/*[CR]*************************************************************************

  Copyright (c) 2001 - 2003 by PEP Modular Computers GmbH

  All Rights reserved.

*/
/*[FH]*************************************************************************
  FILE:     MAX1617.h
  MODULE:   MAX1617
  CMM ID:   $ID$
  CONTENTS: API interface for MAX1617 temperature sensor library.
*/


/*
DESCRIPTION
This module provides support for the MAX1617 temperature sensor. There are
functions available to read the remote or local temperature, to get or set
the alert limits for both temperatures, to wait for an ALERT interrupt, and
finally to get the status of the MAX1617. 

The data format for temperature values and alarm limits is 7 bits plus sign,
with each bit corresponding to 1°C, in twos-complement format. All values for
temperatures or limits range from -55°C (11001001) to +127°C (01111111). 

The local channel measures the case temperature of the MAX1617 whereas the
remote channel measures the CPU temperature. The actual values for the remote
or local temperature can be read with max1617TempGet().

Alarm thresholds for high-temperature and low-temperature can be set for every
channel. After power on the high-temperature limit is set to +127°C and the
low-temperature limit is set to -55°C. The actual alarm thresholds can be read
with max1617LimitGet() or can be modified with max1617LimitSet().

As soon as a temperature equals or exceeds the corresponding alarm limit value
an ALERT interrupt is asserted. A task can be connected to the interrupt with
max1617WaitForAlert(). This routine enables the interrupt and suspends the
connected task until the interrupt occures. Before taking any corrective action
it is recommended to check that the interrupt is valid by reading the current
temperature. max1617StatusGet() provides the status byte of the MAX1617
indicating the temperature thresholds that have been exceeded.

SEE ALSO
max1617_hw.h
MAX1617 hardware manual: http://www.maxim-ic.com
*/

