Binary loader API. More...

#include <muteki/common.h>
#include <muteki/file.h>

Data Structures
struct	applet_args_v4_s
	Applet argument passing V4 struct. More...

struct	loader_cart_descriptor_s
	Cart file descriptor. More...

struct	loader_file_descriptor_s
	File descriptor specific to loader. More...

struct	loader_resource_descriptor_s
	Resource descriptor. More...

struct	loader_resource_subfile_request_s
	Resource descriptor subfile request. More...

struct	loader_image_info_s
	Executable image info. More...

struct	loader_impl_s
	Loader implementation vtable. More...

struct	loader_loaded_s
	Loaded applet executable. More...

struct	loader_applet_info_s
	Basic info on a loaded applet. More...

Typedefs
typedef struct applet_args_v4_s	applet_args_v4_t
	Applet argument passing V4 struct.

typedef struct loader_cart_descriptor_s	loader_cart_descriptor_t
	Cart file descriptor.

typedef struct loader_file_descriptor_s	loader_file_descriptor_t
	File descriptor specific to loader.

typedef struct loader_resource_descriptor_s	loader_resource_descriptor_t
	Resource descriptor.

typedef struct loader_resource_subfile_request_s	loader_resource_subfile_request_t
	Resource descriptor subfile request.

typedef struct loader_image_info_s	loader_image_info_t
	Executable image info.

typedef struct loader_impl_s	loader_impl_t
	Loader implementation vtable.

typedef struct loader_loaded_s	loader_loaded_t
	Loaded applet executable.

typedef struct loader_applet_info_s	loader_applet_info_t
	Basic info on a loaded applet.

Enumerations
enum	applet_subroutine_e { APPLET_SUBROUTINE_MAIN = 0 , APPLET_SUBROUTINE_RESET_STATES = 5 }

Functions
loader_file_descriptor_t *	_OpenFile (const char pathname, const char mode_or_subfile)
	Open a loader file descriptor from a file.

loader_file_descriptor_t *	_OpenFileW (const UTF16 pathname, const void mode_or_subfile)
	Open a loader file descriptor from a file (LFN path).

int	_CloseFile (loader_file_descriptor_t *ldrfd)
	Close a loader file descriptor.

size_t	_ReadFile (loader_file_descriptor_t ldrfd, void buf, size_t size)
	Read data from a loader file descriptor.

int	_FseekFile (loader_file_descriptor_t *ldrfd, size_t offset, int whence)
	Seek to a specific position in an opened sub-file.

ssize_t	_FileSize (loader_file_descriptor_t *ldrfd)
	Get the size of sub-file.

loader_file_descriptor_t *	_OpenSubFile (loader_file_descriptor_t *parent, size_t base, size_t max_size)
	Open a sub-file from a parent loader file descriptor.

ssize_t	_TellFile (loader_file_descriptor_t *ldrfd)
	Get the current offset of sub-file.

int	RunApplicationA (const char pathname, int subroutine, void applet_arg1, void *applet_arg2)
	Load and execute an applet by its DOS 8.3 pathname.

size_t	GetApplicationNameA (const char pathname, UTF16 out_name, size_t max_size)
	Get the title name of the ROM file.

loader_loaded_t *	LoadProgramA (const char *pathname)
	Load an applet executable.

int	FreeProgram (loader_loaded_t *applet)
	Unload a loaded applet.

int	ExecuteProgram (loader_loaded_t applet, int subroutine, const void applet_arg1, const void *applet_arg2)
	Invoke a specific subroutine of the loaded applet with arguments.

const char *	GetCurrentPathA (void)
	Get the path to the current running executable (argv[0]).

loader_loaded_t *	ProgramIsRunningA (const char *pathname)
	Return the instance of a running applet by its DOS 8.3 path name.

int	RunApplicationW (const UTF16 pathname, int subroutine, void applet_arg1, void *applet_arg2)
	Load and execute an applet by its LFN pathname.

