usm.yml

#
# Copyright (C) 2021 Intel Corporation
#
# Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
# See LICENSE.TXT
# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
#
# See YaML.md for syntax definition
#
--- #--------------------------------------------------------------------------
type: header
desc: "Intel $OneApi Unified Runtime APIs"
ordinal: "4"
--- #--------------------------------------------------------------------------
type: enum
desc: "USM host memory property flags"
class: $xUSM
name: $x_usm_host_mem_flags_t
etors:
    - name: INITIAL_PLACEMENT
      value: "$X_BIT(0)"
      desc: "Optimize shared allocation for first access on the host"
--- #--------------------------------------------------------------------------
type: enum
desc: "USM device memory property flags"
class: $xUSM
name: $x_usm_device_mem_flags_t
etors:
    - name: WRITE_COMBINED
      value: "$X_BIT(0)"
      desc: "Memory should be allocated write-combined (WC)"
    - name: INITIAL_PLACEMENT
      value: "$X_BIT(1)"
      desc: "Optimize shared allocation for first access on the device"
    - name: DEVICE_READ_ONLY
      value: "$X_BIT(2)"
      desc: "Memory is only possibly modified from the host, but read-only in all device code"
--- #--------------------------------------------------------------------------
type: enum
desc: "USM memory property flags"
class: $xUSM
name: $x_usm_pool_flags_t
etors:
    - name: ZERO_INITIALIZE_BLOCK
      value: "$X_BIT(0)"
      desc: "All coarse-grain allocations (allocations from the driver) will be zero-initialized."
--- #--------------------------------------------------------------------------
type: enum
desc: "USM allocation type"
class: $xUSM
name: $x_usm_type_t
etors:
    - name: UNKNOWN
      desc: "Unknown USM type"
    - name: HOST
      desc: "Host USM type"
    - name: DEVICE
      desc: "Device USM type"
    - name: SHARED
      desc: "Shared USM type"
--- #--------------------------------------------------------------------------
type: enum
desc: "USM memory allocation information type"
class: $xUSM
name: $x_usm_alloc_info_t
typed_etors: True
etors:
    - name: TYPE
      desc: "[$x_usm_type_t] Memory allocation type info"
    - name: BASE_PTR
      desc: "[void *] Memory allocation base pointer info"
    - name: SIZE
      desc: "[size_t] Memory allocation size info"
    - name: DEVICE
      desc: "[$x_device_handle_t] Memory allocation device info"
    - name: POOL
      desc: "[$x_usm_pool_handle_t] Memory allocation pool info"
--- #--------------------------------------------------------------------------
type: enum
desc: "USM memory advice"
class: $xUSM
name: $x_usm_advice_flags_t
etors:
    - name: DEFAULT
      value: "$X_BIT(0)"
      desc: "The USM memory advice is default"
    - name: SET_READ_MOSTLY
      value: "$X_BIT(1)"
      desc: "Hint that memory will be read from frequently and written to rarely"
    - name: CLEAR_READ_MOSTLY
      value: "$X_BIT(2)"
      desc: "Removes the affect of $X_USM_ADVICE_FLAG_SET_READ_MOSTLY"
    - name: SET_PREFERRED_LOCATION
      value: "$X_BIT(3)"
      desc: "Hint that the preferred memory location is the specified device"
    - name: CLEAR_PREFERRED_LOCATION
      value: "$X_BIT(4)"
      desc: "Removes the affect of $X_USM_ADVICE_FLAG_SET_PREFERRED_LOCATION"
    - name: SET_NON_ATOMIC_MOSTLY
      value: "$X_BIT(5)"
      desc: "Hint that memory will mostly be accessed non-atomically"
    - name: CLEAR_NON_ATOMIC_MOSTLY
      value: "$X_BIT(6)"
      desc: "Removes the affect of $X_USM_ADVICE_FLAG_SET_NON_ATOMIC_MOSTLY"
    - name: BIAS_CACHED
      value: "$X_BIT(7)"
      desc: "Hint that memory should be cached"
    - name: BIAS_UNCACHED
      value: "$X_BIT(8)"
      desc: "Hint that memory should be not be cached"
    - name: SET_ACCESSED_BY_DEVICE
      value: "$X_BIT(9)"
      desc: "Hint that memory will be mostly accessed by the specified device"
    - name: CLEAR_ACCESSED_BY_DEVICE
      value: "$X_BIT(10)"
      desc: "Removes the affect of $X_USM_ADVICE_FLAG_SET_ACCESSED_BY_DEVICE"
    - name: SET_ACCESSED_BY_HOST
      value: "$X_BIT(11)"
      desc: "Hint that memory will be mostly accessed by the host"
    - name: CLEAR_ACCESSED_BY_HOST
      value: "$X_BIT(12)"
      desc: "Removes the affect of $X_USM_ADVICE_FLAG_SET_ACCESSED_BY_HOST"
    - name: SET_PREFERRED_LOCATION_HOST
      value: "$X_BIT(13)"
      desc: "Hint that the preferred memory location is the host"
    - name: CLEAR_PREFERRED_LOCATION_HOST
      value: "$X_BIT(14)"
      desc: "Removes the affect of $X_USM_ADVICE_FLAG_SET_PREFERRED_LOCATION_HOST"
    - name: SET_NON_COHERENT_MEMORY
      value: "$X_BIT(15)"
      desc: "Hint that memory coherence will be coarse-grained (up-to-date only at kernel boundaries)"
    - name: CLEAR_NON_COHERENT_MEMORY
      value: "$X_BIT(16)"
      desc: "Removes the effect of $X_USM_ADVICE_FLAG_SET_NON_COHERENT_MEMORY"
