ncDeviceGetOption()

Info Value
Header mvnc.h
Library libmvnc.so
Version 2.0
See also struct ncDeviceHandle_t, ncDeviceOption_t, ncDeviceSetOption()

Overview

This function gets the value of an option for a neural compute device. The available options and possible values can be found in the ncDeviceOption_t enumeration.

Prototype

ncStatus_t ncDeviceGetOption(struct ncDeviceHandle_t* deviceHandle,
                             int option, void* data,
                             unsigned int* dataLength);

Parameters

Name Type Description
deviceHandle struct ncDeviceHandle_t* A pointer to an ncDeviceHandle_t struct for the device for which the option value will be retrieved. The device state must be NC_DEVICE_CREATED or NC_DEVICE_OPENED.
option int A value from the ncDeviceOption_t enumeration that specifies which option’s value will be retrieved.
data void* A pointer to a buffer where the value of the option will be copied. The size and type of data this points to will depend on the option that is specified. See ncDeviceOption_t for option data types.
dataLength unsigned int* A pointer to an unsigned int which contains the size, in bytes, of the buffer allocated by the caller for the data parameter.

Upon normal return (status code NC_OK), dataLength will be set to the number of bytes copied to the data buffer. In the event that the data buffer was an insufficient size to hold the option value, the return status code will be NC_INVALID_DATA_LENGTH and dataLength will be set to the size required to hold the option value.

Return

An appropriate value from the ncStatus_t enumeration.

If the data buffer was an insufficient size to hold the option value, the return status code will be NC_INVALID_DATA_LENGTH and dataLength will be set to the size required to hold the option value.

Notes

  • If you don’t know what value to use for dataLength, you can call this function once with a dataLength of 0 to have dataLength be set to the correct value and then allocate a correctly sized buffer and call this function again. See the example below.

Example

Get an option value when you know the correct data length:

#include <stdio.h>
#include <stdlib.h>
#include <mvnc.h>

int main(int argc, char** argv)
{
    ncStatus_t retCode;
    struct ncDeviceHandle_t* deviceHandlePtr;
    
    ncDeviceCreate(0, &deviceHandlePtr);
    
    /* Get the device state option value */  
    int deviceState;
    unsigned int dataLength = sizeof(int);
    retCode = ncDeviceGetOption(deviceHandlePtr, NC_RO_DEVICE_STATE, &deviceState, &dataLength);
    if (retCode != NC_OK)
    {
        // Failed to get the option.
        printf("ncDeviceGetOption Failed [%d].\n", retCode);
        ncDeviceDestroy(&deviceHandlePtr);
        exit(-1);
    }
    
    /* Use the device state as needed */
    printf("The device state is %d.\n", deviceState);

    // open, use and close the device here as needed    

    ncDeviceDestroy(&deviceHandlePtr);
    return 0;
}

Get an option value when you don’t know the correct data length:

#include <stdio.h>
#include <stdlib.h>
#include <mvnc.h>

int main(int argc, char** argv)
{
    ncStatus_t retCode;
    struct ncDeviceHandle_t* deviceHandlePtr;
    
    ncDeviceCreate(0, &deviceHandlePtr);
    
    /* Get the size of the option so we know what to allocate */  
    unsigned int dataLength = 0;
    retCode = ncDeviceGetOption(deviceHandlePtr, NC_RO_DEVICE_STATE, NULL, &dataLength);
    if (retCode == NC_INVALID_DATA_LENGTH)
    {   // we passed length too small (zero) and it should now be set to correct size
        void *optionPtr = NULL;
        optionPtr = malloc(dataLength);
        retCode = ncDeviceGetOption(deviceHandlePtr, NC_RO_DEVICE_STATE, optionPtr, &dataLength);
        if (retCode != NC_OK)
        {
            // Failed to get the option.
            printf("ncDeviceGetOption Failed [%d].\n", retCode);
            ncDeviceDestroy(&deviceHandlePtr);
            exit(-1);
        }
        /* Use the device state as needed */
        printf("The device state is %d.\n", *((int *)optionPtr));
        free(optionPtr);
        optionPtr = NULL;
    }
    else
    {
        // Failed to get the option size.
        printf("ncDeviceGetOption Failed to get the size[%d].\n", retCode);
        ncDeviceDestroy(&deviceHandlePtr);
        exit(-1);
    }

    // open, use and close the device here as needed    

    // done with device, destroy it.
    ncDeviceDestroy(&deviceHandlePtr);

    
    return 0;
}