Update header file documentation22.11-rc222.11

Update documentation in driver header file.

Some functions were inconsistently returning boolean status. These
functions have been updated to return integer status, with 0 on
success and negative error code on failure.

Change-Id: Ie044bf5b4f2daaff348e698fa6147472dbc582a9

2 files changed, 127 insertions, 36 deletions

diff --git a/include/ethosu_driver.h b/include/ethosu_driver.h
index 187d49a..77a015c 100644
--- a/include/ethosu_driver.h
+++ b/include/ethosu_driver.h
@@ -98,49 +98,102 @@ enum ethosu_request_clients
 
 /**
  * Interrupt handler to be called on IRQ from Ethos-U
+ *
+ * @param drv       Pointer to driver handle
  */
 void ethosu_irq_handler(struct ethosu_driver *drv);
 
-/*
+/**
  * Flush/clean the data cache by address and size. Passing NULL as p argument
  * expects the whole cache to be flushed.
+ *
+ * Addresses passed to this function must be 16 byte aligned.
+ *
+ * @param p         16 byte aligned address
+ * @param bytes     Size of memory block in bytes
  */
-
 void ethosu_flush_dcache(uint32_t *p, size_t bytes);
-/*
+
+/**
  * Invalidate the data cache by address and size. Passing NULL as p argument
  * expects the whole cache to be invalidated.
+ *
+ * Addresses passed to this function must be 16 byte aligned.
+ *
+ * @param p         16 byte aligned address
+ * @param bytes     Size in bytes
  */
 void ethosu_invalidate_dcache(uint32_t *p, size_t bytes);
 
-/*
- * Minimal sempahore and mutex implementation for baremetal applications. See
+/**
+ * Minimal mutex implementation for baremetal applications. See
  * ethosu_driver.c.
+ *
+ * @return Pointer to mutex handle
  */
 void *ethosu_mutex_create(void);
+
+/**
+ * Minimal sempahore implementation for baremetal applications. See
+ * ethosu_driver.c.
+ *
+ * @return Pointer to semaphore handle
+ */
 void *ethosu_semaphore_create(void);
-/*
- * Returns:
- *   -1 on error
- *    0 on success
+
+/**
+ * Lock mutex.
+ *
+ * @param mutex     Pointer to mutex handle
+ * @returns 0 on success, else negative error code
  */
 int ethosu_mutex_lock(void *mutex);
+
+/**
+ * Unlock mutex.
+ *
+ * @param mutex     Pointer to mutex handle
+ * @returns 0 on success, else negative error code
+ */
 int ethosu_mutex_unlock(void *mutex);
+
+/**
+ * Take semaphore.
+ *
+ * @param sem       Pointer to semaphore handle
+ * @returns 0 on success, else negative error code
+ */
 int ethosu_semaphore_take(void *sem);
+
+/**
+ * Give semaphore.
+ *
+ * @param sem       Pointer to semaphore handle
+ * @returns 0 on success, else negative error code
+ */
 int ethosu_semaphore_give(void *sem);
 
-/*
- * Callbacks for begin/end of inference. user_data pointer is passed to the
- * ethosu_invoke() call and forwarded to the callback functions.
+/**
+ * Callback invoked just before the inference is started.
+ *
+ * @param drv       Pointer to driver handle
+ * @param user_arg  User argument provided to ethosu_invoke_*()
  */
 void ethosu_inference_begin(struct ethosu_driver *drv, void *user_arg);
+
+/**
+ * Callback invoked just after the inference has completed.
+ *
+ * @param drv       Pointer to driver handle
+ * @param user_arg  User argument provided to ethosu_invoke_*()
+ */
 void ethosu_inference_end(struct ethosu_driver *drv, void *user_arg);
 
 /**
  * Remapping command stream and base pointer addresses.
  *
  * @param address   Address to be remapped.
- * @param index     -1: command stream, 0-n base address index
+ * @param index     -1 command stream, 0-n base address index
  *
  * @return Remapped address
  */
