The native file format for 8086 based CP/M derived operating systems, including FlexOS 186/286. More...

#include <cpm86.h>

Inheritance diagram for DigitalResearch::CPM86Format:

Classes
class	CPM86OptionCollector

class	Descriptor
	A representation of segment group within the executable. More...

class	FastLoadDescriptor
	(FlexOS 286 only) The fast loading group (unimplemented) More...

struct	library
	(FlexOS 286 only) A shared runtime library entry in the shared runtime library group More...

struct	library_id
	(FlexOS only) A shared runtime library identifier More...

class	LibraryDescriptor
	A special descriptor to represent the group for imported shared runtime libraries. More...

struct	Relocation
	Represents a single relocation. More...

struct	relocation_source
	Represents the location of a 16-bit words that needs to be relocated. More...

struct	rsx_record
	Represents an attached RSX file (residential system extension) More...

Public Types
enum	{ FLAG_FIXUPS = 0x80 , FLAG_OPTIONAL_8087 = 0x40 , FLAG_REQUIRED_8087 = 0x20 , FLAG_RSX = 0x10 , FLAG_DIRECT_VIDEO = 0x08 , FLAG_MPMLOCK = 0x04 , FLAG_NO_BANKING = 0x02 }

enum	{ CPM_FLAG_F1 = 0x01 , CPM_FLAG_F2 = 0x02 , CPM_FLAG_F3 = 0x03 , CPM_FLAG_F4 = 0x04 }

enum	format_type { FORMAT_UNKNOWN , FORMAT_8080 , FORMAT_SMALL , FORMAT_COMPACT , FORMAT_FLEXOS , FORMAT_FASTLOAD }
	Describes the number and type of segment groups, as well as the target operating system. More...

enum	application_type { APPL_UNKNOWN , APPL_CMD , APPL_RSX , APPL_RSP , APPL_MPM , APPL_CON , APPL_OVR , APPL_286 , APPL_SRL }

enum	memory_model_t { MODEL_DEFAULT , MODEL_TINY , MODEL_SMALL , MODEL_COMPACT }
	Represents the memory model of the running executable, which is the way in which the segments are set up during execution. More...

typedef relocation_source	relocation_target

Public Member Functions
void	Clear () override
	Resets all fields to their default values, deallocate memory.

	CPM86Format (format_type format=FORMAT_UNKNOWN, application_type application=APPL_UNKNOWN)

uint16_t	GetRelocationSizeParas () const

size_t	CountValidGroups ()

number_t	FindSegmentGroup (unsigned group) const

void	CheckValidSegmentGroup (unsigned group)

bool	IsFastLoadFormat () const

bool	IsSharedRunTimeLibrary () const

void	ReadRelocations (Linker::Reader &rd)

void	WriteRelocations (Linker::Writer &wr) const

offset_t	MeasureRelocations ()

void	ReadFile (Linker::Reader &rd) override
	Loads file into memory.

offset_t	ImageSize () const override
	Retrieves size of stored data.

offset_t	WriteFile (Linker::Writer &wr) const override
	Stores data in memory to file.

offset_t	GetFullFileSize () const

void	Dump (Dumper::Dumper &dump) const override
	Display file contents in a nice manner.

void	CalculateValues () override
	Intermediate step between processing module and generating output file to set up headers and management sections It is expected that after a module is processed, additional steps are required to evaluate the final values of the fields.

bool	FormatSupportsSegmentation () const override
	Whether the format supports multiple segments.

bool	FormatIs16bit () const override
	Whether the format is 16-bit or not.

bool	FormatIsProtectedMode () const override
	Whether the format is in protected mode or not (x86 only)

bool	FormatSupportsLibraries () const override
	Whether the format supports libraries.

unsigned	FormatAdditionalSectionFlags (std::string section_name) const override

std::vector< std::shared_ptr< Linker::Segment > > &	Segments ()

void	AssignSegmentTypes ()
	Determine the segment group type number, must be called before accessing segment_types.

unsigned	GetSegmentNumber (std::shared_ptr< Linker::Segment > segment)

std::vector< Linker::OptionDescription< void > >	GetMemoryModelNames () override
	Returns a list of the supported memory models, used for documentation.

