LE/LX .EXE linear executable file format. More...

#include <leexe.h>

Inheritance diagram for Microsoft::LEFormat:

Classes
class	Entry
	Represents an entry into the binary, typically DLL exported procedures. More...

class	IteratedPage
	A data structure to represent an LE/LX iterated page, consisting of data produced from a repetition of a certain pattern. More...

class	LEOptionCollector

class	ModuleDirective
	Stores a module directive in the module directive table. More...

struct	Name
	A name and ordinal pair, as used for resident and non-resident names. More...

class	Object
	Represents an LE/LX object (a relocatable section of memory) as stored in the object table, alongside associated information. More...

class	Page
	Represents a page (usually of 4 KiB) within an LE/LX object. More...

class	PageSet
	An image instance that is a collection of other images, conceptually pages. More...

struct	PhysicalPageNumber
	Type safe wrapper for an uint32_t to access physical pages. More...

class	PhysicalPages
	Typesafe wrapper around std::vector<Page> to only access elements via physical pages. More...

class	Resource
	Stores an OS/2 resource. More...

class	SegmentPage
	An image instance for a single page within a complete object image. More...

Public Types
enum	compatibility_type { CompatibleNone , CompatibleWatcom , CompatibleMicrosoft , CompatibleBorland }

enum	cpu_type { I286 = 0x01 , I386 = 0x02 , I486 = 0x03 , I586 = 0x04 , I860_N10 = 0x20 , I860_N11 = 0x21 , MIPS1 = 0x40 , MIPS2 = 0x41 , MIPS3 = 0x42 }

enum	system_type { OS2 = 1 , Windows , MSDOS4 , Windows386 , Neutral , DOS4G = 0x10001 }

enum	output_type { OUTPUT_GUI , OUTPUT_CON , OUTPUT_DLL , OUTPUT_PDD , OUTPUT_VDD }
	Represents the target image type. More...

enum	{ PreProcessInitialization = 0x00000004 , NoInternalFixup = 0x00000010 , NoExternalFixup = 0x00000020 , FullScreen = 0x00000100 , GUIAware = 0x00000200 , GUI = 0x00000300 , ErrorInImage = 0x00002000 , Library = 0x00008000 , ProtectedMemoryLibrary = 0x00018000 , PhysicalDriver = 0x00020000 , VirtualDriver = 0x00028000 , PerProcessTermination = 0x40000000 }

Public Member Functions
bool	IsExtendedFormat () const

PhysicalPageNumber	ObjectPageToPhysicalPage (uint32_t index) const

void	SetTargetDefaults ()
	Configures the values for system/output type.

	LEFormat (bool extended_format)

	LEFormat (system_type system, output_type output)

	LEFormat (system_type system, output_type output, bool extended_format)

bool	IsLibrary () const

bool	IsDriver () const

bool	IsOS2 () const

bool	MayHaveStack () const

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.

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

offset_t	GetPageOffset (PhysicalPageNumber physical_page_number) const

offset_t	GetPageSize (PhysicalPageNumber physical_page_number) const

std::shared_ptr< LEFormat >	SimulateLinker (compatibility_type compatibility)

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

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

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

unsigned	FormatAdditionalSectionFlags (std::string section_name) const override

Resource &	AddResource (Resource resource)

void	GetRelocationOffset (Object &object, size_t offset, PhysicalPageNumber &page_index, uint16_t &page_offset)

void	AddRelocation (Object &object, unsigned type, unsigned flags, size_t offset, uint16_t module, uint32_t target=0, uint32_t addition=0)

unsigned	GetDefaultObjectFlags () const

void	AddObject (const Object &object)

uint16_t	FetchImportedModuleName (std::string name)

uint16_t	FetchImportedProcedureName (std::string name)

uint16_t	MakeEntry (Linker::Position value)

uint16_t	MakeEntry (uint16_t index, Linker::Position value)

uint8_t	CountBundles (size_t entry_index) const

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.

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	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.

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	OnCallDirective (std::string identifier)
	Callback function for the CALL directive.

std::shared_ptr< Segment >	AppendSegment (std::string name)
	Creates a new segment and attaches it to the image.

void	AppendSegment (std::shared_ptr< Segment > segment)
	Attaches the segment 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	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 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.

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::Contents
virtual std::shared_ptr< const Image >	AsImage () const
	Retrieves a randomly accessible image.

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