size_t	GetApplicationNameW (const UTF16 pathname, UTF16 out_name, size_t max_size)
	Get the title name of the ROM file (LFN path).

loader_loaded_t *	LoadProgramW (const UTF16 *pathname)
	Load an applet executable. (UTF-16 variant)

const UTF16 *	GetCurrentPathW (void)
	Get the path to the current running executable (argv[0]). (UTF-16 variant)

loader_loaded_t *	ProgramIsRunningW (const UTF16 *pathname)
	Return the instance of a running applet by its LFN.

loader_loaded_t *	LoadHFileProgramW (loader_file_descriptor_t ldrfd, const UTF16 pathname)
	Load an applet executable from a loader file descriptor.

loader_loaded_t *	LoadHFileProgramA (loader_file_descriptor_t ldrfd, const char pathname)
	Load an applet executable from a loader file descriptor.

loader_loaded_t *	GetApplicationProcA (const char *pathname)
	Search and return the applet instance by DOS 8.3 pathname.

int	StayResidentProgramA (const char *pathname)
	Mark a loaded applet as stay resident by its DOS 8.3 pathname.

int	UnStayResidentProgramA (const char *pathname)
	Unmark a loaded applet as stay resident by its DOS 8.3 pathname.

int	CheckProgramIsStayResident (loader_loaded_t *applet)
	Check if an loaded applet has been set to stay resident.

loader_loaded_t *	GetApplicationProcW (const UTF16 *pathname)
	Search and return the applet instance by LFN.

int	StayResidentProgramW (const UTF16 *pathname)
	Mark a loaded applet as stay resident by its LFN pathname.

int	UnStayResidentProgramW (const UTF16 *pathname)
	Unmark a loaded applet as stay resident by its LFN pathname.

int	GetApplicationHeadInfoA (const char pathname, loader_applet_info_t info)
	Obtain information on loaded applet by its DOS 8.3 pathname.

int	GetApplicationHeadInfoW (const UTF16 pathname, loader_applet_info_t info)
	Obtain information on loaded applet by its LFN pathname.

Detailed Description

Binary loader API.

Typedef Documentation

◆ applet_args_v4_t

typedef struct applet_args_v4_s applet_args_v4_t

Applet argument passing V4 struct.

Mirrors the parameter set by the parent ExecuteProgram() call.

See also: ExecuteProgram

◆ loader_cart_descriptor_t

typedef struct loader_cart_descriptor_s loader_cart_descriptor_t

Cart file descriptor.

Todo:: Add more details.

◆ loader_image_info_t

typedef struct loader_image_info_s loader_image_info_t

Executable image info.

Todo:: Add more details.

◆ loader_impl_t

typedef struct loader_impl_s loader_impl_t

Loader implementation vtable.

Todo:: Add more details.

◆ loader_resource_descriptor_t

typedef struct loader_resource_descriptor_s loader_resource_descriptor_t

Resource descriptor.

Todo:: Add more details.

◆ loader_resource_subfile_request_t

typedef struct loader_resource_subfile_request_s loader_resource_subfile_request_t

Resource descriptor subfile request.

Todo:: Add more details.

Enumeration Type Documentation

◆ applet_subroutine_e

enum applet_subroutine_e

Defines the default subroutine identifiers to be used with ExecuteProgram().

See also: ExecuteProgram

Enumerator
APPLET_SUBROUTINE_MAIN	Run the main subroutine.
APPLET_SUBROUTINE_RESET_STATES	Run a subroutine that clears the persistent states of the applet.

Function Documentation

◆ _CloseFile()

int _CloseFile ( loader_file_descriptor_t * ldrfd )

extern

Close a loader file descriptor.

Syscall Number: 0x100ef

Parameters

ldrfd The loader file descriptor.

Return values

0	The operation was completed successfully.
-1	The operation failed with error.

◆ _FileSize()

ssize_t _FileSize ( loader_file_descriptor_t * ldrfd )

extern

Get the size of sub-file.

Syscall Number: 0x100f2

Parameters

ldrfd The loader file descriptor.

