BCOS Home » ... » ... » BCOS File Format Specifications » BCOS System File Format Specifications

BCOS Boot Module File Format Specification

Version 1.0

Project Map

Contents:

Tables:

Chapter 1: Overview

This specification defines the file format used for executable modules used during boot; including the Boot Abstraction Layer, any intermediate modules it uses, and each kernel's Kernel Setup module.

Chapter 2: Specification Change Policy

Any changes made in future versions of this specification are not guaranteed to be backward or forward compatible (however changes may be backward or forward compatible if possible).

In general, this specification, all boot loaders, the Boot Abstraction Layer, all intermediate boot modules, and all Kernel Setup modules need to be updated at the same time (so that everything complies with the same version of this specification). Tools (e.g. compilers) may support multiple versions of this specification.

Chapter 3: General File Structure

The basic structure of the file is described in Figure 3-1. File Structure.

Figure 3-1. File Structure
  End of file 
(Optional) Metadata
Data
Code 0x00000200
Digital Signature 0x00000080
Platform Header 0x00000038
Extended Header 0x00000030
Generic Header 0x00000000
Note: Not to scale.

Chapter 4: File Format

4.1. Generic File Header

This is the native file format header defined in BCOS Native File Format Specification. For this specification, the "file type" field in the generic header (at offset 0x00000028) must be set to one of the values described in Table 4-1. File Types for Boot Modules.

Table 4-1. File Types for Boot Modules
MajorMinorDescription
0xFFFF0xE00080x86 Boot Abstraction Layer
0xFFFF0xE00180x86 BAL Log Output Module
0xFFFF0xE00280x86 BAL CPU Detection Module
0xFFFF0xE00F80x86 32-bit Kernel Setup
0xFFFF0xE10F80x86 64-bit Kernel Setup

4.2. Extended Header

The Extended Header follows the Generic File Header, and is described in Table 4-2. Extended Header Format.

Table 4-2. Extended Header Format
OffsetSizeDescription
0x000000301 byteReliability rating (see Subsection 4.2.1. Major, Minor, Revision and Reliability Rating)
0x000000311 byteRevision number (see Subsection 4.2.1. Major, Minor, Revision and Reliability Rating)
0x000000321 byteMinor version number (see Subsection 4.2.1. Major, Minor, Revision and Reliability Rating)
0x000000331 byteMajor version number (see Subsection 4.2.1. Major, Minor, Revision and Reliability Rating)
0x000000344 bytesPlatform ID (see Subsection 4.2.2. Platform ID)

4.2.1. Major, Minor, Revision and Reliability Rating

All executables have both a version number and a reliability rating. This allows users to decide if they want to run the latest version (e.g. with all the new features) or an older more thoroughly tested version (that lacks newer features). The version numbers are not a "freestyle" string, where a developer can decide to use "Version 1.2.3.4" or "Version 1A". The operating system uses a standardized representation for version numbers, so that software can determine which version of an executable is older or newer than another (which makes it much easier for things like automated software updates).

For display purposes, the version number is displayed as the major version number (with leading zeros suppressed), followed by a decimal point, followed by the minor version number (with trailing zeros suppressed), followed by a dash, then the letter r, then the revision (with leading zeros suppressed). For example, if "major = 0x01", "minor = 0x20" and "revision = 0x1E", then the full version number would be displayed as "Version 1.32-r30".

The reliability rating provides an indication of how stable the software is meant to be; ranging from 0 (not stable at all) to 255 (extremely stable). As a general guide, see Table 4-3. Reliability Rating Values.

Table 4-3. Reliability Rating Values
Value/sMeaning
0 to 63Developer's unfinished work (typically untested and/or containing known and unknown faults)
64 to 127Alpha version (potentially containing both known and unknown faults)
128 to 191Beta version (potentially containing unknown faults)
192 to 223Stable version (potentially not containing unknown faults)
224 to 254Mature stable version (throughly tested by many users without any faults found)
255Extremely mature stable version (guaranteed to be free of all possible faults)

If the reliability rating is in the range from 0 to 63, then the text "-developer" will be appended to the version number when it is displayed (e.g. "Version 1.32-r30-developer"). If the reliability rating is in the range from 64 to 127, then the text "-alpha" will be appended to the version number when it is displayed (e.g. "Version 1.32-r30-alpha"). If the reliability rating is in the range from 128 to 191, then the text "-beta" will be appended to the version number when it is displayed (e.g. "Version 1.32-r30-beta"). Finally, if the reliability rating is equal to or higher than 192, then no text will be appended to the version number when it is displayed (e.g. "Version 1.32-r30").

