Initial commit.

include/internal/imoc_core.h

@@ -0,0 +1,173 @@
+#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_*/