Message ID | 20170816180057.8768-7-stefan@agner.ch |
---|---|
State | Accepted |
Commit | f9c39d95f16e62a39d751d9b886f673c6d1e90b8 |
Delegated to: | Stefano Babic |
Headers | show |
Hi Stefan, > From: Stefan Agner <stefan.agner@toradex.com> > > Document the U-Boot Serial Download Protocol implementation and > some typical use cases. Thanks for providing the description :-) Reviewed-by: Ćukasz Majewski <lukma@denx.de> > > Signed-off-by: Stefan Agner <stefan.agner@toradex.com> > --- > This ended up to be almost more a imx_usb documentation. But there > is really not much to document from a U-Boot side since actual usage > heavily depends on host side tooling... > > This assumes that the necessary changes will get merged upstream: > https://github.com/toradex/imx_loader/tree/imx_usb_batch_mode_refactored > > > Changes in v2: None > > doc/README.sdp | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 100 insertions(+) > create mode 100644 doc/README.sdp > > diff --git a/doc/README.sdp b/doc/README.sdp > new file mode 100644 > index 0000000000..9b438c0746 > --- /dev/null > +++ b/doc/README.sdp > @@ -0,0 +1,100 @@ > +------------- > +SDP in U-Boot > +------------- > + > +SDP stands for serial download protocol. It is the protocol used in NXP's > +i.MX SoCs ROM Serial Downloader and provides means to download a program > +image to the chip over USB and UART serial connection. > + > +The implementation in U-Boot uses the USB Downloader Gadget (g_dnl) to > +provide a SDP implementation over USB. This allows to download program > +images to the target in SPL/U-Boot using the same protocol/tooling the > +SoC's recovery mechanism is using. > + > +The SDP protocol over USB is a USB HID class protocol. USB HID class > +protocols allow to access a USB device without OS specific drivers. The > +U-Boot implementation has primarly been tested using the open source > +imx_loader utility (https://github.com/toradex/imx_loader). > + > +The host side utilities are typically capable to interpret the i.MX > +specific image header (see doc/README.imximage). There are extensions > +for imx_loader's imx_usb utility which allow to interpret the U-Boot > +specific legacy image format (see mkimage(1)). Also the U-Boot side > +support beside the i.MX specific header the U-Boot legacy header. > + > +Usage > +----- > + > +This implementation can be started in U-Boot using the sdp command > +(CONFIG_CMD_USB_SDP) or in SPL if Serial Downloader boot mode has been > +detected (CONFIG_SPL_USB_SDP_SUPPORT). > + > +A typical use case is downloading full U-Boot after SPL has been > +downloaded through the boot ROM's Serial Downloader. Using boot mode > +detection the SPL will run the SDP implementation automatically in > +this case: > + > + # imx_usb SPL > + > +Targets Serial Console: > + > + Trying to boot from USB SDP > + SDP: initialize... > + SDP: handle requests... > + > +At this point the SPL reenumerated as a new HID device and emulating > +the boot ROM's SDP protocol. The USB VID/PID will depend on standard > +U-Boot configurations CONFIG_G_DNL_(VENDOR|PRODUCT)_NUM. Make sure > +imx_usb is aware of the USB VID/PID for your device by adding a > +configuration entry in imx_usb.conf: > + > + 0x1b67:0x4fff, mx6_usb_sdp_spl.conf > + > +And the device specific configuration file mx6_usb_sdp_spl.conf: > + > + mx6_spl_sdp > + hid,uboot_header,1024,0x910000,0x10000000,1G,0x00900000,0x40000 > + > +This allows to download the regular U-Boot with legacy image headers > +(u-boot.img) using a second invocation of imx_usb: > + > + # imx_usb u-boot.img > + > +Furthermore, when U-Boot is running the sdp command can be used to > +download and run scripts: > + > + # imx_usb script.scr > + > +imx_usb configuration files can be also used to download multiple > +files and of arbitrary types, e.g. > + > + mx6_usb_sdp_uboot > + hid,1024,0x10000000,1G,0x00907000,0x31000 > + full.itb:load 0x12100000 > + boot.scr:load 0x12000000,jump 0x12000000 > + > +There is also a batch mode which allows imx_usb to handle multiple > +consecutive reenumerations by adding multiple VID/PID specifications > +in imx_usb.conf: > + > + 0x15a2:0x0061, mx6_usb_rom.conf, 0x1b67:0x4fff, mx6_usb_sdp_spl.conf > + > +In this mode the file to download (imx_usb job) needs to be specified > +in the configuration files. > + > +mx6_usb_rom.conf: > + > + mx6_qsb > + hid,1024,0x910000,0x10000000,1G,0x00900000,0x40000 > + SPL:jump header2 > + > +mx6_usb_sdp_spl.conf: > + > + mx6_spl_sdp > + hid,uboot_header,1024,0x10000000,1G,0x00907000,0x31000 > + u-boot.img:jump header2 > + > +With that SPL and U-Boot can be downloaded with a single invocation > +of imx_usb without arguments: > + > + # imx_usb >
diff --git a/doc/README.sdp b/doc/README.sdp new file mode 100644 index 0000000000..9b438c0746 --- /dev/null +++ b/doc/README.sdp @@ -0,0 +1,100 @@ +------------- +SDP in U-Boot +------------- + +SDP stands for serial download protocol. It is the protocol used in NXP's +i.MX SoCs ROM Serial Downloader and provides means to download a program +image to the chip over USB and UART serial connection. + +The implementation in U-Boot uses the USB Downloader Gadget (g_dnl) to +provide a SDP implementation over USB. This allows to download program +images to the target in SPL/U-Boot using the same protocol/tooling the +SoC's recovery mechanism is using. + +The SDP protocol over USB is a USB HID class protocol. USB HID class +protocols allow to access a USB device without OS specific drivers. The +U-Boot implementation has primarly been tested using the open source +imx_loader utility (https://github.com/toradex/imx_loader). + +The host side utilities are typically capable to interpret the i.MX +specific image header (see doc/README.imximage). There are extensions +for imx_loader's imx_usb utility which allow to interpret the U-Boot +specific legacy image format (see mkimage(1)). Also the U-Boot side +support beside the i.MX specific header the U-Boot legacy header. + +Usage +----- + +This implementation can be started in U-Boot using the sdp command +(CONFIG_CMD_USB_SDP) or in SPL if Serial Downloader boot mode has been +detected (CONFIG_SPL_USB_SDP_SUPPORT). + +A typical use case is downloading full U-Boot after SPL has been +downloaded through the boot ROM's Serial Downloader. Using boot mode +detection the SPL will run the SDP implementation automatically in +this case: + + # imx_usb SPL + +Targets Serial Console: + + Trying to boot from USB SDP + SDP: initialize... + SDP: handle requests... + +At this point the SPL reenumerated as a new HID device and emulating +the boot ROM's SDP protocol. The USB VID/PID will depend on standard +U-Boot configurations CONFIG_G_DNL_(VENDOR|PRODUCT)_NUM. Make sure +imx_usb is aware of the USB VID/PID for your device by adding a +configuration entry in imx_usb.conf: + + 0x1b67:0x4fff, mx6_usb_sdp_spl.conf + +And the device specific configuration file mx6_usb_sdp_spl.conf: + + mx6_spl_sdp + hid,uboot_header,1024,0x910000,0x10000000,1G,0x00900000,0x40000 + +This allows to download the regular U-Boot with legacy image headers +(u-boot.img) using a second invocation of imx_usb: + + # imx_usb u-boot.img + +Furthermore, when U-Boot is running the sdp command can be used to +download and run scripts: + + # imx_usb script.scr + +imx_usb configuration files can be also used to download multiple +files and of arbitrary types, e.g. + + mx6_usb_sdp_uboot + hid,1024,0x10000000,1G,0x00907000,0x31000 + full.itb:load 0x12100000 + boot.scr:load 0x12000000,jump 0x12000000 + +There is also a batch mode which allows imx_usb to handle multiple +consecutive reenumerations by adding multiple VID/PID specifications +in imx_usb.conf: + + 0x15a2:0x0061, mx6_usb_rom.conf, 0x1b67:0x4fff, mx6_usb_sdp_spl.conf + +In this mode the file to download (imx_usb job) needs to be specified +in the configuration files. + +mx6_usb_rom.conf: + + mx6_qsb + hid,1024,0x910000,0x10000000,1G,0x00900000,0x40000 + SPL:jump header2 + +mx6_usb_sdp_spl.conf: + + mx6_spl_sdp + hid,uboot_header,1024,0x10000000,1G,0x00907000,0x31000 + u-boot.img:jump header2 + +With that SPL and U-Boot can be downloaded with a single invocation +of imx_usb without arguments: + + # imx_usb