|author||Karel Gardas <firstname.lastname@example.org>||2020-08-25 10:28:19 +0000|
|committer||Chris Johns <email@example.com>||2020-09-09 14:14:08 +1000|
user/pc386 BSP: add documentation.
The content is compiled from TBR pc386 wiki page, BSP's README files and from the actual BSP code.
1 files changed, 395 insertions, 1 deletions
diff --git a/user/bsps/bsps-i386.rst b/user/bsps/bsps-i386.rst
index a29edf6..3080d69 100644
@@ -8,4 +8,398 @@ i386
+This BSP supports a standard Intel/AMD PC on i386 and up CPUs. If run
+on a Pentium or above, the TSC register is used for timing calibration
+purposes rather than relying entirely on the i8254.
+Partial support is implemented for more modern PCs which do not have a
+complete complement of legacy peripherals.
+The BSP is able to utilize up to 3 GB of available RAM and up to 16
+CPUs. Hyper-threading is supported, but may not be detected by the
+.. note:: BSP capability to detect target hardware SMP details is
+ limited due to fact the SMP support is implemented based on
+ Intel Multi-Processor Specification (MPS). Final version of
+ the specification is version 1.4 which was released on July
+ 1, 1995. On most newer machines the MPS functionality was
+ more or less supplanted by more modern ACPI (Advanced
+ Configuration and Power Interface). Still, on some machine
+ SMP support may be fragile at least at the platform
+ detection and initialization state depending on the target
+ BIOS/ACPI/MPS compatibility implementation.
+There are several BSP variants provided which differ only in the target CPU
+optimization. The most general is `pc386` which is tuned for i386. The `pc486`
+variant is tuned for i486, `pc585` is tuned for Pentium, `pc586-sse` is tuned
+for Pentium processor supporting SSE instructions. Finally `pc686` is tuned
+for Pentium Pro processor, but generating only instructions for Pentium
+and `pcp4` is tuned and generating instructions for Pentium4 processor
+including SSE3 instructions.
+Build Configuration Options
+ If defined to a non-zero value, then print a message and wait until
+ any key is pressed before resetting board when application
+ terminates (disabled by default).
+ If defined to a non-zero value, then reset the board when the
+ application terminates (enabled by default).
+ If defined to a non-zero value, then print the exception context
+ when an unexpected exception occurs (enabled by default).
+ If defined to a non-zero value, then print more information in case
+ of a fatal error (enabled by default).
+ Enables VGA console driver (enabled by default).
+ Enables support of COM1 thorough COM4 (enabled by default).
+ Enforces usage of COM1 as a console device (disabled by default).
+ Enables legacy IDE driver (enabled by default).
+ Allows RTEMS to use storage drive(s) connected to the primary IDE
+ interface. Disable if (i) the target hardware does not have primary
+ IDE interface or (ii) it does not have any drive attached to the
+ primary IDE interface or (iii) there is no need to use drive(s)
+ attached to the primary IDE interface at all (enabled by default).
+ Allows RTEMS to use storage drive(s) connected to the secondary IDE
+ interface. Enable if (i) the target hardware does have secondary IDE
+ interface and (ii) there is at least one drive attached to the
+ secondary IDE interface and (iii) there is a need to use drive(s)
+ attached to the secondary IDE interface (disabled by default).
+ Sets the VGA display to 80x50 character mode (disabled by default).
+ Enforces clock driver to use TSC register available on Pentium and
+ higher class CPUs. If disabled and ``CLOCK_DRIVER_USE_8243`` is
+ disabled too, then BSP will choose clock driver mechanism itself
+ during the runtime (disabled by default).
+ Enforces clock driver to use 8254 chip. If disabled and
+ ``CLOCK_DRIVER_USE_TSC`` is disabled too, then BSP will choose clock
+ driver mechanism itself during the runtime (disabled by default).
+ Defines how many descriptors in GDT may be allocated for the
+ application or driver usage.
+ Enables usage of Cirrus GD5446 graphic card for RTEMS frame-buffer
+ (disabled by default).
+ Enables usage of generic VGA graphic card for RTEMS frame-buffer
+ (disabled by default).
+ Enables usage of graphic card implementing VESA BIOS Extensions for
+ RTEMS frame-buffer (enabled by default).
+ Enables GDB support for debugging over serial port (enabled by
+The BSP supports several runtime options. They may be used by either setting
+during boot by using target hardware bootloader or by using Qemu's
+``-append`` command-line parameter in case BSP application is run
+inside the Qemu emulator.
+.. option:: --console=<dev>
+ specifies console
+ device. E.g. ``--console=/dev/com1``. COM device name may
+ also be followed by a baud rate like ``--console=/dev/com2,19200``
+.. option:: --printk=<dev>
+ specifies target device for printk/getk
+ calls. E.g. ``--printk=/dev/vgacons``
+.. option:: --video=<mode>
+ specifies required video mode. The options applies only to
+ the systems supporting VESA BIOS Extensions. Choices are
+ ``auto`` which selects graphic mode automatically or
+ ``none``/``off`` which disables initialization of the
+ graphic driver or direct specification of resolution
+ and/or color depth by
+ ``<resX>x<resY>[-<bpp>]``. E.g. ``--video=none`` disables
+ graphic driver. Using ``--video=1280x1024`` sets video
+ mode to 1280x1024 pixels mode while ``--video=800x600-32``
+ sets video mode to 800x600 pixels with 32bit color depth.
+.. option:: --disable-com1-com4
+ disables usage of COM1 thorough COM4.
+If the specified console device is not present then suitable fallback
+device is selected based on the device order specified in `Console Drivers`.
+PCI-based UART devices are named ``/dev/pcicom<number>`` as they are
+probed and found. The numbers sequence starts with 1. E.g. first PCI
+UART device found is accessible with ``/dev/pcicom1`` name.
+Testing with Qemu
+To test with Qemu, we need to:
+- Build / install Qemu (most distributions should have it available on the
+ package manager).
+Booting RTEMS in Qemu
+.. code-block:: none
+ $ qemu-system-i386 -m 128 -no-reboot -append \
+ "--video=off --console=/dev/com1" -nographic -kernel ./hello.exe
+This command boots ``hello.exe`` application located in current
+directory and sets Qemu to provide 128MB RAM and to switch both Qemu's
+and BSP's video off.
+Booting RTEMS in KVM accelerated Qemu
+When the Qemu host hardware and OS support KVM, it is possible to use it
+to accelerate BSP run by using ``-machine type=q35,accel=kvm`` Qemu option.
+Depending on the Qemu host configuration it may or may not require
+administrator privileges to run the command.
+.. code-block:: none
+ $ sudo qemu-system-i386 -machine type=q35,accel=kvm -m 128 -no-reboot \
+ -append "--video=off --console=/dev/com1" -nographic -kernel \
+This command boots ``dhrystone.exe`` application and sets Qemu to use
+Running on a PC hardware
+There are several ways how to start RTEMS BSP application on the real
+Booting with GRUB boot-loader
+In case the target machine does already have Linux with GRUB boot
+loader installed, then the most easy way to load and boot RTEMS is
+to use GRUB. This may be done in following steps:
+(i) prepare RTEMS binary and save it either to Linux
+ partition/directory accessible from GRUB or to an USB stick.
+(ii) boot machine to GRUB menu.
+.. note:: Some Linux installations hide GRUB menu by default and
+ quickly continues with booting default Linux option. If this
+ is the case, then during the boot hold down 'Shift' key to
+ un-hide the menu.
+(iii) press ``c`` key to get into the GRUB's command-line mode.
+(iv) use ``ls`` command to observe drives and partitions on them. If
+ unsure, use 'ls' command with drive/partition description to show
+ the target file system content. E.g. ``ls (hd1,msdos1)/`` will list
+ files on the second drive, first partition which is formatted
+ using fat/vfat file-system.
+.. note:: Use `ls (hdX, partY)` without a slash at the end to show
+ information about the partition.
+(v) use ``multiboot`` command to load the RTEMS application binary for
+ boot. E.g. ``multiboot (hd1,msdos2)/rtems/ticker.exe`` will load
+ ticker.exe from the second drive, second partition with fat/vfat
+ file-system and its rtems directory.
+(vi) use ``boot`` command to boot loaded binary.
+.. note:: Advantage of using GRUB for booting RTEMS is the GRUB's
+ support for both classical BIOS and UEFI boot. This way
+ RTEMS may be booted even on UEFI only systems.
+Booting with PXE/iPXE
+PXE booting is more complex than GRUB based booting and hence requires
+more infrastructure configuration. The booting may be done in two
+(i) using iPXE booted from an USB stick or a hard drive
+It may be done using following steps:
+- Download iPXE ISO image from http://boot.ipxe.org/ipxe.iso
+- Either record it to CD/DVD or copy it to an USB stick
+- boot from the medium above on the target hardware
+- wait for ``Press Ctrl-B for the iPXE command line...`` prompt and once
+ it appears press ``Ctrl-B`` key.
+- use 'dhcp' command to configure network interface card
+- use 'boot' command to boot RTEMS application from specified tftp
+ server. E.g. ``boot tftp://10.0.0.5/hello.exe`` will boot hello.exe
+ application from the tftp server on host with 10.0.0.5 IP address.
+Whole interaction may look as:
+.. code-block:: none
+ Press Ctrl-B for the iPXE command line...
+ iPXE> dhcp
+ Configuring (net0 <mac address>)..... ok
+ iPXE> boot tftp://10.0.0.5/hello.exe
+(ii) using built in network card's PXE BIOS to boot into iPXE
+This way is more complex and requires network infrastructure
+configuration changes which description is out of the scope of this
+documentation. Generic steps how to achieve this are:
+- use target hardware BIOS/SETUP to enable PXE booting on the board
+- setup network router to announce tftp server and file on it as a
+ part of the router's BOOTP/DHCP protocol reply. You should use
+ http://boot.ipxe.org/undionly.kpxe as a payload for non-UEFI based
+ booting. Put that file into tftp server served/root directory.
+- reboot target hardware and it should run network card PXE BIOS which
+ should obtain IP address from the network router and load
+ undionly.kpxe file from the tftp server. Once this is done, familiar
+ iPXE UI appears. Follow steps described in previous paragraph to
+ boot RTEMS application.
+.. note:: It is not possible to use UEFI based PXE booting. Neither
+ directly by the network card PXE BIOS nor indirectly by
+ booting into iPXE. UEFI booting in both cases is not
+ currently supported.
+The BSP supports two clock drivers. If there is no build option used
+(see `Build Configuration Options`) for selecting particular clock
+driver, then the decision which is used is done during the runtime.
+- i8254 based driver. It is used on pre-Pentium CPUs by default.
+- TSC register based driver. It is used on Pentium and later CPUs by
+The BSP console supports device drivers for a variety of devices
+including VGA/keyboard and a number of serial ports. The default
+console is selected based on which devices are present in the
+following order of priority:
+- VGA with PS/2 keyboard
+- COM1 thorough COM4
+- Any COM devices on the PCI bus including IO and memory mapped
+Besides supporting generic devices above, the BSP also support
+specific UART chips. The drivers for those are not initialized
+automatically, but requires initialization from the application code:
+- Exar 17d15x (NS16550 compatible multiport PCI UART)
+The BSP supports several drivers implementing RTEMS frame-buffer
+API. The default driver is for card(s) implementing VESA BIOS
+Extensions. Others may be enabled by using appropriate build option
+(see `Build Configuration Options`). Available drivers support:
+- generic VGA graphic card
+- Cirrus Logic GD5446
+- generic graphic card supporting VESA BIOS Extensions
+Network Interface Drivers
+The network interface drivers are provided by the `libbsd`.
+USB Host Drivers
+The USB host drivers are provided by the `libbsd`.
+There are several real time clock devices supported by drivers in the
+- Maxim DS1375
+- Mostek M48T08/M48T18 (Maxim/Dallas Semiconductor DS1643 compatible)
+- Motorola MC146818A
+- Renesas ICM7170
+There are several drivers for various I2C bus connected peripherals
+supported by the BSP. Supported peripherals are:
+- Maxim DS1621 temperature sensor
+- Semtech SC620 Octal LED Driver
+There are several devices which connect to serial peripheral interfaces
+supported by the BSP.
+- M25P40 flash
+- FM25L256 fram
+- memory devices
+- SD card
+The BSP source code provides legacy drivers for storage and network
+The usage of legacy drivers is discouraged and description of such use
+is out of the scope of this documentation. Interested users should
+consult BSP source code directly but use legacy driver only when it is
+not possible to use similar driver provided by `libbsd`.
+- AM26LV160/M29W160D flash
+- 3Com 3c509
+- 3Com 3c90x (Etherlink XL family)
+- Novell NE2000
+- Western Digital WD8003
+- Intel 82586
+- Intel EtherExpress PRO/100
+- Cirrus Logic CS8900
+- DEC/Intel 21140
+- SMC 91111
+- Opencores Ethernet Controller
+- National Semiconductor SONIC DP83932