liblarod  @VERSION_STR@
Data Structures | Macros | Typedefs | Enumerations | Functions
larod.h File Reference

Main larod header file. More...

#include <limits.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include "larod-version.h"
Include dependency graph for larod.h:

Go to the source code of this file.

Data Structures

struct  larodError
 Type containing error information. More...
 
struct  larodTensorDims
 A type containing information about a tensor's dimensions. More...
 
struct  larodTensorPitches
 A type containing information about a tensor's pitches. More...
 

Macros

#define LAROD_TENSOR_MAX_LEN   12
 Maximum number of dimensions of a larodTensor.
 
#define LAROD_INVALID_MODEL_ID   UINT64_MAX
 Macro for invalid model ID.
 
#define LAROD_INVALID_FD   (INT_MIN)
 Macro for invalid tensor file descriptor.
 
#define LAROD_FD_PROP_READWRITE   (1UL << 0)
 The Linux read/write syscalls can be performed on the fd.
 
#define LAROD_FD_PROP_MAP   (1UL << 1)
 The Linux mmap syscall can be performed on the fd.
 
#define LAROD_FD_PROP_DMABUF   (1UL << 2)
 The fd represents a Linux (kernel) struct dma_buf.
 

Typedefs

typedef struct larodModel larodModel
 A type representing a model. More...
 
typedef void(* larodLoadModelCallback) (larodModel *model, void *userData, larodError *error)
 Callback used in larodLoadModelAsync(). More...
 
typedef void(* larodRunJobCallback) (void *userData, larodError *error)
 Callback used in larodRunJobAsync(). More...
 
typedef struct larodConnection larodConnection
 Connection handle type for the larod service. More...
 
typedef struct larodJobRequest larodJobRequest
 Type describing a job request. More...
 
typedef struct larodTensor larodTensor
 A type representing a tensor. More...
 
typedef struct larodMap larodMap
 A type containing key-value pairs. More...
 
typedef void(* larodRunInferenceCallback) (void *userData, larodError *error)
 Callback used in larodRunInferenceAsync(). More...
 
typedef struct larodJobRequest larodInferenceRequest
 Type describing a job request. More...
 

Enumerations

enum  larodChip
 Enum type with supported chips. More...
 
enum  larodAccess
 Enum type for specifying access. More...
 
enum  larodErrorCode
 Enum type for error codes. More...
 
enum  larodTensorDataType
 Enum type for specifying tensor data type. More...
 
enum  larodTensorLayout
 Enum type for specifying tensor layout. More...
 

Functions

void larodClearError (larodError **error)
 Deallocate an error handle. More...
 
bool larodConnect (larodConnection **conn, larodError **error)
 Connect to larod. More...
 
bool larodDisconnect (larodConnection **conn, larodError **error)
 Disconnect from larod. More...
 
bool larodGetNumSessions (larodConnection *conn, uint64_t *numSessions, larodError **error)
 Get number of currently active sessions in larod. More...
 
const char * larodGetChipName (const larodChip chip)
 Get name of a chip. More...
 
bool larodListChips (larodConnection *conn, larodChip **chips, size_t *numChips, larodError **error)
 List available chips. More...
 
larodModellarodLoadModel (larodConnection *conn, const int fd, const larodChip chip, const larodAccess access, const char *name, const larodMap *params, larodError **error)
 Load a new model. More...
 
bool larodLoadModelAsync (larodConnection *conn, const int fd, const larodChip chip, const larodAccess access, const char *name, const larodMap *params, larodLoadModelCallback callback, void *userData, larodError **error)
 Load a new model asynchronously. More...
 
larodModellarodGetModel (larodConnection *conn, const uint64_t modelId, larodError **error)
 Get handle to a model by model ID. More...
 
larodModel ** larodGetModels (larodConnection *conn, size_t *numModels, larodError **error)
 Get all loaded models. More...
 
void larodDestroyModel (larodModel **model)
 Free an allocated larodModel handle. More...
 
void larodDestroyModels (larodModel ***models, size_t numModels)
 Destroy a list of model objects. More...
 
bool larodDeleteModel (larodConnection *conn, larodModel *model, larodError **error)
 Delete a loaded model. More...
 
uint64_t larodGetModelId (const larodModel *model, larodError **error)
 Get model ID. More...
 
larodChip larodGetModelChip (const larodModel *model, larodError **error)
 Get chip for a model. More...
 
size_t larodGetModelSize (const larodModel *model, larodError **error)
 Get model size. More...
 
const char * larodGetModelName (const larodModel *model, larodError **error)
 Get model name. More...
 
larodAccess larodGetModelAccess (const larodModel *model, larodError **error)
 Get model access mode. More...
 
size_t larodGetModelNumInputs (const larodModel *model, larodError **error)
 Get number of input tensors for a model. More...
 
size_t larodGetModelNumOutputs (const larodModel *model, larodError **error)
 Get number of output tensors for a model. More...
 
size_t * larodGetModelInputByteSizes (const larodModel *model, size_t *numInputs, larodError **error)
 Get input tensor byte sizes for a model. More...
 
size_t * larodGetModelOutputByteSizes (const larodModel *model, size_t *numOutputs, larodError **error)
 Get output tensor byte sizes for a model. More...
 
larodTensor ** larodCreateModelInputs (const larodModel *model, size_t *numTensors, larodError **error)
 Create input tensors from a model. More...
 
larodTensor ** larodCreateModelOutputs (const larodModel *model, size_t *numTensors, larodError **error)
 Create output tensors from a model. More...
 
larodTensor ** larodAllocModelInputs (larodConnection *conn, const larodModel *model, const uint32_t fdPropFlags, size_t *numTensors, larodMap *params, larodError **error)
 Create and allocate input tensors from a model. More...
 
larodTensor ** larodAllocModelOutputs (larodConnection *conn, const larodModel *model, const uint32_t fdPropFlags, size_t *numTensors, larodMap *params, larodError **error)
 Create and allocate output tensors from a model. More...
 
larodTensor ** larodCreateTensors (size_t numTensors, larodError **error)
 Create a list of empty larodTensor handles. More...
 
void larodDestroyTensors (larodTensor ***tensors, size_t numTensors)
 Destroy a list of larodTensor. More...
 
bool larodSetTensorDims (larodTensor *tensor, const larodTensorDims *dims, larodError **error)
 Set the dimensions of a tensor. More...
 
const larodTensorDimslarodGetTensorDims (const larodTensor *tensor, larodError **error)
 Get dimensions of a tensor. More...
 
bool larodSetTensorPitches (larodTensor *tensor, const larodTensorPitches *pitches, larodError **error)
 Set pitches of a tensor. More...
 
const larodTensorPitcheslarodGetTensorPitches (const larodTensor *tensor, larodError **error)
 Get pitches of a tensor. More...
 
bool larodSetTensorDataType (larodTensor *tensor, const larodTensorDataType dataType, larodError **error)
 Set data type of a tensor. More...
 
larodTensorDataType larodGetTensorDataType (const larodTensor *tensor, larodError **error)
 Get data type of a tensor. More...
 
bool larodSetTensorLayout (larodTensor *tensor, const larodTensorLayout layout, larodError **error)
 Set layout of a tensor. More...
 
larodTensorLayout larodGetTensorLayout (const larodTensor *tensor, larodError **error)
 Get layout of a tensor. More...
 
bool larodSetTensorFd (larodTensor *tensor, const int fd, larodError **error)
 Set file descriptor of a tensor. More...
 
int larodGetTensorFd (const larodTensor *tensor, larodError **error)
 Get file descriptor of a tensor. More...
 
bool larodSetTensorFdSize (larodTensor *tensor, const size_t size, larodError **error)
 Set file descriptor maximum capacity (bytes) for a tensor. More...
 
bool larodGetTensorFdSize (const larodTensor *tensor, size_t *size, larodError **error)
 Get file descriptor maximum capacity (bytes) for a tensor. More...
 
bool larodSetTensorFdOffset (larodTensor *tensor, const int64_t offset, larodError **error)
 Set file offset for a tensor. More...
 
int64_t larodGetTensorFdOffset (const larodTensor *tensor, larodError **error)
 Get file offset for a tensor. More...
 
bool larodTrackTensor (larodConnection *conn, larodTensor *tensor, larodError **error)
 Start tracking a tensor in the service. More...
 
bool larodSetTensorFdProps (larodTensor *tensor, const uint32_t fdPropFlags, larodError **error)
 Set the properties for a file descriptor of a tensor. More...
 
bool larodGetTensorFdProps (const larodTensor *tensor, uint32_t *fdPropFlags, larodError **error)
 Get the properties of a file descriptor of a tensor. More...
 
const char * larodGetTensorName (const larodTensor *tensor, larodError **error)
 Get name of tensor. More...
 
larodMaplarodCreateMap (larodError **error)
 Create new larodMap. More...
 
void larodDestroyMap (larodMap **map)
 Destroy a larodMap. More...
 
bool larodMapSetStr (larodMap *map, const char *key, const char *value, larodError **error)
 Add a string to a larodMap object. More...
 
bool larodMapSetInt (larodMap *map, const char *key, const int64_t value, larodError **error)
 Add an integer to a larodMap object. More...
 
