Internal API

Internal Types

group nomp_internal_types

Internal types (structures and enums) used by libnomp.

Enums

enum nomp_log_type_t

Defines nomp log levels. A log can be an error, warning or general information.

Values:

enumerator NOMP_ERROR

Error type.

enumerator NOMP_WARNING

Warning type.

enumerator NOMP_INFO

Information type.

struct nomp_config_t

#include <nomp-impl.h>

Structure to keep track of nomp runtime configuration.

Public Members

int platform

ID of the platform to be used for the backend. This is only used when the backend is OpenCL.

int device

ID of the device to be used with the backend.

int verbose

Verbose level to be used for displaying log messages.

int profile

Turn profiling on or off.

char backend[NOMP_MAX_BUFFER_SIZE + 1]

Name of the backend to be used (OpenCL, CUDA, etc.).

char install_dir[PATH_MAX + 1]

Installed directory of the library.

char scripts_dir[PATH_MAX + 1]

Directory where transform and annotations scripts are located.

char annotations_script[NOMP_MAX_BUFFER_SIZE + 1]

Name of the annotation script.

struct nomp_arg_t

#include <nomp-impl.h>

Structure to keep track of arguments (variables) of a nomp program (nomp_prog_t).

Public Members

char name[NOMP_MAX_BUFFER_SIZE + 1]

Name of the argument (respective variable name in C).

size_t size

Size of the argument given by sizeof() operator.

nomp_arg_type_t type

Type of the argument (one of nomp_arg_type_t).

void *ptr

Pointer to the argument.

struct nomp_prog_t

#include <nomp-impl.h>

Structure to keep track of nomp program.

Public Members

unsigned nargs

Number of arguments of the kernel.

nomp_arg_t *args

Pointer to the arguments of the kernel.

unsigned ndim

Dimension of kernel launch parameters.

CVecBasic *sym_global

SymEngine expressions of kernel launch parameters as a vector.

int eval_grid

Flag used to determine if the grid size should be evaluated or not.

CMapBasicBasic *map

Map of variable names and their values used to evaluate the kernel launch parameters.

size_t global[3]

Evaluated value of kernel launch parameters (re-evaluated if the input changes).

void *bptr

Pointer to keep track of backend specific data for the active backend.

int reduction_index

Index of the reduction argument if one exists.

nomp_reduction_op_t reduction_op

Reduction operation to be performed.

nomp_arg_type_t reduction_type

Type of the reduction variable.

int reduction_size

Size of the reduction variable given by sizeof().

void *reduction_ptr

Pointer to the reduction variable.

PyObject *py_dict

Dictionary to hold jit argument names and values.

struct nomp_mem_t

#include <nomp-impl.h>

Structure to keep track of memory allocated by the backend.

Public Members

size_t idx0

Start index of the memory region.

size_t idx1

End index of the memory region.

size_t usize

Size of a single unit of memory type given by sizeof().

void *hptr

Host pointer of the memory region.

void *bptr

Device pointer allocated by the backend for the memory region.

size_t bsize

Size of the bptr given by sizeof().

struct nomp_backend

#include <nomp-impl.h>

Structure to keep track of nomp runtime data and backend specific data. This structure is also used to dispatch backend specific functions.

Public Members

int (*update)(struct nomp_backend*, nomp_mem_t*, const nomp_map_direction_t op, size_t start, size_t end, size_t usize)

Function pointer to the backend update function which can allocate, update and free backend memory.

int (*knl_build)(struct nomp_backend*, nomp_prog_t*, const char*, const char*)

Function pointer to the backend kernel build function.

int (*knl_run)(struct nomp_backend*, nomp_prog_t*)

Function pointer to the backend kernel run function.

int (*knl_free)(nomp_prog_t*)

Function pointer to the backend kernel free function.

int (*sync)(struct nomp_backend*)

Function pointer to the backend synchronization function.

int (*finalize)(struct nomp_backend*)

Function pointer to the backend finalize function which releases allocated resources.

nomp_mem_t scratch

Scratch memory to be used as temporary memory for kernels (like reductions)

