Instructions for building and booting Linux: Difference between revisions

From Linux/Xtensa
Jump to navigation Jump to search
(Use menuconfig instead of editing the kernel's .config directly.)
m (building kernel on its own)
 
(109 intermediate revisions by 5 users not shown)
Line 1: Line 1:
These instructions explain how to build a toolchain, root filesystem and kernel for Linux running on an Xtensa processor.  These instructions apply specifically to the XTAV60 (LX60) board.  They are based on a snapshot of work in progress.
This page describes what parts are necessary in order to run GNU/Linux OS on Xtensa, their interaction and setup.


Some general notes on these instructions:
= GNU/Linux on Xtensa =


*  The following was tested on an x86 machine running Fedora Core 3 (FC3) and Fedora Core 6 (FC6).  Other host distributions likely work but have not been tested.
GNU is a collection of free software that provides POSIX environment.
Linux is an operating system kernel.
In order to boot GNU/Linux OS on Xtensa the following parts are needed:


* Lines prefixed with "sudo" need to be executed as root.  The rest is best executed as a non-root user.  (It is possible to install subversion and git as a non-root user if root access is an issue.  How to do this isn't shown here.)
* a board with Xtensa core supported by Linux, or Xtensa simulator
* bootable Linux kernel image
* GNU software packaged in a form suitable for booting on Linux, the so called root file system
* a bootloader or on-chip debugger capable of loading Linux kernel image into the board RAM


*  Lines that set environment variables assume a Bourne compatible shell (e.g. /bin/sh or bash), but are easily adapted to other shells.
To build Linux image and root file system a toolchain correctly configured for used Xtensa core is needed. Toolchain configuration is performed by application of [[Toolchain_Overlay_File|Xtensa configuration overlay]]. Correct toolchain configuration is critical for building other pieces of software correctly.


*  Instructions are assumed executed all in order (e.g. commands assume current directory and environment variables set earlier).
== Xtensa cores supported by Linux ==


Official requirements for Xtensa core to run Linux are listed in the Xtensa OSKit Guide document.
The absolute minimum set of options required to run Linux is windowed registers, exception option and one level-1 or medium level timer interrupt.
* Full MMU option is required for full featured Linux kernel that includes process address space isolation, virtual memory and fork syscall.
* Full MMU option, thread pointer option and conditional store option are required for running userspace with NPTL or TLS.


== Xtensa boards supported by Linux ==


== Ensure you have all needed packages installed on your system ==
The following boards collectively referred as XTFPGA family are readily supported by Linux: Avnet LX60, LX110, LX200; Xilinx ML605, KC705. For board details/setup guide please see corresponding Board Guide or Board Prototyping Guide provided with Xtensa software release.


=== Install the 'subversion' source control tools ===
== Xtensa simulators ==


Download and install the 'subversion' source control tools if you
* Xtensa software provides Instruction Set Simulator (xt-run) capable of running Linux configured for ISS.
don't have it already installed (FC6 has it, FC3 doesn't):
* QEMU is a free system emulator capable of emulating any XTFPGA board or ISS. It can be configured to emulate any Xtensa core, but it does not currently support TIE extensions to the core architecture. Please see [[Xtensa_on_QEMU|this]] page for more details.


  $ sudo yum install subversion
== Linux kernel ==


This may install dependent packages (e.g. 'apr', etc).
Linux kernel needs to be configured for the specific Xtensa core. For that reason Linux is usually configured and built separately from the userspace software. Please see [[Linux_Kernel|this]] page for more details.


=== Download and install the 'git' source control tools ===
== Root file system ==


Download and install the 'git' source control tools if you
Currently we support building GNU software and packaging it into root file system with the [[Buildroot]].
don't already have it installed. On FC3, yum doesn't know about git,
There are several types of root file system that Linux can boot with:
so you have to do something like:


  $ cd /tmp
=== CPIO archive ===
  $ lwp-download http://kernel.org/pub/software/scm/git/git-1.5.3.1.tar.bz2
* CPIO archive may be built into the kernel (so called 'built-in initramfs'), the resulting single image will contain both Linux and GNU software. It's easy to boot, but in order to change anything the kernel needs to be rebuilt.
  $ tar xfj git-1.5.3.1.tar.bz2
* CPIO archive may also be loaded separately from the kernel, but used in the same way as the built-in initramfs. It's harder to boot (two files instead of one), but easier to change.
  $ cd git-1.5.3.1
  $ make prefix=/usr/local all
  $ sudo make prefix=/usr/local install


This doesn't install git documentation. For that, you have
Both cases of CPIO use RAM for the root file system, so they're very fast. The downsides are that they take some time at startup to unpack, reserve some RAM (which may be an issue on low-memory boards like LX60) and are not persistent.
to build 'doc' and 'info' make targets, which require first
installing other packages such as 'asciidoc' and others.
However, for this example, documentation is not necessary.


On FC6, you can just do the following, which includes docs:
=== EXT2/3/4 file system image ===
EXT2/3/4 file system image may be used directly with ISS or QEMU through the Simulated block device Linux feature. Please see [[Linux_Kernel#ISS_platform|this]] chapter for more details.


  $ sudo yum install git
=== TAR image ===
Tar image may be unpacked into a directory shared through NFS. Linux on XTFPGA boards and on QEMU can be configured to use NFS root file system.


== Download and build a toolchain and root filesystem using buildroot ==
=== UBIFS image ===
UBIFS image may be written directly to the daughterboard FLASH on XTFPGA boards. Please see [[Linux_Kernel#Rootfs_in_FLASH_.28UBIFS.29|this]] chapter for more details.


  $ cd <workdir>
== Bootloader ==
U-Boot can be used as a bootloader on XTFPGA boards. Please see [[U-Boot|this]] page for more details about installing it into the daughterboard FLASH.


where <workdir> is the path to an empty directory on a disk with
== On-chip debugger ==
at least 4 GB available space.
On-chip debugger is good for debugging lowest level software: bootloader and Linux kernel itself. It also allows loading executable images into new board with empty FLASH.
The following creates and populates the <workdir>/trunk directory:
It consists of JTAG probe connected to the XTFPGA daughterboard (ML605 and KC705 daughterboards also have built-in JTAG chip), OCD monitor (xt-ocd) running on developer machine where the other end of JTAG probe is connected, and xt-gdb, the modified version of GNU debugger from the Xtensa software release. Please see Tensilica Debug User's Guide for more information about OCD setup and configuration.


  $ svn co svn://linux-xtensa.org/var/svn/repos/buildroot/trunk/
= Building GNU/Linux OS =
In order to follow these instruction a build machine with GNU/Linux and a set of development tools (native binutils and gcc, make, wget, tar, ...) is needed. In the following example all software will be downloaded and built in the current directory. Xtensa tools used in the examples are installed into $XT_ROOT, tools release is $XT_RELEASE and selected core is $XT_CORE.


== Prepare the overlay ==
Please see [[Toolchain_Overlay_File|this]] page for overlay repacking script and details of the overlay source location.
Create conversion script by pasting [[Toolchain_Overlay_File#Conversion_Script|this]] into the file overlay-script and making it executable:
  $ '''cat > overlay-script'''
  '''....'''
  ^D
  $ '''chmod +x overlay-script'''


=== Change some default behavior ===
Run it and rename the resulting file:
  $ '''./overlay-script ${XT_ROOT}/XtDevTools/install/builds/${XT_RELEASE}-linux/${XT_CORE}/src/xtensa-config-overlay.tar.gz'''
  $ '''mv xtensa-overlay.tar xtensa_${XT_CORE}.tar'''


Edit  trunk/target/generic/target_skeleton/etc/inittab
== Get, configure and build the toolchain and root file system ==
Get the buildroot git tree:
  $ '''git clone git://git.buildroot.net/buildroot'''


Comment out the default getty's:
Check out some released version:
  $ '''git checkout 2014.11'''


      # Set up a couple of getty's
Create build directory and configure it:
      #tty1::respawn:/sbin/getty 38400 tty1
  $ '''mkdir buildroot-build'''
      #tty2::respawn:/sbin/getty 38400 tty2
  $ '''make -C buildroot O=$(pwd)/buildroot-build menuconfig'''


Un-comment the serial port getty and modify the baud rate:
Please see [[Buildroot#Configuring_and_building_Buildroot|this]] chapter for more details about configuring the Buildroot.


      # Put a getty on the serial port
Select 'Target Architecture' = Xtensa, 'Target Architecture Variant' = Custom Xtensa processor configuration, set 'Overlay file for custom configuration ' to the location of the overlay archive (it may be a path to a local file or an URL).
      ttyS0::respawn:/sbin/getty -L ttyS0 38400 vt100


Select toolchain options, packages to be built and final root file system image type. Select whether the kernel need to be built, kernel version and configuration.


=== Prepare the overlay for gcc and binutils ===
Build the toolchain, kernel and the root file system:
  $ '''make -C buildroot O=$(pwd)/buildroot-build'''


  $ cd <workdir>
== The kernel may be built on its own ==
  $ mkdir overlay-DC232L
Get stable Linux release tree:
  $ cd overlay-DC232L
  $ '''wget https://www.kernel.org/pub/linux/kernel/v3.x/linux-3.19.1.tar.xz'''
  $ lwp-download http://linux-xtensa.org/pub/processors/dc232l/dc232l-binutils.tar
  $ '''tar -xf linux-3.19.1.tar.xz'''
  $ lwp-download http://linux-xtensa.org/pub/processors/dc232l/dc232l-gcc.tar
 
  $ export XTENSA_CONFIG_DIR='<workdir>/overlay-DC-232L'
  $ export XTENSA_CONFIG_NAME='dc232l'


(As usual, replace <workdir> with the appropriate full path.)
Create variant directory for the specific core and copy core configuration files there:
  $ '''mkdir -p linux-3.19.1/arch/xtensa/variants/${XT_CORE}/include/variant'''
  $ '''cp ${XT_ROOT}/XtDevTools/install/builds/${XT_RELEASE}-linux/${XT_CORE}/config/*.h linux-3.19.1/arch/xtensa/variants/${XT_CORE}/include/variant'''


=== Configure buildroot ===
Create build directory and configure it:
  $ '''mkdir linux-build'''
  $ '''ARCH=xtensa CROSS_COMPILE=$(pwd)/buildroot-build/host/usr/bin/xtensa-buildroot-linux-uclibc- make -C linux-3.19.1 O=$(pwd)/linux-build menuconfig'''


Note:  You need the TERM environment variable properly set for curses
Select 'Xtensa Processor Configuration' = Custom Xtensa processor configuration, set 'Xtensa Processor Custom Core Variant Name' to the contents of ${XT_CORE}. Select desired 'Xtensa System Type'.
based tools to work.


  $ cd <workdir>/trunk
Please see [[Linux_Kernel#Configuring_the_kernel|this]] chapter for more details about configuring Linux.
  $ make ARCH=xtensa menuconfig


You should get a curses interface for configuring buildroot.
Build the kernel:
Make the following changes:
  $ '''ARCH=xtensa CROSS_COMPILE=$(pwd)/buildroot-build/host/usr/bin/xtensa-buildroot-linux-uclibc- make -C linux-3.19.1 O=$(pwd)/linux-build all'''


* Change 'Target Architecture' from i386 to xtensa
= Booting GNU/Linux =
* Change 'Target Architecture Variant' from xtensa_generic to DC 232L
TBD
* Under 'Toolchain Options', change 'Binutils Version' from '2.17' to '2.17.50.0.17'
* Under 'Toolchain Options', make sure 'uClibc C library Version' is set to (uClibc 0.9.29)
* Under 'Target Options', enable 'cpio the root filesystem'; this creates a 'Compression method' submenu; under this submenu, select 'gzip'
* Again under 'Target Options', enable 'initramfs for initial ramdisk of linux kernel'
* Exit and save the configuration
 
=== Configure uClibc ===
 
  $ make ARCH=xtensa uclibc-config
 
Select '24' for 'xtensa' and accept all default settings (ENTER).
 
 
=== Build buildroot ===
 
  $ make ARCH=xtensa
 
Wait patiently for build to complete.  This builds an entire toolchain
as well as some basic packages, and constructs a root filesystem.
 
 
== Build a Linux kernel ==
 
=== Download the kernel ===
 
  $ cd <workdir>
  $ git clone git://git.linux-xtensa.org/kernel/xtensa-devel
 
This creates and populates the <workdir>/xtensa-devel directory.
 
 
=== Configure the kernel ===
 
The build is a two-step process:  configure the kernel, and build it.
First, before we can do anything with the kernel, set your PATH to
point to the toolchain built using buildroot.
 
  $ export PATH="<workdir>/trunk/build_xtensa/staging_dir/usr/bin:$PATH"
 
Now setup a destination for kernel builds.
We usually like to have the build directory separate from
the source directory, so we use 'O=</destination/path>' in
kernel make commands.
 
  $ mkdir build-kernel
 
Let's start with the default configuration for the XTAV60 (LX60)
board as follows
(one long line if you omit the '\' continuator):
 
  $ cd xtensa-devel
  $ make O=../build-kernel ARCH=xtensa CROSS_COMPILE=xtensa-linux-uclibc-  \
        KBUILD_DEFCONFIG=lx60_defconfig defconfig
 
This configures the kernel using the default configuration found in
arch/xtensa/configs/lx60_defconfig.
 
Let's customize this a little bit to bundle the root filesystem into the kernel:
 
  $ make O=../build-kernel ARCH=xtensa CROSS_COMPILE=xtensa-linux-uclibc-  menuconfig
 
Under '''General setup''',
make sure the '''Initial RAM filesystem and RAM disk (initramfs/initrd) support'''
entry is enabled.  Underneath that, edit '''Initramfs source file(s)''',
and enter the path to the cpio formatted root filesystem
generated by buildroot:
 
      <workdir>/trunk/binaries/uclibc/rootfs.xtensa.cpio.gz
 
(Don't forget to replace <workdir> with the appropriate full path.)
 
Exit menuconfig, saving your configuration changes.
 
Backup your configuration outside the build directory.  For example:
 
  $ cp ../build-kernel/.config config.saved
 
If you do a clean rebuild of the kernel (e.g. "rm -rf ../build-kernel")
you can now configure it with simply:
          mkdir ../build-kernel ; cp config.saved ../build-kernel/.config
Of course if you update the kernel, you'll probably again have to do:
          make O=../build-kernel ARCH=xtensa CROSS_COMPILE=xtensa-linux-uclibc-  menuconfig
and save a new copy of your configuration.
 
=== Build the kernel ===
 
  $ make O=../build-kernel ARCH=xtensa CROSS_COMPILE=xtensa-linux-uclibc-
 
The build will issue a few warnings which are normal, such as
about RSR macro, elfcore.h, and section mismatches in MODPOST.
Once complete, the bootable image is in:
      <workdir>/build-kernel/arch/xtensa/boot/Image.elf
and the uncompressed ELF file containing kernel symbols is in:
      <workdir>/build-kernel/vmlinux
There is also a RedBoot bootable image (if you use RedBoot) in:
      <workdir>/build-kernel/arch/xtensa/boot/zImage.redboot
 
== Run the resulting kernel ==
 
=== Install Xtensa Tools with the 232L core ===
 
This can be done a a different machine than the one used so far,
as long as it has access to the <workdir> directory tree.
 
=== Install and setup the Xtensa OCD Daemon ===
 
Setup and connect your JTAG probe, etc.
 
=== Connect a terminal server ===
 
At 38400 bps 8N1 no flow control to the LX60 serial port.
 
=== Optionally, setup networking ===
 
This step is optional.
 
Setup the board's MAC address using dipswitches
(see LX60 docs) and connect the LX60 to a network that has a
DHCP server that will respond to that MAC address.
If you don't do this step, you'll simply not have network
access, and the boot process will take a minute or so longer
while the kernel times out waiting for a BOOTP response.
You can edit the kernel configuration and rebuild the kernel
to avoid using bootp (in particular, remove "ip=bootp" from
the kernel cmdline).
 
=== Download and run the kernel ===
 
Reset the LX60 board (see board documentation).
 
Using Xtensa Tools, invoke:
 
  $ xt-gdb <workdir>/build-kernel/arch/xtensa/boot/Image.elf
 
  (xt-gdb) target remote <ocdhost>:20000 0
  (xt-gdb) reset
  (xt-gdb) load
  (xt-gdb) set $pc = &_ResetVector
  (xt-gdb) symbol-file <workdir>/build-kernel/vmlinux
  (xt-gdb) c
 
where <ocdhost> is the IP address or DNS name of the machine
running the Xtensa OCD daemon.  The Linux kernel should
start booting as soon as 'c' (continue) is executed.
 
You should eventually get a login prompt.
Just login as root (no password).
 
Try various Linux commands.  Look at /bin, /sbin, /usr/bin,
etc to see what's available.  Not all guaranteed to work,
but basic things like 'ls' and 'ping' seem to work fine.
 
Note:  no need to setup an NFS or TFTP server.  The filesystem
is contained within the kernel image.  You may be able to mount
other filesystems over NFS though, if you wish, after booting.

Latest revision as of 01:21, 30 August 2019

This page describes what parts are necessary in order to run GNU/Linux OS on Xtensa, their interaction and setup.

GNU/Linux on Xtensa

GNU is a collection of free software that provides POSIX environment. Linux is an operating system kernel. In order to boot GNU/Linux OS on Xtensa the following parts are needed:

  • a board with Xtensa core supported by Linux, or Xtensa simulator
  • bootable Linux kernel image
  • GNU software packaged in a form suitable for booting on Linux, the so called root file system
  • a bootloader or on-chip debugger capable of loading Linux kernel image into the board RAM

To build Linux image and root file system a toolchain correctly configured for used Xtensa core is needed. Toolchain configuration is performed by application of Xtensa configuration overlay. Correct toolchain configuration is critical for building other pieces of software correctly.

Xtensa cores supported by Linux

Official requirements for Xtensa core to run Linux are listed in the Xtensa OSKit Guide document. The absolute minimum set of options required to run Linux is windowed registers, exception option and one level-1 or medium level timer interrupt.

  • Full MMU option is required for full featured Linux kernel that includes process address space isolation, virtual memory and fork syscall.
  • Full MMU option, thread pointer option and conditional store option are required for running userspace with NPTL or TLS.

Xtensa boards supported by Linux

The following boards collectively referred as XTFPGA family are readily supported by Linux: Avnet LX60, LX110, LX200; Xilinx ML605, KC705. For board details/setup guide please see corresponding Board Guide or Board Prototyping Guide provided with Xtensa software release.

Xtensa simulators

  • Xtensa software provides Instruction Set Simulator (xt-run) capable of running Linux configured for ISS.
  • QEMU is a free system emulator capable of emulating any XTFPGA board or ISS. It can be configured to emulate any Xtensa core, but it does not currently support TIE extensions to the core architecture. Please see this page for more details.

Linux kernel

Linux kernel needs to be configured for the specific Xtensa core. For that reason Linux is usually configured and built separately from the userspace software. Please see this page for more details.

Root file system

Currently we support building GNU software and packaging it into root file system with the Buildroot. There are several types of root file system that Linux can boot with:

CPIO archive

  • CPIO archive may be built into the kernel (so called 'built-in initramfs'), the resulting single image will contain both Linux and GNU software. It's easy to boot, but in order to change anything the kernel needs to be rebuilt.
  • CPIO archive may also be loaded separately from the kernel, but used in the same way as the built-in initramfs. It's harder to boot (two files instead of one), but easier to change.

Both cases of CPIO use RAM for the root file system, so they're very fast. The downsides are that they take some time at startup to unpack, reserve some RAM (which may be an issue on low-memory boards like LX60) and are not persistent.

EXT2/3/4 file system image

EXT2/3/4 file system image may be used directly with ISS or QEMU through the Simulated block device Linux feature. Please see this chapter for more details.

TAR image

Tar image may be unpacked into a directory shared through NFS. Linux on XTFPGA boards and on QEMU can be configured to use NFS root file system.

UBIFS image

UBIFS image may be written directly to the daughterboard FLASH on XTFPGA boards. Please see this chapter for more details.

Bootloader

U-Boot can be used as a bootloader on XTFPGA boards. Please see this page for more details about installing it into the daughterboard FLASH.

On-chip debugger

On-chip debugger is good for debugging lowest level software: bootloader and Linux kernel itself. It also allows loading executable images into new board with empty FLASH. It consists of JTAG probe connected to the XTFPGA daughterboard (ML605 and KC705 daughterboards also have built-in JTAG chip), OCD monitor (xt-ocd) running on developer machine where the other end of JTAG probe is connected, and xt-gdb, the modified version of GNU debugger from the Xtensa software release. Please see Tensilica Debug User's Guide for more information about OCD setup and configuration.

Building GNU/Linux OS

In order to follow these instruction a build machine with GNU/Linux and a set of development tools (native binutils and gcc, make, wget, tar, ...) is needed. In the following example all software will be downloaded and built in the current directory. Xtensa tools used in the examples are installed into $XT_ROOT, tools release is $XT_RELEASE and selected core is $XT_CORE.

Prepare the overlay

Please see this page for overlay repacking script and details of the overlay source location. Create conversion script by pasting this into the file overlay-script and making it executable: 

 $ cat > overlay-script
 ....
 ^D
 $ chmod +x overlay-script

Run it and rename the resulting file: 

 $ ./overlay-script ${XT_ROOT}/XtDevTools/install/builds/${XT_RELEASE}-linux/${XT_CORE}/src/xtensa-config-overlay.tar.gz
 $ mv xtensa-overlay.tar xtensa_${XT_CORE}.tar

Get, configure and build the toolchain and root file system

Get the buildroot git tree: 

 $ git clone git://git.buildroot.net/buildroot

Check out some released version: 

 $ git checkout 2014.11

Create build directory and configure it: 

 $ mkdir buildroot-build
 $ make -C buildroot O=$(pwd)/buildroot-build menuconfig

Please see this chapter for more details about configuring the Buildroot.

Select 'Target Architecture' = Xtensa, 'Target Architecture Variant' = Custom Xtensa processor configuration, set 'Overlay file for custom configuration ' to the location of the overlay archive (it may be a path to a local file or an URL).

Select toolchain options, packages to be built and final root file system image type. Select whether the kernel need to be built, kernel version and configuration.

Build the toolchain, kernel and the root file system: 

 $ make -C buildroot O=$(pwd)/buildroot-build

The kernel may be built on its own

Get stable Linux release tree: 

 $ wget https://www.kernel.org/pub/linux/kernel/v3.x/linux-3.19.1.tar.xz
 $ tar -xf linux-3.19.1.tar.xz

Create variant directory for the specific core and copy core configuration files there: 

 $ mkdir -p linux-3.19.1/arch/xtensa/variants/${XT_CORE}/include/variant
 $ cp ${XT_ROOT}/XtDevTools/install/builds/${XT_RELEASE}-linux/${XT_CORE}/config/*.h linux-3.19.1/arch/xtensa/variants/${XT_CORE}/include/variant

Create build directory and configure it: 

 $ mkdir linux-build
 $ ARCH=xtensa CROSS_COMPILE=$(pwd)/buildroot-build/host/usr/bin/xtensa-buildroot-linux-uclibc- make -C linux-3.19.1 O=$(pwd)/linux-build menuconfig

Select 'Xtensa Processor Configuration' = Custom Xtensa processor configuration, set 'Xtensa Processor Custom Core Variant Name' to the contents of ${XT_CORE}. Select desired 'Xtensa System Type'.

Please see this chapter for more details about configuring Linux.

Build the kernel: 

 $ ARCH=xtensa CROSS_COMPILE=$(pwd)/buildroot-build/host/usr/bin/xtensa-buildroot-linux-uclibc- make -C linux-3.19.1 O=$(pwd)/linux-build all

Booting GNU/Linux

TBD

Retrieved from "http://wiki.linux-xtensa.org/index.php?title=Instructions_for_building_and_booting_Linux&oldid=788"