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 MOST driver uses module stacking to divide the associated modules into
  27 three layers. From bottom up these layers are: the adapter layer, the core
  28 layer and the application layer. The core layer implements the MOST
  29 subsystem and consists basically of the module core.c and its API. It
  30 registers the MOST bus with the kernel's device model, handles the data
  31 routing through all three layers, the configuration of the driver, the
  32 representation of the configuration interface in sysfs and the buffer
  33 management.
  34
  35 For each of the other two layers a set of modules is provided. Those can be
  36 arbitrarily combined with the core to meet the connectivity of the desired
  37 system architecture.
  38
  39 A module of the adapter layer is basically a device driver for a different
  40 subsystem. It is registered with the core to connect the MOST subsystem to
  41 the attached network interface controller hardware. Hence, a given module
  42 of this layer is designed to handle exactly one of the peripheral
  43 interfaces (e.g. USB, MediaLB, I2C) the hardware provides.
  44
  45 A module of the application layer is referred to as a core comoponent,
  46 which kind of extends the core by providing connectivity to the user space.
  47 Applications, then, can access a MOST network via character devices, an
  48 ALSA soundcard, a Network adapter or a V4L2 capture device.
  49
  50 To physically access MOST, an Intelligent Network Interface Controller
  51 (INIC) is needed. For more information on available controllers visit:
  52 www.microchip.com
  53
  54
  55
  56                 Section 1.1 Adapter Layer
  57
  58 The adapter layer contains a pool of device drivers. For each peripheral
  59 interface the hardware supports there is one suitable module that handles
  60 the interface. Adapter drivers encapsulate the peripheral interface
  61 specific knowledge of the MOST driver stack and provide an easy way of
  62 extending the number of supported interfaces. Currently the following
  63 interfaces are available:
  64
  65         1) MediaLB (DIM2)
  66            Host wants to communicate with hardware via MediaLB.
  67
  68         2) I2C
  69            Host wants to communicate with the hardware via I2C.
  70
  71         3) USB
  72            Host wants to communicate with the hardware via USB.
  73
  74 Once an adapter driver recognizes a MOST device being attached, it
  75 registers it with the core, which, in turn, assigns the necessary members
  76 of the embedded struct device (e.g. the bus this device belongs to and
  77 attribute groups) and registers it with the kernel's device model.
  78
  79
  80                 Section 1.2 Core Layer
  81
  82 This layer implements the MOST subsystem. It contains the core module and
  83 the header file most.h that exposes the API of the core. When inserted in
  84 the kernel, it registers the MOST bus_type with the kernel's device model
  85 and registers itself as a device driver for this bus. Besides these meta
  86 tasks the core populates the configuration directory for a registered MOST
  87 device (represented by struct most_interface) in sysfs and processes the
  88 configuration of the device's interface. The core layer also handles the
  89 buffer management and the data/message routing.
  90
  91
  92                 Section 1.3 Application Layer
  93
  94 This layer contains a pool of device drivers that are components of the
  95 core designed to make up the userspace experience of the MOST driver stack.
  96 Depending on how an application is meant to interface the driver, one or
  97 more modules of this pool can be registered with the core. Currently the
  98 following components are available
  99
 100         1) Character Device
 101            Userspace can access the driver by means of character devices.
 102
 103         2) Networking
 104            Standard networking applications (e.g. iperf) can by used to access
 105            the driver via the networking subsystem.
 106
 107         3) Video4Linux (v4l2)
 108            Standard video applications (e.g. VLC) can by used to access the
 109            driver via the V4L subsystem.
 110
 111         4) Advanced Linux Sound Architecture (ALSA)
 112            Standard sound applications (e.g. aplay, arecord, audacity) can by
 113            used to access the driver via the ALSA subsystem.
 114
 115
 116                 Section 2 Usage of the MOST Driver
 117
 118                 Section 2.1 Configuration
 119
 120 See ABI/sysfs-bus-most.txt
 121
 122
 123                 Section 2.2 Routing Channels
 124
 125 To connect a configured channel to a certain core component and make it
 126 accessible for user space applications, the driver attribute 'add_link' is
 127 used. The configuration string passed to it has the following format:
 128
 129         "device_name:channel_name:component_name:link_name[.param]"
 130
 131 It is the concatenation of up to four substrings separated by a colon. The
 132 substrings contain the names of the MOST interface, the channel, the
 133 component driver and a custom name with which the link is going to be
 134 referenced with. Since some components need additional information, the
 135 link name can be extended with a component-specific parameter (separated by
 136 a dot). In case the character device component is loaded, the handle would
 137 also appear as a device node in the /dev directory.
 138
 139 Cdev component example:
 140         $ echo "mdev0:ep_81:cdev:my_rx_channel" >$(DRV_DIR)/add_link
 141
 142
 143 Sound component example:
 144
 145 The sound component needs an additional parameter to determine the audio
 146 resolution that is going to be used. The following formats are available:
 147
 148         - "1x8" (Mono)
 149         - "2x16" (16-bit stereo)
 150         - "2x24" (24-bit stereo)
 151         - "2x32" (32-bit stereo)
 152         - "6x16" (16-bit surround 5.1)
 153
 154         $ echo "mdev0:ep_81:sound:most51_playback.6x16" >$(DRV_DIR)/add_link
 155
 156
 157
 158                 Section 2.3 USB Padding
 159
 160 When transceiving synchronous or isochronous data, the number of packets
 161 per USB transaction and the sub-buffer size need to be configured. These
 162 values are needed for the driver to process buffer padding, as expected by
 163 hardware, which is for performance optimization purposes of the USB
 164 transmission.
 165
 166 When transmitting synchronous data the allocated channel width needs to be
 167 written to 'set_subbuffer_size'. Additionally, the number of MOST frames
 168 that should travel to the host within one USB transaction need to be
 169 written to 'packets_per_xact'.
 170
 171 The driver, then, calculates the synchronous threshold as follows:
 172
 173         frame_size = set_subbuffer_size * packets_per_xact
 174
 175 In case 'packets_per_xact' is set to 0xFF the maximum number of packets,
 176 allocated within one MOST frame, is calculated that fit into _one_ 512 byte
 177 USB full packet.
 178
 179         frame_size = floor(MTU_USB / bandwidth_sync) * bandwidth_sync
 180
 181 This frame_size is the number of synchronous data within an USB
 182 transaction, which renders MTU_USB - frame_size bytes for padding.
 183
 184 When transmitting isochronous AVP data the desired packet size needs to be
 185 written to 'set_subbuffer_size' and hardware will always expect two
 186 isochronous packets within one USB transaction. This renders
 187
 188         MTU_USB - (2 * set_subbuffer_size)
 189
 190 bytes for padding.
 191
 192 Note that at least (2 * set_subbuffer_size) bytes for isochronous data or
 193 (set_subbuffer_size * packts_per_xact) bytes for synchronous data need to
 194 be put in the transmission buffer and passed to the driver.
 195
 196 Since adapter drivers are allowed to change a chosen configuration to best
 197 fit its constraints, it is recommended to always double check the
 198 configuration and read back the previously written files.