bool larodMapSetIntArr2 (larodMap *map, const char *key, const int64_t value0, const int64_t value1, larodError **error)
 Add an integer array of two elements to a larodMap object. More...
 
bool larodMapSetIntArr4 (larodMap *map, const char *key, const int64_t value0, const int64_t value1, const int64_t value2, const int64_t value3, larodError **error)
 Add an integer array of four elements to a larodMap object. More...
 
const char * larodMapGetStr (larodMap *map, const char *key, larodError **error)
 Get string type value tied to given key. More...
 
bool larodMapGetInt (larodMap *map, const char *key, int64_t *value, larodError **error)
 Get an integer type value tied to given key. More...
 
const int64_t * larodMapGetIntArr2 (larodMap *map, const char *key, larodError **error)
 Get an integer array of two elements tied to given key. More...
 
const int64_t * larodMapGetIntArr4 (larodMap *map, const char *key, larodError **error)
 Get an integer array of four elements tied to given key. More...
 
larodJobRequestlarodCreateJobRequest (const larodModel *model, larodTensor **inputTensors, size_t numInputs, larodTensor **outputTensors, size_t numOutputs, larodMap *params, larodError **error)
 Create and initialize a job request handle. More...
 
void larodDestroyJobRequest (larodJobRequest **jobReq)
 Destroy a request handle. More...
 
bool larodSetJobRequestModel (larodJobRequest *jobReq, const larodModel *model, larodError **error)
 Set model in a request. More...
 
bool larodSetJobRequestInputs (larodJobRequest *jobReq, larodTensor **tensors, const size_t numTensors, larodError **error)
 Set input tensor array in a request. More...
 
bool larodSetJobRequestOutputs (larodJobRequest *jobReq, larodTensor **tensors, const size_t numTensors, larodError **error)
 Set output tensor array in a job request. More...
 
bool larodSetJobRequestPriority (larodJobRequest *jobReq, const uint8_t priority, larodError **error)
 Set an priority of a job request. More...
 
bool larodSetJobRequestParams (larodJobRequest *jobReq, const larodMap *params, larodError **error)
 Set additional parameters to a job request. More...
 
bool larodRunJob (larodConnection *conn, const larodJobRequest *jobReq, larodError **error)
 Run a job on a loaded model. More...
 
bool larodRunJobAsync (larodConnection *conn, const larodJobRequest *jobReq, larodRunJobCallback callback, void *userData, larodError **error)
 Run a job on a loaded model asynchronously. More...
 
larodModellarodLoadModel (larodConnection *conn, const int fd, const larodAccess access, const char *name, larodError **error)
 Load a new model to current chip. More...
 
bool larodLoadModelAsync (larodConnection *conn, const int fd, const larodAccess access, const char *name, larodLoadModelCallback callback, void *userData, larodError **error)
 Load a new model to current chip asynchronously. More...
 
larodInferenceRequestlarodCreateInferenceRequest (const larodModel *model, larodTensor **inputTensors, size_t numInputs, larodTensor **outputTensors, size_t numOutputs, larodError **error)
 Create and initialize an inference request handle. More...
 
void larodDestroyInferenceRequest (larodInferenceRequest **infReq)
 Destroy an inference request handle. More...
 
bool larodSetInferenceRequestModel (larodInferenceRequest *infReq, const larodModel *model, larodError **error)
 Set model in an inference request. More...
 
bool larodSetInferenceRequestInputs (larodInferenceRequest *infReq, larodTensor **tensors, const size_t numTensors, larodError **error)
 Set input tensor array in an inference request. More...
 
bool larodSetInferenceRequestOutputs (larodInferenceRequest *infReq, larodTensor **tensors, const size_t numTensors, larodError **error)
 Set output tensor array in an inference request. More...
 
bool larodSetInferenceRequestPriority (larodInferenceRequest *infReq, const uint8_t priority, larodError **error)
 Set an priority of an inference request. More...
 
bool larodRunInference (larodConnection *conn, const larodInferenceRequest *infReq, larodError **error)
 Run inference on a loaded model. More...
 
bool larodRunInferenceAsync (larodConnection *conn, const larodInferenceRequest *infReq, larodRunInferenceCallback callback, void *userData, larodError **error)
 Run inference on a loaded model asynchronously. More...
 
bool larodGetChipId (larodConnection *conn, uint64_t *chipId, larodError **error)
 Get current chip ID in use for the session in larod. More...
 
bool larodSetChipId (larodConnection *conn, const uint64_t chipId, larodError **error)
 Set current chip using ID in use for the session in larod. More...
 
bool larodSetChip (larodConnection *conn, const larodChip chip, larodError **error)
 Set current chip using larodChip in use for the session in larod. More...
 
bool larodGetChipType (larodConnection *conn, larodChip *chipType, larodError **error)
 Get current chip type in use for the session in larod. More...
 

Detailed Description

Main larod header file.

Copyright 2018 Axis Communications SPDX-License-Identifier: Apache-2.0

Note
This library is not thread safe.

Typedef Documentation

◆ larodConnection

Connection handle type for the larod service.

This connection handle type is used to connect to and interfacing the larod service.

◆ larodInferenceRequest

Type describing a job request.

This is used when running jobs such as pre-processing or inference.

Deprecated:
Replaced with larodJobRequest in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.

◆ larodJobRequest

Type describing a job request.

This is used when running jobs such as pre-processing or inference.

◆ larodLoadModelCallback

typedef void(* larodLoadModelCallback) (larodModel *model, void *userData, larodError *error)

Callback used in larodLoadModelAsync().

Callback function should not carry out relatively extensive blocking tasks (it will block the main poll thread for the message bus). Especially note that it must not call the synchronous calls larodRunJob() and larodDeleteModel().

Parameters
modelHandle to the loaded model. Caller must release this handle using larodDestroyModel() when it's not needed any more.
userDataUser data.
errorAn initialized error handle when errors occurred (model is is NULL). error will be NULL on success. In this callback function, one must not free this handle with larodClearError(), since the library will do it when returning from this callback.

◆ larodMap

typedef struct larodMap larodMap

A type containing key-value pairs.

This type can hold key-value pairs, where the key is a string and the value can be any of a given number of types. It should be created using larodCreateMap(), destroyed using larodDestroyMap(), and accessed using the various access functions such as larodMapSetInt(), larodMapGetStr(), etcetera.

◆ larodModel

typedef struct larodModel larodModel

A type representing a model.

This type represents a model that has been loaded in the service. It contains information about the model, such as how many input and output tensor handles it requires for running a job, what ID it has been designated by the service etcetera. The properties of a model is accessed by various access functions (e.g. larodGetModelId()).

◆ larodRunInferenceCallback

typedef void(* larodRunInferenceCallback) (void *userData, larodError *error)

Callback used in larodRunInferenceAsync().

Callback function should not carry out relatively extensive blocking tasks (it will block the main poll thread for the message bus). Especially note that it must not call the synchronous calls larodRunInference() and larodDeleteModel().

Parameters
userDataUser data.
errorAn initialized error handle if any errors occur while running inference. Otherwise, it will be NULL. In this callback function, one must not free this handle with larodClearError(), since the library will do it when returning from this callback.
Deprecated:
Replaced with larodRunJobCallback() in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.

◆ larodRunJobCallback

typedef void(* larodRunJobCallback) (void *userData, larodError *error)

Callback used in larodRunJobAsync().

Callback function should not carry out relatively extensive blocking tasks (it will block the main poll thread for the message bus). Especially note that it must not call the synchronous calls larodRunJob() and larodDeleteModel().

Parameters
userDataUser data.
errorAn initialized error handle if any errors occur while running the job. Otherwise, it will be NULL. In this callback function, one must not free this handle with larodClearError(), since the library will do it when returning from this callback.

◆ larodTensor

typedef struct larodTensor larodTensor

A type representing a tensor.

This type contains various information about a tensor, such as dimensions, data type, data file descriptor etcetera. The properties of a tensor is accessed by get and set functions (e.g. larodGetTensorDims()).

Enumeration Type Documentation

◆ larodAccess

Enum type for specifying access.

Models can either be public or private; only the creator can modify private models, while anyone can modify public models.

Enumerator
LAROD_ACCESS_INVALID 

Invalid access.

LAROD_ACCESS_PRIVATE 

Private access.

LAROD_ACCESS_PUBLIC 

Public access.

◆ larodChip

enum larodChip

Enum type with supported chips.

The chips in this enum are supported by larod.

Enumerator
LAROD_CHIP_INVALID 

Invalid chip.

LAROD_CHIP_DEBUG 

Dummy chip for debugging.

LAROD_CHIP_TFLITE_CPU 

CPU with TensorFlow Lite.

LAROD_CHIP_TPU 

Google TPU.

LAROD_CHIP_CVFLOW_NN 

Ambarella CVFlow (NN).

LAROD_CHIP_TFLITE_GLGPU 

GPU with TensorFlow Lite. WARNING: This is an experimental chip which is subject to change.

LAROD_CHIP_CVFLOW_PROC 

Ambarella CVFlow (proc).

LAROD_CHIP_ACE 

Axis Compute Engine.

