fsfw/rmap/RMAP.h

#ifndef RMAPpp_H_
#define RMAPpp_H_

#include <framework/returnvalues/HasReturnvaluesIF.h>
#include <framework/rmap/RMAPCookie.h>

//SHOULDTODO: clean up includes for RMAP, should be enough to include RMAP.h but right now it's quite chaotic...

/**
 * API for a Cookie/Channel based RMAP implementation.
 *
 * The API offers the four basic RMAP actions: sending a Read or Write command and getting the reply to each.
 * As RMAP is an asynchronous protocol, these are implemented as four seperate calls. There are blocking
 * calls which combine a send and get call using a timeout, but these are "real" blocking, looping in between
 * the calls.
 *
 * Cookies are used to contain Information between a send[Read,Write]Command and a get[Read,Write]Reply call,
 * one can think of them like *nix file descriptors. A cookie is valid from a sendX call until the related getX
 * call. That means if a cookie is used in a getX call, the reply to the sendX call the cookie was used with
 * previously is returned.
 * Depending on the underlying RMAPChannel implementation, a cookie can also be valid for more than one getX
 * call, but this should not be assumed generally.
 * A cookie encapsulates information like the RMAP Channel to use, as well as the RMAP Address
 * and a Command Mask used for specifying which RMAP capabilities are used.
 * Cookies are created without interaction with this API, there is no open() call. The RMAP implementation
 * will initialize all fields which are not set by the cookie's constructor.
 *
 * The RMAP implementation relies on Channels. A channel is used to construct the RMAP Headers and handle the
 * protocol. It is access via the RMAPChannelIF. Thus it is possible to use different Implementations which only
 * need to implement the RMAPChannelIF. A channel is also responsible for accessing the lower layers, for example
 * a SPaceWire transport layer.
 *
 * There is one RMAP Channel per physical device. The cookie-channel as well as the device-channel assignment
 * can be changed at runtime to allow for example redundancy switching. This API is static as the information which
 * channel to use is contained within the cookie.
 */
class RMAP: public HasReturnvaluesIF {
public:
	static const uint8_t INTERFACE_ID = CLASS_ID::RMAP_CHANNEL;

	//static const ReturnValue_t COMMAND_OK = MAKE_RETURN_CODE(0x00);
	static const ReturnValue_t COMMAND_NO_DESCRIPTORS_AVAILABLE =
			MAKE_RETURN_CODE(0xE1); //no descriptors available for sending command; command was not sent
	static const ReturnValue_t COMMAND_BUFFER_FULL = MAKE_RETURN_CODE(0xE2); //no receiver buffer available for expected len; command was not sent
	static const ReturnValue_t COMMAND_CHANNEL_OUT_OF_RANGE = MAKE_RETURN_CODE(
			0xE3); //The cookie points to an invalid channel; command was not sent
//Replaced by DeviceCommunicationIF::TOO_MUCH_DATA	static const ReturnValue_t COMMAND_TOO_BIG = MAKE_RETURN_CODE(0xE4); //the data that was to be sent was too long for the hw to handle (write command) or the expected len was bigger than maximal expected len (read command)
	//command was not sent
//replaced by DeviceCommunicationIF::NULLPOINTER	static const ReturnValue_t COMMAND_NULLPOINTER = MAKE_RETURN_CODE(0xE5); //datalen was != 0 but data was == NULL in write command, or nullpointer in read command
	static const ReturnValue_t COMMAND_CHANNEL_DEACTIVATED = MAKE_RETURN_CODE(
			0xE6);	//the channel has no port set
	static const ReturnValue_t COMMAND_PORT_OUT_OF_RANGE = MAKE_RETURN_CODE(
			0xE7);	//The specified port is not valid
	static const ReturnValue_t COMMAND_PORT_IN_USE = MAKE_RETURN_CODE(0xE8);//The specified port is already in use
	static const ReturnValue_t COMMAND_NO_CHANNEL = MAKE_RETURN_CODE(0xE9);//The cookie to work with has no channel assigned.
	static const ReturnValue_t NO_HW_CRC = MAKE_RETURN_CODE(0xEA);//The SpW port does not support HW CRC generation, which is unsupported
	//return values for both get_write_reply and get_read_reply
	static const ReturnValue_t REPLY_NO_REPLY = MAKE_RETURN_CODE(0xD0);	//no reply was received
	static const ReturnValue_t REPLY_NOT_SENT = MAKE_RETURN_CODE(0xD1);	//command was not sent, implies no reply
	static const ReturnValue_t REPLY_NOT_YET_SENT = MAKE_RETURN_CODE(0xD2);	//command is still waiting to be sent
	static const ReturnValue_t REPLY_MISSMATCH = MAKE_RETURN_CODE(0xD3);//a read command was issued, but get_write_rply called, or other way round
	static const ReturnValue_t REPLY_TIMEOUT = MAKE_RETURN_CODE(0xD4);//timeout
//replaced by DeviceCommunicationIF::NULLPOINTER	static const ReturnValue_t REPLY_NULLPOINTER = MAKE_RETURN_CODE(0xD5);//one of the arguments in a read reply was NULL
	//return values for get_reply
	static const ReturnValue_t REPLY_INTERFACE_BUSY = MAKE_RETURN_CODE(
			0xC0);//Interface is busy (transmission buffer still being processed)
	static const ReturnValue_t REPLY_TRANSMISSION_ERROR =
			MAKE_RETURN_CODE(0xC1);	//Interface encountered errors during last operation, data could not be processed. (transmission error)
	static const ReturnValue_t REPLY_INVALID_DATA = MAKE_RETURN_CODE(
			0xC2);	//Invalid data (amount / value)
	static const ReturnValue_t REPLY_NOT_SUPPORTED = MAKE_RETURN_CODE(
			0xC3);

