stm.h File Reference

Detailed Description

STM Runtime.

Overview: STM is a co-operative, non-preemptive, static scheduling framework for real-time systems. The STM runtime is a library that executes a schedule produced offline by the STM compiler, enforcing data dependency ordering and control flow ordering across engines on a Tegra SoC.

STM Clients: Every STM client corresponds to an OS process. All STM clients mentioned to the STM compiler must be launched before any STM client will begin scheduling runnables.

STM Master: Alongside STM clients, the STM master executable needs to be launched and passed a .stm file generated by the STM compiler. STM clients will block at the call to stmClientInit() until the STM master process has been launched.

Definition in file stm.h.

Go to the source code of this file.

Classes
struct	stmRunnableInfo_t
	Information which can be queried by CPU runnables using stmGetRuntimeInfo() More...

Typedefs
typedef void(*	stmCudaSubmitter_t) (void *userdata, cudaStream_t stream)
	Function signature for STM CUDA submitter runnable. More...
typedef void(*	stmCuDlaSubmitter_t) (void *userdata, cudaStream_t cudla)
	Function signature for STM cuDLA submitter runnable. More...
typedef void(*	stmRunnable_t) (void *userdata)
	Function signature for STM CPU runnable. More...
typedef void(*	stmVpuSubmitter_t) (void *userdata, cupvaStream_t vpu)
	Function signature for STM VPU submitter runnable. More...

Functions
STM_API void	stmClientExit (void)
	Cleans up STM client context. No STM APIs can be called after this. More...
STM_API void	stmClientInit (const char *clientName)
	Initialize STM client context. More...
STM_API void	stmClientInitWithDiscriminator (const char *clientName, int32_t discriminator)
	Initialize STM client context with a discriminator. More...
STM_API stmErrorCode_t	stmEnterScheduler (void)
	Yield to STM scheduler, which will schedule all registered runnables in the STM schedule periodically until completion. This function will not return until a runnable calls stmExitScheduler() or the number of epochs specified in the STM master process have completed. More...
STM_API stmErrorCode_t	stmExitScheduler (void)
	Return from stmEnterScheduler(). More...
STM_API stmErrorCode_t	stmGetRuntimeInfo (stmRunnableInfo_t *info)
	Get runtime information about execution. More...
STM_API stmErrorCode_t	stmRegisterCpuRunnable (stmRunnable_t func, const char *const runnableId, void *userdata)
	Registers an stmRunnable_t function with the name provided by the user to the STM compiler. More...
STM_API stmErrorCode_t	stmRegisterCudaResource (const char *resourceName, cudaStream_t stream)
	Registers a CUDA stream resource. More...
STM_API stmErrorCode_t	stmRegisterCudaSubmitter (stmCudaSubmitter_t func, const char *const runnableId, void *userdata)
	Registers an stmCudaSubmitter_t function with the name provided by the user to the STM compiler. More...
STM_API stmErrorCode_t	stmRegisterCuDlaResource (const char *resourceName, cudaStream_t cudla)
	Registers a cuDLA resource. More...
STM_API stmErrorCode_t	stmRegisterCuDlaSubmitter (stmCuDlaSubmitter_t func, const char *const runnableId, void *userdata)
	Registers an stmCudlaSubmitter_t function with the name provided by the user to the STM compiler. More...
STM_API stmErrorCode_t	stmRegisterVpuResource (const char *resourceName, cupvaStream_t vpu)
	Registers a cuPVA resource. More...
STM_API stmErrorCode_t	stmRegisterVpuSubmitter (stmVpuSubmitter_t func, const char *const runnableId, void *userdata)
	Registers an stmVpuSubmitter_t function with the name provided by the user to the STM compiler. More...

---

Class Documentation

stmRunnableInfo_t

struct stmRunnableInfo_t

Class Members
uint32_t	epochIterations
uint16_t	scheduleId

Typedef Documentation

stmCudaSubmitter_t

typedef void(* stmCudaSubmitter_t) (void *userdata, cudaStream_t stream)

Function signature for STM CUDA submitter runnable.

Remarks

stmCudaSubmitter_t functions should contain some CPU work, followed by some number of asynchronous CUDA kernel launches. All kernels launched in submitter must be launched onto cudaStream_t stream. The use of stream 0 (the null stream) is prohibited due to CUDA's implicit synchronization semantics. This function should not internally launch any threads or call any blocking APIs, including cudaMemcpy(), cudaMemset(), cudaFree(), etc..

Parameters

[in]	userdata	Pointer to any data needed by the runnable
[in]	stream	CUDA stream created by application for the kernels

Definition at line 104 of file stm.h.

stmCuDlaSubmitter_t

typedef void(* stmCuDlaSubmitter_t) (void *userdata, cudaStream_t cudla)

Function signature for STM cuDLA submitter runnable.

Remarks

stmCuDlaSubmitter_t functions should contain some CPU work, followed by some number of cuDLA submits. All submits must be launched on the provided cuDLA handle. These functions should not internally launch any threads or call any blocking APIs. STM cuDLA Support is only enabled with the 6.0.2.0 PDK, and will fail at the link stage otherwise.

