Z80 control. More...

Defines
#define	Z80_HALT_PORT 0xA11100
#define	Z80_RESET_PORT 0xA11200
#define	Z80_RAM_START 0xA00000
	Z80 RAM start address.
#define	Z80_RAM_END 0xA01FFF
	Z80 RAM end address.
#define	Z80_RAM Z80_RAM_START
	Z80 RAM address.
#define	Z80_RAM_LEN ((Z80_RAM_END - Z80_RAM_START) + 1)
	Z80 RAM length in byte.
#define	Z80_YM2612 0xA04000
	Z80 YM2612 port address.
#define	Z80_BANK_REGISTER 0xA06000
	Z80 Bank register address.
#define	Z80_DRV_COMMAND 0xA00100
	Z80 default driver command address.
#define	Z80_DRV_STATUS 0xA00102
	Z80 default driver status address.
#define	Z80_DRV_PARAMS 0xA00104
	Z80 default driver parameters address.
#define	Z80_DRV_COM_PLAY_SFT 0
#define	Z80_DRV_COM_STOP_SFT 4
#define	Z80_DRV_STAT_PLAYING_SFT 0
#define	Z80_DRV_STAT_READY_SFT 7
#define	Z80_DRV_COM_PLAY (1 << Z80_DRV_COM_PLAY_SFT)
	Z80 default driver play command.
#define	Z80_DRV_COM_STOP (1 << Z80_DRV_COM_STOP_SFT)
	Z80 default driver stop command.
#define	Z80_DRV_STAT_PLAYING (1 << Z80_DRV_STAT_PLAYING_SFT)
	Z80 default driver play status.
#define	Z80_DRV_STAT_READY (1 << Z80_DRV_STAT_READY_SFT)
	Z80 default driver ready status.
#define	Z80_DRV_CH0_SFT _Pragma("GCC error \"This method is deprecated, use SOUND_PCM_CH1 instead.\"")
#define	Z80_DRV_CH1_SFT _Pragma("GCC error \"This method is deprecated, use SOUND_PCM_CH2 instead.\"")
#define	Z80_DRV_CH2_SFT _Pragma("GCC error \"This method is deprecated, use SOUND_PCM_CH3 instead.\"")
#define	Z80_DRV_CH3_SFT _Pragma("GCC error \"This method is deprecated, use SOUND_PCM_CH4 instead.\"")
#define	Z80_DRV_CH0 _Pragma("GCC error \"This method is deprecated, use SOUND_PCM_CH1_MSK instead.\"")
#define	Z80_DRV_CH1 _Pragma("GCC error \"This method is deprecated, use SOUND_PCM_CH2_MSK instead.\"")
#define	Z80_DRV_CH2 _Pragma("GCC error \"This method is deprecated, use SOUND_PCM_CH3_MSK instead.\"")
#define	Z80_DRV_CH3 _Pragma("GCC error \"This method is deprecated, use SOUND_PCM_CH4_MSK instead.\"")
#define	Z80_DRIVER_NULL 0
	NULL Z80 driver.
#define	Z80_DRIVER_PCM 1
	Variable rate sample player Z80 driver. It can play a sample (8 bit signed) from 8 Khz up to 32 Khz rate.
#define	Z80_DRIVER_DPCM2 2
	2 channels PCM sample player Z80 driver. It can mix 2 samples (4 bit PCM) at a fixed 22 Khz rate.
#define	Z80_DRIVER_PCM4 3
	4 channels sample player Z80 driver with envelop control. It can mix 4 samples (8 bit signed) at a fixed 16 Khz rate and handle volume (16 levels) for each channel.
#define	Z80_DRIVER_XGM 4
	eXtended VGM music player driver. This driver takes VGM (or XGM) file as input to play music. It supports 4 PCM channels at a fixed 14 Khz and allows to play SFX through PCM with 16 level of priority. The driver is designed to avoid DMA contention when possible (depending CPU load).
#define	Z80_DRIVER_XGM2 5
	eXtended VGM music player driver version 2. This driver takes VGM (or XGM2) file as input to play music. It supports 3 PCM channels at either 13.3 Khz or 6.65 Khz and envelop control for both FM and PSG. It allows to play SFX through PCM with 16 level of priority. The driver supports renforced protection against DMA contention.
#define	Z80_DRIVER_CUSTOM -1
	CUSTOM Z80 driver.
#define	Z80_DRIVER_4PCM_ENV _Pragma("GCC error \"This definition is deprecated, use Z80_DRIVER_PCM4 instead.\"")
#define	Z80_DRIVER_2ADPCM _Pragma("GCC error \"This definition is deprecated, use Z80_DRIVER_DPCM2 instead.\"")
Functions
void	Z80_init (void)
	Initialize Z80 sub system.
bool	Z80_isBusTaken (void)
	Return Z80 BUS taken state.
void	Z80_requestBus (bool wait)
	Request Z80 BUS.
bool	Z80_getAndRequestBus (bool wait)
	Request Z80 BUS if not yet taken.
void	Z80_releaseBus (void)
	Release Z80 BUS.
void	Z80_startReset (void)
	Start Z80 reset.
void	Z80_endReset (void)
	End Z80 reset.
void	Z80_setBank (const u16 bank)
	Set Z80 memory bank.
u8	Z80_read (const u16 addr)
	Read Z80 memory (Z80_RAM).
void	Z80_write (const u16 addr, const u8 value)
	Write to Z80 memory (Z80_RAM).
void	Z80_clear (void)
	Clear Z80 memory.
void	Z80_upload (const u16 dest, const u8 *data, const u16 size)
	Upload data in Z80 memory.
void	Z80_download (const u16 from, u8 *dest, const u16 size)
	Read data from Z80 memory.
u16	Z80_getLoadedDriver (void)
	Return currently loaded Z80 driver.
void	Z80_unloadDriver (void)
	Unload Z80 driver (set NULL driver).
void	Z80_loadDriver (const u16 driver, const bool waitReady)
	Load a Z80 driver.
void	Z80_loadCustomDriver (const u8 *drv, u16 size)
	Load a custom Z80 driver.
bool	Z80_isDriverReady (void)
	Return driver ready state (only for non custom driver).
void	Z80_useBusProtection (u16 signalAddress)
	Enable/disable 68K bus access protection from Z80 (can be used by any sound driver).
void	Z80_setBusProtection (bool value)
	Set temporary 68K BUS protection from Z80 (for sound driver supporting it). You should protect BUS Access during DMA and restore it after. Ex: Z80_setBusProtection(TRUE); DMA_doDma(VRAM, data, 0x1000, 0x100, 2); Z80_setBusProtection(FALSE);.
void	Z80_enableBusProtection ()
	Enable temporary 68K BUS protection from Z80 (for sound driver supporting it). See Z80_setBusProtection(..) for more info.
void	Z80_disableBusProtection ()
	Disable temporary 68K BUS protection from Z80 (for sound driver supporting it). See Z80_setBusProtection(..) for more info.
bool	Z80_getForceDelayDMA (void)
	Returns TRUE if DMA delay is enabled to improve PCM playback.
void	Z80_setForceDelayDMA (bool value)
	This method can be used to improve the PCM playback during music play and while DMA queue is used. Even using the BUS protection with Z80_setBusProtection you may still experience altered PCM playback. With the XGM driver for instance this happens when music contains PSG data (Z80 requires the main BUS to access PSG). By delaying a bit the DMA execution from the DMA queue we let the Z80 to access main bus for a bit of time thus avoiding any stall. The delay is about 3 scanlines so using the force delay DMA will reduce the DMA bandwidth for about 3 vblank lines.

Detailed Description

Z80 control.

Author:: Stephane Dallongeville

Date:: 08/2011

This unit provides Z80 access from the YM2612:

enable / disable Z80
request / release Z80 BUS
upload / download data to / from Z80 memory
set Z80 external Bank
Z80 driver handling

Function Documentation

void Z80_clear ( void )

Clear Z80 memory.

You need to request Z80 BUS before accessing Z80 memory.

See also:: Z80_requestBus(bool)

void Z80_disableBusProtection ( )

Disable temporary 68K BUS protection from Z80 (for sound driver supporting it). See Z80_setBusProtection(..) for more info.

See also:: Z80_setBusProtection(..); Z80_enableBusProtection(..); Z80_disableBusProtection(..)

void Z80_download	(	const u16	from,
		u8 *	dest,
		const u16	size
	)

Read data from Z80 memory.

Parameters:

from	Source address (Z80 memory).
dest	Destination where to write data.
size	Size in byte of data to read.

void Z80_enableBusProtection ( )

Enable temporary 68K BUS protection from Z80 (for sound driver supporting it). See Z80_setBusProtection(..) for more info.

