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.
24 #include <linux/usb/ch9.h>
25 #include <linux/usb/gadget.h>
26 #include <linux/usb/composite.h>
36 #define HID_REPORT_ID_MASK 0x000000ff
41 #define HID_REQ_GET_REPORT 0x01
42 #define HID_REQ_GET_IDLE 0x02
43 #define HID_REQ_GET_PROTOCOL 0x03
44 #define HID_REQ_SET_REPORT 0x09
45 #define HID_REQ_SET_IDLE 0x0A
46 #define HID_REQ_SET_PROTOCOL 0x0B
48 #define HID_USAGE_PAGE_LEN 76
51 u8 usage_page[HID_USAGE_PAGE_LEN];
54 #define SDP_READ_REGISTER 0x0101
55 #define SDP_WRITE_REGISTER 0x0202
56 #define SDP_WRITE_FILE 0x0404
57 #define SDP_ERROR_STATUS 0x0505
58 #define SDP_DCD_WRITE 0x0a0a
59 #define SDP_JUMP_ADDRESS 0x0b0b
60 #define SDP_SKIP_DCD_HEADER 0x0c0c
62 #define SDP_SECURITY_CLOSED 0x12343412
63 #define SDP_SECURITY_OPEN 0x56787856
65 #define SDP_WRITE_FILE_COMPLETE 0x88888888
66 #define SDP_WRITE_REGISTER_COMPLETE 0x128A8A12
67 #define SDP_SKIP_DCD_HEADER_COMPLETE 0x900DD009
68 #define SDP_ERROR_IMXHEADER 0x000a0533
70 #define SDP_COMMAND_LEN 16
83 SDP_STATE_RX_DCD_DATA,
84 SDP_STATE_RX_FILE_DATA,
85 SDP_STATE_TX_SEC_CONF,
86 SDP_STATE_TX_SEC_CONF_BUSY,
87 SDP_STATE_TX_REGISTER,
88 SDP_STATE_TX_REGISTER_BUSY,
90 SDP_STATE_TX_STATUS_BUSY,
95 struct usb_function usb_function;
97 struct usb_descriptor_header **function;
100 enum sdp_state state;
101 enum sdp_state next_state;
103 u32 dnl_bytes_remaining;
105 bool always_send_status;
109 struct usb_request *req;
112 struct usb_ep *in_ep;
113 struct usb_request *in_req;
115 bool configuration_done;
118 static struct f_sdp *sdp_func;
120 static inline struct f_sdp *func_to_sdp(struct usb_function *f)
122 return container_of(f, struct f_sdp, usb_function);
125 static struct usb_interface_descriptor sdp_intf_runtime = {
126 .bLength = sizeof(sdp_intf_runtime),
127 .bDescriptorType = USB_DT_INTERFACE,
128 .bAlternateSetting = 0,
130 .bInterfaceClass = USB_CLASS_HID,
131 .bInterfaceSubClass = 0,
132 .bInterfaceProtocol = 0,
133 /* .iInterface = DYNAMIC */
136 /* HID configuration */
137 static struct usb_class_hid_descriptor sdp_hid_desc = {
138 .bLength = sizeof(sdp_hid_desc),
139 .bDescriptorType = USB_DT_CS_DEVICE,
141 .bcdCDC = __constant_cpu_to_le16(0x0110),
143 .bNumDescriptors = 1,
145 .bDescriptorType0 = USB_DT_HID_REPORT,
146 .wDescriptorLength0 = HID_USAGE_PAGE_LEN,
149 static struct usb_endpoint_descriptor in_desc = {
150 .bLength = USB_DT_ENDPOINT_SIZE,
151 .bDescriptorType = USB_DT_ENDPOINT, /*USB_DT_CS_ENDPOINT*/
153 .bEndpointAddress = 1 | USB_DIR_IN,
154 .bmAttributes = USB_ENDPOINT_XFER_INT,
155 .wMaxPacketSize = 64,
159 static struct usb_descriptor_header *sdp_runtime_descs[] = {
160 (struct usb_descriptor_header *)&sdp_intf_runtime,
161 (struct usb_descriptor_header *)&sdp_hid_desc,
162 (struct usb_descriptor_header *)&in_desc,
166 /* This is synchronized with what the SoC implementation reports */
167 static struct hid_report sdp_hid_report = {
169 0x06, 0x00, 0xff, /* Usage Page */
170 0x09, 0x01, /* Usage (Pointer?) */
171 0xa1, 0x01, /* Collection */
173 0x85, 0x01, /* Report ID */
174 0x19, 0x01, /* Usage Minimum */
175 0x29, 0x01, /* Usage Maximum */
176 0x15, 0x00, /* Local Minimum */
177 0x26, 0xFF, 0x00, /* Local Maximum? */
178 0x75, 0x08, /* Report Size */
179 0x95, 0x10, /* Report Count */
180 0x91, 0x02, /* Output Data */
182 0x85, 0x02, /* Report ID */
183 0x19, 0x01, /* Usage Minimum */
184 0x29, 0x01, /* Usage Maximum */
185 0x15, 0x00, /* Local Minimum */
186 0x26, 0xFF, 0x00, /* Local Maximum? */
187 0x75, 0x80, /* Report Size 128 */
188 0x95, 0x40, /* Report Count */
189 0x91, 0x02, /* Output Data */
191 0x85, 0x03, /* Report ID */
192 0x19, 0x01, /* Usage Minimum */
193 0x29, 0x01, /* Usage Maximum */
194 0x15, 0x00, /* Local Minimum */
195 0x26, 0xFF, 0x00, /* Local Maximum? */
196 0x75, 0x08, /* Report Size 8 */
197 0x95, 0x04, /* Report Count */
198 0x81, 0x02, /* Input Data */
200 0x85, 0x04, /* Report ID */
201 0x19, 0x01, /* Usage Minimum */
202 0x29, 0x01, /* Usage Maximum */
203 0x15, 0x00, /* Local Minimum */
204 0x26, 0xFF, 0x00, /* Local Maximum? */
205 0x75, 0x08, /* Report Size 8 */
206 0x95, 0x40, /* Report Count */
207 0x81, 0x02, /* Input Data */
212 static const char sdp_name[] = "Serial Downloader Protocol";
215 * static strings, in UTF-8
217 static struct usb_string strings_sdp_generic[] = {
219 { } /* end of list */
222 static struct usb_gadget_strings stringtab_sdp_generic = {
223 .language = 0x0409, /* en-us */
224 .strings = strings_sdp_generic,
227 static struct usb_gadget_strings *sdp_generic_strings[] = {
228 &stringtab_sdp_generic,
232 static inline void *sdp_ptr(u32 val)
234 return (void *)(uintptr_t)val;
237 static void sdp_rx_command_complete(struct usb_ep *ep, struct usb_request *req)
239 struct f_sdp *sdp = req->context;
240 int status = req->status;
245 pr_err("Status: %d\n", status);
250 pr_err("Unexpected report %d\n", report);
254 struct sdp_command *cmd = req->buf + 1;
256 debug("%s: command: %04x, addr: %08x, cnt: %u\n",
257 __func__, be16_to_cpu(cmd->cmd),
258 be32_to_cpu(cmd->addr), be32_to_cpu(cmd->cnt));
260 switch (be16_to_cpu(cmd->cmd)) {
261 case SDP_READ_REGISTER:
262 sdp->always_send_status = false;
263 sdp->error_status = 0x0;
265 sdp->state = SDP_STATE_TX_SEC_CONF;
266 sdp->dnl_address = be32_to_cpu(cmd->addr);
267 sdp->dnl_bytes_remaining = be32_to_cpu(cmd->cnt);
268 sdp->next_state = SDP_STATE_TX_REGISTER;
269 printf("Reading %d registers at 0x%08x... ",
270 sdp->dnl_bytes_remaining, sdp->dnl_address);
273 sdp->always_send_status = true;
274 sdp->error_status = SDP_WRITE_FILE_COMPLETE;
276 sdp->state = SDP_STATE_RX_FILE_DATA;
277 sdp->dnl_address = be32_to_cpu(cmd->addr);
278 sdp->dnl_bytes_remaining = be32_to_cpu(cmd->cnt);
279 sdp->next_state = SDP_STATE_IDLE;
281 printf("Downloading file of size %d to 0x%08x... ",
282 sdp->dnl_bytes_remaining, sdp->dnl_address);
285 case SDP_ERROR_STATUS:
286 sdp->always_send_status = true;
287 sdp->error_status = 0;
289 sdp->state = SDP_STATE_TX_SEC_CONF;
290 sdp->next_state = SDP_STATE_IDLE;
293 sdp->always_send_status = true;
294 sdp->error_status = SDP_WRITE_REGISTER_COMPLETE;
296 sdp->state = SDP_STATE_RX_DCD_DATA;
297 sdp->dnl_bytes_remaining = be32_to_cpu(cmd->cnt);
298 sdp->next_state = SDP_STATE_IDLE;
300 case SDP_JUMP_ADDRESS:
301 sdp->always_send_status = false;
302 sdp->error_status = 0;
304 sdp->jmp_address = be32_to_cpu(cmd->addr);
305 sdp->state = SDP_STATE_TX_SEC_CONF;
306 sdp->next_state = SDP_STATE_JUMP;
308 case SDP_SKIP_DCD_HEADER:
309 sdp->always_send_status = true;
310 sdp->error_status = SDP_SKIP_DCD_HEADER_COMPLETE;
312 /* Ignore command, DCD not supported anyway */
313 sdp->state = SDP_STATE_TX_SEC_CONF;
314 sdp->next_state = SDP_STATE_IDLE;
317 pr_err("Unknown command: %04x\n", be16_to_cpu(cmd->cmd));
321 static void sdp_rx_data_complete(struct usb_ep *ep, struct usb_request *req)
323 struct f_sdp *sdp = req->context;
324 int status = req->status;
327 int datalen = req->length - 1;
330 pr_err("Status: %d\n", status);
335 pr_err("Unexpected report %d\n", report);
339 if (sdp->dnl_bytes_remaining < datalen) {
341 * Some USB stacks require to send a complete buffer as
342 * specified in the HID descriptor. This leads to longer
343 * transfers than the file length, no problem for us.
345 sdp->dnl_bytes_remaining = 0;
347 sdp->dnl_bytes_remaining -= datalen;
350 if (sdp->state == SDP_STATE_RX_FILE_DATA) {
351 memcpy(sdp_ptr(sdp->dnl_address), req->buf + 1, datalen);
352 sdp->dnl_address += datalen;
355 if (sdp->dnl_bytes_remaining)
360 switch (sdp->state) {
361 case SDP_STATE_RX_FILE_DATA:
362 sdp->state = SDP_STATE_TX_SEC_CONF;
364 case SDP_STATE_RX_DCD_DATA:
365 sdp->state = SDP_STATE_TX_SEC_CONF;
368 pr_err("Invalid state: %d\n", sdp->state);
372 static void sdp_tx_complete(struct usb_ep *ep, struct usb_request *req)
374 struct f_sdp *sdp = req->context;
375 int status = req->status;
378 pr_err("Status: %d\n", status);
382 switch (sdp->state) {
383 case SDP_STATE_TX_SEC_CONF_BUSY:
384 /* Not all commands require status report */
385 if (sdp->always_send_status || sdp->error_status)
386 sdp->state = SDP_STATE_TX_STATUS;
388 sdp->state = sdp->next_state;
391 case SDP_STATE_TX_STATUS_BUSY:
392 sdp->state = sdp->next_state;
394 case SDP_STATE_TX_REGISTER_BUSY:
395 if (sdp->dnl_bytes_remaining)
396 sdp->state = SDP_STATE_TX_REGISTER;
398 sdp->state = SDP_STATE_IDLE;
401 pr_err("Wrong State: %d\n", sdp->state);
402 sdp->state = SDP_STATE_IDLE;
405 debug("%s complete --> %d, %d/%d\n", ep->name,
406 status, req->actual, req->length);
409 static int sdp_setup(struct usb_function *f, const struct usb_ctrlrequest *ctrl)
411 struct usb_gadget *gadget = f->config->cdev->gadget;
412 struct usb_request *req = f->config->cdev->req;
413 struct f_sdp *sdp = f->config->cdev->req->context;
414 u16 len = le16_to_cpu(ctrl->wLength);
415 u16 w_value = le16_to_cpu(ctrl->wValue);
417 u8 req_type = ctrl->bRequestType & USB_TYPE_MASK;
419 debug("w_value: 0x%04x len: 0x%04x\n", w_value, len);
420 debug("req_type: 0x%02x ctrl->bRequest: 0x%02x sdp->state: %d\n",
421 req_type, ctrl->bRequest, sdp->state);
423 if (req_type == USB_TYPE_STANDARD) {
424 if (ctrl->bRequest == USB_REQ_GET_DESCRIPTOR) {
425 /* Send HID report descriptor */
426 value = min(len, (u16) sizeof(sdp_hid_report));
427 memcpy(req->buf, &sdp_hid_report, value);
428 sdp->configuration_done = true;
432 if (req_type == USB_TYPE_CLASS) {
433 int report = w_value & HID_REPORT_ID_MASK;
435 /* HID (SDP) request */
436 switch (ctrl->bRequest) {
437 case HID_REQ_SET_REPORT:
440 value = SDP_COMMAND_LEN + 1;
441 req->complete = sdp_rx_command_complete;
445 req->complete = sdp_rx_data_complete;
453 req->zero = value < len;
454 value = usb_ep_queue(gadget->ep0, req, 0);
456 debug("ep_queue --> %d\n", value);
464 static int sdp_bind(struct usb_configuration *c, struct usb_function *f)
466 struct usb_gadget *gadget = c->cdev->gadget;
467 struct usb_composite_dev *cdev = c->cdev;
468 struct f_sdp *sdp = func_to_sdp(f);
471 id = usb_interface_id(c, f);
474 sdp_intf_runtime.bInterfaceNumber = id;
478 /* allocate instance-specific endpoints */
479 ep = usb_ep_autoconfig(gadget, &in_desc);
485 sdp->in_ep = ep; /* Store IN EP for enabling @ setup */
487 cdev->req->context = sdp;
493 static void sdp_unbind(struct usb_configuration *c, struct usb_function *f)
499 static struct usb_request *alloc_ep_req(struct usb_ep *ep, unsigned length)
501 struct usb_request *req;
503 req = usb_ep_alloc_request(ep, 0);
507 req->length = length;
508 req->buf = memalign(CONFIG_SYS_CACHELINE_SIZE, length);
510 usb_ep_free_request(ep, req);
518 static struct usb_request *sdp_start_ep(struct usb_ep *ep)
520 struct usb_request *req;
522 req = alloc_ep_req(ep, 64);
523 debug("%s: ep:%p req:%p\n", __func__, ep, req);
528 memset(req->buf, 0, req->length);
529 req->complete = sdp_tx_complete;
533 static int sdp_set_alt(struct usb_function *f, unsigned intf, unsigned alt)
535 struct f_sdp *sdp = func_to_sdp(f);
536 struct usb_composite_dev *cdev = f->config->cdev;
539 debug("%s: intf: %d alt: %d\n", __func__, intf, alt);
541 result = usb_ep_enable(sdp->in_ep, &in_desc);
544 sdp->in_req = sdp_start_ep(sdp->in_ep);
545 sdp->in_req->context = sdp;
547 sdp->in_ep->driver_data = cdev; /* claim */
549 sdp->altsetting = alt;
550 sdp->state = SDP_STATE_IDLE;
555 static int sdp_get_alt(struct usb_function *f, unsigned intf)
557 struct f_sdp *sdp = func_to_sdp(f);
559 return sdp->altsetting;
562 static void sdp_disable(struct usb_function *f)
564 struct f_sdp *sdp = func_to_sdp(f);
566 usb_ep_disable(sdp->in_ep);
574 static int sdp_bind_config(struct usb_configuration *c)
579 sdp_func = memalign(CONFIG_SYS_CACHELINE_SIZE, sizeof(*sdp_func));
584 memset(sdp_func, 0, sizeof(*sdp_func));
586 sdp_func->usb_function.name = "sdp";
587 sdp_func->usb_function.hs_descriptors = sdp_runtime_descs;
588 sdp_func->usb_function.descriptors = sdp_runtime_descs;
589 sdp_func->usb_function.bind = sdp_bind;
590 sdp_func->usb_function.unbind = sdp_unbind;
591 sdp_func->usb_function.set_alt = sdp_set_alt;
592 sdp_func->usb_function.get_alt = sdp_get_alt;
593 sdp_func->usb_function.disable = sdp_disable;
594 sdp_func->usb_function.strings = sdp_generic_strings;
595 sdp_func->usb_function.setup = sdp_setup;
597 status = usb_add_function(c, &sdp_func->usb_function);
602 int sdp_init(int controller_index)
604 printf("SDP: initialize...\n");
605 while (!sdp_func->configuration_done) {
607 puts("\rCTRL+C - Operation aborted.\n");
612 usb_gadget_handle_interrupts(controller_index);
618 static u32 sdp_jump_imxheader(void *address)
620 flash_header_v2_t *headerv2 = address;
621 ulong (*entry)(void);
623 if (headerv2->header.tag != IVT_HEADER_TAG) {
624 printf("Header Tag is not an IMX image\n");
625 return SDP_ERROR_IMXHEADER;
628 printf("Jumping to 0x%08x\n", headerv2->entry);
629 entry = sdp_ptr(headerv2->entry);
632 /* The image probably never returns hence we won't reach that point */
636 static void sdp_handle_in_ep(void)
638 u8 *data = sdp_func->in_req->buf;
642 switch (sdp_func->state) {
643 case SDP_STATE_TX_SEC_CONF:
644 debug("Report 3: HAB security\n");
647 status = SDP_SECURITY_OPEN;
648 memcpy(&data[1], &status, 4);
649 sdp_func->in_req->length = 5;
650 usb_ep_queue(sdp_func->in_ep, sdp_func->in_req, 0);
651 sdp_func->state = SDP_STATE_TX_SEC_CONF_BUSY;
654 case SDP_STATE_TX_STATUS:
655 debug("Report 4: Status\n");
658 memcpy(&data[1], &sdp_func->error_status, 4);
659 sdp_func->in_req->length = 65;
660 usb_ep_queue(sdp_func->in_ep, sdp_func->in_req, 0);
661 sdp_func->state = SDP_STATE_TX_STATUS_BUSY;
663 case SDP_STATE_TX_REGISTER:
664 debug("Report 4: Register Values\n");
667 datalen = sdp_func->dnl_bytes_remaining;
672 memcpy(&data[1], sdp_ptr(sdp_func->dnl_address), datalen);
673 sdp_func->in_req->length = 65;
675 sdp_func->dnl_bytes_remaining -= datalen;
676 sdp_func->dnl_address += datalen;
678 usb_ep_queue(sdp_func->in_ep, sdp_func->in_req, 0);
679 sdp_func->state = SDP_STATE_TX_REGISTER_BUSY;
682 printf("Jumping to header at 0x%08x\n", sdp_func->jmp_address);
683 status = sdp_jump_imxheader(sdp_ptr(sdp_func->jmp_address));
685 /* If imx header fails, try some U-Boot specific headers */
687 #ifdef CONFIG_SPL_BUILD
688 /* In SPL, allow jumps to U-Boot images */
689 struct spl_image_info spl_image = {};
690 spl_parse_image_header(&spl_image,
691 (struct image_header *)sdp_func->jmp_address);
692 jump_to_image_no_args(&spl_image);
694 /* In U-Boot, allow jumps to scripts */
695 source(sdp_func->jmp_address, "script@1");
699 sdp_func->next_state = SDP_STATE_IDLE;
700 sdp_func->error_status = status;
702 /* Only send Report 4 if there was an error */
704 sdp_func->state = SDP_STATE_TX_STATUS;
706 sdp_func->state = SDP_STATE_IDLE;
713 void sdp_handle(int controller_index)
715 printf("SDP: handle requests...\n");
718 puts("\rCTRL+C - Operation aborted.\n");
723 usb_gadget_handle_interrupts(controller_index);
729 int sdp_add(struct usb_configuration *c)
733 id = usb_string_id(c->cdev);
736 strings_sdp_generic[0].id = id;
737 sdp_intf_runtime.iInterface = id;
739 debug("%s: cdev: %p gadget: %p gadget->ep0: %p\n", __func__,
740 c->cdev, c->cdev->gadget, c->cdev->gadget->ep0);
742 return sdp_bind_config(c);
745 DECLARE_GADGET_BIND_CALLBACK(usb_dnl_sdp, sdp_add);