	//return values for reset
	static const ReturnValue_t LINK_DOWN = MAKE_RETURN_CODE(0xF0);//The spw link is down
	//Other SpW codes:
	static const ReturnValue_t SPW_CREDIT = MAKE_RETURN_CODE(0xF1);
	static const ReturnValue_t SPW_ESCAPE = MAKE_RETURN_CODE(0xF2);
	static const ReturnValue_t SPW_DISCONNECT = MAKE_RETURN_CODE(0xF3);
	static const ReturnValue_t SPW_PARITY = MAKE_RETURN_CODE(0xF4);
	static const ReturnValue_t SPW_WRITE_SYNC = MAKE_RETURN_CODE(0xF5);
	static const ReturnValue_t SPW_INVALID_ADDRESS = MAKE_RETURN_CODE(0xF6);
	static const ReturnValue_t SPW_EARLY_EOP = MAKE_RETURN_CODE(0xF7);
	static const ReturnValue_t SPW_DMA = MAKE_RETURN_CODE(0xF8);
	static const ReturnValue_t SPW_LINK_ERROR = MAKE_RETURN_CODE(0xF9);


	//RMAP standard replies
	static const ReturnValue_t REPLY_OK = MAKE_RETURN_CODE(0);
	static const ReturnValue_t REPLY_GENERAL_ERROR_CODE = MAKE_RETURN_CODE(1);// The detected error does not fit into the other
	// error cases or the node does not support
	// further distinction between the errors
	static const ReturnValue_t REPLY_UNUSED_PACKET_TYPE_OR_COMMAND_CODE =
			MAKE_RETURN_CODE(2);	// The Header CRC was decoded correctly but
	// the packet type is reserved or the command
	// is not used by the RMAP protocol.
	static const ReturnValue_t REPLY_INVALID_KEY = MAKE_RETURN_CODE(3);	// The Header CRC was decoded correctly but
	// the device key did not match that expected
	// by the target user application
	static const ReturnValue_t REPLY_INVALID_DATA_CRC = MAKE_RETURN_CODE(4);// Error in the CRC of the data field
	static const ReturnValue_t REPLY_EARLY_EOP = MAKE_RETURN_CODE(5);// EOP marker detected before the end of the data
	static const ReturnValue_t REPLY_TOO_MUCH_DATA = MAKE_RETURN_CODE(6);// More than the expected amount of data in a
	// command has been received
	static const ReturnValue_t REPLY_EEP = MAKE_RETURN_CODE(7);	// EEP marker detected immediately after the
	// header CRC or during the transfer of data
	// and Data CRC or immediately thereafter.
	// Indicates that there was a communication
	// failure of some sort on the network
	static const ReturnValue_t REPLY_RESERVED = MAKE_RETURN_CODE(8);// Reserved
	static const ReturnValue_t REPLY_VERIFY_BUFFER_OVERRUN = MAKE_RETURN_CODE(
			9);	// The verify before write bit of the command
	// was set so that the data field was buffered in
	// order to verify the Data CRC before
	// transferring the data to target memory. The
	// data field was longer than able to fit inside
	// the verify buffer resulting in a buffer overrun
	// Note that the command is not executed in
	// this case
	static const ReturnValue_t REPLY_COMMAND_NOT_IMPLEMENTED_OR_NOT_AUTHORISED =
			MAKE_RETURN_CODE(10);// The target user application did not authorise
	// the requested operation. This may be because
	// the command requested has not been
	// implemented
	static const ReturnValue_t REPLY_RMW_DATA_LENGTH_ERROR = MAKE_RETURN_CODE(
			11);	// The amount of data in a RMW command is
	// invalid (0x01	 0x03	 0x05	 0x07 or  greater
	// than 0x08)
	static const ReturnValue_t REPLY_INVALID_TARGET_LOGICAL_ADDRESS =
			MAKE_RETURN_CODE(12);	// The Header CRC was decoded correctly but
	// the Target Logical Address was not the value
	// expected by the target

