|
1 | | - |
2 | | - |
3 | | ---- |
4 | | - |
5 | | - |
6 | | -3DS homebrew sdk written entirely in zig. |
7 | | - |
8 | | -## Installation |
9 | | - |
10 | | -> [!NOTE] |
11 | | -> Not even the language this project is written in is 1.0 |
12 | | -> |
13 | | -> You acknowledge that any amount of breaking changes may occur until |
14 | | -> the first stable (minor) release, a.k.a `0.1.0`. No ETA is given. |
15 | | -
|
16 | | -```bash |
17 | | -zig fetch --save git+https://github.com/GasInfinity/zitrus |
18 | | -``` |
19 | | - |
20 | | -Then add this to your `build.zig`: |
21 | | -```zig |
22 | | -const zitrus = @import("zitrus"); |
23 | | -
|
24 | | -const zitrus_dep = b.dependency("zitrus", .{}); |
25 | | -
|
26 | | -// zitrus contains code useful for tooling outside of a 3DS environment. |
27 | | -const zitrus_mod = zitrus_dep.module("zitrus"); |
28 | | -
|
29 | | -const exe = b.addExecutable(.{ |
30 | | - .name = "panic.elf", |
31 | | - .root_module = b.createModule(.{ |
32 | | - .root_source_file = b.path("src/main.zig"), |
33 | | - .target = b.resolveTargetQuery(zitrus.target.arm11.horizon.query), // zig 0.16.0 will add 'arm-3ds' and this will be deprecated! |
34 | | - .optimize = optimize, |
35 | | - .single_threaded = true, // XXX: Currently needed for page_allocator. |
36 | | - .imports = &.{ |
37 | | - .{ .name = "zitrus", .module = zitrus_mod }, |
38 | | - }, |
39 | | - }), |
40 | | -}); |
41 | | -
|
42 | | -// 3DSX's are PIE's |
43 | | -exe.pie = true; |
44 | | -
|
45 | | -// Needed for any binary which targets the 3DS |
46 | | -exe.setLinkerScript(zitrus_dep.path(zitrus.target.arm11.horizon.linker_script)); |
47 | | -
|
48 | | -// You can skip installing the elf but it is recommended to keep it for debugging purposes |
49 | | -b.installArtifact(exe); |
50 | | -
|
51 | | -const smdh: zitrus.MakeSmdh = .init(zitrus_dep, .{ |
52 | | - .settings = b.path("path-to-smdh-settings.zon"), // look at any demo for a quick sample. |
53 | | - .icon = b.path("path-to-icon.png/jpg/..."), // supported formats depends on zigimg image decoding. |
54 | | -}); |
55 | | -
|
56 | | -// See `MakeRomFs` if you need something patchable unlike `@embedFile`. |
57 | | -// WARNING: Won't be properly cached as there's an issue upstream. |
58 | | -
|
59 | | -// This step will convert your executable to 3dsx (the defacto homebrew executable format) to execute it in an emulator or real 3DS |
60 | | -const final_3dsx: zitrus.Make3dsx = .init(zitrus_dep, .{ .exe = exe, .smdh = smdh }); |
61 | | -final_3dsx.install(b, .default); |
62 | | -``` |
63 | | - |
64 | | -In your root file, you must also add this, as there's no way to implicitly tell zig to evaluate/import it automagically: |
65 | | -```zig |
66 | | -pub const panic = zitrus.horizon.panic; |
67 | | -
|
68 | | -comptime { |
69 | | - _ = zitrus; |
70 | | -} |
71 | | -``` |
72 | | - |
73 | | -## Examples / Demos |
74 | | -Currently there are multiple examples in the `demo/` directory. To build them, you must have `zig 0.15.1` in your path and run `zig build`. |
75 | | -- [mango](demo/mango/) contains samples of how to use the mango graphics api. |
76 | | - |
77 | | -- [panic](demo/panic/) is a simple example that panics when opened to test panics and traces. |
78 | | -- [info](demo/info) is a simple app that currently shows the console region and model (will be updated to show more info over time). |
79 | | -- [bitmap](demo/bitmap/) is a port of the bitmap example in libctru's 3ds-examples. |
80 | | -- [flappy](demo/flappy) is a simple fully functional flappy bird clone written entirely with software blitting. |
81 | | -- [gpu](demo/gpu/) is a playground for [mango](src/mango.zig), bleeding edge features are tested there. Not really an example per-se. |
82 | | - |
83 | | ---- |
84 | | - |
85 | | -You can (and are encouraged) to look at the `tools` directory as it is a good example of how to use the API's `zitrus` provides outside (and inside!) of a 3DS environment. Almost all tools are self-contained and span 50-300 LOC. |
86 | | - |
87 | | -# Coverage |
88 | | - |
89 | | -### Legend |
90 | | -β οΈ Feature regressed temporarily due to dependency or upstream (usually when zig updates this can happen) |
91 | | - |
92 | | -β Blocked due to upstream. Impossible to do until something gets fixed or added, usually listed in https://github.com/GasInfinity/zitrus/issues/1 |
93 | | - |
94 | | -π’ Fully implemented |
95 | | -π‘ Partially implemented |
96 | | -π΄ Implementation not started/missing critical things |
97 | | - |
98 | | -π High priority |
99 | | -πͺ« Low priority |
100 | | - |
101 | | -## Documentation |
102 | | - |
103 | | -- π‘ Mango |
104 | | -- π‘ Horizon |
105 | | - |
106 | | -## Tests |
107 | | - |
108 | | -- π‘ Horizon |
109 | | -- π‘ Mango |
110 | | - |
111 | | -## Formats (+ Tooling) |
112 | | -- π’ Smdh (tools/Smdh): Make / Dump |
113 | | -- π’ 3dsx (tools/3dsx): Make / Dump |
114 | | -- π’ Pica (tools/Pica): Assemble / Disassemble |
115 | | - - π’ Assemble: Only **Z**itrus**P**ica**Sh**ader's are implemented as an output format. |
116 | | - - π’ Disassemble: Outputs **Z**itrus**P**ica**A**sse**m**bly. Either RAW instructions, ZPSH's or DVL's (.shbin) can be disassembled. |
117 | | -- π’ Firm (tools/Firm): Make / Info / Dump |
118 | | -- π‘ Ncch (tools/Ncch): Make CXI / Dump / Info |
119 | | - - π’ ExeFS (tools/ExeFs): Make / List / Dump |
120 | | - - π’ RomFS (tools/RomFs): Make / List / Dump |
121 | | -- π‘ Compression (tools/Compress): |
122 | | - - π‘ LZrev (Compress/LzRev): Decompression |
123 | | - - π‘ Yaz0 (Compress/Yaz): Decompression |
124 | | - - π‘ LZ10 (Compress/Lz10): Decompression |
125 | | - - π‘ LZ11 (Compress/Lz11): Decompression |
126 | | -- π‘ Archives (tools/Archive): |
127 | | - - π’ Darc (Archive/Darc): Make / List / Dump |
128 | | - - π‘ Sarc (Archive/Sarc): List / Dump |
129 | | -- π‘ Layouts (tools/Layout): |
130 | | - - π‘ Image (Layout/Image): Dump |
131 | | - - π΄ Layout |
132 | | - - π΄ Animation |
133 | | -- π΄ Cro0 / Crr0 |
134 | | -- π΄ Cia |
135 | | - |
136 | | -## Horizon |
137 | | - |
138 | | -### Runtime |
139 | | -- π΄β `threadlocal` variables. |
140 | | -- π‘βπ Panic / error reporting and tracing. |
141 | | -- π‘βπ *Application* Test runner. |
142 | | - |
143 | | -### Services |
144 | | - |
145 | | -- π’ `srv:` |
146 | | -- π’ `err:f` |
147 | | -- π‘ `APT:S/A/U` |
148 | | -- π‘ `hid:SPRV/USER` |
149 | | -- π’ `ir:rst` |
150 | | -- π‘ `fs:USER/LDR` |
151 | | -- π‘ `cfg:u/s/i` |
152 | | -- π’ `gsp::Gpu` |
153 | | -- π‘πͺ« `gsp::Lcd` |
154 | | -- π‘ `ns:s` |
155 | | -- π’ `ns:p/c` |
156 | | -- π‘ `csnd:SND` |
157 | | -- π‘πͺ« `pm:app` |
158 | | -- π’ `pm:dbg` |
159 | | -- π‘ `soc:U` |
160 | | -- π‘ `ps:ps` |
161 | | -- π‘ `pxi:ps9` |
162 | | -- π‘ `Loader` |
163 | | -- π΄ All other [services](https://www.3dbrew.org/wiki/Services_API) not listed here |
164 | | - |
165 | | -### Library Applets |
166 | | - |
167 | | -- π’ `error` |
168 | | -- π‘ `swkbd` |
169 | | -- π΄ All other [applets](https://www.3dbrew.org/wiki/NS_and_APT_Services#AppIDs) not listed here. |
170 | | - |
171 | | -## Mango (PICA200 VK-like Graphics API) |
172 | | - |
173 | | -### Backends |
174 | | -- π’ Horizon |
175 | | -- π΄ Interface (for `freestanding` usage) |
176 | | - |
177 | | -### Objects |
178 | | -- π’ Presentation engine: 240x400, 240x400x2, 240x800 + 240x320. `Double` or `Triple` buffered in `Mailbox` or `Fifo`. |
179 | | -- π‘ Queues |
180 | | - - π‘ Fill (clear and fill operations) |
181 | | - - π‘ Transfer (copy and blit operations) |
182 | | - - π’ Submit (`CommandBuffer` submission) |
183 | | - - π’ Present (see `PresentationEngine`) |
184 | | -- π’ `Semaphore`s |
185 | | -- π’ `DeviceMemory` |
186 | | -- π’ `Buffer`s |
187 | | -- π’ `Sampler` |
188 | | -- π’ `Image`s / ImageViews |
189 | | -- π’ `CommandPool`s |
190 | | -- π‘ `Pipeline`s |
191 | | - - π’ Lighting |
192 | | - - π΄ Shadows |
193 | | - - π΄ Geometry shaders |
194 | | - - π΄ Fog |
195 | | - - π΄ Gas |
196 | | -- π‘ `CommandBuffer`s |
197 | | - - π΄ Shadow Rendering |
198 | | - - π΄ Gas Rendering |
199 | | - - π‘ Image Sampling |
200 | | - - π΄ Shadow textures |
201 | | - - π΄ Cubemaps |
202 | | - |
203 | | -## Hardware |
204 | | - |
205 | | -Whether register bits are present and/or relevant tooling (assemblers, disassemblers, etc...) |
206 | | - |
207 | | -- π’ CSND |
208 | | -- π’ PXI |
209 | | -- π’ LGY |
210 | | -- π’ HID |
211 | | -- π’ I2C |
212 | | -- π‘ DSP |
213 | | -- π‘ PICA200: Missing typing of some documented registers, mostly done. |
214 | | - |
215 | | -## Why? |
216 | | -I wanted to learn arm and always wanted to develop 3DS homebrew, also I searched and I haven't found any kind of zig package that doesn't use libctru, so I just started reading a lot and doing things. Furthermore, using only zig has a lot of advantages: |
217 | | -- Really simplified and easy development. You don't need complex toolchains, you just need the `zig` executable, that's it. The tools `zitrus` provides also have no dependencies, they'll work on any platform that zig supports! You can still use devkitPRO's binutils if you need. |
218 | | -- Safety in `Debug` and `ReleaseSafe` modes. Zitrus currently uses the `ErrDisp` port to report panics and returned errors. The only missing thing is reporting return traces with debugging symbols (Currently only addresses are logged) |
219 | | -- Really useful and simple build-system (as you've seen the example `build.zig` is really small and makefiles are really arcane) |
220 | | - |
221 | | -# Credits |
222 | | -- [3dbrew](https://www.3dbrew.org/wiki/Main_Page) is seriously the best resource if you need info about the 3DS hardware/software. |
223 | | -- [gbatek](https://problemkaputt.de/gbatek.htm#3dsreference) is the second best resource for low level info about the 3DS hardware. |
224 | | -- @devkitPro for the tooling, a starting point/reference for this project and reference for unknown/undocumented/unspecified things (e.g: libctru and how tf jumping to home menu worked). |
225 | | -- @azahar-emu/[azahar](https://github.com/azahar-emu/azahar) for providing an emulator to quickly test changes and the initial iterations. |
226 | | -- @LumaTeam/[Luma3DS](https://github.com/LumaTeam/Luma3DS/) for literally saving my life when trying to debug things in my 2DS. |
| 1 | +# Moved to [Codeberg](https://codeberg.org/GasInfinity/zitrus/src/branch/main) |
0 commit comments