/**
 * \file rmap_packet_library.h
 * \brief Declarations of the functions provided by the STAR-Dundee RMAP Packet
 *        Library.
 * \author Stuart Mills\n
 *         STAR-Dundee\n
 *         c/o School of Computing\n
 *         University of Dundee\n
 *         Dundee, DD1 4HN\n
 *         Scotland, UK\n
 *         e-mail: support@star-dundee.com
 *
 * This file contains the declarations of the functions provided by the
 * STAR-Dundee RMAP Packet Library, along with constants and types used by the
 * library.  The RMAP Packet Library provides functions for building and
 * interpreting RMAP packets.
 *
 * <b>IMPORTANT NOTE:</b>
 * \note            If you are experiencing compilation errors indicating that
 *                  U8 is already defined, for example, please add the following
 *                  line to your code prior to including this  file:\n
 *                      <code>\#define NO_STAR_TYPES</code>\n
 *                  Alternatively you can compile your code with a flag of
 *                  <code>-DNO_STAR_TYPES</code>.\n
 *                  (Copied from star_dundee_types.h)
 *
 * \version 2.0 - October 28th 2009\n
 *          Changed internal architecture to minimise memory allocations.\n
 *          Restored __stdcall calling convention on Windows.\n
 *          Updated names to be consistent with terminology in latest RMAP
 *          standard.\n
 *          Added functions to calculate the length of different packet types
 *          and to fill a buffer with specific packets.\n\n
 * 
 * \version 1.9 - July 29th 2009\n
 *          Fixed problem with byte ordering in return value of
 *          RMAP_GetAddress.\n
 *          Fixed bug when creating read and write reply packets, with a packet
 *          structure provided.\n\n
 *
 * \version 1.8 - February 26th 2009\n
 *          Updated the calling convention used in the function declaration to
 *          __stdcall on Windows.\n\n
 *
 * \version 1.7 - November 20th 2008\n
 *          Fixed problem with naming of RMAP_IsCRCValid in header file.\n
 *          Added function to calculate a CRC starting from a CRC seed
 *          value.\n\n
 *
 * \version 1.6 - October 29th 2007\n
 *          Added support for SpaceCube.\n\n
 *
 * \version 1.5 - March 23rd 2007\n
 *          Used star_dundee_types.h to represent integer values of 1, 2 and 4
 *          bytes in a cross-platform manner.\n
 *          Fixed problems encountered on big endian machines.\n\n
 *
 * \version 1.4 - March 19th 2007\n
 *          Improved freeing of memory following errors.\n\n
 *
 * \version 1.3 - November 7th 2006\n
 *          Updated to be multi-platform.\n
 *          Using new CRC table.\n
 *          Fixed error when checking the format of read-modify-write command
 *          packets, data length incorrect.\n
 *          Fixed error when identifying the start of the extended and normal
 *          read/write address.\n
 *          Fixed error when reading the data length in a read command.\n\n
 *
 * \version 1.2 - April 3rd 2006\n
 *          Fixed potential problems with RMAP_PACKET_STATUS enum being an
 *          undefined size (no change to this file required).\n\n
 *
 * \version 1.1 - March 9th 2006\n
 *          Added support for different byte alignment requirements.\n\n
 *
 * \version 1.0 - December 20th 2005\n
 *          Initial version.\n\n
 *
 * Copyright &copy; 2009 STAR-Dundee Ltd
 */



#ifndef RMAP_PACKET_LIBRARY_H
#define RMAP_PACKET_LIBRARY_H



#include "star_dundee_types.h"