@@ -152,6 +205,14 @@ uint64_t ethosu_address_remap(uint64_t address, int index);
 
 /**
  * Initialize the Ethos-U driver.
+ *
+ * @param drv               Pointer to driver handle
+ * @param base_address      NPU register base address
+ * @param fast_memory       Fast memory area, used for Ethos-U65 with spilling
+ * @param fast_memory_size  Size in bytes of fast memory area
+ * @param secure_enable     Configure NPU in secure- or non-secure mode
+ * @param privilege_enable  Configure NPU in privileged- or non-privileged mode
+ * @return 0 on success, else negative error code
  */
 int ethosu_init(struct ethosu_driver *drv,
                 const void *base_address,
@@ -162,39 +223,64 @@ int ethosu_init(struct ethosu_driver *drv,
 
 /**
  * Deinitialize the Ethos-U driver.
+ *
+ * @param drv       Pointer to driver handle
  */
 void ethosu_deinit(struct ethosu_driver *drv);
 
 /**
  * Soft resets the Ethos-U device.
+ *
+ * @param drv       Pointer to driver handle
+ * @return 0 on success, else negative error code
  */
-bool ethosu_soft_reset(struct ethosu_driver *drv);
+int ethosu_soft_reset(struct ethosu_driver *drv);
 
 /**
  * Request to disable Q-channel power gating of the Ethos-U device.
  * Power requests are ref.counted. Increases count.
  * (Note: clock gating is made to follow power gating)
+ *
+ * @param drv       Pointer to driver handle
+ * @return 0 on success, else negative error code
  */
-bool ethosu_request_power(struct ethosu_driver *drv);
+int ethosu_request_power(struct ethosu_driver *drv);
 
 /**
  * Release disable request for Q-channel power gating of the Ethos-U device.
  * Power requests are ref.counted. Decreases count.
+ *
+ * @param drv       Pointer to driver handle
  */
 void ethosu_release_power(struct ethosu_driver *drv);
 
 /**
  * Get Ethos-U driver version.
+ *
+ * @param ver       Driver version struct
  */
 void ethosu_get_driver_version(struct ethosu_driver_version *ver);
 
 /**
  * Get Ethos-U hardware information.
+ *
+ * @param drv       Pointer to driver handle
+ * @param hw        Hardware information struct
  */
 void ethosu_get_hw_info(struct ethosu_driver *drv, struct ethosu_hw_info *hw);
 
 /**
- * Invoke Vela command stream.
+ * Invoke command stream.
+ *
+ * @param drv               Pointer to driver handle
+ * @param custom_data_ptr   Custom data payload
+ * @param custom_data_size  Size in bytes of custom data
+ * @param base_addr         Array of base address pointers
+ * @param base_addr_size    Size in bytes of each address in base_addr
+ * @param num_base_addr     Number of elements in base_addr array
+ * @param user_arg          User argument, will be passed to
+ *                          ethosu_inference_begin() and ethosu_inference_end()
+ * @return 0 on success, else negative error code
  */
 int ethosu_invoke_v3(struct ethosu_driver *drv,
                      const void *custom_data_ptr,
@@ -208,11 +294,10 @@ int ethosu_invoke_v3(struct ethosu_driver *drv,
     ethosu_invoke_v3(drv, custom_data_ptr, custom_data_size, base_addr, base_addr_size, num_base_addr, 0)
 
 /**
- * Invoke Vela command stream using async interface.
+ * Invoke command stream using async interface.
  * Must be followed by call(s) to ethosu_wait() upon successful return.
- * Returns
- *   -1 on error
- *    0 on success
+ *
+ * @see ethosu_invoke_v3 for documentation.
  */
 int ethosu_invoke_async(struct ethosu_driver *drv,
                         const void *custom_data_ptr,
@@ -226,26 +311,32 @@ int ethosu_invoke_async(struct ethosu_driver *drv,
  * Wait for inference to complete (block=true)
  * Poll status or finish up if inference is complete (block=false)
  * (This function is only intended to be used in conjuction with ethosu_invoke_async)
- * Returns
- *    1 on inference running (only for block=false)
- *    0 on inference success
- *   -1 on inference error
- *   -2 on inference not invoked
+ *
+ * @param drv       Pointer to driver handle
+ * @param block     If call should block if inference is running
+ * @return -2 on inference not invoked, -1 on inference error, 0 on success, 1 on inference running
  */
 int ethosu_wait(struct ethosu_driver *drv, bool block);
 
 /**
- * Reserves a driver to execute inference with
+ * Reserves a driver to execute inference with. Call will block until a driver
+ * is available.
+ *
+ * @return Pointer to driver handle.
  */
 struct ethosu_driver *ethosu_reserve_driver(void);
 
 /**
- * Change driver status to available
+ * Release driver that was previously reserved with @see ethosu_reserve_driver.
+ *
+ * @param drv       Pointer to driver handle
  */
 void ethosu_release_driver(struct ethosu_driver *drv);
 
 /**
- * Static inline for backwards-compatibility
+ * Static inline for backwards-compatibility.
+ *
+ * @see ethosu_invoke_v3 for documentation.
  */
 static inline int ethosu_invoke_v2(const void *custom_data_ptr,
                                    const int custom_data_size,
diff --git a/src/ethosu_driver.c b/src/ethosu_driver.c
index 11c51f6..4ddcb6c 100644
--- a/src/ethosu_driver.c
+++ b/src/ethosu_driver.c
@@ -344,7 +344,7 @@ static int handle_command_stream(struct ethosu_driver *drv, const uint8_t *cmd_s
     }
 
     // Request power gating disabled during inference run
-    if (!ethosu_request_power(drv))
+    if (ethosu_request_power(drv))
     {
         LOG_ERR("Failed to request power");
         return -1;
@@ -437,13 +437,13 @@ void ethosu_deinit(struct ethosu_driver *drv)
     drv->dev = NULL;
 }
 
-bool ethosu_soft_reset(struct ethosu_driver *drv)
+int ethosu_soft_reset(struct ethosu_driver *drv)
 {
     // Soft reset the NPU
     if (ethosu_dev_soft_reset(drv->dev) != ETHOSU_SUCCESS)
     {
         LOG_ERR("Failed to soft-reset NPU");
-        return false;
+        return -1;
     }
 
     // Update power and clock gating after the soft reset
@@ -451,24 +451,24 @@ bool ethosu_soft_reset(struct ethosu_driver *drv)
                                    drv->power_request_counter > 0 ? ETHOSU_CLOCK_Q_DISABLE : ETHOSU_CLOCK_Q_ENABLE,
                                    drv->power_request_counter > 0 ? ETHOSU_POWER_Q_DISABLE : ETHOSU_POWER_Q_ENABLE);
 
-    return true;
+    return 0;
 }
 
-bool ethosu_request_power(struct ethosu_driver *drv)
+int ethosu_request_power(struct ethosu_driver *drv)
 {
     // Check if this is the first power request, increase counter
     if (drv->power_request_counter++ == 0)
     {
         // Always reset to a known state. Changes to requested
         // security state/privilege mode if necessary.
-        if (ethosu_soft_reset(drv) == false)
+        if (ethosu_soft_reset(drv))
         {
             LOG_ERR("Failed to request power for Ethos-U");
             drv->power_request_counter--;
-            return false;
+            return -1;
         }
     }
-    return true;
+    return 0;
 }
 
 void ethosu_release_power(struct ethosu_driver *drv)