CONTENT:

   dma.h
   dma1.c
   dma2.s

WHAT ARE THESE FILES:

These files contain MPC8240 (Kahlua) DMA controller
driver routines. The driver routines are not 
written for any specific operating system. 
They serves the purpose of code sample, and 
jump-start for using the MPC8240 DMA controller.

For the reason of correctness of C language
syntax, these files are compiled by Metaware
C compiler and assembler.

ENDIAN NOTATION:

The algorithm is designed for big-endian mode,
software is responsible for byte swapping.

USAGE:

1. The host system that is running on MPC8240 
   or using MPC8240 as I/O device shall link
   the files listed here. The memory location 
   of driver routines shall take into account of 
   that driver routines need to run in supervisor 
   mode and they process DMA controller interrupt.

2. The host system is responsible for configuring
   the MPC8240 including Embedded Utilities Memory 
   Block. Since the DMA controller on MPC8240 can 
   be accessed by either local 603e core or the host 
   that MPC8240 serves as I/O processor through host 
   PCI configuration, it is important that the local
   processor uses EUMBBAR to access its local DMA 
   controller while the PCI master uses I/O 
   processor's PCSRBAR to access the DMA controller 
   on I/O device.

   To qualify whether is EUMBBAR or PCSRBAR, one
   additional parameter is requied from the host
   system, LOCAL or REMOTE so that the base value 
   can be correctly interpreted.

3. If the host system is also using the EPIC unit
   on MPC8240, the system can register the
   DMA_ISR with the EPIC including other
   desired resources.  

   If the host system does not using the EPIC unit
   on MPC8240, DMA_ISR function can be called for 
   each desired time interval.

   In both cases, the host system is free to 
   provide its own interrupt service routine.
  
4. To start a direct mode DMA transaction,
   use DMA_Bld_Curr with the start parameter 
   set to 1.

   To start a chaining mode DMA transaction,
   the application shall build descriptors
   in memory first, next, use DMA_Bld_Desp
   with the start parameter set to 1.

5. DMA_Start function clears, then sets the CS 
   bit of DMA mode register.

   DMA_Halt function clears the CS bit of DMA 
   mode register.

   These functions can be used to start and
   halt the DMA transaction.

   If the chaining descriptors has been
   modified since the last time a DMA 
   transaction started, use DMA_Chn_Cnt
   function to let DMA controller process
   the modified descriptor chain without 
   stopping or disturbing the current DMA 
   transaction.

   It is the host system's responsibility of
   setting up the correct DMA transfer mode 
   and pass the correct memory address parameters.

6. It is the host system's responsibility of
   queueing the DMA I/O request. The host 
   system can call the DMA_ISR with its own
   desired interrupt service subroutines to 
   handle each individual interrupt and queued
   DMA I/O requests.
   
7. The DMA driver routines contains a set 
   of utilities, Set and Get, for host system
   to query and modify the desired DMA registers.