index 7055f500b85e1a72adef95cf788532b395b80aa1..770b2f27651a6512a31a87e7569e50da900d3293 100644 (file)
* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-/** ===========================================================================
- * @file NameServer.h
+/**
+ * @file ti/ipc/NameServer.h
*
* @brief NameServer Manager
*
* The NameServer module manages local name/value pairs that
* enables an application and other modules to store and
* retrieve values based on a name. The module supports different
- * lengths of values. The #NameServer_add and #NameServer_get
- * functions are for variable length values. The #NameServer_addUInt32 and
- * #NameServer_getUInt32 functions are optimized for UInt32 variables
+ * lengths of values. The NameServer_add() and NameServer_get()
+ * functions are for variable length values. The NameServer_addUInt32() and
+ * NameServer_getUInt32() functions are optimized for UInt32 variables
* and constants.
*
* The NameServer module maintains thread-safety for the APIs. However,
* The NameServer module uses the MultiProc module for
* identifying the different processors. Which remote processors and
* the order they are queried is determined by the procId array in the
- * #NameServer_get function.
+ * NameServer_get() function.
*
* Currently there is no endian or wordsize conversion performed by the
* NameServer module. Also there is no asynchronous support at this time.
*/
/*!
- * @def NameServer_S_BUSY
* @brief The resource is still in use
*/
-#define NameServer_S_BUSY 2
+#define NameServer_S_BUSY (2)
/*!
- * @def NameServer_S_ALREADYSETUP
* @brief The module has been already setup
*/
-#define NameServer_S_ALREADYSETUP 1
+#define NameServer_S_ALREADYSETUP (1)
/*!
- * @def NameServer_S_SUCCESS
* @brief Operation is successful.
*/
-#define NameServer_S_SUCCESS 0
+#define NameServer_S_SUCCESS (0)
/*!
- * @def NameServer_E_FAIL
* @brief Generic failure.
*/
-#define NameServer_E_FAIL -1
+#define NameServer_E_FAIL (-1)
/*!
- * @def NameServer_E_INVALIDARG
* @brief Argument passed to function is invalid.
*/
-#define NameServer_E_INVALIDARG -2
+#define NameServer_E_INVALIDARG (-2)
/*!
- * @def NameServer_E_MEMORY
* @brief Operation resulted in memory failure.
*/
-#define NameServer_E_MEMORY -3
+#define NameServer_E_MEMORY (-3)
/*!
- * @def NameServer_E_ALREADYEXISTS
* @brief The specified entity already exists.
*/
-#define NameServer_E_ALREADYEXISTS -4
+#define NameServer_E_ALREADYEXISTS (-4)
/*!
- * @def NameServer_E_NOTFOUND
* @brief Unable to find the specified entity.
*/
-#define NameServer_E_NOTFOUND -5
+#define NameServer_E_NOTFOUND (-5)
/*!
- * @def NameServer_E_TIMEOUT
* @brief Operation timed out.
*/
-#define NameServer_E_TIMEOUT -6
+#define NameServer_E_TIMEOUT (-6)
/*!
- * @def NameServer_E_INVALIDSTATE
* @brief Module is not initialized.
*/
-#define NameServer_E_INVALIDSTATE -7
+#define NameServer_E_INVALIDSTATE (-7)
/*!
- * @def NameServer_E_OSFAILURE
* @brief A failure occurred in an OS-specific call
*/
-#define NameServer_E_OSFAILURE -8
+#define NameServer_E_OSFAILURE (-8)
/*!
- * @def NameServer_E_RESOURCE
* @brief Specified resource is not available
*/
-#define NameServer_E_RESOURCE -9
+#define NameServer_E_RESOURCE (-9)
/*!
- * @def NameServer_E_RESTART
* @brief Operation was interrupted. Please restart the operation
*/
-#define NameServer_E_RESTART -10
+#define NameServer_E_RESTART (-10)
/* =============================================================================
* Macros
*/
/*!
- * @def NameServer_ALLOWGROWTH
* @brief Allow dynamic growth of the NameServer instance table
*/
#define NameServer_ALLOWGROWTH (~0)
/*!
- * @def NameServer_Params_MAXNAMELEN
* @brief The default maximum length of the name for the name/value pair
*/
-#define NameServer_Params_MAXNAMELEN 16
+#define NameServer_Params_MAXNAMELEN (16)
/* =============================================================================
* Structures & Enums
*/
typedef struct NameServer_Params {
UInt maxRuntimeEntries;
- /*!< Maximum number of name/value pairs that can be dynamically created.
+ /*!< @brief Maximum name/value pairs that can be dynamically created.
*
* This parameter allows NameServer to pre-allocate memory.
* When NameServer_add() or NameServer_addUInt32() is
* If the number of pairs is not known at configuration time, set this
* value to #NameServer_ALLOWGROWTH. This instructs NameServer
* to grow the table as needed. NameServer will allocate memory from the
- * #NameServer_Params#tableHeap when a name/value pair is added.
+ * #NameServer_Params.tableHeap when a name/value pair is added.
*
* The default is #NameServer_ALLOWGROWTH.
*/
Ptr tableHeap;
- /*!< Name/value table is allocated from this heap.
+ /*!< @brief Name/value table is allocated from this heap.
*
* The instance table and related buffers are allocated out of this heap
* during the dynamic create. This heap is also used to allocate new
* name/value pairs when #NameServer_ALLOWGROWTH for
- * #NameServer_Params#maxRuntimeEntries
+ * #NameServer_Params.maxRuntimeEntries
*
* The default is to use the same heap that instances are allocated
* from which can be configured via the
*/
Bool checkExisting;
- /*!< Check if a name already exists in the name/value table.
+ /*!< @brief Check if a name already exists in the name/value table.
*
* When a name/value pair is added during runtime, if this boolean is
* true, the table is searched to see if the name already exists. If
*/
UInt maxValueLen;
- /*!< Length, in MAUs, of the value field in the table.
+ /*!< @brief Length, in MAUs, of the value field in the table.
*
* Any value less than sizeof(UInt32) will be rounded up to sizeof(UInt32)
*/
UInt maxNameLen;
- /*!< Length, in MAUs, of the name field in the table.
+ /*!< @brief Length, in MAUs, of the name field in the table.
*
* The maximum length of the name portion of the name/value
* pair. The length includes the null terminator ('\\0').
*
* @param params Instance param structure
*
- * @sa NameServer_create
+ * @sa NameServer_create()
*/
Void NameServer_Params_init(NameServer_Params *params);
*
* @return NameServer handle
*
- * @sa NameServer_delete
+ * @sa NameServer_delete()
*/
NameServer_Handle NameServer_create(String name,
const NameServer_Params *params);
* - #NameServer_S_SUCCESS: Instance successfully deleted
* - #NameServer_E_FAIL: Instance delete failed
*
- * @sa NameServer_create
+ * @sa NameServer_create()
*/
Int NameServer_delete(NameServer_Handle *handlePtr);
* @brief Adds a variable length value into the local NameServer table
*
* This function adds a variable length value into the local table.
- * If the #NameServer_Params#checkExisting flag was true on
+ * If the #NameServer_Params.checkExisting flag was true on
* creation, this function searches the table to make sure the name
* does not already exist. If it does, the name/value pair is not
* added and the #NameServer_E_ALREADYEXISTS error is returned.
*
* There is memory allocation during this function if
- * #NameServer_Params#maxRuntimeEntries is set to
+ * #NameServer_Params.maxRuntimeEntries is set to
* #NameServer_ALLOWGROWTH.
*
* This function copies the name and buffer into the name/value table,
*
* @return Unique entry identifier
*
- * @sa NameServer_addUInt32,
- * NameServer_get,
+ * @sa NameServer_addUInt32()
+ * @sa NameServer_get()
*/
Ptr NameServer_add(NameServer_Handle handle, String name, Ptr buf, UInt32 len);
* that allows a convenient way to add UInt32 bit values without needing
* to specify the address of a UInt32 local variable.
*
- * If the #NameServer_Params#checkExisting flag was true on
+ * If the #NameServer_Params.checkExisting flag was true on
* creation, this function searches the table to make sure the name does
* not already exist. If it does, the name/value pair is not added and the
* #NameServer_E_ALREADYEXISTS error is returned.
* This function copies the name into the name/value table.
*
* There is memory allocation during this function if
- * #NameServer_Params#maxRuntimeEntries is set to
+ * #NameServer_Params.maxRuntimeEntries is set to
* #NameServer_ALLOWGROWTH.
*
* The function does not query remote processors to make sure the
*
* @return Unique entry identifier
*
- * @sa NameServer_add,
- * NameServer_getUInt32
+ * @sa NameServer_add()
+ * @sa NameServer_getUInt32()
*/
Ptr NameServer_addUInt32(NameServer_Handle handle, String name, UInt32 value);
* sleep/wait between successive NameServer_get[UInt32] operations if polling
* on the success of this call. This helps ensure that remote cores
* are not inundated by a flood of incoming notifications and helps
- * reduce the possiblity of deadlocks.
+ * reduce the possibility of deadlocks.
*
* The processors to query is determined by the procId array.
* The array is used to specify which processors to query and the order.
* - #NameServer_E_NOTFOUND: Entry was not found, len unchanged
* - #NameServer_E_FAIL: Error searching for entry
*
- * @sa NameServer_add,
- * NameServer_getLocal
+ * @sa NameServer_add()
+ * @sa NameServer_getLocal()
*/
Int NameServer_get(NameServer_Handle handle,
String name,
* sleep/wait between successive NameServer_get[UInt32] operations if polling
* on the success of this call. This helps ensure that remote cores
* are not inundated by a flood of incoming notifications and helps
- * reduce the possiblity of deadlocks.
+ * reduce the possibility of deadlocks.
*
* The processors to query is determined by the procId array.
* The array is used to specify which processors to query and the order.
* - #NameServer_E_NOTFOUND: Entry was not found
* - #NameServer_E_FAIL: Error searching for entry
*
- * @sa NameServer_addUInt32,
- * NameServer_getLocalUInt32
+ * @sa NameServer_addUInt32()
+ * @sa NameServer_getLocalUInt32()
*/
Int NameServer_getUInt32(NameServer_Handle handle,
String name,
* - #NameServer_E_NOTFOUND: Entry was not found, len remains
* unchanged.
*
- * @sa NameServer_add,
- * NameServer_get
+ * @sa NameServer_add()
+ * @sa NameServer_get()
*/
Int NameServer_getLocal(NameServer_Handle handle,
String name,
* - #NameServer_S_SUCCESS: Successfully found entry
* - #NameServer_E_NOTFOUND: Entry was not found
*
- * @sa NameServer_addUInt32,
- * NameServer_getUInt32
+ * @sa NameServer_addUInt32()
+ * @sa NameServer_getUInt32()
*/
Int NameServer_getLocalUInt32(NameServer_Handle handle,
String name,
*
* This function removes a name/value pair from the table.
*
- * If #NameServer_Params#maxRuntimeEntries is set to
+ * If #NameServer_Params.maxRuntimeEntries is set to
* #NameServer_ALLOWGROWTH,
* memory will be freed which was allocated in NameServer_add().
* Otherwise, no memory is freed during this call.
* When another NameServer_add() occurs, it will reuse the
* empty entry.
*
- * Once an Entry is removed from the NameServer table, it cannot be
+ * Once an entry is removed from the NameServer table, it cannot be
* removed again (just like you cannot free the same block of memory
* twice).
*
* entry does not exists
* - #NameServer_E_FAIL: Operation failed
*
- * @sa NameServer_add
+ * @sa NameServer_add()
*/
Int NameServer_removeEntry(NameServer_Handle handle, Ptr entry);