[NRC/N10] NPU driver API interface

In http://suprem.sec.samsung.net/confluence/pages/viewpage.action?pageId=126187176
this is about N10 and N10's dependencies

V1:
Added details regarding the ioctl calls and signal handling

V2:
Updated interface to accomodate update in overall design for NPU design

V3:
Updated to use offset, and minor bug fixes

V4:
Updated with ioctl design
UIO design needed access to physical address in user side

V5:
Added interface to pass dmabuf_fd to kernel driver for physical address access
Added an extra identifier when setting up npu device

V6:
Updated based on blocking I/O

Signed-off-by: Parichay Kapoor <pk.kapoor@samsung.com>

diff --git a/core/libnpu-core/include/NPUdrvAPI.h b/core/libnpu-core/include/NPUdrvAPI.h
index 4f38fab..8336b46 100644 (file)
--- a/core/libnpu-core/include/NPUdrvAPI.h
+++ b/core/libnpu-core/include/NPUdrvAPI.h
@@ -1,21 +1,205 @@
 /**
  * Proprietary
  * Copyright (C) 2019 Samsung Electronics
+ * Copyright (C) 2019 Parichay Kapoor <pk.kapoor@samsung.com>
  * Copyright (C) 2019 MyungJoo Ham <myungjoo.ham@samsung.com>
  */
 /**
  * @file NPUdrvAPI.h
- * @date 15 Apr 2019
+ * @date 7 June 2019
  * @brief API to access SR NPU device driver.
  * @see http://suprem.sec.samsung.net/confluence/display/ODLC/Software+Stack
+ * @author Parichay Kapoor <pk.kapoor@samsung.com>
  * @author MyungJoo Ham <myungjoo.ham@samsung.com>
  * @bug No known bugs except for NYI items
  *
- * To packagers: this is used by NPURuntime-Core.
+ * To packagers: this is used by NPU Engine (NE).
  */
 
 #ifndef __NPU_CORE_NPUdrvAPI_H__
 #define __NPU_CORE_NPUdrvAPI_H__
 
