SDOCM00115293 Linux transport interfaces need documentation
authorRamsey Harris <ramsey@ti.com>
Mon, 14 Sep 2015 17:34:22 +0000 (10:34 -0700)
committerAngela Stegmaier <angelabaker@ti.com>
Tue, 15 Sep 2015 20:56:34 +0000 (15:56 -0500)
Add documentation to Linux transport interface header files.

linux/include/ti/ipc/interfaces/IMessageQTransport.h
linux/include/ti/ipc/interfaces/INetworkTransport.h
linux/include/ti/ipc/interfaces/ITransport.h

index d003c5e7eb87eb985561d073ec4b4728aa2240ff..b67c07f8bc87d66e0c71231efd7c300278712b3c 100644 (file)
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ *  @file linux/include/ti/ipc/interfaces/IMessageQTransport.h
+ *
+ *  @brief Primary interface for all MessageQ transports
+ *
+ *  A typical memory based transport used as the primary transport for
+ *  MessageQ would implement this interface. The transport implementation
+ *  has to be registered with MessageQ using the MessageQ_registerTransport
+ *  method. This is typically done by the factor code.
+ *
+ *  The IMessageQTransport interface includes the following instance methods:
+ *
+ *  bind - create transport resources on behalf of the given queue
+ *  unbind - delete transport resources used by the given queue
+ *  put - send the message
+ */
+
 /*
  *  ======== IMessageQTransport.h ========
  */
 
 #include <ti/ipc/interfaces/ITransport.h>
 
