Playstation®2 Ee Library Overview Release 3.0
Playstation®2 Ee Library Overview Release 3.0
Release 3.0
Sif Libraries
© 2003 Sony Computer Entertainment Inc.
Publication date: December 2003
The PlayStation®2 EE Library Overview - Sif Libraries manual is supplied pursuant to and subject to the
terms of the Sony Computer Entertainment PlayStation® license agreements.
The PlayStation®2 EE Library Overview - Sif Libraries manual is intended for distribution to and use by only
Sony Computer Entertainment licensed Developers and Publishers in accordance with the PlayStation®
license agreements.
Unauthorized reproduction, distribution, lending, rental or disclosure to any third party, in whole or in part,
of this book is expressly prohibited by law and by the terms of the Sony Computer Entertainment
PlayStation® license agreements.
Ownership of the physical property of the book is retained by and reserved by Sony Computer
Entertainment. Alteration to or deletion, in whole or in part, of the book, its presentation, or its contents is
prohibited.
The information in the PlayStation®2 EE Library Overview - Sif Libraries manual is subject to change
without notice. The content of this book is Confidential Information of Sony Computer Entertainment.
and PlayStation are registered trademarks of Sony Computer Entertainment Inc. All other trademarks
are property of their respective owners and/or their licensors.
Summary Table of Contents
About This Manual v
Changes Since Last Release v
Related Documentation vi
Typographic Conventions vi
Developer Support vi
Chapter 1: Standard IOP Services 1-1
Chapter 2: SIF System 2-1
• The figure in the "Overview" of "SIF RPC API" was changed and the description of the completion
of the service function was added to "Usage Procedure".
• “Differences in Structure Between RPC and MRPC" was deleted from "Support for Multithreading
in SIF RPC" and an "Overview" was added.
• A case was added to the description of cases where re-entry occurs from NOWAIT state in "How
RPC Re-entry Works" in the "Notes on RPC Re-entry" section.
• The description of preventing RPC re-entry in "Preventing RPC Re-entry" in the "Notes on RPC
Re-entry" section was changed and the description of library function in "Library Functions That
Use RPC" was also changed.
• The description of libraries in "Specifying Thread Priorities for IOP Modules" in the "IOP Module
Replacement" section was changed.
Related Documentation
Library specifications for the IOP can be found in the PlayStation®2 IOP Library Reference manuals and the
PlayStation®2 IOP Library Overview manuals.
Note: the Developer Support Web site posts current developments regarding the Libraries and also
provides notice of future documentation releases and upgrades.
Typographic Conventions
Certain Typographic Conventions are used throughout this manual to clarify the meaning of the text:
Convention Meaning
courier Indicates literal program code.
italic Indicates names of arguments and structure
members (in structure/function definitions
only).
medium bold Indicates data types and structure/function
names (in structure/function definitions
only).
blue Indicates a hyperlink.
Developer Support
Library Overview
Standard IOP services include functions used to load IOP modules from the EE side, manage the IOP
heap, etc. These functions use the SIF RPC as an extension to the EE Kernel. They can be broadly divided
into the two categories shown below.
Related Files
The following header file is needed to use the standard IOP services API.
Table 1-1
Category Filename
Header file sifdev.h
• sceSifQueryBlockTopAddress()
• sceSifQueryMaxFreeMemSize()
• sceSifQueryMemSize()
• sceSifQueryTotalFreeMemSize()
• sceSifSearchModuleByAddress()
• sceSifSearchModuleByName()
• sceSifStopModule()
• sceSifUnloadModule()
Non-RPC Functions
The following functions do not use sceSifBindRpc() / sceSifCallRpc(). They can be used without concern for
RPC re-entry issues (this does not mean that the functions themselves are re-entrant).
• sceSifLoadFileReset()
• sceSifAddRebootNotifyHandler()
• sceSifRemoveRebootNotifyHandler()
• sceSifSetRebootNotifyBuffer()
• sceSifSyncIop()
Other Functions
Although the following function is not directly related to RPC re-entry, it does perform SIF reinitialization,
and therefore, will close any RPC connections. As a result, if you use this function, you cannot use other
functions that perform transfers via the SIF until you call a function like sceSifSyncIop() to confirm that this
function has completed operations.
• sceSifRebootIop()
Both the EE and IOP sides are provided with almost identical APIs at three levels, namely SIF DMA, SIF
CMD, and SIF RPC (Remote Procedure Call).
Overview
The SIF DMA API is the lowest level API of the SIF system. It provides functions for performing DMA
transfers to the other side's memory, bidirectionally between the EE and IOP. It also provides functions for
checking the transfer status.
Figure 2-2
The SIF DMA receiving channels for both the EE and IOP are normally open, and DMA transfers to the
other side's memory can be executed asynchronously (without being concerned with the status of the
other side). However, when the EE is on the receiving end of a transfer, and a DMA termination interrupt is
generated, the EE-side receiving channel will be closed. In this case, a SIF CMD can be used to reopen the
receiving channel.
Related Files
The following files are required to use the SIF DMA API.
Table 2-1
Category Filename
Header file sif.h
EE Library libkernl.a
IOP module iop.ilb
Overview
The SIF CMD (Command) API, which is located at a level above the SIF DMA API, is used to send
command packets that execute functions (command functions) that were previously defined and registered
locally on either the EE and IOP, from the other side. For example, if a command function for changing a
variable of an IOP application was registered on the IOP, the SIF CMD API would permit this operation to
be performed from the EE. Likewise, by registering a command function on the EE, executing an instruction
in an IOP application can cause an action to occur on the EE. The EE and IOP have nearly identical APIs.
Figure 2-3
The SIF CMD API can be used at the same time as the SIF DMA API.
Related Files
The following files are required to use the SIF CMD API.
Table 2-2
Category Filename
Header file sifcmd.h
EE Library Libkernl.a
IOP module iop.ilb
Usage Procedure
First, sceSifInitCmd() is called by both the EE and IOP for initialization. The internal operations performed at
this time are as follows.
1. Allocate a receive buffer (8 qwords) and convert its address.
2. Register the SIF CMD interrupt handler.
3. Initialize software registers.
Next, at the processor that will be the receiver, call sceSifSetCmdBuffer() to register a command function
registration buffer (table). Also, call sceSifAddCmdHandler() to register a command function. A command
function is executed as an interrupt function. To register several command functions, repeatedly call
sceSifAddCmdHandler() the required number of times.
Then, when necessary, prepare an appropriate command packet and call sceSifSendCmd() to send it to
the receiving processor. The internal operations performed at this time are as follows.
1. The command packet is transferred to the receive buffer on the other side and generates a
transfer termination interrupt.
2. The SIF CMD interrupt handler searches the receive buffer on the receiving side.
3. If a command packet is found in the receive buffer, the packet is analyzed and the appropriate
command function is executed in the interrupt handler context.
If no data is found in the receive buffer, processing returns directly from the interrupt handler.
Sample Programs
Sample programs that use the SIF CMD API can be found in /sce/ee/sample/sif/sifcmd and
/sce/iop/sample/sif/sifcmd.
Overview
The SIF RPC (Remote Procedure Call) API is a mechanism for building a simple client/server model on top
of the SIF CMD API. For example, a function that was registered on the IOP can be called from an EE
application and the results can be returned to the EE application.
Figure 2-4
Since nearly identical APIs are provided for both the EE and IOP, the EE can also be the server and the IOP
can be the client, which is the opposite to the situation shown in the above figure. Both sides can also play
both roles at the same time.
In addition, the SIF RPC API can be used at the same time as the SIF DMA API and the SIF CMD API.
Related Files
The following files are required to use the SIF RPC API.
Table 2-3
Category Filename
Header file sifrpc.h
EE library libkernl.a
IOP module iop.ilb
Usage Procedure
The procedure to follow when using the SIF RPC API is summarized as follows.
Figure 2-5
Server-side Client-side
Synchronize Initialize
Initialize
sceSifInitRpc sceSifInitRpc
Register service
functions
sceSifSetRpcQueue
sceSifRegisterRpc
Get service
information
sceSifBindRpc
Service loop
sceSifRpcLoop
Issue Request
Get Request sceSifCallRpc
sceSifGetNextRequest
Execute service
functions
sceSifExecRequest
When there is no request from the client while executing the server-side service loop, the thread calling the
service loop will enter SLEEP state until a request is received.
With the client-side functions sceSifBindRpc() and sceSifCallRpc(), the thread calling these functions will
wait for a semaphore or an event flag until there is a response from the server (this is known as
synchronous calling or WAIT execution). This call can also be performed without a WAIT state. In this case,
completion of the operation can be checked with sceSifCheckStatRpc() (this is known as asynchronous
calling or NOWAIT execution).
The completion of the service function is reported from the server using a SIF CMD. Note that calling the
sceSifCallRpc() function with interrupts disabled or from inside of an interrupt handler can result in a hang..
Sample Programs
Sample programs that use the SIF RPC API can be found in /sce/ee/sample/sif/sifrpc and
/sce/iop/sample/sif/sifrpc.
Overview
libmrpc incorporates support for multithreading into the general concept of SIFRPC (RPC) and provides an
MSIFRPC (MRPC). With multithreading, multiple threads on the EE can bind to the same service function
enabling each thread to call the function at arbitrary times.
In RPC, a service is performed on the server by a registered thread for a previously registered function. In
other words, even when multiple clients have invoked Bind, all processing is still performed by one thread
and the individual clients are not distinguished from each other. An Unbind is not performed since no
thread is created or deleted.
However, with MRPC, the registered thread itself does not perform the service. Instead, when a Bind
request arrives on the server, the server creates one thread, and that thread executes the registered
function. As a result, processing is performed by a different thread for each client that issued Bind, and
multiple threads can execute simultaneously on one server.
The default values for the priority and stack size of the threads that perform the service and of the receive
data buffer size are 32, 0x2000, and 0x800, respectively.
These values can be specified by using sceSifMBindRpcParam().
A thread that performs a service is deleted with an Unbind request.
MRPC uses RPC buffers when Bind is performed. Up to 32 simultaneous Bind requests are supported.
Related Files
The following files are required to use libmrpc.
Table 2-4
Category File Name
Library file libmrpc.a
Header file libmrpc.h
IOP module msifrpc.irx
Sample Programs
For sample programs that use libmrpc, please see the libnet library (network library) whose source code is
publicly available, as well as the libmrpc function reference which contains notes about using the functions.
Programming Notes
Transfer units
Carefully note the units used for the size of the MSIFRPC buffer and the units used for the size of data to be
transferred.
Although the buffer is 16-byte aligned on the EE, and 4-byte aligned on the IOP, this does not take the
cache into account. When considering the cache, 64-byte alignment should be used by applications. This
means that the starting address of the MSIFRPC buffer should be 64-byte aligned, and the buffer area
should be allocated in 64-byte units. In addition, the transfer data size should also be in 64-byte units.
#include <eekernel.h>
#include <eeregs.h>
#include <sifdev.h>
#include <stdio.h>
#include <libcdvd.h>
#ifdef CDROM
#define IOPRP "cdrom0:\\MODULES\\"IOP_IMAGE_FILE";1"
#else
#define IOPRP "host0:/usr/local/sce/iop/modules/"IOP_IMAGE_file
#endif
int main()
{
#ifdef REPLACE
#ifdef CDROM
sceSifInitRpc(0);
sceCdInit(SCECdINIT);
#else
sceSifInitRpc(0);
#endif /* CDROM */
while (!sceSifRebootIop (IOPRP)); /* IOP reboot module
substitution */
while( !sceSifSyncIop() ); /* Wait for completion */
#endif /* REPLACE */
sceSifInitRpc(0);
sceSifLoadFileReset();
sceFsReset();
#ifdef CDROM
sceCdInit(SCECdINIT);
sceCdMmode(SCECdCD); /* Media: CD-ROM */
#endif
The IOP_IMAGE_FILE and IOP_IMAGE_file macros used in the program define the IOP replacement
module from Release 1.6 in sifdev.h as shown below. This filename is updated every release.
<sifdev.h>
#define IOP_IMAGE_FILE "IOPRPXX.IMG"
#define IOP_IMAGE_file "ioprpXX.img"
This allows the specification method shown below to be used when replacing an IOP default module and
makes modification unnecessary when only a library update is performed.
Example:
#ifdef CDROM
// Starting up from a CD/DVD-ROM disk (access IOPreplace module
on the CD/DVD-ROM)
while (!sceSifRebootIop ("cdrom0:\\" IOP_IMAGE_FILE ";1"));
#else
// Access IOP replacement module on the local disk
while (!sceSifRebootIop ("host0:/usr/local/sce/iop/modules/"
IOP_IMAGE_file));
#endif
No services can be used via the IOP, including printf(), from the time sceSifRebootIop() is issued until
sceSifSyncIop() returns a non-zero value (however, the EE coprocessor can be controlled).
Also, since all SIFCMD, SIFRPC, and DECI settings are reset, they should be set again. For sceOpen() or
sceRead(), call sceFsReset() and for libcdvd, call sceCdInit().
Many libraries that have an IOP module provide a function (sceXXXChangeThreadPriority()) to change the
thread priority of an active module.
For more information, refer to the library documents.