void	SetModel (std::string model) override
	Sets the way memory is organized, typically modifying a built-in script.

std::shared_ptr< Linker::OptionCollector >	GetOptions () override
	Returns object containing a sequence of option fields provided with the -S command line flag.

void	SetOptions (std::map< std::string, std::string > &options) override
	Passes command line parameters as settings over to format object.

std::unique_ptr< Script::List >	GetScript (Linker::Module &module)

void	Link (Linker::Module &module)

void	BuildLDTImage (Linker::Module &module)
	Creates the LDT image for a fastload FlexOS binary.

void	ProcessModule (Linker::Module &module) override
	Processes the module object and initializes format fields.

void	GenerateFile (std::string filename, Linker::Module &module) override
	The main function that handles processing, calculating and generating the final image.

std::string	GetDefaultExtension (Linker::Module &module, std::string filename) const override
	Appends a default extension to the filename.

Public Member Functions inherited from Linker::SegmentManager
void	ClearSegmentManager ()

void	SetLinkScript (std::string script_file, std::map< std::string, std::string > &options) override
	Sets up the linker script and linker parameters.

std::unique_ptr< Script::List >	GetScript (Module &module)
	Compiles the linker script into an internal format.

offset_t	GetCurrentAddress () const
	Retrieves current address pointer.

void	SetCurrentAddress (offset_t address)
	Moves the current address pointer further, and if the current segment already contains data, fill it up to the point.

void	AlignCurrentAddress (offset_t align)
	Aligns current address to alignment, using SetCurrentAddress.

void	SetLatestBase (offset_t address)
	Sets the base of the current section (the value from which offsets are counted from)

void	FinishCurrentSegment ()
	Closes the current segment, sets current_segment to null.

virtual void	OnNewSegment (std::shared_ptr< Segment > segment)
	Callback function when allocating a new segment When the linker script runs, it creates segments consecutively. Overriding this method permits the output format to handle the allocated segment.

std::shared_ptr< Segment >	AppendSegment (std::string name)
	Terminates the current segment (if there is one), creates a new segment and attaches it to the image.

std::shared_ptr< Segment >	FetchSegment (std::string name)
	Attempts to fetch a segment, returns null if not found.

void	AppendSection (std::shared_ptr< Section > section)
	Adds a new section to the current segment, sets the base to the same as the segment.

void	ProcessScript (std::unique_ptr< Script::List > &directives, Module &module)
	Executes a parsed linker script on a module and collects segments The function OnNewSegment can be defined to handle each newly allocated segment.

void	ProcessAction (std::unique_ptr< Script::Node > &action, Module &module)

void	PostProcessAction (std::unique_ptr< Script::Node > &action, Module &module)

void	ProcessCommand (std::unique_ptr< Script::Node > &command, Module &module)

bool	CheckPredicate (std::unique_ptr< Script::Node > &predicate, std::shared_ptr< Section > section, Module &module)

offset_t	EvaluateExpression (std::unique_ptr< Script::Node > &expression, Module &module)

Public Member Functions inherited from Linker::OutputFormat
virtual bool	AddSupplementaryOutputFormat (std::string subformat)
	If the output format actually drives multiple output formats (resource file, apple double, etc.), specify multiple types, return false if unknown.

virtual std::vector< OptionDescription< void > * >	GetLinkerScriptParameterNames ()
	Returns a list of the parameters used in the linker scripts, used for documentation.

virtual std::vector< OptionDescription< void > >	GetSpecialSymbolNames ()
	Returns a list of special symbol names recognized by the format, used for documentation.

std::optional< std::string >	FetchOption (std::map< std::string, std::string > &options, std::string name)
	Convenience method to look up option by name.

std::string	FetchOption (std::map< std::string, std::string > &options, std::string name, std::string default_value)
	Convenience method to look up option by name, returning default value if name is missing.

std::optional< offset_t >	FetchIntegerOption (std::map< std::string, std::string > &options, std::string name)
	Convenience method to look up option by name and convert it to integer.

virtual std::string	GetDefaultExtension (Module &module) const
	Provides a default filename for the output file.

virtual bool	FormatIsLinear () const
	Whether the address space is linear or segmented.

virtual bool	FormatSupportsResources () const
	Whether the format supports resources.