#ifdef __cplusplus
extern "C" {
#endif

#ifdef MAX1617_EXPORTS
#define MAX1617_API __declspec(dllexport)
#else
#define MAX1617_API __declspec(dllimport)
#endif

typedef VOID (*ftNotifyFunc)(UCHAR SmbAddr);


/*******************************************************************************
*
* Max1617Init - initialize the MAX1617 temperature sensor library
*
* This routine initializes the MAX1617 library and attaches the device to the
* SMBus host controller.
*
* PARAMETERS: This routine requires the following parameter
*
* UCHAR SmbAddr			must be set to a valid MAX1617 SM bus address
*
* RETURNS:	OK
*			ERROR_INVALID_PARAMETER			invalid SM bus address
*			ERROR_GEN_FAILURE				MAX1617 system management init failed
*			ERROR_IO_DEVICE					SMbus not accessable
*			other							see definition of CreateFile()
*
*/
MAX1617_API DWORD Max1617Init(
	UCHAR  SmbAddr	/* SMBus address */
);

/*******************************************************************************
*
* Max1617DeInit - deinitialize the MAX1617 device
*
* This routine deinitializes the MAX1617 device and disconnects from SMbus if
* it has been last active MAX1617 device
*
* PARAMETERS: This routine requires the following parameter
*
* UCHAR SmbAddr			must be set to a valid MAX1617 SM bus address
*
* RETURNS:	OK
*			ERROR_INVALID_PARAMETER			invalid SM bus address
*			ERROR_IO_DEVICE					SMbus not accessable
*			other							see definition of CloseHandle(), CancelIo()
*
*/

MAX1617_API DWORD Max1617DeInit(
	UCHAR  SmbAddr	/* SMBus address */
);

/*******************************************************************************
*
* Max1617RegisterAlert - enables alarm notification for MAX device
*
* This routine enables the ALERT interrupt

* PARAMETERS: This routine requires the following parameter
*
* UCHAR SmbAddr					must be set to a valid MAX1617 SM bus address
* ftNotifyFunc ToBeInformed		ptr to a callback function to be called in case
*								of alert from this device
*								refer to definition of ftNotifyFunc
*
* RETURNS:	OK
*			ERROR_INVALID_PARAMETER			invalid SM bus address
*											ToBeInformed not valid
*			ERROR_NOT_READY					device not initialized
*			ERROR_IO_DEVICE					SMbus not accessable
*			other							see definition of DeviceIoControl()
*
*/

MAX1617_API DWORD Max1617RegisterAlert(
	UCHAR  SmbAddr,	/* SMBus address */
	ftNotifyFunc ToBeInformed  /* callback function */
);

/*******************************************************************************
*
* Max1617DeRegisterAlert - deregister from alert notification list
*
* The device is prevented from generating alerts and afterwards it is removed
* from alert notification list
*
* PARAMETERS: This routine requires the following parameter
*
* UCHAR SmbAddr			must be set to a valid MAX1617 SM bus address
*
* RETURNS:	OK
*			ERROR_INVALID_PARAMETER			invalid SM bus address
*			ERROR_NOT_READY					device not initialized
*			ERROR_IO_DEVICE					SMbus not accessable
*			other							see definition of DeviceIoControl()
*
*/

MAX1617_API DWORD Max1617DeRegisterAlert(
	UCHAR  SmbAddr	/* SMBus address */
);

/*******************************************************************************
*
* Max1617StatusGet - get the MAX1617 status byte
*
* This routine gets the status byte of the MAX1617, which indicates whether
* a temperature threshold is exceeded or an open-circuit has been detected in
* the path to the remote sensor.
*
* PARAMETERS: This routine requires the following parameters
*
* UCHAR SmbAddr			must be set to a valid MAX1617 SM bus address
* UCHAR *pStatus		ptr to location to store status of device
*						for status values see definition inside max1617.h
*
* RETURNS:	OK
*			ERROR_INVALID_PARAMETER			invalid SM bus address
*			ERROR_NOT_READY					device not initialized
*			ERROR_IO_DEVICE					SMbus not accessable
*
* NOTE:
* Due to the fact that the ADC is disabled before reading the status byte and
* is enabled again afterwards, the BUSY bit (MSB) returned is always low. If
* one of the bits MAX1617_RSTS_LHIGH, MAX1617_RSTS_LLOW, MAX1617_RSTS_RHIGH or
* MAX1617_RSTS_RLOW is high, the related temperature limit has been violated.
* If the bit MAX1617_RSTS_OPEN is high an open circuit has been detected in the
* path to the remote diode. The calling task is suspended for 156 ms to ensure
* that the temperature values subsequently read are valid.
* 
*/

MAX1617_API DWORD Max1617StatusGet (
	UCHAR  SmbAddr,	/* SMBus address */
	UCHAR* pStatus	/* location to store the status byte */
);

/*******************************************************************************
*
* max1617TempGet - get the local or remote temperature
*
* This routine gets the temperature calculated for the local or remote channel.
*
* PARAMETERS: This routine requires the following parameter
*
* UCHAR SmbAddr			must be set to a valid MAX1617 SM bus address
* UCHAR Channel			set to channel to read temperature from
*						refer to MAX1617 channel definitions
* CHAR  *pTemperature	ptr to location to store temperature in degree celsius
*
* RETURNS:	OK
*			ERROR_INVALID_PARAMETER			invalid SM bus address
*											invalid channel
*			ERROR_NOT_READY					device not initialized
*			ERROR_IO_DEVICE					SMbus not accessable
*
*/

MAX1617_API DWORD Max1617TempGet (
	UCHAR  SmbAddr,		/* SMBus address */
	UCHAR  channel,		/* desired channel */
	CHAR*  pTemperature	/* location to store the temperature */
);

/*******************************************************************************
*
* max1617LimitGet - get the temperature limit
*
* This routine gets the low or high alarm temperature limit for the local or
* remote channel.
*
* PARAMETERS: This routine requires the following parameter
*
* UCHAR SmbAddr			must be set to a valid MAX1617 SM bus address
* UCHAR channel			set to channel to read temperature from
*						refer to MAX1617 channel definitions
* UCHAR threshold		select limit to be read
*						refer to MAX1617 threshold definitions
* CHAR  *pLimit			ptr to location to store temperature limit in degree celsius
*
* RETURNS:	OK
*			ERROR_INVALID_PARAMETER			invalid SM bus address
*											invalid channel
*											invalid threshold
*			ERROR_NOT_READY					device not initialized
*			ERROR_IO_DEVICE					SMbus not accessable
*
*/

MAX1617_API DWORD Max1617LimitGet (
	UCHAR  SmbAddr,		/* SMBus address */
	UCHAR  channel,		/* desired channel */
	UCHAR  threshold,	/* desired threshold */
	CHAR*  pLimit		/* location to store the limit */
);

/*******************************************************************************
*
* max1617LimitSet - set the temperature limit
*
* This routine sets the low or high alarm temperature limit for the local or
* remote channel.
*
* PARAMETERS: This routine requires the following parameters
*
*
* UCHAR SmbAddr			must be set to a valid MAX1617 SM bus address
* UCHAR channel			set to channel to be used
*						refer to MAX1617 channel definitions
* UCHAR threshold		select limit to be set
*						refer to MAX1617 threshold definitions
* CHAR  limit			temperature limit in degree celsius
*
* RETURNS:	OK
*			ERROR_INVALID_PARAMETER			invalid SM bus address
*											invalid channel
*											invalid threshold
*			ERROR_NOT_READY					device not initialized
*			ERROR_IO_DEVICE					SMbus not accessable
*
*/

MAX1617_API DWORD Max1617LimitSet (
	UCHAR  SmbAddr,		/* SMBus address */
	UCHAR  channel,		/* desired channel */
	UCHAR  threshold,	/* desired threshold */
	CHAR   limit		/* alarm limit to set */
);

#ifdef __cplusplus
}
#endif
