[U-Boot] [PATCH 0/7] Restructure the i.MX U-Boot documentation
This patch set is restructuring and cleaning up the current i.MX documentation included in the U-Boot doc directory.
The current i.MX documentation is in the root directory so we cannot easily check which one is i.MX related: http://git.denx.de/?p=u-boot/u-boot-imx.git;a=tree;f=doc;
This series is restructuring the documentation only relevant for i.MX devices in a new imx directory:
doc └── imx ├── common │ ├── imx25.txt │ ├── imx27.txt │ ├── imx5.txt │ ├── imx6.txt │ └── mxs.txt ├── hab │ └── habv4 │ ├── encrypted_boot.txt │ └── secure_boot.txt ├── misc │ └── sdp.txt └── mkimage ├── imximage.txt └── mxsimage.txt
Subsequent patches will include more content in HAB documentation.
Breno Lima (7): doc: imx: reorganize i.MX documentation doc: imx: Move SPD related info to the appropriate doc doc: imx: mkimage: reorganize i.MX mkimage documentation doc: imx: Reorganize i.MX SoC common documentation doc: imx: hab: Reorganize High Assurance Boot documentation doc: imx: misc: Reorganize miscellaneous documentation doc: imx: Improve i.MX documentation naming
doc/{README.imx25 => imx/common/imx25.txt} | 0 doc/{README.imx27 => imx/common/imx27.txt} | 0 doc/{README.imx5 => imx/common/imx5.txt} | 0 doc/{README.imx6 => imx/common/imx6.txt} | 25 ----------- doc/{README.mxs => imx/common/mxs.txt} | 0 doc/imx/hab/habv4/encrypted_boot.txt | 43 ++++++++++++++++++ .../hab/habv4/secure_boot.txt} | 44 ------------------- doc/{README.sdp => imx/misc/sdp.txt} | 22 +++++++++- .../mkimage/imximage.txt} | 0 .../mkimage/mxsimage.txt} | 0 10 files changed, 63 insertions(+), 71 deletions(-) rename doc/{README.imx25 => imx/common/imx25.txt} (100%) rename doc/{README.imx27 => imx/common/imx27.txt} (100%) rename doc/{README.imx5 => imx/common/imx5.txt} (100%) rename doc/{README.imx6 => imx/common/imx6.txt} (73%) rename doc/{README.mxs => imx/common/mxs.txt} (100%) create mode 100644 doc/imx/hab/habv4/encrypted_boot.txt rename doc/{README.mxc_hab => imx/hab/habv4/secure_boot.txt} (68%) rename doc/{README.sdp => imx/misc/sdp.txt} (82%) rename doc/{README.imximage => imx/mkimage/imximage.txt} (100%) rename doc/{README.mxsimage => imx/mkimage/mxsimage.txt} (100%)
Currently the U-Boot doc/ directory contains the following files that are only relevant for i.MX devices:
- doc/README.imx25 - doc/README.imx27 - doc/README.imx5 - doc/README.imx6 - doc/README.imximage - doc/README.mxc_hab - doc/README.mxs - doc/README.mxsimage - doc/README.sdp
Move all content to a common i.MX folder for a better documentation structure.
Signed-off-by: Breno Lima breno.lima@nxp.com --- doc/{ => imx}/README.imx25 | 0 doc/{ => imx}/README.imx27 | 0 doc/{ => imx}/README.imx5 | 0 doc/{ => imx}/README.imx6 | 0 doc/{ => imx}/README.imximage | 0 doc/{ => imx}/README.mxc_hab | 0 doc/{ => imx}/README.mxs | 0 doc/{ => imx}/README.mxsimage | 0 doc/{ => imx}/README.sdp | 0 9 files changed, 0 insertions(+), 0 deletions(-) rename doc/{ => imx}/README.imx25 (100%) rename doc/{ => imx}/README.imx27 (100%) rename doc/{ => imx}/README.imx5 (100%) rename doc/{ => imx}/README.imx6 (100%) rename doc/{ => imx}/README.imximage (100%) rename doc/{ => imx}/README.mxc_hab (100%) rename doc/{ => imx}/README.mxs (100%) rename doc/{ => imx}/README.mxsimage (100%) rename doc/{ => imx}/README.sdp (100%)
diff --git a/doc/README.imx25 b/doc/imx/README.imx25 similarity index 100% rename from doc/README.imx25 rename to doc/imx/README.imx25 diff --git a/doc/README.imx27 b/doc/imx/README.imx27 similarity index 100% rename from doc/README.imx27 rename to doc/imx/README.imx27 diff --git a/doc/README.imx5 b/doc/imx/README.imx5 similarity index 100% rename from doc/README.imx5 rename to doc/imx/README.imx5 diff --git a/doc/README.imx6 b/doc/imx/README.imx6 similarity index 100% rename from doc/README.imx6 rename to doc/imx/README.imx6 diff --git a/doc/README.imximage b/doc/imx/README.imximage similarity index 100% rename from doc/README.imximage rename to doc/imx/README.imximage diff --git a/doc/README.mxc_hab b/doc/imx/README.mxc_hab similarity index 100% rename from doc/README.mxc_hab rename to doc/imx/README.mxc_hab diff --git a/doc/README.mxs b/doc/imx/README.mxs similarity index 100% rename from doc/README.mxs rename to doc/imx/README.mxs diff --git a/doc/README.mxsimage b/doc/imx/README.mxsimage similarity index 100% rename from doc/README.mxsimage rename to doc/imx/README.mxsimage diff --git a/doc/README.sdp b/doc/imx/README.sdp similarity index 100% rename from doc/README.sdp rename to doc/imx/README.sdp
Currently the Serial Download Protocol tools and procedure are documented in two places:
- doc/imx/README.sdp - doc/imx/README.imx6
It is better to consolidate all SDP related information into README.sdp file, so move the content from README.imx6 to README.sdp.
Signed-off-by: Breno Lima breno.lima@nxp.com --- doc/imx/README.imx6 | 25 ------------------------- doc/imx/README.sdp | 22 ++++++++++++++++++++-- 2 files changed, 20 insertions(+), 27 deletions(-)
diff --git a/doc/imx/README.imx6 b/doc/imx/README.imx6 index b0644f8491..eab88353f6 100644 --- a/doc/imx/README.imx6 +++ b/doc/imx/README.imx6 @@ -88,28 +88,3 @@ Reading bank 4:
Word 0x00000002: 9f027772 00000004
-2. Using imx_usb_loader for first install with SPL --------------------------------------------------- - -imx_usb_loader is a very nice tool by Boundary Devices that -allow to install U-Boot without a JTAG debugger, using -the USB boot mode as described in the manual. It is -a replacement for Freescale's MFGTOOLS. - -The sources can be found here: - - https://github.com/boundarydevices/imx_usb_loader.git - -Booting in USB mode, the i.MX6 announces itself to the Linux Host as: - -Bus 001 Device 111: ID 15a2:0061 Freescale Semiconductor, Inc. - -imx_usb_loader is able to download a single file (u-boot.imx) -to the board. For boards without SPL support, it is enough to -issue the command: - - sudo ../imx_usb_loader/imx_usb -v u-boot.imx - -In order to load SPL and u-boot.img via imx_usb_loader tool, -please refer to doc/README.sdp. - diff --git a/doc/imx/README.sdp b/doc/imx/README.sdp index 178ea688a7..6ea6e41395 100644 --- a/doc/imx/README.sdp +++ b/doc/imx/README.sdp @@ -16,14 +16,19 @@ 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/boundarydevices/imx_usb_loader).
+imx_usb_loader is a very nice tool by Boundary Devices that allow to +install U-Boot without a JTAG debugger, using the USB boot mode as +described in the manual. It is a replacement for Freescale's +MFGTOOLS. + 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 ------ +1. Using imx_usb_loader for first install with SPL +--------------------------------------------------
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 @@ -98,3 +103,16 @@ With that SPL and U-Boot can be downloaded with a single invocation of imx_usb without arguments:
# imx_usb + +2. Using imx_usb_loader non-SPL images +--------------------------------------- + +Booting in USB mode, the i.MX6 announces itself to the Linux Host as: + +Bus 001 Device 111: ID 15a2:0061 Freescale Semiconductor, Inc. + +imx_usb_loader is able to download a single file (u-boot.imx) +to the board. For boards without SPL support, it is enough to +issue the command: + + sudo ../imx_usb_loader/imx_usb -v u-boot.imx
The following documents describe the image type used by the mkimage tool to generate U-Boot images for i.MX devices.
- README.imximage - README.mxsimage
Move all mkimage related document to doc/imx/mkimage for a better directory structure.
Signed-off-by: Breno Lima breno.lima@nxp.com --- doc/imx/{ => mkimage}/README.imximage | 0 doc/imx/{ => mkimage}/README.mxsimage | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename doc/imx/{ => mkimage}/README.imximage (100%) rename doc/imx/{ => mkimage}/README.mxsimage (100%)
diff --git a/doc/imx/README.imximage b/doc/imx/mkimage/README.imximage similarity index 100% rename from doc/imx/README.imximage rename to doc/imx/mkimage/README.imximage diff --git a/doc/imx/README.mxsimage b/doc/imx/mkimage/README.mxsimage similarity index 100% rename from doc/imx/README.mxsimage rename to doc/imx/mkimage/README.mxsimage
The following documents describe device details according to the i.MX family:
- README.imx25 - README.imx27 - README.imx5 - README.imx6 - README.mxs
Move all device common related document to doc/imx/common for a better directory structure.
Signed-off-by: Breno Lima breno.lima@nxp.com --- doc/imx/{ => common}/README.imx25 | 0 doc/imx/{ => common}/README.imx27 | 0 doc/imx/{ => common}/README.imx5 | 0 doc/imx/{ => common}/README.imx6 | 0 doc/imx/{ => common}/README.mxs | 0 5 files changed, 0 insertions(+), 0 deletions(-) rename doc/imx/{ => common}/README.imx25 (100%) rename doc/imx/{ => common}/README.imx27 (100%) rename doc/imx/{ => common}/README.imx5 (100%) rename doc/imx/{ => common}/README.imx6 (100%) rename doc/imx/{ => common}/README.mxs (100%)
diff --git a/doc/imx/README.imx25 b/doc/imx/common/README.imx25 similarity index 100% rename from doc/imx/README.imx25 rename to doc/imx/common/README.imx25 diff --git a/doc/imx/README.imx27 b/doc/imx/common/README.imx27 similarity index 100% rename from doc/imx/README.imx27 rename to doc/imx/common/README.imx27 diff --git a/doc/imx/README.imx5 b/doc/imx/common/README.imx5 similarity index 100% rename from doc/imx/README.imx5 rename to doc/imx/common/README.imx5 diff --git a/doc/imx/README.imx6 b/doc/imx/common/README.imx6 similarity index 100% rename from doc/imx/README.imx6 rename to doc/imx/common/README.imx6 diff --git a/doc/imx/README.mxs b/doc/imx/common/README.mxs similarity index 100% rename from doc/imx/README.mxs rename to doc/imx/common/README.mxs
The current High Assurance Boot document README.mxc_hab include details for the following features in a single file:
- HAB Secure Boot - HAB Encrypted Boot
Split HAB documentation in a specific directory for a cleaner documentation structure, subsequent patches will include more content in HAB documentation.
Signed-off-by: Breno Lima breno.lima@nxp.com --- doc/imx/hab/habv4/encrypted_boot.txt | 43 ++++++++++++++++++ .../habv4/secure_boot.txt} | 44 ------------------- 2 files changed, 43 insertions(+), 44 deletions(-) create mode 100644 doc/imx/hab/habv4/encrypted_boot.txt rename doc/imx/{README.mxc_hab => hab/habv4/secure_boot.txt} (68%)
diff --git a/doc/imx/hab/habv4/encrypted_boot.txt b/doc/imx/hab/habv4/encrypted_boot.txt new file mode 100644 index 0000000000..c59d204d38 --- /dev/null +++ b/doc/imx/hab/habv4/encrypted_boot.txt @@ -0,0 +1,43 @@ +1. Setup U-Boot Image for Encrypted Boot +---------------------------------------- +An authenticated U-Boot image is used as starting point for +Encrypted Boot. The image is encrypted by i.MX Code Signing +Tool (CST). The CST replaces only the image data of +u-boot-dtb.imx with the encrypted data. The Initial Vector Table, +DCD, and Boot data, remains in plaintext. + +The image data is encrypted with a Encryption Key (DEK). +Therefore, this key is needed to decrypt the data during the +booting process. The DEK is protected by wrapping it in a Blob, +which needs to be appended to the U-Boot image and specified in +the CSF file. + +The DEK blob is generated by an authenticated U-Boot image with +the dek_blob cmd enabled. The image used for DEK blob generation +needs to have the following configurations enabled in Kconfig: + +CONFIG_SECURE_BOOT=y +CONFIG_CMD_DEKBLOB=y + +Note: The encrypted boot feature is only supported by HABv4 or +greater. + +The dek_blob command then can be used to generate the DEK blob of +a DEK previously loaded in memory. The command is used as follows: + +dek_blob <DEK address> <Output Address> <Key Size in Bits> +example: dek_blob 0x10800000 0x10801000 192 + +The resulting DEK blob then is used to construct the encrypted +U-Boot image. Note that the blob needs to be transferred back +to the host.Then the following commands are used to construct +the final image. + +cat u-boot-dtb.imx csf-u-boot.bin > u-boot-signed.imx +objcopy -I binary -O binary --pad-to <blob_dst> --gap-fill=0x00 \ + u-boot-signed.imx u-boot-signed-pad.bin +cat u-boot-signed-pad.imx DEK_blob.bin > u-boot-encrypted.imx + + NOTE: u-boot-signed.bin needs to be padded to the value + equivalent to the address in which the DEK blob is specified + in the CSF. diff --git a/doc/imx/README.mxc_hab b/doc/imx/hab/habv4/secure_boot.txt similarity index 68% rename from doc/imx/README.mxc_hab rename to doc/imx/hab/habv4/secure_boot.txt index a40ebf3e84..ae68dc8040 100644 --- a/doc/imx/README.mxc_hab +++ b/doc/imx/hab/habv4/secure_boot.txt @@ -98,47 +98,3 @@ cat u-boot-ivt.img csf-u-boot.bin > u-boot-signed.img
These two signed binaries can be used on an i.MX in closed configuration when the according SRK Table Hash has been flashed. - -4. Setup U-Boot Image for Encrypted Boot ----------------------------------------- -An authenticated U-Boot image is used as starting point for -Encrypted Boot. The image is encrypted by i.MX Code Signing -Tool (CST). The CST replaces only the image data of -u-boot-dtb.imx with the encrypted data. The Initial Vector Table, -DCD, and Boot data, remains in plaintext. - -The image data is encrypted with a Encryption Key (DEK). -Therefore, this key is needed to decrypt the data during the -booting process. The DEK is protected by wrapping it in a Blob, -which needs to be appended to the U-Boot image and specified in -the CSF file. - -The DEK blob is generated by an authenticated U-Boot image with -the dek_blob cmd enabled. The image used for DEK blob generation -needs to have the following configurations enabled in Kconfig: - -CONFIG_SECURE_BOOT=y -CONFIG_CMD_DEKBLOB=y - -Note: The encrypted boot feature is only supported by HABv4 or -greater. - -The dek_blob command then can be used to generate the DEK blob of -a DEK previously loaded in memory. The command is used as follows: - -dek_blob <DEK address> <Output Address> <Key Size in Bits> -example: dek_blob 0x10800000 0x10801000 192 - -The resulting DEK blob then is used to construct the encrypted -U-Boot image. Note that the blob needs to be transferred back -to the host.Then the following commands are used to construct -the final image. - -cat u-boot-dtb.imx csf-u-boot.bin > u-boot-signed.imx -objcopy -I binary -O binary --pad-to <blob_dst> --gap-fill=0x00 \ - u-boot-signed.imx u-boot-signed-pad.bin -cat u-boot-signed-pad.imx DEK_blob.bin > u-boot-encrypted.imx - - NOTE: u-boot-signed.bin needs to be padded to the value - equivalent to the address in which the DEK blob is specified - in the CSF.
The Serial Download Protocol feature is availible in various i.MX SoCs.
Move README.sdp document to imx/misc directory.
Signed-off-by: Breno Lima breno.lima@nxp.com --- doc/imx/{ => misc}/README.sdp | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/imx/{ => misc}/README.sdp (100%)
diff --git a/doc/imx/README.sdp b/doc/imx/misc/README.sdp similarity index 100% rename from doc/imx/README.sdp rename to doc/imx/misc/README.sdp
There is no need to have README in all i.MX documents name. Remove README from i.MX docs name and add .txt file extension.
Signed-off-by: Breno Lima breno.lima@nxp.com Reviewed-by: Ye Li ye.li@nxp.com --- doc/imx/common/{README.imx25 => imx25.txt} | 0 doc/imx/common/{README.imx27 => imx27.txt} | 0 doc/imx/common/{README.imx5 => imx5.txt} | 0 doc/imx/common/{README.imx6 => imx6.txt} | 0 doc/imx/common/{README.mxs => mxs.txt} | 0 doc/imx/misc/{README.sdp => sdp.txt} | 0 doc/imx/mkimage/{README.imximage => imximage.txt} | 0 doc/imx/mkimage/{README.mxsimage => mxsimage.txt} | 0 8 files changed, 0 insertions(+), 0 deletions(-) rename doc/imx/common/{README.imx25 => imx25.txt} (100%) rename doc/imx/common/{README.imx27 => imx27.txt} (100%) rename doc/imx/common/{README.imx5 => imx5.txt} (100%) rename doc/imx/common/{README.imx6 => imx6.txt} (100%) rename doc/imx/common/{README.mxs => mxs.txt} (100%) rename doc/imx/misc/{README.sdp => sdp.txt} (100%) rename doc/imx/mkimage/{README.imximage => imximage.txt} (100%) rename doc/imx/mkimage/{README.mxsimage => mxsimage.txt} (100%)
diff --git a/doc/imx/common/README.imx25 b/doc/imx/common/imx25.txt similarity index 100% rename from doc/imx/common/README.imx25 rename to doc/imx/common/imx25.txt diff --git a/doc/imx/common/README.imx27 b/doc/imx/common/imx27.txt similarity index 100% rename from doc/imx/common/README.imx27 rename to doc/imx/common/imx27.txt diff --git a/doc/imx/common/README.imx5 b/doc/imx/common/imx5.txt similarity index 100% rename from doc/imx/common/README.imx5 rename to doc/imx/common/imx5.txt diff --git a/doc/imx/common/README.imx6 b/doc/imx/common/imx6.txt similarity index 100% rename from doc/imx/common/README.imx6 rename to doc/imx/common/imx6.txt diff --git a/doc/imx/common/README.mxs b/doc/imx/common/mxs.txt similarity index 100% rename from doc/imx/common/README.mxs rename to doc/imx/common/mxs.txt diff --git a/doc/imx/misc/README.sdp b/doc/imx/misc/sdp.txt similarity index 100% rename from doc/imx/misc/README.sdp rename to doc/imx/misc/sdp.txt diff --git a/doc/imx/mkimage/README.imximage b/doc/imx/mkimage/imximage.txt similarity index 100% rename from doc/imx/mkimage/README.imximage rename to doc/imx/mkimage/imximage.txt diff --git a/doc/imx/mkimage/README.mxsimage b/doc/imx/mkimage/mxsimage.txt similarity index 100% rename from doc/imx/mkimage/README.mxsimage rename to doc/imx/mkimage/mxsimage.txt
Hi Breno,
On Tue, Oct 9, 2018 at 10:54 PM Breno Matheus Lima breno.lima@nxp.com wrote:
This patch set is restructuring and cleaning up the current i.MX documentation included in the U-Boot doc directory.
The current i.MX documentation is in the root directory so we cannot easily check which one is i.MX related: http://git.denx.de/?p=u-boot/u-boot-imx.git;a=tree;f=doc;
This series is restructuring the documentation only relevant for i.MX devices in a new imx directory:
doc └── imx ├── common │ ├── imx25.txt │ ├── imx27.txt │ ├── imx5.txt │ ├── imx6.txt │ └── mxs.txt ├── hab │ └── habv4 │ ├── encrypted_boot.txt │ └── secure_boot.txt ├── misc │ └── sdp.txt └── mkimage ├── imximage.txt └── mxsimage.txt
Subsequent patches will include more content in HAB documentation.
Breno Lima (7): doc: imx: reorganize i.MX documentation doc: imx: Move SPD related info to the appropriate doc doc: imx: mkimage: reorganize i.MX mkimage documentation doc: imx: Reorganize i.MX SoC common documentation doc: imx: hab: Reorganize High Assurance Boot documentation doc: imx: misc: Reorganize miscellaneous documentation doc: imx: Improve i.MX documentation naming
I think this cleanup makes things better organized, thanks:
Reviewed-by: Fabio Estevam festevam@gmail.com
On 10/10/18 03:10, Breno Matheus Lima wrote:
This patch set is restructuring and cleaning up the current i.MX documentation included in the U-Boot doc directory.
The current i.MX documentation is in the root directory so we cannot easily check which one is i.MX related: http://git.denx.de/?p=u-boot/u-boot-imx.git;a=tree;f=doc;
This series is restructuring the documentation only relevant for i.MX devices in a new imx directory:
doc └── imx ├── common │ ├── imx25.txt │ ├── imx27.txt │ ├── imx5.txt │ ├── imx6.txt │ └── mxs.txt ├── hab │ └── habv4 │ ├── encrypted_boot.txt │ └── secure_boot.txt ├── misc │ └── sdp.txt └── mkimage ├── imximage.txt └── mxsimage.txt
Subsequent patches will include more content in HAB documentation.
Breno Lima (7): doc: imx: reorganize i.MX documentation doc: imx: Move SPD related info to the appropriate doc doc: imx: mkimage: reorganize i.MX mkimage documentation doc: imx: Reorganize i.MX SoC common documentation doc: imx: hab: Reorganize High Assurance Boot documentation doc: imx: misc: Reorganize miscellaneous documentation doc: imx: Improve i.MX documentation naming
doc/{README.imx25 => imx/common/imx25.txt} | 0 doc/{README.imx27 => imx/common/imx27.txt} | 0 doc/{README.imx5 => imx/common/imx5.txt} | 0 doc/{README.imx6 => imx/common/imx6.txt} | 25 ----------- doc/{README.mxs => imx/common/mxs.txt} | 0 doc/imx/hab/habv4/encrypted_boot.txt | 43 ++++++++++++++++++ .../hab/habv4/secure_boot.txt} | 44 ------------------- doc/{README.sdp => imx/misc/sdp.txt} | 22 +++++++++- .../mkimage/imximage.txt} | 0 .../mkimage/mxsimage.txt} | 0 10 files changed, 63 insertions(+), 71 deletions(-) rename doc/{README.imx25 => imx/common/imx25.txt} (100%) rename doc/{README.imx27 => imx/common/imx27.txt} (100%) rename doc/{README.imx5 => imx/common/imx5.txt} (100%) rename doc/{README.imx6 => imx/common/imx6.txt} (73%) rename doc/{README.mxs => imx/common/mxs.txt} (100%) create mode 100644 doc/imx/hab/habv4/encrypted_boot.txt rename doc/{README.mxc_hab => imx/hab/habv4/secure_boot.txt} (68%) rename doc/{README.sdp => imx/misc/sdp.txt} (82%) rename doc/{README.imximage => imx/mkimage/imximage.txt} (100%) rename doc/{README.mxsimage => imx/mkimage/mxsimage.txt} (100%)
Nice work !
Applied to u-boot-imx, thanks !
Best regards, Stefano Babic
participants (3)
-
Breno Matheus Lima -
Fabio Estevam -
Stefano Babic