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. Commom 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