mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-10-04 16:15:11 +00:00
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>
This commit is contained in:
Christian Gromm
Greg Kroah-Hartman
parent
a4198cdf0c
commit
59cc3399ef
2 changed files with 361 additions and 0 deletions
181
drivers/staging/most/Documentation/ABI/sysfs-class-most.txt
Normal file
181
drivers/staging/most/Documentation/ABI/sysfs-class-most.txt
Normal file
|
|
@ -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:
|
||||
180
drivers/staging/most/Documentation/driver_usage.txt
Normal file
180
drivers/staging/most/Documentation/driver_usage.txt
Normal file
|
|
@ -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
|
||||
Loading…
Reference in a new issue