MPIonCell/include/internal/imoc_core.h

#ifndef MOC_INTERNAL_CORE_
#define MOC_INTERNAL_CORE_


#include <stdint.h>


/**
 * \addtogroup internal_core
 * 
 * This section deals with the data-structures and the basic concepts which 
 * form the core of this implementation.
 * 
 * \section icore_struct Data-Structures
 * 
 * Basically there are four data-structures. \ref moc_message_envelope_struct
 * holds meta-information about a message and \ref moc_message_status_struct holds
 * information about used buffer-space and provide means for a receiving proccess
 * to send some information back to the sending process. 
 * 
 * \ref moc_process_struct stores information every node needs to know about the 
 * other nodes to successfully communicate with them.
 * 
 * The forth data-structure (actually there are two) \ref moc_node_handle_ppu_struct
 * respectively \ref moc_node_handle_spu_struct holds information a node know about 
 * itself and the execution environment.
 * 
 * \section core_conc Concepts
 * 
 * Every node has (N-1) queues for incoming messages, where N is the overall number
 * of node. Each queue is exclusively used by a specific remote node to write 
 * meta-data about the message to be send into it (queue-entries are of type \ref
 * moc_message_envelope_struct). Because there are several independend queues and no
 * global time is available, an exact order of all incoming messages cannot be guaranteed.
 * Corrent ordering can only be guaranteed for messages from the same source-node.
 * The queues are implemented in form of a big array which is divided in (N-1) equally 
 * sized pieces.
 * 
 * Furthermore every node has an array of size (N-1)*m where m is the size of a
 * message-queue (entries are of type \ref moc_message_status_struct). 
 * This array is used for buffer-management and to report the status of a message
 * back to the sender.
 * Every message currently under progress has a message-id which is unique in respect 
 * to the sending-node. This message-id is equal to the index of the corresponding
 * entry of the status-array.
 * 
 * In order to communicate with other nodes every node also keeps a list of all nodes
 * in the execution environment (entries are of type \ref moc_process_struct).
 * 
 * Pointers to the own arrays and some further information a node needs to know (e.g.
 * own rank) is stored in the globally accessible variable \ref node_handle.
 **/
//@{
/**
 * @name PPU & SPU
 **/
//@{


/**
 * Default size of the message-queues.
 **/
#define MOC_QUEUE_SIZE	4

/**
 * Default size of the buffers used for buffered communication.
 **/
#define MOC_BUFFER_SIZE	2048


/**
 * Message-envelope structure.
 * 
 * Is used to store meta-data about the message in the message-queues of the receiving process.
 **/
typedef struct moc_message_envelope_struct
	{
	uint8_t id; /**< Message-ID. Also index of message-status-array*/
	uint8_t tag; /**< Message-tag*/
	uint8_t communicator; /**< Communicator of message*/
	union
		{
		struct 
			{
			unsigned int valid 		 	: 1; /**< Is the message valid? */
			unsigned int signal_back	: 1; /**< Should the status be reported back to the
			 								   	  sending process */
			unsigned int special	 	: 1; /**< Is this message a special message? */
			unsigned int collaborative  : 1; /**< Is this message part of a collaborative 
												  communication? */
			unsigned int channel		: 2; /**< Which channel is used to transport the message? */
			unsigned int in_mm			: 1; /**< Are the data in Main-Memory? */
			unsigned int keep_valid    	: 1; /**< Should the message-status-entry be invalidated? */
			} __attribute__((__packed__)) bits; /**< flag-struct */
		uint8_t value; /**< union-value */
		} flags; /**< flag-union */
	unsigned int size		: 24; /**< Message-size in byte*/
	unsigned int datatype 	: 8;  /**< Data-type of message-entries */ 
	uint64_t message_address; /**< Effective address of message-data*/
	} __attribute__((__packed__)) moc_message_envelope_t; 
	
	
/**
 * Constant for moc_message_envelope_t.flags.channel.
 * 
 * Message is transported via a DMA-Call.
 **/
#define IMOC_MESSAGE_CHANNEL_DMA	0
	
	
/**
 * Constant for moc_message_envelope_t.flags.channel.
 * 
 * Message is embedded in message-envelope.
 **/
#define IMOC_MESSAGE_CHANNEL_ENV	1
	
	
/**
 * Message-status structure.
 * 
 * Is used to store information about the message-status and the buffer used in the
 * message-status-array.
 **/
typedef struct moc_message_status_struct
	{
	uint32_t buffer_offset; /**< allocated buffer-offset from buffer-base */
	uint32_t message_size; /**< size of message in byte */
	uint32_t error_value; /**< optional error-code of message */
	union
		{
		struct
			{
			unsigned int valid 			: 1; /**< Is this entry valid? */
			unsigned int outstanding	: 1; /**< Message is not yet received? */
			unsigned int buffer_used	: 1; /**< Is Bufferspace used? */
			unsigned int reserved		: 5; /**< reserved */
			} __attribute__((__packed__)) bits; /**< flag-struct */
		uint8_t value; /**< union-value */
		} flags; /**< flag-union */
	uint8_t reserved[3]; /**< reserved */
	} __attribute__((__packed__)) moc_message_status_t; 

	
/**
 * Constant for moc_process_struct.type.
 **/
#define MOC_PPU_PROCESS	0

/**
 * Constant for moc_process_struct.type.
 **/
#define MOC_SPU_PROCESS	1


/**
 * Process-information structure.
 * 
 * Stores information about a MOC-Process. This information is used for communication
 * between the processes.
 */
typedef struct moc_process_struct
	{
	uint8_t type; /**< Process-type (SPU or PPU) */
	uint8_t reserved[7]; /**< reserved */
	uint64_t inbox_queue_base; /**< effective base-address of message-queues */
	uint64_t stat_array_base; /**< effective base-address of message-status-array */
	uint64_t ps_base; /**< effective base-address of problem-state (Signals, mailboxes, ...)*/
	} __attribute__((__packed__)) moc_process_t; 

//@}
//@}
#endif /*MOC_INTERNAL_CORE_*/