A class that provides a general interface to setting up generation for a format. More...

#include <format.h>

Inheritance diagram for Linker::OutputFormat:

Public Member Functions
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 > * >	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.

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

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

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 void	SetLinkScript (std::string script_file, std::map< std::string, std::string > &options)
	Selects a script file to use for linking.

virtual void	ProcessModule (Module &object)
	Processes the module object and initializes format fields.

virtual void	CalculateValues ()
	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.

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

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

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	FormatSupportsTransitionVectors () const
	Whether the format supports generating transition vectors.

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

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

virtual bool	FormatSupportsEntryTable () const
	Whether the format supports a structure containing addresses of methods.

virtual unsigned	FormatAdditionalSectionFlags (std::string section_name) const

virtual void	AllocateSymbols (Module &module) const
	Instructs the module to allocate any unallocated local symbols.

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

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

virtual void	ReadFile (const std::shared_ptr< Reader > &rd)=0
	Loads file into memory.

offset_t	WriteFile (const std::shared_ptr< Writer > &wr) const override=0
	Stores data in memory to file.

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

virtual void	SetFileOffset (offset_t new_offset)
	Attempts to alter the offset to the first byte of the format from the beginning of the file.

offset_t	ImageSize () const override
	Retrieves the offset of the byte after the last one belonging to this format from the first one.

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

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

Additional Inherited Members
Public Attributes inherited from Linker::Format
offset_t	file_offset
	The offset of the first byte used by this format in the file it is stored in.

Detailed Description

A class that provides a general interface to setting up generation for a format.

Member Function Documentation

◆ AddSupplementaryOutputFormat()

bool OutputFormat::AddSupplementaryOutputFormat ( std::string subformat )

virtual

If the output format actually drives multiple output formats (resource file, apple double, etc.), specify multiple types, return false if unknown.

Reimplemented in Apple::OutputDriver.

◆ AllocateSymbols()

void OutputFormat::AllocateSymbols ( Module & module ) const

virtual

Instructs the module to allocate any unallocated local symbols.

Reimplemented in Microsoft::PEFormat.

◆ CalculateValues()

void OutputFormat::CalculateValues ( )

virtual

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 in Apple::AppleDriver, Commodore::CommodoreFormat, DigitalResearch::CPM3Format, ARM::AIFFormat, AOut::AOutFormat, Apple::OutputDriver, Archive::ArchiveFormat, BFLT::BFLTFormat, Binary::GenericBinaryFormat, DOS16M::BWFormat, COFF::COFFFormat, DigitalResearch::CPM68KFormat, DigitalResearch::CPM86Format, DigitalResearch::CPM8KFormat, CauseWay::CauseWayFormat, SeychellDOS32::AdamFormat, BorcaD3X::D3X1Format, ELF::ELFFormat, ELF::FatELFFormat, EMX::EMXAOutFormat, Apple::OMFFormat, X68000::HUFormat, Amiga::HunkFormat, Microsoft::LEFormat, MachO::FatMachOFormat, Apple::MacintoshResourceFileFormat, Apple::Classic68KDriver, MINIX::MINIXFormat, Microsoft::MZFormat, Microsoft::NEFormat, PCOS::CMDFormat, Microsoft::PEFormat, Apple::PEFFormat, Apple::PEFOutputDriver, PharLap::MPFormat, PharLap::P3Format::Flat, PharLap::P3Format::MultiSegmented, PMODE::PMW1Format, Xenix::XOutFormat, and Ergo::XPFormat.

◆ FormatIs16bit()

bool OutputFormat::FormatIs16bit ( ) const

virtual

Whether the format is 16-bit or not.

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

Reimplemented in Binary::BinaryFormat, DOS16M::BWFormat, DigitalResearch::CPM86Format, GEOS::GeodeFormat, MINIX::MINIXFormat, Microsoft::MZFormat, Microsoft::NEFormat, PharLap::P3Format, and Ergo::XPFormat.

◆ FormatIsLinear()

bool OutputFormat::FormatIsLinear ( ) const

virtual

Whether the address space is linear or segmented.

This is needed to determine whether symbol relocations are absolute addresses or offsets within their own segments. Typically, Intel 8086 backends are non-linear, the others are linear.

◆ FormatIsProtectedMode()

bool OutputFormat::FormatIsProtectedMode ( ) const

