openamp: improve documentation

Author: kbumsik

cores/arduino/stm32/OpenAMP/openamp.c

@@ -39,6 +39,9 @@ struct rpmsg_virtio_device rvdev;
 
 static metal_phys_addr_t shm_physmap;
 
+/**
+ * @brief OpenAMP libmetal device structure
+ */
 struct metal_device shm_device = {
   .name = SHM_DEVICE_NAME,
   .num_regions = 2,
@@ -51,6 +54,12 @@ struct metal_device shm_device = {
   .irq_info = NULL
 };
 
+/**
+ * @brief Initialize OpenAMP shared memory (libmetal and resource table)
+ *
+ * @param RPMsgRole: RPMSG_REMOTE - Device is remote (slave)
+ * @retval 0 on success
+ */
 static int OPENAMP_shmem_init(int RPMsgRole)
 {
   int status = 0;
@@ -98,6 +107,11 @@ static int OPENAMP_shmem_init(int RPMsgRole)
   return 0;
 }
 
+/**
+ * @brief Initialize the openamp framework
+ *
+ * @retval 0 when success
+ */
 int OPENAMP_Init()
 {
   struct fw_rsc_vdev_vring *vring_rsc;
@@ -141,18 +155,37 @@ int OPENAMP_Init()
   return 0;
 }
 
+/**
+ * @brief Deinitialize the openamp framework
+ */
 void OPENAMP_DeInit()
 {
   rpmsg_deinit_vdev(&rvdev);
 
   metal_finish();
 }
 
+/**
+ * @brief Initialize the endpoint struct
+ *
+ * @param ept: virtio rpmsg endpoint
+ */
 void OPENAMP_init_ept(struct rpmsg_endpoint *ept)
 {
   rpmsg_init_ept(ept, "", RPMSG_ADDR_ANY, RPMSG_ADDR_ANY, NULL, NULL);
 }
 
+/**
+ * @brief Create and register the name service endpoint
+ *
+ * @param ept: virtio rpmsg endpoint
+ * @param name: virtio rpmsg name service name
+ * @param dest: message destination address. Set RPMSG_ADDR_ANY if
+ *              the host processor will decide this
+ * @param cb: virtio rpmsg endpoint callback (receive)
+ * @param unbind_cb: virtio rpmsg endpoint destroy callback
+ * @retval 0 when success
+ */
 int OPENAMP_create_endpoint(struct rpmsg_endpoint *ept, const char *name,
                             uint32_t dest, rpmsg_ept_cb cb,
                             rpmsg_ns_unbind_cb unbind_cb)

cores/arduino/stm32/OpenAMP/openamp.h

@@ -30,28 +30,18 @@ extern "C" {
 #include <openamp/rpmsg.h>
 #include "openamp_conf.h"
 
-
 #define OPENAMP_send  rpmsg_send
 #define OPENAMP_destroy_ept rpmsg_destroy_ept
 
-/* Initialize the openamp framework*/
 int OPENAMP_Init(void);
-
-/* Deinitialize the openamp framework*/
 void OPENAMP_DeInit(void);
-
-/* Initialize the endpoint struct*/
 void OPENAMP_init_ept(struct rpmsg_endpoint *ept);
 
-/* Create and register the endpoint */
 int OPENAMP_create_endpoint(struct rpmsg_endpoint *ept, const char *name,
                             uint32_t dest, rpmsg_ept_cb cb,
                             rpmsg_ns_unbind_cb unbind_cb);
-
-/* Check for new rpmsg reception */
-void OPENAMP_check_for_message(void);
-
-/* Wait loop on endpoint ready ( message dest address is know)*/
+void OPENAMP_check_for_tx_message(void);
+void OPENAMP_check_for_rx_message(void);
 void OPENAMP_Wait_EndPointready(struct rpmsg_endpoint *rp_ept);
 
 #ifdef __cplusplus