2. WrmOS: configuration

← 1. WrmOS: build system

3. WrmOS: bootloader →

Contents
2.1 Overview
2.2 Build environment variables
2.3 Project configuration parameters
2.4 Platform configuration parameters
2.5 Alpha run-time configuration

2.1 Overview [up]


All configuration files generally are located in cfg/ directory. It contains project configurations that describe target system parameters, building parameters, toolchain path, kernel parameters, list of target applications, alpha configuration and other. For convenience all files are grouping at 3 directories:

cfg/plt/ Platform configurations. They describe target platform parameters — CPU, memory, clock frequency, timer, UART and MMU.
cfg/prj/ Project configurations. They describe building parameters, list of applications, path to toolchain. Here including platform file from cfg/plt/ directory and specify alpha configuration file from cfg/alph/.
cfg/alph/ Root-task configurations. They are processing by root-task Alpha in run-time. They describe applications to run and their capabilities.

Some mandatory parameters are defined in cfg/base.cfg.

Configuration looks like this:

make-param-P --> cfg/prj/project-name.prj --> build-system
                               ↑  ↑  ↑          ↓
   cfg/plt/platform-name.plt --+  |  |          +--> environment variables
   cfg/alph/alpha-config.alph ----+  |          +--> generate configuration h-file
   cfg/base.cfg ---------------------+          +--> build libraries
                                                +--> build kernel
                                                +--> build applications
                                                +--> build RAMFS with alpha config and ELFs
                                                +--> build bootloader with RAMFS image

2.2 Build environment variables [up]


While building in Makefiles and configuration files are available the next variables:

wrmdir root of WrmOS sources directory
blddir build directory specified by build options B=<build-dir-name>

2.3 Project configuration parameters [up]


Project configuration file is locate in cfg/prj/ directory and must contents the next parameters:

Parameter Description Example
plt_file Path to platform configuration file. plt_file = $(wrmdir)/cfg/plt/x86-qemu-q35.plt
gccprefix Prefix for GCC toolchain. gccprefix = i686-linux-
usr_lib_dbg Debug flags for libraries, kernel, applications and bootloader. My be 0 or 1. It allows to use debug configuration with asserts, additional debug outputs and other (for 1) or use release configuration (for 0). usr_lib_dbg = 1
usr_krn_dbg usr_krn_dbg = 1
usr_app_dbg usr_app_dbg = 1
usr_ldr_dbg usr_ldr_dbg = 1
usr_krn_log Kernel logging enable flag. May be 0 or 1. It enables internal kernel logging, that allow to see kernel activities and actions. usr_krn_log = 1
usr_ramfs

List of RAMFS files. These files will be built and put to RAMFS. Each list item has format:
<ramfs-file-name>:<host-file-path>
Before  colon — file name in RAM filesystem, it used by root-task Alpha in run-time.
After colon — path to file in host filesystem.
In cfg/base.cfg configuration file to this list is adding additional 3 files — kernel.elf, sigma0.elf and roottask.elf.

usr_ramfs = config.alph:$(wrmdir)/cfg/alph/hello.alph
usr_ramfs += hello.elf:$(blddir)/app/hello/hello.elf

After all parameters must be including of cfg/base.cfg file:

include $(wrmdir)/cfg/base.cfg

2.4 Platform configuration parameters [up]


Platform configuration file is locate in cfg/plt/ directory and must contents the next parameters:

Parameter Description Example
System parameters
arch Target CPU architecture. It specifies architecture specifics for libraries, kernel and applications. arch = x86
arch_ver Version of target CPU architecture. It specifies specifics for architecture version components of libraries, kernel and applications. arch_ver = armv7-a
cpu Target CPU model. It specifies CPU specifics for libraries, kernel and applications. cpu = q35
plat Target platform name. It specifies platform specifics for libraries, kernel and applications. plt = qemu
brd Target board name. It specifies board specifics for libraries, kernel and applications. brd = qemu_q35
max_cpus Maximum numbers of CPU cores. max_cpus = 2
sys_clock_hz System clock in hertz. sys_clock_hz = 1193182
ram_start Start address of physical RAM memory. ram_start = 0x100000
# skip 1 MB for low-memory, needs for x86
ram_sz Size of physical RAM memory in bytes. ram_sz = 0x800000
page_sz Page size in bytes. page_sz = 0x1000
Kernel parameters
krn_vaddr Start of kernel virtual addresses. krn_vaddr = 0xf0100000
# skip 1 MB for low-memory, needs for x86
krn_tick_usec Kernel tick in microseconds. Kernel periodically timer will tick every krn_tick_usec microseconds. krn_tick_usec = 10000
krn_uart_paddr Kernel UART physical address. For x86 architecture it specifies MMIO device address (page aligned part of address) and IO-port (lowest 12 bits). krn_uart_paddr = (0xb8000 + 0x3f8)
# video_mem + ioport_COM1_addr
krn_uart_sz Kernel UART size in bytes. For x86 architecture it specifies MMIO device size (0x10 aligned part of size) and IO-port size (lowest 4 bits). krn_uart_sz = (0x1000 + 0x8)
# video_sz  + ioport_COM1_sz
krn_uart_bitrate Kernel UART bitrate. krn_uart_bitrate = 115200
krn_uart_irq Kernel UART interrupt number. krn_uart_irq = 4
krn_intc_paddr Interrupt Controller physical address. For x86 architecture don't need and must be 0x1 to disable kernel mapping of Interrupt Controller. krn_intc_paddr = 0x1
# lowest bit 1 — don't need kmap
krn_intc_sz Interrupt Controller size in bytes. For x86 architecture don't need and must be 0. krn_intc_sz = 0x0
krn_timer_paddr Kernel Timer physical address. For x86 architecture don't need and must be 0x1 to disable kernel mapping of Kernel Timer. krn_timer_paddr = 0x1
# lowest bit 1 — don't need kmap
krn_timer_sz Kernel Timer size in bytes. For x86 architecture don't need and must be 0. krn_timer_sz = 0x0
krn_timer_irq Kernel Timer interrupt number. krn_timer_irq = 0
Bootloader parameters
ldr_uart_paddr Bootloader UART physical address. For x86 architecture it specifies MMIO device address (page aligned part of address) and IO-port (lowest 12 bits). ldr_uart_paddr = (0xb8000 + 0x3f8)
# video_mem + ioport_COM1_addr
ldr_uart_bitrate Bootloader UART bitrate. krn_uart_bitrate = 115200
Base platform devices
plt_uart Platform UART name. It specifies UART driver for Kernel and Bootloader. plt_uart = x86_8250
plt_intc Platform Interrupt Controller name. It specifies kernel driver for Interrupt Controller. plt_intc = x86_8259
plt_timer Platform Timer name. It specifies kernel driver for Timer. plt_timer = x86_8253
plt_mmu Platform MMU name. It specifies kernel driver for MMU. plt_mmu = x86_mmu

