diff options
| author | Sascha Hauer <s.hauer@pengutronix.de> | 2014-06-17 10:37:25 +0200 |
|---|---|---|
| committer | Sascha Hauer <s.hauer@pengutronix.de> | 2014-06-26 11:07:10 +0200 |
| commit | 3fef396bb42efc0bb12b0a8caf0d076ab1c4d879 (patch) | |
| tree | 91625b2407ed25dffd093b19159135481eb80f84 /Documentation | |
| parent | 7e65163b9165bccca780da91fad247c0e4ac7f9f (diff) | |
| download | barebox-3fef396bb42efc0bb12b0a8caf0d076ab1c4d879.tar.gz barebox-3fef396bb42efc0bb12b0a8caf0d076ab1c4d879.tar.xz | |
Documentation: Add new sphinxs docs
This is a rewrite of the Documentation in reStructuredText format using
Sphinx as build system, see http://sphinx-doc.org/.
The documentation is built into static html pages with 'make docs'.
The pages can be found under Documentation/html after building.
Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>
Diffstat (limited to 'Documentation')
61 files changed, 2935 insertions, 0 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 1936cc1d44..1454566002 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -1 +1,2 @@ +build html diff --git a/Documentation/boards.rst b/Documentation/boards.rst new file mode 100644 index 0000000000..78e4951ab1 --- /dev/null +++ b/Documentation/boards.rst @@ -0,0 +1,10 @@ +.. _boards: + +Board support +============= + +.. toctree:: + :glob: + :maxdepth: 2 + + boards/* diff --git a/Documentation/boards/cirrus-logic.rst b/Documentation/boards/cirrus-logic.rst new file mode 100644 index 0000000000..95a961e244 --- /dev/null +++ b/Documentation/boards/cirrus-logic.rst @@ -0,0 +1,9 @@ +Cirrus Logic edb9xxx +==================== + +.. toctree:: + :glob: + :numbered: + :maxdepth: 1 + + edb9xxx/* diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9301.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9301.rst new file mode 100644 index 0000000000..78c2d30c79 --- /dev/null +++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9301.rst @@ -0,0 +1,10 @@ +Cirrus Logic EP9301 +=================== + +This boards is based on a Cirrus Logic EP9301 CPU. The board is shipped with: + + * 16MiB NOR type Flash Memory + * 32MiB synchronous dynamic RAM on CS3 + * 128kiB serial EEPROM + * MII 10/100 Ethernet PHY + * Stereo audio codec diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9302.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9302.rst new file mode 100644 index 0000000000..43dfb83da4 --- /dev/null +++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9302.rst @@ -0,0 +1,10 @@ +Cirrus Logic EDB9302 +==================== + +This board is based on a Cirrus Logic EP9302 CPU. The board is shipped with: + + * 16MiB NOR type Flash Memory + * 32MiB synchronous dynamic RAM on CS3 + * 128kiB serial EEPROM + * MII 10/100 Ethernet PHY + * Stereo audio codec diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9302a.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9302a.rst new file mode 100644 index 0000000000..7283536ea1 --- /dev/null +++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9302a.rst @@ -0,0 +1,10 @@ +Cirrus Logic EDB9302A +===================== + +This board is based on a Cirrus Logic EP9302 CPU. The board is shipped with: + + * 16MiB NOR type Flash Memory + * 32MiB synchronous dynamic RAM on CS0 + * 512kiB serial EEPROM + * MII 10/100 Ethernet PHY + * Stereo audio codec diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9307.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9307.rst new file mode 100644 index 0000000000..9006f2c9ce --- /dev/null +++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9307.rst @@ -0,0 +1,13 @@ +Cirrus Logic EDB9307 +==================== + +This board is based on a Cirrus Logic EP9307 CPU. The board is shipped with: + + * 32MiB NOR type Flash Memory + * 64MiB synchronous dynamic RAM on CS3 + * 512kiB asynchronous SRAM + * 128kiB serial EEPROM + * MII 10/100 Ethernet PHY + * Stereo audio codec + * Real-Time Clock + * IR receiver diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9307a.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9307a.rst new file mode 100644 index 0000000000..ba3763c386 --- /dev/null +++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9307a.rst @@ -0,0 +1,13 @@ +Cirrus Logic EDB9307A +===================== + +This board is based on a Cirrus Logic EP9307 CPU. The board is shipped with: + + * 32MiB NOR type Flash Memory + * 64MiB synchronous dynamic RAM on CS0 + * 512kiB serial EEPROM + * MII 10/100 Ethernet PHY + * Stereo audio codec + * Real-Time Clock + * IR receiver + diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9312.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9312.rst new file mode 100644 index 0000000000..16ad7fbbf9 --- /dev/null +++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9312.rst @@ -0,0 +1,13 @@ +Cirrus Logic EDB9312 +==================== + +This board is based on a Cirrus Logic EP9312 CPU. The board is shipped with: + + * 32MiB NOR type Flash Memory + * 64MiB synchronous dynamic RAM on CS3 + * 512kiB asynchronous SRAM + * 128kiB serial EEPROM + * MII 10/100 Ethernet PHY + * Stereo audio codec + * Real-Time Clock + * IR receiver diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9315.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9315.rst new file mode 100644 index 0000000000..5adb96696b --- /dev/null +++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9315.rst @@ -0,0 +1,13 @@ +Cirrus Logic EDB9315 +==================== + +This board is based on a Cirrus Logic EP9315 CPU. The board is shipped with: + + * 32MiB NOR type Flash Memory + * 64MiB synchronous dynamic RAM on CS3 + * 512kiB asynchronous SRAM + * 128kiB serial EEPROM + * MII 10/100 Ethernet PHY + * Stereo audio codec + * Real-Time Clock + * IR receiver diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9315a.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9315a.rst new file mode 100644 index 0000000000..c44f873859 --- /dev/null +++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9315a.rst @@ -0,0 +1,12 @@ +Cirrus Logic EDB9315A +===================== + +This board is based on a Cirrus Logic EP9315 CPU. The board is shipped with: + + * 32MiB NOR type Flash Memory + * 64MiB synchronous dynamic RAM on CS0 + * 128kiB serial EEPROM + * MII 10/100 Ethernet PHY + * Stereo audio codec + * Real-Time Clock + * IR receiver diff --git a/Documentation/boards/imx.rst b/Documentation/boards/imx.rst new file mode 100644 index 0000000000..c6b208728e --- /dev/null +++ b/Documentation/boards/imx.rst @@ -0,0 +1,103 @@ +Freescale i.MX +============== + +Freescale i.MX is traditionally very good supported under barebox. +Depending on the SoC there are different Boot Modes supported. Older +SoCs up to i.MX31 only support the external Boot Mode. Newer SoCs +can be configured for internal or external Boot Mode with the internal +boot mode being the more popular mode. The i.MX23 and i.MX28, also +known as i.MXs, are special. These SoCs have a completely different +boot mechanism. + +Internal Boot Mode +------------------ + +The Internal Boot Mode is supported on: + +* i.MX25 +* i.MX35 +* i.MX51 +* i.MX53 +* i.MX6 + +With the Internal Boot Mode the images contain a header which describes +where the binary shall be loaded and started. Also these headers contain +a so called DCD table which consists of register/value pairs. These are +executed by the Boot ROM and are used to configure the SDRAM. In barebox +the i.MX images are generated with the ``scripts/imx/imx-image`` tool. +Normally it's not necessary to call this tool manually, it is executed +automatically at the end of the build process. + +The images generated by the build process can be directly written to an +SD card:: + + # with Multi Image support: + cat images/barebox-freescale-imx51-babbage.img > /dev/sdd + # otherwise: + cat barebox-flash-image > /dev/sdd + +This will overwrite the partition table on the card. It can be preserved +with:: + + dd if=images/barebox-freescale-imx51-babbage.img of=/dev/sdd bs=512 skip=1 seek=1 + +The images can also always be started second stage:: + + bootm /mnt/tftp/barebox-freescale-imx51-babbage.img + +USB Boot +^^^^^^^^ + +Most boards can be explicitly configured for USB Boot Mode or fall back +to USB Boot when no other medium can be found. The barebox repository +contains a USB upload tool. As it depends on the libusb development headers +it is not built by default. Enable it explicitly in ``make menuconfig`` +and install the libusb development package. On Debian this can be done +with ``apt-get install libusb-dev``. After compilation the tool can be used +with only the image name as argument:: + + scripts/imx/imx-usb-loader images/barebox-freescale-imx51-babbage.img + +External Boot Mode +------------------ + +The External Boot Mode is supported by the older i.MX SoCs: + +* i.MX1 +* i.MX21 +* i.MX27 +* i.MX31 + +(It may be supported on newer SoCs aswell, but it is not widely used there) + +The External Boot Mode only supports booting from NOR and NAND flash. On NOR +flash the binary is started directly on its physical address in memory. Booting +from NAND flash is more complicated. The NAND flash controller copies the first +2kb of the image to the NAND Controllers internal SRAM. This initial binary +portion is then has to: + +* Set up the SDRAM +* Copy the initial binary to SDRAM to make the internal SRAM in the NAND flash + controller free for use for the controller +* Copy the whole barebox image to SDRAM +* Start the image + +It is possible to write the image directly to NAND. However, since NAND flash +can have bad blocks which must be skipped during writing the image and also +by the initial loader, it is recommended to use the :ref:`command_barebox_update` +command for writing to NAND flash. + +i.MX boards +----------- + +Not supported all boards have a description here. Many newer boards also do +not have individual defconfig files, they are covered by ``imx_v7_defconfig`` +or ``imx_defconfig`` instead. + +.. toctree:: + :glob: + :numbered: + :maxdepth: 1 + + imx/* + mxs/* diff --git a/Documentation/boards/imx/Garz-Fricke-Cupid.rst b/Documentation/boards/imx/Garz-Fricke-Cupid.rst new file mode 100644 index 0000000000..1328810bd3 --- /dev/null +++ b/Documentation/boards/imx/Garz-Fricke-Cupid.rst @@ -0,0 +1,9 @@ +Garz+Fricke Cupid +================= + +This CPU card is based on a Freescale i.MX35 CPU. The card is shipped with: + + * 256MiB Nand flash + * 128MiB synchronous dynamic RAM + +see http://www.garz-fricke.com/cupid-core_de.html for more information diff --git a/Documentation/boards/imx/Phytec-phyCORE-i.MX31.rst b/Documentation/boards/imx/Phytec-phyCORE-i.MX31.rst new file mode 100644 index 0000000000..527c49045f --- /dev/null +++ b/Documentation/boards/imx/Phytec-phyCORE-i.MX31.rst @@ -0,0 +1,38 @@ +Phytec phyCORE-i.MX31 CPU module PCM-037 +======================================== + +The CPU module +-------------- + +http://www.phytec.eu/europe/products/modules-overview/phycore/produktdetails/p/phycore-imx31-2.html + +This CPU card is based on a Freescale i.MX31 CPU. The card in configuration -0000REU is shipped with: + + * 128 MiB synchronous dynamic RAM (DDR type) + * 64 MiB NAND flash + * 32 MiB NOR flash + * 512 kiB SRAM + * 4kiB EEPROM + * MMU, FPU + * Serial, Ethernet, USB (OTG), I2C, SPI, MMC/SD/SDIO, PCMCIA/CF, RTC + +Supported baseboards +-------------------- + +Supported baseboards are: + * Silica / Phytec PCM-970 via phyMAP-i.MX31, PMA-001 + +How to get barebox for 'Phytec's phyCORE-i.MX31' +------------------------------------------------ + +Using the default configuration:: + + make ARCH=arm pcm037_defconfig + +Build the binary image:: + + make ARCH=arm CROSS_COMPILE=armv5compiler + +**NOTE** Replace ''armv5compiler'' with your ARM v5 cross compiler, e.g.: ''arm-1136jfs-linux-gnueabi-'' + +The resulting binary image to be flashed will be barebox.bin, whereas the file named just barebox is an ELF executable for ARM. diff --git a/Documentation/boards/imx/eukrea_cpuimx27.rst b/Documentation/boards/imx/eukrea_cpuimx27.rst new file mode 100644 index 0000000000..c5ab4b94b7 --- /dev/null +++ b/Documentation/boards/imx/eukrea_cpuimx27.rst @@ -0,0 +1,11 @@ +Eukrea CPUIMX27 +=============== + +This CPU card is based on a Freescale i.MX27 CPU. The card is shipped with: + + * up to 64MiB NOR type Flash Memory + * up to 256MiB synchronous dynamic RAM + * up to 512MiB NAND type Flash Memory + * MII 10/100 ethernet PHY + * optional 16554 Quad UART on CS3 + diff --git a/Documentation/boards/imx/synertronixx_scb9328.rst b/Documentation/boards/imx/synertronixx_scb9328.rst new file mode 100644 index 0000000000..229b3d0a1e --- /dev/null +++ b/Documentation/boards/imx/synertronixx_scb9328.rst @@ -0,0 +1,12 @@ +Synertronixx scb9328 +==================== + +See http://www.synertronixx.de/produkte/scb9328/scb9328.htm + +This CPU card is based on a Freescale i.MX1 CPU. The card is shipped with: + + * 16MiB NOR type Flash Memory + * 16MiB synchronous dynamic RAM + * DM9000 network controller + +It's the first i.MX board sha has ever ported Linux to. diff --git a/Documentation/boards/mxs/Chumby-Falconwing.rst b/Documentation/boards/mxs/Chumby-Falconwing.rst new file mode 100644 index 0000000000..73e4c302f0 --- /dev/null +++ b/Documentation/boards/mxs/Chumby-Falconwing.rst @@ -0,0 +1,46 @@ +chumbyone Chumby Industrie's Falconwing +======================================= + +This device is also known as "chumby one" (http://www.chumby.com/) + +This CPU card is based on a Freescale i.MX23 CPU. The card is shipped with: + + * 64 MiB synchronous dynamic RAM (DDR type) + +Memory layout when @b barebox is running: + + * 0x40000000 start of SDRAM + * 0x40000100 start of kernel's boot parameters + * below malloc area: stack area + * below barebox: malloc area + * 0x42000000 start of @b barebox + +How to get the bootloader binary image +-------------------------------------- + +Using the default configuration:: + + make ARCH=arm chumbyone_defconfig + +Build the bootloader binary image:: + + make ARCH=arm CROSS_COMPILE=armv5compiler + +NOTE replace the armv5compiler with your ARM v5 cross compiler. + +How to prepare an MCI card to boot the "chumby one" with barebox +---------------------------------------------------------------- + + * Create four primary partitions on the MCI card + * the first one for the bootlets (about 256 kiB) + * the second one for the persistant environment (size is up to you, at least 256k) + * the third one for the kernel (2 MiB ... 4 MiB in size) + * the 4th one for the root filesystem which can fill the rest of the available space + + * Mark the first partition with the partition ID "53" and copy the bootlets into this partition (currently not part of @b barebox!). + + * Copy the default @b barebox environment into the second partition (no filesystem required). + + * Copy the kernel into the third partition (no filesystem required). + + * Create the root filesystem in the 4th partition. You may copy an image into this partition or you can do it in the classic way: mkfs on it, mount it and copy all required data and programs into it. diff --git a/Documentation/boards/mxs/Freescale-i.MX23-evk.rst b/Documentation/boards/mxs/Freescale-i.MX23-evk.rst new file mode 100644 index 0000000000..b03508c0bb --- /dev/null +++ b/Documentation/boards/mxs/Freescale-i.MX23-evk.rst @@ -0,0 +1,28 @@ +Freescale i.MX23 evaluation kit +=============================== + +This CPU card is based on an i.MX23 CPU. The card is shipped with: + + * 32 MiB synchronous dynamic RAM (mobile DDR type) + * ENC28j60 based network (over SPI) + +Memory layout when @b barebox is running: + + * 0x40000000 start of SDRAM + * 0x40000100 start of kernel's boot parameters + * below malloc area: stack area + * below barebox: malloc area + * 0x41000000 start of @b barebox + +How to get the bootloader binary image +-------------------------------------- + +Using the default configuration:: + + make ARCH=arm imx23evk_defconfig + +Build the bootloader binary image:: + + make ARCH=arm CROSS_COMPILE=armv5compiler + +**NOTE** replace the armv5compiler with your ARM v5 cross compiler. diff --git a/Documentation/boards/mxs/KaRo-TX28.rst b/Documentation/boards/mxs/KaRo-TX28.rst new file mode 100644 index 0000000000..a6c308c7e6 --- /dev/null +++ b/Documentation/boards/mxs/KaRo-TX28.rst @@ -0,0 +1,48 @@ +KARO TX28 CPU module +==================== + +The CPU module +-------------- + +http://www.karo-electronics.de/ + +This CPU card is based on a Freescale i.MX28 CPU. The card is shipped with: + + * 128 MiB synchronous dynamic RAM (DDR2 type), 200 MHz support + * 128 MiB NAND K9F1G08U0A (3.3V type) + * PCA9554 GPIO expander + * DS1339 RTC + * LAN8710 Phy + +Supported baseboards +-------------------- + +Supported baseboards are: + * KARO's Starterkit 5 + +How to get barebox for 'KARO's Starterkit 5' +-------------------------------------------- + +Using the default configuration:: + + make ARCH=arm tx28stk5_defconfig + +Build the binary image:: + + make ARCH=arm CROSS_COMPILE=armv5compiler + +**NOTE** replace the armv5compiler with your ARM v5 cross compiler. + +**NOTE** To use the result, you also need the following resources from Freescale: + * the 'bootlets' archive + * the 'elftosb2' encryption tool + * in the case you want to start @b barebox from an attached SD card the 'sdimage' tool from Freescale's 'uuc' archive. + +Memory layout when barebox is running +------------------------------------- + + * 0x40000000 start of SDRAM + * 0x40000100 start of kernel's boot parameters + * below malloc area: stack area + * below barebox: malloc area + * 0x47000000 start of @b barebox diff --git a/Documentation/boards/omap.rst b/Documentation/boards/omap.rst new file mode 100644 index 0000000000..63caf66f5a --- /dev/null +++ b/Documentation/boards/omap.rst @@ -0,0 +1,40 @@ +Texas Instruments OMAP/AM335x +============================= + +Texas Intruments OMAP SoCs have a two staged boot process. The first stage is +known as Xload which only loads the second stage bootloader. barebox can act as +both the first and the second stage loader. To build as a first stage loader +build the \*_xload_defconfig for your board, for second stage build the normal +\*_defconfig for your board. + +bootstrapping a panda board +--------------------------- + +The Panda board boots from SD card. The OMAP Boot ROM code loads a file named +'MLO' on a bootable FAT partition on this card. There are several howtos and +scripts on the net which describe how to prepare such a card (it needs a +special partitioning). The same procedure can be used for barebox. With such a +card (assumed to be at /dev/sdc) the following can be used to build and install +barebox:: + + # mount -t fat /dev/sdc1 /mnt + # make panda_xload_defconfig + # make + # cp barebox.bin.ift /mnt/MLO + # make panda_defconfig + # make + # cp barebox.bin /mnt/barebox.bin + # umount /mnt + +Bootstrapping a Beagle board is the same with the corresponding Beagle board defconfigs + +Networking +---------- + +The Beagle board does not have ethernet, but a USB ethernet dongle can be used +for networking. the Panda board has an integrated USB ethernet converter which +exactly behaves like an external dongle. Barebox does not automatically detect +USB devices as this would have bad effects on boot time when USB is not needed. +So you have to use the [[commands:usb|usb]] command to trigger USB detection. +After this a network device should be present which can be used with the normal +[[commands:dhcp|dhcp]] and [[commands:tftp|tftp]] commands. diff --git a/Documentation/boards/s3c/Digi-a9m2440.rst b/Documentation/boards/s3c/Digi-a9m2440.rst new file mode 100644 index 0000000000..4ed8ae4101 --- /dev/null +++ b/Documentation/boards/s3c/Digi-a9m2440.rst @@ -0,0 +1,67 @@ +DIGI a9m2440 +============ + +This CPU card is based on a Samsung S3C2440 CPU. The card is shipped with: + + * S3C2440\@400 MHz or 533 MHz (ARM920T/ARMv4T) + * 16.9344 MHz crystal reference + * SDRAM 32/64/128 MiB + * Samsung K4M563233E-EE1H (one or two devices for 32 MiB or 64 MiB) + * 2M x 32bit x 4 Banks Mobile SDRAM + * CL2\@100 MHz (CAS/RAS delay 19ns) + * 105 MHz max + * column address size is 9 bits + * Row cycle time: 69ns + * Samsung K4M513233C-DG75 (one or two devices for 64 MiB or 128 MiB) + * 4M x 32bit x 4 Banks Mobile SDRAM + * CL2\@100MHz (CAS/RAS delay 18ns) + * 111 MHz max + * column address size is 9 bits + * Row cycle time: 63ns + * 64ms refresh period (4k) + * 90 pin FBGA + * 32 bit data bits + * Extended temperature range (-25°C...85°C) + * NAND Flash 32/64/128 MiB + * Samsung KM29U512T (NAND01GW3A0AN6) + * 64 MiB 3,3V 8-bit + * ID: 0xEC, 0x76, 0x??, 0xBD + * Samsung KM29U256T + * 32 MiB 3,3V 8-bit + * ID: 0xEC, 0x75, 0x??, 0xBD + * ST Micro + * 128 MiB 3,3V 8-bit + * ID: 0x20, 0x79 + * 30ns/40ns/20ns + * I2C interface, 100 KHz and 400 KHz + * Real Time Clock + * Dallas DS1337 + * address 0x68 + * EEPROM + * ST M24LC64 + * address 0x50 + * 16bit addressing + * LCD interface + * Touch Screen interface + * Camera interface + * I2S interface + * AC97 Audio-CODEC interface + * SD card interface + * 3 serial RS232 interfaces + * Host and device USB interface, USB1.1 compliant + * Ethernet interface + * 10Mbps, Cirrus Logic, CS8900A (on the CPU card) + * SPI interface + * JTAG interface + +How to get the binary image: + +Using the default configuration:: + + make ARCH=arm a9m2440_defconfig + +Build the binary image:: + + make ARCH=arm CROSS_COMPILE=armv4compiler + +**NOTE** replace the armv4compiler with your ARM v4 cross compiler. diff --git a/Documentation/boards/samsung.rst b/Documentation/boards/samsung.rst new file mode 100644 index 0000000000..d75224f780 --- /dev/null +++ b/Documentation/boards/samsung.rst @@ -0,0 +1,9 @@ +Samsung S3C/S5P +=============== + +.. toctree:: + :glob: + :numbered: + :maxdepth: 1 + + s3c/* diff --git a/Documentation/boards/sandbox.rst b/Documentation/boards/sandbox.rst new file mode 100644 index 0000000000..4601aedbc0 --- /dev/null +++ b/Documentation/boards/sandbox.rst @@ -0,0 +1,67 @@ +Sandbox +======= + +barebox can be run as a simulator on your host to check and debug new non +hardware related features. + +Build barebox for simulation +---------------------------- + +the barebox sand box can be built with the host compiler:: + + ARCH=sandbox make sandbox_defconfig + ARCH=sandbox make + +Run sandbox +----------- + +:: + + $ barebox [\<OPTIONS\>] + +Options can be:: + + -m, --malloc=\<size\> + +Start sandbox with a specified malloc-space \<size\> in bytes. + +:: + + -i \<file\> + +Map a \<file\> to barebox. This option can be given multiple times. The \<file\>s +will show up as /dev/fd0 ... /dev/fdx in the barebox simulator. + +:: + + -e \<file\> + +Map \<file\> to barebox. With this option \<file\>s are mapped as /dev/env0 ... +/dev/envx and thus are used as default environment. A clean file generated +with dd will do to get started with an empty environment + +:: + + -O \<file\> + +Register \<file\> as a console capable of doing stdout. \<file\> can be a +regular file or a fifo. + +:: + + -I \<file\> + +Register \<file\> as a console capable of doing stdin. \<file\> can be a regular +file or a fifo. + +:: + + -x, --xres \<res\> + +Specify SDL width + +:: + + -y, --yres \<res\> + +Specify SDL height diff --git a/Documentation/boards/tegra.rst b/Documentation/boards/tegra.rst new file mode 100644 index 0000000000..f28c506a69 --- /dev/null +++ b/Documentation/boards/tegra.rst @@ -0,0 +1,102 @@ +.. highlight:: console + +Nvidia Tegra +============ + +Building +-------- + +All currently supported Tegra boards are integrated in a single +multi-image build (:ref:`multi_image`). Building is as easy as typing: + +.. code-block:: sh + + make ARCH=arm tegra_v7_defconfig + make ARCH=arm CROSS_COMPILE=arm-v7-compiler- + +**NOTE** replace the arm-v7-compiler- with your ARM v7 cross compiler. + +Tegra images are specific to the bootsource. The build will generate images for +all combinations of bootsources and supported boards. You can find the +completed images in the ``images/`` subdirectory. + +The naming scheme consists of the triplet tegracodename-boardname-bootsource + +Kickstarting a board using USB +------------------------------ + +The tool needed to transfer and start a bootloader image to any Tegra board +using the USB boot mode is called TegraRCM. Most likely this isn't available +from your distributions repositories. You can get and install it by running the +following commands: + +.. code-block:: sh + + git clone https://github.com/NVIDIA/tegrarcm.git + cd tegrarcm + ./autogen.sh + make + sudo make install + +Connect the board to your host via the USB OTG port. +The next step is to bring the device into USB boot mode. On developer boards +this could normally be done by holding down a force recovery button (or setting +some jumper) while resetting the board. On other devices you are on your own +finding out how to achieve this. + +The tegrarcm tool has 3 basic options: + +.. code-block:: none + + --bct : the BCT file needed for basic hardware init, + this can be found in the respective board directory + --bootloader : the actual barebox image + use the -usbloader image + --loadaddr : start address of the barebox image + use 0x00108000 for Tegra20 aka Tegra2 devices + use 0x80108000 for all other Tegra devices + +An example command line for the NVIDIA Beaver board looks like this: + +.. code-block:: sh + + tegrarcm --bct arch/arm/boards/nvidia-beaver/beaver-2gb-emmc.bct \ + --bootloader images/barebox-tegra30-nvidia-beaver-usbloader.img \ + --loadaddr 0x80108000 + +You should now see barebox coming up on the serial console. + +Writing barebox to the primary boot device +------------------------------------------ + +**NOTE** This may change in the near future to work with the standard +barebox update mechanism (:ref:`update`). + +Copy the image corresponding to the primary boot device for your board to a +SD-card and plug it into your board. + +Within the barebox shell use the standard mount and cp commands to copy the +image to the boot device. + +On the NVIDIA Beaver board this looks like this: + +.. code-block:: sh + + barebox@NVIDIA Tegra30 Beaver evaluation board:/ mount -a + mci0: detected SD card version 2.0 + mci0: registered disk0 + mci1: detected MMC card version 4.65 + mci1: registered disk1.boot0 + mci1: registered disk1.boot1 + mci1: registered disk1 + ext4 ext40: EXT2 rev 1, inode_size 128 + ext4 ext41: EXT2 rev 1, inode_size 256 + ext4 ext42: EXT2 rev 1, inode_size 256 + none on / type ramfs + none on /dev type devfs + /dev/disk0.0 on /mnt/disk0.0 type ext4 + /dev/disk0.1 on /mnt/disk0.1 type ext4 + /dev/disk1.1 on /mnt/disk1.1 type ext4 + barebox@NVIDIA Tegra30 Beaver evaluation board:/ cp /mnt/disk0.0/barebox-tegra30-nvidia-beaver-emmc.img /dev/disk1.boot0 + +That's it: barebox should come up after resetting the board. diff --git a/Documentation/boards/x86.rst b/Documentation/boards/x86.rst new file mode 100644 index 0000000000..5d38955001 --- /dev/null +++ b/Documentation/boards/x86.rst @@ -0,0 +1,128 @@ +x86 +=== + +Features +-------- + +barebox can act as a bootloader for PC based systems. In this case a special +binary layout will be created to be able to store it on some media the PC +BIOS can boot from. It can boot Linux kernels stored also on the same boot +media and be configured at runtime, with the possibility to store the changed +configuration on the boot media. + +Restrictions +------------ + +Due to some BIOS and barebox restrictions the boot media must be +prepared in some special way: + + * barebox must be stored in the MBR (Master Boot Record) of the boot media. Currently its not possible to store and boot it in one of the partition sectors to use it as a second stage loader). This is no eternal restriction. It only needs further effort to add this feature. + * barebox currently cannot run a chained boot loader. Also, this is no external restriction, only further effort needed. + * barebox comes with limited filesystem support. There is currently no support for the most common and popular filesystems used in the \*NIX world. This restricts locations where to store a kernel and other runtime information + * barebox must be stored to the first n sectors of the boot media. To ensure this does not collide with partitions on the boot media, the first partition must start at a sector behind the ones barebox occupies. + * barebox handles its runtime configuration in a special way: It stores it in a binary way into some reserved sectors ("persistant storage"). + +Boot Preparations +----------------- + +To store the barebox image to a boot media, it comes with the tool +setupmbr in the directory scripts/setupmbr/ . To be able to use it on +the boot media of your choice, some preparations are required. + +Keep Sectors free +----------------- + +Build the barebox image and check its size. At least this amount of +sectors must be kept free after the MBR prior the first partition. Do this +simple calulation:: + + sectors = (\<size of barebox image\> + 511) / 512 + +To be able to store the runtime configuration, further free sectors are +required. Its up to you and your requirements, how large this persistant +storage must be. If you need 16 kiB for this purpose, you need to keep +additional 32 sectors free. + +For this example we are reserving 300 sectors for the barebox image and +additionaly 32 sectors for the persistant storage. So, the first partition on +the boot media must start at sector 333 or later. + +Run the fdisk tool to setup such a partition table:: + + + [jb@host]~> fdisk /dev/sda + Command (m for help): p + + Disk /dev/sda: 20.7 MB, 212680704 bytes + 16 heads, 63 sectors/track, 406 cylinders + Units = cylinders of 1008 * 512 = 516096 bytes + + Device Boot Start End Blocks Id System + +Change the used units to sectors for easier handling. + +:: + + Command (m for help): u + Changing display/entry units to sectors + + Command (m for help): p + + Disk /dev/sda: 20.7 MB, 212680704 bytes + 16 heads, 63 sectors/track, 406 cylinders, total 409248 sectors + Units = sectors of 1 * 512 = 512 bytes + + Device Boot Start End Blocks Id System + +Now its possible to create the first partition with the required offset:: + + Command (m for help): n + Command action + e extended + p primary partition (1-4) + p + Partition number (1-4): 1 + First sector (63-409247, default 63): 333 + Last sector or +size or +sizeM or +sizeK (333-409247, default 409247): +18M + Command (m for help): p + + Disk /dev/sda: 20.7 MB, 212680704 bytes + 16 heads, 63 sectors/track, 406 cylinders, total 409248 sectors + Units = sectors of 1 * 512 = 512 bytes + + Device Boot Start End Blocks Id System + /dev/sda 333 35489 17578+ 83 Linux + +That's all. Do whatever is required now with the new partition (formatting +and populating the root filesystem for example) to make it useful. + +In the next step, barebox gets installed to this boot media:: + + [jb@host]~> scripts/setupmbr/setupmbr -s 32 -m ./barebox -d /dev/sda + +This command writes the barebox image file './barebox' onto the device + /dev/sda. + +The -s option will keep the persistant storage sectors free and untouched +and set flags in the MBR to forward its existance, size and location to +barebox at runtime. setupmbr also does not change the partition table. + +The barebox image gets stored on the boot media like this:: + + sector 0 1 33 333 + |---|-------------|--------------- ~~~ ------------|-------------- + MBR persistant barebox first + storage main image partition + +If the -s option is omitted, the "persistant storage" part simply does +not exist:: + + sector 0 1 333 + |---|--------------- ~~~ ------------|-------------- + MBR barebox first + main image partition + +**NOTE** The setupmbr tool is also working on real image file than on device + nodes only. So, there is no restriction what kind of file will be + modified. + diff --git a/Documentation/commands.rst b/Documentation/commands.rst new file mode 100644 index 0000000000..a649209e39 --- /dev/null +++ b/Documentation/commands.rst @@ -0,0 +1,9 @@ +barebox command reference +========================= + +.. toctree:: + :glob: + :maxdepth: 1 + + commands/* + diff --git a/Documentation/conf.py b/Documentation/conf.py new file mode 100644 index 0000000000..0292c720a7 --- /dev/null +++ b/Documentation/conf.py @@ -0,0 +1,262 @@ +# -*- coding: utf-8 -*- +# +# barebox documentation build configuration file, created by +# sphinx-quickstart on Tue Jun 17 11:45:57 2014. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'barebox' +copyright = u'2014, The barebox project' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +import os + +version = os.environ["KERNELVERSION"] +# The full version, including alpha/beta/rc tags. +release = os.environ["KERNELRELEASE"] + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'bareboxdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'barebox.tex', u'barebox Documentation', + u'The barebox project', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'barebox', u'barebox Documentation', + [u'The barebox project'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'barebox', u'barebox Documentation', + u'The barebox project', 'barebox', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + +highlight_language = 'c' diff --git a/Documentation/devicetree/bindings/README b/Documentation/devicetree/bindings/README new file mode 100644 index 0000000000..b818ee8243 --- /dev/null +++ b/Documentation/devicetree/bindings/README @@ -0,0 +1,6 @@ + +barebox uses the same devicetree bindings as the kernel. For +the bindings derived from the kernel look in the kernel sources +for reference. + +barebox specific bindings are documented here. diff --git a/Documentation/devicetree/bindings/barebox/barebox,environment.rst b/Documentation/devicetree/bindings/barebox/barebox,environment.rst new file mode 100644 index 0000000000..d243484d90 --- /dev/null +++ b/Documentation/devicetree/bindings/barebox/barebox,environment.rst @@ -0,0 +1,25 @@ +barebox environment +=================== + +This driver provides an environment for barebox from the devicetree. + +Required properties: +- compatible: should be "barebox,environment" +- device-path: path to the environment + +The device-path is a multistring property. The first string should be a +nodepath to the node containing the physical device of the environment. +The subsequent strings are of the form <type>:<options> to further describe +the path to the environment. Supported values for <type>: + +partname:<partname> This describes a partition on a device. <partname> can + be the label for mtd partitions, the number for DOS + partitions (beginning with 0) or the name for GPT + partitions + +Example:: + + environment@0 { + compatible = "barebox,environment"; + device-path = &flash, "partname:barebox-environment"; + }; diff --git a/Documentation/devicetree/bindings/leds/common.rst b/Documentation/devicetree/bindings/leds/common.rst new file mode 100644 index 0000000000..63a45bda5c --- /dev/null +++ b/Documentation/devicetree/bindings/leds/common.rst @@ -0,0 +1,9 @@ +Common leds properties +====================== + +- linux,default-trigger barebox,default-trigger: This parameter, if present, is a + string defining the trigger assigned to the LED. Current triggers are: + "heartbeat" - LED flashes at a constant rate + "panic" - LED turns on when barebox panics + "net" - LED indicates network activity + diff --git a/Documentation/devicetree/bindings/misc/fsl,imx-iim.rst b/Documentation/devicetree/bindings/misc/fsl,imx-iim.rst new file mode 100644 index 0000000000..a067579189 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/fsl,imx-iim.rst @@ -0,0 +1,21 @@ +Freescale i.MX IIM (Ic Identification Module) +============================================= + +Required properties: + +- compatible: fsl,imx27-iim +- reg: physical register base and size + +Optional properties: + +- barebox,provide-mac-address: Provide MAC addresses for ethernet devices. This + can be multiple entries in the form <&phandle bankno fuseofs> to specify a MAC + address to a ethernet device. + +Example:: + + iim: iim@83f98000 { + compatible = "fsl,imx51-iim", "fsl,imx27-iim"; + reg = <0x83f98000 0x4000>; + barebox,provide-mac-address = <&fec 1 9>; + }; diff --git a/Documentation/devicetree/bindings/misc/fsl,imx-ocotp.rst b/Documentation/devicetree/bindings/misc/fsl,imx-ocotp.rst new file mode 100644 index 0000000000..472b9e251f --- /dev/null +++ b/Documentation/devicetree/bindings/misc/fsl,imx-ocotp.rst @@ -0,0 +1,21 @@ +Freescale i.MX OCOTP (On-Chip OTP) +================================== + +Required properties: + +- compatible: fsl,imx6q-ocotp +- reg: physical register base and size + +Optional properties: + +- barebox,provide-mac-address: Provide MAC addresses for ethernet devices. This + can be multiple entries in the form <&phandle regofs> to specify a MAC + address to a ethernet device. + +Example:: + + ocotp1: ocotp@021bc000 { + compatible = "fsl,imx6q-ocotp"; + reg = <0x021bc000 0x4000>; + barebox,provide-mac-address = <&fec 0x620>; + }; diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst new file mode 100644 index 0000000000..a24d635fde --- /dev/null +++ b/Documentation/devicetree/index.rst @@ -0,0 +1,13 @@ +barebox specific devicetree bindings +==================================== + +Contents: + +.. toctree:: + :glob: + :numbered: + :maxdepth: 1 + + bindings/barebox/* + bindings/leds/* + bindings/misc/* diff --git a/Documentation/download.rst b/Documentation/download.rst new file mode 100644 index 0000000000..9e30efeda3 --- /dev/null +++ b/Documentation/download.rst @@ -0,0 +1,16 @@ +:: _download: + +Getting barebox +=============== + +Releases of barebox can be downloaded here: + +http://barebox.org/download/ + +git +--- + +The barebox development repository is available via `git <http://git-scm.com/>`_ here: + + * clone address git://git.pengutronix.de/git/barebox.git + * git web http://git.pengutronix.de/?p=barebox.git;a=summary diff --git a/Documentation/filesystems.rst b/Documentation/filesystems.rst new file mode 100644 index 0000000000..3bb1edfb16 --- /dev/null +++ b/Documentation/filesystems.rst @@ -0,0 +1,10 @@ +.. _filesystems: + +filesystems +=========== + +.. toctree:: + :maxdepth: 2 + :glob: + + filesystems/* diff --git a/Documentation/filesystems/fat.rst b/Documentation/filesystems/fat.rst new file mode 100644 index 0000000000..2138328d18 --- /dev/null +++ b/Documentation/filesystems/fat.rst @@ -0,0 +1,15 @@ +.. index:: fat (filesystem) + +FAT filesystem +============== + +barebox supports FAT filesystems in both read and write modes with optional +support for long filenames. A FAT filesystem can be mounted using the +:ref:`command_mount` command:: + + mkdir /mnt + mount /dev/disk0.0 fat /mnt + ls /mnt + zImage barebox.bin + umount /mnt + diff --git a/Documentation/filesystems/nfs.rst b/Documentation/filesystems/nfs.rst new file mode 100644 index 0000000000..b8ad4f3fe3 --- /dev/null +++ b/Documentation/filesystems/nfs.rst @@ -0,0 +1,12 @@ +.. index:: nfs (filesystem) + +.. _filesystems_nfs: + +NFS Support +=========== + +barebox has readonly support for NFSv3 un UDP mode. + +Example:: + + mount -t nfs 192.168.23.4:/home/user/nfsroot /mnt/nfs diff --git a/Documentation/filesystems/ramfs.rst b/Documentation/filesystems/ramfs.rst new file mode 100644 index 0000000000..37d6ffc8c7 --- /dev/null +++ b/Documentation/filesystems/ramfs.rst @@ -0,0 +1,10 @@ +.. index:: ramfs (filesystem) + +ram filesystem +============== + +ramfs is a simple malloc based filesystem. An instance of ramfs is mounted during startup on /. The filesystemtype passed to mount is 'ramfs' + +example:: + + mount none ramfs /somedir diff --git a/Documentation/filesystems/tftp.rst b/Documentation/filesystems/tftp.rst new file mode 100644 index 0000000000..273be5ee2a --- /dev/null +++ b/Documentation/filesystems/tftp.rst @@ -0,0 +1,16 @@ +.. index:: tftp (filesystem) + +.. _filesystems_tftp: + +TFTP support +============ + +barebox has read/write support for the Trivial File Transfer Protocol. + +TFTP is not designed as a filesystem. It does not have support for listing +directories. This means a :ref:`command_ls` to a TFTP mounted path will show an empty +directory. Nevertheless the files are there. + +Example:: + + mount -t tftp 192.168.23.4 /mnt/tftp diff --git a/Documentation/gen_commands.py b/Documentation/gen_commands.py new file mode 100755 index 0000000000..4e33ccaea6 --- /dev/null +++ b/Documentation/gen_commands.py @@ -0,0 +1,164 @@ +#!/usr/bin/python + +import os +import re +import sys + +from collections import defaultdict +from pprint import pprint + +# TODO: handle commands with the same name in multiple files +# TODO: handle #ifdefs + +HELP_START = re.compile(r"""^BAREBOX_CMD_HELP_START\s*\((\w+)\)?\s*$""") +HELP_TEXT = re.compile(r"""^BAREBOX_CMD_HELP_TEXT\s*\("(.*?)"\)?\s*$""") +HELP_OPT = re.compile(r"""^BAREBOX_CMD_HELP_OPT\s*\("(.+?)",\s*"(.+?)"\)?\s*$""") +HELP_END = re.compile(r"""^BAREBOX_CMD_HELP_END\s*$""") + +CMD_START = re.compile(r"""^BAREBOX_CMD_START\s*\((.+)\)\s*$""") +CMD_FUNC = re.compile(r"""^\s*\.cmd\s*=\s*(.+?),\s*$""") +CMD_DESC = re.compile(r"""^\s*BAREBOX_CMD_DESC\s*\("(.*?)"\)?\s*$""") +CMD_OPTS = re.compile(r"""^\s*BAREBOX_CMD_OPTS\s*\("(.*?)"\)?\s*$""") +CMD_GROUP = re.compile(r"""^\s*BAREBOX_CMD_GROUP\s*\((.+)\)\s*$""") +CMD_END = re.compile(r"""^BAREBOX_CMD_END\s*$""") + +CONT = re.compile(r"""\s*"(.*?)"\s*\)?\s*$""") + +CMDS = {} + +def parse_c(name): + cmd = None + last = None + for line in file(name, 'r'): + x = HELP_START.match(line) + if x: + cmd = CMDS.setdefault(x.group(1), defaultdict(list)) + cmd.setdefault("files", set()).add(name) + continue + x = CMD_START.match(line) + if x: + cmd = CMDS.setdefault(x.group(1), defaultdict(list)) + cmd.setdefault("files", set()).add(name) + continue + if cmd is None: + continue + x = HELP_TEXT.match(line) + if x: + if 'h_opts' not in cmd: + last = cmd['h_pre'] + else: + last = cmd['h_post'] + last.append(x.group(1).decode("string_escape").strip()) + continue + x = HELP_OPT.match(line) + if x: + last = cmd['h_opts'] + last.append([ + x.group(1).decode("string_escape"), + x.group(2).decode("string_escape") + ]) + continue + x = CMD_FUNC.match(line) + if x: + last = cmd['c_func'] + last.append(x.group(1)) + continue + x = CMD_DESC.match(line) + if x: + last = cmd['c_desc'] + last.append(x.group(1).decode("string_escape")) + continue + x = CMD_OPTS.match(line) + if x: + last = cmd['c_opts'] + last.append(x.group(1).decode("string_escape")) + continue + x = CMD_GROUP.match(line) + if x: + last = cmd['c_group'] + last.append(x.group(1).decode("string_escape")) + continue + x = CONT.match(line) + if x: + if last is None: + raise Exception("Parse error in %s: %r" % (name, line)) + if isinstance(last[-1], str): + last[-1] += x.group(1).decode("string_escape") + elif isinstance(last[-1], list): + last[-1][1] += x.group(1).decode("string_escape") + continue + x = HELP_END.match(line) + if x: + cmd = last = None + x = CMD_END.match(line) + if x: + cmd = last = None + +def gen_rst(name, cmd): + out = [] + out.append('.. index:: %s (command)' % name) + out.append('') + out.append('.. _command_%s:' % name) + out.append('') + if 'c_desc' in cmd: + out.append("%s (%s)" % (name, ''.join(cmd['c_desc']).strip())) + else: + out.append("%s" % (name,)) + out.append('='*len(out[-1])) + out.append('') + if 'c_opts' in cmd: + out.append('Usage') + out.append('^'*len(out[-1])) + out.append('``%s %s``' % (name, ''.join(cmd['c_opts']).strip())) + out.append('') + if 'h_pre' in cmd: + pre = cmd['h_pre'] + if pre and pre[-1] == "Options:": + del pre[-1] + if pre and pre[-1] == "": + del pre[-1] + if pre: + out.append('Synopsis') + out.append('^'*len(out[-1])) + out.append('\n'.join(cmd['h_pre']).strip()) + out.append('') + if 'h_opts' in cmd: + out.append('Options') + out.append('^'*len(out[-1])) + for o, d in cmd['h_opts']: + o = o.strip() + d = d.strip() + if o: + out.append('%s\n %s' % (o, d)) + else: + out.append(' %s' % (d,)) + out.append('') + if 'h_post' in cmd: + post = cmd['h_post'] + if post and post[0] == "": + del post[0] + if post: + out.append('Description') + out.append('^'*len(out[-1])) + out.append('\n'.join(cmd['h_post']).strip()) + out.append('') + out.append('.. generated from: %s' % ', '.join(cmd['files'])) + if 'c_func' in cmd: + out.append('.. command function: %s' % ', '.join(cmd['c_func'])) + return '\n'.join(out) + +for root, dirs, files in os.walk(sys.argv[1]): + for name in files: + if name.endswith('.c'): + source = os.path.join(root, name) + parse_c(source) + +for name in CMDS.keys(): + CMDS[name] = dict(CMDS[name]) + +for name, cmd in CMDS.items(): + #pprint({name: cmd}) + rst = gen_rst(name, cmd) + target = os.path.join(sys.argv[2], name+'.rst') + file(target, 'w').write(rst) + diff --git a/Documentation/glossary.rst b/Documentation/glossary.rst new file mode 100644 index 0000000000..a702859620 --- /dev/null +++ b/Documentation/glossary.rst @@ -0,0 +1,18 @@ +.. _glossary: + +Glossary +======== + +.. glossary:: :sorted: + + FTD + Flattened Device Tree + + DTB + Device Tree Blob (or Binary) + + DTS + Device Tree Source + + PBL + Pre BootLoader image diff --git a/Documentation/index.rst b/Documentation/index.rst new file mode 100644 index 0000000000..aff450a3c3 --- /dev/null +++ b/Documentation/index.rst @@ -0,0 +1,26 @@ +.. barebox documentation master file, created by + sphinx-quickstart on Tue Jun 17 11:45:57 2014. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to barebox +================== + +Contents: + +.. toctree:: + :glob: + :numbered: + :maxdepth: 1 + + download + user/user-manual + filesystems + commands + boards + glossary + devicetree/* + +* :ref:`search` +* :ref:`genindex` + diff --git a/Documentation/user/automount.rst b/Documentation/user/automount.rst new file mode 100644 index 0000000000..d13eaf19af --- /dev/null +++ b/Documentation/user/automount.rst @@ -0,0 +1,34 @@ +.. _automount: + +Automount +========= + +barebox supports automatically mounting filesystems when a path is first +accessed. This is handled with the :ref:`command_automount` command. With automounting +it is possible to separate the configuration of a board from actually using +filesystems. The filesystems (and the devices they are on) are only probed +when necessary, so barebox does not lose time probing unused devices. + +Typical usage is for accessing the TFTP server. To set up an automount for a +TFTP server, the following is required:: + + mkdir -p /mnt/tftp + automount /mnt/tftp 'ifup eth0 && mount -t tftp $eth0.serverip /mnt/tftp' + +This creates an automountpoint on /mnt/tftp. Whenever this directory is accessed, +the command ``ifup eth0 && mount -t tftp $eth0.serverip /mnt/tftp`` is executed. +It will bring up the network device using :ref:`command_ifup` and mount a TFTP filesystem +using :ref:`command_mount`. + +Usually the above automount command is executed from an init script in /env/init/automount. +With the above, files on the TFTP server can be accessed without configuration:: + + cp /mnt/tftp/linuximage /image + +This automatically detects a USB mass storage device and mounts the first +partition to /mnt/fat:: + + mkdir -p /mnt/fat + automount -d /mnt/fat 'usb && [ -e /dev/disk0.0 ] && mount /dev/disk0.0 /mnt/fat' + +To see a list of currently registered automountpoints use ``automount -l``. diff --git a/Documentation/user/barebox.rst b/Documentation/user/barebox.rst new file mode 100644 index 0000000000..9eb34af874 --- /dev/null +++ b/Documentation/user/barebox.rst @@ -0,0 +1,178 @@ +barebox +======= + +Getting barebox +--------------- + +barebox is released on a monthly basis. The version numbers use the format +YYYY.MM.N, so 2014.06.0 is the monthly release for June 2014. Stable releases +are done as needed to fix critical problems and are indicated by incrementing +the suffix (for example 2014.06.1). + +All releases can be downloaded from: + +http://www.barebox.org/download/ + +Development versions of barebox are accessible via git. A local repository clone +can be created using git:: + + git clone git://git.pengutronix.de/git/barebox.git + Cloning into 'barebox'... + remote: Counting objects: 113356, done. + remote: Compressing objects: 100% (25177/25177), done. + remote: Total 113356 (delta 87910), reused 111155 (delta 85935) + Receiving objects: 100% (113356/113356), 33.13 MiB | 183.00 KiB/s, done. + Resolving deltas: 100% (87910/87910), done. + Checking connectivity... done. + Checking out files: 100% (5651/5651), done. + +A web interface to the repository is available at +http://git.pengutronix.de/?p=barebox.git. + +.. _configuration: + +Configuration +------------- + +barebox uses Kconfig from the Linux Kernel as a configuration tool. +All configuration is accessible via the 'make' command. Before running +it you have to specify your architecture with the ARCH environment +variable and the cross compiler with the CROSS_COMPILE environment +variable. ARCH has to be one of: + +* arm +* blackfin +* mips +* nios2 +* openrisc +* ppc +* sandbox +* x86 + +CROSS_COMPILE should be the prefix of your cross compiler. This can +either contain the full path or, if the cross compiler binary is +in your $PATH, just the prefix. + +Either export ARCH and CROSS_COMPILE once before working on barebox:: + + export ARCH=arm + export CROSS_COMPILE=/path/to/arm-cortexa8-linux-gnueabihf- + make ... + +or add them before each 'make' command:: + + ARCH=arm CROSS_COMPILE=/path/to/arm-cortexa8-linux-gnueabihf- make ... + +For readability, ARCH/CROSS_COMPILE are skipped from the following examples. + +Configuring for a board +^^^^^^^^^^^^^^^^^^^^^^^ + +All configuration files can be found under arch/$ARCH/configs/. For an +overview type:: + + make help + + ... + Architecture specific targets (mips): + No architecture specific help defined for mips + + loongson-ls1b_defconfig - Build for loongson-ls1b + ritmix-rzx50_defconfig - Build for ritmix-rzx50 + tplink-mr3020_defconfig - Build for tplink-mr3020 + dlink-dir-320_defconfig - Build for dlink-dir-320 + qemu-malta_defconfig - Build for qemu-malta + +barebox supports building for multiple boards with a single config. If you +can't find your board in the list, it may be supported by one of the multi-board +configs. As an example, this is the case for tegra_v7_defconfig and imx_v7_defconfig. +Select your config with ``make <yourboard>_defconfig``:: + + make imx_v7_defconfig + +The configuration can be further customized with one of the configuration frontends +with the most popular being ``menuconfig``:: + + make menuconfig + +Compilation +----------- + +After barebox has been :ref:`configured <configuration>` it can be compiled:: + + make + +The resulting binary varies depending on the board barebox is compiled for. +Without :ref:`multi_image` support the 'barebox-flash-image' link will point +to the binary for flashing/uploading to the board. With :ref:`multi_image` support +the compilation process will finish with a list of images built under images/:: + + images built: + barebox-freescale-imx51-babbage.img + barebox-genesi-efikasb.img + barebox-freescale-imx53-loco.img + barebox-freescale-imx53-loco-r.img + barebox-freescale-imx53-vmx53.img + barebox-tq-mba53-512mib.img + barebox-tq-mba53-1gib.img + barebox-datamodul-edm-qmx6.img + barebox-guf-santaro.img + barebox-gk802.img + +Starting barebox +----------------- + +Bringing barebox to a board for the first time is highly board specific, see your +board documentation for initial bringup. + +barebox binaries are, where possible, designed to be startable second stage from another +bootloader. For example, if you have U-Boot running on your board, you can start barebox +with U-Boot's 'go' command:: + + U-Boot: tftp $load_addr barebox.bin + U-Boot: go $load_addr + +With barebox already running on your board, this can be used to chainload another barebox:: + + bootm /mntf/tftp/barebox.bin + +At least ``barebox.bin`` (with :ref:`pbl` support enabled ``arch/$ARCH/pbl/zbarebox.bin``) +should be startable second stage. The flash binary (``barebox-flash-image``) may or may not +be startable second stage as it may have SoC specific headers which prevent running second +stage. + +First Steps +----------- + +This is a typical barebox startup log:: + + barebox 2014.06.0-00232-g689dc27-dirty #406 Wed Jun 18 00:25:17 CEST 2014 + + + Board: Genesi Efika MX Smartbook + detected i.MX51 revision 3.0 + mc13xxx-spi mc13892@00: Found MC13892 ID: 0x0045d0 [Rev: 2.0a] + m25p80 m25p800: sst25vf032b (4096 Kbytes) + ata0: registered /dev/ata0 + imx-esdhc 70004000.esdhc: registered as 70004000.esdhc + imx-esdhc 70008000.esdhc: registered as 70008000.esdhc + imx-ipuv3 40000000.ipu: IPUv3EX probed + netconsole: registered as cs2 + malloc space: 0xabe00000 -> 0xafdfffff (size 64 MiB) + mmc1: detected SD card version 2.0 + mmc1: registered mmc1 + barebox-environment environment-sd.7: setting default environment path to /dev/mmc1.barebox-environment + running /env/bin/init... + + Hit any key to stop autoboot: 3 + + barebox@Genesi Efika MX Smartbook:/ + +Without intervention, barebox will continue booting after 3 seconds. If interrupted +by pressing a key, you will find yourself on the :ref:`shell <hush>`. + +On the shell type ``help`` for a list of supported commands. ``help <command>`` shows +the usage for a particular command. barebox has tab completion which will complete +your command. Arguments to commands are also completed depending on the command. If +a command expects a file argument only files will be offered as completion. Other +commands will only complete devices or devicetree nodes. diff --git a/Documentation/user/booting-linux.rst b/Documentation/user/booting-linux.rst new file mode 100644 index 0000000000..561a850ce3 --- /dev/null +++ b/Documentation/user/booting-linux.rst @@ -0,0 +1,267 @@ +.. _booting_linux: + +Booting Linux +============= + +Introduction +------------ + +The basic boot command in barebox is :ref:`command_bootm`. This command +can be used directly, but there is also a :ref:`command_boot` command +which offers additional features like a boot sequence which tries to +boot different entries until one succeeds. + +The bootm command +----------------- + +The :ref:`command_bootm` command is the basic boot command. Depending on the +architecture the bootm command handles different image types. On ARM the +following images are supported: + +* ARM Linux zImage +* U-Boot uImage +* barebox images + +The images can either be passed directly to the bootm command as argument or +in the ``global.bootm.image`` variable: + +.. code-block:: sh + + bootm /path/to/zImage + + # same as: + + global.bootm.image=/path/to/zImage + bootm + +When barebox has an internal devicetree it is passed to the kernel. You can +specify an alternative devicetree with the ``-o DTS`` option or the ``global.bootm.oftree`` +variable: + +.. code-block:: sh + + bootm -o /path/to/dtb /path/to/zImage + + # same as: + + global.bootm.oftree=/path/to/dtb + global.bootm.image=/path/to/zImage + bootm + +**NOTE** It may happen that barebox is probed from the devicetree, but you have +want to start a Kernel without passing a devicetree. In this case call ``oftree -f`` +to free the internal devicetree before calling ``bootm`` + +Passing Kernel Arguments +^^^^^^^^^^^^^^^^^^^^^^^^ + +Depending on the barebox configuration (``CONFIG_FLEXIBLE_BOOTARGS``) there +are to ways to pass bootargs to the Kernel. With ``CONFIG_FLEXIBLE_BOOTARGS`` +disabled the bootm command takes the bootargs from the ``bootargs`` environment +variable. With ``CONFIG_FLEXIBLE_BOOTARGS`` enabled the bootargs are composed +from different :ref:`global_device` variables. All variables beginning with +``global.bootargs.`` will be concatenated to the bootargs: + +.. code-block:: sh + + global linux.bootargs.base="console=ttyO0,115200" + global linux.bootargs.debug="earlyprintk ignore_loglevel" + + bootm zImage + + ... + + Kernel command line: console=ttymxc0,115200n8 earlyprintk ignore_loglevel + +Additionally all variables starting with ``global.linux.mtdparts.`` are concatenated +to a ``mtdparts=`` parameter to the kernel. This makes it possible to consistently +partition devices with the :ref:`command_addpart` command and pass the same string as used +with addpart to the Kernel: + +.. code-block:: sh + + norparts="512k(bootloader),512k(env),4M(kernel),-(root)" + nandparts="1M(bootloader),1M(env),4M(kernel),-(root)" + + global linux.mtdparts.nor0="physmap-flash.0:$norparts" + global linux.mtdparts.nand0="mxc_nand:$nandparts" + + addpart /dev/nor0 $norparts + addpart /dev/nand0 $nandparts + + ... + + bootm zImage + + ... + + Kernel command line: mtdparts=physmap-flash.0:512k(bootloader),512k(env),4M(kernel),-(root); + mxc_nand:1M(bootloader),1M(env),4M(kernel),-(root) + + +The boot command +---------------- + +The :ref:`command_boot` command offers additional convenience for the :ref:`command_bootm` +command. It works with :ref:`boot_entries` and :ref:`bootloader_spec` entries. Boot entries +are located under /env/boot/ and are scripts which setup the bootm variables so that the +``boot`` command can run ``bootm`` without further arguments. + +.. _boot_entries: + +Boot entries +^^^^^^^^^^^^ + +A simple boot entry in ``/env/boot/mmc`` could look like this: + +.. code-block:: sh + + #!/bin/sh + + global.bootm.image=/mnt/mmc1/zImage + global.bootm.oftree=/env/oftree + + global linux.bootargs.dyn.root="root=PARTUUID=deadbeef:01" + +This takes the kernel from ``/mnt/mmc1/zImage`` (which could be an +:ref:`automount` path registered earlier). The devicetree will be used from +``/env/oftree``. The Kernel gets the command line +``root=PARTUUID=deadbeef:01``. Note the ``.dyn`` in the bootargs variable name. +boot entries should always add Kernel command line parameters to variables with +``.dyn`` in it. These will be cleared before booting different boot entries. +This is done so that following boot entries do not leak command line +parameters from the previous boot entries. + +This entry can be booted with ``boot mmc``. It can also be made the default by +setting the ``global.boot.default`` variable to ``mmc`` and then calling +``boot`` without arguments. + +.. _bootloader_spec: + +Bootloader Spec +^^^^^^^^^^^^^^^ + +barebox supports booting according to the bootloader spec: + +http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/ + +It follows another philosophy than the :ref:`boot_entries`. With Boot Entries +booting is completely configured in the bootloader. Bootloader Spec Entries +on the other hand the boot entries are on a boot medium. This gives a boot medium +the possibility to describe where a Kernel is and what parameters it needs. + +All Bootloader Spec Entries are in a partition on the boot medium under ``/loader/entries/*.conf``. +In the Bootloader Spec a boot medium has a dedicated partition to use for +boot entries. barebox is less strict, it accepts Bootloader Spec Entries on +every partition barebox can read. + +A Bootloader Spec Entry consists of key value pairs:: + + /loader/entries/6a9857a393724b7a981ebb5b8495b9ea-3.8.0-2.fc19.x86_64.conf: + + title Fedora 19 (Rawhide) + version 3.8.0-2.fc19.x86_64 + machine-id 6a9857a393724b7a981ebb5b8495b9ea + options root=UUID=6d3376e4-fc93-4509-95ec-a21d68011da2 + linux /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/linux + initrd /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/initrd + +All pathes are absolute pathes in the partition. Bootloader Spec Entries can +be created manually, but there also is the ``scripts/kernel-install`` tool to +create/list/modify entries directly on a MMC/SD card or other media. To use +it create a SD card / USB memory stick with a /boot partition with type 0xea. +The partition can be formatted with FAT or EXT4 filesystem. If you wish to write +to it from barebox later you must use FAT. The following creates a Bootloader +Spec Entry on a SD card: + +.. code-block:: sh + + scripts/kernel-install --device=/dev/mmcblk0 -a \ + --machine-id=11ab7c89d02c4f66a4e2474ea25b2b84 --kernel-version="3.15" \ + --kernel=/home/sha/linux/arch/arm/boot/zImage --add-root-option \ + --root=/dev/mmcblk0p1 -o "console=ttymxc0,115200" + +The entry can be listed with the -l option: + +.. code-block:: sh + + scripts/kernel-install --device=/dev/mmcblk0 -l + + Entry 0: + title: Linux-3.15 + version: 3.15 + machine_id: 11ab7c89d02c4f66a4e2474ea25b2b84 + options: console=ttymxc0,115200 root=PARTUUID=0007CB20-01 + linux: 11ab7c89d02c4f66a4e2474ea25b2b84.15/linux + +When on barebox the SD card shows up as ``mmc`` then this entry can be booted with +``boot mmc1`` or with setting ``global.boot.default`` to ``mmc1``. + +network boot +------------ + +With the following steps barebox can start the Kernel and root filesystem +over network, a standard development case. + +Configure network: edit ``/env/network/eth0``. For a standard dhcp setup +the following is enough: + +.. code-block:: sh + + #!/bin/sh + + ip=dhcp + serverip=192.168.23.45 + +serverip is only necessary if it differs from the serverip offered from the dhcp server. +A static ip setup can look like this: + +.. code-block:: sh + + #!/bin/sh + + ip=static + ipaddr=192.168.2.10 + netmask=255.255.0.0 + gateway=192.168.2.1 + serverip=192.168.2.1 + +Note that barebox will pass the same ip settings to the kernel, i.e. it passes +``ip=$ipaddr:$serverip:$gateway:$netmask::eth0:`` for a static ip setup and +``ip=dhcp`` for a dynamic dhcp setup. + +Adjust ``global.user`` and maybe ``global.hostname`` in ``/env/config``:: + + global.user=sha + global.hostname=efikasb + +Copy the kernel (and devicetree if needed) to the base dir of the TFTP server:: + + cp zImage /tftpboot/sha-linux-efikasb + cp myboard.dtb /tftpboot/sha-oftree-efikasb + +barebox will pass ``nfsroot=/home/${global.user}/nfsroot/${global.hostname}`` +This may be a link to another location on the NFS server. Make sure that the +link target is exported from the server. + +``boot net`` will then start the Kernel. + +If the pathes or names are not suitable they can be adjusted in +``/env/boot/net``: + +.. code-block:: sh + + #!/bin/sh + + path="/mnt/tftp" + + global.bootm.image="${path}/${global.user}-linux-${global.hostname}" + + oftree="${path}/${global.user}-oftree-${global.hostname}" + if [ -f "${oftree}" ]; then + global.bootm.oftree="$oftree" + fi + + nfsroot="/home/${global.user}/nfsroot/${global.hostname}" + bootargs-ip + global.linux.bootargs.dyn.root="root=/dev/nfs nfsroot=$nfsroot,v3,tcp" diff --git a/Documentation/user/defaultenv-2.rst b/Documentation/user/defaultenv-2.rst new file mode 100644 index 0000000000..fc3723ec6f --- /dev/null +++ b/Documentation/user/defaultenv-2.rst @@ -0,0 +1,113 @@ +Default environment version 2 +============================= + +barebox has its environment files under /env/. Most of the runtime configuration +takes place under /env/. The environment is comparable to a tar archive which is +unpacked from a storage medium during startup. If for whatever reason the environment +cannot be loaded from a storage medium, a compiled-in default environment is used +instead. + +The environment is not automatically stored on the storage medium when a file +under /env/ is changed, instead this has to be done manually using the +:ref:`command_saveenv` command. + +There are two sets of generic environment files which can be used. The older one +should not be used for new boards and is not described here. New boards should use +defaultenv-2 instead. + +The default environment is composed from different directories during compilation:: + + defaultenv/defaultenv-2-base -> base files + defaultenv/defaultenv-2-dfu -> overlay for DFU + defaultenv/defaultenv-2-menu -> overlay for menus + arch/$ARCH/boards/<board>/env -> board specific overlay + +The content of the above directories is applied one after another. If the +same file exists in a later overlay, it will overwrite the preceding one. + +/env/bin/init +------------- + +This script is executed by the barebox startup code after initialization. +In the defaultenv-2 it will add some global variables and executes the scripts +in /env/init/. It is also responsible for printing the boot timeout prompt. +Be careful with changes to this script: since it is executed before any user +intervention, it might lock the system. + +/env/init/ +---------- + +/env/init/ is the place for startup scripts. The scripts in this directory +will be executed in alphabetical order by the /env/bin/init script. + +/env/boot/ +---------- + +/env/boot/ contains boot entry scripts. the :ref:`command_boot` command treats +the files in this directory as possible boot targets. See :ref:`booting_linux` +for more details. + +/env/config +----------- + +This file contains some basic configuration settings. It can be edited using +the :ref:`command_edit` command. Typical content: + +.. code-block:: sh + + #!/bin/sh + + # change network settings in /env/network/eth0 + # change mtd partition settings and automountpoints in /env/init/* + + #global.hostname= + + # set to false if you do not want to have colors + #global.allow_color=true + + # user (used for network filenames) + #global.user=none + + # timeout in seconds before the default boot entry is started + #global.autoboot_timeout=3 + + # list of boot entries. These are executed in order until one + # succeeds. An entry can be: + # - a filename in /env/boot/ + # - a full path to a directory. All files in this directory are + # treated as boot files and executed in alphabetical order + #global.boot.default=net + + # base bootargs + #global.linux.bootargs.base="console=ttyS0,115200" + +When changing this file remember to do a ``saveenv`` to make the change +persistent. Also it may be necessary to manually ``source /env/config`` before +the changes take effect. + +/env/network/ +------------- + +This contains the configuration files for the network interfaces. Typically +there will be a file ``eth0`` with a content like this: + +.. code-block:: sh + + #!/bin/sh + + # ip setting (static/dhcp) + ip=dhcp + global.dhcp.vendor_id=barebox-${global.hostname} + + # static setup used if ip=static + ipaddr= + netmask= + gateway= + serverip= + + # MAC address if needed + #ethaddr=xx:xx:xx:xx:xx:xx + + # put code to discover eth0 (i.e. 'usb') to /env/network/eth0-discover + + exit 0 diff --git a/Documentation/user/devicetree.rst b/Documentation/user/devicetree.rst new file mode 100644 index 0000000000..856ff6a05b --- /dev/null +++ b/Documentation/user/devicetree.rst @@ -0,0 +1,84 @@ +.. _devicetree: + +Devicetree support +================== + +Flattened Device Tree (FDT) is a data structure for describing the hardware on +a system. On an increasing number of boards both barebox and the Linux Kernel can +probe their devices directly from devicetrees. barebox needs the devicetree compiled +into the binary. The Kernel usually does not have a devicetree compiled in, instead +the Kernel expects to be passed a devicetree from the bootloader. + +From a bootloader's point of view, using devicetrees has the advantage that the +same devicetree is used to probe both the Kernel and the Bootloader; this +drastically reduces porting effort since the devicetree has to be written only +once (and with luck somebody has already written a devicetree for the Kernel). +Probing barebox from devicetree is highly recommended for new projects. + +.. _internal_devicetree: + +The internal devicetree +----------------------- + +The devicetree barebox has been probed from plays a special role. It is referred to +as the :ref:`internal_devicetree`. The barebox devicetree commands work on this +devicetree. The devicetree source (DTS) files are kept in sync with the Kernel DTS +files. As the FDT files are meant to be backward compatible, it should always be possible +to start a Kernel with the barebox internal devicetree. However, since the barebox +devicetree may not be complete or contain bugs it is always possible to start the +Kernel with another devicetree than barebox has been started with. +If a device has been probed from the devicetree then using the :ref:`command_devinfo` +command on it will show the corresponding devicetree node: + +.. code-block:: sh + + barebox@Phytec pcm970:/ devinfo 10002000.wdog + Resources: + num: 0 + name: /soc/aipi@10000000/wdog@10002000 + start: 0x10002000 + size: 0x00001000 + Driver: imx-watchdog + Bus: platform + Device node: /soc/aipi@10000000/wdog@10002000 + wdog@10002000 { + compatible = "fsl,imx27-wdt", "fsl,imx21-wdt"; + reg = <0x10002000 0x1000>; + interrupts = <0x1b>; + clocks = <0x1 0x4a>; + }; + +Devicetree commands +------------------- + +barebox has commands to show and manipulate devicetrees. These commands always +work on the internal devicetree. It is possible to add/remove nodes using the +:ref:`command_of_node` command and to add/change/remove properties using the +:ref:`command_of_property` command. To dump devicetrees on the console use the +:ref:`command_of_dump` command. + +.. code-block:: sh + + # dump the whole devicetree + of_dump + + # dump node of_dump /soc/nand@d8000000/ + of_dump /soc/nand@d8000000/ + + # create a new node + of_node -c /chosen/mynode + + # add a property to it + of_property -s /chosen/mynode/ myproperty myvalue + +It is important to know that these commands always work on the internal +devicetree. If you modify the internal devicetree to influence the behaviour of +a Kernel booted later, make sure that you start the kernel with the internal +devicetree (i.e. don't pass a devicetree to the :ref:`command_bootm` command). If you +wish to use another devicetree than the internal devicetree for starting the Kernel, +you can exchange the internal devicetree during runtime: + +.. code-block:: sh + + oftree -f + oftree -l /new/dtb diff --git a/Documentation/user/driver-model.rst b/Documentation/user/driver-model.rst new file mode 100644 index 0000000000..2ec55f1385 --- /dev/null +++ b/Documentation/user/driver-model.rst @@ -0,0 +1,91 @@ +Driver model +============ + +barebox has a driver model. This matches the devices on a board with their +corresponding drivers. From a users point of view this is mostly visible in the +:ref:`command_devinfo` and :ref:`command_drvinfo` command. Without arguments +the :ref:`command_devinfo` command will show a hierarchical list of devices +found on the board. As this may be instantiated from the :ref:`devicetree` +there may be devices listed for which no driver is available. The +:ref:`command_drvinfo` command shows a list of drivers together with the +devices they handle. + +:ref:`command_devinfo` also shows a list of device files a device has registered:: + + `-- 70008000.esdhc + `-- mmc1 + `-- 0x00000000-0x1d9bfffff ( 7.4 GiB): /dev/mmc1 + `-- 0x00100000-0x040fffff ( 64 MiB): /dev/mmc1.0 + `-- 0x04100000-0x240fffff ( 512 MiB): /dev/mmc1.1 + `-- 0x24100000-0xe40fffff ( 3 GiB): /dev/mmc1.2 + `-- 0xe4100000-0x1640fffff ( 2 GiB): /dev/mmc1.3 + `-- 0x00080000-0x000fffff ( 512 KiB): /dev/mmc1.barebox-environment + +In this case the /dev/mmc1\* are handled by the mmc1 device. It must be noted +that it's desirable that devices (mmc1) have the same name as the device files (/dev/mmc1\*), +but this doesn't always have to be the case. + +Device detection +---------------- + +Some devices like USB or MMC may take a longer time to probe. Probing USB +devices should not delay booting when USB may not even be used. This case is +handled with device detection. The user visible interface to device detection +is the :ref:`command_detect` command. ``detect -l`` shows a list of detectable +devices:: + + barebox@Genesi Efika MX Smartbook:/ detect -l + 70004000.esdhc + 70008000.esdhc + 73f80000.usb + 73f80200.usb + 73f80400.usb + 83fe0000.pata + ata0 + mmc0 + mmc1 + miibus0 + +A particular device can be detected with ``detect <devname>``:: + + barebox@Genesi Efika MX Smartbook:/ detect 73f80200.usb + Found SMSC USB331x ULPI transceiver (0x0424:0x0006). + Bus 002 Device 004: ID 13d3:3273 802.11 n WLAN + mdio_bus: miibus0: probed + eth0: got preset MAC address: 00:1c:49:01:03:4b + Bus 002 Device 005: ID 0b95:7720 ZoWii + Bus 002 Device 002: ID 0424:2514 + Bus 002 Device 001: ID 0000:0000 EHCI Host Controller + +For detecting all devices ``detect -a`` can be used. + +Device parameters +----------------- + +Devices can have parameters which can be used to configure devices or to provide +additional information for a device. The parameters can be listed with the +:ref:`command_devinfo` command. A ``devinfo <devicename>`` will print the parameters +of a device:: + + barebox@Genesi Efika MX Smartbook:/ devinfo eth0 + Parameters: + ipaddr: 192.168.23.197 + serverip: 192.168.23.1 + gateway: 192.168.23.1 + netmask: 255.255.0.0 + ethaddr: 00:1c:49:01:03:4b + +The parameters can be used as shell variables:: + + eth0.ipaddr=192.168.23.15 + echo "my current ip is: $eth0.ipaddr" + +device variables may have a type, so assigning wrong values may fail:: + + barebox@Genesi Efika MX Smartbook:/ eth0.ipaddr="This is not an IP" + set parameter: Invalid argument + barebox@Genesi Efika MX Smartbook:/ echo $? + 1 + +**HINT** barebox has tab completion for variables. Typing ``eth0.<TAB><TAB>`` +will show the parameters for eth0. diff --git a/Documentation/user/framebuffer.rst b/Documentation/user/framebuffer.rst new file mode 100644 index 0000000000..0065e7b42f --- /dev/null +++ b/Documentation/user/framebuffer.rst @@ -0,0 +1,43 @@ +Framebuffer support +=================== + +barebox has support for framebuffer devices. Currently there is no console support +for framebuffers, so framebuffer usage is limited to splash screens only. barebox +supports BMP and PNG graphics using the :ref:`command_splash` command. barebox +currently has no support for backlights, so unless there is a board specific enable +hook for enabling a display it must be done manually with a script. Since barebox +has nothing useful to show on the framebuffer it doesn't enable it during startup. +A framebuffer can be enabled with the ``enable`` parameter of the framebuffer device: + +.. code-block:: sh + + fb0.enable=1 + +Some framebuffer devices support different resolutions. These can be configured +with the ``mode_name`` parameter. See a list of supported modes using ``devinfo fb0``. +A mode can only be changed when the framebuffer is disabled. + +A typical script to enable the framebuffer could look like this: + +.. code-block:: sh + + #!/bin/sh + + SPLASH=/path/to/mysplash.png + + if [ ! -f $SPLASH ]; then + exit 0 + fi + + # first show splash + splash /path/to/mysplash.png + + # enable framebuffer + fb0.enable=1 + + # wait for signals to become stable + msleep 100 + + # finally enable backlight + gpio_direction_output 42 1 + diff --git a/Documentation/user/hush.rst b/Documentation/user/hush.rst new file mode 100644 index 0000000000..4a1b84bad1 --- /dev/null +++ b/Documentation/user/hush.rst @@ -0,0 +1,52 @@ +.. index:: hush shell + +.. _hush: + +hush shell +========== + +barebox has an integrated shell: hush. This is a simple shell which +is enough for writing simple shell scripts. Usage of the shell for +scripts should not be overstrained. Often a command written in C is +more flexible and also more robust than a complicated shell script. + +hush features +------------- + +variables:: + + a="Hello user" + echo $a + Hello user + +conditional execution ``if`` / ``elif`` / ``else`` / ``fi``:: + + if [ ${foo} = ${bar} ]; then + echo "foo equals bar" + else + echo "foo and bar differ" + fi + +``for`` loops:: + + for i in a b c; do + echo $i + done + +``while`` loops:: + + while true; do + echo "endless loop" + done + +wildcard globbing:: + + ls d* + echo ??? + +There is no support in hush for input/output redirection or pipes. +Some commands work around this limitation with additional arguments. for +example the :ref:`command_echo` command has the ``-a FILE`` option for appending +a file and the ``-o FILE`` option for overwriting a file. The readline +command requires a variable name as argument in which the line will be +stored. diff --git a/Documentation/user/introduction.rst b/Documentation/user/introduction.rst new file mode 100644 index 0000000000..8eb586044a --- /dev/null +++ b/Documentation/user/introduction.rst @@ -0,0 +1,27 @@ +Introduction +============ + +This is the barebox user manual. It describes how to configure, compile +and run barebox on Embedded Systems. + +barebox (just barebox, not *the* barebox) is a bootloader designed for +Embedded Systems. It runs on a variety of ARM, MIPS, PowerPC based SoCs. +barebox aims to be a versatile and flexible bootloader, not only for +booting Embedded Linux Systems but also for initial hardware bringup and +development. barebox is highly configurable to be suitable as a full featured +development binary to a lean production system. Just like busybox is the swiss +army knife for Embedded Linux, barebox is the swiss army knife for bare metal, +hence the name. + +Feedback +-------- + +For sending patches, asking for help and giving general feedback you are +always welcome to write a mail to the barebox mailing list. Most of the +discussion of barebox takes place here: + +http://lists.infradead.org/mailman/listinfo/barebox/ + +There's also an IRC channel: + +IRC: #barebox (Freenode) diff --git a/Documentation/user/memory-areas.rst b/Documentation/user/memory-areas.rst new file mode 100644 index 0000000000..dd1db9e8cd --- /dev/null +++ b/Documentation/user/memory-areas.rst @@ -0,0 +1,27 @@ +memory areas +============ + +Several barebox commands like :ref:`command_md`, erase or crc work on an area +of memory. Areas have the following form:: + + <start>-<end> + +or:: + + <start>+<count> + +start, end and count are interpreted as decimal values if not prefixed with 0x. +Additionally these can be postfixed with K, M or G for kilobyte, megabyte or +gigabyte. + +Examples +-------- + +Display a hexdump from 0x80000000 to 0x80001000 (inclusive):: + + md 0x80000000-0x80001000 + +Display 1 kilobyte of memory starting at 0x80000000:: + + md 0x80000000+1k + diff --git a/Documentation/user/multi-image.rst b/Documentation/user/multi-image.rst new file mode 100644 index 0000000000..727b98fe5a --- /dev/null +++ b/Documentation/user/multi-image.rst @@ -0,0 +1,54 @@ +.. _multi_image: + +Multi Image Support +=================== + +Traditionally a single configuration only works for a single board. Sometimes +even variants of a single board like different amount of memory require a new +config. This has the effect that the number of defconfig files increases dramatically. +All the configs have to be kept in sync manually. Multi Image Support solves this +problem. + +With Multi Image Support binaries for multiple boards can be generated from a single +config. A single board can only support compilation with or without Multi Image Support. +Multi Image Support exposes several user visible changes: + +* In ``make menuconfig`` it becomes possible to select multiple boards instead of + only one. +* The ``barebox-flash-image`` link is no longer generated since there is no single + binary to use anymore. +* images are generated under images/. The build process shows all images generated + at the end of the build. + +Technical background +-------------------- + +With Multi Image Support enabled, the main barebox binary (barebox.bin) will be +shared across different boards. For board specific code this means that it has +to test whether it actually runs on the board it is designed for. Typically board +specific code has this: + +.. code-block:: c + + static int efikamx_init(void) + { + if (!of_machine_is_compatible("genesi,imx51-sb")) + return 0; + + ... board specific code ... + } + device_initcall(efikamx_init); + +Multi Image Support always uses :ref:`PBL <pbl>` to generate compressed images. +A board specific PBL image is prepended to the common barebox binary. The PBL +image contains the devicetree which is passed to the common barebox binary to +let the common binary determine the board type. + +The board specific PBL images are generated from a single set of object files +using the linker. The basic trick here is that the PBL objects have multiple +entry points, specified with the ENTRY_POINT macro. For each PBL binary +generated a different entry point is selected using the ``-e`` option to ld. +The linker will throw away all unused entry points and only keep the functions +used by a particular entry point. + +The Multi Image PBL files can be disassembled with ``make <entry-function-name.pbl.S`` diff --git a/Documentation/user/networking.rst b/Documentation/user/networking.rst new file mode 100644 index 0000000000..23b0e4640b --- /dev/null +++ b/Documentation/user/networking.rst @@ -0,0 +1,81 @@ +networking +========== + +barebox has IPv4 networking support. Several protocols such as +:ref:`command_dhcp`, :ref:`filesystems_nfs`, :ref:`command_tftp` are +supported. + +Network configuration +--------------------- + +The first step for networking is configuring the network device. The network +device is usually ``eth0``. The current configuration can be viewed with the +:ref:`command_devinfo` command: + +.. code-block:: sh + + barebox@Genesi Efika MX Smartbook:/ devinfo eth0 + Parameters: + ipaddr: 192.168.23.197 + serverip: 192.168.23.1 + gateway: 192.168.23.1 + netmask: 255.255.0.0 + ethaddr: 00:1c:49:01:03:4b + +The configuration can be changed on the command line with: + +.. code-block:: sh + + eth0.ipaddr=172.0.0.10 + +The :ref:`command_dhcp` command will change the settings based on the answer +from the DHCP server. + +This low level configuration of the network interface is often not necessary. Normally +the network settings should be edited in ``/env/network/eth0``, then the network interface +can be brought up using the :ref:`command_ifup` command. + +Network filesystems +------------------- + +barebox supports NFS and TFTP as filesystem implementations. See :ref:`filesystems_nfs` +and :ref:`filesystems_tftp` for more information. After the network device has been +brought up a network filesystem can be mounted with: + +.. code-block:: sh + + mount -t tftp 192.168.2.1 /mnt + +or + +.. code-block:: sh + + mount -t nfs 192.168.2.1:/export none /mnt + +**NOTE** This can often be hidden behind the :ref:`command_automount` command to make +mounting transparent to the user. + +Network console +--------------- + +barebox has a udp based network console. If enabled in the config, you will see +something like this during startup: + + registered netconsole as cs1 + +By default the network console is disabled during runtime to prevent security +risks. It can be enabled using: + +.. code-block:: sh + + cs1.ip=192.168.23.2 + cs1.active=ioe + +This will send udp packets to 192.168.23.2 on port 6666. On 192.168.23.2 the +scripts/netconsole script can be used to control barebox: + +.. code-block:: sh + + scripts/netconsole <board IP> 6666 + +The netconsole can be used just like any other console. diff --git a/Documentation/user/pbl.rst b/Documentation/user/pbl.rst new file mode 100644 index 0000000000..a08d6c9d77 --- /dev/null +++ b/Documentation/user/pbl.rst @@ -0,0 +1,31 @@ +.. _pbl: + +PreBootLoader images (PBL) +========================== + +Traditionally barebox generates a raw uncompressed binary. PBL is an effort to +create self extracting compressed images instead. This helps on some boards +where storage space is sparse. Another usecase of PBL is on SoCs on which the +ROM code loads the initial bootloader to (limited) SRAM. With self extracting +binaries, more binary space becomes available. + +PBL is available for ARM and MIPS. It can be enabled in ``make menuconfig`` with +the ``[*] Pre-Bootloader image`` option. + +The user visible difference is that with PBL support ``barebox.bin`` is no longer +the final binary image, but instead ``arch/$ARCH/pbl/zbarebox.bin``. Use the +``barebox-flash-image`` link which always points to the correct image. + +Technical background +-------------------- + +Normal object files are added to the make system using ``obj-y += file.o``. +With PBL the build system recurses into the source directories a second +time, this time all files specified with ``pbl-y += file.o`` are compiled. +This way source code can be shared between regular barebox and PBL. A special +case is ``lwl-y += file.o`` which expands to ``obj-y`` when PBL is disabled +and to ``pbl-y`` when PBL is enabled. + +**HINT** For getting an overview over the binaries, disassemble barebox.bin +(``make barebox.S``) with or without PBL support and also disassemble the +PBL (``make arch/$ARCH/pbl/zbarebox.S``) diff --git a/Documentation/user/system-setup.rst b/Documentation/user/system-setup.rst new file mode 100644 index 0000000000..35d61475f3 --- /dev/null +++ b/Documentation/user/system-setup.rst @@ -0,0 +1,64 @@ +System Setup +============ + +Serial Console Access +--------------------- + +As most current development machines don't have serial ports, the usual setup +is to use a USB-Serial-Converter. Some evaluation boards have such a converter +on board. After connecting, these usually show up on your host as +``/dev/ttyUSB#`` or ``/dev/ttyACM#`` (check ``dmesg`` to find out). + +On Debian systems, the device node will be accessible to the ``dialout`` group, +so adding your user to that group (``adduser <user> dialout``) removes the need +for root privileges. + +Using the "screen" program +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The terminal manager ``screen`` can also be used as a simple terminal emulator:: + + screen /dev/ttyUSB0 115200 + +To exit from ``screen``, press ``<CTRL-A> <K> <y>``. + +Using the "microcom" program +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A good alternative terminal program is microcom. On Debian it can be installed +with ``apt-get install microcom``, on other distributions it can be installed +from source: + +http://git.pengutronix.de/?p=tools/microcom;a=summary + +Usage is simple:: + + microcom -p /dev/ttyUSB0 + +Network Access +-------------- + +Having network connectivity between your host and your target will save you a +lot of time otherwise spent on writing SD cards or using JTAG. The main +protocols used with barebox are DHCP, TFTP and NFS. + +Configuration of dnsmasq for DHCP and TFTP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``dnsmasq`` program can be configured as a DHCP and TFTP server in addition +to its original DNS functionality:: + + sudo ip addr add 192.168.23.1/24 dev <interface> + sudo ip link set <interface> up + sudo /usr/sbin/dnsmasq --interface=<interface> --no-daemon --log-queries \ + --enable-tftp --tftp-root=<absolute-path-to-your-images>/ \ + --dhcp-range=192.168.23.240,192.168.23.250 + +Configuration of a TFTP Server +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Configuration of a BOOTP / DHCP Server +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Configuring a NFS Server +^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/user/ubi.rst b/Documentation/user/ubi.rst new file mode 100644 index 0000000000..a2e386fdc9 --- /dev/null +++ b/Documentation/user/ubi.rst @@ -0,0 +1,138 @@ +UBI/UBIFS support +================= + +barebox has both UBI and UBIFS support. For handling UBI barebox has commands similar to +the Linux commands :ref:`command_ubiformat`, :ref:`command_ubiattach`, :ref:`command_ubidetach`, +:ref:`command_ubimkvol` and :ref:`command_ubirmvol`. + +The following examples assume we work on the first UBI device. Replace ``ubi0`` with +the appropriate number when you have multiple UBI devices. + +The first step for preparing a pristine Flash for UBI is to :ref:`command_ubiformat` the +device: + +.. code-block:: sh + + ubiformat /dev/nand0.root + +If you intend to use a device with UBI you should always use ``ubiformat`` instead of plain +:ref:`command_erase`. ``ubiformat`` will make sure the erasecounters are preserved and also +:ref:`ubi_fastmap` won't work when a flash is erased with ``erase`` + +NOTE: When using the :ref:`ubi_fastmap` feature make sure that the UBI is attached and detached +once after using ``ubiformat``. This makes sure the Fastmap is written. + +After a device has been formatted it can be attached with :ref:`command_ubiattach`. + +.. code-block:: sh + + ubiattach /dev/nand0.root + +This will create the controlling node ``/dev/ubi0`` and also register all volumes present +on the device as ``/dev/ubi0.<volname>``. When freshly formatted there won't be any volumes +present. A volume can be created with: + +.. code-block:: sh + + ubimkvol /dev/ubi0 root 0 + +The first parameter is the controlling node. The second parameter is the name of the volume. +In this case the volume can be found under ``/dev/ubi.root``. The third parameter contains +the size. A size of zero means that all available space shall be used. + +The next step is to write a UBIFS image to the volume. The image must be created on a host using +the ``mkfs.ubifs`` command. ``mkfs.ubifs`` requires several arguments for describing the +flash layout. Values for these arguments can be retrieved from a ``devinfo ubi`` under barebox: + +.. code-block:: sh + + barebox@Phytec pcm970:/ devinfo ubi0 + Parameters: + peb_size: 16384 + leb_size: 15360 + vid_header_offset: 512 + min_io_size: 512 + sub_page_size: 512 + good_peb_count: 3796 + bad_peb_count: 4 + max_erase_counter: 0 + mean_erase_counter: 0 + available_pebs: 3713 + reserved_pebs: 83 + +To build a UBIFS image for this device the following command is suitable: + +.. code-block:: sh + + mkfs.ubifs --min-io-size=512 --leb-size=15360 --max-leb-cnt=4096 -r rootdir \ + /tftpboot/root.ubifs + +The ``--max-leb-cnt`` parameter specifies the maximum number of logical erase blocks +the UBIFS image can ever have. For this particular device a number of 3713 would be +enough. If the image shall be used for multiple boards the maximim peb count of all +boards must be used. + +The UBIFS image can be transferred to the board for example with TFTP: + +.. code-block:: sh + + cp /mnt/tftp/root.ubifs /dev/ubi0.root + +Finally it can be mounted using the :ref:`command_mount` command: + +.. code-block:: sh + + mkdir -p /mnt/ubi + mount -t ubifs /dev/ubi0.root /mnt/ubi + +The second time the UBIFS is mounted the above can be simplified to: + +.. code-block:: sh + + ubiattach /dev/nand0.root + mount -t ubifs /dev/ubi0.root /mnt/ubi + +Mounting the UBIFS can also be made transparent with the automount command. +With this helper script in ``/env/bin/automount-ubi:``: + +.. code-block:: sh + + #!/bin/sh + + if [ ! -e /dev/ubi0 ]; then + ubiattach /dev/nand0 || exit 1 + fi + + mount -t ubifs /dev/ubi0.root $automount_path + + +The command ``automount -d /mnt/ubi/ '/env/bin/automount-ubi'`` will automatically +attach the UBI device and mount the UBIFS image to ``/mnt/ubi`` whenever ``/mnt/ubi`` +is first accessed. The automount command can be added to ``/env/init/automount`` to +execute it during startup. + +.. _ubi_fastmap: + +UBI Fastmap +----------- + +When attaching UBI to a flash device the UBI code has to scan all eraseblocks on the +flash. Since this can take some time the Fastmap feature has been introduced. It has +been merged in Linux 3.7. barebox has support for the Fastmap feature, but to use +it some care must be taken. The Fastmap feature reduces scanning time by adding +informations to one of the first blocks of a flash. For technical details see +http://www.linux-mtd.infradead.org/doc/ubi.html#L_fastmap. Since the Fastmap can +only live near the beginning of a flash the Fastmap code relies on finding a free +eraseblock there. The above example command make that sure, but Fastmap is incompatible +with creating a UBI image on a host and directly flashing the UBI image to the +raw NAND/NOR device. In this case the Fastmap code will not find a free eraseblock +and the following message will occur during ``ubidetach``: + +.. code-block:: sh + + UBI error: ubi_update_fastmap: could not find any anchor PEB + UBI warning: ubi_update_fastmap: Unable to write new fastmap, err=-28 + +The Fastmap is first written after a ``ubidetach``, so it's important to attach/detach +a UBI volume after using ``ubiformat``. + diff --git a/Documentation/user/updating.rst b/Documentation/user/updating.rst new file mode 100644 index 0000000000..0503e7dc72 --- /dev/null +++ b/Documentation/user/updating.rst @@ -0,0 +1,29 @@ + +.. _update: + +Updating barebox +================ + +Updating barebox is potentially a dangerous task. When the update fails, +the board may not start anymore and must be recovered. barebox has a special +command to make updating barebox easier and safer: :ref:`command_barebox_update`. +A board can register an update handler to the update command. The handler can +do additional checks before trying an update, e.g. it's possible +to check whether the new image actually is a barebox image. + +Updating barebox can be as easy as:: + + barebox_update /path/to/new/barebox.img + +Multiple handlers can be registered to the update mechanism. Usually the device +barebox has been started from is registered as default (marked with a ``*``):: + + barebox@Genesi Efika MX Smartbook:/ barebox_update -l + registered update handlers: + * mmc -> /dev/mmc1 + spinor -> /dev/m25p0 + +:ref:`command_barebox_update` requires board support, so it may not be +available for your board. It is recommended to implement it, but you can also +update barebox manually using :ref:`command_erase` and :ref:`command_cp` +commands. The exact commands are board specific. diff --git a/Documentation/user/usb.rst b/Documentation/user/usb.rst new file mode 100644 index 0000000000..9bbfccac5f --- /dev/null +++ b/Documentation/user/usb.rst @@ -0,0 +1,65 @@ +USB support +=========== + +USB host support +---------------- + +barebox has support for USB host and USB device mode. USB devices +take a long time to probe, so they are not probed automatically. Probing +has to be triggered using the :ref:`command_usb` or :ref:`command_detect` command. +USB devices in barebox are not hotpluggable. It is expected that USB +devices are not disconnected while barebox is running. + +USB Networking +^^^^^^^^^^^^^^ + +barebox supports ASIX compatible devices and the SMSC95xx. After +detection the device shows up as eth0 and can be used like a regular network +device. + +To use a USB network device together with the :ref:`command_ifup` command, add the +following to /env/network/eth0-discover: + +.. code-block:: sh + + #!/bin/sh + + usb + +USB mass storage +^^^^^^^^^^^^^^^^ + +barebox supports USB mass storage devices. After probing them with the :ref:`command_usb` +they show up as ``/dev/diskx`` and can be used like any other device. + +USB device support +------------------ + +DFU +^^^ + +USB Device Firmware Upgrade (DFU) is an official USB device class specification of the USB +Implementers Forum. It provides a vendor independent way to update the firmware of embedded +devices. The current specification is version 1.1 and can be downloaded here: +http://www.usb.org/developers/devclass_docs/DFU_1.1.pdf + +On barebox side the update is handled with the :ref:`command_dfu` command. It is passes a list +of partitions to provide to the host. The partition list has the form ``<file>(<name>)<flags>``. +``file`` is the path to the device or regular file which shall be updated. ``name`` is the +name under which the partition shall be provided to the host. For the possible ``flags`` see +:ref:`command_dfu`. A typical ``dfu`` command could look like this: + +.. code-block:: sh + + dfu "/dev/nand0.barebox.bb(barebox)sr,/dev/nand0.kernel.bb(kernel)r,/dev/nand0.root.bb(root)r" + +On the host the tool `dfu-util <http://dfu-util.gnumonks.org/>`_ can be used to update the +partitions. It is available for the most distributions. To update the Kernel for the above +example the following can be used: + +.. code-block:: sh + + dfu-util -D arch/arm/boot/zImage -a kernel + +The dfu-util command automatically finds dfu capable devices. If there are multiple devices +found it has to be specified with the ``-d``/``-p`` options. diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst new file mode 100644 index 0000000000..4e2a2509f2 --- /dev/null +++ b/Documentation/user/user-manual.rst @@ -0,0 +1,33 @@ +.. highlight:: console + +barebox user manual +=================== + +Contents: + +.. toctree:: + :numbered: + :maxdepth: 2 + + introduction + system-setup + barebox + networking + automount + memory-areas + driver-model + hush + defaultenv-2 + variables + updating + devicetree + pbl + multi-image + framebuffer + usb + ubi + booting-linux + +* :ref:`search` +* :ref:`genindex` + diff --git a/Documentation/user/variables.rst b/Documentation/user/variables.rst new file mode 100644 index 0000000000..04e179114e --- /dev/null +++ b/Documentation/user/variables.rst @@ -0,0 +1,49 @@ +Configuration variables +======================= + +.. _global_device: + +The ``global`` device +--------------------- + +The ``global`` device is a special purpose device. It only exists as a +storage for global variables. Some global variables are created internally +in barebox (see :ref:`magicvars`). Additional variables can be created with +the :ref:`command_global` command:: + + global myvar + +This creates the ``global.myvar`` variable which now can be used like any +other variable. You can also directly assign a value during creation:: + + global myvar1=foobar + +**NOTE** creating a variable with ``global myvar1=foobar`` looks very similar +to assigning a value with ``global.myvar1=foobar``, but the latter fails when +a variable has not been created before. + +.. _magicvars: + +Magic variables +--------------- + +Some variables have special meanings and influence the behaviour +of barebox. Most but not all of them are consolidated in the :ref:`global_device` +Since it's hard to remember which variables these are and if the current +barebox has support for them the :ref:`command_magicvar` command can print a list +of all variables with special meaning along with a short description:: + + barebox@Genesi Efika MX Smartbook:/ magicvar + OPTARG optarg for hush builtin getopt + PATH colon separated list of pathes to search for executables + PS1 hush prompt + armlinux_architecture ARM machine ID + armlinux_system_rev ARM system revision + armlinux_system_serial ARM system serial + automount_path mountpath passed to automount scripts + bootargs Linux Kernel parameters + bootsource The source barebox has been booted from + bootsource_instance The instance of the source barebox has been booted from + global.boot.default default boot order + ... + |