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.

Data Structures
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(*	stmCuDlaStandaloneSubmitter_t) (void *userdata, cudlaDevHandle cudla)
	Function signature for STM cuDLA standalone submitter runnable. More...
typedef void(*	stmCuDlaSubmitter_t) (void *userdata, cudaStream_t cudla)
	Function signature for STM cuDLA hybrid submitter runnable. More...
typedef void(*	stmRunnable_t) (void *userdata)
	Function signature for STM CPU runnable. More...
typedef void(*	stmScheduleSwitchCallback_t) (uint16_t startScheduleId, uint16_t hyperepochId, void *userdata)
	Function signature for STM schedule switch callback. More...
typedef void(*	stmVpuSubmitter_t) (void *userdata, cupvaStream_t vpu)
	Function signature for STM VPU submitter runnable. More...
typedef void(*	stmVulkanSubmitter_t) (void *userdata, VkQueue queue)

Functions
STM_API void	stmClientExit (void)
	Cleans up STM client context. No STM APIs can be called after this. More...
STM_API stmErrorCode_t	stmClientInit (const char *clientName)
	Initialize STM client context. More...
STM_API stmErrorCode_t	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	stmRegisterCallBack (stmScheduleSwitchCallback_t func, void *userdata)
	Registers a callback function with a client to be invoked during a schedule switch. Before this client starts running, the callback function will be invoked. 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 hybrid resource. More...
STM_API stmErrorCode_t	stmRegisterCuDlaStandaloneResource (const char *resourceName, cudlaDevHandle cudla)
	Registers a cuDLA standalone resource. More...
STM_API stmErrorCode_t	stmRegisterCuDlaStandaloneSubmitter (stmCuDlaStandaloneSubmitter_t func, const char *const runnableId, void *userdata)
	Registers an stmCudlaStandaloneSubmitter_t function with the name provided by the user to the STM compiler. 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...
STM_API stmErrorCode_t	stmRegisterVulkanResource (const char *resourceName, VkQueue queue, VkDevice device, VkPhysicalDevice physicalDevice, VkInstance instance)
STM_API stmErrorCode_t	stmRegisterVulkanSubmitter (stmVulkanSubmitter_t func, const char *const runnableId, void *userdata)

---

Data Structure Documentation

stmRunnableInfo_t

struct stmRunnableInfo_t

Data Fields
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 114 of file stm.h.

stmCuDlaStandaloneSubmitter_t

typedef void(* stmCuDlaStandaloneSubmitter_t) (void *userdata, cudlaDevHandle cudla)

Function signature for STM cuDLA standalone submitter runnable.

Remarks

stmCuDlaStandaloneSubmitter_t functions should contain some CPU work, followed by some number of cuDLA standalone 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 standalone Support is only enabled with the 6.0.4.0 PDK, and will fail at the link stage otherwise.

Parameters

[in]	userdata	Pointer to any data needed by the runnable
[in]	cudla	cuDLA device handle created by application

Definition at line 267 of file stm.h.

stmCuDlaSubmitter_t

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

Function signature for STM cuDLA hybrid submitter runnable.

Remarks

stmCuDlaSubmitter_t functions should contain some CPU work, followed by some number of cuDLA hybrid submits. All submits must be launched on the provided CUDA stream. These functions should not internally launch any threads or call any blocking APIs. STM cuDLA hybrid 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 218 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 101 of file stm.h.

stmScheduleSwitchCallback_t

typedef void(* stmScheduleSwitchCallback_t) (uint16_t startScheduleId, uint16_t hyperepochId, void *userdata)

Function signature for STM schedule switch callback.

Remarks

stmScheduleSwitchCallback_t functions should only contain some CPU work. This function will be called once per hyperepoch for each client.

Definition at line 499 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 282 of file stm.h.

stmVulkanSubmitter_t

typedef void(* stmVulkanSubmitter_t) (void *userdata, VkQueue queue)

Definition at line 187 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 stmErrorCode_t stmClientInit

(

const char *

clientName

)

Initialize STM client context.

