resonance 1.0.1
Loading...
Searching...
No Matches
async.h File Reference
#include <stddef.h>
#include <sys/types.h>
Include dependency graph for async.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  AsyncJobInfo
 One queued asynchronous read. More...
struct  AsyncRequest
 One queued or completed asynchronous request. More...

Enumerations

enum  FileSeekOrigin { kFileSeekSet = 0 , kFileSeekCur = 1 , kFileSeekEnd = 2 }
 Origins FileSeek() and SeekArkStream() accept. More...

Functions

void InitAsync ()
 Bring up the asynchronous file-I/O layer.
void ShutdownAsync ()
 Release the job ring.
int AsyncSubmitRequest (int nFile, void *pBuffer, int nLength, int bCloseOnComplete, AsyncCallback *pCallback, int bOwnsBuffer)
 Queue one asynchronous read and report its identifier.
int AsyncLoadFileByPath (const char *pszPath, void *pBuffer, unsigned nLength, AsyncCallback *pCallback)
 Open a path and queue the whole file as one asynchronous read.
void AsyncQueueRequest (AsyncRequest request)
 Split a request into chunk jobs and put it on the pending list.
void AsyncJobComplete (AsyncRequest *pRequest, int nStatus)
 Finish a request and put it on the completed list.
int AsyncGetIdFromFd (int nFile)
 Resolve a file handle to the file the sector cache is keyed by.
int MatchesCurrentAsyncOp (int nFile, int nSector)
 Report whether the operation the drive is servicing right now covers a chunk.
void AsyncCheck (int nBlocking)
 Advance the operation the media is servicing.
void AsyncPumpCompletedRequests ()
 Service the queue once.
int IsMediaReady ()
 Report whether the disc is ready to read.
void AsyncMediaEventCallback (int nFunction)
 Drive completion callback the async layer installs on disc media.
int AsyncPollComplete (int nHandle, void **ppBuffer, int *pnLength)
 Report a finished request and take it off the completed list.
void AsyncCancelRequest (int nHandle)
 Abandon a request wherever it sits.
void AsyncDump ()
 Report the queue to the log.
void AsyncStatus (int &nPending, int &nCompleted, int &nFreeJobs)
 Report how much work the queue is holding.
AsyncJobInfo * AsyncGetFreeJobChain ()
 Take the next job off the free list.
void AsyncReturnJobChain (AsyncJobInfo *pChain)
 Put a whole chain of jobs back on the free list.
int FileOpen (const char *pszPath, int nFlags,...)
 Open a file by path.
ssize_t read (int nFile, void *pBuffer, size_t nLength)
 Read one run of bytes from a file.
int FileSeek (int nFile, int nOffset, int nOrigin)
 Move a file's read position.
int close (int nFile)
 Close a file.
ssize_t write (int nFile, const void *pBuffer, size_t nLength)
 Write to a file.
int isatty (int nFile)
 Report whether a file is an interactive terminal.
int ArkfileGetCurrAbsOffset (int nStream)
 Report an ark stream's read position.
int SeekArkStream (int nStream, int nOffset, int nOrigin)
 Move an ark stream's read position.

Variables

constexpr int kAsyncJobCount = 512
 The number of job records the ring is built from.
constexpr int kFileHandleArkStream = 0x4000
 Bit of a file handle that identifies a stream inside a mounted ark rather than a loose file.
constexpr int kFileHandleSceFile = 0x2000
 Bit of a file handle that identifies a file the host or disc file service opened.
constexpr unsigned kAsyncRequestCloseFile = 1
 Bit of AsyncRequest::mFlags that makes completion close the request's file.
constexpr unsigned kAsyncRequestInflate = 2
 Bit of AsyncRequest::mFlags that makes completion inflate what the read delivered.
constexpr int kAsyncStatusPending = -1
 Stored in AsyncRequest::mStatus while the request has not completed.
constexpr int kAsyncStatusOk = 0
 Stored in AsyncRequest::mStatus once the data is in place.
constexpr int kAsyncStatusOpenFailed = 2
 Stored in AsyncRequest::mStatus when the path could not be opened.
constexpr int kAsyncStatusBufferTooSmall = 3
 Stored in AsyncRequest::mStatus when the caller's buffer is smaller than the file.
constexpr int kAsyncStatusReadFailed = 4
 Stored in AsyncRequest::mStatus when the read itself failed.
constexpr int kAsyncStatusInflateFailed = 5
 Stored in AsyncRequest::mStatus when the read succeeded and the inflate did not.

Enumeration Type Documentation

◆ FileSeekOrigin

Origins FileSeek() and SeekArkStream() accept.

