pinkiepie.dasm16

PinkiePie Interrupt Handler is cubeOS's integrated software interrupt handler.

Software Interrupts

A software interrupt is called in assembly by INT a, where a is a "message." Upon executing an interrupt, PC and A are pushed to the stack and replaced by the value in the register IA and the message, respectively. This forces the DCPU to begin executing code at whatever address IA was set to beforehand. That code can then exit by doing, after restoring other registers, RFI 0, which disables interrupt queueing, pops A from the stack, then pops PC from the stack. That will allow the DCPU to resume the code it was executing before the interrupt was called. In large operating environments, it makes sense to set IA to a constant value at the start of operation, before any interrupts are called. This allows for interrupt handlers, which are usually provided by operating systems. The start address of the interrupt handler is placed in IA, so it is invoked whenever an interrupt is called. This allows it to handle interrupts consistently, as based on the message. It also allows software not included in the kernal (and therefore not privvy to labels,) to make function calls defined by the interrupt handler. Furthermore, advanced enough interrupt handlers can allow an operating system to support multitasking.

Initialization

To initialize PinkiePie, use pih.init. Changes to IA can be reset by performing this call again.

pih.init

Does IAS pih to direct any interrupts to the interrupt handler.

Interrupt Handler

The interrupt handler is located at the label pih. The subroutine pih.init makes this the active interrupt handler. PinkiePie's interrupt handling process is as follows.

1. Trigger interrupt queueing with IAQ 1
2. Drops the interrupt and returns with RFI if the message is greater than 128.
3. Looks up the message in pih.cmdtable.
4. If the value is 0xFFFF, then return with RFI.
5. Push B and C to the stack, so they will be preserved.
6. JSR to the value returned by the table.
7. Pop C and B from the stack, and do RFI.

If the interrupt is actually an API call, (i.e. A call made to the OS with arguments,) then the receiving subroutine should note that the arguments A, B, and C will enter the subroutine unchanged. In order to return a value in A, however, the subroutine must exit with pih.return. X is the location of the subroutine when it enters.

Messages

Messages 0-63 are reserved for calls reagarding the OS. Messages 64-127 are reserved for programs.

10: Reserve Heap Space

Reserves the amount of words in A on the heap, and returns the location of the reserved memory in A.

11

pih.return ()

Exits the interrupt handler, returning the value that is currently in A in the register A (avoiding clearing it during the return process.)

syntax SET PC, pih.returnVal to exit

pih.chOSMsg (msg, location)

Redefines the OS (msg < 64) interrupt message to point at location.

modifies A

returns msg

pih.newMsg (location)

Finds the first unused message greater than or equal to 64, but less than or equal to 127. It then makes location the location to jump to when that interrupt is triggered.

returns the first open message