Merge branch 'next' of git://git.kernel.org/pub/scm/linux/kernel/git/rzhang/linux
[sfrench/cifs-2.6.git] / Documentation / networking / can_ucan_protocol.rst
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
147 Setup bittiming by sending the 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 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``