2.5 Alpha run-time configuration [up]


Alpha run-time configuration file has the next view:

# config for roottask
# mmio devices
DEVICES
        #name     paddr        size        irq
        uart      0x12345678   0x100       12

# named memory regions
MEMORY
        #name      sz      access  cached  contig
        uart_buf   0x1000  rw      0       1

# applications
APPLICATIONS
    {
        name:             hello
        short_name:       hell
        file_path:        ramfs:/hello.elf
        stack_size:       0x1000
        heap_size:        0x0
        aspaces_max:      1
        threads_max:      3
        prio_max:         100
        fpu:              off
        malloc_strategy:  on_startup
        devices:
        memory:
        args:             arg1=123, arg2=345
    }

Alpha run-time configuration contents 3 sections:

  • device table
  • named memory table
  • application table

File format

Configuration file format has the following rules:

  • every line starting from '#' is comment and ignored;
  • every section is started from its name — DEVICES, MEMORY or APPLICATIONS.

Device table

The device table has the view:

DEVICES
        #name     paddr        size        irq
        uart      0x12345678   0x100       12

Device table describes of used system devices. Table starts from key word DEVICES. Every table row corresponds to one device. Table consists from 4 columns:

Column Field name Description
1 name Name of MMIO device. This name will be used by user application to get access to it.
2 paddr Physical address of MMIO device.
3 size Size of MMIO devices in bytes.
4 irq Interrupt number of MMIO devices. Value '-1' means interrupt does not used.

Named memory table

The named memory table has the view:

MEMORY
        #name      sz      access  cached  contig
        uart_buf   0x1000  rw      0       1

Named memory table describes of named memory regions. Named memory needs to allows to user applications use memory with required properties — size, access permissions, cached or not, contiguous or not. Table starts from key word MEMORY. Every table row corresponds to one memory region. Table consists from 5 columns:

Column Field name Description
1 name Name of memory region. This name will be used by user application to get access to it.
2 size Size of memory region in bytes.
3 access Access permissions of memory region. Value may be combination of characters — 'r', 'w' and 'x' (read, write and executable).
4 cached Cached flag of memory region. 0 — not cached, 1 — cached.
5 contiguous

Contiguous flag of memory region. 0 — not contiguous, 1 — contiguous.

Application table

The application table has the view:

APPLICATIONS
    {
        name:             hello
        short_name:       hell
        file_path:        ramfs:/hello.elf
        stack_size:       0x1000
        heap_size:        0x0
        aspaces_max:      1
        threads_max:      3
        prio_max:         100
        fpu:              off
        malloc_strategy:  on_startup
        devices:
        memory:
        args:             arg1=123, arg2=345
    }

Application table describes of user applications and their parameters. It will be used by root-task Alpha to start applications on system startup. Every application description is started by line with character '{' and terminated by line with character '}'. Between  this lines there is a application parameters. Every parameter there is in separate line. Parameter starts from "parameter-name:", after that there is a parameter value. There are the next parameters:

Name Mandatory Description
name mandatory Application name.
short_name mandatory Application short name — 4 characters. It is used to prefixed application output.
file_path mandatory Path to executable file path in RAMFS. It has view "ramfs:/filename.elf".
stack_size mandatory Stack size for main (first) thread in application.
heap_size optional Size of memory that root-task Alpha will give to application on its startup. Application may get this memory by Memory Pool WrmOS API. Default value is 0.
aspaces_max mandatory Number of address spaces allowed for this application. Must be >=1.
threads_max mandatory Number of threads allowed for this application. Must be >=1.
prio_max mandatory Maximal value of thread priority from range: 1 (lowest) .. 255 (highest).
fpu optional FPU enable flag. 0 — application does not use FPU. 1 — application use FPU. By default 0.
malloc_strategy optional Memory allocating strategy.
on_startup — allocate all memory (data, code, bss) for application on its startup, it allows be sure memory enough;
on_pagefault — allocate memory (data, code, bss) for application page by page on pagefault, it allows not allocate memory if not need.
on_startup requires some time for allocating on application startup, but not need any time for allocating in run-time.
devices optional Comma separated list of device names. Names must be correspond devices from Device Table.
memory optional Comma separated list of named memory names. Names must be correspond memory regions from Named Memory Table.
args optional Space separated strings. They will accessible by user application as main(argc, argv[]) function incoming argument list.

← 1. WrmOS: build system

3. WrmOS: bootloader →