include/doxygen_main.doxygen

Go to the documentation of this file.

#ifndef MOC_DOXYGEN_MAIN_H_
#define MOC_DOXYGEN_MAIN_H_

/**
 * \mainpage MPI On Cell
 *
 * The idea of this project is to implement a message passing
 * library for work on the Cell BE. The main idea behind such
 * an implementation would be to help the programmer by adding
 * an layer of abstraction between the very low level libraries
 * by IBM and give him the possibility to work with an interface
 * he is more familiar with. To achieve this we decided to try
 * to keep very closely to the standard provided by the Message
 * Passing Interface (MPI), so that programmers knowing how to
 * write MPI programmers can easily work with our library.
 * Because of the very special nature of the Cell, it might not
 * be possible to keep 100% true to the standard, but we try to
 * introduce changes only when absolutely necessary and of great
 * benefit, because of some specialties of the Cell's hardware.
 *
 *
 * \par Table of Content
 * \par
 * \ref end_user
 * \par
 * \subpage restrictions
 * \par
 * \subpage violations
 * \par
 * \subpage performance
 * \par
 * \subpage conclusion
 * \if full
 * \par
 * \par
 * \ref internal_main
 * \endif
 **/


/**
 * \defgroup end_user End-User Documentation
 *
 * This section describes the public API provided by the MOC-library.
 *
 * If some things remain unclear, consult the official MPI-standard (Version 1.3).
 *
 * This library uses Direct Memory Access (DMA) provided by the Cell Broadband Engine.
 * So the use of other DMA operations than provided of this library is discouraged,
 * because it may interfere with this library. One exceptions are signals.
 * We don't use signals at all at the moment, so one can savely use signal.
 **/


/**
 * \defgroup environment_main Environmental Management
 * \ingroup end_user
 *
 * This chapter discusses routines for getting and, where appropriate, setting various parameters
 * that relate to the MPI implementation and the execution environment (such as error handling,
 * startup&shutdown and Time).
 **/
/**
 * \defgroup environment_startup Startup & Shutdown
 * \ingroup environment_main
 *
 * Functions to start and terminate the MOC-execution environment.
 *
 * To be able to communicate with other processes every MOC-process needs to setup his
 * MOC-Environment before any MOC-function can be called (there are some exceptions though).
 *
 * The PPU-process has a special role, because he is the one who starts the SPU-processes.
 * SPU-processes can be added to the MOC-environment by calling \ref MOC_Add_spu_thread with
 * the appropriate SPU-thread-handle (This implementation only supports the embedded binary
 * concept where the SPU-binary is embedded into the PPU-binary and accessed via a handle).
 * The order of calling determines the rank of the SPU-processes. To get the number of total
 * and available SPUs the functions \ref MOC_Get_avail_spu_count and \ref MOC_Get_max_spu_count
 * can be used.
 *
 * The buffer-size and the size of the message-queues can be set before calling \ref MOC_Init
 * on the PPU using \ref MOC_Set_buffer_size and \ref MOC_Set_queue_size.
 *
 * MOC_Init only returns after all processes have called this function and have set up their
 * environment.
 *
 * If the MOC-environment isn't needed anymore, \ref MOC_Finalize should be called by all
 * MOC-processes. MOC_Finalize only returns after all MOC-processes have called this functions
 * and have shutdown their environments.
 **/
/**
 * \defgroup environment_information Implementation Information
 * \ingroup environment_main
 **/
/**
 * \defgroup environment_error Error-Handling
 * \ingroup environment_main
 **/
/**
 * \defgroup environment_timer Timers and Synchronization
 * \ingroup environment_main
 **/

/**
 * \defgroup p2p_main Point-to-Point Communication
 * \ingroup end_user
 *
 * Sending and receiving of messages by processes is the basic MPI communication mechanism.
 * The basic point-to-point communication operations are send and receive.
 *
 * \ref MOC_Send uses either buffered or synchronous send depending on the message-size
 * (Short messages are transmitted using buffered send and long messages are transmitted using
 * synchronous send).
 *
 * \ref MOC_Recv receives all messages irrespective wether buffered or synchronous
 * communication is used.
 *
 * \note Because there are separate message-queues for each remote process and no distinct
 *       global ordering of messages, there may be some situation where a message from a
 *       process may never be received. This may occur when MOC_Recv, MOC_Probe and MOC_IProbe
 *       are used with MOC_ANY_SOURCE, because then there is the possibility that new messages
 *       are received before a specific message from a process with a higher rank than the other
 *       senders. This may also occur with lower possibility when using MOC_ANY_TAG between
 *       messages from the same sender but with other tags.
 *
 **/
