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@xxxxxxxxxxxxx> --- .../most/Documentation/ABI/sysfs-class-most.txt | 181 ++++++++++++++++++++ .../staging/most/Documentation/driver_usage.txt | 180 +++++++++++++++++++ 2 files changed, 361 insertions(+) create mode 100644 drivers/staging/most/Documentation/ABI/sysfs-class-most.txt create mode 100644 drivers/staging/most/Documentation/driver_usage.txt 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 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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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@xxxxxxxxxxxxx> +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 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 -- 1.7.9.5 _______________________________________________ devel mailing list devel@xxxxxxxxxxxxxxxxxxxxxx http://driverdev.linuxdriverproject.org/mailman/listinfo/driverdev-devel