-/* opaque instance handle */
-typedef struct IMessageQTransport_Object *IMessageQTransport_Handle;
+#if defined (__cplusplus)
+extern "C" {
+#endif
 
+/*!
+ *  @brief  Interface type ID
+ *
+ *  This ID uniquely identifies this interface type.
+ */
 #define IMessageQTransport_TypeId 0x02
 
-/* virtual functions */
+/*!
+ *  @brief IMessageQTransport_Handle type
+ *
+ *  An opaque instance handle.
+ */
+typedef struct IMessageQTransport_Object *IMessageQTransport_Handle;
+
+/*!
+ *  @brief The interface function table
+ *
+ *  All transports must provide a concrete implementation for each of
+ *  these virtual functions. The transport user (e.g. MessageQ) will
+ *  invoke the implementation functions through the interface function
+ *  stubs defined below.
+ */
 typedef struct IMessageQTransport_Fxns {
+
     Int (*bind)(void *handle, UInt32 queueId);
+    /*!< function pointer for bind method
+     *
+     *  This method allows the transport to bind/create resources
+     *  needed for message delivery. The method is invoked when a
+     *  new message queue is created and for all existing queues
+     *  when attaching to a processor.
+     *
+     *  @param[in]  inst        Transport instance handle
+     *  @param[in]  queueId     Message queue identifier
+     *
+     *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
+     */
+
     Int (*unbind)(void *handle, UInt32 queueId);
+    /*!< function pointer for unbind method
+     *
+     *  This method allows the transport to unbind/delete resources
+     *  which where allocated on behalf of the given message queue.
+     *  This method is invoked when deleting a message queue and for
+     *  all existing queues when detaching from a processor.
+     *
+     *  @param[in]  inst        Transport instance handle
+     *  @param[in]  queueId     Message queue identifier
+     *
+     *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
+     */
+
     Bool (*put)(void *handle, Ptr msg);
+    /*!< function pointer for put method
+     *
+     *  Invoked to deliver the given message. Once MessageQ calls into this
+     *  method, the message ownership has been transferred to the transport.
+     *  Regardless of the outcome of message delivery, the message ownership
+     *  is *never* returned back to MessageQ. If delivery fails, the message
+     *  is lost but all resources must be reclaimed.
+     *
+     *  @param[in]  inst        Transport instance handle
+     *  @param[in]  msg         Pointer to the message (MessageQ_Msg)
+     *
+     *  @return Status result:
+     *          - TRUE: message was delivered
+     *          - FALSE: delivery failure, message lost
+     */
 } IMessageQTransport_Fxns;
 
-/* abstract instance object */
+/*!
+ *  @brief The instance object definition for IMessageQTransport
+ *
+ *  All instances of this interface type must define this object
+ *  within the implementation object. It must be the first element
+ *  of the instance object and it must be named 'base'. Otherwise,
+ *  the converter functions below will fail.
+ *
+ *  typedef TransportAcme_Object {
+ *      IMessageQTransport_Object base;
+ *      ...
+ *  } TransportAcme_Object;
+ */
 typedef struct IMessageQTransport_Object {
-    ITransport_Object base;             /* inheritance */
-    IMessageQTransport_Fxns *fxns;      /* virtual functions */
+
+    ITransport_Object base;
+    /*!< Base class inheritance
+     *
+     *  The instance constructor must initialize this base object.
+     */
+
+    IMessageQTransport_Fxns *fxns;
+    /*!< Address of interface function table
+     *
+     *  The instance constructor must initialize this field to contain
+     *  the address of the instance function table.
+     *
+     *  IMessageQTransport_Fxns TransportAcme_fxns = {
+     *      .bind   = TransportAcme_bind,
+     *      .unbind = TransportAcme_unbind,
+     *      .put    = TransportAcme_put
+     *  };
+     *
+     *  obj->base.fxns = &TransportAcme_fxns;
+     */
 } IMessageQTransport_Object;
 
-/* function stubs */
+/*!
+ *  @brief Bind transport resources on behalf of the given message queue
+ *
+ *  Interface function to invoke transport implementation.
+ *
+ *  @sa IMessageQTransport_Fxns.bind()
+ *
+ *  @param[in]  inst        Transport instance handle
+ *  @param[in]  queueId     Message queue identifier
+ *
+ *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
+ */
 static inline
 Int IMessageQTransport_bind(IMessageQTransport_Handle inst, UInt32 queueId)
 {
@@ -65,6 +186,18 @@ Int IMessageQTransport_bind(IMessageQTransport_Handle inst, UInt32 queueId)
     return obj->fxns->bind((void *)inst, queueId);
 }
 
+/*!
+ *  @brief Unbind transport resources allocated for the given message queue
+ *
+ *  Interface function to invoke transport implementation.
+ *
+ *  @sa IMessageQTransport_Fxns.unbind()
+ *
+ *  @param[in]  inst        Transport instance handle
+ *  @param[in]  queueId     Message queue identifier
+ *
+ *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
+ */
 static inline
 Int IMessageQTransport_unbind(IMessageQTransport_Handle inst, UInt32 queueId)
 {
@@ -72,6 +205,18 @@ Int IMessageQTransport_unbind(IMessageQTransport_Handle inst, UInt32 queueId)
     return obj->fxns->unbind((void *)inst, queueId);
 }
 
+/*!
+ *  @brief Deliver the given message
+ *
+ *  Interface function to invoke transport implementation.
+ *
+ *  @sa IMessageQTransport_Fxns.put()
+ *
+ *  @param[in]  inst        Transport instance handle
+ *  @param[in]  msg         Pointer to the message (MessageQ_Msg)
+ *
+ *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
+ */
 static inline
 Bool IMessageQTransport_put(IMessageQTransport_Handle inst, Ptr msg)
 {
@@ -79,7 +224,17 @@ Bool IMessageQTransport_put(IMessageQTransport_Handle inst, Ptr msg)
     return obj->fxns->put((void *)inst, msg);
 }
 
-/* instance convertors */
+/*!
+ *  @brief Convert the instance handle to a base class handle
+ *
+ *  Use this method to safely get a handle to the base interface.
+ *  The returned handle can be used to invoke methods on the base
+ *  interface.
+ *
+ *  @param[in]  inst        Transport instance handle
+ *
+ *  @return An ITransport_Handle for the given instance object
+ */
 static inline
 ITransport_Handle IMessageQTransport_upCast(IMessageQTransport_Handle inst)
 {
@@ -87,10 +242,24 @@ ITransport_Handle IMessageQTransport_upCast(IMessageQTransport_Handle inst)
     return (ITransport_Handle)&obj->base;
 }
 
+/*!
+ *  @brief Convert the base class handle into and instance handle
+ *
+ *  Use this method to safely get a handle to the interface instance.
+ *  The returned handle can be used to invoke methods on the instance
+ *  object.
+ *
+ *  @param[in]  inst        ITransport_handle of the instance object
+ *
+ *  @return An ITransport_Handle for the given instance
+ */
 static inline
 IMessageQTransport_Handle IMessageQTransport_downCast(ITransport_Handle base)
 {
     return (IMessageQTransport_Handle)base;
 }
 
+#if defined (__cplusplus)
+}
+#endif
 #endif /* IMESSAGEQTRANSPORT_H */
