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

Staging: most: add MOST driver's documentation 



This patch adds the documentation to the MOST driver that describes its ABI
interface and the basic usage.

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

drivers/staging/most/Documentation/ABI/sysfs-class-most.txt

0 → 100644
+181 −0
Original line number Diff line number Diff line 
What:		/sys/class/most/mostcore/aims

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		List of AIMs that have been loaded.

Users:



What:		/sys/class/most/mostcore/aims/<aim>/add_link

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		This is used to establish a connection of a channel and the

		current AIM.

Users:



What:		/sys/class/most/mostcore/aims/<aim>/remove_link

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		This is used to remove a connected channel from the

		current AIM.

Users:



What:		/sys/class/most/mostcore/devices

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		List of attached MOST interfaces.

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/description

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		Provides information about the interface type and the physical

		location of the device. Hardware attached via USB, for instance,

		might return <usb_device 1-1.1:1.0>

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/interface

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		Indicates the type of peripherial interface the current device

		uses.

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/<channel>/

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		For every channel of the device a directory is created, whose

		name is dictated by the HDM. This enables an application to

		collect information about the channel's capabilities and

		configure it.

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/<channel>/available_datatypes

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		Indicates the data types the current channel can transport.

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/<channel>/available_directions

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		Indicates the directions the current channel is capable of.

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/<channel>/number_of_packet_buffers

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		Indicates the number of packet buffers the current channel can

		handle.

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/<channel>/number_of_stream_buffers

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		Indicates the number of streaming buffers the current channel can

		handle.

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/<channel>/size_of_packet_buffer

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		Indicates the size of a packet buffer the current channel can

		handle.

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/<channel>/size_of_stream_buffer

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		Indicates the size of a streaming buffer the current channel can

		handle.

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/<channel>/set_number_of_buffers

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		This is to configure the number of buffers of the current channel.

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/<channel>/set_buffer_size

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		This is to configure the size of a buffer of the current channel.

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/<channel>/set_direction

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		This is to configure the direction of the current channel.

		The following strings will be accepted:

			'dir_tx',

			'dir_rx'

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/<channel>/set_datatype

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		This is to configure the data type of the current channel.

		The following strings will be accepted:

			'control',

			'async',

			'sync',

			'isoc_avp'

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/<channel>/set_subbuffer_size

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		This is to configure the subbuffer size of the current channel.

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/<channel>/set_packets_per_xact

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		This is to configure the number of packets per transaction of

		the current channel. This is only needed network interface

		controller is attached via USB.

Users:



What:		/sys/class/most/mostcore/devices/<mdev>/<channel>/channel_starving

Date:		June 2015

KernelVersion:	4.3

Contact:	Christian Gromm <christian.gromm@microchip.com>

Description:

		Indicates whether current channel ran out of buffers.

Users:

drivers/staging/most/Documentation/driver_usage.txt

0 → 100644
+180 −0
Original line number Diff line number Diff line 


		Section 1 Overview



The Media Oriented Systems Transport (MOST) driver gives Linux applications

access a MOST network: The Automotive Information Backbone and the de-facto

standard for high-bandwidth automotive multimedia networking.



MOST defines the protocol, hardware and software layers necessary to allow

for the efficient and low-cost transport of control, real-time and packet

data using a single medium (physical layer). Media currently in use are

fiber optics, unshielded twisted pair cables (UTP) and coax cables. MOST

also supports various speed grades up to 150 Mbps.

For more information on MOST, visit the MOST Cooperation website:

www.mostcooperation.com.



Cars continue to evolve into sophisticated consumer electronics platforms,

increasing the demand for reliable and simple solutions to support audio,

video and data communications. MOST can be used to connect multiple

consumer devices via optical or electrical physical layers directly to one

another or in a network configuration. As a synchronous network, MOST

provides excellent Quality of Service and seamless connectivity for

audio/video streaming. Therefore, the driver perfectly fits to the mission

of Automotive Grade Linux to create open source software solutions for

automotive applications.



The driver consists basically of three layers. The hardware layer, the

core layer and the application layer. The core layer consists of the core

module only. This module handles the communication flow through all three

layers, the configuration of the driver, the configuration interface