+#include <stdint.h>
+#include <linux/srnpu.h>
+#include <typedef.h>
+
+
+/**
+ * @brief open the npu device
+ * @param[in] dev_id index of the device to be opened
+ * @return file descriptor is not error. otherwise -1
+ *
+ * @details This will open the device using the driver (exposed via /dev).
+ *
+ * @note dev_id is used to indicate device in case of multiple devices
+ */
+int
+npu_open (unsigned int dev_id);
+
+
+/**
+ * @brief close the npu device
+ * @param[in] fd file descriptor of the device
+ * @returns 0 on success, -1 on error
+ *
+ * @details Stop allowing more computations to be run.
+ *          Clear the current state.
+ *          Finally, close the device.
+ */
+int
+npu_close (int fd);
+
+
+/**
+ * @brief set mode for the NPU to operate in
+ * @param[in] fd file descriptor of the device
+ * @param[in] mode mode of operation for the NPU
+ *
+ * @details Set mode for NPU to operate. This will set the mode in kernel driver
+ *          as well.
+ *
+ *          ICAM allows the input buffer to be set and enabling the device from
+ *          the shared kernel driver. HOST mode sets the ENABLE in
+ *          npu_setup_device().
+ */
+void
+npu_set_mode (int fd, npu_input_opmode mode);
+
+
+/**
+ * @brief run the npu based on the set configuration
+ * @param[in] fd file descriptor of the device
+ * @return 0 on success, -1 on error
+ *
+ * @details this function will make the ioctl call to the kernel driver. A
+ *          single ioctl call will be made to pass the memory addresses.
+ *          The data will be page aligned. The data will be packed as below:
+ *
+ *          (32bits) NPU_PROG_BASE, (32bits) NPU_PROG_SIZE,
+ *          (32bits) NPU_ACT_BASE0, (32bits) NPU_ACT_BASE1,
+ *          (32bits) NPU_WGT_BASE,  (8bits) ENABLE
+ *
+ *          argp argmuent to ioctl will be IN parameter with size 21 bytes.
+ *          ENABLE is set dependent on the mode set on the device
+ *
+ * @note Compute ready check should be performed by the driver before setting
+ *       the registers.
+ *
+ * @note this function call will block till the computation is not complete
+ *       if enable is set.
+ */
+int
+npu_setup_device (int fd);
+
+
+/**
+ * @brief wait for the device to get ready
+ * @param[in] fd file descriptor of the device
+ * @return NULL to error, else register values filled in struct
+ *
+ * @details this function will make the ioctl call to the kernel driver. A
+ *          single ioctl call will be made to check the status of various status
+ *          registers. argp argmuent to ioctl will be OUT parameter with size
+ *          4*N byte, where N is the number of status registers.
+ *
+ *          The returned struct should be freed by the caller.
+ *
+ * @note N42 should verify ready state for the NPU before setting up NPU.
+ */
+struct srnpu_status_arg *
+npu_get_status (int fd);
+
+
+/**
+ * @brief set the program instruction offset dram address and size
+ * @param[in] fd file descriptor of the device
+ * @param[in] program_offset_addr offset address for the instructions (NPU_PROG_BASE)
+ * @param[in] program_size size of the program instructions (NPU_PROG_SIZE)
+ * @return 0 on success, -1 on error
+ *
+ * @note The addr value act as offset from the base physical address
+ */
+int
+npu_set_program (int fd, uint64_t program_offset_addr, uint64_t program_size);
+
+
+/**
+ * @brief set the offset dram address for the model parameters
+ * @param[in] fd file descriptor of the device
+ * @param[in] weight_offset_addr offset address for storing weights (NPU_WGT_BASE)
+ * @return 0 on success, -1 on error
+ *
+ * @note The addr value act as offset from the base physical address
+ */
+int
+npu_set_weight (int fd, uint64_t weight_offset_addr);
+
+
+/**
+ * @brief set the offset dram address for the activation/input
+ * @param[in] fd file descriptor of the device
+ * @param[in] activation_offset_addr0 offset address for storing weights (NPU_ACT_BASE0)
+ * @param[in] activation_offset_addr1 offset address for storing weights (NPU_ACT_BASE1)
+ * @return 0 on success, -1 on error
+ *
+ * @note The addr value act as offset from the base physical address
+ */
+int
+npu_set_activation (int fd, uint64_t activation_offset_addr0,
+               uint64_t activation_offset_addr1);
+
+
+/**
+ * @brief set the base dram address
+ * @param[in] fd file descriptor of the device
+ * @param[in] dmabuf_fd to extract the base physical address
+ * @param[in] offset1 to get start of first memory region
+ * @param[in] offset2 to get start of second memory region
+ * @return 0 on success, -1 on error
+ *
+ * @details this function will make the ioctl call to the kernel driver. A
+ *          single ioctl call will be made to share the dmabuf_fd and offsets
+ *          with the kernel driver. Kernel driver will extract the base
+ *          physical address from the dmabuf_fd.
+ *
+ *          dmabuf_fd should be set before enabling the device.
+ *
+ * @note This base address is common for input, output and intermediate data.
+ */
+int
+npu_set_buffer (int fd, int dmabuf_fd, uint64_t offset0, uint64_t offset1);
+
+
+/**
+ * @brief check if the device to get ready for the next computation
+ * @param[in] fd file descriptor of the device
+ * @return 0 if ready, negative if not ready or error
+ *
+ * @details this function will make the ioctl call to the kernel driver. A
+ *          single ioctl call will be made to check the status of the register
+ *          CP_PROC_STAT and processed result will be result will be returned
+ *          back. argp argmuent to ioctl will be OUT parameter with size 1 byte.
+ *
+ *          This is a subset of npu_get_status() for convenience.
+ *
+ * @note N42 should verify ready state for the NPU before setting up NPU.
+ */
+int
+npu_check_compute_ready (int fd);
+
+
+/**
+ * @brief check if the device to get ready for the next computation
+ * @param[in] fd file descriptor of the device
+ * @return 0 if ready, negative if not ready or error
+ *
+ * @details this function will make the ioctl call to the kernel driver. This
+ *          function will block till the npu compute ready flag is not set.
+ *
+ * @note This function should be called when waiting for iCAM to finish its output
+ */
+int
+npu_wait_compute_ready (int fd);
+
+#endif /** __NPU_CORE_NPUdrvAPI_H__ */
 
-#endif /* __NPU_CORE_NPUdrvAPI_H__ */