00001 #ifndef MOC_INTERNAL_DOXYGEN_MAIN_H_ 00002 #define MOC_INTERNAL_DOXYGEN_MAIN_H_ 00003 00004 00005 00006 /** 00007 * \defgroup internal_main Developer Documentation 00008 * 00009 * This section deals with the internal design and functionality. For correct 00010 * understanding knowledge about the functionality of the Cell Broadband Engine 00011 * is needed. So you should read the official CBE documentation before you 00012 * continue. 00013 * 00014 * \note Because we had only access to a playstation, we cannot guarantee correct 00015 * execution on another CBE-machine than a playstation 3. 00016 **/ 00017 /** 00018 * \defgroup internal_core Implementation-Core 00019 * \ingroup internal_main 00020 **/ 00021 /** 00022 * \defgroup internal_am Address-Macros 00023 * \ingroup internal_core 00024 * 00025 * Predefined Macros for calculating Addresses of Message-Queue and Status-Array. 00026 **/ 00027 /** 00028 * \defgroup internal_tm Test-Macros 00029 * \ingroup internal_core 00030 * 00031 * Predefined Macros for testing the validity of parameters. 00032 **/ 00033 /** 00034 * \defgroup internal_env Environmental Management 00035 * \ingroup internal_main 00036 * 00037 * Internals about Startup & Shutdown and Error-Handling 00038 **/ 00039 /** 00040 * \defgroup internal_init Startup & Shutdown 00041 * \ingroup internal_env 00042 * 00043 * Internals about the startup of the execution-environment and 00044 * SPU-Thread-Management. 00045 * 00046 * \section iinit_start Startup 00047 * 00048 * The PPU-Process creates for every SPU-thread an own thread using the 00049 * pthread-library (see \ref internal_spu_thread). The rank of each prozess, 00050 * the overall process count, the sizes of message-queue and buffer-space 00051 * and the effective base address of the buffer is send to each SPU-thread via 00052 * mailbox-messages. The SPU-threads then send the memory-addresses of their 00053 * message-queues and status-arrays back to the PPU-process which writes this 00054 * data into the prozess-list. After all SPU-Threads have reported back to the 00055 * PPU-process the effective address of the PPU's process-list ist distributed 00056 * among the SPU-processes which then copy the process-list via DMA in their 00057 * local storages. 00058 * 00059 * \section iinit_shut Shutdown 00060 * 00061 * \subsection iinit_shut_ppu PPU 00062 * 00063 * The PPU-process waits till all SPU-threads have signalled that they are also 00064 * executing the finalize-function. After that a signal is send back to each 00065 * SPU-Thread that they can now stop execution. Then local ressources are freed 00066 * and the finalize-function returns. 00067 * 00068 * \subsection iinit_shut_spu SPU 00069 * 00070 * A mailbox-message is send to the PPU to signal that the SPU-process is now 00071 * executing the finalize-function. After that the SPU-process is waiting till 00072 * a mailbox-message from the PPU-process is received. Then local ressources are 00073 * freed and the finalize-function returns. 00074 * 00075 **/ 00076 /** 00077 * \defgroup internal_spu_thread SPU-Thread Management 00078 * \ingroup internal_init 00079 * 00080 * This section deals about the creation and management of SPU-threads. 00081 **/ 00082 /** 00083 * \defgroup internal_error Error-Handling 00084 * \ingroup internal_env 00085 **/ 00086 /** 00087 * \defgroup internal_timer Timers and Synchronization 00088 * \ingroup internal_env 00089 * 00090 * Internals about Time. 00091 * 00092 * On the PPU "gettimeofday()" from time.h is used, because it is the only function 00093 * which seems to work ("clock()" from time.h always returns 0). 00094 * 00095 * On the SPU there are two implementations. One uses also "gettimeofday()" and the 00096 * other uses the spu-timer-library. The reason for this lies in the fact, that the 00097 * spu-timer-library was marked as prototype in Cell SDK 3.0 and the future development 00098 * of this library was uncertain. Cell SDK 3.1 has integrated the spu-timer-library in 00099 * the main-library and so the gettimeofday-implementation is now obsolete. 00100 * 00101 * \note The timebase-constant which is needed to calculate time is hardcoded, because 00102 * there was no according function for retrieving this value in Cell SDK 3.0 and we had 00103 * only access to a playstation 3. Now Cell SDK 3.1 provides a function for retrieving 00104 * the timebase value, but we didn't use it to provide backwards-compatibility. So if 00105 * you plan to use MOC on another platform than playstation 3 keep in mind to check if 00106 * the timebase-value is correct. 00107 * 00108 **/ 00109 00110 /** 00111 * \defgroup internal_comm Groups, Context and Communicators 00112 * \ingroup internal_main 00113 * 00114 * At the moment user-defined groups and communicators are not implemented and maybe never 00115 * will be. 00116 * At the moment user-defined groups and communicators are not implemented and maybe never 00117 * will be. Nevertheless user-defined groups and communicators have been taken into 00118 * consideration while making the software-design (e.g. reserved field for communicator 00119 * in message-envelope). So it should be not too hard to implement groups and communicators. 00120 * However a lot of things concerning communicators are hardcoded (e.g. parameter checks). 00121 * 00122 * To save memory only one byte is used to encode the communicator. So if one 00123 * day user-defined communicators are implemented there are only 256 possible 00124 * communicators. 00125 **/ 00126 00127 00128 /** 00129 * \defgroup internal_p2p_main Point-to-Point Communication 00130 * \ingroup internal_main 00131 * 00132 * Internals about Point-to-Point Communication. 00133 **/ 00134 /** 00135 * \defgroup internal_p2p_dma DMA-Helper Functions 00136 * \ingroup internal_p2p_main 00137 * 00138 * Functions wrapping DMA-Transfers. 00139 * 00140 * The Cell Broadband Engine uses Direct Memory Access (DMA) for communication. Therefore 00141 * data of a MOC-message is transfered using DMA operations. Because programming DMA is 00142 * rather complex, some functions are provided to hide this complexity. One DMA-call can 00143 * only tranfer a maximum of 16KByte of data and the data-size has to be a multiple of 00144 * 16 byte. The provided functions split the data into multiple DMA-calls if needed. If 00145 * the data-size requires it, an intermediate buffer is used into which a separate 00146 * DMA-Call transfers 16 byte containing the piece of data not fitting into the 16-byte 00147 * scheme. Then only the needed bytes are copied into the receive-buffer. But the latter 00148 * only works for a get-operation. 00149 * 00150 * The internal DMA-functions are also made publicly available via wrapping-function 00151 * (see chapter \ref dma_access) which provide parameter checks. 00152 **/ 00153 /** 00154 * \defgroup internal_p2p_blocking Blocking Communication 00155 * \ingroup internal_p2p_main 00156 * 00157 * Internals about blocking Point-to-Point Communication. 00158 **/ 00159 /** 00160 * \defgroup internal_p2p_synch Synchronous Communication 00161 * \ingroup internal_p2p_blocking 00162 * 00163 * Internals about blocking synchronous Communication. 00164 * 00165 * \image html synchronous_communication_1.png 00166 **/ 00167 /** 00168 * \defgroup internal_p2p_buffered Buffered Communication 00169 * \ingroup internal_p2p_blocking 00170 * 00171 * Internals about blocking buffered Communication. 00172 * 00173 * \image html buffered_communication_1.png 00174 **/ 00175 /** 00176 * \defgroup internal_p2p_bmalloc Buffer-Management 00177 * \ingroup internal_p2p_buffered 00178 * 00179 * This section shows how the buffer used for buffered communication is managed. 00180 **/ 00181 /** 00182 * \defgroup internal_p2p_imm Non-Blocking Communication 00183 * \ingroup internal_p2p_main 00184 * 00185 * Internals about non-blocking communication. 00186 * 00187 * The SPUs are very limited in usage, e.g. only one thread per SPU is supported, 00188 * and so it is hard to make communication non-blocking. In fact only synchronous 00189 * send and receive provide possibilities for non-blocking communication. Because 00190 * we think that the advantages of a non-blocking receive aren't worth the effort, 00191 * only non-blocking send is implemented at the moment. The picture below illustrates 00192 * a non-blocking synchronous communication call. 00193 * 00194 * \image html isyncronous_communication_1.png 00195 **/ 00196 /** 00197 * \defgroup internal_collective Collective Communication 00198 * \ingroup internal_main 00199 * 00200 * Internals about Collective Communication 00201 * 00202 * Currently there are only two operations implemented. 00203 * 00204 * \section MOC_Bcast 00205 * 00206 * The root node sends normal messages using the reserved tag MOC_BCAST_TAG, which 00207 * is received by all other nodes. 00208 * 00209 * \section MOC_Barrier 00210 * 00211 * All but the process with the highest rank send a special-message (special-flag set) 00212 * to the latter process. This process then sends another special-message back to 00213 * the others. After that the function returns on all calling processes. 00214 */ 00215 00216 00217 00218 #endif /*MOC_DOXYGEN_MAIN_H_*/
1.5.6