1 | RTEMS LibBSD Waf |
---|
2 | ~~~~~~~~~~~~~~~~ |
---|
3 | |
---|
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. |
---|
9 | |
---|
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. |
---|
14 | |
---|
15 | Waf Setup |
---|
16 | ~~~~~~~~~ |
---|
17 | |
---|
18 | You can find the Waf project at: |
---|
19 | |
---|
20 | https://waf.io/ |
---|
21 | |
---|
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 | |
---|
44 | We will build an Xilinx Zynq QEMU BSP using the name |
---|
45 | 'arm/xilinx_zynq_a9_qemu'. |
---|
46 | |
---|
47 | Steps |
---|
48 | ----- |
---|
49 | |
---|
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" |
---|
64 | mkdir b-xilinx_zynq_a9_qemu |
---|
65 | cd b-xilinx_zynq_a9_qemu |
---|
66 | PATH="$sandbox/rtems-4.12/bin:$PATH" "$sandbox/rtems/configure" \ |
---|
67 | --target=arm-rtems4.12 --prefix="$sandbox/rtems-4.12" \ |
---|
68 | --disable-networking --enable-rtemsbsp=xilinx_zynq_a9_qemu |
---|
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" \ |
---|
76 | --rtems-bsps=arm/xilinx_zynq_a9_qemu |
---|
77 | waf |
---|
78 | waf install |
---|
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 |
---|
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" |
---|
92 | $ git clone git://git.rtems.org/rtems-source-builder.git |
---|
93 | $ git clone git://git.rtems.org/rtems.git |
---|
94 | $ git clone git://git.rtems.org/rtems-libbsd.git |
---|
95 | |
---|
96 | 2. Build and install the tools. In this example the path is |
---|
97 | $sandbox/rtems-4.12: |
---|
98 | |
---|
99 | $ cd "$sandbox" |
---|
100 | $ cd rtems-source-builder/rtems |
---|
101 | $ ../source-builder/sb-set-builder --prefix="$sandbox/rtems-4.12" 4.12/rtems-arm |
---|
102 | |
---|
103 | 3. Bootstrap the RTEMS sources: |
---|
104 | |
---|
105 | $ cd "$sandbox" |
---|
106 | $ cd rtems |
---|
107 | $ PATH="$sandbox/rtems-4.12/bin:$PATH" ./bootstrap |
---|
108 | |
---|
109 | 5. Build and install the RTEMS Board Support Packages (BSP) you want to use. In |
---|
110 | this example the path is /opt/rtems/4.12/bsps: |
---|
111 | |
---|
112 | $ cd "$sandbox" |
---|
113 | $ mkdir b-xilinx_zynq_a9_qemu |
---|
114 | $ cd b-xilinx_zynq_a9_qemu |
---|
115 | $ PATH="$sandbox/rtems-4.12/bin:$PATH" "$sandbox/rtems/configure" \ |
---|
116 | --target=arm-rtems4.12 --prefix="$sandbox/rtems-4.12" \ |
---|
117 | --disable-networking --enable-rtemsbsp=xilinx_zynq_a9_qemu |
---|
118 | $ PATH="$sandbox/rtems-4.12/bin:$PATH" make |
---|
119 | $ PATH="$sandbox/rtems-4.12/bin:$PATH" make install |
---|
120 | |
---|
121 | 6. Populate the rtems_waf git submodule. Note, make sure you specify |
---|
122 | 'rtems_waf' or the FreeBSD kernel source will be cloned: |
---|
123 | |
---|
124 | $ cd "$sandbox" |
---|
125 | $ cd rtems-libbsd |
---|
126 | $ git submodule init |
---|
127 | $ git submodule update rtems_waf |
---|
128 | |
---|
129 | 7. Run Waf's configure with your specific settings. In this case the path to |
---|
130 | the tools and RTEMS are provided on the command line and so do not need to |
---|
131 | be in your path or environment [1]. You can use |
---|
132 | '--rtems-archs=arm,sparc,i386' or |
---|
133 | '--rtems-bsps=arm/xilinx_zynq_a9_qemu,sparc/sis,i386/pc586' to build for |
---|
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: |
---|
136 | |
---|
137 | $ cd "$sandbox" |
---|
138 | $ cd rtems-libbsd |
---|
139 | $ waf configure --prefix="$sandbox/rtems-4.12" \ |
---|
140 | --rtems-bsps=arm/xilinx_zynq_a9_qemu |
---|
141 | |
---|
142 | 8. Build and install. The LibBSD package will be installed into the prefix |
---|
143 | provided to configure: |
---|
144 | |
---|
145 | $ cd "$sandbox" |
---|
146 | $ cd rtems-libbsd |
---|
147 | $ waf |
---|
148 | $ waf install |
---|
149 | |
---|
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 | |
---|
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. |
---|
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 |
---|
192 | $ cd .. |
---|
193 | $ git commit -m "Update rtems_waf" rtems_waf |
---|
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. |
---|