virtual

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 in Binary::BinaryFormat, DOS16M::BWFormat, DigitalResearch::CPM86Format, GEOS::GeodeFormat, MINIX::MINIXFormat, Microsoft::MZFormat, Microsoft::NEFormat, PharLap::P3Format, and Ergo::XPFormat.

◆ FormatSupportsEntryTable()

bool OutputFormat::FormatSupportsEntryTable ( ) const

virtual

Whether the format supports a structure containing addresses of methods.

Formats such as NE, LE/LX and the Macintosh classic support an ordinal table or jump table that contains the addresses of certain methods.

Reimplemented in Microsoft::LEFormat, Apple::MacintoshResourceFileFormat, Apple::Classic68KDriver, Microsoft::NEFormat, Apple::PEFFormat, and Apple::PEFOutputDriver.

◆ FormatSupportsLibraries()

bool OutputFormat::FormatSupportsLibraries ( ) const

virtual

Whether the format supports libraries.

Reimplemented in COFF::COFFFormat, DigitalResearch::CPM86Format, ELF::ELFFormat, Microsoft::LEFormat, Microsoft::NEFormat, Microsoft::PEFormat, Apple::PEFFormat, and Apple::PEFOutputDriver.

◆ FormatSupportsResources()

bool OutputFormat::FormatSupportsResources ( ) const

virtual

Whether the format supports resources.

Formats such as NE, LE/LX, PE and the Macintosh classic support including resources in the final binary. To simplify writing resources, the ELF parser permits incorporating them directly in the binary image as $$RSRC$_<type>$<id>.

Reimplemented in COFF::AUXOutputDriver, Microsoft::LEFormat, Apple::MacintoshResourceFileFormat, Apple::Classic68KDriver, Microsoft::NEFormat, Microsoft::PEFormat, Apple::PEFFormat, and Apple::PEFOutputDriver.

◆ FormatSupportsSegmentation()

bool OutputFormat::FormatSupportsSegmentation ( ) const

virtual

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 in Binary::BinaryFormat, DOS16M::BWFormat, DigitalResearch::CPM86Format, DigitalResearch::CPM8KFormat, SeychellDOS32::AdamFormat, GEOS::GeodeFormat, Microsoft::LEFormat, Microsoft::MZFormat, Microsoft::NEFormat, PharLap::P3Format, and Ergo::XPFormat.

◆ FormatSupportsTransitionVectors()

bool OutputFormat::FormatSupportsTransitionVectors ( ) const

virtual

Whether the format supports generating transition vectors.

Transition vectors are a structure containing the address of a procedure alongside the address of the start of a data area. 68K based software calls this the A5 world, accessed via the A5 register, PowerPC based software calls this the TOC or Table of Contents, accessed via GPR2.

Reimplemented in Apple::PEFFormat, and Apple::PEFOutputDriver.

◆ GenerateFile()

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

virtual

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

Reimplemented in Apple::AppleDriver, AOut::AOutFormat, BFLT::BFLTFormat, COFF::COFFFormat, DigitalResearch::CPM68KFormat, DigitalResearch::CPM86Format, DigitalResearch::CPM8KFormat, SeychellDOS32::AdamFormat, DX64::LVFormat, ELF::ELFFormat, EMX::EMXAOutFormat, X68000::HUFormat, Amiga::HunkFormat, Microsoft::LEFormat, Apple::MacintoshResourceFileFormat, Apple::Classic68KDriver, MINIX::MINIXFormat, Microsoft::MZFormat, Microsoft::NEFormat, Microsoft::PEFormat, Apple::PEFFormat, and Apple::PEFOutputDriver.

◆ GetDefaultExtension() [1/2]

virtual std::string Linker::OutputFormat::GetDefaultExtension ( Module & module ) const

virtual

Provides a default filename for the output file.

Typically a.out or some other extension, such as a.exe.

Reimplemented in UZI::UZIFormat, UZI::UZI280Format, AOut::AOutFormat, BFLT::BFLTFormat, EMX::EMXAOutFormat, Amiga::HunkFormat, Apple::MacintoshResourceFileFormat, Apple::Classic68KDriver, MINIX::MINIXFormat, and Apple::PEFOutputDriver.

◆ GetDefaultExtension() [2/2]

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