Public Member Functions inherited from Linker::Format
	Format (offset_t file_offset=0)

offset_t	ImageSize () const override
	Retrieves size of stored data.

offset_t	WriteFile (Writer &wr, offset_t count, offset_t offset=0) const override
	Writes data of non-zero filled sections.

Public Member Functions inherited from Linker::Image
virtual std::shared_ptr< const ActualImage >	AsImage () const
	Retrieves a randomly accessible image.

std::shared_ptr< ActualImage >	AsImage ()
	Retrieves a randomly accessible image.

Public Attributes
std::array< Descriptor, 8 >	descriptors
	A .cmd file may contain up to 8 descriptors that describer the segment groups.

LibraryDescriptor	library_descriptor
	FlexOS 286 defines a shared runtime library group at offset 0x48.

FastLoadDescriptor	fastload_descriptor
	FlexOS 286 defines a fast load segment (unknown name) at offset 0x51.

library_id	lib_id
	FlexOS 286 library identifier (for libraries) at offset 0x60.

std::vector< Relocation >	relocations
	The sequence of intramodule relocations.

uint32_t	relocations_offset = 0
	Offset of relocation records, stored in 128 byte units at offset 0x7D.

std::array< rsx_record, 8 >	rsx_table
	Represents a list of attached RSX modules.

uint32_t	rsx_table_offset = 0
	The actual RSX table, stored in 128 byte units at offset 0x7B.

uint8_t	flags = 0
	Execution flags, stored at offset 0x7F.

uint8_t	cpm_flags = 0
	CP/M specific flags used by Concurrent DOS, stored at offset 0x7A.

uint32_t	file_offset = 0
	The start of the image within the file, typically 0 except for embedded modules, usually for embedded RSX files.

offset_t	file_size = offset_t(-1)
	The full size of the image.

format_type	format
	Format of file to generate.

application_type	application
	Target application type.

bool	option_shared_code = false
	Flag indicating that the code group is shared, not possible in 8080 format.

bool	option_no_relocation = false
	Flag to indicate that relocations must be suppressed.

bool	option_generate_fixup_group = false
	On FlexOS, relocations can be part of its own group.

memory_model_t	memory_model = MODEL_SMALL
	Memory model of generated code, determines how the offsets are calculated within a segment group.

std::map< std::shared_ptr< Linker::Segment >, Descriptor::group_type >	segment_types
	Assignment from each segment to the segment group type number (1: code, 2: data, etc.)

Public Attributes inherited from Linker::SegmentManager
offset_t	current_base = 0
	The base address of the current section.

std::vector< std::shared_ptr< Segment > >	segment_vector
	Ordered sequence of segments.

std::map< std::string, std::shared_ptr< Segment > >	segment_map
	Map of segments from their names.

std::shared_ptr< Segment >	current_segment
	Currently processed segment.

std::map< std::string, Location >	linker_parameters
	Parameters that permit customizing the linker script.

std::string	linker_script
	Contents of the linker script.

Public Attributes inherited from Linker::Format
offset_t	file_offset

Static Public Attributes
static std::vector< Linker::OptionDescription< void > >	MemoryModelNames

Additional Inherited Members
Protected Attributes inherited from Linker::SegmentManager
offset_t	current_address = 0
	Holds the current address value when there is no current_segment.

bool	current_is_template = false

bool	current_is_template_head = false

offset_t	template_counter = 0

std::string	current_template_name

Detailed Description

The native file format for 8086 based CP/M derived operating systems, including FlexOS 186/286.

The current implementation supports 3 memory model formats:

8080 model (also called tiny model for MS-DOS programs)
Small model
Compact model
Preliminary provisions for FlexOS memory models

The format was used on a multitude of Digital Research operating systems, from CP/M-86 and DOS Plus to Multiuser DOS, as well as FlexOS. It supports many special features, such as shared libraries and attachable residential system extensions. These are not currently implemented.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Enumerator
FLAG_FIXUPS	Set when relocations are present, indicates that the executable is relocatable and needs fixing up before executing.
FLAG_OPTIONAL_8087	Set when the software expects the system to allocate 8087 resources, but it can emulate the missing 8087 coprocessor insturctions if needed.
FLAG_REQUIRED_8087	Set when the software only runs if an 8087 is present. The system will allocate 8087 resources.
FLAG_RSX	Set for residential system extensions (RSX files)
FLAG_DIRECT_VIDEO	Set when the program uses direct video access. Such programs cannot execute in the background.
FLAG_MPMLOCK	Program uses record locking functions of MP/M-86 instead of those of Concurrent CP/M-86 or Concurrent DOS.
FLAG_NO_BANKING	Set when the program cannot run in banked memory.

