| Message ID | db0a9206d31c82f8381316ef5ff9872bfb53665b.1589654470.git.vilhelm.gray@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Introduce the Counter character device interface | expand |
On Sat, 16 May 2020 15:20:02 -0400 William Breathitt Gray <vilhelm.gray@gmail.com> wrote: > This patch adds high-level documentation about the Counter subsystem > character device interface. > > Signed-off-by: William Breathitt Gray <vilhelm.gray@gmail.com> > --- > Documentation/driver-api/generic-counter.rst | 112 +++++++++++++------ > 1 file changed, 76 insertions(+), 36 deletions(-) > > 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-ended) and instead focus > on the core idea of what the data and process represent (e.g. position > as interpreted from quadrature encoding data). > > -Userspace Interface > -=================== > - > -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 > ========== > > @@ -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" / > -------------------------------------------------- > > -There are three primary components involved: > +There are four primary components involved: > > 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 > +=============== > + > +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 > +======================== > + > +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. From 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). Jonathan
On Sat 2020-05-16 15:20:02, William Breathitt Gray wrote: > This patch adds high-level documentation about the Counter subsystem > character device interface. > > Signed-off-by: William Breathitt Gray <vilhelm.gray@gmail.com> > --- > Documentation/driver-api/generic-counter.rst | 112 +++++++++++++------ > 1 file changed, 76 insertions(+), 36 deletions(-) > > 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 > + > +Counter chrdev > +-------------- > +Translates counter data to the standard Counter character device; data > +is transferred via standard character device read/write calls. > + > +Sysfs Interface > +=============== > + > +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 > +======================== > + > +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. This looks like very, very strange interface, and not described in detail required to understand it. Could you take a look at input subsystem, /dev/input/event0? Perhaps it is directly usable, and if not something similar should probably be acceptable. Best regards, Pavel
On Fri, May 29, 2020 at 03:26:04PM +0200, Pavel Machek wrote: > On Sat 2020-05-16 15:20:02, William Breathitt Gray wrote: > > This patch adds high-level documentation about the Counter subsystem > > character device interface. > > > > Signed-off-by: William Breathitt Gray <vilhelm.gray@gmail.com> > > --- > > Documentation/driver-api/generic-counter.rst | 112 +++++++++++++------ > > 1 file changed, 76 insertions(+), 36 deletions(-) > > > > 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 > > > + > > +Counter chrdev > > +-------------- > > +Translates counter data to the standard Counter character device; data > > +is transferred via standard character device read/write calls. > > + > > +Sysfs Interface > > +=============== > > + > > +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 > > +======================== > > + > > +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. > > This looks like very, very strange interface, and not described in detail > required to understand it. > > Could you take a look at input subsystem, /dev/input/event0? Perhaps it is > directly usable, and if not something similar should probably be acceptable. > > Best regards, > Pavel Yes, I don't think this is a good interface afterall. I'm implementing a different design for v3 that should be more intuitive. The input subsystem could be useful for streams of events such as timestamps, so I'll take a look at it as well in case something similar to it could be used. William Breathitt Gray
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-ended) and instead focus on the core idea of what the data and process represent (e.g. position as interpreted from quadrature encoding data). -Userspace Interface -=================== - -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 ========== @@ -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" / -------------------------------------------------- -There are three primary components involved: +There are four primary components involved: 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 +=============== + +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 +======================== + +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.
This patch adds high-level documentation about the Counter subsystem character device interface. Signed-off-by: William Breathitt Gray <vilhelm.gray@gmail.com> --- Documentation/driver-api/generic-counter.rst | 112 +++++++++++++------ 1 file changed, 76 insertions(+), 36 deletions(-)