AMD rocAL API

AMD rocAL API#

rocAL: API: AMD rocAL API

The AMD rocAL is designed to efficiently decode and process images and videos from a variety of storage formats and modify them through a processing graph programmable by the user. More...

Functions
RocalContext ROCAL_API_CALL	rocalCreate (size_t batch_size, RocalProcessMode affinity, int gpu_id=0, size_t cpu_thread_count=1, size_t prefetch_queue_depth=3, RocalTensorOutputType output_tensor_data_type=RocalTensorOutputType::ROCAL_FP32, bool enable_checkpointing=false)
	rocalCreate creates the context for a new augmentation pipeline. Initializes all the required internals for the pipeline More...

RocalStatus ROCAL_API_CALL	rocalVerify (RocalContext context)
	rocalVerify function to verify the graph for all the inputs and outputs More...

RocalStatus ROCAL_API_CALL	rocalRun (RocalContext context)
	rocalRun function to process and run the built and verified graph. More...

RocalStatus ROCAL_API_CALL	rocalRelease (RocalContext rocal_context)
	rocalRelease function to free all the resources allocated during the graph creation process. More...

RocalStatus ROCAL_API_CALL	rocalSerialize (RocalContext rocal_context, size_t *serialized_string_size)
	Serialize the current pipeline into an opaque binary string. More...

RocalStatus ROCAL_API_CALL	rocalGetSerializedString (RocalContext rocal_context, char *serialized_string)
	Copy the last serialized pipeline string into a user buffer. More...

RocalContext ROCAL_API_CALL	rocalDeserialize (const char serialized_pipeline, size_t serialized_string_size, RocalPipelineParams pipe_params)
	Deserialize a pipeline from a serialized binary string. More...

RocalStatus ROCAL_API_CALL	rocalCheckpoint (RocalContext rocal_context, size_t *serialized_ckpt_string_size)
	Serialize the current pipeline state into an opaque checkpoint blob. More...

RocalStatus ROCAL_API_CALL	rocalGetSerializedCheckpointString (RocalContext rocal_context, char *serialized_ckpt_string)
	Copy the last serialized checkpoint blob into a user buffer. More...

RocalStatus ROCAL_API_CALL	rocalRestoreFromSerializedCheckpoint (RocalContext rocal_context, const char *serialized_ckpt_string, size_t serialized_ckpt_size)
	Restore pipeline state from a serialized checkpoint blob. More...

Detailed Description

The AMD rocAL is designed to efficiently decode and process images and videos from a variety of storage formats and modify them through a processing graph programmable by the user.

Function Documentation

◆ rocalCheckpoint()

RocalStatus ROCAL_API_CALL rocalCheckpoint	(	RocalContext	rocal_context,
		size_t *	serialized_ckpt_string_size
	)

Serialize the current pipeline state into an opaque checkpoint blob.

This API captures the internal runtime state of the pipeline (for example, loader position, operator state and random number generator state) into an opaque binary checkpoint blob. The size of the blob is returned in serialized_ckpt_string_size and the binary data can subsequently be obtained via rocalGetSerializedCheckpointString().

Checkpointing must be enabled when creating the context (see the enable_checkpointing parameter of rocalCreate) and the pipeline must have run at least once; otherwise this function will fail and return ROCAL_RUNTIME_ERROR.

Parameters

[in]	rocal_context	the rocAL context
[out]	serialized_ckpt_string_size	number of bytes in the serialized checkpoint blob

Returns: A RocalStatus - A status code indicating the success or failure.

◆ rocalCreate()

RocalContext ROCAL_API_CALL rocalCreate	(	size_t	batch_size,
		RocalProcessMode	affinity,
		int	gpu_id = `0`,
		size_t	cpu_thread_count = `1`,
		size_t	prefetch_queue_depth = `3`,
		RocalTensorOutputType	output_tensor_data_type = `RocalTensorOutputType::ROCAL_FP32`,
		bool	enable_checkpointing = `false`
	)

rocalCreate creates the context for a new augmentation pipeline. Initializes all the required internals for the pipeline

Parameters

[in]	batch_size	batch size
[in]	affinity	RocalProcessMode: Defines whether rocal data loading should be on the CPU or GPU.
[in]	gpu_id	GPU id
[in]	cpu_thread_count	number of cpu threads
[in]	prefetch_queue_depth	The depth of the prefetch queue.
[in]	output_tensor_data_type	RocalTensorOutputType: Defines whether the output of rocal tensor is FP32 or FP16.
[in]	enable_checkpointing	is enabled to store the state of each operator in the pipeline for every iteration

Returns: A RocalContext - The context for the pipeline

◆ rocalDeserialize()

RocalContext ROCAL_API_CALL rocalDeserialize	(	const char *	serialized_pipeline,
		size_t	serialized_string_size,
		RocalPipelineParams *	pipe_params
	)

Deserialize a pipeline from a serialized binary string.

Constructs a rocAL pipeline from the serialized input and returns a new context. Caller-provided fields in pipe_params take precedence over values stored in the serialized pipeline; any remaining unset fields are populated from the deserialized pipeline metadata.

