/******************************************************************************
 *
 * Copyright (c) 2003, ACEECA Limited. All rights reserved. 
 *
 * File: MeazuraLib_V300b.h
 *
 * Release: 8th June 2004, 
 *					MzLibVersion = 3,0,0,sysROMStageBeta,5
 *
 * Description:
 *		Meazura library API definitions.  
 *
 * History:
 *	V300b:
 *	19-Dec-03	HD: Swapped the definitions for PeripheralUSBCradle and PeripheralRS232Cradle 
 *								to agree with the API.
 *	20-Jan-04	HD: Added more baudrate enumerations for UARTcontrolCodeSetBaudRate. 
 *	18-Feb-04	HD: Incorporated two new enumerations for MzParallelControl which are: 
 *								ParallelControlCodeEnableCS0 and ParallelControlCodeDisableCS0. 
 *								These new enumerations will give the developer the ability to disable 
 *								CS0 and use it as a GPIO pin if required.
 *	18-Feb-04	HD: Added ParallelControlCodeGPIOSetCS1, ParallelControlCodeGPIOGetCS1, 
 *								ParallelControlCodeGPIOSetCS0, ParallelControlCodeGPIOGetCS0 to the 
 *								Parallel control enumerations.
 *	20-Feb-04	HD: Improved the header document to be more compatible with GCC compilers as 
 *								well as adding better descriptions for the *value parameter for each enumeration.
 *	23-Feb-04	HD: Changed MOD_PWR and MOD_RESET to be inputs pulled low on exit of the API 
 *								library. They were previously being driven low.
 *	30-Mar-04	HD: Was not checking null pointer errors for ModuleControlCodeUART2ViaModule. 
 *								The enumeration now returns mzNullPointerError if the boolean value given is a 
 *								NULL pointer.
 *	30-Mar-04	HD: Incorporated checking of requested MZIO functionality to see if it being currently 
 *								used by the system. If the function requested is being used by the system the 
 *								mzHwFunctionBusy error is returned. This checking incurs a small overhead on all the 
 *								routines listed to the right.
 *	V301b		
 *	1-Apr-04	HD: Added a UARTcontrolCodeSetCustomBaudrate so that the caller can set a custom baudrate 
 *								if the standard baudrates listed are insufficient. 	
 *	19-Apr-04	HD:	Changed numberOfBytes in MzSPITransferData and MzSPIReceiveData to be numberOfWords.
 *						HD:	Changed the documentation to make clear the arguments in MzSPITransferData, MzSPIReceiveData
 *								MzUARTTrasmitData and MzUARTReceiveData. 
 *	22-Apr-04	HD:	SPIcontrolCodeEnablePort now checks for a NULL pointer error on valueP.
 *	 					HD: ParallelControlCodeGPIOSetCS1, ParallelControlCodeGPIOGetCS1, ParallelControlCodeGPIOGetCS0, ParallelControlCodeGPIOSetCS0
 *								now check for NULL pointers before using valueP. 
 *						HD:	MzLibSleep and MzLibWake now check for NULL pointers when accessing the library globals structure. 
 *	12-May-04	HD:	Fixed bug in V300b library where when changing UART1 baudrate, debugging data was being
 *								output from the library via UART1 port.  
 *	V302b		
 *	4-Jun-04	HD: Corrected the bug where the signals returned from MzGPIOGetValue for the UART_TX and UART_RX masks were 
 *								swapped around.  	
 *	8-Jun-04	HD:	Corrected the bug where non-zero bit values were being returned by MzGPIOGetValue for the un-masked bits.
 *								The function now only returns the bit field representing the GPIO lines defined in the mask fiel, 
 *								all other bits are zeroed.
 *						HD: Corrected the bug where ModuleControlCodeMOD_PWRGet was setting the MOD_POWER pin to dedicated functions instead 
 *								of GPIO.    	
 *						HD: ParallelControlCodeGPIOGetCS1 and ParallelControlCodeGPIOGetCS0 have been modified to return
 *								a true boolean value when returning the state of the corresponding pin.
 *							 	
 *	V303b
 *	7-Oct-04	HD:	UARTcontrolCodeSetBaudRate for baudrates greater than UARTBaudRate230400 in the enum list
 *								was causing a problem when checking for a valid baudrate value. This has now been changed
 *								to reference the maximum enum to UARTBaudRateLast.
 *	24-Nov-04	HD: Found that external 100K pull downs on MOD_RESET and MOD_PWR were not sufficient to keep 
 *								these lines low resulting in ~1.5V on the pins. On MOD_PWR this can sometimes result in 
 *								the unit losing power overnight as it is drained by the module. The software now pushes 
 *								these lines low when the library exits. Please note that if these pins are driven high
 *								from an external source, there is a potential to short circuit the pin causing undesirable
 *								results. It is advised that if the pins are being used as GPIO inputs, series resistors
 *								be placed on the respective lines to limit the current into the pins.	
 *						HD: Instead of generating a fatal exception alert, now MeazuraErrParam is returned when 
 *								the version pointer is a NULL value.
 * 	18-Jan-05 HD: Will now always check the peripheral resistor data is up to date by reading the value of the
 *								resistor directly. Was previously relying on the value of updated globals. 
 *						HD:	Corrected a bug in MzGetPeripheralID where by PeripheralNoDevicePresent was being returned in
 *								the place of Peripheral560K. 
 *	15-Mar-05	HD:	Changed MzLibClose to NOT set UART2 to channel to the cradle interface by default. It now remains sticky
 *								even when the Meazura API library is closed. 
 *	31-Mar-05	HD:	Modified the ParallelControlSetCS1Size opcode in MzParallelControl so that it doesn't
 *								always return an error code. The error code was being returned even if the hardware 
 *								wasn't busy, hence not changing the size of the chip select. 
 *
 *	V304b
 *	9-May-05	HD:	Found that ParallelControlCodeEnableCS1 and ParallelControlCodeDisableCS1 were only addressing
 *								reconfiguration of the physical pin to be routed via the chip select function. The actual chip
 *								select was however not being enabled. Upon reset, the chip select was set to be enabled 
 *								by the HAL and hence didn't cause a problem previously. However now that compact flash 
 *								specifically disables the chip select if a CF card is not found, an bus error is 
 *								generated causing Fatal Exception alerts. This has now been addresssed. 
 *
 *	V305
 *	02-Sep-05	HD:	Incorporated error checking in MzLibGetVersion if SysGetROMToken fails, such as times when the 
 *								token doesn't exist.
 *
 *
 *
 *****************************************************************************/

#ifndef __MEAZURA_LIB_H__
#define __MEAZURA_LIB_H__

// If we're actually compiling the library code, then we need to
// eliminate the trap glue that would otherwise be generated from
// this header file in order to prevent compiler errors in CW Pro 2.
#ifdef BUILDING_Meazura_LIB
	#define Meazura_LIB_TRAP(trapNum)
#else
	#define Meazura_LIB_TRAP(trapNum) SYS_TRAP(trapNum)
#endif


#ifdef __MWERKS__
#pragma	mark Library Version
#endif
/********************************************************************
 * Library Version
 ********************************************************************/
// The library version scheme follows the system versioning scheme.
// See sysMakeROMVersion and friends in SystemMgr.h.
//
// For reference:
//
// 0xMMmfsbbb, where MM is major version, m is minor version
// f is bug fix, s is stage: 3-release,2-beta,1-alpha,0-development,
// bbb is build number for non-releases 
// V1.12b3   would be: 0x01122003
// V2.00a2   would be: 0x02001002
// V1.01     would be: 0x01013000
#define MzLibVersion	sysMakeROMVersion(3, 0, 0, sysROMStageBeta, 5)