LAROD_CHIP_LIBYUV 

CPU with libyuv.

LAROD_CHIP_TFLITE_ARTPEC8DLPU 

ARTPEC-8 DLPU with TensorFlow Lite. WARNING: This is an experimental chip which is subject to change.

LAROD_CHIP_OPENCL 

Image processing using OpenCL.

◆ larodErrorCode

Enum type for error codes.

These are set in larodError on errors. Note that only the negative values are defined in this enum explicitly. larodErrorCode can also be a positive value, this corresponds then to Linux style errno values.

For example, if the value is 12 (positive), that is then value of the Linux errno ENOMEM, which means "could not allocate memory". While a value of -4 (negative) is LAROD_ERROR_MODEL_NOT_FOUND defined in this enum.

Enumerator
LAROD_ERROR_NONE 

No errors.

LAROD_ERROR_JOB 

General error for job.

LAROD_ERROR_INFERENCE 

General error for inference.

Deprecated:
Replaced with LAROD_ERROR_JOB in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
LAROD_ERROR_LOAD_MODEL 

General error for loading model.

LAROD_ERROR_FD 

Error regarding file descriptors.

LAROD_ERROR_MODEL_NOT_FOUND 

Model was not found.

LAROD_ERROR_PERMISSION 

Insufficient permissions.

LAROD_ERROR_CONNECTION 

Invalid connection.

LAROD_ERROR_CREATE_SESSION 

Could not create session.

LAROD_ERROR_KILL_SESSION 

Failed killing session.

LAROD_ERROR_INVALID_CHIP_ID 

Invalid chip ID.

LAROD_ERROR_INVALID_ACCESS 

Invalid access specifier.

LAROD_ERROR_DELETE_MODEL 

Error while deleting model.

LAROD_ERROR_TENSOR_MISMATCH 

Tensor mismatch.

LAROD_ERROR_VERSION_MISMATCH 

Version mismatch.

LAROD_ERROR_ALLOC 

Error while allocating.

LAROD_ERROR_MAX_ERRNO 

Max errno value (dummy value).

◆ larodTensorDataType

Enum type for specifying tensor data type.

As part of larodTensor these are used to describe the data type of a tensor.

If no data type is specified (LAROD_TENSOR_DATA_TYPE_UNSPECIFIED) for an input or output tensor when running a job, there will be no sanity check that it matches what the model expects.

Enumerator
LAROD_TENSOR_DATA_TYPE_INVALID 

Invalid data type.

LAROD_TENSOR_DATA_TYPE_UNSPECIFIED 

No data type is specified.

LAROD_TENSOR_DATA_TYPE_BOOL 

1-bit boolean.

LAROD_TENSOR_DATA_TYPE_UINT8 

8-bit unsigned integer.

LAROD_TENSOR_DATA_TYPE_INT8 

8-bit signed integer.

LAROD_TENSOR_DATA_TYPE_UINT16 

16-bit unsigned integer.

LAROD_TENSOR_DATA_TYPE_INT16 

16-bit signed integer.

LAROD_TENSOR_DATA_TYPE_UINT32 

32-bit unsigned integer.

LAROD_TENSOR_DATA_TYPE_INT32 

32-bit signed integer.

LAROD_TENSOR_DATA_TYPE_UINT64 

64-bit unsigned integer.

LAROD_TENSOR_DATA_TYPE_INT64 

64-bit signed integer.

LAROD_TENSOR_DATA_TYPE_FLOAT16 

16-bit floating point.

LAROD_TENSOR_DATA_TYPE_FLOAT32 

32-bit floating point.

LAROD_TENSOR_DATA_TYPE_FLOAT64 

64-bit floating point.

LAROD_TENSOR_DATA_TYPE_MAX 

Max enum (dummy value).

◆ larodTensorLayout

Enum type for specifying tensor layout.

As part of larodTensor these are used to describe how to interpret the dimensions of a tensor.

N, H, W, C stands for batch size, height, width and channels respectively. However, the semantic interpretation of the dimensions can of course differ when working on image data that is not laid out in memory this way. The important thing is that input tensors sent for jobs have the same layout as what the model they are sent to expects, and similarly that outputs are interpreted according to the model's output layout.

LAROD_TENSOR_LAYOUT_420SP represents a semiplanar data layout with subsampling 4:2:0, such as for example the NV12 color format. With this layout the interpretations of what larodTensorDims and larodTensorPitches represent differ from the other layouts. The larodTensorPitches is expected to have 3 elements. The "rightmost" element, pitches[2], represents the total byte size of a single row in the image for both the plane separated data part and the plane interleaved part. The middle element, pitches[1], correspond to the total byte size of the plane separated data, including padding on the end, i.e. it is the offset in bytes to the plane interleaved part of the data. The first element, pitches[0], describe the total byte size of the data, all padding included. This also accounts for extra padding on the end of the buffer. For an explicit example, see larodTensorPitches. The larodTensorDims is also expected to have 3 elements. The first element dims[0] represents the number of channels and should always be equal to 3. The second element dims[1] corresponds to the height in pixels of the image, and dims[2] the width in pixels of the image. This layout is experimental.

If no layout is specified (LAROD_TENSOR_LAYOUT_UNSPECIFIED) for an input or output tensor when running a job, there will be no sanity check that it matches what the model expects.

Enumerator
LAROD_TENSOR_LAYOUT_INVALID 

Invalid layout.

LAROD_TENSOR_LAYOUT_UNSPECIFIED 

No layout is specified.

LAROD_TENSOR_LAYOUT_NHWC 

Tensor is laid out with dimensions NxHxWxC, this is also referred to as "color interleaved" image data. The len member of the larodTensorDims must be 4 or 0 ("unspecified") for this kind of layout.

LAROD_TENSOR_LAYOUT_NCHW 

Tensor is laid out with dimensions NxCxHxW, this is also referred to as "plane separated color" image data. The len member of the larodTensorDims must be 4 or 0 ("unspecified") for this kind of layout.

LAROD_TENSOR_LAYOUT_420SP 

Image format, subsampling 4:2:0, semiplanar data layout (experimental).

LAROD_TENSOR_LAYOUT_MAX 

Max enum (dummy value).

Function Documentation

◆ larodAllocModelInputs()

larodTensor** larodAllocModelInputs ( larodConnection conn,
const larodModel model,
const uint32_t  fdPropFlags,
size_t *  numTensors,
larodMap params,
larodError **  error 
)

Create and allocate input tensors from a model.

Create input tensors according to what model requires. The tensors will be initialized with metadata such as data type, dims, layout etcetera based on information from the model.

The service will also allocate a buffer for each created tensor. These buffers are represented by the file descriptors set on the tensors and as such will be used to store the tensors' contents.

Furthermore, the buffers are guaranteed to meet the requirements specified in fdPropFlags (if non-zero) and the fd properties of each tensor will be set accordingly. If fdPropFlags is not set (i.e. zero), the service will decide for itself (based on model) which operations should be supported on the newly allocated tensors and thus set the fd properties accordingly (c.f. larodSetTensorFdProps()). In addition the service will automatically track each tensor, i.e. as if larodTrackTensor() would have been called on the newly created and allocated tensors (this increments the total number of tracked tensors for conn, see larodTrackTensor() for more details).

The buffers will be deallocated when conn closes, typically via a call to larodDisconnect(). The array of tensors needs to be released when it is no longer needed using larodDestroyTensors(). Note that the call to larodDestroyTensors() will not deallocate the allocated buffers.

Parameters
connAn initialized connection handle.
modelPointer to an initialized model handle.
fdPropFlagsAn indicator to the service of what kind of memory operations should be possible to perform on the file descriptors of the tensors. The relevant LAROD_FD_PROP_* flags should be or:ed together (bitmask) in this parameter. Can be set to 0 to let the service decide for itself which operations should be supported.
numTensorsOutput pointer that will be filled with number of entries in the returned array. This can be set to NULL if client does not need to retrieve this information (e.g. if the number is already known).
paramsAdditional larodChip specific optional parameters (can be NULL). Please refer to the documentation for the larodChip you are using to see what key-value pairs are applicable.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise pointer to an array of larodTensor pointers.

◆ larodAllocModelOutputs()

larodTensor** larodAllocModelOutputs ( larodConnection conn,
const larodModel model,
const uint32_t  fdPropFlags,
size_t *  numTensors,
larodMap params,
larodError **  error 
)

Create and allocate output tensors from a model.

Create output tensors according to what model requires. The tensors will be initialized with metadata such as data type, dims, layout etcetera based on information from the model.

The service will also allocate a buffer for each created tensor. These buffers are represented by the file descriptors set on the tensors and as such will be used to store the tensors' contents.

Furthermore, the buffers are guaranteed to meet the requirements specified in fdPropFlags (if non-zero) and the fd properties of each tensor will be set accordingly. If fdPropFlags is not set (i.e. zero), the service will decide for itself (based on model) which operations should be supported on the newly allocated tensors and thus set the fd properties accordingly (c.f. larodSetTensorFdProps()). In addition the service will automatically track each tensor, i.e. as if larodTrackTensor() would have been called on the newly created and allocated tensors (this increments the total number of tracked tensors for conn, see larodTrackTensor() for more details).