representation in sysfs, and the buffer management.

For each of the other two layers a selection of modules is provided. These

modules can arbitrarily be combined to meet the needs of the desired

system architecture. A module of the hardware layer is referred to as an

HDM (hardware dependent module). Each module of this layer handles exactly

one of the peripheral interfaces of a network interface controller (e.g.

USB, MediaLB, I2C). A module of the application layer is referred to as an

AIM (application interfacing module). The modules of this layer give access

to MOST via one the following ways: character devices, ALSA, Networking or

V4L2.



To physically access MOST, an Intelligent Network Interface Controller

(INIC) is needed. For more information on available controllers visit:

www.microchip.com







		Section 1.1 Hardware Layer



The hardware layer contains so called hardware dependent modules (HDM). For each

peripheral interface the hardware supports the driver has a suitable module

that handles the interface.



The HDMs encapsulate the peripheral interface specific knowledge of the driver

and provides an easy way of extending the number of supported interfaces.

Currently the following HDMs are available:



	1) MediaLB (DIM2)

	   Host wants to communicate with hardware via MediaLB.



	2) I2C

	   Host wants to communicate with the hardware via I2C.



	3) USB

	   Host wants to communicate with the hardware via USB.





		Section 1.2 Core Layer



The core layer contains the mostcore module only, which processes the driver

configuration via sysfs, buffer management and data forwarding.







		Section 1.2 Application Layer



The application layer contains so called application interfacing modules (AIM).

Depending on how the driver should interface to the application, one or more

suitable modules can be selected.



The AIMs encapsulate the application interface specific knowledge of the driver

and provides access to user space or other kernel subsystems.

Currently the following AIMs are available



	1) Character Device

	   Applications can access the driver by means of character devices.



	2) Networking

	   Standard networking applications (e.g. iperf) can by used to access

	   the driver via the networking subsystem.



	3) Video4Linux (v4l2)

	   Standard video applications (e.g. VLC) can by used to access the

	   driver via the V4L subsystem.



	4) Advanced Linux Sound Architecture (ALSA)

	   Standard sound applications (e.g. aplay, arecord, audacity) can by

	   used to access the driver via the ALSA subsystem.







		Section 2 Configuration



See ABI/sysfs-class-most.txt







		Section 3 USB Padding



When transceiving synchronous or isochronous data, the number of packets per USB

transaction and the sub-buffer size need to be configured. These values

are needed for the driver to process buffer padding, as expected by 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'.



Internally the synchronous threshold is calculated as follows:



	frame_size = set_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

USB full packet.



	frame_size = floor(MTU_USB / bandwidth_sync) * bandwidth_sync



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



	MTU_USB - (2 * set_subbuffer_size)



bytes for padding.



Note that at least 2 times set_subbuffer_size bytes for isochronous data or

set_subbuffer_size times packts_per_xact bytes for synchronous data need to be

put in the transmission buffer and passed to the driver.



Since HDMs are allowed to change a chosen configuration to best fit its

constraints, it is recommended to always double check the configuration and read

back the previously written files.







		Section 4 Routing Channels



To connect a channel that has been configured as outlined above to an AIM and

make it accessible to user space applications, the attribute file 'add_link' is

used. To actually bind a channel to the AIM a string needs to be written to the

file that complies with the following syntax:



	"most_device:channel_name:link_name[.param]"



The example above links the channel "channel_name" of the device "most_device"

to the AIM. In case the AIM interfaces the VFS this would also create a device

node "link_name" in the /dev directory. The parameter "param" is an AIM dependent

string, which can be omitted in case the used AIM does not make any use of it.



Cdev AIM example:

        $ echo "mdev0:ep_81:my_rx_channel" >add_link

        $ echo "mdev0:ep_81" >add_link





Sound/ALSA AIM example:



The sound/ALSA AIM needs an additional parameter to determine the audio resolution

that is going to be used. The following strings can be used:



	- "1x8" (Mono)

	- "2x16" (16-bit stereo)

	- "2x24" (24-bit stereo)

	- "2x32" (32-bit stereo)



        $ echo "mdev0:ep_81:audio_rx.2x16" >add_link

        $ echo "mdev0:ep_81" >add_link