CD Shell Development: Module File Format

Appendix B: Module File Format

Module Template

What follows in this document is a detailed account of the structure of a CD Shell module. If you are creating your module using NASM, a template is provided that makes setting up the various data areas extremely painless. If the module common routines are included (common.asm), then a lot of default functions and messages can be included as well. See the skeleton module, included in the source code release, for examples of how to use the template.

File Structure Overview

Modules consist of four distinct areas, as defined below.

Header

The header conveys information about the module to the core, such as the module format and where to find service definitions. The core also patches some information into the header for the module to make use of.

The header is always at the beginning of the module file, and is located at offset zero of the module segment. Its format is defined in the following section.

Module Services Lists

These are collections of service definitions, indicating to the core what commands, functions, hotkeys, and macros the module supports.

Service Routines and Data

The various service handlers' code and data is located in this area. It may come either before or after the services lists.

Uninitialized Data (BSS)

While not actually part of the module file, the uninitialized data area is allocated directly following the file after it is loaded into memory. Thus a module addresses this area as if it were located at the end of the file, on the next paragraph (16-byte) boundary.

Header

At the start of the module there is a 28-byte header. The fields of which are defined as follows:

Offset	Size	Description
0	4 bytes	signature
0	2 bytes	identifier
4	2 bytes	module format
6	2 bytes	requested BSS size
8	2 bytes	name pointer
10	2 bytes	initialization routine pointer
12	2 bytes	cleanup routine pointer
14	2 bytes	command services list pointer
16	2 bytes	function services list pointer
18	2 bytes	hotkey services list pointer
20	2 bytes	macro services list pointer
22	2 bytes	Core Services Table segment
24	2 bytes	core segment
26	2 bytes	core command buffer pointer

Signature

This is used to determine whether a file is a valid CD Shell module or not. It is four bytes long and contains the characters '-CDS'.

Identifier

The first two bytes of the module signature are replaced by a unique identifier when the module is loaded by the core. This identifier is used to refer to the module when requesting certain core services.

Module Format

This field represents the version of the module format used. Currently CD Shell uses module format M.4, represented by the value 0x0010. Future versions of CD Shell may require modules to be structured differently, and so would have some other value in this field.

Requested BSS Size

This field represents the ammount of BSS space (uninitialized data) a module requires. The BSS space is allocated at the first paragraph (16-byte boundary) following the module. The total module size, including header and BSS space, cannot exceed 64kb.

Name Pointer

This field points to a null-terminated module name string. If no module name is specified, this field should be zeroed out.

Initialization Routine Pointer

A pointer to an initialization routine can be located here. The core will call this routine as soon as the module is loaded into memory. If no initialization routine is present, this field should be zeroed out.

Cleanup Routine Pointer

A pointer to a cleanup routine can be located here. The core will call this routine before it CD Shell terminates. This is a cue to the module that it should restore the system to a clean state so that the boot process may proceed. If no cleanup routine is present, the field should be zero.

Command Services List Pointer

This field points to a list of command services provided by the module. If no command services are provided, set this field to zero.

Function Services List Pointer

This field points to a list of function services provided by the module. If no function services are provided, set this field to zero.

Hotkey Services List Pointer

This field points to a list of hotkey services provided by the module. If no hotkey services are provided, set this field to zero.

Macro Services List Pointer

This field points to a list of macro services provided by the module. If no macro services are provided, set this field to zero.

Core Services Table Segment

When the module is loaded into memory, the core will patch this field with the segment where the Core Services Table is located.

Core Segment

When the module is loaded into memory, the core will patch this field with the segment where the core command buffer is located.

Core Command Buffer Pointer

When the module is loaded into memory, the core will patch this field with the offset of the core command buffer. This buffer is used to pass parameters to the command service routine, and to pass commands back to the core for processing.

- Previous -