[U-Boot] [PATCH 1/6] add README.distro file

[Stephen Warren <swarren@wwwdotorg.org>]

On 03/20/2014 04:12 PM, Dennis Gilmore wrote:
> Add documentation on how to setup a system to use the generic distro
> configs and boot commands. This spells out what is needed to make a
> system conformant, but does not limit the board to only the defaults.

> diff --git a/doc/README.distro b/doc/README.distro

> +There is some memory addresses you will need to define in
> +CONFIG_EXTRA_ENV_SETTINGS
> +fdt_addr:
> +Optional, If specified a dtb to boot the system must be available at the given
> +address.

Perhaps add "when the kernel is booted"? To avoid someone putting it
somewhere that will get over-written between when U-Boot starts and the
kernel is booted.

> +fdt_addr_r:
> +Mandatory, This is the location where the sysboot/pxeboot with load the dtb to,

s/with/will/ Both here and other place(s).

> +using the fdtdir/devicetreedir or fdt/devicetree options in the pxe/extlinux
> +config file. The location can be anywhere in ram it just needs to not overlap
> +with anything, allowing 1 megabyte seems to be a safe option.

Related to Tom's comments, I think saying that the location doesn't
matter isn't quite true. For example, an ARM zImage assumes it's located
with the first 128M of RAM, and will decompress the image to the start
of RAM. If the DTB was located in the decompression target region, it
would at least need to be moved by the decompressor (wasted effort) or
perhaps just get blindly over-written (boot fails).

> +ramdisk_addr_r:
> +Mandatory, This is the location where the sysboot/pxeboot with load the
> +initramfs to, using the initrd option in the pxe/extlinux config file, the
> +location of the initramfs does not matter, there needs to be enough room to be
> +able to store any image. Making the image the last item stored should allow for
> +any initramfs to fit and not overwrite anything else.

"last item" could refer to time not space. Perhaps s/Making the image
the last item stored/Placing the image higher in RAM than any other image/

> +kernel_addr_r:
> +Mandatory, This is the location where the sysboot/pxeboot with load the kernel
> +to,using the kernel option in the pxe/extlinux config file, the location of the
> +kernel needs to 

That sentence isn't complete.

> +You should not set initrd_high and fdt_high to 0xffffffff as the user should
> +not need to edit the memory locations having the initramfs and dtb being
> +relocatable is best to ensure the system will boot in all situations. 

Perhaps CONFIG_SYS_BOOTMAPSZ is worth a mention too. The commit
description for 7f1b767aea94 "ARM: tegra: define CONFIG_SYS_BOOTMAPSZ"
might be useful when writing this part of the document.

> +booting your system
> +-------------------
> +in the most simplest form CONFIG_BOOTCOMMAND just needs one line
> +
> +"for target in ${boot_targets}; do run bootcmd_${target}; done "
> +
> +you can run any setup before going through the targets for example run a
> +command to set "fdtfile" variable for the dtb for your board.

Isn't this automatic based on using config_distro_defaults.h? It seems
like it should be, and it is were, you wouldn't need this section of
this document at all; it's happen automatically.