PCCL API reference[top|sitemap|download|docs]

PCCL API reference guide and documentation

This is the offical PCCL API reference guide. It documents all commands and their parameter packets. Using the /dev/pccl device driver prevents you from using a direct I/O port based programming interface and simplifies a lot.

/dev/pccl I/O command reference

CAEIOC_COMMAND lowlevel operations (always possible)
command handshake with caetla u_char : WR
This is the lowlevel caetla handshake. It exchanges 'CL' against 'do' and takes as parameter a command byte. If you want to program caetla directly you definitly need this. This command is only for experienced caetla hackers!
CAEIOC_COMMAND_RAW lowlevel operations (always possible)
lowlevel command handshake with caetla u_char : WR
This is the same as CAEIOC_COMMAND, but it exchanges 'PR' against 'do'. This is the old PSPAR handshake which is used by all cartridges during the RESET phase. It is needed if you want to reflash a cartridge's EEPROM with the original protocol. I'm using this only for the emergency reflash. It takes a command byte for the protocol as parameter. DO NOT USE THIS UNLESS YOU KNOW WHAT YOU ARE DOING...
CAEIOC_SWAP_8 lowlevel operations (always possible)
exchange 8-bit value with caetla u_char * : WR
This exchanges a single character with over the link. The parameter is a pointer to a character; the character will be sent over the link and the result is written to the character.
CAEIOC_SWAP_16 lowlevel operations (always possible)
exchange 16-bit value with caetla u_short * : WR
This exchanges a single 16-bit value with over the link. The parameter is a pointer to a 16-bit value; the 16-bit value will be sent over the link and the result is written to the 16-bit value.
CAEIOC_SWAP_32 lowlevel operations (always possible)
exchange 32-bit value with caetla u_long * : WR
This exchanges a single 32-bit value with over the link. The parameter is a pointer to a 32-bit value; the 32-bit value will be sent over the link and the result is written to the 32-bit value.
CAEIOC_DEVICE_INFO lowlevel operations (always possible)
checksum exchange (after a memory transfer) caetla_device_info_t * : R
After a memory transfer you need to exchange a checksum, which is done with this command. See the example sources on how to use it correctly.
CAEIOC_DEVICE_GET_MODE lowlevel operations (always possible)
get global device mode caetla_device_mode_t * : R
This command will fill the parameter packet with informations about a requested mode. The mode in request must be given in the parameter packet and its value will be returned in that structure too.
CAEIOC_DEVICE_SET_MODE lowlevel operations (always possible)
set global device mode caetla_device_mode_t * : W
Set a global mode for the current device. The only currently supported global mode is the AUTORESUME mode. Since /dev/pccl has a /proc interface there was no good choice of how to deal with a resumed execution. If you are modifying remote memory you probably don't want to press a RESUME button every time you changed a byte (especially when you were using /proc/pccl/0/mem). On the other hand you want to control the execution flow surely by yourself if you are debugging. This is why there is a AUTORESUME. If activated, you can't interrupt the remote machine; it will continue as soon as possible. If deactivated the remote machine will stop on each access unless you let resume the execution.
CAEIOC_NOP base operations (always possible)
do nothing operation void : -
Does really nothing. Needed by the fileserver.
CAEIOC_CONTROL base operations (always possible)
control basic operation mode of caetla u_char : WR
Control the current mode of caetla. Caetla provides several basic modes:
  • main menu
  • memory card manager
  • frame buffer viewer
  • code selector
  • CD-ROM manager
  • configuration
  • debug utility
