Commit deaf3b71 authored by Christian Gromm's avatar Christian Gromm Committed by Greg Kroah-Hartman
Browse files

staging: most: Documentation: update driver documentation 



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

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

Signed-off-by: default avatarChristian Gromm <christian.gromm@microchip.com>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 1a89eb0a

drivers/staging/most/Documentation/ABI/configfs-most.txt

0 → 100644
+204 −0
Original line number Diff line number Diff line 
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.

drivers/staging/most/Documentation/driver_usage.txt

+80 −51
Original line number Diff line number Diff line
@@ -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

CRA Git | Maintained and supported by SUSTech CRA and CCSE