1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 2018 embedded brains GmbH |
---|
4 | |
---|
5 | i386 |
---|
6 | **** |
---|
7 | |
---|
8 | pc386 |
---|
9 | ===== |
---|
10 | |
---|
11 | This BSP supports a standard Intel/AMD PC on i386 and up CPUs. If run |
---|
12 | on a Pentium or above, the TSC register is used for timing calibration |
---|
13 | purposes rather than relying entirely on the i8254. |
---|
14 | Partial support is implemented for more modern PCs which do not have a |
---|
15 | complete complement of legacy peripherals. |
---|
16 | |
---|
17 | The BSP is able to utilize up to 3 GB of available RAM and up to 16 |
---|
18 | CPUs. Hyper-threading is supported, but may not be detected by the |
---|
19 | BSP successfully. |
---|
20 | |
---|
21 | .. note:: BSP capability to detect target hardware SMP details is |
---|
22 | limited due to fact the SMP support is implemented based on |
---|
23 | Intel Multi-Processor Specification (MPS). Final version of |
---|
24 | the specification is version 1.4 which was released on July |
---|
25 | 1, 1995. On most newer machines the MPS functionality was |
---|
26 | more or less supplanted by more modern ACPI (Advanced |
---|
27 | Configuration and Power Interface). Still, on some machine |
---|
28 | SMP support may be fragile at least at the platform |
---|
29 | detection and initialization state depending on the target |
---|
30 | BIOS/ACPI/MPS compatibility implementation. |
---|
31 | |
---|
32 | There are several BSP variants provided which differ only in the target CPU |
---|
33 | optimization. The most general is `pc386` which is tuned for i386. The `pc486` |
---|
34 | variant is tuned for i486, `pc585` is tuned for Pentium, `pc586-sse` is tuned |
---|
35 | for Pentium processor supporting SSE instructions. Finally `pc686` is tuned |
---|
36 | for Pentium Pro processor, but generating only instructions for Pentium |
---|
37 | and `pcp4` is tuned and generating instructions for Pentium4 processor |
---|
38 | including SSE3 instructions. |
---|
39 | |
---|
40 | |
---|
41 | Build Configuration Options |
---|
42 | --------------------------- |
---|
43 | |
---|
44 | ``BSP_PRESS_KEY_FOR_RESET`` |
---|
45 | If defined to a non-zero value, then print a message and wait until |
---|
46 | any key is pressed before resetting board when application |
---|
47 | terminates (disabled by default). |
---|
48 | |
---|
49 | ``BSP_RESET_BOARD_AT_EXIT`` |
---|
50 | If defined to a non-zero value, then reset the board when the |
---|
51 | application terminates (enabled by default). |
---|
52 | |
---|
53 | ``BSP_PRINT_EXCEPTION_CONTEXT`` |
---|
54 | If defined to a non-zero value, then print the exception context |
---|
55 | when an unexpected exception occurs (enabled by default). |
---|
56 | |
---|
57 | ``BSP_VERBOSE_FATAL_EXTENSION`` |
---|
58 | If defined to a non-zero value, then print more information in case |
---|
59 | of a fatal error (enabled by default). |
---|
60 | |
---|
61 | ``BSP_ENABLE_VGA`` |
---|
62 | Enables VGA console driver (enabled by default). |
---|
63 | |
---|
64 | ``BSP_ENABLE_COM1_COM4`` |
---|
65 | Enables support of COM1 thorough COM4 (enabled by default). |
---|
66 | |
---|
67 | ``USE_COM1_AS_CONSOLE`` |
---|
68 | Enforces usage of COM1 as a console device (disabled by default). |
---|
69 | |
---|
70 | ``BSP_ENABLE_IDE`` |
---|
71 | Enables legacy IDE driver (enabled by default). |
---|
72 | |
---|
73 | ``IDE_USE_PRIMARY_INTERFACE`` |
---|
74 | Allows RTEMS to use storage drive(s) connected to the primary IDE |
---|
75 | interface. Disable if (i) the target hardware does not have primary |
---|
76 | IDE interface or (ii) it does not have any drive attached to the |
---|
77 | primary IDE interface or (iii) there is no need to use drive(s) |
---|
78 | attached to the primary IDE interface at all (enabled by default). |
---|
79 | |
---|
80 | ``IDE_USE_SECONDARY_INTERFACE`` |
---|
81 | Allows RTEMS to use storage drive(s) connected to the secondary IDE |
---|
82 | interface. Enable if (i) the target hardware does have secondary IDE |
---|
83 | interface and (ii) there is at least one drive attached to the |
---|
84 | secondary IDE interface and (iii) there is a need to use drive(s) |
---|
85 | attached to the secondary IDE interface (disabled by default). |
---|
86 | |
---|
87 | ``BSP_VIDEO_80x50`` |
---|
88 | Sets the VGA display to 80x50 character mode (disabled by default). |
---|
89 | |
---|
90 | ``CLOCK_DRIVER_USE_TSC`` |
---|
91 | Enforces clock driver to use TSC register available on Pentium and |
---|
92 | higher class CPUs. If disabled and ``CLOCK_DRIVER_USE_8243`` is |
---|
93 | disabled too, then BSP will choose clock driver mechanism itself |
---|
94 | during the runtime (disabled by default). |
---|
95 | |
---|
96 | ``CLOCK_DRIVER_USE_8254`` |
---|
97 | Enforces clock driver to use 8254 chip. If disabled and |
---|
98 | ``CLOCK_DRIVER_USE_TSC`` is disabled too, then BSP will choose clock |
---|
99 | driver mechanism itself during the runtime (disabled by default). |
---|
100 | |
---|
101 | ``NUM_APP_DRV_GDT_DESCRIPTORS`` |
---|
102 | Defines how many descriptors in GDT may be allocated for the |
---|
103 | application or driver usage. |
---|
104 | |
---|
105 | ``USE_CIRRUS_GD5446`` |
---|
106 | Enables usage of Cirrus GD5446 graphic card for RTEMS frame-buffer |
---|
107 | (disabled by default). |
---|
108 | |
---|
109 | ``USE_VGA`` |
---|
110 | Enables usage of generic VGA graphic card for RTEMS frame-buffer |
---|
111 | (disabled by default). |
---|
112 | |
---|
113 | ``USE_VBE_RM`` |
---|
114 | Enables usage of graphic card implementing VESA BIOS Extensions for |
---|
115 | RTEMS frame-buffer (enabled by default). |
---|
116 | |
---|
117 | ``BSP_GDB_STUB`` |
---|
118 | Enables GDB support for debugging over serial port (enabled by |
---|
119 | default). |
---|
120 | |
---|
121 | Runtime Options |
---|
122 | --------------- |
---|
123 | The BSP supports several runtime options. They may be used by either setting |
---|
124 | during boot by using target hardware bootloader or by using Qemu's |
---|
125 | ``-append`` command-line parameter in case BSP application is run |
---|
126 | inside the Qemu emulator. |
---|
127 | |
---|
128 | .. option:: --console=<dev> |
---|
129 | |
---|
130 | specifies console |
---|
131 | device. E.g. ``--console=/dev/com1``. COM device name may |
---|
132 | also be followed by a baud rate like ``--console=/dev/com2,19200`` |
---|
133 | |
---|
134 | The pc386 BSP family uses 9600 as a default baud rate |
---|
135 | for console over UART (/dev/comX) with 8 data bits, no parity and 1 stop bit. |
---|
136 | |
---|
137 | .. option:: --printk=<dev> |
---|
138 | |
---|
139 | specifies target device for printk/getk |
---|
140 | calls. E.g. ``--printk=/dev/vgacons`` |
---|
141 | |
---|
142 | If the specified console device is not present then suitable fallback |
---|
143 | device is selected based on the device order specified in `Console Drivers`. |
---|
144 | |
---|
145 | .. option:: --video=<mode> |
---|
146 | |
---|
147 | specifies required video mode. The options applies only to |
---|
148 | the systems supporting VESA BIOS Extensions. Choices are |
---|
149 | ``auto`` which selects graphic mode automatically or |
---|
150 | ``none``/``off`` which disables initialization of the |
---|
151 | graphic driver or direct specification of resolution |
---|
152 | and/or color depth by |
---|
153 | ``<resX>x<resY>[-<bpp>]``. E.g. ``--video=none`` disables |
---|
154 | graphic driver. Using ``--video=1280x1024`` sets video |
---|
155 | mode to 1280x1024 pixels mode while ``--video=800x600-32`` |
---|
156 | sets video mode to 800x600 pixels with 32bit color depth. |
---|
157 | |
---|
158 | .. option:: --disable-com1-com4 |
---|
159 | |
---|
160 | disables usage of COM1 thorough COM4. |
---|
161 | |
---|
162 | .. option:: --gdb=<dev> |
---|
163 | |
---|
164 | specifies UART device for communication between BSP's |
---|
165 | GDB stub and GDB running on a host system. Option accepts device |
---|
166 | and baud rate like the ``--console`` option above. |
---|
167 | E.g. ``--gdb=/dev/com2,115200`` instructs BSP to use COM2 device |
---|
168 | for GDB stub/host communication with the speed of 115200 bauds. |
---|
169 | |
---|
170 | The default GDB stub/host is similar to console over UART, i.e., |
---|
171 | 9600 baud rate, 8 data bits, no parity and 1 stop bit. |
---|
172 | |
---|
173 | .. option:: --gdb-break |
---|
174 | |
---|
175 | halts BSP execution at a break point in the BSP initialization code |
---|
176 | and waits for GDB connection. |
---|
177 | |
---|
178 | .. option:: --gdb-remote-debug |
---|
179 | |
---|
180 | outputs the GDB remote protocol data to printk. |
---|
181 | |
---|
182 | Testing with Qemu |
---|
183 | ----------------- |
---|
184 | |
---|
185 | To test with Qemu, we need to: |
---|
186 | |
---|
187 | - Build / install Qemu (most distributions should have it available on the |
---|
188 | package manager). |
---|
189 | |
---|
190 | Booting RTEMS in Qemu |
---|
191 | ^^^^^^^^^^^^^^^^^^^^^ |
---|
192 | |
---|
193 | .. code-block:: none |
---|
194 | |
---|
195 | $ qemu-system-i386 -m 128 -no-reboot -append \ |
---|
196 | "--video=off --console=/dev/com1" -nographic -kernel ./hello.exe |
---|
197 | |
---|
198 | This command boots ``hello.exe`` application located in current |
---|
199 | directory and sets Qemu to provide 128MB RAM and to switch both Qemu's |
---|
200 | and BSP's video off. |
---|
201 | |
---|
202 | Booting RTEMS in KVM accelerated Qemu |
---|
203 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
204 | When the Qemu host hardware and OS support KVM, it is possible to use it |
---|
205 | to accelerate BSP run by using ``-machine type=q35,accel=kvm`` Qemu option. |
---|
206 | Depending on the Qemu host configuration it may or may not require |
---|
207 | administrator privileges to run the command. |
---|
208 | |
---|
209 | .. code-block:: none |
---|
210 | |
---|
211 | $ sudo qemu-system-i386 -machine type=q35,accel=kvm -m 128 -no-reboot \ |
---|
212 | -append "--video=off --console=/dev/com1" -nographic -kernel \ |
---|
213 | ./dhrystone.exe |
---|
214 | |
---|
215 | This command boots ``dhrystone.exe`` application and sets Qemu to use |
---|
216 | KVM acceleration. |
---|
217 | |
---|
218 | |
---|
219 | Running on a PC hardware |
---|
220 | ---------------------- |
---|
221 | |
---|
222 | There are several ways how to start RTEMS BSP application on the real |
---|
223 | PC hardware. |
---|
224 | |
---|
225 | Booting with GRUB boot-loader |
---|
226 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
227 | |
---|
228 | In case the target machine does already have Linux with GRUB boot |
---|
229 | loader installed, then the most easy way to load and boot RTEMS is |
---|
230 | to use GRUB. This may be done in following steps: |
---|
231 | |
---|
232 | (i) prepare RTEMS binary and save it either to Linux |
---|
233 | partition/directory accessible from GRUB or to an USB stick. |
---|
234 | |
---|
235 | (ii) boot machine to GRUB menu. |
---|
236 | |
---|
237 | .. note:: Some Linux installations hide GRUB menu by default and |
---|
238 | quickly continues with booting default Linux option. If this |
---|
239 | is the case, then during the boot hold down 'Shift' key to |
---|
240 | un-hide the menu. |
---|
241 | |
---|
242 | (iii) press ``c`` key to get into the GRUB's command-line mode. |
---|
243 | |
---|
244 | (iv) use ``ls`` command to observe drives and partitions on them. If |
---|
245 | unsure, use 'ls' command with drive/partition description to show |
---|
246 | the target file system content. E.g. ``ls (hd1,msdos1)/`` will list |
---|
247 | files on the second drive, first partition which is formatted |
---|
248 | using fat/vfat file-system. |
---|
249 | |
---|
250 | .. note:: Use `ls (hdX, partY)` without a slash at the end to show |
---|
251 | information about the partition. |
---|
252 | |
---|
253 | (v) use ``multiboot`` command to load the RTEMS application binary for |
---|
254 | boot. E.g. ``multiboot (hd1,msdos2)/rtems/ticker.exe`` will load |
---|
255 | ticker.exe from the second drive, second partition with fat/vfat |
---|
256 | file-system and its rtems directory. |
---|
257 | |
---|
258 | (vi) use ``boot`` command to boot loaded binary. |
---|
259 | |
---|
260 | .. note:: Advantage of using GRUB for booting RTEMS is the GRUB's |
---|
261 | support for both classical BIOS and UEFI boot. This way |
---|
262 | RTEMS may be booted even on UEFI only systems. |
---|
263 | |
---|
264 | Booting with PXE/iPXE |
---|
265 | ^^^^^^^^^^^^^^^^ |
---|
266 | PXE booting is more complex than GRUB based booting and hence requires |
---|
267 | more infrastructure configuration. The booting may be done in two |
---|
268 | possible ways: |
---|
269 | |
---|
270 | (i) using iPXE booted from an USB stick or a hard drive |
---|
271 | |
---|
272 | It may be done using following steps: |
---|
273 | |
---|
274 | - Download iPXE ISO image from http://boot.ipxe.org/ipxe.iso |
---|
275 | - Either record it to CD/DVD or copy it to an USB stick |
---|
276 | - boot from the medium above on the target hardware |
---|
277 | - wait for ``Press Ctrl-B for the iPXE command line...`` prompt and once |
---|
278 | it appears press ``Ctrl-B`` key. |
---|
279 | - use 'dhcp' command to configure network interface card |
---|
280 | - use 'boot' command to boot RTEMS application from specified tftp |
---|
281 | server. E.g. ``boot tftp://10.0.0.5/hello.exe`` will boot hello.exe |
---|
282 | application from the tftp server on host with 10.0.0.5 IP address. |
---|
283 | |
---|
284 | Whole interaction may look as: |
---|
285 | |
---|
286 | .. code-block:: none |
---|
287 | |
---|
288 | Press Ctrl-B for the iPXE command line... |
---|
289 | iPXE> dhcp |
---|
290 | Configuring (net0 <mac address>)..... ok |
---|
291 | iPXE> boot tftp://10.0.0.5/hello.exe |
---|
292 | |
---|
293 | |
---|
294 | (ii) using built in network card's PXE BIOS to boot into iPXE |
---|
295 | |
---|
296 | This way is more complex and requires network infrastructure |
---|
297 | configuration changes which description is out of the scope of this |
---|
298 | documentation. Generic steps how to achieve this are: |
---|
299 | |
---|
300 | - use target hardware BIOS/SETUP to enable PXE booting on the board |
---|
301 | - setup network router to announce tftp server and file on it as a |
---|
302 | part of the router's BOOTP/DHCP protocol reply. You should use |
---|
303 | http://boot.ipxe.org/undionly.kpxe as a payload for non-UEFI based |
---|
304 | booting. Put that file into tftp server served/root directory. |
---|
305 | - reboot target hardware and it should run network card PXE BIOS which |
---|
306 | should obtain IP address from the network router and load |
---|
307 | undionly.kpxe file from the tftp server. Once this is done, familiar |
---|
308 | iPXE UI appears. Follow steps described in previous paragraph to |
---|
309 | boot RTEMS application. |
---|
310 | |
---|
311 | .. note:: It is not possible to use UEFI based PXE booting. Neither |
---|
312 | directly by the network card PXE BIOS nor indirectly by |
---|
313 | booting into iPXE. UEFI booting in both cases is not |
---|
314 | currently supported. |
---|
315 | |
---|
316 | Clock Drivers |
---|
317 | ------------- |
---|
318 | |
---|
319 | The BSP supports two clock drivers. If there is no build option used |
---|
320 | (see `Build Configuration Options`) for selecting particular clock |
---|
321 | driver, then the decision which is used is done during the runtime. |
---|
322 | |
---|
323 | - i8254 based driver. It is used on pre-Pentium CPUs by default. |
---|
324 | - TSC register based driver. It is used on Pentium and later CPUs by |
---|
325 | default. |
---|
326 | |
---|
327 | Console Drivers |
---|
328 | --------------- |
---|
329 | |
---|
330 | The BSP console supports device drivers for a variety of devices |
---|
331 | including VGA/keyboard and a number of serial ports. The default |
---|
332 | console is selected based on which devices are present in the |
---|
333 | following order of priority: |
---|
334 | |
---|
335 | - VGA with PS/2 keyboard |
---|
336 | - COM1 thorough COM4 |
---|
337 | - Any COM devices on the PCI bus including IO and memory mapped |
---|
338 | |
---|
339 | PCI-based UART devices are named ``/dev/pcicom<number>`` as they are |
---|
340 | probed and found. The numbers sequence starts with 1. E.g. first PCI |
---|
341 | UART device found is accessible with ``/dev/pcicom1`` name. |
---|
342 | |
---|
343 | Besides supporting generic devices above, the BSP also support |
---|
344 | specific UART chips. The drivers for those are not initialized |
---|
345 | automatically, but requires initialization from the application code: |
---|
346 | |
---|
347 | - Exar 17d15x (NS16550 compatible multiport PCI UART) |
---|
348 | |
---|
349 | Frame-Buffer Drivers |
---|
350 | -------------------- |
---|
351 | |
---|
352 | The BSP supports several drivers implementing RTEMS frame-buffer |
---|
353 | API. The default driver is for card(s) implementing VESA BIOS |
---|
354 | Extensions. Others may be enabled by using appropriate build option |
---|
355 | (see `Build Configuration Options`). Available drivers support: |
---|
356 | |
---|
357 | - generic VGA graphic card |
---|
358 | - Cirrus Logic GD5446 |
---|
359 | - generic graphic card supporting VESA BIOS Extensions |
---|
360 | |
---|
361 | Network Interface Drivers |
---|
362 | ------------------------- |
---|
363 | |
---|
364 | The network interface drivers are provided by the `libbsd`. |
---|
365 | |
---|
366 | USB Host Drivers |
---|
367 | ---------------- |
---|
368 | |
---|
369 | The USB host drivers are provided by the `libbsd`. |
---|
370 | |
---|
371 | RTC Drivers |
---|
372 | ----------- |
---|
373 | |
---|
374 | There are several real time clock devices supported by drivers in the |
---|
375 | BSP. |
---|
376 | |
---|
377 | - Maxim DS1375 |
---|
378 | - Mostek M48T08/M48T18 (Maxim/Dallas Semiconductor DS1643 compatible) |
---|
379 | - Motorola MC146818A |
---|
380 | - Renesas ICM7170 |
---|
381 | |
---|
382 | I2C Drivers |
---|
383 | ----------- |
---|
384 | There are several drivers for various I2C bus connected peripherals |
---|
385 | supported by the BSP. Supported peripherals are: |
---|
386 | |
---|
387 | - EEPROM |
---|
388 | - Maxim DS1621 temperature sensor |
---|
389 | - Semtech SC620 Octal LED Driver |
---|
390 | |
---|
391 | SPI Drivers |
---|
392 | ----------- |
---|
393 | There are several devices which connect to serial peripheral interfaces |
---|
394 | supported by the BSP. |
---|
395 | |
---|
396 | - M25P40 flash |
---|
397 | - FM25L256 fram |
---|
398 | - memory devices |
---|
399 | - SD card |
---|
400 | |
---|
401 | Legacy Drivers |
---|
402 | -------------- |
---|
403 | |
---|
404 | The BSP source code provides legacy drivers for storage and network |
---|
405 | devices. |
---|
406 | The usage of legacy drivers is discouraged and description of such use |
---|
407 | is out of the scope of this documentation. Interested users should |
---|
408 | consult BSP source code directly but use legacy driver only when it is |
---|
409 | not possible to use similar driver provided by `libbsd`. |
---|
410 | |
---|
411 | Storage Drivers |
---|
412 | ^^^^^^^^^^^^^^^ |
---|
413 | - IDE/ATA |
---|
414 | - AM26LV160/M29W160D flash |
---|
415 | |
---|
416 | Network Drivers |
---|
417 | ^^^^^^^^^^^^^^^ |
---|
418 | - 3Com 3c509 |
---|
419 | - 3Com 3c90x (Etherlink XL family) |
---|
420 | - Novell NE2000 |
---|
421 | - Western Digital WD8003 |
---|
422 | - Intel 82586 |
---|
423 | - Intel EtherExpress PRO/100 |
---|
424 | - Cirrus Logic CS8900 |
---|
425 | - DEC/Intel 21140 |
---|
426 | - SMC 91111 |
---|
427 | - Opencores Ethernet Controller |
---|
428 | - National Semiconductor SONIC DP83932 |
---|