--- #--------------------------------------------------------------------------
type: handle
desc: "Handle of USM pool"
class: $xUSM
name: "$x_usm_pool_handle_t"
--- #--------------------------------------------------------------------------
type: struct
desc: "USM allocation descriptor type."
class: $xUSM
name: $x_usm_desc_t
base: $x_base_desc_t
members:
    - type: $x_usm_advice_flags_t
      name: hints
      desc: "[in] Memory advice hints"
    - type: uint32_t
      name: align
      desc: |
            [in] alignment of the USM memory object
            Must be zero or a power of 2.
            Must be equal to or smaller than the size of the largest data type supported by `hDevice`.
--- #--------------------------------------------------------------------------
type: struct
desc: "USM host allocation descriptor type."
details:
  - Specify these properties in $xUSMHostAlloc and $xUSMSharedAlloc via $x_usm_desc_t
    as part of a `pNext` chain.
class: $xUSM
name: $x_usm_host_desc_t
base: $x_base_desc_t
members:
    - type: $x_usm_host_mem_flags_t
      name: flags
      desc: "[in] host memory allocation flags"
--- #--------------------------------------------------------------------------
type: struct
desc: "USM device allocation descriptor type."
details:
  - Specify these properties in $xUSMDeviceAlloc and $xUSMSharedAlloc via $x_usm_desc_t
    as part of a `pNext` chain.
class: $xUSM
name: $x_usm_device_desc_t
base: $x_base_desc_t
members:
    - type: $x_usm_device_mem_flags_t
      name: flags
      desc: "[in] device memory allocation flags."
--- #--------------------------------------------------------------------------
type: struct
desc: "USM allocation location desc"
details:
    - Specify these properties in $xUSMHostAlloc, $xUSMDeviceAlloc and
      $xUSMSharedAlloc via $x_usm_desc_t as part of a `pNext` chain.
analogue:
    - "cl_intel_mem_alloc_buffer_location"
class: $xUSM
name: $x_usm_alloc_location_desc_t
base: $x_base_desc_t
members:
    - type: uint32_t
      name: location
      desc: >
          [in] Identifies the ID of global memory partition to which the memory
          should be allocated.
--- #--------------------------------------------------------------------------
type: struct
desc: "USM pool descriptor type"
class: $xUSM
name: $x_usm_pool_desc_t
base: $x_base_desc_t
members:
    - type: $x_usm_pool_flags_t
      name:  flags
      desc: "[in] memory allocation flags"
--- #--------------------------------------------------------------------------
type: struct
desc: "USM pool limits descriptor type"
details:
  - Specify these properties in $xUSMPoolCreate via $x_usm_pool_desc_t
    as part of a `pNext` chain.
