Execution Context Management

Functions

Execution Context Management

HIP API

Collaboration diagram for Execution Context Management:

Functions
hipError_t	hipDeviceGetDevResource (hipDevice_t device, hipDevResource *resource, hipDevResourceType type)
	Gets device resource of a given type for a device.
hipError_t	hipDevSmResourceSplitByCount (hipDevResource *result, unsigned int *nbGroups, const hipDevResource *input, hipDevResource *remainder, unsigned int flags, unsigned int minCount)
	Splits SM resources into groups containing the specified number of SMs.
hipError_t	hipDevSmResourceSplit (hipDevResource *result, unsigned int nbGroups, const hipDevResource *input, hipDevResource *remainder, unsigned int flags, hipDevSmResourceGroupParams *groupParams)
	Splits SM resources into structured groups.
hipError_t	hipDevResourceGenerateDesc (hipDevResourceDesc_t *phDesc, hipDevResource *resources, unsigned int nbResources)
	Generates a resource descriptor from one or more device resources.
hipError_t	hipGreenCtxCreate (hipExecutionCtx_t *ctx, hipDevResourceDesc_t desc, int device, unsigned int flags)
	Creates a green context from a resource descriptor.
hipError_t	hipExecutionCtxDestroy (hipExecutionCtx_t ctx)
	Destroys an execution context.
hipError_t	hipDeviceGetExecutionCtx (hipExecutionCtx_t *ctx, int device)
	Returns the default execution context for a device.
hipError_t	hipExecutionCtxStreamCreate (hipStream_t *stream, hipExecutionCtx_t greenctx, unsigned int flags, int priority)
	Creates a stream on an execution context with specified flags and priority.
hipError_t	hipExecutionCtxGetDevResource (hipExecutionCtx_t ctx, hipDevResource *resource, hipDevResourceType type)
	Returns the device resource of a given type for an execution context.
hipError_t	hipExecutionCtxGetDevice (int *device, hipExecutionCtx_t ctx)
	Returns the device associated with an execution context.
hipError_t	hipExecutionCtxGetId (hipExecutionCtx_t ctx, unsigned long long *ctxId)
	Returns a unique identifier for an execution context.
hipError_t	hipStreamGetDevResource (hipStream_t hStream, hipDevResource *resource, hipDevResourceType type)
	Returns the device resource of a given type for a stream.
hipError_t	hipExecutionCtxRecordEvent (hipExecutionCtx_t ctx, hipEvent_t event)
	Records an event on an execution context.
hipError_t	hipExecutionCtxSynchronize (hipExecutionCtx_t ctx)
	Blocks until all work on an execution context has completed.
hipError_t	hipExecutionCtxWaitEvent (hipExecutionCtx_t ctx, hipEvent_t event)
	Makes an execution context wait on an event.

Detailed Description

---

---

This section describes execution context management functions of HIP runtime API.

Function Documentation

◆ hipDeviceGetDevResource()

hipError_t hipDeviceGetDevResource	(	hipDevice_t	device,
		hipDevResource *	resource,
		hipDevResourceType	type
	)

Gets device resource of a given type for a device.

Parameters

[out]	resource	- Output device resource pointer
[in]	device	- Device to get resource for
[in]	type	- Type of resource to retrieve

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidResourceType, hipErrorInvalidDevice

◆ hipDeviceGetExecutionCtx()

hipError_t hipDeviceGetExecutionCtx	(	hipExecutionCtx_t *	ctx,
		int	device
	)

Returns the default execution context for a device.

Parameters

[out]	ctx	- Output pointer for execution context
[in]	device	- The device on which to receive the execution context

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidDevice, hipErrorOutOfMemory

◆ hipDevResourceGenerateDesc()

hipError_t hipDevResourceGenerateDesc	(	hipDevResourceDesc_t *	phDesc,
		hipDevResource *	resources,
		unsigned int	nbResources
	)

Generates a resource descriptor from one or more device resources.

Parameters

[out]	phDesc	- Output parameter that receives the generated resource descriptor
[in]	resources	- Pointer of device resources to be included in the descriptor
[in]	nbResources	- Number of resources specified

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidResourceType, hipErrorInvalidDevice

◆ hipDevSmResourceSplit()

hipError_t hipDevSmResourceSplit	(	hipDevResource *	result,
		unsigned int	nbGroups,
		const hipDevResource *	input,
		hipDevResource *	remainder,
		unsigned int	flags,
		hipDevSmResourceGroupParams *	groupParams
	)

Splits SM resources into structured groups.

Parameters

[out]	result	- Output device resource pointer
[in]	nbGroups	- The poiter specifying the number of groups
[in]	input	- Valid input SM resource to be split
[in]	remainder	- If the input resource cannot be evenly split among nbGroups, the remaining resourced are returned through this parameter.
[in]	flags	- Flags specifying partition usage and constraints to apply when splitting the inout resource.
[in]	groupParams	- Describes how the SM resources should be partitioned and assigned to the corresponding result entries.

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidResourceType, hipErrorInvalidResourceConfiguration, hipErrorInvalidDevice

