diff --git a/PXI.md b/PXI.md new file mode 100644 index 0000000..f879377 --- /dev/null +++ b/PXI.md @@ -0,0 +1,35 @@ +GodMode9 mainly runs on the ARM9 CPU (ARM946E-S) on the 3DS, but as there are certain hardware registers that can simply not be accessed from it, GM9 needs to be able to talk to the ARM11 CPU (MPCore11). + +This is achieved using built-in hardware ([PXI](https://3dbrew.org/wiki/PXI_Registers)) that's available on the console, with both CPUs using a very simple [protocol](https://github.com/d0k3/GodMode9/blob/07e419f51426d9121fdf1bc3096c1f0f893464d1/common/pxi.h#L133) to send messages to each other. + +Currently implemented commands are available [here](https://github.com/d0k3/GodMode9/blob/07e419f51426d9121fdf1bc3096c1f0f893464d1/common/pxi.h#L17). + + +### Protocol overview + +Both CPUs must have been synchronized to have their PXISync Remote port set to `PXI_READY` at some point earlier. The receiving CPU must also have interrupts enabled and properly set up, or periodically poll the PXISync Remote port register. + + +Whenever CPU A wants to send a command to CPU B: + + 1) CPU A makes sure CPU B is ready to accept a command (Remote port is `PXI_READY`). + 2) CPU A sends up to 16 32-bit parameters. The parameter count depends on the command. + 3) CPU A sets its Remote port to the command ID. + 4) CPU A triggers a PXISync interrupt which will be picked up by CPU B. + 5) CPU A waits on a tight loop until CPU B's Remote port is `PXI_BUSY`. + +At Step 4, CPU B will receive a processor hardware interrupt and execute the PXI command handler. This handler will: + + 1) Read the Remote port of CPU A to get the command ID. + 2) Depending on the command, it'll receive up to 16 32-bit parameters onto a local buffer. + 3.0) If the command is asynchronous, the Remote port will be set to `PXI_BUSY`. + 3.1) Execute the desired command with the specified arguments. + 3.2) If the command is synchronous, the Remote port will be set to `PXI_BUSY`. + 4) The Remote port will be set to `PXI_READY`. + + +### Adding new commands + +Due to GM9 limitations, interrupts must be masked on the ARM9 at all times. Therefore, it is not possible to send commands from the ARM11 to the ARM9. + +In order to add a new command, a new ID must be added to [common/pxi.h](https://github.com/d0k3/GodMode9/blob/master/common/pxi.h) and the code to handle it has to be implemented in [mpcore/source/main.c](https://github.com/d0k3/GodMode9/blob/master/arm11/source/main.c). There's a "template" present, plus two currently implemented commands that can be used as examples. diff --git a/Scripting.md b/Scripting.md index 367aa7e..dee255c 100644 --- a/Scripting.md +++ b/Scripting.md @@ -1,18 +1,26 @@ -GodMode9 is a large and complicated program, which since release v1.2.7 has had support for Scripting. Scripts are formatted in plaintext with a `.gm9` file extension, and allow the automation of many complex things. +GodMode9 has featured a scripting engine since [version 1.2.7](https://github.com/d0k3/GodMode9/releases/tag/v1.2.7). + +Scripts are formatted as plaintext ASCII with a `.gm9` file extension, and allow the automation of complex tasks. + ### Running a Script -To run a GodMode9 script, all one must do is place the script file in the `/gm9/scripts` folder on the SD card. Then, in GodMode9, press the HOME button, press on Scripts... and select the script that you would like to run. -One can also place the script anywhere on the SD (or any other drive, for that matter), and press A on the script file. There will be the option to Execute GM9 Script. You will get another prompt (are you sure you would like to execute this script?), press A there, and then the script will be run. +All scripts placed in the `/gm9/scripts` folder on the SD card will show up on the Scripts menu (HOME button -> Scripts...) and can be conviniently executed from there. + +To run a script that's not present in this folder, it can be manually executed by navigating to it and choosing "Execute GM9 Script" from its context menu. + ### Basics -GodMode9 script resembles shell script. Comments are denoted by `#` and work anywhere. Variable are in the format `$[VAR]` where `VAR` is the name of the variable. (i.e. $[HAX]). Surround an argument with `"` if it must contain whitespaces. Any redundant whitespaces outside of `"` will be treated as a single whitespace. -An unknown command will lead to script abort. +GodMode9 scripts resemble shell scripts. Comments are denoted by `#` and work anywhere. Variable are in the format `$[VAR]` where `VAR` is the name of the variable. (i.e. $[HAX]). Surround an argument with `"` if it must contain whitespaces. Any redundant whitespaces outside of `"` will be treated as a single whitespace. +An unknown command will lead to a script abort. + + #### `-o` and `-s` Switches You can use `-o` and/or `-s` switches on any command, or `--optional` / `--silent` respectively. `-o` Continues on failures of a command, and `-s` will try to suppress all error messages. Example: `ask -o -s "Perform this operation (I will completely ignore your response)?"` + ### Commands A short description of every command. Click on the command to go to a more detailed page about it. @@ -26,9 +34,10 @@ A short description of every command. Click on the command to go to a more detai [more to come ofc] -#### Environmental Variables -Environmental Variables are variables that are always available, no matter what. They are determined when GodMode9 boots, and cannot be changed via scripting commands. Remember, when including a variable in a command, use `$[VAR]` where `VAR` is the name of the variable (i.e. `$[HAX]`). +#### Environment Variables + +Environment Variables are variables that are always available, no matter what. They are determined when GodMode9 boots, and cannot be changed via scripting commands. Remember, when including a variable in a command, use `$[VAR]` where `VAR` is the name of the variable (i.e. `$[HAX]`). * `GM9VER` - the version of the currently running GodMode9 firm. (i.e. v5.0.0) * `REGION` - the region of the console's SysNAND. (can be `USA`, `EUR`, `JPN`, `KOR`, `CHN`, `TWN`, or `UNK` for unknown) @@ -41,4 +50,4 @@ Environmental Variables are variables that are always available, no matter what. * `SYSID0` - ID0 of SysNAND. * `EMUID0` - ID0 of EmuNAND (if available). * `TIMESTAMP` - the current time in hhmmss format (based on RTC). -* `DATESTAMP` - the current date in YYMMDD format (based on RTC). \ No newline at end of file +* `DATESTAMP` - the current date in YYMMDD format (based on RTC).