diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/device-tree-bindings/mtd/spi/spi-flash.txt | 25 | ||||
| -rw-r--r-- | doc/device-tree-bindings/spi/soft-spi.txt | 34 | ||||
| -rw-r--r-- | doc/driver-model/README.txt | 7 | ||||
| -rw-r--r-- | doc/driver-model/spi-howto.txt | 594 | ||||
| -rw-r--r-- | doc/uImage.FIT/kernel.its | 50 | ||||
| -rw-r--r-- | doc/uImage.FIT/source_file_format.txt | 19 | ||||
| -rw-r--r-- | doc/uImage.FIT/x86-fit-boot.txt | 276 |
7 files changed, 995 insertions, 10 deletions
diff --git a/doc/device-tree-bindings/mtd/spi/spi-flash.txt b/doc/device-tree-bindings/mtd/spi/spi-flash.txt new file mode 100644 index 0000000..85522d8 --- /dev/null +++ b/doc/device-tree-bindings/mtd/spi/spi-flash.txt @@ -0,0 +1,25 @@ +* MTD SPI driver for serial flash chips + +Required properties: +- #address-cells, #size-cells : Must be present if the device has sub-nodes + representing partitions. +- compatible : Should be the manufacturer and the name of the chip. Bear in + mind that the DT binding is not U-Boot-only, but in case of + U-Boot, see spi_flash_params_table table in + drivers/mtd/spi/sf_params.c for the list of supported chips. +- reg : Chip-Select number +- spi-max-frequency : Maximum frequency of the SPI bus the chip can operate at + +Optional properties: + - memory-map : Address and size of the flash, if memory mapped. This may + apply to Intel chipsets, which tend to memory-map flash. + +Example: + + flash: m25p80@0 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "spansion,m25p80"; + reg = <0>; + spi-max-frequency = <40000000>; + }; diff --git a/doc/device-tree-bindings/spi/soft-spi.txt b/doc/device-tree-bindings/spi/soft-spi.txt new file mode 100644 index 0000000..d09c1a5 --- /dev/null +++ b/doc/device-tree-bindings/spi/soft-spi.txt @@ -0,0 +1,34 @@ +Soft SPI + +The soft SPI bus implementation allows the use of GPIO pins to simulate a +SPI bus. No SPI host is required for this to work. The down-side is that the +performance will typically be much lower than a real SPI bus. + +The soft SPI node requires the following properties: + +compatible: "u-boot,soft-spi" +soft_spi_cs: GPIO number to use for SPI chip select (output) +soft_spi_sclk: GPIO number to use for SPI clock (output) +soft_spi_mosi: GPIO number to use for SPI MOSI line (output) +soft_spi_miso GPIO number to use for SPI MISO line (input) +spi-delay-us: Number of microseconds of delay between each CS transition + +The GPIOs should be specified as required by the GPIO controller referenced. +The first cell holds the phandle of the controller and the second cell +typically holds the GPIO number. + + +Example: + + soft-spi { + compatible = "u-boot,soft-spi"; + cs-gpio = <&gpio 235 0>; /* Y43 */ + sclk-gpio = <&gpio 225 0>; /* Y31 */ + mosi-gpio = <&gpio 227 0>; /* Y33 */ + miso-gpio = <&gpio 224 0>; /* Y30 */ + spi-delay-us = <1>; + #address-cells = <1>; + #size-cells = <0>; + cs@0 { + }; + }; diff --git a/doc/driver-model/README.txt b/doc/driver-model/README.txt index f9b68be..8dfcf75 100644 --- a/doc/driver-model/README.txt +++ b/doc/driver-model/README.txt @@ -95,7 +95,7 @@ are provided in test/dm. To run them, try: You should see something like this: <...U-Boot banner...> - Running 21 driver model tests + Running 22 driver model tests Test: dm_test_autobind Test: dm_test_autoprobe Test: dm_test_bus_children @@ -103,6 +103,7 @@ You should see something like this: Device 'c-test@0': seq 0 is in use by 'a-test' Device 'c-test@1': seq 1 is in use by 'd-test' Test: dm_test_bus_children_funcs + Test: dm_test_bus_children_iterators Test: dm_test_bus_parent_data Test: dm_test_bus_parent_ops Test: dm_test_children @@ -358,7 +359,9 @@ Device Sequence Numbers U-Boot numbers devices from 0 in many situations, such as in the command line for I2C and SPI buses, and the device names for serial ports (serial0, serial1, ...). Driver model supports this numbering and permits devices -to be locating by their 'sequence'. +to be locating by their 'sequence'. This numbering unique identifies a +device in its uclass, so no two devices within a particular uclass can have +the same sequence number. Sequence numbers start from 0 but gaps are permitted. For example, a board may have I2C buses 0, 1, 4, 5 but no 2 or 3. The choice of how devices are diff --git a/doc/driver-model/spi-howto.txt b/doc/driver-model/spi-howto.txt new file mode 100644 index 0000000..719dbd5 --- /dev/null +++ b/doc/driver-model/spi-howto.txt @@ -0,0 +1,594 @@ +How to port a SPI driver to driver model +======================================== + +Here is a rough step-by-step guide. It is based around converting the +exynos SPI driver to driver model (DM) and the example code is based +around U-Boot v2014.10-rc2 (commit be9f643). + +It is quite long since it includes actual code examples. + +Before driver model, SPI drivers have their own private structure which +contains 'struct spi_slave'. With driver model, 'struct spi_slave' still +exists, but now it is 'per-child data' for the SPI bus. Each child of the +SPI bus is a SPI slave. The information that was stored in the +driver-specific slave structure can now be port in private data for the +SPI bus. + +For example, struct tegra_spi_slave looks like this: + +struct tegra_spi_slave { + struct spi_slave slave; + struct tegra_spi_ctrl *ctrl; +}; + +In this case 'slave' will be in per-child data, and 'ctrl' will be in the +SPI's buses private data. + + +0. How long does this take? + +You should be able to complete this within 2 hours, including testing but +excluding preparing the patches. The API is basically the same as before +with only minor changes: + +- methods to set speed and mode are separated out +- cs_info is used to get information on a chip select + + +1. Enable driver mode for SPI and SPI flash + +Add these to your board config: + +#define CONFIG_DM_SPI +#define CONFIG_DM_SPI_FLASH + + +2. Add the skeleton + +Put this code at the bottom of your existing driver file: + +struct spi_slave *spi_setup_slave(unsigned int busnum, unsigned int cs, + unsigned int max_hz, unsigned int mode) +{ + return NULL; +} + +struct spi_slave *spi_setup_slave_fdt(const void *blob, int slave_node, + int spi_node) +{ + return NULL; +} + +static int exynos_spi_ofdata_to_platdata(struct udevice *dev) +{ + return -ENODEV; +} + +static int exynos_spi_probe(struct udevice *dev) +{ + return -ENODEV; +} + +static int exynos_spi_remove(struct udevice *dev) +{ + return -ENODEV; +} + +static int exynos_spi_claim_bus(struct udevice *dev) +{ + + return -ENODEV; +} + +static int exynos_spi_release_bus(struct udevice *dev) +{ + + return -ENODEV; +} + +static int exynos_spi_xfer(struct udevice *dev, unsigned int bitlen, + const void *dout, void *din, unsigned long flags) +{ + + return -ENODEV; +} + +static int exynos_spi_set_speed(struct udevice *dev, uint speed) +{ + return -ENODEV; +} + +static int exynos_spi_set_mode(struct udevice *dev, uint mode) +{ + return -ENODEV; +} + +static int exynos_cs_info(struct udevice *bus, uint cs, + struct spi_cs_info *info) +{ + return -ENODEV; +} + +static const struct dm_spi_ops exynos_spi_ops = { + .claim_bus = exynos_spi_claim_bus, + .release_bus = exynos_spi_release_bus, + .xfer = exynos_spi_xfer, + .set_speed = exynos_spi_set_speed, + .set_mode = exynos_spi_set_mode, + .cs_info = exynos_cs_info, +}; + +static const struct udevice_id exynos_spi_ids[] = { + { .compatible = "samsung,exynos-spi" }, + { } +}; + +U_BOOT_DRIVER(exynos_spi) = { + .name = "exynos_spi", + .id = UCLASS_SPI, + .of_match = exynos_spi_ids, + .ops = &exynos_spi_ops, + .ofdata_to_platdata = exynos_spi_ofdata_to_platdata, + .probe = exynos_spi_probe, + .remove = exynos_spi_remove, +}; + + +3. Replace 'exynos' in the above code with your driver name + + +4. #ifdef out all of the code in your driver except for the above + +This will allow you to get it building, which means you can work +incrementally. Since all the methods return an error initially, there is +less chance that you will accidentally leave something in. + +Also, even though your conversion is basically a rewrite, it might help +reviewers if you leave functions in the same place in the file, +particularly for large drivers. + + +5. Add some includes + +Add these includes to your driver: + +#include <dm.h> +#include <errno.h> + + +6. Build + +At this point you should be able to build U-Boot for your board with the +empty SPI driver. You still have empty methods in your driver, but we will +write these one by one. + +If you have spi_init() functions or the like that are called from your +board then the build will fail. Remove these calls and make a note of the +init that needs to be done. + + +7. Set up your platform data structure + +This will hold the information your driver to operate, like its hardware +address or maximum frequency. + +You may already have a struct like this, or you may need to create one +from some of the #defines or global variables in the driver. + +Note that this information is not the run-time information. It should not +include state that changes. It should be fixed throughout the live of +U-Boot. Run-time information comes later. + +Here is what was in the exynos spi driver: + +struct spi_bus { + enum periph_id periph_id; + s32 frequency; /* Default clock frequency, -1 for none */ + struct exynos_spi *regs; + int inited; /* 1 if this bus is ready for use */ + int node; + uint deactivate_delay_us; /* Delay to wait after deactivate */ +}; + +Of these, inited is handled by DM and node is the device tree node, which +DM tells you. The name is not quite right. So in this case we would use: + +struct exynos_spi_platdata { + enum periph_id periph_id; + s32 frequency; /* Default clock frequency, -1 for none */ + struct exynos_spi *regs; + uint deactivate_delay_us; /* Delay to wait after deactivate */ +}; + + +8a. Write ofdata_to_platdata() [for device tree only] + +This method will convert information in the device tree node into a C +structure in your driver (called platform data). If you are not using +device tree, go to 8b. + +DM will automatically allocate the struct for us when we are using device +tree, but we need to tell it the size: + +U_BOOT_DRIVER(spi_exynos) = { +... + .platdata_auto_alloc_size = sizeof(struct exynos_spi_platdata), + + +Here is a sample function. It gets a pointer to the platform data and +fills in the fields from device tree. + +static int exynos_spi_ofdata_to_platdata(struct udevice *bus) +{ + struct exynos_spi_platdata *plat = bus->platdata; + const void *blob = gd->fdt_blob; + int node = bus->of_offset; + + plat->regs = (struct exynos_spi *)fdtdec_get_addr(blob, node, "reg"); + plat->periph_id = pinmux_decode_periph_id(blob, node); + + if (plat->periph_id == PERIPH_ID_NONE) { + debug("%s: Invalid peripheral ID %d\n", __func__, + plat->periph_id); + return -FDT_ERR_NOTFOUND; + } + + /* Use 500KHz as a suitable default */ + plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", + 500000); + plat->deactivate_delay_us = fdtdec_get_int(blob, node, + "spi-deactivate-delay", 0); + debug("%s: regs=%p, periph_id=%d, max-frequency=%d, deactivate_delay=%d\n", + __func__, plat->regs, plat->periph_id, plat->frequency, + plat->deactivate_delay_us); + + return 0; +} + + +8b. Add the platform data [non-device-tree only] + +Specify this data in a U_BOOT_DEVICE() declaration in your board file: + +struct exynos_spi_platdata platdata_spi0 = { + .periph_id = ... + .frequency = ... + .regs = ... + .deactivate_delay_us = ... +}; + +U_BOOT_DEVICE(board_spi0) = { + .name = "exynos_spi", + .platdata = &platdata_spi0, +}; + +You will unfortunately need to put the struct into a header file in this +case so that your board file can use it. + + +9. Add the device private data + +Most devices have some private data which they use to keep track of things +while active. This is the run-time information and needs to be stored in +a structure. There is probably a structure in the driver that includes a +'struct spi_slave', so you can use that. + +struct exynos_spi_slave { + struct spi_slave slave; + struct exynos_spi *regs; + unsigned int freq; /* Default frequency */ + unsigned int mode; + enum periph_id periph_id; /* Peripheral ID for this device */ + unsigned int fifo_size; + int skip_preamble; + struct spi_bus *bus; /* Pointer to our SPI bus info */ + ulong last_transaction_us; /* Time of last transaction end */ +}; + + +We should rename this to make its purpose more obvious, and get rid of +the slave structure, so we have: + +struct exynos_spi_priv { + struct exynos_spi *regs; + unsigned int freq; /* Default frequency */ + unsigned int mode; + enum periph_id periph_id; /* Peripheral ID for this device */ + unsigned int fifo_size; + int skip_preamble; + ulong last_transaction_us; /* Time of last transaction end */ +}; + + +DM can auto-allocate this also: + +U_BOOT_DRIVER(spi_exynos) = { +... + .priv_auto_alloc_size = sizeof(struct exynos_spi_priv), + + +Note that this is created before the probe method is called, and destroyed +after the remove method is called. It will be zeroed when the probe +method is called. + + +10. Add the probe() and remove() methods + +Note: It's a good idea to build repeatedly as you are working, to avoid a +huge amount of work getting things compiling at the end. + +The probe method is supposed to set up the hardware. U-Boot used to use +spi_setup_slave() to do this. So take a look at this function and see +what you can copy out to set things up. + + +static int exynos_spi_probe(struct udevice *bus) +{ + struct exynos_spi_platdata *plat = dev_get_platdata(bus); + struct exynos_spi_priv *priv = dev_get_priv(bus); + + priv->regs = plat->regs; + if (plat->periph_id == PERIPH_ID_SPI1 || + plat->periph_id == PERIPH_ID_SPI2) + priv->fifo_size = 64; + else + priv->fifo_size = 256; + + priv->skip_preamble = 0; + priv->last_transaction_us = timer_get_us(); + priv->freq = plat->frequency; + priv->periph_id = plat->periph_id; + + return 0; +} + +This implementation doesn't actually touch the hardware, which is somewhat +unusual for a driver. In this case we will do that when the device is +claimed by something that wants to use the SPI bus. + +For remove we could shut down the clocks, but in this case there is +nothing to do. DM frees any memory that it allocated, so we can just +remove exynos_spi_remove() and its reference in U_BOOT_DRIVER. + + +11. Implement set_speed() + +This should set up clocks so that the SPI bus is running at the right +speed. With the old API spi_claim_bus() would normally do this and several +of the following functions, so let's look at that function: + +int spi_claim_bus(struct spi_slave *slave) +{ + struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); + struct exynos_spi *regs = spi_slave->regs; + u32 reg = 0; + int ret; + + ret = set_spi_clk(spi_slave->periph_id, + spi_slave->freq); + if (ret < 0) { + debug("%s: Failed to setup spi clock\n", __func__); + return ret; + } + + exynos_pinmux_config(spi_slave->periph_id, PINMUX_FLAG_NONE); + + spi_flush_fifo(slave); + + reg = readl(®s->ch_cfg); + reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); + + if (spi_slave->mode & SPI_CPHA) + reg |= SPI_CH_CPHA_B; + + if (spi_slave->mode & SPI_CPOL) + reg |= SPI_CH_CPOL_L; + + writel(reg, ®s->ch_cfg); + writel(SPI_FB_DELAY_180, ®s->fb_clk); + + return 0; +} + + +It sets up the speed, mode, pinmux, feedback delay and clears the FIFOs. +With DM these will happen in separate methods. + + +Here is an example for the speed part: + +static int exynos_spi_set_speed(struct udevice *bus, uint speed) +{ + struct exynos_spi_platdata *plat = bus->platdata; + struct exynos_spi_priv *priv = dev_get_priv(bus); + int ret; + + if (speed > plat->frequency) + speed = plat->frequency; + ret = set_spi_clk(priv->periph_id, speed); + if (ret) + return ret; + priv->freq = speed; + debug("%s: regs=%p, speed=%d\n", __func__, priv->regs, priv->freq); + + return 0; +} + + +12. Implement set_mode() + +This should adjust the SPI mode (polarity, etc.). Again this code probably +comes from the old spi_claim_bus(). Here is an example: + + +static int exynos_spi_set_mode(struct udevice *bus, uint mode) +{ + struct exynos_spi_priv *priv = dev_get_priv(bus); + uint32_t reg; + + reg = readl(&priv->regs->ch_cfg); + reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); + + if (mode & SPI_CPHA) + reg |= SPI_CH_CPHA_B; + + if (mode & SPI_CPOL) + reg |= SPI_CH_CPOL_L; + + writel(reg, &priv->regs->ch_cfg); + priv->mode = mode; + debug("%s: regs=%p, mode=%d\n", __func__, priv->regs, priv->mode); + + return 0; +} + + +13. Implement claim_bus() + +This is where a client wants to make use of the bus, so claims it first. +At this point we need to make sure everything is set up ready for data +transfer. Note that this function is wholly internal to the driver - at +present the SPI uclass never calls it. + +Here again we look at the old claim function and see some code that is +needed. It is anything unrelated to speed and mode: + +static int exynos_spi_claim_bus(struct udevice *bus) +{ + struct exynos_spi_priv *priv = dev_get_priv(bus); + + exynos_pinmux_config(priv->periph_id, PINMUX_FLAG_NONE); + spi_flush_fifo(priv->regs); + + writel(SPI_FB_DELAY_180, &priv->regs->fb_clk); + + return 0; +} + +The spi_flush_fifo() function is in the removed part of the code, so we +need to expose it again (perhaps with an #endif before it and '#if 0' +after it). It only needs access to priv->regs which is why we have +passed that in: + +/** + * Flush spi tx, rx fifos and reset the SPI controller + * + * @param regs Pointer to SPI registers + */ +static void spi_flush_fifo(struct exynos_spi *regs) +{ + clrsetbits_le32(®s->ch_cfg, SPI_CH_HS_EN, SPI_CH_RST); + clrbits_le32(®s->ch_cfg, SPI_CH_RST); + setbits_le32(®s->ch_cfg, SPI_TX_CH_ON | SPI_RX_CH_ON); +} + + +14. Implement release_bus() + +This releases the bus - in our example the old code in spi_release_bus() +is a call to spi_flush_fifo, so we add: + +static int exynos_spi_release_bus(struct udevice *bus) +{ + struct exynos_spi_priv *priv = dev_get_priv(bus); + + spi_flush_fifo(priv->regs); + + return 0; +} + + +15. Implement xfer() + +This is the final method that we need to create, and it is where all the +work happens. The method parameters are the same as the old spi_xfer() with +the addition of a 'struct udevice' so conversion is pretty easy. Start +by copying the contents of spi_xfer() to your new xfer() method and proceed +from there. + +If (flags & SPI_XFER_BEGIN) is non-zero then xfer() normally calls an +activate function, something like this: + +void spi_cs_activate(struct spi_slave *slave) +{ + struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); + + /* If it's too soon to do another transaction, wait */ + if (spi_slave->bus->deactivate_delay_us && + spi_slave->last_transaction_us) { + ulong delay_us; /* The delay completed so far */ + delay_us = timer_get_us() - spi_slave->last_transaction_us; + if (delay_us < spi_slave->bus->deactivate_delay_us) + udelay(spi_slave->bus->deactivate_delay_us - delay_us); + } + + clrbits_le32(&spi_slave->regs->cs_reg, SPI_SLAVE_SIG_INACT); + debug("Activate CS, bus %d\n", spi_slave->slave.bus); + spi_slave->skip_preamble = spi_slave->mode & SPI_PREAMBLE; +} + +The new version looks like this: + +static void spi_cs_activate(struct udevice *dev) +{ + struct udevice *bus = dev->parent; + struct exynos_spi_platdata *pdata = dev_get_platdata(bus); + struct exynos_spi_priv *priv = dev_get_priv(bus); + + /* If it's too soon to do another transaction, wait */ + if (pdata->deactivate_delay_us && + priv->last_transaction_us) { + ulong delay_us; /* The delay completed so far */ + delay_us = timer_get_us() - priv->last_transaction_us; + if (delay_us < pdata->deactivate_delay_us) + udelay(pdata->deactivate_delay_us - delay_us); + } + + clrbits_le32(&priv->regs->cs_reg, SPI_SLAVE_SIG_INACT); + debug("Activate CS, bus '%s'\n", bus->name); + priv->skip_preamble = priv->mode & SPI_PREAMBLE; +} + +All we have really done here is change the pointers and print the device name +instead of the bus number. Other local static functions can be treated in +the same way. + + +16. Set up the per-child data and child pre-probe function + +To minimise the pain and complexity of the SPI subsystem while the driver +model change-over is in place, struct spi_slave is used to reference a +SPI bus slave, even though that slave is actually a struct udevice. In fact +struct spi_slave is the device's child data. We need to make sure this space +is available. It is possible to allocate more space that struct spi_slave +needs, but this is the minimum. + +U_BOOT_DRIVER(exynos_spi) = { +... + .per_child_auto_alloc_size = sizeof(struct spi_slave), +} + + +17. Optional: Set up cs_info() if you want it + +Sometimes it is useful to know whether a SPI chip select is valid, but this +is not obvious from outside the driver. In this case you can provide a +method for cs_info() to deal with this. If you don't provide it, then the +device tree will be used to determine what chip selects are valid. + +Return -ENODEV if the supplied chip select is invalid, or 0 if it is valid. +If you don't provide the cs_info() method, -ENODEV is assumed for all +chip selects that do not appear in the device tree. + + +18. Test it + +Now that you have the code written and it compiles, try testing it using +the 'sf test' command. You may need to enable CONFIG_CMD_SF_TEST for your +board. + + +19. Prepare patches and send them to the mailing lists + +You can use 'tools/patman/patman' to prepare, check and send patches for +your work. See the README for details. diff --git a/doc/uImage.FIT/kernel.its b/doc/uImage.FIT/kernel.its index ef3ab8f..539cdbf 100644 --- a/doc/uImage.FIT/kernel.its +++ b/doc/uImage.FIT/kernel.its @@ -35,3 +35,53 @@ }; }; }; + + + +For x86 a setup node is also required: see x86-fit-boot.txt. + +/dts-v1/; + +/ { + description = "Simple image with single Linux kernel on x86"; + #address-cells = <1>; + + images { + kernel@1 { + description = "Vanilla Linux kernel"; + data = /incbin/("./image.bin.lzo"); + type = "kernel"; + arch = "x86"; + os = "linux"; + compression = "lzo"; + load = <0x01000000>; + entry = <0x00000000>; + hash@2 { + algo = "sha1"; + }; + }; + + setup@1 { + description = "Linux setup.bin"; + data = /incbin/("./setup.bin"); + type = "x86_setup"; + arch = "x86"; + os = "linux"; + compression = "none"; + load = <0x00090000>; + entry = <0x00090000>; + hash@2 { + algo = "sha1"; + }; + }; + }; + + configurations { + default = "config@1"; + config@1 { + description = "Boot Linux kernel"; + kernel = "kernel@1"; + setup = "setup@1"; + }; + }; +}; diff --git a/doc/uImage.FIT/source_file_format.txt b/doc/uImage.FIT/source_file_format.txt index 9ed6f65..b47ce73 100644 --- a/doc/uImage.FIT/source_file_format.txt +++ b/doc/uImage.FIT/source_file_format.txt @@ -55,7 +55,7 @@ FIT is formally a flattened device tree (in the libfdt meaning), which conforms to bindings defined in this document. .its - image tree source -.itb - image tree blob +.fit - flattened image tree blob c) Image building procedure @@ -101,15 +101,15 @@ Root node of the uImage Tree should have the following layout: | o images | | - | o img@1 {...} - | o img@2 {...} + | o image@1 {...} + | o image@2 {...} | ... | o configurations - |- default = "cfg@1" + |- default = "conf@1" | - o cfg@1 {...} - o cfg@2 {...} + o conf@1 {...} + o conf@2 {...} ... @@ -159,7 +159,7 @@ the '/images' node should have the following layout: - description : Textual description of the component sub-image - type : Name of component sub-image type, supported types are: "standalone", "kernel", "ramdisk", "firmware", "script", "filesystem", - "flat_dt". + "flat_dt" and others (see uimage_type in common/images.c). - data : Path to the external file which contains this node's binary data. - compression : Compression used by included data. Supported compressions are "gzip" and "bzip2". If no compression is used compression property @@ -173,7 +173,8 @@ the '/images' node should have the following layout: - arch : Architecture name, mandatory for types: "standalone", "kernel", "firmware", "ramdisk" and "fdt". Valid architecture names are: "alpha", "arm", "i386", "ia64", "mips", "mips64", "ppc", "s390", "sh", "sparc", - "sparc64", "m68k", "microblaze", "nios2", "blackfin", "avr32", "st200". + "sparc64", "m68k", "microblaze", "nios2", "blackfin", "avr32", "st200", + "sandbox". - entry : entry point address, address size is determined by '#address-cells' property of the root node. Mandatory for for types: "standalone" and "kernel". @@ -246,6 +247,8 @@ o config@1 node of a "ramdisk" type). - fdt : Unit name of the corresponding fdt blob (component image node of a "fdt type"). + - setup : Unit name of the corresponding setup binary (used for booting + an x86 kernel). This contains the setup.bin file built by the kernel. The FDT blob is required to properly boot FDT based kernel, so the minimal configuration for 2.6 FDT kernel is (kernel, fdt) pair. diff --git a/doc/uImage.FIT/x86-fit-boot.txt b/doc/uImage.FIT/x86-fit-boot.txt new file mode 100644 index 0000000..61c10ff --- /dev/null +++ b/doc/uImage.FIT/x86-fit-boot.txt @@ -0,0 +1,276 @@ +Booting Linux on x86 with FIT +============================= + +Background +---------- + +(corrections to the text below are welcome) + +Generally Linux x86 uses its own very complex booting method. There is a setup +binary which contains all sorts of parameters and a compressed self-extracting +binary for the kernel itself, often with a small built-in serial driver to +display decompression progress. + +The x86 CPU has various processor modes. I am no expert on these, but my +understanding is that an x86 CPU (even a really new one) starts up in a 16-bit +'real' mode where only 1MB of memory is visible, moves to 32-bit 'protected' +mode where 4GB is visible (or more with special memory access techniques) and +then to 64-bit 'long' mode if 64-bit execution is required. + +Partly the self-extracting nature of Linux was introduced to cope with boot +loaders that were barely capable of loading anything. Even changing to 32-bit +mode was something of a challenge, so putting this logic in the kernel seemed +to make sense. + +Bit by bit more and more logic has been added to this post-boot pre-Linux +wrapper: + +- Changing to 32-bit mode +- Decompression +- Serial output (with drivers for various chips) +- Load address randomisation +- Elf loader complete with relocation (for the above) +- Random number generator via 3 methods (again for the above) +- Some sort of EFI mini-loader (1000+ glorious lines of code) +- Locating and tacking on a device tree and ramdisk + +To my mind, if you sit back and look at things from first principles, this +doesn't make a huge amount of sense. Any boot loader worth its salts already +has most of the above features and more besides. The boot loader already knows +the layout of memory, has a serial driver, can decompress things, includes an +ELF loader and supports device tree and ramdisks. The decision to duplicate +all these features in a Linux wrapper caters for the lowest common +denominator: a boot loader which consists of a BIOS call to load something off +disk, followed by a jmp instruction. + +(Aside: On ARM systems, we worry that the boot loader won't know where to load +the kernel. It might be easier to just provide that information in the image, +or in the boot loader rather than adding a self-relocator to put it in the +right place. Or just use ELF? + +As a result, the x86 kernel boot process is needlessly complex. The file +format is also complex, and obfuscates the contents to a degree that it is +quite a challenge to extract anything from it. This bzImage format has become +so prevalent that is actually isn't possible to produce the 'raw' kernel build +outputs with the standard Makefile (as it is on ARM for example, at least at +the time of writing). + +This document describes an alternative boot process which uses simple raw +images which are loaded into the right place by the boot loader and then +executed. + + +Build the kernel +---------------- + +Note: these instructions assume a 32-bit kernel. U-Boot does not currently +support booting a 64-bit kernel as it has no way of going into 64-bit mode on +x86. + +You can build the kernel as normal with 'make'. This will create a file called +'vmlinux'. This is a standard ELF file and you can look at it if you like: + +$ objdump -h vmlinux + +vmlinux: file format elf32-i386 + +Sections: +Idx Name Size VMA LMA File off Algn + 0 .text 00416850 81000000 01000000 00001000 2**5 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE + 1 .notes 00000024 81416850 01416850 00417850 2**2 + CONTENTS, ALLOC, LOAD, READONLY, CODE + 2 __ex_table 00000c50 81416880 01416880 00417880 2**3 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 3 .rodata 00154b9e 81418000 01418000 00419000 2**5 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 4 __bug_table 0000597c 8156cba0 0156cba0 0056dba0 2**0 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 5 .pci_fixup 00001b80 8157251c 0157251c 0057351c 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 6 .tracedata 00000024 8157409c 0157409c 0057509c 2**0 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 7 __ksymtab 00007ec0 815740c0 015740c0 005750c0 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 8 __ksymtab_gpl 00004a28 8157bf80 0157bf80 0057cf80 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 9 __ksymtab_strings 0001d6fc 815809a8 015809a8 005819a8 2**0 + CONTENTS, ALLOC, LOAD, READONLY, DATA + 10 __init_rodata 00001c3c 8159e0a4 0159e0a4 0059f0a4 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 11 __param 00000ff0 8159fce0 0159fce0 005a0ce0 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 12 __modver 00000330 815a0cd0 015a0cd0 005a1cd0 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 13 .data 00063000 815a1000 015a1000 005a2000 2**12 + CONTENTS, ALLOC, LOAD, RELOC, DATA + 14 .init.text 0002f104 81604000 01604000 00605000 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE + 15 .init.data 00040cdc 81634000 01634000 00635000 2**12 + CONTENTS, ALLOC, LOAD, RELOC, DATA + 16 .x86_cpu_dev.init 0000001c 81674cdc 01674cdc 00675cdc 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 17 .altinstructions 0000267c 81674cf8 01674cf8 00675cf8 2**0 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 18 .altinstr_replacement 00000942 81677374 01677374 00678374 2**0 + CONTENTS, ALLOC, LOAD, READONLY, CODE + 19 .iommu_table 00000014 81677cb8 01677cb8 00678cb8 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 20 .apicdrivers 00000004 81677cd0 01677cd0 00678cd0 2**2 + CONTENTS, ALLOC, LOAD, RELOC, DATA + 21 .exit.text 00001a80 81677cd8 01677cd8 00678cd8 2**0 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE + 22 .data..percpu 00007880 8167a000 0167a000 0067b000 2**12 + CONTENTS, ALLOC, LOAD, RELOC, DATA + 23 .smp_locks 00003000 81682000 01682000 00683000 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 24 .bss 000a1000 81685000 01685000 00686000 2**12 + ALLOC + 25 .brk 00424000 81726000 01726000 00686000 2**0 + ALLOC + 26 .comment 00000049 00000000 00000000 00686000 2**0 + CONTENTS, READONLY + 27 .GCC.command.line 0003e055 00000000 00000000 00686049 2**0 + CONTENTS, READONLY + 28 .debug_aranges 0000f4c8 00000000 00000000 006c40a0 2**3 + CONTENTS, RELOC, READONLY, DEBUGGING + 29 .debug_info 0440b0df 00000000 00000000 006d3568 2**0 + CONTENTS, RELOC, READONLY, DEBUGGING + 30 .debug_abbrev 0022a83b 00000000 00000000 04ade647 2**0 + CONTENTS, READONLY, DEBUGGING + 31 .debug_line 004ead0d 00000000 00000000 04d08e82 2**0 + CONTENTS, RELOC, READONLY, DEBUGGING + 32 .debug_frame 0010a960 00000000 00000000 051f3b90 2**2 + CONTENTS, RELOC, READONLY, DEBUGGING + 33 .debug_str 001b442d 00000000 00000000 052fe4f0 2**0 + CONTENTS, READONLY, DEBUGGING + 34 .debug_loc 007c7fa9 00000000 00000000 054b291d 2**0 + CONTENTS, RELOC, READONLY, DEBUGGING + 35 .debug_ranges 00098828 00000000 00000000 05c7a8c8 2**3 + CONTENTS, RELOC, READONLY, DEBUGGING + +There is also the setup binary mentioned earlier. This is at +arch/x86/boot/setup.bin and is about 12KB in size. It includes the command +line and various settings need by the kernel. Arguably the boot loader should +provide all of this also, but setting it up is some complex that the kernel +helps by providing a head start. + +As you can see the code loads to address 0x01000000 and everything else +follows after that. We could load this image using the 'bootelf' command but +we would still need to provide the setup binary. This is not supported by +U-Boot although I suppose you could mostly script it. This would permit the +use of a relocatable kernel. + +All we need to boot is the vmlinux file and the setup.bin file. + + +Create a FIT +------------ + +To create a FIT you will need a source file describing what should go in the +FIT. See kernel.its for an example for x86. Put this into a file called +image.its. + +Note that setup is loaded to the special address of 0x90000 (a special address +you just have to know) and the kernel is loaded to 0x01000000 (the address you +saw above). This means that you will need to load your FIT to a different +address so that U-Boot doesn't overwrite it when decompressing. Something like +0x02000000 will do so you can set CONFIG_SYS_LOAD_ADDR to that. + +In that example the kernel is compressed with lzo. Also we need to provide a +flat binary, not an ELF. So the steps needed to set things are are: + + # Create a flat binary + objcopy -O binary vmlinux vmlinux.bin + + # Compress it into LZO format + lzop vmlinux.bin + + # Build a FIT image + mkimage -f image.its image.fit + +(be careful to run the mkimage from your U-Boot tools directory since it +will have x86_setup support.) + +You can take a look at the resulting fit file if you like: + +$ dumpimage -l image.fit +FIT description: Simple image with single Linux kernel on x86 +Created: Tue Oct 7 10:57:24 2014 + Image 0 (kernel@1) + Description: Vanilla Linux kernel + Created: Tue Oct 7 10:57:24 2014 + Type: Kernel Image + Compression: lzo compressed + Data Size: 4591767 Bytes = 4484.15 kB = 4.38 MB + Architecture: Intel x86 + OS: Linux + Load Address: 0x01000000 + Entry Point: 0x00000000 + Hash algo: sha1 + Hash value: 446b5163ebfe0fb6ee20cbb7a8501b263cd92392 + Image 1 (setup@1) + Description: Linux setup.bin + Created: Tue Oct 7 10:57:24 2014 + Type: x86 setup.bin + Compression: uncompressed + Data Size: 12912 Bytes = 12.61 kB = 0.01 MB + Hash algo: sha1 + Hash value: a1f2099cf47ff9816236cd534c77af86e713faad + Default Configuration: 'config@1' + Configuration 0 (config@1) + Description: Boot Linux kernel + Kernel: kernel@1 + + +Booting the FIT +--------------- + +To make it boot you need to load it and then use 'bootm' to boot it. A +suitable script to do this from a network server is: + + bootp + tftp image.fit + bootm + +This will load the image from the network and boot it. The command line (from +the 'bootargs' environment variable) will be passed to the kernel. + +If you want a ramdisk you can add it as normal with FIT. If you want a device +tree then x86 doesn't normally use those - it has ACPI instead. + + +Why Bother? +----------- + +1. It demystifies the process of booting an x86 kernel +2. It allows use of the standard U-Boot boot file format +3. It allows U-Boot to perform decompression - problems will provide an error +message and you are still in the boot loader. It is possible to investigate. +4. It avoids all the pre-loader code in the kernel which is quite complex to +follow +5. You can use verified/secure boot and other features which haven't yet been +added to the pre-Linux +6. It makes x86 more like other architectures in the way it boots a kernel. +You can potentially use the same file format for the kernel, and the same +procedure for building and packaging it. + + +References +---------- + +In the Linux kernel, Documentation/x86/boot.txt defines the boot protocol for +the kernel including the setup.bin format. This is handled in U-Boot in +arch/x86/lib/zimage.c and arch/x86/lib/bootm.c. + +The procedure for entering 64-bit mode on x86 seems to be described here: + + http://wiki.osdev.org/64-bit_Higher_Half_Kernel_with_GRUB_2 + +Various files in the same directory as this file describe the FIT format. + + +-- +Simon Glass +sjg@chromium.org +7-Oct-2014 |