Parameters

[in]	serialized_pipeline	pointer to the serialized pipeline buffer.
[in]	serialized_string_size	size in bytes of the serialized pipeline buffer.
[in,out]	pipe_params	pointer to RocalPipelineParams used to override pipeline configuration; must not be nullptr.

Returns: A RocalContext representing the newly created pipeline context, or nullptr on failure.

◆ rocalGetSerializedCheckpointString()

RocalStatus ROCAL_API_CALL rocalGetSerializedCheckpointString	(	RocalContext	rocal_context,
		char *	serialized_ckpt_string
	)

Copy the last serialized checkpoint blob into a user buffer.

This API copies the checkpoint data produced by rocalCheckpoint() into the user-provided buffer. The buffer must be pre-allocated with size at least serialized_ckpt_string_size bytes as returned by rocalCheckpoint().

Warning: The checkpoint blob is binary data and is not null-terminated. The caller is responsible for treating it as raw bytes and for ensuring the destination buffer has sufficient capacity (at least serialized_ckpt_string_size bytes). Passing an insufficiently sized buffer will result in buffer overflow and undefined behavior.

Parameters

[in]	rocal_context	the rocAL context
[out]	serialized_ckpt_string	destination buffer to receive the serialized checkpoint blob. Must be pre-allocated with at least serialized_ckpt_string_size bytes.

Returns: A RocalStatus - A status code indicating the success or failure.

◆ rocalGetSerializedString()

RocalStatus ROCAL_API_CALL rocalGetSerializedString	(	RocalContext	rocal_context,
		char *	serialized_string
	)

Copy the last serialized pipeline string into a user buffer.

This API copies the serialized pipeline string produced by rocalSerialize() into the user-provided buffer. The buffer must be pre-allocated with size at least serialized_string_size + 1 bytes to accommodate the null terminator.

Warning: The caller is responsible for ensuring the destination buffer has sufficient capacity (at least serialized_string_size + 1 bytes as returned by rocalSerialize). Passing an insufficiently sized buffer will result in buffer overflow and undefined behavior.

Parameters

[in]	rocal_context	the rocAL context
[out]	serialized_string	destination buffer to receive the serialized string (null-terminated). Must be pre-allocated with at least serialized_string_size + 1 bytes.

Returns: A RocalStatus - A status code indicating the success or failure.

◆ rocalRelease()

RocalStatus ROCAL_API_CALL rocalRelease ( RocalContext rocal_context )

rocalRelease function to free all the resources allocated during the graph creation process.

Parameters

[in] context the rocal context

Returns: A RocalStatus - A status code indicating the success or failure.

◆ rocalRestoreFromSerializedCheckpoint()

RocalStatus ROCAL_API_CALL rocalRestoreFromSerializedCheckpoint	(	RocalContext	rocal_context,
		const char *	serialized_ckpt_string,
		size_t	serialized_ckpt_size
	)

Restore pipeline state from a serialized checkpoint blob.

Restores the pipeline runtime state from a checkpoint blob previously produced by rocalCheckpoint()/rocalGetSerializedCheckpointString().

Note

Preconditions:

The pipeline must be built (rocalVerify() called) but not currently running.
Checkpointing must have been enabled at pipeline creation time (enable_checkpointing=True).
The checkpoint must originate from a pipeline with a compatible configuration (same augmentation graph, batch size, and reader setup).
Any buffered data in the prefetch queue is discarded and re-filled from the restored reader position.

Parameters

[in]	rocal_context	the rocAL context
[in]	serialized_ckpt_string	pointer to checkpoint blob bytes
[in]	serialized_ckpt_size	size in bytes of the checkpoint blob

Returns: A RocalStatus - A status code indicating the success or failure.

◆ rocalRun()

RocalStatus ROCAL_API_CALL rocalRun ( RocalContext context )

rocalRun function to process and run the built and verified graph.

Parameters

[in] context the rocal context

Returns: A RocalStatus - A status code indicating the success or failure

◆ rocalSerialize()

RocalStatus ROCAL_API_CALL rocalSerialize	(	RocalContext	rocal_context,
		size_t *	serialized_string_size
	)

Serialize the current pipeline into an opaque binary string.

Parameters

[in]	rocal_context	the rocAL context
[out]	serialized_string_size	number of bytes in the serialized string

Returns: A RocalStatus - A status code indicating the success or failure.

◆ rocalVerify()

RocalStatus ROCAL_API_CALL rocalVerify ( RocalContext context )

rocalVerify function to verify the graph for all the inputs and outputs

Parameters

[in] context the rocal context

Returns: A RocalStatus - A status code indicating the success or failure

AMD rocAL API

AMD rocAL API#

Functions

Detailed Description

Function Documentation

◆ rocalCheckpoint()

◆ rocalCreate()

◆ rocalDeserialize()

◆ rocalGetSerializedCheckpointString()

◆ rocalGetSerializedString()

◆ rocalRelease()

◆ rocalRestoreFromSerializedCheckpoint()

◆ rocalRun()

◆ rocalSerialize()

◆ rocalVerify()