The buffers will be deallocated when conn closes, typically via a call to larodDisconnect(). The array of tensors needs to be released when it is no longer needed using larodDestroyTensors(). Note that the call to larodDestroyTensors() will not deallocate the allocated buffers.

Parameters
connAn initialized connection handle.
modelPointer to an initialized model handle.
fdPropFlagsAn indicator to the service of what kind of memory operations should be possible to perform on the file descriptors of the tensors. The relevant LAROD_FD_PROP_* flags should be or:ed together (bitmask) in this parameter. Can be set to 0 to let the service decide for itself which operations should be supported.
numTensorsOutput pointer that will be filled with number of entries in the returned array. This can be set to NULL if client does not need to retrieve this information (e.g. if the number is already known).
paramsAdditional larodChip specific optional parameters (can be NULL). Please refer to the documentation for the larodChip you are using to see what key-value pairs are applicable.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise pointer to an array of larodTensor pointers.

◆ larodClearError()

void larodClearError ( larodError **  error)

Deallocate an error handle.

Functions that has an argument of type larodError** allocates larodError when errors occur. This function should then later be used to deallocate it.

Parameters
errorAn initialized error handle or NULL. If error is NULL this function will do nothing. *error will be set to NULL after this call.

◆ larodConnect()

bool larodConnect ( larodConnection **  conn,
larodError **  error 
)

Connect to larod.

Connects to larod and creates a new session. Upon success, this allocates the connection handle conn and must thus be freed afterwards with with larodDisconnect().

Parameters
connAn uninitialized connection handle.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodCreateInferenceRequest()

larodInferenceRequest* larodCreateInferenceRequest ( const larodModel model,
larodTensor **  inputTensors,
size_t  numInputs,
larodTensor **  outputTensors,
size_t  numOutputs,
larodError **  error 
)

Create and initialize an inference request handle.

Creates and initializes an inference request handle with a minimum set of arguments needed to run an inference. The inference request needs to be deallocated with larodDestroyInferenceRequest() when no longer needed.

The tensor data and model information is copied into the larodInferenceRequest when it is created. The input and output file descriptors specified in the tensors inputTensors and outputTensors must have reading and writing permissions respectively when running the inference. Moreover, inputTensors file descriptors' file offsets will be set to the beginning before reading, while outputTensors file descriptors' file offsets will be untouched before writing (and left at the resulting position after the write).

Deprecated:
Replaced with larodCreateJobRequest() in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
Parameters
modelLoaded model to run inference on.
inputTensorsArray of input tensors.
numInputsNumber of input tensors.
outputTensorsArray of output tensors.
numOutputsNumber of output tensors.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise a pointer to an initialized inference request.

◆ larodCreateJobRequest()

larodJobRequest* larodCreateJobRequest ( const larodModel model,
larodTensor **  inputTensors,
size_t  numInputs,
larodTensor **  outputTensors,
size_t  numOutputs,
larodMap params,
larodError **  error 
)

Create and initialize a job request handle.

Creates and initializes a job request handle with a minimum set of arguments needed to run a job. The job request needs to be deallocated with larodDestroyJobRequest() when no longer needed.

The tensor data and model information is copied into the larodJobRequest when it is created. The input and output file descriptors specified in the tensors inputTensors and outputTensors must have reading and writing permissions respectively when running the job. Moreover, inputTensors file descriptors' file offsets will be set to the beginning before reading, while outputTensors file descriptors' file offsets will be untouched before writing (and left at the resulting position after the write).

Parameters
modelLoaded model to run the job on.
inputTensorsArray of input tensors.
numInputsNumber of input tensors.
outputTensorsArray of output tensors.
numOutputsNumber of output tensors.
paramsAdditional optional parameters (can be NULL). Please refer to the documentation for the chip you are using to see what key-value pairs are applicable.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise a pointer to an initialized request.

◆ larodCreateMap()

larodMap* larodCreateMap ( larodError **  error)

Create new larodMap.

Creates and initializes a handle to a mapping of key-value pairs. This struct is used to send additional information to the service, see for instance larodLoadModel. In particular, this struct may contain information that is relevant to only one, or a few backends.

It can hold various different data types as values and each value is identified via a key string. Adding key-value pairs to the mapping should be done using the set functions larodMapSetStr(), larodMapSetInt(), etcetera, and accessing the elements should be done via the get functions larodMapGetStr(), larodMapGetInt(), and so on. Strings added to this map has a maximum allowed length of 128 bytes (including terminating NULL-byte).

Once the mapping is no longer needed it should be destroyed using larodDestroyMap(). When key-value pairs are added to the map copies of the data are created, and the allocated memory is managed internally.

Parameters
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise a pointer to an initialized larodMap struct. Should be destroyed using larodDestroyMap when no longer needed.

◆ larodCreateModelInputs()

larodTensor** larodCreateModelInputs ( const larodModel model,
size_t *  numTensors,
larodError **  error 
)

Create input tensors from a model.

Create input tensors according to what model requires. The tensors will be initialized with metadata such as data type, dims, layout etcetera based on information from the model.

The created tensors will not have buffers allocated for their contents. For this reason the tensors will have file descriptors set to -1 (invalid) but fd properties will however be set to LAROD_FD_PROP_READWRITE (for backward compatibility). The user will have to allocate buffers for the tensors by themselves and then set the aforementioned tensor fields accordingly using the relevant set functions.

The array of tensors needs to be released when it is no longer needed using larodDestroyTensors(). To make the service track a returned tensor for subsequent jobs, larodTrackTensor() must be called on that tensor, prior to running the first job.

Parameters
modelPointer to an initialized model handle.
numTensorsOutput pointer that will be filled with number of entries in the returned array. This can be set to NULL if client does not need to retrieve this information (e.g. if the number is already known).
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise pointer to an array of larodTensor pointers.

◆ larodCreateModelOutputs()

larodTensor** larodCreateModelOutputs ( const larodModel model,
size_t *  numTensors,
larodError **  error 
)

Create output tensors from a model.

Create output tensors according to what model requires. The tensors will be initialized with metadata such as data type, dims, layout etcetera based on information from the model.

The created tensors will not have buffers allocated for their contents. For this reason the tensors will have file descriptors set to -1 (invalid) but fd properties will however be set to LAROD_FD_PROP_READWRITE (for backward compatibility). The user will have to allocate buffers for the tensors by themselves and then set the aforementioned tensor fields accordingly using the relevant set functions.

The array of tensors needs to be released when it is no longer needed using larodDestroyTensors(). To make the service track a returned tensor for subsequent jobs, larodTrackTensor() must be called on that tensor, prior to running the first job.

Parameters
modelPointer to an initialized model handle.
numTensorsOutput pointer that will be filled with number of entries in the returned array. This can be set to NULL if client does not need to retrieve this information (e.g. if the number is already known).
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise pointer to an array of larodTensor pointers.

◆ larodCreateTensors()

larodTensor** larodCreateTensors ( size_t  numTensors,
larodError **  error 
)

Create a list of empty larodTensor handles.

Creates a list of larodTensor. After a successful call, various attributes can be set on these tensors. The returned allocated array needs to be released with larodDestroyTensors() when no longer needed.

New tensors created with this function will have the following default values set on the attributes:

Parameters
numTensorsNumber of tensors to create.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise pointer to an array of larodTensor pointers.

◆ larodDeleteModel()

bool larodDeleteModel ( larodConnection conn,
larodModel model,
larodError **  error 
)

Delete a loaded model.

A public model can be deleted by anyone. However, for private models, only the creator has permission to delete it (if the creator disconnects, the private models will automatically get deleted).

The model handle model will not be released after a successful call. Consequently larodDestroyModel() should be called for model when no longer needed.

Parameters
connAn initialized connection handle.
modelModel to delete.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodDestroyInferenceRequest()

void larodDestroyInferenceRequest ( larodInferenceRequest **  infReq)

Destroy an inference request handle.

infReq should not be used after this call.

Deprecated:
Replaced with larodDestroyJobRequest() in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
Parameters
infReqPointer to an initialized handle or NULL. The dereferenced infReq will be set to NULL after the inference request is released. If infReq is NULL this function will nothing.

◆ larodDestroyJobRequest()

void larodDestroyJobRequest ( larodJobRequest **  jobReq)

Destroy a request handle.

jobReq should not be used after this call.

Parameters
jobReqPointer to an initialized handle or NULL. The dereferenced jobReq will be set to NULL after the job request is released. If jobReq is NULL this function will nothing.

◆ larodDestroyMap()

void larodDestroyMap ( larodMap **  map)

Destroy a larodMap.

Releases all memory associated with a larodMap, including allocated key-value pairs. map should not be used after this call.

Parameters
mapPointer to an initialized handle of a larodMap or NULL.

◆ larodDestroyModel()

void larodDestroyModel ( larodModel **  model)

Free an allocated larodModel handle.

Release the memory for a model handle. model must not be used after this call. The model will not be deleted in the server by this call. Use larodDeleteModel() to accomplish this.

Parameters
modelPointer to model (allocated from e.g a larodLoadModel() call) or NULL. The model handle will be released and then the dereferenced model will be set to NULL. If model is NULL this function will do nothing.

