DevKit7/libctru
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #182 from Steveice10/docs

Browse Source 
Finish documentation in include/3ds and include/3ds/util.
This commit is contained in:
fincs 2015-10-05 00:07:48 +02:00
commit c0b4a4bae1
17 changed files with 904 additions and 362 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
libctru/include/3ds/console.h
View File

@ -1,21 +1,16 @@
/*! \file console.h
\brief 3ds stdio support.
<div class="fileHeader">
Provides stdio integration for printing to the 3DS screen as well as debug print
functionality provided by stderr.
General usage is to initialize the console by:
consoleDemoInit()
or to customize the console usage by:
consoleInit()
/**
* @file console.h
* @brief 3ds stdio support.
*
* Provides stdio integration for printing to the 3DS screen as well as debug print
* functionality provided by stderr.
*
* General usage is to initialize the console by:
* consoleDemoInit()
* or to customize the console usage by:
* consoleInit()
*/
#ifndef CONSOLE_H
#define CONSOLE_H
#pragma once
#include <3ds/types.h>
#include <3ds/gfx.h>
@ -24,73 +19,74 @@ consoleInit()
extern "C" {
#endif
/// A callback for printing a character.
typedef bool(*ConsolePrint)(void* con, int c);
//! a font struct for the console.
/// A font struct for the console.
typedef struct ConsoleFont
{
u8* gfx; //!< A pointer to the font graphics
u16 asciiOffset; //!< Offset to the first valid character in the font table
u16 numChars; //!< Number of characters in the font graphics
u8* gfx; ///< A pointer to the font graphics
u16 asciiOffset; ///< Offset to the first valid character in the font table
u16 numChars; ///< Number of characters in the font graphics
}ConsoleFont;
/** \brief console structure used to store the state of a console render context.
Default values from consoleGetDefault();
<div class="fixedFont"><pre>
PrintConsole defaultConsole =
{
//Font:
{
(u8*)default_font_bin, //font gfx
0, //first ascii character in the set
128, //number of characters in the font set
},
0,0, //cursorX cursorY
0,0, //prevcursorX prevcursorY
40, //console width
30, //console height
0, //window x
0, //window y
32, //window width
24, //window height
3, //tab size
0, //font character offset
0, //print callback
false //console initialized
};
</pre></div>
/**
* @brief console structure used to store the state of a console render context.
*
* Default values from consoleGetDefault();
* <div class="fixedFont"><pre>
* PrintConsole defaultConsole =
* {
* //Font:
* {
* (u8*)default_font_bin, //font gfx
* 0, //first ascii character in the set
* 128, //number of characters in the font set
* },
* 0,0, //cursorX cursorY
* 0,0, //prevcursorX prevcursorY
* 40, //console width
* 30, //console height
* 0, //window x
* 0, //window y
* 32, //window width
* 24, //window height
* 3, //tab size
* 0, //font character offset
* 0, //print callback
* false //console initialized
* };
* </pre></div>
*/
typedef struct PrintConsole
{
ConsoleFont font; //!< font of the console.
ConsoleFont font; ///< Font of the console.
u16 *frameBuffer; //!< framebuffer address.
u16 *frameBuffer; ///< Framebuffer address.
int cursorX; /*!< Current X location of the cursor (as a tile offset by default) */
int cursorY; /*!< Current Y location of the cursor (as a tile offset by default) */
int cursorX; ///< Current X location of the cursor (as a tile offset by default)
int cursorY; ///< Current Y location of the cursor (as a tile offset by default)
int prevCursorX; /*!< Internal state */
int prevCursorY; /*!< Internal state */
int prevCursorX; ///< Internal state
int prevCursorY; ///< Internal state
int consoleWidth; /*!< Width of the console hardware layer in characters */
int consoleHeight; /*!< Height of the console hardware layer in characters */
int consoleWidth; ///< Width of the console hardware layer in characters
int consoleHeight; ///< Height of the console hardware layer in characters
int windowX; /*!< Window X location in characters (not implemented) */
int windowY; /*!< Window Y location in characters (not implemented) */
int windowWidth; /*!< Window width in characters (not implemented) */
int windowHeight; /*!< Window height in characters (not implemented) */
int windowX; ///< Window X location in characters (not implemented)
int windowY; ///< Window Y location in characters (not implemented)
int windowWidth; ///< Window width in characters (not implemented)
int windowHeight; ///< Window height in characters (not implemented)
int tabSize; /*!< Size of a tab*/
int fg; /*!< foreground color*/
int bg; /*!< background color*/
int flags; /*!< reverse/bright flags*/
int tabSize; ///< Size of a tab
int fg; ///< Foreground color
int bg; ///< Background color
int flags; ///< Reverse/bright flags
ConsolePrint PrintChar; /*!< callback for printing a character. Should return true if it has handled rendering the graphics
(else the print engine will attempt to render via tiles) */
ConsolePrint PrintChar; ///< Callback for printing a character. Should return true if it has handled rendering the graphics (else the print engine will attempt to render via tiles).
bool consoleInitialised; /*!< True if the console is initialized */
bool consoleInitialised; ///< True if the console is initialized
}PrintConsole;
#define CONSOLE_COLOR_BOLD (1<<0)
@ -103,58 +99,61 @@ typedef struct PrintConsole
#define CONSOLE_CONCEAL (1<<7)
#define CONSOLE_CROSSED_OUT (1<<8)
//! Console debug devices supported by libnds.
/// Console debug devices supported by libnds.
typedef enum {
debugDevice_NULL, //!< swallows prints to stderr
debugDevice_3DMOO, //!< Directs stderr debug statements to 3dmoo
debugDevice_CONSOLE, //!< Directs stderr debug statements to 3DS console window
debugDevice_NULL, ///< swallows prints to stderr
debugDevice_3DMOO, ///< Directs stderr debug statements to 3dmoo
debugDevice_CONSOLE, ///< Directs stderr debug statements to 3DS console window
} debugDevice;
/*! \brief Loads the font into the console
\param console pointer to the console to update, if NULL it will update the current console
\param font the font to load
/**
* @brief Loads the font into the console.
* @param console Pointer to the console to update, if NULL it will update the current console.
* @param font The font to load.
*/
void consoleSetFont(PrintConsole* console, ConsoleFont* font);
/*! \brief Sets the print window
\param console console to set, if NULL it will set the current console window
\param x x location of the window
\param y y location of the window
\param width width of the window
\param height height of the window
/**
* @brief Sets the print window.
* @param console Console to set, if NULL it will set the current console window.
* @param x X location of the window.
* @param y Y location of the window.
* @param width Width of the window.
* @param height Height of the window.
*/
void consoleSetWindow(PrintConsole* console, int x, int y, int width, int height);
/*! \brief Gets a pointer to the console with the default values
this should only be used when using a single console or without changing the console that is returned, other wise use consoleInit()
\return A pointer to the console with the default values
/**
* @brief Gets a pointer to the console with the default values.
* This should only be used when using a single console or without changing the console that is returned, otherwise use consoleInit().
* @return A pointer to the console with the default values.
*/
PrintConsole* consoleGetDefault(void);
/*! \brief Make the specified console the render target
\param console A pointer to the console struct (must have been initialized with consoleInit(PrintConsole* console)
\return a pointer to the previous console
/**
* @brief Make the specified console the render target.
* @param console A pointer to the console struct (must have been initialized with consoleInit(PrintConsole* console)).
* @return A pointer to the previous console.
*/
PrintConsole *consoleSelect(PrintConsole* console);
/*! \brief Initialise the console.
\param screen The screen to use for the console
\param console A pointer to the console data to initialze (if it's NULL, the default console will be used)
\return A pointer to the current console.
/**
* @brief Initialise the console.
* @param screen The screen to use for the console.
* @param console A pointer to the console data to initialize (if it's NULL, the default console will be used).
* @return A pointer to the current console.
*/
PrintConsole* consoleInit(gfxScreen_t screen, PrintConsole* console);
/*! \brief Initializes debug console output on stderr to the specified device
\param device The debug device (or devices) to output debug print statements to
/**
* @brief Initializes debug console output on stderr to the specified device.
* @param device The debug device (or devices) to output debug print statements to.
*/
void consoleDebugInit(debugDevice device);
//! Clears the screan by using iprintf("\x1b[2J");
/// Clears the screan by using iprintf("\x1b[2J");
void consoleClear(void);
#ifdef __cplusplus
}
#endif
#endif

