N64® Functions Menu

al - Audio Library 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

## osEPiStartDma
osEPiWriteIo
osEPiReadIo

Syntax

    #include <ultra64.h>

    s32 osEPiStartDma(
       OSPiHandle *phandle,
       OSIoMesg *mb,
       s32 direction);
    s32 osEPiWriteIo(
       OSPiHandle *phandle,
       u32 devAddr, u32 data);
    s32 osEPiReadIo(
       OSPiHandle *phandle,
       u32 devAddr, u32 *data);

Explanation
The osEPiStartDma, osEPiWriteIo, and osEPiReadIo routines gain access to the expanded peripheral interface (EPI) by using the PI manager. The expanded peripheral interface (EPI) transfers data between RDRAM and a bulk storage device (BSD) such as ROM, Drive ROM, and the N64 Disk Drive. EPI supports many devices sharing the PI domain, and it can switch among these devices dynamically.
These functions manage the PI bus by using the PI manager, and they support synchronization and independence when the PI is shared by peripheral IO utilities such as debug, print, logging, and profiling. You need to initialize the PI manager's system thread before using these EPI routines. See osPiStartDma for more information on how to do it.
The OSPiHandle data structure acts as a handler so the EPI routines can reference each PI device. The OSPiHandle structure is allocated and initialized by each device's initialization routine, and it stores each device's attributes.
The osEPiStartDma routine sets up a DMA transfer between RDRAM and the EPI device address space (devAddr), by sending an IO message block request (mb) to the PI manager, based on the value of direction (OS_READ or OS_WRITE).
The calling side specifies the following parameters in the request block:

- The device address (devAddr)
- The RDRAM address (dramAddr)
- Transfer volume
- The message queue (hdr.retQueue) that is to receive the message from the PI manager that the IO operation has finished

If the priority request (hdr.pri) is OS_MESG_PRI_HIGH (the default is OS_MESG_PRI_NORMAL), the osEPiStartDma function pushes the message in front of the PI manager's command queue. If it is not OS_MESG_PRI_HIGH, the message is added to the end of the command queue.
If the PI manager is not started, osEPiStartDma returns -1. Otherwise, the status is returned to either the osSendMesg or the osJamMesg function.
The transfer volume is a maximum of 16 megabytes, and it must be a multiple of two. Two-byte alignment is required for the PI device address (devAddr), and eight-byte alignment is required for the RDRAM's virtual address (dramAddr). Nintendo recommends that you use a 16-byte alignment if the DMA operation is done with OS_READ. See OS_DCACHE_ROUNDUP_ADDR for information about the problems that can occur when the address and the transfer volume are not multiples of the cache line.
The osEPiWriteIo routine performs 32-bit IO Write operations to the PI device address (devAddr).
The osEPiReadIo routine performs 32-bit IO read operations from the PI device address (devAddr), and it stores the value to data.
Warning
To gain access to the PI, Nintendo strongly recommends that you use these high-level, managed functions (osEPiWriteIo, osEPiReadIo, or osEPiStartDma).
Caution is especially required when high- and low-level functions are mixed. The PI can support only one IO at a time, so an out of synchronization condition may cause an error to occur in the PI. The osEPiStartDma, osEPiWriteIo, and osEPiReadIo routines reset the PI bus, if there is a discrepancy between the PI bus setting specified by pihandle and the actual PI bus setting when the function is called. It is not necessary to call osCartRomInit each time.
Example

    void romCopy(const char *src,
       const char *dest,
       const int len)
    {
       OSIoMesg dmaIoMesgBuf;
       OSMesgQueue dmaMessageQ;
       OSMesg dummyMesg;
       osInvalDCache((void *)dest,
          (s32) len);
       dmaIoMesgBuf.hdr.pri =
          OS_MESG_PRI_NORMAL;
       dmaIoMesgBuf.hdr.retQueue =
          dmaIoMesgBuf.dramAddr = dest;
       dmaIoMesgBuf.devAddr = (u32)src;
       dmaIoMesgBuf.size = len;
       osEPiStartDma(carthandle,
          (void) osRecvMesg(&dmaMessageQ,
          &dummyMesg, OS_MESG_BLOCK
    }

See Also
osPiRawStartDma
osPiStartDma
osEPiRawStartDma
osCartRomInit
osSendMesg
osJamMesg

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 March 1998