You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 9 Next »

Terminology

Buildroot is the tool that we use to build the kernel, kernel modules, user tools, and root file system for our Linux RT machines.

The name we give to the artifacts that buildroot generates is "buildroot".  So, we talk about versions of buildroot as if they are releases of a Linux distribution like Red Hat or Ubuntu.  But they are unrelated to any distribution - they are just buildroot artifacts.

The machines and the buildroot running on these machines are critical to the experiment infrastructure at SLAC.  Experiments have very narrow timing requirements.  This is why we use buildroot.  Buildroot allows us to create a minimal kernel and minimal user tools.  So that for example the kernel is not needlessly interrupted to check for a system update when it should be gathering data for the experiment.

Buildroot also allows user to easily apply patches to the kernel.  We apply the Preempt RT (real time) kernel patch.  This patch makes modifications to the kernel such that kernel interruptions are time-bounded.

Links

Why create a new version?

You might want to create a new version of buildroot if you've found a bug in the current version, or if a new feature is needed.  As I write this document, we have discovered three issues with the current buildroot that must be fixed.

Where do versions exist?

There are two locations in AFS in which we keep our buildroot releases.

  • /afs/slac/g/lcls/package/linuxRT - this location seems to be deprecated
  • /afs/slac/g/lcls/tftpboot/linuxRT/boot - this seems to be the currently-accepted location

You can create directories under the "boot" directory.  You'll see that there are various directory name formats.  Please use a format like this:

  • buildroot-<year>.<month>-<version>-<architecture>

For example:

  • buildroot-2019.08-2-x86_64

The example name indicates it is the second release of buildroot (the artifacts) based off the 2019.08 version of buildroot (the tool).  Note that it does not indicate when you built this version.  You may have built it today but you based it off a version of buildroot from 2019 (or whenever).

We've never had a second release before, so you'll not see -1 or -2 in any of the names, except the version I am working on as I write this doc.

The "ipxe" directory under "boot" contains a file for every machine that boots buildroot.  The filename indicates the machine name.  In that file you will find a line like this:

  • set vers buildroot-2019.08-x86_64

You can modify that line to point at whatever version of buildroot you would like, including a test directory.  Your test directory must not be in a mounted directory (like AFS) as the machine booting won't be able to access mounted file systems.  For this reason, if you have a test directory, it's probably best for it to be in this ("boot") directory.

Versions

There are many versions that get baked in to buildroot.  There is a BusyBox version, a kernel version, a Preempt RT patch version, user tools versions, and of course a buildroot version.

The version of buildroot (the tool) you download and use defines the BusyBox and kernel versions.  The kernel version defines the Preempt RT version.  So, the buildroot (tool) version is the key to all the versions.

Buildroot versions can be found at their downloads page.

The current version that we use (2019.08) is here.

SLAC specifics

We can't use buildroot (tool) exactly as it comes from its website.  We have a git repo which contains all the SLAC-specific stuff.  The repo is here.  The master branch is not used (as I write this doc).  Instead, the branches are named by the release, e.g. br-2019.08.  This is done because each branch works with only a single version of buildroot (tool).  For example, br-2019.08 works with buildroot-2019.08, but not necessarily any other version.

The SLAC-specific stuff:

  • config files for BusyBox, kernel, and buildroot (tool)
    • so you don't have to "make menuconfig" every time you want a new version of buildroot (artifacts)
  • Preempt RT patch (big)
  • other patches (several)
  • pre-rootfs scripts for adding tools, creating users, adding a password to root

The README in the repo is useful, though vague.  I will update it to be more useful.

Note that the BusyBox config file is reset every time a "make clean" is performed in buildroot (tool).  The other config files are preserved.  I plan to fix this.

Setting up

I first tried to unzip buildroot (tool) in AFS.  I much later hit a permissions issue during the build phase.  I would avoid AFS or any mounted file system.  I ultimately used aird-b50-srv01, under the /scratch directory.  In there I created a directory for my username (/scratch/egumtow).

Under that, you should have this structure:

  • buildroot
    • buildroot-<year>.<month>-<version>
      • buildroot-<year>.<month>-<version>-<architecture> (created by unzipping the downloaded buildroot, and renaming the resulting directory)
      • site-top
      • host
      • download

Yes, it's repetitive.  But we will have many buildroots, and different architectures for each buildroot.

Behind the buildroot-<year>.<month>-<version>-<architecture> directory, you must symlink "site" to "../site-top".

Now you must run a SLAC-specific script (br-installconf.sh) to apply things.

And now you can run "make".  It should succeed, and if so, you can find the artifacts in the output/images/ directory.

Here is the full sequence of commands:


  • No labels