The debug mode can only be used if a game is running, and all other modes only if no game is running (caetla menu mode).
CAEIOC_RESUME base operations (always possible)
resume execution (give control back to caetla) void : -
The execution on the remote machine is resumed. This command is ignored in AUTORESUME=off mode.
CAEIOC_RESET base operations (always possible)
software reset void : -
Tries to software reset the PSX. If the PSX is crashed a software reset does not work, so have to do it manually.
CAEIOC_CONSOLE base operations (always possible)
switch I/O redirection on/off u_char : W
All standard input and output can be redirected to a local server. You have to enable/disable this feature with this command.
CAEIOC_VERSION base operations (always possible)
get caetla subsystems versions caetla_version_t * : R
This will fill out the supplied parameter packet with the versions of all caetla sub systems. These versions are not very useful and it seems that the caetla authors do not update them. The version numbers are 8.8 bit numbers.
CAEIOC_GET_STATUS_PSPAR base operations (always possible)
get status in PSPAR notation u_char * : R
Fills out the parameter packet with the current status in PS/PAR notation.
CAEIOC_GET_STATUS_CAETLA base operations (always possible)
get status in caetla notation u_char * : R
Fills out the parameter packet with the current status in CAETLA notation.
CAEIOC_GET_EXECUTE_FLAGS base operations (always possible)
get caetla execution flags u_char * : R
Returns the settings from caetlas configuration manager during the execution of an application, like if I/O redirection is enabled, breakpoints are allowed etc.
CAEIOC_WRITE_MEMORY normal communication (CAETLA_MM)
write memory to PSX caetla_memory_t * : W
Initiate a memory transfer to the PSX. The paramter packet tells the address and length of the data to be transferred. After this command you should call write() with exactly length bytes of data. Finally you have to send an 8-bit checksum. /dev/pccl does always calculate an internal checksum, you can get it with the the CAEIOC_DEVICE_INFO command. See the tutorial for a detailed description.
CAEIOC_READ_MEMORY normal communication (CAETLA_MM)
read memory from PSX caetla_memory_t * : R
This is the same as the WRITE_MEMORY command but in the other direction.
CAEIOC_EXECUTE normal communication (CAETLA_MM)
execute a program on PSX caetla_execute_t * : W
With this command you will provide an execution environment. The program code must already be transferred. The execution will start as soon as you give the control back to the PSX (with CAEIOC_RESUME).
CAEIOC_JUMP_ADDRESS normal communication (CAETLA_MM)
continue execution at a specific address u_long : W
Directly execute program code at a specific address. No environment is created, so the code must initialize itself (clear all registers, set a stack and so on).
CAEIOC_ARGUMENTS normal communication (CAETLA_MM)
set main() function arguments caetla_arguments_t * : W
This command should be used to set the int argc, char **argv arguments of a main() function, unfortunately I have no clue how to really get these arguments; so this command is considered non-working.
CAEIOC_MC_DIRECTORY memory card (CAETLA_MCM)
get directory of memory card caetla_mc_directory_t * : R
Get the directory listing of a memory card. The parameter packet will hold the complete directory informations after this command. You have to provide only the memory card slot.
CAEIOC_MC_READ_SECTOR memory card (CAETLA_MCM)
read sector from memory card caetla_mc_sector_t * : R
Read a raw sector from a memory card.
CAEIOC_MC_WRITE_SECTOR memory card (CAETLA_MCM)
write sector to memory card caetla_mc_sector_t * : R
Write a raw sector to a memory card.
CAEIOC_MC_FORMAT memory card (CAETLA_MCM)
format a memory card caetla_mc_result_t * : R
Install a new filesystem to a memory card. This command does not work correctly, caetla will hang. This seems to be a bug in caetla.
CAEIOC_MC_LOCK memory card (CAETLA_MCM)
lock a memory card caetla_mc_result_t * : R
Locks a memory card
CAEIOC_MC_UNLOCK memory card (CAETLA_MCM)
unlock a memory card caetla_mc_result_t * : R
Unlocks a memory card
CAEIOC_MC_STATUS memory card (CAETLA_MCM)
get status of memory card caetla_mc_result_t * : R
Get the status of a memory card. Various error bits are set in the status.
CAEIOC_MC_READ_FILE memory card (CAETLA_MCM)
read a file from memory card caetla_mc_file_read_t * : R
Read a file from a memory card
CAEIOC_MC_CREATE_FILE memory card (CAETLA_MCM)
create a file on a memory card caetla_mc_file_create_t * : R
Create a file on a memory card.
CAEIOC_MC_DELETE_FILE memory card (CAETLA_MCM)
delete a file from a memory card caetla_mc_result_t * : R
Delete a file from a memory card
CAEIOC_MC_RESCAN_FILES memory card (CAETLA_MCM)
rescan files from a memory card caetla_mc_result_t * : R
Rescan the directory of a memory card into the caetla buffer. The directory is cached in the caetla memory card manager.
CAEIOC_FB_READ_MEMORY frame buffer (CAETLA_FBV)
read frame buffer memory caetla_fb_mode_t * : R
This command transfers selected portions of the remote frame buffer. You have to provide the basic modes in the parameter packet.
CAEIOC_FB_WRITE_MEMORY frame buffer (CAETLA_FBV)
write frame buffer memory caetla_fb_mode_t * : W
This is the same as the above command but in the other direction.
CAEIOC_FB_GET_MODE frame buffer (CAETLA_FBV)
get frame buffer video mode caetla_fb_mode_t * : R
Get the current frame buffer mode (as selected in the caetla frame buffer viewer)
CAEIOC_FB_SET_MODE frame buffer (CAETLA_FBV)
set frame buffer video mode caetla_fb_mode_t * : W
Sets the frame buffer video mode.
CAEIOC_DU_FLUSH_ICACHE debugger commands (CAETLA_DU)
flush processor instruction cache void : -
This is an important call if you are modifying code, like inserting breakpoints. You always have to call this command before continuing execution after you have modified the machine code!
CAEIOC_DU_DISABLE_HBP debugger commands (CAETLA_DU)
disable use of hardware breakpoints void : -
Switch off hardware breakpoints.
CAEIOC_DU_CONFIGURE_HBP debugger commands (CAETLA_DU)
configure a hardware breakpoint caetla_hbp_t * : W
Configure the hardware breakpoint. These breakpoints can not only be used to stop at a given address, they can also be used to watch the access of a memory location (readable and writable).
CAEIOC_DU_GET_REGISTERS debugger commands (CAETLA_DU)
get processor registers caetla_registers_t * : R
Get all registers of the MIPS R3000 processor
CAEIOC_DU_SET_REGISTER debugger commands (CAETLA_DU)
set a processor register caetla_register_t * : R
Set a single register of the MIPS R3000 processor
CAEIOC_DU_GET_CPCOND debugger commands (CAETLA_DU)
get coprocessor condition caetla_cpcond_t * : R
Get CP condition.
CAEIOC_DU_WRITE_MEMORY debugger commands (CAETLA_DU)
write memory to PSX in debug mode caetla_memory_t * : W
If a game is running, you have to use the DU_*_MEMORY commands to transfer memory. These commands unfortunately have a different syntax. The recommended way of accessing memory is currently the /proc/pccl/?/fullmem interface.
CAEIOC_DU_READ_MEMORY debugger commands (CAETLA_DU)
read memory from PSX in debug mode caetla_memory_t * : R
See the above command.
CAEIOC_DU_WRITE_BYTE debugger commands (CAETLA_DU)
write a byte in debug mode caetla_byte_t * : W
Write a single byte
CAEIOC_DU_WRITE_WORD debugger commands (CAETLA_DU)
write a word (32-bit) in debug mode caetla_word_t * : W
Write a word (32-bit) in debug mode
CAEIOC_DU_READ_WORD debugger commands (CAETLA_DU)
read a word (32-bit) in debug mode caetla_word_t * : R
Read a word (32-bit) in debug mode
CAEIOC_DU_HBP_DETECTION debugger commands (CAETLA_DU)
enable/disable hardware breakpoint detection u_char : W
enable/disable hardware breakpoint detection
CAEIOC_READ_CODE_MEMORY code preservation area (CAETLA_MM)
read from code preservation area of cartridge u_long * : R
read from code preservation area of cartridge
CAEIOC_WRITE_CODE_MEMORY code preservation area (CAETLA_MM)
write to code preservation area of cartridge u_long * : W
write to code preservation area of cartridge
CAEIOC_READ_XALIST code preservation area (CAETLA_MM)
read XALIST from non volatile EEPROM u_long * : R
read XALIST from non volatile EEPROM
CAEIOC_WRITE_XALIST code preservation area (CAETLA_MM)
write XALIST to non volatile EEPROM void : -
write XALIST to non volatile EEPROM
CAEIOC_WRITE_EEPROM code preservation area (CAETLA_MM)
flash EEPROM of cartridge caetla_eeprom_t * : W
flash EEPROM of cartridge

