9
0
Fork 0

Merge branch 'for-next/doc'

master
Sascha Hauer 2014-07-04 17:19:40 +02:00
commit ce1b0d4ae3
186 changed files with 3357 additions and 5223 deletions

2
.gitignore vendored
View File

@ -67,6 +67,8 @@ include/generated
# Generated files
Doxyfile.version
Documentation/commands/*.rst
doctrees/
# stgit generated dirs
patches-*

View File

@ -1 +1,2 @@
build
html

View File

@ -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:
- <b>POSIX File API:</b><br>
@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.
- <b>Shell:</b><br>
We have the standard shell commands like ls/cd/mkdir/echo/cat,...
- <b>Environment Filesystem:</b><br>
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'.
- <b>Filesystem Support:</b><br>
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.
- <b>Driver Model (borrowed from Linux):</b><br>
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.
- <b>Clocksource:</b><br>
We use the standard clocksource API from Linux.
- <b>Kconfig/Kbuild:</b><br>
This gives us parallel builds and removes the need for lots of ifdefs.
- <b>Sandbox:</b><br>
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.
- <b>Device Parameters:</b><br>
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 \<devid\>.\<param\>="...". 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'.
- <b>Getopt:</b><br>
@a Barebox has a lightweight getopt() implementation. This makes it
unnecessary to use positional parameters, which can be hard to read.
- <b>Integrated Editor:</b><br>
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
*/

View File

@ -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/\<architecture\>/boards/\<boardname\>
- arch/\<architecture\>/boards/\<boardname\>/Makefile
- arch/\<architecture\>/boards/\<boardname\>/\<boardname\>.c
- arch/\<architecture\>/boards/\<boardname\>/\<boardname\>.dox
- include/configs/\<boardname\>.h
- arch/\<architecture\>/configs/\<boardname\>_defconfig
@subsection board_makefile arch/\<architecture\>/boards/\<boardname\>Makefile
@verbatim
obj-y += all files that builds the BSP (Assembler and/or C files)
@endverbatim
@subsection board_basefile arch/\<architecture\>/boards/\<boardname\>\<boardname\>.c
TBD
@subsection board_doxygen arch/\<architecture\>/boards/\<boardname\>/\<boardname\>.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 <boardname> <Manufacturer> <Board's Name>
This board uses an <architecture> 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 ("<boardname>" in the
template above) into Documentation/boards.dox as:
@verbatim
...
@subpage <boardname>
...
@endverbatim
at the right architecture.
@note Consider to use an unique page lable.
@subsection board_lscript arch/\<architecture\>/boards/\<boardname\>/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 += <board_linker_script>
@endverbatim
in your local \b Makefile to the list of files, forwarded to the last linking step.
@section board_defconfig arch/\<architecture\>/configs/\<boardname\>_defconfig
TBD
@section board_mod_files These files needs to be modified:
- modify Documentation/board.dox
- modify arch/\<architecture\>/Kconfig
- add your board (MACH_*) to the list
- add your default text base address for this architecture (ARCH_TEXT_BASE)
- modify arch/\<architecture\>/Makefile:
- add board-$(MACH_*) = \<your board_dir\>
First, the new board should be visible in the menu.
@section board_specific_cpu Porting hints for specific CPUs
@li @subpage dev_s3c24xx_mach
*/

View File

@ -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 <reference>) and include it here with:
*
* @subpage <reference>
*
*/

10
Documentation/boards.rst Normal file
View File

