Public APIs

The following APIs should only be accessed by clients They can be accessed by including stm.h and linking to libstm runtime.so

typedef void (stmRunnable_t)(void userdata);
- Brief Function signature for STM CPU runnable.
- stmRunnable_t functions should only contain CPU work. They should not call any blocking APIs or internally launch any threads.
typedef void (stmCudaSubmitter_t)(void userdata, cudaStream_t stream);
- Function signature for STM CUDA submitter runnable.
- 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...
STM_API void stmClientInit(const char* clientName);
- Initialize STM client context.
- 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.
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.
- param[in] func STM CPU runnable function pointer.
- param[in] runnableId Name of CPU runnable provided to the STM compiler.
- param[in] userdata Pointer to any data needed by the runnable.
- return 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
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
- param[in] func STM CUDA submitter runnable function pointer
- param[in] runnableId Name of CUDA submitter runnable provided to the STM compiler
- param[in] userdata Pointer to any data needed by the runnable
- return 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.
STM_API stmErrorCode_t stmRegisterCudaResource(const char* resourceName,cudaStream_t stream);
- Registers a CUDA stream resource.
- param[in] resourceName Name of resource. Needs to match resource name passed to STM compiler
- param[in] stream CUDA stream created by application
- return 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.
typedef void (stmVpuSubmitter_t)(void userdata, cupvaStream_t vpu);
- Function signature for STM VPU submitter runnable
- stmVpuSubmitter_t functions should contain some CPU work, followed by some number of VPU submits. All submits must be launched on the provided VPU stream. These functions should not internally launch any threads or call any blocking APIs.
STM_API stmErrorCode_t stmRegisterVpuResource(const char* resourceName, cupvaStream_t vpu);
- Registers a VPU resource
- param[in] resourceName Name of resource. Needs to match resource name passed to STM compiler
- param[in] VPU stream created by application o return 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
  - the same vpu stream has already been registered (possibly with a different resourceName)
- STM_ERROR_NOT_INITIALIZED if stmClientInit() has not been called.
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
- param[in] func STM VPU submitter runnable function pointer
- param[in] runnableId Name of VPU submitter runnable provided to the STM compiler
- param[in] userdata Pointer to any data needed by the runnable
- return 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.
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
- 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()
- return 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.
STM_API stmErrorCode_t stmGetRuntimeInfo(stmRunnableInfo_t* info);
- Get runtime information about executiono Must be called from within a CPU runnable
- param[out] info Pointer to stmRunnableInfo_t whose fields will be populated
- return 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.
STM_API stmErrorCode_t stmExitScheduler(void);
- Return from stmEnterScheduler()
- 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.
- return 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.
STM_API void stmClientExit(void);
- Cleans up STM client context. No STM APIs can be called after this.
- This API can only be called once per call to stmClientInit(); doing so multiple times will cause undefined behavior. The following APIs can be accessed by including stm_manager.h.
STM_API stmErrorCode_t stmScheduleManagerInit(const char* scheduleManagerName);
- This API must be called before any other STM Schedule Management APIs. This API will block until the STM master process is started. Manager's context should be cleaned up with stmScheduleManagerExit() after STM has completed its execution. There is only one schedule manager in the system.
- return stmErrorCode_t, the completion code of the operation:
  - STM_ERROR_INSUFFICIENT_MEMORY : failure of memory allocation of STM.
  - STM_ERROR_BAD_VALUE : unsupported value for discriminator.
  - STM_ERROR_NOT_SUPPORTED : connection to master not enabled. ignore this error for dual SOC case and soc is secondary
  - STM_ERROR_GENERIC : Failed to receive messages from master.
STM_API stmErrorCode_t stmScheduleManagerInitWithDiscriminator(const char* scheduleManagerName, int32_t discriminator);
- This API must be called before any other STM Schedule Management APIs. This API will block until the STM master process with this discriminator is started. Manager's context should be cleaned up with stmScheduleManagerExit() after STM has completed its execution. Manager must call at most one of the two: stmScheduleManagerInit() or stmScheduleManagerInitWithDiscriminator(),if both are called single or multiple times, it will cause undefined behavior. There is only one schedule manager in the system. All negative values of discriminator are equivalent and the same as calling stmScheduleManagerInit()
- return stmErrorCode_t, the completion code of the operation:
  - STM_ERROR_INSUFFICIENT_MEMORY : failure of memory allocation of STM.
  - STM_ERROR_BAD_VALUE : unsupported value for discriminator.
  - STM_ERROR_NOT_SUPPORTED : connection to master not enabled. ignore this error for dual SOC case and soc is secondary
  - STM_ERROR_GENERIC : Failed to receive messages from master.
STM_API stmErrorCode_t stmScheduleManagerExit(void);
- Cleans up STM schedule Manager context. No STM APIs can be called after this.
- This API can only be called once per call to stmScheduleManagerInit(); doing so multiple times will cause undefined behavior.
- return stmErrorCode_t, the completion code of the operation:
  - STM_ERROR_NOT_INITIALIZED if not init api was called or called but failed.
  - STM_ERROR_GENERIC if fail to release some OS resources.check debug logs for further information
STM_API stmErrorCode_t stmScheduleManagerExit(void);
- This API must be called between stmScheduleManagerInit()/stmScheduleManagerInitWithDiscriminator() and stmScheduleManagerExit().
- return stmErrorCode_t, the completion code of the operation:
  - STM_ERROR_INSUFFICIENT_MEMORY : failure of memory allocation of STM.
  - STM_ERROR_BAD_STATE_TRANSITION : If current state is not READY
  - STM_ERROR_BAD_VALUE : unsupported value for discriminator.
  - STM_ERROR_NOT_SUPPORTED : connection to master not enabled. ignore this error for dual SOC case and soc is secondary
  - STM_ERROR_GENERIC : Failed to receive messages from master.
STM_API stmErrorCode_t stmStopSchedule(uint16_t scheduleId);
- This API must be called between stmScheduleManagerInit()/stmScheduleManagerInitWithDiscriminator() and stmScheduleManagerExit().
- return stmErrorCode_t, the completion code of the operation:
  - STM_ERROR_INSUFFICIENT_MEMORY : failure of memory allocation of STM.
  - STM_ERROR_BAD_STATE_TRANSITION : If current state is not READY
  - STM_ERROR_BAD_VALUE : unsupported value for discriminator.
  - STM_ERROR_NOT_SUPPORTED : connection to master not enabled. ignore this error for dual SOC case and soc is secondary
  - STM_ERROR_GENERIC : Failed to receive messages from master.