index 7834032880f7de23d5d0497b47261e77cc623ff9..d0aee848be7ba6c78e1f3f520b570be87b368876 100644 (file)
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ *  @file linux/include/ti/ipc/interfaces/INetworkTransport.h
+ *
+ *  @brief Secondary interface for MessageQ transports
+ *
+ *  This interface is suitable for implementing a secondary message
+ *  transport for the MessageQ module.
+ *
+ *  The INetworkTransport interface includes the following instance methods:
+ *
+ *  bind - create transport resources on behalf of the given queue
+ *  unbind - delete transport resources used by the given queue
+ *  put - send the message
+ */
+
 /*
  *  ======== INetworkTransport.h ========
  */
 
 #include <ti/ipc/interfaces/ITransport.h>
 
+#if defined (__cplusplus)
+extern "C" {
+#endif
 
-/*
- *  ======== INetworkTransport_Handle ========
- *  Opaque handle to interface instance object
+/*!
+ *  @brief  Interface type ID
+ *
+ *  This ID uniquely identifies this interface type.
  */
-typedef struct INetworkTransport_Object *INetworkTransport_Handle;
+#define INetworkTransport_TypeId 0x03
 
-/*
- *  ======== INetworkTransport_TypeId ========
- *  Unique identifier for this interface
+/*!
+ *  @brief INetworkTransport_Handle type
+ *
+ *  An opaque instance handle.
  */
-#define INetworkTransport_TypeId 0x03
+typedef struct INetworkTransport_Object *INetworkTransport_Handle;
 
-/*
- *  ======== INetworkTransport_Fxns ========
- *  Interface virtual function table
+/*!
+ *  @brief The interface function table
+ *
+ *  All transports must provide a concrete implementation for each of
+ *  these virtual functions. The transport user (e.g. MessageQ) will
+ *  invoke the implementation functions through the interface function
+ *  stubs defined below.
  */
 typedef struct INetworkTransport_Fxns {
+
     Int (*bind)(void *handle, UInt32 queueId);
+    /*!< function pointer for bind method
+     *
+     *  This method allows the transport to bind/create resources
+     *  needed for message delivery. The method is invoked when a
+     *  new message queue is created and for all existing queues
+     *  when attaching to a processor.
+     *
+     *  @param[in]  inst        Transport instance handle
+     *  @param[in]  queueId     Message queue identifier
+     *
+     *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
+     */
+
     Int (*unbind)(void *handle, UInt32 queueId);
+    /*!< function pointer for unbind method
+     *
+     *  This method allows the transport to unbind/delete resources
+     *  which where allocated on behalf of the given message queue.
+     *  This method is invoked when deleting a message queue and for
+     *  all existing queues when detaching from a processor.
+     *
+     *  @param[in]  inst        Transport instance handle
+     *  @param[in]  queueId     Message queue identifier
+     *
+     *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
+     */
+
     Bool (*put)(void *handle, Ptr msg);
+    /*!< function pointer for put method
+     *
+     *  Invoked to deliver the given message. Once MessageQ calls into this
+     *  method, the message ownership has been transferred to the transport.
+     *  Regardless of the outcome of message delivery, the message ownership
+     *  is *never* returned back to MessageQ. If delivery fails, the message
+     *  is lost but all resources must be reclaimed.
+     *
+     *  @param[in]  inst        Transport instance handle
+     *  @param[in]  msg         Pointer to the message (MessageQ_Msg)
+     *
+     *  @return Status result:
+     *          - TRUE: message was delivered
+     *          - FALSE: delivery failure, message lost
+     */
 } INetworkTransport_Fxns;
 
-/*
- *  ======== INetworkTransport_Object ========
- *  Abstract instance object
+/*!
+ *  @brief The instance object definition for INetworkTransport
+ *
+ *  All instances of this interface type must define this object
+ *  within the implementation object. It must be the first element
+ *  of the instance object and it must be named 'base'. Otherwise,
+ *  the converter functions below will fail.
+ *
+ *  typedef TransportAcme_Object {
+ *      INetworkTransport_Object base;
+ *      ...
+ *  } TransportAcme_Object;
  */
 typedef struct INetworkTransport_Object {
-    ITransport_Object base;             /* inheritance */
-    INetworkTransport_Fxns *fxns;       /* virtual functions */
+
+    ITransport_Object base;
+    /*!< Base class inheritance
+     *
+     *  The instance constructor must initialize this base object.
+     */
+
+    INetworkTransport_Fxns *fxns;
+    /*!< Address of interface function table
+     *
+     *  The instance constructor must initialize this field to contain
+     *  the address of the instance function table.
+     *
+     *  INetworkTransport_Fxns TransportAcme_fxns = {
+     *      .bind   = TransportAcme_bind,
+     *      .unbind = TransportAcme_unbind,
+     *      .put    = TransportAcme_put
+     *  };
+     *
+     *  obj->base.fxns = &TransportAcme_fxns;
+     */
 } INetworkTransport_Object;
 
-/*
- *  ======== INetworkTransport_bind ========
- *  Instance function stub
+/*!
+ *  @brief Bind transport resources on behalf of the given message queue
+ *
+ *  Interface function to invoke transport implementation.
+ *
+ *  @sa INetworkTransport_Fxns.bind()
+ *
+ *  @param[in]  inst        Transport instance handle
+ *  @param[in]  queueId     Message queue identifier
+ *
+ *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
  */
 static inline
 Bool INetworkTransport_bind(INetworkTransport_Handle inst, UInt32 queueId)
@@ -82,9 +184,17 @@ Bool INetworkTransport_bind(INetworkTransport_Handle inst, UInt32 queueId)
     return (obj->fxns->bind((void *)inst, queueId));
 }
 