/**
 * \defgroup p2p_status Return Status
 * \ingroup p2p_main
 **/
/**
 * \defgroup p2p_datatype Datatypes
 * \ingroup p2p_main
 **/
/**
 * \defgroup p2p_synch Synchronous Communication
 * \ingroup p2p_main
 *
 * Direct blocking sending of messages without any intermediate buffer.
 *
 * The blocking synchronous send-operation returns only when the receiver has completely
 * received the message.
 **/
/**
 * \defgroup p2p_buffered Buffered Communication
 * \ingroup p2p_main
 *
 * Blocking sending of messages with the use of an intermediate buffer.
 *
 * The blocking buffered send-operation returns if the send-buffer can be safely reused
 * (after the data has been copied into the intermediate buffer).
 **/
/**
 * \defgroup p2p_sendrecv Send-Receive
 * \ingroup p2p_main
 *
 * The send-receive operations combine in one call the sending of a message
 * to one destination and the receiving of another message, from another process.
 *
 * A message sent by a send-receive operation can be received by a regular receive
 * operation or probed by a probe operation; a send-receive operation can receive
 * a message sent by a regular send operation.
 **/
/**
 * \defgroup p2p_imm Non-Blocking Communication
 * \ingroup p2p_main
 *
 * Non-blocking sending and receiving messages.
 *
 * Because of restrictions of the Cell Broadband Engine non-blocking communication can
 * only be provided with a lot of limitations. In fact the only operation where
 * non-blocking communication make sense is synchronous send.
 *
 * \ref MOC_ISend uses blocking buffered send or non-blocking synchronous send according to
 * the message size.
 *
 * \note Every non-blocking communication operation has to be finished using \ref MOC_Test
 * or \ref MOC_Wait, otherwise resources are no freed and some data are not copied correctly.
 **/


/**
 * \defgroup broadcast Collective Communication
 * \ingroup end_user
 *
 * Communication that involves a group of processes.
 *
 * A collective operation is normally executed by having all processes in the group call
 * the communication routine, with matching arguments. Since there are no means for creating
 * groups currently implemented, the only available groups are MOC_COMM_WORLD and
 * MOC_COMM_SELF.
 **/


/**
 * \defgroup dma_access Direct Memory Access
 * \ingroup end_user
 *
 * Functions which use DMA to transfer Data.
 *
 * The operations defined in this section provide simple means to use Direct Memory
 * Access (DMA).
 *
 * The MPI-standard assumes a distributed memory architecture, where
 * active participation of the sending and the receiving processes is required. But
 * the Cell Broadband Engine is a distributed shared memory architecture which provides
 * a common address space and DMA-Operations enabling processes to write data directly
 * into the memory of an remote process without active participation of the receiving
 * process.
 * DMA is faster than Send-Receive but more complicated to handle, and so there are some
 * functions provided to enable the advantages of DMA and to hide as much complexity as
 * possible. So the user doesn't have to care about the upper-limit of an DMA-transfer
 * and in get-operations the data-size doesn't have to be a multiple of 16-byte. However
 * the data-address should be at least 16-byte aligned and in put-operations the data-size
 * has to be a multiple of 16-byte.
 *
 * There are two kind of addresses. Local-store addresses are used on the SPUs and are only
 * valid in context of a specific SPU. Effective addresses define a common address-space and
 * are used on the PPU. Functions to translate between those address types are provided.
 *
 * DMA-operations can be blocking or non-blocking. The status of non-blocking DMA-calls can
 * be requested by using \ref MOC_Test and \ref MOC_Wait.
 *
 * \note Every non-blocking DMA operation has to be finished using \ref MOC_Test
 * or \ref MOC_Wait, otherwise resources are no freed and some data are not copied correctly.
 **/

/**
 * \defgroup comm_main Groups, Context and Communicators
 * \ingroup end_user
 *
 * The MOC communicator specifies a group of processes inside which
 * a communication occurs.
 * Initially there is a single communicator, MPI_COMM_WORLD, which
 * contains all of the processes involved in the computation.
 **/
/**
 * \defgroup comm_mgt Communicator Management
 * \ingroup comm_main
 **/




#endif /*MOC_DOXYGEN_MAIN_H_*/

---