◆ application_type

enum DigitalResearch::CPM86Format::application_type

Enumerator
APPL_UNKNOWN	Unspecified.
APPL_CMD	CP/M-86 .cmd executable file.
APPL_RSX	CP/M-86 .rsx resident system extension file.
APPL_RSP	MP/M-86 or Concurrent CP/M-86 .rsp resident system process file (unsupported)
APPL_MPM	MP/M-86 .mpm system module file (unsupported)
APPL_CON	Concurrent CP/M-86 .con system module file (unsupported)
APPL_OVR	CP/M-86 .ovr overlay (unsupported)
APPL_286	FlexOS 286 .286 executable file (limited support)
APPL_SRL	FlexOS 286 .SRL shared runtime library (limited support)

◆ format_type

enum DigitalResearch::CPM86Format::format_type

Describes the number and type of segment groups, as well as the target operating system.

Enumerator
FORMAT_UNKNOWN	Unspecified.
FORMAT_8080	CP/M-86 format, only a single non-shared code group is present, with optional relocations and attached RSX system extensions.
FORMAT_SMALL	CP/M-86 format, only code (possibly shared) and a separate data group is present, also used for medium model.
FORMAT_COMPACT	CP/M-86 format, each non-executable section will have its own group, including stack and up to 4 auxiliary groups, also used for large model.
FORMAT_FLEXOS	FlexOS 286 format, running in protected mode, possible SRTL shared libraries (untested)
FORMAT_FASTLOAD	FlexOS 286 fastload format as generated by postlink, with an LDT image in file (unfinished)

◆ memory_model_t

enum DigitalResearch::CPM86Format::memory_model_t

Represents the memory model of the running executable, which is the way in which the segments are set up during execution.

Enumerator
MODEL_TINY	CS=DS=SS=ES, only possible in 8080 mode.
MODEL_SMALL	DS=SS=ES, only possible in 8080 or small mode.
MODEL_COMPACT	DS!=SS!=ES.

Member Function Documentation

◆ CalculateValues()

void CPM86Format::CalculateValues ( )

overridevirtual

Intermediate step between processing module and generating output file to set up headers and management sections It is expected that after a module is processed, additional steps are required to evaluate the final values of the fields.

Reimplemented from Linker::OutputFormat.

◆ Clear()

void CPM86Format::Clear ( )

overridevirtual

Resets all fields to their default values, deallocate memory.

Reimplemented from Linker::Format.

◆ Dump()

void CPM86Format::Dump ( Dumper::Dumper & dump ) const

overridevirtual

Display file contents in a nice manner.

Reimplemented from Linker::Format.

◆ FormatAdditionalSectionFlags()

unsigned CPM86Format::FormatAdditionalSectionFlags ( std::string section_name ) const

overridevirtual

Reimplemented from Linker::OutputFormat.

◆ FormatIs16bit()

bool CPM86Format::FormatIs16bit ( ) const

overridevirtual

Whether the format is 16-bit or not.

This is needed for the ELF parser which can not distinguish between the 8086 and 80386 backends.

Reimplemented from Linker::OutputFormat.

◆ FormatIsProtectedMode()

bool CPM86Format::FormatIsProtectedMode ( ) const

overridevirtual

Whether the format is in protected mode or not (x86 only)

This is needed for the ELF parser to determine whether segment references are paragraph offsets (16-byte units) or selector indexes.

For non-x86 targets, the result is meaningless.

Reimplemented from Linker::OutputFormat.

◆ FormatSupportsLibraries()

bool CPM86Format::FormatSupportsLibraries ( ) const

overridevirtual

Whether the format supports libraries.

Reimplemented from Linker::OutputFormat.

◆ FormatSupportsSegmentation()