PyObject *py_annotate

Python function object which will be called to perform annotations.

PyObject *py_context

Context info is used to pass necessary information to kernel transformations and annotations.

void *bptr

Pointer to keep track of backend specific data. This is allocated and released by the backend.

Internal Macros

group nomp_internal_macros

Internal macros used in libnomp.

Defines

NOMP_UNUSED(x)

Macro to mark unused variables. Used to avoid -Wunused-variable warning. This is required since some backend functions may not use all the arguments defined in the function signature.

nomp_check(err)

Check if nomp API return value is an error. In case of an error, non-zero error code is returned to the user. Otherwise, the return value is zero.

Parameters

• err – [in] Return value from nomp API.

Memory Management Functions and Macros

group nomp_mem_utils

Defines

nomp_free(p)

Helper macro for deallocating or freeing a memory block using nomp_free_(). File name and line number are passed implicitly.

Parameters

• p – Address of the pointer to the memory to deallocate.

Returns

void

nomp_calloc(T, count)

Helper macro for allocating an array in memory with elements initialized to 0 using nomp_calloc_(). File name and line number are passed implicitly.

Parameters

• T – Type of element.

• count – Number of elements.

Returns

Pointer of type T.

nomp_realloc(ptr, T, count)

Helper macro for reallocating memory blocks using nomp_realloc_(). File name and line number are passed implicitly.

Parameters

• ptr – Pointer to the memory area to be reallocated.

• T – Type of element.

• count – Number of elements.

Returns

Pointer of type T

Functions

static inline nomp_mem_t *nomp_get_memory_if_mapped(void *p)

Returns the nomp_mem object corresponding to host pointer p.

Returns the nomp_mem object corresponding to host ponter p. If no buffer has been allocated for p on the device, returns NULL.

Parameters

p – [in] Host pointer

Returns

nomp_mem_t *

Backend Initialization Functions

group nomp_backend_init

Functions for initializing different backend as OpenCL, CUDA, etc. These have to be refactored to handle the case when the backend is not available.

Functions

int opencl_init(nomp_backend_t *bnd, const int platform_id, const int device_id)

Initializes OpenCL backend with the specified platform and device.

Initializes OpenCL backend while creating a command queue using the given platform id and device id. Returns a negative value if an error occurred during the initialization, otherwise returns 0.

Parameters

• bnd – [in] Target backend for code generation.

• platform_id – [in] Target platform id.

• device_id – [in] Target device id.

Returns

int

Python Helper Functions

group nomp_py_utils

Python helper functions for calling loopy and other python functions.

Functions

int nomp_py_init(const nomp_config_t *const cfg)

Initialize the nomp python interface.

Parameters

cfg – [in] Nomp configuration struct of type nomp_config_t.

Returns

int

int nomp_py_append_to_sys_path(const char *path)

Appends specified path to system path.

Parameters

path – [in] Path to be appended to system path.

Returns

int

int nomp_py_c_to_loopy(PyObject **kernel, const char *src)

Creates loopy kernel from C source.

Parameters

• kernel – [out] Loopy Kernel object.

• src – [in] C kernel source.

Returns

int

int nomp_py_realize_reduction(PyObject **kernel, const char *const variable, const PyObject *const py_context)

Realize reductions if one is present in the kernel.

Parameters

• kernel – [inout] Loopy kernel object.

• variable – [in] Name of the reduction variable as a C-string.

• py_context – [in] Python dictionary with context information.

Returns

int

int nomp_py_transform(PyObject **kernel, const char *const file, const char *function, const PyObject *const context)

Apply kernel specific user transformations on a loopy kernel.

Call the user transform function function in file file on the loopy kernel kernel. kernel will be modified based on the transformations. Python file (module) must reside on nomp scripts directory which is set using --nomp-scripts-dir option or environment variable NOMP_SCRIPTS_DIR. Function will return a non-zero value if there was an error. Non-zero return value can be used to query the error code using nomp_get_err_no() and error message using nomp_get_err_str().

Parameters

• kernel – [inout] Pointer to loopy kernel object.

