The native executable format for the Motorola 68000 port of CP/M. More...

#include <cpm68k.h>

Inheritance diagram for DigitalResearch::CPM68KFormat:

Classes
class	CPM68KOptionCollector

struct	Relocation

Public Types
enum	magic_type { MAGIC_CONTIGUOUS = 1 , MAGIC_NONCONTIGUOUS , MAGIC_CRUNCHED }
	Represents the magic number at the beginning of the executable file. More...

enum	system_type { SYSTEM_UNKNOWN , SYSTEM_CPM68K , SYSTEM_GEMDOS_EARLY , SYSTEM_GEMDOS , SYSTEM_HUMAN68K , SYSTEM_CDOS68K }
	Different systems have different relocation formats and expectations as to what segments should be present. More...

Public Member Functions
magic_type	GetSignature () const

void	SetSignature (magic_type magic)

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

	CPM68KFormat (system_type system=SYSTEM_UNKNOWN)

	CPM68KFormat (system_type system, magic_type magic)

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

offset_t	MeasureRelocations () const

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

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

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.

std::shared_ptr< Linker::Segment >	CodeSegment ()
	Return code segment (if it exists)

std::shared_ptr< Linker::Segment >	DataSegment ()
	Return data segment (if it exists)

unsigned	FormatAdditionalSectionFlags (std::string section_name) const override

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

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.

void	OnNewSegment (std::shared_ptr< Linker::Segment > segment) override
	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.

void	CreateDefaultSegments ()

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

void	Link (Linker::Module &module)

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.

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 > >	GetMemoryModelNames ()
	Returns a list of the supported memory models, 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 void	SetModel (std::string model)
	Sets the way memory is organized, typically modifying a built-in script.

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

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

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

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

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

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

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

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.

Static Public Member Functions
template<typename SizeType >
static offset_t	CDOS68K_MeasureRelocations (std::map< uint32_t, SizeType > relocations)

template<typename SizeType >
static void	CDOS68K_WriteRelocations (Linker::Writer &wr, std::map< uint32_t, SizeType > relocations)

Public Attributes
char	signature [2] = { 0x60, 0x1A }
	The magic number at the beginning of the executable file, one of 0x601A (contiguous), 0x601B (non-contiguous), 0x601C (contiguous with crunched relocations)

uint32_t	code_size = 0
	Size of the code/text segment.

uint32_t	data_size = 0
	Size of the initialized data segment.

uint32_t	bss_size = 0
	Size of the uninitialized data (bss) segment. Human68k includes the stack in it.

uint32_t	symbol_table_size = 0
	Size of the symbol table.

uint32_t	stack_size = 0
	Size of the stack segment. Only used by Concurrent DOS 68K.

uint32_t	code_address = 0
	Load address of the code/text segment. Not used by GEMDOS which stores the program flags at this offset.

uint32_t	program_flags = 0
	Program flags, used by GEMDOS.

uint16_t	relocations_suppressed = 1
	Set to a non-0 value when relocations are suppressed. Typically this can be 1, but Human68k specifically expects a 0xFFFF, according to documentation.

uint32_t	data_address = 0
	Load address of the initialized data segment. Only relevant for non-contiguous executables (CP/M-68K), otherwise it should follow the code/text segment directy.

uint32_t	bss_address = 0
	Load address of the uninitialized data (bss) segment. Only relevant for non-contiguous executables (CP/M-68K), otherwise it should follow the initialized data segment directy.

offset_t	file_size = 0
	Size of entire file, not used for generation.

std::shared_ptr< Linker::Image >	code = nullptr
	Storage for code segment.

std::shared_ptr< Linker::Image >	data = nullptr
	Storage for data segment.

std::map< uint32_t, Relocation >	relocations
	Relocations, not used for Human68k.

system_type	system
	The system which will load the executable.

bool	option_no_relocation = true
	Makes sure no relocations are placed into the output file.

std::shared_ptr< Linker::Segment >	bss_segment
	Segment to collect bss.

std::shared_ptr< Linker::Segment >	stack_segment
	Segment to collect stack (Concurrent DOS 68K only)

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 > * >	ParameterNames

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 executable format for the Motorola 68000 port of CP/M.

This format was also adopted on the following systems:

CP/M-68K .68k contiguous and non-contiguous files
GEMDOS .prg and gem .app files (contiguous only)
Atari TOS .prg, .app, .tos, .ttp, .gtp files (contiguous only)
Concurrent DOS 68K .68k contiguous files with normal or crunched relocations
Human68k .z files with no relocations

