BIOS Events

Event management service that reports interrupts, exceptions and device completion.

Overview

An event is either a CPU exception or an interrupt from an external device. Because events occur asynchronously with the main program, there are two ways of dealing with them: polling to see whether an event has occurred, or installing an event handler that the kernel executes automatically when the event occurs.¹ The event management service of the PS-X OS controls program execution triggered by these events.² The kernel and the libraries also deliver events of their own for file I/O and device completion.³⁴

An event is specified by two 32-bit integers called the cause descriptor and the event type. OpenEvent() takes the cause descriptor, the event type, the event mode and the address of the handler function, and returns a 32-bit event descriptor that identifies the event to the other functions.³ psx-spx calls the cause descriptor the class and the event type the spec.⁵ The event is triggered only when both values match.⁵

Event handlers execute in interrupt context on a 4K interrupt stack in the kernel's reserved memory. When a handler completes its processing it calls ReturnFromException(), which restores the registers and returns to the previous context.¹³ A handler may instead enable interrupts with ExitCriticalSection() and continue as the main flow. In this case the user must provide a stack allocated before the interrupt, and the stack is changed with SetSp().³

Event Status

An event has one of four statuses.⁶ Before it is opened its status is EvStUNUSED. OpenEvent() makes it EvStWAIT, and EnableEvent() makes it EvStACTIVE, in which the event may occur. DisableEvent() returns an EvStACTIVE or EvStALREADY event to EvStWAIT, and the previous state is not saved.⁶

The macros and their meanings are from the Run-Time Library Overview.⁶ psx-spx gives the EvCB status values as 0x0000 free, 0x1000 disabled, 0x2000 enabled and busy, and 0x4000 enabled and ready, which correspond in meaning to the four Sony statuses.⁷

Event Modes

An event has one of two modes, chosen when it is opened.⁶ With EvMdINTR the handler function is called when the event occurs and the event stays EvStACTIVE. With EvMdNOINTR no handler is called, the event becomes EvStALREADY, and the program must test for it.⁶

psx-spx gives mode 0x1000 as "execute function and stay busy" and mode 0x2000 as "no function and mark ready", which correspond to EvMdINTR and EvMdNOINTR.⁸ Because an EvMdINTR event never becomes EvStALREADY, WaitEvent() on such an event never returns.⁵

Generating and Clearing Events

DeliverEvent() switches every enabled event with the given cause descriptor and event type to EvStALREADY. Events in EvMdINTR mode have their handler called inside DeliverEvent().⁶ Clearing an event switches it from EvStALREADY back to EvStACTIVE. UnDeliverEvent() takes a cause descriptor and an event type and clears all matching events, while TestEvent() and WaitEvent() clear the one event they are given.⁶⁹¹⁰ An event must be cleared with UnDeliverEvent() before it is issued again.⁶

DeliverEvent() scans every EvCB, even when all events are disabled. A larger EVENT value in SYSTEM.CNF therefore slows down every event delivery.⁵ OpenEvent(), CloseEvent(), DeliverEvent() and UnDeliverEvent() must be executed in a critical section.^11121314

A program may define its own events with the DescUEV macro. The calls take the forms DeliverEvent(DescUEV|my_event_num, my_event_spec) and OpenEvent(DescUEV|my_event_num, my_event_spec, EvMdNOINTR, NULL).⁶

Event Functions

Sony documents CloseEvent(), EnableEvent() and DisableEvent() as returning 1 on success and 0 on failure.¹²¹⁵¹⁶ psx-spx finds that the BIOS functions always return 1 and do so even for an unused or invalid descriptor.⁵ The return value of WaitEvent() is also unreliable: it may return 0 when the event becomes ready shortly after the call.⁵ In a program with several threads, a loop that calls TestEvent() and ChangeTh() lets other threads run, whereas WaitEvent() holds the CPU until the event occurs.⁵

Event Control Block

The kernel keeps the information about an event in an event control block. The EvCB array is reached through ToT entry 4 at address 0x00000120.¹⁷³

struct EvCB {              /* event control block */
    unsigned long desc;    /* cause descriptor */
    long status;           /* status */
    long spec;             /* event type */
    long mode;             /* mode */
    long (*FHandler)();    /* function format handler */
    long system[2];        /* system reserved */
};

The structure is from the Run-Time Library Reference, and the offsets and values are from psx-spx.¹⁸⁷ An event descriptor converts to its EvCB as [0x120] + (event AND 0xFFFF) * 0x1C.¹⁹

Cause Descriptors

The cause descriptors related to the kernel library are shown below. Other events are described in the individual libraries.³

The numeric classes used by the BIOS are shown below.²⁰

psx-spx also reports classes 0xF1xxxxxx for events, 0xF3xxxxxx for user events and 0xFFxxxxxx for threads, which the BIOS does not use.²⁰

Event Types

The numeric event types are shown below.²¹

Events Delivered by the BIOS

The BIOS opens five CD-ROM events for itself, with class 0xF0000003 and types 0x10, 0x20, 0x40, 0x80 and 0x8000. The other events below are delivered by the BIOS for a game to open.⁴

The default interrupt handler also delivers class 0xF0000001 to 0xF000000B with type 0x1000. psx-spx advises against using these events, because the handler does not record which interrupt occurred and may deliver them at random.⁴²² It also reports timer 2 with the same class as timer 1.⁴

Interrupt Handling

When an interrupt or exception occurs, the kernel saves the registers in the execution TCB as the main flow context. Processing begins at address 0x00000080, which jumps to the kernel interrupt dispatcher, and the dispatcher calls the routine for the interrupt. When processing is complete, the main flow registers are restored and the main flow resumes.²³

The dispatcher keeps four priority chains of interrupt handlers and calls every handler in order. The first handler called is the first element of chain 0. Each handler checks the interrupt status register at 0x1F801070 for its own source.²² A handler that has processed and acknowledged its interrupt may call ReturnFromException() to skip the handlers of lower priority.²² The default chains are shown below.²²

Because the dispatcher does not record the incoming interrupt flags, a high priority handler may reject an interrupt that has not yet been flagged while a lower priority handler later processes or acknowledges it. psx-spx therefore recommends only one handler for each interrupt source.²² The kernel does not support nested exceptions: the registers are saved in the current TCB and the exception stack has a fixed start address, so a nested exception overwrites both.²²

HookEntryInt() installs a function that runs after the handler chains have been fully processed. It takes a structure in the setjmp() format, and the hook is called with R2 = 1 and should end with ReturnFromException(). ResetEntryInt() restores the default structure, whose RA is ReturnFromException().²²

The cautions and prohibitions for code in interrupt context are on the PS-X OS page.

References