Kernel Library (libapi)

Provides an interface between applications and the PlayStation OS.

This is an old revision of this page, as edited by RemmyLee at 02:58, 23 October 2026. Edit this revision | Latest revision

Overview

The Kernel Library (libapi) provides the interface (API) by which applications control the basic parts of the PlayStation OS. These parts include the CPU and other hardware. Its services are root counter processing, event processing, thread processing, I/O processing, module processing, the controller and others.¹

A program that uses libapi links with libapi.lib and includes libapi.h and kernel.h.¹

System Designation File

SYSTEM.CNF is a system designation file. It reserves memory for the stack, the tasks and the events, and the kernel reads it at boot. Each line has the form KEYWORD = CONTENT. Keywords are uppercase one-byte characters with a space on either side of the equal sign, and when a keyword appears twice the first line takes precedence. The keywords are the following:¹

The numbers of task and event control blocks must satisfy TCB x 192 + EVENT x 32 + 544 < 4096.¹

System Table Information

The task control blocks and the event control blocks are two of the tables that the kernel uses. To access them in a uniform way, the ToT (Table of Tables) structure at address 0x00000100 describes them, and the head member of each entry points to the actual table. The entries are the following:²

A TCB holds the information of one task, and the TCBH structure points to the TCB that is executing now. A program can therefore find the executing TCB through entry 1 of the ToT.²

Descriptors

The kernel refers to resources such as files and threads by descriptors. A descriptor is an unsigned 32-bit integer whose bits 31 to 24 hold the descriptor class, bits 23 to 16 are reserved and bits 15 to 0 hold the number of the entry in the kernel table. The classes are defined in kernel.h:³

A program obtains a descriptor from the Open function of the resource, such as OpenTh(), open() or OpenEvent(), uses it to name the resource, and releases it with the matching Close function.³⁴

Callbacks

Libraries such as libgpu and libsnd that drive devices by DMA register callback functions in the kernel, which are executed after an event occurs. A callback runs in the callback context on its own callback stack, which is declared in libetc and lies in the application data area. The callback is called automatically when a DMA transfer completes, and it can report the end of the transfer by setting a flag or issuing an event.⁴

Critical Sections

Any function that modifies data in the kernel must run with interrupts inhibited, and such a section of code is called a critical section. Interrupts are inhibited right after system start until ResetCallback() enables them. EnterCriticalSection() inhibits them and ExitCriticalSection() enables them again. They are also inhibited at the start of an event handler, which returns to the original context with ReturnFromException().⁴

Interrupt Context

The normal execution of a program is its main flow. When an interrupt or exception occurs, the registers are saved in the execution TCB as the main flow context, and processing jumps to address 0x00000080, which holds the jump to the kernel interrupt dispatcher. When the interrupt has been processed the main flow context is restored.⁴

Event handlers and callbacks run in this interrupt context. Event handlers use the interrupt stack and callbacks use the callback stack. Halting interrupts for a long time affects the whole PlayStation. Such code is therefore designed to complete in the shortest possible time. It does not call functions that depend on interrupts, non-re-entrant functions that the main flow may call, or ReturnFromException() inside a callback.⁴⁵

Kernel Reserved Memory

The kernel uses the first 64 KB of memory. The addresses that the user may use therefore begin at 0x00010000.⁵

Root Counters

The root counters provide time limits and timing adjustments for game programs. A counter counts up from zero to a 16-bit target value. At the target it generates an interrupt, which can be masked, clears itself to zero and counts again, so the values that can be read run from 0 to the target value minus 1. The vertical synch counter has a fixed target of 1 and therefore interrupts at each vertical blank. The counters are the following:⁵

One system clock tick is about 0.03 microseconds. The display timings are the following:⁶

N depends on the display width:⁶

The root counters use the hardware counting function, so the count continues while interrupts are disabled. StopRCnt() only stops the interrupts of the counter while the count goes on, and StartRCnt() only allows the interrupts. The mode of each counter selects interrupt or polling (RCntMdINTR, RCntMdNOINTR), the clock source and whether a gate condition applies (RCntMdGATE). With the gate, RCntCNT0 counts only outside the horizontal blank and RCntCNT1 only outside the vertical blank.⁶⁷

All counters are stopped or free running right after the kernel starts, so a program always initializes a counter before it uses it. A counter interrupt cannot occur inside a critical section. The kernel itself reads the controller buttons on root counter 3, and the buttons cannot be read while that counter is stopped or uninitialized.⁷

Events

An event is a CPU exception or an interrupt from an external device. Because an event occurs asynchronously with the main program, the program either polls for it or installs an event handler that the kernel runs when it occurs. Handlers run in interrupt context on a 4 KB interrupt stack in the kernel area, and GetSysSp() returns the top address of that stack.⁷

An event is specified by two 32-bit integers called the cause descriptor and the event type:⁸