	/**
	 * Resets the underlying channel.
	 *
	 * @param cookie The cookie which points to the channel to reset
	 * @return
	 */
	static ReturnValue_t reset(RMAPCookie *cookie);

	/**
	 * send an RMAP write command
	 *
	 * datalen is only 24bit wide, rest will be ignored
	 * IMPORTANT: the data buffer must be datalen+1 large, as the driver might
	 * write a CRC sum at data[datalen]
	 * if you want to send an empty packet, just do datalen = 0 and data = NULL
	 *
	 * @param cookie The cookie to write to
	 * @param buffer the data to write
	 * @param length length of data
	 * @return
	 *      - @c COMMAND_NULLPOINTER				datalen was != 0 but data was == NULL in write command
	 *      - return codes of RMAPChannelIF::sendCommand()
	 */
	static ReturnValue_t sendWriteCommand(RMAPCookie *cookie, uint8_t* buffer,
			uint32_t length);

	/**
	 * get the reply to a write command
	 *
	 * @param cookie the cookie the command was sent with
	 * @return
	 *      - @c REPLY_MISSMATCH			a read command was issued, but getWriteReply called
	 *      - return codes of RMAPChannelIF::getReply()
	 */
	static ReturnValue_t getWriteReply(RMAPCookie *cookie);

	/**
	 * @see sendWriteCommand()
	 * @see getWriteReply()
	 *
	 * @param timeout_us the time after the function returns, if no reply was received
	 *
	 * @return
	 *       - All of sendWriteCommand()
	 *       - All of getWriteReply()
	 *       - @c REPLY_TIMEOUT				timeout
	 */
	static ReturnValue_t writeBlocking(RMAPCookie *cookie, uint8_t* buffer,
			uint32_t length, uint32_t timeout_us);

	/**
	 * send an RMAP read command
	 *
	 * @param cookie to cookie to read from
	 * @param expLength the expected maximum length of the reply
	 * @return
	 *      - @c COMMAND_NULLPOINTER				datalen was != 0 but data was == NULL in write command, or nullpointer in read command
	 *      - return codes of RMAPChannelIF::sendCommand()
	 */
	static ReturnValue_t sendReadCommand(RMAPCookie *cookie,
			uint32_t expLength);

	/**
	 * get a reply to an RMAP read command
	 *
	 * @param cookie the cookie that was read from
	 * @param[out] buffer the location of the data
	 * @param[out] size size of the data
	 * @return
	 *      - @c COMMAND_NULLPOINTER		buffer or size was NULL
	 *      - @c REPLY_MISSMATCH			a write command was issued, but getReadReply called
	 *      - return codes of RMAPChannelIF::getReply()
	 */
	static ReturnValue_t getReadReply(RMAPCookie *cookie, uint8_t **buffer,
			uint32_t *size);

	/**
	 * @see sendReadCommand()
	 * @see getReadReply()
	 *
	 * @param timeout_us the time after the function returns, if no reply was received
	 *
	 * @return
	 *       - All of sendReadCommand()
	 *       - All of getReadReply()
	 *       - @c REPLY_TIMEOUT				timeout
	 */
	static ReturnValue_t readBlocking(RMAPCookie *cookie, uint32_t expLength,
			uint8_t** buffer, uint32_t *size, uint32_t timeout_us);

protected:
	RMAP();
};

#endif /* RMAPpp_H_ */