Below is a description of API-breaking changes in major version updates of the larod API. This document can thus serve as a guide for developers that want to port their applications to the latest version.

Note that larod features not only ABI but also API backwards compatibility. Using an older API version when compiling with a newer version of larod requires a #define LAROD_API_VERSION_X, see "Backwards compatibility" in introduction-for-app-developers for details.

Table of Contents

Changes in the larod API
- larod 3.0 (AXIS OS 10.7.0)
- larod 2.0 (AXIS OS 10.4.0)
  - Set chip when loading model
  - Rename "inference" to "job"

larod 3.0 (AXIS OS 10.7.0)

larodDevice replaces larodChip

The larodChip enum has been replaced by a larodDevice handle. The following of the API is therefore deprecated:

enum larodChip;
const char* larodGetChipName(const larodChip chip);
bool larodListChips(larodConnection* conn, larodChip** chips,
                    size_t* numChips, larodError** error);
larodChip larodGetModelChip(const larodModel* model,
                            larodError** error);

To replace them, the larod 3.0 API introduces:

typedef struct larodDevice larodDevice;
const larodDevice* larodGetDevice(const larodConnection* conn, const char* name,
                                  const uint32_t instance, larodError** error);
const char* larodGetDeviceName(const larodDevice* dev, larodError** error);
bool larodGetDeviceInstance(const larodDevice* dev, uint32_t* instance,
                            larodError** error);
const larodDevice** larodListDevices(larodConnection* conn, size_t* numDevices,
                                     larodError** error);
const larodDevice* larodGetModelDevice(const larodModel* model,
                                       larodError** error);

Instead of choosing a larodChip when loading a model, a user of liblarod should now ask for a larodDevice handle with larodGetDevice(), e.g.

const larodDevice* dev = larodGetDevice(conn, "cpu-tflite", 0, &error);

The list of available strings like "cpu-tflite" can be found in nn-inference.md. This handle is then passed on when loading model, which means that the following functions have a signature change:

larodModel* larodLoadModel(larodConnection* conn, const int fd,
                           const larodDevice* dev /* changed */,
                           const larodAccess access, const char* name,
                           const larodMap* params, larodError** error);
bool larodLoadModelAsync(larodConnection* conn, const int inFd,
                         const larodDevice* dev /* changed */,
                         const larodAccess access,
                         const char* name, const larodMap* params,
                         larodLoadModelCallback callback, void* userData,
                         larodError** error);

Migration table from larodChip enums to larodDevice strings

2.0 enum	3.0 string
`LAROD_CHIP_DEBUG`	`debug-device`
`LAROD_CHIP_TFLITE_CPU`	`cpu-tflite`
`LAROD_CHIP_TPU`	`google-edge-tpu-tflite`
`LAROD_CHIP_CVFLOW_NN`	`ambarella-cvflow`
`LAROD_CHIP_TFLITE_GLGPU`	`gpu-tflite`
`LAROD_CHIP_CVFLOW_PROC`	`ambarella-cvflow-proc`
`LAROD_CHIP_ACE`	`axis-a8-ace-proc`
`LAROD_CHIP_LIBYUV`	`cpu-proc`
`LAROD_CHIP_TFLITE_ARTPEC8DLPU`	`axis-a8-dlpu-tflite`
`LAROD_CHIP_OPENCL`	`axis-a7-gpu-proc` (deprecated)
`LAROD_CHIP_OPENCL`	`axis-a8-gpu-proc`
`LAROD_CHIP_OPENCL`	`axis-a8-dlpu-proc` (see below)

Starting from larod 3.0 LAROD_CHIP_OPENCL is split into multiple devices, one for each OpenCL-supporting hardware, as shown in the table above. If you are using this enum on ARTPEC-7 you should use axis-a7-gpu-proc. If you are using this enum on ARTPEC-8 you may use either axis-a8-gpu-proc, which will select the GPU, or axis-a8-dlpu-proc, which selects the DLPU. Either should work.

Note that axis-a7-gpu-proc is deprecated and is no longer being tested. It is recommended to use cpu-proc instead.

New parameters in larodDestroyTensors()

When using buffers that are allocated by larod (using e.g. larodAllocModelInputs()), larodDestroyTensors() now also deallocate these buffers. Therefore the function signature has been changed to

bool larodDestroyTensors(larodConnection* conn /* new */,
                         larodTensor*** tensors, size_t numTensors,
                         larodError** error /* new */);

Cache policy

Clients that use DMA buffers are now responsible for handling all the cache synchronization. See "About dma-buf" in nn-inference.md for details.

Non-breaking changes

larod 3.4.2 (AXIS OS 12.5.21) Removed artificial limitation on number of tracked tensors in larodTrackTensor. It is now only limited by the amount of available memory.

larod 3.3.0 (AXIS OS 12.4.2) Added the larodExportModel function.

larod 3.2.69 (AXIS OS 11.8.4) The public access type is marked as deprecated.

larod 3.2.0 (AXIS OS 11.4.9) Added support for external power control. The functions larodLoadModel and larodRunJob can now return LAROD_ERROR_POWER_NOT_AVAILABLE if there is not enough power available to use the DLPU. See introduction-for-app-developers.md for more details.

larod 3.1.36 (AXIS OS 10.10.9) Version 1 and version 2 of the larod API are marked as deprecated. Define LAROD_API_VERSION_1 or LAROD_API_VERSION_2 in order to use them.

larod 3.1.9 (AXIS OS 10.8.0) Added the larodGetTensorByteSize function.

larod 2.0 (AXIS OS 10.4.0)

Set chip when loading model

Chip is now tied to the larodModel being loaded instead of the larodConnection. Hence, the following functions are removed:

larodGetChipType()
larodGetChipId()
larodSetChipId()
larodSetChip()

Instead, one specifies the chip as an argument to larodLoadModel() and larodLoadModelAsync(). There is also an additional argument, larodMap, that can be used for back end specific parameters. When converting code from v1.0 to v2.0, the larodMap parameter can be set to NULL.

Rename "inference" to "job"

Since larod 2.0 introduces image processing capabilities, larod is no longer a pure inference service. Therefore, the word "Inference" has been replaced with "Job". For example, larodInferenceRequest() is now called larodJobRequest(). Additionally, larodCreateJobRequest() needs a larodMap parameter. When converting code from v1.0 to v2.0 the larodMap parameter can be set to NULL.

The following tables show the errors, structs and functions that have changed name, respectively:

1.0	2.0
`LAROD_ERROR_INFERENCE`	`LAROD_ERROR_JOB`

1.0	2.0
`larodInferenceRequest`	`larodJobRequest`

1.0	2.0
`larodCreateInferenceRequest`	`larodCreateJobRequest`
`larodDestroyInferenceRequest`	`larodDestroyJobRequest`
`larodSetInferenceRequestModel`	`larodSetJobRequestModel`
`larodSetInferenceRequestInputs`	`larodSetJobRequestInputs`
`larodSetInferenceRequestOutputs`	`larodSetJobRequestOutputs`
`larodSetInferenceRequestPriority`	`larodSetJobRequestPriority`
`larodRunInference`	`larodRunJob`
`larodRunInferenceAsync`	`larodRunJobAsync`
`larodRunInferenceCallback`	`larodRunJobCallback`