graph - 2022.2 English

AI Engine Kernel and Graph Programming Guide (UG1079)

Document ID
UG1079
Release Date
2022-10-19
Version
2022.2 English

This is the main graph abstraction exported by the ADF tools. All user-defined graphs should be inherited from class graph.

Scope

All instances of those user-defined graph types that form part of a user design must be declared in global scope, but can be declared under any name space.

Member Functions

virtual return_code init() ;

This method loads and initializes a precompiled graph object onto the AI Engine array using a predetermined set of processor tiles. Currently, no relocation is supported. All existing information in the program memory, data memory, and stream switches belonging to the tiles being loaded is replaced. The loaded processors are left in a disabled state.

virtual return_code run();
virtual return_code run(unsigned int num_iterations);

This method enables the processors associated with a graph to start execution from the beginning of their respective main programs. Without any arguments, the graph will run forever. The API with arguments can set the number of iterations for each run differently. This is a non-blocking operation on the PS application.

virtual return_code end();
virtual return_code end(unsigned int cycle_timeout);

The end method is used to wait for the termination of the graph. A graph is considered to be terminated when all its active processors exit their main thread and disable themselves. This is a blocking operation for the PS application. This method also cleans up the state of the graph such as forcing the release of all locks and cleaning up the stream switch configurations used in the graph. The end method with cycle timeout terminates and cleans up the graph when the timeout expires rather than waiting for any graph related event. Attempting to run the graph after end without re-initializing it can give unpredictable results.

virtual return_code wait();
virtual return_code wait(unsigned int cycle_timeout);

virtual return_code resume();

The wait method is used to pause the graph execution temporarily without cleaning up its state so that it can be restarted with a run or resume method. The wait method without arguments is useful when waiting for a previous run with a fixed number of iterations to finish. This can be followed by another run with a new set of iterations. The wait method with cycle timeout pauses the graph execution when the timeout expires counted from a previous run or resume call. This should only be followed by a resume to let the graph to continue to execute. Attempting to run after a wait with cycle timeout call can lead to unpredictable results because the graph can be paused in an unpredictable state and the run can restart the processors from the beginning of their main programs.

virtual return_code update(input_port& pName, <type> value);

virtual return_code update(input_port& pName, const <type>* value, size_t size);

These methods are various forms of run-time parameter update APIs that can be used to update scalar or array run-time parameter ports. The port name is a fully qualified path name such as graph1.graph2.port or graph1.graph2.kernel.port. The <type> can be one of int8, int16, int32, int64, uint8, uint16, uint32, uint64, cint16, cint32, float, cfloat. For array run-time parameter updates, a size argument specifies the number of elements in the array to be updated. This size must match the RTP array size defined in the graph, meaning that the full RTP array must be updated at one time.

virtual return_code read(input_port& pName, <type>& value);

virtual return_code read(input_port& pName, <type>* value, size_t size);

These methods are various forms of run-time parameter read APIs that can be used to read scalar or array run-time parameter ports. The port name is a fully qualified path name such as graph1.graph2.portor graph1.graph2.kernel.port. The <type> can be one of int8, int16, int32, int64, uint8, uint16, uint32, uint64, cint16, cint32, float, cfloat. For array run-time parameter reads, a size argument specifies the number of elements in the array to be read.