◆ larodDestroyModels()

void larodDestroyModels ( larodModel ***  models,
size_t  numModels 
)

Destroy a list of model objects.

Release all data associated with models (which was returned by larodGetModels()). The pointer models must not be used after this call.

Parameters
modelsPointer to allocated (with larodGetModels()) list of models or NULL. The dereferenced models will be set to NULL after release of the list. If models is NULL this function will do nothing.
numModelsNumber of models in the models array.

◆ larodDestroyTensors()

void larodDestroyTensors ( larodTensor ***  tensors,
size_t  numTensors 
)

Destroy a list of larodTensor.

Releases the memory associated with a list of larodTensor handles. Neither the pointers in the tensors array nor the array itself can be used after this call.

Parameters
tensorsPointer to array of larodTensor pointers or NULL. The dereferenced tensors will be set to NULL after the list is released. If tensors is NULL, this function will do nothing.
numTensorsNumber of tensors in the tensors array.

◆ larodDisconnect()

bool larodDisconnect ( larodConnection **  conn,
larodError **  error 
)

Disconnect from larod.

Disconnects from larod and kills the corresponding session. This will always deallocate the connection handle conn and set it to NULL (as well as other allocated stuff). The return value indicates if the corresponding session in larod was successfully killed.

Parameters
connAn initialized connection handle. The dereferenced conn will be set to NULL after the connection is released. If conn is NULL this function will do nothing.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodGetChipId()

bool larodGetChipId ( larodConnection conn,
uint64_t *  chipId,
larodError **  error 
)

Get current chip ID in use for the session in larod.

Deprecated:
Replaced with larodGetModelChip() in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
Parameters
connAn initialized connection handle.
chipIdPointer to the variable where the result will be stored.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodGetChipName()

const char* larodGetChipName ( const larodChip  chip)

Get name of a chip.

This is a convenience function to get the string representation of a chip. If chip has an invalid value (not defined in enum type larodChip), "Invalid chip" will be returned.

Parameters
chipChip to get the name of.
Returns
String representation of chip.

◆ larodGetChipType()

bool larodGetChipType ( larodConnection conn,
larodChip chipType,
larodError **  error 
)

Get current chip type in use for the session in larod.

Deprecated:
Replaced with larodGetModelChip() in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
Parameters
connAn initialized connection handle.
chipTypePointer to the variable where the result will be stored.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodGetModel()

larodModel* larodGetModel ( larodConnection conn,
const uint64_t  modelId,
larodError **  error 
)

Get handle to a model by model ID.

The model ID could for example be retrieved with larodGetModelId().

Parameters
connAn initialized connection handle.
modelIdModel ID to get the corresponding model handle for.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if any errors occur, otherwise a valid pointer to larodModel. The returned pointer should be released with larodDestroyModel() when it is no longer needed.

◆ larodGetModelAccess()

larodAccess larodGetModelAccess ( const larodModel model,
larodError **  error 
)

Get model access mode.

Parameters
modelPointer to an initialized model handle.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is LAROD_ACCESS_INVALID), it must later be deallocated with larodClearError().
Returns
LAROD_ACCESS_INVALID if error has occurred, otherwise a valid model access.

◆ larodGetModelChip()

larodChip larodGetModelChip ( const larodModel model,
larodError **  error 
)

Get chip for a model.

Parameters
modelPointer to an initialized model handle.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is LAROD_INVALID_MODEL_ID), it must later be deallocated with larodClearError().
Returns
LAROD_CHIP_INVALID if error has occurred, otherwise the associated chip for model.

◆ larodGetModelId()

uint64_t larodGetModelId ( const larodModel model,
larodError **  error 
)

Get model ID.

All models have a unique ID.

Parameters
modelPointer to an initialized model handle.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is LAROD_INVALID_MODEL_ID), it must later be deallocated with larodClearError().
Returns
LAROD_INVALID_MODEL_ID if error has occurred, otherwise a valid model ID.

◆ larodGetModelInputByteSizes()

size_t* larodGetModelInputByteSizes ( const larodModel model,
size_t *  numInputs,
larodError **  error 
)

Get input tensor byte sizes for a model.

Allocate input tensors byte sizes based on a larodModel. The array of byte sizes needs to be released when it is no longer needed by calling free().

Parameters
modelPointer to an initialized model handle.
numInputsOutput pointer that will be filled with number of input tensors. This can be set to NULL if client does not need to retrieve this information (e.g. if the number is already known).
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise pointer to an array of input tensor byte sizes.

◆ larodGetModelName()

const char* larodGetModelName ( const larodModel model,
larodError **  error 
)

Get model name.

The returned pointer is valid as long as model handle is valid, the caller does not need to deallocate it.

Parameters
modelPointer to an initialized model handle.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
Model name as NULL-terminated string, or NULL if error occurred.

◆ larodGetModelNumInputs()

size_t larodGetModelNumInputs ( const larodModel model,
larodError **  error 
)

Get number of input tensors for a model.

Parameters
modelPointer to an initialized model handle.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is 0), it must later be deallocated with larodClearError().
Returns
Number of input tensors or 0 if error occurred.

◆ larodGetModelNumOutputs()

size_t larodGetModelNumOutputs ( const larodModel model,
larodError **  error 
)

Get number of output tensors for a model.

Parameters
modelPointer to an initialized model handle.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is 0), it must later be deallocated with larodClearError().
Returns
Number of output tensors or 0 if error occurred.

◆ larodGetModelOutputByteSizes()

size_t* larodGetModelOutputByteSizes ( const larodModel model,
size_t *  numOutputs,
larodError **  error 
)

Get output tensor byte sizes for a model.

Allocate output tensors byte sizes based on a larodModel. The array of byte sizes needs to be released when it is no longer needed by calling free().

Parameters
modelPointer to an initialized model handle.
numOutputsOutput pointer that will be filled with number of output tensors. This can be set to NULL if client does not need to retrieve this information (e.g. if the number is already known).
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise pointer to an array of output tensor byte sizes.

◆ larodGetModels()

larodModel** larodGetModels ( larodConnection conn,
size_t *  numModels,
larodError **  error 
)

Get all loaded models.

Retrieve a list of all loaded models. Caller needs to free this list afterwards with the function larodDestroyModels().

If any of the returned models' sizes exceeds the address space size of this system, then SIZE_MAX will be the listed as the model size (see larodGetModelSize()).

Parameters
connAn initialized connection handle.
numModelsOutput pointer that will be filled with number of entries in the returned array. If the number of loaded models is 0 in the server, this pointer will be set accordingly. If an error occurred the target of this pointer remains untouched.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if any errors occurred, an array with a single element NULL if the number of loaded models is 0 in the service, and otherwise an array of pointers to larodModel.

◆ larodGetModelSize()

size_t larodGetModelSize ( const larodModel model,
larodError **  error 
)

Get model size.

Get size (in bytes) of a loaded model.

Parameters
modelPointer to an initialized model handle.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is 0), it must later be deallocated with larodClearError().
Returns
Model size in bytes or 0 if error occurred.

◆ larodGetNumSessions()

bool larodGetNumSessions ( larodConnection conn,
uint64_t *  numSessions,
larodError **  error 
)

Get number of currently active sessions in larod.

Parameters
connAn initialized connection handle.
numSessionsPointer to the variable where the result will be stored.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodGetTensorDataType()

larodTensorDataType larodGetTensorDataType ( const larodTensor tensor,
larodError **  error 
)

Get data type of a tensor.

Parameters
tensorPointer to an already allocated larodTensor.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is LAROD_TENSOR_DATA_TYPE_INVALID), it must later be deallocated with larodClearError().
Returns
LAROD_TENSOR_DATA_TYPE_INVALID if error has occurred, otherwise a valid tensor data type.

◆ larodGetTensorDims()

const larodTensorDims* larodGetTensorDims ( const larodTensor tensor,
larodError **  error 
)

Get dimensions of a tensor.

See larodTensorDims for definition of dimensions and larodTensorPitches for how they are related to tensors' pitches.

Parameters
tensorPointer to an already allocated larodTensor.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise a pointer to larodTensorDims instance. This pointer is valid as long as tensor is valid and should not be freed manually by the caller.

◆ larodGetTensorFd()

int larodGetTensorFd ( const larodTensor tensor,
larodError **  error 
)

Get file descriptor of a tensor.

Parameters
tensorPointer to an already allocated larodTensor.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is LAROD_INVALID_FD), it must later be deallocated with larodClearError().
Returns
LAROD_INVALID_FD if error occurred, otherwise a valid file descriptor.

◆ larodGetTensorFdOffset()

int64_t larodGetTensorFdOffset ( const larodTensor tensor,
larodError **  error 
)

Get file offset for a tensor.

Retrieves the user-supplied file offset (bytes) of the file descriptor associated with tensor, i.e. the value set by larodSetTensorFdOffset() or default value 0.

Parameters
tensorPointer to an already allocated larodTensor.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is -1), it must later be deallocated with larodClearError().
Returns
-1 if error occurred, otherwise the configured offset value.

◆ larodGetTensorFdProps()

