summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMartin Burnicki <martin.burnicki@meinberg.de>2014-07-30 12:00:00 +0200
committerMartin Burnicki <martin.burnicki@meinberg.de>2014-07-30 12:00:00 +0200
commitac08e59d3c927bd0ae95f926df08295c7e9b2269 (patch)
tree898fcb3c43a5e8bb97d92651e9b701c5885d9e90
parentf6c51fd5c56b3e0247792573ea3335f7e00675a9 (diff)
downloadmbgsdk-win-ac08e59d3c927bd0ae95f926df08295c7e9b2269.tar.gz
mbgsdk-win-ac08e59d3c927bd0ae95f926df08295c7e9b2269.zip
Update mbglib files for the C demo projectsmbgsdk-mbglib-2014-07-30
Diffstat
-rw-r--r--c/mbglib/include/eventlog.h6
-rw-r--r--c/mbglib/include/gpsdefs.h8936
-rw-r--r--c/mbglib/include/gpsutils.h12
-rw-r--r--c/mbglib/include/lan_util.h597
-rw-r--r--c/mbglib/include/mbg_arch.h16
-rw-r--r--c/mbglib/include/mbg_tgt.h277
-rw-r--r--c/mbglib/include/mbg_w32.h2
-rw-r--r--c/mbglib/include/mbgdevio.h2757
-rw-r--r--c/mbglib/include/mbgerror.h283
-rw-r--r--c/mbglib/include/mbgirig.h467
-rw-r--r--c/mbglib/include/mbgmutex.h15
-rw-r--r--c/mbglib/include/mbgpccyc.h8
-rw-r--r--c/mbglib/include/mbgsvcio.h140
-rw-r--r--c/mbglib/include/mbgtime.h87
-rw-r--r--c/mbglib/include/mbgutil.h69
-rw-r--r--c/mbglib/include/pci_asic.h21
-rw-r--r--c/mbglib/include/pcpsdefs.h1735
-rw-r--r--c/mbglib/include/pcpsdev.h567
-rw-r--r--c/mbglib/include/usbdefs.h114
-rw-r--r--c/mbglib/include/use_pack.h8
-rw-r--r--c/mbglib/include/words.h298
-rw-r--r--c/mbglib/lib/bc/mbgsvcio.libbin2560 -> 2560 bytes
-rw-r--r--c/mbglib/lib/msc/mbgsvcio.libbin7736 -> 7148 bytes
23 files changed, 11808 insertions, 4607 deletions
diff --git a/c/mbglib/include/eventlog.h b/c/mbglib/include/eventlog.h
index 910be4c..576d3f8 100644
--- a/c/mbglib/include/eventlog.h
+++ b/c/mbglib/include/eventlog.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: eventlog.h 1.3 2007/09/26 14:56:03Z martin REL_M $
+ * $Id: eventlog.h 1.4 2014/03/05 10:38:46Z martin TRASH $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -10,6 +10,8 @@
*
* -----------------------------------------------------------------------
* $Log: eventlog.h $
+ * Revision 1.4 2014/03/05 10:38:46Z martin
+ * Windows.h is now included in mbg_tgt.h.
* Revision 1.3 2007/09/26 14:56:03Z martin
* Updated function prototypes.
* Revision 1.2 2004/04/14 08:36:54Z martin
@@ -25,7 +27,7 @@
/* Other headers to be included */
-#include <windows.h>
+#include <mbg_tgt.h>
#include <use_pack.h>
diff --git a/c/mbglib/include/gpsdefs.h b/c/mbglib/include/gpsdefs.h
index c65a251..df30fe5 100644
--- a/c/mbglib/include/gpsdefs.h
+++ b/c/mbglib/include/gpsdefs.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: gpsdefs.h 1.105.1.5.1.6 2012/08/03 11:33:33Z Gregoire TRASH $
+ * $Id: gpsdefs.h 1.120.1.24 2014/07/14 15:42:45Z martin TRASH martin $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -13,23 +13,122 @@
*
* -----------------------------------------------------------------------
* $Log: gpsdefs.h $
- * Revision 1.105.1.5.1.6 2012/08/03 11:33:33Z Gregoire
- * short strings for GPIO types added (DEFAULT_GPIO_TYPES_SHORT_STRS)
- * Revision 1.105.1.5.1.5 2012/07/23 14:53:05Z andre
- * bugfix in XMULTI Ref Names
- * Revision 1.105.1.5.1.4 2012/07/20 10:12:04Z martin
- * Revision 1.105.1.5.1.3 2012/07/20 09:36:46 martin
- * Revision 1.105.1.5.1.2 2012/07/19 14:03:27 martin
- * More changes, not yet finished.
- * Revision 1.105.1.5.1.1 2012/07/19 12:57:57 martin
- * Started to modify GPIO structures.
- * Revision 1.105.1.5 2012/07/19 10:29:48 martin
- * Revision 1.105.1.4 2012/07/10 12:43:20 werner
- * GRC defines added
- * Revision 1.105.1.3 2012/06/28 08:20:02Z marvin
+ * Revision 1.120.1.24 2014/07/14 15:42:45Z martin
+ * Revision 1.120.1.23 2014/07/09 15:08:10 martin
+ * Revision 1.120.1.22 2014/07/09 14:14:34 martin
+ * Revision 1.120.1.21 2014/07/09 09:25:14 martin
+ * Revision 1.120.1.20 2014/07/08 15:26:28Z martin
+ * Doxygen stuff.
+ * Revision 1.120.1.19 2014/07/08 10:45:14 martin
+ * Revision 1.120.1.18 2014/07/08 10:41:47 martin
+ * Revision 1.120.1.17 2014/07/08 10:33:20 martin
+ * Doxygen fixes.
+ * Revision 1.120.1.16 2014/07/08 09:46:20Z martin
+ * Doxygen fixes.
+ * Revision 1.120.1.15 2014/07/08 09:35:55 martin
+ * Removed obsolete/unused XMR flag.
+ * Revision 1.120.1.14 2014/07/08 08:45:20 martin
+ * Revision 1.120.1.13 2014/07/08 08:18:41 martin
+ * Doxygen stuff.
+ * Revision 1.120.1.12 2014/07/08 07:24:08 martin
+ * Revision 1.120.1.10 2014/07/07 11:29:21 martin
+ * Revision 1.120.1.9 2014/07/07 11:05:01 martin
+ * Revision 1.120.1.8 2014/07/07 08:34:55 martin
+ * Revision 1.120.1.7 2014/07/04 12:08:17 martin
+ * Revision 1.120.1.6 2014/07/04 08:00:02 martin
+ * Revision 1.120.1.5 2014/07/02 15:34:41 martin
+ * Modified holdover status structure
+ * Revision 1.120.1.4 2014/06/30 15:43:29 martin
+ * Revision 1.120.1.3 2014/06/26 13:38:06 martin
+ * Modified/extended MBG_GPIO_STATUS.
+ * Revision 1.120.1.2 2014/06/23 09:11:49 martin
+ * Revision 1.120.1.1 2014/06/19 15:13:25 martin
+ * Support GPIO status.
+ * Revision 1.120 2014/05/27 08:34:40 martin
+ * Fixed braces in some _mbg_rcvr_is_..() macros.
+ * Definitions used with extended network cfg, VST, and SHS.
+ * Introduced XMR_HOLDOVER_STATUS.
+ * Introduced programmable output mode POUT_GPIO.
+ * Introduced oscillator type OCXO_SQ.
+ * Defined some new baud rates.
+ * Defines for IEEE C37.118.1-2011 CTQ.
+ * Support for new model SCG by paul.
+ * Support new model PPG180.
+ * New SCU control masks.
+ * New GNSS flag MBG_GNSS_FLAG_SAT_INFO_IDX_SUPP_SER.
+ * DEFAULT_MULTI_REF_NAMES_SHORT added by udo.
+ * Definitions used for NTP configuration by thomas-b and marvin.
+ * MBG_NET_ADDR structures changed to MBG_IP_ADDR, and
+ * associated symbols defined by marvin.
+ * Huge rework of comments in doxygen format.
+ * Revision 1.119 2013/12/05 10:13:13 daniel
+ * Support new PTP_CFG_FLAGS for 1-step-L2 and 1-step-P2P support
+ * Revision 1.118 2013/11/19 13:38:35 martin
+ * Added LAN_IF_TYPE_RSC.
+ * Revision 1.117 2013/11/18 14:13:39 martin
+ * Support model LNE_GB.
+ * Revision 1.116 2013/11/11 09:46:11 martin
+ * New PTP configuration flags PTP_CFG_SUPP_MCAST_SLAVE_FLAG and
+ * PTP_CFG_CAN_BE_MULTICAST_SLAVE, plus associated bit masks.
+ * New XMR_INST_FLAGS and XMR_INST_FLAG_MASKS defined by andre.
+ * Fixes for big-endian targets.
+ * Updated doxygen comments.
+ * Revision 1.115 2013/10/02 15:19:28 martin
+ * Changed PTP_CFG_SETTINGS::vlan_cfg back to a reserved field,
+ * and removed associated flag and flag mask.
+ * Revision 1.114 2013/09/25 11:02:10 martin
+ * Support models MRI, BPE, GLN180PEX, N2X, RSC180.
+ * Added feature bit GPS_FEAT_NTP.
+ * Enhanced VLAN configuration structures.
+ * Started to support IPv6.
+ * Renamed PTP_CFG_SETTINGS field "profile" to "selected_presets".
+ * Renamed PTP_CFG_INFO field "supp_profiles" to "supp_opt_ext".
+ * New PTP role PTP_ROLE_BOTH_MASTER.
+ * New PTP flag PTP_FLAG_ONE_STEP.
+ * Added some new PTP_CFG_FLAGS flags.
+ * Added PTP_OPT_EXTS and associated definitions.
+ * Added PTP_PRESETS and associated definitions.
+ * Added "tzdl" field to PTP_POWER_PROFILE_CFG.
+ * Made reserved PTP_CFG_SETTINGS field to "opt_ext" field.
+ * Made reserved PTP_CFG_SETTINGS field to "vlan_cfg" field.
+ * Made reserved PTP_STATE field to "parent_clock_class" and "parent_clock_accuracy".
+ * Definitions for MULTI_REF_EXT_OSC added by Andre.
+ * String initializers for supported HaveQuick formats added by Gregoire.
+ * Lots of doxygen changes.
+ * Revision 1.113 2013/04/04 09:02:01Z martin
+ * Added definitions to support HaveQuick.
+ * Fixed a typo.
+ * Revision 1.112 2013/02/19 15:39:13 martin
+ * New PTP settings field ann_rcpt_timeout and associated
+ * values PTP_ANN_RCPT_TIMEOUT_LIMITS.
+ * Changed many defines to named enums to simplify references
+ * with doxygen.
+ * Updated doxygen comments.
+ * Revision 1.111 2013/02/01 15:37:36 martin
+ * Added and modified a huge number of doxygen comments.
+ * Revision 1.110 2013/01/16 15:23:25 martin
+ * Fixed 2 comments which were interchanged.
+ * Revision 1.109 2013/01/11 10:39:34 martin
+ * Added definitions for IMS.
+ * Support XMR_HOLDOVER_INTV.
+ * New XMRS status bit XMRS_BIT_LOW_JITTER / XMRS_MSK_LOW_JITTER.
+ * Added framing type 8E2, though most UARTs don't support this.
+ * Added enum names and updated comments for doxygen.
+ * Revision 1.108 2012/10/30 11:31:16 martin
+ * Defined PTP_UC_MSG_DURATION_MIN and PTP_UC_MSG_DURATION_MAX.
+ * Fixed some doxygen comments.
+ * Changes by andre: changed reserved field to ssm and boc in BITS_OUT settings.
+ * Revision 1.107 2012/10/12 07:40:12 martin
+ * New PTP state flags PTP_FLAG_MSK_UTC_VALID and
+ * PTP_CFG_MSK_SUPP_UTC_VALID.
+ * Revision 1.106 2012/10/02 18:22:10 martin
* Added default baud rate and framing for binary protocol.
- * Revision 1.105.1.2 2012/06/22 14:48:27Z martin
- * Revision 1.105.1.1 2012/06/21 08:44:25 martin
+ * Added definitions for IRIG codes E002/E112 and NASA36.
+ * Reworked GPIO structures.
+ * Added definitions for GRC, LIU, DCF600RS, and DCF600HS.
+ * New flag POUT_FIXED_PULSE_LEN.
+ * New flag POUT_NOT_INVERTIBLE.
+ * Unified capitalization in MBG_XMRS_STATUS_STRS.
* Revision 1.105 2012/06/01 16:31:16 martin
* Some TIME_SLOT definitions added by marvin.
* Moved some PTP configuration defaults and limits to ptpdflts.h.
@@ -123,7 +222,7 @@
* Added support for new model GLN170.
* Revision 1.87 2010/03/10 11:29:37Z martin
* Added definitions for GPS180.
- * Added multiref source 1 PPS plus associated string.
+ * Added multi ref source 1 PPS plus associated string.
* Revision 1.86 2010/02/17 14:16:42 martin
* Added definitions for PZF600 and TCR600.
* Revision 1.85 2010/02/15 11:34:36 martin
@@ -193,7 +292,7 @@
* Added definitions for PTP270PEX and FRC511PEX.
* Revision 1.67 2008/07/17 08:54:52Z martin
* Added macros to convert the endianess of structures.
- * Added multiref fixed frequency source.
+ * Added multi ref fixed frequency source.
* Revision 1.66 2008/05/19 14:49:07 daniel
* Renamed s_addr to start_addr in FPGA_INFO.
* Revision 1.65 2008/05/19 09:00:01Z martin
@@ -215,7 +314,7 @@
* Added definitions to support GPS170PEX.
* Revision 1.60 2007/09/13 12:37:35Z martin
* Modified and added initializers for TZDL.
- * Added multiref source PTP over E1.
+ * Added multi ref source PTP over E1.
* Added codes for MSF511 and GRC170 devices.
* Modified XMULTI_REF_SETTINGS and XMULTI_REF_STATUS structures.
* Avoid inclusion of other Meinberg headers in non-Meinberg projects.
@@ -268,7 +367,7 @@
* Added ROM_CSUM, RCV_TIMEOUT, and IGNORE_LOCK types.
* Revision 1.44 2006/05/18 09:34:41Z martin
* Added definitions for POUT max. pulse_len and max timeout.
- * Changed comment for POUT_SETTINGS::timeout:
+ * Changed comment for POUT_SETTINGS::timeout.
* Units are minutes, not seconds.
* Added definition for MAX_POUT_TIME_STR_PORTS.
* Added definitions for POUT mode 10MHz.
@@ -341,7 +440,7 @@
* Revision 1.20 2003/04/03 11:03:44Z martin
* Extended definitions for IRIG support.
* Revision 1.19 2003/01/31 13:38:20 MARTIN
- * Modified type of RECEIVER_INFO.fixed_freq field.
+ * Modified type of RECEIVER_INFO::fixed_freq field.
* Revision 1.18 2002/10/28 09:24:07 MARTIN
* Added/renamed some POUT related symbols.
* Revision 1.17 2002/09/05 10:58:39 MARTIN
@@ -421,12 +520,36 @@
#endif
+
/* "magic" number */
#define MEINBERG_MAGIC 0x6AAC
-#define MIN_SVNO 1 /* min. SV number */
-#define MAX_SVNO 32 /* max. SV number */
-#define N_SVNO ( MAX_SVNO - MIN_SVNO + 1) /* number of possibly active SVs */
+/**
+ * @brief GNSS satellite numbers
+ *
+ * @todo: Check if MAX_SVNO_GLN is 94 instead of 95, and thus
+ * N_SVNO_GLN is 30 instead of 31, as reported by Wikipedia.
+ */
+enum GNSS_SVNOS
+{
+ MIN_SVNO_GPS = 1, ///< min. GPS satellite PRN number
+ MAX_SVNO_GPS = 32, ///< max. GPS satellite PRN number
+ N_SVNO_GPS = 32, ///< max. number of active GPS satellites
+
+ MIN_SVNO_WAAS = 33, ///< min. WAAS satellite number
+ MAX_SVNO_WAAS = 64, ///< max. WAAS satellite number
+ N_SVNO_WAAS = 32, ///< max. number of active WAAS satellites
+
+ MIN_SVNO_GLONASS = 65, ///< min. Glonass satellite number (64 + sat slot ID)
+ MAX_SVNO_GLONASS = 95, ///< max. Glonass satellite number (64 + sat slot ID)
+ N_SVNO_GLONASS = 31 ///< max. number of active Glonass satellites
+};
+
+// for compatibility with GPS-only software:
+#define MIN_SVNO MIN_SVNO_GPS ///< min. SV number
+#define MAX_SVNO MAX_SVNO_GPS ///< max. SV number
+#define N_SVNO N_SVNO_GPS ///< number of possibly active SVs
+
#define GPS_ID_STR_LEN 16
@@ -436,29 +559,30 @@
#define GPS_EPLD_STR_SIZE ( GPS_EPLD_STR_LEN + 1 )
-#define DEFAULT_GPS_TICKS_PER_SEC 10000000L /* system time base */
+#define DEFAULT_GPS_TICKS_PER_SEC 10000000L ///< system time base, see ::GPS_TICKS_PER_SEC
#if !defined( GPS_TICKS_PER_SEC )
/*
* The actual ticks per seconds may vary for different
* GPS receiver models. If this is the case, the receiver
- * model support the RECEIVER_INFO structure which contains
+ * model support the ::RECEIVER_INFO structure which contains
* the actual value.
*/
- #define GPS_TICKS_PER_SEC DEFAULT_GPS_TICKS_PER_SEC
+ #define GPS_TICKS_PER_SEC DEFAULT_GPS_TICKS_PER_SEC ///< see ::DEFAULT_GPS_TICKS_PER_SEC
+
#endif
-typedef uint16_t SVNO; /* the number of a SV */
-typedef uint16_t HEALTH; /* a SV's health code */
-typedef uint16_t CFG; /* a SV's configuration code */
-typedef uint16_t IOD; /* Issue-Of-Data code */
+typedef uint16_t SVNO; ///< the number of an SV (Space Vehicle, i.e. satellite)
+typedef uint16_t HEALTH; ///< an SV's health code
+typedef uint16_t CFG; ///< an SV's configuration code
+typedef uint16_t IOD; ///< Issue-Of-Data code
/* the type of various checksums */
#ifndef _CSUM_DEFINED
- typedef uint16_t CSUM;
+ typedef uint16_t CSUM; ///< checksum used by some structures stored in non-volatile memory
#define _CSUM_DEFINED
#define _mbg_swab_csum( _p ) _mbg_swab16( _p )
@@ -468,9 +592,8 @@ typedef uint16_t IOD; /* Issue-Of-Data code */
/**
* @brief The type of a GPS command code
*
- * These command codes can be passed via
- * @ref group_gps_cmds_serial "serial port" (see @file gpsserio.h), or
- * @ref group_gps_cmds_bus "system bus" (see @file pcpsdefs.h).
+ * @see ::GPS_CMD_CODES
+ * @see ::PC_GPS_CMD_CODES
*/
typedef uint16_t GPS_CMD;
@@ -485,9 +608,10 @@ typedef uint16_t GPS_CMD;
*/
typedef struct
{
- uint16_t code; /**< Version number, e.g. 0x0120 means v1.20 */
- char name[GPS_ID_STR_SIZE]; /**< Optional string identifying a customized version */
- uint8_t reserved; /**< Reserved field to yield even structure size */
+ uint16_t code; ///< Version number, e.g. 0x0120 means v1.20
+ char name[GPS_ID_STR_SIZE]; ///< Optional string identifying a customized version
+ uint8_t reserved; ///< Reserved field to yield even structure size
+
} SW_REV;
#define _mbg_swab_sw_rev( _p ) \
@@ -498,7 +622,7 @@ typedef struct
/**
- * @defgroup group_bvar_stat BVAR_STAT status of buffered GPS data
+ * @defgroup group_bvar_stat Status of buffered (non-volatile) data
*
* Status word, associated bit numbers and bit masks indicating
* whether certain data from the GPS satellites are
@@ -510,49 +634,96 @@ typedef struct
* @{ */
/**
- * @brief Status flags of battery buffered data received
- * from GPS satellites.
+ * @brief Status flags of battery buffered data
+ *
+ * Related to data received from the satellites, or data derived thereof.
*
* All '0' means OK, single bits set to '1' indicate
* the associated type of GPS data is not available.
+ *
+ * @see ::BVAR_FLAGS
*/
typedef uint16_t BVAR_STAT;
#define _mbg_swab_bvar_stat( _p ) _mbg_swab16( (_p) )
-/** @brief Enumeration of bits used with BVAR_STAT */
-enum
+/**
+ * @brief Enumeration of flag bits used to define ::BVAR_FLAGS
+ *
+ * For each bit which is set this means the associated data set in
+ * non-volatile memory is not available, or incomplete.
+ * Most data sets will just be re-collected from the data streams sent
+ * by the satellites. However, the receiver position has usually been
+ * computed earlier during normal operation, and will be re-computed
+ * when a sufficient number of satellites can be received.
+ *
+ * @see ::BVAR_STAT
+ * @see ::BVAR_FLAGS
+ * @see ::BVAR_FLAG_NAMES
+ */
+enum BVAR_FLAG_BITS
+{
+ BVAR_BIT_CFGH_INVALID, ///< Satellite configuration and health parameters incomplete
+ BVAR_BIT_ALM_NOT_COMPLETE, ///< Almanac parameters incomplete
+ BVAR_BIT_UTC_INVALID, ///< %UTC offset parameters incomplete
+ BVAR_BIT_IONO_INVALID, ///< Ionospheric correction parameters incomplete
+ BVAR_BIT_RCVR_POS_INVALID, ///< No valid receiver position available
+ N_BVAR_BIT ///< number of defined ::BVAR_STAT bits
+};
+
+
+/**
+ * @brief Bit masks associated with ::BVAR_FLAG_BITS
+ *
+ * Used with ::BVAR_STAT.
+ *
+ * @see ::BVAR_STAT
+ * @see ::BVAR_FLAG_BITS
+ * @see ::BVAR_FLAG_NAMES
+ */
+enum BVAR_FLAGS
{
- BVAR_BIT_CFGH_INVALID,
- BVAR_BIT_ALM_NOT_COMPLETE,
- BVAR_BIT_UTC_INVALID,
- BVAR_BIT_IONO_INVALID,
- BVAR_BIT_RCVR_POS_INVALID,
- N_BVAR_BIT /**< @brief number of defined ::BVAR_STAT bits */
+ BVAR_CFGH_INVALID = ( 1UL << BVAR_BIT_CFGH_INVALID ), ///< see ::BVAR_BIT_CFGH_INVALID
+ BVAR_ALM_NOT_COMPLETE = ( 1UL << BVAR_BIT_ALM_NOT_COMPLETE ), ///< see ::BVAR_BIT_ALM_NOT_COMPLETE
+ BVAR_UTC_INVALID = ( 1UL << BVAR_BIT_UTC_INVALID ), ///< see ::BVAR_BIT_UTC_INVALID
+ BVAR_IONO_INVALID = ( 1UL << BVAR_BIT_IONO_INVALID ), ///< see ::BVAR_BIT_IONO_INVALID
+ BVAR_RCVR_POS_INVALID = ( 1UL << BVAR_BIT_RCVR_POS_INVALID ), ///< see ::BVAR_BIT_RCVR_POS_INVALID
};
-#define BVAR_CFGH_INVALID ( 1UL << BVAR_BIT_CFGH_INVALID ) /**< @brief Configuration and health data (::CFGH) not valid */
-#define BVAR_ALM_NOT_COMPLETE ( 1UL << BVAR_BIT_ALM_NOT_COMPLETE ) /**< @brief Almanach data (::ALM) not complete */
-#define BVAR_UTC_INVALID ( 1UL << BVAR_BIT_UTC_INVALID ) /**< @brief UTC data not valid */
-#define BVAR_IONO_INVALID ( 1UL << BVAR_BIT_IONO_INVALID ) /**< @brief Ionospheric correction data (::IONO) not valid */
-#define BVAR_RCVR_POS_INVALID ( 1UL << BVAR_BIT_RCVR_POS_INVALID ) /**< @brief Receiver position (::POS) not valid */
+#define BVAR_MASK ( ( 1UL << N_BVAR_BIT ) - 1 ) ///< Bit mask for all defined bits
+
-#define BVAR_MASK ( ( 1UL << N_BVAR_BIT ) - 1 ) /**< @brief Bit mask for all defined bits */
+/**
+ * @brief String initializer for ::BVAR_STAT flag names
+ *
+ * @see ::BVAR_STAT
+ * @see ::BVAR_FLAG_BITS
+ * @see ::BVAR_FLAGS
+ */
+#define BVAR_FLAG_NAMES \
+{ \
+ "Sat. config and health", \
+ "Almanac", \
+ "UTC offset", \
+ "Ionospheric correction", \
+ "Receiver position" \
+}
-/** @} group_bvar_stat */
+/** @} defgroup group_bvar_stat */
/**
- A structure used to hold a fixed frequency value.
- frequ[kHz] = khz_val * 10^range
-*/
-
+ * @brief A structure used to hold a fixed frequency value
+ *
+ * @note frequ[kHz] = khz_val * 10^range
+ */
typedef struct
{
- uint16_t khz_val; /* the base frequency in [kHz] */
- int16_t range; /* an optional base 10 exponent */
+ uint16_t khz_val; ///< the base frequency in [kHz]
+ int16_t range; ///< an optional base 10 exponent
+
} FIXED_FREQ_INFO;
#define _mbg_swab_fixed_freq_info( _p ) \
@@ -562,38 +733,37 @@ typedef struct
}
-typedef uint32_t RI_FEATURES; // type of RECEIVER_INFO::features field
+/**
+ * @brief A data type to specify feature flags within ::RECEIVER_INFO
+ */
+typedef uint32_t RI_FEATURES; ///< see @ref GPS_FEATURE_MASKS
-/*
- * The following code defines features and properties
- * of the various GPS receivers. Older GPS receivers
- * may require a recent firmvare version to support
- * this, or may not support this at all.
- */
-
-/**
- * The structure is ordered in a way that all fields
- * except chars or arrays of chars are word-aligned.
- */
-typedef struct
-{
- uint16_t model_code; /**< identifier for receiver model */
- SW_REV sw_rev; /**< software revision and ID */
- char model_name[GPS_ID_STR_SIZE]; /**< ASCIIZ, name of receiver model */
- char sernum[GPS_ID_STR_SIZE]; /**< ASCIIZ, serial number */
- char epld_name[GPS_EPLD_STR_SIZE]; /**< ASCIIZ, file name of EPLD image */
- uint8_t n_channels; /**< number of sats to be tracked simultaneously */
- uint32_t ticks_per_sec; /**< resolution of fractions of seconds */
- RI_FEATURES features; /**< optional features, see below */
- FIXED_FREQ_INFO fixed_freq; /**< optional non-standard fixed frequency */
- uint8_t osc_type; /**< type of installed oscillator, see below */
- uint8_t osc_flags; /**< oscillator flags, see below */
- uint8_t n_ucaps; /**< number of user time capture inputs */
- uint8_t n_com_ports; /**< number of on-board serial ports */
- uint8_t n_str_type; /**< max num of string types supported by any port */
- uint8_t n_prg_out; /**< number of programmable pulse outputs */
- uint16_t flags; /**< additional information, see below */
+
+/**
+ * @brief A structure used to identify a device type and supported features
+ *
+ * @note This may not be supported by some very old devices.
+ */
+typedef struct
+{
+ uint16_t model_code; ///< identifier for receiver model, see ::GPS_MODEL_CODES
+ SW_REV sw_rev; ///< software revision and ID
+ char model_name[GPS_ID_STR_SIZE]; ///< ASCIIZ, name of receiver model
+ char sernum[GPS_ID_STR_SIZE]; ///< ASCIIZ, serial number
+ char epld_name[GPS_EPLD_STR_SIZE]; ///< ASCIIZ, file name of EPLD image (optional)
+ uint8_t n_channels; ///< number of satellites which can be tracked simultaneously
+ uint32_t ticks_per_sec; ///< resolution of fractions of seconds, see ::GPS_TICKS_PER_SEC
+ RI_FEATURES features; ///< optional features, see @ref GPS_FEATURE_MASKS
+ FIXED_FREQ_INFO fixed_freq; ///< optional non-standard fixed frequency, may be 0 if not supported
+ uint8_t osc_type; ///< type of installed oscillator, see ::GPS_OSC_TYPES
+ uint8_t osc_flags; ///< oscillator flags, actually not used and always 0
+ uint8_t n_ucaps; ///< number of user time capture inputs
+ uint8_t n_com_ports; ///< number of on-board serial ports
+ uint8_t n_str_type; ///< max num of string types supported by any port
+ uint8_t n_prg_out; ///< number of programmable pulse outputs
+ uint16_t flags; ///< additional information, see ::RECEIVER_INFO_FLAG_BITS
+
} RECEIVER_INFO;
#define _mbg_swab_receiver_info( _p ) \
@@ -608,9 +778,12 @@ typedef struct
/**
- * Valid codes for RECEIVER_INFO.model_code:
+ * @brief Known device ID codes for ::RECEIVER_INFO::model_code
+ *
+ * @see @ref GPS_MODEL_NAMES
+ * @see ::DEFAULT_GPS_MODEL_NAMES
*/
-enum
+enum GPS_MODEL_CODES
{
GPS_MODEL_UNKNOWN,
GPS_MODEL_GPS166,
@@ -657,20 +830,38 @@ enum
GPS_MODEL_CPE180,
GPS_MODEL_LNO180,
GPS_MODEL_GRC180,
+ GPS_MODEL_LIU,
+ GPS_MODEL_DCF600HS,
+ GPS_MODEL_DCF600RS,
+ GPS_MODEL_MRI,
+ GPS_MODEL_BPE,
+ GPS_MODEL_GLN180PEX,
+ GPS_MODEL_N2X,
+ GPS_MODEL_RSC180,
+ GPS_MODEL_LNE_GB,
+ GPS_MODEL_PPG180,
+ GPS_MODEL_SCG,
N_GPS_MODEL
/* If new model codes are added then care must be taken
- * to update the associated string initializers below
- * accordingly, and to check whether the classification macros
- * also cover the new model names. */
+ * to update the associated string initializers GPS_MODEL_NAMES
+ * and GPS_MODEL_NAME_TABLE accordingly, and to check whether
+ * the classification macros also cover the new model names.
+ */
};
+/**
+ * @brief Model name strings used with Meinberg devices
+ *
+ * String initializers for each of the device models
+ * enumerated in ::GPS_MODEL_CODES.
+ *
+ * @see ::GPS_MODEL_CODES
+ * @see ::DEFAULT_GPS_MODEL_NAMES
+ *
+ * @anchor GPS_MODEL_NAMES @{ */
-/*
- * String initializers for each of the GPS
- * receiver models enum'ed above:
- */
#define GPS_MODEL_NAME_UNKNOWN "(unknown)"
#define GPS_MODEL_NAME_GPS166 "GPS166"
#define GPS_MODEL_NAME_GPS167 "GPS167"
@@ -716,12 +907,33 @@ enum
#define GPS_MODEL_NAME_CPE180 "CPE180"
#define GPS_MODEL_NAME_LNO180 "LNO180"
#define GPS_MODEL_NAME_GRC180 "GRC180"
+#define GPS_MODEL_NAME_LIU "LIU"
+#define GPS_MODEL_NAME_DCF600HS "DCF600HS"
+#define GPS_MODEL_NAME_DCF600RS "DCF600RS"
+#define GPS_MODEL_NAME_MRI "MRI"
+#define GPS_MODEL_NAME_BPE "BPE"
+#define GPS_MODEL_NAME_GLN180PEX "GLN180PEX"
+#define GPS_MODEL_NAME_N2X "N2X"
+#define GPS_MODEL_NAME_RSC180 "RSC180"
+#define GPS_MODEL_NAME_LNE_GB "LNE_GB"
+#define GPS_MODEL_NAME_PPG180 "PPG180"
+#define GPS_MODEL_NAME_SCG "SCG"
-/*
- * The definition below can be used to initialize
- * an array of N_GPS_MODEL type name strings.
- * Including the trailing 0, each name must not
- * exceed GPS_ID_STR_SIZE chars.
+/** @} anchor GPS_MODEL_NAMES */
+
+
+
+/**
+ * @brief An initializer for a table of device names
+ *
+ * Can be used to initialize an array of ::N_GPS_MODEL
+ * type name strings.
+ *
+ * @note Including the trailing 0, each name must not
+ * exceed ::GPS_ID_STR_SIZE chars.
+ *
+ * @see ::GPS_MODEL_CODES
+ * @see @ref GPS_MODEL_NAMES
*/
#define DEFAULT_GPS_MODEL_NAMES \
{ \
@@ -769,9 +981,397 @@ enum
GPS_MODEL_NAME_ESI180, \
GPS_MODEL_NAME_CPE180, \
GPS_MODEL_NAME_LNO180, \
- GPS_MODEL_NAME_GRC180 \
+ GPS_MODEL_NAME_GRC180, \
+ GPS_MODEL_NAME_LIU, \
+ GPS_MODEL_NAME_DCF600HS, \
+ GPS_MODEL_NAME_DCF600RS, \
+ GPS_MODEL_NAME_MRI, \
+ GPS_MODEL_NAME_BPE, \
+ GPS_MODEL_NAME_GLN180PEX, \
+ GPS_MODEL_NAME_N2X, \
+ GPS_MODEL_NAME_RSC180, \
+ GPS_MODEL_NAME_LNE_GB, \
+ GPS_MODEL_NAME_PPG180, \
+ GPS_MODEL_NAME_SCG \
+}
+
+
+
+/**
+ * @brief Definitions used to classify devices and built-in features
+ *
+ * @see ::GPS_MODEL_CODES
+ * @see ::GPS_BUILTIN_FEATURE_BITS
+ * @see @ref GPS_BUILTIN_FEATURE_MASKS
+ *
+ * @anchor GPS_BUILTIN_FEATURE_DEFS @{ */
+
+
+/**
+ * @brief Enumeration of classifiers and built-in features
+ *
+ * @see ::GPS_MODEL_CODES
+ * @see @ref GPS_BUILTIN_FEATURE_MASKS
+ */
+enum GPS_BUILTIN_FEATURE_BITS
+{
+ GPS_BIT_MODEL_IS_GPS,
+ GPS_BIT_MODEL_IS_GNSS,
+ GPS_BIT_MODEL_IS_TCR,
+ GPS_BIT_MODEL_IS_DCF_AM,
+ GPS_BIT_MODEL_IS_DCF_PZF,
+ GPS_BIT_MODEL_IS_MSF,
+ GPS_BIT_MODEL_IS_JJY,
+ GPS_BIT_MODEL_IS_WWV,
+
+ GPS_BIT_MODEL_IS_LNO,
+ GPS_BIT_MODEL_IS_SCU,
+
+ GPS_BIT_MODEL_HAS_BVAR_STAT,
+ GPS_BIT_MODEL_HAS_POS_XYZ,
+ GPS_BIT_MODEL_HAS_POS_LLA,
+ GPS_BIT_MODEL_HAS_TZDL,
+ GPS_BIT_MODEL_HAS_ANT_INFO,
+ GPS_BIT_MODEL_HAS_ENABLE_FLAGS,
+ GPS_BIT_MODEL_HAS_STAT_INFO,
+ GPS_BIT_MODEL_HAS_ANT_CABLE_LENGTH,
+ GPS_BIT_MODEL_HAS_GPS_IGNORE_LOCK,
+ GPS_BIT_MODEL_HAS_XMR_HOLDOVER_INTV,
+ GPS_BIT_MODEL_HAS_GNSS_MODE,
+
+ N_GPS_BIT_MODEL
+};
+
+
+
+/**
+ * @brief Bit masks associated with classifiers and built-in features
+ *
+ * @see ::GPS_MODEL_CODES
+ * @see ::GPS_BUILTIN_FEATURE_BITS
+ *
+ * @anchor GPS_BUILTIN_FEATURE_MASKS @{ */
+
+#define GPS_MODEL_IS_GPS ( 1UL << GPS_BIT_MODEL_IS_GPS ) ///< see ::GPS_BIT_MODEL_IS_GPS
+#define GPS_MODEL_IS_GNSS ( 1UL << GPS_BIT_MODEL_IS_GNSS ) ///< see ::GPS_BIT_MODEL_IS_GNSS
+#define GPS_MODEL_IS_TCR ( 1UL << GPS_BIT_MODEL_IS_TCR ) ///< see ::GPS_BIT_MODEL_IS_TCR
+#define GPS_MODEL_IS_DCF_AM ( 1UL << GPS_BIT_MODEL_IS_DCF_AM ) ///< see ::GPS_BIT_MODEL_IS_DCF_AM
+#define GPS_MODEL_IS_DCF_PZF ( 1UL << GPS_BIT_MODEL_IS_DCF_PZF ) ///< see ::GPS_BIT_MODEL_IS_DCF_PZF
+#define GPS_MODEL_IS_MSF ( 1UL << GPS_BIT_MODEL_IS_MSF ) ///< see ::GPS_BIT_MODEL_IS_MSF
+#define GPS_MODEL_IS_JJY ( 1UL << GPS_BIT_MODEL_IS_JJY ) ///< see ::GPS_BIT_MODEL_IS_JJY
+#define GPS_MODEL_IS_WWV ( 1UL << GPS_BIT_MODEL_IS_WWV ) ///< see ::GPS_BIT_MODEL_IS_WWV
+
+#define GPS_MODEL_IS_LNO ( 1UL << GPS_BIT_MODEL_IS_LNO ) ///< see ::GPS_BIT_MODEL_IS_LNO
+#define GPS_MODEL_IS_SCU ( 1UL << GPS_BIT_MODEL_IS_SCU ) ///< see ::GPS_BIT_MODEL_IS_SCU
+
+#define GPS_MODEL_HAS_BVAR_STAT ( 1UL << GPS_BIT_MODEL_HAS_BVAR_STAT ) ///< see ::GPS_BIT_MODEL_HAS_BVAR_STAT
+#define GPS_MODEL_HAS_POS_XYZ ( 1UL << GPS_BIT_MODEL_HAS_POS_XYZ ) ///< see ::GPS_BIT_MODEL_HAS_POS_XYZ
+#define GPS_MODEL_HAS_POS_LLA ( 1UL << GPS_BIT_MODEL_HAS_POS_LLA ) ///< see ::GPS_BIT_MODEL_HAS_POS_LLA
+#define GPS_MODEL_HAS_TZDL ( 1UL << GPS_BIT_MODEL_HAS_TZDL ) ///< see ::GPS_BIT_MODEL_HAS_TZDL
+#define GPS_MODEL_HAS_ANT_INFO ( 1UL << GPS_BIT_MODEL_HAS_ANT_INFO ) ///< see ::GPS_BIT_MODEL_HAS_ANT_INFO
+#define GPS_MODEL_HAS_ENABLE_FLAGS ( 1UL << GPS_BIT_MODEL_HAS_ENABLE_FLAGS ) ///< see ::GPS_BIT_MODEL_HAS_ENABLE_FLAGS
+#define GPS_MODEL_HAS_STAT_INFO ( 1UL << GPS_BIT_MODEL_HAS_STAT_INFO ) ///< see ::GPS_BIT_MODEL_HAS_STAT_INFO
+#define GPS_MODEL_HAS_ANT_CABLE_LENGTH ( 1UL << GPS_BIT_MODEL_HAS_ANT_CABLE_LENGTH ) ///< see ::GPS_BIT_MODEL_HAS_ANT_CABLE_LENGTH
+#define GPS_MODEL_HAS_GPS_IGNORE_LOCK ( 1UL << GPS_BIT_MODEL_HAS_GPS_IGNORE_LOCK ) ///< see ::GPS_BIT_MODEL_HAS_GPS_IGNORE_LOCK
+#define GPS_MODEL_HAS_XMR_HOLDOVER_INTV ( 1UL << GPS_BIT_MODEL_HAS_XMR_HOLDOVER_INTV ) ///< see ::GPS_BIT_MODEL_HAS_XMR_HOLDOVER_INTV
+
+#define GPS_MODEL_HAS_GNSS_MODE ( 1UL << GPS_BIT_MODEL_HAS_GNSS_MODE ) ///< see ::GPS_BIT_MODEL_HAS_GNSS_MODE
+
+//##+++++ TODO: should we use an extra flag?
+#define GPS_MODEL_HAS_POS ( GPS_MODEL_HAS_POS_XYZ | GPS_MODEL_HAS_POS_LLA )
+
+/** @} anchor GPS_BUILTIN_FEATURE_MASKS */
+
+
+#if 0 //##++ more potential builtin features and classifiers
+
+ GPS_MODEL_HAS_CFGH | \
+ GPS_MODEL_HAS_ALM | \
+ GPS_MODEL_HAS_EPH | \
+ GPS_MODEL_HAS_UTC | \
+ GPS_MODEL_HAS_IONO \
+
+#define GPS_MODEL_HAS_AUTO_ON // --
+#define GPS_MODEL_HAS_AUTO_OFF // --
+#define GPS_MODEL_HAS_SW_REV // deprecated, use only if ri not supported
+#define GPS_MODEL_HAS_BVAR_STAT // req
+#define GPS_MODEL_HAS_TIME // ?
+#define GPS_MODEL_HAS_POS_XYZ // GPS_MODEL_IS_GPS, GPS_MODEL_HAS_POS, GPS_MODEL_HAS_POS_XYZ ?
+#define GPS_MODEL_HAS_POS_LLA // GPS_MODEL_IS_GPS, GPS_MODEL_HAS_POS, GPS_MODEL_HAS_POS_LLA ?
+#define GPS_MODEL_HAS_TZDL // req
+#define GPS_MODEL_HAS_PORT_PARM // deprecated, use only if ri not supported
+#define GPS_MODEL_HAS_SYNTH // ri GPS_HAS_SYNTH
+#define GPS_MODEL_HAS_ANT_INFO // GPS_MODEL_IS_GPS, also GNSS, or req?
+#define GPS_MODEL_HAS_UCAP // ri n_ucap
+#define GPS_MODEL_HAS_ENABLE_FLAGS // req
+#define GPS_MODEL_HAS_STAT_INFO // req
+#define GPS_MODEL_HAS_SWITCH_PARMS // deprecated, use ...
+#define GPS_MODEL_HAS_STRING_PARMS // deprecated, use ...
+#define GPS_MODEL_HAS_ANT_CABLE_LENGTH // GPS_MODEL_IS_GPS, also GNSS, or req?
+#define GPS_MODEL_HAS_SYNC_OUTAGE_DELAY // custom
+#define GPS_MODEL_HAS_PULSE_INFO // custom
+#define GPS_MODEL_HAS_OPT_FEATURES // deprecated, use ri
+#define GPS_MODEL_HAS_IRIG_TX_SETTINGS // ri GPS_HAS_IRIG_TX
+#define GPS_MODEL_HAS_RECEIVER_INFO // --
+#define GPS_MODEL_HAS_STR_TYPE_INFO_IDX // ri n_str_type
+#define GPS_MODEL_HAS_PORT_INFO_IDX // ri n_com
+#define GPS_MODEL_HAS_PORT_SETTINGS_IDX // ri n_com
+#define GPS_MODEL_HAS_POUT_INFO_IDX // ri n_pout
+#define GPS_MODEL_HAS_POUT_SETTINGS_IDX // ri n_pout
+#define GPS_MODEL_HAS_IRIG_TX_INFO // ri GPS_HAS_IRIG_TX
+#define GPS_MODEL_HAS_MULTI_REF_SETTINGS // ri GPS_HAS_MULTI_REF
+#define GPS_MODEL_HAS_MULTI_REF_INFO // ri GPS_HAS_MULTI_REF
+#define GPS_MODEL_HAS_ROM_CSUM // ?
+#define GPS_MODEL_HAS_MULTI_REF_STATUS // ri ...
+#define GPS_MODEL_HAS_RCV_TIMEOUT // ri ...
+#define GPS_MODEL_HAS_IGNORE_LOCK // ?
+#define GPS_MODEL_HAS_IRIG_RX_SETTINGS // ri ...
+#define GPS_MODEL_HAS_IRIG_RX_INFO // ri ...
+#define GPS_MODEL_HAS_REF_OFFS // ri ...
+#define GPS_MODEL_HAS_DEBUG_STATUS //
+#define GPS_MODEL_HAS_XMR_SETTINGS_IDX //
+#define GPS_MODEL_HAS_XMR_INFO_IDX //
+#define GPS_MODEL_HAS_XMR_STATUS_IDX //
+#define GPS_MODEL_HAS_OPT_SETTINGS //
+#define GPS_MODEL_HAS_OPT_INFO //
+#define GPS_MODEL_HAS_CLR_UCAP_BUFF //
+#define GPS_MODEL_HAS_TIME_SCALE //
+#define GPS_MODEL_HAS_NAV_ENG_SETTINGS //
+#define GPS_MODEL_HAS_RAW_IRIG_DATA //
+#define GPS_MODEL_HAS_GPIO_CFG_LIMITS //
+#define GPS_MODEL_HAS_GPIO_INFO_IDX //
+#define GPS_MODEL_HAS_GPIO_SETTINGS_IDX //
+#define GPS_MODEL_HAS_XMR_INSTANCES //
+#define GPS_MODEL_HAS_CLR_EVT_LOG //
+#define GPS_MODEL_HAS_NUM_EVT_LOG_ENTRIES //
+#define GPS_MODEL_HAS_FIRST_EVT_LOG_ENTRY //
+#define GPS_MODEL_HAS_NEXT_EVT_LOG_ENTRY //
+#define GPS_MODEL_HAS_LNO_STATUS //
+#define GPS_MODEL_HAS_IMS_STATE //
+#define GPS_MODEL_HAS_IMS_SENSOR_STATE_IDX //
+#define GPS_MODEL_HAS_XMR_HOLDOVER_INTV //
+#define GPS_MODEL_HAS_HAVEQUICK_RX_SETTINGS //
+#define GPS_MODEL_HAS_HAVEQUICK_RX_INFO //
+#define GPS_MODEL_HAS_HAVEQUICK_TX_SETTINGS //
+#define GPS_MODEL_HAS_HAVEQUICK_TX_INFO //
+#define GPS_MODEL_HAS_PTP_CFG //
+#define GPS_MODEL_HAS_PTP_STATE //
+#define GPS_MODEL_HAS_PTP_UC_MASTER_CFG_LIMITS //
+#define GPS_MODEL_HAS_PTP_UC_MASTER_CFG //
+#define GPS_MODEL_HAS_NTP_GLB_CFG //
+#define GPS_MODEL_HAS_NTP_CLNT_MODE_CFG //
+#define GPS_MODEL_HAS_NTP_SRV_MODE_CFG //
+#define GPS_MODEL_HAS_NTP_PEER_SETTINGS_IDX //
+#define GPS_MODEL_HAS_NTP_SYS_STATE //
+#define GPS_MODEL_HAS_NTP_PEER_STATE_IDX //
+#define GPS_MODEL_HAS_SHS //
+#define GPS_MODEL_HAS_SHS_STATUS //
+#define GPS_MODEL_HAS_NET_GLB_CFG //
+#define GPS_MODEL_HAS_NET_DNS_SRVR //
+#define GPS_MODEL_HAS_NET_DNS_SRC_DOM //
+#define GPS_MODEL_HAS_NET_STAT_DNS_SRVR //
+#define GPS_MODEL_HAS_NET_STAT_DNS_SRC_DOM //
+#define GPS_MODEL_HAS_GNSS_SAT_INFO_IDX //
+
+#define GPS_MODEL_HAS_CFGH //
+#define GPS_MODEL_HAS_ALM //
+#define GPS_MODEL_HAS_EPH //
+#define GPS_MODEL_HAS_UTC //
+#define GPS_MODEL_HAS_IONO //
+#define GPS_MODEL_HAS_ASCII_MSG //
+
+#define GPS_MODEL_HAS_GLNS_ALM //
+#define GPS_MODEL_HAS_GNSS_SAT_INFO //
+#define GPS_MODEL_HAS_GNSS_MODE //
+
+#define GPS_MODEL_HAS_IP4_SETTINGS //
+#define GPS_MODEL_HAS_LAN_IF_INFO //
+#define GPS_MODEL_HAS_IP4_STATE //
+
+#define GPS_MODEL_HAS_SCU_STAT //
+
+#define GPS_MODEL_HAS_CRYPTED_PACKET //
+#define GPS_MODEL_HAS_CRYPTED_RAW_PACKET //
+
+#define GPS_MODEL_HAS_SECU_INFO //
+#define GPS_MODEL_HAS_SECU_SETTINGS //
+#define GPS_MODEL_HAS_SECU_PUBLIC_KEY //
+
+#endif //##++ more potential builtin features and classifiers
+
+
+
+/**
+ * @brief Common builtin features of all GPS receivers
+ */
+#define BUILTIN_FEAT_GPS \
+( \
+ GPS_MODEL_IS_GPS | \
+ GPS_MODEL_HAS_BVAR_STAT | \
+ GPS_MODEL_HAS_POS_XYZ | \
+ GPS_MODEL_HAS_POS_LLA | \
+ GPS_MODEL_HAS_TZDL | \
+ GPS_MODEL_HAS_ANT_INFO | \
+ GPS_MODEL_HAS_ENABLE_FLAGS | \
+ GPS_MODEL_HAS_STAT_INFO | \
+ GPS_MODEL_HAS_ANT_CABLE_LENGTH \
+)
+
+
+/**
+ * @brief Common builtin features of all GNSS receivers
+ *
+ * GNSS includes GPS but optionally other satellite systems,
+ * and the associated API.
+ */
+#define BUILTIN_FEAT_GNSS \
+( \
+ BUILTIN_FEAT_GPS | \
+ GPS_MODEL_IS_GNSS | \
+ GPS_MODEL_HAS_GNSS_MODE \
+)
+
+
+
+/**
+ * @brief Definitions of builtin features per device type
+ *
+ * @see ::GPS_MODEL_CODES
+ * @see @ref GPS_MODEL_BUILTIN_FEATURES
+ *
+ * @anchor GPS_MODEL_BUILTIN_FEATURE_MASKS @{ */
+
+#define BUILTIN_FEAT_GPS166 ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_GPS167 ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_GPS167SV ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_GPS167PC ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_GPS167PCI ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_GPS163 ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_GPS168PCI ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_GPS161 ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_GPS169PCI ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_TCR167PCI ( 0 )
+#define BUILTIN_FEAT_GPS164 ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_GPS170PCI ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_PZF511 ( 0 )
+#define BUILTIN_FEAT_GPS170 ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_TCR511 ( 0 )
+#define BUILTIN_FEAT_AM511 ( 0 )
+#define BUILTIN_FEAT_MSF511 ( 0 )
+#define BUILTIN_FEAT_GRC170 ( 0 )
+#define BUILTIN_FEAT_GPS170PEX ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_GPS162 ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_PTP270PEX ( 0 )
+#define BUILTIN_FEAT_FRC511PEX ( 0 )
+#define BUILTIN_FEAT_GEN170 ( 0 )
+#define BUILTIN_FEAT_TCR170PEX ( 0 )
+#define BUILTIN_FEAT_WWVB511 ( 0 )
+#define BUILTIN_FEAT_MGR170 ( 0 )
+#define BUILTIN_FEAT_JJY511 ( 0 )
+#define BUILTIN_FEAT_PZF600 ( 0 )
+#define BUILTIN_FEAT_TCR600 ( 0 )
+#define BUILTIN_FEAT_GPS180 ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_GLN170 ( 0 )
+#define BUILTIN_FEAT_GPS180PEX ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_TCR180PEX ( 0 )
+#define BUILTIN_FEAT_PZF180PEX ( 0 )
+#define BUILTIN_FEAT_MGR180 ( 0 )
+#define BUILTIN_FEAT_MSF600 ( 0 )
+#define BUILTIN_FEAT_WWVB600 ( 0 )
+#define BUILTIN_FEAT_JJY600 ( 0 )
+#define BUILTIN_FEAT_GPS180HS ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_GPS180AMC ( BUILTIN_FEAT_GPS )
+#define BUILTIN_FEAT_ESI180 ( 0 )
+#define BUILTIN_FEAT_CPE180 ( 0 )
+#define BUILTIN_FEAT_LNO180 ( 0 )
+#define BUILTIN_FEAT_GRC180 ( 0 )
+#define BUILTIN_FEAT_LIU ( 0 )
+#define BUILTIN_FEAT_DCF600HS ( 0 )
+#define BUILTIN_FEAT_DCF600RS ( 0 )
+#define BUILTIN_FEAT_MRI ( 0 )
+#define BUILTIN_FEAT_BPE ( 0 )
+#define BUILTIN_FEAT_GLN180PEX ( BUILTIN_FEAT_GNSS )
+#define BUILTIN_FEAT_N2X ( 0 )
+#define BUILTIN_FEAT_RSC180 ( 0 )
+#define BUILTIN_FEAT_LNE_GB ( 0 )
+#define BUILTIN_FEAT_PPG180 ( 0 )
+#define BUILTIN_FEAT_SCG ( 0 )
+
+/** @} anchor GPS_MODEL_BUILTIN_FEATURE_MASKS */
+
+
+
+/**
+ * @brief Initializer for a table of built-in features per device
+ *
+ * Last entry is all zero to indicated end of table.
+ *
+ * @see ::GPS_MODEL_CODES
+ * @see @ref GPS_MODEL_BUILTIN_FEATURE_MASKS
+ */
+#define GPS_MODEL_BUILTIN_FEATURES \
+{ \
+ { GPS_MODEL_GPS166, BUILTIN_FEAT_GPS166 }, \
+ { GPS_MODEL_GPS167, BUILTIN_FEAT_GPS167 }, \
+ { GPS_MODEL_GPS167SV, BUILTIN_FEAT_GPS167SV }, \
+ { GPS_MODEL_GPS167PC, BUILTIN_FEAT_GPS167PC }, \
+ { GPS_MODEL_GPS167PCI, BUILTIN_FEAT_GPS167PCI }, \
+ { GPS_MODEL_GPS163, BUILTIN_FEAT_GPS163 }, \
+ { GPS_MODEL_GPS168PCI, BUILTIN_FEAT_GPS168PCI }, \
+ { GPS_MODEL_GPS161, BUILTIN_FEAT_GPS161 }, \
+ { GPS_MODEL_GPS169PCI, BUILTIN_FEAT_GPS169PCI }, \
+ { GPS_MODEL_TCR167PCI, BUILTIN_FEAT_TCR167PCI }, \
+ { GPS_MODEL_GPS164, BUILTIN_FEAT_GPS164 }, \
+ { GPS_MODEL_GPS170PCI, BUILTIN_FEAT_GPS170PCI }, \
+ { GPS_MODEL_PZF511, BUILTIN_FEAT_PZF511 }, \
+ { GPS_MODEL_GPS170, BUILTIN_FEAT_GPS170 }, \
+ { GPS_MODEL_TCR511, BUILTIN_FEAT_TCR511 }, \
+ { GPS_MODEL_AM511, BUILTIN_FEAT_AM511 }, \
+ { GPS_MODEL_MSF511, BUILTIN_FEAT_MSF511 }, \
+ { GPS_MODEL_GRC170, BUILTIN_FEAT_GRC170 }, \
+ { GPS_MODEL_GPS170PEX, BUILTIN_FEAT_GPS170PEX }, \
+ { GPS_MODEL_GPS162, BUILTIN_FEAT_GPS162 }, \
+ { GPS_MODEL_PTP270PEX, BUILTIN_FEAT_PTP270PEX }, \
+ { GPS_MODEL_FRC511PEX, BUILTIN_FEAT_FRC511PEX }, \
+ { GPS_MODEL_GEN170, BUILTIN_FEAT_GEN170 }, \
+ { GPS_MODEL_TCR170PEX, BUILTIN_FEAT_TCR170PEX }, \
+ { GPS_MODEL_WWVB511, BUILTIN_FEAT_WWVB511 }, \
+ { GPS_MODEL_MGR170, BUILTIN_FEAT_MGR170 }, \
+ { GPS_MODEL_JJY511, BUILTIN_FEAT_JJY511 }, \
+ { GPS_MODEL_PZF600, BUILTIN_FEAT_PZF600 }, \
+ { GPS_MODEL_TCR600, BUILTIN_FEAT_TCR600 }, \
+ { GPS_MODEL_GPS180, BUILTIN_FEAT_GPS180 }, \
+ { GPS_MODEL_GLN170, BUILTIN_FEAT_GLN170 }, \
+ { GPS_MODEL_GPS180PEX, BUILTIN_FEAT_GPS180PEX }, \
+ { GPS_MODEL_TCR180PEX, BUILTIN_FEAT_TCR180PEX }, \
+ { GPS_MODEL_PZF180PEX, BUILTIN_FEAT_PZF180PEX }, \
+ { GPS_MODEL_MGR180, BUILTIN_FEAT_MGR180 }, \
+ { GPS_MODEL_MSF600, BUILTIN_FEAT_MSF600 }, \
+ { GPS_MODEL_WWVB600, BUILTIN_FEAT_WWVB600 }, \
+ { GPS_MODEL_JJY600, BUILTIN_FEAT_JJY600 }, \
+ { GPS_MODEL_GPS180HS, BUILTIN_FEAT_GPS180HS }, \
+ { GPS_MODEL_GPS180AMC, BUILTIN_FEAT_GPS180AMC }, \
+ { GPS_MODEL_ESI180, BUILTIN_FEAT_ESI180 }, \
+ { GPS_MODEL_CPE180, BUILTIN_FEAT_CPE180 }, \
+ { GPS_MODEL_LNO180, BUILTIN_FEAT_LNO180 }, \
+ { GPS_MODEL_GRC180, BUILTIN_FEAT_GRC180 }, \
+ { GPS_MODEL_LIU, BUILTIN_FEAT_LIU }, \
+ { GPS_MODEL_DCF600HS, BUILTIN_FEAT_DCF600HS }, \
+ { GPS_MODEL_DCF600RS, BUILTIN_FEAT_DCF600RS }, \
+ { GPS_MODEL_MRI, BUILTIN_FEAT_MRI }, \
+ { GPS_MODEL_BPE, BUILTIN_FEAT_BPE }, \
+ { GPS_MODEL_GLN180PEX, BUILTIN_FEAT_GLN180PEX }, \
+ { GPS_MODEL_N2X, BUILTIN_FEAT_N2X }, \
+ { GPS_MODEL_RSC180, BUILTIN_FEAT_RSC180 }, \
+ { GPS_MODEL_LNE_GB, BUILTIN_FEAT_LNE_GB }, \
+ { GPS_MODEL_PPG180, BUILTIN_FEAT_PPG180 }, \
+ { GPS_MODEL_SCG, BUILTIN_FEAT_SCG }, \
+ { 0, 0 } \
}
+/** @} anchor GPS_BUILTIN_FEATURE_DEFS */
+
+
/*
* The macros below can be used to classify a receiver,
@@ -781,11 +1381,11 @@ enum
#define _mbg_rcvr_is_plug_in( _p_ri ) \
( strstr( (_p_ri)->model_name, "PC" ) || \
- ( strstr( (_p_ri)->model_name, "PEX" ) )
+ strstr( (_p_ri)->model_name, "PEX" ) )
#define _mbg_rcvr_is_gps( _p_ri ) \
( strstr( (_p_ri)->model_name, "GPS" ) || \
- ( strstr( (_p_ri)->model_name, "MGR" ) )
+ strstr( (_p_ri)->model_name, "MGR" ) )
#define _mbg_rcvr_is_mobile_gps( _p_ri ) \
( strstr( (_p_ri)->model_name, "MGR" ) )
@@ -835,7 +1435,7 @@ enum
#define _mbg_rcvr_is_glonass( _p_ri ) \
( strstr( (_p_ri)->model_name, "GRC" ) || \
- ( strstr( (_p_ri)->model_name, "GLN" ) )
+ strstr( (_p_ri)->model_name, "GLN" ) )
#define _mbg_rcvr_is_glonass_plug_in( _p_ri ) \
( _mbg_rcvr_is_glonass( _p_ri ) && \
@@ -849,13 +1449,17 @@ enum
_mbg_rcvr_is_plug_in( _p_ri ) )
+
/**
- * The classification codes for oscillators below
- * are used with RECEIVER_INFO.osc_type. New codes
- * must be appended to the enumeration, so the sequence
- * of codes does NOT reflect the order of quality:
+ * @brief Known oscillator types used with ::RECEIVER_INFO::osc_type
+ *
+ * The sequence of codes does NOT reflect the order of quality.
+ * New oscillator type codes will just be appended to the enumeration.
+ *
+ * @see ::DEFAULT_GPS_OSC_NAMES
+ * @see ::DEFAULT_GPS_OSC_QUALITY_IDX
*/
-enum
+enum GPS_OSC_TYPES
{
GPS_OSC_UNKNOWN,
GPS_OSC_TCXO_LQ,
@@ -867,14 +1471,19 @@ enum
GPS_OSC_RUBIDIUM,
GPS_OSC_TCXO_MQ,
GPS_OSC_OCXO_DHQ,
+ GPS_OSC_OCXO_SQ,
N_GPS_OSC
};
-/*
- * The sequence and number of oscillator names
- * listed below must correspond to the enumeration
- * above:
+/**
+ * @brief Oscillator type name string initializer
+ *
+ * The sequence and number of oscillator names has to
+ * correspond to the enumeration in ::GPS_OSC_TYPES
+ *
+ * @see ::GPS_OSC_TYPES
+ * @see ::DEFAULT_GPS_OSC_QUALITY_IDX
*/
#define DEFAULT_GPS_OSC_NAMES \
{ \
@@ -887,15 +1496,21 @@ enum
"OCXO XHQ", \
"RUBIDIUM", \
"TCXO MQ", \
- "OCXO DHQ" \
+ "OCXO DHQ", \
+ "OCXO SQ" \
}
-/*
- * The initializer below can be used to initialize
- * an array (e.g. "int osc_quality_idx[N_GPS_OSC]")
- * which allows to display the oscillator types
- * ordered by quality:
+/**
+ * @brief Oscillator quality index
+ *
+ * Can be used to initialize a index array
+ * (e.g. "int osc_quality_idx[N_GPS_OSC];")
+ * allowing to display the oscillator types
+ * ordered by quality
+ *
+ * @see ::GPS_OSC_TYPES
+ * @see ::DEFAULT_GPS_OSC_NAMES
*/
#define DEFAULT_GPS_OSC_QUALITY_IDX \
{ \
@@ -904,6 +1519,7 @@ enum
GPS_OSC_TCXO_MQ, \
GPS_OSC_TCXO_HQ, \
GPS_OSC_OCXO_LQ, \
+ GPS_OSC_OCXO_SQ, \
GPS_OSC_OCXO_MQ, \
GPS_OSC_OCXO_HQ, \
GPS_OSC_OCXO_DHQ, \
@@ -913,50 +1529,60 @@ enum
-/*
- * Codes to be used with RECEIVER_INFO.osc_flags
- * are not yet used/required, so they are reserved
- * for future use.
- */
-
-
/**
- * The codes below enumerate some features which may be
- * supported by a given clock, or not.
- */
-enum
-{
- GPS_FEAT_PPS, /**< has pulse per second output */
- GPS_FEAT_PPM, /**< has pulse per minute output */
- GPS_FEAT_SYNTH, /**< has programmable synthesizer output */
- GPS_FEAT_DCFMARKS, /**< has DCF77 compatible time mark output */
- GPS_FEAT_IRIG_TX, /**< has on-board IRIG output */
- GPS_FEAT_IRIG_RX, /**< has on-board IRIG input */
- GPS_FEAT_LAN_IP4, /**< has LAN IPv4 interface */
- GPS_FEAT_MULTI_REF, /**< has multiple input sources with priorities */
-
- GPS_FEAT_RCV_TIMEOUT, /**< timeout after GPS reception has stopped */
- GPS_FEAT_IGNORE_LOCK, /**< supports "ignore lock", MBG_OPT_BIT_EMU_SYNC can be set alternatively */
- GPS_FEAT_5_MHZ, /**< output 5 MHz rather than 100 kHz */
- GPS_FEAT_XMULTI_REF, /**< has extended multiple input source configuration */
- GPS_FEAT_OPT_SETTINGS, /**< supports MBG_OPT_SETTINGS */
- GPS_FEAT_TIME_SCALE, /**< supports configurable time scale (UTC, TAI, GPS, ...) */
- GPS_FEAT_IRIG_CTRL_BITS, /**< supports IRIG control bits */
- GPS_FEAT_PTP, /**< has PTP support */
-
- GPS_FEAT_NAV_ENGINE_SETTINGS, /**< supports navigation engine configuration */
- GPS_FEAT_RAW_IRIG_DATA, /**< supports reading raw IRIG input data */
- GPS_FEAT_RAW_IRIG_TIME, /**< supports reading decoded IRIG time */
- GPS_FEAT_PTP_UNICAST, /**< has PTP Unicast support */
- GPS_FEAT_GPIO, /**< has general purpose in/outputs */
- GPS_FEAT_XMRS_MULT_INSTC, /**< multiple XMRS instances of the same ref type supported, @see XMRSF_BIT_MULT_INSTC_SUPP */
- GPS_FEAT_10MHZ_DISBD, /**< 10 MHz output is always disabled */
- GPS_FEAT_EVT_LOG, /**< Event logging supported */
-
- N_GPS_FEATURE /**< the number of valid features */
+ * @brief Enumeration of device features flags reported in ::RECEIVER_INFO::features
+ *
+ * Each flags indicates if a device supports the associated feature.
+ */
+enum GPS_FEATURE_BITS
+{
+ GPS_FEAT_PPS, ///< has pulse per second output
+ GPS_FEAT_PPM, ///< has pulse per minute output
+ GPS_FEAT_SYNTH, ///< has programmable synthesizer output
+ GPS_FEAT_DCFMARKS, ///< has DCF77 compatible time mark output
+ GPS_FEAT_IRIG_TX, ///< has on-board IRIG output
+ GPS_FEAT_IRIG_RX, ///< has on-board IRIG input
+ GPS_FEAT_LAN_IP4, ///< has simple LAN IPv4 interface, superseded by ::GPS_FEAT_NET_CFG
+ GPS_FEAT_MULTI_REF, ///< has multiple input sources with priorities, superseded by ::GPS_FEAT_XMULTI_REF
+
+ GPS_FEAT_RCV_TIMEOUT, ///< timeout after GPS reception has stopped
+ GPS_FEAT_IGNORE_LOCK, ///< supports "ignore lock", ::MBG_OPT_BIT_EMU_SYNC can be set alternatively
+ GPS_FEAT_5_MHZ, ///< output 5 MHz rather than 100 kHz
+ GPS_FEAT_XMULTI_REF, ///< has extended multiple input source configuration, supersedes ::GPS_FEAT_MULTI_REF
+ GPS_FEAT_OPT_SETTINGS, ///< supports ::MBG_OPT_SETTINGS
+ GPS_FEAT_TIME_SCALE, ///< supports configurable time scale (%UTC, TAI, GPS, ...)
+ GPS_FEAT_IRIG_CTRL_BITS, ///< supports IRIG control bits (::MBG_IRIG_CTRL_BITS)
+ GPS_FEAT_PTP, ///< has PTP support
+
+ GPS_FEAT_NAV_ENGINE_SETTINGS, ///< supports navigation engine configuration
+ GPS_FEAT_RAW_IRIG_DATA, ///< supports reading raw IRIG input data (::MBG_RAW_IRIG_DATA)
+ GPS_FEAT_RAW_IRIG_TIME, ///< supports reading decoded IRIG time (::PCPS_IRIG_TIME)
+ GPS_FEAT_PTP_UNICAST, ///< has PTP Unicast support
+ GPS_FEAT_GPIO, ///< has general purpose inputs/outputs
+ GPS_FEAT_XMRS_MULT_INSTC, ///< multiple XMRS instances of the same ref type supported (::XMULTI_REF_INSTANCES)
+ GPS_FEAT_10MHZ_DISBD, ///< 10 MHz output is always disabled
+ GPS_FEAT_EVT_LOG, ///< Event logging supported
+
+ GPS_FEAT_IMS, ///< supports IMS data structures
+ GPS_FEAT_HAVEQUICK, ///< supports HaveQuick structures
+ GPS_FEAT_NTP, ///< supports NTP structures
+ GPS_FEAT_NET_CFG, ///< supports extended network interface configuration, supersedes ::GPS_FEAT_LAN_IP4
+ GPS_FEAT_VST, ///< supports VST (Versatile Storage) API and structures
+ GPS_FEAT_SHS, ///< supports SHS (Secure Hybrid System) API and structures
+
+ N_GPS_FEATURE ///< the number of valid features
+ /*
+ * If new features are added then care must be taken to update the associated
+ * definitions below accordingly, e.g. string initializers and bit masks.
+ */
};
+/**
+ * @brief Names of device features
+ *
+ * @see ::GPS_FEATURE_BITS
+ */
#define DEFAULT_GPS_FEATURE_NAMES \
{ \
"Pulse Per Second", \
@@ -982,40 +1608,63 @@ enum
"General Purpose I/O", \
"Multiple XMRS Instances", \
"10 MHz Output Disabled", \
- "Event Logging" \
+ "Event Logging", \
+ "IMS data", \
+ "HaveQuick", \
+ "NTP", \
+ "Ext. Network Config", \
+ "Versatile Storage", \
+ "SHS" \
}
-/*
- * Bit masks used with RECEIVER_INFO.features
- * (others are reserved):
- */
-#define GPS_HAS_PPS ( 1UL << GPS_FEAT_PPS )
-#define GPS_HAS_PPM ( 1UL << GPS_FEAT_PPM )
-#define GPS_HAS_SYNTH ( 1UL << GPS_FEAT_SYNTH )
-#define GPS_HAS_DCFMARKS ( 1UL << GPS_FEAT_DCFMARKS )
-#define GPS_HAS_IRIG_TX ( 1UL << GPS_FEAT_IRIG_TX )
-#define GPS_HAS_IRIG_RX ( 1UL << GPS_FEAT_IRIG_RX )
-#define GPS_HAS_LAN_IP4 ( 1UL << GPS_FEAT_LAN_IP4 )
-#define GPS_HAS_MULTI_REF ( 1UL << GPS_FEAT_MULTI_REF )
-#define GPS_HAS_RCV_TIMEOUT ( 1UL << GPS_FEAT_RCV_TIMEOUT )
-#define GPS_HAS_IGNORE_LOCK ( 1UL << GPS_FEAT_IGNORE_LOCK )
-#define GPS_HAS_5_MHZ ( 1UL << GPS_FEAT_5_MHZ )
-#define GPS_HAS_XMULTI_REF ( 1UL << GPS_FEAT_XMULTI_REF )
-#define GPS_HAS_OPT_SETTINGS ( 1UL << GPS_FEAT_OPT_SETTINGS )
-#define GPS_HAS_TIME_SCALE ( 1UL << GPS_FEAT_TIME_SCALE )
-#define GPS_HAS_IRIG_CTRL_BITS ( 1UL << GPS_FEAT_IRIG_CTRL_BITS )
-#define GPS_HAS_PTP ( 1UL << GPS_FEAT_PTP )
-#define GPS_HAS_NAV_ENGINE_SETTINGS ( 1UL << GPS_FEAT_NAV_ENGINE_SETTINGS )
-#define GPS_HAS_RAW_IRIG_DATA ( 1UL << GPS_FEAT_RAW_IRIG_DATA )
-#define GPS_HAS_RAW_IRIG_TIME ( 1UL << GPS_FEAT_RAW_IRIG_TIME )
-#define GPS_HAS_PTP_UNICAST ( 1UL << GPS_FEAT_PTP_UNICAST )
-#define GPS_HAS_GPIO ( 1UL << GPS_FEAT_GPIO )
-#define GPS_HAS_XMRS_MULT_INSTC ( 1UL << GPS_FEAT_XMRS_MULT_INSTC )
-#define GPS_HAS_10MHZ_DISBD ( 1UL << GPS_FEAT_10MHZ_DISBD )
-#define GPS_HAS_EVT_LOG ( 1UL << GPS_FEAT_EVT_LOG )
-
-#define GPS_HAS_REF_OFFS GPS_HAS_IRIG_RX
+/**
+ * @brief Bit masks used with ::RECEIVER_INFO::features
+ *
+ * @see ::GPS_FEATURE_BITS
+ *
+ * @anchor GPS_FEATURE_MASKS @{ */
+
+#define GPS_HAS_PPS ( 1UL << GPS_FEAT_PPS ) ///< see ::GPS_FEAT_PPS
+#define GPS_HAS_PPM ( 1UL << GPS_FEAT_PPM ) ///< see ::GPS_FEAT_PPM
+#define GPS_HAS_SYNTH ( 1UL << GPS_FEAT_SYNTH ) ///< see ::GPS_FEAT_SYNTH
+#define GPS_HAS_DCFMARKS ( 1UL << GPS_FEAT_DCFMARKS ) ///< see ::GPS_FEAT_DCFMARKS
+#define GPS_HAS_IRIG_TX ( 1UL << GPS_FEAT_IRIG_TX ) ///< see ::GPS_FEAT_IRIG_TX
+#define GPS_HAS_IRIG_RX ( 1UL << GPS_FEAT_IRIG_RX ) ///< see ::GPS_FEAT_IRIG_RX
+#define GPS_HAS_LAN_IP4 ( 1UL << GPS_FEAT_LAN_IP4 ) ///< see ::GPS_FEAT_LAN_IP4
+#define GPS_HAS_MULTI_REF ( 1UL << GPS_FEAT_MULTI_REF ) ///< see ::GPS_FEAT_MULTI_REF
+
+#define GPS_HAS_RCV_TIMEOUT ( 1UL << GPS_FEAT_RCV_TIMEOUT ) ///< see ::GPS_FEAT_RCV_TIMEOUT
+#define GPS_HAS_IGNORE_LOCK ( 1UL << GPS_FEAT_IGNORE_LOCK ) ///< see ::GPS_FEAT_IGNORE_LOCK
+#define GPS_HAS_5_MHZ ( 1UL << GPS_FEAT_5_MHZ ) ///< see ::GPS_FEAT_5_MHZ
+#define GPS_HAS_XMULTI_REF ( 1UL << GPS_FEAT_XMULTI_REF ) ///< see ::GPS_FEAT_XMULTI_REF
+#define GPS_HAS_OPT_SETTINGS ( 1UL << GPS_FEAT_OPT_SETTINGS ) ///< see ::GPS_FEAT_OPT_SETTINGS
+#define GPS_HAS_TIME_SCALE ( 1UL << GPS_FEAT_TIME_SCALE ) ///< see ::GPS_FEAT_TIME_SCALE
+#define GPS_HAS_IRIG_CTRL_BITS ( 1UL << GPS_FEAT_IRIG_CTRL_BITS ) ///< see ::GPS_FEAT_IRIG_CTRL_BITS
+#define GPS_HAS_PTP ( 1UL << GPS_FEAT_PTP ) ///< see ::GPS_FEAT_PTP
+
+#define GPS_HAS_NAV_ENGINE_SETTINGS ( 1UL << GPS_FEAT_NAV_ENGINE_SETTINGS ) ///< see ::GPS_FEAT_NAV_ENGINE_SETTINGS
+#define GPS_HAS_RAW_IRIG_DATA ( 1UL << GPS_FEAT_RAW_IRIG_DATA ) ///< see ::GPS_FEAT_RAW_IRIG_DATA
+#define GPS_HAS_RAW_IRIG_TIME ( 1UL << GPS_FEAT_RAW_IRIG_TIME ) ///< see ::GPS_FEAT_RAW_IRIG_TIME
+#define GPS_HAS_PTP_UNICAST ( 1UL << GPS_FEAT_PTP_UNICAST ) ///< see ::GPS_FEAT_PTP_UNICAST
+#define GPS_HAS_GPIO ( 1UL << GPS_FEAT_GPIO ) ///< see ::GPS_FEAT_GPIO
+#define GPS_HAS_XMRS_MULT_INSTC ( 1UL << GPS_FEAT_XMRS_MULT_INSTC ) ///< see ::GPS_FEAT_XMRS_MULT_INSTC
+#define GPS_HAS_10MHZ_DISBD ( 1UL << GPS_FEAT_10MHZ_DISBD ) ///< see ::GPS_FEAT_10MHZ_DISBD
+#define GPS_HAS_EVT_LOG ( 1UL << GPS_FEAT_EVT_LOG ) ///< see ::GPS_FEAT_EVT_LOG
+
+#define GPS_HAS_IMS ( 1UL << GPS_FEAT_IMS ) ///< see ::GPS_FEAT_IMS
+#define GPS_HAS_HAVEQUICK ( 1UL << GPS_FEAT_HAVEQUICK ) ///< see ::GPS_FEAT_HAVEQUICK
+#define GPS_HAS_NTP ( 1UL << GPS_FEAT_NTP ) ///< see ::GPS_FEAT_NTP
+#define GPS_HAS_NET_CFG ( 1UL << GPS_FEAT_NET_CFG ) ///< see ::GPS_FEAT_NET_CFG
+#define GPS_HAS_VST ( 1UL << GPS_FEAT_VST ) ///< see ::GPS_FEAT_VST
+#define GPS_HAS_SHS ( 1UL << GPS_FEAT_SHS ) ///< see ::GPS_FEAT_SHS
+
+
+// the next ones are special since they just shadow another flag:
+#define GPS_HAS_REF_OFFS GPS_HAS_IRIG_RX ///< always supported with IRIG inputs, see ::GPS_HAS_IRIG_RX
+#define GPS_HAS_DEBUG_STATUS GPS_HAS_IRIG_RX ///< always supported with IRIG inputs, see ::GPS_HAS_IRIG_RX
+
+/** @} anchor GPS_FEATURE_MASKS */
/*
@@ -1031,17 +1680,32 @@ enum
}
-/*
- * Codes to be used with RECEIVER_INFO::flags:
+/**
+ * @brief Bits used to define ::RECEIVER_INFO_FLAG_MASKS
+ */
+enum RECEIVER_INFO_FLAG_BITS
+{
+ GPS_BIT_OSC_CFG_SUPP, ///< oscillator cfg is supported, see ::RECEIVER_INFO::osc_type
+ GPS_BIT_IRIG_FO_IN, ///< IRIG input via fiber optics
+ GPS_BIT_HAS_FPGA, ///< device provides on-board FPGA
+ N_RECEIVER_INFO_FLAG_BITS ///< number of known bits
+};
+
+
+/**
+ * @brief Bit masks to be used with ::RECEIVER_INFO::flags
*/
-#define GPS_OSC_CFG_SUPP 0x0001 // GPS_OSC_CFG supported
-#define GPS_IRIG_FO_IN 0x0002 // IRIG input via fiber optics
-#define GPS_HAS_FPGA 0x0004 // device provides on-board FPGA
+enum RECEIVER_INFO_FLAG_MASKS
+{
+ GPS_OSC_CFG_SUPP = ( 1UL << GPS_BIT_OSC_CFG_SUPP ), ///< see ::GPS_BIT_OSC_CFG_SUPP
+ GPS_IRIG_FO_IN = ( 1UL << GPS_BIT_IRIG_FO_IN ), ///< see ::GPS_BIT_IRIG_FO_IN
+ GPS_HAS_FPGA = ( 1UL << GPS_BIT_HAS_FPGA ) ///< see ::GPS_BIT_HAS_FPGA
+};
/*
- * If the GPS_HAS_FPGA flag is set in RECEIVER_INFO::flags then the card
+ * If the ::GPS_HAS_FPGA flag is set in ::RECEIVER_INFO::flags then the card
* provides an FPGA and the following information about the FPGA is available:
*/
#define FPGA_NAME_LEN 31 // max name length
@@ -1077,6 +1741,7 @@ typedef struct
{
CSUM csum;
uint16_t fpga_start_seg; // Number of the 4k block where an FPGA image is located
+
} FPGA_START_INFO;
#define DEFAULT_FPGA_START_SEG 0x60
@@ -1090,18 +1755,28 @@ typedef struct
/**
- Date and time referred to the linear time scale defined by GPS.
- GPS time is defined by the number of weeks since midnight from
- January 5, 1980 to January 6, 1980 plus the number of seconds of
- the current week plus fractions of a second. GPS time differs from
- UTC because UTC is corrected with leap seconds while GPS time scale
- is continuous.
-*/
+ * @brief A structure used to hold time in GPS format
+ *
+ * Date and time refer to the linear time scale defined by GPS, with
+ * the epoch starting at %UTC midnight at the beginning of January 6, 1980.
+ *
+ * GPS time is counted by the week numbers since the epoch, plus second
+ * of the week, plus fraction of the second. The week number transmitted
+ * by the satellites rolls over from 1023 to 0, but Meinberg devices
+ * just continue to count the weeks beyond the 1024 week limit to keep
+ * the receiver's internal time.
+ *
+ * %UTC time differs from GPS time since a number of leap seconds have
+ * been inserted in the %UTC time scale after the GPS epoche. The number
+ * of leap seconds is disseminated by the satellites using the ::UTC
+ * parameter set, which also provides info on pending leap seconds.
+ */
typedef struct
{
- uint16_t wn; /**< the week number since GPS has been installed */
- uint32_t sec; /**< the second of that week */
- uint32_t tick; /**< fractions of a second; scale: 1/GPS_TICKS_PER_SEC */
+ uint16_t wn; ///< the week number since GPS has been installed
+ uint32_t sec; ///< the second of that week
+ uint32_t tick; ///< fractions of a second, 1/::RECEIVER_INFO::ticks_per_sec units
+
} T_GPS;
#define _mbg_swab_t_gps( _p ) \
@@ -1113,26 +1788,32 @@ typedef struct
/**
- Local date and time computed from GPS time. The current number
- of leap seconds have to be added to get UTC from GPS time.
- Additional corrections could have been made according to the
- time zone/daylight saving parameters (TZDL, see below) defined
- by the user. The status field can be checked to see which corrections
- have been applied.
-*/
+ * @brief Local date and time computed from GPS time
+ *
+ * The current number of leap seconds have to be added to get %UTC
+ * from GPS time. Additional corrections could have been made according
+ * to the time zone/daylight saving parameters ::TZDL defined by the user.
+ * The status field can be checked to see which corrections
+ * have actually been applied.
+ *
+ * @note Conversion from GPS time to %UTC and/or local time can only be
+ * done if some valid ::UTC correction parameters are available in the
+ * receiver's non-volatile memory.
+ */
typedef struct
{
- int16_t year; /**< year number, 0..9999 */
- int8_t month; /**< month, 1..12 */
- int8_t mday; /**< day of month, 1..31 */
- int16_t yday; /**< day of year, 1..366 */
- int8_t wday; /**< day of week, 0..6 == Sun..Sat */
- int8_t hour; /**< hours, 0..23 */
- int8_t min; /**< minutes, 0..59 */
- int8_t sec; /**< seconds, 0..59 */
- int32_t frac; /**< fractions of a second; scale: 1/GPS_TICKS_PER_SEC */
- int32_t offs_from_utc; /**< local time's offset from UTC */
- uint16_t status; /**< status flags */
+ int16_t year; ///< year number, 0..9999
+ int8_t month; ///< month, 1..12
+ int8_t mday; ///< day of month, 1..31
+ int16_t yday; ///< day of year, 1..365, or 366 in case of leap year
+ int8_t wday; ///< day of week, 0..6 == Sun..Sat
+ int8_t hour; ///< hours, 0..23
+ int8_t min; ///< minutes, 0..59
+ int8_t sec; ///< seconds, 0..59, or 60 in case of inserted leap second
+ int32_t frac; ///< fractions of a second, 1/::RECEIVER_INFO::ticks_per_sec units
+ int32_t offs_from_utc; ///< local time's offset from %UTC
+ uint16_t status; ///< status flags, see ::TM_GPS_STATUS_BIT_MASKS
+
} TM_GPS;
#define _mbg_swab_tm_gps( _p ) \
@@ -1145,76 +1826,105 @@ typedef struct
}
-/* status flag bits used with conversion from GPS time to local time */
+/**
+ * @brief Status flag bits used to define ::TM_GPS_STATUS_BIT_MASKS
+ *
+ * These bits report info on the time conversion from GPS time to %UTC
+ * and/or local time as well as device status info.
+ *
+ * @see ::TM_GPS_STATUS_BIT_MASKS
+ */
+enum TM_GPS_STATUS_BITS
+{
+ TM_BIT_UTC, ///< %UTC correction has been made
+ TM_BIT_LOCAL, ///< %UTC has been converted to local time according to ::TZDL settings
+ TM_BIT_DL_ANN, ///< state of daylight saving is going to change
+ TM_BIT_DL_ENB, ///< daylight saving is in effect
+ TM_BIT_LS_ANN, ///< leap second pending
+ TM_BIT_LS_ENB, ///< current second is leap second
+ TM_BIT_LS_ANN_NEG, ///< set in addition to ::TM_BIT_LS_ANN if leap sec is negative
+ TM_BIT_INVT, ///< invalid time, e.g. if RTC battery bas been empty
+
+ TM_BIT_EXT_SYNC, ///< synchronized externally
+ TM_BIT_HOLDOVER, ///< in holdover mode after previous synchronization
+ TM_BIT_ANT_SHORT, ///< antenna cable short circuited
+ TM_BIT_NO_WARM, ///< OCXO has not warmed up
+ TM_BIT_ANT_DISCONN, ///< antenna currently disconnected
+ TM_BIT_SYN_FLAG, ///< TIME_SYN output is low
+ TM_BIT_NO_SYNC, ///< time sync actually not verified
+ TM_BIT_NO_POS ///< position actually not verified, LOCK LED off
+};
-enum
-{
- TM_BIT_UTC, /* UTC correction has been made */
- TM_BIT_LOCAL, /* UTC has been converted to local time */
- TM_BIT_DL_ANN, /* state of daylight saving is going to change */
- TM_BIT_DL_ENB, /* daylight saving is enabled */
- TM_BIT_LS_ANN, /* leap second will be inserted */
- TM_BIT_LS_ENB, /* current second is leap second */
- TM_BIT_LS_ANN_NEG, /* set in addition to TM_LS_ANN if leap sec negative */
- TM_BIT_INVT, /* invalid time, e.g. if RTC battery empty */
-
- TM_BIT_EXT_SYNC, /* sync'd externally */
- TM_BIT_HOLDOVER, /* holdover mode after previous sync. */
- TM_BIT_ANT_SHORT, /* antenna cable short circuited */
- TM_BIT_NO_WARM, /* OCXO has not warmed up */
- TM_BIT_ANT_DISCONN, /* antenna currently disconnected */
- TM_BIT_SYN_FLAG, /* TIME_SYN output is low */
- TM_BIT_NO_SYNC, /* time sync actually not verified */
- TM_BIT_NO_POS /* position actually not verified, LOCK LED off */
-};
-
-// Type of an extended TM status which is mainly used by the firmware.
-typedef uint32_t TM_STATUS_EXT; // extended status, mainly used by the firmware
-
-// The lower 16 bits of the TM_STATUS_X type correspond to those defined above,
-// and the upper bits are defined below:
-enum
-{
- TM_BIT_SCALE_GPS = 16,
- TM_BIT_SCALE_TAI
- // the remaining bits are reserved
+
+/**
+ * @brief Status flag masks used with ::TM_GPS::status
+ *
+ * These bits report info on the time conversion from GPS time to %UTC
+ * and/or local time as well as device status info.
+ *
+ * @see ::TM_GPS_STATUS_BITS
+ */
+enum TM_GPS_STATUS_BIT_MASKS
+{
+ TM_UTC = ( 1UL << TM_BIT_UTC ), ///< see ::TM_BIT_UTC
+ TM_LOCAL = ( 1UL << TM_BIT_LOCAL ), ///< see ::TM_BIT_LOCAL
+ TM_DL_ANN = ( 1UL << TM_BIT_DL_ANN ), ///< see ::TM_BIT_DL_ANN
+ TM_DL_ENB = ( 1UL << TM_BIT_DL_ENB ), ///< see ::TM_BIT_DL_ENB
+ TM_LS_ANN = ( 1UL << TM_BIT_LS_ANN ), ///< see ::TM_BIT_LS_ANN
+ TM_LS_ENB = ( 1UL << TM_BIT_LS_ENB ), ///< see ::TM_BIT_LS_ENB
+ TM_LS_ANN_NEG = ( 1UL << TM_BIT_LS_ANN_NEG ), ///< see ::TM_BIT_LS_ANN_NEG
+ TM_INVT = ( 1UL << TM_BIT_INVT ), ///< see ::TM_BIT_INVT
+
+ TM_EXT_SYNC = ( 1UL << TM_BIT_EXT_SYNC ), ///< see ::TM_BIT_EXT_SYNC
+ TM_HOLDOVER = ( 1UL << TM_BIT_HOLDOVER ), ///< see ::TM_BIT_HOLDOVER
+ TM_ANT_SHORT = ( 1UL << TM_BIT_ANT_SHORT ), ///< see ::TM_BIT_ANT_SHORT
+ TM_NO_WARM = ( 1UL << TM_BIT_NO_WARM ), ///< see ::TM_BIT_NO_WARM
+ TM_ANT_DISCONN = ( 1UL << TM_BIT_ANT_DISCONN ), ///< see ::TM_BIT_ANT_DISCONN
+ TM_SYN_FLAG = ( 1UL << TM_BIT_SYN_FLAG ), ///< see ::TM_BIT_SYN_FLAG
+ TM_NO_SYNC = ( 1UL << TM_BIT_NO_SYNC ), ///< see ::TM_BIT_NO_SYNC
+ TM_NO_POS = ( 1UL << TM_BIT_NO_POS ) ///< see ::TM_BIT_NO_POS
};
-/* bit masks corresponding to the flag bits above */
-#define TM_UTC ( 1UL << TM_BIT_UTC )
-#define TM_LOCAL ( 1UL << TM_BIT_LOCAL )
-#define TM_DL_ANN ( 1UL << TM_BIT_DL_ANN )
-#define TM_DL_ENB ( 1UL << TM_BIT_DL_ENB )
-#define TM_LS_ANN ( 1UL << TM_BIT_LS_ANN )
-#define TM_LS_ENB ( 1UL << TM_BIT_LS_ENB )
-#define TM_LS_ANN_NEG ( 1UL << TM_BIT_LS_ANN_NEG )
-#define TM_INVT ( 1UL << TM_BIT_INVT )
+/**
+ * @brief Type of an extended TM status which is mainly used inside the firmware
+ */
+typedef uint32_t TM_STATUS_EXT;
-#define TM_EXT_SYNC ( 1UL << TM_BIT_EXT_SYNC )
-#define TM_HOLDOVER ( 1UL << TM_BIT_HOLDOVER )
-#define TM_ANT_SHORT ( 1UL << TM_BIT_ANT_SHORT )
-#define TM_NO_WARM ( 1UL << TM_BIT_NO_WARM )
-#define TM_ANT_DISCONN ( 1UL << TM_BIT_ANT_DISCONN )
-#define TM_SYN_FLAG ( 1UL << TM_BIT_SYN_FLAG )
-#define TM_NO_SYNC ( 1UL << TM_BIT_NO_SYNC )
-#define TM_NO_POS ( 1UL << TM_BIT_NO_POS )
+/**
+ * @brief Enumeration of extended status bits used with ::TM_STATUS_EXT
+ *
+ * @note The lower 16 bits correspond to ::TM_GPS_STATUS_BITS
+ */
+enum TM_GPS_STATUS_BITS_EX
+{
+ TM_BIT_SCALE_GPS = 16, ///< time scale configured to return GPS time
+ TM_BIT_SCALE_TAI ///< time scale configured to return TAI
+ // the remaining bits are reserved
+};
-// The following bits are only used with the TM_STATUS_X type:
+// The following bits are only used with the ::TM_STATUS_X type:
#define TM_SCALE_GPS ( 1UL << TM_BIT_SCALE_GPS )
#define TM_SCALE_TAI ( 1UL << TM_BIT_SCALE_TAI )
#define TM_MSK_TIME_VALID ( TM_UTC | TM_SCALE_GPS | TM_SCALE_TAI )
+
/**
* @brief A structure used to transmit information on date and time
+ *
+ * This structure can be used to transfer the current time, in which
+ * case the channel field has to be set to -1, or an event capture time
+ * retrieved from the on-board FIFO, in which case the channel field
+ * contains the index of the time capture input, e.g. 0 or 1.
*/
typedef struct
{
- int16_t channel; /**< -1: the current time; 0, 1: capture 0, 1 */
- T_GPS t; /**< time in GPS format */
- TM_GPS tm; /**< that time converted to local time */
+ int16_t channel; ///< -1: the current on-board time; >= 0 the capture channel number
+ T_GPS t; ///< time in GPS scale and format
+ TM_GPS tm; ///< time converted to %UTC and/or local time according to ::TZDL settings
+
} TTM;
#define _mbg_swab_ttm( _p ) \
@@ -1226,10 +1936,14 @@ typedef struct
+/**
+ * @brief A timestamp with nanosecond resolution
+ */
typedef struct
{
- int32_t nano_secs; // [nanoseconds]
- int32_t secs; // [seconds]
+ int32_t nano_secs; ///< [nanoseconds]
+ int32_t secs; ///< [seconds]
+
} NANO_TIME;
#define _mbg_swab_nano_time( _p ) \
@@ -1238,24 +1952,24 @@ typedef struct
_mbg_swab32( &(_p)->secs ); \
}
-// The macro below checks if a NANO_TIME value is negative.
+// The macro below checks if a ::NANO_TIME value is negative.
#define _nano_time_negative( _nt ) \
( ( (_nt)->secs < 0 ) || ( (_nt)->nano_secs < 0 ) )
-/* Two types of variables used to store a position. Type XYZ is */
-/* used with a position in earth centered, earth fixed (ECEF) */
-/* coordinates whereas type LLA holds such a position converted */
-/* to geographic coordinates as defined by WGS84 (World Geodetic */
-/* System from 1984). */
-
#ifndef _XYZ_DEFINED
- /* sequence and number of components of a cartesian position */
- enum { XP, YP, ZP, N_XYZ };
+ /**
+ * @brief Sequence and number of components of a cartesian position
+ */
+ enum XYZ_FIELDS { XP, YP, ZP, N_XYZ }; // x, y, z
- /** @brief An array holding a cartesian position */
- typedef double XYZ[N_XYZ]; /**< values are in [m] */
+ /**
+ * @brief A position in cartesian coordinates
+ *
+ * Usually earth centered, earth fixed (ECEF) coordinates.
+ */
+ typedef double XYZ[N_XYZ]; ///< values are in [m], see ::XYZ_FIELDS
#define _XYZ_DEFINED
#endif
@@ -1264,11 +1978,20 @@ typedef struct
#ifndef _LLA_DEFINED
- /* sequence and number of components of a geographic position */
- enum { LAT, LON, ALT, N_LLA }; /* latitude, longitude, altitude */
+ /**
+ * @brief Sequence and number of components of a geographic position
+ */
+ enum LLA_FIELDS { LAT, LON, ALT, N_LLA }; /* latitude, longitude, altitude */
- /** @brief An array holding a geographic position */
- typedef double LLA[N_LLA]; /**< lon, lat in [rad], alt in [m] */
+ /**
+ * @brief A geographic position based on latitude, longitude, and altitude
+ *
+ * The geographic position associated to specific cartesian coordinates
+ * depends on the characteristics of the ellipsoid used for the computation,
+ * the so-called geographic datum. GPS uses the WGS84 (World Geodetic System
+ * from 1984) ellipsoid by default.
+ */
+ typedef double LLA[N_LLA]; ///< lon, lat in [rad], alt in [m], see ::LLA_FIELDS
#define _LLA_DEFINED
#endif
@@ -1277,65 +2000,74 @@ typedef struct
/**
- @defgroup group_synth Synthesizer parameters
-
- Synthesizer frequency is expressed as a
- four digit decimal number (freq) to be multiplied by 0.1 Hz and an
- base 10 exponent (range). If the effective frequency is less than
- 10 kHz its phase is synchronized corresponding to the variable phase.
- Phase may be in a range from -360 deg to +360 deg with a resolution
- of 0.1 deg, so the resulting numbers to be stored are in a range of
- -3600 to +3600.
-
- Example:<br>
- Assume the value of freq is 2345 (decimal) and the value of phase is 900.
- If range == 0 the effective frequency is 234.5 Hz with a phase of +90 deg.
- If range == 1 the synthesizer will generate a 2345 Hz output frequency
- and so on.
-
- Limitations:<br>
- If freq == 0 the synthesizer is disabled. If range == 0 the least
- significant digit of freq is limited to 0, 3, 5 or 6. The resulting
- frequency is shown in the examples below:
- - freq == 1230 --> 123.0 Hz
- - freq == 1233 --> 123 1/3 Hz (real 1/3 Hz, NOT 123.3 Hz)
- - freq == 1235 --> 123.5 Hz
- - freq == 1236 --> 123 2/3 Hz (real 2/3 Hz, NOT 123.6 Hz)
-
- If range == MAX_RANGE the value of freq must not exceed 1000, so the
- output frequency is limited to 10 MHz.
- @{
-*/
+ * @defgroup group_synth Synthesizer parameters
+ *
+ * Synthesizer frequency is expressed as a
+ * four digit decimal number (freq) to be multiplied by 0.1 Hz and an
+ * base 10 exponent (range). If the effective frequency is less than
+ * 10 kHz its phase is synchronized corresponding to the variable phase.
+ * Phase may be in a range from -360 deg to +360 deg with a resolution
+ * of 0.1 deg, so the resulting numbers to be stored are in a range of
+ * -3600 to +3600.
+ *
+ * Example:<br>
+ * Assume the value of freq is 2345 (decimal) and the value of phase is 900.
+ * If range == 0 the effective frequency is 234.5 Hz with a phase of +90 deg.
+ * If range == 1 the synthesizer will generate a 2345 Hz output frequency
+ * and so on.
+ *
+ * Limitations:<br>
+ * If freq == 0 the synthesizer is disabled. If range == 0 the least
+ * significant digit of freq is limited to 0, 3, 5 or 6. The resulting
+ * frequency is shown in the examples below:
+ * - freq == 1230 --> 123.0 Hz
+ * - freq == 1233 --> 123 1/3 Hz (real 1/3 Hz, NOT 123.3 Hz)
+ * - freq == 1235 --> 123.5 Hz
+ * - freq == 1236 --> 123 2/3 Hz (real 2/3 Hz, NOT 123.6 Hz)
+ *
+ * If range == ::MAX_SYNTH_RANGE the value of freq must not exceed 1000, so
+ * the output frequency is limited to 10 MHz (see ::MAX_SYNTH_FREQ_VAL).
+ *
+ * @{ */
-#define N_SYNTH_FREQ_DIGIT 4 /**< number of digits to edit */
-#define MAX_SYNTH_FREQ 1000 /**< if range == MAX_SYNTH_RANGE */
+#define N_SYNTH_FREQ_DIGIT 4 ///< number of digits to edit
+#define MAX_SYNTH_FREQ 1000 ///< if range == ::MAX_SYNTH_RANGE
#define MIN_SYNTH_RANGE 0
#define MAX_SYNTH_RANGE 5
#define N_SYNTH_RANGE ( MAX_SYNTH_RANGE - MIN_SYNTH_RANGE + 1 )
-#define N_SYNTH_PHASE_DIGIT 4
-#define MAX_SYNTH_PHASE 3600
+#define N_SYNTH_PHASE_DIGIT 4
+#define MAX_SYNTH_PHASE 3600
-#define MAX_SYNTH_FREQ_EDIT 9999 /**< max sequence of digits when editing */
+#define MAX_SYNTH_FREQ_EDIT 9999 ///< max sequence of digits when editing
-/** @brief The maximum frequency that can be configured for the synthesizer */
-#define MAX_SYNTH_FREQ_VAL 10000000UL /**< 10 MHz */
+
+/**
+ * @brief The maximum frequency that can be configured for the synthesizer
+ */
+#define MAX_SYNTH_FREQ_VAL 10000000UL ///< 10 MHz
/* == MAX_SYNTH_FREQ * 10^(MAX_SYNTH_RANGE-1) */
-/** @brief The synthesizer's phase is only be synchronized if the frequency is below this limit */
-#define SYNTH_PHASE_SYNC_LIMIT 10000UL /**< 10 kHz */
+/**
+ * @brief The synthesizer's phase is only be synchronized if the frequency is below this limit
+ */
+#define SYNTH_PHASE_SYNC_LIMIT 10000UL ///< 10 kHz
/**
- the position of the decimal point if the frequency is
- printed as 4 digit value */
+ * A Macro used to determine the position of the decimal point
+ * when printing the synthesizer frequency as 4 digit value
+ */
#define _synth_dp_pos_from_range( _r ) \
( ( ( N_SYNTH_RANGE - (_r) ) % ( N_SYNTH_FREQ_DIGIT - 1 ) ) + 1 )
/**
- An initializer for commonly displayed synthesizer frequency units
- (N_SYNTH_RANGE strings) */
+ * @brief Synthesizer frequency units
+ *
+ * An initializer for commonly displayed synthesizer frequency units
+ * (::N_SYNTH_RANGE strings)
+ */
#define DEFAULT_FREQ_RANGES \
{ \
"Hz", \
@@ -1348,11 +2080,15 @@ typedef struct
+/**
+ * @brief Synthesizer configuration parameters
+ */
typedef struct
{
- int16_t freq; /**< four digits used; scale: 0.1; e.g. 1234 -> 123.4 Hz */
- int16_t range; /**< scale factor for freq; 0..MAX_SYNTH_RANGE */
- int16_t phase; /**< -MAX_SYNTH_PHASE..+MAX_SYNTH_PHASE; >0 -> pulses later */
+ int16_t freq; ///< four digits used; scale: 0.1 Hz; e.g. 1234 -> 123.4 Hz
+ int16_t range; ///< scale factor for freq; 0..::MAX_SYNTH_RANGE
+ int16_t phase; ///< -::MAX_SYNTH_PHASE..+::MAX_SYNTH_PHASE; >0 -> pulses later
+
} SYNTH;
#define _mbg_swab_synth( _p ) \
@@ -1364,56 +2100,74 @@ typedef struct
/**
- The definitions below can be used to query the
- current synthesizer state.
+ * @brief Enumeration of synthesizer states
*/
-enum
+enum SYNTH_STATES
{
- SYNTH_DISABLED, /**< disbled by cfg, i.e. freq == 0.0 */
- SYNTH_OFF, /**< not enabled after power-up */
- SYNTH_FREE, /**< enabled, but not synchronized */
- SYNTH_DRIFTING, /**< has initially been sync'd, but now running free */
- SYNTH_SYNC, /**< fully synchronized */
- N_SYNTH_STATE /**< the number of known states */
+ SYNTH_DISABLED, ///< disbled by cfg, i.e. freq == 0.0
+ SYNTH_OFF, ///< not enabled after power-up
+ SYNTH_FREE, ///< enabled, but not synchronized
+ SYNTH_DRIFTING, ///< has initially been sync'd, but now running free
+ SYNTH_SYNC, ///< fully synchronized
+ N_SYNTH_STATE ///< the number of known states
};
+
+/**
+ * @brief A structure used to report the synthesizer state
+ */
typedef struct
{
- uint8_t state; /**< state code as enumerated above */
- uint8_t flags; /**< reserved, currently always 0 */
+ uint8_t state; ///< state code as enumerated in ::SYNTH_STATES
+ uint8_t flags; ///< reserved, currently always 0
+
} SYNTH_STATE;
#define _mbg_swab_synth_state( _p ) _nop_macro_fnc()
#define SYNTH_FLAG_PHASE_IGNORED 0x01
-/** @} group_synth */
+/** @} defgroup group_synth */
-/**
- @defgroup group_tzdl Time zone/daylight saving parameters
- Example: <br>
- For automatic daylight saving enable/disable in Central Europe,
- the variables are to be set as shown below: <br>
- - offs = 3600L one hour from UTC
- - offs_dl = 3600L one additional hour if daylight saving enabled
- - tm_on = first Sunday from March 25, 02:00:00h ( year |= DL_AUTO_FLAG )
- - tm_off = first Sunday from October 25, 03:00:00h ( year |= DL_AUTO_FLAG )
- - name[0] == "CET " name if daylight saving not enabled
- - name[1] == "CEST " name if daylight saving is enabled
- @{
-*/
-/** the name of a time zone, 5 characters plus trailing zero */
+/**
+ * @defgroup group_tzdl Time zone / daylight saving parameters
+ *
+ * Example: <br>
+ * For automatic daylight saving enable/disable in Central Europe,
+ * the variables are to be set as shown below: <br>
+ * - offs = 3600L one hour from %UTC
+ * - offs_dl = 3600L one additional hour if daylight saving enabled
+ * - tm_on = first Sunday from March 25, 02:00:00h ( year |= ::DL_AUTO_FLAG )
+ * - tm_off = first Sunday from October 25, 03:00:00h ( year |= ::DL_AUTO_FLAG )
+ * - name[0] == "CET " name if daylight saving not enabled
+ * - name[1] == "CEST " name if daylight saving is enabled
+ *
+ * @{ */
+
+/**
+ * @brief The name of a time zone
+ *
+ * @note Up to 5 printable characters, plus trailing zero
+ */
typedef char TZ_NAME[6];
+/**
+ * @brief Time zone / daylight saving parameters
+ *
+ * This structure is used to specify how a device is to convert
+ * on-board %UTC to local time, including computation of beginning
+ * and end of daylight saving time (DST), if required.
+ */
typedef struct
{
- int32_t offs; /**< offset from UTC to local time [sec] */
- int32_t offs_dl; /**< additional offset if daylight saving enabled [sec] */
- TM_GPS tm_on; /**< date/time when daylight saving starts */
- TM_GPS tm_off; /**< date/time when daylight saving ends */
- TZ_NAME name[2]; /**< names without and with daylight saving enabled */
+ int32_t offs; ///< standard offset from %UTC to local time [sec]
+ int32_t offs_dl; ///< additional offset if daylight saving enabled [sec]
+ TM_GPS tm_on; ///< date/time when daylight saving starts
+ TM_GPS tm_off; ///< date/time when daylight saving ends
+ TZ_NAME name[2]; ///< names without and with daylight saving enabled
+
} TZDL;
#define _mbg_swab_tzdl( _p ) \
@@ -1426,8 +2180,10 @@ typedef struct
/**
- If the year in tzdl.tm_on and tzdl.tm_off is or'ed with that constant,
- the receiver automatically generates daylight saving year by year.
+ * @brief A flag indicating automatic computation of DST
+ *
+ * If this flag is or'ed to the year numbers in ::TZDL::tm_on and ::TZDL::tm_off
+ * then daylight saving is computed automatically year by year.
*/
#define DL_AUTO_FLAG 0x8000
@@ -1437,18 +2193,18 @@ typedef struct
#define DEFAULT_TZDL_AUTO_YEAR ( 2007 | DL_AUTO_FLAG )
-#define DEFAULt_TZDL_OFFS_DL 3600L /**< usually DST is +1 hour */
+#define DEFAULt_TZDL_OFFS_DL 3600L ///< usually DST is +1 hour
/**
- The symbol below can be used to initialize both the tm_on
- and tm_off fields for time zones which do not switch to DST:
+ * An initializer for ::TZDL::tm_on and ::TZDL::tm_off for time zones
+ * which do not observe DST.
*/
#define DEFAULT_TZDL_TM_ON_OFF_NO_DST \
{ DEFAULT_TZDL_AUTO_YEAR, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0 }
-// Settings used with UTC:
+// Settings used with %UTC:
#define TZ_INFO_UTC "UTC (Universal Time, Coordinated)"
@@ -1456,22 +2212,23 @@ typedef struct
#define DEFAULT_TZDL_UTC \
{ \
- 0L, /**< offs */ \
- 0L, /**< offs_dl */ \
- DEFAULT_TZDL_TM_ON_OFF_NO_DST, /**< tm_on */ \
- DEFAULT_TZDL_TM_ON_OFF_NO_DST, /**< tm_off */ \
- DEFAULT_TZDL_NAMES_UTC /**< name[] */ \
+ 0L, /* offs */ \
+ 0L, /* offs_dl */ \
+ DEFAULT_TZDL_TM_ON_OFF_NO_DST, /* tm_on */ \
+ DEFAULT_TZDL_TM_ON_OFF_NO_DST, /* tm_off */ \
+ DEFAULT_TZDL_NAMES_UTC /* name */ \
}
/**
- The symbols below specify beginning and end of DST for
- Central Europe, as constituted by the European Parliament:
- */
-
+ * @brief An initializer for ::TZDL::tm_on according to the rules for Central Europe
+ */
#define DEFAULT_TZDL_TM_ON_CET_CEST \
{ DEFAULT_TZDL_AUTO_YEAR, 3, 25, 0, 0, 2, 0, 0, 0L, 0L, 0 }
+/**
+ * @brief An initializer for ::TZDL::tm_off according to the rules for Central Europe
+ */
#define DEFAULT_TZDL_TM_OFF_CET_CEST \
{ DEFAULT_TZDL_AUTO_YEAR, 10, 25, 0, 0, 3, 0, 0, 0L, 0L, 0 }
@@ -1488,20 +2245,20 @@ typedef struct
#define DEFAULT_TZDL_CET_CEST_EN \
{ \
- DEFAULT_TZDL_OFFS_CET, /**< offs */ \
- DEFAULt_TZDL_OFFS_DL, /**< offs_dl */ \
- DEFAULT_TZDL_TM_ON_CET_CEST, /**< tm_on */ \
- DEFAULT_TZDL_TM_OFF_CET_CEST, /**< tm_off */ \
- DEFAULT_TZDL_NAMES_CET_CEST_EN /**< name[] */ \
+ DEFAULT_TZDL_OFFS_CET, /* offs */ \
+ DEFAULt_TZDL_OFFS_DL, /* offs_dl */ \
+ DEFAULT_TZDL_TM_ON_CET_CEST, /* tm_on */ \
+ DEFAULT_TZDL_TM_OFF_CET_CEST, /* tm_off */ \
+ DEFAULT_TZDL_NAMES_CET_CEST_EN /* name */ \
}
#define DEFAULT_TZDL_CET_CEST_DE \
{ \
- DEFAULT_TZDL_OFFS_CET, /**< offs */ \
- DEFAULt_TZDL_OFFS_DL, /**< offs_dl */ \
- DEFAULT_TZDL_TM_ON_CET_CEST, /**< tm_on */ \
- DEFAULT_TZDL_TM_OFF_CET_CEST, /**< tm_off */ \
- DEFAULT_TZDL_NAMES_CET_CEST_DE /**< name[] */ \
+ DEFAULT_TZDL_OFFS_CET, /* offs */ \
+ DEFAULt_TZDL_OFFS_DL, /* offs_dl */ \
+ DEFAULT_TZDL_TM_ON_CET_CEST, /* tm_on */ \
+ DEFAULT_TZDL_TM_OFF_CET_CEST, /* tm_off */ \
+ DEFAULT_TZDL_NAMES_CET_CEST_DE /* name */ \
}
@@ -1531,7 +2288,7 @@ typedef struct
DEFAULt_TZDL_OFFS_DL, /* offs_dl */ \
DEFAULT_TZDL_TM_ON_EET_EEST, /* tm_on */ \
DEFAULT_TZDL_TM_OFF_EET_EEST, /* tm_off */ \
- DEFAULT_TZDL_NAMES_EET_EEST_EN /* name[] */ \
+ DEFAULT_TZDL_NAMES_EET_EEST_EN /* name */ \
}
#define DEFAULT_TZDL_EET_EEST_DE \
@@ -1540,22 +2297,35 @@ typedef struct
DEFAULt_TZDL_OFFS_DL, /* offs_dl */ \
DEFAULT_TZDL_TM_ON_EET_EEST, /* tm_on */ \
DEFAULT_TZDL_TM_OFF_EET_EEST, /* tm_off */ \
- DEFAULT_TZDL_NAMES_EET_EEST_DE /* name[] */ \
+ DEFAULT_TZDL_NAMES_EET_EEST_DE /* name */ \
}
-/** @} group_tzdl */
+/** @} defgroup group_tzdl */
+
+
/**
+ * @brief Antenna status and error at reconnect information
+ *
* The structure below reflects the status of the antenna,
* the times of last disconnect/reconnect, and the board's
- * clock offset after the disconnection interval.
+ * clock offset when it has synchronized again after the
+ * disconnection interval.
+ *
+ * @note ::ANT_INFO::status changes back to ::ANT_RECONN only
+ * after the antenna has been reconnected <b>and</b> the
+ * receiver has re-synchronized to the satellite signal.
+ * In this case ::ANT_INFO::delta_t reports the time offset
+ * before resynchronization, i.e. how much the internal
+ * time has drifted while the antenna was disconnected.
*/
typedef struct
{
- int16_t status; /**< current status of antenna */
- TM_GPS tm_disconn; /**< time of antenna disconnect */
- TM_GPS tm_reconn; /**< time of antenna reconnect */
- int32_t delta_t; /**< clock offs. at reconn. time in #GPS_TICKS_PER_SEC */
+ int16_t status; ///< current status of antenna, see ::ANT_STATUS_CODES
+ TM_GPS tm_disconn; ///< time of antenna disconnect
+ TM_GPS tm_reconn; ///< time of antenna reconnect
+ int32_t delta_t; ///< clock offs at reconn. time in 1/::RECEIVER_INFO::ticks_per_sec units
+
} ANT_INFO;
#define _mbg_swab_ant_info( _p ) \
@@ -1568,38 +2338,35 @@ typedef struct
/**
- The status field may be set to one of the values below:
-*/
-enum
+ * @brief Status code used with ::ANT_INFO::status
+ */
+enum ANT_STATUS_CODES
{
- ANT_INVALID, /**< struct not set yet because ant. has not been disconn. */
- ANT_DISCONN, /**< ant. now disconn., tm_reconn and delta_t not set */
- ANT_RECONN /**< ant. has been disconn. and reconn., all fields valid */
+ ANT_INVALID, ///< No other fields valid since antenna has not yet been disconnected
+ ANT_DISCONN, ///< Antenna is disconnected, tm_reconn and delta_t not yet set
+ ANT_RECONN, ///< Antenna has been disconnect, and receiver sync. after reconnect, so all fields valid
+ N_ANT_STATUS_CODES ///< the number of known status codes
};
-/* Defines used with ENABLE_FLAGS */
-#define EF_OFF 0x00 /**< outputs off until sync'd */
-
-#define EF_SERIAL_BOTH 0x03 /**< both serial ports on */
-#define EF_PULSES_BOTH 0x03 /**< both pulses P_SEC and P_MIN on */
-#define EF_FREQ_ALL 0x07 /**< all fixed freq. outputs on */
-#define EF_SYNTH 0x01 /**< synth. on */
/**
- The structure holds some flags which let
- the corresponding outputs be disabled after power-up until
- the receiver has synchronized (flag == 0x00, the default) or force
- the outputs to be enabled immediately after power-up. The fixed
- frequency output is hard-wired to be enabled immediately after
- power-up, so the code for freq must always be 0x03.
-*/
+ * @brief A structure controlling when output signals are enabled
+ *
+ * The structure holds some flags which let the corresponding outputs
+ * be disabled after power-up until the receiver has synchronized
+ * (flags == ::EF_OFF, the default) or force the outputs to be enabled
+ * immediately after power-up. The fixed frequency output is hard-wired
+ * to be enabled immediately after power-up, so ::ENABLE_FLAGS::freq must
+ * always be set to ::EF_FREQ_ALL.
+ */
typedef struct
{
- uint16_t serial; /**< #EF_OFF or #EF_SERIAL_BOTH */
- uint16_t pulses; /**< #EF_OFF or #EF_PULSES_BOTH */
- uint16_t freq; /**< always #EF_FREQ_ALL */
- uint16_t synth; /**< #EF_OFF or #EF_SYNTH */
+ uint16_t serial; ///< ::EF_OFF or ::EF_SERIAL_BOTH
+ uint16_t pulses; ///< ::EF_OFF or ::EF_PULSES_BOTH
+ uint16_t freq; ///< always ::EF_FREQ_ALL
+ uint16_t synth; ///< ::EF_OFF or ::EF_SYNTH
+
} ENABLE_FLAGS;
#define _mbg_swab_enable_flags( _p ) \
@@ -1611,25 +2378,53 @@ typedef struct
}
-/* A struct used to hold the settings of a serial port: */
+/**
+ * @brief Codes used with ::ENABLE_FLAGS
+ **/
+enum ENABLE_FLAGS_CODES
+{
+ EF_OFF = 0x00, ///< associated outputs off until synchronized
+
+ EF_SERIAL_BOTH = 0x03, ///< both serial ports on, use with ::ENABLE_FLAGS::serial
+ EF_PULSES_BOTH = 0x03, ///< both pulses P_SEC and P_MIN on, use with ::ENABLE_FLAGS::pulses
+ EF_FREQ_ALL = 0x07, ///< all fixed freq. outputs on, use with ::ENABLE_FLAGS::freq
+ EF_SYNTH = 0x01 ///< synthesizer on, use with ::ENABLE_FLAGS::synth
+};
+
+
#ifndef _COM_HS_DEFINED
- /* types of handshake */
- enum { HS_NONE, HS_XONXOFF, HS_RTSCTS, N_COM_HS };
+ /**
+ * @brief Enumeration of handshake modes
+ */
+ enum COM_HANSHAKE_MODES { HS_NONE, HS_XONXOFF, HS_RTSCTS, N_COM_HS };
#define _COM_HS_DEFINED
#endif
#ifndef _COM_PARM_DEFINED
+ /**
+ * @brief A data type to configure a serial port's baud rate
+ *
+ * @see ::MBG_BAUD_RATES
+ */
typedef int32_t BAUD_RATE;
- /* indices used to identify a parameter in the framing string */
- enum { F_DBITS, F_PRTY, F_STBITS };
+ /**
+ * @brief Indices used to identify a parameter in the framing string
+ *
+ * @see ::MBG_FRAMING_STRS
+ */
+ enum MBG_FRAMING_STR_IDXS { F_DBITS, F_PRTY, F_STBITS };
+ /**
+ * @brief A structure to store the configuration of a serial port
+ */
typedef struct
{
- BAUD_RATE baud_rate; /* e.g. 19200L */
- char framing[4]; /* e.g. "8N1" */
- int16_t handshake; /* a numeric value, only HS_NONE supported yet */
+ BAUD_RATE baud_rate; ///< transmission speed, e.g. 19200L, see ::MBG_BAUD_RATES
+ char framing[4]; ///< ASCIIZ framing string, e.g. "8N1" or "7E2", see ::MBG_FRAMING_STRS
+ int16_t handshake; ///< handshake mode, yet only ::HS_NONE supported
+
} COM_PARM;
#define _COM_PARM_DEFINED
@@ -1644,12 +2439,15 @@ typedef struct
}
-/*
- * Indices of any supported baud rates.
- * Note that not each baud rate must be supported by
- * any clock model and/or port:
+/**
+ * @brief Enumeration of serial port baud rates
+ *
+ * @note Most clock models and/or serial ports don't support all defined baud rates.
+ *
+ * @see ::MBG_BAUD_RATES
+ * @see ::MBG_BAUD_RATE_MASKS
*/
-enum
+enum MBG_BAUD_RATE_CODES
{
MBG_BAUD_RATE_300,
MBG_BAUD_RATE_600,
@@ -1659,12 +2457,23 @@ enum
MBG_BAUD_RATE_9600,
MBG_BAUD_RATE_19200,
MBG_BAUD_RATE_38400,
- N_MBG_BAUD_RATES /* the number of supported baud rates */
+ MBG_BAUD_RATE_57600,
+ MBG_BAUD_RATE_115200,
+ MBG_BAUD_RATE_230400,
+ MBG_BAUD_RATE_460800,
+ MBG_BAUD_RATE_921600,
+ N_MBG_BAUD_RATES ///< the number of known baud rates
};
-/*
- * An initializer for a table of baud rate values.
- * The values must correspond to the enumeration above.
+/**
+ * @brief An initializer for a table of baud rate values
+ *
+ * These values can be used with ::COM_PARM::baud_rate, if the device
+ * supports the particular baud rate.
+ *
+ * The values must correspond to the enumeration ::MBG_BAUD_RATE_CODES
+ *
+ * @see ::MBG_BAUD_RATE_CODES
*/
#define MBG_BAUD_RATES \
{ \
@@ -1675,12 +2484,20 @@ enum
4800L, \
9600L, \
19200L, \
- 38400L \
+ 38400L, \
+ 57600L, \
+ 115200L, \
+ 230400L, \
+ 460800L, \
+ 921600L \
}
-/*
- * An initializer for a table of baud rate strings.
- * The values must correspond to the enumeration above.
+/**
+ * @brief An initializer for a table of baud rate strings
+ *
+ * The values must correspond to the enumeration ::MBG_BAUD_RATE_CODES
+ *
+ * @see ::MBG_BAUD_RATE_CODES
*/
#define MBG_BAUD_STRS \
{ \
@@ -1691,32 +2508,49 @@ enum
"4800", \
"9600", \
"19200", \
- "38400" \
+ "38400", \
+ "57600", \
+ "115200", \
+ "230400", \
+ "460800", \
+ "921600" \
}
-/*
- * The bit masks below can be used to determine which baud rates
- * are supported by a serial port. This may vary between
- * different ports of the same device since different
- * types of UART are used which must not necessarily support
- * each baud rate:
- */
-#define MBG_PORT_HAS_300 ( 1UL << MBG_BAUD_RATE_300 )
-#define MBG_PORT_HAS_600 ( 1UL << MBG_BAUD_RATE_600 )
-#define MBG_PORT_HAS_1200 ( 1UL << MBG_BAUD_RATE_1200 )
-#define MBG_PORT_HAS_2400 ( 1UL << MBG_BAUD_RATE_2400 )
-#define MBG_PORT_HAS_4800 ( 1UL << MBG_BAUD_RATE_4800 )
-#define MBG_PORT_HAS_9600 ( 1UL << MBG_BAUD_RATE_9600 )
-#define MBG_PORT_HAS_19200 ( 1UL << MBG_BAUD_RATE_19200 )
-#define MBG_PORT_HAS_38400 ( 1UL << MBG_BAUD_RATE_38400 )
+/**
+ * @brief Bit masks associated with baud rates enumerated in ::MBG_BAUD_RATE_CODES
+ *
+ * These bit masks are used e.g. with ::PORT_INFO::supp_baud_rates to
+ * determine which baud rates are supported by a particular serial port.
+ *
+ * @see ::MBG_BAUD_RATE_CODES
+ * @see ::MBG_FRAMING_MASKS
+ */
+enum MBG_BAUD_RATE_MASKS
+{
+ MBG_PORT_HAS_300 = ( 1UL << MBG_BAUD_RATE_300 ), ///< see ::MBG_BAUD_RATE_300
+ MBG_PORT_HAS_600 = ( 1UL << MBG_BAUD_RATE_600 ), ///< see ::MBG_BAUD_RATE_600
+ MBG_PORT_HAS_1200 = ( 1UL << MBG_BAUD_RATE_1200 ), ///< see ::MBG_BAUD_RATE_1200
+ MBG_PORT_HAS_2400 = ( 1UL << MBG_BAUD_RATE_2400 ), ///< see ::MBG_BAUD_RATE_2400
+ MBG_PORT_HAS_4800 = ( 1UL << MBG_BAUD_RATE_4800 ), ///< see ::MBG_BAUD_RATE_4800
+ MBG_PORT_HAS_9600 = ( 1UL << MBG_BAUD_RATE_9600 ), ///< see ::MBG_BAUD_RATE_9600
+ MBG_PORT_HAS_19200 = ( 1UL << MBG_BAUD_RATE_19200 ), ///< see ::MBG_BAUD_RATE_19200
+ MBG_PORT_HAS_38400 = ( 1UL << MBG_BAUD_RATE_38400 ), ///< see ::MBG_BAUD_RATE_38400
+ MBG_PORT_HAS_57600 = ( 1UL << MBG_BAUD_RATE_57600 ), ///< see ::MBG_BAUD_RATE_57600
+ MBG_PORT_HAS_115200 = ( 1UL << MBG_BAUD_RATE_115200 ), ///< see ::MBG_BAUD_RATE_115200
+ MBG_PORT_HAS_230400 = ( 1UL << MBG_BAUD_RATE_230400 ), ///< see ::MBG_BAUD_RATE_230400
+ MBG_PORT_HAS_460800 = ( 1UL << MBG_BAUD_RATE_460800 ), ///< see ::MBG_BAUD_RATE_460800
+ MBG_PORT_HAS_921600 = ( 1UL << MBG_BAUD_RATE_921600 ) ///< see ::MBG_BAUD_RATE_921600
+};
-/*
- * Indices of any supported framings.
- * Note that not each framing must be supported by
- * any clock model and/or port:
+/**
+ * @brief Enumeration of all known serial port framings
+ *
+ * @note Most clock models and/or serial ports don't support all defined framing types.
+ *
+ * @see ::MBG_FRAMING_STRS
*/
-enum
+enum MBG_FRAMING_CODES
{
MBG_FRAMING_7N2,
MBG_FRAMING_7E1,
@@ -1727,12 +2561,21 @@ enum
MBG_FRAMING_7O1,
MBG_FRAMING_7O2,
MBG_FRAMING_8O1,
- N_MBG_FRAMINGS /* the number of supported framings */
+ MBG_FRAMING_8E2, ///< Note: most serial ports don't support this!
+ N_MBG_FRAMINGS ///< the number of known framings
};
-/*
- * An initializer for a table of framing strings.
- * The values must correspond to the enumeration above.
+/**
+ * @brief An initializer for a table of known framing strings
+ *
+ * These values can be used with ::COM_PARM::framing, if the device
+ * supports the particular framing.
+ *
+ * The values must correspond to the enumeration ::MBG_FRAMING_CODES
+ *
+ * @see ::MBG_FRAMING_CODES
+ * @see ::MBG_FRAMING_MASKS
+ * @see ::MBG_FRAMING_STR_IDXS
*/
#define MBG_FRAMING_STRS \
{ \
@@ -1744,31 +2587,80 @@ enum
"8E1", \
"7O1", \
"7O2", \
- "8O1" \
+ "8O1", \
+ "8E2" \
}
-/*
- * The bit masks below can be used to determine which framings
- * are supported by a serial port. This may vary between
- * different ports of the same device since different
- * types of UART are used which must not necessarily support
- * each framing type:
+/**
+ * @brief Bit masks associated with framings enumerated in ::MBG_FRAMING_CODES
+ *
+ * These bit masks are used e.g. with ::PORT_INFO::supp_framings to
+ * determine which framings are supported by a particular serial port.
+ *
+ * @see ::MBG_FRAMING_CODES
+ * @see ::MBG_FRAMING_STRS
+ */
+enum MBG_FRAMING_MASKS
+{
+ MBG_PORT_HAS_7N2 = ( 1UL << MBG_FRAMING_7N2 ), ///< see ::MBG_FRAMING_7N2
+ MBG_PORT_HAS_7E1 = ( 1UL << MBG_FRAMING_7E1 ), ///< see ::MBG_FRAMING_7E1
+ MBG_PORT_HAS_7E2 = ( 1UL << MBG_FRAMING_7E2 ), ///< see ::MBG_FRAMING_7E2
+ MBG_PORT_HAS_8N1 = ( 1UL << MBG_FRAMING_8N1 ), ///< see ::MBG_FRAMING_8N1
+ MBG_PORT_HAS_8N2 = ( 1UL << MBG_FRAMING_8N2 ), ///< see ::MBG_FRAMING_8N2
+ MBG_PORT_HAS_8E1 = ( 1UL << MBG_FRAMING_8E1 ), ///< see ::MBG_FRAMING_8E1
+ MBG_PORT_HAS_7O1 = ( 1UL << MBG_FRAMING_7O1 ), ///< see ::MBG_FRAMING_7O1
+ MBG_PORT_HAS_7O2 = ( 1UL << MBG_FRAMING_7O2 ), ///< see ::MBG_FRAMING_7O2
+ MBG_PORT_HAS_8O1 = ( 1UL << MBG_FRAMING_8O1 ), ///< see ::MBG_FRAMING_8O1
+ MBG_PORT_HAS_8E2 = ( 1UL << MBG_FRAMING_8E2 ) ///< see ::MBG_FRAMING_8E2
+};
+
+
+
+/**
+ * @brief Definitions used with the Meinberg binary protocol
+ *
+ * @anchor GPS_BIN_PROT_DEFS @{ */
+
+/**
+ * @brief Framing used with the binary protocol
+ *
+ * Different data length, or parity settings would corrupt
+ * the binary data.
*/
-#define MBG_PORT_HAS_7N2 ( 1UL << MBG_FRAMING_7N2 )
-#define MBG_PORT_HAS_7E1 ( 1UL << MBG_FRAMING_7E1 )
-#define MBG_PORT_HAS_7E2 ( 1UL << MBG_FRAMING_7E2 )
-#define MBG_PORT_HAS_8N1 ( 1UL << MBG_FRAMING_8N1 )
-#define MBG_PORT_HAS_8N2 ( 1UL << MBG_FRAMING_8N2 )
-#define MBG_PORT_HAS_8E1 ( 1UL << MBG_FRAMING_8E1 )
-#define MBG_PORT_HAS_7O1 ( 1UL << MBG_FRAMING_7O1 )
-#define MBG_PORT_HAS_7O2 ( 1UL << MBG_FRAMING_7O2 )
-#define MBG_PORT_HAS_8O1 ( 1UL << MBG_FRAMING_8O1 )
+#define MBG_DEFAULT_FRAMING "8N1"
+/**
+ * @brief The standard baud rate used for the binary protocol
+ *
+ * This is supported by most devices. Some new devices may also
+ * support ::MBG_DEFAULT_BAUDRATE_HS
+ */
+#define MBG_DEFAULT_BAUDRATE 19200L
-// Default port settings to be used
-// with the binary protocol
-#define MBG_DEFAULT_BAUDRATE 19200L
-#define MBG_DEFAULT_FRAMING "8N1"
+/**
+ * @brief The high speed baud rate used for the binary protocol
+ *
+ * This is not supported by older devices which work
+ * with ::MBG_DEFAULT_BAUDRATE only.
+ */
+#define MBG_DEFAULT_BAUDRATE_HS 115200L
+
+
+/**
+ * @brief Strings used to force connection settings for the binary protocol
+ *
+ * If a device supports this and receives one of these ASCII strings
+ * then it temporarily switches the serial port to some well-known
+ * baud rate and framing appropriate for the binary protocol.
+ *
+ * @anchor GPS_BIN_PROT_CMD_STRS @{ */
+
+#define MBG_FORCE_CONN_CMD_STR "\nDFC\n" ///< switch to ::MBG_DEFAULT_BAUDRATE
+#define MBG_FORCE_CONN_HS_CMD_STR "\nDFCHS\n" ///< switch to ::MBG_DEFAULT_BAUDRATE_HS
+
+/** @} anchor GPS_BIN_PROT_CMD_STRS */
+
+/** @} anchor GPS_BIN_PROT_DEFS */
@@ -1825,17 +2717,19 @@ enum
)
-/*
- * The structure below is more flexible if different receiver
- * models have different numbers of serial ports, so the old
- * structure PORT_PARM will become obsolete.
+/**
+ * @brief Configuration settings of a serial port
+ *
+ * @note This should be used preferably instead of
+ * ::PORT_PARM, which is deprecated.
*/
typedef struct
{
- COM_PARM parm; /* speed, framing, etc. */
- uint8_t mode; /* per second, per minute, etc. */
- uint8_t str_type; /* type of the output string */
- uint32_t flags; /* reserved for future use, currently 0 */
+ COM_PARM parm; ///< transmission speed, framing, etc.
+ uint8_t mode; ///< string mode, see ::STR_MODES
+ uint8_t str_type; ///< index of the supported time string formats, see ::STR_TYPE_INFO_IDX
+ uint32_t flags; ///< reserved, don't use, currently 0
+
} PORT_SETTINGS;
#define _mbg_swab_port_settings( _p ) \
@@ -1845,59 +2739,81 @@ typedef struct
}
-/*
- * The definitions below can be used to mark specific fields of a
- * PORT_SETTINGS structure, e.g. when editing build a mask indicating
- * which of the fields have changed or which are not valid.
- */
-enum
-{
- MBG_PS_BIT_BAUD_RATE_OVR_SW, /* Baud rate index exceeds num supp by driver SW */
- MBG_PS_BIT_BAUD_RATE_OVR_DEV, /* Baud rate index exceeds num supp by device */
- MBG_PS_BIT_BAUD_RATE, /* Baud rate not supp by given port */
- MBG_PS_BIT_FRAMING_OVR_SW, /* Framing index exceeds num supp by driver SW */
- MBG_PS_BIT_FRAMING_OVR_DEV, /* Framing index exceeds num supp by device */
- MBG_PS_BIT_FRAMING, /* Framing not supp by given port */
- MBG_PS_BIT_HS_OVR_SW, /* Handshake index exceeds num supp by driver SW */
- MBG_PS_BIT_HS, /* Handshake mode not supp by given port */
- MBG_PS_BIT_STR_TYPE_OVR_SW, /* String type index exceeds num supp by driver SW */
- MBG_PS_BIT_STR_TYPE_OVR_DEV, /* String type index exceeds num supp by device */
- MBG_PS_BIT_STR_TYPE, /* String type not supp by given port */
- MBG_PS_BIT_STR_MODE_OVR_SW, /* String mode index exceeds num supp by driver SW */
- MBG_PS_BIT_STR_MODE_OVR_DEV, /* String mode index exceeds num supp by device */
- MBG_PS_BIT_STR_MODE, /* String mode not supp by given port and string type */
- MBG_PS_BIT_FLAGS_OVR_SW, /* Flags not supp by driver SW */
- MBG_PS_BIT_FLAGS, /* Flags not supp by device */
+/**
+ * @brief Flag bits used to mark individual ::PORT_SETTINGS fields
+ *
+ * These definitions can be used to mark specific fields of a
+ * ::PORT_SETTINGS structure, e.g. which fields have changed when
+ * editing, or which fields have settings which are not valid.
+ */
+enum MBG_COM_CFG_STATUS_BITS
+{
+ MBG_PS_BIT_BAUD_RATE_OVR_SW, ///< Baud rate index exceeds num supp by driver SW
+ MBG_PS_BIT_BAUD_RATE_OVR_DEV, ///< Baud rate index exceeds num supp by device
+ MBG_PS_BIT_BAUD_RATE, ///< Baud rate not supp by given port
+ MBG_PS_BIT_FRAMING_OVR_SW, ///< Framing index exceeds num supp by driver SW
+ MBG_PS_BIT_FRAMING_OVR_DEV, ///< Framing index exceeds num supp by device
+ MBG_PS_BIT_FRAMING, ///< Framing not supp by given port
+ MBG_PS_BIT_HS_OVR_SW, ///< Handshake index exceeds num supp by driver SW
+ MBG_PS_BIT_HS, ///< Handshake mode not supp by given port
+ MBG_PS_BIT_STR_TYPE_OVR_SW, ///< String type index exceeds num supp by driver SW
+ MBG_PS_BIT_STR_TYPE_OVR_DEV, ///< String type index exceeds num supp by device
+ MBG_PS_BIT_STR_TYPE, ///< String type not supp by given port
+ MBG_PS_BIT_STR_MODE_OVR_SW, ///< String mode index exceeds num supp by driver SW
+ MBG_PS_BIT_STR_MODE_OVR_DEV, ///< String mode index exceeds num supp by device
+ MBG_PS_BIT_STR_MODE, ///< String mode not supp by given port and string type
+ MBG_PS_BIT_FLAGS_OVR_SW, ///< Flags not supp by driver SW
+ MBG_PS_BIT_FLAGS, ///< Flags not supp by device
N_MBG_PS_BIT
};
-#define MBG_PS_MSK_BAUD_RATE_OVR_SW ( 1UL << MBG_PS_BIT_BAUD_RATE_OVR_SW )
-#define MBG_PS_MSK_BAUD_RATE_OVR_DEV ( 1UL << MBG_PS_BIT_BAUD_RATE_OVR_DEV )
-#define MBG_PS_MSK_BAUD_RATE ( 1UL << MBG_PS_BIT_BAUD_RATE )
-#define MBG_PS_MSK_FRAMING_OVR_SW ( 1UL << MBG_PS_BIT_FRAMING_OVR_SW )
-#define MBG_PS_MSK_FRAMING_OVR_DEV ( 1UL << MBG_PS_BIT_FRAMING_OVR_DEV )
-#define MBG_PS_MSK_FRAMING ( 1UL << MBG_PS_BIT_FRAMING )
-#define MBG_PS_MSK_HS_OVR_SW ( 1UL << MBG_PS_BIT_HS_OVR_SW )
-#define MBG_PS_MSK_HS ( 1UL << MBG_PS_BIT_HS )
-#define MBG_PS_MSK_STR_TYPE_OVR_SW ( 1UL << MBG_PS_BIT_STR_TYPE_OVR_SW )
-#define MBG_PS_MSK_STR_TYPE_OVR_DEV ( 1UL << MBG_PS_BIT_STR_TYPE_OVR_DEV )
-#define MBG_PS_MSK_STR_TYPE ( 1UL << MBG_PS_BIT_STR_TYPE )
-#define MBG_PS_MSK_STR_MODE_OVR_SW ( 1UL << MBG_PS_BIT_STR_MODE_OVR_SW )
-#define MBG_PS_MSK_STR_MODE_OVR_DEV ( 1UL << MBG_PS_BIT_STR_MODE_OVR_DEV )
-#define MBG_PS_MSK_STR_MODE ( 1UL << MBG_PS_BIT_STR_MODE )
-#define MBG_PS_MSK_FLAGS_OVR_SW ( 1UL << MBG_PS_BIT_FLAGS_OVR_SW )
-#define MBG_PS_MSK_FLAGS ( 1UL << MBG_PS_BIT_FLAGS )
+/**
+ * @brief Flag bit masks associated with ::MBG_COM_CFG_STATUS_BITS
+ *
+ * These definitions can be used to mark specific fields of a
+ * ::PORT_SETTINGS structure, e.g. which fields have changed when
+ * editing, or which fields have settings which are not valid.
+ *
+ * @anchor MBG_COM_CFG_STATUS_MASKS @{ */
+#define MBG_PS_MSK_BAUD_RATE_OVR_SW ( 1UL << MBG_PS_BIT_BAUD_RATE_OVR_SW ) ///< see ::MBG_PS_BIT_BAUD_RATE_OVR_SW
+#define MBG_PS_MSK_BAUD_RATE_OVR_DEV ( 1UL << MBG_PS_BIT_BAUD_RATE_OVR_DEV ) ///< see ::MBG_PS_BIT_BAUD_RATE_OVR_DEV
+#define MBG_PS_MSK_BAUD_RATE ( 1UL << MBG_PS_BIT_BAUD_RATE ) ///< see ::MBG_PS_BIT_BAUD_RATE
+#define MBG_PS_MSK_FRAMING_OVR_SW ( 1UL << MBG_PS_BIT_FRAMING_OVR_SW ) ///< see ::MBG_PS_BIT_FRAMING_OVR_SW
+#define MBG_PS_MSK_FRAMING_OVR_DEV ( 1UL << MBG_PS_BIT_FRAMING_OVR_DEV ) ///< see ::MBG_PS_BIT_FRAMING_OVR_DEV
+#define MBG_PS_MSK_FRAMING ( 1UL << MBG_PS_BIT_FRAMING ) ///< see ::MBG_PS_BIT_FRAMING
+#define MBG_PS_MSK_HS_OVR_SW ( 1UL << MBG_PS_BIT_HS_OVR_SW ) ///< see ::MBG_PS_BIT_HS_OVR_SW
+#define MBG_PS_MSK_HS ( 1UL << MBG_PS_BIT_HS ) ///< see ::MBG_PS_BIT_HS
+#define MBG_PS_MSK_STR_TYPE_OVR_SW ( 1UL << MBG_PS_BIT_STR_TYPE_OVR_SW ) ///< see ::MBG_PS_BIT_STR_TYPE_OVR_SW
+#define MBG_PS_MSK_STR_TYPE_OVR_DEV ( 1UL << MBG_PS_BIT_STR_TYPE_OVR_DEV ) ///< see ::MBG_PS_BIT_STR_TYPE_OVR_DEV
+#define MBG_PS_MSK_STR_TYPE ( 1UL << MBG_PS_BIT_STR_TYPE ) ///< see ::MBG_PS_BIT_STR_TYPE
+#define MBG_PS_MSK_STR_MODE_OVR_SW ( 1UL << MBG_PS_BIT_STR_MODE_OVR_SW ) ///< see ::MBG_PS_BIT_STR_MODE_OVR_SW
+#define MBG_PS_MSK_STR_MODE_OVR_DEV ( 1UL << MBG_PS_BIT_STR_MODE_OVR_DEV ) ///< see ::MBG_PS_BIT_STR_MODE_OVR_DEV
+#define MBG_PS_MSK_STR_MODE ( 1UL << MBG_PS_BIT_STR_MODE ) ///< see ::MBG_PS_BIT_STR_MODE
+#define MBG_PS_MSK_FLAGS_OVR_SW ( 1UL << MBG_PS_BIT_FLAGS_OVR_SW ) ///< see ::MBG_PS_BIT_FLAGS_OVR_SW
+#define MBG_PS_MSK_FLAGS ( 1UL << MBG_PS_BIT_FLAGS ) ///< see ::MBG_PS_BIT_FLAGS
+/** @} anchor MBG_COM_CFG_STATUS_MASKS */
-/*
- * The structure below adds an index number to the structure
- * above to allow addressing of several instances:
+
+
+/**
+ * @brief Configuration settings of a specific serial port
+ *
+ * This structure should be sent to a device to configure
+ * a specific serial port. The number of supported ports
+ * is ::RECEIVER_INFO::n_com_ports.
+ *
+ * @note The ::PORT_INFO_IDX structure should be read from
+ * a device to retrieve the current settings and capabilities.
+ *
+ * @see ::STR_TYPE_INFO
*/
typedef struct
{
- uint16_t idx; /* 0..RECEIVER_INFO.n_com_port-1 */
+ uint16_t idx; ///< port index, 0..::RECEIVER_INFO::n_com_ports-1
PORT_SETTINGS port_settings;
+
} PORT_SETTINGS_IDX;
#define _mbg_swab_port_settings_idx( _p ) \
@@ -1907,21 +2823,24 @@ typedef struct
}
-/*
- * The structure below holds the current settings
- * for a port, plus additional informaton on the
- * port's capabilities. This can be read by setup
- * programs to allow setup of supported features
- * only.
+/**
+ * @brief Current settings and general capabilities of a serial port
+ *
+ * @note This structure should be read from a device to retrieve
+ * the current settings of a serial port plus its capabilities,
+ * e.g. supported baud rates, supported string formats, etc.
+ *
+ * @see ::STR_TYPE_INFO
*/
typedef struct
{
- PORT_SETTINGS port_settings; /* COM port settings as defined above */
- uint32_t supp_baud_rates; /* bit mask of baud rates supp. by this port */
- uint32_t supp_framings; /* bit mask of framings supp. by this port */
- uint32_t supp_str_types; /* bit mask, bit 0 set if str_type[0] supp. */
- uint32_t reserved; /* reserved for future use, currently 0 */
- uint32_t flags; /* reserved for future use, currently 0 */
+ PORT_SETTINGS port_settings; ///< current configuration of the port
+ uint32_t supp_baud_rates; ///< bit mask of baud rates supp. by this port, see ::MBG_BAUD_RATE_MASKS
+ uint32_t supp_framings; ///< bit mask of framings supp. by this port, see ::MBG_FRAMING_MASKS
+ uint32_t supp_str_types; ///< bit mask of string types supp. by this port, i.e. bit 0 set if str_type[0] is supp.
+ uint32_t reserved; ///< reserved for future use, currently always 0
+ uint32_t flags; ///< see ::PORT_INFO_FLAGS
+
} PORT_INFO;
#define _mbg_swab_port_info( _p ) \
@@ -1936,26 +2855,46 @@ typedef struct
/**
- * @brief Flags used with PORT_SETTINGS::flags and PORT_INFO::flags
+ * @brief Flags bits used to define ::PORT_INFO_FLAGS
+ *
+ * @see ::PORT_INFO_FLAGS
*/
-enum
+enum PORT_INFO_FLAG_BITS
{
- PORT_FLAG_BIT_PORT_INVISIBLE, /**< this port is used internally and should not be displayed by config apps */
- N_PORT_FLAGS /**< the number of defined bits */
+ PORT_INFO_FLAG_BIT_PORT_INVISIBLE, ///< port is used internally and should not be displayed by config apps
+ PORT_INFO_FLAG_BIT_BIN_PROT_HS, ///< port supports binary protocol at high speed, see ::MBG_DEFAULT_BAUDRATE_HS
+ N_PORT_INFO_FLAG_BITS ///< the number of defined bits
};
-#define PORT_FLAG_PORT_INVISIBLE ( 1UL << PORT_FLAG_BIT_PORT_INVISIBLE )
+/**
+ * @brief Bit masks used with ::PORT_INFO::flags
+ *
+ * @see ::PORT_INFO_FLAG_BITS
+ */
+enum PORT_INFO_FLAGS
+{
+ PORT_INFO_FLAG_PORT_INVISIBLE = ( 1UL << PORT_INFO_FLAG_BIT_PORT_INVISIBLE ), ///< see ::PORT_INFO_FLAG_BIT_PORT_INVISIBLE
+ PORT_INFO_FLAG_BIN_PROT_HS = ( 1UL << PORT_INFO_FLAG_BIT_BIN_PROT_HS ) ///< see ::PORT_INFO_FLAG_BIT_BIN_PROT_HS
+};
-/*
- * The structure below adds an index number to the structure
- * above to allow addressing of several instances:
+/**
+ * @brief Current settings and general capabilities of a specific serial port
+ *
+ * This structure should be read from the device to retrieve the
+ * current settings of a specific serial port plus its capabilities,
+ * e.g. supported baud rates, supported string formats, etc.
+ * The number of supported ports is ::RECEIVER_INFO::n_com_ports.
+ *
+ * @note The ::PORT_SETTINGS_IDX structure should be send back to
+ * the device to configure the specified serial port.
*/
typedef struct
{
- uint16_t idx; /* 0..RECEIVER_INFO.n_com_port-1 */
+ uint16_t idx; ///< port index, 0..::RECEIVER_INFO::n_com_ports-1
PORT_INFO port_info;
+
} PORT_INFO_IDX;
#define _mbg_swab_port_info_idx( _p ) \
@@ -1965,17 +2904,25 @@ typedef struct
}
-/*
- * The structure below keeps information for a given
- * string type, e.g. which modes can be used with that
- * string type:
+/**
+ * @brief Information on a supported string format
+ *
+ * Information includes the name of the string format, which
+ * transmission modes are supported, etc.
+ *
+ * The number of string types, and which string types are supported
+ * depends on the device type and firmware version.
+ *
+ * @note Multiple structures ::STR_TYPE_INFO_IDX should be read
+ * to retrieve all supported string types.
*/
typedef struct
{
- uint32_t supp_modes; /* bit mask of modes supp. with this string type */
- char long_name[23]; /* long name of the string format */
- char short_name[11]; /* short name of the string format */
- uint16_t flags; /* reserved, currently always 0 */
+ uint32_t supp_modes; ///< bit mask of modes supp. for this string type, see ::STR_MODE_MASKS
+ char long_name[23]; ///< long name of the string format
+ char short_name[11]; ///< short name of the string format
+ uint16_t flags; ///< reserved, currently always 0
+
} STR_TYPE_INFO;
#define _mbg_swab_str_type_info( _p ) \
@@ -1986,14 +2933,22 @@ typedef struct
-/*
- * The structure below adds an index number to the structure
- * above to allow addressing of several instances:
+/**
+ * @brief Information on a specific supported string format
+ *
+ * This structure should be read from a device to retrieve information
+ * on a specific supported time string type from an array of supported
+ * string types. The number of supported string types is returned
+ * in ::RECEIVER_INFO::n_str_type.
+ *
+ * A selected index number can be saved in ::PORT_SETTINGS::str_type to
+ * configure the selected string type for the specific serial port.
*/
typedef struct
{
- uint16_t idx; /* 0..RECEIVER_INFO.n_str_type-1 */
+ uint16_t idx; ///< string type index, 0..::RECEIVER_INFO::n_str_type-1
STR_TYPE_INFO str_type_info;
+
} STR_TYPE_INFO_IDX;
#define _mbg_swab_str_type_info_idx( _p ) \
@@ -2003,22 +2958,49 @@ typedef struct
}
-/*
- * The codes below define valid modes for time strings,
- * i.e. the condition when a string is being sent
- * via the serial port:
+/**
+ * @brief Enumeration of modes supported for time string transmission
+ *
+ * This determines e.g. at which point in time a string starts
+ * to be transmitted via the serial port.
+ * Used with ::PORT_SETTINGS::mode.
+ *
+ * @see ::STR_MODE_MASKS
*/
-enum
+enum STR_MODES
+{
+ STR_ON_REQ, ///< transmission on request by received '?' character only
+ STR_PER_SEC, ///< transmission automatically if second changes
+ STR_PER_MIN, ///< transmission automatically if minute changes
+ STR_AUTO, ///< transmission automatically if required, e.g. on capture event
+ STR_ON_REQ_SEC, ///< transmission if second changes and a request has been received before
+ N_STR_MODE ///< the number of known modes
+};
+
+
+/**
+ * @brief Bit masks associated with ::STR_MODES
+ *
+ * Used with ::STR_TYPE_INFO::supp_modes to indicate which
+ * transmission modes are supported by the particular string type.
+ *
+ * @see ::STR_MODES
+ */
+enum STR_MODE_MASKS
{
- STR_ON_REQ, /* on request only */
- STR_PER_SEC, /* automatically if second changes */
- STR_PER_MIN, /* automatically if minute changes */
- STR_AUTO, /* automatically if required, e.g. on capture event */
- STR_ON_REQ_SEC, /* if second changes and a request has been received */
- N_STR_MODE /* the number of valid modes */
+ MSK_STR_ON_REQ = ( 1UL << STR_ON_REQ ), ///< see ::STR_ON_REQ
+ MSK_STR_PER_SEC = ( 1UL << STR_PER_SEC ), ///< see ::STR_PER_SEC
+ MSK_STR_PER_MIN = ( 1UL << STR_PER_MIN ), ///< see ::STR_PER_MIN
+ MSK_STR_AUTO = ( 1UL << STR_AUTO ), ///< see ::STR_AUTO
+ MSK_STR_ON_REQ_SEC = ( 1UL << STR_ON_REQ_SEC ) ///< see ::STR_ON_REQ_SEC
};
+/**
+ * @brief Initializer for short name strings associated with ::STR_MODES
+ *
+ * @see ::STR_MODES
+ */
#define DEFAULT_SHORT_MODE_NAMES \
{ \
"'?'", \
@@ -2029,9 +3011,12 @@ enum
}
-/*
- * Default initializers for English mode string names. Initializers
- * for multi-language strings can be found in pcpslstr.h.
+/**
+ * @brief Default initializers for English mode name strings
+ *
+ * Initializers for multi-language strings can be found in pcpslstr.h.
+ *
+ * @see ::STR_MODES
*/
#define ENG_MODE_NAME_STR_ON_REQ "on request '?' only"
#define ENG_MODE_NAME_STR_PER_SEC "per second"
@@ -2039,6 +3024,14 @@ enum
#define ENG_MODE_NAME_STR_AUTO "automatically"
#define ENG_MODE_NAME_STR_ON_REQ_SEC "sec after request"
+
+/**
+ * @brief Initializer for an English mode name string table
+ *
+ * Initializers for multi-language strings can be found in pcpslstr.h.
+ *
+ * @see ::STR_MODES
+ */
#define DEFAULT_ENG_MODE_NAMES \
{ \
ENG_MODE_NAME_STR_ON_REQ, \
@@ -2048,17 +3041,6 @@ enum
ENG_MODE_NAME_STR_ON_REQ_SEC \
}
-/*
- * The definitions below are used to set up bit masks
- * which restrict the modes which can be used with
- * a given string type:
- */
-#define MSK_STR_ON_REQ ( 1UL << STR_ON_REQ )
-#define MSK_STR_PER_SEC ( 1UL << STR_PER_SEC )
-#define MSK_STR_PER_MIN ( 1UL << STR_PER_MIN )
-#define MSK_STR_AUTO ( 1UL << STR_AUTO )
-#define MSK_STR_ON_REQ_SEC ( 1UL << STR_ON_REQ_SEC )
-
/*
* The modes below are supported by most string types:
@@ -2082,9 +3064,11 @@ enum
-/**
- * The number of serial ports which were available
- * with all GPS receiver models:
+/*
+ * The number of serial ports which are at least available
+ * even with very old GPS receiver models. For devices providing
+ * a ::RECEIVER_INFO structure the number of provided COM ports
+ * is available in ::RECEIVER_INFO::n_com_ports.
*/
#define DEFAULT_N_COM 2
@@ -2097,13 +3081,16 @@ enum
#endif
/**
- * The structure used to store the modes of both serial ports:<br>
- * <b>(now obsolete)</b>
+ * @brief A The structure used to store the configuration of two serial ports
+ *
+ * @deprecated This structure is deprecated, ::PORT_SETTINGS and related structures
+ * should be used instead, if supported by the device.
*/
typedef struct
{
- COM_PARM com[DEFAULT_N_COM]; /**< COM0 and COM1 settings */
- uint8_t mode[DEFAULT_N_COM]; /**< COM0 and COM1 output mode */
+ COM_PARM com[DEFAULT_N_COM]; ///< COM0 and COM1 settings
+ uint8_t mode[DEFAULT_N_COM]; ///< COM0 and COM1 output mode
+
} PORT_PARM;
#define _mbg_swab_port_parm( _p ) \
@@ -2117,10 +3104,14 @@ typedef struct
}
-/*
- * The codes below were used with the obsolete
- * PORT_PARM.mode above. They are defined for
- * compatibility with older devices only:
+/**
+ * @brief Deprecated codes for mode of operation
+ *
+ * @deprecated These codes have been used with the
+ * deprecated ::PORT_PARM::mode. They are only still
+ * defined for compatibility with older devices.
+ *
+ * @see ::STR_MODES
*/
enum
{
@@ -2136,75 +3127,91 @@ enum
/**
- @defgroup group_icode IRIG codes
-
- The following definitions are used to configure an optional
- on-board IRIG input or output. Which frame types are supported
- by a device depends on the device type, and may eventually
- depend on the device's firmware version.
-
- All IRIG frames transport the day-of-year number plus the time-of-day,
- and include a control field segment which can transport user defined
- information.
-
- Some newer IRIG frames are compatible with older frame types but support
- well defined extensions like the year number, local time offset, DST status,
- etc., in the control fields:
-
- - Supported IRIG signal code types:
- - \b A002: 1000 bps, DCLS, time-of-year
- - \b A003: 1000 bps, DCLS, time-of-year, SBS
- - \b A132: 1000 bps, 10 kHz carrier, time-of-year
- - \b A133: 1000 bps, 10 kHz carrier, time-of-year, SBS
- - \b B002: 100 bps, DCLS, time-of-year
- - \b B003: 100 bps, DCLS, time-of-year, SBS
- - \b B122: 100 bps, 1 kHz carrier, time-of-year
- - \b B123: 100 bps, 1 kHz carrier, time-of-year, SBS
- - \b B006: 100 bps, DCLS, complete date
- - \b B007: 100 bps, DCLS, complete date, SBS
- - \b B126: 100 bps, 1 kHz carrier, complete date
- - \b B127: 100 bps, 1 kHz carrier, complete date, SBS
- - \b B220/1344: 100 bps, DCLS, manchester encoded, IEEE1344 extensions
- - \b B222: 100 bps, DCLS, manchester encoded, time-of-year
- - \b B223: 100 bps, DCLS, manchester encoded, time-of-year, SBS
- - \b G002: 10 kbps, DCLS, time-of-year
- - \b G142: 10 kbps, 100 kHz carrier, time-of-year
- - \b G006: 10 kbps, DCLS, complete date
- - \b G146: 10 kbps, 100 kHz carrier, complete date
- - \b AFNOR: 100 bps, 1 kHz carrier, SBS, complete date
- - <b> AFNOR DC:</b> 100 bps, DCLS, SBS, complete date
- - \b IEEE1344: 100 bps, 1 kHz carrier, time-of-year, SBS, IEEE1344 extensions (B120)
- - <b> IEEE1344 DC:</b> 100 bps, DCLS, time-of-year, SBS, IEEE1344 extensions (B000)
- - \b C37.118: like IEEE1344, but UTC offset with reversed sign
- - \b C37.118 DC: like IEEE1344 DC, but UTC offset with reversed sign
-
- - time-of-year: day-of-year, hours, minutes, seconds
- - complete date: time-of-year plus year number
- - SBS: straight binary seconds, second-of-day
-
- AFNOR codes are based on the french standard AFNOR NF S87-500
-
- IEEE1344 codes are defined in IEEE standard 1344-1995. The code frame is compatible
- with B002/B122 but provides some well defined extensions in the control field which
- include a quality indicator (time figure of merit, TFOM), year number, DST and leap
- second status, and local time offset from UTC.
-
- C37.118 codes are defined in IEEE standard C37.118-2005 which includes a revised version
- of the IEEE 1344 standard from 1995. These codes provide the same extensions as IEEE 1344
- but unfortunately define the UTC offset with reversed sign.
-
- @note There are 3rd party IRIG devices out there which apply the UTC offset as specified
- in C37.118, but claim to be compatible with IEEE 1344. So if local time is transmitted
- by the IRIG signal then care must be taken that the UTC offset is evaluated by the IRIG
- receiver in the same way as computed by the IRIG generator. Otherwise the UTC
- time computed by the receiver may be <b>wrong</b>.
- @{
- */
-
-/**
- * Definitions used with IRIG transmitters which usually output both
- * the unmodulated and the modulated IRIG signals at the same time: */
-enum
+ * @defgroup group_icode IRIG time codes
+ *
+ * The following definitions are used to configure an optional
+ * on-board IRIG input or output. Which frame types are supported
+ * by a device depends on the device type, and may eventually
+ * depend on the device's firmware version.
+ *
+ * All IRIG frames transport the day-of-year number plus the time-of-day,
+ * and include a control field segment which can transport user defined
+ * information.
+ *
+ * Some newer IRIG frames are compatible with older frame types but support
+ * well defined extensions like the year number, local time offset, DST status,
+ * etc., in the control fields:
+ *
+ * - Known IRIG signal code types:
+ * - \b A002: 1000 bps, DCLS, time-of-year
+ * - \b A003: 1000 bps, DCLS, time-of-year, SBS
+ * - \b A132: 1000 bps, 10 kHz carrier, time-of-year
+ * - \b A133: 1000 bps, 10 kHz carrier, time-of-year, SBS
+ * - \b B002: 100 bps, DCLS, time-of-year
+ * - \b B003: 100 bps, DCLS, time-of-year, SBS
+ * - \b B122: 100 bps, 1 kHz carrier, time-of-year
+ * - \b B123: 100 bps, 1 kHz carrier, time-of-year, SBS
+ * - \b B006: 100 bps, DCLS, complete date
+ * - \b B007: 100 bps, DCLS, complete date, SBS
+ * - \b B126: 100 bps, 1 kHz carrier, complete date
+ * - \b B127: 100 bps, 1 kHz carrier, complete date, SBS
+ * - \b B220/1344: 100 bps, DCLS, manchester encoded, IEEE1344 extensions
+ * - \b B222: 100 bps, DCLS, manchester encoded, time-of-year
+ * - \b B223: 100 bps, DCLS, manchester encoded, time-of-year, SBS
+ * - \b G002: 10 kbps, DCLS, time-of-year
+ * - \b G142: 10 kbps, 100 kHz carrier, time-of-year
+ * - \b G006: 10 kbps, DCLS, complete date
+ * - \b G146: 10 kbps, 100 kHz carrier, complete date
+ * - \b AFNOR: 100 bps, 1 kHz carrier, SBS, complete date
+ * - \b AFNOR DC: 100 bps, DCLS, SBS, complete date
+ * - \b IEEE1344: 100 bps, 1 kHz carrier, time-of-year, SBS, IEEE 1344 extensions (B120)
+ * - \b IEEE1344 DC: 100 bps, DCLS, time-of-year, SBS, IEEE 1344 extensions (B000)
+ * - \b C37.118: like IEEE 1344, but %UTC offset applied with reversed sign
+ * - \b C37.118 DC: like IEEE 1344 DC, but %UTC offset applied with reversed sign
+ *
+ * - time-of-year: day-of-year, hours, minutes, seconds
+ * - complete date: time-of-year plus year number
+ * - SBS: straight binary seconds, second-of-day
+ *
+ * AFNOR codes are based on the french standard AFNOR NF S87-500
+ *
+ * IEEE 1344 codes are defined in IEEE standard 1344-1995. The code frame is compatible
+ * with B002/B122 but provides some well defined extensions in the control field which
+ * include a quality indicator (time figure of merit, TFOM), year number, DST and leap
+ * second status, and local time offset from %UTC.
+ *
+ * IEEE C37.118 codes are defined in IEEE standard C37.118-2005 which includes a revised version
+ * of the IEEE 1344 standard from 1995. These codes provide the same extensions as IEEE 1344
+ * but unfortunately determine that the %UTC offset has to be applied with reversed sign.
+ *
+ * For example, if a -6 hours UTC offset is transmitted in the time code:<br>
+ * IEEE 1344: (IRIG time 14:43:27 h) - (offs -6 h) = (UTC 20:43:27)<br>
+ * IEEE C37.118: (IRIG time 14:43:27 h) + (offs -6 h) = (UTC 08:43:27)<br>
+ *
+ * @see @ref MSK_ICODE_RX_UTC_OFFS_ADD and @ref MSK_ICODE_RX_UTC_OFFS_SUB
+ *
+ * @note There are 3rd party IRIG devices out there which apply the %UTC offset as specified
+ * in IEEE C37.118-2005, but claim to be compatible with IEEE 1344. So if local time is transmitted
+ * by the timecode then care must be taken that the %UTC offset is evaluated by the timecode
+ * receiver in the same way as computed by the timecode generator. Otherwise the %UTC
+ * time computed by the receiver may be <b>wrong</b>.
+ *
+ * @{ */
+
+/**
+ * @brief Known IRIG TX code formats
+ *
+ * Used with ::IRIG_SETTINGS::icode for IRIG transmitters.
+ * For IRIG receivers see ::ICODE_RX_CODES.
+ *
+ * Meinberg timecode transmitters always generate the unmodulated (DCLS)
+ * and usually the modulated timecode signals internally at the same time,
+ * so the code definitions always refer to both.
+ *
+ * @note Not all device may provide both the modulated and unmodulated
+ * signal externally.
+ */
+enum ICODE_TX_CODES
{
ICODE_TX_B002_B122,
ICODE_TX_B003_B123,
@@ -2212,20 +3219,25 @@ enum
ICODE_TX_A003_A133,
ICODE_TX_AFNOR,
ICODE_TX_IEEE1344,
- ICODE_TX_B2201344, // DCLS only
- ICODE_TX_B222, // DCLS only
- ICODE_TX_B223, // DCLS only
+ ICODE_TX_B2201344, ///< DCLS only
+ ICODE_TX_B222, ///< DCLS only
+ ICODE_TX_B223, ///< DCLS only
ICODE_TX_B006_B126,
ICODE_TX_B007_B127,
ICODE_TX_G002_G142,
ICODE_TX_G006_G146,
ICODE_TX_C37118,
- N_ICODE_TX /**< number of code types */
+ ICODE_TX_TXC101,
+ ICODE_TX_E002_E112,
+ ICODE_TX_NASA36,
+ N_ICODE_TX ///< number of known codes
};
/**
- * Initializers for format name strings.
+ * @brief Initializers for timecode format name strings
+ *
+ * @see ::ICODE_TX_CODES
*/
#define DEFAULT_ICODE_TX_NAMES \
{ \
@@ -2242,12 +3254,18 @@ enum
"B007+B127", \
"G002+G142", \
"G006+G146", \
- "C37.118" \
+ "C37.118", \
+ "TXC-101 DTR-6", \
+ "E002+E112", \
+ "NASA 36" \
}
/**
- * Initializers for short name strings which must not
- * be longer than 10 printable characters.
+ * @brief Initializers for short timecode format name strings
+ *
+ * @note Must not be longer than 10 printable characters
+ *
+ * @see ::ICODE_TX_CODES
*/
#define DEFAULT_ICODE_TX_NAMES_SHORT \
{ \
@@ -2255,7 +3273,7 @@ enum
"B003+B123", \
"A002+A132", \
"A003+A133", \
- "AFNOR NF-S", \
+ "AFNOR NF S", \
"IEEE1344", \
"B220/1344", \
"B222 DC", \
@@ -2264,12 +3282,17 @@ enum
"B007+B127", \
"G002+G142", \
"G006+G146", \
- "C37.118" \
+ "C37.118", \
+ "TXC-101", \
+ "E002+E112", \
+ "NASA 36" \
}
/**
- * Initializers for English format description strings.
+ * @brief Initializers for English format description strings
+ *
+ * @see ::ICODE_TX_CODES
*/
#define DEFAULT_ICODE_TX_DESCRIPTIONS_ENG \
{ \
@@ -2286,14 +3309,24 @@ enum
"100 bps, DCLS or 1 kHz carrier, complete date, SBS", \
"10 kbps, DCLS or 100 kHz carrier", \
"10 kbps, DCLS or 100 kHz carrier, complete date", \
- "like IEEE1344, but UTC offset with reversed sign" \
+ "like IEEE1344, but UTC offset with reversed sign", \
+ "code from TV time sync device TXC-101 DTR-6", \
+ "10 bps, DCLS or 100 Hz carrier", \
+ "100 bps, DCLS or 1 kHz carrier" \
}
-/*
- * The definitions below are used to set up bit masks
- * which restrict the IRIG formats which are supported
- * by a given IRIG transmitter device:
- */
+
+/**
+ * @brief Bit masks used with ::IRIG_INFO::supp_codes
+ *
+ * These bit masks are used with timecode receivers only
+ *
+ * @see @ref ICODE_TX_CODES
+ * @see @ref ICODE_RX_CODES
+ * @see @ref ICODE_RX_MASKS
+ *
+ * @anchor ICODE_TX_MASKS @{ */
+
#define MSK_ICODE_TX_B002_B122 ( 1UL << ICODE_TX_B002_B122 )
#define MSK_ICODE_TX_B003_B123 ( 1UL << ICODE_TX_B003_B123 )
#define MSK_ICODE_TX_A002_A132 ( 1UL << ICODE_TX_A002_A132 )
@@ -2308,19 +3341,33 @@ enum
#define MSK_ICODE_TX_G002_G142 ( 1UL << ICODE_TX_G002_G142 )
#define MSK_ICODE_TX_G006_G146 ( 1UL << ICODE_TX_G006_G146 )
#define MSK_ICODE_TX_C37118 ( 1UL << ICODE_TX_C37118 )
+#define MSK_ICODE_TX_TXC101 ( 1UL << ICODE_TX_TXC101 )
+#define MSK_ICODE_TX_E002_E112 ( 1UL << ICODE_TX_E002_E112 )
+#define MSK_ICODE_TX_NASA36 ( 1UL << ICODE_TX_NASA36 )
+
+/** @} anchor ICODE_TX_MASKS */
+
/**
- * A mask of IRIG formats with manchester encoded DC output:
+ * @brief A mask of IRIG formats with manchester encoded DC output
*/
#define MSK_ICODE_TX_DC_MANCH \
( \
- MSK_ICODE_TX_B2201344 | \
- MSK_ICODE_TX_B222 | \
+ MSK_ICODE_TX_B2201344 | \
+ MSK_ICODE_TX_B222 | \
MSK_ICODE_TX_B223 \
)
/**
- * A mask of IRIG formats with 1 kHz carrier:
+ * @brief A mask of IRIG formats with 100 Hz carrier
+ */
+#define MSK_ICODE_TX_100HZ \
+( \
+ MSK_ICODE_TX_E002_E112 \
+)
+
+/**
+ * @brief A mask of IRIG formats with 1 kHz carrier
*/
#define MSK_ICODE_TX_1KHZ \
( \
@@ -2333,11 +3380,12 @@ enum
MSK_ICODE_TX_B223 | \
MSK_ICODE_TX_B006_B126 | \
MSK_ICODE_TX_B007_B127 | \
- MSK_ICODE_TX_C37118 \
+ MSK_ICODE_TX_C37118 | \
+ MSK_ICODE_TX_NASA36 \
)
/**
- * A mask of IRIG formats with 10 kHz carrier:
+ * @brief A mask of IRIG formats with 10 kHz carrier
*/
#define MSK_ICODE_TX_10KHZ \
( \
@@ -2346,67 +3394,163 @@ enum
)
/**
- * A mask of IRIG formats with 100 kHz carrier:
+ * @brief A mask of IRIG formats with 100 kHz carrier
*/
#define MSK_ICODE_TX_100KHZ \
( \
- MSK_ICODE_TX_G002_G142 | \
+ MSK_ICODE_TX_G002_G142 | \
MSK_ICODE_TX_G006_G146 \
)
/**
- * A mask of IRIG formats with 100 bps data rate:
+ * @brief A mask of IRIG formats with 10 bps data rate
+ */
+#define MSK_ICODE_TX_10BPS \
+( \
+ MSK_ICODE_TX_E002_E112 \
+)
+
+/**
+ * @brief A mask of IRIG formats with 100 bps data rate
*/
#define MSK_ICODE_TX_100BPS \
( \
- MSK_ICODE_TX_B002_B122 | \
- MSK_ICODE_TX_B003_B123 | \
- MSK_ICODE_TX_AFNOR | \
- MSK_ICODE_TX_IEEE1344 | \
- MSK_ICODE_TX_B006_B126 | \
- MSK_ICODE_TX_B007_B127 | \
+ MSK_ICODE_TX_B002_B122 | \
+ MSK_ICODE_TX_B003_B123 | \
+ MSK_ICODE_TX_AFNOR | \
+ MSK_ICODE_TX_IEEE1344 | \
+ MSK_ICODE_TX_B006_B126 | \
+ MSK_ICODE_TX_B007_B127 | \
MSK_ICODE_TX_C37118 \
)
/**
- * A mask of IRIG formats with 1000 bps data rate:
+ * @brief A mask of IRIG formats with 1000 bps data rate
*/
#define MSK_ICODE_TX_1000BPS \
( \
- MSK_ICODE_TX_A002_A132 | \
+ MSK_ICODE_TX_A002_A132 | \
MSK_ICODE_TX_A003_A133 \
)
/**
- * A mask of IRIG formats with 10 kbps data rate:
+ * @brief A mask of IRIG formats with 10 kbps data rate
*/
#define MSK_ICODE_TX_10000BPS \
( \
- MSK_ICODE_TX_G002_G142 | \
+ MSK_ICODE_TX_G002_G142 | \
MSK_ICODE_TX_G006_G146 \
)
/**
- * A mask of IRIG formats which support TFOM:
+ * @brief A mask of IRIG formats supporting 10ths of seconds
+ */
+#define MSK_ICODE_TX_HAS_SEC10THS \
+( \
+ MSK_ICODE_TX_A002_A132 | \
+ MSK_ICODE_TX_A003_A133 | \
+ MSK_ICODE_TX_G002_G142 | \
+ MSK_ICODE_TX_G006_G146 \
+)
+
+/**
+ * @brief A mask of IRIG formats supporting 100ths of seconds
+ */
+#define MSK_ICODE_TX_HAS_SEC100THS \
+( \
+ MSK_ICODE_TX_G002_G142 | \
+ MSK_ICODE_TX_G006_G146 \
+)
+
+/**
+ * @brief A mask of IRIG formats supporting a 2 digit year number
+ */
+#define MSK_ICODE_TX_HAS_SHORT_YEAR \
+( \
+ MSK_ICODE_TX_AFNOR | \
+ MSK_ICODE_TX_IEEE1344 | \
+ MSK_ICODE_TX_B006_B126 | \
+ MSK_ICODE_TX_B007_B127 | \
+ MSK_ICODE_TX_C37118 \
+)
+
+/**
+ * @brief A mask of IRIG formats supporting TFOM
*/
#define MSK_ICODE_TX_HAS_TFOM \
( \
- MSK_ICODE_TX_IEEE1344 | \
+ MSK_ICODE_TX_IEEE1344 | \
+ MSK_ICODE_TX_C37118 \
+)
+
+/**
+ * @brief A mask of IRIG formats supporting CTQ continuous time quality
+ *
+ * This has been introduced in IEEE C37.118.1-2011
+ */
+#define MSK_ICODE_TX_HAS_CTQ \
+( \
+ MSK_ICODE_TX_IEEE1344 | \
MSK_ICODE_TX_C37118 \
)
/**
- * A mask of IRIG formats which support time zone information:
+ * @brief A mask of IRIG formats supporting time zone information
*/
#define MSK_ICODE_TX_HAS_TZI \
( \
- MSK_ICODE_TX_IEEE1344 | \
+ MSK_ICODE_TX_IEEE1344 | \
MSK_ICODE_TX_C37118 \
)
/**
- * The default mask of IRIG formats supported by
- * IRIG transmitters:
+ * @brief IRIG formats where UTC offset must be subtracted to yield UTC
+ *
+ * A mask of IRIG formats where the decoded UTC offset must be
+ * subtracted from the time decoded from the IRIG signal to yield UTC, e.g.:<br>
+ * (IRIG time 14:43:27 h) - (offs -6 h) = (UTC 20:43:27)
+ */
+#define MSK_ICODE_TX_UTC_OFFS_SUB \
+( \
+ MSK_ICODE_TX_IEEE1344 \
+)
+
+/**
+ * @brief IRIG formats where UTC offset must be added to yield UTC
+ *
+ * A mask of IRIG formats where the decoded UTC offset must be
+ * added to the time decoded from the IRIG signal to yield UTC, e.g.:<br>
+ * (IRIG time 14:43:27 h) + (offs -6 h) = (UTC 08:43:27)
+ */
+#define MSK_ICODE_TX_UTC_OFFS_ADD \
+( \
+ MSK_ICODE_TX_C37118 \
+)
+
+/**
+ * @brief A mask of IRIG formats supporting a day of week number
+ */
+#define MSK_ICODE_TX_HAS_AFNOR_WDAY \
+( \
+ MSK_ICODE_TX_AFNOR | \
+ MSK_ICODE_TX_AFNOR_DC \
+)
+
+/**
+ * @brief A mask of IRIG formats supporting a date (day-of-month, month)
+ */
+#define MSK_ICODE_TX_HAS_AFNOR_DATE \
+( \
+ MSK_ICODE_TX_AFNOR | \
+ MSK_ICODE_TX_AFNOR_DC \
+)
+
+
+/**
+ * @brief The default mask of IRIG formats supported by IRIG transmitters
+ *
+ * @note The formats which are actually supported should be retrieved
+ * from the device
*/
#if !defined( SUPP_MSK_ICODE_TX )
#define SUPP_MSK_ICODE_TX \
@@ -2422,33 +3566,46 @@ enum
/**
- * Definitions used with IRIG receivers which decode
- * two similar IRIG codes (with or without SBS)
- * at the same time.
- */
-enum
-{
- ICODE_RX_B122_B123, // modulated
- ICODE_RX_A132_A133, // modulated
- ICODE_RX_B002_B003, // DCLS
- ICODE_RX_A002_A003, // DCLS
- ICODE_RX_AFNOR, // modulated
- ICODE_RX_AFNOR_DC, // DCLS
- ICODE_RX_IEEE1344, // modulated
- ICODE_RX_IEEE1344_DC, // DCLS
- ICODE_RX_B126_B127, // modulated
- ICODE_RX_B006_B007, // DCLS
- ICODE_RX_G142_G146, // modulated
- ICODE_RX_G002_G006, // DCLS
- ICODE_RX_C37118, // modulated
- ICODE_RX_C37118_DC, // DCLS
- ICODE_RX_TXC_101, // modulated
- ICODE_RX_TXC_101_DC, // DCLS
- N_ICODE_RX /* the number of valid signal code types */
+ * @brief Known IRIG RX code formats
+ *
+ * Used with ::IRIG_SETTINGS::icode for IRIG receivers.
+ * For IRIG transmitters see ::ICODE_TX_CODES.
+ *
+ * The SBS value is redundant and can easily by computed
+ * from the time-of-day, so Meinberg time code receivers
+ * usually don't evaluate the SBS field anyway, and thus
+ * it makes no difference if a code with or withour SBS
+ * is supplied.
+ */
+enum ICODE_RX_CODES
+{
+ ICODE_RX_B122_B123, ///< modulated
+ ICODE_RX_A132_A133, ///< modulated
+ ICODE_RX_B002_B003, ///< DCLS
+ ICODE_RX_A002_A003, ///< DCLS
+ ICODE_RX_AFNOR, ///< modulated
+ ICODE_RX_AFNOR_DC, ///< DCLS
+ ICODE_RX_IEEE1344, ///< modulated
+ ICODE_RX_IEEE1344_DC, ///< DCLS
+ ICODE_RX_B126_B127, ///< modulated
+ ICODE_RX_B006_B007, ///< DCLS
+ ICODE_RX_G142_G146, ///< modulated
+ ICODE_RX_G002_G006, ///< DCLS
+ ICODE_RX_C37118, ///< modulated
+ ICODE_RX_C37118_DC, ///< DCLS
+ ICODE_RX_TXC101, ///< modulated
+ ICODE_RX_TXC101_DC, ///< DCLS
+ ICODE_RX_E112, ///< modulated
+ ICODE_RX_E002, ///< DCLS
+ ICODE_RX_NASA36, ///< modulated
+ ICODE_RX_NASA36_DC, ///< DCLS
+ N_ICODE_RX ///< the number of known codes
};
/**
- * Initializers for format name strings.
+ * @brief Initializers for timecode format name strings
+ *
+ * @see ::ICODE_RX_CODES
*/
#define DEFAULT_ICODE_RX_NAMES \
{ \
@@ -2467,12 +3624,19 @@ enum
"C37.118", \
"C37.118 (DCLS)", \
"TXC-101 DTR-6", \
- "TXC-101 DTR-6 (DCLS)" \
+ "TXC-101 DTR-6 (DCLS)", \
+ "E112", \
+ "E002 (DCLS)", \
+ "NASA-36", \
+ "NASA-36 (DCLS)" \
}
/**
- * Initializers for short name strings which must not
- * be longer than 11 printable characters.
+ * @brief Initializers for short timecode format name strings
+ *
+ * @note Must not be longer than 11 printable characters
+ *
+ * @see ::ICODE_RX_CODES
*/
#define DEFAULT_ICODE_RX_NAMES_SHORT \
{ \
@@ -2480,7 +3644,7 @@ enum
"A132/A133", \
"B002/B003", \
"A002/A003", \
- "AFNOR NF-S", \
+ "AFNOR NF S", \
"AFNOR DC", \
"IEEE1344", \
"IEEE1344 DC", \
@@ -2491,12 +3655,18 @@ enum
"C37.118", \
"C37.118 DC", \
"TXC-101", \
- "TXC-101 DC" \
+ "TXC-101 DC", \
+ "E112", \
+ "E002 DC", \
+ "NASA-36", \
+ "NASA-36 DC" \
}
/**
- * Initializers for English format description strings.
+ * @brief Initializers for English format description strings
+ *
+ * @see ::ICODE_RX_CODES
*/
#define DEFAULT_ICODE_RX_DESCRIPTIONS_ENG \
{ \
@@ -2515,12 +3685,24 @@ enum
"like IEEE1344, but UTC offset with reversed sign", \
"like IEEE1344 DC, but UTC offset with reversed sign", \
"code from TV time sync device TXC-101 DTR-6", \
- "DC code from TV time sync device TXC-101 DTR-6" \
+ "DC code from TV time sync device TXC-101 DTR-6", \
+ "10 bps, 100 Hz carrier", \
+ "10 bps, DCLS", \
+ "100 bps, 1 kHz carrier", \
+ "100 bps, DCLS" \
}
-/*
- * Bit masks corresponding to the enumeration above:
- */
+/**
+ * @brief Bit masks used with ::IRIG_INFO::supp_codes
+ *
+ * These bit masks are used with timecode receivers only
+ *
+ * @see @ref ICODE_RX_CODES
+ * @see @ref ICODE_TX_CODES
+ * @see @ref ICODE_TX_MASKS
+ *
+ * @anchor ICODE_RX_MASKS @{ */
+
#define MSK_ICODE_RX_B122_B123 ( 1UL << ICODE_RX_B122_B123 )
#define MSK_ICODE_RX_A132_A133 ( 1UL << ICODE_RX_A132_A133 )
#define MSK_ICODE_RX_B002_B003 ( 1UL << ICODE_RX_B002_B003 )
@@ -2535,11 +3717,18 @@ enum
#define MSK_ICODE_RX_G002_G006 ( 1UL << ICODE_RX_G002_G006 )
#define MSK_ICODE_RX_C37118 ( 1UL << ICODE_RX_C37118 )
#define MSK_ICODE_RX_C37118_DC ( 1UL << ICODE_RX_C37118_DC )
-#define MSK_ICODE_RX_TXC_101 ( 1UL << ICODE_RX_TXC_101 )
-#define MSK_ICODE_RX_TXC_101_DC ( 1UL << ICODE_RX_TXC_101_DC )
+#define MSK_ICODE_RX_TXC101 ( 1UL << ICODE_RX_TXC101 )
+#define MSK_ICODE_RX_TXC101_DC ( 1UL << ICODE_RX_TXC101_DC )
+#define MSK_ICODE_RX_E112 ( 1UL << ICODE_RX_E112 )
+#define MSK_ICODE_RX_E002 ( 1UL << ICODE_RX_E002 )
+#define MSK_ICODE_RX_NASA36 ( 1UL << ICODE_RX_NASA36 )
+#define MSK_ICODE_RX_NASA36_DC ( 1UL << ICODE_RX_NASA36_DC )
+
+/** @} anchor ICODE_RX_MASKS */
+
/**
- * A mask of IRIG DCLS formats:
+ * @brief A mask of IRIG DCLS formats
*/
#define MSK_ICODE_RX_DC \
( \
@@ -2550,11 +3739,22 @@ enum
MSK_ICODE_RX_B006_B007 | \
MSK_ICODE_RX_G002_G006 | \
MSK_ICODE_RX_C37118_DC | \
- MSK_ICODE_RX_TXC_101_DC \
+ MSK_ICODE_RX_TXC101_DC | \
+ MSK_ICODE_RX_E002 | \
+ MSK_ICODE_RX_NASA36_DC \
+)
+
+/**
+ * @brief A mask of IRIG formats with 100 Hz carrier
+ */
+#define MSK_ICODE_RX_100HZ \
+( \
+ MSK_ICODE_RX_E112 | \
+ MSK_ICODE_RX_E002 \
)
/**
- * A mask of IRIG formats with 1 kHz carrier:
+ * @brief A mask of IRIG formats with 1 kHz carrier
*/
#define MSK_ICODE_RX_1KHZ \
( \
@@ -2563,11 +3763,12 @@ enum
MSK_ICODE_RX_IEEE1344 | \
MSK_ICODE_RX_B126_B127 | \
MSK_ICODE_RX_C37118 | \
- MSK_ICODE_RX_TXC_101 \
+ MSK_ICODE_RX_TXC101 | \
+ MSK_ICODE_RX_NASA36 \
)
/**
- * A mask of IRIG formats with 10 kHz carrier:
+ * @brief A mask of IRIG formats with 10 kHz carrier
*/
#define MSK_ICODE_RX_10KHZ \
( \
@@ -2575,7 +3776,7 @@ enum
)
/**
- * A mask of IRIG formats with 100 kHz carrier:
+ * @brief A mask of IRIG formats with 100 kHz carrier
*/
#define MSK_ICODE_RX_100KHZ \
( \
@@ -2583,7 +3784,16 @@ enum
)
/**
- * A mask of IRIG formats with 100 bps data rate:
+ * @brief A mask of IRIG formats with 10 bps data rate
+ */
+#define MSK_ICODE_RX_10BPS \
+( \
+ MSK_ICODE_RX_E002_E112 | \
+ MSK_ICODE_RX_E002_E002 \
+)
+
+/**
+ * @brief A mask of IRIG formats with 100 bps data rate
*/
#define MSK_ICODE_RX_100BPS \
( \
@@ -2597,30 +3807,67 @@ enum
MSK_ICODE_RX_B006_B007 | \
MSK_ICODE_RX_C37118 | \
MSK_ICODE_RX_C37118_DC | \
- MSK_ICODE_RX_TXC_101 | \
- MSK_ICODE_RX_TXC_101_DC \
+ MSK_ICODE_RX_TXC101 | \
+ MSK_ICODE_RX_TXC101_DC | \
+ MSK_ICODE_RX_NASA36 | \
+ MSK_ICODE_RX_NASA36_DC \
)
/**
- * A mask of IRIG formats with 1000 bps data rate:
+ * @brief A mask of IRIG formats with 1000 bps data rate
*/
#define MSK_ICODE_RX_1000BPS \
( \
- MSK_ICODE_RX_A132_A133 | \
+ MSK_ICODE_RX_A132_A133 | \
MSK_ICODE_RX_A002_A003 \
)
/**
- * A mask of IRIG formats with 10 kbps data rate:
+ * @brief A mask of IRIG formats with 10 kbps data rate
*/
#define MSK_ICODE_RX_10000BPS \
( \
- MSK_ICODE_RX_G142_G146 | \
+ MSK_ICODE_RX_G142_G146 | \
MSK_ICODE_RX_G002_G006 \
)
/**
- * A mask of IRIG formats which support TFOM:
+ * @brief A mask of IRIG formats supporting 10ths of seconds
+ */
+#define MSK_ICODE_RX_HAS_SEC10THS \
+( \
+ MSK_ICODE_RX_A132_A133 | \
+ MSK_ICODE_RX_A002_A003 | \
+ MSK_ICODE_RX_G142_G146 | \
+ MSK_ICODE_RX_G002_G006 \
+)
+
+/**
+ * @brief A mask of IRIG formats which support 100ths of seconds
+ */
+#define MSK_ICODE_RX_HAS_SEC100THS \
+( \
+ MSK_ICODE_RX_G142_G146 | \
+ MSK_ICODE_RX_G002_G006 \
+)
+
+/**
+ * @brief A mask of IRIG formats supporting a 2 digit year number
+ */
+#define MSK_ICODE_RX_HAS_SHORT_YEAR \
+( \
+ MSK_ICODE_RX_AFNOR | \
+ MSK_ICODE_RX_AFNOR_DC | \
+ MSK_ICODE_RX_IEEE1344 | \
+ MSK_ICODE_RX_IEEE1344_DC | \
+ MSK_ICODE_RX_B126_B127 | \
+ MSK_ICODE_RX_B006_B007 | \
+ MSK_ICODE_RX_C37118 | \
+ MSK_ICODE_RX_C37118_DC \
+)
+
+/**
+ * @brief A mask of IRIG formats supporting TFOM time quality indicator
*/
#define MSK_ICODE_RX_HAS_TFOM \
( \
@@ -2631,7 +3878,20 @@ enum
)
/**
- * A mask of IRIG formats which support time zone information:
+ * @brief A mask of IRIG formats supporting CTQ continuous time quality
+ *
+ * This has been introduced in IEEE C37.118.1-2011
+ */
+#define MSK_ICODE_RX_HAS_CTQ \
+( \
+ MSK_ICODE_RX_IEEE1344 | \
+ MSK_ICODE_RX_IEEE1344_DC | \
+ MSK_ICODE_RX_C37118 | \
+ MSK_ICODE_RX_C37118_DC \
+)
+
+/**
+ * @brief A mask of IRIG formats supporting time zone information
*/
#define MSK_ICODE_RX_HAS_TZI \
( \
@@ -2642,8 +3902,55 @@ enum
)
/**
- * The default mask of IRIG formats supported by
- * IRIG receivers:
+ * @brief IRIG formats where UTC offset must be subtracted to yield UTC
+ *
+ * A mask of IRIG formats where the decoded UTC offset must be
+ * subtracted from the time decoded from the IRIG signal to yield UTC, e.g.:<br>
+ * (IRIG time 14:43:27 h) - (offs -6 h) = (UTC 20:43:27)
+ */
+#define MSK_ICODE_RX_UTC_OFFS_SUB \
+( \
+ MSK_ICODE_RX_IEEE1344 | \
+ MSK_ICODE_RX_IEEE1344_DC \
+)
+
+/**
+ * @brief IRIG formats where UTC offset must be added to yield UTC
+ *
+ * A mask of IRIG formats where the decoded UTC offset must be
+ * added to the time decoded from the IRIG signal to yield UTC, e.g.:<br>
+ * (IRIG time 14:43:27 h) + (offs -6 h) = (UTC 08:43:27)
+ */
+#define MSK_ICODE_RX_UTC_OFFS_ADD \
+( \
+ MSK_ICODE_RX_C37118 | \
+ MSK_ICODE_RX_C37118_DC \
+)
+
+/**
+ * @brief A mask of IRIG formats supporting a day of week number
+ */
+#define MSK_ICODE_RX_HAS_AFNOR_WDAY \
+( \
+ MSK_ICODE_RX_AFNOR | \
+ MSK_ICODE_RX_AFNOR_DC \
+)
+
+/**
+ * @brief A mask of IRIG formats supporting a date (day-of-month, month)
+ */
+#define MSK_ICODE_RX_HAS_AFNOR_DATE \
+( \
+ MSK_ICODE_RX_AFNOR | \
+ MSK_ICODE_RX_AFNOR_DC \
+)
+
+
+/**
+ * @brief The default mask of IRIG formats supported by IRIG receivers
+ *
+ * @note The formats which are actually supported should be retrieved
+ * from the device
*/
#if !defined( SUPP_MSK_ICODE_RX )
#define SUPP_MSK_ICODE_RX \
@@ -2657,18 +3964,20 @@ enum
)
#endif
-/** @} group_icode */
+/** @} defgroup group_icode */
/**
- * The structure below is used to configure an optional
- * on-board IRIG output:
+ * @brief Configuration settings of an IRIG input or output
+ *
+ * @see @ref group_icode
*/
typedef struct
{
- uint16_t icode; /**< IRIG signal code, see \ref group_icode */
- uint16_t flags; /**< see \ref group_irig_flags */
+ uint16_t icode; ///< IRIG signal code, see ::ICODE_RX_CODES and ::ICODE_TX_CODES
+ uint16_t flags; ///< see ::IFLAGS_BIT_MASKS
+
} IRIG_SETTINGS;
#define _mbg_swab_irig_settings( _p ) \
@@ -2678,35 +3987,51 @@ typedef struct
}
+
/**
- * @defgroup group_irig_flags Bit Masks used with IRIG_SETTINGS::flags
+ * @brief Flag bits used to define ::IFLAGS_BIT_MASKS
*
- * (others are reserved)
- * @{
+ * @see ::IFLAGS_BIT_MASKS
*/
-#define IFLAGS_DISABLE_TFOM 0x0001 /**< RX ignore/TX don't gen TFOM */
-#define IFLAGS_TX_GEN_LOCAL_TIME 0x0002 /**< gen local time, not UTC */
+enum IFLAGS_BITS
+{
+ IFLAGS_BIT_DISABLE_TFOM, ///< for RX ignore, for TX don't generate TFOM flag
+ IFLAGS_BIT_TX_GEN_LOCAL_TIME, ///< TX output local time instead of %UTC
+ N_IFLAGS_BITS ///< number of known bits
+};
+
-#define IFLAGS_MASK 0x0003 /**< flags above or'ed */
+/**
+ * @brief Bit masks used with ::IRIG_SETTINGS::flags
+ *
+ * @note The presence or absence of the ::IFLAGS_DISABLE_TFOM flag for the IRIG RX
+ * settings of some PCI cards may not be evaluated correctly by some firmware
+ * versions for those cards, even if an IRIG code has been configured which supports
+ * this flag. See the comments near the declaration of the ::_pcps_incoming_tfom_ignored
+ * macro in pcpsdev.h for details.
+ *
+ * @see ::IFLAGS_BITS
+ */
+enum IFLAGS_BIT_MASKS
+{
+ IFLAGS_DISABLE_TFOM = ( 1UL << IFLAGS_BIT_DISABLE_TFOM ), ///< see ::IFLAGS_BIT_DISABLE_TFOM
+ IFLAGS_TX_GEN_LOCAL_TIME = ( 1UL << IFLAGS_BIT_TX_GEN_LOCAL_TIME ), ///< see ::IFLAGS_BIT_TX_GEN_LOCAL_TIME
-// Note: the presence or absence of the IFLAGS_DISABLE_TFOM flag for the IRIG RX
-// settings of some PCI cards may not be evaluated correctly by some firmware
-// versions for those cards, even if an IRIG code has been configured which supports
-// this flag. See the comments near the declaration of the _pcps_incoming_tfom_ignored()
-// macro in pcpsdev.h for details.
+ IFLAGS_MASK = ( ( 1UL << N_IFLAGS_BITS ) - 1 ) ///< mask of all known flags
+};
-/** @} group_irig_flags */
/**
* @brief Current IRIG settings and supported codes
*
- * Used to query the IRIG current IRIG settings
+ * Used to query the current IRIG settings
* plus a mask of supported codes.
*/
typedef struct
{
- IRIG_SETTINGS settings;
- uint32_t supp_codes; /**< bit mask of supported codes */
+ IRIG_SETTINGS settings; ///< current settings
+ uint32_t supp_codes; ///< see @ref ICODE_TX_MASKS and @ref ICODE_RX_MASKS
+
} IRIG_INFO;
#define _mbg_swab_irig_info( _p ) \
@@ -2723,6 +4048,7 @@ typedef struct
* which is supported by some IRIG receivers. Delay compensation
* depends on the basic frame type, so there are different records
* required for the different frame type groups.
+ *
* @{ */
/**
@@ -2732,13 +4058,16 @@ typedef struct
*/
#define N_IRIG_RX_COMP_VAL 4
-/** @brief A structure which stores compensation values. */
+/**
+ * @brief A structure used to store compensation values
+ */
typedef struct
{
- /** Delay compensation values [100 ns units].
+ /**
+ * @brief Delay compensation values [100 ns units]
*
- * Only the first value is actually used to compensate a delay,
- * so the remaining values should be 0.
+ * @note Only the first value is actually used to compensate
+ * a delay, so the remaining values should be 0.
*/
int16_t c[N_IRIG_RX_COMP_VAL];
@@ -2752,16 +4081,19 @@ typedef struct
}
-/** The absolute value of the maximum compensation value accepted by a device */
+/** The absolute value of the maximum compensation value accepted by a device */
#define IRIG_RX_COMP_MAX 999 // [100 ns units], i.e. valid range is +/-99.9 us
-/** @brief Structure used to retrieve the number of records for a given type */
+/**
+ * @brief Structure used to retrieve the number of records for a given type
+ */
typedef struct
{
- uint16_t type; /**< record type */
- uint16_t idx; /**< index if several records of same type are supported */
+ uint16_t type; ///< record type, see ::CAL_REC_TYPES
+ uint16_t idx; ///< index if several records of same type are supported, see ::IRIG_RX_COMP_GROUPS
+
} CAL_REC_HDR;
#define _mbg_swab_cal_rec_hdr( _p ) \
@@ -2771,33 +4103,37 @@ typedef struct
}
-/** @brief Types to be used with CAL_REC_HDR::type */
-enum
+/**
+ * @brief Types to be used with ::CAL_REC_HDR::type
+ */
+enum CAL_REC_TYPES
{
- CAL_REC_TYPE_UNDEF, /**< undefined */
- CAL_REC_TYPE_IRIG_RX_COMP, /**< IRIG receiver delay compensation */
- N_CAL_REC_TYPE /**< number of known types */
+ CAL_REC_TYPE_UNDEF, ///< undefined type
+ CAL_REC_TYPE_IRIG_RX_COMP, ///< IRIG receiver delay compensation
+ N_CAL_REC_TYPE ///< number of known types
};
/**
- * @brief Types to be used with CAL_REC_HDR::idx
+ * @brief Types to be used with ::CAL_REC_HDR::idx
*
* IRIG frame type groups to be distinguished for delay compensation.
*/
-enum
+enum IRIG_RX_COMP_GROUPS
{
- IRIG_RX_COMP_B1, /**< codes B1xx, AFNOR, IEEE1344 */
- IRIG_RX_COMP_A1, /**< code A1xx */
- IRIG_RX_COMP_B0, /**< codes B0xx, AFNOR DC, IEEE1344 DC */
- IRIG_RX_COMP_A0, /**< code A0xx */
- IRIG_RX_COMP_G1, /**< code G14x */
- IRIG_RX_COMP_G0, /**< code G00x */
- N_IRIG_RX_COMP /**< number of compensation values */
+ IRIG_RX_COMP_B1, ///< codes B1xx, AFNOR, IEEE1344
+ IRIG_RX_COMP_A1, ///< code A1xx
+ IRIG_RX_COMP_B0, ///< codes B0xx, AFNOR DC, IEEE1344 DC
+ IRIG_RX_COMP_A0, ///< code A0xx
+ IRIG_RX_COMP_G1, ///< code G14x
+ IRIG_RX_COMP_G0, ///< code G00x
+ N_IRIG_RX_COMP ///< number of compensation values
};
-/** @brief Initializers for format name strings. */
+/**
+ * @brief Initializers for format name strings
+ */
#define DEFAULT_IRIG_RX_COMP_NAMES \
{ \
"B1xx/AFNOR/IEEE1344", \
@@ -2810,11 +4146,13 @@ enum
-/** @brief Structure used to transfer calibration records. */
+/**
+ * @brief Structure used to transfer calibration records
+ */
typedef struct
{
- CAL_REC_HDR hdr;
- IRIG_RX_COMP comp_data; /**< IRIG receiver delay compensation */
+ CAL_REC_HDR hdr; ///< data header
+ IRIG_RX_COMP comp_data; ///< IRIG receiver delay compensation
} CAL_REC_IRIG_RX_COMP;
@@ -2824,12 +4162,17 @@ typedef struct
_mbg_swab_irig_rx_comp( &(_p)->comp_data ); \
}
-/** @} group_irig_comp */
+/** @} defgroup group_irig_comp */
-// The type below is used to read the board's debug status
-// which also include IRIG decoder status:
+/**
+ * @brief A data type used to read the board's debug status
+ *
+ * @note This also includes IRIG decoder status.
+ *
+ * @see @ref MBG_DEBUG_STATUS_BIT_MASKS
+ */
typedef uint32_t MBG_DEBUG_STATUS;
#define _mbg_swab_debug_status( _p ) \
@@ -2837,28 +4180,34 @@ typedef uint32_t MBG_DEBUG_STATUS;
-// The debug status is bit coded as defined below:
-enum
+/**
+ * @brief Enumeration of flag bits used for debug status
+ *
+ * @see @ref MBG_DEBUG_STATUS_BIT_MASKS
+ */
+enum MBG_DEBUG_STATUS_BITS
{
- MBG_IRIG_BIT_WARMED_UP, /**< Osc has warmed up */
- MBG_IRIG_BIT_PPS_ACTIVE, /**< PPS output is active */
- MBG_IRIG_BIT_INV_CONFIG, /**< Invalid config, e.g. data csum error */
- MBG_IRIG_BIT_MSG_DECODED, /**< IRIG msg could be decoded */
- MBG_IRIG_BIT_MSG_INCONSISTENT, /**< IRIG msg contains inconsistent data */
- MBG_IRIG_BIT_LOOP_LOCKED, /**< Decoder control loop is locked */
- MBG_IRIG_BIT_JITTER_TOO_LARGE, /**< Phase jitter too large */
- MBG_IRIG_BIT_INV_REF_OFFS, /**< UTC ref offset not configured */
+ MBG_IRIG_BIT_WARMED_UP, ///< Osc has warmed up
+ MBG_IRIG_BIT_PPS_ACTIVE, ///< PPS output is active
+ MBG_IRIG_BIT_INV_CONFIG, ///< Invalid config, e.g. data csum error
+ MBG_IRIG_BIT_MSG_DECODED, ///< IRIG msg could be decoded
+ MBG_IRIG_BIT_MSG_INCONSISTENT, ///< IRIG msg contains inconsistent data
+ MBG_IRIG_BIT_LOOP_LOCKED, ///< Decoder control loop is locked
+ MBG_IRIG_BIT_JITTER_TOO_LARGE, ///< Phase jitter too large
+ MBG_IRIG_BIT_INV_REF_OFFS, ///< %UTC ref offset not configured
- MBG_SYS_BIT_INV_TIME, /**< Internal time not valid/set */
- MBG_SYS_BIT_TIME_SET_VIA_API, /**< On board time set externally */
- MBG_SYS_BIT_INV_RTC, /**< On board RTC invalid */
- MBG_SYS_BIT_CPU_PLL_FAILED, /**< The CPU's PLL watchdog */
+ MBG_SYS_BIT_INV_TIME, ///< Internal time not valid/set
+ MBG_SYS_BIT_TIME_SET_VIA_API, ///< On board time set externally
+ MBG_SYS_BIT_INV_RTC, ///< On board RTC invalid
+ MBG_SYS_BIT_CPU_PLL_FAILED, ///< The CPU's PLL watchdog
- N_MBG_DEBUG_BIT
+ N_MBG_DEBUG_BIT ///< The number of known bits
};
-/*
- * Initializers for IRIG status bit strings.
+/**
+ * @brief Initializers for debug status bit strings
+ *
+ * @see ::MBG_DEBUG_STATUS_BITS
*/
#define MBG_DEBUG_STATUS_STRS \
{ \
@@ -2878,6 +4227,12 @@ enum
}
+/**
+ * @brief Bit masks used with ::MBG_DEBUG_STATUS
+ *
+ * @see ::MBG_DEBUG_STATUS_BITS
+ *
+ * @anchor MBG_DEBUG_STATUS_BIT_MASKS @{ */
#define MBG_IRIG_MSK_WARMED_UP ( 1UL << MBG_IRIG_BIT_WARMED_UP )
#define MBG_IRIG_MSK_PPS_ACTIVE ( 1UL << MBG_IRIG_BIT_PPS_ACTIVE )
@@ -2893,26 +4248,54 @@ enum
#define MBG_SYS_MSK_INV_RTC ( 1UL << MBG_SYS_BIT_INV_RTC )
#define MBG_SYS_MSK_CPU_PLL_FAILED ( 1UL << MBG_SYS_BIT_CPU_PLL_FAILED )
+/** @} anchor MBG_DEBUG_STATUS_BIT_MASKS */
-typedef int16_t MBG_REF_OFFS; /**< -MBG_REF_OFFS_MAX..MBG_REF_OFFS_MAX */
+/**
+ * @brief A data type used to configure the ref offset
+ *
+ * The ref offset if the offset of the incoming reference time from %UTC.
+ * For some types of signal (e.g. most IRIG frame formats) this can't be
+ * determined automatically.
+ *
+ * Valid range: -::MBG_REF_OFFS_MAX..::MBG_REF_OFFS_MAX, or ::MBG_REF_OFFS_NOT_CFGD
+ *
+ * @note There's a special flag ::MBG_REF_OFFS_NOT_CFGD indicating that
+ * this parameter is unconfigured, in which case a Meinberg time code
+ * receiver refuses to synchronize to the time code signal unless a time
+ * code frame has been configured which provides the UTC offset (namely
+ * IEEE 1344 or IEEE C37.118).
+ */
+typedef int16_t MBG_REF_OFFS;
#define _mbg_swab_mbg_ref_offs( _p ) _mbg_swab16( (_p) )
-/** the maximum allowed positive / negative offset */
+/**
+ * @brief The maximum allowed positive / negative ref offset
+ */
#define MBG_REF_OFFS_MAX ( ( 12L * 60 ) + 30 ) // [minutes]
/**
- * the following value is used to indicate that the ref offset
- * value has not yet been configured
+ * @brief A flag indicating that the ref offset has not yet been configured
+ *
+ * If this flag is set in ::MBG_REF_OFFS this means the ref offset
+ * (time offset from %UTC) has not yet been configured. This is usually
+ * the case for IRIG receiver devices right after they have been shipped.
*/
#define MBG_REF_OFFS_NOT_CFGD 0x8000
+
+/**
+ * @brief A structure used to configure optional settings
+ *
+ * Optional settings are a generic way to configure some extended settings.
+ */
typedef struct
{
- uint32_t flags;
+ uint32_t flags; ///< @see ::MBG_OPT_FLAGS
+
} MBG_OPT_SETTINGS;
#define _mbg_swab_mbg_opt_settings( _p ) \
@@ -2921,10 +4304,17 @@ typedef struct
}
+/**
+ * @brief A structure used to configure optional settings
+ *
+ * This structure includes the current settings, and a bit mask
+ * indicating which flags are supported.
+ */
typedef struct
{
- MBG_OPT_SETTINGS settings;
- uint32_t supp_flags;
+ MBG_OPT_SETTINGS settings; ///< current settings
+ uint32_t supp_flags; ///< bit mask of supported flags, see ::MBG_OPT_FLAGS
+
} MBG_OPT_INFO;
#define _mbg_swab_mbg_opt_info( _p ) \
@@ -2934,32 +4324,55 @@ typedef struct
}
-enum
+/**
+ * @brief Enumeration of flag bits used to define ::MBG_OPT_FLAGS
+ */
+enum MBG_OPT_BITS
{
- MBG_OPT_BIT_STR_UTC, /**< serial string contains UTC time */
- MBG_OPT_BIT_EMU_SYNC, /**< emulate/pretend to be synchronized, */
- /**< alternatively GPS_FEAT_IGNORE_LOCK may be supported */
+ MBG_OPT_BIT_STR_UTC, ///< serial time string contains %UTC time
+ MBG_OPT_BIT_EMU_SYNC, ///< always pretend to be synchronized, alternatively ::GPS_FEAT_IGNORE_LOCK may be supported
N_MBG_OPT_BIT
};
-/*
- * Bit masks corresponding to the enumeration above:
+
+/**
+ * @brief Bit masks according to ::MBG_OPT_BITS
+ *
+ * Used with ::MBG_OPT_SETTINGS::flags and ::MBG_OPT_INFO::supp_flags.
*/
-#define MBG_OPT_FLAG_STR_UTC ( 1UL << MBG_OPT_BIT_STR_UTC )
-#define MBG_OPT_FLAG_EMU_SYNC ( 1UL << MBG_OPT_BIT_EMU_SYNC )
+enum MBG_OPT_FLAGS
+{
+ MBG_OPT_FLAG_STR_UTC = ( 1UL << MBG_OPT_BIT_STR_UTC ), ///< see ::MBG_OPT_BIT_STR_UTC
+ MBG_OPT_FLAG_EMU_SYNC = ( 1UL << MBG_OPT_BIT_EMU_SYNC ) ///< see ::MBG_OPT_BIT_EMU_SYNC
+};
-// bit coded return type for PCPS_GET_IRIG_CTRL_BITS
-typedef uint32_t MBG_IRIG_CTRL_BITS;
+/**
+ * @brief Bit coded return type for ::PCPS_GET_IRIG_CTRL_BITS
+ *
+ * The control bits a time code receiver has decoded from
+ * the incoming time code signal.
+ *
+ * @note ::MBG_RAW_IRIG_DATA is more versatile and should
+ * be used preferably, if supported.
+ *
+ * @see ::MBG_RAW_IRIG_DATA
+ */
+typedef uint32_t MBG_IRIG_CTRL_BITS;
#define _mbg_swab_irig_ctrl_bits( _p ) _mbg_swab32( _p )
-// The following macro extracts the 4 bit TFOM code from the
-// IRIG control bits read from a card. This only works if the received
-// IRIG code is a code which supports TFOM, this is currently
-// only IEEE1344.
+/**
+ * @brief Extract the TFOM code from ::MBG_IRIG_CTRL_BITS
+ *
+ * The resulting code is only valid if the configured IRIG code frame format
+ * supports this. See @ref MSK_ICODE_TX_HAS_TFOM and @ref MSK_ICODE_RX_HAS_TFOM
+ *
+ * As specified in the IEEE 1344 standard as "Time Quality", the TFOM code is
+ * the range 0x0 (locked, maximum accuracy) to 0xF (failed, data unreliable).
+ */
#define _pcps_tfom_from_irig_ctrl_bits( _p ) \
( ( ( *(_p) ) >> 24 ) & 0x0F )
@@ -2968,24 +4381,33 @@ typedef uint32_t MBG_IRIG_CTRL_BITS;
#define RAW_IRIG_SIZE 16
/**
- The buffer below can be used to get the raw data bits
- from the IRIG decoder. A maximum number of RAW_IRIG_SIZE
- bytes can be filled. If less bytes are used then the rest
- of the bytes are filled with zeros.
-
- The first IRIG bit received from the transmitter is saved
- in the MSB (bit 7) of data_bytes[0], etc.
-*/
+ * @brief A buffer used to read raw IRIG data bits from an IRIG receiver
+ *
+ * Used to get the raw data bits from the IRIG decoder. A maximum number
+ * of ::RAW_IRIG_SIZE bytes can be filled up, depending on the IRIG code.
+ * If less bytes are used then the rest of the bytes are filled with zeros.
+ *
+ * @note The first IRIG bit received from the transmitter is saved
+ * in the MSB (bit 7) of data_bytes[0], etc.
+ */
typedef struct
{
uint8_t data_bytes[RAW_IRIG_SIZE];
+
} MBG_RAW_IRIG_DATA;
-// The following macro extracts the 4 bit TFOM code from the raw
-// data bits read from a card. This only works if the received
-// IRIG code is a code which supports TFOM, this is currently
-// only IEEE1344.
-#define _pcps_tfom_from_raw_irig_data( _p ) \
+#define _mbg_swab_mbg_raw_irig_data( _p ) _nop_macro_fnc()
+
+/**
+ * @brief Extract the TFOM code from ::MBG_RAW_IRIG_DATA
+ *
+ * The resulting code is only valid if the configured IRIG code frame format
+ * supports this. See @ref MSK_ICODE_TX_HAS_TFOM and @ref MSK_ICODE_RX_HAS_TFOM
+ *
+ * As specified in the IEEE 1344 standard as "Time Quality", the TFOM code is
+ * the range 0x0 (locked, maximum accuracy) to 0xF (failed, data unreliable).
+ */
+#define _pcps_tfom_from_raw_irig_data( _p ) \
( ( ( (_p)->data_bytes[9] >> 2 ) & 0x08 ) \
| ( ( (_p)->data_bytes[9] >> 4 ) & 0x04 ) \
| ( ( (_p)->data_bytes[9] >> 6 ) & 0x02 ) \
@@ -2994,32 +4416,43 @@ typedef struct
/**
- @defgroup group_time_scale Time Scale Configuration
-
- The structures and defines can be used to configure the GPS receiver's
- basic time scale. By default this is UTC which can optionally
- be converted to some local time. However, some applications
- prefer TAI or pure GPS time. This can be configured using the
- structures below if the GPS_HAS_TIME_SCALE flag is set in
- RECEIVER_INFO::features.
- @{
-*/
+ * @defgroup group_time_scale Time Scale Configuration
+ *
+ * Used to configure the GPS receiver's basic time scale.
+ * By default this is %UTC which can optionally be converted
+ * to some local time. However, some applications prefer
+ * TAI or pure GPS time. This can be configured using the
+ * structures below if the ::GPS_HAS_TIME_SCALE flag is set
+ * in ::RECEIVER_INFO::features.
+ *
+ * @{ */
+/**
+ * @brief Known time scales
+ *
+ * @see ::MBG_TIME_SCALE_MASKS
+ * @see ::TM_SCALE_GPS
+ * @see ::TM_SCALE_TAI
+ */
enum MBG_TIME_SCALES
{
- MBG_TIME_SCALE_DEFAULT, /**< UTC or local time, t_gps - deltat_ls */
- MBG_TIME_SCALE_GPS, /**< GPS time, monotonical */
- MBG_TIME_SCALE_TAI, /**< TAI, t_gps + GPS_TAI_OFFSET seconds */
+ MBG_TIME_SCALE_DEFAULT, ///< %UTC or local time according to ::UTC parameters and ::TZDL configuration
+ MBG_TIME_SCALE_GPS, ///< GPS time as sent by the satellites, monotonical
+ MBG_TIME_SCALE_TAI, ///< TAI, i.e. GPS time plus constant offset (see ::GPS_TAI_OFFSET)
N_MBG_TIME_SCALE
};
-#define MBG_TIME_SCALE_MSK_DEFAULT ( 1UL << MBG_TIME_SCALE_DEFAULT )
-#define MBG_TIME_SCALE_MSK_GPS ( 1UL << MBG_TIME_SCALE_GPS )
-#define MBG_TIME_SCALE_MSK_TAI ( 1UL << MBG_TIME_SCALE_TAI )
-
-// See also the extended status bits TM_SCALE_GPS and TM_SCALE_TAI
-// indicating the active time scale setting.
-
+/**
+ * @brief Bit masks for known time scales
+ *
+ * @see ::MBG_TIME_SCALES
+ */
+enum MBG_TIME_SCALE_MASKS
+{
+ MBG_TIME_SCALE_MSK_DEFAULT = ( 1UL << MBG_TIME_SCALE_DEFAULT ), ///< see ::MBG_TIME_SCALE_DEFAULT
+ MBG_TIME_SCALE_MSK_GPS = ( 1UL << MBG_TIME_SCALE_GPS ), ///< see ::MBG_TIME_SCALE_GPS
+ MBG_TIME_SCALE_MSK_TAI = ( 1UL << MBG_TIME_SCALE_TAI ) ///< see ::MBG_TIME_SCALE_TAI
+};
#define MBG_TIME_SCALE_STRS \
{ \
@@ -3031,26 +4464,34 @@ enum MBG_TIME_SCALES
/**
- The fixed time offset between the GPS and TAI time scales, in seconds
-*/
-#define GPS_TAI_OFFSET 19 /**< [s], TAI = GPS + GPS_TAI_OFFSET */
+ * @brief The constant time offset between the GPS and TAI time scales, in seconds
+ */
+#define GPS_TAI_OFFSET 19 ///< [s], TAI = GPS + GPS_TAI_OFFSET
+/**
+ * @brief Time scale configuration settings
+ */
typedef struct
{
- uint8_t scale; /**< current time scale code from enum MBG_TIME_SCALES */
- uint8_t flags; /**< reserved, currently always 0 */
+ uint8_t scale; ///< current time scale code, see ::MBG_TIME_SCALES
+ uint8_t flags; ///< reserved, don't use, currently always 0
+
} MBG_TIME_SCALE_SETTINGS;
#define _mbg_swab_mbg_time_scale_settings( _p ) \
_nop_macro_fnc()
+/**
+ * @brief Time scale configuration settings plus capabilities
+ */
typedef struct
{
- MBG_TIME_SCALE_SETTINGS settings; /**< current settings */
- MBG_TIME_SCALE_SETTINGS max_settings; /**< numb. of scales, all supported flags */
- uint32_t supp_scales; /**< bit masks of supported scales */
+ MBG_TIME_SCALE_SETTINGS settings; ///< current settings
+ MBG_TIME_SCALE_SETTINGS max_settings; ///< number of scales, all supported flags
+ uint32_t supp_scales; ///< bit masks of supported scales, see ::MBG_TIME_SCALE_MASKS
+
} MBG_TIME_SCALE_INFO;
#define _mbg_swab_mbg_time_scale_info( _p ) \
@@ -3060,24 +4501,25 @@ typedef struct
_mbg_swab32( &(_p)->supp_scales ); \
}
-/** @} group_time_scale */
+/** @} defgroup group_time_scale */
/*
* The structures below are required to setup the programmable
* pulse outputs which are provided by some GPS receivers.
* The number of programmable pulse outputs supported by a GPS
- * receiver is reported in the RECEIVER_INFO.n_str_type field.
+ * receiver is reported in the RECEIVER_INFO::n_str_type field.
*/
/**
- * The structure is used to define a date of year:
+ * @brief A calendar date including full year number
*/
typedef struct
{
- uint8_t mday; /* 1..28,29,30,31 */
- uint8_t month; /* 1..12 */
- uint16_t year; /* including century */
+ uint8_t mday; ///< 1..28,29,30,31
+ uint8_t month; ///< 1..12
+ uint16_t year; ///< including century
+
} MBG_DATE;
#define _mbg_swab_mbg_date( _p ) \
@@ -3087,14 +4529,15 @@ typedef struct
/**
- * The structure is used to define a time of day:
+ * @brief The time of day including hundredths of seconds
*/
typedef struct
{
- uint8_t hour; /**< 0..23 */
- uint8_t min; /**< 0..59 */
- uint8_t sec; /**< 0..59,60 */
- uint8_t sec100; /**< reserved, currently always 0 */
+ uint8_t hour; ///< 0..23
+ uint8_t min; ///< 0..59
+ uint8_t sec; ///< 0..59,60
+ uint8_t sec100; ///< reserved, currently always 0
+
} MBG_TIME;
#define _mbg_swab_mbg_time( _p ) \
@@ -3102,15 +4545,15 @@ typedef struct
/**
- * The structure defines a single date and time
- * for switching operations:
+ * @brief Date and time specification for switching operations
*/
typedef struct
{
- MBG_DATE d; /* date to switch */
- MBG_TIME t; /* time to switch */
- uint8_t wday; /* reserved, currently always 0 */
- uint8_t flags; /* reserved, currently 0 */
+ MBG_DATE d; ///< date to switch
+ MBG_TIME t; ///< time to switch
+ uint8_t wday; ///< reserved, currently always 0
+ uint8_t flags; ///< reserved, currently 0
+
} MBG_DATE_TIME;
#define _mbg_swab_mbg_date_time( _p ) \
@@ -3121,13 +4564,13 @@ typedef struct
/**
- * The structure defines times and dates
- * for an on/off cycle:
+ * @brief A structure to define on/off cycle times
*/
typedef struct
{
- MBG_DATE_TIME on; /* time and date to switch on */
- MBG_DATE_TIME off; /* time and date to switch off */
+ MBG_DATE_TIME on; ///< date and time to switch on
+ MBG_DATE_TIME off; ///< date and time to switch off
+
} POUT_TIME;
#define _mbg_swab_pout_time( _p ) \
@@ -3138,57 +4581,50 @@ typedef struct
/**
- * The number of POUT_TIMEs for each programmable pulse output
+ * @brief The number of ::POUT_TIME settings for each programmable pulse output
+ *
+ * @note This can't be changed without breaking compatibility of the API
*/
-#define N_POUT_TIMES 3
+#define N_POUT_TIMES 3
/**
- * The structure is used to configure a single programmable
- * pulse output.
+ * @brief Configuration settings for a single programmable pulse output
*/
typedef struct
{
- uint16_t mode; /**< mode of operation, codes defined below */
- uint16_t pulse_len; /**< 10 msec units, or COM port number */
- uint16_t timeout; /**< [min], for dcf_mode */
- uint16_t flags; /**< see below */
- POUT_TIME tm[N_POUT_TIMES]; /**< switching times, or other data */
+ uint16_t mode; ///< mode of operation, see ::POUT_MODES
+ uint16_t mode_param; ///< depending on the mode, e.g. pulse length, or index of a signal source
+ uint16_t timeout; ///< timeout after which output signal is disabled [min], used with ::POUT_DCF77 and ::POUT_DCF77_M59 only, see ::MAX_POUT_DCF_TIMOUT
+ uint16_t flags; ///< @see ::POUT_SETTINGS_FLAGS
+ POUT_TIME tm[N_POUT_TIMES]; ///< switching times, or other data, see ::POUT_DATA
+
} POUT_SETTINGS;
-// If the mode is set to POUT_TIME_SLOTS then POUT_SETTINGS::tm must be
-// interpretet as POUT_DATA, i.e. just an array of bytes. We can not change
-// the type of the tm field to a union for compatibility reasons ...
+/**
+ * @brief A Generic data field for programmable output settings
+ *
+ * If the mode is set to ::POUT_TIME_SLOTS then ::POUT_SETTINGS::tm must be
+ * interpreted as ::POUT_DATA, i.e. just an array of bytes. We can not change
+ * the type of the tm field to a union for compatibility reasons ... :(
+ */
typedef union
{
uint8_t b[N_POUT_TIMES * sizeof( POUT_TIME )];
-} POUT_DATA;
-// In POUT_TIME_SLOTS mode the number of time slots per minute is stored
-// in the pulse_len field. Valid numbers all numbers n in the range 1..60
-// for which the remainder of 60 / n is 0.
-#define MIN_TIME_SLOTS_PER_MINUTE 1
-#define MAX_TIME_SLOTS_PER_MINUTE 60
-#define TIME_SLOT_REGISTER_IN_SEC 60
-
-#define TIME_SLOT_SWITCH_OFF_BUFFER_MIN 50
-#define TIME_SLOT_SWITCH_OFF_BUFFER_MAX 500
-#define TIME_SLOT_SWITCH_OFF_BUFFER_STD 500
-#define TIME_SLOT_SWITCH_OFF_BUFFER_STEP_SIZE 50
-
-#define _valid_time_slots_per_minute( _n ) \
- ( ( (_n) >= MIN_TIME_SLOTS_PER_MINUTE ) && \
- ( (_n) <= MAX_TIME_SLOTS_PER_MINUTE ) && \
- ( ( 60 % (_n) ) == 0 ) \
- )
+} POUT_DATA;
-// When reading data from a device we first need to correct the endianess
-// of the mode first, and correct the endianess of the tm field only
-// if the tm field is not interpreted as POUT_DATA.
+/**
+ * @brief Convert ::POUT_SETTINGS endianess after reading from a device
+ *
+ * When reading data from a device we first need to correct the endianess
+ * of the mode first, and correct the endianess of the tm field only
+ * if the tm field is not interpreted as ::POUT_DATA.
+ */
#define _mbg_swab_pout_settings_on_get( _p ) \
{ \
_mbg_swab16( &(_p)->mode ); \
- _mbg_swab16( &(_p)->pulse_len ); \
+ _mbg_swab16( &(_p)->mode_param ); \
_mbg_swab16( &(_p)->timeout ); \
_mbg_swab16( &(_p)->flags ); \
\
@@ -3201,10 +4637,14 @@ typedef union
} \
}
-// When writing data to a device we first need to check the mode,
-// and correct the endianess of the tm field only if the tm field
-// is not interpreted as POUT_DATA. Finally we can also correct
-// the endianess of the mode field.
+/**
+ * @brief Convert ::POUT_SETTINGS endianess before writing to a device
+ *
+ * When writing data to a device we first need to check the mode,
+ * and correct the endianess of the tm field only if the tm field
+ * is not interpreted as ::POUT_DATA. Finally we can also correct
+ * the endianess of the mode field.
+ */
#define _mbg_swab_pout_settings_on_set( _p ) \
{ \
if ( (_p)->mode != POUT_TIME_SLOTS ) \
@@ -3216,45 +4656,122 @@ typedef union
} \
\
_mbg_swab16( &(_p)->mode ); \
- _mbg_swab16( &(_p)->pulse_len ); \
+ _mbg_swab16( &(_p)->mode_param ); \
_mbg_swab16( &(_p)->timeout ); \
_mbg_swab16( &(_p)->flags ); \
}
-#define MAX_POUT_PULSE_LEN 1000 /**< 10 secs, in 10 msec units */
-#define MAX_POUT_DCF_TIMOUT ( 48 * 60 ) /**< 48 hours, in minutes */
+/**
+ * @brief Definitions used with ::POUT_TIME_SLOTS mode
+ *
+ * If ::POUT_SETTINGS::mode is set to ::POUT_TIME_SLOTS then the number
+ * of time slots per minute is stored in ::POUT_SETTINGS::mode_param.
+ * Valid numbers are all numbers n in the range ::MIN_TIME_SLOTS_PER_MINUTE
+ * to ::MAX_TIME_SLOTS_PER_MINUTE for which the remainder of 60 / n is 0.
+ *
+ * @anchor POUT_TIME_SLOTS_MODE_DEFS @{ */
+
+#define MIN_TIME_SLOTS_PER_MINUTE 1
+#define MAX_TIME_SLOTS_PER_MINUTE 60
+#define TIME_SLOT_REGISTER_IN_SEC 60
+
+#define TIMEOUT_DIVIDED_BY 10
+#define TIME_SLOT_SWITCH_OFF_BUFFER_MIN 50 / TIMEOUT_DIVIDED_BY
+#define TIME_SLOT_SWITCH_OFF_BUFFER_MAX 500 / TIMEOUT_DIVIDED_BY
+#define TIME_SLOT_SWITCH_OFF_BUFFER_STD 500 / TIMEOUT_DIVIDED_BY
+#define TIME_SLOT_SWITCH_OFF_BUFFER_STEP_SIZE 50 / TIMEOUT_DIVIDED_BY
+
+#define _valid_time_slots_per_minute( _n ) \
+ ( ( (_n) >= MIN_TIME_SLOTS_PER_MINUTE ) && \
+ ( (_n) <= MAX_TIME_SLOTS_PER_MINUTE ) && \
+ ( ( 60 % (_n) ) == 0 ) \
+ )
+
+/** @} anchor POUT_TIME_SLOTS_MODE_DEFS */
+
+
+
+#define MAX_POUT_PULSE_LEN 1000 ///< 10 secs, in 10 msec units
+#define MAX_POUT_DCF_TIMOUT ( 48 * 60 ) ///< 48 hours, in minutes
+
/**
- * These codes are defined for POUT_SETTINGS.mode to setup
- * the basic mode of operation for a single programmable pulse
- * output:
- */
-enum
-{
- POUT_IDLE, /**< always off, or on if POUT_INVERTED */
- POUT_TIMER, /**< switch on/off at configured times */
- POUT_SINGLE_SHOT, /**< pulse at time POUT_SETTINGS.tm[0].on */
- POUT_CYCLIC_PULSE, /**< pulse every POUT_SETTINGS.tm[0].on.t interval */
- POUT_PER_SEC, /**< pulse if second changes */
- POUT_PER_MIN, /**< pulse if minute changes */
- POUT_PER_HOUR, /**< pulse if hour changes */
- POUT_DCF77, /**< emulate DCF77 signal */
- POUT_POS_OK, /**< on if pos. OK (nav_solved) */
- POUT_TIME_SYNC, /**< on if time sync (time_syn) */
- POUT_ALL_SYNC, /**< on if pos. OK and time sync */
- POUT_TIMECODE, /**< IRIG/AFNOR DCLS output */
- POUT_TIMESTR, /**< COM port number in pulse_len field */
- POUT_10MHZ, /**< 10 MHz fixed frequency */
- POUT_DCF77_M59, /**< DCF77-like signal with 500 ms pulse in 59th second */
- POUT_SYNTH, /**< programmable synthesizer frequency */
- POUT_TIME_SLOTS, /**< programmable time slots during each minute */
- N_POUT_MODES
+ * @brief Enumeration of known operation modes for programmable pulse outputs
+ *
+ * These codes are used with ::POUT_SETTINGS::mode. One or more of
+ * the remaining fields in ::POUT_SETTINGS are evaluated depending
+ * on the selected mode.
+ *
+ * Unless ::POUT_NOT_INVERTIBLE is set in ::POUT_INFO::flags
+ * the output signal level can be inverted if ::POUT_INVERTED
+ * is set in ::POUT_SETTINGS::flags.
+ *
+ * @note Not every programmable pulse output supports all modes.
+ *
+ * @see @ref POUT_MODE_MASKS
+ */
+enum POUT_MODES
+{
+ POUT_IDLE, ///< always off, or on if ::POUT_INVERTED flag is set
+ POUT_TIMER, ///< switch on/off at times specified in ::POUT_SETTINGS::tm
+ POUT_SINGLE_SHOT, ///< pulse at time POUT_SETTINGS::tm[0].on, pulse length in ::POUT_SETTINGS::mode_param [10 ms units], see ::MAX_POUT_PULSE_LEN
+ POUT_CYCLIC_PULSE, ///< pulse every POUT_SETTINGS::tm[0].on.t interval, pulse length in ::POUT_SETTINGS::mode_param [10 ms units], see ::MAX_POUT_PULSE_LEN
+ POUT_PER_SEC, ///< pulse if second changes, pulse length in ::POUT_SETTINGS::mode_param [10 ms units], see ::MAX_POUT_PULSE_LEN
+ POUT_PER_MIN, ///< pulse if minute changes, pulse length in ::POUT_SETTINGS::mode_param [10 ms units], see ::MAX_POUT_PULSE_LEN
+ POUT_PER_HOUR, ///< pulse if hour changes, pulse length in ::POUT_SETTINGS::mode_param [10 ms units], see ::MAX_POUT_PULSE_LEN
+ POUT_DCF77, ///< emulate DCF77 signal, uses ::POUT_SETTINGS::timeout, see ::MAX_POUT_DCF_TIMOUT
+ POUT_POS_OK, ///< on if receiver position verified (nav_solved)
+ POUT_TIME_SYNC, ///< on if time synchronized (time_syn)
+ POUT_ALL_SYNC, ///< on if position verified and time synchronized
+ POUT_TIMECODE, ///< IRIG/AFNOR DCLS signal output
+ POUT_TIMESTR, ///< serial time string, ::POUT_SETTINGS::mode_param contains the number of the COM port, see ::MAX_POUT_TIMESTR_PORTS
+ POUT_10MHZ, ///< 10 MHz fixed frequency
+ POUT_DCF77_M59, ///< DCF77-like signal with 500 ms pulse in 59th second, uses ::POUT_SETTINGS::timeout, see ::MAX_POUT_DCF_TIMOUT
+ POUT_SYNTH, ///< programmable frequency synthesizer output signal
+ POUT_TIME_SLOTS, ///< programmable time slots during each minute, uses ::POUT_DATA, ::POUT_SETTINGS::mode_param contains time slots per minute
+ POUT_GPIO, ///< GPIO input or output signal, ::POUT_SETTINGS::mode_param specifies the GPIO number, see ::MBG_GPIO_CFG_LIMITS::num_io
+ // New modes have to be added here at the end of the enumeration, and
+ // the POUT_MODE_MASKS and string initializers (also in pcpslstr.h)
+ // have to be updated accordingly.
+ N_POUT_MODES ///< the number of known modes
};
+/**
+ * @brief Bit masks associated with ::POUT_MODES
+ *
+ * Used with ::POUT_INFO::supp_modes to specify which ::POUT_MODES
+ * are supported for a particular programmable output.
+ *
+ * @see ::POUT_MODES
+ *
+ * @anchor POUT_MODE_MASKS @{ */
+
+#define MSK_POUT_IDLE ( 1UL << POUT_IDLE ) ///< see ::POUT_IDLE
+#define MSK_POUT_TIMER ( 1UL << POUT_TIMER ) ///< see ::POUT_TIMER
+#define MSK_POUT_SINGLE_SHOT ( 1UL << POUT_SINGLE_SHOT ) ///< see ::POUT_SINGLE_SHOT
+#define MSK_POUT_CYCLIC_PULSE ( 1UL << POUT_CYCLIC_PULSE ) ///< see ::POUT_CYCLIC_PULSE
+#define MSK_POUT_PER_SEC ( 1UL << POUT_PER_SEC ) ///< see ::POUT_PER_SEC
+#define MSK_POUT_PER_MIN ( 1UL << POUT_PER_MIN ) ///< see ::POUT_PER_MIN
+#define MSK_POUT_PER_HOUR ( 1UL << POUT_PER_HOUR ) ///< see ::POUT_PER_HOUR
+#define MSK_POUT_DCF77 ( 1UL << POUT_DCF77 ) ///< see ::POUT_DCF77
+#define MSK_POUT_POS_OK ( 1UL << POUT_POS_OK ) ///< see ::POUT_POS_OK
+#define MSK_POUT_TIME_SYNC ( 1UL << POUT_TIME_SYNC ) ///< see ::POUT_TIME_SYNC
+#define MSK_POUT_ALL_SYNC ( 1UL << POUT_ALL_SYNC ) ///< see ::POUT_ALL_SYNC
+#define MSK_POUT_TIMECODE ( 1UL << POUT_TIMECODE ) ///< see ::POUT_TIMECODE
+#define MSK_POUT_TIMESTR ( 1UL << POUT_TIMESTR ) ///< see ::POUT_TIMESTR
+#define MSK_POUT_10MHZ ( 1UL << POUT_10MHZ ) ///< see ::POUT_10MHZ
+#define MSK_POUT_DCF77_M59 ( 1UL << POUT_DCF77_M59 ) ///< see ::POUT_DCF77_M59
+#define MSK_POUT_SYNTH ( 1UL << POUT_SYNTH ) ///< see ::POUT_SYNTH
+#define MSK_POUT_TIME_SLOTS ( 1UL << POUT_TIME_SLOTS ) ///< see ::POUT_TIME_SLOTS
+#define MSK_POUT_GPIO ( 1UL << POUT_GPIO ) ///< see ::POUT_GPIO
+
+/** @} anchor POUT_MODE_MASKS */
+
+
/*
* Default initializers for English pulse mode names. Initializers
* for multi-language strings can be found in pcpslstr.h.
@@ -3271,11 +4788,12 @@ enum
#define ENG_POUT_NAME_TIME_SYNC "Time Sync"
#define ENG_POUT_NAME_ALL_SYNC "All Sync"
#define ENG_POUT_NAME_TIMECODE "DCLS Time Code"
-#define ENG_POUT_NAME_TIMESTR "COM Time String"
+#define ENG_POUT_NAME_TIMESTR "Serial Time String"
#define ENG_POUT_NAME_10MHZ "10 MHz Frequency"
#define ENG_POUT_NAME_DCF77_M59 "DCF77-like M59"
#define ENG_POUT_NAME_SYNTH "Synthesizer Frequency"
#define ENG_POUT_NAME_TIME_SLOTS "Time Slots per Minute"
+#define ENG_POUT_NAME_GPIO "GPIO Signal"
#define DEFAULT_ENG_POUT_NAMES \
{ \
@@ -3295,7 +4813,8 @@ enum
ENG_POUT_NAME_10MHZ, \
ENG_POUT_NAME_DCF77_M59, \
ENG_POUT_NAME_SYNTH, \
- ENG_POUT_NAME_TIME_SLOTS \
+ ENG_POUT_NAME_TIME_SLOTS, \
+ ENG_POUT_NAME_GPIO \
}
@@ -3316,6 +4835,7 @@ enum
#define ENG_POUT_HINT_DCF77_M59 "DCF77 time marks with 500 ms pulse in 59th second"
#define ENG_POUT_HINT_SYNTH "Frequency generated by programmable synthesizer"
#define ENG_POUT_HINT_TIME_SLOTS "Output enabled during specified time slots per minute"
+#define ENG_POUT_HINT_GPIO "Duplicated signal of the specified GPIO input or output"
#define DEFAULT_ENG_POUT_HINTS \
{ \
@@ -3335,53 +4855,55 @@ enum
ENG_POUT_HINT_10MHZ, \
ENG_POUT_HINT_DCF77_M59, \
ENG_POUT_HINT_SYNTH, \
- ENG_POUT_HINT_TIME_SLOTS \
+ ENG_POUT_HINT_TIME_SLOTS, \
+ ENG_POUT_HINT_GPIO \
}
-/*
- * The definitions below are used to set up bit masks
- * which restrict the modes which can be used with
- * a given programmable output:
- */
-#define MSK_POUT_IDLE ( 1UL << POUT_IDLE )
-#define MSK_POUT_TIMER ( 1UL << POUT_TIMER )
-#define MSK_POUT_SINGLE_SHOT ( 1UL << POUT_SINGLE_SHOT )
-#define MSK_POUT_CYCLIC_PULSE ( 1UL << POUT_CYCLIC_PULSE )
-#define MSK_POUT_PER_SEC ( 1UL << POUT_PER_SEC )
-#define MSK_POUT_PER_MIN ( 1UL << POUT_PER_MIN )
-#define MSK_POUT_PER_HOUR ( 1UL << POUT_PER_HOUR )
-#define MSK_POUT_DCF77 ( 1UL << POUT_DCF77 )
-#define MSK_POUT_POS_OK ( 1UL << POUT_POS_OK )
-#define MSK_POUT_TIME_SYNC ( 1UL << POUT_TIME_SYNC )
-#define MSK_POUT_ALL_SYNC ( 1UL << POUT_ALL_SYNC )
-#define MSK_POUT_TIMECODE ( 1UL << POUT_TIMECODE )
-#define MSK_POUT_TIMESTR ( 1UL << POUT_TIMESTR )
-#define MSK_POUT_10MHZ ( 1UL << POUT_10MHZ )
-#define MSK_POUT_DCF77_M59 ( 1UL << POUT_DCF77_M59 )
-#define MSK_POUT_SYNTH ( 1UL << POUT_SYNTH )
-#define MSK_POUT_TIME_SLOTS ( 1UL << POUT_TIME_SLOTS )
+/**
+ * @brief Flag bits used to define ::POUT_SETTINGS_FLAGS
+ *
+ * @see ::POUT_SETTINGS_FLAGS
+ */
+enum POUT_SETTINGS_FLAG_BITS
+{
+ POUT_BIT_INVERTED, ///< output level is inverted, use only if ::POUT_NOT_INVERTIBLE not set
+ POUT_BIT_IF_SYNC_ONLY, ///< disable output in holdover mode, use only if ::POUT_SUPP_IF_SYNC_ONLY is set
+ POUT_BIT_TIMEBASE_UTC, ///< output %UTC if mode is ::POUT_DCF77 or ::POUT_DCF77_M59, use only if ::POUT_SUPP_DCF77_UTC is set
+ N_POUT_SETTINGS_FLAG_BITS ///< Number of known flag bits
+};
-/*
- * The codes below are used with POUT_SETTINGS::flags:
+
+/**
+ * @brief Flag bit masks used with ::POUT_SETTINGS::flags
+ *
+ * @see ::POUT_SETTINGS_FLAG_BITS
*/
-#define POUT_INVERTED 0x0001 // invert output level
-#define POUT_IF_SYNC_ONLY 0x0002 // disable in holdover mode
-#define POUT_TIMEBASE_UTC 0x0004 // use UTC, only applicable for DCF77 output
+enum POUT_SETTINGS_FLAGS
+{
+ POUT_INVERTED = ( 1UL << POUT_BIT_INVERTED ), ///< see ::POUT_BIT_INVERTED, ::POUT_NOT_INVERTIBLE
+ POUT_IF_SYNC_ONLY = ( 1UL << POUT_BIT_IF_SYNC_ONLY ), ///< see ::POUT_BIT_IF_SYNC_ONLY, ::POUT_SUPP_IF_SYNC_ONLY
+ POUT_TIMEBASE_UTC = ( 1UL << POUT_BIT_TIMEBASE_UTC ) ///< see ::POUT_BIT_TIMEBASE_UTC, ::POUT_SUPP_DCF77_UTC
+};
+
/**
- Since a clock may support more than one programmable
- pulse output, setup tools must use the structure below
- to read/set pulse output configuration.
- The number of outputs supported by a receiver model
- can be queried using the RECEIVER_INFO structure.
+ * @brief Configuration settings for a specific programmable pulse output
+ *
+ * This structure can be used to send configuration settings for a specific
+ * programmable output to a device.
+ * The number of supported outputs is RECEIVER_INFO::n_prg_out.
+ *
+ * @note The ::POUT_INFO_IDX structure should be read from
+ * a device to retrieve the current settings and capabilities.
*/
typedef struct
{
- uint16_t idx; /**< 0..RECEIVER_INFO.n_prg_out-1 */
+ uint16_t idx; ///< 0..::RECEIVER_INFO::n_prg_out-1
POUT_SETTINGS pout_settings;
+
} POUT_SETTINGS_IDX;
#define _mbg_swab_pout_settings_idx_on_set( _p ) \
@@ -3398,20 +4920,24 @@ typedef struct
/**
- The structure below holds the current settings
- for a programmable pulse output, plus additional
- informaton on the output's capabilities.
- This can be read by setup programs to allow setup
- of supported features only.
+ * @brief Current settings and general capabilities of a programmable pulse output
+ *
+ * This structure should be read from the device to retrieve the
+ * current settings of a programmable pulse output plus its capabilities,
+ * e.g. the supported output modes, etc.
+ *
+ * @note The ::POUT_INFO_IDX structure should be used to read
+ * current settings and capabilities of a specific output.
*/
typedef struct
{
POUT_SETTINGS pout_settings;
- uint32_t supp_modes; /**< bit mask of modes supp. by this output */
- uint8_t timestr_ports; /**< bit mask of COM ports supported for POUT_TIMESTR */
- uint8_t reserved_0; /**< reserved for future use, currently 0 */
- uint16_t reserved_1; /**< reserved for future use, currently 0 */
- uint32_t flags; /**< see below */
+ uint32_t supp_modes; ///< bit mask of modes supp. by this output, see @ref POUT_MODE_MASKS
+ uint8_t timestr_ports; ///< bit mask of COM ports supported for mode ::POUT_TIMESTR, see ::MAX_POUT_TIMESTR_PORTS
+ uint8_t reserved_0; ///< reserved for future use, currently unused and always 0
+ uint16_t reserved_1; ///< reserved for future use, currently unused and always 0
+ uint32_t flags; ///< @see ::POUT_INFO_FLAG_MASKS
+
} POUT_INFO;
#define _mbg_swab_pout_info_on_get( _p ) \
@@ -3423,25 +4949,56 @@ typedef struct
}
-/** The max number of COM ports that can be handled by POUT_INFO::timestr_ports */
-#define MAX_POUT_TIMESTR_PORTS 8
+#define MAX_POUT_TIMESTR_PORTS 8 ///< The max number of COM ports that can be handled by ::POUT_INFO::timestr_ports
-/*
- * The codes below are used with POUT_INFO::flags:
+
+/**
+ * @brief Flag bits used to define ::POUT_INFO_FLAG_MASKS
+ *
+ * @see ::POUT_INFO_FLAG_MASKS
*/
-#define POUT_SUPP_IF_SYNC_ONLY 0x0001 // supports disabling outputs in holdover mode
-#define POUT_SUPP_DCF77_UTC 0x0002 // supports UTC output in DCF77 mode
+enum POUT_INFO_FLAG_BITS
+{
+ POUT_BIT_SUPP_IF_SYNC_ONLY, ///< ::POUT_IF_SYNC_ONLY is supported for this output
+ POUT_BIT_SUPP_DCF77_UTC, ///< ::POUT_SUPP_DCF77_UTC is supported for this output
+ POUT_BIT_FIXED_PULSE_LEN, ///< pulse length is limited to the value ::POUT_SETTINGS::mode_param
+ POUT_BIT_NOT_INVERTIBLE, ///< output level can't be inverted, thus ::POUT_INVERTED is not supported for this output
+ N_POUT_INFO_FLAG_BITS ///< number of known flag bits
+};
/**
- The structure below adds an index number to the structure
- above to allow addressing of several instances:
+ * @brief Flag bit masks used with ::POUT_INFO::flags
+ *
+ * @see ::POUT_INFO_FLAG_BITS
+ */
+enum POUT_INFO_FLAG_MASKS
+{
+ POUT_SUPP_IF_SYNC_ONLY = ( 1UL << POUT_BIT_SUPP_IF_SYNC_ONLY ), ///< see ::POUT_BIT_SUPP_IF_SYNC_ONLY, ::POUT_IF_SYNC_ONLY
+ POUT_SUPP_DCF77_UTC = ( 1UL << POUT_BIT_SUPP_DCF77_UTC ), ///< see ::POUT_BIT_SUPP_DCF77_UTC, ::POUT_SUPP_DCF77_UTC
+ POUT_FIXED_PULSE_LEN = ( 1UL << POUT_BIT_FIXED_PULSE_LEN ), ///< see ::POUT_BIT_FIXED_PULSE_LEN
+ POUT_NOT_INVERTIBLE = ( 1UL << POUT_BIT_NOT_INVERTIBLE ) ///< see ::POUT_BIT_NOT_INVERTIBLE, ::POUT_INVERTED
+};
+
+
+
+/**
+ * @brief Current settings and general capabilities of a specific programmable pulse output
+ *
+ * This structure should be read from the device to retrieve the
+ * current settings of a specific programmable output plus its capabilities,
+ * e.g. supported modes of operation, etc.
+ * The number of supported ports is RECEIVER_INFO::n_prg_out.
+ *
+ * @note The ::POUT_SETTINGS_IDX structure should be send back to
+ * the device to configure the specified programmable pulse output.
*/
typedef struct
{
- uint16_t idx; /**< 0..RECEIVER_INFO.n_prg_out-1 */
+ uint16_t idx; ///< 0..::RECEIVER_INFO::n_prg_out-1
POUT_INFO pout_info;
+
} POUT_INFO_IDX;
#define _mbg_swab_pout_info_idx_on_get( _p ) \
@@ -3451,40 +5008,93 @@ typedef struct
}
-/*
- * The codes below are used with devices which support multiple
- * ref time sources at the same time. The priorities of the
- * supported ref time sources is configurable.
- */
+/**
+ * @defgroup group_multi_ref_all Support for multiple reference time sources
+ *
+ * Some devices can evaluate and synchronize to several different types
+ * of input signal, and eventually even several signals of the same type,
+ * e.g. several 1 PPS input signals.
+ *
+ * There are two different ways to configure multi ref devices.
+ *
+ * Newer devices which have the ::GPS_HAS_XMULTI_REF flag set in
+ * ::RECEIVER_INFO::features support the newer XMULTI_REF_... structures
+ * which provide a more flexible API, see @ref group_multi_ref_ext
+ *
+ * Older devices may have the ::GPS_FEAT_MULTI_REF flag set in which
+ * case an older API is supported, see @ref group_multi_ref_old
+ *
+ * Symbols defined in @ref group_multi_ref_common can be used
+ * with both APIs.
+ *
+ * @see @ref group_multi_ref_common
+ * @see @ref group_multi_ref_old
+ * @see @ref group_multi_ref_ext
+ * @{ */
+
+/**
+ * @defgroup group_multi_ref_common Common multi ref definitions
+ *
+ * Common definitions used with both the old and the extended
+ * multi ref API.
+ *
+ * @{ */
/**
- * @brief All possibly supported ref time sources
+ * @brief Enumeration of all known types of reference time source
+ *
+ * All known types of input signals which may possibly be supported
+ * by devices which support several different input signals, i.e.
+ * have the ::GPS_HAS_MULTI_REF or ::GPS_HAS_XMULTI_REF bit set
+ * in ::RECEIVER_INFO::features. Not all devices support each known
+ * type of input signal.
+ *
+ * @see @ref group_multi_ref_all
+ * @see ::DEFAULT_MULTI_REF_NAMES
+ * @see ::DEFAULT_MULTI_REF_NAMES_SHORT
+ * @see @ref MULTI_REF_TYPE_MASKS
*/
enum MULTI_REF_TYPES
{
- MULTI_REF_NONE = -1, /**< nothing, undefined */
- MULTI_REF_GPS = 0, /**< standard GPS */
- MULTI_REF_10MHZ, /**< 10 MHz input frequency */
- MULTI_REF_PPS, /**< 1 PPS input signal */
- MULTI_REF_10MHZ_PPS, /**< combined 10 MHz plus PPS */
- MULTI_REF_IRIG, /**< IRIG input */
- MULTI_REF_NTP, /**< Network Time Protocol (NTP) */
- MULTI_REF_PTP, /**< Precision Time Protocol (PTP, IEEE1588) */
- MULTI_REF_PTP_E1, /**< PTP over E1 */
- MULTI_REF_FREQ, /**< fixed frequency */
- MULTI_REF_PPS_STRING, /**< PPS in addition to string */
- MULTI_REF_GPIO, /**< variable input signal via GPIO */
- MULTI_REF_INTERNAL, /**< reserved, used internally by firmware only */
- MULTI_REF_PZF, /**< DCF77 PZF providing much more accuracy than a standard LWR */
- MULTI_REF_LWR, /**< long wave receiver. e.g. DCF77 AM, WWVB, MSF, JJY */
- MULTI_REF_GRC, /**< Glonass / GPS receiver */
- N_MULTI_REF /**< the number of defined sources, can not exceed bit number of uint32_t - 1 */
+ /// This ref type must not be used as index, but marks particular
+ /// ::XMULTI_REF_SETTINGS structures as "unused". It is only
+ /// supported if bit ::XMRIF_BIT_MRF_NONE_SUPP is set
+ MULTI_REF_NONE = -1,
+
+ MULTI_REF_GPS = 0, ///< standard GPS
+ MULTI_REF_10MHZ, ///< 10 MHz input frequency
+ MULTI_REF_PPS, ///< 1 PPS input signal
+ MULTI_REF_10MHZ_PPS, ///< combined 10 MHz plus PPS
+ MULTI_REF_IRIG, ///< IRIG input
+ MULTI_REF_NTP, ///< Network Time Protocol (NTP)
+ MULTI_REF_PTP, ///< Precision Time Protocol (PTP/IEEE1588)
+ MULTI_REF_PTP_E1, ///< PTP over E1
+ MULTI_REF_FREQ, ///< fixed frequency
+ MULTI_REF_PPS_STRING, ///< 1 PPS in addition to time string
+ MULTI_REF_GPIO, ///< variable input signal via GPIO
+ MULTI_REF_INTERNAL, ///< reserved, used internally by firmware only
+ MULTI_REF_PZF, ///< DCF77 PZF providing much more accuracy than a standard LWR
+ MULTI_REF_LWR, ///< long wave receiver. e.g. DCF77 AM, WWVB, MSF, JJY
+ MULTI_REF_GRC, ///< Glonass / GPS receiver
+ MULTI_REF_HAVEQUICK, ///< HaveQuick input
+ MULTI_REF_EXT_OSC, ///< external oscillator disciplined and looped back via 1 PPS I/O
+ N_MULTI_REF ///< the number of defined sources, must not exceed ::MAX_N_MULTI_REF_TYPES
};
+/**
+ * @brief Theoretical maximum number of multi ref input signal types
+ *
+ * Actually only ::N_MULTI_REF types have been defined, but ::N_MULTI_REF
+ * must not exceed the number of bits which can be hold by a uint32_t type.
+ */
+#define MAX_N_MULTI_REF_TYPES 32
-/*
- * Names of supported ref time sources
+
+/**
+ * @brief Names of known ref time sources
+ *
+ * @see ::MULTI_REF_TYPES
*/
#define DEFAULT_MULTI_REF_NAMES \
{ \
@@ -3502,139 +5112,236 @@ enum MULTI_REF_TYPES
"(reserved)", \
"DCF77 PZF Receiver", \
"Long Wave Receiver", \
- "GLONASS/GPS Receiver" \
+ "GLONASS/GPS Receiver", \
+ "HaveQuick Input", \
+ "ext. Osc." \
}
+/**
+ * @brief Short names of supported ref time sources
+ *
+ * Used e.g. to configure a particular input signal type
+ *
+ * @see ::MULTI_REF_TYPES
+ */
+#define DEFAULT_MULTI_REF_NAMES_SHORT \
+{ \
+ "GPS", \
+ "FRQ", \
+ "PPS", \
+ "10MHZ+PPS", \
+ "TCR", \
+ "NTP", \
+ "PTP hq", \
+ "PTP E1", \
+ "Fixed in", \
+ "STR in", \
+ "GPIO in", \
+ "(reserved)", \
+ "PZF", \
+ "LWR", \
+ "GGR", \
+ "HQI", \
+ "EXT" \
+}
-/*
- * Bit masks used to indicate supported reference sources
- */
-#define HAS_MULTI_REF_GPS ( 1UL << MULTI_REF_GPS )
-#define HAS_MULTI_REF_10MHZ ( 1UL << MULTI_REF_10MHZ )
-#define HAS_MULTI_REF_PPS ( 1UL << MULTI_REF_PPS )
-#define HAS_MULTI_REF_10MHZ_PPS ( 1UL << MULTI_REF_10MHZ_PPS )
-#define HAS_MULTI_REF_IRIG ( 1UL << MULTI_REF_IRIG )
-#define HAS_MULTI_REF_NTP ( 1UL << MULTI_REF_NTP )
-#define HAS_MULTI_REF_PTP ( 1UL << MULTI_REF_PTP )
-#define HAS_MULTI_REF_PTP_E1 ( 1UL << MULTI_REF_PTP_E1 )
-
-#define HAS_MULTI_REF_FREQ ( 1UL << MULTI_REF_FREQ )
-#define HAS_MULTI_REF_PPS_STRING ( 1UL << MULTI_REF_PPS_STRING )
-#define HAS_MULTI_REF_GPIO ( 1UL << MULTI_REF_GPIO )
-#define HAS_MULTI_REF_INTERNAL ( 1UL << MULTI_REF_INTERNAL )
-#define HAS_MULTI_REF_PZF ( 1UL << MULTI_REF_PZF )
-#define HAS_MULTI_REF_LWR ( 1UL << MULTI_REF_LWR )
-#define HAS_MULTI_REF_GRC ( 1UL << MULTI_REF_GRC )
+/**
+ * @brief Bit masks associated with multi ref types
+ *
+ * Used to indicate which multi ref types are supported, e.g.
+ * in ::XMULTI_REF_INFO::supp_ref or ::MULTI_REF_INFO::supp_ref.
+ *
+ * @see ::MULTI_REF_TYPES
+ *
+ * @anchor MULTI_REF_TYPE_MASKS @{ */
-/*
- * There are 2 different ways to configure multi ref support
- * provided by some devices.
+#define HAS_MULTI_REF_GPS ( 1UL << MULTI_REF_GPS ) ///< see ::MULTI_REF_GPS
+#define HAS_MULTI_REF_10MHZ ( 1UL << MULTI_REF_10MHZ ) ///< see ::MULTI_REF_10MHZ
+#define HAS_MULTI_REF_PPS ( 1UL << MULTI_REF_PPS ) ///< see ::MULTI_REF_PPS
+#define HAS_MULTI_REF_10MHZ_PPS ( 1UL << MULTI_REF_10MHZ_PPS ) ///< see ::MULTI_REF_10MHZ_PPS
+#define HAS_MULTI_REF_IRIG ( 1UL << MULTI_REF_IRIG ) ///< see ::MULTI_REF_IRIG
+#define HAS_MULTI_REF_NTP ( 1UL << MULTI_REF_NTP ) ///< see ::MULTI_REF_NTP
+#define HAS_MULTI_REF_PTP ( 1UL << MULTI_REF_PTP ) ///< see ::MULTI_REF_PTP
+#define HAS_MULTI_REF_PTP_E1 ( 1UL << MULTI_REF_PTP_E1 ) ///< see ::MULTI_REF_PTP_E1
+
+#define HAS_MULTI_REF_FREQ ( 1UL << MULTI_REF_FREQ ) ///< see ::MULTI_REF_FREQ
+#define HAS_MULTI_REF_PPS_STRING ( 1UL << MULTI_REF_PPS_STRING ) ///< see ::MULTI_REF_PPS_STRING
+#define HAS_MULTI_REF_GPIO ( 1UL << MULTI_REF_GPIO ) ///< see ::MULTI_REF_GPIO
+#define HAS_MULTI_REF_INTERNAL ( 1UL << MULTI_REF_INTERNAL ) ///< see ::MULTI_REF_INTERNAL
+#define HAS_MULTI_REF_PZF ( 1UL << MULTI_REF_PZF ) ///< see ::MULTI_REF_PZF
+#define HAS_MULTI_REF_LWR ( 1UL << MULTI_REF_LWR ) ///< see ::MULTI_REF_LWR
+#define HAS_MULTI_REF_GRC ( 1UL << MULTI_REF_GRC ) ///< see ::MULTI_REF_GRC
+#define HAS_MULTI_REF_HAVEQUICK ( 1UL << MULTI_REF_HAVEQUICK ) ///< see ::MULTI_REF_HAVEQUICK
+
+#define HAS_MULTI_REF_EXT_OSC ( 1UL << MULTI_REF_EXT_OSC ) ///< see ::MULTI_REF_EXT_OSC
+
+/** @} anchor MULTI_REF_TYPE_MASKS */
+
+/** @} defgroup group_multi_ref_common */
+
+
+
+/**
+ * @defgroup group_multi_ref_old Definitions used with the old multi ref API
*
- * Newer devices which have the GPS_FEAT_XMULTI_REF flag set
- * in RECEIVER_INFO::features support the newer XMULTI_REF_...
- * structures which provide a more flexible interface.
+ * This API has been deprecated by a newer one which should be used preferably.
*
- * Older devices which have the GPS_FEAT_MULTI_REF flag set
- * support these MULTI_REF_... structures below where
- * the number of supported input sources and priorities
- * is limited to N_MULTI_REF_PRIO.
- */
+ * @see @ref group_multi_ref_ext
+ *
+ * @{ */
+/**
+ * @brief Maximum number of input sources
+ *
+ * The number of supported input sources and priorities is
+ * limited to this value if the old API is used, i.e. if only
+ * the ::GPS_FEAT_MULTI_REF flag is set.
+ */
#define N_MULTI_REF_PRIO 4
/**
- The structure below is used to configure the priority of
- the supported ref sources.
-
- The number stored in prio[0] of the array indicates the ref time
- source with highest priority. If that source fails, the device
- falls back to the source indicated by prio[1]. Each field of
- the prio[] array must be set to one of the values 0..N_MULTI_REF-1,
- or to -1 (0xFF) if the value is not assigned.
+ * @brief A structure used to configure the priority of the supported ref sources
+ *
+ * The number stored in prio[0] of the array indicates the ref time
+ * source with highest priority. If that source fails, the device
+ * falls back to the source indicated by prio[1]. Each field of
+ * the prio[] array has to be set to one of the values 0..::N_MULTI_REF-1,
+ * or to ::MULTI_REF_NONE if no time source is specified.
*/
typedef struct
{
uint8_t prio[N_MULTI_REF_PRIO];
+
} MULTI_REF_SETTINGS;
/**
- The structure below is used to query the MULTI_REF configuration,
- plus the supported ref sources.
+ * @brief A structure used to query MULTI_REF configuration parameters
+ *
+ * This also includes a bit mask of supported ref sources.
*/
typedef struct
{
- MULTI_REF_SETTINGS settings; /* current settings */
- uint32_t supp_ref; /* supp. HAS_MULTI_REF_... codes or'ed */
- uint16_t n_levels; /* supp. levels, 0..N_MULTI_REF_PRIO */
- uint16_t flags; /* reserved, currently 0 */
+ MULTI_REF_SETTINGS settings; ///< current settings
+ uint32_t supp_ref; ///< bit mask of supported sources, see @ref MULTI_REF_TYPE_MASKS
+ uint16_t n_levels; ///< supported priority levels, 0..::N_MULTI_REF_PRIO-1
+ uint16_t flags; ///< reserved, currently always 0
+
} MULTI_REF_INFO;
-/*
- * The type below is used to query the MULTI_REF status information,
+/**
+ * @brief A data type used to query MULTI_REF status information
+ *
+ * @see ::MULTI_REF_STATUS_BIT_MASKS
*/
-typedef uint16_t MULTI_REF_STATUS; /* flag bits as defined below */
+typedef uint16_t MULTI_REF_STATUS;
-/*
- * The bits and associated bit masks below are used with the
- * MULTI_REF_STATUS type. Each bit is set if the associated
- * condition is true and is reset if the condition is not true:
- */
-enum
-{
- WRN_MODULE_MODE, /* selected input mode was invalid, set to default */
- WRN_COLD_BOOT, /* GPS is in cold boot mode */
- WRN_WARM_BOOT, /* GPS is in warm boot mode */
- WRN_ANT_DISCONN, /* antenna is disconnected */
- WRN_10MHZ_UNLOCK, /* impossible to lock to external 10MHz reference */
- WRN_1PPS_UNLOCK, /* impossible to lock to external 1PPS reference */
- WRN_GPS_UNLOCK, /* impossible to lock to GPS */
- WRN_10MHZ_MISSING, /* external 10MHz signal not available */
- WRN_1PPS_MISSING, /* external 1PPS signal not available */
- N_MULTI_REF_STATUS_BITS
+/**
+ * @brief Enumeration of multi ref status bits
+ *
+ * @see ::MULTI_REF_STATUS_BIT_MASKS
+ */
+enum MULTI_REF_STATUS_BITS
+{
+ WRN_MODULE_MODE, ///< selected input mode was invalid, set to default
+ WRN_COLD_BOOT, ///< GPS is in cold boot mode
+ WRN_WARM_BOOT, ///< GPS is in warm boot mode
+ WRN_ANT_DISCONN, ///< antenna is disconnected
+ WRN_10MHZ_UNLOCK, ///< impossible to lock to external 10 MHz reference
+ WRN_1PPS_UNLOCK, ///< impossible to lock to external 1 PPS reference
+ WRN_GPS_UNLOCK, ///< impossible to lock to GPS
+ WRN_10MHZ_MISSING, ///< external 10 MHz signal not available
+ WRN_1PPS_MISSING, ///< external 1 PPS signal not available
+ N_MULTI_REF_STATUS_BITS ///< the number of known bits
};
-#define MSK_WRN_COLD_BOOT ( 1UL << WRN_COLD_BOOT )
-#define MSK_WRN_WARM_BOOT ( 1UL << WRN_WARM_BOOT )
-#define MSK_WRN_ANT_DISCONN ( 1UL << WRN_ANT_DISCONN )
-#define MSK_WRN_10MHZ_UNLOCK ( 1UL << WRN_10MHZ_UNLOCK )
-#define MSK_WRN_1PPS_UNLOCK ( 1UL << WRN_1PPS_UNLOCK )
-#define MSK_WRN_GPS_UNLOCK ( 1UL << WRN_GPS_UNLOCK )
-#define MSK_WRN_10MHZ_MISSING ( 1UL << WRN_10MHZ_MISSING )
-#define MSK_WRN_1PPS_MISSING ( 1UL << WRN_1PPS_MISSING )
-#define MSK_WRN_MODULE_MODE ( 1UL << WRN_MODULE_MODE )
+
+/**
+ * @brief Bit masks associated with ::MULTI_REF_STATUS_BITS
+ *
+ * Used with ::MULTI_REF_STATUS.
+ *
+ * @see ::MULTI_REF_STATUS_BITS
+ */
+enum MULTI_REF_STATUS_BIT_MASKS
+{
+ MSK_WRN_COLD_BOOT = ( 1UL << WRN_COLD_BOOT ), ///< see ::WRN_COLD_BOOT
+ MSK_WRN_WARM_BOOT = ( 1UL << WRN_WARM_BOOT ), ///< see ::WRN_WARM_BOOT
+ MSK_WRN_ANT_DISCONN = ( 1UL << WRN_ANT_DISCONN ), ///< see ::WRN_ANT_DISCONN
+ MSK_WRN_10MHZ_UNLOCK = ( 1UL << WRN_10MHZ_UNLOCK ), ///< see ::WRN_10MHZ_UNLOCK
+ MSK_WRN_1PPS_UNLOCK = ( 1UL << WRN_1PPS_UNLOCK ), ///< see ::WRN_1PPS_UNLOCK
+ MSK_WRN_GPS_UNLOCK = ( 1UL << WRN_GPS_UNLOCK ), ///< see ::WRN_GPS_UNLOCK
+ MSK_WRN_10MHZ_MISSING = ( 1UL << WRN_10MHZ_MISSING ), ///< see ::WRN_10MHZ_MISSING
+ MSK_WRN_1PPS_MISSING = ( 1UL << WRN_1PPS_MISSING ), ///< see ::WRN_1PPS_MISSING
+ MSK_WRN_MODULE_MODE = ( 1UL << WRN_MODULE_MODE ) ///< see ::WRN_MODULE_MODE
+};
+
+/** @} defgroup group_multi_ref_old */
/**
- * @defgroup group_xmr_cfg Extended multiref configuration stuff
+ * @defgroup group_multi_ref_ext Extended multi ref definitions
*
- * If the RECEIVER_INFO::features flag GPS_FEAT_XMULTI_REF is set
- * then the following XMULTI_REF_... data structures must be used
- * instead of the older MULTI_REF_... structures.
+ * If the ::GPS_HAS_XMULTI_REF feature is set in ::RECEIVER_INFO::features then
+ * the XMULTI_REF (extended multi ref, XMR) feature and API are supported and
+ * must be used in favor of the older multi ref API (see @ref group_multi_ref_old).
*
- * Those devices support a number of priority levels addressed by
- * the priority index, starting at 0 for highest priority. A single
- * reference time source from the set of supported sources can be
- * assigned to each priority level.
+ * Devices supporting the XMULTI_REF feature provide a number of
+ * priority levels addressed by the priority index, starting at 0
+ * for highest priority. A single reference time source from the set
+ * of supported sources can be assigned to each priority level.
*
* These structures are used to configure the individual
* time source for each priority level, and retrieve the status
* of the time source at each priority level.
*
+ * If ::GPS_HAS_XMRS_MULT_INSTC is also set in ::RECEIVER_INFO::features then
+ * ::XMULTI_REF_INSTANCES can be used to find out which types of input source
+ * are supported (::XMULTI_REF_INSTANCES::n_inst array entries != 0), and
+ * how many priority levels are supported to get an input source assigned
+ * (::XMULTI_REF_INSTANCES::n_xmr_settings).
+ *
+ * If ::XMRIF_MSK_HOLDOVER_STATUS_SUPP is set in ::XMULTI_REF_INSTANCES::flags
+ * then ::XMR_HOLDOVER_STATUS can be used to monitor the switching between
+ * different time sources when they become available or unavailable.
+ *
+ * If an XMR time source at a high priority level becomes unavailable the
+ * XMR control function tries to find and switch to a different time source
+ * at a lower level of the priority list, which is still available.
+ *
+ * On the other hand, if a time source at a higher priority level becomes
+ * available again, the XMR control function switches over to the time source
+ * at the higher priority even if the current time source is still available.
+ *
+ * If the accuracy of the time source at the next priority level is better than
+ * the accuracy of the time source at the current priority level then switching
+ * can be done immediately. However, if the next time source is worse than
+ * the current one it makes more sense to switch only after a certain holdover
+ * interval.
+ *
+ * The holdover interval is computed so that the time error due to the expected
+ * drift of the previously disciplined time base grows until it reaches the
+ * accuracy level of the next available reference time source.
+ *
+ * Only if the time source at the current priority level is still unavailable
+ * when the holdover interval expires the reference time source is switched
+ * to the time source at the next available priority level.
+ *
* @{ */
+
/**
* @brief Identifier for a reference source
*/
typedef struct
{
- uint8_t type; /**< one of the enum MULTI_REF_TYPES */
- uint8_t instance; /**< instance number, if multiple instances are supported, else 0 */
+ uint8_t type; ///< see ::MULTI_REF_TYPES, and note for ::XMRIF_BIT_MRF_NONE_SUPP
+ uint8_t instance; ///< instance number, if multiple instances are supported, else 0
} XMULTI_REF_ID;
@@ -3645,53 +5352,68 @@ typedef struct
*/
typedef struct
{
- XMULTI_REF_ID id; /**< time source identifier */
- uint16_t flags; /**< reserved, currently always 0 */
- NANO_TIME bias; /**< time bias, e.g. path delay */
- NANO_TIME precision; /**< precision of the time source */
- uint32_t fine_limit; /**< smooth control if below this limit */
+ XMULTI_REF_ID id; ///< reference time source identifier
+ uint16_t flags; ///< reserved, currently always 0
+ NANO_TIME bias; ///< time bias, e.g. path delay @todo specify sign vs. earlier/later
+ NANO_TIME precision; ///< precision of the time source
+ uint32_t reserved; ///< reserved, currently always 0
} XMULTI_REF_SETTINGS;
/**
- * @brief Reference source configuration settings for a specific priority level
+ * @brief Reference source configuration for a specific priority level
*
- * @note After configuring, a structure with idx == 0xFFFF (-1) must be sent
- * to let the changes become effective.
+ * @note After all other ::XMULTI_REF_SETTINGS_IDX configuration structures
+ * have been sent to a device, an additional structure with idx == -1 (0xFFFF)
+ * has to be sent to let the new settings come into effect.
*/
typedef struct
{
- uint16_t idx; /* the priority level index, highest == 0 */
- XMULTI_REF_SETTINGS settings; /* the settings configured for this level */
+ uint16_t idx; ///< the priority level index (highest == 0), 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1
+ XMULTI_REF_SETTINGS settings; ///< the settings configured for this level
} XMULTI_REF_SETTINGS_IDX;
/**
- * @brief Reference source configuration settings and capabilities
+ * @brief Reference source capabilities and current configuration
*/
typedef struct
{
- XMULTI_REF_SETTINGS settings; /**< current settings */
- uint32_t supp_ref; /**< bit mask of or'ed HAS_MULTI_REF_... codes */
- uint8_t n_supp_ref; /**< number of supported ref time sources */
- uint8_t n_prio; /**< number of supported priority levels */
- uint16_t flags; /**< currently always 0 */
+ XMULTI_REF_SETTINGS settings; ///< current settings
+
+ /**
+ * @deprecated Deprecated by ::XMULTI_REF_INSTANCES::n_inst.
+ * If ::GPS_HAS_XMRS_MULT_INSTC is *not* set then this field provides
+ * a bit mask of supported sources (see @ref MULTI_REF_TYPE_MASKS),
+ * and only a single instance of each source signal type is supported.
+ */
+ uint32_t supp_ref;
+
+ /**
+ * @deprecated Deprecated by ::XMULTI_REF_INSTANCES::n_xmr_settings.
+ * If ::GPS_HAS_XMRS_MULT_INSTC is *not* set then this field
+ * reports the number of priority levels supported by the device.
+ */
+ uint8_t n_supp_ref;
+
+ uint8_t reserved; ///< reserved, don't use, currently always 0
+ uint16_t flags; ///< reserved, don't use, currently always 0
} XMULTI_REF_INFO;
/**
- * @brief Reference source configuration settings and capabilities for a specific priority level
+ * @brief Reference source capabilities and current configuration for a specific priority level
*/
typedef struct
{
- uint16_t idx; /**< the priority level index, highest == 0 */
- XMULTI_REF_INFO info; /**< ref source cfg and capabilities */
+ uint16_t idx; ///< the priority level index (highest == 0), 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1
+ XMULTI_REF_INFO info; ///< ref source configuration and capabilities
} XMULTI_REF_INFO_IDX;
@@ -3702,99 +5424,96 @@ typedef struct
*/
typedef struct
{
- XMULTI_REF_ID id; /**< time source identifier */
- uint16_t status; /**< flag bits as defined below */
- NANO_TIME offset; /**< time offset from main time base */
- uint16_t flags; /**< see flags specified below */
- uint8_t ssm; /**< synchronization status message ( if supported by src. )*/
- uint8_t soc; /**< signal outage counter ( updt. on loss of signal ) */
+ XMULTI_REF_ID id; ///< time source identifier
+ uint16_t status; ///< status bits, see @ref XMR_REF_STATUS_BIT_MASKS
+ NANO_TIME offset; ///< time offset from main time base @todo specify sign vs. earlier/later
+ uint16_t flags; ///< flags, currently unused
+ uint8_t ssm; ///< synchronization status message, if supported by signal source
+ uint8_t soc; ///< signal outage counter, incremented on loss of signal
+
} XMULTI_REF_STATUS;
/**
- * @brief Bits and masks used with XMULTI_REF_STATUS::flags
- *
- * @note This API is only supported if bit GPS_HAS_XMRS_MULT_INSTC
- * is set in RECEIVER_INFO::features.
+ * @brief Status information on a ref time source at a specific priority level
*/
-enum
+typedef struct
{
- XMRSF_BIT_MULT_INSTC_SUPP, /**< multiple instances of the same ref type supported */
- XMRSF_BIT_IS_EXTERNAL, /**< this ref source is on extension card */
- N_XMRS_FLAGS
-};
+ uint16_t idx; ///< the priority level index (highest == 0), 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1
+ XMULTI_REF_STATUS status; ///< status information
-#define XMRSF_MSK_MULT_INSTC_SUPP ( 1UL << XMRSF_BIT_MULT_INSTC_SUPP )
-#define XMRSF_MSK_IS_EXTERNAL ( 1UL << XMRSF_BIT_IS_EXTERNAL )
+} XMULTI_REF_STATUS_IDX;
/**
- * @brief Status information on a ref time source at a specific priority level
+ * @brief XMULTI_REF status bits
*/
-typedef struct
+enum XMR_REF_STATUS_BITS
{
- uint16_t idx; /**< the priority level index, highest == 0 */
- XMULTI_REF_STATUS status; /**< status information */
+ XMRS_BIT_NOT_SUPP, ///< ref type cfg'd for this level is not supported
+ XMRS_BIT_NO_CONN, ///< input signal is disconnected
+ XMRS_BIT_NO_SIGNAL, ///< no input signal
+ XMRS_BIT_IS_MASTER, ///< reference is master source
+ XMRS_BIT_IS_LOCKED, ///< locked to input signal
+ XMRS_BIT_IS_ACCURATE, ///< oscillator control has reached full accuracy
+ XMRS_BIT_NOT_SETTLED, ///< reference time signal not settled
+ XMRS_BIT_NOT_PHASE_LOCKED, ///< oscillator not phase locked to PPS
+ XMRS_BIT_NUM_SRC_EXC, ///< number of available sources exceeds what can be handled
+ XMRS_BIT_IS_EXTERNAL, ///< this ref source is on extension card
+ XMRS_BIT_LOW_JITTER, ///< this ref source has low jitter
+ N_XMRS_BITS ///< number of know status bits
+};
-} XMULTI_REF_STATUS_IDX;
+/**
+ * @brief Bit masks associated with ::XMR_REF_STATUS_BITS
+ *
+ * Used with ::XMULTI_REF_STATUS::status.
+ *
+ * @see ::XMR_REF_STATUS_BITS
+ *
+ * @anchor XMR_REF_STATUS_BIT_MASKS @{ */
+
+#define XMRS_MSK_NOT_SUPP ( 1UL << XMRS_BIT_NOT_SUPP ) ///< see ::XMRS_BIT_NOT_SUPP
+#define XMRS_MSK_NO_CONN ( 1UL << XMRS_BIT_NO_CONN ) ///< see ::XMRS_BIT_NO_CONN
+#define XMRS_MSK_NO_SIGNAL ( 1UL << XMRS_BIT_NO_SIGNAL ) ///< see ::XMRS_BIT_NO_SIGNAL
+#define XMRS_MSK_IS_MASTER ( 1UL << XMRS_BIT_IS_MASTER ) ///< see ::XMRS_BIT_IS_MASTER
+#define XMRS_MSK_IS_LOCKED ( 1UL << XMRS_BIT_IS_LOCKED ) ///< see ::XMRS_BIT_IS_LOCKED
+#define XMRS_MSK_IS_ACCURATE ( 1UL << XMRS_BIT_IS_ACCURATE ) ///< see ::XMRS_BIT_IS_ACCURATE
+#define XMRS_MSK_NOT_SETTLED ( 1UL << XMRS_BIT_NOT_SETTLED ) ///< see ::XMRS_BIT_NOT_SETTLED
+#define XMRS_MSK_NOT_PHASE_LOCKED ( 1UL << XMRS_BIT_NOT_PHASE_LOCKED ) ///< see ::XMRS_BIT_NOT_PHASE_LOCKED
+#define XMRS_MSK_NUM_SRC_EXC ( 1UL << XMRS_BIT_NUM_SRC_EXC ) ///< see ::XMRS_BIT_NUM_SRC_EXC
+#define XMRS_MSK_IS_EXTERNAL ( 1UL << XMRS_BIT_IS_EXTERNAL ) ///< see ::XMRS_BIT_IS_EXTERNAL
+#define XMRS_MSK_LOW_JITTER ( 1UL << XMRS_BIT_LOW_JITTER ) ///< see ::XMRS_BIT_LOW_JITTER
+
+/** @} anchor XMR_REF_STATUS_BIT_MASKS */
/**
- * @brief Bits and bit masks used with XMULTI_REF_STATUS::status
+ * @brief XMRS status bit name strings
*
- * @note Flags XMRS_BIT_MULT_INSTC_SUPP and XMRS_BIT_NUM_SRC_EXC
- * are set in the status flags for every priority if the associated
- * condition is met.
- */
-enum
-{
- XMRS_BIT_NOT_SUPP, /**< ref type cfg'd for this level is not supported */
- XMRS_BIT_NO_CONN, /**< input signal is disconnected */
- XMRS_BIT_NO_SIGNAL, /**< no input signal */
- XMRS_BIT_IS_MASTER, /**< reference is master source */
- XMRS_BIT_IS_LOCKED, /**< locked to input signal */
- XMRS_BIT_IS_ACCURATE, /**< oscillator control has reached full accuracy */
- XMRS_BIT_NOT_SETTLED, /**< reference time signal not settled */
- XMRS_BIT_NOT_PHASE_LOCKED, /**< oscillator not phase locked to PPS */
- XMRS_BIT_NUM_SRC_EXC, /**< number of available sources exceeds what can be handled */
- XMRS_BIT_IS_EXTERNAL, /**< this ref source is on extension card */
- N_XMRS_BITS /**< number of know status bits */
-};
-
-#define XMRS_MSK_NOT_SUPP ( 1UL << XMRS_BIT_NOT_SUPP )
-#define XMRS_MSK_NO_CONN ( 1UL << XMRS_BIT_NO_CONN )
-#define XMRS_MSK_NO_SIGNAL ( 1UL << XMRS_BIT_NO_SIGNAL )
-#define XMRS_MSK_IS_MASTER ( 1UL << XMRS_BIT_IS_MASTER )
-#define XMRS_MSK_IS_LOCKED ( 1UL << XMRS_BIT_IS_LOCKED )
-#define XMRS_MSK_IS_ACCURATE ( 1UL << XMRS_BIT_IS_ACCURATE )
-#define XMRS_MSK_NOT_SETTLED ( 1UL << XMRS_BIT_NOT_SETTLED )
-#define XMRS_MSK_NOT_PHASE_LOCKED ( 1UL << XMRS_BIT_NOT_PHASE_LOCKED )
-#define XMRS_MSK_NUM_SRC_EXC ( 1UL << XMRS_BIT_NUM_SRC_EXC )
-#define XMRS_MSK_IS_EXTERNAL ( 1UL << XMRS_BIT_IS_EXTERNAL )
-
-/*
- * Initializers for XMRS status bit strings.
+ * @see ::XMR_REF_STATUS_BITS
*/
#define MBG_XMRS_STATUS_STRS \
{ \
"Ref type not supported", \
"No connection", \
"No signal", \
- "Is Master", \
+ "Is master", \
"Is locked", \
- "Is accuracte", \
+ "Is accurate", \
"Not settled", \
"Phase not locked", \
"Number sources exceeds limit", \
- "Is external" \
+ "Is external", \
+ "Low jitter" \
}
/*
- * An initializer for a XMULTI_REF_STATUS variable
+ * An initializer for a ::XMULTI_REF_STATUS variable
* with status invalid / not used
*/
#define XMULTI_REF_STATUS_INVALID \
@@ -3807,29 +5526,201 @@ enum
/**
- * @brief The number of supported instances of each ref source type
+ * @brief General info on supported XMR sources and instances
+ *
+ * @note This structure is only supported if ::GPS_HAS_XMRS_MULT_INSTC
+ * is set in ::RECEIVER_INFO::features.
+ *
+ * The field ::XMULTI_REF_INSTANCES::n_xmr_settings reports the maximum number
+ * of entries that can be held by the input source table provided by this device.
+ * The input source table entry with the lowest index has the highest priority,
+ * and values 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1 can be used as index
+ * when reading ::XMULTI_REF_INFO_IDX or ::XMULTI_REF_STATUS_IDX from the device,
+ * or when writing ::XMULTI_REF_SETTINGS_IDX to the device to configure
+ * the priority/order of input sources.
+ *
+ * An input source table entry is empty if ::XMULTI_REF_ID::type is set to
+ * ::MULTI_REF_NONE in ::XMULTI_REF_SETTINGS::id, and accordingly
+ * in ::XMULTI_REF_STATUS::id.
*
- * @note This structure is only supported if bit GPS_HAS_XMRS_MULT_INSTC
- * is set in RECEIVER_INFO::features.
+ * The array ::XMULTI_REF_INSTANCES::n_inst reports how many instances are supported
+ * for every known reference type. For example, if 2 PPS input signals were supported
+ * then ::XMULTI_REF_INSTANCES::n_inst[::MULTI_REF_PPS] was set to 2. Even though
+ * this array can hold up to ::MAX_N_MULTI_REF_TYPES entries, the number entries
+ * which are actually used is ::N_MULTI_REF, according to the number of known
+ * reference signal types, which is less or equal than ::MAX_N_MULTI_REF_TYPES.
*/
typedef struct
{
- uint32_t flags; /**< currently always 0 */
- uint16_t n_xmr_settings; /**< number of configurable multi ref settings */
- uint8_t slot_id; /**< current slot ID of board ( 0..15 ) */
- uint8_t reserved; /**< reserved */
- uint8_t n_inst[32]; /**< N_MULTI_REF entries used, but can not exceed bit number of uint32_t - 1 */
+ uint32_t flags; ///< see ::XMR_INST_FLAG_BIT_MASKS
+ uint16_t n_xmr_settings; ///< number of entries in the input source priority table
+ uint8_t slot_id; ///< ID of the slot in which this device is installed, 0 or up to 15, if multiple slots not supported
+ uint8_t reserved; ///< reserved, don't use, currently always 0
+ uint8_t n_inst[MAX_N_MULTI_REF_TYPES]; ///< the number of supported instances of each input signal type
+
} XMULTI_REF_INSTANCES;
-/** @} group_xmr_cfg */
+
+
+/**
+ * @brief Enumeration of flag bits used with XMULTI_REF instances
+ *
+ * @see ::XMR_INST_FLAG_BIT_MASKS
+ */
+enum XMR_INST_FLAGS
+{
+ /// This flag indicates that configuration programs may set
+ /// ::XMULTI_REF_ID::type to ::MULTI_REF_NONE in ::XMULTI_REF_SETTINGS::id
+ /// for unused priority levels, and that this will be reflected in
+ /// ::XMULTI_REF_STATUS::id accordingly. With some older firmware versions
+ /// this was not supported.
+ XMRIF_BIT_MRF_NONE_SUPP,
+
+ XMRIF_BIT_HOLDOVER_STATUS_SUPP, ///< ::XMR_HOLDOVER_STATUS and associated types supported
+
+ N_XMRIF_BITS ///< number of known flag bits
+};
+
+
+/**
+ * @brief Bit masks associated with ::XMR_INST_FLAGS
+ *
+ * Used with ::XMULTI_REF_INSTANCES::flags.
+ *
+ * @see ::XMR_INST_FLAGS
+ */
+enum XMR_INST_FLAG_BIT_MASKS
+{
+ XMRIF_MSK_MRF_NONE_SUPP = ( 1UL << XMRIF_BIT_MRF_NONE_SUPP ), ///< see ::XMRIF_BIT_MRF_NONE_SUPP
+ XMRIF_MSK_HOLDOVER_STATUS_SUPP = ( 1UL << XMRIF_BIT_HOLDOVER_STATUS_SUPP ) ///< see ::XMRIF_BIT_HOLDOVER_STATUS_SUPP
+};
+
+
+/**
+ * @brief XMR holdover interval, or elapsed holdover time, in [s]
+ */
+typedef uint32_t XMR_HOLDOVER_INTV;
+
+#define _mbg_swab_xmr_holdover_intv( _p ) \
+ _mbg_swab32( _p );
+
+
+
+/**
+ * @brief A code used to indicate that a input source table index is unspecified
+ */
+#define XMR_PRIO_LVL_UNSPEC -1
+
+
+/**
+ * @brief XMR holdover status
+ *
+ * Only supported if ::XMRIF_MSK_HOLDOVER_STATUS_SUPP is set in ::XMULTI_REF_INSTANCES::flags
+ *
+ * Reports the current holdover status including the elapsed holdover time
+ * and the currently active holdover interval, as well as the indices of the
+ * current and next XMR time source.
+ *
+ * The flag ::XMR_HLDOVR_MSK_IN_HOLDOVER is set if holdover mode is currently active.
+ *
+ * The fields ::XMR_HOLDOVER_STATUS::curr_prio and ::XMR_HOLDOVER_STATUS::nxt_prio
+ * specify the current or next priority level which can be in the range
+ * 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, or ::XMR_PRIO_LVL_UNSPEC if the
+ * index is undefined, e.g. because no input source is available to which can
+ * be switched after the holdover interval.
+ *
+ * The ::XMR_HOLDOVER_STATUS::mode field indicates the current XMR/holdover mode
+ * which is usually ::XMR_HLDOVR_AUTONOMOUS. However, in certain applications
+ * XMR switching is controlled remotely, in which case ::XMR_HOLDOVER_STATUS::mode
+ * is set to ::XMR_HLDOVR_REMOTE.
+ *
+ * If the device is in remote mode and needs to switch XMR sources then mode changes
+ * to ::XMR_HLDOVR_PRE_AUTONOMOUS, and the ::XMR_HOLDOVER_STATUS::remote_watchdog
+ * starts to count down. If the watchdog expires before a remote switch command
+ * has been received the device switches to ::XMR_HLDOVR_AUTONOMOUS.
+ */
+typedef struct
+{
+ uint8_t mode; ///< XMR/holdover mode, see ::XMR_HOLDOVER_STATUS_MODES
+ int8_t curr_prio; ///< current priority level, 0..::XMULTI_REF_INSTANCES::n_xmr_settings, or ::XMR_PRIO_LVL_UNSPEC
+ int8_t nxt_prio; ///< next priority level after holdover, 0..::XMULTI_REF_INSTANCES::n_xmr_settings, or ::XMR_PRIO_LVL_UNSPEC
+ uint8_t remote_watchdog; ///< counts down in ::XMR_HLDOVR_PRE_AUTONOMOUS mode
+ uint32_t reserved; ///< reserved, don't use, currently 0
+ XMR_HOLDOVER_INTV elapsed; ///< elapsed time in holdover mode, only valid if ::XMR_HLDOVR_MSK_IN_HOLDOVER is set
+ XMR_HOLDOVER_INTV interval; ///< current holdover interval, only valid if ::XMR_HLDOVR_MSK_IN_HOLDOVER is set
+ uint32_t flags; ///< holdover status flags, see ::XMR_HOLDOVER_STATUS_FLAG_MASKS
+
+} XMR_HOLDOVER_STATUS;
+
+
+/**
+ * @brief XMR holdover status modes
+ *
+ * Used with ::XMR_HOLDOVER_STATUS::mode.
+ *
+ * @see ::XMR_HOLDOVER_STATUS_MODE_NAMES
+ */
+enum XMR_HOLDOVER_STATUS_MODES
+{
+ XMR_HLDOVR_AUTONOMOUS, ///< autonomous mode, XMR sources are selected automatically by the device
+ XMR_HLDOVR_PRE_AUTONOMOUS, ///< going to switch to autonomous mode when ::XMR_HOLDOVER_STATUS::remote_watchdog reaches 0
+ XMR_HLDOVR_REMOTE, ///< remote mode, XMR switching done by external command/control
+ N_XMR_HOLDOVER_STATUS_MODES ///< the number of known modes
+};
+
+
+/**
+ * @brief String initializers for XMR holdover status mode
+ *
+ * @see ::XMR_HOLDOVER_STATUS_MODES
+ */
+#define XMR_HOLDOVER_STATUS_MODE_NAMES \
+{ \
+ "autonomous", \
+ "pre-autonomous", \
+ "remote" \
+}
+
+
+
+/**
+ * @brief XMR holdover status flag bits
+ *
+ * Used to define ::XMR_HOLDOVER_STATUS_FLAG_MASKS.
+ */
+enum XMR_HOLDOVER_STATUS_FLAG_BITS
+{
+ XMR_HLDOVR_BIT_IN_HOLDOVER, ///< the device is currently in holdover mode
+ XMR_HLDOVR_BIT_TRANSITION_ENBD, ///< timebase is in transition (being slewed) after sources have been switched
+ XMR_HLDOVR_BIT_IN_TRANSITION, ///< transition is currently active, slewing in progress
+ N_XMR_HOLDOVER_STATUS_FLAG_BITS ///< the number of known status flags
+};
+
+
+/**
+ * @brief XMR holdover status flag masks
+ *
+ * Used with ::XMR_HOLDOVER_STATUS::flags.
+ */
+enum XMR_HOLDOVER_STATUS_FLAG_MASKS
+{
+ XMR_HLDOVR_MSK_IN_HOLDOVER = ( 1UL << XMR_HLDOVR_BIT_IN_HOLDOVER ), ///< see ::XMR_HLDOVR_BIT_IN_HOLDOVER
+ XMR_HLDOVR_MSK_TRANSITION_ENBD = ( 1UL << XMR_HLDOVR_BIT_TRANSITION_ENBD ), ///< see ::XMR_HLDOVR_BIT_TRANSITION_ENBD
+ XMR_HLDOVR_MSK_IN_TRANSITION = ( 1UL << XMR_HLDOVR_BIT_IN_TRANSITION ) ///< see ::XMR_HLDOVR_BIT_IN_TRANSITION
+};
+
+
+/** @} defgroup group_multi_ref_ext */
+
+/** @} defgroup group_multi_ref_all */
/**
* @defgroup group_gpio GPIO port configuration stuff
*
- * @note This is only supported if the GPS_HAS_GPIO bit is set
- * in the RECEIVER_INFO::features mask.
+ * @note This is only supported if ::GPS_HAS_GPIO is set
+ * in the ::RECEIVER_INFO::features mask.
*
* @{ */
@@ -3838,17 +5729,52 @@ typedef struct
* @brief General GPIO config info to be read from a device
*
* Used to query from a device how many GPIO ports are supported
- * by the device, then index 0..num_io-1 configuration or status
- * records can be read from or written to the device.
+ * by the device, then index 0..::MBG_GPIO_CFG_LIMITS::num_io-1
+ * configuration or status records can be read from or written to
+ * the device.
*/
typedef struct
{
- uint32_t num_io; /**< number of supported GPIO ports */
- uint32_t reserved; /**< currently always 0 */
- uint32_t flags; /**< currently always 0 */
+ uint32_t num_io; ///< number of supported GPIO ports
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t flags; ///< see ::MBG_GPIO_CFG_LIMIT_FLAG_MASKS
} MBG_GPIO_CFG_LIMITS;
+#define _mbg_swab_gpio_cfg_limits( p ) \
+{ \
+ _mbg_swab32( &(_p)->num_io ); \
+ _mbg_swab32( &(_p)->reserved ); \
+ _mbg_swab32( &(_p)->flags ); \
+}
+
+
+
+/**
+ * @brief GPIO limits flag bits uded to define ::MBG_GPIO_CFG_LIMIT_FLAG_MASKS
+ *
+ * @see ::MBG_GPIO_CFG_LIMIT_FLAG_MASKS
+ */
+enum MBG_GPIO_CFG_LIMIT_FLAG_BITS
+{
+ MBG_GPIO_CFG_LIMIT_FLAG_BIT_STATUS_SUPP, ///< indicates that ::MBG_GPIO_STATUS is supported
+ N_MBG_GPIO_CFG_LIMIT_FLAG_BITS
+};
+
+
+
+/**
+ * @brief GPIO limits flag masks associated with ::MBG_GPIO_CFG_LIMIT_FLAG_BITS
+ *
+ * Used with ::MBG_GPIO_CFG_LIMITS::flags
+ *
+ * @see ::MBG_GPIO_CFG_LIMIT_FLAG_BITS
+ */
+enum MBG_GPIO_CFG_LIMIT_FLAG_MASKS
+{
+ MBG_GPIO_CFG_LIMIT_FLAG_MASK_STATUS_SUPP = ( 1UL << MBG_GPIO_CFG_LIMIT_FLAG_BIT_STATUS_SUPP ), ///< see ::MBG_GPIO_CFG_LIMIT_FLAG_BIT_STATUS_SUPP
+};
+
/**
@@ -3857,48 +5783,79 @@ typedef struct
* Usually a specific GPIO port can only be either an input
* or an output, and supports only a single signal type.
* This is due to hardware limitations, i.e. input or output
- * circuitry required for the given signal
+ * circuitry required for the given signal.
+ *
+ * @see ::DEFAULT_GPIO_TYPES_SHORT_STRS
*/
enum MBG_GPIO_TYPES
{
- MBG_GPIO_TYPE_FREQ_IN, /**< variable frequency input */
- MBG_GPIO_TYPE_FREQ_OUT, /**< variable frequency output */
- MBG_GPIO_TYPE_FIXED_FREQ_OUT, /**< fixed frequency output */
- MBG_GPIO_TYPE_BITS_IN, /**< framed data stream input */
- MBG_GPIO_TYPE_BITS_OUT, /**< framed data stream output */
- N_MBG_GPIO_TYPES /**< number of known types */
+ MBG_GPIO_TYPE_FREQ_IN, ///< variable frequency input, freq == 0 if input not used
+ MBG_GPIO_TYPE_FREQ_OUT, ///< variable frequency output
+ MBG_GPIO_TYPE_FIXED_FREQ_OUT, ///< fixed frequency output
+ MBG_GPIO_TYPE_BITS_IN, ///< framed data stream input
+ MBG_GPIO_TYPE_BITS_OUT, ///< framed data stream output
+ N_MBG_GPIO_TYPES ///< number of known types
};
-#define DEFAULT_GPIO_TYPES_SHORT_STRS \
-{ \
- "Freq. In", \
- "Freq. Out", \
- "Fixed Freq Out", \
- "BITS In", \
- "BITS Out" \
+#define DEFAULT_GPIO_TYPES_SHORT_STRS \
+{ \
+ "Freq. In", \
+ "Freq. Out", \
+ "Fixed Freq Out", \
+ "BITS In", \
+ "BITS Out" \
}
/**
- * @brief Enumeration of signal shapes
+ * @brief Enumeration of known signal shapes
*
* Used to specify the signal shape of an input or output
* frequency signal.
+ *
+ * @see ::MBG_GPIO_SIGNAL_SHAPE_MASKS
+ * @see ::DEFAULT_GPIO_SIGNAL_SHAPE_NAMES
*/
enum MBG_GPIO_SIGNAL_SHAPES
{
- MBG_GPIO_SIGNAL_SHAPE_UNSPECIFIED, /**< unknown or unspecified signal shape */
- MBG_GPIO_SIGNAL_SHAPE_SINE, /**< sine wave */
- MBG_GPIO_SIGNAL_SHAPE_SQUARE, /**< square wave */
- N_MBG_GPIO_SIGNAL_SHAPES /**< number of known signal shapes */
+ MBG_GPIO_SIGNAL_SHAPE_UNSPECIFIED, ///< unknown or unspecified signal shape
+ MBG_GPIO_SIGNAL_SHAPE_SINE, ///< sine wave
+ MBG_GPIO_SIGNAL_SHAPE_SQUARE, ///< square wave
+ N_MBG_GPIO_SIGNAL_SHAPES ///< number of known signal shapes
+};
+
+
+/**
+ * @brief Bit masks associated with ::MBG_GPIO_SIGNAL_SHAPES
+ *
+ * Used e.g. with ::MBG_GPIO_FREQ_IN_SUPP::supp_shapes,
+ * ::MBG_GPIO_FREQ_OUT_SUPP::supp_shapes,
+ * and ::MBG_GPIO_FIXED_FREQ_OUT_SUPP::supp_shapes.
+ *
+ * @see ::MBG_GPIO_SIGNAL_SHAPES
+ */
+enum MBG_GPIO_SIGNAL_SHAPE_MASKS
+{
+ MBG_GPIO_SIGNAL_SHAPE_MSK_UNSPECIFIED = ( 1UL << MBG_GPIO_SIGNAL_SHAPE_UNSPECIFIED ), ///< see ::MBG_GPIO_SIGNAL_SHAPE_UNSPECIFIED
+ MBG_GPIO_SIGNAL_SHAPE_MSK_SINE = ( 1UL << MBG_GPIO_SIGNAL_SHAPE_SINE ), ///< see ::MBG_GPIO_SIGNAL_SHAPE_SINE
+ MBG_GPIO_SIGNAL_SHAPE_MSK_SQUARE = ( 1UL << MBG_GPIO_SIGNAL_SHAPE_SQUARE ) ///< see ::MBG_GPIO_SIGNAL_SHAPE_SQUARE
};
-/** Bit masks of signal shapes, corresponding to enum MBG_GPIO_SIGNAL_SHAPES */
-#define MBG_GPIO_SIGNAL_SHAPE_MSK_UNSPECIFIED ( 1UL << MBG_GPIO_SIGNAL_SHAPE_UNSPECIFIED )
-#define MBG_GPIO_SIGNAL_SHAPE_MSK_SINE ( 1UL << MBG_GPIO_SIGNAL_SHAPE_SINE )
-#define MBG_GPIO_SIGNAL_SHAPE_MSK_SQUARE ( 1UL << MBG_GPIO_SIGNAL_SHAPE_SQUARE )
+
+
+/**
+ * @brief String initializers for GPIO signal shapes
+ *
+ * @see ::MBG_GPIO_SIGNAL_SHAPES
+ */
+#define DEFAULT_GPIO_SIGNAL_SHAPE_NAMES \
+{ \
+ "(unspec. shape)", \
+ "Sine wave", \
+ "Rectangle Pulse" \
+}
@@ -3909,8 +5866,8 @@ enum MBG_GPIO_SIGNAL_SHAPES
*/
typedef struct
{
- uint32_t hz; /**< integral number, Hz */
- uint32_t frac; /**< fractional part, binary */
+ uint32_t hz; ///< integral number [Hz]
+ uint32_t frac; ///< fractional part, binary (0x80000000 --> 0.5, 0xFFFFFFFF --> 0.9999999...)
} MBG_GPIO_FREQ;
@@ -3919,15 +5876,18 @@ typedef struct
/**
* @brief Configuration of a GPIO variable frequency input
*
- * @see MBG_GPIO_TYPE_FREQ_IN
+ * Used as sub-structure of ::MBG_GPIO_SETTINGS.
+ *
+ * @see ::MBG_GPIO_TYPE_FREQ_IN
+ * @see ::MBG_GPIO_SETTINGS
*/
typedef struct
{
- MBG_GPIO_FREQ freq; /**< frequency */
- uint32_t csc_limit; /**< max. cycle slip [1/1000 cycle units] */
- uint32_t shape; /**< signal shape, @see enum MBG_GPIO_SIGNAL_SHAPES */
- uint32_t reserved; /**< currently always 0 */
- uint32_t flags; /**< currently always 0 */
+ MBG_GPIO_FREQ freq; ///< frequency in range ::MBG_GPIO_FREQ_IN_SUPP::freq_min..::MBG_GPIO_FREQ_IN_SUPP::freq_max, or 0 if input is not used
+ uint32_t csc_limit; ///< max. cycle slip [1/1000 cycle units], see ::MBG_GPIO_FREQ_IN_SUPP::csc_limit_max
+ uint32_t shape; ///< selected signal shape, see ::MBG_GPIO_SIGNAL_SHAPES
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t flags; ///< reserved, currently always 0
} MBG_GPIO_FREQ_IN_SETTINGS;
@@ -3935,17 +5895,19 @@ typedef struct
/**
* @brief Supported options for a variable frequency GPIO input
*
- * @see MBG_GPIO_TYPE_FREQ_IN
+ * Used as sub-structure of ::MBG_GPIO_LIMITS.
+ *
+ * @see ::MBG_GPIO_TYPE_FREQ_IN
+ * @see ::MBG_GPIO_LIMITS
*/
typedef struct
{
- //##++++++++++++++++
- uint32_t freq_min; /**< minimum output frequency [Hz] */
- uint32_t freq_max; /**< maximum output frequency [Hz] */
- uint32_t csc_limit_max; /**< max. milli_phase, unspecified if 0 */
- uint32_t supp_shapes; /**< bit mask of supported signal shapes, @see enum MBG_GPIO_SIGNAL_SHAPES */
- uint32_t reserved; /**< currently always 0 */
- uint32_t flags; /**< currently always 0 */
+ uint32_t freq_min; ///< minimum output frequency [Hz]
+ uint32_t freq_max; ///< maximum output frequency [Hz]
+ uint32_t csc_limit_max; ///< 1/1000 units of the signal period, limited due to 10 ns sampling interval, see ::MBG_GPIO_FREQ_IN_SETTINGS::csc_limit //##++++++++++++++++
+ uint32_t supp_shapes; ///< bit mask of supported signal shapes, see ::MBG_GPIO_SIGNAL_SHAPE_MASKS
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t flags; ///< reserved, currently always 0
} MBG_GPIO_FREQ_IN_SUPP;
@@ -3954,15 +5916,18 @@ typedef struct
/**
* @brief Configuration of a GPIO variable frequency output
*
- * @see MBG_GPIO_TYPE_FREQ_OUT
+ * Used as sub-structure of ::MBG_GPIO_SETTINGS.
+ *
+ * @see ::MBG_GPIO_TYPE_FREQ_OUT
+ * @see ::MBG_GPIO_SETTINGS
*/
typedef struct
{
- MBG_GPIO_FREQ freq; /**< frequency */
- int32_t milli_phase; /**< phase [1/1000 degree units] */
- uint32_t shape; /**< signal shape, @see enum MBG_GPIO_SIGNAL_SHAPES */
- uint32_t reserved; /**< currently always 0 */
- uint32_t flags; /**< currently always 0 */
+ MBG_GPIO_FREQ freq; ///< frequency, see ::MBG_GPIO_FREQ_OUT_SUPP::freq_min and ::MBG_GPIO_FREQ_OUT_SUPP::freq_max
+ int32_t milli_phase; ///< phase [1/1000 degree units], see ::MBG_GPIO_FREQ_OUT_SUPP::milli_phase_max
+ uint32_t shape; ///< selected signal shape, see ::MBG_GPIO_SIGNAL_SHAPES
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t flags; ///< reserved, currently always 0
} MBG_GPIO_FREQ_OUT_SETTINGS;
@@ -3971,75 +5936,96 @@ typedef struct
/**
* @brief Supported options for a variable frequency GPIO output
*
- * @see MBG_GPIO_TYPE_FREQ_OUT
+ * Used as sub-structure of ::MBG_GPIO_LIMITS.
+ *
+ * @see ::MBG_GPIO_TYPE_FREQ_OUT
+ * @see ::MBG_GPIO_LIMITS
*/
typedef struct
{
- uint32_t freq_min; /**< minimum output frequency [Hz] */
- uint32_t freq_max; /**< maximum output frequency [Hz] */
- uint32_t freq_resolution; /**< frequency resolution [Hz], unspecified if 0 */
- uint32_t milli_phase_max; /**< max. abs. milli_phase */
- uint32_t supp_shapes; /**< bit mask of supported signal shapes, @see enum MBG_GPIO_SIGNAL_SHAPES */
- uint32_t reserved; /**< currently always 0 */
- uint32_t flags; /**< currently always 0 */
+ uint32_t freq_min; ///< minimum output frequency [Hz], see ::MBG_GPIO_FREQ_OUT_SETTINGS::freq
+ uint32_t freq_max; ///< maximum output frequency [Hz], see ::MBG_GPIO_FREQ_OUT_SETTINGS::freq
+ uint32_t freq_resolution; ///< frequency resolution [Hz], unspecified if 0
+ uint32_t milli_phase_max; ///< max. abs. milli_phase, see ::MBG_GPIO_FREQ_OUT_SETTINGS::milli_phase
+ uint32_t supp_shapes; ///< bit mask of supported signal shapes, see ::MBG_GPIO_SIGNAL_SHAPE_MASKS
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t flags; ///< reserved, currently always 0
} MBG_GPIO_FREQ_OUT_SUPP;
/**
- * @brief Supported fixed frequencies
- */
-enum MBG_GPIO_FIXED_FREQ
-{
- MBG_GPIO_FIXED_FREQ_8kHz, /**< 8kHz */
- MBG_GPIO_FIXED_FREQ_48kHz, /**< 48kHz */
- MBG_GPIO_FIXED_FREQ_1MHz, /**< 1MHz */
- MBG_GPIO_FIXED_FREQ_1544kHz, /**< 1.544MHz */
- MBG_GPIO_FIXED_FREQ_2048kHz, /**< 2.048MHz */
- MBG_GPIO_FIXED_FREQ_5MHz, /**< 5MHz */
- MBG_GPIO_FIXED_FREQ_10MHz, /**< 10MHz */
- MBG_GPIO_FIXED_FREQ_19440kHz, /**< 19.44MHz */
- N_MBG_GPIO_FIXED_FREQ /**< number of known frequencies */
+ * @brief Enumeration of predefined fixed frequencies
+ *
+ * @see ::MBG_GPIO_FIXED_FREQ_MASKS
+ * @see ::MBG_GPIO_FIXED_FREQ_STRS
+ */
+enum MBG_GPIO_FIXED_FREQS
+{
+ MBG_GPIO_FIXED_FREQ_8kHz, ///< 8 kHz
+ MBG_GPIO_FIXED_FREQ_48kHz, ///< 48 kHz
+ MBG_GPIO_FIXED_FREQ_1MHz, ///< 1 MHz
+ MBG_GPIO_FIXED_FREQ_1544kHz, ///< 1.544 MHz
+ MBG_GPIO_FIXED_FREQ_2048kHz, ///< 2.048 MHz
+ MBG_GPIO_FIXED_FREQ_5MHz, ///< 5 MHz
+ MBG_GPIO_FIXED_FREQ_10MHz, ///< 10 MHz
+ MBG_GPIO_FIXED_FREQ_19440kHz, ///< 19.44 MHz
+ N_MBG_GPIO_FIXED_FREQ ///< number of predefined fixed frequencies
};
-/** Bit masks of supported fixed frequencies */
-#define MSK_MBG_GPIO_FIXED_FREQ_8kHz ( 1UL << MBG_GPIO_FIXED_FREQ_8kHz )
-#define MSK_MBG_GPIO_FIXED_FREQ_48kHz ( 1UL << MBG_GPIO_FIXED_FREQ_48kHz )
-#define MSK_MBG_GPIO_FIXED_FREQ_1MHz ( 1UL << MBG_GPIO_FIXED_FREQ_1MHz )
-#define MSK_MBG_GPIO_FIXED_FREQ_1544kHz ( 1UL << MBG_GPIO_FIXED_FREQ_1544kHz )
-#define MSK_MBG_GPIO_FIXED_FREQ_2048kHz ( 1UL << MBG_GPIO_FIXED_FREQ_2048kHz )
-#define MSK_MBG_GPIO_FIXED_FREQ_5MHz ( 1UL << MBG_GPIO_FIXED_FREQ_5MHz )
-#define MSK_MBG_GPIO_FIXED_FREQ_10MHz ( 1UL << MBG_GPIO_FIXED_FREQ_10MHz )
-#define MSK_MBG_GPIO_FIXED_FREQ_19440kHz ( 1UL << MBG_GPIO_FIXED_FREQ_19440kHz )
+/**
+ * @brief Bit masks associated with ::MBG_GPIO_FIXED_FREQS
+ *
+ * @see ::MBG_GPIO_FIXED_FREQS
+ * @see ::MBG_GPIO_FIXED_FREQ_STRS
+ */
+enum MBG_GPIO_FIXED_FREQ_MASKS
+{
+ MSK_MBG_GPIO_FIXED_FREQ_8kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_8kHz ), ///< see ::MBG_GPIO_FIXED_FREQ_8kHz
+ MSK_MBG_GPIO_FIXED_FREQ_48kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_48kHz ), ///< see ::MBG_GPIO_FIXED_FREQ_48kHz
+ MSK_MBG_GPIO_FIXED_FREQ_1MHz = ( 1UL << MBG_GPIO_FIXED_FREQ_1MHz ), ///< see ::MBG_GPIO_FIXED_FREQ_1MHz
+ MSK_MBG_GPIO_FIXED_FREQ_1544kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_1544kHz ), ///< see ::MBG_GPIO_FIXED_FREQ_1544kHz
+ MSK_MBG_GPIO_FIXED_FREQ_2048kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_2048kHz ), ///< see ::MBG_GPIO_FIXED_FREQ_2048kHz
+ MSK_MBG_GPIO_FIXED_FREQ_5MHz = ( 1UL << MBG_GPIO_FIXED_FREQ_5MHz ), ///< see ::MBG_GPIO_FIXED_FREQ_5MHz
+ MSK_MBG_GPIO_FIXED_FREQ_10MHz = ( 1UL << MBG_GPIO_FIXED_FREQ_10MHz ), ///< see ::MBG_GPIO_FIXED_FREQ_10MHz
+ MSK_MBG_GPIO_FIXED_FREQ_19440kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_19440kHz ) ///< see ::MBG_GPIO_FIXED_FREQ_19440kHz
+};
-/*
- * Initializers for GPIO fixed frequency strings.
+
+/**
+ * @brief Initializers for an array of GPIO fixed frequency name strings
+ *
+ * @see ::MBG_GPIO_FIXED_FREQS
+ * @see ::MBG_GPIO_FIXED_FREQ_MASKS
*/
#define MBG_GPIO_FIXED_FREQ_STRS \
{ \
- "8kHz", \
- "48kHz", \
- "1MHz", \
- "1544kHz", \
- "2048kHz", \
- "5MHz", \
- "10MHz", \
- "19440kHz" \
+ "8 kHz", \
+ "48 kHz", \
+ "1 MHz", \
+ "1544 kHz", \
+ "2048 kHz", \
+ "5 MHz", \
+ "10 MHz", \
+ "19440 kHz" \
}
/**
* @brief Configuration of a GPIO fixed frequency output
*
- * @see MBG_GPIO_TYPE_FIXED_FREQ_OUT
+ * Used as sub-structure of ::MBG_GPIO_SETTINGS.
+ *
+ * @see ::MBG_GPIO_TYPE_FIXED_FREQ_OUT
+ * @see ::MBG_GPIO_SETTINGS
*/
typedef struct
{
- uint32_t freq_idx; /**< fixed frequency index, @see enum MBG_GPIO_FIXED_FREQ */
- uint32_t shape; /**< signal shape, @see enum MBG_GPIO_SIGNAL_SHAPES */
- uint32_t reserved; /**< currently always 0 */
- uint32_t flags; /**< currently always 0 */
+ uint32_t freq_idx; ///< fixed frequency index, see ::MBG_GPIO_FIXED_FREQS
+ uint32_t shape; ///< selected signal shape, see ::MBG_GPIO_SIGNAL_SHAPES
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t flags; ///< reserved, currently always 0
} MBG_GPIO_FIXED_FREQ_OUT_SETTINGS;
@@ -4047,120 +6033,262 @@ typedef struct
/**
* @brief Supported options for a fixed frequency output
*
- * @see MBG_GPIO_TYPE_FIXED_FREQ_OUT
+ * Used as sub-structure of ::MBG_GPIO_LIMITS.
+ *
+ * @see ::MBG_GPIO_TYPE_FIXED_FREQ_OUT
+ * @see ::MBG_GPIO_LIMITS
*/
typedef struct
{
- uint32_t supp_freq; /**< bit mask of supported fixed frequencies, @see enum MBG_GPIO_FIXED_FREQ */
- uint32_t supp_shapes; /**< bit mask of supported signal shapes, @see enum MBG_GPIO_SIGNAL_SHAPES */
- uint32_t reserved; /**< currently always 0 */
- uint32_t supp_flags; /**< currently always 0 */
+ uint32_t supp_freq; ///< bit mask of supported fixed frequencies, see ::MBG_GPIO_FIXED_FREQ_MASKS
+ uint32_t supp_shapes; ///< bit mask of supported signal shapes, see ::MBG_GPIO_SIGNAL_SHAPE_MASKS
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t supp_flags; ///< reserved, currently always 0
} MBG_GPIO_FIXED_FREQ_OUT_SUPP;
/**
- * @brief Definitions for MBG_GPIO_BITS::format
+ * @brief Enumeration of BITS signal formats
+ *
+ * Used with ::MBG_GPIO_BITS_IN_SETTINGS::format and ::MBG_GPIO_BITS_OUT_SETTINGS::format
+ *
+ * @see ::MBG_GPIO_BITS_FORMAT_MASKS
*/
enum MBG_GPIO_BITS_FORMATS
{
- MBG_GPIO_BITS_E1_FRAMED, /**< 2.048MBit */
- MBG_GPIO_BITS_T1_FRAMED, /**< 1.544MBit */
- MBG_GPIO_BITS_E1_TIMING, /**< 2.048MHz */
- MBG_GPIO_BITS_T1_TIMING, /**< 2.048MHz */
- N_MBG_GPIO_BITS_FORMATS /**< number of formats */
+ MBG_GPIO_BITS_E1_FRAMED, ///< 2.048 MBit
+ MBG_GPIO_BITS_T1_FRAMED, ///< 1.544 MBit
+ MBG_GPIO_BITS_E1_TIMING, ///< 2.048 MHz
+ MBG_GPIO_BITS_T1_TIMING, ///< 2.048 MHz
+ N_MBG_GPIO_BITS_FORMATS ///< number of defined formats
+};
+
+/**
+ * @brief Bit masks associated with ::MBG_GPIO_BITS_FORMATS
+ *
+ * Used with ::MBG_GPIO_BITS_IN_SUPP::supp_fmts and ::MBG_GPIO_BITS_OUT_SUPP::supp_fmts.
+ *
+ * @see ::MBG_GPIO_BITS_FORMATS
+ */
+enum MBG_GPIO_BITS_FORMAT_MASKS
+{
+ MSK_MBG_GPIO_BITS_E1_FRAMED = ( 1UL << MBG_GPIO_BITS_E1_FRAMED ), ///< see ::MBG_GPIO_BITS_E1_FRAMED
+ MSK_MBG_GPIO_BITS_T1_FRAMED = ( 1UL << MBG_GPIO_BITS_T1_FRAMED ), ///< see ::MBG_GPIO_BITS_T1_FRAMED
+ MSK_MBG_GPIO_BITS_E1_TIMING = ( 1UL << MBG_GPIO_BITS_E1_TIMING ), ///< see ::MBG_GPIO_BITS_E1_TIMING
+ MSK_MBG_GPIO_BITS_T1_TIMING = ( 1UL << MBG_GPIO_BITS_T1_TIMING ) ///< see ::MBG_GPIO_BITS_T1_TIMING
+};
+
+
+
+/**
+ * @brief Minimum and maximum known SSM values
+ *
+ * Values according to ITU G.704-1998
+ *
+ * Used with ::MBG_GPIO_BITS_IN_SETTINGS::quality::e1.ssm
+ * and ::MBG_GPIO_BITS_OUT_SETTINGS::ssm.
+ */
+enum GPIO_SSM_VALS
+{
+ GPIO_SSM_UNKNOWN, ///< Quality unknown, existing synchronization network
+ GPIO_SSM_RSVD_1, ///< (reserved)
+ GPIO_SSM_G_811, ///< Rec. G.811
+ GPIO_SSM_RSVD_3, ///< (reserved)
+ GPIO_SSM_SSU_A, ///< SSU-A
+ GPIO_SSM_RSVD_5, ///< (reserved)
+ GPIO_SSM_RSVD_6, ///< (reserved)
+ GPIO_SSM_RSVD_7, ///< (reserved)
+ GPIO_SSM_SSU_B, ///< SSU-B
+ GPIO_SSM_RSVD_9, ///< (reserved)
+ GPIO_SSM_RSVD_10, ///< (reserved)
+ GPIO_SSM_RSVD_SETS, ///< Synchronous Equipment Timing Source (SETS)
+ GPIO_SSM_RSVD_12, ///< (reserved)
+ GPIO_SSM_RSVD_13, ///< (reserved)
+ GPIO_SSM_RSVD_14, ///< (reserved)
+ GPIO_SSM_DONT_USE, ///< don't use
+ N_GPIO_SSM_VALS
};
-#define MSK_MBG_GPIO_BITS_E1_FRAMED ( 1UL << MBG_GPIO_BITS_E1_FRAMED )
-#define MSK_MBG_GPIO_BITS_T1_FRAMED ( 1UL << MBG_GPIO_BITS_T1_FRAMED )
-#define MSK_MBG_GPIO_BITS_E1_TIMING ( 1UL << MBG_GPIO_BITS_E1_TIMING )
-#define MSK_MBG_GPIO_BITS_T1_TIMING ( 1UL << MBG_GPIO_BITS_T1_TIMING )
+/**
+ * @brief Minimum and maximum SA BITS groups
+ *
+ * Used with ::MBG_GPIO_BITS_IN_SETTINGS::quality::e1::sa_bits
+ * and ::MBG_GPIO_BITS_OUT_SETTINGS::sa_bits.
+ */
+enum GPIO_SA_BITS_GROUPS
+{
+ MIN_SA_BITS_GROUP = 4,
+ MAX_SA_BITS_GROUP = 8
+};
+
/**
* @brief Configuration of a GPIO as BITS input module
*
- * @see MBG_GPIO_TYPE_BITS_IN
+ * Used as sub-structure of ::MBG_GPIO_SETTINGS.
+ *
+ * @see ::MBG_GPIO_TYPE_BITS_IN
+ * @see ::MBG_GPIO_SETTINGS
*/
typedef struct
{
- uint32_t format; /**< signal type, enum MBG_GPIO_BITS_FORMATS */
- uint32_t reserved;
- uint32_t csc_limit; /**< max. cycle slip [1/1000 cycle units] */
+ uint32_t format; ///< signal format, see ::MBG_GPIO_BITS_FORMATS
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t csc_limit; ///< max. cycle slip [1/1000 cycle units]
- union
+ union quality
{
- struct
+ struct e1
{
- uint8_t ssm; /**< minimum E1 SSM ( 0...15 ) for acceptance */
- uint8_t sa_bits; /**< Sa Bits group ( 4...8 ) carrying SSM */
- uint16_t reserve;
- } e1; /**< used with E1 formats */
+ uint8_t ssm; ///< minimum E1 SSM for acceptance, 0..::N_GPIO_SSM_VALS-1
+ uint8_t sa_bits; ///< sa bits group carrying SSM, ::MIN_SA_BITS_GROUP..::MAX_SA_BITS_GROUP
+ uint16_t reserved; ///< reserved, currently always 0
+ } e1; ///< used with E1 formats
- struct
+ struct t1
{
uint8_t min_boc;
- uint8_t reserve_0;
- uint16_t reserve_1;
- } t1; /**< used with T1 formats */
+ uint8_t reserved_0; ///< reserved, currently always 0
+ uint16_t reserved_1; ///< reserved, currently always 0
+ } t1; ///< used with T1 formats
- uint32_t u32; /**< dummy to force at least 32 bit alignment */
+ uint32_t u32; ///< dummy to force at least 32 bit alignment
} quality;
- uint32_t err_msk; /**< controls which types of error can be ignored, see enum MBG_GPIO_BITS_ERR */
- uint32_t flags; /**< currently always 0 */
+ uint32_t err_msk; ///< controls which types of error can be ignored, see ::MBG_GPIO_BITS_ERR_MASKS
+ uint32_t flags; ///< reserved, currently always 0
} MBG_GPIO_BITS_IN_SETTINGS;
+
/**
- * @brief Definitions for MBG_GPIO_BITS_IN_SETTINGS::err_msk
+ * @brief Enumeration of BITS input error conditions
*/
-enum MBG_GPIO_BITS_ERR
+enum MBG_GPIO_BITS_ERRS
{
- MBG_GPIO_BITS_ERR_LOS, /**< loss of signal error */
- MBG_GPIO_BITS_ERR_LOF, /**< loss of frame */
- N_MBG_GPIO_BITS_ERR /**< number of formats */
+ MBG_GPIO_BITS_ERR_LOS, ///< loss of signal
+ MBG_GPIO_BITS_ERR_LOF, ///< loss of frame
+ N_MBG_GPIO_BITS_ERRS ///< number of known errors
};
-#define MSK_MBG_GPIO_BITS_ERR_LOS ( 1UL << MBG_GPIO_BITS_ERR_LOS )
-#define MSK_MBG_GPIO_BITS_ERR_LOF ( 1UL << MBG_GPIO_BITS_ERR_LOF )
-
+/**
+ * @brief Bit masks associated with BITS input error conditions
+ *
+ * Used with ::MBG_GPIO_BITS_IN_SETTINGS::err_msk
+ *
+ * @see ::MBG_GPIO_BITS_ERRS
+ */
+enum MBG_GPIO_BITS_ERR_MASKS
+{
+ MSK_MBG_GPIO_BITS_ERR_LOS = ( 1UL << MBG_GPIO_BITS_ERR_LOS ), ///< see ::MBG_GPIO_BITS_ERR_LOS
+ MSK_MBG_GPIO_BITS_ERR_LOF = ( 1UL << MBG_GPIO_BITS_ERR_LOF ) ///< see ::MBG_GPIO_BITS_ERR_LOF
+};
/**
* @brief Supported options of a BITS GPIO input
*
- * @see MBG_GPIO_TYPE_BITS_IN
+ * Used as sub-structure of ::MBG_GPIO_LIMITS.
+ *
+ * @see ::MBG_GPIO_TYPE_BITS_IN
+ * @see ::MBG_GPIO_LIMITS
*/
typedef struct
{
- uint32_t supp_fmts; /**< bit mask of supported formats, @see enum MBG_GPIO_BITS_FORMATS */
- uint32_t reserved; /**< currently always 0 */
+ uint32_t supp_fmts; ///< bit mask of supported formats, see ::MBG_GPIO_BITS_FORMAT_MASKS
+ uint32_t reserved; ///< reserved, currently always 0
} MBG_GPIO_BITS_IN_SUPP;
/**
- * @brief A generic structure used to configure a GPIO port
+ * @brief Configuration of a GPIO as BITS output module
+ *
+ * Used as sub-structure of ::MBG_GPIO_SETTINGS.
+ *
+ * @see ::MBG_GPIO_TYPE_BITS_OUT
+ * @see ::MBG_GPIO_SETTINGS
*/
typedef struct
{
- uint32_t type; /**< GPIO type, @see enum MBG_GPIO_TYPES */
- uint32_t reserved; /**< currently always 0 */
- uint32_t flags; /**< currently always 0 */
+ uint32_t format; ///< signal format, see ::MBG_GPIO_BITS_FORMATS
+ uint32_t flags; ///< flags for encoder control etc., see ::MBG_GPIO_BITS_OUT_FLAG_MASKS
+ uint8_t sa_bits; ///< number of SA bit group for E1 SSM, ::MIN_SA_BITS_GROUP..::MAX_SA_BITS_GROUP
+ uint8_t ssm; ///< ssm for E1 mode, 0..::N_GPIO_SSM_VALS-1
+ uint8_t boc; ///< boc for T1 mode, 0..0x1F //##++++++++++++++
+ uint8_t reserved_0; ///< reserved, currently always 0
+ uint32_t reserved_1; ///< reserved, currently always 0
+ uint32_t reserved_2; ///< reserved, currently always 0
+ uint32_t reserved_3; ///< reserved, currently always 0
+
+} MBG_GPIO_BITS_OUT_SETTINGS;
+
+
+/**
+ * @brief Enumeration of flags used with BITS type GPIO outputs
+ */
+enum MBG_GPIO_BITS_OUT_FLAGS
+{
+ MBG_GPIO_BITS_OUT_FLAG_HDB3, ///< enable HDB3 encoding (E1 mode only)
+ MBG_GPIO_BITS_OUT_FLAG_B8ZS, ///< enable B8ZS encoding (T1 mode only)
+ N_MBG_GPIO_BITS_OUT_FLAGS ///< number of known flags
+};
+
+/**
+ * @brief Bit masks associated with ::MBG_GPIO_BITS_OUT_FLAGS
+ *
+ * Used with ::MBG_GPIO_BITS_OUT_SETTINGS::flags
+ *
+ * @see ::MBG_GPIO_BITS_OUT_FLAGS
+ */
+enum MBG_GPIO_BITS_OUT_FLAG_MASKS
+{
+ MSK_MBG_GPIO_BITS_OUT_FLAG_HDB3 = ( 1UL << MBG_GPIO_BITS_OUT_FLAG_HDB3 ), ///< see ::MBG_GPIO_BITS_OUT_FLAG_HDB3
+ MSK_MBG_GPIO_BITS_OUT_FLAG_B8ZS = ( 1UL << MBG_GPIO_BITS_OUT_FLAG_B8ZS ) ///< see ::MBG_GPIO_BITS_OUT_FLAG_B8ZS
+};
+
- union /**< settings depending on the GPIO ::type, @see enum MBG_GPIO_TYPES */
+/**
+ * @brief Supported options of a BITS type GPIO output
+ *
+ * Used as sub-structure of ::MBG_GPIO_LIMITS.
+ *
+ * @see ::MBG_GPIO_TYPE_BITS_OUT
+ * @see ::MBG_GPIO_LIMITS
+ */
+typedef struct
+{
+ uint32_t supp_fmts; ///< bit mask of supported formats, see ::MBG_GPIO_BITS_FORMAT_MASKS
+ uint32_t reserved; ///< reserved, currently always 0
+
+} MBG_GPIO_BITS_OUT_SUPP;
+
+
+
+/**
+ * @brief A generic structure used to hold a GPIO port's settings
+ */
+typedef struct
+{
+ uint32_t type; ///< GPIO type, see ::MBG_GPIO_TYPES
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t flags; ///< reserved, currently always 0
+
+ /// settings depending on the GPIO type, see ::MBG_GPIO_TYPES
+ union
{
- MBG_GPIO_FREQ_IN_SETTINGS freq_in; /** if ::type is MBG_GPIO_TYPE_FREQ_IN */
- MBG_GPIO_FREQ_OUT_SETTINGS freq_out; /** if ::type is MBG_GPIO_TYPE_FREQ_OUT */
- MBG_GPIO_FIXED_FREQ_OUT_SETTINGS ff_out; /** if ::type is MBG_GPIO_TYPE_FIXED_FREQ_OUT */
- MBG_GPIO_BITS_IN_SETTINGS bits_in; /** if ::type is MBG_GPIO_TYPE_BITS_IN */
- // MBG_GPIO_BITS_OUT_SETTINGS bits_out; /** if ::type is MBG_GPIO_TYPE_BITS_OUT */
+ MBG_GPIO_FREQ_IN_SETTINGS freq_in; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FREQ_IN
+ MBG_GPIO_FREQ_OUT_SETTINGS freq_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FREQ_OUT
+ MBG_GPIO_FIXED_FREQ_OUT_SETTINGS ff_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FIXED_FREQ_OUT
+ MBG_GPIO_BITS_IN_SETTINGS bits_in; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_BITS_IN
+ MBG_GPIO_BITS_OUT_SETTINGS bits_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_BITS_OUT
} u;
} MBG_GPIO_SETTINGS;
@@ -4168,21 +6296,34 @@ typedef struct
/**
- * @brief A generic structure used to describe a GPIO ports limiting values
+ * @brief A GPIO port's current settings, plus port index
+ */
+typedef struct
+{
+ uint32_t idx; ///< port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1
+ MBG_GPIO_SETTINGS settings; ///< current settings
+
+} MBG_GPIO_SETTINGS_IDX;
+
+
+
+/**
+ * @brief A generic structure used to specify a GPIO port's limits
*/
typedef struct
{
- uint32_t type; /**< GPIO type, @see enum MBG_GPIO_TYPES */
- uint32_t reserved; /**< currently always 0 */
- uint32_t supp_flags; /**< supported flags */
+ uint32_t type; ///< GPIO type, see ::MBG_GPIO_TYPES
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t supp_flags; ///< supported flags //##++++++++++++ which?
- union /**< limits depending on the GPIO ::type, @see enum MBG_GPIO_TYPES */
+ /// limits depending on the GPIO type, see ::MBG_GPIO_TYPES
+ union
{
- MBG_GPIO_FREQ_IN_SUPP freq_in; /** if ::type is MBG_GPIO_TYPE_FREQ_IN */
- MBG_GPIO_FREQ_OUT_SUPP freq_out; /** if ::type is MBG_GPIO_TYPE_FREQ_OUT */
- MBG_GPIO_FIXED_FREQ_OUT_SUPP ff_out; /** if ::type is MBG_GPIO_TYPE_FIXED_FREQ_OUT */
- MBG_GPIO_BITS_IN_SUPP bits_in; /** if ::type is MBG_GPIO_TYPE_BITS_IN */
- // MBG_GPIO_BITS_OUT_SUPP bits_out; /** if ::type is MBG_GPIO_TYPE_BITS_OUT */
+ MBG_GPIO_FREQ_IN_SUPP freq_in; ///< if type is ::MBG_GPIO_TYPE_FREQ_IN
+ MBG_GPIO_FREQ_OUT_SUPP freq_out; ///< if type is ::MBG_GPIO_TYPE_FREQ_OUT
+ MBG_GPIO_FIXED_FREQ_OUT_SUPP ff_out; ///< if type is ::MBG_GPIO_TYPE_FIXED_FREQ_OUT
+ MBG_GPIO_BITS_IN_SUPP bits_in; ///< if type is ::MBG_GPIO_TYPE_BITS_IN
+ MBG_GPIO_BITS_OUT_SUPP bits_out; ///< if type is ::MBG_GPIO_TYPE_BITS_OUT
} u;
} MBG_GPIO_LIMITS;
@@ -4190,56 +6331,266 @@ typedef struct
/**
- * @brief A structure used to configure a specific GPIO port
+ * @brief A GPIO port's current settings and limits
*/
typedef struct
{
- uint32_t idx; /**< port number, 0..(MBG_GPIO_CFG_LIMITS::num_io - 1) */
- MBG_GPIO_SETTINGS settings; /**< configuration settings */
+ MBG_GPIO_SETTINGS settings; ///< current settings
+ MBG_GPIO_LIMITS limits; ///< limits of this GPIO port
-} MBG_GPIO_SETTINGS_IDX;
+} MBG_GPIO_INFO;
/**
- * @brief A structure used query the current GPIO port settings and capabilities
+ * @brief A GPIO port's current settings and limits, plus port index
*/
typedef struct
{
- MBG_GPIO_SETTINGS settings; /**< current configuration */
- MBG_GPIO_LIMITS limits; /**< supp. and max. values */
+ uint32_t idx; ///< port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1
+ MBG_GPIO_INFO info; ///< limits and current settings of this GPIO port
-} MBG_GPIO_INFO;
+} MBG_GPIO_INFO_IDX;
/**
- * @brief A structure used to query configuration and capabilities of a specific GPIO port
+ * @brief Status information on a single GPIO port
*/
typedef struct
{
- uint32_t idx; /**< port number, 0..(MBG_GPIO_CFG_LIMITS::num_io - 1) */
- MBG_GPIO_INFO info; /**< current settings and capabilities of this GPIO port */
+ uint8_t port_state; ///< see ::MBG_GPIO_PORT_STATES
+ uint8_t reserved_0; ///< reserved, currently unused and always 0
+ uint16_t reserved_1; ///< reserved, currently unused and always 0
+ uint32_t reserved_2; ///< reserved, currently unused and always 0
+ uint32_t reserved_3; ///< reserved, currently unused and always 0
-} MBG_GPIO_INFO_IDX;
+} MBG_GPIO_STATUS;
-/** @} group_gpio */
+/**
+ * @brief Status information on a specific GPIO port
+ */
+typedef struct
+{
+ uint16_t idx; ///< port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1
+ MBG_GPIO_STATUS status; ///< status information
+
+} MBG_GPIO_STATUS_IDX;
+
+
+
+/**
+ * @brief GPIO port states
+ *
+ * Used with ::MBG_GPIO_STATUS::port_state
+ *
+ * @see ::DEFAULT_GPIO_PORT_STATE_NAMES
+ */
+enum MBG_GPIO_PORT_STATES
+{
+ MBG_GPIO_PORT_UNUSED, ///< configured as unused input
+ MBG_GPIO_PORT_OUTPUT_ENBD, ///< configured output signal enabled
+ MBG_GPIO_INPUT_SIG_AVAIL, ///< input signal is available
+ N_MBG_GPIO_PORT_STATES ///< number of known port states
+};
+
+
+
+/**
+ * @brief String initializers for GPIO port state names
+ *
+ * @see ::MBG_GPIO_PORT_STATES
+ */
+#define DEFAULT_GPIO_PORT_STATE_NAMES \
+{ \
+ "unused", \
+ "output enabled", \
+ "input signal available" \
+}
+
+
+/** @} defgroup group_gpio */
+
+
+
+/**
+ * @defgroup group_havequick HaveQuick definitions
+ *
+ * @note This is only supported if the ::GPS_HAS_HAVEQUICK bit is set
+ * in the ::RECEIVER_INFO::features mask.
+ *
+ * @{ */
+
+
+/**
+ * @brief Enumeration of HaveQuick formats
+ *
+ * @see ::HAVEQUICK_SETTINGS::format
+ * @see ::HAVEQUICK_FORMAT_MASKS
+ */
+enum HAVEQUICK_FORMATS
+{
+ HQ_FMT_STANAG4246_1,
+ HQ_FMT_STANAG4246_2,
+ HQ_FMT_STANAG4246_PTTI,
+ HQ_FMT_STANAG4372_SATURN_1,
+ HQ_FMT_STANAG4372_SATURN_2,
+ HQ_FMT_STANAG4430_EXTD,
+ N_HQ_FMT ///< number of known formats
+};
+
+
+/**
+ * @brief Bit masks associated with the enumerated HaveQuick formats
+ *
+ * @see ::HAVEQUICK_INFO::supp_formats
+ * @see ::HAVEQUICK_FORMATS
+ */
+enum HAVEQUICK_FORMAT_MASKS
+{
+ HQ_MSK_STANAG4246_1 = ( 1UL << HQ_FMT_STANAG4246_1 ), ///< see ::HQ_FMT_STANAG4246_1
+ HQ_MSK_STANAG4246_2 = ( 1UL << HQ_FMT_STANAG4246_2 ), ///< see ::HQ_FMT_STANAG4246_2
+ HQ_MSK_STANAG4246_PTTI = ( 1UL << HQ_FMT_STANAG4246_PTTI ), ///< see ::HQ_FMT_STANAG4246_PTTI
+ HQ_MSK_STANAG4372_SATURN_1 = ( 1UL << HQ_FMT_STANAG4372_SATURN_1 ), ///< see ::HQ_FMT_STANAG4372_SATURN_1
+ HQ_MSK_STANAG4372_SATURN_2 = ( 1UL << HQ_FMT_STANAG4372_SATURN_2 ), ///< see ::HQ_FMT_STANAG4372_SATURN_2
+ HQ_MSK_STANAG4430_EXTD = ( 1UL << HQ_FMT_STANAG4430_EXTD ) ///< see ::HQ_FMT_STANAG4430_EXTD
+};
+
+/*
+ * String initializers for each Havequick format
+ */
+#define HQ_FMT_NAME_STANAG4246_1 "STANAG4246 1"
+#define HQ_FMT_NAME_STANAG4246_2 "STANAG4246 2"
+#define HQ_FMT_NAME_STANAG4246_PTTI "STANAG4246 PTTI"
+#define HQ_FMT_NAME_STANAG4372_SATURN_1 "STANAG4372 SATURN 1"
+#define HQ_FMT_NAME_STANAG4372_SATURN_2 "STANAG4372 SATURN 2"
+#define HQ_FMT_NAME_STANAG4430_EXTD "STANAG4430 EXTD"
+
+#define HQ_FMT_SHRT_NAME_STANAG4246_1 "STG4246 1"
+#define HQ_FMT_SHRT_NAME_STANAG4246_2 "STG4246 2"
+#define HQ_FMT_SHRT_NAME_STANAG4246_PTTI "STG4246 PTTI"
+#define HQ_FMT_SHRT_NAME_STANAG4372_SATURN_1 "STG4372 SATURN1"
+#define HQ_FMT_SHRT_NAME_STANAG4372_SATURN_2 "STG4372 SATURN2"
+#define HQ_FMT_SHRT_NAME_STANAG4430_EXTD "STG4430 EXTD"
+
+/*
+ * The definition below can be used to initialize
+ * an array of ::N_HQ_FMT name strings.
+ */
+#define DEFAULT_HQ_FMT_NAMES \
+{ \
+ HQ_FMT_NAME_STANAG4246_1, \
+ HQ_FMT_NAME_STANAG4246_2, \
+ HQ_FMT_NAME_STANAG4246_PTTI, \
+ HQ_FMT_NAME_STANAG4372_SATURN_1, \
+ HQ_FMT_NAME_STANAG4372_SATURN_2, \
+ HQ_FMT_NAME_STANAG4430_EXTD \
+}
+
+#define DEFAULT_HQ_SHRT_FMT_NAMES \
+{ \
+ HQ_FMT_SHRT_NAME_STANAG4246_1, \
+ HQ_FMT_SHRT_NAME_STANAG4246_2, \
+ HQ_FMT_SHRT_NAME_STANAG4246_PTTI, \
+ HQ_FMT_SHRT_NAME_STANAG4372_SATURN_1, \
+ HQ_FMT_SHRT_NAME_STANAG4372_SATURN_2, \
+ HQ_FMT_SHRT_NAME_STANAG4430_EXTD \
+}
+
+
+
+/**
+ * @brief Configuration settings for a HaveQuick input or output
+ */
+typedef struct
+{
+ uint16_t format; ///< see ::HAVEQUICK_FORMATS
+ uint16_t flags; ///< see ::HAVEQUICK_FLAG_MASKS
+ int32_t offset; ///< Tx: unused, Rx: offset of incoming time in [s]
+ uint32_t reserved_0; ///< reserved, currently always 0
+ uint32_t reserved_1; ///< reserved, currently always 0
+
+} HAVEQUICK_SETTINGS;
+
+#define _mbg_swab_havequick_settings( _p ) \
+{ \
+ _mbg_swab16( &(_p)->format ); \
+ _mbg_swab16( &(_p)->flags ); \
+ _mbg_swab32( &(_p)->offset ); \
+ _mbg_swab32( &(_p)->reserved_0 ); \
+ _mbg_swab32( &(_p)->reserved_1 ); \
+}
+
+/**
+ * @brief Current settings and capabilities of a HaveQuick input or output
+ */
+typedef struct
+{
+ HAVEQUICK_SETTINGS settings; ///< current settings
+ uint32_t supp_formats; ///< see ::HAVEQUICK_FORMAT_MASKS
+ uint16_t supp_flags; ///< mask of flags supported in settings, see ::HAVEQUICK_FLAG_MASKS
+ uint16_t reserved; ///< reserved, currently always 0
+
+} HAVEQUICK_INFO;
+
+#define _mbg_swab_havequick_info( _p ) \
+{ \
+ _mbg_swab_havequick_settings( &(_p)->settings ); \
+ _mbg_swab32( &(_p)->supp_formats ); \
+ _mbg_swab16( &(_p)->supp_flags ); \
+ _mbg_swab16( &(_p)->reserved ); \
+}
+
+
+/**
+ * @brief Known HaveQuick control flags
+ *
+ * @see ::HAVEQUICK_FLAG_MASKS
+ */
+enum HAVEQUICK_FLAG_BITS
+{
+ HQ_FLAG_TX_GEN_LOCAL_TIME,
+ HQ_FLAG_SIGNAL_INVERTED,
+ HQ_FLAG_USE_EXT_PPS,
+ N_HQ_FLAG_BITS
+};
+
+
+/**
+ * @brief Bit masks associated with HaveQuick control flags
+ *
+ * @see ::HAVEQUICK_SETTINGS::flags
+ * @see ::HAVEQUICK_INFO::supp_flags
+ * @see ::HAVEQUICK_FLAG_BITS
+ */
+enum HAVEQUICK_FLAG_MASKS
+{
+ HQ_MSK_TX_GEN_LOCAL_TIME = ( 1UL << HQ_FLAG_TX_GEN_LOCAL_TIME ), ///< see ::HQ_FLAG_TX_GEN_LOCAL_TIME
+ HQ_MSK_SIGNAL_INVERTED = ( 1UL << HQ_FLAG_SIGNAL_INVERTED ), ///< see ::HQ_FLAG_SIGNAL_INVERTED
+ HQ_MSK_USE_EXT_PPS = ( 1UL << HQ_FLAG_USE_EXT_PPS ) ///< see ::HQ_FLAG_USE_EXT_PPS
+};
+
+/** @} defgroup group_havequick */
+
/**
* @defgroup group_evt_log Event logging support
*
- * @note This is only available if GPS_HAS_EVT_LOG is set in RECEIVER_INFO::features.
+ * @note This is only available if ::GPS_HAS_EVT_LOG is set in ::RECEIVER_INFO::features.
*
* @{ */
-/** @brief Number of event log entries that can be stored and yet have been saved */
+/**
+ * @brief Number of event log entries that can be stored and yet have been saved
+ */
typedef struct
{
- uint32_t used; /**< current number of saved log entries */
- uint32_t max; /**< max number of log entries which can be saved */
+ uint32_t used; ///< current number of saved log entries
+ uint32_t max; ///< max number of log entries which can be saved
+
} MBG_NUM_EVT_LOG_ENTRIES;
#define _mbg_swab_mbg_num_evt_log_entries( _p ) \
@@ -4255,13 +6606,16 @@ typedef uint16_t MBG_EVT_CODE;
typedef uint16_t MBG_EVT_INFO;
#define _mbg_swab_evt_info( _p ) _mbg_swab16( _p );
-/** @brief An event log entry */
- typedef struct
- {
- uint32_t time; /**< like time_t, seconds since 1970 */
- MBG_EVT_CODE code; /**< event ID or'ed with severity level */
- MBG_EVT_INFO info; /**< optional event info, depending on event ID */
- } MBG_EVT_LOG_ENTRY;
+/**
+ * @brief An event log entry
+ */
+typedef struct
+{
+ uint32_t time; ///< like time_t, seconds since 1970
+ MBG_EVT_CODE code; ///< event ID or'ed with severity level, see @ref MBG_EVENT_CODES
+ MBG_EVT_INFO info; ///< optional event info, depending on event ID
+
+} MBG_EVT_LOG_ENTRY;
#define _mbg_swab_mbg_evt_log_entry( _p ) \
{ \
@@ -4271,9 +6625,9 @@ typedef uint16_t MBG_EVT_INFO;
}
-// MBG_EVT_LOG_ENTRY::code is a combination of some bits used for the ID,
+// ::MBG_EVT_LOG_ENTRY::code is a combination of some bits used for the ID,
// plus some bits used for the severity/level. The sum of bits must not
-// exceed (8 * sizeof MBG_EVT_LOG_ENTRY::code):
+// exceed (8 * sizeof ::MBG_EVT_LOG_ENTRY::code):
#define MBG_EVT_ID_BITS 13
#define MBG_EVT_LVL_BITS 3
@@ -4296,19 +6650,25 @@ typedef uint16_t MBG_EVT_INFO;
( ( (_code) >> MBG_EVT_ID_BITS ) & MBG_EVT_LVL_MASK )
-/** @brief Enumeration of event IDs */
-enum
-{
- MBG_EVT_ID_NONE, /**< no event (empty entry) */
- MBG_EVT_ID_POW_UP_RES, /**< power up reset */
- MBG_EVT_ID_WDOG_RES, /**< watchdog reset */
- MBG_EVT_ID_COLD_BOOT, /**< entering cold boot mode */
- MBG_EVT_ID_WARM_BOOT, /**< entering warm boot mode */
- MBG_EVT_ID_NORMAL_OP, /**< entering normal operation */
- MBG_EVT_ID_ANT_DISCONN, /**< antenna disconnect detected */
- MBG_EVT_ID_ANT_SHORT, /**< antenna short circuit detected */
- MBG_EVT_ID_ANT_OK, /**< antenna OK after failure */
- MBG_EVT_ID_LOW_SATS, /**< no satellites can be received though antenna not failing */
+/**
+ * @brief Enumeration of event IDs
+ *
+ * @see @ref MBG_EVENT_CODES
+ * @see @ref MBG_EVT_ID_BITS
+ * @see @ref MBG_EVT_LVL_BITS
+ */
+enum MBG_EVT_IDS
+{
+ MBG_EVT_ID_NONE, ///< no event (empty entry)
+ MBG_EVT_ID_POW_UP_RES, ///< power up reset
+ MBG_EVT_ID_WDOG_RES, ///< watchdog reset
+ MBG_EVT_ID_COLD_BOOT, ///< entering cold boot mode
+ MBG_EVT_ID_WARM_BOOT, ///< entering warm boot mode
+ MBG_EVT_ID_NORMAL_OP, ///< entering normal operation
+ MBG_EVT_ID_ANT_DISCONN, ///< antenna disconnect detected
+ MBG_EVT_ID_ANT_SHORT, ///< antenna short circuit detected
+ MBG_EVT_ID_ANT_OK, ///< antenna OK after failure
+ MBG_EVT_ID_LOW_SATS, ///< no satellites can be received though antenna not failing
N_MBG_EVT_ID
};
@@ -4341,8 +6701,14 @@ enum
-/** @brief Enumeration of event severity levels */
-enum
+/**
+ * @brief Enumeration of event severity levels
+ *
+ * @see @ref MBG_EVENT_CODES
+ * @see @ref MBG_EVT_ID_BITS
+ * @see @ref MBG_EVT_LVL_BITS
+ */
+enum MBG_EVT_LVLS
{
MBG_EVT_LVL_NONE,
MBG_EVT_LVL_DEBUG,
@@ -4373,7 +6739,13 @@ enum
}
-/** @brief Predefined event codes with associated severity levels */
+/**
+ * @brief Predefined event codes with associated severity levels
+ *
+ * @see ::MBG_EVT_IDS
+ * @see ::MBG_EVT_LVLS
+ *
+ * @anchor MBG_EVENT_CODES @{ */
#define MBG_EVT_NONE _mbg_mk_evt_code( MBG_EVT_ID_NONE, MBG_EVT_LVL_NONE )
#define MBG_EVT_POW_UP_RES _mbg_mk_evt_code( MBG_EVT_ID_POW_UP_RES, MBG_EVT_LVL_WARN )
@@ -4386,8 +6758,109 @@ enum
#define MBG_EVT_ANT_OK _mbg_mk_evt_code( MBG_EVT_ID_ANT_OK, MBG_EVT_LVL_INFO )
#define MBG_EVT_LOW_SATS _mbg_mk_evt_code( MBG_EVT_ID_LOW_SATS, MBG_EVT_LVL_WARN )
+/** @} anchor MBG_EVENT_CODES */
+
+/** @} defgroup group_evt_log */
+
+
+
+/**
+ * @defgroup group_ims IMS support
+ *
+ * @note This is only supported if ::GPS_HAS_IMS is set in ::RECEIVER_INFO::features.
+ *
+ * @{ */
+
+/**
+ * @brief Generic state of an IMS device
+ */
+typedef struct
+{
+ uint8_t chassis_id; ///< chassis ID, 0 if installed on the backplane
+ uint8_t slot_id; ///< slot number on the chassis
+ uint16_t num_sensors; ///< number of sensors provided by the device
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t flags; ///< unused, currently always 0
+
+} MBG_IMS_STATE;
+
+#define _mbg_swab_mbg_ims_state( _p ) \
+{ \
+ _mbg_swab16( &(_p)->num_sensors ); \
+ _mbg_swab32( &(_p)->reserved ); \
+ _mbg_swab32( &(_p)->flags ); \
+}
+
+
+
+/**
+ * @brief Generic state of an IMS sensor
+ */
+typedef struct
+{
+ uint16_t type; ///< sensor type, see ::MBG_IMS_SENSORS
+ uint16_t idx; ///< index of the sensor of this type
+ int32_t val; ///< sensor value, in units according to the type
+ int16_t exp; ///< 10s exponent of the sensor value
+ uint16_t reserved; ///< currently unused, always 0
+ uint32_t flags; ///< currently unused, always 0
+
+} MBG_IMS_SENSOR_STATE;
+
+#define _mbg_swab_mbg_ims_sensor_state( _p ) \
+{ \
+ _mbg_swab16( &(_p)->type ); \
+ _mbg_swab16( &(_p)->idx ); \
+ _mbg_swab32( &(_p)->val ); \
+ _mbg_swab16( &(_p)->exp ); \
+ _mbg_swab16( &(_p)->reserved ); \
+ _mbg_swab32( &(_p)->flags ); \
+}
+
+
+/**
+ * @brief Generic state of an IMS sensor, with sensor index
+ */
+typedef struct
+{
+ uint32_t idx; ///< sensor index, 0..::MBG_IMS_STATE::num_sensors-1
+ MBG_IMS_SENSOR_STATE state; ///< sensor state
+
+} MBG_IMS_SENSOR_STATE_IDX;
+
+#define _mbg_swab_mbg_ims_sensor_state_idx( _p ) \
+{ \
+ _mbg_swab32( &(_p)->idx ); \
+ _mbg_swab_mbg_ims_sensor_state( &(_p)->state ); \
+}
+
+
+
+/**
+ * @brief IMS sensor types
+ */
+enum MBG_IMS_SENSORS
+{
+ MBG_IMS_SENSOR_TEMP_C, ///< temperature in degrees Celsius
+ MBG_IMS_SENSOR_VOLTAGE, ///< voltage in val/exp, output state in flags
+ MBG_IMS_SENSOR_PLL, ///< control voltage in val/exp, lock state in flags
+ N_MBG_IMS_SENSORS ///< number of supported sensor types
+};
+
+
+
+// Definitions used with ::MBG_IMS_SENSOR_STATE::flags:
+
+// if ::MBG_IMS_SENSOR_STATE::type == ::MBG_IMS_SENSOR_VOLTAGE
+#define MBG_IMS_SENSOR_VOLTAGE_OUT_ENB 0x01 // output is enabled
+#define MBG_IMS_SENSOR_VOLTAGE_OUT_OVR 0x02 // output overload
+
+// if ::MBG_IMS_SENSOR_STATE::type == ::MBG_IMS_SENSOR_PLL
+#define MBG_IMS_SENSOR_PLL_LOCKED 0x01
+
+
+/** @} defgroup group_ims */
-/** @} group_evt_log */
/**
@@ -4400,9 +6873,9 @@ enum
* _pcps_has_generic_io() or the corresponding function
* mbg_dev_has_generic_io() should be used by applications to
* check whether a particular bus-level device supports this.
+ *
* @{ */
-
typedef uint16_t GEN_IO_INFO_TYPE;
#define _mbg_swab_gen_io_info_type( _p ) \
@@ -4411,16 +6884,14 @@ typedef uint16_t GEN_IO_INFO_TYPE;
/**
- * @brief The data structure used with the PCPS_GEN_IO_GET_INFO command
+ * @brief The data structure used with the ::PCPS_GEN_IO_GET_INFO command
*
- * type specifier in order to query from a device which of the other
- * specified types is supported, and how many data sets are being
- * used by the device. The GEN_IO_INFO_TYPE must be passed to the
- * call which returns a GEN_IO_INFO structure filled by the device.
+ * Used to determine how many data sets of a specific type are supported
+ * by the device.
*/
typedef struct
{
- GEN_IO_INFO_TYPE type; // a PCPS_GEN_IO_GET_INFO type from the enum above
+ GEN_IO_INFO_TYPE type; // see ::PCPS_GEN_IO_TYPES
uint16_t num; // supported number of data sets of the specified type
} GEN_IO_INFO;
@@ -4434,35 +6905,30 @@ typedef struct
/**
- * @brief Data types used with GEN_IO_INFO::type
+ * @brief Data types used with ::GEN_IO_INFO::type
*
- * The first type specifier, PCPS_GEN_IO_GET_INFO, can
+ * The first type specifier, ::PCPS_GEN_IO_GET_INFO, can
* be used to find out which of the other data types are
* supported, and how many data sets of the specified type
* are supported by a device.
*/
-enum
+enum PCPS_GEN_IO_TYPES
{
- PCPS_GEN_IO_GET_INFO, /**< GEN_IO_INFO (read only) */
- PCPS_GEN_IO_CAL_REC_IRIG_RX_COMP, /**< CAL_REC_IRIG_RX_COMP (read/write) */
- N_PCPS_GEN_IO_TYPE /**< number of known types */
+ PCPS_GEN_IO_GET_INFO, ///< ::GEN_IO_INFO (read only)
+ PCPS_GEN_IO_CAL_REC_IRIG_RX_COMP, ///< ::CAL_REC_IRIG_RX_COMP (read/write)
+ N_PCPS_GEN_IO_TYPE ///< number of known types
};
-/** @} group_generic_io */
+/** @} defgroup group_generic_io */
-/*------------------------------------------------------------------------*/
-
-/*
- * The types below are not used with all devices:
- */
typedef uint16_t ROM_CSUM; /* The ROM checksum */
-typedef uint16_t RCV_TIMEOUT; /* [min] (only if HAS_RCV_TIMEOUT) */
-typedef uint16_t IGNORE_LOCK; /* (only if GPS_HAS_IGNORE_LOCK) */
+typedef uint16_t RCV_TIMEOUT; /* [min] (only if ::HAS_RCV_TIMEOUT) */
+typedef uint16_t IGNORE_LOCK; /* (only if ::GPS_HAS_IGNORE_LOCK) */
/*
- * Originally IGNORE_LOG above has been a boolean value (equal or
+ * Originally ::IGNORE_LOG above has been a boolean value (equal or
* not equal 0) which was evaluated the same way for all ports.
*
* Due to special firmware requirements it has been changed to a
@@ -4491,86 +6957,124 @@ typedef uint16_t IGNORE_LOCK; /* (only if GPS_HAS_IGNORE_LOCK) */
( (_il) & ( _ignore_lock_for_port(_n) | IGNORE_LOCK_FOR_ALL_PORTS ) )
-/*------------------------------------------------------------------------*/
-/*
+/**
+ * @defgroup group_scu Definitions used with SCU devices
+ *
* The structures below are used with the SCU multiplexer board
- * in a redundant system:
- */
+ * in a redundant system.
+ *
+ * @see ::GPS_MODEL_IS_SCU
+ *
+ * @{ */
typedef struct
{
- uint32_t hw_id; // hardware identification
- uint32_t fw_id; // firmware identification
- uint16_t flags; // reserved currently 0
- uint8_t clk0_info; // reference clock 0 type
- uint8_t clk1_info; // reference clock 1 type
- uint16_t epld_status; // epld status word, see defintions below
- uint16_t epld_control; // epld control word, see defintions below
+ uint32_t hw_id; ///< hardware identification
+ uint32_t fw_id; ///< firmware identification
+ uint16_t flags; ///< reserved currently 0
+ uint8_t clk0_info; ///< reference clock 0 type
+ uint8_t clk1_info; ///< reference clock 1 type
+ uint16_t epld_status; ///< EPLD status word, see ::SCU_STAT_MASKS
+ uint16_t epld_control; ///< EPLD control word, see ::SCU_CTRL_MASKS
+
} SCU_STAT_INFO;
+
typedef struct
{
- uint16_t epld_control_mask; // control mask, determines which bit is to be changed
- uint16_t epld_control_value; // control value, determines value of bits to be changed
- uint32_t flags; // reserved, currently 0
+ uint16_t epld_control_mask; ///< control mask, determines which bit is to be changed, see ::SCU_CTRL_MASKS
+ uint16_t epld_control_value; ///< control value, determines value of bits to be changed, see ::SCU_CTRL_MASKS
+ uint32_t flags; ///< reserved, currently 0
+
} SCU_STAT_SETTINGS;
-// definitions for status word bit masks
-#define MSK_EPLD_STAT_TS1 0x0001 // state of time sync signal clk_1
-#define MSK_EPLD_STAT_TS2 0x0002 // state of time sync signal clk_2
-#define MSK_EPLD_STAT_TL_ERROR 0x0004 // state of time limit error input
-#define MSK_EPLD_STAT_PSU1_OK 0x0008 // state of power supply 1 monitoring input
-#define MSK_EPLD_STAT_PSU2_OK 0x0010 // state of power supply 2 monitoring input
-#define MSK_EPLD_STAT_AUTO 0x0020 // AUTOMATIC/REMOTE or MANUAL Mode
-#define MSK_EPLD_STAT_SEL 0x0040 // select bit for output MUX, ( clk_1 = 0 )
-#define MSK_EPLD_STAT_ENA 0x0080 // enable Bit for output MUX, set if enabled
-#define MSK_EPLD_STAT_ACO 0x4000 // Access control override bit
-#define MSK_EPLD_STAT_WDOG_OK 0x8000 // WDT_OK set to zero if watchdog expired
+/**
+ * @brief Bit masks used to check the SCU EPLD status
+ *
+ * Used with ::SCU_STAT_INFO::epld_status
+ */
+enum SCU_STAT_MASKS
+{
+ MSK_EPLD_STAT_TS1 = 0x0001, ///< state of time sync signal clk_1
+ MSK_EPLD_STAT_TS2 = 0x0002, ///< state of time sync signal clk_2
+ MSK_EPLD_STAT_TL_ERROR = 0x0004, ///< state of time limit error input
+ MSK_EPLD_STAT_PSU1_OK = 0x0008, ///< state of power supply 1 monitoring input
+ MSK_EPLD_STAT_PSU2_OK = 0x0010, ///< state of power supply 2 monitoring input
+ MSK_EPLD_STAT_AUTO = 0x0020, ///< AUTOMATIC/REMOTE or MANUAL Mode
+ MSK_EPLD_STAT_SEL = 0x0040, ///< select bit for output MUX, ( clk_1 = 0 )
+ MSK_EPLD_STAT_ENA = 0x0080, ///< enable Bit for output MUX, set if enabled
-#define MSK_EPLD_CNTL_SEL_REM 0x0800 // remote select for output MUX ( clk_1 = 0 )
-#define MSK_EPLD_CNTL_DIS_REM 0x1000 // remote disable for output MUX
-#define MSK_EPLD_CNTL_REMOTE 0x2000 // must be set to enable remote operation
-#define MSK_EPLD_CNTL_SEL_SNMP 0x4000 // connect COM0 channels to XPORT
-#define MSK_EPLD_CNTL_ENA_SNMP 0x8000 // select clk for comm. ( clk1 = 0 )
+ MSK_EPLD_STAT_ACO = 0x4000, ///< Access control override bit
+ MSK_EPLD_STAT_WDOG_OK = 0x8000 ///< WDT_OK set to zero if watchdog expired
+};
-/*
- * Definitions for clk0_info and clk1_info, can be used to determine
- * the reference clock type connected to SCU input channel 0 and 1:
+
+/**
+ * @brief Bit masks used to control the SCU EPLD
+ *
+ * Used with ::SCU_STAT_INFO::epld_control, ::SCU_STAT_SETTINGS::epld_control_mask,
+ * and ::SCU_STAT_SETTINGS::epld_control_value.
*/
-enum
+enum SCU_CTRL_MASKS
+{
+ MSK_EPLD_CTL_DISB_SERIAL = 0x0001, ///< disable serial output on error
+ MSK_EPLD_CTL_DISB_PPS = 0x0002, ///< disable PPS output on error
+ MSK_EPLD_CTL_DISB_10MHZ = 0x0004, ///< disable 10 MHz output on error
+
+ MSK_EPLD_CNTL_SEL_REM = 0x0800, ///< remote select for output MUX (clk_1 = 0)
+ MSK_EPLD_CNTL_DIS_REM = 0x1000, ///< remote disable for output MUX
+ MSK_EPLD_CNTL_REMOTE = 0x2000, ///< must be set to enable remote operation
+ MSK_EPLD_CNTL_SEL_SNMP = 0x4000, ///< select clk for comm. (clk1 = 0)
+ MSK_EPLD_CNTL_ENA_SNMP = 0x8000, ///< connect COM0 channels to XPORT
+};
+
+
+
+/**
+ * @brief Definitions for ::SCU_STAT_INFO::clk0_info and ::SCU_STAT_INFO::clk1_info
+ *
+ * Can be used to determine the reference clock type connected to the SCU input channels.
+ */
+enum SCU_CLK_INFO_TYPES
{
- SCU_CLK_INFO_GPS, // ref. clock is GPS receiver
- SCU_CLK_INFO_DCF_PZF, // ref. clock is DCF77 PZF receiver
- SCU_CLK_INFO_DCF_AM, // ref. clock is DCF77 AM receiver
- SCU_CLK_INFO_TCR // ref. clock is IRIG time code receiver
+ SCU_CLK_INFO_GPS, ///< ref. clock is GPS receiver
+ SCU_CLK_INFO_DCF_PZF, ///< ref. clock is DCF77 PZF receiver
+ SCU_CLK_INFO_DCF_AM, ///< ref. clock is DCF77 AM receiver
+ SCU_CLK_INFO_TCR, ///< ref. clock is IRIG time code receiver
+ N_SCU_CLK_INFO ///< number of known types
};
+/** @} defgroup group_scu */
+
/*------------------------------------------------------------------------*/
+#define REMOTE 0x10
+#define BOOT 0x20
+
/**
* @brief Satellite receiver modes of operation.
*
- * @note Some of the code combinations are obsolete with recent
+ * @note Some of the code combinations are deprecated with recent
* satellite receivers. However, this doesn't matter since the mode
* is just read from the receiver.
*/
-#define REMOTE 0x10
-#define BOOT 0x20
-
-#define TRACK ( 0x01 )
-#define AUTO_166 ( 0x02 )
-#define WARM_166 ( 0x03 | BOOT )
-#define COLD_166 ( 0x04 | BOOT )
-#define AUTO_BC ( 0x05 | REMOTE )
-#define WARM_BC ( 0x06 | REMOTE | BOOT )
-#define COLD_BC ( 0x07 | REMOTE | BOOT )
-#define UPDA_166 ( 0x08 | BOOT )
-#define UPDA_BC ( 0x09 | REMOTE | BOOT )
+enum RECEIVER_MODES
+{
+ TRACK = ( 0x01 ),
+ AUTO_166 = ( 0x02 ),
+ WARM_166 = ( 0x03 | BOOT ),
+ COLD_166 = ( 0x04 | BOOT ),
+ AUTO_BC = ( 0x05 | REMOTE ),
+ WARM_BC = ( 0x06 | REMOTE | BOOT ),
+ COLD_BC = ( 0x07 | REMOTE | BOOT ),
+ UPDA_166 = ( 0x08 | BOOT ),
+ UPDA_BC = ( 0x09 | REMOTE | BOOT )
+};
@@ -4586,11 +7090,12 @@ typedef int16_t DAC_VAL;
*/
typedef struct
{
- uint16_t mode; /**< Mode of operation, see predefined codes */
- uint16_t good_svs; /**< Numb. of satellites that can currently be received and used */
- uint16_t svs_in_view; /**< Numb. of satellites that should be in view according to the almanac data */
- DAC_VAL dac_val; /**< Oscillator fine DAC value */
- DAC_VAL dac_cal; /**< Oscillator calibration DAC value ( see #OSC_DAC_RANGE, #OSC_DAC_BIAS ) */
+ uint16_t mode; ///< Mode of operation, see ::RECEIVER_MODES
+ uint16_t good_svs; ///< Numb. of satellites that can currently be received and used
+ uint16_t svs_in_view; ///< Numb. of satellites that should be visible above the horizon
+ DAC_VAL dac_val; ///< Oscillator fine DAC value
+ DAC_VAL dac_cal; ///< Oscillator calibration DAC value ( see ::OSC_DAC_RANGE, ::OSC_DAC_BIAS )
+
} STAT_INFO;
#define _mbg_swab_stat_info( _p ) \
@@ -4610,37 +7115,67 @@ typedef struct
/**
* @brief An enumeration of known satellite navigation systems
+ *
+ * @see ::MBG_GNSS_TYPE_MASKS
+ * @see ::GNSS_TYPE_STRS
+ */
+enum MBG_GNSS_TYPES
+{
+ GNSS_TYPE_GPS, ///< GPS, United States
+ GNSS_TYPE_GLONASS, ///< GLONASS, Russia
+ GNSS_TYPE_BEIDOU, ///< BEIDOU, China
+ GNSS_TYPE_GALILEO, ///< GALILEO, Europe
+ GNSS_TYPE_WAAS, ///< WAAS, Wide Area Augmentation System
+ GNSS_TYPE_EGNOS, ///< EGNOS, European Geostationary Navigation Overlay Service
+ N_GNSS_TYPES ///< Number of defined codes
+};
+
+
+/**
+ * @brief Bit masks associated with ::MBG_GNSS_TYPES
+ *
+ * @see ::MBG_GNSS_TYPES
*/
-enum
+enum MBG_GNSS_TYPE_MASKS
{
- GNSS_TYPE_GPS, /**< GPS, United States */
- GNSS_TYPE_GLONASS, /**< GLONASS, Russia */
- GNSS_TYPE_BEIDOU, /**< BEIDOU, China */
- GNSS_TYPE_GALILEO, /**< GALILEO, Europe */
- N_GNSS_TYPES /**< Number of defined codes */
+ MBG_GNSS_TYPE_MSK_GPS = ( 1UL << GNSS_TYPE_GPS ), ///< see ::GNSS_TYPE_GPS
+ MBG_GNSS_TYPE_MSK_GLONASS = ( 1UL << GNSS_TYPE_GLONASS ), ///< see ::GNSS_TYPE_GLONASS
+ MBG_GNSS_TYPE_MSK_BEIDOU = ( 1UL << GNSS_TYPE_BEIDOU ), ///< see ::GNSS_TYPE_BEIDOU
+ MBG_GNSS_TYPE_MSK_GALILEO = ( 1UL << GNSS_TYPE_GALILEO ), ///< see ::GNSS_TYPE_GALILEO
+ MBG_GNSS_TYPE_MSK_WAAS = ( 1UL << GNSS_TYPE_WAAS ), ///< see ::GNSS_TYPE_WAAS
+ MBG_GNSS_TYPE_MSK_EGNOS = ( 1UL << GNSS_TYPE_EGNOS ) ///< see ::GNSS_TYPE_EGNOS
};
+
+/**
+ * @brief Name strings for the the known satellite navigation systems
+ *
+ * @see ::MBG_GNSS_TYPES
+ */
#define GNSS_TYPE_STRS \
{ \
"GPS", \
"GLONASS", \
- "BEIDOU" , \
- "GALILEO" \
+ "BEIDOU", \
+ "GALILEO", \
+ "WAAS", \
+ "EGNOS" \
}
-#define MBG_GNSS_TYPE_MSK_GPS ( 1UL << GNSS_TYPE_GPS )
-#define MBG_GNSS_TYPE_MSK_GLONASS ( 1UL << GNSS_TYPE_GLONASS )
-#define MBG_GNSS_TYPE_MSK_BEIDOU ( 1UL << GNSS_TYPE_BEIDOU )
-#define MBG_GNSS_TYPE_MSK_GALILEO ( 1UL << GNSS_TYPE_GALILEO )
-
#define N_GNSS_MODE_PRIO 8
+/**
+ * @brief GNSS mode settings
+ *
+ * @see ::MBG_GNSS_TYPES
+ */
typedef struct
{
- uint32_t gnss_set; /**< current set of GNSS types */
- uint8_t prio[N_GNSS_MODE_PRIO]; /**< index 0 for highest priority, use GNSS enumeration above, init with 0xFF if not supported */
- uint32_t flags; /**< see below */
+ uint32_t gnss_set; ///< bit mask of currently used GNSS systems, see ::MBG_GNSS_TYPE_MASKS
+ uint8_t prio[N_GNSS_MODE_PRIO]; ///< see ::MBG_GNSS_TYPES, unused fields set to 0xFF, idx 0 is highest prio
+ uint32_t flags; ///< see ::MBG_GNSS_MODE_FLAG_MASKS
+
} MBG_GNSS_MODE_SETTINGS;
#define _mbg_swab_mbg_gnss_mode_settings( _p ) \
@@ -4653,9 +7188,10 @@ typedef struct
typedef struct
{
- MBG_GNSS_MODE_SETTINGS settings; /**< current GNSS mode settings */
- uint32_t supp_gnss_types; /**< bit masks of supported GNSS types */
- uint32_t flags; /**< indicates which of the defined flags are supported by the device */
+ MBG_GNSS_MODE_SETTINGS settings; ///< current GNSS mode settings
+ uint32_t supp_gnss_types; ///< bit masks of supported GNSS types, see ::MBG_GNSS_TYPE_MASKS
+ uint32_t flags; ///< indicates which flags are supported for settings::flags, see ::MBG_GNSS_MODE_FLAG_MASKS
+
} MBG_GNSS_MODE_INFO;
#define _mbg_swab_mbg_gnss_mode_info( _p ) \
@@ -4667,32 +7203,47 @@ typedef struct
/**
- * @brief Flags used with MBG_GNSS_MODE_SETTINGS::flags and MBG_GNSS_MODE_INFO::flags
+ * @brief Flag bits used with ::MBG_GNSS_MODE_SETTINGS and ::MBG_GNSS_MODE_INFO
+ *
+ * @see ::MBG_GNSS_MODE_FLAG_MASKS
*/
-enum
+enum MBG_GNSS_MODE_FLAG_BITS
{
- MBG_GNSS_FLAG_EXCLUSIVE, /**< (read only) only one of the supported GNSS systems can be used at the same time */
- MBG_GNSS_FLAG_HAS_PRIORITY, /**< (read only) priority can be configured using the MBG_GNSS_MODE_SETTINGS::prio field */
+ MBG_GNSS_FLAG_EXCLUSIVE, ///< (read only) only one of the supported GNSS systems can be used at the same time
+ MBG_GNSS_FLAG_HAS_PRIORITY, ///< (read only) priority can be configured using the MBG_GNSS_MODE_SETTINGS::prio field
+ MBG_GNSS_FLAG_SAT_INFO_IDX_SUPP_SER, ///< (read only)
N_MBG_GNSS_FLAGS
};
-#define MBG_GNSS_FLAG_MSK_EXCLUSIVE ( 1UL << MBG_GNSS_FLAG_EXCLUSIVE )
-#define MBG_GNSS_FLAG_MSK_HAS_PRIORITY ( 1UL << MBG_GNSS_FLAG_HAS_PRIORITY )
+
+/**
+ * @brief Flag masks used with MBG_GNSS_MODE_SETTINGS::flags and MBG_GNSS_MODE_INFO::flags
+ *
+ * @see ::MBG_GNSS_MODE_FLAG_BITS
+ */
+enum MBG_GNSS_MODE_FLAG_MASKS
+{
+ MBG_GNSS_FLAG_MSK_EXCLUSIVE = ( 1UL << MBG_GNSS_FLAG_EXCLUSIVE ), ///< see ::MBG_GNSS_FLAG_EXCLUSIVE
+ MBG_GNSS_FLAG_MSK_HAS_PRIORITY = ( 1UL << MBG_GNSS_FLAG_HAS_PRIORITY ), ///< see ::MBG_GNSS_FLAG_HAS_PRIORITY
+ MBG_GNSS_FLAG_MSK_SAT_INFO_IDX_SUPP_SER = ( 1UL << MBG_GNSS_FLAG_SAT_INFO_IDX_SUPP_SER ) ///< see ::MBG_GNSS_FLAG_SAT_INFO_IDX_SUPP_SER
+};
+
-#define MAX_USED_SATS 32
+#define MAX_USED_SATS 32
/**
- * @brief SV information from a certain GNSS type.
+ * @brief Satellite information for a particular GNSS type.
*/
typedef struct
{
- uint8_t gnss_type; /**< GNSS type from the enumeration above */
- uint8_t reserved;
- uint16_t good_svs;
- uint16_t svs_in_view;
- uint8_t svs[MAX_USED_SATS];
+ uint8_t gnss_type; ///< GNSS type as enumerated in ::MBG_GNSS_TYPES
+ uint8_t reserved; ///< Reserved, currently always 0
+ uint16_t good_svs; ///< Num. of satellites that can currently be received and used
+ uint16_t svs_in_view; ///< Num. of satellites that should be visible above the horizon
+ uint8_t svs[MAX_USED_SATS]; ///< IDs of the satellites actually used for navigation, 0 == not used
+
} GNSS_SAT_INFO;
#define _mbg_swab_gnss_sat_info( _p ) \
@@ -4702,6 +7253,28 @@ typedef struct
}
+
+/**
+ * @brief One of several sets of satellite information for a particular GNSS type.
+ *
+ *
+ */
+typedef struct
+{
+ uint16_t idx; ///< GNSS system type index
+ GNSS_SAT_INFO gnss_sat_info; ///< see ::GNSS_SAT_INFO
+
+} GNSS_SAT_INFO_IDX;
+
+#define _mbg_swab_gnss_sat_info_idx( _p ) \
+{ \
+ _mbg_swab16( &(_p)->idx ); \
+ _mbg_swab_gnss_sat_info( &(_p)->gnss_sat_info ); \
+}
+
+
+
+
#ifndef _IDENT_DEFINED
typedef union
@@ -4731,14 +7304,25 @@ typedef uint16_t ANT_CABLE_LEN;
/**
- * @defgroup group_ip4_cfg Simple configuration and status
- * of an optional LAN interface.
+ * @defgroup group_net_cfg Network configuration stuff
*
- * @note This is only supported if the flag GPS_HAS_LAN_IP4 is set
- * in RECEIVER_INFO::features.
+ * @{ */
+
+/**
+ * @defgroup group_net_basic_types Basic network parameter types
*
* @{ */
+/**
+ * @brief The MAC address of a network interface
+ */
+typedef struct
+{
+ uint8_t b[6];
+
+} MBG_MAC_ADDR;
+
+
/**
* @brief An IPv4 address
@@ -4749,54 +7333,78 @@ typedef uint32_t IP4_ADDR;
_mbg_swab32( _p );
+
+/** @brief The number of bits used for an IPv6 address */
+#define IP6_ADDR_BITS 128
+
+/** @brief The number of bytes used for an IPv6 address */
+#define IP6_ADDR_BYTES ( IP6_ADDR_BITS / 8 ) // == 16
+
/**
- * @brief Settings of an IPv4 network interface
+ * @brief An IPv6 address
*/
typedef struct
{
- IP4_ADDR ip_addr; /**< the IP address */
- IP4_ADDR netmask; /**< the network mask */
- IP4_ADDR broad_addr; /**< the broadcast address */
- IP4_ADDR gateway; /**< the default gateway */
- uint16_t flags; /**< flags as specified below */
- uint16_t vlan_cfg; /**< VLAN configuration, see below */
+ uint8_t b[IP6_ADDR_BYTES]; ///< bytes holding the address bits, b[0] == LSBs
-} IP4_SETTINGS;
+} IP6_ADDR;
+
+
+
+/** @brief The max number of chars required for an IPv6 address string */
+#define MAX_IP6_ADDR_STR_LEN 43 ///< e.g. 2001:0db8:85a3:08d3:1319:8a2e:0370:7344/128
+
+/** @brief Buffer size required to store an IPv6 address string */
+#define IP6_ADDR_STR_SIZE ( MAX_IP6_ADDR_STR_LEN + 1 ) ///< ::MAX_IP6_ADDR_STR_LEN + terminating 0
+
+/** @brief A buffer for an IPv6 address string */
+typedef char IP6_ADDR_STR[IP6_ADDR_STR_SIZE];
+
+
+/**
+ * @brief A host's fully qualified domain name (FQDN), or a numeric IP address string
+ *
+ * In theory each single component (host name, domain name, top level domain name)
+ * of a FQDN can have up to 63 characters, but the overall length is limited to
+ * 255 characters. We specify one more character for the trailing 0.
+ */
+typedef char MBG_HOSTNAME[256]; ///< ASCIIZ format
+
+/** @} defgroup group_net_basic_types */
-#define _mbg_swab_ip4_settings( _p ) \
-{ \
- _mbg_swab_ip4_addr( &(_p)->ip_addr ); \
- _mbg_swab_ip4_addr( &(_p)->netmask ); \
- _mbg_swab_ip4_addr( &(_p)->broad_addr ); \
- _mbg_swab_ip4_addr( &(_p)->gateway ); \
- _mbg_swab16( &(_p)->flags ); \
- _mbg_swab16( &(_p)->vlan_cfg ); \
-}
/**
- * @brief Definitions used with IP4_SETTINGS::vlan_cfg
+ * @defgroup group_vlan_cfg Definitions used with VLAN configuration
*
- * @note IP4_SETTINGS::vlan_cfg contains a combination of
- * a VLAN ID number plus a VLAN priority code.
+ * @{ */
+
+/**
+ * @brief VLAN configuration
+ *
+ * @note This is a combination of a VLAN ID number plus a VLAN priority code.
*/
-#define VLAN_ID_BITS 12 //< number of bits to hold the ID
-#define N_VLAN_ID ( 1 << VLAN_ID_BITS ) //< number of ID values
-#define MIN_VLAN_ID 0 //< minimum ID value
-#define MAX_VLAN_ID ( N_VLAN_ID - 1 ) //< maximum ID value
+typedef uint16_t MBG_VLAN_CFG;
+
+#define _mbg_swab_mbg_vlan_cfg( _p ) _mbg_swab16( _p );
+
+#define VLAN_ID_BITS 12 ///< number of bits to hold the ID
+#define N_VLAN_ID ( 1 << VLAN_ID_BITS ) ///< number of ID values
+#define MIN_VLAN_ID 0 ///< minimum ID value
+#define MAX_VLAN_ID ( N_VLAN_ID - 1 ) ///< maximum ID value
// vlan_id = ( vlan_cfg >> VLAN_ID_SHIFT ) & VLAN_ID_MSK
#define VLAN_ID_SHIFT 0
#define VLAN_ID_MSK ( ( 1 << VLAN_ID_BITS ) - 1 )
-#define VLAN_PRIORITY_BITS 3 //< number of bits to hold priority
-#define N_VLAN_PRIORITY ( 1 << VLAN_PRIORITY_BITS ) //< number of priority values
-#define MIN_VLAN_PRIORITY 0 //< minimum priority
-#define MAX_VLAN_PRIORITY ( N_VLAN_PRIORITY - 1 ) //< maximum priority
+#define VLAN_PRIORITY_BITS 3 ///< number of bits to hold priority
+#define N_VLAN_PRIORITY ( 1 << VLAN_PRIORITY_BITS ) ///< number of priority values
+#define MIN_VLAN_PRIORITY 0 ///< minimum priority
+#define MAX_VLAN_PRIORITY ( N_VLAN_PRIORITY - 1 ) ///< maximum priority
// vlan_priority = ( vlan_cfg >> VLAN_PRIORITY_SHIFT ) & VLAN_PRIORITY_MSK
-#define VLAN_PRIORITY_SHIFT ( ( 8 * sizeof( uint16_t ) ) - VLAN_PRIORITY_BITS )
+#define VLAN_PRIORITY_SHIFT ( ( 8 * sizeof( MBG_VLAN_CFG ) ) - VLAN_PRIORITY_BITS )
#define VLAN_PRIORITY_MSK ( ( 1 << VLAN_PRIORITY_BITS ) - 1 )
/**
@@ -4806,102 +7414,743 @@ typedef struct
#define _decode_vlan_priority( _cfg ) ( ( (_cfg) >> VLAN_PRIORITY_SHIFT ) & VLAN_PRIORITY_MSK )
#define _encode_vlan_cfg( _id, _prty ) ( ( (_id) << VLAN_ID_SHIFT ) | ( (_prty) << VLAN_PRIORITY_SHIFT ) )
+/** @} defgroup group_vlan_cfg */
-#if 0 //##++ currently not used
-/* Misc configuration */
+/**
+ * @defgroup group_ip4_cfg Simple IPv4-only configuration or status
+ *
+ * This is only supported if the flag ::GPS_HAS_LAN_IP4 is set
+ * in ::RECEIVER_INFO::features.
+ * @see @ref group_ext_net_cfg Extended network configuration and status
+ *
+ * @{ */
+
+/**
+ * @brief Settings of an IPv4-only network interface
+ */
typedef struct
{
- uint16_t id; /* service ID, see below */
- uint16_t index; /* used if several same svcs must be cfg'd, e.g. DNS */
- char host[50]; /* see below */
+ IP4_ADDR ip_addr; ///< the IP address
+ IP4_ADDR netmask; ///< the network mask
+ IP4_ADDR broad_addr; ///< the broadcast address
+ IP4_ADDR gateway; ///< the default gateway
+ uint16_t flags; ///< see ::MBG_IP4_FLAG_MASKS
+ MBG_VLAN_CFG vlan_cfg; ///< VLAN configuration
-} IP_CFG;
+} IP4_SETTINGS;
+#define _mbg_swab_ip4_settings( _p ) \
+{ \
+ _mbg_swab_ip4_addr( &(_p)->ip_addr ); \
+ _mbg_swab_ip4_addr( &(_p)->netmask ); \
+ _mbg_swab_ip4_addr( &(_p)->broad_addr ); \
+ _mbg_swab_ip4_addr( &(_p)->gateway ); \
+ _mbg_swab16( &(_p)->flags ); \
+ _mbg_swab_mbg_vlan_cfg( &(_p)->vlan_cfg ); \
+}
-/* Description of a service running on a device */
+/**
+ * @brief Simple LAN interface information
+ *
+ * This structure can be retrieved from a device
+ * to check the device's capabilities.
+ *
+ * It is only supported if the flag ::GPS_HAS_LAN_IP4 is set
+ * in ::RECEIVER_INFO::features.
+ *
+ * @see @ref group_ext_net_cfg Extended network configuration and status
+ */
typedef struct
{
- uint16_t id; /* service ID, see below */
- uint16_t socket; /* the socket on which the service is listening */
- uint32_t flags; /* see below */
+ uint16_t type; ///< type of LAN interface, see ::LAN_IF_TYPES
+ MBG_MAC_ADDR mac_addr; ///< MAC address
+ uint16_t ver_code; ///< version number (hex)
+ char ver_str[GPS_ID_STR_SIZE]; ///< version string
+ char sernum[GPS_ID_STR_SIZE]; ///< serial number
+ uint32_t rsvd_0; ///< reserved, currently always 0
+ uint16_t flags; ///< see ::MBG_IP4_FLAG_MASKS
+ uint16_t rsvd_1; ///< reserved, currently always 0
+
+} LAN_IF_INFO;
+
+#define _mbg_swab_lan_if_info( _p ) \
+{ \
+ _mbg_swab16( &(_p)->type ); \
+ _mbg_swab16( &(_p)->ver_code ); \
+ _mbg_swab32( &(_p)->rsvd_0 ); \
+ _mbg_swab16( &(_p)->flags ); \
+ _mbg_swab16( &(_p)->rsvd_1 ); \
+}
-} IP_SERVICE;
-#endif // 0
+/**
+ * @brief Codes used with ::LAN_IF_INFO::type
+ */
+enum LAN_IF_TYPES
+{
+ LAN_IF_TYPE_XPORT, ///< LAN interface on an XPORT, superseded by RSC devices
+ LAN_IF_TYPE_PTP, ///< LAN interface is a special PTP interface
+ LAN_IF_TYPE_RSC, ///< RSC device, supersedes XPORT
+ N_LAN_IF_TYPE ///< number of defined LAN interface types
+};
+
+/**
+ * @brief Enumeration of flag bits used with ::IP4_SETTINGS::flags and ::LAN_IF_INFO::flags
+ *
+ * @see ::MBG_IP4_FLAG_MASKS
+ */
+enum MBG_IP4_FLAG_BITS
+{
+ IP4_BIT_DHCP, ///< DHCP supported (::LAN_IF_INFO) / enabled (::IP4_SETTINGS)
+ IP4_BIT_LINK, ///< only used in ::IP4_SETTINGS to report link state
+ IP4_BIT_VLAN, ///< VLAN supported (::LAN_IF_INFO) / enabled (::IP4_SETTINGS)
+ N_IP4_BIT ///< number of defined flag bits
+};
/**
- * @brief A structure to holds the MAC address of a LAN interface
+ * @brief Bit masks used with ::IP4_SETTINGS::flags and ::LAN_IF_INFO::flags
+ *
+ * @see ::MBG_IP4_FLAG_BITS
*/
-typedef struct
+enum MBG_IP4_FLAG_MASKS
{
- uint8_t b[6];
-} MBG_MAC_ADDR;
+ IP4_MSK_DHCP = ( 1UL << IP4_BIT_DHCP ), ///< see ::IP4_BIT_DHCP
+ IP4_MSK_LINK = ( 1UL << IP4_BIT_LINK ), ///< see ::IP4_BIT_LINK
+ IP4_MSK_VLAN = ( 1UL << IP4_BIT_VLAN ), ///< see ::IP4_BIT_VLAN
+};
+
+/** @} defgroup group_ip4_cfg */
/**
- * @brief LAN interface information
+ * @defgroup group_ext_net_cfg_types Types used for extended network configuration and status
*
- * This structure can be retrieved from a device
- * to check the device's capabilities.
+ * @{ */
+
+/**
+ * @brief Enumeration of types used with ::MBG_IP_ADDR::type
*/
-typedef struct
+enum MBG_IP_ADDR_TYPES
{
- uint16_t type; //< type of LAN interface, see below
- MBG_MAC_ADDR mac_addr; //< MAC address
- uint16_t ver_code; //< version number, high byte.low byte, in hex
- char ver_str[GPS_ID_STR_SIZE]; //< version string
- char sernum[GPS_ID_STR_SIZE]; //< serial number
- uint32_t rsvd_0; //< reserved, currently always 0
- uint16_t flags; //< flags as specified below
- uint16_t rsvd_1; //< reserved, currently always 0
+ MBG_IP_ADDR_TYPE_UNKNOWN,
+ MBG_IP_ADDR_TYPE_IP4,
+ MBG_IP_ADDR_TYPE_IP6
+};
-} LAN_IF_INFO;
+/*
+ * Default initializers for English mode string names. Initializers
+ * for multi-language strings can be found in tmonlstr.h.
+ */
+#define MBG_IP_ADDR_TYPE_STR_ENG_UNKNOWN "unknown"
+#define MBG_IP_ADDR_TYPE_STR_ENG_IP4 "IPv4"
+#define MBG_IP_ADDR_TYPE_STR_ENG_IP6 "IPv6"
-#define _mbg_swab_lan_if_info( _p ) \
-{ \
- _mbg_swab16( &(_p)->type ); \
- _mbg_swab16( &(_p)->ver_code ); \
- _mbg_swab32( &(_p)->rsvd_0 ); \
- _mbg_swab16( &(_p)->flags ); \
- _mbg_swab16( &(_p)->rsvd_1 ); \
+#define MBG_IP_ADDR_TYPE_NAMES_ENG \
+{ \
+ MBG_IP_ADDR_TYPE_STR_ENG_UNKNOWN, \
+ MBG_IP_ADDR_TYPE_STR_ENG_IP4, \
+ MBG_IP_ADDR_TYPE_STR_ENG_IP6 \
}
+/**
+ * @brief Network link speed modes
+ *
+ * @see ::MBG_NET_LINK_MODE_MASKS
+ *
+ * Note: Half duplex is not supported for 10GBit
+ */
+enum MBG_NET_LINK_MODES
+{
+ MBG_NET_LINK_MODE_AUTONEG, ///< auto negotiation
+ MBG_NET_LINK_MODE_10_BT_H, ///< 10 MBit half duplex
+ MBG_NET_LINK_MODE_10_BT_F, ///< 10 MBit full duplex
+ MBG_NET_LINK_MODE_100_BT_H, ///< 100 MBit half duplex
+ MBG_NET_LINK_MODE_100_BT_F, ///< 100 MBit full duplex
+ MBG_NET_LINK_MODE_1000_BT_H, ///< 1 GBit half duplex
+ MBG_NET_LINK_MODE_1000_BT_F, ///< 1 GBit full duplex
+ MBG_NET_LINK_MODE_10000_BT_F, ///< 10 GBit Full Duplex
+ N_MBG_NET_LINK_MODES
+};
+
+
+/**
+ * @brief Network link speed mode masks
+ *
+ * @see ::MBG_NET_LINK_MODES
+ */
+enum MBG_NET_LINK_MODE_MASKS
+{
+ MBG_NET_LINK_MODE_MASK_AUTONEG = ( 1UL << MBG_NET_LINK_MODE_AUTONEG ), ///< see ::MBG_NET_LINK_MODE_AUTONEG
+ MBG_NET_LINK_MODE_MASK_10_BT_H = ( 1UL << MBG_NET_LINK_MODE_10_BT_H ), ///< see ::MBG_NET_LINK_MODE_10_BT_H
+ MBG_NET_LINK_MODE_MASK_10_BT_F = ( 1UL << MBG_NET_LINK_MODE_10_BT_F ), ///< see ::MBG_NET_LINK_MODE_10_BT_F
+ MBG_NET_LINK_MODE_MASK_100_BT_H = ( 1UL << MBG_NET_LINK_MODE_100_BT_H ), ///< see ::MBG_NET_LINK_MODE_100_BT_H
+ MBG_NET_LINK_MODE_MASK_100_BT_F = ( 1UL << MBG_NET_LINK_MODE_100_BT_F ), ///< see ::MBG_NET_LINK_MODE_100_BT_F
+ MBG_NET_LINK_MODE_MASK_1000_BT_H = ( 1UL << MBG_NET_LINK_MODE_1000_BT_H ), ///< see ::MBG_NET_LINK_MODE_1000_BT_H
+ MBG_NET_LINK_MODE_MASK_1000_BT_F = ( 1UL << MBG_NET_LINK_MODE_1000_BT_F ), ///< see ::MBG_NET_LINK_MODE_1000_BT_F
+ MBG_NET_LINK_MODE_MASK_10000_BT_F = ( 1UL << MBG_NET_LINK_MODE_10000_BT_F ) ///< see ::MBG_NET_LINK_MODE_10000_BT_F
+};
+
+
/**
- * @brief Codes used with LAN_IF_INFO::type
+ * @brief Network link port types
+ *
+ * @see ::MBG_NET_LINK_PORT_MASKS
*/
-enum
+enum MBG_NET_LINK_PORTS
{
- LAN_IF_TYPE_XPORT, //< LAN interface on an XPORT
- LAN_IF_TYPE_PTP, //< LAN interface is a special PTP interface
- N_LAN_IF_TYPE //< number of defined LAN interface types
+ MBG_NET_LINK_PORT_AUTO, ///< auto detection
+ MBG_NET_LINK_PORT_TP, ///< Twisted Pair (TP)
+ MBG_NET_LINK_PORT_AUI, ///< Attachment Unit Interface (AUI), externel transceiver
+ MBG_NET_LINK_PORT_MII, ///< Media Independent Interface (MII), external receiver
+ MBG_NET_LINK_PORT_FIBRE, ///< fibre optic
+ MBG_NET_LINK_PORT_BNC, ///< coaxial cable
+ N_MBG_NET_LINK_PORTS
};
/**
- * @brief Flags used with IP4_SETTINGS::flags and LAN_IF_INFO::flags
+ * @brief Network link port type masks
+ *
+ * @see ::MBG_NET_LINK_PORTS
*/
-enum
+enum MBG_NET_LINK_PORT_MASKS
+{
+ MBG_NET_LINK_PORT_MASK_AUTO = ( 1UL << MBG_NET_LINK_PORT_AUTO ), ///< see ::MBG_NET_LINK_PORT_AUTO
+ MBG_NET_LINK_PORT_MASK_TP = ( 1UL << MBG_NET_LINK_PORT_TP ), ///< see ::MBG_NET_LINK_PORT_TP
+ MBG_NET_LINK_PORT_MASK_AUI = ( 1UL << MBG_NET_LINK_PORT_AUI ), ///< see ::MBG_NET_LINK_PORT_AUI
+ MBG_NET_LINK_PORT_MASK_MII = ( 1UL << MBG_NET_LINK_PORT_MII ), ///< see ::MBG_NET_LINK_PORT_MII
+ MBG_NET_LINK_PORT_MASK_FIBRE = ( 1UL << MBG_NET_LINK_PORT_FIBRE ), ///< see ::MBG_NET_LINK_PORT_FIBRE
+ MBG_NET_LINK_PORT_MASK_BNC = ( 1UL << MBG_NET_LINK_PORT_BNC ) ///< see ::MBG_NET_LINK_PORT_BNC
+};
+
+
+
+/**
+ * @brief Network link state bits
+ *
+ * @see ::MBG_NET_LINK_STATE_MASKS
+ *
+ * @note See official Linux kernel documentation
+ * https://www.kernel.org/doc/Documentation/networking/operstates.txt
+ * for states below and explanations. Windows supports this in nearly the same way
+ * using similar names struct IP_ADAPTER_ADDRESSES which is explained at
+ * http://msdn.microsoft.com/en-us/library/windows/desktop/aa366058%28v=vs.85%29.aspx
+ */
+enum MBG_NET_LINK_STATE_BITS
+{
+ MBG_NET_LINK_STATE_BIT_UP,
+ MBG_NET_LINK_STATE_BIT_BROADCAST,
+ MBG_NET_LINK_STATE_BIT_LOOPBACK,
+ MBG_NET_LINK_STATE_BIT_P2P,
+ MBG_NET_LINK_STATE_BIT_RUNNING,
+ MBG_NET_LINK_STATE_BIT_NO_ARP,
+ MBG_NET_LINK_STATE_BIT_PROMISC,
+ MBG_NET_LINK_STATE_BIT_MASTER,
+ MBG_NET_LINK_STATE_BIT_SLAVE,
+ MBG_NET_LINK_STATE_BIT_MULTICAST,
+ MBG_NET_LINK_STATE_BIT_LOWER_UP,
+ MBG_NET_LINK_STATE_BIT_DORMANT,
+ MBG_NET_LINK_STATE_BIT_ECHO,
+ N_MBG_NET_LINK_STATE_BITS
+};
+
+
+/**
+ * @brief Network link state masks
+ *
+ * @see ::MBG_NET_LINK_STATE_BITS (reclined to Linux' if.h, Windows is similiar)
+ */
+enum MBG_NET_LINK_STATE_MASKS
+{
+ MBG_NET_LINK_STATE_MASK_UP = ( 1UL << MBG_NET_LINK_STATE_BIT_UP ), ///< see ::MBG_NET_LINK_STATE_BIT_UP
+ MBG_NET_LINK_STATE_MASK_BROADCAST = ( 1UL << MBG_NET_LINK_STATE_BIT_BROADCAST ), ///< see ::MBG_NET_LINK_STATE_BIT_BROADCAST
+ MBG_NET_LINK_STATE_MASK_LOOPBACK = ( 1UL << MBG_NET_LINK_STATE_BIT_LOOPBACK ), ///< see ::MBG_NET_LINK_STATE_BIT_LOOPBACK
+ MBG_NET_LINK_STATE_MASK_P2P = ( 1UL << MBG_NET_LINK_STATE_BIT_P2P ), ///< see ::MBG_NET_LINK_STATE_BIT_P2P
+ MBG_NET_LINK_STATE_MASK_RUNNING = ( 1UL << MBG_NET_LINK_STATE_BIT_RUNNING ), ///< see ::MBG_NET_LINK_STATE_BIT_RUNNING
+ MBG_NET_LINK_STATE_MASK_NO_ARP = ( 1UL << MBG_NET_LINK_STATE_BIT_NO_ARP ), ///< see ::MBG_NET_LINK_STATE_BIT_NO_ARP
+ MBG_NET_LINK_STATE_MASK_PROMISC = ( 1UL << MBG_NET_LINK_STATE_BIT_PROMISC ), ///< see ::MBG_NET_LINK_STATE_BIT_PROMISC
+ MBG_NET_LINK_STATE_MASK_MASTER = ( 1UL << MBG_NET_LINK_STATE_BIT_MASTER ), ///< see ::MBG_NET_LINK_STATE_BIT_MASTER
+ MBG_NET_LINK_STATE_MASK_SLAVE = ( 1UL << MBG_NET_LINK_STATE_BIT_SLAVE ), ///< see ::MBG_NET_LINK_STATE_BIT_SLAVE
+ MBG_NET_LINK_STATE_MASK_MULTICAST = ( 1UL << MBG_NET_LINK_STATE_BIT_MULTICAST ), ///< see ::MBG_NET_LINK_STATE_BIT_MULTICAST
+ MBG_NET_LINK_STATE_MASK_LOWER_UP = ( 1UL << MBG_NET_LINK_STATE_BIT_LOWER_UP ), ///< see ::MBG_NET_LINK_STATE_BIT_LOWER_UP
+ MBG_NET_LINK_STATE_MASK_DORMANT = ( 1UL << MBG_NET_LINK_STATE_BIT_DORMANT ), ///< see ::MBG_NET_LINK_STATE_BIT_DORMANT
+ MBG_NET_LINK_STATE_MASK_ECHO = ( 1UL << MBG_NET_LINK_STATE_BIT_ECHO ) ///< see ::MBG_NET_LINK_STATE_BIT_ECHO
+};
+
+
+
+/**
+ * @brief Network link option bits
+ *
+ * @see ::MBG_NET_LINK_OPT_MASKS
+ */
+enum MBG_NET_LINK_OPTS
{
- IP4_BIT_DHCP, //< DHCP supported (LAN_IF_INFO) / enabled (IP4_SETTINGS)
- IP4_BIT_LINK, //< used only in IP4_SETTINGS to report link state
- IP4_BIT_VLAN, //< VLAN supported (LAN_IF_INFO) / enabled (IP4_SETTINGS)
- N_IP4_BIT //< number of defined flag bits
+ MBG_NET_LINK_OPT_CAN_SET_MAC,
+ MBG_NET_LINK_OPT_CAN_BOND,
+ N_MBG_NET_LINK_OPTS
};
-#define IP4_MSK_DHCP ( 1UL << IP4_BIT_DHCP )
-#define IP4_MSK_LINK ( 1UL << IP4_BIT_LINK )
-#define IP4_MSK_VLAN ( 1UL << IP4_BIT_VLAN )
-/** @} group_ip4_cfg */
+/**
+ * @brief Network link option masks
+ *
+ * @see ::MBG_NET_LINK_OPTS
+ */
+enum MBG_NET_LINK_OPT_MASKS
+{
+ MBG_NET_LINK_OPT_MASK_CAN_SET_MAC = ( 1UL << MBG_NET_LINK_OPT_CAN_SET_MAC ), ///< see ::MBG_NET_LINK_OPT_CAN_SET_MAC
+ MBG_NET_LINK_OPT_MASK_CAN_BOND = ( 1UL << MBG_NET_LINK_OPT_CAN_BOND ) ///< see ::MBG_NET_LINK_OPT_CAN_BOND
+};
+
+
+
+/**
+ * @brief Network link roles
+ *
+ * Used with ::MBG_NET_LINK_SETTINGS::role to determine
+ * if a network link operates in normal mode, or in
+ * a special mode, e.g. as part of a higher level pseudo
+ * interface (bonding, etc.)
+ */
+enum MBG_NET_LINK_ROLES
+{
+ MBG_NET_LINK_ROLE_UNKNOWN, ///< role can't be determined
+ MBG_NET_LINK_ROLE_NORMAL, ///< link is normal physical interface
+ MBG_NET_LINK_ROLE_MASTER, ///< link is master (e.g. bonding)
+ MBG_NET_LINK_ROLE_SLAVE, ///< link is slave (e.g. bonding)
+ N_MBG_NET_LINK_ROLES
+};
+//##++++++++++++++++ TODO define masks?
+
+
+
+/**
+ * @brief Network link bonding bits
+ *
+ * @see SIOCGIFPFLAGS under Linux, found no hint under Windows
+ */
+enum MBG_NET_LINK_ROLE_BITS
+{
+ MBG_NET_LINK_ROLE_BIT_BONDING, ///< Bonding master
+ MBG_NET_LINK_ROLE_BIT_BOND_SLAVE_INACTIVE, ///< Bonding slave is not active
+ MBG_NET_LINK_ROLE_BIT_BOND_MASTER_8023AD, ///< 802.3ad bonding master
+ MBG_NET_LINK_ROLE_BIT_BOND_MASTER_ALB, ///< Balanced-alb bonding master
+ N_MBG_NET_LINK_ROLE_BITS
+};
+
+
+/**
+ * @brief Network link role masks
+ *
+ * @see ::MBG_NET_LINK_ROLE_BITS
+ */
+enum MBG_NET_LINK_ROLE_MASKS
+{
+ MBG_NET_LINK_ROLE_MASK_BONDING = ( 1UL << MBG_NET_LINK_ROLE_BIT_BONDING ), ///< see ::MBG_NET_LINK_ROLE_BIT_BONDING
+ MBG_NET_LINK_ROLE_MASK_BOND_SLAVE_INACTIVE = ( 1UL << MBG_NET_LINK_ROLE_BIT_BOND_SLAVE_INACTIVE ), ///< see ::MBG_NET_LINK_ROLE_BIT_BOND_SLAVE_INACTIVE
+ MBG_NET_LINK_ROLE_MASK_BOND_MASTER_8023AD = ( 1UL << MBG_NET_LINK_ROLE_BIT_BOND_MASTER_8023AD ), ///< see ::MBG_NET_LINK_ROLE_BIT_BOND_MASTER_8023AD
+ MBG_NET_LINK_ROLE_MASK_BOND_MASTER_ALB = ( 1UL << MBG_NET_LINK_ROLE_BIT_BOND_MASTER_ALB ), ///< see ::MBG_NET_LINK_ROLE_BIT_BOND_MASTER_ALB
+ N_MBG_NET_LINK_ROLE_MASKS
+};
+
+
+
+/**
+ * @brief Network link bonding mode
+ *
+ * Used with ::MBG_NET_LINK_SETTINGS::role_value
+ *
+ * @note if_bonding.h contains bonding modes under Linux, found no hint under Windows.
+ * BUT: Something similiar (concerning naming) can be configured under Windows
+ * via GUI in device manager, if supported.
+ */
+enum MBG_NET_LINK_BOND_MODES
+{
+ MBG_NET_LINK_BOND_MODE_UNKNOWN,
+ MBG_NET_LINK_BOND_MODE_ROUNDROBIN,
+ MBG_NET_LINK_BOND_MODE_ACTIVEBACKUP,
+ MBG_NET_LINK_BOND_MODE_XOR,
+ MBG_NET_LINK_BOND_MODE_BROADCAST,
+ MBG_NET_LINK_BOND_MODE_8023AD,
+ MBG_NET_LINK_BOND_MODE_TLB,
+ MBG_NET_LINK_BOND_MODE_ALB,
+ N_MBG_NET_LINK_BOND_MODES
+};
+
+
+/**
+ * @brief Network logical interface commands
+ *
+ * Used with ::MBG_NET_INTF_SETTINGS::cmd
+ */
+enum MBG_NET_LOG_INTF_CMDS
+{
+ MBG_NET_LOG_CMD_NONE,
+ MBG_NET_LOG_CMD_ADD_UPDATE,
+ MBG_NET_LOG_CMD_REMOVE,
+ N_MBG_NET_LOG_CMDS
+};
+
+
+/**
+ * @brief Network logical interface roles
+ *
+ * Used with ::MBG_NET_INTF_SETTINGS::role
+ */
+enum MBG_NET_LOG_INTF_ROLES
+{
+ MBG_NET_LOG_ROLE_STANDARD,
+ MBG_NET_LOG_ROLE_BOND,
+ MBG_NET_LOG_ROLE_VLAN,
+ N_MBG_NET_INTF_ROLE
+};
+
+
+/**
+ * @brief Network interface bits
+ *
+ * @see ::MBG_NET_INTF_MASKS
+ *
+ * Used with ::MBG_NET_INTF_INFO::supp_flags
+ */
+enum MBG_NET_INTF_BITS
+{
+ MBG_NET_INTF_BIT_EXT_ROUTING,
+ N_MBG_NET_INTF_BITS
+};
+
+
+/**
+ * @brief Network interface masks
+ *
+ * @see ::MBG_NET_INTF_BITS
+ */
+enum MBG_NET_INTF_MASKS
+{
+ MBG_NET_INTF_MASK_EXT_ROUTING = ( 1UL << MBG_NET_INTF_BIT_EXT_ROUTING ) ///< see ::MBG_NET_INTF_BIT_EXT_ROUTING
+};
+
+/** @} defgroup group_ext_net_cfg_types */
+
+
+
+/**
+ * @defgroup group_ext_net_cfg Extended network configuration and status
+ *
+ * This is only supported if the flag ::GPS_HAS_NET_CFG is set
+ * in ::RECEIVER_INFO::features.
+ *
+ * @{ */
+
+/**
+ * @brief Global network configuration settings
+ */
+typedef struct
+{
+ MBG_HOSTNAME hostname; ///< hostname, eventually FQDN including domain name
+ uint32_t reserved; ///< currently reserved, always 0
+ uint32_t flags; ///< currently reserved, always 0
+ //##++++ TODO: flags could control IPv6, enable forwarding, etc.
+
+} MBG_NET_GLB_CFG_SETTINGS;
+
+#define _mbg_swab_net_glb_cfg_settings( _p ) \
+{ \
+ _mbg_swab32( &(_p)->reserved ); \
+ _mbg_swab32( &(_p)->flags ); \
+}
+
+
+/**
+ * @brief Global current network settings and supported features
+ */
+typedef struct
+{
+ MBG_NET_GLB_CFG_SETTINGS glb_settings;
+ uint16_t num_link; ///< max. supported links (physical interfaces), see ::MBG_NET_LINK_SETTINGS_IDX, ::MBG_NET_LINK_INFO_IDX
+ uint16_t num_intf; ///< max. logical (including virtual) interfaces, see ::MBG_NET_INTF_SETTINGS_IDX, ::MBG_NET_INTF_INFO_IDX
+ uint16_t num_dns_srvr; ///< max. configurable DNS server addresses, using ::MBG_IP_ADDR_IDX records
+ uint16_t num_dns_srch_dom; ///< max. configurable DNS search domain records, using ::MBG_NET_NAME_IDX records
+ uint16_t num_static_routes; ///< max. configurable static routes
+ uint16_t max_hostname_len; ///< max. length of hostname including trailing 0; if set to 0, max. length is 256 (see rfc1123)
+ uint32_t reserved_1; ///< currently reserved, always 0
+ uint32_t reserved_2; ///< currently reserved, always 0
+ uint32_t flags_1; ///< currently reserved, always 0
+ uint32_t flags_2; ///< currently reserved, always 0
+
+} MBG_NET_GLB_CFG_INFO;
+
+#define _mbg_swab_net_glb_cfg_info( _p ) \
+{ \
+ _mbg_swab_net_glb_cfg_settings( &(_p)->glb_settings ); \
+ _mbg_swab16( &(_p)->num_link ); \
+ _mbg_swab16( &(_p)->num_intf ); \
+ _mbg_swab16( &(_p)->num_dns_srvr ); \
+ _mbg_swab16( &(_p)->num_dns_srch_dom ); \
+ _mbg_swab16( &(_p)->num_static_routes ); \
+ _mbg_swab16( &(_p)->max_hostname_len ); \
+ _mbg_swab32( &(_p)->reserved_1 ); \
+ _mbg_swab32( &(_p)->reserved_2 ); \
+ _mbg_swab32( &(_p)->flags_1 ); \
+ _mbg_swab32( &(_p)->flags_2 ); \
+}
+
+
+/**
+ * @brief An IPv4 or IPv6 network address
+ */
+typedef struct
+{
+ uint8_t type; ///< see ::MBG_IP_ADDR_TYPES
+ uint8_t reserved_1; ///< reserved, currently always 0 @todo Do we need this as scope indicator?
+ uint16_t reserved_2; ///< reserved, currently always 0
+
+ union
+ {
+ IP4_ADDR ip4_addr; ///< IPv4 address if ::MBG_IP_ADDR::type == MBG_IP_ADDR_TYPE_IP4
+ IP6_ADDR ip6_addr; ///< IPv6 address if ::MBG_IP_ADDR::type == MBG_IP_ADDR_TYPE_IP6
+ } u_addr;
+
+} MBG_IP_ADDR;
+
+
+/**
+ * @brief An IPv4 or IPv6 network address, plus index
+ */
+typedef struct
+{
+ uint16_t idx;
+ MBG_IP_ADDR addr; ///< network address
+
+} MBG_IP_ADDR_IDX;
+
+
+/**
+ * @brief Network host or domain name
+ */
+typedef struct
+{
+ MBG_HOSTNAME name;
+
+} MBG_NET_NAME;
+
+
+/**
+ * @brief Network host or domain name, plus index
+ */
+typedef struct
+{
+ uint16_t idx;
+ MBG_NET_NAME net_name;
+
+} MBG_NET_NAME_IDX;
+
+
+
+/**
+ * @brief Link (physical interface) specific settings
+ */
+typedef struct
+{
+ MBG_MAC_ADDR mac_addr; ///< Physical hardware address
+ MBG_MAC_ADDR broadcast; ///< Physical broadcast address
+ uint32_t mtu; ///< Max. packet size in bytes
+ uint32_t states; ///< see ::MBG_NET_LINK_STATE_BITS
+ uint32_t flags; ///< Reserved, currently 0
+ uint32_t reserved_1; ///< Reserved, currently 0
+ uint32_t reserved_2; ///< Reserved, currently 0
+ uint16_t bond_idx; ///< Current primary slave link index in ::MBG_NET_LINK_ROLE_MASTER role,
+ ///< current bonding master link index in ::MBG_NET_LINK_ROLE_SLAVE role,
+ ///< otherwise reserved and usually 0.
+ uint8_t speed_mode; ///< see ::MBG_NET_LINK_MODES
+ uint8_t port; ///< see ::MBG_NET_LINK_PORTS
+ uint8_t role; ///< see ::MBG_NET_LINK_ROLES
+ uint8_t reserved[3]; ///< Alignment. Can be used in future for usefull stuff.
+//##+++++ TODO check reserved above
+ uint32_t role_flags; ///< see ::MBG_NET_LINK_ROLE_BITS
+ uint32_t role_value; ///< Additional role parameters depending on role and role_flags,
+ ///< e.g. if role is master and flags contain bonding.
+ ///< See ::MBG_NET_LINK_BOND_MODES.
+} MBG_NET_LINK_SETTINGS;
+
+#define _mbg_swab_net_link_settings( _p ) \
+{ \
+ _mbg_swab32( &(_p)->mtu ); \
+ _mbg_swab32( &(_p)->states ); \
+ _mbg_swab32( &(_p)->flags ); \
+ _mbg_swab32( &(_p)->reserved_1 ); \
+ _mbg_swab32( &(_p)->reserved_2 ); \
+ _mbg_swab16( &(_p)->bond_idx ); \
+ _mbg_swab32( &(_p)->role_flags ); \
+ _mbg_swab32( &(_p)->role_value ); \
+}
+
+/**
+ * @brief Link (physical interface) specific settings, plus index
+ */
+typedef struct
+{
+ uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_INFO::num_link-1
+ MBG_NET_LINK_SETTINGS settings;
+
+} MBG_NET_LINK_SETTINGS_IDX;
+
+
+/**
+ * @brief Link (physical interface) specific settings, flags and supported features
+ */
+typedef struct
+{
+ MBG_NET_LINK_SETTINGS link_settings; ///< see ::MBG_NET_LINK_SETTINGS
+ uint32_t supp_opts; ///< see ::MBG_NET_LINK_OPT_MASKS
+ uint32_t supp_speed_modes; ///< see ::MBG_NET_LINK_MODE_MASKS
+ uint32_t supp_link_ports; ///< see ::MBG_NET_LINK_PORT_MASKS
+ uint32_t supp_states; ///< see ::MBG_NET_LINK_STATE_MASKS
+ uint32_t reserved_2;
+ uint32_t reserved_3;
+
+} MBG_NET_LINK_INFO;
+
+#define _mbg_swab_net_link_info( _p ) \
+{ \
+ _mbg_swab_net_link_settings( &(_p)->link_settings ); \
+ _mbg_swab32( &(_p)->supp_opts ); \
+ _mbg_swab32( &(_p)->supp_speed_modes ); \
+ _mbg_swab32( &(_p)->supp_link_ports ); \
+ _mbg_swab32( &(_p)->supp_states ); \
+ _mbg_swab32( &(_p)->reserved_2 ); \
+ _mbg_swab32( &(_p)->reserved_3 ); \
+}
+
+
+/**
+ * @brief Query MBG_NET_LINK_INFO by its index
+ */
+typedef struct
+{
+ uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_INFO::num_link-1
+ MBG_NET_LINK_INFO info;
+
+} MBG_NET_LINK_INFO_IDX;
+
+
+/**
+ * @brief Interface specific settings, flags and supported features
+ *
+ * @note Use link_mac and role to identify uniquely its associated network link.
+ */
+typedef struct
+{
+ uint8_t cmd; ///< see ::MBG_NET_LOG_INTF_CMDS
+ uint8_t role; ///< see ::MBG_NET_LOG_INTF_ROLES
+ uint16_t reserved_1; ///< Reserved, currently 0
+ uint32_t role_value; ///< Role specific value. E.g. VLAN ID
+ uint32_t flags; ///< Reserved, currently 0
+ uint32_t reserved_2; ///< Reserved, currently 0
+ MBG_IP_ADDR ip; ///< IP address associated with this interface
+ MBG_IP_ADDR gateway; ///< Interface specific. Reserved for future use. see ::MBG_IP_ADDR and ::MBG_NET_INTF_BIT_EXT_ROUTING
+ MBG_MAC_ADDR link_mac; ///< Unique identifier for related link (physical) interface
+ uint8_t prefix; ///< Subnet mask bits for CIDR notation, e.g. /24
+ uint8_t reserved_3; ///< Reserved, currently 0
+
+} MBG_NET_INTF_SETTINGS;
+
+
+/**
+ * @brief Query MBG_NET_INTF_INFO by its index
+ */
+typedef struct
+{
+ uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_INFO::num_intf-1
+ MBG_NET_INTF_SETTINGS settings;
+
+} MBG_NET_INTF_SETTINGS_IDX;
+
+
+/**
+ * @brief Interface specific settings, flags and supported features
+ */
+typedef struct
+{
+ MBG_NET_INTF_SETTINGS intf_settings;
+ uint32_t supp_flags; ///< see ::MBG_NET_INTF_MASKS
+ uint32_t reserved_1; ///< Reserved, currently 0
+ uint32_t reserved_2; ///< Reserved, currently 0
+
+} MBG_NET_INTF_INFO;
+
+
+/**
+ * @brief Query MBG_NET_INTF_INFO by its index
+ */
+typedef struct
+{
+ uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_INFO::num_intf-1
+ MBG_NET_INTF_INFO info;
+
+} MBG_NET_INTF_INFO_IDX;
+
+
+/**
+ * @brief An IPv4 or IPv6 network address plus UDP or TCP port number
+ */
+typedef struct
+{
+ MBG_IP_ADDR addr; ///< see ::MBG_IP_ADDR
+
+ uint16_t port; ///< UDP or TCP port
+ uint16_t flags; ///< currently always 0
+ //##+++++ TODO should the flags field indicate if the port is UDP and/or TCP?
+
+} MBG_IP_ADDR_PORT;
+
+
+
+#if 0 //##++++++++++++++++++++++
+
+/**
+ * @brief Network service configuration
+ *
+ * Used to configure known services, e.g SSH, FTP, etc.
+ */
+typedef struct
+{
+ uint16_t svc_type; ///< see ::MBG_NET_SVC_TYPES
+ uint16_t reserved; ///< reserved, currently always 0
+ MBG_IP_ADDR_PORT settings; ///< The network address and port a service listens on
+ uint32_t flags; ///< reserved, currently always 0
+
+} MBG_NET_INTF_CFG;
+
+
+
+/**
+ * @brief
+ */
+typedef struct
+{
+ uint8_t b[IP6_ADDR_BYTES]; ///< bytes holding the address bits, b[0] == LSBs
+//##+++ uint8_t cidr_net_mask; ///< number of CIDR net mask bits, 0..::IP6_ADDR_BITS
+// uint8_t reserved; ///< not yet used, always 0
+// uint16_t flags; ///< not yet used, always 0
+
+} MBG_NET_INTF_CFG;
+
+#endif
+
+/** @} defgroup group_ext_net_cfg */
+
+/** @} defgroup group_net_cfg */
@@ -4912,29 +8161,44 @@ enum
/**
* @brief Enumeration of protocols possibly used with PTP
+ *
+ * @see ::PTP_NW_PROT_MASKS
+ */
+enum PTP_NW_PROTS
+{
+ PTP_NW_PROT_RESERVED, ///< reserved
+ PTP_NW_PROT_UDP_IPV4, ///< IPv4
+ PTP_NW_PROT_UDP_IPV6, ///< IPv6
+ PTP_NW_PROT_IEEE_802_3, ///< Ethernet (raw layer 2)
+ PTP_NW_PROT_DEVICE_NET, ///< DeviceNet
+ PTP_NW_PROT_CONTROL_NET, ///< ControlNet
+ PTP_NW_PROT_PROFINET, ///< ProfiNet
+ N_PTP_NW_PROT ///< number of defined protocols
+};
+
+
+/**
+ * @brief Bit masks for enumerated protocols possibly used with PTP
+ *
+ * @see ::PTP_NW_PROTS
*/
-enum
+enum PTP_NW_PROT_MASKS
{
- PTP_NW_PROT_BIT_RESERVED, //< reserved
- PTP_NW_PROT_BIT_UDP_IPV4, //< IPv4
- PTP_NW_PROT_BIT_UDP_IPV6, //< IPv6
- PTP_NW_PROT_BIT_IEEE_802_3, //< Ethernet (raw layer 2)
- PTP_NW_PROT_BIT_DEVICE_NET, //< DeviceNet
- PTP_NW_PROT_BIT_CONTROL_NET, //< ControlNet
- PTP_NW_PROT_BIT_PROFINET, //< ProfiNet
- N_PTP_NW_PROT //< number of defined protocols
+ PTP_NW_PROT_MSK_RESERVED = ( 1UL << PTP_NW_PROT_RESERVED ), ///< see ::PTP_NW_PROT_RESERVED
+ PTP_NW_PROT_MSK_UDP_IPV4 = ( 1UL << PTP_NW_PROT_UDP_IPV4 ), ///< see ::PTP_NW_PROT_UDP_IPV4
+ PTP_NW_PROT_MSK_UDP_IPV6 = ( 1UL << PTP_NW_PROT_UDP_IPV6 ), ///< see ::PTP_NW_PROT_UDP_IPV6
+ PTP_NW_PROT_MSK_IEEE_802_3 = ( 1UL << PTP_NW_PROT_IEEE_802_3 ), ///< see ::PTP_NW_PROT_IEEE_802_3
+ PTP_NW_PROT_MSK_DEVICE_NET = ( 1UL << PTP_NW_PROT_DEVICE_NET ), ///< see ::PTP_NW_PROT_DEVICE_NET
+ PTP_NW_PROT_MSK_CONTROL_NET = ( 1UL << PTP_NW_PROT_CONTROL_NET ), ///< see ::PTP_NW_PROT_CONTROL_NET
+ PTP_NW_PROT_MSK_PROFINET = ( 1UL << PTP_NW_PROT_PROFINET ) ///< see ::PTP_NW_PROT_PROFINET
};
-#define PTP_NW_PROT_MSK_RESERVED ( 1UL << PTP_NW_PROT_BIT_RESERVED )
-#define PTP_NW_PROT_MSK_UDP_IPV4 ( 1UL << PTP_NW_PROT_BIT_UDP_IPV4 )
-#define PTP_NW_PROT_MSK_UDP_IPV6 ( 1UL << PTP_NW_PROT_BIT_UDP_IPV6 )
-#define PTP_NW_PROT_MSK_IEEE_802_3 ( 1UL << PTP_NW_PROT_BIT_IEEE_802_3 )
-#define PTP_NW_PROT_MSK_DEVICE_NET ( 1UL << PTP_NW_PROT_BIT_DEVICE_NET )
-#define PTP_NW_PROT_MSK_CONTROL_NET ( 1UL << PTP_NW_PROT_BIT_CONTROL_NET )
-#define PTP_NW_PROT_MSK_PROFINET ( 1UL << PTP_NW_PROT_BIT_PROFINET )
+
/**
* @brief Name strings for the protocols possibly used with PTP
+ *
+ * @see ::PTP_NW_PROTS
*/
#define PTP_NW_PROT_STRS \
{ \
@@ -4950,6 +8214,8 @@ enum
/**
* @brief Short name strings for the protocols possibly used with PTP
+ *
+ * @see ::PTP_NW_PROTS
*/
#define PTP_NW_PROT_STRS_SHORT \
{ \
@@ -4966,19 +8232,19 @@ enum
/**
* @brief Possible states of a PTP port
*/
-enum
-{
- PTP_PORT_STATE_UNINITIALIZED, //< uninitialized
- PTP_PORT_STATE_INITIALIZING, //< currently initializing
- PTP_PORT_STATE_FAULTY, //< faulty
- PTP_PORT_STATE_DISABLED, //< disabled
- PTP_PORT_STATE_LISTENING, //< listening for PTP packets
- PTP_PORT_STATE_PRE_MASTER, //< going to become master
- PTP_PORT_STATE_MASTER, //< master
- PTP_PORT_STATE_PASSIVE, //< passive
- PTP_PORT_STATE_UNCALIBRATED, //< uncalibrated
- PTP_PORT_STATE_SLAVE, //< slave
- N_PTP_PORT_STATE //< number of defined port states
+enum PTP_PORT_STATES
+{
+ PTP_PORT_STATE_UNINITIALIZED, ///< uninitialized
+ PTP_PORT_STATE_INITIALIZING, ///< currently initializing
+ PTP_PORT_STATE_FAULTY, ///< faulty
+ PTP_PORT_STATE_DISABLED, ///< disabled
+ PTP_PORT_STATE_LISTENING, ///< listening for PTP packets
+ PTP_PORT_STATE_PRE_MASTER, ///< going to become master
+ PTP_PORT_STATE_MASTER, ///< master
+ PTP_PORT_STATE_PASSIVE, ///< passive
+ PTP_PORT_STATE_UNCALIBRATED, ///< uncalibrated
+ PTP_PORT_STATE_SLAVE, ///< slave
+ N_PTP_PORT_STATE ///< number of defined port states
};
@@ -5005,36 +8271,51 @@ enum
*/
typedef struct
{
- uint8_t value; //< the parameter value
- const char *name; //< the parameter name
+ uint8_t value; ///< the parameter value
+ const char *name; ///< the parameter name
+
} PTP_TABLE;
+
/**
* @brief An enumeration of PTP delay mechanisms
*
* @note This is different than the numeric values specified
* in the published specs for IEEE1588. In addition, the specs
- * define 0x14 for "disabled".
+ * define code 0x14 for "disabled".
+ *
+ * @see ::PTP_DELAY_MECH_MASKS
+ * @see ::PTP_DELAY_MECH_NAMES
*/
-enum
+enum PTP_DELAY_MECHS
{
- PTP_DELAY_MECH_BIT_E2E, //< End-to-End (in PTP2 specs: 0x01)
- PTP_DELAY_MECH_BIT_P2P, //< Peer-to-Peer (in PTP2 specs: 0x02)
- N_PTP_DELAY_MECH //< number of defined delay mechanisms
+ PTP_DELAY_MECH_E2E, ///< End-to-End (in PTP2 specs: 0x01)
+ PTP_DELAY_MECH_P2P, ///< Peer-to-Peer (in PTP2 specs: 0x02)
+ N_PTP_DELAY_MECH ///< number of defined delay mechanisms
};
-#define PTP_DELAY_MECH_MSK_E2E ( 1UL << PTP_DELAY_MECH_BIT_E2E )
-#define PTP_DELAY_MECH_MSK_P2P ( 1UL << PTP_DELAY_MECH_BIT_P2P )
-
/**
- * @brief Name strings for the PTP delay mechanisms
+ * @brief Bit masks associated with enumerated PTP delay mechanisms
+ *
+ * @see ::PTP_DELAY_MECH_MASKS
*/
+enum PTP_DELAY_MECH_MASKS
+{
+ PTP_DELAY_MECH_MSK_E2E = ( 1UL << PTP_DELAY_MECH_E2E ), ///< see ::PTP_DELAY_MECH_E2E
+ PTP_DELAY_MECH_MSK_P2P = ( 1UL << PTP_DELAY_MECH_P2P ) ///< see ::PTP_DELAY_MECH_P2P
+};
+
#define PTP_DELAY_MECH_NAME_E2E "E2E"
#define PTP_DELAY_MECH_NAME_P2P "P2P"
+/**
+ * @brief Name strings for the PTP delay mechanisms
+ *
+ * @see ::PTP_DELAY_MECHS
+ */
#define PTP_DELAY_MECH_NAMES \
{ \
PTP_DELAY_MECH_NAME_E2E, \
@@ -5043,16 +8324,17 @@ enum
-#define PTP_CLOCK_ACCURACY_NUM_BIAS 0x20
-
/**
* @brief An enumeration of accuracy classes used with PTP
*
* @note This enumeration does not start at 0 but with a bias
- * specified by PTP_CLOCK_ACCURACY_NUM_BIAS.
+ * specified by ::PTP_CLOCK_ACCURACY_NUM_BIAS.
+ *
+ * @see ::PTP_CLOCK_ACCURACY_STRS
*/
-enum
+enum PTP_CLOCK_ACCURACIES
{
+ PTP_CLOCK_ACCURACY_NUM_BIAS = 0x20,
PTP_CLOCK_ACCURACY_25ns = PTP_CLOCK_ACCURACY_NUM_BIAS,
PTP_CLOCK_ACCURACY_100ns,
PTP_CLOCK_ACCURACY_250ns,
@@ -5083,8 +8365,10 @@ enum
* @brief Name strings for PTP accuracy classes
*
* @note The enumeration does not start at 0 but with a bias
- * specified by PTP_CLOCK_ACCURACY_NUM_BIAS, so this bias needs
+ * specified by ::PTP_CLOCK_ACCURACY_NUM_BIAS, so this bias needs
* to be accounted for when accessing a string table.
+ *
+ * @see ::PTP_CLOCK_ACCURACIES
*/
#define PTP_CLOCK_ACCURACY_STRS \
{ \
@@ -5116,20 +8400,27 @@ enum
/**
* @brief Codes to specify the type of a time source used with PTP
- */
-#define PTP_TIME_SOURCE_ATOMIC_CLOCK 0x10
-#define PTP_TIME_SOURCE_GPS 0x20
-#define PTP_TIME_SOURCE_TERRESTRIAL_RADIO 0x30
-#define PTP_TIME_SOURCE_PTP 0x40
-#define PTP_TIME_SOURCE_NTP 0x50
-#define PTP_TIME_SOURCE_HAND_SET 0x60
-#define PTP_TIME_SOURCE_OTHER 0x90
-#define PTP_TIME_SOURCE_INTERNAL_OSCILLATOR 0xA0
+ *
+ * @see ::PTP_TIME_SOURCE_TABLE
+ */
+enum PTP_TIME_SOURCES
+{
+ PTP_TIME_SOURCE_ATOMIC_CLOCK = 0x10,
+ PTP_TIME_SOURCE_GPS = 0x20,
+ PTP_TIME_SOURCE_TERRESTRIAL_RADIO = 0x30,
+ PTP_TIME_SOURCE_PTP = 0x40,
+ PTP_TIME_SOURCE_NTP = 0x50,
+ PTP_TIME_SOURCE_HAND_SET = 0x60,
+ PTP_TIME_SOURCE_OTHER = 0x90,
+ PTP_TIME_SOURCE_INTERNAL_OSCILLATOR = 0xA0
+};
/**
* @brief A table of PTP time source codes plus associated name strings
+ *
+ * @see ::PTP_TIME_SOURCES
*/
#define PTP_TIME_SOURCE_TABLE \
{ \
@@ -5148,32 +8439,70 @@ enum
/**
* @brief An enumeration of roles which can be taken by a PTP node
*
- * @note A role in this context specifies a certain mode of operation.
+ * A role in this context specifies a certain mode of operation.
+ * Depending on its specification a devices may not be able to take
+ * each of the specified roles.
+ *
+ * @note: A device in MULTICAST_AUTO role can be either master or slave,
+ * so the port state needs to be checked to determine the current
+ * mode of operation.
+ *
+ * @see ::PTP_ROLE_MASKS
+ * @see ::PTP_ROLE_STRS
+ * @see ::PTP_ROLE_STRS_SHORT
+ */
+enum PTP_ROLES
+{
+ PTP_ROLE_MULTICAST_SLAVE, ///< slave in multicast mode
+ PTP_ROLE_UNICAST_SLAVE, ///< slave in unicast mode
+ PTP_ROLE_MULTICAST_MASTER, ///< multicast master
+ PTP_ROLE_UNICAST_MASTER, ///< unicast master
+ PTP_ROLE_MULTICAST_AUTO, ///< multicast master or slave (auto selection)
+ PTP_ROLE_BOTH_MASTER, ///< simultanous multicast and unicast master
+ N_PTP_ROLES ///< number of defined roles
+};
+
+
+/**
+ * @brief Bit mask associated with ::PTP_ROLES
+ *
+ * A role in this context specifies a certain mode of operation.
* Depending on its specification a devices may not be able to take
* each of the specified roles.
+ *
+ * @note: A device in MULTICAST_AUTO role can be either master or slave,
+ * so the port state needs to be checked to determine the current
+ * mode of operation.
+ *
+ * @see ::PTP_ROLES
+ * @see ::get_supp_ptp_role_mask
*/
-enum
+enum PTP_ROLE_MASKS
{
- PTP_ROLE_MULTICAST_SLAVE, //< slave in multicast mode
- PTP_ROLE_UNICAST_SLAVE, //< slave in unicast mode
- PTP_ROLE_MULTICAST_MASTER, //< multicast master
- PTP_ROLE_UNICAST_MASTER, //< unicast master
- PTP_ROLE_MULTICAST_AUTO, //< multicast master or slave (auto selection)
- N_PTP_ROLES //< number of defined roles
+ PTP_ROLE_MSK_MULTICAST_SLAVE = ( 1UL << PTP_ROLE_MULTICAST_SLAVE ), ///< see ::PTP_ROLE_MULTICAST_SLAVE
+ PTP_ROLE_MSK_UNICAST_SLAVE = ( 1UL << PTP_ROLE_UNICAST_SLAVE ), ///< see ::PTP_ROLE_UNICAST_SLAVE
+ PTP_ROLE_MSK_MULTICAST_MASTER = ( 1UL << PTP_ROLE_MULTICAST_MASTER ), ///< see ::PTP_ROLE_MULTICAST_MASTER
+ PTP_ROLE_MSK_UNICAST_MASTER = ( 1UL << PTP_ROLE_UNICAST_MASTER ), ///< see ::PTP_ROLE_UNICAST_MASTER
+ PTP_ROLE_MSK_MULTICAST_AUTO = ( 1UL << PTP_ROLE_MULTICAST_AUTO ), ///< see ::PTP_ROLE_MULTICAST_AUTO
+ PTP_ROLE_MSK_BOTH_MASTER = ( 1UL << PTP_ROLE_BOTH_MASTER ) ///< see ::PTP_ROLE_BOTH_MASTER
};
-#define PTP_ROLE_MSK_MULTICAST_SLAVE ( 1UL << PTP_ROLE_MULTICAST_SLAVE )
-#define PTP_ROLE_MSK_UNICAST_SLAVE ( 1UL << PTP_ROLE_UNICAST_SLAVE )
-#define PTP_ROLE_MSK_MULTICAST_MASTER ( 1UL << PTP_ROLE_MULTICAST_MASTER )
-#define PTP_ROLE_MSK_UNICAST_MASTER ( 1UL << PTP_ROLE_UNICAST_MASTER )
-#define PTP_ROLE_MSK_MULTICAST_AUTO ( 1UL << PTP_ROLE_MULTICAST_AUTO )
-#define PTP_ROLE_MSK_SLAVES ( PTP_ROLE_MSK_MULTICAST_SLAVE | PTP_ROLE_MSK_UNICAST_SLAVE )
-#define PTP_ROLE_MSK_MASTERS ( PTP_ROLE_MSK_MULTICAST_MASTER | PTP_ROLE_MSK_UNICAST_MASTER )
+#define PTP_ROLE_MSK_SLAVES ( PTP_ROLE_MSK_MULTICAST_SLAVE \
+ | PTP_ROLE_MSK_UNICAST_SLAVE \
+ | PTP_ROLE_MSK_MULTICAST_AUTO )
+
+#define PTP_ROLE_MSK_MASTERS ( PTP_ROLE_MSK_MULTICAST_MASTER \
+ | PTP_ROLE_MSK_UNICAST_MASTER \
+ | PTP_ROLE_MSK_MULTICAST_AUTO \
+ | PTP_ROLE_BOTH_MASTER )
/**
* @brief Name strings for defined PTP roles
+ *
+ * @see ::PTP_ROLES
+ * @see ::PTP_ROLE_STRS_SHORT
*/
#define PTP_ROLE_STRS \
{ \
@@ -5181,12 +8510,16 @@ enum
"Unicast Slave", \
"Multicast Master", \
"Unicast Master", \
- "Multicast (Auto)" \
+ "Multicast (Auto)", \
+ "UC+MC Master" \
}
/**
* @brief Short name strings for defined PTP roles
+ *
+ * @see ::PTP_ROLES
+ * @see ::PTP_ROLE_STRS
*/
#define PTP_ROLE_STRS_SHORT \
{ \
@@ -5194,7 +8527,8 @@ enum
"UCS", \
"MCM", \
"UCM", \
- "MC" \
+ "MCA", \
+ "UMM" \
}
@@ -5207,6 +8541,7 @@ enum
typedef struct
{
uint8_t b[8];
+
} PTP_CLOCK_ID;
#define _mbg_swab_ptp_clock_id( _p ) _nop_macro_fnc() // nothing to swap
@@ -5216,9 +8551,6 @@ typedef struct
/**
* @brief A PTP port ID
- *
- * @note This usually consists of a 6 byte MAC address with
- * 2 fixed bytes inserted, or all ones as wildcard.
*/
typedef uint16_t PTP_PORT_ID;
@@ -5231,13 +8563,17 @@ typedef uint16_t PTP_PORT_ID;
* @brief An enumeration of time scales used with PTP
*
* @note The standard time scale used by PTP is TAI, which is a linear time scale.
- * The protocol provides a UTC offset to be able to convert TAI to compute UTC, which
- * can observe leap seconds. For the arbitrary time scale the UTC offset is unspecified.
+ * The protocol provides a %UTC offset to be able to convert TAI to compute %UTC, which
+ * can observe leap seconds. For the arbitrary time scale the %UTC offset is unspecified,
+ * so arbitrary time can be %UTC, or something else.
+ *
+ * @see ::PTP_TIMESCALE_NAMES
+ * @see ::PTP_TIMESCALE_NAMES_SHORT
*/
-enum
+enum PTP_TIME_SCALES
{
- PTP_TIMESCALE_PTP, /* default */
- PTP_TIMESCALE_ARB,
+ PTP_TIMESCALE_PTP, ///< PTP default, TAI
+ PTP_TIMESCALE_ARB, ///< arbitrary time scale, maybe %UTC
N_PTP_TIMESCALE
};
@@ -5257,6 +8593,9 @@ enum
/**
* @brief A table of name strings for the PTP time scales
+ *
+ * @see ::PTP_TIME_SCALES
+ * @see ::PTP_TIMESCALE_NAMES_SHORT
*/
#define PTP_TIMESCALE_NAMES \
{ \
@@ -5266,6 +8605,9 @@ enum
/**
* @brief A table of short name strings for the PTP time scales
+ *
+ * @see ::PTP_TIME_SCALES
+ * @see ::PTP_TIMESCALE_NAMES
*/
#define PTP_TIMESCALE_NAMES_SHORT \
{ \
@@ -5280,34 +8622,36 @@ enum
*/
typedef struct
{
- //##++++ Do we need a port identifier ??
- uint16_t nw_prot; /**< one of the enumerated protocols (@see N_PTP_NW_PROT) */
- uint8_t ptp_prot_version; /**< PTP protocol version, 1, or 2, usually 2 for v2 */
- uint8_t port_state; /**< one of the enumerated port states (@see N_PTP_PORT_STATE ) */
- uint32_t flags; /**< bit masks as defined below */
- NANO_TIME offset; /**< estimated time offset from the upstream time source */
+ uint16_t nw_prot; ///< one of the enumerated protocols, see ::PTP_NW_PROTS
+ uint8_t ptp_prot_version; ///< PTP protocol version, 1, or 2, usually 2 for v2
+ uint8_t port_state; ///< one of the enumerated port states, see ::PTP_PORT_STATES
+ uint32_t flags; ///< see ::PTP_STATE_FLAGS
+ NANO_TIME offset; ///< estimated time offset from the upstream time source
NANO_TIME path_delay;
NANO_TIME mean_path_delay;
NANO_TIME delay_asymmetry;
- PTP_CLOCK_ID gm_id; /**< identifier ot the upstream time source */
+ PTP_CLOCK_ID gm_id; ///< identifier ot the upstream time source
uint16_t clock_offset_scaled_log_variance;
uint8_t clock_class;
- uint8_t clock_accuracy; /**< one of the enumerated accuracy class codes (@see N_PTP_CLOCK_ACCURACY) */
+ uint8_t clock_accuracy; ///< see ::PTP_CLOCK_ACCURACIES
- uint32_t reserved_1; /**< reserved, currently always 0 */
- uint32_t reserved_2; /**< reserved, currently always 0 */
+ uint32_t reserved_1; ///< reserved, currently always 0
+ uint32_t reserved_2; ///< reserved, currently always 0
- uint8_t domain_number; /**< the PTP clock domain number, 0:3 */
- uint8_t time_source; /**< one of the defined codes PTP_TIME_SOURCE_... */
- uint8_t delay_mech; /**< PTP_DELAY_MECH_BIT_E2E or PTP_DELAY_MECH_BIT_P2P */
+ uint8_t domain_number; ///< the PTP clock domain number, 0:3
+ uint8_t time_source; ///< see ::PTP_TIME_SOURCES
+ uint8_t delay_mech; ///< see ::PTP_DELAY_MECHS
int8_t log_delay_req_intv;
- int16_t utc_offset; /**< UTC offset observed against TAI */
- DAC_VAL osc_dac_cal; /**< disciplination value of the oscillator */
+ int16_t utc_offset; ///< %UTC offset observed against TAI
+ DAC_VAL osc_dac_cal; ///< disciplination value of the oscillator
+
+ uint8_t parent_clock_class; ///< clock class of the parent node
+ uint8_t parent_clock_accuracy; ///< clock accuracy of the parent node, see ::PTP_CLOCK_ACCURACIES
- uint32_t reserved_3; /**< reserved, currently always 0 */
+ uint16_t reserved_3; ///< reserved, currently always 0
} PTP_STATE;
@@ -5325,30 +8669,44 @@ typedef struct
_mbg_swab32( &(_p)->reserved_2 ); \
_mbg_swab16( &(_p)->utc_offset ); \
_mbg_swab_dac_val( &(_p)->osc_dac_cal ); \
- _mbg_swab32( &(_p)->reserved_3 ); \
+ _mbg_swab16( &(_p)->reserved_3 ); \
}
/**
- * @brief Flag bits used with PTP_STATE::flags
- */
-enum
-{
- PTP_FLAG_BIT_SLAVE_ONLY, /**< the port can only be slave */
- PTP_FLAG_BIT_IS_SLAVE, /**< the port is currently slave */
- PTP_FLAG_BIT_TIMESCALE_IS_PTP, /**< the timescale is PTP standard, not arbitrary */
- PTP_FLAG_BIT_LS_ANN, /**< a leap second is being announced */
- PTP_FLAG_BIT_LS_ANN_NEG, /**< the announced leap second is negative */
- PTP_FLAG_BIT_IS_UNICAST, /**< the port currently operates in unicast mode */
- N_PTP_FLAG_BIT /**< the number of defined flag bits */
+ * @brief Flags bits used with PTP_STATE::flags
+ *
+ * @see ::PTP_STATE_FLAG_MASKS
+ */
+enum PTP_STATE_FLAGS
+{
+ PTP_FLAG_SLAVE_ONLY, ///< the port can only be slave
+ PTP_FLAG_IS_SLAVE, ///< the port is currently slave
+ PTP_FLAG_TIMESCALE_IS_PTP, ///< the timescale is PTP standard, not arbitrary
+ PTP_FLAG_LS_ANN, ///< a leap second is being announced
+ PTP_FLAG_LS_ANN_NEG, ///< the announced leap second is negative
+ PTP_FLAG_IS_UNICAST, ///< the port currently operates in unicast mode
+ PTP_FLAG_UTC_VALID, ///< %UTC parameters are valid
+ PTP_FLAG_ONE_STEP, ///< One-Step Clock active
+ N_PTP_STATE_FLAGS ///< the number of defined flag bits
};
-#define PTP_FLAG_MSK_SLAVE_ONLY ( 1UL << PTP_FLAG_BIT_SLAVE_ONLY )
-#define PTP_FLAG_MSK_IS_SLAVE ( 1UL << PTP_FLAG_BIT_IS_SLAVE )
-#define PTP_FLAG_MSK_TIMESCALE_IS_PTP ( 1UL << PTP_FLAG_BIT_TIMESCALE_IS_PTP )
-#define PTP_FLAG_MSK_LS_ANN ( 1UL << PTP_FLAG_BIT_LS_ANN )
-#define PTP_FLAG_MSK_LS_ANN_NEG ( 1UL << PTP_FLAG_BIT_LS_ANN_NEG )
-#define PTP_FLAG_MSK_IS_UNICAST ( 1UL << PTP_FLAG_BIT_IS_UNICAST )
+/**
+ * @brief Flags masks used with PTP_STATE::flags
+ *
+ * @see ::PTP_STATE_FLAGS
+ */
+enum PTP_STATE_FLAG_MASKS
+{
+ PTP_FLAG_MSK_SLAVE_ONLY = ( 1UL << PTP_FLAG_SLAVE_ONLY ), ///< see ::PTP_FLAG_SLAVE_ONLY
+ PTP_FLAG_MSK_IS_SLAVE = ( 1UL << PTP_FLAG_IS_SLAVE ), ///< see ::PTP_FLAG_IS_SLAVE
+ PTP_FLAG_MSK_TIMESCALE_IS_PTP = ( 1UL << PTP_FLAG_TIMESCALE_IS_PTP ), ///< see ::PTP_FLAG_TIMESCALE_IS_PTP
+ PTP_FLAG_MSK_LS_ANN = ( 1UL << PTP_FLAG_LS_ANN ), ///< see ::PTP_FLAG_LS_ANN
+ PTP_FLAG_MSK_LS_ANN_NEG = ( 1UL << PTP_FLAG_LS_ANN_NEG ), ///< see ::PTP_FLAG_LS_ANN_NEG
+ PTP_FLAG_MSK_IS_UNICAST = ( 1UL << PTP_FLAG_IS_UNICAST ), ///< see ::PTP_FLAG_IS_UNICAST
+ PTP_FLAG_MSK_UTC_VALID = ( 1UL << PTP_FLAG_UTC_VALID ), ///< see ::PTP_FLAG_UTC_VALID
+ PTP_FLAG_MSK_ONE_STEP = ( 1UL << PTP_FLAG_ONE_STEP ) ///< see ::PTP_FLAG_ONE_STEP
+};
@@ -5357,72 +8715,83 @@ enum
*/
typedef struct
{
- //##++++ Do we need a port identifier ??
- uint16_t nw_prot; /**< one of the enumerated and supported protocols (@see N_PTP_NW_PROT) */
- uint8_t profile; /**< PTP profile, currently only 0 = default */
- uint8_t domain_number; /**< the PTP clock domain number, 0:3 */
+ uint16_t nw_prot; ///< see ::PTP_NW_PROTS
+ uint8_t selected_presets; ///< selected PTP presets, see ::PTP_PRESETS
+ uint8_t domain_number; ///< the PTP clock domain number, 0:3
- uint8_t delay_mech; /**< PTP_DELAY_MECH_BIT_E2E or PTP_DELAY_MECH_BIT_P2P, if supported */
- uint8_t ptp_role; /**< one of the enumerated PTP roles (@see N_PTP_ROLES) */
- uint8_t priority_1; /**< priority 1 */
- uint8_t priority_2; /**< priority 2 */
+ uint8_t delay_mech; ///< see ::PTP_DELAY_MECHS
+ uint8_t ptp_role; ///< one of the supported PTP roles, see ::PTP_ROLES
+ uint8_t priority_1; ///< priority 1
+ uint8_t priority_2; ///< priority 2
uint8_t dflt_clk_class_unsync_cold; // 6:255
uint8_t dflt_clk_class_unsync_warm; // 6:255
uint8_t dflt_clk_class_sync_cold; // 6:255
uint8_t dflt_clk_class_sync_warm; // 6:255
- uint8_t reserved_1; /**< reserved, currently always 0 */
- uint8_t reserved_2; /**< reserved, currently always 0 */
- int16_t sync_intv; /**< log2 of the sync interval [s] */
+ uint8_t ann_rcpt_timeout; ///< announce msg. receipt timeout, see ::PTP_ANN_RCPT_TIMEOUT_LIMITS
+ uint8_t opt_ext; ///< optional configuration extension, see ::PTP_OPT_EXTS
+ int16_t sync_intv; ///< log2 of the sync interval [s]
- int16_t ann_intv; /**< log2 of the announce interval [s] */
- int16_t delay_req_intv; /**< log2 of the delay request interval [s] */
+ int16_t ann_intv; ///< log2 of the announce interval [s]
+ int16_t delay_req_intv; ///< log2 of the delay request interval [s]
- uint32_t upper_bound; /**< sync state set to false if above this limit [ns] */
- uint32_t lower_bound; /**< sync state set to true if below this limit [ns] */
+ uint32_t upper_bound; ///< sync state set to false if above this limit [ns]
+ uint32_t lower_bound; ///< sync state set to true if below this limit [ns]
- uint32_t reserved_3; /**< reserved, currently always 0 */
- uint32_t flags; /**< bit masks as defined below */
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t flags; ///< see ::PTP_CFG_FLAG_MASKS
} PTP_CFG_SETTINGS;
-#define _mbg_swab_ptp_cfg_settings( _p ) \
-{ \
- _mbg_swab16( &(_p)->nw_prot ); \
- _mbg_swab16( &(_p)->sync_intv ); \
- _mbg_swab16( &(_p)->ann_intv ); \
- _mbg_swab16( &(_p)->delay_req_intv ); \
- _mbg_swab32( &(_p)->upper_bound ); \
- _mbg_swab32( &(_p)->lower_bound ); \
- _mbg_swab32( &(_p)->reserved_3 ); \
- _mbg_swab32( &(_p)->flags ); \
+#define _mbg_swab_ptp_cfg_settings( _p ) \
+{ \
+ _mbg_swab16( &(_p)->nw_prot ); \
+ _mbg_swab16( &(_p)->sync_intv ); \
+ _mbg_swab16( &(_p)->ann_intv ); \
+ _mbg_swab16( &(_p)->delay_req_intv ); \
+ _mbg_swab32( &(_p)->upper_bound ); \
+ _mbg_swab32( &(_p)->lower_bound ); \
+ _mbg_swab32( &(_p)->reserved ); \
+ _mbg_swab32( &(_p)->flags ); \
}
/**
+ * @brief Possible values for PTP_CFG_SETTINGS::ann_rcpt_timeout
+ */
+enum PTP_ANN_RCPT_TIMEOUT_LIMITS
+{
+ PTP_ANN_RCPT_TIMEOUT_MIN = 2,
+ PTP_ANN_RCPT_TIMEOUT_MAX = 255,
+ DEFAULT_PTP_ANN_RCPT_TIMEOUT = 3
+};
+
+
+
+/**
* @brief A structure to used to query the current configuration and capabilities of a PTP port
*/
typedef struct
{
- PTP_CFG_SETTINGS settings; /**< the current configuration */
+ PTP_CFG_SETTINGS settings; ///< the current configuration
- uint8_t ptp_proto_version; /**< PTP protocol version, 1, or 2, usually 2 for v2 */
- uint8_t reserved_1; /**< reserved, currently always 0 */
- uint16_t reserved_2; /**< reserved, currently always 0 */
+ uint8_t ptp_proto_version; ///< PTP protocol version, 1, or 2, usually 2 for v2
+ uint8_t reserved_1; ///< reserved, currently always 0
+ uint16_t reserved_2; ///< reserved, currently always 0
- int16_t sync_intv_min; /**< log2 of minimum sync interval [s] */
- int16_t sync_intv_max; /**< log2 of maximum sync interval [s] */
- int16_t ann_intv_min; /**< log2 of minimum announce interval [s] */
- int16_t ann_intv_max; /**< log2 of maximum announce interval [s] */
- int16_t delay_req_intv_min; /**< log2 of minimum delay request interval [s] */
- int16_t delay_req_intv_max; /**< log2 of maximum delay request interval [s] */
+ int16_t sync_intv_min; ///< log2 of minimum sync interval [s]
+ int16_t sync_intv_max; ///< log2 of maximum sync interval [s]
+ int16_t ann_intv_min; ///< log2 of minimum announce interval [s]
+ int16_t ann_intv_max; ///< log2 of maximum announce interval [s]
+ int16_t delay_req_intv_min; ///< log2 of minimum delay request interval [s]
+ int16_t delay_req_intv_max; ///< log2 of maximum delay request interval [s]
- uint32_t supp_flags; /**< a bit mask of supported features (see below) */
- uint32_t supp_nw_prot; /**< a bit mask of supported network protocols */
- uint32_t supp_profiles; /**< a bit mask of supported profiles */
- uint32_t supp_delay_mech; /**< a bit mask of supported delay mechanisms */
+ uint32_t supp_flags; ///< a bit mask of supported features, see ::PTP_CFG_FLAG_MASKS
+ uint32_t supp_nw_prot; ///< a bit mask of supported network protocols, see ::PTP_NW_PROT_MASKS
+ uint32_t supp_opt_ext; ///< a bit mask of supported optional extensions, see ::PTP_OPT_EXT_MASKS
+ uint32_t supp_delay_mech; ///< a bit mask of supported delay mechanisms, see ::PTP_DELAY_MECH_MASKS
} PTP_CFG_INFO;
@@ -5438,82 +8807,165 @@ typedef struct
_mbg_swab16( &(_p)->delay_req_intv_max ); \
_mbg_swab32( &(_p)->supp_flags ); \
_mbg_swab32( &(_p)->supp_nw_prot ); \
- _mbg_swab32( &(_p)->supp_profiles ); \
+ _mbg_swab32( &(_p)->supp_opt_ext ); \
_mbg_swab32( &(_p)->supp_delay_mech ); \
}
/**
- * @brief Flags used with PTP_CFG_SETTINGS::flags and PTP_CFG_INFO::supp_flags
- */
-enum
-{
- PTP_CFG_BIT_TIME_SCALE_IS_PTP, /**< time scale is PTP/TAI, else arbitrary */
- PTP_CFG_BIT_V1_HW_COMPAT, /**< maybe required for certain NIC chips, not used by Meinberg */
- PTP_CFG_BIT_CAN_BE_UNICAST_SLAVE, /**< the PTP port can take the role of a unicast slave */
- PTP_CFG_BIT_CAN_BE_MULTICAST_MASTER, /**< the PTP port can take the role of a multicast master */
- PTP_CFG_BIT_CAN_BE_UNICAST_MASTER, /**< the PTP port can take the role of a unicast master */
- PTP_CFG_BIT_CAN_BE_MULTICAST_AUTO, /**< the PTP port can automatically become multicast master or slave */
- N_PTP_CFG_BIT /**< the number of defined bits */
+ * @brief Flags bits used with PTP configuration
+ *
+ * Flags labeled [R/-] can only be used with ::PTP_CFG_INFO::supp_flags
+ * to indicate that the associated feature is supported in general.
+ *
+ * If a flag labeled [R/W] is set in ::PTP_CFG_INFO::supp_flags then
+ * this flag can also be used with ::PTP_CFG_SETTINGS::flags to control
+ * the associated feature.
+ *
+ * @note Originally, all devices supported the multicast slave role, so
+ * there was no extra flag to indicate this. However, some newer devices
+ * may not support the multicast slave role, so two new flags have been
+ * introduced to cope with this:
+ * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is set then a different flag
+ * ::PTP_CFG_CAN_BE_MULTICAST_SLAVE needs to be checked to tell if
+ * the multicast slave role is supported, or not.
+ * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is not set then the device
+ * definitely supports the multicast slave role.
+ *
+ * @see ::PTP_CFG_FLAG_MASKS
+ */
+enum PTP_CFG_FLAGS
+{
+ PTP_CFG_TIME_SCALE_IS_PTP, ///< [R/W] time scale is PTP/TAI, else arbitrary
+ PTP_CFG_V1_HW_COMPAT, ///< [R/W] maybe required for certain NIC chips, not used by Meinberg
+ PTP_CFG_CAN_BE_UNICAST_SLAVE, ///< [R/-] supports unicast slave role, see ::PTP_ROLE_UNICAST_SLAVE
+ PTP_CFG_CAN_BE_MULTICAST_MASTER, ///< [R/-] supports multicast master role, see ::PTP_ROLE_MULTICAST_MASTER
+ PTP_CFG_CAN_BE_UNICAST_MASTER, ///< [R/-] supports unicast master, see ::PTP_ROLE_UNICAST_MASTER
+ PTP_CFG_CAN_BE_MULTICAST_AUTO, ///< [R/-] can automatically become multicast master or slave, see ::PTP_CFG_CAN_BE_MULTICAST_AUTO
+ PTP_CFG_SUPP_UTC_VALID, ///< [R/-] ::PTP_FLAG_UTC_VALID bit in ::PTP_STATE::flags is supported
+ PTP_CFG_CAN_BE_BOTH_MASTER, ///< [R/-] supports unicast and multicast master role at the same time, see ::PTP_CFG_CAN_BE_BOTH_MASTER
+
+ PTP_CFG_HYBRID_MASTER, ///< [R/W] supports hybrid mode in master roles
+ PTP_CFG_HYBRID_SLAVE, ///< [R/W] supports hybrid mode in slave roles
+ PTP_CFG_ONE_STEP_MASTER, ///< [R/W] supports one-step mode in master roles
+ PTP_CFG_MNGMNT_MSGS_DISB, ///< [R/W] supports disabling of PTP management messages
+ PTP_CFG_SUPP_MCAST_SLAVE_FLAG, ///< [R/-] indicates that ::PTP_CFG_CAN_BE_MULTICAST_SLAVE flag is supported and can be checked
+ PTP_CFG_CAN_BE_MULTICAST_SLAVE, ///< [R/-] if ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG bit set, indicates if multicast slave role is supported
+ PTP_CFG_ONE_STEP_L2, ///< [R/-] supports the combination of One-Step and Layer2 mode
+ PTP_CFG_ONE_STEP_P2P, ///< [R/-] supports the combination of One-Step and P2P Delay Mechanism
+
+ N_PTP_CFG_FLAGS ///< the number of defined flags
};
-#define PTP_CFG_MSK_TIME_SCALE_IS_PTP ( 1UL << PTP_CFG_BIT_TIME_SCALE_IS_PTP )
-#define PTP_CFG_MSK_V1_HW_COMPAT ( 1UL << PTP_CFG_BIT_V1_HW_COMPAT )
-#define PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE ( 1UL << PTP_CFG_BIT_CAN_BE_UNICAST_SLAVE )
-#define PTP_CFG_MSK_CAN_BE_MULTICAST_MASTER ( 1UL << PTP_CFG_BIT_CAN_BE_MULTICAST_MASTER )
-#define PTP_CFG_MSK_CAN_BE_UNICAST_MASTER ( 1UL << PTP_CFG_BIT_CAN_BE_UNICAST_MASTER )
-#define PTP_CFG_MSK_CAN_BE_MULTICAST_AUTO ( 1UL << PTP_CFG_BIT_CAN_BE_MULTICAST_AUTO )
+
+/**
+ * @brief Bit masks used with ::PTP_CFG_INFO::supp_flags and ::PTP_CFG_SETTINGS::flags
+ *
+ * @see ::PTP_CFG_FLAGS
+ */
+enum PTP_CFG_FLAG_MASKS
+{
+ PTP_CFG_MSK_TIME_SCALE_IS_PTP = ( 1UL << PTP_CFG_TIME_SCALE_IS_PTP ), ///< see ::PTP_CFG_TIME_SCALE_IS_PTP
+ PTP_CFG_MSK_V1_HW_COMPAT = ( 1UL << PTP_CFG_V1_HW_COMPAT ), ///< see ::PTP_CFG_V1_HW_COMPAT
+ PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE = ( 1UL << PTP_CFG_CAN_BE_UNICAST_SLAVE ), ///< see ::PTP_CFG_CAN_BE_UNICAST_SLAVE
+ PTP_CFG_MSK_CAN_BE_MULTICAST_MASTER = ( 1UL << PTP_CFG_CAN_BE_MULTICAST_MASTER ), ///< see ::PTP_CFG_CAN_BE_MULTICAST_MASTER
+ PTP_CFG_MSK_CAN_BE_UNICAST_MASTER = ( 1UL << PTP_CFG_CAN_BE_UNICAST_MASTER ), ///< see ::PTP_CFG_CAN_BE_UNICAST_MASTER
+ PTP_CFG_MSK_CAN_BE_MULTICAST_AUTO = ( 1UL << PTP_CFG_CAN_BE_MULTICAST_AUTO ), ///< see ::PTP_CFG_CAN_BE_MULTICAST_AUTO
+ PTP_CFG_MSK_SUPP_UTC_VALID = ( 1UL << PTP_CFG_SUPP_UTC_VALID ), ///< see ::PTP_CFG_SUPP_UTC_VALID
+ PTP_CFG_MSK_CAN_BE_BOTH_MASTER = ( 1UL << PTP_CFG_CAN_BE_BOTH_MASTER ), ///< see ::PTP_CFG_CAN_BE_BOTH_MASTER
+
+ PTP_CFG_MSK_HYBRID_MASTER = ( 1UL << PTP_CFG_HYBRID_MASTER ), ///< see ::PTP_CFG_HYBRID_MASTER
+ PTP_CFG_MSK_HYBRID_SLAVE = ( 1UL << PTP_CFG_HYBRID_SLAVE ), ///< see ::PTP_CFG_HYBRID_SLAVE
+ PTP_CFG_MSK_ONE_STEP_MASTER = ( 1UL << PTP_CFG_ONE_STEP_MASTER ), ///< see ::PTP_CFG_ONE_STEP_MASTER
+ PTP_CFG_MSK_MNGMNT_MSGS_DISB = ( 1UL << PTP_CFG_MNGMNT_MSGS_DISB ), ///< see ::PTP_CFG_MNGMNT_MSGS_DISB
+ PTP_CFG_MSK_SUPP_MCAST_SLAVE_FLAG = ( 1UL << PTP_CFG_SUPP_MCAST_SLAVE_FLAG ), ///< see ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG
+ PTP_CFG_MSK_CAN_BE_MULTICAST_SLAVE = ( 1UL << PTP_CFG_CAN_BE_MULTICAST_SLAVE ), ///< see ::PTP_CFG_CAN_BE_MULTICAST_SLAVE
+ PTP_CFG_MSK_ONE_STEP_L2 = ( 1UL << PTP_CFG_ONE_STEP_L2 ), ///< see ::PTP_CFG_ONE_STEP_L2
+ PTP_CFG_MSK_ONE_STEP_P2P = ( 1UL << PTP_CFG_ONE_STEP_P2P ), ///< see ::PTP_CFG_ONE_STEP_P2P
+};
-/** @brief A bit mask of the role bits within the flag bits */
-#define PTP_CFG_MSK_SUPPORT_PTP_ROLES ( PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE | \
- PTP_CFG_MSK_CAN_BE_MULTICAST_MASTER | \
- PTP_CFG_MSK_CAN_BE_UNICAST_MASTER | \
- PTP_CFG_MSK_CAN_BE_MULTICAST_AUTO )
/** @brief A bit mask of the unicast role bits within the flag bits */
#define PTP_CFG_MSK_SUPPORT_PTP_UNICAST ( PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE | \
PTP_CFG_MSK_CAN_BE_UNICAST_MASTER )
+
+
/**
- * @brief Derive a "supported PTP roles" bit mask from PTP_CFG_INFO::supp_flags
+ * @brief Known optional PTP protocol extensions, see ::PTP_CFG_SETTINGS::opt_ext
*
- * There's no explicite flag to indicate that the role of a multicast slave
- * is supported, since this role is always supported. The sequence of flags
- * indicating that a specific optional role is supported matches the enumerated
- * roles above, but don't start at bit 0. So we compine the optional flag bits
- * with the LSB always set for the implicite multicast slave role to yield
- * a bit mask which according to the enumerated roles.
+ * @see ::PTP_OPT_EXT_MASKS
*/
-#define _get_supp_ptp_role_idx_msk( _f ) \
- ( 1UL | ( ( (_f) & PTP_CFG_MSK_SUPPORT_PTP_ROLES ) >> ( PTP_CFG_BIT_CAN_BE_UNICAST_SLAVE - 1 ) ) )
+enum PTP_OPT_EXTS
+{
+ PTP_OPT_EXT_NONE, ///< no extension used
+ PTP_OPT_EXT_POWER, ///< IEEE C37.238 profile extension
+ PTP_OPT_EXT_TELECOM, ///< ITU-T G.8265.1 profile extension
+ N_PTP_OPT_EXT ///< number of known optional extension
+};
/**
- * @brief Flags used with PTP_CFG_SETTINGS::profile and PTP_CFG_INFO::supp_profiles
+ * @brief Flag masks used with ::PTP_CFG_INFO::supp_opt_ext
+ *
+ * @see ::PTP_OPT_EXTS
*/
-enum
+enum PTP_OPT_EXT_MASKS
{
- PTP_PROFILE_CUSTOM, /**< customizable, always supported */
- PTP_PROFILE_DFLT_E2E, /**< pure IEEE1588-2008 (PTPv2) with E2E */
- PTP_PROFILE_DFLT_P2P, /**< pure IEEE1588-2008 (PTPv2) with P2P */
- PTP_PROFILE_POWER, /**< IEEE C37.238 profile extension */
- PTP_PROFILE_TELECOM, /**< ITU-T G.8265.1 profile extension */
- N_PTP_PROFILES /**< number of supported profiles */
+ PTP_MSK_OPT_EXT_NONE = ( 1UL << PTP_OPT_EXT_NONE ), ///< this is actually not used, see ::PTP_OPT_EXT_NONE
+ PTP_MSK_OPT_EXT_POWER = ( 1UL << PTP_OPT_EXT_POWER ), ///< see ::PTP_OPT_EXT_POWER
+ PTP_MSK_OPT_EXT_TELECOM = ( 1UL << PTP_OPT_EXT_TELECOM ) ///< see ::PTP_OPT_EXT_TELECOM
};
-#define PTP_MSK_PROFILE_DEFAULT ( 1UL << PTP_PROFILE_DEFAULT )
-#define PTP_MSK_PROFILE_POWER ( 1UL << PTP_PROFILE_POWER )
-#define PTP_MSK_PROFILE_TELECOM ( 1UL << PTP_PROFILE_TELECOM )
/**
- * @brief Name strings for defined PTP profiles
+ * @brief Enumeration of PTP cfg presets used with ::PTP_CFG_SETTINGS::selected_presets
+ *
+ * This can be used by configuration programs to determine
+ * the last recently selected presets.
+ *
+ * @see ::PTP_PRESETS_STRS
+ * @see ::PTP_PRESETS_MASKS
+ */
+enum PTP_PRESETS
+{
+ PTP_PRESETS_CUSTOM, ///< customizable, always supported
+ PTP_PRESETS_DFLT_E2E, ///< pure IEEE1588-2008 (PTPv2) with E2E
+ PTP_PRESETS_DFLT_P2P, ///< pure IEEE1588-2008 (PTPv2) with P2P
+ PTP_PRESETS_POWER, ///< IEEE C37.238 profile extension, only if ::PTP_MSK_OPT_EXT_POWER is set
+ PTP_PRESETS_TELECOM, ///< ITU-T G.8265.1 profile extension, only if ::PTP_MSK_OPT_EXT_TELECOM is set
+ N_PTP_PRESETS ///< number of supported profiles
+};
+
+
+/**
+ * @brief Flag masks used with ::PTP_CFG_INFO::supp_opt_ext
+ *
+ * @see ::PTP_PRESETS
*/
-#define PTP_PROFILE_STRS \
+enum PTP_PRESETS_MASKS
+{
+ PTP_MSK_PRESETS_CUSTOM = ( 1UL << PTP_PRESETS_CUSTOM ), ///< see ::PTP_PRESETS_CUSTOM
+ PTP_MSK_PRESETS_DFLT_E2E = ( 1UL << PTP_PRESETS_DFLT_E2E ), ///< see ::PTP_PRESETS_DFLT_E2E
+ PTP_MSK_PRESETS_DFLT_P2P = ( 1UL << PTP_PRESETS_DFLT_P2P ), ///< see ::PTP_PRESETS_DFLT_P2P
+ PTP_MSK_PRESETS_POWER = ( 1UL << PTP_PRESETS_POWER ), ///< see ::PTP_PRESETS_POWER
+ PTP_MSK_PRESETS_TELECOM = ( 1UL << PTP_PRESETS_TELECOM ) ///< see ::PTP_PRESETS_TELECOM
+};
+
+
+/**
+ * @brief Name strings for defined PTP presets
+ *
+ * @see ::PTP_PRESETS
+ */
+#define PTP_PRESETS_STRS \
{ \
- "Default", \
+ "Custom", \
+ "Default E2E", \
+ "Default P2P", \
"Power", \
"Telecom" \
}
@@ -5528,23 +8980,23 @@ enum
typedef struct
{
- uint32_t network_incaccuracy; /**< Pre-defined network inaccuracy from master in [ns] */
- uint8_t grandmaster_id; /**< [PTP_POWER_PROFILE_GM_ID_MIN..PTP_POWER_PROFILE_GM_ID_MAX] */
+ uint32_t network_incaccuracy; ///< Pre-defined network inaccuracy from master in [ns]
+ uint8_t grandmaster_id; ///< [::PTP_POWER_PROFILE_GM_ID_MIN..::PTP_POWER_PROFILE_GM_ID_MAX]
uint8_t reserved_1;
uint16_t reserved_2;
+ TZDL tzdl;
} PTP_POWER_PROFILE_CFG;
-
-
-/**
- * @brief A host's fully qualified domain name (FQDN), or a numeric IP address string
- *
- * In theory each single component (host name, domain name, top level domain name)
- * of a FQDN can have up to 63 characters, but the overall length is limited to
- * 255 characters. We specify one more character for the trailing 0.
- */
-typedef char MBG_HOSTNAME[256];
+#define _mbg_swab_ptp_power_profile_cfg( _p ) \
+{ \
+ _mbg_swab32( &(_p)->network_incaccuracy ); \
+ _mbg_swab8( &(_p)->grandmaster_id ); \
+ _mbg_swab8( &(_p)->reserved_1 ); \
+ _mbg_swab16( &(_p)->reserved_2 ); \
+ _mbg_swab_tzdl( &(_p)->tzdl ); \
+ _mbg_swab32( &(_p)->flags ); \
+}
/**
@@ -5552,16 +9004,16 @@ typedef char MBG_HOSTNAME[256];
*/
typedef struct
{
- uint16_t n_supp_master; /**< number of unicast masters which can be specified */
- int16_t sync_intv_min; /**< log2 of minimum sync interval [s] */
- int16_t sync_intv_max; /**< log2 of maximum sync interval [s] */
- int16_t ann_intv_min; /**< log2 of minimum announce interval [s] */
- int16_t ann_intv_max; /**< log2 of maximum announce interval [s] */
- int16_t delay_req_intv_min; /**< log2 of minimum delay request interval [s] */
- int16_t delay_req_intv_max; /**< log2 of maximum delay request interval [s] */
- uint16_t reserved_0; /**< reserved, currently always 0 */
- uint32_t supp_flags; /**< a bit mask indicating which flags are supported */
- uint32_t reserved_1; /**< reserved, currently always 0 */
+ uint16_t n_supp_master; ///< number of unicast masters which can be specified
+ int16_t sync_intv_min; ///< log2 of minimum sync interval [s]
+ int16_t sync_intv_max; ///< log2 of maximum sync interval [s]
+ int16_t ann_intv_min; ///< log2 of minimum announce interval [s]
+ int16_t ann_intv_max; ///< log2 of maximum announce interval [s]
+ int16_t delay_req_intv_min; ///< log2 of minimum delay request interval [s]
+ int16_t delay_req_intv_max; ///< log2 of maximum delay request interval [s]
+ uint16_t reserved_0; ///< reserved, currently always 0
+ uint32_t supp_flags; ///< a bit mask indicating which flags are supported
+ uint32_t reserved_1; ///< reserved, currently always 0
} PTP_UC_MASTER_CFG_LIMITS;
@@ -5581,26 +9033,29 @@ typedef struct
/**
- * @brief Specification of unicast masters
+ * @brief Configuration settings specifiying how to query a PTP unicast master
*
* This structure is used on a unicast slave to specify the settings of
* a unicast master polled by the slave. The number of unicast masters
* which can be specified depends on the capabilities of the slave device
- * and is returned in PTP_UC_MASTER_CFG_LIMITS::n_supp_master.
+ * and is returned in ::PTP_UC_MASTER_CFG_LIMITS::n_supp_master.
+ *
+ * The structure ::PTP_UC_MASTER_SETTINGS_IDX should be sent to the device
+ * to save the configuration.
*/
typedef struct
{
- MBG_HOSTNAME gm_host; /**< grandmaster's hostname or IP address */
- PTP_CLOCK_ID gm_clock_id; /**< use clock ID of master port, or PTP_CLOCK_ID_WILDCARD */
- PTP_PORT_ID gm_port_id; /**< use target port ID of master port (e.g. 135) or PTP_PORT_ID_WILDCARD */
- int16_t sync_intv; /**< sync interval [log2 s] */
- int16_t ann_intv; /**< announce interval [log2 s] */
- int16_t delay_req_intv; /**< delay request interval [log2 s]*/
- int32_t fix_offset; /**< constant time offset to be compensated [ns] */
- uint16_t message_duration; /**< time period until master stops sending messages [s] */
- uint16_t reserved_0; /**< reserved, currently always 0 */
- uint32_t reserved_1; /**< reserved, currently always 0 */
- uint32_t flags; /**< reserved, currently always 0 */
+ MBG_HOSTNAME gm_host; ///< grandmaster's hostname or IP address
+ PTP_CLOCK_ID gm_clock_id; ///< use clock ID of master port, or ::PTP_CLOCK_ID_WILDCARD
+ PTP_PORT_ID gm_port_id; ///< use target port ID of master port (e.g. 135) or ::PTP_PORT_ID_WILDCARD
+ int16_t sync_intv; ///< sync interval [log2 s]
+ int16_t ann_intv; ///< announce interval [log2 s]
+ int16_t delay_req_intv; ///< delay request interval [log2 s]
+ int32_t fix_offset; ///< constant time offset to be compensated [ns]
+ uint16_t message_duration; ///< time period until master stops sending messages [s]
+ uint16_t reserved_0; ///< reserved, currently always 0
+ uint32_t reserved_1; ///< reserved, currently always 0
+ uint32_t flags; ///< reserved, currently always 0
} PTP_UC_MASTER_SETTINGS;
@@ -5620,12 +9075,31 @@ typedef struct
/**
- * @brief Specification of a certain unicast master
+ * @brief Unicast PTP master message duration limits
+ *
+ * Each unicast PTP master sends messages to a unicast slave only
+ * for a given interval as requested by the particular slave, which
+ * is called message duration.
+ * These symbols define the minimum and maximum message duration
+ * configured on a slave for a specific unicast master, i.e. for
+ * PTP_UC_MASTER_SETTINGS::message_duration. The values are defined
+ * in the PTP v2 standard.
+ */
+enum PTP_UC_MSG_DURATION_LIMITS
+{
+ PTP_UC_MSG_DURATION_MIN = 10, ///< minimum message duration [s]
+ PTP_UC_MSG_DURATION_MAX = 1000 ///< maximum message duration [s]
+};
+
+
+
+/**
+ * @brief Configuration settings for a specific PTP unicast master
*/
typedef struct
{
- uint32_t idx; /**< index, 0..(PTP_UC_MASTER_CFG_LIMITS::n_supp_master - 1) */
- PTP_UC_MASTER_SETTINGS settings; /**< specification for the unicast master with that index */
+ uint32_t idx; ///< index, 0..PTP_UC_MASTER_CFG_LIMITS::n_supp_master-1
+ PTP_UC_MASTER_SETTINGS settings; ///< specification for the unicast master with that index
} PTP_UC_MASTER_SETTINGS_IDX;
@@ -5637,13 +9111,16 @@ typedef struct
/**
- * @brief Capabilities and current settings of a unicast master
+ * @brief Current settings and general capabilities of a unicast master
+ *
+ * This structure is used with a PTP unicast slave device to specify
+ * a PTP unicast master which can be queried by the slave device.
*/
typedef struct
{
- PTP_UC_MASTER_SETTINGS settings; /**< current settings */
- uint32_t reserved; /**< reserved, currently always 0 */
- uint32_t flags; /**< reserved, currently always 0 */
+ PTP_UC_MASTER_SETTINGS settings; ///< current settings
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t flags; ///< reserved, currently always 0
} PTP_UC_MASTER_INFO;
@@ -5656,12 +9133,22 @@ typedef struct
/**
- * @brief Capabilities and current settings of a specific unicast master
+ * @brief Current settings and general capabilities of a specific unicast master
+ *
+ * This structure is used with a PTP unicast slave device to specify
+ * a PTP unicast master which can be queried by the slave device.
+ *
+ * This structure should be read from the device to retrieve the
+ * current settings and capabilities. The number of supported
+ * configuration records is PTP_UC_MASTER_CFG_LIMITS::n_supp_master.
+ *
+ * @note The ::PTP_UC_MASTER_SETTINGS_IDX structure should be send back
+ * to the device to save the configuration.
*/
typedef struct
{
- uint32_t idx; /**< index, 0..(PTP_UC_MASTER_CFG_LIMITS::n_supp_master - 1) */
- PTP_UC_MASTER_INFO info; /**< capabilities and current settings */
+ uint32_t idx; ///< index, 0..PTP_UC_MASTER_CFG_LIMITS::n_supp_master-1
+ PTP_UC_MASTER_INFO info; ///< capabilities and current settings
} PTP_UC_MASTER_INFO_IDX;
@@ -5671,8 +9158,1204 @@ typedef struct
_mbg_swab_ptp_uc_master_info( &(_p)->info ); \
}
+/** @} defgroup group_ptp */
+
+
+
+/**
+ * @defgroup group_ntp Definitions used with NTP
+ *
+ * @{ */
+
+
+/**
+ * @brief Enumeration of known NTP roles
+ *
+ * @see ::NTP_GLB_SETTINGS::ntp_role
+ */
+enum NTP_ROLES
+{
+ NTP_ROLE_NONE = 0, ///< NTP services disabled
+ NTP_ROLE_CLIENT, ///< NTP client
+ NTP_ROLE_SERVER, ///< NTP server
+ NTP_ROLE_CLIENT_SERVER, ///< both NTP client and server
+ N_NTP_ROLES ///< number of supported roles
+};
+
+
+/**
+ * @brief Flag masks associated with NTP roles
+ *
+ * @see ::NTP_GLB_INFO::supp_ntp_roles
+ */
+enum NTP_ROLE_MASKS
+{
+ NTP_MSK_ROLE_NONE = ( 1UL << NTP_ROLE_NONE ), ///< see ::NTP_ROLE_NONE
+ NTP_MSK_ROLE_CLIENT = ( 1UL << NTP_ROLE_CLIENT ), ///< see ::NTP_ROLE_CLIENT
+ NTP_MSK_ROLE_SERVER = ( 1UL << NTP_ROLE_SERVER ), ///< see ::NTP_ROLE_SERVER
+ NTP_MSK_ROLE_CLIENT_SERVER = ( 1UL << NTP_ROLE_CLIENT_SERVER ), ///< see ::NTP_ROLE_CLIENT_SERVER
+};
+
+
+/**
+ * @brief Enumeration of global NTP flags
+ *
+ * @see ::NTP_FLAG_MASKS
+ */
+enum NTP_FLAGS
+{
+ NTP_IPV4, ///< NTP via IPv4/UDP
+ NTP_IPV6, ///< NTP via IPv6/UDP
+ NTP_SYMM_KEYS, ///< support symmetric key authentication (MD5)
+ NTP_AUTOKEY, ///< include authentication fields encrypted using the autokey scheme
+ NTP_BURST, ///< send a burst of eight packets at each polling cycle
+ NTP_IBURST, ///< send a burst of eight packets at the first polling cycle
+ NTP_NO_SELECT, ///< marks a server as not to be selected for time synchronization
+ NTP_PREEMPT, ///< specifies the association as preemptable rather than the default persistent
+ NTP_PREFER, ///< marks a server as preferred peer for time synchronization
+ NTP_TRUE, ///< force the association to assume truechimer status; always survive the selection and clustering algorithms
+ NTP_BROADCAST, ///< transmission via broadcast, point to multipoint
+ NTP_MULTICAST, ///< transmission via multicast, point to multipoint
+ NTP_MANYCAST, ///< transmission via manycast, point to multipoint
+ NTP_POOL, ///< peer shall be treated as a pool server
+ N_NTP_FLAGS
+};
+
+
+/**
+ * @brief Flag masks associated with ::NTP_FLAGS
+ *
+ * Used with ::NTP_GLB_INFO::supp_flags, ::NTP_GLB_SETTINGS::flags, NTP_CLNT_MODE_INFO::supp_flags,
+ * ::NTP_CLNT_MODE_INFO::supp_peer_flags, ::NTP_CLNT_MODE_SETTINGS::flags, ::NTP_PEER_SETTINGS::flags,
+ * ::NTP_SRV_MODE_SETTINGS::flags, and ::NTP_SRV_MODE_INFO::supp_flags.
+ *
+ * @todo We may need structures to configure symmetric keys, and autokey certificates.
+ *
+ * @see ::NTP_FLAGS
+ */
+enum NTP_FLAG_MASKS
+{
+ NTP_MSK_IPV4 = ( 1UL << NTP_IPV4 ), ///< see ::NTP_IPV4
+ NTP_MSK_IPV6 = ( 1UL << NTP_IPV6 ), ///< see ::NTP_IPV6
+ NTP_MSK_SYMM_KEYS = ( 1UL << NTP_SYMM_KEYS ), ///< see ::NTP_SYMM_KEYS
+ NTP_MSK_AUTOKEY = ( 1UL << NTP_AUTOKEY ), ///< see ::NTP_AUTOKEY
+ NTP_MSK_BURST = ( 1UL << NTP_BURST ), ///< see ::NTP_BURST
+ NTP_MSK_IBURST = ( 1UL << NTP_IBURST ), ///< see ::NTP_IBURST
+ NTP_MSK_NO_SELECT = ( 1UL << NTP_NO_SELECT ), ///< see ::NTP_NO_SELECT
+ NTP_MSK_PREEMPT = ( 1UL << NTP_PREEMPT ), ///< see ::NTP_PREEMPT
+ NTP_MSK_PREFER = ( 1UL << NTP_PREFER ), ///< see ::NTP_PREFER
+ NTP_MSK_TRUE = ( 1UL << NTP_TRUE ), ///< see ::NTP_TRUE
+ NTP_MSK_BROADCAST = ( 1UL << NTP_BROADCAST ), ///< see ::NTP_BROADCAST
+ NTP_MSK_MULTICAST = ( 1UL << NTP_MULTICAST ), ///< see ::NTP_MULTICAST
+ NTP_MSK_MANYCAST = ( 1UL << NTP_MANYCAST ), ///< see ::NTP_MANYCAST
+ NTP_MSK_POOL = ( 1UL << NTP_POOL ) ///< see ::NTP_POOL
+};
+
+
+/**
+ * @brief Global configuration settings of an NTP device (client/server)
+ *
+ * This structure should be sent to an NTP device to configure global settings
+ */
+typedef struct
+{
+ uint8_t ntp_role; ///< one of the supported NTP roles, see ::NTP_ROLES
+ uint8_t reserved_1; ///< reserved, currently 0
+ uint16_t reserved_2; ///< reserved, currently 0
+
+ uint32_t reserved_3; ///< reserved, currently 0
+ uint32_t reserved_4; ///< reserved, currently 0
+
+ uint32_t flags; ///< NTP flags, see ::NTP_FLAG_MASKS
+
+} NTP_GLB_SETTINGS;
+
+#define _mbg_swab_ntp_glb_settings( _p ) \
+{ \
+ _mbg_swab16( &(_p)->reserved_2 ); \
+ _mbg_swab32( &(_p)->reserved_3 ); \
+ _mbg_swab32( &(_p)->reserved_4 ); \
+ _mbg_swab32( &(_p)->cfg_flags ); \
+}
+
+
+
+/**
+ * @brief Global configuration info of an NTP device (client/server)
+ *
+ * This structure can be used to determine possible configurations of an NTP device
+ */
+typedef struct
+{
+ NTP_GLB_SETTINGS settings; ///< current configuration settings
+
+ uint32_t reserved_1; ///< reserved, currently 0
+ uint32_t reserved_2; ///< reserved, currently 0
+
+ uint32_t supp_ntp_roles; ///< supported NTP roles, see ::NTP_ROLE_MASKS
+ uint32_t supp_flags; ///< supported NTP flags, see ::NTP_FLAG_MASKS
+
+} NTP_GLB_INFO;
+
+#define _mbg_swab_ntp_glb_info( _p ) \
+{ \
+ _mbg_swab_ntp_glb_settings( &(_p)->settings ); \
+ _mbg_swab32( &(_p)->reserved_1 ); \
+ _mbg_swab32( &(_p)->reserved_2 ); \
+ _mbg_swab32( &(_p)->supp_ntp_roles ); \
+ _mbg_swab32( &(_p)->supp_flags ); \
+}
+
+
+/**
+ * @brief Client settings of an NTP device
+ *
+ * This structure should be sent to an NTP client to configure client parameters
+ */
+typedef struct
+{
+ uint32_t reserved_1; ///< reserved, currently 0
+ uint32_t reserved_2; ///< reserved, currently 0
+
+ uint32_t flags; ///< NTP flags, see ::NTP_FLAG_MASKS
+
+} NTP_CLNT_MODE_SETTINGS;
+
+#define _mbg_swab_ntp_clnt_mode_settings( _p ) \
+{ \
+ _mbg_swab32( &(_p)->reserved_1 ); \
+ _mbg_swab32( &(_p)->reserved_2 ); \
+ _mbg_swab32( &(_p)->flags ); \
+}
+
+
+/**
+ * @brief Client settings info of an NTP device
+ *
+ * This structure can be used to determine possible NTP client settings and the current configuration
+ */
+typedef struct
+{
+ NTP_CLNT_MODE_SETTINGS settings;
+
+ uint8_t n_supp_peers; ///< maximal number of configurable peers
+ uint8_t n_supp_pref_peers; ///< maximal number of configurable preferred ref sources
+ uint8_t poll_intv_min; ///< minimal supported NTP polling interval
+ uint8_t poll_intv_max; ///< maximal supported NTP polling interval
+
+ uint32_t reserved_1; ///< reserved, currently 0
+ uint32_t reserved_2; ///< reserved, currently 0
+
+ uint32_t supp_flags; ///< supported NTP flags, see ::NTP_FLAG_MASKS
+ uint32_t supp_peer_flags; ///< supported NTP flags for peers, see ::NTP_FLAG_MASKS
+
+} NTP_CLNT_MODE_INFO;
+
+#define _mbg_swab_ntp_clnt_mode_info( _p ) \
+{ \
+ _mbg_swab_ntp_clnt_mode_settings( &(_p)->settings ); \
+ _mbg_swab32( &(_p)->reserved_1 ); \
+ _mbg_swab32( &(_p)->reserved_2 ); \
+ _mbg_swab32( &(_p)->supp_flags ); \
+ _mbg_swab32( &(_p)->supp_peer_flags ); \
+}
+
+
+/**
+ * @brief Peer settings for NTP devices to configure an upload NTP server
+ *
+ * This structure should be read from the NTP client device to retrieve the
+ * current settings and capabilities. The number of supported peers is
+ * ::NTP_CLNT_MODE_INFO::n_supp_peers.
+ *
+ * @note The ::NTP_PEER_SETTINGS_IDX structure should be send back
+ * to the device to save the configuration.
+ */
+typedef struct
+{
+ MBG_HOSTNAME hostname; ///< hostname or IP address of the peer
+
+ uint8_t min_poll; ///< minimal configurable NTP polling interval
+ uint8_t max_poll; ///< maximal configurable NTP polling interval
+ uint8_t ttl; ///< time-to-live to use with broadcast/multicast/manycast
+ uint8_t reserved_1; ///< reserved, currently 0
+
+ uint32_t reserved_2; ///< reserved, currently 0
+ uint32_t reserved_3; ///< reserved, currently 0
+ uint32_t reserved_4; ///< reserved, currently 0
+
+ uint32_t flags; ///< additional options configured, see ::NTP_FLAG_MASKS
+
+} NTP_PEER_SETTINGS;
+
+#define _mbg_swab_ntp_peer_settings( _p ) \
+{ \
+ _mbg_swab32( &(_p)->reserved_2 ); \
+ _mbg_swab32( &(_p)->reserved_3 ); \
+ _mbg_swab32( &(_p)->reserved_4 ); \
+ _mbg_swab32( &(_p)->flags ); \
+}
+
+/**
+ * @brief Peer settings for NTP devices
+ *
+ * @see ::NTP_PEER_SETTINGS
+ */
+typedef struct
+{
+ uint32_t idx;
+ NTP_PEER_SETTINGS peer_settings;
+
+} NTP_PEER_SETTINGS_IDX;
+
+#define _mbg_swab_ntp_peer_settings_idx( _p ) \
+{ \
+ _mbg_swab32( &(_p)->idx ); \
+ _mbg_swab_ntp_peer_settings( &(_p)->peer_settings ); \
+}
+
+#ifdef DEBUG
+/**
+ * @brief Dummy structure for later NTP server implementations, not used, yet
+ */
+typedef struct
+{
+ uint32_t reserved_1; ///< reserved, currently 0
+ uint32_t reserved_2; ///< reserved, currently 0
+
+ uint32_t flags; ///< NTP flags, see ::NTP_FLAG_MASKS
+
+} NTP_SRV_MODE_SETTINGS;
+
+#define _mbg_swab_ntp_srv_mode_settings( _p ) \
+{ \
+ _mbg_swab32( &(_p)->reserved_1 ); \
+ _mbg_swab32( &(_p)->reserved_2 ); \
+ _mbg_swab32( &(_p)->flags ); \
+}
+
+
+/**
+ * @brief Dummy structure for later NTP server implementations
+ */
+typedef struct
+{
+ NTP_SRV_MODE_SETTINGS settings;
+
+ uint32_t reserved_1; ///< reserved, currently 0
+ uint32_t reserved_2; ///< reserved, currently 0
+
+ uint32_t supp_flags; ///< supported NTP flags, see ::NTP_FLAG_MASKS
+
+} NTP_SRV_MODE_INFO;
+
+#define _mbg_swab_ntp_srv_mode_info( _p ) \
+{ \
+ _mbg_swab_ntp_srv_mode_settings( &(_p)->settings ); \
+ _mbg_swab32( &(_p)->reserved_1 ); \
+ _mbg_swab32( &(_p)->reserved_2 ); \
+ _mbg_swab32( &(_p)->supp_flags ); \
+}
+#endif // DEBUG
+
+
+/**
+ * @brief Structure that represents a timestamp in NTP Short Format
+ *
+ * Maximal value for seconds is 65535.
+ * Resolution of fractions is 15 microseconds.
+ */
+typedef struct
+{
+ uint16_t seconds;
+ uint16_t fractions;
+
+} NTP_SHORT_TSTAMP;
+
+#define _mbg_swab_ntp_short_tstamp( _p ) \
+{ \
+ _mbg_swab16( &(_p)->seconds ); \
+ _mbg_swab16( &(_p)->fractions ); \
+}
+
+
+/**
+ * @brief Structure that represents a timestamp in NTP Timestamp Format
+ *
+ * Maximal value for seconds is 4294967296.
+ * Minimal resolution of fractions is 233 picoseconds.
+ */
+typedef struct
+{
+ uint32_t seconds;
+ uint32_t fractions;
+
+} NTP_TSTAMP;
+
+#define _mbg_swab_ntp_tstamp( _p ) \
+{ \
+ _mbg_swab32( &(_p)->seconds ); \
+ _mbg_swab32( &(_p)->fractions ); \
+}
+
+
+/**
+ * @brief Enumeration of known NTP implementations
+ *
+ * Used with ::NTP_SYS_STATE::impl_type
+ */
+enum NTP_IMPL
+{
+ NTP_IMPL_UNKNOWN = 0, ///< Unknown NTP implementation
+ NTP_IMPL_NTPD, ///< Network Time Protocol daemon (ntpd)
+ NTP_IMPL_NTPDATE, ///< NTP client only (ntpdate)
+ NTP_IMPL_SNTP, ///< Simple Network Time Protocol (sntp)
+ NTP_IMPL_W32TIME, ///< Windows time service (w32time)
+ NTP_IMPL_MBGNTP, ///< Meinberg NTP implementation (mbgntp)
+ N_NTP_IMPLS
+};
+
+/*
+ * Default initializers for English leapsecond string names. Initializers
+ * for multi-language strings can be found in tmonlstr.h.
+ */
+#define MBG_NTP_IMPL_STR_ENG "Implemetation Type:"
+#define MBG_NTP_IMPL_STR_ENG_UNKNOWN "Unknown NTP implementation"
+#define MBG_NTP_IMPL_STR_ENG_NTPD "Network Time Protocol daemon (ntpd)"
+#define MBG_NTP_IMPL_STR_ENG_NTPDATE "NTP client only (ntpdate)"
+#define MBG_NTP_IMPL_STR_ENG_SNTP "Simple Network Time Protocol (sntp)"
+#define MBG_NTP_IMPL_STR_ENG_W32TIME "Windows time service (w32time)"
+#define MBG_NTP_IMPL_STR_ENG_MBGNTP "Meinberg NTP implementation (mbgntp)"
+
+
+#define MBG_NTP_IMPL_NAMES_ENG \
+{ \
+ MBG_NTP_IMPL_STR_ENG_UNKNOWN, \
+ MBG_NTP_IMPL_STR_ENG_NTPD, \
+ MBG_NTP_IMPL_STR_ENG_NTPDATE, \
+ MBG_NTP_IMPL_STR_ENG_SNTP, \
+ MBG_NTP_IMPL_STR_ENG_W32TIME, \
+ MBG_NTP_IMPL_STR_ENG_MBGNTP \
+}
+
+
+/**
+ * @brief Enumeration of CPU types using NTP
+ *
+ * Used with ::NTP_SYS_STATE::cpu_type
+ */
+enum NTP_CPU_TYPES
+{
+ NTP_CPU_TYPE_UNKNOWN = 0,
+ NTP_CPU_TYPE_X86,
+ NTP_CPU_TYPE_I386,
+ NTP_CPU_TYPE_I486,
+ NTP_CPU_TYPE_I586,
+ NTP_CPU_TYPE_I686,
+ NTP_CPU_TYPE_X64,
+ NTP_CPU_TYPE_X86_64,
+ NTP_CPU_TYPE_AMD64,
+ NTP_CPU_TYPE_SUN4U,
+ NTP_CPU_TYPE_ARM,
+ N_NTP_CPU_TYPES
+};
+
+
+/**
+ * @brief Name strings for known CPU types using NTP
+ *
+ * @see ::NTP_CPU_TYPES
+ */
+#define NTP_CPU_TYPES_STRS \
+{ \
+ "Unknown", \
+ "x86", \
+ "i386", \
+ "i486", \
+ "i586", \
+ "i686", \
+ "x64", \
+ "x86_64", \
+ "amd64", \
+ "sun4u", \
+ "arm" \
+}
+
+
+/**
+ * @brief Enumeration of operating systems using NTP
+ *
+ * Used with ::NTP_SYS_STATE::system
+*/
+enum NTP_SYSTEMS
+{
+ NTP_SYSTEM_UNKNOWN = 0,
+ NTP_SYSTEM_NONE,
+ NTP_SYSTEM_WINDOWS,
+ NTP_SYSTEM_LINUX,
+ NTP_SYSTEM_BSD,
+ NTP_SYSTEM_SOLARIS,
+ N_NTP_SYSTEMS
+};
+
+
+/**
+ * @brief Name strings for operating systens using NTP
+ *
+ * @see ::NTP_SYSTEMS
+ */
+#define NTP_SYSTEMS_STRS \
+{ \
+ "Unknown", \
+ "No OS", \
+ "Windows", \
+ "Linux", \
+ "BSD", \
+ "Solaris" \
+}
+
+
+/**
+ * @brief Enumeration of NTP leap indication bits
+ *
+ * Used with ::NTP_SYS_STATE::leap_ind
+ *
+ */
+enum NTP_LI_BITS
+{
+ NTP_LEAP_NONE = 0, ///< normal synchronized state
+ NTP_LEAP_ADD_SEC, ///< insert second after 23:59:59 of the current day
+ NTP_LEAP_DEL_SEC, ///< delete second 23:59:59 of the current day
+ NTP_LEAP_ALARM, ///< never synchronized
+ N_NTP_LI_BITS
+};
+
+/*
+ * Default initializers for English leapsecond string names. Initializers
+ * for multi-language strings can be found in tmonlstr.h.
+ */
+#define MBG_NTP_LEAP_STR_ENG "Leapsecond indication:"
+#define MBG_NTP_LEAP_STR_ENG_NONE "None"
+#define MBG_NTP_LEAP_STR_ENG_ADD_SEC "Insert second"
+#define MBG_NTP_LEAP_STR_ENG_DEL_SEC "Delete second"
+#define MBG_NTP_LEAP_STR_ENG_ALARM "Alarm"
+
+#define MBG_NTP_LEAP_NAMES_ENG \
+{ \
+ MBG_NTP_LEAP_STR_ENG_NONE, \
+ MBG_NTP_LEAP_STR_ENG_ADD_SEC, \
+ MBG_NTP_LEAP_STR_ENG_DEL_SEC, \
+ MBG_NTP_LEAP_STR_ENG_ALARM \
+}
+
+
+/**
+ * @brief Enumeration of NTP synchronization source bits
+ *
+ * Used with ::NTP_SYS_STATE::sys_sync_src
+ *
+ */
+enum NTP_SYNC_SRC_BITS
+{
+ NTP_SYNC_SRC_UNSPEC = 0, ///< not yet synchronized
+ NTP_SYNC_SRC_PPS, ///< pulse-per-second signal (Cs, Ru, GPS, etc.)
+ NTP_SYNC_SRC_LF_RADIO, ///< VLF/LF radio (WWVB, DCF77, etc.)
+ NTP_SYNC_SRC_HF_RADIO, ///< MF/HF radio (WWV, etc.)
+ NTP_SYNC_SRC_UHF_RADIO, ///< VHF/UHF radio/satellite (GPS, Galileo, etc.)
+ NTP_SYNC_SRC_LOCAL, ///< local timecode (IRIG, LOCAL driver, etc.)
+ NTP_SYNC_SRC_NTP, ///< NTP
+ NTP_SYNC_SRC_OTHER, ///< other (IEEE 1588, openntp, crony, etc.)
+ NTP_SYNC_SRC_WRISTWATCH, ///< eyeball and wristwatch
+ NTP_SYNC_SRC_TELEPHONE, ///< telephone modem (ACTS, PTB, etc.)
+ N_NTP_SYNC_SRC_BITS
+};
+
+/*
+ * Default initializers for English sync source string names. Initializers
+ * for multi-language strings can be found in tmonlstr.h.
+ */
+#define MBG_NTP_SYNC_SRC_STR_ENG_LABEL "Sync Source:"
+#define MBG_NTP_SYNC_SRC_STR_ENG_UNSPEC "Not yet synchronized"
+#define MBG_NTP_SYNC_SRC_STR_ENG_PPS "Pulse per second signal"
+#define MBG_NTP_SYNC_SRC_STR_ENG_LF_RADIO "VLF/LF radio"
+#define MBG_NTP_SYNC_SRC_STR_ENG_HF_RADIO "MF/HF radio"
+#define MBG_NTP_SYNC_SRC_STR_ENG_UHF_RADIO "VHF/UHF radio/satellite"
+#define MBG_NTP_SYNC_SRC_STR_ENG_LOCAL "local timecode"
+#define MBG_NTP_SYNC_SRC_STR_ENG_NTP "NTP"
+#define MBG_NTP_SYNC_SRC_STR_ENG_OTHER "other"
+#define MBG_NTP_SYNC_SRC_STR_ENG_WRISTWATCH "eyeball and wristwatch"
+#define MBG_NTP_SYNC_SRC_STR_ENG_TELEPHONE "telephone modem"
+
+#define MBG_NTP_SYNC_SRC_NAMES_ENG \
+{ \
+ MBG_NTP_SYNC_SRC_STR_ENG_UNSPEC, \
+ MBG_NTP_SYNC_SRC_STR_ENG_PPS, \
+ MBG_NTP_SYNC_SRC_STR_ENG_LF_RADIO, \
+ MBG_NTP_SYNC_SRC_STR_ENG_HF_RADIO, \
+ MBG_NTP_SYNC_SRC_STR_ENG_UHF_RADIO, \
+ MBG_NTP_SYNC_SRC_STR_ENG_LOCAL, \
+ MBG_NTP_SYNC_SRC_STR_ENG_NTP, \
+ MBG_NTP_SYNC_SRC_STR_ENG_OTHER, \
+ MBG_NTP_SYNC_SRC_STR_ENG_WRISTWATCH, \
+ MBG_NTP_SYNC_SRC_STR_ENG_TELEPHONE \
+}
+
+
+/**
+ * @brief Enumeration of NTP system event message bits
+ *
+ * Used with ::NTP_SYS_STATE::sys_rec_evt
+ *
+ */
+enum NTP_SYS_EVT_BITS
+{
+ NTP_SYS_EVT_UNSPEC = 0, ///< unspecified NTP event
+ NTP_SYS_EVT_FREQ_NOT_SET, ///< frequency file not available
+ NTP_SYS_EVT_FREQ_SET, ///< frequency set from frequency file
+ NTP_SYS_EVT_SPIKE_DETECT, ///< spike detected
+ NTP_SYS_EVT_FREQ_MODE, ///< initial frequency training mode
+ NTP_SYS_EVT_CLOCK_SYNC, ///< clock synchronized
+ NTP_SYS_EVT_RESTART, ///< program restart
+ NTP_SYS_EVT_PANIC_STOP, ///< clock error more than 600 s
+ NTP_SYS_EVT_NO_SYSTEM_PEER, ///< no system peer
+ NTP_SYS_EVT_LEAP_ARMED, ///< leap second armed from file or autokey
+ NTP_SYS_EVT_LEAP_DISARMED, ///< leap second disarmed
+ NTP_SYS_EVT_LEAP_EVENT, ///< leap event
+ NTP_SYS_EVT_CLOCK_STEP, ///< clock stepped
+ NTP_SYS_EVT_KERNEL, ///< kernel information message
+ NTP_SYS_EVT_TAI, ///< leapsecond values update from file
+ NTP_SYS_EVT_STALE_LS_VALUES, ///< new NIST leapseconds file needed
+ N_NTP_SYS_EVT_BITS
+};
+
+/*
+ * Default initializers for English sync source string names. Initializers
+ * for multi-language strings can be found in tmonlstr.h.
+ */
+#define MBG_NTP_SYS_EVT_STR_ENG_CNT_LABEL "System Event Counter:"
+#define MBG_NTP_SYS_EVT_STR_ENG_MSG_LABEL "System Event Message:"
+#define MBG_NTP_SYS_EVT_STR_ENG_UNSPEC "Unspecified NTP event"
+#define MBG_NTP_SYS_EVT_STR_ENG_FREQ_NOT_SET "Frequency file not available"
+#define MBG_NTP_SYS_EVT_STR_ENG_FREQ_SET "Frequency set from frequency file"
+#define MBG_NTP_SYS_EVT_STR_ENG_SPIKE_DETECT "Spike detected"
+#define MBG_NTP_SYS_EVT_STR_ENG_FREQ_MODE "Initial frequency training mode"
+#define MBG_NTP_SYS_EVT_STR_ENG_CLOCK_SYNC "Clock synchronized"
+#define MBG_NTP_SYS_EVT_STR_ENG_RESTART "Program restart"
+#define MBG_NTP_SYS_EVT_STR_ENG_PANIC_STOP "Clock error more than 600 s"
+#define MBG_NTP_SYS_EVT_STR_ENG_NO_SYSTEM_PEER "No system peer"
+#define MBG_NTP_SYS_EVT_STR_ENG_LEAP_ARMED "Leap second armed from file or autokey"
+#define MBG_NTP_SYS_EVT_STR_ENG_LEAP_DISARMED "Leap second disarmed"
+#define MBG_NTP_SYS_EVT_STR_ENG_LEAP_EVENT "Leap event"
+#define MBG_NTP_SYS_EVT_STR_ENG_CLOCK_STEP "Clock stepped"
+#define MBG_NTP_SYS_EVT_STR_ENG_KERNEL "Kernel information message"
+#define MBG_NTP_SYS_EVT_STR_ENG_TAI "Leap second values update from file"
+#define MBG_NTP_SYS_EVT_STR_ENG_STALE_LS_VALUES "New NIST leapseconds file needed"
+
+
+#define MBG_NTP_SYS_EVT_NAMES_ENG \
+{ \
+ MBG_NTP_SYS_EVT_STR_ENG_UNSPEC, \
+ MBG_NTP_SYS_EVT_STR_ENG_FREQ_NOT_SET, \
+ MBG_NTP_SYS_EVT_STR_ENG_FREQ_SET, \
+ MBG_NTP_SYS_EVT_STR_ENG_SPIKE_DETECT, \
+ MBG_NTP_SYS_EVT_STR_ENG_FREQ_MODE, \
+ MBG_NTP_SYS_EVT_STR_ENG_CLOCK_SYNC, \
+ MBG_NTP_SYS_EVT_STR_ENG_RESTART, \
+ MBG_NTP_SYS_EVT_STR_ENG_PANIC_STOP, \
+ MBG_NTP_SYS_EVT_STR_ENG_NO_SYSTEM_PEER, \
+ MBG_NTP_SYS_EVT_STR_ENG_LEAP_ARMED, \
+ MBG_NTP_SYS_EVT_STR_ENG_LEAP_DISARMED, \
+ MBG_NTP_SYS_EVT_STR_ENG_LEAP_EVENT, \
+ MBG_NTP_SYS_EVT_STR_ENG_CLOCK_STEP, \
+ MBG_NTP_SYS_EVT_STR_ENG_KERNEL, \
+ MBG_NTP_SYS_EVT_STR_ENG_TAI, \
+ MBG_NTP_SYS_EVT_STR_ENG_STALE_LS_VALUES \
+}
+
+/**
+ * @brief Enumeration of supported NTP system state values
+ *
+ * @see ::NTP_SYS_STATE_SUPP_FLAG_MASKS
+ */
+enum NTP_SYS_STATE_SUPP_FLAGS
+{
+ NTP_SYS_STATE_SUPP_STD = 0, ///< supports standard values of ::NTP_SYS_STATE, all fields except below and reserved
+ NTP_SYS_STATE_SUPP_EVENTS, ///< supports sys state events (::NTP_SYS_STATE::sys_evt_cnt, ::NTP_SYS_STATE::sys_rec_evt)
+ NTP_SYS_STATE_SUPP_PRECISION, ///< supports precision indication, see ::NTP_SYS_STATE::precision
+ NTP_SYS_STATE_SUPP_ROOT_DELAY, ///< supports root delay to syspeer, see ::NTP_SYS_STATE::root_delay
+ NTP_SYS_STATE_SUPP_ROOT_DISP, ///< supports root dispersion, see ::NTP_SYS_STATE::root_disp
+ NTP_SYS_STATE_SUPP_FREQ, ///< supports frequency offset, see ::NTP_SYS_STATE::freq
+ NTP_SYS_STATE_SUPP_SYS_JITTER, ///< supports combined jitter, see ::NTP_SYS_STATE::sys_jitter
+ NTP_SYS_STATE_SUPP_CLK_JITTER, ///< supports clock jitter, see ::NTP_SYS_STATE::clk_jitter
+ NTP_SYS_STATE_SUPP_CLK_WANDER, ///< supports clock wander, see ::NTP_SYS_STATE::clk_wander
+ N_NTP_SYS_STATE_SUPP_FLAGS
+};
+
+
+/**
+ * @brief Flag masks for NTP_SYS_STATE_SUPP_FLAGS
+ *
+ * Used with ::NTP_SYS_STATE::supp_flags
+ *
+ * @see ::NTP_SYS_STATE_SUPP_FLAGS
+ */
+enum NTP_SYS_STATE_SUPP_FLAG_MASKS
+{
+ NTP_SYS_STATE_SUPP_STD_MSK = ( 1UL << NTP_SYS_STATE_SUPP_STD ), ///< see ::NTP_SYS_STATE_SUPP_STD
+ NTP_SYS_STATE_SUPP_EVENTS_MSK = ( 1UL << NTP_SYS_STATE_SUPP_EVENTS ), ///< see ::NTP_SYS_STATE_SUPP_EVENTS
+ NTP_SYS_STATE_SUPP_PRECISION_MSK = ( 1UL << NTP_SYS_STATE_SUPP_PRECISION ), ///< see ::NTP_SYS_STATE_SUPP_PRECISION
+ NTP_SYS_STATE_SUPP_ROOT_DELAY_MSK = ( 1UL << NTP_SYS_STATE_SUPP_ROOT_DELAY ), ///< see ::NTP_SYS_STATE_SUPP_ROOT_DELAY
+ NTP_SYS_STATE_SUPP_ROOT_DISP_MSK = ( 1UL << NTP_SYS_STATE_SUPP_ROOT_DISP ), ///< see ::NTP_SYS_STATE_SUPP_ROOT_DISP
+ NTP_SYS_STATE_SUPP_FREQ_MSK = ( 1UL << NTP_SYS_STATE_SUPP_FREQ ), ///< see ::NTP_SYS_STATE_SUPP_FREQ
+ NTP_SYS_STATE_SUPP_SYS_JITTER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_SYS_JITTER ), ///< see ::NTP_SYS_STATE_SUPP_SYS_JITTER
+ NTP_SYS_STATE_SUPP_CLK_JITTER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_CLK_JITTER ), ///< see ::NTP_SYS_STATE_SUPP_CLK_JITTER
+ NTP_SYS_STATE_SUPP_CLK_WANDER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_CLK_WANDER ) ///< see ::NTP_SYS_STATE_SUPP_CLK_WANDER
+};
+
+
+/**
+ * @brief Structure that represents the current system status of an NTP device
+ *
+ * This structure can be requested from a monitoring program to determine the device system status
+ */
+typedef struct
+{
+ uint32_t supp_flags; ///< Supported NTP system state values, see ::NTP_SYS_STATE_SUPP_FLAG_MASKS
+
+ uint8_t leap_ind; ///< Leap indicator, see ::NTP_LI_BITS
+ uint8_t sys_sync_src; ///< Current synchronization source, see ::NTP_SYNC_SRC_BITS
+ uint8_t sys_evt_cnt; ///< Number of events, since the last time the event code changed
+ uint8_t sys_rec_evt; ///< Most recent event message, see ::NTP_SYS_EVT_BITS
+
+ uint8_t impl_type; ///< NTP implementation type, see ::NTP_IMPL
+ uint8_t major_version; ///< Major version number
+ uint8_t minor_version; ///< Minor version number
+ uint8_t micro_version; ///< Micro version number
+
+ uint16_t patch_lvl; ///< Patch level number
+ uint8_t cpu_type; ///< Processor type, see ::NTP_CPU_TYPES
+ uint8_t system; ///< Operating system, see ::NTP_SYSTEMS
+
+ uint8_t stratum; ///< Current stratum level of the system
+ int8_t precision; ///< Precision of the system clock (2^precision)
+ uint16_t reserved_1; ///< Reserved, currently always 0
+
+ int32_t root_delay; ///< [us] Total roundtrip delay to the system peer
+ int32_t root_disp; ///< [us] Total dispersion to the system peer
+
+ MBG_IP_ADDR ref_id; ///< Reference ID of the current system peer, see ::MBG_IP_ADDR
+
+ NTP_TSTAMP ref_time; ///< Last time the system time has been adjusted, see ::NTP_TSTAMP
+ NTP_TSTAMP sys_time; ///< Current system time, see ::NTP_TSTAMP
+
+ uint16_t sys_peer; ///< Assocation ID of the current system peer
+ uint8_t poll; ///< Current polling interval for the system peer (tc)
+ uint8_t minpoll; ///< Minimal polling interval for the system peer (mintc)
+
+ int64_t offset; ///< [ns] Combined offset to the system peer
+
+ int32_t freq; ///< [ppb] Frequency offset relative to hardware clock
+ int32_t sys_jitter; ///< [us] Combined jitter of the system
+ int32_t clk_jitter; ///< [us] Jitter of the clock
+ int32_t clk_wander; ///< [ppb] Frequency wander of the clock
+
+ uint32_t reserved_2; ///< Reserved, currently always 0
+ uint32_t reserved_3; ///< Reserved, currently always 0
+
+} NTP_SYS_STATE;
+
+
+/**
+ * @brief Enumeration of NTP mode bits
+ *
+ * Used with ::NTP_PEER_STATE::host_mode and ::NTP_PEER_STATE::peer_mode
+ *
+ */
+enum NTP_MODE_BITS
+{
+ NTP_MODE_RESERVED = 0,
+ NTP_MODE_SYMM_ACT,
+ NTP_MODE_SYMM_PASS,
+ NTP_MODE_CLIENT,
+ NTP_MODE_SERVER,
+ NTP_MODE_BROADCAST,
+ NTP_MODE_CONTROL,
+ NTP_MODE_PRIVATE,
+ N_NTP_MODE_BITS
+};
+
+/*
+ * Default initializers for English NTP peer mode string names. Initializers
+ * for multi-language strings can be found in tmonlstr.h.
+ */
+#define MBG_NTP_MODE_STR_ENG_HOST_LABEL "Host Mode:"
+#define MBG_NTP_MODE_STR_ENG_PEER_LABEL "Peer Mode:"
+
+#define MBG_NTP_PEER_MODE_STR_ENG_RESERVED "Reserved"
+#define MBG_NTP_PEER_MODE_STR_ENG_SYMM_ACT "Symm Act"
+#define MBG_NTP_PEER_MODE_STR_ENG_SYMM_PASS "Symm Pass"
+#define MBG_NTP_PEER_MODE_STR_ENG_CLIENT "Client"
+#define MBG_NTP_PEER_MODE_STR_ENG_SERVER "Server"
+#define MBG_NTP_PEER_MODE_STR_ENG_BROADCAST "Broadcast"
+#define MBG_NTP_PEER_MODE_STR_ENG_CONTROL "Control"
+#define MBG_NTP_PEER_MODE_STR_ENG_PRIVATE "Private"
+
+#define MBG_NTP_MODE_STAT_NAMES_ENG \
+{ \
+ MBG_NTP_PEER_MODE_STR_ENG_RESERVED, \
+ MBG_NTP_PEER_MODE_STR_ENG_SYMM_ACT, \
+ MBG_NTP_PEER_MODE_STR_ENG_SYMM_PASS, \
+ MBG_NTP_PEER_MODE_STR_ENG_CLIENT, \
+ MBG_NTP_PEER_MODE_STR_ENG_SERVER, \
+ MBG_NTP_PEER_MODE_STR_ENG_BROADCAST, \
+ MBG_NTP_PEER_MODE_STR_ENG_CONTROL, \
+ MBG_NTP_PEER_MODE_STR_ENG_PRIVATE \
+}
+
+
+/**
+ * @brief Enumeration of NTP peer reach status
+ *
+ * Used with ::NTP_PEER_STATE::peer_reach_stat
+ */
+enum NTP_REACH_STAT_BITS
+{
+ NTP_REACH_STAT_UNKNOWN = 0, ///< unknown reach status
+ NTP_REACH_STAT_NO_LINK, ///< no network connection
+ NTP_REACH_STAT_DNS_UNREACH, ///< DNS server could not be reached
+ NTP_REACH_STAT_DNS_UNRESOLVED, ///< DNS name could not be resolved
+ NTP_REACH_STAT_PEER_UNREACH, ///< peer could not be reached
+ NTP_REACH_STAT_PEER_NOT_SYNC, ///< peer is not sync (leap alarm, stratum 16)
+ NTP_REACH_STAT_PEER_BAD_QUALITY, ///< peer has bad quality (dispersion, ...)
+ NTP_REACH_STAT_OK, ///< reach status is fine
+ N_NTP_REACH_STAT_BITS
+};
+
+/*
+ * Default initializers for English reach status string names. Initializers
+ * for multi-language strings can be found in tmonlstr.h.
+ */
+#define MBG_NTP_PEER_REACH_STAT_STR_ENG_LABEL "Reach State:"
+
+#define MBG_NTP_PEER_REACH_STAT_STR_ENG_UNKNOWN "Unknown"
+#define MBG_NTP_PEER_REACH_STAT_STR_ENG_NO_LINK "No link"
+#define MBG_NTP_PEER_REACH_STAT_STR_ENG_DNS_UNREACH "DNS Server unreached"
+#define MBG_NTP_PEER_REACH_STAT_STR_ENG_DNS_UNRESOLVED "DNS name not resolved"
+#define MBG_NTP_PEER_REACH_STAT_STR_ENG_PEER_UNREACH "Peer not reached"
+#define MBG_NTP_PEER_REACH_STAT_STR_ENG_PEER_NOT_SYNC "Peer not sync"
+#define MBG_NTP_PEER_REACH_STAT_STR_ENG_PEER_BAD_QUALITY "Peer has bad quality"
+#define MBG_NTP_PEER_REACH_STAT_STR_ENG_OK "Good"
+
+#define MBG_NTP_PEER_REACH_STAT_NAMES_ENG \
+{ \
+ MBG_NTP_PEER_REACH_STAT_STR_ENG_UNKNOWN, \
+ MBG_NTP_PEER_REACH_STAT_STR_ENG_NO_LINK, \
+ MBG_NTP_PEER_REACH_STAT_STR_ENG_DNS_UNREACH, \
+ MBG_NTP_PEER_REACH_STAT_STR_ENG_DNS_UNRESOLVED, \
+ MBG_NTP_PEER_REACH_STAT_STR_ENG_PEER_UNREACH, \
+ MBG_NTP_PEER_REACH_STAT_STR_ENG_PEER_NOT_SYNC, \
+ MBG_NTP_PEER_REACH_STAT_STR_ENG_PEER_BAD_QUALITY, \
+ MBG_NTP_PEER_REACH_STAT_STR_ENG_OK \
+}
+
+
+/**
+ * @brief Enumeration of NTP peer selection status
+ *
+ * Used with ::NTP_PEER_STATE::peer_sel_stat
+ *
+ */
+enum NTP_PEER_SEL_STATUS_BITS
+{
+ NTP_PEER_SEL_REJECT = 0, ///< discarded as not valid (TEST10-TEST13)
+ NTP_PEER_SEL_FALSETICK, ///< discarded by intersection algorithm
+ NTP_PEER_SEL_EXCESS, ///< discarded by table overflow (not used)
+ NTP_PEER_SEL_OUTLYER, ///< discarded by the cluster algorithm
+ NTP_PEER_SEL_CANDIDATE, ///< included by the combine algorithm
+ NTP_PEER_SEL_BACKUP, ///< backup (more than tos maxclock sources)
+ NTP_PEER_SEL_SYS_PEER, ///< system peer
+ NTP_PEER_SEL_PPS_PEER, ///< PPS peer (when the prefer peer is valid)
+ N_NTP_PEER_SEL_STATUS_BITS
+};
+
+/*
+ * Default initializers for English peer select status string names. Initializers
+ * for multi-language strings can be found in tmonlstr.h.
+ */
+#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_LABEL "Selected Status:"
+
+#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_REJECT "Not valid"
+#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_FALSETICK "Falsetick"
+#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_EXCESS "Excess"
+#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_OUTLYER "Outlyer"
+#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_CANDIDATE "Candidate"
+#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_BACKUP "Backup"
+#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_SYS_PEER "System Peer"
+#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_PPS_PEER "PPS Peer"
+
+#define MBG_NTP_PEER_SEL_STATUS_NAMES_ENG \
+{ \
+ MBG_NTP_PEER_SEL_STATUS_STR_ENG_REJECT, \
+ MBG_NTP_PEER_SEL_STATUS_STR_ENG_FALSETICK, \
+ MBG_NTP_PEER_SEL_STATUS_STR_ENG_EXCESS, \
+ MBG_NTP_PEER_SEL_STATUS_STR_ENG_OUTLYER, \
+ MBG_NTP_PEER_SEL_STATUS_STR_ENG_CANDIDATE, \
+ MBG_NTP_PEER_SEL_STATUS_STR_ENG_BACKUP, \
+ MBG_NTP_PEER_SEL_STATUS_STR_ENG_SYS_PEER, \
+ MBG_NTP_PEER_SEL_STATUS_STR_ENG_PPS_PEER \
+}
+
+
+/**
+ * @brief Enumeration of NTP peer status codes
+ *
+ * @see ::NTP_PEER_STATUS_FLAG_MASKS
+ *
+ */
+enum NTP_PEER_STATUS_FLAGS
+{
+ NTP_PEER_STATUS_BCST = 0, ///< broadcast association
+ NTP_PEER_STATUS_REACH, ///< host reachable
+ NTP_PEER_STATUS_AUTHENB, ///< authentication enabled
+ NTP_PEER_STATUS_AUTH, ///< authentication ok
+ NTP_PEER_STATUS_CONFIG, ///< persistent association
+ N_NTP_PEER_STATUS_FLAGS
+};
+
+
+/**
+ * @brief Flag masks for NTP_PEER_STATUS_FLAGS
+ *
+ * Used with ::NTP_PEER_STATE::peer_status_flags
+ *
+ * @see ::NTP_PEER_STATUS_FLAGS
+ */
+enum NTP_PEER_STATUS_FLAG_MASKS
+{
+ NTP_PEER_STATUS_BCST_MSK = ( 1UL << NTP_PEER_STATUS_BCST ), ///< see ::NTP_PEER_STATUS_BCST
+ NTP_PEER_STATUS_REACH_MSK = ( 1UL << NTP_PEER_STATUS_REACH ), ///< see ::NTP_PEER_STATUS_REACH
+ NTP_PEER_STATUS_AUTHENB_MSK = ( 1UL << NTP_PEER_STATUS_AUTHENB ), ///< see ::NTP_PEER_STATUS_AUTHENB
+ NTP_PEER_STATUS_AUTH_MSK = ( 1UL << NTP_PEER_STATUS_AUTH ), ///< see ::NTP_PEER_STATUS_AUTH
+ NTP_PEER_STATUS_CONFIG_MSK = ( 1UL << NTP_PEER_STATUS_CONFIG ), ///< see ::NTP_PEER_STATUS_CONFIG
+};
+
+
+/*
+ * Default initializers for English peer status string names. Initializers
+ * for multi-language strings can be found in tmonlstr.h.
+ */
+#define MBG_NTP_PEER_STATUS_STR_ENG_LABEL "Peer Status:"
+#define MBG_NTP_PEER_STATUS_STR_ENG_BCST "Broadcast association"
+#define MBG_NTP_PEER_STATUS_STR_ENG_REACH "Host reachable"
+#define MBG_NTP_PEER_STATUS_STR_ENG_AUTHENB "Authentication enabled"
+#define MBG_NTP_PEER_STATUS_STR_ENG_CONFIG "Persistant assosiation"
+
+#define MBG_NTP_PEER_STATUS_NAMES_ENG \
+{ \
+ MBG_NTP_PEER_STATUS_STR_ENG_BCST, \
+ MBG_NTP_PEER_STATUS_STR_ENG_REACH, \
+ MBG_NTP_PEER_STATUS_STR_ENG_REACH, \
+ MBG_NTP_PEER_STATUS_STR_ENG_AUTHENB, \
+ MBG_NTP_PEER_STATUS_STR_ENG_CONFIG \
+}
+
+
+/**
+ * @brief Enumeration of NTP peer event message codes
+ *
+ * Used with ::NTP_PEER_STATE::peer_rec_evt
+ *
+ */
+enum NTP_PEER_EVT_BITS
+{
+ NTP_PEER_EVT_UNSPEC = 0, ///< unspecified NTP event
+ NTP_PEER_EVT_MOBILIZE, ///< association mobilized
+ NTP_PEER_EVT_DEMOBILIZE, ///< association demobilized
+ NTP_PEER_EVT_UNREACHABLE, ///< server unreachable
+ NTP_PEER_EVT_REACHABLE, ///< server reachable
+ NTP_PEER_EVT_RESTART, ///< association restart
+ NTP_PEER_EVT_NO_REPLY, ///< no server found (ntpdate mode)
+ NTP_PEER_EVT_RATE_EXCEEDED, ///< rate exceeded (kiss code RATE)
+ NTP_PEER_EVT_ACCESS_DENIED, ///< access denied (kiss code DENY)
+ NTP_PEER_EVT_LEAP_ARMED, ///< leap armed from server LI code
+ NTP_PEER_EVT_SYS_PEER, ///< become system peer
+ NTP_PEER_EVT_CLOCK_EVENT, ///< see clock status word
+ NTP_PEER_EVT_BAD_AUTH, ///< authentication failure
+ NTP_PEER_EVT_POPCORN, ///< popcorn spike suppressor
+ NTP_PEER_EVT_INTERLEAVE_MODE, ///< entering interleave mode
+ NTP_PEER_EVT_INTERLEAVE_ERROR, ///< interleave error (recovered)
+ N_NTP_PEER_EVT_BITS
+};
+
+/*
+ * Default initializers for English event message codes. Initializers
+ * for multi-language strings can be found in tmonlstr.h.
+ */
+#define MBG_NTP_PEER_EVT_STR_ENG_CNT_LABEL "Peer Event Counter:"
+#define MBG_NTP_PEER_EVT_STR_ENG_MSG_LABEL "Peer Event Message:"
+#define MBG_NTP_PEER_EVT_STR_ENG_UNSPEC "Unspecified NTP event"
+#define MBG_NTP_PEER_EVT_STR_ENG_MOBILIZE "Association mobilized"
+#define MBG_NTP_PEER_EVT_STR_ENG_DEMOBILIZE "Association demobilized"
+#define MBG_NTP_PEER_EVT_STR_ENG_UNREACHABLE "Server unreachable"
+#define MBG_NTP_PEER_EVT_STR_ENG_REACHABLE "Server reachable"
+#define MBG_NTP_PEER_EVT_STR_ENG_RESTART "Association restart"
+#define MBG_NTP_PEER_EVT_STR_ENG_NO_REPLY "No server found"
+#define MBG_NTP_PEER_EVT_STR_ENG_RATE_EXCEEDED "Rate exceeded"
+#define MBG_NTP_PEER_EVT_STR_ENG_ACCESS_DENIED "Access denied"
+#define MBG_NTP_PEER_EVT_STR_ENG_LEAP_ARMED "Leap second armed from LI code"
+#define MBG_NTP_PEER_EVT_STR_ENG_SYS_PEER "Become system Peer"
+#define MBG_NTP_PEER_EVT_STR_ENG_CLOCK_EVENT "Clock event"
+#define MBG_NTP_PEER_EVT_STR_ENG_BAD_AUTH "Authentication failure"
+#define MBG_NTP_PEER_EVT_STR_ENG_POPCORN "Popcorn Spike suspressor"
+#define MBG_NTP_PEER_EVT_STR_ENG_INTERLEAVE_MODE "Entering Interleave mode"
+#define MBG_NTP_PEER_EVT_STR_ENG_INTERLEAVE_ERROR "Interleave error"
+
+
+#define MBG_NTP_PEER_EVT_NAMES_ENG \
+{ \
+ MBG_NTP_PEER_EVT_STR_ENG_UNSPEC, \
+ MBG_NTP_PEER_EVT_STR_ENG_MOBILIZE, \
+ MBG_NTP_PEER_EVT_STR_ENG_DEMOBILIZE, \
+ MBG_NTP_PEER_EVT_STR_ENG_UNREACHABLE, \
+ MBG_NTP_PEER_EVT_STR_ENG_REACHABLE, \
+ MBG_NTP_PEER_EVT_STR_ENG_RESTART, \
+ MBG_NTP_PEER_EVT_STR_ENG_NO_REPLY, \
+ MBG_NTP_PEER_EVT_STR_ENG_RATE_EXCEEDED, \
+ MBG_NTP_PEER_EVT_STR_ENG_ACCESS_DENIED, \
+ MBG_NTP_PEER_EVT_STR_ENG_LEAP_ARMED, \
+ MBG_NTP_PEER_EVT_STR_ENG_SYS_PEER, \
+ MBG_NTP_PEER_EVT_STR_ENG_CLOCK_EVENT, \
+ MBG_NTP_PEER_EVT_STR_ENG_BAD_AUTH, \
+ MBG_NTP_PEER_EVT_STR_ENG_POPCORN, \
+ MBG_NTP_PEER_EVT_STR_ENG_INTERLEAVE_MODE, \
+ MBG_NTP_PEER_EVT_STR_ENG_INTERLEAVE_ERROR \
+}
+
+
+/**
+ * @brief Enumeration of NTP flash status bit codes
+ *
+ * @see ::NTP_FLASH_STAT_FLAG_MASKS
+ *
+ */
+enum NTP_FLASH_STAT_FLAGS
+{
+ NTP_FLASH_STAT_PKT_DUP = 0, ///< duplicate packet
+ NTP_FLASH_STAT_PKT_BOGUS, ///< bogus packet
+ NTP_FLASH_STAT_PKT_UNSYNC, ///< server not synchronized
+ NTP_FLASH_STAT_PKT_DENIED, ///< access denied
+ NTP_FLASH_STAT_PKT_AUTH, ///< authentication failure
+ NTP_FLASH_STAT_PKT_STRATUM, ///< invalid leap or stratum
+ NTP_FLASH_STAT_PKT_HEADER, ///< header distance exceeded
+ NTP_FLASH_STAT_PKT_AUTOKEY, ///< Autokey sequence error
+ NTP_FLASH_STAT_PKT_CRYPTO, ///< Autokey protocol error
+ NTP_FLASH_STAT_PEER_STRATUM, ///< invalid header or stratum
+ NTP_FLASH_STAT_PEER_DIST, ///< distance threshold exceeded
+ NTP_FLASH_STAT_PEER_LOOP, ///< synchronization loop
+ NTP_FLASH_STAT_PEER_UNREACH, ///< unreachable or nonselect
+ N_NTP_FLASH_STAT_FLAGS
+};
+
+
+/**
+ * @brief Flag masks for ::NTP_FLASH_STAT_FLAGS
+ *
+ * Used with ::NTP_PEER_STATE::flash_stat_flags
+ *
+ * @see ::NTP_FLASH_STAT_FLAGS
+ */
+enum NTP_FLASH_STAT_FLAG_MASKS
+{
+ NTP_FLASH_STAT_PKT_DUP_MSK = ( 1UL << NTP_FLASH_STAT_PKT_DUP ), ///< see ::NTP_FLASH_STAT_PKT_DUP
+ NTP_FLASH_STAT_PKT_BOGUS_MSK = ( 1UL << NTP_FLASH_STAT_PKT_BOGUS ), ///< see ::NTP_FLASH_STAT_PKT_BOGUS
+ NTP_FLASH_STAT_PKT_UNSYNC_MSK = ( 1UL << NTP_FLASH_STAT_PKT_UNSYNC ), ///< see ::NTP_FLASH_STAT_PKT_UNSYNC
+ NTP_FLASH_STAT_PKT_DENIED_MSK = ( 1UL << NTP_FLASH_STAT_PKT_DENIED ), ///< see ::NTP_FLASH_STAT_PKT_DENIED
+ NTP_FLASH_STAT_PKT_AUTH_MSK = ( 1UL << NTP_FLASH_STAT_PKT_AUTH ), ///< see ::NTP_FLASH_STAT_PKT_AUTH
+ NTP_FLASH_STAT_PKT_STRATUM_MSK = ( 1UL << NTP_FLASH_STAT_PKT_STRATUM ), ///< see ::NTP_FLASH_STAT_PKT_STRATUM
+ NTP_FLASH_STAT_PKT_HEADER_MSK = ( 1UL << NTP_FLASH_STAT_PKT_HEADER ), ///< see ::NTP_FLASH_STAT_PKT_HEADER
+ NTP_FLASH_STAT_PKT_AUTOKEY_MSK = ( 1UL << NTP_FLASH_STAT_PKT_AUTOKEY ), ///< see ::NTP_FLASH_STAT_PKT_AUTOKEY
+ NTP_FLASH_STAT_PKT_CRYPTO_MSK = ( 1UL << NTP_FLASH_STAT_PKT_CRYPTO ), ///< see ::NTP_FLASH_STAT_PKT_CRYPTO
+ NTP_FLASH_STAT_PEER_STRATUM_MSK = ( 1UL << NTP_FLASH_STAT_PEER_STRATUM ), ///< see ::NTP_FLASH_STAT_PEER_STRATUM
+ NTP_FLASH_STAT_PEER_DIST_MSK = ( 1UL << NTP_FLASH_STAT_PEER_DIST ), ///< see ::NTP_FLASH_STAT_PEER_DIST
+ NTP_FLASH_STAT_PEER_LOOP_MSK = ( 1UL << NTP_FLASH_STAT_PEER_LOOP ), ///< see ::NTP_FLASH_STAT_PEER_LOOP
+ NTP_FLASH_STAT_PEER_UNREACH_MSK = ( 1UL << NTP_FLASH_STAT_PEER_UNREACH ), ///< see ::NTP_FLASH_STAT_PEER_UNREACH
+};
+
+/*
+ * Default initializers for English ntp flash state mask. Initializers
+ * for multi-language strings can be found in tmonlstr.h.
+ */
+
+#define MBG_NTP_FLASH_STR_ENG_LABEL "Flash Status:"
+#define MBG_NTP_FLASH_STR_ENG_PKT_DUP "Duplicate packet"
+#define MBG_NTP_FLASH_STR_ENG_PKT_BOGUS "Bogus packet"
+#define MBG_NTP_FLASH_STR_ENG_PKT_UNSYNC "Server not synchronized"
+#define MBG_NTP_FLASH_STR_ENG_PKT_DENIED "Access denied"
+#define MBG_NTP_FLASH_STR_ENG_PKT_AUTH "Authentication failure"
+#define MBG_NTP_FLASH_STR_ENG_PKT_STRATUM "Invalid leap or stratum"
+#define MBG_NTP_FLASH_STR_ENG_PKT_HEADER "Header distance exceeded"
+#define MBG_NTP_FLASH_STR_ENG_PKT_AUTOKEY "Autokey sequence error"
+#define MBG_NTP_FLASH_STR_ENG_PKT_CRYPTO "Autokey protocol error"
+#define MBG_NTP_FLASH_STR_ENG_PEER_STRATUM "Invalid header or stratum"
+#define MBG_NTP_FLASH_STR_ENG_PEER_DIST "Distance threshold exceeded"
+#define MBG_NTP_FLASH_STR_ENG_PEER_LOOP "Synchronization loop"
+#define MBG_NTP_FLASH_STR_ENG_PEER_UNREACH "Unreachable or nonselect"
+
+
+#define MBG_NTP_FLASH_NAMES_ENG \
+{ \
+ MBG_NTP_FLASH_STR_ENG_PKT_DUP, \
+ MBG_NTP_FLASH_STR_ENG_PKT_BOGUS, \
+ MBG_NTP_FLASH_STR_ENG_PKT_UNSYNC, \
+ MBG_NTP_FLASH_STR_ENG_PKT_DENIED, \
+ MBG_NTP_FLASH_STR_ENG_PKT_AUTH, \
+ MBG_NTP_FLASH_STR_ENG_PKT_STRATUM, \
+ MBG_NTP_FLASH_STR_ENG_PKT_HEADER, \
+ MBG_NTP_FLASH_STR_ENG_PKT_AUTOKEY, \
+ MBG_NTP_FLASH_STR_ENG_PKT_CRYPTO, \
+ MBG_NTP_FLASH_STR_ENG_PEER_STRATUM, \
+ MBG_NTP_FLASH_STR_ENG_PEER_DIST, \
+ MBG_NTP_FLASH_STR_ENG_PEER_LOOP, \
+ MBG_NTP_FLASH_STR_ENG_PEER_UNREACH \
+}
+
+
+/**
+ * @brief Enumeration of supported NTP peer state values
+ *
+ * @see ::NTP_PEER_STATE_SUPP_FLAG_MASKS
+ */
+enum NTP_PEER_STATE_SUPP_FLAGS
+{
+ NTP_PEER_STATE_SUPP_STD = 0, ///< supports standard values of ::NTP_PEER_STATE, all fields except below and reserved
+ NTP_PEER_STATE_SUPP_ASS_ID, ///< supports association ID, see ::NTP_PEER_STATE::ass_id
+ NTP_PEER_STATE_SUPP_EVENTS, ///< supports peer state events (NTP_PEER_STATE::peer_evt_cnt, NTP_PEER_STATE::peer_rec_evt)
+ NTP_PEER_STATE_SUPP_REACH_STAT, ///< supports peer reach status, see ::NTP_PEER_STATE::peer_reach_stat
+ NTP_PEER_STATE_SUPP_PRECISION, ///< supports precision indication, see ::NTP_PEER_STATE::precision
+ NTP_PEER_STATE_SUPP_ROOT_DELAY, ///< supports root delay to syspeer, see ::NTP_PEER_STATE::root_delay
+ NTP_PEER_STATE_SUPP_ROOT_DISP, ///< supports root dispersion, see ::NTP_PEER_STATE::root_disp
+ NTP_PEER_STATE_SUPP_HEADWAY, ///< supports headway, see ::NTP_PEER_STATE::headway
+ NTP_PEER_STATE_SUPP_FLASH_STAT, ///< supports flash status word, see ::NTP_PEER_STATE::flash_stat_flags
+ NTP_PEER_STATE_SUPP_KEY_ID, ///< supports symmetric key id, see ::NTP_PEER_STATE::key_id
+ NTP_PEER_STATE_SUPP_DISP, ///< supports filter dispersion, see ::NTP_PEER_STATE::disp
+ NTP_PEER_STATE_SUPP_JITTER, ///< supports filter jitter, see ::NTP_PEER_STATE::jitter
+ NTP_PEER_STATE_SUPP_XLEAVE, ///< supports interleave delay, see ::NTP_PEER_STATE::xleave
+ N_NTP_PEER_STATE_SUPP_FLAGS
+};
+
+
+/**
+ * @brief Flag masks for NTP_PEER_STATE_SUPP_FLAGS
+ *
+ * Used with ::NTP_PEER_STATE::supp_flags
+ *
+ * @see ::NTP_PEER_STATE_SUPP_FLAGS
+ */
+enum NTP_PEER_STATE_SUPP_FLAG_MASKS
+{
+ NTP_PEER_STATE_SUPP_STD_MSK = ( 1UL << NTP_PEER_STATE_SUPP_STD ), ///< see ::NTP_PEER_STATE_SUPP_STD
+ NTP_PEER_STATE_SUPP_ASS_ID_MSK = ( 1UL << NTP_PEER_STATE_SUPP_ASS_ID ), ///< see ::NTP_PEER_STATE_SUPP_ASS_ID
+ NTP_PEER_STATE_SUPP_EVENTS_MSK = ( 1UL << NTP_PEER_STATE_SUPP_EVENTS ), ///< see ::NTP_PEER_STATE_SUPP_EVENTS
+ NTP_PEER_STATE_SUPP_REACH_STAT_MSK = ( 1UL << NTP_PEER_STATE_SUPP_REACH_STAT ), ///< see ::NTP_PEER_STATE_SUPP_REACH_STAT
+ NTP_PEER_STATE_SUPP_PRECISION_MSK = ( 1UL << NTP_PEER_STATE_SUPP_PRECISION ), ///< see ::NTP_PEER_STATE_SUPP_PRECISION
+ NTP_PEER_STATE_SUPP_ROOT_DELAY_MSK = ( 1UL << NTP_PEER_STATE_SUPP_ROOT_DELAY ), ///< see ::NTP_PEER_STATE_SUPP_ROOT_DELAY
+ NTP_PEER_STATE_SUPP_ROOT_DISP_MSK = ( 1UL << NTP_PEER_STATE_SUPP_ROOT_DISP ), ///< see ::NTP_PEER_STATE_SUPP_ROOT_DISP
+ NTP_PEER_STATE_SUPP_HEADWAY_MSK = ( 1UL << NTP_PEER_STATE_SUPP_HEADWAY ), ///< see ::NTP_PEER_STATE_SUPP_HEADWAY
+ NTP_PEER_STATE_SUPP_FLASH_STAT_MSK = ( 1UL << NTP_PEER_STATE_SUPP_FLASH_STAT ), ///< see ::NTP_PEER_STATE_SUPP_FLASH_STAT
+ NTP_PEER_STATE_SUPP_KEY_ID_MSK = ( 1UL << NTP_PEER_STATE_SUPP_KEY_ID ), ///< see ::NTP_PEER_STATE_SUPP_KEY_ID
+ NTP_PEER_STATE_SUPP_DISP_MSK = ( 1UL << NTP_PEER_STATE_SUPP_DISP ), ///< see ::NTP_PEER_STATE_SUPP_DISP
+ NTP_PEER_STATE_SUPP_JITTER_MSK = ( 1UL << NTP_PEER_STATE_SUPP_JITTER ), ///< see ::NTP_PEER_STATE_SUPP_JITTER
+ NTP_PEER_STATE_SUPP_XLEAVE_MSK = ( 1UL << NTP_PEER_STATE_SUPP_XLEAVE ), ///< see ::NTP_PEER_STATE_SUPP_XLEAVE
+};
+
+
+/**
+ * @brief Structure that represents the status of an NTP peer
+ *
+ * This structure should be requested via ::NTP_PEER_STATE_IDX
+ *
+ * @see ::NTP_PEER_STATE_IDX
+ */
+typedef struct
+{
+ uint32_t supp_flags; ///< Supported NTP peer state values, see ::NTP_PEER_STATE_SUPP_FLAG_MASKS
+
+ uint16_t ass_id; ///< Association ID of the peer
+ uint16_t peer_status_flags; ///< Peer status flags, see ::NTP_PEER_STATUS_FLAG_MASKS
+
+ uint8_t leap_ind; ///< Leap indicator, see ::NTP_LI_BITS
+ uint8_t peer_sel_stat; ///< Current selection status of the peer, see ::NTP_PEER_SEL_STATUS_BITS
+ uint8_t peer_evt_cnt; ///< Number of events, since the last time the event code changed
+ uint8_t peer_rec_evt; ///< Most recent event message, see ::NTP_PEER_EVT_BITS
+
+ uint8_t peer_reach_stat; ///< Current reach status of the peer, see ::NTP_REACH_STAT_BITS
+ uint8_t reserved_1; ///< Reserved, currently always 0
+ uint16_t reserved_2; ///< Reserved, currently always 0
+
+ MBG_IP_ADDR_PORT src_addr; ///< Source address of the NTP peer, see ::MBG_IP_ADDR_PORT
+ MBG_IP_ADDR_PORT dst_addr; ///< Destination address of the NTP peer, see ::MBG_IP_ADDR_PORT
+
+ uint8_t stratum; ///< Current stratum level of the NTP peer
+ int8_t precision; ///< Precision of the peer clock (2^precision)
+ uint16_t reserved_3; ///< Reserved, currently always 0
+
+ int32_t root_delay; ///< [us] Total roundtrip delay to the system peer of the NTP peer
+ int32_t root_disp; ///< [us] Total dispersion to the system peer of the NTP peer
+
+ MBG_IP_ADDR ref_id; ///< Reference ID of the NTP peer, see ::MBG_IP_ADDR
+
+ NTP_TSTAMP ref_time; ///< Last time the NTP peers time has been adjusted, see ::NTP_TSTAMP
+ NTP_TSTAMP rec_time; ///< Current system time of the NTP peer, see ::NTP_TSTAMP
+
+ uint8_t reach; ///< Shift register for the last 8 polling intervals
+ uint8_t reserved_4; ///< Reserved, currently always 0
+ uint16_t unreach; ///< Counter for the number of unsuccessful polling intervals
+
+ uint8_t host_mode; ///< NTP mode of the requesting host, see ::NTP_MODE_BITS
+ uint8_t peer_mode; ///< NTP mode of the peer, see ::NTP_MODE_BITS
+ uint8_t host_poll; ///< Host NTP polling interval
+ uint8_t peer_poll; ///< Peer NTP polling interval
+
+ uint8_t headway; ///< Indicator for the KoD packet, TODO: further investigation
+ uint8_t reserved_5; ///< Reserved, currently always 0
+ uint16_t flash_stat_flags; ///< Flash status flags, see ::NTP_FLASH_STAT_FLAG_MASKS
+
+ uint16_t key_id; ///< ID of symmetric authentication key
+ uint16_t reserved_6; ///< Reserved, currently always 0
+
+ int64_t offset; ///< [ns] filter offset to this NTP peer
+ int64_t delay; ///< [ns] filter delay to this NTP peer
+
+ int32_t disp; ///< [us] filter dispersion of the NTP peer
+ int32_t jitter; ///< [us] filter jitter of the NTP peer
+
+ uint32_t xleave; ///< [ns] interleave delay of the NTP peer
+
+ uint8_t n_filter_values; ///< Number of filter values available, currently always 0
+ uint8_t reserved_7; ///< Reserved, currently always 0
+ uint16_t reserved_8; ///< Reserved, currently always 0
+
+ uint32_t reserved_9; ///< Reserved, currently always 0
+
+} NTP_PEER_STATE;
+
+
+/**
+ * @brief Structure that contains an index value and the NTP peer state
+ *
+ * This structure can be requested by a monitoring program to observe the status of configured NTP peers
+ *
+ * @see ::NTP_PEER_STATE
+ */
+typedef struct
+{
+ uint32_t idx; ///< The index of the observed NTP peer
+ NTP_PEER_STATE peer_state; ///< Peer state, see ::NTP_PEER_STATE
+
+} NTP_PEER_STATE_IDX;
+
+/** @} defgroup group_ntp */
-/** @} group_ptp */
/**
@@ -5682,16 +10365,19 @@ typedef struct
#define MAX_LNO_OUTPUT 4
+/**
+ * @brief LNO status
+ */
typedef struct
{
- uint16_t sine_lvl[MAX_LNO_OUTPUT]; /**< signal levels at the outputs */
+ uint16_t sine_lvl[MAX_LNO_OUTPUT]; ///< signal levels at the outputs
- uint16_t max_sine_lvl; /**< max level of an output, e.g. 1024 */
- uint8_t n_outputs; /**< actual number of outputs [0 .. MAX_LNO_OUTPUT-1] */
- uint8_t out_enb_state; /**< e.g. bit 0 is set if corresponding output 0 is enabled, etc. */
+ uint16_t max_sine_lvl; ///< max level of an output, e.g. 1024
+ uint8_t n_outputs; ///< actual number of outputs [0..::MAX_LNO_OUTPUT-1]
+ uint8_t out_enb_state; ///< e.g. bit 0 is set if corresponding output 0 is enabled, etc.
- uint16_t reserved_0; /**< reserved, currently always 0 */
- uint16_t flags; /**< status flags as described below */
+ uint16_t reserved_0; ///< reserved, currently always 0
+ uint16_t flags; ///< status flags, see ::LNO_STATE_FLAG_BITS
} LNO_STATE;
@@ -5711,128 +10397,346 @@ typedef struct
/**
* @brief Flags used with LNO_STATE::flags
*/
-enum
+enum LNO_STATE_FLAG_BITS
{
- LNO_FLAG_BIT_PLL_LOCKED, /**< PLL is locked */
- N_LNO_FLAG_BIT /**< the number of defined bits */
+ LNO_FLAG_BIT_PLL_LOCKED, ///< PLL is locked
+ N_LNO_FLAG_BIT ///< number of known bits
};
#define LNO_FLAG_PLL_LOCKED ( 1UL << LNO_FLAG_BIT_PLL_LOCKED )
-/** @} group_lno */
+/** @} defgroup group_lno */
+
+
+
+/**
+ * @defgroup group_vst Definitions used with Versatile Storage
+ *
+ * Versatile storage is used to store binary data on a device where the storage
+ * device must not necessarily know about the data structure. It just stores
+ * a piece of data, and retrieves it on demand.
+ *
+ * The structures and associated API calls are only supported if the
+ * ::GPS_HAS_VST bit is set in ::RECEIVER_INFO::features.
+ *
+ * @{ */
+
+/**
+ * @brief Known common VST data types
+ */
+enum VST_DATA_TYPES
+{
+ VST_DATA_TYPE_MAC_ADDR, //##++++++++++++ This is just an example. More to be added.
+ N_VST_DATA_TYPES
+};
+
+
+/**
+ * @brief
+ */
+typedef struct
+{
+ uint16_t data_type; ///< data type identifier, see ::VST_DATA_TYPES for common types
+ uint16_t idx; ///< Index for several sets of the same type
+ uint16_t data_len; ///< length of the data set appended to the header
+ uint16_t reserved; ///< reserved, currently always 0
+
+} VST_HEADER;
+
+#define _mbg_swab_vst_header( _p ) \
+{ \
+ _mbg_swab16( &(_p)->data_type ); \
+ _mbg_swab16( &(_p)->idx ); \
+ _mbg_swab16( &(_p)->data_len ); \
+ _mbg_swab16( &(_p)->reserved ); \
+}
+
+/** @} defgroup group_vst */
+
+
+
+/**
+ * @defgroup group_shs Definitions used with SHS devices
+ *
+ * An SHS (Secure Hybrid System) device compares the times from 2 sources
+ * and eventually sets an alarm (warning and/or error) flag if the difference
+ * between the 2 time sources exceeds a configurable limit.
+ *
+ * These structures and associated definitions are used to query the SHS
+ * capabilities, configure the SHS device according to its capabilities,
+ * and query the SHS status.
+ *
+ * The structures and associated API calls are only supported if the
+ * ::GPS_HAS_SHS bit is set in ::RECEIVER_INFO::features.
+ *
+ * The ::SHS_INFO structure can be read to retrieve the capabilities and
+ * current settings of the device. The ::SHS_SETTINGS structure can then
+ * be set up according to the capabilities, and be written back to configure
+ * the device.
+ *
+ * If ::SHS_SETTINGS::err_limit and/or ::SHS_SETTINGS::warn_limit are
+ * not 0 then the SHS device checks if the time difference between the
+ * 2 clocks exceeds these limits and sets ::SHS_STATUS::shs_state
+ * as appropriate.
+ *
+ * If indicated by ::SHS_INFO::supp_flags the SHS device can also take
+ * certain actions if the time difference exceeds the error limit.
+ * If this happens then the same flags are set in ::SHS_STATUS::flags
+ * to indicate the action has been taken.
+ *
+ * @{ */
+
+/**
+ * @brief Current configuration of an SHS controller
+ *
+ * @see ::SHS_INFO
+ * @see ::SHS_STATUS
+ */
+typedef struct
+{
+ NANO_TIME err_limit; ///< time difference limit above which an error is indicated
+ NANO_TIME warn_limit; ///< time difference limit above which a warning is indicated
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t flags; ///< see ::SHS_FLAG_MASKS
+
+} SHS_SETTINGS;
+
+#define _mbg_swab_shs_settings( _p ) \
+{ \
+ _mbg_swab_nano_time( &(_p)->err_limit ); \
+ _mbg_swab_nano_time( &(_p)->warn_limit ); \
+ _mbg_swab32( &(_p)->reserved ); \
+ _mbg_swab32( &(_p)->flags ); \
+}
+
+
+
+/**
+ * @brief Current SHS settings and general SHS capabilities
+ *
+ * @see ::SHS_SETTINGS
+ * @see ::SHS_STATUS
+ */
+typedef struct
+{
+ SHS_SETTINGS settings; ///< current configuration settings
+ NANO_TIME max_limit; ///< if not 0, the max. allowed value for ::SHS_SETTINGS::err_limit and ::SHS_SETTINGS::warn_limit
+ uint32_t reserved; ///< reserved, currently always 0
+ uint32_t supp_flags; ///< indicates which flags are supported for ::SHS_SETTINGS::flags, see ::SHS_FLAG_MASKS
+
+} SHS_INFO;
+
+#define _mbg_swab_shs_info( _p ) \
+{ \
+ _mbg_swab_shs_settings( &(_p)->settings ); \
+ _mbg_swab_nano_time( &(_p)->max_limit ); \
+ _mbg_swab32( &(_p)->reserved ); \
+ _mbg_swab32( &(_p)->flags ); \
+}
+
+
+
+/**
+ * @brief Current SHS status
+ */
+typedef struct
+{
+ NANO_TIME time_diff; ///< current time difference between the 2 clocks
+ TM_STATUS_EXT clk_status_1; ///< status of first clock
+ TM_STATUS_EXT clk_status_2; ///< status of second clock
+ uint8_t shs_state; ///< see ::SHS_STATES
+ uint8_t reserved_1; ///< reserved, currently always 0
+ uint16_t reserved_2; ///< reserved, currently always 0
+ uint32_t flags; ///< see ::SHS_FLAG_MASKS
+
+} SHS_STATUS;
+
+#define _mbg_swab_shs_status( _p ) \
+{ \
+ _mbg_swab_nano_time( &(_p)->time_diff ); \
+ _mbg_swab32( &(_p)->clk_status_1 ); \
+ _mbg_swab32( &(_p)->clk_status_2 ); \
+ _mbg_swab16( &(_p)->reserved_2 ); \
+ _mbg_swab32( &(_p)->flags ); \
+}
+
+
+
+/**
+ * @brief SHS configuration flag bits
+ *
+ * Codes used with ::SHS_STATUS::shs_state
+ */
+enum SHS_STATES
+{
+ SHS_STATE_DISABLED, ///< time difference not checked, eventually no limits configured
+ SHS_STATE_OK, ///< time difference OK, below warning limit
+ SHS_STATE_WARNING, ///< time difference exceeds warning limit
+ SHS_STATE_ERROR, ///< time difference exceeds error limit
+ SHS_STATE_FATAL, ///< one or both time sources disconnected
+ N_SHS_STATES
+};
+
+
+
+/**
+ * @brief SHS flag bits
+ *
+ * @see ::SHS_FLAG_MASKS
+ */
+enum SHS_FLAG_BITS
+{
+ SHS_FLAG_BIT_DISB_SERIAL, ///< disable serial output in state ::SHS_STATE_ERROR
+ SHS_FLAG_BIT_DISB_PPS, ///< disable PPS output in state ::SHS_STATE_ERROR
+ SHS_FLAG_BIT_DISB_10MHZ, ///< disable 10 MHz output in state ::SHS_STATE_ERROR
+ N_SHS_FLAG_BITS
+};
+
+
+/**
+ * @brief SHS flag masks
+ *
+ * With ::SHS_INFO::supp_flags these flags indicate what is supported
+ * by the SHS controller, e.g. what action can be taken automatically.
+ * Each bit set in ::SHS_INFO::supp_flags can be set by a configuration
+ * tool in ::SHS_SETTINGS::flags to enable the associated feature.
+ * If a corresponding bit is set in ::SHS_STATUS::flags this means the
+ * associated feature has been enabled, e.g. an action has been taken.
+ *
+ * @see ::SHS_FLAG_BITS
+ */
+enum SHS_FLAG_MASKS
+{
+ SHS_FLAG_DISB_SERIAL = ( 1UL << SHS_FLAG_BIT_DISB_SERIAL ), ///< see ::SHS_FLAG_BIT_DISB_SERIAL
+ SHS_FLAG_DISB_PPS = ( 1UL << SHS_FLAG_BIT_DISB_PPS ), ///< see ::SHS_FLAG_BIT_DISB_PPS
+ SHS_FLAG_DISB_10MHZ = ( 1UL << SHS_FLAG_BIT_DISB_10MHZ ) ///< see ::SHS_FLAG_BIT_DISB_10MHZ
+};
+
+/** @} defgroup group_shs */
+
/*------------------------------------------------------------------------*/
-/* Ephemeris parameters of one specific SV. Needed to compute the position */
-/* of a satellite at a given time with high precision. Valid for an */
-/* interval of 4 to 6 hours from start of transmission. */
-
-typedef struct
-{
- CSUM csum; /* checksum of the remaining bytes */
- int16_t valid; /* flag data are valid */
-
- HEALTH health; /* health indication of transmitting SV [---] */
- IOD IODC; /* Issue Of Data, Clock */
- IOD IODE2; /* Issue of Data, Ephemeris (Subframe 2) */
- IOD IODE3; /* Issue of Data, Ephemeris (Subframe 3) */
- T_GPS tt; /* time of transmission */
- T_GPS t0c; /* Reference Time Clock [---] */
- T_GPS t0e; /* Reference Time Ephemeris [---] */
-
- double sqrt_A; /* Square Root of semi-major Axis [sqrt(m)] */
- double e; /* Eccentricity [---] */
- double M0; /* +- Mean Anomaly at Ref. Time [rad] */
- double omega; /* +- Argument of Perigee [rad] */
- double OMEGA0; /* +- Longit. of Asc. Node of orbit plane [rad] */
- double OMEGADOT; /* +- Rate of Right Ascension [rad/sec] */
- double deltan; /* +- Mean Motion Diff. from computed value [rad/sec] */
- double i0; /* +- Inclination Angle [rad] */
- double idot; /* +- Rate of Inclination Angle [rad/sec] */
- double crc; /* +- Cosine Corr. Term to Orbit Radius [m] */
- double crs; /* +- Sine Corr. Term to Orbit Radius [m] */
- double cuc; /* +- Cosine Corr. Term to Arg. of Latitude [rad] */
- double cus; /* +- Sine Corr. Term to Arg. of Latitude [rad] */
- double cic; /* +- Cosine Corr. Term to Inclination Angle [rad] */
- double cis; /* +- Sine Corr. Term to Inclination Angle [rad] */
-
- double af0; /* +- Clock Correction Coefficient 0 [sec] */
- double af1; /* +- Clock Correction Coefficient 1 [sec/sec] */
- double af2; /* +- Clock Correction Coefficient 2 [sec/sec^2] */
- double tgd; /* +- estimated group delay differential [sec] */
-
- uint16_t URA; /* predicted User Range Accuracy */
-
- uint8_t L2code; /* code on L2 channel [---] */
- uint8_t L2flag; /* L2 P data flag [---] */
-} EPH;
+/**
+ * @brief Ephemeris parameters of one specific satellite
+ *
+ * Needed to compute the position of a satellite at a given time with
+ * high precision. Valid for an interval of 4 to 6 hours from start
+ * of transmission.
+ */
+typedef struct
+{
+ CSUM csum; ///< checksum of the remaining bytes
+ int16_t valid; ///< flag data are valid
+
+ HEALTH health; ///< health indication of transmitting SV [---]
+ IOD IODC; ///< Issue Of Data, Clock
+ IOD IODE2; ///< Issue of Data, Ephemeris (Subframe 2)
+ IOD IODE3; ///< Issue of Data, Ephemeris (Subframe 3)
+ T_GPS tt; ///< time of transmission
+ T_GPS t0c; ///< Reference Time Clock [---]
+ T_GPS t0e; ///< Reference Time Ephemeris [---]
+
+ double sqrt_A; ///< Square Root of semi-major Axis [sqrt(m)]
+ double e; ///< Eccentricity [---]
+ double M0; ///< +- Mean Anomaly at Ref. Time [rad]
+ double omega; ///< +- Argument of Perigee [rad]
+ double OMEGA0; ///< +- Longit. of Asc. Node of orbit plane [rad]
+ double OMEGADOT; ///< +- Rate of Right Ascension [rad/sec]
+ double deltan; ///< +- Mean Motion Diff. from computed value [rad/sec]
+ double i0; ///< +- Inclination Angle [rad]
+ double idot; ///< +- Rate of Inclination Angle [rad/sec]
+ double crc; ///< +- Cosine Corr. Term to Orbit Radius [m]
+ double crs; ///< +- Sine Corr. Term to Orbit Radius [m]
+ double cuc; ///< +- Cosine Corr. Term to Arg. of Latitude [rad]
+ double cus; ///< +- Sine Corr. Term to Arg. of Latitude [rad]
+ double cic; ///< +- Cosine Corr. Term to Inclination Angle [rad]
+ double cis; ///< +- Sine Corr. Term to Inclination Angle [rad]
+
+ double af0; ///< +- Clock Correction Coefficient 0 [sec]
+ double af1; ///< +- Clock Correction Coefficient 1 [sec/sec]
+ double af2; ///< +- Clock Correction Coefficient 2 [sec/sec^2]
+ double tgd; ///< +- estimated group delay differential [sec]
+
+ uint16_t URA; ///< predicted User Range Accuracy
+
+ uint8_t L2code; ///< code on L2 channel [---]
+ uint8_t L2flag; ///< L2 P data flag [---]
+} EPH;
-/* Almanac parameters of one specific SV. A reduced precision set of */
-/* parameters used to check if a satellite is in view at a given time. */
-/* Valid for an interval of more than 7 days from start of transmission. */
+/**
+ * @brief Almanac parameters of one specific satellite
+ *
+ * A reduced precision set of parameters used to check if a satellite
+ * is in view at a given time. Valid for an interval of more than 7 days
+ * from start of transmission.
+ */
typedef struct
{
- CSUM csum; /* checksum of the remaining bytes */
- int16_t valid; /* flag data are valid */
+ CSUM csum; ///< checksum of the remaining bytes
+ int16_t valid; ///< flag data are valid
- HEALTH health; /* [---] */
- T_GPS t0a; /* Reference Time Almanac [sec] */
+ HEALTH health; ///< [---]
+ T_GPS t0a; ///< Reference Time Almanac [sec]
- double sqrt_A; /* Square Root of semi-major Axis [sqrt(m)] */
- double e; /* Eccentricity [---] */
+ double sqrt_A; ///< Square Root of semi-major Axis [sqrt(m)]
+ double e; ///< Eccentricity [---]
- double M0; /* +- Mean Anomaly at Ref. Time [rad] */
- double omega; /* +- Argument of Perigee [rad] */
- double OMEGA0; /* +- Longit. of Asc. Node of orbit plane [rad] */
- double OMEGADOT; /* +- Rate of Right Ascension [rad/sec] */
- double deltai; /* +- [rad] */
- double af0; /* +- Clock Correction Coefficient 0 [sec] */
- double af1; /* +- Clock Correction Coefficient 1 [sec/sec] */
-} ALM;
+ double M0; ///< +- Mean Anomaly at Ref. Time [rad]
+ double omega; ///< +- Argument of Perigee [rad]
+ double OMEGA0; ///< +- Longit. of Asc. Node of orbit plane [rad]
+ double OMEGADOT; ///< +- Rate of Right Ascension [rad/sec]
+ double deltai; ///< +- [rad]
+ double af0; ///< +- Clock Correction Coefficient 0 [sec]
+ double af1; ///< +- Clock Correction Coefficient 1 [sec/sec]
+} ALM;
-/* Summary of configuration and health data of all SVs. */
+/**
+ * @brief Summary of configuration and health data of all satellites
+ */
typedef struct
{
- CSUM csum; /* checksum of the remaining bytes */
- int16_t valid; /* flag data are valid */
+ CSUM csum; ///< checksum of the remaining bytes
+ int16_t valid; ///< flag data are valid
+
+ T_GPS tot_51; ///< time of transmission, page 51
+ T_GPS tot_63; ///< time of transmission, page 63
+ T_GPS t0a; ///< complete reference time almanac
- T_GPS tot_51; /* time of transmission, page 51 */
- T_GPS tot_63; /* time of transmission, page 63 */
- T_GPS t0a; /* complete reference time almanac */
+ CFG cfg[N_SVNO_GPS]; ///< SV configuration from page 63
+ HEALTH health[N_SVNO_GPS]; ///< SV health from pages 51, 63
- CFG cfg[N_SVNO]; /* SV configuration from page 63 */
- HEALTH health[N_SVNO]; /* SV health from pages 51, 63 */
} CFGH;
/**
- * @brief GPS UTC correction parameters
+ * @brief GPS %UTC correction parameters
*
- * UTC correction parameters basically as sent by the GPS satellites.
+ * %UTC correction parameters basically as sent by the GPS satellites.
*
- * The CSUM field is only used by the card's firmware to check the
+ * The csum field is only used by the card's firmware to check the
* consistency of the structure in non-volatile memory.
*
* The field labeled valid indicates if the parameter set is valid, i.e.
* if it contains data received from the satellites.
*
* t0t, A0 and A1 contain fractional correction parameters for the current
- * GPS-UTC time offset in addition to the whole seconds. This is evaluated
- * by the receivers' firmware to convert GPS time to UTC time.
+ * GPS-%UTC time offset in addition to the whole seconds. This is evaluated
+ * by the receivers' firmware to convert GPS time to %UTC time.
*
* The delta_tls field contains the current full seconds offset between
- * GPS time and UTC, which corresponds to the number of leap seconds inserted
- * into the UTC time scale since GPS was put into operation in January 1980.
+ * GPS time and %UTC, which corresponds to the number of leap seconds inserted
+ * into the %UTC time scale since GPS was put into operation in January 1980.
*
- * delta_tlfs holds the number of "future" leap seconds, i.e. the UTC offset
+ * delta_tlfs holds the number of "future" leap seconds, i.e. the %UTC offset
* after the next leap second event defined by WNlsf and DNt.
*
* The fields WNlsf and DNt specify the GPS week number and the day number
@@ -5850,17 +10754,18 @@ typedef struct
*/
typedef struct
{
- CSUM csum; /**< Checksum of the remaining bytes */
- int16_t valid; /**< Flag indicating UTC parameters are valid */
+ CSUM csum; ///< Checksum of the remaining bytes
+ int16_t valid; ///< Flag indicating %UTC parameters are valid
- T_GPS t0t; /**< Reference Time UTC Parameters [wn|sec] */
- double A0; /**< +- Clock Correction Coefficient 0 [sec] */
- double A1; /**< +- Clock Correction Coefficient 1 [sec/sec] */
+ T_GPS t0t; ///< Reference Time %UTC Parameters [wn|sec]
+ double A0; ///< +- Clock Correction Coefficient 0 [sec]
+ double A1; ///< +- Clock Correction Coefficient 1 [sec/sec]
+
+ uint16_t WNlsf; ///< Week number of nearest leap second
+ int16_t DNt; ///< The day number at the end of which a leap second occurs
+ int8_t delta_tls; ///< Current %UTC offset to GPS system time [sec]
+ int8_t delta_tlsf; ///< Future %UTC offset to GPS system time after next leap second transition [sec]
- uint16_t WNlsf; /**< Week number of nearest leap second */
- int16_t DNt; /**< The day number at the end of which a leap second occurs */
- int8_t delta_tls; /**< Current UTC offset to GPS system time [sec] */
- int8_t delta_tlsf; /**< Future UTC offset to GPS system time after next leap second transition [sec] */
} UTC;
#define _mbg_swab_utc_parm( _p ) \
@@ -5876,38 +10781,42 @@ typedef struct
-/* Ionospheric correction parameters */
-
+/**
+ * @brief Ionospheric correction parameters
+ */
typedef struct
{
- CSUM csum; /* checksum of the remaining bytes */
- int16_t valid; /* flag data are valid */
+ CSUM csum; ///< checksum of the remaining bytes
+ int16_t valid; ///< flag data are valid
- double alpha_0; /* Ionosph. Corr. Coeff. Alpha 0 [sec] */
- double alpha_1; /* Ionosph. Corr. Coeff. Alpha 1 [sec/deg] */
- double alpha_2; /* Ionosph. Corr. Coeff. Alpha 2 [sec/deg^2] */
- double alpha_3; /* Ionosph. Corr. Coeff. Alpha 3 [sec/deg^3] */
+ double alpha_0; ///< Ionosph. Corr. Coeff. Alpha 0 [sec]
+ double alpha_1; ///< Ionosph. Corr. Coeff. Alpha 1 [sec/deg]
+ double alpha_2; ///< Ionosph. Corr. Coeff. Alpha 2 [sec/deg^2]
+ double alpha_3; ///< Ionosph. Corr. Coeff. Alpha 3 [sec/deg^3]
- double beta_0; /* Ionosph. Corr. Coeff. Beta 0 [sec] */
- double beta_1; /* Ionosph. Corr. Coeff. Beta 1 [sec/deg] */
- double beta_2; /* Ionosph. Corr. Coeff. Beta 2 [sec/deg^2] */
- double beta_3; /* Ionosph. Corr. Coeff. Beta 3 [sec/deg^3] */
-} IONO;
+ double beta_0; ///< Ionosph. Corr. Coeff. Beta 0 [sec]
+ double beta_1; ///< Ionosph. Corr. Coeff. Beta 1 [sec/deg]
+ double beta_2; ///< Ionosph. Corr. Coeff. Beta 2 [sec/deg^2]
+ double beta_3; ///< Ionosph. Corr. Coeff. Beta 3 [sec/deg^3]
+} IONO;
-/* GPS ASCII message */
+/**
+ * @brief GPS ASCII message
+ */
typedef struct
{
- CSUM csum; /* checksum of the remaining bytes */
- int16_t valid; /* flag data are valid */
- char s[23]; /* 22 chars GPS ASCII message plus trailing zero */
+ CSUM csum; ///< checksum of the remaining bytes */
+ int16_t valid; ///< flag data are valid
+ char s[23]; ///< 22 chars GPS ASCII message plus trailing zero
+
} ASCII_MSG;
-enum
+enum GPS_PLATFORMS
{
GPS_PLATFORM_PORTABLE,
GPS_PLATFORM_FIXED,
@@ -5937,11 +10846,12 @@ enum
-enum
+enum TIME_MODES
{
TIME_MODE_DISABLED,
TIME_MODE_SURVEY_IN,
- TIME_MODE_FIXED
+ TIME_MODE_FIXED,
+ N_TIME_MODES
};
@@ -5955,15 +10865,16 @@ typedef struct
int32_t fixedPosY; // cm
int32_t fixedPosZ; // cm
uint32_t fixedPosVar; // cm
- uint32_t flags; // currently 0
- uint32_t reserved; // currently 0
+ uint32_t flags; // currently 0
+ uint32_t reserved; // currently 0
+
} NAV_TIME_MODE_SETTINGS;
/**
- Navigation Engine settings to set configuration
- parameters of a dynamic platform model.
-*/
+ * Navigation Engine settings to set configuration
+ * parameters of a dynamic platform model.
+ */
typedef struct
{
uint8_t dynamic_platform;
@@ -5975,6 +10886,7 @@ typedef struct
uint32_t flags; // currently 0
uint32_t reserved; // currently 0
NAV_TIME_MODE_SETTINGS nav_time_mode_settings;
+
} NAV_ENGINE_SETTINGS;
diff --git a/c/mbglib/include/gpsutils.h b/c/mbglib/include/gpsutils.h
index 476a5c1..c2143ca 100644
--- a/c/mbglib/include/gpsutils.h
+++ b/c/mbglib/include/gpsutils.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: gpsutils.h 1.4.1.2 2010/07/15 09:19:04Z martin REL_M $
+ * $Id: gpsutils.h 1.7 2010/07/15 09:32:09Z martin REL_M $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -10,10 +10,12 @@
*
* -----------------------------------------------------------------------
* $Log: gpsutils.h $
- * Revision 1.4.1.2 2010/07/15 09:19:04Z martin
+ * Revision 1.7 2010/07/15 09:32:09Z martin
* Use DEG character definition from pcpslstr.h.
- * Revision 1.4.1.1 2003/05/15 09:40:25Z martin
- * Changed degree string/char for QNX.
+ * Revision 1.6 2005/02/18 10:32:33Z martin
+ * Check more predefined macros to determine if compiling for Windows.
+ * Revision 1.5 2003/02/04 09:18:48Z MARTIN
+ * Updated function prototypes.
* Revision 1.4 2002/12/12 16:08:11 martin
* Definitions for degree character.
* Requires mbggeo.h.
@@ -62,7 +64,9 @@ extern "C" {
void swap_iono_doubles( IONO *ionop ) ;
void swap_pos_doubles( POS *posp ) ;
void sprint_dms( char *s, DMS *pdms, int prec ) ;
+ void sprint_alt( char *s, double alt ) ;
void sprint_pos_geo( char *s, POS *ppos, const char *sep, int prec ) ;
+ void sprint_fixed_freq( char *s, FIXED_FREQ_INFO *p_ff ) ;
/* ----- function prototypes end ----- */
diff --git a/c/mbglib/include/lan_util.h b/c/mbglib/include/lan_util.h
new file mode 100644
index 0000000..ede3818
--- /dev/null
+++ b/c/mbglib/include/lan_util.h
@@ -0,0 +1,597 @@
+
+/**************************************************************************
+ *
+ * $Id: lan_util.h 1.5.1.2 2014/05/19 14:46:14Z martin TRASH $
+ *
+ * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
+ *
+ * Description:
+ * Definitions and prototypes for lan_util.c.
+ *
+ * -----------------------------------------------------------------------
+ * $Log: lan_util.h $
+ * Revision 1.5.1.2 2014/05/19 14:46:14Z martin
+ * Fixed comment grammar.
+ * Revision 1.5.1.1 2014/01/31 14:45:24 martin
+ * Revision 1.5 2013/10/02 07:20:36 martin
+ * Updated function prototypes.
+ * Revision 1.4 2013/02/19 15:15:53 martin
+ * Added some inline functions.
+ * Redefined return codes as named enum.
+ * Updated function prototypes.
+ * Revision 1.3 2012/10/02 18:24:29 martin
+ * Added some macros to simpliy conversion to string.
+ * Revision 1.2 2012/03/09 08:51:44 martin
+ * Updated function prototypes.
+ * Revision 1.1 2011/03/04 10:01:32 martin
+ * Initial revision.
+ *
+ **************************************************************************/
+
+#ifndef _LAN_UTIL_H
+#define _LAN_UTIL_H
+
+
+/* Other headers to be included */
+
+#include <mbg_tgt.h>
+#include <gpsdefs.h> // for some Meinberg data structures
+
+#include <stdlib.h>
+
+#if defined( MBG_TGT_POSIX )
+ #include <sys/types.h>
+ #include <sys/socket.h>
+ #include <net/if.h>
+#else
+ // A dummy declaration to prevent from warnings due to usage
+ // of this type with function prototypes.
+ struct ifreq
+ {
+ int dummy;
+ };
+#endif
+
+
+#if defined( IFHWADDRLEN ) // usually defined in net/if.h
+ #if ( IFHWADDRLEN != 6 )
+ #error Warning: IFHWADDRLEN is not 6!
+ #endif
+#endif
+
+
+
+#ifdef _LAN_UTIL
+ #define _ext
+ #define _DO_INIT
+#else
+ #define _ext extern
+#endif
+
+
+/* Start of header body */
+
+#if defined( _USE_PACK )
+ #pragma pack( 1 ) // set byte alignment
+ #define _USING_BYTE_ALIGNMENT
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+#if !defined( MAC_SEP_CHAR )
+ #define MAC_SEP_CHAR ':' // character used to separate octets of a MAC ID
+#endif
+
+#if !defined( MAC_SEP_CHAR_ALT )
+ #define MAC_SEP_CHAR_ALT '-' // alternate character
+#endif
+
+
+/**
+ * @brief Return codes for the LAN utility functions
+ */
+enum MBG_LU_CODES
+{
+ MBG_LU_SUCCESS = 0, ///< success
+ MBG_LU_ERR_NSUPP = -1, ///< function not supported
+ MBG_LU_ERR_PORT_NAME = -2, ///< port name exceeds max length
+ MBG_LU_ERR_SOCKET = -3, ///< failed to open socket
+ MBG_LU_ERR_IOCTL = -4, ///< IOCTL call failed
+ MBG_LU_ERR_NOT_SET = -5, ///< octets are all 0
+ MBG_LU_ERR_BUFF_SZ = -6, ///< buffer size too small
+ MBG_LU_ERR_FMT = -7, ///< parameter format not correct
+ MBG_LU_ERR_RANGE = -8 ///< range for some parameter exceeded
+};
+
+
+#define MAX_IP4_BITS ( 8 * sizeof( IP4_ADDR ) )
+
+#define IP4_MSB_MASK ( 1UL << ( MAX_IP4_BITS - 1 ) )
+
+#define MIN_IP4_CIDR_NETMASK_BITS 0
+#define MAX_IP4_CIDR_NETMASK_BITS MAX_IP4_BITS
+
+
+
+/**
+ * @brief Compute an IP4 net mask according to the number of CIDR netmask bits
+ *
+ * E.g. the 24 bits mentioned in "172.16.3.250/24" result in 0xFFFFFF00,
+ * corresponding to 255.255.255.0 in dotted quad notation.
+ *
+ * @param netmask_bits Number of netmask bits from CIDR notation
+ *
+ * @return The IP4 net mask
+ *
+ * @see get_ip4_net_mask_bits()
+ */
+static __mbg_inline
+IP4_ADDR ip4_net_mask_from_cidr( int netmask_bits )
+{
+ return (IP4_ADDR) ~( ( 1UL << ( MAX_IP4_BITS - netmask_bits ) ) - 1 );
+
+} // ip4_net_mask_from_cidr
+
+
+
+/**
+ * @brief Determine the broadcast address for an IP4 address plus net mask
+ *
+ * E.g. IP 0xAC1003FA, net mask 0xFFFFFF00 yields broadcast addr 0xAC1003FF.
+ * In dotted quad notation, IP 172.16.3.250 with net mask 255.255.255.0
+ * result in broadcast address 172.16.3.255.
+ *
+ * @param p_addr The full IP4 address
+ * @param p_mask The IP4 net mask
+ *
+ * @return The determined IP4 broadcast address
+ */
+static __mbg_inline
+IP4_ADDR ip4_broad_addr_from_addr( const IP4_ADDR *p_addr, const IP4_ADDR *p_mask )
+{
+ return *p_addr | ~(*p_mask);
+
+} // ip4_broad_addr_from_addr
+
+
+
+/**
+ * @brief Determine the network part of an IP4 address based on the net mask
+ *
+ * E.g. IP 0xAC1003FA, net mask 0xFFFFFF00 yields network part 0xAC100300.
+ * In dotted quad notation, IP 172.16.3.250 with net mask 255.255.255.0
+ * results in network part 172.16.3.0.
+ *
+ * @param p_addr The full IP4 address
+ * @param p_mask The IP4 net mask
+ *
+ * @return The network part of the IP4 address
+ */
+static __mbg_inline
+IP4_ADDR ip4_net_part_from_addr( const IP4_ADDR *p_addr, const IP4_ADDR *p_mask )
+{
+ return *p_addr & *p_mask;
+
+} // ip4_net_part_from_addr
+
+
+
+/**
+ * @brief Check if two IP4 addresses have the same network part.
+ *
+ * @param p_addr1 The first IP4 address to check
+ * @param p_addr2 The second IP4 address to check
+ * @param p_mask The IP4 net mask
+ *
+ * @return true, if the network parts are matching
+ */
+static __mbg_inline
+int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2,
+ const IP4_ADDR *p_mask )
+{
+ return ip4_net_part_from_addr( p_addr1, p_mask )
+ == ip4_net_part_from_addr( p_addr2, p_mask );
+
+} // ip4_net_part_matches
+
+
+
+#define _ip4_addr_to_str( _s, _a ) \
+ snprint_ip4_addr( _s, sizeof( _s ), _a, NULL )
+
+#define _mac_addr_to_str( _s, _a ) \
+ snprint_mac_addr( _s, sizeof( _s ), _a )
+
+
+
+/* function prototypes: */
+
+/* ----- function prototypes begin ----- */
+
+/* This section was generated automatically */
+/* by MAKEHDR, do not remove the comments. */
+
+ /**
+ * @brief Count the number of sequential bits set starting from MSB
+ *
+ * E.g. for 0xC0 and 0xC1 the results are both 2 since only
+ * the 2 MSBs are sequentially set.
+ *
+ * @param p_mask The IP4 net mask
+ *
+ * @return The number of sequential MSB bits set in val
+ *
+ * @see ip4_net_mask_from_cidr
+ */
+ int get_ip4_net_mask_bits( const IP4_ADDR *p_mask ) ;
+
+ /**
+ * @brief Print an IPv4 address to a dotted quad format string.
+ *
+ * @param s The string buffer into which to print
+ * @param max_len Maximum length of the string, i.e. size of the buffer
+ * @param p_addr The IPv4 address
+ * @param info An optional string which is prepended to the string, or NULL
+ *
+ * @return The overall number of characters printed to the string
+ *
+ * @see snprint_ip4_cidr_addr
+ * @see str_to_ip4_addr
+ * @see cidr_str_to_ip4_addr_and_net_mask
+ */
+ int snprint_ip4_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, const char *info ) ;
+
+ /**
+ * @brief Print an IPv4 address plus net mask to string in CIDR notation.
+ *
+ * The printed CIDR string is something like "172.16.3.250/24"
+ *
+ * @param s The string buffer into which to print
+ * @param max_len Maximum length of the string, i.e. size of the buffer
+ * @param p_addr The IPv4 address
+ * @param p_mask The IPv4 net mask
+ * @param info An optional string which is prepended to the string, or NULL
+ *
+ * @return The overall number of characters printed to the string
+ *
+ * @see snprint_ip4_addr
+ * @see str_to_ip4_addr
+ * @see cidr_str_to_ip4_addr_and_net_mask
+ */
+ int snprint_ip4_cidr_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, const IP4_ADDR *p_mask, const char *info ) ;
+
+ /**
+ * @brief Convert a string to an IP4_ADDR.
+ *
+ * @param p_addr Pointer to the IP4_ADDR variable, or NULL, in which case this
+ * function can be used to check if the string is formally correct.
+ * @param s The string to be converted
+ *
+ * @return >= 0 on success, number of characters evaluated from the input string
+ * -1 if invalid number found in string
+ * -2 if separator is not a dot '.'
+ *
+ * @see snprint_ip4_addr
+ * @see snprint_ip4_cidr_addr
+ * @see cidr_str_to_ip4_addr_and_net_mask
+ */
+ int str_to_ip4_addr( IP4_ADDR *p_addr, const char *s ) ;
+
+ /**
+ * @brief Convert a string in CIDR notation to an IP4_ADDR and net mask.
+ *
+ * @param p_addr Pointer to an IP4_ADDR variable for the IP4 address,
+ * or NULL, in which case this function can be used
+ * to check if the string is formally correct.
+ * @param p_mask Pointer to an IP4_ADDR variable for the net mask,
+ * or NULL, in which case this function can be used
+ * to check if the string is formally correct.
+ * @param cidr_str The string to be converted, in CIDR format, e.g. "172.16.3.250/24"
+ *
+ * @return >= 0 on success, number of characters evaluated from the input string
+ * one of the ::MBG_LU_CODES on error
+ *
+ * @see snprint_ip4_addr
+ * @see snprint_ip4_cidr_addr
+ * @see str_to_ip4_addr
+ */
+ int cidr_str_to_ip4_addr_and_net_mask( IP4_ADDR *p_addr, IP4_ADDR *p_mask, const char *cidr_str ) ;
+
+ /**
+ * @brief Print a MAC ID or similar array of octets to a string.
+ *
+ * @param s The string buffer into which to print
+ * @param max_len Maximum length of the string, i.e. size of the buffer
+ * @param octets An array of octets
+ * @param num_octets The number of octets to be printed from the array
+ * @param sep The separator printed between the bytes, or 0
+ * @param info An optional string which is prepended to the output, or NULL
+ *
+ * @return The overall number of characters printed to the string
+ *
+ * @see snprint_mac_addr
+ * @see str_to_octets
+ * @see check_octets_not_all_zero
+ */
+ int snprint_octets( char *s, size_t max_len, const uint8_t *octets, int num_octets, char sep, const char *info ) ;
+
+ /**
+ * @brief Print a MAC address to a string.
+ *
+ * @param s The string buffer into which to print
+ * @param max_len Maximum length of the string, i.e. size of the buffer
+ * @param p_mac_addr The MAC address to be printed
+ *
+ * @return The overall number of characters printed to the string
+ *
+ * @see snprint_octets
+ * @see str_to_octets
+ * @see check_octets_not_all_zero
+ */
+ int snprint_mac_addr( char *s, size_t max_len, const MBG_MAC_ADDR *p_mac_addr ) ;
+
+ /**
+ * @brief Set a MAC ID or a similar array of octets from a string.
+ *
+ * @param octets An array of octets to be set up
+ * @param num_octets The number of octets which can be stored
+ * @param s The string to be converted
+ *
+ * @return The overall number of octets decoded from the string
+ *
+ * @see snprint_octets
+ * @see snprint_mac_addr
+ * @see check_octets_not_all_zero
+ */
+ int str_to_octets( uint8_t *octets, int num_octets, const char *s ) ;
+
+ /**
+ * @brief Check if an array of octets is valid, i.e. != 0
+ *
+ * @param octets Pointer to the array of octets
+ * @param num_octets Number of octets
+ *
+ * @return MBG_LU_SUCCESS octets are valid, i.e. not all 0
+ * MBG_LU_ERR_NOT_SET octets are invalid, i.e. all 0
+ *
+ * @see snprint_octets
+ * @see snprint_mac_addr
+ * @see str_to_octets
+ */
+ int check_octets_not_all_zero( const uint8_t *octets, int num_octets ) ;
+
+ /**
+ * @brief Check if an array of octets is valid, i.e. != 0
+ *
+ * @param p_addr Pointer to a MAC address
+ *
+ * @return MBG_LU_SUCCESS MAC address is valid, i.e. not all 0
+ * MBG_LU_ERR_NOT_SET MAC address is invalid, i.e. all 0
+ *
+ * @see check_octets_not_all_zero
+ */
+ int check_mac_addr_not_all_zero( const MBG_MAC_ADDR *p_addr ) ;
+
+ /**
+ * @brief Do a SIOCGxxx IOCTL call to read specific information from a LAN interface
+ *
+ * @param if_name Name of the interface
+ * @param ioctl_code One of the predefined system SIOCGxxx IOCTL codes
+ * @param p_ifreq Pointer to a request buffer
+ *
+ * @return one of the ::MBG_LU_CODES
+ */
+ int do_siocg_ioctl( const char *if_name, int ioctl_code, struct ifreq *p_ifreq ) ;
+
+ /**
+ * @brief Retrieve the index of a specific network interface
+ *
+ * @param if_name Name of the interface
+ * @param p_intf_idx Pointer to a variable to be filled up
+ *
+ * @return one of the ::MBG_LU_CODES
+ * on error the MAC addr is set to all 0
+ *
+ * @see get_port_mac_addr_check
+ */
+ int get_port_intf_idx( const char *if_name, int *p_intf_idx ) ;
+
+ /**
+ * @brief Retrieve the MAC address of a network interface
+ *
+ * @param if_name Name of the interface
+ * @param p_mac_addr Pointer to the MAC address buffer to be filled up
+ *
+ * @return one of the ::MBG_LU_CODES
+ * on error the MAC addr is set to all 0
+ *
+ * @see get_port_mac_addr_check
+ */
+ int get_port_mac_addr( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) ;
+
+ /**
+ * @brief Retrieve and check the MAC address of a network interface
+ *
+ * @param if_name Name of the interface
+ * @param p_mac_addr Pointer to the MAC address buffer to be filled up
+ *
+ * @return one of the ::MBG_LU_CODES
+ * on error the MAC addr is set to all 0
+ *
+ * @see get_port_mac_addr
+ */
+ int get_port_mac_addr_check( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) ;
+
+ /**
+ * @brief Check the link state of a network interface
+ *
+ * @param if_name Name of the interface
+ *
+ * @return 1 link detected on port
+ * 0 no link detected on port
+ * one of the ::MBG_LU_CODES in case of an error
+ */
+ int check_port_link( const char *if_name ) ;
+
+ /**
+ * @brief Retrieve the IPv4 address of a network interface
+ *
+ * @param if_name Name of the interface
+ * @param p_addr Pointer to address field to be filled up
+ *
+ * @return one of the ::MBG_LU_CODES
+ *
+ * @see get_port_ip4_settings
+ * @see get_port_ip4_addr_str
+ * @see get_port_ip4_netmask
+ * @see get_port_ip4_netmask_str
+ * @see get_port_ip4_broad_addr
+ * @see get_port_ip4_broad_addr_str
+ * @see get_specific_port_ip4_addr
+ */
+ int get_port_ip4_addr( const char *if_name, IP4_ADDR *p_addr ) ;
+
+ /**
+ * @brief Retrieve the IPv4 net mask of a network interface
+ *
+ * @param if_name Name of the interface
+ * @param p_addr Pointer to address field to be filled up
+ *
+ * @return one of the ::MBG_LU_CODES
+ *
+ * @see get_port_ip4_settings
+ * @see get_port_ip4_addr
+ * @see get_port_ip4_addr_str
+ * @see get_port_ip4_netmask_str
+ * @see get_port_ip4_broad_addr
+ * @see get_port_ip4_broad_addr_str
+ * @see get_specific_port_ip4_addr
+ */
+ int get_port_ip4_netmask( const char *if_name, IP4_ADDR *p_addr ) ;
+
+ /**
+ * @brief Retrieve the IPv4 broadcast address of a network interface
+ *
+ * @param if_name Name of the interface
+ * @param p_addr Pointer to address field to be filled up
+ *
+ * @return one of the ::MBG_LU_CODES
+ *
+ * @see get_port_ip4_settings
+ * @see get_port_ip4_addr
+ * @see get_port_ip4_addr_str
+ * @see get_port_ip4_netmask
+ * @see get_port_ip4_netmask_str
+ * @see get_port_ip4_broad_addr_str
+ * @see get_specific_port_ip4_addr
+ */
+ int get_port_ip4_broad_addr( const char *if_name, IP4_ADDR *p_addr ) ;
+
+ /**
+ * @brief Retrieve the IPv4 gateway (default route)
+ *
+ * @param p_addr Pointer to address field to be filled up
+ *
+ * @return one of the ::MBG_LU_CODES
+ */
+ int get_ip4_gateway( IP4_ADDR *p_addr ) ;
+
+ /**
+ * @brief Retrieve the IPv4 address of a network interface as string
+ *
+ * @param if_name Name of the interface
+ * @param p_addr_buf Pointer to the string buffer to be filled up
+ * @param buf_size size of the string buffer
+ *
+ * @return one of the ::MBG_LU_CODES
+ *
+ * @see get_port_ip4_settings
+ * @see get_port_ip4_addr
+ * @see get_port_ip4_netmask
+ * @see get_port_ip4_netmask_str
+ * @see get_port_ip4_broad_addr
+ * @see get_port_ip4_broad_addr_str
+ * @see get_specific_port_ip4_addr
+ */
+ int get_port_ip4_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) ;
+
+ /**
+ * @brief Retrieve the IPv4 net mask of a network interface as string
+ *
+ * @param if_name Name of the interface
+ * @param p_addr_buf Pointer to the string buffer to be filled up
+ * @param buf_size size of the string buffer
+ *
+ * @return one of the ::MBG_LU_CODES
+ *
+ * @see get_port_ip4_settings
+ * @see get_port_ip4_addr
+ * @see get_port_ip4_addr_str
+ * @see get_port_ip4_netmask
+ * @see get_port_ip4_broad_addr
+ * @see get_port_ip4_broad_addr_str
+ * @see get_specific_port_ip4_addr
+ */
+ int get_port_ip4_netmask_str( const char *if_name, char *p_addr_buf, int buf_size ) ;
+
+ /**
+ * @brief Retrieve the IPv4 broadcast address of a network interface as string
+ *
+ * @param if_name Name of the interface
+ * @param p_addr_buf Pointer to the string buffer to be filled up
+ * @param buf_size size of the string buffer
+ *
+ * @return one of the ::MBG_LU_CODES
+ *
+ * @see get_port_ip4_settings
+ * @see get_port_ip4_addr
+ * @see get_port_ip4_addr_str
+ * @see get_port_ip4_netmask
+ * @see get_port_ip4_netmask_str
+ * @see get_port_ip4_broad_addr
+ * @see get_specific_port_ip4_addr
+ */
+ int get_port_ip4_broad_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) ;
+
+ /**
+ * @brief Retrieve the current IPv4 settings of a network interface
+ *
+ * @param if_name Name of the interface
+ * @param p Pointer to a IP4_SETTINGS structure to be filled up
+ *
+ * @return 0 on success, < 0 on error
+ *
+ * @see get_port_ip4_addr
+ * @see get_port_ip4_addr_str
+ * @see get_port_ip4_netmask
+ * @see get_port_ip4_netmask_str
+ * @see get_port_ip4_broad_addr
+ * @see get_port_ip4_broad_addr_str
+ * @see get_specific_port_ip4_addr
+ */
+ int get_port_ip4_settings( const char *if_name, IP4_SETTINGS *p ) ;
+
+
+/* ----- function prototypes end ----- */
+
+#ifdef __cplusplus
+}
+#endif
+
+
+#if defined( _USING_BYTE_ALIGNMENT )
+ #pragma pack() // set default alignment
+ #undef _USING_BYTE_ALIGNMENT
+#endif
+
+/* End of header body */
+
+
+#undef _ext
+#undef _DO_INIT
+
+#endif /* _LAN_UTIL_H */
+
diff --git a/c/mbglib/include/mbg_arch.h b/c/mbglib/include/mbg_arch.h
index 28edaf5..fa3227c 100644
--- a/c/mbglib/include/mbg_arch.h
+++ b/c/mbglib/include/mbg_arch.h
@@ -1,20 +1,24 @@
/**************************************************************************
*
- * $Id: mbg_arch.h 1.3.1.4 2011/06/27 16:12:59Z martin TEST $
+ * $Id: mbg_arch.h 1.5 2014/03/11 16:01:55Z martin REL_M $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
* Description:
* Definitions to support different computer hardware architectures.
*
+ * For a good summary of predefined macros which can be used to determine
+ * the build environment, the target environment, and architecture, see:
+ * http://sourceforge.net/p/predef/wiki/Home/
+ *
* -----------------------------------------------------------------------
* $Log: mbg_arch.h $
- * Revision 1.3.1.4 2011/06/27 16:12:59Z martin
- * Revision 1.3.1.3 2011/04/12 12:55:28 martin
- * Include words.h.
- * Revision 1.3.1.2 2011/02/09 15:46:48 martin
- * Revision 1.3.1.1 2011/02/09 15:26:58 martin
+ * Revision 1.5 2014/03/11 16:01:55Z martin
+ * Added a comment.
+ * Revision 1.4 2012/10/02 18:32:00 martin
+ * Include words.h and, conditionally, stdlib.h.
+ * Use generic preprocessor symbol MBG_TGT_KERNEL.
* Revision 1.3 2009/06/12 13:12:37Z martin
* Fixed compiler warning.
* Revision 1.2 2009/03/19 15:14:15 martin
diff --git a/c/mbglib/include/mbg_tgt.h b/c/mbglib/include/mbg_tgt.h
index 10c5de3..b5302d7 100644
--- a/c/mbglib/include/mbg_tgt.h
+++ b/c/mbglib/include/mbg_tgt.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: mbg_tgt.h 1.24.1.1 2011/10/21 14:08:50Z martin TRASH $
+ * $Id: mbg_tgt.h 1.32 2014/06/24 09:21:44Z martin REL_M $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -11,8 +11,29 @@
*
* -----------------------------------------------------------------------
* $Log: mbg_tgt.h $
- * Revision 1.24.1.1 2011/10/21 14:08:50Z martin
- * Changes for QNX.
+ * Revision 1.32 2014/06/24 09:21:44Z martin
+ * Update for newer C++Builder versions.
+ * Revision 1.31 2014/05/27 10:23:33 martin
+ * Finer control of which types are required for or already
+ * available on particular target systems.
+ * First definitions to support SunOS/Solaris.
+ * Revision 1.30 2014/04/01 12:55:58 martin
+ * Define MBG_TGT_WIN32 also for MS resource compiler.
+ * New target MBG_TGT_POSIX.
+ * Always include winsock2.h and windows.h for MBG_TGT_WIN32.
+ * Always include unistd.h for MBG_TGT_POSIX.
+ * Define empty __attribute__ macro for non-gcc environments.
+ * Revision 1.29 2013/02/01 14:50:46 martin
+ * Fixed a typo which caused an error under Borland CBuilder 5.
+ * Revision 1.28 2012/12/12 10:03:16Z martin
+ * Fix for Borland C 3.1.
+ * Revision 1.27 2012/11/29 12:03:14Z martin
+ * Moved definition of _no_macro_fnc() to words.h.
+ * Revision 1.26 2012/11/02 09:01:47Z martin
+ * Merged some stuff depending on the build environment here
+ * and cleaned up.
+ * Revision 1.25 2012/04/04 07:17:18 martin
+ * Treat QNX Neutrino as Unix target.
* Revision 1.24 2011/08/23 10:21:23 martin
* New symbol _NO_MBG_API_ATTR which can be used with functions
* which are going to be exported by a DLL, but actually aren't, yet.
@@ -100,11 +121,16 @@
/* Start of header body */
-#if defined( _CVI ) || defined( _CVI_ )
+#if defined( _CVI_ )
- #define MBG_TGT_WIN32
#define MBG_TGT_CVI
+ #if defined( _NI_mswin_ )
+ #define MBG_TGT_WIN32
+ #else
+ #error Unsupported CVI target platform.
+ #endif
+
#elif defined( _WIN32_WINNT )
// MS platform SDK
@@ -140,6 +166,11 @@
// MS Visual C++
#define MBG_TGT_WIN32
+#elif defined( RC_INVOKED )
+
+ //MS resource compiler
+ #define MBG_TGT_WIN32
+
#elif defined( __WINDOWS_386__ )
// Watcom C/C++ for target Win32
@@ -180,6 +211,23 @@
// GCC for target OpenBSD
#define MBG_TGT_OPENBSD
+#elif defined( __sun ) // Oracle Solaris or other SunOS derived operating system
+
+ // __SUNPRO_C Oracle Solaris Studio C compiler, __SUNPRO_C value is the version number
+ // __SUNPRO_CC Oracle Solaris Studio C++ compiler, __SUNPRO_CC value is the version number
+ // __sparc generate code for SPARC (R) architecture (32-bit or 64-bit)
+ // __sparcv9 generate code for 64-bit SPARC architecture
+ // __i386 generate code for 32-bit x86 architecture
+ // __amd64 generate code for 64-bit x64 architecture
+
+ #define MBG_TGT_SUNOS
+
+ #define __mbg_inline __inline__
+
+ #include <stdint.h>
+ #include <stdbool.h>
+ #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1
+
#elif defined( __QNX__ )
// any compiler for target QNX
@@ -203,13 +251,31 @@
#endif
-// Some definitions which depend on the type of compiler ...
-#if defined( __GNUC__ )
- #define __mbg_inline __inline__
+#if defined( MBG_TGT_FREEBSD ) \
+ || defined( MBG_TGT_NETBSD ) \
+ || defined( MBG_TGT_OPENBSD )
+ #define MBG_TGT_BSD
+
+ #if defined( _KERNEL )
+ #define MBG_TGT_KERNEL
+ #endif
- #define MBG_TGT_HAS_WCHAR_T 1
+#endif
+
+#if defined( MBG_TGT_LINUX ) \
+ || defined( MBG_TGT_BSD ) \
+ || defined( MBG_TGT_SUNOS )
+ #define MBG_TGT_POSIX
+ #define MBG_TGT_UNIX
+#endif
+
+
+
+// Some definitions depending on the build environment ...
+
+#if defined( __GNUC__ )
#if defined( __i386__ )
@@ -240,19 +306,151 @@
#endif
+ #if defined( MBG_TGT_LINUX )
+
+ #if defined( __KERNEL__ )
+
+ #include <linux/types.h>
+ #include <linux/version.h>
+
+ #if ( LINUX_VERSION_CODE <= KERNEL_VERSION( 2, 6, 4 ) )
+ #define _ULONG_DEFINED 1
+ #define _USHORT_DEFINED 1
+ #define _UINT_DEFINED 1
+ #endif
+
+ #else
+
+ #include <sys/types.h>
+ #include <stdint.h>
+ #include <stdbool.h>
+
+ #if defined( __u_char_defined )
+ #define _ULONG_DEFINED 1
+ #define _USHORT_DEFINED 1
+ #define _UINT_DEFINED 1
+ #endif
+
+ #endif
+
+ #elif defined( MBG_TGT_BSD )
+
+ #include <sys/types.h>
+
+ #elif defined( MBG_TGT_QNX_NTO ) // QNX 6.x (Neutrino)
+
+ #include <stdint.h>
+ #include <stdbool.h>
+
+ #else
+
+ #include <stdint.h>
+ #include <stdbool.h>
+
+ #endif
+
+ #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1
+
+ #define MBG_TGT_HAS_WCHAR_T 1
+
+ #define __mbg_inline __inline__
+
#elif defined( _MSC_VER )
+ // Known predifined MS compiler version codes:
+ // 1700: MSVC++ 11.0 (Visual Studio 2012)
+ // 1600: MSVC++ 10.0 (Visual Studio 2010)
+ // 1500: MSVC++ 9.0 (Visual Studio 2008)
+ // 1400: MSVC++ 8.0 (Visual Studio 2005)
+ // 1310: MSVC++ 7.1 (Visual Studio 2003)
+ // 1300: MSVC++ 7.0
+ // 1200: MSVC++ 6.0
+ // 1100: MSVC++ 5.0
+
+ #if ( _MSC_VER >= 1600 )
+ #include <stdint.h>
+ #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1
+ #else
+ #define MBG_TGT_HAS_INT_8_16_32 1
+ #endif
+
+ // no bool support anyway
+ #define MBG_TGT_MISSING_BOOL_TYPE 1
+
+ #define MBG_TGT_HAS_WCHAR_T 1
+
#define __mbg_inline __forceinline
- #define MBG_TGT_HAS_WCHAR_T 1
+#elif defined( _CVI_ )
-#elif defined( _CVI ) || defined( _CVI_ )
+ // 1000 for CVI v10.0 (CVI 2010)
+ // 911 for CVI v9.1.1 (CVI 2009 SP1)
+ // 910 for CVI v9.1 (CVI 2009)
+ // 310 for CVI v3.1
+ // 301 for CVI v3.0.1
+ // 1 for CVI v3.0
- // Inline code is not supported.
+ #if ( _CVI_ >= 910 )
+ // LabWindows/CVI 2009 is the first version providing stdint.h.
+ #include <stdint.h>
+ #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1
+ #else
+ #define USE_LONG_FOR_INT32 1
+ #endif
- #define MBG_TGT_HAS_WCHAR_T 0
+ // As of LabWindows/CVI 2010, stdbool.h is still missing.
+ #define MBG_TGT_MISSING_BOOL_TYPE 1
+
+ #define MBG_TGT_HAS_WCHAR_T 0
+
+ // Inline code is not supported, though the inline keyword
+ // is silently accepted since CVI v9.0
+
+#elif defined( __BORLANDC__ ) // or __CODEGEARC__ in newer versions
+
+ // 0x0200 Borland C/C++ 2.0
+ // 0x0400 Borland C/C++ 3.0
+ // 0x0410 Borland C/C++ 3.1
+ // 0x0550 Borland C/C++ 5.5 (C++Builder 5.0)
+
+ // Next codes are in addition defined as __CODEGEARC__
+ // See http://docwiki.embarcadero.com
+
+ // 0x0570 for Borland Developer Studio 2006 (BDS 2006)
+ // 0x0590 for C++Builder 2007
+ // 0x0591 for update 1 to C++Builder 2007
+ // 0x0592 for RAD Studio 2007
+ // 0x0593 for the December update to RAD Studio 2007
+ // 0x0610 for C++Builder 2009 and for C++Builder 2009 Update 1
+ // 0x0620 for C++Builder 2010 and for C++Builder 2010 Update 1
+ // 0x0621 for C++Builder 2010 Update 2
+ // 0x0630 for C++Builder XE
+ // 0x0631 for C++Builder XE Update 1
+ // 0x0640 for C++Builder XE2
+ // 0x0650 for C++Builder XE3
+
+ #if ( __BORLANDC__ >= 0x630 )
+ // C++Builder XE starts to provide stdbool.h
+ #include <stdint.h>
+ #include <stdbool.h>
+ #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1
+ #elif ( __BORLANDC__ >= 0x570 )
+ // at least BDS 2006 starts to provide stdint.h
+ #include <stdint.h>
+ #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1
+ #define MBG_TGT_MISSING_BOOL_TYPE 1
+ #elif ( __BORLANDC__ >= 0x0550 )
+ #define MBG_TGT_HAS_INT_8_16_32 1
+ #define MBG_TGT_MISSING_BOOL_TYPE 1
+ #else // e.g. BC 3.1 or earlier
+ #if ( __BORLANDC__ <= 0x410 )
+ #define MBG_TGT_MISSING_64_BIT_TYPES 1
+ #define MBG_TGT_MISSING_BOOL_TYPE 1
+ #define USE_LONG_FOR_INT32 1
+ #endif
+ #endif
-#elif defined( __BORLANDC__ )
+ #define MBG_TGT_HAS_WCHAR_T defined( MBG_TGT_WIN32 )
#if defined( __cplusplus )
#define __mbg_inline inline // standard C++ syntax
@@ -262,35 +460,41 @@
#define __mbg_inline // up to BC3.1 not supported for C
#endif
- #define MBG_TGT_HAS_WCHAR_T defined( MBG_TGT_WIN32 )
-
#elif defined( __WATCOMC__ )
- #define __mbg_inline _inline
+ // 1050 v10.5
+ // 1100 v11.0
+ // 1200 Open Watcom C++ v1.0
+ // 1230 Open Watcom C++ v1.3
+ // 1270 Open Watcom C++ v1.7
- #define MBG_TGT_HAS_WCHAR_T defined( MBG_TGT_WIN32 )
+ #if defined( MBG_TGT_QNX ) // QNX 4.x
-#endif
+ #include <sys/types.h>
+ #define MBG_TGT_MISSING_64_BIT_TYPES 1
+ #elif ( __WATCOMC__ > 1230 ) // Open Watcom C 1.3 and above
-#if defined( MBG_TGT_FREEBSD ) \
- || defined( MBG_TGT_NETBSD ) \
- || defined( MBG_TGT_OPENBSD )
- #define MBG_TGT_BSD
+ #include <stdint.h>
+
+ #elif !defined( __WATCOM_INT64__ ) // Watcom C 11
+
+ #define MBG_TGT_MISSING_64_BIT_TYPES 1
- #if defined( _KERNEL )
- #define MBG_TGT_KERNEL
#endif
-#endif
+ #define MBG_TGT_HAS_WCHAR_T defined( MBG_TGT_WIN32 )
+
+ #define __mbg_inline _inline
-#if defined( MBG_TGT_LINUX ) \
- || defined( MBG_TGT_BSD )
- #define MBG_TGT_UNIX
#endif
+#if !defined( __GNUC__ ) && !defined( __attribute__ )
+ #define __attribute__( _x )
+#endif
+
#if defined( MBG_TGT_WIN32 )
@@ -309,7 +513,11 @@
#include <ntddk.h>
#else
// This must not be used for kernel drivers.
+ #define WIN32_LEAN_AND_MEAN 1
+ #define _WINSOCKAPI_ /* Prevent inclusion of winsock.h in windows.h */
+ #include <winsock2.h>
#include <windows.h>
+
typedef HANDLE MBG_HANDLE;
#define MBG_INVALID_HANDLE INVALID_HANDLE_VALUE
@@ -340,7 +548,11 @@
#define _MBG_API_ATTR __declspec( dllimport )
#endif
-#elif defined( MBG_TGT_UNIX )
+#elif defined( MBG_TGT_POSIX )
+
+ #if !defined( MBG_TGT_KERNEL )
+ #include <unistd.h>
+ #endif
typedef int MBG_HANDLE;
typedef int MBG_PORT_HANDLE;
@@ -378,11 +590,6 @@
#endif
-#if !defined( _nop_macro_fnc )
- #define _nop_macro_fnc() do {} while (0)
-#endif
-
-
// The macros below are defined in order to be able to check if
// certain C language extensions are available on the target system:
#if defined( __STDC_VERSION__ ) && ( __STDC_VERSION__ >= 199409L )
diff --git a/c/mbglib/include/mbg_w32.h b/c/mbglib/include/mbg_w32.h
index 3b93e8f..ebdc119 100644
--- a/c/mbglib/include/mbg_w32.h
+++ b/c/mbglib/include/mbg_w32.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: mbg_w32.h 1.7 2012/05/30 13:28:43Z martin TRASH $
+ * $Id: mbg_w32.h 1.7 2012/05/30 13:28:43Z martin TEST $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
diff --git a/c/mbglib/include/mbgdevio.h b/c/mbglib/include/mbgdevio.h
index 70fcef4..8c56a98 100644
--- a/c/mbglib/include/mbgdevio.h
+++ b/c/mbglib/include/mbgdevio.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: mbgdevio.h 1.39.1.27 2012/04/11 15:45:12Z martin TEST $
+ * $Id: mbgdevio.h 1.41.1.16 2014/07/18 11:01:41Z martin TRASH martin $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -10,71 +10,49 @@
*
* -----------------------------------------------------------------------
* $Log: mbgdevio.h $
- * Revision 1.39.1.27 2012/04/11 15:45:12Z martin
+ * Revision 1.41.1.16 2014/07/18 11:01:41Z martin
+ * Revision 1.41.1.15 2014/07/16 15:19:57 martin
+ * Revision 1.41.1.14 2014/07/16 13:06:39 martin
+ * Revision 1.41.1.13 2014/07/14 15:42:49 martin
+ * Revision 1.41.1.12 2014/06/26 12:24:22 martin
+ * Revision 1.41.1.11 2014/05/27 08:22:20Z martin
+ * Revision 1.41.1.10 2014/05/26 16:02:13 martin
+ * Revision 1.41.1.9 2014/05/23 12:40:19 martin
+ * Revision 1.41.1.8 2014/05/23 09:24:08 martin
+ * gpio and xmr functions.
+ * Revision 1.41.1.7 2014/04/23 15:42:59 martin
+ * Revision 1.41.1.6 2014/04/22 15:27:47 martin
+ * Revision 1.41.1.5 2014/04/22 13:29:18 martin
+ * Revision 1.41.1.4 2014/03/28 10:23:24 martin
+ * Revision 1.41.1.3 2014/03/05 10:38:29 martin
+ * Windows.h is now included in mbg_tgt.h.
+ * Revision 1.41.1.2 2014/01/31 14:45:35Z martin
+ * Revision 1.41.1.1 2013/12/12 11:24:16 martin
+ * Revision 1.41 2013/09/26 08:54:54 martin
+ * Defined thread function type MBG_THREAD_FNC.
+ * Defined check-if-supported function type MBG_CHK_SUPP_FNC.
+ * Updated function prototypes.
+ * Revision 1.40 2012/10/02 18:40:30Z martin
+ * There are some g++ versions which fail to compile source code using
+ * the macros provided by Linux to define IOCTL codes. If only the API
+ * functions are called by an application then the IOCTL codes aren't
+ * required anyway, so we just avoid inclusion of mbgioctl.h.
* Updated doxygen comments.
- * Revision 1.39.1.26 2012/04/11 14:49:06 martin
* Updated function prototypes.
- * Revision 1.39.1.25 2011/11/25 15:03:22 martin
* Support on-board event logs.
- * Revision 1.39.1.24 2011/11/23 16:42:03 martin
- * Updated function prototypes.
- * Added some comments.
- * Revision 1.39.1.23.1.4 2011/11/23 16:37:24 martin
- * Removed tmp. debug code.
- * Revision 1.39.1.23.1.3 2011/11/23 16:32:53 martin
- * Modified tmp. debug code.
- * Revision 1.39.1.23.1.2 2011/11/22 15:13:14 martin
- * Updated function prototypes.
- * Revision 1.39.1.23.1.1 2011/11/21 14:16:33 martin
- * Tmp. debug generic I/O.
- * Revision 1.39.1.23 2011/11/16 10:09:28 martin
* Fixed a bug which caused a crash when generic I/O calls
* were used under Windows.
- * Revision 1.39.1.22 2011/10/21 14:08:28Z martin
* Changes for QNX.
- * Revision 1.39.1.21 2011/09/26 14:03:21 martin
* Workaround to make mbgmon (BC) build under Windows.
- * See diff for details.
* Cleaned up CPU set support under Linux.
- * Updated function prototypes.
- * Revision 1.39.1.20 2011/07/20 15:52:22Z martin
- * Conditionally use older IOCTL request buffer structures.
* Moved some macros here so they can be used by other modules.
- * Modified some macros and definitions.
- * Revision 1.39.1.19 2011/07/19 15:46:39 martin
- * Revision 1.39.1.18 2011/07/06 11:19:24 martin
* Support reading CORR_INFO, and reading/writing TR_DISTANCE.
- * Revision 1.39.1.17 2011/06/29 11:10:19 martin
- * Updated function prototypes.
- * Revision 1.39.1.16 2011/06/22 10:16:22 martin
* Cleaned up handling of pragma pack().
* Cleaned up inclusion of header files.
- * Updated function prototypes.
- * Revision 1.39.1.15 2011/04/12 12:57:53 martin
* Moved mutex definitions to new mbgmutex.h.
* Renamed mutex stuff to critical sections.
- * Revision 1.39.1.14 2011/03/31 13:20:55 martin
- * Updated function prototypes.
- * Revision 1.39.1.13 2011/02/15 14:26:22Z martin
- * Revision 1.39.1.12 2011/02/15 11:22:29 daniel
* Updated function prototypes to support PTP unicast configuration
- * Revision 1.39.1.11 2011/02/02 12:21:39Z martin
- * Fixed a type.
- * Revision 1.39.1.10 2011/01/28 09:33:45 martin
- * Cosmetics.
- * Revision 1.39.1.9 2010/12/14 11:23:49 martin
- * Moved definition of MBG_HW_NAME to the header file.
- * Revision 1.39.1.8 2010/12/14 10:56:35Z martin
- * Revision 1.39.1.7 2010/08/11 13:48:53 martin
- * Cleaned up comments.
- * Revision 1.39.1.6 2010/08/11 12:43:52 martin
- * Revision 1.39.1.5 2010/07/15 08:40:57 martin
- * Revision 1.39.1.4 2010/01/08 15:04:17Z martin
- * Revision 1.39.1.3 2010/01/08 11:24:02Z martin
- * Compute and check time of day only if any leap second status bit set.
- * Revision 1.39.1.2 2010/01/08 11:13:57Z martin
* Made xhrt leap second check an inline function.
- * Revision 1.39.1.1 2010/01/07 15:49:37Z martin
* Fixed macro to avoid compiler warning.
* Revision 1.39 2009/12/15 15:34:59Z daniel
* Support reading the raw IRIG data bits for firmware versions
@@ -245,7 +223,6 @@
#endif
#define MBG_USE_KERNEL_DRIVER 1
- #include <windows.h>
#define MBGDEVIO_RET_VAL DWORD
#define _mbgdevio_cnv_ret_val( _v ) (_v)
@@ -307,14 +284,16 @@
#if defined( MBG_USE_KERNEL_DRIVER )
- #include <mbgioctl.h>
-
#include <stdlib.h>
#include <string.h>
#endif
+#if defined( MBG_TGT_POSIX )
+ #define MBG_HAS_UNIX_IOCTL 1
+#endif
+
#if !defined( MBGDEVIO_XHRT_API )
#define MBGDEVIO_XHRT_API 0
#endif
@@ -386,13 +365,16 @@
/**
- The type below is used to store a unique ID for a device which
- is made up of the device model name and its serial number, i.e.:
- Format: [model_name]_[serial_number], e.g. "GPS170PCI_028210040670"
- */
+ * @brief A string buffer for a unique device ID
+ *
+ * The unique ID is made up of the device model name
+ * and its serial number, i.e. [model_name]_[serial_number]
+ * E.g.: "GPS170PCI_028210040670"
+ */
typedef char MBG_HW_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1];
+// Definitions specific to the target OS
#if defined( MBG_TGT_LINUX )
@@ -434,7 +416,7 @@ typedef char MBG_HW_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1];
#if !defined( MBG_TGT_WIN32 )
- #define FILETIME int // just a dummy to avoid build errors
+ #define FILETIME int // just a dummy to avoid build errors
#endif
@@ -497,6 +479,7 @@ typedef struct
#endif
} MBG_THREAD_INFO;
+typedef MBG_THREAD_FNC_RET_VAL (MBG_THREAD_FNC_ATTR *MBG_THREAD_FNC)(void *);
typedef struct
@@ -527,15 +510,17 @@ typedef struct
/**
- Match modes to decide how to proceed if a certain
- model type with certain serial number can not be found
+ * @brief Device matching modes
+ *
+ * Match modes to determine how to proceed if a device with
+ * particular model type and serial number has not been detected.
*/
enum MBG_MATCH_MODE
{
- MBG_MATCH_ANY, /**< open the next available device on the system */
- MBG_MATCH_MODEL, /**< open the next available device on the system with the same clock type */
- MBG_MATCH_EXACTLY, /**< force opening exactly the requested device otherwise exit with failure */
- N_MBG_MATCH_MODE /**< number of known modes */
+ MBG_MATCH_ANY, ///< use the next device available on the system
+ MBG_MATCH_MODEL, ///< use the next available device of the same type
+ MBG_MATCH_EXACTLY, ///< use only exactly the excat matching device, otherwise fail
+ N_MBG_MATCH_MODE ///< number of known modes
};
@@ -557,6 +542,11 @@ typedef struct _MBG_DEVICENAME_LIST
} MBG_DEVICENAME_LIST;
+/**
+ * @brief Type of functions to check if a feature is supported
+ */
+typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh, int *p );
+
/* function prototypes: */
@@ -570,182 +560,184 @@ extern "C" {
/* by MAKEHDR, do not remove the comments. */
/**
- Get the version number of the precompiled DLL/shared object library.
-
- If this library is used as a DLL/shared object library then the version
- number can be checked to see if the header files which are actually used
- to build an application are compatible with the header files which have
- been used to build the library, and thus the API function are called
- in the correct way.
-
- @return the version number
-
- @see mbgdevio_check_version()
- @see ::MBGDEVIO_VERSION defined in mbgdevio.h
- */
+ * @brief Get the version number of the precompiled DLL/shared object library
+ *
+ * If this library is used as a DLL/shared object library then the version
+ * number can be checked to see if the header files which are actually used
+ * to build an application are compatible with the header files which have
+ * been used to build the library, and thus the API function are called
+ * in the correct way.
+ *
+ * @return the version number
+ *
+ * @see ::mbgdevio_check_version
+ * @see ::MBGDEVIO_VERSION defined in mbgdevio.h
+ */
_MBG_API_ATTR int _MBG_API mbgdevio_get_version( void ) ;
/**
- @brief Check if the DLL/shared library is compatible with a given version.
-
- If this library is used as a DLL/shared object library then the version
- number can be checked to see if the header files which are actually used
- to build an application are compatible with the header files which have
- been used to build the library, and thus the API function are called
- in the correct way.
-
- @param header_version Version number to be checked, should be ::MBGDEVIO_VERSION
- from the mbgdevio.h file used to build the application
-
- @return ::MBG_SUCCESS if compatible, ::MBG_ERR_LIB_NOT_COMPATIBLE if not.
-
- @see mbgdevio_get_version()
- @see ::MBGDEVIO_VERSION defined in mbgdevio.h
- */
+ * @brief Check if the DLL/shared library is compatible with a given version
+ *
+ * If this library is used as a DLL/shared object library then the version
+ * number can be checked to see if the header files which are actually used
+ * to build an application are compatible with the header files which have
+ * been used to build the library, and thus the API functions are called
+ * in the correct way.
+ *
+ * @param[in] header_version Version number to be checked, should be ::MBGDEVIO_VERSION
+ * from the mbgdevio.h file version used to build the application
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbgdevio_get_version
+ * @see ::MBGDEVIO_VERSION defined in mbgdevio.h
+ */
_MBG_API_ATTR int _MBG_API mbgdevio_check_version( int header_version ) ;
/**
- @brief Open a device by index, starting from 0.
-
- This function is <b>out of date</b>, mbg_open_device_by_name()
- should be used instead.
-
- See the <b>note</b> for mbg_find_device() for details.
-
- @param device_index index of the device, use 0 for the first device.
- */
+ * @brief Open a device by index, starting from 0
+ *
+ * @deprecated This function is deprecated,
+ * ::mbg_open_device_by_name should be used instead.
+ *
+ * @note See comments for ::mbg_find_devices for details.
+ *
+ * @param[in] device_index Index of the device, use 0 for the first device
+ *
+ * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE
+ */
_MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device( unsigned int device_index ) ;
/**
- @brief Get the number of supported devices installed on the computer.
-
- This function is <b>out of date</b>, mbg_find_devices_with_names()
- should be used instead.
-
- <b>Note:</b> This function is out of date since it may not work
- correctly for Meinberg devices which are disconnected and reconnected
- while the system is running (e.g. USB devices). However, the function
- will be kept for compatibility reasons and works correctly if all
- Meinberg devices are connected at system boot and are not disconnected
- and reconnected during operation
-
- @return The number of devices found
-
- @see mbg_find_devices_with_names()
- */
+ * @brief Get the number of supported devices installed on the computer.
+ *
+ * @deprecated This function is deprecated, ::mbg_find_devices_with_names
+ * should be used instead.
+ *
+ * @note This function is out of date since it may not work
+ * correctly for Meinberg devices which are disconnected and reconnected
+ * while the system is running (e.g. USB devices). However, the function
+ * will be kept for compatibility reasons and works correctly if all
+ * Meinberg devices are connected at system boot and are not disconnected
+ * and reconnected during operation
+ *
+ * @return The number of devices found
+ *
+ * @see ::mbg_find_devices_with_names
+ */
_MBG_API_ATTR int _MBG_API mbg_find_devices( void ) ;
/**
- @brief Allocate memory and set up a list of installed and supported devices.
-
- This function should be used preferably instead of mbg_find_devices().
-
- @param device_list Pointer to a linked list of type ::MBG_DEVICENAME_LIST
- with device names. The list will be allocated by this
- function and has to be freed after usage by calling
- mbg_free_device_name_list().
- @param max_devices Maximum number of devices the function should look for
- (can not exceed ::MBG_MAX_DEVICES).
-
- @return number of present devices
-
- @see ::MBG_HW_NAME for the format of the unique names
- @see mbg_free_device_name_list()
- @see mbg_find_devices()
- */
+ * @brief Allocate memory and set up a list of installed and supported devices.
+ *
+ * This function should be used preferably instead of ::mbg_find_devices.
+ *
+ * @param[in] device_list Pointer to a linked list of type ::MBG_DEVICENAME_LIST
+ * with device names. The list will be allocated by this
+ * function and has to be freed after usage by calling
+ * ::mbg_free_device_name_list.
+ * @param[in] max_devices Maximum number of devices the function should look for
+ * (must not exceed ::MBG_MAX_DEVICES).
+ *
+ * @return number of present devices
+ *
+ * @see ::MBG_HW_NAME for the format of the unique names
+ * @see ::mbg_free_device_name_list
+ * @see ::mbg_find_devices
+ */
_MBG_API_ATTR int _MBG_API mbg_find_devices_with_names( MBG_DEVICENAME_LIST **device_list, int max_devices ) ;
/**
- @brief Free the memory allocated for a ::MBG_DEVICENAME_LIST.
-
- The list may have been set up and allocated before
- by mbg_find_devices_with_names().
-
- @param *list Linked list of type ::MBG_DEVICENAME_LIST
-
- @see mbg_find_devices_with_names()
- */
+ * @brief Free the memory allocated for a ::MBG_DEVICENAME_LIST.
+ *
+ * The list may have been set up and allocated before
+ * by ::mbg_find_devices_with_names.
+ *
+ * @param[in,out] *list Linked list of type ::MBG_DEVICENAME_LIST
+ *
+ * @see ::mbg_find_devices_with_names
+ */
_MBG_API_ATTR void _MBG_API mbg_free_device_name_list( MBG_DEVICENAME_LIST *list) ;
/**
- @brief Return a handle to a device with a certain unique name.
-
- The names of the devices that are installed on the system can be retrieved by
- the function mbg_find_devices_with_names().
-
- This function should be used preferably instead of mbg_open_device().
-
- @param hw_name String with the unique name of the device to be opened
- @param selection_mode One of the enum values of ::MBG_MATCH_MODE
-
- @return On success, the function returns a handle to the device, otherwise ::MBG_INVALID_DEV_HANDLE
-
- @see ::MBG_HW_NAME for the format of the unique names.
- @see ::MBG_MATCH_MODE
- @see mbg_find_devices_with_names()
- */
- _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const char* hw_name, int selection_mode ) //##++++
+ * @brief Return a handle to a device with a certain unique name.
+ *
+ * The names of the devices that are installed on the system can be retrieved by
+ * the function ::mbg_find_devices_with_names.
+ *
+ * This function should be used preferably instead of ::mbg_open_device.
+ *
+ * @param[in] srch_name String with the unique name of the device to be opened
+ * @param[in] selection_mode One of the enum values of ::MBG_MATCH_MODE
+ *
+ * @return On success, the function returns a handle to the device, otherwise ::MBG_INVALID_DEV_HANDLE
+ *
+ * @see ::MBG_HW_NAME for the format of the unique names
+ * @see ::MBG_MATCH_MODE
+ * @see ::mbg_find_devices_with_names
+ */
+ _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const char *srch_name, int selection_mode ) //##++++
;
/**
- @brief Close a handle to a device and set the handle value to ::MBG_INVALID_DEV_HANDLE.
-
- @param dev_handle Handle to a Meinberg device.
- */
+ * @brief Close a handle to a device and set the handle value to ::MBG_INVALID_DEV_HANDLE.
+ *
+ * @param[in,out] dev_handle Pointer to a Meinberg device handle
+ */
_MBG_API_ATTR void _MBG_API mbg_close_device( MBG_DEV_HANDLE *dev_handle ) ;
/**
- @brief Read information about the driver handling a given device.
-
- @param dh Valid handle to a Meinberg device
- @param *p Pointer to a ::PCPS_DRVR_INFO structure which is filled up.
-
- @return ::MBG_SUCCESS or error code returned by device I/O control function
- */
+ * @brief Read information about the driver handling a given device
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param[out] *p A ::PCPS_DRVR_INFO structure to be filled up.
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ */
_MBG_API_ATTR int _MBG_API mbg_get_drvr_info( MBG_DEV_HANDLE dh, PCPS_DRVR_INFO *p ) ;
/**
- @brief Read detailed device information.
-
- @param dh Valid handle to a Meinberg device
- @param *p Pointer to a ::PCPS_DEV structure to be filled up
-
- @return ::MBG_SUCCESS or error code returned by device I/O control function
- */
+ * @brief Read detailed device information
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device
+ * @param[out] *p A ::PCPS_DEV structure to be filled up
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ */
_MBG_API_ATTR int _MBG_API mbg_get_device_info( MBG_DEV_HANDLE dh, PCPS_DEV *p ) ;
/**
- @brief Read the current state of the on-board ::PCPS_STATUS_PORT.
-
- @param dh Valid handle to a Meinberg device
- @param *p Pointer to a ::PCPS_STATUS_PORT value to be filled up
-
- @return ::MBG_SUCCESS or error code returned by device I/O control function
-
- @see \ref group_status_port "bitmask"
- */
+ * @brief Read the current state of the on-board ::PCPS_STATUS_PORT
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device
+ * @param[out] *p A ::PCPS_STATUS_PORT value to be filled up
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see @ref group_status_port "bitmask" //##++++
+ */
_MBG_API_ATTR int _MBG_API mbg_get_status_port( MBG_DEV_HANDLE dh, PCPS_STATUS_PORT *p ) ;
/* (Intentionally excluded from Doxygen)
- Generic read function which writes a command code to a device
- and reads a number of replied data to a generic buffer.
-
- <b>Warning</b>: This is for debugging purposes only!
- The specialized API calls should be used preferably.
- A specific device may not support any command code.
-
- @param dh Valid handle to a Meinberg device
- @param cmd Can be any \ref group_cmd_bytes "command byte" supported by the device
- @param *p Pointer to a buffer to be filled up
- @param size Size of the buffer *p
-
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_generic_write()
- @see mbg_generic_read_gps()
- @see mbg_generic_write_gps()
- @see mbg_generic_io()
- */
+ * Generic read function which writes a command code to a device
+ * and reads a number of replied data to a generic buffer.
+ *
+ * <b>Warning</b>: This is for debugging purposes only!
+ * The specialized API calls should be used preferably.
+ * A specific device may not support any command code.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param[in] cmd Can be any @ref PCPS_CMD_CODES "command code" supported by the device
+ * @param[out] *p Pointer to a buffer to be filled up
+ * @param[in] size Size of the buffer *p
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_generic_write
+ * @see ::mbg_generic_read_gps
+ * @see ::mbg_generic_write_gps
+ * @see ::mbg_generic_io
+ */
_MBG_API_ATTR int _MBG_API mbg_generic_read( MBG_DEV_HANDLE dh, int cmd, void *p, int size ) ;
/* (Intentionally excluded from Doxygen)
@@ -758,18 +750,18 @@ extern "C" {
The specialized API calls should be used preferably.
A specific device may not support any GPS command code.
- @param dh Valid handle to a Meinberg device
- @param cmd Can be any \ref group_cmd_bytes "command byte" supported by the device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ @param cmd Can be any @ref PCPS_CMD_CODES "command code" supported by the device
@param *p Pointer to a buffer to be filled up
@param size Size of the buffer *p
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_gps_data()
- @see mbg_generic_write_gps()
- @see mbg_generic_read()
- @see mbg_generic_write()
- @see mbg_generic_io()
+ * @see ::mbg_dev_has_gps_data
+ * @see ::mbg_generic_write_gps
+ * @see ::mbg_generic_read
+ * @see ::mbg_generic_write
+ * @see ::mbg_generic_io
*/
_MBG_API_ATTR int _MBG_API mbg_generic_read_gps( MBG_DEV_HANDLE dh, int cmd, void *p, int size ) ;
@@ -781,17 +773,17 @@ extern "C" {
The specialized API calls should be used preferably.
A specific device may not support any command code.
- @param dh Valid handle to a Meinberg device
- @param cmd Can be any \ref group_cmd_bytes "command byte" supported by the device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ @param cmd Can be any @ref PCPS_CMD_CODES "command code" supported by the device
@param *p Pointer to a buffer to be written
@param size Size of the buffer *p
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_generic_read()
- @see mbg_generic_read_gps()
- @see mbg_generic_write_gps()
- @see mbg_generic_io()
+ * @see ::mbg_generic_read
+ * @see ::mbg_generic_read_gps
+ * @see ::mbg_generic_write_gps
+ * @see ::mbg_generic_io
*/
_MBG_API_ATTR int _MBG_API mbg_generic_write( MBG_DEV_HANDLE dh, int cmd, const void *p, int size ) ;
@@ -805,18 +797,18 @@ extern "C" {
The specialized API calls should be used preferably.
A specific device may not support any GPS command code.
- @param dh Valid handle to a Meinberg device
- @param cmd Can be any \ref group_cmd_bytes "command byte" supported by the device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ @param cmd Can be any @ref PCPS_CMD_CODES "command code" supported by the device
@param *p Pointer to a buffer to be written
@param size Size of the buffer *p
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_gps_data()
- @see mbg_generic_read_gps()
- @see mbg_generic_read()
- @see mbg_generic_write()
- @see mbg_generic_io()
+ * @see ::mbg_dev_has_gps_data
+ * @see ::mbg_generic_read_gps
+ * @see ::mbg_generic_read
+ * @see ::mbg_generic_write
+ * @see ::mbg_generic_io
*/
_MBG_API_ATTR int _MBG_API mbg_generic_write_gps( MBG_DEV_HANDLE dh, int cmd, const void *p, int size ) ;
@@ -827,18 +819,18 @@ extern "C" {
<b>Warning</b>: This call is for debugging purposes and internal use only!
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_generic_io()
- @see mbg_generic_read()
- @see mbg_generic_write()
- @see mbg_generic_read_gps()
- @see mbg_generic_write_gps()
+ * @see ::mbg_dev_has_generic_io
+ * @see ::mbg_generic_read
+ * @see ::mbg_generic_write
+ * @see ::mbg_generic_read_gps
+ * @see ::mbg_generic_write_gps
*/
_MBG_API_ATTR int _MBG_API mbg_generic_io( MBG_DEV_HANDLE dh, int type, const void *in_p, int in_sz, void *out_p, int out_sz ) ;
/**
- @brief Read a ::PCPS_TIME structure returning the current date/time/status.
+ * @brief Read a ::PCPS_TIME structure returning the current date/time/status.
The returned time is local time according to the card's time zone setting,
with a resolution of 10 ms (i.e. 10ths of seconds).
@@ -848,34 +840,34 @@ extern "C" {
mbg_get_fast_hr_timestamp..() group of calls should be used preferably
if supported by the device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_TIME structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_get_hr_time()
- @see mbg_set_time()
- @see mbg_get_sync_time()
- */
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_get_hr_time
+ * @see ::mbg_set_time
+ * @see ::mbg_get_sync_time
+ */
_MBG_API_ATTR int _MBG_API mbg_get_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ;
/**
- @brief Set the device's on-board clock to a given date and time.
+ * @brief Set the device's on-board clock to a given date and time.
The macro _pcps_can_set_time() checks whether this call
is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_STIME structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_get_time()
- */
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_get_time
+ */
_MBG_API_ATTR int _MBG_API mbg_set_time( MBG_DEV_HANDLE dh, const PCPS_STIME *p ) ;
/**
- @brief Read the time when the device has last recently synchronized.
+ * @brief Read the time when the device has last recently synchronized.
Fills a ::PCPS_TIME structure with the date/time/status reporting
when the device was synchronized the last time to its time source,
@@ -891,17 +883,17 @@ extern "C" {
The macro _pcps_time_is_read() can be used to check whether the
returned information is valid, or not available.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_TIME structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_get_time()
- */
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_get_time
+ */
_MBG_API_ATTR int _MBG_API mbg_get_sync_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ;
/**
- @brief Wait until the next second change, then return current time.
+ * @brief Wait until the next second change, then return current time.
Returns time in a ::PCPS_TIME structure similar to mbg_get_time().
@@ -909,17 +901,17 @@ extern "C" {
The call blocks until the kernel driver detects a second change
reported by the device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_TIME structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_get_time()
- */
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_get_time
+ */
_MBG_API_ATTR int _MBG_API mbg_get_time_sec_change( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ;
/**
- @brief Read the card's current time with high resolution, plus status.
+ * @brief Read the card's current time with high resolution, plus status.
Fills up a ::PCPS_HR_TIME (High Resolution time) structure containing
the current %UTC time (seconds since 1970), %UTC offset, and status.
@@ -932,16 +924,16 @@ extern "C" {
The mbg_get_hr_time_cycles() and mbg_get_hr_time_comp() calls
provide ways to account for and/or compensate the latency.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_HR_TIME structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_dev_has_hr_time()
- @see mbg_get_time()
- @see mbg_get_hr_time_cycles()
- @see mbg_get_hr_time_comp()
- */
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_hr_time
+ * @see ::mbg_get_time
+ * @see ::mbg_get_hr_time_cycles
+ * @see ::mbg_get_hr_time_comp
+ */
_MBG_API_ATTR int _MBG_API mbg_get_hr_time( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) ;
/* (Intentionally excluded from Doxygen )
@@ -952,59 +944,55 @@ extern "C" {
<b>Note:</b> This is only supported by some special firmware.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_TIME_STAMP structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_dev_has_event_time()
- */
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_event_time
+ */
_MBG_API_ATTR int _MBG_API mbg_set_event_time( MBG_DEV_HANDLE dh, const PCPS_TIME_STAMP *p ) ;
/**
- @brief Read the serial port configuration from an old type of device.
-
- <b>Note:</b> Direct usage of this function is obsolete.
-
- The generic API function mbg_get_serial_settings() should be used instead
- which fully supports the capabilities of current devices.
-
- The macro _pcps_has_serial() checks whether this call
- is supported by a device.
-
- @param dh Valid handle to a Meinberg device
- @param *p Pointer to a ::PCPS_SERIAL structure to be filled up
-
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see \ref group_cmd_bytes
- @see mbg_get_serial_settings()
- */
+ * @brief Read the serial port configuration from an old type of device
+ *
+ * @deprecated Direct usage of this function is deprecated. The generic
+ * API function ::mbg_get_serial_settings should be used instead
+ * which fully supports the capabilities of current devices.
+ *
+ * The macro ::_pcps_has_serial checks whether this call
+ * is supported by a device.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device
+ * @param[out] p Pointer to a ::PCPS_SERIAL structure to be filled up
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_get_serial_settings
+ */
_MBG_API_ATTR int _MBG_API mbg_get_serial( MBG_DEV_HANDLE dh, PCPS_SERIAL *p ) ;
/**
- @brief Write the serial port configuration to an old type of device.
-
- <b>Note:</b> Direct usage of this function is obsolete.
-
- The generic API function mbg_save_serial_settings() should be used instead
- which fully supports the capabilities of current devices.
-
- The macro _pcps_has_serial() checks whether this call
- is supported by a device.
-
- @param dh Valid handle to a Meinberg device
- @param *p Pointer to a ::PCPS_SERIAL structure to be written
-
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see \ref group_cmd_bytes
- @see mbg_save_serial_settings()
- */
+ * @brief Write the serial port configuration to an old type of device
+ *
+ * @deprecated Direct usage of this function is deprecated. The generic
+ * API function ::mbg_save_serial_settings should be used instead
+ * which fully supports the capabilities of current devices.
+ *
+ * The macro ::_pcps_has_serial checks whether this call
+ * is supported by a device.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device
+ * @param[in] p Pointer to a ::PCPS_SERIAL structure to be written
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_save_serial_settings
+ */
_MBG_API_ATTR int _MBG_API mbg_set_serial( MBG_DEV_HANDLE dh, const PCPS_SERIAL *p ) ;
/**
- @brief Read time zone/daylight saving configuration code from a device.
+ * @brief Read time zone/daylight saving configuration code from a device.
The APIs using TZCODE are only supported by some simpler cards
and allow just a very basic configuration.
@@ -1016,21 +1004,20 @@ extern "C" {
calls instead which allow for a more detailed configuration of the
time zone and daylight saving settings.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_TZCODE structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_dev_has_tzcode()
- @see mbg_set_tzcode()
- @see mbg_get_pcps_tzdl()
- @see mbg_get_gps_tzdl()
- @see \ref group_cmd_bytes
- */
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_tzcode
+ * @see ::mbg_set_tzcode
+ * @see ::mbg_get_pcps_tzdl
+ * @see ::mbg_get_gps_tzdl
+ */
_MBG_API_ATTR int _MBG_API mbg_get_tzcode( MBG_DEV_HANDLE dh, PCPS_TZCODE *p ) ;
/**
- @brief Write time zone/daylight saving configuration code to a device.
+ * @brief Write time zone/daylight saving configuration code to a device.
The APIs using TZCODE are only supported by some simpler cards
and allow just a very basic configuration.
@@ -1042,21 +1029,20 @@ extern "C" {
calls instead which allow for a more detailed configuration of the
time zone and daylight saving settings.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_TZCODE structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_dev_has_tzcode()
- @see mbg_get_tzcode()
- @see mbg_set_pcps_tzdl()
- @see mbg_set_gps_tzdl()
- @see \ref group_cmd_bytes
- */
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_tzcode
+ * @see ::mbg_get_tzcode
+ * @see ::mbg_set_pcps_tzdl
+ * @see ::mbg_set_gps_tzdl
+ */
_MBG_API_ATTR int _MBG_API mbg_set_tzcode( MBG_DEV_HANDLE dh, const PCPS_TZCODE *p ) ;
/**
- @brief Read time zone/daylight saving parameters from a device.
+ * @brief Read time zone/daylight saving parameters from a device.
This function fills up a ::PCPS_TZDL structure which supports a more
detailed configuration of time zone and daylight saving than the TZCODE
@@ -1068,21 +1054,20 @@ extern "C" {
Other cards may support the mbg_get_tzcode() or mbg_get_gps_tzdl()
calls instead.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_TZDL structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_pcps_tzdl()
- @see mbg_set_pcps_tzdl()
- @see mbg_get_tzcode()
- @see mbg_get_gps_tzdl()
- @see \ref group_cmd_bytes
+ * @see ::mbg_dev_has_pcps_tzdl
+ * @see ::mbg_set_pcps_tzdl
+ * @see ::mbg_get_tzcode
+ * @see ::mbg_get_gps_tzdl
*/
_MBG_API_ATTR int _MBG_API mbg_get_pcps_tzdl( MBG_DEV_HANDLE dh, PCPS_TZDL *p ) ;
/**
- @brief Write time zone/daylight saving parameters to a device.
+ * @brief Write time zone/daylight saving parameters to a device.
This function passes a ::PCPS_TZDL structure to a device which supports
a more detailed configuration of time zone and daylight saving than the
@@ -1093,21 +1078,20 @@ extern "C" {
Other cards may support the mbg_set_tzcode() or mbg_set_gps_tzdl()
calls instead.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_TZDL structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_pcps_tzdl()
- @see mbg_get_pcps_tzdl()
- @see mbg_set_tzcode()
- @see mbg_set_gps_tzdl()
- @see \ref group_cmd_bytes
+ * @see ::mbg_dev_has_pcps_tzdl
+ * @see ::mbg_get_pcps_tzdl
+ * @see ::mbg_set_tzcode
+ * @see ::mbg_set_gps_tzdl
*/
_MBG_API_ATTR int _MBG_API mbg_set_pcps_tzdl( MBG_DEV_HANDLE dh, const PCPS_TZDL *p ) ;
/**
- @brief Read the %UTC offset configuration of the reference time from a device.
+ * @brief Read the %UTC offset configuration of the reference time from a device.
This parameter is used to specify the %UTC offset of an incoming
reference time signal if a kind of time signal e.g. an IRIG input
@@ -1116,19 +1100,18 @@ extern "C" {
The macro _pcps_has_ref_offs() or the API call mbg_dev_has_ref_offs()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::MBG_REF_OFFS value to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_ref_offs()
- @see mbg_set_ref_offs()
- @see ::PCPS_GET_REF_OFFS
+ * @see ::mbg_dev_has_ref_offs
+ * @see ::mbg_set_ref_offs
*/
_MBG_API_ATTR int _MBG_API mbg_get_ref_offs( MBG_DEV_HANDLE dh, MBG_REF_OFFS *p ) ;
/**
- @brief Write the %UTC offset configuration of the reference time to a device.
+ * @brief Write the %UTC offset configuration of the reference time to a device.
This parameter is used to specify the %UTC offset of an incoming
reference time signal if a kind of time signal e.g. an IRIG input
@@ -1137,158 +1120,156 @@ extern "C" {
The macro _pcps_has_ref_offs() or the API call mbg_dev_has_ref_offs()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::MBG_REF_OFFS value to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_ref_offs()
- @see mbg_get_ref_offs()
- @see ::PCPS_SET_REF_OFFS
+ * @see ::mbg_dev_has_ref_offs
+ * @see ::mbg_get_ref_offs
*/
_MBG_API_ATTR int _MBG_API mbg_set_ref_offs( MBG_DEV_HANDLE dh, const MBG_REF_OFFS *p ) ;
/**
- @brief Read a ::MBG_OPT_INFO structure containing optional settings, controlled by flags.
+ * @brief Read a ::MBG_OPT_INFO structure containing optional settings, controlled by flags.
The ::MBG_OPT_INFO structure contains a mask of supported flags plus the current
settings of those flags.
The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::MBG_OPT_INFO structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_opt_flags()
- @see mbg_set_opt_settings()
+ * @see ::mbg_dev_has_opt_flags
+ * @see ::mbg_set_opt_settings
*/
_MBG_API_ATTR int _MBG_API mbg_get_opt_info( MBG_DEV_HANDLE dh, MBG_OPT_INFO *p ) ;
/**
- @brief Write a ::MBG_OPT_SETTINGS structure containing optional device settings.
+ * @brief Write a ::MBG_OPT_SETTINGS structure containing optional device settings.
The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags()
check whether this call is supported by a device.
The ::MBG_OPT_INFO structure should be read first to check which of the specified
flag is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::MBG_OPT_SETTINGS structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_opt_flags()
- @see mbg_get_opt_info()
+ * @see ::mbg_dev_has_opt_flags
+ * @see ::mbg_get_opt_info
*/
_MBG_API_ATTR int _MBG_API mbg_set_opt_settings( MBG_DEV_HANDLE dh, const MBG_OPT_SETTINGS *p ) ;
/**
- @brief Read the current IRIG input settings plus the supported settings.
-
- Calling this function directly is usually obsolete. The function
- mbg_get_all_irig_rx_info() should be used instead which also reads some
- other associated parameters affecting the behaviour of the IRIG input.
-
- The macro _pcps_is_irig_rx() or the API call mbg_dev_is_irig_rx()
- check whether this call is supported by a device.
-
- @param dh Valid handle to a Meinberg device
- @param *p Pointer to an ::IRIG_INFO structure to be filled up
-
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_get_all_irig_rx_info()
- @see mbg_set_irig_rx_settings()
- @see mbg_dev_is_irig_rx()
- @see mbg_dev_has_irig_tx()
- @see mbg_dev_has_irig()
- @see \ref group_icode
- */
+ * @brief Read the current IRIG input settings plus capabilities
+ *
+ * @deprecated Calling this function directly is deprecated. The function
+ * ::mbg_get_all_irig_rx_info should be used instead which also reads some
+ * other associated parameters affecting the behaviour of the IRIG input.
+ *
+ * The API call ::mbg_dev_is_irig_rx checks whether this call is supported
+ * by a device.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device
+ * @param[out] *p An ::IRIG_INFO structure to be filled up
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_get_all_irig_rx_info
+ * @see ::mbg_set_irig_rx_settings
+ * @see ::mbg_dev_is_irig_rx
+ * @see ::mbg_dev_has_irig_tx
+ * @see ::mbg_dev_has_irig
+ * @see @ref group_icode
+ */
_MBG_API_ATTR int _MBG_API mbg_get_irig_rx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p ) ;
/**
- @brief Write an ::IRIG_SETTINGS structure to a device to configure an IRIG input.
-
- Calling this function directly is usually obsolete. The function
- mbg_set_all_irig_rx_info() should be used instead which also writes some
- other associated parameters affecting the behaviour of the IRIG input.
-
- The macro _pcps_is_irig_rx() or the API call mbg_dev_is_irig_rx()
- check whether this call is supported by a device.
- The ::IRIG_INFO structure should be read first to determine the possible
- settings supported by this card's IRIG input.
-
- @param dh Valid handle to a Meinberg device
- @param *p Pointer to a ::IRIG_SETTINGS structure to be written
-
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_set_all_irig_rx_info()
- @see mbg_get_irig_rx_info()
- @see mbg_dev_is_irig_rx()
- @see mbg_dev_has_irig_tx()
- @see mbg_dev_has_irig()
- @see \ref group_icode
- */
+ * @brief Write an ::IRIG_SETTINGS structure to a device to configure an IRIG input.
+ *
+ * @deprecated Calling this function directly is deprecated. The function
+ * ::mbg_save_all_irig_rx_settings should be used instead which also writes some
+ * other associated parameters affecting the behaviour of the IRIG input.
+ *
+ * The API call ::mbg_dev_is_irig_rx checks whether this call is supported
+ * by a device. The ::IRIG_INFO structure should be read first to determine
+ * the possible settings supported by the device's IRIG input.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param[in] p Pointer to a ::IRIG_SETTINGS structure to be written
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_save_all_irig_rx_settings
+ * @see ::mbg_get_irig_rx_info
+ * @see ::mbg_dev_is_irig_rx
+ * @see ::mbg_dev_has_irig_tx
+ * @see ::mbg_dev_has_irig
+ * @see @ref group_icode
+ */
_MBG_API_ATTR int _MBG_API mbg_set_irig_rx_settings( MBG_DEV_HANDLE dh, const IRIG_SETTINGS *p ) ;
/**
- @brief Read all IRIG input configuration information from a device.
+ * @brief Read all IRIG input configuration information from a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param pdev Pointer to the device's ::PCPS_DEV structure
@param p_irig_info Pointer to a ::IRIG_SETTINGS structure to be written
@param p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written
@param p_opt_info Pointer to a ::MBG_OPT_SETTINGS structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_save_all_irig_rx_settings()
- @see mbg_set_irig_rx_settings()
- @see mbg_set_ref_offs()
- @see mbg_set_opt_settings()
+ * @see ::mbg_save_all_irig_rx_settings
+ * @see ::mbg_set_irig_rx_settings
+ * @see ::mbg_set_ref_offs
+ * @see ::mbg_set_opt_settings
*/
_MBG_API_ATTR int _MBG_API mbg_get_all_irig_rx_info( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, IRIG_INFO *p_irig_info, MBG_REF_OFFS *p_ref_offs, MBG_OPT_INFO *p_opt_info ) ;
/**
- @brief Write all IRIG input configuration settings to a device.
+ * @brief Write all IRIG input configuration settings to a device.
The macro _pcps_is_irig_rx() or the API call mbg_dev_is_irig_rx()
check whether this call is supported by a device.
The ::IRIG_INFO structure should be read first to determine the possible
settings supported by this card's IRIG input.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param pdev Pointer to the device's ::PCPS_DEV structure
@param p_irig_settings Pointer to a ::IRIG_SETTINGS structure to be written
@param p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written
@param p_opt_settings Pointer to a ::MBG_OPT_SETTINGS structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_all_irig_rx_info()
- @see mbg_set_irig_rx_settings()
- @see mbg_set_ref_offs()
- @see mbg_set_opt_settings()
+ * @see ::mbg_get_all_irig_rx_info
+ * @see ::mbg_set_irig_rx_settings
+ * @see ::mbg_set_ref_offs
+ * @see ::mbg_set_opt_settings
*/
_MBG_API_ATTR int _MBG_API mbg_save_all_irig_rx_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const IRIG_SETTINGS *p_irig_settings, const MBG_REF_OFFS *p_ref_offs, const MBG_OPT_SETTINGS *p_opt_settings ) ;
/**
- @brief Check if a device supports the mbg_get_irig_ctrl_bits() call.
+ * @brief Check if a device supports the ::mbg_get_irig_ctrl_bits call
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_get_irig_ctrl_bits()
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_get_irig_ctrl_bits
+ */
_MBG_API_ATTR int _MBG_API mbg_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Read the control function bits received from an incoming IRIG signal.
+ * @brief Read the control function bits received from an incoming IRIG signal.
This function fills a ::MBG_IRIG_CTRL_BITS structure with the control function
bits decoded from the incoming IRIG signal.
@@ -1310,30 +1291,30 @@ extern "C" {
The macro _pcps_has_irig_ctrl_bits() or the API call mbg_dev_has_irig_ctrl_bits()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::MBG_IRIG_CTRL_BITS type to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_dev_has_irig_ctrl_bits()
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_irig_ctrl_bits
+ */
_MBG_API_ATTR int _MBG_API mbg_get_irig_ctrl_bits( MBG_DEV_HANDLE dh, MBG_IRIG_CTRL_BITS *p ) ;
/**
- @brief Check if a device supports the mbg_get_raw_irig_data() call.
+ * @brief Check if a device supports the mbg_get_raw_irig_data() call.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_get_raw_irig_data()
- @see mbg_get_raw_irig_data_on_sec_change()
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_get_raw_irig_data
+ * @see ::mbg_get_raw_irig_data_on_sec_change
+ */
_MBG_API_ATTR int _MBG_API mbg_dev_has_raw_irig_data( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Read raw IRIG data from an IRIG receiver.
+ * @brief Read raw IRIG data from an IRIG receiver.
This function fills a ::MBG_RAW_IRIG_DATA structure with the raw data bits received
from the incoming IRIG signal. This enables an application itself to decode the
@@ -1342,18 +1323,18 @@ extern "C" {
The macro _pcps_has_raw_irig_data() or the API call mbg_dev_has_raw_irig_data()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_dev_has_raw_irig_data()
- @see mbg_get_raw_irig_data_on_sec_change()
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_raw_irig_data
+ * @see ::mbg_get_raw_irig_data_on_sec_change
+ */
_MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data( MBG_DEV_HANDLE dh, MBG_RAW_IRIG_DATA *p ) ;
/**
- @brief Wait for second changeover then read raw IRIG data from an IRIG receiver.
+ * @brief Wait for second changeover then read raw IRIG data from an IRIG receiver.
This function waits until the second of the device's on-board time rolls over, and
then reads the last recent raw IRIG data from the device.
@@ -1364,31 +1345,31 @@ extern "C" {
<b>Note:</b> The mbg_get_time_sec_change() function called by this function is
supported under Windows only, so this function can also only be used under Windows.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_raw_irig_data()
- @see mbg_get_raw_irig_data()
- @see mbg_get_time_sec_change()
+ * @see ::mbg_dev_has_raw_irig_data
+ * @see ::mbg_get_raw_irig_data
+ * @see ::mbg_get_time_sec_change
*/
_MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data_on_sec_change( MBG_DEV_HANDLE dh, MBG_RAW_IRIG_DATA *p ) ;
/**
- @brief Check if a device supports the mbg_get_irig_time() call.
+ * @brief Check if a device supports the mbg_get_irig_time() call.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_irig_time()
+ * @see ::mbg_get_irig_time
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_irig_time( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Read the IRIG time and day-of-year number from an IRIG receiver.
+ * @brief Read the IRIG time and day-of-year number from an IRIG receiver.
Fills up a ::PCPS_IRIG_TIME structure with the raw IRIG day-of-year number
and time decoded from the latest IRIG input frame. If the configured IRIG code
@@ -1398,33 +1379,33 @@ extern "C" {
The macro _pcps_has_irig_time() or the API call mbg_dev_has_irig_time()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_IRIG_TIME type to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_irig_time()
+ * @see ::mbg_dev_has_irig_time
*/
_MBG_API_ATTR int _MBG_API mbg_get_irig_time( MBG_DEV_HANDLE dh, PCPS_IRIG_TIME *p ) ;
/**
- @brief Clear a device's on-board time capture FIFO buffer.
+ * @brief Clear a device's on-board time capture FIFO buffer.
The macro _pcps_can_clr_ucap_buff() or the API call mbg_dev_can_clr_ucap_buff()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_can_clr_ucap_buff()
- @see mbg_get_ucap_entries()
- @see mbg_get_ucap_event()
+ * @see ::mbg_dev_can_clr_ucap_buff
+ * @see ::mbg_get_ucap_entries
+ * @see ::mbg_get_ucap_event
*/
_MBG_API_ATTR int _MBG_API mbg_clr_ucap_buff( MBG_DEV_HANDLE dh ) ;
/**
- @brief Read information on a device's event capture buffer.
+ * @brief Read information on a device's event capture buffer.
Fills a ::PCPS_UCAP_ENTRIES structure with the number of user capture
events actually stored in the FIFO buffer, and the maximum number of
@@ -1433,19 +1414,19 @@ extern "C" {
The macro _pcps_has_ucap() or the API call mbg_dev_has_ucap()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_UCAP_ENTRIES structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_ucap()
- @see mbg_get_ucap_entries()
- @see mbg_get_ucap_event()
+ * @see ::mbg_dev_has_ucap
+ * @see ::mbg_get_ucap_entries
+ * @see ::mbg_get_ucap_event
*/
_MBG_API_ATTR int _MBG_API mbg_get_ucap_entries( MBG_DEV_HANDLE dh, PCPS_UCAP_ENTRIES *p ) ;
/**
- @brief Retrieve a single time capture event from the on-board FIFO buffer.
+ * @brief Retrieve a single time capture event from the on-board FIFO buffer.
The capture event is returned in a ::PCPS_HR_TIME structure. The oldest entry
in the FIFO is retrieved and then removed from the FIFO.
@@ -1460,19 +1441,19 @@ extern "C" {
call which is obsolete but still supported for compatibility with
older cards.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_HR_TIME structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_ucap()
- @see mbg_get_ucap_entries()
- @see mbg_clr_ucap_buff()
+ * @see ::mbg_dev_has_ucap
+ * @see ::mbg_get_ucap_entries
+ * @see ::mbg_clr_ucap_buff
*/
_MBG_API_ATTR int _MBG_API mbg_get_ucap_event( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) ;
/**
- @brief Read the card's time zone/daylight saving parameters.
+ * @brief Read the card's time zone/daylight saving parameters.
This function returns the time zone/daylight saving parameters
in a ::TZDL structure.
@@ -1484,21 +1465,21 @@ extern "C" {
supported by non-GPS cards. Other cards may support the mbg_get_tzcode()
or mbg_get_pcps_tzdl() calls instead.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::TZDL structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_tzdl()
- @see mbg_set_gps_tzdl()
- @see mbg_get_tzcode()
- @see mbg_get_pcps_tzdl()
- @see \ref group_tzdl
+ * @see ::mbg_dev_has_tzdl
+ * @see ::mbg_set_gps_tzdl
+ * @see ::mbg_get_tzcode
+ * @see ::mbg_get_pcps_tzdl
+ * @see @ref group_tzdl
*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_tzdl( MBG_DEV_HANDLE dh, TZDL *p ) ;
/**
- @brief Write the card's time zone/daylight saving parameters.
+ * @brief Write the card's time zone/daylight saving parameters.
This function writes the time zone/daylight saving parameters
in a ::TZDL structure to a device.
@@ -1510,21 +1491,21 @@ extern "C" {
supported by non-GPS cards. Other cards may support the mbg_set_tzcode()
or mbg_set_pcps_tzdl() calls instead.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::TZDL structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_tzdl()
- @see mbg_get_gps_tzdl()
- @see mbg_set_tzcode()
- @see mbg_set_pcps_tzdl()
- @see \ref group_tzdl
+ * @see ::mbg_dev_has_tzdl
+ * @see ::mbg_get_gps_tzdl
+ * @see ::mbg_set_tzcode
+ * @see ::mbg_set_pcps_tzdl
+ * @see @ref group_tzdl
*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_tzdl( MBG_DEV_HANDLE dh, const TZDL *p ) ;
/**
- @brief Retrieve the software revision of a GPS receiver.
+ * @brief Retrieve the software revision of a GPS receiver.
This call is obsolete but still supported for compatibility
with older GPS cards.
@@ -1535,18 +1516,18 @@ extern "C" {
<b>Note:</b> The function mbg_get_gps_receiver_info() should
be used instead, if supported by the card.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::SW_REV structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_is_gps()
- @see mbg_get_gps_receiver_info()
+ * @see ::mbg_dev_is_gps
+ * @see ::mbg_get_gps_receiver_info
*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_sw_rev( MBG_DEV_HANDLE dh, SW_REV *p ) ;
/**
- @brief Retrieve the status of the battery buffered GPS variables.
+ * @brief Retrieve the status of the battery buffered GPS variables.
These GPS variables hold some parameters sent by the GPS satellites
which are required for proper operation. If the saved set of parameters
@@ -1556,15 +1537,15 @@ extern "C" {
The macro _pcps_is_gps() or the API call mbg_dev_is_gps()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::BVAR_STAT structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ */
_MBG_API_ATTR int _MBG_API mbg_get_gps_bvar_stat( MBG_DEV_HANDLE dh, BVAR_STAT *p ) ;
/**
- @brief Read the current board time using a ::TTM structure.
+ * @brief Read the current board time using a ::TTM structure.
The macro _pcps_is_gps() or the API call mbg_dev_is_gps()
check whether this call is supported by a device.
@@ -1572,18 +1553,18 @@ extern "C" {
<b>Note:</b> This API call is pretty slow, so the mbg_get_hr_time_..()
or mbg_get_fast_hr_timestamp...() group of calls should be used preferably.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::TTM structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_hr_time()
- @see mbg_get_fast_hr_timestamp()
+ * @see ::mbg_get_hr_time
+ * @see ::mbg_get_fast_hr_timestamp
*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_time( MBG_DEV_HANDLE dh, TTM *p ) ;
/**
- @brief Set the time on a GPS receiver device.
+ * @brief Set the time on a GPS receiver device.
Write a ::TTM structure to a GPS receiver in order to set the
on-board date and time.
@@ -1591,15 +1572,15 @@ extern "C" {
The macro _pcps_is_gps() or the API call mbg_dev_is_gps()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::TTM structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ */
_MBG_API_ATTR int _MBG_API mbg_set_gps_time( MBG_DEV_HANDLE dh, const TTM *p ) ;
/**
- @brief Read a ::PORT_PARM structure with a device's serial port configuration.
+ * @brief Read a ::PORT_PARM structure with a device's serial port configuration.
The macro _pcps_is_gps() or the API call mbg_dev_is_gps()
check whether this call is supported by a device.
@@ -1609,17 +1590,17 @@ extern "C" {
up to 2 ports. The generic function mbg_get_serial_settings()
should be used instead.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PORT_PARM structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_get_serial_settings()
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_get_serial_settings
+ */
_MBG_API_ATTR int _MBG_API mbg_get_gps_port_parm( MBG_DEV_HANDLE dh, PORT_PARM *p ) ;
/**
- @brief Write a ::PORT_PARM structure to configure the on-board serial ports.
+ * @brief Write a ::PORT_PARM structure to configure the on-board serial ports.
The macro _pcps_is_gps() or the API call mbg_dev_is_gps()
check whether this call is supported by a device.
@@ -1629,17 +1610,17 @@ extern "C" {
up to 2 ports. The generic function mbg_save_serial_settings()
should be used instead.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PORT_PARM structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_save_serial_settings()
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_save_serial_settings
+ */
_MBG_API_ATTR int _MBG_API mbg_set_gps_port_parm( MBG_DEV_HANDLE dh, const PORT_PARM *p ) ;
/**
- @brief Read an ::ANT_INFO structure to retrieve an extended GPS antenna status.
+ * @brief Read an ::ANT_INFO structure to retrieve an extended GPS antenna status.
The macro _pcps_is_gps() or the API call mbg_dev_is_gps()
check whether this call is supported by a device.
@@ -1650,15 +1631,15 @@ extern "C" {
the antenna has been reconnected <b>and</b> the receiver has synchronized
to the GPS satellites again.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ANT_INFO structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ */
_MBG_API_ATTR int _MBG_API mbg_get_gps_ant_info( MBG_DEV_HANDLE dh, ANT_INFO *p ) ;
/**
- @brief Read a time capture event from the on-board FIFO buffer using a ::TTM structure.
+ * @brief Read a time capture event from the on-board FIFO buffer using a ::TTM structure.
The macro _pcps_is_gps() or the API call mbg_dev_is_gps()
check whether this call is supported by a device.
@@ -1668,19 +1649,19 @@ extern "C" {
by the device. Anyway, this call is still supported for compatibility
with older devices.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::TTM structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_ucap_entries()
- @see mbg_get_ucap_event()
- @see mbg_clr_ucap_buff()
+ * @see ::mbg_get_ucap_entries
+ * @see ::mbg_get_ucap_event
+ * @see ::mbg_clr_ucap_buff
*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_ucap( MBG_DEV_HANDLE dh, TTM *p ) ;
/**
- @brief Read the ::ENABLE_FLAGS structure controlling when outputs are to be enabled.
+ * @brief Read the ::ENABLE_FLAGS structure controlling when outputs are to be enabled.
The ::ENABLE_FLAGS structure controls whether certain outputs
shall be enabled immediately after the card's power-up, or only
@@ -1692,18 +1673,18 @@ extern "C" {
<b>Note:</b> Not all of the input signals specified for the
::ENABLE_FLAGS structure can be modified individually.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::ENABLE_FLAGS structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see ::ENABLE_FLAGS
- @see mbg_set_gps_enable_flags()
+ * @see ::ENABLE_FLAGS
+ * @see ::mbg_set_gps_enable_flags
*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_enable_flags( MBG_DEV_HANDLE dh, ENABLE_FLAGS *p ) ;
/**
- @brief Write an ENABLE_FLAGS structure to configure when outputs shall be enabled.
+ * @brief Write an ENABLE_FLAGS structure to configure when outputs shall be enabled.
The ::ENABLE_FLAGS structure controls whether certain outputs
shall be enabled immediately after the card's power-up, or only
@@ -1715,18 +1696,18 @@ extern "C" {
<b>Note:</b> Not all of the input signals specified for the
ENABLE_FLAGS structure can be modified individually.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ENABLE_FLAGS structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see ENABLE_FLAGS
- @see mbg_get_gps_enable_flags()
+ * @see ::ENABLE_FLAGS
+ * @see ::mbg_get_gps_enable_flags
*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_enable_flags( MBG_DEV_HANDLE dh, const ENABLE_FLAGS *p ) ;
/**
- @brief Read the extended GPS receiver status from a device.
+ * @brief Read the extended GPS receiver status from a device.
The ::STAT_INFO structure reports the status of the GPS receiver,
including mode of operation and number of visible/usable satellites.
@@ -1734,32 +1715,32 @@ extern "C" {
The macro _pcps_is_gps() or the API call mbg_dev_is_gps()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::STAT_INFO structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see ::STAT_INFO
+ * @see ::STAT_INFO
*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_stat_info( MBG_DEV_HANDLE dh, STAT_INFO *p ) ;
/**
- @brief Send a ::GPS_CMD to a GPS receiver device.
+ * @brief Send a ::GPS_CMD to a GPS receiver device.
The macro _pcps_is_gps() or the API call mbg_dev_is_gps()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::GPS_CMD
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see ::PC_GPS_CMD_BOOT, ::PC_GPS_CMD_INIT_SYS, ::PC_GPS_CMD_INIT_USER, ::PC_GPS_CMD_INIT_DAC
+ * @see ::PC_GPS_CMD_BOOT, ::PC_GPS_CMD_INIT_SYS, ::PC_GPS_CMD_INIT_USER, ::PC_GPS_CMD_INIT_DAC
*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_cmd( MBG_DEV_HANDLE dh, const GPS_CMD *p ) ;
/**
- @brief Read the current geographic position from a GPS device.
+ * @brief Read the current geographic position from a GPS device.
The returned ::POS structure contains the current position in
ECEF (Earth Centered, Earth Fixed) kartesian coordinates, and in
@@ -1769,18 +1750,18 @@ extern "C" {
The macro _pcps_is_gps() or the API call mbg_dev_is_gps()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::POS structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_set_gps_pos_xyz()
- @see mbg_set_gps_pos_lla()
+ * @see ::mbg_set_gps_pos_xyz
+ * @see ::mbg_set_gps_pos_lla
*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_pos( MBG_DEV_HANDLE dh, POS *p ) ;
/**
- @brief Set the GPS receiver position using ::XYZ coordinates.
+ * @brief Set the GPS receiver position using ::XYZ coordinates.
The structure ::XYZ must specify the new position in ECEF
(Earth Centered, Earth Fixed) kartesian coordinates.
@@ -1788,75 +1769,81 @@ extern "C" {
The macro _pcps_is_gps() or the API call mbg_dev_is_gps()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param p Position in ::XYZ format to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_set_gps_pos_lla()
- @see mbg_get_gps_pos()
+ * @see ::mbg_set_gps_pos_lla
+ * @see ::mbg_get_gps_pos
*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_pos_xyz( MBG_DEV_HANDLE dh, const XYZ p ) ;
/**
- @brief Set the GPS receiver position using ::LLA coordinates.
-
- The structure LLA must specify the new position as longitude, latitude,
- and altitude, using the WGS84 geographic datum.
-
- The macro _pcps_is_gps() or the API call mbg_dev_is_gps()
- check whether this call is supported by a device.
-
- @param dh Valid handle to a Meinberg device.
- @param p Position in ::LLA format to be written
-
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_set_gps_pos_xyz()
- @see mbg_get_gps_pos()
-*/
+ * @brief Set the GPS receiver position using ::LLA coordinates
+ *
+ * The structure ::LLA must specify the new position as longitude,
+ * latitude, and altitude, using the WGS84 geographic datum.
+ *
+ * The macro ::_pcps_is_gps or the API call ::mbg_dev_is_gps
+ * check whether this call is supported by a device.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param p Position in ::LLA format to be written
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_set_gps_pos_xyz
+ * @see ::mbg_get_gps_pos
+ */
_MBG_API_ATTR int _MBG_API mbg_set_gps_pos_lla( MBG_DEV_HANDLE dh, const LLA p ) ;
/**
- @brief Read the configured GPS antenna cable length from a device.
-
- The antenna cable length parameter is used to compensate the propagation
- delay of the RF signal over the antenna cable, which is about 5 ns/m.
-
- The macro _pcps_has_cab_len() or the API call mbg_dev_has_cab_len()
- check whether this call is supported by a device.
-
- @param dh Valid handle to a Meinberg device.
- @param *p ::ANT_CABLE_LEN structure to be filled up
-
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_dev_has_cab_len()
- @see mbg_set_gps_ant_cable_len()
-*/
+ * @brief Read the configured GPS antenna cable length from a device.
+ *
+ * The antenna cable length parameter is used by GPS/GNSS receivers
+ * to compensate the propagation delay of the RF signal over the antenna
+ * cable, which is about 5 ns/m.
+ *
+ * The macro ::_pcps_has_cab_len or the API call ::mbg_dev_has_cab_len
+ * check whether this call is supported by a device.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param *p ::ANT_CABLE_LEN structure to be filled up
+ *
+ * @return One of the @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_cab_len
+ * @see ::mbg_set_gps_ant_cable_len
+ */
_MBG_API_ATTR int _MBG_API mbg_get_gps_ant_cable_len( MBG_DEV_HANDLE dh, ANT_CABLE_LEN *p ) ;
/**
- @brief Write the GPS antenna cable length configuration to a device.
-
- The antenna cable length parameter is used to compensate the propagation
- delay of the RF signal over the antenna cable, which is about 5 ns/m.
-
- The macro _pcps_has_cab_len() or the API call mbg_dev_has_cab_len()
- check whether this call is supported by a device.
-
- @param dh Valid handle to a Meinberg device.
- @param *p ::ANT_CABLE_LEN structure to be written
-
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_dev_has_cab_len()
- @see mbg_get_gps_ant_cable_len()
+ * @brief Write the GPS antenna cable length configuration to a device.
+ *
+ * The antenna cable length parameter is used by GPS/GNSS receivers
+ * to compensate the propagation delay of the RF signal over the antenna
+ * cable, which is about 5 ns/m.
+ *
+ * The macro ::_pcps_has_cab_len or the API call ::mbg_dev_has_cab_len
+ * check whether this call is supported by a device.
+ *
+ * @note Different devices may accept different maximum values, so the
+ * written value should be re-read using ::mbg_get_gps_ant_cable_len
+ * to check if the parameter has been accepted.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param *p ::ANT_CABLE_LEN structure to be written
+ *
+ * @return One of the @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_cab_len
+ * @see ::mbg_get_gps_ant_cable_len
*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_ant_cable_len( MBG_DEV_HANDLE dh, const ANT_CABLE_LEN *p ) ;
/**
- @brief Read the ::RECEIVER_INFO structure from a device.
+ * @brief Read the ::RECEIVER_INFO structure from a device.
The macro _pcps_has_receiver_info() or the API call mbg_dev_has_receiver_info()
check whether this call is supported by a device.
@@ -1865,17 +1852,17 @@ extern "C" {
preferably, which also sets up a basic ::RECEIVER_INFO structure
for devices which don't provide that structure by themselves.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::RECEIVER_INFO structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_setup_receiver_info()
+ * @see ::mbg_setup_receiver_info
*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_receiver_info( MBG_DEV_HANDLE dh, RECEIVER_INFO *p ) ;
/**
- @brief Read a ::STR_TYPE_INFO_IDX array of supported string types.
+ * @brief Read a ::STR_TYPE_INFO_IDX array of supported string types.
The function mbg_setup_receiver_info() must have been called before,
and the returned ::RECEIVER_INFO structure passed to this function.
@@ -1883,20 +1870,20 @@ extern "C" {
<b>Note:</b> The function mbg_get_serial_settings() should be used preferably
to get retrieve the current port settings and configuration options.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param stii Pointer to a an array of string type information to be filled up
@param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info()
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_setup_receiver_info()
- @see mbg_get_gps_all_port_info()
- @see mbg_get_serial_settings()
+ * @see ::mbg_setup_receiver_info
+ * @see ::mbg_get_gps_all_port_info
+ * @see ::mbg_get_serial_settings
*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_all_str_type_info( MBG_DEV_HANDLE dh, STR_TYPE_INFO_IDX stii[], const RECEIVER_INFO *p_ri ) ;
/**
- @brief Read a ::PORT_INFO_IDX array of supported serial port configurations.
+ * @brief Read a ::PORT_INFO_IDX array of supported serial port configurations.
The function mbg_setup_receiver_info() must have been called before,
and the returned ::RECEIVER_INFO structure passed to this function.
@@ -1904,20 +1891,20 @@ extern "C" {
<b>Note:</b> The function mbg_get_serial_settings() should be used preferably
to get retrieve the current port settings and configuration options.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param pii Pointer to a an array of port configuration information to be filled up
@param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info()
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_setup_receiver_info()
- @see mbg_get_gps_all_str_type_info()
- @see mbg_get_serial_settings()
+ * @see ::mbg_setup_receiver_info
+ * @see ::mbg_get_gps_all_str_type_info
+ * @see ::mbg_get_serial_settings
*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_all_port_info( MBG_DEV_HANDLE dh, PORT_INFO_IDX pii[], const RECEIVER_INFO *p_ri ) ;
/**
- @brief Write the configuration for a single serial port to a device.
+ * @brief Write the configuration for a single serial port to a device.
The ::PORT_SETTINGS_IDX structure contains both the ::PORT_SETTINGS
and the port index value. Except for the parameter types this call is
@@ -1929,19 +1916,19 @@ extern "C" {
<b>Note:</b> The function mbg_save_serial_settings() should be used preferably
to write new port configuration to the board.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PORT_SETTINGS_IDX structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_save_serial_settings()
- @see mbg_set_gps_port_settings()
- @see mbg_dev_has_receiver_info()
+ * @see ::mbg_save_serial_settings
+ * @see ::mbg_set_gps_port_settings
+ * @see ::mbg_dev_has_receiver_info
*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings_idx( MBG_DEV_HANDLE dh, const PORT_SETTINGS_IDX *p ) ;
/**
- @brief Write the configuration for a single serial port to a device.
+ * @brief Write the configuration for a single serial port to a device.
The ::PORT_SETTINGS structure does not contain the port index, so the
the port index must be given separately. Except for the parameter types
@@ -1953,20 +1940,20 @@ extern "C" {
<b>Note:</b> The function mbg_save_serial_settings() should be used preferably
to write new port configuration to the board.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PORT_SETTINGS structure to be filled up
@param idx Index of the serial port to be configured (starting from 0 ).
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_save_serial_settings()
- @see mbg_set_gps_port_settings_idx()
- @see mbg_dev_has_receiver_info()
+ * @see ::mbg_save_serial_settings
+ * @see ::mbg_set_gps_port_settings_idx
+ * @see ::mbg_dev_has_receiver_info
*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings( MBG_DEV_HANDLE dh, const PORT_SETTINGS *p, int idx ) ;
/**
- @brief Set up a ::RECEIVER_INFO structure for a device.
+ * @brief Set up a ::RECEIVER_INFO structure for a device.
If the device supports the ::RECEIVER_INFO structure then the structure
is read from the device, otherwise a structure is set up using
@@ -1974,65 +1961,65 @@ extern "C" {
The function mbg_get_device_info() must have been called before,
and the returned PCPS_DEV structure passed to this function.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *pdev Pointer to a ::PCPS_DEV structure returned by mbg_get_device_info()
@param *p Pointer to a ::RECEIVER_INFO structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_device_info()
- @see mbg_dev_has_receiver_info()
+ * @see ::mbg_get_device_info
+ * @see ::mbg_dev_has_receiver_info
*/
_MBG_API_ATTR int _MBG_API mbg_setup_receiver_info( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, RECEIVER_INFO *p ) ;
/**
- @brief Read the version code of the on-board PCI/PCIe interface ASIC.
+ * @brief Read the version code of the on-board PCI/PCIe interface ASIC.
The macro _pcps_has_asic_version() or the API call mbg_dev_has_asic_version()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCI_ASIC_VERSION type to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_asic_version()
+ * @see ::mbg_dev_has_asic_version
*/
_MBG_API_ATTR int _MBG_API mbg_get_asic_version( MBG_DEV_HANDLE dh, PCI_ASIC_VERSION *p ) ;
/**
- @brief Read the features of the on-board PCI/PCIe interface ASIC.
+ * @brief Read the features of the on-board PCI/PCIe interface ASIC.
The macro _pcps_has_asic_features() or the API call mbg_dev_has_asic_features()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCI_ASIC_FEATURES type to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_asic_features()
+ * @see ::mbg_dev_has_asic_features
*/
_MBG_API_ATTR int _MBG_API mbg_get_asic_features( MBG_DEV_HANDLE dh, PCI_ASIC_FEATURES *p ) ;
/**
- @brief Check if a device supports configurable time scales.
+ * @brief Check if a device supports configurable time scales.
By default the cards return UTC and/or local time. However, some cards
can be configured to return raw GPS time or TAI instead.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_time_scale_info()
- @see mbg_set_time_scale_settings()
+ * @see ::mbg_get_time_scale_info
+ * @see ::mbg_set_time_scale_settings
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_time_scale( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Read the current time scale settings and which time scales are supported.
+ * @brief Read the current time scale settings and which time scales are supported.
The ::MBG_TIME_SCALE_INFO structure tells which time scale settings are supported
by a device, and which time scale is currently configured.
@@ -2041,18 +2028,18 @@ extern "C" {
check whether this call is supported by a device.
See also the notes for mbg_dev_has_time_scale().
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::MBG_TIME_SCALE_INFO structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_set_time_scale_settings()
- @see mbg_dev_has_time_scale()
+ * @see ::mbg_set_time_scale_settings
+ * @see ::mbg_dev_has_time_scale
*/
_MBG_API_ATTR int _MBG_API mbg_get_time_scale_info( MBG_DEV_HANDLE dh, MBG_TIME_SCALE_INFO *p ) ;
/**
- @brief Write the time scale configuration to a device.
+ * @brief Write the time scale configuration to a device.
The ::MBG_TIME_SCALE_SETTINGS structure determines which time scale
is to be used for the time stamps which can be read from a device.
@@ -2064,18 +2051,18 @@ extern "C" {
The function mbg_get_time_scale_info() should have been called before
in order to determine which time scales are supported by the card.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::MBG_TIME_SCALE_SETTINGS structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_time_scale_info()
- @see mbg_dev_has_time_scale()
+ * @see ::mbg_get_time_scale_info
+ * @see ::mbg_dev_has_time_scale
*/
- _MBG_API_ATTR int _MBG_API mbg_set_time_scale_settings( MBG_DEV_HANDLE dh, MBG_TIME_SCALE_SETTINGS *p ) ;
+ _MBG_API_ATTR int _MBG_API mbg_set_time_scale_settings( MBG_DEV_HANDLE dh, const MBG_TIME_SCALE_SETTINGS *p ) ;
/**
- @brief Check if a device support reading/writing of UTC parameters.
+ * @brief Check if a device support reading/writing of UTC parameters.
This API call checks if a device supports reading/writing a GPS UTC
parameter set via the PC bus. Reading/writing these parameters via the
@@ -2089,35 +2076,35 @@ extern "C" {
It may be useful to overwrite them to do some tests, or for applications
where a card is freewheeling.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_utc_parm()
- @see mbg_set_utc_parm()
+ * @see ::mbg_get_utc_parm
+ * @see ::mbg_set_utc_parm
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_utc_parm( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Read a ::UTC parameter structure from a device.
+ * @brief Read a ::UTC parameter structure from a device.
The macro _pcps_has_utc_parm() or the API call mbg_dev_has_utc_parm()
check whether this call is supported by a device.
See also the notes for mbg_dev_has_utc_parm().
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::UTC structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_utc_parm()
- @see mbg_set_utc_parm()
+ * @see ::mbg_dev_has_utc_parm
+ * @see ::mbg_set_utc_parm
*/
_MBG_API_ATTR int _MBG_API mbg_get_utc_parm( MBG_DEV_HANDLE dh, UTC *p ) ;
/**
- @brief Write a ::UTC parameter structure to a device.
+ * @brief Write a ::UTC parameter structure to a device.
This should only be done for testing, or if a card is operated in
freewheeling mode. If the receiver is tracking any satellites then the settings
@@ -2128,18 +2115,18 @@ extern "C" {
check whether this call is supported by a device.
See also the notes for mbg_dev_has_utc_parm().
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a valid ::UTC structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_utc_parm()
- @see mbg_get_utc_parm()
+ * @see ::mbg_dev_has_utc_parm
+ * @see ::mbg_get_utc_parm
*/
- _MBG_API_ATTR int _MBG_API mbg_set_utc_parm( MBG_DEV_HANDLE dh, UTC *p ) ;
+ _MBG_API_ATTR int _MBG_API mbg_set_utc_parm( MBG_DEV_HANDLE dh, const UTC *p ) ;
/**
- @brief Read the current time plus the associated PC cycles from a device.
+ * @brief Read the current time plus the associated PC cycles from a device.
The ::PCPS_TIME_CYCLES structure contains a ::PCPS_TIME structure
and a PC cycle counter value which can be used to compensate the latency
@@ -2159,20 +2146,20 @@ extern "C" {
latency of the call in units of the cycle counter clock frequency, e.g as reported
by QueryPerformanceFrequency() under Windows.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_TIME_CYCLES structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_hr_time_cycles()
- @see mbg_get_hr_time_comp()
- @see mbg_get_hr_time()
- @see mbg_get_time()
+ * @see ::mbg_get_hr_time_cycles
+ * @see ::mbg_get_hr_time_comp
+ * @see ::mbg_get_hr_time
+ * @see ::mbg_get_time
*/
_MBG_API_ATTR int _MBG_API mbg_get_time_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_CYCLES *p ) ;
/**
- @brief Read the current high resolution time plus the associated PC cycles from a device.
+ * @brief Read the current high resolution time plus the associated PC cycles from a device.
The ::PCPS_HR_TIME_CYCLES structure contains a ::PCPS_HR_TIME structure
and a PC cycle counter value which can be used to compensate the latency
@@ -2191,20 +2178,20 @@ extern "C" {
latency of the call in units of the cycle counter clock frequency, e.g as reported
by QueryPerformanceFrequency() under Windows.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_HR_TIME_CYCLES structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_hr_time_comp()
- @see mbg_get_hr_time()
- @see mbg_get_time_cycles()
- @see mbg_get_time()
+ * @see ::mbg_get_hr_time_comp
+ * @see ::mbg_get_hr_time
+ * @see ::mbg_get_time_cycles
+ * @see ::mbg_get_time
*/
_MBG_API_ATTR int _MBG_API mbg_get_hr_time_cycles( MBG_DEV_HANDLE dh, PCPS_HR_TIME_CYCLES *p ) ;
/**
- @brief Read the current high resolution time, and compensate the call's latency.
+ * @brief Read the current high resolution time, and compensate the call's latency.
Read a ::PCPS_HR_TIME structure plus cycle counter value, and correct the
time stamp for the latency of the call as described for mbg_get_hr_time_cycles(),
@@ -2222,22 +2209,22 @@ extern "C" {
latency of the call in units of the cycle counter clock frequency, e.g as reported
by QueryPerformanceFrequency() under Windows.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_HR_TIME structure to be filled up
@param *hns_latency Optional pointer to an int32_t value to return
the latency in 100ns units. Pass NULL if not used.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_hr_time_comp()
- @see mbg_get_hr_time()
- @see mbg_get_time_cycles()
- @see mbg_get_time()
+ * @see ::mbg_get_hr_time_comp
+ * @see ::mbg_get_hr_time
+ * @see ::mbg_get_time_cycles
+ * @see ::mbg_get_time
*/
_MBG_API_ATTR int _MBG_API mbg_get_hr_time_comp( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p, int32_t *hns_latency ) ;
/**
- @brief Read the current IRIG output settings plus the supported settings.
+ * @brief Read the current IRIG output settings plus the supported settings.
The returned ::IRIG_INFO structure contains the configuration of an IRIG output
plus the possible settings supported by that output.
@@ -2245,146 +2232,146 @@ extern "C" {
The macro _pcps_has_irig_tx() or the API call mbg_dev_has_irig_tx()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an ::IRIG_INFO structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_set_irig_tx_settings()
- @see mbg_dev_has_irig_tx()
- @see mbg_dev_is_irig_rx()
- @see mbg_dev_has_irig()
- @see \ref group_icode
+ * @see ::mbg_set_irig_tx_settings
+ * @see ::mbg_dev_has_irig_tx
+ * @see ::mbg_dev_is_irig_rx
+ * @see ::mbg_dev_has_irig
+ * @see @ref group_icode
*/
_MBG_API_ATTR int _MBG_API mbg_get_irig_tx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p ) ;
/**
- @brief Write an ::IRIG_SETTINGS structure to a device to configure the IRIG output.
+ * @brief Write an ::IRIG_SETTINGS structure to a device to configure the IRIG output.
The macro _pcps_has_irig_tx() or the API call mbg_dev_has_irig_tx()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an ::IRIG_INFO structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_irig_tx_info()
- @see mbg_dev_has_irig_tx()
- @see mbg_dev_is_irig_rx()
- @see mbg_dev_has_irig()
- @see \ref group_icode
+ * @see ::mbg_get_irig_tx_info
+ * @see ::mbg_dev_has_irig_tx
+ * @see ::mbg_dev_is_irig_rx
+ * @see ::mbg_dev_has_irig
+ * @see @ref group_icode
*/
_MBG_API_ATTR int _MBG_API mbg_set_irig_tx_settings( MBG_DEV_HANDLE dh, const IRIG_SETTINGS *p ) ;
/**
- @brief Read the current frequency synthesizer settings from a device.
-
- Read a ::SYNTH structure containing the configuration of an optional
- on-board programmable frequency synthesizer.
-
- The macro _pcps_has_synth() or the API call mbg_dev_has_synth()
- check whether this call is supported by a device.
-
- @param dh Valid handle to a Meinberg device
- @param *p Pointer to a ::SYNTH structure to be filled up
-
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_dev_has_synth()
- @see mbg_set_synth()
- @see mbg_get_synth_state()
- @see \ref group_synth
-*/
+ * @brief Read the current frequency synthesizer settings from a device.
+ *
+ * Read a ::SYNTH structure containing the configuration of an optional
+ * on-board programmable frequency synthesizer.
+ *
+ * The macro ::_pcps_has_synth or the API call ::mbg_dev_has_synth
+ * check whether this call is supported by a device.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param *p Pointer to a ::SYNTH structure to be filled up
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_synth
+ * @see ::mbg_set_synth
+ * @see ::mbg_get_synth_state
+ * @see @ref group_synth
+ */
_MBG_API_ATTR int _MBG_API mbg_get_synth( MBG_DEV_HANDLE dh, SYNTH *p ) ;
/**
- @brief Write some frequency synthesizer settings to a device.
-
- Write a ::SYNTH structure containing the configuration of an optional
- on-board programmable frequency synthesizer.
-
- The macro _pcps_has_synth() or the API call mbg_dev_has_synth()
- check whether this call is supported by a device.
-
- @param dh Valid handle to a Meinberg device
- @param *p Pointer to a ::SYNTH structure to be written
-
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_dev_has_synth()
- @see mbg_get_synth()
- @see mbg_get_synth_state()
- @see \ref group_synth
-*/
+ * @brief Write some frequency synthesizer settings to a device.
+ *
+ * Write a ::SYNTH structure containing the configuration of an optional
+ * on-board programmable frequency synthesizer.
+ *
+ * The macro _pcps_has_synth() or the API call mbg_dev_has_synth()
+ * check whether this call is supported by a device.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param *p Pointer to a ::SYNTH structure to be written
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_synth
+ * @see ::mbg_get_synth
+ * @see ::mbg_get_synth_state
+ * @see @::\ref group_synth
+ */
_MBG_API_ATTR int _MBG_API mbg_set_synth( MBG_DEV_HANDLE dh, const SYNTH *p ) ;
/**
- @brief Read the current status of the on-board frequency synthesizer.
+ * @brief Read the current status of the on-board frequency synthesizer.
The macro _pcps_has_synth() or the API call mbg_dev_has_synth()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::SYNTH_STATE structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_synth()
- @see mbg_get_synth()
- @see mbg_set_synth()
- @see \ref group_synth
+ * @see ::mbg_dev_has_synth
+ * @see ::mbg_get_synth
+ * @see ::mbg_set_synth
+ * @see @ref group_synth
*/
_MBG_API_ATTR int _MBG_API mbg_get_synth_state( MBG_DEV_HANDLE dh, SYNTH_STATE *p ) ;
/**
- @brief Check if a device supports the mbg_get_fast_hr_timestamp_...() calls.
+ * @brief Check if a device supports the mbg_get_fast_hr_timestamp_...() calls.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_fast_hr_timestamp_cycles()
- @see mbg_get_fast_hr_timestamp_comp()
- @see mbg_get_fast_hr_timestamp()
+ * @see ::mbg_get_fast_hr_timestamp_cycles
+ * @see ::mbg_get_fast_hr_timestamp_comp
+ * @see ::mbg_get_fast_hr_timestamp
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_fast_hr_timestamp( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Read a high resolution ::PCPS_TIME_STAMP_CYCLES structure via memory mapped access.
+ * @brief Read a high resolution ::PCPS_TIME_STAMP_CYCLES structure via memory mapped access.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_TIME_STAMP_CYCLES structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_fast_hr_timestamp()
- @see mbg_get_fast_hr_timestamp_comp()
- @see mbg_get_fast_hr_timestamp()
+ * @see ::mbg_dev_has_fast_hr_timestamp
+ * @see ::mbg_get_fast_hr_timestamp_comp
+ * @see ::mbg_get_fast_hr_timestamp
*/
_MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP_CYCLES *p ) ;
/**
- @brief Read a high resolution timestamp and compensate the latency of the call.
+ * @brief Read a high resolution timestamp and compensate the latency of the call.
The retrieved ::PCPS_TIME_STAMP is read from memory mapped registers,
and timestamp is compensated for the call's latency before it is returned.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_TIME_STAMP structure to be filled up
@param *hns_latency Optionally receive the latency in hectonanoseconds
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_fast_hr_timestamp()
- @see mbg_get_fast_hr_timestamp_cycles()
- @see mbg_get_fast_hr_timestamp()
+ * @see ::mbg_dev_has_fast_hr_timestamp
+ * @see ::mbg_get_fast_hr_timestamp_cycles
+ * @see ::mbg_get_fast_hr_timestamp
*/
_MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_comp( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP *p, int32_t *hns_latency ) ;
/**
- @brief Read a high resolution ::PCPS_TIME_STAMP structure via memory mapped access.
+ * @brief Read a high resolution ::PCPS_TIME_STAMP structure via memory mapped access.
This function does not return or evaluate a cycles count, so the latency
of the call can not be determined. However, depending on the timer hardware
@@ -2392,167 +2379,167 @@ extern "C" {
on some hardware architectures, so this call can be used to yield lower
latencies, under the restriction to be unable to determine the exact latency.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_TIME_STAMP structure to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_fast_hr_timestamp()
- @see mbg_get_fast_hr_timestamp_comp()
- @see mbg_get_fast_hr_timestamp_cycles()
+ * @see ::mbg_dev_has_fast_hr_timestamp
+ * @see ::mbg_get_fast_hr_timestamp_comp
+ * @see ::mbg_get_fast_hr_timestamp_cycles
*/
_MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP *p ) ;
/**
- @brief Check if a device is a GPS receiver.
+ * @brief Check if a device is a GPS receiver.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ */
_MBG_API_ATTR int _MBG_API mbg_dev_is_gps( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device is a DCF77 receiver.
+ * @brief Check if a device is a DCF77 receiver.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ */
_MBG_API_ATTR int _MBG_API mbg_dev_is_dcf( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device is a MSF receiver.
+ * @brief Check if a device is a MSF receiver.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ */
_MBG_API_ATTR int _MBG_API mbg_dev_is_msf( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device is a WWVB receiver.
+ * @brief Check if a device is a WWVB receiver.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ */
_MBG_API_ATTR int _MBG_API mbg_dev_is_wwvb( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device is any long wave signal receiver.
+ * @brief Check if a device is any long wave signal receiver.
Long wave receivers include e.g. DCF77, MSF, WWVB, or JJY.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ */
_MBG_API_ATTR int _MBG_API mbg_dev_is_lwr( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device provides a configurable IRIG input.
+ * @brief Check if a device provides a configurable IRIG input.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_irig_rx_info()
- @see mbg_set_irig_rx_settings()
- @see mbg_dev_has_irig_tx()
- @see mbg_dev_has_irig()
+ * @see ::mbg_get_irig_rx_info
+ * @see ::mbg_set_irig_rx_settings
+ * @see ::mbg_dev_has_irig_tx
+ * @see ::mbg_dev_has_irig
*/
_MBG_API_ATTR int _MBG_API mbg_dev_is_irig_rx( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports the HR_TIME functions.
+ * @brief Check if a device supports the HR_TIME functions.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_hr_time()
- @see mbg_get_hr_time_cycles()
- @see mbg_get_hr_time_comp()
+ * @see ::mbg_get_hr_time
+ * @see ::mbg_get_hr_time_cycles
+ * @see ::mbg_get_hr_time_comp
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_hr_time( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports configuration of antenna cable length.
+ * @brief Check if a device supports configuration of antenna cable length.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_gps_ant_cable_len()
- @see mbg_set_gps_ant_cable_len()
+ * @see ::mbg_get_gps_ant_cable_len
+ * @see ::mbg_set_gps_ant_cable_len
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_cab_len( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports timezone configuration using the ::TZDL structure.
+ * @brief Check if a device supports timezone configuration using the ::TZDL structure.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_gps_tzdl()
- @see mbg_set_gps_tzdl()
- @see mbg_dev_has_tz()
+ * @see ::mbg_get_gps_tzdl
+ * @see ::mbg_set_gps_tzdl
+ * @see ::mbg_dev_has_tz
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_tzdl( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure.
+ * @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_pcps_tzdl()
- @see mbg_set_pcps_tzdl()
- @see mbg_dev_has_tz()
+ * @see ::mbg_get_pcps_tzdl
+ * @see ::mbg_set_pcps_tzdl
+ * @see ::mbg_dev_has_tz
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_pcps_tzdl( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports timezone configuration using the ::PCPS_TZCODE type.
+ * @brief Check if a device supports timezone configuration using the ::PCPS_TZCODE type.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_tzcode()
- @see mbg_set_tzcode()
- @see mbg_dev_has_tz()
+ * @see ::mbg_get_tzcode
+ * @see ::mbg_set_tzcode
+ * @see ::mbg_dev_has_tz
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_tzcode( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports any kind of timezone configuration.
+ * @brief Check if a device supports any kind of timezone configuration.
This can be used e.g. to check if a specifig dialog or menu has to
be displayed.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_tzdl()
- @see mbg_dev_has_pcps_tzdl()
- @see mbg_dev_has_tzcode()
+ * @see ::mbg_dev_has_tzdl
+ * @see ::mbg_dev_has_pcps_tzdl
+ * @see ::mbg_dev_has_tzcode
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_tz( MBG_DEV_HANDLE dh, int *p ) ;
@@ -2562,17 +2549,17 @@ extern "C" {
<b>Note:</b> This is only supported by some special firmware.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_set_event_time()
+ * @see ::mbg_set_event_time
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_event_time( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports the ::RECEIVER_INFO structure and related calls.
+ * @brief Check if a device supports the ::RECEIVER_INFO structure and related calls.
@note Older GPS devices may not support that structure.
@@ -2580,62 +2567,62 @@ extern "C" {
::RECEIVER_INFO can be read directly from a device, or whether a default
structure has to be set up using default values depending on the device type.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_gps_receiver_info()
+ * @see ::mbg_get_gps_receiver_info
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_receiver_info( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports the mbg_clr_ucap_buff() call.
+ * @brief Check if a device supports the mbg_clr_ucap_buff() call.
The mbg_clr_ucap_buff() call can be used to clear a card's on-board
time capture FIFO buffer.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_clr_ucap_buff()
+ * @see ::mbg_clr_ucap_buff
*/
_MBG_API_ATTR int _MBG_API mbg_dev_can_clr_ucap_buff( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports the mbg_get_ucap_entries() and mbg_get_ucap_event() calls.
+ * @brief Check if a device supports the mbg_get_ucap_entries() and mbg_get_ucap_event() calls.
If the card does not but it is a GPS card then the card provides
a time capture FIFO buffer and the obsolete mbg_get_gps_ucap()
call can be used to retrieve entries from the FIFO buffer.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_ucap_entries()
- @see mbg_get_ucap_event()
- @see mbg_clr_ucap_buff()
- @see mbg_get_gps_ucap()
+ * @see ::mbg_get_ucap_entries
+ * @see ::mbg_get_ucap_event
+ * @see ::mbg_clr_ucap_buff
+ * @see ::mbg_get_gps_ucap
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_ucap( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device provides a configurable IRIG output.
+ * @brief Check if a device provides a configurable IRIG output.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_irig_tx_info()
- @see mbg_set_irig_tx_settings()
- @see mbg_dev_is_irig_rx()
- @see mbg_dev_has_irig()
- @see \ref group_icode
+ * @see ::mbg_get_irig_tx_info
+ * @see ::mbg_set_irig_tx_settings
+ * @see ::mbg_dev_is_irig_rx
+ * @see ::mbg_dev_has_irig
+ * @see @ref group_icode
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_irig_tx( MBG_DEV_HANDLE dh, int *p ) ;
@@ -2648,149 +2635,149 @@ extern "C" {
The mbg_get_serial_settings() takes care of this, so applications
which use that call as suggested won't need to use this call directly.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_serial_settings()
+ * @see ::mbg_get_serial_settings
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_serial_hs( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device provides the level of its inputs signal.
+ * @brief Check if a device provides the level of its inputs signal.
This is useful to display the signal level of e.g. an IRIG or longwave signal.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ */
_MBG_API_ATTR int _MBG_API mbg_dev_has_signal( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device provides a modulation signal.
+ * @brief Check if a device provides a modulation signal.
Modulation signals are e.g. the second marks of a DCF77 AM receiver.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ */
_MBG_API_ATTR int _MBG_API mbg_dev_has_mod( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device provides either an IRIG input or output.
+ * @brief Check if a device provides either an IRIG input or output.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_dev_is_irig_rx()
- @see mbg_dev_has_irig_tx()
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_is_irig_rx
+ * @see ::mbg_dev_has_irig_tx
+ */
_MBG_API_ATTR int _MBG_API mbg_dev_has_irig( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device provides a configurable ref time offset.
+ * @brief Check if a device provides a configurable ref time offset.
This may be required to convert the received time to %UTC, if the input
signal doesn't specify this (e.g. most IRIG code formats).
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-
- @see mbg_get_ref_offs()
- @see mbg_set_ref_offs()
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_get_ref_offs
+ * @see ::mbg_set_ref_offs
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_ref_offs( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS.
+ * @brief Check if a device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS.
These structures containing optional settings, controlled by flags.
See ::MBG_OPT_SETTINGS and related definitions.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_opt_info()
- @see mbg_set_opt_settings()
+ * @see ::mbg_get_opt_info
+ * @see ::mbg_set_opt_settings
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_opt_flags( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports large configuration data structures.
+ * @brief Check if a device supports large configuration data structures.
Such structures have been introduced with the first Meinberg GPS receivers.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
-*/
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ */
_MBG_API_ATTR int _MBG_API mbg_dev_has_gps_data( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device provides a programmable frequency synthesizer.
+ * @brief Check if a device provides a programmable frequency synthesizer.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_synth()
- @see mbg_set_synth()
+ * @see ::mbg_get_synth
+ * @see ::mbg_set_synth
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_synth( MBG_DEV_HANDLE dh, int *p ) ;
/* (Intentionally excluded from Doxygen)
- @brief Check if a device supports the mbg_generic_io() call.
+ * @brief Check if a device supports the mbg_generic_io() call.
<b>Warning</b>: That call is for debugging purposes and internal use only!
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_generic_io()
+ * @see ::mbg_generic_io()
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_generic_io( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports the mbg_get_asic_version() call.
+ * @brief Check if a device supports the mbg_get_asic_version() call.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_asic_version()
+ * @see ::mbg_get_asic_version
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_asic_version( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports the mbg_get_asic_features() call.
+ * @brief Check if a device supports the mbg_get_asic_features() call.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_asic_features()
+ * @see ::mbg_get_asic_features
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_asic_features( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Read current configuraton and features provided by the programmable pulse outputs.
+ * @brief Read current configuraton and features provided by the programmable pulse outputs.
Reads a ::POUT_INFO_IDX array of current settings and configuration
options of the device's programmable pulse outputs.
@@ -2803,20 +2790,20 @@ extern "C" {
The array passed to this function to receive the returned data
must be able to hold at least ::RECEIVER_INFO::n_prg_out elements.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param pii Pointer to a an array of ::POUT_INFO_IDX structures to be filled up
@param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info()
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_set_gps_pout_settings_idx()
- @see mbg_set_gps_pout_settings()
- @see mbg_setup_receiver_info()
+ * @see ::mbg_set_gps_pout_settings_idx
+ * @see ::mbg_set_gps_pout_settings
+ * @see ::mbg_setup_receiver_info
*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_all_pout_info( MBG_DEV_HANDLE dh, POUT_INFO_IDX pii[], const RECEIVER_INFO *p_ri ) ;
/**
- @brief Write the configuration for a single programmable pulse output
+ * @brief Write the configuration for a single programmable pulse output
The ::POUT_SETTINGS_IDX structure contains both the ::POUT_SETTINGS
and the output index value. Except for the parameter types this call
@@ -2826,18 +2813,18 @@ extern "C" {
(i.e. the number of programmable outputs on the board) is not 0, and the
output index value must be in the range 0..::RECEIVER_INFO::n_prg_out.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::POUT_SETTINGS_IDX structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_gps_all_pout_info()
- @see mbg_set_gps_pout_settings()
+ * @see ::mbg_get_gps_all_pout_info
+ * @see ::mbg_set_gps_pout_settings
*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings_idx( MBG_DEV_HANDLE dh, const POUT_SETTINGS_IDX *p ) ;
/**
- @brief Write the configuration for a single programmable pulse output
+ * @brief Write the configuration for a single programmable pulse output
The ::POUT_SETTINGS structure does not contain the index of the
programmable output to be configured, so the index must explicitely
@@ -2848,227 +2835,227 @@ extern "C" {
(i.e. the number of programmable outputs on the board) is not 0, and the
output index value must be in the range 0..::RECEIVER_INFO::n_prg_out.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::POUT_SETTINGS structure to be written
@param idx Index of the programmable pulse output to be configured (starting from 0 ).
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_gps_all_pout_info()
- @see mbg_set_gps_pout_settings_idx()
+ * @see ::mbg_get_gps_all_pout_info
+ * @see ::mbg_set_gps_pout_settings_idx
*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings( MBG_DEV_HANDLE dh, const POUT_SETTINGS *p, int idx ) ;
/**
- @brief Read a device's IRQ status information.
+ * @brief Read a device's IRQ status information.
IRQ status information includes flags indicating whether IRQs are
actually enabled, and whether IRQ support by a card is possibly
unsafe due to the firmware and interface chip version.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PCPS_IRQ_STAT_INFO variable to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
- */
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ */
_MBG_API_ATTR int _MBG_API mbg_get_irq_stat_info( MBG_DEV_HANDLE dh, PCPS_IRQ_STAT_INFO *p ) ;
/**
- @brief Check if a device provides simple LAN interface API calls.
+ * @brief Check if a device provides simple LAN interface API calls.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_lan_if_info()
- @see mbg_get_ip4_state()
- @see mbg_get_ip4_settings()
- @see mbg_set_ip4_settings()
+ * @see ::mbg_get_lan_if_info
+ * @see ::mbg_get_ip4_state
+ * @see ::mbg_get_ip4_settings
+ * @see ::mbg_set_ip4_settings
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_lan_intf( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Read LAN interface information from a device.
+ * @brief Read LAN interface information from a device.
The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::LAN_IF_INFO variable to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_lan_intf()
- @see mbg_get_ip4_state()
- @see mbg_get_ip4_settings()
- @see mbg_set_ip4_settings()
+ * @see ::mbg_dev_has_lan_intf
+ * @see ::mbg_get_ip4_state
+ * @see ::mbg_get_ip4_settings
+ * @see ::mbg_set_ip4_settings
*/
_MBG_API_ATTR int _MBG_API mbg_get_lan_if_info( MBG_DEV_HANDLE dh, LAN_IF_INFO *p ) ;
/**
- @brief Read LAN IPv4 state from a device.
+ * @brief Read LAN IPv4 state from a device.
The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::IP4_SETTINGS variable to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_lan_intf()
- @see mbg_get_lan_if_info()
- @see mbg_get_ip4_settings()
- @see mbg_set_ip4_settings()
+ * @see ::mbg_dev_has_lan_intf
+ * @see ::mbg_get_lan_if_info
+ * @see ::mbg_get_ip4_settings
+ * @see ::mbg_set_ip4_settings
*/
_MBG_API_ATTR int _MBG_API mbg_get_ip4_state( MBG_DEV_HANDLE dh, IP4_SETTINGS *p ) ;
/**
- @brief Read LAN IPv4 settings from a device.
+ * @brief Read LAN IPv4 settings from a device.
The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::IP4_SETTINGS variable to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_lan_intf()
- @see mbg_get_lan_if_info()
- @see mbg_get_ip4_state()
- @see mbg_set_ip4_settings()
+ * @see ::mbg_dev_has_lan_intf
+ * @see ::mbg_get_lan_if_info
+ * @see ::mbg_get_ip4_state
+ * @see ::mbg_set_ip4_settings
*/
_MBG_API_ATTR int _MBG_API mbg_get_ip4_settings( MBG_DEV_HANDLE dh, IP4_SETTINGS *p ) ;
/**
- @brief Write LAN IPv4 settings to a device.
+ * @brief Write LAN IPv4 settings to a device.
The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p ::IP4_SETTINGS structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_lan_intf()
- @see mbg_get_lan_if_info()
- @see mbg_get_ip4_settings()
+ * @see ::mbg_dev_has_lan_intf
+ * @see ::mbg_get_lan_if_info
+ * @see ::mbg_get_ip4_settings
*/
_MBG_API_ATTR int _MBG_API mbg_set_ip4_settings( MBG_DEV_HANDLE dh, const IP4_SETTINGS *p ) ;
/**
- @brief Check if a device provides PTP configuration/status calls.
+ * @brief Check if a device provides PTP configuration/status calls.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_all_ptp_cfg_info
- @see mbg_get_ptp_state
- @see mbg_get_ptp_cfg_info
- @see mbg_set_ptp_cfg_settings
- @see mbg_dev_has_ptp_unicast
+ * @see ::mbg_get_all_ptp_cfg_info
+ * @see ::mbg_get_ptp_state
+ * @see ::mbg_get_ptp_cfg_info
+ * @see ::mbg_set_ptp_cfg_settings
+ * @see ::mbg_dev_has_ptp_unicast
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_ptp( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device provides PTP unicast feature/configuration.
+ * @brief Check if a device provides PTP unicast feature/configuration.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_all_ptp_cfg_info
- @see mbg_get_ptp_uc_master_cfg_limits
- @see mbg_get_all_ptp_uc_master_info
- @see mbg_set_ptp_uc_master_settings_idx
- @see mbg_get_ptp_state
+ * @see ::mbg_get_all_ptp_cfg_info
+ * @see ::mbg_get_ptp_uc_master_cfg_limits
+ * @see ::mbg_get_all_ptp_uc_master_info
+ * @see ::mbg_set_ptp_uc_master_settings_idx
+ * @see ::mbg_get_ptp_state
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_ptp_unicast( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Read PTP/IEEE1588 status from a device.
+ * @brief Read PTP/IEEE1588 status from a device.
The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PTP_STATE variable to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_ptp
- @see mbg_get_all_ptp_cfg_info
- @see mbg_get_ptp_cfg_info
- @see mbg_set_ptp_cfg_settings
- @see mbg_dev_has_ptp_unicast
+ * @see ::mbg_dev_has_ptp
+ * @see ::mbg_get_all_ptp_cfg_info
+ * @see ::mbg_get_ptp_cfg_info
+ * @see ::mbg_set_ptp_cfg_settings
+ * @see ::mbg_dev_has_ptp_unicast
*/
_MBG_API_ATTR int _MBG_API mbg_get_ptp_state( MBG_DEV_HANDLE dh, PTP_STATE *p ) ;
/**
- @brief Read PTP/IEEE1588 config info and current settings from a device.
+ * @brief Read PTP/IEEE1588 config info and current settings from a device.
The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PTP_CFG_INFO variable to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_ptp
- @see mbg_get_all_ptp_cfg_info
- @see mbg_get_ptp_state
- @see mbg_set_ptp_cfg_settings
- @see mbg_dev_has_ptp_unicast
+ * @see ::mbg_dev_has_ptp
+ * @see ::mbg_get_all_ptp_cfg_info
+ * @see ::mbg_get_ptp_state
+ * @see ::mbg_set_ptp_cfg_settings
+ * @see ::mbg_dev_has_ptp_unicast
*/
_MBG_API_ATTR int _MBG_API mbg_get_ptp_cfg_info( MBG_DEV_HANDLE dh, PTP_CFG_INFO *p ) ;
/**
- @brief Write PTP/IEEE1588 configuration settings to a device.
+ * @brief Write PTP/IEEE1588 configuration settings to a device.
The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p ::PTP_CFG_SETTINGS structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_ptp
- @see mbg_get_all_ptp_cfg_info
- @see mbg_get_ptp_state
- @see mbg_get_ptp_cfg_info
- @see mbg_dev_has_ptp_unicast
+ * @see ::mbg_dev_has_ptp
+ * @see ::mbg_get_all_ptp_cfg_info
+ * @see ::mbg_get_ptp_state
+ * @see ::mbg_get_ptp_cfg_info
+ * @see ::mbg_dev_has_ptp_unicast
*/
_MBG_API_ATTR int _MBG_API mbg_set_ptp_cfg_settings( MBG_DEV_HANDLE dh, const PTP_CFG_SETTINGS *p ) ;
/**
- @brief Read PTP/IEEE1588 unicast master configuration limits from a device.
+ * @brief Read PTP/IEEE1588 unicast master configuration limits from a device.
The macro _pcps_has_ri_ptp_unicast() or the API call mbg_dev_has_ptp_unicast()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::PTP_UC_MASTER_CFG_LIMITS variable to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_ptp_unicast
- @see mbg_get_all_ptp_cfg_info
- @see mbg_get_all_ptp_uc_master_info
- @see mbg_set_ptp_uc_master_settings_idx
- @see mbg_get_ptp_state
+ * @see ::mbg_dev_has_ptp_unicast
+ * @see ::mbg_get_all_ptp_cfg_info
+ * @see ::mbg_get_all_ptp_uc_master_info
+ * @see ::mbg_set_ptp_uc_master_settings_idx
+ * @see ::mbg_get_ptp_state
*/
_MBG_API_ATTR int _MBG_API mbg_get_ptp_uc_master_cfg_limits( MBG_DEV_HANDLE dh, PTP_UC_MASTER_CFG_LIMITS *p ) ;
/**
- @brief Read PTP Unicast master settings and configuration options.
+ * @brief Read PTP Unicast master settings and configuration options.
The function mbg_setup_receiver_info() must have been called before,
and the returned ::RECEIVER_INFO structure passed to this function.
@@ -3078,41 +3065,41 @@ extern "C" {
The array passed to this function to receive the returned data
must be able to hold at least ::RECEIVER_INFO::n_prg_out elements.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param pii Pointer to a an array of ::PTP_UC_MASTER_INFO_IDX structures to be filled up
@param p_umsl Pointer to a ::PTP_UC_MASTER_CFG_LIMITS structure returned by mbg_get_ptp_uc_master_cfg_limits()
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_ptp_unicast
- @see mbg_get_all_ptp_cfg_info
- @see mbg_get_ptp_uc_master_cfg_limits
- @see mbg_set_ptp_uc_master_settings_idx
- @see mbg_get_ptp_state
+ * @see ::mbg_dev_has_ptp_unicast
+ * @see ::mbg_get_all_ptp_cfg_info
+ * @see ::mbg_get_ptp_uc_master_cfg_limits
+ * @see ::mbg_set_ptp_uc_master_settings_idx
+ * @see ::mbg_get_ptp_state
*/
_MBG_API_ATTR int _MBG_API mbg_get_all_ptp_uc_master_info( MBG_DEV_HANDLE dh, PTP_UC_MASTER_INFO_IDX pii[], const PTP_UC_MASTER_CFG_LIMITS *p_umsl ) ;
/**
- @brief Write PTP/IEEE1588 unicast configuration settings to a device.
+ * @brief Write PTP/IEEE1588 unicast configuration settings to a device.
The macro _pcps_has_ri_ptp_unicast() or the API call mbg_dev_has_ptp_unicast()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device.
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p ::PTP_UC_MASTER_SETTINGS_IDX structure to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_ptp_unicast
- @see mbg_get_all_ptp_cfg_info
- @see mbg_get_ptp_uc_master_cfg_limits
- @see mbg_get_all_ptp_uc_master_info
- @see mbg_get_ptp_state
+ * @see ::mbg_dev_has_ptp_unicast
+ * @see ::mbg_get_all_ptp_cfg_info
+ * @see ::mbg_get_ptp_uc_master_cfg_limits
+ * @see ::mbg_get_all_ptp_uc_master_info
+ * @see ::mbg_get_ptp_state
*/
_MBG_API_ATTR int _MBG_API mbg_set_ptp_uc_master_settings_idx( MBG_DEV_HANDLE dh, const PTP_UC_MASTER_SETTINGS_IDX *p ) ;
/**
- @brief Read both system time and associated device time from the kernel driver.
+ * @brief Read both system time and associated device time from the kernel driver.
The kernel driver reads the current system time plus a HR time structure
from a card immediately after each other. The returned info structure also
@@ -3128,95 +3115,95 @@ extern "C" {
_pcps_has_hr_time() or the API call mbg_dev_has_hr_time() can be
used to check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::MBG_TIME_INFO_HRT variable to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_hr_time()
- @see mbg_get_time_info_tstamp()
- */
+ * @see ::mbg_dev_has_hr_time
+ * @see ::mbg_get_time_info_tstamp
+ */
_MBG_API_ATTR int _MBG_API mbg_get_time_info_hrt( MBG_DEV_HANDLE dh, MBG_TIME_INFO_HRT *p ) ;
/**
- @brief Read both system time and associated device timestamp from the kernel driver.
+ * @brief Read both system time and associated device timestamp from the kernel driver.
This call is similar to mbg_get_time_info_hrt() except that a
mbg_get_fast_hr_timestamp_cycles() call is made internally, so the macro
_pcps_has_fast_hr_timestamp() or the API call mbg_dev_has_fast_hr_timestamp()
can be used to check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::MBG_TIME_INFO_TSTAMP variable to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_fast_hr_timestamp()
- @see mbg_get_time_info_hrt()
- */
+ * @see ::mbg_dev_has_fast_hr_timestamp
+ * @see ::mbg_get_time_info_hrt
+ */
_MBG_API_ATTR int _MBG_API mbg_get_time_info_tstamp( MBG_DEV_HANDLE dh, MBG_TIME_INFO_TSTAMP *p ) ;
/**
- @brief Check if a device supports demodulation of the DCF77 PZF code.
+ * @brief Check if a device supports demodulation of the DCF77 PZF code.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_corr_info()
- @see mbg_dev_has_tr_distance()
+ * @see ::mbg_dev_has_corr_info
+ * @see ::mbg_dev_has_tr_distance
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_pzf( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports reading correlation info.
+ * @brief Check if a device supports reading correlation info.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_pzf()
- @see mbg_get_corr_info()
+ * @see ::mbg_dev_has_pzf
+ * @see ::mbg_get_corr_info
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_corr_info( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Check if a device supports configurable distance from transmitter.
+ * @brief Check if a device supports configurable distance from transmitter.
The distance from transmitter parameter is used to compensate
the RF propagation delay, mostly with long wave receivers.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_pzf()
- @see mbg_get_tr_distance()
- @see mbg_set_tr_distance()
+ * @see ::mbg_dev_has_pzf
+ * @see ::mbg_get_tr_distance
+ * @see ::mbg_set_tr_distance
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_tr_distance( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Read PZF correlation info from a device.
+ * @brief Read PZF correlation info from a device.
The macro _pcps_has_corr_info() or the API call mbg_dev_has_corr_info()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::CORR_INFO variable to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_pzf()
- @see mbg_dev_has_corr_info()
+ * @see ::mbg_dev_has_pzf
+ * @see ::mbg_dev_has_corr_info
*/
_MBG_API_ATTR int _MBG_API mbg_get_corr_info( MBG_DEV_HANDLE dh, CORR_INFO *p ) ;
/**
- @brief Read configurable "distance from transmitter" parameter from a device.
+ * @brief Read configurable "distance from transmitter" parameter from a device.
The distance from transmitter parameter is used to compensate
the RF propagation delay, mostly with long wave receivers.
@@ -3224,19 +3211,19 @@ extern "C" {
The macro _pcps_has_tr_distance() or the API call mbg_dev_has_tr_distance()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::TR_DISTANCE variable to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_pzf()
- @see mbg_dev_has_tr_distance()
- @see mbg_set_tr_distance()
- */
+ * @see ::mbg_dev_has_pzf
+ * @see ::mbg_dev_has_tr_distance
+ * @see ::mbg_set_tr_distance
+ */
_MBG_API_ATTR int _MBG_API mbg_get_tr_distance( MBG_DEV_HANDLE dh, TR_DISTANCE *p ) ;
/**
- @brief Write configurable "distance from transmitter" parameter to a device.
+ * @brief Write configurable "distance from transmitter" parameter to a device.
The distance from transmitter parameter is used to compensate
the RF propagation delay, mostly with long wave receivers.
@@ -3244,31 +3231,31 @@ extern "C" {
The macro _pcps_has_tr_distance() or the API call mbg_dev_has_tr_distance()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::TR_DISTANCE variable to be written
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_pzf()
- @see mbg_dev_has_tr_distance()
- @see mbg_get_tr_distance()
+ * @see ::mbg_dev_has_pzf
+ * @see ::mbg_dev_has_tr_distance
+ * @see ::mbg_get_tr_distance
*/
_MBG_API_ATTR int _MBG_API mbg_set_tr_distance( MBG_DEV_HANDLE dh, const TR_DISTANCE *p ) ;
/**
- @brief Check if a device provides a debug status word to be read.
+ * @brief Check if a device provides a debug status word to be read.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_debug_status()
+ * @see ::mbg_get_debug_status
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_debug_status( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Read a debug status word from a device.
+ * @brief Read a debug status word from a device.
This is mainly supported by IRIG timecode receiver cards, and the status
word is intended to provide more detailed information why a card might not
@@ -3279,49 +3266,49 @@ extern "C" {
The macro _pcps_has_debug_status() or the API call mbg_dev_has_debug_status()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::MBG_DEBUG_STATUS variable to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_debug_status()
+ * @see ::mbg_dev_has_debug_status
*/
_MBG_API_ATTR int _MBG_API mbg_get_debug_status( MBG_DEV_HANDLE dh, MBG_DEBUG_STATUS *p ) ;
/**
- @brief Check if a device provides an on-board event log.
+ * @brief Check if a device provides an on-board event log.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to an int which is set 0 or != 0 unless the call fails.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_clr_evt_log()
- @see mbg_get_num_evt_log_entries()
- @see mbg_get_first_evt_log_entry()
- @see mbg_get_next_evt_log_entry()
+ * @see ::mbg_clr_evt_log
+ * @see ::mbg_get_num_evt_log_entries
+ * @see ::mbg_get_first_evt_log_entry
+ * @see ::mbg_get_next_evt_log_entry
*/
_MBG_API_ATTR int _MBG_API mbg_dev_has_evt_log( MBG_DEV_HANDLE dh, int *p ) ;
/**
- @brief Clear the card's on-board event log.
+ * @brief Clear the card's on-board event log.
The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_evt_log()
- @see mbg_get_num_evt_log_entries()
- @see mbg_get_first_evt_log_entry()
- @see mbg_get_next_evt_log_entry()
+ * @see ::mbg_dev_has_evt_log
+ * @see ::mbg_get_num_evt_log_entries
+ * @see ::mbg_get_first_evt_log_entry
+ * @see ::mbg_get_next_evt_log_entry
*/
_MBG_API_ATTR int _MBG_API mbg_clr_evt_log( MBG_DEV_HANDLE dh ) ;
/**
- @brief Read details about a device's on-board event log buffer.
+ * @brief Read details about a device's on-board event log buffer.
The returned ::MBG_NUM_EVT_LOG_ENTRIES structure tells how many event log
entries which can be saved on the board, and how many entries actually
@@ -3330,82 +3317,358 @@ extern "C" {
The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log()
check whether this call is supported by a device.
- @param dh Valid handle to a Meinberg device
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
@param *p Pointer to a ::MBG_NUM_EVT_LOG_ENTRIES variable to be filled up
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_dev_has_evt_log()
- @see mbg_clr_evt_log()
- @see mbg_get_first_evt_log_entry()
- @see mbg_get_next_evt_log_entry()
+ * @see ::mbg_dev_has_evt_log
+ * @see ::mbg_clr_evt_log
+ * @see ::mbg_get_first_evt_log_entry
+ * @see ::mbg_get_next_evt_log_entry
*/
_MBG_API_ATTR int _MBG_API mbg_get_num_evt_log_entries( MBG_DEV_HANDLE dh, MBG_NUM_EVT_LOG_ENTRIES *p ) ;
/**
- @brief Read the first (oldest) event log entry from a device.
+ * @brief Read the first (oldest) event log entry from a device.
+ *
+ * @note Subsequent reads should be made using mbg_get_next_evt_log_entry().
+ *
+ * The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log()
+ * check whether this call is supported by a device.
+ *
+ * If no (more) event log entry is available on the device then
+ * the returned MBG_EVT_LOG_ENTRY::code is MBG_EVT_ID_NONE.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param *p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_evt_log
+ * @see ::mbg_clr_evt_log
+ * @see ::mbg_get_num_evt_log_entries
+ * @see ::mbg_get_next_evt_log_entry
+ */
+ _MBG_API_ATTR int _MBG_API mbg_get_first_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) ;
- @note Subsequent reads should be made using mbg_get_next_evt_log_entry().
+ /**
+ * @brief Read the next event log entry from a device.
+ *
+ * @note The first read should be made using mbg_get_first_evt_log_entry()
+ * to set the on-board read index to the oldest entry.
+ *
+ * The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log()
+ * check whether this call is supported by a device.
+ *
+ * If no (more) event log entry is available on the device then
+ * the returned MBG_EVT_LOG_ENTRY::code is MBG_EVT_ID_NONE.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param *p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_evt_log
+ * @see ::mbg_clr_evt_log
+ * @see ::mbg_get_num_evt_log_entries
+ * @see ::mbg_get_first_evt_log_entry
+ */
+ _MBG_API_ATTR int _MBG_API mbg_get_next_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) ;
- The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log()
- check whether this call is supported by a device.
+ /**
+ * @brief Check if a device supports GNSS configuration.
+ *
+ * This is usually the case if a device supports reception of
+ * several different satellite systems, e.g. GPS, Glonass, etc.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param *p Pointer to an int which is set 0 or != 0 unless the call fails.
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_get_gps_gnss_mode_info
+ * @see ::mbg_set_gps_gnss_mode_settings
+ * @see ::mbg_get_gps_all_gnss_sat_info
+ */
+ _MBG_API_ATTR int _MBG_API mbg_dev_is_gnss( MBG_DEV_HANDLE dh, int *p ) ;
- If no (more) event log entry is available on the device then
- the returned MBG_EVT_LOG_ENTRY::code is MBG_EVT_ID_NONE.
+ /**
+ * @brief Read the current GNSS mode info including current settings.
+ *
+ * The ::MBG_GNSS_MODE_INFO structure tells which GNSS systems are supported
+ * by a device, and also includes the settings currently in effect.
+ *
+ * The API call mbg_dev_is_gnss() can be used to check whether this call
+ * is supported by a device. See also the notes for mbg_dev_is_gnss().
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param *p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure to be filled up
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_set_gps_gnss_mode_settings
+ * @see ::mbg_get_gps_all_gnss_sat_info
+ * @see ::mbg_dev_is_gnss
+ */
+ _MBG_API_ATTR int _MBG_API mbg_get_gps_gnss_mode_info( MBG_DEV_HANDLE dh, MBG_GNSS_MODE_INFO *p_mi ) ;
+
+ /**
+ * @brief Write the GNSS mode configuration to a device.
+ *
+ * The ::MBG_GNSS_MODE_SETTINGS structure determines to configure the
+ * GNSS settings for a device, i.e. which satellite systems have to be used.
+ *
+ * The function mbg_get_gps_gnss_mode_info() should have been called before
+ * to determine which GNSS settings are supported by the device.
+ *
+ * The API call mbg_dev_is_gnss() can be used to check whether these API calls
+ * are supported by a device. See also the notes for mbg_dev_is_gnss().
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param *p_ms Pointer to a ::MBG_GNSS_MODE_SETTINGS structure to be written
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_get_gps_gnss_mode_info
+ * @see ::mbg_get_gps_all_gnss_sat_info
+ * @see ::mbg_dev_is_gnss
+ */
+ _MBG_API_ATTR int _MBG_API mbg_set_gps_gnss_mode_settings( MBG_DEV_HANDLE dh, const MBG_GNSS_MODE_SETTINGS *p_ms ) ;
- @param dh Valid handle to a Meinberg device
- @param *p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up
+ /**
+ * @brief Read a ::GNSS_SAT_INFO_IDX array of satellite status information.
+ *
+ * The function mbg_get_gps_gnss_mode_info() must have been called before,
+ * and the returned ::MBG_GNSS_MODE_INFO structure passed to this function.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param gsii Pointer to a an array of satellite info structures to be filled up
+ * @param *p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure returned by mbg_get_gps_gnss_mode_info()
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_get_gps_gnss_mode_info
+ * @see ::mbg_set_gps_gnss_mode_settings
+ * @see ::mbg_dev_is_gnss
+ */
+ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gnss_sat_info( MBG_DEV_HANDLE dh, GNSS_SAT_INFO_IDX gsii[], const MBG_GNSS_MODE_INFO *p_mi ) ;
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ /**
+ * @brief Check if a device provides GPIO signal inputs and/or outputs
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param[out] *p Pointer to an int which is set 0 or != 0 unless the call fails.
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_gpio
+ * @see ::mbg_get_gpio_cfg_limits
+ * @see ::mbg_get_gps_all_gpio_info
+ * @see ::mbg_set_gps_gpio_settings_idx
+ * @see ::mbg_get_gps_all_gpio_status
+ */
+ _MBG_API_ATTR int _MBG_API mbg_dev_has_gpio( MBG_DEV_HANDLE dh, int *p ) ;
- @see mbg_dev_has_evt_log()
- @see mbg_clr_evt_log()
- @see mbg_get_num_evt_log_entries()
- @see mbg_get_next_evt_log_entry()
- */
- _MBG_API_ATTR int _MBG_API mbg_get_first_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) ;
+ /**
+ * @brief Read common GPIO configuration limits
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device
+ * @param[out] p A ::MBG_GPIO_CFG_LIMITS structure to be filled up
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_gpio
+ * @see ::mbg_get_gpio_cfg_limits
+ * @see ::mbg_get_gps_all_gpio_info
+ * @see ::mbg_set_gps_gpio_settings_idx
+ * @see ::mbg_get_gps_all_gpio_status
+ */
+ _MBG_API_ATTR int _MBG_API mbg_get_gpio_cfg_limits( MBG_DEV_HANDLE dh, MBG_GPIO_CFG_LIMITS *p ) ;
/**
- @brief Read the next event log entry from a device.
+ * @brief Get all GPIO settings and capabilities
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device
+ * @param[out] gii An array of ::MBG_GPIO_STATUS_IDX structures to be filled up
+ * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_gpio
+ * @see ::mbg_get_gpio_cfg_limits
+ * @see ::mbg_get_gps_all_gpio_info
+ * @see ::mbg_set_gps_gpio_settings_idx
+ * @see ::mbg_get_gps_all_gpio_status
+ */
+ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gpio_info( MBG_DEV_HANDLE dh, MBG_GPIO_INFO_IDX gii[], const MBG_GPIO_CFG_LIMITS *p_gcl ) ;
- @note The first read should be made using mbg_get_first_evt_log_entry()
- to set the on-board read index to the oldest entry.
+ /**
+ * @brief Write the configuration for a single GPIO port to a device
+ *
+ * The ::MBG_GPIO_SETTINGS_IDX structure contains both the ::MBG_GPIO_SETTINGS
+ * and the port index value.
+ *
+ * The macro ::_pcps_has_ri_gpio or the API call ::mbg_dev_has_gpio
+ * check whether this call is supported by a device.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device
+ * @param[out] p Pointer to a ::MBG_GPIO_SETTINGS_IDX structure to be written
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_gpio
+ * @see ::mbg_get_gpio_cfg_limits
+ * @see ::mbg_get_gps_all_gpio_info
+ * @see ::mbg_set_gps_gpio_settings_idx
+ * @see ::mbg_get_gps_all_gpio_status
+ */
+ _MBG_API_ATTR int _MBG_API mbg_set_gps_gpio_settings_idx( MBG_DEV_HANDLE dh, const MBG_GPIO_SETTINGS_IDX *p ) ;
- The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log()
- check whether this call is supported by a device.
+ /**
+ * @brief Read the status of all GPIO signal ports
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device
+ * @param[out] gsi An array of ::MBG_GPIO_STATUS_IDX structures to be filled up
+ * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_gpio
+ * @see ::mbg_get_gpio_cfg_limits
+ * @see ::mbg_get_gps_all_gpio_info
+ * @see ::mbg_set_gps_gpio_settings_idx
+ */
+ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gpio_status( MBG_DEV_HANDLE dh, MBG_GPIO_STATUS_IDX gsi[], const MBG_GPIO_CFG_LIMITS *p_gcl ) ;
- If no (more) event log entry is available on the device then
- the returned MBG_EVT_LOG_ENTRY::code is MBG_EVT_ID_NONE.
+ /**
+ * @brief Check if a device provides extended multi ref (XMR) inputs
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param *p Pointer to an int which is set 0 or != 0 unless the call fails.
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_get_xmr_instances
+ * @see ::mbg_get_gps_all_xmr_status
+ * @see ::mbg_get_gps_all_xmr_info
+ * @see ::mbg_set_gps_xmr_settings_idx
+ * @see ::mbg_get_xmr_holdover_status
+ */
+ _MBG_API_ATTR int _MBG_API mbg_dev_has_xmr( MBG_DEV_HANDLE dh, int *p ) ;
- @param dh Valid handle to a Meinberg device
- @param *p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up
+ /**
+ * @brief
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param[out] *p A ::XMULTI_REF_INSTANCES structure to be filled up
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_xmr
+ * @see ::mbg_get_gps_all_xmr_status
+ * @see ::mbg_get_gps_all_xmr_info
+ * @see ::mbg_set_gps_xmr_settings_idx
+ * @see ::mbg_get_xmr_holdover_status
+ */
+ _MBG_API_ATTR int _MBG_API mbg_get_xmr_instances( MBG_DEV_HANDLE dh, XMULTI_REF_INSTANCES *p ) ;
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ /**
+ * @brief Read the status of all XMR sources
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device
+ * @param[out] xmrsi An array of ::XMULTI_REF_STATUS_IDX structures to be filled up
+ * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_xmr
+ * @see ::mbg_get_xmr_instances
+ * @see ::mbg_get_gps_all_xmr_info
+ * @see ::mbg_set_gps_xmr_settings_idx
+ * @see ::mbg_get_xmr_holdover_status
+ */
+ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_xmr_status( MBG_DEV_HANDLE dh, XMULTI_REF_STATUS_IDX xmrsi[], const XMULTI_REF_INSTANCES *p_xmri ) ;
- @see mbg_dev_has_evt_log()
- @see mbg_clr_evt_log()
- @see mbg_get_num_evt_log_entries()
- @see mbg_get_first_evt_log_entry()
- */
- _MBG_API_ATTR int _MBG_API mbg_get_next_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) ;
+ /**
+ * @brief Read all XMR settings and capabilities
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device
+ * @param[out] xmrii An array of ::XMULTI_REF_INFO_IDX structures to be filled up
+ * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_xmr
+ * @see ::mbg_get_xmr_instances
+ * @see ::mbg_get_gps_all_xmr_status
+ * @see ::mbg_set_gps_xmr_settings_idx
+ * @see ::mbg_get_xmr_holdover_status
+ */
+ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_xmr_info( MBG_DEV_HANDLE dh, XMULTI_REF_INFO_IDX xmrii[], const XMULTI_REF_INSTANCES *p_xmri ) ;
+
+ /**
+ * @brief Write a single XMR setting to a device
+ *
+ * The ::XMULTI_REF_SETTINGS_IDX structure contains both the ::XMULTI_REF_SETTINGS
+ * and the index value.
+ *
+ * The macro ::_pcps_has_ri_xmr or the API call ::mbg_dev_has_xmr
+ * check whether this call is supported by a device.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param *p Pointer to a ::XMULTI_REF_SETTINGS_IDX structure to be written
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_xmr
+ * @see ::mbg_get_xmr_instances
+ * @see ::mbg_get_gps_all_xmr_status
+ * @see ::mbg_get_gps_all_xmr_info
+ * @see ::mbg_get_xmr_holdover_status
+ */
+ _MBG_API_ATTR int _MBG_API mbg_set_gps_xmr_settings_idx( MBG_DEV_HANDLE dh, const XMULTI_REF_SETTINGS_IDX *p ) ;
+
+ /**
+ * @brief Read the current XMR holdover interval from a device
+ *
+ * Read a ::SYNTH structure containing the configuration of an optional
+ * on-board programmable frequency synthesizer.
+ *
+ * The macro ::_pcps_has_ri_xmr or the API call ::mbg_dev_has_xmr
+ * check whether this call is supported by a device.
+ *
+ * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
+ * @param *p Pointer to a ::XMR_HOLDOVER_INTV structure to be filled up
+ * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before
+ *
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
+ *
+ * @see ::mbg_dev_has_xmr
+ * @see ::mbg_get_xmr_instances
+ * @see ::mbg_get_gps_all_xmr_status
+ * @see ::mbg_get_gps_all_xmr_info
+ * @see ::mbg_set_gps_xmr_settings_idx
+ */
+ _MBG_API_ATTR int _MBG_API mbg_get_xmr_holdover_status( MBG_DEV_HANDLE dh, XMR_HOLDOVER_STATUS *p, const XMULTI_REF_INSTANCES *p_xmri ) ;
/**
- @brief Read the CPU affinity of a process.
+ * @brief Read the CPU affinity of a process.
This means on which of the available CPUs or CPU cores the process can be executed.
@param pid The process ID.
@param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs.
- @return ::MBG_SUCCESS or error code returned by the system call.
+ * @return ::MBG_SUCCESS or error code returned by the system call.
- @see mbg_set_process_affinity()
- @see mbg_set_current_process_affinity_to_cpu()
+ * @see ::mbg_set_process_affinity
+ * @see ::mbg_set_current_process_affinity_to_cpu
*/
_MBG_API_ATTR int _MBG_API mbg_get_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p ) ;
/**
- @brief Set the CPU affinity of a process.
+ * @brief Set the CPU affinity of a process.
This determines on which of the available CPUs
the process is allowed to be executed.
@@ -3413,29 +3676,29 @@ extern "C" {
@param pid The process ID.
@param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs.
- @return ::MBG_SUCCESS or error code returned by the system call.
+ * @return ::MBG_SUCCESS or error code returned by the system call.
- @see mbg_get_process_affinity()
- @see mbg_set_current_process_affinity_to_cpu()
+ * @see ::mbg_get_process_affinity
+ * @see ::mbg_set_current_process_affinity_to_cpu
*/
_MBG_API_ATTR int _MBG_API mbg_set_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p ) ;
/**
- @brief Set the CPU affinity of a process for a single CPU only.
+ * @brief Set the CPU affinity of a process for a single CPU only.
This means the process may only be executed on that single CPU.
@param cpu_num The number of the CPU.
- @return ::MBG_SUCCESS or error code returned by the system call.
+ * @return ::MBG_SUCCESS or error code returned by the system call.
- @see mbg_get_process_affinity()
- @see mbg_set_process_affinity()
+ * @see ::mbg_get_process_affinity
+ * @see ::mbg_set_process_affinity
*/
_MBG_API_ATTR int _MBG_API mbg_set_current_process_affinity_to_cpu( int cpu_num ) ;
/**
- @brief Create a new execution thread for the current process.
+ * @brief Create a new execution thread for the current process.
This function is only implemented for targets which support threads.
@@ -3443,32 +3706,32 @@ extern "C" {
@param fnc The name of the thread function to be started.
@param arg A generic argument passed to the thread function.
- @return ::MBG_SUCCESS or error code returned by the system call.
+ * @return ::MBG_SUCCESS or error code returned by the system call.
- @see mbg_thread_stop()
- @see mbg_thread_sleep_interruptible()
- @see mbg_thread_set_affinity()
+ * @see ::mbg_thread_stop
+ * @see ::mbg_thread_sleep_interruptible
+ * @see ::mbg_thread_set_affinity
*/
- _MBG_API_ATTR int _MBG_API mbg_thread_create( MBG_THREAD_INFO *p_ti, MBG_THREAD_FNC_RET_VAL (MBG_THREAD_FNC_ATTR *fnc)(void *), void *arg ) ;
+ _MBG_API_ATTR int _MBG_API mbg_thread_create( MBG_THREAD_INFO *p_ti, MBG_THREAD_FNC fnc, void *arg ) ;
/**
- @brief Stop a thread which has been created by mbg_thread_create().
+ * @brief Stop a thread which has been created by mbg_thread_create().
Wait until the thread has finished and release all resources.
This function is only implemented for targets which support threads.
@param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread.
- @return ::MBG_SUCCESS or error code returned by the system call.
+ * @return ::MBG_SUCCESS or error code returned by the system call.
- @see mbg_thread_create()
- @see mbg_thread_sleep_interruptible()
- @see mbg_thread_set_affinity()
+ * @see ::mbg_thread_create
+ * @see ::mbg_thread_sleep_interruptible
+ * @see ::mbg_thread_set_affinity
*/
_MBG_API_ATTR int _MBG_API mbg_thread_stop( MBG_THREAD_INFO *p_ti ) ;
/**
- @brief Let the current thread sleep for a certain interval.
+ * @brief Let the current thread sleep for a certain interval.
The sleep is interrupted if a signal is received indicating
the thread should terminate.
@@ -3477,18 +3740,18 @@ extern "C" {
@param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread.
@param sleep_ms The number of milliseconds to sleep
- @return 0 if the sleep interval has expired normally
+ * @return 0 if the sleep interval has expired normally
1 if a signal to terminate has been received
<0 if an error has occurred
- @see mbg_thread_create()
- @see mbg_thread_stop()
- @see mbg_thread_set_affinity()
+ * @see ::mbg_thread_create
+ * @see ::mbg_thread_stop
+ * @see ::mbg_thread_set_affinity
*/
_MBG_API_ATTR int _MBG_API mbg_thread_sleep_interruptible( MBG_THREAD_INFO *p_ti, ulong sleep_ms ) ;
/**
- @brief Set the CPU affinity of a single thread.
+ * @brief Set the CPU affinity of a single thread.
This determines on which of the available CPUs the thread
is allowed to be executed.
@@ -3498,16 +3761,16 @@ extern "C" {
@param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread.
@param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs.
- @return ::MBG_SUCCESS or error code returned by the system call.
+ * @return ::MBG_SUCCESS or error code returned by the system call.
- @see mbg_thread_create()
- @see mbg_thread_stop()
- @see mbg_thread_sleep_interruptible()
+ * @see ::mbg_thread_create
+ * @see ::mbg_thread_stop
+ * @see ::mbg_thread_sleep_interruptible
*/
_MBG_API_ATTR int _MBG_API mbg_thread_set_affinity( MBG_THREAD_INFO *p_ti, MBG_CPU_SET *p ) ;
/**
- @brief Set up a ::MBG_POLL_THREAD_INFO structure and start a new thread.
+ * @brief Set up a ::MBG_POLL_THREAD_INFO structure and start a new thread.
The new thread runs the mbg_xhrt_poll_thread_fnc() function.
@@ -3519,37 +3782,35 @@ extern "C" {
@param sleep_ms the sleep interval for the poll thread function in ms.
If this parameter is 0 then the default sleep interval is used.
- @return ::MBG_SUCCESS on success,
+ * @return ::MBG_SUCCESS on success,
::MBG_ERR_NOT_SUPP_BY_DEV if the device to poll does not support HR time
else the result of mbg_thread_create()
- @see mbg_xhrt_poll_thread_fnc()
- @see mbg_xhrt_poll_thread_stop()
- @see mbg_get_xhrt_time_as_pcps_hr_time()
- @see mbg_get_xhrt_time_as_filetime()
- @see mbg_get_xhrt_cycles_frequency()
+ * @see ::mbg_xhrt_poll_thread_stop
+ * @see ::mbg_get_xhrt_time_as_pcps_hr_time
+ * @see ::mbg_get_xhrt_time_as_filetime
+ * @see ::mbg_get_xhrt_cycles_frequency
*/
_MBG_API_ATTR int _MBG_API mbg_xhrt_poll_thread_create( MBG_POLL_THREAD_INFO *p_pti, MBG_DEV_HANDLE dh, MBG_PC_CYCLES_FREQUENCY freq_hz, int sleep_ms ) ;
/**
- @brief Stop a polling thread started by mbg_xhrt_poll_thread_create().
+ * @brief Stop a polling thread started by mbg_xhrt_poll_thread_create().
This call also releases all associated resources.
@param *p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure.
- @return the result of mbg_thread_stop()
+ * @return the result of mbg_thread_stop()
- @see mbg_xhrt_poll_thread_fnc()
- @see mbg_xhrt_poll_thread_create()
- @see mbg_get_xhrt_time_as_pcps_hr_time()
- @see mbg_get_xhrt_time_as_filetime()
- @see mbg_get_xhrt_cycles_frequency()
+ * @see ::mbg_xhrt_poll_thread_create
+ * @see ::mbg_get_xhrt_time_as_pcps_hr_time
+ * @see ::mbg_get_xhrt_time_as_filetime
+ * @see ::mbg_get_xhrt_cycles_frequency
*/
_MBG_API_ATTR int _MBG_API mbg_xhrt_poll_thread_stop( MBG_POLL_THREAD_INFO *p_pti ) ;
/**
- @brief Retrieve an extrapolated time stamp in PCPS_HR_TIME format.
+ * @brief Retrieve an extrapolated time stamp in PCPS_HR_TIME format.
The time stamp is extrapolated using the system's current cycles counter value
and a time stamp plus associated cycles counter value saved by the polling thread.
@@ -3560,18 +3821,17 @@ extern "C" {
@param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread.
@param *p_hrt Pointer to a ::PCPS_HR_TIME structure to be filled up.
- @return MBG_SUCCESS or another return value from the polling thread's IOCTL call.
+ * @return MBG_SUCCESS or another return value from the polling thread's IOCTL call.
- @see mbg_xhrt_poll_thread_fnc()
- @see mbg_xhrt_poll_thread_create()
- @see mbg_xhrt_poll_thread_stop()
- @see mbg_get_xhrt_time_as_filetime()
- @see mbg_get_xhrt_cycles_frequency()
+ * @see ::mbg_xhrt_poll_thread_create
+ * @see ::mbg_xhrt_poll_thread_stop
+ * @see ::mbg_get_xhrt_time_as_filetime
+ * @see ::mbg_get_xhrt_cycles_frequency
*/
_MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_pcps_hr_time( MBG_XHRT_INFO *p, PCPS_HR_TIME *p_hrt ) ;
/**
- @brief Retrieve an extrapolated time stamp in FILETIME format.
+ * @brief Retrieve an extrapolated time stamp in FILETIME format.
The time stamp is extrapolated using the system's current cycles counter value
and a time stamp plus associated cycles counter value saved by the polling thread.
@@ -3581,20 +3841,19 @@ extern "C" {
implemented under Windows.
@param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread.
- @param *p_ft Pointer to a ::FILETIME structure to be filled up.
+ @param *p_ft Pointer to a FILETIME structure to be filled up.
- @return MBG_SUCCESS or another return value from the polling thread's IOCTL call.
+ * @return MBG_SUCCESS or another return value from the polling thread's IOCTL call.
- @see mbg_xhrt_poll_thread_fnc()
- @see mbg_xhrt_poll_thread_create()
- @see mbg_xhrt_poll_thread_stop()
- @see mbg_get_xhrt_time_as_pcps_hr_time()
- @see mbg_get_xhrt_cycles_frequency()
+ * @see ::mbg_xhrt_poll_thread_create
+ * @see ::mbg_xhrt_poll_thread_stop
+ * @see ::mbg_get_xhrt_time_as_pcps_hr_time
+ * @see ::mbg_get_xhrt_cycles_frequency
*/
_MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_filetime( MBG_XHRT_INFO *p, FILETIME *p_ft ) ;
/**
- @brief Retrieve the frequency of the system's cycles counter.
+ * @brief Retrieve the frequency of the system's cycles counter.
The frequency is determined by the device polling thread.
See mbg_xhrt_poll_thread_fnc() for details and limitations.
@@ -3603,27 +3862,26 @@ extern "C" {
@param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread.
@param *p_freq_hz Pointer to a ::MBG_PC_CYCLES_FREQUENCY variable in which the frequency is returned.
- @return a status code from the polling thread: MBG_SUCCESS or an IOCTL error code.
+ * @return a status code from the polling thread: MBG_SUCCESS or an IOCTL error code.
- @see mbg_xhrt_poll_thread_fnc()
- @see mbg_xhrt_poll_thread_create()
- @see mbg_xhrt_poll_thread_stop()
- @see mbg_get_xhrt_time_as_pcps_hr_time()
- @see mbg_get_xhrt_time_as_filetime()
+ * @see ::mbg_xhrt_poll_thread_create
+ * @see ::mbg_xhrt_poll_thread_stop
+ * @see ::mbg_get_xhrt_time_as_pcps_hr_time
+ * @see ::mbg_get_xhrt_time_as_filetime
*/
_MBG_API_ATTR int _MBG_API mbg_get_xhrt_cycles_frequency( MBG_XHRT_INFO *p, MBG_PC_CYCLES_FREQUENCY *p_freq_hz ) ;
/**
- @brief Retrieve the default system's cycles counter frequency from the kernel driver.
+ * @brief Retrieve the default system's cycles counter frequency from the kernel driver.
This API call can be used on systems which don't provide this information in user space.
@param dh handle of the device to which the IOCTL call is sent.
@param *p Pointer of a ::MBG_PC_CYCLES_FREQUENCY variable to be filled up.
- @return ::MBG_SUCCESS or error code returned by device I/O control function.
+ * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES
- @see mbg_get_default_cycles_frequency()
+ * @see ::mbg_get_default_cycles_frequency
*/
_MBG_API_ATTR int _MBG_API mbg_get_default_cycles_frequency_from_dev( MBG_DEV_HANDLE dh, MBG_PC_CYCLES_FREQUENCY *p ) ;
@@ -3636,7 +3894,7 @@ extern "C" {
@return the default cycles counter frequency in Hz, or 0 if the value is not available.
- @see mbg_get_default_cycles_frequency_from_dev()
+ * @see ::mbg_get_default_cycles_frequency_from_dev
*/
_MBG_API_ATTR MBG_PC_CYCLES_FREQUENCY _MBG_API mbg_get_default_cycles_frequency( void ) ;
@@ -3671,7 +3929,7 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code,
// mismatch errors.
// do not report a USB device timeout error
- if ( rc != _mbg_err_to_os( MBG_ERR_USB_ACCESS ) )
+ if ( rc != MBG_ERR_USB_ACCESS )
mbgsvctl_log_mbgdevio_error( ioctl_code, rc );
#endif
@@ -3685,7 +3943,7 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code,
#define _do_mbg_ioctl( _dh, _ioctl, _p, _in_sz, _out_sz ) \
do_mbg_ioctl( _dh, _ioctl, (LPVOID) _p, _in_sz, (LPVOID) _p, _out_sz )
-#elif defined( MBG_TGT_UNIX )
+#elif defined( MBG_HAS_UNIX_IOCTL )
#define _do_mbg_ioctl( _dh, _ioctl, _p, _in_sz, _out_sz ) \
ioctl( _dh, _ioctl, _p )
@@ -3697,21 +3955,24 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code,
// The code below depends on whether the target device is accessed via
// IOCTLs to a device driver, or the hardware is accessed directly.
-#if defined( _MBGIOCTL_H ) // using IOCTL to access device driver
+#if defined( MBG_USE_KERNEL_DRIVER ) // using IOCTL to access device driver
/**
@brief Send a generic IOCTL command to the driver.
- @param dh Valid handle to a Meinberg device
- @param info Additional information for the kernel driver depending on
- the IOCTL code, i.e. the low level function to be called: <br>
- one of the PCPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}<br>
- one of the PC_GPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}_GPS<br>
- one of the PCPS_GEN_IO_... enumeration codes with IOCTL_PCPS_GENERIC_IO
- @param ioctl One of the IOCTL_GENERIC_... codes telling the kernel driver
- which low level function to use, e.g. normal read or write,
- large (GPS) data read or write, or generic I/O.
- @param *p Pointer to an int which is set 0 or != 0 unless the call fails.
+ @param dh Valid handle to a Meinberg device
+ @param info Additional information for the kernel driver depending on
+ the IOCTL code, i.e. the low level function to be called: <br>
+ one of the PCPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}<br>
+ one of the PC_GPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}_GPS<br>
+ one of the PCPS_GEN_IO_... enumeration codes with IOCTL_PCPS_GENERIC_IO
+ @param ioctl_code One of the IOCTL_GENERIC_... codes telling the kernel driver
+ which low level function to use, e.g. normal read or write,
+ large (GPS) data read or write, or generic I/O.
+ @param in_p Pointer to an input buffer passed to the driver, can be NULL
+ @param in_sz Size of the input buffer, can be 0 if no buffer is used
+ @param out_p Pointer to an output buffer passed to the driver, can be NULL
+ @param out_sz Size of the output buffer, can be 0 if no buffer is used
@return ::MBG_SUCCESS or error code returned by device I/O control function.
*/
@@ -3750,7 +4011,7 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code,
p_buff = (IOCTL_GENERIC_BUFFER *) malloc( buff_size );
if ( p_buff == NULL )
- return _mbg_err_to_os( MBG_ERR_NO_MEM );
+ return MBG_ERR_NO_MEM;
p_buff->ctl.info = info;
p_buff->ctl.data_size_in = in_sz;
@@ -3797,8 +4058,10 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code,
#define _mbgdevio_write_cmd( _dh, _cmd, _ioctl ) \
_do_mbgdevio_write( _dh, _cmd, _ioctl, NULL, 0 )
+ #define _mbgdevio_read_gps _do_mbgdevio_read
#define _mbgdevio_read_gps_var _mbgdevio_read_var
+ #define _mbgdevio_write_gps _do_mbgdevio_write
#define _mbgdevio_write_gps_var _mbgdevio_write_var
@@ -3820,10 +4083,10 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code,
#else // accessing hardware device directly
- #define _mbgdevio_chk_cond( _cond ) \
- { \
- if ( !(_cond) ) \
- return _mbg_err_to_os( MBG_ERR_NOT_SUPP_BY_DEV ); \
+ #define _mbgdevio_chk_cond( _cond ) \
+ { \
+ if ( !(_cond) ) \
+ return MBG_ERR_NOT_SUPP_BY_DEV; \
}
#define _mbgdevio_read( _dh, _cmd, _ioctl, _p, _sz ) \
diff --git a/c/mbglib/include/mbgerror.h b/c/mbglib/include/mbgerror.h
index 4f1bb22..10d0aa6 100644
--- a/c/mbglib/include/mbgerror.h
+++ b/c/mbglib/include/mbgerror.h
@@ -1,8 +1,7 @@
/**************************************************************************
*
- * $Id: mbgerror.h 1.5 2011/03/31 10:56:17Z martin REL_M $
- * $Name: $
+ * $Id: mbgerror.h 1.7.1.1 2014/06/25 08:52:50Z martin TRASH $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -12,7 +11,18 @@
*
* -----------------------------------------------------------------------
* $Log: mbgerror.h $
- * Revision 1.5 2011/03/31 10:56:17Z martin
+ * Revision 1.7.1.1 2014/06/25 08:52:50Z martin
+ * Re-enabled some symbols which have been commented out..
+ * Revision 1.7 2014/05/27 13:32:47Z martin
+ * Defined additional common error codes which can be
+ * translated from OS specific codes.
+ * Function prototypes from new module mbgerror.c.
+ * Comments in doxygen style.
+ * Revision 1.6 2012/10/02 18:42:26Z martin
+ * New codes MBG_ERR_N_POUT_EXCEEDS_SUPP and
+ * MBG_ERR_N_UC_MSTR_EXCEEDS_SUPP.
+ * Modified comments for doxygen.
+ * Revision 1.5 2011/03/31 10:56:17 martin
* Added MBG_ERR_COPY_TO_USER and MBG_ERR_COPY_FROM_USER.
* Revision 1.4 2008/12/05 13:28:50 martin
* Added new code MBG_ERR_IRQ_UNSAFE.
@@ -46,73 +56,117 @@
/* Start of header body */
-/**
- @defgroup group_error_codes Error codes
-
- Error codes used with Meinberg devices and drivers.
- The codes will be translated into an OS dependent error code,
- when they are returned to the calling function.
-
- For Windows, these codes are made positive and or'ed with 0xE0000000 afterwards.
-
- Example: Code -19 (#MBG_ERR_GENERIC) will be converted to 0xE0000013 under Windows.
-
- @{
-*/
-
-// Attention!!
-// These error codes below must fit exactly to the corresponding codes that are evaluated in user space.
-// For Windows, they are located in messages.mc/.h in mbgsvctl.dll
-
-#define MBG_SUCCESS PCPS_SUCCESS /**< 0, no error */
-
-// The codes below are defined in pcpsdefs.h and returned by the firmware:
-#define MBG_ERR_STIME PCPS_ERR_STIME /**< -1, invalid date/time/status passed */
-#define MBG_ERR_CFG PCPS_ERR_CFG /**< -2, invalid parms with a PCPS_CFG_GROUP cmd */
-
-// Codes returned by the driver's low level functions:
-#define MBG_ERR_GENERIC -19 /**< Generic error */
-#define MBG_ERR_TIMEOUT -20 /**< Timeout accessing the board */
-#define MBG_ERR_FW_ID -21 /**< Invalid firmware ID */
-#define MBG_ERR_NBYTES -22 /**< The number of parameter bytes
- passed to the board did not match
- the number of bytes expected. */
-#define MBG_ERR_INV_TIME -23 /**< The device's time is not valid */
-#define MBG_ERR_FIFO -24 /**< The device's FIFO is empty, though
- it shouldn't be */
-#define MBG_ERR_NOT_READY -25 /**< Board is temporary unable to respond
- (during initialization after RESET) */
-#define MBG_ERR_INV_TYPE -26 /**< Board did not recognize data type */
-
-
-// Codes returned by the driver's high level functions:
-#define MBG_ERR_NO_MEM -27 /**< Failed to allocate memory */
-#define MBG_ERR_CLAIM_RSRC -28 /**< Failed to claim port or mem resource */
-#define MBG_ERR_DEV_NOT_SUPP -29 /**< Specified device type not supported by driver */
-#define MBG_ERR_INV_DEV_REQUEST -30 /**< IOCTL call not supported by driver */
-#define MBG_ERR_NOT_SUPP_BY_DEV -31 /**< Cmd or feature not supported by device */
-#define MBG_ERR_USB_ACCESS -32 /**< USB access failed */
-#define MBG_ERR_CYCLIC_TIMEOUT -33 /**< Cyclic event (IRQ, etc.) didn't occur */
-#define MBG_ERR_NOT_SUPP_ON_OS -34 /**< The function is not supported on this operating system */
-#define MBG_ERR_LIB_NOT_COMPATIBLE -35 /**< The installed version of the DLL/shared object is not
- compatible with version used to build the application */
-#define MBG_ERR_N_COM_EXCEEDS_SUPP -36 /**< The number of COM ports provided by the device
- exceeds the maximum supported by the driver */
-#define MBG_ERR_N_STR_EXCEEDS_SUPP -37 /**< The number of string formats supported by the device
- exceeds the maximum supported by the driver */
-#define MBG_ERR_IRQ_UNSAFE -38 /**< The enabled IRQs are unsafe with this firmware/ASIC version */
+#if !defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_KERNEL )
+ //##++++ Surprisingly we need this also for Windows
+ // in kernel mode. This should be fixed.
+ #define DWORD uint32_t // just to avoid compiler errors
+#endif
+
+
+/**
+ * @brief Error codes used with Meinberg devices and drivers
+ *
+ * Some of the codes have to match codes which are defined in pcpsdefs.h
+ * and returned by the firmware of bus-level devices.
+ *
+ * The codes will be translated into an OS dependent error code
+ * when returned to the calling function.
+ *
+ * For Windows, these codes are made positive and or'ed with 0xE0000000 afterwards.
+ *
+ * Example: Code -19 (#MBG_ERR_GENERIC) will be converted to 0xE0000013 under Windows.
+ *
+ * @note Attention:
+ * The error codes below must match exactly the corresponding codes that are evaluated in user space.
+ * For Windows, they are located in messages.mc/.h in mbgsvctl.dll
+ *
+ * @anchor MBG_RETURN_CODES @{ */
+
+#define MBG_SUCCESS 0 ///< no error, must match ::PCPS_SUCCESS
+
+ /** @anchor MBG_ERROR_CODES @{ */
+
+// Other codes which have to match codes defined in pcpsdefs.h returned by bus-level devices
+#define MBG_ERR_STIME -1 ///< invalid date/time/status passed, must match ::PCPS_ERR_STIME
+#define MBG_ERR_CFG -2 ///< invalid params with a configuration cmd, must match ::PCPS_ERR_CFG
+
+
+// Codes returned by low level functions of the bus-level device driver
+#define MBG_ERR_GENERIC -19 ///< generic error
+#define MBG_ERR_TIMEOUT -20 ///< timeout accessing the device
+#define MBG_ERR_FW_ID -21 ///< invalid firmware ID
+#define MBG_ERR_NBYTES -22 ///< the number of parameter bytes passed to the device did not
+ ///< match the number of bytes expected by the device
+#define MBG_ERR_INV_TIME -23 ///< the device doesn't have valid time
+#define MBG_ERR_FIFO -24 ///< the data FIFO of a bus-level device is empty, though it shouldn't be
+#define MBG_ERR_NOT_READY -25 ///< bus-level device is temp. unable to respond e.g. during init. after RESET
+#define MBG_ERR_INV_TYPE -26 ///< bus-level device didn't recognize data type
+
+
+// Codes returned by the high level API functions
+#define MBG_ERR_NO_MEM -27 ///< failed to allocate memory
+#define MBG_ERR_CLAIM_RSRC -28 ///< failed to claim port or mem resource
+#define MBG_ERR_DEV_NOT_SUPP -29 ///< specified device type not supported by driver
+#define MBG_ERR_INV_DEV_REQUEST -30 ///< IOCTL call not supported by driver
+#define MBG_ERR_NOT_SUPP_BY_DEV -31 ///< cmd or feature not supported by device
+#define MBG_ERR_USB_ACCESS -32 ///< USB access failed
+#define MBG_ERR_CYCLIC_TIMEOUT -33 ///< cyclic event (IRQ, etc.) didn't occur
+#define MBG_ERR_NOT_SUPP_ON_OS -34 ///< function is not supported under this operating system
+#define MBG_ERR_LIB_NOT_COMPATIBLE -35 ///< installed shared lib. version not compat. with version used at build time
+#define MBG_ERR_N_COM_EXCEEDS_SUPP -36 ///< num. COM ports of the device exceeds max. supp. by driver
+#define MBG_ERR_N_STR_EXCEEDS_SUPP -37 ///< num. string formats of the device exceeds max. supp. by driver
+#define MBG_ERR_IRQ_UNSAFE -38 ///< enabled IRQ of bus-level device is unsafe with this firmware/ASIC version
+#define MBG_ERR_N_POUT_EXCEEDS_SUPP -39 ///< num. prog. outputs of the device exceeds max. supp. by driver
// Legacy codes used with DOS TSRs only:
-#define MBG_ERR_INV_INTNO -40 /**< Invalid interrupt number */
-#define MBG_ERR_NO_DRIVER -41 /**< A driver could not be found */
-#define MBG_ERR_DRV_VERSION -42 /**< The driver is too old */
+#define MBG_ERR_INV_INTNO -40 ///< invalid interrupt number
+#define MBG_ERR_NO_DRIVER -41 ///< a driver could not be found
+#define MBG_ERR_DRV_VERSION -42 ///< the driver is too old
+
+
+#define MBG_ERR_COPY_TO_USER -43 ///< kernel driver failed to copy data from kernel to user space
+#define MBG_ERR_COPY_FROM_USER -44 ///< kernel driver failed to copy data from use to kernel space
+
+
+// More codes returned by the driver's high level functions:
+#define MBG_ERR_N_UC_MSTR_EXCEEDS_SUPP -45 ///< num. PTP unicast masters of the device exceeds max. supp. by driver
+#define MBG_ERR_N_GNSS_EXCEEDS_SUPP -46 ///< num. of GNSS systems supp. by device exceeds max. supp. by driver
+#define MBG_ERR_N_GPIO_EXCEEDS_SUPP -47 ///< num. of GPIO ports supp. by device exceeds max. supp. by driver
+#define MBG_ERR_N_XMR_EXCEEDS_SUPP -48 ///< num. of XMR sources supp. by device exceeds max. supp. by driver
+
+#define MBG_ERR_UNSPEC -60 ///< unspecified error
+#define MBG_ERR_HDR_CSUM -61 ///< binary protocol header checksum error
+#define MBG_ERR_DATA_CSUM -62 ///< binary protocol data checksum error
+#define MBG_ERR_RCVD_NACK -63 ///< binary protocol received reply msg with a NACK code
+#define MBG_ERR_RCVD_NO_ACK -64 ///< binary protocol received reply msg without expected ACK code
+#define MBG_ERR_CONN_TYPE -65 ///< binary protocol no valid/supported connection type specified
+#define MBG_ERR_BYTES_WRITTEN -66 ///< binary protocol failed to write all bytes
+#define MBG_ERR_AUTH -67 ///< binary protocol failed authentication
+
+#define MBG_ERR_SOCK_INIT -68 ///< socket interface not initialized, or failed to initialize
+#define MBG_ERR_INV_SOCK_FD -69 ///< invalid socket when tried to open network socket
+#define MBG_ERR_NOT_A_SOCKET -70 ///< socket descriptor is not a socket
+#define MBG_ERR_NBLOCK_WAIT_SLCT -71 ///< select timed when waiting for non-blocking network port to become ready
+#define MBG_ERR_NBLOCK_WAIT_WR_FD -72 ///< write fd not set after select when waiting for non-blocking network port to become ready
+
+#define MBG_ERR_IO -73 ///< generic I/O error
+#define MBG_ERR_INV_PARM -74 ///< invalid parameter
+#define MBG_ERR_NO_DEV -75 ///< specified device not found
+#define MBG_ERR_NOT_FOUND -76 ///< specified item not found
+
+#define MBG_ERR_OVERFLOW -77 ///< buffer overflow
+#define MBG_ERR_PIPE -78 ///< pipe error
+#define MBG_ERR_INTR -79 ///< interrupted system call
+#define MBG_ERR_ACCESS -80 ///< access denied, no permission, eventually distinguish from "Operation not permitted"
+#define MBG_ERR_BUSY -81 ///< device busy
+
+/** @} anchor MBG_ERROR_CODES */
+
+/** @} anchor MBG_RETURN_CODES */
-#define MBG_ERR_COPY_TO_USER -43 /**< kernel driver failed to copy data from kernel to user space */
-#define MBG_ERR_COPY_FROM_USER -44 /**< kernel driver failed to copy data from use to kernel space */
-/** @} */ // endgroup
// Depending on the operating system, the codes above have to be converted before
// they are sent up to user space
@@ -145,7 +199,106 @@ extern "C" {
/* This section was generated automatically */
/* by MAKEHDR, do not remove the comments. */
-/* (no header definitions found) */
+ /**
+ * @brief Translate a Windows non-socket API error code to one of the @ref MBG_ERROR_CODES
+ *
+ * @param wsa_err A Windows non-socket API error code as returned by GetLastError()
+ * @param info An optional informational text string, or NULL
+ *
+ * @return One of the @ref MBG_ERROR_CODES
+ */
+ int mbg_win32_last_err_to_mbg( DWORD wsa_err, const char *info ) ;
+
+ /**
+ * @brief Translate a Windows socket API error code to one of the @ref MBG_ERROR_CODES
+ *
+ * @param wsa_err A Windows socket API error code as returned by WSAGetLastError()
+ * @param info An optional informational text string, or NULL
+ *
+ * @return One of the @ref MBG_ERROR_CODES
+ */
+ int mbg_win32_wsa_err_to_mbg( DWORD wsa_err, const char *info ) ;
+
+ /**
+ * @brief Translate a POSIX errno error code to one of the @ref MBG_ERROR_CODES
+ *
+ * @param posix_errno A POSIX error code as usually defined in errno.h
+ * @param info An optional informational text string, or NULL
+ *
+ * @return One of the @ref MBG_ERROR_CODES
+ */
+ int mbg_posix_errno_to_mbg( int posix_errno, const char *info ) ;
+
+ /**
+ * @brief Translate a POSIX h_errno error code to one of the @ref MBG_ERROR_CODES
+ *
+ * This function is specific to translate error codes returned by
+ * gethostbyname() and gethostbyaddr(). In case of error these functions
+ * don't set errno but h_errno to a specific value.
+ *
+ * The functions gethostbyname() and gethostbyaddr() are obsolete,
+ * and getaddressinfo() should be used preferably.
+ *
+ * @param posix_h_errno An error code as usually defined in netdb.h
+ * @param info An optional informational text string, or NULL
+ *
+ * @return One of the @ref MBG_ERROR_CODES
+ */
+ int mbg_posix_h_errno_to_mbg( int posix_h_errno, const char *info ) ;
+
+ /**
+ * @brief Get and translate last error after non-socket function call
+ *
+ * Retrieve the "last error" code after a non-socket function has been called
+ * and translate to one of the @ref MBG_ERROR_CODES.
+ *
+ * On POSIX systems the "last error" code is always stored in errno, but
+ * e.g. under Windows the "last error" code after a socket function
+ * has to be retrieved by calling WSAGetLastError(), whereas the "last error"
+ * code from non-socket POSIX-like functions has to be retrieved
+ * by calling GetLastError().
+ *
+ * @param info An optional informational text string, or NULL
+ *
+ * @return One of the @ref MBG_ERROR_CODES
+ */
+ int mbg_get_last_error( const char *info ) ;
+
+ /**
+ * @brief Get and translate last error after socket function call
+ *
+ * Retrieve the "last error" code after a socket function has been called
+ * and translate to one of the @ref MBG_ERROR_CODES.
+ *
+ * On POSIX systems the "last error" code is always stored in errno, but
+ * e.g. under Windows the "last error" code after a socket function
+ * has to be retrieved by calling WSAGetLastError, whereas the "last error"
+ * code from non-socket POSIX-like functions is stored in errno as usual.
+ *
+ * @param info An optional informational text string, or NULL
+ *
+ * @return One of the @ref MBG_ERROR_CODES
+ */
+ int mbg_get_last_socket_error( const char *info ) ;
+
+ /**
+ * @brief Retrieve and convert last error after gethostbyname()
+ *
+ * This function is specific to retrieve and translate error codes
+ * returned by gethostbyname() and gethostbyaddr(). In case of error
+ * these functions don't set errno but h_errno on POSIX systems, but
+ * under Windows the error code can be retrieved by WSAGetLastError()
+ * as usual.
+ *
+ * The functions gethostbyname() and gethostbyaddr() are obsolete,
+ * and getaddressinfo() should be used preferably.
+ *
+ * @param info An optional informational text string, or NULL
+ *
+ * @return One of the @ref MBG_ERROR_CODES
+ */
+ int mbg_get_gethostbyname_error( const char *info ) ;
+
/* ----- function prototypes end ----- */
diff --git a/c/mbglib/include/mbgirig.h b/c/mbglib/include/mbgirig.h
new file mode 100644
index 0000000..8caa50b
--- /dev/null
+++ b/c/mbglib/include/mbgirig.h
@@ -0,0 +1,467 @@
+
+/**************************************************************************
+ *
+ * $Id: mbgirig.h 1.2 2014/03/18 16:47:34Z martin TRASH $
+ *
+ * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
+ *
+ * Description:
+ * Definitions and prototypes used with IRIG and similar timecodes.
+ *
+ * -----------------------------------------------------------------------
+ * $Log: mbgirig.h $
+ * Revision 1.2 2014/03/18 16:47:34Z martin
+ * Support IEEE C37.118.1-2011 CTQ.
+ * Revision 1.1 2013/09/02 16:11:54Z martin
+ * Initial revision.
+ *
+ **************************************************************************/
+
+#ifndef _MBGIRIG_H
+#define _MBGIRIG_H
+
+
+/* Other headers to be included */
+
+#include <mbg_tgt.h>
+#include <gpsdefs.h>
+
+
+#ifdef _MBGIRIG
+ #define _ext
+ #define _DO_INIT
+#else
+ #define _ext extern
+#endif
+
+
+/* Start of header body */
+
+#if defined( _USE_PACK )
+ #pragma pack( 1 ) // set byte alignment
+ #define _USING_BYTE_ALIGNMENT
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Get a particular bit from ::MBG_RAW_IRIG_DATA
+ *
+ * @param[in] idx The index number of the raw IRIG bits
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return 0 or 1, depending on the bit level
+ */
+static __mbg_inline
+int mbg_decode_raw_irig_bit( int idx, const MBG_RAW_IRIG_DATA *p )
+{
+ return ( p->data_bytes[idx >> 3] >> ( 7 - ( idx & 7 ) ) ) & 0x01;
+
+} // mbg_decode_raw_irig_bit
+
+
+
+/**
+ * @brief Decode a particular value from ::MBG_RAW_IRIG_DATA
+ *
+ * @param[in] first_idx Index number of the first bit to decode
+ * @param[in] num_bits Number of sequential bits to decode
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return the decoded value
+ */
+static __mbg_inline
+long mbg_decode_raw_irig_val( int first_idx, int num_bits, const MBG_RAW_IRIG_DATA *p )
+{
+ long ret_val = 0;
+ int i;
+
+ for ( i = 0; i < num_bits; i++ )
+ ret_val |= ( ( (long) mbg_decode_raw_irig_bit( first_idx + i, p ) ) << i );
+
+ return ret_val;
+
+} // mbg_decode_raw_irig_val
+
+
+
+/**
+ * @brief Decode the seconds field from ::MBG_RAW_IRIG_DATA
+ *
+ * This is supported for IRIG / IEEE / Afnor code formats.
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return the decoded value
+ */
+static __mbg_inline
+int mbg_decode_raw_irig_sec( const MBG_RAW_IRIG_DATA *p )
+{
+ return mbg_decode_raw_irig_val( 1, 4, p )
+ + mbg_decode_raw_irig_val( 6, 3, p ) * 10;
+
+} // mbg_decode_raw_irig_sec
+
+
+
+/**
+ * @brief Decode the minutes field from ::MBG_RAW_IRIG_DATA
+ *
+ * This is supported for IRIG / IEEE / Afnor code formats.
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return the decoded value
+ */
+static __mbg_inline
+int mbg_decode_raw_irig_min( const MBG_RAW_IRIG_DATA *p )
+{
+ return mbg_decode_raw_irig_val( 10, 4, p )
+ + mbg_decode_raw_irig_val( 15, 3, p ) * 10;
+
+} // mbg_decode_raw_irig_min
+
+
+
+/**
+ * @brief Decode the hours field from ::MBG_RAW_IRIG_DATA
+ *
+ * This is supported for IRIG / IEEE / Afnor code formats.
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return the decoded value
+ */
+static __mbg_inline
+int mbg_decode_raw_irig_hour( const MBG_RAW_IRIG_DATA *p )
+{
+ return mbg_decode_raw_irig_val( 20, 4, p )
+ + mbg_decode_raw_irig_val( 25, 2, p ) * 10;
+
+} // mbg_decode_raw_irig_hour
+
+
+
+/**
+ * @brief Decode the yday (day-of-year) field from ::MBG_RAW_IRIG_DATA
+ *
+ * This is supported for IRIG / IEEE / Afnor code formats.
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return the decoded value
+ */
+static __mbg_inline
+int mbg_decode_raw_irig_yday( const MBG_RAW_IRIG_DATA *p )
+{
+ return mbg_decode_raw_irig_val( 30, 4, p )
+ + mbg_decode_raw_irig_val( 35, 4, p ) * 10
+ + mbg_decode_raw_irig_val( 40, 2, p ) * 100;
+
+} // mbg_decode_raw_irig_yday
+
+
+
+/**
+ * @brief Decode the straight binary seconds (SBS) field from ::MBG_RAW_IRIG_DATA
+ *
+ * @note The returned value is only valid if a code format is received
+ * which provides this information.
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return the decoded value
+ */
+static __mbg_inline
+long mbg_decode_raw_irig_sbs( const MBG_RAW_IRIG_DATA *p )
+{
+ return ( (long) mbg_decode_raw_irig_val( 80, 9, p ) )
+ + ( ( (long) mbg_decode_raw_irig_val( 90, 8, p ) ) << 9 );
+
+} // mbg_decode_raw_irig_sbs
+
+
+
+/**
+ * @brief Decode the short (2-digit) year number from ::MBG_RAW_IRIG_DATA
+ *
+ * @note The returned value is only valid if a code format is received
+ * which provides this information, see @ref MSK_ICODE_TX_HAS_SHORT_YEAR
+ * and @ref MSK_ICODE_RX_HAS_SHORT_YEAR
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return the decoded value
+ */
+static __mbg_inline
+long mbg_decode_raw_irig_short_year( const MBG_RAW_IRIG_DATA *p )
+{
+ return mbg_decode_raw_irig_val( 50, 4, p )
+ + mbg_decode_raw_irig_val( 55, 4, p ) * 10;
+
+} // mbg_decode_raw_irig_short_year
+
+
+
+/**
+ * @brief Decode the leap second announcement bit from ::MBG_RAW_IRIG_DATA
+ *
+ * @note The returned value is only valid if a code format is received
+ * which provides this information, see @ref MSK_ICODE_TX_HAS_TZI and
+ * @ref MSK_ICODE_RX_HAS_TZI
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return 1 if a leap second is pending, else 0
+ */
+static __mbg_inline
+int mbg_decode_raw_irig_ls_ann( const MBG_RAW_IRIG_DATA *p )
+{
+ return mbg_decode_raw_irig_bit( 60, p );
+
+} // mbg_decode_raw_irig_ls_ann
+
+
+
+/**
+ * @brief Decode the leap second negative bit from ::MBG_RAW_IRIG_DATA
+ *
+ * @note The returned value is only valid if a code format is received
+ * which provides this information, see @ref MSK_ICODE_TX_HAS_TZI and
+ * @ref MSK_ICODE_RX_HAS_TZI
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return 1 if a pending leap second is negative (deleted), else 0 (inserted)
+ */
+static __mbg_inline
+int mbg_decode_raw_irig_ls_neg( const MBG_RAW_IRIG_DATA *p )
+{
+ return mbg_decode_raw_irig_bit( 61, p );
+
+} // mbg_decode_raw_irig_ls_neg
+
+
+
+/**
+ * @brief Decode the DST change announcement bit from ::MBG_RAW_IRIG_DATA
+ *
+ * @note The returned value is only valid if a code format is received
+ * which provides this information, see @ref MSK_ICODE_TX_HAS_TZI and
+ * @ref MSK_ICODE_RX_HAS_TZI
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return 1 if a change in daylight saving is pending
+ */
+static __mbg_inline
+int mbg_decode_raw_irig_dl_ann( const MBG_RAW_IRIG_DATA *p )
+{
+ return mbg_decode_raw_irig_bit( 62, p );
+
+} // mbg_decode_raw_irig_dl_ann
+
+
+
+/**
+ * @brief Decode the DST enabled bit from ::MBG_RAW_IRIG_DATA
+ *
+ * @note The returned value is only valid if a code format is received
+ * which provides this information, see @ref MSK_ICODE_TX_HAS_TZI and
+ * @ref MSK_ICODE_RX_HAS_TZI
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return 1 if daylight saving is currently active, else 0
+ */
+static __mbg_inline
+int mbg_decode_raw_irig_dl_enb( const MBG_RAW_IRIG_DATA *p )
+{
+ return mbg_decode_raw_irig_bit( 63, p );
+
+} // mbg_decode_raw_irig_dl_enb
+
+
+
+/**
+ * @brief Decode UTC offset from ::MBG_RAW_IRIG_DATA
+ *
+ * This is only supported by some timecode signal formats,
+ * see @ref MSK_ICODE_TX_HAS_TZI and @ref MSK_ICODE_RX_HAS_TZI
+ *
+ * @note The way the UTC offset has to be applied has been reversed in
+ * IEEE C37.118, which is the successor of the original IEEE 1344 standard.
+ *
+ * For example, if a -6 hours UTC offset is transmitted in the time code:<br>
+ * IEEE 1344: (IRIG time 14:43:27 h) - (offs -6 h) = (UTC 20:43:27)<br>
+ * IEEE C37.118: (IRIG time 14:43:27 h) + (offs -6 h) = (UTC 08:43:27)<br>
+ */
+static __mbg_inline
+long mbg_decode_raw_irig_utc_offs_sec( const MBG_RAW_IRIG_DATA *p )
+{
+ long ret_val = ( (long) mbg_decode_raw_irig_val( 65, 4, p ) ) * SECS_PER_HOUR;
+
+ // a single bit indicates an addition 1/2 hour offset
+ if ( mbg_decode_raw_irig_bit( 70, p ) )
+ ret_val += SECS_PER_HOUR / 2;
+
+ // check the sign bit
+ if ( mbg_decode_raw_irig_bit( 64, p ) )
+ ret_val = -ret_val;
+
+ return ret_val;
+
+} // mbg_decode_raw_irig_utc_offs_sec
+
+
+
+/**
+ * @brief Decode the Time Figure Of Merit (TFOM) code from ::MBG_RAW_IRIG_DATA
+ *
+ * This code reports the time quality from the IRIG generator which is ranging
+ * from 0x0 (locked, maximum accuracy) to 0xF (failed, data unreliable).
+ *
+ * @note The returned value is only valid if a code format is used which supports
+ * this. See @ref MSK_ICODE_TX_HAS_TFOM and @ref MSK_ICODE_RX_HAS_TFOM
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return the decoded value
+ */
+static __mbg_inline
+int mbg_decode_raw_irig_tfom( const MBG_RAW_IRIG_DATA *p )
+{
+ return mbg_decode_raw_irig_val( 71, 4, p );
+
+} // mbg_decode_raw_irig_tfom
+
+
+
+/**
+ * @brief Decode the Continuous Time Quality (CTQ) code from ::MBG_RAW_IRIG_DATA
+ *
+ * IEEE C37.118.1-2011 defines 3 new "Continuous Time Quality, CTQ" bits.
+ * These bits have been 0 (unused) in earlier IEEE codes. Coding:
+ *
+ * 000: not used for CTQ for compatibility with older codes
+ * 001: estimated time error < 100 ns
+ * 010: estimated time error < 1 us
+ * 011: estimated time error < 10 us
+ * 100: estimated time error < 100 us
+ * 101: estimated time error < 1 ms
+ * 110: estimated time error < 10 ms
+ * 111: estimated time error > 10 ms or unknown
+ *
+ * @note The returned value is only valid if a time code format is
+ * used which supports this (see @ref MSK_ICODE_TX_HAS_CTQ and
+ * @ref MSK_ICODE_RX_HAS_CTQ), and if also the time code generator
+ * supports C37.118.1-2011, in which case these 3 bits are never all 0.
+ * If supported, the bits are active all the time, in locked and
+ * unlocked generator state.
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return the decoded value
+ */
+static __mbg_inline
+int mbg_decode_raw_irig_ctq( const MBG_RAW_IRIG_DATA *p )
+{
+ return mbg_decode_raw_irig_val( 76, 3, p );
+
+} // mbg_decode_raw_irig_ctq
+
+
+
+/**
+ * @brief Decode the day-of-week number from ::MBG_RAW_IRIG_DATA
+ *
+ * @note The returned value is only valid if a code format is received
+ * which provides this information, see @ref MSK_ICODE_TX_HAS_AFNOR_WDAY
+ * and @ref MSK_ICODE_RX_HAS_AFNOR_WDAY
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return the decoded value
+ */
+static __mbg_inline
+long mbg_decode_raw_afnor_wday( const MBG_RAW_IRIG_DATA *p )
+{
+ return mbg_decode_raw_irig_val( 44, 3, p );
+
+} // mbg_decode_raw_afnor_wday
+
+
+
+/**
+ * @brief Decode the day-of-month from ::MBG_RAW_IRIG_DATA
+ *
+ * @note The returned value is only valid if a code format is received
+ * which provides this information, see @ref MSK_ICODE_TX_HAS_AFNOR_DATE
+ * and @ref MSK_ICODE_RX_HAS_AFNOR_DATE
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return the decoded value
+ */
+static __mbg_inline
+long mbg_decode_raw_afnor_mday( const MBG_RAW_IRIG_DATA *p )
+{
+ return mbg_decode_raw_irig_val( 70, 4, p )
+ + mbg_decode_raw_irig_val( 75, 2, p ) * 10;
+
+} // mbg_decode_raw_afnor_mday
+
+
+
+/**
+ * @brief Decode the month number from ::MBG_RAW_IRIG_DATA
+ *
+ * @note The returned value is only valid if a code format is received
+ * which provides this information, see @ref MSK_ICODE_TX_HAS_AFNOR_DATE
+ * and @ref MSK_ICODE_RX_HAS_AFNOR_DATE
+ *
+ * @param[in] p A ::MBG_RAW_IRIG_DATA structure
+ *
+ * @return the decoded value
+ */
+static __mbg_inline
+long mbg_decode_raw_afnor_month( const MBG_RAW_IRIG_DATA *p )
+{
+ return mbg_decode_raw_irig_val( 60, 4, p )
+ + mbg_decode_raw_irig_val( 65, 1, p ) * 10;
+
+} // mbg_decode_raw_afnor_month
+
+
+
+
+
+/* ----- function prototypes begin ----- */
+
+/* This section was generated automatically */
+/* by MAKEHDR, do not remove the comments. */
+
+/* (no header definitions found) */
+
+/* ----- function prototypes end ----- */
+
+#ifdef __cplusplus
+}
+#endif
+
+
+#if defined( _USING_BYTE_ALIGNMENT )
+ #pragma pack() // set default alignment
+ #undef _USING_BYTE_ALIGNMENT
+#endif
+
+/* End of header body */
+
+
+#undef _ext
+#undef _DO_INIT
+
+#endif /* _MBGIRIG_H */
+
diff --git a/c/mbglib/include/mbgmutex.h b/c/mbglib/include/mbgmutex.h
index 86fd058..b0d2e7a 100644
--- a/c/mbglib/include/mbgmutex.h
+++ b/c/mbglib/include/mbgmutex.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: mbgmutex.h 1.2 2012/03/08 12:19:01Z martin REL_M $
+ * $Id: mbgmutex.h 1.3.1.2 2014/03/04 12:08:12Z martin TRASH $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -11,6 +11,11 @@
*
* -----------------------------------------------------------------------
* $Log: mbgmutex.h $
+ * Revision 1.3.1.2 2014/03/04 12:08:12Z martin
+ * Revision 1.3.1.1 2014/01/08 17:20:57Z martin
+ * MBG_TGT_POSIX
+ * Revision 1.3 2013/04/11 13:46:58 martin
+ * Use non-specific spinlock function under Windows.
* Revision 1.2 2012/03/08 12:19:01Z martin
* Fixes for Linux kernel and FreeBSD.
* Fixed build under DOS and QNX usinc dummy defines.
@@ -47,8 +52,8 @@
typedef KSPIN_LOCK MBG_SPINLOCK;
#define _mbg_spin_lock_init( _spl ) KeInitializeSpinLock( _spl )
// _mbg_spin_lock_destroy is not supported
- #define _mbg_spin_lock_acquire( _spl ) KeAcquireSpinLockAtDpcLevel( _spl )
- #define _mbg_spin_lock_release( _spl ) KeReleaseSpinLockFromDpcLevel( _spl )
+ #define _mbg_spin_lock_acquire( _spl ) KeAcquireSpinLock( _spl, &OldIrql )
+ #define _mbg_spin_lock_release( _spl ) KeReleaseSpinLock( _spl, OldIrql )
#define _MBG_SPINLOCK_DEFINED 1
@@ -141,8 +146,6 @@
#if defined( MBG_TGT_WIN32 ) // Windows user space
- #include <windows.h>
-
// definitions used with mutexes
typedef HANDLE MBG_MUTEX;
#define _mbg_mutex_init( _pm ) *(_pm) = CreateMutex( NULL, FALSE, NULL )
@@ -161,7 +164,7 @@
#define _MBG_CRIT_SECT_DEFINED 1
- #elif defined( MBG_TGT_UNIX ) // Unix user space use pthread library
+ #elif defined( MBG_TGT_POSIX ) // Unix user space use pthread library
#include <pthread.h>
diff --git a/c/mbglib/include/mbgpccyc.h b/c/mbglib/include/mbgpccyc.h
index bebb38e..d32e21e 100644
--- a/c/mbglib/include/mbgpccyc.h
+++ b/c/mbglib/include/mbgpccyc.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: mbgpccyc.h 1.2 2012/03/12 13:45:57Z martin TRASH $
+ * $Id: mbgpccyc.h 1.2.1.1 2014/01/08 17:21:03Z martin TRASH $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -10,7 +10,9 @@
*
* -----------------------------------------------------------------------
* $Log: mbgpccyc.h $
- * Revision 1.2 2012/03/12 13:45:57Z martin
+ * Revision 1.2.1.1 2014/01/08 17:21:03Z martin
+ * MBG_TGT_POSIX
+ * Revision 1.2 2012/03/12 13:45:57 martin
* Added cycles support for Linux/IA64, FreeBSD and NetBSD
* in kernel space.
* Use get_cycles() in Linux kernel mode if no special cycles support
@@ -67,7 +69,7 @@
* The cycle counter value is usually derived from the PC CPU's TSC or some other
* timer hardware on the mainboard.
*/
-#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_UNIX )
+#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX )
typedef int64_t MBG_PC_CYCLES;
typedef uint64_t MBG_PC_CYCLES_FREQUENCY;
diff --git a/c/mbglib/include/mbgsvcio.h b/c/mbglib/include/mbgsvcio.h
index f97b9b5..83161ef 100644
--- a/c/mbglib/include/mbgsvcio.h
+++ b/c/mbglib/include/mbgsvcio.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: mbgsvcio.h 1.17 2014/07/10 15:03:14Z martin TEST $
+ * $Id: mbgsvcio.h 1.16.1.3 2012/10/17 12:45:11Z martin TRASH $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -10,9 +10,10 @@
*
* -----------------------------------------------------------------------
* $Log: mbgsvcio.h $
- * Revision 1.17 2014/07/10 15:03:14Z martin
- * Moved some definitions here.
- * Updated function prototypes.
+ * Revision 1.16.1.3 2012/10/17 12:45:11Z martin
+ * Fixed doxygen comments.
+ * Revision 1.16.1.2 2010/01/08 15:04:38Z martin
+ * Revision 1.16.1.1 2010/01/07 16:24:56Z martin
* Revision 1.16 2009/08/14 09:28:13Z daniel
* New version code 306, compatibility version code still 200.
* Revision 1.15 2009/06/09 08:57:47Z daniel
@@ -56,8 +57,8 @@
/* Other headers to be included */
#include <mbg_tgt.h>
-#include <words.h>
-#include <pcpsdefs.h>
+#include <mbgdevio.h> // for mutex support only
+#include <timecnv.h> // for REF_TIME only
@@ -79,67 +80,11 @@
#define MBGSVCIO_COMPAT_VERSION 0x0200
+
#ifdef __cplusplus
extern "C" {
#endif
-/**
- * @brief A union used to access a FILETIME as 64 bit number
- *
- * @note using this union may be tricky. Even though no problems
- * have been observed, yet, the MS docs clearly say there may be
- * alignment problems under 64 bit Windows.
- * If the FILETIME members are not 32 bit aligned then accessing
- * the dwl member will yield wrong values.
- */
-typedef union
-{
- FILETIME ft; ///< FILETIME structure as provided by the Windows API
- uint64_t dwl; ///< used to access as single 64 bit number
-
-} FT_DWL;
-
-
-
-/**
- * @brief A timestamp in Windows format, plus %UTC offset and clock status
- */
-typedef struct
-{
- FT_DWL ftdwl; ///< time stamp, based on %UTC
- int32_t utc_offs; ///< %UTC offset in [sec]
- PCPS_TIME_STATUS_X status; ///< extended status, see ::PCPS_TIME_STATUS_X
-
-} REF_TIME;
-
-
-
-/**
- * @brief Error information retrieved from the time adjustment service
- */
-typedef struct
-{
- uint32_t code; ///< error/status code, see ::ERR_INFO_CODES
- REF_TIME time; ///< clock's time and status when ::code was updated
-
-} ERR_INFO;
-
-
-/**
- * @brief Codes used with ::ERR_INFO::code
- */
-enum ERR_INFO_CODES
-{
- MBG_SVC_NO_ERROR, ///< No current error condition
- MBG_SVC_ERR_OPEN_CLOCK_DEV, ///< Failed to open clock device
- MBG_SVC_ERR_OPEN_SERIAL_PORT, ///< Failed to open serial port
- MBG_SVC_ERR_SAME_REF_TIME, ///< Clock device always returns same time (hardware failure)
- MBG_SVC_ERR_REF_TIME_STEP, ///< Time on the clock device has jumped, service stopped disciplining system time
- N_MBG_SVC_ERR_CODE ///< the number of known codes
-};
-
-
-
/* ----- function prototypes begin ----- */
/* This section was generated automatically */
@@ -179,13 +124,6 @@ enum ERR_INFO_CODES
_MBG_API_ATTR int _MBG_API mbg_time_adjustment_active( void ) ;
/**
- Read the ::ERROR_INFO structure from the Meinberg time adjustment service "mbgadjtm.exe"
-
- @return 0 on success, < 0 on error
-*/
- _MBG_API_ATTR int _MBG_API mbg_get_time_adjustment_err_info( ERR_INFO *p ) ;
-
- /**
Check if the time of the reference clock is accessible.
@return 1: The reference clock is accessible and delivers a valid time.<br>
@@ -218,6 +156,68 @@ enum ERR_INFO_CODES
*/
_MBG_API_ATTR int _MBG_API mbg_get_ref_time_status( void ) ;
+ /**
+ Save the latest date and time from a serial time string
+ plus the associated PC cycles count, so other processes
+ or functions can use the current cycles count together
+ with this data pair to interpolate the time between two
+ time strings.
+
+ This function is (and should only be) called by the time
+ adjustment service.
+
+ @return MBG_SUCCESS always
+*/
+ _MBG_API_ATTR int _MBG_API mbg_set_serial_xhrt_data( const REF_TIME_CYCLES *p ) ;
+
+ /**
+ Set the "invalid time" flag (PCPS_INVT) in the status of the
+ saved serial date and time. This is normally done by time
+ adjustment service if the serial string times out, e.g. because
+ the serial device has been disconnected.
+
+ @return MBG_SUCCESS always
+*/
+ _MBG_API_ATTR int _MBG_API mbg_set_serial_xhrt_data_invalid( void ) ;
+
+ /**
+ Retrieve the latest date and time from a serial time string
+ plus the associated PC cycles count, so this data pair can
+ be used to interpolate the time between two serial strings
+ using the current cycles count.
+
+ @return MBG_SUCCESS always
+*/
+ _MBG_API_ATTR int _MBG_API mbg_get_serial_xhrt_data( uint64_t *tstamp, MBG_XHRT_VARS *vars ) ;
+
+ /**
+ Retrieve a time stamp in PCPS_HR_TIME format which is extrapolated
+ using the system's current cycles counter value and a time stamp
+ plus associated cycles counter value from a serial time string,
+ saved by the time adjustment service.
+
+ @param *p_hrt Pointer to a ::PCPS_HR_TIME structure to be filled up.
+
+ @return MBG_SUCCESS
+
+ @see mbg_get_serial_xhrt_time_as_filetime()
+ */
+ _MBG_API_ATTR int _MBG_API mbg_get_serial_xhrt_time_as_pcps_hr_time( PCPS_HR_TIME *p_hrt ) ;
+
+ /**
+ Retrieve a time stamp in FILETIME format which is extrapolated
+ using the system's current cycles counter value and a time stamp
+ plus associated cycles counter value from a serial time string,
+ saved by the time adjustment service.
+
+ @param *p_ft Pointer to a FILETIME structure to be filled up.
+
+ @return MBG_SUCCESS
+
+ @see mbg_get_serial_xhrt_time_as_pcps_hr_time()
+ */
+ _MBG_API_ATTR int _MBG_API mbg_get_serial_xhrt_time_as_filetime( FILETIME *p_ft ) ;
+
/* ----- function prototypes end ----- */
diff --git a/c/mbglib/include/mbgtime.h b/c/mbglib/include/mbgtime.h
index 541d462..c7b0eee 100644
--- a/c/mbglib/include/mbgtime.h
+++ b/c/mbglib/include/mbgtime.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: mbgtime.h 1.17.1.7 2011/10/21 14:07:52Z martin TEST $
+ * $Id: mbgtime.h 1.20 2014/05/27 08:09:19Z martin REL_M $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -10,17 +10,13 @@
*
* -----------------------------------------------------------------------
* $Log: mbgtime.h $
- * Revision 1.17.1.7 2011/10/21 14:07:52Z martin
- * Changes for QNX.
- * Revision 1.17.1.6 2011/05/06 09:03:12 martin
- * Fix for DOS.
- * Revision 1.17.1.5 2011/05/06 08:07:58Z daniel
- * include <time.h> for WIN32 target and firmware only
- * Revision 1.17.1.4 2011/02/09 15:46:48Z martin
- * Revision 1.17.1.3 2011/01/24 17:09:20 martin
- * Fixed build under FreeBSD.
- * Revision 1.17.1.2 2010/08/13 11:57:13 martin
- * Revision 1.17.1.1 2010/08/13 11:39:20Z martin
+ * Revision 1.20 2014/05/27 08:09:19Z martin
+ * Added NTP_SEC_BIAS.
+ * Revision 1.19 2013/05/22 16:47:01 martin
+ * Added some useful macros.
+ * Revision 1.18 2012/10/02 18:51:11 martin
+ * Include <time.h> for WIN32 target and firmware only
+ * Fixed build under QNX, DOS, and FreeBSD.
* Revision 1.17 2010/08/06 13:03:03 martin
* Removed obsolete code.
* Revision 1.16 2010/07/16 10:22:07Z martin
@@ -89,13 +85,30 @@ extern "C" {
/* Start of header body */
-// The Unix time_t epoche is usually 1970-01-01 00:00 whereas
-// the GPS epoche is 1980-01-06 00:00, so the difference is 10 years,
-// plus 2 days due to leap years (1972 and 1976), plus the difference
-// of the day-of-month (6 - 1).
-#define GPS_SEC_BIAS 315964800UL // ( ( ( 10UL * 365UL ) + 2 + 5 ) * SECS_PER_DAY )
+/**
+ * @brief GPS epoch bias from ordinary time_t epoch
+ *
+ * The Unix time_t epoch is usually 1970-01-01 00:00 whereas
+ * the GPS epoch is 1980-01-06 00:00, so the difference is 10 years,
+ * plus 2 days due to leap years (1972 and 1976), plus the difference
+ * of the day-of-month (6 - 1), so:<br>
+ *
+ * time_t t = ( gps_week * ::SECS_PER_WEEK ) + sec_of_week + ::GPS_SEC_BIAS
+ */
+#define GPS_SEC_BIAS 315964800UL // ( ( ( 10UL * 365UL ) + 2 + 5 ) * SECS_PER_DAY )
+
+
+/**
+ * @brief NTP epoch bias from ordinary time_t epoch
+ *
+ * The Unix time_t epoch is usually 1970-01-01 00:00 whereas
+ * the NTP epoch is 1900-01-01 00:00, so the difference is
+ * a constant number of seconds:<br>
+ *
+ * time_t t = ntp_time - ::NTP_SEC_BIAS
+ */
+#define NTP_SEC_BIAS 2208988800UL
-// time_t t = ( gps_week * SECS_PER_WEEK ) + sec_of_week + GPS_SEC_BIAS
// Modified Julian Day (MJD) numbers for some commonly used epochs.
@@ -217,6 +230,28 @@ typedef struct
#endif
+/**
+ * @brief A table with the days of month
+ *
+ * First row is for standard years, second row is
+ * for leap years.
+ *
+ * @see DAYS_OF_MONTH_TABLE_INIT
+ */
+typedef char DAYS_OF_MONTH_TABLE[2][12];
+
+
+/**
+ * @brief An initializer for a ::DAYS_OF_MONTH_TABLE
+ */
+#define DAYS_OF_MONTH_TABLE_INIT \
+{ \
+ { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }, \
+ { 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 } \
+}
+
+
+
_ext TM_GPS dhms;
_ext TM_GPS datum;
@@ -271,12 +306,9 @@ _ext const TM_GPS init_tm
;
-_ext char days_of_month[2][12]
+_ext DAYS_OF_MONTH_TABLE days_of_month
#ifdef _MBGTIME
- = {
- { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 },
- { 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }
- }
+ = DAYS_OF_MONTH_TABLE_INIT
#endif
;
@@ -286,6 +318,15 @@ _ext char days_of_month[2][12]
n_days( (_s)->mday, (_s)->month, (_s)->year )
+#define _is_leap_year( _y ) \
+ ( ( ( ( (_y) % 4 ) == 0 ) && ( ( (_y) % 100 ) != 0 ) ) || ( ( (_y) % 400 ) == 0 ) )
+
+
+#define _get_days_of_month( _y, _m ) \
+ days_of_month[ _is_leap_year( _y ) ][_m]
+
+
+
/* ----- function prototypes begin ----- */
/* This section was generated automatically */
diff --git a/c/mbglib/include/mbgutil.h b/c/mbglib/include/mbgutil.h
index 09d53ee..a12c713 100644
--- a/c/mbglib/include/mbgutil.h
+++ b/c/mbglib/include/mbgutil.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: mbgutil.h 1.16.1.2 2011/06/22 10:21:57Z martin TEST $
+ * $Id: mbgutil.h 1.17.1.8 2014/05/27 11:32:47Z martin TRASH martin $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -10,10 +10,18 @@
*
* -----------------------------------------------------------------------
* $Log: mbgutil.h $
- * Revision 1.16.1.2 2011/06/22 10:21:57Z martin
- * Cleaned up handling of pragma pack().
- * Revision 1.16.1.1 2011/02/09 15:27:23 martin
+ * Revision 1.17.1.8 2014/05/27 11:32:47Z martin
+ * Revision 1.17.1.7 2014/03/13 16:04:12 martin
+ * Revision 1.17.1.6 2014/03/13 15:45:37 martin
+ * Revision 1.17.1.5 2014/03/13 14:58:52Z martin
+ * Revision 1.17.1.4 2014/03/13 14:31:53Z martin
+ * Revision 1.17.1.3 2014/03/05 10:38:30Z martin
+ * Windows.h is now included in mbg_tgt.h.
+ * Revision 1.17.1.2 2013/10/23 10:40:53Z martin
+ * Revision 1.17.1.1 2013/10/22 10:06:01 martin
+ * Revision 1.17 2012/10/15 10:08:32 martin
* Include stdlib.h.
+ * Cleaned up handling of pragma pack().
* Revision 1.16 2009/08/14 10:11:53Z daniel
* New version code 306, compatibility version still 110.
* Revision 1.15 2009/06/09 08:57:47Z daniel
@@ -71,7 +79,6 @@
#if defined( MBG_TGT_WIN32 )
- #include <windows.h>
#elif defined( MBG_TGT_LINUX )
@@ -133,11 +140,57 @@ extern "C" {
/* This section was generated automatically */
/* by MAKEHDR, do not remove the comments. */
+ /**
+ * @brief Get the DLL/shared library's version code
+ *
+ * @return The version code at which the library was built
+ */
_MBG_API_ATTR int _MBG_API mbgutil_get_version( void ) ;
+
+ /**
+ * @brief Check the DLL/shared library's compatibility
+ *
+ * @param header_version Version code defined in the header file when the application is built
+ *
+ * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE
+ */
_MBG_API_ATTR int _MBG_API mbgutil_check_version( int header_version ) ;
- _MBG_API_ATTR int _MBG_API mbg_snprintf( char *s, size_t max_len, const char * fmt, ... ) ;
+
+ /**
+ * @brief A portable implementation of snprintf()
+ *
+ * Under Windows _snprintf() returns -1 and does not write
+ * a terminating 0 if the output exceeds the buffer size.
+ *
+ * This function terminates the output string properly. However,
+ * the maximum return value is (max_len - 1), so the function
+ * can not be used to determine the buffer size that would be
+ * required for an untruncated string.
+ *
+ * @param s pointer to the output buffer
+ * @param max_len size of the output buffer
+ * @param fmt format string according to subsequent parameters
+ * @param ... variable argument list according to the format string
+ *
+ * @return the number of characters written to the output buffer, except the terminating 0
+ */
+ _MBG_API_ATTR int __attribute__( ( format( printf, 3, 4 ) ) ) _MBG_API mbg_snprintf( char *s, size_t max_len, const char * fmt, ... ) ;
+
_MBG_API_ATTR int _MBG_API mbg_strncpy( char *s, size_t max_len, const char *src ) ;
+ /**
+ * @brief Write a character multiple times to a string buffer
+ *
+ * Append a terminating 0 to the buffer.
+ *
+ * @param s pointer to the output buffer
+ * @param max_len size of the output buffer
+ * @param c the character to write to the output buffer
+ * @param n the number of characters to write to the output buffer
+ *
+ * @return the number of characters written to the output buffer, except the terminating 0
+ */
_MBG_API_ATTR int _MBG_API mbg_strchar( char *s, size_t max_len, char c, size_t n ) ;
+
_MBG_API_ATTR int _MBG_API mbg_str_date_short( char *s, int max_len, int mday, int month ) ;
_MBG_API_ATTR int _MBG_API mbg_str_date( char *s, int max_len, int mday, int month, int year ) ;
_MBG_API_ATTR int _MBG_API mbg_str_time_short( char *s, int max_len, int hour, int min ) ;
@@ -154,8 +207,8 @@ extern "C" {
_MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time( char *s, int max_len, uint32_t sec ) ;
_MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date_time_utc( char *s, int max_len, const PCPS_HR_TIME *pt ) ;
_MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date_time_loc( char *s, int max_len, const PCPS_HR_TIME *pt ) ;
- _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_frac( char *s, int max_len, uint32_t frac ) ;
- _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_offs( char *s, int max_len, const PCPS_HR_TIME *pt, const char *info ) ;
+ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_frac( char *s, int max_len, uint32_t frac ) ;
+ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_offs( char *s, int max_len, const PCPS_HR_TIME *pt, const char *info ) ;
_MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_tstamp_utc( char *s, int max_len, const PCPS_HR_TIME *pt ) ;
_MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_tstamp_loc( char *s, int max_len, const PCPS_HR_TIME *pt ) ;
_MBG_API_ATTR int _MBG_API mbg_str_pcps_tstamp_raw( char *s, int max_len, const PCPS_TIME_STAMP *pt ) ;
diff --git a/c/mbglib/include/pci_asic.h b/c/mbglib/include/pci_asic.h
index 8eb6371..cdbc995 100644
--- a/c/mbglib/include/pci_asic.h
+++ b/c/mbglib/include/pci_asic.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: pci_asic.h 1.22 2011/10/05 09:46:12Z martin REL_M $
+ * $Id: pci_asic.h 1.24 2013/10/01 15:29:39Z martin REL_M $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -10,7 +10,11 @@
*
* -----------------------------------------------------------------------
* $Log: pci_asic.h $
- * Revision 1.22 2011/10/05 09:46:12Z martin
+ * Revision 1.24 2013/10/01 15:29:39Z martin
+ * Updated version info for PTP270PEX.
+ * Revision 1.23 2013/06/26 15:57:07Z martin
+ * Support GLN180PEX.
+ * Revision 1.22 2011/10/05 09:46:12 martin
* Updated version info for GPS180PEX.
* Revision 1.21 2011/09/13 07:36:21Z martin
* Updated version info for GPS180PEX.
@@ -280,13 +284,14 @@ enum
PCI_ASIC_MAJOR_GPS180PEX, // PEX EPLD for GPS180PEX
PCI_ASIC_MAJOR_TCR180PEX, // PEX EPLD for TCR180PEX
PCI_ASIC_MAJOR_PZF180PEX, // PEX EPLD for PZF180PEX
+ PCI_ASIC_MAJOR_GLN180PEX, // PEX EPLD for GLN180PEX
N_PCI_ASIC_MAJOR // the number of known codes
};
/*
The minor number increases when a new EPLD image is released.
- At least EPLD images with the following "required minor" numbers
- should be installed for proper operation. The "current minor"
+ At least EPLD images with the following "required minor" numbers
+ should be installed for proper operation. The "current minor"
numbers can be used to check if a newer EPLD image is available:
*/
#define PCI_ASIC_CURRENT_MINOR_PEX511 0x04
@@ -306,8 +311,11 @@ enum
// 0x04 // EPLD sources shared with PEX511 0x04
#define PCI_ASIC_FIX_IRQ_MINOR_TCR511PEX 0x03 // fixes IRQ problem, increases HRT accuracy
-#define PCI_ASIC_CURRENT_MINOR_PTP270PEX 0x02
+#define PCI_ASIC_CURRENT_MINOR_PTP270PEX 0x05
#define PCI_ASIC_REQUIRED_MINOR_PTP270PEX 0x01
+// 0x05 // ...
+// 0x04 // ...
+// 0x03 // ...
// 0x02 // increased accuracy of IRIG DCLS slopes
// 0x01 // supports inversion of ucap slopes
@@ -333,6 +341,8 @@ enum
#define PCI_ASIC_CURRENT_MINOR_PZF180PEX 0x00
#define PCI_ASIC_REQUIRED_MINOR_PZF180PEX 0x00
+#define PCI_ASIC_CURRENT_MINOR_GLN180PEX 0x00
+#define PCI_ASIC_REQUIRED_MINOR_GLN180PEX 0x00
typedef struct
{
@@ -353,6 +363,7 @@ typedef struct
{ PCPS_TYPE_GPS180PEX, PCI_ASIC_MAJOR_GPS180PEX, PCI_ASIC_CURRENT_MINOR_GPS180PEX, PCI_ASIC_REQUIRED_MINOR_GPS180PEX }, \
{ PCPS_TYPE_TCR180PEX, PCI_ASIC_MAJOR_TCR180PEX, PCI_ASIC_CURRENT_MINOR_TCR180PEX, PCI_ASIC_REQUIRED_MINOR_TCR180PEX }, \
{ PCPS_TYPE_PZF180PEX, PCI_ASIC_MAJOR_PZF180PEX, PCI_ASIC_CURRENT_MINOR_PZF180PEX, PCI_ASIC_REQUIRED_MINOR_PZF180PEX }, \
+ { PCPS_TYPE_GLN180PEX, PCI_ASIC_MAJOR_GLN180PEX, PCI_ASIC_CURRENT_MINOR_GLN180PEX, PCI_ASIC_REQUIRED_MINOR_GLN180PEX }, \
{ 0 } \
}
diff --git a/c/mbglib/include/pcpsdefs.h b/c/mbglib/include/pcpsdefs.h
index 9f97c0f..54d22e6 100644
--- a/c/mbglib/include/pcpsdefs.h
+++ b/c/mbglib/include/pcpsdefs.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: pcpsdefs.h 1.48 2011/11/25 15:02:28Z martin REL_M $
+ * $Id: pcpsdefs.h 1.55 2014/07/17 10:52:24Z martin REL_M $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -10,7 +10,28 @@
*
* -----------------------------------------------------------------------
* $Log: pcpsdefs.h $
- * Revision 1.48 2011/11/25 15:02:28Z martin
+ * Revision 1.55 2014/07/17 10:52:24Z martin
+ * Increased safety of firmware builds.
+ * Revision 1.54 2014/07/17 09:54:19 martin
+ * New command codes PC_GPS_XMR_HOLDOVER_STATUS
+ * and PC_GPS_ALL_GPIO_STATUS.
+ * Huge update and cleanup on doxygen comments.
+ * Revision 1.53 2014/05/27 10:13:20 martin
+ * Support GPS180AMC.
+ * Moved some signal constant definitions to pcpsdefs.h.
+ * Simplified declaration of code/name tables.
+ * Huge rework of comments in doxygen format.
+ * Revision 1.52 2013/09/26 09:02:52Z martin
+ * Support GNSS API.
+ * Updated doxygen comments.
+ * Revision 1.51 2013/06/25 09:51:39 martin
+ * Support GLN180PEX.
+ * Revision 1.50 2013/01/30 15:59:54 martin
+ * Updated and fixed some doxygen comments.
+ * Revision 1.49 2012/10/02 18:53:02 martin
+ * Added structure PCPS_TIME_STATUS_X_MASKS.
+ * Added initializer for command names, useful for debugging.
+ * Revision 1.48 2011/11/25 15:02:28 martin
* Support on-board event logs.
* Revision 1.47 2011/11/25 10:22:44 martin
* Modified handling of pragma pack().
@@ -196,8 +217,8 @@
* Changes before put under RCS control:
*
* Revision 1.5 2000/03/24
- * Introduced PCPS_GIVE_SERNUM
- * Cleaned up for definitions for serial parameter byte
+ * Introduced PCPS_GIVE_SERNUM.
+ * Cleaned up for definitions for serial parameter byte.
* Reviewed and updated comments.
*
* 1998/07/22
@@ -206,7 +227,7 @@
* Reviewed and updated comments.
*
* 1997/06/12
- * GPS definitions added.
+ * Added GPS definitions.
*
* 1996/01/25
* PCPS_TIME redefined from an array of bytes to a structure.
@@ -222,6 +243,13 @@
#include <words.h>
#include <use_pack.h>
+#ifndef _USE_PCPSPRIV
+ #define _USE_PCPSPRIV _IS_MBG_FIRMWARE
+#endif
+
+#if _USE_PCPSPRIV
+ #include <pcpspriv.h>
+#endif
/* Start of header body */
@@ -236,16 +264,16 @@
*/
enum
{
- PCPS_REF_NONE, /**< (unknown or not defined) */
- PCPS_REF_DCF, /**< see http://www.meinberg.de/english/info/dcf77.htm */
- PCPS_REF_GPS, /**< see http://www.meinberg.de/english/info/gps.htm */
- PCPS_REF_IRIG, /**< see http://www.meinberg.de/english/info/irig.htm */
- PCPS_REF_MSF, /**< MSF Receiver (UK) */
- PCPS_REF_PTP, /**< PTP/IEEE1588 network protocol */
- PCPS_REF_FRC, /**< Free Running Clock */
- PCPS_REF_WWVB, /**< WWVB Receiver (US) */
- PCPS_REF_JJY, /**< JJY Receiver (Japan) */
- N_PCPS_REF /**< number of valid ref time sources */
+ PCPS_REF_NONE, ///< (unknown or not defined)
+ PCPS_REF_DCF, ///< see http://www.meinberg.de/english/info/dcf77.htm
+ PCPS_REF_GPS, ///< see http://www.meinberg.de/english/info/gps.htm
+ PCPS_REF_IRIG, ///< see http://www.meinberg.de/english/info/irig.htm
+ PCPS_REF_MSF, ///< MSF Receiver (UK)
+ PCPS_REF_PTP, ///< PTP/IEEE1588 network protocol
+ PCPS_REF_FRC, ///< Free Running Clock
+ PCPS_REF_WWVB, ///< WWVB Receiver (US)
+ PCPS_REF_JJY, ///< JJY Receiver (Japan)
+ N_PCPS_REF ///< number of defined ref time sources
};
@@ -293,14 +321,21 @@ enum
/**
- * @brief Meinberg PCI vendor ID (assigned by PCI SIG)
+ * @brief Meinberg PCI vendor ID (assigned by the PCI SIG)
*/
#define PCI_VENDOR_MEINBERG 0x1360
-/* PCI device ID numbers (assigned by Meinberg) *
- * High byte: type of ref time source
- * Low Byte: enumeration of device types
- */
+
+/**
+ * @brief PCI device IDs assigned by Meinberg
+ *
+ * High byte: type of ref time source
+ * Low Byte: enumeration of device types
+ *
+ * @see ::PCI_VENDOR_MEINBERG
+ *
+ * @anchor MEINBERG_PCI_DEVICE_IDS @{ */
+
#define PCI_DEV_PCI32 ( ( PCPS_REF_DCF << 8 ) | 0x01 )
#define PCI_DEV_PCI509 ( ( PCPS_REF_DCF << 8 ) | 0x02 )
#define PCI_DEV_PCI510 ( ( PCPS_REF_DCF << 8 ) | 0x03 )
@@ -314,6 +349,8 @@ enum
#define PCI_DEV_GPS170PCI ( ( PCPS_REF_GPS << 8 ) | 0x04 )
#define PCI_DEV_GPS170PEX ( ( PCPS_REF_GPS << 8 ) | 0x05 )
#define PCI_DEV_GPS180PEX ( ( PCPS_REF_GPS << 8 ) | 0x06 )
+#define PCI_DEV_GLN180PEX ( ( PCPS_REF_GPS << 8 ) | 0x07 )
+#define PCI_DEV_GPS180AMC ( ( PCPS_REF_GPS << 8 ) | 0x08 )
#define PCI_DEV_TCR510PCI ( ( PCPS_REF_IRIG << 8 ) | 0x01 )
#define PCI_DEV_TCR167PCI ( ( PCPS_REF_IRIG << 8 ) | 0x02 )
@@ -326,37 +363,54 @@ enum
#define PCI_DEV_FRC511PEX ( ( PCPS_REF_FRC << 8 ) | 0x01 )
+/** @} anchor MEINBERG_PCI_DEVICE_IDS */
-// definitions used for the status port register
-// (not to be intermixed with PCPS_TIME_STATUS)
-typedef uint8_t PCPS_STATUS_PORT; /**< see @ref group_status_port "Bitmask" */
/**
- * @defgroup group_status_port Bit masks of PCPS_STATUS_PORT
+ * @defgroup group_status_port Definitions used with the status port
+ *
+ * The status port register on bus-level cards reflects some hardware
+ * signals (e.g. DCF-77 modulation), and flags used for communication
+ * with the card (e.g. the BUSY flag, ::PCPS_ST_BUSY).
+ *
+ * @note Must not be confused with ::PCPS_TIME_STATUS which returns
+ * the synchronization status and associated information
*
- * Bit definitions used with the #PCPS_STATUS_PORT register.
+ * @{ */
+
+/**
+ * @brief Type of the status register port
+ */
+typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS
+
+
+/**
+ * @brief Bit masks used with ::PCPS_STATUS_PORT
*
- * The flags #PCPS_ST_SEC and #PCPS_ST_MIN are cleared whenever the clock
+ * The flags ::PCPS_ST_SEC and ::PCPS_ST_MIN are cleared whenever the clock
* is read, so they are not very reliable in multitasking environments.
*
- * @note The PCPS_ST_IRQF flag originates from old ISA cards.
+ * The ::PCPS_ST_IRQF flag originates from old ISA cards.
* Some PCI cards also support this, but in case of PCI cards the
* associated flag of the PCI interface chip should be checked to see
- * if a certain card has generated an IRQ on the PC bus.
+ * if a particular card has generated an IRQ on the PC bus.
*
* The macro _pcps_ddev_has_gen_irq() cares about this and should be used
* to determine in a portable way whether a card has generated an IRQ.
*
- * @{ */
+ * @anchor PCPS_STATUS_PORT_BIT_MASKS @{ */
+
+#define PCPS_ST_BUSY 0x01 ///< the clock is busy filling the output FIFO
+#define PCPS_ST_IRQF 0x02 ///< the clock has generated an IRQ on the PC bus (ISA only)
+#define PCPS_ST_MOD 0x20 ///< the raw demodulated DCF77 signal
+#define PCPS_ST_SEC 0x40 ///< seconds have changed since last reading
+#define PCPS_ST_MIN 0x80 ///< minutes have changed since last reading
-#define PCPS_ST_BUSY 0x01 /**< the clock is busy filling the output FIFO */
-#define PCPS_ST_IRQF 0x02 /**< the clock has generated an IRQ on the PC bus (ISA only)*/
-#define PCPS_ST_MOD 0x20 /**< the raw demodulated DCF77 signal */
-#define PCPS_ST_SEC 0x40 /**< seconds have changed since last reading */
-#define PCPS_ST_MIN 0x80 /**< minutes have changed since last reading */
+/** @} anchor PCPS_STATUS_PORT_BIT_MASKS */
+
+/** @} defgroup group_status_port */
-/** @} group_status_port */
/**
* A format string to be used with snprintb() which is available on some Unix
@@ -368,512 +422,485 @@ typedef uint8_t PCPS_STATUS_PORT; /**< see @ref group_status_port "Bitmask" */
-/** @defgroup group_cmd_bytes Command bytes used to access the device
-
- The commands described below are used to access computer peripherals
- manufactured by Meinberg.
-
- The header files pcpsdev.h and pcpsdrvr.h contain macros which can be
- used to check if a detected device supports a certain feature or command.
- If checking is required then the name of the macro is given in the
- comments below.
-
- Some commands expect parameters to be passed to the board. In that
- case, the board returns the number of parameter bytes expected when
- the command code is passed. Every parameter byte has to be supplied
- to the board exactly like a command byte.
- Refer to function pcps_write_data() and the macro _pcps_write_var()
- for details.
-
-
- - #PCPS_GIVE_TIME<br>
- Return a PCPS_TIME structure with current date,
- time and status. Supported by all clocks.
-
- - #PCPS_GIVE_TIME_NOCLEAR<br>
- Same as #PCPS_GIVE_TIME but the bits #PCPS_ST_SEC
- and #PCPS_ST_MIN (see pcpsdev.h) of the status
- port are not cleared.
- Supported by all clocks except PC31/PS31 with
- firmware version older than v3.0.
- This is mainly used by the DOS TSR and should
- not be used in other environments.
-
- - #PCPS_GIVE_SYNC_TIME<br>
- Return a ::PCPS_TIME structure with date and time
- of last synchronization of the clock or
- the last time set via the interface.
- _pcps_has_sync_time() checks whether supported.
-
- - #PCPS_GIVE_HR_TIME<br>
- Return a PCPS_HR_TIME structure with current
- date, time and status. This command should be
- used to read the clock with higher resolution.
- _pcps_has_hr_time() checks whether supported.
-
- - #PCPS_GIVE_IRIG_TIME<br>
- Return a PCPS_IRIG_TIME structure with day-of-year,
- time and status as decoded from the IRIG signal.
- _pcps_has_irig_time() checks whether supported.
-
- - #PCPS_SET_TIME<br>
- Set the board date, time and status. This
- command expects sizeof( ::PCPS_STIME ) parameter
- bytes.
- _pcps_can_set_time() checks whether supported.
-
- - #PCPS_SET_EVENT_TIME<br>
- Send a high resolution time stamp to the clock to
- configure a UTC time when the clock shall generate
- some event. This command expects a PCPS_TIME_STAMP
- parameter.
- _pcps_has_event_time() checks whether supported.
- (requires custom GPS CERN firmware)
-
- - #PCPS_IRQ_NONE<br>
- Disable the board's hardware IRQ<br>
- - #PCPS_IRQ_1_SEC<br>
- Enable hardware IRQs once per second<br>
- - #PCPS_IRQ_1_MIN<br>
- Enable hardware IRQs once per minute<br>
- - #PCPS_IRQ_10_MIN<br>
- Enable hardware IRQs once per 10 minutes<br>
- - #PCPS_IRQ_30_MIN<br>
- Enable hardware IRQs once per 30 minutes<br>
-
- - #PCPS_GET_SERIAL<br>
- #PCPS_SET_SERIAL<br>
- These commands read or set the configuration
- of a clock's serial port COM0. The commands
- expect PCPS_SERIAL_BYTES parameter bytes and
- should be used preferably with the DCF77
- clocks which have only one COM port.
- _pcps_has_serial() checks whether supported.
- Recent GPS clocks' COM ports should be cfg'd
- using the structures RECEIVER_INFO, PORT_INFO,
- and STR_TYPE_INFO.
- _pcps_has_receiver_info() checks whether
- these are supported. If they are not, then
- the code #PC_GPS_PORT_PARM together with the
- #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA
- commands should be used.
-
- - #PCPS_GET_TZCODE<br>
- #PCPS_SET_TZCODE<br>
- These commands read or set a DCF77 clock's
- time zone code and should be used preferably
- with the newer DCF77 clocks which have limited
- support of different time zones.
- _pcps_has_tzcode() checks whether supported.
- A GPS clock's time zone must be cfg'd using
- the code #PC_GPS_TZDL together with the
- #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA
- commands.
-
- - #PCPS_GET_PCPS_TZDL<br>
- #PCPS_SET_PCPS_TZDL<br>
- These commands read or set a DCF77 clock's
- time zone / daylight saving configuration.
- _pcps_has_pcps_tzdl() checks whether supported.
- A GPS clock's time zone must be cfg'd using
- the code #PC_GPS_TZDL together with the
- #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA
- commands.
-
- - #PCPS_GET_REF_OFFS<br>
- #PCPS_SET_REF_OFFS<br>
- These commands can be used to configure the
- reference time offset from UTC for clocks
- which can't determine the offset automatically,
- e.g. from an IRIG input signal.
- _pcps_has_ref_offs() checks whether supported.
-
- - #PCPS_GET_OPT_INFO<br>
- #PCPS_SET_OPT_SETTINGS<br>
- These commands can be used to configure some
- optional settings, controlled by flags.
- When reading, the clock returns a MBG_OPT_INFO
- structure which contains the supported values,
- plus the current settings.
- When writing, clocks accepts a MBG_OPT_SETTINGS
- structure only which contain the desired settings
- of the supported flags only.
- _pcps_has_opt_flags() checks whether supported.
-
- - #PCPS_GET_IRIG_RX_INFO<br>
- #PCPS_SET_IRIG_RX_SETTINGS<br>
- #PCPS_GET_IRIG_TX_INFO<br>
- #PCPS_SET_IRIG_TX_SETTINGS<br>
- These commands can be used to configure IRIG
- inputs and outputs.<br>
- When reading, the clock returns an IRIG_INFO
- structure which contains the supported values,
- plus the current settings.<br>
- When writing, clocks accepts an IRIG_SETTINGS
- structure only which contain the desired settings
- only. _pcps_is_irig_rx() and _pcps_is_irig_tx()
- check whether supported.
-
- - #PCPS_GET_IRIG_CTRL_BITS<br>
- This command can be used to retrieve the control function
- bits of the latest IRIG input frame. Those bits may carry
- some well-known information as in the IEEE1344 code, but
- may also contain some customized information, depending on
- the IRIG frame type and the configuration of the IRIG generator.
- So these bits are returned as-is and must be interpreted
- by the application.
- _pcps_has_irig_ctrl_bits() checks whether supported.
-
- - #PCPS_GET_SYNTH<br>
- #PCPS_SET_SYNTH<br>
- #PCPS_GET_SYNTH_STATE<br>
- These commands can be used to configure an on-board
- frequency synthesizer and query the synthesizer
- status. The commands are only supported if the board
- supports the RECEIVER_INFO structure and the flag
- #GPS_HAS_SYNTH is set in the RECEIVER_INFO::features.
- _pcps_has_synth() checks whether supported.
- The structures SYNTH and SYNTH_STATE used with these
- commands are defined in gpsdefs.h.
-
- - #PCPS_GIVE_FW_ID_1<br>
- #PCPS_GIVE_FW_ID_2<br>
- Returns the first/second block of PCPS_FIFO_SIZE
- characters of the firmware ID string. These
- commands can be used to check if the board
- responds properly. This is done by the clock
- detection functions.
-
- - #PCPS_GIVE_SERNUM<br>
- Returns PCPS_FIFO_SIZE characters of the
- clock's serial number.
- _pcps_has_sernum() checks whether supported.
-
- - #PCPS_GENERIC_IO<br>
- Generic I/O read and write. Can be used to query
- specific data, e.g. a selected element of an array.
- _pcps_has_generic_io() checks whether supported.
-
- - #PCPS_GET_DEBUG_STATUS<br>
- This command reads a MBG_DEBUG_STATUS structure
- which represents the internal status of the
- IRIG decoder and some additional debug info.
- _pcps_has_debug_status() checks whether supported.
-
- - #PCPS_READ_GPS_DATA<br>
- #PCPS_WRITE_GPS_DATA<br>
- These commands are used by the functions
- pcps_read_gps_data() and pcps_write_gps_data()
- to read or write large data structures to
- Meinberg GPS plug-in clocks.
- _pcps_is_gps() checks whether supported.
-
- - #PCPS_CLR_UCAP_BUFF<br>
- Clear a clock's time capture buffer.
- _pcps_can_clr_ucap_buff() checks whether
- supported.
-
- - #PCPS_GIVE_UCAP_ENTRIES<br>
- Read a PCPS_UCAP_ENTRIES structure which
- reports the max number of entries and the
- currently used number of entries in the
- user capture buffer.
- _pcps_has_ucap() checks whether supported.
-
- - #PCPS_GIVE_UCAP_EVENT<br>
- Read capture events using a PCPS_HR_TIME
- structure. This is faster than reading using the
- GPS command #PC_GPS_UCAP. If no capture event is
- available then the structure is filled with 0s.
- _pcps_has_ucap() checks whether supported.
-
- - #PCPS_GET_CORR_INFO<br>
- Read PZF correlation info using a CORR_INFO
- structure.
- _pcps_has_pzf() checks whether supported.
-
- - #PCPS_GET_TR_DISTANCE<br>
- #PCPS_SET_TR_DISTANCE<br>
- Read or write distance from the RF transmitter.
- This is used to compensate the RF propagation delay
- for PZF receivers.
- _pcps_has_tr_distance() checks whether supported.
-
- - #PCPS_CLR_EVT_LOG<br>
- Clear on-board event log.
- _pcps_has_evt_log() checks whether supported.
-
- - #PCPS_NUM_EVT_LOG_ENTRIES<br>
- Read max number of num event log entries which can
- be saved on the board, and how many entries actually
- have been saved.
- _pcps_has_evt_log() checks whether supported.
-
- - #PCPS_FIRST_EVT_LOG_ENTRY<br>
- - #PCPS_NEXT_EVT_LOG_ENTRY<br>
- Read first (oldest) or next event log entry.
- _pcps_has_evt_log() checks whether supported.
-
- - #PCPS_FORCE_RESET<br>
- Resets the microprocessor on the device. This is
- for special test scenarios only and should not be
- used by standard applications since this may lock up
- the PC.
-
- The command codes listed above are defined below.
-
- @{ */
-
-
-#if _IS_MBG_FIRMWARE //##++
-
-// These group codes are obsolete and should be removed.
-// The explicite command codes defined below should be used instead.
-#define PCPS_GIVE_TIME_GROUP 0x00
-#define PCPS_SET_TIME_GROUP 0x10
-#define PCPS_IRQ_GROUP 0x20
-#define PCPS_CFG_GROUP 0x30
-#define PCPS_GIVE_DATA_GROUP 0x40
-#define PCPS_GPS_DATA_GROUP 0x50
-#define PCPS_CTRL_GROUP 0x60
-#define PCPS_CFG2_GROUP 0x70
-
-#endif
-
-
+/**
+ * @brief Command codes used to communicate with bus level devices
+ *
+ * The commands described below are used to access computer peripherals
+ * manufactured by Meinberg.
+ *
+ * The header files pcpsdev.h and pcpsdrvr.h contain macros which can be
+ * used to check if a detected device supports a certain feature or command.
+ * If checking is required then the name of the macro is given in the
+ * comments associated with the command codes.
+ *
+ * Some commands expect parameters to be passed to the board. In that
+ * case, the board returns the number of parameter bytes expected when
+ * the command code is passed. Every parameter byte has to be supplied
+ * to the board exactly like a command byte.
+ *
+ * Refer to function pcps_write_data() and the macro _pcps_write_var()
+ * for details.
+ *
+ * - #PCPS_GIVE_TIME<br>
+ * Return a PCPS_TIME structure with current date,
+ * time and status. Supported by all clocks.
+ *
+ * - #PCPS_GIVE_TIME_NOCLEAR<br>
+ * Same as #PCPS_GIVE_TIME but the bits #PCPS_ST_SEC
+ * and #PCPS_ST_MIN (see pcpsdev.h) of the status
+ * port are not cleared.
+ * Supported by all clocks except PC31/PS31 with
+ * firmware version older than v3.0.
+ * This is mainly used by the DOS TSR and should
+ * not be used in other environments.
+ *
+ * - #PCPS_GIVE_SYNC_TIME<br>
+ * Return a ::PCPS_TIME structure with date and time
+ * of last synchronization of the clock or
+ * the last time set via the interface.
+ * _pcps_has_sync_time() checks whether supported.
+ *
+ * - #PCPS_GIVE_HR_TIME<br>
+ * Return a PCPS_HR_TIME structure with current
+ * date, time and status. This command should be
+ * used to read the clock with higher resolution.
+ * _pcps_has_hr_time() checks whether supported.
+ *
+ * - #PCPS_GIVE_IRIG_TIME<br>
+ * Return a PCPS_IRIG_TIME structure with day-of-year,
+ * time and status as decoded from the IRIG signal.
+ * _pcps_has_irig_time() checks whether supported.
+ *
+ * - #PCPS_SET_TIME<br>
+ * Set the board date, time and status. This
+ * command expects sizeof( ::PCPS_STIME ) parameter
+ * bytes.
+ * _pcps_can_set_time() checks whether supported.
+ *
+ * - #PCPS_SET_EVENT_TIME<br>
+ * Send a high resolution time stamp to the clock to
+ * configure a %UTC time when the clock shall generate
+ * some event. This command expects a PCPS_TIME_STAMP
+ * parameter.
+ * _pcps_has_event_time() checks whether supported.
+ * (requires custom GPS CERN firmware)
+ *
+ * - #PCPS_IRQ_NONE<br>
+ * Disable the board's hardware IRQ<br>
+ * - #PCPS_IRQ_1_SEC<br>
+ * Enable hardware IRQs once per second<br>
+ * - #PCPS_IRQ_1_MIN<br>
+ * Enable hardware IRQs once per minute<br>
+ * - #PCPS_IRQ_10_MIN<br>
+ * Enable hardware IRQs once per 10 minutes<br>
+ * - #PCPS_IRQ_30_MIN<br>
+ * Enable hardware IRQs once per 30 minutes<br>
+ *
+ * - #PCPS_GET_SERIAL<br>
+ * #PCPS_SET_SERIAL<br>
+ * These commands read or set the configuration
+ * of a clock's serial port COM0. The commands
+ * expect PCPS_SERIAL_BYTES parameter bytes and
+ * should be used preferably with the DCF77
+ * clocks which have only one COM port.
+ * _pcps_has_serial() checks whether supported.
+ * Recent GPS clocks' COM ports should be cfg'd
+ * using the structures RECEIVER_INFO, PORT_INFO,
+ * and STR_TYPE_INFO.
+ * _pcps_has_receiver_info() checks whether
+ * these are supported. If they are not, then
+ * the code #PC_GPS_PORT_PARM together with the
+ * #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA
+ * commands should be used.
+ *
+ * - #PCPS_GET_TZCODE<br>
+ * #PCPS_SET_TZCODE<br>
+ * These commands read or set a DCF77 clock's
+ * time zone code and should be used preferably
+ * with the newer DCF77 clocks which have limited
+ * support of different time zones.
+ * _pcps_has_tzcode() checks whether supported.
+ * A GPS clock's time zone must be cfg'd using
+ * the code #PC_GPS_TZDL together with the
+ * #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA
+ * commands.
+ *
+ * - #PCPS_GET_PCPS_TZDL<br>
+ * #PCPS_SET_PCPS_TZDL<br>
+ * These commands read or set a DCF77 clock's
+ * time zone / daylight saving configuration.
+ * _pcps_has_pcps_tzdl() checks whether supported.
+ * A GPS clock's time zone must be cfg'd using
+ * the code #PC_GPS_TZDL together with the
+ * #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA
+ * commands.
+ *
+ * - #PCPS_GET_REF_OFFS<br>
+ * #PCPS_SET_REF_OFFS<br>
+ * These commands can be used to configure the
+ * reference time offset from %UTC for clocks
+ * which can't determine the offset automatically,
+ * e.g. from an IRIG input signal.
+ * _pcps_has_ref_offs() checks whether supported.
+ *
+ * - #PCPS_GET_OPT_INFO<br>
+ * #PCPS_SET_OPT_SETTINGS<br>
+ * These commands can be used to configure some
+ * optional settings, controlled by flags.
+ * When reading, the clock returns a MBG_OPT_INFO
+ * structure which contains the supported values,
+ * plus the current settings.
+ * When writing, clocks accepts a MBG_OPT_SETTINGS
+ * structure only which contain the desired settings
+ * of the supported flags only.
+ * _pcps_has_opt_flags() checks whether supported.
+ *
+ * - #PCPS_GET_IRIG_RX_INFO<br>
+ * #PCPS_SET_IRIG_RX_SETTINGS<br>
+ * #PCPS_GET_IRIG_TX_INFO<br>
+ * #PCPS_SET_IRIG_TX_SETTINGS<br>
+ * These commands can be used to configure IRIG
+ * inputs and outputs.<br>
+ * When reading, the clock returns an IRIG_INFO
+ * structure which contains the supported values,
+ * plus the current settings.<br>
+ * When writing, clocks accepts an IRIG_SETTINGS
+ * structure only which contain the desired settings
+ * only. _pcps_is_irig_rx() and _pcps_is_irig_tx()
+ * check whether supported.
+ *
+ * - #PCPS_GET_IRIG_CTRL_BITS<br>
+ * This command can be used to retrieve the control function
+ * bits of the latest IRIG input frame. Those bits may carry
+ * some well-known information as in the IEEE1344 code, but
+ * may also contain some customized information, depending on
+ * the IRIG frame type and the configuration of the IRIG generator.
+ * So these bits are returned as-is and must be interpreted
+ * by the application.
+ * _pcps_has_irig_ctrl_bits() checks whether supported.
+ *
+ * - #PCPS_GET_SYNTH<br>
+ * #PCPS_SET_SYNTH<br>
+ * #PCPS_GET_SYNTH_STATE<br>
+ * These commands can be used to configure an on-board
+ * frequency synthesizer and query the synthesizer
+ * status. The commands are only supported if the board
+ * supports the RECEIVER_INFO structure and the flag
+ * #GPS_HAS_SYNTH is set in the RECEIVER_INFO::features.
+ * _pcps_has_synth() checks whether supported.
+ * The structures SYNTH and SYNTH_STATE used with these
+ * commands are defined in gpsdefs.h.
+ *
+ * - #PCPS_GIVE_FW_ID_1<br>
+ * #PCPS_GIVE_FW_ID_2<br>
+ * Returns the first/second block of PCPS_FIFO_SIZE
+ * characters of the firmware ID string. These
+ * commands can be used to check if the board
+ * responds properly. This is done by the clock
+ * detection functions.
+ *
+ * - #PCPS_GIVE_SERNUM<br>
+ * Returns PCPS_FIFO_SIZE characters of the
+ * clock's serial number.
+ * _pcps_has_sernum() checks whether supported.
+ *
+ * - #PCPS_GENERIC_IO<br>
+ * Generic I/O read and write. Can be used to query
+ * specific data, e.g. a selected element of an array.
+ * _pcps_has_generic_io() checks whether supported.
+ *
+ * - #PCPS_GET_DEBUG_STATUS<br>
+ * This command reads a MBG_DEBUG_STATUS structure
+ * which represents the internal status of the
+ * IRIG decoder and some additional debug info.
+ * _pcps_has_debug_status() checks whether supported.
+ *
+ * - #PCPS_READ_GPS_DATA<br>
+ * #PCPS_WRITE_GPS_DATA<br>
+ * These commands are used by the functions
+ * pcps_read_gps_data() and pcps_write_gps_data()
+ * to read or write large data structures to
+ * Meinberg GPS plug-in clocks.
+ * _pcps_is_gps() checks whether supported.
+ *
+ * - #PCPS_CLR_UCAP_BUFF<br>
+ * Clear a clock's time capture buffer.
+ * _pcps_can_clr_ucap_buff() checks whether
+ * supported.
+ *
+ * - #PCPS_GIVE_UCAP_ENTRIES<br>
+ * Read a PCPS_UCAP_ENTRIES structure which
+ * reports the max number of entries and the
+ * currently used number of entries in the
+ * user capture buffer.
+ * _pcps_has_ucap() checks whether supported.
+ *
+ * - #PCPS_GIVE_UCAP_EVENT<br>
+ * Read capture events using a PCPS_HR_TIME
+ * structure. This is faster than reading using the
+ * GPS command #PC_GPS_UCAP. If no capture event is
+ * available then the structure is filled with 0s.
+ * _pcps_has_ucap() checks whether supported.
+ *
+ * - #PCPS_GET_CORR_INFO<br>
+ * Read PZF correlation info using a CORR_INFO
+ * structure.
+ * _pcps_has_pzf() checks whether supported.
+ *
+ * - #PCPS_GET_TR_DISTANCE<br>
+ * #PCPS_SET_TR_DISTANCE<br>
+ * Read or write distance from the RF transmitter.
+ * This is used to compensate the RF propagation delay
+ * for PZF receivers.
+ * _pcps_has_tr_distance() checks whether supported.
+ *
+ * - #PCPS_CLR_EVT_LOG<br>
+ * Clear on-board event log.
+ * _pcps_has_evt_log() checks whether supported.
+ *
+ * - #PCPS_NUM_EVT_LOG_ENTRIES<br>
+ * Read max number of num event log entries which can
+ * be saved on the board, and how many entries actually
+ * have been saved.
+ * _pcps_has_evt_log() checks whether supported.
+ *
+ * - #PCPS_FIRST_EVT_LOG_ENTRY<br>
+ * - #PCPS_NEXT_EVT_LOG_ENTRY<br>
+ * Read first (oldest) or next event log entry.
+ * _pcps_has_evt_log() checks whether supported.
+ *
+ * - #PCPS_FORCE_RESET<br>
+ * Resets the microprocessor on the device. This is
+ * for special test scenarios only and should not be
+ * used by standard applications since this may lock up
+ * the computer.
+ *
+ * @anchor PCPS_CMD_CODES @{ */
-#define PCPS_GIVE_TIME 0x00
-#define PCPS_GIVE_TIME_NOCLEAR 0x01
-#define PCPS_GIVE_SYNC_TIME 0x02 // only supported if _pcps_has_sync_time()
-#define PCPS_GIVE_HR_TIME 0x03 // only supported if _pcps_has_hr_time()
-#define PCPS_GIVE_IRIG_TIME 0x04 // only supported if _pcps_has_irig_time()
+#define PCPS_GIVE_TIME 0x00 ///< (r-) read current time in ::PCPS_TIME format
+#define PCPS_GIVE_TIME_NOCLEAR 0x01 ///< (r-) read current time in ::PCPS_TIME format, don't clear sec and min flags
+#define PCPS_GIVE_SYNC_TIME 0x02 ///< (r-) read last sync time as ::PCPS_TIME, only if ::_pcps_has_sync_time()
+#define PCPS_GIVE_HR_TIME 0x03 ///< (r-) read high res. time as ::PCPS_HR_TIME, only if ::_pcps_has_hr_time()
+#define PCPS_GIVE_IRIG_TIME 0x04 ///< (r-) read raw IRIG time as ::PCPS_IRIG_TIME, only if ::_pcps_has_irig_time()
-#define PCPS_SET_TIME 0x10
+#define PCPS_SET_TIME 0x10 ///< (-w) set on-board time, see ::PCPS_STIME
/* on error, return PCPS_ERR_STIME */
-/* Attention: The code below can be used EXCLUSIVELY */
-/* with a GPS167PCI with customized CERN firmware !! */
-/* _pcps_has_event_time() checks whether supported. */
-#define PCPS_SET_EVENT_TIME 0x14
+#define PCPS_SET_EVENT_TIME 0x14 ///< (-w) write event time as ::PCPS_TIME_STAMP, only if ::_pcps_has_event_time()
-#define PCPS_IRQ_NONE 0x20
-#define PCPS_IRQ_1_SEC 0x21
-#define PCPS_IRQ_1_MIN 0x22
-#define PCPS_IRQ_10_MIN 0x24
-#define PCPS_IRQ_30_MIN 0x28
+#define PCPS_IRQ_NONE 0x20 ///< (-w) disable IRQs
+#define PCPS_IRQ_1_SEC 0x21 ///< (-w) enable IRQ per 1 second
+#define PCPS_IRQ_1_MIN 0x22 ///< (-w) enable IRQ per 1 minute (deprecated)
+#define PCPS_IRQ_10_MIN 0x24 ///< (-w) enable IRQ per 10 minutes (deprecated)
+#define PCPS_IRQ_30_MIN 0x28 ///< (-w) enable IRQ per 10 minutes (deprecated)
-#define PCPS_GET_SERIAL 0x30
-#define PCPS_SET_SERIAL 0x31
+#define PCPS_GET_SERIAL 0x30 ///< (r-) read serial settings as ::PCPS_SERIAL, superseded by ::PC_GPS_ALL_PORT_INFO
+#define PCPS_SET_SERIAL 0x31 ///< (-w) write serial settings as ::PCPS_SERIAL, superseded by ::PC_GPS_PORT_SETTINGS_IDX
/* on error, return PCPS_ERR_CFG */
-typedef uint8_t PCPS_SERIAL;
-
-
-#define PCPS_GET_TZCODE 0x32
-#define PCPS_SET_TZCODE 0x33
+#define PCPS_GET_TZCODE 0x32 ///< (r-) read ::PCPS_TZCODE, only if ::_pcps_has_tzcode()
+#define PCPS_SET_TZCODE 0x33 ///< (-w) write ::PCPS_TZCODE, only if ::_pcps_has_tzcode()
/* on error, return PCPS_ERR_CFG */
-typedef uint8_t PCPS_TZCODE;
-
-/* the following codes are used with the PCPS_TZCODE parameter: */
-enum
-{
- PCPS_TZCODE_CET_CEST, /* default as broadcasted by DCF77 (UTC+1h/UTC+2h) */
- PCPS_TZCODE_CET, /* always CET (UTC+1h), discard DST */
- PCPS_TZCODE_UTC, /* always UTC */
- PCPS_TZCODE_EET_EEST, /* East European Time, CET/CEST + 1h */
- N_PCPS_TZCODE /* the number of valid codes */
-};
-
-/* the definitions below are for compatibily only: */
-#define PCPS_TZCODE_MEZMESZ PCPS_TZCODE_CET_CEST
-#define PCPS_TZCODE_MEZ PCPS_TZCODE_CET
-#define PCPS_TZCODE_OEZ PCPS_TZCODE_EET_EEST
-
-
-#define PCPS_GET_PCPS_TZDL 0x34
-#define PCPS_SET_PCPS_TZDL 0x35
+#define PCPS_GET_PCPS_TZDL 0x34 ///< (r-) read ::PCPS_TZDL, only if ::_pcps_has_pcps_tzdl()
+#define PCPS_SET_PCPS_TZDL 0x35 ///< (-w) write ::PCPS_TZDL, only if ::_pcps_has_pcps_tzdl()
/* on error, return PCPS_ERR_CFG */
-
-/**
- * The structures below can be used to configure a clock's
- * time zone/daylight saving setting. This structure is shorter
- * than the TZDL structure used with GPS clocks.
- */
-typedef struct
-{
- // The year_or_wday field below contains the full year number
- // or 0..6 == Sun..Sat if the DL_AUTO_FLAG is set; see below.
- uint16_t year_or_wday;
- uint8_t month;
- uint8_t mday;
- uint8_t hour;
- uint8_t min;
-} PCPS_DL_ONOFF;
-
-#define _mbg_swab_pcps_dl_onoff( _p ) \
-{ \
- _mbg_swab16( &(_p)->year_or_wday ); \
-}
-
-/**
- * If the field year_or_wday is or'ed with the constant DL_AUTO_FLAG
- * defined below then this means that start and end of daylight saving
- * time shall be computed automatically for each year. In this case
- * the remaining bits represent the day-of-week after the specified
- * mday/month at which the change shall occur. If that flag is not set
- * then the field contains the full four-digit year number and the
- * mday/month values specify the exact date of that year.
- */
-#define DL_AUTO_FLAG 0x8000 // also defined in gpsdefs.h
-
-typedef struct
-{
- int16_t offs; /**< offset from UTC to local time [min] */
- int16_t offs_dl; /**< additional offset if DST enabled [min] */
- PCPS_DL_ONOFF tm_on; /**< date/time when daylight saving starts */
- PCPS_DL_ONOFF tm_off; /**< date/time when daylight saving ends */
-} PCPS_TZDL;
-
-#define _mbg_swab_pcps_tzdl( _p ) \
-{ \
- _mbg_swab16( &(_p)->offs ); \
- _mbg_swab16( &(_p)->offs_dl ); \
- _mbg_swab_pcps_dl_onoff( &(_p)->tm_on ); \
- _mbg_swab_pcps_dl_onoff( &(_p)->tm_off ); \
-}
-
-
-
-#define PCPS_GET_REF_OFFS 0x36
-#define PCPS_SET_REF_OFFS 0x37
+#define PCPS_GET_REF_OFFS 0x36 ///< (r-) read ::MBG_REF_OFFS, only if ::_pcps_has_ref_offs()
+#define PCPS_SET_REF_OFFS 0x37 ///< (-w) write ::MBG_REF_OFFS, only if ::_pcps_has_ref_offs()
/* on error, return PCPS_ERR_CFG */
-/* The associated type MBG_REF_OFFS is defined in gpsdefs.h. */
-
-
-#define PCPS_GET_OPT_INFO 0x38
-#define PCPS_SET_OPT_SETTINGS 0x39
+#define PCPS_GET_OPT_INFO 0x38 ///< (r-) read ::MBG_OPT_INFO, only if ::_pcps_has_opt_flags()
+#define PCPS_SET_OPT_SETTINGS 0x39 ///< (-w) write ::MBG_OPT_SETTINGS, only if ::_pcps_has_opt_flags()
/* on error, return PCPS_ERR_CFG */
-/* The associated structures MBG_OPT_INFO and MBG_OPT_SETTINGS
- are defined in gpsdefs.h. */
-
-
-#define PCPS_GET_IRIG_RX_INFO 0x3A
-#define PCPS_SET_IRIG_RX_SETTINGS 0x3B
+#define PCPS_GET_IRIG_RX_INFO 0x3A ///< (r-) read ::IRIG_INFO, only if ::_pcps_is_irig_rx()
+#define PCPS_SET_IRIG_RX_SETTINGS 0x3B ///< (-w) write ::IRIG_SETTINGS, only if ::_pcps_is_irig_rx()
/* on error, return PCPS_ERR_CFG */
-#define PCPS_GET_IRIG_TX_INFO 0x3C
-#define PCPS_SET_IRIG_TX_SETTINGS 0x3D
+#define PCPS_GET_IRIG_TX_INFO 0x3C ///< (r-) read ::IRIG_INFO, only if ::_pcps_has_irig_tx()
+#define PCPS_SET_IRIG_TX_SETTINGS 0x3D ///< (-w) write ::IRIG_SETTINGS, only if ::_pcps_has_irig_tx()
/* on error, return PCPS_ERR_CFG */
-/* The associated structures IRIG_INFO and IRIG_SETTINGS
- are defined in gpsdefs.h. */
+#define PCPS_GET_SYNTH 0x3E ///< (r-) read ::SYNTH, only if ::_pcps_has_synth()
+#define PCPS_SET_SYNTH 0x3F ///< (-w) write ::SYNTH, only if ::_pcps_has_synth()
+/* on error, return PCPS_ERR_CFG */
+#define PCPS_GIVE_FW_ID_1 0x40 ///< (r-) get first ::PCPS_FIFO_SIZE chars of firmware ID
+#define PCPS_GIVE_FW_ID_2 0x41 ///< (r-) get last ::PCPS_FIFO_SIZE chars of firmware ID
+#define PCPS_GIVE_SERNUM 0x42 ///< (r-) read serial number as ::PCPS_SN_STR, only if _pcps_has_sernum()
+#define PCPS_GENERIC_IO 0x43 ///< (rw) see pcps_generic_io() or _mbgdevio_gen_io()
+#define PCPS_GET_SYNTH_STATE 0x44 ///< (r-) read ::SYNTH_STATE, only if _pcps_has_synth()
+#define PCPS_GET_IRIG_CTRL_BITS 0x45 ///< (r-) read ::MBG_IRIG_CTRL_BITS, only if ::_pcps_has_irig_ctrl_bits()
+#define PCPS_GET_RAW_IRIG_DATA 0x46 ///< (r-) read ::MBG_RAW_IRIG_DATA, only if ::_pcps_has_raw_irig_data()
-#define PCPS_GET_SYNTH 0x3E
-#define PCPS_SET_SYNTH 0x3F
-/* on error, return PCPS_ERR_CFG */
+#define PCPS_GET_STATUS_PORT 0x4B ///< (r-) read ::PCPS_STATUS_PORT
+#define PCPS_GET_DEBUG_STATUS 0x4C ///< (r-) read ::MBG_DEBUG_STATUS, only if _pcps_has_debug_status()
-/* The associated structure SYNTH is defined in gpsdefs.h. */
+// Command codes 0x4D, 0x4E, and 0x4F are reserved.
+#define PCPS_READ_GPS_DATA 0x50 ///< (r-) read large data structure, see ::PC_GPS_CMD_CODES
+#define PCPS_WRITE_GPS_DATA 0x51 ///< (-w) write large data structure, see ::PC_GPS_CMD_CODES
-#define PCPS_GIVE_FW_ID_1 0x40
-#define PCPS_GIVE_FW_ID_2 0x41
-#define PCPS_GIVE_SERNUM 0x42
-#define PCPS_GENERIC_IO 0x43
-#define PCPS_GET_SYNTH_STATE 0x44
-#define PCPS_GET_IRIG_CTRL_BITS 0x45
-#define PCPS_GET_RAW_IRIG_DATA 0x46
+#define PCPS_CLR_UCAP_BUFF 0x60 ///< (-w) no param., clear on-board capture FIFO, only if ::_pcps_has_ucap()
+#define PCPS_GIVE_UCAP_ENTRIES 0x61 ///< (r-) read ::PCPS_UCAP_ENTRIES, only if ::_pcps_has_ucap()
+#define PCPS_GIVE_UCAP_EVENT 0x62 ///< (r-) return oldes event as ::PCPS_HR_TIME, only if ::_pcps_has_ucap()
+#define PCPS_GET_CORR_INFO 0x63 ///< (r-) read ::CORR_INFO structure, only if _pcps_has_pzf()
+#define PCPS_GET_TR_DISTANCE 0x64 ///< (r-) read ::TR_DISTANCE, only if _pcps_has_tr_distance()
+#define PCPS_SET_TR_DISTANCE 0x65 ///< (-w) write ::TR_DISTANCE, only if _pcps_has_tr_distance()
+#define PCPS_CLR_EVT_LOG 0x66 ///< (-w) write clear on-board event log, only if _pcps_has_evt_log()
+#define PCPS_NUM_EVT_LOG_ENTRIES 0x67 ///< (r-) read ::MBG_NUM_EVT_LOG_ENTRIES, only if _pcps_has_evt_log()
+#define PCPS_FIRST_EVT_LOG_ENTRY 0x68 ///< (r-) read first (oldest) ::MBG_EVT_LOG_ENTRY, only if _pcps_has_evt_log()
+#define PCPS_NEXT_EVT_LOG_ENTRY 0x69 ///< (r-) read next ::MBG_EVT_LOG_ENTRY, only if _pcps_has_evt_log()
-#define PCPS_GET_STATUS_PORT 0x4B
-#define PCPS_GET_DEBUG_STATUS 0x4C
-// expects sizeof( MBG_DEBUG_STATUS ) chars
+#define PCPS_FORCE_RESET 0x80 ///< (-w) no param., reset the device (this can lockup the computer!!)
-// Command codes 0x4D, 0x4E, and 0x4F are reserved.
+// Command codes 0xF0 through 0xFF are reserved.
+/** @} anchor PCPS_CMD_CODES */
-#define PCPS_READ_GPS_DATA 0x50
-#define PCPS_WRITE_GPS_DATA 0x51
-#define PCPS_CLR_UCAP_BUFF 0x60
-#define PCPS_GIVE_UCAP_ENTRIES 0x61
-#define PCPS_GIVE_UCAP_EVENT 0x62
-typedef struct
-{
- uint32_t used; /**< the number of saved capture events */
- uint32_t max; /**< capture buffer size */
-} PCPS_UCAP_ENTRIES;
+#if _IS_MBG_FIRMWARE //##++
-#define _mbg_swab_pcps_ucap_entries( _p ) \
-{ \
- _mbg_swab32( &(_p)->used ); \
- _mbg_swab32( &(_p)->max ); \
-}
+/**
+ * @brief Deprecated command group codes
+ *
+ * @deprecated These group codes are deprecated.
+ * They should not be used anymore but removed
+ * from existing source code. The explicite command
+ * codes @ref PCPS_CMD_CODES should be used instead.
+ *
+ * @anchor PCPS_CMD_GROUP_CODES @{ */
+#define PCPS_GIVE_TIME_GROUP 0x00
+#define PCPS_SET_TIME_GROUP 0x10
+#define PCPS_IRQ_GROUP 0x20
+#define PCPS_CFG_GROUP 0x30
+#define PCPS_GIVE_DATA_GROUP 0x40
+#define PCPS_GPS_DATA_GROUP 0x50
+#define PCPS_CTRL_GROUP 0x60
+#define PCPS_CFG2_GROUP 0x70
+/** @} anchor PCPS_CMD_GROUP_CODES */
-#define PCPS_GET_CORR_INFO 0x63 // read CORR_INFO structure, only if _pcps_has_pzf()
-#define PCPS_GET_TR_DISTANCE 0x64 // read TR_DISTANCE, only if _pcps_has_tr_distance()
-#define PCPS_SET_TR_DISTANCE 0x65 // write TR_DISTANCE, only if _pcps_has_tr_distance()
+#endif // _IS_MBG_FIRMWARE
-#define PCPS_CLR_EVT_LOG 0x66 // clear on-board event log, only if _pcps_has_evt_log()
-#define PCPS_NUM_EVT_LOG_ENTRIES 0x67 // read num event log entries, only if _pcps_has_evt_log()
-#define PCPS_FIRST_EVT_LOG_ENTRY 0x68 // read first (oldest) event log entry, only if _pcps_has_evt_log()
-#define PCPS_NEXT_EVT_LOG_ENTRY 0x69 // read next event log entry, only if _pcps_has_evt_log()
+#if !defined( MBG_CMD_TABLE_EXT )
+ #define MBG_CMD_TABLE_EXT _mbg_cn_table_end()
+#endif
/**
- special -- use with care !
-*/
-#define PCPS_FORCE_RESET 0x80
+ * @brief An initializer for a table of code/name entries of non-GPS commands.
+ *
+ * This can e.g. be assigned to an array of ::MBG_CODE_NAME_TABLE_ENTRY elements
+ * and may be helpful when debugging.
+ */
+#define MBG_CMD_TABLE \
+{ \
+ _mbg_cn_table_entry( PCPS_GIVE_TIME ), /* 00 */ \
+ _mbg_cn_table_entry( PCPS_GIVE_TIME_NOCLEAR ), /* 01 */ \
+ _mbg_cn_table_entry( PCPS_GIVE_SYNC_TIME ), /* 02 */ \
+ _mbg_cn_table_entry( PCPS_GIVE_HR_TIME ), /* 03 */ \
+ _mbg_cn_table_entry( PCPS_GIVE_IRIG_TIME ), /* 04 */ \
+ _mbg_cn_table_entry( PCPS_SET_TIME ), /* 10 */ \
+ _mbg_cn_table_entry( PCPS_SET_EVENT_TIME ), /* 14 */ \
+ _mbg_cn_table_entry( PCPS_IRQ_NONE ), /* 20 */ \
+ _mbg_cn_table_entry( PCPS_IRQ_1_SEC ), /* 21 */ \
+ _mbg_cn_table_entry( PCPS_IRQ_1_MIN ), /* 22 */ \
+ _mbg_cn_table_entry( PCPS_IRQ_10_MIN ), /* 24 */ \
+ _mbg_cn_table_entry( PCPS_IRQ_30_MIN ), /* 28 */ \
+ _mbg_cn_table_entry( PCPS_GET_SERIAL ), /* 30 */ \
+ _mbg_cn_table_entry( PCPS_SET_SERIAL ), /* 31 */ \
+ _mbg_cn_table_entry( PCPS_GET_TZCODE ), /* 32 */ \
+ _mbg_cn_table_entry( PCPS_SET_TZCODE ), /* 33 */ \
+ _mbg_cn_table_entry( PCPS_GET_PCPS_TZDL ), /* 34 */ \
+ _mbg_cn_table_entry( PCPS_SET_PCPS_TZDL ), /* 35 */ \
+ _mbg_cn_table_entry( PCPS_GET_REF_OFFS ), /* 36 */ \
+ _mbg_cn_table_entry( PCPS_SET_REF_OFFS ), /* 37 */ \
+ _mbg_cn_table_entry( PCPS_GET_OPT_INFO ), /* 38 */ \
+ _mbg_cn_table_entry( PCPS_SET_OPT_SETTINGS ), /* 39 */ \
+ _mbg_cn_table_entry( PCPS_GET_IRIG_RX_INFO ), /* 3A */ \
+ _mbg_cn_table_entry( PCPS_SET_IRIG_RX_SETTINGS ), /* 3B */ \
+ _mbg_cn_table_entry( PCPS_GET_IRIG_TX_INFO ), /* 3C */ \
+ _mbg_cn_table_entry( PCPS_SET_IRIG_TX_SETTINGS ), /* 3D */ \
+ _mbg_cn_table_entry( PCPS_GET_SYNTH ), /* 3E */ \
+ _mbg_cn_table_entry( PCPS_SET_SYNTH ), /* 3F */ \
+ _mbg_cn_table_entry( PCPS_GIVE_FW_ID_1 ), /* 40 */ \
+ _mbg_cn_table_entry( PCPS_GIVE_FW_ID_2 ), /* 41 */ \
+ _mbg_cn_table_entry( PCPS_GIVE_SERNUM ), /* 42 */ \
+ _mbg_cn_table_entry( PCPS_GENERIC_IO ), /* 43 */ \
+ _mbg_cn_table_entry( PCPS_GET_SYNTH_STATE ), /* 44 */ \
+ _mbg_cn_table_entry( PCPS_GET_IRIG_CTRL_BITS ), /* 45 */ \
+ _mbg_cn_table_entry( PCPS_GET_RAW_IRIG_DATA ), /* 46 */ \
+ _mbg_cn_table_entry( PCPS_GET_STATUS_PORT ), /* 4B */ \
+ _mbg_cn_table_entry( PCPS_GET_DEBUG_STATUS ), /* 4C */ \
+ _mbg_cn_table_entry( PCPS_READ_GPS_DATA ), /* 50 */ \
+ _mbg_cn_table_entry( PCPS_WRITE_GPS_DATA ), /* 51 */ \
+ _mbg_cn_table_entry( PCPS_CLR_UCAP_BUFF ), /* 60 */ \
+ _mbg_cn_table_entry( PCPS_GIVE_UCAP_ENTRIES ), /* 61 */ \
+ _mbg_cn_table_entry( PCPS_GIVE_UCAP_EVENT ), /* 62 */ \
+ _mbg_cn_table_entry( PCPS_GET_CORR_INFO ), /* 63 */ \
+ _mbg_cn_table_entry( PCPS_GET_TR_DISTANCE ), /* 64 */ \
+ _mbg_cn_table_entry( PCPS_SET_TR_DISTANCE ), /* 65 */ \
+ _mbg_cn_table_entry( PCPS_CLR_EVT_LOG ), /* 66 */ \
+ _mbg_cn_table_entry( PCPS_NUM_EVT_LOG_ENTRIES ), /* 67 */ \
+ _mbg_cn_table_entry( PCPS_FIRST_EVT_LOG_ENTRY ), /* 68 */ \
+ _mbg_cn_table_entry( PCPS_NEXT_EVT_LOG_ENTRY ), /* 69 */ \
+ _mbg_cn_table_entry( PCPS_FORCE_RESET ), /* 80 */ \
+ MBG_CMD_TABLE_EXT, \
+ _mbg_cn_table_end() \
+}
+
-// Command codes 0xF0 through 0xFF are reserved.
-/** @} group_cmd_bytes */
+/**
+ * @brief Bus level command return codes
+ *
+ * Codes returned when commands with parameters have been passed to a device
+ *
+ * @anchor PCPS_LEVEL_CMD_RETURN_CODES @{ */
+#define PCPS_SUCCESS 0 ///< OK, no error
+#define PCPS_ERR_STIME -1 ///< invalid date/time/status passed
+#define PCPS_ERR_CFG -2 ///< invalid parms for a cmd writing config parameters
-/* Codes returned when commands with parameters have been passed */
-/* to the board */
-#define PCPS_SUCCESS 0 /**< OK, no error */
-#define PCPS_ERR_STIME -1 /**< invalid date/time/status passed */
-#define PCPS_ERR_CFG -2 /**< invalid parms for a cmd writing config parameters */
+/** @} anchor PCPS_LEVEL_CMD_RETURN_CODES */
-#ifndef BITMASK
+#if !defined( BITMASK )
#define BITMASK( b ) ( ( 1 << b ) - 1 )
#endif
-/** The size of the plug-in card's on-board FIFO */
+/**
+ * @brief The size of a bus level device's command/data FIFO
+ */
#define PCPS_FIFO_SIZE 16
typedef int8_t PCPS_BUFF[PCPS_FIFO_SIZE];
-#define PCPS_ID_SIZE ( 2 * PCPS_FIFO_SIZE + 1 ) /**< ASCIIZ string */
+#define PCPS_ID_SIZE ( 2 * PCPS_FIFO_SIZE + 1 ) ///< ASCIIZ string
typedef char PCPS_ID_STR[PCPS_ID_SIZE];
-#define PCPS_SN_SIZE ( PCPS_FIFO_SIZE + 1 ) /**< ASCIIZ string */
+#define PCPS_SN_SIZE ( PCPS_FIFO_SIZE + 1 ) ///< ASCIIZ string
typedef char PCPS_SN_STR[PCPS_SN_SIZE];
/**
- * The structure has been introduced to be able to handle
- * high resolution time stamps.
+ * @brief A high resolution time stamp
*/
typedef struct
{
- uint32_t sec; /**< seconds since 1970 (UTC) */
- uint32_t frac; /**< fractions of second ( 0xFFFFFFFF == 0.9999.. sec) */
+ uint32_t sec; ///< seconds since 1970, usually %UTC
+ uint32_t frac; ///< fractions of second ( 0xFFFFFFFF == 0.9999.. sec)
} PCPS_TIME_STAMP;
#define _mbg_swab_pcps_time_stamp( _p ) \
@@ -887,17 +914,17 @@ typedef struct
// Depending on the target environment define a data type
// which can be used to convert binary fractions without
// range overflow.
-#if defined( MBG_TGT_UNIX )
- #define PCPS_HRT_FRAC_CONVERSION_TYPE int64_t
-#elif defined( MBG_TGT_WIN32 )
- #define PCPS_HRT_FRAC_CONVERSION_TYPE int64_t
-#elif defined( __WATCOMC__ ) && ( __WATCOMC__ >= 1100 )
- #define PCPS_HRT_FRAC_CONVERSION_TYPE int64_t
-#else
+#if defined( MBG_TGT_MISSING_64_BIT_TYPES )
#define PCPS_HRT_FRAC_CONVERSION_TYPE double
+#else
+ #define PCPS_HRT_FRAC_CONVERSION_TYPE int64_t
#endif
-// Max value of PCPS_TIME_STAMP::frac + 1 used for scaling
+/**
+ * @brief Constant used to convert ::PCPS_TIME_STAMP::frac values
+ *
+ * Max value of ::PCPS_TIME_STAMP::frac + 1, used for scaling
+ */
#define PCPS_HRT_BIN_FRAC_SCALE ( (PCPS_HRT_FRAC_CONVERSION_TYPE) 4294967296.0 ) // == 0x100000000
@@ -915,11 +942,60 @@ typedef struct
-typedef uint16_t PCPS_TIME_STATUS_X; /**< extended status */
+/**
+ * @brief Extended status code
+ *
+ * Low byte corresponds to ::PCPS_TIME_STATUS, high byte
+ * contains additional flags.
+ *
+ * @see @ref PCPS_TIME_STATUS_FLAGS
+ */
+typedef uint16_t PCPS_TIME_STATUS_X;
#define _mbg_swab_pcps_time_status_x( _p ) _mbg_swab16( _p )
+typedef struct
+{
+ PCPS_TIME_STATUS_X set_mask;
+ PCPS_TIME_STATUS_X clr_mask;
+
+} PCPS_TIME_STATUS_X_MASKS;
+
+#define _mbg_swab_pcps_time_status_x_masks( _p ) \
+{ \
+ _mbg_swab_pcps_time_status_x( &(_p)->set_mask ); \
+ _mbg_swab_pcps_time_status_x( &(_p)->clr_mask ); \
+}
+
+
+
+/**
+ * @brief Definitions used to report a signal strength
+ *
+ * @anchor PCPS_SIG_VAL_DEFS @{ */
+
+/**
+ * @brief A data type used to report the signal value
+ */
+typedef uint8_t PCPS_SIG_VAL;
+
+// The following constants are used to draw a signal bar
+// depending on a DCF77 clock's signal value:
+#define PCPS_SIG_BIAS 55
+#define PCPS_SIG_ERR 1
+#define PCPS_SIG_MIN 20
+#define PCPS_SIG_MAX 68
+
+// These constants are used by non-DCF77 devices to indicate
+// if an input signal is available or not:
+#define PCPS_SIG_LVL_SIG_NOT_AVAIL 0
+#define PCPS_SIG_LVL_SIG_AVAIL 128
+
+/** @} anchor PCPS_SIG_VAL_DEFS */
+
+
+
/**
* The structure has been introduced to be able to read the
* current time with higher resolution of fractions of seconds and
@@ -936,10 +1012,10 @@ typedef uint16_t PCPS_TIME_STATUS_X; /**< extended status */
*/
typedef struct
{
- PCPS_TIME_STAMP tstamp; /**< High resolution time stamp (UTC) */
- int32_t utc_offs; /**< UTC offs [sec] (loc_time = UTC + utc_offs) */
- PCPS_TIME_STATUS_X status; /**< status flags as defined below */
- uint8_t signal; /**< for normal time, the relative RF signal level, for ucap, the channel number */
+ PCPS_TIME_STAMP tstamp; ///< High resolution time stamp (%UTC)
+ int32_t utc_offs; ///< %UTC offs [sec] (loc_time = tstamp + utc_offs)
+ PCPS_TIME_STATUS_X status; ///< status bits, see @ref PCPS_TIME_STATUS_FLAGS
+ PCPS_SIG_VAL signal; ///< signal strength, different meanings, see notes for @ref PCPS_SIG_VAL_DEFS
} PCPS_HR_TIME;
#define _mbg_swab_pcps_hr_time( _p ) \
@@ -950,46 +1026,69 @@ typedef struct
}
+/**
+ * @brief Time synchronization status
+ *
+ * Used by legacy API calls. New API calls provide
+ * an extended status word ::PCPS_TIME_STATUS_X.
+ *
+ * @see ::PCPS_TIME_STATUS_FLAGS_COMMON
+ * @see ::PCPS_TIME_STATUS_X
+ */
typedef uint8_t PCPS_TIME_STATUS;
-/**
- The standard structure used to read times from the board.
- The time has a resultion of 10 ms.
-*/
-typedef struct PCPS_TIME_s
+
+
+/**
+ * @brief Local calendar date and time, plus sync status
+ *
+ * This legacy structure is supported by all devices but has
+ * a time resultion of 10 ms only. For more accurate time stamps
+ * the structures ::PCPS_HR_TIME and ::PCPS_TIME_STAMP should be
+ * used preferably.
+ *
+ * @see ::PCPS_HR_TIME
+ * @see ::PCPS_TIME_STAMP
+ * @see ::PCPS_STIME
+ */
+typedef struct
{
- uint8_t sec100; /**< hundredths of seconds, 0..99 */
- uint8_t sec; /**< seconds, 0..59, or 60 if leap second */
- uint8_t min; /**< minutes, 0..59 */
- uint8_t hour; /**< hours, 0..23 */
-
- uint8_t mday; /**< day of month, 0..31 */
- uint8_t wday; /**< day of week, 1..7, 1 = Monday */
- uint8_t month; /**< month, 1..12 */
- uint8_t year; /**< year of the century, 0..99 */
-
- PCPS_TIME_STATUS status; /**< status bits, see below */
- uint8_t signal; /**< relative signal strength, range depends on device type */
- int8_t offs_utc; /**< [hours], 0 if !_pcps_has_utc_offs() */
+ uint8_t sec100; ///< hundredths of seconds, 0..99
+ uint8_t sec; ///< seconds, 0..59, or 60 if leap second
+ uint8_t min; ///< minutes, 0..59
+ uint8_t hour; ///< hours, 0..23
+
+ uint8_t mday; ///< day of month, 0..31
+ uint8_t wday; ///< day of week, 1..7, 1 = Monday
+ uint8_t month; ///< month, 1..12
+ uint8_t year; ///< year of the century, 0..99
+
+ PCPS_TIME_STATUS status; ///< status bits, see below
+ PCPS_SIG_VAL signal; ///< signal strength, different meanings, see notes for @ref PCPS_SIG_VAL_DEFS
+ int8_t offs_utc; ///< [hours], 0 if !_pcps_has_utc_offs()
} PCPS_TIME;
-/**
- The structure is passed as parameter with the PCPS_SET_TIME cmd
-*/
-typedef struct PCPS_STIME_s
+
+/**
+ * @brief Date time and status used with the ::PCPS_SET_TIME command
+ *
+ * @see ::PCPS_STIME
+ */
+typedef struct
{
- uint8_t sec100; /**< hundredths of seconds, 0..99 */
- uint8_t sec; /**< seconds, 0..59, or 60 if leap second */
- uint8_t min; /**< minutes, 0..59 */
- uint8_t hour; /**< hours, 0..23 */
+ uint8_t sec100; ///< hundredths of seconds, 0..99
+ uint8_t sec; ///< seconds, 0..59, or 60 if leap second
+ uint8_t min; ///< minutes, 0..59
+ uint8_t hour; ///< hours, 0..23
+
+ uint8_t mday; ///< day of month, 0..31
+ uint8_t wday; ///< day of week, 1..7, 1 = Monday
+ uint8_t month; ///< month, 1..12
+ uint8_t year; ///< year of the century, 0..99
- uint8_t mday; /**< day of month, 0..31 */
- uint8_t wday; /**< day of week, 1..7, 1 = Monday */
- uint8_t month; /**< month, 1..12 */
- uint8_t year; /**< year of the century, 0..99 */
+ PCPS_TIME_STATUS status; ///< status bits, see ::PCPS_TIME_STATUS_FLAGS_COMMON
- PCPS_TIME_STATUS status; /**< status bits, see below */
} PCPS_STIME;
#ifdef _C166
@@ -1024,16 +1123,16 @@ typedef union
*/
typedef struct PCPS_IRIG_TIME_s
{
- PCPS_TIME_STATUS_X status; /**< status bits, see below */
- int16_t offs_utc; /**< [minutes] */
- uint16_t yday; /**< day of year, 1..365/366 */
- uint16_t frac; /**< fractions of seconds, 0.1 ms units */
- uint8_t sec; /**< seconds, 0..59, or 60 if leap second */
- uint8_t min; /**< minutes, 0..59 */
- uint8_t hour; /**< hours, 0..23 */
- uint8_t year; /**< 2 digit year number, 0xFF if year not supp. by the IRIG code */
- uint8_t signal; /**< relative signal strength, range depends on device type */
- uint8_t reserved; /**< currently not used, always 0 */
+ PCPS_TIME_STATUS_X status; ///< status bits, see @ref PCPS_TIME_STATUS_FLAGS
+ int16_t offs_utc; ///< [minutes]
+ uint16_t yday; ///< day of year, 1..365/366
+ uint16_t frac; ///< fractions of seconds, 0.1 ms units
+ uint8_t sec; ///< seconds, 0..59, or 60 if leap second
+ uint8_t min; ///< minutes, 0..59
+ uint8_t hour; ///< hours, 0..23
+ uint8_t year; ///< 2 digit year number, 0xFF if year not supp. by the IRIG code
+ PCPS_SIG_VAL signal; ///< signal strength, different meanings, see notes for @ref PCPS_SIG_VAL_DEFS
+ uint8_t reserved; ///< currently not used, always 0
} PCPS_IRIG_TIME;
#define _mbg_swab_pcps_irig_time( _p ) \
@@ -1046,91 +1145,121 @@ typedef struct PCPS_IRIG_TIME_s
+/**
+ * @brief Time status flags
+ *
+ * @anchor PCPS_TIME_STATUS_FLAGS @{ */
/**
- * Bit masks used with both PCPS_TIME_STATUS and PCPS_TIME_STATUS_X
+ * @brief Legacy time status flags
+ *
+ * Bit masks used with both ::PCPS_TIME_STATUS and ::PCPS_TIME_STATUS_X
*/
-#define PCPS_FREER 0x01 /**< DCF77 clock running on xtal */
- /**< GPS receiver has not verified its position */
-
-#define PCPS_DL_ENB 0x02 /**< daylight saving enabled */
-
-#define PCPS_SYNCD 0x04 /**< clock has sync'ed at least once after pwr up */
-
-#define PCPS_DL_ANN 0x08 /**< a change in daylight saving is announced */
-
-#define PCPS_UTC 0x10 /**< a special UTC firmware is installed */
-
-#define PCPS_LS_ANN 0x20 /**< leap second announced */
- /**< (requires firmware rev. REV_PCPS_LS_ANN_...) */
-
-#define PCPS_IFTM 0x40 /**< the current time was set via PC */
- /**< (requires firmware rev. REV_PCPS_IFTM_...) */
-
-#define PCPS_INVT 0x80 /**< invalid time because battery was disconn'd */
+enum PCPS_TIME_STATUS_FLAGS_COMMON
+{
+ PCPS_FREER = 0x01, ///< long wave or time code receiver running on xtal, satellite receiver has not verified its position
+ PCPS_DL_ENB = 0x02, ///< daylight saving enabled
+ PCPS_SYNCD = 0x04, ///< long wave or time code receiver has sync'ed at least once after pwr up, sat receiver is synchronized
+ PCPS_DL_ANN = 0x08, ///< a change in daylight saving status is announced
+ PCPS_UTC = 0x10, ///< returned time is always %UTC
+ PCPS_LS_ANN = 0x20, ///< leap second announced, for *very* old clocks see ::REV_PCPS_LS_ANN_PC31PS31
+ PCPS_IFTM = 0x40, ///< the current time has been set by an API call, for *very* old clocks see ::REV_PCPS_IFTM_PC31PS31
+ PCPS_INVT = 0x80 ///< invalid time because battery was disconn'd, or absolute time can't be decoded safely
+};
/**
- * Bit masks used only with PCPS_TIME_STATUS_X
+ * @brief Extended time status flags
+ *
+ * Bit masks used with ::PCPS_TIME_STATUS_X only
*/
-#define PCPS_LS_ENB 0x0100 /**< current second is leap second */
-#define PCPS_ANT_FAIL 0x0200 /**< antenna failure */
-#define PCPS_LS_ANN_NEG 0x0400 /**< announced leap second is negative */
-#define PCPS_SCALE_GPS 0x0800 /**< time stamp is GPS scale */
-#define PCPS_SCALE_TAI 0x1000 /**< time stamp is TAI scale */
+enum PCPS_TIME_STATUS_FLAGS_EXT
+{
+ PCPS_LS_ENB = 0x0100, ///< current second is leap second
+ PCPS_ANT_FAIL = 0x0200, ///< antenna failure
+ PCPS_LS_ANN_NEG = 0x0400, ///< announced leap second is negative
+ PCPS_SCALE_GPS = 0x0800, ///< time stamp is GPS scale
+ PCPS_SCALE_TAI = 0x1000, ///< time stamp is TAI scale
+
+ PCPS_UCAP_OVERRUN = 0x2000, ///< events interval too short (capture events only)
+ PCPS_UCAP_BUFFER_FULL = 0x4000, ///< events read too slow (capture events only)
+
+ /**
+ * Bit masks used only with time stamps representing the current board time.
+ * A DCF77 PZF receiver can set this bit if it is actually synchronized
+ * using PZF correlation and thus provides higher accuracy than AM receivers.
+ * Same numeric code as ::PCPS_UCAP_OVERRUN
+ */
+ PCPS_SYNC_PZF = 0x2000,
+
+ /**
+ * Immediately after a clock has been accessed, subsequent accesses
+ * may be blocked for up to 1.5 msec to give the clock's microprocessor
+ * some time to decode the incoming time signal.
+ * The flag below is eventually set if a program tries to read ::PCPS_HR_TIME
+ * during this interval. In this case the read function returns the
+ * proper time stamp which is taken if the command byte is written,
+ * however, the read function returns with delay.
+ * This flag is not supported by all clocks.
+ */
+ PCPS_IO_BLOCKED = 0x8000
-/**
- * Bit masks used only with time stamps representing user capture events
- */
-#define PCPS_UCAP_OVERRUN 0x2000 /**< events interval too short */
-#define PCPS_UCAP_BUFFER_FULL 0x4000 /**< events read too slow */
+};
-/**
- * Bit masks used only with time stamps representing the current board time.
- * A DCF77 PZF receiver can set this bit if it is actually synchronized
- * using PZF correlation and thus provides higher accuracy than AM receivers.
- */
-#define PCPS_SYNC_PZF 0x2000 /**< same code as PCPS_UCAP_OVERRUN */
-/**
- * Immediately after a clock has been accessed, subsequent accesses
- * are blocked for up to 1.5 msec to give the clock's microprocessor
- * some time to decode the incoming time signal.
- * The flag below is set if a program tries to read the PCPS_HR_TIME
- * during this interval. In this case the read function returns the
- * proper time stamp which is taken if the command byte is written,
- * however, the read function returns with delay.
- * This flag is not supported by all clocks.
- */
-#define PCPS_IO_BLOCKED 0x8000
/**
* This bit mask can be used to extract the time scale information out
* of a PCPS_TIME_STATUS_X value.
-*/
+ */
#define PCPS_SCALE_MASK ( PCPS_SCALE_TAI | PCPS_SCALE_GPS )
+/** @} anchor PCPS_TIME_STATUS_FLAGS */
+
+
+
+/**
+ * @brief Legacy definitions used to configure a device's serial port
+ *
+ * @deprecated This structure and the associated command codes
+ * are deprecated. ::PORT_SETTINGS, ::PORT_INFO and associated
+ * definitions should be used instead, if supported.
+ *
+ * @anchor PCPS_OLD_SERIAL_CFG @{ */
+
/**
- * Some DCF77 clocks have a serial interface that can be controlled
- * using the commands PCPS_SET_SERIAL and PCPS_GET_SERIAL. Both commands
- * use a parameter byte describing transmission speed, framing and mode
- * of operation. The parameter byte can be build using the constants
- * defined below, by or'ing one of the constants of each group, shifted
- * to the right position. PCPS_GET_SERIAL expects that parameter byte
- * and PCPS_GET_SERIAL returns the current configuration from the board.
+ * @brief Configuration information for a device's serial port
+ *
+ * Used with ::PCPS_GET_SERIAL and ::PCPS_SET_SERIAL
+ *
+ * The serial interface on some old DCF77 clocks can be configured
+ * using the commands ::PCPS_SET_SERIAL and ::PCPS_GET_SERIAL.
+ * Both commands use a parameter byte describing transmission speed,
+ * framing and mode of operation. The parameter byte can be assembled
+ * using the constants defined in ::PCPS_BD_CODES, ::PCPS_FR_CODES,
+ * and ::PCPS_MOD_CODES, by or'ing one of the constants of each group,
+ * shifted to the right position. ::PCPS_GET_SERIAL expects that parameter
+ * byte and ::PCPS_GET_SERIAL returns the current configuration from
+ * the board.
* _pcps_has_serial() checks whether supported.
- * For GPS clocks, please refer to the comments for the PCPS_GET_SERIAL
+ * For old GPS clocks refer to the comments for the ::PCPS_GET_SERIAL
* command.
*/
+typedef uint8_t PCPS_SERIAL;
+
/**
- * Baud rate indices. The values below are obsolete and should
- * be replaced by the codes named MBG_BAUD_RATE_... which are
- * defined in gpsdefs.h. The resulting index numbers, however,
- * have not changed.
+ * @brief Deprecated baud rate indices
+ *
+ * @deprecated These values are deprecated.
+ * ::MBG_BAUD_RATE_CODES and associated structures
+ * should be used preferably.
+ *
+ * The sequence of codes matches the sequence
+ * defined in ::MBG_BAUD_RATE_CODES.
*/
-enum
+enum PCPS_BD_CODES
{
PCPS_BD_300,
PCPS_BD_600,
@@ -1139,95 +1268,197 @@ enum
PCPS_BD_4800,
PCPS_BD_9600,
PCPS_BD_19200,
- N_PCPS_BD /* number of codes */
+ N_PCPS_BD ///< number of codes
};
-#define PCPS_BD_BITS 4 /* field with in the cfg byte */
-#define PCPS_BD_SHIFT 0 /* num of bits to shift left */
+#define PCPS_BD_BITS 4 ///< field with in the cfg byte
+#define PCPS_BD_SHIFT 0 ///< num of bits to shift left
-/*
- * Initializers for a table of all baud rate strings
- * and values can be found in gpsdefs.h.
- */
/**
- * Unfortunately, the framing codes below can not simply be
- * replaced by the newer MBG_FRAMING_... definitions since
- * the order of indices does not match.
+ * @brief Deprecated framing code indices
+ *
+ * @deprecated These values are deprecated.
+ * ::MBG_FRAMING_CODES and associated structures
+ * should be used preferably.
+ *
+ * Unfortunately, these framing codes can *not* simply
+ * be replaced by the newer MBG_FRAMING_... definitions
+ * since the order of indices doesn't match.
*/
-enum
+enum PCPS_FR_CODES
{
PCPS_FR_8N1,
PCPS_FR_7E2,
PCPS_FR_8N2,
PCPS_FR_8E1,
- N_PCPS_FR_DCF /* number of valid codes */
+ N_PCPS_FR_DCF ///< number of valid codes
};
-#define PCPS_FR_BITS 2 /* field with in the cfg byte */
-#define PCPS_FR_SHIFT PCPS_BD_BITS /* num of bits to shift left */
+#define PCPS_FR_BITS 2 ///< field with in the cfg byte
+#define PCPS_FR_SHIFT PCPS_BD_BITS ///< num of bits to shift left
+
-/*
- * An initializer for a table of framing strings is only defined for
- * the new MBG_FRAMING_... definitions. For editing the serial port
- * configuration, the old codes above should be translated to the new
- * codes to unify handling inside the edit functions.
+
+/**
+ * @brief Deprecated codes for modes of operation
+ *
+ * @deprecated These values are deprecated.
+ * ::STR_MODES and associated structures
+ * should be used preferably.
+ *
+ * The sequence of codes matches the sequence
+ * defined in ::STR_MODES.
*/
+enum PCPS_MOD_CODES
+{
+ PCPS_MOD_REQ, ///< time string on request '?' only
+ PCPS_MOD_SEC, ///< time string once per second
+ PCPS_MOD_MIN, ///< time string once per minute
+ PCPS_MOD_RSVD, ///< reserved
+ N_PCPS_MOD_DCF ///< number of possible codes
+};
-/**
- Modes of operation
+#define PCPS_MOD_BITS 2 ///< field with in the cfg byte
+#define PCPS_MOD_SHIFT ( PCPS_BD_BITS + PCPS_FR_BITS ) ///< num of bits to shift left
- * Indices for modes of operation. The values below are obsolete
- * and should be replaced by the codes named STR_... which are
- * defined in gpsdefs.h. The resulting index numbers, however,
- * have not changed.
+/** @} anchor PCPS_OLD_SERIAL_CFG */
+
+
+
+/**
+ * @brief Type of variable to hold a TZ code
+ *
+ * This is used with the PCI interface but differs from ::TZCODE
+ * which is used with the binary protocol.
+ *
+ * @see ::TZCODE
+ * @see ::TZCODE_UNION
*/
-enum
+typedef uint8_t PCPS_TZCODE;
+
+
+/**
+ * @brief Enumeration of codes used with PCPS_TZCODE
+ */
+enum PCPS_TZCODES
{
- PCPS_MOD_REQ, /* time string on request '?' only */
- PCPS_MOD_SEC, /* time string once per second */
- PCPS_MOD_MIN, /* time string once per minute */
- PCPS_MOD_RSVD, /* reserved */
- N_PCPS_MOD_DCF /* number of possible codes */
+ PCPS_TZCODE_CET_CEST, /* default as broadcasted by DCF77 (UTC+1h/UTC+2h) */
+ PCPS_TZCODE_CET, /* always CET (UTC+1h), discard DST */
+ PCPS_TZCODE_UTC, /* always %UTC */
+ PCPS_TZCODE_EET_EEST, /* East European Time, CET/CEST + 1h */
+ N_PCPS_TZCODE /* the number of valid codes */
};
-#define PCPS_MOD_BITS 2 /* field with in the cfg byte */
-#define PCPS_MOD_SHIFT ( PCPS_BD_BITS + PCPS_FR_BITS )
- /* num of bits to shift left */
+/* the definitions below are for compatibily only: */
+#define PCPS_TZCODE_MEZMESZ PCPS_TZCODE_CET_CEST
+#define PCPS_TZCODE_MEZ PCPS_TZCODE_CET
+#define PCPS_TZCODE_OEZ PCPS_TZCODE_EET_EEST
+
+
+/**
+ * The structures below can be used to configure a clock's
+ * time zone/daylight saving setting. This structure is shorter
+ * than the TZDL structure used with GPS clocks.
+ */
+typedef struct
+{
+ // The year_or_wday field below contains the full year number
+ // or 0..6 == Sun..Sat if the DL_AUTO_FLAG is set; see below.
+ uint16_t year_or_wday;
+ uint8_t month;
+ uint8_t mday;
+ uint8_t hour;
+ uint8_t min;
+} PCPS_DL_ONOFF;
+#define _mbg_swab_pcps_dl_onoff( _p ) \
+{ \
+ _mbg_swab16( &(_p)->year_or_wday ); \
+}
/**
- * Some definitions used with PZF receivers
+ * If the field year_or_wday is or'ed with the constant DL_AUTO_FLAG
+ * defined below then this means that start and end of daylight saving
+ * time shall be computed automatically for each year. In this case
+ * the remaining bits represent the day-of-week after the specified
+ * mday/month at which the change shall occur. If that flag is not set
+ * then the field contains the full four-digit year number and the
+ * mday/month values specify the exact date of that year.
*/
+#define DL_AUTO_FLAG 0x8000 // also defined in gpsdefs.h
-/* receiver distance from transmitter [km] */
-typedef uint16_t TR_DISTANCE;
+typedef struct
+{
+ int16_t offs; ///< offset from %UTC to local time [min]
+ int16_t offs_dl; ///< additional offset if DST enabled [min]
+ PCPS_DL_ONOFF tm_on; ///< date/time when daylight saving starts
+ PCPS_DL_ONOFF tm_off; ///< date/time when daylight saving ends
+} PCPS_TZDL;
+
+#define _mbg_swab_pcps_tzdl( _p ) \
+{ \
+ _mbg_swab16( &(_p)->offs ); \
+ _mbg_swab16( &(_p)->offs_dl ); \
+ _mbg_swab_pcps_dl_onoff( &(_p)->tm_on ); \
+ _mbg_swab_pcps_dl_onoff( &(_p)->tm_off ); \
+}
+
+
+
+typedef struct
+{
+ uint32_t used; ///< the number of saved capture events
+ uint32_t max; ///< capture buffer size
+} PCPS_UCAP_ENTRIES;
+
+#define _mbg_swab_pcps_ucap_entries( _p ) \
+{ \
+ _mbg_swab32( &(_p)->used ); \
+ _mbg_swab32( &(_p)->max ); \
+}
+
+
+
+/**
+ * @defgroup group_pzf_supp Definitions used with PZF receivers
+ *
+ * @{ */
+
+/**
+ * @brief Receiver distance from transmitter [km]
+ */
+typedef uint16_t TR_DISTANCE; ///< Range may vary with receiver type
#define _mbg_swab_tr_distance( _p ) \
_mbg_swab16( _p )
-
-/* correlation status info */
+/**
+ * @brief PZF correlation status info
+ */
typedef struct
{
- uint8_t val; /**< correlation value, or check count if status == PZF_CORR_CHECK */
- uint8_t status; /**< status codes, see below */
- char corr_dir; /**< space, '<', or '>' */
- uint8_t signal; /**< signal level, may always be 0 for devices which do not support this */
+ uint8_t val; ///< correlation value, or check count if status == PZF_CORR_CHECK
+ uint8_t status; ///< status codes, see below
+ char corr_dir; ///< space, '<', or '>'
+ PCPS_SIG_VAL signal; ///< signal strength, different meanings, see notes for @ref PCPS_SIG_VAL_DEFS
+
} CORR_INFO;
#define _mbg_swab_corr_info( _p ) \
_nop_macro_fnc()
-/** Codes used with CORR_INFO::status: */
+/**
+ * @brief Codes used with CORR_INFO::status:
+ */
enum
{
- PZF_CORR_RAW, /**< trying raw correlation, combi receivers running in AM mode */
- PZF_CORR_CHECK, /**< raw correlation achieved, doing plausibility checks */
- PZF_CORR_FINE, /**< fine correlation achieved */
+ PZF_CORR_RAW, ///< trying raw correlation, combi receivers running in AM mode
+ PZF_CORR_CHECK, ///< raw correlation achieved, doing plausibility checks
+ PZF_CORR_FINE, ///< fine correlation achieved
N_PZF_CORR_STATE
};
@@ -1256,132 +1487,150 @@ enum
{ PZF_CORR_STATE_NAME_FINE_ENG, PZF_CORR_STATE_NAME_FINE_GER } \
}
+/** @} defgroup group_pzf_supp */
-/** @defgroup group_gps_cmds_bus GPS commands passed via the system bus
- This enumeration defines the various types of data that can be read
- from or written to Meinberg bus level devices which support this.
- Access should be done using the functions pcps_read_gps_data()
- and pcps_write_gps_data() since the size of some of the structures
- exceeds the size of the device's I/O buffer and must therefore be
- accessed in several blocks.
-
- The structures to be used are defined in gpsdefs.h. Not all structures
- are supported, yet. Check the R/W indicators for details.
-
- * @{ */
-enum
-{ // R/W data type description
- // system data -----------------------------------------------
- PC_GPS_TZDL = 0, // R/W TZDL time zone / daylight saving
- PC_GPS_SW_REV, // R/- SW_REV software revision
- PC_GPS_BVAR_STAT, // R/- BVAR_STAT status of buffered variables
- PC_GPS_TIME, // R/W TTM curr. time
- PC_GPS_POS_XYZ, // -/W XYZ curr. pos. in ECEF coords
- PC_GPS_POS_LLA, // -/W LLA curr. pos. in geogr. coords
- PC_GPS_PORT_PARM, // R/W PORT_PARM param. of the serial ports
- PC_GPS_ANT_INFO, // R/- ANT_INFO time diff after ant. disconn.
- PC_GPS_UCAP, // R/- TTM user capture
- PC_GPS_ENABLE_FLAGS, // R/W ENABLE_FLAGS controls when to enable outp.
- PC_GPS_STAT_INFO, // R/- GPS_STAT_INFO
- PC_GPS_CMD, // -/W GPS_CMD commands as described below
- PC_GPS_IDENT, // R/- GPS_IDENT serial number
- PC_GPS_POS, // R/- POS position XYZ, LLA, and DMS
- PC_GPS_ANT_CABLE_LEN, // R/W ANT_CABLE_LEN used to compensate delay
- // The codes below are supported by new GPS receiver boards:
- PC_GPS_RECEIVER_INFO, // R/- RECEIVER_INFO rcvr model info
- PC_GPS_ALL_STR_TYPE_INFO, // R/- n*STR_TYPE_INFO_IDX all string types
- PC_GPS_ALL_PORT_INFO, // R/- n*PORT_INFO_IDX all port info
- PC_GPS_PORT_SETTINGS_IDX, // -/W PORT_SETTINGS_IDX port settings only
- PC_GPS_ALL_POUT_INFO, // R/- n*POUT_INFO_IDX all pout info
- PC_GPS_POUT_SETTINGS_IDX, // -/W POUT_SETTINGS_IDX pout settings only
- PC_GPS_TIME_SCALE, // R/W MBG_TIME_SCALE_{SETTINGS|INFO}, only if PCPS_HAS_TIME_SCALE
- PC_GPS_LAN_IF_INFO, // R/- LAN_IF_INFO LAN interface info, only if PCPS_HAS_LAN_INTF
- PC_GPS_IP4_STATE, // R/- IP4_SETTINGS LAN interface state, only if PCPS_HAS_LAN_INTF
- PC_GPS_IP4_SETTINGS, // R/W IP4_SETTINGS LAN interface configuration, only if PCPS_HAS_LAN_INTF
- PC_GPS_PTP_STATE, // R/- PTP_STATE, only if PCPS_HAS_PTP
- PC_GPS_PTP_CFG, // R/W PTP_CFG_{SETTINGS|INFO}, only if PCPS_HAS_PTP
- PC_GPS_PTP_UC_MASTER_CFG_LIMITS, // R/- PTP_UC_MASTER_CFG_LIMITS, only if can be unicast master
- PC_GPS_ALL_PTP_UC_MASTER_INFO, // R/- n*PTP_UC_MASTER_INFO_IDX, only if can be unicast master
- PC_GPS_PTP_UC_MASTER_SETTINGS_IDX, // -/W PTP_UC_MASTER_SETTINGS_IDX, only if can be unicast master
- PC_GPS_GPIO_CFG_LIMITS, // R/- MBG_GPIO_CFG_LIMITS, only if PCPS_HAS_GPIO
- PC_GPS_ALL_GPIO_INFO, // R/- n*MBG_GPIO_INFO, all GPIO info, only if PCPS_HAS_GPIO
- PC_GPS_GPIO_SETTINGS_IDX, // -/W MBG_GPIO_SETTINGS_IDX, GPIO cfg for a specific port, only if PCPS_HAS_GPIO
+/**
+ * @brief GPS Command codes passed via the system bus
+ *
+ * This enumeration defines the various types of data that can be read
+ * from or written to Meinberg bus level devices which support this.
+ * Access should be done using the functions pcps_read_gps_data()
+ * and pcps_write_gps_data() since the size of some of the structures
+ * exceeds the size of the device's I/O buffer and must therefore be
+ * accessed in several blocks.
+ *
+ * The structures to be used are defined in gpsdefs.h. Not all structures
+ * are supported, yet. Check the R/W indicators for details.
+ */
+enum PC_GPS_CMD_CODES
+{
+ // system data
+ PC_GPS_TZDL = 0, ///< (r/w) ::TZDL, time zone / daylight saving, only if ::GPS_MODEL_HAS_TZDL
+ PC_GPS_SW_REV, ///< (r/-) ::SW_REV, software revision, deprecated by ::PC_GPS_RECEIVER_INFO
+ PC_GPS_BVAR_STAT, ///< (r/-) ::BVAR_STAT, status of buffered variables, only if ::GPS_MODEL_HAS_BVAR_STAT
+ PC_GPS_TIME, ///< (r/w) ::TTM, current time, deprecated by ::PCPS_GIVE_HR_TIME
+ PC_GPS_POS_XYZ, ///< (-/w) ::XYZ, current position in ECEF coordinates, only if ::GPS_MODEL_HAS_POS_XYZ
+ PC_GPS_POS_LLA, ///< (-/w) ::LLA, current position in geographic coordinates, only if ::GPS_MODEL_HAS_POS_LLA
+ PC_GPS_PORT_PARM, ///< (r/w) ::PORT_PARM, param. of the serial ports, deprecated by ::PC_GPS_ALL_PORT_INFO
+ PC_GPS_ANT_INFO, ///< (r/-) ::ANT_INFO, time diff at sync. after antenna had been disconn., only if ::GPS_MODEL_HAS_ANT_INFO
+ PC_GPS_UCAP, ///< (r/-) ::TTM, user capture events, deprecated by ::PCPS_GIVE_UCAP_EVENT
+ PC_GPS_ENABLE_FLAGS, ///< (r/w) ::ENABLE_FLAGS, when to enable serial, pulses, and synth, only if ::GPS_MODEL_HAS_ENABLE_FLAGS
+ PC_GPS_STAT_INFO, ///< (r/-) ::GPS_STAT_INFO, satellite info, mode of operation, and DAC info, only if ::GPS_MODEL_HAS_STAT_INFO
+ PC_GPS_CMD, ///< (-/w) ::GPS_CMD, send one of the ::PC_GPS_COMMANDS
+ PC_GPS_IDENT, ///< (r/-) ::IDENT, serial number, deprecated by ::PC_GPS_RECEIVER_INFO
+ PC_GPS_POS, ///< (r/-) ::POS, position ::XYZ, ::LLA, and ::DMS combined, only if ::GPS_MODEL_HAS_POS
+ PC_GPS_ANT_CABLE_LEN, ///< (r/w) ::ANT_CABLE_LEN, length of antenna cable, only if ::GPS_MODEL_HAS_ANT_CABLE_LENGTH
+ PC_GPS_RECEIVER_INFO, ///< (r/-) ::RECEIVER_INFO, rcvr model info, only if ::PCPS_HAS_RECEIVER_INFO
+ PC_GPS_ALL_STR_TYPE_INFO, ///< (r/-) n * ::STR_TYPE_INFO_IDX, names and capabilities of all supp. string types, only if ::RECEIVER_INFO::n_str_type > 0
+ PC_GPS_ALL_PORT_INFO, ///< (r/-) n * ::PORT_INFO_IDX, settings and capabilities of all serial ports, only if ::RECEIVER_INFO::n_com_ports > 0
+ PC_GPS_PORT_SETTINGS_IDX, ///< (-/w) ::PORT_SETTINGS_IDX, settings for specified serial port, only if ::RECEIVER_INFO::n_com_ports > 0
+
+ PC_GPS_ALL_POUT_INFO, ///< (r/-) n * ::POUT_INFO_IDX, all programmable output info
+ PC_GPS_POUT_SETTINGS_IDX, ///< (-/w) ::POUT_SETTINGS_IDX, settings for one programmable output
+ PC_GPS_TIME_SCALE, ///< (r/w) ::MBG_TIME_SCALE_SETTINGS / ::MBG_TIME_SCALE_INFO, only if ::PCPS_HAS_TIME_SCALE
+ PC_GPS_LAN_IF_INFO, ///< (r/-) ::LAN_IF_INFO, LAN interface info, only if ::PCPS_HAS_LAN_INTF
+ PC_GPS_IP4_STATE, ///< (r/-) ::IP4_SETTINGS, LAN interface state, only if ::PCPS_HAS_LAN_INTF
+ PC_GPS_IP4_SETTINGS, ///< (r/w) ::IP4_SETTINGS, LAN interface configuration, only if ::PCPS_HAS_LAN_INTF
+ PC_GPS_PTP_STATE, ///< (r/-) ::PTP_STATE, only if ::PCPS_HAS_PTP
+ PC_GPS_PTP_CFG, ///< (r/w) ::PTP_CFG_SETTINGS / ::PTP_CFG_INFO, only if ::PCPS_HAS_PTP
+ PC_GPS_PTP_UC_MASTER_CFG_LIMITS, ///< (r/-) ::PTP_UC_MASTER_CFG_LIMITS, only if ::PTP_CFG_MSK_SUPPORT_PTP_UNICAST
+ PC_GPS_ALL_PTP_UC_MASTER_INFO, ///< (r/-) n * ::PTP_UC_MASTER_INFO_IDX, only if ::PTP_CFG_MSK_SUPPORT_PTP_UNICAST
+ PC_GPS_PTP_UC_MASTER_SETTINGS_IDX, ///< (-/w) ::PTP_UC_MASTER_SETTINGS_IDX, only if ::PTP_CFG_MSK_SUPPORT_PTP_UNICAST
+ PC_GPS_GPIO_CFG_LIMITS, ///< (r/-) ::MBG_GPIO_CFG_LIMITS, only if ::GPS_HAS_GPIO
+ PC_GPS_ALL_GPIO_INFO, ///< (r/-) n * ::MBG_GPIO_INFO_IDX, all GPIO info, only if ::GPS_HAS_GPIO
+ PC_GPS_GPIO_SETTINGS_IDX, ///< (-/w) ::MBG_GPIO_SETTINGS_IDX, settings for a specific port, only if ::GPS_HAS_GPIO
+ PC_GPS_GNSS_MODE, ///< (r/w) ::MBG_GNSS_MODE_INFO / ::MBG_GNSS_MODE_SETTINGS, only if ::PCPS_IS_GNSS
+ PC_GPS_ALL_GNSS_SAT_INFO, ///< (r/-) n * ::GNSS_SAT_INFO_IDX, satellite info, only if ::PCPS_IS_GNSS
+ PC_GPS_XMR_INSTANCES, ///< (r/-) ::XMULTI_REF_INSTANCES, only if ::GPS_HAS_XMULTI_REF and ::GPS_HAS_XMRS_MULT_INSTC
+ PC_GPS_XMR_SETTINGS_IDX, ///< (-/w) ::XMULTI_REF_SETTINGS_IDX, idx 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, only if ::GPS_HAS_XMULTI_REF
+ PC_GPS_ALL_XMR_INFO, ///< (r/-) n * ::XMULTI_REF_INFO_IDX, where n == ::XMULTI_REF_INSTANCES::n_xmr_settings, only if ::GPS_HAS_XMULTI_REF
+ PC_GPS_ALL_XMR_STATUS, ///< (r/w) n * ::XMULTI_REF_STATUS_IDX, where n == ::XMULTI_REF_INSTANCES::n_xmr_settings, one structure on write, only if ::GPS_HAS_XMULTI_REF
+ PC_GPS_XMR_HOLDOVER_STATUS, ///< (r/-) ::XMR_HOLDOVER_STATUS, only if ::XMRIF_MSK_HOLDOVER_STATUS_SUPP
+ PC_GPS_ALL_GPIO_STATUS, ///< (r/-) n * ::MBG_GPIO_STATUS_IDX, where n == ::MBG_GPIO_CFG_LIMITS::num_io, only if ::MBG_GPIO_CFG_LIMIT_FLAG_MASK_STATUS_SUPP
// GPS data
- PC_GPS_CFGH = 0x80, // -/- CFGH SVs' config. and health codes
- PC_GPS_ALM, // -/- SV_ALM one SV's num and almanac
- PC_GPS_EPH, // -/- SV_EPH one SV's num and ephemeris
- PC_GPS_UTC, // R/W UTC UTC corr. param., only if PCPS_HAS_UTC_PARM
- PC_GPS_IONO, // -/- IONO ionospheric corr. param.
- PC_GPS_ASCII_MSG // -/- ASCII_MSG the GPS ASCII message
+ PC_GPS_CFGH = 0x80, ///< (-/-) ::CFGH, SVs' config. and health codes (yet not used)
+ PC_GPS_ALM, ///< (-/-) ::SV_ALM, one SV's num and almanac (yet not used)
+ PC_GPS_EPH, ///< (-/-) ::SV_EPH, one SV's num and ephemeris (yet not used)
+ PC_GPS_UTC, ///< (r/w) ::UTC, %UTC corr. param., only if ::PCPS_HAS_UTC_PARM
+ PC_GPS_IONO, ///< (-/-) ::IONO, ionospheric corr. param. (yet not used)
+ PC_GPS_ASCII_MSG ///< (-/-) ::ASCII_MSG, the GPS ASCII message (yet not used)
};
-/** @} group_gps_cmds_bus */
-
/**
* @brief An initializer for a table of code/name entries of GPS commands.
*
- * This can e.g. be assigned to an array of MBG_CODE_NAME_TABLE_ENTRY elements
+ * This can e.g. be assigned to an array of ::MBG_CODE_NAME_TABLE_ENTRY elements
* and may be helpful when debugging.
*/
-#define MBG_PC_GPS_CMD_TABLE \
-{ \
- { PC_GPS_TZDL, "PC_GPS_TZDL" }, \
- { PC_GPS_SW_REV, "PC_GPS_SW_REV" }, \
- { PC_GPS_BVAR_STAT, "PC_GPS_BVAR_STAT" }, \
- { PC_GPS_TIME, "PC_GPS_TIME" }, \
- { PC_GPS_POS_XYZ, "PC_GPS_POS_XYZ" }, \
- { PC_GPS_POS_LLA, "PC_GPS_POS_LLA" }, \
- { PC_GPS_PORT_PARM, "PC_GPS_PORT_PARM" }, \
- { PC_GPS_ANT_INFO, "PC_GPS_ANT_INFO" }, \
- { PC_GPS_UCAP, "PC_GPS_UCAP" }, \
- { PC_GPS_ENABLE_FLAGS, "PC_GPS_ENABLE_FLAGS" }, \
- { PC_GPS_STAT_INFO, "PC_GPS_STAT_INFO" }, \
- { PC_GPS_CMD, "PC_GPS_CMD" }, \
- { PC_GPS_IDENT, "PC_GPS_IDENT" }, \
- { PC_GPS_POS, "PC_GPS_POS" }, \
- { PC_GPS_ANT_CABLE_LEN, "PC_GPS_ANT_CABLE_LEN" }, \
- { PC_GPS_RECEIVER_INFO, "PC_GPS_RECEIVER_INFO" }, \
- { PC_GPS_ALL_STR_TYPE_INFO, "PC_GPS_ALL_STR_TYPE_INFO" }, \
- { PC_GPS_ALL_PORT_INFO, "PC_GPS_ALL_PORT_INFO" }, \
- { PC_GPS_PORT_SETTINGS_IDX, "PC_GPS_PORT_SETTINGS_IDX" }, \
- { PC_GPS_ALL_POUT_INFO, "PC_GPS_ALL_POUT_INFO" }, \
- { PC_GPS_POUT_SETTINGS_IDX, "PC_GPS_POUT_SETTINGS_IDX" }, \
- { PC_GPS_TIME_SCALE, "PC_GPS_TIME_SCALE" }, \
- { PC_GPS_LAN_IF_INFO, "PC_GPS_LAN_IF_INFO" }, \
- { PC_GPS_IP4_STATE, "PC_GPS_IP4_STATE" }, \
- { PC_GPS_IP4_SETTINGS, "PC_GPS_IP4_SETTINGS" }, \
- { PC_GPS_PTP_STATE, "PC_GPS_PTP_STATE" }, \
- { PC_GPS_PTP_CFG, "PC_GPS_PTP_CFG" }, \
- { PC_GPS_PTP_UC_MASTER_CFG_LIMITS, "PC_GPS_PTP_UC_MASTER_CFG_LIMITS" }, \
- { PC_GPS_ALL_PTP_UC_MASTER_INFO, "PC_GPS_ALL_PTP_UC_MASTER_INFO" }, \
- { PC_GPS_PTP_UC_MASTER_SETTINGS_IDX, "PC_GPS_PTP_UC_MASTER_SETTINGS_IDX" }, \
- { PC_GPS_GPIO_CFG_LIMITS, "PC_GPS_GPIO_CFG_LIMITS" }, \
- { PC_GPS_ALL_GPIO_INFO, "PC_GPS_ALL_GPIO_INFO" }, \
- { PC_GPS_GPIO_SETTINGS_IDX, "PC_GPS_GPIO_SETTINGS_IDX" }, \
- { PC_GPS_CFGH, "PC_GPS_CFGH" }, \
- { PC_GPS_ALM, "PC_GPS_ALM" }, \
- { PC_GPS_EPH, "PC_GPS_EPH" }, \
- { PC_GPS_UTC, "PC_GPS_UTC" }, \
- { PC_GPS_IONO, "PC_GPS_IONO" }, \
- { PC_GPS_ASCII_MSG, "PC_GPS_ASCII_MSG" }, \
- { 0, NULL } \
+#define MBG_PC_GPS_CMD_TABLE \
+{ \
+ _mbg_cn_table_entry( PC_GPS_TZDL ), \
+ _mbg_cn_table_entry( PC_GPS_SW_REV ), \
+ _mbg_cn_table_entry( PC_GPS_BVAR_STAT ), \
+ _mbg_cn_table_entry( PC_GPS_TIME ), \
+ _mbg_cn_table_entry( PC_GPS_POS_XYZ ), \
+ _mbg_cn_table_entry( PC_GPS_POS_LLA ), \
+ _mbg_cn_table_entry( PC_GPS_PORT_PARM ), \
+ _mbg_cn_table_entry( PC_GPS_ANT_INFO ), \
+ _mbg_cn_table_entry( PC_GPS_UCAP ), \
+ _mbg_cn_table_entry( PC_GPS_ENABLE_FLAGS ), \
+ _mbg_cn_table_entry( PC_GPS_STAT_INFO ), \
+ _mbg_cn_table_entry( PC_GPS_CMD ), \
+ _mbg_cn_table_entry( PC_GPS_IDENT ), \
+ _mbg_cn_table_entry( PC_GPS_POS ), \
+ _mbg_cn_table_entry( PC_GPS_ANT_CABLE_LEN ), \
+ _mbg_cn_table_entry( PC_GPS_RECEIVER_INFO ), \
+ _mbg_cn_table_entry( PC_GPS_ALL_STR_TYPE_INFO ), \
+ _mbg_cn_table_entry( PC_GPS_ALL_PORT_INFO ), \
+ _mbg_cn_table_entry( PC_GPS_PORT_SETTINGS_IDX ), \
+ _mbg_cn_table_entry( PC_GPS_ALL_POUT_INFO ), \
+ _mbg_cn_table_entry( PC_GPS_POUT_SETTINGS_IDX ), \
+ _mbg_cn_table_entry( PC_GPS_TIME_SCALE ), \
+ _mbg_cn_table_entry( PC_GPS_LAN_IF_INFO ), \
+ _mbg_cn_table_entry( PC_GPS_IP4_STATE ), \
+ _mbg_cn_table_entry( PC_GPS_IP4_SETTINGS ), \
+ _mbg_cn_table_entry( PC_GPS_PTP_STATE ), \
+ _mbg_cn_table_entry( PC_GPS_PTP_CFG ), \
+ _mbg_cn_table_entry( PC_GPS_PTP_UC_MASTER_CFG_LIMITS ), \
+ _mbg_cn_table_entry( PC_GPS_ALL_PTP_UC_MASTER_INFO ), \
+ _mbg_cn_table_entry( PC_GPS_PTP_UC_MASTER_SETTINGS_IDX ), \
+ _mbg_cn_table_entry( PC_GPS_GPIO_CFG_LIMITS ), \
+ _mbg_cn_table_entry( PC_GPS_ALL_GPIO_INFO ), \
+ _mbg_cn_table_entry( PC_GPS_GPIO_SETTINGS_IDX ), \
+ _mbg_cn_table_entry( PC_GPS_GNSS_MODE ), \
+ _mbg_cn_table_entry( PC_GPS_ALL_GNSS_SAT_INFO ), \
+ _mbg_cn_table_entry( PC_GPS_XMR_INSTANCES ), \
+ _mbg_cn_table_entry( PC_GPS_XMR_SETTINGS_IDX ), \
+ _mbg_cn_table_entry( PC_GPS_ALL_XMR_INFO ), \
+ _mbg_cn_table_entry( PC_GPS_ALL_XMR_STATUS ), \
+ _mbg_cn_table_entry( PC_GPS_XMR_HOLDOVER_STATUS ), \
+ _mbg_cn_table_entry( PC_GPS_ALL_GPIO_STATUS ), \
+ _mbg_cn_table_entry( PC_GPS_CFGH ), \
+ _mbg_cn_table_entry( PC_GPS_ALM ), \
+ _mbg_cn_table_entry( PC_GPS_EPH ), \
+ _mbg_cn_table_entry( PC_GPS_UTC ), \
+ _mbg_cn_table_entry( PC_GPS_IONO ), \
+ _mbg_cn_table_entry( PC_GPS_ASCII_MSG ), \
+ _mbg_cn_table_end() \
}
-/** codes used with PC_GPS_CMD */
-enum
+/**
+ * @brief Codes used with ::PC_GPS_CMD
+ */
+enum PC_GPS_COMMANDS //##++++++++++++++
{
- PC_GPS_CMD_BOOT = 1, /**< force the clock to boot mode */
- PC_GPS_CMD_INIT_SYS, /**< let the clock clear its system variables */
- PC_GPS_CMD_INIT_USER, /**< reset the clock's user parameters to defaults */
- PC_GPS_CMD_INIT_DAC, /**< initialize the oscillator disciplining values */
- N_PC_GPS_CMD /**< no command, just the number of known commands */
+ PC_GPS_CMD_BOOT = 1, ///< force the clock to boot mode
+ PC_GPS_CMD_INIT_SYS, ///< let the clock clear its system variables
+ PC_GPS_CMD_INIT_USER, ///< reset the clock's user parameters to defaults
+ PC_GPS_CMD_INIT_DAC, ///< initialize the oscillator disciplining values
+ N_PC_GPS_CMD_CODES ///< no command, just the number of known commands
};
@@ -1400,6 +1649,8 @@ typedef uint16_t PCPS_CMD_INFO;
#undef _USING_BYTE_ALIGNMENT
#endif
+#define _PCPSDEFS_H_INCLUDED
+
/* End of header body */
#endif /* _PCPSDEFS_H */
diff --git a/c/mbglib/include/pcpsdev.h b/c/mbglib/include/pcpsdev.h
index 551d097..1d6694e 100644
--- a/c/mbglib/include/pcpsdev.h
+++ b/c/mbglib/include/pcpsdev.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: pcpsdev.h 1.49.1.71 2012/06/01 11:04:30Z daniel TEST $
+ * $Id: pcpsdev.h 1.53.1.8 2014/05/23 09:48:55Z martin TRASH martin $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -17,125 +17,64 @@
*
* -----------------------------------------------------------------------
* $Log: pcpsdev.h $
- * Revision 1.49.1.71 2012/06/01 11:04:30Z daniel
- * temporarily exclude function pointer definition for
- * KeQuerySystemTime() from x64 builds
- * Revision 1.49.1.70 2012/05/29 14:37:43Z martin
+ * Revision 1.53.1.8 2014/05/23 09:48:55Z martin
+ * Revision 1.53.1.7 2014/05/22 14:53:34 martin
+ * Added _pcps_has_ri_xmr() macro.
+ * Revision 1.53.1.6 2014/04/15 15:37:47 martin
+ * Support GPIO ports.
+ * Revision 1.53.1.5 2014/01/23 15:35:48 martin
+ * Support GPS180AMC.
+ * Revision 1.53.1.4 2013/12/18 14:52:15 martin
+ * Moved inline function num_bits_set() to cfg_hlp.h.
+ * Revision 1.53.1.3 2013/12/16 10:39:35 martin
+ * Revision 1.53.1.2 2013/12/12 11:58:09Z martin
+ * Revision 1.53.1.1 2013/12/12 11:29:17Z martin
+ * Doxygen stuff.
+ * Revision 1.53 2013/11/08 08:46:00 martin
+ * Doxygen comment updates.
+ * Revision 1.52 2013/09/26 09:06:47Z martin
+ * Support GLN180PEX and GNSS API.
+ * Added inline fnc num_bits_set().
+ * Revision 1.51 2013/01/25 15:44:21 martin
+ * Added inline function setup_hr_time_cycles_from_timestamp_cycles() which sets
+ * up a PCPS_HR_TIME_CYCLES structure from PCPS_TIME_STAMP_CYCLES.
+ * Revision 1.50 2012/10/02 19:00:46 martin
+ * Support GPS180PEX, TCR180PEX, and PZF180PEX.
+ * Support DCF600USB, TCR600USB, MSF600USB, and WVB600USB.
* Runtime support for precise time API introduced with Windows 8.
- * Revision 1.49.1.69 2012/05/08 10:22:58Z daniel
- * Bugfix: Use negative sign for delay in KeDelayExecutionThread()
- * Revision 1.49.1.68 2011/11/28 10:04:39Z martin
- * PZF180PEX doesn't support TIME_SCALE by default.
- * Revision 1.49.1.67 2011/11/25 15:03:23 martin
+ * This does not yet for x64 builds.
+ * There are some g++ versions which fail to compile source code using
+ * the macros provided by Linux to define IOCTL codes. If only the API
+ * functions are called by an application then the IOCTL codes aren't
+ * required anyway, so we just avoid inclusion of mbgioctl.h.
+ * However, some IOCTL related definitions are required anyway, so
+ * they have been moved to this file which is always included.
+ * Bug fix: Use negative sign for delay in KeDelayExecutionThread()
* Support on-board event logs.
- * Revision 1.49.1.66 2011/11/24 14:01:45 martin
- * Added kernel uptime/sleep for NetBSD.
- * Revision 1.49.1.65 2011/11/24 08:54:53 martin
* Moved macro _must_do_fw_workaround_20ms() here.
- * Revision 1.49.1.64 2011/11/22 16:27:25 martin
* New macro _pcps_has_debug_status().
- * Revision 1.49.1.63 2011/11/01 12:20:00 martin
- * Revision 1.49.1.62 2011/11/01 12:14:33 martin
- * Revision 1.49.1.61 2011/11/01 09:13:05 martin
- * Revision 1.49.1.60 2011/10/31 08:55:05 martin
- * Revision 1.49.1.59 2011/10/28 13:51:15 martin
* Added some macros to test if specific stat_info stuff is supported.
- * Revision 1.49.1.58 2011/10/21 14:07:27 martin
- * Revision 1.49.1.57 2011/09/21 16:03:04 martin
* Moved some definitions useful for configuration tools to new file cfg_hlp.h.
- * Revision 1.49.1.56 2011/09/20 08:31:22 martin
- * Modified default features for PZF180PEX.
- * Revision 1.49.1.55 2011/09/12 12:32:38Z martin
- * Revision 1.49.1.54 2011/09/12 09:45:12 martin
- * Fixed a typo (missing comma).
- * Revision 1.49.1.53 2011/08/05 11:02:28 martin
- * Revision 1.49.1.52 2011/07/19 10:41:48 martin
- * Revision 1.49.1.51 2011/07/14 13:29:14 martin
- * Revision 1.49.1.50 2011/07/13 09:44:53 martin
* Moved IA64 includes from pcpsdev.h to mbgpccyc.h.
- * Revision 1.49.1.49 2011/07/06 13:23:24 martin
- * Revision 1.49.1.48 2011/07/06 11:22:50 martin
* Added macros _pcps_has_corr_info() and _pcps_has_tr_distance().
- * Revision 1.49.1.47 2011/07/05 12:25:19 martin
- * Revision 1.49.1.46 2011/07/04 10:29:44 martin
- * Modified a comment.
- * Revision 1.49.1.45 2011/06/29 14:06:08 martin
- * Added support for TCR600USB, MSF600USB, and WVB600USB.
* Extended bus flag for USB v2 and macro _pcps_is_usb_v2().
* New feature ..._HAS_PZF and macro _pcps_has_pzf().
- * Revision 1.49.1.44 2011/06/29 09:10:26 martin
- * Renamed PZF600PEX to PZF180PEX.
- * Revision 1.49.1.43 2011/06/24 10:26:52 martin
- * Fixed warning under DOS.
- * Revision 1.49.1.42 2011/06/24 08:07:03Z martin
* Moved PC cycles stuff to an new extra header.
- * Revision 1.49.1.41 2011/06/21 15:17:36 martin
- * Fixed build under DOS.
- * Revision 1.49.1.40 2011/06/21 14:23:59Z martin
* Cleaned up handling of pragma pack().
* Introduced generic MBG_SYS_TIME with nanosecond resolution.
* Support struct timespec under Linux, if available.
- * Revision 1.49.1.39 2011/06/01 09:29:09 martin
- * Revision 1.49.1.38 2011/05/31 14:20:54 martin
- * Revision 1.49.1.37 2011/05/16 13:18:38 martin
* Use MBG_TGT_KERNEL instead of _KDD_.
- * Revision 1.49.1.36 2011/05/06 13:47:38Z martin
- * Support PZF600PEX.
- * Revision 1.49.1.35 2011/04/19 15:06:24 martin
* Added PTP unicast master configuration stuff.
- * Revision 1.49.1.34 2011/03/29 14:08:45 martin
* For compatibility use cpu_counter() instead of cpu_counter_serializing() under NetBSD.
- * Revision 1.49.1.33 2011/03/28 09:50:18 martin
- * Modifications for NetBSD from Frank Kardel.
- * Revision 1.49.1.32 2011/03/25 11:09:43 martin
* Optionally support timespec for sys time (USE_TIMESPEC).
- * Started to support NetBSD.
- * Revision 1.49.1.31 2011/02/16 10:10:49 martin
- * Fixed macro syntax for _pcps_time_set_unread().
- * Revision 1.49.1.30 2011/02/15 14:24:56Z martin
- * Revision 1.49.1.29 2011/02/10 13:34:21 martin
- * Revision 1.49.1.28 2011/02/10 13:21:59 martin
- * Revision 1.49.1.27 2011/02/10 12:26:17 martin
- * Revision 1.49.1.26 2011/02/09 15:46:49 martin
- * Revision 1.49.1.25 2011/02/04 14:44:44 martin
- * Revision 1.49.1.24 2011/02/04 10:10:00 martin
- * Revision 1.49.1.23 2011/02/02 12:34:10 martin
- * Revision 1.49.1.22 2011/02/01 17:12:04 martin
- * Revision 1.49.1.21 2011/01/28 13:11:11 martin
- * Preliminary implementation of mbg_get_sys_time for FreeBSD traps.
- * Revision 1.49.1.20 2011/01/28 10:34:37 martin
+ * Support FreeBSD and NetBSD.
* Moved MBG_TGT_SUPP_MEM_ACC definition here.
- * Revision 1.49.1.19 2011/01/26 16:39:05 martin
- * Preliminarily support FreeBSD build.
- * Revision 1.49.1.18 2011/01/24 17:09:51 martin
- * Preliminarily fixed build under FreeBSD.
- * Revision 1.49.1.17 2010/12/14 13:19:58 martin
- * Fixed doxgen comments.
- * Revision 1.49.1.16 2010/12/14 12:20:10 martin
- * Revision 1.49.1.15 2010/11/25 14:54:22 martin
* Moved status port register definitions to pcpsdefs.h.
- * Revision 1.49.1.14 2010/11/11 09:15:38 martin
- * Added definitions to support DCF600USB.
- * Revision 1.49.1.13 2010/09/27 13:09:06 martin
* Features are now defined using enum and bit masks.
* Added initializer for feature names (used for debug).
- * Revision 1.49.1.12 2010/08/25 12:44:42 martin
- * Revision 1.49.1.11 2010/08/20 09:34:41Z martin
* Added macro _pcps_features().
- * Revision 1.49.1.10 2010/08/17 15:34:23 martin
- * Revision 1.49.1.9 2010/08/16 15:41:32 martin
- * Revision 1.49.1.8 2010/08/13 12:14:46 daniel
- * Revision 1.49.1.7 2010/08/13 11:57:54Z martin
- * Revision 1.49.1.6 2010/08/13 11:39:28Z martin
- * Revision 1.49.1.5 2010/08/13 11:19:41 martin
* Implemented portable mbg_get_sys_uptime() and mbg_sleep_sec()
* functions and associated types.
- * Revision 1.49.1.4 2010/08/11 14:32:14 martin
- * Revision 1.49.1.3 2010/08/11 13:47:42 martin
- * Cleanup.
- * Revision 1.49.1.2 2010/07/14 14:50:42 martin
- * Revision 1.49.1.1 2010/06/30 13:17:18 martin
- * Support GPS180PEX and TCR180PEX.
* Revision 1.49 2010/06/30 13:03:48 martin
* Use new preprocessor symbol MBG_ARCH_X86.
* Use ulong port addresses for all platforms but x86.
@@ -330,6 +269,10 @@
#include <usbdefs.h>
#include <use_pack.h>
+#if !defined( MBG_TGT_KERNEL )
+ #include <string.h>
+#endif
+
#if defined( MBG_TGT_WIN32 )
#include <mbg_w32.h>
@@ -469,33 +412,36 @@
#endif
+// MBG_SYS_TIME is always read in native machine endianess,
+// so no need to convert endianess.
+#define _mbg_swab_mbg_sys_time( _p ) \
+ _nop_macro_fnc()
+
+
#if !defined( MBG_TGT_SUPP_MEM_ACC )
#define MBG_TGT_SUPP_MEM_ACC 0
#endif
-// MBG_SYS_TIME is always read in native machine endianess,
-// so no endianess conversion is required.
-#define _mbg_swab_mbg_sys_time( _p ) \
- _nop_macro_fnc()
-
-
/**
- The structure holds a system timestamp in a format depending on the target OS
- plus two cycles counter values which can be taken before and after reading
- the system time. These cycles values can be used to determine the execution
- time required to read the system time.
-
- Limitations of the operating system need to be taken into account,
- e.g. the Windows system time may increase once every ~16 ms only.
- */
+ * @brief System time plus associated cycles counter values
+ *
+ * The structure holds a system timestamp in a format depending on the target OS
+ * plus two cycles counter values which can be taken before and after reading
+ * the system time. These cycles values can be used to determine the execution
+ * time required to read the system time.
+ *
+ * Limitations of the operating system need to be taken into account,
+ * e.g. the Windows system time may increase once every ~16 ms or ~1 ms only,
+ * depending on the Windows version.
+ */
typedef struct
{
- MBG_PC_CYCLES cyc_before; /**< cycles count before sys time is read */
- MBG_PC_CYCLES cyc_after; /**< cycles count after sys time has been read */
- MBG_SYS_TIME sys_time; /**< system time stamp */
+ MBG_PC_CYCLES cyc_before; ///< cycles count before sys time is read
+ MBG_PC_CYCLES cyc_after; ///< cycles count after sys time has been read
+ MBG_SYS_TIME sys_time; ///< system time stamp
} MBG_SYS_TIME_CYCLES;
#define _mbg_swab_mbg_sys_time_cycles( _p ) \
@@ -507,7 +453,6 @@ typedef struct
-
static __mbg_inline
void mbg_get_sys_time( MBG_SYS_TIME *p )
{
@@ -633,6 +578,7 @@ void mbg_get_sys_uptime( MBG_SYS_UPTIME *p )
#elif defined( MBG_TGT_LINUX )
#if defined( MBG_TGT_KERNEL )
+ // getrawmonotonic() can possibly be used for this in newer kernels
{
// Using a simple 64 bit division may result in a linker error
// in kernel mode due to a missing symbol __udivdi3, so we use
@@ -831,7 +777,9 @@ typedef uint16_t MBG_DBG_PORT;
-/** A list of known radio clocks. */
+/**
+ * @brief A list of known devices
+ */
enum PCPS_TYPES
{
PCPS_TYPE_PC31,
@@ -867,6 +815,8 @@ enum PCPS_TYPES
PCPS_TYPE_TCR600USB,
PCPS_TYPE_MSF600USB,
PCPS_TYPE_WVB600USB,
+ PCPS_TYPE_GLN180PEX,
+ PCPS_TYPE_GPS180AMC,
N_PCPS_DEV_TYPE
};
@@ -878,11 +828,13 @@ typedef uint16_t PCPS_REF_TYPE;
typedef uint16_t PCPS_BUS_FLAGS;
/**
- The structure contains the characteristics of each
- of the clocks listed above. These fields are always the
- same for a single type of clock and do not change with
- firmware version, port address, etc.
- */
+ * @brief Device type specification
+ *
+ * Contains the characteristics of one of the ::PCPS_TYPES.
+ * These specifications are always the same for a particular
+ * type of device and do not change with firmware version,
+ * port address, etc.
+ */
typedef struct
{
uint16_t num;
@@ -903,16 +855,17 @@ typedef struct
/**
- The structure below describes an I/O port resource
- used by a clock.
-*/
+ * @brief An I/O port resource used by a device
+ */
typedef struct
{
PCPS_PORT_ADDR base;
uint16_t num;
} PCPS_PORT_RSRC;
-/** The max number of I/O port resources used by a clock. */
+/**
+ * @brief The max. number of I/O port resources used by a clock
+ */
#define N_PCPS_PORT_RSRC 2
@@ -930,20 +883,21 @@ typedef struct
-typedef uint32_t PCPS_ERR_FLAGS; /**< see \ref group_err_flags "Error flags" */
-typedef uint32_t PCPS_FEATURES; /**< see \ref group_features "Features" */
+typedef uint32_t PCPS_ERR_FLAGS; ///< see @ref PCPS_ERR_FLAG_MASKS
+typedef uint32_t PCPS_FEATURES; ///< see @ref PCPS_FEATURE_MASKS
typedef uint16_t PCPS_BUS_NUM;
typedef uint16_t PCPS_SLOT_NUM;
/**
- The structure below contains data which depends
- on a individual instance of the clock, e.g.
- the firmware which is currently installed, the
- port address which has been configured, etc.
-*/
+ * @brief Device information
+ *
+ * Contains data which depends on a particular instance
+ * of a device, e.g. the firmware which is currently installed,
+ * the port address which has actually been assigned, etc.
+ */
typedef struct
{
- PCPS_ERR_FLAGS err_flags; /**< See \ref group_err_flags "Error flags" */
+ PCPS_ERR_FLAGS err_flags; ///< See @ref PCPS_ERR_FLAG_MASKS
PCPS_BUS_NUM bus_num;
PCPS_SLOT_NUM slot_num;
PCPS_PORT_RSRC port[N_PCPS_PORT_RSRC];
@@ -951,36 +905,51 @@ typedef struct
int16_t irq_num;
uint32_t timeout_clk;
uint16_t fw_rev_num;
- PCPS_FEATURES features; /**< See \ref group_features "Feature flags" */
+ PCPS_FEATURES features; ///< See @ref PCPS_FEATURE_MASKS
PCPS_ID_STR fw_id;
PCPS_SN_STR sernum;
} PCPS_DEV_CFG;
-/** @defgroup group_err_flags Error flags in PCPS_DEV_CFG
- Flags used with PCPS_DEV_CFG::err_flags
- @{
-*/
-#define PCPS_EF_TIMEOUT 0x00000001 /**< timeout occured */
-#define PCPS_EF_INV_EPROM_ID 0x00000002 /**< invalid EPROM ID */
-#define PCPS_EF_IO_INIT 0x00000004 /**< I/O intf not init'd */
-#define PCPS_EF_IO_CFG 0x00000008 /**< I/O intf not cfg'd */
-#define PCPS_EF_IO_ENB 0x00000010 /**< I/O intf not enabled */
-#define PCPS_EF_IO_RSRC 0x00000020 /**< I/O not registered w/ rsrcmgr */
-/** @} */
-
-/** @defgroup group_features Feature flags used with PCPS_FEATURES
-
- Some features of the radio clocks have been introduced with
- specific firmware versions, so depending on the firmware version
- a clock may support a feature or not. The clock detection function
- checks the clock model and firmware version and updates the field
- PCPS_DEV_CFG::features accordingly. There are some macros which
- can easily be used to query whether a clock device actually
- supports a function, or not. The definitions define
- the possible features.
- @{
-*/
-enum
+
+/**
+ * @brief Possible device initialization error flags
+ *
+ * Used with ::PCPS_DEV_CFG::err_flags
+ *
+ * @see ::PCPS_ERR_FLAGS
+ *
+ * @anchor PCPS_ERR_FLAG_MASKS @{ */
+
+#define PCPS_EF_TIMEOUT 0x00000001 ///< timeout occured
+#define PCPS_EF_INV_FW_ID 0x00000002 ///< invalid firmware ID
+#define PCPS_EF_IO_INIT 0x00000004 ///< I/O interface not initialized
+#define PCPS_EF_IO_CFG 0x00000008 ///< I/O interface not configured
+#define PCPS_EF_IO_ENB 0x00000010 ///< I/O interface not enabled
+#define PCPS_EF_IO_RSRC 0x00000020 ///< I/O resource not registered with resource manager
+
+/** @} anchor PCPS_ERR_FLAG_MASKS */
+
+
+/**
+ * @defgroup group_pcps_features Feature flags used with ::PCPS_FEATURES
+ *
+ * Some features of the radio clocks have been introduced with
+ * specific firmware versions, so depending on the firmware version
+ * a clock may support a feature or not. The clock detection function
+ * checks the clock model and firmware version and updates the field
+ * PCPS_DEV_CFG::features accordingly. There are some macros which
+ * can easily be used to query whether a clock device actually
+ * supports a function, or not. The definitions define
+ * the possible features.
+ *
+ * @{ */
+
+/**
+ * @brief Feature bits for bus-level devices
+ *
+ * @see @ref PCPS_FEATURE_MASKS
+ */
+enum PCPS_FEATURE_BITS
{
PCPS_BIT_CAN_SET_TIME,
PCPS_BIT_HAS_SERIAL,
@@ -1014,41 +983,57 @@ enum
PCPS_BIT_HAS_RAW_IRIG_DATA,
PCPS_BIT_HAS_PZF, // can also demodulate DCF77 PZF
PCPS_BIT_HAS_EVT_LOG,
+ PCPS_BIT_IS_GNSS, // supports several satellite systems and GNSS API calls
- N_PCPS_FEATURE // must not exceed 32 !!
+ N_PCPS_FEATURE_BITS // must not exceed 32 !!
};
-#define PCPS_CAN_SET_TIME ( 1UL << PCPS_BIT_CAN_SET_TIME )
-#define PCPS_HAS_SERIAL ( 1UL << PCPS_BIT_HAS_SERIAL )
-#define PCPS_HAS_SYNC_TIME ( 1UL << PCPS_BIT_HAS_SYNC_TIME )
-#define PCPS_HAS_TZDL ( 1UL << PCPS_BIT_HAS_TZDL )
-#define PCPS_HAS_IDENT ( 1UL << PCPS_BIT_HAS_IDENT )
-#define PCPS_HAS_UTC_OFFS ( 1UL << PCPS_BIT_HAS_UTC_OFFS )
-#define PCPS_HAS_HR_TIME ( 1UL << PCPS_BIT_HAS_HR_TIME )
-#define PCPS_HAS_SERNUM ( 1UL << PCPS_BIT_HAS_SERNUM )
-#define PCPS_HAS_TZCODE ( 1UL << PCPS_BIT_HAS_TZCODE )
-#define PCPS_HAS_CABLE_LEN ( 1UL << PCPS_BIT_HAS_CABLE_LEN )
-#define PCPS_HAS_EVENT_TIME ( 1UL << PCPS_BIT_HAS_EVENT_TIME )
-#define PCPS_HAS_RECEIVER_INFO ( 1UL << PCPS_BIT_HAS_RECEIVER_INFO )
-#define PCPS_CAN_CLR_UCAP_BUFF ( 1UL << PCPS_BIT_CAN_CLR_UCAP_BUFF )
-#define PCPS_HAS_PCPS_TZDL ( 1UL << PCPS_BIT_HAS_PCPS_TZDL )
-#define PCPS_HAS_UCAP ( 1UL << PCPS_BIT_HAS_UCAP )
-#define PCPS_HAS_IRIG_TX ( 1UL << PCPS_BIT_HAS_IRIG_TX )
-#define PCPS_HAS_GPS_DATA_16 ( 1UL << PCPS_BIT_HAS_GPS_DATA_16 )
-#define PCPS_HAS_SYNTH ( 1UL << PCPS_BIT_HAS_SYNTH )
-#define PCPS_HAS_GENERIC_IO ( 1UL << PCPS_BIT_HAS_GENERIC_IO )
-#define PCPS_HAS_TIME_SCALE ( 1UL << PCPS_BIT_HAS_TIME_SCALE )
-#define PCPS_HAS_UTC_PARM ( 1UL << PCPS_BIT_HAS_UTC_PARM )
-#define PCPS_HAS_IRIG_CTRL_BITS ( 1UL << PCPS_BIT_HAS_IRIG_CTRL_BITS )
-#define PCPS_HAS_LAN_INTF ( 1UL << PCPS_BIT_HAS_LAN_INTF )
-#define PCPS_HAS_PTP ( 1UL << PCPS_BIT_HAS_PTP )
-#define PCPS_HAS_IRIG_TIME ( 1UL << PCPS_BIT_HAS_IRIG_TIME )
-#define PCPS_HAS_FAST_HR_TSTAMP ( 1UL << PCPS_BIT_HAS_FAST_HR_TSTAMP )
-#define PCPS_HAS_RAW_IRIG_DATA ( 1UL << PCPS_BIT_HAS_RAW_IRIG_DATA )
-#define PCPS_HAS_PZF ( 1UL << PCPS_BIT_HAS_PZF )
-#define PCPS_HAS_EVT_LOG ( 1UL << PCPS_BIT_HAS_EVT_LOG )
+/**
+ * @brief Feature bit masks for bus-level devices
+ *
+ * Used with ::PCPS_DEV_CFG::err_flags
+ *
+ * @see ::PCPS_FEATURES
+ *
+ * @anchor PCPS_FEATURE_MASKS @{ */
+
+#define PCPS_CAN_SET_TIME ( 1UL << PCPS_BIT_CAN_SET_TIME ) ///< see ::PCPS_BIT_CAN_SET_TIME
+#define PCPS_HAS_SERIAL ( 1UL << PCPS_BIT_HAS_SERIAL ) ///< see ::PCPS_BIT_HAS_SERIAL
+#define PCPS_HAS_SYNC_TIME ( 1UL << PCPS_BIT_HAS_SYNC_TIME ) ///< see ::PCPS_BIT_HAS_SYNC_TIME
+#define PCPS_HAS_TZDL ( 1UL << PCPS_BIT_HAS_TZDL ) ///< see ::PCPS_BIT_HAS_TZDL
+#define PCPS_HAS_IDENT ( 1UL << PCPS_BIT_HAS_IDENT ) ///< see ::PCPS_BIT_HAS_IDENT
+#define PCPS_HAS_UTC_OFFS ( 1UL << PCPS_BIT_HAS_UTC_OFFS ) ///< see ::PCPS_BIT_HAS_UTC_OFFS
+#define PCPS_HAS_HR_TIME ( 1UL << PCPS_BIT_HAS_HR_TIME ) ///< see ::PCPS_BIT_HAS_HR_TIME
+#define PCPS_HAS_SERNUM ( 1UL << PCPS_BIT_HAS_SERNUM ) ///< see ::PCPS_BIT_HAS_SERNUM
+
+#define PCPS_HAS_TZCODE ( 1UL << PCPS_BIT_HAS_TZCODE ) ///< see ::PCPS_BIT_HAS_TZCODE
+#define PCPS_HAS_CABLE_LEN ( 1UL << PCPS_BIT_HAS_CABLE_LEN ) ///< see ::PCPS_BIT_HAS_CABLE_LEN
+#define PCPS_HAS_EVENT_TIME ( 1UL << PCPS_BIT_HAS_EVENT_TIME ) ///< see ::PCPS_BIT_HAS_EVENT_TIME
+#define PCPS_HAS_RECEIVER_INFO ( 1UL << PCPS_BIT_HAS_RECEIVER_INFO ) ///< see ::PCPS_BIT_HAS_RECEIVER_INFO
+#define PCPS_CAN_CLR_UCAP_BUFF ( 1UL << PCPS_BIT_CAN_CLR_UCAP_BUFF ) ///< see ::PCPS_BIT_CAN_CLR_UCAP_BUFF
+#define PCPS_HAS_PCPS_TZDL ( 1UL << PCPS_BIT_HAS_PCPS_TZDL ) ///< see ::PCPS_BIT_HAS_PCPS_TZDL
+#define PCPS_HAS_UCAP ( 1UL << PCPS_BIT_HAS_UCAP ) ///< see ::PCPS_BIT_HAS_UCAP
+#define PCPS_HAS_IRIG_TX ( 1UL << PCPS_BIT_HAS_IRIG_TX ) ///< see ::PCPS_BIT_HAS_IRIG_TX
+
+#define PCPS_HAS_GPS_DATA_16 ( 1UL << PCPS_BIT_HAS_GPS_DATA_16 ) ///< see ::PCPS_BIT_HAS_GPS_DATA_16
+#define PCPS_HAS_SYNTH ( 1UL << PCPS_BIT_HAS_SYNTH ) ///< see ::PCPS_BIT_HAS_SYNTH
+#define PCPS_HAS_GENERIC_IO ( 1UL << PCPS_BIT_HAS_GENERIC_IO ) ///< see ::PCPS_BIT_HAS_GENERIC_IO
+#define PCPS_HAS_TIME_SCALE ( 1UL << PCPS_BIT_HAS_TIME_SCALE ) ///< see ::PCPS_BIT_HAS_TIME_SCALE
+#define PCPS_HAS_UTC_PARM ( 1UL << PCPS_BIT_HAS_UTC_PARM ) ///< see ::PCPS_BIT_HAS_UTC_PARM
+#define PCPS_HAS_IRIG_CTRL_BITS ( 1UL << PCPS_BIT_HAS_IRIG_CTRL_BITS ) ///< see ::PCPS_BIT_HAS_IRIG_CTRL_BITS
+#define PCPS_HAS_LAN_INTF ( 1UL << PCPS_BIT_HAS_LAN_INTF ) ///< see ::PCPS_BIT_HAS_LAN_INTF
+#define PCPS_HAS_PTP ( 1UL << PCPS_BIT_HAS_PTP ) ///< see ::PCPS_BIT_HAS_PTP
+
+#define PCPS_HAS_IRIG_TIME ( 1UL << PCPS_BIT_HAS_IRIG_TIME ) ///< see ::PCPS_BIT_HAS_IRIG_TIME
+#define PCPS_HAS_FAST_HR_TSTAMP ( 1UL << PCPS_BIT_HAS_FAST_HR_TSTAMP ) ///< see ::PCPS_BIT_HAS_FAST_HR_TSTAMP
+#define PCPS_HAS_RAW_IRIG_DATA ( 1UL << PCPS_BIT_HAS_RAW_IRIG_DATA ) ///< see ::PCPS_BIT_HAS_RAW_IRIG_DATA
+#define PCPS_HAS_PZF ( 1UL << PCPS_BIT_HAS_PZF ) ///< see ::PCPS_BIT_HAS_PZF
+#define PCPS_HAS_EVT_LOG ( 1UL << PCPS_BIT_HAS_EVT_LOG ) ///< see ::PCPS_BIT_HAS_EVT_LOG
+#define PCPS_IS_GNSS ( 1UL << PCPS_BIT_IS_GNSS ) ///< see ::PCPS_BIT_IS_GNSS
+
+/** @} anchor PCPS_FEATURE_MASKS */
#define PCPS_FEATURE_NAMES \
@@ -1081,10 +1066,11 @@ enum
"PCPS_HAS_FAST_HR_TSTAMP", \
"PCPS_HAS_RAW_IRIG_DATA", \
"PCPS_HAS_PZF", \
- "PCPS_HAS_EVT_LOG" \
+ "PCPS_HAS_EVT_LOG", \
+ "PCPS_IS_GNSS" \
}
-/** @} */
+/** @} defgroup group_pcps_features */
@@ -1228,6 +1214,10 @@ enum
#define PCPS_FEAT_WVB600USB ( PCPS_FEAT_WWVB51USB )
+#define PCPS_FEAT_GLN180PEX ( PCPS_FEAT_GPS180PEX | PCPS_IS_GNSS )
+
+#define PCPS_FEAT_GPS180AMC ( PCPS_FEAT_GPS180PEX )
+
// Some features of the API used to access Meinberg plug-in devices
// have been implemented starting with the special firmware revision
// numbers defined below.
@@ -1323,9 +1313,11 @@ enum
/**
- The structure has been defined to pass all
- information on a clock device from a device driver
- to a user program. */
+ * @brief Device info structure
+ *
+ * Used to pass all information on a bus-level device
+ * from a device driver to a user space application.
+ */
typedef struct
{
PCPS_DEV_TYPE type;
@@ -1356,6 +1348,7 @@ typedef struct
#define _pcps_is_irig_rx( _d ) ( _pcps_ref_type( _d ) == PCPS_REF_IRIG )
#define _pcps_is_ptp( _d ) ( _pcps_ref_type( _d ) == PCPS_REF_PTP )
#define _pcps_is_frc( _d ) ( _pcps_ref_type( _d ) == PCPS_REF_FRC )
+#define _pcps_is_gnss( _d ) _pcps_has_feature( (_d), PCPS_IS_GNSS )
#define _pcps_is_lwr( _d ) ( _pcps_is_dcf( _d ) || _pcps_is_msf( _d ) || _pcps_is_wwvb( _d ) )
@@ -1405,10 +1398,10 @@ typedef struct
#define _pcps_clr_err_flags( _d, _msk ) ( _pcps_err_flags( _d ) &= ~(_msk) )
-// Query whether a special feature is supported:
+/// Check whether a special feature is supported
#define _pcps_has_feature( _d, _f ) ( ( (_d)->cfg.features & (_f) ) != 0 )
-// Query whether a special feature is supported according to RECEIVER_INFO:
+/// Check whether a special feature is supported according to ::RECEIVER_INFO
#define _pcps_has_ri_feature( _p_ri, _f ) ( ( (_p_ri)->features & (_f) ) != 0 )
@@ -1516,6 +1509,13 @@ typedef struct
#define _pcps_has_stat_info_svs( _d ) _pcps_is_gps( _d )
+#define _pcps_has_ri_gpio( _p_ri ) _pcps_has_ri_feature( (_p_ri), GPS_HAS_GPIO )
+
+// We only report that XMR is supported if all required features are supported.
+#define _pcps_has_ri_xmr( _p_ri ) ( _pcps_has_ri_feature( (_p_ri), GPS_HAS_XMULTI_REF ) && \
+ _pcps_has_ri_feature( (_p_ri), GPS_HAS_XMRS_MULT_INSTC ) )
+//##++++++++++ should also check GPS_MODEL_HAS_XMR_HOLDOVER_INTV, which is a builtin featur flag only
+
// There are some versions of IRIG receiver cards which ignore the TFOM code
@@ -1524,7 +1524,7 @@ typedef struct
// signal even if the TFOM code reports the IRIG generator is not synchronized.
// The intended behaviour is that the IRIG receiver card changes its status
// to "freewheeling" in this case, unless it has been configured to ignore
-// the TFOM code of the incoming IRIG signal (see the IFLAGS_DISABLE_TFOM flag
+// the TFOM code of the incoming IRIG signal (see the ::IFLAGS_DISABLE_TFOM flag
// defined in gpsdefs.h).
// The macro below can be used to check based on the device info if a specific
@@ -1568,13 +1568,16 @@ typedef struct
/**
- The structure is used to return info
- on the device driver.*/
+ * @brief Device driver information
+ *
+ * Used to pass info on the device driver to
+ * a user space application.
+ */
typedef struct
{
- uint16_t ver_num; /**< the device driver's version number */
- uint16_t n_devs; /**< the number of radio clocks handled by the driver */
- PCPS_ID_STR id_str; /**< the device driver's ID string */
+ uint16_t ver_num; ///< the device driver's version number
+ uint16_t n_devs; ///< the number of devices handled by the driver
+ PCPS_ID_STR id_str; ///< the device driver's ID string
} PCPS_DRVR_INFO;
@@ -1588,10 +1591,11 @@ typedef struct
/**
- The structure is used to read the current time from
- a device, combined with an associated PC cycle counter value
- to compensate program execution time.
- */
+ * @brief Time read from a device plus associated system cycles count
+ *
+ * Contains current time from a device, plus an associated PC
+ * cycles counter value useful to compensate execution time.
+ */
typedef struct
{
MBG_PC_CYCLES cycles;
@@ -1601,9 +1605,11 @@ typedef struct
/**
- The structure is used to read a high resolution UTC time stamp
- plus associated PC cycles counter value to compensate the latency.
- */
+ * @brief High resolution time stamp plus associated system cycles count
+ *
+ * Contains current high resolution UTC time stamp from a device, plus
+ * an associated PC cycles counter value useful to compensate execution time.
+ */
typedef struct
{
MBG_PC_CYCLES cycles;
@@ -1619,10 +1625,12 @@ typedef struct
/**
- The structure is used to read the current high resolution time
- from a device, combined with an associated PC cycle counter value
- to compensate program execution time.
- */
+ * @brief High resolution time plus associated system cycles count
+ *
+ * Contains current high resolution UTC time from a device, including
+ * local time offset and status, plus an associated PC cycles counter value
+ * useful to compensate execution time.
+ */
typedef struct
{
MBG_PC_CYCLES cycles;
@@ -1638,16 +1646,19 @@ typedef struct
/**
- The structure below can be used to let the kernel driver read
- the current system time plus the associated HR time from a plugin card
- as close as possibly, and return the results to a user space application
- which can then compute the time difference and latencies.
- This structure also contains the card's status information (e.g. sync status).
- */
+ * @brief High resolution device time, system time, and associated cycles counts
+ *
+ * Used to let the kernel driver read the current system time plus the associated
+ * high resolution time from a bus-level device as close as possible, and return
+ * the results to the caller which can then compute the time difference, taking
+ * into account the latencies determined from the cycles counts.
+ *
+ * This structure also contains the card's status information (e.g. sync status).
+ */
typedef struct
{
- PCPS_HR_TIME_CYCLES ref_hr_time_cycles; /**< HR time read from the card, plus cycles */
- MBG_SYS_TIME_CYCLES sys_time_cycles; /**< system timestamp plus associated cycles */
+ PCPS_HR_TIME_CYCLES ref_hr_time_cycles; ///< HR time read from the card, plus cycles
+ MBG_SYS_TIME_CYCLES sys_time_cycles; ///< system time stamp plus associated cycles
} MBG_TIME_INFO_HRT;
#define _mbg_swab_mbg_time_info_hrt( _p ) \
@@ -1659,18 +1670,20 @@ typedef struct
/**
- The structure below can be used to let the kernel driver read
- the current system time plus an associated HR timestamp from a plugin card
- as close as possibly, and return the results to a user space application
- which can then compute the time difference and latencies.
- Since the card's time stamp is usually taken using the fast memory mapped
- access this structure does *not* contain the card's status information
- (e.g. sync status).
- */
+ * @brief High resolution device time stamp, system time, and associated cycles counts
+ *
+ * Used to let the kernel driver read the current system time plus the associated
+ * high resolution time stamp from a bus-level device as close as possible, and return
+ * the results to the caller which can then compute the time difference, taking
+ * into account the latencies determined from the cycles counts.
+ *
+ * Since the card's time stamp is taken from the fast memory mapped registers
+ * this structure does *not* contain the card's status information (e.g. sync status).
+ */
typedef struct
{
- PCPS_TIME_STAMP_CYCLES ref_tstamp_cycles; /**< HR timestamp from the card, plus cycles */
- MBG_SYS_TIME_CYCLES sys_time_cycles; /**< system timestamp plus associated cycles */
+ PCPS_TIME_STAMP_CYCLES ref_tstamp_cycles; ///< HR timestamp from the card, plus cycles
+ MBG_SYS_TIME_CYCLES sys_time_cycles; ///< system timestamp plus associated cycles
} MBG_TIME_INFO_TSTAMP;
#define _mbg_swab_mbg_time_info_tstamp( _p ) \
@@ -1702,6 +1715,102 @@ typedef uint32_t PCPS_IRQ_STAT_INFO;
#undef _USING_BYTE_ALIGNMENT
#endif
+
+// We must use native alignment here!
+
+// The structure below is used by the IOCTL_PCPS_GENERIC_... calls.
+
+#if defined( MBG_TGT_LINUX )
+ #if defined( MBG_ARCH_ARM ) || defined( MBG_ARCH_SPARC )
+ #define USE_IOCTL_GENERIC_REQ 0
+ #endif
+#endif
+
+#if defined( MBG_TGT_WIN32 )
+ // required for 32bit/64 bit compatibility
+ #define USE_IOCTL_GENERIC_REQ 0
+#endif
+
+#if !defined( USE_IOCTL_GENERIC_REQ )
+ #define USE_IOCTL_GENERIC_REQ 1
+#endif
+
+
+#if USE_IOCTL_GENERIC_REQ
+
+/**
+ * @brief A structure used to pass generic IOCTL requests to the kernel driver
+ *
+ * @note This does not work properly under Linux/Sparc where the kernel
+ * may be 64 bit while user space is 32 bit, which leads to different sizes
+ * for pointers and size_t.
+ */
+typedef struct
+{
+ ulong info;
+ const void *in_p;
+ size_t in_sz;
+ void *out_p;
+ size_t out_sz;
+
+} IOCTL_GENERIC_REQ;
+
+#define _MBG_IOG( _t, _n, _s ) _MBG_IOW( _t, _n, _s )
+
+#else
+
+/**
+ * @brief Control structure used for generic IOCTL requests
+ *
+ * Used by the IOCTL_PCPS_GENERIC_... calls.
+ *
+ * @note Is slower, but avoids OS-specific problems occurring
+ * with IOCTL_GENERIC_REQ.
+ */
+typedef struct
+{
+ uint32_t info;
+ uint32_t data_size_in;
+ uint32_t data_size_out;
+} IOCTL_GENERIC_CTL;
+
+
+/**
+ * @brief Data buffer used for generic IOCTL requests
+ *
+ * Used by the IOCTL_PCPS_GENERIC_... calls.
+ *
+ * @note Is slower, but avoids OS-specific problems occurring
+ * with IOCTL_GENERIC_REQ.
+ */
+typedef struct
+{
+ IOCTL_GENERIC_CTL ctl;
+ uint8_t data[1];
+} IOCTL_GENERIC_BUFFER;
+
+#define _MBG_IOG( _t, _n, _s ) _MBG_IO( _t, _n )
+
+#endif
+
+
+
+#if !defined( MBG_TGT_KERNEL )
+
+static __mbg_inline
+void setup_hr_time_cycles_from_timestamp_cycles( PCPS_HR_TIME_CYCLES *p_ht_c,
+ const PCPS_TIME_STAMP_CYCLES *p_ts_c )
+{
+ memset( p_ht_c, 0, sizeof( *p_ht_c ) );
+
+ p_ht_c->t.tstamp = p_ts_c->tstamp;
+ p_ht_c->cycles = p_ts_c->cycles;
+
+} // setup_hr_time_cycles_from_timestamp_cycles
+
+#endif
+
+
/* End of header body */
#undef _ext
diff --git a/c/mbglib/include/usbdefs.h b/c/mbglib/include/usbdefs.h
index e0e21e2..9280d9f 100644
--- a/c/mbglib/include/usbdefs.h
+++ b/c/mbglib/include/usbdefs.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: usbdefs.h 1.17 2012/08/08 07:53:29Z daniel TRASH $
+ * $Id: usbdefs.h 1.21.1.4 2014/05/05 12:57:43Z paul TRASH $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -10,6 +10,22 @@
*
* -----------------------------------------------------------------------
* $Log: usbdefs.h $
+ * Revision 1.21.1.4 2014/05/05 12:57:43Z paul
+ * Added class code for SCG
+ * Revision 1.21.1.3 2014/04/10 12:56:29Z martin
+ * Removed obsolete multiple definitions for FTDI serial interface chips.
+ * Added a new definition for unique FTDI chip.
+ * Revision 1.21.1.2 2014/02/05 14:55:44 martin
+ * Revision 1.21.1.1 2014/01/24 13:02:18 martin
+ * Tmp. saved changes.
+ * Revision 1.21 2014/01/16 15:26:09 daniel
+ * Added class codes and devices for USB to serial adapters and ASIX network chips
+ * Revision 1.20 2013/10/08 09:13:04 daniel
+ * Added definition and class code for RSC.
+ * Revision 1.19 2013/06/04 10:45:53 daniel
+ * Added class codes and device IDs for IMS devices MRI and BPE
+ * Revision 1.18 2013/01/24 11:29:21 joerg
+ * Added class code and device ID for LNE-GB
* Revision 1.17 2012/08/08 07:53:29Z daniel
* Added class code and device ID for LIU
* Revision 1.16 2012/02/13 09:29:59 paul
@@ -63,14 +79,14 @@ extern "C" {
#endif
-/* Meinberg's USB vendor ID number (assigned by USB-IF Administration) */
+/** Meinberg's USB vendor ID number (assigned by USB-IF administration) */
#define USB_VENDOR_MEINBERG 0x1938
-/*
- * USB device class codes (assigned by Meinberg)
+/**
+ * @brief USB device class codes assigned by Meinberg
*/
-enum
+enum MBG_USB_CLASS_CODES
{
MBG_USB_CLASS_NONE, // (unknown or not defined)
MBG_USB_CLASS_CPC, // Control Panel Controller
@@ -82,20 +98,32 @@ enum
MBG_USB_CLASS_WWVB, // WWVB Radio Clock
MBG_USB_CLASS_SCU, // Meinberg Signal Changeover Unit
MBG_USB_CLASS_ESI, // External Synchronization Interface
- MBG_USB_CLASS_FCU, // Fan Control Unit
+ MBG_USB_CLASS_FCU, // Fan Control Unit
MBG_USB_CLASS_CPE, // Configurable Port Expander
MBG_USB_CLASS_GPS, // GPS Receiver
MBG_USB_CLASS_LNO, // Low Phase Noise Option
- MBG_USB_CLASS_LIU, // Line Interface Unit
+ MBG_USB_CLASS_LIU, // Line Interface Unit
+ MBG_USB_CLASS_LNE, // LNE-GB
+ MBG_USB_CLASS_MRI, // MRS Input card for IMS
+ MBG_USB_CLASS_BPE, // IMS Backplane Port Expander
+ MBG_USB_CLASS_RSC, // RSC Redundant Switch Control
+ MBG_USB_CLASS_SERIAL, // USB to Serial controller
+ MBG_USB_CLASS_SCG, // Studio Clock Generator
+
+ MBG_USB_CLASS_NIC = 0x17, // ASIX AX88179 Network interface chips on LNE
+
N_MBG_USB_CLASS // number of known device class codes
};
-/*
- * USB device ID numbers (assigned by Meinberg)
- * High byte: USB device class as specified above
- * Low byte: enumeration of device of a class
- */
+/**
+ * @brief USB device ID numbers assigned by Meinberg
+ *
+ * High byte: USB device class, see ::MBG_USB_CLASS_CODES<br>
+ * Low byte: enumeration of devices of a class
+ *
+ * @anchor MBG_USB_DEVICE_IDS @{ */
+
#define USB_DEV_CPC_01 ( ( MBG_USB_CLASS_CPC << 8 ) | 0x01 )
#define USB_DEV_TSU_01 ( ( MBG_USB_CLASS_TSU << 8 ) | 0x01 )
@@ -128,6 +156,68 @@ enum
#define USB_DEV_LIU_01 ( ( MBG_USB_CLASS_LIU << 8 ) | 0x01 )
+#define USB_DEV_LNE_01 ( ( MBG_USB_CLASS_LNE << 8 ) | 0x01 )
+
+#define USB_DEV_MRI_01 ( ( MBG_USB_CLASS_MRI << 8 ) | 0x01 )
+
+#define USB_DEV_BPE_01 ( ( MBG_USB_CLASS_BPE << 8 ) | 0x01 )
+
+#define USB_DEV_RSC_01 ( ( MBG_USB_CLASS_RSC << 8 ) | 0x01 )
+
+/// LANTIME CPU quad FTDI serial interface chip
+#define USB_DEV_LAN_CPU_SERIAL ( ( MBG_USB_CLASS_SERIAL << 8 ) | 0x01 )
+
+#define USB_DEV_SCG_01 ( ( MBG_USB_CLASS_SCG << 8 ) | 0x01 )
+
+/** @} anchor MBG_USB_DEVICE_IDS */
+
+
+/**
+ * @brief Device name strings for Meinberg USB devices
+ *
+ * @see @ref MBG_USB_DEVICE_IDS
+ *
+ * @anchor MBG_USB_DEVICE_NAMES @{ */
+
+#if 0 //##++++++++++++ TODO
+
+#define USB_DEV_CPC_01 ( ( MBG_USB_CLASS_CPC << 8 ) | 0x01 )
+#define USB_DEV_TSU_01 ( ( MBG_USB_CLASS_TSU << 8 ) | 0x01 )
+#define USB_DEV_USB5131 ( ( MBG_USB_CLASS_DCF << 8 ) | 0x01 )
+#define USB_DEV_DCF600USB ( ( MBG_USB_CLASS_DCF << 8 ) | 0x02 )
+#define USB_DEV_CMC ( ( MBG_USB_CLASS_CMC << 8 ) | 0x01 )
+#define USB_DEV_TCR51USB ( ( MBG_USB_CLASS_TCR << 8 ) | 0x01 )
+#define USB_DEV_TCR600USB ( ( MBG_USB_CLASS_TCR << 8 ) | 0x02 )
+#define USB_DEV_MSF51USB ( ( MBG_USB_CLASS_MSF << 8 ) | 0x01 )
+#define USB_DEV_MSF600USB ( ( MBG_USB_CLASS_MSF << 8 ) | 0x02 )
+#define USB_DEV_WWVB51USB ( ( MBG_USB_CLASS_WWVB << 8 ) | 0x01 )
+#define USB_DEV_WVB600USB ( ( MBG_USB_CLASS_WWVB << 8 ) | 0x02 )
+#define USB_DEV_SCU_USB ( ( MBG_USB_CLASS_SCU << 8 ) | 0x01 )
+#define USB_DEV_ESI_01 ( ( MBG_USB_CLASS_ESI << 8 ) | 0x01 )
+#define USB_DEV_FCU_01 ( ( MBG_USB_CLASS_FCU << 8 ) | 0x01 )
+
+#define USB_DEV_CPE_01 ( ( MBG_USB_CLASS_CPE << 8 ) | 0x01 )
+
+#define USB_DEV_GPS180 ( ( MBG_USB_CLASS_GPS << 8 ) | 0x01 )
+
+#define USB_DEV_LNO180_01 ( ( MBG_USB_CLASS_LNO << 8 ) | 0x01 )
+
+#define USB_DEV_LIU_01 ( ( MBG_USB_CLASS_LIU << 8 ) | 0x01 )
+
+#define USB_DEV_LNE_01 ( ( MBG_USB_CLASS_LNE << 8 ) | 0x01 )
+
+#define USB_DEV_MRI_01 ( ( MBG_USB_CLASS_MRI << 8 ) | 0x01 )
+
+#define USB_DEV_BPE_01 ( ( MBG_USB_CLASS_BPE << 8 ) | 0x01 )
+
+#define USB_DEV_RSC_01 ( ( MBG_USB_CLASS_RSC << 8 ) | 0x01 )
+
+#define USB_DEV_LAN_CPU_SERIAL ( ( MBG_USB_CLASS_SERIAL << 8 ) | 0x01 )
+
+#endif
+
+/** @} anchor MBG_USB_DEVICE_NAMES */
+
enum
{
diff --git a/c/mbglib/include/use_pack.h b/c/mbglib/include/use_pack.h
index 16950fa..cef3d97 100644
--- a/c/mbglib/include/use_pack.h
+++ b/c/mbglib/include/use_pack.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: use_pack.h 1.3 2011/01/26 10:01:41Z martin REL_M $
+ * $Id: use_pack.h 1.5 2012/10/12 12:40:01Z martin REL_M $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -11,7 +11,11 @@
*
* -----------------------------------------------------------------------
* $Log: use_pack.h $
- * Revision 1.3 2011/01/26 10:01:41Z martin
+ * Revision 1.5 2012/10/12 12:40:01Z martin
+ * Removed temporary changes.
+ * Revision 1.4 2012/10/02 18:06:25 martin
+ * Temporary changes to test alignment under Linux/Sparc.
+ * Revision 1.3 2011/01/26 10:01:41 martin
* Provided a way to suppress packing of structures on a project base.
* Revision 1.2 2002/02/25 08:50:33 Andre
* query __ARM added, __SH2 removed
diff --git a/c/mbglib/include/words.h b/c/mbglib/include/words.h
index 2174160..d41fe76 100644
--- a/c/mbglib/include/words.h
+++ b/c/mbglib/include/words.h
@@ -1,7 +1,7 @@
/**************************************************************************
*
- * $Id: words.h 1.29 2012/07/11 16:45:45Z martin REL_M $
+ * $Id: words.h 1.33 2014/05/27 10:18:35Z martin REL_M $
*
* Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
*
@@ -10,6 +10,20 @@
*
* -----------------------------------------------------------------------
* $Log: words.h $
+ * Revision 1.33 2014/05/27 10:18:35Z martin
+ * Finer control of which types are required for or already
+ * available on particular target systems.
+ * Added macros helpful to simplify declarations of code/name tables.
+ * Revision 1.32 2014/01/07 15:43:52 martin
+ * Define __mbg_inline for ARM firmware targets.
+ * Revision 1.31 2012/11/29 11:54:39Z martin
+ * Removed #if sizeof() definitions which may cause build errors
+ * with some older compilers.
+ * Include stdbool.h for __ARMCC_VERSION targets.
+ * Moved _nop_macro_fnc() definition here.
+ * Revision 1.30 2012/11/02 09:12:29Z martin
+ * Moved most feature detection code to mbg_tgt.h.
+ * Tried to define missing features most flexibly and portably.
* Revision 1.29 2012/07/11 16:45:45Z martin
* New macros to access individual bytes of long constants.
* Revision 1.28 2012/04/05 14:36:18Z martin
@@ -89,23 +103,33 @@
#if !defined( _IS_MBG_FIRMWARE )
-#if defined( _C166 ) || \
- defined( _CC51 ) || \
- defined( __ARM ) || \
- defined( __ARMCC_VERSION )
- #define _IS_MBG_FIRMWARE 1
-#else
- #define _IS_MBG_FIRMWARE 0
-#endif
-
+ #if defined( _C166 ) || \
+ defined( _CC51 ) || \
+ defined( __ARM ) || \
+ defined( __ARMCC_VERSION )
+ #define _IS_MBG_FIRMWARE 1
+ #else
+ #define _IS_MBG_FIRMWARE 0
+ #endif
#endif
+
#if !_IS_MBG_FIRMWARE
#include <mbg_tgt.h>
+#else
+ #if defined( __ARMCC_VERSION ) // Keil RealView Compiler for ARM
+ #define __mbg_inline __inline
+ #include <stdint.h>
+ #include <stdbool.h>
+ #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1
+ #else
+ #define MBG_TGT_MISSING_64_BIT_TYPES 1
+ #endif
#endif
+
#ifdef _WORDS
#define _ext
#else
@@ -115,120 +139,60 @@
/* Start of header body */
-
-// The compilers below support native bit types.
-
-#if defined( _C166 ) || defined( _CC51 )
- #define _BIT_DEFINED 1
+#if defined( _C166 ) \
+ || defined( _CC51 )
+ #define _BIT_DEFINED 1 // these compilers natively support the "bit" type
+ #define USE_LONG_FOR_INT32 1
#endif
-// Check whether the target system supports C99 fixed-size types.
-
-#if defined( MBG_TGT_LINUX ) // any Linux target
+#if !defined( MBG_TGT_HAS_EXACT_SIZE_TYPES )
- #if defined( __KERNEL__ )
- #include <linux/types.h>
- #else
- #include <stdint.h>
- #include <sys/types.h>
- #endif
+ #if defined( MBG_TGT_HAS_INT_8_16_32 )
- #define _C99_BIT_TYPES_DEFINED 1
+ // Define C99 exact size types using non-standard exact-size types
+ typedef __int8 int8_t;
+ typedef unsigned __int8 uint8_t;
-#elif defined( MBG_TGT_BSD )
+ typedef __int16 int16_t;
+ typedef unsigned __int16 uint16_t;
- #include <sys/types.h>
-
- #define _C99_BIT_TYPES_DEFINED 1
- #define _MISSING_STDBOOL_H 1
-
-#elif defined( MBG_TGT_QNX ) // QNX 4.x or QNX 6.x
-
- #if defined( MBG_TGT_QNX_NTO ) // QNX 6.x (Neutrino) with gcc
- #include <stdint.h>
- #else // QNX 4.x with Watcom C 10.6
- #include <sys/types.h> // 64 bit types not supported
- #endif
-
- #define _C99_BIT_TYPES_DEFINED 1
-
-#endif
+ typedef __int32 int32_t;
+ typedef unsigned __int32 uint32_t;
+ #else
+ // Assume a 16 or 32 bit compiler which doesn't
+ // support exact-size types.
-// If it's not yet clear whether fixed-size types are supported,
-// check the build environment which may be multi-platform.
+ typedef char int8_t;
+ typedef unsigned char uint8_t;
-#if !defined( _C99_BIT_TYPES_DEFINED )
+ typedef short int16_t;
+ typedef unsigned short uint16_t;
- #if defined( __WATCOMC__ )
- #if ( __WATCOMC__ > 1230 ) // Open Watcom C 1.3 and above
- #include <stdint.h>
- #define _C99_BIT_TYPES_DEFINED 1
- #elif defined( __WATCOM_INT64__ ) // Watcom C 11, non-QNX
- typedef __int64 int64_t;
- typedef unsigned __int64 uint64_t;
+ // Using #if sizeof() to determine the size of a type may not
+ // be supported by all preprocessors, and may even result in
+ // build errors if used in a conditional preprocessor section,
+ // so we can't use this here without compatibility problems.
- #define _C99_BIT_TYPES_DEFINED 1
+ #if defined( USE_LONG_FOR_INT32 )
+ typedef long int32_t;
+ typedef unsigned long uint32_t;
+ #elif defined( USE_INT_FOR_INT32 )
+ typedef int int32_t;
+ typedef unsigned int uint32_t;
+ #else
+ #error Need to define int32_t and uint32_t
#endif
- #endif
-
- #if defined( __BORLANDC__ )
- #if ( __BORLANDC__ >= 0x570 ) // at least Borland Developer Studio 2006
- #define _C99_BIT_TYPES_DEFINED 1
- #endif
- #endif
-
- #if defined( __GNUC__ )
- #include <stdint.h>
- #define _C99_BIT_TYPES_DEFINED 1
- #endif
- #if defined( __ARMCC_VERSION ) // Keil RealView Compiler for ARM
- #include <stdint.h>
- #define _C99_BIT_TYPES_DEFINED 1
- #endif
-
- #if defined( _CVI_ ) && ( _CVI_ >= 1000 )
- #include <stdint.h>
- #define _C99_BIT_TYPES_DEFINED 1
- #define _MISSING_STDBOOL_H 1
#endif
-#endif
-
-
-// If neither the target system nor the build environment define C99 fixed-size
-// types define those types based on standard types with the proper sizes
-// commonly used in 16/32 bit environments.
-
-#if defined( _C99_BIT_TYPES_DEFINED )
-
- #define MBG_TGT_HAS_64BIT_TYPES 1
-
-#else
-
- typedef char int8_t;
- typedef unsigned char uint8_t;
-
- typedef short int16_t;
- typedef unsigned short uint16_t;
-
- typedef long int32_t;
- typedef unsigned long uint32_t;
-
+ #if defined( MBG_TGT_MISSING_64_BIT_TYPES )
- #if defined( MBG_TGT_WIN32 )
-
- typedef __int64 int64_t;
- typedef unsigned __int64 uint64_t;
-
- #define MBG_TGT_HAS_64BIT_TYPES 1
-
- #else
- // The types below are required to avoid build errors
+ // The build environment does not support 64 bit types. However,
+ // 64 bit types need to be defined to avoid build errors
// if these types are formally used in function prototypes.
// We explicitely use abnormal data types to hopefully
// cause compiler errors in case these types are
@@ -236,61 +200,101 @@
// platform which does not support 64 bit types.
typedef void *int64_t;
typedef void *uint64_t;
+
+ #else
+
+ // Define C99 types using non-standard exact-size types
+ // which are usually supported by build envonronments
+ // supporting 64 bit types but no C99 types.
+ typedef __int64 int64_t;
+ typedef unsigned __int64 uint64_t;
+
#endif
#endif
-#if !defined( MBG_TGT_HAS_64BIT_TYPES )
+#if defined( MBG_TGT_MISSING_64_BIT_TYPES )
#define MBG_TGT_HAS_64BIT_TYPES 0
+#else
+
+ #define MBG_TGT_HAS_64BIT_TYPES 1
+
#endif
// Some commonly used types
-typedef unsigned char uchar;
+#if !defined( _UCHAR_DEFINED )
+ typedef unsigned char uchar;
+ #define uchar uchar
+#endif
-#if !defined( MBG_TGT_LINUX ) && !( defined ( MBG_TGT_NETBSD ) && defined ( MBG_TGT_KERNEL ) )
+#if !defined( _USHORT_DEFINED )
typedef unsigned short ushort;
+ #define ushort ushort
+#endif
+
+#if !defined( _UINT_DEFINED )
typedef unsigned int uint;
+ #define uint uint
+#endif
+
+#if !defined( _ULONG_DEFINED )
typedef unsigned long ulong;
+ #define ulong ulong
#endif
-typedef double udouble;
+#if !defined( _UDOUBLE_DEFINED )
+ typedef double udouble;
+ #define udouble udouble
+#endif
-typedef unsigned char byte;
-typedef unsigned short word;
-typedef unsigned long longword;
-typedef unsigned long dword;
+#if !defined( _BYTE_DEFINED )
+ typedef unsigned char byte;
+ #define byte byte
+#endif
+#if !defined( _WORD_DEFINED )
+ typedef unsigned short word;
+ #define word word
+#endif
-#if !defined( _BIT_DEFINED )
+#if !defined( _LONGWORD_DEFINED )
+ typedef unsigned long longword;
+ #define longword longword
+#endif
- #if _C99_BIT_TYPES_DEFINED
+#if !defined( _DWORD_DEFINED )
+// typedef unsigned long dword;
+// #define dword dword
+#endif
- #if !defined( _MISSING_STDBOOL_H )
- #include <stdbool.h>
- #endif
- #if !defined( __bool_true_false_are_defined )
- #if !defined( __cplusplus )
- #define bool _Bool
- #define true 1
- #define false 0
- #define __bool_true_false_are_defined 1
- #endif
+#if !defined( _BIT_DEFINED )
- #endif
+ // We need to implement a "bit" type. Preferably we use "bool"
+ // to do this, but this is only supported by C++ compilers, and
+ // by C compilers supporting the C99 standard.
+
+ #if !defined( MBG_TGT_MISSING_BOOL_TYPE ) && \
+ ( defined( __cplusplus ) || defined( __bool_true_false_are_defined ) )
typedef bool bit;
+ #define bit bit
- #else
+ #else // C99 types not supported
+ // Falling back to use "int" for "bit". This prevents error
+ // messages if "bit" is used in function prototypes, but may
+ // yield unexpected results for code like:
+ // return (bit) ( val & 0x10 );
typedef int bit;
+ #define bit bit
#endif
@@ -299,17 +303,17 @@ typedef unsigned long dword;
#endif
-#define BYTE_0( _x ) ( ( (ulong) (_x) ) & 0xFF )
-#define BYTE_1( _x ) ( ( ( (ulong) (_x) ) >> 8 ) & 0xFF )
-#define BYTE_2( _x ) ( ( ( (ulong) (_x) ) >> 16 ) & 0xFF )
-#define BYTE_3( _x ) ( ( ( (ulong) (_x) ) >> 24 ) & 0xFF )
+#define BYTE_0( _x ) ( (uint8_t ) ( (_x) & 0xFF ) )
+#define BYTE_1( _x ) ( (uint8_t ) ( ( ( (uint16_t) (_x) ) >> 8 ) & 0xFF ) )
+#define BYTE_2( _x ) ( (uint8_t ) ( ( ( (uint32_t) (_x) ) >> 16 ) & 0xFF ) )
+#define BYTE_3( _x ) ( (uint8_t ) ( ( ( (uint32_t) (_x) ) >> 24 ) & 0xFF ) )
-#define HI_BYTE( _x ) ( (_x) >> 8 )
-#define LO_BYTE( _x ) ( (_x) & 0xFF )
+#define HI_BYTE( _x ) ( (uint8_t ) ( (_x) >> 8 ) )
+#define LO_BYTE( _x ) ( (uint8_t ) ( (_x) & 0xFF ) )
-#define HI_WORD( _x ) ( (_x) >> 16 )
-#define LO_WORD( _x ) ( (_x) & 0xFFFF )
+#define HI_WORD( _x ) ( (uint16_t ) ( (_x) >> 16 ) )
+#define LO_WORD( _x ) ( (uint16_t ) ( (_x) & 0xFFFF ) )
// the macros below assume little endianess
// these macros expect the name of a variable
@@ -366,6 +370,15 @@ typedef unsigned long dword;
#endif
+// A macro function which can safely be used without
+// side effects as a macro doing nothing.
+// This is useful to define debug macros away in
+// release builds, etc.
+#if !defined( _nop_macro_fnc )
+ #define _nop_macro_fnc() do {} while (0)
+#endif
+
+
/**
* @brief A table entry which can be used to map codes to names.
*/
@@ -375,6 +388,21 @@ typedef struct
const char *name;
} MBG_CODE_NAME_TABLE_ENTRY;
+/**
+ * @brief A macro defining a ::MBG_CODE_NAME_TABLE_ENTRY
+ *
+ * The stringified parameter is used for the name.
+ *
+ * @param _n The symbolic name of the numeric code
+ */
+#define _mbg_cn_table_entry( _n ) { _n, #_n }
+
+/**
+ * @brief A macro defining an empty ::MBG_CODE_NAME_TABLE_ENTRY
+ *
+ * This is used to terminate a table.
+ */
+#define _mbg_cn_table_end() { 0, NULL }
/* End of header body */
diff --git a/c/mbglib/lib/bc/mbgsvcio.lib b/c/mbglib/lib/bc/mbgsvcio.lib
index 33ac0fa..86b966f 100644
--- a/c/mbglib/lib/bc/mbgsvcio.lib
+++ b/c/mbglib/lib/bc/mbgsvcio.lib
Binary files differ
diff --git a/c/mbglib/lib/msc/mbgsvcio.lib b/c/mbglib/lib/msc/mbgsvcio.lib
index e49df2b..c4987be 100644
--- a/c/mbglib/lib/msc/mbgsvcio.lib
+++ b/c/mbglib/lib/msc/mbgsvcio.lib
Binary files differ
generated by cgit v1.2.3 (git 2.25.1) at 2024-05-18 21:37:51 +0000