Enumerator
kFileSeekSet 

Measure the offset from the start.

kFileSeekCur 

Measure the offset from the current position.

kFileSeekEnd 

Measure the offset from the end.

Function Documentation

◆ InitAsync()

void InitAsync ( )

Bring up the asynchronous file-I/O layer.

Allocates the 512-job ring, threads it into one doubly linked free list, and clears the current operation. On disc media the drive callback thread is created and AsyncMediaEventCallback() is installed as the drive completion callback. The routine is idempotent through the initialised flag, and every queue entry point calls it first.

Ghidra address:
NTSC-U/C: 0x0045f000
Ghidra address:
PAL: 0x0049c6c0

◆ ShutdownAsync()

void ShutdownAsync ( )

Release the job ring.

Performs no work when the layer was never brought up. The initialised flag is not cleared, so the layer cannot be brought up again afterwards.

Ghidra address:
NTSC-U/C: 0x00460b98
Ghidra address:
PAL: 0x0049e258

◆ AsyncSubmitRequest()

int AsyncSubmitRequest ( int nFile,
void * pBuffer,
int nLength,
int bCloseOnComplete,
AsyncCallback * pCallback,
int bOwnsBuffer )

Queue one asynchronous read and report its identifier.

Brings the layer up on first use, then builds a request whose caller window and read window both describe the whole transfer. For an ark stream on disc media the stream position is advanced past the data the read will deliver once the request is queued. A following request therefore continues where this one ends.

Parameters
nFileThe file to read, positioned where the read should start.
pBufferThe destination.
nLengthThe number of bytes to read.
bCloseOnCompleteNon-zero to close nFile once the request completes.
pCallbackReceiver notified once the request completes, or null.
bOwnsBufferNon-zero to have a cancelled request release pBuffer.
Returns
The request identifier, which AsyncPollComplete() and AsyncCancelRequest() match on.
Ghidra address:
NTSC-U/C: 0x00460bd0
Ghidra address:
PAL: 0x0049e290

◆ AsyncLoadFileByPath()

int AsyncLoadFileByPath ( const char * pszPath,
void * pBuffer,
unsigned nLength,
AsyncCallback * pCallback )

Open a path and queue the whole file as one asynchronous read.

A path ending in .gz is inflated in place once the read completes. The buffer is sized to the larger of the stored and inflated sizes, the stored bytes are read into its tail, and kAsyncRequestInflate makes completion inflate them forward over the buffer. With no buffer supplied one is allocated, from the selected zone when there is one. An ark stream reports both sizes from its directory entry, and a loose gzip file reports the inflated size from its own last four bytes.

Two failures are reported as a completed request rather than through the return value. A path that will not open completes with kAsyncStatusOpenFailed, and a buffer smaller than the file completes with kAsyncStatusBufferTooSmall. Either way the identifier is a real one a caller can poll.

Parameters
pszPathThe file to read.
pBufferThe destination, or null to have one allocated.
nLengthThe destination size, ignored when pBuffer is null. The unsigned type is proven by the unsigned comparison against the file size and by the zero extension at the stream-advance call.
pCallbackReceiver notified once the request completes, or null.
Returns
The request identifier.
Ghidra address:
NTSC-U/C: 0x0045f148
Ghidra address:
PAL: 0x0049c808

◆ AsyncQueueRequest()

void AsyncQueueRequest ( AsyncRequest request)

Split a request into chunk jobs and put it on the pending list.

The request is passed by value, which is what the image does. Every caller copies the 48-byte record into its outgoing argument area and passes the address of the copy.

On host media the read runs at once through read() and the request completes in place. On disc media the file position is taken, the transfer is divided at kSectorCacheRowSize boundaries, and for an ark stream every chunk the sector cache already buffers is copied straight out of its row. Each remaining chunk takes a job off the free chain. A request with no job at all completes immediately.

Parameters
requestThe request to queue.
Ghidra address:
NTSC-U/C: 0x0045fc90
Ghidra address:
PAL: 0x0049d350

◆ AsyncJobComplete()

void AsyncJobComplete ( AsyncRequest * pRequest,
int nStatus )

Finish a request and put it on the completed list.

A positive status is reported through the log as AsyncJobComplete: job d has error: d and skips the inflate. kAsyncRequestInflate inflates mReadLength bytes from mReadBuffer over mBuffer, and a failed inflate is reported as status 5. kAsyncRequestCloseFile then closes mFile.

Parameters
pRequestThe request to finish.
nStatusThe status to record.
Ghidra address:
NTSC-U/C: 0x0045ffa8
Ghidra address:
PAL: 0x0049d668

