Hi, attached is current work in progress of my pc386 BSP documentation attempt.
There is still a big "Running on PC hardware" paragraph missing, but other parts should be more stable hence good for review and/or comments. Thanks, Karel
>From 952311867654322c75f8b0fa47e0f11786876831 Mon Sep 17 00:00:00 2001 From: Karel Gardas <karel.gar...@centrum.cz> Date: Tue, 25 Aug 2020 10:28:19 +0000 Subject: [PATCH] user/pc386 BSP: add some documentation (booting on real PC HW info still missing) --- user/bsps/bsps-i386.rst | 294 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 293 insertions(+), 1 deletion(-) diff --git a/user/bsps/bsps-i386.rst b/user/bsps/bsps-i386.rst index a29edf6..8b00e18 100644 --- a/user/bsps/bsps-i386.rst +++ b/user/bsps/bsps-i386.rst @@ -8,4 +8,296 @@ 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 not supported, but BSP will run on system +with hyper-threading enabled just reporting number of cores as a +number of available CPUs. + +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=<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 \ + ./dhrystone.exe + +This command boots ``dhrystone.exe`` application and sets Qemu to use +KVM acceleration. + + +Running on PC hardware +---------------------- + +TODO + +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 -- 2.25.1
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