Member Enumeration Documentation

◆ magic_type

enum DigitalResearch::CPM68KFormat::magic_type

Represents the magic number at the beginning of the executable file.

Enumerator
MAGIC_CONTIGUOUS	Contiguous executables (magic value 0x601A in big endian) must load the code, data, bss segments consecutively.
MAGIC_NONCONTIGUOUS	Non-contiguous executables (magic value 0x601B in big endian) can load the code, data, bss segments at non-consecutive addresses, only used by CP/M-68K.
MAGIC_CRUNCHED	Contiguous executables with crunched relocations (magic value 0x601C in big endian), only used by Concurrent DOS 68K.

◆ system_type

enum DigitalResearch::CPM68KFormat::system_type

Different systems have different relocation formats and expectations as to what segments should be present.

Enumerator
SYSTEM_UNKNOWN	Unknown system: use GEMDOS with no relocations.
SYSTEM_CPM68K	Digital Research CP/M-68K, uses CP/M-68K relocations.
SYSTEM_GEMDOS_EARLY	Digital Research GEMDOS, only contiguous, relocations always present, header is an unusual 0x1E bytes long and most entries are reserved.
SYSTEM_GEMDOS	Digital Research GEMDOS, Atari TOS, only contiguous, text load address field replaced by program fields.
SYSTEM_HUMAN68K	Sharp Corporation & Hudson Soft Human68k .z executable, only contiguous, no relocations or symbol table.
SYSTEM_CDOS68K	Digital Research Concurrent DOS 68K, non-contiguous not allowed, but relocations can be in CP/M-68K format or crunched format, depending on magic number. Header contains separate field for stack size.

Member Function Documentation

◆ CalculateValues()

void CPM68KFormat::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 CPM68KFormat::Clear ( )

overridevirtual

Resets all fields to their default values, deallocate memory.

Reimplemented from Linker::Format.

◆ Dump()

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

overridevirtual

Display file contents in a nice manner.

Reimplemented from Linker::Format.

◆ FormatAdditionalSectionFlags()

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

overridevirtual

Reimplemented from Linker::OutputFormat.

◆ GenerateFile()

void CPM68KFormat::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 CPM68KFormat::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.

◆ GetLinkerScriptParameterNames()

std::vector< Linker::OptionDescription< void > * > CPM68KFormat::GetLinkerScriptParameterNames ( )

overridevirtual

Returns a list of the parameters used in the linker scripts, used for documentation.

Reimplemented from Linker::OutputFormat.

◆ GetOptions()

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

overridevirtual

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

Reimplemented from Linker::OutputFormat.

◆ ImageSize()

offset_t CPM68KFormat::ImageSize ( ) const

overridevirtual

Retrieves size of stored data.

Implements Linker::Image.

◆ OnNewSegment()

void CPM68KFormat::OnNewSegment ( std::shared_ptr< Linker::Segment > segment )

overridevirtual

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.

Reimplemented from Linker::SegmentManager.

◆ ProcessModule()

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

overridevirtual

Processes the module object and initializes format fields.

Reimplemented from Linker::OutputFormat.

◆ ReadFile()

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

overridevirtual

Loads file into memory.

Implements Linker::Format.

◆ SetOptions()

void CPM68KFormat::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 CPM68KFormat::WriteFile ( Linker::Writer & wr ) const

overridevirtual

Stores data in memory to file.

Implements Linker::Format.

Member Data Documentation

◆ ParameterNames

std::vector< Linker::OptionDescription< void > * > CPM68KFormat::ParameterNames

static

Initial value:

=
{
    &p_code_base_address,
    &p_data_base_address,
    &p_bss_base_address,
}

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

src/format/cpm68k.h
src/format/cpm68k.cc

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ magic_type

◆ system_type

Member Function Documentation

◆ CalculateValues()

◆ Clear()

◆ Dump()

◆ FormatAdditionalSectionFlags()

◆ GenerateFile()

◆ GetDefaultExtension()

◆ GetLinkerScriptParameterNames()

◆ GetOptions()

◆ ImageSize()

◆ OnNewSegment()

◆ ProcessModule()

◆ ReadFile()

◆ SetOptions()

◆ WriteFile()

Member Data Documentation

◆ ParameterNames