1================= 2The UCAN Protocol 3================= 4 5UCAN is the protocol used by the microcontroller-based USB-CAN 6adapter that is integrated on System-on-Modules from Theobroma Systems 7and that is also available as a standalone USB stick. 8 9The UCAN protocol has been designed to be hardware-independent. 10It is modeled closely after how Linux represents CAN devices 11internally. All multi-byte integers are encoded as Little Endian. 12 13All structures mentioned in this document are defined in 14``drivers/net/can/usb/ucan.c``. 15 16USB Endpoints 17============= 18 19UCAN devices use three USB endpoints: 20 21CONTROL endpoint 22 The driver sends device management commands on this endpoint 23 24IN endpoint 25 The device sends CAN data frames and CAN error frames 26 27OUT endpoint 28 The driver sends CAN data frames on the out endpoint 29 30 31CONTROL Messages 32================ 33 34UCAN devices are configured using vendor requests on the control pipe. 35 36To support multiple CAN interfaces in a single USB device all 37configuration commands target the corresponding interface in the USB 38descriptor. 39 40The driver uses ``ucan_ctrl_command_in/out`` and 41``ucan_device_request_in`` to deliver commands to the device. 42 43Setup 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. Common ZLP 54 semantics are used. 55================= ===================================================== 56 57Error Handling 58-------------- 59 60The device indicates failed control commands by stalling the 61pipe. 62 63Device Commands 64--------------- 65 66UCAN_DEVICE_GET_FW_STRING 67~~~~~~~~~~~~~~~~~~~~~~~~~ 68 69*Dev2Host; optional* 70 71Request the device firmware string. 72 73 74Interface Commands 75------------------ 76 77UCAN_COMMAND_START 78~~~~~~~~~~~~~~~~~~ 79 80*Host2Dev; mandatory* 81 82Bring the CAN interface up. 83 84Payload Format 85 ``ucan_ctl_payload_t.cmd_start`` 86 87==== ============================ 88mode or mask of ``UCAN_MODE_*`` 89==== ============================ 90 91UCAN_COMMAND_STOP 92~~~~~~~~~~~~~~~~~~ 93 94*Host2Dev; mandatory* 95 96Stop the CAN interface 97 98Payload Format 99 *empty* 100 101UCAN_COMMAND_RESET 102~~~~~~~~~~~~~~~~~~ 103 104*Host2Dev; mandatory* 105 106Reset the CAN controller (including error counters) 107 108Payload Format 109 *empty* 110 111UCAN_COMMAND_GET 112~~~~~~~~~~~~~~~~ 113 114*Host2Dev; mandatory* 115 116Get Information from the Device 117 118Subcommands 119^^^^^^^^^^^ 120 121UCAN_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 131UCAN_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 142UCAN_COMMAND_SET_BITTIMING 143~~~~~~~~~~~~~~~~~~~~~~~~~~ 144 145*Host2Dev; mandatory* 146 147Setup bittiming by sending the structure 148``ucan_ctl_payload_t.cmd_set_bittiming`` (see ``struct bittiming`` for 149details) 150 151Payload Format 152 ``ucan_ctl_payload_t.cmd_set_bittiming``. 153 154UCAN_SLEEP/WAKE 155~~~~~~~~~~~~~~~ 156 157*Host2Dev; optional* 158 159Configure sleep and wake modes. Not yet supported by the driver. 160 161UCAN_FILTER 162~~~~~~~~~~~ 163 164*Host2Dev; optional* 165 166Setup hardware CAN filters. Not yet supported by the driver. 167 168Allowed interface commands 169-------------------------- 170 171================== =================== ================== 172Legal Device State Command New Device State 173================== =================== ================== 174stopped SET_BITTIMING stopped 175stopped START started 176started STOP or RESET stopped 177stopped STOP or RESET stopped 178started RESTART started 179any GET *no change* 180================== =================== ================== 181 182IN Message Format 183================= 184 185A data packet on the USB IN endpoint contains one or more 186``ucan_message_in`` values. If multiple messages are batched in a USB 187data 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 189against the actual data size). 190 191.. _can_ucan_in_message_len: 192 193``len`` field 194------------- 195 196Each ``ucan_message_in`` must be aligned to a 4-byte boundary (relative 197to the start of the start of the data buffer). That means that there 198may 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 218The ``type`` field specifies the type of the message. 219 220UCAN_IN_RX 221~~~~~~~~~~ 222 223``subtype`` 224 zero 225 226Data received from the CAN bus (ID + payload). 227 228UCAN_IN_TX_COMPLETE 229~~~~~~~~~~~~~~~~~~~ 230 231``subtype`` 232 zero 233 234The CAN device has sent a message to the CAN bus. It answers with a 235list of tuples <echo-ids, flags>. 236 237The echo-id identifies the frame from (echos the id from a previous 238UCAN_OUT_TX message). The flag indicates the result of the 239transmission. Whereas a set Bit 0 indicates success. All other bits 240are reserved and set to zero. 241 242Flow Control 243------------ 244 245When receiving CAN messages there is no flow control on the USB 246buffer. The driver has to handle inbound message quickly enough to 247avoid drops. I case the device buffer overflow the condition is 248reported by sending corresponding error frames (see 249:ref:`can_ucan_error_handling`) 250 251 252OUT Message Format 253================== 254 255A data packet on the USB OUT endpoint contains one or more ``struct 256ucan_message_out`` values. If multiple messages are batched into one 257data packet, the device uses the ``len`` field to jump to the next 258ucan_message_out value. Each ucan_message_out must be aligned to 4 259bytes (relative to the start of the data buffer). The mechanism is 260same 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 280In protocol version 3 only ``UCAN_OUT_TX`` is defined, others are used 281only by legacy devices (protocol version 1). 282 283UCAN_OUT_TX 284~~~~~~~~~~~ 285``subtype`` 286 echo id to be replied within a CAN_IN_TX_COMPLETE message 287 288Transmit a CAN frame. (parameters: ``id``, ``data``) 289 290Flow Control 291------------ 292 293When the device outbound buffers are full it starts sending *NAKs* on 294the *OUT* pipe until more buffers are available. The driver stops the 295queue when a certain threshold of out packets are incomplete. 296 297.. _can_ucan_error_handling: 298 299CAN Error Handling 300================== 301 302If error reporting is turned on the device encodes errors into CAN 303error frames (see ``uapi/linux/can/error.h``) and sends it using the 304IN endpoint. The driver updates its error statistics and forwards 305it. 306 307Although UCAN devices can suppress error frames completely, in Linux 308the driver is always interested. Hence, the device is always started with 309the ``UCAN_MODE_BERR_REPORT`` set. Filtering those messages for the 310user space is done by the driver. 311 312Bus 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 324Example 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`` 333