Skip to content

Latest commit

 

History

History
303 lines (223 loc) · 11.1 KB

API.md

File metadata and controls

303 lines (223 loc) · 11.1 KB
Raw

CHaiDNN-v2
Analysis and Eval
Supported Layers Performance/Resource Utilization
Performance Eval
Design and Development
API Reference Quantization User Guide for CHaiDNN Model Zoo Running Inference on new Network
Creating SDx GUI Project Configurable Parameters Custom Platform Generation Software Layer Plugin
SDSoC Environment User Guide Hardware-Software Partitioning for Performance

API Reference

CHaiDNN APIs enables users an easy way to utilize the library. The APIs are grouped into the following three categories.

  1. Core
  2. Pre and Post processing
  3. Utility

Core

Core APIs are described below.

Initialization

xiInit() returns handle to a job-queue used by xiExec().

Syntax

void* xiInit( char *dirpath,  
		char* prototxt,  
		char* caffemodel,
		io_layer_info *io_layer_info_ptr,
		int numImg_to_process,
		bool is_first_layer,
		std::string start_layer,
		std::string end_layer);

Parameters

  • dirpath : Directory Path of the Network. Keep all caffe files in this directory (.prototxt, .caffemodel).

  • prototxt : Name of the prototxt file existing inside "dirpath". <E.g. deploy.prototxt>

  • caffemodel : Name of the caffemodel file existing inside "dirpath". <E.g. SSD.caffemodel>

  • io_layer_info_ptr : Provides information about number of I/O buffers and their sizes.

  • numImg_to_process : Specifies the number of images to process. This version of CHaiDNN only supports a value of 2 for this parameter.

  • start_layer : String that represents the first layer of the network. If it is empty, first layer in the prototxt is taken by default.

  • end_layer : String that represents the last layer of the network. If it is empty, last layer in the prototxt is taken by default.

  • start_layer and end_layer is useful to extract and execute a particular sub-graph of the full network. Please visit here to see it could be used to optimize the inference.

  • is_first_layer : Set to true if start_layer is the first layer in prototxt.

  • return value : returns an opaque handle.

Execution

xiExec() makes use of handle generated by xiInit() and executes the graph.

Syntax

void xiExec(
	void *chai_handle,
	std::vector<void *> input,
	std::vector<void *> output);

Parameters

  • chai_handle : Handle to the graph compute initialized by xiInit.

  • input : Vector of input Buffers. Read Utility API can be used to intialize input buffers.

  • output : Vector of output Buffers. Create memory for output buffers. This will be filled with output of the network inside xiExec API. Output will be in CHaiDNN pack format.

A Note on Output Data from xiExec API

CHaiDNN always processes images in a batch size of 2. For different networks, the o/p data organization changes based on the last layer in the network. For now, we are supporting 3 different kinds of data organization for the o/p buffers.

  1. Classification Network For these kind of networks, the Softmax layer would be the last layer. Data organization for these kind of networks will be as follows. The output buffers will contain probability values for the number of classes in batch interleaved fashion. The index values will always start from 0.

    📃 Example: For GoogleNet, the output is probabilities of 1000 Classes. Position of the probability value gives the class ID (Starts from 0).(List of Class IDs can be found here)

  2. Detection Networks For these kind of networks, the last layer will most probably be NMS layer. The output of the NMS layer is box ID, class ID, score (probability), co-ordinates. Output of first image will be followed by output of second image.

    How to Interpret output data for detection networks?

    • First entry of the output buffer is the number of output boxes generated by the network for an Image.

      📃 Example:

        int nOutBoxes_batch0 = ((int*)outptr)[0];
    int nOutBoxes_batch1 = ((int*)outptr+(nOutBoxes_batch0*7+1))[0];
    • From second entry onwards the output is arranged in the below format. Each Box will have the following 7 values: 
      Box-ID,