bool larodGetTensorFdProps ( const larodTensor tensor,
uint32_t *  fdPropFlags,
larodError **  error 
)

Get the properties of a file descriptor of a tensor.

Parameters
tensorPointer to an already allocated larodTensor.
typePointer to a variable that will indicate what kind of memory operations are possible to perform on the fd of tensor. These properties will be represented as an or:ing together (bitmask) of relevant LAROD_FD_PROP_* flags.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodGetTensorFdSize()

bool larodGetTensorFdSize ( const larodTensor tensor,
size_t *  size,
larodError **  error 
)

Get file descriptor maximum capacity (bytes) for a tensor.

Retrieves the user-supplied file descriptor maximum capacity (bytes) of a tensor, i.e. the value set by larodSetTensorFdSize() or default value 0. Please refer to larodSetTensorFdSize() for details about the size value.

Parameters
tensorPointer to an already allocated larodTensor.
sizeOutput pointer, the dereferenced pointer will be updated with currently set size.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodGetTensorLayout()

larodTensorLayout larodGetTensorLayout ( const larodTensor tensor,
larodError **  error 
)

Get layout of a tensor.

Parameters
tensorPointer to an already allocated larodTensor.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is LAROD_TENSOR_LAYOUT_INVALID), it must later be deallocated with larodClearError().
Returns
LAROD_TENSOR_LAYOUT_INVALID if error occurred, otherwise a valid larodTensorLayout.

◆ larodGetTensorName()

const char* larodGetTensorName ( const larodTensor tensor,
larodError **  error 
)

Get name of tensor.

Returns a reference to a string representing the name of the supplied tensor. The returned string pointer is valid as long as tensor is valid.

Parameters
tensorPointer to an already allocated larodTensor.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise a pointer to an initialized string representing the name of tensor.

◆ larodGetTensorPitches()

const larodTensorPitches* larodGetTensorPitches ( const larodTensor tensor,
larodError **  error 
)

Get pitches of a tensor.

See larodTensorPitches for the definition of pitches.

Parameters
tensorPointer to an already allocated larodTensor.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise a pointer to larodTensorDims instance. This pointer is valid as long as tensor is valid and should not be freed manually by the caller.

◆ larodListChips()

bool larodListChips ( larodConnection conn,
larodChip **  chips,
size_t *  numChips,
larodError **  error 
)

List available chips.

Fills chips with a list of available larodChip sorted in no particular order.

Warning
The parameter numChips has changed meaning in larod 1.3. Before larod 1.3, this parameter was used for the size (in bytes) of the chips array.
Parameters
connAn initialized connection handle.
chipsPointer to a pointer where an array of returned chips will be allocated to. After a successful call, you should thus free *chips!
numChipsOutput pointer that will be filled with number of chips. This can be set to NULL if client does not need to retrieve this information.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodLoadModel() [1/2]

larodModel* larodLoadModel ( larodConnection conn,
const int  fd,
const larodAccess  access,
const char *  name,
larodError **  error 
)

Load a new model to current chip.

This function returns a model handle. Use this for referencing the loaded model in other functions such as larodDeleteModel(), larodCreateInferenceRequest() etcetera. Note that the file descriptor fd for the binary model file must have valid reading permissions.

Deprecated:
Replaced with larodLoadModel() in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
Parameters
connAn initialized connection handle.
fdFile descriptor to the model data.
accessAccess specifier for the model.
nameName for the model.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL) it must later be deallocated with larodClearError().
Returns
NULL if any errors occur, otherwise a valid pointer to larodModel. The returned pointer should be released with larodDestroyModel() when it is no longer needed.

◆ larodLoadModel() [2/2]

larodModel* larodLoadModel ( larodConnection conn,
const int  fd,
const larodChip  chip,
const larodAccess  access,
const char *  name,
const larodMap params,
larodError **  error 
)

Load a new model.

This function returns a model handle. Use this for referencing the loaded model in other functions such as larodDeleteModel(), larodCreateJobRequest() etcetera. Note that the file descriptor fd for the binary model file must have valid reading permissions.

Parameters
connAn initialized connection handle.
fdFile descriptor to the model data. This can be set to a negative value (i.e. invalid) if params is also specified (not NULL).
chipChip type to load model onto.
accessAccess specifier for the model.
nameName for the model.
paramsAdditional optional parameters (can be NULL). Please refer to the documentation for the chip you are using to see what key-value pairs are applicable.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL) it must later be deallocated with larodClearError().
Returns
NULL if any errors occur, otherwise a valid pointer to larodModel. The returned pointer should be released with larodDestroyModel() when it is no longer needed.

◆ larodLoadModelAsync() [1/2]

bool larodLoadModelAsync ( larodConnection conn,
const int  fd,
const larodAccess  access,
const char *  name,
larodLoadModelCallback  callback,
void *  userData,
larodError **  error 
)

Load a new model to current chip asynchronously.

This is the asynchronous version of larodLoadModel(). The callback function callback will be called as soon as the model has been loaded.

Deprecated:
Replaced with larodLoadModelAsync() in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
Parameters
connAn initialized connection handle.
fdFile descriptor to the model data.
accessAccess specifier for the model.
nameName for the model.
callbackCallback function.
userDataUser data that will passed to the callback function.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodLoadModelAsync() [2/2]

bool larodLoadModelAsync ( larodConnection conn,
const int  fd,
const larodChip  chip,
const larodAccess  access,
const char *  name,
const larodMap params,
larodLoadModelCallback  callback,
void *  userData,
larodError **  error 
)

Load a new model asynchronously.

This is the asynchronous version of larodLoadModel(). The callback function callback will be called as soon as the model has been loaded.

Parameters
connAn initialized connection handle.
fdFile descriptor to the model data. This can be set to a negative value (i.e. invalid) if params is also specified (not NULL).
chipChip type to load model onto.
accessAccess specifier for the model.
nameName for the model.
paramsAdditional optional parameters (can be NULL). Please refer to the documentation for the chip you are using to see what key-value pairs are applicable.
callbackCallback function.
userDataUser data that will be passed to the callback function.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodMapGetInt()

bool larodMapGetInt ( larodMap map,
const char *  key,
int64_t *  value,
larodError **  error 
)

Get an integer type value tied to given key.

Get a 64-bit integer corresponding to the given key. If the key is not found in map, or if the key exists, but the value is not an integer type an error is reported. The key string should be at maximum 128 bytes long (including terminating NULL-byte).

Parameters
mapObject to search for the key.
keyKey string to search for.
valueOutput pointer for value to be extracted. The referenced memory will be set to the value of the requested key if call is successful, otherwise it will not be changed.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodMapGetIntArr2()

const int64_t* larodMapGetIntArr2 ( larodMap map,
const char *  key,
larodError **  error 
)

Get an integer array of two elements tied to given key.

Get a 64-bit integer array of two elements, corresponding to the given key. If the key is not found in map, or if the key exists, but the value is not an integer array of two elements an error is reported. The key string should be at maximum 128 bytes long (including terminating NULL-byte).

Parameters
mapObject to search for the key.
keyKey string to search for.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise pointer to an array of two elements corresponding to the given key. Should not be freed by the user.

◆ larodMapGetIntArr4()

const int64_t* larodMapGetIntArr4 ( larodMap map,
const char *  key,
larodError **  error 
)

Get an integer array of four elements tied to given key.

Get a 64-bit integer array of four elements, corresponding to the given key. If the key is not found in map, or if the key exists, but the value is not an integer array of four elements an error is reported. The key string should be at maximum 128 bytes long (including terminating NULL-byte).

Parameters
mapObject to search for the key.
keyKey string to search for.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise pointer to an array of four elements corresponding to the given key. Should not be freed by the user.

◆ larodMapGetStr()

const char* larodMapGetStr ( larodMap map,
const char *  key,
larodError **  error 
)

Get string type value tied to given key.

Get a string value corresponding to the given key. If the key is not found in map, or if the key exists, but the value is not a string type an error is reported. The key string should be at maximum 128 bytes long (including terminating NULL-byte).

Parameters
mapObject to search for the key.
keyKey string to search for.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
NULL if error occurred, otherwise a string corresponding to the given key. Should not be freed by the user.

◆ larodMapSetInt()

bool larodMapSetInt ( larodMap map,
const char *  key,
const int64_t  value,
larodError **  error 
)

Add an integer to a larodMap object.

Adds a 64-bit integer to a larodMap object and associates the value with a string given by key. If an integer type value already exists for the given key it will be replaced by the new value. If a value already exists for the given key, but the value is of another type an error will be reported. The key string should be at maximum 128 bytes long (including terminating NULL-byte).

Parameters
mapHandle to a larodMap object.
keyString key to identify value with.
valueValue to associate with key.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodMapSetIntArr2()

bool larodMapSetIntArr2 ( larodMap map,
const char *  key,
const int64_t  value0,
const int64_t  value1,
larodError **  error 
)

Add an integer array of two elements to a larodMap object.

Adds a 64-bit integer array of two elements to a larodMap object and associates it with a string given by key. If a two element integer array value already exists for the given key it will be replaced by the new value. If a value already exists for the given key, but the value is of another type an error will be reported. The key string should be at maximum 128 bytes long (including terminating NULL-byte).