Returns: The size of the sub-file, or -1 when something is wrong.

◆ _FseekFile()

int _FseekFile	(	loader_file_descriptor_t *	ldrfd,
		size_t	offset,
		int	whence
	)

extern

Seek to a specific position in an opened sub-file.

Syscall Number: 0x100f1

Parameters

ldrfd	The loader file descriptor.
offset	Seek offset.
whence	Treat offset as relative to start of file/current offset/end of file.

Return values

0	The operation was completed successfully.
-1	The operation failed with error.

◆ _OpenFile()

loader_file_descriptor_t * _OpenFile	(	const char *	pathname,
		const char *	mode_or_subfile
	)

extern

Open a loader file descriptor from a file.

mode_or_subfile can either be a mode or one of the following UNC paths:

Path

Effect

\\.\ROMFILE Reopens the current ROM/applet file.

\\.\DATAFILE Opens the data partition of the cartridge as a file. More details TBA.

Syscall Number: 0x100ec

Parameters

[in]	pathname	DOS 8.3 path to the file.
[in]	mode_or_subfile	Either a mode string accepted by _afopen(), or a special UNC path to open assets of the current applet/cartridge.

Returns: Loader file descriptor

◆ _OpenFileW()

loader_file_descriptor_t * _OpenFileW	(	const UTF16 *	pathname,
		const void *	mode_or_subfile
	)

extern

Open a loader file descriptor from a file (LFN path).

Syscall Number: 0x100ee

Parameters

[in]	pathname	LFN path to the file.
[in]	mode_or_subfile	Either a mode string accepted by __wfopen() (in UTF-16), or a special UNC path (in ASCII) to open assets of the current applet/cartridge.

Returns: Loader file descriptor

◆ _OpenSubFile()

loader_file_descriptor_t * _OpenSubFile	(	loader_file_descriptor_t *	parent,
		size_t	base,
		size_t	max_size
	)

extern

Open a sub-file from a parent loader file descriptor.

Sub-files are areas in the parent file. The parameter base and max_size controls where and how large the area will be. The sub-file descriptors operate independently of the parent file descriptor, a la dup() in POSIX. This is also used internally to parse ROM files and asset packs.

Syscall Number: 0x100f3

Parameters

parent	Parent file descriptor.
base	Base offset of the file.
max_size	Max size of the area included in this sub-file.

Returns: The loader sub-file descriptor.

◆ _ReadFile()

size_t _ReadFile	(	loader_file_descriptor_t *	ldrfd,
		void *	buf,
		size_t	size
	)

extern

Read data from a loader file descriptor.

Syscall Number: 0x100f0

Parameters

	ldrfd	The loader file descriptor.
[out]	buf	Buffer that holds the data.
	size	Number of bytes to be read.

Returns: Actual number of bytes read.

◆ _TellFile()

ssize_t _TellFile ( loader_file_descriptor_t * ldrfd )

extern

Get the current offset of sub-file.

Syscall Number: 0x100f4

Parameters

ldrfd The loader file descriptor.

Returns: The offset of the sub-file, or -1 when something is wrong.

◆ CheckProgramIsStayResident()

int CheckProgramIsStayResident ( loader_loaded_t * applet )

extern

Check if an loaded applet has been set to stay resident.

Syscall Number: 0x1028c

Parameters

[in,out] applet Loaded applet descriptor to perform the check on.

Return values

0	Applet is not stay resident.
1	Applet is stay resident.

◆ ExecuteProgram()

int ExecuteProgram	(	loader_loaded_t *	applet,
		int	subroutine,
		const void *	applet_arg1,
		const void *	applet_arg2
	)

extern

Invoke a specific subroutine of the loaded applet with arguments.

Once called, the control is fully transferred to the loaded applet and this function will block until the invoked subroutine fully exits.

Actual format of arguments seem to be applet-specific.

Syscall Number: 0x10118

Parameters