class: $xUSM
name: $x_usm_pool_limits_desc_t
base: $x_base_desc_t
members:
    - type: "size_t"
      name:  maxPoolableSize
      desc: "[in] Allocations up to this limit will be subject to pooling"
    - type: "size_t"
      name:  minDriverAllocSize
      desc: "[in] Minimum allocation size that will be requested from the driver"
--- #--------------------------------------------------------------------------
type: function
desc: "USM allocate host memory"
class: $xUSM
name: HostAlloc
ordinal: "0"
details:
  - "If pUSMDesc is not NULL and pUSMDesc->pool is not NULL the allocation will be served from a specified memory pool."
  - "Otherwise, the behavior is implementation-defined."
  - "Allocations served from different memory pools must be isolated and must not reside on the same page."
  - "Any flags/hints passed through pUSMDesc only affect the single allocation."
  - "See also $x_usm_host_desc_t."
  - "See also $x_usm_alloc_location_desc_t."
params:
    - type: $x_context_handle_t
      name: hContext
      desc: "[in] handle of the context object"
    - type: const $x_usm_desc_t*
      name: pUSMDesc
      desc: "[in][optional] USM memory allocation descriptor"
    - type: $x_usm_pool_handle_t
      name: pool
      desc: "[in][optional] Pointer to a pool created using urUSMPoolCreate"
    - type: "size_t"
      name: size
      desc: "[in] minimum size in bytes of the USM memory object to be allocated"
    - type: void**
      name: ppMem
      desc: "[out] pointer to USM host memory object"
returns:
    - $X_RESULT_ERROR_INVALID_CONTEXT
    - $X_RESULT_ERROR_INVALID_OPERATION:
      - "If $X_DEVICE_INFO_USM_HOST_SUPPORT is false."
    - $X_RESULT_ERROR_INVALID_VALUE:
      - "`pUSMDesc && pUSMDesc->align != 0 && ((pUSMDesc->align & (pUSMDesc->align-1)) != 0)`" # alignment must be power of two
      - "If `align` is greater that the size of the largest data type supported by `hDevice`."
    - $X_RESULT_ERROR_INVALID_USM_SIZE:
      - "`size == 0`"
      - "`size` is greater than $X_DEVICE_INFO_MAX_MEM_ALLOC_SIZE."
    - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
    - $X_RESULT_ERROR_OUT_OF_RESOURCES
    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
        - "If any device associated with `hContext` reports `false` for $X_DEVICE_INFO_USM_POOL_SUPPORT"
--- #--------------------------------------------------------------------------
type: function
desc: "USM allocate device memory"
class: $xUSM
name: DeviceAlloc
ordinal: "0"
details:
  - "If pUSMDesc is not NULL and pUSMDesc->pool is not NULL the allocation will be served from a specified memory pool."
  - "Otherwise, the behavior is implementation-defined."
  - "Allocations served from different memory pools must be isolated and must not reside on the same page."
  - "Any flags/hints passed through pUSMDesc only affect the single allocation."
  - "See also $x_usm_device_desc_t."
  - "See also $x_usm_alloc_location_desc_t."
params:
    - type: $x_context_handle_t
      name: hContext
      desc: "[in] handle of the context object"
    - type: $x_device_handle_t
      name: hDevice
      desc: "[in] handle of the device object"
    - type: const $x_usm_desc_t*
      name: pUSMDesc
      desc: "[in][optional] USM memory allocation descriptor"
    - type: $x_usm_pool_handle_t
      name: pool
      desc: "[in][optional] Pointer to a pool created using urUSMPoolCreate"
    - type: "size_t"
      name: size
      desc: "[in] minimum size in bytes of the USM memory object to be allocated"
    - type: void**
      name: ppMem
      desc: "[out] pointer to USM device memory object"
