Difference between revisions of "Build Xinu"

From Embedded Xinu
Jump to navigation Jump to search
(→‎Building the XINU image: Link to build system guide)
 
(27 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 +
[[Category:HOWTO]]
 
The new MIPS port of Embedded XINU has been released.  See the [[Downloads]] tab for more information.
 
The new MIPS port of Embedded XINU has been released.  See the [[Downloads]] tab for more information.
A revision of Doug Comer's venerable ''Operating System Design - The XINU Approach'' textbook is in progress.
 
  
= Cross-Compiler =
+
== Cross-Compiler ==
 +
=== RISC-V Cross-Compiler and Toolchain ===
 +
The RISC-V cross-compiler and toolchain can be found [[https://github.com/riscv-collab/riscv-gnu-toolchain here]].  Installing the toolchain installs the cross-compiler, LLVM, QEMU, and GCC all with RISC-V support.
 +
 
 +
==== Installing the Toolchain ====
 +
1. Clone the RISC-V toolchain.  Note, this may take a while.
 +
 
 +
    git clone https://github.com/riscv-collab/riscv-gnu-toolchain --recurse-submodules
 +
2. Install the dependencies for your system
 +
 
 +
'''For Ubuntu'''
 +
 
 +
    sudo apt-get install autoconf automake autotools-dev curl python3 python3-pip libmpc-dev libmpfr-dev libgmp-dev gawk build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev libexpat-dev ninja-build git cmake libglib2.0-dev
 +
 
 +
'''For Fedora/CentOS/RHEL OS'''
 +
 
 +
    sudo yum install autoconf automake python3 libmpc-devel mpfr-devel gmp-devel gawk  bison flex texinfo patchutils gcc gcc-c++ zlib-devel expat-devel
 +
4. Run the configuration script.  By default, it will install the toolchain in <code>/opt/riscv</code>.  Change this parameter to install the toolchain in a different location.
 +
    cd riscv-gnu-toolchain && ./configure --prefix=/opt/riscv
 +
 
 +
5. Install the toolchain
 +
    make linux
 +
 
 +
6. Ensure the directory containing the toolchain is added to the system's PATH.  This is operating system specific.  If the toolchain is not added to the PATH, users will not be able to execute it from any directory.
 +
 
 +
7. If all has gone well, you should now have a gcc cross-compiler from your host's native architecture to RISC-V 64-bit:
 +
 
 +
  riscv64-linux-gnu-gcc
 +
 
 +
=== MIPS Cross-Compiler ===
 
In order to compile Embedded MIPS kernels on a workstation that is not itself
 
In order to compile Embedded MIPS kernels on a workstation that is not itself
 
a MIPS processor, it is necessary to build and install an appropriate
 
a MIPS processor, it is necessary to build and install an appropriate
Line 8: Line 37:
 
ways to accomplish this; for reference, we list the specific versions and
 
ways to accomplish this; for reference, we list the specific versions and
 
steps we used for our installation.
 
steps we used for our installation.
 +
 +
'''NOTE:''' the following tutorial describes the steps for creating a MIPS cross-compiler in a Linux environment. See our other wiki pages for tutorials on building cross-compilers for [[HOWTO:Build XINU on Windows XP|Windows XP]] or [[HOWTO:Build XINU on Mac OS X|Mac OS X]].
  
 
As always, one should be wary of installing unfamilar software as the root
 
As always, one should be wary of installing unfamilar software as the root
 
user of the system.  All of the steps below have been carried out as a
 
user of the system.  All of the steps below have been carried out as a
 
lesser-privileged user with write access to the necessary directories.
 
lesser-privileged user with write access to the necessary directories.
 +
 +
==== Build binutils ====
  
 
First, we downloaded, compiled, and installed the appropriate binary utilities.
 
First, we downloaded, compiled, and installed the appropriate binary utilities.
 
We downloaded [http://www.gnu.org/software/binutils/ binutils] version
 
We downloaded [http://www.gnu.org/software/binutils/ binutils] version
[http://ftp.gnu.org/gnu/binutils/binutils-2.17.tar.gz 2.17], untarred the
+
[http://ftp.gnu.org/gnu/binutils/binutils-2.21.tar.gz 2.21], untarred the
source code, and and ran the following commands:
+
source code, and ran the following commands inside the new directory created by untarring the download:
  
 
   ./configure  --prefix=/usr/local/project/mipsel-dev --target=mipsel
 
   ./configure  --prefix=/usr/local/project/mipsel-dev --target=mipsel
 
   make
 
   make
 
   make install
 
   make install
 +
 +
==== Note about cross-compiler location ====
  
 
We have chosen the path "/usr/local/project/mipsel-dev" to host our cross-compiler
 
We have chosen the path "/usr/local/project/mipsel-dev" to host our cross-compiler
 
installation.  Whatever path is used here must be reflected in the [[XINU]] build
 
installation.  Whatever path is used here must be reflected in the [[XINU]] build
configuration file, "compile/makeVars" when you arrive at that step.
+
configuration file, "compile/platforms/*/platformVars" when you arrive at that step.
 +
 
 +
==== Link include directory ====
  
 
We are not building a true, full-blown UNIX cross-compiler here, and do not need
 
We are not building a true, full-blown UNIX cross-compiler here, and do not need
Line 34: Line 71:
 
   mkdir -p /usr/local/project/mipsel-dev/mipsel/usr
 
   mkdir -p /usr/local/project/mipsel-dev/mipsel/usr
 
   ln -s /usr/include /usr/local/project/mipsel-dev/mipsel/usr/include
 
   ln -s /usr/include /usr/local/project/mipsel-dev/mipsel/usr/include
 +
 +
==== Build GNU C Compiler ====
  
 
Second, we downloaded, patched, compiled and installed the GNU C Compiler.
 
Second, we downloaded, patched, compiled and installed the GNU C Compiler.
We downloaded [http://gcc.gnu.org/ GCC] version 3.4.6.  We applied a
+
We downloaded [http://gcc.gnu.org/ GCC] version 4.6.1.  We added the newly compiled binutils
[http://www.mscs.mu.edu/~brylow/xinu/gcc-3.4.6-fixproto.patch short patch]
 
to correct some kind of obscure fixproto error.  We added the newly compiled binutils
 
 
into the shell path (/usr/local/project/mipsel-dev/bin) for the gcc compilation to find them.
 
into the shell path (/usr/local/project/mipsel-dev/bin) for the gcc compilation to find them.
 
This is also known to work with [http://gcc.gnu.org/ GCC] version 4.1.2 and 4.2.0 unpatched, using
 
This is also known to work with [http://gcc.gnu.org/ GCC] version 4.1.2 and 4.2.0 unpatched, using
Line 47: Line 84:
 
   make
 
   make
 
   make install
 
   make install
 +
 +
==== Rejoice ====
  
 
If all has gone well, you should now have a gcc cross-compiler from your host's native architecture to
 
If all has gone well, you should now have a gcc cross-compiler from your host's native architecture to
Line 53: Line 92:
 
   /usr/local/project/mipsel-dev/bin/mipsel-gcc
 
   /usr/local/project/mipsel-dev/bin/mipsel-gcc
  
= Building the XINU image =
+
Remember the path to this file because later you'll need to double check some building variables to make sure they point to the correct location of your cross-compiler.
 +
 
 +
== Building the XINU Image ==
 +
 
 +
Once you have downloaded and extracted the Xinu tarball, you will see a basic directory structure (depending on the architecture): First, it is a good idea to read up on [[Build System|building the XINU system]].
  
Once you have downloaded and extracted the xinu tarball, you will see a basic directory structure:
+
<pre>AUTHORS device   lib      loader   README  system
  AUTHORS   include/  LICENSE   README  system/ tty/
+
compile  include LICENSE mailbox shell   test</pre>
  compile/ lib/      loader/   shell/  test/   uart/
 
  
 
<tt>AUTHORS</tt> is a brief history of contributors to the XINU operating system in it's varying iterations.
 
<tt>AUTHORS</tt> is a brief history of contributors to the XINU operating system in it's varying iterations.
  
<tt>compile/</tt> contains the Makefile and other necesities for [[Build System|building the XINU system]] once you have a cross-compiler.
+
<tt>compile/</tt> contains the Makefile and other necessities for [[Build System|building the XINU system]] once you have a cross-compiler.
 +
 
 +
<tt>device/</tt> contains the source for all device drivers, including the tty and uart driver.
  
 
<tt>include/</tt> contains all the header files used by XINU.
 
<tt>include/</tt> contains all the header files used by XINU.
Line 69: Line 113:
 
<tt>LICENSE</tt> is the license under which this project falls.
 
<tt>LICENSE</tt> is the license under which this project falls.
  
<tt>loader/</tt> contains assembly files and is where the bootloader will begin execution of O/S code.
+
<tt>loader/</tt> (MIPS only) contains assembly files and is where the bootloader will begin execution of O/S code.
 +
 
 +
<tt>mailbox/</tt> contains the source for the mailbox message-passing implementation.  
  
 
<tt>README</tt> is this document.
 
<tt>README</tt> is this document.
Line 79: Line 125:
 
<tt>test/</tt> contains a number of testcases (which can be run using the shell command testsuite).
 
<tt>test/</tt> contains a number of testcases (which can be run using the shell command testsuite).
  
<tt>tty/</tt> contains the source for the tty driver.
+
----
 +
 
 +
=== MIPS Specific Instructions ===
 +
Next, you'll want to check your <code> mipsVars </code> file in the <code> compile </code> directory. The file should look something like this:
 +
<pre>MIPS_ROOT = /usr/local/project/mipsel-dev/bin
 +
MIPS_PREFIX = mipsel-
  
<tt>uart/</tt> contains the source for the uart driver.
+
COMPILER_ROOT = ${MIPS_ROOT}/${MIPS_PREFIX}
  
----
+
CC      = ${COMPILER_ROOT}gcc
 +
CPP      = ${COMPILER_ROOT}cpp
 +
LD      = ${COMPILER_ROOT}ld
 +
AS      = ${COMPILER_ROOT}as
 +
AR      = ${COMPILER_ROOT}ar
 +
MAKEDEP  = `which makedepend`
 +
 
 +
DOCGEN  = doxygen
 +
 
 +
# DETAIL  = -DDETAIL
 +
 
 +
DEFS    =
 +
INCLUDE  = -I../include
 +
 
 +
#flag for producing GDB debug information
 +
BUGFLAG = -ggdb
 +
 
 +
CFLAGS = -O0 -Wall -Werror -Wstrict-prototypes -Wno-trigraphs            \
 +
            -nostdinc -fno-builtin -fno-strict-aliasing -fno-common \
 +
        -fomit-frame-pointer -fno-pic -ffunction-sections -G 0  \
 +
        -mlong-calls -mno-abicalls -mabi=32 -march=mips32      \
 +
        -Wa,-32 -Wa,-march=mips32 -Wa,-mips32 -Wa,--trap        \
 +
        ${DEBUG} ${INCLUDE} ${DETAIL} ${DEFS} -c
 +
 
 +
 
 +
ASFLAGS  = ${INCLUDE} ${DEBUG} -march=mips32 -mips32
 +
</pre>
  
By this point it is assumed you have built a cross-compiler (from your host computer's architecture to MIPS), have obtained a supported router and have made the necessary modifications to use the serial port. If you have not it is suggested you visit http://mulug.mscs.mu.edu/xinu/ to understand what you need and why.
+
The important thing to note on this file is the <code> MIPS_ROOT </code> variable. It needs to point to the directory containing the cross-compiler. If you followed the commands in the tutorial exactly, then the value of the <code> MIPS_ROOT </code> variable in the code above should be the correct value.
  
Once you have obtained all the required components building the XINU system is a straightforward process. Change into the <tt>compile</tt> directory and (if needed) update the makeVars file to point to your cross-compiler. Once you have done that you can simply execute <tt>make</tt> which should leave you with a <tt>xinu.boot</tt> file in the compile directory.
+
Now you'll want to actually create your boot image. In the <code> compile/ </code> directory execute the following commands: <code>make clean </code> and <code> make</code>. The <code> make </code> command will let you know if you have any compiling errors or warnings. If there are none, then you should have successfully created a XINU boot image located in the file <code> xinu.boot </code> in the <code> compile/ </code> directory. Remember that each time you make changes to source files, to recompile and create a new XINU boot image you have to execute <code> make clean </code> and then <code> make</code>.
  
After creating the <tt>xinu.boot</tt> image you can hook the router's serial port up to your computer and connect using a serial communications program of your choice (the xinu-console tools available from http://www.mscs.mu.edu/~brylow/xinu/ contain a program called tty-connect which is a basic serial communication program). The settings needed are 8 data bits, no parity bit, and 1 stop bit (8N1) with a speed of 115,200 bps.
+
== What to do next? ==
  
Upon connection you can power on the router and immediatly start sending breaks (Control-C) to the device, if your luck holds you will be greated with a CFE prompt. If you are using a DHCP server you can execute <tt>ifconfig eth0 -auto</tt> to obtain an IP, otherwise your computer can have a static IP in the 192.168.1.[2-255] range. On the host computer initiate a tftp put on the <tt>xinu.boot</tt> image and on the router type the command <tt>boot -elf [host ip]:xinu.boot</tt>.  If all has gone correctly the router should now be running a XINU image and you will be greeted with a basic shell (<tt>xsh$ </tt>).
+
Now that you have successfully built a XINU boot image you're ready to use that file to actually [[HOWTO:Deploy_Xinu|boot XINU]] on your device.
  
Within the shell you have some basic commands: exit, gpiostat, help, kill, memstat, led, ps, reset, sleep, uartstat. Each can be described using <tt>[command] --help</tt>.
 
  
For more information check out the Embedded XINU wiki [http://mulug.mscs.mu.edu/xinu/].
+
<hr/>
 +
''This work is supported in part by NSF grant DUE-CCLI-0737476.''

Latest revision as of 00:52, 22 March 2024

The new MIPS port of Embedded XINU has been released. See the Downloads tab for more information.

Cross-Compiler

RISC-V Cross-Compiler and Toolchain

The RISC-V cross-compiler and toolchain can be found [here]. Installing the toolchain installs the cross-compiler, LLVM, QEMU, and GCC all with RISC-V support.

Installing the Toolchain

1. Clone the RISC-V toolchain. Note, this may take a while.

   git clone https://github.com/riscv-collab/riscv-gnu-toolchain --recurse-submodules

2. Install the dependencies for your system

For Ubuntu

   sudo apt-get install autoconf automake autotools-dev curl python3 python3-pip libmpc-dev libmpfr-dev libgmp-dev gawk build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev libexpat-dev ninja-build git cmake libglib2.0-dev

For Fedora/CentOS/RHEL OS

   sudo yum install autoconf automake python3 libmpc-devel mpfr-devel gmp-devel gawk  bison flex texinfo patchutils gcc gcc-c++ zlib-devel expat-devel

4. Run the configuration script. By default, it will install the toolchain in /opt/riscv. Change this parameter to install the toolchain in a different location.

   cd riscv-gnu-toolchain && ./configure --prefix=/opt/riscv

5. Install the toolchain

   make linux

6. Ensure the directory containing the toolchain is added to the system's PATH. This is operating system specific. If the toolchain is not added to the PATH, users will not be able to execute it from any directory.

7. If all has gone well, you should now have a gcc cross-compiler from your host's native architecture to RISC-V 64-bit:

  riscv64-linux-gnu-gcc

MIPS Cross-Compiler

In order to compile Embedded MIPS kernels on a workstation that is not itself a MIPS processor, it is necessary to build and install an appropriate cross compiler. There are many ways to accomplish this; for reference, we list the specific versions and steps we used for our installation.

NOTE: the following tutorial describes the steps for creating a MIPS cross-compiler in a Linux environment. See our other wiki pages for tutorials on building cross-compilers for Windows XP or Mac OS X.

As always, one should be wary of installing unfamilar software as the root user of the system. All of the steps below have been carried out as a lesser-privileged user with write access to the necessary directories.

Build binutils

First, we downloaded, compiled, and installed the appropriate binary utilities. We downloaded binutils version 2.21, untarred the source code, and ran the following commands inside the new directory created by untarring the download:

  ./configure  --prefix=/usr/local/project/mipsel-dev --target=mipsel
  make
  make install

Note about cross-compiler location

We have chosen the path "/usr/local/project/mipsel-dev" to host our cross-compiler installation. Whatever path is used here must be reflected in the XINU build configuration file, "compile/platforms/*/platformVars" when you arrive at that step.

Link include directory

We are not building a true, full-blown UNIX cross-compiler here, and do not need a proper installation of the platform-specific C libraries; XINU has its own small libraries that compile with the kernel. However, the GCC compilation will want to see appropriate library headers, so we cheat here by linking the platform-specific include directory to the host machine's include directory.

  mkdir -p /usr/local/project/mipsel-dev/mipsel/usr
  ln -s /usr/include /usr/local/project/mipsel-dev/mipsel/usr/include

Build GNU C Compiler

Second, we downloaded, patched, compiled and installed the GNU C Compiler. We downloaded GCC version 4.6.1. We added the newly compiled binutils into the shell path (/usr/local/project/mipsel-dev/bin) for the gcc compilation to find them. This is also known to work with GCC version 4.1.2 and 4.2.0 unpatched, using this script to get around installing a bunch of platform-specific UNIX libraries.

  ./configure  --prefix=/usr/local/project/mipsel-dev --target=mipsel --with-sysroot=/usr/local/project/mipsel-dev/mipsel/ --enable-languages=c
  make
  make install

Rejoice

If all has gone well, you should now have a gcc cross-compiler from your host's native architecture to little-endian MIPS:

  /usr/local/project/mipsel-dev/bin/mipsel-gcc

Remember the path to this file because later you'll need to double check some building variables to make sure they point to the correct location of your cross-compiler.

Building the XINU Image

Once you have downloaded and extracted the Xinu tarball, you will see a basic directory structure (depending on the architecture): First, it is a good idea to read up on building the XINU system.

AUTHORS  device   lib      loader   README  system
compile  include  LICENSE  mailbox  shell   test

AUTHORS is a brief history of contributors to the XINU operating system in it's varying iterations.

compile/ contains the Makefile and other necessities for building the XINU system once you have a cross-compiler.

device/ contains the source for all device drivers, including the tty and uart driver.

include/ contains all the header files used by XINU.

lib/ contains a folder (libxc/) with a Makefile and source for the library, as well as a binary blob which contains the pre-compiled library.

LICENSE is the license under which this project falls.

loader/ (MIPS only) contains assembly files and is where the bootloader will begin execution of O/S code.

mailbox/ contains the source for the mailbox message-passing implementation.

README is this document.

shell/ contains the source for all shell related functions.

system/ contains the source for all system functions such as the nulluser process (initialize.c) as well as code to set up a C environment (startup.S).

test/ contains a number of testcases (which can be run using the shell command testsuite).


MIPS Specific Instructions

Next, you'll want to check your mipsVars file in the compile directory. The file should look something like this:

MIPS_ROOT = /usr/local/project/mipsel-dev/bin
MIPS_PREFIX = mipsel-

COMPILER_ROOT = ${MIPS_ROOT}/${MIPS_PREFIX}

CC       = ${COMPILER_ROOT}gcc
CPP      = ${COMPILER_ROOT}cpp
LD       = ${COMPILER_ROOT}ld
AS       = ${COMPILER_ROOT}as
AR       = ${COMPILER_ROOT}ar
MAKEDEP  = `which makedepend`

DOCGEN   = doxygen

# DETAIL   = -DDETAIL

DEFS     =
INCLUDE  = -I../include

#flag for producing GDB debug information
BUGFLAG = -ggdb

CFLAGS = -O0 -Wall -Werror -Wstrict-prototypes -Wno-trigraphs            \
             -nostdinc -fno-builtin -fno-strict-aliasing -fno-common \
         -fomit-frame-pointer -fno-pic -ffunction-sections -G 0  \
         -mlong-calls -mno-abicalls -mabi=32 -march=mips32       \
         -Wa,-32 -Wa,-march=mips32 -Wa,-mips32 -Wa,--trap        \
         ${DEBUG} ${INCLUDE} ${DETAIL} ${DEFS} -c


ASFLAGS  = ${INCLUDE} ${DEBUG} -march=mips32 -mips32

The important thing to note on this file is the MIPS_ROOT variable. It needs to point to the directory containing the cross-compiler. If you followed the commands in the tutorial exactly, then the value of the MIPS_ROOT variable in the code above should be the correct value.

Now you'll want to actually create your boot image. In the compile/ directory execute the following commands: make clean and make. The make command will let you know if you have any compiling errors or warnings. If there are none, then you should have successfully created a XINU boot image located in the file xinu.boot in the compile/ directory. Remember that each time you make changes to source files, to recompile and create a new XINU boot image you have to execute make clean and then make.

What to do next?

Now that you have successfully built a XINU boot image you're ready to use that file to actually boot XINU on your device.



This work is supported in part by NSF grant DUE-CCLI-0737476.