CD Shell Development: Modules

Expansion Modules

Introduction

Expansion modules are a key part of the CD Shell environment; without them, the core can not accomplish anything. Through the four types of services they provide (commands, functions, hotkeys, and macros), the modules account for every useful action performed in CD Shell.

Execution Environment

Module Location

The location a module is loaded can vary; the area that the core assigns during the dynamic memory allocation process is where the module will ultimately be located. This address will always be on a paragraph (16-byte) boundary, so that the module will be located at offset zero of its segment (hereafter called the module segment). If the module requests uninitialized memory (BSS space), it is allocated directly following the module at the next paragraph boundary.

Memory Model

Modules, including the BSS space they reserve, may not be larger than 64kb. The code and data that is local to the module is accessed using near pointers, while global code and data (eg. core services, scratch area) are accessed using far pointers.

Support Routines

Initialization and Cleanup

When the core first loads a module into memory, it will check for an initialization routine listed in the module header. If it finds one, then it will be invoked using the context described below to give the module an opportunity to initialize.

When it comes time for CD Shell to exit, either in the process of executing a boot command or otherwise, it gives all modules a chance to free any resources they may have used so that the system can proceed to boot cleanly, as if CD Shell had never been run. The core checks for a cleanup routine listed in the module header, and if it finds one it will be invoked using the following context.

Support Routine Call Context

Register	Contents
al	command source (Command.Console or Command.Script)
cs	module segment
ds	module segment
es	module segment
gs	Core Services Table segment
ss:sp	global stack, far return pointer on top

Note: Command.Console and Command.Script are defined in cdshell.inc.

The command source lets the module know if the core is currently operation in console mode (as it is when CD Shell first starts up and loads the modules) or script mode (for instance, it could be processing a loadmodule command in a script).

Support Routine Return Context

Register	Contents
ss:sp	global stack, far return pointer popped

Accessing Core Services

The core services are accessed using a vector table. The segment of the vector table can be found in the module header, and is also passed in the gs register whenever a module is invoked. The location in the table of a given function is defined in the file cdshell.inc.

The easiest way to call a core service is to use the acall macro defined in cdshell.inc. For example, while having the gs register loaded with the Core Services Table segment, issue the command 'acall display.cls' to clear the display. This will execute a far call to the CD Shell core, which will clear the display and then return control to the module.

Core services preserve all registers and flags except for those they expressly modify. See the individual service reference to determine which registers/flags a given service will modify.

- Previous -

- Next -