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

BCOS Boot Image File Format Specification

Preliminary Draft

Project Map

Contents:

Tables:

Chapter 1: Overview

A Boot Image is an archive of files, including a directory structure, that is loaded into RAM early during boot and used by boot code to find any files that are needed before the virtual file system is available.

The Boot Image is also used to initialize the virtual file system, so that the directory structure and files that were contained in the Boot Image become available using normal file I/O after boot (e.g. using something like a RAM disk). After boot the virtual file system sychronizes with any file systems, so that (for example) when the operating system is being installed and a new/empty file system is mounted at "/" the directory structure and files that were contained in the Boot Image will be written to the new file system.

The Boot Image itself consists of entries, where each entry describes a directory or a file.

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, the Boot Abstraction Layer, and any other software that works with Boot Images need to be updated at the same time (so that everything complies with the same version of this specification). Tools 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 Layout.

Figure 3-1. File Layout
  End of file 
(Optional) Metadata
Boot Image Entries
Extended Header 0x00000030
Generic File Header 0x00000000
 
Note: Area sizes 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.

4.2. Extended Header

The extended header follows the generic file header, and is described in Table 4-1. Extended Header Format.

Table 4-1. Extended Header Format
OffsetSizeDescription
0x000000304 bytes32-bit offset within file for start of Boot Image Entries (see Section 4.3. Boot Image Entries)
0x000000344 bytesNumber of Boot Image Entries

4.3. Boot Image Entries

There are 2 types of Boot Image Entries - entries that describe a directory, and entries that describe a file.

4.3.1. Boot Image Directory Entries

The format for a Boot Image Directory Entry is described in Table 4-2. Boot Image Directory Entry Layout.

Table 4-2. Boot Image Directory Entry Layout
OffsetSizeDescription
0x000000004 bytesSize of this entry
0x000000044 bytesMust be zero to indicate the entry is a directory entry
0x000000082 bytesDirectory general flags (see BCOS Native File System Attributes Application Note, Chapter 4: General Flags)
0x0000000A2 bytesReserved/unused
0x0000000C4 bytesDirectory owner subject ID (see BCOS Native File System Attributes Application Note, Chapter 5: File Owner Subject ID and BCOS Security Model Application Note, Section 2.1. Subject IDs)
0x0000001016 bytesOperation permission table (see BCOS Native File System Attributes Application Note, Chapter 6: Operation Permission Table)
0x0000002016 bytesDirectory creation timestamp (see BCOS Native File System Attributes Application Note, Chapter 2: Timestamps)
0x00000020VariesZero terminated UTF-8 directory name string (see BCOS Native File System Attributes Application Note, Chapter 3: File and Directory Names)
VariesVariesOptional padding (e.g. to align next entry on 4 byte boundary)

4.3.2. Boot Image File Entries

The format for a Boot Image File Entry is described in Table 4-3. Boot Image File Entry Layout.

Table 4-3. Boot Image File Entry Layout
OffsetSizeDescription
0x000000004 bytesSize of this entry
0x000000044 bytesOffset of file data relative to the start of the entry
0x000000082 bytesFile general flags (see BCOS Native File System Attributes Application Note, Chapter 4: General Flags)
0x0000000A2 bytesReserved/unused
0x0000000C4 bytesFile owner subject ID (see BCOS Native File System Attributes Application Note, Chapter 5: File Owner Subject ID and BCOS Security Model Application Note, Section 2.1. Subject IDs)
0x0000001016 bytesOperation permission table (see BCOS Native File System Attributes Application Note, Chapter 6: Operation Permission Table)
0x0000002016 bytesFile creation timestamp (see BCOS Native File System Attributes Application Note, Chapter 2: Timestamps)
0x000000304 bytesFile type (see BCOS File Type Specification)
0x00000034VariesZero terminated UTF-8 file name string (see BCOS Native File System Attributes Application Note, Chapter 3: File and Directory Names)
VariesVariesOptional padding (e.g. to align file data on 4 byte boundary)
VariesVariesFile data
VariesVariesOptional padding (e.g. to align next entry on 4 byte boundary)

Note: During boot, boot code will set bit 14 in the general flags for file entries that were accessed. This is intended to make it easier for software to generate a minimal boot image (containing only the accessed/used files) after boot.

4.4. Implied Directories

In general, there should be entries for all directories used in the path of all file and directory names. For example, for the file "first/second/foo" the boot image should include entries for the directory "first" and for the directory "first/second". However; it is permitted to omit directory entries. For example, for the file "first/second/foo" the boot image might not include entries for the directory "first" or the directory "first/second".

When directory entries are omitted, they are simply assumed to have existed. The implied directory's attributes are described in Table 4-4. Implied Directory Default Attributes.

Table 4-4. Implied Directory Default Attributes
FieldDefault Value
Directory creation timestampZero (unknown)
Directory general flagsZero (not deleted)
Operation permission tableAll entries zero (only directory owner is permitted to perform any operation)
Directory owner subject ID0x80000000 (the operating system is the directory owner)
Generated at 04:55:06 on the 22nd of April, 2017 (UTC)