333 lines · plain
1=================2The UCAN Protocol3=================4 5UCAN is the protocol used by the microcontroller-based USB-CAN6adapter that is integrated on System-on-Modules from Theobroma Systems7and 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 devices11internally. All multi-byte integers are encoded as Little Endian.12 13All structures mentioned in this document are defined in14``drivers/net/can/usb/ucan.c``.15 16USB Endpoints17=============18 19UCAN devices use three USB endpoints:20 21CONTROL endpoint22 The driver sends device management commands on this endpoint23 24IN endpoint25 The device sends CAN data frames and CAN error frames26 27OUT endpoint28 The driver sends CAN data frames on the out endpoint29 30 31CONTROL Messages32================33 34UCAN devices are configured using vendor requests on the control pipe.35 36To support multiple CAN interfaces in a single USB device all37configuration commands target the corresponding interface in the USB38descriptor.39 40The driver uses ``ucan_ctrl_command_in/out`` and41``ucan_device_request_in`` to deliver commands to the device.42 43Setup Packet44------------45 46================= =====================================================47``bmRequestType`` Direction | Vendor | (Interface or Device)48``bRequest`` Command Number49``wValue`` Subcommand Number (16 Bit) or 0 if not used50``wIndex`` USB Interface Index (0 for device commands)51``wLength`` * Host to Device - Number of bytes to transmit52 * Device to Host - Maximum Number of bytes to53 receive. If the device send less. Common ZLP54 semantics are used.55================= =====================================================56 57Error Handling58--------------59 60The device indicates failed control commands by stalling the61pipe.62 63Device Commands64---------------65 66UCAN_DEVICE_GET_FW_STRING67~~~~~~~~~~~~~~~~~~~~~~~~~68 69*Dev2Host; optional*70 71Request the device firmware string.72 73 74Interface Commands75------------------76 77UCAN_COMMAND_START78~~~~~~~~~~~~~~~~~~79 80*Host2Dev; mandatory*81 82Bring the CAN interface up.83 84Payload Format85 ``ucan_ctl_payload_t.cmd_start``86 87==== ============================88mode or mask of ``UCAN_MODE_*``89==== ============================90 91UCAN_COMMAND_STOP92~~~~~~~~~~~~~~~~~~93 94*Host2Dev; mandatory*95 96Stop the CAN interface97 98Payload Format99 *empty*100 101UCAN_COMMAND_RESET102~~~~~~~~~~~~~~~~~~103 104*Host2Dev; mandatory*105 106Reset the CAN controller (including error counters)107 108Payload Format109 *empty*110 111UCAN_COMMAND_GET112~~~~~~~~~~~~~~~~113 114*Host2Dev; mandatory*115 116Get Information from the Device117 118Subcommands119^^^^^^^^^^^120 121UCAN_COMMAND_GET_INFO122 Request the device information structure ``ucan_ctl_payload_t.device_info``.123 124 See the ``device_info`` field for details, and125 ``uapi/linux/can/netlink.h`` for an explanation of the126 ``can_bittiming fields``.127 128 Payload Format129 ``ucan_ctl_payload_t.device_info``130 131UCAN_COMMAND_GET_PROTOCOL_VERSION132 133 Request the device protocol version134 ``ucan_ctl_payload_t.protocol_version``. The current protocol version is 3.135 136 Payload Format137 ``ucan_ctl_payload_t.protocol_version``138 139.. note:: Devices that do not implement this command use the old140 protocol version 1141 142UCAN_COMMAND_SET_BITTIMING143~~~~~~~~~~~~~~~~~~~~~~~~~~144 145*Host2Dev; mandatory*146 147Setup bittiming by sending the structure148``ucan_ctl_payload_t.cmd_set_bittiming`` (see ``struct bittiming`` for149details)150 151Payload Format152 ``ucan_ctl_payload_t.cmd_set_bittiming``.153 154UCAN_SLEEP/WAKE155~~~~~~~~~~~~~~~156 157*Host2Dev; optional*158 159Configure sleep and wake modes. Not yet supported by the driver.160 161UCAN_FILTER162~~~~~~~~~~~163 164*Host2Dev; optional*165 166Setup hardware CAN filters. Not yet supported by the driver.167 168Allowed interface commands169--------------------------170 171================== =================== ==================172Legal Device State Command New Device State173================== =================== ==================174stopped SET_BITTIMING stopped175stopped START started176started STOP or RESET stopped177stopped STOP or RESET stopped178started RESTART started179any GET *no change*180================== =================== ==================181 182IN Message Format183=================184 185A data packet on the USB IN endpoint contains one or more186``ucan_message_in`` values. If multiple messages are batched in a USB187data packet, the ``len`` field can be used to jump to the next188``ucan_message_in`` value (take care to sanity-check the ``len`` value189against the actual data size).190 191.. _can_ucan_in_message_len:192 193``len`` field194-------------195 196Each ``ucan_message_in`` must be aligned to a 4-byte boundary (relative197to the start of the start of the data buffer). That means that there198may be padding bytes between multiple ``ucan_message_in`` values:199 200.. code::201 202 +----------------------------+ < 0203 | |204 | struct ucan_message_in |205 | |206 +----------------------------+ < len207 [padding]208 +----------------------------+ < round_up(len, 4)209 | |210 | struct ucan_message_in |211 | |212 +----------------------------+213 [...]214 215``type`` field216--------------217 218The ``type`` field specifies the type of the message.219 220UCAN_IN_RX221~~~~~~~~~~222 223``subtype``224 zero225 226Data received from the CAN bus (ID + payload).227 228UCAN_IN_TX_COMPLETE229~~~~~~~~~~~~~~~~~~~230 231``subtype``232 zero233 234The CAN device has sent a message to the CAN bus. It answers with a235list of tuples <echo-ids, flags>.236 237The echo-id identifies the frame from (echos the id from a previous238UCAN_OUT_TX message). The flag indicates the result of the239transmission. Whereas a set Bit 0 indicates success. All other bits240are reserved and set to zero.241 242Flow Control243------------244 245When receiving CAN messages there is no flow control on the USB246buffer. The driver has to handle inbound message quickly enough to247avoid drops. I case the device buffer overflow the condition is248reported by sending corresponding error frames (see249:ref:`can_ucan_error_handling`)250 251 252OUT Message Format253==================254 255A data packet on the USB OUT endpoint contains one or more ``struct256ucan_message_out`` values. If multiple messages are batched into one257data packet, the device uses the ``len`` field to jump to the next258ucan_message_out value. Each ucan_message_out must be aligned to 4259bytes (relative to the start of the data buffer). The mechanism is260same as described in :ref:`can_ucan_in_message_len`.261 262.. code::263 264 +----------------------------+ < 0265 | |266 | struct ucan_message_out |267 | |268 +----------------------------+ < len269 [padding]270 +----------------------------+ < round_up(len, 4)271 | |272 | struct ucan_message_out |273 | |274 +----------------------------+275 [...]276 277``type`` field278--------------279 280In protocol version 3 only ``UCAN_OUT_TX`` is defined, others are used281only by legacy devices (protocol version 1).282 283UCAN_OUT_TX284~~~~~~~~~~~285``subtype``286 echo id to be replied within a CAN_IN_TX_COMPLETE message287 288Transmit a CAN frame. (parameters: ``id``, ``data``)289 290Flow Control291------------292 293When the device outbound buffers are full it starts sending *NAKs* on294the *OUT* pipe until more buffers are available. The driver stops the295queue when a certain threshold of out packets are incomplete.296 297.. _can_ucan_error_handling:298 299CAN Error Handling300==================301 302If error reporting is turned on the device encodes errors into CAN303error frames (see ``uapi/linux/can/error.h``) and sends it using the304IN endpoint. The driver updates its error statistics and forwards305it.306 307Although UCAN devices can suppress error frames completely, in Linux308the driver is always interested. Hence, the device is always started with309the ``UCAN_MODE_BERR_REPORT`` set. Filtering those messages for the310user space is done by the driver.311 312Bus OFF313-------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 frame319 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 completed322 immediately with the success bit left unset.323 324Example Conversation325====================326 327#) Device is connected to USB328#) Host sends command ``UCAN_COMMAND_RESET``, subcmd 0329#) 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