Remarks

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. Calling this after registering resources and runnables will allow the client to also receive schedule information here instead of in stmEnterScheduler.

Returns

stmErrorCode_t, the completion code of the operation:

• STM_ERROR_GENERIC if some error occured.
• STM_SUCCESS otherwise.

stmClientInitWithDiscriminator()

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

Initialize STM client context with a discriminator.

Remarks

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() Calling this after registering resources and runnables will allow the client to also receive schedule information here instead of in stmEnterScheduler.

Returns

stmErrorCode_t, the completion code of the operation:

• STM_ERROR_GENERIC if some error occured.
• STM_SUCCESS otherwise.

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 runnable in one STM client; subsequent calls are ignored.

Returns

stmErrorCode_t, the completion code of the operation: -STM_SUCCESS if successful. -STM_ERROR_GENERIC if the request to set the state to exit failed. -STM_ERROR_BAD_PARAMETER if the request to set the state to exit has already been triggered. -STM_ERROR_NOT_INITIALIZED if stmClientInit() has not been called, or stmClientExit() has already been called.

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.

stmRegisterCallBack()

STM_API stmErrorCode_t stmRegisterCallBack	(	stmScheduleSwitchCallback_t	func,
		void *	userdata
	)

Registers a callback function with a client to be invoked during a schedule switch. Before this client starts running, the callback function will be invoked.

Remarks

This API can only be called once per client; doing so multiple times will result in an error.

Parameters

[in]	func	The callback function to be executed.
[in]	userdata	Optional pointer to any data needed by the callback.

Returns

stmErrorCode_t, the completion code of the operation:

• STM_ERROR_BAD_PARAMETER if a call back function has already been registered with this client.
• STM_ERROR_GENERIC if some other error occured.
• STM_SUCCESS

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_GENERIC if some other error occured.
• STM_SUCCESS otherwise.

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_GENERIC if some other error occured.
• STM_SUCCESS otherwise.

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_GENERIC if some other error occured.
• STM_SUCCESS otherwise.

stmRegisterCuDlaResource()

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

Registers a cuDLA hybrid resource.

Remarks

STM cuDLA hybrid 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_GENERIC if some other error occured.
• STM_SUCCESS otherwise.

stmRegisterCuDlaStandaloneResource()

STM_API stmErrorCode_t stmRegisterCuDlaStandaloneResource	(	const char *	resourceName,
		cudlaDevHandle	cudla
	)

Registers a cuDLA standalone resource.

Remarks

STM cuDLA standalone Support is only enabled with the 6.0.4.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 cuDLA device handle 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 cudlaCreateDevice()
  • the same cuDLA device handle has already been registered (possibly with a different resourceName)

• STM_ERROR_GENERIC if some other error occured.
• STM_SUCCESS otherwise.

stmRegisterCuDlaStandaloneSubmitter()

STM_API stmErrorCode_t stmRegisterCuDlaStandaloneSubmitter	(	stmCuDlaStandaloneSubmitter_t	func,
		const char *const	runnableId,
		void *	userdata
	)

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

Remarks

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

Parameters

[in]	func	STM cuDLA standalone submitter runnable function pointer.
[in]	runnableId	Name of cuDLA standalone 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_GENERIC if some other error occured.
• STM_SUCCESS otherwise.

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 hybrid 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_GENERIC if some other error occured.
• STM_SUCCESS otherwise.

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_GENERIC if some other error occured.
• STM_SUCCESS otherwise.

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_GENERIC if some other error occured.
• STM_SUCCESS otherwise.

stmRegisterVulkanResource()

STM_API stmErrorCode_t stmRegisterVulkanResource	(	const char *	resourceName,
		VkQueue	queue,
		VkDevice	device,
		VkPhysicalDevice	physicalDevice,
		VkInstance	instance
	)

stmRegisterVulkanSubmitter()

STM_API stmErrorCode_t stmRegisterVulkanSubmitter	(	stmVulkanSubmitter_t	func,
		const char *const	runnableId,
		void *	userdata
	)