returns:
    - $X_RESULT_ERROR_INVALID_CONTEXT
    - $X_RESULT_ERROR_INVALID_OPERATION:
      - "If $X_DEVICE_INFO_USM_HOST_SUPPORT is false."
    - $X_RESULT_ERROR_INVALID_VALUE:
      - "`pUSMDesc && pUSMDesc->align != 0 && ((pUSMDesc->align & (pUSMDesc->align-1)) != 0)`" # alignment must be power of two
      - "If `align` is greater that the size of the largest data type supported by `hDevice`."
    - $X_RESULT_ERROR_INVALID_USM_SIZE:
      - "`size == 0`"
      - "`size` is greater than $X_DEVICE_INFO_MAX_MEM_ALLOC_SIZE."
    - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
    - $X_RESULT_ERROR_OUT_OF_RESOURCES
    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
        - "If any device associated with `hContext` reports `false` for $X_DEVICE_INFO_USM_POOL_SUPPORT"
--- #--------------------------------------------------------------------------
type: function
desc: "USM allocate shared memory"
class: $xUSM
name: SharedAlloc
ordinal: "0"
details:
  - "If pUSMDesc is not NULL and pUSMDesc->pool is not NULL the allocation will be served from a specified memory pool."
  - "Otherwise, the behavior is implementation-defined."
  - "Allocations served from different memory pools must be isolated and must not reside on the same page."
  - "Any flags/hints passed through pUSMDesc only affect the single allocation."
  - "See also $x_usm_host_desc_t."
  - "See also $x_usm_device_desc_t."
  - "See also $x_usm_alloc_location_desc_t."
params:
    - type: $x_context_handle_t
      name: hContext
      desc: "[in] handle of the context object"
    - type: $x_device_handle_t
      name: hDevice
      desc: "[in] handle of the device object"
    - type: const $x_usm_desc_t*
      name: pUSMDesc
      desc: "[in][optional] Pointer to USM memory allocation descriptor."
    - type: $x_usm_pool_handle_t
      name: pool
      desc: "[in][optional] Pointer to a pool created using urUSMPoolCreate"
    - type: "size_t"
      name: size
      desc: "[in] minimum size in bytes of the USM memory object to be allocated"
    - type: void**
      name: ppMem
      desc: "[out] pointer to USM shared memory object"
returns:
    - $X_RESULT_ERROR_INVALID_CONTEXT
    - $X_RESULT_ERROR_INVALID_VALUE:
      - "`pUSMDesc && pUSMDesc->align != 0 && ((pUSMDesc->align & (pUSMDesc->align-1)) != 0)`" # alignment must be power of two
      - "If `align` is greater that the size of the largest data type supported by `hDevice`."
    - $X_RESULT_ERROR_INVALID_USM_SIZE:
      - "`size == 0`"
      - "`size` is greater than $X_DEVICE_INFO_MAX_MEM_ALLOC_SIZE."
    - $X_RESULT_ERROR_INVALID_OPERATION:
      - "If `UR_DEVICE_INFO_USM_SINGLE_SHARED_SUPPORT` and `UR_DEVICE_INFO_USM_CROSS_SHARED_SUPPORT` are both false."
    - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
    - $X_RESULT_ERROR_OUT_OF_RESOURCES
    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
        - "If any device associated with `hContext` reports `false` for $X_DEVICE_INFO_USM_POOL_SUPPORT"
--- #--------------------------------------------------------------------------
type: function
desc: "Free the USM memory object"
class: $xUSM
name: Free
ordinal: "0"
params:
    - type: $x_context_handle_t
      name: hContext
      desc: "[in] handle of the context object"
    - type: void*
      name: pMem
      desc: "[in] pointer to USM memory object"
returns:
    - $X_RESULT_ERROR_INVALID_MEM_OBJECT
    - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
--- #--------------------------------------------------------------------------
type: function
desc: "Get USM memory object allocation information"
class: $xUSM
name: GetMemAllocInfo
ordinal: "0"
params:
    - type: $x_context_handle_t
      name: hContext
      desc: "[in] handle of the context object"
    - type: "const void*"
      name: pMem
      desc: "[in] pointer to USM memory object"
    - type: $x_usm_alloc_info_t
      name: propName
      desc: "[in] the name of the USM allocation property to query"
    - type: size_t
      name: propSize
      desc: "[in] size in bytes of the USM allocation property value"
    - type: void*
      name: pPropValue
      desc: "[out][optional][typename(propName, propSize)] value of the USM allocation property"
    - type: size_t*
      name: pPropSizeRet
      desc: "[out][optional] bytes returned in USM allocation property"
