**
**	file: Z80.i
**
** General Z80 emulator definitions and declarations. The control structure
** is defined in Z80_struct.i

	IFND Z80_INCLUDE
Z80_INCLUDE SET 1

** =========================================================================


** All sizes and offsets are in bytes:


	;The amount of bytes needed for the Z80 memory space

Z80_MEMSIZE	EQU	$10000


	;These are uninteresting to the normal user

Z80_LBUFSIZE	EQU	16
Z80_HBUFSIZE	EQU	16
Z80_0_OFFSET	EQU	$8000
CACHE_0_OFFSET	EQU	Z80_LBUFSIZE+(2*Z80_0_OFFSET)
ATTRS_0_OFFSET	EQU	Z80_0_OFFSET


	;The size of the memory used for the cache.
	;The allocated memory must be word-aligned!

Z80_CACHESIZE	EQU	(2*Z80_MEMSIZE)+Z80_LBUFSIZE+Z80_HBUFSIZE


	;The space needed for memory control attributes

Z80_ATTRMEMSIZE EQU	Z80_MEMSIZE


**  Memory write access control attributes:
**
**	Memory attribute values (unsigned byte):
**
**		0		write allowed (no detection)
**		1 to 126	user-defined handler call
**		127		read-only
**
**	Call Z80_SetMemAttr (described below) to set these attributes.
**	In particular, bit 7 of each attribute byte is used internally
**	and should not be modified or interpreted as part of the value.
**
**	If an attempt is made to write to an address whose attribute is
**	in the range 1 to 126, then if the field Z80_MemHandler is
**	nonzero, a call is made to the address it points to. If it is
**	zero, the value is written as if the attribute was 0.
**
**	The user memory handler is called with the following parameters:
**
**		d0 contains the exception number (longword, range -128
**		   to 127).
**
**		d1 contains the value (longword, range -128 to 127).
**
**		d2 contains the Z80 address (longword, range -32768 to
**		   32767).
**
**		a0 is scratch (address of user handler).
**
**	All other registers must be protected before they are modified.
**
**	The handler should return the following values:
**
**		d0 (longword) nonzero if value should be written, zero
**		   if not.
**
**		d1 (low byte) contains the value.
**
**	Changes to d2 and a0 have no effect.
**
**	The user-defined handler call has some overhead, and is not
**	recommended for memory addresses/areas that are written to very
**	often, like bit-mapped display memory. More suitable
**	applications are e.g. memory-mapped I/O and character-mapped
**	display memory.
**
**	For certain reasons, it is not possible to extract any
**	information about the current Z80 CPU status during a memory
**	handler call. Single-step procedures in combination with memory
**	write access checking could be used for such purposes.
**
**	Example in C:
**
**		Z80_SetMemAttr(Control, 0x4000, 0x1B00, Z80_MEM_ROM);
**
**	Flags the area from $4000 to $5AFF as ROM.

;(These values are hard-coded in the detection and handler routines.)

Z80_MEM_ROM	EQU	127
Z80_MEM_RAM	EQU	0

** -------------------------------------------------------------------------


	IFND Z80_NOXREF


		** Emulator functions **


** Initialisation:

** Before beginning emulation, the control structure must be initialised by
** calling Z80_Init. This also initialises the cache memory.
**   a0 must point to the control structure. The fields Z80_Memory and
** Z80_CacheMem must be initialised to point to allocated memory. If the
** memory write access checking feature is used, the field Z80_AttrMem must
** also be initialised, and if Z80_MemHandler is nonzero it is assumed to be
** a pointer to a user memory exception handler. See MemoryHandler below for
** details.
**   The user environment data area is not changed. All other fields (apart
** from those mentioned above) are automatically initialised to zero. The
** CPU status substructure is set up as after a reset.
**   The value returned in d0 is nonzero if an error occurred, and zero
** otherwise. All other registers are automatically protected.

	XREF Z80_Init


** Cold start:

** The emulation is started 'from scratch', with a CPU reset. a0 must point
** to the control structure, which must be initialised (see Z80_Init above).
**   The return value in d0 is nonzero if an error occurred, and zero
** otherwise. All other registers are automatically protected.

	XREF Z80_Coldstart


** Warm start:

** The emulation is resumed as if nothing happened since last exit (unless
** the saved processor status has been manipulated). Changes to other fields
** than the CPU status substructure entries are not recommended; calling
** Z80_Continue does not guarantee that such changes have any effect (see
** Z80_NewSettings below).
**   a0 must point to the control structure.
**   The return value in d0 is the same as for Z80_Coldstart. All other
** registers are automatically protected.

	XREF Z80_Continue


** Refreshing the internal data after modifications:

** This subroutine makes the emulator update the private fields of the
** control structure when any of the public fields outside the CPU status
** substructure have been modified, for instance if the Z80_Memory field is
** changed. It must not be called while the emulator is running.
**  a0 must point to the control structure.
**  The return value in d0 is nonzero if an error occurred, and zero
** otherwise.
**
** Memory reallocation example:
**
** Call Z80_EXITreq and make sure the emulator has stopped before
** reallocating memory (remember to copy the old memory contents to the new
** areas), then update the corresponding entries in the control structure
** (Z80_Memory, Z80_Cachemem and Z80_Attrmem). Calling Z80_NewSettings will
** then make sure that Z80_Continue will properly resume the emulation from
** the new addresses.
**
**   Note that the control structure can be moved whenever the emulator is
** not running, without doing anything other than passing the new address to
** Z80_Continue.

	XREF Z80_NewSettings


** Request making subroutines:
**
** These routines emulate the CPU request lines (including requests to halt
** the emulation). Requests are currently only tested for after flow control
** instructions and memory wrap-around, but that seems to be quite
** sufficient.
**   A request overrides those of lower priority. The priority order
** (from highest to lowest) is: EXIT, RESET, BUSRQ, NMI and INT. BUSRQ is
** currently not implemented. The status of other requests is stored while
** one request is handled, and no requests are lost.
**    Note that the emulation clears a signal automatically after it has
** been detected and acted upon (or has been ignored). A possible future
** extension is to include a complete model of the CPU pins.
**   The requests could be called from hardware interrupts, keypresses,
** menus or whatever. They do not affect any registers (apart from CCR), and
** return nothing. They are not sensitive to concurrent accessing of the
** shared data (no protected mode or semaphores needed).
**  a0 must contain a pointer to the control structure.

	XREF Z80_EXITreq

	XREF Z80_RESETreq

	XREF Z80_NMIreq

	XREF Z80_INTreq

** -------------------------------------------------------------------------

		** Utility functions **


** Routines to access the Z80 address space:
**
** These routines mirror any memory changes in the cache and handle the
** wraparound of addresses transparently. I recommend that they are used
** rather than writing directly into the Z80 address space. They do *not*
** respect any memory protection attributes - a write always takes effect.
**   All need a pointer to the control structure in a0. The Z80 address
** (word-sized) is passed in d0 (for block functions this is the block start
** address).
**
**	Z80_SetByte is passed a byte value to be written in d1. It
**	returns nothing.
**
**	Z80_SetWordLH is passed a (big-endian) word-sized value in d1
**	and writes it (little-endian) to Z80 memory. It returns nothing.
**
**	Z80_GetByte returns the read byte value in d0.
**
**	Z80_GetWordLH reads a (little-endian) word-sized value and
**	returns it (in big-endian form) in d0.
**
** All block functions are passed the block size (an unsigned longword) in
** d1. They return nothing.
**
**	Z80_SetBlock is passed the byte value to be written in d2.
**
** Z80_ReadBlock and Z80_WriteBlock are passed the buffer address (in the
** 680x0 address space) in a1.
**
** All Z80 address arithmetic is word-sized. For instance, calling
** Z80_SetWordLH(ctrl, $ffff, $1234) will store $34 in Z80 address $ffff and
** $12 in address $0000. The block functions will also wrap at $ffff.

	XREF Z80_SetByte	;(a0,d0,d1)

	XREF Z80_SetWordLH	;(a0,d0,d1)

	XREF Z80_GetByte	;(a0,d0)

	XREF Z80_GetWordLH	;(a0,d0)

	XREF Z80_SetBlock	;(a0,d0,d1,d2)

	XREF Z80_ReadBlock	;(a0,a1,d0,d1)

	XREF Z80_WriteBlock	;(a0,a1,d0,d1)


** Accessing memory attributes:
**
** Z80_SetMemAttr sets the memory attributes for a block of Z80 memory to
** a specific value. It takes a pointer to the control structure in a0, a
** Z80 block start address in d0 (low word), the block size (an unsigned
** longword) in d1 and the attribute value in d2 (low byte). Nothing is
** returned.
**
** Z80_GetMemAttr returns the memory attribute value for a single address.
** It takes a pointer to the control structure in a0 and a Z80 address in d0
** (low word). It returns the attribute value in d0.
**
** For ranges of attribute values, see the section on memory attributes
** above.

	XREF Z80_SetMemAttr	;(a0,d0,d1,d2)

	XREF Z80_GetMemAttr	;(a0,d0)


	ENDC ;IFND Z80_NOXREF

** =========================================================================

	ENDC ;IFND Z80_INCLUDE