Static Public Member Functions
static std::shared_ptr< LEFormat >	CreateConsoleApplication (system_type system=OS2)

static std::shared_ptr< LEFormat >	CreateGUIApplication (system_type system=OS2)

static std::shared_ptr< LEFormat >	CreateLibraryModule (system_type system=OS2)

static std::shared_ptr< LEFormat >	CreateDeviceDriver (system_type system=OS2, bool virtual_device_driver=true)

Public Attributes
::EndianType	endiantype = ::LittleEndian

std::array< char, 2 >	signature {'L', 'E'}
	The signature, almost always "LE" or "LX".

uint32_t	format_level = 0

cpu_type	cpu = I386

system_type	system = system_type(0)

output_type	output

uint32_t	module_version = 0

uint32_t	module_flags = 0

uint32_t	page_count = 0

uint32_t	page_size = 0x1000

uint32_t	eip_object = 0

uint32_t	eip_value = 0

uint32_t	esp_object = 0

uint32_t	esp_value = 0

union {

uint32_t last_page_size

uint32_t page_offset_shift

};

uint32_t	fixup_section_size = 0

uint32_t	fixup_section_checksum = 0

uint32_t	loader_section_size = 0

uint32_t	loader_section_checksum = 0

uint32_t	object_table_offset = 0

uint32_t	object_page_table_offset = 0

uint32_t	object_iterated_pages_offset = 0

uint32_t	resource_table_offset = 0

uint32_t	resource_table_entry_count = 0

uint32_t	resident_name_table_offset = 0

uint32_t	entry_table_offset = 0

uint32_t	module_directives_offset = 0

uint32_t	fixup_page_table_offset = 0

uint32_t	fixup_record_table_offset = 0

uint32_t	imported_module_table_offset = 0

uint32_t	imported_procedure_table_offset = 0

uint32_t	per_page_checksum_offset = 0

uint32_t	data_pages_offset = 0

uint32_t	preload_page_count = 0

uint32_t	nonresident_name_table_offset = 0

uint32_t	nonresident_name_table_size = 0

uint32_t	nonresident_name_table_checksum = 0

uint32_t	automatic_data = 0

uint32_t	debug_info_offset = 0

uint32_t	debug_info_size = 0

uint32_t	instance_preload_page_count = 0

uint32_t	instance_demand_page_count = 0

uint32_t	stack_size = 0

uint32_t	heap_size = 0

uint32_t	vxd_version_info_resource_offset = 0

uint32_t	vxd_version_info_resource_length = 0

ResourceFile	vxd_version_info_resource = ResourceFile(ResourceFile::System_Windows_3x)

uint16_t	vxd_device_id = 0

uint16_t	vxd_ddk_version = 0

std::vector< Object >	objects

std::vector< ModuleDirective >	module_directives

PhysicalPages	pages

std::vector< std::tuple< PhysicalPageNumber, Page::page_type > >	page_map_table
	(LE only) The object page map table contents

std::map< std::tuple< uint16_t, uint16_t >, Resource >	resources

std::vector< Name >	resident_names

std::vector< Name >	nonresident_names

std::vector< Entry >	entries

std::vector< std::string >	imported_modules

std::vector< std::string >	imported_procedures

offset_t	file_size = offset_t(-1)

MZStubWriter	stub

compatibility_type	compatibility = CompatibleNone

std::string	program_name

std::string	module_name

std::shared_ptr< Linker::Segment >	stack

std::shared_ptr< Linker::Segment >	heap

std::map< std::shared_ptr< Linker::Segment >, size_t >	object_index

std::map< std::string, uint32_t >	imported_procedure_name_offsets

offset_t	imported_procedure_names_length = 0

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_head = false
	Set during evaluation of `guard` in a `for <guard> { <body> }` statement.

bool	current_is_template = false
	Set during evaluation of `body` in a `for <guard> { <body> }` statement.

offset_t	template_counter = 0
	Counts how many times a `for` statement has been invoked.

bool	condition_failed = false
	Condition to signal end of current `for` statement.

std::string	current_template_name
	Records the name of the currently generating segment for a `for` statement.

Detailed Description

LE/LX .EXE linear executable file format.

Introduced first for 32-bit virtual device drivers for 16-bit versions of Windows, it was adopted and extended for 32-bit versions of OS/2 as well as a few DOS extenders. It has two main variants, the LE and the LX executable formats.

