From aba4c6bc9bd6ebb4f2754303c0f9d75d5de35cfb Mon Sep 17 00:00:00 2001 From: Karel Gardas Date: Tue, 25 Aug 2020 10:28:19 +0000 Subject: user/pc386 BSP: add documentation. The content is compiled from TBR pc386 wiki page, BSP's README files and from the actual BSP code. --- user/bsps/bsps-i386.rst | 396 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 395 insertions(+), 1 deletion(-) (limited to 'user') diff --git a/user/bsps/bsps-i386.rst b/user/bsps/bsps-i386.rst index a29edf6..3080d69 100644 --- a/user/bsps/bsps-i386.rst +++ b/user/bsps/bsps-i386.rst @@ -8,4 +8,398 @@ i386 pc386 ===== -TODO. +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 +BSP successfully. + +.. 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 +--------------------------- + +``BSP_PRESS_KEY_FOR_RESET`` + 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). + +``BSP_RESET_BOARD_AT_EXIT`` + If defined to a non-zero value, then reset the board when the + application terminates (enabled by default). + +``BSP_PRINT_EXCEPTION_CONTEXT`` + If defined to a non-zero value, then print the exception context + when an unexpected exception occurs (enabled by default). + +``BSP_VERBOSE_FATAL_EXTENSION`` + If defined to a non-zero value, then print more information in case + of a fatal error (enabled by default). + +``BSP_ENABLE_VGA`` + Enables VGA console driver (enabled by default). + +``BSP_ENABLE_COM1_COM4`` + Enables support of COM1 thorough COM4 (enabled by default). + +``USE_COM1_AS_CONSOLE`` + Enforces usage of COM1 as a console device (disabled by default). + +``BSP_ENABLE_IDE`` + Enables legacy IDE driver (enabled by default). + +``IDE_USE_PRIMARY_INTERFACE`` + 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). + +``IDE_USE_SECONDARY_INTERFACE`` + 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). + +``BSP_VIDEO_80x50`` + Sets the VGA display to 80x50 character mode (disabled by default). + +``CLOCK_DRIVER_USE_TSC`` + 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). + +``CLOCK_DRIVER_USE_8254`` + 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). + +``NUM_APP_DRV_GDT_DESCRIPTORS`` + Defines how many descriptors in GDT may be allocated for the + application or driver usage. + +``USE_CIRRUS_GD5446`` + Enables usage of Cirrus GD5446 graphic card for RTEMS frame-buffer + (disabled by default). + +``USE_VGA`` + Enables usage of generic VGA graphic card for RTEMS frame-buffer + (disabled by default). + +``USE_VBE_RM`` + Enables usage of graphic card implementing VESA BIOS Extensions for + RTEMS frame-buffer (enabled by default). + +``BSP_GDB_STUB`` + Enables GDB support for debugging over serial port (enabled by + default). + +Runtime Options +--------------- +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= + + 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= + + specifies target device for printk/getk + calls. E.g. ``--printk=/dev/vgacons`` + +.. option:: --video= + + 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 + ``x[-]``. 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`` 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 \ + ./dhrystone.exe + +This command boots ``dhrystone.exe`` application and sets Qemu to use +KVM acceleration. + + +Running on a PC hardware +---------------------- + +There are several ways how to start RTEMS BSP application on the real +PC hardware. + +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 +possible ways: + +(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 )..... 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. + +Clock Drivers +------------- + +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 + default. + +Console Drivers +--------------- + +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) + +Frame-Buffer Drivers +-------------------- + +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`. + +RTC Drivers +----------- + +There are several real time clock devices supported by drivers in the +BSP. + +- Maxim DS1375 +- Mostek M48T08/M48T18 (Maxim/Dallas Semiconductor DS1643 compatible) +- Motorola MC146818A +- Renesas ICM7170 + +I2C Drivers +----------- +There are several drivers for various I2C bus connected peripherals +supported by the BSP. Supported peripherals are: + +- EEPROM +- Maxim DS1621 temperature sensor +- Semtech SC620 Octal LED Driver + +SPI Drivers +----------- +There are several devices which connect to serial peripheral interfaces +supported by the BSP. + +- M25P40 flash +- FM25L256 fram +- memory devices +- SD card + +Legacy Drivers +-------------- + +The BSP source code provides legacy drivers for storage and network +devices. +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`. + +Storage Drivers +^^^^^^^^^^^^^^^ +- IDE/ATA +- AM26LV160/M29W160D flash + +Network Drivers +^^^^^^^^^^^^^^^ +- 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 -- cgit v1.2.3