diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.gpt | 2 | ||||
| -rw-r--r-- | doc/README.rockchip | 43 | ||||
| -rw-r--r-- | doc/README.scrapyard | 2 | ||||
| -rw-r--r-- | doc/README.ti-secure | 177 | ||||
| -rw-r--r-- | doc/README.ubispl | 141 | ||||
| -rw-r--r-- | doc/README.x86 | 2 | ||||
| -rw-r--r-- | doc/SPL/README.spl-secure-boot | 18 | ||||
| -rw-r--r-- | doc/device-tree-bindings/serial/sh.txt | 6 | ||||
| -rw-r--r-- | doc/driver-model/of-plat.txt | 310 | ||||
| -rw-r--r-- | doc/feature-removal-schedule.txt | 2 |
10 files changed, 643 insertions, 60 deletions
diff --git a/doc/README.gpt b/doc/README.gpt index a6f6de6a0f..3fcd83557f 100644 --- a/doc/README.gpt +++ b/doc/README.gpt @@ -165,7 +165,7 @@ To restore GUID partition table one needs to: The fields 'name' and 'size' are mandatory for every partition. The field 'start' is optional. - If field 'size' of the last partition is 0, the partiton is extended + If field 'size' of the last partition is 0, the partition is extended up to the end of the device. The fields 'uuid' and 'uuid_disk' are optional if CONFIG_RANDOM_UUID is diff --git a/doc/README.rockchip b/doc/README.rockchip index e0572c80b9..c218a8b547 100644 --- a/doc/README.rockchip +++ b/doc/README.rockchip @@ -36,11 +36,12 @@ You will need: Building ======== -At present three RK3288 boards are supported: +At present four RK3288 boards are supported: - Firefly RK3288 - use firefly-rk3288 configuration - Radxa Rock 2 - use rock2 configuration - Hisense Chromebook - use chromebook_jerry configuration + - EVB RK3288 - use evb-rk3288 configuration Two RK3036 board are supported: @@ -119,6 +120,20 @@ something like: Hit any key to stop autoboot: 0 => +The rockchip bootrom can load and boot an initial spl, then continue to +load a second-level bootloader(ie. U-BOOT) as soon as it returns to bootrom. +Therefore RK3288 has another loading sequence like RK3036. The option of +U-Boot is controlled with this setting in U-Boot: + + #define CONFIG_ROCKCHIP_SPL_BACK_TO_BROM + +You can create the image via the following operations: + + ./firefly-rk3288/tools/mkimage -n rk3288 -T rksd -d \ + firefly-rk3288/spl/u-boot-spl-dtb.bin out && \ + cat firefly-rk3288/u-boot-dtb.bin >> out && \ + sudo dd if=out of=/dev/sdc seek=64 + If you have an HDMI cable attached you should see a video console. For evb_rk3036 board: @@ -129,6 +144,32 @@ For evb_rk3036 board: Note: rk3036 SDMMC and debug uart use the same iomux, so if you boot from SD, the debug uart must be disabled +Using fastboot on rk3288 +======================== +- Define GPT partition layout like kylin_rk3036(see include/configs/kylin_rk3036.h) +- Write GPT partition layout to mmc device which fastboot want to use it to +store the image + + => gpt write mmc 1 $partitions + +- Invoke fastboot command to prepare + + => fastboot 1 + +- Start fastboot request on PC + + fastboot -i 0x2207 flash loader evb-rk3288/spl/u-boot-spl-dtb.bin + +You should see something like: + + => fastboot 1 + WARNING: unknown variable: partition-type:loader + Starting download of 357796 bytes + .. + downloading of 357796 bytes finished + Flashing Raw Image + ........ wrote 357888 bytes to 'loader' + Booting from SPI ================ diff --git a/doc/README.scrapyard b/doc/README.scrapyard index b7cf62df9b..200f670806 100644 --- a/doc/README.scrapyard +++ b/doc/README.scrapyard @@ -3,7 +3,7 @@ while other board support code dies a silent death caused by negligence in combination with ordinary bitrot. Sometimes this goes by unnoticed, but often build errors will result. If nobody cares any more to resolve such problems, then the code is really dead and will -be removed from the U-Boot source tree. The remainders rest in piece +be removed from the U-Boot source tree. The remainders rest in peace in the imperishable depths of the git history. This document tries to maintain a list of such former fellows, so archaeologists can check easily if there is something they might want to dig for... diff --git a/doc/README.ti-secure b/doc/README.ti-secure index 7fc9b9bc30..54c996d8f6 100644 --- a/doc/README.ti-secure +++ b/doc/README.ti-secure @@ -19,69 +19,80 @@ control restrictions. Access must be requested and granted by TI before the package is viewable and downloadable. Contact TI, either online or by way of a local TI representative, to request access. -When CONFIG_TI_SECURE_DEVICE is set, the U-Boot SPL build process requires -the presence and use of these tools in order to create a viable boot image. -The build process will look for the environment variable TI_SECURE_DEV_PKG, -which should be the path of the installed SECDEV package. If the -TI_SECURE_DEV_PKG variable is not defined or if it is defined but doesn't -point to a valid SECDEV package, a warning is issued during the build to -indicate that a final secure bootable image was not created. - -Within the SECDEV package exists an image creation script: - -${TI_SECURE_DEV_PKG}/scripts/create-boot-image.sh - -This is called as part of the SPL/u-boot build process. As the secure boot -image formats and requirements differ between secure SOC from TI, the -purpose of this script is to abstract these details as much as possible. - -The script is basically the only required interface to the TI SECDEV package -for secure TI devices. - -Invoking the script for AM43xx Secure Devices -============================================= - -create-boot-image.sh <IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR> - -<IMAGE_FLAG> is a value that specifies the type of the image to generate OR -the action the image generation tool will take. Valid values are: - SPI_X-LOADER - Generates an image for SPI flash (byte swapped) - XIP_X-LOADER - Generates a single stage u-boot for NOR/QSPI XiP - ISSW - Generates an image for all other boot modes - -<INPUT_FILE> is the full path and filename of the public world boot loader -binary file (depending on the boot media, this is usually either -u-boot-spl.bin or u-boot.bin). - -<OUTPUT_FILE> is the full path and filename of the final secure image. The -output binary images should be used in place of the standard non-secure -binary images (see the platform-specific user's guides and releases notes -for how the non-secure images are typically used) +Booting of U-Boot SPL +===================== + + When CONFIG_TI_SECURE_DEVICE is set, the U-Boot SPL build process + requires the presence and use of these tools in order to create a + viable boot image. The build process will look for the environment + variable TI_SECURE_DEV_PKG, which should be the path of the installed + SECDEV package. If the TI_SECURE_DEV_PKG variable is not defined or + if it is defined but doesn't point to a valid SECDEV package, a + warning is issued during the build to indicate that a final secure + bootable image was not created. + + Within the SECDEV package exists an image creation script: + + ${TI_SECURE_DEV_PKG}/scripts/create-boot-image.sh + + This is called as part of the SPL/u-boot build process. As the secure + boot image formats and requirements differ between secure SOC from TI, + the purpose of this script is to abstract these details as much as + possible. + + The script is basically the only required interface to the TI SECDEV + package for creating a bootable SPL image for secure TI devices. + + Invoking the script for AM43xx Secure Devices + ============================================= + + create-boot-image.sh \ + <IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR> + + <IMAGE_FLAG> is a value that specifies the type of the image to + generate OR the action the image generation tool will take. Valid + values are: + SPI_X-LOADER - Generates an image for SPI flash (byte + swapped) + XIP_X-LOADER - Generates a single stage u-boot for + NOR/QSPI XiP + ISSW - Generates an image for all other boot modes + + <INPUT_FILE> is the full path and filename of the public world boot + loaderbinary file (depending on the boot media, this is usually + either u-boot-spl.bin or u-boot.bin). + + <OUTPUT_FILE> is the full path and filename of the final secure + image. The output binary images should be used in place of the standard + non-secure binary images (see the platform-specific user's guides and + releases notes for how the non-secure images are typically used) u-boot-spl_HS_SPI_X-LOADER - byte swapped boot image for SPI flash u-boot_HS_XIP_X-LOADER - boot image for NOR or QSPI flash u-boot-spl_HS_ISSW - boot image for all other boot media -<SPL_LOAD_ADDR> is the address at which SOC ROM should load the <INPUT_FILE> + <SPL_LOAD_ADDR> is the address at which SOC ROM should load the + <INPUT_FILE> -Invoking the script for DRA7xx/AM57xx Secure Devices -==================================================== + Invoking the script for DRA7xx/AM57xx Secure Devices + ==================================================== -create-boot-image.sh <IMAGE_TYPE> <INPUT_FILE> <OUTPUT_FILE> + create-boot-image.sh <IMAGE_TYPE> <INPUT_FILE> <OUTPUT_FILE> -<IMAGE_TYPE> is a value that specifies the type of the image to generate OR -the action the image generation tool will take. Valid values are: - X-LOADER - Generates an image for NOR or QSPI boot modes - MLO - Generates an image for SD/MMC/eMMC boot modes - ULO - Generates an image for USB/UART peripheral boot modes - Note: ULO is not yet used by the u-boot build process + <IMAGE_TYPE> is a value that specifies the type of the image to + generate OR the action the image generation tool will take. Valid + values are: + X-LOADER - Generates an image for NOR or QSPI boot modes + MLO - Generates an image for SD/MMC/eMMC boot modes + ULO - Generates an image for USB/UART peripheral boot modes + Note: ULO is not yet used by the u-boot build process -<INPUT_FILE> is the full path and filename of the public world boot loader -binary file (for this platform, this is always u-boot-spl.bin). + <INPUT_FILE> is the full path and filename of the public world boot + loader binary file (for this platform, this is always u-boot-spl.bin). -<OUTPUT_FILE> is the full path and filename of the final secure image. The -output binary images should be used in place of the standard non-secure -binary images (see the platform-specific user's guides and releases notes -for how the non-secure images are typically used) + <OUTPUT_FILE> is the full path and filename of the final secure image. + The output binary images should be used in place of the standard + non-secure binary images (see the platform-specific user's guides + and releases notes for how the non-secure images are typically used) u-boot-spl_HS_MLO - boot image for SD/MMC/eMMC. This image is copied to a file named MLO, which is the name that the device ROM bootloader requires for loading from @@ -89,3 +100,61 @@ for how the non-secure images are typically used) non-secure devices) u-boot-spl_HS_X-LOADER - boot image for all other flash memories including QSPI and NOR flash + +Booting of Primary U-Boot (u-boot.img) +====================================== + + The SPL image is responsible for loading the next stage boot loader, + which is the main u-boot image. For secure TI devices, the SPL will + be authenticated, as described above, as part of the particular + device's ROM boot process. In order to continue the secure boot + process, the authenticated SPL must authenticate the main u-boot + image that it loads. + + The configurations for secure TI platforms are written to make the boot + process use the FIT image format for the u-boot.img (CONFIG_SPL_FRAMEWORK + and CONFIG_SPL_LOAD_FIT). With these configurations the binary + components that the SPL loads include a specific DTB image and u-boot + image. These DTB image may be one of many available to the boot + process. In order to secure these components so that they can be + authenticated by the SPL as they are loaded from the FIT image, the + build procedure for secure TI devices will secure these images before + they are integrated into the FIT image. When those images are extracted + from the FIT image at boot time, they are post-processed to verify that + they are still secure. The outlined security-related SPL post-processing + is enabled through the CONFIG_SPL_FIT_IMAGE_POST_PROCESS option which + must be enabled for the secure boot scheme to work. In order to allow + verifying proper operation of the secure boot chain in case of successful + authentication messages like "Authentication passed: CERT_U-BOOT-NOD" are + output by the SPL to the console for each blob that got extracted from the + FIT image. Note that the last part of this log message is the (truncated) + name of the signing certificate embedded into the blob that got processed. + + The exact details of the how the images are secured is handled by the + SECDEV package. Within the SECDEV package exists a script to process + an input binary image: + + ${TI_SECURE_DEV_PKG}/scripts/secure-binary-image.sh + + This is called as part of the u-boot build process. As the secure + image formats and requirements can differ between the various secure + SOCs from TI, this script in the SECDEV package abstracts these + details. This script is essentially the only required interface to the + TI SECDEV package for creating a u-boot.img image for secure TI + devices. + + The SPL/u-boot code contains calls to dedicated secure ROM functions + to perform the validation on the secured images. The details of the + interface to those functions is shown in the code. The summary + is that they are accessed by invoking an ARM secure monitor call to + the device's secure ROM (fixed read-only-memory that is secure and + only accessible when the ARM core is operating in the secure mode). + + Invoking the secure-binary-image script for Secure Devices + ========================================================== + + secure-binary-image.sh <INPUT_FILE> <OUTPUT_FILE> + + <INPUT_FILE> is the full path and filename of the input binary image + + <OUTPUT_FILE> is the full path and filename of the output secure image. diff --git a/doc/README.ubispl b/doc/README.ubispl new file mode 100644 index 0000000000..ff008bc311 --- /dev/null +++ b/doc/README.ubispl @@ -0,0 +1,141 @@ +Lightweight UBI and UBI fastmap support + +# Copyright (C) Thomas Gleixner <tglx@linutronix.de> +# +# SPDX-License-Identifier: GPL 2.0+ BSD-3-Clause + +Scans the UBI information and loads the requested static volumes into +memory. + +Configuration Options: + + CONFIG_SPL_UBI + Enables the SPL UBI support + + CONFIG_SPL_UBI_MAX_VOL_LEBS + The maximum number of logical eraseblocks which a static volume + to load can contain. Used for sizing the scan data structure + + CONFIG_SPL_UBI_MAX_PEB_SIZE + The maximum physical erase block size. Either a compile time + constant or runtime detection. Used for sizing the scan data + structure + + CONFIG_SPL_UBI_MAX_PEBS + The maximum physical erase block count. Either a compile time + constant or runtime detection. Used for sizing the scan data + structure + + CONFIG_SPL_UBI_VOL_IDS + The maximum volume ids which can be loaded. Used for sizing the + scan data structure. + +Usage notes: + +In the board config file define for example: + +#define CONFIG_SPL_UBI +#define CONFIG_SPL_UBI_MAX_VOL_LEBS 256 +#define CONFIG_SPL_UBI_MAX_PEB_SIZE (256*1024) +#define CONFIG_SPL_UBI_MAX_PEBS 4096 +#define CONFIG_SPL_UBI_VOL_IDS 8 + +The size requirement is roughly as follows: + + 2k for the basic data structure + + CONFIG_SPL_UBI_VOL_IDS * CONFIG_SPL_UBI_MAX_VOL_LEBS * 8 + + CONFIG_SPL_UBI_MAX_PEBS * 64 + + CONFIG_SPL_UBI_MAX_PEB_SIZE * UBI_FM_MAX_BLOCKS + +The last one is big, but I really don't care in that stage. Real world +implementations only use the first couple of blocks, but the code +handles up to UBI_FM_MAX_BLOCKS. + +Given the above configuration example the requirement is about 5M +which is usually not a problem to reserve in the RAM along with the +other areas like the kernel/dts load address. + +So something like this will do the trick: + +#define SPL_FINFO_ADDR 0x80800000 +#define SPL_DTB_LOAD_ADDR 0x81800000 +#define SPL_KERNEL_LOAD_ADDR 0x82000000 + +In the board file, implement the following: + +static struct ubispl_load myvolumes[] = { + { + .vol_id = 0, /* kernel volume */ + .load_addr = (void *)SPL_KERNEL_LOAD_ADDR, + }, + { + .vol_id = 1, /* DT blob */ + .load_addr = (void *)SPL_DTB_LOAD_ADDR, + } +}; + +int spl_start_uboot(void) +{ + struct ubispl_info info; + + info.ubi = (struct ubi_scan_info *) SPL_FINFO_ADDR; + info.fastmap = 1; + info.read = nand_spl_read_flash; + +#if COMPILE_TIME_DEFINED + /* + * MY_NAND_NR_SPL_PEBS is the number of physical erase blocks + * in the FLASH which are reserved for the SPL. Think about + * mtd partitions: + * + * part_spl { .start = 0, .end = 4 } + * part_ubi { .start = 4, .end = NR_PEBS } + */ + info.peb_offset = MY_NAND_NR_SPL_PEBS; + info.peb_size = CONFIG_SYS_NAND_BLOCK_SIZE; + info.vid_offset = MY_NAND_UBI_VID_OFFS; + info.leb_start = MY_NAND_UBI_DATA_OFFS; + info.peb_count = MY_NAND_UBI_NUM_PEBS; +#else + get_flash_info(&flash_info); + info.peb_offset = MY_NAND_NR_SPL_PEBS; + info.peb_size = flash_info.peb_size; + + /* + * The VID and Data offset depend on the capability of the + * FLASH chip to do subpage writes. + * + * If the flash chip supports subpage writes, then the VID + * header starts at the second subpage. So for 2k pages size + * with 4 subpages the VID offset is 512. The DATA offset is 2k. + * + * If the flash chip does not support subpage writes then the + * VID offset is FLASH_PAGE_SIZE and the DATA offset + * 2 * FLASH_PAGE_SIZE + */ + info.vid_offset = flash_info.vid_offset; + info.leb_start = flash_info.data_offset; + + /* + * The flash reports the total number of erase blocks, so + * we need to subtract the number of blocks which are reserved + * for the SPL itself and not managed by UBI. + */ + info.peb_count = flash_info.peb_count - MY_NAND_NR_SPL_PEBS; +#endif + + ret = ubispl_load_volumes(&info, myvolumes, ARRAY_SIZE(myvolumes); + + .... + +} + +Note: you can load any payload that way. You can even load u-boot from +UBI, so the only non UBI managed FLASH area is the one which is +reserved for the SPL itself and read from the SoC ROM. + +And you can do fallback scenarios: + + if (ubispl_load_volumes(&info, volumes0, ARRAY_SIZE(volumes0))) + if (ubispl_load_volumes(&info, volumes1, ARRAY_SIZE(volumes1))) + ubispl_load_volumes(&info, vol_uboot, ARRAY_SIZE(vol_uboot)); diff --git a/doc/README.x86 b/doc/README.x86 index a548b54b5b..7d694b19cc 100644 --- a/doc/README.x86 +++ b/doc/README.x86 @@ -1020,8 +1020,6 @@ Features not supported so far (to make it a complete ACPI solution): * S3 (Suspend to RAM), S4 (Suspend to Disk). Features that are optional: - * ACPI global NVS support. We may need it to simplify ASL code logic if - utilizing NVS variables. Most likely we will need this sooner or later. * Dynamic AML bytecodes insertion at run-time. We may need this to support SSDT table generation and DSDT fix up. * SMI support. Since U-Boot is a modern bootloader, we don't want to bring diff --git a/doc/SPL/README.spl-secure-boot b/doc/SPL/README.spl-secure-boot new file mode 100644 index 0000000000..f2f8d78883 --- /dev/null +++ b/doc/SPL/README.spl-secure-boot @@ -0,0 +1,18 @@ +Overview of SPL verified boot on powerpc/mpc85xx & arm/layerscape platforms +=========================================================================== + +Introduction +------------ + +This document provides an overview of how SPL verified boot works on powerpc/ +mpc85xx & arm/layerscape platforms. + +Methodology +----------- + +The SPL image is responsible for loading the next stage boot loader, which is +the main u-boot image. For secure boot process on these platforms ROM verifies +SPL image, so to continue chain of trust SPL image verifies U-boot image using +spl_validate_uboot(). This function uses QorIQ Trust Architecture header +(appended to U-boot image) to validate the U-boot binary just before passing +control to it. diff --git a/doc/device-tree-bindings/serial/sh.txt b/doc/device-tree-bindings/serial/sh.txt new file mode 100644 index 0000000000..99634a5e70 --- /dev/null +++ b/doc/device-tree-bindings/serial/sh.txt @@ -0,0 +1,6 @@ +* Renesas SCI serial interface + +Required properties: +- compatible: must be "renesas,scif", "renesas,scifa" or "renesas,sci" +- reg: exactly one register range with length +- clock: input clock frequency for the SCI unit diff --git a/doc/driver-model/of-plat.txt b/doc/driver-model/of-plat.txt new file mode 100644 index 0000000000..86e5e25300 --- /dev/null +++ b/doc/driver-model/of-plat.txt @@ -0,0 +1,310 @@ +Driver Model Compiled-in Device Tree / Platform Data +==================================================== + + +Introduction +------------ + +Device tree is the standard configuration method in U-Boot. It is used to +define what devices are in the system and provide configuration information +to these devices. + +The overhead of adding device tree access to U-Boot is fairly modest, +approximately 3KB on Thumb 2 (plus the size of the DT itself). This means +that in most cases it is best to use device tree for configuration. + +However there are some very constrained environments where U-Boot needs to +work. These include SPL with severe memory limitations. For example, some +SoCs require a 16KB SPL image which must include a full MMC stack. In this +case the overhead of device tree access may be too great. + +It is possible to create platform data manually by defining C structures +for it, and reference that data in a U_BOOT_DEVICE() declaration. This +bypasses the use of device tree completely, effectively creating a parallel +configuration mechanism. But it is an available option for SPL. + +As an alternative, a new 'of-platdata' feature is provided. This converts the +device tree contents into C code which can be compiled into the SPL binary. +This saves the 3KB of code overhead and perhaps a few hundred more bytes due +to more efficient storage of the data. + +Note: Quite a bit of thought has gone into the design of this feature. +However it still has many rough edges and comments and suggestions are +strongly encouraged! Quite possibly there is a much better approach. + + +Caveats +------- + +There are many problems with this features. It should only be used when +strictly necessary. Notable problems include: + + - Device tree does not describe data types. But the C code must define a + type for each property. These are guessed using heuristics which + are wrong in several fairly common cases. For example an 8-byte value + is considered to be a 2-item integer array, and is byte-swapped. A + boolean value that is not present means 'false', but cannot be + included in the structures since there is generally no mention of it + in the device tree file. + + - Naming of nodes and properties is automatic. This means that they follow + the naming in the device tree, which may result in C identifiers that + look a bit strange. + + - It is not possible to find a value given a property name. Code must use + the associated C member variable directly in the code. This makes + the code less robust in the face of device-tree changes. It also + makes it very unlikely that your driver code will be useful for more + than one SoC. Even if the code is common, each SoC will end up with + a different C struct name, and a likely a different format for the + platform data. + + - The platform data is provided to drivers as a C structure. The driver + must use the same structure to access the data. Since a driver + normally also supports device tree it must use #ifdef to separate + out this code, since the structures are only available in SPL. + + +How it works +------------ + +The feature is enabled by CONFIG SPL_OF_PLATDATA. This is only available +in SPL and should be tested with: + + #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA) + +A new tool called 'dtoc' converts a device tree file either into a set of +struct declarations, one for each compatible node, or a set of +U_BOOT_DEVICE() declarations along with the actual platform data for each +device. As an example, consider this MMC node: + + sdmmc: dwmmc@ff0c0000 { + compatible = "rockchip,rk3288-dw-mshc"; + clock-freq-min-max = <400000 150000000>; + clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>, + <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>; + clock-names = "biu", "ciu", "ciu_drv", "ciu_sample"; + fifo-depth = <0x100>; + interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; + reg = <0xff0c0000 0x4000>; + bus-width = <4>; + cap-mmc-highspeed; + cap-sd-highspeed; + card-detect-delay = <200>; + disable-wp; + num-slots = <1>; + pinctrl-names = "default"; + pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>; + vmmc-supply = <&vcc_sd>; + status = "okay"; + u-boot,dm-pre-reloc; + }; + + +Some of these properties are dropped by U-Boot under control of the +CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce +the following C struct declaration: + +struct dtd_rockchip_rk3288_dw_mshc { + fdt32_t bus_width; + bool cap_mmc_highspeed; + bool cap_sd_highspeed; + fdt32_t card_detect_delay; + fdt32_t clock_freq_min_max[2]; + struct phandle_2_cell clocks[4]; + bool disable_wp; + fdt32_t fifo_depth; + fdt32_t interrupts[3]; + fdt32_t num_slots; + fdt32_t reg[2]; + fdt32_t vmmc_supply; +}; + +and the following device declaration: + +static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = { + .fifo_depth = 0x100, + .cap_sd_highspeed = true, + .interrupts = {0x0, 0x20, 0x4}, + .clock_freq_min_max = {0x61a80, 0x8f0d180}, + .vmmc_supply = 0xb, + .num_slots = 0x1, + .clocks = {{&dtv_clock_controller_at_ff760000, 456}, + {&dtv_clock_controller_at_ff760000, 68}, + {&dtv_clock_controller_at_ff760000, 114}, + {&dtv_clock_controller_at_ff760000, 118}}, + .cap_mmc_highspeed = true, + .disable_wp = true, + .bus_width = 0x4, + .u_boot_dm_pre_reloc = true, + .reg = {0xff0c0000, 0x4000}, + .card_detect_delay = 0xc8, +}; +U_BOOT_DEVICE(dwmmc_at_ff0c0000) = { + .name = "rockchip_rk3288_dw_mshc", + .platdata = &dtv_dwmmc_at_ff0c0000, + .platdata_size = sizeof(dtv_dwmmc_at_ff0c0000), +}; + +The device is then instantiated at run-time and the platform data can be +accessed using: + + struct udevice *dev; + struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_platdata(dev); + +This avoids the code overhead of converting the device tree data to +platform data in the driver. The ofdata_to_platdata() method should +therefore do nothing in such a driver. + + +Converting of-platdata to a useful form +--------------------------------------- + +Of course it would be possible use the of-platdata directly in your driver +whenever configuration information is required. However this meands that the +driver will not be able to support device tree, since the of-platdata +structure is not available when device tree is used. It would make no sense +to use this structure if device tree were available, since the structure has +all the limitations metioned in caveats above. + +Therefore it is recommended that the of-platdata structure should be used +only in the probe() method of your driver. It cannot be used in the +ofdata_to_platdata() method since this is not called when platform data is +already present. + + +How to structure your driver +---------------------------- + +Drivers should always support device tree as an option. The of-platdata +feature is intended as a add-on to existing drivers. + +Your driver should convert the platdata struct in its probe() method. The +existing device tree decoding logic should be kept in the +ofdata_to_platdata() method and wrapped with #if. + +For example: + + #include <dt-structs.h> + + struct mmc_platdata { + #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA) + /* Put this first since driver model will copy the data here */ + struct dtd_mmc dtplat; + #endif + /* + * Other fields can go here, to be filled in by decoding from + * the device tree (or the C structures when of-platdata is used). + */ + int fifo_depth; + }; + + static int mmc_ofdata_to_platdata(struct udevice *dev) + { + #if !CONFIG_IS_ENABLED(SPL_OF_PLATDATA) + /* Decode the device tree data */ + struct mmc_platdata *plat = dev_get_platdata(dev); + const void *blob = gd->fdt_blob; + int node = dev->of_offset; + + plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0); + #endif + + return 0; + } + + static int mmc_probe(struct udevice *dev) + { + struct mmc_platdata *plat = dev_get_platdata(dev); + + #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA) + /* Decode the of-platdata from the C structures */ + struct dtd_mmc *dtplat = &plat->dtplat; + + plat->fifo_depth = dtplat->fifo_depth; + #endif + /* Set up the device from the plat data */ + writel(plat->fifo_depth, ...) + } + + static const struct udevice_id mmc_ids[] = { + { .compatible = "vendor,mmc" }, + { } + }; + + U_BOOT_DRIVER(mmc_drv) = { + .name = "mmc", + .id = UCLASS_MMC, + .of_match = mmc_ids, + .ofdata_to_platdata = mmc_ofdata_to_platdata, + .probe = mmc_probe, + .priv_auto_alloc_size = sizeof(struct mmc_priv), + .platdata_auto_alloc_size = sizeof(struct mmc_platdata), + }; + + +In the case where SPL_OF_PLATDATA is enabled, platdata_auto_alloc_size is +still used to allocate space for the platform data. This is different from +the normal behaviour and is triggered by the use of of-platdata (strictly +speaking it is a non-zero platdata_size which triggers this). + +The of-platdata struct contents is copied from the C structure data to the +start of the newly allocated area. In the case where device tree is used, +the platform data is allocated, and starts zeroed. In this case the +ofdata_to_platdata() method should still set up the platform data (and the +of-platdata struct will not be present). + +SPL must use either of-platdata or device tree. Drivers cannot use both at +the same time, but they must support device tree. Supporting of-platdata is +optional. + +The device tree becomes in accessible when CONFIG_SPL_OF_PLATDATA is enabled, +since the device-tree access code is not compiled in. A corollary is that +a board can only move to using of-platdata if all the drivers it uses support +it. There would be little point in having some drivers require the device +tree data, since then libfdt would still be needed for those drivers and +there would be no code-size benefit. + +Internals +--------- + +The dt-structs.h file includes the generated file +(include/generated//dt-structs.h) if CONFIG_SPL_OF_PLATDATA is enabled. +Otherwise (such as in U-Boot proper) these structs are not available. This +prevents them being used inadvertently. All usage must be bracketed with +#if CONFIG_IS_ENABLED(SPL_OF_PLATDATA). + +The dt-platdata.c file contains the device declarations and is is built in +spl/dt-platdata.c. + +Some phandles (thsoe that are recognised as such) are converted into +points to platform data. This pointer can potentially be used to access the +referenced device (by searching for the pointer value). This feature is not +yet implemented, however. + +The beginnings of a libfdt Python module are provided. So far this only +implements a subset of the features. + +The 'swig' tool is needed to build the libfdt Python module. If this is not +found then the Python model is not used and a fallback is used instead, which +makes use of fdtget. + + +Credits +------- + +This is an implementation of an idea by Tom Rini <trini@konsulko.com>. + + +Future work +----------- +- Consider programmatically reading binding files instead of device tree + contents +- Complete the phandle feature +- Move to using a full Python libfdt module + +-- +Simon Glass <sjg@chromium.org> +Google, Inc +6/6/16 +Updated Independence Day 2016 diff --git a/doc/feature-removal-schedule.txt b/doc/feature-removal-schedule.txt index 4ed30df707..b5a70da296 100644 --- a/doc/feature-removal-schedule.txt +++ b/doc/feature-removal-schedule.txt @@ -12,7 +12,7 @@ When: Release v2013.10 Why: As the 'mtest' command is no longer default, a number of platforms have not opted to turn the command back on and thus provide unused - defines (which are likely to be propogated to new platforms from + defines (which are likely to be propagated to new platforms from copy/paste). Remove these defines when unused. Who: Tom Rini <trini@ti.com> |