/dev/pccl data types and structures

For a more detailed description of each field and all constants you should definitly take a look into /opt/psxdev/include/pccl.h!
typedef struct {
	int mode;
	int value;
} caetla_device_mode_t;
Used as parameter packet for the get and set mode command
typedef struct {
	u_char checksum;
	u_short checksum2;
} caetla_device_info_t;
Footer of a memory read/write transaction. Used to transfer the checksums after a read or write access.
typedef struct {
	u_long address;
	u_long size;
} caetla_memory_t;
Header of a memory read/write transaction. Used to transfer the memory range.
typedef struct {
	u_long pc0;
	u_long gp0;
	u_long t_addr;
	u_long t_size;
	u_long d_addr;
	u_long d_size;
	u_long b_addr;
	u_long b_size;
	u_long s_addr;
	u_long s_size;
	u_long sp,fp,gp,ret,base;
	u_long task;
	u_long event;
	u_long stack;
	u_char mode;
} caetla_execute_t;
Used to setup the execution environment.
typedef struct {
	u_short firmware;
	u_short cdm, mcm, fbv;
	u_short cs, du, cfg, mm;
} caetla_version_t;
Holds all version numbers for the caetla subsystems.
typedef struct {
	u_long address;
	u_long argv;
	u_long argc;
} caetla_arguments_t;
Used to set the main() arguments. Currently not possible.
typedef struct {
	u_long address;
	u_long condition;
	u_long datamask;
	u_long execmask;
} caetla_hbp_t;
CAEIOC_CONFIGURE_HBP parameter packet. Describes a hardware breakpoint.
typedef struct {
	u_long number;
	u_long data;
} caetla_register_t;
CAEIOC_SET_REGISTER parameter packet. Sets a single processor register.
typedef struct {
	u_long data[36];
} caetla_registers_t;
CAEIOC_GET_REGISTERS parameter packet. Gets all processor registers at once.
typedef u_char caetla_cpcond_t;
CAEIOC_GET_CPCOND parameter packet. The coprocessor status bits.
typedef u_char caetla_status_t;
CAEIOC_STATUS parameter packet. The status of the caetla link.
typedef u_char pspar_status_t;
The status in PSPAR notation.
typedef struct {
	u_long address;
	u_char data;
} caetla_byte_t;
Single byte transfer parameter packet.
typedef struct {
	u_long address;
	u_long data;
} caetla_word_t;
Single word (32-bit) transfer parameter packet.
typedef struct {
	u_short magic;
	u_char type;
	u_char size;
	u_char name[64];
	u_char reserved[28];
	u_short clut[16];
	u_short icon[3][(16*16)/4];
} caetla_mc_file_header_t;
Used by memory card interface
typedef struct {
	u_long magic;
	u_long reserved;
	u_long pc0;
	u_long gp0;
	u_long t_addr;
	u_long t_size;
	u_long d_addr;
	u_long d_size;
	u_long b_addr;
	u_long b_size;
	u_long s_addr;
	u_long s_size;
} caetla_mc_mexe_header_t;
Used by memory card interface
typedef struct {
	u_short slot;
	u_short fileno;
	u_short blocks;
	u_short checksum;
	u_short result;
} caetla_mc_file_read_t;
Used by memory card interface
typedef struct {
	u_short slot;
	u_char name[];
	u_long size;
	u_short blocks;
	u_short checksum;
	u_short result;
} caetla_mc_file_create_t;
Used by memory card interface
typedef struct {
	u_short slot;
	u_short sector;
	u_long size;
	u_char *data;
	u_short checksum;
	u_short result;
} caetla_mc_sector_t;
Used by memory card interface
typedef struct {
	u_short p1;
	u_long size;
	u_short p2;
	char name[];
	u_char p3;
	u_short p4;
	u_short p5;
	char comment[94];
} caetla_mc_file_info_t;
Used by memory card interface
typedef struct {
	u_short slot;
	u_short result;
	u_short fileno;
} caetla_mc_result_t;
Used by memory card interface
typedef struct {
	u_short slot;
	u_short count;
	caetla_mc_file_info_t file[16];
} caetla_mc_directory_t;
Used by memory card interface
typedef struct {
	u_char action;
	u_long address;
	u_long size;
} caetla_write_eeprom_t;
Used to flash an eeprom
typedef struct {
	u_short x,y;
	u_short width, height;
	u_short mode;
} caetla_fb_mode_t;
Set/get the frame buffer mode


Created with psxdev.pl
Copyright ©2000 by Daniel Balster