N64® Functions Menu

al - Audio Library Functions
etc - String Manipulation Functions
gDP - DP GBI Macros
gdSP - General GBI Macros
gSP - SP GBI Macros
gt - Turbo Microcode RDP
gu - Graphics Utilities
Math - Math Functions
nuSys - NuSystem
os - N64 Operating System
sp - Sprite Library Functions
uh - Host to Target IO
64DD - N64 Disk Drive

Nintendo® Confidential

## LeoReadWrite

Syntax

    #include <leo.h>

    s32 LeoReadWrite (LEOCmd *cmdBlock,
       s32 direction , u32 startLBA,
       void *vaddr, u32 nLBAs,
       OSMesgQueue *mq);

Note: None of the N64 Disk Drive-related instructions involve ROM DMA (including DMA to ROM in the drive). In fact, the instructions are designed on the assumption that ROM DMA will not be carried out. To learn more about this, please see the "Programming Cautions" section of the N64 Disk Drive Programmer's Guide.
Explanation
It performs reads and writes between RDRAM and the N64 Disk Drive. This function is used to set up various parameters of the command block specified by the cmdBlock argument in accordance with the following arguments specified on the call side:

- The transfer direction specified by the direction argument
- The starting LBA specified by the startLBA argument
- The RDRAM address specified by the vaddr argument
- The transfer LBA size specified by the nLBAs argument; it specifies the size of the logical block to be transferred
- The message queue specified by the mq argument that indicates that command processing has ended

Use 16-byte alignment to store the RDRAM virtual address specified by the vaddr argument. This can be easily done by using OS_DCACHE_ROUNDUP_ADDR.
The cmdBlock._nbytes element stores the current extent to which the read or write has been performed. So even if an error is returned, the data that has been correctly read up to that point can be used.
Nothing needs to be set for the command block specified by the cmdBlock argument.
When this function finishes processing, an error code is returned to the location pointed to by the mq argument. An error could arise, so the programmer needs to check this error code. Following are some possible errors to be returned, their causes and the actions that should be taken:

- LEO_ERROR_QUEUE_FULL - There is no more space in the command queue. The queue size should be enlarged. See the LeoCreateLeoManager function for details.
- LEO_ERROR_COMMAND_TERMINATED - The LeoClearQueue or LeoReset function was issued, so this function (LeoReadWrite) did not execute.
- LEO_ERROR_DEVICE_COMMUNICATION_FAILURE - The main reason for this error is a bad physical connection. However, there is a possibility that the drive itself is not functioning.
- LEO_ERROR_COMMAND_PHASE_ERROR - This error occurs when the N64 Disk Drive status is not good.
- LEO_ERROR_POWERONRESET_DEVICERESET_OCCURED - This error appears when the drive is reset. The possible cause is that the connector was reconnected, which caused subsequent N64 Disk Drive actions to become unstable. Advise the users to reset the drive.
- LEO_ERROR_MEDIUM_NOT_PRESENT - The disk has not been inserted.
- LEO_ERROR_MEDIUM_MAY_HAVE_CHANGED - A disk was reinserted after being removed. There is no certainty that the game should be continued using the newly inserted disk. If this error occurs, call the LeoReadDiskID function to verify the identity of the newly inserted disk.
- LEO_ERROR_INCOMPATIBLE_MEDIUM_INSTALLED - This error occurs when a disk of an unsupported type is inserted. It is unlikely that you will encounter this error.
- LEO_ERROR_LBA_OUT_OF_RANGE - The specified LBA is out of range. All LBAs fall in the range between 0 and 4291.
- LEO_ERROR_WRITE_PROTECTED (Write only) - The LBA that was the intended write target is in the unwritable area (ROM area), so no write occurred.
- LEO_ERROR_DRIVE_NOT_READY - This error occurs when the disk is not operating or when it is not stable.
- LEO_ERROR_NO_REFERENCE_POSITION_FOUND - This error occurs when the servo data cannot be read or when an abnormality is found.
- LEO_ERROR_DIAGNOSTIC_FAILURE - This error occurs when an abnormality is found or traced.
- LEO_ERROR_NO_SEEK_COMPLETE - This error occurs when seeking cannot be done because of a seek time out or trace time out.
- LEO_ERROR_DATA_PHASE_ERROR - This error occurs when data transmission did not finish in the allotted time.
- LEO_ERROR_UNRECOVERED_READ_ERROR - This error occurs when the data could not be read clearly because of a flaw on the disk.
- LEO_ERROR_WRITE_FAULT (Write only) - This error occurs when an abnormality is detected while writing.
- LEO_ERROR_TRACK_FOLLOWING_ERROR - This error occurs when the head slips off the track while reading.

For more information about the possible errors, their causes, and ways to deal with them, please see the "Error-Handling" section of the N64 Disk Drive Programmer's Guide.
The return value is -1 if Leo Manager has not been created, and 0 if it has. Usually no check is necessary.
Example

    LEOCmd cmdBlock;
    u32 error;
    …..
    LeoReadWrite (&cmdBlock, OS_READ, 5,
       (void*)0x80200000, 100, &diskQ) ;
    osRecvMesg (&diskQ, (OSMesg *)&error,
       OS_MESG_BLOCK) ;

See Also
Leo
LeoCreateLeoManager
LeoSeek
LeoSpdlMotor
LeoByteToLBA
LeoLBAToByte
LeoTestUnitReady
LeoRezero
LeoClearQueue
LeoReadDiskID
LeoReadCapacity

Nintendo® Confidential Warning: all information in this document is confidential and covered by a non-disclosure agreement. You are responsible for keeping this information confidential and protected. Nintendo will vigorously enforce this responsibility.
Copyright © 1998
Nintendo of America Inc. All rights reserved
Nintendo and N64 are registered trademarks of Nintendo
Last Updated April, 1999