◆ hipDevSmResourceSplitByCount()

hipError_t hipDevSmResourceSplitByCount	(	hipDevResource *	result,
		unsigned int *	nbGroups,
		const hipDevResource *	input,
		hipDevResource *	remainder,
		unsigned int	flags,
		unsigned int	minCount
	)

Splits SM resources into groups containing the specified number of SMs.

Parameters

[out]	result	- Output device resource pointer
[in]	nbGroups	- The poiter specifying the number of groups
[in]	input	- Valid input SM resource to be split
[in]	remainder	- If the input resource cannot be evenly split among nbGroups, the remaining resourced are returned through this parameter.
[in]	flags	- Flags specifying partition usage and constraints to apply when splitting the inout resource.
[in]	minCount	- Specifies the minimum number of SMs required

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidResourceType, hipErrorInvalidDevice, hipErrorNotSupported

◆ hipExecutionCtxDestroy()

hipError_t hipExecutionCtxDestroy

(

hipExecutionCtx_t

ctx

)

Destroys an execution context.

Parameters

[in]

ctx

- Execution context to destroy

Returns

hipSuccess, hipErrorInvalidValue

◆ hipExecutionCtxGetDevice()

hipError_t hipExecutionCtxGetDevice	(	int *	device,
		hipExecutionCtx_t	ctx
	)

Returns the device associated with an execution context.

Parameters

[out]	device	- Returns device handle for the specified execution context
[in]	ctx	- Execution context to obtain the device

Returns

hipSuccess, hipErrorInvalidValue

◆ hipExecutionCtxGetDevResource()

hipError_t hipExecutionCtxGetDevResource	(	hipExecutionCtx_t	ctx,
		hipDevResource *	resource,
		hipDevResourceType	type
	)

Returns the device resource of a given type for an execution context.

Parameters

[out]	resource	- Output pointer that receives the structured device resource
[in]	ctx	- Execution context to get resource for
[in]	type	- Type of device resource

Returns

hipSuccess, hipErrorInvalidValue

◆ hipExecutionCtxGetId()

hipError_t hipExecutionCtxGetId	(	hipExecutionCtx_t	ctx,
		unsigned long long *	ctxId
	)

Returns a unique identifier for an execution context.

Parameters

[out]	ctxId	- Pointer to the context ID
[in]	ctx	- Execution context to obtain the ID

Returns

hipSuccess, hipErrorInvalidValue

◆ hipExecutionCtxRecordEvent()

hipError_t hipExecutionCtxRecordEvent	(	hipExecutionCtx_t	ctx,
		hipEvent_t	event
	)

Records an event on an execution context.

Parameters

[out]	event	- Event to record
[in]	ctx	- Execution context to record event for

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidHandle

◆ hipExecutionCtxStreamCreate()

hipError_t hipExecutionCtxStreamCreate	(	hipStream_t *	stream,
		hipExecutionCtx_t	greenctx,
		unsigned int	flags,
		int	priority
	)

Creates a stream on an execution context with specified flags and priority.

Parameters

[out]	stream	- Output pointer of the created stream
[in]	greenctx	- Execution context used to create and initialize the stream
[in]	flags	- Flags for stream creation
[in]	priority	- Stream priority

Returns

hipSuccess, hipErrorInvalidValue, hipErrorOutOfMemory

◆ hipExecutionCtxSynchronize()

hipError_t hipExecutionCtxSynchronize

(

hipExecutionCtx_t

ctx

)

Blocks until all work on an execution context has completed.

Parameters

[in]

ctx

- Execution context to synchronize

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidHandle

◆ hipExecutionCtxWaitEvent()

hipError_t hipExecutionCtxWaitEvent	(	hipExecutionCtx_t	ctx,
		hipEvent_t	event
	)

Makes an execution context wait on an event.

Parameters

[in]	event	- Event to wait on
[in]	ctx	- Execution context to wait for

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidHandle

◆ hipGreenCtxCreate()

hipError_t hipGreenCtxCreate	(	hipExecutionCtx_t *	ctx,
		hipDevResourceDesc_t	desc,
		int	device,
		unsigned int	flags
	)

Creates a green context from a resource descriptor.

Parameters

[out]	ctx	- Output parameter that receives the handle to the created green context
[in]	desc	- Resource descriptor generated via hipDevResourceGenerateDesc that specifies the set of resources to be used
[in]	device	- Device on which the green context is created
[in]	flags	- Flags controlling green context creation

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidDevice

◆ hipStreamGetDevResource()

hipError_t hipStreamGetDevResource	(	hipStream_t	hStream,
		hipDevResource *	resource,
		hipDevResourceType	type
	)

Returns the device resource of a given type for a stream.

Parameters

[out]	resource	- Pointer to the structured device resource
[in]	hStream	- Stream to get resource for
[in]	type	- Type of resource

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidResourceType, hipErrorInvalidHandle