1 // SPDX-License-Identifier: GPL-2.0+
3 * f_sdp.c -- USB HID Serial Download Protocol
5 * Copyright (C) 2017 Toradex
6 * Author: Stefan Agner <stefan.agner@toradex.com>
8 * This file implements the Serial Download Protocol (SDP) as specified in
9 * the i.MX 6 Reference Manual. The SDP is a USB HID based protocol and
10 * allows to download images directly to memory. The implementation
11 * works with the imx_loader (imx_usb) USB client software on host side.
13 * Not all commands are implemented, e.g. WRITE_REGISTER, DCD_WRITE and
14 * SKIP_DCD_HEADER are only stubs.
16 * Parts of the implementation are based on f_dfu and f_thor.
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;
105 u32 dnl_bytes_remaining;
107 bool always_send_status;
111 struct usb_request *req;
114 struct usb_ep *in_ep;
115 struct usb_request *in_req;
117 bool configuration_done;
120 static struct f_sdp *sdp_func;
122 static inline struct f_sdp *func_to_sdp(struct usb_function *f)
124 return container_of(f, struct f_sdp, usb_function);
127 static struct usb_interface_descriptor sdp_intf_runtime = {
128 .bLength = sizeof(sdp_intf_runtime),
129 .bDescriptorType = USB_DT_INTERFACE,
130 .bAlternateSetting = 0,
132 .bInterfaceClass = USB_CLASS_HID,
133 .bInterfaceSubClass = 0,
134 .bInterfaceProtocol = 0,
135 /* .iInterface = DYNAMIC */
138 /* HID configuration */
139 static struct usb_class_hid_descriptor sdp_hid_desc = {
140 .bLength = sizeof(sdp_hid_desc),
141 .bDescriptorType = USB_DT_CS_DEVICE,
143 .bcdCDC = __constant_cpu_to_le16(0x0110),
145 .bNumDescriptors = 1,
147 .bDescriptorType0 = USB_DT_HID_REPORT,
148 .wDescriptorLength0 = HID_USAGE_PAGE_LEN,
151 static struct usb_endpoint_descriptor in_desc = {
152 .bLength = USB_DT_ENDPOINT_SIZE,
153 .bDescriptorType = USB_DT_ENDPOINT, /*USB_DT_CS_ENDPOINT*/
155 .bEndpointAddress = 1 | USB_DIR_IN,
156 .bmAttributes = USB_ENDPOINT_XFER_INT,
157 .wMaxPacketSize = 64,
161 static struct usb_descriptor_header *sdp_runtime_descs[] = {
162 (struct usb_descriptor_header *)&sdp_intf_runtime,
163 (struct usb_descriptor_header *)&sdp_hid_desc,
164 (struct usb_descriptor_header *)&in_desc,
168 /* This is synchronized with what the SoC implementation reports */
169 static struct hid_report sdp_hid_report = {
171 0x06, 0x00, 0xff, /* Usage Page */
172 0x09, 0x01, /* Usage (Pointer?) */
173 0xa1, 0x01, /* Collection */
175 0x85, 0x01, /* Report ID */
176 0x19, 0x01, /* Usage Minimum */
177 0x29, 0x01, /* Usage Maximum */
178 0x15, 0x00, /* Local Minimum */
179 0x26, 0xFF, 0x00, /* Local Maximum? */
180 0x75, 0x08, /* Report Size */
181 0x95, 0x10, /* Report Count */
182 0x91, 0x02, /* Output Data */
184 0x85, 0x02, /* Report ID */
185 0x19, 0x01, /* Usage Minimum */
186 0x29, 0x01, /* Usage Maximum */
187 0x15, 0x00, /* Local Minimum */
188 0x26, 0xFF, 0x00, /* Local Maximum? */
189 0x75, 0x80, /* Report Size 128 */
190 0x95, 0x40, /* Report Count */
191 0x91, 0x02, /* Output Data */
193 0x85, 0x03, /* Report ID */
194 0x19, 0x01, /* Usage Minimum */
195 0x29, 0x01, /* Usage Maximum */
196 0x15, 0x00, /* Local Minimum */
197 0x26, 0xFF, 0x00, /* Local Maximum? */
198 0x75, 0x08, /* Report Size 8 */
199 0x95, 0x04, /* Report Count */
200 0x81, 0x02, /* Input Data */
202 0x85, 0x04, /* Report ID */
203 0x19, 0x01, /* Usage Minimum */
204 0x29, 0x01, /* Usage Maximum */
205 0x15, 0x00, /* Local Minimum */
206 0x26, 0xFF, 0x00, /* Local Maximum? */
207 0x75, 0x08, /* Report Size 8 */
208 0x95, 0x40, /* Report Count */
209 0x81, 0x02, /* Input Data */
214 static const char sdp_name[] = "Serial Downloader Protocol";
217 * static strings, in UTF-8
219 static struct usb_string strings_sdp_generic[] = {
221 { } /* end of list */
224 static struct usb_gadget_strings stringtab_sdp_generic = {
225 .language = 0x0409, /* en-us */
226 .strings = strings_sdp_generic,
229 static struct usb_gadget_strings *sdp_generic_strings[] = {
230 &stringtab_sdp_generic,
234 static inline void *sdp_ptr(u32 val)
236 return (void *)(uintptr_t)val;
239 static void sdp_rx_command_complete(struct usb_ep *ep, struct usb_request *req)
241 struct f_sdp *sdp = req->context;
242 int status = req->status;
247 pr_err("Status: %d\n", status);
252 pr_err("Unexpected report %d\n", report);
256 struct sdp_command *cmd = req->buf + 1;
258 debug("%s: command: %04x, addr: %08x, cnt: %u\n",
259 __func__, be16_to_cpu(cmd->cmd),
260 be32_to_cpu(cmd->addr), be32_to_cpu(cmd->cnt));
262 switch (be16_to_cpu(cmd->cmd)) {
263 case SDP_READ_REGISTER:
264 sdp->always_send_status = false;
265 sdp->error_status = 0x0;
267 sdp->state = SDP_STATE_TX_SEC_CONF;
268 sdp->dnl_address = be32_to_cpu(cmd->addr);
269 sdp->dnl_bytes_remaining = be32_to_cpu(cmd->cnt);
270 sdp->next_state = SDP_STATE_TX_REGISTER;
271 printf("Reading %d registers at 0x%08x... ",
272 sdp->dnl_bytes_remaining, sdp->dnl_address);
275 sdp->always_send_status = true;
276 sdp->error_status = SDP_WRITE_FILE_COMPLETE;
278 sdp->state = SDP_STATE_RX_FILE_DATA;
279 sdp->dnl_address = be32_to_cpu(cmd->addr);
280 sdp->dnl_bytes_remaining = be32_to_cpu(cmd->cnt);
281 sdp->dnl_bytes = sdp->dnl_bytes_remaining;
282 sdp->next_state = SDP_STATE_IDLE;
284 printf("Downloading file of size %d to 0x%08x... ",
285 sdp->dnl_bytes_remaining, sdp->dnl_address);
288 case SDP_ERROR_STATUS:
289 sdp->always_send_status = true;
290 sdp->error_status = 0;
292 sdp->state = SDP_STATE_TX_SEC_CONF;
293 sdp->next_state = SDP_STATE_IDLE;
296 sdp->always_send_status = true;
297 sdp->error_status = SDP_WRITE_REGISTER_COMPLETE;
299 sdp->state = SDP_STATE_RX_DCD_DATA;
300 sdp->dnl_bytes_remaining = be32_to_cpu(cmd->cnt);
301 sdp->next_state = SDP_STATE_IDLE;
303 case SDP_JUMP_ADDRESS:
304 sdp->always_send_status = false;
305 sdp->error_status = 0;
307 sdp->jmp_address = be32_to_cpu(cmd->addr);
308 sdp->state = SDP_STATE_TX_SEC_CONF;
309 sdp->next_state = SDP_STATE_JUMP;
311 case SDP_SKIP_DCD_HEADER:
312 sdp->always_send_status = true;
313 sdp->error_status = SDP_SKIP_DCD_HEADER_COMPLETE;
315 /* Ignore command, DCD not supported anyway */
316 sdp->state = SDP_STATE_TX_SEC_CONF;
317 sdp->next_state = SDP_STATE_IDLE;
320 pr_err("Unknown command: %04x\n", be16_to_cpu(cmd->cmd));
324 static void sdp_rx_data_complete(struct usb_ep *ep, struct usb_request *req)
326 struct f_sdp *sdp = req->context;
327 int status = req->status;
330 int datalen = req->length - 1;
333 pr_err("Status: %d\n", status);
338 pr_err("Unexpected report %d\n", report);
342 if (sdp->dnl_bytes_remaining < datalen) {
344 * Some USB stacks require to send a complete buffer as
345 * specified in the HID descriptor. This leads to longer
346 * transfers than the file length, no problem for us.
348 sdp->dnl_bytes_remaining = 0;
350 sdp->dnl_bytes_remaining -= datalen;
353 if (sdp->state == SDP_STATE_RX_FILE_DATA) {
354 memcpy(sdp_ptr(sdp->dnl_address), req->buf + 1, datalen);
355 sdp->dnl_address += datalen;
358 if (sdp->dnl_bytes_remaining)
361 #ifndef CONFIG_SPL_BUILD
362 env_set_hex("filesize", sdp->dnl_bytes);
366 switch (sdp->state) {
367 case SDP_STATE_RX_FILE_DATA:
368 sdp->state = SDP_STATE_TX_SEC_CONF;
370 case SDP_STATE_RX_DCD_DATA:
371 sdp->state = SDP_STATE_TX_SEC_CONF;
374 pr_err("Invalid state: %d\n", sdp->state);
378 static void sdp_tx_complete(struct usb_ep *ep, struct usb_request *req)
380 struct f_sdp *sdp = req->context;
381 int status = req->status;
384 pr_err("Status: %d\n", status);
388 switch (sdp->state) {
389 case SDP_STATE_TX_SEC_CONF_BUSY:
390 /* Not all commands require status report */
391 if (sdp->always_send_status || sdp->error_status)
392 sdp->state = SDP_STATE_TX_STATUS;
394 sdp->state = sdp->next_state;
397 case SDP_STATE_TX_STATUS_BUSY:
398 sdp->state = sdp->next_state;
400 case SDP_STATE_TX_REGISTER_BUSY:
401 if (sdp->dnl_bytes_remaining)
402 sdp->state = SDP_STATE_TX_REGISTER;
404 sdp->state = SDP_STATE_IDLE;
407 pr_err("Wrong State: %d\n", sdp->state);
408 sdp->state = SDP_STATE_IDLE;
411 debug("%s complete --> %d, %d/%d\n", ep->name,
412 status, req->actual, req->length);
415 static int sdp_setup(struct usb_function *f, const struct usb_ctrlrequest *ctrl)
417 struct usb_gadget *gadget = f->config->cdev->gadget;
418 struct usb_request *req = f->config->cdev->req;
419 struct f_sdp *sdp = f->config->cdev->req->context;
420 u16 len = le16_to_cpu(ctrl->wLength);
421 u16 w_value = le16_to_cpu(ctrl->wValue);
423 u8 req_type = ctrl->bRequestType & USB_TYPE_MASK;
425 debug("w_value: 0x%04x len: 0x%04x\n", w_value, len);
426 debug("req_type: 0x%02x ctrl->bRequest: 0x%02x sdp->state: %d\n",
427 req_type, ctrl->bRequest, sdp->state);
429 if (req_type == USB_TYPE_STANDARD) {
430 if (ctrl->bRequest == USB_REQ_GET_DESCRIPTOR) {
431 /* Send HID report descriptor */
432 value = min(len, (u16) sizeof(sdp_hid_report));
433 memcpy(req->buf, &sdp_hid_report, value);
434 sdp->configuration_done = true;
438 if (req_type == USB_TYPE_CLASS) {
439 int report = w_value & HID_REPORT_ID_MASK;
441 /* HID (SDP) request */
442 switch (ctrl->bRequest) {
443 case HID_REQ_SET_REPORT:
446 value = SDP_COMMAND_LEN + 1;
447 req->complete = sdp_rx_command_complete;
451 req->complete = sdp_rx_data_complete;
459 req->zero = value < len;
460 value = usb_ep_queue(gadget->ep0, req, 0);
462 debug("ep_queue --> %d\n", value);
470 static int sdp_bind(struct usb_configuration *c, struct usb_function *f)
472 struct usb_gadget *gadget = c->cdev->gadget;
473 struct usb_composite_dev *cdev = c->cdev;
474 struct f_sdp *sdp = func_to_sdp(f);
477 id = usb_interface_id(c, f);
480 sdp_intf_runtime.bInterfaceNumber = id;
484 /* allocate instance-specific endpoints */
485 ep = usb_ep_autoconfig(gadget, &in_desc);
491 sdp->in_ep = ep; /* Store IN EP for enabling @ setup */
493 cdev->req->context = sdp;
499 static void sdp_unbind(struct usb_configuration *c, struct usb_function *f)
505 static struct usb_request *alloc_ep_req(struct usb_ep *ep, unsigned length)
507 struct usb_request *req;
509 req = usb_ep_alloc_request(ep, 0);
513 req->length = length;
514 req->buf = memalign(CONFIG_SYS_CACHELINE_SIZE, length);
516 usb_ep_free_request(ep, req);
524 static struct usb_request *sdp_start_ep(struct usb_ep *ep)
526 struct usb_request *req;
528 req = alloc_ep_req(ep, 64);
529 debug("%s: ep:%p req:%p\n", __func__, ep, req);
534 memset(req->buf, 0, req->length);
535 req->complete = sdp_tx_complete;
539 static int sdp_set_alt(struct usb_function *f, unsigned intf, unsigned alt)
541 struct f_sdp *sdp = func_to_sdp(f);
542 struct usb_composite_dev *cdev = f->config->cdev;
545 debug("%s: intf: %d alt: %d\n", __func__, intf, alt);
547 result = usb_ep_enable(sdp->in_ep, &in_desc);
550 sdp->in_req = sdp_start_ep(sdp->in_ep);
551 sdp->in_req->context = sdp;
553 sdp->in_ep->driver_data = cdev; /* claim */
555 sdp->altsetting = alt;
556 sdp->state = SDP_STATE_IDLE;
561 static int sdp_get_alt(struct usb_function *f, unsigned intf)
563 struct f_sdp *sdp = func_to_sdp(f);
565 return sdp->altsetting;
568 static void sdp_disable(struct usb_function *f)
570 struct f_sdp *sdp = func_to_sdp(f);
572 usb_ep_disable(sdp->in_ep);
580 static int sdp_bind_config(struct usb_configuration *c)
585 sdp_func = memalign(CONFIG_SYS_CACHELINE_SIZE, sizeof(*sdp_func));
590 memset(sdp_func, 0, sizeof(*sdp_func));
592 sdp_func->usb_function.name = "sdp";
593 sdp_func->usb_function.hs_descriptors = sdp_runtime_descs;
594 sdp_func->usb_function.descriptors = sdp_runtime_descs;
595 sdp_func->usb_function.bind = sdp_bind;
596 sdp_func->usb_function.unbind = sdp_unbind;
597 sdp_func->usb_function.set_alt = sdp_set_alt;
598 sdp_func->usb_function.get_alt = sdp_get_alt;
599 sdp_func->usb_function.disable = sdp_disable;
600 sdp_func->usb_function.strings = sdp_generic_strings;
601 sdp_func->usb_function.setup = sdp_setup;
603 status = usb_add_function(c, &sdp_func->usb_function);
608 int sdp_init(int controller_index)
610 printf("SDP: initialize...\n");
611 while (!sdp_func->configuration_done) {
613 puts("\rCTRL+C - Operation aborted.\n");
618 usb_gadget_handle_interrupts(controller_index);
624 static u32 sdp_jump_imxheader(void *address)
626 flash_header_v2_t *headerv2 = address;
627 ulong (*entry)(void);
629 if (headerv2->header.tag != IVT_HEADER_TAG) {
630 printf("Header Tag is not an IMX image\n");
631 return SDP_ERROR_IMXHEADER;
634 printf("Jumping to 0x%08x\n", headerv2->entry);
635 entry = sdp_ptr(headerv2->entry);
638 /* The image probably never returns hence we won't reach that point */
642 #ifdef CONFIG_SPL_BUILD
643 #ifdef CONFIG_SPL_LOAD_FIT
644 static ulong sdp_fit_read(struct spl_load_info *load, ulong sector,
645 ulong count, void *buf)
647 debug("%s: sector %lx, count %lx, buf %lx\n",
648 __func__, sector, count, (ulong)buf);
649 memcpy(buf, (void *)(load->dev + sector), count);
655 static void sdp_handle_in_ep(struct spl_image_info *spl_image)
657 u8 *data = sdp_func->in_req->buf;
661 switch (sdp_func->state) {
662 case SDP_STATE_TX_SEC_CONF:
663 debug("Report 3: HAB security\n");
666 status = SDP_SECURITY_OPEN;
667 memcpy(&data[1], &status, 4);
668 sdp_func->in_req->length = 5;
669 usb_ep_queue(sdp_func->in_ep, sdp_func->in_req, 0);
670 sdp_func->state = SDP_STATE_TX_SEC_CONF_BUSY;
673 case SDP_STATE_TX_STATUS:
674 debug("Report 4: Status\n");
677 memcpy(&data[1], &sdp_func->error_status, 4);
678 sdp_func->in_req->length = 65;
679 usb_ep_queue(sdp_func->in_ep, sdp_func->in_req, 0);
680 sdp_func->state = SDP_STATE_TX_STATUS_BUSY;
682 case SDP_STATE_TX_REGISTER:
683 debug("Report 4: Register Values\n");
686 datalen = sdp_func->dnl_bytes_remaining;
691 memcpy(&data[1], sdp_ptr(sdp_func->dnl_address), datalen);
692 sdp_func->in_req->length = 65;
694 sdp_func->dnl_bytes_remaining -= datalen;
695 sdp_func->dnl_address += datalen;
697 usb_ep_queue(sdp_func->in_ep, sdp_func->in_req, 0);
698 sdp_func->state = SDP_STATE_TX_REGISTER_BUSY;
701 printf("Jumping to header at 0x%08x\n", sdp_func->jmp_address);
702 status = sdp_jump_imxheader(sdp_ptr(sdp_func->jmp_address));
704 /* If imx header fails, try some U-Boot specific headers */
706 #ifdef CONFIG_SPL_BUILD
707 image_header_t *header =
708 sdp_ptr(sdp_func->jmp_address);
709 #ifdef CONFIG_SPL_LOAD_FIT
710 if (image_get_magic(header) == FDT_MAGIC) {
711 struct spl_load_info load;
713 debug("Found FIT\n");
716 load.read = sdp_fit_read;
717 spl_load_simple_fit(spl_image, &load, 0,
723 /* In SPL, allow jumps to U-Boot images */
724 struct spl_image_info spl_image = {};
725 spl_parse_image_header(&spl_image, header);
726 jump_to_image_no_args(&spl_image);
728 /* In U-Boot, allow jumps to scripts */
729 image_source_script(sdp_func->jmp_address, "script@1");
733 sdp_func->next_state = SDP_STATE_IDLE;
734 sdp_func->error_status = status;
736 /* Only send Report 4 if there was an error */
738 sdp_func->state = SDP_STATE_TX_STATUS;
740 sdp_func->state = SDP_STATE_IDLE;
747 #ifndef CONFIG_SPL_BUILD
748 int sdp_handle(int controller_index)
750 int spl_sdp_handle(int controller_index, struct spl_image_info *spl_image)
753 printf("SDP: handle requests...\n");
756 puts("\rCTRL+C - Operation aborted.\n");
760 #ifdef CONFIG_SPL_BUILD
761 if (spl_image->flags & SPL_FIT_FOUND)
766 usb_gadget_handle_interrupts(controller_index);
768 #ifdef CONFIG_SPL_BUILD
769 sdp_handle_in_ep(spl_image);
771 sdp_handle_in_ep(NULL);
776 int sdp_add(struct usb_configuration *c)
780 id = usb_string_id(c->cdev);
783 strings_sdp_generic[0].id = id;
784 sdp_intf_runtime.iInterface = id;
786 debug("%s: cdev: %p gadget: %p gadget->ep0: %p\n", __func__,
787 c->cdev, c->cdev->gadget, c->cdev->gadget->ep0);
789 return sdp_bind_config(c);
792 DECLARE_GADGET_BIND_CALLBACK(usb_dnl_sdp, sdp_add);