Parameters

[in]	userdata	Pointer to any data needed by the runnable
[in]	cudla	CUDA stream created by application

Definition at line 186 of file stm.h.

stmRunnable_t

typedef void(* stmRunnable_t) (void *userdata)

Function signature for STM CPU runnable.

Remarks

stmRunnable_t functions should only contain CPU work. They should not call any blocking APIs or internally launch any threads.

Definition at line 91 of file stm.h.

stmVpuSubmitter_t

typedef void(* stmVpuSubmitter_t) (void *userdata, cupvaStream_t vpu)

Function signature for STM VPU submitter runnable.

Remarks

stmVpuSubmitter_t functions should contain some CPU work, followed by some number of VPU submits. All submits must be launched on the provided cuPVA stream. These functions should not internally launch any threads or call any blocking APIs. STM VPU Support is only enabled with the 6.0.0.0 PDK, and will fail at the link stage otherwise.

Parameters

[in]	userdata	Pointer to any data needed by the runnable
[in]	vpu	cuPVA stream created by application

Definition at line 201 of file stm.h.

Function Documentation

stmClientExit()

STM_API void stmClientExit

(

void

)

Cleans up STM client context. No STM APIs can be called after this.

Remarks

This API can only be called once per call to stmClientInit(); doing so multiple times will cause undefined behavior.

stmClientInit()

STM_API void stmClientInit

(

const char *

clientName

)

Initialize STM client context.

Remarks

This API must be called before any other STM APIs. This API will block until the STM master process is started. Client contexts should be cleaned up with stmClientExit() after STM has completed its execution. Same as calling stmClientInitWithDiscriminator() with discriminator = -1

stmClientInitWithDiscriminator()

STM_API void stmClientInitWithDiscriminator	(	const char *	clientName,
		int32_t	discriminator
	)

Initialize STM client context with a discriminator.

Remarks

This API must be called before any other STM APIs. This API will block until the STM master process with this discriminator is started. Client contexts should be cleaned up with stmClientExit() after STM has completed its execution. Client must call at most one of the two: stmClientInit() or stmClientInitWithDiscriminator() All negative values of discriminator are equivalent and the same as calling stmClientInit()

stmEnterScheduler()

STM_API stmErrorCode_t stmEnterScheduler

(

void

)

Yield to STM scheduler, which will schedule all registered runnables in the STM schedule periodically until completion. This function will not return until a runnable calls stmExitScheduler() or the number of epochs specified in the STM master process have completed.

Remarks

All runnables and resources need to be registered prior to entering the schedule. This API will only begin scheduling work after all STM clients have started. This API can only be called once per call to stmClientInit(); doing so multiple times will cause undefined behavior.

Returns

stmErrorCode_t, the completion code of the operation:

• STM_ERROR_TIMEOUT if any fence timed out.
• STM_ERROR_GENERIC if there was another error.
• STM_SUCCESS otherwise.

stmExitScheduler()

STM_API stmErrorCode_t stmExitScheduler

(

void

)

Return from stmEnterScheduler().

Remarks

Called from within a runnable; causes all clients to return from their respective calls to stmEnterScheduler() at the next epoch boundary. Only needs to be called from one STM client; subsequent calls are ignored.

Returns

stmErrorCode_t, the completion code of the operation: -STM_SUCCESS if successful. -STM_ERROR_GENERIC if any client process died or if any APIs in any STM client returned an error code.

stmGetRuntimeInfo()

STM_API stmErrorCode_t stmGetRuntimeInfo

(

stmRunnableInfo_t *

info

)

Get runtime information about execution.

Remarks

Must be called from within a CPU runnable

Parameters

[out]

info

Pointer to stmRunnableInfo_t whose fields will be populated

Returns

stmErrorCode_t, the completion code of the operation:

• STM_ERROR_BAD_PARAMETER if info is NULL.
• STM_ERROR_NOT_FOUND if the current STM thread could not be found.
• STM_ERROR_INVALID_STATE if the requisite information could not be obtained.
• STM_SUCCESS otherwise.

stmRegisterCpuRunnable()

STM_API stmErrorCode_t stmRegisterCpuRunnable	(	stmRunnable_t	func,
		const char *const	runnableId,
		void *	userdata
	)

Registers an stmRunnable_t function with the name provided by the user to the STM compiler.

Parameters

[in]	func	STM CPU runnable function pointer.
[in]	runnableId	Name of CPU runnable provided to the STM compiler.
[in]	userdata	Pointer to any data needed by the runnable.

Returns

stmErrorCode_t, the completion code of the operation:

• STM_ERROR_BAD_PARAMETER if runnableId exceeds STM_FUNC_NAME_MAX.
• STM_ERROR_NOT_INITIALIZED if stmClientInit() has not been called.

stmRegisterCudaResource()

STM_API stmErrorCode_t stmRegisterCudaResource	(	const char *	resourceName,
		cudaStream_t	stream
	)

Registers a CUDA stream resource.

Parameters

[in]	resourceName	Name of resource. Needs to match resource name passed to STM compiler.
[in]	stream	CUDA stream created by application.