prog	The loaded applet descriptor returned by LoadProgramA or LoadProgramW.
subroutine	Subroutine to invoke.
applet_arg1	Argument 1. Can either be a pointer to some data or an integer.
applet_arg2	Argument 2. Can either be a pointer to some data or an integer.

Returns: Exit value returned from the applet subroutine.

See also: LoadProgramA; LoadProgramW

◆ FreeProgram()

int FreeProgram ( loader_loaded_t * applet )

extern

Unload a loaded applet.

Syscall Number: 0x10117

Parameters

prog	The loaded executable description returned by LoadProgramA() or LoadProgramW().

See also: LoadProgramA; LoadProgramW

◆ GetApplicationHeadInfoA()

int GetApplicationHeadInfoA	(	const char *	pathname,
		loader_applet_info_t *	info
	)

extern

Obtain information on loaded applet by its DOS 8.3 pathname.

Syscall Number: 0x102cb

Parameters

	pathname	Pathname of the applet.
[out]	Information	on the applet.

Return values

0	The operation was completed successfully.
-1	The operation failed with error.

◆ GetApplicationHeadInfoW()

int GetApplicationHeadInfoW	(	const UTF16 *	pathname,
		loader_applet_info_t *	info
	)

extern

Obtain information on loaded applet by its LFN pathname.

Syscall Number: 0x102cc

Parameters

	pathname	Pathname of the applet.
[out]	Information	on the applet.

Return values

0	The operation was completed successfully.
-1	The operation failed with error.

◆ GetApplicationNameA()

size_t GetApplicationNameA	(	const char *	pathname,
		UTF16 *	out_name,
		size_t	max_size
	)

extern

Get the title name of the ROM file.

This will return UTF16-encoded localized title name that matches the current locale.

Syscall Number: 0x10115

Parameters

[in]	pathname	DOS 8.3 path to the ROM file or executable.
[out]	out_name	The title name in current locale.
	max_size	Max size of the title name.

Returns: Length of the title name in number of UTF16 code units.

◆ GetApplicationNameW()

size_t GetApplicationNameW	(	const UTF16 *	pathname,
		UTF16 *	out_name,
		size_t	max_size
	)

extern

Get the title name of the ROM file (LFN path).

This will return UTF16-encoded localized title name that matches the current locale.

Warning: Not all systems implement this. When not implemented, the length read will always be 0.

Syscall Number: 0x10280

Parameters

[in]	pathname	LFN path to the ROM file or executable.
[out]	out_name	The title name in current locale.
	max_size	Max size of the title name.

Returns: Length of the title name in number of UTF16 code units.

◆ GetApplicationProcA()

loader_loaded_t * GetApplicationProcA ( const char * pathname )

extern

Search and return the applet instance by DOS 8.3 pathname.

To query the current applet, one can use the following:

loader_loaded_t *current_applet = GetApplicationProcA(GetCurrentPathA());

GetCurrentPathA

const char * GetCurrentPathA(void)

Get the path to the current running executable (argv[0]).

GetApplicationProcA

loader_loaded_t * GetApplicationProcA(const char *pathname)

Search and return the applet instance by DOS 8.3 pathname.

loader_loaded_s

Loaded applet executable.

Definition loader.h:203

or

loader_loaded_t *current_applet = ProgramIsRunningA(GetCurrentPathA());

ProgramIsRunningA

loader_loaded_t * ProgramIsRunningA(const char *pathname)

Return the instance of a running applet by its DOS 8.3 path name.

Syscall Number: 0x10289

Parameters

pathname DOS 8.3 path to the loaded applet file.

Returns: Pointer to the applet instance, or NULL when applet is not loaded.

◆ GetApplicationProcW()

loader_loaded_t * GetApplicationProcW ( const UTF16 * pathname )

extern

Search and return the applet instance by LFN.

Similar to GetApplicationProcA(), to query the current applet, one can use the following:

loader_loaded_t *current_applet = GetApplicationProcW(GetCurrentPathW());

GetCurrentPathW

const UTF16 * GetCurrentPathW(void)

Get the path to the current running executable (argv[0]). (UTF-16 variant)