/********************************************************************
 * Meazura Feature Numbers
 ********************************************************************/
#define		MzFeatureCreator						'AFtr'		// ACEECA's feature creator


// Feature number for ROM version
#define 	MzFeatureIDVersion					'rs' 																							// Feature number for ROM version

// Feature number for flash disk
#define 	MzFeatureFlashDiskVersion		2																									// Feature number for flash disk 		


/********************************************************************
 * Type and creator of Meazura Library database
 ********************************************************************/
#define		MzLibCreatorID				'MAPI'		// Meazura Library database creator
#define		MzLibTypeID						'libr'		// Standard library database type

/********************************************************************
 * Internal library name which can be passed to SysLibFind()
 ********************************************************************/
#define		MzLibName							"MeazuraAPILibrary"		

/********************************************************************
 * Registered Meazura notifications
 ********************************************************************/
#ifdef __MWERKS__
#pragma mark Meazura Notifications 
#endif
#define		MzAlmNotification			'MZAL'		// External alarm notification
#define		MzPerpNotification		'MZPE'		// Peripheral change notification
#define		MzModuleNotification	'MZMD'		// Module interrupt notification 
#define		MzWakeupNotification	'MZWK'		// Wakeup notification 

// Note: 
//		All of these notifications have NULL notify data pointers, ie. no system data
//		returned with the notification. They however support user data pointers that 
//		can be set up using SysNotifyRegister.
//		
//		When catching a MzPerNotification you can request peripheral information 
//		using the MzGetPeripheralID API.
//

#ifdef __MWERKS__
#pragma mark Meazura Key Bit definitions
#endif
/********************************************************************
 * Meazura key bit definitions
 ********************************************************************/
#define		MzLeftKeyBit					keyBitHard1		
#define		MzCentreKeyBit				keyBitHard2		
#define		MzRightKeyBit					keyBitHard3	 
#define		MzUpKeyBit			 			keyBitPageUp
#define		MzDownKeyBit		 			keyBitPageDown
#define		MzPowerKeyBit		 			keyBitPower

#ifdef __MWERKS__
#pragma mark Meazura Virtual Key definitions
#endif
/********************************************************************
 * Meazura virtual keys definitions
 ********************************************************************/
#define		MzVLeftKey						chrLeftArrow		
#define		MzVCentreKey					vchrHard1		
#define		MzVRightKey						chrRightArrow	 
#define		MzVUpKey			 				vchrPageUp
#define		MzVDownKey		 				vchrPageDown
#define		MzVPowerKey		 				vchrAutoOff

#define		MzVirtualKeyMin				0x1D00
#define 	MzVirtualKeyMax				0x1D0F
#define		MzBarcodeReceivedKey	0x1D00		// enqueued when a valid barcode is received
#define		MzBatteryTriggerOn		0x1D01		// enqueued when the trigger  
#define		MzBatteryTriggerOff		0x1D02		// enqueued when the trigger  


/************************************************************
 * Meazura Library result codes
 * (appErrorClass is reserved for 3rd party apps/libraries.
 * It is defined in SystemMgr.h)
 *************************************************************/
#ifdef __MWERKS__
#pragma mark Error Codes 
#endif

#define MeazuraErrParam							(oemErrorClass | 0x1)		// invalid parameter
#define MeazuraErrNotOpen						(oemErrorClass | 0x2)		// library is not open
#define mzLibAlreadyOpen						(oemErrorClass | 0x3)		// returned from MzLibClose() if the library is still open by others
#define mzMemoryError								(oemErrorClass | 0x4)		// memory error occurred
#define mzHwFunctionNotSupported		(oemErrorClass | 0x5)		// the function being accessed is not available on the current hardware
#define mzHwFunctionBusy						(oemErrorClass | 0x6)		// the function being accessed is being accessed by someone else

// API error codes
#define mzNullPointerError					(oemErrorClass | 0xA)		// Error setting the alarm
#define mzSetAlarmError							(oemErrorClass | 0xB)		// Error setting the alarm
#define mzCommsError								(oemErrorClass | 0xC)		// Error communicating with external processor
#define mzControlCodeError					(oemErrorClass | 0xD)		// Unrecognised control code
#define mzTimeOutError							(oemErrorClass | 0xE)		// Baud rate to SPI controller unrecognised
#define mzBadBaudRateError					(oemErrorClass | 0x10)	// Baud rate unrecognised
#define mzConfigError								(oemErrorClass | 0x11)	// Error setting up the configuration

#define mzNullCallbackProcPtrError	(oemErrorClass | 0x12)	// Null callback function pointer 
#define mzNullCallbackDataPtrError	(oemErrorClass | 0x13)	// Null callback data pointer 

#define mzUARTOverrunError					(oemErrorClass | 0x14)	// UART has received an overrun error
#define mzUARTFrameError						(oemErrorClass | 0x15)	// UART has received a frame error
#define mzUARTParityError						(oemErrorClass | 0x16)	// UART has received parity error

#define mzParallelChipSelectError		(oemErrorClass | 0x17)	// Unrecognised chip select
#define mzParallelOffsetError				(oemErrorClass | 0x18)	// Offset is out of range
#define mzParallelDataSizeError			(oemErrorClass | 0x19)	// The size and offset specified is out of the addressable chip select range 

#define mzGPIOPinBusyError					(oemErrorClass | 0x1A)	// The pin is currently being used by some dedicated function 

#define mzNoFIFODataError						(oemErrorClass | 0x1B)	// This error is returned when there is no data in the receive FIFO
#define mzPortNotOpenError					(oemErrorClass | 0x1C)	// Returned when the port is not openned.


#ifdef __MWERKS__
#pragma mark -
#endif
/********************************************************************
 * Callback function prototypes
 ********************************************************************/
typedef void (*ModuleCallbackPtr) (MemPtr userData);
typedef void (*SPICallbackPtr) (UInt8 SPIIntStatus, MemPtr userData);
typedef void (*UARTCallbackPtr) (UInt8 UARTIntStatus, MemPtr userData);

/********************************************************************
 * Public Structures
 ********************************************************************/
typedef struct MzCallbackType 
{
	void*	callbackProcPtr;										// pointer to a callback procedure when SPI interrupt occurs
	void*	callbackDataPtr;										// pointer to a user specified callback data structure passed to the interrupt
} MzCallbackType;
typedef MzCallbackType*		MzCallbackPtr;

typedef struct MzVersion 
{
	UInt32	APIVersion;												// The version of the API
	UInt32	PICVersion;												// The firmware version of the keypad board processor
	UInt32	ROMVersion;												// The ROM OS version
	UInt32	HardwareVersion;									// The hardware version, format 0xMMxxxbbb, MM - major version, bbb - minor version, x - don't care  
} MzVersion;
typedef MzVersion*		MzVersionPtr;



#ifdef __MWERKS__
#pragma mark Alarm API structures
#endif
// -------------------------------------------------------------------//
// Alarm API structures
// -------------------------------------------------------------------//
typedef struct MzAlarmType
{
	Int8 		second;														// start time second (00 - 59)
	Int8 		minute;														// start time minute (00 - 59)
	Int8 		hour; 														// start time hour (00 - 23)
	Int8 		day; 															// start time day (1 - 31), see notes
	Int8		prdUnits;													// period units, see description below
	Int8 		period;														// period (0 - 255)
	Int16 	maxAlarmCnt;											// maximum alarm count (0 = no limit)
	Int8	 	almConfig;												// Alarm configuration register
} MzAlarmType;
typedef	 MzAlarmType* MzAlarmPtr;