Parameters
mapHandle to a larodMap object.
keyString key to identify value with.
value0First array value to associate with key.
value1Second array value to associate with key.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is NULL), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodMapSetIntArr4()

bool larodMapSetIntArr4 ( larodMap map,
const char *  key,
const int64_t  value0,
const int64_t  value1,
const int64_t  value2,
const int64_t  value3,
larodError **  error 
)

Add an integer array of four elements to a larodMap object.

Adds a 64-bit integer array of four elements to a larodMap object and associates it with a string given by key. If a four element integer array value already exists for the given key it will be replaced by the new value. If a value already exists for the given key, but the value is of another type an error will be reported. The key string should be at maximum 128 bytes long (including terminating NULL-byte).

Parameters
mapHandle to a larodMap object.
keyString key to identify value with.
value0First array value to associate with key.
value1Second array value to associate with key.
value2Third array value to associate with key.
value3Fourth array value to associate with key.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodMapSetStr()

bool larodMapSetStr ( larodMap map,
const char *  key,
const char *  value,
larodError **  error 
)

Add a string to a larodMap object.

Adds a copy of the string pointed to by value to a larodMap object and associates the value with a string given by key. If a string type value already exists for the given key it will be replaced by the new value. If a value already exists for the given key, but the value is of another type an error will be reported. Both key and value strings should be at maximum 128 bytes long (including terminating NULL-byte).

Parameters
mapHandle to a larodMap object.
keyString key to identify value with.
valueString value to associate with key.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodRunInference()

bool larodRunInference ( larodConnection conn,
const larodInferenceRequest infReq,
larodError **  error 
)

Run inference on a loaded model.

Data will be read or written using the tensors' file descriptors. The maximum number of bytes that the larod service will access (read or write) can be set by larodSetTensorFdSize() for each tensor. Offsets into the file descriptors can be configured using larodSetTensorFdOffset(). If the size value for a tensor is 0 (default value) then larod will use file operations to determine the file descriptor size. The larod service will also use file operations to read and write tensor data, thus the current file positions of tensor file descriptors will be updated by the inference call. The client should not access the file descriptors during this call.

Deprecated:
Replaced with larodRunJob() in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
Parameters
connAn initialized connection handle.
infReqAn initialized inference request handle. The input and output file descriptors specified in the request must have reading and writing permissions, respectively. Moreover, the input file descriptors' file offsets will be set to the beginning before reading, while the output file descriptors' file offsets will be untouched before writing (and left at the resulting position after the write).
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodRunInferenceAsync()

bool larodRunInferenceAsync ( larodConnection conn,
const larodInferenceRequest infReq,
larodRunInferenceCallback  callback,
void *  userData,
larodError **  error 
)

Run inference on a loaded model asynchronously.

This is the asynchronous version of larodRunInference(). The same set of parameters as larodRunInference() must be explicitly set in infReq.

Data will be accessed for read or write using the tensor file descriptors. Offsets into the file descriptors can be configured using larodSetTensorFdOffset(). The maximum number of bytes that the larod service will access (read or write) can be set by larodSetTensorFdSize() for each tensor. If the size value for a tensor is 0 (default value) then larod will use file operations to determine the file descriptor size. The larod service will also use file operations to read and write tensor data, thus the current file positions of tensor file descriptors will be updated by the inference call. The client should not access the file descriptors while an asynchronous inference in running.

The callback function callback will be called as soon as the inference has finished. The callbacks are not guaranteed to be called in any order; userData can be used to tag different requests.

Deprecated:
Replaced with larodRunJobAsync() in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
Parameters
connAn initialized connection handle.
infReqAn initialized inference request handle. The input and output file descriptors specified in the request must have reading and writing permissions, respectively. Moreover, the input file descriptors' file offsets will be set to the beginning before reading, while the output file descriptors' file offsets will be untouched before writing (and left at the resulting position after the write).
callbackCallback function.
userDataUser data that will passed to the callback function.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodRunJob()

bool larodRunJob ( larodConnection conn,
const larodJobRequest jobReq,
larodError **  error 
)

Run a job on a loaded model.

Data will be read or written using the tensors' file descriptors. The maximum number of bytes that the larod service will access (read or write) can be set by larodSetTensorFdSize() for each tensor. Offsets into the file descriptors can be configured using larodSetTensorFdOffset(). If the size value for a tensor is 0 (default value) then larod will use file operations to determine the file descriptor size. The larod service will also use file operations to read and write tensor data, thus the current file positions of tensor file descriptors will be updated by the job call. The client should not access the file descriptors during this call.

Parameters
connAn initialized connection handle.
jobReqAn initialized job request handle. The input and output file descriptors specified in the request must have reading and writing permissions, respectively. Moreover, the input file descriptors' file offsets will be set to the beginning before reading, while the output file descriptors' file offsets will be untouched before writing (and left at the resulting position after the write).
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodRunJobAsync()

bool larodRunJobAsync ( larodConnection conn,
const larodJobRequest jobReq,
larodRunJobCallback  callback,
void *  userData,
larodError **  error 
)

Run a job on a loaded model asynchronously.

This is the asynchronous version of larodRunJob(). The same set of parameters as larodRunJob() must be explicitly set in jobReq.

Data will be accessed for read or write using the tensor file descriptors. Offsets into the file descriptors can be configured using larodSetTensorFdOffset(). The maximum number of bytes that the larod service will access (read or write) can be set by larodSetTensorFdSize() for each tensor. If the size value for a tensor is 0 (default value) then larod will use file operations to determine the file descriptor size. The larod service will also use file operations to read and write tensor data, thus the current file positions of tensor file descriptors will be updated by the job call. The client should not access the file descriptors while an asynchronous job is running.

The callback function callback will be called as soon as the job has finished. The callbacks are not guaranteed to be called in any order; userData can be used to tag different requests.

Parameters
connAn initialized connection handle.
jobReqAn initialized job request handle. The input and output file descriptors specified in the request must have reading and writing permissions, respectively. Moreover, the input file descriptors' file offsets will be set to the beginning before reading, while the output file descriptors' file offsets will be untouched before writing (and left at the resulting position after the write).
callbackCallback function.
userDataUser data that will be passed to the callback function.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodSetChip()

bool larodSetChip ( larodConnection conn,
const larodChip  chip,
larodError **  error 
)

Set current chip using larodChip in use for the session in larod.

Note: if there is more than one chip on the device corresponding to chip then the one with the smallest chip ID will be chosen.

Deprecated:
Replaced with larodLoadModel() (with chip parameter) in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
Parameters
connAn initialized connection handle.
chipChip to set.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodSetChipId()

bool larodSetChipId ( larodConnection conn,
const uint64_t  chipId,
larodError **  error 
)

Set current chip using ID in use for the session in larod.

Deprecated:
Replaced with larodLoadModel() (with chip parameter) in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
Parameters
connAn initialized connection handle.
chipIdChip ID to set.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodSetInferenceRequestInputs()

bool larodSetInferenceRequestInputs ( larodInferenceRequest infReq,
larodTensor **  tensors,
const size_t  numTensors,
larodError **  error 
)

Set input tensor array in an inference request.

Copies the tensors array into the inference request. The existing tensor array in infReq will be overwritten.

Deprecated:
Replaced with larodSetJobRequestInputs() in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
Parameters
infReqPointer to an already allocated inference request.
tensorsTensor array to copy into the inference request.
numTensorsNumbers of tensor entries in the tensor array.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodSetInferenceRequestModel()

bool larodSetInferenceRequestModel ( larodInferenceRequest infReq,
const larodModel model,
larodError **  error 
)

Set model in an inference request.

Specifies which model to run the inference request on. Copies the model information into the inference request. The existing model information in infReq will be overwritten.

Deprecated:
Replaced with larodSetJobRequestModel() in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
Parameters
infReqPointer to an already allocated inference request.
modelModel to copy into the inference request.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodSetInferenceRequestOutputs()

bool larodSetInferenceRequestOutputs ( larodInferenceRequest infReq,
larodTensor **  tensors,
const size_t  numTensors,
larodError **  error 
)

Set output tensor array in an inference request.

Copies the tensors array into the inference request. The existing tensor array in infReq will be overwritten.

Deprecated:
Replaced with larodSetJobRequestOutputs() in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
Parameters
infReqInference request handle.
tensorsTensor array to copy into the inference request.
numTensorsNumbers of tensor entries in the tensor array.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodSetInferenceRequestPriority()

bool larodSetInferenceRequestPriority ( larodInferenceRequest infReq,
const uint8_t  priority,
larodError **  error 
)

Set an priority of an inference request.

Only applicable when used with asynchronous inferences. 0 means lowest priority while 100 means highest priority.

When the service processes requests for a given session, it will attempt to run higher priority inference requests before lower priority requests. Specifically, the service will dispatch inferences to the underlying chip framework in order of priority. As a result of the dependency on the underlying chip framework, the service cannot guarantee that inferences will be finished in priority order.

As an illustrative example, consider a case where multiple low priority requests are enqueued, followed by a high priority request, followed by another set of low priority requests. In this case, after the high priority request is enqueued, it is guaranteed to be the next request to be dispatched to the chip framework. Thus, the high priority request may be processed before some of the earlier low priority ones. Also, the high priority request is guaranteed be processed before any low priority requests that were enqueued later.

