HAL OS layout and headers

Hardware Abstraction Layer

» HAL/OS layout and headers

The OS is linked to run at a particular base address. Pre-HAL OS’s were linked to run at <n>MB (in logical space), that is on a MB alignment to allow efficient MMU section mapping. In HAL-based OS versions this is still true, however it will be the HAL that is located on the megabyte boundary and not the kernel. The kernel (and the rest of the OS modules) will be located at an offset defined by the HALSize parameter defined in the platform’s build environment file (note this setting must also match the kernel offset specified in the components file). During the build, the HALSize value is exposed to assembler components via the OSROM_HALSize constant, assuming you have a GET Hdr:HALSize.<HALSize> statement within your assembler sources.

Note that for section-mapping to be possible, the HAL must make sure the HAL + OS are aligned correctly in physical space (i.e. combined HAL + OS starts on a megabyte boundary). Other offsets are supported (down to 4k page size), but will result in less efficient TLB usage.

OS image header

The OS starts with a header including a magic word – this aids probing and location of images. The OS header format is defined as:

Word 0: Magic word ("OSIm" - &6D49534F)
Word 1: Flags
            bit 0 => image supports compression
            bits 1-31 reserved
Word 2: Image size (bytes)
Word 3: Offset (bytes) from OS base to table of OS routine entry points
Word 4: Number of entries in table
If the 'supports compression' flag is set:
Word 5: Compressed image size (bytes)
Word 6: Offset (bytes) from OS base to decompression header
Word 7: Compression offset (bytes)

For details of how compressed ROMs operate, see the Compressed ROMs page.

Because the OS image header is located right at the start of the OS image, it’s typically very easy for the HAL to locate it via use of the OSROM_HALSize constant described above.

HAL descriptor block

The HAL itself should have whatever header is required to start the system. For example on ARM7500 16→32 bit switch code is required, and on the 9500 parts a special ROM header and checksum must be present. Unlike the OS image header, the HAL descriptor block can be placed at any (word-aligned) location within the HAL. A pointer to this block is passed by the HAL to the OS in the RISCOS_Start call:

Word 0: Flags
            bit 0 => uncachable workspace (32K) required
            bits 1-31 reserved
Word 1: Offset (bytes) from descriptor to start of HAL (will be <= 0)
Word 2: HAL size (bytes)
Word 3: Offset (bytes) from descriptor to table of HAL routine entry points
Word 4: Number of entries in table
Word 5: Size of HAL static workspace required (bytes)

See also HAL workspace for details on how the OS uses the HAL header to allocate the HAL’s workspace.

Information source: Kernel.Docs.HAL.HAL_API in CVS

Unused source: Kernel.Docs.HAL.Entries in CVS