#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_*/