Skip to main content
`Ctrl`+`K`

# Handle

MIOpen: Handle
Typedefs | Enumerations | Functions
Handle

## Typedefs

typedef void *(* | miopenAllocatorFunction) (void *context, size_t sizeBytes)
| Custom allocator function.
typedef void(* | miopenDeallocatorFunction) (void *context, void *memory)
| Custom deallocator function.

## Enumerations

enum | miopenStatus_t { miopenStatusSuccess = 0 , miopenStatusNotInitialized = 1 , miopenStatusInvalidValue = 2 , miopenStatusBadParm = 3 , miopenStatusAllocFailed = 4 , miopenStatusInternalError = 5 , miopenStatusNotImplemented = 6 , miopenStatusUnknownError = 7 , miopenStatusUnsupportedOp = 8 , miopenStatusGpuOperationsSkipped = 9 , miopenStatusVersionMismatch = 10 }
enum | miopenF8RoundingMode_t { miopenF8RoundingModeStandard = 0 , miopenF8RoundingModeStochastic = 1 }
enum | miopenTuningPolicy_t { miopenTuningPolicyNone = 1 , miopenTuningPolicyDbUpdate = 2 , miopenTuningPolicySearch , miopenTuningPolicySearchDbUpdate = 4 , miopenTuningPolicyDbClean = 5 }

## Functions

| MIOPEN_DECLARE_OBJECT (miopenHandle)
| Creates the miopenHandle_t type.
const char * | miopenGetErrorString (miopenStatus_t error)
| Get character string for an error code.
miopenStatus_t | miopenGetVersion (size_t *major, size_t *minor, size_t *patch)
| Method to return version of MIOpen.
miopenStatus_t | miopenCreate (miopenHandle_t *handle)
| Method to create the MIOpen handle object.
miopenStatus_t | miopenCreateWithStream (miopenHandle_t *handle, miopenAcceleratorQueue_t stream)
| Create a MIOpen handle with an accelerator stream.
miopenStatus_t | miopenDestroy (miopenHandle_t handle)
| Destroys the MIOpen handle.
miopenStatus_t | miopenSetStream (miopenHandle_t handle, miopenAcceleratorQueue_t streamID)
| Set accelerator command queue previously created.
miopenStatus_t | miopenGetStream (miopenHandle_t handle, miopenAcceleratorQueue_t *streamID)
| Get the previously created accelerator command queue.
miopenStatus_t | miopenSetAllocator (miopenHandle_t handle, miopenAllocatorFunction allocator, miopenDeallocatorFunction deallocator, void *allocatorContext)
| Set allocator for previously created miopenHandle.
miopenStatus_t | miopenGetKernelTime (miopenHandle_t handle, float *time)
| Get time for last kernel launched.
miopenStatus_t | miopenEnableProfiling (miopenHandle_t handle, bool enable)
| Enable profiling to retrieve kernel time.
miopenStatus_t | miopenSetTuningPolicy (miopenHandle_t handle, miopenTuningPolicy_t newValue)
| Update tuning policy for a specific handle. API alternative for MIOPEN_FIND_ENFORCE environment variable.
miopenStatus_t | miopenGetTuningPolicy (miopenHandle_t handle, miopenTuningPolicy_t *value)
| Get tuning policy from a handle.

## Detailed Description

## Typedef Documentation

## ◆ miopenAllocatorFunction

typedef void *(* miopenAllocatorFunction) (void *context, size_t sizeBytes)

Custom allocator function.

This function allow for user-defined custom allocator

Parameters

  context | A pointer a context (input)
  sizeBytes | Number of bytes to allocate (input)

## ◆ miopenDeallocatorFunction

typedef void(* miopenDeallocatorFunction) (void *context, void *memory)

Custom deallocator function.

This function allow for user-defined custom deallocation function

Parameters

  context | A pointer context (input)
  memory | A pointer allocated memory (input)

## Enumeration Type Documentation

## ◆ miopenF8RoundingMode_t

enum miopenF8RoundingMode_t

Enumerator
miopenF8RoundingModeStandard |
miopenF8RoundingModeStochastic |

## ◆ miopenStatus_t

enum miopenStatus_t

Error codes that are returned by all MIOpen API calls.

Enumerator
miopenStatusSuccess | No errors
miopenStatusNotInitialized | Data not initialized.
miopenStatusInvalidValue | Incorrect variable value.
miopenStatusBadParm | Incorrect parameter detected.
miopenStatusAllocFailed | Memory allocation error.
miopenStatusInternalError | MIOpen failure.
miopenStatusNotImplemented | Use of unimplemented feature.
miopenStatusUnknownError | Unknown error occurred.
miopenStatusUnsupportedOp | Unsupported operator for fusion.
miopenStatusGpuOperationsSkipped | This is not an error.
miopenStatusVersionMismatch | Version mismatch of the supplied binary data argment.

## ◆ miopenTuningPolicy_t

enum miopenTuningPolicy_t

Tuning policy for MIOpen Find-related calls. Supports only the following policies of MIOpenFindEnforce:

1. None: Do not enforce anything.
2. DbUpdate: Tune and update the database.
3. Search: Search the database first; if no record is found, tune but do not update the database.
4. SearchDbUpdate: Combination of Search and DbUpdate.
5. DbClean: Remove existing entry, do not tune. Note: MIOpenFindEnforce has additional features that are not supported by TuningPolicy. Note: TuningPolicy has higher priority over MIOPEN_FIND_ENFORCE.

Enumerator
miopenTuningPolicyNone |
miopenTuningPolicyDbUpdate |
miopenTuningPolicySearch |
miopenTuningPolicySearchDbUpdate |
miopenTuningPolicyDbClean |

