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: Christian Gromm <christian.gromm@microchip.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

diff --git a/drivers/staging/most/Documentation/ABI/sysfs-class-most.txt b/drivers/staging/most/Documentation/ABI/sysfs-class-most.txt
new file mode 100644 (file)
index 0000000..380c137
--- /dev/null
+++ b/drivers/staging/most/Documentation/ABI/sysfs-class-most.txt
@@ -0,0 +1,181 @@
+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:

diff --git a/drivers/staging/most/Documentation/driver_usage.txt b/drivers/staging/most/Documentation/driver_usage.txt
new file mode 100644 (file)
index 0000000..a4dc0c3
--- /dev/null
+++ b/drivers/staging/most/Documentation/driver_usage.txt
@@ -0,0 +1,180 @@
+
+               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