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

import CAref function and return codes reference to doxygen comments

Browse Source 
Import all function documentations, return code reference
into the header files, as doc comments,
in the hopes of moving the CAref.html manual to docs.epics-controls.org,
which will be done in a later PR.

Also added doc comments to some other low-hanging fruits,
for example when plain comments where near, or when it was obvious to do so.
This commit is contained in:
Minijackson
2025-01-20 13:44:09 +01:00
committed by Andrew Johnson
parent e4ebc01401
commit 0c75f1fe99
7 changed files with 1479 additions and 235 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
documentation/Makefile
View File

@@ -65,6 +65,11 @@ libcom_HEADERS += yajl_common
libcom_HEADERS += yajl_gen
libcom_HEADERS += yajl_parse
ca_HEADERS += cadef
ca_HEADERS += caerr
ca_HEADERS += caeventmask
ca_HEADERS += db_access
database_HEADERS += chfPlugin
database_HEADERS += dbChannel
database_HEADERS += dbCommon
@@ -128,7 +133,7 @@ menu_HEADERS += menuScan
menu_HEADERS += menuSimm
menu_HEADERS += menuYesNo
HEADER_TYPES = libcom database record menu
HEADER_TYPES = libcom ca database record menu
HEADER_MD_FILES = $(foreach t, $(HEADER_TYPES), \
$(addsuffix _h.md, $($t_HEADERS)))

7
documentation/ca-API.rst Normal file
View File

@@ -0,0 +1,7 @@
Channel Access C/C++ APIs
=========================
.. toctree::
:maxdepth: 1
:caption: CA Header Files

1
documentation/index.rst
View File

@@ -25,6 +25,7 @@ EPICS Base Documentation
:caption: C/C++ Headers
libcom-api
ca-api
database-api
record-api
menu-api

1545
modules/ca/src/client/cadef.h
View File

File diff suppressed because it is too large Load Diff

71
modules/ca/src/client/caerr.h
View File