The following platforms are supported:

Windows/386 device drivers, LE format (not tested or fully supported)
LE executables for the DOS/4G DOS extender
LX executables for 32-bit versions of OS/2

Member Enumeration Documentation

◆ compatibility_type

enum Microsoft::LEFormat::compatibility_type

Enumerator
CompatibleNone	No emulation is attempted.
CompatibleWatcom	Attempts to mimic the output of the Watcom linker.
CompatibleMicrosoft	Attempts to mimic the output of the Microsoft linker (TODO: unimplemented)
CompatibleBorland	Attempts to mimic the output of the Borland linker (TODO: unimplemented)

◆ output_type

enum Microsoft::LEFormat::output_type

Represents the target image type.

Enumerator
OUTPUT_GUI	A graphical executable image, conventionally taking the suffix `.exe`
OUTPUT_CON	A console executable image, conventionally taking the suffix `.exe`
OUTPUT_DLL	A dynamically linked library, conventionally taking the suffix `.dll`
OUTPUT_PDD	A physical device driver, conventionally taking the suffix `.sys`
OUTPUT_VDD	A virtual device driver, conventionally taking the suffix `.sys`

◆ system_type

enum Microsoft::LEFormat::system_type

Enumerator
OS2	Runs on OS/2 2.0+.
Windows	Reserved for Windows, unimplemented.
MSDOS4	Reserved for DOS 4.x, unimplemented.
Windows386	Windows 386 (only virtual device drivers supported)
Neutral	IBM Microkernel Personality Neutral, unimplemented.
DOS4G	Used by DOS/4G, the numerical value is chosen so that it gets stored as OS/2 in the binary.

Member Function Documentation

◆ CalculateValues()

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

◆ Dump()

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

overridevirtual

Display file contents in a nice manner.

Reimplemented from Linker::Format.

◆ FormatAdditionalSectionFlags()

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

overridevirtual

Reimplemented from Linker::OutputFormat.

◆ FormatSupportsLibraries()

bool LEFormat::FormatSupportsLibraries ( ) const

overridevirtual

Whether the format supports libraries.

Reimplemented from Linker::OutputFormat.

◆ FormatSupportsResources()

bool LEFormat::FormatSupportsResources ( ) const

overridevirtual

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 from Linker::OutputFormat.

◆ FormatSupportsSegmentation()

bool LEFormat::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 LEFormat::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 LEFormat::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 > * > LEFormat::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 > LEFormat::GetOptions ( )

overridevirtual

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

Reimplemented from Linker::OutputFormat.

◆ ImageSize()

offset_t LEFormat::ImageSize ( ) const

overridevirtual

Retrieves size of stored data.

Reimplemented from Linker::Format.

◆ OnNewSegment()

void LEFormat::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 LEFormat::ProcessModule ( Linker::Module & object )

overridevirtual

Processes the module object and initializes format fields.

Reimplemented from Linker::OutputFormat.

◆ ReadFile()

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

overridevirtual

Loads file into memory.

Implements Linker::Format.

◆ SetOptions()

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

overridevirtual

Stores data in memory to file.

Implements Linker::Format.

Member Data Documentation

◆ page_map_table

std::vector<std::tuple<PhysicalPageNumber, Page::page_type> > Microsoft::LEFormat::page_map_table

(LE only) The object page map table contents

The available documentation contradict each other, but each object page seems to map to a physical page offset within the file. In the LX format, the offset field of the object page table serves a similar purpose.

◆ ParameterNames

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

static

Initial value:

=
{
    &p_base_address,
    &p_align,
}

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

src/format/leexe.h
src/format/leexe.cc

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ compatibility_type

◆ output_type

◆ system_type

Member Function Documentation

◆ CalculateValues()

◆ Dump()

◆ FormatAdditionalSectionFlags()

◆ FormatSupportsLibraries()

◆ FormatSupportsResources()

◆ FormatSupportsSegmentation()

◆ GenerateFile()

◆ GetDefaultExtension()

◆ GetLinkerScriptParameterNames()

◆ GetOptions()

◆ ImageSize()

◆ OnNewSegment()

◆ ProcessModule()

◆ ReadFile()

◆ SetOptions()

◆ WriteFile()

Member Data Documentation

◆ page_map_table

◆ ParameterNames