#ifdef __cplusplus
extern "C" {
#endif



#if defined(_WIN32) || defined(_WIN64)
	#ifdef RMAPPACKETLIBRARY_EXPORTS
		#define RMAPPACKETLIBRARY_API __declspec(dllexport)
	#else
		#define RMAPPACKETLIBRARY_API __declspec(dllimport)
	#endif

	#ifdef  _WIN64
		#define RMAPPACKETLIBRARY_CC
	#else
		#define RMAPPACKETLIBRARY_CC __stdcall
	#endif
#else
	#define RMAPPACKETLIBRARY_API
	#define RMAPPACKETLIBRARY_CC
#endif



typedef enum
{
	RMAP_SUCCESS								= 0x00,
	RMAP_GENERAL_ERROR							= 0x01,
	RMAP_UNUSED_PACKET_TYPE_OR_COMMAND_CODE		= 0x02,
	RMAP_INVALID_KEY							= 0x03,
	RMAP_INVALID_DATA_CRC						= 0x04,
	RMAP_EARLY_EOP								= 0x05,
	RMAP_TOO_MUCH_DATA							= 0x06,
	RMAP_EEP									= 0x07,
	RMAP_VERIFY_BUFFER_OVERRUN					= 0x09,
	RMAP_COMMAND_NOT_IMPLEMENTED_OR_AUTHORISED	= 0x0a,
	RMAP_RMW_DATA_LENGTH_ERROR					= 0x0b,
	RMAP_INVALID_TARGET_LOGICAL_ADDRESS			= 0x0c,
	RMAP_INVALID_STATUS							= 0xff
} RMAP_STATUS;



#define RMAP_PROTOCOL_IDENTIFIER	1

#define RMAP_RESERVED_BIT				0x80
#define RMAP_COMMAND_BIT				0x40
#define RMAP_WRITE_OPERATION_BIT		0x20
#define RMAP_VERIFY_BEFORE_WRITE_BIT	0x10
#define RMAP_REPLY_BIT					0x08
#define RMAP_INCREMENT_ADDRESS_BIT		0x04
#define RMAP_REPLY_ADDRESS_LENGTH_BITS	0x03



typedef enum
{
	RMAP_WRITE_COMMAND				= RMAP_COMMAND_BIT |
										RMAP_WRITE_OPERATION_BIT,
	RMAP_WRITE_REPLY				= RMAP_WRITE_OPERATION_BIT,
	RMAP_READ_COMMAND				= RMAP_COMMAND_BIT,
	RMAP_READ_REPLY					= 0,
	RMAP_READ_MODIFY_WRITE_COMMAND	= RMAP_COMMAND_BIT |
										RMAP_VERIFY_BEFORE_WRITE_BIT,
	RMAP_READ_MODIFY_WRITE_REPLY	= RMAP_VERIFY_BEFORE_WRITE_BIT,
	RMAP_INVALID_PACKET_TYPE		= 0xff
} RMAP_PACKET_TYPE;



typedef struct
{
	RMAP_PACKET_TYPE	packetType;
	U8					*pTargetAddress;
	unsigned long		targetAddressLength;
	U8					*pReplyAddress;
	unsigned long		replyAddressLength;
	U8					*pProtocolIdentifier;
	U8					*pInstruction;
	/* Changed mcrw 01/11/11 */
	/* char				verifyBeforeWrite; */
	/* char				acknowledge; */
	/* char				incrementAddress; */
	U8				verifyBeforeWrite;
	U8				acknowledge;
	U8				incrementAddress;
	U8					*pKey;
	U16					*pTransactionIdentifier;
	U32					*pReadWriteAddress;
	U8					*pExtendedReadWriteAddress;
	U8					*pStatus;
	U8					*pHeader;
	unsigned long		headerLength;
	U8					*pHeaderCRC;
	U8					*pData;
	void				*pDataLength;
	U32					dataLength;
	U8					*pDataCRC;
	U8					*pMask;
	/*	char			maskLength;	*/
	U8					maskLength;
	U8					*pRawPacket;
	unsigned long		rawPacketLength;
} RMAP_PACKET;



/* Declarations of the functions provided by the RMAP Packet Library */

RMAPPACKETLIBRARY_API
U32
RMAPPACKETLIBRARY_CC
RMAP_GetVersion(
	);

RMAPPACKETLIBRARY_API
U8
RMAPPACKETLIBRARY_CC
RMAP_CalculateCRC(
	void			*pBuffer,
	unsigned long	len
	);

RMAPPACKETLIBRARY_API
U8
RMAPPACKETLIBRARY_CC
RMAP_CalculateCRCWithSeed(
	void			*pBuffer,
	unsigned long	len,
	U8				crc
	);

RMAPPACKETLIBRARY_API
char
RMAPPACKETLIBRARY_CC
RMAP_IsCRCValid(
	void			*pBuffer,
	unsigned long	len,
	U8				crc
	);

RMAPPACKETLIBRARY_API
RMAP_STATUS
RMAPPACKETLIBRARY_CC
RMAP_CheckPacketValid(
	void			*pRawPacket,
	unsigned long	packetLength,
	RMAP_PACKET		*pPacketStruct,
	char			checkPacketTooLong
	);

RMAPPACKETLIBRARY_API
RMAP_PACKET_TYPE
RMAPPACKETLIBRARY_CC
RMAP_GetPacketType(
	RMAP_PACKET	*pPacketStruct
	);

RMAPPACKETLIBRARY_API
U8 *
RMAPPACKETLIBRARY_CC
RMAP_GetTargetAddress(
	RMAP_PACKET	*pPacketStruct,
	unsigned long	*pTargetAddressLength
	);

RMAPPACKETLIBRARY_API
char
RMAPPACKETLIBRARY_CC
RMAP_GetVerifyBeforeWrite(
	RMAP_PACKET	*pPacketStruct
	);

RMAPPACKETLIBRARY_API
char
RMAPPACKETLIBRARY_CC
RMAP_GetPerformAcknowledgement(
	RMAP_PACKET	*pPacketStruct
	);

RMAPPACKETLIBRARY_API
char
RMAPPACKETLIBRARY_CC
RMAP_GetIncrementAddress(
	RMAP_PACKET	*pPacketStruct
	);

RMAPPACKETLIBRARY_API
U8
RMAPPACKETLIBRARY_CC
RMAP_GetKey(
	RMAP_PACKET	*pPacketStruct
	);

RMAPPACKETLIBRARY_API
U8 *
RMAPPACKETLIBRARY_CC
RMAP_GetReplyAddress(
	RMAP_PACKET		*pPacketStruct,
	unsigned long	*pReplyAddressLength
	);

RMAPPACKETLIBRARY_API
U16
RMAPPACKETLIBRARY_CC
RMAP_GetTransactionID(
	RMAP_PACKET	*pPacketStruct
	);

RMAPPACKETLIBRARY_API
U32
RMAPPACKETLIBRARY_CC
RMAP_GetAddress(
	RMAP_PACKET	*pPacketStruct,
	U8			*pExtendedAddress
	);

RMAPPACKETLIBRARY_API
U8 *
RMAPPACKETLIBRARY_CC
RMAP_GetData(
	RMAP_PACKET	*pPacketStruct,
	U32			*pDataLength
	);

RMAPPACKETLIBRARY_API
RMAP_STATUS
RMAPPACKETLIBRARY_CC
RMAP_GetStatus(
	RMAP_PACKET	*pPacketStruct
	);

RMAPPACKETLIBRARY_API
U8
RMAPPACKETLIBRARY_CC
RMAP_GetHeaderCRC(
	RMAP_PACKET	*pPacketStruct
	);

RMAPPACKETLIBRARY_API
U8
RMAPPACKETLIBRARY_CC
RMAP_GetDataCRC(
	RMAP_PACKET	*pPacketStruct
	);

RMAPPACKETLIBRARY_API
U8 *
RMAPPACKETLIBRARY_CC
RMAP_GetMask(
	RMAP_PACKET	*pPacketStruct,
	U8			*pMaskLength
	);

RMAPPACKETLIBRARY_API
unsigned long
RMAPPACKETLIBRARY_CC
RMAP_CalculateWriteCommandPacketLength(
	unsigned long	targetAddressLength,
	unsigned long	replyAddressLength,
	U32				dataLength,
	char			alignment
	);

RMAPPACKETLIBRARY_API
char
RMAPPACKETLIBRARY_CC
RMAP_FillWriteCommandPacket(
	U8				*pTargetAddress,
	unsigned long	targetAddressLength,
	U8				*pReplyAddress,
	unsigned long	replyAddressLength,
	char			verifyBeforeWrite,
	char			acknowledge,
	char			incrementAddress,
	U8				key,
	U16				transactionIdentifier,
	U32				writeAddress,
	U8				extendedWriteAddress,
	U8				*pData,
	U32				dataLength,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment,
	U8				*pRawPacket,
	unsigned long	rawPacketLength
	);

RMAPPACKETLIBRARY_API
void *
RMAPPACKETLIBRARY_CC
RMAP_BuildWriteCommandPacket(
	U8				*pTargetAddress,
	unsigned long	targetAddressLength,
	U8				*pReplyAddress,
	unsigned long	replyAddressLength,
	char			verifyBeforeWrite,
	char			acknowledge,
	char			incrementAddress,
	U8				key,
	U16				transactionIdentifier,
	U32				writeAddress,
	U8				extendedWriteAddress,
	U8				*pData,
	U32				dataLength,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment
	);

RMAPPACKETLIBRARY_API
void *
RMAPPACKETLIBRARY_CC
RMAP_BuildWriteRegisterPacket(
	U8				*pTargetAddress,
	unsigned long	targetAddressLength,
	U8				*pReplyAddress,
	unsigned long	replyAddressLength,
	char			verifyBeforeWrite,
	char			acknowledge,
	char			incrementAddress,
	U8				key,
	U16				transactionIdentifier,
	U32				writeAddress,
	U8				extendedWriteAddress,
	U32				registerValue,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment
	);

RMAPPACKETLIBRARY_API
unsigned long
RMAPPACKETLIBRARY_CC
RMAP_CalculateWriteReplyPacketLength(
	unsigned long	initiatorAddressLength,
	char			alignment
	);

RMAPPACKETLIBRARY_API
char
RMAPPACKETLIBRARY_CC
RMAP_FillWriteReplyPacket(
	U8				*pInitiatorAddress,
	unsigned long	initiatorAddressLength,
	U8				targetAddress,
	char			verifyBeforeWrite,
	char			incrementAddress,
	RMAP_STATUS		status,
	U16				transactionIdentifier,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment,
	U8				*pRawPacket,
	unsigned long	rawPacketLength
	);

RMAPPACKETLIBRARY_API
void *
RMAPPACKETLIBRARY_CC
RMAP_BuildWriteReplyPacket(
	U8				*pInitiatorAddress,
	unsigned long	initiatorAddressLength,
	U8				targetAddress,
	char			verifyBeforeWrite,
	char			incrementAddress,
	RMAP_STATUS		status,
	U16				transactionIdentifier,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment
	);

RMAPPACKETLIBRARY_API
unsigned long
RMAPPACKETLIBRARY_CC
RMAP_CalculateReadCommandPacketLength(
	unsigned long	targetAddressLength,
	unsigned long	replyAddressLength,
	char			alignment
	);

RMAPPACKETLIBRARY_API
char
RMAPPACKETLIBRARY_CC
RMAP_FillReadCommandPacket(
	U8				*pTargetAddress,
	unsigned long	targetAddressLength,
	U8				*pReplyAddress,
	unsigned long	replyAddressLength,
	char			incrementAddress,
	U8				key,
	U16				transactionIdentifier,
	U32				readAddress,
	U8				extendedReadAddress,
	U32				dataLength,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment,
	U8				*pRawPacket,
	unsigned long	rawPacketLength
	);

RMAPPACKETLIBRARY_API
void *
RMAPPACKETLIBRARY_CC
RMAP_BuildReadCommandPacket(
	U8				*pTargetAddress,
	unsigned long	targetAddressLength,
	U8				*pReplyAddress,
	unsigned long	replyAddressLength,
	char			incrementAddress,
	U8				key,
	U16				transactionIdentifier,
	U32				readAddress,
	U8				extendedReadAddress,
	U32				dataLength,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment
	);

RMAPPACKETLIBRARY_API
void *
RMAPPACKETLIBRARY_CC
RMAP_BuildReadRegisterPacket(
	U8				*pTargetAddress,
	unsigned long	targetAddressLength,
	U8				*pReplyAddress,
	unsigned long	replyAddressLength,
	char			incrementAddress,
	U8				key,
	U16				transactionIdentifier,
	U32				readAddress,
	U8				extendedReadAddress,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment
	);

RMAPPACKETLIBRARY_API
unsigned long
RMAPPACKETLIBRARY_CC
RMAP_CalculateReadReplyPacketLength(
	unsigned long	initiatorAddressLength,
	U32				dataLength,
	char			alignment
	);

RMAPPACKETLIBRARY_API
char
RMAPPACKETLIBRARY_CC
RMAP_FillReadReplyPacket(
	U8				*pInitiatorAddress,
	unsigned long	initiatorAddressLength,
	U8				targetAddress,
	char			incrementAddress,
	RMAP_STATUS		status,
	U16				transactionIdentifier,
	U8				*pData,
	U32				dataLength,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment,
	U8				*pRawPacket,
	unsigned long	rawPacketLength
	);

RMAPPACKETLIBRARY_API
void *
RMAPPACKETLIBRARY_CC
RMAP_BuildReadReplyPacket(
	U8				*pInitiatorAddress,
	unsigned long	initiatorAddressLength,
	U8				targetAddress,
	char			incrementAddress,
	RMAP_STATUS		status,
	U16				transactionIdentifier,
	U8				*pData,
	U32				dataLength,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment
	);

RMAPPACKETLIBRARY_API
unsigned long
RMAPPACKETLIBRARY_CC
RMAP_CalculateReadModifyWriteCommandPacketLength(
	unsigned long	targetAddressLength,
	unsigned long	replyAddressLength,
	U32				dataAndMaskLength,
	char			alignment
	);

RMAPPACKETLIBRARY_API
char
RMAPPACKETLIBRARY_CC
RMAP_FillReadModifyWriteCommandPacket(
	U8				*pTargetAddress,
	unsigned long	targetAddressLength,
	U8				*pReplyAddress,
	unsigned long	replyAddressLength,
	U8				key,
	U16				transactionIdentifier,
	U32				readModifyWriteAddress,
	U8				extendedReadModifyWriteAddress,
	U8				dataAndMaskLength,
	U8				*pData,
	U8				*pMask,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment,
	U8				*pRawPacket,
	unsigned long	rawPacketLength
	);

RMAPPACKETLIBRARY_API
void *
RMAPPACKETLIBRARY_CC
RMAP_BuildReadModifyWriteCommandPacket(
	U8				*pTargetAddress,
	unsigned long	targetAddressLength,
	U8				*pReplyAddress,
	unsigned long	replyAddressLength,
	U8				key,
	U16				transactionIdentifier,
	U32				readModifyWriteAddress,
	U8				extendedReadModifyWriteAddress,
	U8				dataAndMaskLength,
	U8				*pData,
	U8				*mask,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment
	);

RMAPPACKETLIBRARY_API
void *
RMAPPACKETLIBRARY_CC
RMAP_BuildReadModifyWriteRegisterPacket(
	U8				*pTargetAddress,
	unsigned long	targetAddressLength,
	U8				*pReplyAddress,
	unsigned long	replyAddressLength,
	U8				key,
	U16				transactionIdentifier,
	U32				readModifyWriteAddress,
	U8				extendedReadModifyWriteAddress,
	U32				registerValue,
	U32				mask,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment
	);

RMAPPACKETLIBRARY_API
unsigned long
RMAPPACKETLIBRARY_CC
RMAP_CalculateReadModifyWriteReplyPacketLength(
	unsigned long	initiatorAddressLength,
	U32				dataLength,
	char			alignment
	);

RMAPPACKETLIBRARY_API
char
RMAPPACKETLIBRARY_CC
RMAP_FillReadModifyWriteReplyPacket(
	U8				*pInitiatorAddress,
	unsigned long	initiatorAddressLength,
	U8				targetAddress,
	RMAP_STATUS		status,
	U16				transactionIdentifier,
	unsigned long	dataLength,
	U8				*pData,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment,
	U8				*pRawPacket,
	unsigned long	rawPacketLength
	);

RMAPPACKETLIBRARY_API
void *
RMAPPACKETLIBRARY_CC
RMAP_BuildReadModifyWriteReplyPacket(
	U8				*pInitiatorAddress,
	unsigned long	initiatorAddressLength,
	U8				targetAddress,
	RMAP_STATUS		status,
	U16				transactionIdentifier,
	unsigned long	dataLength,
	U8				*pData,
	unsigned long	*pRawPacketLength,
	RMAP_PACKET		*pPacketStruct,
	char			alignment
	);

RMAPPACKETLIBRARY_API
void
RMAPPACKETLIBRARY_CC
RMAP_FreeBuffer(
	void	*pBuffer
	);


/* Macros for accessing the version */

#define RMAP_GET_VERSION_MAJOR(versionInfo)	(((version) & 0xff000000) >> 24)
#define RMAP_GET_VERSION_MINOR(versionInfo)	(((version) & 0x00ff0000) >> 16)
#define RMAP_GET_VERSION_EDIT(versionInfo)	(((version) & 0x0000ffc0) >> 6)
#define RMAP_GET_VERSION_PATCH(versionInfo)	((version) & 0x0000003f)


/* Macros provided for compatibility with older versions of the library */

#define RMAP_CheckPacketFormat(pRawPacket, packetLength, pPacketStruct)	\
	(RMAP_CheckPacketValid(pRawPacket, packetLength, pPacketStruct, 0) == \
		RMAP_SUCCESS)

#define RMAP_GetDestinationAddress(pPacketStruct, pTargetAddressLength)	\
	RMAP_GetTargetAddress(pPacketStruct, pTargetAddressLength)

#define RMAP_VerifyBeforeWrite(pPacketStruct)	\
	RMAP_GetVerifyBeforeWrite(pPacketStruct)

#define RMAP_PerformAcknowledgement(pPacketStruct)	\
	RMAP_GetPerformAcknowledgement(pPacketStruct)

#define RMAP_IncrementTarget(pPacketStruct)	\
	RMAP_GetIncrementAddress(pPacketStruct)

#define RMAP_GetDestinationKey(pPacketStruct)	\
	RMAP_GetKey(pPacketStruct)

#define RMAP_GetSourceAddress(pPacketStruct, pReplyAddressLength)	\
	RMAP_GetReplyAddress(pPacketStruct, pReplyAddressLength)


#define RMAP_INVALID_DESTINATION_KEY				RMAP_INVALID_KEY
#define RMAP_CARGO_TOO_LARGE						RMAP_TOO_MUCH_DATA
#define RMAP_EARLY_EEP								RMAP_EEP
#define RMAP_INVALID_DESTINATION_LOGICAL_ADDRESS	\
	RMAP_INVALID_TARGET_LOGICAL_ADDRESS

#define RMAP_WRITE_RESPONSE					RMAP_WRITE_REPLY
#define RMAP_READ_RESPONSE					RMAP_READ_REPLY
#define RMAP_READ_MODIFY_WRITE_RESPONSE		RMAP_READ_MODIFY_WRITE_REPLY

#define RMAP_ACKNOWLEDGE_BIT		RMAP_REPLY_BIT

#define PRMAP_STATUS		RMAP_STATUS *
#define PRMAP_PACKET_TYPE	RMAP_PACKET_TYPE *
#define PRMAP_PACKET		RMAP_PACKET *



#ifdef __cplusplus
}
#endif



#endif	/* RMAP_PACKET_LIBRARY_H */