Note also that priorities are only valid within the set of requests for a given session. The priority does not influence the ordering in different connections! Default priority is 50 when a request is created (

See also
larodCreateInferenceRequest() and
larodCreateEmptyInferenceRequest()).
Deprecated:
Replaced with larodSetJobRequestPriority() in larod 2.0. This type is still available in larod 2.0 and later if LAROD_API_VERSION_1 is defined before larod.h is included.
Parameters
infReqPointer to an initialized handle.
priorityThe priority to attach to infReq.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodSetJobRequestInputs()

bool larodSetJobRequestInputs ( larodJobRequest jobReq,
larodTensor **  tensors,
const size_t  numTensors,
larodError **  error 
)

Set input tensor array in a request.

Copies the tensors array into the request. The existing tensor array in jobReq will be overwritten.

Parameters
jobReqPointer to an already allocated job request.
tensorsTensor array to copy into the request.
numTensorsNumbers of tensor entries in the tensor array.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodSetJobRequestModel()

bool larodSetJobRequestModel ( larodJobRequest jobReq,
const larodModel model,
larodError **  error 
)

Set model in a request.

Specifies which model to run the job request on. Copies the model information into the job request. The existing model information in req will be overwritten.

Parameters
jobReqPointer to an already allocated job request.
modelModel to copy into the request.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodSetJobRequestOutputs()

bool larodSetJobRequestOutputs ( larodJobRequest jobReq,
larodTensor **  tensors,
const size_t  numTensors,
larodError **  error 
)

Set output tensor array in a job request.

Copies the tensors array into the job request. The existing tensor array in jobReq will be overwritten.

Parameters
jobReqJob request handle.
tensorsTensor array to copy into the job request.
numTensorsNumbers of tensor entries in the tensor array.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodSetJobRequestParams()

bool larodSetJobRequestParams ( larodJobRequest jobReq,
const larodMap params,
larodError **  error 
)

Set additional parameters to a job request.

Copies the params map into the job request. The existing parameters map in jobReq will be overwritten.

Parameters
jobReqJob request handle.
paramsAdditional optional parameters. Please refer to the documentation for the chip you are using to see what key-value pairs are applicable.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodSetJobRequestPriority()

bool larodSetJobRequestPriority ( larodJobRequest jobReq,
const uint8_t  priority,
larodError **  error 
)

Set an priority of a job request.

Only applicable when used with asynchronous jobs. 0 means lowest priority while 100 means highest priority.

When the service processes requests for a given session, it will attempt to run higher priority job requests before lower priority requests. Specifically, the service will dispatch jobs to the underlying chip framework in order of priority. As a result of the dependency on the underlying chip framework, the service cannot guarantee that jobs will be finished in priority order.

As an illustrative example, consider a case where multiple low priority requests are enqueued, followed by a high priority request, followed by another set of low priority requests. In this case, after the high priority request is enqueued, it is guaranteed to be the next request to be dispatched to the chip framework. Thus, the high priority request may be processed before some of the earlier low priority ones. Also, the high priority request is guaranteed be processed before any low priority requests that were enqueued later.

Note also that priorities are only valid within the set of requests for a given session. The priority does not influence the ordering in different connections! Default priority is 50 when a request is created (

See also
larodCreateJobRequest()).
Parameters
jobReqPointer to an initialized handle.
priorityThe priority to attach to jobReq.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodSetTensorDataType()

bool larodSetTensorDataType ( larodTensor tensor,
const larodTensorDataType  dataType,
larodError **  error 
)

Set data type of a tensor.

If the data type is set to LAROD_TENSOR_DATA_TYPE_UNSPECIFIED no sanity checks for the tensor data type (i.e. comparisons with what the model expects of the tensor data type) will be performed when running a job.

Parameters
tensorPointer to an already allocated larodTensor.
dataTypeData type for the tensor (see larodTensorDataType).
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodSetTensorDims()

bool larodSetTensorDims ( larodTensor tensor,
const larodTensorDims dims,
larodError **  error 
)

Set the dimensions of a tensor.

If the dims member len is set to 0 no sanity checks for the tensor dimensions (i.e. comparisons with what the model expects of the tensor dimensions) will be performed when running a job.

If len is specified, it must be equal to the len of the tensor's pitches if that is also specified; otherwise one gets an error when creating job requests. See larodTensorPitches for more details of how they are related.

Parameters
tensorPointer to an already allocated larodTensor.
dimsPointer to larodTensorDims. The contents of the struct will be copied into tensor.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodSetTensorFd()

bool larodSetTensorFd ( larodTensor tensor,
const int  fd,
larodError **  error 
)

Set file descriptor of a tensor.

Parameters
tensorPointer to an already allocated larodTensor.
fdFile descriptor.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodSetTensorFdOffset()

bool larodSetTensorFdOffset ( larodTensor tensor,
const int64_t  offset,
larodError **  error 
)

Set file offset for a tensor.

Set the file offset (bytes) that will be applied when larod is accessing the tensor's file descriptor during a job call (by either reading or writing, c.f. larodSetTensorFdSize()). The offset is specified from the beginning of the file. Negative offset values are not allowed. The default value is 0.

Parameters
tensorPointer to an already allocated larodTensor.
offsetOffset from the start for tensor's file descriptor.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodSetTensorFdProps()

bool larodSetTensorFdProps ( larodTensor tensor,
const uint32_t  fdPropFlags,
larodError **  error 
)

Set the properties for a file descriptor of a tensor.

Should be called with relevant LAROD_FD_PROP_* flags or:ed together as fdPropFlags in order to notify the service of what kind of memory operations can be used on the fd of tensor. The service will then access the fd as efficiently as possible using this information.

Note that valid fd properties must be set for every larodTensor sent to the service via a larodJobRequest. In particular 0 is not valid for fdPropFlags as this would indicate that there are no possible ways for the service to access the memory of the tensor's fd.

Parameters
tensorPointer to an already allocated larodTensor.
fdPropFlagsAn indicator to the service of what kind of memory operations are possible to perform on the fd of tensor. The relevant LAROD_FD_PROP_* flags should be or:ed together (bitmask) in this parameter.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodSetTensorFdSize()

bool larodSetTensorFdSize ( larodTensor tensor,
const size_t  size,
larodError **  error 
)

Set file descriptor maximum capacity (bytes) for a tensor.

Sets the maximum number of bytes that is allowed to be read or written to the file descriptor associated with tensor. If size is set to 0 for a tensor (default), there will be no size checks when the service is reading or writing to the fd; the service will try to read or write the required amount.

For example, when reading from an input tensor, the service will try to read the required byte size from the file descriptor. Similarly for an output tensor, the service will try to write the required byte size to the file descriptor. Note that it is valid to set an fd offset using larodSetTensorFdOffset() even when size is 0.

Parameters
tensorPointer to an already allocated larodTensor.
sizeMaximum file descriptor capacity (bytes) to be set for tensor.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.

◆ larodSetTensorLayout()

bool larodSetTensorLayout ( larodTensor tensor,
const larodTensorLayout  layout,
larodError **  error 
)

Set layout of a tensor.

If the layout is set to LAROD_TENSOR_LAYOUT_UNSPECIFIED no sanity checks for the tensor layout (i.e. comparisons with what the model expects of the tensor layout) will be performed when running a job.

Parameters
tensorPointer to an already allocated larodTensor.
layoutLayout as specified by larodTensorLayout.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodSetTensorPitches()

bool larodSetTensorPitches ( larodTensor tensor,
const larodTensorPitches pitches,
larodError **  error 
)

Set pitches of a tensor.

If the pitches member len is set to 0 no sanity checks for the tensor pitches (i.e. comparisons with what the model expects of the tensor pitches) will be performed when running a job. See larodTensorPitches for the definition of pitches.

Parameters
tensorPointer to an already allocated larodTensor.
pitchesPointer to larodTensorPitches. The contents of the struct will be copied into tensor.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if any errors occur, otherwise true.

◆ larodTrackTensor()

bool larodTrackTensor ( larodConnection conn,
larodTensor tensor,
larodError **  error 
)

Start tracking a tensor in the service.

Can be called in order to let the service keep track of tensor. The service will do its best to cache resources (e.g. memory mapping of the tensor's fd) so that setup-related operations only have to be done once for each tracked tensor recurring in the service. This is desirable from a performance perspective.

Once this function is called on tensor, its file descriptor can not be replaced (c.f. larodSetTensorFd()). This also applies to the fd size, fd offset and fd props of tensor (c.f. larodSetTensorFdSize(), larodSetTensorFdOffset() and larodSetTensorFdProps(), respectively). Furthermore, this function should only be called once per larodTensor even if the tensor is used for more than one larodModel.

Note
A total maximum of 32 tensors can be tracked for a given conn.
Parameters
connAn initialized connection handle.
tensorPointer to an already allocated larodTensor.
errorAn uninitialized handle to an error. error can also be NULL if one does not want any error information. In case of errors (when return value is false), it must later be deallocated with larodClearError().
Returns
False if error occurred, otherwise true.