// Periodic units supported
#define tenMsUnits 						0x40					// 10ms unit 
#define secondsUnits 					0x01					// seconds unit
#define minutesUnits 					0x02					// minutes unit
#define hoursUnits 						0x04					// hourly unit
#define daysUnits 						0x08					// daily unit
#define weeksUnits 						0x10					// weekly unit
#define monthsUnits 					0x20					// montly unit

// Alarm configuration types 
#define wakeOS_onAlarm 				0x01
#define wakeModule_onAlarm 		0x02
#define powerupUnit_onAlarm 	0x04  				// Not currently supported
#define kybSleep_afterAlarm 	0x08	

#ifdef __MWERKS__
#pragma mark SPI API structures
#endif
// -------------------------------------------------------------------//
// SPI API structures
// -------------------------------------------------------------------//
typedef enum MzSPIControlCodeEnum
{
	SPIcontrolCodeEnablePort,									
		// Enables the SPI hardware. This should be done before accessing
		// other SPI configurations. 
		// *valueP = (UInt8) Pins to be used for SPI (see GPIO control API structures) eg. SPI_MOSI etc.

	SPIcontrolCodeDisablePort,								
		// Disables the SPI hardware
		// valueP = NULL
		
	SPIcontrolCodeEnableInterrupts,						
		// Enables interrupts in the interruptType register
		// *valueP = (UInt8) Interrupt types supported, eg. SPITxFIFOEmpty etc.
		
	SPIcontrolCodeDisableInterrupts,					
		// Disables all currently configured SPI interrupts
		// valueP = NULL
		
	SPIcontrolCodeSetConfiguration,						
		// Sets the configuration bits in the config register
		// *valueP = (UInt16) configuration tuple eg. SPIPortIsMaster etc.
		
	SPIcontrolCodeSetBaudRate,								
		// Sets the baud rate divisor in the baudRate register
		// *valueP = (UInt16) baud rate tuple eg. SPIbaudRateSysClkDiv4 etc.
		
	SPIcontrolCodeSetSamplePeriod,						
		// Sets the amount of time between samples in master mode. 
		// *valueP = (UInt16) sample period value. Bitwise OR with samplePeriodSelect32khz
		// to get the 32kHz clock instead of SPI clock (33Mhz/divisor)
		
	SPIcontrolCodeSetBitsToTransfer,					
		// Sets the number of bits to transfer in the numberOfBits register
		// *valueP = (UInt8) number of bits to transfer (1 to 16)
		
	SPIcontrolCodeFlushReceiveFIFO,						
		// Flushes the receive fifo of the SPI
		// valueP = NULL
		
	SPIcontrolCodeSetCallbackProc							
		// Sets the callback function for SPI interrupt processing
		// *valueP = (MzCallbackPtr) callback data information callbackProcPtr, callbackDataPtr
} MzSPIControlCodeEnum;

// Divisors for SPI baudRate (SPICONT1 register), SYSCLK= 33Mhz
#define SPIbaudRateSysClkDiv4		0x0000
#define SPIbaudRateSysClkDiv8		0x2000
#define SPIbaudRateSysClkDiv16	0x4000
#define SPIbaudRateSysClkDiv32	0x6000
#define SPIbaudRateSysClkDiv64	0x8000
#define SPIbaudRateSysClkDiv128	0xA000
#define SPIbaudRateSysClkDiv256	0xC000
#define SPIbaudRateSysClkDiv512	0xE000
#define	SPIbaudRateMask					0xE000			// Data Rate mask

// SPI interrupt types supported (high byte of SPIINTCS register)
#define SPITxFIFOEmpty 			0x01						// Interrupts when the transmit FIFO is empty
#define	SPITxFIFOHalf				0x02						// Interrupts when the transmit FIFO has 4 words or fewer
#define	SPITxFIFOFull				0x04						// Interrupts when the transmit FIFO is full
#define	SPIRxFIFOReady			0x08						// Interrupts when the receive FIFO is ready with at least 1 byte/word of data
#define	SPIRxFIFOHalf				0x10						// Interrupts when the receive FIFO has at least 4 words 
#define	SPIRxFIFOFull				0x20						// Interrupts when the receive FIFO is full
#define	SPIRxFIFOOverflow		0x40						// Interrupts when the receive FIFO overflows
#define	SPIBitCountOverflow	0x80						// Interrupts when the bit count overflows, see note 1

// SPI configuration types (SPICONT1 register)
#define	SPIDRActiveLow			0x1000					// Configures Data Ready to be active low
#define	SPIDRFallingEdge		0x0800					// Configures Data Ready to be falling edge
#define	SPIPortIsMaster			0x0400					// Configures the SPI to be the master
#define	SPISSPolarityIsHigh	0x0080					// Makes the SS active high
#define	SPISSWaveformSelect	0x0040					// See note 2 below
#define	SPIPhaseBitSet			0x0020					// See note 3 below
#define	SPIPolarityBitSet		0x0010					//

// SPI bits to transfer mask (SPICONT1 register)
#define SPIBitCountMask			0x000F

// Sampling period clock type (SPISPC register)
#define samplePeriodSelect32khz 	0x8000		// If set=32kHz selected, otherwise SPICLK selected.
#define sampleNumberOfClocksMask 	0x7FFF		// 15-bits for setting up how many clocks between samples
/* 
// -------------------------------------------------------------------//
	Notes:
// -------------------------------------------------------------------//
	1:
		BitCountOverflow interrupt
		This interrupt is generated if the SPI controller is place in slave mode where
		the SPI receive FIFO is advanced by the SS rising edge. An interrupt occurs if
		at least 1 of the data locations in the receive FIFO had received more than 16 bits
		in one burst. This interrupt can be cleared by reading the SPI data. There is 
		nothing to indicate which data word has overflowed, hence the bad data word may
		still be in the receive FIFO if it is not empty.
			
	2:
		SPISSWaveformSelect
		In master mode this bit selects the output wave form for the SS signal.
		In slave mode, this bit controls RxFIFO	advancement.
		Master Mode:
		0 = SS stays low between SPI 1 bursts
		1 = Insert pulse between SPI 1 bursts
		Slave Mode:
		0 = RxFIFO advanced by Bit Count
		1 = RxFIFO advanced by SS rising edge
	
	3:
		SPIPhaseBitSet and SPIPolarityBitSet
		
		SPIPolarityBitSet = 1, SPIPhaseBitSet = 1 
		______     ___     ___     ___      _     ________
		      |___|   |___|   |___|   |_.... |___|	

		SPIPolarityBitSet = 1, SPIPhaseBitSet = 0 
		__________     ___     ___     _    _____     ____
				      |___|   |___|   |___| ....     |___|	

		SPIPolarityBitSet = 0, SPIPhaseBitSet = 1 
				   ___     ___     ___     _      ___ 
		______|   |___|   |___|   |___| ...._|   |________	

		SPIPolarityBitSet = 0, SPIPhaseBitSet = 0 
				       ___     ___     ___            ___ 
		__________|   |___|   |___|   |_...._____|   |____	

		______ _______  _______  _______      _______ ____ 
					|__DN___||__DN-1_||__DN-2_|....|__D0___|	

*/