Returns

stmErrorCode_t, the completion code of the operation:

• STM_ERROR_BAD_PARAMETER if any of the following occurs:
  • resourceName exceeds STM_RESOURCE_NAME_MAX
  • the number of resources registered exceeds STM_MAX_NUM_RESOURCES
  • stream is the NULL stream or has not been previously created by calling cudaStreamCreate()
  • the same cudaStream_t has already been registered (possibly with a different resourceName)
• STM_ERROR_NOT_INITIALIZED if stmClientInit() has not been called.

stmRegisterCudaSubmitter()

STM_API stmErrorCode_t stmRegisterCudaSubmitter	(	stmCudaSubmitter_t	func,
		const char *const	runnableId,
		void *	userdata
	)

Registers an stmCudaSubmitter_t function with the name provided by the user to the STM compiler.

Parameters

[in]	func	STM CUDA submitter runnable function pointer.
[in]	runnableId	Name of CUDA submitter runnable provided to the STM compiler.
[in]	userdata	Pointer to any data needed by the runnable.

Returns

stmErrorCode_t, the completion code of the operation:

• STM_ERROR_BAD_PARAMETER if runnableId exceeds STM_FUNC_NAME_MAX.
• STM_ERROR_NOT_INITIALIZED if stmClientInit() has not been called.

stmRegisterCuDlaResource()

STM_API stmErrorCode_t stmRegisterCuDlaResource	(	const char *	resourceName,
		cudaStream_t	cudla
	)

Registers a cuDLA resource.

Remarks

STM cuDLA Support is only enabled with the 6.0.2.0 PDK, and will fail at the link stage otherwise.

Parameters

[in]	resourceName	Name of resource. Needs to match resource name passed to STM compiler.
[in]	cudla	The CUDA stream created by the application used for cuDLA task submission

Returns

stmErrorCode_t, the completion code of the operation:

• STM_ERROR_BAD_PARAMETER if any of the following occurs:
  • resourceName exceeds STM_RESOURCE_NAME_MAX
  • the number of resources registered exceeds STM_MAX_NUM_RESOURCES
  • cudla is NULL or has not been previously created by calling cudaStreamCreate()
  • the same CUDA stream has already been registered (possibly with a different resourceName)
• STM_ERROR_NOT_INITIALIZED if stmClientInit() has not been called.

stmRegisterCuDlaSubmitter()

STM_API stmErrorCode_t stmRegisterCuDlaSubmitter	(	stmCuDlaSubmitter_t	func,
		const char *const	runnableId,
		void *	userdata
	)

Registers an stmCudlaSubmitter_t function with the name provided by the user to the STM compiler.

Remarks

STM cuDLA Support is only enabled with the 6.0.2.0 PDK, and will fail at the link stage otherwise.

Parameters

[in]	func	STM cuDLA submitter runnable function pointer.
[in]	runnableId	Name of cuDLA submitter runnable provided to the STM compiler.
[in]	userdata	Pointer to any data needed by the runnable.

Returns

stmErrorCode_t, the completion code of the operation:

• STM_ERROR_BAD_PARAMETER if runnableId exceeds STM_FUNC_NAME_MAX.
• STM_ERROR_NOT_INITIALIZED if stmClientInit() has not been called.

stmRegisterVpuResource()

STM_API stmErrorCode_t stmRegisterVpuResource	(	const char *	resourceName,
		cupvaStream_t	vpu
	)

Registers a cuPVA resource.

Remarks

STM cuPVA Support is only enabled with the 6.0.0.0 PDK, and will fail at the link stage otherwise.

Parameters

[in]	resourceName	Name of resource. Needs to match resource name passed to STM compiler.
[in]	vpu	cuPVA stream created by application.

Returns

stmErrorCode_t, the completion code of the operation:

• STM_ERROR_BAD_PARAMETER if any of the following occurs:
  • resourceName exceeds STM_RESOURCE_NAME_MAX
  • the number of resources registered exceeds STM_MAX_NUM_RESOURCES
  • vpu is NULL or has not been previously created by calling cupvaStreamCreate()
  • the same cuPVA stream has already been registered (possibly with a different resourceName)
• STM_ERROR_NOT_INITIALIZED if stmClientInit() has not been called.

stmRegisterVpuSubmitter()

STM_API stmErrorCode_t stmRegisterVpuSubmitter	(	stmVpuSubmitter_t	func,
		const char *const	runnableId,
		void *	userdata
	)

Registers an stmVpuSubmitter_t function with the name provided by the user to the STM compiler.

Remarks

STM cuPVA Support is only enabled with the 6.0.0.0 PDK, and will fail at the link stage otherwise.

Parameters

[in]	func	STM cuPVA submitter runnable function pointer.
[in]	runnableId	Name of cuPVA submitter runnable provided to the STM compiler.
[in]	userdata	Pointer to any data needed by the runnable.

Returns

stmErrorCode_t, the completion code of the operation:

• STM_ERROR_BAD_PARAMETER if runnableId exceeds STM_FUNC_NAME_MAX.
• STM_ERROR_NOT_INITIALIZED if stmClientInit() has not been called.