mirrors/linux-stable
1
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git synced 2024-10-04 16:15:11 +00:00
Code Issues Releases Wiki Activity

staging: most: Documentation: update driver documentation

Browse source 
This patch updates the driver documentation files to reflect the
latest changes regarding configfs.

Signed-off-by: Christian Gromm <christian.gromm@microchip.com>
v2:
	- changed kernel version to 5.2
v3:
v4:

Signed-off-by: Christian Gromm <christian.gromm@microchip.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Christian Gromm 2019-04-03 15:19:55 +02:00 committed by Greg Kroah-Hartman
parent 1a89eb0a8f
commit deaf3b7155
2 changed files with 278 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

204
drivers/staging/most/Documentation/ABI/configfs-most.txt Normal file
View file

@ -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.

119
drivers/staging/most/Documentation/driver_usage.txt
View file

@ -115,36 +115,75 @@ following components are available
Section 2 Usage of the MOST Driver
Section 2.1 Configuration
Section 2.1 Configuration and Data Link
See ABI/sysfs-bus-most.txt
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
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
See ABI/sysfs-bus-most.txt and ABI/configfs-most.txt
Sound component example:
Section 2.2 Configure a Sound Card
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:
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