/**
* \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.
*
* IMPORTANT NOTE:
* \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
* \#define NO_STAR_TYPES
\n
* Alternatively you can compile your code with a flag of
* -DNO_STAR_TYPES
.\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 © 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 */