virtual

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 in Apple::AppleDriver, Commodore::CommodoreFormat, FLEX::FLEXFormat, ARM::AIFFormat, AOut::AOutFormat, Binary::GenericBinaryFormat, DOS16M::BWFormat, COFF::COFFFormat, DigitalResearch::CPM68KFormat, DigitalResearch::CPM86Format, DigitalResearch::CPM8KFormat, CauseWay::CauseWayFormat, SeychellDOS32::AdamFormat, ELF::ELFFormat, EMX::EMXAOutFormat, GEOS::GeodeFormat, X68000::HUFormat, Microsoft::LEFormat, Apple::Classic68KDriver, Microsoft::MZFormat, Microsoft::NEFormat, PCOS::CMDFormat, Microsoft::PEFormat, Apple::PEFOutputDriver, PharLap::MPFormat, PharLap::P3Format, PMODE::PMW1Format, and Ergo::XPFormat.

◆ GetLinkerScriptParameterNames()

std::vector< OptionDescription< void > * > OutputFormat::GetLinkerScriptParameterNames ( )

virtual

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

Reimplemented in AOut::AOutFormat, Binary::GenericBinaryFormat, Binary::BinaryFormat, COFF::COFFFormat, DigitalResearch::CPM68KFormat, ELF::ELFFormat, EMX::EMXAOutFormat, X68000::HUFormat, Microsoft::LEFormat, MINIX::MINIXFormat, and Microsoft::PEFormat.

◆ GetMemoryModelNames()

std::vector< OptionDescription< void > > OutputFormat::GetMemoryModelNames ( )

virtual

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

Reimplemented in Binary::BinaryFormat, DigitalResearch::CPM86Format, Apple::MacintoshResourceFileFormat, Apple::Classic68KDriver, Microsoft::MZFormat, Apple::PEFOutputDriver, and Ergo::XPFormat.

◆ GetOptions()

std::shared_ptr< OptionCollector > OutputFormat::GetOptions ( )

virtual

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

Reimplemented in Apple::AppleDriver, Commodore::CommodoreFormat, DigitalResearch::CPM3Format, DigitalResearch::PRLFormat, AOut::AOutFormat, BFLT::BFLTFormat, DOS16M::BWFormat, COFF::COFFFormat, DigitalResearch::CPM68KFormat, DigitalResearch::CPM86Format, SeychellDOS32::AdamFormat, DX64::LVFormat, BorcaD3X::D3X1Format, ELF::ELFFormat, EMX::EMXAOutFormat, Amiga::HunkFormat, Microsoft::LEFormat, Apple::MacintoshResourceFileFormat, Apple::Classic68KDriver, MINIX::MINIXFormat, Microsoft::MZFormat, Microsoft::NEFormat, Microsoft::PEFormat, Apple::PEFFormat, Apple::PEFOutputDriver, PharLap::MPFormat, PharLap::P3Format, and Ergo::XPFormat.

◆ ProcessModule()

void OutputFormat::ProcessModule ( Module & object )

virtual

◆ SetLinkScript()

void OutputFormat::SetLinkScript	(	std::string	script_file,
		std::map< std::string, std::string > &	options
	)

virtual

Selects a script file to use for linking.

Reimplemented in BFLT::BFLTFormat, Apple::Classic68KDriver, MINIX::MINIXFormat, Apple::PEFOutputDriver, and Linker::SegmentManager.

◆ SetModel()

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

virtual

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

Reimplemented in Binary::BinaryFormat, DigitalResearch::CPM86Format, Apple::MacintoshResourceFileFormat, Apple::Classic68KDriver, Microsoft::MZFormat, Microsoft::NEFormat, Apple::PEFOutputDriver, and Ergo::XPFormat.

◆ SetOptions()

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

virtual

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

src/linker/format.h
src/linker/format.cc

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ AddSupplementaryOutputFormat()

◆ AllocateSymbols()

◆ CalculateValues()

◆ FormatIs16bit()

◆ FormatIsLinear()

◆ FormatIsProtectedMode()

◆ FormatSupportsEntryTable()

◆ FormatSupportsLibraries()

◆ FormatSupportsResources()

◆ FormatSupportsSegmentation()

◆ FormatSupportsTransitionVectors()

◆ GenerateFile()

◆ GetDefaultExtension() [1/2]

◆ GetDefaultExtension() [2/2]

◆ GetLinkerScriptParameterNames()

◆ GetMemoryModelNames()

◆ GetOptions()

◆ ProcessModule()

◆ SetLinkScript()

◆ SetModel()

◆ SetOptions()