Documentation/networking/can_ucan_protocol.rst

   1 =================
   2 The UCAN Protocol
   3 =================
   4
   5 UCAN is the protocol used by the microcontroller-based USB-CAN
   6 adapter that is integrated on System-on-Modules from Theobroma Systems
   7 and that is also available as a standalone USB stick.
   8
   9 The UCAN protocol has been designed to be hardware-independent.
  10 It is modeled closely after how Linux represents CAN devices
  11 internally. All multi-byte integers are encoded as Little Endian.
  12
  13 All structures mentioned in this document are defined in
  14 ``drivers/net/can/usb/ucan.c``.
  15
  16 USB Endpoints
  17 =============
  18
  19 UCAN devices use three USB endpoints:
  20
  21 CONTROL endpoint
  22   The driver sends device management commands on this endpoint
  23
  24 IN endpoint
  25   The device sends CAN data frames and CAN error frames
  26
  27 OUT endpoint
  28   The driver sends CAN data frames on the out endpoint
  29
  30
  31 CONTROL Messages
  32 ================
  33
  34 UCAN devices are configured using vendor requests on the control pipe.
  35
  36 To support multiple CAN interfaces in a single USB device all
  37 configuration commands target the corresponding interface in the USB
  38 descriptor.
  39
  40 The driver uses ``ucan_ctrl_command_in/out`` and
  41 ``ucan_device_request_in`` to deliver commands to the device.
  42
  43 Setup Packet
  44 ------------
  45
  46 =================  =====================================================
  47 ``bmRequestType``  Direction | Vendor | (Interface or Device)
  48 ``bRequest``       Command Number
  49 ``wValue``         Subcommand Number (16 Bit) or 0 if not used
  50 ``wIndex``         USB Interface Index (0 for device commands)
  51 ``wLength``        * Host to Device - Number of bytes to transmit
  52                    * Device to Host - Maximum Number of bytes to
  53                      receive. If the device send less. Commom ZLP
  54                      semantics are used.
  55 =================  =====================================================
  56
  57 Error Handling
  58 --------------
  59
  60 The device indicates failed control commands by stalling the
  61 pipe.
  62
  63 Device Commands
  64 ---------------
  65
  66 UCAN_DEVICE_GET_FW_STRING
  67 ~~~~~~~~~~~~~~~~~~~~~~~~~
  68
  69 *Dev2Host; optional*
  70
  71 Request the device firmware string.
  72
  73
  74 Interface Commands
  75 ------------------
  76
  77 UCAN_COMMAND_START
  78 ~~~~~~~~~~~~~~~~~~
  79
  80 *Host2Dev; mandatory*
  81
  82 Bring the CAN interface up.
  83
  84 Payload Format
  85   ``ucan_ctl_payload_t.cmd_start``
  86
  87 ====  ============================
  88 mode  or mask of ``UCAN_MODE_*``
  89 ====  ============================
  90
  91 UCAN_COMMAND_STOP
  92 ~~~~~~~~~~~~~~~~~~
  93
  94 *Host2Dev; mandatory*
  95
  96 Stop the CAN interface
  97
  98 Payload Format
  99   *empty*
 100
 101 UCAN_COMMAND_RESET
 102 ~~~~~~~~~~~~~~~~~~
 103
 104 *Host2Dev; mandatory*
 105
 106 Reset the CAN controller (including error counters)
 107
 108 Payload Format
 109   *empty*
 110
 111 UCAN_COMMAND_GET
 112 ~~~~~~~~~~~~~~~~
 113
 114 *Host2Dev; mandatory*
 115
 116 Get Information from the Device
 117
 118 Subcommands
 119 ^^^^^^^^^^^
 120
 121 UCAN_COMMAND_GET_INFO
 122   Request the device information structure ``ucan_ctl_payload_t.device_info``.
 123
 124   See the ``device_info`` field for details, and
 125   ``uapi/linux/can/netlink.h`` for an explanation of the
 126   ``can_bittiming fields``.
 127
 128   Payload Format
 129     ``ucan_ctl_payload_t.device_info``
 130
 131 UCAN_COMMAND_GET_PROTOCOL_VERSION
 132
 133   Request the device protocol version
 134   ``ucan_ctl_payload_t.protocol_version``. The current protocol version is 3.
 135
 136   Payload Format
 137     ``ucan_ctl_payload_t.protocol_version``
 138
 139 .. note:: Devices that do not implement this command use the old
 140           protocol version 1
 141
 142 UCAN_COMMAND_SET_BITTIMING
 143 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 144
 145 *Host2Dev; mandatory*
 146
 147 Setup bittiming by sending the structure
 148 ``ucan_ctl_payload_t.cmd_set_bittiming`` (see ``struct bittiming`` for
 149 details)
 150
 151 Payload Format
 152   ``ucan_ctl_payload_t.cmd_set_bittiming``.
 153
 154 UCAN_SLEEP/WAKE
 155 ~~~~~~~~~~~~~~~
 156
 157 *Host2Dev; optional*
 158
 159 Configure sleep and wake modes. Not yet supported by the driver.
 160
 161 UCAN_FILTER
 162 ~~~~~~~~~~~
 163
 164 *Host2Dev; optional*
 165
 166 Setup hardware CAN filters. Not yet supported by the driver.
 167
 168 Allowed interface commands
 169 --------------------------
 170
 171 ==================  ===================  ==================
 172 Legal Device State  Command              New Device State
 173 ==================  ===================  ==================
 174 stopped             SET_BITTIMING        stopped
 175 stopped             START                started
 176 started             STOP or RESET        stopped
 177 stopped             STOP or RESET        stopped
 178 started             RESTART              started
 179 any                 GET                  *no change*
 180 ==================  ===================  ==================
 181
 182 IN Message Format
 183 =================
 184
 185 A data packet on the USB IN endpoint contains one or more
 186 ``ucan_message_in`` values. If multiple messages are batched in a USB
 187 data packet, the ``len`` field can be used to jump to the next
 188 ``ucan_message_in`` value (take care to sanity-check the ``len`` value
 189 against the actual data size).
 190
 191 .. _can_ucan_in_message_len:
 192
 193 ``len`` field
 194 -------------
 195
 196 Each ``ucan_message_in`` must be aligned to a 4-byte boundary (relative
 197 to the start of the start of the data buffer). That means that there
 198 may be padding bytes between multiple ``ucan_message_in`` values:
 199
 200 .. code::
 201
 202     +----------------------------+ < 0
 203     |                            |
 204     |   struct ucan_message_in   |
 205     |                            |
 206     +----------------------------+ < len
 207               [padding]
 208     +----------------------------+ < round_up(len, 4)
 209     |                            |
 210     |   struct ucan_message_in   |
 211     |                            |
 212     +----------------------------+
 213                 [...]
 214
 215 ``type`` field
 216 --------------
 217
 218 The ``type`` field specifies the type of the message.
 219
 220 UCAN_IN_RX
 221 ~~~~~~~~~~
 222
 223 ``subtype``
 224   zero
 225
 226 Data received from the CAN bus (ID + payload).
 227
 228 UCAN_IN_TX_COMPLETE
 229 ~~~~~~~~~~~~~~~~~~~
 230
 231 ``subtype``
 232   zero
 233
 234 The CAN device has sent a message to the CAN bus. It answers with a
 235 list of tuples <echo-ids, flags>.
 236
 237 The echo-id identifies the frame from (echos the id from a previous
 238 UCAN_OUT_TX message). The flag indicates the result of the
 239 transmission. Whereas a set Bit 0 indicates success. All other bits
 240 are reserved and set to zero.
 241
 242 Flow Control
 243 ------------
 244
 245 When receiving CAN messages there is no flow control on the USB
 246 buffer. The driver has to handle inbound message quickly enough to
 247 avoid drops. I case the device buffer overflow the condition is
 248 reported by sending corresponding error frames (see
 249 :ref:`can_ucan_error_handling`)
 250
 251
 252 OUT Message Format
 253 ==================
 254
 255 A data packet on the USB OUT endpoint contains one or more ``struct
 256 ucan_message_out`` values. If multiple messages are batched into one
 257 data packet, the device uses the ``len`` field to jump to the next
 258 ucan_message_out value. Each ucan_message_out must be aligned to 4
 259 bytes (relative to the start of the data buffer). The mechanism is
 260 same as described in :ref:`can_ucan_in_message_len`.
 261
 262 .. code::
 263
 264     +----------------------------+ < 0
 265     |                            |
 266     |   struct ucan_message_out  |
 267     |                            |
 268     +----------------------------+ < len
 269               [padding]
 270     +----------------------------+ < round_up(len, 4)
 271     |                            |
 272     |   struct ucan_message_out  |
 273     |                            |
 274     +----------------------------+
 275                 [...]
 276
 277 ``type`` field
 278 --------------
 279
 280 In protocol version 3 only ``UCAN_OUT_TX`` is defined, others are used
 281 only by legacy devices (protocol version 1).
 282
 283 UCAN_OUT_TX
 284 ~~~~~~~~~~~
 285 ``subtype``
 286   echo id to be replied within a CAN_IN_TX_COMPLETE message
 287
 288 Transmit a CAN frame. (parameters: ``id``, ``data``)
 289
 290 Flow Control
 291 ------------
 292
 293 When the device outbound buffers are full it starts sending *NAKs* on
 294 the *OUT* pipe until more buffers are available. The driver stops the
 295 queue when a certain threshold of out packets are incomplete.
 296
 297 .. _can_ucan_error_handling:
 298
 299 CAN Error Handling
 300 ==================
 301
 302 If error reporting is turned on the device encodes errors into CAN
 303 error frames (see ``uapi/linux/can/error.h``) and sends it using the
 304 IN endpoint. The driver updates its error statistics and forwards
 305 it.
 306
 307 Although UCAN devices can suppress error frames completely, in Linux
 308 the driver is always interested. Hence, the device is always started with
 309 the ``UCAN_MODE_BERR_REPORT`` set. Filtering those messages for the
 310 user space is done by the driver.
 311
 312 Bus OFF
 313 -------
 314
 315 - The device does not recover from bus of automatically.
 316 - Bus OFF is indicated by an error frame (see ``uapi/linux/can/error.h``)
 317 - Bus OFF recovery is started by ``UCAN_COMMAND_RESTART``
 318 - Once Bus OFF recover is completed the device sends an error frame
 319   indicating that it is on ERROR-ACTIVE state.
 320 - During Bus OFF no frames are sent by the device.
 321 - During Bus OFF transmission requests from the host are completed
 322   immediately with the success bit left unset.
 323
 324 Example Conversation
 325 ====================
 326
 327 #) Device is connected to USB
 328 #) Host sends command ``UCAN_COMMAND_RESET``, subcmd 0
 329 #) Host sends command ``UCAN_COMMAND_GET``, subcmd ``UCAN_COMMAND_GET_INFO``
 330 #) Device sends ``UCAN_IN_DEVICE_INFO``
 331 #) Host sends command ``UCAN_OUT_SET_BITTIMING``
 332 #) Host sends command ``UCAN_COMMAND_START``, subcmd 0, mode ``UCAN_MODE_BERR_REPORT``