GetApplicationProcW

loader_loaded_t * GetApplicationProcW(const UTF16 *pathname)

Search and return the applet instance by LFN.

or

loader_loaded_t *current_applet = ProgramIsRunningW(GetCurrentPathW());

ProgramIsRunningW

loader_loaded_t * ProgramIsRunningW(const UTF16 *pathname)

Return the instance of a running applet by its LFN.

However using the GetApplicationProcA() counterpart results in slightly more performant code.

Syscall Number: 0x10292

Parameters

pathname LFN path to the loaded applet file.

Returns: Pointer to the applet instance, or NULL when applet is not loaded.

◆ GetCurrentPathA()

const char * GetCurrentPathA ( void )

extern

Get the path to the current running executable (argv[0]).

Syscall Number: 0x10119

Parameters: None.

Returns: The DOS 8.3 path to the current running executable.

◆ GetCurrentPathW()

const UTF16 * GetCurrentPathW ( void )

extern

Get the path to the current running executable (argv[0]). (UTF-16 variant)

Syscall Number: 0x10282

Parameters: None.

Returns: The UTF-16 LFN path to the current running executable.

◆ LoadHFileProgramA()

loader_loaded_t * LoadHFileProgramA	(	loader_file_descriptor_t *	ldrfd,
		const char *	pathname
	)

extern

Load an applet executable from a loader file descriptor.

Syscall Number: 0x10285

Parameters

ldrfd	Loader file descriptor of the applet executable.
pathname	DOS 8.3 path to the applet executable, or name of a registered system applet.

Returns: A pointer to a structure describing the loaded executable, or NULL if ldrfd is NULL or the loading process failed.

◆ LoadHFileProgramW()

loader_loaded_t * LoadHFileProgramW	(	loader_file_descriptor_t *	ldrfd,
		const UTF16 *	pathname
	)

extern

Load an applet executable from a loader file descriptor.

Syscall Number: 0x10284

Parameters

ldrfd	Loader file descriptor of the applet executable.
pathname	LFN path to the applet executable.

Returns: A pointer to a structure describing the loaded executable, or NULL if ldrfd is NULL or the loading process failed.

◆ LoadProgramA()

loader_loaded_t * LoadProgramA ( const char * pathname )

extern

Load an applet executable.

The pathname specified must be a DOS 8.3 name.

Syscall Number: 0x10116

Parameters

pathname Path to executable.

Returns: A pointer to a structure describing the loaded executable, or NULL if the loading process failed.

◆ LoadProgramW()

loader_loaded_t * LoadProgramW ( const UTF16 * pathname )

extern

Load an applet executable. (UTF-16 variant)

Syscall Number: 0x10281

Parameters

pathname UTF-16 LFN path to executable.

Returns: A pointer to a structure describing the loaded executable, or NULL if the loading process failed.

See also: LoadProgramA

◆ ProgramIsRunningA()

loader_loaded_t * ProgramIsRunningA ( const char * pathname )

extern

Return the instance of a running applet by its DOS 8.3 path name.

This is similar to GetApplicationProcA() but will return NULL in case loader_loaded_s::active_refcount of that applet is 0.

Syscall Number: 0x1011a

Parameters

pathname DOS 8.3 path to the ROM file or executable.

Returns: Pointer to the applet instance, or NULL when applet is not loaded or not currently running.

◆ ProgramIsRunningW()

loader_loaded_t * ProgramIsRunningW ( const UTF16 * pathname )

extern

Return the instance of a running applet by its LFN.

This is similar to GetApplicationProcW() but will return NULL in case loader_loaded_s::active_refcount of that applet is 0.

Syscall Number: 0x10283

Parameters

pathname LFN path to the ROM file or executable.

Returns: Pointer to the applet instance, or NULL when applet is not loaded or not currently running.

◆ RunApplicationA()

int RunApplicationA	(	const char *	pathname,
		int	subroutine,
		void *	applet_arg1,
		void *	applet_arg2
	)

extern