◆ AsyncGetIdFromFd()

int AsyncGetIdFromFd ( int nFile)

Resolve a file handle to the file the sector cache is keyed by.

An ark stream handle resolves to the archive's own file. Two streams inside one archive therefore share its cache rows. Any other handle resolves to itself.

Parameters
nFileThe file handle.
Returns
The resolved file, or -1 when no stream record has that handle.
Ghidra address:
NTSC-U/C: 0x00460d58
Ghidra address:
PAL: 0x0049e418

◆ MatchesCurrentAsyncOp()

int MatchesCurrentAsyncOp ( int nFile,
int nSector )

Report whether the operation the drive is servicing right now covers a chunk.

A row the in-flight operation is still filling must not be read out of the cache, which is the one use of this test.

Parameters
nFileThe resolved file.
nSectorThe 64 KiB chunk index.
Returns
Non-zero when the current operation is filling that chunk.
Ghidra address:
NTSC-U/C: 0x00460f78
Ghidra address:
PAL: 0x0049e638

◆ AsyncCheck()

void AsyncCheck ( int nBlocking)

Advance the operation the media is servicing.

The name is attested by the routine's own report, AsyncCheck: unexpected op status: d. The body returns at once unless the current chunk transfer has a command in flight. Otherwise it waits for that command, then advances the transfer: a finished seek issues the read, and a finished read marks the data ready for AsyncPumpCompletedRequests() to distribute.

How the wait is performed depends on the media. On disc media the drive callback thread raises a flag the routine consumes, and without that thread the routine calls sceCdSync() instead. Either way a drive error of SCECdErTRMOPN waits for the tray and requests a retry, and every other drive error is fatal through CD ERROR: d on sector d, NOT retrying....

A command that has been in flight for more than three seconds also consults the drive directly. A drive reporting SCECdNotReady requests a retry, and a ready drive more than ten seconds in reports HEY - 10 SECONDS SINCE ASYNC OP through a routine whose body is empty in this build.

Thirteen call sites, most of them immediately before a synchronous read. That is what stops a queued read from racing the synchronous one.

Parameters
nBlockingNon-zero to keep waiting until the command settles, zero to return as soon as the drive reports that it is still busy.
Ghidra address:
NTSC-U/C: 0x00460590
Ghidra address:
PAL: 0x0049dc50

◆ AsyncPumpCompletedRequests()

void AsyncPumpCompletedRequests ( )

Service the queue once.

On disc media the routine advances the chunk transfer the drive is performing. A finished chunk is distributed to every pending request covering it and its cache row is unlocked, and an idle drive is then given the next chunk any pending request still needs. Nothing here waits for the drive. A caller that wants the data now calls AsyncCheck() instead.

Every completed request is then reported to its callback, its jobs are released, and its record is erased. A request with no callback is erased in the same pass. A caller that wants the buffer back through AsyncPollComplete() therefore has to poll before the next pump.

Ghidra address:
NTSC-U/C: 0x0045f8d8
Ghidra address:
PAL: 0x0049cf98

◆ IsMediaReady()

int IsMediaReady ( )

Report whether the disc is ready to read.

This build always reports 1. MetRenderer::Update() is the one caller, and it shows met_disc_prob.view while the report is 0. The name is inferred from that view.

Returns
1.
Ghidra address:
NTSC-U/C: 0x00460b20
Ghidra address:
PAL: 0x0049e1e0

◆ AsyncMediaEventCallback()

void AsyncMediaEventCallback ( int nFunction)

Drive completion callback the async layer installs on disc media.

The shape is libcdvd's sceCdCBFunc, and the argument is the function code of the command that just finished. The drive error code is latched on every report, and a finished read or seek raises the flag AsyncCheck() waits on. Every other code only latches the error.

Parameters
nFunctionThe libcdvd function code of the finished command.
Ghidra address:
NTSC-U/C: 0x00460b28
Ghidra address:
PAL: 0x0049e1e8

◆ AsyncPollComplete()

int AsyncPollComplete ( int nHandle,
void ** ppBuffer,
int * pnLength )

Report a finished request and take it off the completed list.

The request's job chain is released and its node erased. Either output pointer may be null.

Parameters
nHandleThe identifier AsyncSubmitRequest() reported.
ppBufferReceives the request's buffer, or null to discard it.
pnLengthReceives the number of bytes the request covers, or null to discard it.
Returns
The request's status, or -1 when no completed request has that identifier.
Ghidra address:
NTSC-U/C: 0x0045f658
Ghidra address:
PAL: 0x0049cd18

◆ AsyncCancelRequest()

