numba_dpex.utils package

Submodules

• numba_dpex.utils.array_utils module
• numba_dpex.utils.constants module
• numba_dpex.utils.llvm_codegen_helpers module
• numba_dpex.utils.messages module
• numba_dpex.utils.misc module
• numba_dpex.utils.type_conversion_fns module

Module contents

Various utility functions and classes to aid LLVM IR building.

exception numba_dpex.utils.IndeterminateExecutionQueueError

Bases: Exception

class numba_dpex.utils.LLVMTypes

Bases: object

A helper class to get LLVM Values for integer C types.

byte_ptr_ptr_t = <<class 'llvmlite.ir.types.PointerType'> i8**>

byte_ptr_t = <<class 'llvmlite.ir.types.PointerType'> i8*>

byte_t = <<class 'llvmlite.ir.types.IntType'> i8>

int32_ptr_t = <<class 'llvmlite.ir.types.PointerType'> i32*>

int32_t = <<class 'llvmlite.ir.types.IntType'> i32>

int64_ptr_t = <<class 'llvmlite.ir.types.PointerType'> i64*>

int64_t = <<class 'llvmlite.ir.types.IntType'> i64>

void_t = <<class 'llvmlite.ir.types.VoidType'> void>

class numba_dpex.utils.address_space

Bases: object

Supported address space values.

Address space	Value
PRIVATE	0
GLOBAL	1
CONSTANT	2
LOCAL	3
GENERIC	4

CONSTANT = 2

GENERIC = 4

GLOBAL = 1

LOCAL = 3

PRIVATE = 0

numba_dpex.utils.as_usm_obj(obj, queue=None, usm_type='shared', copy=True)

Determine and return a SYCL device accesible object.

We try to determine if the provided object defines a valid __sycl_usm_array_interface__ dictionary. If not, we create a USM memory of usm_type and try to copy the data obj holds. Only numpy.ndarray is supported currently as obj if the object is not already allocated using USM.

Args:

obj: Object to be tested and data copied from. usm_type: USM type used in case obj is not already allocated using USM. queue (dpctl.SyclQueue): SYCL queue to be used to allocate USM

memory in case obj is not already USM allocated.

copy (bool): Flag to determine if we copy data from obj.

Returns:

A Python object allocated using USM memory.

Raises:

TypeError:

1. If obj is not allocated on USM memory or is not of type numpy.ndarray, TypeError is raised.

2. If queue is not of type dpctl.SyclQueue.

ValueError:

1. In case obj is not USM allocated, users need to pass the SYCL queue to be used for creating new memory. ValuieError is raised if queue argument is not provided.

2. If usm_type is not valid.

3. If dtype of the passed ndarray(obj) is not supported.

numba_dpex.utils.assert_no_return(rettype)

Make sure the type of return is void/None.

@dppy.kernel does not allow users to return any value and this function raises TypeError when users do return something.

Args:

rettype: Numba type representing the return value.

Raises:

TypeError: Only None and types.void is allowed. In case

of any other type TypeError is raised.

class numba_dpex.utils.calling_conv

Bases: object

CC_SPIR_FUNC = 'spir_func'

CC_SPIR_KERNEL = 'spir_kernel'

numba_dpex.utils.copy_from_numpy_to_usm_obj(usm_allocated, obj)

Copy from supported objects to USM allocated data.

This function copies the data of a supported Python type (only numpy.ndarray is supported at this point) into object that defines a __sycl_usm_array_interface__ attribute. For more information please refer to the specification of __sycl_usm_array_interface__: https://github.com/IntelPython/dpctl/wiki/Zero-copy-data-exchange-using-SYCL-USM#sycl-usm-array-interface

Args:

usm_allocated: An object that should define a

__sycl_usm_array_interface__ dictionary. A TypeError is thrown if the object does not have such an attribute.

obj (numpy.ndarray): Numpy ndarray, the data will be copied into.

Raises:

TypeError: If any argument is not of permitted type. ValueError:

1. If size of data does not match.