See also:: Z80_setBusProtection(..); Z80_enableBusProtection(..); Z80_disableBusProtection(..)

bool Z80_getAndRequestBus ( bool wait )

Request Z80 BUS if not yet taken.

Parameters:

wait	Wait for BUS request operation to complete.

Returns:: Z80 BUS taken state before calling the function.

bool Z80_getForceDelayDMA ( void )

Returns TRUE if DMA delay is enabled to improve PCM playback.

See also:: Z80_setForceDelayDMA(bool)

u16 Z80_getLoadedDriver ( void )

Return currently loaded Z80 driver.

Possible returned values are:

void Z80_init ( void )

Initialize Z80 sub system.

Request Z80 BUS and reset bank number.

void Z80_loadCustomDriver	(	const u8 *	drv,
		u16	size
	)

Load a custom Z80 driver.

Parameters:

drv	Pointer to the driver binary to load.
size	Size (in bytes) of the driver binary.

void Z80_loadDriver	(	const u16	driver,
		const bool	waitReady
	)

Load a Z80 driver.

Parameters:

driver	Driver to load, possible values are: Z80_DRIVER_NULL Z80_DRIVER_PCM Z80_DRIVER_DPCM2 Z80_DRIVER_PCM4 Z80_DRIVER_XGM Z80_DRIVER_XGM2
waitReady	Wait for driver to be ready.

u8 Z80_read ( const u16 addr )

Read Z80 memory (Z80_RAM).

Parameters:

addr	Address to read (relative to start of Z80_RAM).

You need to request Z80 BUS before accessing Z80 memory.

See also:: Z80_requestBus(bool)

void Z80_requestBus ( bool wait )

Request Z80 BUS.

Parameters:

wait	Wait for BUS request operation to complete.

void Z80_setBank ( const u16 bank )

Set Z80 memory bank.

Parameters:

bank	Bank number to set (0x000-0x1FF)

void Z80_setBusProtection ( bool value )

Set temporary 68K BUS protection from Z80 (for sound driver supporting it).
You should protect BUS Access during DMA and restore it after. Ex:
Z80_setBusProtection(TRUE); DMA_doDma(VRAM, data, 0x1000, 0x100, 2); Z80_setBusProtection(FALSE);.

This way the sound driver will *try* to avoid accessing the 68K BUS during DMA to avoid execution interruption and so preserve PCM playback quality.
Note that depending the sound driver, the success of the operation is not 100% garantee and can fails in some conditions (heavy Z80 load, lot of PSG data in XGM music).
In that case you can also try to use the Z80_setForceDelayDMA() method to help improving the PCM playblack.

See also:: Z80_useBusProtection(..); Z80_enableBusProtection(..); Z80_disableBusProtection(..)

void Z80_setForceDelayDMA ( bool value )

This method can be used to improve the PCM playback during music play and while DMA queue is used.
Even using the BUS protection with Z80_setBusProtection you may still experience altered PCM playback. With the XGM driver for instance this happens when music contains PSG data (Z80 requires the main BUS to access PSG).
By delaying a bit the DMA execution from the DMA queue we let the Z80 to access main bus for a bit of time thus avoiding any stall. The delay is about 3 scanlines so using the force delay DMA will reduce the DMA bandwidth for about 3 vblank lines.

Parameters:

value TRUE or FALSE

See also:: Z80_getForceDelayDMA(); Z80_setBusProtection()

void Z80_upload	(	const u16	dest,
		const u8 *	data,
		const u16	size
	)

Upload data in Z80 memory.

Parameters:

dest	Destination address (Z80 memory).
data	Data to upload.
size	Size in byte of data to upload.

void Z80_useBusProtection ( u16 signalAddress )

Enable/disable 68K bus access protection from Z80 (can be used by any sound driver).

Parameters:

signalAddress Z80 RAM address used (relative to the start of Z80 RAM) to set the BUS protection signal.
Signal is set to 1 when main BUS should not be accesssed from Z80 (DMA operation in progess), set to 0 otherwise.

void Z80_write	(	const u16	addr,
		const u8	value
	)

Write to Z80 memory (Z80_RAM).

Parameters:

addr	Address to write (relative to start of Z80_RAM).
value	Value to write.

You need to request Z80 BUS before accessing Z80 memory.

See also:: Z80_requestBus(bool)

Defines

Functions

Detailed Description

Function Documentation