Received: by 2002:a25:2c96:0:0:0:0:0 with SMTP id s144csp421096ybs; Sun, 24 May 2020 09:21:48 -0700 (PDT) X-Google-Smtp-Source: ABdhPJwa9pN0E+HqhAYXnVtjhpE3N6tYs1nABOHv59ib3JLpdD+lAT1v+iD8PeIPawiOgL5kVMtd X-Received: by 2002:a05:6402:3044:: with SMTP id bu4mr11960824edb.342.1590337308168; Sun, 24 May 2020 09:21:48 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1590337308; cv=none; d=google.com; s=arc-20160816; b=wMOz2z8f5owzCpLZ27lQv2CCQo9Lo3qPfHeMuBQ90c1Sah13HZMPoAGwqeeaSAuELh crZQJGgrDn829iRrYuk1qJUH8naE6w4x/83V4VMGLxexjUtCRb9Pai89MkYPUkeESAMv L4YeMDLU7Hgfwc/c6uNCSnsGEkOR7DrAVUivjyTaQah/ajLhvrWzaU6m0w1NLplq73vN eY+AbtCsLUJwnsH6b70RYrUlTtejYrDScVUJvDXKnh4jMJXlE2J39VoYi+encWx34a3R b4FgiQyMNgoc/oFrzgRuNz6Os5j8Ytyfr1VR7Wxf8pkIo5KekTsu8p93hMWC7UMzPpzu qULg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:subject:cc:to:from:date :dkim-signature; bh=KTrdccoBokj+lV8xqj46cu4s5wrITJHKfDTlh1Otg9E=; b=Kx+v2SFG6ARmqYYKQcF4iX9jJlVL4c1TGtLGehrdR2suqlgubUv6s3HlpZMzkixuOX YsEouucUwnmJal5Twi55D+1uKI9mb4dUHQJNkg/mxmAEQuLAts5wVQ037GptZtoYKw8i EyZWDxYq9KQGhsryI+UVfEH+Re4tcf3Ou46cCv9l0M+fWFjYn78t8/WImxbVvCweWBhD jl/JsHe5ic6tIR+O4PGhLoexvGb8uEfxt7QMzH9xWBjWRM5Bc51kyqn3hsd2LHTVFTt0 9V9RA2SzRBie5hCiekegYk/FyuLqAJJKvUSYrgv00dMvwzQlxQQrkPg64Asz92rzqC/2 9uyA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@kernel.org header.s=default header.b=JvUcpJFK; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [23.128.96.18]) by mx.google.com with ESMTP id h22si7607505ejx.328.2020.05.24.09.21.25; Sun, 24 May 2020 09:21:48 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18; Authentication-Results: mx.google.com; dkim=pass header.i=@kernel.org header.s=default header.b=JvUcpJFK; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728748AbgEXQTS (ORCPT + 99 others); Sun, 24 May 2020 12:19:18 -0400 Received: from mail.kernel.org ([198.145.29.99]:54764 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727899AbgEXQTS (ORCPT ); Sun, 24 May 2020 12:19:18 -0400 Received: from archlinux (cpc149474-cmbg20-2-0-cust94.5-4.cable.virginm.net [82.4.196.95]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 8F85520776; Sun, 24 May 2020 16:19:14 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1590337157; bh=byWAOearMKEuXBmgx0LII0i67ProJOMxHQL8RV5rP/A=; h=Date:From:To:Cc:Subject:In-Reply-To:References:From; b=JvUcpJFKHz88LiH5SCQSet+ZpwD2HegE8hERUtZ/olPDY74CuXEAxm0uWSSUFPE9f 7rQfrCtiDIrL/HdOJ2/joFHqfIEL3PkyfhvV34SKRSyVjGM8h5e+lJXZ/XlckA6c2q 3l2j8O7BExBSwe5kdDzekrxQ3CMOY3SAuJkRMDSs= Date: Sun, 24 May 2020 17:19:11 +0100 From: Jonathan Cameron To: William Breathitt Gray Cc: kamel.bouhara@bootlin.com, gwendal@chromium.org, alexandre.belloni@bootlin.com, david@lechnology.com, linux-iio@vger.kernel.org, linux-kernel@vger.kernel.org, linux-stm32@st-md-mailman.stormreply.com, linux-arm-kernel@lists.infradead.org, syednwaris@gmail.com, patrick.havelange@essensium.com, fabrice.gasnier@st.com, mcoquelin.stm32@gmail.com, alexandre.torgue@st.com Subject: Re: [PATCH v2 4/4] docs: counter: Document character device interface Message-ID: <20200524171911.229e34f1@archlinux> In-Reply-To: References: X-Mailer: Claws Mail 3.17.5 (GTK+ 2.24.32; x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Sat, 16 May 2020 15:20:02 -0400 William Breathitt Gray wrote: > This patch adds high-level documentation about the Counter subsystem > character device interface. >=20 > Signed-off-by: William Breathitt Gray > --- > Documentation/driver-api/generic-counter.rst | 112 +++++++++++++------ > 1 file changed, 76 insertions(+), 36 deletions(-) >=20 > diff --git a/Documentation/driver-api/generic-counter.rst b/Documentation= /driver-api/generic-counter.rst > index 8f85c30dea0b..58045b33b576 100644 > --- a/Documentation/driver-api/generic-counter.rst > +++ b/Documentation/driver-api/generic-counter.rst > @@ -223,19 +223,6 @@ whether an input line is differential or single-ende= d) and instead focus > on the core idea of what the data and process represent (e.g. position > as interpreted from quadrature encoding data). > =20 > -Userspace Interface > -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > - > -Several sysfs attributes are generated by the Generic Counter interface, > -and reside under the /sys/bus/counter/devices/counterX directory, where > -counterX refers to the respective counter device. Please see > -Documentation/ABI/testing/sysfs-bus-counter for detailed > -information on each Generic Counter interface sysfs attribute. > - > -Through these sysfs attributes, programs and scripts may interact with > -the Generic Counter paradigm Counts, Signals, and Synapses of respective > -counter devices. > - > Driver API > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > =20 > @@ -377,13 +364,13 @@ driver can be exemplified by the following:: > +----------------------------+ | > | Processes data from device | ------------------- > |----------------------------| / driver callbacks / > - | Type: unsigned long | ------------------- > + | Type: u64 | ------------------- > | Value: 42 | | > +----------------------------+ | > | | > - ---------------- | > - / unsigned long / | > - ---------------- | > + ---------- | > + / u64 / | > + ---------- | > | | > | V > | +----------------------+ > @@ -398,25 +385,32 @@ driver can be exemplified by the following:: > | / driver callbacks / > | ------------------- > | | > - +-------+ | > + +-------+---------------+ | > + | | | > + | +-------|-------+ > + | | | > + V | V > + +--------------------+ | +---------------------+ > + | Counter sysfs |<-+->| Counter chrdev | > + +--------------------+ +---------------------+ > + | Translates to the | | Translates to the | > + | standard Counter | | standard Counter | > + | sysfs output | | character device | > + |--------------------| |---------------------+ > + | Type: const char * | | Type: u64 | > + | Value: "42" | | Value: 42 | > + +--------------------+ +---------------------+ > | | > - | +---------------+ > - | | > - V | > - +--------------------+ | > - | Counter sysfs |<-+ > - +--------------------+ > - | Translates to the | > - | standard Counter | > - | sysfs output | > - |--------------------| > - | Type: const char * | > - | Value: "42" | > - +--------------------+ > - | > - --------------- > - / const char * / > - --------------- > + --------------- ---------- > + / const char * / / u64 / > + --------------- ---------- > + | | > + | V > + | +-----------+ > + | | read | > + | +-----------+ > + | \ Count: 42 / > + | ----------- > | > V > +--------------------------------------------------+ > @@ -425,7 +419,7 @@ driver can be exemplified by the following:: > \ Count: "42" / > -------------------------------------------------- > =20 > -There are three primary components involved: > +There are four primary components involved: > =20 > Counter device driver > --------------------- > @@ -445,3 +439,49 @@ and vice versa. > Please refer to the `Documentation/ABI/testing/sysfs-bus-counter` file > for a detailed breakdown of the available Generic Counter interface > sysfs attributes. > + > +Counter chrdev > +-------------- > +Translates counter data to the standard Counter character device; data > +is transferred via standard character device read/write calls. > + > +Sysfs Interface > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +Several sysfs attributes are generated by the Generic Counter interface, > +and reside under the `/sys/bus/counter/devices/counterX` directory, > +where `X` is to the respective counter device id. Please see > +Documentation/ABI/testing/sysfs-bus-counter for detailed information on > +each Generic Counter interface sysfs attribute. > + > +Through these sysfs attributes, programs and scripts may interact with > +the Generic Counter paradigm Counts, Signals, and Synapses of respective > +counter devices. > + > +Counter Character Device > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +Counter character device nodes are created under the `/dev` directory as > +`counterX`, where `X` is the respective counter device id. Defines for > +the standard Counter data types are exposed via the userspace > +`include/uapi/linux/counter-types.h` file. > + > +The first 196095 bytes of the character device serve as a control > +selection area where control exposure of desired Counter components and > +extensions may be selected. Each byte serves as a boolean selection > +indicator for a respective Counter component or extension. The format of > +this area is as follows: > + > +* For each device extension, a byte is required. > +* For each Signal, a byte is reserved for the Signal component, and a > + byte is reserved for each Signal extension. > +* For each Count, a byte is reserved for the Count component, a byte is > + reserved for the count function, a byte is reserved for each Synapse > + action, and byte is reserved for each Count extension. > + > +The selected Counter components and extensions may then be interfaced > +after the first 196095 bytes via standard character device read/write > +operations. The number of bytes available for each component or > +extension is dependent on their respective data type: u8 will have 1 > +byte available, u64 will have 8 bytes available, strings will have 64 > +bytes available, etc. =46rom what I recall of the earlier conversation, I'm not sure this is what was being suggested. I 'think' what people were after was a simple read interface for just the counters (+ timestamps). This would also include the option to use select / poll on the counter. Simply moving over to a read / write really doesn't help for ease of use. I'm not sure what the right control approach is, or perhaps if we even need one (could just output all counts provided by hardware once the chrdev is opened).=20 Jonathan