returns:
    - $X_RESULT_ERROR_INVALID_CONTEXT
    - $X_RESULT_ERROR_INVALID_VALUE
    - $X_RESULT_ERROR_INVALID_MEM_OBJECT
    - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
--- #--------------------------------------------------------------------------
type: function
desc: "Create USM memory pool with desired properties."
class: $xUSM
name: PoolCreate
ordinal: "0"
details:
  - "UR can create multiple instances of the pool depending on allocation requests."
  - "See also $x_usm_pool_limits_desc_t."
params:
    - type: $x_context_handle_t
      name: hContext
      desc: "[in] handle of the context object"
    - type: $x_usm_pool_desc_t*
      name: pPoolDesc
      desc: "[in] pointer to USM pool descriptor. Can be chained with $x_usm_pool_limits_desc_t"
    - type: $x_usm_pool_handle_t*
      name: ppPool
      desc: "[out] pointer to USM memory pool"
returns:
    - $X_RESULT_ERROR_INVALID_NULL_HANDLE
    - $X_RESULT_ERROR_INVALID_VALUE
    - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
        - "If any device associated with `hContext` reports `false` for $X_DEVICE_INFO_USM_POOL_SUPPORT"
--- #--------------------------------------------------------------------------
type: function
desc: "Get a reference to the pool handle. Increment its reference count"
class: $xUSM
name: PoolRetain
ordinal: "0"
params:
    - type: $x_usm_pool_handle_t
      name: pPool
      desc: "[in][retain] pointer to USM memory pool"
returns:
    - $X_RESULT_ERROR_INVALID_NULL_HANDLE
    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE
--- #--------------------------------------------------------------------------
type: function
desc: "Decrement the pool's reference count and delete the pool if the reference count becomes zero."
class: $xUSM
name: PoolRelease
ordinal: "0"
details:
    - "All allocation belonging to the pool must be freed prior to the the
      reference count becoming zero."
    - "If the pool is deleted, this function returns all its reserved memory to the driver."
params:
    - type: $x_usm_pool_handle_t
      name: pPool
      desc: "[in][release] pointer to USM memory pool"
returns:
    - $X_RESULT_ERROR_INVALID_NULL_HANDLE
    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE
--- #--------------------------------------------------------------------------
type: enum
desc: "Get USM memory pool information"
class: $xUSM
name: $x_usm_pool_info_t
typed_etors: True
etors:
    - name: REFERENCE_COUNT
      desc: |
            [uint32_t] Reference count of the pool object.
            The reference count returned should be considered immediately stale.
            It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
    - name: CONTEXT
      desc: "[$x_context_handle_t] USM memory pool context info"
--- #--------------------------------------------------------------------------
type: function
desc: "Query information about a USM memory pool"
class: $xUSM
name: PoolGetInfo
ordinal: "0"
params:
    - type: $x_usm_pool_handle_t
      name: hPool
      desc: "[in] handle of the USM memory pool"
    - type: "$x_usm_pool_info_t"
      name: propName
      desc: "[in] name of the pool property to query"
    - type: "size_t"
      name: propSize
      desc: "[in] size in bytes of the pool property value provided"
    - type: "void*"
      name: pPropValue
      desc: "[out][optional][typename(propName, propSize)] value of the pool property"
    - type: "size_t*"
      name: pPropSizeRet
      desc: "[out][optional] size in bytes returned in pool property value"
returns:
    - $X_RESULT_ERROR_UNSUPPORTED_ENUMERATION:
        - "If `propName` is not supported by the adapter."
    - $X_RESULT_ERROR_INVALID_SIZE:
        - "`propSize == 0 && pPropValue != NULL`"
        - "If `propSize` is less than the real number of bytes needed to return the info."
    - $X_RESULT_ERROR_INVALID_NULL_POINTER:
        - "`propSize != 0 && pPropValue == NULL`"
        - "`pPropValue == NULL && pPropSizeRet == NULL`"
    - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
    - $X_RESULT_ERROR_OUT_OF_RESOURCES
    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE