Fábio Coutada
ae6144a1c5
- Extract 37 of 45 PDFs under docs/ to docs-extracted/ - Preserve directory structure (apex, cdk, development, platform, etc.) - Add docs-extracted/index.md with navigation table - 8 PDFs were 0-byte/empty and could not be extracted
242 KiB
| title | source | category | pages | extracted |
|---|---|---|---|---|
| Platform Manual X86 Amd64 | docs/platform/platform-manual-x86_amd64.pdf | platform | 90 | 2026-07-06T23:05:36.957841 |
Platform Manual X86 Amd64
Extracted from
docs/platform/platform-manual-x86_amd64.pdf(90 pages). Figures, diagrams, and tables may not render accurately in plain text.
PikeOS Platform Manual for x86-amd64 Boards
Am Pfaffenstein 14, D-55270 Klein-Winternheim
Notice: The contents of this document are proprietary to SYSGO GmbH and shall not be disclosed, disseminated, copied, or used except for purposes expressly authorized in writing by SYSGO GmbH. PikeOS Platform Manual for x86-amd64 Boards PikeOS D5.0, Document Version D5.0-490
c 2005 – 2019 SYSGO GmbH
SYSGO GmbH Email: office@sysgo.com Am Pfaffenstein 14 55270 Klein-Winternheim, Germany http://www.sysgo.com
All rights reserved. PikeOS is a trademark of SYSGO GmbH. The designations used to identify other software or hardware products in this publication may be trademarks of their manufacturers or sellers. Contents
1 About this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2 Boards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.2 Board qemu-x86-64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.2.1 The Board Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.2.2 Set-up environment for QEMU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.2.3 The PSP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.2.4 Running the Hello World Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.2.5 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.3 Board x86-64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.3.1 The Board Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.3.2 The PSP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.3.3 I/O Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.3.4 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.4 Board Interface Concept VPX3a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.4.1 The Board Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.4.2 The PSP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.4.3 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.5 Board Kontron COMe-bBD6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.5.1 The Board Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.5.2 The PSP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.5.3 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.6 Board Kontron VX3035 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.6.1 The Board Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.6.2 The PSP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.6.3 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3 PSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.2 Common PSP Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.3 IO Sequencer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.4 Microcode Updater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 3.4.1 Microcode Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 3.4.2 CPU identification printout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3.5 PSP x86-64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3.5.1 The PSP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3.5.2 PSP Specific Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 3.5.3 PSP Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 3.5.3.1 Serial console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.5.3.2 Text Mode Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.5.3.3 Framebuffer Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.5.3.4 VESA Framebuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.5.4 SMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
4 CONTENTS
3.5.5 Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.5.5.1 PIC Interrupt Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.5.5.2 IO-APIC Interrupt Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.5.5.3 Overriding Interrupt Routing Mode . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.5.5.4 Message Signaled Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.5.5.4.1 MSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.5.5.4.2 MSI-X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.5.5.5 System Management Interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.5.6 Recommended BIOS Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.5.7 Entry Point Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.5.8 System Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.5.9 System Poweroff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.5.10 Multiboot2 Execution Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.5.11 BIOS Supplied Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.5.12 IO Sequencer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.5.13 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4 Boot Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 4.1 Boot Strategies Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 4.2 Integrity Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 4.3 Boot strategy "multiboot2" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 4.4 Boot strategy "grub2" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 4.4.1 Legacy BIOS bootstrap under Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 4.4.2 Legacy BIOS bootstrap under cygwin . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 4.4.3 UEFI BIOS bootstrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 4.4.4 Using existing GRUB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 4.4.5 Configuring Text Mode or Framebuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 4.5 Boot strategy "diskimage" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.5.1 Configuring Textmode or Framebuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.6 Boot strategies "elf" and "multiboot1" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.6.1 Diskless Client with Etherboot/gPXE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 4.7 Boot strategy "uefi64" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 4.8 Boot strategy "qemu" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 4.9 Raw pikeos binary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 4.10 Prebooters and Bootloaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 4.10.1 Legacy Prebooter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 4.10.2 UEFI Prebooter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 4.10.3 GRUB2 as Prebooter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 5 Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 5.1 Serial Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 5.1.1 Serial 8250 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 5.1.1.1 Driver Specific Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . 40 5.1.1.2 Driver IOCTL Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 5.1.1.3 Driver Specific Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 5.1.1.4 User Level Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 5.1.1.5 Kernel Level Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 5.1.1.5.1 Kernel Fusion Project . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 5.1.1.5.2 Configuring the Integration Project . . . . . . . . . . . . . . . . . . . . 42
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
CONTENTS 5
5.2 Ethernet Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 5.2.1 Ethernet e1000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 5.2.1.1 Driver Base Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 5.2.1.2 Physical Device Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 5.2.1.3 BSP Configuration / PCI Device Configuration . . . . . . . . . . . . . . . . . . . 45 5.2.1.4 Virtual Channel Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 5.2.1.5 Maximum Transfer Size Configuration . . . . . . . . . . . . . . . . . . . . . . . . 46 5.2.1.6 Driver Specific Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 5.2.2 Ethernet Realtek RTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 5.2.2.1 Driver Base Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 5.2.2.2 Physical Device Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 5.2.2.3 BSP Configuration / PCI Device Configuration . . . . . . . . . . . . . . . . . . . 48 5.2.2.4 Virtual Channel Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 5.2.2.5 Driver Specific Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 5.2.3 Ethernet virtio-net . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 5.2.3.1 Driver Base Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 5.2.3.2 Physical Device Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 5.2.3.3 Virtual Channel Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 5.2.3.4 Maximum Transfer Size Configuration . . . . . . . . . . . . . . . . . . . . . . . . 52 5.2.3.5 Driver Specific Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 5.3 Block Device and MTD Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 5.3.1 Block Device and MTD Simulator blkdrvsim . . . . . . . . . . . . . . . . . . . . . . . . . 52 5.3.1.1 Driver Specific Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . 53 5.3.1.1.1 blkdrvsim Base Component . . . . . . . . . . . . . . . . . . . . . . . . 53 5.3.1.1.2 blkdrvsim Device Component . . . . . . . . . . . . . . . . . . . . . . . 53 5.3.1.2 Driver Specific Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 5.3.1.3 Usage of the User Level Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 5.3.1.3.1 Integration Project for the User Level Driver . . . . . . . . . . . . . . . . 54 5.3.1.4 Usage of the Kernel Level Driver . . . . . . . . . . . . . . . . . . . . . . . . . . 55 5.3.1.4.1 Fusion Project for the Kernel Level Driver . . . . . . . . . . . . . . . . . 55 5.3.1.4.2 Integration Project for the Kernel Level Driver . . . . . . . . . . . . . . . 56 5.3.1.5 Demonstration Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 5.3.1.6 Driver Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 5.3.2 AHCI Block Device Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 5.3.2.1 Driver Specific Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . 57 5.3.2.1.1 AHCI Base Component . . . . . . . . . . . . . . . . . . . . . . . . . . 57 5.3.2.1.2 AHCI Device Component . . . . . . . . . . . . . . . . . . . . . . . . . 58 5.3.2.1.3 Operation Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 5.3.2.1.4 Speed Allowed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 5.3.2.1.5 BLK Devices for disk drive partitions . . . . . . . . . . . . . . . . . . . 59 5.3.2.1.6 AHCI Device Partition Component . . . . . . . . . . . . . . . . . . . . 59 5.3.2.2 User Level Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 5.3.2.3 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 5.3.2.4 AHCI Emulation in the QEMU . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 5.3.2.5 Multiple AHCI Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 5.3.2.6 Demonstration Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
6 CONTENTS
5.3.3 USB Block Device Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.3.3.1 User Level Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.3.3.1.1 USB Device Component . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.3.3.2 USB Emulation in QEMU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.3.3.3 Demonstration Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.3.3.4 Driver Specific Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.3.4 Partitioned Image Creation Tool mkblkimage . . . . . . . . . . . . . . . . . . . . . . . . 63
5.4 PCI Controller Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 5.4.1 PSP PCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 6 The PikeOS CDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 6.1 Target binaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 7 Direct I/O Device Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 7.1 Graphical Framebuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 7.2 VGA and PS/2 Keyboard + Mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 A Architecture Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 A.1 Supported Architectures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 A.2 Address Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 A.3 Basic Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 A.4 Architecture specific KINFO page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 A.5 User Mode Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 A.5.1 Register Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 A.5.2 Short Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 A.5.3 FPU Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 A.5.4 Layout of GDT and LDT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 A.5.5 Segment registers in the 64-bit mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 A.5.6 Segment registers in the compatibility mode . . . . . . . . . . . . . . . . . . . . . . . . . 78 A.5.7 System Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 A.6 Mapping Translations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 A.6.1 PikeOS to Architecture Specific Access Permissions . . . . . . . . . . . . . . . . . . . . 79 A.6.2 Architecture Specific to PikeOS Access Permissions . . . . . . . . . . . . . . . . . . . . 79 A.6.3 Supported Caching Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 A.6.4 VMIT Cache Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 A.7 Translation of Architecture Specific Exceptions to PikeOS Trap Codes . . . . . . . . . . . . . . . 81 A.8 Memory Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 A.8.1 Kernel Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 A.9 Cache Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 A.10 Speculative Execution Side Channels Mitigations - Meltdown, Spectre and MDS . . . . . . . . . . 83 A.11 Hardware Dependent Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 A.12 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 B Boards Fusion/PSP Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 C Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
1 About this Manual
This manual describes additional platform specific information and supported boards for the x86 architecture. The manual is organized as follows. The Boards sub-chapters discuss the individual board support packages for each board. Each BSP chapter con- tains information about available drivers, board specific settings or pre-compiled system software with additional system extensions. The platform support packages (PSPs) chapter mimics the structure of BSP chapters and discusses more low level information and possible limitations. The Boot Strategies chapter discusses the setup of bootloaders for different boot strategies supported by the BSPs. The Drivers chapter discusses supported device drivers, the device driver configuration and usage. The CDK chapter provides information about the compiler usage and settings. The Architecture Dependencies chapter discusses various low level interfaces and information from the PikeOS kernel point of view. The Boards Fusion/PSP Projects chapter gives an overview of the corresponding kernel and PSSW fusion projects for each BSP.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
2 Boards
2.1 Introduction
PikeOS supports multiple processor architectures and, for each architecture, multiple board types. This manual covers the x86, 64-bit architecture and the reference boards supported by PikeOS at the moment this manual was published. The PikeOS kernel for x86 64-bit will run on the Intel and AMD 64-bit platforms. Refer the to the section A for the details. All x86 boards and PSPs have integrated PCI support. The boards (BSPs) have by default the PCI Manager component. To list the PCI devices managed by the PCI Manager or change PCI Manager configuration, please refer to PikeOS User Manual, section 10.7, page 244. For an introduction to the PCI Manager and MSI, MSI-X related options, please refer to PikeOS User Manual, section 10.7, page 244. The x86 platform has a variety of BIOS options which impact system performance, energy management and OS compatibility, please check your board’s BIOS settings. The sections 3.5.6, 3.5.5, and 3.5.4 discuss various recommended settings for interrupt handling and real-time settings.
2.2 Board qemu-x86-64
This board support package supports the QEMU emulated machine "pc" (version pc 1.2). The Board qemu-x86-64 board support package consists of the x86-64 PSP, PCI Manager, PikeOS system Software and drivers for serial, Ethernet and AHCI interfaces. The PikeOS board name for this board is qemu- x86-64.
2.2.1 The Board Configuration
PikeOS provides drivers and configuration for the following board resources:
• Serial controller (8250), section 5.1.1, page 40
• Ethernet controller (virtio-net), section 5.2.3, page 49
The drivers for the following resources are available on demand:
• AHCI controller (ahci), section 5.3.2, page 57
• USB mass storage (blkusb), section 5.3.3, page 61
The PCI Manager component is automatically included. To list the PCI devices managed by the PCI Manager or change PCI Manager configuration, please refer to PikeOS User Manual, section 10.7, page 244.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Board qemu-x86-64 9
2.2.2 Set-up environment for QEMU
The QEMU virtio-net controller can be reached from outside of QEMU. The QEMU network setup is described in the detail in the PikeOS User Manual. To load and run the ROMimage with networking support, use the generated QEMU command line. By default, the virtio-net device is instantiated using ’-device virtio-net-pci,vlan=0’ command line option. By default, the driver matches ’byid/1af4/1000/1af4/0001/0000’ PCI device, which can be adjusted in the virtio-net device BSP settings. To enable QEMU’s serial line support, add the option ’-serial {device}’ to the QEMU command line, where {device} might be one of stdio, vc, pty, null. The VGA console can be used in text or framebuffer mode. This configuration is provided to the PikeOS by the grub2 boot loader. For details see4.4. To enable QEMU’s AHCI support emulation, open the integration project, locate a AHCI Device Component and enable the device emulation by switching the Enable checkbox on (parameter EMULATE), then in the Drive Image File (parameter DRIVE_IMAGE) parameter select a image file and configure the Physical Block Size of emulated device (parameter BLOCK_SIZE). The QEMU’s boot strategy script will execute QEMU with required arguments. There is preconfigured demo image for AHCI Device located in the /opt/pikeos- D5.0/share/mkblkimage/blkdemo.image. This image if it is configured, will be copied into integration project directory upon the first boot. See the README in the mkblkimage demo directory for details about this image.
2.2.3 The PSP Configuration
For the PSP configuration options see section 3.5, page 19.
2.2.4 Running the Hello World Image
The PikeOS distribution contains a ROMimage which can be used to verify that development host and target are set up correctly. This section explains the steps of the setup and boot procedure which are specific to the Board qemu-x86-64 board. To load and run the pre-compiled "Hello World" image, start QEMU with the following command:
sh# /opt/pikeos-D5.0/target/x86/amd64/boot-images/simple-pikeos-qemu-x86-64-qemu.qemu_cmdline
Now you should see the following output generated by the "Hello World" image:
PikeOS (C) Copyright SYSGO AG, Germany ROM image build: devel-pikeos@builder.sysgo.com-250317-00:14 Kernel build: 4.2-1558, type: noassert tracesys smp standard ASP: "x86_amd64" x86_64 SMEP RDTSCP PSP build: 4.2-325 PSP: "x86-64" PC x86-64 (SMP) Features: RETAIL TRACER-SYSCALL OPT SMP(8/64) Configuration limits: respart: 63 task: 256 thread: 511
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
10 Boards
timepart: 63 priority: 256 interrupts: 512 TP windows: 256 thr sstack: 4096 B Resource partition 0 kernel memory refill strategy: dynamic (on demand) Time stamp counter clock: 1496673 kHz, user accessible System ticker: dynamic mode, resolution 10000 ns Time partition switch: 10000000 ns, watchdog timeout: 10000000 ns Free memory: 4072916 KiB PikeOS PCI Manager KDEV, Build: 4.2-172 PSSW +Ext. FPs +Messages (Production), Build: 4.2-3587 eth0: Using MSIX interrupts with 2 vectors eth0: Registered MAC address(02:70:34:8a:2a:2e) for channel ’3’ eth0: Registered MAC address(06:70:34:8a:2a:2e) for channe eth0: Registered MAC address(0a:70:34:8a:2a:2e) for channel ’1’ 8250: Provider "ser0" started, Build: 4.2-155 Production eth0: Registered MAC address(0e:70:34:8a:2a:2e) for channel ’0’ e1000: Provider "eth0" started, Build: 4.2-116 Production Hello World, starting up. Hello World, this is task 22, thread 0 Hello World, this is task 22, thread 0 ...
2.2.5 Limitations
See section 3.5, page 19 for the PSP limitations.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
2.3 Board x86-64
The Board x86-64 board is supported by the PikeOS PSP x86-64. The PikeOS board name for this board is x86-64. Note: Because of the vast variety of x86 computers, please contact the PikeOS support to get assistance for your project configuration.
2.3.1 The Board Configuration
The board has no pre-configured drivers. You may add serial or Ethernet drivers see section 2.2, page 8 as a reference. See the I/O mappings sub-chapter for the hardware address space mappings. The PCI Manager component is automatically included. To list the PCI devices managed by the PCI Manager or change PCI Manager configuration, please refer to PikeOS User Manual, section 10.7, page 244.
2.3.2 The PSP Configuration
For the PSP configuration options see section 3.5, page 19.
2.3.3 I/O Mappings
In the most cases, the PCI Manager can be used to grant particular PCI I/O resources to the specified partition without the need to specify the lists of physical addresses manually. To list the PCI devices managed by the PCI Manager or change PCI Manager configuration, please refer to PikeOS User Manual, section 10.7, page 244. If some device uses some I/O ports or memory mapped area which is not accessible through standard PCI BARs, then a special direct hardware access mapping needs to be established. The system integrator can add access to the I/O port or memory addresses of desired devices in the VMIT. The PikeOS System Software Reference Manual describes how to do this. Warning: Granting hardware access to partitions may break the security/safety model. You can contact the PikeOS support to get assistance for your project configuration.
Please consult the ELinOS Platform manuals for further details of how to add access to the certain devices to the P4Linux.
2.3.4 Limitations
See section 3.5, page 19 for the PSP limitations.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
2.4 Board Interface Concept VPX3a
The Board Interface Concept VPX3a board is supported by the PikeOS PSP x86-64. The PikeOS board name for this board is ic-int-vpx3a-64.
2.4.1 The Board Configuration
PikeOS provides drivers and configuration for the following board resources:
• Serial controller (8250), section 5.1.1, page 40
• 3x Ethernet controllers (e1000), section 5.2.1, page 43
The drivers for the following resources are available on demand:
• AHCI controller (ahci), section 5.3.2, page 57
• USB mass storage (blkusb), section 5.3.3, page 61
This BSP supports by the default three on-board Ethernet controllers. Each Ethernet controller is identified by the PCI Ethernet class ID and instance number. Thus if other Ethernet PCI Express cards are installed, the instance numbers of the Ethernet adapters might change. It is possible to change the PCI device location string in the respective e1000 device configuration, BSP section. For a string format please check the PikeOS User Manual, section 10.7, page 244. The PCI Manager component is automatically included. To list the PCI devices managed by the PCI Manager or change PCI Manager configuration, please refer to PikeOS User Manual, section 10.7, page 244.
2.4.2 The PSP Configuration
For the PSP configuration options see section 3.5, page 19.
2.4.3 Limitations
See section 3.5, page 19 for the PSP limitations.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
2.5 Board Kontron COMe-bBD6
The Board Kontron COMe-bBD6 board is supported by the PikeOS PSP x86-64. The PikeOS board name for this board is kontron-come-bbd6-64.
2.5.1 The Board Configuration
PikeOS provides drivers and configuration for the following board resources:
• Serial controller (8250), section 5.1.1, page 40
• 1x Ethernet controllers (e1000), section 5.2.1, page 43
The PCI Manager component is automatically included. To list the PCI devices managed by the PCI Manager or change PCI Manager configuration, please refer to PikeOS User Manual, section 10.7, page 244.
2.5.2 The PSP Configuration
For the PSP configuration options see section 3.5, page 19.
2.5.3 Limitations
The BIOS of the board provides wrong interrupt routing information for certain PCIe slots. Be sure to use latest BIOS from the board manufacturer. The issue exists up to and including BIOS project version 1.14, built on 06/17/2016. See section 3.5, page 19 for the PSP limitations.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
2.6 Board Kontron VX3035
The Board Kontron VX3035 board is supported by the PikeOS PSP x86-64. The PikeOS board name for this board is kontron-vx3035-64.
2.6.1 The Board Configuration
PikeOS provides drivers and configuration for the following board resources:
• Serial controller (8250), section 5.1.1, page 40
• 3x Ethernet controllers (e1000), section 5.2.1, page 43
The drivers for the following resources are available on demand:
• AHCI controller (ahci), section 5.3.2, page 57
• USB mass storage (blkusb), section 5.3.3, page 61
This BSP supports by the default three on-board Ethernet controllers. Each Ethernet controller is identified by the PCI Ethernet class ID and instance number. Thus if other Ethernet PCI Express cards are installed, the instance numbers of the Ethernet adapters might change. It is possible to change the PCI device location string in the respective e1000 device configuration, BSP section. For a string format please check the PikeOS User Manual, section 10.7, page 244. The PCI Manager component is automatically included. To list the PCI devices managed by the PCI Manager or change PCI Manager configuration, please refer to PikeOS User Manual, section 10.7, page 244.
2.6.2 The PSP Configuration
For the PSP configuration options see section 3.5, page 19.
2.6.3 Limitations
See section 3.5, page 19 for the PSP limitations.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
3 PSPs
3.1 Introduction
This chapter describes the supported platform support packages and their configuration. The first section de- scribes the common PSP properties which may be used to configure various options of the PSP. The following section discusses low level details, functionalities and limitations of each supported PSPs including PSP specific properties.
3.2 Common PSP Properties
Some features of the PSP can be controlled via properties which are be specified in the RBX file. This section describes the available PSP properties for the different PSPs. The default value is used if the corresponding property is not specified. Table 1 lists the PSP properties and their default values for all x86 based PSPs.
Path Type Default
psp/console/port uint32 64
This property specifies the console output port. The value 0 disables the console output, values 1 or 2
cause the console output to be directed to the serial controller 1 or 2, value 64 directs the console output to
a graphical adapter. Consult the respective PSP chapter for details.
psp/debug/port uint32 1
This property specifies the debug port. The value 0 disables the debug port, values 1 or 2 cause debug data
to be directed to the serial controller 1 or 2. Application debugging uses muxa channels, not this interface.
psp/console/baudrate uint32 38400
This property specifies the baud rate for the console port. Possible values are 9600, 19200, 38400, 57600,
and 115200.
psp/memory/size uint64 0
This property may be used to lower the the amount of available RAM reported by the bootloader to a specific
value given in bytes. The Value 0 causes the PSP to use all available RAM.
psp/cpu_mask uint32 0
This property defines a static set of CPUs used in SMP operation. Each bit represents a CPU which shall
be booted at the system start. The value 0 enables CPU autodetection via BIOS provided MPS tables.
psp/memory/test bool false
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
16 PSPs
Path Type Default
This property provides a simple memory tester, which will test all PSP specified P4_MRT_URW regions. The
memory test consists of two passes. The first pass will fill all regions with the address pattern, second pass
fills the regions with the bit-inverted address pattern. The memtester checks if the address pattern matches
after each pass. The value 0 disables the feature, the value 1 enables this test.
Table 1: x86 PSP specific properties with default values
Some of the kernel defined properties influence the PSP behavior, namely p4/kernel/num_cpu and p4/kernel/boot_message (see table 2). For the complete list please refer to the PikeOS Kernel Reference Manual, section 2, page 581.
Path Type Default
p4/kernel/boot_message uint32 2
Let the kernel display a message on startup. Setting to 0 disables any boot message of the kernel. Setting
to 1 enables the welcome message of the kernel. Setting to 2 or higher enables some kernel statistics on
the current configuration and memory usage of the system. Setting to 3 or higher enables output of CPU
information.
Table 2: x86 kernel defined properties and PSP behavior
Please consult the PSP chapter for further notes about the p4/kernel/boot_message property.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
3.3 IO Sequencer
IO Sequencer is a mechanism to allow a user to make simple board-specific register adjustments without writing a driver or a custom PSP. The adjustments to be made are described in the property file system, by default under the board/config/io_seq directory. The configuration consists of property sub-directories named 0 . . . n − 1, each describing a write to a memory location (presumably a memory-mapped register). The properties listed in table 3 are used to describe the memory operation.
addr addr Address of memory location that should be changed.
The address is a virtual address, translation depends on
the PSP.
value uint64 Value that should be written at the given address. Only
the lowest bytes matching the size property are used.
size uint32 Size of the memory write, either 1, 2, 4 or 8 bytes. If
the property is not present, the size is assumed to be 4
bytes.
mask uint64 Bitmask specifying which bytes should be changed. If the
property is not present, whole memory location is over-
written. If the property is present, the memory location is
read, masked with a one-complement of this mask and
ORed with the value property.
io_port uint32 This flag can be used to specify that the operation should
be performed on IO ports instead of MMIO. In that case,
size must not be 8 bytes and only the lower 16 bits of
addr are used. This flag is only supported on x86. If the
property is not specified, it is assumed to be false
Table 3: Memory operation properties
If any of the properties does not conform to the specification, the PSP will refuse to boot and print an error message. If console is available at the time when the IO sequencer runs (depends on the BSP), you can get verbose information about the operations performed by the IO sequencer by setting the UK_BOOT_MESSAGE kernel configuration parameter to Verbose boot. Unless noted otherwise in the corresponding PSP’s documentation, the IO sequencer configuration mechanism is supported by the PSP and the IO sequencer is run just after initializing the PSP console. As an example, the following snippet will configure the IO sequencer on x86 machines to write letter ’X’ to the serial port (assuming it is already configured).
<prop_dir name="board"> <prop_dir name="config"> <prop_dir name="io_seq"> <prop_dir name="0"> <prop_addr name="addr" data="0x3F8" /> <prop_uint64 name="value" data="0x58" /> <prop_uint32 name="size" data="1" /> <prop_bool name="io_port" data="true" />
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
18 PSPs
</prop_dir>
</prop_dir>
</prop_dir> </prop_dir>
3.4 Microcode Updater
The PSP allows loading a user-provided CPU microcode. The microcode updater supports both AMD and Intel CPUs.
3.4.1 Microcode Loading
The microcode updater reads file prop:psp/microcode/cpu.bin. This file can be chosen in the Integration project in the PSP component under the "Microcode update" option. It is parsed as both AMD and Intel microcode update format; the file format is the same as the one used in Linux. For AMD CPUs, please choose the appropriate mi- crocode_amd*.bin. For Intel CPUs, the file is inside the archive in the intel-ucode directory, with format FF-MO-PI (FF is family, MO is model, PI is platform identificator). An image containing more Intel microcode images can be created as follows:
cat /lib/firmware/intel-ucode/* > cpu.bin
Image for AMD CPUs can be created in a similar way:
cat /lib/firmware/amd-ucode/*.bin > cpu.bin
It is also possible to create a mixed image for both AMD and Intel CPUs:
cat /lib/firmware/intel-ucode/* /lib/firmware/amd-ucode/*.bin > cpu.bin
though there is a risk of misparsing of the file or microcode update failure. Please note that Intel microcode should come before the AMD microcode because it has stricter alignment requirements. The files can be obtained at: https://downloadcenter.intel.com/search?keyword=linux+microcode https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/tree/ amd-ucode If boot verbosity is set to at least 2, a message is printed when microcode update fails:
Updating microcode to revision 0x25, date 2018-04-02 Microcode update failed!
or when the microcode parser fails:
Microcode parse error at offset 27434
Please note that a failed microcode update might as well result in a CPU hangup or reset. If the microcode update fails, please retry with using only one specific file as the microcode update, instead of concatenating multiple files as shown above.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
PSP x86-64 19
3.4.2 CPU identification printout
The PSP also prints the CPU identification, including microcode revision and update status, if boot verbosity is set to at least 3:
Updating microcode to revision 0x25, date 2018-04-02 CPU vendor: GenuineIntel CPU name: Intel(R) Core(TM) i5-4590 CPU @ 3.30GHz CPUID: 0x306c3 CPU family: 0x6, model: 0x3c, stepping: 0x3 CPU platform ID [52:50]: 0x1 CPU microcode revision: 0x25
or, for AMD CPUs:
Updating microcode to revision 0x600063e, date 2018-02-07 CPU vendor: AuthenticAMD CPU name: AMD FX(tm)-6100 Six-Core Processor CPUID: 0x600f12 CPU family: 0x15, model: 0x1, stepping: 0x2 CPU microcode revision: 0x600063e
These messages are printed only for the first CPU. Please note the microcde date is read from the microcode image; some images are known to contain wrong or invalid date, such as 1896-00-07 and 2011-13-09. If the debug PSP is used, the PSP also verifies all the CPUs are using the same microcode revision.
3.5 PSP x86-64
3.5.1 The PSP Configuration
The PSP and kernel properties can be set within the PikeOS project through the project editor. The PSP specific properties are defined in this chapter. The common PSP properties are defined in the section 3.2, page 15. By default, the x86-64 PSP uses the VGA console as system console. You can change the configuration to use the serial console through the project editor.
Warning: Concurrent use of serial interface as system console and 8250 driver may result in unexpected behavior.
The PSP will print the BIOS provided interrupt routing layout, ACPI debug information, USB handoff information, memory information and CPU and topology information if the property p4/kernel/boot_messge is set at least to 3. To improve the determinism of C1 wakeup time the x86-64 PSP is automatically disabling the automatic C1E promotion on subset of recent Intel processors such as Core, Xeon or Atom series with code names Airmont, Broadwell, Cannon Lake, Gemini Lake, Goldmont, Haswell, Ivy Bridge, Kaby Lake, Nehalem, Sandy Bridge, Silvermont, Skylake and Westmere. Further board specific settings might be required for hard real-time determinism, please consult your board and BIOS vendor. You can also check the recommended BIOS settings - see section 3.5.6, page 29 for details.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
20 PSPs
3.5.2 PSP Specific Properties
Table 4 lists the supported PSP specific properties and their default values.
Path Type Default
psp/irq_routing uint32 3
This property allows control of the interrupt routing. Possible configurations are: 0, 1, 2, 3 (described in
section 3.5.5.3, page 26)
psp/smi_watchdog uint32 0
This property allows control of the SMI watchdog; see section 3.5.6, page 29 for details. Possible configura-
tions are: 0 - disabled, 1 - enabled
psp/usb_handoff uint32 1
This property controls the USB handoff functionality; see section 3.5.6, page 29 for details. Possible values
are: 0 - disabled, 1 - enabled
psp/msi_msix uint32 0
This property disables the MSI/MSI-X support. It is a flag composed of the following bits:
bit 0 - disable the MSI support on all devices,
bit 1 - disable the MSI-X support on all devices,
bit 2 - disable the MSI support on all devices which do not support the interrupt masking extension.
Possible values are:
0 - MSI/MSI-X enabled,
1 - MSI support disabled,
2 - MSI-X support disabled,
3 - MSI/MSI-X support disabled,
4 - disable MSI without interrupt masking support, etc ...
psp/tsc_apic_calib uint32 10
This property controls the TSC and local APIC timer calibration type and retries.
Following values are defined:
1 - Perform the PIT based calibration just once,
10 - Retry the PIT based calibration at most 10 times,
20 - Retry the PIT based calibration at most 20 times.
psp/tsc_disable uint32 0
This property enables or disables specific PSP features. Setting bit 0 will disable user access to the CPU
time stamp counter via the rdtsc or rdtscp instructions.
psp/cr4_mce uint32 2
This parameter enables Machine Check Exceptions (MCE) in the CPU control register CR4. The parameter
value 1 enables MCE, the value 2 disables MCE. If the parameter value is zero, PikeOS keeps the value of
CR4.MCE set up by BIOS.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
PSP x86-64 21
Path Type Default psp/acpi/dump_tables uint32 false This parameter enables printout of ACPI tables on PSP startup. The tables are printed to the PikeOS console in a format compatible with the ACPICA tool acpixtract.
psp/acpi/dsdt.dat uint32 empty string This parameter specifies path to a file. The file is stored in the ROM file system and overrides the ACPI DSDT table provided by BIOS.
psp/cpu_features_dis uint32 0 This parameter is a debug parameter designed to override detected CPU features bitmask passed in the PSP descriptor arch.cpu_features member. If any P4_X86_CPU_ bits are set, PSP won’t pass corresponding feature to the ASP. Please note that P4_X86_CPU_AMD, P4_X86_CPU_IN- TEL, P4_X86_CPU_PG1G, P4_X86_CPU_NX features cannot be overriden. Please consult the /opt/pikeos-D5.0/target/x86/amd64/include/kernel/p4kinfoarch.h file for the bitmask definitions.
psp/alt_features_dis uint32 0 This parameter is a debug parameter designed to override detected alternative features bit- mask passed in the PSP descriptor arch.alt_features member. If any P4_X86_ALT_ bits are set, PSP won’t pass corresponding feature to the ASP. Please note that most of the alternative feature bits have a separate option to control them. Please consult the /opt/pikeos-D5.0/target/x86/amd64/include/kernel/p4kinfoarch.h file for the bitmask definitions.
psp/pcicfg uint32 1 This property controls the PCI configuration space access method. Following values are defined: 0 - legacy PCI configuration space access through I/O ports 0xcf8/0xcfc, 1 - extended PCI configuration space access through MCFG, if available.
psp/meltdown_workaround uint32 0 This property allows control of the Meltdown mitigation. Possible configurations are: 0, 1, 2 (described in detail section A.10, page 83)
psp/spectre_v2_ibrs uint32 0 This property allows control of the Spectre variant 2 mitigation. Possible configurations are: 0, 1, 2 (described in detail section A.10, page 83)
psp/spectre_v2_ibpb uint32 0 This property allows control of the Spectre variant 2 mitigation. Possible configurations are: 0, 1, 2 (described in detail section A.10, page 83)
psp/spectre_v2_rsb_cpl uint32 0 This property allows control of the Spectre variant 2 mitigation. Possible configurations are: 0, 1, 2 (described in detail section A.10, page 83)
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
22 PSPs
Path Type Default
psp/spectre_v2_rsb_ctx uint32 0
This property allows control of the Spectre variant 2 mitigation. Possible configurations are: 0, 1, 2 (described
in detail section A.10, page 83)
psp/spectre_v2_rsba uint32 0
This property allows control of the Spectre variant 2 mitigation. Possible configurations are: 0, 1, 2 (described
in detail section A.10, page 83)
psp/spectre_lazy_fpu_clear uint32 0
This property allows control of the Spectre lazy FPU state restore mitigation. Possible configurations are: 0,
1, 2 (described in detail section A.10, page 83)
psp/spectre_v4_ssbd uint32 0
This property allows control of the Spectre variant 4 mitigation known as Speculative Store Bypass. Possible
configurations are: 0, 1, 2 (described in detail section A.10, page 83)
Table 4: x86-64 PSP specific properties with default values
3.5.3 PSP Console
The PSP supports the console over the serial interfaces, VGA text mode console or through the framebuffer console. Table 5 summarizes the possible console configurations depending on the configured property value.
psp/console/port property Output Device
0 Console disabled
1 Serial console on COM1
2 Serial console on COM2
64 Framebuffer or text mode console
Table 5: x86-64 possible console outut modes
The PSP console may be configured with the psp/console/port property as described in the section 3.2, page 15. The serial adapter 1 and serial adapter 2 mentioned in the PSP properties chapter are the legacy PC COM1 and COM2 serial UARTs. The graphical framebuffer or the text mode console selection depends on the boot strategy and presence of legacy VGA BIOS. For example, the UEFI boot strategies do not support the text mode console, as the VGA text mode is no longer available for the UEFI BIOS. Table 6 summarizes the text or graphical framebuffer options for the various boot strategies. For details please consult the respective chapter in the Notes column.
Boot Console Type Notes
strategy
elf textmode See section 4.10.1, page 38
grub textmode See section 4.10.1, page 38
grub2 textmode / framebuffer See section 4.4.5, page 34
isoboot textmode Forced by the configuration of GRUB2
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Boot Console Type Notes
strategy
raw textmode / framebuffer Depends on the multiboot2 tag value MULTI-
BOOT_TAG_TYPE_FRAMEBUFFER
qemu textmode See section 4.10.1, page 38
uefi64 framebuffer See section 4.10.2, page 38
Table 6: x86-64 text and framebuffer options
3.5.3.1 Serial console
The PSP assumes for COM1 the I/O port base 0x3f8 and IRQ 4. It is assumed that COM2 has I/O port base 0x2f8 and IRQ 3. The PSP serial console does not use the interrupt but the IRQ information is used by the serial drivers available with certain boards.
3.5.3.2 Text Mode Console
The PSP will use the legacy 80x50 VGA console if it was setup by the legacy prebooter (see section 4.10.1, page 38), or the multiboot2 capable bootloader passed the textmode information in the multiboot2 information structure.
3.5.3.3 Framebuffer Console
The framebuffer console can be used if MULTIBOOT_TAG_TYPE_FRAMEBUFFER was passed to the PSP via the multiboot2 information block. The PSP supports the linear framebuffer type of MULTIBOOT_FRAME- BUFFER_TYPE_RGB. The supported bits per pixel modes are with 15, 16, 24 or 32. The geometry of the framebuffer is derived from the tag information. The framebuffer type of MULTIBOOT_FRAMEBUFFER_TYPE_IN- DEXED or 8 bits per pixel mode is unsupported. The PSP will generate the VESA information block for the p4linux regardless of the PSP console settings (only for MULTIBOOT_FRAMEBUFFER_TYPE_RGB type). The frame buffer resolution and geometry can be setup by the bootloader. Some boot strategies can be configured to pass specific resolution to the bootloader. If GRUB2 is used, you can configure the desired framebuffer resolution. See section 4.4.5, page 34, which also provides information how to list and set the desired video mode using either the VESA BIOS Extensions (VBE) or the UEFI GOP extensions. The scrolling of the framebuffer console is not implemented as no hardware acceleration is available. The first line after the last active line drawn will be empty and will contain a cursor at the beginning of the line.
3.5.3.4 VESA Framebuffer
A support for the PSP VESA framebuffer mode setting (PSP_VESA_MODE kernel tag) has been removed and delegated to the bootloader. The framebuffer information structure is still generated, see section 3.5.3.3, page 23.
3.5.4 SMP
On x86, the SMP variants of the x86-64 PSP support systems with more than one processor. The PSP automati- cally starts all processors listed in the ACPI or MPS table provided by the BIOS.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
The PSP will print CPU topology information if the p4/kernel/boot_message property is set at least to 3, with the following CPU nn -> CPU xx:yy:zz format:
CPU 00 -> CPU 00:00:00 (APIC ID 0x00) CPU 01 -> CPU 00:01:00 (APIC ID 0x02) CPU 02 -> CPU 00:02:00 (APIC ID 0x04) CPU 03 -> CPU 00:03:00 (APIC ID 0x06) CPU 04 -> CPU 00:00:01 (APIC ID 0x01) CPU 05 -> CPU 00:01:01 (APIC ID 0x03) CPU 06 -> CPU 00:02:01 (APIC ID 0x05) CPU 07 -> CPU 00:03:01 (APIC ID 0x07)
Where nn is PikeOS ID, xx is package ID, yy is core ID, zz is hyperthread ID. The APIC ID is the CPU local APIC ID. In the example above can be seen that hyperthread CPUs are CPUs with PikeOS ID of 0,4 1,5 2,6 and 3,7. Such CPUs might share some resources with each other and influence real-time behavior. The kernel configuration property p4/kernel/num_cpu limits the number of processors used by the kernel. Processors are enumerated by their order in the ACPI or MPS table. The configuration property psp/cpu_mask provides a mechanism to override SMP detection and to enable only selected CPU threads. For each bit set in the mask, the according CPU thread is started at PSP boot. The bit number refers to the thread’s APIC ID. Depending on the APIC ID order, defined CPU threads can be enabled or disabled in the mask. For example, if the APIC IDs are assigned like in listed table 7.
APIC ID Thread Core Description
0 0 0 1st thread, 1st core
1 1 0 2nd thread, 1st core
2 0 1 1nd thread, 2nd core
3 1 1 2nd thread, 2nd core
Table 7: APIC ID for enabling and disabling threads on x86 SMP CPU
Setting PSP_CPU_MASK to 0x3 enables both threads of the first core, but setting it to 0x5 enables only one thread CPU on both cores. A setting of 0xf starts all four threads. The first thread of the first core should always be included in the mask. The exact setting for your board depends on the used processors and APIC IDs assigned by the BIOS.
3.5.5 Interrupt Handling
This chapter describes the details of the x86 external interrupt handling. If you are looking for the CPU exceptions, see section A.7, page 81 for details. The external interrupts sources are: A legacy interrupt controller (PIC), an advanced programmable interrupt controller (IO-APIC), the message signaled interrupts (MSI/MSI-X) and system management interrupt (SMI). Depending on what is available on the platform there are two main interrupt models. The older, PIC model uses two i8259 (PIC) controllers. The new model uses one or more IO-APIC controllers but legacy PIC controllers are still available. The PIC model relies on BIOS to setup the PCI IRQ routing, triggering and polarity of the IRQs. When the IO- APIC model is used, PCI IRQ routing and interrupt setup is obtained from ACPI, or from MP-Table whatever is available.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
PSP x86-64 25
The MSI/MSI-X interrupts are somewhat special. They are allocated at a run-time by the driver. They are delivered directly to the CPU, without using the PIC or IO-APIC. The SMI is a special platform interrupt which is transparent to the operating system. The last sub-chapter discusses the details. If possible the x86-64 PSP will try to honor the interrupt affinity requested by the PikeOS kernel. This behavior depends on which controller handles the interrupts. Please check the following sub-chapters for additional details. To list the IRQ of the PCI devices managed by the PCI Manager or change PCI Manager configuration, please refer to PikeOS User Manual, section 10.7, page 244. For an introduction to the PCI Manager and MSI, MSI-X related options, please refer to PikeOS User Manual, section 10.7, page 244.
3.5.5.1 PIC Interrupt Model
The PIC model utilizes the two cascaded 8259 interrupt controllers (also known as ISA interrupt controllers) on x86 based boards. As this interrupt architecture originates from 8-bit micro computers of the 1970s and 1980s, it does not provide support for multiprocessor systems. All interrupts are handled with the CPU 0, regardless of affinity of the actual thread waiting for an interrupt. The PIC interrupt controllers provide 16 interrupt lines with the following typical device assignments listed in table 8.
PikeOS IRQ ID Origin Can Attach Description
0 8259: IRQ 0 yes Legacy PIT System timer
1 8259: IRQ 1 yes Keyboard
2 8259: IRQ 2 no Interrupt cascading
3 8259: IRQ 3 yes serial 2
4 8259: IRQ 4 yes serial 1
5 8259: IRQ 5 yes PCI
6 8259: IRQ 6 yes floppy
7 8259: IRQ 7 yes parallel
8 8259: IRQ 8 yes RTC timer
9 8259: IRQ 9 yes PCI
10 8259: IRQ 10 yes PCI
11 8259: IRQ 11 yes PCI
12 8259: IRQ 12 yes PS/2 Mouse
13 8259: IRQ 13 yes FP error
14 8259: IRQ 14 yes IDE
15 8259: IRQ 15 yes IDE
Table 8: PIC interrupts and typical device assignments
PCI devices typically share interrupts in this scenario. BIOS is responsible to setup the INT register of each PCI device and set such PIC interrupt as level triggered. You should use DDK or PCI Manager services to obtain the particular PCI interrupt number. A x86-64 PSP will issue a warning if the INT register is not set or interrupt is not level triggered.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
26 PSPs
3.5.5.2 IO-APIC Interrupt Model
The x86-64 PSP uses the IO-APIC interrupt architecture by default if routing information is available. This interrupt architecture supports routing of interrupts to multiple processors and more than 16 interrupt sources. To setup the IO-APIC interrupt controller, the PSP requires interrupt routing information from the BIOS. For IO- APIC interrupts x86-64 PSP will honor the requested CPU affinity. The interrupts will be delivered on same CPU where is the respective thread waiting for an interrupt. However depending on the BIOS, some of the PikeOS legacy IRQ IDs 0 - 15 might be handled by the PIC and be delivered to CPU 0 only. The NMI interrupt from a southbridge is always delivered to the CPU 0. At system start-up, the PSP tries to enable ACPI mode and obtain information about PCI routing and then disable ACPI mode again. If this fails, the PSP searches for an MPS table (Multiprocessor Specification, version 1.1 or 1.4) in system memory. If this routing information is incomplete or unavailable, the PSP falls back to the legacy PIC interrupt model.
PikeOS IRQ ID Origin Can Attach Description
0 .. 15 8259: IRQ0 - IRQ15 or IO- yes, except Depending on the IRQ routing tables
APIC 0 pins 0 - 15 of IRQ2 (MPS/ACPI), either attached to 8259 or
to the first IO-APIC pins 0 - 15
16 .. 31 IOAPIC 0: pins 0 - 15 no Shadows of legacy ISA interrupts, 8259
IRQ 0 is routed to pin 0 or pin 2
32 .. 16 + N - 1 IOAPIC 0: pins 16 - N - 1 yes PCI interrupts, usually PIRQA - PIRQH
(chipset specific)
16 + N .. N + M - 1 IOAPIC 1: pin 0 - pin M - 1 yes PCI interrupts
16 + N + M .. 208 PCI MSI/MSI-X entries pro- yes Reserved for MSI/MSI-X interrupts
grammed by PikeOS PSP
Table 9: x86 IO-APIC interrupts usage and description
The actual number of interrupts handled by the IO-APIC infrastructure depends on the number of IO-APICs in the system and the number of interrupts that can be handled by specific IO-APICs (N: number of pins / interrupts of first IO-APIC, M: number of interrupts of second IO-APIC etc). The first 16 (ISA) interrupts are handled through the legacy 8259 controller, but if an ACPI or MP-Table has an redirection entry it will be transparently routed via IO-APIC. The interrupts above 17 depend on the particular IO-APICs used in the system. The common scenario is that interrupts 17-32 are IO-APIC shadow ISA interrupts (those are the redirection targets as mentioned above and are not user-attachable) and 33-40 are IO-APIC PCI/PCIe interrupts. The particular PCI device INT register is updated during PSP start-up with the corresponding PCI interrupt number used. However you should use DDK or PCI Manager services to obtain the particular PCI interrupt number.
3.5.5.3 Overriding Interrupt Routing Mode
Using the PSP property psp/irq_routing, the system integrator select the preferred IRQ routing method based on the property value listed in table 10.
Value Description
0 Legacy BIOS - Use legacy PIC interrupt model, use PCI interrupt numbers setup by
the BIOS
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
PSP x86-64 27
1 MP-Table - Use IO-APIC interrupt model, obtain IRQ routing information from MP-
Table otherwise fallback to the legacy BIOS routing mode
2 Custom MP-Table - Override interrupt routing with custom MPS table. The ROM
image must contain the custom MPS table in a file named MPTABLE.BIN in MPS
version 1.1 or 1.4 format.
3 (default) ACPI - Use IO-APIC interrupt model, obtain the IRQ routing information from the ACPI
tables otherwise fallback to MP-Table routing mode
Table 10: x86 overriding interrupt routing mode
3.5.5.4 Message Signaled Interrupts
Message Signaled Interrupt is an interrupt delivery mechanism introduced by the PCI/PCIe specification. It allows assigning an exclusive, non-shared interrupt to a PCI or a PCI Express device. MSI was introduced in the PCI 2.2 specification and MSI-X in the PCI 3.0 specification. PikeOS supports MSI/MSI-X interrupts for all x86 PSPs. The MSI/MSI-X API is available in the DDK and P4linux. For the single MSI and any MSI-X interrupts x86-64 PSP will honor the requested CPU affinity. The interrupts will be delivered on same CPU where is the respective thread waiting for an interrupt. The CPU is determined by the thread that waits for the first of the MSIs. CPU 0 is used if no thread waits for the first MSI. Various drivers already have configuration options to enable or disable the MSI/MSI-X for a particular device. If not, the generic way to disable MSI/MSI-X interrupts per device is documented in PikeOS User Manual, section 10.7, page 244. Alternatively the MSI/MSI-X can be globally selectively enabled or disabled via PSP configuration properties. For details see section 3.5.2, page 20.
3.5.5.4.1 MSI
PikeOS PCI design restricts the number of allocated MSI interrupts to a power of two (1, 2, 4, 8, 16, 32), but the PSP is limited to just one MSI per device (the MSI-X is not limited, there can be multiple MSI-X per device). The PSP will assign the target processor based on the thread attached to the MSI interrupt of a particular device. A further restriction stems from the fact that the original MSI specification did not provide any means to mask the device interrupts. This means that the PSP cannot mask the MSI interrupt and this interrupt remains unmasked even if there is no thread currently waiting for the interrupt. This is contrary to the PikeOS interrupt model where an interrupt is logically masked when any of its attached threads is not blocked waiting for the interrupt. The PSP implements a state machine which tracks if the MSI interrupt was triggered when it was logically masked and replays the event for the kernel when it is logically unmasked. Later revisions of the PCI specification introduced optional MSI masking support. This feature is supported by the PSP and in this case the expected device interrupt masking is performed (the virtual masking described above is omitted). The x86 PSP also supports the 64-bit version of the PCI MSI structure. The PSP supports up to 32 different MSI interrupts. MSI support and the support for devices without the MSI masking feature may be disabled globally with a custom PSP property, see section 3.5.2, page 20 for details. Disabling MSI support only for a specific PCI/PCIe device is possible via the PCI Manager configuration option, please refer to PikeOS User Manual, section 10.7, page 244.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
3.5.5.4.2 MSI-X
MSI-X is the evolution of MSI. It enables the use of up to 2048 interrupts, which may be used sparsely. The per-interrupt masking support is mandatory. The x86 PSP supports up to 32 different MSI-X interrupts. MSI-X support may be disabled globally with a PSP property, see section 3.5.2, page 20 for details. Disabling MSI-X support only for a specific PCI/PCIe device is possible via the PCI Manager configuration option, please refer to PikeOS User Manual, section 10.7, page 244.
3.5.5.5 System Management Interrupt
The x86 architecture defines a special non-maskable CPU mode named SMM for platform specific handling of certain events. The hardware platform can raise an SMI (System Management Interrupt) to enter SMM mode and execute a BIOS provided handler to act on the event. The SMI is non-maskable by the operating system and introduces uncontrollable latencies which harm real-time determinism. The following settings are recommended on Intel systems to disable additional sources of system management interrupt (SMI):
• Disable USB mouse and keyboard support in the BIOS.
• Disable additional USB devices, i.e. USB floppy boot.
• Disable Total Cost of Ownership (TCO) timer generation of SMIs.
For Intel based system, consult Intel document "323671" with a name "Designing Real-Time Solutions on Embed- ded Intel Architecture Processors". Further board specific settings might be required for hard real-time determinism, please consult your board and BIOS vendor. You can also check the recommended BIOS settings - see section 3.5.6, page 29 for details. If disabling of USB devices in BIOS is not desired for some reason, e.g. a USB device is used to boot up the system or USB keyboard is used for BIOS, the PSP USB handoff functionality (default on) will claim ownership of the USB controllers. After the handoff, USB controllers will no longer generate SMI and BIOS will not manage USB devices. To assist with an SMI problem an SMI watchdog is available in the x86-64 PSP. If an SMI is triggered, the watchdog will act on the next timer tick printing "SMI watchdog: SMI on CPU #0" and halting the system. The SMI watchdog may be activated with a PSP property described in the section 3.2, page 15. The watchdog is not available on every CPU, it uses certain counters found only in the subset of recent Intel processors like Core 7 series with code names Airmont, Annidale, Broadwell, Gemini Lake, Goldmont, Haswell, Ivy Bridge, Kaby Lake, Nehalem, Sandy Bridge, Silvermont, Skylake, Tangier, Westmere, Xeon and Xeon Phi series. If it is enabled on an unsupported CPU it will print "SMI watchdog: Unsupported CPU" during system startup. The TSC and local APIC timer calibration can be also influenced by the incoming SMI. The calibration type and the number of tries is controlled by the PSP property as described in the section 3.2, page 15. The PIT calibration loop monitors the maximum and minimum CPU clocks necessary for each loop iteration. If max and min value differ more than by factor of 10x, calibration is considered unsuccessful and it is restarted.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
PSP x86-64 29
3.5.6 Recommended BIOS Settings
This section discusses recommended BIOS settings that have an effect on real-time behavior and system config- uration. Please consult your board’s manuals how to access the BIOS configuration menu. Table 11 lists recommended BIOS settings for PikeOS. The names of the BIOS settings may differ between BIOS vendors.
Configuration Entry Setting Core Multiplexing Technology enabled (enables multicore) Hyperthreading enabled or disabled, depending on configuration if SMT shall be used, see section 3.5.4, page 23 CPU Execute Disable Bit enabled C1E state support disabled MPS version 1.4 Max CPUID value limit no or disabled Plug & Play OS installed no (full PCI setup) Intel VT technology enable (enables hardware virtualization) Intel VT-d enable (enables I/O MMU support) APM power management disable (source of additional SMIs)
Table 11: Recommended BIOS settings
3.5.7 Entry Point Validation
In the PSP there is a checks that the PSP code was entered on the _start address. The first instruction on this address writes a magic marker to the DR0 register. Later during startup it is verified that the DR0 contains this magic value. If the expected value is not found a message is printed on the console and the system is halted.
3.5.8 System Reset
The PSP performs several reset methods in the following order:
• try ACPI based reset - using ACPI specified reset register and reset register value
• try keyboard reset - using legacy keyboard controller reset (port 0x60/0x64)
• try ACPI based reset again
• try keyboard reset again
• try port 0xcf9 warm reset - only for Intel chipsets
• perform triple fault reset
When everything fails, the triple fault reset will force the CPU to generate a shutdown special cycle, which will be detected by southbridge and that will result in a system reset. The ACPI based reset method is performed only when ACPI IRQ routing is enabled (see section 3.5.5.3, page 26) and only when ACPI specified the reset port in its internal structures.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
30 PSPs
3.5.9 System Poweroff
The PSP will attempt to shutdown the system to ACPI S5 state (poweroff). If it fails, the system just halts. The ACPI based power off method is performed only when ACPI IRQ routing is enabled (see section 3.5.5.3, page 26) and only if the sleep registers and sleep values were specified by ACPI in its internal structures.
3.5.10 Multiboot2 Execution Environment
The x86-64 PSP expects that it will be started in accordance with the multiboot2 specification. The PSP expects that at least system memory map will be provided (tag MULTIBOOT_TAG_TYPE_MMAP). The PSP will use the MULTIBOOT_TAG_TYPE_ACPI_NEW or MULTIBOOT_TAG_TYPE_ACPI_OLD tags to obtain the ACPI RSDP pointer instead of legacy probing. If the selected PSP console is VGA, the MULTIBOOT_TAG_TYPE_FRAME- BUFFER is consulted to provide either the graphical frame buffer console, or the text mode console with specified geometry. If the MULTIBOOT_TAG_TYPE_FRAMEBUFFER is not present and VGA console is selected, the legacy VGA 80x25 textmode is assumed. The legacy multiboot1 is supported by certain boot strategies with a multiboot1 legacy prebooter. Refer to the section section 4, page 31 for the details.
3.5.11 BIOS Supplied Tables
Certain PSP features use information provided by the BIOS. The ACPI RSDP table pointer is either passed through the multiboot2 tag or legacy addresses are probed. The interrupt routing information is obtained through ACPI. If ACPI tables are missing, then MP-Table is searched, else legacy BIOS IRQ routing is used. In this case the BIOS is responsible for the setup of the INT register of each PCI device and set such PIC interrupts as level triggered. See section 3.5.5, page 24 for details. The SMP information are obtained from the ACPI MADT or MP-Table. If the ACPI MADT table is not found and there is no MP-Table, SMP is disabled.
3.5.12 IO Sequencer
The IO Sequencer is available in this PSP with the default prefix (board/config/io_seq) and is run after the initialization of serial and VGA console.
3.5.13 Limitations
The maximum amount of RAM PSP may use is limited by the number of physical address bits supported by the CPU and by the size of the supported kernel virtual address space (127 TiB). The amount of physically contiguous RAM available may be less than reported available RAM. The x86 BIOS creates a PCI memory hole in the low 4 GiB of the physical address space for compatibility reasons. Therefore a typical 4 GiB RAM system has about 3 GiB of RAM followed by 1 GiB of PCI hole. The last 1 GiB RAM starts at 4 GiB boundary. Setting the kernel property p4/kernel/boot_message to at least to 3 will force the PSP to print the BIOS provided memory map. The MSI (not MSI-X) is limited to the single MSI interrupt per device. For the PikeOS kernel x86 related architecture limitations see section A.12, page 88.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
4 Boot Strategies
Though x86 PCs are highly standardized, there exists a variety of boot strategies for those platforms, particularly in the embedded sector. Depending on the boot process used by the BIOS or firmware, the ROMimage must be transformed to a certain kind of boot image. Altogether, PikeOS supports several possible boot strategies and offers the corresponding configuration tools for them. The following sections describe the mode of functioning for the individual strategies, their advantages and drawbacks, as well as their typical areas of use.
Note: Not all boards support all of the boot strategies. For each board, the PikeOS project administration offers only those boot strategies that make sense. On recent UEFI BIOS based systems consider using boot strategy "uefi64" or "grub2" as neither of them depends on legacy BIOS features.
For further information on creating the ROMimage see the PikeOS User Manual .
4.1 Boot Strategies Summary
Various PikeOS boot strategies will prepend special prebooters which will supply the necessary information from legacy BIOS, UEFI BIOS or multiboot specification version 1. The prebooter particularities are described in more detail in the later chapters. Table 12 maps the boot strategy names to the output image format, supported PikeOS architectures, expected execution environment and a list of bootloaders known to support this boot strategy.
Boot Image Execution Bootloaders
Strategy Format Environment
elf ELF32 multiboot1 GRUB legacy, GRUB2, gpxe, ipxe, etherboot
or any multiboot1 compliant loader
multiboot1 ELF32 multiboot1 GRUB legacy, GRUB2, gpxe, ipxe, etherboot
or any multiboot1 compliant loader
multiboot2 ELF32 multiboot2 GRUB2 or any multiboot2 compliant loader
grub2 ELF32 multiboot2 GRUB2 or any multiboot2 compliant loader
diskimage ISO 9660, legacy/UEFI BIOS CD-ROM/DVD disc, harddrive or USB flash
MBR, GPT
qemu ISO 9660, legacy/UEFI BIOS QEMU with "-boot d" and "-cdrom" options
MBR, GPT
uefi64 PE64 UEFI 2.0+ UEFI X64 BIOS conforming to at least UEFI
version 2.0
Table 12: x86 boot strategies
The multiboot1 and multiboot2 specification specifies the execution environment and also a way how the system parameters are passed to the operating system. For the further details please check the respective specification located at:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
32 Boot Strategies
http://git.savannah.gnu.org/cgit/grub.git/tree/doc/multiboot.texi?h=multiboot http://git.savannah.gnu.org/cgit/grub.git/tree/doc/multiboot.texi?h=multiboot2. The section section 3.5.10, page 30 specifies PSP multiboot2 requirements. The PikeOS boot strategies do not support the legacy 16-bit "boot sector" style of loaders.
4.2 Integrity Check
The x86-64 PSP provides support for CRC32 checksum generation and checking on boot-up. This can be used to validate boot images that might get corrupted by the bootloader. This feature is on by default in the PSP configuration. Refer to the PSP properties (Section 3.2) on how to control this feature.
4.3 Boot strategy "multiboot2"
The "multiboot2" boot strategy produces a multiboot2 compliant ELF file, which can be loaded by any bootloader supporting multiboot2 environemnt.
4.4 Boot strategy "grub2"
The "grub2" boot strategy produces a multiboot2 compliant ELF file, which can be loaded by GRUB. The GRUB can be used for legacy BIOS boot as well as for the UEFI BIOS boot. In addition to "multiboot2" this boot strategy provides configuration script that can be used to ease the creation of GRUB configuration.
4.4.1 Legacy BIOS bootstrap under Linux
This section describes the GRUB boot on legacy systems. The GRUB can be installed on any devices such as HDDs, SSDs or USB flash disks. Before starting the GRUB installation, you have to connect the drive to the host system and create at least one partition for the ROMimage. The wild card "DISKDEV" is the device on the host computer, which stands for the target hard disk connected to your host. "PARTITIONDEV" represents the partition of your hard disk as connected to your host (e.g. /dev/sdb1 for the first partition on the second SCSI/SATA/USB device). Connect the drive to your host and optionally re-partition the disk. In the following example, fdisk tool is used to re-partition the disk and ext2 filesystem is then created on the selected partition:
sh# fdisk /dev/DISKDEV sh# mkfs.ext2 /dev/PARTITIONDEV
Now, install the GRUB bootloader and copy the "$PIKEOS_IMAGE" from the project boot/ directory to the partition on the target drive:
sh# mount /dev/PARTITIONDEV /mnt
sh# ${PIKEOS_PREFIX}/share/grub2/sbin/grub-install --target=i386-pc --no-floppy
--boot-directory=/mnt/boot /dev/DISKDEV
sh# cp ./boot/$PIKEOS_IMAGE /mnt/boot/pikeos.img
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Boot strategy "grub2" 33
The configuration of the GRUB boot menu is stored on the target filesystem in the file boot/grub/grub.cfg, create it with the following content:
set default=0 set timeout=2 menuentry "PikeOS" { multiboot2 /boot/pikeos.img }
You may need to add the set root=’hd0,msdos1’ statement to the menuentry to help GRUB locate the pikeos.img on the first hard drive and first partition. When done, unmount the filesystem:
sh# umount /mnt
GRUB installation does not have to be re-run if image files are overwritten or the configuration has been changed.
4.4.2 Legacy BIOS bootstrap under cygwin
Partition and format the target drive with FAT partition. Prepare the grub.cfg configuration file as described in the previous section. Install the GRUB bootloader and copy the "$PIKEOS_IMAGE" from the project boot/ directory to the partition on the target drive:
sh# ${PIKEOS_PREFIX}/share/grub2/sbin/grub-install --target=i386-pc --no-floppy
--boot-directory=/cygdrive/DISKDRIVE/boot/ /dev/DISKDEV
sh# cp ./boot/$PIKEOS_IMAGE /cygdrive/DISKDRIVE/boot/pikeos.img
The DISKDRIVE is a operating system drive, for example "e" for disk E:. Please consult the cygwin manual how to map the DISKDEV to the DISKDRIVE. The manual is located here: http://cygwin.com/cygwin-ug-net/using-specialnames.html Please note that by a default there is no partition created if a target USB drive (removable media) contains FAT filesystem.
4.4.3 UEFI BIOS bootstrap
You can produce an UEFI GRUB image under Linux and cygwin using the following command:
sh$ ${PIKEOS_PREFIX}/share/grub2/bin/grub-mkimage --format=x86_64-efi
--output=bootx64.efi --prefix=/boot multiboot multiboot2 part_msdos
part_gpt fat efi_gop normal
You need to install the resulting bootx64.efi either to the root directory of FAT formatted partition or to the EFI/BOOT directory. Store the GRUB configuration file grub.cfg in the BOOT/grub/ directory and PikeOS boot image in the BOOT/ directory.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
34 Boot Strategies
4.4.4 Using existing GRUB2
This section only applies if you try to boot PikeOS on a PC or development host that uses GRUB2 to load its default OS. If you need to install GRUB yourself follow the explanations in the sections above. To boot your PikeOS image via GRUB2 you need to follow these steps (as root):
• Copy the image (located in project_name/boot) to the directory containing grub images (usually /boot)
• Create a file in your GRUB2 script folder (usually /etc/grub.d) using an editor and add the following text:
#!/bin/sh -e
printf ’%s\n’ "menuentry \"PikeOS\" {"
printf ’\t%s\n’ "multiboot2 /boot/pikeos_image_name"
printf ’%s\n’ "}"
• Adjust the settings to your needs. In most cases you need to edit the PikeOS image name behind multiboot
• Name the file XX_PikeOS - replace the ’XX’ with a two digit number, e.g. ’99’. This number indicates in
which order the scripts will be parsed and therefore the position the entry will appear in your GRUB2 boot
list
• Grant the file execution rights e.g. ’chmod +x /etc/grub.d/99_PikeOS’
• Run ’grub-mkconfig’ followed by ’update-grub’ to update your GRUB2 configuration
Note: Changes done directly to ’/boot/grub/grub.cfg’ will be lost, if the configuration is updated - therefore it is not recommended to manually edit ’grub.cfg’
4.4.5 Configuring Text Mode or Framebuffer
The GRUB allows users to select the text or graphical mode for the payload generated with the "grub2" boot strategy by setting the "gfxpayload" variable. The boot strategy provides a script for creating the grub configuration. Predefined value in this script is taken from GRUB2_GFXPAYLOAD PSP parameter. The default setting is "text", which will select the text console if booted in legacy mode and will be changed to "auto" in the UEFI mode because UEFI does not support text mode. Other resolution can by configured by changing GRUB2_GFXPAYLOAD PSP parameter to the requested string or by manual grub configuration editing:
set default=0 set timeout=2 menuentry "PikeOS" { multiboot2 /boot/pikeos.img set gfxpayload=text }
In order to use the framebuffer console, make sure that GRUB has the "all_video" module loaded and optionally that the "videoinfo" module is also loaded. To list the supported video modes, invoke the following commands on the GRUB command line:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Boot strategy "diskimage" 35
set pager=1 insmod videoinfo videoinfo
For example, to configure the framebuffer to the 1024x768 mode with 32 bits per pixel using the VESA BIOS Extensions (VBE), use the following configuration:
set timeout=2 insmod all_video menuentry "PikeOS" { multiboot2 /boot/pikeos.img set gfxpayload=1024x768x32 }
Please note that the bits per pixel parameter can be omitted. The gfxpayload variable needs to be set after the multiboot2 command. For details please consult the GRUB manual. For more details about the supported framebuffer configurations see section 3.5.3.3, page 23. Note that UEFI environment does not support the text mode. If the text mode is requested by the GRUB2_GFX- PAYLOAD PSP a check for UEFI environment in XX_PikeOS_D5.0 configuration script. This check is performed during runtime of the grub2 bootloader and if UEFI environement detected the "text" mode is replaced with frame- buffer in "auto" mode.
4.5 Boot strategy "diskimage"
This boot strategy will produce the image that can be burned to an optical medium such as DVD or CD-ROM or written to a harddrive or USB flash. The image is according to ISO 9660 standard, following to El Torito Bootable CD Specification in harddisk emula- tion. This allows it to be booted if burned to a optical medium. Along with that here is a GPT table with protective MBR record, that allows booting if written on a media like USB flash or harddrive. Because of presence of both MBR and GPT the media can be booted either from Legacy or EFI BIOS. The image contains GRUB2 boot- loader that can be started with all the means described above. Once started GRUB2 prepares the multiboot2 environment for PikeOS and runs the PikeOS system itself.
4.5.1 Configuring Textmode or Framebuffer
As the diskimage boot strategy uses grub2 internally it allows a framebuffer configuration to be provided to PikeOS the same way as the grub2 boot strategy. For more details see section 4.4.5, page 34, which also provides information how to list and set the desired video mode. Note that UEFI environment does not support the text mode. If the image is started from UEFI BIOS and text mode is requested the framebuffer in "auto" mode is provided by grub instead. See section 4.4, page 32 for more details about the grub configuration is prepared.
4.6 Boot strategies "elf" and "multiboot1"
The "("elf) and "multiboot1" boot strategies generates a multiboot1 specification compliant ELF file, which can be loaded with various bootloaders including GRUB.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
36 Boot Strategies
In case of x86 platform the "elf" boot is equivalent to the "multiboot1". The "elf" strategy output binary format is commom for many platforms and this name is perserved for consistency reasons. On recent UEFI BIOS based systems use different boot strategy instead of legacy "elf" boot strategy, see section 4.10.1, page 38 for further details. The GRUB2 will be able to load multiboot1/elf image if the "multiboot2" keyword is replaced with "multiboot1".
menuentry "PikeOS" { multiboot /boot/pikeos.img }
For more details how to set up GRUB2 see section 4.4, page 32. The elf image format is widely supported by bootloders allowing booting over network. Following subsection discusses the way how to boot the image over network using such bootloaders. With a network bootstrap, the ROMimage is loaded from a server into the main memory of the embedded system via the network by means of the TFTP protocol. The server can for instance be an appropriately configured Linux workstation. Note: The examples assume that you have set up servers for TFTP and BOOTP already. This is explained in the PikeOS User Manual in section "Setting Up Network Servers".
4.6.1 Diskless Client with Etherboot/gPXE
If you have a network interface card with an empty socket for a boot PROM, you may want to try the free network boot loader Etherboot/gPXE. This is a free boot PROM software that can be configured for many types of network cards. Thus, you only need a matching PROM chip, a programmer and this software to enable your network card to boot PikeOS completely from the network. Etherboot/gPXE operates with a small boot loader, which retrieves via the network the considerably larger elf ROMimage. You can install the Etherboot/gPXE image on a floppy disk or USB stick, start it from boot loaders like GRUB, or chain load it via PXE. Please visit the web site http://rom-o-matic.net/. Here you find a web based tool for the configuration and the building of the boot loader binary. To generate a ROMimage suitable for Etherboot/gPXE select the "elf" boot strategy in the project configuration. After generating the ROMimage by typing
sh# make boot
you only need to copy the resulting image (boot/$PIKEOS_IMAGE) to your TFTP server’s download directory (usually /tftpboot) from where Etherboot/gPXE will retrieve it. More information can be found at http://www.etherboot.org/.
4.7 Boot strategy "uefi64"
This boot strategy may be used in the systems with UEFI BIOSes. The boot strategy generates an UEFI Appli- cation program which may be executed from the UEFI BIOS. It can be executed either from UEFI shell or from any BIOS supported boot device. Some UEFI BIOSes might require the boot file to have .EFI file extension. If
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Prebooters and Bootloaders 37
it is going to be installed on a disk media, place the resulting UEFI application renamed to BOOTX64.EFI to the EFI/BOOT directory of FAT formatted partition. This boot strategy uses a prebooter, for more information about expected system environment please check section 4.10.2, page 38. The vast majority of UEFI BIOSes are 64-bit, therefore "uefi64" should be used even if the 32-bit PikeOS is going to be used. If this image is signed with 3rd party tool it can be used with secureboot.
4.8 Boot strategy "qemu"
This is the boot strategy to be used with the qemu system. The resulting file is an ISO image that is expected to be booted from emulated CD-ROM with the "-cdrom boot/" and "-boot d" parameters of qemu. If needed the resulting boot image can be booted same way as the one produced by diskimage strategy. The integration project is evaluated and command line parameters for running qemu system are stored in "boot/qemu_cmdline" in the integration project directory. If the integration project contains USB, ethernet or AHCI controller driver, the parameters to set up emulation of these devices will be added too. The qemu boot strategy uses grub2 internally and thanks to this it allows a framebuffer configuration to be provided to PikeOS the same way as for the grub2 boot strategy. For more details see section 4.4.5, page 34, which also provides information how to list and set the desired video mode.
4.9 Raw pikeos binary
If there is a need for a raw PikeOS binary, e.g. if hardware debugger is used to load the image directly to the memory, the pikeos.boot file stored in the integration project directory can be used. This file is created by all boot strategies during compilation of the integration project.
4.10 Prebooters and Bootloaders
As noted above, the various boot strategies may use special preboot programs which will collect the system information. Table section 13, page 37 summarizes the usage of "legacy" and "UEFI" prebooters and GRUB2 boot loader with different boot strategies.
Boot Prebooter
strategy
elf legacy
multiboot1 legacy
multiboot2 none
grub2 none
diskimage grub2
qemu grub2
uefi64 UEFI
Table 13: prebooters and bootloader
Both preboot programs will transform the needed system information to the multiboot2 information structure and pass it to the PSP.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
38 Boot Strategies
4.10.1 Legacy Prebooter
The legacy prebooter is prepended to the PikeOS ROMimage and a multiboot 1.0 compliant ELF image is created. The legacy prebooter obtains the BIOS memory map using BIOS interrupt 0x15 mechanism. The multiboot1 memory information is not considered, as there are too many buggy bootloaders. The prebooter will set the 80x50 legacy VGA mode regardless of the current PSP console settings. However, if the multiboot1 information structure contains MULTIBOOT_FRAMEBUFFER_TYPE_RGB it will pass the framebuffer information to the PSP without changing the mode. Table 14 summarizes the BIOS calls performed by the legacy prebooter.
BIOS BIOS Service Usage
Interrupt
0x15 0xe820 Obtain the usable RAM map
0x15 0xe801 Obtain the usable RAM map, if e820h is not available
0x15 0x8800 Obtain the usable RAM map, if e801h is not available
0x10 0x0003 Used to set VGA 80x25 text mode
0x10 0x1112 Used to set VGA 80x50 text mode
Table 14: Legacy prebooter BIOS calls
The ACPI or MP-Tables will be searched by the PSP in the legacy address ranges. The recent UEFI BIOS based systems might be slightly incompatible with the legacy BIOS features mentioned above. Consider using "uefi64" or "grub2" boot strategies, which do not depend on a legacy BIOS features.
4.10.2 UEFI Prebooter
The UEFI prebooter is linked with the PikeOS ROMimage, and PE executable UEFI version 2.0 or later is created. The final image is 64-bit PE executable. The UEFI prebooter obtains the memory map using the UEFI Boot Services. If EFI_GRAPHICS_OUTPUT_PRO- TOCOL (GOP) is available the framebuffer information is passed to the PSP. If there are multiple GOP protocols installed, either the first one is used, or the one which also implements the console output protocol. The UEFI prebooter will pass the ACPI RSDP pointer to the PSP if such information is found in the EFI configura- tion table. The instruction on the entry point address of UEFI prebooter writes a magic value to the DR1 register, that can be later during PSP startup used to verify that the prebooter code was entered on the expected address. This check requires a custom build PSP with the PREBOOT_GNUEFI_CHECK macro enabled or some other way to check the DR1 register content.
4.10.3 GRUB2 as Prebooter
GNU GRUB (short for GNU GRand Unified Bootloader) is a bootloader from GNU Project. In it’s version 2 (reffered as GRUB2) it is a versatile boot loader that can be used in various environments (e.g. Legacy or UEFI BIOS, El Torito ISO 9660, ...) to start the Pike OS system. The common ways of using PikeOS with GRUB are described in section 4.4, page 32.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Prebooters and Bootloaders 39
The diskimage and boot strategies incorporates GRUB Version 2 to prepare the environment and start the multi- boot2 PikeOS image. GRUB is used as a standalone aplication that is stored together with the PikeOS binary on the ISO 9660 image, or can be stored and set up on the hard drive of the target system to boot the PikeOS.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
5 Drivers
5.1 Serial Drivers
5.1.1 Serial 8250
PikeOS provides a serial driver for use with 8250 controllers. The 8250 serial driver uses the driver development environment with the Serial Driver High Level Module (see PikeOS Device Driver Programming Reference Manual, section 9, page 412). Please refer to the PikeOS Device Driver Programming Reference Manual, section 8.5, page 409 for details about the serial class driver configuration and PikeOS Device Driver Programming Reference Manual, section 8.4, page 395 for description of the interface between driver and client. The 8250 driver is provided in two versions - user level (external file provider) and kernel level.
5.1.1.1 Driver Specific Configuration Parameters
In addition to the standard parameters defined for serial drivers by the driver framework, the 8250 serial driver has three specific configuration parameters. The access to the 8250 registers is always 8-bit. However, on some platforms the registers are not located in con- secutive bytes. Instead, there is a certain spacing between the registers. On such platforms, the "reg_multiplier" parameter can be used to select the spacing, in bytes, including the 8-bit register itself. If the "reg_multiplier" is greater than one byte and the system is big-endian, then the correct location of the 8- bit 8250 register can be selected using the "address_swap_mask" parameter, which XORs the intended register address with the mask. The addresses are assumed to be little endian.
Property pathnames are relative to the subdirectory prop:config/provider//priv/io/. The default value is used if the property is not present. If the property is present but cannot be read or is of the wrong type, this is treated as an error. Property Pathname Property Type Description Default Value address_swap_mask prop_uint32 Address swap mask remaps the address of regis- 0 ter location. The value is XORed with the actual register address. reg_multiplier prop_uint32 Register multiplier denotes the size of one 8250 1 register in bytes sampling_rate prop_uint32 Oversampling Rate, depends on particular UART 16 chip
5.1.1.2 Driver IOCTL Commands
The DRV_SER_IOCTL_SET_COMM command is used to set port communication parameters. When calling this command, the 8250 driver resets the UART and the RS232 signals to a default state.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Serial Drivers 41
The following signals can be set with the DRV_SER_IOCTL_SET_SIGNAL command and read back with the DRV_SER_IOCTL_GET_SIGNAL command:
• DRV_SER_SIGNAL_LOOP
• DRV_SER_SIGNAL_OUT1
• DRV_SER_SIGNAL_RTS
• DRV_SER_SIGNAL_DTR
Warning: When hardware flow control is enabled it is not possible to set RTS signal.
Note: Since on some platforms is used OUT2 signal for enabling interrupts it is not possible to set this signal.
Additionally the following signals can be read with the DRV_SER_IOCTL_GET_SIGNAL command:
• DRV_SER_SIGNAL_CTS
• DRV_SER_SIGNAL_DCD
• DRV_SER_SIGNAL_RI
• DRV_SER_SIGNAL_DSR
5.1.1.3 Driver Specific Limitations
The 8250 serial driver has the following limitations:
• The driver only supports one logical device per I/O device.
5.1.1.4 User Level Driver
The user level version of the driver is provided by the module
/opt/pikeos-D5.0/target/x86/amd64/driver/object/8250.elf
and the corresponding configuration file is
/opt/pikeos-D5.0/target/x86/amd64/driver/serial/8250.dom
The dom file adds the driver to the service partition, instantiates a single serial port, associating it with the COM1 I/O device. The port communication parameters are defaulted to 115200,8N1, no handshake. It has no dependencies. In CODEO, the 8250 driver can be added to an integration project using the Add... button. Browse to PIKEOS_POOL->driver->serial and select 8250 Serial User Level Driver. In a configuration script, the 8250 driver can be added to an integration project with the line
add PIKEOS_POOL driver/serial/8250.dom
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
42 Drivers
5.1.1.5 Kernel Level Driver
The use the kernel lever version of the 8250 driver, the following steps are needed:
• Using a kernel fusion project, create a new kernel linked with the driver
• Configure the integration project to use this new kernel
• Add the driver configuration to the integration project
5.1.1.5.1 Kernel Fusion Project
The kernel level version of the driver is provided by the module
/opt/pikeos-D5.0/target/x86/amd64/fusion-kernel/object/kerneldriver/8250/8250.kdev
and the corresponding configuration file is
/opt/pikeos-D5.0/target/x86/amd64/fusion-kernel/kerneldriver.cmp
To add the driver to a kernel fusion project using CODEO:
• Create a new PikeOS project, of type Kernel Fusion. From the list of demo projects, select the kernel
corresponding to the board used in the integration project. Please refer to the Appendix for the list of
kernels.
• Set the custom pool. The kernel fusion project should use the same pool as the integration project.
• Select the base component and click the Add... button.
• Browse to PIKEOS_POOL->fusion-kernel->kerneldriver. Click OK, Finish. Save the project.
• Execute the all and install Make targets.
The new kernel should now be installed under the object/bsp directory in the custom pool.
5.1.1.5.2 Configuring the Integration Project
The new kernel created in the fusion project and the kernel driver configuration must be added to the integration project. The kernel driver property based configuration is provided by the file
/opt/pikeos-D5.0/target/x86/amd64/driver/serial/8250_kdev.dom
Alternatively, it is possible to use the binary configuration file
/opt/pikeos-D5.0/target/x86/amd64/driver/serial/8250/8250_prov_kdev.cmp
Using CODEO:
• Open the integration project in the project editor (open the project.xml file).
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Ethernet Drivers 43
• Set the custom pool. The integration project should use the same pool as the kernel fusion project.
• Select the PikeOS Kernel element inside the board component.
• In the parameter section labelled Kernel Binary, set the Kernel Directory to Custom Pool.
• Select the board component and click the Add... button.
• Browse to PIKEOS_POOL->driver->serial->8250 Serial Kernel Level Driver. Click OK, Finish.
• Configure the driver. The driver supports up to four devices. By default, the first device is enabled. Other
devices are enabled by setting the Number of devices parameter. For each device, configure the I/O settings
to match the board.
• Save the project.
• Execute the boot Make target.
5.2 Ethernet Drivers
5.2.1 Ethernet e1000
PikeOS provides a multi-channel Ethernet driver which allows usage of the Intel e1000 family Ethernet controller from different applications simultaneously. When available, the driver gives preference to use of MSI-X or MSI over legacy interrupt signaling, with automatic fallback. The e1000 Ethernet driver uses the PikeOS driver development environment with the Network Driver High Level Module. Please refer to the PikeOS Device Driver Programming Reference Manual
• section 11, page 488 for Network Driver High Level Module documentation
• section 10.5, page 486 for details about the network class driver configuration
• section 10.4, page 466 for description of the interface between driver and client
By default, the driver can be accessed through the following filenames:
• "eth0:dev0" for the physical device
• "eth0:0" for virtual channel 0
• "eth0:1" for virtual channel 1
• "eth0:2" for virtual channel 2
• "eth0:3" for virtual channel 3
The Ethernet driver is provided by the module:
/opt/pikeos-D5.0/target/x86/amd64/driver/object/e1000.elf
The corresponding driver configuration files are:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
44 Drivers
• The domain file, instantiating and configuring the base driver configuration component,the physical device
componenent and 4 virtual channel components, and overloading default configuration parameters when
needed:
/opt/pikeos-D5.0/target/x86/amd64/driver/ethernet/e1000.dom
• The driver component files giving the driver configuration and data structure:
/opt/pikeos-D5.0/target/x86/amd64/driver/ethernet/e1000/e1000-fp_ext.cmp
/opt/pikeos-D5.0/target/x86/amd64/driver/ethernet/e1000/e1000-device.cmp
/opt/pikeos-D5.0/target/x86/amd64/driver/config/hlnet/hlnet-vchan.cmp
The Ethernet driver can be added using Add... button. Select Ethernet type and select e1000 Ethernet User Level Driver. The driver provides a single device and 4 virtual channels which can be independently configured.
Note: In order to restore a previously deleted driver group. It is recommended to use Restore Child... function from the BSP group context menu rather then the Add... button. The items will be restored with the BSP configuration preserved.
Warning: Note that the use of the physical device and the use of the virtual channels are exclusive. When using virtual channels, the physical device shall not be used, and vice versa.
5.2.1.1 Driver Base Configuration
These configuration parameters are the most generic configuration parameters. They allow configuration of:
• Driver Process:
Process Name: Default: e1000
Provider Name: Default: eth0
• Diagnostics: Allows the user to configure the BASE class diagnostics parameters (described in PikeOS
Device Driver Programming Reference Manual)
• Provider Resources: Allows the user to configure the CHAR class parameters (described in PikeOS Device
Driver Programming Reference Manual)
Note: The Maximum Transfer Size can be increased to support jumbo frames (view section 5.2.1.5).
5.2.1.2 Physical Device Configuration
The device configuration is done in 3 generic steps:
• Generic Device Configuration:
Device Name: Device name used to identify the logical device in the configuration. Default:0.
File name: The file name used by client applications to access the logical device. Default: dev0
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Ethernet Drivers 45
Access Mode: The access mode supported on the device. Can be: Read Only (RD_ONLY ), Write
Only (WR_ONLY ) or both (RD_WR). Default: RD_WR
Shared Device: If set to true, multiple concurrent opens on the device are supported. Default: false
Read Timeout: Timeout mode for read requests. Can be: Non-blocking, User Value or Infinite.
Default: Infinite
Read Timeout Value: If Read Timeout is set to User Value, this parameter is the PikeOS timeout
value (in nanosecond) for read requests. Default: 1000000
Write Timeout: Timeout mode for write requests. Default: Infinite
Write Timeout Value: If Write Timeout is set to User Value, this parameter is the PikeOS timeout
value (in nanosecond) for write requests. Default: 1000000
• Ethernet Device Configuration:
MBUF pool size: Number of mbufs in the pool. buffer. Default: 512
MAC Address: Channel MAC address. If set to 00:00:00:00:00:00, the high level layer of the driver
automatically retrieves the MAC address from the hardware EEPROM memory. If the hardware value
is still 00:00:00:00:00:00, the driver raises an error. Default: 00:00:00:00:00:00
Receive queue depth: Number of packets in the receive queue. Default: 64
Send queue depth: Number of packets in the send queue. Default: 64
Enable Multicast Communication: Enable Ethernet multicast communication for this device. Default:
false.
Multicast Table Size: Number of entries in multicast table. One entry in the table equals one multicast
MAC address. Default: 128
5.2.1.3 BSP Configuration / PCI Device Configuration
• PCI Device Location: Selects the PCI device location. For more information about the possible ways how to express the PCI device location please refer to PikeOS User Manual, section 10.7, page 244. Default: byclass/020000/0000 (First instance of Ethernet PCI Class).
• MSI Support: Enables or disables MSI interrupt support. Default: enabled.
• MSI-X Support: Enables or disables MSI-X interrupt support. Default: enabled.
5.2.1.4 Virtual Channel Configuration
The Virtual Channel (VC) configuration is a generic configuration repeating 3 steps of the device configuration:
• Virtual Channel: As for the Device configuration, this configuration group is used to configure properties file name and provided file name.
• Channel Configuration: Used for configuring the VC MAC Address, the Receive/Send queues depth in terms of packet number. Default: (00:00:00:00:00:00, 32, 32).
Warning: The VC MAC Address default value (00:00:00:00:00:00) is used by the high level layer of
the driver as a flag to automatically compute and provide the VC MAC Address, the value of the MAC
Address being accessible by ioctl.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
46 Drivers
• Multicast Communication: Used for enabling and configuring the Multicast feature of the VC. Default: (false,
32)
5.2.1.5 Maximum Transfer Size Configuration
The Maximum Transfer Size can be increased to support jumbo frames. The Maximum Transmission Unit (MTU) is calculated using this value minus the Ethernet frame header and the VLAN encapsulation (18+4 bytes). The default value of Maximum Transfer Size is 1522 (1500+18+4) to support standard Ethernet frames but the driver can support an MTU of up to 8192.
Warning: The supported Maximum Transer Size depends on hardware and driver limitations. Some devices will support 8KB jumbo frames and others will be limited to 4KB or standard 1522 bytes. An health monitor event will be raised during driver initialization if the configured size is not supported for the device.
To support 8KB jumbo frames, the Maximum Transfer Size must be configured to 8192 and the Heap Memory Size must be set to 0x800000 (with the default number of 512 mbufs in the pool).
5.2.1.6 Driver Specific Limitations
The e1000 network driver has the following limitations:
• Only support one Ethernet device per driver module.
• Only available as External File Provider Driver.
• Dependency on PCI Manager
5.2.2 Ethernet Realtek RTL
PikeOS provides a multi-channel Ethernet driver which allows usage of the Realtek RTL8111x, RTL8110x and RTL8169x based Ethernet controller from different applications simultaneously. When available, the driver gives preference to use of MSI-X or MSI over legacy interrupt signaling, with automatic fallback. The rtl Ethernet driver uses the PikeOS driver development environment with the Network Driver High Level Module. Please refer to the PikeOS Device Driver Programming Reference Manual
• section 11, page 488 for Network Driver High Level Module documentation
• section 10.5, page 486 for details about the network class driver configuration
• section 10.4, page 466 for description of the interface between driver and client
By default, the driver can be accessed through the following filenames:
• "eth0:dev0" for the physical device
• "eth0:0" for virtual channel 0
• "eth0:1" for virtual channel 1
• "eth0:2" for virtual channel 2
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Ethernet Drivers 47
• "eth0:3" for virtual channel 3
The Ethernet driver is provided by the module:
/opt/pikeos-D5.0/target/x86/amd64/driver/object/rtl.elf
The corresponding driver configuration files are:
• The domain file, instantiating and configuring the base driver configuration component,the physical device componenent and 4 virtual channel components, and overloading default configuration parameters when needed:
/opt/pikeos-D5.0/target/x86/amd64/driver/ethernet/rtl.dom
• The driver component files giving the driver configuration and data structure:
/opt/pikeos-D5.0/target/x86/amd64/driver/ethernet/rtl/rtl-fp_ext.cmp
/opt/pikeos-D5.0/target/x86/amd64/driver/ethernet/rtl/rtl-device.cmp
/opt/pikeos-D5.0/target/x86/amd64/driver/config/hlnet/hlnet-vchan.cmp
The Ethernet driver can be added using Add... button. Select Ethernet type and select RTL Ethernet User Level Driver. The driver provides a single device and 1 virtual channel. More virtual channels can be added which can be independently configured.
Note: In order to restore a previously deleted driver group. It is recommended to use Restore Child... function from the BSP group context menu rather then the Add... button. The items will be restored with the BSP configuration preserved.
Warning: Note that the use of the physical device and the use of the virtual channels are exclusive. When using virtual channels, the physical device shall not be used, and vice versa.
5.2.2.1 Driver Base Configuration
These configuration parameters are the most generic configuration parameters. They allow configuration of:
• Driver Process:
Process Name: Default: rtl
Provider Name: Default: eth0
• Diagnostics: Allows the user to configure the BASE class diagnostics parameters (described in PikeOS Device Driver Programming Reference Manual)
• Provider Resources: Allows the user to configure the CHAR class parameters (described in PikeOS Device Driver Programming Reference Manual)
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
48 Drivers
5.2.2.2 Physical Device Configuration
The device configuration is done in 3 generic steps:
• Generic Device Configuration:
Device Name: Device name used to identify the logical device in the configuration. Default:0.
File name: The file name used by client applications to access the logical device. Default: dev0
Access Mode: The access mode supported on the device. Can be: Read Only (RD_ONLY ), Write
Only (WR_ONLY ) or both (RD_WR). Default: RD_WR
Shared Device: If set to true, multiple concurrent opens on the device are supported. Default: false
Read Timeout: Timeout mode for read requests. Can be: Non-blocking, User Value or Infinite.
Default: Infinite
Read Timeout Value: If Read Timeout is set to User Value, this parameter is the PikeOS timeout
value (in nanosecond) for read requests. Default: 1000000
Write Timeout: Timeout mode for write requests. Default: Infinite
Write Timeout Value: If Write Timeout is set to User Value, this parameter is the PikeOS timeout
value (in nanosecond) for write requests. Default: 1000000
• Ethernet Device Configuration:
MBUF pool size: Number of mbufs in the pool. buffer. Default: 512
MAC Address: Channel MAC address. If set to 00:00:00:00:00:00, the high level layer of the driver
automatically retrieves the MAC address from the hardware EEPROM memory. If the hardware value
is still 00:00:00:00:00:00, the driver raises an error. Default: 00:00:00:00:00:00
Receive queue depth: Number of packets in the receive queue. Default: 64
Send queue depth: Number of packets in the send queue. Default: 64
Enable Multicast Communication: Enable Ethernet multicast communication for this device. Default:
false.
Multicast Table Size: Number of entries in multicast table. One entry in the table equals one multicast
MAC address. Default: 128
5.2.2.3 BSP Configuration / PCI Device Configuration
• PCI Device Location: Selects the PCI device location. For more information about the possible ways how
to express the PCI device location please refer to PikeOS User Manual, section 10.7, page 244. Default:
byclass/020000/0000 (First instance of Ethernet PCI Class).
• MSI Support: Enables or disables MSI interrupt support. Default: enabled.
• MSI-X Support: Enables or disables MSI-X interrupt support. Default: enabled.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Ethernet Drivers 49
5.2.2.4 Virtual Channel Configuration
The Virtual Channel (VC) configuration is a generic configuration repeating 3 steps of the device configuration:
• Virtual Channel: As for the Device configuration, this configuration group is used to configure properties file
name and provided file name.
• Channel Configuration: Used for configuring the VC MAC Address, the Receive/Send queues depth in
terms of packet number. Default: (00:00:00:00:00:00, 32, 32).
Warning: The VC MAC Address default value (00:00:00:00:00:00) is used by the high level layer of
the driver as a flag to automatically compute and provide the VC MAC Address, the value of the MAC
Address being accessible by ioctl.
• Multicast Communication: Used for enabling and configuring the Multicast feature of the VC. Default: (false,
32)
Note: While the driver supports an arbitrary number of virtual channels, the underlying hardware supports only one physical address. If multiple virtual channels are used, the network controller is forced to run in promiscuous mode.
5.2.2.5 Driver Specific Limitations
The rtl network driver has the following limitations:
• Only support one Ethernet device per driver module.
• Only available as External File Provider Driver.
• Only supports multiple virtual channels in a promiscuous mode.
• Dependency on PCI Manager
5.2.3 Ethernet virtio-net
PikeOS provides a multi-channel Ethernet driver which allows usage of the virtio-net virtual Ethernet controller from different applications simultaneously. The virtio-net Ethernet driver uses the PikeOS driver development environment with the Network Driver High Level Module. Please refer to the PikeOS Device Driver Programming Reference Manual
• section 11, page 488 for Network Driver High Level Module documentation
• section 10.5, page 486 for details about the network class driver configuration
• section 10.4, page 466 for description of the interface between driver and client
By default, the driver can be accessed through the following filenames:
• "eth0:dev0" for the physical device
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
50 Drivers
• "eth0:0" for virtual channel 0
• "eth0:1" for virtual channel 1
• "eth0:2" for virtual channel 2
• "eth0:3" for virtual channel 3
The Ethernet driver is provided by the module:
/opt/pikeos-D5.0/target/x86/amd64/driver/object/virtio-net.elf
The corresponding driver configuration files are:
• The domain file, instantiating and configuring the base driver configuration component,the physical device
componenent and 4 virtual channel components, and overloading default configuration parameters when
needed:
/opt/pikeos-D5.0/target/x86/amd64/driver/ethernet/virtio-net.dom
• The driver component files giving the driver configuration and data structure:
/opt/pikeos-D5.0/target/x86/amd64/driver/ethernet/virtio-net/virtio-net-fp_ext.cmp
/opt/pikeos-D5.0/target/x86/amd64/driver/ethernet/virtio-net/virtio-net-device.cmp
/opt/pikeos-D5.0/target/x86/amd64/driver/config/hlnet/hlnet-vchan.cmp
Note: This component includes a BSP Settings option node, allowing to configure BSP specific param-
eters. On ARM architectures, the configuration must be done manually by specifying the memory region
and IRQ used by the device (consult the respective BSP documentation). On other architectures, virtual
PCI is used - BSP Settings allow specifying the PCI device for the device to attach to.
The Ethernet driver can be added using Add... button. Select Ethernet type and select VirtIO Ethernet User Level Driver. The driver provides a single device and 4 virtual channels which can be independently configured.
Note: In order to restore a previously deleted driver group. It is recommended to use Restore Child... function from the BSP group context menu rather then the Add... button. The items will be restored with the BSP configuration preserved.
Warning: Note that the use of the physical device and the use of the virtual channels are exclusive. When using virtual channels, the physical device shall not be used, and vice versa.
5.2.3.1 Driver Base Configuration
These configuration parameters are the most generic configuration parameters. They allow configuration of:
• Driver Process:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Ethernet Drivers 51
Process Name: Default: virtio-net
Provider Name: Default: eth0
• Diagnostics: Allows the user to configure the BASE diagnostics parameters (described in PikeOS Device Driver Programming Reference Manual)
• Provider Resources: Allows the user to configure the CHAR class parameters (described in PikeOS Device Driver Programming Reference Manual)
Note: The Maximum Transfer Size can be increased to support jumbo frames (view section 5.2.3.4).
5.2.3.2 Physical Device Configuration
The device configuration is done in 3 generic steps:
• Generic Device Configuration:
Device Name: Device name used to identify the logical device in the configuration. Default:0.
File name: The file name used by client applications to access the logical device. Default: dev0
Access Mode: The access mode supported on the device. Can be: Read Only (RD_ONLY ), Write
Only (WR_ONLY ) or both (RD_WR). Default: RD_WR
Shared Device: If set to true, multiple concurrent opens on the device are supported. Default: false
Read Timeout: Timeout mode for read requests. Can be: Non-blockig, User Value or Infinite. Default:
Infinite
Read Timeout Value: If Read Timeout is set to User Value, this parameter is the PikeOS timeout
value (in nanosecond) for read requests. Default: 1000000
Write Timeout: Timeout mode for write requests. Default: Infinite
Write Timeout Value: If Write Timeout is set to User Value, this parameter is the PikeOS timeout
value (in nanosecond) for write requests. Default: 1000000
• Ethernet Device Configuration:
MBUF pool size: Number of mbufs in the pool. buffer. Default: 512
MAC Address: Channel MAC address. If set to 00:00:00:00:00:00, the high level layer of the
driver automatically retrieves the MAC address from qemu defaults. If the hardware value is still
00:00:00:00:00:00, the driver raises an error. Default: 00:00:00:00:00:00
Receive queue depth: Number of packets in the receive queue. Default: 64
Send queue depth: Number of packets in the send queue. Default: 64
Enable Multicast Communication: Enable Ethernet multicast communication for this device. Default:
false.
Multicast Table Size: Number of entries in multicast table. One entry in the table equals one multicast
MAC address. Default: 128
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
52 Drivers
5.2.3.3 Virtual Channel Configuration
The Virtual Channel (VC) configuration is a generic configuration repeating 3 steps of the device configuration:
• Virtual Channel: As for the Device configuration, this configuration group is used to configure properties file
name and provided file name.
• Channel Configuration: Used for configuring the VC MAC Address, the Receive/Send queues depth in
terms of packet number. Default: (00:00:00:00:00:00, 32, 32).
Warning: The VC MAC Address default value (00:00:00:00:00:00) is used by the high level layer of
the driver as a flag to automatically compute and provide the VC MAC Address, the value of the MAC
Address being accessible by ioctl.
• Multicast Communication: Used for enabling and configuring the Multicast feature of the VC. Default: (false,
32)
5.2.3.4 Maximum Transfer Size Configuration
The value of Maximum Transfer Size supported by the driver is 1522. The driver doesn’t support fragmented frames.
5.2.3.5 Driver Specific Limitations
The virtio-net network driver has the following limitations:
• Only support one Ethernet device per driver module.
• Only available as External File Provider Driver.
• Dependency on PCI Manager on non-ARM boards.
5.3 Block Device and MTD Drivers
Drivers for Block Devices or Memory Technology Devices (MTD).
5.3.1 Block Device and MTD Simulator blkdrvsim
PikeOS provides a driver for emulating BLK devices in RAM. It can be configured to emulate block devices, such as HDD or SDD, or Memory Technology Devices such as NOR and NAND. Arbitrary device size and block size can be configured for emulated block device. Arbitrary device size, size of erase block, page size and size of out-of-band area can be configured for emulated NOR and NAND devices. Driver also provides bad block API for these devices. ECC is not emulated. The blkdrvsim BLK driver uses the driver development environment with the BLK Driver High Level Module (see PikeOS Device Driver Programming Reference Manual, section 17, page 687). Please refer to the PikeOS Device Driver Programming Reference Manual, section 16.4, page 665 for description of the interface between driver and client. The blkdrvsim driver is provided in two variants - user level (external file provider), and kernel level.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Block Device and MTD Drivers 53
5.3.1.1 Driver Specific Configuration Parameters
5.3.1.1.1 blkdrvsim Base Component
The driver can be executed in multiple instances. Each instance can provide BLK devices on configured Provider Prefix. This prefix is set by default to blk0 in a base component of driver. The base component file defines blkdrvsim BLK driver instance. In addition to the standard parameters defined for BLK drivers by the driver framework, the blkdrvsim BLK driver has additional configuration parameters.
Following parameters can be configured in the blkdrvsim_-base component. Default value is used if component instance does not override parameter value. Parameter Name Type Description Default Value PROVIDER string Device Prefix of provider blk0 MAX_FD_COUNT integer A count of the PikeOS file descriptors provided by 4 this driver. One descriptor is required for every client connected to some device or some partition. MAX_TRANSFER_- integer The maximum transfer size is the number of bytes 8192 SIZE that can be transferred in a single read or write operation.
5.3.1.1.2 blkdrvsim Device Component
Multiple emulated devices can be attached to user level blkdrvsim driver. For the kernel level driver only single device is supported and it can be configured in the base component.
Following parameters can be configured in blkdrvsim_ext-device and blkdrvsim_kdev-base components. Default value is used if component instance does not override parameter value. Property Pathname Property Type Description Default Value DEVICE_TYPE option Emulated Device Type (block, nand, nor) block TOTAL_SIZE integer Device Size in bytes; data area only 4194304 BLOCK_SIZE integer (block only) Block Size in bytes 512 ERASE_SIZE integer (nand and nor only) Erase Size in bytes 131072 PAGE_SIZE integer (nand and nor only) Page Size in bytes 512 OOB_SIZE integer (nand only) Out-of-Band Page Area Size in bytes 16 MAX_PAGES integer Maximum Pages Transfered in single operation 1 Following parameters can be configured in blkdrvsim_ext-device component only. Default value is used if component instance does not override parameter value. The PikeOS path for device will have the form PROVIDER:FILE_NAME, for example a blk0:0. Each BLK device can be opened by single client only. FILE_NAME string The file name used by client applications to ac- 0 cess the logical device. MEM_SOURCE option Source of device memory (shm or pool) pool SHM_SIZE integer Size of SHM requirement in bytes; it has to be 4329472 aligned to page size and it shall include the OOB area if configured and 4 bytes for each erase block KEEP_SHM boolean Do not clean SHM content on start; can be used false for pre-loading SHM with filesystem data
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
54 Drivers
Following parameters can be configured in blkdrvsim_ext-device and blkdrvsim_kdev-base components. Default value is used if component instance does not override parameter value. Property Pathname Property Type Description Default Value Following parameters can be configured in the blkdrvsim_kdev-base component only. Default value is used if component instance does not override parameter value. The PikeOS path for device will have the form PROVIDER:DEV0_FILE_NAME, for example a blk0:0. Each device can be opened up to the MAX_CLIENT_COUNT clients. DEV0_FILE_NAME string The file name used by client applications to ac- 0 cess the logical device. MAX_CLIENT_COUNT integer Maximum number of concurrently connected 1 clients to device.
5.3.1.2 Driver Specific Limitations
The blkdrvsim BLK driver has the following limitations:
• User level driver does not support multiple connected clients on single device due to the limitation in the
BLK High Level Module.
• Kernel level driver component does not support defining multiple devices within single instance. Multiple
instances with different Provider Prefix can be used instead.
5.3.1.3 Usage of the User Level Driver
This paragraph explains integration of the user level variant of the blkdrvsim driver. The user level driver runs are regular PikeOS process with the adjustable process priority and CPU affinity. These can be adjusted in the VMIT. Number of executed driver threads depends on the settings of the THREAD_MODEL property.
5.3.1.3.1 Integration Project for the User Level Driver
The user level driver configuration must be added to the integration project. The user level version of the driver is provided by the module
/opt/pikeos-D5.0/target/x86/amd64/driver/object/blkdrvsim.elf
and the corresponding configuration files are
/opt/pikeos-D5.0/target/x86/amd64/driver/blk/blkdrvsim/blkdrvsim_ext-base.cmp /opt/pikeos-D5.0/target/x86/amd64/driver/blk/blkdrvsim/blkdrvsim_ext-device.cmp
Using CODEO:
• Open the integration project in the project editor (open the project.xml file).
• Select any Group component and click the Add... button.
• Browse to PIKEOS_POOL->driver->blk->blkdrvsim->blkdrvsim_ext-base. Click OK, Finish.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Block Device and MTD Drivers 55
• Browse to PIKEOS_POOL->driver->blk->blkdrvsim->blkdrvsim_ext-device. Click OK, Finish. Repeat multi-
ple times for multiple devices.
• Assign PROVIDER dependency of created devices to the associated base component of driver.
• Configure parameters of created components.
A pre-configured integration snippet demonstration can be found in
/opt/pikeos-D5.0/target/x86/amd64/driver/blk/blkdrvsim_ext-demo.dom
The dom file adds the driver to the service partition, instantiates the blkdrvsim driver with prefix blk0 and adds BLK device blk0:0. In CODEO, the blkdrvsim driver can be added to an integration project using the Add... button. Browse to PIKEOS_POOL->driver->blk and select blkdrvsim Block User Level Driver.
5.3.1.4 Usage of the Kernel Level Driver
This paragraph explains integration of the kernel level variant of the blkdrvsim driver. It runs in the kernel space at the same priority and the task switching time is the shortest of all other driver variants. The use the kernel level version of the blkdrvsim driver, the following steps are needed:
• Using a kernel fusion project, create a new kernel linked with the driver.
• Configure the integration project to use this new kernel.
• Add the driver configuration to the integration project.
5.3.1.4.1 Fusion Project for the Kernel Level Driver
The kernel level version of the driver is provided by the module
/opt/pikeos-D5.0/target/x86/amd64/fusion-kernel/object/kerneldriver/blkdrvsim.kdev
and the corresponding configuration file is
/opt/pikeos-D5.0/target/x86/amd64/fusion-kernel/kerneldriver.cmp
To add the driver to a kernel fusion project using CODEO:
• Create a new PikeOS project, of type Kernel Fusion. From the list of demo projects, select the kernel
corresponding to the board used in the integration project.
• Set the custom pool. The kernel fusion project should use the same pool as the integration project.
• Select a Group element and click the Add... button.
• Browse to PIKEOS_POOL->fusion-kernel->kerneldriver. Click OK, Finish. Save the project.
• Execute the all and install Make targets.
The new kernel is now installed under the object/bsp directory in the custom pool.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
56 Drivers
5.3.1.4.2 Integration Project for the Kernel Level Driver
The new kernel created in the fusion project and the kernel driver configuration must be added to the integration project. The kernel driver configuration is provided by the file
/opt/pikeos-D5.0/target/x86/amd64/driver/blk/blkdrvsim/blkdrvsim_kdev-base.cmp
Using CODEO:
• Open the integration project in the project editor (open the project.xml file).
• Set the custom pool. The integration project should use the same pool as the kernel fusion project.
• Select the PikeOS Kernel element inside the board component.
• In the parameter section labelled Kernel Binary, set the Kernel Directory parameter to Custom Pool.
• Select the board component and click the Add... button.
• Browse to PIKEOS_POOL->driver->blk->blkdrvsim->blkdrvsim_kdev-base. Click OK, Finish.
• Configure parameters of created components.
5.3.1.5 Demonstration Projects
Following demo project can be used for the querying (and testing) of the simulated devices:
/opt/pikeos-D5.0/demo/pikeos-native/blk-client/
These demonstration projects are using the blkdrvsim driver:
/opt/pikeos-D5.0/integration/blk-sim/project.xml /opt/pikeos-D5.0/integration/volume-provider-pikeos-native/project.xml /opt/pikeos-D5.0/integration/volume-provider-posix/project.xml /opt/pikeos-D5.0/integration/volume-provider-apex/project.xml /opt/pikeos-D5.0/integration/volume-provider-cfs-apex/project.xml /opt/pikeos-D5.0/integration/volume-provider-cfs-pikeos-native/project.xml /opt/pikeos-D5.0/integration/volume-provider-cfs-posix/project.xml /opt/pikeos-D5.0/integration/libhttpd-posix/project.xml /opt/pikeos-D5.0/integration/libmicrohttpd-posix/project.xml
5.3.1.6 Driver Source Code
A full source code of this driver is available in the DDK demos:
/opt/pikeos-D5.0/demo/ddk-user-level/hlblk-driver/ /opt/pikeos-D5.0/demo/ddk-kerneldriver/hlblk-driver/
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Block Device and MTD Drivers 57
5.3.2 AHCI Block Device Driver
The driver described in this chapter is available only on demand. Please contact sales@sysgo.com for further details. PikeOS provides an access to Serial ATA (SATA) storage devices connected to the Advanced Host Controller Interface (AHCI) compatible adapter via AHCI BLK driver. The AHCI BLK driver uses the driver development environment with the BLK Driver High Level Module (see PikeOS Device Driver Programming Reference Manual, section 17, page 687). Please refer to the PikeOS Device Driver Programming Reference Manual, section 16.4, page 665 for description of the interface between driver and client. The AHCI driver is provided as user level driver (external file provider).
5.3.2.1 Driver Specific Configuration Parameters
5.3.2.1.1 AHCI Base Component
The driver can be executed in multiple instances. Each instance serves single AHCI controller and provides BLK devices on configured prefix. This prefix is set to default value blk0 in the driver component. The base component file defines AHCI BLK driver for single AHCI controller. In addition to the standard parameters defined for BLK drivers by the driver framework, the AHCI BLK driver has additional configuration parameters.
These parameters can be configured in the ahci_ext-base component. Default value is used if component instance does not override parameter value. Parameter Name Type Description Default Value PROVIDER string Device Prefix of provider blk0 PCI_LOC string PCI Device Location (see PikeOS User Manual, byclass/ section 10.7.3, page 245) 010601/0000 MAX_FD_COUNT integer A count of the PikeOS file descriptors provided by 4 this driver. One descriptor is required for every client connected to some device or some partition. MAX_FILE_COUNT integer A count of device partitions that can be loaded by 2 the driver if LOAD_ALL_PARTITIONS is enabled. MAX_TRANS- integer The maximum transfer size is the number of bytes 8192 FER_SIZE that can be transferred in a single read or write operation. DIAG_VERBOSITY quiet, normal, The verbosity level determines which diagnostic normal verbose message will be displayed. DIAG_CONFIG boolean Display diagnostic messages for configuration and false initialization phase. In the verbose mode it also reports device’s information from ATAID and the layout of detected partition table. DIAG_IO boolean Display run-time reporting of the I/O errors and false port resets in the verbose mode. DIAG_TRACE boolean Display reporting executed ATA commands. In the false verbose mode it reports also error interrupts.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
58 Drivers
5.3.2.1.2 AHCI Device Component
Multiple devices on different AHCI ports can be attached to AHCI driver. The driver does not probe AHCI bus, devices configured in the integration project are probed only. Each device allows configuring following properties:
These parameters can be configured in the ahci_ext-device component. Default value is used if component instance does not override parameter value. Property Pathname Property Type Description Default Value PORT_NUM integer AHCI Port Number 0 OPERATION_MODE Buffered, Direct Access mode from AHCI controller and driver to Buffered or Mixed user I/O buffers. More info bellow. IO_BUFFER_SIZE integer Size of request I/O buffer used for Buffered and 8192 Mixed operation mode. It limits the maximum size of transaction. The amount of allocated memory will depend on the number of configured concur- rently executed requests; one buffer is needed for each request. MAX_REQUESTS integer Maximum number of concurrently executed re- 1 quests on the device. DETECT_TIMEOUT integer Timeout for a detection of the device (ms) 5000 IO_TIMEOUT integer Timeout for I/O operations (ms). Started operation 5000 that exceeds this timeout will be reported as I/O error. SPEED_ALLOWED integer Specifies the highest allowable speed of the inter- 0 face. More info bellow. FILE_NAME string The file name used by client applications to ac- 0 cess the logical device. MANDATORY boolean The flag that forces the AHCI driver to raise Health false Monitor Event if the device has not been found. AUTO_SYNC boolean The flag that forces flushing all device buffers after true each write operation on the device. PTABLE_TYPE none or DOS This option selects a partition table type on the none device. If the table type is specified, the driver tries to load partition table before the BLK devices for partitions are configured. LOAD_ALL_PARTI- boolean Provide BLK devices for all valid partitions found false TIONS in the partition table.
The PikeOS path of configured BLK device for AHCI device will have the form PROVIDER:FILE_NAME, for example a blk0:0 for a device on AHCI port 0. Each BLK device can be opened by single client only.
5.3.2.1.3 Operation Mode
• Buffered: The driver uses an internal buffer for the DMA transfers. This mode causes an overhead for
copying data from/to the user buffers.
• Direct: The driver uses the buffer provided by the user for DMA transfers. It has to be aligned to
P4_ARCH_ALIGN otherwise operation fails with P4_E_ALIGN error.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Block Device and MTD Drivers 59
• Mixed: In this mode the driver handles aligned user buffers in the Direct Mode and it handles unaligned
user buffers in the Buffered Mode.
5.3.2.1.4 Speed Allowed
• 0: No speed negotiation restrictions
• 1: Generation 1 (1.5 Gbps)
• 2: Generation 2 (3 Gbps)
• 3: Generation 3 (6 Gbps)
Notice: The negotiated speed may be lower depending on the HBA and SATA device capabilities.
5.3.2.1.5 BLK Devices for disk drive partitions
The AHCI driver can provide access to disk drive partitions defined in the DOS Partition Table via translation from a BLK Device of partition to its area on the disk device. The Partition Table loading can be enabled on device via PTABLE_TYPE. If the Partition Table type is specified, the driver tries to load it before the BLK devices for partitions are configured. The PikeOS path of configured BLK device for partition on AHCI device will have the form PROVIDER:FILE_NAME:PARTITION, for example the a blk0:2:1 for the first partition on a device on AHCI port 2. The partition number will match the index in the DOS Partition Table, so the first partition will have number 1 and the last one will have number 8. Up to 7 partitions per device are supported. Each BLK device of partition can be opened by single client only. Concurrent read/write access to partitions and underlying device is allowed, however the result of operation will depend on execution order of these operations. If the Partition Table loading is enabled the driver can create BLK devices for all valid partitions found in the partition table (see LOAD_ALL_PARTITIONS and MAX_FILE_COUNT options). Alternatively the driver can be configured to create BLK devices for statically defined partitions via Device Partition Component. Concurrent usage of the LOAD_ALL_PARTITIONS option and static partition definition is not supported and all partition components binded to such device shall be removed. Notice: A partition table for a device can be created using mkblkimage tool, see 5.3.4.
5.3.2.1.6 AHCI Device Partition Component
This component allows defining BLK device for disk drive partition statically.
These parameters can be configured in the ahci_ext-device-partition component. Default value is used if component instance does not override parameter value. Property Pathname Property Type Description Default Value PARTITION integer Partition Number (1-8) 1 MANDATORY boolean The flag that forces the AHCI driver to raise Health false Monitor Event if the partition has not been found.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
60 Drivers
5.3.2.2 User Level Driver
The user level version of the driver is provided by the module:
/opt/pikeos-D5.0/target/x86/amd64/driver/object/ahci.elf
and the corresponding configuration files are:
/opt/pikeos-D5.0/target/x86/amd64/driver/blk/ahci/ahci_ext-base.cmp /opt/pikeos-D5.0/target/x86/amd64/driver/blk/ahci/ahci_ext-device.cmp /opt/pikeos-D5.0/target/x86/amd64/driver/blk/ahci/ahci_ext-device-partition.cmp
Using CODEO:
• Open the integration project in the project editor (open the project.xml file).
• Select service partition component and click on the Add... button.
• Browse to PIKEOS_POOL -> driver -> blk -> ahci -> ahci_ext-base. And add the Base Component by
clicking on the OK, Finish button.
• For all connected AHCI devices use the Add... button and browse to PIKEOS_POOL -> driver -> blk -> ahci
-> ahci_ext-device. Then click on the OK, Finish.
• In the PikeOS Dependencies View assign the PROVIDER dependency of created devices to the Base
Component of the driver.
• If statically defined partitions will be used, then for each partition click on the Add... button and browse to
the PIKEOS_POOL -> driver -> blk -> ahci -> ahci_ext-device-partition. Then click on the OK, Finish to add
at least one Partition Component into the project.
• In the PikeOS Dependencies View assign DEVICE dependency of created partition devices to components
of their devices.
• Configure parameters of created components.
The driver also provides a pre-configured integration domain file for a fast demonstration:
/opt/pikeos-D5.0/target/x86/amd64/driver/blk/ahci_ext-blk-driver.dom
To try this in CODEO open an integration project, select service partition component, click on the Add... button, then browse to PIKEOS_POOL -> driver -> blk -> AHCI Block User Level Driver and confirm by clicking on the OK, Finish. This configuration domain file file adds the driver to the service partition, instantiates an AHCI driver named ’blk0’ on PCI device pci:byclass/010601/0000 with 100ms I/O timeout. It adds BLK device ’blk0:0’ on the AHCI port number 0 with DOS partition table and configures two non-mandatory statically defined partitions on ’blk0:0:1’ and ’blk0:0:2’.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Block Device and MTD Drivers 61
5.3.2.3 Error Handling
During the initialization, the driver performs detection and identification of configured devices. If a device is not available during the initialization, it will not be accessible during the run-time. If the read or write operation finishes with fatal error, or if IO_TIMEOUT is exceeded, or if a disconnection of the device is detected then the operation will return P4_E_IO error. The driver will try to re-initialize the device on the following read/write operation if there was fatal error or disconnection, and only if it suceeds the new operation is executed. The operation in such case will take longer time than in the normal case. If the re-initialization fails, the operation will return P4_E_BUSY error. Notice: The P4_E_BUSY error can be also returned if the device is accessed by more clients than is configured by the value MAX_REQUESTS. And also if multiple operations end with timeout and all available requests stays blocked.
5.3.2.4 AHCI Emulation in the QEMU
The QEMU is capable to emulate an AHCI controller and multiple disk drives connected to it. To enable QEMU’s AHCI support emulation, open the integration project, locate a AHCI Device Component and enable the device emulation by switching the Enable checkbox on (parameter EMULATE), then in the Drive Image File (parameter DRIVE_IMAGE) parameter select a image file and configure the Physical Block Size of emulated device (parameter BLOCK_SIZE). The QEMU’s boot strategy script will execute QEMU with required arguments. There is preconfigured demo image for AHCI Device located in the "PIKEOS/share/mkblkimage/blkdemo.image". This image if it is configured, will be copied into integration project directory upon the first boot. See the README in the mkblkimage demo directory for details about this image.
5.3.2.5 Multiple AHCI Controllers
If multiple AHCI Controllers are present in the system, then a separate device driver can be configured for each of them. Start by adding a new ahci_ext-base component into the Integration Project and change its component name and the values of following properties to unique values: PROCESS, PROVIDER, PCI_LOC. If the QEMU Emulation is used then change also the QEMU_ID.
5.3.2.6 Demonstration Projects
Following demo project can be used for the querying (and testing) of the AHCI devices:
/opt/pikeos-D5.0/demo/pikeos-native/blk-client/
5.3.3 USB Block Device Driver
The driver described in this chapter is available only on demand. Please contact sales@sysgo.com for further details. PikeOS provides a driver for accessing USB key storage devices connected to
• the Enhanced Host Controller Interface (EHCI) i.e USB 2.0
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
62 Drivers
• or the eXtensible Host Controller Interface (xHCI) i.e USB 3.0
These controllers are accessed through the PCI Manager. The USB driver provides the BLK class API to client applications and can therefore be used as an external driver for a volume provider. Please refer to the PikeOS Device Driver Programming Reference Manual, section 16.4, page 665 for description of the interface between driver and client. The USB driver is provided as a user level driver (external file provider).
5.3.3.1 User Level Driver
The USB driver is provided by the binary:
/opt/pikeos-D5.0/target/x86/amd64/driver/object/blkusb.elf
The corresponding driver configuration files are:
• The domain file, instantiating and configuring the provider configuration component, the physical device
componenent and 1 partition component, and overloading default configuration parameters when needed:
/opt/pikeos-D5.0/target/x86/amd64/driver/blk/blkusb_ext-blk-driver-pci.dom
• The driver component files giving the driver configuration and data structures:
/opt/pikeos-D5.0/target/x86/amd64/driver/blk/blkusb/blkusb_ext-fp.cmp
/opt/pikeos-D5.0/target/x86/amd64/driver/blk/blkusb/blkusb_ext-device.cmp
/opt/pikeos-D5.0/target/x86/amd64/driver/blk/blkusb/blkusb_ext-device-partition.cmp
/opt/pikeos-D5.0/target/x86/amd64/driver/blk/blkusb/blkusb_ext-device-pcidev.cmp
The USB driver can be added to an intergration project using the Add... button (or the add command in a script). Browse to PIKEOS_POOL/driver/blk and select USB Block User Level Driver PCI. The driver provides a single device and 1 partition. This configuration domain file file adds the driver to the service partition, instantiates a provider named blkusb0 on PCI device byclass/0c0330/0000. It adds a BLK device blkusb0:0 with a DOS partition table and configures one mandatory statically defined partition on blkusb0:0:1. Default timeouts for read/write operations on the device are set to 100ms. It is important to use the correct PCI device name. For a QEMU xHCI host device, the PCI device name should be byclass/0c0330/0000, whereas for a EHCI host device, it should be byclass/0c0320/0000.
5.3.3.1.1 USB Device Component
Note: Only one controller is currently supported and this controller can manage only one mass storage device.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Block Device and MTD Drivers 63
These parameters can be configured in the blkusb_ext-device-pcidev component. Default value is used if component instance does not override parameter value. Parameter Name Type Description Default Value PCI_LOC string PCI Device Location (see PikeOS User Manual, byclass/0c0330/0000 section 10.7.3, page 245)
5.3.3.2 USB Emulation in QEMU
QEMU can emulate EHCI and xHCI controllers and a disk drive connected to it. To enable QEMU’s USB emulation, it is sufficient to set the Drive Image File parameter (parameter name DRIVE_IMAGE) for the USB device component in the integration project. The boot strategy script will then exe- cute QEMU with the required arguments. The argument for the USB controller type is set based on the value of the PCI_LOC parameter. There is pre-configured disk partition image which can be used with the USB BLK Device in PIKEOS_POOL/share/mkblkimage/blkdemo.image. For further information on creating a disk partition im- age, refer to the documentation for the mkblkimage tool (5.3.4).
5.3.3.3 Demonstration Projects
The following demo project can be used for testing access to a USB key storage device through a EHCI or xHCI controller:
/opt/pikeos-D5.0/demo/integration/usb-volume-provider-fat/
5.3.3.4 Driver Specific Limitations
The blkusb USB block driver has the following limitations:
• Only supports one USB device per driver module.
• Only available as External File Provider.
• Hotplug is not supported.
• Available on demand for x86 boards.
5.3.4 Partitioned Image Creation Tool mkblkimage
mkblkimage is a tool that helps with preparation of a partitioned disk drive or a partitioned disk image file for usage with PikeOS BLK drivers. It can generates partition table data and shell script for initializing a disk drive or a file image. The layout of the disk drive image is defined in the configuration file by number of partitions, partition indexes, partition sizes, partition type and optionally with partition content data file. The partition sizes are specified in the units of sector size and they can be aligned to the larger physical sector boundaries via the size align parameter. The mkblkimage tool generates DOS partition table data by following rules:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
64 Drivers
• Partitions will be created and allocated in the following order: (1) 1st primary, (2) 2nd primary, (3) 3rd
primary, (4) 4th primary, (5) 1st logical, (6) 2nd logical, (7) 3rd logical, (8) 4th logical.
• The partition entry will be stored into the partition table on the index specified in the parenthesis above. For
example, the 2nd logical partition will have index 6.
• A partition will be not be generated if it has zero size.
• The first partition with non-zero size will start on the first aligned sector after the partition table.
• Further processed partitions with non-zero size will start on the aligned sector right after the end of the
previous partition.
• If logical partitions are created then 4th primary partition must not be used and it should have set size to 0.
On execution without arguments the mkblkimage tool prints brief help:
$ /opt/pikeos-D5.0/bin/mkblkimage --help Usage: mkblkimage CONFIG_FILE OUTPUT_PREFIX A new configuration file will be created if CONFIG_FILE is not existing file. Check the Platform Manual,chapter Partitioned Image Creation Tool mkblkimage for a detailed documentation.
An empty configuration file will be generated if the file specified as the first argument does not exist:
$ /opt/pikeos-D5.0/bin/mkblkimage test.conf Notice: new configuration file test.conf has been created $ cat test.conf #MKBLKIMAGE_CONFIG_BEGIN#
Notice:
This file is interpreted by bash,you can use arithmetic evaluation.
Example: SIZE_PART1_SEC=$(((64<<20)/$SIZE_SEC)) will be evaluated as 64MiB.
type of partition table
TYPE=dos
size of one sector in bytes
SIZE_SEC=512
partition alignment size in bytes
SIZE_ALIGN=4096
1st primary partition
size of partition in sectors
SIZE_PART1_SEC=0
partition type (use ćf́or FAT,otherwise keep empty)
TYPE_PART1=
path to partition image file; used for image initialization via script
IMAGE_PART1=
2nd primary partition
SIZE_PART2_SEC=0 TYPE_PART2= IMAGE_PART2=
3rd primary partition
SIZE_PART3_SEC=0 TYPE_PART3= IMAGE_PART3=
4th primary partition
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
PCI Controller Drivers 65
size of 4th partition in sectors (set to 0 if using logical partitions)
SIZE_PART4_SEC=0 TYPE_PART4= IMAGE_PART4=
1st logical partition
SIZE_LOGPART1_SEC=0 TYPE_LOGPART1= IMAGE_LOGPART1=
2nd logical partition
SIZE_LOGPART2_SEC=0 TYPE_LOGPART2= IMAGE_LOGPART2=
3rd logical partition
SIZE_LOGPART3_SEC=0 TYPE_LOGPART3= IMAGE_LOGPART3=
4th logical partition
SIZE_LOGPART4_SEC=0 TYPE_LOGPART4= IMAGE_LOGPART4= #MKBLKIMAGE_CONFIG_END#
Executing the mkblkimage tool with valid configuration file results in generation of partition table data, script and information file:
$ /opt/pikeos-D5.0/bin/mkblkimage
/opt/pikeos-D5.0/share/mkblkimage/blkdemoimage_fat.conf demoimage
Completed. Output is stored into demoimage_ptable* files.
$ ls
demoimage_ptable_0x00000000.bin demoimage_ptable.create.sh demoimage_ptable.info
The ptable.create.sh script can be used for generating partitioned disk image or device:
$ ./demoimage_ptable.create.sh demo.image $ /sbin/fdisk demo.image Command (m for help): p Disk demo.image: 64 MiB, 67112960 bytes, 131080 sectors Units: sectors of 1 * 512 = 512 bytes Sector size (logical/physical): 512 bytes / 512 bytes I/O size (minimum/optimal): 512 bytes / 512 bytes Disklabel type: dos Disk identifier: 0x00000000
Device Boot Start End Sectors Size Id Type demo.image1 8 65543 65536 32M c W95 FAT32 (LBA) demo.image2 65544 131079 65536 32M c W95 FAT32 (LBA)
5.4 PCI Controller Drivers
5.4.1 PSP PCI
The PSP PCI is a PSP level driver providing the low level functionality for the PCI and MSI drivers. This driver provides functions like reading and writing PCI configuration or device enumeration that is common for all PCI
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
66 Drivers
drivers. If there is a PCI Manager driver provided for the board this driver is an integral part of the PSP and is always present, even if the PCI manager is not actually compiled in.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
6 The PikeOS CDK
The PikeOS CDK will be installed into the directory
/opt/pikeos-D5.0/cdk/x86/amd64/bin
To avoid conflicts with other utilities installed on the host, all binaries provided by the CDK are prefixed with x86_amd64- like x86_amd64-gcc. The PikeOS x86 cross development toolchain supports the System V ABI for x86-64.. This is important if routines compiled with the C-compiler shall be called from an assembly language function or vice versa. Detailed PDF documentation can be found in:
/opt/pikeos-D5.0/documentation/cdk/x86_amd64
6.1 Target binaries
With the installation of the PikeOS Package: Base, all the processor family dependent binary modules, libraries, header files, BSPs and PSPs will be installed into the directory
/opt/pikeos-D5.0/target/x86/amd64/
The PikeOS architecture name is x86_amd64.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
7 Direct I/O Device Configuration
This section provides examples of the direct I/O access to the certain hardware resources such as legacy I/O ports or memory regions. The PCI devices are managed by the PCI Manager. It provides services to make PCI device resources accessible to the applications. No manual configuration described in this chapter is necessary. To list the PCI devices managed by the PCI Manager or change PCI Manager configuration, please refer to the PikeOS User Manual, section 10.7, page 244. The P4Linux uses the virtual PCI bus to access the devices managed by the PCI Manager. In general, there are two ways of how to map resources to the partitions. The first one, which is described in this chapter, is to define the MemoryRequirements and respective virtual mapping in the partition configuration. The second possibility is to define the properties in the property filesystem and the application may map it to the virtual address it likes. Moreover, the only way how to permit access to a certain interrupt is also to use the property filesystem. The P4Linux expects that the mapping will declared using the MemoryRequirements. The non-PCI interrupt can be enabled to P4Linux using a property filesystem via the help of the configuration switch in the P4Linux component. The MemoryRequirement may be added to the partition using a graphical editor, or it can be directly copy pasted from the following examples. Once MemoryRequirement is defined, a mapping to the selected virtual address must be established. This is done via MemMap entries of the partition. The virtual address must be selected not to collide with other virtual addresses used by the application. The P4Linux has a reserved range for such mappings, please check the ELinOS Platform Manual for details.
7.1 Graphical Framebuffer
The multiboot2 information passed to the PSP may contain framebuffer information. The PSP will print and export the framebuffer information in the memory structure regardless of the current console settings. Such information might be useful for any application requesting direct framebuffer access such as P4Linux (VESA VGA framebuffer). The framebuffer resolution is input to the PSP, hence the PSP cannot change the framebuffer settings in any way. If "grub2" boot strategy is used, you may change the resolution as part of GRUB2 configuration. This can be used on UEFI as well as legacy systems. See section 4.4.5, page 34 for details. To obtain the framebuffer, an application should be granted read-only access to physical page zero and read-write access to the framebuffer itself:
• I/O memory 0x0, size 0x1000 (4 KiB), read-only access
• I/O memory of the framebuffer, read-write access
The PSP stores the framebuffer settings at physical address 0x600 using the following structure:
/*
-
Framebuffer info structure
-
The fb info structure is placed within the first page
-
at address 0x600 (above BIOS + DOS communication area)
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Graphical Framebuffer 69
/ struct fb_info { / framebuffer mode */ U32 width; // width U32 height; // height U32 bpp; // bits per pixel U32 linelen; // line length in bytes U32 lfb_base; // framebuffer physical base address U32 lfb_size; // framebuffer size in bytes U32 flags; // 0 U32 reserved; // 0
/* red, green, blue, reserved position and sizes (in bits) */ U8 r_size; U8 r_pos; U8 g_size; U8 g_pos; U8 b_size; U8 b_pos; U8 x_size; U8 x_pos; U64 lfb_base; // framebuffer physical base address };
In addition if the property p4/kernel/boot_message is set at least to 3, the PSP will print the resolution, base address and size to the PSP console, so the requirements can be adjusted accordingly:
Writing fb_info structure. Framebuffer address 0x00000000FD000000 size 0x000000000012C000 resolution: 640 x 480 x 32
If only the physical page zero with valid framebuffer configuration is mapped, but the page with the actual Frame- buffer not, the P4Linux will warn about that and print the expected Framebuffer address during startup like:
P4Linux: VESA video memory not mapped (0xfd000000, size 0x300000)
On QEMU x86 please find below an example of the VMIT configuration for 640x480x32 mode. The virtual address used is free address for P4Linux as documented in the ELinOS Platform Manual. Please keep in mind that the Framebuffer configuration needs to be provided to the PSP by the bootloader, which is not the case of the default qemu PikeOS boot strategy (more details section 4.4.5, page 34).
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
70 Direct I/O Device Configuration
In order to create these memory regions in Codeo you can go to the Source Editor tab find the resource partition with your P4Linux application and add there the memory MemoryRequirementTable snippet above. Find the source of the go to the Linux Process and add the mapping above to the already existing there.
7.2 VGA and PS/2 Keyboard + Mouse
To utilize the legacy VGA controller on x86, the following I/O resources should be accessible by a partition:
• p60: I/O ports 0x60, size 16 ports
• p80: I/O ports 0x80, size 1 port
• vga: I/O ports 0x3c0, size 32 ports
• vgabios: I/O memory at 0xa0000, size 0x28000 (160 KiB), read-write access
• bda: BIOS data area at 0x00000, size 0x1000 (4 KiB), read only access
• keyboard: interrupt 1
• mouse: interrupt 12
Additionally, a partition needs to have access to the PCI or PCI Express VGA device. The PS/2 keyboard and mouse needs to have access to the legacy IRQ 1 and IRQ 12. In the following example, the first 4 KiB of physical memory will be available to the partition at the virtual address 0x40000000. The physical memory range of 0xa0000-0xc7fff will be accessible to the partition at the virtual address 0x40001000. The I/O ports will be available as described above. The I/O ports are reachable as usual on the x86 platform with the ioport CPU instructions. To allow partition access to the hardware, add the desired memory requirements and process map entries to the partition configuration. For the I/O ports only the PhysicalAddress, Size and Type parameters apply. The must contain the I/O port entries to actually grant a partition an access to them.
<MemoryRequirement
AccessMode="VM_MEM_ACCESS_RD"
Alignment="0xffffffff" CacheMode="VM_MEM_CACHE_INHIBIT"
Contiguous="true" IsPool="false" MemRegionID="0xffffffff"
MemRegionPartition="0xffffffff" Name="bda"
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
VGA and PS/2 Keyboard + Mouse 71
PhysicalAddress="0x0" Size="0x00001000"
Type="VM_MEM_TYPE_IO_MEM" ZeroCount="0" />
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
A Architecture Dependencies
A.1 Supported Architectures
The ASP supports x86 64-bit capable processors, which are marketed under very different names like: AMD64, Intel64 or with older names like EM64T, IA-32E, or x86-64. The ASP requires that the Non-Executable (NX) bit feature is supported and enabled. The NX feature is not available on some very early 64-bit Intel processors (Prescott). On newer CPUs, some BIOSes provide a feature to disable NX bit support for compatibility reasons. The ASP supports optional hardware features or workarounds that may be supported only by some CPUs, please refer to the section A.11, page 86 for further details.
A.2 Address Layout
The user accessible part of the address space covers the address range from address 0 to 0x7fffffffefff, inclusive. The page size is 4096 bytes. The physical addresses space range is CPU dependent (usually larger than 36 bits). The PSP detects the maximum supported width and pass it for kernel in the PSP Descriptor.
A.3 Basic Data Types
PikeOS Type Size in Bytes Description P4_cpureg_t 8 Size of a processor register P4_address_t 8 Virtual memory address P4_size_t 8 Size of objects in virtual memory P4_phys_addr_t 8 Physical address space type P4_cpumask_t 8 Up to 64 processors are supported in the API
Table 22: x86_amd64 basic data types
A.4 Architecture specific KINFO page
The KINFO page contains arch member which provides information on certain run-time available features de- pending on installed CPU. It can be accessed from application program via a pointer like this: p4_kinfo_arch()->arch.
typedef struct P4_kinfo_arch_str { /** Copy of XCR0 register / P4_cpureg_t xcr0; /* Copy of PSP cpu_features / P4_uint32_t cpu_features; /* Copy of PSP alt_features / P4_uint32_t alt_features; /* status flag if CPU has an FPU implemented */
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
User Mode Context 73
int has_fpu;
/** @internal Explicit padding */
P4_uint32_t padding;
} P4_kinfo_arch_t;
Please refer to the section A.11, page 86 for the description of the cpu_features and alt_features. The has_fpu member is always set to 1. The xcr0 member matches the value of hardware XCR0 register. If some bit is set, it indicates that the respective FPU sub-components are supported by the CPU and can be used. Currently following bits are defined:
• bit 0, x87 FPU component is available (always 1)
• bit 1, SSE FPU component is available (always 1)
• bit 2, AVX FPU component is available
• bit 63, reserved for future use
Thus, the CPU without AVX extensions supported will set the arch.xcr0 to 3 and CPU with AVX extensions support to 7.
A.5 User Mode Context
The user mode context contains all registers necessary to save the state of a thread on a thread switch or an exception. When creating new application thread, use p4_thread_arg() function, which sets up the necessary usermode context for 64-bit operation.
A.5.1 Register Set
The register set consists of the integer register subset, virtual registers and FPU set which stores x87, SSE and AVX context. See A.5.3 for further FPU related information. The order of the registers is defined in the following structure. The size of a complete user mode context is 1088 bytes.
typedef struct P4_regs_str { P4_cpureg_t rdi; /* General purpose registers (64 bit) */ P4_cpureg_t rsi; P4_cpureg_t rdx; P4_cpureg_t r10; P4_cpureg_t r8; P4_cpureg_t r9; P4_cpureg_t rcx; P4_cpureg_t r11; P4_cpureg_t rax; P4_cpureg_t rbx; P4_cpureg_t rbp; P4_cpureg_t r12; P4_cpureg_t r13; P4_cpureg_t r14; P4_cpureg_t r15;
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
74 Architecture Dependencies
P4_cpureg_t vector; /* Exception entry vector, see note 2 */
P4_cpureg_t error; /* Exception error code, see note 3 */
P4_cpureg_t rip; /* Instruction pointer / program counter */
P4_cpureg_t cs; /* Segment selector CS, see note 1 */
P4_cpureg_t rflags; /* Processor flags, see note 4 */
P4_cpureg_t rsp; /* Stack pointer */
P4_cpureg_t ss; /* Segment selector SS, see note 1 */
P4_cpureg_t fs_base; /* FS segment base value, see note 5 */
P4_cpureg_t gs_base; /* GS segment base value, see note 5 */
P4_cpureg_t reserved[6]; /* Reserved, see note 13 */
P4_cpureg_t ex_code; /* Exception status/reply code, see note 6 */
P4_cpureg_t usedfpu; /* Floating-point usage flag, see note 7 */
/* FPU register save area (x87, SSE and AVX), see note 8 / struct { struct { P4_uint32_t fcw_fsw; / FPU control and status word / P4_uint32_t ftw_fop; P4_cpureg_t fip; P4_cpureg_t foo; P4_uint32_t mxcsr; / MXCSR, see note 9 / P4_uint32_t mxcsr_msk; / MXCSR Mask, see note 10 / P4_cpureg_t mm[16]; / 8 FPU (80 bit) or 8 MMX (64 bit) registers, see note 11 / P4_cpureg_t xmm[32]; / SSE data registers XMM0 to XMM15 (128 bit) / P4_cpureg_t reserved[12]; / Reserved, see note 12 / } fxsave; struct { P4_uint64_t xstate_bv; / State of the FPU components, see note 14 / P4_uint64_t xcomp_bv; / Format of FPU register area, see note 15 / P4_uint64_t reserved[6]; / Reserved, see note 12 / } xsave_header; struct { P4_cpureg_t ymmh[32]; / AVX data registers YMM0 to YMM15 (high 128 bit) */ } avx; } fpu; } P4_regs_t attribute((aligned(64)));
Reserved space in the register save area must be treated as undefined data and must not be used to store any user data.
• Note 1: The segment selectors CS, SS may refer to any valid userspace entry in the GDT, see A.5.5 for
more information. A privilege level of 3 is enforced. Code and data (stack) segment selectors should be set
to 0x33 and to 0x2b respectively for 64-bit userspace mode with a Requested Privilege Level (RPL) of 3.
• Note 2: vector is not a CPU register. It contains only the most recent CPU exception vector number or
page fault address (CR2 register copy) which has occured while the thread was running. Regular interrupts,
NMI or #MCE exceptions store zero in this member. See section A.7, page 81 for further details.
• Note 3: error is not a CPU register. It reflects the additional error information generated by the processor
in case of an exception. The meaning of error depends on the kind of exception. See section A.7, page
81 for further details.
• Note 4: Not all bit combinations are allowed in this register. The user is only allowed to change CF (bit
0), PF (bit 2), AF (bit 4), ZF (bit 6), SF (bit 7), TF (bit 8), DF (bit 10), OF (bit 11), RF (bit 16), and AC (bit
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
User Mode Context 75
18). The TF bit enables single stepping. The RF bit disables single stepping for the first instruction after an
exception. The AC bit enforces strict alignment in user space.
• Note 5: fs_base and gs_base is not a CPU register. It reflects the base address loaded into hidden part of the segment register. See A.5.5 for more information.
• Note 6: ex_code is not a CPU register. It contains the exception message status code. See section A.7, page 81 for further details.
• Note 7: usedfpu is not a CPU register, it is a control register for the FPU. See A.5.3 for further information.
• Note 8: Order and format of the x87, SSE and AVX FPU context is either compatible with XSAVE area or with FXSAVE instruction using the REX prefix. See A.5.3 for further information.
• Note 9: mxcsr is the CPU’s MXCSR register. See A.5.3 for further information.
• Note 10: mxcsr_mask is the state of MXCSR_MASK field after an FXSAVE instruction. Content depends on the CPU version.
• Note 11: Depending on the state of the thread, 80 bit x87 FPU registers or 64 bit MMX registers are saved. Other bits are reserved.
• Note 12: This area is reserved do not use.
• Note 13: The xstate_bv field controls the state of x87, SSE and AVX components. See A.5.3 for further information.
• Note 14: The xcomp_bv field is reserved for future use.
A.5.2 Short Context
The short context is used in the short exception message and defines only a subset of all registers. Registers ex_code and vector contain the exception status code and fault address, rip and rsp represent program counter and stack pointer, and rflags and usedfpu are used as architecture specific registers 1 and 2.
A.5.3 FPU Support
PikeOS userspace thread context contains parts for FPU and vector units. The x86 FPU x87, SSE and AVX contexts are controlled by the FPU part of the userspace context only. The vector part of the context is not used on this platform. The layout of the FPU part of the context matches the layout of XSAVE area. Note that the P4_regs_t structure is enforcing proper alignment in memory. As an optimization, the ASP might try to restore the FPU context directly from the userspace. This operation might fail if "fpu.xsave_header" contains invalid data (reserved values non-zero, invalid bits set in the "xstate_bv" etc). If the thread is going to perform x87, SSE or AVX operations, one needs to set the P4_THREAD_ARG_FPU argument when calling p4_thread_arg() or modify the context of the thread with p4_thread_fpu_on(). Please consult the PikeOS Kernel Reference Manual for further details. When using the PikeOS Native API Extensions, set the P4_THREAD_ARG_FPU in the context_flags of the thread attribute object.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
76 Architecture Dependencies
The GCC compiler provides intrisic functions for vector operation. The header files such as xmmintrin.h or immintrin.h etc may require external headers. To overcome this issue,PikeOS CENV might be used to supply required functionality. In order to use AVX, supply the -mavx compiler switch to the compilation flags. Please note that the compiler might want to try to use SSE instructions even when there are no floating point variables in the program for the purpose of the optimization. The support for x87, SSE or AVX components is indicated in the KINFO page arch.xcr0 member as noted above. The x87 and SSE FPU context is always supported. A legacy software can detect AVX and XSAVE feature set using standard CPUID features (OSXSAVE, AVX). If AVX is unsupported by the CPU, the size of the P4_regs_t context loaded by the kernel is truncated to 768 bytes (P4_regs_t context without AVX registers). Depending on CPU features, legacy FXSAVE format (with REX prefix applied) or XSAVE format (with REX prefix applied) without AVX component is used. If legacy FXSAVE format is used, the "fpu.xstate_header.xstate_bv" is still considered by the ASP and above information about the initial hardware state still applies. The XSAVE area header is stored in the fpu.xstate_header member of the P4_regs_t. The xstate_bv indicates the state of x87, SSE and AVX components of the context. The bit positions matches the XCR0 register described above. If the respective XCR0 bit is set, the the corresponding FPU context area is used. If the respective bit is clear, the FPU unit itself is in the hardware defined initial state. For x87, controlled by bit 0, the initial hardware state is as follows:
fpu.fxsave.fcw_fsw = 0x0000037f fpu.fxsave.ftw_fop = 0x0 fpu.fxsave.fip = 0x0 fpu.fxsave.foo = 0x0 fpu.fxsave.mm[0..15] = 0x0
The default value of the FPU control word is 0x37F (round to nearest even, 64-bit precision, mask all floating-point exceptions). For SSE, controlled by bit 1, the initial hardware state is as follows:
fpu.fxsave.xmm[0..31] = 0x0
For AVX, controlled by bit 2, the initial hardware state is as follows:
fpu.avx.ymmh[0..31] = 0x0
The fpu.fxsave.mxcsr is somewhat independent. It may be loaded or saved from / to the P4_regs_t structure unconditionally regardless of the AVX / SSE component state. On some CPUs, it has no default value. PikeOS sets the MXCSR to 0x1f80. The user is allowed to change bits 0 to 5 and 7 to 15. If the CPU supports the "denormals are zero" feature, bit 6 is modifiable too. Please refer the to the Intel and AMD x86 instruction manual for a complete description of xstate_bv field and effects of XSAVE / XRSTOR instructions on the fpu.fxsave.mxcsr field. The PikeOS sets the EDX:EAX instruction mask to all ones, thus if XCR0[n] bit is set the corresponding RFBM[n] bit is also set. Internally, the FPU context is controlled via bit 0 in the Used-FPU flag usedfpu of the thread userspace context. If the bit is set, FPU is accessible in user space, and saved and restored upon thread switches and exception handling (see table 23). The PikeOS sets the FPU to x86 ABI compliant values, which matches the hardware initial state.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
User Mode Context 77
Bit Name Description
0 R_USEDFPU_ENABLED FPU enabled if set
Table 23: x86 FPU support
A.5.4 Layout of GDT and LDT
PikeOS does not support defining an own LDT, but allows the user to indirectly modify base addresses of two GDT entries. The GDT has the layout mentioned in table 24.
Entry Name Access Modify Description 0 KERN_NULL Y - Null segment: empty segment for NULL selectors 1 KERN_UNUSED - - Unused 2 KERN_CS - - 64-bit code segment selector used by kernel 3 KERN_DS - - 64-bit data segment selector used by kernel 4 USER_CS32 Y - 32-bit code segment selector used by user code 5 USER_DS Y - 32-bit data segment selector used by user code 6 USER_CS Y - 64-bit code segment selector used by user code 7 USER_UNUSED - - Unused 8 USER_TLS0 Y Y user TLS selector (for FS in 32/64-bit mode) 9 USER_TLS1 Y Y user TLS selector (for GS in 32/64-bit mode) 10 KERN_TSS - - Task state segment (TSS) 11 KERN_TSS2 - - Task state segment (TSS) (second slot)
Table 24: x86_AMD64 GDT layout.
Only entries 0 and 4, 5, 6, 8 and 9 are accessible to the user. Entry 5 is 32-bit user data segment with base set to 0. Entry 6 is 64-bit user code segment. Entries 8 and 9 define a selector which is used in the 64/32-bit mode for FS and GS. The kernel enforces a Descriptor Privilege Level (DPL) of 3 for the user modifiable segments. The user cannot specify system segments and gate descriptors. The layout of a GDT entry is described in the CPU vendors manuals. The base value of the USER_TLS0 is formed by fs_base of the register context, and USER_TLS1 by gs_base.
A.5.5 Segment registers in the 64-bit mode
In general, using p4_thread_arg() avoids any needs to setup userspace context of the thread for 64-bit operation. Note that the processor in the 64-bit mode ignores actual selectors of DS, ES, FS, GS segment registers. It does not matter if 64-bit or 32-bit selector is loaded to any segment register except of CS, which must be loaded with (USER_CS<< 3) | 3 for the 64-bit user code segment. The SS segment selector must have P bit set. PikeOS loads SS with (USER_DS<< 3) | 3. The processor still uses the segment base in the hidden part of the FS and GS segment register when the FS or GS segment override with some instruction is in a use. PikeOS loads the segment base of FS and GS from register context fs_base and gs_base respectively. The lower 32 bits of the base are always reflected in the respective USER_TLS0 or USER_TLS1 selector. If the base in the register context is set to zero, USER_DS selector may be
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
78 Architecture Dependencies
loaded instead depending on other CPU features. Values are checked to fit the user virtual address space. Out of bounds bases are trimmed to 0. PikeOS uses hidden part of the FS segment register together with fs_base as thread local storage pointer. The PikeOS will load segment registers with user accessible selectors specified in table 25.
Segment Loaded Selector Base Attributes Register CS USER_CS 0 64-bit code SS USER_DS 0 32-bit data DS USER_DS 0 32-bit data ES USER_DS 0 32-bit data SS USER_DS 0 32-bit data FS may be USER_DS / 0 / Loaded from fs_base if non-zero user TLS for FS, 32-bit USER_TLS0 GS may be USER_DS / 0 / Loaded from gs_base if non-zero user TLS for GS, 32-bit USER_TLS1
Table 25: x86_AMD64 segment register
A.5.6 Segment registers in the compatibility mode
The user code may execute under 32-bit compatibility mode, however the SYSCALL/SYSENTER instruction will trigger an exception on Intel CPUs. On AMD CPUs, only SYSENTER causes an exception. The segment registers are loaded in a same way as in the 64-bit mode as they already contain 32-bit mode compatible selectors. The FS will contain the USER_TLS0 selector, the GS will contain the USER_TLS1 selector. If the base in the register context is set to zero, USER_DS selector may be loaded instead depending on other CPU features. The CS register will remain set to the 32-bit USER_CS32 selector during the context switch, however execution environment of SYSEMU exit or exception handlers will set 64-bit CS. It is expected that 32-bit code will be executed in only in the SYSEMU mode.
A.5.7 System Calls
The PikeOS kernel supports SYSCALL instruction. System call ABI uses same convention as described in the System V Application Binary Interface AMD64 Architecture Processor Supplement. When using SYSCALL, the ASP expects that register RCX register is saved in the register R10 before entering the kernel. If user space software wishes to utilize SYSCALL instruction for system call emulation, the register content of RCX and R11 will be overwritten by the SYSCALL instruction and saved in the thread’s register context as follows. The RCX will be saved in the rcx and rip, the R11 will be saved in the r11 and rflags. The cs will contain USER_CS, value and the ss will contain USER_DS value. As a performance improvement PikeOS might use the SYSRET instruction when returning from the sysemu handler if register values match as if the SYSCALL instruction was previously executed as noted above and CPU’s RF and TF flags are not set. The SYSCALL instruction in the SYSEMU mode will trigger exception 257 in the 64-bit context. No exception is generated if executed from the 32-bit context on AMD CPUs. The SYSENTER instruction is unsupported.
Note: The functionality of p4_thread_get_regs() to retrieve the caller’s register context requires the PikeOS library function to be used. Do not invoke the system call directly.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Mapping Translations 79
A.6 Mapping Translations
A.6.1 PikeOS to Architecture Specific Access Permissions
The mapping attributes P4_M_READ, P4_M_WRITE, and P4_M_EXEC on the left of table 26 are translated to the following effective architecture specific attributes on the right.
P4_M_READ P4_M_WRITE P4_M_EXEC Present Write Execute Disable 0 0 0 0 n.a.1 n.a. 0 0 1 1 0 0 0 1 0 1 1 1 0 1 1 1 1 0 1 0 0 1 0 1 1 0 1 1 0 0 1 1 0 1 1 1 1 1 1 1 1 0
Table 26: PikeOS access permissions mapped to x86_AMD64 specific access permissions
The x86 64-bit processor NX (Not eXecute, execute disable) feature supports execution permissions on a per page level, but implies P4_M_READ for these page as well. Furthermore, P4_M_WRITE always implies P4_M_READ, because there is no concept of write only pages.
A.6.2 Architecture Specific to PikeOS Access Permissions
The architecture specific mapping attributes stored in the page tables in the kernel (on the left of table 27) are translated to the following generic attributes (on the right):
Present Write Execute Disable P4_M_READ P4_M_WRITE P4_M_EXEC 0 n.a.1 n.a. n.a. n.a. n.a. 1 0 0 1 0 1 1 0 1 1 0 0 1 1 0 1 1 1 1 1 1 1 1 0
Table 27: x86_AMD64 access permissions mapped to PikeOS specific access permissions
The five supported combinations are:
• 0: no access at all,
• P4_M_READ | P4_M_EXEC: read only and executable,
• P4_M_READ : read only,
• P4_M_READ | P4_M_WRITE | P4_M_EXEC: read, write and executable, and
• P4_M_READ | P4_M_WRITE : read and write.
1 n.a. denotes not applicable.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
80 Architecture Dependencies
A.6.3 Supported Caching Attributes
PikeOS sets up the PAT cache attributes table (see table 28).
ID Cache mode Description
0 WB write-back
1 WT write-through
2 WC write-combining
3 UC strong uncached
4 WB write-back
5 WT write-through
6 WC write-combining
7 UC strong uncached
Table 28: x86_AMD64 caching attributes
The three PikeOS caching attributes P4_M_C_ENABLE, P4_M_C_WRITEBACK and P4_M_C_PREFETCH are trans- lated to specific values of the PAT, PCD and PWT bits in the page tables. The attributes P4_M_C_COHERENCY, P4_M_C_PLATFORM1 and P4_M_C_PLATFORM2 are not supported and ignored. Since memory coherency is al- ways ensured on the x86 architecture, the P4_M_C_COHERENCY attribute is always set when querying memory attributes. Table 29 shows the relation, PAT bit is always set to zero.
P4_M_C_ P4_M_C_ P4_M_C_ PCD PWT Description ENABLE WRITEBACK PREFETCH 0 x 0 1 1 Strong uncached 0 x 1 1 0 Uncached with write-combining 1 0 x 0 1 Caching enabled cache strategy is write-through 1 1 x 0 0 Caching enabled cache strategy is write-back
Table 29: x86_AMD64 caching attributes
A.6.4 VMIT Cache Modes
The VMIT cache modes map to the settings listed in table 30, PAT bit is set to zero.
VMIT cache mode Kernel cache PCD PWT Description
attributes
VM_MEM_CACHE_CB P4_M_C_WB 0 0 write-back cacheable
VM_MEM_CACHE_WT P4_M_C_WT 0 1 write-through cacheable
VM_MEM_CACHE_INHIBIT P4_M_C_UC 1 1 uncached
VM_MEM_CACHE_WC P4_M_C_WC 1 0 write-combining uncached
VM_MEM_CACHE_DEV P4_M_C_DEV 1 1 uncached
Table 30: x86_AMD64 VMIT cache modes
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Translation of Architecture Specific Exceptions to PikeOS Trap Codes 81
A.7 Translation of Architecture Specific Exceptions to PikeOS Trap Codes
When CPU generates an exception, the CPU exception vector number is stored in the vector member and optional CPU exception error code (or zero) is stored in the error member of user mode context. The PikeOS transforms the CPU exception to the PikeOS exception message stored in the ex_code member as noted in the table below. Then, PikeOS propagates the exception to the user mode routines. Regular interrupts (and special exceptions) are forwarded to the PSP for the processing. The meaning of vector is redefined if PikeOS indicates the page fault exception using P4_TRAP_SEG exception code. In this case the vector member contains the page fault address.
Vector / Exception Trapcode Description 0 / DIV0 P4_TRAP_ARI Division by 0 1 / DEBUG P4_TRAP_BRK Debug 2 / NMI - routed to PSP machinecheck() handler 3 / BREAK P4_TRAP_BRK Breakpoint 4 / INTO P4_TRAP_ARI Overflow 5 / Boundary P4_TRAP_TRP Boundary 6 / INVOP P4_TRAP_ILL Invalid Opcode 7 / COPRNA P4_TRAP_FP_UNAVAIL FPU not enabled, see A.5.3 8 / DBLF System halted Double fault 9 / COPRSEGOVRN P4_TRAP_FP FPU segment violation 10 / INVTSS P4_TRAP_BUS Invalid TSS 11 / SEGNP P4_TRAP_BUS Segment not present 12 / STKF P4_TRAP_BUS Stack fault 13 / GPF P4_TRAP_BUS General protection fault 14 / PF P4_TRAP_SEG Page fault 15 (undefined) - routed to PSP machinecheck() handler 16 / COPRERR P4_TRAP_FP FPU error 17 / ALIGN P4_TRAP_BUS Alignment exception 18 / MCHECK - routed to PSP machinecheck() handler 19 / SIMD P4_TRAP_FP SSE error 20 / VE (Intel only) - routed to PSP machinecheck() handler 21 .. 28 (undefined) - routed to PSP machinecheck() handler 29 / VC (AMD only) - routed to PSP machinecheck() handler 30 / SX (AMD only) - routed to PSP machinecheck() handler 31 (undefined) - routed to PSP machinecheck() handler 32 .. 255 P4_TRAP_BUS Hardware interrupts
Table 31: Translation of x86_AMD64 specific exceptions to PikeOS trap codes
For an exception of type P4_TRAP_BUS, the P4_PF_READ, P4_PF_WRITE and P4_PF_EXEC flags are never set. The x86 architecture does not report the type of access that caused the exception. The SYSCALL and SYSENTER instructions generate different exceptions under different conditions depending on a CPU manufacturer or PikeOS system mode (see table 32).
Vendor Vector Trapcode Description AMD 6 P4_TRAP_ILL 32 / 64-bit CS, SYSENTER instruction invocation
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
82 Architecture Dependencies
Vendor Vector Trapcode Description Intel 6 P4_TRAP_ILL 32-bit CS, SYSCALL instruction invocation Intel 13 P4_TRAP_BUS 32 / 64-bit CS, SYSENTER instruction invocation AMD / Intel 257 P4_TRAP_SYS 64-bit CS, SYSCALL instruction invoked from PikeOS SYSEMU state AMD - - 32-bit CS, SYSCALL instruction invocation causes no exception
Table 32: Vendor specific trap codes
A.8 Memory Usage
A.8.1 Kernel Resources
Kernel memory is allocated in units whose size depend on the thrinfo_size configuration parameter. The maximum configurable thrinfo_size for the architecture is 4 pages (0x4000). The minimum and default is two pages (0x2000 bytes). There are no special alignment requirements for kernel resources. Kernel uses the resources listed in table 33 for the mappings and threads.
Size in Units Resource Description 4 or 5 Task Task descriptor, thread directory, IO permission bitmap and optionally PML4 paging structure 1 Thread Thread control block (1 TCB per thread) 1 Page table 1 per 2 MiB mapping 1 Page directory 1 per 1 GiB mapping 1 Page directory pointer table 1 per 512 GiB mapping
Table 33: x86_AMD64 kernel resources
A freshly activated task without any threads consumes four or five units (one unit for the task descriptor, one unit for thread directory and two for I/O permission bitmap. Without Meltdown workaround activated, one unit is used for the PML4 paging structure. Each thread started in the task consumes one unit. One idle thread is allocated on each CPU, and one unit is allocated on each CPU to host a scheduler stack. A user space mapping created in an untouched 2 MiB area needs three units to do the mapping as indicated in the table above. If any other mapping fits already touched 1 GiB region only one unit per 2 MiB area is allocated. The maximum number of supported interrupts is 512.
A.9 Cache Handling
The x86 PSP implements the cache operations exported in the p4_cache() kernel API as table 34 shows.
Cache Operation Description
P4_INVAL_ICACHE_RANGE Always returns P4_E_OK, as the architecture maintains coherency
between instruction data caches.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Speculative Execution Side Channels Mitigations - Meltdown, Spectre and MDS 83
Cache Operation Description
P4_FLUSH_DCACHE_RANGE, Flush and invalidate cache contents in all levels of the cache hierar-
P4_SYNC_DCACHE_RANGE, and chy using the CLFLUSH instruction.
P4_INVAL_DCACHE_RANGE
Table 34: x86_AMD64 cache handling
The x86 architecture has no issues with aliases in the instruction cache, the alias parameter in p4_cache() is always ignored. The x86 architecture does not support addressing individual levels of the cache architecture and always flushes all cache levels, therefore the flags parameter in p4_cache() is ignored. On a time partition switch, if one of the VM_SCF_INVAL_ICACHE or VM_SCF_FLUSH_DCACHE window flags are configured in VMIT, the x86 PSP uses the WBINVD instruction to flush all cache levels. The p4_inval_icache_range() function does nothing on this architecture. The p4_flush_dcache_range(), p4_sync_dcache_range(), and p4_inval_dcache_range() func- tions call p4_cache() internally. All cache operations using CLFLUSH are preceded and followed by MFENCE instructions. Please consult the Intel x86 Architecture Software Developer Manuals for the exact description of the CLFLUSH and WBINVD instructions and their effects on the cache hierarchy in the SMP system.
A.10 Speculative Execution Side Channels Mitigations - Meltdown, Spectre and MDS
PikeOS contains mitigations against the following processor vulnerabilities:
• CVE-2017-5753 Spectre "Bounds Check Bypass" (Variant 1)
• CVE-2017-5715 Spectre "Branch Target Injection" (Variant 2)
• SpectreRSB "Spectre RSB" (Variant 2)
• CVE-2017-5754 Meltdown "Rogue Data Cache Load" (Variant 3)
• CVE-2018-3665 Spectre "Lazy FPU state restore" (Variant 3a)
• CVE-2018-3639 Spectre "Speculative Store Bypass" (Variant 4)
• CVE-2018-3620 L1 Terminal Fault known as Foreshadow
• CVE-2018-12126 MSBDS Microarchitectural Store Buffer Data Sampling
• CVE-2018-12130 MFBDS Microarchitectural Fill Buffer Data Sampling
• CVE-2018-12127 MLPDS Microarchitectural Load Port Data Sampling
• CVE-2019-11091 MDSUM Microarchitectural Data Sampling Uncacheable Memory
• CVE-2019-1125 Spectre "Bounds Check Bypass" (SWAPGS Variant)
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
84 Architecture Dependencies
These mitigations may have a significant performance impact on the system with respect to a system that does not implement these mitigations. Since the Spectre, Meltdown or MDS vulnerabilities only violate the confidentiality property of secure systems, a system not subject to this requirement may consider disabling the mitigations (see options below) to re-gain CPU performance. Some of these mitigations can be controlled through PSP configuration options, see section 3.5.2, page 20. Each configuration option might be set to 0, 1 or 2. The graphical configurator will show them as "Automatic" resp. "Enabled" resp. "Disabled". If the "Automatic" option is selected, that particular option will be enabled or disabled on demand, depending on the particular CPU on which PikeOS runs. The "Automatic" option may require certain CPU features to be present which are installed via microcode updates. If the requested feature is missing, the PSP prints a warning message during startup, but the system continues to boot. The overview of what is currently activated is printed during system startup, see section A.11, page 86. It is recommended to manually change all "Automatic" options to either "Enabled" or "Disabled", as the safe defaults might be different in the future. If the "Enabled" option is selected, that particular feature is always enabled, regardless of the installed CPU, and, if some CPU feature is missing, the PSP prints an error message and halts. If the "Disabled" option is selected, then this feature is disabled. Both AMD and Intel provide documents with suggested mitigation techniques for different CPUs. Please check https://www.intel.com/content/www/us/en/architecture-and-technology/ facts-about-side-channel-analysis-and-intel-products.html and https://software. intel.com/security-software-guidance/ for details of this problem on Intel CPUs and https://www.amd.com/en/corporate/speculative-execution for AMD CPUs. It is important to disable hyperthreading in the BIOS and use the latest BIOS versions with updated microcode versions as suggested by the CPU vendors, even if the IBRS/IBPB or Speculative Story Bypass features are not used. The PSP can perform the microcode update, see section 3.4, page 18 for details. The PSP print the CPUID string and the microcode version if boot message level is set to at least 3. The following table summarizes all mitigations provided in PikeOS and their control and description.
Vulnerability Mitigation Location Mitigation Description CVE-2017-5754 PSP property Use separate address spaces when running in psp/meltdown_workaround userspace and when running in kernelspace. This isolation protects kernel code and data from the Meltdown attack. AMD CPUs are not affected. Fu- ture Intel CPUs without the vulnerability will be de- tected. CVE-2017-5753 C macro P4_FENCE_INDEX() A new C macro is introduced to stop the Spec- tre Variant 1 speculation attack. The C macro P4_FENCE_INDEX() is described in PikeOS Ker- nel Reference Manual, section 1.40.1, page 567. The usage of this C macro in the application code depends on the results of the vulnerability analy- sis of your particular application or KDEV driver. The kernel always uses P4_FENCE_INDEX() to stop speculation for user-provided index values, e.g. task and thread IDs or file descriptors.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Speculative Execution Side Channels Mitigations - Meltdown, Spectre and MDS 85
Vulnerability Mitigation Location Mitigation Description CVE-2017-5715 GCC Compiler Options The compiler can be instructed to stop the gener- ation of indirect CALLs and JMPs and use "retpo- line" instead. PikeOS uses "retpoline" as the de- fault set of compiler options for kernel, PSP and KDEV drivers. The libgcc contains the necessary "retpoline" thunks. CVE-2017-5715, PSP property Stuff the RSB predictor on kernel entry (during SpectreRSB psp/spectre_v2_rsb_cpl userspace to kernelspace switch). This may be required only on certain CPUs without SMEP sup- port. If psp/spectre_v2_rsba is enabled, stuff- ing the RSB is already performed and this option may remain disabled. CVE-2017-5715, PSP property Stuff the RSB predictor during PikeOS thread con- SpectreRSB psp/spectre_v2_rsb_ctx text switch and SYSEMU state switch. CVE-2017-5715 PSP property Stuff the RSB predictor whenever entering the ker- psp/spectre_v2_rsba nel or interrupting the kernel again. This option should be enabled only on CPUs from Skylake gen- eration and its close derivates (or on CPUs report- ing alternate RSB behavior). On such CPUs, this option is needed to make retpoline mitigation effec- tive. Full protection can be achieved only when us- ing costly IBRS mitigation option instead. CVE-2017-5715 PSP property Disable Indirect Branch Speculation when enter- psp/spectre_v2_ibrs ing the kernel, either by using the IBRS or the IBRS_ALL mechanism. This may be required only on certain CPUs. The new IBRS_ALL feature is used when available. CVE-2017-5715 PSP property Invoke an Indirect Branch Predictor Barrier on a psp/spectre_v2_ibpb PikeOS address space switch. This may be re- quired only on certain CPUs. CVE-2018-3665 PSP property Clear the FPU context on lazy FPU disable. This psp/spectre_lazy_fpu_clear may be required only on certain CPUs. CVE-2017-5715 PSP property Detect SMIs and halt the system, see section 3.5.6, psp/smi_watchdog page 29. This may be required only on certain CPUs. CVE-2017-5715 SMEP CPU feature Stop execution (even speculative one) of user code while in kernel mode. CVE-2017-5715, Hyperthreading BIOS option Disable Hyperthreading in the BIOS to stop side CVE-2018-3620, channel attacks on sibling CPU threads. Hyper- CVE-2018-12126, threading needs to be disabled on all CPUs which CVE-2018-12130, supports hyperhreading. CVE-2018-12127, CVE-2019-11091
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
86 Architecture Dependencies
Vulnerability Mitigation Location Mitigation Description CVE-2017-5715, Latest microcode If the latest microcode is not available in the most CVE-2018-3639 recent BIOS provided by the hardware vendor, and others please refer to section 3.4, page 18 on how to up- date the microcode in PikeOS. CVE-2018-3639 PSP property If enabled, the Speculative Store Bypass will be psp/spectre_v4_ssbd disabled in the CPU. CVE-2018-3620 ASP / PSP PikeOS always sets the not present paging struc- ture entries to zero. CVE-2018-12126, PSP property If enabled, Microarchitectural Data Sampling CVE-2018-12130, psp/mds_workaround (MDS) workaround will be activated and microar- CVE-2018-12127, chitectural state will be flushed using the VERW in- CVE-2019-11091 struction functionality retrospectively defined by In- tel and supported with latest microcode updates. The flush is performed when returning to the userspace from kernel. Note: If a NMI triggers just before the kernel is about to exit to the user space but after the VERW instruction was already executed, the flush- ing when exiting the NMI is not performed and the vulnerability is not mitigated for this particular cor- ner case. In the standard PikeOS PSP, NMI is never invoked for anything else than system shut- down.
CVE-2019-1125 ASP PikeOS always issues the speculation barrier in the affected code paths.
A.11 Hardware Dependent Features
The ASP supports optional hardware features or workarounds that may be supported only by some CPUs. Such features are configured by the PSP and passed to the ASP via the PSP Descriptor. The features will be finally initialized by the ASP, printed during startup as provided in the example below and exported to the kernel info page.
PikeOS (C) Copyright SYSGO AG, Germany ROM image build: devel-pikeos@builder.sysgo.com-250317-00:14 Kernel build: D5.0-1839, type: assert tracesys smp standard [gcc] ASP: "x86_amd64" x86_64 NX SMEP SMAP RDTSCP AVX XSAVE ...
The following table describes the CPU features exported as cpu_features member of the kernel info page (see section A.4, page 72). The "Symbol Name" column corresponds to the define exported by the PikeOS. The "Printed" column corresponds to the feature name printed during PikeOS startup.
Symbol Name Printed Description P4_X86_CPU_NX NX NX CPU feature is enabled (mandatory)
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Hardware Dependent Features 87
Symbol Name Printed Description P4_X86_CPU_SMEP SMEP SMEP CPU feature is enabled P4_X86_CPU_SMAP SMAP SMAP CPU feature is enabled (available only in debug kernels) P4_X86_CPU_RDTSCP RDTSCP If a CPU supports RDTSCP instruction, the ECX reg- ister will contain the same value as returned with a p4_my_cpuid() function. P4_X86_CPU_AVX AVX AVX CPU feature is enabled. P4_X86_CPU_XSAVE XSAVE XSAVE CPU feature is enabled. P4_X86_CPU_XSAVEOPT XSAVEOPT XSAVEOPT CPU feature is enabled. P4_X86_CPU_PG1G PG1G Large 1 GiB pages may be used by the PSP. P4_X86_CPU_PCID PCID PCID CPU feature is enabled, currently only used to speedup the MELTDOWN workaround. P4_X86_CPU_AMD AMD CPU vendor is AMD, workaround for SS descriptor cache wrong after SYSRET is active. P4_X86_CPU_INTEL INTEL CPU vendor is Intel
The PSP enables the features if they are supported by the CPU. Currently, only a debug override is provided to alter the detected CPU features by the PSP, see section 4, page 22 for further details. Setting the p4/kernel/boot_message property to 3 or more enables printout of the additional CPU information such as CPU model and CPU family, and stepping during PSP startup. The following table describes the CPU features exported as alt_features member of the kernel info page (see section A.4, page 72). The "Symbol Name" column corresponds to the define exported by the PikeOS. The "Printed" column corresponds to the feature name printed during PikeOS startup. Most of the features are user configurable, see the "Description" column for further details.
Symbol Name Printed Description P4_X86_ALT_MELTDOWN_WORKAROUND MELTDOWN Meltdown workaround is enabled, see sec- tion A.10, page 83. P4_X86_ALT_SPECTRE_V2_IBRS IBRS IBRS workaround is enabled, see section A.10, page 83. P4_X86_ALT_SPECTRE_V2_IBRS_ALL IBRS-ALL IBRS workaround (set only once during startup) is enabled, see section A.10, page 83. P4_X86_ALT_SPECTRE_V2_IBPB IBPB IBPB barrier is enabled, see section A.10, page 83. P4_X86_ALT_RSB_CLEAR_ON_CTX_SWITCH RSB-CTX RSB clearing on address space switch is enabled, see section A.10, page 83. P4_X86_ALT_RSB_CLEAR_ON_CPL_SWITCH RSB-CPL RSB clearing on CPL switch is enabled, see section A.10, page 83. P4_X86_ALT_FPU_CLEAR_ON_LAZY_DISABLE LAZY-FPU FPU clearing on context switch is enabled, see section A.10, page 83. P4_X86_ALT_AMD_SER_LFENCE LFENCE Dispatch serializing LFENCE on AMD is enabled. This is a default behavior on In- tel CPUs. P4_X86_ALT_MCE_ON MCE Machine check exception is enabled, see section 4, page 22.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
88 Architecture Dependencies
Symbol Name Printed Description P4_X86_ALT_TSCDIS TSC-DIS TSC access is disabled, see section 4, page 22. P4_X86_ALT_AMD_FPU_LEAK CLR-FERR AMD FPU error pointers leak workaround is enabled. Older AMD CPUs do not save/restore FPU error pointers unless an FPU exception is pending. If set, perform the workaround by clearing the affected registers during context switch. P4_X86_ALT_SPECTRE_V4_SSBD SSBD If set, Speculative Store Bypass feature is disabled, see section A.10, page 83. P4_X86_ALT_MDS_WORKAROUND MDS If set, Microarchitectural Data Sampling workaround is active, see section A.10, page 83.
Please consult the /opt/pikeos-D5.0/target/x86/amd64/include/kernel/p4kinfoarch.h file for the bitmask definitions.
A.12 Limitations
The PikeOS kernel does not support setting up an own Local Descriptor Table (LDT). The usage of the 16-bit protected mode is not supported. The AVX-512 is currently unsupported. The amount of memory currently supported by the PikeOS kernel is limited to 127 TiB on the x86 platform. A CPU or a PSP may impose lower limit see the section 3, page 15 for the details. Only the first 64 processors will be used, if the target system supports more than 64 processors.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
B Boards Fusion/PSP Projects
This chapter gives a table referencing for each available board the corresponding example projects. The example projects can be used as starting points for creating modified fusion and PSP projects. The example fusion projects are located in the /opt/pikeos-D5.0/demo/fusion-kernel and /opt/pikeos-D5.0/demo/fusion-pssw directories. The example PSP projects are located in the /opt/pikeos-D5.0/demo/psp directory.
Board Name Kernel Fusion PSSW Fusion PSP ic-int-vpx3a-64 x86-64 standard x86-64 kontron-come-bbd6-64 x86-64 standard x86-64 kontron-vx3035-64 x86-64 standard x86-64 qemu-x86-64 x86-64 standard x86-64 x86-64 x86-64 standard x86-64
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
C Glossary
BASE Service Library: The BASE service library provides general purpose data types and services for devel- oping device drivers.
BLK Class: The BLK class defines client and configuration interfaces for drivers for mass storage devices, such as computer drives or flash memories.
BLK Service Library: The BLK service library provides data types and services for developing drivers for mass storage devices, such as computer drives or flash memories.
Block Device: A block device can be a hard disk or a solid state disk but e.g. also a USB flash drive. Block devices always allow a block of any size (including single characters/bytes) and any alignment to be read or written.
CAN Class: The CAN class defines client and configuration interfaces for CAN bus device drivers.
CAN Service Library: The CAN service library provides data types and services for developing CAN bus device drivers.
CHAR Class: The CHAR class defines client and configuration interfaces for generic I/O device drivers.
CHAR Service Library: The CHAR service library provides data types and services for developing generic I/O device drivers.
DIO Class: The DIO class defines client and configuration interfaces for digital I/O device drivers.
DIO Service Library: The DIO service library provides data types and services for developing digital I/O device drivers.
MTD: Memory Technology Device, a type of device file interacting with flash memory (NOR, NAND), not to be confused with non-raw flash devices, e.g. USB flash drives.
NET Class: The NET class defines client and configuration interfaces for Ethernet device drivers.
NET Service Library: The NET service library provides data types and services for developing Ethernet device drivers.
PCI Service Library: The PCI service library provides data types and services for accessing devices on the PCI bus.
SER Class: The SER class defines client and configuration interfaces for serial UART device drivers.
SER Service Library: The SER service library provides data types and services for developing serial UART device drivers.
SYS Service Library: The SYS service library provides data types and services for accessing devices on the system bus (non-PCI).
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.