More actions
m (Text replacement - "| licence" to "| license") |
m (Text replacement - "Category:PC utilities for 3DS homebrew" to "") |
||
| (5 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
{{Infobox 3DS Homebrews | {{Infobox 3DS Homebrews | ||
| title = libctr9 | |title=libctr9 | ||
| image = | |image=Libctr92.png | ||
| | |description=Nintendo 3DS ARM9 disk-level IO library. | ||
| | |author=Gabriel Marcano | ||
| lastupdated = 2016/07/17 | |lastupdated=2016/07/17 | ||
| | |type=File Operation | ||
| | |version=0.0.1 | ||
| | |license=GPL-2.0 | ||
| | |download=https://dlhb.gamebrew.org/3dshomebrews/libctr9.7z | ||
| source = | |website=https://gemarcano.github.io/libctr9/annotated.html | ||
|source=https://github.com/gemarcano/libctr9 | |||
}} | }} | ||
{{Obsolete}} | |||
This library is meant to be a collection of useful routines for ARM9 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. | |||
==Installation== | |||
===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 libctr9 was configured to be installed in. | |||
* [https://github.com/gemarcano/libctrelf 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 CTRARM9 holds the prefix path, then $CTRARM9/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. See [https://www.gnu.org/software/automake/manual/html_node/config_002esite.html here] for more information and details about config.site files. | |||
The Autotools setup assumes that devkitarm is already in the PATH. | The Autotools setup assumes that devkitarm is already in the PATH. | ||
| Line 46: | Line 47: | ||
make -j10 | make -j10 | ||
== | ===Installing=== | ||
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)). | |||
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): | Example (after having compiled): | ||
| Line 58: | Line 55: | ||
make install | make install | ||
Among the files installed is an example linker script, in $prefix/share/libctr9. It is recommended to use this linker script to link programs that use libctr9, since it will make sure that libctr9's built-in crt0.o is loaded in the correct location and that it initializes IO. | |||
Depending on where the library is installed, one may need to use -L in one's | ==User guide== | ||
projects to point the compiler to find the library, then use -lctr9 to cause | 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 -lctr9 to cause the linker to link in the static library. | ||
the linker to link in the static library. | |||
Example: | Example: | ||
arm-none-eabi-gcc -I$HOME/.local/usr/arm-none-eabi-9/include \ | |||
-L$HOME/.local/usr/arm-none-eabi-9/lib -Os -Wall -Wextra -Wpedantic hello.c\ | |||
-lctr9 -lfreetype2 -lctrelf | |||
One setup that is recommended is to export a variable such as, CTRARM9, to point to the root of the prefix where libctr9 is installed. This way, it is easier to point to the lib and include directories (such as by using $CTRARM9/include and $CTRARM9/lib). | |||
No start.s or _start.s files are necessary, libctr9 has its own crt0.o built in. It initializes the 3DS ARM9 MPU allowing full rwx access to all normal 3DS memory regions (ITCM and DTCM are mapped, resets the stack, and then calls libc initialization functions and then libctr9, then it jumps to main. It is recommended that any modifications to the environment be done early in main. | |||
In addition, if using libctr9'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 libctr9 is called. This allows for certain things, like caching the OTP hash value when launching from a/k9lh before the hash register is used by libctr9 during its initialization. Do | |||
note that no disk nor console subsystems are initialized at this point. | |||
===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. | 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 | In addition, some documentation is hosted in [https://gemarcano.github.io/libctr9/ GitHub pages]. | ||
== | ===Testing=== | ||
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. | |||
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. | To compile it, change directory to test/, then execute `make test`. The generated test.bin is an A9LH compatible binary. | ||
== | ==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. | |||
* See COPYING for details about code usage from other sources. | |||
==External links== | |||
* | * Official website - https://gemarcano.github.io/libctr9/annotated.html | ||
* GitHub - https://github.com/gemarcano/libctr9 | |||
* | |||
Latest revision as of 04:32, 6 Mayıs 2024
| libctr9 | |
|---|---|
 | |
| General | |
| Author | Gabriel Marcano |
| Type | File Operation |
| Version | 0.0.1 |
| License | GPL-2.0 |
| Last Updated | 2016/07/17 |
| Links | |
| Download | |
| Website | |
| Source | |
 |
This application has been obsoleted by one or more applications that serve the same purpose, but are more stable or maintained. |
This library is meant to be a collection of useful routines for ARM9 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.
Installation
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 libctr9 was configured to be installed in.
- 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 CTRARM9 holds the prefix path, then $CTRARM9/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. See here 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-9/"
make -j10
Installing
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/libctr9. It is recommended to use this linker script to link programs that use libctr9, since it will make sure that libctr9's built-in crt0.o is loaded in the correct location and that it initializes IO.
User guide
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 -lctr9 to cause the linker to link in the static library.
Example:
arm-none-eabi-gcc -I$HOME/.local/usr/arm-none-eabi-9/include \ -L$HOME/.local/usr/arm-none-eabi-9/lib -Os -Wall -Wextra -Wpedantic hello.c\ -lctr9 -lfreetype2 -lctrelf
One setup that is recommended is to export a variable such as, CTRARM9, to point to the root of the prefix where libctr9 is installed. This way, it is easier to point to the lib and include directories (such as by using $CTRARM9/include and $CTRARM9/lib).
No start.s or _start.s files are necessary, libctr9 has its own crt0.o built in. It initializes the 3DS ARM9 MPU allowing full rwx access to all normal 3DS memory regions (ITCM and DTCM are mapped, resets the stack, and then calls libc initialization functions and then libctr9, then it jumps to main. It is recommended that any modifications to the environment be done early in main.
In addition, if using libctr9'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 libctr9 is called. This allows for certain things, like caching the OTP hash value when launching from a/k9lh before the hash register is used by libctr9 during its initialization. Do note that no disk nor console subsystems are initialized at this point.
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.
Testing
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.
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.
- See COPYING for details about code usage from other sources.
External links
- Official website - https://gemarcano.github.io/libctr9/annotated.html
- GitHub - https://github.com/gemarcano/libctr9