-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
214 lines (158 loc) · 9.37 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
________________________________________________________________________________
(Working title) libctr11
Copyright 2016 Gabriel Marcano
________________________________________________________________________________
--------------------------------------------------------------------------------
Licensing
--------------------------------------------------------------------------------
This project is licensed under the GPL 2 or later licenses, at your choice.
Refer to COPYING for more licensing information and for the licensing for the
code borrowed from other sources.
--------------------------------------------------------------------------------
About
--------------------------------------------------------------------------------
This library is meant to be a collection of useful routines for ARM11 3DS
development. The plan is for it to eventually grow to something like libnds.
Currently the main contribution to this library is a generic disk IO framework
that has been designed for ease of use and extensibility.
The library was meant to be linked with LTO, but due to technical limitations of
devKitARM with GCC 5.3, it is not. Instead, it is compiled with
-ffunction-section, so if the final executable uses the gc-section option for
the linker, the linker when linking the final executable will be able to throw
out parts of the library that are not in use, reducing executable size.
Note this library is still in active development and the API is not considered
stable. Breaking changes will be mentioned in commits at the very least.
--------------------------------------------------------------------------------
Dependencies
--------------------------------------------------------------------------------
- FreeType2 - Used for font handling. Make sure it is installed somewhere that
the compiler can pick it up, or use -L and -I to instruct the compiler where
to find it. The build tools will attempt to find it within the prefix where
libctr11 was configured to be installed in.
- libctrelf - https://github.com/gemarcano/libctrelf
Used for helping to parse and handle ELF data.
- Autotools in general. These are used to create the build scripts.
--------------------------------------------------------------------------------
Compiling
--------------------------------------------------------------------------------
As a suggestion, it is recommended for one to set up a fixed prefix directory
and to store a share/config.site under the prefix. For example, if the variable
CTRARM11 holds the prefix path, then $CTRARM11/share/config.site is where this
file would be located. Any variables defined here will be picked up by configure
upon being run. At a minimum, if other libraries will be installed to the prefix
path, the config.site should have the following:
CPPFLAGS="$CPPFLAGS -I$prefix/include -I$prefix/include/freetype2"
LDFLAGS="-L$prefix/lib $LDFLAGS"
This example assumes that these directories exist, and in particular that
FreeType2's include path exists in the folder shown above. Refer to:
https://www.gnu.org/software/automake/manual/html_node/config_002esite.html
for more information and details about config.site files.
The Autotools setup assumes that devkitarm is already in the PATH.
# this following line is if the 3ds compiler isn't in the path
export PATH=${PATH}:${DEVKITPRO}/bin:${DEVKITARM}/bin
autoreconf -if
./configure --host arm-none-eabi --prefix=[lib install path]
make
Example:
export PATH=${PATH}:${DEVKITPRO}/bin:${DEVKITARM}/bin
autoreconf -if
./configure --host arm-none-eabi --prefix="$HOME/.local/usr/arm-none-eabi-11/"
make -j10
--------------------------------------------------------------------------------
Installation
--------------------------------------------------------------------------------
TBD. This library is built using Autotools, so it supports the 'make install'
and 'make uninstall' targets. Be sure to set --prefix when calling configure
if either of the preceeding targets will be used, else by default the generated
Makefile will install to /usr/local/ (most likely)) !
Example (after having compiled):
#this will install to the directory specified in prefix, or /usr/local/ if
#prefix isn't defined (most likely)!
make install
Among the files installed is an example linker script, in $prefix/share/libctr11.
It is recommended to use this linker script to link programs that use libctr11,
since it will make sure that libctr11's built-in crt0.o is loaded in the correct
location and that it initializes IO.
--------------------------------------------------------------------------------
Usage
--------------------------------------------------------------------------------
Depending on where the library is installed, one may need to use -L in one's
projects to point the compiler to find the library, then use -lctr11 to cause
the linker to link in the static library.
Example:
arm-none-eabi-gcc -I$HOME/.local/usr/arm-none-eabi-11/include \
-L$HOME/.local/usr/arm-none-eabi-11/lib -Os -Wall -Wextra -Wpedantic \
hello.c -lctr11 -lfreetype2 -lctrelf
One setup that is recommended is to export a variable such as, CTRARM11, to
point to the root of the prefix where libctr11 is installed. This way, it is
easier to point to the lib and include directories (such as by using
$CTRARM11/include and $CTRARM11/lib).
No start.s or _start.s files are necessary, libctr11 has its own crt0.o built
in. It (FIXME is supposed to) initializes the 3DS ARM11 MMU to (FIXME WHAT?).
(FIXME This part is not done )resets the stack, and then calls libc
initialization functions and then libctr11, then it jumps to main. It is
recommended that any modifications to the environment be done early in main.
FIXME the following isn't true yet
In addition, if using libctr11's included crt0 functionality, it does support
the __constructor__ attribute for functions. Functions with this attribute will
be executed before the main initialization function for libctr11 is called.
--------------------------------------------------------------------------------
Documentation
--------------------------------------------------------------------------------
This project uses Doxygen markup in order to facilitate the generation of
documentation, which should be found when generated in the doc/ folder. Each
header in the include/ directory should also be well documented and can be used
as reference for programming.
In addition, some documentation is hosted in GitHub pages:
https://gemarcano.github.io/libctr11/
--------------------------------------------------------------------------------
Testing - FIXME not there yet
--------------------------------------------------------------------------------
This project does include a homegrown unit testing framework and some unit tests
for this library. See the test/ directory for more information. Note that the
unit testing payload WILL write to NAND (in theory writes to areas that are
unused) as a part of unit testing.
To compile it, change directory to test/, then execute `make test`. The
generated test.bin is an A9LH compatible binary.
--------------------------------------------------------------------------------
Issues/Bugs
--------------------------------------------------------------------------------
Please report these to the issue tracker at the repository, and these will be
addressed as soon as possible, if not at least acknowledged. The more detailed
the reports, the more likely they are to be addressed quickly. In particular,
the following information can be quite useful when debugging bugs:
- Type of 2/3DS system
- Operating system being used to compile
- Release/commit of library in use
- Steps to reproduce issue
- Expected behavior
- Actual behavior
- ARM9 entry point
- How the ARM11 payload was launched and set up
- Any modifications to the library, or extensions
--------------------------------------------------------------------------------
Contributing
--------------------------------------------------------------------------------
Pull requests are welcome. All requests will be looked at in detail, and must be
documented in a similar fashion as the rest of the code for this project. In
particular, it is unlikely (but not impossible) that code that emmits warnings
with the warnings in use by this library would be merged without first fixing/
addressing what is causing the warnings to be emitted.
--------------------------------------------------------------------------------
Credits
--------------------------------------------------------------------------------
- #3dshacks @ Rizon for starting me on my path to 3DS homebrew development
- #Cakey @ Freenode for the continued development support
- #3dsdev @ EFNet for the occasional help answering questions
- d0k3 for some code use in this library and for suggestions
- dark_samus for helping to develop A9LH stuff in Cakey, which drove for the
development of this library
- Delebile for publishing the public arm9loaderhax implementation, making using
and testing this library possible (or less of a pain)
- Aurora, et. al (you know who you are, I hope) for for general development
help and brainstorming
- Normmatt for yelling at me for screwing up his sdmmc code :) Also a lot of
other general 3DS development stuff
- bilis for his ctr library (a small amount of code from that is used) and for
his QEMU implementation of the 3DS ARM9 environment.
- See COPYING for details about code usage from other sources