## Function Documentation

## ◆ MIOPEN_DECLARE_OBJECT()

MIOPEN_DECLARE_OBJECT | ( | miopenHandle |  | ) |

Creates the miopenHandle_t type.

## ◆ miopenCreate()

miopenStatus_t miopenCreate | ( | miopenHandle_t * | handle | ) |

Method to create the MIOpen handle object.

This function creates a MIOpen handle. This is called at the very start to initialize the MIOpen environment.

Parameters

  handle | A pointer to a MIOpen handle type (output)

Returns
  miopenStatus_t

## ◆ miopenCreateWithStream()

miopenStatus_t miopenCreateWithStream | ( | miopenHandle_t * | handle,
|  | miopenAcceleratorQueue_t | stream )

Create a MIOpen handle with an accelerator stream.

The HIP side uses a hipStream_t type for the stream, while OpenCL will use a cl_command_queue.

Create a handle with a previously created accelerator command queue.

Parameters

  handle | A pointer to a MIOpen handle type (output)
  stream | An accelerator queue type (input)

Returns
  miopenStatus_t

## ◆ miopenDestroy()

miopenStatus_t miopenDestroy | ( | miopenHandle_t | handle | ) |

Destroys the MIOpen handle.

This is called when breaking down the MIOpen environment.

Parameters

  handle | MIOpen handle (input)

Returns
  miopenStatus_t

## ◆ miopenEnableProfiling()

miopenStatus_t miopenEnableProfiling | ( | miopenHandle_t | handle,
|  | bool | enable )

Enable profiling to retrieve kernel time.

Enable or disable kernel profiling. This profiling is only for kernel time.

Parameters

  handle | MIOpen handle (input)
  enable | Boolean to toggle profiling (input)

Returns
  miopenStatus_t

## ◆ miopenGetErrorString()

const char * miopenGetErrorString | ( | miopenStatus_t | error | ) |

Get character string for an error code.

A function which returns a NULL terminated character string of the error code.

Parameters

  error | miopenStatus_t type error status (input)

Returns
  errorString

## ◆ miopenGetKernelTime()

miopenStatus_t miopenGetKernelTime | ( | miopenHandle_t | handle,
|  | float * | time )

Get time for last kernel launched.

This function is used only when profiling mode has been enabled. Kernel timings are based on the MIOpen handle and is not thread-safe. In order to use multi-threaded profiling, create an MIOpen handle for each concurrent thread.

Parameters

  handle | MIOpen handle (input)
  time | Pointer to a float type to contain kernel time in milliseconds (output)

Returns
  miopenStatus_t

## ◆ miopenGetStream()

miopenStatus_t miopenGetStream | ( | miopenHandle_t | handle,
|  | miopenAcceleratorQueue_t * | streamID )

Get the previously created accelerator command queue.

Creates a command queue for an accelerator device

Parameters

  handle | MIOpen handle (input)
  streamID | Pointer to a accelerator queue type (output)

Returns
  miopenStatus_t

## ◆ miopenGetTuningPolicy()

miopenStatus_t miopenGetTuningPolicy | ( | miopenHandle_t | handle,
|  | miopenTuningPolicy_t * | value )

Get tuning policy from a handle.

Parameters

  [in] | handle | MIOpen Handle to fetch value from
  [in] | value | Would be set to the current tuning policy value. Must not be null

Returns
  miopenStatus_t

## ◆ miopenGetVersion()

miopenStatus_t miopenGetVersion | ( | size_t * | major,
|  | size_t * | minor,
|  | size_t * | patch )

Method to return version of MIOpen.

The output values of this call follow from the versioning format major.minor.patch

Pointers that are NULL will be ignored.

Parameters

  major | Major version number (output)
  minor | Minor version number (output)
  patch | Patch version number (output)

Returns
  miopenStatus_t

## ◆ miopenSetAllocator()

miopenStatus_t miopenSetAllocator | ( | miopenHandle_t | handle,
|  | miopenAllocatorFunction | allocator,
|  | miopenDeallocatorFunction | deallocator,
|  | void * | allocatorContext )

Set allocator for previously created miopenHandle.

Set a command queue for an accelerator device

Parameters

  handle | MIOpen handle
  allocator | A callback function MIOpen will use for internal memory allocations. The provided callback function should allocate device memory with requested size and return a pointer to this memory. Passing 0 will restore the default MIOpen allocator and deallocator.
  deallocator | A callback function MIOpen will use to for internal memory deallocation. The provided callback function should free the specified memory pointer
  allocatorContext | User-specified pointer which is passed to `allocator` and `deallocator` This allows the callback function to access state set by the caller to this function, for example a stateful heap allocator or a c++ class.

Returns
  miopenStatus_t

## ◆ miopenSetStream()

miopenStatus_t miopenSetStream | ( | miopenHandle_t | handle,
|  | miopenAcceleratorQueue_t | streamID )

Set accelerator command queue previously created.

Set a command queue for an accelerator device

Parameters

  handle | MIOpen handle (input)
  streamID | An accelerator queue type (input)

Returns
  miopenStatus_t

## ◆ miopenSetTuningPolicy()

miopenStatus_t miopenSetTuningPolicy | ( | miopenHandle_t | handle,
|  | miopenTuningPolicy_t | newValue )

Update tuning policy for a specific handle. API alternative for MIOPEN_FIND_ENFORCE environment variable.

Parameters

  [in] | handle | MIOpen Handle to update
  [in] | newValue | New tuning policy value. Default value is miopenTuningPolicyNone

Returns
  miopenStatus_t