diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.android-fastboot | 91 | ||||
| -rw-r--r-- | doc/README.android-fastboot-protocol | 170 | ||||
| -rw-r--r-- | doc/README.atmel_pmecc | 21 | ||||
| -rw-r--r-- | doc/README.generic-board | 2 | ||||
| -rw-r--r-- | doc/README.gpt | 14 | ||||
| -rw-r--r-- | doc/git-mailrc | 2 |
6 files changed, 292 insertions, 8 deletions
diff --git a/doc/README.android-fastboot b/doc/README.android-fastboot new file mode 100644 index 0000000000..f1d128caa9 --- /dev/null +++ b/doc/README.android-fastboot @@ -0,0 +1,91 @@ +Android Fastboot +~~~~~~~~~~~~~~~~ + +Overview +======== +The protocol that is used over USB is described in +README.android-fastboot-protocol in same directory. + +The current implementation does not yet support the flash and erase +commands. + +Client installation +=================== +The counterpart to this gadget is the fastboot client which can +be found in Android's platform/system/core repository in the fastboot +folder. It runs on Windows, Linux and even OSX. Linux user are lucky since +they only need libusb. +Windows users need to bring some time until they have Android SDK (currently +http://dl.google.com/android/installer_r12-windows.exe) installed. You +need to install ADB package which contains the required glue libraries for +accessing USB. Also you need "Google USB driver package" and "SDK platform +tools". Once installed the usb driver is placed in your SDK folder under +extras\google\usb_driver. The android_winusb.inf needs a line like + + %SingleBootLoaderInterface% = USB_Install, USB\VID_0451&PID_D022 + +either in the [Google.NTx86] section for 32bit Windows or [Google.NTamd64] +for 64bit Windows. VID and PID should match whatever the fastboot is +advertising. + +Board specific +============== +The fastboot gadget relies on the USB download gadget, so the following +options must be configured: + +CONFIG_USBDOWNLOAD_GADGET +CONFIG_G_DNL_VENDOR_NUM +CONFIG_G_DNL_PRODUCT_NUM +CONFIG_G_DNL_MANUFACTURER + +The fastboot function is enabled by defining CONFIG_CMD_FASTBOOT and +CONFIG_ANDROID_BOOT_IMAGE. + +The fastboot protocol requires a large memory buffer for downloads. This +buffer should be as large as possible for a platform. The location of the +buffer and size are set with CONFIG_USB_FASTBOOT_BUF_ADDR and +CONFIG_USB_FASTBOOT_BUF_SIZE. + +In Action +========= +Enter into fastboot by executing the fastboot command in u-boot and you +should see: +|GADGET DRIVER: usb_dnl_fastboot + +On the client side you can fetch the bootloader version for instance: +|>fastboot getvar bootloader-version +|bootloader-version: U-Boot 2014.04-00005-gd24cabc +|finished. total time: 0.000s + +or initiate a reboot: +|>fastboot reboot + +and once the client comes back, the board should reset. + +You can also specify a kernel image to boot. You have to either specify +the an image in Android format _or_ pass a binary kernel and let the +fastboot client wrap the Android suite around it. On OMAP for instance you +take zImage kernel and pass it to the fastboot client: + +|>fastboot -b 0x80000000 -c "console=ttyO2 earlyprintk root=/dev/ram0 +| mem=128M" boot zImage +|creating boot image... +|creating boot image - 1847296 bytes +|downloading 'boot.img'... +|OKAY [ 2.766s] +|booting... +|OKAY [ -0.000s] +|finished. total time: 2.766s + +and on the gadget side you should see: +|Starting download of 1847296 bytes +|........................................................ +|downloading of 1847296 bytes finished +|Booting kernel.. +|## Booting Android Image at 0x81000000 ... +|Kernel load addr 0x80008000 size 1801 KiB +|Kernel command line: console=ttyO2 earlyprintk root=/dev/ram0 mem=128M +| Loading Kernel Image ... OK +|OK +| +|Starting kernel ... diff --git a/doc/README.android-fastboot-protocol b/doc/README.android-fastboot-protocol new file mode 100644 index 0000000000..e9e7166a26 --- /dev/null +++ b/doc/README.android-fastboot-protocol @@ -0,0 +1,170 @@ +FastBoot Version 0.4 +---------------------- + +The fastboot protocol is a mechanism for communicating with bootloaders +over USB. It is designed to be very straightforward to implement, to +allow it to be used across a wide range of devices and from hosts running +Linux, Windows, or OSX. + + +Basic Requirements +------------------ + +* Two bulk endpoints (in, out) are required +* Max packet size must be 64 bytes for full-speed and 512 bytes for + high-speed USB +* The protocol is entirely host-driven and synchronous (unlike the + multi-channel, bi-directional, asynchronous ADB protocol) + + +Transport and Framing +--------------------- + +1. Host sends a command, which is an ascii string in a single + packet no greater than 64 bytes. + +2. Client response with a single packet no greater than 64 bytes. + The first four bytes of the response are "OKAY", "FAIL", "DATA", + or "INFO". Additional bytes may contain an (ascii) informative + message. + + a. INFO -> the remaining 60 bytes are an informative message + (providing progress or diagnostic messages). They should + be displayed and then step #2 repeats + + b. FAIL -> the requested command failed. The remaining 60 bytes + of the response (if present) provide a textual failure message + to present to the user. Stop. + + c. OKAY -> the requested command completed successfully. Go to #5 + + d. DATA -> the requested command is ready for the data phase. + A DATA response packet will be 12 bytes long, in the form of + DATA00000000 where the 8 digit hexidecimal number represents + the total data size to transfer. + +3. Data phase. Depending on the command, the host or client will + send the indicated amount of data. Short packets are always + acceptable and zero-length packets are ignored. This phase continues + until the client has sent or received the number of bytes indicated + in the "DATA" response above. + +4. Client responds with a single packet no greater than 64 bytes. + The first four bytes of the response are "OKAY", "FAIL", or "INFO". + Similar to #2: + + a. INFO -> display the remaining 60 bytes and return to #4 + + b. FAIL -> display the remaining 60 bytes (if present) as a failure + reason and consider the command failed. Stop. + + c. OKAY -> success. Go to #5 + +5. Success. Stop. + + +Example Session +--------------- + +Host: "getvar:version" request version variable + +Client: "OKAY0.4" return version "0.4" + +Host: "getvar:nonexistant" request some undefined variable + +Client: "OKAY" return value "" + +Host: "download:00001234" request to send 0x1234 bytes of data + +Client: "DATA00001234" ready to accept data + +Host: < 0x1234 bytes > send data + +Client: "OKAY" success + +Host: "flash:bootloader" request to flash the data to the bootloader + +Client: "INFOerasing flash" indicate status / progress + "INFOwriting flash" + "OKAY" indicate success + +Host: "powerdown" send a command + +Client: "FAILunknown command" indicate failure + + +Command Reference +----------------- + +* Command parameters are indicated by printf-style escape sequences. + +* Commands are ascii strings and sent without the quotes (which are + for illustration only here) and without a trailing 0 byte. + +* Commands that begin with a lowercase letter are reserved for this + specification. OEM-specific commands should not begin with a + lowercase letter, to prevent incompatibilities with future specs. + + "getvar:%s" Read a config/version variable from the bootloader. + The variable contents will be returned after the + OKAY response. + + "download:%08x" Write data to memory which will be later used + by "boot", "ramdisk", "flash", etc. The client + will reply with "DATA%08x" if it has enough + space in RAM or "FAIL" if not. The size of + the download is remembered. + + "verify:%08x" Send a digital signature to verify the downloaded + data. Required if the bootloader is "secure" + otherwise "flash" and "boot" will be ignored. + + "flash:%s" Write the previously downloaded image to the + named partition (if possible). + + "erase:%s" Erase the indicated partition (clear to 0xFFs) + + "boot" The previously downloaded data is a boot.img + and should be booted according to the normal + procedure for a boot.img + + "continue" Continue booting as normal (if possible) + + "reboot" Reboot the device. + + "reboot-bootloader" Reboot back into the bootloader. + Useful for upgrade processes that require upgrading + the bootloader and then upgrading other partitions + using the new bootloader. + + "powerdown" Power off the device. + + + +Client Variables +---------------- + +The "getvar:%s" command is used to read client variables which +represent various information about the device and the software +on it. + +The various currently defined names are: + + version Version of FastBoot protocol supported. + It should be "0.3" for this document. + + version-bootloader Version string for the Bootloader. + + version-baseband Version string of the Baseband Software + + product Name of the product + + serialno Product serial number + + secure If the value is "yes", this is a secure + bootloader requiring a signature before + it will install or boot images. + +Names starting with a lowercase character are reserved by this +specification. OEM-specific names should not start with lowercase +characters. diff --git a/doc/README.atmel_pmecc b/doc/README.atmel_pmecc index cf8373b54e..cc0f73db8f 100644 --- a/doc/README.atmel_pmecc +++ b/doc/README.atmel_pmecc @@ -27,3 +27,24 @@ Take AT91SAM9X5EK as an example, the board definition file likes: #define CONFIG_ATMEL_NAND_HW_PMECC 1 #define CONFIG_PMECC_CAP 2 #define CONFIG_PMECC_SECTOR_SIZE 512 + +How to enable PMECC header for direct programmable boot.bin +----------------------------------------------------------- +2014-05-19 Andreas Bießmann <andreas.devel@googlemail.com> + +The usual way to program SPL into NAND flash is to use the SAM-BA Atmel tool. +This however is often not usable when doing field updates. To be able to +program a SPL binary into NAND flash we need to add the PMECC header to the +binary before. Chapter '12.4.4.1 NAND Flash Boot: NAND Flash Detection' in +sama5d3 SoC spec (as of 03. April 2014) defines how this PMECC header has to +look like. In order to do so we have a new image type added to mkimage to +generate this PMECC header and integrated this into the build process of SPL. + +To enable the generation of atmel PMECC header for SPL one need to define +CONFIG_SPL_GENERATE_ATMEL_PMECC_HEADER. The required parameters are taken from +board configuration and compiled into the host tools atmel_pmecc_params. This +tool will be called in build process to parametrize mkimage for atmelimage +type. The mkimage tool has intentionally _not_ compiled in those parameters. + +The mkimage image type atmelimage also set the 6'th interrupt vector to the +correct value. This feature can also be used to setup a boot.bin for MMC boot. diff --git a/doc/README.generic-board b/doc/README.generic-board index 50d3a26849..17da0b9f87 100644 --- a/doc/README.generic-board +++ b/doc/README.generic-board @@ -17,7 +17,7 @@ architecture-specific board.c file before October 2014. Background ---------- -U-Boot has tranditionally had a board.c file for each architecture. This has +U-Boot has traditionally had a board.c file for each architecture. This has introduced quite a lot of duplication, with each architecture tending to do initialisation slightly differently. To address this, a new 'generic board init' feature was introduced a year ago in March 2013 (further motivation is diff --git a/doc/README.gpt b/doc/README.gpt index f822894709..ec0156d8aa 100644 --- a/doc/README.gpt +++ b/doc/README.gpt @@ -66,14 +66,14 @@ GPT brief explanation: |Partition n | | | ---------------------------------------------------------- - LBA -34 |Entry 1|Entry 2| Entry 3| Entry 4| Secondary - -------------------------------------------------- (bkp) - LBA -33 |Entries 5 - 128 | GPT + LBA -34 |Entry 1|Entry 2| Entry 3| Entry 4| Backup + -------------------------------------------------- GPT + LBA -33 |Entries 5 - 128 | | | | | LBA -2 | | -------------------------------------------------- - LBA -1 |Secondary GPT Header | + LBA -1 |Backup GPT Header | ---------------------------------------------------------- For a legacy reasons, GPT's LBA 0 sector has a MBR structure. It is called @@ -86,7 +86,7 @@ It is possible to define 128 linearly placed partition entries. "LBA -1" means the last addressable block (in the mmc subsystem: "dev_desc->lba - 1") -Primary/Secondary GPT header: +Primary/Backup GPT header: ---------------------------- Offset Size Description @@ -115,7 +115,7 @@ IMPORTANT: GPT headers and partition entries are protected by CRC32 (the POSIX CRC32). -Primary GPT header and Secondary GPT header have swapped values of "Current LBA" +Primary GPT header and Backup GPT header have swapped values of "Current LBA" and "Backup LBA" and therefore different CRC32 check-sum. CRC32 for GPT headers (field "CRC of header") are calculated up till @@ -125,7 +125,7 @@ CRC32 for partition entries (field "CRC32 of partition array") is calculated for the whole array entry ( Number_of_partition_entries * sizeof(partition_entry_size (usually 128))) -Observe, how Secondary GPT is placed in the memory. It is NOT a mirror reflect +Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect of the Primary. Partition Entry Format: diff --git a/doc/git-mailrc b/doc/git-mailrc index 251586e052..e53c888351 100644 --- a/doc/git-mailrc +++ b/doc/git-mailrc @@ -22,6 +22,7 @@ alias jagan Jagannadha Sutradharudu Teki <jagannadh.teki@gmail.com> alias jasonjin Jason Jin <jason.jin@freescale.com> alias jhersh Joe Hershberger <joe.hershberger@gmail.com> alias kimphill Kim Phillips <kim.phillips@freescale.com> +alias lukma Lukasz Majewski <l.majewski@samsung.com> alias macpaul Macpaul Lin <macpaul@andestech.com> alias marex Marek Vasut <marex@denx.de> alias monstr Michal Simek <monstr@monstr.eu> @@ -101,6 +102,7 @@ alias x86 uboot, sjg, gruss # Subsystem aliases alias cfi uboot, stroese +alias dfu uboot, lukma alias kerneldoc uboot, marex alias fdt uboot, Jerry Van Baren <vanbaren@cideas.com> alias i2c uboot, hs |