0001 =================
0002 The UCAN Protocol
0003 =================
0004
0005 UCAN is the protocol used by the microcontroller-based USB-CAN
0006 adapter that is integrated on System-on-Modules from Theobroma Systems
0007 and that is also available as a standalone USB stick.
0008
0009 The UCAN protocol has been designed to be hardware-independent.
0010 It is modeled closely after how Linux represents CAN devices
0011 internally. All multi-byte integers are encoded as Little Endian.
0012
0013 All structures mentioned in this document are defined in
0014 ``drivers/net/can/usb/ucan.c``.
0015
0016 USB Endpoints
0017 =============
0018
0019 UCAN devices use three USB endpoints:
0020
0021 CONTROL endpoint
0022 The driver sends device management commands on this endpoint
0023
0024 IN endpoint
0025 The device sends CAN data frames and CAN error frames
0026
0027 OUT endpoint
0028 The driver sends CAN data frames on the out endpoint
0029
0030
0031 CONTROL Messages
0032 ================
0033
0034 UCAN devices are configured using vendor requests on the control pipe.
0035
0036 To support multiple CAN interfaces in a single USB device all
0037 configuration commands target the corresponding interface in the USB
0038 descriptor.
0039
0040 The driver uses ``ucan_ctrl_command_in/out`` and
0041 ``ucan_device_request_in`` to deliver commands to the device.
0042
0043 Setup Packet
0044 ------------
0045
0046 ================= =====================================================
0047 ``bmRequestType`` Direction | Vendor | (Interface or Device)
0048 ``bRequest`` Command Number
0049 ``wValue`` Subcommand Number (16 Bit) or 0 if not used
0050 ``wIndex`` USB Interface Index (0 for device commands)
0051 ``wLength`` * Host to Device - Number of bytes to transmit
0052 * Device to Host - Maximum Number of bytes to
0053 receive. If the device send less. Commom ZLP
0054 semantics are used.
0055 ================= =====================================================
0056
0057 Error Handling
0058 --------------
0059
0060 The device indicates failed control commands by stalling the
0061 pipe.
0062
0063 Device Commands
0064 ---------------
0065
0066 UCAN_DEVICE_GET_FW_STRING
0067 ~~~~~~~~~~~~~~~~~~~~~~~~~
0068
0069 *Dev2Host; optional*
0070
0071 Request the device firmware string.
0072
0073
0074 Interface Commands
0075 ------------------
0076
0077 UCAN_COMMAND_START
0078 ~~~~~~~~~~~~~~~~~~
0079
0080 *Host2Dev; mandatory*
0081
0082 Bring the CAN interface up.
0083
0084 Payload Format
0085 ``ucan_ctl_payload_t.cmd_start``
0086
0087 ==== ============================
0088 mode or mask of ``UCAN_MODE_*``
0089 ==== ============================
0090
0091 UCAN_COMMAND_STOP
0092 ~~~~~~~~~~~~~~~~~~
0093
0094 *Host2Dev; mandatory*
0095
0096 Stop the CAN interface
0097
0098 Payload Format
0099 *empty*
0100
0101 UCAN_COMMAND_RESET
0102 ~~~~~~~~~~~~~~~~~~
0103
0104 *Host2Dev; mandatory*
0105
0106 Reset the CAN controller (including error counters)
0107
0108 Payload Format
0109 *empty*
0110
0111 UCAN_COMMAND_GET
0112 ~~~~~~~~~~~~~~~~
0113
0114 *Host2Dev; mandatory*
0115
0116 Get Information from the Device
0117
0118 Subcommands
0119 ^^^^^^^^^^^
0120
0121 UCAN_COMMAND_GET_INFO
0122 Request the device information structure ``ucan_ctl_payload_t.device_info``.
0123
0124 See the ``device_info`` field for details, and
0125 ``uapi/linux/can/netlink.h`` for an explanation of the
0126 ``can_bittiming fields``.
0127
0128 Payload Format
0129 ``ucan_ctl_payload_t.device_info``
0130
0131 UCAN_COMMAND_GET_PROTOCOL_VERSION
0132
0133 Request the device protocol version
0134 ``ucan_ctl_payload_t.protocol_version``. The current protocol version is 3.
0135
0136 Payload Format
0137 ``ucan_ctl_payload_t.protocol_version``
0138
0139 .. note:: Devices that do not implement this command use the old
0140 protocol version 1
0141
0142 UCAN_COMMAND_SET_BITTIMING
0143 ~~~~~~~~~~~~~~~~~~~~~~~~~~
0144
0145 *Host2Dev; mandatory*
0146
0147 Setup bittiming by sending the structure
0148 ``ucan_ctl_payload_t.cmd_set_bittiming`` (see ``struct bittiming`` for
0149 details)
0150
0151 Payload Format
0152 ``ucan_ctl_payload_t.cmd_set_bittiming``.
0153
0154 UCAN_SLEEP/WAKE
0155 ~~~~~~~~~~~~~~~
0156
0157 *Host2Dev; optional*
0158
0159 Configure sleep and wake modes. Not yet supported by the driver.
0160
0161 UCAN_FILTER
0162 ~~~~~~~~~~~
0163
0164 *Host2Dev; optional*
0165
0166 Setup hardware CAN filters. Not yet supported by the driver.
0167
0168 Allowed interface commands
0169 --------------------------
0170
0171 ================== =================== ==================
0172 Legal Device State Command New Device State
0173 ================== =================== ==================
0174 stopped SET_BITTIMING stopped
0175 stopped START started
0176 started STOP or RESET stopped
0177 stopped STOP or RESET stopped
0178 started RESTART started
0179 any GET *no change*
0180 ================== =================== ==================
0181
0182 IN Message Format
0183 =================
0184
0185 A data packet on the USB IN endpoint contains one or more
0186 ``ucan_message_in`` values. If multiple messages are batched in a USB
0187 data packet, the ``len`` field can be used to jump to the next
0188 ``ucan_message_in`` value (take care to sanity-check the ``len`` value
0189 against the actual data size).
0190
0191 .. _can_ucan_in_message_len:
0192
0193 ``len`` field
0194 -------------
0195
0196 Each ``ucan_message_in`` must be aligned to a 4-byte boundary (relative
0197 to the start of the start of the data buffer). That means that there
0198 may be padding bytes between multiple ``ucan_message_in`` values:
0199
0200 .. code::
0201
0202 +----------------------------+ < 0
0203 | |
0204 | struct ucan_message_in |
0205 | |
0206 +----------------------------+ < len
0207 [padding]
0208 +----------------------------+ < round_up(len, 4)
0209 | |
0210 | struct ucan_message_in |
0211 | |
0212 +----------------------------+
0213 [...]
0214
0215 ``type`` field
0216 --------------
0217
0218 The ``type`` field specifies the type of the message.
0219
0220 UCAN_IN_RX
0221 ~~~~~~~~~~
0222
0223 ``subtype``
0224 zero
0225
0226 Data received from the CAN bus (ID + payload).
0227
0228 UCAN_IN_TX_COMPLETE
0229 ~~~~~~~~~~~~~~~~~~~
0230
0231 ``subtype``
0232 zero
0233
0234 The CAN device has sent a message to the CAN bus. It answers with a
0235 list of tuples <echo-ids, flags>.
0236
0237 The echo-id identifies the frame from (echos the id from a previous
0238 UCAN_OUT_TX message). The flag indicates the result of the
0239 transmission. Whereas a set Bit 0 indicates success. All other bits
0240 are reserved and set to zero.
0241
0242 Flow Control
0243 ------------
0244
0245 When receiving CAN messages there is no flow control on the USB
0246 buffer. The driver has to handle inbound message quickly enough to
0247 avoid drops. I case the device buffer overflow the condition is
0248 reported by sending corresponding error frames (see
0249 :ref:`can_ucan_error_handling`)
0250
0251
0252 OUT Message Format
0253 ==================
0254
0255 A data packet on the USB OUT endpoint contains one or more ``struct
0256 ucan_message_out`` values. If multiple messages are batched into one
0257 data packet, the device uses the ``len`` field to jump to the next
0258 ucan_message_out value. Each ucan_message_out must be aligned to 4
0259 bytes (relative to the start of the data buffer). The mechanism is
0260 same as described in :ref:`can_ucan_in_message_len`.
0261
0262 .. code::
0263
0264 +----------------------------+ < 0
0265 | |
0266 | struct ucan_message_out |
0267 | |
0268 +----------------------------+ < len
0269 [padding]
0270 +----------------------------+ < round_up(len, 4)
0271 | |
0272 | struct ucan_message_out |
0273 | |
0274 +----------------------------+
0275 [...]
0276
0277 ``type`` field
0278 --------------
0279
0280 In protocol version 3 only ``UCAN_OUT_TX`` is defined, others are used
0281 only by legacy devices (protocol version 1).
0282
0283 UCAN_OUT_TX
0284 ~~~~~~~~~~~
0285 ``subtype``
0286 echo id to be replied within a CAN_IN_TX_COMPLETE message
0287
0288 Transmit a CAN frame. (parameters: ``id``, ``data``)
0289
0290 Flow Control
0291 ------------
0292
0293 When the device outbound buffers are full it starts sending *NAKs* on
0294 the *OUT* pipe until more buffers are available. The driver stops the
0295 queue when a certain threshold of out packets are incomplete.
0296
0297 .. _can_ucan_error_handling:
0298
0299 CAN Error Handling
0300 ==================
0301
0302 If error reporting is turned on the device encodes errors into CAN
0303 error frames (see ``uapi/linux/can/error.h``) and sends it using the
0304 IN endpoint. The driver updates its error statistics and forwards
0305 it.
0306
0307 Although UCAN devices can suppress error frames completely, in Linux
0308 the driver is always interested. Hence, the device is always started with
0309 the ``UCAN_MODE_BERR_REPORT`` set. Filtering those messages for the
0310 user space is done by the driver.
0311
0312 Bus OFF
0313 -------
0314
0315 - The device does not recover from bus of automatically.
0316 - Bus OFF is indicated by an error frame (see ``uapi/linux/can/error.h``)
0317 - Bus OFF recovery is started by ``UCAN_COMMAND_RESTART``
0318 - Once Bus OFF recover is completed the device sends an error frame
0319 indicating that it is on ERROR-ACTIVE state.
0320 - During Bus OFF no frames are sent by the device.
0321 - During Bus OFF transmission requests from the host are completed
0322 immediately with the success bit left unset.
0323
0324 Example Conversation
0325 ====================
0326
0327 #) Device is connected to USB
0328 #) Host sends command ``UCAN_COMMAND_RESET``, subcmd 0
0329 #) Host sends command ``UCAN_COMMAND_GET``, subcmd ``UCAN_COMMAND_GET_INFO``
0330 #) Device sends ``UCAN_IN_DEVICE_INFO``
0331 #) Host sends command ``UCAN_OUT_SET_BITTIMING``
0332 #) Host sends command ``UCAN_COMMAND_START``, subcmd 0, mode ``UCAN_MODE_BERR_REPORT``