@ -0,0 +1,10 @@
.. _boards:
Board support
=============
.. toctree::
:glob:
:maxdepth: 2
boards/*

View File

@ -0,0 +1,9 @@
Cirrus Logic edb9xxx
====================
.. toctree::
:glob:
:numbered:
:maxdepth: 1
edb9xxx/*

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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/*

View File

@ -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

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -0,0 +1,9 @@
MIPS
====
.. toctree::
:glob:
:numbered:
:maxdepth: 1
mips/*

View File

@ -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 <LAN> 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

View File

@ -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 <Enter> 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

View File

@ -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/

View File

@ -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

View File

@ -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/

View File

@ -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.

View File

@ -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.

View File

@ -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

View File

@ -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.

View File

@ -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.

View File

@ -0,0 +1,9 @@
Samsung S3C/S5P
===============
.. toctree::
:glob:
:numbered:
:maxdepth: 1
s3c/*

View File

@ -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 [<OPTIONS>]
Available sandbox invocation options include:
``-m``, ``--malloc=<size>``
Start sandbox with a specified malloc-space <size> in bytes.
``-i <file>``
Map a <file> to barebox. This option can be given multiple times. The <file>s
will show up as ``/dev/fd0`` ... ``/dev/fdX`` in the barebox simulator.
``-e <file>``
Map <file> to barebox. With this option <file>s are mapped as
``/dev/env0`` ... ``/dev/envX`` and thus are used as default environment.
A clean file generated with ``dd`` will do to get started with an empty environment.
``-O <file>``
Register <file> as a console capable of doing stdout. <file> can be a
regular file or a FIFO.
``-I <file>``
Register <file> as a console capable of doing stdin. <file> can be a regular
file or a FIFO.
``-x``, ``--xres <res>``
Specify SDL width.
``-y``, ``--yres <res>``
Specify SDL height.

View File

@ -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.

View File

@ -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 = (\<size of barebox image\> + 511) / 512
To be able to store the runtime configuration, further free sectors are
required. Its up to you and your requirements, how large this persistant
storage must be. If you need 16 kiB for this purpose, you need to keep
additional 32 sectors free.
For this example we are reserving 300 sectors for the barebox image and
additionaly 32 sectors for the persistant storage. So, the first partition on
the boot media must start at sector 333 or later.
Run the fdisk tool to setup such a partition table::
[jb@host]~> fdisk /dev/sda
Command (m for help): p
Disk /dev/sda: 20.7 MB, 212680704 bytes
16 heads, 63 sectors/track, 406 cylinders
Units = cylinders of 1008 * 512 = 516096 bytes
Device Boot Start End Blocks Id System
Change the used units to sectors for easier handling.
::
Command (m for help): u
Changing display/entry units to sectors
Command (m for help): p
Disk /dev/sda: 20.7 MB, 212680704 bytes
16 heads, 63 sectors/track, 406 cylinders, total 409248 sectors
Units = sectors of 1 * 512 = 512 bytes
Device Boot Start End Blocks Id System
Now its possible to create the first partition with the required offset::
Command (m for help): n
Command action
e extended
p primary partition (1-4)
p
Partition number (1-4): 1
First sector (63-409247, default 63): 333
Last sector or +size or +sizeM or +sizeK (333-409247, default 409247): +18M
Command (m for help): p
Disk /dev/sda: 20.7 MB, 212680704 bytes
16 heads, 63 sectors/track, 406 cylinders, total 409248 sectors
Units = sectors of 1 * 512 = 512 bytes
Device Boot Start End Blocks Id System
/dev/sda 333 35489 17578+ 83 Linux
That's all. Do whatever is required now with the new partition (formatting
and populating the root filesystem for example) to make it useful.
In the next step, barebox gets installed to this boot media::
[jb@host]~> scripts/setupmbr/setupmbr -s 32 -m ./barebox -d /dev/sda
This command writes the barebox image file './barebox' onto the device
/dev/sda.
The -s option will keep the persistant storage sectors free and untouched
and set flags in the MBR to forward its existance, size and location to
barebox at runtime. setupmbr also does not change the partition table.
The barebox image gets stored on the boot media like this::
sector 0 1 33 333
|---|-------------|--------------- ~~~ ------------|--------------
MBR persistant barebox first
storage main image partition
If the -s option is omitted, the "persistant storage" part simply does
not exist::
sector 0 1 333
|---|--------------- ~~~ ------------|--------------
MBR barebox first
main image partition
**NOTE:** the ``setupmbr`` tool is also working on real image file than on device
nodes only. So, there is no restriction what kind of file will be
modified.

View File

@ -1,60 +0,0 @@
/** @page building Building
<i>This section describes how to build the Barebox bootloader.</i>
@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=\<architecture>
- CROSS_COMPILE=\<compiler-prefix>
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 \<n\>' 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
*/

View File

@ -1,111 +0,0 @@
/**
* @page command_reference Shell Commands
<i>This section describes the commands which are available on the @a
Barebox shell. </i>
@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
*/

View File

@ -0,0 +1,9 @@
Command reference
=================
.. toctree::
:glob:
:maxdepth: 1
commands/*

262
Documentation/conf.py Normal file
View File

@ -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