PS-X OS

Kernel of the PlayStation that provides its services as C functions.

Overview

The PS-X OS was developed for the R3000, which is the CPU of the PlayStation. Its design concept is to give the developer of game programs an environment in which programs can be controlled with interrupts. Based on this concept, the kernel is provided as the aggregate of the services (subroutines) that control the R3000 and the PlayStation hardware, and each service is provided as a C language function.¹² The kernel is stored in the 512KB OS ROM, which programmers call the BIOS.³

The R3000 interrupt processing is complicated, so the OS uses a substitute dispatcher with a simple interface and low overhead.² To place emphasis on application performance, the OS uses at most 64K bytes of RAM and as little CPU time as possible. The OS system tables are disclosed so that applications can extend the OS and read its internal data.¹² For greater speed the OS also leaves out the checks of prohibited operations that other operating systems make. Consequently the application must perform these checks itself, and careful programming makes higher tuning possible.¹²

The OS is an environment for game program developers. It therefore has no interface for the user to operate the hardware directly, apart from the debug monitor in the debugging environment, and the application must provide the user interface.⁴⁵

Tasks

The PS-X OS is a multi-tasking operating system that can carry out several processes asynchronously. Multi-task control suits the control of the CD-ROM drive, a comparatively slow device, and the playing of background music.⁶ Immediately after the OS starts, however, it is in single task mode, and a program that does not start more threads stays in single task mode. A programmer does not have to use the multi-tasking feature at all.⁶⁷ The threads page describes thread management.

File System

The file system of the PS-X OS takes as a premise that files are on CD-ROM, the medium on which applications are supplied. It is based on ISO 9660 level 1, which is an international standard.⁸ The file system is accessed through a device driver, which allows several file systems to coexist and spares the application low-level file handling.⁶ A file name is an 8-character base name and a 3-character extension separated by a period, the same format as MS-DOS, and 1-byte katakana and kanji cannot be used.⁸ The file I/O page describes the devices and the file functions.

Memory Map

The space that a program uses is called logic space. It is expressed by a 32-bit address and mapped onto physical space several times, and access to a logic address with no physical memory behind it raises a bus error.⁸⁹ The interface registers of the peripheral devices are also mapped in logic space as memory mapped I/O. Memory may be accessed in units of 1 to 4 bytes, but an interface register must be accessed in its own unit size, and any other size raises a bus error.⁹ The memory map page lists the segments.

The kernel uses the first 64K bytes of memory, and the addresses that the user may use begin at 0x00010000.¹⁰ Logic addresses from 0x80000000 run through the I-cache and addresses from 0xA0000000 do not. Sony therefore recommends placing programs in segment B from 0x80000000.¹¹

Library Components

The PlayStation libraries form two levels according to their relation to the OS. A program may use either level as needed, and with some exceptions may use both at the same time.¹² The libraries are summarized below.¹³¹⁴¹⁵

The PlayStation Operating System manual gives a shorter list of libgpu, libgte, libgs, libpress, libstr, libsnd, libapi and libetc, and it describes libgpu as "CPU basic operation".¹⁶

Services

The services of the PS-X OS are called application programmer interfaces (API), and a program that calls the OS must link their function libraries. All PlayStation features are covered by the API.¹⁷ Programs that use the kernel services link libapi.lib and include libapi.h and kernel.h.¹⁸ The API has the following services.¹⁷¹⁶

All file control on the PlayStation is performed with the I/O management service.¹⁷ The function tables are on the BIOS page.

Descriptors

When a program works with system resources such as files or threads, the kernel provides descriptors to refer to them. A descriptor is an unsigned 32-bit integer.¹⁹

The classifications are defined as macros in kernel.h.¹⁹

A program obtains a descriptor from the Open() function of each resource, uses it to specify the resource in every operation, and releases it with the matching Close() function after use.¹⁹ For example, the default thread has the descriptor DescTH|0x0000 = 0xFF000000.²⁰

Critical Sections and Interrupt Context

Any function that modifies data within the kernel must be executed with interrupts inhibited, and such a section of code is called a critical section. Interrupts are inhibited immediately after the PlayStation starts until ResetCallbacks() enables them, after EnterCriticalSection() until ExitCriticalSection(), and at the start of an event handler.²¹ The syscalls page describes these functions.

The normal execution of a program is called its main flow. When an interrupt or exception occurs, the kernel saves the registers in the execution TCB as the main flow context, and the state after saving is called the interrupt context. Processing then begins at 0x00000080, which jumps to the kernel interrupt dispatcher, and when the interrupt processing is complete the main flow registers are restored.²¹ Event handlers execute in interrupt context on the interrupt stack, and callbacks on the callback stack declared in libetc.²¹

Code in interrupt context must finish in the shortest possible time, because halting interrupts for long may adversely affect operation. Functions that generate internal exceptions, such as ExitCriticalSection(), destroy the main flow context, which the thread management service can prevent by changing the execution TCB. ReturnFromException() inside an event handler returns to the main flow but breaks off the interrupt dispatcher, and Sony therefore restricts it to error management.²¹

Code in interrupt context must not call functions that use internal interrupts, because those functions cannot complete while interrupts are not generated. It must not call non-reentrant functions that the main flow may also call, and most library functions, including the kernel services, are not reentrant. A callback function must not call ReturnFromException().¹⁰

Callbacks

