Commit | Line | Data |
---|---|---|
9f2d3eae JU |
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. Commom 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 | ||
6d0fe3ae | 147 | Setup bittiming by sending the structure |
9f2d3eae JU |
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 | |
6d0fe3ae | 235 | list of tuples <echo-ids, flags>. |
9f2d3eae JU |
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`` |