ClassID,
Score(Prob),
Coordinates(Xmin, Ymin, Xmax, Ymax)
      This order will be followed for all the output boxes.
    • With number of output boxes, user can read all the output boxes generated by SSD.
    • Xmin, Ymin, Xmax, Ymax are floating point values. To get the correct pixel positions or co-ordinates of the boxes in the image, user has to multiply these values with input height/width (in case of SSD : 300 x 300).

  3. Segmentation Networks For these kind of networks, the output layer is Crop and the size of the output layer will be same as the input size of the network.

    The output will be written sequentially in raster scan order inside output buffers. Output of first image will be followed by output of second image.

    📃 Example: For AlexNet-FCN, the last layer is Crop and the output size is 500 x 500.

Release

Releases the memory.

Syntax

void xiRelease(void *chai_handle);

Parameters

  • chai_handle : Handle to the graph compute initialized by xiInit().

Pre and Post Processing

Pre and post processing APIs supports input image processing and output data processing. Pre processing includes mean subtraction and normalization of input image data. Post processing includes output write to text files.

Pre Processing

Performs mean subtraction and normalization of input data for given two images and returns the normalized data.

Syntax

int inputNormalization( std::vector<void *> input,
		int resize_h,
		int resize_w,
		char *img_path1,  
		char *img_path2,
		bool inp_mode,
		float *mean_ptr,
		float *var_ptr,
		int numImg_to_process,
		io_layer_info io_layer_info_ptr
		);

Parameters

  • input : Vector of input buffers. Create memory for input buffers with input size of network. These buffers will be filled with mean subtracted data inside inputNormalization function.

  • resize_h : Input resize height.

  • resize_w : Input resize width.

  • img_path1 : Path of first image.

  • img_path2 : Path of second image.

  • inp_mode : Set to true if normalization of input data required .

  • mean_ptr : Fill the buffer with mean values.

  • var_ptr : Fill the buffer with variance values.

  • numImg_to_process : Specifies the number of images to process. This version of CHaiDNN only supports a value of 2 for this parameter.

  • io_layer_info_ptr : Provides information about number of I/O buffers and their sizes and is initiated by the xiInit API.

  • return value : Returns zero value upon suceessfull execution.

Post Processing

Post processing API used to write output to text files.

Syntax

int outputWrite( char *dirpath,
		char *img_path,
		std::vector<void *> unpack_output,
		int numImg_to_process,
		io_layer_info io_layer_info_ptr
		);

Parameters

  • dirpath : Directory Path of the Network.

  • img_path : Path of the input image

  • unpack_output : Create memory for unpack_output buffers. This buffer will be filled with unpack output.

  • numImg_to_process : Specifies the number of images to process. This version of CHaiDNN only supports a value of 2 for this parameter

  • io_layer_info_ptr : Provides information about number of I/O buffers and their sizes and is initiated by the xiInit API

  • return value : Returns zero value upon successful execution

Utilities

Utility APIs are used for pack and unpacking of input and output data.

Read

xiInputRead() takes normalized data as input and generates packed input data required by CHaiDNN.

Syntax

int xiInputRead( std::vector<void *> noramalizeinput,
		std::vector<void *> input,
		int numImg_to_process,
		io_layer_info io_layer_info_ptr
		);

Parameters

  • normalizeinput : Buffer which holds normalized data.

  • input : Buffer will be filled with pack data inside xiInputRead API.

  • numImg_to_process : Specifies the number of images to process. This version of CHaiDNN only supports a value of 2 for this parameter.

  • io_layer_info_ptr : Provides information about number of I/O buffers and their sizes and is initiated by the xiInit API.

  • return value : Returns zero value upon successful execution.

Write

xiUnpackOutput() takes output of xiExec API and unpacks the data as per standard form.

Syntax

int xiUnpackOutput( std::vector<void *> exec_output,
		std::vector<void *> unpack_output,
		kernel_type_e out_kerType,
		int out_layer_size,
		int numImg_to_process
		);

Parameters

  • exec_output : Output buffer from xiExec API.

  • unpack_output : Create memory for unpack_output buffers. This buffer will be filled with unpack output inside xiUnpackOutput API.

  • out_kerType : Output layer type. Currently supported layers are SOFTMAX, CROP and NMS. Please refer output data session for more details.

  • out_layer_size : Size of the output layer.

  • numImg_to_process : Specifies the number of images to process. This version of CHaiDNN only supports a value of 2 for this parameter.

  • return value : Returns zero value upon successful execution.

Copyright© 2018 Xilinx