6
libctru/include/3ds/gfx.h
View File

@ -13,10 +13,11 @@
#define RGB565(r,g,b) (((b)&0x1f)|(((g)&0x3f)<<5)|(((r)&0x1f)<<11))
#define RGB8_to_565(r,g,b) (((b)>>3)&0x1f)|((((g)>>2)&0x3f)<<5)|((((r)>>3)&0x1f)<<11)
/// Available screens.
typedef enum
{
GFX_TOP = 0,
GFX_BOTTOM = 1
GFX_TOP = 0, ///< Top screen
GFX_BOTTOM = 1 ///< Bottom screen
}gfxScreen_t;
/**
@ -29,7 +30,6 @@ typedef enum
{
GFX_LEFT = 0, ///< Left eye framebuffer
GFX_RIGHT = 1,///< Right eye framebuffer
// GFX_BOTTOM = 0
}gfx3dSide_t;

4
libctru/include/3ds/gpu/gx.h
View File

@ -32,9 +32,7 @@ typedef enum
GX_TRANSFER_SCALE_XY = 2, ///< 2x2 anti-aliasing
} GX_TRANSFER_SCALE;
/**
* @brief GX transfer control flags
*/
/// GX transfer control flags
typedef enum
{
GX_FILL_TRIGGER = 0x001, ///< Trigger the PPF event

7
libctru/include/3ds/ipc.h
View File

@ -7,11 +7,12 @@
#include <3ds/types.h>
/// IPC buffer access rights.
typedef enum
{
IPC_BUFFER_R = BIT(1),
IPC_BUFFER_W = BIT(2),
IPC_BUFFER_RW = IPC_BUFFER_R | IPC_BUFFER_W
IPC_BUFFER_R = BIT(1), ///< Readable
IPC_BUFFER_W = BIT(2), ///< Writable
IPC_BUFFER_RW = IPC_BUFFER_R | IPC_BUFFER_W ///< Readable and Writable
} IPC_BufferRights;

2
libctru/include/3ds/linear.h
View File

@ -4,8 +4,6 @@
*/
#pragma once
// Functions for allocating/deallocating memory from linear heap
/**
* @brief Allocates a 0x80-byte aligned buffer.
* @param size Size of the buffer to allocate.

2
libctru/include/3ds/mappable.h
View File

@ -4,8 +4,6 @@
*/
#pragma once
// Functions for allocating/deallocating mappable memory
/**
* @brief Allocates a page-aligned buffer.
* @param size Size of the buffer to allocate.

15
libctru/include/3ds/os.h
View File

@ -13,20 +13,20 @@
#define GET_VERSION_REVISION(version) (((version)>> 8)&0xFF)
/**
* Converts an address from virtual (process) memory to physical memory.
* @brief Converts an address from virtual (process) memory to physical memory.
* It is sometimes required by services or when using the GPU command buffer.
*/
u32 osConvertVirtToPhys(u32 vaddr);
/**
* Converts 0x14* vmem to 0x30*.
* @brief Converts 0x14* vmem to 0x30*.
* @return The input address when it's already within the new vmem.
* @return 0 when outside of either LINEAR mem areas.
*/
u32 osConvertOldLINEARMemToNew(u32 addr);
/**
* @brief Basic information about a service error.
* @brief Retreives basic information about a service error.
* @return A string of the summary of an error.
*
* This can be used to get some details about an error returned by a service call.
@ -34,14 +34,16 @@ u32 osConvertOldLINEARMemToNew(u32 addr);
const char* osStrError(u32 error);
/**
* @return the Firm version
* @brief Gets the system's FIRM version.
* @return The FIRM version.
*
* This can be used to compare system versions easily with @ref SYSTEM_VERSION.
*/
u32 osGetFirmVersion(void);
/**
* @return the kernel version
* @brief Gets the system's kernel version.
* @return The kernel version.
*
* This can be used to compare system versions easily with @ref SYSTEM_VERSION.
*
@ -52,7 +54,8 @@ u32 osGetFirmVersion(void);
u32 osGetKernelVersion(void);
/**
* @return number of milliseconds since 1st Jan 1900 00:00.
* @brief Gets the current time.
* @return The number of milliseconds since 1st Jan 1900 00:00.
*/
u64 osGetTime(void);

56
libctru/include/3ds/romfs.h
View File

@ -1,35 +1,59 @@
/**
* @file romfs.h
* @brief RomFS driver.
*/
#pragma once
#include <3ds/types.h>
/// RomFS header.
typedef struct
{
u32 headerSize;
u32 dirHashTableOff, dirHashTableSize;
u32 dirTableOff, dirTableSize;
u32 fileHashTableOff, fileHashTableSize;
u32 fileTableOff, fileTableSize;
u32 fileDataOff;
u32 headerSize; ///< Size of the header.
u32 dirHashTableOff; ///< Offset of the directory hash table.
u32 dirHashTableSize; ///< Size of the directory hash table.
u32 dirTableOff; ///< Offset of the directory table.
u32 dirTableSize; ///< Size of the directory table.
u32 fileHashTableOff; ///< Offset of the file hash table.
u32 fileHashTableSize; ///< Size of the file hash table.
u32 fileTableOff; ///< Offset of the file table.
u32 fileTableSize; ///< Size of the file table.
u32 fileDataOff; ///< Offset of the file data.
} romfs_header;
/// RomFS directory.
typedef struct
{
u32 parent, sibling;
u32 childDir, childFile;
u32 nextHash;
u32 nameLen;
u16 name[];
u32 parent; ///< Offset of the parent directory.
u32 sibling; ///< Offset of the next sibling directory.
u32 childDir; ///< Offset of the first child directory.
u32 childFile; ///< Offset of the first file.
u32 nextHash; ///< Directory hash table pointer.
u32 nameLen; ///< Name length.
u16 name[]; ///< Name. (UTF-16)
} romfs_dir;
/// RomFS file.
typedef struct
{
u32 parent, sibling;
u64 dataOff, dataSize;
u32 nextHash;
u32 nameLen;
u16 name[];
u32 parent; ///< Offset of the parent directory.
u32 sibling; ///< Offset of the next sibling file.
u64 dataOff; ///< Offset of the file's data.
u64 dataSize; ///< Length of the file's data.
u32 nextHash; ///< File hash table pointer.
u32 nameLen; ///< Name length.
u16 name[]; ///< Name. (UTF-16)
} romfs_file;
/// Initializes the RomFS driver.
Result romfsInit(void);
/**
* @brief Initializes the RomFS driver from a RomFS file.
* @param file Handle of the RomFS file.
* @param offset Offset of the RomFS within the file.
*/
Result romfsInitFromFile(Handle file, u32 offset);
/// Exits the RomFS driver.
Result romfsExit(void);

8
libctru/include/3ds/sdmc.h
View File

@ -6,12 +6,8 @@
#include <3ds/types.h>
/**
* @brief Initializes the SDMC driver.
*/
/// Initializes the SDMC driver.
Result sdmcInit(void);
/**
* @brief Exits the SDMC driver.
*/
/// Exits the SDMC driver.
Result sdmcExit(void);

101
libctru/include/3ds/services/fs.h
View File

@ -1,12 +1,13 @@
/**
* @file FS.h
* @brief Filesystem Services
*/
#pragma once
#include <3ds/types.h>
/*! @file FS.h
*
* Filesystem Services
*/
/*! @defgroup fs_open_flags FS Open Flags
/**
* @defgroup fs_open_flags FS Open Flags
*
* @sa FSUSER_OpenFile
* @sa FSUSER_OpenFileDirectly
@ -14,15 +15,16 @@
* @{
*/
/*! Open file for read. */
/// Open file for read.
#define FS_OPEN_READ (1<<0)
/*! Open file for write. */
/// Open file for write.
#define FS_OPEN_WRITE (1<<1)
/*! Create file if it doesn't exist. */
/// Create file if it doesn't exist.
#define FS_OPEN_CREATE (1<<2)
/* @} */
/// @}
/*! @defgroup fs_create_attributes FS Create Attributes
/**
* @defgroup fs_create_attributes FS Create Attributes
*
* @sa FSUSER_OpenFile
* @sa FSUSER_OpenFileDirectly
@ -30,43 +32,44 @@
* @{
*/
/*! No attributes. */
/// No attributes.
#define FS_ATTRIBUTE_NONE (0x00000000)
/*! Create with read-only attribute. */
/// Create with read-only attribute.
#define FS_ATTRIBUTE_READONLY (0x00000001)
/*! Create with archive attribute. */
/// Create with archive attribute.
#define FS_ATTRIBUTE_ARCHIVE (0x00000100)
/*! Create with hidden attribute. */
/// Create with hidden attribute.
#define FS_ATTRIBUTE_HIDDEN (0x00010000)
/*! Create with directory attribute. */
/// Create with directory attribute.
#define FS_ATTRIBUTE_DIRECTORY (0x01000000)
/*! @} */
/// @}
/*! @defgroup fs_write_flush_flags FS Flush Flags
/**
* @defgroup fs_write_flush_flags FS Flush Flags
*
* @sa FSFILE_Write
*
* @{
*/
/*! Don't flush */
/// Don't flush
#define FS_WRITE_NOFLUSH (0x00000000)
/*! Flush */
/// Flush
#define FS_WRITE_FLUSH (0x00010001)
/* @} */
/// @}
/*! FS path type */
/// FS path type
typedef enum
{
PATH_INVALID = 0, //!< Specifies an invalid path.
PATH_EMPTY = 1, //!< Specifies an empty path.
PATH_BINARY = 2, //!< Specifies a binary path, which is non-text based.
PATH_CHAR = 3, //!< Specifies a text based path with a 8-bit byte per character.
PATH_WCHAR = 4, //!< Specifies a text based path with a 16-bit short per character.
PATH_INVALID = 0, ///< Specifies an invalid path.
PATH_EMPTY = 1, ///< Specifies an empty path.
PATH_BINARY = 2, ///< Specifies a binary path, which is non-text based.
PATH_CHAR = 3, ///< Specifies a text based path with a 8-bit byte per character.
PATH_WCHAR = 4, ///< Specifies a text based path with a 16-bit short per character.
} FS_pathType;
/*! FS archive ids */
/// FS archive ids
typedef enum
{
ARCH_ROMFS = 0x3,
@ -83,48 +86,48 @@ typedef enum
ARCH_NAND_RO_WRITE_ACCESS = 0x1234567F,
} FS_archiveIds;
/*! FS path */
/// FS path
typedef struct
{
FS_pathType type; //!< FS path type.
u32 size; //!< FS path size.
const u8 *data; //!< Pointer to FS path data.
FS_pathType type; ///< FS path type.
u32 size; ///< FS path size.
const u8 *data; ///< Pointer to FS path data.
} FS_path;
/*! FS archive */
/// FS archive
typedef struct
{
u32 id; //!< Archive ID.
FS_path lowPath; //!< FS path.
Handle handleLow; //!< High word of handle.
Handle handleHigh; //!< Low word of handle.
u32 id; ///< Archive ID.
FS_path lowPath; ///< FS path.
Handle handleLow; ///< High word of handle.
Handle handleHigh; ///< Low word of handle.
} FS_archive;
/*! Directory entry */
/// Directory entry
typedef struct
{
// 0x00
u16 name[0x106]; //!< UTF-16 encoded name
u16 name[0x106]; ///< UTF-16 encoded name
// 0x20C
u8 shortName[0x09]; //!< 8.3 file name
u8 shortName[0x09]; ///< 8.3 file name
// 0x215
u8 unknown1; //!< ???
u8 unknown1; ///< ???
// 0x216
u8 shortExt[0x04]; //!< 8.3 file extension (set to spaces for directories)
u8 shortExt[0x04]; ///< 8.3 file extension (set to spaces for directories)
// 0x21A
u8 unknown2; //!< ???
u8 unknown2; ///< ???
// 0x21B
u8 unknown3; //!< ???
u8 unknown3; ///< ???
// 0x21C
u8 isDirectory; //!< directory bit
u8 isDirectory; ///< directory bit
// 0x21D
u8 isHidden; //!< hidden bit
u8 isHidden; ///< hidden bit
// 0x21E
u8 isArchive; //!< archive bit
u8 isArchive; ///< archive bit
// 0x21F
u8 isReadOnly; //!< read-only bit
u8 isReadOnly; ///< read-only bit
// 0x220
u64 fileSize; //!< file size
u64 fileSize; ///< file size
} FS_dirent;
Result fsInit(void);

51
libctru/include/3ds/srv.h
View File

@ -1,14 +1,65 @@
/**
* @file srv.h
* @brief Service API.
*/
#pragma once
/// Initializes the service API.
Result srvInit(void);
/// Exits the service API.
Result srvExit(void);
/**
* @brief Gets the current service API session handle.
* @return The current service API session handle.
*/
Handle *srvGetSessionHandle(void);
/// Registers the current process as a client to the service API.
Result srvRegisterClient(void);
/**
* @brief Retrieves a service handle, bypassing the handle list.
* @param out Pointer to write the handle to.
* @param name Name of the service.
*/
Result srvGetServiceHandleDirect(Handle* out, const char* name);
/**
* @brief Retrieves a service handle.
* @param out Pointer to write the handle to.
* @param name Name of the service.
*/
Result srvGetServiceHandle(Handle* out, const char* name);
/**
* @brief Registers the current process as a service.
* @param out Pointer to write the service handle to.
* @param name Name of the service.
* @param maxSessions Maximum number of sessions the service can handle.
*/
Result srvRegisterService(Handle* out, const char* name, int maxSessions);
/**
* @brief Unregisters the current process as a service.
* @param name Name of the service.
*/
Result srvUnregisterService(const char* name);
/// Initializes the srv:pm port.
Result srvPmInit(void);
/**
* @brief Registers a process with srv:pm.
* @param procid ID of the process to register.
* @param count Number of services to register access to.
* @param serviceaccesscontrol Service access permissions of the process.
*/
Result srvRegisterProcess(u32 procid, u32 count, void *serviceaccesscontrol);
/**
* @brief Unregisters a process with srv:pm.
* @param procid ID of the process to unregister.
*/
Result srvUnregisterProcess(u32 procid);

575
libctru/include/3ds/svc.h
View File

@ -2,7 +2,6 @@
* @file svc.h
* @brief Syscall wrappers.
*/
#pragma once
#include "types.h"
@ -27,54 +26,55 @@ typedef enum {
MEMOP_UNMAP = 5, ///< Mirror unmapping
MEMOP_PROT = 6, ///< Change protection
MEMOP_REGION_APP = 0x100,
MEMOP_REGION_SYSTEM = 0x200,
MEMOP_REGION_BASE = 0x300,
MEMOP_REGION_APP = 0x100, ///< APPLICATION memory region.
MEMOP_REGION_SYSTEM = 0x200, ///< SYSTEM memory region.
MEMOP_REGION_BASE = 0x300, ///< BASE memory region.
MEMOP_OP_MASK = 0xFF,
MEMOP_REGION_MASK = 0xF00,
MEMOP_LINEAR_FLAG = 0x10000, ///< Flag for linear memory operations
MEMOP_ALLOC_LINEAR = MEMOP_LINEAR_FLAG | MEMOP_ALLOC,
MEMOP_ALLOC_LINEAR = MEMOP_LINEAR_FLAG | MEMOP_ALLOC, ///< Allocates linear memory.
} MemOp;
/// The state of a memory block.
typedef enum {
MEMSTATE_FREE = 0,
MEMSTATE_RESERVED = 1,
MEMSTATE_IO = 2,
MEMSTATE_STATIC = 3,
MEMSTATE_CODE = 4,
MEMSTATE_PRIVATE = 5,
MEMSTATE_SHARED = 6,
MEMSTATE_CONTINUOUS = 7,
MEMSTATE_ALIASED = 8,
MEMSTATE_ALIAS = 9,
MEMSTATE_ALIASCODE = 10,
MEMSTATE_LOCKED = 11
MEMSTATE_FREE = 0, ///< Free memory
MEMSTATE_RESERVED = 1, ///< Reserved memory
MEMSTATE_IO = 2, ///< I/O memory
MEMSTATE_STATIC = 3, ///< Static memory
MEMSTATE_CODE = 4, ///< Code memory
MEMSTATE_PRIVATE = 5, ///< Private memory
MEMSTATE_SHARED = 6, ///< Shared memory
MEMSTATE_CONTINUOUS = 7, ///< Continuous memory
MEMSTATE_ALIASED = 8, ///< Aliased memory
MEMSTATE_ALIAS = 9, ///< Alias memory
MEMSTATE_ALIASCODE = 10, ///< Aliased code memory
MEMSTATE_LOCKED = 11 ///< Locked memory
} MemState;
/**
* @brief Memory permission flags
*/
/// Memory permission flags
typedef enum {
MEMPERM_READ = 1,
MEMPERM_WRITE = 2,
MEMPERM_EXECUTE = 4,
MEMPERM_DONTCARE = 0x10000000
MEMPERM_READ = 1, ///< Readable
MEMPERM_WRITE = 2, ///< Writable
MEMPERM_EXECUTE = 4, ///< Executable
MEMPERM_DONTCARE = 0x10000000 ///< Don't care
} MemPerm;
/// Memory information.
typedef struct {
u32 base_addr;
u32 size;
u32 perm; ///< See @ref MemPerm
u32 state; ///< See @ref MemState
u32 base_addr; ///< Base address.
u32 size; ///< Size.
u32 perm; ///< Memory permissions. See @ref MemPerm
u32 state; ///< Memory state. See @ref MemState
} MemInfo;
/// Memory page information.
typedef struct {
u32 flags;
u32 flags; ///< Page flags.
} PageInfo;
/// Arbitration modes.
typedef enum {
ARBITRATION_SIGNAL = 0, ///< Signal #value threads for wake-up.
ARBITRATION_WAIT_IF_LESS_THAN = 1, ///< If the memory at the address is strictly lower than #value, then wait for signal.
@ -91,8 +91,9 @@ typedef enum {
///@name Multithreading
///@{
/// Types of thread info.
typedef enum {
THREADINFO_TYPE_UNKNOWN
THREADINFO_TYPE_UNKNOWN ///< Unknown.
} ThreadInfoType;
/// Pseudo handle for the current thread
@ -103,127 +104,148 @@ typedef enum {
///@name Debugging
///@{
/// Reasons for a process event.
typedef enum {
REASON_CREATE = 1,
REASON_ATTACH = 2
REASON_CREATE = 1, ///< Process created.
REASON_ATTACH = 2 ///< Process attached.
} ProcessEventReason;
/// Event relating to a process.
typedef struct {
u64 program_id;
u8 process_name[8];
u32 process_id;
u32 reason; ///< See @ref ProcessEventReason
u64 program_id; ///< ID of the program.
u8 process_name[8]; ///< Name of the process.
u32 process_id; ///< ID of the process.
u32 reason; ///< Reason for the event. See @ref ProcessEventReason
} ProcessEvent;
/// Reasons for an exit process event.
typedef enum {
EXITPROCESS_EVENT_NONE = 0,
EXITPROCESS_EVENT_TERMINATE = 1,
EXITPROCESS_EVENT_UNHANDLED_EXCEPTION = 2
EXITPROCESS_EVENT_NONE = 0, ///< No reason.
EXITPROCESS_EVENT_TERMINATE = 1, ///< Process terminated.
EXITPROCESS_EVENT_UNHANDLED_EXCEPTION = 2 ///< Unhandled exception occurred.
} ExitProcessEventReason;
/// Event relating to the exiting of a process.
typedef struct {
u32 reason; ///< See @ref ExitProcessEventReason
u32 reason; ///< Reason for exiting. See @ref ExitProcessEventReason
} ExitProcessEvent;
/// Event relating to the creation of a thread.
typedef struct {
u32 creator_thread_id;
u32 base_addr;
u32 entry_point;
u32 creator_thread_id; ///< ID of the creating thread.
u32 base_addr; ///< Base address.
u32 entry_point; ///< Entry point of the thread.
} CreateThreadEvent;
/// Reasons for an exit thread event.
typedef enum {
EXITTHREAD_EVENT_NONE = 0,
EXITTHREAD_EVENT_TERMINATE = 1,
EXITTHREAD_EVENT_UNHANDLED_EXC = 2,
EXITTHREAD_EVENT_TERMINATE_PROCESS = 3
EXITTHREAD_EVENT_NONE = 0, ///< No reason.
EXITTHREAD_EVENT_TERMINATE = 1, ///< Thread terminated.
EXITTHREAD_EVENT_UNHANDLED_EXC = 2, ///< Unhandled exception occurred.
EXITTHREAD_EVENT_TERMINATE_PROCESS = 3 ///< Process terminated.
} ExitThreadEventReason;
/// Event relating to the exiting of a thread.
typedef struct {
u32 reason; ///< See @ref ExitThreadEventReason
u32 reason; ///< Reason for exiting. See @ref ExitThreadEventReason
} ExitThreadEvent;
/// Reasons for a user break.
typedef enum {
USERBREAK_PANIC = 0,
USERBREAK_ASSERT = 1,
USERBREAK_USER = 2
USERBREAK_PANIC = 0, ///< Panic.
USERBREAK_ASSERT = 1, ///< Assertion failed.
USERBREAK_USER = 2 ///< User related.
} UserBreakType;
/// Reasons for an exception event.
typedef enum {
EXC_EVENT_UNDEFINED_INSTRUCTION = 0, ///< arg: (None)
EXC_EVENT_UNKNOWN1 = 1, ///< arg: (None)
EXC_EVENT_UNKNOWN2 = 2, ///< arg: address
EXC_EVENT_UNKNOWN3 = 3, ///< arg: address
EXC_EVENT_ATTACH_BREAK = 4, ///< arg: (None)
EXC_EVENT_BREAKPOINT = 5, ///< arg: (None)
EXC_EVENT_USER_BREAK = 6, ///< arg: @ref UserBreakType
EXC_EVENT_DEBUGGER_BREAK = 7, ///< arg: (None)
EXC_EVENT_UNDEFINED_SYSCALL = 8 ///< arg: attempted syscall
EXC_EVENT_UNDEFINED_INSTRUCTION = 0, ///< Undefined instruction. arg: (None)
EXC_EVENT_UNKNOWN1 = 1, ///< Unknown. arg: (None)
EXC_EVENT_UNKNOWN2 = 2, ///< Unknown. arg: address
EXC_EVENT_UNKNOWN3 = 3, ///< Unknown. arg: address
EXC_EVENT_ATTACH_BREAK = 4, ///< Attached break. arg: (None)
EXC_EVENT_BREAKPOINT = 5, ///< Breakpoint reached. arg: (None)
EXC_EVENT_USER_BREAK = 6, ///< User break occurred. arg: @ref UserBreakType
EXC_EVENT_DEBUGGER_BREAK = 7, ///< Debugger break occurred. arg: (None)
EXC_EVENT_UNDEFINED_SYSCALL = 8 ///< Undefined syscall. arg: attempted syscall
} ExceptionEventType;
/// Event relating to exceptions.
typedef struct {
u32 type; ///< See @ref ExceptionEventType
u32 address;
u32 argument; ///< See @ref ExceptionEventType
u32 type; ///< Type of event. See @ref ExceptionEventType
u32 address; ///< Address of the exception.
u32 argument; ///< Event argument. See @ref ExceptionEventType
} ExceptionEvent;
/// Event relating to the scheduler.
typedef struct {
u64 clock_tick;
u64 clock_tick; ///< Clock tick that the event occurred.
} SchedulerInOutEvent;
/// Event relating to syscalls.
typedef struct {
u64 clock_tick;
u32 syscall;
u64 clock_tick; ///< Clock tick that the event occurred.
u32 syscall; ///< Syscall sent/received.
} SyscallInOutEvent;
/// Event relating to debug output.
typedef struct {
u32 string_addr;
u32 string_size;
u32 string_addr; ///< Address of the outputted string.
u32 string_size; ///< Size of the outputted string.
} OutputStringEvent;
/// Event relating to the mapping of memory.
typedef struct {
u32 mapped_addr;
u32 mapped_size;
u32 memperm;
u32 memstate;
u32 mapped_addr; ///< Mapped address.
u32 mapped_size; ///< Mapped size.
u32 memperm; ///< Memory permissions. See @ref MemPerm
u32 memstate; ///< Memory state. See @ref MemState
} MapEvent;
/// Debug event type.
typedef enum {
DBG_EVENT_PROCESS = 0,
DBG_EVENT_CREATE_THREAD = 1,
DBG_EVENT_EXIT_THREAD = 2,
DBG_EVENT_EXIT_PROCESS = 3,
DBG_EVENT_EXCEPTION = 4,
DBG_EVENT_DLL_LOAD = 5,
DBG_EVENT_DLL_UNLOAD = 6,
DBG_EVENT_SCHEDULE_IN = 7,
DBG_EVENT_SCHEDULE_OUT = 8,
DBG_EVENT_SYSCALL_IN = 9,
DBG_EVENT_SYSCALL_OUT = 10,
DBG_EVENT_OUTPUT_STRING = 11,
DBG_EVENT_MAP = 12
DBG_EVENT_PROCESS = 0, ///< Process event.
DBG_EVENT_CREATE_THREAD = 1, ///< Thread creation event.
DBG_EVENT_EXIT_THREAD = 2, ///< Thread exit event.
DBG_EVENT_EXIT_PROCESS = 3, ///< Process exit event.
DBG_EVENT_EXCEPTION = 4, ///< Exception event.
DBG_EVENT_DLL_LOAD = 5, ///< DLL load event.
DBG_EVENT_DLL_UNLOAD = 6, ///< DLL unload event.
DBG_EVENT_SCHEDULE_IN = 7, ///< Schedule in event.
DBG_EVENT_SCHEDULE_OUT = 8, ///< Schedule out event.
DBG_EVENT_SYSCALL_IN = 9, ///< Syscall in event.
DBG_EVENT_SYSCALL_OUT = 10, ///< Syscall out event.
DBG_EVENT_OUTPUT_STRING = 11, ///< Output string event.
DBG_EVENT_MAP = 12 ///< Map event.
} DebugEventType;
/// Information about a debug event.
typedef struct {
u32 type; ///< See @ref DebugEventType
u32 thread_id;
u32 unknown[2];
u32 type; ///< Type of event. See @ref DebugEventType
u32 thread_id; ///< ID of the thread.
u32 unknown[2]; ///< Unknown data.
union {
ProcessEvent process;
CreateThreadEvent create_thread;
ExitThreadEvent exit_thread;
ExitProcessEvent exit_process;
ExceptionEvent exception;
ProcessEvent process; ///< Process event data.
CreateThreadEvent create_thread; ///< Thread creation event data.
ExitThreadEvent exit_thread; ///< Thread exit event data.
ExitProcessEvent exit_process; ///< Process exit event data.
ExceptionEvent exception; ///< Exception event data.
/* TODO: DLL_LOAD */
/* TODO: DLL_UNLOAD */
SchedulerInOutEvent scheduler;
SyscallInOutEvent syscall;
OutputStringEvent output_string;
MapEvent map;
SchedulerInOutEvent scheduler; ///< Schedule in/out event data.
SyscallInOutEvent syscall; ///< Syscall in/out event data.
OutputStringEvent output_string; ///< Output string event data.
MapEvent map; ///< Map event data.
};
} DebugEventInfo;
///@}
/**
* @brief Gets the thread local storage buffer.
* @return The thread local storage bufger.
*/
static inline void* getThreadLocalStorage(void)
{
void* ret;
@ -231,11 +253,19 @@ static inline void* getThreadLocalStorage(void)
return ret;
}
/**
* @brief Gets the thread command buffer.
* @return The thread command bufger.
*/
static inline u32* getThreadCommandBuffer(void)
{
return (u32*)((u8*)getThreadLocalStorage() + 0x80);
}
/**
* @brief Gets the thread static buffer.
* @return The thread static bufger.
*/
static inline u32* getThreadStaticBuffers(void)
{
return (u32*)((u8*)getThreadLocalStorage() + 0x180);
@ -243,7 +273,6 @@ static inline u32* getThreadStaticBuffers(void)
///@name Memory management
///@{
/**
* @brief Controls memory mapping
* @param[out] addr_out The virtual address resulting from the operation. Usually the same as addr0.
@ -281,55 +310,183 @@ Result svcControlProcessMemory(Handle process, u32 addr0, u32 addr1, u32 size, u
/**
* @brief Creates a block of shared memory
* @param memblock Pointer to store the handle of the block
* @param[out] memblock Pointer to store the handle of the block
* @param addr Address of the memory to map, page-aligned. So its alignment must be 0x1000.
* @param size Size of the memory to map, a multiple of 0x1000.
* @param my_perm Memory permissions for the current process
* @param my_perm Memory permissions for the other processes
* @param other_perm Memory permissions for the other processes
*
* @note The shared memory block, and its rights, are destroyed when the handle is closed.
*/
Result svcCreateMemoryBlock(Handle* memblock, u32 addr, u32 size, MemPerm my_perm, MemPerm other_perm);
/**
* @brief Maps a block of shared memory
* @param memblock Handle of the block
* @param addr Address of the memory to map, page-aligned. So its alignment must be 0x1000.
* @param my_perm Memory permissions for the current process
* @param other_perm Memory permissions for the other processes
*
* @note The shared memory block, and its rights, are destroyed when the handle is closed.
*/
Result svcMapMemoryBlock(Handle memblock, u32 addr, MemPerm my_perm, MemPerm other_perm);
/**
* @brief Maps a block of process memory.
* @param process Handle of the process.
* @param startAddr Start address of the memory to map.
* @param endAddr End address of the memory to map.
*/
Result svcMapProcessMemory(Handle process, u32 startAddr, u32 endAddr);
/**
* @brief Unmaps a block of process memory.
* @param process Handle of the process.
* @param startAddr Start address of the memory to unmap.
* @param endAddr End address of the memory to unmap.
*/
Result svcUnmapProcessMemory(Handle process, u32 startAddr, u32 endAddr);
/**
* @brief Unmaps a block of shared memory
* @param memblock Handle of the block
* @param addr Address of the memory to unmap, page-aligned. So its alignment must be 0x1000.
*/
Result svcUnmapMemoryBlock(Handle memblock, u32 addr);
Result svcStartInterProcessDma(Handle* dma, Handle dstProcess, void* dst, Handle srcProcess, const void* src, u32 size, void* dmaConfig);
Result svcStopDma(Handle dma);
Result svcGetDmaState(void* dmaState, Handle dma);
/**
* @brief Memory information query
* @param addr Virtual memory address
* @brief Begins an inter-process DMA.
* @param[out] dma Pointer to output the handle of the DMA to.
* @param dstProcess Destination process.
* @param dst Buffer to write data to.
* @param srcprocess Source process.
* @param src Buffer to read data from.
* @param size Size of the data to DMA.
* @param dmaConfig DMA configuration data.
*/
Result svcStartInterProcessDma(Handle* dma, Handle dstProcess, void* dst, Handle srcProcess, const void* src, u32 size, void* dmaConfig);
/**
* @brief Terminates an inter-process DMA.
* @param dma Handle of the DMA.
*/
Result svcStopDma(Handle dma);
/**
* @brief Gets the state of an inter-process DMA.
* @param[out] dmaState Pointer to output the state of the DMA to.
* @param dma Handle of the DMA.
*/
Result svcGetDmaState(void* dmaState, Handle dma);
/**
* @brief Queries memory information.
* @param[out] info Pointer to output memory info to.
* @param out Pointer to output page info to.
* @param addr Virtual memory address to query.
*/
Result svcQueryMemory(MemInfo* info, PageInfo* out, u32 addr);
/**
* @brief Queries process memory information.
* @param[out] info Pointer to output memory info to.
* @param[out] out Pointer to output page info to.
* @param process Process to query memory from.
* @param addr Virtual memory address to query.
*/
Result svcQueryProcessMemory(MemInfo* info, PageInfo* out, Handle process, u32 addr);
/**
* @brief Invalidates a process's data cache.
* @param process Handle of the process.
* @param addr Address to invalidate.
* @param size Size of the memory to invalidate.
*/
Result svcInvalidateProcessDataCache(Handle process, void* addr, u32 size);
/**
* @brief Flushes a process's data cache.
* @param process Handle of the process.
* @param addr Address to flush.
* @param size Size of the memory to flush.
*/
Result svcFlushProcessDataCache(Handle process, void const* addr, u32 size);
/**
* @brief Reads from a process's memory.
* @param buffer Buffer to read data to.
* @param debug Debug handle of the process.
* @param addr Address to read from.
* @param size Size of the memory to read.
*/
Result svcReadProcessMemory(void* buffer, Handle debug, u32 addr, u32 size);
/**
* @brief Writes to a process's memory.
* @param debug Debug handle of the process.
* @param buffer Buffer to write data from.
* @param addr Address to write to.
* @param size Size of the memory to write.
*/
Result svcWriteProcessMemory(Handle debug, const void* buffer, u32 addr, u32 size);
///@}
///@name Process management
///@{
/**
* @brief Gets the handle of a process.
* @param[out] process The handle of the process
* @param processId The ID of the process to open
*/
Result svcOpenProcess(Handle* process, u32 processId);
/// Exits the current process.
void svcExitProcess() __attribute__((noreturn));
/**
* @brief Terminates a process.
* @param process Handle of the process to terminate.
*/
Result svcTerminateProcess(Handle process);
/**
* @brief Gets information about a process.
* @param[out] out Pointer to output process info to.
* @param process Handle of the process to get information about.
* @param type Type of information to retreieve.
*/
Result svcGetProcessInfo(s64* out, Handle process, u32 type);
/**
* @brief Gets the ID of a process.
* @param[out] out Pointer to output the process ID to.
* @param handle Handle of the process to get the ID of.
*/
Result svcGetProcessId(u32 *out, Handle handle);
/**
* @brief Gets a list of running processes.
* @param[out] processCount Pointer to output the process count to.
* @param[out] processIds Pointer to output the process IDs to.
* @param processIdMaxCount Maximum number of process IDs.
*/
Result svcGetProcessList(s32* processCount, u32* processIds, s32 processIdMaxCount);
/**
* @brief Creates a port.
* @param[out] portServer Pointer to output the port server handle to.
* @param[out] portClient Pointer to output the port client handle to.
* @param name Name of the port.
* @param maxSessions Maximum number of sessions that can connect to the port.
*/
Result svcCreatePort(Handle* portServer, Handle* portClient, const char* name, s32 maxSessions);
/**
* @brief Connects to a port.
* @param[out] out Pointer to output the port handle to.
* @param portName Name of the port.
*/
Result svcConnectToPort(volatile Handle* out, const char* portName);
///@}
@ -378,9 +535,7 @@ void svcExitThread(void) __attribute__((noreturn));
*/
void svcSleepThread(s64 ns);
/**
* @brief Retrieves the priority of a thread.
*/
/// Retrieves the priority of a thread.
Result svcGetThreadPriority(s32 *out, Handle handle);
/**
@ -390,9 +545,35 @@ Result svcGetThreadPriority(s32 *out, Handle handle);
* Low values gives the thread higher priority.
*/
Result svcSetThreadPriority(Handle thread, s32 prio);
/**
* @brief Gets a thread's affinity mask.
* @param[out] affinitymask Pointer to output the affinity masks to.
* @param thread Handle of the thread.
* @param processorcount Number of processors.
*/
Result svcGetThreadAffinityMask(u8* affinitymask, Handle thread, s32 processorcount);
/**
* @brief Sets a thread's affinity mask.
* @param thread Handle of the thread.
* @param affinitymask Pointer to retreive the affinity masks from.
* @param processorcount Number of processors.
*/
Result svcSetThreadAffinityMask(Handle thread, u8* affinitymask, s32 processorcount);
/**
* @brief Gets a thread's ideal processor.
* @param[out] processorid Pointer to output the ID of the thread's ideal processor to.
* @param thread Handle of the thread.
*/
Result svcGetThreadIdealProcessor(s32* processorid, Handle thread);
/**
* Sets a thread's ideal processor.
* @param thread Handle of the thread.
* @param processorid ID of the thread's ideal processor.
*/
Result svcSetThreadIdealProcessor(Handle thread, s32 processorid);
/**
@ -402,12 +583,16 @@ Result svcSetThreadIdealProcessor(Handle thread, s32 processorid);
s32 svcGetProcessorID();
/**
* @param out The thread ID of the thread @p handle.
* @brief Gets the ID of a thread.
* @param[out] out Pointer to output the thread ID of the thread @p handle to.
* @param handle Handle of the thread.
*/
Result svcGetThreadId(u32 *out, Handle handle);
/**
* @param out The process ID of the thread @p handle.
* @brief Gets the process ID of a thread.
* @param[out] out Pointer to output the process ID of the thread @p handle to.
* @param handle Handle of the thread.
* @sa svcOpenProcess
*/
Result svcGetProcessIdOfThread(u32 *out, Handle handle);
@ -424,21 +609,74 @@ Result svcGetThreadInfo(s64* out, Handle thread, ThreadInfoType type);
///@name Synchronization
///@{
/**
* @brief Creates a mutex.
* @param[out] mutex Pointer to output the handle of the created mutex to.
* @param initially_locked Whether the mutex should be initially locked.
*/
Result svcCreateMutex(Handle* mutex, bool initially_locked);
/**
* @brief Releases a mutex.
* @param handle Handle of the mutex.
*/
Result svcReleaseMutex(Handle handle);
/**
* @brief Creates a semaphore.
* @param[out] semaphore Pointer to output the handle of the created semaphore to.
* @param initial_count Initial count of the semaphore.
* @param max_count Maximum count of the semaphore.
*/
Result svcCreateSemaphore(Handle* semaphore, s32 initial_count, s32 max_count);
/**
* @brief Releases a semaphore.
* @param[out] count Pointer to output the current count of the semaphore to.
* @param semaphore Handle of the semaphore.
* @param release_count Number to increase the semaphore count by.
*/
Result svcReleaseSemaphore(s32* count, Handle semaphore, s32 release_count);
/**
* @brief Creates an event handle.
* @param[out] event Pointer to output the created event handle to.
* @param reset_type Type of reset the event uses.
*/
Result svcCreateEvent(Handle* event, u8 reset_type);
/**
* @brief Signals an event.
* @param handle Handle of the event to signal.
*/
Result svcSignalEvent(Handle handle);
/**
* @brief Clears an event.
* @param handle Handle of the event to clear.
*/
Result svcClearEvent(Handle handle);
/**
* @brief Waits for synchronization on a handle.
* @param handle Handle to wait on.
* @param nanoseconds Maximum nanoseconds to wait for.
*/
Result svcWaitSynchronization(Handle handle, s64 nanoseconds);
/**
* @brief Waits for synchronization on multiple handles.
* @param[out] out Pointer to output the index of the synchronized handle to.
* @param handles Handles to wait on.
* @param handles_num Number of handles.
* @param wait_all Whether to wait for synchronization on all handles.
* @param nanoseconds Maximum nanoseconds to wait for.
*/
Result svcWaitSynchronizationN(s32* out, Handle* handles, s32 handles_num, bool wait_all, s64 nanoseconds);
/**
* @brief Creates an address arbiter
* @param[out] mutex Pointer to output the handle of the created address arbiter to.
* @sa svcArbitrateAddress
*/
Result svcCreateAddressArbiter(Handle *arbiter);
@ -462,40 +700,151 @@ Result svcCreateAddressArbiter(Handle *arbiter);
*/
Result svcArbitrateAddress(Handle arbiter, u32 addr, ArbitrationType type, s32 value, s64 nanoseconds);
/**
* @brief Sends a synchronized request to a session handle.
* @param session Handle of the session.
*/
Result svcSendSyncRequest(Handle session);
/**
* @brief Accepts a session.
* @param[out] session Pointer to output the created session handle to.
* @param port Handle of the port to accept a session from.
*/
Result svcAcceptSession(Handle* session, Handle port);
/**
* @brief Replies to and receives a new request.
* @param index Pointer to the index of the request.
* @param handles Session handles to receive requests from.
* @param handleCount Number of handles.
* @param replyTarget Handle of the session to reply to.
*/
Result svcReplyAndReceive(s32* index, Handle* handles, s32 handleCount, Handle replyTarget);
///@}
///@name Time
///@{
/**
* @brief Creates a timer.
* @param[out] timer Pointer to output the handle of the created timer to.
* @param reset_type Type of reset to perform on the timer.
*/
Result svcCreateTimer(Handle* timer, u8 reset_type);
/**
* @brief Sets a timer.
* @param timer Handle of the timer to set.
* @param initial Initial value of the timer.
* @param interval Interval of the timer.
*/
Result svcSetTimer(Handle timer, s64 initial, s64 interval);
/**
* @brief Cancels a timer.
* @param timer Handle of the timer to cancel.
*/
Result svcCancelTimer(Handle timer);
/**
* @brief Clears a timer.
* @param timer Handle of the timer to clear.
*/
Result svcClearTimer(Handle timer);
/**
* @brief Gets the current system tick.
* @return The current system tick.
*/
u64 svcGetSystemTick();
///@}
///@name System
///@{
/**
* @brief Closes a handle.
* @param handle Handle to close.
*/
Result svcCloseHandle(Handle handle);
/**
* @brief Duplicates a handle.
* @param[out] out Pointer to output the duplicated handle to.
* @param original Handle to duplicate.
*/
Result svcDuplicateHandle(Handle* out, Handle original);
/**
* @brief Gets the system info.
* @param[out] out Pointer to output the system info to.
* @param type Type of system info to retreive.
* @param param Parameter clarifying the system info type.
*/
Result svcGetSystemInfo(s64* out, u32 type, s32 param);
/**
* @brief Sets the current kernel state.
* @param type Type of state to set.
* @param param0 First parameter of the state.
* @param param1 Second parameter of the state.
* @param param2 Third parameter of the state.
*/
Result svcKernelSetState(u32 type, u32 param0, u32 param1, u32 param2);
///@}
///@name Debugging
///@{
/**
* @brief Breaks execution.
* @param breakReason Reason for breaking.
*/
void svcBreak(UserBreakType breakReason);
/**
* @brief Outputs a debug string.
* @param str String to output.
* @param length Length of the string to output.
*/
Result svcOutputDebugString(const char* str, int length);
/**
* @brief Creates a debug handle for an active process.
* @param[out] debug Pointer to output the created debug handle to.
* @param processId ID of the process to debug.
*/
Result svcDebugActiveProcess(Handle* debug, u32 processId);
/**
* @brief Breaks a debugged process.
* @param debug Debug handle of the process.
*/
Result svcBreakDebugProcess(Handle debug);
/**
* @brief Terminates a debugged process.
* @param debug Debug handle of the process.
*/
Result svcTerminateDebugProcess(Handle debug);
/**
* @brief Gets the current debug event of a debugged process.
* @param[out] info Pointer to output the debug event information to.
* @param debug Debug handle of the process.
*/
Result svcGetProcessDebugEvent(DebugEventInfo* info, Handle debug);
/**
* @brief Continues the current debug event of a debugged process.
* @param debug Debug handle of the process.
* @param flags Flags to continue with.
*/
Result svcContinueDebugEvent(Handle debug, u32 flags);
///@}
/**
* @brief Executes a function in kernel mode.
* @param callback Function to execute.
*/
Result svcBackdoor(s32 (*callback)(void));

52
libctru/include/3ds/synchronization.h
View File

@ -1,19 +1,31 @@
/**
* @file synchronization.h
* @brief Provides synchronization locks.
*/
#pragma once
/// A light lock.
typedef s32 LightLock;
/// A recursive lock.
typedef struct
{
LightLock lock;
u32 thread_tag;
u32 counter;
LightLock lock; ///< Inner light lock.
u32 thread_tag; ///< Tag of the thread that currently has the lock.
u32 counter; ///< Lock count.
} RecursiveLock;
/// Performs a clrex operation.
static inline void __clrex(void)
{
__asm__ __volatile__("clrex");
}
/**
* @brief Performs a ldrex operation.
* @param addr Address to perform the operation on.
* @return The resulting value.
*/
static inline s32 __ldrex(s32* addr)
{
s32 val;
@ -21,6 +33,12 @@ static inline s32 __ldrex(s32* addr)
return val;
}
/**
* @brief Performs a strex operation.
* @param addr Address to perform the operation on.
* @param val Value to store.
* @return Whether the operation was successful.
*/
static inline bool __strex(s32* addr, s32 val)
{
bool res;
@ -28,10 +46,38 @@ static inline bool __strex(s32* addr, s32 val)
return res;
}
/**
* @brief Initializes a light lock.
* @param lock Pointer to the lock.
*/
void LightLock_Init(LightLock* lock);
/**
* @brief Locks a light lock.
* @param lock Pointer to the lock.
*/
void LightLock_Lock(LightLock* lock);
/**
* @brief Unlocks a light lock.
* @param lock Pointer to the lock.
*/
void LightLock_Unlock(LightLock* lock);
/**
* @brief Initializes a recursive lock.
* @param lock Pointer to the lock.
*/
void RecursiveLock_Init(RecursiveLock* lock);
/**
* @brief Locks a recursive lock.
* @param lock Pointer to the lock.
*/
void RecursiveLock_Lock(RecursiveLock* lock);
/**
* @brief Unlocks a recursive lock.
* @param lock Pointer to the lock.
*/
void RecursiveLock_Unlock(RecursiveLock* lock);

59
libctru/include/3ds/types.h
View File

@ -1,54 +1,57 @@
/*
types.h _ Various system types.
/**
* @file types.h
* @brief Various system types.
*/
#pragma once
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
/// The maximum value of a u64.
#define U64_MAX UINT64_MAX
/// Possible media types.
typedef enum
{
mediatype_NAND,
mediatype_SDMC,
mediatype_GAMECARD,
mediatype_NAND, ///< NAND
mediatype_SDMC, ///< SDMC
mediatype_GAMECARD, ///< Game card
} mediatypes_enum;
typedef uint8_t u8;
typedef uint16_t u16;
typedef uint32_t u32;
typedef uint64_t u64;
typedef uint8_t u8; ///< 8-bit unsigned integer
typedef uint16_t u16; ///< 16-bit unsigned integer
typedef uint32_t u32; ///< 32-bit unsigned integer
typedef uint64_t u64; ///< 64-bit unsigned integer
typedef int8_t s8;
typedef int16_t s16;
typedef int32_t s32;
typedef int64_t s64;
typedef int8_t s8; ///< 8-bit signed integer
typedef int16_t s16; ///< 16-bit signed integer
typedef int32_t s32; ///< 32-bit signed integer
typedef int64_t s64; ///< 64-bit signed integer
typedef volatile u8 vu8;
typedef volatile u16 vu16;
typedef volatile u32 vu32;
typedef volatile u64 vu64;
typedef volatile u8 vu8; ///< 8-bit volatile unsigned integer.
typedef volatile u16 vu16; ///< 16-bit volatile unsigned integer.
typedef volatile u32 vu32; ///< 32-bit volatile unsigned integer.
typedef volatile u64 vu64; ///< 64-bit volatile unsigned integer.
typedef volatile s8 vs8;
typedef volatile s16 vs16;
typedef volatile s32 vs32;
typedef volatile s64 vs64;
typedef volatile s8 vs8; ///< 8-bit volatile signed integer.
typedef volatile s16 vs16; ///< 16-bit volatile signed integer.
typedef volatile s32 vs32; ///< 32-bit volatile signed integer.
typedef volatile s64 vs64; ///< 64-bit volatile signed integer.
typedef u32 Handle;
typedef s32 Result;
typedef void (*ThreadFunc)(void *);
typedef u32 Handle; ///< Resource handle.
typedef s32 Result; ///< Function result.
typedef void (*ThreadFunc)(void *); ///< Thread entrypoint function.
/// Creates a bitmask from a bit number.
#define BIT(n) (1U<<(n))
//! aligns a struct (and other types?) to m, making sure that the size of the struct is a multiple of m.
/// aligns a struct (and other types?) to m, making sure that the size of the struct is a multiple of m.
#define ALIGN(m) __attribute__((aligned(m)))
//! packs a struct (and other types?) so it won't include padding bytes.
/// packs a struct (and other types?) so it won't include padding bytes.
#define PACKED __attribute__((packed))
//! flags a function as deprecated.
/// flags a function as deprecated.
#ifndef LIBCTRU_NO_DEPRECATION
#define DEPRECATED __attribute__ ((deprecated))
#else

89
libctru/include/3ds/util/rbtree.h
View File

@ -1,74 +1,145 @@
/**
* @file rbtree.h
* @brief Red-black trees.
*/
#pragma once
#include <stdint.h>
#include <stddef.h>
/// brief Retreives an rbtree item.
#define rbtree_item(ptr, type, member) \
((type*)(((char*)ptr) - offsetof(type, member)))
typedef struct rbtree rbtree_t;
typedef struct rbtree_node rbtree_node_t;
typedef struct rbtree rbtree_t; ///< rbtree type.
typedef struct rbtree_node rbtree_node_t; ///< rbtree node type.
typedef void (*rbtree_node_destructor_t)(rbtree_node_t *Node);
typedef void (*rbtree_node_destructor_t)(rbtree_node_t *Node); ///< rbtree node destructor.
typedef int (*rbtree_node_comparator_t)(const rbtree_node_t *lhs,
const rbtree_node_t *rhs);
const rbtree_node_t *rhs); ///< rbtree node comparator.
/// An rbtree node.
struct rbtree_node
{
uintptr_t parent_color;
rbtree_node_t *child[2];
uintptr_t parent_color; ///< Parent color.
rbtree_node_t *child[2]; ///< Node children.
};
/// An rbtree.
struct rbtree
{
rbtree_node_t *root;
rbtree_node_comparator_t comparator;
size_t size;
rbtree_node_t *root; ///< Root node.
rbtree_node_comparator_t comparator; ///< Node comparator.
size_t size; ///< Size.
};
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Initializes an rbtree.
* @param tree Pointer to the tree.
* @param comparator Comparator to use.
*/
void
rbtree_init(rbtree_t *tree,
rbtree_node_comparator_t comparator);
/**
* @brief Gets whether an rbtree is empty
* @param tree Pointer to the tree.
* @return A non-zero value if the tree is not empty.
*/
int
rbtree_empty(const rbtree_t *tree);
/**
* @brief Gets the size of an rbtree.
* @param tree Pointer to the tree.
*/
size_t
rbtree_size(const rbtree_t *tree);
/**
* @brief Inserts a node into an rbtree.
* @param tree Pointer to the tree.
* @param node Pointer to the node.
* @return The inserted node.
*/
__attribute__((warn_unused_result))
rbtree_node_t*
rbtree_insert(rbtree_t *tree,
rbtree_node_t *node);
/**
* @brief Inserts multiple nodes into an rbtree.
* @param tree Pointer to the tree.
* @param node Pointer to the nodes.
*/
void
rbtree_insert_multi(rbtree_t *tree,
rbtree_node_t *node);
/**
* @brief Finds a node within an rbtree.
* @param tree Pointer to the tree.
* @param node Pointer to the node.
* @return The located node.
*/
rbtree_node_t*
rbtree_find(const rbtree_t *tree,
const rbtree_node_t *node);
/**
* @brief Gets the minimum node of an rbtree.
* @param tree Pointer to the tree.
* @return The minimum node.
*/
rbtree_node_t*
rbtree_min(const rbtree_t *tree);
/**
* @brief Gets the maximum node of an rbtree.
* @param tree Pointer to the tree.
* @return The maximum node.
*/
rbtree_node_t*
rbtree_max(const rbtree_t *tree);
/**
* @brief Gets the next node from an rbtree node.
* @param node Pointer to the node.
* @return The next node.
*/
rbtree_node_t*
rbtree_node_next(const rbtree_node_t *node);
/**
* @brief Gets the previous node from an rbtree node.
* @param node Pointer to the node.
* @return The previous node.
*/
rbtree_node_t*
rbtree_node_prev(const rbtree_node_t *node);
/**
* @brief Removes a node from an rbtree.
* @param tree Pointer to the tree.
* @param node Pointer to the node.
* @param destructor Destructor to use when removing the node.
* @return The removed node.
*/
rbtree_node_t*
rbtree_remove(rbtree_t *tree,
rbtree_node_t *node,
rbtree_node_destructor_t destructor);
/**
* @brief Clears an rbtree.
* @param tree Pointer to the tree.
* @param destructor Destructor to use when clearing the tree's nodes.
*/
void
rbtree_clear(rbtree_t *tree,
rbtree_node_destructor_t destructor);

24
libctru/include/3ds/util/utf.h
View File

@ -1,9 +1,13 @@
/**
* @file utf.h
* @brief UTF conversion functions.
*/
#pragma once
#include <stdint.h>
#include <sys/types.h>
/*! Convert a UTF-8 sequence into a UTF-32 codepoint
/** Convert a UTF-8 sequence into a UTF-32 codepoint
*
* @param[out] out Output codepoint
* @param[in] in Input sequence
@ -13,7 +17,7 @@
*/
ssize_t decode_utf8 (uint32_t *out, const uint8_t *in);
/*! Convert a UTF-16 sequence into a UTF-32 codepoint
/** Convert a UTF-16 sequence into a UTF-32 codepoint
*
* @param[out] out Output codepoint
* @param[in] in Input sequence
@ -23,7 +27,7 @@ ssize_t decode_utf8 (uint32_t *out, const uint8_t *in);
*/
ssize_t decode_utf16(uint32_t *out, const uint16_t *in);
/*! Convert a UTF-32 codepoint into a UTF-8 sequence
/** Convert a UTF-32 codepoint into a UTF-8 sequence
*
* @param[out] out Output sequence
* @param[in] in Input codepoint
@ -35,7 +39,7 @@ ssize_t decode_utf16(uint32_t *out, const uint16_t *in);
*/
ssize_t encode_utf8 (uint8_t *out, uint32_t in);
/*! Convert a UTF-32 codepoint into a UTF-16 sequence
/** Convert a UTF-32 codepoint into a UTF-16 sequence
*
* @param[out] out Output sequence
* @param[in] in Input codepoint
@ -47,7 +51,7 @@ ssize_t encode_utf8 (uint8_t *out, uint32_t in);
*/
ssize_t encode_utf16(uint16_t *out, uint32_t in);
/*! Convert a UTF-8 sequence into a UTF-16 sequence
/** Convert a UTF-8 sequence into a UTF-16 sequence
*
* @param[out] out Output sequence
* @param[in] in Input sequence
@ -57,7 +61,7 @@ ssize_t encode_utf16(uint16_t *out, uint32_t in);
*/
size_t utf8_to_utf16(uint16_t *out, const uint8_t *in, size_t len);
/*! Convert a UTF-8 sequence into a UTF-32 sequence
/** Convert a UTF-8 sequence into a UTF-32 sequence
*
* @param[out] out Output sequence
* @param[in] in Input sequence
@ -67,7 +71,7 @@ size_t utf8_to_utf16(uint16_t *out, const uint8_t *in, size_t len);
*/
size_t utf8_to_utf32(uint32_t *out, const uint8_t *in, size_t len);
/*! Convert a UTF-16 sequence into a UTF-8 sequence
/** Convert a UTF-16 sequence into a UTF-8 sequence
*
* @param[out] out Output sequence
* @param[in] in Input sequence
@ -77,7 +81,7 @@ size_t utf8_to_utf32(uint32_t *out, const uint8_t *in, size_t len);
*/
size_t utf16_to_utf8(uint8_t *out, const uint16_t *in, size_t len);
/*! Convert a UTF-16 sequence into a UTF-32 sequence
/** Convert a UTF-16 sequence into a UTF-32 sequence
*
* @param[out] out Output sequence
* @param[in] in Input sequence
@ -87,7 +91,7 @@ size_t utf16_to_utf8(uint8_t *out, const uint16_t *in, size_t len);
*/
size_t utf16_to_utf32(uint32_t *out, const uint16_t *in, size_t len);
/*! Convert a UTF-32 sequence into a UTF-8 sequence
/** Convert a UTF-32 sequence into a UTF-8 sequence
*
* @param[out] out Output sequence
* @param[in] in Input sequence
@ -97,7 +101,7 @@ size_t utf16_to_utf32(uint32_t *out, const uint16_t *in, size_t len);
*/
size_t utf32_to_utf8(uint8_t *out, const uint32_t *in, size_t len);
/*! Convert a UTF-32 sequence into a UTF-16 sequence
/** Convert a UTF-32 sequence into a UTF-16 sequence
*
* @param[out] out Output sequence
* @param[in] in Input sequence

2
libctru/include/3ds/vram.h
View File

@ -4,8 +4,6 @@
*/
#pragma once
// Functions for allocating/deallocating VRAM
/**
* @brief Allocates a 0x80-byte aligned buffer.
* @param size Size of the buffer to allocate.