diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.fdt-control | 20 | ||||
| -rw-r--r-- | doc/README.mxs | 26 | ||||
| -rw-r--r-- | doc/README.scrapyard | 31 | ||||
| -rw-r--r-- | doc/driver-model/README.txt | 238 | ||||
| -rw-r--r-- | doc/uImage.FIT/beaglebone_vboot.txt | 608 | ||||
| -rw-r--r-- | doc/uImage.FIT/howto.txt | 5 | ||||
| -rw-r--r-- | doc/uImage.FIT/signature.txt | 6 |
7 files changed, 904 insertions, 30 deletions
diff --git a/doc/README.fdt-control b/doc/README.fdt-control index 86bae6816d..d8fe4a826f 100644 --- a/doc/README.fdt-control +++ b/doc/README.fdt-control @@ -66,11 +66,11 @@ Tools To use this feature you will need to get the device tree compiler here: - git://jdl.com/software/dtc.git + git://git.kernel.org/pub/scm/utils/dtc/dtc.git For example: - $ git clone git://jdl.com/software/dtc.git + $ git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git $ cd dtc $ make $ sudo make install @@ -122,7 +122,8 @@ This should include your CPU or SOC's device tree file, placed in arch/<arch>/dts, and then make any adjustments required. If CONFIG_OF_EMBED is defined, then it will be picked up and built into -the U-Boot image (including u-boot.bin). +the U-Boot image (including u-boot.bin). This is suitable for debugging +and development only and is not recommended for production devices. If CONFIG_OF_SEPARATE is defined, then it will be built and placed in a u-boot.dtb file alongside u-boot.bin. A common approach is then to @@ -130,7 +131,10 @@ join the two: cat u-boot.bin u-boot.dtb >image.bin -and then flash image.bin onto your board. +and then flash image.bin onto your board. Note that U-Boot creates +u-boot-dtb.bin which does the above step for you also. If you are using +CONFIG_SPL_FRAMEWORK, then u-boot.img will be built to include the device +tree binary. If CONFIG_OF_HOSTFILE is defined, then it will be read from a file on startup. This is only useful for sandbox. Use the -d flag to U-Boot to @@ -138,6 +142,14 @@ specify the file to read. You cannot use more than one of these options at the same time. +To use a device tree file that you have compiled yourself, pass +EXT_DTB=<filename> to 'make', as in: + + make EXT_DTB=boot/am335x-boneblack-pubkey.dtb + +Then U-Boot will copy that file to u-boot.dtb, put it in the .img file +if used, and u-boot-dtb.bin. + If you wish to put the fdt at a different address in memory, you can define the "fdtcontroladdr" environment variable. This is the hex address of the fdt binary blob, and will override either of the options. diff --git a/doc/README.mxs b/doc/README.mxs index 0235a5aeaf..ed2e568856 100644 --- a/doc/README.mxs +++ b/doc/README.mxs @@ -23,6 +23,7 @@ Contents 2) Compiling U-Boot for a MXS based board 3) Installation of U-Boot for a MXS based board to SD card 4) Installation of U-Boot into NAND flash on a MX28 based board +5) Installation of U-boot into SPI NOR flash on a MX28 based board 1) Prerequisites ---------------- @@ -262,3 +263,28 @@ There are two possibilities when preparing an image writable to NAND flash. In case the user needs to boot a firmware image bigger than 1Mb, the user has to adjust the "update_nand_firmware_maxsz" variable for the update scripts to work properly. + +5) Installation of U-Boot into SPI NOR flash on a MX28 based board +------------------------------------------------------------------ + +The u-boot.sb file can be directly written to SPI NOR from U-boot prompt. + +Load u-boot.sb into RAM, this can be done in several ways and one way is to use +tftp: + => tftp u-boot.sb 0x42000000 + +Probe the SPI NOR flash: + => sf probe + +(SPI NOR should be succesfully detected in this step) + +Erase the blocks where U-boot binary will be written to: + => sf erase 0x0 0x80000 + +Write u-boot.sb to SPI NOR: + => sf write 0x42000000 0 0x80000 + +Power off the board and set the boot mode DIP switches to boot from the SPI NOR +according to MX28 manual section 12.2.1 (Table 12-2) + +Last step is to power up the board and U-boot should start from SPI NOR. diff --git a/doc/README.scrapyard b/doc/README.scrapyard index f9742e7d49..6c6be68c5a 100644 --- a/doc/README.scrapyard +++ b/doc/README.scrapyard @@ -11,15 +11,28 @@ easily if here is something they might want to dig for... Board Arch CPU Commit Removed Last known maintainer/contact ================================================================================================= -lubbock arm pxa - 2014-04-04 Kyle Harris <kharris@nexus-tech.net> -MOUSSE powerpc mpc824x - 2014-04-04 -rsdproto powerpc mpc8260 - 2014-04-04 -RPXsuper powerpc mpc8260 - 2014-04-04 -RPXClassic powerpc mpc8xx - 2014-04-04 -RPXlite powerpc mpc8xx - 2014-04-04 -genietv powerpc mpc8xx - 2014-04-04 -mbx8xx powerpc mpc8xx - 2014-04-04 -nx823 powerpc mpc8xx - 2014-04-04 +simpc8313 powerpc mpc83xx - 2014-04-28 Ron Madrid <info@sheldoninst.com> +hidden_dragon powerpc mpc824x 3fe1a854 2014-05-30 Yusdi Santoso <yusdi_santoso@adaptec.com> +debris powerpc mpc824x 7edb1f7b 2014-05-30 Sangmoon Kim <dogoil@etinsys.com> +kvme080 powerpc mpc824x 2868f862 2014-05-30 Sangmoon Kim <dogoil@etinsys.com> +ep8248 powerpc mpc8260 49ad566d 2014-05-30 Yuli Barcohen <yuli@arabellasw.com> +ispan powerpc mpc8260 80bae39a 2014-05-30 Yuli Barcohen <yuli@arabellasw.com> +rattler powerpc mpc8260 d0664db4 2014-05-30 Yuli Barcohen <yuli@arabellasw.com> +zpc1900 powerpc mpc8260 6f80bb48 2014-05-30 Yuli Barcohen <yuli@arabellasw.com> +mpc8260ads powerpc mpc8260 facb6725 2014-05-30 Yuli Barcohen <yuli@arabellasw.com> +adder powerpc mpc8xx 373a9788 2014-05-30 Yuli Barcohen <yuli@arabellasw.com> +quad100hd powerpc ppc405ep 3569571d 2014-05-30 Gary Jennejohn <gljennjohn@googlemail.com> +lubbock arm pxa 36bf57b 2014-04-18 Kyle Harris <kharris@nexus-tech.net> +EVB64260 powerpc mpc824x bb3aef9 2014-04-18 +MOUSSE powerpc mpc824x 03f2ecc 2014-04-18 +rsdproto powerpc mpc8260 8b043e6 2014-04-18 +RPXsuper powerpc mpc8260 0ebf5f5 2014-04-18 +RPXClassic powerpc mpc8xx 4fb3925 2014-04-18 +RPXlite powerpc mpc8xx 4fb3925 2014-04-18 +FADS powerpc mpc8xx aa6e1e4 2014-04-18 +genietv powerpc mpc8xx b8a49bd 2014-04-18 +mbx8xx powerpc mpc8xx d6b11fd 2014-04-18 +nx823 powerpc mpc8xx a146e8b 2014-04-18 idmr m68k mcf52x2 ba650e9b 2014-01-28 M5271EVB m68k mcf52x2 ba650e9b 2014-01-28 dvl_host arm ixp e317de6b 2014-01-28 Michael Schwingen <michael@schwingen.org> diff --git a/doc/driver-model/README.txt b/doc/driver-model/README.txt index e0b395a618..22c3fcb6ef 100644 --- a/doc/driver-model/README.txt +++ b/doc/driver-model/README.txt @@ -20,7 +20,7 @@ Terminology ----------- Uclass - a group of devices which operate in the same way. A uclass provides - a way of accessing invidual devices within the group, but always + a way of accessing individual devices within the group, but always using the same interface. For example a GPIO uclass provides operations for get/set value. An I2C uclass may have 10 I2C ports, 4 with one driver, and 6 with another. @@ -120,9 +120,9 @@ What is going on? ----------------- Let's start at the top. The demo command is in common/cmd_demo.c. It does -the usual command procesing and then: +the usual command processing and then: - struct device *demo_dev; + struct udevice *demo_dev; ret = uclass_get_device(UCLASS_DEMO, devnum, &demo_dev); @@ -147,7 +147,7 @@ this particular device may use one or other of them. The code for demo_hello() is in drivers/demo/demo-uclass.c: -int demo_hello(struct device *dev, int ch) +int demo_hello(struct udevice *dev, int ch) { const struct demo_ops *ops = device_get_ops(dev); @@ -160,7 +160,7 @@ int demo_hello(struct device *dev, int ch) As you can see it just calls the relevant driver method. One of these is in drivers/demo/demo-simple.c: -static int simple_hello(struct device *dev, int ch) +static int simple_hello(struct udevice *dev, int ch) { const struct dm_demo_pdata *pdata = dev_get_platdata(dev); @@ -222,13 +222,50 @@ device tree) and probe. Platform Data ------------- -Where does the platform data come from? See demo-pdata.c which +Platform data is like Linux platform data, if you are familiar with that. +It provides the board-specific information to start up a device. + +Why is this information not just stored in the device driver itself? The +idea is that the device driver is generic, and can in principle operate on +any board that has that type of device. For example, with modern +highly-complex SoCs it is common for the IP to come from an IP vendor, and +therefore (for example) the MMC controller may be the same on chips from +different vendors. It makes no sense to write independent drivers for the +MMC controller on each vendor's SoC, when they are all almost the same. +Similarly, we may have 6 UARTs in an SoC, all of which are mostly the same, +but lie at different addresses in the address space. + +Using the UART example, we have a single driver and it is instantiated 6 +times by supplying 6 lots of platform data. Each lot of platform data +gives the driver name and a pointer to a structure containing information +about this instance - e.g. the address of the register space. It may be that +one of the UARTS supports RS-485 operation - this can be added as a flag in +the platform data, which is set for this one port and clear for the rest. + +Think of your driver as a generic piece of code which knows how to talk to +a device, but needs to know where it is, any variant/option information and +so on. Platform data provides this link between the generic piece of code +and the specific way it is bound on a particular board. + +Examples of platform data include: + + - The base address of the IP block's register space + - Configuration options, like: + - the SPI polarity and maximum speed for a SPI controller + - the I2C speed to use for an I2C device + - the number of GPIOs available in a GPIO device + +Where does the platform data come from? It is either held in a structure +which is compiled into U-Boot, or it can be parsed from the Device Tree +(see 'Device Tree' below). + +For an example of how it can be compiled in, see demo-pdata.c which sets up a table of driver names and their associated platform data. The data can be interpreted by the drivers however they like - it is basically a communication scheme between the board-specific code and the generic drivers, which are intended to work on any board. -Drivers can acceess their data via dev->info->platdata. Here is +Drivers can access their data via dev->info->platdata. Here is the declaration for the platform data, which would normally appear in the board file. @@ -259,21 +296,30 @@ following device tree fragment: sides = <4>; }; +This means that instead of having lots of U_BOOT_DEVICE() declarations in +the board file, we put these in the device tree. This approach allows a lot +more generality, since the same board file can support many types of boards +(e,g. with the same SoC) just by using different device trees. An added +benefit is that the Linux device tree can be used, thus further simplifying +the task of board-bring up either for U-Boot or Linux devs (whoever gets to +the board first!). The easiest way to make this work it to add a few members to the driver: .platdata_auto_alloc_size = sizeof(struct dm_test_pdata), .ofdata_to_platdata = testfdt_ofdata_to_platdata, - .probe = testfdt_drv_probe, The 'auto_alloc' feature allowed space for the platdata to be allocated -and zeroed before the driver's ofdata_to_platdata method is called. This -method reads the information out of the device tree and puts it in -dev->platdata. Then the probe method is called to set up the device. +and zeroed before the driver's ofdata_to_platdata() method is called. The +ofdata_to_platdata() method, which the driver write supplies, should parse +the device tree node for this device and place it in dev->platdata. Thus +when the probe method is called later (to set up the device ready for use) +the platform data will be present. Note that both methods are optional. If you provide an ofdata_to_platdata -method then it wlil be called first (after bind). If you provide a probe -method it will be called next. +method then it will be called first (during activation). If you provide a +probe method it will be called next. See Driver Lifecycle below for more +details. If you don't want to have the platdata automatically allocated then you can leave out platdata_auto_alloc_size. In this case you can use malloc @@ -295,6 +341,166 @@ numbering comes from include/dm/uclass.h. To add a new uclass, add to the end of the enum there, then declare your uclass as above. +Driver Lifecycle +---------------- + +Here are the stages that a device goes through in driver model. Note that all +methods mentioned here are optional - e.g. if there is no probe() method for +a device then it will not be called. A simple device may have very few +methods actually defined. + +1. Bind stage + +A device and its driver are bound using one of these two methods: + + - Scan the U_BOOT_DEVICE() definitions. U-Boot It looks up the +name specified by each, to find the appropriate driver. It then calls +device_bind() to create a new device and bind' it to its driver. This will +call the device's bind() method. + + - Scan through the device tree definitions. U-Boot looks at top-level +nodes in the the device tree. It looks at the compatible string in each node +and uses the of_match part of the U_BOOT_DRIVER() structure to find the +right driver for each node. It then calls device_bind() to bind the +newly-created device to its driver (thereby creating a device structure). +This will also call the device's bind() method. + +At this point all the devices are known, and bound to their drivers. There +is a 'struct udevice' allocated for all devices. However, nothing has been +activated (except for the root device). Each bound device that was created +from a U_BOOT_DEVICE() declaration will hold the platdata pointer specified +in that declaration. For a bound device created from the device tree, +platdata will be NULL, but of_offset will be the offset of the device tree +node that caused the device to be created. The uclass is set correctly for +the device. + +The device's bind() method is permitted to perform simple actions, but +should not scan the device tree node, not initialise hardware, nor set up +structures or allocate memory. All of these tasks should be left for +the probe() method. + +Note that compared to Linux, U-Boot's driver model has a separate step of +probe/remove which is independent of bind/unbind. This is partly because in +U-Boot it may be expensive to probe devices and we don't want to do it until +they are needed, or perhaps until after relocation. + +2. Activation/probe + +When a device needs to be used, U-Boot activates it, by following these +steps (see device_probe()): + + a. If priv_auto_alloc_size is non-zero, then the device-private space + is allocated for the device and zeroed. It will be accessible as + dev->priv. The driver can put anything it likes in there, but should use + it for run-time information, not platform data (which should be static + and known before the device is probed). + + b. If platdata_auto_alloc_size is non-zero, then the platform data space + is allocated. This is only useful for device tree operation, since + otherwise you would have to specific the platform data in the + U_BOOT_DEVICE() declaration. The space is allocated for the device and + zeroed. It will be accessible as dev->platdata. + + c. If the device's uclass specifies a non-zero per_device_auto_alloc_size, + then this space is allocated and zeroed also. It is allocated for and + stored in the device, but it is uclass data. owned by the uclass driver. + It is possible for the device to access it. + + d. All parent devices are probed. It is not possible to activate a device + unless its predecessors (all the way up to the root device) are activated. + This means (for example) that an I2C driver will require that its bus + be activated. + + e. If the driver provides an ofdata_to_platdata() method, then this is + called to convert the device tree data into platform data. This should + do various calls like fdtdec_get_int(gd->fdt_blob, dev->of_offset, ...) + to access the node and store the resulting information into dev->platdata. + After this point, the device works the same way whether it was bound + using a device tree node or U_BOOT_DEVICE() structure. In either case, + the platform data is now stored in the platdata structure. Typically you + will use the platdata_auto_alloc_size feature to specify the size of the + platform data structure, and U-Boot will automatically allocate and zero + it for you before entry to ofdata_to_platdata(). But if not, you can + allocate it yourself in ofdata_to_platdata(). Note that it is preferable + to do all the device tree decoding in ofdata_to_platdata() rather than + in probe(). (Apart from the ugliness of mixing configuration and run-time + data, one day it is possible that U-Boot will cache platformat data for + devices which are regularly de/activated). + + f. The device's probe() method is called. This should do anything that + is required by the device to get it going. This could include checking + that the hardware is actually present, setting up clocks for the + hardware and setting up hardware registers to initial values. The code + in probe() can access: + + - platform data in dev->platdata (for configuration) + - private data in dev->priv (for run-time state) + - uclass data in dev->uclass_priv (for things the uclass stores + about this device) + + Note: If you don't use priv_auto_alloc_size then you will need to + allocate the priv space here yourself. The same applies also to + platdata_auto_alloc_size. Remember to free them in the remove() method. + + g. The device is marked 'activated' + + h. The uclass's post_probe() method is called, if one exists. This may + cause the uclass to do some housekeeping to record the device as + activated and 'known' by the uclass. + +3. Running stage + +The device is now activated and can be used. From now until it is removed +all of the above structures are accessible. The device appears in the +uclass's list of devices (so if the device is in UCLASS_GPIO it will appear +as a device in the GPIO uclass). This is the 'running' state of the device. + +4. Removal stage + +When the device is no-longer required, you can call device_remove() to +remove it. This performs the probe steps in reverse: + + a. The uclass's pre_remove() method is called, if one exists. This may + cause the uclass to do some housekeeping to record the device as + deactivated and no-longer 'known' by the uclass. + + b. All the device's children are removed. It is not permitted to have + an active child device with a non-active parent. This means that + device_remove() is called for all the children recursively at this point. + + c. The device's remove() method is called. At this stage nothing has been + deallocated so platform data, private data and the uclass data will all + still be present. This is where the hardware can be shut down. It is + intended that the device be completely inactive at this point, For U-Boot + to be sure that no hardware is running, it should be enough to remove + all devices. + + d. The device memory is freed (platform data, private data, uclass data). + + Note: Because the platform data for a U_BOOT_DEVICE() is defined with a + static pointer, it is not de-allocated during the remove() method. For + a device instantiated using the device tree data, the platform data will + be dynamically allocated, and thus needs to be deallocated during the + remove() method, either: + + 1. if the platdata_auto_alloc_size is non-zero, the deallocation + happens automatically within the driver model core; or + + 2. when platdata_auto_alloc_size is 0, both the allocation (in probe() + or preferably ofdata_to_platdata()) and the deallocation in remove() + are the responsibility of the driver author. + + e. The device is marked inactive. Note that it is still bound, so the + device structure itself is not freed at this point. Should the device be + activated again, then the cycle starts again at step 2 above. + +5. Unbind stage + +The device is unbound. This is the step that actually destroys the device. +If a parent has children these will be destroyed first. After this point +the device does not exist and its memory has be deallocated. + + Data Structures --------------- @@ -310,18 +516,18 @@ Changes since v1 For the record, this implementation uses a very similar approach to the original patches, but makes at least the following changes: -- Tried to agressively remove boilerplate, so that for most drivers there +- Tried to aggressively remove boilerplate, so that for most drivers there is little or no 'driver model' code to write. - Moved some data from code into data structure - e.g. store a pointer to the driver operations structure in the driver, rather than passing it to the driver bind function. -- Rename some structures to make them more similar to Linux (struct device +- Rename some structures to make them more similar to Linux (struct udevice instead of struct instance, struct platdata, etc.) - Change the name 'core' to 'uclass', meaning U-Boot class. It seems that this concept relates to a class of drivers (or a subsystem). We shouldn't use 'class' since it is a C++ reserved word, so U-Boot class (uclass) seems better than 'core'. -- Remove 'struct driver_instance' and just use a single 'struct device'. +- Remove 'struct driver_instance' and just use a single 'struct udevice'. This removes a level of indirection that doesn't seem necessary. - Built in device tree support, to avoid the need for platdata - Removed the concept of driver relocation, and just make it possible for diff --git a/doc/uImage.FIT/beaglebone_vboot.txt b/doc/uImage.FIT/beaglebone_vboot.txt new file mode 100644 index 0000000000..b4ab28542e --- /dev/null +++ b/doc/uImage.FIT/beaglebone_vboot.txt @@ -0,0 +1,608 @@ +Verified Boot on the Beaglebone Black +===================================== + +Introduction +------------ + +Before reading this, please read verified-boot.txt and signature.txt. These +instructions are for mainline U-Boot from v2014.07 onwards. + +There is quite a bit of documentation in this directory describing how +verified boot works in U-Boot. There is also a test which runs through the +entire process of signing an image and running U-Boot (sandbox) to check it. +However, it might be useful to also have an example on a real board. + +Beaglebone Black is a fairly common board so seems to be a reasonable choice +for an example of how to enable verified boot using U-Boot. + +First a note that may to help avoid confusion. U-Boot and Linux both use +device tree. They may use the same device tree source, but it is seldom useful +for them to use the exact same binary from the same place. More typically, +U-Boot has its device tree packaged wtih it, and the kernel's device tree is +packaged with the kernel. In particular this is important with verified boot, +since U-Boot's device tree must be immutable. If it can be changed then the +public keys can be changed and verified boot is useless. An attacker can +simply generate a new key and put his public key into U-Boot so that +everything verifies. On the other hand the kernel's device tree typically +changes when the kernel changes, so it is useful to package an updated device +tree with the kernel binary. U-Boot supports the latter with its flexible FIT +format (Flat Image Tree). + + +Overview +-------- + +The steps are roughly as follows: + +1. Build U-Boot for the board, with the verified boot options enabled. + +2. Obtain a suitable Linux kernel + +3. Create a Image Tree Source file (ITS) file describing how you want the +kernel to be packaged, compressed and signed. + +4. Create a key pair + +5. Sign the kernel + +6. Put the public key into U-Boot's image + +7. Put U-Boot and the kernel onto the board + +8. Try it + + +Step 1: Build U-Boot +-------------------- + +a. Set up the environment variable to point to your toolchain. You will need +this for U-Boot and also for the kernel if you build it. For example if you +installed a Linaro version manually it might be something like: + + export CROSS_COMPILE=/opt/linaro/gcc-linaro-arm-linux-gnueabihf-4.8-2013.08_linux/bin/arm-linux-gnueabihf- + +or if you just installed gcc-arm-linux-gnueabi then it might be + + export CROSS_COMPILE=arm-linux-gnueabi- + +b. Configure and build U-Boot with verified boot enabled: + + export ARCH=arm + export UBOOT=/path/to/u-boot + cd $UBOOT + # You can add -j10 if you have 10 CPUs to make it faster + make O=b/am335x_boneblack_vboot am335x_boneblack_vboot_config all + export UOUT=$UBOOT/b/am335x_boneblack_vboot + +c. You will now have a U-Boot image: + + file b/am335x_boneblack_vboot/u-boot-dtb.img +b/am335x_boneblack_vboot/u-boot-dtb.img: u-boot legacy uImage, U-Boot 2014.07-rc2-00065-g2f69f8, Firmware/ARM, Firmware Image (Not compressed), 395375 bytes, Sat May 31 16:19:04 2014, Load Address: 0x80800000, Entry Point: 0x00000000, Header CRC: 0x0ABD6ACA, Data CRC: 0x36DEF7E4 + + +Step 2: Build Linux +-------------------- + +a. Find the kernel image ('Image') and device tree (.dtb) file you plan to +use. In our case it is am335x-boneblack.dtb and it is built with the kernel. +At the time of writing an SD Boot image can be obtained from here: + + http://www.elinux.org/Beagleboard:Updating_The_Software#Image_For_Booting_From_microSD + +You can write this to an SD card and then mount it to extract the kernel and +device tree files. + +You can also build a kernel. Instructions for this are are here: + + http://elinux.org/Building_BBB_Kernel + +or you can use your favourite search engine. Following these instructions +produces a kernel Image and device tree files. For the record the steps were: + + export KERNEL=/path/to/kernel + cd $KERNEL + git clone git://github.com/beagleboard/kernel.git . + git checkout v3.14 + ./patch.sh + cp configs/beaglebone kernel/arch/arm/configs/beaglebone_defconfig + cd kernel + make beaglebone_defconfig + make uImage dtbs # -j10 if you have 10 CPUs + export OKERNEL=$KERNEL/kernel/arch/arm/boot + +c. You now have the 'Image' and 'am335x-boneblack.dtb' files needed to boot. + + +Step 3: Create the ITS +---------------------- + +Set up a directory for your work. + + export WORK=/path/to/dir + cd $WORK + +Put this into a file in that directory called sign.its: + +/dts-v1/; + +/ { + description = "Beaglebone black"; + #address-cells = <1>; + + images { + kernel@1 { + data = /incbin/("Image.lzo"); + type = "kernel"; + arch = "arm"; + os = "linux"; + compression = "lzo"; + load = <0x80008000>; + entry = <0x80008000>; + hash@1 { + algo = "sha1"; + }; + }; + fdt@1 { + description = "beaglebone-black"; + data = /incbin/("am335x-boneblack.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + hash@1 { + algo = "sha1"; + }; + }; + }; + configurations { + default = "conf@1"; + conf@1 { + kernel = "kernel@1"; + fdt = "fdt@1"; + signature@1 { + algo = "sha1,rsa2048"; + key-name-hint = "dev"; + sign-images = "fdt", "kernel"; + }; + }; + }; +}; + + +The explanation for this is all in the documentation you have already read. +But briefly it packages a kernel and device tree, and provides a single +configuration to be signed with a key named 'dev'. The kernel is compressed +with LZO to make it smaller. + + +Step 4: Create a key pair +------------------------- + +See signature.txt for details on this step. + + cd $WORK + mkdir keys + openssl genrsa -F4 -out keys/dev.key 2048 + openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt + +Note: keys/dev.key contains your private key and is very secret. If anyone +gets access to that file they can sign kernels with it. Keep it secure. + + +Step 5: Sign the kernel +----------------------- + +We need to use mkimage (which was built when you built U-Boot) to package the +Linux kernel into a FIT (Flat Image Tree, a flexible file format that U-Boot +can load) using the ITS file you just created. + +At the same time we must put the public key into U-Boot device tree, with the +'required' property, which tells U-Boot that this key must be verified for the +image to be valid. You will make this key available to U-Boot for booting in +step 6. + + ln -s $OKERNEL/dts/am335x-boneblack.dtb + ln -s $OKERNEL/Image + ln -s $UOUT/u-boot-dtb.img + cp $UOUT/arch/arm/dts/am335x-boneblack.dtb am335x-boneblack-pubkey.dtb + lzop Image + $UOUT/tools/mkimage -f sign.its -K am335x-boneblack-pubkey.dtb -k keys -r image.fit + +You should see something like this: + +FIT description: Beaglebone black +Created: Sun Jun 1 12:50:30 2014 + Image 0 (kernel@1) + Description: unavailable + Created: Sun Jun 1 12:50:30 2014 + Type: Kernel Image + Compression: lzo compressed + Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB + Architecture: ARM + OS: Linux + Load Address: 0x80008000 + Entry Point: 0x80008000 + Hash algo: sha1 + Hash value: c94364646427e10f423837e559898ef02c97b988 + Image 1 (fdt@1) + Description: beaglebone-black + Created: Sun Jun 1 12:50:30 2014 + Type: Flat Device Tree + Compression: uncompressed + Data Size: 31547 Bytes = 30.81 kB = 0.03 MB + Architecture: ARM + Hash algo: sha1 + Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d + Default Configuration: 'conf@1' + Configuration 0 (conf@1) + Description: unavailable + Kernel: kernel@1 + FDT: fdt@1 + + +Now am335x-boneblack-pubkey.dtb contains the public key and image.fit contains +the signed kernel. Jump to step 6 if you like, or continue reading to increase +your understanding. + +You can also run fit_check_sign to check it: + + $UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb + +which results in: + +Verifying Hash Integrity ... sha1,rsa2048:dev+ +## Loading kernel from FIT Image at 7fc6ee469000 ... + Using 'conf@1' configuration + Verifying Hash Integrity ... +sha1,rsa2048:dev+ +OK + + Trying 'kernel@1' kernel subimage + Description: unavailable + Created: Sun Jun 1 12:50:30 2014 + Type: Kernel Image + Compression: lzo compressed + Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB + Architecture: ARM + OS: Linux + Load Address: 0x80008000 + Entry Point: 0x80008000 + Hash algo: sha1 + Hash value: c94364646427e10f423837e559898ef02c97b988 + Verifying Hash Integrity ... +sha1+ +OK + +Unimplemented compression type 4 +## Loading fdt from FIT Image at 7fc6ee469000 ... + Using 'conf@1' configuration + Trying 'fdt@1' fdt subimage + Description: beaglebone-black + Created: Sun Jun 1 12:50:30 2014 + Type: Flat Device Tree + Compression: uncompressed + Data Size: 31547 Bytes = 30.81 kB = 0.03 MB + Architecture: ARM + Hash algo: sha1 + Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d + Verifying Hash Integrity ... +sha1+ +OK + + Loading Flat Device Tree ... OK + +## Loading ramdisk from FIT Image at 7fc6ee469000 ... + Using 'conf@1' configuration +Could not find subimage node + +Signature check OK + + +At the top, you see "sha1,rsa2048:dev+". This means that it checked an RSA key +of size 2048 bits using SHA1 as the hash algorithm. The key name checked was +'dev' and the '+' means that it verified. If it showed '-' that would be bad. + +Once the configuration is verified it is then possible to rely on the hashes +in each image referenced by that configuration. So fit_check_sign goes on to +load each of the images. We have a kernel and an FDT but no ramkdisk. In each +case fit_check_sign checks the hash and prints sha1+ meaning that the SHA1 +hash verified. This means that none of the images has been tampered with. + +There is a test in test/vboot which uses U-Boot's sandbox build to verify that +the above flow works. + +But it is fun to do this by hand, so you can load image.fit into a hex editor +like ghex, and change a byte in the kernel: + + $UOUT/tools/fit_info -f image.fit -n /images/kernel@1 -p data +NAME: kernel@1 +LEN: 7790938 +OFF: 168 + +This tells us that the kernel starts at byte offset 168 (decimal) in image.fit +and extends for about 7MB. Try changing a byte at 0x2000 (say) and run +fit_check_sign again. You should see something like: + +Verifying Hash Integrity ... sha1,rsa2048:dev+ +## Loading kernel from FIT Image at 7f5a39571000 ... + Using 'conf@1' configuration + Verifying Hash Integrity ... +sha1,rsa2048:dev+ +OK + + Trying 'kernel@1' kernel subimage + Description: unavailable + Created: Sun Jun 1 13:09:21 2014 + Type: Kernel Image + Compression: lzo compressed + Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB + Architecture: ARM + OS: Linux + Load Address: 0x80008000 + Entry Point: 0x80008000 + Hash algo: sha1 + Hash value: c94364646427e10f423837e559898ef02c97b988 + Verifying Hash Integrity ... +sha1 error +Bad hash value for 'hash@1' hash node in 'kernel@1' image node +Bad Data Hash + +## Loading fdt from FIT Image at 7f5a39571000 ... + Using 'conf@1' configuration + Trying 'fdt@1' fdt subimage + Description: beaglebone-black + Created: Sun Jun 1 13:09:21 2014 + Type: Flat Device Tree + Compression: uncompressed + Data Size: 31547 Bytes = 30.81 kB = 0.03 MB + Architecture: ARM + Hash algo: sha1 + Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d + Verifying Hash Integrity ... +sha1+ +OK + + Loading Flat Device Tree ... OK + +## Loading ramdisk from FIT Image at 7f5a39571000 ... + Using 'conf@1' configuration +Could not find subimage node + +Signature check Bad (error 1) + + +It has detected the change in the kernel. + +You can also be sneaky and try to switch images, using the libfdt utilities +that come with dtc (package name is device-tree-compiler but you will need a +recent version like 1.4: + + dtc -v +Version: DTC 1.4.0 + +First we can check which nodes are actually hashed by the configuration: + + fdtget -l image.fit / +images +configurations + + fdtget -l image.fit /configurations +conf@1 +fdtget -l image.fit /configurations/conf@1 +signature@1 + + fdtget -p image.fit /configurations/conf@1/signature@1 +hashed-strings +hashed-nodes +timestamp +signer-version +signer-name +value +algo +key-name-hint +sign-images + + fdtget image.fit /configurations/conf@1/signature@1 hashed-nodes +/ /configurations/conf@1 /images/fdt@1 /images/fdt@1/hash@1 /images/kernel@1 /images/kernel@1/hash@1 + +This gives us a bit of a look into the signature that mkimage added. Note you +can also use fdtdump to list the entire device tree. + +Say we want to change the kernel that this configuration uses +(/images/kernel@1). We could just put a new kernel in the image, but we will +need to change the hash to match. Let's simulate that by changing a byte of +the hash: + + fdtget -tx image.fit /images/kernel@1/hash@1 value +c9436464 6427e10f 423837e5 59898ef0 2c97b988 + fdtput -tx image.fit /images/kernel@1/hash@1 value c9436464 6427e10f 423837e5 59898ef0 2c97b981 + +Now check it again: + + $UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb +Verifying Hash Integrity ... sha1,rsa2048:devrsa_verify_with_keynode: RSA failed to verify: -13 +rsa_verify_with_keynode: RSA failed to verify: -13 +- +Failed to verify required signature 'key-dev' +Signature check Bad (error 1) + +This time we don't even get as far as checking the images, since the +configuration signature doesn't match. We can't change any hashes without the +signature check noticing. The configuration is essentially locked. U-Boot has +a public key for which it requires a match, and will not permit the use of any +configuration that does not match that public key. The only way the +configuration will match is if it was signed by the matching private key. + +It would also be possible to add a new signature node that does match your new +configuration. But that won't work since you are not allowed to change the +configuration in any way. Try it with a fresh (valid) image if you like by +running the mkimage link again. Then: + + fdtput -p image.fit /configurations/conf@1/signature@2 value fred + $UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb +Verifying Hash Integrity ... - +sha1,rsa2048:devrsa_verify_with_keynode: RSA failed to verify: -13 +rsa_verify_with_keynode: RSA failed to verify: -13 +- +Failed to verify required signature 'key-dev' +Signature check Bad (error 1) + + +Of course it would be possible to add an entirely new configuration and boot +with that, but it still needs to be signed, so it won't help. + + +6. Put the public key into U-Boot's image +----------------------------------------- + +Having confirmed that the signature is doing its job, let's try it out in +U-Boot on the board. U-Boot needs access to the public key corresponding to +the private key that you signed with so that it can verify any kernels that +you sign. + + cd $UBOOT + make O=b/am335x_boneblack_vboot EXT_DTB=${WORK}/am335x-boneblack-pubkey.dtb + +Here we are overrriding the normal device tree file with our one, which +contains the public key. + +Now you have a special U-Boot image with the public key. It can verify can +kernel that you sign with the private key as in step 5. + +If you like you can take a look at the public key information that mkimage +added to U-Boot's device tree: + + fdtget -p am335x-boneblack-pubkey.dtb /signature/key-dev +required +algo +rsa,r-squared +rsa,modulus +rsa,n0-inverse +rsa,num-bits +key-name-hint + +This has information about the key and some pre-processed values which U-Boot +can use to verify against it. These values are obtained from the public key +certificate by mkimage, but require quite a bit of code to generate. To save +code space in U-Boot, the information is extracted and written in raw form for +U-Boot to easily use. The same mechanism is used in Google's Chrome OS. + +Notice the 'required' property. This marks the key as required - U-Boot will +not boot any image that does not verify against this key. + + +7. Put U-Boot and the kernel onto the board +------------------------------------------- + +The method here varies depending on how you are booting. For this example we +are booting from an micro-SD card with two partitions, one for U-Boot and one +for Linux. Put it into your machine and write U-Boot and the kernel to it. +Here the card is /dev/sde: + + cd $WORK + export UDEV=/dev/sde1 # Change thes two lines to the correct device + export KDEV=/dev/sde2 + sudo mount $UDEV /mnt/tmp && sudo cp $UOUT/u-boot-dtb.img /mnt/tmp/u-boot.img && sleep 1 && sudo umount $UDEV + sudo mount $KDEV /mnt/tmp && sudo cp $WORK/image.fit /mnt/tmp/boot/image.fit && sleep 1 && sudo umount $KDEV + + +8. Try it +--------- + +Boot the board using the commands below: + + setenv bootargs console=ttyO0,115200n8 quiet root=/dev/mmcblk0p2 ro rootfstype=ext4 rootwait + ext2load mmc 0:2 82000000 /boot/image.fit + bootm 82000000 + +You should then see something like this: + +U-Boot# setenv bootargs console=ttyO0,115200n8 quiet root=/dev/mmcblk0p2 ro rootfstype=ext4 rootwait +U-Boot# ext2load mmc 0:2 82000000 /boot/image.fit +7824930 bytes read in 589 ms (12.7 MiB/s) +U-Boot# bootm 82000000 +## Loading kernel from FIT Image at 82000000 ... + Using 'conf@1' configuration + Verifying Hash Integrity ... sha1,rsa2048:dev+ OK + Trying 'kernel@1' kernel subimage + Description: unavailable + Created: 2014-06-01 19:32:54 UTC + Type: Kernel Image + Compression: lzo compressed + Data Start: 0x820000a8 + Data Size: 7790938 Bytes = 7.4 MiB + Architecture: ARM + OS: Linux + Load Address: 0x80008000 + Entry Point: 0x80008000 + Hash algo: sha1 + Hash value: c94364646427e10f423837e559898ef02c97b988 + Verifying Hash Integrity ... sha1+ OK +## Loading fdt from FIT Image at 82000000 ... + Using 'conf@1' configuration + Trying 'fdt@1' fdt subimage + Description: beaglebone-black + Created: 2014-06-01 19:32:54 UTC + Type: Flat Device Tree + Compression: uncompressed + Data Start: 0x8276e2ec + Data Size: 31547 Bytes = 30.8 KiB + Architecture: ARM + Hash algo: sha1 + Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d + Verifying Hash Integrity ... sha1+ OK + Booting using the fdt blob at 0x8276e2ec + Uncompressing Kernel Image ... OK + Loading Device Tree to 8fff5000, end 8ffffb3a ... OK + +Starting kernel ... + +[ 0.582377] omap_init_mbox: hwmod doesn't have valid attrs +[ 2.589651] musb-hdrc musb-hdrc.0.auto: Failed to request rx1. +[ 2.595830] musb-hdrc musb-hdrc.0.auto: musb_init_controller failed with status -517 +[ 2.606470] musb-hdrc musb-hdrc.1.auto: Failed to request rx1. +[ 2.612723] musb-hdrc musb-hdrc.1.auto: musb_init_controller failed with status -517 +[ 2.940808] drivers/rtc/hctosys.c: unable to open rtc device (rtc0) +[ 7.248889] libphy: PHY 4a101000.mdio:01 not found +[ 7.253995] net eth0: phy 4a101000.mdio:01 not found on slave 1 +systemd-fsck[83]: Angstrom: clean, 50607/218160 files, 306348/872448 blocks + +.---O---. +| | .-. o o +| | |-----.-----.-----.| | .----..-----.-----. +| | | __ | ---'| '--.| .-'| | | +| | | | | |--- || --'| | | ' | | | | +'---'---'--'--'--. |-----''----''--' '-----'-'-'-' + -' | + '---' + +The Angstrom Distribution beaglebone ttyO0 + +Angstrom v2012.12 - Kernel 3.14.1+ + +beaglebone login: + +At this point your kernel has been verified and you can be sure that it is one +that you signed. As an exercise, try changing image.fit as in step 5 and see +what happens. + + +Further Improvements +-------------------- + +Several of the steps here can be easily automated. In particular it would be +capital if signing and packaging a kernel were easy, perhaps a simple make +target in the kernel. + +Some mention of how to use multiple .dtb files in a FIT might be useful. + +U-Boot's verified boot mechanism has not had a robust and independent security +review. Such a review should look at the implementation and its resistance to +attacks. + +Perhaps the verified boot feature could could be integrated into the Amstrom +distribution. + + +Simon Glass +sjg@chromium.org +2-June-14 diff --git a/doc/uImage.FIT/howto.txt b/doc/uImage.FIT/howto.txt index 526be55a57..14e316f72c 100644 --- a/doc/uImage.FIT/howto.txt +++ b/doc/uImage.FIT/howto.txt @@ -16,7 +16,10 @@ create an uImage in the new format: mkimage and dtc, although only one (mkimage) is invoked directly. dtc is called from within mkimage and operates behind the scenes, but needs to be present in the $PATH nevertheless. It is important that the dtc used has support for binary includes -- refer to -www.jdl.com for its latest version. mkimage (together with dtc) takes as input + + git://git.kernel.org/pub/scm/utils/dtc/dtc.git + +for its latest version. mkimage (together with dtc) takes as input an image source file, which describes the contents of the image and defines its various properties used during booting. By convention, image source file has the ".its" extension, also, the details of its format are given in diff --git a/doc/uImage.FIT/signature.txt b/doc/uImage.FIT/signature.txt index 9502037705..a6ab543de4 100644 --- a/doc/uImage.FIT/signature.txt +++ b/doc/uImage.FIT/signature.txt @@ -328,6 +328,9 @@ be enabled: CONFIG_FIT_SIGNATURE - enable signing and verfication in FITs CONFIG_RSA - enable RSA algorithm for signing +WARNING: When relying on signed FIT images with required signature check +the legacy image format is default disabled by not defining +CONFIG_IMAGE_FORMAT_LEGACY Testing ------- @@ -358,6 +361,7 @@ Test Verified Boot Run: unsigned config: OK Sign images Test Verified Boot Run: signed config: OK check signed config on the host +Signature check OK OK Test Verified Boot Run: signed config: OK Test Verified Boot Run: signed config with bad hash: OK @@ -371,12 +375,14 @@ Test Verified Boot Run: unsigned config: OK Sign images Test Verified Boot Run: signed config: OK check signed config on the host +Signature check OK OK Test Verified Boot Run: signed config: OK Test Verified Boot Run: signed config with bad hash: OK Test passed + Future Work ----------- - Roll-back protection using a TPM is done using the tpm command. This can |