245 lines
9.1 KiB
Plaintext
Executable File
245 lines
9.1 KiB
Plaintext
Executable 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_*/
|