2 * f_sdp.c -- USB HID Serial Download Protocol
4 * Copyright (C) 2017 Toradex
5 * Author: Stefan Agner <stefan.agner@toradex.com>
7 * This file implements the Serial Download Protocol (SDP) as specified in
8 * the i.MX 6 Reference Manual. The SDP is a USB HID based protocol and
9 * allows to download images directly to memory. The implementation
10 * works with the imx_loader (imx_usb) USB client software on host side.
12 * Not all commands are implemented, e.g. WRITE_REGISTER, DCD_WRITE and
13 * SKIP_DCD_HEADER are only stubs.
15 * Parts of the implementation are based on f_dfu and f_thor.
17 * SPDX-License-Identifier: GPL-2.0+
25 #include <linux/usb/ch9.h>
26 #include <linux/usb/gadget.h>
27 #include <linux/usb/composite.h>
37 #define HID_REPORT_ID_MASK 0x000000ff
42 #define HID_REQ_GET_REPORT 0x01
43 #define HID_REQ_GET_IDLE 0x02
44 #define HID_REQ_GET_PROTOCOL 0x03
45 #define HID_REQ_SET_REPORT 0x09
46 #define HID_REQ_SET_IDLE 0x0A
47 #define HID_REQ_SET_PROTOCOL 0x0B
49 #define HID_USAGE_PAGE_LEN 76
52 u8 usage_page
[HID_USAGE_PAGE_LEN
];
55 #define SDP_READ_REGISTER 0x0101
56 #define SDP_WRITE_REGISTER 0x0202
57 #define SDP_WRITE_FILE 0x0404
58 #define SDP_ERROR_STATUS 0x0505
59 #define SDP_DCD_WRITE 0x0a0a
60 #define SDP_JUMP_ADDRESS 0x0b0b
61 #define SDP_SKIP_DCD_HEADER 0x0c0c
63 #define SDP_SECURITY_CLOSED 0x12343412
64 #define SDP_SECURITY_OPEN 0x56787856
66 #define SDP_WRITE_FILE_COMPLETE 0x88888888
67 #define SDP_WRITE_REGISTER_COMPLETE 0x128A8A12
68 #define SDP_SKIP_DCD_HEADER_COMPLETE 0x900DD009
69 #define SDP_ERROR_IMXHEADER 0x000a0533
71 #define SDP_COMMAND_LEN 16
84 SDP_STATE_RX_DCD_DATA
,
85 SDP_STATE_RX_FILE_DATA
,
86 SDP_STATE_TX_SEC_CONF
,
87 SDP_STATE_TX_SEC_CONF_BUSY
,
88 SDP_STATE_TX_REGISTER
,
89 SDP_STATE_TX_REGISTER_BUSY
,
91 SDP_STATE_TX_STATUS_BUSY
,
96 struct usb_function usb_function
;
98 struct usb_descriptor_header
**function
;
101 enum sdp_state state
;
102 enum sdp_state next_state
;
104 u32 dnl_bytes_remaining
;
106 bool always_send_status
;
110 struct usb_request
*req
;
113 struct usb_ep
*in_ep
;
114 struct usb_request
*in_req
;
116 bool configuration_done
;
119 static struct f_sdp
*sdp_func
;
121 static inline struct f_sdp
*func_to_sdp(struct usb_function
*f
)
123 return container_of(f
, struct f_sdp
, usb_function
);
126 static struct usb_interface_descriptor sdp_intf_runtime
= {
127 .bLength
= sizeof(sdp_intf_runtime
),
128 .bDescriptorType
= USB_DT_INTERFACE
,
129 .bAlternateSetting
= 0,
131 .bInterfaceClass
= USB_CLASS_HID
,
132 .bInterfaceSubClass
= 0,
133 .bInterfaceProtocol
= 0,
134 /* .iInterface = DYNAMIC */
137 /* HID configuration */
138 static struct usb_class_hid_descriptor sdp_hid_desc
= {
139 .bLength
= sizeof(sdp_hid_desc
),
140 .bDescriptorType
= USB_DT_CS_DEVICE
,
142 .bcdCDC
= __constant_cpu_to_le16(0x0110),
144 .bNumDescriptors
= 1,
146 .bDescriptorType0
= USB_DT_HID_REPORT
,
147 .wDescriptorLength0
= HID_USAGE_PAGE_LEN
,
150 static struct usb_endpoint_descriptor in_desc
= {
151 .bLength
= USB_DT_ENDPOINT_SIZE
,
152 .bDescriptorType
= USB_DT_ENDPOINT
, /*USB_DT_CS_ENDPOINT*/
154 .bEndpointAddress
= 1 | USB_DIR_IN
,
155 .bmAttributes
= USB_ENDPOINT_XFER_INT
,
156 .wMaxPacketSize
= 64,
160 static struct usb_descriptor_header
*sdp_runtime_descs
[] = {
161 (struct usb_descriptor_header
*)&sdp_intf_runtime
,
162 (struct usb_descriptor_header
*)&sdp_hid_desc
,
163 (struct usb_descriptor_header
*)&in_desc
,
167 /* This is synchronized with what the SoC implementation reports */
168 static struct hid_report sdp_hid_report
= {
170 0x06, 0x00, 0xff, /* Usage Page */
171 0x09, 0x01, /* Usage (Pointer?) */
172 0xa1, 0x01, /* Collection */
174 0x85, 0x01, /* Report ID */
175 0x19, 0x01, /* Usage Minimum */
176 0x29, 0x01, /* Usage Maximum */
177 0x15, 0x00, /* Local Minimum */
178 0x26, 0xFF, 0x00, /* Local Maximum? */
179 0x75, 0x08, /* Report Size */
180 0x95, 0x10, /* Report Count */
181 0x91, 0x02, /* Output Data */
183 0x85, 0x02, /* Report ID */
184 0x19, 0x01, /* Usage Minimum */
185 0x29, 0x01, /* Usage Maximum */
186 0x15, 0x00, /* Local Minimum */
187 0x26, 0xFF, 0x00, /* Local Maximum? */
188 0x75, 0x80, /* Report Size 128 */
189 0x95, 0x40, /* Report Count */
190 0x91, 0x02, /* Output Data */
192 0x85, 0x03, /* Report ID */
193 0x19, 0x01, /* Usage Minimum */
194 0x29, 0x01, /* Usage Maximum */
195 0x15, 0x00, /* Local Minimum */
196 0x26, 0xFF, 0x00, /* Local Maximum? */
197 0x75, 0x08, /* Report Size 8 */
198 0x95, 0x04, /* Report Count */
199 0x81, 0x02, /* Input Data */
201 0x85, 0x04, /* Report ID */
202 0x19, 0x01, /* Usage Minimum */
203 0x29, 0x01, /* Usage Maximum */
204 0x15, 0x00, /* Local Minimum */
205 0x26, 0xFF, 0x00, /* Local Maximum? */
206 0x75, 0x08, /* Report Size 8 */
207 0x95, 0x40, /* Report Count */
208 0x81, 0x02, /* Input Data */
213 static const char sdp_name
[] = "Serial Downloader Protocol";
216 * static strings, in UTF-8
218 static struct usb_string strings_sdp_generic
[] = {
220 { } /* end of list */
223 static struct usb_gadget_strings stringtab_sdp_generic
= {
224 .language
= 0x0409, /* en-us */
225 .strings
= strings_sdp_generic
,
228 static struct usb_gadget_strings
*sdp_generic_strings
[] = {
229 &stringtab_sdp_generic
,
233 static inline void *sdp_ptr(u32 val
)
235 return (void *)(uintptr_t)val
;
238 static void sdp_rx_command_complete(struct usb_ep
*ep
, struct usb_request
*req
)
240 struct f_sdp
*sdp
= req
->context
;
241 int status
= req
->status
;
246 pr_err("Status: %d\n", status
);
251 pr_err("Unexpected report %d\n", report
);
255 struct sdp_command
*cmd
= req
->buf
+ 1;
257 debug("%s: command: %04x, addr: %08x, cnt: %u\n",
258 __func__
, be16_to_cpu(cmd
->cmd
),
259 be32_to_cpu(cmd
->addr
), be32_to_cpu(cmd
->cnt
));
261 switch (be16_to_cpu(cmd
->cmd
)) {
262 case SDP_READ_REGISTER
:
263 sdp
->always_send_status
= false;
264 sdp
->error_status
= 0x0;
266 sdp
->state
= SDP_STATE_TX_SEC_CONF
;
267 sdp
->dnl_address
= be32_to_cpu(cmd
->addr
);
268 sdp
->dnl_bytes_remaining
= be32_to_cpu(cmd
->cnt
);
269 sdp
->next_state
= SDP_STATE_TX_REGISTER
;
270 printf("Reading %d registers at 0x%08x... ",
271 sdp
->dnl_bytes_remaining
, sdp
->dnl_address
);
274 sdp
->always_send_status
= true;
275 sdp
->error_status
= SDP_WRITE_FILE_COMPLETE
;
277 sdp
->state
= SDP_STATE_RX_FILE_DATA
;
278 sdp
->dnl_address
= be32_to_cpu(cmd
->addr
);
279 sdp
->dnl_bytes_remaining
= be32_to_cpu(cmd
->cnt
);
280 sdp
->next_state
= SDP_STATE_IDLE
;
282 printf("Downloading file of size %d to 0x%08x... ",
283 sdp
->dnl_bytes_remaining
, sdp
->dnl_address
);
286 case SDP_ERROR_STATUS
:
287 sdp
->always_send_status
= true;
288 sdp
->error_status
= 0;
290 sdp
->state
= SDP_STATE_TX_SEC_CONF
;
291 sdp
->next_state
= SDP_STATE_IDLE
;
294 sdp
->always_send_status
= true;
295 sdp
->error_status
= SDP_WRITE_REGISTER_COMPLETE
;
297 sdp
->state
= SDP_STATE_RX_DCD_DATA
;
298 sdp
->dnl_bytes_remaining
= be32_to_cpu(cmd
->cnt
);
299 sdp
->next_state
= SDP_STATE_IDLE
;
301 case SDP_JUMP_ADDRESS
:
302 sdp
->always_send_status
= false;
303 sdp
->error_status
= 0;
305 sdp
->jmp_address
= be32_to_cpu(cmd
->addr
);
306 sdp
->state
= SDP_STATE_TX_SEC_CONF
;
307 sdp
->next_state
= SDP_STATE_JUMP
;
309 case SDP_SKIP_DCD_HEADER
:
310 sdp
->always_send_status
= true;
311 sdp
->error_status
= SDP_SKIP_DCD_HEADER_COMPLETE
;
313 /* Ignore command, DCD not supported anyway */
314 sdp
->state
= SDP_STATE_TX_SEC_CONF
;
315 sdp
->next_state
= SDP_STATE_IDLE
;
318 pr_err("Unknown command: %04x\n", be16_to_cpu(cmd
->cmd
));
322 static void sdp_rx_data_complete(struct usb_ep
*ep
, struct usb_request
*req
)
324 struct f_sdp
*sdp
= req
->context
;
325 int status
= req
->status
;
328 int datalen
= req
->length
- 1;
331 pr_err("Status: %d\n", status
);
336 pr_err("Unexpected report %d\n", report
);
340 if (sdp
->dnl_bytes_remaining
< datalen
) {
342 * Some USB stacks require to send a complete buffer as
343 * specified in the HID descriptor. This leads to longer
344 * transfers than the file length, no problem for us.
346 sdp
->dnl_bytes_remaining
= 0;
348 sdp
->dnl_bytes_remaining
-= datalen
;
351 if (sdp
->state
== SDP_STATE_RX_FILE_DATA
) {
352 memcpy(sdp_ptr(sdp
->dnl_address
), req
->buf
+ 1, datalen
);
353 sdp
->dnl_address
+= datalen
;
356 if (sdp
->dnl_bytes_remaining
)
361 switch (sdp
->state
) {
362 case SDP_STATE_RX_FILE_DATA
:
363 sdp
->state
= SDP_STATE_TX_SEC_CONF
;
365 case SDP_STATE_RX_DCD_DATA
:
366 sdp
->state
= SDP_STATE_TX_SEC_CONF
;
369 pr_err("Invalid state: %d\n", sdp
->state
);
373 static void sdp_tx_complete(struct usb_ep
*ep
, struct usb_request
*req
)
375 struct f_sdp
*sdp
= req
->context
;
376 int status
= req
->status
;
379 pr_err("Status: %d\n", status
);
383 switch (sdp
->state
) {
384 case SDP_STATE_TX_SEC_CONF_BUSY
:
385 /* Not all commands require status report */
386 if (sdp
->always_send_status
|| sdp
->error_status
)
387 sdp
->state
= SDP_STATE_TX_STATUS
;
389 sdp
->state
= sdp
->next_state
;
392 case SDP_STATE_TX_STATUS_BUSY
:
393 sdp
->state
= sdp
->next_state
;
395 case SDP_STATE_TX_REGISTER_BUSY
:
396 if (sdp
->dnl_bytes_remaining
)
397 sdp
->state
= SDP_STATE_TX_REGISTER
;
399 sdp
->state
= SDP_STATE_IDLE
;
402 pr_err("Wrong State: %d\n", sdp
->state
);
403 sdp
->state
= SDP_STATE_IDLE
;
406 debug("%s complete --> %d, %d/%d\n", ep
->name
,
407 status
, req
->actual
, req
->length
);
410 static int sdp_setup(struct usb_function
*f
, const struct usb_ctrlrequest
*ctrl
)
412 struct usb_gadget
*gadget
= f
->config
->cdev
->gadget
;
413 struct usb_request
*req
= f
->config
->cdev
->req
;
414 struct f_sdp
*sdp
= f
->config
->cdev
->req
->context
;
415 u16 len
= le16_to_cpu(ctrl
->wLength
);
416 u16 w_value
= le16_to_cpu(ctrl
->wValue
);
418 u8 req_type
= ctrl
->bRequestType
& USB_TYPE_MASK
;
420 debug("w_value: 0x%04x len: 0x%04x\n", w_value
, len
);
421 debug("req_type: 0x%02x ctrl->bRequest: 0x%02x sdp->state: %d\n",
422 req_type
, ctrl
->bRequest
, sdp
->state
);
424 if (req_type
== USB_TYPE_STANDARD
) {
425 if (ctrl
->bRequest
== USB_REQ_GET_DESCRIPTOR
) {
426 /* Send HID report descriptor */
427 value
= min(len
, (u16
) sizeof(sdp_hid_report
));
428 memcpy(req
->buf
, &sdp_hid_report
, value
);
429 sdp
->configuration_done
= true;
433 if (req_type
== USB_TYPE_CLASS
) {
434 int report
= w_value
& HID_REPORT_ID_MASK
;
436 /* HID (SDP) request */
437 switch (ctrl
->bRequest
) {
438 case HID_REQ_SET_REPORT
:
441 value
= SDP_COMMAND_LEN
+ 1;
442 req
->complete
= sdp_rx_command_complete
;
446 req
->complete
= sdp_rx_data_complete
;
454 req
->zero
= value
< len
;
455 value
= usb_ep_queue(gadget
->ep0
, req
, 0);
457 debug("ep_queue --> %d\n", value
);
465 static int sdp_bind(struct usb_configuration
*c
, struct usb_function
*f
)
467 struct usb_gadget
*gadget
= c
->cdev
->gadget
;
468 struct usb_composite_dev
*cdev
= c
->cdev
;
469 struct f_sdp
*sdp
= func_to_sdp(f
);
472 id
= usb_interface_id(c
, f
);
475 sdp_intf_runtime
.bInterfaceNumber
= id
;
479 /* allocate instance-specific endpoints */
480 ep
= usb_ep_autoconfig(gadget
, &in_desc
);
486 sdp
->in_ep
= ep
; /* Store IN EP for enabling @ setup */
488 cdev
->req
->context
= sdp
;
494 static void sdp_unbind(struct usb_configuration
*c
, struct usb_function
*f
)
500 static struct usb_request
*alloc_ep_req(struct usb_ep
*ep
, unsigned length
)
502 struct usb_request
*req
;
504 req
= usb_ep_alloc_request(ep
, 0);
508 req
->length
= length
;
509 req
->buf
= memalign(CONFIG_SYS_CACHELINE_SIZE
, length
);
511 usb_ep_free_request(ep
, req
);
519 static struct usb_request
*sdp_start_ep(struct usb_ep
*ep
)
521 struct usb_request
*req
;
523 req
= alloc_ep_req(ep
, 64);
524 debug("%s: ep:%p req:%p\n", __func__
, ep
, req
);
529 memset(req
->buf
, 0, req
->length
);
530 req
->complete
= sdp_tx_complete
;
534 static int sdp_set_alt(struct usb_function
*f
, unsigned intf
, unsigned alt
)
536 struct f_sdp
*sdp
= func_to_sdp(f
);
537 struct usb_composite_dev
*cdev
= f
->config
->cdev
;
540 debug("%s: intf: %d alt: %d\n", __func__
, intf
, alt
);
542 result
= usb_ep_enable(sdp
->in_ep
, &in_desc
);
545 sdp
->in_req
= sdp_start_ep(sdp
->in_ep
);
546 sdp
->in_req
->context
= sdp
;
548 sdp
->in_ep
->driver_data
= cdev
; /* claim */
550 sdp
->altsetting
= alt
;
551 sdp
->state
= SDP_STATE_IDLE
;
556 static int sdp_get_alt(struct usb_function
*f
, unsigned intf
)
558 struct f_sdp
*sdp
= func_to_sdp(f
);
560 return sdp
->altsetting
;
563 static void sdp_disable(struct usb_function
*f
)
565 struct f_sdp
*sdp
= func_to_sdp(f
);
567 usb_ep_disable(sdp
->in_ep
);
575 static int sdp_bind_config(struct usb_configuration
*c
)
580 sdp_func
= memalign(CONFIG_SYS_CACHELINE_SIZE
, sizeof(*sdp_func
));
585 memset(sdp_func
, 0, sizeof(*sdp_func
));
587 sdp_func
->usb_function
.name
= "sdp";
588 sdp_func
->usb_function
.hs_descriptors
= sdp_runtime_descs
;
589 sdp_func
->usb_function
.descriptors
= sdp_runtime_descs
;
590 sdp_func
->usb_function
.bind
= sdp_bind
;
591 sdp_func
->usb_function
.unbind
= sdp_unbind
;
592 sdp_func
->usb_function
.set_alt
= sdp_set_alt
;
593 sdp_func
->usb_function
.get_alt
= sdp_get_alt
;
594 sdp_func
->usb_function
.disable
= sdp_disable
;
595 sdp_func
->usb_function
.strings
= sdp_generic_strings
;
596 sdp_func
->usb_function
.setup
= sdp_setup
;
598 status
= usb_add_function(c
, &sdp_func
->usb_function
);
603 int sdp_init(int controller_index
)
605 printf("SDP: initialize...\n");
606 while (!sdp_func
->configuration_done
) {
608 puts("\rCTRL+C - Operation aborted.\n");
613 usb_gadget_handle_interrupts(controller_index
);
619 static u32
sdp_jump_imxheader(void *address
)
621 flash_header_v2_t
*headerv2
= address
;
622 ulong (*entry
)(void);
624 if (headerv2
->header
.tag
!= IVT_HEADER_TAG
) {
625 printf("Header Tag is not an IMX image\n");
626 return SDP_ERROR_IMXHEADER
;
629 printf("Jumping to 0x%08x\n", headerv2
->entry
);
630 entry
= sdp_ptr(headerv2
->entry
);
633 /* The image probably never returns hence we won't reach that point */
637 static void sdp_handle_in_ep(void)
639 u8
*data
= sdp_func
->in_req
->buf
;
643 switch (sdp_func
->state
) {
644 case SDP_STATE_TX_SEC_CONF
:
645 debug("Report 3: HAB security\n");
648 status
= SDP_SECURITY_OPEN
;
649 memcpy(&data
[1], &status
, 4);
650 sdp_func
->in_req
->length
= 5;
651 usb_ep_queue(sdp_func
->in_ep
, sdp_func
->in_req
, 0);
652 sdp_func
->state
= SDP_STATE_TX_SEC_CONF_BUSY
;
655 case SDP_STATE_TX_STATUS
:
656 debug("Report 4: Status\n");
659 memcpy(&data
[1], &sdp_func
->error_status
, 4);
660 sdp_func
->in_req
->length
= 65;
661 usb_ep_queue(sdp_func
->in_ep
, sdp_func
->in_req
, 0);
662 sdp_func
->state
= SDP_STATE_TX_STATUS_BUSY
;
664 case SDP_STATE_TX_REGISTER
:
665 debug("Report 4: Register Values\n");
668 datalen
= sdp_func
->dnl_bytes_remaining
;
673 memcpy(&data
[1], sdp_ptr(sdp_func
->dnl_address
), datalen
);
674 sdp_func
->in_req
->length
= 65;
676 sdp_func
->dnl_bytes_remaining
-= datalen
;
677 sdp_func
->dnl_address
+= datalen
;
679 usb_ep_queue(sdp_func
->in_ep
, sdp_func
->in_req
, 0);
680 sdp_func
->state
= SDP_STATE_TX_REGISTER_BUSY
;
683 printf("Jumping to header at 0x%08x\n", sdp_func
->jmp_address
);
684 status
= sdp_jump_imxheader(sdp_ptr(sdp_func
->jmp_address
));
686 /* If imx header fails, try some U-Boot specific headers */
688 #ifdef CONFIG_SPL_BUILD
689 /* In SPL, allow jumps to U-Boot images */
690 struct spl_image_info spl_image
= {};
691 spl_parse_image_header(&spl_image
,
692 (struct image_header
*)sdp_func
->jmp_address
);
693 jump_to_image_no_args(&spl_image
);
695 /* In U-Boot, allow jumps to scripts */
696 source(sdp_func
->jmp_address
, "script@1");
700 sdp_func
->next_state
= SDP_STATE_IDLE
;
701 sdp_func
->error_status
= status
;
703 /* Only send Report 4 if there was an error */
705 sdp_func
->state
= SDP_STATE_TX_STATUS
;
707 sdp_func
->state
= SDP_STATE_IDLE
;
714 void sdp_handle(int controller_index
)
716 printf("SDP: handle requests...\n");
719 puts("\rCTRL+C - Operation aborted.\n");
724 usb_gadget_handle_interrupts(controller_index
);
730 int sdp_add(struct usb_configuration
*c
)
734 id
= usb_string_id(c
->cdev
);
737 strings_sdp_generic
[0].id
= id
;
738 sdp_intf_runtime
.iInterface
= id
;
740 debug("%s: cdev: %p gadget: %p gadget->ep0: %p\n", __func__
,
741 c
->cdev
, c
->cdev
->gadget
, c
->cdev
->gadget
->ep0
);
743 return sdp_bind_config(c
);
746 DECLARE_GADGET_BIND_CALLBACK(usb_dnl_sdp
, sdp_add
);