[Pocketstation] Document SWI handler

docs/graphicsprocessingunitgpu.md

@@ -1398,7 +1398,7 @@ There are 4 semi-transparency modes in the GPU.<br/>
   * 1.0 x B +0.25 x F    ;aka B+F/4
 ```
 For textured primitives using 4-bit or 8-bit textures, bit 15 of each CLUT entry acts as a semi-transparency flag and determines whether to apply semi-transparency to the pixel or not. If the semi-transparency flag is off, the new pixel is written to VRAM as-is.<br/>
-When using additive blending, if a channel's intensity is greater than 255, it gets clamped to 255 rather than being masked. Similarly, if using subtractive blending and a channel's intensity ends up being < 0, it's clamped to 0.
+When using additive blending, if a channel's intensity is greater than 255, it gets clamped to 255 rather than being masked. Similarly, if using subtractive blending and a channel's intensity ends up being < 0, it's clamped to 0.<br/>
 
 #### Modulation (also known as Texture Blending)
 Modulation is a colour effect that can be applied to textured primitives.
@@ -1409,7 +1409,7 @@ For each pixel of the primitive it combines every colour channel of the fetched
 Using modulation, one can either decrease (if the vertex colour channel value is < 128) or increase (if it's > 128) the intensity of each colour channel of the texel, which is helpful for implementing things such as brightness effects.<br/>
 Using a vertex colour of 0x808080 (ie all channels set to 128) is equivalent to not applying modulation to the primitive, as shown by the above formula.<br/>
 "Texture blending" is not meant to be confused with normal blending, ie an operation that merges the backbuffer colour with the incoming pixel and draws the resulting colour to the backbuffer.
-The PS1 has this capability to an extent, using semi-transparency.
+The PS1 has this capability to an extent, using semi-transparency.<br/>
 
 #### Draw to display enable
 This will enable/disable any drawing to the area that is currently displayed.

docs/pocketstation.md

@@ -1399,7 +1399,35 @@ useful for setting up a custom SWI table in FLASH or in RAM. When doing that,
 one must restore the original setting before returning control to the GUI or to
 another executable (the setting isn't automatically restored).<br/>
 
+#### SWI service routine
+The default SWI service routine is slightly finicky<br/>
+```arm
+push {r1-r12, lr} @ Backup SVC-mode registers
+mrs r12, spsr     @ Old CPSR in r12
+nop
 
+@ Check if we were previously in Thumb mode
+@ And adjust LR accordingly to fetch the SWI comment field
+tst r12, #0x20
+subeq lr, #2
+sub lr, #2
+
+@ Fetch the comment field
+ldrh r12, [lr]
+and r12, #0xFF
+
+@ Load function pointer for SWI handler and call it
+mov lr, #0xE0 ; Pointer to SWI table in LR
+ldr r11, [lr]
+add r11, r11, r12, lsl #2 @ r11 = &swi_table[comment]
+ldr r11, [r11] @ Get function pointer
+mov lr, pc     @ Set LR to return address
+bx r11         @ Call SWI handler
+
+@ Restore SVC regs, return from SWI service routine and restore SPSR into CPSR
+pop {r1-r12, pc}^
+```
+It's important that the SWI service routine use a 16-bit load to fetch the comment field, as most memory on the Pocketstation can't be safely read using `ldrb`. Any custom handler needs to do the same, otherwise it won't work on real hardware. Also, for emulator developers, be wary of the last `pop` as it abuses an ldm edge case (S bit set with r15 in rlist - restores registers properly and then does CPSR = SPSR)<br/>
 
 ##   Pocketstation BU Command Summary
 The Pocketstation supports the standard Memory Card commands (Read Sector,
@@ -2061,7 +2089,7 @@ checking for TTY messages after the actual upload):<br/>
 With that ID, and with the XBOO-hardware being used, the game will be started
 with with "TTY+" in R0 (notifying it that the XBOO hardware is present, and
 that it needs to install special transmission handlers):<br/>
-```
+```arm
  ;------------------
  .data?
  org  200h