2. If obj is not C-contiguous.

numba_dpex.utils.copy_to_numpy_from_usm_obj(usm_allocated, obj)

Copy from USM allocated data to supported objects.

Args:

usm_allocated: An object that should define a

__sycl_usm_array_interface__ dictionary. A TypeError is thrown if the object does not have such an attribute.

obj (numpy.ndarray): Numpy ndarray, the data will be copied into.

Raises:

TypeError: If any argument is not of permitted type. ValueError: If size of data does not match.

numba_dpex.utils.create_null_ptr(builder, context)

Allocates a new LLVM Value storing a void* and returns the Value to caller.

Args:

builder: The LLVM IR builder to be used for code generation. context: The LLVM IR builder context.

Returns: An LLVM value storing a null pointer

numba_dpex.utils.get_info_from_suai(obj)

Convenience function to gather information from __sycl_usm_array_interface__.

Args:

obj: Array with SUAI attribute.

Returns:

usm_mem: USM memory object. total_size: Total number of items in the array. shape: Shape of the array. ndim: Total number of dimensions. itemsize: Size of each item. strides: Stride of the array. dtype: Dtype of the array.

numba_dpex.utils.get_llvm_ptr_type(type)

Returns an LLVM pointer type for a give LLVM type object.

Args:

type: An LLVM type for which we need the corresponding pointer type.

Returns: An LLVM pointer type object corresponding to the input LLVM type.

numba_dpex.utils.get_llvm_type(context, type)

Returns the LLVM Value corresponsing to a Numba type.

Args:

context: The LLVM context or the execution state of the current IR

generator.

type: A Numba type object.

Returns: An Python object wrapping an LLVM Value corresponding to the

specified Numba type.

numba_dpex.utils.get_one(context)

Returns an LLVM Constant storing a 64 bit representation for one.

Args:

context: The LLVM IR builder context.

Returns: An LLVM Contant Value storing one.

numba_dpex.utils.get_zero(context)

Returns an LLVM Constant storing a 64 bit representation for zero.

Args:

context: The LLVM IR builder context.

Returns: An LLVM Contant Value storing zero.

numba_dpex.utils.has_usm_memory(obj)

Determine and return a SYCL device accesible object.

as_usm_memory() converts Python object with __sycl_usm_array_interface__ property to one of MemoryUSMShared, MemoryUSMDevice, or MemoryUSMHost instances. For more information please refer: https://github.com/IntelPython/dpctl/blob/0.8.0/dpctl/memory/_memory.pyx#L673

Args:

obj: Object to be tested and data copied from.

Returns:

A Python object allocated using USM memory if argument is already allocated using USM (zero-copy), None otherwise.

numba_dpex.utils.npytypes_array_to_dppy_array(arrtype, addrspace=1)

Convert Numba’s Array type to numba_dpex’s DPPYArray type.

Numba’s Array type does not have a notion of address space for the data pointer. numba_dpex defines its own array type, DPPYArray, that is similar to Numba’s Array, but the data pointer has an associated address space. In addition, the meminfo and the parent attributes of Array are stored as CPointer types instead of PyObject. The converter function converts the Numba Array type to DPPYArray type with address space of pointer members typed to the specified address space.

Args:

arrtype (numba.types): A numba data type that should be

numba.types.Array.

specified: Defaults to numba_dpex.utils.address_space.GLOBAL.

The SPIR-V address space to which the data pointer of the array belongs.

Returns: The numba_dpex data type corresponding to the input numba type.

Raises:

NotImplementedError: If the input numba type is not

numba.types.Array

numba_dpex.utils.suai_to_dppy_array_type(arr, addrspace=1)

Create type for Array with __sycl_usm_array_interface__ (SUAI) attribute.

This function cretes a Numba type for arrays with SUAI attribute.

Args:

arr: Array with SUAI attribute. addrspace: Address space this array is allocated in.

Returns: The Numba type for SUAI array.

Raises:

NotImplementedError: If the dtype of the passed array is not supported.