#ifdef __MWERKS__
#pragma mark UART API structures
#endif
// -------------------------------------------------------------------//
// UART API structures
// -------------------------------------------------------------------//
typedef enum MzUARTControlCodeEnum
{
	UARTcontrolCodeEnablePort,								
		// Enables the UART hardware. This should be done before accessing
		// other UART configurations. 
		// *valueP = (UInt8) UART configuration tuple, eg. UARTReceiverEnable etc
		
	UARTcontrolCodeDisablePort,								
		// Disables the UART hardware
		// valueP	= NULL
		
	UARTcontrolCodeEnableInterrupts,					
		// Enables interrupts in the interruptType register
		// *valueP = (UInt8) Interrupt type tuple eg. UARTTxFIFOAvailable
		
	UARTcontrolCodeDisableInterrupts,					
		// Disables all currently configured UART interrupts
		// valueP = NULL
		
	UARTcontrolCodeSetBaudRate,								
		// Sets the baud rate of the UART in bits/s
		// *valueP = (UInt8) baud rate enum, eg. UARTBaudRate2400 etc.
		
	UARTcontrolCodeFlushReceiveFifo,					
		// Flushes the receive fifo
		// valueP = NULL
		
	UARTcontrolCodeSetCallbackProc,						
		// Sets the callback function and data pointers for interrupt processing
		// *valueP = (MzCallbackPtr) callback data information callbackProcPtr, callbackDataPtr

	UARTcontrolCodeSetCustomBaudrate						
		// Sets a custom baudrate for UART1
		// *valueP = (UInt32) baudrate in bits per second, eg. 115K2 == *valueP = 115200
} MzUARTControlCodeEnum;

typedef enum MzUARTBaudRateEnum
{
	UARTBaudRate2400 = 1,
	UARTBaudRate9600, 
	UARTBaudRate19200, 
	UARTBaudRate57600, 
	UARTBaudRate115200, 
	UARTBaudRate230400,
	UARTBaudRate1200,
	UARTBaudRate4800,
	UARTBaudRate14400,
	UARTBaudRate28800,
	UARTBaudRate38400,
	UARTBaudRateLast
} MzUARTBaudRateEnum;

// UART interrupt types supported
#define	UARTTxFIFOAvailable				0x01			// TxFIFO has at least 1 slot empty
#define	UARTTxFIFOHalf						0x02			// TxFIFO is less than half full
#define	UARTTxFIFOEmpty						0x04			// TxFIFO is empty
#define	UARTRxFIFOReady						0x20			// RxFIFO has at least 1 byte
#define	UARTRxFIFOHalf						0x40			// RxFIFO has 4 or fewer slots remaining
#define	UARTRxFIFOFull						0x80			// RxFIFO is full and may overrun

// UART configurations types
#define	UARTReceiverEnable				0x40			// Enables the UART receiver
#define	UARTTransmitterEnable			0x20			// Enables the UART transmitter
#define	UARTParityEnable					0x08			// Enables parity checking
#define	UARTOddParitySelected			0x04			// If set, odd parity selected. Otherwise even parity selected.
#define	UARTTwoStopBitsSelected		0x02			// If set, two stop bits selected. Otherwise one stop bit selected.
#define	UART8BitTransmitReceive		0x01			// If set, 8 bit transmit and receive length selected, otherwise 7 bit.



#ifdef __MWERKS__
#pragma mark Parallel interface API structures
#endif
// -------------------------------------------------------------------//
// Parallel interface API structures
// -------------------------------------------------------------------//
typedef enum MzParallelControlCodeEnum
{	
	ParallelControlGetCS1Size,								
		// Returns the size of CS1 in the mappedSize register
		// *valueP = (UInt8) MzParallelCSSizeEnum of the CS1 size.
		
	ParallelControlSetCS1Size,								
		// Sets the size of CS1 relative to the mappedSize register
		// *valueP = (UInt8) MzParallelCSSizeEnum of the CS1 size.

	ParallelControlCodeConfigureCS1,					
		// Sets up the configuration of the chip select, 
		// *valueP = (UInt16) parallel configuration tuple eg. ParallelReadOnly etc 

	ParallelControlCodeSetWaitstate,					
		// Sets up the number of waitstates for the  chip select
		// *valueP = (UInt16) parallel waitstate enum eg. ParallelWaitState0 etc 
		
	ParallelControlCodeEnableCS1,							
		// Enables Chip Select 1 of the MZIO bus 
		// valueP = NULL 
		
	ParallelControlCodeDisableCS1,							
		// Disables Chip Select 1 of the MZIO bus, sets CS1 pin as input pulled high
		// valueP = NULL 

	ParallelControlCodeEnableCS0,							
		// Enables Chip Select 0 of the MZIO bus 
		// valueP = NULL 
		
	ParallelControlCodeDisableCS0,							
		// Disables Chip Select 0 of the MZIO bus, sets CS0 pin as input pulled high 
		// valueP = NULL 

	ParallelControlCodeGPIOSetCS1,
		// Sets the CS1 chip select pin based on valueP. This will only work if the chip select
		// function is disabled, use ParallelControlCodeDisableCS1.
		// *valueP = (Boolean) true or false sets the pin accordingly.

	ParallelControlCodeGPIOGetCS1,
		// Gets the CS1 chip select pin and returns it to valueP. This will only work if the chip select
		// function is disabled, use ParallelControlCodeDisableCS1.
		// *valueP = (Boolean) true or false for the state of the pin.
		
	ParallelControlCodeGPIOSetCS0,
		// Sets the CS0 chip select pin based on valueP. This will only work if the chip select
		// function is disabled, use ParallelControlCodeDisableCS0.
		// *valueP = (Boolean) true or false sets the pin accordingly.

	ParallelControlCodeGPIOGetCS0
		// Gets the CS0 chip select pin and returns it to valueP. This will only work if the chip select
		// function is disabled, use ParallelControlCodeDisableCS0.
		// *valueP = (Boolean) true or false for the state of the pin.

} MzParallelControlCodeEnum;

// Parallel interface configuration types 
#define	ParallelReadOnly				0x8000			// Makes the chip select read only
#define	ParallelFLASHSupport		0x0100			// When set, forces the WE* signal to go active after the chip select line
#define	Parallel16BitBus				0x0080			// When set, forces the bus to be 16 bit, otherwise 8 bit bus, this is currently not supported

// Waitstates supported	
typedef enum MzParallelWaitstateEnum					  
{
	ParallelWaitState0 = 0,										// Zero wait states	
	ParallelWaitState2,												// Two wait states
	ParallelWaitState4,												// Four wait states 
	ParallelWaitState6,												// Six wait states
	ParallelWaitState8,												// Eight wait states
	ParallelWaitState10,											// Ten wait states
	ParallelWaitState12												// Twelve wait states
} MzParallelWaitstateEnum;


// Chip select mapping sizes supported  
typedef enum MzParallelCSSizeEnum					  
{
	ParallelMappingSize32K = 0,								
	ParallelMappingSize64K,										
	ParallelMappingSize128K,									 
	ParallelMappingSize256K,									
	ParallelMappingSize512K,									
	ParallelMappingSize1M,										
	ParallelMappingSize2M,
	ParallelMappingSize4M
} MzParallelCSSizeEnum;



/* 
// -------------------------------------------------------------------//
	Notes:
// -------------------------------------------------------------------//
	1:
		CS0 chip select limitation
		This chip select is currently grouped with the chip select for flash
		memory. This means that this chip select is always selected to be 8Mbytes
		with zero wait states, configured for flash support and 16 bit wide. 
*/


