 **************************************************************************
 * mach64 Chapter 5 sample code                                           *
 *                                                                        *
 * Copyright (c) 1994-1998 ATI Technologies Inc.  All rights reserved.    *
 **************************************************************************

The purpose of this chapter code is to demonstrate mach64 engine
initialization.  This chapter's code is an upgrade of chapter 4 code
with the addition of setting up the engine.

The load_and_set_mode was augmented to include palette initialization
and palettized initalization as the case may be.  Saving and restoring
the pld palette was also implemented.  These additions resulted in the
creation of the palette.c file which contains all the necessary
primitives.  A palette structure was also created for these functions.

The enable_aperture function was also augmented to perform further
checks using the query structure, and also enable the standard VGA
aperture as well.

Setting up the engine context involved reading and writing to registers.
Function to access I/O mapped registers and Memory Mapped registers
were implemented in ioreg.c and memreg.c respectively.  For the I/O
registers: 32, 16, and 8 bit access is possible.  The non GUI registers
are both I/O mapped and memory mapped.  An array was created to hold
their addressing information.  The GUI memory mapped only registers are
set up as defines in the atim64.h file.

The init.c file now contains primitives to initalize the engine to a
known state and to reset the engine.  A few FIFO primitives were also
needed for engine operations.  These are wait_for_idle, and
wait_for_fifo.  They are found in wait.c.

In much the same way chapter 3 code sets the mode and waits for user
keyboard input, chapter 5 code works in a similar fashion.  The
additions include enabling the aperture and initializing the engine.

Upon completion, the old palette is restored, as is the old video text
mode.  Finally, the query data structure, I/O info, and mode information
are displayed.


The following files are included with this chapter:

readme  .txt
main    .h
defines .h
atim64  .h
init    .c
m64bios .c
glob    .c
colour  .c
palette .c
wait    .c
ioreg   .c
memreg  .c
engine  .c
makefile
engine  .exe


The following primitives and globals were added/enhanced from chapter 4:

// Functions in memreg.c

int regw (unsigned int regindex, unsigned long regdata);
unsigned long regr (unsigned int regindex);

// Functions in ioreg.c

int iow32 (unsigned int ioindex, unsigned long iodata);
unsigned long ior32 (unsigned int ioindex);
int iow16 (int regindex, int word_offset, unsigned short iodata);
unsigned short ior16 (int regindex, int word_offset);
int iow8 (int regindex, int byte_offset, char iodata);
char ior8 (int regindex, int byte_offset);

// Functions in init.c

void reset_engine (void);
void init_engine (void);

// Functions in m64bios.c

int load_and_set_mode (int xres, int bpp, int pitch);
int enable_aperture (void);

// Functions in palette.c

void set_palette (int index, palette entry);
palette get_palette (int index);
void save_palette (palette *palettebuffer);
void restore_palette (palette *palettebuffer);
void init_palette (void);
void init_palettized (void);

// Functions in wait.c

void wait_for_idle (void);
void wait_for_fifo (int entries);
void terminate (int idle_problem);


// Globals.

extern reg_table REGISTER[30];
extern palette SAVEPALETTE[256];