@@ -19,6 +19,10 @@
*
*/
/** \file caerr.h
*
* \brief Channel access error definitions.
*/
#ifndef INC_caerr_H
#define INC_caerr_H
@@ -75,72 +79,139 @@
* servers on earlier releases that communicate with current clients
* might still generate exceptions with these error constants
*/
/// Normal successful completion
#define ECA_NORMAL DEFMSG(CA_K_SUCCESS, 0) /* success */
/// Maximum simultaneous IOC connections exceeded
#define ECA_MAXIOC DEFMSG(CA_K_ERROR, 1) /* defunct */
/// Unknown internet host
#define ECA_UKNHOST DEFMSG(CA_K_ERROR, 2) /* defunct */
/// Unknown internet service
#define ECA_UKNSERV DEFMSG(CA_K_ERROR, 3) /* defunct */
/// Unable to allocate a new socket
#define ECA_SOCK DEFMSG(CA_K_ERROR, 4) /* defunct */
/// Unable to connect to internet host or service
#define ECA_CONN DEFMSG(CA_K_WARNING, 5) /* defunct */
/// Unable to allocate additional dynamic memory
#define ECA_ALLOCMEM DEFMSG(CA_K_WARNING, 6)
/// Unknown IO channel
#define ECA_UKNCHAN DEFMSG(CA_K_WARNING, 7) /* defunct */
/// ECA_UKNFIELD - Record field specified inappropriate for channel specified
#define ECA_UKNFIELD DEFMSG(CA_K_WARNING, 8) /* defunct */
/// The requested data transfer is greater than available memory or EPICS_CA_MAX_ARRAY_BYTES
#define ECA_TOLARGE DEFMSG(CA_K_WARNING, 9)
/// User specified timeout on IO operation expired
#define ECA_TIMEOUT DEFMSG(CA_K_WARNING, 10)
/// Sorry, that feature is planned but not supported at this time
#define ECA_NOSUPPORT DEFMSG(CA_K_WARNING, 11) /* defunct */
/// The supplied string is unusually large
#define ECA_STRTOBIG DEFMSG(CA_K_WARNING, 12) /* defunct */
/// The request was ignored because the specified channel is disconnected
#define ECA_DISCONNCHID DEFMSG(CA_K_ERROR, 13) /* defunct */
/// The data type specifed is invalid
#define ECA_BADTYPE DEFMSG(CA_K_ERROR, 14)
/// Remote Channel not found
#define ECA_CHIDNOTFND DEFMSG(CA_K_INFO, 15) /* defunct */
/// Unable to locate all user specified channels
#define ECA_CHIDRETRY DEFMSG(CA_K_INFO, 16) /* defunct */
/// Channel Access Internal Failure
#define ECA_INTERNAL DEFMSG(CA_K_FATAL, 17)
/// The requested local DB operation failed
#define ECA_DBLCLFAIL DEFMSG(CA_K_WARNING, 18) /* defunct */
/// Channel read request failed
#define ECA_GETFAIL DEFMSG(CA_K_WARNING, 19)
/// Channel write request failed
#define ECA_PUTFAIL DEFMSG(CA_K_WARNING, 20)
/// Channel subscription request failed
#define ECA_ADDFAIL DEFMSG(CA_K_WARNING, 21) /* defunct */
/// Invalid element count requested
#define ECA_BADCOUNT DEFMSG(CA_K_WARNING, 22)
/// Invalid string
#define ECA_BADSTR DEFMSG(CA_K_ERROR, 23)
/// Virtual circuit disconnect
#define ECA_DISCONN DEFMSG(CA_K_WARNING, 24)
/// Identical process variable names on multiple servers
#define ECA_DBLCHNL DEFMSG(CA_K_WARNING, 25)
/// Request inappropriate within subscription (monitor) update callback
#define ECA_EVDISALLOW DEFMSG(CA_K_ERROR, 26)
/// Database value get for that channel failed during channel search
#define ECA_BUILDGET DEFMSG(CA_K_WARNING, 27) /* defunct */
/// Unable to initialize without the vxWorks VX_FP_TASK task option set
#define ECA_NEEDSFP DEFMSG(CA_K_WARNING, 28) /* defunct */
/// Event queue overflow has prevented first pass event after event add
#define ECA_OVEVFAIL DEFMSG(CA_K_WARNING, 29) /* defunct */
/// Bad event subscription (monitor) identifier
#define ECA_BADMONID DEFMSG(CA_K_ERROR, 30)
/// Remote channel has new network address
#define ECA_NEWADDR DEFMSG(CA_K_WARNING, 31) /* defunct */
/// New or resumed network connection
#define ECA_NEWCONN DEFMSG(CA_K_INFO, 32) /* defunct */
/// Specified task isnt a member of a CA context
#define ECA_NOCACTX DEFMSG(CA_K_WARNING, 33) /* defunct */
/// Attempt to use defunct CA feature failed
#define ECA_DEFUNCT DEFMSG(CA_K_FATAL, 34) /* defunct */
/// The supplied string is empty
#define ECA_EMPTYSTR DEFMSG(CA_K_WARNING, 35) /* defunct */
/// Unable to spawn the CA repeater thread- auto reconnect will fail
#define ECA_NOREPEATER DEFMSG(CA_K_WARNING, 36) /* defunct */
/// No channel id match for search reply- search reply ignored
#define ECA_NOCHANMSG DEFMSG(CA_K_WARNING, 37) /* defunct */
/// Reseting dead connection- will try to reconnect
#define ECA_DLCKREST DEFMSG(CA_K_WARNING, 38) /* defunct */
/// Server (IOC) has fallen behind or is not responding- still waiting
#define ECA_SERVBEHIND DEFMSG(CA_K_WARNING, 39) /* defunct */
/// No internet interface with broadcast available
#define ECA_NOCAST DEFMSG(CA_K_WARNING, 40) /* defunct */
/// Invalid event selection mask
#define ECA_BADMASK DEFMSG(CA_K_ERROR, 41)
/// IO operations have completed
#define ECA_IODONE DEFMSG(CA_K_INFO, 42)
/// IO operations are in progress
#define ECA_IOINPROGRESS DEFMSG(CA_K_INFO, 43)
/// Invalid synchronous group identifier
#define ECA_BADSYNCGRP DEFMSG(CA_K_ERROR, 44)
/// Put callback timed out
#define ECA_PUTCBINPROG DEFMSG(CA_K_ERROR, 45)
/// Read access denied
#define ECA_NORDACCESS DEFMSG(CA_K_WARNING, 46)
/// Write access denied
#define ECA_NOWTACCESS DEFMSG(CA_K_WARNING, 47)
/// Requested feature is no longer supported
#define ECA_ANACHRONISM DEFMSG(CA_K_ERROR, 48)
/// Empty PV search address list
#define ECA_NOSEARCHADDR DEFMSG(CA_K_WARNING, 49)
/// No reasonable data conversion between client and server types
#define ECA_NOCONVERT DEFMSG(CA_K_WARNING, 50)
/// Invalid channel identifier
#define ECA_BADCHID DEFMSG(CA_K_ERROR, 51)
/// Invalid function pointer
#define ECA_BADFUNCPTR DEFMSG(CA_K_ERROR, 52)
/// Thread is already attached to a client context
#define ECA_ISATTACHED DEFMSG(CA_K_WARNING, 53)
/// Not supported by attached service
#define ECA_UNAVAILINSERV DEFMSG(CA_K_WARNING, 54)
/// User destroyed channel
#define ECA_CHANDESTROY DEFMSG(CA_K_WARNING, 55)
/// Invalid channel priority
#define ECA_BADPRIORITY DEFMSG(CA_K_ERROR, 56)
/// Preemptive callback not enabled - additional threads may not join context
#define ECA_NOTTHREADED DEFMSG(CA_K_ERROR, 57)
/// Client's protocol revision does not support transfers exceeding 16k bytes
#define ECA_16KARRAYCLIENT DEFMSG(CA_K_WARNING, 58)
/// Virtual circuit connection sequence aborted
#define ECA_CONNSEQTMO DEFMSG(CA_K_WARNING, 59)
/// Virtual circuit unresponsive
#define ECA_UNRESPTMO DEFMSG(CA_K_WARNING, 60)
#ifdef __cplusplus
extern "C" {
#endif
/** \brief Return a message character string corresponding to a user specified CA status code.
*
* \param[in] ca_status A CA status code.
* \returns The corresponding error message string.
*/
LIBCA_API const char * epicsStdCall ca_message(long ca_status);
LIBCA_API extern const char * ca_message_text [];

44
modules/ca/src/client/caeventmask.h
View File

@@ -8,37 +8,43 @@
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/** \file caeventmask.h
*
* \brief Event selections
*/
#ifndef INCLcaeventmaskh
#define INCLcaeventmaskh
/*
event selections
(If any more than 8 of these are needed then update the
select field in the event_block struct in db_event.c from
unsigned char to unsigned short)
*/
DBE_VALUE
Trigger an event when a significant change in the channel's value
occurs. Relies on the monitor deadband field under DCT.
DBE_ARCHIVE (DBE_LOG)
Trigger an event when an archive significant change in the channel's
value occurs. Relies on the archiver monitor deadband field under DCT.
DBE_ALARM
Trigger an event when the alarm state changes
DBE_PROPERTY
Trigger an event when a property change (control limit, graphical
limit, status string, enum string ...) occurs.
*/
/** \brief Trigger an event when a significant change in the channel's value occurs.
*
* Relies on the monitor deadband field under DCT.
*/
#define DBE_VALUE (1<<0)
/** \brief Trigger an event when an archive significant change in the channel's value occurs.
*
* Relies on the archiver monitor deadband field under DCT.
*/
#define DBE_ARCHIVE (1<<1)
/** \brief Same as ::DBE_ARCHIVE.
*/
#define DBE_LOG DBE_ARCHIVE
/** \brief Trigger an event when the alarm state changes.
*/
#define DBE_ALARM (1<<2)
/** \brief Trigger an event when a property change occurs.
* (control limit, graphical limit, status string, enum string ...)
*/
#define DBE_PROPERTY (1<<3)
#endif

39
modules/ca/src/client/db_access.h
View File

@@ -516,13 +516,40 @@ struct dbr_ctrl_double{
dbr_double_t value; /* current value */
};
/** \brief Returns the size in bytes for a `DBR_XXXX` type with `COUNT` elements.
*
* If the DBR type is a structure then the value field is the last field in the
* structure. If `COUNT` is greater than one then `COUNT-1` elements are
* appended to the end of the structure so that they can be addressed as an
* array through a pointer to the value field.
*
* \sa dbr_size, dbr_value_size
*
* \param[in] TYPE The data type.
* \param[in] COUNT The element count.
* \returns The size in bytes of the specified type
* with the specified number of elements.
*/
#define dbr_size_n(TYPE,COUNT)\
((unsigned)((COUNT)<0?dbr_size[TYPE]:dbr_size[TYPE]+((COUNT)-1)*dbr_value_size[TYPE]))
/* size for each type - array indexed by the DBR_ type code */
/** \brief Size in bytes for each `DBR_XXXX` type.
*
* Array indexed by the `DBR_XXXX` type code.
*
* \sa dbr_size_n()
*/
LIBCA_API extern const unsigned short dbr_size[];
/* size for each type's value - array indexed by the DBR_ type code */
/** \brief Size in bytes for each type's value.
*
* Array indexed by the `DBR_XXXX` type code.
*
* If the type is a structure the size of the value field is returned otherwise
* the size of the type is returned.
*
* \sa dbr_size_n()
*/
LIBCA_API extern const unsigned short dbr_value_size[];
#ifndef db_accessHFORdb_accessC
@@ -685,6 +712,14 @@ union db_access_val{
break; \
}
/** \brief Returns a constant null terminated string
* corresponding to the specified dbr type.
*
* \param[in] type The data type code.
* A member of the set of `DBR_XXXX` in `db_access.h`.
*
* \returns The const string corresponding to the `DBR_XXXX` type.
*/
#define dbr_type_to_text(type) \
( ((type) >= 0 && (type) < dbr_text_dim) ? \
dbr_text[(type)] : dbr_text_invalid )