#ifdef __MWERKS__
#pragma mark PWM control API structures
#endif
// -------------------------------------------------------------------//
// PWM control API structures
// -------------------------------------------------------------------//
typedef enum MzPWMControlCodeEnum
{
	PWMControlCodeEnable,											
		// Enables the PWM controller
		// valueP = NULL 
	
	PWMControlCodeDisable,										
		// Disables the PWM controller
		// valueP = NULL 

	PWMControlCodeSetClockDivider,						
		// Sets up the clock divider (MzPWMClockDividerEnum)
		// *valueP = (UInt8) MzPWMClockDividerEnum enum eg. PWMbaudRateSysClkDiv4

	PWMControlCodeSetPolarity,								
		// Value=1 inverts the polarity, defaults to zero
		// *valueP = (Boolean) true or false for setting polarity

	PWMControlCodeSetPeriod,									
		// Sets the 16-bit period value
		// *valueP = (UInt16) PWM period to set eg. 500 (clock cycles)
		
	PWMControlCodeSetPulseWidth,							
		// Set the 16-bit pulse width value
		// *valueP = (UInt16) PWM pulse width to period eg. 250 => 50%

	PWMControlCodeGetPin,											
		// Returns the value of the PWM pin
		// *valueP = (Boolean) On or Off for state of the PWM pin
		
	PWMControlCodeGetCounter									
		// Returns the PWM counter value
		// *valueP = (UInt16) PWM counter value 
} MzPWMControlCodeEnum;

typedef enum MzPWMClockDividerEnum
{
	PWMbaudRateSysClkDiv4 = 0,
	PWMbaudRateSysClkDiv8,
	PWMbaudRateSysClkDiv16,
	PWMbaudRateSysClkDiv32,
	PWMbaudRateSysClkDiv64,
	PWMbaudRateSysClkDiv128,
	PWMbaudRateSysClkDiv256,
	PWMbaudRateSysClkDiv512
} MzPWMClockDividerEnum;


#ifdef __MWERKS__
#pragma mark Module control API structures
#endif
// -------------------------------------------------------------------//
// Module control API structures
// -------------------------------------------------------------------//
typedef enum MzModuleControlCodeEnum
{
	ModuleControlCodeEnableModuleInterrupt,		
		// Enables the MOD_IREQ* interrupts
		// valueP = NULL
		
	ModuleControlCodeDisableModuleInterrupt,	
		// Disables the MOD_IREQ* interrupt
		// valueP = NULL

	ModuleControlCodeMOD_IREQGet,							
		// Gets MOD_IREQ  
		// *valueP = (Boolean) On of Off for MOD_IREQ

	ModuleControlCodeMOD_RESETSet,						
		// Sets MOD_RESET to the valueP 
		// *valueP = (Boolean) On of Off for MOD_RESET

	ModuleControlCodeMOD_RESETGet,						
		// Get MOD_RESET current state 
		// *valueP = (Boolean) On of Off for MOD_RESET

	ModuleControlCodeMOD_PWRSet,							
		// Sets MOD_PWR to valueP
		// *valueP = (Boolean) On of Off for MOD_PWR

	ModuleControlCodeMOD_PWRGet,							
		// Get MOD_PWR current state 
		// *valueP = (Boolean) On of Off for MOD_PWR

  ModuleControlCodeUART2ViaModule,					
  	// If true will enable UART2 to communiate via the MZIO bus, default is false. 
		// *valueP = (Boolean) On of Off for UART2ViaModule
  	
	ModuleControlCodeSetCallbackProc					
		// Sets the callback function and data pointer for interrupt processing
		// *valueP = (MzCallbackPtr) callback data information callbackProcPtr, callbackDataPtr		
} MzModuleControlCodeEnum;


#ifdef __MWERKS__
#pragma mark GPIO control API structures
#endif
// -------------------------------------------------------------------//
// GPIO control API structures
// -------------------------------------------------------------------//
// Note that these GPIO signals will not toggle if the corresponding signals are used
// in either SPI or UART modes of operation.
#define SPI_MOSI	0x01
#define SPI_MISO	0x02
#define SPI_CLK		0x04
#define SPI_SS		0x08

#define SPI_DR		0x10
#define UART_TX		0x20
#define UART_RX		0x40


#ifdef __MWERKS__
#pragma mark Peripheral ID enumeration tags
#endif
// -------------------------------------------------------------------//
// Peripheral ID enumeration tags
// -------------------------------------------------------------------//
typedef enum MzPeripheralIDEnum
{
	PeripheralError = 0,					
	Peripheral22K,			// USB Charging cradle 		
	Peripheral27K,			// RS232 Charging cradle			
	Peripheral33K,					
	Peripheral39K,					
	Peripheral47K,			// USB Comms cable		
	Peripheral56K,			// RS232 Comms cable		
	Peripheral68K,					
	Peripheral82K,					
	Peripheral100K,					
	Peripheral120K,					
	Peripheral150K,					
	Peripheral180K,					
	Peripheral220K,					
	Peripheral270K,					
	Peripheral330K,					
	Peripheral390K,					
	Peripheral470K,					
	Peripheral560K,					
	PeripheralNoDevicePresent					
} MzPeripheralIDEnum;

#define PeripheralUSBCable 		Peripheral47K
#define PeripheralUSBCradle		Peripheral22K
#define PeripheralRS232Cable 	Peripheral56K
#define PeripheralRS232Cradle	Peripheral27K
#define PeripheralRS232Keybd	Peripheral68K


#ifdef __MWERKS__
#pragma mark -
#endif
/********************************************************************
 * API Prototypes
 ********************************************************************/
