From 2d4272c18380cdb16f20c493a4085b1b8e057ce7 Mon Sep 17 00:00:00 2001 From: root Date: Sun, 15 May 2016 02:41:44 -0400 Subject: [PATCH] Docs, docs, more docs --- README.md | 45 ++++---------------- doc/CODE_ORIGIN.md | 5 --- doc/STDLIB.md | 16 ------- doc/attribution.md | 7 ++++ doc/features.md | 101 +++++++++++++++++++++++++++++++++++++++++++++ doc/firmware.md | 31 ++++++++++++++ doc/std.md | 2 + firmurls | 23 ----------- 8 files changed, 149 insertions(+), 81 deletions(-) delete mode 100644 doc/CODE_ORIGIN.md delete mode 100644 doc/STDLIB.md create mode 100644 doc/attribution.md create mode 100644 doc/features.md create mode 100644 doc/firmware.md create mode 100644 doc/std.md delete mode 100644 firmurls diff --git a/README.md b/README.md index 6c1bbea..838ce4f 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,18 @@ Corbenik ============================== -This is (yet another) CFW for the 3DS. Unlike other CFWs, this was mostly written from scratch for fun, and because I'm a control freak. +This is (yet another) CFW for the 3DS. Unlike other CFWs, this was mostly written from scratch for fun, and because I'm a control freak. Some parts are inherited from other CFW - near everything in src/firm is based on CakesFW, and the signature patch/firmprot/svcbackdoor fix are all based on Luma3DS while using the more correct CakesFW section code. -Conceptually, and in operation, it is most similar to mid-kid/CakesForeveryWan out of the bunch. That is, it uses external patches from the filesystem. Unlike cakes, patches are dynamically offset - the same way Luma3DS and ReiNand do things. But like cakes, they're software-defined. +Conceptually, and in operation, this is most similar to mid-kid/CakesForeveryWan out of the bunch. That is, it uses external patches from the filesystem and is intended for developers and control freaks. Unlike cakes, patches are dynamically linked code for whatever processor it is on. -More importantly - for arm9 programmers who don't like headaches - I have an implementation of console printf you may be interested in, and a very close imitation of stdio around fatfs in the `std` folder. +Yes; you read that correctly. I initially was going to use a dynamic cake-like patch. I quickly realized a fatal flaw in any "patch" format: what you can do from a patch is limited to what the parser handles. The best way to fix this was to make patches standalone relocatable binaries instead. -The version of loader in this repo is very tightly tied to the operation of Corbenik. It takes care of all binary changes on initialization. It should not be used with other versions of loader. +The binary ABI is not yet stabilized. Do not expect a patch to simply function a version later. For this very reason, the CFW version field in the patch header is ignored at the moment until the ABI has been finalized. I *may* simply rewrite it as an elf loader; I'm unsure yet as to what I'll do. -If you want to know how it sizes up to other CFWs - here's a quicklist of things it does: +If you want to know how Corbenik sizes up to other CFWs - see `doc/features.md`. -Signature patches --------------------------- +For compilation instructions, see `doc/compiling.md`. -Done via standard search and replace. - -FIRM Protection --------------------------- - -Done similarly to Reinand - replacing the 'exe' string with 'prt' - -System module replacement --------------------------- - -Overrides the complete module - can't change size. - -ExeFs replacement --------------------------- - -Overrides the whole exefs. - -Locale Emulation --------------------------- - -Different from existing solutions - a single text file of the format: -``` - -``` -This is technically superior because it doesn't involve large and unloadable directory trees. Corbenik comes with an example locale configuration built automatically from single-region single-language games on 3DSDB. - -ARM9 control thread --------------------------- - -Because...well, I hate NTR with a passion. This is one of the primary features differentiating Corbenik from other CFWs. Hitting X+Y pops open a menu and allows configuring any loader-based patches, as well as taking screenshots and performing memory dumps. I will not add plugins created in ARM9 code, but I may embed an interpreter someday. +Unless otherwise noted, everything in this repo can be used under the terms of the GNU GPL, Version 3 or later (if ever) at your discretion. This includes situations where there's no copyright header within a source file. +Technically, all patches must be open source under a compatible license as well due to these linking restrictions. I will not be making the linking exception. Allowing proprietary patches to exist will only harm everyone in the homebrew community in long-term. Read: NTR. diff --git a/doc/CODE_ORIGIN.md b/doc/CODE_ORIGIN.md deleted file mode 100644 index 0aa1c28..0000000 --- a/doc/CODE_ORIGIN.md +++ /dev/null @@ -1,5 +0,0 @@ -While most everything in this repo is original, some parts are derived from existing software, and I make the best effort to document what is derivative in the interest of giving proper credits: - -src/firm - Firmware decryptor originally from CakesFW (http://github.com/mid-kid/CakesForeveryWan) -src/fatfs - FatFS - http://elm-chan.org/fsw/ff/00index_e.html . This version originates from Decrypt9's repo. -src/std - Work was originally based on memfuncs.c and memory.c from Cakes and ReiNand, but contains near none of the original code now. diff --git a/doc/STDLIB.md b/doc/STDLIB.md deleted file mode 100644 index f8197d3..0000000 --- a/doc/STDLIB.md +++ /dev/null @@ -1,16 +0,0 @@ -The stdlib/ directory is a self-contained, mostly conformant implementation of the C Standard Library for 3DS in ARM9 code. It supports a good chunk of standard functions and interfaces which follow: - -FILE* fopen(const char* name, const char* mode) - - Opens a file @name@ with access mode @mode@ and returns an opaque FILE pointer. - -size_t fread(void* buf, size_t size, size_t elem, FILE* handle) - - Reads @elem@ elements of size @size@ from the file @handle@, storing read data to @buf@. - -size_t fread(void* buf, size_t size, size_t elem, FILE* handle) - - Writes @elem@ elements of size @size@ to the file @handle@, reading data to write from @buf@. - -void fseek(FILE* file, ); - diff --git a/doc/attribution.md b/doc/attribution.md new file mode 100644 index 0000000..6079cee --- /dev/null +++ b/doc/attribution.md @@ -0,0 +1,7 @@ +While most everything in this repo is original, some parts are derived from existing software, and I make the best effort to document what is derivative in the interest of giving proper credits: + +src/firm - Firmware decryptor originally from CakesFW (http://github.com/mid-kid/CakesForeveryWan) +src/fatfs - FatFS - http://elm-chan.org/fsw/ff/00index_e.html . This version originates from Decrypt9's repo. +src/std - Work was originally based on memfuncs.c and memory.c from Cakes and ReiNand, but contains near none of the original code now. +src/patcher.c - Contains some bits from Luma3DS, but they've been adjusted for the cakes structures (src/firm) rather than crazy-ass pointer math. + diff --git a/doc/features.md b/doc/features.md new file mode 100644 index 0000000..6d98ee8 --- /dev/null +++ b/doc/features.md @@ -0,0 +1,101 @@ +Feature graph +---------------- + ++--------+-----------------+-----------------+------------------------------+-----------+---------------+-------------------+-------+ +|CFW |Firms? |Patch Method |Supplies Officially |Available |Optimization[1]|Focus? |Notes | ++--------+-----------------+-----------------+------------------------------+-----------+---------------+-------------------+-------+ +|CakesFW |Dec/Enc (SD) |Loadable, Fixed |Sig,Emu(M),Twl,Agb,Sys,Ptc |Mis,Bck,Mod|Speed/Read |Devs/Advanced Users| [2] | ++--------+-----------------+-----------------+------------------------------+-----------+---------------+-------------------+-------+ +|Luma3DS |Enc(NAND) Dec(SD)|Builtin, Dynamic |Sig,Emu(2),Sys,Mod,Bck,Mis,Ptc|N/A |Giant Mess |"Noob-proof" | [3] | ++--------+-----------------+-----------------+------------------------------+-----------+---------------+-------------------+-------+ +|ReiNAND |Meme(SD) |Builtin, Dynamic |Sig,Emu,Sys,Mod,Ptc |N/A |Readability |Minimalist | [4] | ++--------+-----------------+-----------------+------------------------------+-----------+---------------+-------------------+-------+ +|Corbenik|Dec/Enc (SD) |Executable |Sig,Ptc,Bck,Mod,Sys |Mis |Read/Speed |Advanced Devs | [5] | ++--------+-----------------+-----------------+------------------------------+-----------+---------------+-------------------+-------+ +|NTR |N/A |Executable |Mis |Mis |Douchebaggery |Shilling Closed Src| [6] | ++--------+-----------------+-----------------+------------------------------+-----------+---------------+-------------------+-------+ + + * Sig: Signature Patch. + * Twl: TWL Signature Patch + * Agb: AGB Signature Patch + * Ptc: FIRM protection + * Emu: Emunand. + * (M) - Can have many (unlimited) + * (X) - Can have X emunands. + * Sys: Can boot sysnand from a9lh. + * Mod: Loader replacement + * Bck: Load svcBackdoor on 11.0 + * Mis: Other misc fixes and alterations including: + * UNITINFO patch + * GBA bios screen + +Misc features by CFW: + * Cakes: + * mid-kid/lgy_cakes + * TWL patches + * AGB patches + * 3ds_injector + * You have multiple choices. Wolfvak's, mid-kid's, mine, etc... + * Wolfvak/icing + * UNITINFO + * svcBackdoor (incomplete) + * Luma + * Loader replacement. CPU speed/language emulation + +[1] I'm not just referring to speed; I'm referring to purpose-based optimization. For example; + do you want something well documented? Would you choose a slower algorithm that can be more + easily debugged at the expense of speed? Would you use preprocessor macros to use multiple? + + CakesFW is Speed/Read. Speed first, keep readability if possible whenever possible. Which is a good + approach. + + No, I don't call Luma a complete mess lightly. Go look thorugh the code. You back? Good. Tell me, + are the comments helpful and do you understand what the blatant pointer abuse in patches.c is + actually ref'ing? No? I had to decode that. It's referencing the exefs's code section. Which was + impossible to tell without ten minutes staring at it. Moving on now... + + ReiNAND is cruft-free and well documented. It doesn't do a lot, but what it does do, it does well. + Unix philosphy in a nutshell. The only complaint is memekey. + + My focus will always be readability over speed, unless choosing speed and adding additional documentation + suffices. As an aside; if you see a single trigraph in my code, please report it. Trigraphs are by design a bug. + +[2] CakesFW uses a patch format that has static offsets. They're dynamically loaded and in theory are impervious + to updates. In practice, updating patches is a pain and better done by offset patches like Luma3DS/Rei. + + Either way, Cakes allows doing some things the other firmware authors would probably call idiotic; I call them + smart since I get a choice. Cakes is lacking a few things from Luma3DS mainly because (in my opinion) the patch + format is incapable of accomodating some changes in a sane manner that doesn't require excessive RE or on console + one off offset checks. + +[3] Luma is a weird beast - "Noob-proof" as github states very perfectly describes it for better or worse. Want to load + encrypted SD FIRM? Nope. Load SD firm with SysNAND? Nope. And many options aren't exposed to the user, period. Oh, + I suppose there's no legitimate reason to disable firmprot anyways, either. Detection of Emunand #2 tends to be + faulty. I have four. + +[4] Reisyukaku has fallen behind a bit; his firmware is still in use and rather slim. He does, however, do some fancy + ass magic to load a re-encrypted copy (?) of the nintendo firmware using a key refered to as the 'memekey'. How + encrypting data differently makes it any less illegal to rehost I have no clue. + +[5] Yes, Corbenik currently lacks quite a few things from this graph. On the upside; patches can be implemented + externally. I currently have zero interest in implementing reboot; I never need it, having a n3ds. EmuNAND, as + well is something I have little interest in (but will happen eventually.) + + As for other bits; Aside from fixing svcBackdoor, I can also inject arbitrary custom services. You're welcome. + +[6] Okay, first - I could rant about how NTR is harming us long run for hours. I won't rant for hours, but I will + explain some of the rationale here: + + NTR is a secondary CFW; it's designed to be used with a primary one. It consists of a proprietary blob, ntr.bin + which loads into memory and takes over the debug service and subsequently the arm11 kernel. + + Normally, the functionality would be useful, but when you consider he's using techniques he hasn't bothered to doc + on 3dbrew, you should by now know his goal is lock-in. From BootNTR it's apparent he's a shitty coder[7]. He + won't document it, because someone else will create a better optimized version. Hm...that sounds a lot like a + certain Japanese company who developed a cons- oh wait. + + The point is; NTR is not your friend. Stop using it. + +[7] Tell me that giant switch statement couldn't be implemented as a dynamic patcher on the 3DS itself, considering + all of the python offset extractor could be rewritten in C. Dare you. He also can't be bothered to port to 10.4 + NATIVE_FIRM even though there's literally no difference that should break NTR. diff --git a/doc/firmware.md b/doc/firmware.md new file mode 100644 index 0000000..884edb0 --- /dev/null +++ b/doc/firmware.md @@ -0,0 +1,31 @@ +Old 3DS NATIVE_FIRM Versions: + cetk: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013800000002/cetk + + 10.4: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013800000002/00000050 + 11.0: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013800000002/00000052 + +New 3DS NATIVE_FIRM (The standard 3DS firmware - REQUIRED): + cetk: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013820000002/cetk + + 10.4: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013820000002/0000001F + 11.0: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013820000002/00000021 + +Old 3DS TWL_FIRM (Firmware for DS/DSi games): + cetk: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013800000102/cetk + + firm: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013800000102/00000016 + +New 3DS TWL_FIRM (Firmware for DS/DSi games): + cetk: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013820000102/cetk + + firm: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013820000102/00000000 + +Old 3DS AGB_FIRM (Firmware for GBA games): + cetk: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013800000202/cetk + + firm: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013800000202/0000000B + +New 3DS AGB_FIRM (Firmware for GBA games): + cetk: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013820000202/cetk + + firm: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013820000202/00000000 diff --git a/doc/std.md b/doc/std.md new file mode 100644 index 0000000..ac12f15 --- /dev/null +++ b/doc/std.md @@ -0,0 +1,2 @@ +The std/ directory is a self-contained, mostly conformant implementation of the C Standard Library for 3DS in ARM9 code. +It supports a good chunk of standard functions and interfaces, but not everything. diff --git a/firmurls b/firmurls deleted file mode 100644 index 281179c..0000000 --- a/firmurls +++ /dev/null @@ -1,23 +0,0 @@ -Old 3DS NATIVE_FIRM (The standard 3DS firmware - REQUIRED): -firmware.bin: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013800000002/00000050 -cetk: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013800000002/cetk - -New 3DS NATIVE_FIRM (The standard 3DS firmware - REQUIRED): -firmware.bin: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013820000002/0000001F -cetk: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013820000002/cetk - -Old 3DS TWL_FIRM (Firmware for DS/DSi games): -twl_firmware.bin: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013800000102/00000016 -twl_cetk: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013800000102/cetk - -New 3DS TWL_FIRM (Firmware for DS/DSi games): -twl_firmware.bin: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013820000102/00000000 -twl_cetk: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013820000102/cetk - -Old 3DS AGB_FIRM (Firmware for GBA games): -agb_firmware.bin: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013800000202/0000000B -agb_cetk: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013800000202/cetk - -New 3DS AGB_FIRM (Firmware for GBA games): -agb_firmware.bin: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013820000202/00000000 -agb_cetk: http://nus.cdn.c.shop.nintendowifi.net/ccs/download/0004013820000202/cetk -- 2.39.5