Libraries that handle devices with DMA, such as libgpu and libsnd, have functions that register callback functions in the kernel. A callback is called automatically when a DMA transfer is completed, and it runs in callback context on the callback stack. The program can complete the transfer processing by setting a flag in an external variable and issuing an event.²¹

Root Counters

The root counter management service provides counting for time restrictions and timing adjustments in game programs.¹⁶¹⁰ A counter counts up from zero to a 16-bit target value. At the target it generates an interrupt (each counter can be masked), clears to zero and starts counting again. The values read by polling therefore run from 0 to the target value minus 1.¹⁰ The vertical synchronization counter has its target fixed at 1 and therefore generates an interrupt at each vertical blank.¹⁰ The counters are named by macros.¹⁰

The two Sony manuals describe the counters differently, and the table gives both.¹⁰¹⁶ One tick of the CPU system clock is about 0.03 microseconds. The counts for the graphics display have the following timings.²²

The root counter uses the hardware counting function. Counting therefore continues while interrupts are disabled, and StopRCnt() does not stop counting: it only stops the counter from generating interrupts, and StartRCnt() only allows them.²² The mode of each counter is set by OR-ing the macros below.²²

With RCntMdGATE a counter counts only while its gate condition holds. RCntCNT0 does not count during horizontal blanking, RCntCNT1 does not count during vertical blanking, and RCntCNT2 and RCntCNT3 have no gate condition.²³

All counters are stopped or free running immediately after the kernel starts, so a counter must always be initialized before use. A counter interrupt cannot occur within a critical section.²³ The kernel itself uses root counter 3 to read the controller buttons, and the buttons cannot be read while root counter 3 is stopped or uninitialized.²³

The root counter and the event management service together detect the start of the vertical blanking period. The program opens an event on RCntCNT3, sets the counter with target 1, and starts it. The sample below shows the calls.²⁴

Sample()
{
    unsigned long EV;
    EnterCriticalSection();
    EV = OpenEvent(RCntCNT3, EvSpINT, EvMdNOINTR, NULL);
    EnableEvent(EV);
    SetRCnt(RCntCNT3, 1, RCntMdINTR);
    StartRCnt(RCntCNT3);
    /* initialization of controller */
    while (1) {
        WaitEvent(EV);
        /* per-frame processing */
    }
}

Controller Features

libapi provides a low-level interface to the controllers. The application processes the received data directly, and the type of each controller is identified dynamically.²⁵ InitPAD() registers two receive buffers and their maximum lengths, and StartPAD() begins reading the controllers on each vertical blank interrupt. The presence of a controller and its state are then found by testing the buffer contents.²⁵

The first byte of a buffer is the receive result, which is 0x00 for success. The upper 4 bits of the second byte are the terminal type, and the lower 4 bits are half the number of data bytes that follow from the third byte on.²⁶²⁷ The terminal types are shown below.²⁶

Bytes 2 and 3 hold the button status, in which a bit is 1 for released and 0 for pushed. For the 16-button controller the bits of the button status are assigned as shown below.²⁷

The table leaves out bits D7 to D4, which hold the four symbol buttons.²⁷

The Analog Controller adds R3 at D10 and L3 at D9. The analog devices report stick positions from 0 through 128 to 255 in bytes 4 to 7, and the mouse reports X and Y movement from -128 to 127 in bytes 4 and 5.²⁶²⁸²⁷

Memory Allocation

There are three systems of memory allocation. InitHeap() and the libc malloc(), calloc(), realloc() and free() call the ROM routines. InitHeap2() and malloc2() are a RAM-based version, and InitHeap3() and malloc3() are a faster RAM-based version added in Library 4.0.²⁹³⁰ The ROM malloc has a bug in which an area cannot be completely released by free(). Because the ROM cannot be corrected, the bug was fixed in malloc2 and the ROM version was left for compatibility.³⁰ All three allocate blocks by first fit.³⁰

The C library heap functions are part of the OS, but the OS does not initialize the heap, because the game program developer manages all available memory. A program first calls the heap initialization function with the start address and size of the heap.²⁴ InitHeap() must be executed in a critical section, and some of the given size is used for overhead.³¹ InitHeap3() takes a size that is a multiple of 8 bytes and discards any remainder.³²

Programming Notes

Overlay processing takes the form of executing a child process from a resident module. The OS drives the hardware and starts the file to be executed, but for an overlay the application must do this.⁷ The PlayStation has no character generator and provides no fonts for text display, so the application must draw character strings as part of its graphics.⁷ The kernel ROM does contain a kanji font. The BIOS page describes it.³³

The entry point of an execution file may be any function given at link time. When none is given, main() is used, and the entry function cannot take an argument.²⁴ A program needs a stack pointer value as well as a start address, because a stack pointer that holds an address that cannot be accessed causes a bus error.³⁴

Immediately after starting, standard output is allocated to file descriptor 0 and standard input to file descriptor 1 on RS232C channel 0 (device name tty00). The port runs at 8-bit characters, 1 stop bit, no parity and hardware flow control.³⁴ The Run-Time Library Overview instead assigns the standard I/O stream to a NULL device on the game unit and standard output to Debug Message Window #0 in the development environment.³⁵

The scratchpad (the S segment) is the fastest memory for data. Sony advises placing often-used arrays, global variables and functions there, using -O2 or -O3 for the higher I-cache hit rate, and keeping C functions to 4 or fewer arguments so that all are passed in registers.²⁴³⁶ A transfer between registers takes 1 cycle and an access to the scratchpad also takes 1 cycle. An access to data in main memory takes 5 cycles.³⁷

References