#ifdef __cplusplus
extern "C" {
#endif
//--------------------------------------------------
// Standard library open, close, sleep and wake functions
//--------------------------------------------------

extern Err MzLibOpen(UInt16 refNum)
				Meazura_LIB_TRAP(sysLibTrapOpen);
				
extern Err MzLibClose(UInt16 refNum)
				Meazura_LIB_TRAP(sysLibTrapClose);

extern Err MzLibSleep(UInt16 refNum)
				Meazura_LIB_TRAP(sysLibTrapSleep);

extern Err MzLibWake(UInt16 refNum)
				Meazura_LIB_TRAP(sysLibTrapWake);


//--------------------------------------------------
// Custom library API functions
//--------------------------------------------------
//-----------------------------------------------------------------------------
// Meazura library function trap ID's. Each library call gets a trap number:
//   MeazuraLibTrapXXXX which serves as an index into the library's dispatch table.
//   The constant sysLibTrapCustom is the first available trap number after
//   the system predefined library traps Open,Close,Sleep & Wake.
//-----------------------------------------------------------------------------
#ifdef __MWERKS__
#pragma mark API Traps 
#endif

#define 	meazuraLibTrapMzLibGetVersion 		(sysLibTrapCustom + 0) 
#define 	meazuraLibTrapMzAlmSetAlarm 			(sysLibTrapCustom + 1) 
#define 	meazuraLibTrapMzAlmStopAlarm 			(sysLibTrapCustom + 2) 
#define 	meazuraLibTrapMzSPIControl 				(sysLibTrapCustom + 3) 
#define 	meazuraLibTrapMzSPITransferData 	(sysLibTrapCustom + 4) 
#define 	meazuraLibTrapMzSPIReadData 			(sysLibTrapCustom + 5) 
#define 	meazuraLibTrapMzSPIGetFIFOStatus 	(sysLibTrapCustom + 6) 
#define 	meazuraLibTrapMzUARTControl 			(sysLibTrapCustom + 7) 
#define 	meazuraLibTrapMzUARTSendData 			(sysLibTrapCustom + 8) 
#define 	meazuraLibTrapMzUARTReceiveData 	(sysLibTrapCustom + 9) 
#define 	meazuraLibTrapMzUARTGetFIFOStatus (sysLibTrapCustom + 10) 
#define 	meazuraLibTrapMzParallelControl 	(sysLibTrapCustom + 11) 
#define 	meazuraLibTrapMzParallelSendData	(sysLibTrapCustom + 12) 
#define 	meazuraLibTrapMzParallelReadData	(sysLibTrapCustom + 13) 
#define 	meazuraLibTrapMzModuleControl 		(sysLibTrapCustom + 14) 
#define 	meazuraLibTrapMzGPIOGetValue 			(sysLibTrapCustom + 15) 
#define 	meazuraLibTrapMzGPIOSetValue 			(sysLibTrapCustom + 16) 
#define 	meazuraLibTrapMzGetPeripheralID 	(sysLibTrapCustom + 17) 
#define 	meazuraLibTrapMzPWMControl	 			(sysLibTrapCustom + 18) 
#define 	MeazuraLibTrapLast 								(sysLibTrapCustom + 19) 

#ifdef __MWERKS__
#pragma mark -
#endif
	
/************************************************************
 *
 *  FUNCTION: MzLibGetVersions
 *
 *  DESCRIPTION:	Get our library API version.  The Sample library does not
 *								need to be "opened" to call MzLibGetLibAPIVersion.
 *
 *  PARAMETERS:	refNum		Sample library reference number
 *							version		Pointer to a structure for storing the version numbers
 *
 *  CALLED BY:	Anyone wishing to get our library API version
 *
 *  RETURNS:		errNone		no error
 *
 *  REVISION HISTORY:
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzLibGetVersion
#endif
extern Err MzLibGetVersion(UInt16 refNum, MzVersionPtr version)
				Meazura_LIB_TRAP(meazuraLibTrapMzLibGetVersion);
	
// Alarm APIs
/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzAlmSetAlarm()
 *
 *  DESCRIPTION: 
 *				This function serves to set up the external alarms.
 *				It supports repeating alarms for 10 miliseconds,seconds, 
 *				minutes, hours,	day, weeks and months. The function sets up 
 *				an initial start time, and periodic alarms occur after that point.
 *				If the start day is NULL, the alarms will be immediately
 *				started. Also supports waking up the device after a #max 
 *				number of alarms. If this number is NULL, the system will
 *				keep on getting alarms. 
 *
 *
 *  PARAMETERS:	
 *			-> refNum		reference number of the library
 *			-> alarmsP	pointer to a MzAlarmType structure
 *
 *  RETURNS:
 *			errNone											No error 
 *			mzSetAlarmError							Error in setting the alarm.
 *			mzCommsError								Communications error whilst setting the alarm.	
 *			mzHwFunctionNotSupported		This function is not available on the current hardware
 *
 *	 CALLED BY:
 *			Anybody who wants to set up external Alarms
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzAlmSetAlarm
#endif
 extern Err MzAlmSetAlarm(UInt16 refNum, MzAlarmPtr alarmsP)
				Meazura_LIB_TRAP(meazuraLibTrapMzAlmSetAlarm);

/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzAlmStopAlarm()
 *
 *  DESCRIPTION: 
 *				Stop alarms in Meazura keyboard alarm module 
 *
 *
 *  PARAMETERS:	
 *			-> refNum		reference number of the library
 *
 *  RETURNS:
 *			errNone											No error 
 *			mzCommsError								Communications error whilst setting the alarm.	
 *			mzHwFunctionNotSupported		This function is not available on the current hardware
 *
 *	 CALLED BY:
 *			Anybody who wants to stop external Alarms
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzAlmStopAlarm
#endif
extern Err MzAlmStopAlarm(UInt16 refNum)
				Meazura_LIB_TRAP(meazuraLibTrapMzAlmStopAlarm);



// SPI APIs
/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzSPIControl()
 *
 *  DESCRIPTION: 
 *				This function is a driver to interface to the VZ's SPI 1 port
 *
 *  PARAMETERS:	
 *
 *			-> refNum				Reference number of the library
 *			-> controlCode	Enumerated control code to control the function (MzSPIControlCodeEnum)
 *			-> valueP				pointer to a data value or structure.
 *
 *  RETURNS: 
 *			errNone											No error
 *			mzControlCodeError					Unrecognised control code.
 *			mzBadBaudRateError 					Error setting up the baud rate.
 *			mzConfigError								Error setting up the configuration.
 *			mzNullPointerError					Null pointer error.
 *			mzNullCallbackProcPtrError 	Null callback function pointer error.
 *			mzNullCallbackDataPtrError 	Null callback data pointer error.
 *			mzHwFunctionNotSupported		This function is not available on the current hardware
 *			mzHwFunctionBusy						The SPI function is in use by the system
 *
 *	 CALLED BY:
 *			Anybody who wants to set up the SPI controller
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzSPIControl
#endif
extern Err MzSPIControl(UInt16 refNum, UInt16 controlCode, void* valueP)
				Meazura_LIB_TRAP(meazuraLibTrapMzSPIControl);

/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzSPITransferData()
 *
 *  DESCRIPTION: 
 *				This function loads words into the SPI fifo. If the fifo
 *				is full, the function will try until all words have been
 *				placed in the TxFIFO. If 0 words specified, the function 
 *				will transfer 1 word. This function also checks to see if the 
 *				port is opened.
 *
 *  PARAMETERS:	
 *
 *			-> refNum					Reference number of the library
 *	 		-> dataPtr				Pointer to data words to transfer. 
 *			-> numberOfWords	Pointer to number of words to transfer. Returns number of words 
 *												left to transfer. Word width is set between 1 and 16 bits
 *												using the SPIcontrolCodeSetBitsToTransfer in the MzSPIControl API.
 *
 *  RETURNS: 
 *			errNone							No error
 *			mzPortNotOpenError 	Port is not openned error.	
 *			mzHwFunctionBusy		The SPI function is in use by the system
 *
 *	 CALLED BY:
 *			Anybody who wants to send SPI data to the SPI transmit fifo.
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzSPITransferData
#endif
extern Err MzSPITransferData(UInt16 refNum, UInt16* dataPtr, UInt16 *numberOfWords)
				Meazura_LIB_TRAP(meazuraLibTrapMzSPITransferData);

/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzSPIReadData()
 *
 *  DESCRIPTION: 
 *				This function reads words from the SPI receive fifo. If the fifo
 *				is empty, the function will return an error immediately. 
 *				If 0 words specified, the function will read 1 word.
 *
 *  PARAMETERS:	
 *
 *			-> refNum					Reference number of the library
 *	 		-> dataPtr				Double pointer to the buffer to receive data into. The address it is pointing to
 *												is updated as words are read from the receive FIFO and added to the buffer.
 *			-> numberOfWords	Number of words to receive. Returns number of words 
 *												left to be received. Word width is set between 1 and 16 bits
 *												using the SPIcontrolCodeSetBitsToTransfer in the MzSPIControl API.
 *
 *  RETURNS: 
 *			errNone						No error
 *			mzNoFIFODataError	RxFIFO has no data
 *			mzHwFunctionBusy	The SPI function is in use by the system
 *
 *	 CALLED BY:
 *			Anybody who wants to read SPI data to the SPI receive fifo.
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzSPIReadData
#endif
extern Err MzSPIReadData(UInt16 refNum, UInt16** dataPtr, UInt16 *numberOfWords)
				Meazura_LIB_TRAP(meazuraLibTrapMzSPIReadData);
				
/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzSPIGetFIFOStatus()
 *
 *  DESCRIPTION: 
 *		Gets the status of both the receive and transmit FIFOs of the SPI controller 
 *
 *  PARAMETERS:	
 *
 *			-> refNum					Reference number of the library
 *
 *  RETURNS: 
 *			UInt8				FIFO status
 *
 *	 CALLED BY:
 *			Anybody who wants to obtain the status of the transmit and receive fifos.
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzSPIGetFIFOStatus
#endif
extern UInt8 MzSPIGetFIFOStatus(UInt16 refNum)
				Meazura_LIB_TRAP(meazuraLibTrapMzSPIGetFIFOStatus);


// UART APIs
/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzUARTControl()
 *
 *  DESCRIPTION: 
 *				This function is a driver to interface to the VZ's UART 1 port
 *
 *  PARAMETERS:	
 *
 *			-> refNum				Reference number of the library
 *			-> controlCode	Enumerated control code to control the function (MzUARTControlCodeEnum)
 *			-> valueP				pointer to a data value or structure.
 *
 *  RETURNS: 
 *			errNone											No error
 *			mzControlCodeError					Unrecognised control code.
 *			mzBadBaudRateError 					Error setting up the baud rate.
 *			mzConfigError								Error setting up the configuration.
 *			mzNullPointerError					Null pointer error.
 *			mzNullCallbackProcPtrError 	Null callback function pointer error.
 *			mzNullCallbackDataPtrError 	Null callback data pointer error.
 *			mzHwFunctionNotSupported		This function is not available on the current hardware
 *			mzHwFunctionBusy						The UART1 function is in use by the system
 *
 *	 CALLED BY:
 *			Anybody who wants to set up external Alarms
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzUARTControl
#endif
extern Err MzUARTControl(UInt16 refNum, UInt16 controlCode, void* valueP)
				Meazura_LIB_TRAP(meazuraLibTrapMzUARTControl);

/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzUARTSendData()
 *
 *  DESCRIPTION: 
 *				This function loads bytes into the UART TxFIFO. If the fifo
 *				is full, the function will try until all bytes have been placed
 *				in the TxFIFO. If 0 words specified, the function will transfer 1 byte.
 *				This function will send as many bytes requested without a timeout.
 *
 *  PARAMETERS:	
 *
 *			-> refNum					Reference number of the library
 *	 		-> dataPtr				Pointer to data words to transfer.
 *			-> numberOfBytes	Number of words to transfer. Returns the number of bytes
 *												left to transfer. 
 *
 *  RETURNS: 
 *			errNone							No error
 *			mzPortNotOpenError 	Port is not opened error.	
 *			mzHwFunctionBusy		The UART1 function is in use by the system
 *
 *	 CALLED BY:
 *			Anybody who wants to send UART data to the UART transmit fifo.
 *
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzUARTSendData
#endif
extern Err MzUARTSendData(UInt16 refNum, UInt8* dataPtr, UInt16* numberOfBytes)
				Meazura_LIB_TRAP(meazuraLibTrapMzUARTSendData);

/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzUARTReceiveData()
 *
 *  DESCRIPTION: 
 *				This function reads bytes from the UART RxFIFO. If the RxFIFO
 *				is empty, the function will return immediately with an error. 
 *				If 0 words specified, the function will transfer 1 word.
 *
 *  PARAMETERS:	
 *
 *			-> refNum					Reference number of the library
 *	 		-> dataPtr				Double pointer to the buffer to receive data into. The address it is pointing to
 *												is updated as words are read from the receive FIFO and added to the buffer.
 *			-> numberOfBytes	Number of words to transfer. Returns number of bytes
 *												left to receive.
 *
 *  RETURNS: 
 *			errNone						 	No error
 *			mzNoFIFODataError		RxFIFO has no data
 * 			mzUARTOverrunError 	UART has received an overrun error
 * 			mzUARTFrameError	 	UART has received a frame error
 * 			mzUARTParityError	 	UART has received parity error
 *			mzHwFunctionBusy		The UART1 function is in use by the system
 *
 *	 CALLED BY:
 *			Anybody who wants to read UART data from the UART receive fifo.
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzUARTReceiveData
#endif
extern Err MzUARTReceiveData(UInt16 refNum, UInt8** dataPtr, UInt16* numberOfBytes)
				Meazura_LIB_TRAP(meazuraLibTrapMzUARTReceiveData);

/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzUARTGetFIFOStatus()
 *
 *  DESCRIPTION: 
 *		Gets the status of the UART TxFIFO only. There is a hardware limitation
 *		to get the UART RxFIFO status information without taking the byte out from
 *		the RxFIFO. The use RxFIFO status is only available using interrupts.
 *
 *  PARAMETERS:	
 *
 *			-> refNum					Reference number of the library
 *
 *  RETURNS: 
 *			UInt8				TxFIFO status
 *
 *	 CALLED BY:
 *			Anybody who wants to obtain the status of the transmit and receive fifos.
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzUARTGetFIFOStatus
#endif
extern UInt8 MzUARTGetFIFOStatus(UInt16 refNum)
				Meazura_LIB_TRAP(meazuraLibTrapMzUARTGetFIFOStatus);


// Parallel Interface APIs
/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzParallelControl()
 *
 *  DESCRIPTION: 
 *				This function is a driver to interface to the parallel interface on 
 *				a MZIO module. 
 *
 *  PARAMETERS:	
 *
 *			-> refNum				Reference number of the library
 *			-> controlCode	Enumerated control code to control the function (MzParallelControlCodeEnum)
 *			-> valueP				pointer to a data value or structure.
 *
 *  RETURNS: 
 *			errNone											No error
 *			mzControlCodeError					Unrecognised control code.
 *			mzConfigError								Error setting up the configuration.
 *			mzNullPointerError					Null pointer error.
 *			mzHwFunctionNotSupported		This function is not available on the current hardware
 *			mzHwFunctionBusy						The parallel function is in use by the system
 *
 *	 CALLED BY:
 *			Anybody who wants to set up parallel control.
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzParallelControl
#endif
extern Err MzParallelControl(UInt16 refNum, UInt16 controlCode, void* valueP)
				Meazura_LIB_TRAP(meazuraLibTrapMzParallelControl);

/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzParallelSendData()
 *
 *  DESCRIPTION: 
 *				This function writes sizeOfData number of bytes or words
 *				via parallel adressing on the MZIO bus. One of two chip selects 
 *				can be selected to do the job. If 0 words specified, the function 
 *				will transfer 1 word. 
 *
 *  PARAMETERS:	
 *
 *			-> refNum				Reference number of the library
 *	 		-> chipSelect		Points to which chip select to send data to, 0 or 1.
 *	 		-> offset				The offset relative to the base of the chip select to start sending data to.
 *	 		-> dataPtr			Pointer to data bytes or words to transfer.
 *			-> sizeOfData		Number of data elements to transfer, will limit transfer beyond size of 
 *											chip select. 
 *
 *  RETURNS: 
 *			errNone											No error
 *			mzNullPointerError					Null pointer error
 *			mzParallelChipSelectError		Unrecognised chip select 
 *			mzParallelOffsetError				Offset is out of chip select range 
 *			mzParallelDataSizeError			sizeOfData + offset is out of chip select range
 *			mzHwFunctionBusy						The parallel function is in use by the system
 *
 *	 CALLED BY:
 *			Anybody who wants to send data to the module on the parallel interface.
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzParallelSendData
#endif
extern Err MzParallelSendData(UInt16 refNum, UInt8 chipSelect, UInt32 offset, UInt16* dataPtr, UInt32 sizeOfData)
				Meazura_LIB_TRAP(meazuraLibTrapMzParallelSendData);

/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzParallelReadData()
 *
 *  DESCRIPTION: 
 *				This function reads sizeOfData number of bytes from the MZIO
 *				parallel interface. Reads can be performed on one or the other of the chip selects
 *				available.If 0 words specified, the function will transfer 1 word. 
 *
 *  PARAMETERS:	
 *
 *			-> refNum				Reference number of the library
 *	 		-> chipSelect		Points to which chip select to read data from, 0 or 1.
 *	 		-> offset				The offset relative to the base of the chip select to start reading data.
 *	 		-> dataPtr			Pointer to data bytes or words to read.
 *			-> sizeOfData		Number of bytes to transfer, will limit transfer beyond size of 
 *											chip select. 
 *
 *  RETURNS: 
 *			errNone											No error
 *			mzNullPointerError					Null pointer error
 *			mzParallelChipSelectError		Unrecognised chip select 
 *			mzParallelOffsetError				Offset is out of chip select range 
 *			mzParallelDataSizeError			sizeOfData + offset is out of chip select range
 *			mzHwFunctionBusy						The parallel function is in use by the system
 *
 *	 CALLED BY:
 *			Anybody who wants to read data from a module via the parallel interface.
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzParallelReadData
#endif
extern Err MzParallelReadData(UInt16 refNum, UInt8 chipSelect, UInt32 offset, UInt16* dataPtr, UInt32 sizeOfData)
				Meazura_LIB_TRAP(meazuraLibTrapMzParallelReadData);

// Module Control APIs
/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzModuleControl()
 *
 *  DESCRIPTION: 
 *				This function controls various functionalities on a MZIO module. 
 *
 *  PARAMETERS:	
 *
 *			-> refNum				Reference number of the library
 *			-> controlCode	Enumerated control code to control the function (MzParallelControlCodeEnum)
 *			-> valueP				pointer to a data value or structure.
 *
 *  RETURNS: 
 *			errNone											No error
 *			mzControlCodeError					Unrecognised control code.
 *			mzConfigError								Error setting up the configuration.
 *			mzNullPointerError					Null pointer error.
 *			mzNullCallbackProcPtrError 	Null callback function pointer error.
 *			mzNullCallbackDataPtrError 	Null callback data pointer error.
 *			mzHwFunctionNotSupported		This function is not available on the current hardware
 *			mzHwFunctionBusy						The module control function is in use by the system
 *
 *	 CALLED BY:
 *			Anybody who wants to set up external Alarms
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzModuleControl
#endif
extern Err MzModuleControl(UInt16 refNum, UInt16 controlCode, void* valueP)
				Meazura_LIB_TRAP(meazuraLibTrapMzModuleControl);

// GPIO Control APIs
/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzGPIOGetValue()
 *
 *  DESCRIPTION: 
 *				This function gets the value of a set of GPIO pins that
 *				are currently not used by either the SPI or UART modules.
 *				If the SPI_DR* or PWM function is in use then an error code will be returned.
 *				This function will set the GPIO	pins as inputs with internal pullups enabled.
 *
 *  PARAMETERS:	
 *
 *			-> refNum				Reference number of the library
 *			-> mask 				A byte bitfield containing the GPIO pins to get.
 *			-> value				Pointer to the returned byte value of the GPIO pins.
 *
 *  RETURNS: 
 *			errNone											No error
 *			mzNullPointerError					Returned if a null pointer is given.
 *			mzGPIOPinBusyError					Pin in use by PWM or SPI_DR* dedicated function
 *			mzHwFunctionNotSupported		This function is not available on the current hardware
 *			mzHwFunctionBusy						The GPIO function is in use by the system
 *
 *	 CALLED BY:
 *			Anybody who wants to read GPIO pins.
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzGPIOGetValue
#endif
extern Err MzGPIOGetValue(UInt16 refNum, UInt8 mask, UInt8 *value)
				Meazura_LIB_TRAP(meazuraLibTrapMzGPIOGetValue);

/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzGPIOSetValue()
 *
 *  DESCRIPTION: 
 *				This function sets the value of a set of GPIO pins that
 *				are currently not used by either the SPI or UART modules.
 *	 			The pins are automatically configured as output GPIO if available.
 *    		Pins that are configured as dedicated functions (UART or SPI) will not be affected
 *    		If the SPI_DR* or PWM function is in use then an error code will be returned
 *
 *  PARAMETERS:	
 *
 *			-> refNum				Reference number of the library
 *			-> mask 				A byte bitfield containing the GPIO pins to set.
 *			-> value				The value for which to set the GPIO pins to.
 *
 *  RETURNS: 
 *			errNone											No error
 *			mzGPIOPinBusyError					Pin in use by PWM or SPI_DR* dedicated function
 *			mzHwFunctionNotSupported		This function is not available on the current hardware
 *			mzHwFunctionBusy						The GPIO function is in use by the system
 *
 *	 CALLED BY:
 *			Anybody who wants to set GPIO pins.
 *
 *	Written by:
 *			Hemon Dey
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzGPIOSetValue
#endif
extern Err MzGPIOSetValue(UInt16 refNum, UInt8 mask, UInt8 value)
				Meazura_LIB_TRAP(meazuraLibTrapMzGPIOSetValue);

// Get peripheral ID
/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzGetPeripheralID()
 *
 *  DESCRIPTION: 
 *				This function returns the value of the peripheral ID interms of
 *				the Peripheral ID enumeration type.
 *
 *  PARAMETERS:	
 *
 *			-> refNum				Reference number of the library
 *
 *  RETURNS: 
 *			MzPeripheralIDEnum Returned enumeration of the peripheral ID 
 *
 *	 CALLED BY:
 *			Anybody who wants to get peripheral ID.
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzGetPeripheralID
#endif
extern UInt8 MzGetPeripheralID(UInt16 refNum)
				Meazura_LIB_TRAP(meazuraLibTrapMzGetPeripheralID);

/************************************************************
 *
 *	ACEECA API
 *  FUNCTION: MzPWMControl()
 *
 *  DESCRIPTION: 
 *				This function gives control over the PWM module which is
 *				currently multiplexed with the DATA Ready pin of the SPI
 *				controller. When this controller is enabled, the Data ready pin
 *				is configured as an output pin, and will operate as the PWM 
 *				output. 
 *
 *  PARAMETERS:	
 *
 *			-> refNum				Reference number of the library
 *			-> controlCode	Enumerated control code to control the function
 *			-> valueP				pointer to a data value or structure.
 *
 *  RETURNS: 
 *			errNone											No error
 *			mzControlCodeError					Unrecognised control code.
 *			mzNullPointerError					Null pointer error.
 *			mzHwFunctionNotSupported		This function is not available on the current hardware
 *			mzHwFunctionBusy						The PWM function is in use by the system
 *
 *	 CALLED BY:
 *			Anybody who wants enable and control the PWM module.
 *
 *************************************************************/
#ifdef __MWERKS__
#pragma mark MzPWMControl
#endif
extern Err MzPWMControl(UInt16 refNum, UInt16 controlCode, void* valueP)
				Meazura_LIB_TRAP(meazuraLibTrapMzPWMControl);


// For loading the library in Palm OS Mac emulation mode
extern Err MeazuraLibInstall(UInt16 refNum, SysLibTblEntryPtr entryP);


#ifdef __cplusplus 
}
#endif





#endif	// __MEAZURA_LIB_H__