Miles Sound System SDK 7.2a

RAD_IOP_ASYNC_READ_DATA

The structure RAD_IOP_ASYNC_READ_DATA is a structure used to perform an asynchronous read.

struct RAD_IOP_ASYNC_READ_DATA
{
  S32 file_handle;
  U32 offset;
  U32 bytes_to_read;
  VOID_PTR dest;
  RAD_IOP_ADDRESS_VALUES dest_type;
  RAD_IOP_READCALLBACK callback;
  U32 group;
  RAD_IOP_STATUS_VALUES status;
  U32 bytes_read;
};

In Members

file_handle: You set to a file handle value from RAD_IOPQueueAsyncOpenFile.
A file handle value is one of two types of values. For CD or DVD files, it is the starting sector number or-ed with 0x80000000. For other files, it is just the value returned from the C runtime open function. This means that you don't have to use this routine at all (if you do your own opens, or you know the starting sector number of your file) - just pass these values directly into the read routines.
offset: You set to the offset into the file to read from.
bytes_to_read: You set to the number of bytes to read.
dest: You set to the address where you want the output bytes.
dest_type: Contains the type of memory address that the dest parameter is, an EE, IOP or SPU memory address.
callback: Specifies a callback that should be made upon completion. If you don't want to be called back, then set this field to zero.
group: Optional. Specifies the group identifier of this open. The group id allows you to cancel I/Os for an entire group of requests, if necessary.

Out Members

status: Contains the current status of the async read.
bytes_read: Contains the total bytes read.

Discussion

This structure is used in the RAD_IOPQueueAsyncReadAtTop and RAD_IOPQueueAsyncReadAtBottom functions to schedule a background file read.

You set the file_handle, offset, bytes_to_read, dest, callback, and optionally the group fields and then submit this structure to one of the async read functions. RAD_IOP will then instruct the IOP to perform the read in the background. When the read is complete, the status will be updated, and then the callback made (if you set one).

If you don't have a callback set, then you can spin on the status field and wait for it to go greater than or equal to RAD_IOP_STATUS_COMPLETE. You then query the status for RAD_IOP_STATUS_DONE to determine if the read succeeded.

If the callback is set, then it is called whether the read succeeded or failed, so check the status field in your callback. The callback is made at interrupt time, so be sure that your callback code is interrupt safe.

If the status returns as RAD_IOP_STATUS_ERROR, then you can call the RAD_IOPGetIOStatus function to query for the error code (which will be the result of sceCdRead for CD or DVD files, or the result of the C runtime read functions for other devices).

The read_data structure must remain valid until the read completes or you cancel the read with one of the CancelAsync functions.

Group: The RAD_IOP API for the Sony PS2
Related Functions: RAD_IOPCancelAsyncRead, RAD_IOPGetIOStatus, RAD_IOPQueueAsyncOpenFile, RAD_IOPQueueAsyncReadAtBottom, RAD_IOPQueueAsyncReadAtTop, RAD_IOP_READCALLBACK
Related Basic Types: RAD_IOP_ADDRESS_VALUES, RAD_IOP_STATUS_VALUES, S32, U32, VOID_PTR