From 2075a293c30b52b0a4913c80e422cb09a07019cf Mon Sep 17 00:00:00 2001 From: chaoskagami Date: Wed, 17 Aug 2016 20:38:39 -0400 Subject: [PATCH] Document shit better --- include/arm11.h | 24 +++++- include/firm/decryptor.h | 27 ++++--- include/firm/firm.h | 35 ++++++-- include/firm/headers.h | 8 +- include/input.h | 5 ++ include/interp.h | 17 ++++ include/interrupt.h | 2 + include/menu-backend.h | 11 +++ include/option.h | 153 +++++++++++++++-------------------- include/patch_format.h | 144 ++++++++++++++++----------------- include/patcher.h | 9 +++ include/std/abort.h | 9 +++ include/std/allocator.h | 18 +++-- include/std/draw.h | 168 +++++++++++++++++++++++++++++---------- source/std/draw.c | 2 +- 15 files changed, 398 insertions(+), 234 deletions(-) diff --git a/include/arm11.h b/include/arm11.h index f7c2a21..822eeb4 100644 --- a/include/arm11.h +++ b/include/arm11.h @@ -43,12 +43,34 @@ #define ARM11_STUB_ADDRESS (0x25000000 - 0x30) //It's currently only 0x28 bytes large. We're putting 0x30 just to be sure here #define WAIT_FOR_ARM9() *arm11Entry = 0; while(!*arm11Entry); ((void (*)())*arm11Entry)(); -// Inits the screen if needed. +/* Initializes the screen and sets the display mode. + * + * \param mode Screen mode to initialize in, one of RGBA8, BGR8, RGB565_OES, RGB5_A1_OES, or RGBA4_OES + */ void screen_mode(uint32_t mode); + +/* Invokes a bare ARM11 function. For usage, see arm11.c. + * + * \param func Function to call. + */ void invokeArm11Function(void (*func)()); + +/* Deinitializes the screens. + */ void deinitScreens(void); + +/* Sets the brightness. + * + * \param brightnessIndex The brightness level, in the range 0-4. + */ void updateBrightness(uint32_t brightnessIndex); + +/* Clears screens to black via GPU fill. + */ void clearScreens(void); + +/* Copies the ARM11 stub. Called automatically by invokeArm11Function if needed. + */ void installArm11Stub(void); #endif diff --git a/include/firm/decryptor.h b/include/firm/decryptor.h index 92a1739..293f5f7 100644 --- a/include/firm/decryptor.h +++ b/include/firm/decryptor.h @@ -1,23 +1,26 @@ #ifndef __DECRYPTOR_H #define __DECRYPTOR_H +/* Sha256Sums data quickly, outputting result to a buffer. + * + * \param sum Buffer to output sha256 to. + * \param data Data to calculate sha256 over + * \param size Size, in bytes, of data to sha256 + */ void sha256sum(void* sum, void* data, uint32_t size); typedef enum { - NCCHTYPE_EXHEADER = 1, - NCCHTYPE_EXEFS = 2, - NCCHTYPE_ROMFS = 3, + NCCHTYPE_EXHEADER = 1, ///< ExHeader CTR + NCCHTYPE_EXEFS = 2, ///< ExeFs CTR + NCCHTYPE_ROMFS = 3, ///< RomFs CTR } ctr_ncchtypes; +/* Gets the initial counter for CTR crypto. + * + * \param ncch NCCH in memory to get CTR for + * \param ctr Output buffer of 16 bytes to output ctr to. + * \param type type of CTR value to get from NCCH, one of ctr_ncchtypes + */ void ncch_getctr(const ncch_h *ncch, uint8_t *ctr, uint8_t type); -/* Crypto adaptation from b1l1s -> ctr9 tl;dr: - - aes_setiv -> set_ctr - aes_setkey -> setup_aeskey{,X,Y} - aes_use_keyslot -> use_aeskey - aes_advctr -> add_ctr - aes -> wrapper function thing -*/ - #endif diff --git a/include/firm/firm.h b/include/firm/firm.h index a29d703..d657b40 100644 --- a/include/firm/firm.h +++ b/include/firm/firm.h @@ -3,18 +3,22 @@ #include +/* Console type for FIRM image + */ enum consoles { - console_o3ds, - console_n3ds + console_o3ds, ///< O3DS + console_n3ds ///< N3DS }; +/* Storage struct for version information of FIRMs + */ struct firm_signature { - uint8_t sig[0x10]; - unsigned int version; - char version_string[16]; - enum consoles console; + uint8_t sig[0x10]; ///< First 0x10 bytes of first section hash (used for identification) + unsigned int version; ///< CDN/contents version of FIRM + char version_string[16]; ///< Human readable version number + enum consoles console; ///< Console type }; extern firm_h *firm_loc; @@ -35,15 +39,32 @@ extern struct firm_signature *current_agb_firm; extern firm_section_h agb_firm_proc9; extern exefs_h *agb_firm_p9_exefs; +/* Returns a struct describing the version of a decrypted FIRM + */ struct firm_signature *get_firm_info(firm_h *firm); + +/* Initializes 0x11 KeyY + */ void slot0x11key96_init(); -void extract_firm1(); +/* Extracts 0x05 KeyY from FIRM0 on NAND + */ void extract_slot0x05keyY(); + +/* Extracts 0x3D KeyY from FIRM0 on NAND + */ void extract_slot0x3DkeyY(); +/* Loads FIRM files + */ int load_firms(); + +/* Boots native FIRM - do not call directly. + */ void boot_firm(); + +/* Boots the CFW, generating caches and applying patches as-needed + */ void boot_cfw(); #endif diff --git a/include/firm/headers.h b/include/firm/headers.h index 27fcd80..11c05d0 100644 --- a/include/firm/headers.h +++ b/include/firm/headers.h @@ -11,10 +11,10 @@ #define MEDIA_UNITS 0x200 -#define NCCH_MAGIC (0x4843434E) -#define NCSD_MAGIC (0x4453434E) -#define FIRM_MAGIC (0x4D524946) -#define ARM9BIN_MAGIC (0x47704770) +#define NCCH_MAGIC (0x4843434E) ///< Lit. "NCCH" +#define NCSD_MAGIC (0x4453434E) ///< Lit. "NCSD" +#define FIRM_MAGIC (0x4D524946) ///< Lit. "FIRM" +#define ARM9BIN_MAGIC (0x47704770) #define LGY_ARM9BIN_MAGIC (0xB0862000) typedef struct firm_section_h diff --git a/include/input.h b/include/input.h index c09c217..3f94a17 100644 --- a/include/input.h +++ b/include/input.h @@ -3,6 +3,11 @@ #include +/* Waits for a single key to be pressed and released, returning the key when done. + * + * \param sleep Unused. Previously would add some delay to each read for dpads with issues. + * \return The key pressed and released. + */ uint32_t wait_key(_UNUSED int sleep); #endif diff --git a/include/interp.h b/include/interp.h index 26c2236..eb6ebf3 100644 --- a/include/interp.h +++ b/include/interp.h @@ -1,7 +1,24 @@ #ifndef __INTERP_H #define __INTERP_H +/* Loads and prepares/executes/caches a bytecode patch. + * + * \param filename Filename of patch to load and parse. + * \param build_cache If zero, execute the file. Otherwise, cache the file for later. + * \return Zero on success. + */ + int execb(char *filename, int build_cache); + +/* Low level function to actually execute the bytecode. Do not call directly. + * + * \param bytecode Bytecode data in memory. + * \param len Length of bytecode in bytes. + * \param stack Stack pointer for VM (grows up) + * \param stack_size Size of the stack space (in bytes) + * \param ver Version of Exefs being patched. Only used in loader (subject to change) + * \param debug Whether to output debug information from each step of the VM to stderr + */ int exec_bytecode(uint8_t *bytecode, uint32_t len, uint8_t* stack, uint32_t stack_size, uint16_t ver, int debug); #endif diff --git a/include/interrupt.h b/include/interrupt.h index 9c48a72..8a25f56 100644 --- a/include/interrupt.h +++ b/include/interrupt.h @@ -1,6 +1,8 @@ #ifndef __INTERRUPT_H #define __INTERRUPT_H +/* Install interrupt handlers via libctr9. + */ void install_interrupts(); #endif diff --git a/include/menu-backend.h b/include/menu-backend.h index 3d16475..16aa720 100644 --- a/include/menu-backend.h +++ b/include/menu-backend.h @@ -1,7 +1,18 @@ #ifndef __MENU_BACKEND_H__ #define __MENU_BACKEND_H__ +/* Set the accent foreground color for a screen. + * + * \param screen Which screen it should be set for + * \param fg Foreground color to use for accents. + */ void accent_color(void* screen, int fg); + +/* Display a menu structure. + * + * \param options Menu structure to display + * \param toggles Array of bytes to have values changed according to options + */ int show_menu(struct options_s *options, uint8_t *toggles); #endif diff --git a/include/option.h b/include/option.h index 30d86bb..667e780 100644 --- a/include/option.h +++ b/include/option.h @@ -1,29 +1,33 @@ #ifndef __CONFIG_H #define __CONFIG_H -#define config_version 1 +#define config_version 1 ///< Static version of the config. Updated when the config has changed in an + ///< incompatible way. -#define CONFIG_MAGIC "OVAN" +#define CONFIG_MAGIC "OVAN" ///< Magic to identify config files. -// Structure of config file +/* Structure of config file + */ struct config_file { char magic[4]; // "OVAN" for shits and giggles again. - uint32_t config_ver; // Config file version. + uint32_t config_ver; ///< Config file version. - uint8_t options[256]; // Options in the menu - deliberately large to avoid - // config version bumps. + uint8_t options[256]; ///< Options in the menu - deliberately large to avoid + ///< config version bumps. - uint64_t patch_ids[256]; // What patches are enabled by UUID. 256 is an - // arbitrary limit - contact me if you hit it. + uint64_t patch_ids[256]; ///< What patches are enabled by UUID. 256 is an + ///< arbitrary limit - contact me if you hit it. } __attribute__((packed)); +/* State of a patch file + */ struct patch_state { - char filename[256]; + char filename[256]; ///< Patch filename. - uint8_t state; + uint8_t state; ///< Status of patch. } __attribute__((packed)); #ifdef LOADER @@ -32,15 +36,18 @@ extern struct config_file config; extern struct config_file *config; #endif +/* Menu entry type. Determines how the menu is displayed and which (if any) options + * can be changed. + */ enum type { - boolean_val = 0, // Toggle - ranged_val = 1, // N1 - N2, left and right to pick. - mask_val = 2, // Bitmask allowed values. - not_option = 3, // Skip over this. - call_fun = 4, // Call a function. Treat (a) as (void)(*)(void). - boolean_val_n3ds = 5, // Toggle, but only show on n3DS - break_menu = 6 + boolean_val = 0, ///< Toggleable boolean + ranged_val = 1, ///< N1 - N2, left and right to pick. + mask_val = 2, ///< Bitmask allowed values. + not_option = 3, ///< Skip over this. + call_fun = 4, ///< Call a function. Treat (a) as (void)(*)(void). + boolean_val_n3ds = 5, ///< Toggle, but only show on n3DS + break_menu = 6 ///< Exit the menu (same as B) }; typedef void (*func_call_t)(uint32_t data); @@ -52,101 +59,65 @@ struct range_str struct options_s { - int64_t index; - char name[64]; - char desc[256]; - enum type allowed; - uint32_t a, b; - uint8_t indent; + int64_t index; ///< Option index. Used for displaying values. + char name[64]; ///< Name of patch to display in menus. + char desc[256]; ///< Description of option, shown when pressing select + enum type allowed; ///< Misnomer, FIXME. Type of menu entry. See enum type. + uint32_t a, b; ///< Should be union, FIXME. Data values used for menu entry. + uint8_t indent; ///< Indentation/ownership level of menu. } __attribute__((packed)); -// Use builtin loader module replacer. -#define OPTION_LOADER 2 +#define OPTION_LOADER 2 ///< Use builtin loader module replacer. -// Inject svc calls (including backdoor for 11) -#define OPTION_SVCS 3 +#define OPTION_SVCS 3 ///< Inject svcBackdoor (FIXME, misnomer) -// Use builtin ARM9 thread injector. (NYI) -#define OPTION_ARM9THREAD 4 +#define OPTION_ARM9THREAD 4 ///< Use builtin ARM9 thread injector. (NYI, in the future perhaps) -// Skip menu unless L is held. -#define OPTION_AUTOBOOT 5 +#define OPTION_AUTOBOOT 5 ///< Skip menu unless R is held. -// Don't print debug information. -#define OPTION_SILENCE 6 +#define OPTION_SILENCE 6 ///< Don't print debug information. -// Pause for A key on each step. -#define OPTION_TRACE 7 +#define OPTION_TRACE 7 ///< Pause for A key on each step. -// Dim background for readability. -#define OPTION_DIM_MODE 8 +#define OPTION_DIM_MODE 8 ///< Dim background for readability. -// Accent color in menus. -#define OPTION_ACCENT_COLOR 9 +#define OPTION_ACCENT_COLOR 9 ///< Accent color in menus. -// Screeninit brightness -#define OPTION_BRIGHTNESS 10 +#define OPTION_BRIGHTNESS 10 ///< Screeninit brightness -// Enable L2 cache. -#define OPTION_LOADER_CPU_L2 11 +#define OPTION_LOADER_CPU_L2 11 ///< Enable L2 cache. -// Enable 800Mhz mode. -#define OPTION_LOADER_CPU_800MHZ 12 +#define OPTION_LOADER_CPU_800MHZ 12 ///< Enable 800Mhz mode. -// Enable language emulation. -#define OPTION_LOADER_LANGEMU 13 +#define OPTION_LOADER_LANGEMU 13 ///< Enable language emulation. -// Ignore patch UUID dependencies. Not recommended. -#define IGNORE_PATCH_DEPS 14 +#define IGNORE_PATCH_DEPS 14 ///< Ignore patch UUID dependencies. Not recommended. (NYI) -// Allow enabling patches which are marked as 'incompatible'. Chances are there's a reason. -#define IGNORE_BROKEN_SHIT 15 +#define IGNORE_BROKEN_SHIT 15 ///< Allow enabling patches which are marked as 'incompatible'. + ///< Chances are there's a reason. (NYI) -// Whether to use an EmuNAND -#define OPTION_EMUNAND 16 +#define OPTION_EMUNAND 16 ///< Whether to use an EmuNAND -// Which EmuNAND to use (currently only allows 10 total, but eh, I can change that if anyone truly needs it) -#define OPTION_EMUNAND_INDEX 17 +#define OPTION_EMUNAND_INDEX 17 ///< Which EmuNAND to use (currently only allows 10 total due to arbitary limit) -// Dump titles' code sections as they're loaded by the loader module. -#define OPTION_LOADER_DUMPCODE 18 +#define OPTION_LOADER_DUMPCODE 18 ///< Dump titles' code sections as they're loaded by the loader module. -// Hook firmlaunches. -#define OPTION_REBOOT 19 +#define OPTION_REBOOT 19 ///< Hook firmlaunches. -// Dump *all* code, from system applications, modules, etc. You'll be sitting around for about five minutes. -#define OPTION_LOADER_DUMPCODE_ALL 20 +#define OPTION_LOADER_DUMPCODE_ALL 20 ///< Dump *all* code, from system applications, modules, etc. You'll + ///< be sitting around for about five minutes. -// Load *all* code sections. This is intended for big patches that are currently not implementable and quick testing. -// (e.g. SaltySD) -#define OPTION_LOADER_LOADCODE 21 +#define OPTION_LOADER_LOADCODE 21 ///< Load *all* code sections. This is intended for big patches that + ///< are currently not implementable and quick testing (e.g. SaltySD) -// Silenced autoboot will not init the screen. -#define OPTION_SILENT_NOSCREEN 22 +#define OPTION_SILENT_NOSCREEN 22 ///< Silenced autoboot will not init the screen. -// Calculate EmuNAND at the back of the disk, rather than the front. -// There's many good reasons for this to be supported: -// - Resizable FAT partition -// - Shrink to add EmuNAND -// = Grow to delete EmuNAND -// - Doesn't require copying fucktons of data to manage multiemunand -// This isn't supported by ANY tools like D9 at the moment -// (Though I hope they'll consider it - -// there's only benefits to users with multiple EmuNANDs) +#define OPTION_SAVE_LOGS 253 ///< Save log files during boot and from loader. Slows down boot a bit. -// Disable Reverse. We're going to implement an actual filesystem. -// #define OPTION_EMUNAND_REVERSE 22 +#define OPTION_OVERLY_VERBOSE 254 ///< Output so much debugging info, it'd make your head spin. -// Save log files during boot and from loader. -// This will slow things down a bit. -#define OPTION_SAVE_LOGS 253 - -// Output so much debugging info, it'd make your head spin. -#define OPTION_OVERLY_VERBOSE 254 - -// This is for internal use only. It's set when any patches -// change and causes caches to be regenerated. -#define OPTION_RECONFIGURED 255 +#define OPTION_RECONFIGURED 255 ///< This is for internal use only. It's set when any changes + ///< require caches to be regenerated. //#define HEADER_COLOR 12 // Color of header text. //#define BG_COLOR 13 // Color of background. @@ -154,9 +125,17 @@ struct options_s //#define ARROW_COLOR 15 // Color of Arrow. #ifndef LOADER + +/* Loads the config file off SD from the configured location. + */ void load_config(); + +/* Saves the config file to SD at the configured location. + */ void save_config(); + #endif + /* [CORBENIK] version=1 diff --git a/include/patch_format.h b/include/patch_format.h index 4b39b78..28668f9 100644 --- a/include/patch_format.h +++ b/include/patch_format.h @@ -3,113 +3,109 @@ #include -// The following are titleids which are handled specially for one reason or -// another. +// The following are titleids which are handled specially for one reason or another. // We use titleIDs to be generic; it ensures that patches can share the same -// format -// regardless of whether they're intended for loader or not. Simple logistics. -#define NATIVE_FIRM_TITLEID 0x0004013800000002llu // NATIVE_FIRM -#define NATIVE_FIRM_N3DS_TITLEID 0x0004013820000002llu // NATIVE_FIRM, n3ds +// format regardless of whether they're intended for loader or not. -#define TWL_FIRM_TITLEID 0x0004013000000102llu // TWL_FIRM (DSi Firmware) -#define TWL_FIRM_N3DS_TITLEID 0x0004013020000102llu // TWL_FIRM, n3ds (DSi Firmware) +#define NATIVE_FIRM_TITLEID 0x0004013800000002llu ///< NATIVE_FIRM +#define NATIVE_FIRM_N3DS_TITLEID 0x0004013820000002llu ///< NATIVE_FIRM, n3ds -#define AGB_FIRM_TITLEID 0x0004013000000202llu // AGB_FIRM (GBA firmware) -#define AGB_FIRM_N3DS_TITLEID 0x0004013020000202llu // AGB_FIRM (GBA firmware) +#define TWL_FIRM_TITLEID 0x0004013000000102llu ///< TWL_FIRM (DSi Firmware) +#define TWL_FIRM_N3DS_TITLEID 0x0004013020000102llu ///< TWL_FIRM, n3ds (DSi Firmware) -#define LOADER_TITLEID 0x0004013000001302llu // Loader is handled specially. +#define AGB_FIRM_TITLEID 0x0004013000000202llu ///< AGB_FIRM (GBA firmware) +#define AGB_FIRM_N3DS_TITLEID 0x0004013020000202llu ///< AGB_FIRM (GBA firmware) -#define PATCH_MANDATORY (1 << 0) // Patch must be applied for successful boot. -#define PATCH_FAIL_ABORT (1 << 1) // If patch fails to apply, abort and show an error. -#define PATCH_DISABLED (1 << 2) // Do not allow changing this patch's status. With PATCH_MANDATORY, - // this prevents disabling it. +#define LOADER_TITLEID 0x0004013000001302llu // Loader is handled specially. -#define PATH_MODULES LIBDIR "/module" // Sysmodule location -#define PATH_PATCHES SBINDIR // Patch binary folder. +// TODO - We also need to handle patches for internal system modules here, performing lzss decompression (and either recompression, or getting a patch to skip that if needed -#define PATH_BITS LIBEXECDIR // Path to misc bits we need (emunand code, reboot code, etc) +#define PATH_MODULES LIBDIR "/module" ///< Sysmodule location +#define PATH_PATCHES SBINDIR ///< Patch binary folder. -#define PATH_EMUNAND_CODE PATH_BITS "/emunand.bin" // Emunand hook. -#define PATH_SCREENINIT_CODE PATH_BITS "/screeninit.bin" // Screeninit code (ARM11) -#define PATH_BACKDOOR PATH_BITS "/backdoor.bin" // svcBackdoor -#define PATH_REBOOT_HOOK PATH_BITS "/reboot_hook.bin" // Reboot hook -#define PATH_REBOOT_CODE PATH_BITS "/reboot_code.bin" // Reboot entry code +#define PATH_BITS LIBEXECDIR ///< Path to misc bits we need (emunand code, reboot code, etc) -#define PATH_TOP_BG SHAREDIR "/top.bin" -#define PATH_BOTTOM_BG SHAREDIR "/bottom.bin" -#define PATH_TERMFONT SHAREDIR "/termfont.bin" +#define PATH_EMUNAND_CODE PATH_BITS "/emunand.bin" ///< Emunand hook. +#define PATH_SCREENINIT_CODE PATH_BITS "/screeninit.bin" ///< Screeninit code (ARM11) +#define PATH_BACKDOOR PATH_BITS "/backdoor.bin" ///< svcBackdoor +#define PATH_REBOOT_HOOK PATH_BITS "/reboot_hook.bin" ///< Reboot hook +#define PATH_REBOOT_CODE PATH_BITS "/reboot_code.bin" ///< Reboot entry code -#define PATH_CHAINS PREFIX "/boot" +#define PATH_TOP_BG SHAREDIR "/top.bin" ///< Top screen background +#define PATH_BOTTOM_BG SHAREDIR "/bottom.bin" ///< Bottom screen background +#define PATH_TERMFONT SHAREDIR "/termfont.bin" ///< Font data -#define PATH_TEMP LOCALSTATEDIR "/cache" // Files that are transient and used to speed operation -#define PATH_LOADER_CACHE PATH_TEMP "/loader" // Cached patch bytecode for loader. +#define PATH_CHAINS PREFIX "/boot" ///< Chainloader payloads folder. -#define PATH_LOCEMU LOCALEDIR "/emu" // Locale emulation config -#define PATH_FIRMWARES LIBDIR "/firmware" // Firmware folder. +#define PATH_TEMP LOCALSTATEDIR "/cache" ///< Files that are transient and generated to improve speed +#define PATH_LOADER_CACHE PATH_TEMP "/loader" ///< Cached patch bytecode for loader. -#define PATH_CONFIG_DIR SYSCONFDIR // Config file directory. -#define PATH_CONFIG PATH_CONFIG_DIR "/main.conf" // Config file. -#define PATH_CPU_CFG PATH_CONFIG_DIR "/cpu.conf" // CPU settings config +#define PATH_LOCEMU LOCALEDIR "/emu" ///< Locale emulation config +#define PATH_FIRMWARES LIBDIR "/firmware" ///< Firmware folder. -#define PATH_NATIVE_P PATH_TEMP "/p_native" -#define PATH_AGB_P PATH_TEMP "/p_agb" -#define PATH_TWL_P PATH_TEMP "/p_twl" +#define PATH_CONFIG_DIR SYSCONFDIR ///< Config file directory. +#define PATH_CONFIG PATH_CONFIG_DIR "/main.conf" ///< Config file. -#define PATH_KEYS SHAREDIR "/keys" // Keyfiles will be loaded from this dir, and - // additionally the root if not found. +#define PATH_NATIVE_P PATH_TEMP "/p_native" ///< Patched native_firm. +#define PATH_AGB_P PATH_TEMP "/p_agb" ///< Patched agb_firm +#define PATH_TWL_P PATH_TEMP "/p_twl" ///< Patched twl_firm -#define PATH_EXEFS LIBDIR "/exefs" // ExeFS overrides/dumps, named by titleid -#define PATH_EXEFS_TEXT PATH_EXEFS "/text" // Text segment overrides/dumps, named by titleid -#define PATH_EXEFS_RO PATH_EXEFS "/ro" // RO segment overrides/dumps, named by titleid -#define PATH_EXEFS_DATA PATH_EXEFS "/data" // Data segment overrides/dumps, named by titleid +#define PATH_KEYS SHAREDIR "/keys" ///< Keyfiles will be loaded from this dir, and + ///< additionally the root if not found. -#define PATH_NATIVE_F PATH_FIRMWARES "/native" -#define PATH_AGB_F PATH_FIRMWARES "/agb" -#define PATH_TWL_F PATH_FIRMWARES "/twl" +#define PATH_EXEFS LIBDIR "/exefs" ///< ExeFS overrides/dumps, named by titleid +#define PATH_EXEFS_TEXT PATH_EXEFS "/text" ///< Text segment overrides/dumps, named by titleid +#define PATH_EXEFS_RO PATH_EXEFS "/ro" ///< RO segment overrides/dumps, named by titleid +#define PATH_EXEFS_DATA PATH_EXEFS "/data" ///< Data segment overrides/dumps, named by titleid -#define PATH_NATIVE_CETK PATH_KEYS "/native.cetk" -#define PATH_TWL_CETK PATH_KEYS "/twl.cetk" -#define PATH_AGB_CETK PATH_KEYS "/agb.cetk" +#define PATH_NATIVE_F PATH_FIRMWARES "/native" ///< Native FIRM location +#define PATH_AGB_F PATH_FIRMWARES "/agb" ///< AGB FIRM location +#define PATH_TWL_F PATH_FIRMWARES "/twl" ///< TWL FIRM location -#define PATH_NATIVE_FIRMKEY PATH_KEYS "/native.key" -#define PATH_TWL_FIRMKEY PATH_KEYS "/twl.key" -#define PATH_AGB_FIRMKEY PATH_KEYS "/agb.key" +#define PATH_NATIVE_CETK PATH_KEYS "/native.cetk" ///< Native FIRM cetk, used for decryption +#define PATH_TWL_CETK PATH_KEYS "/twl.cetk" ///< TWL FIRM cetk +#define PATH_AGB_CETK PATH_KEYS "/agb.cetk" ///< AGB FIRM cetk -#define PATH_SLOT0X11KEY96 PATH_KEYS "/11Key96.key" +#define PATH_NATIVE_FIRMKEY PATH_KEYS "/native.key" ///< Native FIRM decrypted titlekey +#define PATH_TWL_FIRMKEY PATH_KEYS "/twl.key" ///< TWL FIRM decrypted titlekey +#define PATH_AGB_FIRMKEY PATH_KEYS "/agb.key" ///< AGB FIRM decrypted titlekey -#define PATH_ALT_SLOT0X11KEY96 "/slot0x11key96.bin" // Hey, your perrogative, buddy. I like cleaned up - // paths. +#define PATH_SLOT0X11KEY96 PATH_KEYS "/11Key96.key" ///< 0x11 KeyY (for 9.6 FIRM arm9loader) -#define PATH_LOG LOCALSTATEDIR "/log" +#define PATH_ALT_SLOT0X11KEY96 "/slot0x11key96.bin" ///< Alternate path for 0x11 KeyY -#define PATH_BOOTLOG PATH_LOG "/boot.log" -#define PATH_LOADERLOG PATH_LOG "/loader.log" +#define PATH_LOG LOCALSTATEDIR "/log" ///< Log directory -#define PATCH_FLAG_REQUIRE (1 << 0) // Force enable patch unless 'Unsafe Options' is checked. -#define PATCH_FLAG_DEVMODE (1 << 1) // Require 'Developer Options' to be checked. -#define PATCH_FLAG_NOABORT (1 << 2) // Don't abort on error. +#define PATH_BOOTLOG PATH_LOG "/boot.log" ///< Boot time log +#define PATH_LOADERLOG PATH_LOG "/loader.log" ///< Loader log -// Structure of a patch file. +#define PATCH_FLAG_REQUIRE (1 << 0) ///< Force enable patch unless 'Unsafe Options' is checked. +#define PATCH_FLAG_DEVMODE (1 << 1) ///< Require 'Developer Options' to be checked. +#define PATCH_FLAG_NOABORT (1 << 2) ///< Don't abort on error. + +/* Patch file header. + */ struct system_patch { - char magic[4]; // "AIDA" for shits and giggles and because we like .hack. - uint8_t version; // Version of the patch itself. + char magic[4]; ///< Magic to represent a patch. Should be "AIDA" for shits and giggles and because we like .hack. + uint8_t version; ///< Version of the patch itself. + + /// NOTE - This metadata stuff is temporary, I eventually plan to move it down + /// to the same 'variable' width section as tids. - // NOTE - This metadata stuff is temporary, I eventually plan to move it down - // to the same 'variable' width section as tids. - char name[64]; // User-readable name for patch in menu. - char desc[256]; // User-readable description for patch in menu. + char name[64]; ///< User-readable name for patch in menu. + char desc[256]; ///< User-readable description for patch in menu. - uint64_t uuid; // Unique ID for patch. Each unique patch should provide - // a unique ID. + uint64_t uuid; ///< Unique ID for patch. Each unique patch should provide + ///< a unique ID. - uint32_t flags; // Extra flags for patch. + uint32_t flags; ///< Extra flags for patch. - uint32_t titles; // How many titles this patch should be applied to (listed later) + uint32_t titles; ///< How many titles this patch should be applied to (listed later) - uint32_t depends; // How many deps there are. + uint32_t depends; ///< How many deps there are. - uint32_t size; // Size of the patch bytecode in bytes. + uint32_t size; ///< Size of the patch bytecode in bytes. // This stuff needs to be read not as part of the struct, but is technically part of it. diff --git a/include/patcher.h b/include/patcher.h index 04cfaeb..f79e531 100644 --- a/include/patcher.h +++ b/include/patcher.h @@ -1,7 +1,16 @@ #ifndef __PATCHER_H #define __PATCHER_H +/* Patches firmware with the current configuration. + * + * \return zero on success + */ int patch_firm_all(); + +/* Generates patch cache for boot/loader for the current configuration. + * + * \return Zero on success. + */ int generate_patch_cache(); #endif diff --git a/include/std/abort.h b/include/std/abort.h index 397ff20..04b0d58 100644 --- a/include/std/abort.h +++ b/include/std/abort.h @@ -1,6 +1,15 @@ #ifndef __ABORT_H #define __ABORT_H +/* Aborts the program and gives the user an opportunity to power off + * via a button. + * + * Does NOT return. + * + * \param x Format string + * \param ... Format operands, see printf manpage + */ + void abort(const char* x, ...) __attribute__ ((format (printf, 1, 2))); #endif diff --git a/include/std/allocator.h b/include/std/allocator.h index fa424f4..8605067 100644 --- a/include/std/allocator.h +++ b/include/std/allocator.h @@ -4,16 +4,24 @@ #include #include -// Space between most of the locations (remove me) -#define FCRAM_SPACING 0x100000 +#define FCRAM_SPACING 0x100000 ///< Space between most of the locations (remove me) -// Grow program break +/* Grow program break. + * + * \param bytes Number of bytes to grow by. + */ void *sbrk(size_t bytes); -// Allocate memory for use. +/* Allocate memory for use. + * + * \param size Size in bytes to allocate. + */ void *malloc (size_t size); -// Free in-use memory. +/* Free in-use memory allocated by malloc. + * + * \param ptr Pointer to free. + */ void free (void* ptr); #endif diff --git a/include/std/draw.h b/include/std/draw.h index 2533685..9759b16 100644 --- a/include/std/draw.h +++ b/include/std/draw.h @@ -7,16 +7,16 @@ #include #include -#define TOP_WIDTH 400 -#define TOP_HEIGHT 240 +#define TOP_WIDTH 400 ///< Top screen width +#define TOP_HEIGHT 240 ///< Top screen height -#define BOTTOM_WIDTH 320 -#define BOTTOM_HEIGHT 240 +#define BOTTOM_WIDTH 320 ///< Bottom screen width +#define BOTTOM_HEIGHT 240 ///< Bottom screen height -#define SCREEN_DEPTH 4 +#define SCREEN_DEPTH 4 ///< Pixel depth of the screen -#define TOP_SIZE (TOP_WIDTH * TOP_HEIGHT * SCREEN_DEPTH) -#define BOTTOM_SIZE (BOTTOM_WIDTH * BOTTOM_HEIGHT * SCREEN_DEPTH) +#define TOP_SIZE (TOP_WIDTH * TOP_HEIGHT * SCREEN_DEPTH) ///< Buffer size of top screen +#define BOTTOM_SIZE (BOTTOM_WIDTH * BOTTOM_HEIGHT * SCREEN_DEPTH) ///< Buffer size of bottom screen enum screen { @@ -34,71 +34,153 @@ struct framebuffers { extern struct framebuffers *framebuffers; // This is marked unused since it occurs in all files. -#define TOP_FB framebuffers->top_left -#define BOTTOM_FB framebuffers->bottom +#define TOP_FB framebuffers->top_left ///< Compact way to specify top +#define BOTTOM_FB framebuffers->bottom ///< Compact way to specify bottom +/* Initialize stdlib functionality. Must be called before ANY other functions here can be used. + */ +void std_init(); + +/* Take a screenshot and save to path. + */ void screenshot(); + +/* Fill an area on the screen with a color. + * + * \param channel Buffer to draw rectangle to. Should be zero or two. + * \param x X1 coordinate to start at. + * \param y Y1 coordinate to start at. + * \param x2 X2 coordinate + * \param y2 Y2 coordinate + * \param color Color to fill with + */ void rect(void* channel, int x, int y, int x2, int y2, uint8_t color); -void fill_line(void* channel, int y, uint8_t color); -void std_init(); +/* Fill a line behind characters with a color. + * + * \param channel Which buffer to fill line on, zero or two + * \param y Which line to fill + * \param color Color to fill with + */ +void fill_line(void* channel, int y, uint8_t color); +/* Clears background image bitmaps. + */ void clear_bg(); + +/* Loads top background image from a path. + * + * \param fname_top filename to load from. + */ void load_bg_top(char* fname_top); + +/* Loads bottom background image from a path. + * + * \param fname_bottom filename to load from. + */ void load_bg_bottom(char* fname_bottom); +/* Clears the displays either to black or the background image. + */ void clear_screens(); + +/* Draws a character to the screen. Internal use. + * + * \param screen Buffer of pixels to draw to + * \param character Character to draw + * \param ch_x X coordinate to draw to + * \param ch_y Y coordinate to draw to + * \param color_fg RGB color to draw character as (as uint32_t) + * \param color_bg RGB color to draw behind character (as uint32_t) + */ void draw_character(uint8_t *screen, const uint32_t character, int ch_x, int ch_y, const uint32_t color_fg, const uint32_t color_bg); +/* Sets the font. + * + * \param filename Font file to load. + */ void set_font(const char* filename); -#define TOP_SCREEN ((void *)0) -#define BOTTOM_SCREEN ((void *)2) +#define TOP_SCREEN ((void *)0) ///< Another name for stdout +#define BOTTOM_SCREEN ((void *)2) ///< Another name for stderr -#define stdout TOP_SCREEN -#define stderr BOTTOM_SCREEN +#define stdout TOP_SCREEN ///< Top screen/stdout +#define stderr BOTTOM_SCREEN ///< Bottom screen/stderr +/* Outputs a character to a handle + * + * \param buf Handle to output to. + * \param c Character (as int) to output + */ void putc(void *buf, const int c); + +/* Outputs a string to a handle + * + * \param buf Handle to output to. + * \param string String to output + */ void puts(void *buf, const char *string); + +/* Flushes a handle + * + * \param channel Handle to flush output on + */ void fflush(void *channel); +/* Moves the cursor/output location on a display device + * + * \param channel Display to move on (stderr/stdout) + * \param x X coordinate + * \param y Y coordinate + */ void set_cursor(void *channel, unsigned int x, unsigned int y); +/* Clear the display specified to black or a background. + * + * \param screen Which screen to clear. + */ void clear_disp(uint8_t *screen); -// Like printf. Supports the following format specifiers: -// %s - char* -// %c - char -// %d - int -// %u - unsigned int -// The following non-standard -// The following prefixes are also supported: -// %h - word (stub) -// %hh - byte (stub) -// %[0-9][0-9] -// Formats are also supported (but are subject to replacement) -// %p - unsigned char, changes color of text (will be replaced with ANSI codes -// eventually) +/* Minimal fprintf implementation. + * + * Supports the following format specifiers: + * %s - char* + * %c - char + * %d - int + * %u - unsigned int + * The following prefixes are also supported: + * %h - word (stub) + * %hh - byte (stub) + * %[0-9][0-9] + * Formats are also supported (but are subject to replacement) + * %p - unsigned char, changes color of text (deprecated, use ANSI codes please) + * + * \param channel Handle to output to. + * \param Format string. + * \param ... Format arguments + */ void fprintf(void *channel, const char *format, ...) __attribute__ ((format (printf, 2, 3))); +/* See fprintf. Takes a va_list instead of variable arguments. + */ void vfprintf(void *channel, const char *format, va_list ap); -#define BLACK 0 -#define BLUE 1 -#define GREEN 2 -#define CYAN 3 -#define RED 4 -#define MAGENTA 5 -#define BROWN 6 -#define GRAY 7 -#define D_GRAY 8 -#define B_BLUE 9 -#define B_GREEN 10 -#define B_CYAN 11 -#define B_RED 12 +#define BLACK 0 +#define BLUE 1 +#define GREEN 2 +#define CYAN 3 +#define RED 4 +#define MAGENTA 5 +#define BROWN 6 +#define GRAY 7 +#define D_GRAY 8 +#define B_BLUE 9 +#define B_GREEN 10 +#define B_CYAN 11 +#define B_RED 12 #define B_MAGENTA 13 -#define YELLOW 14 -#define WHITE 15 +#define YELLOW 14 +#define WHITE 15 #define COLOR(fg, bg) "\x1b[3" #fg ";4" #bg "m" diff --git a/source/std/draw.c b/source/std/draw.c index a595482..557db37 100644 --- a/source/std/draw.c +++ b/source/std/draw.c @@ -365,7 +365,7 @@ draw_character(uint8_t *screen, const uint32_t character, int ch_x, int ch_y, co void shut_up() { - kill_output = !kill_output; + kill_output = 1; // Immediately cancel all output operations. clear_disp(TOP_SCREEN); clear_disp(BOTTOM_SCREEN); } -- 2.39.5