include/internal/imoc.h

Go to the documentation of this file.

#ifndef IMOC_H_
#define IMOC_H_


#include <stdint.h>

#include "../moc.h"
#include "imoc_core.h"



/**
 * \addtogroup internal_p2p_imm
 **/
//@{

/**
 * @name Constants for MOC_Request.request_type
 */
//@{

/**
 * MOC_Request is associated with a DMA-Communication.
 **/
#define MOC_REQ_TYPE_DMA                0

/**
 * MOC_Request is associated with aISsend-Communication.
 **/
#define MOC_REQ_TYPE_ISSEND             1

//@}
//@}

/**
 * \addtogroup internal_p2p_main
 **/
//@{

/**
 * @name Internal constants
 */
//@{

/**
 * Defines a treshold, when to use memcpy and when to use DMA in a get-operation
 * on the PPU.
 **/
#define MEMCPY_GET_TRESHOLD             156

/**
 * Defines a treshold, when to use memcpy and when to use DMA in a put-operation
 * on the PPU.
 **/
#define MEMCPY_PUT_TRESHOLD             2210

//@}

/**
 * @name Internal shared functions
 */
//@{

/**
 * Get the next valid message-envelope from "source" with specified "tag" and "comm".
 *
 * @param source \b in rank of sending node
 * @param tag \b in message-tag
 * @param comm \b in message-communicator
 * @param isSpecial \b in true to return special-message
 * @param status \b inout MOC_status-instance to add some information (e.g. source by MOC_ANY_SOURCE)
 * @returns pointer to the appropriate message-queue-entry.
 **/
moc_message_envelope_t* IMOC_get_entry(int source, int tag, MOC_Comm comm, int isSpecial, MOC_Status *status);


/**
 * Get next free entry in message-queue (a local copy of the message-queue has to be used).
 * To ensure correct ordering message-tag and -comm and -type has to be specified.
 *
 * @param pqueue \b in pointer to local copy of remote message-queue
 * @param tag \b in message-tag
 * @param comm \b in message-communicator
 * @param isSpecial \b in true if message should be a special message
 * @param index \b out index of free entry
 * @return 0 when success otherwise error-code
 **/
int IMOC_getFreeEntry ( moc_message_envelope_t* pqueue, uint8_t tag, MOC_Comm comm, int isSpecial, int* index );

/**
 * Get free message-ID.
 *
 * \note Message-ID is index of message-status-array
 *
 * @param mid \b out free message-ID
 * @retval MOC_SUCCESS No error; MPI routine completed successfully.
 * @retval MOC_ERR_MESSAGE_EXHAUSTED No further messages possible.
 **/
int IMOC_getFreeMID ( int *mid );

/**
 * Wait till message with message-ID mid has been received.
 *
 * Waits till message-status-flag 'outstanding' is 0.
 *
 * @param mid \b in message-ID
 * @return 0 when success otherwise error-code
 **/
int IMOC_waitForMessageCompletion ( uint8_t mid );

/**
 * Tests if message with message-ID mid has been received.
 *
 * Tests if message-status-flag 'outstanding' is 0.
 *
 * @param mid \b in message-ID
 * @param status \b out status of message
 * @retval MOC_SUCCESS No error; MPI routine completed successfully.
 **/
int IMOC_testForMessageCompletion ( uint8_t mid, uint8_t *status );

//@}
//@}




/**
 * \addtogroup internal_error
 *
 * This section deals with error-messages.
 *
 * An array of type \ref error_strings_struct stores error-messages and
 * their corresponding error-codes. \ref MOC_Error_string searches this
 * list for a given error-code and returns the error-message.
 **/
//@{


/**
 * Error-Strings structure.
 *
 * stores the error-string to a given error-code
 **/
typedef struct error_strings_struct
        {
        int error_code; /**< error-code */
        char * text; /**< error-text */
        } error_strings_t; /**< typedef for \ref error_strings_struct */


//@}



/**
 * \addtogroup internal_p2p_bmalloc
 *
 * Information about already allocated buffer-space is stored in the
 * status-array. But this information has no order which forces us
 * everytime we want to allocate buffer-space to create an ordered list
 * of already allocated buffer-space. To avoid this we have additionally
 * an ordered linked-list. This list orders the indexes (== message-IDs)
 * of the status-array-entries in ascending order of the memory-addresses.
 * This enables fast searching for free buffer-space.
 *
 * Allocated buffer-space is cleared by the receiving process by setting
 * the appropriate flag in the status-array-entry. This is done by a
 * DMA-Transfer and so no collaboration of the sending-process is needed.
 * During the next allocation of buffer-space nodes with disabled buffer-flags
 * are freed.
 **/
//@{



/**
 * Node of linked list holding information about allocated buffer-space.
 **/
typedef struct moc_internal_buffer_node_struct
        {
        struct moc_internal_buffer_node_struct *next_node; /**< Pointer to
                                                                                                                next entry **/
        uint8_t mid; /**< Message-ID of message using buffer-space.
                                Information about the used buffer-space is stored in the
                                appropriate message-status-entry (mid is index of entry). **/
        } moc_internal_buffer_node_t;



/**
 * Allocate buffer-space.
 *
 * @param size \b in size of buffer-space
 * @param mid  \b in corresponding message-ID
 * @return effective address of allocated buffer-space (16-byte aligned)
 **/
uint64_t IMOC_bmalloc ( uint32_t size, uint8_t mid );

//@}
#endif /*IMOC_H_*/

---