diff options
Diffstat (limited to 'drivers/staging/most/Documentation')
-rw-r--r-- | drivers/staging/most/Documentation/ABI/sysfs-class-most.txt | 315 | ||||
-rw-r--r-- | drivers/staging/most/Documentation/driver_usage.txt | 237 |
2 files changed, 552 insertions, 0 deletions
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 000000000..48aa45acc --- /dev/null +++ b/drivers/staging/most/Documentation/ABI/sysfs-class-most.txt @@ -0,0 +1,315 @@ +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 peripheral interface the current device + uses. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + If the network interface controller is attached via USB, a dci + directory is created that allows applications to use the + controller's direct communication interface (DCI) to exchange + information. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/arb_address +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + This is used to set an arbitrary DCI register address an + application wants to read from or write to. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/arb_value +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + This is used to read from or write to the arbitrary DCI register + whose address is stored in arb_address. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/mep_eui48_hi +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + This is used to check and configure the MAC address. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/mep_eui48_lo +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + This is used to check and configure the MAC address. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/mep_eui48_mi +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + This is used to check and configure the MAC address. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/mep_filter +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + This is used to check and configure the MEP filter address. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/mep_hash0 +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + This is used to check and configure the MEP hash table. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/mep_hash1 +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + This is used to check and configure the MEP hash table. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/mep_hash2 +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + This is used to check and configure the MEP hash table. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/mep_hash3 +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + This is used to check and configure the MEP hash table. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/ni_state +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + Indicates the current network interface state. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/node_address +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + Indicates the current node address. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/node_position +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + Indicates the current node position. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/packet_bandwidth +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + Indicates the configured packet bandwidth. +Users: + +What: /sys/class/most/mostcore/devices/<mdev>/dci/sync_ep +Date: June 2016 +KernelVersion: 4.9 +Contact: Christian Gromm <christian.gromm@microchip.com> +Description: + Triggers the controller's synchronization process for a certain + endpoint. +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 index 000000000..2fa8dea1d --- /dev/null +++ b/drivers/staging/most/Documentation/driver_usage.txt @@ -0,0 +1,237 @@ + + 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 MOST driver uses module stacking to divide the associated modules into +three layers. From bottom up these layers are: the adapter layer, the core +layer and the application layer. The core layer implements the MOST +subsystem and consists basically of the module core.c and its API. It +registers the MOST bus with the kernel's device model, handles the data +routing through all three layers, the configuration of the driver, the +representation of the configuration interface in sysfs and the buffer +management. + +For each of the other two layers a set of modules is provided. Those can be +arbitrarily combined with the core to meet the connectivity of the desired +system architecture. + +A module of the adapter layer is basically a device driver for a different +subsystem. It is registered with the core to connect the MOST subsystem to +the attached network interface controller hardware. Hence, a given module +of this layer is designed to handle exactly one of the peripheral +interfaces (e.g. USB, MediaLB, I2C) the hardware provides. + +A module of the application layer is referred to as a core component, +which kind of extends the core by providing connectivity to the user space. +Applications, then, can access a MOST network via character devices, an +ALSA soundcard, a Network adapter or a V4L2 capture device. + +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 Adapter Layer + +The adapter layer contains a pool of device drivers. For each peripheral +interface the hardware supports there is one suitable module that handles +the interface. Adapter drivers encapsulate the peripheral interface +specific knowledge of the MOST driver stack and provide an easy way of +extending the number of supported interfaces. Currently the following +interfaces 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. + +Once an adapter driver recognizes a MOST device being attached, it +registers it with the core, which, in turn, assigns the necessary members +of the embedded struct device (e.g. the bus this device belongs to and +attribute groups) and registers it with the kernel's device model. + + + Section 1.2 Core Layer + +This layer implements the MOST subsystem. It contains the core module and +the header file most.h that exposes the API of the core. When inserted in +the kernel, it registers the MOST bus_type with the kernel's device model +and registers itself as a device driver for this bus. Besides these meta +tasks the core populates the configuration directory for a registered MOST +device (represented by struct most_interface) in sysfs and processes the +configuration of the device's interface. The core layer also handles the +buffer management and the data/message routing. + + + Section 1.3 Application Layer + +This layer contains a pool of device drivers that are components of the +core designed to make up the userspace experience of the MOST driver stack. +Depending on how an application is meant to interface the driver, one or +more modules of this pool can be registered with the core. Currently the +following components are available + + 1) Character Device + Userspace 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 Usage of the MOST Driver + + 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 communication 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 communication + 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 + communication 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) + - "2x24" (24-bit stereo) + - "2x32" (32-bit stereo) + - "6x16" (16-bit surround 5.1) + +The resolution string has to be written to the link directory's comp_params +attribute. + + Section 2.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 '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 = 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 'subbuffer_size' and hardware will always expect two isochronous +packets within one USB transaction. This renders + + MTU_USB - (2 * subbuffer_size) + +bytes for padding. + +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 +fit its constraints, it is recommended to always double check the +configuration and read back the previously written files. |