Added more documentation for EdmaMgr APIs.

[mfp/fcdev.git] / packages / ti / sdo / fc / edmamgr / edmamgr.h

diff --git a/packages/ti/sdo/fc/edmamgr/edmamgr.h b/packages/ti/sdo/fc/edmamgr/edmamgr.h
index 4ead7a6eaddfde41fca83d4e8432f887408ff721..38cc60daa0ee9c4b827aec6662e259f6c8aa0282 100644 (file)
--- a/packages/ti/sdo/fc/edmamgr/edmamgr.h
+++ b/packages/ti/sdo/fc/edmamgr/edmamgr.h
@@ -34,6 +34,15 @@
  *
  *  @brief      EdmaMgr Definitions - Functional library for use
  *              with the EDMA3 DMA peripheral.
+ *
+ *  The intent of the EdmaMgr component is to provide a simple and intuitive
+ *  interface for acquiring and using EDMA3 resources for asynchronous data
+ *  transfers.
+ *
+ *  Once the framework provides the initial configuration to EdmaMgr_init(),
+ *  malloc/free style APIs are used to obtain/release resources. The actual
+ *  transfer has been abstracted to multiple APIs which can transfer data of
+ *  various dimensions.
  */
 
 /**
@@ -85,15 +94,24 @@ typedef struct {
 /**
  *  @brief      Initialize EdmaMgr
  *
- *  @param[in]  proc_id         Processor ID
- *  @param[in]  edma3_config    Optional edma3_config
+ *  @param[in]  proc_id         Processor ID. This ID is used to index into the
+ *                              EDMA3_InstanceInitConfig array pointed to by the
+ *                              ti_sdo_fc_edmamgr_edma3RegionConfig variable.
+ *
+ *  @param[in]  edma3_config    Optional edma3_config which will override the
+ *                              configuration which is pointed to by
+ *                              ti_sdo_fc_edmamgr_edma3RegionConfig.
  *
  *  @retval     EdmaMgr_SUCCESS         @copydoc EdmaMgr_SUCCESS
  *  @retval     EdmaMgr_ERROR_INVARG    @copydoc EdmaMgr_ERROR_INVARG
  *  @retval     EdmaMgr_ERROR_INVCFG    @copydoc EdmaMgr_ERROR_INVCFG
  *  @retval     EdmaMgr_ERROR_RMANINIT  @copydoc EdmaMgr_ERROR_RMANINIT
  *
- *  @remarks    @c edma3_config maybe be NULL to accept default values.
+ *  @remarks    @c edma3_config may be NULL to accept default values.
+ *
+ *  @remarks    The FC product includes an example (ex23_edmamgr) which
+ *              demonstrates how to set up a @c ti_sdo_fc_edma3RegionConfig
+ *              variable.
  */
 int32_t EdmaMgr_init
 (
@@ -431,12 +449,19 @@ int32_t EdmaMgr_copy2D2DSepLinked
 );
 
 /**
- *  @brief      Perform a fast copy
+ *  @brief      Perform a fast copy. This API inherits the transfer configuration
+ *              of a previous transfer and only modifies the @c src and @c dst
+ *              addresses.
  *
  *  @param[in]  h     Handle returned from EdmaMgr_alloc().
  *  @param[in]  src   Source address
  *  @param[in]  dst   Destination address
  *
+ *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
+ *
+ *  @pre        A non-linked transfer must have been completed on handle @c h
+ *              before calling this function.
+ *
  *  @sa EdmaMgr_copyLinkedFast
  */
 int32_t EdmaMgr_copyFast
@@ -447,13 +472,20 @@ int32_t EdmaMgr_copyFast
 );
 
 /**
- *  @brief      Perform a linked fast copy
+ *  @brief      Perform a linked fast copy. This API inherits the transfer
+ *              configuration of a previous transfer and only modifies the
+ *              @c src and @c dst addresses.
  *
  *  @param[in]  h     Handle returned from EdmaMgr_alloc().
  *  @param[in]  src[] Array of source addresses
  *  @param[in]  dst[] Array of destination addresses
  *  @param[in]  num_transfers Number of transfers
  *
+ *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
+ *
+ *  @pre        A linked transfer must have been completed on handle @c h
+ *              before calling this function.
+ *
  *  @sa EdmaMgr_copyLinkedFast
  */
 int32_t EdmaMgr_copyLinkedFast