________________________________________________________________________________

arm9launcher

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 set of programs form a 3DS ARM9 payload selector, or bootloader. This
project was started for two reasons: the author thought most ARM9 payload
selectors in existence were too convoluted for their own good, and he wanted
an application to showcase the usage of his general purpose libctr9 3DS ARM9
code library.

Currently arm9launcher supports the following:

  -Button based payload selection, configurable via a configuration file

  -Human readable configuration file, in JSON format

  -Payloads can be launched from an external SD card, and internal CTRNAND,
        TWLN, and TWLP partitions

  -The configuration and bootloader files can be stored in CTRNAND or an SD
    card.

Planned features:

  -Menu based payload selection

  --Author is open to suggestions


Note that this project is still under active development. Please

--------------------------------------------------------------------------------
Build dependencies
--------------------------------------------------------------------------------

 - Autotools in general. These are used to create the build scripts.

 - https://github.com/gemarcano/libctr9 - Used for general 3DS ARM9
    functionality.
    See that repository for instruction on how to install it.

  - https://github.com/gemarcano/libctr_core - Used by libctr9. See that
    repository for instructions on how to install it.

 - Freetype2. Needed by libctr9.

--------------------------------------------------------------------------------
Compiling
--------------------------------------------------------------------------------

The Autotools setup assumes that devkitarm is already in the PATH. It also
assumes the environmental variable CTRARM9 is set to wherever the --prefix used
to install libctr9 is.

 # this following line is if the 3ds compiler isn't in the path
 export PATH=${PATH}:${DEVKITPRO}/bin:${DEVKITARM}/bin
 export CTRARM9=[root path of libctr9 installation]
 autoreconf -if
 ./configure --host arm-none-eabi --prefix=$CTRARM9
 make

Example:
  export PATH=${PATH}:${DEVKITPRO}/bin:${DEVKITARM}/bin
  export CTRARM9=~/.local/usr/arm-none-eabi-9
  autoreconf -if
  ./configure --host arm-none-eabi --prefix=$CTRARM9
  make -j10


--------------------------------------------------------------------------------
Installation
--------------------------------------------------------------------------------

In the src/ directory after `make` is run, the files arm9loaderhax.bin and
arm9launcher.bin are the loader and bootloader, respectively. These can be
copied to the root of an SD card or the root of CTRNAND.

Besides the executables, the loader needs a configuration file,
arm9launcher.cfg. An example configuration file is included on the root of the
armlauncher repository. This configuration needs to be on the root of an SD
card or CTRNAND.


--------------------------------------------------------------------------------
Configuration
--------------------------------------------------------------------------------

The configuration file is in JSON. Every entry is in a key, value pair. The
configuration JSON consists of a configuration entry with a value of an array
of entries. Each configuration entry is a JSON object with some keys.

Each entry requires the following keys with values:

  - "name" : "a string representing a name of a payload (unused currently)"

  - "location : "path to the payload. Use SD:/, CTRNAND:/, TWLN:/, TWLP:/
    prefixes for accessing payloads in the different partitions."

  - "buttons" : [ "array of strings representing which buttons trigger a
    particular choice. Multiple buttons for a single entry are supported."]
      Buttons supported include (case sensitive):
        "None" - Represents the payload chosen if no buttons are pressed
        "A"
        "B"
        "Select"
        "Start"
        "Right"
        "Left"
        "Up"
        "Down"
        "R"
        "L"
        "X"
        "Y"
     Note that this list does not include the second shoulder buttons found on
     the N3DS, nor the home menu button. Those are handled separately in the
     3DS hardware than how the rest of the buttons are polled. This is something
     the author can look into addressing at some later date.

Entries support the following optional entries:

  - "offset" : a numeric value (hex or decimal) specifying the offset from which
    to load the actual payload from the given payload file. This is useful for
    programs like CakesFW, which has the ARM9 binary in the Cakes.dat at offset
    0x12000.

See the arm9launcher.cfg file included in the repository for an example
configuration file.

--------------------------------------------------------------------------------
Usage
--------------------------------------------------------------------------------

When the arm9loaderhax.bin program is launched somehow, it will read the current
HID input state (buttons) to determine which payload to load. It will then try
to parse the configuration file it finds (either on the SD card or on the
CTRNAND, in that order). If the HID state matched any of the payloads described
in the configuration file, it will then try to hand off execution to the
arm9launcher.bin to actually launch the payload.

If an error occurs, like the SD card being really screwed up, or NAND is bad,
or the configuration file is bad, or if the payload was not found, some error
will be reported. Pressing any button will cause the system to power off.
Currently error messages are not exactly user friendly.


--------------------------------------------------------------------------------
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 poin usedt
 - Any modifications or extensions
 - Version of libctr9 in use (or commit)


--------------------------------------------------------------------------------
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
 - Everyone that has helped in the development of libctr9 (see the README of
   libctr9 for more details.