• file – [in] Name of the file containing transform function function.

• function – [in] Name of the transform function.

• context – [in] Context (as a Python dictionary) to pass around information such as backend, device details, etc.

Returns

int

int nomp_py_get_knl_name_and_src(char **name, char **src, const PyObject *kernel)

Get kernel name and generated source for the backend.

Parameters

• name – [out] Kernel name as a C-string.

• src – [out] Kernel source as a C-string.

• kernel – [in] Loopy kernel object.

Returns

int

int nomp_py_set_annotate_func(PyObject **annotate_func, const char *file)

Set the annotate function based on the path to annotation script and function.

Parameters

• annotate_func – [out] Pointer to the annotate function.

• file – [in] Name of the annotation script.

Returns

int

int nomp_py_annotate(PyObject **kernel, PyObject *const function, const PyObject *const annotations, const PyObject *const context)

Apply transformations on a loopy kernel based on annotations.

Apply the transformations to the loopy kernel kernel based on the annotation function function and the key value pairs (annotations) passed in annotations. kernel will be modified based on the transformations.

Parameters

• kernel – [inout] Pointer to loopy kernel object.

• function – [in] Function which performs transformations based on annotations.

• annotations – [in] Annotations (as a PyDict) to specify which transformations to apply.

• context – [in] Context (as a PyDict) to pass around information such as backend, device details, etc.

Returns

int

int nomp_py_get_grid_size(nomp_prog_t *prg, PyObject *kernel)

Get global and local grid sizes as pymoblic expressions.

Grid sizes are stored in the program object itself.

Parameters

• prg – [in] Nomp program object.

• kernel – [in] Python kernel object.

Returns

int

int nomp_py_fix_parameters(PyObject **kernel, const PyObject *py_dict)

Fix the arguments which were marked as jit in the kernel.

Parameters

• kernel – [inout] Python kernel object.

• py_dict – [in] Dictionary containing jit argument names and values.

Returns

int

int nomp_py_finalize(int interpreter)

Finalize the nomp python interface.

Parameters

interpreter – [in] If true, finalize the python interpreter.

Returns

int

int nomp_symengine_update(CMapBasicBasic *map, const char *key, const long val)

Map the keys and values to evaluate the kernel launch parameters.

Parameters

• map – [in] SymEngine object map.

• key – [in] Key as a C-string.

• val – [in] Value as a C-string.

Returns

int

int nomp_symengine_eval_grid_size(nomp_prog_t *prg)

Evaluate global and local grid sizes based on the dictionary dict.

Parameters

prg – [in] Nomp program.

Returns

int

Reductions and Related Functions

group nomp_reduction_utils

Utilities used to perform reduction operations.

Enums

enum nomp_reduction_op_t

Enum for different reduction operations.

Values:

enumerator NOMP_SUM

Sum reduction.

enumerator NOMP_PROD

Multiplication reduction.

Functions

int nomp_host_side_reduction(nomp_backend_t *backend, nomp_prog_t *prg, nomp_mem_t *m)

Perform host side reduction.

Perform residual host side reductions.

Parameters

• backend – [in] Active backend instance.

• prg – [in] Active program instance.

• m – [in] Memory used to store device side partial reductions.

Returns

int

Logging Functions

group nomp_log_utils

Internal functions used for logging.

Defines

nomp_log(errorno, type, ...)

Log an error, warning or an info message. Use this instead of using the nomp_log_() function directly.

Parameters

• errorno – Error number (One of Error codes returned to the user. used only when type is an error).

• type – Log type one of nomp_log_type_t.

• ... – Log message as a C-string followed by arguments.

Functions

int nomp_log_set_verbose(const unsigned verbose_in)

Set the verbose level for the log functions.

Parameters

verbose_in – [in] Verbose level provided by the user.

Returns

int

int nomp_log_(const char *description, int errorno, nomp_log_type_t type, ...)

Register a log with libnomp runtime.