-/*
- *  ======== INetworkTransport_unbind ========
- *  Instance function stub
+/*!
+ *  @brief Unbind transport resources allocated for the given message queue
+ *
+ *  Interface function to invoke transport implementation.
+ *
+ *  @sa INetworkTransport_Fxns.unbind()
+ *
+ *  @param[in]  inst        Transport instance handle
+ *  @param[in]  queueId     Message queue identifier
+ *
+ *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
  */
 static inline
 Bool INetworkTransport_unbind(INetworkTransport_Handle inst, UInt32 queueId)
@@ -93,9 +203,17 @@ Bool INetworkTransport_unbind(INetworkTransport_Handle inst, UInt32 queueId)
     return (obj->fxns->unbind((void *)inst, queueId));
 }
 
-/*
- *  ======== INetworkTransport_put ========
- *  Instance function stub
+/*!
+ *  @brief Deliver the given message
+ *
+ *  Interface function to invoke transport implementation.
+ *
+ *  @sa INetworkTransport_Fxns.put()
+ *
+ *  @param[in]  inst        Transport instance handle
+ *  @param[in]  msg         Pointer to the message (MessageQ_Msg)
+ *
+ *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
  */
 static inline
 Bool INetworkTransport_put(INetworkTransport_Handle inst, Ptr msg)
