This patch updates the driver documentation files to reflect the
latest changes regarding configfs.
Signed-off-by: Christian Gromm <christian.gr...@microchip.com>
v2:
- changed kernel version to 5.2
v3:
Signed-off-by: Christian Gromm <christian.gr...@microchip.com>
---
.../most/Documentation/ABI/configfs-most.txt | 204 +++++++++++++++++++++
.../staging/most/Documentation/driver_usage.txt | 131 +++++++------
2 files changed, 284 insertions(+), 51 deletions(-)
create mode 100644 drivers/staging/most/Documentation/ABI/configfs-most.txt
diff --git a/drivers/staging/most/Documentation/ABI/configfs-most.txt
b/drivers/staging/most/Documentation/ABI/configfs-most.txt
new file mode 100644
index 0000000..25b3e18
--- /dev/null
+++ b/drivers/staging/most/Documentation/ABI/configfs-most.txt
@@ -0,0 +1,204 @@
+What: /sys/kernel/config/most_<component>
+Date: March 8, 2019
+KernelVersion: 5.2
+Description: Interface is used to configure and connect device channels
+ to component drivers.
+
+ Attributes are visible only when configfs is mounted. To mount
+ configfs in /sys/kernel/config directory use:
+ # mount -t configfs none /sys/kernel/config/
+
+
+What: /sys/kernel/config/most_cdev/<link>
+Date: March 8, 2019
+KernelVersion: 5.2
+Description:
+ The attributes:
+
+ buffer_size configure the buffer size for this channel
+
+ subbuffer_size configure the sub-buffer size for this channel
+ (needed for synchronous and isochrnous data)
+
+
+ num_buffers configure number of buffers used for this
+ channel
+
+ datatype configure type of data that will travel over
+ this channel
+
+ direction configure whether this link will be an input
+ or output
+
+ dbr_size configure DBR data buffer size (this is used
+ for MediaLB communiction only)
+
+ packets_per_xact
+ configure the number of packets that will be
+ collected from the network before being
+ transmitted via USB (this is used for USB
+ communiction only)
+
+ device name of the device the link is to be attached to
+
+ channel name of the channel the link is to be attached
to
+
+ comp_params pass parameters needed by some components
+
+ create_link write '1' to this attribute to trigger the
+ creation of the link. In case of speculative
+ configuration, the creation is post-poned until
+ a physical device is being attached to the bus.
+
+ destroy_link write '1' to this attribute to destroy an
+ active link
+
+What: /sys/kernel/config/most_video/<link>
+Date: March 8, 2019
+KernelVersion: 5.2
+Description:
+ The attributes:
+
+ buffer_size configure the buffer size for this channel
+
+ subbuffer_size configure the sub-buffer size for this channel
+ (needed for synchronous and isochrnous data)
+
+
+ num_buffers configure number of buffers used for this
+ channel
+
+ datatype configure type of data that will travel over
+ this channel
+
+ direction configure whether this link will be an input
+ or output
+
+ dbr_size configure DBR data buffer size (this is used
+ for MediaLB communiction only)
+
+ packets_per_xact
+ configure the number of packets that will be
+ collected from the network before being
+ transmitted via USB (this is used for USB
+ communiction only)
+
+ device name of the device the link is to be attached to
+
+ channel name of the channel the link is to be attached
to
+
+ comp_params pass parameters needed by some components
+
+ create_link write '1' to this attribute to trigger the
+ creation of the link. In case of speculative
+ configuration, the creation is post-poned until
+ a physical device is being attached to the bus.
+
+ destroy_link write '1' to this attribute to destroy an
+ active link
+
+What: /sys/kernel/config/most_net/<link>
+Date: March 8, 2019
+KernelVersion: 5.2
+Description:
+ The attributes:
+
+ buffer_size configure the buffer size for this channel
+
+ subbuffer_size configure the sub-buffer size for this channel
+ (needed for synchronous and isochrnous data)
+
+
+ num_buffers configure number of buffers used for this
+ channel
+
+ datatype configure type of data that will travel over
+ this channel
+
+ direction configure whether this link will be an input
+ or output
+
+ dbr_size configure DBR data buffer size (this is used
+ for MediaLB communiction only)
+
+ packets_per_xact
+ configure the number of packets that will be
+ collected from the network before being
+ transmitted via USB (this is used for USB
+ communiction only)
+
+ device name of the device the link is to be attached to
+
+ channel name of the channel the link is to be attached
to
+
+ comp_params pass parameters needed by some components
+
+ create_link write '1' to this attribute to trigger the
+ creation of the link. In case of speculative
+ configuration, the creation is post-poned until
+ a physical device is being attached to the bus.
+
+ destroy_link write '1' to this attribute to destroy an
+ active link
+
+What: /sys/kernel/config/most_sound/<card>
+Date: March 8, 2019
+KernelVersion: 5.2
+Description:
+ The attributes:
+
+ create_card write '1' to this attribute to trigger the
+ registration of the sound card with the ALSA
+ subsystem.
+
+What: /sys/kernel/config/most_sound/<card>/<link>
+Date: March 8, 2019
+KernelVersion: 5.2
+Description:
+ The attributes:
+
+ buffer_size configure the buffer size for this channel
+
+ subbuffer_size configure the sub-buffer size for this channel
+ (needed for synchronous and isochrnous data)
+
+
+ num_buffers configure number of buffers used for this
+ channel
+
+ datatype configure type of data that will travel over
+ this channel
+
+ direction configure whether this link will be an input
+ or output
+
+ dbr_size configure DBR data buffer size (this is used
+ for MediaLB communiction only)
+
+ packets_per_xact
+ configure the number of packets that will be
+ collected from the network before being
+ transmitted via USB (this is used for USB
+ communiction only)
+
+ device name of the device the link is to be attached to
+
+ channel name of the channel the link is to be attached
to
+
+ comp_params pass parameters needed by some components
+
+ create_link write '1' to this attribute to trigger the
+ creation of the link. In case of speculative
+ configuration, the creation is post-poned until
+ a physical device is being attached to the bus.
+
+ destroy_link write '1' to this attribute to destroy an
+ active link
+
+What:
/sys/kernel/config/rdma_cm/<hca>/ports/<port-num>/default_roce_tos
+Date: March 8, 2019
+KernelVersion: 5.2
+Description: RDMA-CM QPs from HCA <hca> at port <port-num>
+ will be created with this TOS as default.
+ This can be overridden by using the rdma_set_option API.
+ The possible RoCE TOS values are 0-255.
diff --git a/drivers/staging/most/Documentation/driver_usage.txt
b/drivers/staging/most/Documentation/driver_usage.txt
index da7a8f4..56d7919 100644
--- a/drivers/staging/most/Documentation/driver_usage.txt
+++ b/drivers/staging/most/Documentation/driver_usage.txt
@@ -115,36 +115,75 @@ following components are available
Section 2 Usage of the MOST Driver
- Section 2.1 Configuration
-
-See ABI/sysfs-bus-most.txt
-
-
- Section 2.2 Routing Channels
-
-To connect a configured channel to a certain core component and make it
-accessible for user space applications, the driver attribute 'add_link' is
-used. The configuration string passed to it has the following format:
-
- "device_name:channel_name:component_name:link_name[.param]"
-
-It is the concatenation of up to four substrings separated by a colon. The
-substrings contain the names of the MOST interface, the channel, the
-component driver and a custom name with which the link is going to be
-referenced with. Since some components need additional information, the
-link name can be extended with a component-specific parameter (separated by
-a dot). In case the character device component is loaded, the handle would
-also appear as a device node in the /dev directory.
-
-Cdev component example:
- $ echo "mdev0:ep_81:cdev:my_rx_channel" >$(DRV_DIR)/add_link
-
-
-Sound component example:
-
-The sound component needs additional parameters to determine the audio
-resolution that is going to be used and to trigger the registration of a
-sound card with ALSA. The following audio formats are available:
+ Section 2.1 Configuration and Data Link
+
+The driver is to be configured via configfs. Each loaded component kernel
+object (see section 1.3) registers a subsystem with configfs, which is used to
+configure and establish communiction pathways (links) to attached devices on
+the bus. To do so, the user has to descend into the component's configuration
+directory and create a new directory (child config itmes). The name of this
+directory will be used as a reference for the link and it will contain the
+following attributes:
+
+ - buffer_size
+ configure the buffer size for this channel
+ - subbuffer_size
+ configure the sub-buffer size for this channel (needed for
+ synchronous and isochrnous data)
+ - num_buffers
+ configure number of buffers used for this channel
+ - datatype
+ configure type of data that will travel over this channel
+ - direction
+ configure whether this link will be an input or output
+ - dbr_size
+ configure DBR data buffer size (this is used for MediaLB communiction
+ only)
+ - packets_per_xact
+ configure the number of packets that will be collected from the
+ network before being transmitted via USB (this is used for USB
+ communiction only)
+ - device
+ name of the device the link is to be attached to
+ - channel
+ name of the channel the link is to be attached to
+ - comp_params
+ pass parameters needed by some components
+ - create_link
+ write '1' to this attribute to trigger the creation of the link. In
+ case of speculative configuration, the creation is post-poned until
+ a physical device is being attached to the bus.
+ - destroy_link
+ write '1' to this attribute to destroy an already established link
+
+
+See ABI/sysfs-bus-most.txt and ABI/configfs-most.txt
+
+
+ Section 2.2 Configure a Sound Card
+
+Setting up synchronous channels to be mapped as an ALSA sound adapter is a two
+step process. Firstly, a directory (child config group) has to be created
+inside the most_sound's configuration directory. This adapter dir will
+represent the sound adapter. The name of the directory is for user reference
+only and has no further influence, as all sound adapters will be given a static
+name in ALSA. The sound adapter will have the following attribute:
+
+ - create_card
+ write '1' to this attribute to trigger the registration of the card
+ with the ALSA subsystem.
+ In case of speculative configuration, the creation is post-poned
+ until a physical device is being attached to the bus.
+
+Secondly, links will have to be created inside the adapter dir as described in
+section 2.1. These links will become the PCM devices of the sound card. The
+name of a PCM device will be inherited from the directory name. When all
+channels have been configured and created, the sound card itself can be created
+by writing '1' to the create_card attribute.
+
+The sound component needs an additional parameter to determine the audio
+resolution that is going to be used.
+The following audio formats are available:
- "1x8" (Mono)
- "2x16" (16-bit stereo)
@@ -152,18 +191,8 @@ sound card with ALSA. The following audio formats are
available:
- "2x32" (32-bit stereo)
- "6x16" (16-bit surround 5.1)
-To make the sound module create a sound card and register it with ALSA the
-string "create" needs to be attached to the module parameter section of the
-configuration string. To create a sound card with with two playback devices
-(linked to channel ep01 and ep02) and one capture device (linked to channel
-ep83) the following is written to the add_link file:
-
- $ echo "mdev0:ep01:sound:most51_playback.6x16" >$(DRV_DIR)/add_link
- $ echo "mdev0:ep02:sound:most_playback.2x16" >$(DRV_DIR)/add_link
- $ echo "mdev0:ep83:sound:most_capture.2x16.create" >$(DRV_DIR)/add_link
-
-The link names (most51_playback, most_playback and most_capture) will
-become the names of the PCM devices of the sound card.
+The resolution string has to be written to the link directory's comp_params
+attribute.
Section 2.3 USB Padding
@@ -174,13 +203,13 @@ hardware, which is for performance optimization purposes
of the USB
transmission.
When transmitting synchronous data the allocated channel width needs to be
-written to 'set_subbuffer_size'. Additionally, the number of MOST frames
-that should travel to the host within one USB transaction need to be
-written to 'packets_per_xact'.
+written to 'subbuffer_size'. Additionally, the number of MOST frames that
+should travel to the host within one USB transaction need to be written to
+'packets_per_xact'.
The driver, then, calculates the synchronous threshold as follows:
- frame_size = set_subbuffer_size * packets_per_xact
+ frame_size = subbuffer_size * packets_per_xact
In case 'packets_per_xact' is set to 0xFF the maximum number of packets,
allocated within one MOST frame, is calculated that fit into _one_ 512 byte
@@ -192,15 +221,15 @@ This frame_size is the number of synchronous data within
an USB
transaction, which renders MTU_USB - frame_size bytes for padding.
When transmitting isochronous AVP data the desired packet size needs to be
-written to 'set_subbuffer_size' and hardware will always expect two
-isochronous packets within one USB transaction. This renders
+written to 'subbuffer_size' and hardware will always expect two isochronous
+packets within one USB transaction. This renders
- MTU_USB - (2 * set_subbuffer_size)
+ MTU_USB - (2 * subbuffer_size)
bytes for padding.
-Note that at least (2 * set_subbuffer_size) bytes for isochronous data or
-(set_subbuffer_size * packts_per_xact) bytes for synchronous data need to
+Note that at least (2 * subbuffer_size) bytes for isochronous data or
+(subbuffer_size * packts_per_xact) bytes for synchronous data need to
be put in the transmission buffer and passed to the driver.
Since adapter drivers are allowed to change a chosen configuration to best
--
2.7.4
_______________________________________________
devel mailing list
de...@linuxdriverproject.org
http://driverdev.linuxdriverproject.org/mailman/listinfo/driverdev-devel