Register a log given a description of the log, error number and log type. This function returns a unique id if the log type is an error and this can be used to query the error log. If the log type is an information or a warning, nomp_log() returns 0 and description is printed to stdout based on the verbose level (which is set by either &#8212;nomp-verbose command line argument or NOMP_VERBOSE environment variable) and not recorded by the libnomp runtime. Also, the errorno is ignored if the log type is not an error. On failure, nomp_log_() returns -1. Use nomp_log() macro without calling this function directly.

Parameters

• description – [in] Detailed description of the log.

• errorno – [in] Log number which is defined in nomp.h

• type – [in] Type of the log (one of nomp_log_type_t)

Returns

int

void nomp_log_finalize(void)

Free variables used to keep track of logs.

Returns

void

Profiling Functions

group nomp_profiler_utils

Internal functions for profiling.

Functions

int nomp_profile_set_level(const int profile_level_in)

Set the profile level for the nomp profiler.

Parameters

profile_level_in – [in] Profile level provided by the user.

Returns

int

void nomp_profile(const char *name, const int toggle, const int sync)

Toggles the timer and records the execution time between the two consecutive uses of the function.

The function either starts or ends the timer by considering the toggle value. The function will start the timer if the toggle is 1. Else, it will capture the execution time and records in a log.

nomp_profile("Entry Name", 1, nomp.profile, 1);
// Code to be measured
nomp_profile("Entry Name", 0, nomp.profile, 1);

Parameters

• name – [in] Name of the execution time that is being profiled.

• toggle – [in] Toggles the timer between tick (start of timing) and a tock (end of timing).

• sync – [in] Execute nomp_sync when toggling off the timer.

Returns

void

void nomp_profile_result(void)

Prints all the execution times recorded by the program. This function is executed only when the --nomp-profile is provided.

Returns

int

void nomp_profile_finalize(void)

Free variables used to keep track of time logs.

Returns

void

Other helper Functions

group nomp_other_utils

Various helper functions used internally by libnomp core library.

Functions

char *nomp_str_cat(unsigned n, unsigned max_len, ...)

Concatenates n strings.

Concatenates n strings and returns a pointer to the resulting string. Each string should be at most max_len length long. User has to free memory allocated for the resulting string using nomp_free().

Parameters

• n – [in] Number of strings to concatenate.

• max_len – [in] Maximum length of an individual string.

• ... – [in] Strings to concatenate.

Returns

char*

int nomp_str_toui(const char *str, size_t size)

Try to convert input string str to an non-negative integer value.

Convert input string str to an non-negative int value. Returns converted non-negative int value if successful, otherwise return -1. size denotes the maximum length of the string str.

Parameters

• str – [in] String to convert into unsigned int.

• size – [in] Length of the string.

Returns

int

int nomp_max(unsigned n, ...)

Returns the maximum among all integers passed.

Returns the maximum between n integers.

Parameters

• n – [in] Total number of integers.

• ... – [in] List of integers.

Returns

int

char *nomp_copy_env(const char *name, size_t size)

Get a copy of the environment variable value if it exists.

Get a copy of the value of the environment variable name as a string if it is defined. Return NULL if the environment variable is not set. size is the maximum length of the string. User must free the memory allocated for the resulting string using nomp_free().

Parameters

• name – [in] Name of the environment variable.

• size – [in] Maximum length of the environment variable value.

Returns

char *

int nomp_path_len(size_t *len, const char *path)

Returns the length of a posix complaint path.

If len is not NULL, it is set to the length of the path if the path length resolution was successful. Otherwise, it is set to zero. On success, the function returns zero. Otherwise, it returns an error id which can be used to query the error id and string using nomp_get_err_str() and nomp_get_err_no().

Parameters

• len – [out] Lenth of path specified in path.

• path – [in] Path to get the maximum length.

Returns

int

int nomp_py_check_module(const char *module, const char *function)

Check if the given python module and function exist.

Check if there is python function function exist in the python module module. Returns 0 if both module and function exist, otherwise returns an error id which can beused to query the error id and string using nomp_get_err_str() and nomp_get_err_no(). The module should be provided without the “.py” extension.

Parameters

• module – [in] Python module name without the “.py” extension.

• function – [in] Python function name.

Returns

int