219 lines
7.9 KiB
Plaintext
Executable File
219 lines
7.9 KiB
Plaintext
Executable File
#ifndef MOC_INTERNAL_DOXYGEN_MAIN_H_
|
|
#define MOC_INTERNAL_DOXYGEN_MAIN_H_
|
|
|
|
|
|
|
|
/**
|
|
* \defgroup internal_main Developer Documentation
|
|
*
|
|
* This section deals with the internal design and functionality. For correct
|
|
* understanding knowledge about the functionality of the Cell Broadband Engine
|
|
* is needed. So you should read the official CBE documentation before you
|
|
* continue.
|
|
*
|
|
* \note Because we had only access to a playstation, we cannot guarantee correct
|
|
* execution on another CBE-machine than a playstation 3.
|
|
**/
|
|
/**
|
|
* \defgroup internal_core Implementation-Core
|
|
* \ingroup internal_main
|
|
**/
|
|
/**
|
|
* \defgroup internal_am Address-Macros
|
|
* \ingroup internal_core
|
|
*
|
|
* Predefined Macros for calculating Addresses of Message-Queue and Status-Array.
|
|
**/
|
|
/**
|
|
* \defgroup internal_tm Test-Macros
|
|
* \ingroup internal_core
|
|
*
|
|
* Predefined Macros for testing the validity of parameters.
|
|
**/
|
|
/**
|
|
* \defgroup internal_env Environmental Management
|
|
* \ingroup internal_main
|
|
*
|
|
* Internals about Startup & Shutdown and Error-Handling
|
|
**/
|
|
/**
|
|
* \defgroup internal_init Startup & Shutdown
|
|
* \ingroup internal_env
|
|
*
|
|
* Internals about the startup of the execution-environment and
|
|
* SPU-Thread-Management.
|
|
*
|
|
* \section iinit_start Startup
|
|
*
|
|
* The PPU-Process creates for every SPU-thread an own thread using the
|
|
* pthread-library (see \ref internal_spu_thread). The rank of each prozess,
|
|
* the overall process count, the sizes of message-queue and buffer-space
|
|
* and the effective base address of the buffer is send to each SPU-thread via
|
|
* mailbox-messages. The SPU-threads then send the memory-addresses of their
|
|
* message-queues and status-arrays back to the PPU-process which writes this
|
|
* data into the prozess-list. After all SPU-Threads have reported back to the
|
|
* PPU-process the effective address of the PPU's process-list ist distributed
|
|
* among the SPU-processes which then copy the process-list via DMA in their
|
|
* local storages.
|
|
*
|
|
* \section iinit_shut Shutdown
|
|
*
|
|
* \subsection iinit_shut_ppu PPU
|
|
*
|
|
* The PPU-process waits till all SPU-threads have signalled that they are also
|
|
* executing the finalize-function. After that a signal is send back to each
|
|
* SPU-Thread that they can now stop execution. Then local ressources are freed
|
|
* and the finalize-function returns.
|
|
*
|
|
* \subsection iinit_shut_spu SPU
|
|
*
|
|
* A mailbox-message is send to the PPU to signal that the SPU-process is now
|
|
* executing the finalize-function. After that the SPU-process is waiting till
|
|
* a mailbox-message from the PPU-process is received. Then local ressources are
|
|
* freed and the finalize-function returns.
|
|
*
|
|
**/
|
|
/**
|
|
* \defgroup internal_spu_thread SPU-Thread Management
|
|
* \ingroup internal_init
|
|
*
|
|
* This section deals about the creation and management of SPU-threads.
|
|
**/
|
|
/**
|
|
* \defgroup internal_error Error-Handling
|
|
* \ingroup internal_env
|
|
**/
|
|
/**
|
|
* \defgroup internal_timer Timers and Synchronization
|
|
* \ingroup internal_env
|
|
*
|
|
* Internals about Time.
|
|
*
|
|
* On the PPU "gettimeofday()" from time.h is used, because it is the only function
|
|
* which seems to work ("clock()" from time.h always returns 0).
|
|
*
|
|
* On the SPU there are two implementations. One uses also "gettimeofday()" and the
|
|
* other uses the spu-timer-library. The reason for this lies in the fact, that the
|
|
* spu-timer-library was marked as prototype in Cell SDK 3.0 and the future development
|
|
* of this library was uncertain. Cell SDK 3.1 has integrated the spu-timer-library in
|
|
* the main-library and so the gettimeofday-implementation is now obsolete.
|
|
*
|
|
* \note The timebase-constant which is needed to calculate time is hardcoded, because
|
|
* there was no according function for retrieving this value in Cell SDK 3.0 and we had
|
|
* only access to a playstation 3. Now Cell SDK 3.1 provides a function for retrieving
|
|
* the timebase value, but we didn't use it to provide backwards-compatibility. So if
|
|
* you plan to use MOC on another platform than playstation 3 keep in mind to check if
|
|
* the timebase-value is correct.
|
|
*
|
|
**/
|
|
|
|
/**
|
|
* \defgroup internal_comm Groups, Context and Communicators
|
|
* \ingroup internal_main
|
|
*
|
|
* At the moment user-defined groups and communicators are not implemented and maybe never
|
|
* will be.
|
|
* At the moment user-defined groups and communicators are not implemented and maybe never
|
|
* will be. Nevertheless user-defined groups and communicators have been taken into
|
|
* consideration while making the software-design (e.g. reserved field for communicator
|
|
* in message-envelope). So it should be not too hard to implement groups and communicators.
|
|
* However a lot of things concerning communicators are hardcoded (e.g. parameter checks).
|
|
*
|
|
* To save memory only one byte is used to encode the communicator. So if one
|
|
* day user-defined communicators are implemented there are only 256 possible
|
|
* communicators.
|
|
**/
|
|
|
|
|
|
/**
|
|
* \defgroup internal_p2p_main Point-to-Point Communication
|
|
* \ingroup internal_main
|
|
*
|
|
* Internals about Point-to-Point Communication.
|
|
**/
|
|
/**
|
|
* \defgroup internal_p2p_dma DMA-Helper Functions
|
|
* \ingroup internal_p2p_main
|
|
*
|
|
* Functions wrapping DMA-Transfers.
|
|
*
|
|
* The Cell Broadband Engine uses Direct Memory Access (DMA) for communication. Therefore
|
|
* data of a MOC-message is transfered using DMA operations. Because programming DMA is
|
|
* rather complex, some functions are provided to hide this complexity. One DMA-call can
|
|
* only tranfer a maximum of 16KByte of data and the data-size has to be a multiple of
|
|
* 16 byte. The provided functions split the data into multiple DMA-calls if needed. If
|
|
* the data-size requires it, an intermediate buffer is used into which a separate
|
|
* DMA-Call transfers 16 byte containing the piece of data not fitting into the 16-byte
|
|
* scheme. Then only the needed bytes are copied into the receive-buffer. But the latter
|
|
* only works for a get-operation.
|
|
*
|
|
* The internal DMA-functions are also made publicly available via wrapping-function
|
|
* (see chapter \ref dma_access) which provide parameter checks.
|
|
**/
|
|
/**
|
|
* \defgroup internal_p2p_blocking Blocking Communication
|
|
* \ingroup internal_p2p_main
|
|
*
|
|
* Internals about blocking Point-to-Point Communication.
|
|
**/
|
|
/**
|
|
* \defgroup internal_p2p_synch Synchronous Communication
|
|
* \ingroup internal_p2p_blocking
|
|
*
|
|
* Internals about blocking synchronous Communication.
|
|
*
|
|
* \image html synchronous_communication_1.png
|
|
**/
|
|
/**
|
|
* \defgroup internal_p2p_buffered Buffered Communication
|
|
* \ingroup internal_p2p_blocking
|
|
*
|
|
* Internals about blocking buffered Communication.
|
|
*
|
|
* \image html buffered_communication_1.png
|
|
**/
|
|
/**
|
|
* \defgroup internal_p2p_bmalloc Buffer-Management
|
|
* \ingroup internal_p2p_buffered
|
|
*
|
|
* This section shows how the buffer used for buffered communication is managed.
|
|
**/
|
|
/**
|
|
* \defgroup internal_p2p_imm Non-Blocking Communication
|
|
* \ingroup internal_p2p_main
|
|
*
|
|
* Internals about non-blocking communication.
|
|
*
|
|
* The SPUs are very limited in usage, e.g. only one thread per SPU is supported,
|
|
* and so it is hard to make communication non-blocking. In fact only synchronous
|
|
* send and receive provide possibilities for non-blocking communication. Because
|
|
* we think that the advantages of a non-blocking receive aren't worth the effort,
|
|
* only non-blocking send is implemented at the moment. The picture below illustrates
|
|
* a non-blocking synchronous communication call.
|
|
*
|
|
* \image html isyncronous_communication_1.png
|
|
**/
|
|
/**
|
|
* \defgroup internal_collective Collective Communication
|
|
* \ingroup internal_main
|
|
*
|
|
* Internals about Collective Communication
|
|
*
|
|
* Currently there are only two operations implemented.
|
|
*
|
|
* \section MOC_Bcast
|
|
*
|
|
* The root node sends normal messages using the reserved tag MOC_BCAST_TAG, which
|
|
* is received by all other nodes.
|
|
*
|
|
* \section MOC_Barrier
|
|
*
|
|
* All but the process with the highest rank send a special-message (special-flag set)
|
|
* to the latter process. This process then sends another special-message back to
|
|
* the others. After that the function returns on all calling processes.
|
|
*/
|
|
|
|
|
|
|
|
#endif /*MOC_DOXYGEN_MAIN_H_*/
|