bool CPM86Format::FormatSupportsSegmentation ( ) const

overridevirtual

Whether the format supports multiple segments.

This is typically true for Intel 8086 targets and false for non-Intel targets. The ELF parser uses this to provide extended relocations, including the following:

$$SEG$<section name>
$$SEGOF$<symbol name>
$$SEGAT$<symbol name>
$$WRTSEG$<symbol name>$<section name>
$$SEGDIF$<section name>$<section name>

Reimplemented from Linker::OutputFormat.

◆ GenerateFile()

void CPM86Format::GenerateFile	(	std::string	filename,
		Linker::Module &	module )

overridevirtual

The main function that handles processing, calculating and generating the final image.

Reimplemented from Linker::OutputFormat.

◆ GetDefaultExtension()

std::string CPM86Format::GetDefaultExtension	(	Linker::Module &	module,
		std::string	filename ) const

overridevirtual

Appends a default extension to the filename.

A typical behavior would be to append .exe at the end of the filename. The default action is to leave it intact.

Reimplemented from Linker::OutputFormat.

◆ GetMemoryModelNames()

std::vector< Linker::OptionDescription< void > > CPM86Format::GetMemoryModelNames ( )

overridevirtual

Returns a list of the supported memory models, used for documentation.

Reimplemented from Linker::OutputFormat.

◆ GetOptions()

std::shared_ptr< Linker::OptionCollector > CPM86Format::GetOptions ( )

overridevirtual

Returns object containing a sequence of option fields provided with the -S command line flag.

Reimplemented from Linker::OutputFormat.

◆ ImageSize()

offset_t CPM86Format::ImageSize ( ) const

overridevirtual

Retrieves size of stored data.

Implements Linker::Image.

◆ ProcessModule()

void CPM86Format::ProcessModule ( Linker::Module & object )

overridevirtual

Processes the module object and initializes format fields.

Reimplemented from Linker::OutputFormat.

◆ ReadFile()

void CPM86Format::ReadFile ( Linker::Reader & rd )

overridevirtual

Loads file into memory.

Implements Linker::Format.

◆ SetModel()

void CPM86Format::SetModel ( std::string model )

overridevirtual

Sets the way memory is organized, typically modifying a built-in script.

Reimplemented from Linker::OutputFormat.

◆ SetOptions()

void CPM86Format::SetOptions ( std::map< std::string, std::string > & options )

overridevirtual

Passes command line parameters as settings over to format object.

Reimplemented from Linker::OutputFormat.

◆ WriteFile()

offset_t CPM86Format::WriteFile ( Linker::Writer & wr ) const

overridevirtual

Stores data in memory to file.

Implements Linker::Format.

Member Data Documentation

◆ MemoryModelNames

std::vector< Linker::OptionDescription< void > > CPM86Format::MemoryModelNames

static

Initial value:

=
{
    Linker::OptionDescription<void>("default", "Depends on format: tiny for 8080 format, small for small format or FlexOS, compact for compact format"),
    Linker::OptionDescription<void>("tiny", "Tiny model, all symbols have the same preferred segment, 8080 format only"),
    Linker::OptionDescription<void>("small", "Small model, symbols in .code have a separate preferred segment, not supported on compact format"),
    Linker::OptionDescription<void>("compact", "Compact model, symbols in .data, .bss and .comm have a common preferred segment, all other sections are treated as separate segments"),
}

The documentation for this class was generated from the following files:

src/format/cpm86.h
src/format/cpm86.cc

Classes

Public Types

Public Member Functions

Public Attributes

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

◆ application_type

◆ format_type

◆ memory_model_t

Member Function Documentation

◆ CalculateValues()

◆ Clear()

◆ Dump()

◆ FormatAdditionalSectionFlags()

◆ FormatIs16bit()

◆ FormatIsProtectedMode()

◆ FormatSupportsLibraries()

◆ FormatSupportsSegmentation()

◆ GenerateFile()

◆ GetDefaultExtension()

◆ GetMemoryModelNames()

◆ GetOptions()

◆ ImageSize()

◆ ProcessModule()

◆ ReadFile()

◆ SetModel()

◆ SetOptions()

◆ WriteFile()

Member Data Documentation

◆ MemoryModelNames