AYUDAME User Manual
Contents
1. un pause and 1 for on x AYU PAUSEONTASK pause request task id is given as third parameter fourth parameter is O for off un pause and 1 for on AYU PAUSEONFUNCTION pause request function id is given as third parameter fourth parameter is O for off un pause and 1 for on x AYUSTEP run until next pause condition is reached x AYU BREAKPOINT set breakpoint i e don t assign new tasks third parameter is O for off un pause and 1 for on SOURCE enum ayu_request_t AYU REQUEST NULL 0 AYUNOREQUEST 1 AYU PAUSEONEVENT 2 AYU PAUSEONTASK 3 AYU PAUSEONFUNCTION 4 AYUSTEP 5 AYU BREAKPOINT 6 AYU BLOCKTASK 7 AYU PRIORITISETASK 8 AYU SETNUMTHREADS 9 3 xxx x x x tx Ayudame types h ayu runtime t NAME ayu runtime t enum of runtime DESCRIPTION ids AYUDAME A 1 The header Ayudame h 15 ayu event t consists of the following ids x AYURT UNKNOWN no or unknown runtime used for initialisation x AYURT CPPSS CPPSS runtime x AYU_RT_SMPSS SmpSs runtime x AYURT OMPSS OmpSs runtime AYURTGOMP GNU OpenMP runtime AYU_RT CILK CILK runtime SOURCE enum ayu runtime t AYURTUNKNOWN 0 AYU RT CPPSS 1 AYU RT SMPSS 2 AYU RT_OMPSS 3 AYURTGOMP 4 AYU_RT_CILK 5 3 xxxx extern C2. xx f AYUDAME AYU event NAME AYU event callback for the Ss runtime SYNOPSIS AYU event event taskId pointer DESCRIPTION this function is called from the Ss runtime to communicate with the AYUDAME package Events of type ayu event t the task ID of the calling task and a pointer to arbitrary data can be sent AYU event will connect to a client via tcp sockets and pass on the information PARAMETERS ayu event t event type of event const int64 t taskld taskId from which the event is sent void p pointer to further data RETURN VALUE void SOURCE void AYU event ayu event t event const int64_t taskId void xp attribute weak xxx xxx x AYUDAME AY U getBreakpoint NAME AYU getBreakpoint return AYU breakpoint SYNOPSIS breakpoint AYU getBreakpoint DESCRIPTION Locks the global variable AYU breakpoint returns its value and unlocks it PARAMETERS void RETURN VALUE 1 if AYU breakpoint is set 0 if AYU breakpoint is not set SOURCE XK X XK XX XX X X int AYU getBreakpoint void _attribute__ weak Steffen Brinkmann HLRS Universitat Stuttgart 16 A Sources ee o fx AYUDAME A YU_isBlocked NAME AYU isBlocked return true if task is blocked SYNOPSIS if AYU isBlocked taskId do something DESCRIPTION Locks the global variable AYU blockedTask using the brea
3. used for initialisation etc x AYU PREINIT raised in css preinit x AYU INIT raised in css init AYU FINISH raised in css finish AYU REGISTERFUNCTION raised in css registerTask with the function name as third parameter x AYUADDTASK raised in css addTask after a task has been generated with the task pointer as second parameter x AYU_ADDHIDDENTASK raised in HiddenWork addPendingHiddenTask after a hidden task has been generated with the task pointer as second parameter x AYUADDWAITONTASK raised in css waitOn to signal that a waiton directive has been encountered Note that the taskld is allways 0 This event is followed by one or more AYUADDDEPENDENCY events x AYUADDDEPENDENCY raised in ParameterConversion convert with task pointer as second parameter and TrackableObject containing information about the lastWriter and the dependency address as third parameter x AYUADDTASKTOQUEUE raised in TaskQueues addGlobalTask TaskQueues addRRToNode TaskQueues addTask TaskQueues addTaskWithLocality TaskQueues addAffineTask AYU_ PRESELECTTASK raised in WorkerEngine TaskExecutor tryToRunTaskOrWait before a task is assigned x AYU PRERUNTASK raised in WorkerEngine TaskExecutor tryToRunTaskOrWait after a task is assigned x AYU RUNTASK raised in WorkerEngine TaskExecutor tryToRunTaskOrWait just before a task is executed x AYU PO
4. AYU ADDDEPENDENCY the task id of the task suffer Figure 1 minimalistic example graph ing the dependency and the additional data This piece of code will result in a dependency graph shown in figure 1 3 Events and requests Genrally speaking the interactions of AYUDAME with the world can be divided into two types events and requests Events represent the information flow from the application and the runtime environment to the outside world e g a file a logging tool or a debugger while requests are passed from the outside world to the application The events are handled runtime independant by the AYU event callback function Requests on the other hand are highly runtime dependant The set of available request varies strongly from one runtime to the other 3 1 Events Events are communicated by the use of the AYU event O callback function It is declared in Ayudame h as follows void AYU event ayu event t event const int64_t taskld void xp attribute weak This declaration permits to leave the header included even if the library libayudame so is not linked or preloaded In that case the callback name AYU event is equivalent to false Therefore it is recommended to call this function within a conditional clause Steffen Brinkmann HLRS Universitat Stuttgart 8 3 Events and requests if AYU event AYU event AYU ADDTASK 1 Ayu data The parameters passed to AYU event co
5. be 0 if unknown It is necessary that both tasks the dependant and the task it depends on are already created when defining a dependency uintptr_t Ayu_data 3 0 0 0 Ayu_data 0 otherTask gt getld Ayu_data 1 mem_addr_of_dependecy Ayu_data 2 original mem addr of dependecy if AYU event AYU event AYU ADDDEPENDENCY task gt getId void Ayu data AYU_ADDTASKTOQUEUE Queue task notification recommended for graph display event Id 8 When a task does not depend on any other tasks it can be marked as queued The task must exist prior to this event Additionally the Id of the thread which queued the task can be passed intptr_t th id getThreadlId if AYU_event Steffen Brinkmann HLRS Universitat Stuttgart 10 3 Events and requests AYU event AYU ADDTASKTOQUEUE task gt getId amp thread id AYU_PRESELECTTASK Task is about to be dequeued do not use debugging event event Id 9 This event notifies that the runtime is checking the queue s for a task to run As this event will usually occur many times it is completely ignored i e not even logged AYU_PRERUNTASK Prerun task notification recommended for graph display event Id 10 When a task is scheduled for execution i e an execution thread has dequeued the task it can be marked as about to run This event is recommended to be emitted before pausing the execution when stepping through the d
6. which type of event is being communicated It is an integer of type enum ayu event t declared in the header Ayudame h Steffen Brinkmann HLRS Universitat Stuttgart o Jo wa e N ja 6 2 Quick start guides enum ayu event t AYU EVENT NULL O AYU PREINIT 1 AYU INIT 2 AYU FINISH 3 AYU REGISTERFUNCTION 4 AYU ADDTASK 5 AYU ADDHIDDENTASK 6 AYU ADDDEPENDENCY Ts AYU_ADDTASKTOQUEUE 8 AYU_PRESELECTTASK 9 AYU_PRERUNTASK 10 AYU_RUNTASK 11 AYU_POSTRUNTASK 12 AYU_RUNTASKFAILED 13 AYU_REMOVETASK 14 AYU_WAITON 15 AYU_BARRIER 16 AYU ADDWAITONTASK 17 ja Not all of these events are necessary A minimalistic seguence of events could look like this include lt Ayudame h gt ayu runtime t ayu rt AYU RT OMPSS for OMPSs runtime AYU event AYU PREINIT 0 void amp ayu rt int64 t AYU data1 2 function id 1 task is critical 1 AYU event AYU ADDTASK 1 AYU datal int64 t AYU data2 2 function id 2 task is critical 2 AYU event AYU ADDTASK 2 AYU data2 uintptr t Ayu data3 3 1 mem address original mem address AYU event AYU_ADDDEPENDENCY 2 AYU data3 Please note that Ayudame h has to be in the include path and that for easier readability the checks of the form if AYU event were omitted Thus this code will only work if libayudame so is preloaded Let us step through the example above In line 1 the header Ayudame h is included Thi
7. AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY DI RECT INDIRECT INCIDENTAL SPECIAL EXEMPLARY OR CONSEQUENTIAL DAMAGES INCLUDING BUT NOT LIMITED TO PROCUREMENT OF SUBSTITUTE GOODS OR SER VICES LOSS OF USE DATA OR PROFITS OR BUSINESS INTERRUPTION HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY WHETHER IN CONTRACT STRICT LIA BILITY OR TORT INCLUDING NEGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE AYUDAME Contents 1 Introduction 2 Quick start guides 2 1 For application programmers sa os o aoea a 2 2 For runtime Programmers psi sa Pew Ea a RG a ee g 3 Events and requests Soli TEVOMES so dom ali ea K eR AE RE T O EE AD Pa Se a To4 32 RESTS ss 3 ime x E ai E a A Hi ee RR a n lt 4 The callback functions 4 1 The AVU evont callback function lt lt 646 4 cassem eda waaa A Sources A 1 The header Ayudame h oa cno k KK KK e 1 Introduction AYUDAME is a generic library for communicating events occuring while running a StarSs task parallel application to the outside The present version will set up a tcp ip socket server wait for a client to connect and send messages to it A client designed to work with AYUDAME is TEMANEJO 2 Quick start guides 2 1 For application programmers In order to use AYUDAME you will have to compile the lib
8. AYUDAME communication for StarSs Steffen Brinkmann HLRS Universitat Stuttgart Disclaimer The information contained in this manual is not garanteed to be complete at this stage It is subject to changes without further notice Please send comments corrections and additional text to brinkmann hlrs de Steffen Brinkmann AYUDAME communication for StarSs manual for the communica tion library AYUDAME Revision history Version Date Remarks Author 1 0 6 Sep 2012 initial version Steffen Brinkmann 2009 2012 HLRS University of Stuttgart all rights reserved Redistribution and use in source SGML DocBook and compiled forms SGML HTML PDF PostScript RTF and so forth with or without modification are permitted provided that the following conditions are met Redistributions of source code SGML DocBook must retain the above copyright notice this list of conditions and the following disclaimer as the first lines of this file unmodified Redistributions in compiled form transformed to other DTDs converted to PDF PostScript RTF and other formats must reproduce the above copyright notice this list of conditions and the following disclaimer in the documentation and or other materials provided with the distribution THIS DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDER AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY
9. DAME library will not be threads PARAMETERS unsigned int n threads RETURN VALUE void XXX XX XX X XX void AYU setNumThreads unsigned i xxx f AYUDAME AYU registerTask NAME AYU registerTask SYNOPSIS DESCRIPTION PARAMETERS RETURN VALUE XK XK XX KF XX KH SOURCE the runtime be implemented in the StarSs runtime If it is not implemented the client of the able to change the number of nt n threads __attribute__ weak obsolete kept for backward compatibility void AYU_registerTask void __attribute__ weak toe ifndef AYU MASTER TASKID define AYU MASTER TASKID 0 jendif jendif AYUDAMEH Steffen Brinkmann HLRS Universit t Stuttgart
10. STRUNTASK raised in WorkerEngine TaskExecutor try ToRunTaskOrWait after runTask AYURUNTASKFAILED raised in WorkerEngine TaskExecutor tryToRunTaskOrWait if Exception is raised by runTask AYUREMOVETASK raised in TaskGraph removeNodeAndEngueueFreeSuccessors and Hidden Work removePendingHiddenTask x AYUWAITON raised in css waitOn AYU BARRIER raised in css barrier SOURCE Y TE E E E ETS AE EEE ERE ERES ZH KBE E TB AE RAE E EEE TK BE EB e E E Steffen Brinkmann HLRS Universit t Stuttgart 14 A Sources enum ayu event t AYU EVENT NULL 0 AYU PREINIT 1 AYU INIT 2 AYU FINISH 3 AYU REGISTERFUNCTION 4 AYU ADDTASK 5 AYU ADDHIDDENTASK 6 AYU ADDDEPENDENCY 7 AYU_ADDTASKTOQUEUE 8 AYU PRESELECTTASK 9 AYU PRERUNTASK 10 AYU RUNTASK 11 AYU POSTRUNTASK 12 AYU RUNTASKFAILED 13 AYU REMOVETASK 14 AYU WAITON 15 AYU BARRIER 16 AYU ADDWAITONTASK 17 xxx x x x tx Ayudame types h ayu reguest t NAME ayu reguest t enum of requests DESCRIPTION ayu event t consists of the following events x AYU REQUEST NULL no request used for initialisation x AYUNOREQUEST explicit no request AYUPAUSEONEVENT pause request event upon which the program should pause is given as third parameter fourth parameter is O for off
11. TOSOCKET 1 endif ifndef AYU WRITETOSTDOUT define AYUWRITETOSTDOUT 0 endif ifndef AYU MASTER TASKID define AYU_MASTER TASKID O endif define AYU VERSION 0 9 20121030 includes and defines for time measurement with rdtsc if defined linux include lt endian h gt telif defined FreeBSD defined NetBSD include lt sys endian h gt elif defined OpenBSD _ include lt sys types h gt define bel6toh x betoh16 x define be32toh x betoh32 x define be64toh x betoh64 x else A error ERROR System not recognised endif ifndef htobe64 include lt byteswap h gt if BYTEORDER LITTLE ENDIAN define htobe64 x _bswap_64 x define be64toh x _ _bswap_64 x else JE define htobe64 x x define be64toh x x endif endif AYUDAME A 1 The header Ayudame h 13 x ifndef htobe64 x define htobe64 x x htonl x gt gt 32 define be64toh x ntohl x gt gt 32 endif ji uint64 t htonl x lt lt 32 i uint64 t ntohl x lt lt 32 const size_t AYU buf size 8 size of message buffer extern unsigned long AYU n threads current number of threads extern unsigned long AYU max threads maximum number of threads x x x tx Ayudame types h ayu event t NAME ayu event t enum of events DESCRIPTION ayu event t consists of the following events x AYU EVENT NULL no event
12. ependency graph The number of nodes marked this way is at any time equal or less the number of execution threads Additionally the Id of the thread which runs the task can be passed intptr_t th id getThreadlId if AYU event AYU event AYU PRERUNTASK task gt getId amp thread id AYU_RUNTASK Run task notification optional for time measurement event Id 11 Just before the task is executed a run task event can be emitted This event is intended for time measurement Between this event and the actual execution of the task there should be as less code as possible to ensure exact time stamps if AYU event AYU event AYURUNTASK task gt getId NULL AYU POSTRUNTASK Task execution finished optional for logging event Id 12 if AYU event AYU event AYU POSTRUNTASK task gt getId NULL 1 AYU RUNTASKFAILED Task execution failed optional for failed tasks event Id 18 if AYU event AYU event AYU RUNTASKFAILED task gt getId NULL AYUDAME 3 2 Requests 11 AYU_REMOVETASK Task execution finished recommended for graph display and time measurement event Id 14 When a task has finished this event should be emitted if AYU event AYU event AYUREMOVETASK taskNode gt getId NULL 1 AYU_WAITON Wait on event do not use development in progress event Id 15 For treating wait on events Do not use This
13. is under development AYU_BARRIER Barrier notification recommended for graph display with horizontal barrier lines event Id 16 Notifies of a barrier if AYU event AYU event AYU BARRIER O NULL AYU ADDWAITONTASK Wait on event do not use development in progress event Id 17 For treating wait on events Do not use This is under development 3 2 Requests tbd 4 The callback functions These functions are declared in the header file Ayudame h as weak references This way it is possible to check whether an implementation of the functions exist during runtime This enables an application to run with or without the preloaded AYUDAME library without recompiling see code example in sec 2 2 4 1 The AYU event callback function tbd A Sources A 1 The header Ayudame h Steffen Brinkmann HLRS Universitat Stuttgart 12 A Sources Listing 1 The main header of the Ayudame package H x AYUDAME Ayudame types h NAME Ayudame types h header file for the event and request types of the AYUDAME package DESCRIPTION This header file declares the following elements enum ayu event t enum ayu request t sek kkk ok ifndef AYUDAMEH define AYUDAMEH include lt stdint h gt include lt unistd h gt define REENTRANT defined by default by gcc ifndef AYU VERBOSE define AYU VERBOSE 0 endif ifndef AYUCONNECTTOSOCKET define AYUCONNECT
14. kpoint mutex lock compares to it taskId given as parameter and returns result PARAMETERS const int taskld RETURN VALUE true if task is blocked false if task is not blocked SOURCE XK XA XA X X XX X X X XX XX X bool AYU_isBlocked const int taskId __attribute__ weak gt kkk k AYUDAME AYU getPriorityLevel NAME AYU getPriorityLevel returns priority of task SYNOPSIS AYU getPriorityLevel taskId DESCRIPTION returns the priority of a task identified by its id If the priority has not been changed in Ayudame it returns 1 PARAMETERS int taskId RETURN VALUE 1 if priority has not changed 0 low no priority positive integer priority level SOURCE int AYU getPriorityLevel int taskId _attribute__ weak 8 xxxxx xx fx AYUDAME AYU getNumThreads NAME AYU_getNumThreads returns number of threads set by AYUDAME SYNOPSIS runtime setNumThreads AYU getNumThreads DESCRIPTION returns the number of threads as set by ayudame PARAMETERS void RETURN VALUE unsigned int number of threads SOURCE unsigned int AYU getNumThreads attribute weak eee xxx fx AYUDAME AYU setNumThreads NAME AYUDAME A 1 The header Ayudame h 17 AYU setNumThreads sets number of threads in SYNOPSIS AYU setNumThreads n threads DESCRIPTION This callback function can AYU
15. n name display event Id 4 This event registers the function name and the function Id of a taskified function if AYU event AYU event AYU REGISTERFUNCTION 0 void name AYUDAME 3 1 Events 9 AYU ADDTASK Create task mandatory for graph display event Id 5 A task is represented by a node in the dependency graph When a task is created a notification should be emitted containing the task Id and the function Id of the function executed by the task It is recommended to either make sure that every function is registered before the first task for this function is created or not to register function names at all The additional data must be a pointer to an integer denoting whether the task is critical high priority 1 or not 0 int64_t AYU data 2 functionId int task gt isCritical if AYU event AYU event AYU ADDTASK task gt getId AYU data AYU ADDHIDDENTASK Add hidden task do not use development in progress event Id 6 Do not use This is under development AYU_ADDDEPENDENCY Define dependency mandatory for graph display event Id 7 A dependency is represented by an edge in the dependency graph When a dependency is created the application should notify that passing along the task Id of the predecessor the memory address of the variable or array causing the dependency and the original memory address of the variable in case of renaming The address can
16. nsist in an event type a task id and additional data the content of which depends on the event type Three events are mandatory for building the graph AYU PREINIT AYU ADDTASK and AYU ADDDEPENDENCY Find a comprehensive list of events in following AYU EVENT NULL dummy event optional for initialisation of event variables event Id O Does not represent an event AYU PREINIT Pre initialisation mandatory for logging event Id 1 Should latest be emmited just before the parallel execution starts Must be the first event to be emitted The additional data must be a pointer to an integer denoting which runtime is in use CppSs 1 SMPSs 2 OMPSs 3 GOMP 4 or CILK ayu_runtime_t ayu rt AYURT SMPSS if AYU event AYU event AYU PREINIT 0 voidx amp ayu_rt AYU INIT Initialisation optional for logging event Id 2 Should be sent just after AYU PREINIT The execution will pause if pausing is available for the specified runtime until a reguest is received in order to proceed to execute the parallel part of the application if AYU event AYU event AYUINIT 0 NULL AYU FINISH Finalisation recommended for closing socket connection event Id 3 This event notifies that the parallel part of the application has finished The socket connection will be closed if AYU event AYU event AYU FINISH 0 NULL AYU_REGISTERFUNCTION Register taskified functions optional for functio
17. rary This is done with make amp amp make install This compiles the library and creates a link to it in the directory jayudame directory lib If you encounter problems please read the README file in the AYUDAME directory and the comments in the Makefile To execute an application with AYUDAME enabled run it as follows LD_PRELOAD lt ayudame_directory gt lib libayudame so application lt parameters gt The application will run until the start of the task parallel part It will then pause and wait for a client e g TEMANEJO to connect Then it will wait until a step request is issued by the client which is done by pressing the Play button in TEMANEJO 2 2 For runtime programmers In order to connect to programmes like TEMANEJO the StarSs runtime has to call the AYU_event callback function This function will send the appropriate message depending on the input parameters Generally a call to AYU_event looks like this if USE_AYUDAME if AYU_event AYU_event lt event_id gt lt task_id gt lt void_data_pointer gt endif The statement is enclosed in a preprocessor directive in order to be able to switch the AYUDAME support of when compiling the runtime It is suggested to do so and to set USE_AYUDAME while configuring the runtime when using autotools Furthermore the statement is only executed if an implementation of AYU_event is found at execution time For details see sec 4 The event_id indicates
18. s is necessary for providing the declarations of the callback functions and the event enum type In line 2 a variable of type ayu runtime t is declared and defined to hold an identifier for the runtime These identifiers are declared in Ayudame h see Appendix In line 3 AYU event is called for the first time with the event id AYU PREINIT When this event is sent AYUDAME will set up the socket server and wait for a client to connect The port of the socket connection is set by the environment variable AYU PORT If this AYUDAME variable is not defined the port is set to port pid 1000 5000 i e for a process id of 23674 the port will result in 5674 In line 4 the additional data is set up for adding a task to the dependency graph It consists of the function id of the task and an integer indicating whether the task is to be executed with priority 1 or not 0 In the next line 4 the creation of the task is communicated to AYUDAME The function param eters are the type of the event AYU ADDTASK the task id 1 and the additional data We repeat the last to steps for another task with the task id 2 Finally we define a dependency between these tasks in lines 8 and 9 Here the additional data con sists of the task id of the task which causes the dependency the memory address of the dependency and in the case of renaming see SMPSs manual the original memory address The call to AYU event contains the type of event
Download Pdf Manuals
Related Search