summaryrefslogtreecommitdiffstats
path: root/Documentation/user/barebox.rst
blob: b6b7a57af300d519fbafa48ab007d66ea4c1f774 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
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:

https://www.barebox.org/download/

Development versions of barebox are accessible via Git. A local repository clone
can be checked out as follows:

.. code-block:: sh

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

By default, the master branch is checked out. If you want to develop for
barebox, this is the right branch to send patches against.

If you want to see which patches are already selected for the next release,
you can look at the ``next`` branch:

.. code-block:: sh

  $ git checkout -b next origin/remotes/next

A web interface to the repository is available at
https://git.pengutronix.de/cgit/barebox

.. _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
* mips
* openrisc
* ppc
* riscv
* 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:

.. code-block:: sh

  export ARCH=arm
  export CROSS_COMPILE=/path/to/arm-cortexa8-linux-gnueabihf-
  make ...

or add them to each invocation of the ``make`` command:

.. code-block:: sh

  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:

.. code-block:: sh

  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:

.. code-block:: sh

  export ARCH=mips

your help output would represent all of the generic (architecture-independent)
targets, followed by the MIPS-specific ones:

.. code-block:: sh

  make [ARCH=mips] help
  ...
  ... list of generic targets ...
  ...
  Architecture specific targets (mips):
    No architecture specific help defined for mips

    ath79_defconfig          - Build for ath79
    bcm47xx_defconfig        - Build for bcm47xx
    gxemul-malta_defconfig   - Build for gxemul-malta
    loongson-ls1b_defconfig  - Build for loongson-ls1b
    qemu-malta_defconfig     - Build for qemu-malta
    xburst_defconfig         - Build for xburst

barebox supports building for multiple boards with a single config. If you
can't find your board in the list, it may be supported by one of the multi-board
configs. As an example, this is the case for tegra_v7_defconfig and imx_v7_defconfig.
Select your config with ``make <yourboard>_defconfig``:

.. code-block:: sh

  make imx_v7_defconfig

The configuration can be further customized with one of the configuration frontends
with the most popular being ``menuconfig``:

.. code-block:: sh

  make menuconfig

barebox uses the same configuration and build system as Linux (Kconfig,
Kbuild), 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:

.. code-block:: sh

  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 <configuration>` it can be compiled
simply with:

.. code-block:: sh

  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

.. _second_stage:

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 ``bootm`` command:

.. code-block:: console

  U-Boot: tftp $load_addr barebox.bin
  U-Boot: bootm $load_addr

With barebox already running on your board, this can be used to chainload
another barebox. For instance, if you mounted a TFTP server to ``/mnt/tftp``
(see :ref:`filesystems_tftp` for how to do that), chainload barebox with:

.. code-block:: console

  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:

.. code-block:: console

  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 <hush>`.

At the shell type ``help`` for a list of supported commands. ``help <command>`` shows
the usage for a particular command. barebox has tab completion which will complete
your command. Arguments to commands are also completed depending on the command. If
a command expects a file argument only files will be offered as completion. Other
commands will only complete devices or devicetree nodes.

Building barebox tools
----------------------

The normal barebox build results in one or more barebox images (cf. :ref:`multi_image`)
and a number of tools built from its ``scripts/`` directory.

Most tools are used for the barebox build itself: e.g. the device tree compiler,
the Kconfig machinery and the different image formatting tools that wrap barebox,
so it may be loaded by the boot ROM of the relevant SoCs.

In addition to these barebox also builds host and target tools that are useful
outside of barebox build: e.g. to manipulate the environment or to load an
image over a boot ROM's USB recovery protocol.

There are two ``ARCH=sandbox`` to make this more straight forward:

Host Tools
^^^^^^^^^^

The ``hosttools_defconfig`` will compile standalone host tools for the
host (build) system. To build the USB loaders, ``pkg-config`` needs to know
about ``libusb-1.0``.

.. code-block:: console

  export ARCH=sandbox
  make hosttools_defconfig
  make scripts

Target Tools
^^^^^^^^^^^^

The ``targettools_defconfig`` will cross-compile standalone target tools for the
target system.  To build the USB loaders, ``CROSS_PKG_CONFIG`` needs to know
about ``libusb-1.0``. This config won't built any host tools, so it's ok to
set ``CROSS_PKG_CONFIG=pkg-config`` if ``pkg-config`` is primed for target
use. The default is ``CROSS_PKG_CONFIG=$(CROSS_COMPILE)pkg-config``. Example:

.. code-block:: console

  export ARCH=sandbox CROSS_COMPILE=aarch64-linux-gnu-
  export CROSS_PKG_CONFIG=pkg-config
  make targettools_defconfig
  make scripts