epics/epics-base
0
0
Fork 0
Code Issues Pull Requests Projects Wiki Activity

Unify doxygen keywords to use '\' not '@'

Browse Source
This commit is contained in:
Andrew Johnson
2020-05-19 18:04:26 -05:00
parent a09b1c8569
commit 9142eca878
35 changed files with 1127 additions and 1123 deletions
Download Patch File Download Diff File Expand all files Collapse all files
modules/libcom/src/as/asTrapWrite.h
+33 -30
View File
@@ -8,9 +8,9 @@
\*************************************************************************/
/**
* @file asTrapWrite.h
* @brief API for monitoring external put operations to an IOC.
* @author Marty Kraimer
* \file asTrapWrite.h
* \brief API for monitoring external put operations to an IOC.
* \author Marty Kraimer
*
* The access security subsystem provides an API asTrapWrite that makes
* put/write requests visible to any facility that registers a listener.
@@ -26,40 +26,43 @@ extern "C" {
#endif
/**
* @brief The message passed to registered listeners.
* \brief The message passed to registered listeners.
*/
typedef struct asTrapWriteMessage {
const char *userid; /**< @brief Userid of whoever orginated the request. */
const char *hostid; /**< @brief Hostid of whoever orginated the request. */
void *serverSpecific; /**< @brief A field for use by the server.
*
* Any listener that uses this field must know what type of
* server is forwarding the put requests. This pointer holds
* the value the server provides to asTrapWriteWithData(), which
* for RSRV is the dbChannel pointer for the target field.
*/
void *userPvt; /**< @brief A field for use by the @ref asTrapWriteListener.
*
* When the listener is called before the write, this has the
* value 0. The listener can give it any value it desires
* and it will have the same value when the listener gets
* called again after the write. */
int dbrType; /**< @brief Data type from ca/db_access.h, NOT dbFldTypes.h */
int no_elements; /**< @brief Array length */
void *data; /**< @brief Might be NULL if no data is available */
const char *userid; /**< \brief Userid of whoever orginated the request. */
const char *hostid; /**< \brief Hostid of whoever orginated the request. */
/** \brief A field for use by the server.
*
* Any listener that uses this field must know what type of
* server is forwarding the put requests. This pointer holds
* the value the server provides to asTrapWriteWithData(), which
* for RSRV is the dbChannel pointer for the target field.
*/
void *serverSpecific;
/** \brief A field for use by the \ref asTrapWriteListener.
*
* When the listener is called before the write, this has the
* value 0. The listener can give it any value it desires
* and it will have the same value when the listener gets
* called again after the write.
*/
void *userPvt;
int dbrType; /**< \brief Data type from ca/db_access.h, NOT dbFldTypes.h */
int no_elements; /**< \brief Array length */
void *data; /**< \brief Might be NULL if no data is available */
} asTrapWriteMessage;
/**
* @brief An identifier needed to unregister an listener.
* \brief An identifier needed to unregister an listener.
*/
typedef void *asTrapWriteId;
/**
* @brief Pointer to a listener function.
* \brief Pointer to a listener function.
*
* Each registered listener function is called twice for every put; once
* before and once after the write is performed.
* The listener may set @c userPvt in the first call and retrieve it in the
* The listener may set \c userPvt in the first call and retrieve it in the
* second call.
*
* Each asTrapWriteMessage can change or may be deleted after the user's
@@ -71,15 +74,15 @@ typedef void *asTrapWriteId;
typedef void(*asTrapWriteListener)(asTrapWriteMessage *pmessage,int after);
/**
* @brief Register function to be called on asTrapWriteListener.
* @param func The listener function to be called.
* @return A listener identifier for unregistering this listener.
* \brief Register function to be called on asTrapWriteListener.
* \param func The listener function to be called.
* \return A listener identifier for unregistering this listener.
*/
epicsShareFunc asTrapWriteId epicsShareAPI asTrapWriteRegisterListener(
asTrapWriteListener func);
/**
* @brief Unregister asTrapWriteListener.
* @param id Listener identifier from asTrapWriteRegisterListener().
* \brief Unregister asTrapWriteListener.
* \param id Listener identifier from asTrapWriteRegisterListener().
*/
epicsShareFunc void epicsShareAPI asTrapWriteUnregisterListener(
asTrapWriteId id);
modules/libcom/src/bucketLib/bucketLib.h
+76 -76
View File
@@ -7,16 +7,16 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/**
* @file bucketLib.h
* @author Jeffrey O. Hill
* @brief A hash table. Do not use for new code.
* \file bucketLib.h
* \author Jeffrey O. Hill
* \brief A hash table. Do not use for new code.
*
* @details
* \details
* A hash table for which keys may be unsigned integers, pointers, or
* strings. This API is used by the IOC's Channel Access Server, but
* it should not be used by other code.
*
* @note Storage for identifiers must persist until an item is deleted
* \note Storage for identifiers must persist until an item is deleted
*/
#ifndef INCbucketLibh
@@ -30,13 +30,13 @@ extern "C" {
#include "epicsTypes.h"
#include "shareLib.h"
/** @brief Internal: bucket identifier */
/** \brief Internal: bucket identifier */
typedef unsigned BUCKETID;
/** @brief Internal: bucket key type */
/** \brief Internal: bucket key type */
typedef enum {bidtUnsigned, bidtPointer, bidtString} buckTypeOfId;
/** @brief Internal: bucket item structure */
/** \brief Internal: bucket item structure */
typedef struct item{
struct item *pItem;
const void *pId;
@@ -44,7 +44,7 @@ typedef struct item{
buckTypeOfId type;
}ITEM;
/** @brief Internal: Hash table structure */
/** \brief Internal: Hash table structure */
typedef struct bucket{
ITEM **pTable;
void *freeListPVT;
@@ -53,140 +53,140 @@ typedef struct bucket{
unsigned nInUse;
}BUCKET;
/**
* @brief Creates a new hash table
* @param nHashTableEntries Table size
* @return Pointer to the newly created hash table, or NULL.
* \brief Creates a new hash table
* \param nHashTableEntries Table size
* \return Pointer to the newly created hash table, or NULL.
*/
epicsShareFunc BUCKET * epicsShareAPI bucketCreate (unsigned nHashTableEntries);
/**
* @brief Release memory used by a hash table
* @param *prb Pointer to the hash table
* @return S_bucket_success
* @note All items must be deleted from the hash table before calling this.
* \brief Release memory used by a hash table
* \param *prb Pointer to the hash table
* \return S_bucket_success
* \note All items must be deleted from the hash table before calling this.
*/
epicsShareFunc int epicsShareAPI bucketFree (BUCKET *prb);
/**
* @brief Display information about a hash table
* @param *prb Pointer to the hash table
* @return S_bucket_success
* \brief Display information about a hash table
* \param *prb Pointer to the hash table
* \return S_bucket_success
*/
epicsShareFunc int epicsShareAPI bucketShow (BUCKET *prb);
/**
* @brief Add an item identified by an unsigned int to the table
* @param *prb Pointer to the hash table
* @param *pId Pointer to the identifier
* @param *pApp Pointer to the payload
* @return Status value
* \brief Add an item identified by an unsigned int to the table
* \param *prb Pointer to the hash table
* \param *pId Pointer to the identifier
* \param *pApp Pointer to the payload
* \return Status value
*/
epicsShareFunc int epicsShareAPI bucketAddItemUnsignedId (BUCKET *prb,
const unsigned *pId, const void *pApp);
/**
* @brief Add an item identified by a pointer to the table
* @param *prb Pointer to the hash table
* @param *pId Pointer to the identifier
* @param *pApp Pointer to the payload
* @return Status value
* \brief Add an item identified by a pointer to the table
* \param *prb Pointer to the hash table
* \param *pId Pointer to the identifier
* \param *pApp Pointer to the payload
* \return Status value
*/
epicsShareFunc int epicsShareAPI bucketAddItemPointerId (BUCKET *prb,
void * const *pId, const void *pApp);
/**
* @brief Add an item identified by a string to the table
* @param *prb Pointer to the hash table
* @param *pId Pointer to the identifier
* @param *pApp Pointer to the payload
* @return Status value
* \brief Add an item identified by a string to the table
* \param *prb Pointer to the hash table
* \param *pId Pointer to the identifier
* \param *pApp Pointer to the payload
* \return Status value
*/
epicsShareFunc int epicsShareAPI bucketAddItemStringId (BUCKET *prb,
const char *pId, const void *pApp);
/**
* @brief Remove an item identified by a string from the table
* @param *prb Pointer to the hash table
* @param *pId Pointer to the identifier
* @return Status value
* \brief Remove an item identified by a string from the table
* \param *prb Pointer to the hash table
* \param *pId Pointer to the identifier
* \return Status value
*/
epicsShareFunc int epicsShareAPI bucketRemoveItemUnsignedId (BUCKET *prb, const unsigned *pId);
/**
* @brief Remove an item identified by a pointer from the table
* @param *prb Pointer to the hash table
* @param *pId Pointer to the identifier
* @return Status value
* \brief Remove an item identified by a pointer from the table
* \param *prb Pointer to the hash table
* \param *pId Pointer to the identifier
* \return Status value
*/
epicsShareFunc int epicsShareAPI bucketRemoveItemPointerId (BUCKET *prb, void * const *pId);
/**
* @brief Remove an item identified by a string from the table
* @param *prb Pointer to the hash table
* @param *pId Pointer to the identifier
* @return Status value
* \brief Remove an item identified by a string from the table
* \param *prb Pointer to the hash table
* \param *pId Pointer to the identifier
* \return Status value
*/
epicsShareFunc int epicsShareAPI bucketRemoveItemStringId (BUCKET *prb, const char *pId);
/**
* @brief Find an item identified by an unsigned int in the table
* @param *prb Pointer to the hash table
* @param *pId Pointer to the identifier
* @return Item's payload pointer, or NULL if not found
* \brief Find an item identified by an unsigned int in the table
* \param *prb Pointer to the hash table
* \param *pId Pointer to the identifier
* \return Item's payload pointer, or NULL if not found
*/
epicsShareFunc void * epicsShareAPI bucketLookupItemUnsignedId (BUCKET *prb, const unsigned *pId);
/**
* @brief Find an item identified by a pointer in the table
* @param *prb Pointer to the hash table
* @param *pId Pointer to the identifier
* @return Item's payload pointer, or NULL if not found
* \brief Find an item identified by a pointer in the table
* \param *prb Pointer to the hash table
* \param *pId Pointer to the identifier
* \return Item's payload pointer, or NULL if not found
*/
epicsShareFunc void * epicsShareAPI bucketLookupItemPointerId (BUCKET *prb, void * const *pId);
/**
* @brief Find an item identified by a string in the table
* @param *prb Pointer to the hash table
* @param *pId Pointer to the identifier
* @return Item's payload pointer, or NULL if not found
* \brief Find an item identified by a string in the table
* \param *prb Pointer to the hash table
* \param *pId Pointer to the identifier
* \return Item's payload pointer, or NULL if not found
*/
epicsShareFunc void * epicsShareAPI bucketLookupItemStringId (BUCKET *prb, const char *pId);
/**
* @brief Find and delete an item identified by an unsigned int from the table
* @param *prb Pointer to the hash table
* @param *pId Pointer to the identifier
* @return Item's payload pointer, or NULL if not found
* \brief Find and delete an item identified by an unsigned int from the table
* \param *prb Pointer to the hash table
* \param *pId Pointer to the identifier
* \return Item's payload pointer, or NULL if not found
*/
epicsShareFunc void * epicsShareAPI bucketLookupAndRemoveItemUnsignedId (BUCKET *prb, const unsigned *pId);
/**
* @brief Find and delete an item identified by a pointer from the table
* @param *prb Pointer to the hash table
* @param *pId Pointer to the identifier
* @return Item's payload pointer, or NULL if not found
* \brief Find and delete an item identified by a pointer from the table
* \param *prb Pointer to the hash table
* \param *pId Pointer to the identifier
* \return Item's payload pointer, or NULL if not found
*/
epicsShareFunc void * epicsShareAPI bucketLookupAndRemoveItemPointerId (BUCKET *prb, void * const *pId);
/**
* @brief Find and delete an item identified by a string from the table
* @param *prb Pointer to the hash table
* @param *pId Pointer to the identifier
* @return Item's payload pointer, or NULL if not found
* \brief Find and delete an item identified by a string from the table
* \param *prb Pointer to the hash table
* \param *pId Pointer to the identifier
* \return Item's payload pointer, or NULL if not found
*/
epicsShareFunc void * epicsShareAPI bucketLookupAndRemoveItemStringId (BUCKET *prb, const char *pId);
/**
* @name Status values returned by some bucketLib functions
* \name Status values returned by some bucketLib functions
* @{
*/
/**
* @brief A synonym for S_bucket_success
* \brief A synonym for S_bucket_success
*/
#define BUCKET_SUCCESS S_bucket_success
/**
* @brief Success, must be 0.
* \brief Success, must be 0.
*/
#define S_bucket_success 0
/**
* @brief Memory allocation failed
* \brief Memory allocation failed
*/
#define S_bucket_noMemory (M_bucket | 1) /*Memory allocation failed*/
/**
* @brief Identifier already in use
* \brief Identifier already in use
*/
#define S_bucket_idInUse (M_bucket | 2) /*Identifier already in use*/
/**
* @brief Unknown identifier
* \brief Unknown identifier
*/
#define S_bucket_uknId (M_bucket | 3) /*Unknown identifier*/
/** @} */
modules/libcom/src/calc/postfix.h
+56 -56
View File
@@ -7,10 +7,10 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/**
* @file postfix.h
* @author Bob Dalesio, Andrew Johnson
* \file postfix.h
* \author Bob Dalesio, Andrew Johnson
*
* @brief The API for the EPICS Calculation Engine
* \brief The API for the EPICS Calculation Engine
*
* Defines macros and the routines provided by the calculation engine for
* subsystems that need to evaluate mathematical expressions.
@@ -21,50 +21,50 @@
#include "shareLib.h"
/** @brief Number of input arguments to a calc expression (A-L) */
/** \brief Number of input arguments to a calc expression (A-L) */
#define CALCPERFORM_NARGS 12
/** @brief Size of the internal partial result stack */
/** \brief Size of the internal partial result stack */
#define CALCPERFORM_STACK 80
/**
* @name Postfix and Infix Buffer Sizes
* \name Postfix and Infix Buffer Sizes
* @{
*/
/**
* @brief Calculate required size of postfix buffer from infix
* \brief Calculate required size of postfix buffer from infix
*
* This macro calculates the maximum size of postfix buffer needed for an
* infix expression buffer of a given size. The argument @c n must count
* infix expression buffer of a given size. The argument \c n must count
* the trailing nil byte in the input expression string. The actual size
* needed is never larger than this value, although it is actually a
* few bytes smaller for some sizes.
*
* The maximum expansion from infix to postfix is for the sub-expression
@code
\code
.1?.1:
@endcode
\endcode
* which is 6 characters long and results in 21 bytes of postfix:
@code
\code
.1 => LITERAL_DOUBLE + 8 byte value
? => COND_IF
.1 => LITERAL_DOUBLE + 8 byte value
: => COND_ELSE
...
=> COND_END
@endcode
\endcode
* For other short expressions the factor 21/6 always gives a big enough
* postfix buffer (proven by hand, look at '1+' and '.1+' as well).
*/
#define INFIX_TO_POSTFIX_SIZE(n) ((n)*21/6)
/**
* @brief Size of a "standard" infix string.
* \brief Size of a "standard" infix string.
*
* This is not a hard limit, just the default size for the database
*/
#define MAX_INFIX_SIZE 100
/**
* @brief Size of a "standard" postfix buffer.
* \brief Size of a "standard" postfix buffer.
*
* This is not a hard limit, just the default size for the database
*/
@@ -72,38 +72,38 @@
/** @} */
/** @name Calc Engine Error Codes
* @note Changes in these errors must also be made in calcErrorStr().
/** \name Calc Engine Error Codes
* \note Changes in these errors must also be made in calcErrorStr().
* @{
*/
/** @brief No error */
/** \brief No error */
#define CALC_ERR_NONE 0
/** @brief Too many results returned */
/** \brief Too many results returned */
#define CALC_ERR_TOOMANY 1
/** @brief Bad numeric literal */
/** \brief Bad numeric literal */
#define CALC_ERR_BAD_LITERAL 2
/** @brief Bad assignment target */
/** \brief Bad assignment target */
#define CALC_ERR_BAD_ASSIGNMENT 3
/** @brief Comma without parentheses */
/** \brief Comma without parentheses */
#define CALC_ERR_BAD_SEPERATOR 4
/** @brief Close parenthesis without open */
/** \brief Close parenthesis without open */
#define CALC_ERR_PAREN_NOT_OPEN 5
/** @brief Open parenthesis at end of expression */
/** \brief Open parenthesis at end of expression */
#define CALC_ERR_PAREN_OPEN 6
/** @brief Unbalanced conditional ?: operators */
/** \brief Unbalanced conditional ?: operators */
#define CALC_ERR_CONDITIONAL 7
/** @brief Incomplete expression, operand missing */
/** \brief Incomplete expression, operand missing */
#define CALC_ERR_INCOMPLETE 8
/** @brief Runtime stack would underflow */
/** \brief Runtime stack would underflow */
#define CALC_ERR_UNDERFLOW 9
/** @brief Runtime stack would overflow */
/** \brief Runtime stack would overflow */
#define CALC_ERR_OVERFLOW 10
/** @brief Syntax error */
/** \brief Syntax error */
#define CALC_ERR_SYNTAX 11
/** @brief NULL or empty input argument */
/** \brief NULL or empty input argument */
#define CALC_ERR_NULL_ARG 12
/** @brief Internal error, bad element type */
/** \brief Internal error, bad element type */
#define CALC_ERR_INTERNAL 13
/** @} */
@@ -112,21 +112,21 @@
extern "C" {
#endif
/** @brief Compile an infix expression into postfix byte-code
/** \brief Compile an infix expression into postfix byte-code
*
* Converts an expression from an infix string to postfix byte-code
*
* @param pinfix Pointer to the infix string
* @param ppostfix Pointer to the postfix buffer
* @param perror Place to return an error code
* @return Non-zero value in event of error
* \param pinfix Pointer to the infix string
* \param ppostfix Pointer to the postfix buffer
* \param perror Place to return an error code
* \return Non-zero value in event of error
*
* It is the callers's responsibility to ensure that \c ppostfix points
* to sufficient storage to hold the postfix expression. The macro
* INFIX_TO_POSTFIX_SIZE(n) can be used to calculate an appropriate
* postfix buffer size from the length of the infix buffer.
*
* @note "n" must count the terminating nil byte too.
* \note "n" must count the terminating nil byte too.
*
* -# The **infix expressions** that can be used are very similar
* to the C expression syntax, but with some additions and subtle
@@ -230,7 +230,7 @@ extern "C" {
* - Arccosine: acos(a)
* - Arctangent: atan(a)
* - 2 parameter arctangent: atan2(a, b)
* @note Note that these arguments are the reverse of the ANSI C function,
* \note Note that these arguments are the reverse of the ANSI C function,
* so while C would return arctan(a/b) the calc expression engine returns arctan(b/a)
*
* -# ***Hyperbolic Trigonometry***
@@ -298,62 +298,62 @@ extern "C" {
epicsShareFunc long
postfix(const char *pinfix, char *ppostfix, short *perror);
/** @brief Run the calculation engine
/** \brief Run the calculation engine
*
* Evaluates the postfix expression against a set ot input values.
*
* @param parg Pointer to an array of double values for the arguments A-L
* \param parg Pointer to an array of double values for the arguments A-L
* that can appear in the expression. Note that the argument values may be
* modified if the expression uses the assignment operator.
* @param presult Where to put the calculated result, which may be a NaN or Infinity.
* @param ppostfix The postfix expression created by postfix().
* @return Status value 0 for OK, or non-zero if an error is discovered
* \param presult Where to put the calculated result, which may be a NaN or Infinity.
* \param ppostfix The postfix expression created by postfix().
* \return Status value 0 for OK, or non-zero if an error is discovered
* during the evaluation process.
*/
epicsShareFunc long
calcPerform(double *parg, double *presult, const char *ppostfix);
/** @brief Find the inputs and outputs of an expression
/** \brief Find the inputs and outputs of an expression
*
* Software using the calc subsystem may need to know what expression
* arguments are used and/or modified by a particular expression. It can
* discover this from the postfix string by calling calcArgUsage(), which
* takes two pointers @c pinputs and @c pstores to a pair of unsigned long
* takes two pointers \c pinputs and \c pstores to a pair of unsigned long
* bitmaps which return that information to the caller. Passing a NULL value
* for either of these pointers is legal if only the other is needed.
*
* The least signficant bit (bit 0) of the bitmap at @c *pinputs will be set
* The least signficant bit (bit 0) of the bitmap at \c *pinputs will be set
* if the expression depends on the argument A, and so on through bit 11 for
* the argument L. An argument that is not used until after a value has been
* assigned to it will not be set in the pinputs bitmap, thus the bits can
* be used to determine whether a value needs to be supplied for their
* associated argument or not for the purposes of evaluating the expression.
*
* Bit 0 of the bitmap at @c *pstores will be set if the expression assigns
* Bit 0 of the bitmap at \c *pstores will be set if the expression assigns
* a value to the argument A, bit 1 for argument B etc.
* @param ppostfix A postfix expression created by postfix().
* @param pinputs Bitmap pointer.
* @param pstores Bitmap pointer.
* @return The return value will be non-zero if the ppostfix expression was
* \param ppostfix A postfix expression created by postfix().
* \param pinputs Bitmap pointer.
* \param pstores Bitmap pointer.
* \return The return value will be non-zero if the ppostfix expression was
* illegal, otherwise 0.
*/
epicsShareFunc long
calcArgUsage(const char *ppostfix, unsigned long *pinputs, unsigned long *pstores);
/** @brief Convert an error code to a string.
/** \brief Convert an error code to a string.
*
* Gives out a printable version of an individual error code.
* The error codes are macros defined here with names starting @c CALC_ERR_
* @param error Error code
* @return A string representation of the error code
* The error codes are macros defined here with names starting \c CALC_ERR_
* \param error Error code
* \return A string representation of the error code
*/
epicsShareFunc const char *
calcErrorStr(short error);
/** @brief Disassemble a postfix expression
/** \brief Disassemble a postfix expression
*
* Convert the byte-code stream to text and print to stdout.
* @param pinst postfix instructions
* \param pinst postfix instructions
*/
epicsShareFunc void
calcExprDump(const char *pinst);
modules/libcom/src/cppStd/epicsAlgorithm.h
+9 -9
View File
@@ -7,12 +7,12 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/**
* @file epicsAlgorithm.h
* @author Jeff Hill & Andrew Johnson
* \file epicsAlgorithm.h
* \author Jeff Hill & Andrew Johnson
*
* @brief Contains a few templates out of the C++ standard header algorithm
* \brief Contains a few templates out of the C++ standard header algorithm
*
* @note The templates are provided here in a much smaller file. Standard algorithm
* \note The templates are provided here in a much smaller file. Standard algorithm
* contains many templates for sorting and searching through C++ template containers
* which are not used in EPICS. If all you need from there is std::min(),
* std::max() and/or std::swap() your code may compile faster if you include
@@ -41,7 +41,7 @@ inline const T& epicsMin (const T& a, const T& b)
/**
* Returns the smaller of a or b compared using a<b.
*
* @note If b is a NaN the above template returns a, but should return NaN.
* \note If b is a NaN the above template returns a, but should return NaN.
* These specializations ensure that epicsMin(x,NaN) == NaN
*/
template <>
@@ -53,7 +53,7 @@ inline const float& epicsMin (const float& a, const float& b)
/**
* Returns the smaller of a or b compared using a<b.
*
* @note If b is a NaN the above template returns a, but should return NaN.
* \note If b is a NaN the above template returns a, but should return NaN.
* These specializations ensure that epicsMin(x,NaN) == NaN
*/
template <>
@@ -75,7 +75,7 @@ inline const T& epicsMax (const T& a, const T& b)
/**
* Returns the larger of a or b compared using a<b.
*
* @note If b is a NaN the above template returns a, but should return NaN.
* \note If b is a NaN the above template returns a, but should return NaN.
* These specializations ensure that epicsMax(x,NaN) == NaN
*/
template <>
@@ -87,7 +87,7 @@ inline const float& epicsMax (const float& a, const float& b)
/**
* Returns the larger of a or b compared using a<b.
*
* @note If b is a NaN the above template returns a, but should return NaN.
* \note If b is a NaN the above template returns a, but should return NaN.
* These specializations ensure that epicsMax(x,NaN) == NaN
*/
template <>
@@ -99,7 +99,7 @@ inline const double& epicsMax (const double& a, const double& b)
/**
* Swaps the values of a and b.
*
* @note The data type must support both copy-construction and assignment.
* \note The data type must support both copy-construction and assignment.
*
*/
template <class T>
modules/libcom/src/dbmf/dbmf.h
+32 -32
View File
@@ -8,10 +8,10 @@
\*************************************************************************/
/**
* @file dbmf.h
* @author Jim Kowalkowski, Marty Kraimer
* \file dbmf.h
* \author Jim Kowalkowski, Marty Kraimer
*
* @brief A library to manage storage that is allocated and quickly freed.
* \brief A library to manage storage that is allocated and quickly freed.
*
* Database Macro/Free describes a facility that prevents memory fragmentation
* when temporary storage is being allocated and freed a short time later, at
@@ -24,10 +24,10 @@
* - Between those calls to malloc() and free(), additional calls to
* malloc() are made that do NOT have an associated free().
*
* @note In some environment, e.g. vxWorks, this behavior causes severe memory
* \note In some environment, e.g. vxWorks, this behavior causes severe memory
* fragmentation.
*
* @note This facility should NOT be used by code that allocates storage and
* \note This facility should NOT be used by code that allocates storage and
* then keeps it for a considerable period of time before releasing. Such code
* should consider using the freeList library.
*/
@@ -42,67 +42,67 @@ extern "C" {
#endif
/**
* @brief Initialize the facility
* @param size The maximum size request from dbmfMalloc() that will be
* \brief Initialize the facility
* \param size The maximum size request from dbmfMalloc() that will be
* allocated from the dbmf pool (Size is always made a multiple of 8).
* @param chunkItems Each time malloc() must be called size*chunkItems bytes
* \param chunkItems Each time malloc() must be called size*chunkItems bytes
* are allocated.
* @return 0 on success, -1 if already initialized
* \return 0 on success, -1 if already initialized
*
* @note If dbmfInit() is not called before one of the other routines then it
* \note If dbmfInit() is not called before one of the other routines then it
* is automatically called with size=64 and chunkItems=10
*/
epicsShareFunc int dbmfInit(size_t size, int chunkItems);
/**
* @brief Allocate memory.
* @param bytes If bytes > size then malloc() is used to allocate the memory.
* @return Pointer to the newly-allocated memory, or NULL on failure.
* \brief Allocate memory.
* \param bytes If bytes > size then malloc() is used to allocate the memory.
* \return Pointer to the newly-allocated memory, or NULL on failure.
*/
epicsShareFunc void * dbmfMalloc(size_t bytes);
/**
* @brief Duplicate a string.
* \brief Duplicate a string.
*
* Create a copy of the input string.
* @param str Pointer to the null-terminated string to be copied.
* @return A pointer to the new copy, or NULL on failure.
* \param str Pointer to the null-terminated string to be copied.
* \return A pointer to the new copy, or NULL on failure.
*/
epicsShareFunc char * dbmfStrdup(const char *str);
/**
* @brief Duplicate a string (up to len bytes).
* \brief Duplicate a string (up to len bytes).
*
* Copy at most len bytes of the input string into a new buffer. If no nil
* terminator is seen in the first @c len bytes a nil terminator is added.
* @param str Pointer to the null-terminated string to be copied.
* @param len Max number of bytes to copy.
* @return A pointer to the new string, or NULL on failure.
* terminator is seen in the first \c len bytes a nil terminator is added.
* \param str Pointer to the null-terminated string to be copied.
* \param len Max number of bytes to copy.
* \return A pointer to the new string, or NULL on failure.
*/
epicsShareFunc char * dbmfStrndup(const char *str, size_t len);
/**
* @brief Concatenate three strings.
* \brief Concatenate three strings.
* Returns a pointer to a null-terminated string made by concatenating the
* three input strings.
* @param lhs Start string to which the others get concatenated to (left part).
* @param mid Next string to be concatenated to the lhs (mid part).
* @param rhs Last string to be concatenated to the lhs+mid (right part).
* @return A pointer to the new string, or NULL on failure.
* \param lhs Start string to which the others get concatenated to (left part).
* \param mid Next string to be concatenated to the lhs (mid part).
* \param rhs Last string to be concatenated to the lhs+mid (right part).
* \return A pointer to the new string, or NULL on failure.
*/
epicsShareFunc char * dbmfStrcat3(const char *lhs, const char *mid,
const char *rhs);
/**
* @brief Free the memory allocated by dbmfMalloc.
* @param bytes Pointer to memory obtained from dbmfMalloc(), dbmfStrdup(),
* \brief Free the memory allocated by dbmfMalloc.
* \param bytes Pointer to memory obtained from dbmfMalloc(), dbmfStrdup(),
* dbmfStrndup() or dbmfStrcat3().
*/
epicsShareFunc void dbmfFree(void *bytes);
/**
* @brief Free all chunks that contain only free items.
* \brief Free all chunks that contain only free items.
*/
epicsShareFunc void dbmfFreeChunks(void);
/**
* @brief Show the status of the dbmf memory pool.
* @param level Detail level.
* @return 0.
* \brief Show the status of the dbmf memory pool.
* \param level Detail level.
* \return 0.
*/
epicsShareFunc int dbmfShow(int level);
modules/libcom/src/ellLib/ellLib.h
+84 -87
View File
@@ -7,16 +7,16 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/**
* @file ellLib.h
* @author John Winans (ANL)
* @author Andrew Johnson (ANL)
* \file ellLib.h
* \author John Winans (ANL)
* \author Andrew Johnson (ANL)
*
* @brief A doubly-linked list library
* \brief A doubly-linked list library
*
* This provides similar functionality to the VxWorks lstLib library.
*
* Supports the creation and maintenance of a doubly-linked list. The user
* supplies a list descriptor (type ELLLIST) that will contain pointers to
* supplies a list descriptor (type \c ELLLIST) that will contain pointers to
* the first and last nodes in the list, and a count of the number of
* nodes in the list. The nodes in the list can be any user-defined structure,
* but they must reserve space for two pointers as their first elements.
@@ -32,9 +32,9 @@
extern "C" {
#endif
/** @brief List node type.
/** \brief List node type.
*
* A list node (@c ELLNODE) must be embedded in the structure to be placed
* A list node (an \c ELLNODE) must be embedded in the structure to be placed
* on the list, ideally as the first member of that structure.
*
* If the node is elsewhere in the structure, care must be taken to convert
@@ -43,26 +43,26 @@ extern "C" {
* cannot be used with such a list.
*/
typedef struct ELLNODE {
struct ELLNODE *next; /**< @brief Pointer to next node in list */
struct ELLNODE *previous; /**< @brief Pointer to previous node in list */
struct ELLNODE *next; /**< \brief Pointer to next node in list */
struct ELLNODE *previous; /**< \brief Pointer to previous node in list */
} ELLNODE;
/** @brief Value of a terminal node
/** \brief Value of a terminal node
*/
#define ELLNODE_INIT {NULL, NULL}
/** @brief List header type
/** \brief List header type
*/
typedef struct ELLLIST {
ELLNODE node; /**< @brief Pointers to the first and last nodes on list */
int count; /**< @brief Number of nodes on the list */
ELLNODE node; /**< \brief Pointers to the first and last nodes on list */
int count; /**< \brief Number of nodes on the list */
} ELLLIST;
/** @brief Value of an empty list
/** \brief Value of an empty list
*/
#define ELLLIST_INIT {ELLNODE_INIT, 0}
/** @brief Pointer to free() for use by ellFree() macro.
/** \brief Pointer to free() for use by ellFree() macro.
*
* This is required for use on Windows, where each DLL has its own free()
* function. The ellFree() macro passes the application's version of free()
@@ -70,146 +70,143 @@ typedef struct ELLLIST {
*/
typedef void (*FREEFUNC)(void *);
/** @brief Initialize a list type
* @param PLIST Pointer to list header to be initialized
/** \brief Initialize a list type
* \param PLIST Pointer to list header to be initialized
*/
#define ellInit(PLIST) {\
(PLIST)->node.next = (PLIST)->node.previous = NULL;\
(PLIST)->count = 0;\
}
/** @brief Report the number of nodes in a list
* @param PLIST Pointer to list descriptor
* @return Number of nodes in the list
/** \brief Report the number of nodes in a list
* \param PLIST Pointer to list descriptor
* \return Number of nodes in the list
*/
#define ellCount(PLIST) ((PLIST)->count)
/** @brief Find the first node in list
* @param PLIST Pointer to list descriptor
* @return Pointer to first node in the list
/** \brief Find the first node in list
* \param PLIST Pointer to list descriptor
* \return Pointer to first node in the list
*/
#define ellFirst(PLIST) ((PLIST)->node.next)
/** @brief Find the last node in list
* @param PLIST Pointer to list descriptor
* @return Pointer to last node in the list
/** \brief Find the last node in list
* \param PLIST Pointer to list descriptor
* \return Pointer to last node in the list
*/
#define ellLast(PLIST) ((PLIST)->node.previous)
/** @brief Find the next node in list
* @param PNODE Pointer to node whose successor is to be found
* @return Pointer to the node following @c PNODE
/** \brief Find the next node in list
* \param PNODE Pointer to node whose successor is to be found
* \return Pointer to the node following \c PNODE
*/
#define ellNext(PNODE) ((PNODE)->next)
/** @brief Find the previous node in list
* @param PNODE Pointer to node whose predecessor is to be found
* @return Pointer to the node prior to @c PNODE
/** \brief Find the previous node in list
* \param PNODE Pointer to node whose predecessor is to be found
* \return Pointer to the node prior to \c PNODE
*/
#define ellPrevious(PNODE) ((PNODE)->previous)
/** @brief Free up the list
* @param PLIST List for which to free all nodes
/** \brief Free up the list
* \param PLIST List for which to free all nodes
*/
#define ellFree(PLIST) ellFree2(PLIST, free)
/**
* @brief Adds a node to the end of a list
* @param pList Pointer to list descriptor
* @param pNode Pointer to node to be added
* \brief Adds a node to the end of a list
* \param pList Pointer to list descriptor
* \param pNode Pointer to node to be added
*/
epicsShareFunc void ellAdd (ELLLIST *pList, ELLNODE *pNode);
/**
* @brief Concatenates a list to the end of another list.
* \brief Concatenates a list to the end of another list.
* The list to be added is left empty. Either list (or both)
* can be empty at the beginning of the operation.
* @param pDstList Destination list
* @param pAddList List to be added to @c pDstList
* \param pDstList Destination list
* \param pAddList List to be added to \c pDstList
*/
epicsShareFunc void ellConcat (ELLLIST *pDstList, ELLLIST *pAddList);
/**
* @brief Deletes a node from a list.
* @param pList Pointer to list descriptor
* @param pNode Pointer to node to be deleted
* \brief Deletes a node from a list.
* \param pList Pointer to list descriptor
* \param pNode Pointer to node to be deleted
*/
epicsShareFunc void ellDelete (ELLLIST *pList, ELLNODE *pNode);
/**
* @brief Extract a sublist from a list.
* @param pSrcList Pointer to source list
* @param pStartNode First node in @c pSrcList to be extracted
* @param pEndNode Last node in @c pSrcList to be extracted
* @param pDstList Pointer to list where to put extracted list
* \brief Extract a sublist from a list.
* \param pSrcList Pointer to source list
* \param pStartNode First node in \c pSrcList to be extracted
* \param pEndNode Last node in \c pSrcList to be extracted
* \param pDstList Pointer to list where to put extracted list
*/
epicsShareFunc void ellExtract (ELLLIST *pSrcList, ELLNODE *pStartNode, ELLNODE *pEndNode, ELLLIST *pDstList);
/**
* @brief Deletes and returns the first node from a list
* @param pList Pointer to list from which to get node
* @return Pointer to the first node from the list, or NULL if the list is empty
* \brief Deletes and returns the first node from a list
* \param pList Pointer to list from which to get node
* \return Pointer to the first node from the list, or NULL if the list is empty
*/
epicsShareFunc ELLNODE * ellGet (ELLLIST *pList);
/**
* @brief Deletes and returns the last node from a list.
* @param pList Pointer to list from which to get node
* @return Pointer to the last node from the list, or NULL if the list is empty
* \brief Deletes and returns the last node from a list.
* \param pList Pointer to list from which to get node
* \return Pointer to the last node from the list, or NULL if the list is empty
*/
epicsShareFunc ELLNODE * ellPop (ELLLIST *pList);
/**
* @brief Inserts a node into a list immediately after a specific node
* @param plist Pointer to list into which to insert node
* @param pPrev Pointer to the node after which to insert
* @param pNode Pointer to the node to be inserted
* @note If @c pPrev is NULL @c pNode will be inserted at the head of the list
* \brief Inserts a node into a list immediately after a specific node
* \param plist Pointer to list into which to insert node
* \param pPrev Pointer to the node after which to insert
* \param pNode Pointer to the node to be inserted
* \note If \c pPrev is NULL \c pNode will be inserted at the head of the list
*/
epicsShareFunc void ellInsert (ELLLIST *plist, ELLNODE *pPrev, ELLNODE *pNode);
/**
* @brief Find the Nth node in a list
* @param pList Pointer to list from which to find node
* @param nodeNum Index of the node to be found
* @return Pointer to the element at index @c nodeNum in pList, or NULL if
* \brief Find the Nth node in a list
* \param pList Pointer to list from which to find node
* \param nodeNum Index of the node to be found
* \return Pointer to the element at index \c nodeNum in pList, or NULL if
* there is no such node in the list.
* @note The first node has index 1.
* \note The first node has index 1.
*/
epicsShareFunc ELLNODE * ellNth (ELLLIST *pList, int nodeNum);
/**
* @brief Find the list node @c nStep steps away from a specified node
* @param pNode The known node
* @param nStep How many steps to take, may be negative to step backwards
* @return Pointer to the node @c nStep nodes from @c pNode, or NULL if there
* \brief Find the list node \c nStep steps away from a specified node
* \param pNode The known node
* \param nStep How many steps to take, may be negative to step backwards
* \return Pointer to the node \c nStep nodes from \c pNode, or NULL if there
* is no such node in the list.
*/
epicsShareFunc ELLNODE * ellNStep (ELLNODE *pNode, int nStep);
/**
* @brief Find the index of a specific node in a list
* @param pList Pointer to list to search
* @param pNode Pointer to node to search for
* @return The node's index, or -1 if it cannot be found on the list.
* @note The first node has index 1.
* \brief Find the index of a specific node in a list
* \param pList Pointer to list to search
* \param pNode Pointer to node to search for
* \return The node's index, or -1 if it cannot be found on the list.
* \note The first node has index 1.
*/
epicsShareFunc int ellFind (ELLLIST *pList, ELLNODE *pNode);
typedef int (*pListCmp)(const ELLNODE* A, const ELLNODE* B);
/**
* @author Michael Davidsaver
* @date 2016
*
* @brief Stable (MergeSort) of a given list.
* @param pList Pointer to list to be sorted
* @param pListCmp Compare function to be used
* @note The comparison function cmp(A,B) is expected
* \brief Stable (MergeSort) of a given list.
* \param pList Pointer to list to be sorted
* \param pListCmp Compare function to be used
* \note The comparison function cmp(A,B) is expected
* to return -1 for A<B, 0 for A==B, and 1 for A>B.
*
* @note Use of mergesort algorithm based on analysis by
* \note Use of mergesort algorithm based on analysis by
* http://www.chiark.greenend.org.uk/~sgtatham/algorithms/listsort.html
*/
epicsShareFunc void ellSortStable(ELLLIST *pList, pListCmp pListCmp);
/**
* @brief Free all the nodes in a list.
* \brief Free all the nodes in a list.
*
* This routine empties a list, calling freeFunc() for every node on it.
* @param pList List from which to free all nodes
* @param freeFunc The free() routine to be called
* @note The nodes in the list are free()'d on the assumption that the node
* \param pList List from which to free all nodes
* \param freeFunc The free() routine to be called
* \note The nodes in the list are free()'d on the assumption that the node
* structures were malloc()'d one-at-a-time and that the ELLNODE structure is
* the first member of the parent structure.
*/
epicsShareFunc void ellFree2 (ELLLIST *pList, FREEFUNC freeFunc);
/**
* @brief Verifies that the list is consistent
* @param pList List to be verified
* \brief Verifies that the list is consistent
* \param pList List to be verified
*/
epicsShareFunc void ellVerify (ELLLIST *pList);
modules/libcom/src/env/envDefs.h
Vendored
+52 -52
View File
@@ -8,10 +8,10 @@
\*************************************************************************/
/**
* @file envDefs.h
* @author Roger A. Cole
* \file envDefs.h
* \author Roger A. Cole
*
* @brief Routines to get and set EPICS environment parameters.
* \brief Routines to get and set EPICS environment parameters.
*
* This file defines environment parameters used by EPICS and the
* routines used to get and set those parameter values.
@@ -23,7 +23,7 @@
* own use--the only caveat is that such parameters aren't automatically
* setup by EPICS.
*
* @note bldEnvData.pl looks for "epicsShareExtern const ENV_PARAM <name>;"
* \note bldEnvData.pl looks for "epicsShareExtern const ENV_PARAM <name>;"
*/
#ifndef envDefsH
@@ -36,11 +36,11 @@ extern "C" {
#include "shareLib.h"
/**
* @brief A structure to hold a single environment parameter
* \brief A structure to hold a single environment parameter
*/
typedef struct envParam {
char *name; /**< @brief Name of the parameter */
char *pdflt; /**< @brief Default value */
char *name; /**< \brief Name of the parameter */
char *pdflt; /**< \brief Default value */
} ENV_PARAM;
epicsShareExtern const ENV_PARAM EPICS_CA_ADDR_LIST;
@@ -58,7 +58,7 @@ epicsShareExtern const ENV_PARAM EPICS_CAS_IGNORE_ADDR_LIST;
epicsShareExtern const ENV_PARAM EPICS_CAS_AUTO_BEACON_ADDR_LIST;
epicsShareExtern const ENV_PARAM EPICS_CAS_BEACON_ADDR_LIST;
epicsShareExtern const ENV_PARAM EPICS_CAS_SERVER_PORT;
epicsShareExtern const ENV_PARAM EPICS_CA_BEACON_PERIOD; /**< @brief deprecated */
epicsShareExtern const ENV_PARAM EPICS_CA_BEACON_PERIOD; /**< \brief deprecated */
epicsShareExtern const ENV_PARAM EPICS_CAS_BEACON_PERIOD;
epicsShareExtern const ENV_PARAM EPICS_CAS_BEACON_PORT;
epicsShareExtern const ENV_PARAM EPICS_BUILD_COMPILER_CLASS;
@@ -80,7 +80,7 @@ epicsShareExtern const ENV_PARAM *env_param_list[];
struct in_addr;
/**
* @brief Get value of a configuration parameter
* \brief Get value of a configuration parameter
*
* Gets the value of a configuration parameter from the environment
* and copies it into the caller's buffer. If the parameter isn't
@@ -88,20 +88,20 @@ struct in_addr;
* copied instead. If neither provides a non-empty string the buffer
* is set to '\0' and NULL is returned.
*
* @param pParam Pointer to config param structure.
* @param bufDim Dimension of parameter buffer
* @param pBuf Pointer to parameter buffer
* @return Pointer to the environment variable value string, or
* \param pParam Pointer to config param structure.
* \param bufDim Dimension of parameter buffer
* \param pBuf Pointer to parameter buffer
* \return Pointer to the environment variable value string, or
* NULL if no parameter value and default value was empty.
*/
epicsShareFunc char * epicsShareAPI
envGetConfigParam(const ENV_PARAM *pParam, int bufDim, char *pBuf);
/**
* @brief Get a configuration parameter's value or default string.
* \brief Get a configuration parameter's value or default string.
*
* @param pParam Pointer to config param structure.
* @return Pointer to the environment variable value string, or to
* \param pParam Pointer to config param structure.
* \return Pointer to the environment variable value string, or to
* the default value for the parameter, or NULL if those strings
* were empty or not set.
*/
@@ -109,16 +109,16 @@ epicsShareFunc const char * epicsShareAPI
envGetConfigParamPtr(const ENV_PARAM *pParam);
/**
* @brief Print the value of a configuration parameter.
* \brief Print the value of a configuration parameter.
*
* @param pParam Pointer to config param structure.
* @return 0
* \param pParam Pointer to config param structure.
* \return 0
*/
epicsShareFunc long epicsShareAPI
envPrtConfigParam(const ENV_PARAM *pParam);
/**
* @brief Get value of an inet addr config parameter.
* \brief Get value of an inet addr config parameter.
*
* Gets the value of a configuration parameter and copies it into
* the caller's (struct in_addr) buffer. If the configuration parameter
@@ -129,67 +129,67 @@ epicsShareFunc long epicsShareAPI
* If no parameter is found and there is no default, then -1 is
* returned and the callers buffer is unmodified.
*
* @param pParam Pointer to config param structure.
* @param pAddr Pointer to struct to receive inet addr.
* @return 0, or -1 if an error is encountered
* \param pParam Pointer to config param structure.
* \param pAddr Pointer to struct to receive inet addr.
* \return 0, or -1 if an error is encountered
*/
epicsShareFunc long epicsShareAPI
envGetInetAddrConfigParam(const ENV_PARAM *pParam, struct in_addr *pAddr);
/**
* @brief Get value of a double configuration parameter.
* \brief Get value of a double configuration parameter.
*
* Gets the value of a configuration parameter, converts it into a
* @c double value and copies that into the caller's buffer. If the
* \c double value and copies that into the caller's buffer. If the
* configuration parameter isn't found in the environment, the
* default value for the parameter is used instead.
*
* If no parameter is found and there is no default, then -1 is
* returned and the callers buffer is unmodified.
*
* @param pParam Pointer to config param structure.
* @param pDouble Pointer to place to store value.
* @return 0, or -1 if an error is encountered
* \param pParam Pointer to config param structure.
* \param pDouble Pointer to place to store value.
* \return 0, or -1 if an error is encountered
*/
epicsShareFunc long epicsShareAPI
envGetDoubleConfigParam(const ENV_PARAM *pParam, double *pDouble);
/**
* @brief Get value of a long configuration parameter.
* \brief Get value of a long configuration parameter.
*
* Gets the value of a configuration parameter, converts it into a
* @c long value and copies that into the caller's buffer. If the
* \c long value and copies that into the caller's buffer. If the
* configuration parameter isn't found in the environment, the
* default value for the parameter is used instead.
*
* If no parameter is found and there is no default, then -1 is
* returned and the callers buffer is unmodified.
*
* @param pParam Pointer to config param structure.
* @param pLong Pointer to place to store value.
* @return 0, or -1 if an error is encountered
* \param pParam Pointer to config param structure.
* \param pLong Pointer to place to store value.
* \return 0, or -1 if an error is encountered
*/
epicsShareFunc long epicsShareAPI
envGetLongConfigParam(const ENV_PARAM *pParam, long *pLong);
/**
* @brief Get value of a port number configuration parameter.
* \brief Get value of a port number configuration parameter.
*
* Returns the value of a configuration parameter that represents
* an inet port number. If no environment variable is found the
* default parameter value is used, and if that is also unset the
* @c defaultPort argument returned instead. The integer value must
* \c defaultPort argument returned instead. The integer value must
* fall between the values IPPORT_USERRESERVED and USHRT_MAX or the
* @c defaultPort argument will be substituted instead.
* \c defaultPort argument will be substituted instead.
*
* @param pEnv Pointer to config param structure.
* @param defaultPort Port number to be used if environment settings invalid.
* @return Port number.
* \param pEnv Pointer to config param structure.
* \param defaultPort Port number to be used if environment settings invalid.
* \return Port number.
*/
epicsShareFunc unsigned short epicsShareAPI envGetInetPortConfigParam
(const ENV_PARAM *pEnv, unsigned short defaultPort);
/**
* @brief Get value of a boolean configuration parameter.
* \brief Get value of a boolean configuration parameter.
*
* Gets the value of a configuration parameter, and puts the value
* 0 or 1 into the caller's buffer depending on the value. If the
@@ -203,38 +203,38 @@ epicsShareFunc unsigned short epicsShareAPI envGetInetPortConfigParam
* If no parameter is found and there is no default, then -1 is
* returned and the callers buffer is unmodified.
*
* @param pParam Pointer to config param structure.
* @param pBool Pointer to place to store value.
* @return 0, or -1 if an error is encountered
* \param pParam Pointer to config param structure.
* \param pBool Pointer to place to store value.
* \return 0, or -1 if an error is encountered
*/
epicsShareFunc long epicsShareAPI
envGetBoolConfigParam(const ENV_PARAM *pParam, int *pBool);
/**
* @brief Prints all configuration parameters and their current value.
* \brief Prints all configuration parameters and their current value.
*
* @return 0
* \return 0
*/
epicsShareFunc long epicsShareAPI epicsPrtEnvParams(void);
/**
* @brief Set an environment variable's value
* \brief Set an environment variable's value
*
* The setenv() routine is not available on all operating systems.
* This routine provides a portable alternative for all EPICS targets.
* @param name Environment variable name.
* @param value New value for environment variable.
* \param name Environment variable name.
* \param value New value for environment variable.
*/
epicsShareFunc void epicsShareAPI epicsEnvSet (const char *name, const char *value);
/**
* @brief Clear the value of an environment variable
* @param name Environment variable name.
* \brief Clear the value of an environment variable
* \param name Environment variable name.
*/
epicsShareFunc void epicsShareAPI epicsEnvUnset (const char *name);
/**
* @brief Print value of an environment variable, or all variables
* \brief Print value of an environment variable, or all variables
*
* @param name Environment variable name, or NULL to show all.
* \param name Environment variable name, or NULL to show all.
*/
epicsShareFunc void epicsShareAPI epicsEnvShow (const char *name);
modules/libcom/src/iocsh/iocsh.h
+11 -11
View File
@@ -85,27 +85,27 @@ epicsShareFunc const iocshVarDef * epicsShareAPI iocshFindVariable(
/* This should only be called when iocsh is no longer needed*/
epicsShareFunc void epicsShareAPI iocshFree(void);
/** shorthand for @code iocshLoad(pathname, NULL) @endcode */
/** shorthand for \code iocshLoad(pathname, NULL) \endcode */
epicsShareFunc int epicsShareAPI iocsh(const char *pathname);
/** shorthand for @code iocshRun(cmd, NULL) @endcode */
/** shorthand for \code iocshRun(cmd, NULL) \endcode */
epicsShareFunc int epicsShareAPI iocshCmd(const char *cmd);
/** Read and evaluate IOC shell commands from the given file.
* @param pathname Path to script file
* @param macros NULL or a comma seperated list of macro definitions. eg. "VAR1=x,VAR2=y"
* @return 0 on success, non-zero on error
* \param pathname Path to script file
* \param macros NULL or a comma seperated list of macro definitions. eg. "VAR1=x,VAR2=y"
* \return 0 on success, non-zero on error
*/
epicsShareFunc int epicsShareAPI iocshLoad(const char *pathname, const char* macros);
/** Evaluate a single IOC shell command
* @param cmd Command string. eg. "echo \"something or other\""
* @param macros NULL or a comma seperated list of macro definitions. eg. "VAR1=x,VAR2=y"
* @return 0 on success, non-zero on error
* \param cmd Command string. eg. "echo \"something or other\""
* \param macros NULL or a comma seperated list of macro definitions. eg. "VAR1=x,VAR2=y"
* \return 0 on success, non-zero on error
*/
epicsShareFunc int epicsShareAPI iocshRun(const char *cmd, const char* macros);
/** @brief Signal error from an IOC shell function.
/** \brief Signal error from an IOC shell function.
*
* @param err 0 - success (no op), !=0 - error
* @return The err argument value.
* \param err 0 - success (no op), !=0 - error
* \return The err argument value.
*/
epicsShareFunc int iocshSetError(int err);
modules/libcom/src/macLib/macLib.h
+52 -52
View File
@@ -7,9 +7,9 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/**
* @file macLib.h
* @brief Text macro substitution routines
* @author William Lupton, W. M. Keck Observatory
* \file macLib.h
* \brief Text macro substitution routines
* \author William Lupton, W. M. Keck Observatory
*
* This general purpose macro substitution library
* is used for all macro substitutions in EPICS Base.
@@ -31,31 +31,31 @@
extern "C" {
#endif
/** @brief Maximum size of a macro name or value
/** \brief Maximum size of a macro name or value
*/
#define MAC_SIZE 256
/** @brief Macro substitution context, for use by macLib routines only.
/** \brief Macro substitution context, for use by macLib routines only.
*
* An application may have multiple active contexts if desired.
*/
typedef struct {
long magic; /**< @brief magic number (used for authentication) */
int dirty; /**< @brief values need expanding from raw values? */
int level; /**< @brief scoping level */
int debug; /**< @brief debugging level */
ELLLIST list; /**< @brief macro name / value list */
int flags; /**< @brief operating mode flags */
long magic; /**< \brief magic number (used for authentication) */
int dirty; /**< \brief values need expanding from raw values? */
int level; /**< \brief scoping level */
int debug; /**< \brief debugging level */
ELLLIST list; /**< \brief macro name / value list */
int flags; /**< \brief operating mode flags */
} MAC_HANDLE;
/** @name Core Library
/** \name Core Library
* The core library provides a minimal set of basic operations.
* @{
*/
/**
* @brief Creates a new macro substitution context.
* @return 0 = OK; <0 = ERROR
* \brief Creates a new macro substitution context.
* \return 0 = OK; <0 = ERROR
*/
epicsShareFunc long
epicsShareAPI macCreateHandle(
@@ -64,16 +64,16 @@ epicsShareAPI macCreateHandle(
const char * pairs[] /**< pointer to NULL-terminated array of
{name,value} pair strings. A NULL
value implies undefined; a NULL @c pairs
value implies undefined; a NULL \c pairs
argument implies no macros. */
);
/**
* @brief Disable or enable warning messages.
* \brief Disable or enable warning messages.
*
* The macExpandString() routine prints warnings when it cant expand a macro.
* This routine can be used to silence those warnings. A non zero value will
* suppress the warning messages from subsequent library routines given the
* same @c handle.
* same \c handle.
*/
epicsShareFunc void
epicsShareAPI macSuppressWarning(
@@ -83,15 +83,15 @@ epicsShareAPI macSuppressWarning(
);
/**
* @brief Expand a string which may contain macro references.
* @return Returns the length of the expanded string, <0 if any macro are
* \brief Expand a string which may contain macro references.
* \return Returns the length of the expanded string, <0 if any macro are
* undefined
*
* This routine parses the @c src string looking for macro references and
* This routine parses the \c src string looking for macro references and
* passes any it finds to macGetValue() for translation.
*
* @note The return value is similar to that of macGetValue(). Its absolute
* value is the number of characters copied to @c dest. If the return value
* \note The return value is similar to that of macGetValue(). Its absolute
* value is the number of characters copied to \c dest. If the return value
* is negative, at least one undefined macro was left unexpanded.
*/
epicsShareFunc long
@@ -106,11 +106,11 @@ epicsShareAPI macExpandString(
);
/**
* @brief Sets the value of a specific macro.
* @return Returns the length of the value string.
* @note If @c value is NULL, all instances of @c name are undefined at
* \brief Sets the value of a specific macro.
* \return Returns the length of the value string.
* \note If \c value is NULL, all instances of \c name are undefined at
* all scoping levels (the named macro doesn't have to exist in this case).
* Macros referenced in @c value need not be defined at this point.
* Macros referenced in \c value need not be defined at this point.
*/
epicsShareFunc long
epicsShareAPI macPutValue(
@@ -122,22 +122,22 @@ epicsShareAPI macPutValue(
);
/**
* @brief Returns the value of a macro
* @return Returns the length of the value string, <0 if undefined
* \brief Returns the value of a macro
* \return Returns the length of the value string, <0 if undefined
*
* @c value will be zero-terminated if the length of the value is less than
* @c capacity. The return value is the number of characters copied to
* @c value (see below for behavior if the macro is undefined). If @c capacity
* is zero, no characters will be copied to @c value (which may be NULL)
* \c value will be zero-terminated if the length of the value is less than
* \c capacity. The return value is the number of characters copied to
* \c value (see below for behavior if the macro is undefined). If \c capacity
* is zero, no characters will be copied to \c value (which may be NULL)
* and the call can be used to check whether the macro is defined.
*
* @note Truncation of the value is not reported, applications should assume
* \note Truncation of the value is not reported, applications should assume
* that truncation has occurred if the return value is equal to capacity.
*
* If the macro is undefined, the macro reference will be returned in
* the value string (if permitted by maxlen) and the function value will
* be _minus_ the number of characters copied. Note that treatment of
* @c capacity is intended to be consistent with the strncpy() routine.
* \c capacity is intended to be consistent with the strncpy() routine.
*
* If the value contains macro references, these references will be
* expanded recursively. This expansion will detect a direct or indirect
@@ -161,9 +161,9 @@ epicsShareAPI macGetValue(
long capacity /**< capacity of destination buffer (value) */
);
/**
* @brief Marks a handle invalid, and frees all storage associated with it
* @return 0 = OK; <0 = ERROR
* @note Note that this does not free any strings into which macro values have
* \brief Marks a handle invalid, and frees all storage associated with it
* \return 0 = OK; <0 = ERROR
* \note Note that this does not free any strings into which macro values have
* been returned. Macro values are always returned into strings which
* were pre-allocated by the caller.
*/
@@ -172,8 +172,8 @@ epicsShareAPI macDeleteHandle(
MAC_HANDLE *handle /**< opaque handle */
);
/**
* @brief Marks the start of a new scoping level
* @return 0 = OK; <0 = ERROR
* \brief Marks the start of a new scoping level
* \return 0 = OK; <0 = ERROR
*
* Marks all macro definitions added after this call as belonging
* to another scope. These macros will be lost on a macPopScope()
@@ -184,8 +184,8 @@ epicsShareAPI macPushScope(
MAC_HANDLE *handle /**< opaque handle */
);
/**
* @brief Retrieve the last pushed scope (like stack operations)
* @return 0 = OK; <0 = ERROR
* \brief Retrieve the last pushed scope (like stack operations)
* \return 0 = OK; <0 = ERROR
*
* See macPushScope()
*/
@@ -194,8 +194,8 @@ epicsShareAPI macPopScope(
MAC_HANDLE *handle /**< opaque handle */
);
/**
* @brief Reports details of current definitions
* @return 0 = OK; <0 = ERROR
* \brief Reports details of current definitions
* \return 0 = OK; <0 = ERROR
* This sends details of current definitions to standard output,
* and is intended purely for debugging purposes.
*/
@@ -205,15 +205,15 @@ epicsShareAPI macReportMacros(
);
/** @} */
/** @name Utility Library
/** \name Utility Library
* These convenience functions are intended for applications to use and
* provide a more convenient interface for some purposes.
* @{
*/
/**
* @brief Parse macro definitions into an array of {name, value} pairs.
* @return Number of macros found; <0 = ERROR
* \brief Parse macro definitions into an array of {name, value} pairs.
* \return Number of macros found; <0 = ERROR
*
* This takes a set of macro definitions in "a=xxx,b=yyy" format and
* converts them into an array of pointers to character strings which
@@ -251,8 +251,8 @@ epicsShareAPI macParseDefns(
);
/**
* @brief Install set of {name, value} pairs as definitions
* @return Number of macros defined; <0 = ERROR
* \brief Install set of {name, value} pairs as definitions
* \return Number of macros defined; <0 = ERROR
*
* This takes an array of pairs as defined above and installs them as
* definitions by calling macPutValue(). The pairs array is terminated
@@ -269,8 +269,8 @@ epicsShareAPI macInstallMacros(
);
/**
* @brief Expand environment variables in a string.
* @return Expanded string; NULL if any undefined macros were used.
* \brief Expand environment variables in a string.
* \return Expanded string; NULL if any undefined macros were used.
*
* This routine expands a string which may contain macros that are
* environment variables. It parses the string looking for such
@@ -285,8 +285,8 @@ epicsShareAPI macEnvExpand(
);
/**
* @brief Expands macros and environment variables in a string.
* @return Expanded string; NULL if any undefined macros were used.
* \brief Expands macros and environment variables in a string.
* \return Expanded string; NULL if any undefined macros were used.
*
* This routine is similar to macEnvExpand() but allows an optional handle
* to be passed in that may contain additional macro definitions.
modules/libcom/src/misc/adjustment.h
+2 -2
View File
@@ -9,8 +9,8 @@
\*************************************************************************/
/**
* @file adjustment.h
* @brief Declare function `adjustToWorstCaseAlignment`
* \file adjustment.h
* \brief Declare function `adjustToWorstCaseAlignment`
*
* Declares a single function `adjustToWorstCaseAlignment`.
*/
modules/libcom/src/misc/alarm.h
+12 -12
View File
@@ -8,9 +8,9 @@
\*************************************************************************/
/**
* @file alarm.h
* @brief Alarm severity and status/condition values
* @author Bob Dalesio and Marty Kraimer
* \file alarm.h
* \brief Alarm severity and status/condition values
* \author Bob Dalesio and Marty Kraimer
*
* These alarm definitions must match the related
* menuAlarmSevr.dbd and menuAlarmStat.dbd files
@@ -27,13 +27,13 @@ extern "C" {
#endif
/**
* @brief The NO_ALARM value can be used as both a severity and a status.
* \brief The NO_ALARM value can be used as both a severity and a status.
*/
#define NO_ALARM 0
/**
* @brief Alarm severity values
* @note These must match the choices in menuAlarmSevr.dbd
* \brief Alarm severity values
* \note These must match the choices in menuAlarmSevr.dbd
*/
typedef enum {
epicsSevNone = NO_ALARM, /**< No alarm */
@@ -44,7 +44,7 @@ typedef enum {
} epicsAlarmSeverity;
/**
* @name Original macros for alarm severity values
* \name Original macros for alarm severity values
* @{
*/
#define firstEpicsAlarmSev epicsSevNone
@@ -55,8 +55,8 @@ typedef enum {
/** @} */
/**
* @brief Alarm status/condition values
* @note These must match the choices in menuAlarmStat.dbd
* \brief Alarm status/condition values
* \note These must match the choices in menuAlarmStat.dbd
*/
typedef enum {
epicsAlarmNone = NO_ALARM, /**< No alarm */
@@ -85,7 +85,7 @@ typedef enum {
} epicsAlarmCondition;
/**
* @name Original macros for alarm status/condition values
* \name Original macros for alarm status/condition values
* @{
*/
#define firstEpicsAlarmCond epicsAlarmNone
@@ -114,11 +114,11 @@ typedef enum {
/** @} */
/**
* @brief How to convert an alarm severity into a string
* \brief How to convert an alarm severity into a string
*/
epicsShareExtern const char *epicsAlarmSeverityStrings [ALARM_NSEV];
/**
* @brief How to convert an alarm condition/status into a string
* \brief How to convert an alarm condition/status into a string
*/
epicsShareExtern const char *epicsAlarmConditionStrings [ALARM_NSTATUS];
modules/libcom/src/misc/alarmString.h
+5 -5
View File
@@ -8,12 +8,12 @@
\*************************************************************************/
/**
* @file alarmString.h
* @brief Deprecated, use alarm.h instead
* \file alarmString.h
* \brief Deprecated, use alarm.h instead
*
* How to convert alarm status and severity values into a string for printing.
*
* @note This file is deprecated, use alarm.h instead.
* \note This file is deprecated, use alarm.h instead.
*/
#ifndef INC_alarmString_H
@@ -26,11 +26,11 @@ extern "C" {
#endif
/**
* @brief An alias for epicsAlarmSeverityStrings
* \brief An alias for epicsAlarmSeverityStrings
*/
#define alarmSeverityString epicsAlarmSeverityStrings
/**
* @brief An alias for epicsAlarmConditionStrings
* \brief An alias for epicsAlarmConditionStrings
*/
#define alarmStatusString epicsAlarmConditionStrings
modules/libcom/src/misc/cantProceed.h
+15 -15
View File
@@ -8,8 +8,8 @@
\*************************************************************************/
/**
* @file cantProceed.h
* @brief Routines for code that can't continue or return after an error.
* \file cantProceed.h
* \brief Routines for code that can't continue or return after an error.
*
* This is the EPICS equivalent of a Kernel Panic, except that the effect
* is to halt only the thread that detects the error.
@@ -33,19 +33,19 @@
extern "C" {
#endif
/** @brief Suspend this thread, the caller cannot continue or return.
/** \brief Suspend this thread, the caller cannot continue or return.
*
* The effect of calling this is to print the error message followed by
* the name of the thread that is being suspended. A stack trace will
* also be shown if supported by the OS, and the thread is suspended
* inside an infinite loop.
* @param errorMessage A printf-style error message describing the error.
* @param ... Any parameters required for the error message.
* \param errorMessage A printf-style error message describing the error.
* \param ... Any parameters required for the error message.
*/
epicsShareFunc void cantProceed(const char *errorMessage, ...)
EPICS_PRINTF_STYLE(1,2);
/** @name Memory Allocation Functions
/** \name Memory Allocation Functions
* These versions of calloc() and malloc() never fail, they suspend the
* thread if the OS is unable to allocate the requested memory at the current
* time. If the thread is resumed, they will re-try the memory allocation,
@@ -54,18 +54,18 @@ epicsShareFunc void cantProceed(const char *errorMessage, ...)
* gracefully when memory runs out.
*/
/** @{ */
/** @brief A calloc() that never returns NULL.
* @param count Number of objects.
* @param size Size of each object.
* @param errorMessage What this memory is needed for.
* @return Pointer to zeroed allocated memory.
/** \brief A calloc() that never returns NULL.
* \param count Number of objects.
* \param size Size of each object.
* \param errorMessage What this memory is needed for.
* \return Pointer to zeroed allocated memory.
*/
epicsShareFunc void * callocMustSucceed(size_t count, size_t size,
const char *errorMessage);
/** @brief A malloc() that never returns NULL.
* @param size Size of block to allocate.
* @param errorMessage What this memory is needed for.
* @return Pointer to allocated memory.
/** \brief A malloc() that never returns NULL.
* \param size Size of block to allocate.
* \param errorMessage What this memory is needed for.
* \return Pointer to allocated memory.
*/
epicsShareFunc void * mallocMustSucceed(size_t size, const char *errorMessage);
/** @} */
modules/libcom/src/misc/dbDefs.h
+17 -17
View File
@@ -8,10 +8,10 @@
\*************************************************************************/
/**
* @file dbDefs.h
* @author Marty Kraimer
* \file dbDefs.h
* \author Marty Kraimer
*
* @brief Miscellaneous macro definitions.
* \brief Miscellaneous macro definitions.
*
* This file defines several miscellaneous macros.
*/
@@ -31,30 +31,30 @@
#endif
#define FALSE 0
/** @brief Deprecated synonym for @c static */
/** \brief Deprecated synonym for \c static */
#ifndef LOCAL
# define LOCAL static
#endif
/** @brief Number of elements in array */
/** \brief Number of elements in array */
#ifndef NELEMENTS
# define NELEMENTS(array) (sizeof (array) / sizeof ((array) [0]))
#endif
/** @brief Deprecated synonym for @c offsetof */
/** \brief Deprecated synonym for \c offsetof */
#ifndef OFFSET
# define OFFSET(structure, member) offsetof(structure, member)
#endif
/** @brief Find parent object from a member pointer
/** \brief Find parent object from a member pointer
*
* Subtracts the byte offset of the member in the structure from the
* pointer to the member itself, giving a pointer to parent strucure.
* @param ptr Pointer to a member data field of a structure
* @param structure Type name of the parent structure
* @param member Field name of the data member
* @return Pointer to the parent structure
* @note Both GCC and Clang will type-check this macro.
* \param ptr Pointer to a member data field of a structure
* \param structure Type name of the parent structure
* \param member Field name of the data member
* \return Pointer to the parent structure
* \note Both GCC and Clang will type-check this macro.
*/
#ifndef CONTAINER
# ifdef __GNUC__
@@ -68,18 +68,18 @@
# endif
#endif
/** @brief Size of a record name including the nil terminator */
/** \brief Size of a record name including the nil terminator */
#define PVNAME_STRINGSZ 61
/** @brief Size of a record name without the nil terminator */
/** \brief Size of a record name without the nil terminator */
#define PVNAME_SZ (PVNAME_STRINGSZ - 1)
/**
* @def PVLINK_STRINGSZ
* @brief Buffer size for the string representation of a DBF_*LINK field
* \def PVLINK_STRINGSZ
* \brief Buffer size for the string representation of a DBF_*LINK field
*/
#define PVLINK_STRINGSZ 1024
/** @brief dbAccess enums/menus can have up to this many choices */
/** \brief dbAccess enums/menus can have up to this many choices */
#define DB_MAX_CHOICES 30
#endif /* INC_dbDefs_H */
modules/libcom/src/misc/epicsExit.h
+21 -21
View File
@@ -8,9 +8,9 @@
\*************************************************************************/
/*epicsExit.h*/
/**
* @file epicsExit.h
* \file epicsExit.h
*
* @brief Extended replacement for the Posix exit and atexit routines.
* \brief Extended replacement for the Posix exit and atexit routines.
*
* This is an extended replacement for the Posix exit and atexit routines, which
* also provides a pointer argument to pass to the exit handlers. This facility
@@ -28,61 +28,61 @@ extern "C" {
#endif
/**
* @brief Pointer to a callback function that is to be called
* \brief Pointer to a callback function that is to be called
* by the epicsExit subsystem.
*/
typedef void (*epicsExitFunc)(void *arg);
/**
* @brief Calls epicsExitCallAtExits(), then the OS exit() routine.
* @param status Passed to exit()
* \brief Calls epicsExitCallAtExits(), then the OS exit() routine.
* \param status Passed to exit()
*/
epicsShareFunc void epicsExit(int status);
/**
* @brief Arrange to call epicsExit() later from a low priority thread.
* \brief Arrange to call epicsExit() later from a low priority thread.
*
* This delays the actual call to exit() so it doesn't run in this thread.
* @param status Passed to exit()
* \param status Passed to exit()
*/
epicsShareFunc void epicsExitLater(int status);
/**
* @brief Internal routine that runs the registered exit routines.
* \brief Internal routine that runs the registered exit routines.
*
* Calls each of the functions registered by prior calls to epicsAtExit
* in reverse order of their registration.
* @note Most applications will not call this routine directly.
* \note Most applications will not call this routine directly.
*/
epicsShareFunc void epicsExitCallAtExits(void);
/**
* @brief Register a function and an associated context parameter
* @param func Function to be called when epicsExitCallAtExits is invoked.
* @param arg Context parameter for the function.
* @param name Function name
* \brief Register a function and an associated context parameter
* \param func Function to be called when epicsExitCallAtExits is invoked.
* \param arg Context parameter for the function.
* \param name Function name
*/
epicsShareFunc int epicsAtExit3(epicsExitFunc func, void *arg, const char* name);
/**
* @brief Convenience macro to register a function and context value to be
* \brief Convenience macro to register a function and context value to be
* run when the process exits.
* @param F Function to be called at process shutdown.
* @param A Context parameter for the function.
* \param F Function to be called at process shutdown.
* \param A Context parameter for the function.
*/
#define epicsAtExit(F,A) epicsAtExit3(F,A,#F)
/**
* @brief Internal routine that runs the registered thread exit routines.
* \brief Internal routine that runs the registered thread exit routines.
*
* Calls each of the functions that were registered in the current thread by
* calling epicsAtThreadExit(), in reverse order of their registration.
* @note This routine is called automatically when an epicsThread's main
* \note This routine is called automatically when an epicsThread's main
* entry routine returns. It will not be run if the thread gets stopped by
* some other method.
*/
epicsShareFunc void epicsExitCallAtThreadExits(void);
/**
* @brief Register a function and an context value to be run by this thread
* \brief Register a function and an context value to be run by this thread
* when it returns from its entry routine.
* @param func Function be called at thread completion.
* @param arg Context parameter for the function.
* \param func Function be called at thread completion.
* \param arg Context parameter for the function.
*/
epicsShareFunc int epicsAtThreadExit(epicsExitFunc func, void *arg);
modules/libcom/src/misc/epicsExport.h
+36 -36
View File
@@ -11,8 +11,8 @@
#ifndef INC_epicsExport_H
#define INC_epicsExport_H
/** @file epicsExport.h
* @brief Exporting IOC objects.
/** \file epicsExport.h
* \brief Exporting IOC objects.
*
* This header is unique, as it defines epicsExportSharedSymbols and thus
* triggers a transition between importing declarations from other libraries,
@@ -21,9 +21,9 @@
*
* This header should be included with a trailing comment to make it stand
* out from other includes, something like this:
@code
\code
#include <epicsExport.h> // defines epicsExportSharedSymbols
@endcode
\endcode
*/
#define epicsExportSharedSymbols
@@ -35,82 +35,82 @@ extern "C" {
typedef void (*REGISTRAR)(void);
/** @brief Generate a name for an export object.
* @param typ Object's data type.
* @param obj Object's name.
* @return C identifier for the export object.
/** \brief Generate a name for an export object.
* \param typ Object's data type.
* \param obj Object's name.
* \return C identifier for the export object.
*/
#define EPICS_EXPORT_POBJ(typ, obj) pvar_ ## typ ## _ ## obj
/** @brief Generate a name for an export function object.
* @param fun Function's name.
* @return C identifier for the export object.
/** \brief Generate a name for an export function object.
* \param fun Function's name.
* \return C identifier for the export object.
*/
#define EPICS_EXPORT_PFUNC(fun) EPICS_EXPORT_POBJ(func, fun)
/** @brief Declare an object for exporting.
/** \brief Declare an object for exporting.
*
* The epicsExportAddress() macro must be used to declare any IOC object
* that is also named in a DBD file. For example a record support source
* file must contain a statement like:
@code
\code
epicsExportAddress(rset, myRSET);
@endcode
\endcode
*
* A device support source file must contain a statement like:
@code
\code
epicsExportAddress(dset, devMyName);
@endcode
* Note that the @p typ parameter for a device support entry table must be
* spelled @c dset even if the @p obj was actually declared as some other
* type, say using @c typed_dset .
\endcode
* Note that the \p typ parameter for a device support entry table must be
* spelled \c dset even if the \p obj was actually declared as some other
* type, say using \c typed_dset .
*
* A driver support source file must contain a statement like:
@code
\code
epicsExportAddress(drvet, drvName);
@endcode
\endcode
*
* A variable named in a DBD @c variable statement must be declared with:
@code
* A variable named in a DBD \c variable statement must be declared with:
\code
int myDebug = 0;
epicsExportAddress(int, myDebug);
@endcode
* Only @c int and @c double are currently supported for DBD variables.
\endcode
* Only \c int and \c double are currently supported for DBD variables.
*
* @param typ Object's data type.
* @param obj Object's name.
* \param typ Object's data type.
* \param obj Object's name.
*/
#define epicsExportAddress(typ, obj) \
epicsShareExtern typ *EPICS_EXPORT_POBJ(typ,obj); \
epicsShareDef typ *EPICS_EXPORT_POBJ(typ, obj) = (typ *) (char *) &obj
/** @brief Declare a registrar function for exporting.
/** \brief Declare a registrar function for exporting.
*
* The epicsExportRegistrar() macro must be used to declare a registrar
* function that is named in a DBD \c registrar statement. For example:
@code
\code
static void myRegistrar(void) {
...
}
epicsExportRegistrar(myRegistrar);
@endcode
\endcode
*
* @param fun Registrar function's name.
* \param fun Registrar function's name.
*/
#define epicsExportRegistrar(fun) \
epicsShareFunc REGISTRAR EPICS_EXPORT_PFUNC(fun) = (REGISTRAR) &fun
/** @brief Declare and register a function for exporting.
/** \brief Declare and register a function for exporting.
*
* The epicsRegisterFunction() macro must be used to declare and register
* a function that is named in a DBD @c function statement and called by
* a function that is named in a DBD \c function statement and called by
* one or more subroutine or aSub records. For example:
@code
\code
epicsRegisterFunction(mySubInit);
epicsRegisterFunction(mySubProcess);
@endcode
\endcode
*
* @param fun Function's name
* \param fun Function's name
*/
#define epicsRegisterFunction(fun) \
static void register_func_ ## fun(void) \
modules/libcom/src/misc/epicsUnitTest.h
+52 -52
View File
@@ -6,9 +6,9 @@
\*************************************************************************/
/**
* @file epicsUnitTest.h
* @brief Unit test routines
* @author Andrew Johnson
* \file epicsUnitTest.h
* \brief Unit test routines
* \author Andrew Johnson
*
* The unit test routines make it easy for a test program to generate output
* that is compatible with the Test Anything Protocol and can thus be used with
@@ -83,7 +83,7 @@
* IOC using iocBuildIsolated() or iocBuild(), it has to be started by calling
* iocRun(). The suggested call sequence in a test program that needs to run the
* IOC without Channel Access is:
@code
\code
#include "iocInit.h"
MAIN(iocTest)
@@ -98,7 +98,7 @@ MAIN(iocTest)
pdbbase = NULL;
return testDone();
}
@endcode
\endcode
* The part from iocBuildIsolated() to iocShutdown() can be repeated to
* execute multiple tests within one executable or harness.
@@ -113,7 +113,7 @@ MAIN(iocTest)
*
* The following is a simple example of a test program using the epicsUnitTest
* routines:
@code
\code
#include <math.h>
#include "epicsUnitTest.h"
#include "testMain.h"
@@ -127,10 +127,10 @@ MAIN(mathTest)
testDiag("4 * atan(1) = %g", 4.0 * atan(1.0));
return testDone();
}
@endcode
\endcode
* The output from running the above program looks like this:
@code
\code
1..3
ok 1 - Sine starts
ok 2 - Cosine continues
@@ -140,7 +140,7 @@ ok 3 - M_PI == 4.0*atan(1.0)
=======
Tests: 3
Passed: 3 = 100%
@endcode
\endcode
*/
#ifndef INC_epicsUnitTest_H
@@ -155,90 +155,90 @@ ok 3 - M_PI == 4.0*atan(1.0)
extern "C" {
#endif
/** @brief Declare the test plan, required.
* @param tests Number of tests to be run. May be zero if not known but the
/** \brief Declare the test plan, required.
* \param tests Number of tests to be run. May be zero if not known but the
* test harness then can't tell if the program dies prematurely.
*/
epicsShareFunc void testPlan(int tests);
/** @name Announcing Test Results
/** \name Announcing Test Results
* Routines that declare individual test results.
*/
/** @{ */
/** @brief Test result with printf-style description.
* @param pass True/False value indicating result.
* @param fmt A printf-style format string describing the test.
* @param ... Any parameters required for the format string.
* @return The value of \p pass.
/** \brief Test result with printf-style description.
* \param pass True/False value indicating result.
* \param fmt A printf-style format string describing the test.
* \param ... Any parameters required for the format string.
* \return The value of \p pass.
*/
epicsShareFunc int testOk(int pass, const char *fmt, ...)
EPICS_PRINTF_STYLE(2, 3);
/** @brief Test result using condition as description
* @param cond Condition to be evaluated and displayed.
* @return The value of \p cond.
/** \brief Test result using condition as description
* \param cond Condition to be evaluated and displayed.
* \return The value of \p cond.
*/
#define testOk1(cond) testOk(cond, "%s", #cond)
/** @brief Test result with var-args description.
* @param pass True/False value indicating result.
* @param fmt A printf-style format string describing the test.
* @param pvar A var-args pointer to any parameters for the format string.
* @return The value of \p pass.
/** \brief Test result with var-args description.
* \param pass True/False value indicating result.
* \param fmt A printf-style format string describing the test.
* \param pvar A var-args pointer to any parameters for the format string.
* \return The value of \p pass.
*/
epicsShareFunc int testOkV(int pass, const char *fmt, va_list pvar);
/** @brief Passing test result with printf-style description.
* @param fmt A printf-style format string describing the test.
* @param ... Any parameters required for the format string.
* @return The value of \p pass.
/** \brief Passing test result with printf-style description.
* \param fmt A printf-style format string describing the test.
* \param ... Any parameters required for the format string.
* \return The value of \p pass.
*/
epicsShareFunc void testPass(const char *fmt, ...)
EPICS_PRINTF_STYLE(1, 2);
/** @brief Failing test result with printf-style description.
* @param fmt A printf-style format string describing the test.
* @param ... Any parameters required for the format string.
/** \brief Failing test result with printf-style description.
* \param fmt A printf-style format string describing the test.
* \param ... Any parameters required for the format string.
*/
epicsShareFunc void testFail(const char *fmt, ...)
EPICS_PRINTF_STYLE(1, 2);
/** @} */
/** @name Missing or Failing Tests
* @brief Routines for handling special situations.
/** \name Missing or Failing Tests
* \brief Routines for handling special situations.
*/
/** @{ */
/** @brief Place-holders for tests that can't be run.
* @param skip How many tests are being skipped.
* @param why Reason for skipping these tests.
/** \brief Place-holders for tests that can't be run.
* \param skip How many tests are being skipped.
* \param why Reason for skipping these tests.
*/
epicsShareFunc void testSkip(int skip, const char *why);
/** @brief Mark the start of a group of tests that are expected to fail
* @param why Reason for expected failures.
/** \brief Mark the start of a group of tests that are expected to fail
* \param why Reason for expected failures.
*/
epicsShareFunc void testTodoBegin(const char *why);
/** @brief Mark the end of a failing test group.
/** \brief Mark the end of a failing test group.
*/
epicsShareFunc void testTodoEnd(void);
/** @brief Stop testing, program cannot continue.
* @param fmt A printf-style format string giving the reason for stopping.
* @param ... Any parameters required for the format string.
/** \brief Stop testing, program cannot continue.
* \param fmt A printf-style format string giving the reason for stopping.
* \param ... Any parameters required for the format string.
*/
epicsShareFunc void testAbort(const char *fmt, ...)
EPICS_PRINTF_STYLE(1, 2);
/** @} */
/** @brief Output additional diagnostics
* @param fmt A printf-style format string containing diagnostic information.
* @param ... Any parameters required for the format string.
/** \brief Output additional diagnostics
* \param fmt A printf-style format string containing diagnostic information.
* \param ... Any parameters required for the format string.
*/
epicsShareFunc int testDiag(const char *fmt, ...)
EPICS_PRINTF_STYLE(1, 2);
/** @brief Mark the end of testing.
/** \brief Mark the end of testing.
*/
epicsShareFunc int testDone(void);
epicsShareFunc
int testImpreciseTiming(void);
/** @name Test Harness for Embedded OSs
/** \name Test Harness for Embedded OSs
* These routines are used to create a test-harness that can run
* multiple test programs, collect their names and results, then
* display a summary at the end of testing.
@@ -246,17 +246,17 @@ int testImpreciseTiming(void);
/** @{ */
typedef int (*TESTFUNC)(void);
/** @brief Initialize test harness
/** \brief Initialize test harness
*/
epicsShareFunc void testHarness(void);
epicsShareFunc void testHarnessExit(void *dummy);
epicsShareFunc void runTestFunc(const char *name, TESTFUNC func);
/** @brief Run a test program
* @param func Name of the test program.
/** \brief Run a test program
* \param func Name of the test program.
*/
#define runTest(func) runTestFunc(#func, func)
/** @brief Declare all test programs finished
/** \brief Declare all test programs finished
*/
#define testHarnessDone() testHarnessExit(0)
/** @} */
modules/libcom/src/misc/shareLib.h
+5 -5
View File
@@ -7,8 +7,8 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/**
* @file shareLib.h
* @brief Mark external symbols and entry points for shared libraries.
* \file shareLib.h
* \brief Mark external symbols and entry points for shared libraries.
*
* This is the header file for the "decorated names" that appear in
* header files, e.g.
@@ -35,7 +35,7 @@
* int epicsShareAPI myExtFunc ( int arg );
* int epicsShareAPI myExtFunc ( int arg ) {}
*
* @note The epicsShareAPI attribute is deprecated and has been removed
* \note The epicsShareAPI attribute is deprecated and has been removed
* from all IOC-specific APIs. Most libCom APIs still use it, but
* it may get removed from these at some point in the future.
*
@@ -77,8 +77,8 @@
* which functions are exported from the DLL and which of them are imported
* from other DLLs.
*
* You must first @c \#include what you import and then @c \#define
* @c epicsExportSharedSymbols only right before you @c \#include the
* You must first \c \#include what you import and then \c \#define
* \c epicsExportSharedSymbols only right before you \c \#include the
* prototypes for what you implement! You must include shareLib.h again each
* time that the state of the import/export keywords changes, but this
* usually occurs as a side effect of including the shareable libraries header
modules/libcom/src/misc/unixFileName.h
+2 -2
View File
@@ -24,13 +24,13 @@ extern "C" {
#define OSI_PATH_SEPARATOR "/"
/** Return the absolute path of the current executable.
@returns NULL or the path. Caller must free()
\return NULL or the path. Caller must free()
*/
epicsShareFunc
char *epicsGetExecName(void);
/** Return the absolute path of the directory containing the current executable.
@returns NULL or the path. Caller must free()
\return NULL or the path. Caller must free()
*/
epicsShareFunc
char *epicsGetExecDir(void);
modules/libcom/src/osi/compilerDependencies.h
+3 -3
View File
@@ -8,9 +8,9 @@
\*************************************************************************/
/**
* @file compilerDependencies.h
* @author Jeffrey O. Hill johill@lanl.gov
* @brief Compiler specific declarations
* \file compilerDependencies.h
* \author Jeffrey O. Hill johill@lanl.gov
* \brief Compiler specific declarations
*
*/
modules/libcom/src/osi/devLib.h
+49 -49
View File
@@ -10,9 +10,9 @@
\*************************************************************************/
/**
* @file devLib.h
* @brief API for accessing hardware devices, originally over VMEbus
* @author Marty Kraimer and Jeff Hill
* \file devLib.h
* \brief API for accessing hardware devices, originally over VMEbus
* \author Marty Kraimer and Jeff Hill
*
* Support for allocation of common device resources
*/
@@ -20,111 +20,111 @@
#define EPICSDEVLIB_H
/**
* @name Macros for normalizing values
* @warning Deprecated, we don't know of any code currently using these.
* \name Macros for normalizing values
* \warning Deprecated, we don't know of any code currently using these.
* @{
*/
/** @brief Create a bit mask for a given number of bits */
/** \brief Create a bit mask for a given number of bits */
#define devCreateMask(NBITS) ((1<<(NBITS))-1)
/** @brief Normalize a raw integer value and convert it to type double */
/** \brief Normalize a raw integer value and convert it to type double */
#define devDigToNml(DIGITAL,NBITS) \
(((double)(DIGITAL))/devCreateMask(NBITS))
/** @brief Convert a normalized value to a raw integer */
/** \brief Convert a normalized value to a raw integer */
#define devNmlToDig(NORMAL,NBITS) \
(((long)(NORMAL)) * devCreateMask(NBITS))
/** @} */
/**
* @name Macros for pointer alignment
* @warning Deprecated, we don't know of any code currently using these.
* \name Macros for pointer alignment
* \warning Deprecated, we don't know of any code currently using these.
* @{
*/
/** @brief Create an alignment mask for CTYPE */
/** \brief Create an alignment mask for CTYPE */
#define devCreateAlignmentMask(CTYPE)\
(sizeof(CTYPE)>sizeof(double)?sizeof(double)-1:sizeof(CTYPE)-1)
/** @brief Check Pointer alignment, returns true if the pointer @c PTR
/** \brief Check Pointer alignment, returns true if the pointer \c PTR
* is suitably aligned for its data type
*/
#define devPtrAlignTest(PTR) (!(devCreateAlignmentMask(*PTR)&(long)(PTR)))
/** @} */
/**
* @name Error status values returned by devLib routines
* \name Error status values returned by devLib routines
* @{
*/
#define S_dev_success 0
/** @brief Interrupt vector in use */
/** \brief Interrupt vector in use */
#define S_dev_vectorInUse (M_devLib| 1) /*Interrupt vector in use*/
/** @brief Interrupt vector install failed */
/** \brief Interrupt vector install failed */
#define S_dev_vecInstlFail (M_devLib| 2) /*Interrupt vector install failed*/
/** @brief Unrecognized interrupt type */
/** \brief Unrecognized interrupt type */
#define S_dev_uknIntType (M_devLib| 3) /*Unrecognized interrupt type*/
/** @brief Interrupt vector not in use by caller */
/** \brief Interrupt vector not in use by caller */
#define S_dev_vectorNotInUse (M_devLib| 4) /*Interrupt vector not in use by caller*/
/** @brief Invalid VME A16 address */
/** \brief Invalid VME A16 address */
#define S_dev_badA16 (M_devLib| 5) /*Invalid VME A16 address*/
/** @brief Invalid VME A24 address */
/** \brief Invalid VME A24 address */
#define S_dev_badA24 (M_devLib| 6) /*Invalid VME A24 address*/
/** @brief Invalid VME A32 address */
/** \brief Invalid VME A32 address */
#define S_dev_badA32 (M_devLib| 7) /*Invalid VME A32 address*/
/** @brief Unrecognized address space type */
/** \brief Unrecognized address space type */
#define S_dev_uknAddrType (M_devLib| 8) /*Unrecognized address space type*/
/** @brief Specified device address overlaps another device */
/** \brief Specified device address overlaps another device */
#define S_dev_addressOverlap (M_devLib| 9) /*Specified device address overlaps another device*/
/** @brief This device already owns the address range */
/** \brief This device already owns the address range */
#define S_dev_identifyOverlap (M_devLib| 10) /*This device already owns the address range*/
/** @brief Unable to map address */
/** \brief Unable to map address */
#define S_dev_addrMapFail (M_devLib| 11) /*Unable to map address*/
/** @brief Interrupt at vector disconnected from an EPICS device */
/** \brief Interrupt at vector disconnected from an EPICS device */
#define S_dev_intDisconnect (M_devLib| 12) /*Interrupt at vector disconnected from an EPICS device*/
/** @brief Internal failure */
/** \brief Internal failure */
#define S_dev_internal (M_devLib| 13) /*Internal failure*/
/** @brief Unable to enable interrupt level */
/** \brief Unable to enable interrupt level */
#define S_dev_intEnFail (M_devLib| 14) /*Unable to enable interrupt level*/
/** @brief Unable to disable interrupt level */
/** \brief Unable to disable interrupt level */
#define S_dev_intDissFail (M_devLib| 15) /*Unable to disable interrupt level*/
/** @brief Memory allocation failed */
/** \brief Memory allocation failed */
#define S_dev_noMemory (M_devLib| 16) /*Memory allocation failed*/
/** @brief Specified device address unregistered */
/** \brief Specified device address unregistered */
#define S_dev_addressNotFound (M_devLib| 17) /*Specified device address unregistered*/
/** @brief No device at specified address */
/** \brief No device at specified address */
#define S_dev_noDevice (M_devLib| 18) /*No device at specified address*/
/** @brief Wrong device type found at specified address */
/** \brief Wrong device type found at specified address */
#define S_dev_wrongDevice (M_devLib| 19) /*Wrong device type found at specified address*/
/** @brief Signal number (offset) to large */
/** \brief Signal number (offset) to large */
#define S_dev_badSignalNumber (M_devLib| 20) /*Signal number (offset) to large*/
/** @brief Signal count to large */
/** \brief Signal count to large */
#define S_dev_badSignalCount (M_devLib| 21) /*Signal count to large*/
/** @brief Device does not support requested operation */
/** \brief Device does not support requested operation */
#define S_dev_badRequest (M_devLib| 22) /*Device does not support requested operation*/
/** @brief Parameter too high */
/** \brief Parameter too high */
#define S_dev_highValue (M_devLib| 23) /*Parameter too high*/
/** @brief Parameter too low */
/** \brief Parameter too low */
#define S_dev_lowValue (M_devLib| 24) /*Parameter too low*/
/** @brief Specified address is ambiguous (more than one device responds) */
/** \brief Specified address is ambiguous (more than one device responds) */
#define S_dev_multDevice (M_devLib| 25) /*Specified address is ambiguous (more than one device responds)*/
/** @brief Device self test failed */
/** \brief Device self test failed */
#define S_dev_badSelfTest (M_devLib| 26) /*Device self test failed*/
/** @brief Device failed during initialization */
/** \brief Device failed during initialization */
#define S_dev_badInit (M_devLib| 27) /*Device failed during initialization*/
/** @brief Input exceeds Hardware Limit */
/** \brief Input exceeds Hardware Limit */
#define S_dev_hdwLimit (M_devLib| 28) /*Input exceeds Hardware Limit*/
/** @brief Unable to locate address space for device */
/** \brief Unable to locate address space for device */
#define S_dev_deviceDoesNotFit (M_devLib| 29) /*Unable to locate address space for device*/
/** @brief Device timed out */
/** \brief Device timed out */
#define S_dev_deviceTMO (M_devLib| 30) /*Device timed out*/
/** @brief Bad function pointer */
/** \brief Bad function pointer */
#define S_dev_badFunction (M_devLib| 31) /*Bad function pointer*/
/** @brief Bad interrupt vector */
/** \brief Bad interrupt vector */
#define S_dev_badVector (M_devLib| 32) /*Bad interrupt vector*/
/** @brief Bad function argument */
/** \brief Bad function argument */
#define S_dev_badArgument (M_devLib| 33) /*Bad function argument*/
/** @brief Invalid ISA address */
/** \brief Invalid ISA address */
#define S_dev_badISA (M_devLib| 34) /*Invalid ISA address*/
/** @brief Invalid VME CR/CSR address */
/** \brief Invalid VME CR/CSR address */
#define S_dev_badCRCSR (M_devLib| 35) /*Invalid VME CR/CSR address*/
/** @brief Synonym for S_dev_intEnFail */
/** \brief Synonym for S_dev_intEnFail */
#define S_dev_vxWorksIntEnFail S_dev_intEnFail
/** @} */
modules/libcom/src/osi/devLibVME.h
+110 -110
View File
@@ -8,9 +8,9 @@
\*************************************************************************/
/**
* @file devLibVME.h
* @author Marty Kraimer, Jeff Hill
* @brief API for accessing hardware devices, mosty over VMEbus.
* \file devLibVME.h
* \author Marty Kraimer, Jeff Hill
* \brief API for accessing hardware devices, mosty over VMEbus.
*
* API for accessing hardware devices. The original APIs here were for
* written for use with VMEbus but additional routines were added for
@@ -36,17 +36,17 @@
extern "C" {
#endif
/** @brief The available bus address types */
/** \brief The available bus address types */
typedef enum {
atVMEA16, /**< @brief VME short I/O. */
atVMEA24, /**< @brief VME standard I/O. */
atVMEA32, /**< @brief VME extended I/O. */
atISA, /**< @brief Memory mapped ISA access. */
atVMECSR, /**< @brief VME-64 CR/CSR address space. */
atLast /**< @brief Invalid, must be the last entry. */
atVMEA16, /**< \brief VME short I/O. */
atVMEA24, /**< \brief VME standard I/O. */
atVMEA32, /**< \brief VME extended I/O. */
atISA, /**< \brief Memory mapped ISA access. */
atVMECSR, /**< \brief VME-64 CR/CSR address space. */
atLast /**< \brief Invalid, must be the last entry. */
} epicsAddressType;
/** @brief A string representation of each of the bus address types */
/** \brief A string representation of each of the bus address types */
epicsShareExtern const char *epicsAddressTypeName[];
#ifdef __cplusplus
@@ -64,54 +64,54 @@ epicsShareExtern const char *epicsAddressTypeName[];
extern "C" {
#endif
/** @brief Print a map of registered bus addresses.
/** \brief Print a map of registered bus addresses.
*
* Display a table of registsred bus address ranges, including the owner of
* each registered address.
* @return 0, or an error status value
* \return 0, or an error status value
*/
epicsShareFunc long devAddressMap(void);
/** @brief Translate a bus address to a pointer the CPU can use.
/** \brief Translate a bus address to a pointer the CPU can use.
*
* Given a bus address, returns a pointer to that location in the CPU's
* memory map, or an error if direct access isn't currently possible.
* @param addrType The bus address type.
* @param busAddr Bus address to be translated.
* @param *ppLocalAddr Where to put the CPU pointer.
* @return 0, or an error status value.
* \param addrType The bus address type.
* \param busAddr Bus address to be translated.
* \param *ppLocalAddr Where to put the CPU pointer.
* \return 0, or an error status value.
*/
epicsShareFunc long devBusToLocalAddr (
epicsAddressType addrType,
size_t busAddr,
volatile void **ppLocalAddr);
/** @brief Probe the bus for reading from a specific address.
/** \brief Probe the bus for reading from a specific address.
*
* Performs a bus-error-safe @c wordSize atomic read from a specific
* Performs a bus-error-safe \c wordSize atomic read from a specific
* address and returns an error if this caused a bus error.
* @param wordSize The word size to read: 1, 2, 4 or 8 bytes.
* @param ptr Pointer to the location in the CPU's memory map to read.
* @param pValueRead Where to put the value read.
* @return 0, or an error status value if the location could not be
* \param wordSize The word size to read: 1, 2, 4 or 8 bytes.
* \param ptr Pointer to the location in the CPU's memory map to read.
* \param pValueRead Where to put the value read.
* \return 0, or an error status value if the location could not be
* accessed or the read caused a bus error.
*/
epicsShareFunc long devReadProbe (
unsigned wordSize, volatile const void *ptr, void *pValueRead);
/** @brief Read-probe a range of bus addresses, looking for empty space.
/** \brief Read-probe a range of bus addresses, looking for empty space.
*
* Verifies that no device responds at any naturally aligned addresses
* within the given range. Tries to read every aligned address at every
* word size between char and long over the entire range, returning
* success only if none of the reads succeed.
* @warning This routine may be slow and have a very bad effect on a busy
* \warning This routine may be slow and have a very bad effect on a busy
* VMEbus. Every read probe of an unused address will hold onto the VMEbus
* for the global bus timeout period.
* @param addrType The bus address type.
* @param base First address base to probe.
* @param size Range of bus addresses to test, in bytes.
* @return 0 if no devices respond, or an error status value.
* \param addrType The bus address type.
* \param base First address base to probe.
* \param size Range of bus addresses to test, in bytes.
* \return 0 if no devices respond, or an error status value.
*/
epicsShareFunc long devNoResponseProbe(
epicsAddressType addrType,
@@ -119,32 +119,32 @@ epicsShareFunc long devNoResponseProbe(
size_t size
);
/** @brief Probe the bus for writing to a specific address.
/** \brief Probe the bus for writing to a specific address.
*
* Performs a bus-error-safe @c wordSize atomic write to a specific
* Performs a bus-error-safe \c wordSize atomic write to a specific
* address and returns an error if this caused a bus error.
* @param wordSize The word size to write: 1, 2, 4 or 8 bytes.
* @param ptr Pointer to the location in the CPU's memory map to write to.
* @param pValueWritten The value to write.
* @return 0, or an error status value if the location could not be
* \param wordSize The word size to write: 1, 2, 4 or 8 bytes.
* \param ptr Pointer to the location in the CPU's memory map to write to.
* \param pValueWritten The value to write.
* \return 0, or an error status value if the location could not be
* accessed or the write caused a bus error.
*/
epicsShareFunc long devWriteProbe (
unsigned wordSize, volatile void *ptr, const void *pValueWritten);
/** @brief Register a bus address range with a name.
/** \brief Register a bus address range with a name.
*
* The devLib code keeps a list of all bus address ranges registered with
* this routine and returns an error if a later call attempts to register
* any addresses that overlap with a range already registered. The call to
* registering a range also converts the given base address into a pointer
* in the CPU address space for the driver to use (see devBusToLocalAddr()).
* @param pOwnerName Name of a driver that will own this range.
* @param addrType The bus address type.
* @param logicalBaseAddress The bus start address.
* @param size Number of bytes to reserve.
* @param pPhysicalAddress Where to put the converted CPU pointer.
* @return 0, or an error status.
* \param pOwnerName Name of a driver that will own this range.
* \param addrType The bus address type.
* \param logicalBaseAddress The bus start address.
* \param size Number of bytes to reserve.
* \param pPhysicalAddress Where to put the converted CPU pointer.
* \return 0, or an error status.
*/
epicsShareFunc long devRegisterAddress(
const char *pOwnerName,
@@ -153,21 +153,21 @@ epicsShareFunc long devRegisterAddress(
size_t size,
volatile void **pPhysicalAddress);
/** @brief Release a bus address range previously registered.
/** \brief Release a bus address range previously registered.
*
* Release an address range that was previously registered by a call to
* devRegisterAddress() or devAllocAddress().
* @param addrType The bus address type.
* @param logicalBaseAddress The bus start address.
* @param pOwnerName The name of the driver that owns this range.
* @return 0, or an error status.
* \param addrType The bus address type.
* \param logicalBaseAddress The bus start address.
* \param pOwnerName The name of the driver that owns this range.
* \return 0, or an error status.
*/
epicsShareFunc long devUnregisterAddress(
epicsAddressType addrType,
size_t logicalBaseAddress,
const char *pOwnerName);
/** @brief Allocate and register an unoccupied address block.
/** \brief Allocate and register an unoccupied address block.
*
* Asks devLib to allocate an address block of a particular address type.
* This is useful for devices that appear in more than one address space
@@ -175,15 +175,15 @@ epicsShareFunc long devUnregisterAddress(
* in another window. As with devRegisterAddress() this call also converts
* the new base address into a pointer in the CPU address space for the
* driver to use (see devBusToLocalAddr()).
* @note This routine calls devNoResponseProbe() to find an unoccupied
* \note This routine calls devNoResponseProbe() to find an unoccupied
* block in the bus address space, so using it may have a bad effect on a
* busy VMEbus at allocation time; see the warning above.
* @param pOwnerName Name of a driver that will own this range.
* @param addrType The bus address type.
* @param size Number of bytes to be allocated.
* @param alignment How many low bits in the address must all be zero.
* @param pLocalAddress Where to put the CPU pointer.
* @return 0, or an error status value.
* \param pOwnerName Name of a driver that will own this range.
* \param addrType The bus address type.
* \param size Number of bytes to be allocated.
* \param alignment How many low bits in the address must all be zero.
* \param pLocalAddress Where to put the CPU pointer.
* \return 0, or an error status value.
*/
epicsShareFunc long devAllocAddress(
const char *pOwnerName,
@@ -192,11 +192,11 @@ epicsShareFunc long devAllocAddress(
unsigned alignment, /*n ls bits zero in addr*/
volatile void **pLocalAddress);
/** @name VME Interrupt Management
/** \name VME Interrupt Management
* Routines to manage VME interrupts.
* @{
*/
/** @brief Connect an ISR up to a VME interrupt vector.
/** \brief Connect an ISR up to a VME interrupt vector.
*
* Interrupt Service Routines (ISRs) are normally written in C, and get
* passed a context parameter given with them to this connection routine.
@@ -206,105 +206,105 @@ epicsShareFunc long devAllocAddress(
* epicsRingPointer.h and epicsTime.h for some APIs known to be suitable.
* It is safest just to trigger a high-priority task to handle any
* complex work that must happen as a result of the interrupt.
* @param vectorNumber VME interrupt vector number.
* @param pFunction The ISR to be called.
* @param parameter Context parameter for the ISR.
* @return 0, or an error status value.
* \param vectorNumber VME interrupt vector number.
* \param pFunction The ISR to be called.
* \param parameter Context parameter for the ISR.
* \return 0, or an error status value.
*/
epicsShareFunc long devConnectInterruptVME(
unsigned vectorNumber,
void (*pFunction)(void *),
void *parameter);
/** @brief Disconnect an ISR from its VME interrupt vector.
/** \brief Disconnect an ISR from its VME interrupt vector.
*
* Device drivers may disconnect an ISR they connected earlier using this
* routine. In addition to taking the @c vectorNumber the ISR itself is
* routine. In addition to taking the \c vectorNumber the ISR itself is
* required and used as a check to prevent a driver from inadvertently
* removing an interrupt handler that it didn't install.
*
* On a PowerPC target running VxWorks, this routine will always return
* with an error status.
* @param vectorNumber VME interrupt vector number.
* @param pFunction The ISR to be disconnected.
* @return 0, or an error status value.
* \param vectorNumber VME interrupt vector number.
* \param pFunction The ISR to be disconnected.
* \return 0, or an error status value.
*/
epicsShareFunc long devDisconnectInterruptVME(
unsigned vectorNumber,
void (*pFunction)(void *));
/** @brief Determine if a VME interrupt vector is in use.
/** \brief Determine if a VME interrupt vector is in use.
*
* On a PowerPC target running VxWorks this routine will always return
* false, indicating that a vector is unused.
* @param vectorNumber Interrupt vector number.
* @return True if vector has an ISR attached, otherwise false.
* \param vectorNumber Interrupt vector number.
* \return True if vector has an ISR attached, otherwise false.
*/
epicsShareFunc int devInterruptInUseVME (unsigned vectorNumber);
/** @brief Enable a VME interrupt level onto the CPU.
/** \brief Enable a VME interrupt level onto the CPU.
*
* The VMEbus allows multiple CPU boards to be installed in the same
* backplane. When this is done, the differente VME interrupt levels
* must be assigned to the CPUs since they cannot be shared. This
* routine tells the VME interface that it should connect interrupts
* from the indicated interrupt level to a CPU interrupt line.
* @param level VMEbus interrupt level to enable, 1-7.
* @return 0, or an error status value.
* \param level VMEbus interrupt level to enable, 1-7.
* \return 0, or an error status value.
*/
epicsShareFunc long devEnableInterruptLevelVME (unsigned level);
/** @brief Disable a VME interrupt level.
/** \brief Disable a VME interrupt level.
*
* This routine is the reverse of devEnableInterruptLevelVME().
* @note This routine should not normally be used, even by a
* \note This routine should not normally be used, even by a
* driver that enabled the interrupt level. Disabling a VME
* interrupt level should only be done by software that knows
* for certain that no other interrupting device is also using
* that VME interrupt level.
* @param level VMEbus interrupt level to disable, 1-7.
* @return 0, or an error status value.
* \param level VMEbus interrupt level to disable, 1-7.
* \return 0, or an error status value.
*/
epicsShareFunc long devDisableInterruptLevelVME (unsigned level);
/** @} */
/** @name Memory for VME DMA Operations
/** \name Memory for VME DMA Operations
* These routines manage memory that can be directly accessed
* from the VMEbus in the A24 address space by another bus master
* such as a DMA controller.
* @{
*/
/** @brief malloc() for VME drivers that support DMA.
/** \brief malloc() for VME drivers that support DMA.
*
* Allocate memory of a given size from a region that can be
* accessed from the VMEbus in the A24 address space.
* @param size How many bytes to allocate
* @return A pointer to the memory allocated, or NULL.
* \param size How many bytes to allocate
* \return A pointer to the memory allocated, or NULL.
*/
epicsShareFunc void *devLibA24Malloc(size_t size);
/** @brief calloc() for VME drivers that support DMA.
/** \brief calloc() for VME drivers that support DMA.
*
* Allocate and zero-fill a block of memory of a given size from
* a region that can be accessed from the VMEbus in the A24
* address space.
* @param size How many bytes to allocate and zero.
* @return A pointer to the memory allocated, or NULL.
* \param size How many bytes to allocate and zero.
* \return A pointer to the memory allocated, or NULL.
*/
epicsShareFunc void *devLibA24Calloc(size_t size);
/** @brief free() for VME drivers that support DMA.
/** \brief free() for VME drivers that support DMA.
*
* Free a block of memory that was allocated using either
* devLibA24Malloc() or devLibA24Calloc().
* @param pBlock Block to be released.
* \param pBlock Block to be released.
*/
epicsShareFunc void devLibA24Free(void *pBlock);
/** @} */
/** @name ISA Interrupt Management
/** \name ISA Interrupt Management
* Routines to manage ISAbus interrupts.
* @note These routines may not have been used for a very long time;
* \note These routines may not have been used for a very long time;
* some appear to have never been implemented at all. They may vanish
* with no notice from future versions of EPICS Base. Nobody is using
* the PC's ISA-bus any more are they?
@@ -313,11 +313,11 @@ epicsShareFunc void devLibA24Free(void *pBlock);
/**
* Connect ISR to a ISA interrupt.
* @warning Not implemented!
* @param interruptLevel Bus interrupt level to connect to.
* @param pFunction C function pointer to connect to.
* @param parameter Parameter to the called function.
* @return Returns success or error.
* \warning Not implemented!
* \param interruptLevel Bus interrupt level to connect to.
* \param pFunction C function pointer to connect to.
* \param parameter Parameter to the called function.
* \return Returns success or error.
*/
epicsShareFunc long devConnectInterruptISA(
unsigned interruptLevel,
@@ -326,10 +326,10 @@ epicsShareFunc long devConnectInterruptISA(
/**
* Disconnect ISR from a ISA interrupt level.
* @warning Not implemented!
* @param interruptLevel Interrupt level.
* @param pFunction C function pointer that was connected.
* @return returns success or error.
* \warning Not implemented!
* \param interruptLevel Interrupt level.
* \param pFunction C function pointer that was connected.
* \return returns success or error.
*/
epicsShareFunc long devDisconnectInterruptISA(
unsigned interruptLevel,
@@ -337,23 +337,23 @@ epicsShareFunc long devDisconnectInterruptISA(
/**
* Determine if an ISA interrupt level is in use
* @warning Not implemented!
* @param interruptLevel Interrupt level.
* @return Returns True/False.
* \warning Not implemented!
* \param interruptLevel Interrupt level.
* \return Returns True/False.
*/
epicsShareFunc int devInterruptLevelInUseISA (unsigned interruptLevel);
/**
* Enable ISA interrupt level
* @param level Interrupt level.
* @return Returns True/False.
* \param level Interrupt level.
* \return Returns True/False.
*/
epicsShareFunc long devEnableInterruptLevelISA (unsigned level);
/**
* Disable ISA interrupt level
* @param level Interrupt level.
* @return Returns True/False.
* \param level Interrupt level.
* \return Returns True/False.
*/
epicsShareFunc long devDisableInterruptLevelISA (unsigned level);
/** @} */
@@ -361,13 +361,13 @@ epicsShareFunc long devDisableInterruptLevelISA (unsigned level);
#ifndef NO_DEVLIB_OLD_INTERFACE
/**
* @name Deprecated Interfaces
* \name Deprecated Interfaces
* @{
*/
typedef enum {intVME, intVXI, intISA} epicsInterruptType;
/**
* @note This routine has been deprecated. It exists
* \note This routine has been deprecated. It exists
* for backwards compatibility purposes only.
* Please use one of devConnectInterruptVME(), devConnectInterruptPCI(),
* devConnectInterruptISA() instead. devConnectInterrupt() will be removed
@@ -380,7 +380,7 @@ epicsShareFunc long devConnectInterrupt(
void *parameter);
/**
* @note This routine has been deprecated. It exists
* \note This routine has been deprecated. It exists
* for backwards compatibility purposes only.
* Please use one of devDisconnectInterruptVME(), devDisconnectInterruptPCI(),
* devDisconnectInterruptISA() instead. devDisconnectInterrupt() will
@@ -392,7 +392,7 @@ epicsShareFunc long devDisconnectInterrupt(
void (*pFunction)(void *));
/**
* @note This routine has been deprecated. It exists
* \note This routine has been deprecated. It exists
* for backwards compatibility purposes only.
* Please use one of devEnableInterruptLevelVME(), devEnableInterruptLevelPCI(),
* devEnableInterruptLevelISA() instead. devEnableInterruptLevel() will
@@ -402,7 +402,7 @@ epicsShareFunc long devEnableInterruptLevel(
epicsInterruptType intType, unsigned level);
/**
* @note This routine has been deprecated. It exists
* \note This routine has been deprecated. It exists
* for backwards compatibility purposes only.
* Please use one of devDisableInterruptLevelVME(), devDisableInterruptLevelISA(),
* devDisableInterruptLevelPCI() instead. devDisableInterruptLevel() will
@@ -412,7 +412,7 @@ epicsShareFunc long devDisableInterruptLevel (
epicsInterruptType intType, unsigned level);
/**
* @note This routine has been deprecated. It exists
* \note This routine has been deprecated. It exists
* for backwards compatibility purposes only.
* Please use devNoResponseProbe() instead. locationProbe() will be removed
* in a future release.
modules/libcom/src/osi/devLibVMEImpl.h
+18 -18
View File
@@ -10,9 +10,9 @@
\*************************************************************************/
/**
* @file devLibVMEImpl.h
* @author Marty Kraimer, Jeff Hill
* @brief An interface from devLibVME.c to its OS-specific implementations.
* \file devLibVMEImpl.h
* \author Marty Kraimer, Jeff Hill
* \brief An interface from devLibVME.c to its OS-specific implementations.
*/
#ifndef INCdevLibImplh
@@ -27,7 +27,7 @@ extern "C" {
#endif
/**
* @brief A table of function pointers for devLibVME implementations
* \brief A table of function pointers for devLibVME implementations
*
* The global virtual OS table \ref pdevLibVME controls
* the behaviour of the functions defined in devLib.h.
@@ -35,48 +35,48 @@ extern "C" {
* to perform system specific tasks.
*/
typedef struct devLibVME {
/** @brief Map a bus address to the CPU's address space. */
/** \brief Map a bus address to the CPU's address space. */
long (*pDevMapAddr) (epicsAddressType addrType, unsigned options,
size_t logicalAddress, size_t size, volatile void **ppPhysicalAddress);
/** @brief Read a word, detect and protect against bus errors. */
/** \brief Read a word, detect and protect against bus errors. */
long (*pDevReadProbe) (unsigned wordSize, volatile const void *ptr,
void *pValueRead);
/** @brief Write a word, detect and protect against bus errors. */
/** \brief Write a word, detect and protect against bus errors. */
long (*pDevWriteProbe) (unsigned wordSize, volatile void *ptr,
const void *pValueWritten);
/** @brief Connect ISR to a VME interrupt vector. */
/** \brief Connect ISR to a VME interrupt vector. */
long (*pDevConnectInterruptVME) (unsigned vectorNumber,
void (*pFunction)(void *), void *parameter);
/** @brief Disconnect ISR from a VME interrupt vector. */
/** \brief Disconnect ISR from a VME interrupt vector. */
long (*pDevDisconnectInterruptVME) (unsigned vectorNumber,
void (*pFunction)(void *));
/** @brief Enable VME interrupt level to CPU. */
/** \brief Enable VME interrupt level to CPU. */
long (*pDevEnableInterruptLevelVME) (unsigned level);
/** @brief Disable VME interrupt level to CPU. */
/** \brief Disable VME interrupt level to CPU. */
long (*pDevDisableInterruptLevelVME) (unsigned level);
/** @brief Malloc a block accessible from the VME A24 address space. */
/** \brief Malloc a block accessible from the VME A24 address space. */
void *(*pDevA24Malloc)(size_t nbytes);
/** @brief Free a block allocated for the VME A24 address space. */
/** \brief Free a block allocated for the VME A24 address space. */
void (*pDevA24Free)(void *pBlock);
/** @brief Init devLib */
/** \brief Init devLib */
long (*pDevInit)(void);
/** @brief Check if interrupt vector has an ISR connected. */
/** \brief Check if interrupt vector has an ISR connected. */
int (*pDevInterruptInUseVME)(unsigned vectorNumber);
}devLibVME;
/** @brief Pointer to the entry table used by devLibVME routines. */
/** \brief Pointer to the entry table used by devLibVME routines. */
epicsShareExtern devLibVME *pdevLibVME;
#ifndef NO_DEVLIB_COMPAT
/** @brief An alias for pdevLibVME */
/** \brief An alias for pdevLibVME */
# define pdevLibVirtualOS pdevLibVME
/** @brief A type definition for devLibVME */
/** \brief A type definition for devLibVME */
typedef devLibVME devLibVirtualOS;
#endif
modules/libcom/src/osi/epicsAssert.h
+13 -13
View File
@@ -7,20 +7,20 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/**@file epicsAssert.h
* @author Jeffery O. Hill
/**\file epicsAssert.h
* \author Jeffery O. Hill
*
* @brief An EPICS-specific replacement for ANSI C's assert.
* \brief An EPICS-specific replacement for ANSI C's assert.
*
* To use this version just include:
@code
\code
#define epicsAssertAuthor "Code Author my@email.address"
#include <epicsAssert.h>
@endcode
\endcode
* instead of
@code
\code
#include <assert.h>
@endcode
\endcode
*
* If an assert() fails, it calls errlog indicating the program's author, file name, and
* line number. Under each OS there are specialized instructions assisting the user to
@@ -34,7 +34,7 @@
* This header also provides a compile-time assertion macro STATIC_ASSERT()
* which can be used to check a constant-expression at compile-time. The C or
* C++ compiler will flag an error if the expresstion evaluates to 0. The
* STATIC_ASSERT() macro can only be used where a @c typedef is syntactically
* STATIC_ASSERT() macro can only be used where a \c typedef is syntactically
* legal.
**/
@@ -50,7 +50,7 @@ extern "C" {
#ifndef epicsAssertAuthor
/**@brief Optional string giving the author's name */
/**\brief Optional string giving the author's name */
# define epicsAssertAuthor 0
#endif
@@ -64,8 +64,8 @@ extern "C" {
epicsShareFunc void epicsAssert (const char *pFile, const unsigned line,
const char *pExp, const char *pAuthorName);
/**@brief Declare that a condition should be true.
* @param exp Expression that should evaluate to True.
/**\brief Declare that a condition should be true.
* \param exp Expression that should evaluate to True.
*/
# define assert(exp) ((exp) ? (void)0 : \
epicsAssert(__FILE__, __LINE__, #exp, epicsAssertAuthor))
@@ -80,8 +80,8 @@ epicsShareFunc void epicsAssert (const char *pFile, const unsigned line,
#define STATIC_JOIN(x, y) STATIC_JOIN2(x, y)
#define STATIC_JOIN2(x, y) x ## y
/**@brief Declare a condition that should be true at compile-time.
* @param expr A C/C++ const-expression that should evaluate to True.
/**\brief Declare a condition that should be true at compile-time.
* \param expr A C/C++ const-expression that should evaluate to True.
*/
#define STATIC_ASSERT(expr) \
typedef int STATIC_JOIN(static_assert_failed_at_line_, __LINE__) \
modules/libcom/src/osi/epicsEvent.h
+66 -66
View File
@@ -7,9 +7,9 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/**@file epicsEvent.h
/**\file epicsEvent.h
*
* @brief APIs for the epicsEvent binary semaphore.
* \brief APIs for the epicsEvent binary semaphore.
*
* Defines the C++ and C API's for a simple binary semaphore. If multiple threads are
* waiting on the same event, only one of them will be woken when the event is signalled.
@@ -19,22 +19,22 @@
* For example:
*
* When creating the consumer thread also create an epicsEvent.
@code
\code
epicsEvent *pevent = new epicsEvent;
@endcode
\endcode
* The consumer thread has code containing:
@code
\code
while(1) {
pevent->wait();
while( {more work} ) {
{process work}
}
}
@endcode
\endcode
* Producers create requests and issue the statement:
@code
\code
pevent->trigger();
@endcode
\endcode
**/
#ifndef epicsEventh
@@ -42,24 +42,24 @@
#include "shareLib.h"
/** @brief An identifier for an epicsEvent for use with the C API */
/** \brief An identifier for an epicsEvent for use with the C API */
typedef struct epicsEventOSD *epicsEventId;
/** @brief Return status from several C API routines. */
/** \brief Return status from several C API routines. */
typedef enum {
epicsEventOK = 0,
epicsEventWaitTimeout,
epicsEventError
} epicsEventStatus;
/** @brief Old name provided for backwards compatibility */
/** \brief Old name provided for backwards compatibility */
#define epicsEventWaitStatus epicsEventStatus
/** @brief Old name provided for backwards compatibility */
/** \brief Old name provided for backwards compatibility */
#define epicsEventWaitOK epicsEventOK
/** @brief Old name provided for backwards compatibility */
/** \brief Old name provided for backwards compatibility */
#define epicsEventWaitError epicsEventError
/** @brief Possible initial states of a new epicsEvent */
/** \brief Possible initial states of a new epicsEvent */
typedef enum {
epicsEventEmpty,
epicsEventFull
@@ -67,7 +67,7 @@ typedef enum {
#ifdef __cplusplus
/**@brief A binary semaphore.
/**\brief A binary semaphore.
*
* An epicsEvent is a binary semaphore that can be empty or full.
* When empty, a wait() issued before the next call to trigger() will block.
@@ -77,39 +77,39 @@ typedef enum {
**/
class epicsShareClass epicsEvent {
public:
/**@brief Constructor.
* @param initial State when created, empty (the default) or full.
/**\brief Constructor.
* \param initial State when created, empty (the default) or full.
**/
epicsEvent ( epicsEventInitialState initial = epicsEventEmpty );
/**@brief Destroy the epicsEvent and any resources it holds. No calls to
/**\brief Destroy the epicsEvent and any resources it holds. No calls to
* wait() can be active when this call is made.
**/
~epicsEvent ();
/**@brief Trigger the event i.e. ensures the next or current call to wait
/**\brief Trigger the event i.e. ensures the next or current call to wait
* completes. This method may be called from a vxWorks or RTEMS interrupt
* handler.
**/
void trigger ();
/**@brief Signal is a synonym for trigger().
/**\brief Signal is a synonym for trigger().
**/
void signal () { this->trigger(); }
/**@brief Wait for the event.
* @note Blocks until full.
/**\brief Wait for the event.
* \note Blocks until full.
**/
void wait ();
/**@brief Wait for the event or until the specified timeout.
* @param timeOut The timeout delay in seconds.
* @return True if the event was triggered, False if it timed out.
/**\brief Wait for the event or until the specified timeout.
* \param timeOut The timeout delay in seconds.
* \return True if the event was triggered, False if it timed out.
**/
bool wait ( double timeOut );
/**@brief Similar to wait() except that if the event is currenly empty the
/**\brief Similar to wait() except that if the event is currenly empty the
* call will return immediately.
* @return True if the event was full (triggered), False if empty.
* \return True if the event was full (triggered), False if empty.
**/
bool tryWait ();
/**@brief Display information about the semaphore.
* @note The information displayed is architecture dependant.
* @param level An unsigned int for the level of information to be displayed.
/**\brief Display information about the semaphore.
* \note The information displayed is architecture dependant.
* \param level An unsigned int for the level of information to be displayed.
**/
void show ( unsigned level ) const;
@@ -123,90 +123,90 @@ private:
extern "C" {
#endif /*__cplusplus */
/**@brief Create an epicsEvent for use from C code, or return NULL.
/**\brief Create an epicsEvent for use from C code, or return NULL.
*
* @param initialState Starting state, @c epicsEventEmpty or @c epicsEventFull.
* @return An identifier for the new event, or NULL if one not be created.
* \param initialState Starting state, \c epicsEventEmpty or \c epicsEventFull.
* \return An identifier for the new event, or NULL if one not be created.
**/
epicsShareFunc epicsEventId epicsEventCreate(
epicsEventInitialState initialState);
/**@brief Create an epicsEvent for use from C code.
/**\brief Create an epicsEvent for use from C code.
*
* This routine does not return if the object could not be created.
* @param initialState Starting state, @c epicsEventEmpty or @c epicsEventFull.
* @return An identifier for the new event.
* \param initialState Starting state, \c epicsEventEmpty or \c epicsEventFull.
* \return An identifier for the new event.
**/
epicsShareFunc epicsEventId epicsEventMustCreate (
epicsEventInitialState initialState);
/**@brief Destroy an epicsEvent and any resources it holds.
/**\brief Destroy an epicsEvent and any resources it holds.
*
* No calls to any epicsEventWait routines can be active when this call is made.
* @param id The event identifier.
* \param id The event identifier.
**/
epicsShareFunc void epicsEventDestroy(epicsEventId id);
/**@brief Trigger an event i.e. ensures the next or current call to wait
/**\brief Trigger an event i.e. ensures the next or current call to wait
* completes.
*
* @note This method may be called from a VxWorks or RTEMS interrupt
* \note This method may be called from a VxWorks or RTEMS interrupt
* handler.
* @param id The event identifier.
* @return Status indicator.
* \param id The event identifier.
* \return Status indicator.
**/
epicsShareFunc epicsEventStatus epicsEventTrigger(
epicsEventId id);
/**@brief Trigger an event.
/**\brief Trigger an event.
*
* This routine does not return if the identifier is invalid.
* @param id The event identifier.
* \param id The event identifier.
*/
epicsShareFunc void epicsEventMustTrigger(epicsEventId id);
/**@brief A synonym for epicsEventTrigger().
* @param ID The event identifier.
* @return Status indicator.
/**\brief A synonym for epicsEventTrigger().
* \param ID The event identifier.
* \return Status indicator.
**/
#define epicsEventSignal(ID) epicsEventMustTrigger(ID)
/**@brief Wait for an event.
* @note Blocks until full.
* @param id The event identifier.
* @return Status indicator.
/**\brief Wait for an event.
* \note Blocks until full.
* \param id The event identifier.
* \return Status indicator.
**/
epicsShareFunc epicsEventStatus epicsEventWait(
epicsEventId id);
/**@brief Wait for an event (see epicsEventWait()).
/**\brief Wait for an event (see epicsEventWait()).
*
* This routine does not return if the identifier is invalid.
* @param id The event identifier.
* \param id The event identifier.
*/
epicsShareFunc void epicsEventMustWait(epicsEventId id);
/**@brief Wait an the event or until the specified timeout period is over.
* @note Blocks until full or timeout.
* @param id The event identifier.
* @param timeOut The timeout delay in seconds.
* @return Status indicator.
/**\brief Wait an the event or until the specified timeout period is over.
* \note Blocks until full or timeout.
* \param id The event identifier.
* \param timeOut The timeout delay in seconds.
* \return Status indicator.
**/
epicsShareFunc epicsEventStatus epicsEventWaitWithTimeout(
epicsEventId id, double timeOut);
/**@brief Similar to wait() except that if the event is currenly empty the
* call will return immediately with status @c epicsEventWaitTimeout.
* @param id The event identifier.
* @return Status indicator, @c epicsEventWaitTimeout when the event is empty.
/**\brief Similar to wait() except that if the event is currenly empty the
* call will return immediately with status \c epicsEventWaitTimeout.
* \param id The event identifier.
* \return Status indicator, \c epicsEventWaitTimeout when the event is empty.
**/
epicsShareFunc epicsEventStatus epicsEventTryWait(
epicsEventId id);
/**@brief Display information about the semaphore.
* @note The information displayed is architecture dependant.
* @param id The event identifier.
* @param level An unsigned int for the level of information to be displayed.
/**\brief Display information about the semaphore.
* \note The information displayed is architecture dependant.
* \param id The event identifier.
* \param level An unsigned int for the level of information to be displayed.
**/
epicsShareFunc void epicsEventShow(
epicsEventId id, unsigned int level);
modules/libcom/src/osi/epicsGeneralTime.h
+32 -32
View File
@@ -7,9 +7,9 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/**@file epicsGeneralTime.h
/**\file epicsGeneralTime.h
*
* @brief The generalTime framework provides a mechanism for several time providers to be
* \brief The generalTime framework provides a mechanism for several time providers to be
* present within the system.
*
* There are two types of time provider, one type provides the current wall-clock
@@ -28,7 +28,7 @@
* cannot check the priority queue, so will only succeed if the last-used provider has
* registered a suitable routine.
*
* @note There are two interfaces to this framework, epicsGeneralTime.h for consumers
* \note There are two interfaces to this framework, epicsGeneralTime.h for consumers
* to obtain a time and query the framework, and generalTimeSup.h for providers
* that can supply timestamps.
**/
@@ -42,108 +42,108 @@
extern "C" {
#endif
/**@def NUM_TIME_EVENTS
* @brief The number of time events that are validated.
/**\def NUM_TIME_EVENTS
* \brief The number of time events that are validated.
*
* Time Events numbered 0 through (NUM_TIME_EVENTS-1) are validated by code in
* epicsGeneralTime.c that tests for advancing timestamps and enforces that
* restriction.
*
* @note Event numbers greater than or equal to NUM_TIME_EVENTS are now allowed
* \note Event numbers greater than or equal to NUM_TIME_EVENTS are now allowed
* if supported by a custom time provider which should provide its own advancing
* timestamp validation.
**/
#define NUM_TIME_EVENTS 256
/**@brief Initialise the framework.
/**\brief Initialise the framework.
*
* This routine is called automatically by any function that requires the
* framework. It does not need to be called explicitly.
**/
epicsShareFunc void generalTime_Init(void);
/**@brief Install a Time Event time provider that returns the current time for any
/**\brief Install a Time Event time provider that returns the current time for any
* Time event number.
*
* @note This is optional as it is site policy whether the last resort for a Time
* \note This is optional as it is site policy whether the last resort for a Time
* Event time in the absence of any working provider should be a failure, or the
* current time.
**/
epicsShareFunc int installLastResortEventProvider(void);
/**@brief Reset the internal counter of the number of times the time returned was
/**\brief Reset the internal counter of the number of times the time returned was
* earlier than when previously requested.
*
* Used by device support for binary out record
* with:
@code
\code
DTYP = "General Time"
OUT = "@RSTERRCNT"
@endcode
\endcode
**/
epicsShareFunc void generalTimeResetErrorCounts(void);
/**@brief Return the internal counter of the number of times the time returned was
/**\brief Return the internal counter of the number of times the time returned was
* earlier than when previously requested.
*
* Used by device support for longin record
* with:
@code
\code
DTYP = "General Time"
INP = "@GETERRCNT"
@endcode
\endcode
*
* @return Reset error counts
* \return Reset error counts
**/
epicsShareFunc int generalTimeGetErrorCounts(void);
/**@brief Return the nume of the provider that last returned a valid current time, or
/**\brief Return the nume of the provider that last returned a valid current time, or
* NULL if none.
*
* Used by stringin device support with:
@code
\code
DTYP = "General Time"
INP = "@BESTTCP"
@endcode
\endcode
*
* @return Provider name
* \return Provider name
**/
epicsShareFunc const char * generalTimeCurrentProviderName(void);
/**@brief Return the name of the provider that last returned a valid Time Event time, or
/**\brief Return the name of the provider that last returned a valid Time Event time, or
* NULL of none.
*
* Used by stringin device support with:
@code
\code
DTYP = "General Time"
INP = "@BESTTEP"
@endcode
\endcode
*
* @return Provider name
* \return Provider name
**/
epicsShareFunc const char * generalTimeEventProviderName(void);
/**@brief Return the name of the registered current time provider that has the highest
/**\brief Return the name of the registered current time provider that has the highest
* priority.
*
* Used by stringin device support with:
@code
\code
DTYP = "General Time"
INP = "@TOPTCP"
@endcode
\endcode
*
* @return Provider name
* \return Provider name
**/
epicsShareFunc const char * generalTimeHighestCurrentName(void);
/** @brief Old name provided for backwards compatibility */
/** \brief Old name provided for backwards compatibility */
#define generalTimeCurrentTpName generalTimeCurrentProviderName
/** @brief Old name provided for backwards compatibility */
/** \brief Old name provided for backwards compatibility */
#define generalTimeEventTpName generalTimeEventProviderName
/**@brief Provide information about the installed providers and their current best times.
/**\brief Provide information about the installed providers and their current best times.
*
* @param interest Desired interest level to report
* \param interest Desired interest level to report
**/
epicsShareFunc long generalTimeReport(int interest);
modules/libcom/src/osi/epicsMutex.h
+56 -56
View File
@@ -7,9 +7,9 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/**@file epicsMutex.h
/**\file epicsMutex.h
*
* @brief APIs for the epicsMutex mutual exclusion semaphore
* \brief APIs for the epicsMutex mutual exclusion semaphore
*
* Mutual exclusion semaphores are for situations requiring exclusive access to
* resources. An epicsMutex may be claimed recursively, i.e. taken more than
@@ -18,16 +18,16 @@
* working on an exclusive resource.
*
* The typical C++ use of a mutual exclusion semaphore is:
@code
\code
epicsMutex *plock = new epicsMutex;
...
...
plock->lock();
// process resources
plock->unlock();
@endcode
\endcode
*
* @note The implementation:
* \note The implementation:
* - MUST implement recursive locking
* - SHOULD implement priority inheritance and deletion safety if possible.
**/
@@ -38,7 +38,7 @@
#include "shareLib.h"
/**@brief An identifier for an epicsMutex for use with the C API */
/**\brief An identifier for an epicsMutex for use with the C API */
typedef struct epicsMutexParm *epicsMutexId;
/** Return status from some C API routines. */
@@ -53,11 +53,11 @@ typedef enum {
#include "compilerDependencies.h"
#include "epicsGuard.h"
/**@brief Create a C++ epicsMutex with current filename and line number
/**\brief Create a C++ epicsMutex with current filename and line number
*/
#define newEpicsMutex new epicsMutex(__FILE__,__LINE__)
/**@brief The C++ API for an epicsMutex.
/**\brief The C++ API for an epicsMutex.
*/
class epicsShareClass epicsMutex {
public:
@@ -67,59 +67,59 @@ public:
class invalidMutex; /* exception payload */
#if !defined(__GNUC__) || __GNUC__<4 || (__GNUC__==4 && __GNUC_MINOR__<8)
/**@brief Create a mutual exclusion semaphore.
/**\brief Create a mutual exclusion semaphore.
**/
epicsMutex ();
/**@brief Create a mutual exclusion semaphore with source location.
/**\brief Create a mutual exclusion semaphore with source location.
*
* @note The newEpicsMutex macro simplifies using this constructor.
* @param *pFileName Source file name.
* @param lineno Source line number
* \note The newEpicsMutex macro simplifies using this constructor.
* \param *pFileName Source file name.
* \param lineno Source line number
**/
epicsMutex ( const char *pFileName, int lineno );
#else
/**@brief Create a mutual exclusion semaphore.
* @param *pFileName Source file name.
* @param lineno Source line number
/**\brief Create a mutual exclusion semaphore.
* \param *pFileName Source file name.
* \param lineno Source line number
**/
epicsMutex ( const char *pFileName = __builtin_FILE(), int lineno = __builtin_LINE() );
#endif
/**@brief Delete the semaphore and its resources.
/**\brief Delete the semaphore and its resources.
**/
~epicsMutex ();
/**@brief Display information about the semaphore.
/**\brief Display information about the semaphore.
*
* @note Results are architecture dependant.
* \note Results are architecture dependant.
*
* @param level Desired information level to report
* \param level Desired information level to report
**/
void show ( unsigned level ) const;
/**@brief Claim the semaphore, waiting until it's free if currently owned
/**\brief Claim the semaphore, waiting until it's free if currently owned
* owned by a different thread.
*
* This call blocks until the calling thread can get exclusive access to
* the semaphore.
* @note After a successful lock(), additional recursive locks may be
* \note After a successful lock(), additional recursive locks may be
* issued by the same thread, but each must have an associated unlock().
**/
void lock ();
/**@brief Release the semaphore.
/**\brief Release the semaphore.
*
* @note If a thread issues recursive locks, it must call unlock() as many
* \note If a thread issues recursive locks, it must call unlock() as many
* times as it calls lock().
**/
void unlock ();
/**@brief Similar to lock() except that the call returns immediately if the
/**\brief Similar to lock() except that the call returns immediately if the
* semaphore is currently owned by another thread, giving the value false.
*
* @return True if the resource is now owned by the caller.
* @return False if some other thread already owns the resource.
* \return True if the resource is now owned by the caller.
* \return False if some other thread already owns the resource.
**/
bool tryLock ();
private:
@@ -128,7 +128,7 @@ private:
epicsMutex & operator = ( const epicsMutex & );
};
/**@brief A semaphore for locating deadlocks in C++ code. */
/**\brief A semaphore for locating deadlocks in C++ code. */
class epicsShareClass epicsDeadlockDetectMutex {
public:
typedef epicsGuard<epicsDeadlockDetectMutex> guard_t;
@@ -154,88 +154,88 @@ private:
extern "C" {
#endif /*__cplusplus*/
/**@brief Create an epicsMutex semaphore for use from C code.
/**\brief Create an epicsMutex semaphore for use from C code.
*
* This macro stores the source location of the creation call in the mutex.
* @return An identifier for the mutex, or NULL if one could not be created.
* \return An identifier for the mutex, or NULL if one could not be created.
**/
#define epicsMutexCreate() epicsMutexOsiCreate(__FILE__,__LINE__)
/**@brief Internal API, used by epicsMutexCreate(). */
/**\brief Internal API, used by epicsMutexCreate(). */
epicsShareFunc epicsMutexId epicsShareAPI epicsMutexOsiCreate(
const char *pFileName,int lineno);
/**@brief Create an epicsMutex semaphore for use from C code.
/**\brief Create an epicsMutex semaphore for use from C code.
*
* This macro stores the source location of the creation call in the mutex.
* The routine does not return if the object could not be created.
* @return An identifier for the mutex.
* \return An identifier for the mutex.
**/
#define epicsMutexMustCreate() epicsMutexOsiMustCreate(__FILE__,__LINE__)
/**@brief Internal API, used by epicsMutexMustCreate(). */
/**\brief Internal API, used by epicsMutexMustCreate(). */
epicsShareFunc epicsMutexId epicsShareAPI epicsMutexOsiMustCreate(
const char *pFileName,int lineno);
/**@brief Destroy an epicsMutex semaphore.
* @param id The mutex identifier.
/**\brief Destroy an epicsMutex semaphore.
* \param id The mutex identifier.
**/
epicsShareFunc void epicsShareAPI epicsMutexDestroy(epicsMutexId id);
/**@brief Release the semaphore.
* @param id The mutex identifier.
* @note If a thread issues recursive locks, it must call epicsMutexUnlock()
/**\brief Release the semaphore.
* \param id The mutex identifier.
* \note If a thread issues recursive locks, it must call epicsMutexUnlock()
* as many times as it calls epicsMutexLock() or equivalents.
**/
epicsShareFunc void epicsShareAPI epicsMutexUnlock(epicsMutexId id);
/**@brief Claim the semaphore, waiting until it's free if currently owned
/**\brief Claim the semaphore, waiting until it's free if currently owned
* owned by a different thread.
*
* This call blocks until the calling thread can get exclusive access to
* the semaphore.
* @note After a successful lock(), additional recursive locks may be
* \note After a successful lock(), additional recursive locks may be
* issued by the same thread, but each must have an associated unlock().
* @param id The mutex identifier.
* @return Status indicator.
* \param id The mutex identifier.
* \return Status indicator.
**/
epicsShareFunc epicsMutexLockStatus epicsShareAPI epicsMutexLock(
epicsMutexId id);
/**@brief Claim a semaphore (see epicsMutexLock()).
/**\brief Claim a semaphore (see epicsMutexLock()).
*
* This routine does not return if the identifier is invalid.
* @param ID The mutex identifier.
* \param ID The mutex identifier.
**/
#define epicsMutexMustLock(ID) { \
epicsMutexLockStatus status = epicsMutexLock(ID); \
assert(status == epicsMutexLockOK); \
}
/**@brief Similar to epicsMutexLock() except that the call returns immediately,
/**\brief Similar to epicsMutexLock() except that the call returns immediately,
* with the return status indicating if the semaphore is currently owned by
* this thread or another thread.
*
* @return \c epicsMutexLockOK if the resource is now owned by the caller.
* @return \c epicsMutexLockTimeout if some other thread owns the resource.
* \return \c epicsMutexLockOK if the resource is now owned by the caller.
* \return \c epicsMutexLockTimeout if some other thread owns the resource.
**/
epicsShareFunc epicsMutexLockStatus epicsShareAPI epicsMutexTryLock(
epicsMutexId id);
/**@brief Display information about the semaphore.
/**\brief Display information about the semaphore.
*
* @note Results are architecture dependant.
* \note Results are architecture dependant.
*
* @param id The mutex identifier.
* @param level Desired information level to report
* \param id The mutex identifier.
* \param level Desired information level to report
**/
epicsShareFunc void epicsShareAPI epicsMutexShow(
epicsMutexId id,unsigned int level);
/**@brief Display information about all epicsMutex semaphores.
/**\brief Display information about all epicsMutex semaphores.
*
* @note Results are architecture dependant.
* \note Results are architecture dependant.
*
* @param onlyLocked Non-zero to show only locked semaphores.
* @param level Desired information level to report
* \param onlyLocked Non-zero to show only locked semaphores.
* \param level Desired information level to report
**/
epicsShareFunc void epicsShareAPI epicsMutexShowAll(
int onlyLocked,unsigned int level);
modules/libcom/src/osi/epicsReadline.h
+12 -12
View File
@@ -8,9 +8,9 @@
\*************************************************************************/
/**
* @file epicsReadline.h
* @brief Command-line editing functions
* @author Eric Norum
* \file epicsReadline.h
* \brief Command-line editing functions
* \author Eric Norum
*
* Provides a generalized API for command line history and line-editing.
* The implementation of this API can call GNU Readline, libtecla, and on
@@ -26,21 +26,21 @@ extern "C" {
#include <shareLib.h>
#include <stdio.h>
/**
* @brief Create a command-line context
* @param in Filehandle to read from
* @returns Command-line context
* \brief Create a command-line context
* \param in Filehandle to read from
* \return Command-line context
*/
epicsShareFunc void * epicsShareAPI epicsReadlineBegin (FILE *in);
/**
* @brief Read a line of input
* @param prompt Prompt string
* @param context To read from
* @returns Line read
* \brief Read a line of input
* \param prompt Prompt string
* \param context To read from
* \return Line read
*/
epicsShareFunc char * epicsShareAPI epicsReadline (const char *prompt, void *context);
/**
* @brief Destroy a command-line context
* @param context Command-line context to destroy
* \brief Destroy a command-line context
* \param context Command-line context to destroy
*/
epicsShareFunc void epicsShareAPI epicsReadlineEnd (void *context);
modules/libcom/src/osi/epicsThread.h
+29 -25
View File
@@ -65,6 +65,9 @@ extern "C" {
typedef void (*EPICSTHREADFUNC)(void *parm);
/** @name Some Named Thread Priorities
* @{
*/
#define epicsThreadPriorityMax 99
#define epicsThreadPriorityMin 0
@@ -80,6 +83,7 @@ typedef void (*EPICSTHREADFUNC)(void *parm);
#define epicsThreadPriorityScanHigh 70
#define epicsThreadPriorityIocsh 91
#define epicsThreadPriorityBaseMax 91
/** @} */
/** Stack sizes for each stackSizeClass are implementation and CPU dependent. */
typedef enum {
@@ -114,13 +118,13 @@ typedef epicsThreadId epicsThreadOnceId;
* -# myInitFunc will have returned before any other epicsThreadOnce
* call using the same epicsThreadOnceId returns.
*
* @code
* \code
* static epicsThreadOnceId onceId = EPICS_THREAD_ONCE_INIT;
* static void myInitFunc(void *arg) { ... }
* static void some Function(void) {
* epicsThreadOnce(&onceId, &myInitFunc, NULL);
* }
* @endcode
* \endcode
*/
epicsShareFunc void epicsShareAPI epicsThreadOnce(
epicsThreadOnceId *id, EPICSTHREADFUNC, void *arg);
@@ -163,12 +167,12 @@ typedef struct epicsThreadOpts {
#define EPICS_THREAD_OPTS_INIT { \
epicsThreadPriorityLow, epicsThreadStackMedium, 0}
/** @brief Allocate and start a new OS thread.
* @param name A name describing this thread. Appears in various log and error message.
* @param funptr The thread main function.
* @param parm Passed to thread main function.
* @param opts Modifiers for the new thread, or NULL to use target specific defaults.
* @return NULL on error
/** \brief Allocate and start a new OS thread.
* \param name A name describing this thread. Appears in various log and error message.
* \param funptr The thread main function.
* \param parm Passed to thread main function.
* \param opts Modifiers for the new thread, or NULL to use target specific defaults.
* \return NULL on error
*/
epicsShareFunc epicsThreadId epicsThreadCreateOpt (
const char * name,
@@ -222,14 +226,14 @@ epicsShareFunc int epicsShareAPI epicsThreadIsEqual(
* for other reasons.
**/
epicsShareFunc int epicsShareAPI epicsThreadIsSuspended(epicsThreadId id);
/** @brief Block the calling thread for at least the specified time.
* @param seconds Time to wait in seconds. Values <=0 blocks for the shortest possible time.
/** \brief Block the calling thread for at least the specified time.
* \param seconds Time to wait in seconds. Values <=0 blocks for the shortest possible time.
*/
epicsShareFunc void epicsShareAPI epicsThreadSleep(double seconds);
/** @brief Query a value approximating the OS timer/scheduler resolution.
* @return A value in seconds >=0
/** \brief Query a value approximating the OS timer/scheduler resolution.
* \return A value in seconds >=0
*
* @warning On targets other than vxWorks and RTEMS, the quantum value often isn't
* \warning On targets other than vxWorks and RTEMS, the quantum value often isn't
* meaningful. Use of this function is discouraged in portable code.
*/
epicsShareFunc double epicsShareAPI epicsThreadSleepQuantum(void);
@@ -238,23 +242,23 @@ epicsShareFunc double epicsShareAPI epicsThreadSleepQuantum(void);
*/
epicsShareFunc epicsThreadId epicsShareAPI epicsThreadGetIdSelf(void);
/** Attempt to find the first instance of a thread by name.
* @return An epicsThreadId, or NULL if no such thread is currently running.
* \return An epicsThreadId, or NULL if no such thread is currently running.
* Note that a non-NULL ID may still be invalid if this call races
* with thread exit.
*
* @warning Safe use of this function requires external knowledge that this
* \warning Safe use of this function requires external knowledge that this
* thread will not return.
*/
epicsShareFunc epicsThreadId epicsShareAPI epicsThreadGetId(const char *name);
/** Return a value approximating the number of threads which this target
* can run in parallel. This value is advisory.
* @return >=1
* \return >=1
*/
epicsShareFunc int epicsThreadGetCPUs(void);
/** Return the name of the current thread.
*
* @return Never NULL. Storage lifetime tied to epicsThreadId.
* \return Never NULL. Storage lifetime tied to epicsThreadId.
*
* This is either a copy of the string passed to epicsThread*Create*(),
* or an arbitrary unique string for non-EPICS threads.
@@ -285,7 +289,7 @@ epicsShareFunc int epicsShareAPI epicsThreadIsOkToBlock(void);
epicsShareFunc void epicsShareAPI epicsThreadSetOkToBlock(int isOkToBlock);
/** Print to stdout information about all running EPICS threads.
* @param level 0 prints minimal output. Higher values print more details.
* \param level 0 prints minimal output. Higher values print more details.
*/
epicsShareFunc void epicsShareAPI epicsThreadShowAll(unsigned int level);
/** Print info about a single EPICS thread. */
@@ -356,18 +360,18 @@ public:
extern "C" void epicsThreadCallEntryPoint ( void * );
/** @brief An OS thread
/** \brief An OS thread
*
* A wrapper around the epicsThread* C API.
*
* @note Threads must be start() ed.
* \note Threads must be start() ed.
*/
class epicsShareClass epicsThread {
public:
/** Create a new thread with the provided information.
*
* cf. epicsThreadOpts
* @note Threads must be start() ed.
* \note Threads must be start() ed.
* @throws epicsThread::unableToCreateThread on error.
*/
epicsThread ( epicsThreadRunable &,const char *name, unsigned int stackSize,
@@ -378,11 +382,11 @@ public:
//! Wait for the thread epicsRunnable::run() to return.
void exitWait () throw ();
//! Wait for the thread epicsRunnable::run() to return.
//! @param delay Wait up to this many seconds.
//! @returns true if run() returned. false on timeout.
//! \param delay Wait up to this many seconds.
//! \return true if run() returned. false on timeout.
bool exitWait ( const double delay ) throw ();
//! @throws A special exitException which will be caught and ignored.
//! @note This exitException doesn't not derive from std::exception
//! \note This exitException doesn't not derive from std::exception
static void exit ();
//! cf. epicsThreadResume()
void resume () throw ();
@@ -396,7 +400,7 @@ public:
void setPriority ( unsigned int ) throw ();
bool priorityIsEqual ( const epicsThread & ) const throw ();
bool isSuspended () const throw ();
//! @return true if call through this thread's epicsRunnable::run()
//! \return true if call through this thread's epicsRunnable::run()
bool isCurrentThread () const throw ();
bool operator == ( const epicsThread & ) const throw ();
//! Say something interesting about this thread to stdout.
modules/libcom/src/osi/os/WIN32/osiFileName.h
+2 -2
View File
@@ -25,13 +25,13 @@ extern "C" {
#define OSI_PATH_SEPARATOR "\\"
/** Return the absolute path of the current executable.
@returns NULL or the path. Caller must free()
* \return NULL or the path. Caller must free()
*/
epicsShareFunc
char *epicsGetExecName(void);
/** Return the absolute path of the directory containing the current executable.
@returns NULL or the path. Caller must free()
* \return NULL or the path. Caller must free()
*/
epicsShareFunc
char *epicsGetExecDir(void);
modules/libcom/src/osi/os/cygwin32/osiFileName.h
+2 -2
View File
@@ -24,13 +24,13 @@ extern "C" {
#define OSI_PATH_SEPARATOR "\\"
/** Return the absolute path of the current executable.
@returns NULL or the path. Caller must free()
\return NULL or the path. Caller must free()
*/
epicsShareFunc
char *epicsGetExecName(void);
/** Return the absolute path of the directory containing the current executable.
@returns NULL or the path. Caller must free()
\return NULL or the path. Caller must free()
*/
epicsShareFunc
char *epicsGetExecDir(void);
modules/libcom/src/osi/os/default/epicsMMIODef.h
+41 -41
View File
@@ -5,12 +5,12 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/**
* @file epicsMMIODef.h
* @brief Memory Mapped I/O
* \file epicsMMIODef.h
* \brief Memory Mapped I/O
*
* Definitions related to Memory Mapped I/O
*
* @author Michael Davidsaver <mdavidsaver@bnl.gov>
* \author Michael Davidsaver <mdavidsaver@bnl.gov>
* @ingroup mmio
*/
@@ -32,7 +32,7 @@
*@{
*/
/** @brief Read a single byte.
/** \brief Read a single byte.
*/
static EPICS_ALWAYS_INLINE
epicsUInt8
@@ -41,7 +41,7 @@ ioread8(volatile void* addr)
return *(volatile epicsUInt8*)(addr);
}
/** @brief Write a single byte.
/** \brief Write a single byte.
*/
static EPICS_ALWAYS_INLINE
void
@@ -50,7 +50,7 @@ iowrite8(volatile void* addr, epicsUInt8 val)
*(volatile epicsUInt8*)(addr) = val;
}
/** @brief Read two bytes in host order.
/** \brief Read two bytes in host order.
* Not byte swapping
*/
static EPICS_ALWAYS_INLINE
@@ -60,7 +60,7 @@ nat_ioread16(volatile void* addr)
return *(volatile epicsUInt16*)(addr);
}
/** @brief Write two byte in host order.
/** \brief Write two byte in host order.
* Not byte swapping
*/
static EPICS_ALWAYS_INLINE
@@ -70,7 +70,7 @@ nat_iowrite16(volatile void* addr, epicsUInt16 val)
*(volatile epicsUInt16*)(addr) = val;
}
/** @brief Read four bytes in host order.
/** \brief Read four bytes in host order.
* Not byte swapping
*/
static EPICS_ALWAYS_INLINE
@@ -80,7 +80,7 @@ nat_ioread32(volatile void* addr)
return *(volatile epicsUInt32*)(addr);
}
/** @brief Write four byte in host order.
/** \brief Write four byte in host order.
* Not byte swapping
*/
static EPICS_ALWAYS_INLINE
@@ -157,50 +157,50 @@ bswap32(epicsUInt32 value)
# error Unable to determine native byte order
#endif
/** @def bswap16
* @brief Unconditional two byte swap
/** \def bswap16
* \brief Unconditional two byte swap
*/
/** @def bswap32
* @brief Unconditional four byte swap
/** \def bswap32
* \brief Unconditional four byte swap
*/
/** @def be_ioread16
* @brief Read two byte in big endian order.
/** \def be_ioread16
* \brief Read two byte in big endian order.
*/
/** @def be_iowrite16
* @brief Write two byte in big endian order.
/** \def be_iowrite16
* \brief Write two byte in big endian order.
*/
/** @def be_ioread32
* @brief Read four byte in big endian order.
/** \def be_ioread32
* \brief Read four byte in big endian order.
*/
/** @def be_iowrite32
* @brief Write four byte in big endian order.
/** \def be_iowrite32
* \brief Write four byte in big endian order.
*/
/** @def le_ioread16
* @brief Read two byte in little endian order.
/** \def le_ioread16
* \brief Read two byte in little endian order.
*/
/** @def le_iowrite16
* @brief Write two byte in little endian order.
/** \def le_iowrite16
* \brief Write two byte in little endian order.
*/
/** @def le_ioread32
* @brief Read four byte in little endian order.
/** \def le_ioread32
* \brief Read four byte in little endian order.
*/
/** @def le_iowrite32
* @brief Write four byte in little endian order.
/** \def le_iowrite32
* \brief Write four byte in little endian order.
*/
/** @ingroup mmio
*@{
*/
/** @brief Explicit read memory barrier
/** \brief Explicit read memory barrier
* Prevents reordering of reads around it.
*/
#define rbarr() do{}while(0)
/** @brief Explicit write memory barrier
/** \brief Explicit write memory barrier
* Prevents reordering of writes around it.
*/
#define wbarr() do{}while(0)
/** @brief Explicit read/write memory barrier
/** \brief Explicit read/write memory barrier
* Prevents reordering of reads or writes around it.
*/
#define rwbarr() do{}while(0)
@@ -239,30 +239,30 @@ bswap32(epicsUInt32 value)
*
*@b PCI
*
@code
\code
be_iowrite16(base+off, 14);
var = be_ioread16(base+off);
@endcode
\endcode
*
*@b VME
*
@code
\code
nat_iowrite16(base+off, 14);
var = nat_ioread16(base+off);
@endcode
\endcode
*
*@subsection mmioexle Little endian device
*
*@b PCI
@code
\code
le_iowrite16(base+off, 14);
var = le_ioread16(base+off);
@endcode
\endcode
*@b VME
@code
\code
nat_iowrite16(base+off, bswap16(14));
var = bswap16(nat_iowrite16(base+off));
@endcode
\endcode
*This difference arises because VME bridges implement hardware byte
*swapping on little endian systems, while PCI bridges do not.
*Software accessing PCI devices must know if byte swapping is required.
@@ -274,7 +274,7 @@ bswap32(epicsUInt32 value)
*
*Software accessing VME must @b not do conditional swapping.
*
*@note All read and write operations have an implicit read or write barrier.
*\note All read and write operations have an implicit read or write barrier.
*/
/** @} */
modules/libcom/src/osi/osiPoolStatus.h
+7 -7
View File
@@ -7,9 +7,9 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/**@file osiPoolStatus.h
* @author Jeff Hill
* @brief Functions to check the state of the system memory pool.
/**\file osiPoolStatus.h
* \author Jeff Hill
* \brief Functions to check the state of the system memory pool.
*
**/
@@ -23,17 +23,17 @@
extern "C" {
#endif
/**@brief Checks if a memory block of a specific size can be safely allocated.
/**\brief Checks if a memory block of a specific size can be safely allocated.
*
* The meaning of "safely allocated" is target-specific, some additional free
* space is usually necessary to keep the system running reliably.
* On vxWorks this returns True if at least 100000 bytes is free.
*
* @note This routine is called quite frequently by the IOC so an efficent
* \note This routine is called quite frequently by the IOC so an efficent
* implementation is important.
*
* @param contiguousBlockSize Block size to check.
* @return True if the requested memory should be available.
* \param contiguousBlockSize Block size to check.
* \return True if the requested memory should be available.
*/
epicsShareFunc int epicsShareAPI osiSufficentSpaceInPool ( size_t contiguousBlockSize );
modules/libcom/src/ring/epicsRingBytes.h
+47 -47
View File
@@ -8,18 +8,18 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/**
* @file epicsRingBytes.h
* @author Marty Kraimer, Eric Norum, Ralph Lange
* @brief A circular buffer to store bytes
* \file epicsRingBytes.h
* \author Marty Kraimer, Eric Norum, Ralph Lange
* \brief A circular buffer to store bytes
*
* @details
* \details
* EpicsRingBytes provides a C API for creating and using ring buffers
* (first in first out circular buffers) that store bytes. The unlocked
* variant is designed so that one writer thread and one reader thread
* can access the ring simultaneously without requiring mutual exclusion.
* The locked variant uses an epicsSpinLock, and works with any numbers of
* writer and reader threads.
* @note If there is only one writer it is not necessary to lock for puts.
* \note If there is only one writer it is not necessary to lock for puts.
* If there is a single reader it is not necessary to lock for gets.
* epicsRingBytesLocked uses a spinlock.
*/
@@ -33,97 +33,97 @@ extern "C" {
#include "shareLib.h"
/** @brief An identifier for a ring buffer */
/** \brief An identifier for a ring buffer */
typedef void *epicsRingBytesId;
typedef void const *epicsRingBytesIdConst;
/**
* @brief Create a new ring buffer
* @param nbytes Size of ring buffer to create
* @return Ring buffer Id or NULL on failure
* \brief Create a new ring buffer
* \param nbytes Size of ring buffer to create
* \return Ring buffer Id or NULL on failure
*/
epicsShareFunc epicsRingBytesId epicsShareAPI epicsRingBytesCreate(int nbytes);
/**
* @brief Create a new ring buffer, secured by a spinlock
* @param nbytes Size of ring buffer to create
* @return Ring buffer Id or NULL on failure
* \brief Create a new ring buffer, secured by a spinlock
* \param nbytes Size of ring buffer to create
* \return Ring buffer Id or NULL on failure
*/
epicsShareFunc epicsRingBytesId epicsShareAPI epicsRingBytesLockedCreate(int nbytes);
/**
* @brief Delete the ring buffer and free any associated memory
* @param id RingbufferID returned by epicsRingBytesCreate()
* \brief Delete the ring buffer and free any associated memory
* \param id RingbufferID returned by epicsRingBytesCreate()
*/
epicsShareFunc void epicsShareAPI epicsRingBytesDelete(epicsRingBytesId id);
/**
* @brief Read data out of the ring buffer
* @param id RingbufferID returned by epicsRingBytesCreate()
* @param value Where to put the data fetched from the buffer
* @param nbytes Maximum number of bytes to get
* @return The number of bytes actually fetched
* \brief Read data out of the ring buffer
* \param id RingbufferID returned by epicsRingBytesCreate()
* \param value Where to put the data fetched from the buffer
* \param nbytes Maximum number of bytes to get
* \return The number of bytes actually fetched
*/
epicsShareFunc int epicsShareAPI epicsRingBytesGet(
epicsRingBytesId id, char *value,int nbytes);
/**
* @brief Write data into the ring buffer
* @param id RingbufferID returned by epicsRingBytesCreate()
* @param value Source of the data to be put into the buffer
* @param nbytes How many bytes to put
* @return The number of bytes actually stored, zero if not enough space
* \brief Write data into the ring buffer
* \param id RingbufferID returned by epicsRingBytesCreate()
* \param value Source of the data to be put into the buffer
* \param nbytes How many bytes to put
* \return The number of bytes actually stored, zero if not enough space
*/
epicsShareFunc int epicsShareAPI epicsRingBytesPut(
epicsRingBytesId id, char *value,int nbytes);
/**
* @brief Make the ring buffer empty
* @param id RingbufferID returned by epicsRingBytesCreate()
* @note Should only be used when both gets and puts are locked out.
* \brief Make the ring buffer empty
* \param id RingbufferID returned by epicsRingBytesCreate()
* \note Should only be used when both gets and puts are locked out.
*/
epicsShareFunc void epicsShareAPI epicsRingBytesFlush(epicsRingBytesId id);
/**
* @brief Return the number of free bytes in the ring buffer
* @param id RingbufferID returned by epicsRingBytesCreate()
* @return The number of free bytes in the ring buffer
* \brief Return the number of free bytes in the ring buffer
* \param id RingbufferID returned by epicsRingBytesCreate()
* \return The number of free bytes in the ring buffer
*/
epicsShareFunc int epicsShareAPI epicsRingBytesFreeBytes(epicsRingBytesId id);
/**
* @brief Return the number of bytes currently stored in the ring buffer
* @param id RingbufferID returned by epicsRingBytesCreate()
* @return The number of bytes currently stored in the ring buffer
* \brief Return the number of bytes currently stored in the ring buffer
* \param id RingbufferID returned by epicsRingBytesCreate()
* \return The number of bytes currently stored in the ring buffer
*/
epicsShareFunc int epicsShareAPI epicsRingBytesUsedBytes(epicsRingBytesId id);
/**
* @brief Return the size of the ring buffer
* @param id RingbufferID returned by epicsRingBytesCreate()
* @return Return the size of the ring buffer, i.e., nbytes specified in
* \brief Return the size of the ring buffer
* \param id RingbufferID returned by epicsRingBytesCreate()
* \return Return the size of the ring buffer, i.e., nbytes specified in
* the call to epicsRingBytesCreate().
*/
epicsShareFunc int epicsShareAPI epicsRingBytesSize(epicsRingBytesId id);
/**
* @brief Test if the ring buffer is currently empty.
* @param id RingbufferID returned by epicsRingBytesCreate()
* @return 1 if the buffer is empty, otherwise 0
* \brief Test if the ring buffer is currently empty.
* \param id RingbufferID returned by epicsRingBytesCreate()
* \return 1 if the buffer is empty, otherwise 0
*/
epicsShareFunc int epicsShareAPI epicsRingBytesIsEmpty(epicsRingBytesId id);
/**
* @brief Test if the ring buffer is currently full.
* @param id RingbufferID returned by epicsRingBytesCreate()
* @return 1 if the buffer is full, otherwise 0
* \brief Test if the ring buffer is currently full.
* \param id RingbufferID returned by epicsRingBytesCreate()
* \return 1 if the buffer is full, otherwise 0
*/
epicsShareFunc int epicsShareAPI epicsRingBytesIsFull(epicsRingBytesId id);
/**
* @brief See how full a ring buffer has been since it was last checked.
* \brief See how full a ring buffer has been since it was last checked.
*
* Returns the maximum amount of data the ring buffer has held in bytes
* since the water mark was last reset. A new ring buffer starts with a
* water mark of 0.
* @param id RingbufferID returned by epicsRingBytesCreate()
* @return Actual Highwater mark
* \param id RingbufferID returned by epicsRingBytesCreate()
* \return Actual Highwater mark
*/
epicsShareFunc int epicsShareAPI epicsRingBytesHighWaterMark(epicsRingBytesIdConst id);
/**
* @brief Reset the Highwater mark of the ring buffer.
* \brief Reset the Highwater mark of the ring buffer.
*
* The Highwater mark will be set to the current usage
* @param id RingbufferID returned by epicsRingBytesCreate()
* \param id RingbufferID returned by epicsRingBytesCreate()
*/
epicsShareFunc void epicsShareAPI epicsRingBytesResetHighWaterMark(epicsRingBytesId id);
modules/libcom/src/ring/epicsRingPointer.h
+68 -68
View File
@@ -8,18 +8,18 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/**
* @file epicsRingPointer.h
* @brief A circular buffer to store pointers
* @author Marty Kraimer, Ralph Lange
* \file epicsRingPointer.h
* \brief A circular buffer to store pointers
* \author Marty Kraimer, Ralph Lange
*
* @details
* \details
* epicsRingPointer.h provides both C and C++ APIs for creating and using ring
* buffers (first in first out circular buffers) that store pointers. The
* unlocked kind is designed so that one writer thread and one reader thread
* can access the ring simultaneously without requiring mutual exclusion. The
* locked variant uses an epicsSpinLock, and works with any numbers of writer
* and reader threads.
* @note If there is only one writer it is not necessary to lock pushes.
* \note If there is only one writer it is not necessary to lock pushes.
* If there is a single reader it is not necessary to lock pops.
* epicsRingPointerLocked uses a spinlock.
*/
@@ -33,63 +33,63 @@
#ifdef __cplusplus
/**
* @brief A C++ template class providing methods for creating and using a ring
* \brief A C++ template class providing methods for creating and using a ring
* buffer (a first in, first out circular buffer) that stores pointers to
* objects of the template type.
*/
template <class T>
class epicsRingPointer {
public: /* Functions */
/**@brief Constructor
* @param size Maximum number of elements (pointers) that can be stored
* @param locked If true, the spin lock secured variant is created
/**\brief Constructor
* \param size Maximum number of elements (pointers) that can be stored
* \param locked If true, the spin lock secured variant is created
*/
epicsRingPointer(int size, bool locked);
/**@brief Destructor
/**\brief Destructor
*/
~epicsRingPointer();
/**@brief Push a new entry on the ring
* @return True on success, False if the buffer was full
/**\brief Push a new entry on the ring
* \return True on success, False if the buffer was full
*/
bool push(T *p);
/**@brief Take an element off the ring
* @return The element, or NULL if the ring was empty
/**\brief Take an element off the ring
* \return The element, or NULL if the ring was empty
*/
T* pop();
/**@brief Remove all elements from the ring.
* @note If this operation is performed on a ring buffer of the
/**\brief Remove all elements from the ring.
* \note If this operation is performed on a ring buffer of the
* unsecured kind, all access to the ring should be locked.
*/
void flush();
/**@brief Get how much free space remains in the ring
* @return The number of additional elements the ring could hold.
/**\brief Get how much free space remains in the ring
* \return The number of additional elements the ring could hold.
*/
int getFree() const;
/**@brief Get how many elements are stored on the ring
* @return The number of elements currently stored.
/**\brief Get how many elements are stored on the ring
* \return The number of elements currently stored.
*/
int getUsed() const;
/**@brief Get the size of the ring
* @return The @c size specified when the ring was created.
/**\brief Get the size of the ring
* \return The \c size specified when the ring was created.
*/
int getSize() const;
/**@brief Test if the ring is currently empty
* @return True if the ring is empty, otherwise false.
/**\brief Test if the ring is currently empty
* \return True if the ring is empty, otherwise false.
*/
bool isEmpty() const;
/**@brief Test if the ring is currently full
* @return True if the ring is full, otherwise false.
/**\brief Test if the ring is currently full
* \return True if the ring is full, otherwise false.
*/
bool isFull() const;
/**@brief See how full the ring has got since it was last checked.
/**\brief See how full the ring has got since it was last checked.
*
* Returns the maximum number of elements the ring
* buffer has held since the water mark was last reset.
* A new ring buffer starts with a water mark of 0.
* @return Actual highwater mark
* \return Actual highwater mark
*/
int getHighWaterMark() const;
/**@brief Reset high water mark
/**\brief Reset high water mark
*
* High water mark will be set to the current usage
*/
@@ -114,92 +114,92 @@ private: /* Data */
extern "C" {
#endif /*__cplusplus */
/** @brief An identifier for the C API to a ring buffer storing pointers */
/** \brief An identifier for the C API to a ring buffer storing pointers */
typedef void *epicsRingPointerId;
typedef void const *epicsRingPointerIdConst;
/**
* @brief Create a new ring buffer
* @param size Size of ring buffer to create
* @return Ring buffer identifier or NULL on failure
* \brief Create a new ring buffer
* \param size Size of ring buffer to create
* \return Ring buffer identifier or NULL on failure
*/
epicsShareFunc epicsRingPointerId epicsShareAPI epicsRingPointerCreate(int size);
/**
* @brief Create a new ring buffer, secured by a spinlock
* @param size Size of ring buffer to create
* @return Ring buffer identifier or NULL on failure
* \brief Create a new ring buffer, secured by a spinlock
* \param size Size of ring buffer to create
* \return Ring buffer identifier or NULL on failure
*/
epicsShareFunc epicsRingPointerId epicsShareAPI epicsRingPointerLockedCreate(int size);
/**
* @brief Delete the ring buffer and free any associated memory
* @param id Ring buffer identifier
* \brief Delete the ring buffer and free any associated memory
* \param id Ring buffer identifier
*/
epicsShareFunc void epicsShareAPI epicsRingPointerDelete(epicsRingPointerId id);
/**
* @brief Push pointer into the ring buffer
* @param id Ring buffer identifier
* @param p Pointer to be pushed to the ring
* @return 1 if the pointer was successfully pushed, 0 if the buffer was full
* \brief Push pointer into the ring buffer
* \param id Ring buffer identifier
* \param p Pointer to be pushed to the ring
* \return 1 if the pointer was successfully pushed, 0 if the buffer was full
*/
epicsShareFunc int epicsShareAPI epicsRingPointerPush(epicsRingPointerId id,void *p);
/**
* @brief Take an element off the ring
* @param id Ring buffer identifier
* @return The pointer from the buffer, or NULL if the ring was empty
* \brief Take an element off the ring
* \param id Ring buffer identifier
* \return The pointer from the buffer, or NULL if the ring was empty
*/
epicsShareFunc void* epicsShareAPI epicsRingPointerPop(epicsRingPointerId id) ;
/**
* @brief Remove all elements from the ring
* @param id Ring buffer identifier
* @note If this operation is performed on a ring buffer of the unsecured
* \brief Remove all elements from the ring
* \param id Ring buffer identifier
* \note If this operation is performed on a ring buffer of the unsecured
* kind, all access to the ring should be locked.
*/
epicsShareFunc void epicsShareAPI epicsRingPointerFlush(epicsRingPointerId id);
/**
* @brief Return the amount of empty space in the ring buffer
* @param id Ring buffer identifier
* @return The number of additional elements it could hold.
* \brief Return the amount of empty space in the ring buffer
* \param id Ring buffer identifier
* \return The number of additional elements it could hold.
*/
epicsShareFunc int epicsShareAPI epicsRingPointerGetFree(epicsRingPointerId id);
/**
* @brief Return the number of elements stored in the ring buffer
* @param id Ring buffer identifier
* @return The number of elements stored in the ring buffer
* \brief Return the number of elements stored in the ring buffer
* \param id Ring buffer identifier
* \return The number of elements stored in the ring buffer
*/
epicsShareFunc int epicsShareAPI epicsRingPointerGetUsed(epicsRingPointerId id);
/**
* @brief Return the size of the ring
* @param id Ring buffer identifier
* @return The size of the ring buffer, i.e. the value of @c size
* \brief Return the size of the ring
* \param id Ring buffer identifier
* \return The size of the ring buffer, i.e. the value of \c size
* given when the ring was created.
*/
epicsShareFunc int epicsShareAPI epicsRingPointerGetSize(epicsRingPointerId id);
/**
* @brief Check if the ring buffer is currently empty
* @param id Ring buffer identifier
* @return 1 if the ring is empty, otherwise 0
* \brief Check if the ring buffer is currently empty
* \param id Ring buffer identifier
* \return 1 if the ring is empty, otherwise 0
*/
epicsShareFunc int epicsShareAPI epicsRingPointerIsEmpty(epicsRingPointerId id);
/**
* @brief Check if the ring buffer is currently full
* @param id Ring buffer identifier
* @return 1 if the ring buffer is full, otherwise 0
* \brief Check if the ring buffer is currently full
* \param id Ring buffer identifier
* \return 1 if the ring buffer is full, otherwise 0
*/
epicsShareFunc int epicsShareAPI epicsRingPointerIsFull(epicsRingPointerId id);
/**
* @brief Get the Highwater mark of the ring buffer
* \brief Get the Highwater mark of the ring buffer
*
* Returns the largest number of elements the ring buffer has held since
* the water mark was last reset. A new ring buffer starts with a
* water mark of 0.
* @param id Ring buffer identifier
* @return Actual Highwater mark
* \param id Ring buffer identifier
* \return Actual Highwater mark
*/
epicsShareFunc int epicsShareAPI epicsRingPointerGetHighWaterMark(epicsRingPointerIdConst id);
/**
* @brief Reset the Highwater mark of the ring buffer
* \brief Reset the Highwater mark of the ring buffer
*
* The Highwater mark will be set to the current usage
* @param id Ring buffer identifier
* \param id Ring buffer identifier
*/
epicsShareFunc void epicsShareAPI epicsRingPointerResetHighWaterMark(epicsRingPointerId id);