[b14fd1f] | 1 | RTEMS LibBSD Waf |
---|
| 2 | ~~~~~~~~~~~~~~~~ |
---|
| 3 | |
---|
[11ec988] | 4 | Welcome to building LibBSD for RTEMS using Waf. This package is a library |
---|
| 5 | containing various parts of the FreeBSD kernel ported to RTEMS. The library |
---|
| 6 | replaces the networking port of FreeBSD in the RTEMS kernel sources. This |
---|
| 7 | package is designed to be updated from the FreeBSD kernel sources and contains |
---|
| 8 | more than just the networking code. |
---|
[b14fd1f] | 9 | |
---|
[11ec988] | 10 | To build this package you need a current RTEMS tool set for your architecture, |
---|
| 11 | and a recent RTEMS kernel for your BSP configured with networking disabled |
---|
| 12 | built and installed. If you already have this you can skip to step 3 of the |
---|
| 13 | build procedure. |
---|
[b14fd1f] | 14 | |
---|
[11ec988] | 15 | Waf Setup |
---|
| 16 | ~~~~~~~~~ |
---|
[b14fd1f] | 17 | |
---|
[11ec988] | 18 | You can find the Waf project at: |
---|
[b14fd1f] | 19 | |
---|
[11ec988] | 20 | https://waf.io/ |
---|
[b14fd1f] | 21 | |
---|
[11ec988] | 22 | Waf is not intended to be installed by distribution packages so we recommend |
---|
| 23 | you download a recent waf version and install it in your home directory. |
---|
| 24 | |
---|
| 25 | Waf is a Python program so you will also need to have a current Python version |
---|
| 26 | installed and in your path. |
---|
| 27 | |
---|
| 28 | Download the latest signed executable file version to $HOME/bin and symlink it |
---|
| 29 | to waf. Add the directory $HOME/bin to your path if it is not already in your |
---|
| 30 | default path. |
---|
| 31 | |
---|
| 32 | Building and Installing LibBSD |
---|
| 33 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
| 34 | |
---|
| 35 | The following instructions show you how to build and install RTEMS Tools and |
---|
| 36 | RTEMS kernel for your BSP in separate paths. Using separate paths for the tools |
---|
| 37 | and BSPs lets you manage what you have installed. If you are happy with a |
---|
| 38 | single path you can use the same path in each stage. |
---|
| 39 | |
---|
| 40 | The waf build support for RTEMS requires you provide your BSP name as an |
---|
| 41 | architecture and BSP pair. You must provide both or waf will generate an error |
---|
| 42 | message during the configure phase. |
---|
| 43 | |
---|
[2c4840f] | 44 | We will build an Xilinx Zynq QEMU BSP using the name |
---|
| 45 | 'arm/xilinx_zynq_a9_qemu'. |
---|
[b14fd1f] | 46 | |
---|
| 47 | Steps |
---|
| 48 | ----- |
---|
| 49 | |
---|
[cf72971] | 50 | ------------------------------------------------------------------------------- |
---|
| 51 | sandbox="$PWD/sandbox" |
---|
| 52 | mkdir sandbox |
---|
| 53 | cd "$sandbox" |
---|
| 54 | git clone git://git.rtems.org/rtems-source-builder.git |
---|
| 55 | git clone git://git.rtems.org/rtems.git |
---|
| 56 | git clone git://git.rtems.org/rtems-libbsd.git |
---|
| 57 | cd "$sandbox" |
---|
| 58 | cd rtems-source-builder/rtems |
---|
| 59 | ../source-builder/sb-set-builder --prefix="$sandbox/rtems-4.12" 4.12/rtems-arm |
---|
| 60 | cd "$sandbox" |
---|
| 61 | cd rtems |
---|
| 62 | PATH="$sandbox/rtems-4.12/bin:$PATH" ./bootstrap |
---|
| 63 | cd "$sandbox" |
---|
[2c4840f] | 64 | mkdir b-xilinx_zynq_a9_qemu |
---|
| 65 | cd b-xilinx_zynq_a9_qemu |
---|
[cf72971] | 66 | PATH="$sandbox/rtems-4.12/bin:$PATH" "$sandbox/rtems/configure" \ |
---|
| 67 | --target=arm-rtems4.12 --prefix="$sandbox/rtems-4.12" \ |
---|
[2c4840f] | 68 | --disable-networking --enable-rtemsbsp=xilinx_zynq_a9_qemu |
---|
[cf72971] | 69 | PATH="$sandbox/rtems-4.12/bin:$PATH" make |
---|
| 70 | PATH="$sandbox/rtems-4.12/bin:$PATH" make install |
---|
| 71 | cd "$sandbox" |
---|
| 72 | cd rtems-libbsd |
---|
| 73 | git submodule init |
---|
| 74 | git submodule update rtems_waf |
---|
| 75 | waf configure --prefix="$sandbox/rtems-4.12" \ |
---|
[2c4840f] | 76 | --rtems-bsps=arm/xilinx_zynq_a9_qemu |
---|
[cf72971] | 77 | waf |
---|
| 78 | waf install |
---|
[2c4840f] | 79 | qemu-system-arm -no-reboot -serial null -serial mon:stdio -net none \ |
---|
| 80 | -nographic -M xilinx-zynq-a9 -m 256M \ |
---|
| 81 | -kernel build/arm-rtems4.12-xilinx_zynq_a9_qemu/selectpollkqueue01.exe |
---|
[cf72971] | 82 | ------------------------------------------------------------------------------- |
---|
| 83 | |
---|
| 84 | 1. Create a sandbox directory: |
---|
| 85 | |
---|
| 86 | $ sandbox="$PWD/sandbox" |
---|
| 87 | $ mkdir sandbox |
---|
| 88 | |
---|
| 89 | 1. Clone the repositories: |
---|
| 90 | |
---|
| 91 | $ cd "$sandbox" |
---|
[b39854a] | 92 | $ git clone git://git.rtems.org/rtems-source-builder.git |
---|
[cf72971] | 93 | $ git clone git://git.rtems.org/rtems.git |
---|
| 94 | $ git clone git://git.rtems.org/rtems-libbsd.git |
---|
[b39854a] | 95 | |
---|
| 96 | 2. Build and install the tools. In this example the path is |
---|
[cf72971] | 97 | $sandbox/rtems-4.12: |
---|
[b14fd1f] | 98 | |
---|
[cf72971] | 99 | $ cd "$sandbox" |
---|
[b14fd1f] | 100 | $ cd rtems-source-builder/rtems |
---|
[cf72971] | 101 | $ ../source-builder/sb-set-builder --prefix="$sandbox/rtems-4.12" 4.12/rtems-arm |
---|
[b39854a] | 102 | |
---|
[cf72971] | 103 | 3. Bootstrap the RTEMS sources: |
---|
[b39854a] | 104 | |
---|
[cf72971] | 105 | $ cd "$sandbox" |
---|
| 106 | $ cd rtems |
---|
| 107 | $ PATH="$sandbox/rtems-4.12/bin:$PATH" ./bootstrap |
---|
[b39854a] | 108 | |
---|
| 109 | 5. Build and install the RTEMS Board Support Packages (BSP) you want to use. In |
---|
[ff6534b] | 110 | this example the path is /opt/rtems/4.12/bsps: |
---|
[b14fd1f] | 111 | |
---|
[cf72971] | 112 | $ cd "$sandbox" |
---|
[2c4840f] | 113 | $ mkdir b-xilinx_zynq_a9_qemu |
---|
| 114 | $ cd b-xilinx_zynq_a9_qemu |
---|
[cf72971] | 115 | $ PATH="$sandbox/rtems-4.12/bin:$PATH" "$sandbox/rtems/configure" \ |
---|
| 116 | --target=arm-rtems4.12 --prefix="$sandbox/rtems-4.12" \ |
---|
[2c4840f] | 117 | --disable-networking --enable-rtemsbsp=xilinx_zynq_a9_qemu |
---|
[cf72971] | 118 | $ PATH="$sandbox/rtems-4.12/bin:$PATH" make |
---|
| 119 | $ PATH="$sandbox/rtems-4.12/bin:$PATH" make install |
---|
[b14fd1f] | 120 | |
---|
[cf72971] | 121 | 6. Populate the rtems_waf git submodule. Note, make sure you specify |
---|
| 122 | 'rtems_waf' or the FreeBSD kernel source will be cloned: |
---|
[aca5496] | 123 | |
---|
[cf72971] | 124 | $ cd "$sandbox" |
---|
| 125 | $ cd rtems-libbsd |
---|
| 126 | $ git submodule init |
---|
| 127 | $ git submodule update rtems_waf |
---|
[b14fd1f] | 128 | |
---|
[b39854a] | 129 | 7. Run Waf's configure with your specific settings. In this case the path to |
---|
[11ec988] | 130 | the tools and RTEMS are provided on the command line and so do not need to |
---|
[cf72971] | 131 | be in your path or environment [1]. You can use |
---|
| 132 | '--rtems-archs=arm,sparc,i386' or |
---|
[2c4840f] | 133 | '--rtems-bsps=arm/xilinx_zynq_a9_qemu,sparc/sis,i386/pc586' to build for |
---|
[cf72971] | 134 | more than BSP at a time. Note, you must provide the architecture and BSP as |
---|
| 135 | a pair. Providing just the BSP name will fail: |
---|
[11ec988] | 136 | |
---|
[cf72971] | 137 | $ cd "$sandbox" |
---|
| 138 | $ cd rtems-libbsd |
---|
| 139 | $ waf configure --prefix="$sandbox/rtems-4.12" \ |
---|
[2c4840f] | 140 | --rtems-bsps=arm/xilinx_zynq_a9_qemu |
---|
[b14fd1f] | 141 | |
---|
[cf72971] | 142 | 8. Build and install. The LibBSD package will be installed into the prefix |
---|
| 143 | provided to configure: |
---|
[11ec988] | 144 | |
---|
[cf72971] | 145 | $ cd "$sandbox" |
---|
| 146 | $ cd rtems-libbsd |
---|
[b14fd1f] | 147 | $ waf |
---|
| 148 | $ waf install |
---|
| 149 | |
---|
[2c4840f] | 150 | 9. Run the tests on QEMU, for example: |
---|
| 151 | |
---|
| 152 | $ qemu-system-arm -no-reboot -serial null -serial mon:stdio -net none \ |
---|
| 153 | $ -nographic -M xilinx-zynq-a9 -m 256M \ |
---|
| 154 | $ -kernel build/arm-rtems4.12-xilinx_zynq_a9_qemu/selectpollkqueue01.exe |
---|
| 155 | |
---|
[b14fd1f] | 156 | [1] It is good practice to keep your environment as empty as possible. Setting |
---|
| 157 | paths to tools or specific values to configure or control a build is |
---|
| 158 | dangerous because settings can leak between different builds and change |
---|
| 159 | what you expect a build to do. The waf tool used here lets you specify on |
---|
| 160 | the command line the tools and RTEMS paths and this is embedded in waf's |
---|
| 161 | configuration information. If you have a few source trees working at any |
---|
| 162 | one time with different tool sets or configurations you can easly move |
---|
| 163 | between them safe in the knowledge that one build will not infect another. |
---|
[97c5024a] | 164 | |
---|
| 165 | Updating RTEMS Waf Support |
---|
| 166 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
| 167 | |
---|
| 168 | If you have a working libbsd repository and new changes to the `rtems_waf` |
---|
| 169 | submodule has been made, you will need update. A `git status` will indicate |
---|
| 170 | there are new commits with: |
---|
| 171 | |
---|
| 172 | $ git status |
---|
| 173 | [ snip output ] |
---|
| 174 | modified: rtems_waf (new commits) |
---|
| 175 | [ snip output ] |
---|
| 176 | |
---|
| 177 | To update: |
---|
| 178 | |
---|
| 179 | $ git submodule update rtems_waf |
---|
| 180 | |
---|
| 181 | Please make sure you use the exact command or you might find you are cloning |
---|
| 182 | the whole of the FreeBSD source tree. If that happens simply git ^C and try |
---|
| 183 | again. |
---|
| 184 | |
---|
| 185 | The following is for developers only who need to move libbsd to a newer |
---|
| 186 | versions: |
---|
| 187 | |
---|
| 188 | $ git submodule update rtems_waf |
---|
| 189 | $ cd rtems_waf |
---|
| 190 | $ git checkout master |
---|
| 191 | $ git pull |
---|
[68bf405] | 192 | $ cd .. |
---|
[97c5024a] | 193 | $ git commit -m "Update rtems_waf" rtems_waf |
---|
[e1e10cd] | 194 | |
---|
| 195 | FreeBSD Developer Support |
---|
| 196 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
| 197 | |
---|
| 198 | The --freebsd-option provides a tool you can set special kernel options. This |
---|
| 199 | is a developer tool and should only be used if you are familiar with the |
---|
| 200 | internals of the FreeBSD kernel and what these options do. |
---|
| 201 | |
---|
| 202 | The options are listed in: |
---|
| 203 | |
---|
| 204 | https://github.com/freebsd/freebsd/blob/master/sys/conf/NOTES |
---|
| 205 | |
---|
| 206 | An example to turn on a verbose kernel boot, verbose sysinit and bus debugging |
---|
| 207 | configure with: |
---|
| 208 | |
---|
| 209 | --freebsd-options=bootverbose,verbose_sysinit,bus_debug |
---|
| 210 | |
---|
| 211 | The LibBSD waf support splits the options and converts them to uppercase and |
---|
| 212 | adds them -D options on the compiler command line. |
---|