void AsyncCancelRequest ( int nHandle)

Abandon a request wherever it sits.

Both lists are searched. A matching request has its buffer released when mOwnsBuffer is set, its file closed when kAsyncRequestCloseFile is set, its job chain released, and its node erased. async.cpp lines 481 and 499.

Parameters
nHandleThe identifier AsyncSubmitRequest() reported.
Ghidra address:
NTSC-U/C: 0x0045f738
Ghidra address:
PAL: 0x0049cdf8

◆ AsyncDump()

void AsyncDump ( )

Report the queue to the log.

Ghidra address:
NTSC-U/C: 0x0045faf0
Ghidra address:
PAL: 0x0049d1b0

◆ AsyncStatus()

void AsyncStatus ( int & nPending,
int & nCompleted,
int & nFreeJobs )

Report how much work the queue is holding.

Every count is walked rather than stored. AsyncDump() reports the same three quantities through its own copies of these loops rather than through this routine, and the names here come from the messages it prints them with. The one caller is a debug reader outside this subsystem.

Parameters
nPendingReceives the number of queued requests.
nCompletedReceives the number of finished requests no caller has taken yet.
nFreeJobsReceives the number of job records still free.
Ghidra address:
NTSC-U/C: 0x0045fa38
Ghidra address:
PAL: 0x0049d0f8

◆ AsyncGetFreeJobChain()

AsyncJobInfo * AsyncGetFreeJobChain ( )

Take the next job off the free list.

Exhausting the free list is fatal.

Returns
The job, unlinked from the free list.
Ghidra address:
NTSC-U/C: 0x00460d90
Ghidra address:
PAL: 0x0049e450

◆ AsyncReturnJobChain()

void AsyncReturnJobChain ( AsyncJobInfo * pChain)

Put a whole chain of jobs back on the free list.

The chain is walked to its end, which is then spliced onto the current free list, and the chain head becomes the new free list head. A null argument produces no work.

Parameters
pChainThe head of the chain to release.
Ghidra address:
NTSC-U/C: 0x00460dd8
Ghidra address:
PAL: 0x0049e498

◆ FileOpen()

int FileOpen ( const char * pszPath,
int nFlags,
... )

Open a file by path.

The game's replacement for the C library's open(), which its trace line open(s) at t:f names. The newlib access mode and the append, create, and truncate bits are translated to the file service's SCE_* flags.

A request to write goes to host0:. On a CD-only boot, a write to a .py, .pyc, or .gz path is refused with -1 instead.

A read first tries a mounted archive when UsingArkFiles() reports ark use, which yields an ark stream with kFileHandleArkStream set. Otherwise, and on a CD-only boot for a path that is not .py, .pyc, or .gz, the path is opened on the disc as cdrom0: plus FilenameToISO9660() for either CD boot mode, or on host0: for a host-only boot. A disc open that fails falls back to host0: when the boot mode permits both media. A file-service handle has kFileHandleSceFile set.

Each open other than the log's own is traced to the file log with the handle it produced.

Parameters
pszPathThe file to open.
nFlagsThe newlib open flags.
Returns
The file. A negative result reports that the open failed.
Ghidra address:
NTSC-U/C: 0x0047c9c0
Ghidra address:
PAL: 0x004ba650

◆ read()

ssize_t read ( int nFile,
void * pBuffer,
size_t nLength )

Read one run of bytes from a file.

The game's own read(), in place of the C library's. An ark stream goes to ReadArkStreamThroughCache(). A file-service handle waits for the async layer and the drive and goes to sceRead() with kFileHandleSceFile cleared. Any other handle goes to the console reader. Every read is traced to the file log.

Parameters
nFileThe file to read.
pBufferThe destination.
nLengthThe number of bytes to read.
Returns
The number of bytes transferred, which is not positive on failure.
Ghidra address:
NTSC-U/C: 0x0047e060
Ghidra address:
PAL: 0x004bbd38

◆ FileSeek()

int FileSeek ( int nFile,
int nOffset,
int nOrigin )

Move a file's read position.

The game's replacement for the C library's lseek(), the routine its trace line identifies. It dispatches on the handle in the same way as read(), to SeekArkStream(), to sceLseek(), or to the console stub. The console stub reports -1. Every seek is traced to the file log.

Parameters
nFileThe file to move.
nOffsetThe offset to move by.
nOriginOne of FileSeekOrigin.
Returns
The resulting position.
Ghidra address:
NTSC-U/C: 0x0047e1c8
Ghidra address:
PAL: 0x004bbea0

◆ close()

int close ( int nFile)

Close a file.

