kernel/drivers/staging/most/Documentation/driver_usage.txt

   1
   2                 Section 1 Overview
   3
   4 The Media Oriented Systems Transport (MOST) driver gives Linux applications
   5 access a MOST network: The Automotive Information Backbone and the de-facto
   6 standard for high-bandwidth automotive multimedia networking.
   7
   8 MOST defines the protocol, hardware and software layers necessary to allow
   9 for the efficient and low-cost transport of control, real-time and packet
  10 data using a single medium (physical layer). Media currently in use are
  11 fiber optics, unshielded twisted pair cables (UTP) and coax cables. MOST
  12 also supports various speed grades up to 150 Mbps.
  13 For more information on MOST, visit the MOST Cooperation website:
  14 www.mostcooperation.com.
  15
  16 Cars continue to evolve into sophisticated consumer electronics platforms,
  17 increasing the demand for reliable and simple solutions to support audio,
  18 video and data communications. MOST can be used to connect multiple
  19 consumer devices via optical or electrical physical layers directly to one
  20 another or in a network configuration. As a synchronous network, MOST
  21 provides excellent Quality of Service and seamless connectivity for
  22 audio/video streaming. Therefore, the driver perfectly fits to the mission
  23 of Automotive Grade Linux to create open source software solutions for
  24 automotive applications.
  25
  26 The driver consists basically of three layers. The hardware layer, the
  27 core layer and the application layer. The core layer consists of the core
  28 module only. This module handles the communication flow through all three
  29 layers, the configuration of the driver, the configuration interface
  30 representation in sysfs, and the buffer management.
  31 For each of the other two layers a selection of modules is provided. These
  32 modules can arbitrarily be combined to meet the needs of the desired
  33 system architecture. A module of the hardware layer is referred to as an
  34 HDM (hardware dependent module). Each module of this layer handles exactly
  35 one of the peripheral interfaces of a network interface controller (e.g.
  36 USB, MediaLB, I2C). A module of the application layer is referred to as an
  37 AIM (application interfacing module). The modules of this layer give access
  38 to MOST via one the following ways: character devices, ALSA, Networking or
  39 V4L2.
  40
  41 To physically access MOST, an Intelligent Network Interface Controller
  42 (INIC) is needed. For more information on available controllers visit:
  43 www.microchip.com
  44
  45
  46
  47                 Section 1.1 Hardware Layer
  48
  49 The hardware layer contains so called hardware dependent modules (HDM). For each
  50 peripheral interface the hardware supports the driver has a suitable module
  51 that handles the interface.
  52
  53 The HDMs encapsulate the peripheral interface specific knowledge of the driver
  54 and provides an easy way of extending the number of supported interfaces.
  55 Currently the following HDMs are available:
  56
  57         1) MediaLB (DIM2)
  58            Host wants to communicate with hardware via MediaLB.
  59
  60         2) I2C
  61            Host wants to communicate with the hardware via I2C.
  62
  63         3) USB
  64            Host wants to communicate with the hardware via USB.
  65
  66
  67                 Section 1.2 Core Layer
  68
  69 The core layer contains the mostcore module only, which processes the driver
  70 configuration via sysfs, buffer management and data forwarding.
  71
  72
  73
  74                 Section 1.2 Application Layer
  75
  76 The application layer contains so called application interfacing modules (AIM).
  77 Depending on how the driver should interface to the application, one or more
  78 suitable modules can be selected.
  79
  80 The AIMs encapsulate the application interface specific knowledge of the driver
  81 and provides access to user space or other kernel subsystems.
  82 Currently the following AIMs are available
  83
  84         1) Character Device
  85            Applications can access the driver by means of character devices.
  86
  87         2) Networking
  88            Standard networking applications (e.g. iperf) can by used to access
  89            the driver via the networking subsystem.
  90
  91         3) Video4Linux (v4l2)
  92            Standard video applications (e.g. VLC) can by used to access the
  93            driver via the V4L subsystem.
  94
  95         4) Advanced Linux Sound Architecture (ALSA)
  96            Standard sound applications (e.g. aplay, arecord, audacity) can by
  97            used to access the driver via the ALSA subsystem.
  98
  99
 100
 101                 Section 2 Configuration
 102
 103 See ABI/sysfs-class-most.txt
 104
 105
 106
 107                 Section 3 USB Padding
 108
 109 When transceiving synchronous or isochronous data, the number of packets per USB
 110 transaction and the sub-buffer size need to be configured. These values
 111 are needed for the driver to process buffer padding, as expected by hardware,
 112 which is for performance optimization purposes of the USB transmission.
 113
 114 When transmitting synchronous data the allocated channel width needs to be
 115 written to 'set_subbuffer_size'. Additionally, the number of MOST frames that
 116 should travel to the host within one USB transaction need to be written to
 117 'packets_per_xact'.
 118
 119 Internally the synchronous threshold is calculated as follows:
 120
 121         frame_size = set_subbuffer_size * packets_per_xact
 122
 123 In case 'packets_per_xact' is set to 0xFF the maximum number of packets,
 124 allocated within one MOST frame, is calculated that fit into _one_ 512 byte
 125 USB full packet.
 126
 127         frame_size = floor(MTU_USB / bandwidth_sync) * bandwidth_sync
 128
 129 This frame_size is the number of synchronous data within an USB transaction,
 130 which renders MTU_USB - frame_size bytes for padding.
 131
 132 When transmitting isochronous AVP data the desired packet size needs to be
 133 written to 'set_subbuffer_size' and hardware will always expect two isochronous
 134 packets within one USB transaction. This renders
 135
 136         MTU_USB - (2 * set_subbuffer_size)
 137
 138 bytes for padding.
 139
 140 Note that at least 2 times set_subbuffer_size bytes for isochronous data or
 141 set_subbuffer_size times packts_per_xact bytes for synchronous data need to be
 142 put in the transmission buffer and passed to the driver.
 143
 144 Since HDMs are allowed to change a chosen configuration to best fit its
 145 constraints, it is recommended to always double check the configuration and read
 146 back the previously written files.
 147
 148
 149
 150                 Section 4 Routing Channels
 151
 152 To connect a channel that has been configured as outlined above to an AIM and
 153 make it accessible to user space applications, the attribute file 'add_link' is
 154 used. To actually bind a channel to the AIM a string needs to be written to the
 155 file that complies with the following syntax:
 156
 157         "most_device:channel_name:link_name[.param]"
 158
 159 The example above links the channel "channel_name" of the device "most_device"
 160 to the AIM. In case the AIM interfaces the VFS this would also create a device
 161 node "link_name" in the /dev directory. The parameter "param" is an AIM dependent
 162 string, which can be omitted in case the used AIM does not make any use of it.
 163
 164 Cdev AIM example:
 165         $ echo "mdev0:ep_81:my_rx_channel" >add_link
 166         $ echo "mdev0:ep_81" >add_link
 167
 168
 169 Sound/ALSA AIM example:
 170
 171 The sound/ALSA AIM needs an additional parameter to determine the audio resolution
 172 that is going to be used. The following strings can be used:
 173
 174         - "1x8" (Mono)
 175         - "2x16" (16-bit stereo)
 176         - "2x24" (24-bit stereo)
 177         - "2x32" (32-bit stereo)
 178
 179         $ echo "mdev0:ep_81:audio_rx.2x16" >add_link
 180         $ echo "mdev0:ep_81" >add_link