In general it's important for developers to estimate the reliability rating as best they can. Under-estimating the reliability rating will probably have less effect on the developer's reputation than over-estimating the reliability rating.

4.2.2. Platform ID

The platform ID is used to determine the format for the remainder of the Boot Abstraction Layer file. The operating system uses the platform ID to make sure the executable file is compatible with the computer it is to be run on, and to arrange any special support needed. The platform ID is a 4 character ASCII string (without a zero terminator).

Defined platform IDs are listed in Table 4-4. Platform IDs, including a reference to the section within this document that describes the format for the Platform Header and executable code and data for each platform ID.

Table 4-4. Platform IDs
IDDescriptionSection
"8632"80x86 systemsSection 5.1. Platform ID '8632'

Note: For 80x86 systems, the Boot Abstraction Layer and all of it's modules are always 32-bit, and the Boot Abstraction Layer is responsible for determining if the CPUs support 64-bit code (and enabling long mode and loading a 64-bit kernel if possible). This means that there is no use for separate platform ID for 64-bit 80x86 systems. An 80x86 64-bit Kernel Setup module is 32-bit code that starts a 64-bit kernel, and not 64-bit code.

Chapter 5: Platform Headers

5.1. Platform ID '8632'

The Platform Header follows the Extended Header, and is described in Table 5-1. '8632' Platform Header.

Table 5-1. '8632' Platform Header
OffsetSizeDescription
0x000000384 bytesCode address (see Subsection 5.1.1. Code, Initialised Data, Uninitialised Data and Initialised Data End Addresses)
0x0000003C4 bytesInitialised data address (see Subsection 5.1.1. Code, Initialised Data, Uninitialised Data and Initialised Data End Addresses)
0x000000404 bytesUninitialised data address (see Subsection 5.1.1. Code, Initialised Data, Uninitialised Data and Initialised Data End Addresses)
0x000000444 bytesUninitialised data end address (see Subsection 5.1.1. Code, Initialised Data, Uninitialised Data and Initialised Data End Addresses)
0x000000484 bytesReserved (must be zero)
0x0000004C4 bytesEntry point (see Subsection 5.1.2. Entry Point)
0x0000005048 bytesReserved (must be zero)

5.1.1. Code, Initialised Data, Uninitialised Data and Initialised Data End Addresses

All of these fields of the '8632' Platform Header contain the addresses of various pieces after the executable file has been loaded into the virtual address space. Because these areas are contiguous, the end of one area is the same as the start of the next area (e.g. "Code end address" can be infered from the "Initialised data address" field). These fields are used (where possible) to determine "read, write, execute" permissions for the pages. The uninitialised data area is not included in the executable file, and the "uninitialised data end address" is used by the loader to allocate (and zero) pages for this area.

5.1.2. Entry Point

The "entry point" field in the Platform Header contains an address (not an offset from the start of the file) for the executable's entry point. This address must correspond to an address within the code area of the file.

Chapter 6: Digital Signature

The Digital Signature follows the Platform Header, and is described in Table 6-1. Digital Signature Structure.

Table 6-1. Digital Signature Structure
OffsetSizeDescription
0x00000080124 bytesFirst 968-bits of hash padding
0x000000FC4 bytesLast 1080-bits of hash padding
0x00000100256 bytesEncrypted hash

6.1. Signing

Digitally signing a file involves several steps:

6.2. Signature Check

Checking a digital signature involves several steps:

6.3. Public Keys

The public key has 2 parts - the public key exponent and the public key modulus.

The public key is either stored directly in the OS's boot loader (typical for BIOS boot loaders) or loaded from a file by the OS's boot loader (typical for UEFI boot loaders). It's the boot loader's responsibility to ensure the public key hasn't been tampered with using any means possible. All boot modules and all kernel modules must be digitally signed using the same private key, and a file's digital signature must be checked before the file is used.

The public key identifies the signer. It is intended that the signer be the owner of the cluster (e.g. where the cluster owner uses a utility to sign the OS's files before installing the OS on computers).

Generated at 14:54:27 on the 3rd of February, 2017 (UTC)