diff --git a/.gitignore b/.gitignore index 28f319acb..135fdeb63 100644 --- a/.gitignore +++ b/.gitignore @@ -67,6 +67,8 @@ include/generated # Generated files Doxyfile.version +Documentation/commands/*.rst +doctrees/ # stgit generated dirs patches-* diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 1936cc1d4..145456600 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -1 +1,2 @@ +build html diff --git a/Documentation/barebox-main.dox b/Documentation/barebox-main.dox deleted file mode 100644 index c98c75fe6..000000000 --- a/Documentation/barebox-main.dox +++ /dev/null @@ -1,126 +0,0 @@ -/** @mainpage Barebox - -Barebox is a bootloader that initializes hardware and boots Linux and -maybe other operating systems or bare metal code on a variety of -processors. It was initially derived from U-Boot and retains several of -U-Boot's ideas, so users familiar with U-Boot should come into -production quickly with Barebox. - -However, as the Barebox developers are highly addicted to the Linux -kernel, its coding style and code quality, we try to stick as closely -as possible to the methodologies and techniques developed in Linux. In -addition we have a strong background in POSIX, so you'll find several -good old Unix traditions realized in Barebox as well. - -@par Highlights: - -- POSIX File API:
- @a Barebox uses the the well known open/close/read/write/lseek access - functions, together with a model of representing devices by files. This - makes the APIs familiar to everyone who has experience with Unix - systems. - -- Shell:
- We have the standard shell commands like ls/cd/mkdir/echo/cat,... - -- Environment Filesystem:
- In contrast to U-Boot, Barebox doesn't misuse the environment for - scripting. If you start the bootloader, it gives you a shell and - something that looks like a filesystem. In fact it isn't; it is a very - simple ar archive being extracted from flash into a ramdisk with 'loadenv' - and stored back with 'saveenv'. - -- Filesystem Support:
- When starting up, the environment is mounted to /, followed by a - device filesytem being mounted to /dev in order to make it possible to - access devices. Other filesystems can be mounted on demand. - -- Driver Model (borrowed from Linux):
- Barebox follows the Linux driver model: devices can be specified in a - hardware specific file, and drivers feel responsible for these devices - if they have the same name. - -- Clocksource:
- We use the standard clocksource API from Linux. - -- Kconfig/Kbuild:
- This gives us parallel builds and removes the need for lots of ifdefs. - -- Sandbox:
- If you develop features for @a Barebox, you can use the 'sandbox' - target which compiles @a Barebox as a POSIX application in the Linux - userspace: it can be started like a normal command and even has - network access (tun/tap). Files from the local filesytem can be used - to simulate devices. - -- Device Parameters:
- There is a parameter model in @a Barebox: each device can specify its - own parameters, which do exist for every instance. Parameters can be - changed on the command line with \.\="...". For - example, if you want to access the IPv4 address for eth0, this is done - with 'eth0.ip=192.168.0.7' and 'echo $eth0.ip'. - -- Getopt:
- @a Barebox has a lightweight getopt() implementation. This makes it - unnecessary to use positional parameters, which can be hard to read. - -- Integrated Editor:
- Scripts can be edited with a small integrated fullscreen editor. - This editor has no features except the ones really needed: moving - the cursor around, typing characters, exiting and saving. - - -@par Directory layout - -Most of the directory layout is based upon the Linux Kernel: - -@verbatim -arch / * / -> contains architecture specific parts -arch / * / mach-* / -> SoC specific code - -drivers / serial -> drivers -drivers / net -drivers / ... - -include / asm-* -> architecture specific includes -include / asm-* / arch-* -> SoC specific includes - -fs / -> filesystem support and filesystem drivers - -lib / -> generic library functions (getopt, readline and the - like) - -common / -> common stuff - -commands / -> many things previously in common/cmd_*, one command - per file - -net / -> Networking stuff - -scripts / -> Kconfig system - -Documentation / -> Parts of the documentation, also doxygen -@endverbatim - -@section license barebox's License - -@verbatim -This program is free software; you can redistribute it and/or -modify it under the terms of the GNU General Public License as -published by the Free Software Foundation; either version 2 of -the License, or (at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -@endverbatim - -@subpage users_manual - -@subpage developers_manual - -@subpage supported_boards - -*/ diff --git a/Documentation/board.dox b/Documentation/board.dox deleted file mode 100644 index e54570935..000000000 --- a/Documentation/board.dox +++ /dev/null @@ -1,94 +0,0 @@ -/** @page dev_board Adapting a new Board - -To add a new board to @a barebox a few steps must be done, to extend and modify -the @a barebox source tree. - -@section board_add_files Files/Directories to be added - - - arch/\/boards/\ - - arch/\/boards/\/Makefile - - arch/\/boards/\/\.c - - arch/\/boards/\/\.dox - - include/configs/\.h - - arch/\/configs/\_defconfig - -@subsection board_makefile arch/\/boards/\Makefile - -@verbatim - obj-y += all files that builds the BSP (Assembler and/or C files) -@endverbatim - -@subsection board_basefile arch/\/boards/\\.c - -TBD - -@subsection board_doxygen arch/\/boards/\/\.dox - -This file should describe in short words your new board, what CPU -it uses, what resources are provided and features it supports. - -Use the doxygen style for this kind of documentation. Below you find a -template for this kind of file: - -@verbatim -/** @page - -This board uses an based CPU. The board is shipped with: - -- many MiB NOR type Flash Memory -- many MiB SDRAM -- a very special network controller - -and so on. - -*/ -@endverbatim - -To make your new shiny file visible in the automatically generated -documentation you must sort in the used page lable ("" in the -template above) into Documentation/boards.dox as: - -@verbatim - ... - @subpage - ... -@endverbatim - -at the right architecture. - -@note Consider to use an unique page lable. - -@subsection board_lscript arch/\/boards/\/barebox.lds.S - -If your board needs a special binary @a barebox layout, you can provide a local -board linker script file. This will replace the generic one provided by your -architecture or CPU support. - -Add this file with - -@verbatim - extra-y += -@endverbatim - -in your local \b Makefile to the list of files, forwarded to the last linking step. - -@section board_defconfig arch/\/configs/\_defconfig - -TBD - -@section board_mod_files These files needs to be modified: - - - modify Documentation/board.dox - - modify arch/\/Kconfig - - add your board (MACH_*) to the list - - add your default text base address for this architecture (ARCH_TEXT_BASE) - - modify arch/\/Makefile: - - add board-$(MACH_*) = \ - -First, the new board should be visible in the menu. - -@section board_specific_cpu Porting hints for specific CPUs - -@li @subpage dev_s3c24xx_mach - -*/ diff --git a/Documentation/boards.dox b/Documentation/boards.dox deleted file mode 100644 index 8d4fabbdd..000000000 --- a/Documentation/boards.dox +++ /dev/null @@ -1,74 +0,0 @@ -/** @page supported_boards Supported Boards - -This is a list of boards that are currently supported by @a barebox. - -PowerPC type: - -@li @subpage pcm030 - -ARM type: - - -@li @subpage pcm037 -@li @subpage pcm038 -@li @subpage pcm043 -@li @subpage imx21ads -@li @subpage imx27ads -@li @subpage tx28 -@li @subpage the3stack -@li @subpage mx23_evk -@li @subpage board_babage -@li @subpage board_loco -@li @subpage chumbyone -@li @subpage scb9328 -@li @subpage netx -@li @subpage dev_omap_arch -@li @subpage a9m2440 -@li @subpage a9m2410 -@li @subpage eukrea_cpuimx27 -@li @subpage eukrea_cpuimx35 -@li @subpage edb9301 -@li @subpage edb9302 -@li @subpage edb9302a -@li @subpage edb9307 -@li @subpage edb9307a -@li @subpage edb9312 -@li @subpage edb9315 -@li @subpage edb9315a -@li @subpage board_cupid -@li @subpage phycard-a-l1 -@li @subpage toshiba-ac100 -@li @subpage qil-a9260 -@li @subpage tny-a9g20-lpw -@li @subpage tny-a9263 -@li @subpage usb-a9g20-lpw -@li @subpage usb-a9263 -@li @subpage virt2real - -Blackfin type: - -@li @subpage ipe337 - -x86 type: - -@li @subpage generic_pc - - -MIPS type: - -@li @subpage dlink_dir_320 -@li @subpage loongson_ls1b -@li @subpage qemu_malta -@li @subpage ritmix-rzx50 -@li @subpage tplink-mr3020 - -*/ - -/* TODO - * - * Add documentation to your boardfile, forward it with doxygen's page - * feature (@page ) and include it here with: - * - * @subpage - * - */ diff --git a/Documentation/boards.rst b/Documentation/boards.rst new file mode 100644 index 000000000..78e4951ab --- /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 000000000..95a961e24 --- /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 000000000..692fb5eee --- /dev/null +++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9301.rst @@ -0,0 +1,10 @@ +Cirrus Logic EP9301 +=================== + +This board 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 000000000..43dfb83da --- /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 000000000..7283536ea --- /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 000000000..9006f2c9c --- /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 000000000..ba3763c38 --- /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 000000000..16ad7fbbf --- /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 000000000..5adb96696 --- /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 000000000..c44f87385 --- /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 000000000..0fde3e747 --- /dev/null +++ b/Documentation/boards/imx.rst @@ -0,0 +1,104 @@ +Freescale i.MX +============== + +Freescale i.MX is traditionally very well supported under barebox. +Depending on the SoC, there are different Boot Modes supported. Older +SoCs up to i.MX31 support only 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. These headers also 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 + +The above will overwrite the MBR (and consequently the partition table) +on the destination SD card. To preserve the MBR while writing the rest +of the image to the card, use:: + + 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 as well, but it is not widely used there.) + +The External Boot Mode supports booting only 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 Controller's internal SRAM. This initial binary +portion 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 000000000..452004859 --- /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 000000000..6c05bcdfd --- /dev/null +++ b/Documentation/boards/imx/Phytec-phyCORE-i.MX31.rst @@ -0,0 +1,41 @@ +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 000000000..c5ab4b94b --- /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 000000000..0e59046a2 --- /dev/null +++ b/Documentation/boards/imx/synertronixx_scb9328.rst @@ -0,0 +1,10 @@ +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 diff --git a/Documentation/boards/mips.rst b/Documentation/boards/mips.rst new file mode 100644 index 000000000..4bac35ffd --- /dev/null +++ b/Documentation/boards/mips.rst @@ -0,0 +1,9 @@ +MIPS +==== + +.. toctree:: + :glob: + :numbered: + :maxdepth: 1 + + mips/* diff --git a/Documentation/boards/mips/dlink-dir-320.rst b/Documentation/boards/mips/dlink-dir-320.rst new file mode 100644 index 000000000..74d11ffe5 --- /dev/null +++ b/Documentation/boards/mips/dlink-dir-320.rst @@ -0,0 +1,44 @@ +D-Link DIR-320 +============== + +The D-Link DIR-320 wireless router has + + * BCM5354 SoC; + * 32 MiB SDRAM; + * 4 MiB NOR type Flash Memory; + * RS232 serial interface (LV-TTL levels on board!); + * 1xUSB interface; + * 4 + 1 ethernet interfaces; + * 802.11b/g (WiFi) interface; + * JTAG interface; + * 5 LEDs; + * 2 buttons. + +The router uses CFE as firmware. + +Running barebox +--------------- + +Barebox can be started from CFE using tftp. +You must setup tftp-server on host 192.168.0.1. +Put your barebox.bin to tftp-server directory +(usual /tftpboot or /srv/tftp). +Connect your DIR-320 to your tftp-server network via +one of four sockets. + +Next, setup network on DIR-320 and run barebox.bin, e.g.:: + + CFE> ifconfig eth0 -addr=192.168.0.99 + CFE> boot -tftp -addr=a0800000 -raw 192.168.0.1:barebox.bin + + +Links +----- + + * http://www.dlink.com.au/products/?pid=768 + * http://wiki.openwrt.org/toh/d-link/dir-320 + +CFE links: + + * http://www.broadcom.com/support/communications_processors/downloads.php#cfe + * http://www.linux-mips.org/wiki/CFE diff --git a/Documentation/boards/mips/loongson_ls1b.rst b/Documentation/boards/mips/loongson_ls1b.rst new file mode 100644 index 000000000..8f475e6e2 --- /dev/null +++ b/Documentation/boards/mips/loongson_ls1b.rst @@ -0,0 +1,56 @@ +Loongson LS1B +============= + +The LS1B is a development board made by Loongson Technology Corp. Ltd. + +The board has + + * Loongson LS1B SoC 250 MHz; + * 64 MiB SDRAM; + * 512 KiB SPI boot ROM; + * 128M x 8 Bit NAND Flash Memory; + * 2 x RS232 serial interfaces (DB9 connectors); + * 2 x Ethernet interfaces; + * 4 x USB interfaces; + * microSD card slot; + * LCD display (480x272); + * audio controller; + * beeper; + * buttons; + * EJTAG 10-pin connector. + +The board uses PMON2000 as bootloader. + +Running barebox +--------------- + + 1. Connect to the boards's UART2 (115200 8N1); + + 2. Turn board's power on; + + 3. Wait ``Press to execute loading image`` prompt and press the space key. + + 4. Build barebox and upload ``zbarebox.bin`` via Ymodem to the board: + +.. code-block:: none + + PMON> ymodem base=0xa0200000 + +.. + + 5. Run barebox + +.. code-block:: none + + PMON> g -e 0xa0200000 + +.. + +Links +----- + + * http://en.wikipedia.org/wiki/Loongson + * http://www.linux-mips.org/wiki/Loongson + * https://github.com/loongson-gz + * http://www.linux-mips.org/wiki/PMON_2000 + * http://www.opsycon.se/PMON2000/Main diff --git a/Documentation/boards/mips/qemu-malta.rst b/Documentation/boards/mips/qemu-malta.rst new file mode 100644 index 000000000..be89ae3d5 --- /dev/null +++ b/Documentation/boards/mips/qemu-malta.rst @@ -0,0 +1,19 @@ +QEMU Malta +========== + +QEMU run string:: + + qemu-system-mips -nodefaults -M malta -m 256 \ + -nographic -serial stdio -monitor null \ + -bios barebox-flash-image + +Also you can use GXemul:: + + gxemul -Q -x -e maltabe -M 256 0xbfc00000:barebox-flash-image + +Links +----- + + * http://www.linux-mips.org/wiki/Mips_Malta + * http://www.qemu.org/ + * http://gxemul.sourceforge.net/ diff --git a/Documentation/boards/mips/ritmix-rzx50.rst b/Documentation/boards/mips/ritmix-rzx50.rst new file mode 100644 index 000000000..a51fe3f71 --- /dev/null +++ b/Documentation/boards/mips/ritmix-rzx50.rst @@ -0,0 +1,62 @@ +Ritmix RZX-50 +============= + +Ritmix RZX-50 is a portable game console for the Russian market. + +The portable game console has + + * Ingenic JZ4755 SoC; + * 64 MiB SDRAM; + * 4 GiB microSDHC card / 4 GiB NAND type Flash Memory (internal boot device); + * RS232 serial interface (LV-TTL levels on the board!); + * LCD display (480x272); + * Video out interface; + * 1xUSB interface; + * buttons. + +The game console uses U-Boot 1.1.6 as bootloader. + +Running barebox +--------------- + + 1. Connect to the game console's UART + (see. http://a320.emulate.su/2012/01/19/uart-na-ritmix-rzx-50/); + + 2. Unblock U-Boot console + (see. http://a320.emulate.su/2012/01/25/rzx-50-dostup-k-konsoli-u-boot/); + Please note that U-Boot's Zmodem support does not work; + + 3. Boot Ritmix linux and login; + + 4. Build barebox and upload ``barebox.bin`` via Zmodem to the board: + +.. code-block:: none + + # cd /tmp + # rz + +.. + + 5. Write barebox to onboard flash: + +.. code-block:: none + + # dd if=barebox.bin of=/dev/mmcblk0 seek=1048576 bs=1 count=262144 + +.. + + 6. Reboot RZX-50, next in U-Boot console start barebox: + +.. code-block:: none + + CETUS # msc read 0xa0800000 0x100000 0x40000; g a0800000 + +.. + + +Links +----- + + * http://www.ritmixrussia.ru/products/252/entertainment/game/rzx-50 + * ftp://ftp.ingenic.cn/2soc/4755/JZ4755_ds.pdf + * ftp://ftp.ingenic.cn/3sw/01linux/01loader/u-boot/u-boot-1.1.6-jz-20110719-r1728-add-jz4770.patch.bz2 diff --git a/Documentation/boards/mips/tplink-mr3020.rst b/Documentation/boards/mips/tplink-mr3020.rst new file mode 100644 index 000000000..c9e092c90 --- /dev/null +++ b/Documentation/boards/mips/tplink-mr3020.rst @@ -0,0 +1,67 @@ +TP-LINK MR3020 +============== + +The TP-LINK MR3020 wireless router has + + * Atheros ar9331 SoC; + * 32 MiB SDRAM; + * 4 MiB NOR type SPI Flash Memory; + * RS232 serial interface (LV-TTL levels on board!); + * 1 USB interface; + * 1 Ethernet interfaces; + * 802.11b/g/n (WiFi) interface; + * LEDs & buttons. + +The router uses U-Boot 1.1.4 as firmware. + +Running barebox +--------------- + +Barebox can be started from U-Boot using tftp. +But you have to encode barebox image in a very special way. + +First obtain ``lzma`` and ``mktplinkfw`` utilities. + +The ``lzma`` utility can be obtained in Debian/Ubuntu +distro by installing lzma package. + +The ``mktplinkfw`` utility can be obtained from openwrt, e.g.:: + + $ OWRTPREF=https://raw.githubusercontent.com/mirrors/openwrt/master + $ curl -OL $OWRTPREF/tools/firmware-utils/src/mktplinkfw.c \ + -OL $OWRTPREF/tools/firmware-utils/src/md5.c \ + -OL $OWRTPREF/tools/firmware-utils/src/md5.h + $ cc -o mktplinkfw mktplinkfw.c md5.c + +To convert your barebox.bin to U-Boot-loadable image (``6F01A8C0.img``) +use this command sequence:: + + $ lzma -c -k barebox.bin > barebox.lzma + $ ./FW/mktplinkfw -c -H 0x07200103 -W 1 -N TL-WR720N-v3 \ + -s -F 4Mlzma -k barebox.lzma -o 6F01A8C0.img + +You must setup tftp-server on host 192.168.0.1. +Put your ``6F01A8C0.img`` to tftp-server directory +(usual ``/tftpboot`` or ``/srv/tftp``). + +Connect your board to your tftp-server network via Ethernet. + +Next, setup network on MR3020 and run ``6F01A8C0.img``, e.g.:: + + hornet> set ipaddr 192.168.0.2 + hornet> set serverip 192.168.0.1 + hornet> tftpboot 0x81000000 6F01A8C0.img + hornet> bootm 0x81000000 + + +Links +----- + + * http://www.tp-link.com/en/products/details/?model=TL-MR3020 + * http://wiki.openwrt.org/toh/tp-link/tl-mr3020 + * https://wikidevi.com/wiki/TP-LINK_TL-MR3020 + +See also + + * http://www.eeboard.com/wp-content/uploads/downloads/2013/08/AR9331.pdf + * http://squonk42.github.io/TL-WR703N/ diff --git a/Documentation/boards/mxs/Chumby-Falconwing.rst b/Documentation/boards/mxs/Chumby-Falconwing.rst new file mode 100644 index 000000000..172d6840c --- /dev/null +++ b/Documentation/boards/mxs/Chumby-Falconwing.rst @@ -0,0 +1,54 @@ +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 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 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 fourth 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 barebox!). + + * Copy the default 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 fourth 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 000000000..85dde46e4 --- /dev/null +++ b/Documentation/boards/mxs/Freescale-i.MX23-evk.rst @@ -0,0 +1,30 @@ +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 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 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 000000000..0fbd4dfd7 --- /dev/null +++ b/Documentation/boards/mxs/KaRo-TX28.rst @@ -0,0 +1,53 @@ +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 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 barebox diff --git a/Documentation/boards/omap.rst b/Documentation/boards/omap.rst new file mode 100644 index 000000000..503861333 --- /dev/null +++ b/Documentation/boards/omap.rst @@ -0,0 +1,41 @@ +Texas Instruments OMAP/AM335x +============================= + +Texas Instruments OMAP SoCs have a two-stage 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 PandaBoard +-------------------------- + +The PandaBoard 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 +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 BeagleBoard is the same with the corresponding BeagleBoard defconfigs. + +Networking +---------- + +The original BeagleBoard does not have Ethernet (the newer BeagleBoard-xM does), +but a USB Ethernet dongle can be used for networking. The PandaBoard has an +integrated USB Ethernet converter which behaves exactly 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 000000000..d01a00117 --- /dev/null +++ b/Documentation/boards/s3c/Digi-a9m2440.rst @@ -0,0 +1,89 @@ +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 +--------------------------- + +Configure with 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 000000000..d75224f78 --- /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 000000000..558f11169 --- /dev/null +++ b/Documentation/boards/sandbox.rst @@ -0,0 +1,55 @@ +Sandbox +======= + +barebox can be run as a simulator on your host to check and debug new non +hardware related features. + +Building barebox for simulation +------------------------------- + +The barebox sandbox can be built with the host compiler:: + + ARCH=sandbox make sandbox_defconfig + ARCH=sandbox make + +Running the sandbox +------------------- + +Once you compile barebox for the sandbox, you can run it with:: + + $ barebox [] + +Available sandbox invocation options include: + + ``-m``, ``--malloc=`` + + Start sandbox with a specified malloc-space in bytes. + + ``-i `` + + Map a to barebox. This option can be given multiple times. The s + will show up as ``/dev/fd0`` ... ``/dev/fdX`` in the barebox simulator. + + ``-e `` + + Map to barebox. With this option 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 `` + + Register as a console capable of doing stdout. can be a + regular file or a FIFO. + + ``-I `` + + Register as a console capable of doing stdin. can be a regular + file or a FIFO. + + ``-x``, ``--xres `` + + Specify SDL width. + + ``-y``, ``--yres `` + + Specify SDL height. diff --git a/Documentation/boards/tegra.rst b/Documentation/boards/tegra.rst new file mode 100644 index 000000000..d2d1a2539 --- /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 000000000..ee5e86980 --- /dev/null +++ b/Documentation/boards/x86.rst @@ -0,0 +1,141 @@ +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 = (\ + 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/building.dox b/Documentation/building.dox deleted file mode 100644 index 527ca45d0..000000000 --- a/Documentation/building.dox +++ /dev/null @@ -1,60 +0,0 @@ -/** @page building Building - -This section describes how to build the Barebox bootloader. - -@a Barebox uses Kconfig/Kbuild from the Linux kernel to build it's -sources. It consists of two parts: the makefile infrastructure (kbuild) -and a configuration system (kconfig). So building @a barebox is very -similar to building the Linux kernel. - -In the examples below we use the "sandbox" configuration, which is a -port of @a Barebox to the Linux userspace. This makes it possible to -test the code without having real hardware or even qemu. Note that the -sandbox architecture does only work well on x86 and has some issues on -x86_64. - -\todo Find out about issues on x86_64. - -Selecting the architecture and the corresponding cross compiler is done -by setting the following environment variables: - -- ARCH=\ -- CROSS_COMPILE=\ - -For @p ARCH=sandbox we do not need a cross compiler, so it is sufficient -to specify the architecture: - -@code -# export ARCH=sandbox -@endcode - -In order to configure the various aspects of @a barebox, start the -@a barebox configuration system: - -@code -# make menuconfig -@endcode - -This command starts a menu box and lets you select all the different -options available for the selected architecture. Once the configuration -is finished (you can simulate this by using the default config file with -'make sandbox_defconfig'), there is a .config file in the toplevel -directory of the sourcecode. - -After @a barebox is configured, we can start the compilation: - -@code -# make -@endcode - -You can use '-j \' in order to do a parallel build if you have more -than one cpus. - -If everything goes well, the result is a file called @p barebox: - -@code -# ls -l barebox --rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 barebox -@endcode - -*/ diff --git a/Documentation/commands.dox b/Documentation/commands.dox deleted file mode 100644 index d8cfa6b8f..000000000 --- a/Documentation/commands.dox +++ /dev/null @@ -1,111 +0,0 @@ -/** - * @page command_reference Shell Commands - -This section describes the commands which are available on the @a -Barebox shell. - -@a Barebox, as a bootloader, usually shall start the Linux kernel right -away. However, there are several use cases around which make it -necessary to have some (customizable) logic and interactive scripting -possibilities. In order to achieve this, @a Barebox offers several -commands on it's integrated commandline shell. - -The following alphabetically sorted list documents all commands -available in @a Barebox: - -\todo Sort this by functionality? - -@li @subpage _name -@li @subpage addpart_command -@li @subpage alternate -@li @subpage bootm_command -@li @subpage bootu -@li @subpage bootz -@li @subpage cat_command -@li @subpage cd_command -@li @subpage clear_command -@li @subpage clko -@li @subpage cp_command -@li @subpage cpufreq -@li @subpage cpuinfo -@li @subpage crc_command -@li @subpage crc32 -@li @subpage delpart_command -@li @subpage devinfo_command -@li @subpage dfu_command -@li @subpage dhcp -@li @subpage dump_clocks -@li @subpage echo_command -@li @subpage edit_command -@li @subpage erase_command -@li @subpage ethact -@li @subpage exec -@li @subpage exit -@li @subpage export_command -@li @subpage false -@li @subpage getopt -@li @subpage gpio_get_value_command -@li @subpage gpio_set_value_command -@li @subpage gpio_direction_input_command -@li @subpage gpio_direction_output_command -@li @subpage go -@li @subpage help -@li @subpage host -@li @subpage i2c_probe -@li @subpage i2c_read -@li @subpage i2c_write -@li @subpage icache -@li @subpage iminfo -@li @subpage insmod -@li @subpage linux16_command -@li @subpage loadenv_command -@li @subpage loadb -@li @subpage loady -@li @subpage loadxc -@li @subpage login -@li @subpage ls_command -@li @subpage lsmod -@li @subpage md -@li @subpage memcmp -@li @subpage meminfo -@li @subpage memset -@li @subpage menu -@li @subpage mkdir -@li @subpage mount_command -@li @subpage mtest -@li @subpage mw -@li @subpage mycdev -@li @subpage nand -@li @subpage nand_boot_test -@li @subpage nfs -@li @subpage passwd -@li @subpage ping -@li @subpage printenv_command -@li @subpage protect_command -@li @subpage pwd -@li @subpage readline -@li @subpage reset -@li @subpage rarpboot -@li @subpage reginfo -@li @subpage rm -@li @subpage rmdir -@li @subpage saveenv_command -@li @subpage setenv_command -@li @subpage sh -@li @subpage sleep -@li @subpage source -@li @subpage splash_command -@li @subpage test -@li @subpage timeout -@li @subpage true -@li @subpage tftp_command -@li @subpage ubiattach -@li @subpage ubimkvol -@li @subpage ubirmvol -@li @subpage umount -@li @subpage unlzo -@li @subpage unprotect_command -@li @subpage usb -@li @subpage version - -*/ diff --git a/Documentation/commands.rst b/Documentation/commands.rst new file mode 100644 index 000000000..55b04f6e5 --- /dev/null +++ b/Documentation/commands.rst @@ -0,0 +1,9 @@ +Command reference +================= + +.. toctree:: + :glob: + :maxdepth: 1 + + commands/* + diff --git a/Documentation/conf.py b/Documentation/conf.py new file mode 100644 index 000000000..0292c720a --- /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 +# " v 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 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/console.txt b/Documentation/console.txt deleted file mode 100644 index 76b6107ac..000000000 --- a/Documentation/console.txt +++ /dev/null @@ -1,13 +0,0 @@ --------------- barebox consoles ------------------ - -barebox supports multiple consoles which may be simultaneously active. -Depending on the configuration none, the first or all consoles are -activated on startup, see CONSOLE_ACTIVATE_FIRST and CONSOLE_ACTIVATE_ALL -options. - -During runtime the behaviour of the consoles can be controlled with the -'active' parameter each console has. The console system recognizes three -characters: 'i' for stdin, 'o' for stdout and 'e' for stderr. These options -may be concatenated together as needed, so setting an 'active' parameter -of a console to 'io' would enable it for stdout and stdin while leaving -stderr disabled. diff --git a/Documentation/developers_manual.dox b/Documentation/developers_manual.dox deleted file mode 100644 index 2f7d3605e..000000000 --- a/Documentation/developers_manual.dox +++ /dev/null @@ -1,24 +0,0 @@ -/** @page developers_manual Developer's Manual - -This part of the documentation is intended for developers of @a barebox. - -@section devel_backgrounds Some background knowledge for some frameworks barebox - -@li @subpage driver_model -@li @subpage dev_params - -@section devel_hints Hints and tips for simply adapting barebox - -@li @subpage dev_architecture -@li @subpage dev_cpu -@li @subpage dev_board - -@section devel_themes Various themes about barebox - -@li @subpage how_mount_works -@li @subpage boot_preparation -@li @subpage barebox_simul -@li @subpage io_access_functions -@li @subpage mcfv4e_MCDlib - -*/ diff --git a/Documentation/devices_drivers.txt b/Documentation/devices_drivers.txt deleted file mode 100644 index e13b13a52..000000000 --- a/Documentation/devices_drivers.txt +++ /dev/null @@ -1,72 +0,0 @@ - ----------- Devices and drivers in barebox -------------- - -We follow a rather simplistic driver model here. There is a struct device which -describes a particular device present in the system. A struct driver represents -a driver present in the system. Both structs find together via the members -'type' (int) and 'name' (char *). If both members match, the driver's probe -function is called with the struct device as argument. People familiar with -the Linux platform bus will recognize this behaviour and in fact many things were -stolen from there. Some selected members of the structs will be described in this -document. -Currently all devices and drivers are handled in simple linked lists. When it comes -to USB or PCI it may be desirable to have a tree structure, but this may also be -unnecessary overhead. - -struct device -------------- - -char name[MAX_DRIVER_NAME]; - -This member (and 'type' described below) is used to match with a driver. This is -a descriptive name and could be MPC5XXX_ether or imx_serial. - -char id[MAX_DRIVER_NAME]; - -The id is used to uniquely identify a device in the system. The id will show up -under /dev/ as the device's name. Usually this is something like eth0 or nor0. - -void *type_data; - -Devices of a particular class normaly need to store more information than struct -device holds. This entry holds a pointer to the type specific struct. - -void *priv; - -Used by the device driver to store private information. - -void *platform_data; - -This is used to carry information of board specific data from the board code to the -device driver. - -struct param_d *param; - -The parameters for this device. See Documentation/parameters.txt for more info. - -struct driver_d ---------------- - -char name[MAX_DRIVER_NAME]; -unsigned long type; - -See above. - -int (*probe) (struct device_d *); -int (*remove)(struct device_d *); - -These are called if an instance of a device is found or gone. - -ssize_t (*read) (struct device_d*, void* buf, size_t count, ulong offset, ulong flags); -ssize_t (*write) (struct device_d*, const void* buf, size_t count, ulong offset, ulong flags); - -The standard read/write functions. These are called as a response to the read/write -system calls. No driver needs to implement these. - -void *type_data; - -This is somewhat redundant with the type data in struct device. Currently the -filesystem implementation uses this field while ethernet drivers use the same -field in struct device. Probably one of them should be removed. - - diff --git a/Documentation/devicetree/bindings/barebox.txt b/Documentation/devicetree/bindings/barebox.txt deleted file mode 100644 index 5e8d46173..000000000 --- a/Documentation/devicetree/bindings/barebox.txt +++ /dev/null @@ -1,10 +0,0 @@ -barebox specific devicetree bindings -==================================== - -barebox uses some barebox specific devicetree bindings. All of these -are under the /chosen/ hierarchy in the devicetree. - -The bindings have the form of a device with regular 'compatible' properties. -drivers matching these devices do not handle physical devices but instead -influence / configure certain behaviours of barebox like the place where to -find the persistent environment. diff --git a/Documentation/devicetree/bindings/barebox/barebox,environment.rst b/Documentation/devicetree/bindings/barebox/barebox,environment.rst new file mode 100644 index 000000000..d472f6639 --- /dev/null +++ b/Documentation/devicetree/bindings/barebox/barebox,environment.rst @@ -0,0 +1,26 @@ +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 : to further describe +the path to the environment. Supported values for : + +``partname``: + This describes a partition on a device. 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/barebox/barebox,environment.txt b/Documentation/devicetree/bindings/barebox/barebox,environment.txt deleted file mode 100644 index 5a8bf9c13..000000000 --- a/Documentation/devicetree/bindings/barebox/barebox,environment.txt +++ /dev/null @@ -1,25 +0,0 @@ -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 : to further describe -the path to the environment. Supported values for : - -partname: This describes a partition on a device. 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 000000000..c1fd1ab89 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/common.rst @@ -0,0 +1,10 @@ +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/leds/common.txt b/Documentation/devicetree/bindings/leds/common.txt deleted file mode 100644 index db264b332..000000000 --- a/Documentation/devicetree/bindings/leds/common.txt +++ /dev/null @@ -1,8 +0,0 @@ -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 000000000..b9d5bcba9 --- /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``, ``fsl,imx51-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 assign a MAC + address to an 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-iim.txt b/Documentation/devicetree/bindings/misc/fsl,imx-iim.txt deleted file mode 100644 index 9759210ba..000000000 --- a/Documentation/devicetree/bindings/misc/fsl,imx-iim.txt +++ /dev/null @@ -1,20 +0,0 @@ -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 000000000..403863e92 --- /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 assign a MAC + address to an Ethernet device. + +Example:: + + ocotp1: ocotp@021bc000 { + compatible = "fsl,imx6q-ocotp"; + reg = <0x021bc000 0x4000>; + barebox,provide-mac-address = <&fec 0x620>; + }; diff --git a/Documentation/devicetree/bindings/misc/fsl,imx-ocotp.txt b/Documentation/devicetree/bindings/misc/fsl,imx-ocotp.txt deleted file mode 100644 index b7a3ee5b1..000000000 --- a/Documentation/devicetree/bindings/misc/fsl,imx-ocotp.txt +++ /dev/null @@ -1,20 +0,0 @@ -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 000000000..abb9088e9 --- /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/filesystems.rst b/Documentation/filesystems.rst new file mode 100644 index 000000000..4f7b39879 --- /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 000000000..2138328d1 --- /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 000000000..f4eda5d13 --- /dev/null +++ b/Documentation/filesystems/nfs.rst @@ -0,0 +1,12 @@ +.. index:: nfs (filesystem) + +.. _filesystems_nfs: + +NFS Support +=========== + +barebox has readonly support for NFSv3 in 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 000000000..b7ece1a9d --- /dev/null +++ b/Documentation/filesystems/ramfs.rst @@ -0,0 +1,12 @@ +.. index:: ramfs (filesystem) + +RAM filesystem +============== + +ramfs is a simple malloc-based filesystem. An instance of ramfs is +mounted during startup on /. The filesystem type 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 000000000..e0a115926 --- /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/first_steps.dox b/Documentation/first_steps.dox deleted file mode 100644 index 17fdf3748..000000000 --- a/Documentation/first_steps.dox +++ /dev/null @@ -1,61 +0,0 @@ -/** @page first_steps First Steps - -This section demonstrates the first steps with the 'sandbox' -platform. - -@a barebox usually needs an environment for storing its configuration. -You can generate an environment using the example environment contained -in arch/sandbox/board/env: - -@code -# ./scripts/bareboxenv -s -p 0x10000 arch/sandbox/board/env/ env.bin -@endcode - -To get some files to play with you can generate a cramfs image: - -@code -# mkcramfs somedir/ cramfs.bin -@endcode - -The @a barebox image is a normal Linux executable, so it can be started -just like every other program: - -@code -# ./barebox -e env.bin -i cramfs.bin - -barebox 2010.10.0 (Oct 29 2010 - 13:47:17) - -loading environment from /dev/env0 -barebox\> / -@endcode - -Specifying -[ie] \ tells @a barebox to map the file as a device -under @p /dev. Files given with '-e' will appear as @p /dev/env[n]. Files -given with '-i' will appear as @p /dev/fd[n]. - -If @a barebox finds a valid configuration sector on @p /dev/env0, it -will be loaded into @p /env and executes @p /env/init if existing. -The default environment from the example above will show up a menu -asking for the relevant settings. - -If you have started @a barebox as root you will find a new tap device on -your host which you can configure using ifconfig. Once configured with -valid network addresses, barebox can be used to ping the host machine or -to fetch files with tftp. - -\todo Add more about tun/tap configuration - -If you have mapped a cramfs image, try mounting it with - -@code -# mkdir /cram -# mount /dev/fd0 cramfs /cram -@endcode - -Memory can be examined using @p md/mw commands. They both understand the --f \ option to tell the commands that they should work on the -specified files instead of @p /dev/mem (which holds the complete address -space). Note that if you call 'md /dev/fd0' (without -f), @a barebox will -segfault on the host, because it will interpret @p /dev/fd0 as a number. - -*/ diff --git a/Documentation/gen_commands.py b/Documentation/gen_commands.py new file mode 100755 index 000000000..4e33ccaea --- /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 000000000..8bad7dc6e --- /dev/null +++ b/Documentation/glossary.rst @@ -0,0 +1,18 @@ +.. _glossary: + +Glossary +======== + +.. glossary:: :sorted: + + FDT + 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 000000000..b7dae2396 --- /dev/null +++ b/Documentation/index.rst @@ -0,0 +1,25 @@ +.. 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 + + user/user-manual + filesystems + commands + boards + glossary + devicetree/* + +* :ref:`search` +* :ref:`genindex` + diff --git a/Documentation/manual_org.dox b/Documentation/manual_org.dox deleted file mode 100644 index 17238f084..000000000 --- a/Documentation/manual_org.dox +++ /dev/null @@ -1,27 +0,0 @@ -/** @page manual_org Organisation of this Manual - -There is no fixed organisation in this manual, as various source files forwards -their content into different parts. So there are more visible menu entries, -than listed here. But these files are the main control files: - - - Documentation - - Documentation/Doxyfile - - Documentation/barebox-main.dox - - Documentation/users_manual.dox - - Documentation/commands.dox - - Documentation/developers_manual.dox - - Documentation/board.dox - - arch/architecture.dox - - arch/arm/mach-arm.dox - - arch/blackfin/mach-bf.dox - - arch/ppc/mach-ppc.dox - - Documentation/parameters.dox - - Documentation/boards.dox - - various documentation files from the board directory - -New commands should forward their content to Documentation/commands.dox, so -their pages should be listed in this file. - -New boards should forward their content to Documentation/boards.dox, so -their pages should be listed in this file. -*/ diff --git a/Documentation/omap4_usb_booting.txt b/Documentation/omap4_usb_booting.txt deleted file mode 100644 index f0d45a2aa..000000000 --- a/Documentation/omap4_usb_booting.txt +++ /dev/null @@ -1,27 +0,0 @@ --------------- omap4_usb_booting -------------- - -omap4 processors have support for booting from the usb port. To be able to fully -use this feature you will need to enable the following: - OMAP4_USBBOOT - This CONFIG_ option adds the required infrastructure. - DRIVER_SERIAL_OMAP4_USBBOOT - This adds console support over the same usb port used for booting. - FS_OMAP4_USBBOOT - This adds filesystem support over the same usb port used for booting. - -To send the bootloader to the processor, execute the utility omap4_usbboot which -can be found in the scripts subdirectory. -omap4_usbboot takes two parameters: - the bootloader image - a directory name which will be the root for the guest system -Once omap4_usbboot is running it will wait for enumeration of the omap4 cpu on -the host usb subsystem. Then power on or reset the cpu with the correct sys_boot -or SAR memory configuration. - -If everything works, barebox's first stage will boot and afterwards it will load -the second stage found at "/barebox.bin". -Barebox's second stage will still have access to the usb filesystem, so an -initrd and a zImage can be loaded. - -Overall this procedure frees the developer of continously be changing the SD -card or other boot media from host to target. diff --git a/Documentation/porting.txt b/Documentation/porting.txt deleted file mode 100644 index bd807a318..000000000 --- a/Documentation/porting.txt +++ /dev/null @@ -1,115 +0,0 @@ - -When porting from old barebox the follwing steps must be taken (please complain -if there's something missing here ;) - - -- Most of the macros in include/configs/yourboard.h can be removed, especially - the CONFIG_COMMANDS section. The goal is to remove this file entirely, but - for now some values are still needed here. If you think some things are better - configured with the Kconfig system feel free to add them there. - -- The linker script needs a new section for the initcalls. The handling of the - barebox command table has changed, too. (The commands are now sorted by the - linker instead at runtime.) To change it you need an entry like the following - in your linker script: - -#include - - __barebox_cmd_start = .; - .barebox_cmd : { BAREBOX_CMDS } - __barebox_cmd_end = .; - - __barebox_initcalls_start = .; - .barebox_initcalls : { INITCALLS } - __barebox_initcalls_end = .; - -- Rename your linker script to barebox.lds.S and add the following entry to the - Makefile to make sure the linker script is generated: - -extra-y += barebox.lds - -- Register the devices present in your system in the board specific .c file. - To see anything you have to at least register a console. In scb9328.c this - looks like this: - - static struct device_d scb9328_serial_device = { - .name = "imx_serial", - .map_base = IMX_UART1_BASE, - .size = 4096, - }; - - static int scb9328_console_init(void) - { - platform_device_register(&scb9328_serial_device); - return 0; - } - - console_initcall(scb9328_console_init); - -- For most boards you will have to register a cfi_flash device. NAND flash - is not ported yet. - -- Call devfs_add_partition() to add an environment partition for your device: - devfs_add_partition("nor0", 0x40000, 0x20000, DEVFS_PARTITION_FIXED, "env0"); - This will add an area starting at 0x40000 of size 0x20000 of the device - nor0 as env0. - -- Port missing drivers. Depending on the driver this can a be rather simple - process: - - Serial drivers - - Declare all functions static. - - in your probe function fill in a struct console_device and register it - with console_register() - - Ethernet drivers - - Basically do the same as with serial drivers. - - Identify the parts of the driver which handle the MAC address. There are - now two functions handling them in struct eth_device. - - get_mac_address() retrieve the MAC address from the EEPROM if one is - connected. If you don't have an EEPROM just return -1. - set_mac_address() set the MAC address in the device. All magic previously - done with getenv/setenv(ethaddr) must be removed. - - During startup barebox calls get_mac_address() to see if an EEPROM is - connected. If so, it calls set_mac_address() with this address. This - is done even if networking is not used during startup. This makes sure - that the MAC address is set in the device and Linux can pick it up later. - - There is now (the beginning of) generic phy support. When porting drivers - it is recommended to use it. The phy support currently only starts generic - autonegotiation, so if you have some fancy things to do (or have gigabit - ethernet) you'll have to extend the phy layer first. Although this is - extra work, it will pay off some day, as phy support is a great source - of duplicated code. see drivers/net/dm9000.c or drivers/net/fec_mpc5200.c - for examples. - -- Add a clocksource for your system. PowerPCs have a generic decrementer - counter, so if you have a PowerPC you have nothing to do here. On ARM - this is SoC dependent. See Documentation/timekeeping.txt for further - information. - -- Adjust start.S. On PowerPC there is at least the Problem that the relocation - offset is defined at compile time. It is easily possible to determine the - address barebox is currently starting from at runtime and thus allowing it - barebox to be started at any address. Look at the relocation code and replace - TEXT_BASE with the following calculation of the runtime address: - - bl calc_source /* Calculate Source Address */ -calc_source: - mfspr r4, LR - subi r4, r4, (calc_source - _start) - subi r4, r4, 0x100 - - (I'm almost sure that PowerPC has a dedicated instruction for this, un- - fortunately I know next to nothing of PowerPC assembler, so if you have - a better way to archieve this, please write to the list.) - - On PowerPC barebox now runs at the address it was linked to, so you have - to adjust TEXT_BASE to be in RAM. This makes the various fixup relocation - functions unnecessary. On PowerPC the removal of -fPIC saves around 10% of - binary space. It also simplifies debugging because you will see the correct - addresses in the objdump without doing offset calculation. - -- On ARM most of the duplicate code under cpu/arm* is already merged into - arch/arm/cpu. The start.S files are missing though. diff --git a/Documentation/timekeeping.txt b/Documentation/timekeeping.txt deleted file mode 100644 index ed5ef62fe..000000000 --- a/Documentation/timekeeping.txt +++ /dev/null @@ -1,13 +0,0 @@ ------------- barebox timekeeping ------------- - -In barebox we use the clocksource mechanism from the Linux Kernel. This makes -it fairly easy to add timer functionality for a new board or architecture. -Apart from initialization there is only one function required: -clocksource_read(). This function returns the current value of a free running -counter. Other functions like udelay() and get_time_ns() are derived from this -function. The only thing you have to implement is a clocksource driver. See -cpu/arm920t/imx/interrupts.c for an example. clocksource drivers from the -Linux Kernel can be used nearly 1:1, except for the register accesses. - -for clocksources the __lshrdi3 symbol is needed. You can find the function for -your architecture in the Linux Kernel or a libc of your choice. diff --git a/Documentation/user/automount.rst b/Documentation/user/automount.rst new file mode 100644 index 000000000..a5e431357 --- /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 000000000..caf544de9 --- /dev/null +++ b/Documentation/user/barebox.rst @@ -0,0 +1,230 @@ +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 checked out as follows:: + + $ 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. + +After this, make sure to check out the appropriate branch. If you want to +develop for barebox, it's best to check out the ``next`` branch rather than +the ``master`` branch:: + + $ git checkout -b next origin/remotes/next + +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, +where all configuration is done 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. Currently, ``ARCH`` must 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 to each invocation of the ``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 the ``arch/${ARCH}/configs/`` +directory. For an overview of possible Make targets for your architecture, +type:: + + make help + +Your output from ``make help`` will be based on the architecture you've +selected via the ``ARCH`` variable. So if, for example, you had selected:: + + export ARCH=mips + +your help output would represent all of the generic (architecture-independent) +targets, followed by the MIPS-specific ones:: + + make [ARCH=mips] help + ... + ... list of generic targets ... + ... + 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 _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 + +barebox uses the same (Kbuild) configuration system as Linux, so you can use +all the kernel config targets you already know, e.g. ``make xconfig``, +``make allyesconfig`` etc. + +Configuring and compiling "out-of-tree" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before going any further, it's worth knowing how you can do all your barebox +configuration and compilation "out of tree"; that is, how you can keep your +source directory pristine and have all output from the various ``make`` commands +generated in a separate build directory. + +Once you check out your barebox source directory, and before you do any +configuration or building, set the environment variable ``KBUILD_OUTPUT`` +to point to your intended output directory, as in:: + + export KBUILD_OUTPUT=.../my_barebox_build_directory + +From that point on, all of the ``make`` commands you run in your source +directory will generate their output in your specified output directory. +Not only does this keep your source directory clean, but it allows several +developers to share the same source directory while doing all their own +configuration and building in their own individual build directories. + +.. note:: + + To do out-of-tree builds, your source tree must be absolutely clean + of all generated artifacts from previous configurations and builds. + In other words, if you had earlier done any configuration or building + in that source tree that dumped its results into the same source tree + directory, you need to do the equivalent of a ``make distclean`` before + using that source directory for any out-of-tree builds. + +Compilation +----------- + +After barebox has been :ref:`configured ` it can be compiled +simply with:: + + 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 /mnt/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 at the :ref:`shell `. + +At the shell type ``help`` for a list of supported commands. ``help `` 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 000000000..17427f363 --- /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 000000000..faeeb81fb --- /dev/null +++ b/Documentation/user/defaultenv-2.rst @@ -0,0 +1,133 @@ +Default environment version 2 +============================= + +barebox stores its environment files under the top-level ``/env/`` +directory, where most of the runtime configuration scripts are located. +This 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; rather, 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 +version (version one) should not be used for new boards and is not described here +(even though there are still numerous board definitions that use it). +All new boards should use defaultenv-2 exclusively. + +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//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. + +Note that not all of the above directories will necessarily be +included in your default environment, it depends on your barebox +configuration settings. You can see the configuration variables +and their respective included directories in ``defaultenv/Makefile``:: + + bbenv-$(CONFIG_DEFAULT_ENVIRONMENT_GENERIC_NEW) += defaultenv-2-base + bbenv-$(CONFIG_DEFAULT_ENVIRONMENT_GENERIC_NEW_MENU) += defaultenv-2-menu + bbenv-$(CONFIG_DEFAULT_ENVIRONMENT_GENERIC_NEW_DFU) += defaultenv-2-dfu + bbenv-$(CONFIG_DEFAULT_ENVIRONMENT_GENERIC) += defaultenv-1 + +/env/bin/init +------------- + +This script is executed by the barebox startup code after initialization. +In defaultenv-2, this script will define and set a number of global +variables, followed by sourcing all of the scripts in ``/env/init/`` with:: + + for i in /env/init/*; do + . $i + done + +This script is also responsible for defining the boot timeout value +(by default, three seconds), then printing the timeout prompt for the user. +Be careful making changes to this script: since it is executed before any user +intervention, it might lock the system. + +/env/init/ +---------- + +The ``/env/init/`` directory is the location for startup scripts. The scripts +in this directory will be executed in alphabetical order by the +``/env/bin/init`` script described earlier. + +/env/boot/ +---------- + +The ``/env/boot/`` directory 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 000000000..17934d86e --- /dev/null +++ b/Documentation/user/devicetree.rst @@ -0,0 +1,85 @@ +.. _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 can be used by both the bootloader and the kernel; 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). +Having barebox consult a devicetree is highly recommended for new projects. + +.. _internal_devicetree: + +The internal devicetree +----------------------- + +The devicetree consulted by barebox plays a special role. It is referred to +as the "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 a devicetree different from the one used by barebox. +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 using the +:ref:`command_oftree` command: + +.. 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 000000000..ce7083589 --- /dev/null +++ b/Documentation/user/driver-model.rst @@ -0,0 +1,93 @@ +Driver model +============ + +barebox has a driver model. This matches the devices on a board with their +corresponding drivers. From a user's point of view this is mostly visible in the +:ref:`command_devinfo` and :ref:`command_drvinfo` commands. 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:/ 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 ``:: + + barebox:/ 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: + +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 `` will print the parameters +of a device:: + + barebox:/ 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:/ eth0.ipaddr="This is not an IP" + set parameter: Invalid argument + barebox:/ echo $? + 1 + +**HINT:** barebox has tab completion for variables. Typing ``eth0.`` +will show the parameters for eth0. diff --git a/Documentation/user/framebuffer.rst b/Documentation/user/framebuffer.rst new file mode 100644 index 000000000..0065e7b42 --- /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 000000000..00d4e2983 --- /dev/null +++ b/Documentation/user/hush.rst @@ -0,0 +1,60 @@ +.. 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. + +**NOTE:** hush feels like a normal Unix shell, but it cannot calculate by +itself, i.e. $(($A/2)) won't work. Calculation can however be done +with :ref:`command_let`:: + + A=10 + let B=$A/2 + echo $B diff --git a/Documentation/user/introduction.rst b/Documentation/user/introduction.rst new file mode 100644 index 000000000..8a980a70a --- /dev/null +++ b/Documentation/user/introduction.rst @@ -0,0 +1,29 @@ +Introduction +============ + +This is the barebox user manual, which 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 architectures including +x86, ARM, MIPS, PowerPC and others. + +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 as well as for lean production systems. +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 an e-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 000000000..6c5bab32d --- /dev/null +++ b/Documentation/user/memory-areas.rst @@ -0,0 +1,27 @@ +Memory areas +============ + +Several barebox commands like :ref:`command_md`, :ref:`command_erase` +or :ref:`command_crc` work on an area of memory. Areas have the following form:: + + - + +or:: + + + + +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 000000000..727b98fe5 --- /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 ` 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