ETC Library (libetc)

Provides functions for callbacks, vertical sync and the video mode.

Overview

The ETC Library (libetc) controls callbacks. All callback functions used in the other libraries are managed by libetc, and the library also contains some controller functions. It is one of the Controller/Peripherals libraries, together with libpad, libtap and libgun.¹²

A program that uses libetc links with libetc.lib and includes libetc.h.²

This library is part of the run-time library that Sony distributed with the Psy-Q development tools.³

Callbacks

Many functions run in parallel in the background, such as drawing, transfers to the sound buffer and reads from the CD-ROM. They are called non-blocking functions, because they do not block the CPU from other work. A callback is a function that runs when such a function ends. The end generates an interrupt, the program jumps to the address registered as the callback and returns to the point of interruption when the callback returns.²

A callback runs on its own local stack, so that the original state is restored when it returns. All interrupts are prohibited inside a callback, which is therefore a critical section. The following callbacks are among those supported:⁴

Callback Initialization

ResetCallback() creates the local stack of the callbacks and sets every callback pointer to NULL. The initialization functions of most libraries call ResetCallback() themselves, so an application does not usually call it. The following functions call it:⁴

StopCallback() halts the callbacks temporarily, and a second ResetCallback() starts them again. The pointers registered before StopCallback() are not kept.⁴

Callback Pointers

A callback records one function pointer at a time, and setting a new function discards the previous pointer. An application that needs several functions on one callback must therefore call them from its own function. A temporary callback saves the previous pointer and restores it afterward.⁵

All callbacks share one local stack, so a callback cannot start inside another callback. A callback requested while another runs waits until the running callback ends, although a timer callback on the root counter interface has priority over the others.⁵⁶

When a library is initialized it registers default callbacks. For example, CdInit() registers a CdSyncCallback() function that delivers an event when a CD-ROM primitive command ends, so the end of a command can be found through an event handler. A new callback cancels the default callback, and the event is then no longer delivered.⁶

Callback Context

Callbacks usually run in the callback context, but not always. When a library function detects the interrupt itself, it may run the callback in the foreground to avoid a needless context switch. For example, a very small LoadImage() can complete before the function returns, and the DrawSyncCallback() function then runs in the foreground. Which context a callback runs in therefore depends on the bus, the CPU and the subprocessors at that moment and cannot be predicted. CheckCallback() returns non-zero in the callback context and zero in the normal context.⁷

Process Switching

Process switching transfers control to a program in a different module. A child process started by a resident parent is one case. The start of PSX.EXE is also a process switch from the OS to the application. When the callback table is not switched, interrupts in the child call the callbacks of the parent. The results are unpredictable.⁸⁹

The parent therefore closes all events with CloseEvent(), halts the callbacks with StopCallback() and jumps to the child with Exec(). The child calls ResetCallback(), initializes its libraries again with CdInit(), ResetGraph() and the others, sets its own callbacks and opens its events. The same steps are needed when control returns to the parent. Because the OS treats the application as its first child, every application calls ResetCallback() at its start.⁹

Controller

libetc reads the standard controller with three functions. PadInit() initializes it, PadRead() returns its state and PadStop() ends the reads. The controller is scanned once each vertical blank, so PadRead() returns the most recent state at any time. Its 32-bit result holds controller A in the upper 16 bits and controller B in the lower 16 bits. This interface works only with the standard controller, and the Reference marks these three functions for prototyping only.^6101112

Video Mode

SetVideoMode() declares the current video signal mode, and the related libraries then work in that mode. NTSC is the default. SetVideoMode() is called before all other library functions.¹³

Vertical Sync

VSync() waits for the next vertical blank or returns the vertical blank counter, and VSyncCallback() defines a function executed in each vertical blank period. The root counter interface keeps its own list of callback functions with no set order, so a program that needs several functions in a fixed order calls them from one VSyncCallback() function.¹⁴¹⁵¹³

VSync interrupts occur at the start of the vertical blank, so drawing starts at the start of the callback. When a sound driver such as SsSeqCalledTbyT() is called before DrawOTag() in the same callback, the drawing starts late and may not finish within the blank. Because DrawOTag() is non-blocking and returns at once, calling it first lets the drawing run in parallel with the sound driver.¹³⁸

Stack Pointer and Exec

libsn.lib sets the stack pointer and clears the data areas before main() is called, and on the DTL-H2000 it sets the stack from the DIP switch settings. A program started with Exec() that must return to its caller cannot keep this setup, since it would destroy the stack of the caller. Such a program is linked with NONE.OBJ, which makes no stack settings, in place of 2MBYTE.OBJ or 8MBYTE.OBJ.⁸

Functions

In the tables below, Introduced is the run-time library version that added the item.¹⁶

libetc has the following functions:¹⁶

References