The game's own close(), in place of the C library's. The close is traced to the file log first. An ark stream's record is erased, a file-service handle goes to sceClose(), and any other handle goes to the console stub. The console stub reports -1.

Parameters
nFileThe file to close.
Returns
The result of the close.
Ghidra address:
NTSC-U/C: 0x0047dfb0
Ghidra address:
PAL: 0x004bbc88

◆ write()

ssize_t write ( int nFile,
const void * pBuffer,
size_t nLength )

Write to a file.

The game's own write(), in place of the C library's. An ark stream, kFileHandleArkStream, cannot be written and reports -1. A file-service handle goes to sceWrite() with kFileHandleSceFile cleared, and any other handle goes to the console writer. Writes are not traced. The C library's write path and the embedded interpreter's posix.write call it.

Parameters
nFileThe file to write.
pBufferThe source.
nLengthThe number of bytes to write.
Returns
The number of bytes transferred, or -1 on failure.
Ghidra address:
NTSC-U/C: 0x0047e178
Ghidra address:
PAL: 0x004bbe50

◆ isatty()

int isatty ( int nFile)

Report whether a file is an interactive terminal.

The game's own isatty(), in place of the C library's. An ark stream or a file-service handle is never a terminal, and any other handle goes to the console stub. The console stub reports 1. The embedded interpreter's raw_input and its interactive-input test call it.

Parameters
nFileThe file to test.
Returns
Non-zero for a terminal.
Ghidra address:
NTSC-U/C: 0x0047e2f0
Ghidra address:
PAL: 0x004bbfc8

◆ ArkfileGetCurrAbsOffset()

int ArkfileGetCurrAbsOffset ( int nStream)

Report an ark stream's read position.

The position reported is ArkStream::mArkPosition, measured inside the whole archive rather than inside the stream's file.

Parameters
nStreamThe ark stream handle, kFileHandleArkStream included.
Returns
The position, or -1 when no stream record has that handle.
Ghidra address:
NTSC-U/C: 0x0055c028
Ghidra address:
PAL: 0x0059d248

◆ SeekArkStream()

int SeekArkStream ( int nStream,
int nOffset,
int nOrigin )

Move an ark stream's read position.

A resulting position before the start of the stream is clamped back to the start. A stream whose archive is no longer mounted, and an origin outside FileSeekOrigin, both report -1.

Parameters
nStreamThe ark stream handle, kFileHandleArkStream included.
nOffsetThe offset to move by.
nOriginOne of FileSeekOrigin.
Returns
The resulting position, or -1 when no stream record has that handle.
Ghidra address:
NTSC-U/C: 0x0055bd38
Ghidra address:
PAL: 0x0059cf58

Variable Documentation

◆ kAsyncJobCount

int kAsyncJobCount = 512
constexpr

The number of job records the ring is built from.

◆ kFileHandleArkStream

int kFileHandleArkStream = 0x4000
constexpr

Bit of a file handle that identifies a stream inside a mounted ark rather than a loose file.

◆ kFileHandleSceFile

int kFileHandleSceFile = 0x2000
constexpr

Bit of a file handle that identifies a file the host or disc file service opened.

◆ kAsyncRequestCloseFile

unsigned kAsyncRequestCloseFile = 1
constexpr

Bit of AsyncRequest::mFlags that makes completion close the request's file.

◆ kAsyncRequestInflate

unsigned kAsyncRequestInflate = 2
constexpr

Bit of AsyncRequest::mFlags that makes completion inflate what the read delivered.

The inflate runs forward from mReadBuffer over mBuffer, which is why AsyncLoadFileByPath() reads a compressed file into the tail of its buffer.

◆ kAsyncStatusPending

int kAsyncStatusPending = -1
constexpr

Stored in AsyncRequest::mStatus while the request has not completed.

◆ kAsyncStatusOk

int kAsyncStatusOk = 0
constexpr

Stored in AsyncRequest::mStatus once the data is in place.

◆ kAsyncStatusOpenFailed

int kAsyncStatusOpenFailed = 2
constexpr

Stored in AsyncRequest::mStatus when the path could not be opened.

◆ kAsyncStatusBufferTooSmall

int kAsyncStatusBufferTooSmall = 3
constexpr

Stored in AsyncRequest::mStatus when the caller's buffer is smaller than the file.

◆ kAsyncStatusReadFailed

int kAsyncStatusReadFailed = 4
constexpr

Stored in AsyncRequest::mStatus when the read itself failed.

◆ kAsyncStatusInflateFailed

int kAsyncStatusInflateFailed = 5
constexpr

Stored in AsyncRequest::mStatus when the read succeeded and the inflate did not.