@@ -104,9 +222,16 @@ Bool INetworkTransport_put(INetworkTransport_Handle inst, Ptr msg)
     return (obj->fxns->put((void *)inst, msg));
 }
 
-/*
- *  ======== INetworkTransport_upCast ========
- *  Instance converter
+/*!
+ *  @brief Convert the instance handle to a base class handle
+ *
+ *  Use this method to safely get a handle to the base interface.
+ *  The returned handle can be used to invoke methods on the base
+ *  interface.
+ *
+ *  @param[in]  inst        Transport instance handle
+ *
+ *  @return An ITransport_Handle for the given instance object
  */
 static inline
 ITransport_Handle INetworkTransport_upCast(INetworkTransport_Handle inst)
@@ -115,9 +240,16 @@ ITransport_Handle INetworkTransport_upCast(INetworkTransport_Handle inst)
     return ((ITransport_Handle)&obj->base);
 }
 
-/*
- *  ======== INetworkTransport_downCast ========
- *  Instance converter
+/*!
+ *  @brief Convert the base class handle into and instance handle
+ *
+ *  Use this method to safely get a handle to the interface instance.
+ *  The returned handle can be used to invoke methods on the instance
+ *  object.
+ *
+ *  @param[in]  inst        ITransport_handle of the instance object
+ *
+ *  @return An ITransport_Handle for the given instance
  */
 static inline
 INetworkTransport_Handle INetworkTransport_downCast(ITransport_Handle base)
@@ -125,4 +257,7 @@ INetworkTransport_Handle INetworkTransport_downCast(ITransport_Handle base)
     return ((INetworkTransport_Handle)base);
 }
 
+#if defined (__cplusplus)
+}
+#endif
 #endif /* INETWORKTRANSPORT_H */
index c8f087ef04b3106523c5c27c334d08bea39c241b..f4bbf90376c8b1fae3ae32391a5d161afdd40400 100644 (file)
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ *  @file linux/include/ti/ipc/interfaces/ITransport.h
+ *
+ *  @brief Base interface for all message transports
+ *
+ *  All message transport interfaces must inherit from this base class.
+ *
+ *  The ITransport interface includes the following instance methods:
+ *
+ *  itype - return the derived interface type
+ */
+
 /*
  *  ======== ITransport.h ========
  */
 #ifndef ITRANSPORT_H
 #define ITRANSPORT_H
 
-/* opaque instance handle */
-typedef struct ITransport_Object *ITransport_Handle;
+#if defined (__cplusplus)
+extern "C" {
+#endif
 
+/*!
+ *  @brief  Interface type ID
+ *
+ *  When adding a new interface type, please ensure to define a
+ *  unique ID value for each new type.
+ */
 #define ITransport_TypeId 0x01
 
-/* instance object */
+/*!
+ *  @brief ITransport_Handle type
+ *
+ *  An opaque instance handle.
+ */
+typedef struct ITransport_Object *ITransport_Handle;
+
+/*!
+ *  @brief The instance object definition for ITransport
+ */
 typedef struct ITransport_Object {
+
     Int interfaceType;
+    /*!< Interface type ID
+     *
+     *  This field is initialized by the constructor of the derived
+     *  implementation. It should be assigned the interface type ID
+     *  which is being implemented.
+     */
 } ITransport_Object;
 
-/* instance functions */
+/*!
+ *  @brief Identify the derived interface type
+ *
+ *  Identify the interface type which is implemented by the instance
+ *  object. Transport users (e.g. MessageQ) would use this method to
+ *  identify the interface type and then downcast the ITransport_Handle
+ *  to that interface type.
+ *
+ *  @param[in]  inst        Instance handle
+ *
+ *  @return     Derived interface type ID
+ */
 static inline
 Int ITransport_itype(ITransport_Handle inst)
 {
@@ -55,4 +101,7 @@ Int ITransport_itype(ITransport_Handle inst)
     return obj->interfaceType;
 }
 
+#if defined (__cplusplus)
+}
+#endif
 #endif /* ITRANSPORT_H */