OpenEvent() installs a handler from the cause descriptor, the event type, the event mode and the address of the handler. It returns a 32-bit event descriptor, which identifies the event to EnableEvent() and the other functions, and the kernel keeps the event in an event control block. When the event occurs the registers are saved and the handler runs. It ends with ReturnFromException(), which restores the registers and returns to the previous context.⁸

An event has one of four states. It is EvStUNUSED before it is opened, EvStWAIT after OpenEvent() and EvStACTIVE after EnableEvent(), when it may occur. DisableEvent() returns it to EvStWAIT:⁹

With the mode EvMdINTR a handler is called when the event occurs and the event returns to EvStACTIVE. With EvMdNOINTR no handler is given, the event goes to EvStALREADY and the program must test it. DeliverEvent() generates an event from a cause descriptor and event type. UnDeliverEvent() or TestEvent() clears it from EvStALREADY back to EvStACTIVE. A program defines its own events with the DescUEV class.⁹¹⁰

Threads

Threads give an application several flows of control, and the context changes when a switching function is called. The context of a thread is the complete contents of the registers, and a TCB stores it. When the kernel starts, the TCB array is allocated and element zero is opened as the execution TCB.¹⁰

OpenTh() opens further TCBs, whose status becomes TcbStACTIVE, and ChangeTh() runs one of them. ChangeTh() issues a software interrupt, saves its own context in the previous TCB, links the new TCB into the task status queue and resumes from it when the dispatcher ends. The context at an interrupt is stored in the TCB being executed and stays there until the next interrupt.¹⁰¹¹

I/O Management

The kernel gives low-level access to files and logical devices. The structures it uses for input and output are defined in sys/file.h. Each device has a block size, and all data access is in multiples of it, so a fraction of a block in a request is discarded. The devices are the following:¹²

The CD-ROM file system follows level 1 of ISO-9660 and has a block size of 2048 bytes. A file name is a base name of 8 characters and an extension of up to 3, with a version number, in capital letters, digits and underscore. Directories are at most 8 levels deep, and all sectors of a file are contiguous. A directory list is read only as far as it fits in one 2048-byte sector, which allows up to 45 directories and 30 files per directory with 8.3 names.¹²

The Memory Card file system has the device name buXY, where X is the port and Y the extension connector number. It has no directories, its file names are ASCII strings of up to 20 bytes without an extension, and its block size is 128 bytes. libcard mounts and initializes it.¹³

File descriptors 0 and 1 are the standard I/O stream. On the game unit both are a NULL device, and in the development environment standard output goes to Debug Message Window #0.¹³

Module Control

libapi loads and executes application modules in the PlayStation EXE format. An execution file contains code and data linked to fixed addresses, a start address, an initial gp value, and the start address and size of the initial data area. It begins with a header of 2048 bytes. The text section and the data section follow in multiples of 2048 bytes.¹³

The EXEC structure in the header holds the start address pc0 and the initial gp0 together with the address and size of the text and initialized data. It also holds the uninitialized data area (b_addr, b_size), which Exec() clears, and the stack area (s_addr, s_size). Exec() sets the stack pointer to s_addr + s_size unless s_addr is zero, so the stack must be defined explicitly or the current context is used.¹³¹⁴

Controller

libapi provides a low-level interface to the controllers, in which the application processes the received data directly and identifies each controller type. InitPAD() sets up two receive buffers with their maximum lengths, and StartPAD() starts reading at each vertical blank interrupt. The presence and state of a device are found from the contents of the buffer.¹⁴

The first byte of the buffer is 0x00 on success. The upper 4 bits of the second byte hold the terminal type, and the lower 4 bits hold half the number of bytes received:¹⁵

Bytes 2 and 3 hold the button status. A button bit is 1 when released and 0 when pressed. A mouse adds X and Y movement from -128 to 127, an analog joystick or analog controller adds four stick positions from 0 to 255 with 128 at center, and a Namco gun adds 16-bit X and Y positions. A Multi Tap returns 0x80 in byte 1 and then the data of ports A to D at offsets 2, 10, 18 and 26.¹⁵¹⁶¹⁷

Kanji Fonts

The kernel ROM includes 16 x 16 dot bitmap kanji fonts. The characters are 15 x 15 dots and cover the JIS first standard kanji and non-kanji in Shift-JIS code. The font data is not stored consecutively. Krom2RawAdd() therefore returns the ROM address of the pattern of each character, which is read directly, with the upper left byte first and the most significant bit on the left.¹⁷¹⁸

Memory Allocation

There are three systems of memory allocation, all of which allocate by first fit. The malloc system calls the ROM routines and has a bug in which free() cannot release the whole area, which cannot be corrected in ROM. The malloc2 system is RAM-based and fixes the bug, and the malloc3 system, added in library 4.0, is a faster RAM-based version:¹⁸¹⁹

Structures

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

libapi has the following structures:²⁰

Functions

libapi has the following functions:²¹

References