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. Common 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``
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.