Load and execute an applet by its DOS 8.3 pathname.

Syscall Number: 0x10114

Parameters

pathname	DOS 8.3 path to the applet executable file, or name of a registered system applet.
subroutine	Subroutine to invoke.
applet_arg1	Argument 1. Can either be a pointer to some data or an integer.
applet_arg2	Argument 2. Can either be a pointer to some data or an integer.

Returns: Exit value returned from the applet subroutine.

◆ RunApplicationW()

int RunApplicationW	(	const UTF16 *	pathname,
		int	subroutine,
		void *	applet_arg1,
		void *	applet_arg2
	)

extern

Load and execute an applet by its LFN pathname.

Syscall Number: 0x1027f

Parameters

pathname	LFN path to the applet executable file.
subroutine	Subroutine to invoke.
applet_arg1	Argument 1. Can either be a pointer to some data or an integer.
applet_arg2	Argument 2. Can either be a pointer to some data or an integer.

Returns: Exit value returned from the applet subroutine.

◆ StayResidentProgramA()

int StayResidentProgramA ( const char * pathname )

extern

Mark a loaded applet as stay resident by its DOS 8.3 pathname.

This prevents the applet from being unloaded even when the applet is not running and after FreeProgram() has been called on it.

Syscall Number: 0x1028a

Parameters

pathname DOS 8.3 path to the applet executable file, or name of a registered system applet.

Return values

0	The operation was completed successfully.
-1	The operation failed with error.

◆ StayResidentProgramW()

int StayResidentProgramW ( const UTF16 * pathname )

extern

Mark a loaded applet as stay resident by its LFN pathname.

This prevents the applet from being unloaded even when the applet is not running and after FreeProgram() has been called on it.

Syscall Number: 0x10295

Parameters

pathname LFN path path to the applet executable file.

Return values

0	The operation was completed successfully.
-1	The operation failed with error.

◆ UnStayResidentProgramA()

int UnStayResidentProgramA ( const char * pathname )

extern

Unmark a loaded applet as stay resident by its DOS 8.3 pathname.

This reverts a previous StayResidentProgramA() call.

Syscall Number: 0x1028b

Parameters

pathname DOS 8.3 path to the applet executable file, or name of a registered system applet.

Return values

0	The operation was completed successfully.
-1	The operation failed with error.

◆ UnStayResidentProgramW()

int UnStayResidentProgramW ( const UTF16 * pathname )

extern

Unmark a loaded applet as stay resident by its LFN pathname.

This reverts a previous StayResidentProgramW() call.

Syscall Number: 0x10296

Parameters

pathname LFN path to the applet executable file.

Return values

0	The operation was completed successfully.
-1	The operation failed with error.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ applet_args_v4_t

◆ loader_cart_descriptor_t

◆ loader_image_info_t

◆ loader_impl_t

◆ loader_resource_descriptor_t

◆ loader_resource_subfile_request_t

Enumeration Type Documentation

◆ applet_subroutine_e

Function Documentation

◆ _CloseFile()

◆ _FileSize()

◆ _FseekFile()

◆ _OpenFile()

◆ _OpenFileW()

◆ _OpenSubFile()

◆ _ReadFile()

◆ _TellFile()

◆ CheckProgramIsStayResident()

◆ ExecuteProgram()

◆ FreeProgram()

◆ GetApplicationHeadInfoA()

◆ GetApplicationHeadInfoW()

◆ GetApplicationNameA()

◆ GetApplicationNameW()

◆ GetApplicationProcA()

◆ GetApplicationProcW()

◆ GetCurrentPathA()

◆ GetCurrentPathW()

◆ LoadHFileProgramA()

◆ LoadHFileProgramW()

◆ LoadProgramA()

◆ LoadProgramW()

◆ ProgramIsRunningA()

◆ ProgramIsRunningW()

◆ RunApplicationA()

◆ RunApplicationW()

◆ StayResidentProgramA()

◆ StayResidentProgramW()

◆ UnStayResidentProgramA()

◆ UnStayResidentProgramW()