diff options
| author | Martin Burnicki <martin.burnicki@meinberg.de> | 2021-11-11 12:15:03 +0100 |
|---|---|---|
| committer | Martin Burnicki <martin.burnicki@meinberg.de> | 2022-07-08 17:21:00 +0200 |
| commit | e5ee94dce7833995f72247cf59301030aae0f8b7 (patch) | |
| tree | a786b9aa0351491e52ff16cd8d41b7353ab0b6f5 | |
| parent | 9a8df188e29ba8f12326be0c0be806fb0cce940a (diff) | |
| download | mbgtools-win-e5ee94dce7833995f72247cf59301030aae0f8b7.tar.gz mbgtools-win-e5ee94dce7833995f72247cf59301030aae0f8b7.zip | |
Update existing mbglib files
55 files changed, 15543 insertions, 5703 deletions
diff --git a/mbglib/common/cfg_hlp.c b/mbglib/common/cfg_hlp.c index 5be0080..b97fc77 100644 --- a/mbglib/common/cfg_hlp.c +++ b/mbglib/common/cfg_hlp.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: cfg_hlp.c 1.4 2018/09/19 16:55:08Z martin REL_M $ + * $Id: cfg_hlp.c 1.5 2019/09/27 14:16:40Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,15 @@ * * ----------------------------------------------------------------------- * $Log: cfg_hlp.c $ + * Revision 1.5 2019/09/27 14:16:40Z martin + * Merged changes from 1.3.1.33: + * Support for next gen PTP config API added by thomas-b. + * XMR improvements by philipp. + * Sys ref API definitions by thomas-b. + * Network address conversion functions added by gregoire.diehl. + * New functions were added, and existing functions were improved. + * Use new types MBG_MSG_IDX and MBG_MSG_IDX_32. + * Lots of doxygen updates and fixes. * Revision 1.4 2018/09/19 16:55:08Z martin * Account for renamed global variables. * Revision 1.3 2018/07/05 10:28:07Z martin @@ -52,9 +61,16 @@ #include <cfg_hlp.h> #undef _CFG_HLP +#if defined( MBG_TGT_UNIX ) + #include <arpa/inet.h> + #include <str_util.h> + #include <math.h> +#endif + #include <mbgerror.h> #include <timeutil.h> #include <str_util.h> +#include <lan_util.h> #include <myutil.h> #include <mbgtime.h> @@ -71,7 +87,7 @@ /*HDR*/ /** - * @brief Check if a software revision name should be displayed + * @brief Check if a software revision name should be displayed. * * The software revision name is usually empty, except if the * firmware is a customized version, in which case the field @@ -79,12 +95,12 @@ * * There are some standard firmware versions where this string * is not empty but padded with spaces, etc., so we try to - * clean this up and display the string properly, if appropriate. + * clean this up, so it can be displayed appropriately. * - * @param[in,out] p The ::SW_REV name to check - * @param[in] verbose The app's verbosity level + * @param[in,out] p The ::SW_REV name to check. + * @param[in] verbose The app's verbosity level. * - * @return != 0 if SW name should be displayed + * @return != 0 if SW name should be displayed. */ int chk_sw_rev_name( SW_REV *p, int verbose ) { @@ -110,6 +126,16 @@ int chk_sw_rev_name( SW_REV *p, int verbose ) /*HDR*/ +/** + * @brief Search a string table for a specific string. + * + * @param[in] search The string to be searched for in table @a str_table. + * @param[in] str_table A table of strings like 'const char *strs[N_STRS]'. + * @param[in] n_entries The number of strings in table @a str_table. + * + * @return The index number of the string table entry matching the @a search string, + * or -1 if the @a search string could not be found. + */ int get_str_idx( const char *search, const char *str_table[], int n_entries ) @@ -127,6 +153,14 @@ int get_str_idx( const char *search, /*HDR*/ +/** + * @brief Search the ::mbg_baud_rates table for a specific baud rate. + * + * @param[in] baud_rate The baud_rate to be searched for. + * + * @return The index number of the specific @a baud_rate in table ::mbg_baud_rates, + * or -1 if the specific @a baud_rate could not be found. + */ int get_baud_rate_idx( BAUD_RATE baud_rate ) { int i; @@ -142,6 +176,14 @@ int get_baud_rate_idx( BAUD_RATE baud_rate ) /*HDR*/ +/** + * @brief Search the ::mbg_framing_strs table for a specific framing string. + * + * @param[in] framing The framing string to be searched for, e.g. "8N1". + * + * @return The index number of the specific @a framing in table ::mbg_framing_strs, + * or -1 if the specific @a framing could not be found. + */ int get_framing_idx( const char *framing ) { return get_str_idx( framing, mbg_framing_strs, N_MBG_FRAMINGS ); @@ -154,13 +196,13 @@ int get_framing_idx( const char *framing ) /** * @brief Convert ::PORT_PARM::mode to ::PORT_SETTINGS::mode * - * This function is used to evaluate the code from a mode field of a legacy + * This function is used to evaluate the code from a @a mode field of a legacy * ::PORT_PARM structure and set up the appropriate fields in a ::PORT_SETTINGS - * structure accordingly. + * structure. * * @param[out] p_ps Pointer to a ::PORT_SETTINGS structure to be updated. * @param[in] pp_mode The mode code from a ::PORT_PARM structure, see ::LGCY_STR_MODES. - * @param[in] cap_str_idx The capture string index number for the case that @p pp_mode is + * @param[in] cap_str_idx The capture string index number for the case that @a pp_mode is * a capture string mode. Usually 1 for legacy devices. * * @ingroup cfg_hlp_com_parm_cnv_fncs @@ -172,7 +214,7 @@ void port_settings_from_port_parm_mode( PORT_SETTINGS *p_ps, uint8_t pp_mode, { if ( pp_mode >= LGCY_STR_UCAP ) { - // If @p pp_mode is ::LGCY_STR_UCAP or greater + // If @a pp_mode is ::LGCY_STR_UCAP or greater // then the string is a capture string which // can have the mode ::STR_AUTO or ::STR_ON_REQ, // and the string type is a capture string, which @@ -182,7 +224,7 @@ void port_settings_from_port_parm_mode( PORT_SETTINGS *p_ps, uint8_t pp_mode, } else { - // If @p pp_mode is less than ::LGCY_STR_UCAP + // If @a pp_mode is less than ::LGCY_STR_UCAP // then the string is the default time string, // the format of which depends on the firmware // version if the device is legacy. @@ -231,7 +273,7 @@ void port_parm_mode_from_port_settings( uint8_t *pp_mode, const PORT_SETTINGS *p /*HDR*/ /** - * @brief Set up a ::PORT_SETTINGS structure from a legacy ::PORT_PARM structure + * @brief Set up a ::PORT_SETTINGS structure from a legacy ::PORT_PARM structure. * * @param[out] p_ps Pointer to a ::PORT_SETTINGS structure to be updated. * @param[in] port_idx Index number of the port settings to be converted. @@ -258,7 +300,7 @@ void port_settings_from_port_parm( PORT_SETTINGS *p_ps, int port_idx, /*HDR*/ /** - * @brief Set up a a legacy ::PORT_PARM structure from a ::PORT_SETTINGS structure + * @brief Set up a a legacy ::PORT_PARM structure from a ::PORT_SETTINGS structure. * * @param[out] p_pp Pointer to a ::PORT_PARM structure to be updated. * @param[in] port_idx Index number of the port settings to be converted. @@ -284,6 +326,19 @@ void port_parm_from_port_settings( PORT_PARM *p_pp, int port_idx, /*HDR*/ +/** + * @brief Check if all serial port capabilities reported by a device are supported by the current driver. + * + * @param[in] p_pi Address of a ::PORT_INFO structure to be checked. + * @param[out] str_type_info_idx An array of ::STR_TYPE_INFO_IDX structures supported by the device + * @param[in] n_str_type The number of entries in the @a str_type_info_idx array. + * + * @return A bit mask of @ref MBG_COM_CFG_STATUS_MASKS flags indicating which type of parameter + * may not be fully supported. Should be 0 if everything is OK. + * + * @see ::is_valid_port_info + * @see @ref MBG_COM_CFG_STATUS_MASKS + */ uint32_t check_valid_port_info( const PORT_INFO *p_pi, const STR_TYPE_INFO_IDX str_type_info_idx[], int n_str_type ) @@ -364,9 +419,21 @@ uint32_t check_valid_port_info( const PORT_INFO *p_pi, /*HDR*/ -int valid_port_info( const PORT_INFO *p_pi, - const STR_TYPE_INFO_IDX str_type_info_idx[], - int n_str_type ) +/** + * @brief Check if the content of a ::PORT_INFO structure is known and valid. + * + * @param[in] p_pi Address of a ::PORT_INFO structure to be checked. + * @param[in] str_type_info_idx An array of string type information. + * @param[in] n_str_type The number of entries in the @a str_type_info_idx array. + * + * @return @a true if the ::PORT_INFO structure contains valid data, + * else @a false. + * + * @see ::check_valid_port_info + */ +bool is_valid_port_info( const PORT_INFO *p_pi, + const STR_TYPE_INFO_IDX str_type_info_idx[], + int n_str_type ) { return check_valid_port_info( p_pi, str_type_info_idx, n_str_type ) == 0; @@ -376,23 +443,25 @@ int valid_port_info( const PORT_INFO *p_pi, /*HDR*/ /** - * @brief Setup an array of ::PORT_INFO_IDX structures from a ::PORT_PARM + * @brief Setup an array of ::PORT_INFO_IDX structures from a ::PORT_PARM. * * Some legacy GPS receivers that don't provide a ::RECEIVER_INFO structure * also provide a ::PORT_PARM structure with the current serial port settings - * only. This function sets up an array of ::PORT_INFO_IDX structures with the + * only. + * + * This function sets up an array of ::PORT_INFO_IDX structures with the * associated settings, and fills up the remaining ::PORT_INFO fields with - * the well-known supported settings, so applications can simple deal with + * the well-known supported settings, so applications can simply deal with * the current API structures. * - * @param[out] pii Array with p_ri->n_com_ports ::PORT_INFO_IDX elements to be filled up. - * @param[in] p_pp Pointer to a ::PORT_PARM structure providing the current COM port settings + * @param[out] pii Array with @a p_ri->n_com_ports ::PORT_INFO_IDX elements to be filled up. + * @param[in] p_pp Pointer to a ::PORT_PARM structure providing the current COM port settings. * @param[in] p_ri Pointer to a ::RECEIVER_INFO structure providing the number of supported COM ports. * - * @return One of the @ref MBG_RETURN_CODES, but actually always ::MBG_SUCCESS. + * @return One of the @ref MBG_RETURN_CODES, but actually always ::MBG_SUCCESS. * * @ingroup cfg_hlp_com_parm_cnv_fncs - * @see setup_port_parm ::FIXME + * @see setup_default_str_type_info_idx */ int setup_port_info_from_port_parm( PORT_INFO_IDX pii[], const PORT_PARM *p_pp, const RECEIVER_INFO *p_ri ) @@ -419,6 +488,25 @@ int setup_port_info_from_port_parm( PORT_INFO_IDX pii[], const PORT_PARM *p_pp, /*HDR*/ +/** + * @brief Setup an array of ::STR_TYPE_INFO_IDX for well-known string types. + * + * Some legacy GPS receivers that don't provide a ::RECEIVER_INFO structure + * also don't support the ::STR_TYPE_INFO structure to indicate which serial + * string formats are supported. + * + * This function sets up an array of ::STR_TYPE_INFO_IDX structures with the + * well-known supported string types, so applications can simply deal with + * the current API structures. + * + * @param[out] stii Array with at least @a p_ri->n_str_type ::STR_TYPE_INFO_IDX elements to be filled up. + * @param[in] p_ri Pointer to a ::RECEIVER_INFO structure providing the number of supported COM ports. + * + * @return One of the @ref MBG_RETURN_CODES, but actually always ::MBG_SUCCESS. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::setup_port_info_from_port_parm + */ int setup_default_str_type_info_idx( STR_TYPE_INFO_IDX stii[], const RECEIVER_INFO *p_ri ) { int i; @@ -437,6 +525,19 @@ int setup_default_str_type_info_idx( STR_TYPE_INFO_IDX stii[], const RECEIVER_IN /*HDR*/ +/** + * @brief Determine how many GNSS systems are marked to be supported. + * + * This function counts the number of bits that are set to indicate + * that specific GNSS types (GPS, GLONASS, Galileo, ...) are supported + * by the device, and sets up the ::ALL_GNSS_INFO::n_gnss_supp field + * accordingly. + * + * @param[in,out] p_agi Address of an ::ALL_GNSS_INFO structure to be updated. + * + * @return ::MBG_SUCCESS on success, or ::MBG_ERR_N_GNSS_EXCEEDS_SUPP if the + * number of bits that are set exceeds the number of known GNSS types. + */ int chk_set_n_gnss_supp( ALL_GNSS_INFO *p_agi ) { p_agi->n_gnss_supp = num_bits_set( p_agi->gnss_mode_info.supp_gnss_types ); @@ -452,11 +553,14 @@ int chk_set_n_gnss_supp( ALL_GNSS_INFO *p_agi ) /*HDR*/ /** - * @brief + * @brief Setup GNSS sat info from the legacy GPS ::STAT_INFO. * - * ### Setup GNSS info from stat_info so we can use the same printing routine + * This simplyifies further evaluation since e.g. a common + * display routine can be used. + * + * @param[in,out] p_agi Address of an ::ALL_GNSS_INFO structure to be updated. */ -void setup_gps_only_sat_info_idx_from_statinfo( ALL_GNSS_INFO *p_agi ) +void setup_gps_only_gnss_sat_info_idx_from_stat_info( ALL_GNSS_INFO *p_agi ) { STAT_INFO *p_si = &p_agi->stat_info; GNSS_SAT_INFO_IDX *p_gsii = &p_agi->gnss_sat_info_idx[GNSS_TYPE_GPS]; @@ -469,17 +573,20 @@ void setup_gps_only_sat_info_idx_from_statinfo( ALL_GNSS_INFO *p_agi ) p_gsi->svs_in_view = p_si->svs_in_view; p_gsi->good_svs = p_si->good_svs; -} // setup_gps_only_sat_info_idx_from_statinfo +} // setup_gps_only_gnss_sat_info_idx_from_stat_info /*HDR*/ /** - * @brief + * @brief Setup GNSS mode info from the legacy GPS ::STAT_INFO. + * + * This simplyifies further evaluation since e.g. a common + * display routine can be used. * - * Setup GNSS info from stat_info so we can use the same printing routine + * @param[in,out] p_agi Address of an ::ALL_GNSS_INFO structure to be updated. */ -int setup_gps_only_gnss_info_from_statinfo( ALL_GNSS_INFO *p_agi ) +int setup_gps_only_gnss_mode_info_from_stat_info( ALL_GNSS_INFO *p_agi ) { MBG_GNSS_MODE_INFO *p_gmi = &p_agi->gnss_mode_info; @@ -490,11 +597,11 @@ int setup_gps_only_gnss_info_from_statinfo( ALL_GNSS_INFO *p_agi ) memset( p_agi->gnss_sat_info_idx, 0, sizeof( p_agi->gnss_sat_info_idx ) ); - setup_gps_only_sat_info_idx_from_statinfo( p_agi ); + setup_gps_only_gnss_sat_info_idx_from_stat_info( p_agi ); return chk_set_n_gnss_supp( p_agi ); -} // setup_gps_only_gnss_info_from_statinfo +} // setup_gps_only_gnss_mode_info_from_stat_info @@ -591,14 +698,14 @@ const char *get_hw_id_from_fw_id( const char *fw_id ) /*HDR*/ /** - * @brief Returns the currently used ::MBG_IO_PORT_TYPE_INFO for the appropriate ::MBG_IO_PORT + * @brief Return the currently used ::MBG_IO_PORT_TYPE_INFO for the appropriate ::MBG_IO_PORT. * - * @param[in] port Pointer to the ::MBG_IO_PORT to search for port_type - * @param[in] port_type Enum value of ::MBG_IO_PORT_TYPES to search for in port (::MBG_IO_PORT) + * @param[in] port Pointer to the ::MBG_IO_PORT to search for port_type + * @param[in] port_type Enum value of ::MBG_IO_PORT_TYPES to search for in @a port (::MBG_IO_PORT) * - * @return Pointer to the ::MBG_IO_PORT_TYPE_INFO_IDX found, or NULL + * @return Pointer to the ::MBG_IO_PORT_TYPE_INFO_IDX found, or NULL. */ -MBG_IO_PORT_TYPE_INFO* get_io_port_type_info( const MBG_IO_PORT *port, +MBG_IO_PORT_TYPE_INFO *get_io_port_type_info( const MBG_IO_PORT *port, uint16_t port_type ) { unsigned i; @@ -631,13 +738,13 @@ MBG_IO_PORT_TYPE_INFO* get_io_port_type_info( const MBG_IO_PORT *port, /*HDR*/ /** - * @brief Initializes a ::MBG_TLV_ANNOUNCE structure + * @brief Initialize a ::MBG_TLV_ANNOUNCE structure. * - * @param[out] tlv Pointer to a ::MBG_TLV_ANNOUNCE structure - * @param[in] uid Unique sender ID used as identifier with all - * subsequent messages related to this transaction. - * @param[in] tlv_feat_type One of the ::MBG_TLV_FEAT_TYPES - * @param[in] total_bytes Total number of bytes of all upcoming TLVs + * @param[out] tlv Pointer to a ::MBG_TLV_ANNOUNCE structure. + * @param[in] uid Unique sender ID used as identifier with all + * subsequent messages related to this transaction. + * @param[in] tlv_feat_type One of the ::MBG_TLV_FEAT_TYPES. + * @param[in] total_bytes Total number of bytes of all upcoming TLVs. */ void mbg_tlv_announce_init( MBG_TLV_ANNOUNCE *tlv, MBG_TLV_UID uid, MBG_TLV_TYPE tlv_feat_type, uint32_t total_bytes ) @@ -656,14 +763,14 @@ void mbg_tlv_announce_init( MBG_TLV_ANNOUNCE *tlv, MBG_TLV_UID uid, /*HDR*/ /** - * @brief Initializes a ::MBG_TLV + * @brief Initialize a ::MBG_TLV structure. * - * @param[out] tlv Pointer to a valid ::MBG_TLV structure - * @param[in] uid Unique sender ID used as identifier for each further + * @param[out] tlv Pointer to a valid ::MBG_TLV structure. + * @param[in] uid Unique sender ID used as identifier for each further * TLV message related to this type. - * @param[in] tlv_type Type identifier, see ::MBG_TLV_TYPES - * @param[in] total_bytes Total number of bytes belonging to this - * TLV transaction (which is very likely split into several TLVs) + * @param[in] tlv_type Type identifier, see ::MBG_TLV_TYPES. + * @param[in] total_bytes Total number of bytes belonging to this TLV transaction + * (which is very likely split into several TLVs) */ void mbg_tlv_init( MBG_TLV *tlv, MBG_TLV_UID uid, MBG_TLV_TYPE tlv_type, uint32_t total_bytes ) @@ -684,13 +791,13 @@ void mbg_tlv_init( MBG_TLV *tlv, MBG_TLV_UID uid, /*HDR*/ /** - * @brief Initializes ::MBG_TLV_RCV_STATE structure + * @brief Initialize ::MBG_TLV_RCV_STATE structure. * - * @param[in,out] state Pointer to ::MBG_TLV_RCV_STATE structure - * @param[in] uid Unique sender ID used as identifier for each further - * TLV message related to this type. - * @param[in] total_bytes Total number of bytes belonging to this - * TLV transaction (which is very likely split into several TLVS) + * @param[out] state Pointer to ::MBG_TLV_RCV_STATE structure to be initialized. + * @param[in] uid Unique sender ID used as identifier for each further + * TLV message related to this type. + * @param[in] total_bytes Total number of bytes belonging to this TLV transaction + * (which is very likely split into several TLVS) */ void mbg_tlv_rcv_state_init( MBG_TLV_RCV_STATE *state, MBG_TLV_UID uid, uint32_t total_bytes ) { @@ -706,30 +813,51 @@ void mbg_tlv_rcv_state_init( MBG_TLV_RCV_STATE *state, MBG_TLV_UID uid, uint32_t /*HDR*/ -int mbg_snprint_revision( char *buf, size_t buflen, +/** + * @brief Print some Meinberg OS revision information into a string buffer. + * + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] prefix Pointer to an optional prefix string, or NULL. + * @param[in] suffix Pointer to an optional suff string, or NULL. + * @param[in] rev The revision code which will be split into major, minor, and patch version. + * + * @return Length of the string in the buffer. + * + * @see @ref group_ext_sys_info + */ +int mbg_snprint_revision( char *s, size_t max_len, const char *prefix, const char *suffix, - uint32_t rev) + uint32_t rev ) { - size_t bytes = 0; + size_t n = 0; uint32_t major, minor, patch; if ( prefix ) - bytes += snprintf_safe( &buf[bytes], buflen, "%s", prefix ); + n += snprintf_safe( &s[n], max_len - n, "%s", prefix ); _mbg_decode_revision( rev, major, minor, patch ); - bytes += snprintf_safe( &buf[bytes], buflen - bytes, "%u.%u.%u", - major, minor, patch); + + n += snprintf_safe( &s[n], max_len - n, "%u.%u.%u", + major, minor, patch); if ( suffix ) - bytes += snprintf_safe( &buf[bytes], buflen - bytes, "%s", suffix ); + n += snprintf_safe( &s[n], max_len - n, "%s", suffix ); - return _int_from_size_t( bytes ); + return _int_from_size_t( n ); } // mbg_snprint_revision /*HDR*/ +/** + * @brief Check if all ::RECEIVER_INFO capabilities reported by a device are supported by the current driver. + * + * @param[in] p Address of a ::RECEIVER_INFO structure to be checked. + * + * @return ::MBG_SUCCESS if everything is OK, one of the @ref MBG_ERROR_CODES, as appropriate. + */ _NO_MBG_API_ATTR int _MBG_API chk_dev_receiver_info( const RECEIVER_INFO *p ) { // Make sure this program supports at least as many serial ports @@ -766,7 +894,7 @@ _NO_MBG_API_ATTR int _MBG_API chk_dev_xbp_supp_nodes( const ALL_XBP_INFO *info ) return MBG_ERR_INV_PARM; -} // chk_dev_xbp_supp_nodes +} // chk_dev_xbp_supp_nodes @@ -778,7 +906,7 @@ _NO_MBG_API_ATTR int _MBG_API chk_dev_net_cfg_supp_stage_2( const ALL_NET_CFG_IN return MBG_ERR_NOT_SUPP_BY_DEV; -} // chk_dev_net_cfg_supp_stage_2 +} // chk_dev_net_cfg_supp_stage_2 @@ -791,7 +919,8 @@ _NO_MBG_API_ATTR int _MBG_API chk_dev_ntp_supp_client( const ALL_NTP_CFG_INFO *i return MBG_ERR_NOT_SUPP_BY_DEV; -} // chk_dev_ntp_supp_client +} // chk_dev_ntp_supp_client + /*HDR*/ @@ -803,89 +932,286 @@ _NO_MBG_API_ATTR int _MBG_API chk_dev_ntp_supp_server( const ALL_NTP_CFG_INFO *i return MBG_ERR_NOT_SUPP_BY_DEV; -} // chk_dev_ntp_supp_server +} // chk_dev_ntp_supp_server + + + +static __mbg_inline /*HDR*/ +/** + * @brief Check if a specific bit is set in ::XMULTI_REF_INSTANCES::flags. + * + * This indicates if a specific feature is supported. + * The ::XMULTI_REF_INSTANCES structure is part of an ::ALL_XMULTI_REF_INFO + * structure, namely ::ALL_XMULTI_REF_INFO::instances. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure + * of which to check the ::XMULTI_REF_INSTANCES::flags. + * + * @param[in] mask One of the ::XMR_INST_FLAG_BIT_MASKS. + * + * @return ::MBG_SUCCESS if the flag specified in @a mask is set, + * else ::MBG_ERR_NOT_SUPP_BY_DEV. + * + * @see ::XMR_INST_FLAG_BIT_MASKS + */ +int chk_mrs_instances_flags( const ALL_XMULTI_REF_INFO *info, int mask ) +{ + return ( info->instances.flags ) & mask ? MBG_SUCCESS :MBG_ERR_NOT_SUPP_BY_DEV; + +} // chk_mrs_instances_flags + /*HDR*/ +/** + * @brief Check if the ::XMULTI_EXT_REF_INSTANCES structure is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ +_NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_supp_ext_instances( const ALL_XMULTI_REF_INFO *info ) +{ + return chk_mrs_instances_flags( info, XMRIF_MSK_EXT_REF_INSTANCES_SUPP ); + +} // chk_dev_xmulti_supp_ext_instances + + + +/*HDR*/ +/** + * @brief Check if the ::XMULTI_EXT_REF_INSTANCES structure is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ +_NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_not_configurable( const ALL_XMULTI_REF_INFO *info ) +{ + return chk_mrs_instances_flags( info, XMRIF_MSK_NOT_CONFIGURABLE ); + +} // chk_dev_xmulti_not_configurable + + + +/*HDR*/ +/** + * @brief Check if the ::XMRIF_BIT_NO_STATUS bit is set. + * + * If this feature bit is set, ***no*** status, stats, etc., are provided. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS if the bit is set, or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ +_NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_no_status( const ALL_XMULTI_REF_INFO *info ) +{ + return chk_mrs_instances_flags( info, XMRIF_MSK_NO_STATUS ); + +} // chk_dev_xmulti_no_status + + + +/*HDR*/ +/** + * @brief Check if the ::XMRIF_BIT_MRF_NONE_SUPP bit is set. + * + * If this feature bit is set, the MRS pseudo-type ::MULTI_REF_NONE is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS if the bit is set, or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_mrf_none( const ALL_XMULTI_REF_INFO *info ) { - if ( ( info->instances.flags & XMRIF_MSK_MRF_NONE_SUPP ) == XMRIF_MSK_MRF_NONE_SUPP ) - return MBG_SUCCESS; + return chk_mrs_instances_flags( info, XMRIF_MSK_MRF_NONE_SUPP ); - return MBG_ERR_NOT_SUPP_BY_DEV; +} // chk_dev_xmulti_ref_supp_mrf_none -} // chk_dev_xmulti_ref_supp_mrf_none /*HDR*/ +/** + * @brief Check if the ::XMR_EXT_SRC_INFO structure is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_src_info( const ALL_XMULTI_REF_INFO *info ) { - if ( ( info->instances.flags & XMRIF_MSK_EXT_SRC_INFO_SUPP ) == XMRIF_MSK_EXT_SRC_INFO_SUPP ) - return MBG_SUCCESS; + return chk_mrs_instances_flags( info, XMRIF_MSK_EXT_SRC_INFO_SUPP ); - return MBG_ERR_NOT_SUPP_BY_DEV; +} // chk_dev_xmulti_ref_supp_ext_src_info -} // chk_dev_xmulti_ref_supp_ext_src_info /*HDR*/ +/** + * @brief Check if the ::::XMR_EXT_SRC_INFO structure is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_holdover_status( const ALL_XMULTI_REF_INFO *info ) { - if ( ( info->instances.flags & XMRIF_MSK_HOLDOVER_STATUS_SUPP ) == XMRIF_MSK_HOLDOVER_STATUS_SUPP ) - return MBG_SUCCESS; + return chk_mrs_instances_flags( info, XMRIF_MSK_HOLDOVER_STATUS_SUPP ); - return MBG_ERR_NOT_SUPP_BY_DEV; +} // chk_dev_xmulti_ref_supp_holdover_status + + + +static __mbg_inline /*HDR*/ +/** + * @brief Check if an MRS type code is valid. + * + * A valid type must be one of the currently defined ::MULTI_REF_TYPES, + * except ::MULTI_REF_NONE, which is < 0, or any other value which is + * less than ::MAX_N_MULTI_REF_TYPES. + * + * @param[in] type The MRS type code to be checked, see ::MULTI_REF_TYPES. + * + * @return @a true if the MRS type code is valid, else @a false. + * + * @see ::MULTI_REF_TYPES + */ +bool is_valid_mrs_type( int type ) +{ + return ( type >= 0 ) && ( type < MAX_N_MULTI_REF_TYPES ); + +} // is_valid_mrs_type + + + +static __mbg_inline /*HDR*/ +/** + * @brief Check if an extended MRS source feature is supported. + * + * Whether a feature is supported, or not, depends on whether a specific + * bit is set in the @a feat_flags field of the @a info field of the + * @a ext_src_infos array entry for the specified @a type. + * + * The bit masks of the features that can be checked are defined + * in ::XMR_EXT_SRC_FEAT_FLAG_MSKS. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure + * of which to check the @a ext_src_infos flags. + * + * @param[in] type A valid code of ::MULTI_REF_TYPES, see ::is_valid_mrs_type. + * + * @param[in] mask One of the ::XMR_EXT_SRC_FEAT_FLAG_MSKS. + * + * @return ::MBG_SUCCESS if the flag specified in @a mask is set, + * ::MBG_ERR_NOT_SUPP_BY_DEV if the bit is not set, or + * ::MBG_ERR_INV_PARM if the @a type is out of range. + * + * @see ::XMR_EXT_SRC_FEAT_FLAG_MSKS + */ +int chk_mrs_ext_src_feat( const ALL_XMULTI_REF_INFO *info, int type, int mask ) +{ + if ( !is_valid_mrs_type( type ) ) + return MBG_ERR_INV_PARM; + + return ( info->ext_src_infos[type].info.feat_flags & mask ) ? + MBG_SUCCESS : MBG_ERR_NOT_SUPP_BY_DEV; + +} // chk_mrs_ext_src_feat -} // chk_dev_xmulti_ref_supp_holdover_status /*HDR*/ -/* - * Type is NOT an index of ::XMULTI_REF_INSTANCES::n_xmr_settings, - * but of ::MULTI_REF_TYPES. - * Depends on chk_dev_supp_xmulti_ref_ext_src_info. - * @see chk_dev_supp_xmulti_ref_ext_src_info +/** + * @brief Check if an XMR source provides ::XMR_STATS. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * @param[in] type One of the ::MULTI_REF_TYPES, except ::MULTI_REF_NONE which is -1. + * + * @see ::chk_dev_supp_xmulti_ref_ext_src_info */ _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_source_stats( const ALL_XMULTI_REF_INFO *info, int type ) { - if ( - ( type < N_MULTI_REF ) && - (( info->ext_src_infos[type].info.feat_flags & XMR_EXT_SRC_FEAT_FLAG_MSK_STATS ) == XMR_EXT_SRC_FEAT_FLAG_MSK_STATS ) - ) return MBG_SUCCESS; + return chk_mrs_ext_src_feat( info, type, XMR_EXT_SRC_FEAT_FLAG_MSK_STATS ); - return MBG_ERR_NOT_SUPP_BY_DEV; +} // chk_dev_xmulti_ref_supp_ext_source_stats -} // chk_dev_xmulti_ref_supp_ext_source_stats /*HDR*/ -/* - * Type is NOT an index of ::XMULTI_REF_INSTANCES::n_xmr_settings, - * but of ::MULTI_REF_TYPES. - * Depends on chk_dev_supp_xmulti_ref_ext_src_info. - * @see chk_dev_supp_xmulti_ref_ext_src_info +/** + * @brief Check if an XMR source provides ::XMR_METRICS. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * @param[in] type One of the ::MULTI_REF_TYPES, except ::MULTI_REF_NONE which is -1. + * + * @see ::chk_dev_xmulti_ref_supp_ext_source_adv_metrics + * @see ::chk_dev_supp_xmulti_ref_ext_src_info */ _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_source_metrics( const ALL_XMULTI_REF_INFO *info, int type ) { - if ( - ( type < N_MULTI_REF ) && - (( info->ext_src_infos[type].info.feat_flags & XMR_EXT_SRC_FEAT_FLAG_MSK_METRICS ) == XMR_EXT_SRC_FEAT_FLAG_MSK_METRICS ) - ) return MBG_SUCCESS; + return chk_mrs_ext_src_feat( info, type, XMR_EXT_SRC_FEAT_FLAG_MSK_METRICS ); - return MBG_ERR_NOT_SUPP_BY_DEV; +} // chk_dev_xmulti_ref_supp_ext_source_metrics + + + +/*HDR*/ +/** + * @brief Check if an XMR source supports advanced XMR QL metrics configuration + * + * If this feature is not available, ::XMR_METRICS can not be configured. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * @param[in] type One of the ::MULTI_REF_TYPES, except ::MULTI_REF_NONE which is -1. + * + * @see ::XMR_QL_LIMITS + * @see ::chk_dev_xmulti_ref_supp_ext_source_metrics + * @see ::chk_dev_supp_xmulti_ref_ext_src_info + */ +_NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_source_adv_metrics( const ALL_XMULTI_REF_INFO *info, int type ) +{ + return chk_mrs_ext_src_feat( info, type, XMR_EXT_SRC_FEAT_FLAG_MSK_ADV_METRICS ); + +} // chk_dev_xmulti_ref_supp_ext_source_adv_metrics + + + +/*HDR*/ +/** + * @brief Check if an XMR source XMR source supports coasting mode. + * + * If this feature is not available, ::XMR_METRICS can not be configured. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * @param[in] type One of the ::MULTI_REF_TYPES, except ::MULTI_REF_NONE which is -1. + * + * @see ::XMR_QL_LIMITS + * @see ::chk_dev_supp_xmulti_ref_ext_src_info + */ +_NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_source_coasting( const ALL_XMULTI_REF_INFO *info, int type ) +{ + return chk_mrs_ext_src_feat( info, type, XMR_EXT_SRC_FEAT_FLAG_MSK_COASTING ); + +} // chk_dev_xmulti_ref_supp_ext_source_coasting -} // chk_dev_xmulti_ref_supp_ext_source_metrics /*HDR*/ _NO_MBG_API_ATTR int _MBG_API chk_dev_ims_has_fdm( const ALL_IMS_INFO *info ) { - if ( ( info->state.flags & MBG_IMS_STATE_FLAG_MSK_HAS_FDM ) == MBG_IMS_STATE_FLAG_MSK_HAS_FDM ) + if ( info->state.flags & MBG_IMS_STATE_FLAG_MSK_HAS_FDM ) return MBG_SUCCESS; return MBG_ERR_NOT_SUPP_BY_DEV; -} // chk_dev_ims_has_fdm +} // chk_dev_ims_has_fdm + /*HDR*/ @@ -893,14 +1219,13 @@ _NO_MBG_API_ATTR int _MBG_API chk_dev_ims_is_volt_out_enabled( const ALL_IMS_STA { const MBG_IMS_SENSOR_STATE *sstate = &ims_state->sensor_state_idx[idx].state; - if ( - ( sstate->type == MBG_IMS_SENSOR_VOLTAGE ) && - ( ( sstate->flags & MBG_IMS_SENSOR_VOLTAGE_OUT_ENB ) == MBG_IMS_SENSOR_VOLTAGE_OUT_ENB ) - ) return MBG_SUCCESS; + if ( ( sstate->type == MBG_IMS_SENSOR_VOLTAGE ) && ( sstate->flags & MBG_IMS_SENSOR_VOLTAGE_OUT_ENB ) ) + return MBG_SUCCESS; return MBG_ERR_NOT_SUPP_BY_DEV; -} // chk_dev_ims_is_volt_out_enabled +} // chk_dev_ims_is_volt_out_enabled + /*HDR*/ @@ -908,14 +1233,13 @@ _NO_MBG_API_ATTR int _MBG_API chk_dev_ims_is_volt_out_overload( const ALL_IMS_ST { const MBG_IMS_SENSOR_STATE *sstate = &ims_state->sensor_state_idx[idx].state; - if ( - ( sstate->type == MBG_IMS_SENSOR_VOLTAGE ) && - ( ( sstate->flags & MBG_IMS_SENSOR_VOLTAGE_OUT_OVR ) == MBG_IMS_SENSOR_VOLTAGE_OUT_OVR ) - ) return MBG_SUCCESS; + if ( ( sstate->type == MBG_IMS_SENSOR_VOLTAGE ) && ( sstate->flags & MBG_IMS_SENSOR_VOLTAGE_OUT_OVR ) ) + return MBG_SUCCESS; return MBG_ERR_NOT_SUPP_BY_DEV; -} // chk_dev_ims_is_volt_out_overload +} // chk_dev_ims_is_volt_out_overload + /*HDR*/ @@ -923,14 +1247,13 @@ _NO_MBG_API_ATTR int _MBG_API chk_dev_ims_is_pll_locked( const ALL_IMS_STATE *im { const MBG_IMS_SENSOR_STATE *sstate = &ims_state->sensor_state_idx[idx].state; - if ( - ( sstate->type == MBG_IMS_SENSOR_PLL ) && - ( ( sstate->flags & MBG_IMS_SENSOR_PLL_LOCKED ) == MBG_IMS_SENSOR_PLL_LOCKED ) - ) return MBG_SUCCESS; + if ( ( sstate->type == MBG_IMS_SENSOR_PLL ) && ( sstate->flags & MBG_IMS_SENSOR_PLL_LOCKED ) ) + return MBG_SUCCESS; return MBG_ERR_NOT_SUPP_BY_DEV; -} // chk_dev_ims_is_pll_locked +} // chk_dev_ims_is_pll_locked + /*HDR*/ @@ -938,12 +1261,13 @@ _NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_supp_ass_idx( const ALL_GPIO_INFO *gp { const MBG_GPIO_LIMITS *limits = &gpio_info->infos[idx].info.limits; - if ( ( limits->supp_flags & MSK_MBG_GPIO_DEPENDS_ON_ASS_IO_IDX ) == MSK_MBG_GPIO_DEPENDS_ON_ASS_IO_IDX ) + if ( limits->supp_flags & MSK_MBG_GPIO_DEPENDS_ON_ASS_IO_IDX ) return MBG_SUCCESS; return MBG_ERR_NOT_SUPP_BY_DEV; -} // chk_dev_gpio_supp_ass_idx +} // chk_dev_gpio_supp_ass_idx + /*HDR*/ @@ -951,19 +1275,21 @@ _NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_dep_on_ass_idx( const ALL_GPIO_INFO * { const MBG_GPIO_SETTINGS *settings = &gpio_info->infos[idx].info.settings; - if ( ( settings->flags & MSK_MBG_GPIO_DEPENDS_ON_ASS_IO_IDX ) == MSK_MBG_GPIO_DEPENDS_ON_ASS_IO_IDX ) + if ( settings->flags & MSK_MBG_GPIO_DEPENDS_ON_ASS_IO_IDX ) return MBG_SUCCESS; return MBG_ERR_NOT_SUPP_BY_DEV; -} // chk_dev_gpio_dep_on_ass_idx +} // chk_dev_gpio_dep_on_ass_idx + /*HDR*/ /** - * @brief Checks whether GPIO supports status function + * @brief Check whether GPIO provides a status. * - * @param[out] info Pointer to a ::ALL_GPIO_INFO structure to be filled up + * @param[out] info Pointer to a ::ALL_GPIO_INFO structure to be filled up ::FIXME + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. * * @return One of the @ref MBG_RETURN_CODES * @@ -973,12 +1299,12 @@ _NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_dep_on_ass_idx( const ALL_GPIO_INFO * */ _NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_has_status( const ALL_GPIO_INFO *info ) { - if ( ( info->cfg_limits.flags & MBG_GPIO_CFG_LIMIT_FLAG_MASK_STATUS_SUPP ) == MBG_GPIO_CFG_LIMIT_FLAG_MASK_STATUS_SUPP ) + if ( info->cfg_limits.flags & MBG_GPIO_CFG_LIMIT_FLAG_MASK_STATUS_SUPP ) return MBG_SUCCESS; return MBG_ERR_NOT_SUPP_BY_DEV; -} // chk_dev_gpio_has_status +} // chk_dev_gpio_has_status @@ -990,7 +1316,7 @@ _NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_has_status( const ALL_GPIO_INFO *info * * @see ::mbgextio_get_all_xbp_info */ -void free_all_xbp_info ( ALL_XBP_INFO *p ) +void free_all_xbp_info( ALL_XBP_INFO *p ) { if ( p ) { @@ -1003,7 +1329,7 @@ void free_all_xbp_info ( ALL_XBP_INFO *p ) free( p ); } -} // free_all_xbp_info +} // free_all_xbp_info @@ -1015,7 +1341,7 @@ void free_all_xbp_info ( ALL_XBP_INFO *p ) * * @see ::mbgextio_get_all_net_cfg_info */ -void free_all_net_cfg_info ( ALL_NET_CFG_INFO *p ) +void free_all_net_cfg_info( ALL_NET_CFG_INFO *p ) { if ( p ) { @@ -1037,7 +1363,7 @@ void free_all_net_cfg_info ( ALL_NET_CFG_INFO *p ) free( p ); } -} // free_all_net_cfg_info +} // free_all_net_cfg_info @@ -1049,7 +1375,7 @@ void free_all_net_cfg_info ( ALL_NET_CFG_INFO *p ) * * @see ::mbgextio_get_all_net_status_info */ -void free_all_net_status_info ( ALL_NET_STATUS_INFO *p ) +void free_all_net_status_info( ALL_NET_STATUS_INFO *p ) { if ( p ) { @@ -1071,7 +1397,7 @@ void free_all_net_status_info ( ALL_NET_STATUS_INFO *p ) free( p ); } -} // free_all_net_status_info +} // free_all_net_status_info @@ -1100,7 +1426,7 @@ void free_all_snmp_info ( ALL_SNMP_INFO *p ) free( p ); } -} // free_all_snmp_info +} // free_all_snmp_info @@ -1133,7 +1459,7 @@ void free_all_syslog_info ( ALL_SYSLOG_INFO *p ) free( p ); } -} // free_all_syslog_info +} // free_all_syslog_info @@ -1158,7 +1484,9 @@ void free_all_monitoring_info ( ALL_MONITORING_INFO *p ) free ( p ); } -} + +} // free_all_monitoring_info + /*HDR*/ @@ -1185,9 +1513,6 @@ void free_all_events( ALL_EVENTS *p ) if ( evt->release_backref ) evt->release_backref( evt ); - - if ( evt->dict_entries ) - free ( evt->dict_entries ); } free( p->events ); @@ -1195,7 +1520,9 @@ void free_all_events( ALL_EVENTS *p ) free ( p ); } -} + +} // free_all_events + /*HDR*/ @@ -1217,6 +1544,9 @@ void free_all_xmulti_ref_info( ALL_XMULTI_REF_INFO *p ) if ( p->ext_src_infos ) free( p->ext_src_infos ); + if ( p->ql_settings ) + free( p->ql_settings ); + free ( p ); } @@ -1373,6 +1703,123 @@ void free_all_ntp_status( ALL_NTP_STATUS *p ) /*HDR*/ /** + * @brief Free an ::ALL_PTP_NG_INFO structure + * + * @param[in] p Pointer to the ::ALL_PTP_NG_INFO structure to be freed + * + * @see ::mbgextio_get_all_ptp_ng_info + */ +void free_all_ptp_ng_info( ALL_PTP_NG_INFO *p ) +{ + if ( p ) + { + MBG_PTP_NG_UC_MASTER *uc_master; + MBG_PTP_NG_TSTAMPER *tstamper; + MBG_PTP_NG_INSTC *instc; + unsigned i; + + for (i = 0; i < p->glb_info.num_timestampers; ++i) + { + tstamper = &p->timestampers[i]; + + if ( tstamper->release_priv ) + tstamper->release_priv( tstamper ); + } + + for (i = 0; i < p->glb_info.settings.num_instances; ++i) + { + instc = &p->instances[i]; + + if ( instc->uc_slave_list ) + free( instc->uc_slave_list ); + + if ( instc->release_priv ) + instc->release_priv( instc ); + } + + for (i = 0; i < p->glb_info.settings.num_uc_masters; ++i) + { + uc_master = &p->uc_masters[i]; + + if ( uc_master->release_priv ) + uc_master->release_priv( uc_master ); + } + + if ( p->timestampers ) + free( p->timestampers ); + + if ( p->instances ) + free( p->instances ); + + if ( p->uc_masters ) + free( p->uc_masters ); + + free( p ); + } + +} // free_all_ptp_ng_info + + + +/*HDR*/ +/** + * @brief Free a list of ::MBG_SYS_REF_SRC structures + * + * @param[in] p Pointer to the ::MBG_SYS_REF_SRC list to be freed + * @param[in] free_source Address of a function to be called to free resources. + * + * @see ::mbgextio_get_all_sys_ref_info + * @see ::free_all_sys_ref_info + */ +void free_all_sys_ref_srcs( struct mbg_klist_head *p, + void (*free_source)( MBG_SYS_REF_SRC * ) ) +{ + struct mbg_klist_head *pos, *next; + MBG_SYS_REF_SRC *src; + + if ( !p || mbg_klist_is_empty( p ) ) + return; + + mbg_klist_for_each_safe( p, pos, next ) + { + src = mbg_container_of( pos, MBG_SYS_REF_SRC, head ); + + mbg_klist_delete_item( &src->head ); + if ( src->release_priv ) + src->release_priv( src ); + if ( free_source ) + free_source( src ); + else + free( src ); + } + +} // free_all_sys_ref_srcs + + + +/*HDR*/ +/** + * @brief Free an ::ALL_SYS_REF_INFO structure + * + * @param[in] p Pointer to the ::ALL_SYS_REF_INFO structure to be freed + * + * @see ::mbgextio_get_all_sys_ref_info + * @see ::free_all_sys_ref_srcs + */ +void free_all_sys_ref_info( ALL_SYS_REF_INFO *p ) +{ + if ( !p ) + return; + + free_all_sys_ref_srcs( &p->sources, p->free_source ); + free( p ); + +} // free_all_sys_ref_info + + + +/*HDR*/ +/** * @brief Free memory allocated by ::mbgextio_get_all_ims_info * * @param[in] p Pointer to the ::ALL_IMS_INFO structure to be freed @@ -1452,7 +1899,7 @@ void free_all_gpio_info( ALL_GPIO_INFO *p ) free( p ); } -} // free_all_gpio_info +} // free_all_gpio_info @@ -1494,7 +1941,8 @@ void free_all_io_ports( ALL_MBG_IO_PORTS *p ) free( p ); } -} // free_all_io_ports +} // free_all_io_ports + /*HDR*/ @@ -1518,7 +1966,7 @@ void free_all_gpio_state( ALL_GPIO_STATE *p ) free( p ); } -} // free_all_gpio_state +} // free_all_gpio_state @@ -1528,7 +1976,7 @@ void free_all_gpio_state( ALL_GPIO_STATE *p ) * * @return The new allocated ::UCAP_ENTRY or NULL if the calloc call was not successful */ -UCAP_ENTRY* calloc_ucap_entry( void ) +UCAP_ENTRY *calloc_ucap_entry( void ) { UCAP_ENTRY *entry = (UCAP_ENTRY *) calloc( 1, sizeof( *entry ) ); @@ -1537,7 +1985,8 @@ UCAP_ENTRY* calloc_ucap_entry( void ) return entry; -} // calloc_ucap_entry +} // calloc_ucap_entry + /*HDR*/ @@ -1569,7 +2018,8 @@ void free_all_ucap_info( ALL_UCAP_INFO *p ) free( p ); } -} // free_all_ucap_info +} // free_all_ucap_info + /*HDR*/ @@ -1590,7 +2040,7 @@ void free_all_ucap_net_info( ALL_UCAP_NET_INFO *p ) free( p ); } -} // free_all_ucap_net_info +} // free_all_ucap_net_info @@ -1627,7 +2077,8 @@ void free_all_user_info( ALL_USER_INFO *p ) free( p ); } -} + +} // free_all_user_info @@ -1664,7 +2115,9 @@ void free_all_svc_info( ALL_SERVICE_INFO *p ) free( p ); } -} + +} // free_all_svc_info + /*HDR*/ @@ -1707,7 +2160,8 @@ void free_all_firmware_info( ALL_FIRMWARE_INFO *p ) free( p ); } -} + +} // free_all_firmware_info @@ -1741,7 +2195,8 @@ void free_all_database_info( ALL_DATABASE_INFO *p ) } free( p ); -} + +} // free_all_database_info @@ -1816,3 +2271,1291 @@ void str_ntp_hex_to_nano_time_64( const char *s, NANO_TIME_64 *p ) #endif // !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + +#if defined( MBG_TGT_UNIX ) + +#define MAX_GRANTOR_PARAM_SIZE 256 +#define MAX_PARAM_STR_SIZE 64 + +/*HDR*/ +/** + * @brief Convert PTP binary config to Oregano config file + * + * @param[in] ptp_info Complete PTP config binary structure + * @param[in] instc PTP instance to write config for + * @param[in] inst_num PTP instance number on its timestamper + * @param[in] intf_lnk Associated interface link settings to determine VLAN ID + * @param[in] ip_addr Associated interface link settings to determine VLAN ID + * @param[in] ascii_file_name Target file name for the oregano cfg file + * + */ +_NO_MBG_API_ATTR int _MBG_API mbg_cnv_ptp_cfg_to_oreg_cfg_file( const ALL_PTP_NG_INFO *ptp_info, + const MBG_PTP_NG_INSTC *instc, + unsigned inst_num, + const MBG_NET_INTF_LINK_SETTINGS *intf_lnk, + const MBG_IP_ADDR *ip_addr, + const char *ascii_file_name ) +{ + char outStr[MAX_PARAM_STR_SIZE]; + int i; + + FILE* fileWrite = fopen(ascii_file_name, "w"); + + if ( fileWrite == NULL ) + return mbg_get_last_error( NULL ); + + + memset(outStr, 0, sizeof(outStr)); + + fprintf(fileWrite, "# Default Configuration File for the ptp stack\n"); + fprintf(fileWrite, "# File can be used as a commandline parameter, e.g: \"ptp default.cfg\"\n"); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# For your convenience, every configurable parameter is described in this\n"); + fprintf(fileWrite, "# default configuration file. Each parameter is commented out by a hash (#).\n"); + fprintf(fileWrite, "# If you want to use/configure specific parameters, just uncomment them\n"); + fprintf(fileWrite, "# by removing the hash (#). If not described otherwise, the value for a con-\n"); + fprintf(fileWrite, "# figuration parameter represents the default value of this parameter.\n"); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# Port Selection:\n"); + fprintf(fileWrite, "# Some syn1588(R)-products do have more than one configurable port.\n"); + fprintf(fileWrite, "# For each configured port, the section name \"port\" with a following port\n"); + fprintf(fileWrite, "# number (starting with 1) and a colon starts a new configuration section.\n"); + + fprintf(fileWrite, " port%u:\n", inst_num); + + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# profile: (string)\n"); + fprintf(fileWrite, "# The profile parameter has to be the first parameter after declaring\n"); + fprintf(fileWrite, "# a port (e.g. \"port 1:\") in a configuration file. It presets all\n"); + fprintf(fileWrite, "# parameters as defined in the respective profile. Afterwards, other\n"); + fprintf(fileWrite, "# parameters may be defined to overwrite the default values from the\n"); + fprintf(fileWrite, "# profile.\n"); + fprintf(fileWrite, "# Overwriting settings may result in non-standard compliant behaviour.\n"); + fprintf(fileWrite, "# Possible values for the parameter \"profile\" are:\n"); + fprintf(fileWrite, "# default ... use default profile (IEEE1588-2008 Annex J.3)\n"); + fprintf(fileWrite, "# default_p ... use P2P default profile (IEEE1588-2008 Annex J.4)\n"); + fprintf(fileWrite, "# power ... use power profile (C37.238 2011)\n"); + fprintf(fileWrite, "# power_s ... use power profile, slave only (C37.238 2011)\n"); + fprintf(fileWrite, "# power2 ... use power profile (C37.238 2014)\n"); + fprintf(fileWrite, "# power2_s ... use power profile, slave only (C37.238 2014)\n"); + fprintf(fileWrite, "# smpte ... use SMPTE profile (ST 2059-2)\n"); + fprintf(fileWrite, "# smpte_s ... use SMPTE profile, slave only (ST 2059-2)\n"); + fprintf(fileWrite, "# telecom ... use telecom profile, master only (G.8265.1)\n"); + fprintf(fileWrite, "# telecom2 ... *deprecated* use telecom profile (G.8275.1)\n"); + fprintf(fileWrite, "# use the following instead\n"); + fprintf(fileWrite, "# g8275_1 ... use telecom profile (G.8275.1), master only\n"); + fprintf(fileWrite, "# telecom2_s... *deprecated* use telecom profile, slave only (G.8275.1)\n"); + fprintf(fileWrite, "# use the following instead\n"); + fprintf(fileWrite, "# g8275_1_s... use telecom profile (G.8275.1), slave only\n"); + fprintf(fileWrite, "# 802.1as ... use gPTP profile (IEEE 802.1as)\n"); + fprintf(fileWrite, "# 802.1as_s ... use gPTP profile, slave only (IEEE 802.1as)\n"); + + { + switch(instc->settings->profile) + { + case PTP_PRESETS_POWER: + if ( instc->settings->role == PTP_ROLE_MULTICAST_SLAVE ) + fprintf(fileWrite, " profile power_s\n"); + else + fprintf(fileWrite, " profile power\n"); + break; + case PTP_PRESETS_C37238_2017: + if ( instc->settings->role == PTP_ROLE_MULTICAST_SLAVE ) + fprintf(fileWrite, " profile power2_s\n"); + else + fprintf(fileWrite, " profile power2\n"); + break; + case PTP_PRESETS_TELECOM_PHASE: + if ( instc->settings->role == PTP_ROLE_MULTICAST_SLAVE ) + fprintf(fileWrite, " profile g8275_1_s\n"); + else + fprintf(fileWrite, " profile g8275_1\n"); + break; + case PTP_PRESETS_TELECOM_PTS: + if ( instc->settings->role == PTP_ROLE_UNICAST_SLAVE ) + fprintf(fileWrite, " profile g8275_2_s\n"); + else + fprintf(fileWrite, " profile g8275_2\n"); + break; + case PTP_PRESETS_SMPTE: + if ( instc->settings->role == PTP_ROLE_MULTICAST_SLAVE || instc->settings->role == PTP_ROLE_UNICAST_SLAVE) + fprintf(fileWrite, " profile smpte_s\n"); + else + fprintf(fileWrite, " profile smpte\n"); + break; + case PTP_PRESETS_8021AS: + if ( instc->settings->role == PTP_ROLE_MULTICAST_SLAVE || instc->settings->role == PTP_ROLE_UNICAST_SLAVE) + fprintf(fileWrite, " profile 802.1as_s\n"); + else + fprintf(fileWrite, " profile 802.1as\n"); + break; + } + + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "#### Application Related Parameters ####\n"); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# filelog: (string)\n"); + fprintf(fileWrite, "# If status, warning and error messages should be logged to a file instead of\n"); + fprintf(fileWrite, "# stdout, specify a log-file-name at the 'filelog'-parameter.\n"); + fprintf(fileWrite, "# File system paths are supported too.\n"); + + fprintf(fileWrite, " filelog /var/log/ptpstack_%s.log\n", instc->settings->intf_label); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# loglevel: (0-4) [0]\n"); + fprintf(fileWrite, "# Sets the log level of the PTP Stack. Range from 0 (Errors only) to 4\n"); + fprintf(fileWrite, "# (all Debug output)\n"); + + //fprintf(fileWrite, " loglevel 2\n"); + fprintf(fileWrite, " loglevel %d\n", instc->settings->log_severity); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# logseverity: (bool) [false]\n"); + fprintf(fileWrite, "# If enabled, a severity string will be prepended to every log message.\n"); + fprintf(fileWrite, " #logseverity false\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# logstamp: (bool) [false]\n"); + fprintf(fileWrite, "# If enabled, a timestamp string will be prepended to every log message.\n"); + fprintf(fileWrite, " logstamp true\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# system_info: (bool) [false]\n"); + fprintf(fileWrite, "# Creates a system information report which contains information about\n"); + fprintf(fileWrite, "# the network setup and driver configurations. This file may be used to\n"); + fprintf(fileWrite, "# gather debugging information for contacting the Oregano Systems support.\n"); + fprintf(fileWrite, " #system_info false\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "#### Network Related Parameters ####\n"); + fprintf(fileWrite, "\n"); + + + fprintf(fileWrite, "#### G.8275.1 Related Parameters ####\n"); + fprintf(fileWrite, "\n"); + + if ( instc->settings->profile == PTP_PRESETS_TELECOM_PHASE ) + { + fprintf(fileWrite, "# alternative_mc_address: (bool) [false]\n"); + + fprintf(fileWrite, "# If layer2 trasnport mechanism is used it's possible to use different\n"); + fprintf(fileWrite, "# multicast addresses to transmit messages.\n"); + fprintf(fileWrite, "# Note: The P2P delay mechanism always uses the non-forwardable multicast\n"); + fprintf(fileWrite, "# address.\n"); + fprintf(fileWrite, "# false: 01:1B:19:00:00:00 (forwardable multicast address)\n"); + fprintf(fileWrite, "# true: 01:80:C2:00:00:0E (non-forwardable multicast address)\n"); + + if (instc->settings->profile_settings.g82751.flags & MBG_PTP_NG_82751_FLAG_USE_ALT_MC_ADDRESS_MSK) + fprintf(fileWrite, " alternative_mc_address true\n"); + else + fprintf(fileWrite, " alternative_mc_address false\n"); + + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# port_master_only: (bool) [false]\n"); + fprintf(fileWrite, "# The alternate BMCA of G.8275.1 considers the per-port Boolean attribute\n"); + fprintf(fileWrite, "# masterOnly. If masterOnly is TRUE, the port is never placed in the SLAVE\n"); + fprintf(fileWrite, "# state. If masterOnly is FALSE, the port can be placed in the SLAVE state.\n"); + fprintf(fileWrite, "# set when using the g8275_1 profile specifier to TRUE by default\n"); + + if (instc->settings->profile_settings.g82751.flags & MBG_PTP_NG_82751_FLAG_PORT_NOT_SLAVE_MSK) + fprintf(fileWrite, " port_master_only true\n"); + else + fprintf(fileWrite, " port_master_only false\n"); + + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# default_local_priority: (uint8_t) [128]\n"); + fprintf(fileWrite, "# The attribute localPriority is assigned to the local clock, to be used\n"); + fprintf(fileWrite, "# if needed when the data associated with the local clock, D0, is compared\n"); + fprintf(fileWrite, "# with data on another potential grandmaster received via an Announce\n"); + fprintf(fileWrite, "# message. Range is {1 - 255}. The default value is 128.\n"); + fprintf(fileWrite, "# default_local_priority %d\n", instc->settings->profile_settings.g82751.default_local_priority); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# port_local_priority: (uint8_t) [128]\n"); + fprintf(fileWrite, "# The per-port attribute localPriority is assigned to each port r of a\n"); + fprintf(fileWrite, "# clock and is used in the determination of Erbest and Ebest. This\n"); + fprintf(fileWrite, "# attribute is used as a tie-breaker in the dataset comparison algorithm,\n"); + fprintf(fileWrite, "# in the event that all other previous attributes of the datasets being\n"); + fprintf(fileWrite, "# compared are equal. Range is {1 - 255}. The default value is 128.\n"); + fprintf(fileWrite, "# port_local_priority %d\n", instc->settings->profile_settings.g82751.port_local_priority ); + fprintf(fileWrite, "\n"); + } + else + { + fprintf(fileWrite, " #alternative_mc_address false\n"); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, " #default_local_priority 128\n"); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, " #port_local_priority 128\n"); + fprintf(fileWrite, "\n"); + } + + fprintf(fileWrite, "# interface:\n"); + fprintf(fileWrite, "# The IP-Address (IPv4 or IPv6; windows and linux) or interface name\n"); + fprintf(fileWrite, "# (IPv4 or Layer2; linux only) of the desired\n"); + fprintf(fileWrite, "# of the Port you want to configure.\n"); + + if( ( instc->settings->protocol == PTP_NW_PROT_UDP_IPV6 ) && ( ip_addr->type == MBG_IP_ADDR_TYPE_IP6 ) ) + inet_ntop( AF_INET6, ip_addr->u_addr.ip6_addr.b, outStr, sizeof(outStr) ); + else + { + if (intf_lnk->type == MBG_NET_INTF_LINK_TYPE_VLAN ) + strncpy_safe( outStr, (char*)intf_lnk->name, sizeof(outStr) ); + else + strncpy_safe( outStr, (char*)instc->settings->intf_label, sizeof(outStr) ); + } + + fprintf(fileWrite, " interface %s\n", outStr); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# layer2: (bool) [false]\n"); + fprintf(fileWrite, "# This parameter enables PTP transport using IEEE802.3/Ethernet (layer 2).\n"); + fprintf(fileWrite, "# Layer 2 transport is only available in Linux and requires the interface\n"); + fprintf(fileWrite, "# name syntax (-i parameter).\n"); + + if( instc->settings->protocol == PTP_NW_PROT_IEEE_802_3 ) + fprintf(fileWrite, " layer2 true\n"); + else + fprintf(fileWrite, " layer2 false\n"); + + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# dsf: (uint8_t) [0]\n"); + fprintf(fileWrite, "# Allows to set the 8 bit differentiated service field of the IPv4 header (linux only).\n"); + fprintf(fileWrite, "# The first 6 bit (MSB) represent the Differentiated Services Codepoint (DSCP) and the\n"); + fprintf(fileWrite, "# last 2 bit the Explicit Congestion Notification (ECN).\n"); + fprintf(fileWrite, " dsf 0x%02X\n", instc->settings->dsf); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# swmode: (bool) [false]\n"); + fprintf(fileWrite, "# This parameter enables/forces pure software timestamping mode for the PTP Stack,\n"); + fprintf(fileWrite, "# even if there would be hardware timestamping support.\n"); + + if( instc->settings->flags & MBG_PTP_NG_FLAG_SW_TSTAMPING_MSK ) + fprintf(fileWrite, " swmode true\n"); + else + fprintf(fileWrite, " swmode false\n"); + + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# ipv6_multicast_scope: (0x0-0xe) [0]\n"); + fprintf(fileWrite, "# This parameter configures the IPv6 multicast scope to use.\n"); + fprintf(fileWrite, "# The default value 0 means autodetect.\n"); + fprintf(fileWrite, "# Refer to RFC 4291 for further details about IPv6 multicast scope.\n"); + fprintf(fileWrite, "#\n"); + fprintf(fileWrite, "# Autodetection:\n"); + fprintf(fileWrite, "# if the selected interface is link local, use link local scope multicast\n"); + fprintf(fileWrite, "# if the selected interface is NOT link local, use global scope multicast\n"); + fprintf(fileWrite, "#\n"); + + if ( ( instc->settings->ipv6_multicast_scope > 0 ) && ( instc->settings->ipv6_multicast_scope <= 0xE ) ) + fprintf(fileWrite, " ipv6_multicast_scope 0x%X\n", instc->settings->ipv6_multicast_scope); + else + fprintf(fileWrite, " ipv6_multicast_scope 0x00\n"); + + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# multicast_ttl: (1-255) [1]\n"); + fprintf(fileWrite, "# Sets the multicast time to live field in the IPv4 header or the multicast hop\n"); + fprintf(fileWrite, "# count in the IPv6 header respectively.\n"); + + fprintf(fileWrite, " multicast_ttl %d\n", instc->settings->multicast_ttl); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# unicast_ttl: (1-255) [64]\n"); + fprintf(fileWrite, "# Sets the unicast time to live field in the IPv4 header or the unicast hop\n"); + fprintf(fileWrite, "# count in the IPv6 header respectively.\n"); + + fprintf(fileWrite, " unicast_ttl %d\n", instc->settings->unicast_ttl); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# vlanid: (disbaled or 0-4095) [disabled]\n"); + fprintf(fileWrite, "# Configures a VLAN ID for the interace. This information is necessary for\n"); + fprintf(fileWrite, "# the timestamper.\n"); + fprintf(fileWrite, "# Note: The network interface must still be configured with the corresponding\n"); + fprintf(fileWrite, "# VLAN ID.\n"); + + if (intf_lnk->type == MBG_NET_INTF_LINK_TYPE_VLAN ) + fprintf(fileWrite, " vlanid %d\n", _decode_vlan_id(intf_lnk->vlan_cfg) ); + else + fprintf(fileWrite, " vlanid disabled\n"); + + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# card_index: (0-127) [0]\n"); + fprintf(fileWrite, "# This parameter is only considered when the Linux PTP hardware\n"); + fprintf(fileWrite, "# interface (PHC) is used. If the network adapter selected with the\n"); + fprintf(fileWrite, "# -i parameter supports the PHC interface, the syn1588(R) PTP Stack\n"); + fprintf(fileWrite, "# automatically tries to use this feature by opening the related ptp\n"); + fprintf(fileWrite, "# device. If there is more than one ptp device available, it tries to\n"); + fprintf(fileWrite, "# find the the appropriate device using an ethtool ioctl. If this fails\n"); + fprintf(fileWrite, "# (or is not available), this parameter allows to manually select the\n"); + fprintf(fileWrite, "# desired interface (/dev/ptpX).\n"); + fprintf(fileWrite, " #card_index 0\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "#### PTP Related Parameters ####\n"); + fprintf(fileWrite, "\n"); + + + fprintf(fileWrite, "# accuracy: (uint8_t) [0x27]\n"); + fprintf(fileWrite, "# Sets the clock accuracy field in the default dataset.\n"); + fprintf(fileWrite, "# This value will be used in the BMCA (third decision point)\n"); + fprintf(fileWrite, "# to determine the best master clock. (lower is better)\n"); + + if ( instc->settings->fixed_quality.clk_accuracy != 0 ) + fprintf(fileWrite, " accuracy 0x%x\n", instc->settings->fixed_quality.clk_accuracy); + else + fprintf(fileWrite, " accuracy 0xFE\n"); + + fprintf(fileWrite, "\n"); + + if( instc->settings->role != PTP_ROLE_UNICAST_SLAVE ) // will be set in Unicast Master config section + { + fprintf(fileWrite, "# announce_interval: (-5...5) [0]\n"); + fprintf(fileWrite, "# Sets the default logarithmic announce interval.\n"); + + fprintf(fileWrite, " announce_interval %d\n", instc->settings->intvs.ann_intv); + fprintf(fileWrite, "\n"); + } + + fprintf(fileWrite, "# announce_reception: [3]\n"); + fprintf(fileWrite, "# number of announce-messages which might be lost before a new\n"); + fprintf(fileWrite, "# master is selected\n"); + fprintf(fileWrite, "# set by this profile by default to a specified and valid value\n"); + + fprintf(fileWrite, " announce_reception %d\n", instc->settings->ann_rcpt_timeout); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# boundary_clock: (bool) [false]\n"); + fprintf(fileWrite, "# Enable boundary clock mode for this port.If true, this port will\n"); + fprintf(fileWrite, "# act as part of a boundary clock together with all other ports\n"); + fprintf(fileWrite, "# in this mode. The BMCA will not only consider one port, but all\n"); + fprintf(fileWrite, "# ports to determine the best master in a network as well as the\n"); + fprintf(fileWrite, "# the states of every individual port.\n"); + + fprintf(fileWrite, " # boundary_clock false\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# class: (uint8_t or string) [248]\n"); + fprintf(fileWrite, "# Sets the PTP clock class of the device. This parameter defines\n"); + fprintf(fileWrite, "# the clock's role in a network:\n"); + fprintf(fileWrite, "# M_EXT....Master on External Reference (6)\n"); + fprintf(fileWrite, "# M_HOLD...Master on External Reference (in Holdover) (7)\n"); + fprintf(fileWrite, "# M_NSYNC..Master on External Reference (not sync'd) (52)\n"); + fprintf(fileWrite, "# M_SLAVE..Master on External Reference (may be Slave) (187)\n"); + fprintf(fileWrite, "# S...Slave Only (255)\n"); + fprintf(fileWrite, "# This value will be used in the BMCA (second decision point)\n"); + fprintf(fileWrite, "# to determine the best master clock. (lower is better)\n"); + + if ( instc->settings->fixed_quality.clk_class_never_sync != 0 ) + fprintf(fileWrite, " class %d\n", instc->settings->fixed_quality.clk_class_never_sync); + else + fprintf(fileWrite, "# class 248\n"); + + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# delay_mechanism: (E2E,P2P,None) [E2E]\n"); + fprintf(fileWrite, "# Selects the used delay mechanism:\n"); + fprintf(fileWrite, "# E2E...End to End delay measurement\n"); + fprintf(fileWrite, "# P2P...Peer to Peer delay measurement\n"); + fprintf(fileWrite, "# None..No delay measurement (syntonization)\n"); + + switch ( instc->settings->delay_mech ) + { + case PTP_DELAY_MECH_E2E: + fprintf(fileWrite, " delay_mechanism E2E\n"); + break; + case PTP_DELAY_MECH_P2P: + fprintf(fileWrite, " delay_mechanism P2P\n"); + break; + default: + fprintf(fileWrite, " delay_mechanism E2E\n"); + break; + } + + fprintf(fileWrite, "\n"); + + if( instc->settings->role != PTP_ROLE_UNICAST_SLAVE ) // will be set in Unicast Master config section + { + fprintf(fileWrite, "# delay_request_offset: (0...5) [4]\n"); + fprintf(fileWrite, "# Sets the default logarithmic delay request offset relativ to\n"); + fprintf(fileWrite, "# the sync interval.\n"); + + if (instc->settings->delay_mech == PTP_DELAY_MECH_E2E) + fprintf(fileWrite, " delay_request_offset %d\n", instc->settings->intvs.del_req_intv - instc->settings->intvs.sync_intv); + else + fprintf(fileWrite, " #delay_request_offset 0\n"); + + fprintf(fileWrite, "\n"); + } + + fprintf(fileWrite, "# domain: (uint8_t) [0]\n"); + fprintf(fileWrite, "# Sets the PTP domain number.\n"); + fprintf(fileWrite, " domain %d\n", instc->settings->domain_number); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# enable_management: (bool) [true]\n"); + fprintf(fileWrite, "# Enables (true) or disables (false) PTP management support. If disabled,\n"); + fprintf(fileWrite, "# all PTP management messages are ignored.\n"); + + if( instc->settings->flags & MBG_PTP_NG_FLAG_MANAGEMENT_MSK ) + fprintf(fileWrite, " enable_management true\n"); + else + fprintf(fileWrite, " enable_management false\n"); + + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# fast_locking_boundary: (int32_t) [65536000]\n"); + fprintf(fileWrite, "# This parameter allows to set a fast locking boundary\n"); + fprintf(fileWrite, "# (offset between master and slave). This boundary is only used\n"); + fprintf(fileWrite, "# as slave and determines if fast locking is used after a master\n"); + fprintf(fileWrite, "# was selected or changed. If the current offset from the master\n"); + fprintf(fileWrite, "# is above the boundary, the fast locking process is started.\n"); + fprintf(fileWrite, "# once the boundary is reached/left.\n"); + fprintf(fileWrite, "# Attention: Fast locking causes the clock to jump by values up\n"); + fprintf(fileWrite, "# to a few microseconds.\n"); + fprintf(fileWrite, "# Specified in scaled nanoseconds (ns << 16), default value\n"); + fprintf(fileWrite, "# is 1000 ns (= 65536000 in scaled nanoseconds). A value of\n"); + fprintf(fileWrite, "# 0 disables fast locking entirely.\n"); + + fprintf(fileWrite, " # fast_locking_boundary %d\n",instc->settings->fast_locking_boundary ); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# grantor: (comma-seperated list of IP addresses)\n"); + fprintf(fileWrite, "# Configures the IPv4 or IPv6 address of PTP nodes which will be\n"); + fprintf(fileWrite, "# contacted for unicast connections. The local node will step\n"); + fprintf(fileWrite, "# through the list and try to establich a unicast negotiation with\n"); + fprintf(fileWrite, "# each node.\n"); + + + if( instc->settings->role == PTP_ROLE_UNICAST_SLAVE ) + { + size_t len; + char grantors[MAX_GRANTOR_PARAM_SIZE]; + int param_size = 0; + + memset( grantors, 0, sizeof(grantors) ); + memset( outStr, 0, sizeof(outStr) ); + + for ( i = 0; i < ptp_info->glb_info.settings.num_uc_masters; i++ ) + { + if ( ptp_info->uc_masters[i].instc == instc ) + { + if( instc->settings->protocol == PTP_NW_PROT_UDP_IPV6 ) + inet_ntop( AF_INET6, ptp_info->uc_masters[i].settings->grantor_addr, outStr, sizeof( outStr ) ); + else if ( instc->settings->protocol == PTP_NW_PROT_UDP_IPV4 ) + snprintf_safe( outStr, sizeof( outStr ), "%i.%i.%i.%i", + ptp_info->uc_masters[i].settings->grantor_addr[0], + ptp_info->uc_masters[i].settings->grantor_addr[1], + ptp_info->uc_masters[i].settings->grantor_addr[2], + ptp_info->uc_masters[i].settings->grantor_addr[3]); + else + snprintf_safe( outStr, sizeof( outStr ), "%02x:%02x:%02x:%02x:%02x:%02x", + ptp_info->uc_masters[i].settings->grantor_addr[0], + ptp_info->uc_masters[i].settings->grantor_addr[1], + ptp_info->uc_masters[i].settings->grantor_addr[2], + ptp_info->uc_masters[i].settings->grantor_addr[3], + ptp_info->uc_masters[i].settings->grantor_addr[4], + ptp_info->uc_masters[i].settings->grantor_addr[5]); + + param_size = MAX_GRANTOR_PARAM_SIZE - (IP6_ADDR_STR_SIZE + strlen(grantors)); + + // Check if maximum size of grantors param is already reached + if ( param_size > ( IP6_ADDR_STR_SIZE+1 ) ) + { + strncat( grantors, outStr, param_size ); + strncat( grantors, ",", param_size ); + } + + // only set duration once + if ( i == 0 ) + { + fprintf(fileWrite, "# unicast_duration: (uint32_t) [60]\n"); + fprintf(fileWrite, "# Sets the duration of a unicast connection before it is renegotiated. This\n"); + fprintf(fileWrite, "# parameter is only used when requesting a connection from a grantor.\n"); + fprintf(fileWrite, " unicast_duration %d\n", ptp_info->uc_masters[0].settings->message_duration); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# sync_interval: (-8...8) [0]\n"); + fprintf(fileWrite, "# Sets the default logarithmic sync message interval.\n"); + + fprintf(fileWrite, " sync_interval %d\n", ptp_info->uc_masters[0].settings->intvs.sync_intv); + fprintf(fileWrite, "\n"); + + if ( ( ptp_info->uc_masters[0].settings->intvs.sync_intv < -3 ) && ( ptp_info->uc_masters[0].settings->intvs.del_req_intv < -3 )) + { + fprintf(fileWrite, "lucky_filter_depth 2\n" ); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "lucky_packet_median %d\n", lucky_packet_median_nvals( ptp_info->uc_masters[0].settings->intvs.sync_intv ) ); + fprintf(fileWrite, "\n"); + } + + fprintf(fileWrite, "# announce_interval: (-5...5) [0]\n"); + fprintf(fileWrite, "# Sets the default logarithmic announce interval.\n"); + + fprintf(fileWrite, " announce_interval %d\n", ptp_info->uc_masters[0].settings->intvs.ann_intv); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# delay_request_offset: (0...5) [4]\n"); + fprintf(fileWrite, "# Sets the default logarithmic delay request offset relativ to\n"); + fprintf(fileWrite, "# the sync interval.\n"); + + fprintf(fileWrite, " delay_request_offset %d\n", ptp_info->uc_masters[0].settings->intvs.del_req_intv - ptp_info->uc_masters[0].settings->intvs.sync_intv); + + fprintf(fileWrite, "\n"); + + } + } + } + + len = strlen(grantors); + if (len) + grantors[len - 1] = 0; // remove last ',' + fprintf(fileWrite, " grantor %s\n", grantors); + fprintf(fileWrite, "\n"); + } + else + { + fprintf(fileWrite, " #grantor\n"); + fprintf(fileWrite, "\n"); + } + + fprintf(fileWrite, "# network_mode: (U,M,B,H) [B]\n"); + fprintf(fileWrite, "# Selects the used network mode:\n"); + fprintf(fileWrite, "# U...Unicast\n"); + fprintf(fileWrite, "# M...Multicast\n"); + fprintf(fileWrite, "# B...Both (Unicast and Multicast\n"); + fprintf(fileWrite, "# H...Hybrid (Multicast: Sync, FollowUp +\n"); + fprintf(fileWrite, "# Unicast: DlyReq, DlyResp, Mgmt)\n"); + + switch ( instc->settings->role ) + { + case PTP_ROLE_UNICAST_SLAVE: + case PTP_ROLE_UNICAST_MASTER: + fprintf(fileWrite, " network_mode U\n"); + break; + case PTP_ROLE_BOTH_MASTER: + fprintf(fileWrite, " network_mode B\n"); + break; + default: + if ( instc->settings->flags & MBG_PTP_NG_FLAG_HYBRID_MODE_MSK ) + fprintf(fileWrite, " network_mode H\n"); + else + fprintf(fileWrite, " network_mode M\n"); + } + + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# no_clock_adjustment: (bool) [false]\n"); + fprintf(fileWrite, "# Disable the clock adjustment mechanism. This mode can be used for\n"); + fprintf(fileWrite, "# network analysis.\n"); + fprintf(fileWrite, " #no_clock_adjustment false\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# path_trace: (bool) [false]\n"); + fprintf(fileWrite, "# Enable or disable the PTP path trace feature.\n"); + + if ( instc->settings->flags & MBG_PTP_NG_FLAG_PATH_TRACE_MSK ) + fprintf(fileWrite, " path_trace true\n"); + else + fprintf(fileWrite, " path_trace false\n"); + + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# pdelay_request: (0...8) [0]\n"); + fprintf(fileWrite, "# Sets the default logarithmic pdelay request interval.\n"); + + if (instc->settings->delay_mech == PTP_DELAY_MECH_P2P) + fprintf(fileWrite, " pdelay_request %d\n", instc->settings->intvs.pdel_req_intv ); + else + fprintf(fileWrite, " #pdelay_request 0\n"); + + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# prio1: (uint8_t) [128]\n"); + fprintf(fileWrite, "# Sets the priority 1 field of the default dataset. This value will\n"); + fprintf(fileWrite, "# be used in the BMCA (first decision point) to determine the best\n"); + fprintf(fileWrite, "# master clock. (lower is better)\n"); + + + if ((instc->settings->profile == PTP_PRESETS_TELECOM_PTS) + ||(instc->settings->profile == PTP_PRESETS_TELECOM_PHASE)) + fprintf(fileWrite, " prio1 128\n"); + else + fprintf(fileWrite, " prio1 %d\n", instc->settings->priority_1 ); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# prio2: (uint8_t) [128]\n"); + fprintf(fileWrite, "# Sets the priority 2 field of the default dataset. This value will\n"); + fprintf(fileWrite, "# be used in the BMCA (fifth decision point) to determine the best\n"); + fprintf(fileWrite, "# master clock. (lower is better)\n"); + + if (((instc->settings->profile == PTP_PRESETS_TELECOM_PTS) + ||(instc->settings->profile == PTP_PRESETS_TELECOM_PHASE)) + && (instc->settings->role == PTP_ROLE_UNICAST_SLAVE) ) + fprintf(fileWrite, " prio2 255\n"); + else + fprintf(fileWrite, " prio2 %d\n", instc->settings->priority_2); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# ptp_timescale: (bool) [true]\n"); + fprintf(fileWrite, "# Sets the PTP timescale flag in the PTP header of all PTP messages\n"); + + if ( instc->settings->flags & MBG_PTP_NG_FLAG_ARB_TIMESCALE_MSK ) + fprintf(fileWrite, " ptp_timescale false\n"); + else + fprintf(fileWrite, " ptp_timescale true\n"); + + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# security: (bool) [false]\n"); + fprintf(fileWrite, "# Enables the security mechanism defined in Annex K of IEEE1588-2008\n"); + fprintf(fileWrite, "# Note: this is an optional feature and is only available on request\n"); + fprintf(fileWrite, " #security false\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# statistic (bool) [false]\n"); + fprintf(fileWrite, "# if enabled statistics are printed to the defined logging interface\n"); + fprintf(fileWrite, " statistic true\n"); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, " statistic_period 0\n"); + fprintf(fileWrite, "\n"); + + if( instc->settings->role != PTP_ROLE_UNICAST_SLAVE ) // will be set in Unicast Master config section + { + fprintf(fileWrite, "# sync_interval: (-8...8) [0]\n"); + fprintf(fileWrite, "# Sets the default logarithmic sync message interval.\n"); + + fprintf(fileWrite, " sync_interval %d\n", instc->settings->intvs.sync_intv); + fprintf(fileWrite, "\n"); + + if ( instc->settings->intvs.sync_intv < -3 ) + { + fprintf(fileWrite, "lucky_filter_depth 2\n" ); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "lucky_packet_median %d\n", lucky_packet_median_nvals( instc->settings->intvs.sync_intv ) ); + fprintf(fileWrite, "\n"); + } + } + + fprintf(fileWrite, "# time_source: (string) [IXO]\n"); + fprintf(fileWrite, "# Sets the PTP time source:\n"); + fprintf(fileWrite, "# ATO... connected to an Atomic clock (0x10)\n"); + fprintf(fileWrite, "# GPS... synchronized to GPS (0x20)\n"); + fprintf(fileWrite, "# TER... synchronized via radio distribution system (0x30)\n"); + fprintf(fileWrite, "# PTP... synchronized via PTP (0x40)\n"); + fprintf(fileWrite, "# NTP... synchronized via NTP (0x50)\n"); + fprintf(fileWrite, "# HAN... hand set by means of a human interface (0x60)\n"); + fprintf(fileWrite, "# OTH... other source of time (0x90)\n"); + fprintf(fileWrite, "# IXO... internal, free-running oscillator (0xA0)\n"); + fprintf(fileWrite, " time_source IXO\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# ts_range_window: (0-31) [2]\n"); + fprintf(fileWrite, "# Allows to set the timestamp range window where out of range\n"); + fprintf(fileWrite, "# timestamps will be ignored.\n"); + fprintf(fileWrite, " #ts_range_window 2\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# two_step: (bool) [true]\n"); + fprintf(fileWrite, "# Enables two step (true -> Sync + Follow Up messages) or one step\n"); + fprintf(fileWrite, "# (false -> only Sync messages) synchronization mechanism in master mode.\n"); + fprintf(fileWrite, "# In slave mode, the mechanism is selected automatically.\n"); + + if ( instc->tstamper->settings->flags & PTP_NG_TSTAMPER_FLAG_ONE_STEP_MSK ) + fprintf(fileWrite, " two_step false\n"); + else + fprintf(fileWrite, " two_step true\n"); + + fprintf(fileWrite, "# unicast_max_connections: (1-512) [512]\n"); + fprintf(fileWrite, "# Sets the maximum number of unicast connections. In unicast mode, a PTP\n"); + fprintf(fileWrite, "# master services PTP slaves with announce, sync and/or delay measurement\n"); + fprintf(fileWrite, "# messages. The master needs a dedicated connection for every slave. The\n"); + fprintf(fileWrite, "# connections are negotiated using the unicast negotiation mechanism.\n"); + fprintf(fileWrite, "# If the maximum number of connections is reached, the unicast master\n"); + fprintf(fileWrite, "# denies all further unicast service requests.\n"); + fprintf(fileWrite, "# This parameter limits the maxmimum number of connections. It can be used\n"); + fprintf(fileWrite, "# to adapt the maximum number of connections according to the host's\n"); + fprintf(fileWrite, "# performance.\n"); + fprintf(fileWrite, " # unicast_max_connections 512\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# unicast_max_messages: (uint32_t) [18432]\n"); + fprintf(fileWrite, "# Sets the number of maximum messages per second. As unicast_max_connections,\n"); + fprintf(fileWrite, "# this parameter may be used to adapt the PTP Stack to the host's performance.\n"); + fprintf(fileWrite, "# If the maximum number of messages is reached, the unicast master\n"); + fprintf(fileWrite, "# outputs a warning for all further unicast service requests.\n"); + fprintf(fileWrite, "# The default value (18432) is calculated as follows:\n"); + fprintf(fileWrite, "# (32 sync/sec + 32 dly resp/sec + 8 ann/sec) * 256 conns\n"); + fprintf(fileWrite, " # unicast_max_messages 18432\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# utc_offset: (int16_t) [37]\n"); + fprintf(fileWrite, "# Sets the currentUtcOffset. This value is used by\n"); + fprintf(fileWrite, "# the PTP Stack in Master state only. In the Slave state, the PTP Stack\n"); + fprintf(fileWrite, "# uses the grandmaster's UTC offset.\n"); + + fprintf(fileWrite, " utc_offset 37\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# utc_offset_valid: (bool) [false]\n"); + fprintf(fileWrite, "# Sets the currentUtcOffsetValid flag of the PTP Stack.\n"); + fprintf(fileWrite, "# The flag should be set if the currentUtcOffset is known to be valid.\n"); + fprintf(fileWrite, "# The value is used by the PTP Stack in Master state only. In the Slave\n"); + fprintf(fileWrite, "# state, the PTP Stack applies the grandmaster's flags.\n"); + fprintf(fileWrite, " utc_offset_valid false\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# variance: (uint16_t) [0xFFFF]\n"); + fprintf(fileWrite, "# Sets the clock variance field in the default dataset.\n"); + fprintf(fileWrite, "# This value will be used in the BMCA (fourth decision point)\n"); + fprintf(fileWrite, "# to determine the best master clock. (lower is better)\n"); + + if ( instc->settings->fixed_quality.clk_accuracy != 0 ) + fprintf(fileWrite, " variance 0x%04X\n", instc->settings->fixed_quality.fixed_clk_variance); + else + fprintf(fileWrite, " variance 0xFFFF\n"); + + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# v1_hardware_compatibility: (bool) [false]\n"); + fprintf(fileWrite, "# If enabled, all event messages will be padded with 0 to match\n"); + fprintf(fileWrite, "# the size of PTPv1 (IEEE1588-2003) event messages.\n"); + + if( instc->settings->flags & MBG_PTP_NG_FLAG_V1_HW_COMPATIBILITY_MSK ) + fprintf(fileWrite, " v1_hw_compatibility true\n"); + else + fprintf(fileWrite, " v1_hw_compatibility false\n"); + + fprintf(fileWrite, "\n"); + + if ( instc->tstamper->settings->flags & PTP_NG_TSTAMPER_FLAG_PACKET_GENERATOR_MSK ) + fprintf(fileWrite, " use_packet_generator true\n"); + else + fprintf(fileWrite, " use_packet_generator false\n"); + + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "#### 802.1AS Related Parameters ####\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# bridge: (bool) [false]\n"); + fprintf(fileWrite, "# Enables the bridge mode of 802.1as. This requires at least two\n"); + fprintf(fileWrite, "# PTP ports. Synchronization information will be forwarded between\n"); + fprintf(fileWrite, "# the two ports according to the BMCA.\n"); + fprintf(fileWrite, " #bridge false\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# neighbor_prop_delay_threshold: (int32_t) [52428800]\n"); + fprintf(fileWrite, "# Sets the maximum peer path delay (propagation delay) measured\n"); + fprintf(fileWrite, "# with the P2P delay mechanism. If this value is exceeded, a \n"); + fprintf(fileWrite, "# neihbor will not be regarded as asCapable and no synchronization\n"); + fprintf(fileWrite, "# information will be exchanged.\n"); + fprintf(fileWrite, "# Specified in scaled nanoseconds (ns << 16), default value\n"); + fprintf(fileWrite, "# is 800 ns (= 52428800 in scaled nanoseconds).\n"); + fprintf(fileWrite, " #neighbor_prop_delay_threshold 52428800\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# sync_receipt_timeout: (2-8) [3]\n"); + fprintf(fileWrite, "#The value is the number of sync intervals that a slave port\n"); + fprintf(fileWrite, "# waits without receiving Sync/Follow-up messages, before assuming\n"); + fprintf(fileWrite, "# that the master is no longer transmitting synchronization\n"); + fprintf(fileWrite, "# information and that the BMCA needs to be run (if appropriate).\n"); + fprintf(fileWrite, " #sync_receipt_timeout 3\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# time_base_indicator: (uint16_t) [0]\n"); + fprintf(fileWrite, "# This parameter will identifies the time base of the current\n"); + fprintf(fileWrite, "# grandmaster. It will be used in Sync/Follow-up messages once this\n"); + fprintf(fileWrite, "# clock becomes grandmaster.\n"); + fprintf(fileWrite, " #time_base_indicator 0\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# transport_802_1as: (bool) [false]\n"); + fprintf(fileWrite, "# Set the 802.1as conformance flag in the transport specific field\n"); + fprintf(fileWrite, "# of the PTP header. Only available in Layer 2 mode.\n"); + fprintf(fileWrite, " #transport_802_1as false\n"); + fprintf(fileWrite, " \n"); + fprintf(fileWrite, " \n"); + + fprintf(fileWrite, " #gm_inaccuracy 0\n"); + + // ### TODO +/* + fprintf(fileWrite, " # gm_id %d\n", + current_bin_cfg->ptp_power_profile_cfg.grandmaster_id + ); + fprintf(fileWrite, " nw_inaccuracy %d\n", + current_bin_cfg->ptp_power_profile_cfg.network_incaccuracy + ); + + fprintf(fileWrite, "\n"); + */ + + fprintf(fileWrite, "#### SMPTE Profile Related Parameters ####\n"); + fprintf(fileWrite, "# The following parameters are only relevant if the SMPTE profile is activated\n"); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# default_system_frame_rate: (comma-seperated list of two uint32_t) [25,1]\n"); + fprintf(fileWrite, "# Default video frame rate of the slave system as a lowest term rational.\n"); + fprintf(fileWrite, "# The data type shall be composed of a pair of unsigned Int32 values coded \n"); + fprintf(fileWrite, "# in big-endian form where the first shall be the numerator and the second \n"); + fprintf(fileWrite, "# shall be the denominator. The denominator shall be the smallest value \n"); + fprintf(fileWrite, "# that represents the frame rate denominator\n"); + fprintf(fileWrite, "# For example, 29.97 Hz: (30000/1001) or 25 Hz: (25/1).\n"); + + //### TODO + + /* + fprintf(fileWrite, " default_system_frame_rate %d,%d\n", + current_bin_cfg->ptp_smpte_profile_cfg.defaultSystemFrameRateNum, + current_bin_cfg->ptp_smpte_profile_cfg.defaultSystemFrameRateDenum + ); + + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# master_locking_status: (uint8_t) [0]\n"); + fprintf(fileWrite, "# Complementary information to clockClass (0: Not in use, 1: Free Run, \n"); + fprintf(fileWrite, "# 2: Cold Locking, 3: Warm Locking, 4: Locked)\n"); + + bufVal = current_bin_cfg->ptp_smpte_profile_cfg.masterLockingStatus; + if(bufVal < 0) bufVal = 0; + if(bufVal > 4) bufVal = 4; + + fprintf(fileWrite, " master_locking_status %d\n", bufVal); + fprintf(fileWrite, " \n"); + fprintf(fileWrite, "# time_address_flags: (uint8_t) [0]\n"); + fprintf(fileWrite, "# Indicates the intended ST 12-1 flags. \n"); + fprintf(fileWrite, "# Bit 0: Drop frame (0: Non-drop-frame, 1: Drop-frame)\n"); + fprintf(fileWrite, "# Bit 1: Color Frame Identification (0: Not in use, 1: In use)\n"); + fprintf(fileWrite, "# Bits 2-7: Reserved\n"); + fprintf(fileWrite, " time_address_flags %d\n", + current_bin_cfg->ptp_smpte_profile_cfg.timeAddressFlags & 0x3 + ); + fprintf(fileWrite, " \n"); + fprintf(fileWrite, "# current_local_offset: (int32_t) 0\n"); + fprintf(fileWrite, "# Offset in seconds of Local Time from PTP time. For example, if Local \n"); + fprintf(fileWrite, "# Time is Eastern Standard Time (North America) UTC-5 and the number of \n"); + fprintf(fileWrite, "# leap seconds is 35, the value will be -18035 (decimal). \n"); + fprintf(fileWrite, " current_local_offset %d\n", + current_bin_cfg->ptp_smpte_profile_cfg.currentLocalOffset + ); + fprintf(fileWrite, " \n"); + fprintf(fileWrite, "# jump_seconds: (int32_t) [0]\n"); + fprintf(fileWrite, "# The size of the next discontinuity, in seconds, of Local Time. A value \n"); + fprintf(fileWrite, "# of zero indicates that no discontinuity is expected. A positive value \n"); + fprintf(fileWrite, "# indicates that the discontinuity will cause the currentLocalOffset to increase.\n"); + fprintf(fileWrite, " jump_seconds %d\n", + current_bin_cfg->ptp_smpte_profile_cfg.jumpSeconds + ); + fprintf(fileWrite, " \n"); + fprintf(fileWrite, "# time_of_next_jump: (uint64_t) [0]\n"); + fprintf(fileWrite, "# The value of the seconds portion of the master PTP time at the time \n"); + fprintf(fileWrite, "# that the next discontinuity of the currentLocalOffset will occur. The \n"); + fprintf(fileWrite, "# discontinuity occurs at the start of the second indicated\n"); + fprintf(fileWrite, " time_of_next_jump %llu\n", + cnvrt_bytes_to_long(current_bin_cfg->ptp_smpte_profile_cfg.timeOfNextJump, 6) + ); + fprintf(fileWrite, " \n"); + fprintf(fileWrite, "# time_of_next_jam: (uint64_t) [0]\n"); + fprintf(fileWrite, "# The value of the seconds portion of the PTP time corresponding to the next \n"); + fprintf(fileWrite, "# scheduled occurrence of the Daily Jam. If no Daily Jam is scheduled, the \n"); + fprintf(fileWrite, "# value of timeOfNextJam shall be zero.\n"); + fprintf(fileWrite, " time_of_next_jam %llu\n", + cnvrt_bytes_to_long(current_bin_cfg->ptp_smpte_profile_cfg.timeOfNextJam, 6) + ); + fprintf(fileWrite, " \n"); + fprintf(fileWrite, "# time_of_previous_jam: (uint64_t) [0]\n"); + fprintf(fileWrite, "# The value of the seconds portion of the PTP time corresponding to the \n"); + fprintf(fileWrite, "# previous occurrence of the Daily Jam.\n"); + fprintf(fileWrite, " time_of_previous_jam %llu\n", + cnvrt_bytes_to_long(current_bin_cfg->ptp_smpte_profile_cfg.timeOfPreviousJam, 6) + ); + fprintf(fileWrite, " \n"); + fprintf(fileWrite, "# previous_jam_local_offset: (int32_t) [0]\n"); + fprintf(fileWrite, "# The value of currentLocalOffset at the previous daily jam time.\n"); + fprintf(fileWrite, "# If a discontinuity of Local Time occurs at the jam time, this parameter \n"); + fprintf(fileWrite, "# reflects the offset after the discontinuity\n"); + fprintf(fileWrite, " previous_jam_local_offset %d\n", + current_bin_cfg->ptp_smpte_profile_cfg.previousJamLocalOffset + ); + fprintf(fileWrite, " \n"); + fprintf(fileWrite, "# daylight_saving: (uint8_t) [0]\n"); + fprintf(fileWrite, "# Bit 0: Current Daylight Saving (0: Not in effect, 1: In effect)\n"); + fprintf(fileWrite, "# Bit 1: Daylight Saving at next discontinuity (0: Not in effect, 1: In effect)\n"); + fprintf(fileWrite, "# Bit 2: Daylight Saving at previous daily jam time (0: Not in effect, 1: In effect)\n"); + fprintf(fileWrite, "# Bits 3-7: Reserved\n"); + fprintf(fileWrite, " daylight_saving %d\n", + current_bin_cfg->ptp_smpte_profile_cfg.daylightSaving & 0x7 + ); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# leap_second_jump: (uint8_t) [0]\n"); + fprintf(fileWrite, "# The reason for the forthcoming discontinuity of currentLocalOffset indicated by \n"); + fprintf(fileWrite, "# timeOfNextJump\n"); + fprintf(fileWrite, "# Bit 0:\n"); + fprintf(fileWrite, "# 0: Other than a change in the number of leap seconds (default)\n"); + fprintf(fileWrite, "# 1: A change in number of leap seconds\n"); + fprintf(fileWrite, "# Bits 1-7: Reserved\n"); + fprintf(fileWrite, " leap_second_jump %d\n", + current_bin_cfg->ptp_smpte_profile_cfg.leapSecondJump & 0x1 + ); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "#### Servo properties ####\n"); + fprintf(fileWrite, "## please be careful when changing any of the parameters below.\n"); + fprintf(fileWrite, "## any changes may deteroide the synchronization performance.\n"); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# adjust_interval: (-8...8) [0]\n"); + fprintf(fileWrite, "# Sets the default logarithmic clock adjust interval.\n"); + fprintf(fileWrite, "# set by this profile by default to a specified and valid value\n"); + + bufVal = current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.adjust_interval; + if(bufVal < -8) bufVal = -8; + if(bufVal > 8) bufVal = 8; + + fprintf(fileWrite, " adjust_interval %d\n", bufVal); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# boundary: (int32_t) [65536000]\n"); + fprintf(fileWrite, "# This parameter allows to set a synchronization boundary\n"); + fprintf(fileWrite, "# (offset between master and slave). A message is displayed\n"); + fprintf(fileWrite, "# once the boundary is reached/left.\n"); + fprintf(fileWrite, "# Specified in scaled nanoseconds (ns << 16), default value\n"); + fprintf(fileWrite, "# is 1000 ns (= 65536000 in scaled nanoseconds). A value of\n"); + fprintf(fileWrite, "# 0 disables the boundary entirely.\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# change_epoch_boundary: (int64_t) [32768000000000]\n"); + fprintf(fileWrite, "# If the master-to-slave delay (calculated using the timestamps\n"); + fprintf(fileWrite, "# of a Sync messages)exceeds this boundary \\a tsRange times, the new\n"); + fprintf(fileWrite, "# epoch is applied by setting the slave's time to the master's time.\n"); + fprintf(fileWrite, "# Specified in scaled nanoseconds (ns << 16), default value\n"); + fprintf(fileWrite, "# is 0.5 s (= 32768000000000 in scaled nanoseconds). A value of\n"); + fprintf(fileWrite, "# 0 disables the boundary entirely.\n"); + + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# cold_start: (bool) [false]\n"); + fprintf(fileWrite, "# Performs a cold start by initializing and resetting the hardware clock\n"); + fprintf(fileWrite, "# as well as the clock rate.\n"); + + fprintf(fileWrite, " cold_start false\n"); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# delay_asymmetry: (int64_t) [0]\n"); + fprintf(fileWrite, "# This paramter can be used to compensate asymmetries\n"); + fprintf(fileWrite, "# in scaled nanoseconds (ns << 16)\n"); + fprintf(fileWrite, " delay_asymmetry %lld\n", + current_bin_cfg->ptp_cfg_x_info.settings.delay_asymmetry + ); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# Servo Properties\n"); + fprintf(fileWrite, "# +- Outbound Pi.K [16500]\n"); + fprintf(fileWrite, "# | +- Outbound Pi.T [100]\n"); + fprintf(fileWrite, "# | | +- iirM2S.Smin [0x8000]\n"); + fprintf(fileWrite, "# | | | +- iirPath.Smin [0x8000]\n"); + fprintf(fileWrite, "# | | | | +- iir.logAdjPrd [4]\n"); + fprintf(fileWrite, "# | | | | | +- iir.logAdjGain [16]\n"); + + fprintf(fileWrite, "servo_props %d %d 0x%04X 0x%04X %d %d\n", + current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.outbound_pi_K, + current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.outbound_pi_T, + current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.iirM2S_smin, + current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.iirPath_smin, + current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.iir_logAdjPrd, + current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.iir_logAdjGain + ); + + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# Outbound delta rate max (scaledNs) [0x200000000]\n"); + fprintf(fileWrite, "# 1024 ns/s\n"); + fprintf(fileWrite, "outbound_delta_rate_max 0x%llX\n", + (uint64_t)(current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.outbound_delta_rate_max) + ); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# Outbound anti windup max (scaledNs) [0xEE6B2800000]\n"); + fprintf(fileWrite, "outbound_anti_windup_max 0x%llX\n", + (uint64_t)(current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.outbound_anti_windup_max) + ); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# Inbound Pi.K [6500]\n"); + fprintf(fileWrite, "inbound_pi_k %d\n", + current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.inbound_pi_K + ); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# Inbound Pi.T [100]\n"); + fprintf(fileWrite, "inbound_pi_t %d\n", + current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.inbound_pi_T + ); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# Inbound delta rate max (scaledNs) [0x200000000]\n"); + fprintf(fileWrite, "# 8 ns/s\n"); + fprintf(fileWrite, "inbound_delta_rate_max 0x%llX\n", + (uint64_t)(current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.inbound_delta_rate_max) + ); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# Inbound anti windup max (scaledNs) [0xEE6B2800000]\n"); + fprintf(fileWrite, "inbound_anti_windup_max 0x%llX\n", + (uint64_t)(current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.inbound_anti_windup_max) + ); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# Lucky Packet Filter Depth (log2 sec) [-1]\n"); + fprintf(fileWrite, "# -1: Lucky packet filter disabled\n"); + fprintf(fileWrite, "lucky_filter_depth %d\n", + current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.lucky_packet_flt_depth + ); + fprintf(fileWrite, "\n"); + + fprintf(fileWrite, "# IIR filter enable [true]\n"); + + if(current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.flags.use_iir_filter) + fprintf(fileWrite, "use_iir_filter true\n"); + else + fprintf(fileWrite, "use_iir_filter false\n"); + + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# spike filter enable [true]\n"); + + if(current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.flags.use_spike_filter) + fprintf(fileWrite, "use_spike_filter true\n"); + else + fprintf(fileWrite, "use_spike_filter false\n"); + + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# sample rate converter [false]\n"); + + if(current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.flags.use_sample_rate_converter) + fprintf(fileWrite, "use_sample_rate_converter true\n"); + else + fprintf(fileWrite, "use_sample_rate_converter false\n"); + + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# lucky packet median filter [1]\n"); + fprintf(fileWrite, "# count of packets which are used for median calculation in lucky packet filter\n"); + fprintf(fileWrite, "lucky_packet_median %d\n", + current_bin_cfg->ptp_cfg_x_info.settings.servo_cfg.clk_servo_cfg.lucky_packet_median + ); + fprintf(fileWrite, "\n"); + fprintf(fileWrite, "# Second port\n"); + fprintf(fileWrite, "# For boundary clock operation, insert a second configuration here:\n"); + fprintf(fileWrite, "# Note: A second physical interface is required. If you are using one\n"); + fprintf(fileWrite, "# or more syn1588 PCIe cards, they have to be synchronized with the syn1588(R)\n"); + fprintf(fileWrite, "# tool lSync as well.\n"); + fprintf(fileWrite, " #port2:\n"); + */ + + fprintf(fileWrite, "\n"); + + } + + fclose(fileWrite); + + return MBG_SUCCESS; + +} + +#endif // defined( MBG_TGT_UNIX ) + + + +/*HDR*/ +/** + * @brief cnvrt_bytes_to_long + */ +uint64_t cnvrt_bytes_to_long( const uint8_t byte_array[], int num_bytes ) +{ + int i; + uint64_t val = 0; + + for ( i = 0; i < num_bytes; i++ ) + val = (val << 8) | byte_array[i]; + + return val; + +} // cnvrt_bytes_to_long + + + +/*HDR*/ +/** + * @brief cnvrt_long_to_bytes + */ +void cnvrt_long_to_bytes( uint8_t byte_array[], int num_bytes, uint64_t val ) +{ + int i; + + for ( i = num_bytes - 1; i >= 0; i-- ) + { + byte_array[i] = (uint8_t) val; // masked by 0xFF anyway + val >>= 8; + } + + return; + +} // cnvrt_long_to_bytes + + + +/*HDR*/ +size_t nw_str_mac_addr_to_str( MBG_MAC_ADDR *mac_addr, char *buf, size_t buflen ) +{ + size_t len = 0; + + if ( !mac_addr || !buf ) + return len; + + len += snprintf_safe( &buf[len], buflen - len, "%02X:%02X:%02X:%02X:%02X:%02X", + mac_addr->b[0], mac_addr->b[1], mac_addr->b[2], mac_addr->b[3], mac_addr->b[4], mac_addr->b[5] ); + + return len; + +} // nw_str_mac_addr_to_str + + + +/*HDR*/ +int nw_str_to_mac_addr( MBG_MAC_ADDR *mac_addr, const char *str ) +{ + int a, b, c, d, e, f; + memset( mac_addr, 0, sizeof( *mac_addr ) ); + + if ( (sscanf(str, "%02x:%02x:%02x:%02x:%02x:%02x", &a, &b, &c, &d, &e, &f) == 6 ) || + ( sscanf(str, "%02x-%02x-%02x-%02x-%02x-%02x", &a, &b, &c, &d, &e, &f) == 6 ) ) + { + mac_addr->b[0] = a; + mac_addr->b[1] = b; + mac_addr->b[2] = c; + mac_addr->b[3] = d; + mac_addr->b[4] = e; + mac_addr->b[5] = f; + return MBG_SUCCESS; + } + + return MBG_ERR_GENERIC; + +} // nw_str_to_mac_addr + + + +/*HDR*/ +int nw_ip6_addr_bytes_to_str( const uint8_t *addr, uint8_t protocol, char *str, size_t buflen ) +{ + switch(protocol) + { + case PTP_NW_PROT_UDP_IPV4 : + snprint_ip4_addr( str, buflen, (IP4_ADDR *) addr, NULL ); break; + + case PTP_NW_PROT_UDP_IPV6 : + snprint_ip6_addr( str, buflen, (IP6_ADDR *) addr, NULL ); break; + + case PTP_NW_PROT_IEEE_802_3 : + nw_str_mac_addr_to_str( (MBG_MAC_ADDR*) addr, str, buflen ); break; + + default : + return MBG_ERR_INV_PARM; + } + + return MBG_SUCCESS; + +} // nw_ip6_addr_bytes_to_str + + + +/*HDR*/ +int nw_str_to_ip6_addr_bytes( uint8_t *addr, const uint8_t protocol, char *str, size_t buflen ) +{ + int rc = 0; + + switch ( protocol ) + { + case PTP_NW_PROT_UDP_IPV4 : + rc = str_to_ip4_addr( (IP4_ADDR *) addr, str ); break; + + case PTP_NW_PROT_UDP_IPV6 : + rc = str_to_ip6_addr( (IP6_ADDR *) addr, str ); break; + + case PTP_NW_PROT_IEEE_802_3 : + rc = nw_str_mac_addr_to_str( (MBG_MAC_ADDR *) addr, str, buflen ); break; + + default : + return MBG_ERR_INV_PARM; + } + + return rc; + +} // nw_str_to_ip6_addr_bytes + + + +/*HDR*/ +int mbg_os_version_to_str( const MBG_EXT_SYS_INFO *info, char *buf, size_t buflen, int long_version ) +{ + ssize_t bytes; + const char* os_strs[] = MBG_EXT_SYS_INFO_OS_SHORT_STRS; + + if ( !( info->supp_members & MBG_EXT_SYS_INFO_MSK_OS_TYPE ) ) + return MBG_ERR_NOT_SUPP_BY_DEV; + + if ( info->mbg_os_type >= N_MBG_EXT_SYS_INFO_OS_TYPES ) + return MBG_ERR_INV_PARM; + + bytes = 0; + + if ( ( info->supp_members & MBG_EXT_SYS_INFO_MSK_OS_NAME ) && long_version ) + bytes += snprintf_safe(&buf[bytes], buflen - bytes, "%s ", info->os_name); + + if ( info->supp_members & MBG_EXT_SYS_INFO_MSK_SW_REV ) + { + unsigned year, month, patch; + + _mbg_decode_revision( info->sw_rev, year, month, patch ); + year += MBG_OS_YEAR_CONSTANT; + + if ( ( info->supp_members & MBG_EXT_SYS_INFO_MSK_RELEASE_CANDIDATE ) && + info->release_candidate ) + { + if ( info->release_candidate != MBG_REVISION_RC_DEVEL ) + bytes += snprintf_safe(&buf[bytes], buflen - bytes, + "%04u.%02u.%u-rc%i-", + year, month, patch, info->release_candidate); + else + bytes += snprintf_safe(&buf[bytes], buflen - bytes, + "%04u.%02u.%u-%s-", + year, month, patch, MBG_REVISION_RC_DEVEL_STR); + } + else + { + bytes += snprintf_safe(&buf[bytes], buflen - bytes, + "%04u.%02u.%u-", + year, month, patch); + } + } + + bytes += snprintf_safe(&buf[bytes], buflen - bytes, + "%s ", + os_strs[info->mbg_os_type]); + + + if ( ( info->supp_members & MBG_EXT_SYS_INFO_MSK_COMMIT_HASH ) && long_version ) + bytes += snprintf_safe(&buf[bytes], buflen - bytes, + "%08x ", info->commit_hash); + + if ( bytes >= (ssize_t)buflen ) + return MBG_ERR_OVERFLOW; + + buf[--bytes] = 0; + + return MBG_SUCCESS; + +} // mbg_os_version_to_str + + + +/*HDR*/ +int mbg_fw_can_set_osv(const MBG_FW_GLB_INFO *info) +{ + if ( info && ( info->flags & MBG_FW_GLB_MSK_CAN_SET_OSV ) ) + return MBG_SUCCESS; + + return MBG_ERR_NOT_SUPP_BY_DEV; + +} // mbg_fw_can_set_osv + diff --git a/mbglib/common/cfg_hlp.h b/mbglib/common/cfg_hlp.h index 9df0f5b..8e11cc5 100644 --- a/mbglib/common/cfg_hlp.h +++ b/mbglib/common/cfg_hlp.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: cfg_hlp.h 1.6 2018/09/20 11:22:11Z martin REL_M $ + * $Id: cfg_hlp.h 1.7 2019/09/27 14:24:45Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -19,7 +19,12 @@ * * ----------------------------------------------------------------------- * $Log: cfg_hlp.h $ - * Revision 1.6 2018/09/20 11:22:11Z martin + * Revision 1.7 2019/09/27 14:24:45Z martin + * New structure definitions to support new API features. + * Struct names were added by thomas-b to support forward declarations. + * Some new inline functions. + * Updated function prototypes and some doxygen comments. + * Revision 1.6 2018/09/20 11:22:11 martin * Renamed some global variables to more common names. * Added string initializer tables and associated macros * for some PTP configuration stuff. @@ -204,7 +209,7 @@ typedef struct * * @see ::GPS_HAS_XBP */ -typedef struct +typedef struct all_xbp_info_s { XBP_LIMITS limits; XBP_NODE_LIMITS* node_limits; @@ -233,7 +238,7 @@ typedef POUT_INFO_IDX ALL_POUT_INFO_IDX[MAX_PARM_POUT]; * @see ::GPS_HAS_NET_CFG * @see ::GPS_HAS_LAN_IP4 */ -typedef struct +typedef struct all_net_cfg_info_s { MBG_NET_GLB_CFG_INFO glb_cfg_info; MBG_NET_INTF_LINK_INFO_IDX *link_infos; @@ -255,7 +260,7 @@ typedef ALL_NET_CFG_INFO ALL_NET_STATUS_INFO; * * @see ::MBG_XFEATURE_MONITORING */ -typedef struct +typedef struct all_snmp_info_s { MBG_SNMP_GLB_INFO glb_info; MBG_SNMP_V12_INFO_IDX *v12_infos; @@ -275,10 +280,10 @@ typedef struct */ typedef struct mbg_event { - unsigned idx; + MBG_MSG_IDX idx; + uint16_t reserved; // for 32 bit alignment MBG_EVENT_INFO info; MBG_EVENT_STATUS status; - MBG_EVENT_VALUE *dict_entries; /* Pointer for 3rd party to connect some data */ void *backref; /* Pointer for the mallocer to connect some private data */ @@ -294,9 +299,11 @@ typedef struct mbg_event } MBG_EVENT; -typedef struct +typedef struct all_events_s { - unsigned num_events; + MBG_EVENT_GLB_INFO glb_info; + MBG_MSG_IDX num_events; + uint16_t reserved; // for 32 bit alignment MBG_EVENT *events; } ALL_EVENTS; @@ -326,7 +333,7 @@ typedef struct mbg_syslog_server } MBG_SYSLOG_SERVER; -typedef struct +typedef struct all_syslog_info_s { MBG_SYSLOG_GLB_INFO glb_info; MBG_SYSLOG_SERVER *servers; @@ -343,7 +350,7 @@ typedef struct * * @see ::MBG_XFEATURE_MONITORING */ -typedef struct +typedef struct all_monitoring_info_s { MBG_MONITORING_LIMITS limits; ALL_SNMP_INFO *all_snmp_info; @@ -366,7 +373,7 @@ typedef PTP_UC_MASTER_INFO_IDX ALL_PTP_UC_MASTER_INFO_IDX[MAX_PARM_PTP_UC_MASTER * @see ::GPS_HAS_PTP * @see ::PTP_UC_MASTER_CFG_LIMITS::n_supp_master */ -typedef struct +typedef struct all_ptp_cfg_info_s { PTP_CFG_INFO ptp_cfg_info; PTP_UC_MASTER_CFG_LIMITS ptp_uc_master_cfg_limits; @@ -375,6 +382,66 @@ typedef struct } ALL_PTP_CFG_INFO; +/** + * @brief All PTP next gen configuration parameters, + * only supported if ::MBG_XFEATURE_PTP_NG is set + */ + +typedef struct mbg_ptp_ng_tstamper +{ + unsigned idx; + MBG_PTP_NG_TSTAMPER_INFO info; + MBG_PTP_NG_TSTAMPER_STATUS status; + MBG_PTP_NG_TSTAMPER_SETTINGS *settings; + + void *priv_data; + void (*release_priv)(struct mbg_ptp_ng_tstamper*); + +} MBG_PTP_NG_TSTAMPER; + + +typedef struct mbg_ptp_ng_instc +{ + MBG_MSG_IDX idx; + uint16_t reserved; // for 32 bit alignment + MBG_PTP_NG_INSTC_INFO info; + MBG_PTP_NG_INSTC_STATUS status; + MBG_PTP_NG_INSTC_PKT_CNTRS cntrs; + MBG_PTP_NG_INSTC_SETTINGS *settings; + const MBG_PTP_NG_TSTAMPER *tstamper; + + MBG_PTP_NG_UC_SLAVE_STATUS *uc_slave_list; + + void *priv_data; + void (*release_priv)(struct mbg_ptp_ng_instc*); + +} MBG_PTP_NG_INSTC; + + +typedef struct mbg_ptp_ng_uc_master +{ + MBG_MSG_IDX idx; + uint16_t reserved; // for 32 bit alignment + MBG_PTP_NG_UC_MASTER_INFO info; + MBG_PTP_NG_UC_MASTER_SETTINGS *settings; + const MBG_PTP_NG_INSTC *instc; + + void *priv_data; + void (*release_priv)(struct mbg_ptp_ng_uc_master*); + +} MBG_PTP_NG_UC_MASTER; + + +typedef struct all_ptp_ng_info_s +{ + MBG_PTP_NG_GLB_INFO glb_info; + + MBG_PTP_NG_TSTAMPER *timestampers; + MBG_PTP_NG_INSTC *instances; + MBG_PTP_NG_UC_MASTER *uc_masters; + +} ALL_PTP_NG_INFO; + /** * @brief All PTPv1 common datasets for a PTP device @@ -428,6 +495,32 @@ typedef struct +typedef struct mbg_sys_ref_src +{ + unsigned idx; + struct mbg_klist_head head; + MBG_SYS_REF_SRC_INFO info; + MBG_SYS_REF_SRC_STATUS status; + MBG_SYS_REF_SRC_SETTINGS *settings; + + void *priv_data; + void (*release_priv)(struct mbg_sys_ref_src*); + +} MBG_SYS_REF_SRC; + + +typedef struct all_sys_ref_info_s +{ + MBG_SYS_REF_LIMITS limits; + MBG_SYS_REF_GLB_STATUS glb_status; + struct mbg_klist_head sources; + const MBG_SYS_REF_SRC *cur_master; + void (*free_source)(MBG_SYS_REF_SRC*); + +} ALL_SYS_REF_INFO; + + + /** * @brief An array of configuration settings for all programmable pulse outputs * @@ -444,7 +537,7 @@ typedef GNSS_SAT_INFO_IDX ALL_GNSS_SAT_INFO_IDX[MAX_PARM_GNSS_SAT]; * Used to collect all configuration parameters even for devices * that can receive the signals from multiple satellite systems. */ -typedef struct +typedef struct all_gnss_info_s { STAT_INFO stat_info; int n_gnss_supp; @@ -473,7 +566,7 @@ typedef struct } NTP_CLIENT_CFG_PEER_SETTINGS; -typedef struct +typedef struct all_ntp_cfg_info_s { NTP_GLB_INFO glb_info; NTP_SYMM_KEY_LIMITS *symm_key_limits; @@ -491,7 +584,7 @@ typedef struct } ALL_NTP_CFG_INFO; -typedef struct +typedef struct all_ntp_status_s { NTP_SYS_STATE sys_state; NTP_REFCLK_STATE_IDX *refclk_states; @@ -517,15 +610,23 @@ typedef XMULTI_REF_INFO_IDX ALL_XMULTI_REF_INFO_IDX[MAX_PARM_XMR]; -typedef struct +typedef struct all_xmulti_ref_info_s { XMULTI_REF_INSTANCES instances; + XMULTI_EXT_REF_INSTANCES ext_instances; XMULTI_REF_INFO_IDX *infos; XMR_EXT_SRC_INFO_IDX *ext_src_infos; + XMR_QL_LIMITS ql_limits; + XMR_QL_SETTINGS_IDX *ql_settings; + /* + * ALL_XMULTI_REF_INFO related flag if at least one ref type supports metrics + * and thus QL stuff! + */ + unsigned has_metrics; } ALL_XMULTI_REF_INFO; -typedef struct +typedef struct all_xmulti_ref_status_s { XMULTI_REF_STATUS_IDX *status; XMR_HOLDOVER_STATUS *holdover_status; @@ -539,7 +640,7 @@ typedef struct -typedef struct +typedef struct all_ims_info_s { MBG_IMS_STATE state; MBG_IMS_FDM_INFO *fdm_info; @@ -548,7 +649,7 @@ typedef struct } ALL_IMS_INFO; -typedef struct +typedef struct all_ims_state_s { MBG_IMS_SENSOR_STATE_IDX *sensor_state_idx; MBG_IMS_FDM_STATE *fdm_state; @@ -557,14 +658,14 @@ typedef struct -typedef struct +typedef struct all_gpio_info_s { MBG_GPIO_CFG_LIMITS cfg_limits; MBG_GPIO_INFO_IDX *infos; } ALL_GPIO_INFO; -typedef struct +typedef struct all_gpio_state_s { MBG_GPIO_STATUS_IDX *states; } ALL_GPIO_STATE; @@ -583,7 +684,7 @@ typedef struct mbg_io_port } MBG_IO_PORT; -typedef struct +typedef struct all_mbg_io_ports_s { MBG_IO_PORT_LIMITS limits; unsigned num_ports; @@ -605,14 +706,14 @@ typedef struct TTM ttm; } UCAP_ENTRY; -typedef struct +typedef struct all_ucap_info_s { uint32_t num_ucaps; /// User capture counter, see ::MAX_UCAP_ENTRIES struct mbg_klist_head list; } ALL_UCAP_INFO; // User Captures via Network configuration, see ::MBG_XFEATURE_UCAP_NET -typedef struct +typedef struct all_ucap_net_info_s { MBG_UCAP_NET_GLB_INFO glb_info; MBG_UCAP_NET_RECV_INFO_IDX *recv_infos; @@ -625,7 +726,7 @@ typedef struct mbg_user MBG_USER_INFO info; MBG_USER_STATUS status; - char salt[3]; + char salt[9]; /* Pointer for 3rd party to connect some data */ void *backref; @@ -642,7 +743,7 @@ typedef struct mbg_user } MBG_USER; -typedef struct +typedef struct all_user_info_s { MBG_USER_MNGMNT_INFO user_mngmnt_info; MBG_USER *users; ///< system users for internal authentication @@ -672,7 +773,7 @@ typedef struct mbg_service } MBG_SERVICE; -typedef struct +typedef struct all_service_info_s { MBG_SERVICE_MGMT_INFO mgmt_info; MBG_SERVICE *svcs; @@ -722,7 +823,7 @@ typedef struct mbg_firmware_ufu } MBG_FIRMWARE_UFU; -typedef struct +typedef struct all_firmware_info_s { MBG_FW_GLB_INFO glb_info; MBG_FIRMWARE *firmwares; /// Array of ::MBG_FW_GLB_INFO::installed_fws @@ -749,7 +850,7 @@ typedef struct mbg_database } MBG_DATABASE; -typedef struct +typedef struct all_database_info_s { MBG_DATABASE_GLB_INFO glb_info; /// Array of ::MBG_DATABASE_GLB_INFO::num_dbs. Yes, until num_dbs!! @@ -769,11 +870,12 @@ typedef struct /// Do not access array via ::MBG_EXT_SYS_INFO_CPUS enum. /// Only use it as lookup table. Initializer for ::MBG_EXT_SYS_INFO_CPU_CODEC. -#define MBG_EXT_SYS_INFO_CPU_CODECS \ -{ \ - {HPS_USB_HOST_G1_V0, "microSYNC HSXXX"}, \ - {HPS_USB_DEVICE_G1_V0, "HPS100"}, \ - {HPS_USB_DEVICE_G1_V1, "SSP100"} \ +#define MBG_EXT_SYS_INFO_CPU_CODECS \ +{ \ + {HPS_USB_HOST_G1_V0, "microSync HSXXX"}, \ + {HPS_USB_DEVICE_G1_V0, "HPS100"}, \ + {HPS_USB_DEVICE_G1_V1, "SSP100"}, \ + {MSSB_USB_HOST_G1_V0, "microSyncHR, microSyncRX"} \ } @@ -1014,13 +1116,34 @@ _ext const PTP_TABLE ptp_time_source_table[] /** + * @brief A structure which holds all satellite info read from a device + * + * @note The structure contains pointers to allocated memory, + * so it can ***not*** be used to exchange data between + * different programs or devices. + * + * @see ::mbgextio_get_all_gnss_sv_info + */ +typedef struct ALL_GNSS_SV_INFO_s +{ + uint16_t n_gnss_sv_stati; // Number of ::GNSS_SV_STATUS_IDX that can be read (if > 0, no ::SV_INFO can be read) + uint16_t n_sv_infos; // Number of ::SV_INFO that can be read + + GNSS_SV_STATUS_IDX *gnss_sv_stati; + SV_INFO *sv_infos; + +} ALL_GNSS_SV_INFO; + + + +/** * @brief Count the number of bits which are not 0 * * @param[in] val Value to be tested * * @return The number of non-zero bits in val */ -static __mbg_inline +static __mbg_inline /*HDR*/ int num_bits_set( long val ) { int bits_set = 0; @@ -1040,6 +1163,52 @@ int num_bits_set( long val ) +static __mbg_inline /*HDR*/ +/** + * @brief Compute the value of 2 to the power of n. + * + * In the special case of a base 2 and a small exponent n + * the function pow( base, n ) can simply be replaced by + * a shift operation which executes ***very*** much faster + * than the floating point pow() function. + * In addition this avoids the requirement of explicitly + * linking against the math library. + * + * Please note that if the result is a 32 bit type then @p exp + * must be less than 32. + * @param[in] exp The number of which to compute pow( 2, n ). + * + * @return The result as integer. + */ +uint32_t uint32_pow2( int exp ) +{ + return 1 << exp; + +} // uint32_pow2 + + + +static __mbg_inline /*HDR*/ +/** + * @brief Compute the number of values to be used for PTP lucky packet median filtering. + * + * This only makes sense if the sync interval is negative, + * and below a certain limit, e.g. < -3. + * + * @param[in] ln_sync_intv The sync_intv parameter from a PTP configuration. + * + * @return The result as integer. + */ +int lucky_packet_median_nvals( int8_t ln_sync_intv ) +{ + // For example, if ln_sync_interval is -4 then pow( 2, 4 ) == 16, and the + // the expected number of samples for the lucky packet median filter is 15. + return uint32_pow2( -ln_sync_intv ) - 1; + +} // lucky_packet_median_nvals + + + #if !defined( MBG_TGT_KERNEL ) /** @@ -1051,7 +1220,7 @@ int num_bits_set( long val ) * * @return true if the device id contains the name of a serial port, else false */ -static __mbg_inline +static __mbg_inline /*HDR*/ bool device_id_is_serial( const char *dev_id ) { #if defined( MBG_TGT_NO_TGT ) @@ -1094,7 +1263,7 @@ bool device_id_is_serial( const char *dev_id ) * * @return true if the device id specifies a LAN connection, else false */ -static __mbg_inline +static __mbg_inline /*HDR*/ bool device_id_is_lan( const char *dev_id ) { return strstr( dev_id, "LAN" ) != NULL; @@ -1107,7 +1276,7 @@ bool device_id_is_lan( const char *dev_id ) #if defined( _PRELIMINARY_CODE ) -static __mbg_inline +static __mbg_inline /*HDR*/ MBG_TLV_UID mbg_tlv_create_id( void ) { #if defined( MBG_TGT_LINUX ) ///### FIXME for FreeBSD and Windows @@ -1133,7 +1302,7 @@ MBG_TLV_UID mbg_tlv_create_id( void ) /* by MAKEHDR, do not remove the comments. */ /** - * @brief Check if a software revision name should be displayed + * @brief Check if a software revision name should be displayed. * * The software revision name is usually empty, except if the * firmware is a customized version, in which case the field @@ -1141,28 +1310,57 @@ MBG_TLV_UID mbg_tlv_create_id( void ) * * There are some standard firmware versions where this string * is not empty but padded with spaces, etc., so we try to - * clean this up and display the string properly, if appropriate. + * clean this up, so it can be displayed appropriately. * - * @param[in,out] p The ::SW_REV name to check - * @param[in] verbose The app's verbosity level + * @param[in,out] p The ::SW_REV name to check. + * @param[in] verbose The app's verbosity level. * - * @return != 0 if SW name should be displayed + * @return != 0 if SW name should be displayed. */ int chk_sw_rev_name( SW_REV *p, int verbose ) ; + /** + * @brief Search a string table for a specific string. + * + * @param[in] search The string to be searched for in table @a str_table. + * @param[in] str_table A table of strings like 'const char *strs[N_STRS]'. + * @param[in] n_entries The number of strings in table @a str_table. + * + * @return The index number of the string table entry matching the @a search string, + * or -1 if the @a search string could not be found. + */ int get_str_idx( const char *search, const char *str_table[], int n_entries ) ; + + /** + * @brief Search the ::mbg_baud_rates table for a specific baud rate. + * + * @param[in] baud_rate The baud_rate to be searched for. + * + * @return The index number of the specific @a baud_rate in table ::mbg_baud_rates, + * or -1 if the specific @a baud_rate could not be found. + */ int get_baud_rate_idx( BAUD_RATE baud_rate ) ; + + /** + * @brief Search the ::mbg_framing_strs table for a specific framing string. + * + * @param[in] framing The framing string to be searched for, e.g. "8N1". + * + * @return The index number of the specific @a framing in table ::mbg_framing_strs, + * or -1 if the specific @a framing could not be found. + */ int get_framing_idx( const char *framing ) ; + /** * @brief Convert ::PORT_PARM::mode to ::PORT_SETTINGS::mode * - * This function is used to evaluate the code from a mode field of a legacy + * This function is used to evaluate the code from a @a mode field of a legacy * ::PORT_PARM structure and set up the appropriate fields in a ::PORT_SETTINGS - * structure accordingly. + * structure. * * @param[out] p_ps Pointer to a ::PORT_SETTINGS structure to be updated. * @param[in] pp_mode The mode code from a ::PORT_PARM structure, see ::LGCY_STR_MODES. - * @param[in] cap_str_idx The capture string index number for the case that @p pp_mode is + * @param[in] cap_str_idx The capture string index number for the case that @a pp_mode is * a capture string mode. Usually 1 for legacy devices. * * @ingroup cfg_hlp_com_parm_cnv_fncs @@ -1188,7 +1386,7 @@ MBG_TLV_UID mbg_tlv_create_id( void ) void port_parm_mode_from_port_settings( uint8_t *pp_mode, const PORT_SETTINGS *p_ps, int cap_str_idx ) ; /** - * @brief Set up a ::PORT_SETTINGS structure from a legacy ::PORT_PARM structure + * @brief Set up a ::PORT_SETTINGS structure from a legacy ::PORT_PARM structure. * * @param[out] p_ps Pointer to a ::PORT_SETTINGS structure to be updated. * @param[in] port_idx Index number of the port settings to be converted. @@ -1202,7 +1400,7 @@ MBG_TLV_UID mbg_tlv_create_id( void ) void port_settings_from_port_parm( PORT_SETTINGS *p_ps, int port_idx, const PORT_PARM *p_pp, int cap_str_idx ) ; /** - * @brief Set up a a legacy ::PORT_PARM structure from a ::PORT_SETTINGS structure + * @brief Set up a a legacy ::PORT_PARM structure from a ::PORT_SETTINGS structure. * * @param[out] p_pp Pointer to a ::PORT_PARM structure to be updated. * @param[in] port_idx Index number of the port settings to be converted. @@ -1215,118 +1413,302 @@ MBG_TLV_UID mbg_tlv_create_id( void ) */ void port_parm_from_port_settings( PORT_PARM *p_pp, int port_idx, const PORT_SETTINGS *p_ps, int cap_str_idx ) ; + /** + * @brief Check if all serial port capabilities reported by a device are supported by the current driver. + * + * @param[in] p_pi Address of a ::PORT_INFO structure to be checked. + * @param[out] str_type_info_idx An array of ::STR_TYPE_INFO_IDX structures supported by the device + * @param[in] n_str_type The number of entries in the @a str_type_info_idx array. + * + * @return A bit mask of @ref MBG_COM_CFG_STATUS_MASKS flags indicating which type of parameter + * may not be fully supported. Should be 0 if everything is OK. + * + * @see ::is_valid_port_info + * @see @ref MBG_COM_CFG_STATUS_MASKS + */ uint32_t check_valid_port_info( const PORT_INFO *p_pi, const STR_TYPE_INFO_IDX str_type_info_idx[], int n_str_type ) ; - int valid_port_info( const PORT_INFO *p_pi, const STR_TYPE_INFO_IDX str_type_info_idx[], int n_str_type ) ; + + /** + * @brief Check if the content of a ::PORT_INFO structure is known and valid. + * + * @param[in] p_pi Address of a ::PORT_INFO structure to be checked. + * @param[in] str_type_info_idx An array of string type information. + * @param[in] n_str_type The number of entries in the @a str_type_info_idx array. + * + * @return @a true if the ::PORT_INFO structure contains valid data, + * else @a false. + * + * @see ::check_valid_port_info + */ + bool is_valid_port_info( const PORT_INFO *p_pi, const STR_TYPE_INFO_IDX str_type_info_idx[], int n_str_type ) ; + /** - * @brief Setup an array of ::PORT_INFO_IDX structures from a ::PORT_PARM + * @brief Setup an array of ::PORT_INFO_IDX structures from a ::PORT_PARM. * * Some legacy GPS receivers that don't provide a ::RECEIVER_INFO structure * also provide a ::PORT_PARM structure with the current serial port settings - * only. This function sets up an array of ::PORT_INFO_IDX structures with the + * only. + * + * This function sets up an array of ::PORT_INFO_IDX structures with the * associated settings, and fills up the remaining ::PORT_INFO fields with - * the well-known supported settings, so applications can simple deal with + * the well-known supported settings, so applications can simply deal with * the current API structures. * - * @param[out] pii Array with p_ri->n_com_ports ::PORT_INFO_IDX elements to be filled up. - * @param[in] p_pp Pointer to a ::PORT_PARM structure providing the current COM port settings + * @param[out] pii Array with @a p_ri->n_com_ports ::PORT_INFO_IDX elements to be filled up. + * @param[in] p_pp Pointer to a ::PORT_PARM structure providing the current COM port settings. * @param[in] p_ri Pointer to a ::RECEIVER_INFO structure providing the number of supported COM ports. * - * @return One of the @ref MBG_RETURN_CODES, but actually always ::MBG_SUCCESS. + * @return One of the @ref MBG_RETURN_CODES, but actually always ::MBG_SUCCESS. * * @ingroup cfg_hlp_com_parm_cnv_fncs - * @see setup_port_parm ::FIXME + * @see setup_default_str_type_info_idx */ int setup_port_info_from_port_parm( PORT_INFO_IDX pii[], const PORT_PARM *p_pp, const RECEIVER_INFO *p_ri ) ; + /** + * @brief Setup an array of ::STR_TYPE_INFO_IDX for well-known string types. + * + * Some legacy GPS receivers that don't provide a ::RECEIVER_INFO structure + * also don't support the ::STR_TYPE_INFO structure to indicate which serial + * string formats are supported. + * + * This function sets up an array of ::STR_TYPE_INFO_IDX structures with the + * well-known supported string types, so applications can simply deal with + * the current API structures. + * + * @param[out] stii Array with at least @a p_ri->n_str_type ::STR_TYPE_INFO_IDX elements to be filled up. + * @param[in] p_ri Pointer to a ::RECEIVER_INFO structure providing the number of supported COM ports. + * + * @return One of the @ref MBG_RETURN_CODES, but actually always ::MBG_SUCCESS. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::setup_port_info_from_port_parm + */ int setup_default_str_type_info_idx( STR_TYPE_INFO_IDX stii[], const RECEIVER_INFO *p_ri ) ; + + /** + * @brief Determine how many GNSS systems are marked to be supported. + * + * This function counts the number of bits that are set to indicate + * that specific GNSS types (GPS, GLONASS, Galileo, ...) are supported + * by the device, and sets up the ::ALL_GNSS_INFO::n_gnss_supp field + * accordingly. + * + * @param[in,out] p_agi Address of an ::ALL_GNSS_INFO structure to be updated. + * + * @return ::MBG_SUCCESS on success, or ::MBG_ERR_N_GNSS_EXCEEDS_SUPP if the + * number of bits that are set exceeds the number of known GNSS types. + */ int chk_set_n_gnss_supp( ALL_GNSS_INFO *p_agi ) ; + /** - * @brief + * @brief Setup GNSS sat info from the legacy GPS ::STAT_INFO. * - * ### Setup GNSS info from stat_info so we can use the same printing routine + * This simplyifies further evaluation since e.g. a common + * display routine can be used. + * + * @param[in,out] p_agi Address of an ::ALL_GNSS_INFO structure to be updated. */ - void setup_gps_only_sat_info_idx_from_statinfo( ALL_GNSS_INFO *p_agi ) ; + void setup_gps_only_gnss_sat_info_idx_from_stat_info( ALL_GNSS_INFO *p_agi ) ; /** - * @brief + * @brief Setup GNSS mode info from the legacy GPS ::STAT_INFO. + * + * This simplyifies further evaluation since e.g. a common + * display routine can be used. * - * Setup GNSS info from stat_info so we can use the same printing routine + * @param[in,out] p_agi Address of an ::ALL_GNSS_INFO structure to be updated. */ - int setup_gps_only_gnss_info_from_statinfo( ALL_GNSS_INFO *p_agi ) ; + int setup_gps_only_gnss_mode_info_from_stat_info( ALL_GNSS_INFO *p_agi ) ; void chk_free_dev_hw_id( DEVICE_INFO *p ) ; int alloc_dev_hw_id( DEVICE_INFO *p, size_t len ) ; const char *get_fw_id_from_hw_id( const char *hw_id ) ; const char *get_hw_id_from_fw_id( const char *fw_id ) ; /** - * @brief Returns the currently used ::MBG_IO_PORT_TYPE_INFO for the appropriate ::MBG_IO_PORT + * @brief Return the currently used ::MBG_IO_PORT_TYPE_INFO for the appropriate ::MBG_IO_PORT. * - * @param[in] port Pointer to the ::MBG_IO_PORT to search for port_type - * @param[in] port_type Enum value of ::MBG_IO_PORT_TYPES to search for in port (::MBG_IO_PORT) + * @param[in] port Pointer to the ::MBG_IO_PORT to search for port_type + * @param[in] port_type Enum value of ::MBG_IO_PORT_TYPES to search for in @a port (::MBG_IO_PORT) * - * @return Pointer to the ::MBG_IO_PORT_TYPE_INFO_IDX found, or NULL + * @return Pointer to the ::MBG_IO_PORT_TYPE_INFO_IDX found, or NULL. */ - MBG_IO_PORT_TYPE_INFO* get_io_port_type_info( const MBG_IO_PORT *port, uint16_t port_type ) ; + MBG_IO_PORT_TYPE_INFO *get_io_port_type_info( const MBG_IO_PORT *port, uint16_t port_type ) ; /** - * @brief Initializes a ::MBG_TLV_ANNOUNCE structure + * @brief Initialize a ::MBG_TLV_ANNOUNCE structure. * - * @param[out] tlv Pointer to a ::MBG_TLV_ANNOUNCE structure - * @param[in] uid Unique sender ID used as identifier with all - * subsequent messages related to this transaction. - * @param[in] tlv_feat_type One of the ::MBG_TLV_FEAT_TYPES - * @param[in] total_bytes Total number of bytes of all upcoming TLVs + * @param[out] tlv Pointer to a ::MBG_TLV_ANNOUNCE structure. + * @param[in] uid Unique sender ID used as identifier with all + * subsequent messages related to this transaction. + * @param[in] tlv_feat_type One of the ::MBG_TLV_FEAT_TYPES. + * @param[in] total_bytes Total number of bytes of all upcoming TLVs. */ void mbg_tlv_announce_init( MBG_TLV_ANNOUNCE *tlv, MBG_TLV_UID uid, MBG_TLV_TYPE tlv_feat_type, uint32_t total_bytes ) ; /** - * @brief Initializes a ::MBG_TLV + * @brief Initialize a ::MBG_TLV structure. * - * @param[out] tlv Pointer to a valid ::MBG_TLV structure - * @param[in] uid Unique sender ID used as identifier for each further + * @param[out] tlv Pointer to a valid ::MBG_TLV structure. + * @param[in] uid Unique sender ID used as identifier for each further * TLV message related to this type. - * @param[in] tlv_type Type identifier, see ::MBG_TLV_TYPES - * @param[in] total_bytes Total number of bytes belonging to this - * TLV transaction (which is very likely split into several TLVs) + * @param[in] tlv_type Type identifier, see ::MBG_TLV_TYPES. + * @param[in] total_bytes Total number of bytes belonging to this TLV transaction + * (which is very likely split into several TLVs) */ void mbg_tlv_init( MBG_TLV *tlv, MBG_TLV_UID uid, MBG_TLV_TYPE tlv_type, uint32_t total_bytes ) ; /** - * @brief Initializes ::MBG_TLV_RCV_STATE structure + * @brief Initialize ::MBG_TLV_RCV_STATE structure. * - * @param[in,out] state Pointer to ::MBG_TLV_RCV_STATE structure - * @param[in] uid Unique sender ID used as identifier for each further - * TLV message related to this type. - * @param[in] total_bytes Total number of bytes belonging to this - * TLV transaction (which is very likely split into several TLVS) + * @param[out] state Pointer to ::MBG_TLV_RCV_STATE structure to be initialized. + * @param[in] uid Unique sender ID used as identifier for each further + * TLV message related to this type. + * @param[in] total_bytes Total number of bytes belonging to this TLV transaction + * (which is very likely split into several TLVS) */ void mbg_tlv_rcv_state_init( MBG_TLV_RCV_STATE *state, MBG_TLV_UID uid, uint32_t total_bytes ) ; - int mbg_snprint_revision( char *buf, size_t buflen, const char *prefix, const char *suffix, uint32_t rev) ; + /** + * @brief Print some Meinberg OS revision information into a string buffer. + * + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] prefix Pointer to an optional prefix string, or NULL. + * @param[in] suffix Pointer to an optional suff string, or NULL. + * @param[in] rev The revision code which will be split into major, minor, and patch version. + * + * @return Length of the string in the buffer. + * + * @see @ref group_ext_sys_info + */ + int mbg_snprint_revision( char *s, size_t max_len, const char *prefix, const char *suffix, uint32_t rev ) ; + + /** + * @brief Check if all ::RECEIVER_INFO capabilities reported by a device are supported by the current driver. + * + * @param[in] p Address of a ::RECEIVER_INFO structure to be checked. + * + * @return ::MBG_SUCCESS if everything is OK, one of the @ref MBG_ERROR_CODES, as appropriate. + */ _NO_MBG_API_ATTR int _MBG_API chk_dev_receiver_info( const RECEIVER_INFO *p ) ; + _NO_MBG_API_ATTR int _MBG_API chk_dev_xbp_supp_nodes( const ALL_XBP_INFO *info ) ; _NO_MBG_API_ATTR int _MBG_API chk_dev_net_cfg_supp_stage_2( const ALL_NET_CFG_INFO *info ) ; _NO_MBG_API_ATTR int _MBG_API chk_dev_ntp_supp_client( const ALL_NTP_CFG_INFO *info ) ; _NO_MBG_API_ATTR int _MBG_API chk_dev_ntp_supp_server( const ALL_NTP_CFG_INFO *info ) ; + /** + * @brief Check if the ::XMULTI_EXT_REF_INSTANCES structure is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_supp_ext_instances( const ALL_XMULTI_REF_INFO *info ) ; + + /** + * @brief Check if the ::XMULTI_EXT_REF_INSTANCES structure is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_not_configurable( const ALL_XMULTI_REF_INFO *info ) ; + + /** + * @brief Check if the ::XMRIF_BIT_NO_STATUS bit is set. + * + * If this feature bit is set, ***no*** status, stats, etc., are provided. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS if the bit is set, or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_no_status( const ALL_XMULTI_REF_INFO *info ) ; + + /** + * @brief Check if the ::XMRIF_BIT_MRF_NONE_SUPP bit is set. + * + * If this feature bit is set, the MRS pseudo-type ::MULTI_REF_NONE is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS if the bit is set, or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_mrf_none( const ALL_XMULTI_REF_INFO *info ) ; + + /** + * @brief Check if the ::XMR_EXT_SRC_INFO structure is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_src_info( const ALL_XMULTI_REF_INFO *info ) ; + + /** + * @brief Check if the ::::XMR_EXT_SRC_INFO structure is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_holdover_status( const ALL_XMULTI_REF_INFO *info ) ; - /* - * Type is NOT an index of ::XMULTI_REF_INSTANCES::n_xmr_settings, - * but of ::MULTI_REF_TYPES. - * Depends on chk_dev_supp_xmulti_ref_ext_src_info. - * @see chk_dev_supp_xmulti_ref_ext_src_info + + /** + * @brief Check if an XMR source provides ::XMR_STATS. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * @param[in] type One of the ::MULTI_REF_TYPES, except ::MULTI_REF_NONE which is -1. + * + * @see ::chk_dev_supp_xmulti_ref_ext_src_info */ _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_source_stats( const ALL_XMULTI_REF_INFO *info, int type ) ; - /* - * Type is NOT an index of ::XMULTI_REF_INSTANCES::n_xmr_settings, - * but of ::MULTI_REF_TYPES. - * Depends on chk_dev_supp_xmulti_ref_ext_src_info. - * @see chk_dev_supp_xmulti_ref_ext_src_info + /** + * @brief Check if an XMR source provides ::XMR_METRICS. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * @param[in] type One of the ::MULTI_REF_TYPES, except ::MULTI_REF_NONE which is -1. + * + * @see ::chk_dev_xmulti_ref_supp_ext_source_adv_metrics + * @see ::chk_dev_supp_xmulti_ref_ext_src_info */ _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_source_metrics( const ALL_XMULTI_REF_INFO *info, int type ) ; + /** + * @brief Check if an XMR source supports advanced XMR QL metrics configuration + * + * If this feature is not available, ::XMR_METRICS can not be configured. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * @param[in] type One of the ::MULTI_REF_TYPES, except ::MULTI_REF_NONE which is -1. + * + * @see ::XMR_QL_LIMITS + * @see ::chk_dev_xmulti_ref_supp_ext_source_metrics + * @see ::chk_dev_supp_xmulti_ref_ext_src_info + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_source_adv_metrics( const ALL_XMULTI_REF_INFO *info, int type ) ; + + /** + * @brief Check if an XMR source XMR source supports coasting mode. + * + * If this feature is not available, ::XMR_METRICS can not be configured. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * @param[in] type One of the ::MULTI_REF_TYPES, except ::MULTI_REF_NONE which is -1. + * + * @see ::XMR_QL_LIMITS + * @see ::chk_dev_supp_xmulti_ref_ext_src_info + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_source_coasting( const ALL_XMULTI_REF_INFO *info, int type ) ; + _NO_MBG_API_ATTR int _MBG_API chk_dev_ims_has_fdm( const ALL_IMS_INFO *info ) ; _NO_MBG_API_ATTR int _MBG_API chk_dev_ims_is_volt_out_enabled( const ALL_IMS_STATE *ims_state, unsigned idx ) ; _NO_MBG_API_ATTR int _MBG_API chk_dev_ims_is_volt_out_overload( const ALL_IMS_STATE *ims_state, unsigned idx ) ; @@ -1334,9 +1716,10 @@ MBG_TLV_UID mbg_tlv_create_id( void ) _NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_supp_ass_idx( const ALL_GPIO_INFO *gpio_info, unsigned idx ) ; _NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_dep_on_ass_idx( const ALL_GPIO_INFO *gpio_info, unsigned idx ) ; /** - * @brief Checks whether GPIO supports status function + * @brief Check whether GPIO provides a status. * - * @param[out] info Pointer to a ::ALL_GPIO_INFO structure to be filled up + * @param[out] info Pointer to a ::ALL_GPIO_INFO structure to be filled up ::FIXME + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. * * @return One of the @ref MBG_RETURN_CODES * @@ -1353,7 +1736,7 @@ MBG_TLV_UID mbg_tlv_create_id( void ) * * @see ::mbgextio_get_all_xbp_info */ - void free_all_xbp_info ( ALL_XBP_INFO *p ) ; + void free_all_xbp_info( ALL_XBP_INFO *p ) ; /** * @brief Free an ::ALL_NET_CFG_INFO structure @@ -1362,7 +1745,7 @@ MBG_TLV_UID mbg_tlv_create_id( void ) * * @see ::mbgextio_get_all_net_cfg_info */ - void free_all_net_cfg_info ( ALL_NET_CFG_INFO *p ) ; + void free_all_net_cfg_info( ALL_NET_CFG_INFO *p ) ; /** * @brief Free an ::ALL_NET_STATUS_INFO structure @@ -1371,7 +1754,7 @@ MBG_TLV_UID mbg_tlv_create_id( void ) * * @see ::mbgextio_get_all_net_status_info */ - void free_all_net_status_info ( ALL_NET_STATUS_INFO *p ) ; + void free_all_net_status_info( ALL_NET_STATUS_INFO *p ) ; /** * @brief Free an ::ALL_SNMP_INFO structure @@ -1458,6 +1841,36 @@ MBG_TLV_UID mbg_tlv_create_id( void ) void free_all_ntp_status( ALL_NTP_STATUS *p ) ; /** + * @brief Free an ::ALL_PTP_NG_INFO structure + * + * @param[in] p Pointer to the ::ALL_PTP_NG_INFO structure to be freed + * + * @see ::mbgextio_get_all_ptp_ng_info + */ + void free_all_ptp_ng_info( ALL_PTP_NG_INFO *p ) ; + + /** + * @brief Free a list of ::MBG_SYS_REF_SRC structures + * + * @param[in] p Pointer to the ::MBG_SYS_REF_SRC list to be freed + * @param[in] free_source Address of a function to be called to free resources. + * + * @see ::mbgextio_get_all_sys_ref_info + * @see ::free_all_sys_ref_info + */ + void free_all_sys_ref_srcs( struct mbg_klist_head *p, void (*free_source)( MBG_SYS_REF_SRC * ) ) ; + + /** + * @brief Free an ::ALL_SYS_REF_INFO structure + * + * @param[in] p Pointer to the ::ALL_SYS_REF_INFO structure to be freed + * + * @see ::mbgextio_get_all_sys_ref_info + * @see ::free_all_sys_ref_srcs + */ + void free_all_sys_ref_info( ALL_SYS_REF_INFO *p ) ; + + /** * @brief Free memory allocated by ::mbgextio_get_all_ims_info * * @param[in] p Pointer to the ::ALL_IMS_INFO structure to be freed @@ -1521,7 +1934,7 @@ MBG_TLV_UID mbg_tlv_create_id( void ) * * @return The new allocated ::UCAP_ENTRY or NULL if the calloc call was not successful */ - UCAP_ENTRY* calloc_ucap_entry( void ) ; + UCAP_ENTRY *calloc_ucap_entry( void ) ; /** * @brief Free memory allocated by ::mbgextio_get_all_ucap_info @@ -1614,6 +2027,35 @@ MBG_TLV_UID mbg_tlv_create_id( void ) */ void str_ntp_hex_to_nano_time_64( const char *s, NANO_TIME_64 *p ) ; + /** + * @brief Convert PTP binary config to Oregano config file + * + * @param[in] ptp_info Complete PTP config binary structure + * @param[in] instc PTP instance to write config for + * @param[in] inst_num PTP instance number on its timestamper + * @param[in] intf_lnk Associated interface link settings to determine VLAN ID + * @param[in] ip_addr Associated interface link settings to determine VLAN ID + * @param[in] ascii_file_name Target file name for the oregano cfg file + * + */ + _NO_MBG_API_ATTR int _MBG_API mbg_cnv_ptp_cfg_to_oreg_cfg_file( const ALL_PTP_NG_INFO *ptp_info, const MBG_PTP_NG_INSTC *instc, unsigned inst_num, const MBG_NET_INTF_LINK_SETTINGS *intf_lnk, const MBG_IP_ADDR *ip_addr, const char *ascii_file_name ) ; + + /** + * @brief cnvrt_bytes_to_long + */ + uint64_t cnvrt_bytes_to_long( const uint8_t byte_array[], int num_bytes ) ; + + /** + * @brief cnvrt_long_to_bytes + */ + void cnvrt_long_to_bytes( uint8_t byte_array[], int num_bytes, uint64_t val ) ; + + size_t nw_str_mac_addr_to_str( MBG_MAC_ADDR *mac_addr, char *buf, size_t buflen ) ; + int nw_str_to_mac_addr( MBG_MAC_ADDR *mac_addr, const char *str ) ; + int nw_ip6_addr_bytes_to_str( const uint8_t *addr, uint8_t protocol, char *str, size_t buflen ) ; + int nw_str_to_ip6_addr_bytes( uint8_t *addr, const uint8_t protocol, char *str, size_t buflen ) ; + int mbg_os_version_to_str( const MBG_EXT_SYS_INFO *info, char *buf, size_t buflen, int long_version ) ; + int mbg_fw_can_set_osv(const MBG_FW_GLB_INFO *info) ; /* ----- function prototypes end ----- */ diff --git a/mbglib/common/cmp_time_util.c b/mbglib/common/cmp_time_util.c index 4e99cc6..dea645a 100644 --- a/mbglib/common/cmp_time_util.c +++ b/mbglib/common/cmp_time_util.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: cmp_time_util.c 1.3 2018/12/11 12:01:03Z martin REL_M $ + * $Id: cmp_time_util.c 1.9 2021/04/29 14:20:20Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,20 @@ * * ----------------------------------------------------------------------- * $Log: cmp_time_util.c $ - * Revision 1.3 2018/12/11 12:01:03Z martin + * Revision 1.9 2021/04/29 14:20:20Z martin + * Variable pc_cycles_frequency was renamed to mbg_pc_cycles_frequency. + * Revision 1.8 2021/03/22 10:09:38 martin + * Updated some comments. + * Revision 1.7 2021/03/12 14:20:16 martin + * Use the new global variable pc_cycles_frequency. + * Revision 1.6 2020/11/04 17:17:38 martin + * Added some functions to support checking the continuity of the timestamps + * and status sequentially read from a device. + * Revision 1.5 2020/05/11 09:35:13 martin + * Removed obsolete 'extern' declaration of variable 'cyc_freq'. + * Revision 1.4 2019/09/25 16:07:44 martin + * Removed inclusion of obsolete header pcpsutil.h. + * Revision 1.3 2018/12/11 12:01:03 martin * Fixed compiler warnings on Windows. * Revision 1.2 2018/08/08 08:22:23Z martin * New function mbg_snprint_hr_time_loc(). @@ -27,7 +40,6 @@ #include <mbgdevio.h> #include <mbgutil.h> -#include <pcpsutil.h> #include <str_util.h> #include <toolutil.h> // for mbg_snprint_hr_tstamp(). FIXME: use function from mbgutil library @@ -35,21 +47,17 @@ #include <stdio.h> -extern MBG_PC_CYCLES_FREQUENCY cyc_freq; ///< Must be set up tby the application. - - - /*HDR*/ /** * @brief Check if both devices support fast HR timestamps. * - * @param[in] dh1 Handle of the first device - * @param[in] p_dev_1 Device info of the first device - * @param[in] dh2 Handle of the second device - * @param[in] p_dev_2 Device info of the second device - * @param[in] err_msg_fnc Pointer to a function to be called in case of error + * @param[in] dh1 Handle of the first device. + * @param[in] p_dev_1 Device info of the first device. + * @param[in] dh2 Handle of the second device. + * @param[in] p_dev_2 Device info of the second device. + * @param[in] err_msg_fnc Pointer to a function to be called in case of error. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ int chk_fast_tstamp_supp( MBG_DEV_HANDLE dh1, const PCPS_DEV *p_dev_1, MBG_DEV_HANDLE dh2, const PCPS_DEV *p_dev_2, @@ -72,15 +80,15 @@ int chk_fast_tstamp_supp( MBG_DEV_HANDLE dh1, const PCPS_DEV *p_dev_1, /*HDR*/ /** - * @brief Read timestamps and cycles from both devices + * @brief Read timestamps and cycles from both devices. * - * @param[in] dh1 Handle of the first device - * @param[out] p_htc1 Timestamp and cycles read from the first device - * @param[in] dh2 Handle of the second device - * @param[out] p_htc2 Timestamp and cycles read from the first device - * @param[in] read_fast Flag indicating that fast timestamps should be read + * @param[in] dh1 Handle of the first device. + * @param[out] p_htc1 Timestamp and cycles read from the first device. + * @param[in] dh2 Handle of the second device. + * @param[out] p_htc2 Timestamp and cycles read from the first device. + * @param[in] read_fast Flag indicating that fast timestamps should be read. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ int get_htc_timestamps( MBG_DEV_HANDLE dh1, PCPS_HR_TIME_CYCLES *p_htc1, MBG_DEV_HANDLE dh2, PCPS_HR_TIME_CYCLES *p_htc2, @@ -128,12 +136,12 @@ done: /*HDR*/ /** - * @brief Compute the delta cycles and time difference + * @brief Compute the delta cycles and time difference. * * @param[in] p_htc Timestamp/cycles t from device under test. * @param[in] p_htc_ref Timestamp/cycles t_ref from reference device. - * @param[out] p_delta_ts Pointer to save time difference (t - tref), can be NULL. - * @param[out] p_delta_cyc Pointer to save delta cycles (t - tref), can be NULL. + * @param[out] p_delta_ts Pointer to save time difference (t - tref), can be @a NULL. + * @param[out] p_delta_cyc Pointer to save delta cycles (t - tref), can be @a NULL. * * @return The difference between delta_t and delta_cycles. */ @@ -150,10 +158,10 @@ double get_htc_delta( const PCPS_HR_TIME_CYCLES *p_htc, #if defined( MBG_TGT_WIN32 ) { __int64 dt_t = p_htc->cycles - p_htc_ref->cycles; - delta_cyc = (double) dt_t / (__int64) cyc_freq; + delta_cyc = (double) dt_t / (__int64) mbg_pc_cycles_frequency; } #else - delta_cyc = ( (double) ( p_htc->cycles - p_htc_ref->cycles ) ) / cyc_freq; + delta_cyc = ( (double) ( p_htc->cycles - p_htc_ref->cycles ) ) / mbg_pc_cycles_frequency; #endif if ( p_delta_ts ) @@ -170,7 +178,80 @@ double get_htc_delta( const PCPS_HR_TIME_CYCLES *p_htc, /*HDR*/ /** - * @brief Print UTC date and time from a ::PCPS_TIME_STAMP structure to a string + * @brief Print a HR time stamp, and optionally a status and time difference. + * + * @param[in] p_ts Pointer to the time stamp. + * @param[in] p_st Pointer to the status code, optional, can be @a NULL. + * @param[in] p_d Pointer to the variable with time difference in microseconds, can be @a NULL. + * + * @see ::mbg_check_continuity + */ +void mbg_show_delta_exceeded( const PCPS_TIME_STAMP *p_ts, const PCPS_TIME_STATUS_X *p_st, const double *p_d ) +{ + char s[256]; + size_t sz = sizeof( s ); + int n = 0; + + n += mbg_snprint_hr_tstamp( &s[n], sz - n, p_ts, 0, 1 ); + + if ( p_st ) + n += snprintf_safe( &s[n], sz - n, ", st 0x%04X", *p_st ); + + if ( p_d ) + n += snprintf_safe( &s[n], sz - n, ", d: %.3f us\n", *p_d ); + + fprintf( stderr, "%s\n", s ); + +} // mbg_show_delta_exceeded + + + +/*HDR*/ +/** + * @brief Check continuity of 2 subsequent time stamps and status codes. + * + * Compares the current timestamp to the previous timestamp, + * and optionally, the current sttus to the previous status. + * + * Calls ::mbg_show_delta_exceeded if the time difference + * is less than 0, or exceeeds @p max_allowed_delta_us, + * or if the status has changed. + * + * @param[in] p_ts Pointer to the current time stamp. + * @param[in] p_prv_ts Pointer to the previous time stamp. + * @param[in] p_st Pointer to the current status code, optional, can be @a NULL. + * @param[in] p_prv_st Pointer to the previous status code, optional, can be @a NULL. + * @param[in] max_allowed_delta_us Maximum allowed time difference, in microseconds. + * + * @see ::mbg_show_delta_exceeded + */ +void mbg_check_continuity( const PCPS_TIME_STAMP *p_ts, const PCPS_TIME_STAMP *p_prv_ts, + const PCPS_TIME_STATUS_X *p_st, const PCPS_TIME_STATUS_X *p_prv_st, + double max_allowed_delta_us ) +{ + int must_show = 0; + + double d = delta_timestamp_us( p_ts, p_prv_ts ); + + if ( ( d < 0 ) || ( d > max_allowed_delta_us ) ) + must_show = 1; + + if ( p_st && p_prv_st && ( *p_st != *p_prv_st ) ) + must_show = 1; + + if ( must_show ) + { + mbg_show_delta_exceeded( p_prv_ts, p_prv_st, NULL ); + mbg_show_delta_exceeded( p_ts, p_st, &d ); + } + +} // mbg_check_continuity + + + +/*HDR*/ +/** + * @brief Print %UTC date and time from a ::PCPS_TIME_STAMP structure to a string. * * This function is mostly similar to ::mbg_snprint_hr_tstamp, but optionally * appends the raw timestamp instead of inserting it at the beginning. @@ -180,7 +261,8 @@ double get_htc_delta( const PCPS_HR_TIME_CYCLES *p_htc, * @param[in] p Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. * @param[in] print_raw Flag indicating if a raw timestamp (hex) is to be appended. * - * @return The number of characters printed to the buffer. + * @return The number of characters written to the string buffer, + * except the terminating 0. * * @see ::mbg_snprint_hr_tstamp * @see ::mbg_snprint_hr_time_loc @@ -203,7 +285,7 @@ int mbg_snprint_hr_tstamp_ext( char *s, int max_len, /*HDR*/ /** - * @brief Print local date and time from a ::PCPS_TIME_STAMP structure to a string + * @brief Print local date and time from a ::PCPS_TIME_STAMP structure to a string. * * This function is mostly similar to ::mbg_snprint_hr_tstamp, but optionally * appends the raw timestamp instead of inserting it at the beginning. @@ -212,7 +294,8 @@ int mbg_snprint_hr_tstamp_ext( char *s, int max_len, * @param[in] max_len Size of the string buffer. * @param[in] p Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. * - * @return The number of characters printed to the buffer. + * @return The number of characters written to the string buffer, + * except the terminating 0. * * @see ::mbg_snprint_hr_tstamp * @see ::mbg_snprint_hr_tstamp_ext diff --git a/mbglib/common/cmp_time_util.h b/mbglib/common/cmp_time_util.h index ad93f7e..a85434d 100644 --- a/mbglib/common/cmp_time_util.h +++ b/mbglib/common/cmp_time_util.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: cmp_time_util.h 1.2 2018/08/08 08:23:28Z martin REL_M $ + * $Id: cmp_time_util.h 1.5 2021/03/22 17:37:32Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,14 @@ * * ----------------------------------------------------------------------- * $Log: cmp_time_util.h $ - * Revision 1.2 2018/08/08 08:23:28Z martin + * Revision 1.5 2021/03/22 17:37:32Z martin + * Updated some comments. + * Revision 1.4 2021/03/12 14:20:20 martin + * Use the new global variable pc_cycles_frequency. + * Revision 1.3 2020/11/04 17:17:37 martin + * Added some functions to support checking the continuity of the timestamps + * and status sequentially read from a device. + * Revision 1.2 2018/08/08 08:23:28 martin * Moved some functions and structures to more convenient files. * Fixed Windows build. * Updated function prototypes. @@ -39,7 +46,7 @@ /* Start of header body */ #if 0 && defined( _USE_PACK ) // use default alignment - #pragma pack( 1 ) // set byte alignment + #pragma pack( 1 ) // Set byte alignment. #define _USING_BYTE_ALIGNMENT #endif @@ -48,7 +55,6 @@ extern "C" { #endif -_ext MBG_PC_CYCLES_FREQUENCY cyc_freq; #if defined( MBG_TGT_WIN32 ) #define snprintf _snprintf @@ -64,43 +70,74 @@ _ext MBG_PC_CYCLES_FREQUENCY cyc_freq; /** * @brief Check if both devices support fast HR timestamps. * - * @param[in] dh1 Handle of the first device - * @param[in] p_dev_1 Device info of the first device - * @param[in] dh2 Handle of the second device - * @param[in] p_dev_2 Device info of the second device - * @param[in] err_msg_fnc Pointer to a function to be called in case of error + * @param[in] dh1 Handle of the first device. + * @param[in] p_dev_1 Device info of the first device. + * @param[in] dh2 Handle of the second device. + * @param[in] p_dev_2 Device info of the second device. + * @param[in] err_msg_fnc Pointer to a function to be called in case of error. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ int chk_fast_tstamp_supp( MBG_DEV_HANDLE dh1, const PCPS_DEV *p_dev_1, MBG_DEV_HANDLE dh2, const PCPS_DEV *p_dev_2, MBG_ERR_MSG_FNC err_msg_fnc ) ; /** - * @brief Read timestamps and cycles from both devices + * @brief Read timestamps and cycles from both devices. * - * @param[in] dh1 Handle of the first device - * @param[out] p_htc1 Timestamp and cycles read from the first device - * @param[in] dh2 Handle of the second device - * @param[out] p_htc2 Timestamp and cycles read from the first device - * @param[in] read_fast Flag indicating that fast timestamps should be read + * @param[in] dh1 Handle of the first device. + * @param[out] p_htc1 Timestamp and cycles read from the first device. + * @param[in] dh2 Handle of the second device. + * @param[out] p_htc2 Timestamp and cycles read from the first device. + * @param[in] read_fast Flag indicating that fast timestamps should be read. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ int get_htc_timestamps( MBG_DEV_HANDLE dh1, PCPS_HR_TIME_CYCLES *p_htc1, MBG_DEV_HANDLE dh2, PCPS_HR_TIME_CYCLES *p_htc2, int read_fast ) ; /** - * @brief Compute the delta cycles and time difference + * @brief Compute the delta cycles and time difference. * * @param[in] p_htc Timestamp/cycles t from device under test. * @param[in] p_htc_ref Timestamp/cycles t_ref from reference device. - * @param[out] p_delta_ts Pointer to save time difference (t - tref), can be NULL. - * @param[out] p_delta_cyc Pointer to save delta cycles (t - tref), can be NULL. + * @param[out] p_delta_ts Pointer to save time difference (t - tref), can be @a NULL. + * @param[out] p_delta_cyc Pointer to save delta cycles (t - tref), can be @a NULL. * * @return The difference between delta_t and delta_cycles. */ double get_htc_delta( const PCPS_HR_TIME_CYCLES *p_htc, const PCPS_HR_TIME_CYCLES *p_htc_ref, double *p_delta_ts, double *p_delta_cyc ) ; /** - * @brief Print UTC date and time from a ::PCPS_TIME_STAMP structure to a string + * @brief Print a HR time stamp, and optionally a status and time difference. + * + * @param[in] p_ts Pointer to the time stamp. + * @param[in] p_st Pointer to the status code, optional, can be @a NULL. + * @param[in] p_d Pointer to the variable with time difference in microseconds, can be @a NULL. + * + * @see ::mbg_check_continuity + */ + void mbg_show_delta_exceeded( const PCPS_TIME_STAMP *p_ts, const PCPS_TIME_STATUS_X *p_st, const double *p_d ) ; + + /** + * @brief Check continuity of 2 subsequent time stamps and status codes. + * + * Compares the current timestamp to the previous timestamp, + * and optionally, the current sttus to the previous status. + * + * Calls ::mbg_show_delta_exceeded if the time difference + * is less than 0, or exceeeds @p max_allowed_delta_us, + * or if the status has changed. + * + * @param[in] p_ts Pointer to the current time stamp. + * @param[in] p_prv_ts Pointer to the previous time stamp. + * @param[in] p_st Pointer to the current status code, optional, can be @a NULL. + * @param[in] p_prv_st Pointer to the previous status code, optional, can be @a NULL. + * @param[in] max_allowed_delta_us Maximum allowed time difference, in microseconds. + * + * @see ::mbg_show_delta_exceeded + */ + void mbg_check_continuity( const PCPS_TIME_STAMP *p_ts, const PCPS_TIME_STAMP *p_prv_ts, const PCPS_TIME_STATUS_X *p_st, const PCPS_TIME_STATUS_X *p_prv_st, double max_allowed_delta_us ) ; + + /** + * @brief Print %UTC date and time from a ::PCPS_TIME_STAMP structure to a string. * * This function is mostly similar to ::mbg_snprint_hr_tstamp, but optionally * appends the raw timestamp instead of inserting it at the beginning. @@ -110,7 +147,8 @@ _ext MBG_PC_CYCLES_FREQUENCY cyc_freq; * @param[in] p Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. * @param[in] print_raw Flag indicating if a raw timestamp (hex) is to be appended. * - * @return The number of characters printed to the buffer. + * @return The number of characters written to the string buffer, + * except the terminating 0. * * @see ::mbg_snprint_hr_tstamp * @see ::mbg_snprint_hr_time_loc @@ -118,7 +156,7 @@ _ext MBG_PC_CYCLES_FREQUENCY cyc_freq; int mbg_snprint_hr_tstamp_ext( char *s, int max_len, const PCPS_TIME_STAMP *p, int print_raw ) ; /** - * @brief Print local date and time from a ::PCPS_TIME_STAMP structure to a string + * @brief Print local date and time from a ::PCPS_TIME_STAMP structure to a string. * * This function is mostly similar to ::mbg_snprint_hr_tstamp, but optionally * appends the raw timestamp instead of inserting it at the beginning. @@ -127,7 +165,8 @@ _ext MBG_PC_CYCLES_FREQUENCY cyc_freq; * @param[in] max_len Size of the string buffer. * @param[in] p Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. * - * @return The number of characters printed to the buffer. + * @return The number of characters written to the string buffer, + * except the terminating 0. * * @see ::mbg_snprint_hr_tstamp * @see ::mbg_snprint_hr_tstamp_ext @@ -143,7 +182,7 @@ _ext MBG_PC_CYCLES_FREQUENCY cyc_freq; #if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment + #pragma pack() // Set default alignment. #undef _USING_BYTE_ALIGNMENT #endif diff --git a/mbglib/common/ctry.c b/mbglib/common/ctry.c index c726f22..b397f3a 100644 --- a/mbglib/common/ctry.c +++ b/mbglib/common/ctry.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: ctry.c 1.7 2010/07/15 08:26:57Z martin REL_M $ + * $Id: ctry.c 1.8 2021/03/16 12:21:12Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -14,7 +14,9 @@ * * ----------------------------------------------------------------------- * $Log: ctry.c $ - * Revision 1.7 2010/07/15 08:26:57Z martin + * Revision 1.8 2021/03/16 12:21:12Z martin + * Updated some comments. + * Revision 1.7 2010/07/15 08:26:57 martin * Added clstr_lng() implemented by stefan returning a translated string * by giving the different strings as function arguments. * Revision 1.6 2007/03/29 12:21:51 martin @@ -44,32 +46,48 @@ #include <string.h> -// Return the index of a CLSTR component for a -// certain language lng /*HDR*/ +/** + * @brief Return the index of a CLSTR component for a certain language code. + * + * If the strings for several languages are the same, only the first + * array entry may be populated, while the others are all @a NULL, + * so the returned index differs from the language code @p lng. + * + * @param[in] s Pointer to a constant array of localized strings. + * @param[in] lng The language code 0..::N_LNG-1. + * + * @return The index to the array @p s, derived from @p lng. + */ int lstr_idx( CLSTR s, int lng ) { - if ( lng >= N_LNG ) // if lng out of range - return 0; // use default index + if ( lng >= N_LNG ) // If lng out of range, + return 0; // use default index. - // If there are duplicate strings for several languages - // then the duplicate strings may be NULL, in which case - // the string at index 0 must be used. + // If the array entry for the selected language is 0, + // return index 0 for the default entry. return s[lng] ? lng : 0; } // lstr_idx -// Return the index of a CLSTR component for a -// certain language lng out of an array of CLSTRs. -// CLSTR s: the array of CLSTRs -// int idx: the index of the array element -// int n_lng: the number of supported languages -// int lng: the language for which the inex shall be retrieved - /*HDR*/ +/** + * @brief Return the index of a ::CLSTR component for a certain language. + * + * If the strings for several languages are the same, only the first + * array entry may be populated, while the others are all @a NULL, + * so the returned index differs from the language code @p lng. + * + * @param[in] s The array of ::CLSTR entries. + * @param[in] idx The index of the array element. + * @param[in] n_lng The number of supported languages. + * @param[in] lng The language for which the index is to be retrieved. + * + * @return The index to the array @p s, derived from @p lng. + */ int lstr_array_idx( CLSTR s, int idx, int n_lng, int lng ) { int str_idx = n_lng * idx; @@ -80,6 +98,14 @@ int lstr_array_idx( CLSTR s, int idx, int n_lng, int lng ) /*HDR*/ +/** + * @brief Return a localized string according to a language code. + * + * @param[in] s Pointer to a constant array of localized strings. + * @param[in] lng The language code 0..::N_LNG-1. + * + * @return The string according to the language code. + */ const char *lstr_lng( CLSTR s, int lng ) { return s[lstr_idx( s, lng)]; @@ -89,6 +115,13 @@ const char *lstr_lng( CLSTR s, int lng ) /*HDR*/ +/** + * @brief Set up some localization depending on a specific country code. + * + * This sets up the global variable ::ctry. + * + * @param[in] code The ::CTRY_CODE. + */ void ctry_setup( CTRY_CODE code ) { language = LNG_ENGLISH; @@ -129,6 +162,11 @@ void ctry_setup( CTRY_CODE code ) /*HDR*/ +/** + * @brief Set up localization for the next supported country code. + * + * Used to easily switch between different country codes. + */ void ctry_next( void ) { switch ( ctry.code ) @@ -152,6 +190,14 @@ void ctry_next( void ) /*HDR*/ +/** + * @brief Return a string from an array of strings given as function arguments. + * + * @param[in] index Index of the string to be returned. + * @param[in] ... Variable number of string arguments. + * + * @return The string associated with the index. + */ const char *clstr_lng( int index, ... ) { const char *ret; diff --git a/mbglib/common/ctry.h b/mbglib/common/ctry.h index 816ebaf..723fac4 100644 --- a/mbglib/common/ctry.h +++ b/mbglib/common/ctry.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: ctry.h 1.14 2017/06/23 09:53:27Z martin REL_M $ + * $Id: ctry.h 1.17 2021/04/21 10:59:09Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,15 @@ * * ----------------------------------------------------------------------- * $Log: ctry.h $ - * Revision 1.14 2017/06/23 09:53:27Z martin + * Revision 1.17 2021/04/21 10:59:09Z martin + * Doxygen fixes. + * Revision 1.16 2021/04/13 21:31:52 martin + * Changed CTRY_CODES from enum back to defines because the enum type + * caused a build error on some system when being used as initializer. + * Updated some doxygen comments. + * Revision 1.15 2021/03/22 17:37:26 martin + * Updated some comments. + * Revision 1.14 2017/06/23 09:53:27 martin * Fixed spelling in an earlier log message. * Revision 1.13 2012/11/29 12:01:09 martin * Don't include mbg_tgt.h explicitly since this will anyway be @@ -83,7 +91,7 @@ /* Start of header body */ #if defined( _USE_PACK ) - #pragma pack( 1 ) // set byte alignment + #pragma pack( 1 ) // Set byte alignment. #define _USING_BYTE_ALIGNMENT #endif @@ -93,13 +101,16 @@ extern "C" { #endif -// the definitions below are used to support different languages: -typedef uint8_t LANGUAGE; +typedef uint8_t LANGUAGE; ///< A language code, see ::LNG_CODES. + typedef uint16_t CTRY_CODE; -// codes used with LANGUAGE: + #if !defined LNG_DEFINED - enum + /** + * @brief Codes used with ::LANGUAGE. + */ + enum LNG_CODES { LNG_ENGLISH, LNG_GERMAN, @@ -109,41 +120,51 @@ typedef uint16_t CTRY_CODE; #define LNG_DEFINED #endif -// the type below is used to declare string variables -// for several languages -typedef char *LSTR[N_LNG]; // array of strings -typedef char **PLSTR; // pointer to array +typedef char *LSTR[N_LNG]; ///< An array of strings for several languages. +typedef char **PLSTR; ///< A pointer to an array of strings for several languages. -// same as above, but const -typedef const char * const CLSTR[N_LNG]; // array of strings -typedef const char * const *PCLSTR; // pointer to array +typedef const char * const CLSTR[N_LNG]; ///< An array of strings like ::LSTR, but const. +typedef const char * const *PCLSTR; ///< A pointer to an array like ::PLSTR, but with const strings. -// the definitions below are used to handle date and time -// formats used by different countries: +/** + * @brief A structure for easy localization. + * + * Specifies date and time formats for selected countries. + */ typedef struct { - CTRY_CODE code; + CTRY_CODE code; ///< See @ref CTRY_CODES. - uint8_t dt_fmt; // (codes defined below) - uint8_t tm_fmt; // (codes defined below) - char dt_sep; // (valid chars defined below) - char tm_sep; // (valid chars defined below) + uint8_t dt_fmt; ///< See ::DT_FMT_CODES. + uint8_t tm_fmt; ///< See ::TM_FMT_CODES. + char dt_sep; ///< See @ref DT_SEP_CHARS. + char tm_sep; ///< See @ref TM_SEP_CHARS. } CTRY; -// codes used with CTRY.code: +/** + * @defgroup CTRY_CODES Country codes + * + * Used with ::CTRY::code. + * + * @{ */ + #define CTRY_US 1 #define CTRY_UK 44 #define CTRY_GERMANY 49 +/** @} defgroup CTRY_CODES */ + #ifndef CTRY_DEFINED #define CTRY_DEFINED - // codes used with CTRY.dt_fmt: - enum + /** + * @brief Codes used with ::CTRY::dt_fmt. + */ + enum DT_FMT_CODES { DT_FMT_DDMMYYYY, DT_FMT_MMDDYYYY, @@ -151,29 +172,52 @@ typedef struct N_DT_FMT }; - // codes used with CTRY.tm_fmt: - enum + + /** + * @brief Codes used with ::CTRY::tm_fmt. + */ + enum TM_FMT_CODES { TM_FMT_24H, - // TM_FMT_12H, // not yet supported + // TM_FMT_12H, // Not yet supported. N_TM_FMT }; - // codes used with CTRY.dt_sep: + /** + * @defgroup DT_SEP_CHARS Date string separator codes + * + * Used with ::CTRY::dt_sep. + * + * @{ */ + #define DT_SEP_DOT '.' #define DT_SEP_MINUS '-' #define DT_SEP_SLASH '/' - // a zero-terminated list of valid dt_sep characters + /** @} defgroup DT_SEP_CHARS */ + + /** + * @brief A zero-terminated list of valid @ref DT_SEP_CHARS characters. + */ #define DT_SEP_LIST { DT_SEP_DOT, DT_SEP_MINUS, DT_SEP_SLASH, 0 } - // codes used with CTRY.tm_sep: + /** + * @defgroup TM_SEP_CHARS Time string separator codes + * + * Used with ::CTRY::tm_sep. + * + * @{ */ + #define TM_SEP_COLON ':' #define TM_SEP_DOT '.' - // a zero-terminated list of valid tm_sep characters + /** @} defgroup TM_SEP_CHARS */ + + /** + * @brief A zero-terminated list of valid @ref TM_SEP_CHARS characters. + */ #define TM_SEP_LIST { TM_SEP_COLON, TM_SEP_DOT, 0 } #endif // CTRY_DEFINED @@ -213,13 +257,73 @@ extern CTRY ctry; /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ + /** + * @brief Return the index of a CLSTR component for a certain language code. + * + * If the strings for several languages are the same, only the first + * array entry may be populated, while the others are all @a NULL, + * so the returned index differs from the language code @p lng. + * + * @param[in] s Pointer to a constant array of localized strings. + * @param[in] lng The language code 0..::N_LNG-1. + * + * @return The index to the array @p s, derived from @p lng. + */ int lstr_idx( CLSTR s, int lng ) ; + + /** + * @brief Return the index of a ::CLSTR component for a certain language. + * + * If the strings for several languages are the same, only the first + * array entry may be populated, while the others are all @a NULL, + * so the returned index differs from the language code @p lng. + * + * @param[in] s The array of ::CLSTR entries. + * @param[in] idx The index of the array element. + * @param[in] n_lng The number of supported languages. + * @param[in] lng The language for which the index is to be retrieved. + * + * @return The index to the array @p s, derived from @p lng. + */ int lstr_array_idx( CLSTR s, int idx, int n_lng, int lng ) ; + + /** + * @brief Return a localized string according to a language code. + * + * @param[in] s Pointer to a constant array of localized strings. + * @param[in] lng The language code 0..::N_LNG-1. + * + * @return The string according to the language code. + */ const char *lstr_lng( CLSTR s, int lng ) ; + + /** + * @brief Set up some localization depending on a specific country code. + * + * This sets up the global variable ::ctry. + * + * @param[in] code The ::CTRY_CODE. + */ void ctry_setup( CTRY_CODE code ) ; + + /** + * @brief Set up localization for the next supported country code. + * + * Used to easily switch between different country codes. + */ void ctry_next( void ) ; + + /** + * @brief Return a string from an array of strings given as function arguments. + * + * @param[in] index Index of the string to be returned. + * @param[in] ... Variable number of string arguments. + * + * @return The string associated with the index. + */ const char *clstr_lng( int index, ... ) ; + /* ----- function prototypes end ----- */ #ifdef __cplusplus @@ -228,7 +332,7 @@ extern CTRY ctry; #if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment + #pragma pack() // Set default alignment. #undef _USING_BYTE_ALIGNMENT #endif diff --git a/mbglib/common/deviohlp.c b/mbglib/common/deviohlp.c index 5f557eb..caa324d 100644 --- a/mbglib/common/deviohlp.c +++ b/mbglib/common/deviohlp.c @@ -1,24 +1,30 @@ /************************************************************************** * - * $Id: deviohlp.c 1.7 2018/09/19 16:54:12Z martin REL_M $ + * $Id: deviohlp.c 1.9 2021/03/22 17:57:27Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * * Description: * Device configuration helper functions. This is an extension to - * mbgdevio.c providing useful functions to simplify reading/writing + * mbgdevio.c, providing useful functions to simplify reading/writing * complex device configuration structure sets. * * Warning: * These functions should not be implemented in a DLL / shared library * since the parameter sizes might vary with different versions - * of the API calls, which which would make different versions of + * of the API calls, which would make different versions of * precompiled libraries incompatible to each other. * * ----------------------------------------------------------------------- * $Log: deviohlp.c $ - * Revision 1.7 2018/09/19 16:54:12Z martin + * Revision 1.9 2021/03/22 17:57:27Z martin + * Updated a bunch of comments. + * Revision 1.8 2020/02/27 13:37:09 martin + * Use some feature check functions instead of macros. This obsoletes + * the PCPS_DEV pointers that are expected by some functions. + * Account for renamed library symbol. + * Revision 1.7 2018/09/19 16:54:12 martin * Account for renamed global variables. * Revision 1.6 2018/07/05 08:23:51Z martin * Account for a renamed function in cfg_hlp.c. @@ -58,15 +64,11 @@ MBG_PORT_HAS_9600 \ ) + #define DEFAULT_BAUD_RATES_DCF_HS \ ( \ - MBG_PORT_HAS_300 | \ - MBG_PORT_HAS_600 | \ - MBG_PORT_HAS_1200 | \ - MBG_PORT_HAS_2400 | \ - MBG_PORT_HAS_4800 | \ - MBG_PORT_HAS_9600 | \ - MBG_PORT_HAS_19200 | \ + DEFAULT_BAUD_RATES_DCF | \ + MBG_PORT_HAS_19200 | \ MBG_PORT_HAS_38400 \ ) @@ -114,7 +116,7 @@ int chk_feat_supp( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, MBG_CHK_SUPP_FNC *c } - cp = "Failed to check if supported"; //##++++ TODO:proper error msg + cp = "Failed to check if supported"; // TODO Pproper error msg. fail: if ( err_msg_fnc && cp ) @@ -129,7 +131,7 @@ out: /*HDR*/ /** - * @brief Read or setup all GNSS status information + * @brief Read or setup all GNSS status information. * * This function should be called preferably to get a summary of * the GNSS status from GNSS receivers (GPS, GLONASS, ...). @@ -137,20 +139,20 @@ out: * The function ::mbg_get_device_info must have been called before, and * the returned ::PCPS_DEV structure has to be passed to this function. * - * If the device supports this then the low level GNSS API functions + * If the device supports this, the low level GNSS API functions * are called directly to collect the status information. If the device - * doesn't support the GNSS API but is a pure GPS receiver then the GPS + * doesn't support the GNSS API but is a pure GPS receiver, the GPS * API functions are called and the GNSS data structures are filled up * accordingly, so the calling application can always evaluate the * GNSS data structures in ::ALL_GNSS_INFO. * - * If neither GPS nor another GNSS system is supported then this function + * If neither GPS nor another GNSS system is supported, this function * returns the ::MBG_ERR_NOT_SUPP_BY_DEV error. * - * @param[in] dh Valid handle to a Meinberg device - * @param[out] p_agi Pointer to a ::ALL_GNSS_INFO to be filled + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p_agi Pointer to an ::ALL_GNSS_INFO to be filled. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. * * @see ::mbg_get_gps_stat_info * @see ::mbg_get_gps_gnss_mode_info @@ -199,18 +201,18 @@ int mbg_chk_get_all_gnss_info( MBG_DEV_HANDLE dh, ALL_GNSS_INFO *p_agi ) goto out; - // If the the device supports the current API we can simply + // If the the device supports the current API, we can simply // retrieve status information for each individual GNSS system. rc = mbg_get_gps_all_gnss_sat_info( dh, p_agi->gnss_sat_info_idx, &p_agi->gnss_mode_info ); goto out; } - // If we get here then the device is a pure GPS receiver + // If we get here, the device is a pure GPS receiver // which neither supports additional GNSS systems nor the // associated data structures, so we set up all GNSS // data structures for GPS only. - rc = setup_gps_only_gnss_info_from_statinfo( p_agi ); + rc = setup_gps_only_gnss_mode_info_from_stat_info( p_agi ); out: return rc; @@ -221,28 +223,28 @@ out: /*HDR*/ /** - * @brief Read all serial port settings and supported configuration parameters + * @brief Read all serial port settings and supported configuration parameters. * * The functions ::mbg_get_device_info and ::mbg_setup_receiver_info * must have been called before, and the returned ::PCPS_DEV and * ::RECEIVER_INFO structures have to be passed to this function. * * The complementary function ::mbg_save_serial_settings should be used - * to write the modified serial port configuration back to the board. + * to write the modified serial port configuration back to the device. * - * @param[in] dh Valid handle to a Meinberg device - * @param[in] *p_dev Pointer to a valid ::PCPS_DEV structure - * @param[out] *p_rpcfg Pointer to a ::RECEIVER_PORT_CFG structure to be filled up - * @param[in] *p_ri Pointer to a valid ::RECEIVER_INFO structure + * @param[in] dh Valid handle to a Meinberg device. + * @param[in] p_obs Obsolete pointer kept for compatibility, should be @a NULL. + * @param[out] p_rpcfg Pointer to a ::RECEIVER_PORT_CFG structure to be filled up. + * @param[in] p_ri Pointer to a valid ::RECEIVER_INFO structure. * - * @return ::MBG_SUCCESS or error code returned by device I/O control function + * @return ::MBG_SUCCESS, or error code returned by device I/O control function. * * @see ::mbg_get_device_info * @see ::mbg_setup_receiver_info * @see ::mbg_save_serial_settings */ int mbg_get_serial_settings( MBG_DEV_HANDLE dh, - const PCPS_DEV *p_dev, + const void *p_obs, RECEIVER_PORT_CFG *p_rpcfg, const RECEIVER_INFO *p_ri ) { @@ -250,7 +252,7 @@ int mbg_get_serial_settings( MBG_DEV_HANDLE dh, memset( p_rpcfg, 0, sizeof( *p_rpcfg ) ); - if ( _pcps_has_receiver_info( p_dev ) ) + if ( mbg_rc_is_success( mbg_chk_dev_has_receiver_info( dh ) ) ) { // The device provides a RECEIVER_INFO, so we can simply read all // serial port configuration and supported string types directly. @@ -270,7 +272,7 @@ int mbg_get_serial_settings( MBG_DEV_HANDLE dh, // The device doesn't support a RECEIVER_INFO, so this is // an old GPS or non-GPS device. - if ( _pcps_is_gps( p_dev ) ) + if ( mbg_rc_is_success( mbg_chk_dev_is_gps( dh ) ) ) { // Read the serial port configuration from an old GPS device using // a legacy API call and set up current structures accordingly. @@ -290,8 +292,8 @@ int mbg_get_serial_settings( MBG_DEV_HANDLE dh, } else { - // Not all legacy non-GPS clocks have a serial port. - if ( _pcps_has_serial( p_dev ) ) + // Not all legacy non-GPS devices have an onbord serial port. + if ( mbg_rc_is_success( mbg_chk_dev_has_serial( dh ) ) ) { // Read the serial port configuration from an old non-GPS device using // a legacy API call and set up current structures accordingly. @@ -304,7 +306,7 @@ int mbg_get_serial_settings( MBG_DEV_HANDLE dh, goto out; port_info_from_pcps_serial( p_rpcfg->pii, ser_code, - _pcps_has_serial_hs( p_dev ) ? + mbg_rc_is_success( mbg_chk_dev_has_serial_hs( dh ) ) ? DEFAULT_BAUD_RATES_DCF_HS : DEFAULT_BAUD_RATES_DCF ); @@ -326,7 +328,7 @@ out: /*HDR*/ /** - * @brief Write the configuration settings for a single serial port to a device + * @brief Write the configuration settings for a single serial port to a device. * * Modifications to the serial port configuration should be made only * after ::mbg_get_serial_settings had been called to read all serial port @@ -337,12 +339,12 @@ out: * As also required by ::mbg_get_serial_settings, the functions * ::mbg_get_device_info and ::mbg_setup_receiver_info must have been * called before, and the returned ::PCPS_DEV and ::RECEIVER_INFO structures - * vave to be passed to this function. + * have to be passed to this function. * - * @param[in] dh Valid handle to a Meinberg device - * @param[in] *p_dev Pointer to a valid ::PCPS_DEV structure - * @param[in] *p_rpcfg Pointer to a valid ::RECEIVER_PORT_CFG structure - * @param[in] port_num Index of the serial port to be saved + * @param[in] dh Valid handle to a Meinberg device. + * @param[in] p_obs Obsolete pointer kept for compatibility, should be @a NULL. + * @param[in] p_rpcfg Pointer to a valid ::RECEIVER_PORT_CFG structure. + * @param[in] port_num Index of the serial port to be saved. * * @return ::MBG_SUCCESS or error code returned by device I/O control function. * @@ -350,12 +352,12 @@ out: * @see ::mbg_get_device_info * @see ::mbg_setup_receiver_info */ -int mbg_save_serial_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, +int mbg_save_serial_settings( MBG_DEV_HANDLE dh, const void *p_obs, RECEIVER_PORT_CFG *p_rpcfg, int port_num ) { int rc; - if ( _pcps_has_receiver_info( p_dev ) ) + if ( mbg_rc_is_success( mbg_chk_dev_has_receiver_info( dh ) ) ) { // The device provides a ::RECEIVER_INFO, so we can simply write // the configuration for the specified serial port directly. @@ -364,9 +366,9 @@ int mbg_save_serial_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, else { // This is a legacy device which doesn't provide a ::RECEIVER_INFO. - if ( _pcps_is_gps( p_dev ) ) + if ( mbg_rc_is_success( mbg_chk_dev_is_gps( dh ) ) ) { - // If the legacy device is a GPS receiver we have to set up + // If the legacy device is a GPS receiver, we have to set up // an appropriate ::PORT_PARM structure and write that one // to the device. port_parm_from_port_settings( &p_rpcfg->tmp_pp, port_num, @@ -376,7 +378,7 @@ int mbg_save_serial_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, } else { - // If the legacy device is not a GPS receiver we have + // If the legacy device is not a GPS receiver, we have // to set up a ::PCPS_SERIAL configuration byte and write // that one to the device. PCPS_SERIAL ser_code; @@ -395,22 +397,22 @@ int mbg_save_serial_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, /*HDR*/ /** - * @brief Read all network configuration into an ::ALL_NET_CFG_INFO structure + * @brief Read all network configuration into an ::ALL_NET_CFG_INFO structure. * * Reads the network configuration of a device via the LAN_IP4 API and * translates the structures into NET_CFG structures. * * As soon as available, this function should make use of the NET_CFG API. * - * A ::ALL_NET_CFG_INFO and the appropriate number of ::MBG_NET_INTF_LINK_INFO_IDX, + * An ::ALL_NET_CFG_INFO and the appropriate number of ::MBG_NET_INTF_LINK_INFO_IDX, * ::MBG_NET_INTF_ADDR_INFO_IDX, ::MBG_IP_ADDR_IDX, ::MBG_NET_NAME_IDX and * ::MBG_NET_INTF_ROUTE_INFO_IDX will be allocated and need to be freed later - * by calling ::free_all_net_cfg_info + * by calling ::free_all_net_cfg_info. * - * @param[in] dh Valid handle to a Meinberg device - * @param[out] p Pointer to a pointer of ::ALL_NET_CFG_INFO + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p Pointer to a pointer of ::ALL_NET_CFG_INFO. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. * * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info @@ -432,7 +434,7 @@ int mbg_get_all_net_cfg_info( MBG_DEV_HANDLE dh, ALL_NET_CFG_INFO **p ) } } - // TODO Use NET_CFG API as soon as its available for PCI/PCIe devices + // TODO Use NET_CFG API as soon as it's available for PCI/PCIe devices. rc = mbg_chk_dev_has_lan_intf( dh ); if ( mbg_rc_is_success( rc ) ) @@ -593,7 +595,7 @@ out: /*HDR*/ /** - * @brief Write all network settings to a device + * @brief Write all network settings to a device. * * The complementary function ::mbg_get_all_net_cfg_info should * have been used to read the original network settings and @@ -604,17 +606,17 @@ out: * * As soon as available, this function should make use of the NET_CFG API. * - * @param[in] dh Valid handle to a Meinberg device - * @param[in] p Pointer to a pointer of ::ALL_NET_CFG_INFO + * @param[in] dh Valid handle to a Meinberg device. + * @param[in] p Pointer to a pointer of ::ALL_NET_CFG_INFO. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. * * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_set_ip4_settings */ int mbg_save_all_net_cfg_info( MBG_DEV_HANDLE dh, ALL_NET_CFG_INFO *p ) { - // TODO: Use NET_CFG API as soon as its available for PCI/PCIe devices + // TODO Use NET_CFG API as soon as it's available for PCI/PCIe devices. int rc = mbg_chk_dev_has_lan_intf( dh ); if ( mbg_rc_is_success( rc ) ) @@ -651,22 +653,22 @@ int mbg_save_all_net_cfg_info( MBG_DEV_HANDLE dh, ALL_NET_CFG_INFO *p ) /*HDR*/ /** - * @brief Read current network status into an ::ALL_NET_STATUS_INFO structure + * @brief Read current network status into an ::ALL_NET_STATUS_INFO structure. * * Reads the network status of a device via the LAN_IP4 API and * translates the structures into NET_CFG structures. * * As soon as available, this function should make use of the NET_CFG API. * - * A ::ALL_NET_STATUS_INFO and the appropriate number of ::MBG_NET_INTF_LINK_INFO_IDX, + * An ::ALL_NET_STATUS_INFO and the appropriate number of ::MBG_NET_INTF_LINK_INFO_IDX, * ::MBG_NET_INTF_ADDR_INFO_IDX, ::MBG_IP_ADDR_IDX, ::MBG_NET_NAME_IDX and * ::MBG_NET_INTF_ROUTE_INFO_IDX will be allocated and need to be freed later - * by calling ::free_all_net_status_info + * by calling ::free_all_net_status_info. * - * @param[in] dh Valid handle to a Meinberg device - * @param[out] p Pointer to a pointer of ::ALL_NET_STATUS_INFO + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p Pointer to a pointer of ::ALL_NET_STATUS_INFO. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. * * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info @@ -688,7 +690,7 @@ int mbg_get_all_net_status_info( MBG_DEV_HANDLE dh, ALL_NET_STATUS_INFO **p ) } } - // TODO Use NET_CFG API as soon as its available for PCI/PCIe devices + // TODO Use NET_CFG API as soon as it's available for PCI/PCIe devices. rc = mbg_chk_dev_has_lan_intf( dh ); if ( mbg_rc_is_success( rc ) ) @@ -849,13 +851,13 @@ out: /*HDR*/ /** - * @brief Read all PTP settings and supported configuration parameters + * @brief Read all PTP settings and supported configuration parameters. * * The complementary function ::mbg_save_all_ptp_cfg_info should * be used to write the modified configuration back to the device. * - * @param[in] dh Valid handle to a Meinberg device - * @param[out] *p Pointer to a ::ALL_PTP_CFG_INFO structure to be filled up + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p Address of an ::ALL_PTP_CFG_INFO structure to be filled up. * * @return ::MBG_SUCCESS or error code returned by device I/O control function. * @@ -905,14 +907,14 @@ int mbg_get_all_ptp_cfg_info( MBG_DEV_HANDLE dh, ALL_PTP_CFG_INFO *p ) /*HDR*/ /** - * @brief Write all PTP settings to a device + * @brief Write all PTP settings to a device. * * The complementary function ::mbg_get_all_ptp_cfg_info should * have been used to read the original PTP settings and supported * configuration parameters. * - * @param[in] dh Valid handle to a Meinberg device - * @param[in] *p Pointer to a valid ::ALL_PTP_CFG_INFO structure + * @param[in] dh Valid handle to a Meinberg device. + * @param[in] p Pointer to a valid ::ALL_PTP_CFG_INFO structure. * * @return ::MBG_SUCCESS or error code returned by device I/O control function. * @@ -960,18 +962,18 @@ int mbg_save_all_ptp_cfg_info( MBG_DEV_HANDLE dh, const ALL_PTP_CFG_INFO *p ) /*HDR*/ /** - * @brief Read all XMR info into a newly or re-allocated ::ALL_XMULTI_REF_INFO + * @brief Read all XMR info into a newly or re-allocated ::ALL_XMULTI_REF_INFO. * - * @note ::mbg_chk_dev_has_xmr should be called before using this function + * @note ::mbg_chk_dev_has_xmr should be called before using this function. * - * A ::ALL_XMULTI_REF_INFO and a number of ::XMULTI_REF_INSTANCES::n_xmr_settings + * An ::ALL_XMULTI_REF_INFO and a number of ::XMULTI_REF_INSTANCES::n_xmr_settings * of ::XMULTI_REF_INFO_IDX and ::XMR_EXT_SRC_INFO_IDX will be allocated and needs - * to be freed by calling ::free_all_xmulti_ref_info + * to be freed by calling ::free_all_xmulti_ref_info. * - * @param[in] dh Valid handle to a Meinberg device - * @param[out] p Pointer to a pointer of ::ALL_XMULTI_REF_INFO + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p Pointer to a pointer of ::ALL_XMULTI_REF_INFO. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. * * @see ::free_all_xmulti_ref_info */ @@ -990,7 +992,7 @@ int mbg_get_all_xmulti_ref_info( MBG_DEV_HANDLE dh, ALL_XMULTI_REF_INFO **p ) } } - // First, get the XMULTI_REF_INSTANCES to check how many sources are supported + // First, get the XMULTI_REF_INSTANCES to check how many sources are supported. rc = mbg_get_xmr_instances( dh, &xmr_info->instances ); if ( mbg_rc_is_error( rc ) ) @@ -1013,11 +1015,11 @@ int mbg_get_all_xmulti_ref_info( MBG_DEV_HANDLE dh, ALL_XMULTI_REF_INFO **p ) if ( mbg_rc_is_success( chk_dev_xmulti_ref_supp_ext_src_info( xmr_info ) ) ) { - // TODO!!! - // XMR_EXT_SRC_INFO_IDX can not be read out from bus devices, yet - // Therefore, remove the feature bit from this card + // TODO + // XMR_EXT_SRC_INFO_IDX can not yet be read from bus devices. + // Therefore, remove the feature bit from this card. // Has to be changed as soon as low level functions are ready - // TODO!!! + // TODO xmr_info->instances.flags &= ~XMRIF_MSK_EXT_SRC_INFO_SUPP; } @@ -1035,17 +1037,18 @@ out: } // mbg_get_all_xmulti_ref_info + /*HDR*/ /** - * @brief Set all extended multi ref settings to a device + * @brief Write all extended multi ref settings to a device. * * The complementary function ::mbg_get_all_xmulti_ref_info should * have been used to read the original extended multi ref info. * - * @param[in] dh Valid handle to a Meinberg device - * @param[out] p Pointer to a ::ALL_XMULTI_REF_INFO structure with all settings + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p Pointer to an ::ALL_XMULTI_REF_INFO structure with all settings. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. * * @see ::mbg_set_gps_xmr_settings_idx */ @@ -1061,7 +1064,8 @@ _NO_MBG_API_ATTR int _MBG_API mbg_save_all_xmulti_ref_info( MBG_DEV_HANDLE dh, A rc = mbg_set_gps_xmr_settings_idx( dh, &settings ); } - // if all settings have been successully set, send dummy structure with index -1 to apply settings + // After all settings have been successully written, write + // a dummy structure with index -1 to apply settings. if( mbg_rc_is_success( rc ) ) { memset( &settings, 0, sizeof( settings ) ); @@ -1075,19 +1079,20 @@ _NO_MBG_API_ATTR int _MBG_API mbg_save_all_xmulti_ref_info( MBG_DEV_HANDLE dh, A } // mbg_save_all_xmulti_ref_info + /*HDR*/ /** - * @brief Read all XMR status info into a newly or re-allocated ::ALL_XMULTI_REF_STATUS + * @brief Read all XMR status info into a newly or re-allocated ::ALL_XMULTI_REF_STATUS. * - * @note ::mbg_chk_dev_has_xmr should be called before using this function + * @note ::mbg_chk_dev_has_xmr should be called before using this function. * - * A ::ALL_XMULTI_REF_STATUS and a number of ::XMULTI_REF_INSTANCES::n_xmr_settings + * An ::ALL_XMULTI_REF_STATUS and a number of ::XMULTI_REF_INSTANCES::n_xmr_settings * of ::XMULTI_REF_STATUS_IDX will be allocated and needs to be freed by calling - * ::free_all_xmulti_ref_status + * ::free_all_xmulti_ref_status. * - * @param[in] dh Valid handle to a Meinberg device - * @param[in] info Pointer to the appropriate info structure - * @param[out] p Pointer to a pointer of ::ALL_XMULTI_REF_STATUS + * @param[in] dh Valid handle to a Meinberg device. + * @param[in] info Pointer to the appropriate info structure. + * @param[out] p Pointer to a pointer of ::ALL_XMULTI_REF_STATUS. * * @return One of the @ref MBG_RETURN_CODES * @@ -1130,7 +1135,7 @@ int mbg_get_all_xmulti_ref_status( MBG_DEV_HANDLE dh, const ALL_XMULTI_REF_INFO if ( mbg_rc_is_success( chk_dev_xmulti_ref_supp_ext_src_info( info ) ) ) { // TODO - // XMR_EXT_SRC_INFO_IDX can not be read out from bus devices, yet + // XMR_EXT_SRC_INFO_IDX can not yet be read from bus level devices. } out: @@ -1150,7 +1155,7 @@ out: /*HDR*/ /** - * @brief Read all user capture information and store it into a newly allocated or reused ::ALL_UCAP_INFO + * @brief Read all user capture information and store it into a newly allocated or reused ::ALL_UCAP_INFO. * * @note ::mbg_chk_dev_has_ucap should be called to check if this API is supported. * @@ -1158,10 +1163,10 @@ out: * by calling ::free_all_ucap_info. Existing user captures will not be removed, so the * number of user captures can never decrease. * - * @param[in] dh Valid handle to a Meinberg device - * @param[out] p Pointer to a pointer to ::ALL_UCAP_INFO + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p Pointer to a pointer to ::ALL_UCAP_INFO. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. * * @see ::mbg_chk_dev_has_ucap * @see ::free_all_ucap_info @@ -1172,7 +1177,8 @@ int mbg_get_all_ucap_info( MBG_DEV_HANDLE dh, ALL_UCAP_INFO **p ) ALL_UCAP_INFO *ucap_info = *p; UCAP_ENTRY *new_entry, *old_entry; - // if this function is called for the first time, allocate a new ::ALL_UCAP_INFO structure + // If this function is called for the first time, + // allocate a new ::ALL_UCAP_INFO structure. if ( ucap_info == NULL ) { ucap_info = ( ALL_UCAP_INFO* )calloc( 1, sizeof( *ucap_info ) ); @@ -1437,7 +1443,7 @@ void test_xmr( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int verbose ) continue; } - // If execution gets here then the signal type is unknown. + // If execution gets here, the signal type is unknown. // Print a warning if the device supports instances of this signal type. if ( n_inst ) printf( "*** Warning: %u instances of unknown signal type idx %u supported!\n", @@ -1563,6 +1569,7 @@ void port_info_from_pcps_serial( } // port_info_from_pcps_serial + /*HDR*/ void pcps_serial_from_port_info( PCPS_SERIAL *p, @@ -1599,18 +1606,13 @@ void pcps_serial_from_port_info( -/*-------------------------------------------------------------- - * Name: pcps_unpack_serial() - * - * Purpose: Unpack a structure with serial port parameters - * - * Input/Output: p address of a structure holding both the - * packed and unpacked information - * - * Ret value: -- - *-------------------------------------------------------------*/ - /*HDR*/ +/** + * @brief Unpack a structure with serial port parameters. + * + * @param[in,out] p Address of a structure holding both the + * packed and unpacked information. + */ void pcps_unpack_serial( PCPS_SER_PACK *p ) { uint8_t pack = p->pack; @@ -1623,18 +1625,13 @@ void pcps_unpack_serial( PCPS_SER_PACK *p ) -/*-------------------------------------------------------------- - * Name: pcps_pack_serial() - * - * Purpose: Pack a structure with serial port parameters - * - * Input/Output: p address of a structure holding both the - * packed and unpacked information - * - * Ret value: -- - *-------------------------------------------------------------*/ - /*HDR*/ +/** + * @brief Pack a structure with serial port parameters. + * + * @param[in,out] p Address of a structure holding both the + * packed and unpacked information. + */ void pcps_pack_serial( PCPS_SER_PACK *p ) { p->pack = (uint8_t) ( ( p->baud & BITMASK( PCPS_BD_BITS ) ) @@ -1645,20 +1642,14 @@ void pcps_pack_serial( PCPS_SER_PACK *p ) -/*-------------------------------------------------------------- - * Name: pcps_str_to_port() - * - * Purpose: Try to convert a string to a valid port - * address. - * - * Input: s the string - * - * Output: -- - * - * Ret value: a valid port number or 0 - *+-------------------------------------------------------------*/ - /*HDR*/ +/** + * @brief Setup a list of ISA port addresses from a string. + * + * @param[in] s A string with port addresses, separated by comma. + * @param[out] port_vals An array of port addresses to be filled. + * @param[in] n_vals The max number of possible entries in @p port_vals. + */ void pcps_setup_isa_ports( char *s, int *port_vals, int n_vals ) diff --git a/mbglib/common/deviohlp.h b/mbglib/common/deviohlp.h index c5aa620..04b8cce 100644 --- a/mbglib/common/deviohlp.h +++ b/mbglib/common/deviohlp.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: deviohlp.h 1.4 2017/07/05 13:50:18Z martin REL_M $ + * $Id: deviohlp.h 1.6 2021/03/21 18:08:14Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,12 @@ * * ----------------------------------------------------------------------- * $Log: deviohlp.h $ - * Revision 1.4 2017/07/05 13:50:18Z martin + * Revision 1.6 2021/03/21 18:08:14Z martin + * Updated a bunch of comments. + * Revision 1.5 2020/02/27 13:40:00 martin + * Added some new inline functions. + * Updated function prototypes. + * Revision 1.4 2017/07/05 13:50:18 martin * Moved definition of PCPS_SER_PACK here. * Defined function type MBG_ERR_MSG_FNC. * New structure PCPS_TIME_EXT. @@ -54,19 +59,19 @@ extern "C" { /** - * @brief A helper structure used with configuration of old DCF77 clocks + * @brief A helper structure used with configuration of old DCF77 receivers. * * @deprecated This structure has been used with some very - * old DCF77 clocks to configure the serial interface. + * old DCF77 receivers to configure the serial interface. * It has been deprecated by ::PORT_SETTINGS and ::PORT_INFO. */ typedef struct { - PCPS_SERIAL pack; ///< This packed byte is read from or written to the board + PCPS_SERIAL pack; ///< This packed byte is read from or written to the device. - uint8_t baud; ///< The unpacked baud rate code, see ::PCPS_BD_CODES - uint8_t frame; ///< The unpacked framing code, see ::PCPS_FR_CODES - uint8_t mode; ///< The unpacked mode code, see ::PCPS_MOD_CODES + uint8_t baud; ///< The unpacked baud rate code, see ::PCPS_BD_CODES. + uint8_t frame; ///< The unpacked framing code, see ::PCPS_FR_CODES. + uint8_t mode; ///< The unpacked mode code, see ::PCPS_MOD_CODES. } PCPS_SER_PACK; @@ -98,25 +103,97 @@ typedef struct +static __mbg_inline /*HDR*/ +/** + * @brief Check if the day-of-week in a ::PCPS_TIME structure is in the valid range. + * + * For historical reasons, the valid range for ::PCPS_TIME::wday + * is 1 to 7, as transmitted by DCF77. See also ::PCPS_TIME::wday. + * + * @param[in] p The structure to be checked. + * + * @return @a true if day-of-week is valid, else @a false. + * + * @see ::pcps_date_time_is_valid + * @see ::pcps_date_time_wday_is_valid + */ +int pcps_wday_is_valid( const PCPS_TIME *p ) +{ + return ( p->wday >= 1 ) && ( p->wday <= 7 ); + +} // pcps_wday_is_valid + + + +static __mbg_inline /*HDR*/ /** * @brief Check if a ::PCPS_TIME structure contains valid date and time * - * @param[in] p The structure to be checked + * This function does ***not*** check if the day-of-week + * (::PCPS_TIME::wday) is in the valid range. + * Use ::pcps_date_time_wday_is_valid to check this, too, + * ::pcps_wday_is_valid to explicitly check the day-of-week. + * + * @param[in] p The structure to be checked + * + * @return @a true if date and time are valid, else @a false. * - * @return != 0 if date and time valid, else 0 + * @see ::pcps_date_time_wday_is_valid + * @see ::pcps_wday_is_valid */ -static __mbg_inline -int pcps_time_is_valid( const PCPS_TIME *p ) +bool pcps_date_time_is_valid( const PCPS_TIME *p ) { return ( p->sec100 <= 99 ) && ( p->sec <= 60 ) // allow for leap second && ( p->min <= 59 ) && ( p->hour <= 23 ) && ( p->mday >= 1 ) && ( p->mday <= 31 ) - && ( p->wday >= 1 ) && ( p->wday <= 7 ) && ( p->month >= 1 ) && ( p->month <= 12 ) && ( p->year <= 99 ); +} // pcps_date_time_is_valid + + + +static __mbg_inline /*HDR*/ +/** + * @brief Check if a ::PCPS_TIME structure contains valid date, time, and day-of-week. + * + * Unlike ::pcps_date_time_is_valid, this function also checks + * if the day-of-week (::PCPS_TIME::wday) is in the valid range. + * + * @param[in] p The structure to be checked + * + * @return @a true if date, time and day-of-week are valid, else @a false. + * + * @see ::pcps_date_time_is_valid + */ +int pcps_date_time_wday_is_valid( const PCPS_TIME *p ) +{ + return pcps_date_time_is_valid( p ) + && pcps_wday_is_valid( p ); + +} // pcps_date_time_wday_is_valid + + + +static __mbg_inline /*HDR*/ +/** + * @brief Check if a ::PCPS_TIME structure contains valid date, time, and day-of-week. + * + * Unlike ::pcps_date_time_is_valid, this function also checks + * if the day-of-week (::PCPS_TIME::wday) is in the valid range. + * + * @param[in] p The structure to be checked + * + * @return @a true if date, time and day-of-week are valid, else @a false. + * + * @see ::pcps_date_time_is_valid + */ +int _DEPRECATED_BY( "pcps_date_time_wday_is_valid" ) pcps_time_is_valid( const PCPS_TIME *p ) +{ + return pcps_date_time_wday_is_valid( p ); + } // pcps_time_is_valid @@ -128,7 +205,7 @@ int pcps_time_is_valid( const PCPS_TIME *p ) int chk_feat_supp( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, MBG_CHK_SUPP_FNC *chk_supp_fnc, MBG_ERR_MSG_FNC *err_msg_fnc, const char *not_supp_msg ) ; /** - * @brief Read or setup all GNSS status information + * @brief Read or setup all GNSS status information. * * This function should be called preferably to get a summary of * the GNSS status from GNSS receivers (GPS, GLONASS, ...). @@ -136,20 +213,20 @@ int pcps_time_is_valid( const PCPS_TIME *p ) * The function ::mbg_get_device_info must have been called before, and * the returned ::PCPS_DEV structure has to be passed to this function. * - * If the device supports this then the low level GNSS API functions + * If the device supports this, the low level GNSS API functions * are called directly to collect the status information. If the device - * doesn't support the GNSS API but is a pure GPS receiver then the GPS + * doesn't support the GNSS API but is a pure GPS receiver, the GPS * API functions are called and the GNSS data structures are filled up * accordingly, so the calling application can always evaluate the * GNSS data structures in ::ALL_GNSS_INFO. * - * If neither GPS nor another GNSS system is supported then this function + * If neither GPS nor another GNSS system is supported, this function * returns the ::MBG_ERR_NOT_SUPP_BY_DEV error. * - * @param[in] dh Valid handle to a Meinberg device - * @param[out] p_agi Pointer to a ::ALL_GNSS_INFO to be filled + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p_agi Pointer to an ::ALL_GNSS_INFO to be filled. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. * * @see ::mbg_get_gps_stat_info * @see ::mbg_get_gps_gnss_mode_info @@ -158,30 +235,30 @@ int pcps_time_is_valid( const PCPS_TIME *p ) int mbg_chk_get_all_gnss_info( MBG_DEV_HANDLE dh, ALL_GNSS_INFO *p_agi ) ; /** - * @brief Read all serial port settings and supported configuration parameters + * @brief Read all serial port settings and supported configuration parameters. * * The functions ::mbg_get_device_info and ::mbg_setup_receiver_info * must have been called before, and the returned ::PCPS_DEV and * ::RECEIVER_INFO structures have to be passed to this function. * * The complementary function ::mbg_save_serial_settings should be used - * to write the modified serial port configuration back to the board. + * to write the modified serial port configuration back to the device. * - * @param[in] dh Valid handle to a Meinberg device - * @param[in] *p_dev Pointer to a valid ::PCPS_DEV structure - * @param[out] *p_rpcfg Pointer to a ::RECEIVER_PORT_CFG structure to be filled up - * @param[in] *p_ri Pointer to a valid ::RECEIVER_INFO structure + * @param[in] dh Valid handle to a Meinberg device. + * @param[in] p_obs Obsolete pointer kept for compatibility, should be @a NULL. + * @param[out] p_rpcfg Pointer to a ::RECEIVER_PORT_CFG structure to be filled up. + * @param[in] p_ri Pointer to a valid ::RECEIVER_INFO structure. * - * @return ::MBG_SUCCESS or error code returned by device I/O control function + * @return ::MBG_SUCCESS, or error code returned by device I/O control function. * * @see ::mbg_get_device_info * @see ::mbg_setup_receiver_info * @see ::mbg_save_serial_settings */ - int mbg_get_serial_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, RECEIVER_PORT_CFG *p_rpcfg, const RECEIVER_INFO *p_ri ) ; + int mbg_get_serial_settings( MBG_DEV_HANDLE dh, const void *p_obs, RECEIVER_PORT_CFG *p_rpcfg, const RECEIVER_INFO *p_ri ) ; /** - * @brief Write the configuration settings for a single serial port to a device + * @brief Write the configuration settings for a single serial port to a device. * * Modifications to the serial port configuration should be made only * after ::mbg_get_serial_settings had been called to read all serial port @@ -192,12 +269,12 @@ int pcps_time_is_valid( const PCPS_TIME *p ) * As also required by ::mbg_get_serial_settings, the functions * ::mbg_get_device_info and ::mbg_setup_receiver_info must have been * called before, and the returned ::PCPS_DEV and ::RECEIVER_INFO structures - * vave to be passed to this function. + * have to be passed to this function. * - * @param[in] dh Valid handle to a Meinberg device - * @param[in] *p_dev Pointer to a valid ::PCPS_DEV structure - * @param[in] *p_rpcfg Pointer to a valid ::RECEIVER_PORT_CFG structure - * @param[in] port_num Index of the serial port to be saved + * @param[in] dh Valid handle to a Meinberg device. + * @param[in] p_obs Obsolete pointer kept for compatibility, should be @a NULL. + * @param[in] p_rpcfg Pointer to a valid ::RECEIVER_PORT_CFG structure. + * @param[in] port_num Index of the serial port to be saved. * * @return ::MBG_SUCCESS or error code returned by device I/O control function. * @@ -205,25 +282,25 @@ int pcps_time_is_valid( const PCPS_TIME *p ) * @see ::mbg_get_device_info * @see ::mbg_setup_receiver_info */ - int mbg_save_serial_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, RECEIVER_PORT_CFG *p_rpcfg, int port_num ) ; + int mbg_save_serial_settings( MBG_DEV_HANDLE dh, const void *p_obs, RECEIVER_PORT_CFG *p_rpcfg, int port_num ) ; /** - * @brief Read all network configuration into an ::ALL_NET_CFG_INFO structure + * @brief Read all network configuration into an ::ALL_NET_CFG_INFO structure. * * Reads the network configuration of a device via the LAN_IP4 API and * translates the structures into NET_CFG structures. * * As soon as available, this function should make use of the NET_CFG API. * - * A ::ALL_NET_CFG_INFO and the appropriate number of ::MBG_NET_INTF_LINK_INFO_IDX, + * An ::ALL_NET_CFG_INFO and the appropriate number of ::MBG_NET_INTF_LINK_INFO_IDX, * ::MBG_NET_INTF_ADDR_INFO_IDX, ::MBG_IP_ADDR_IDX, ::MBG_NET_NAME_IDX and * ::MBG_NET_INTF_ROUTE_INFO_IDX will be allocated and need to be freed later - * by calling ::free_all_net_cfg_info + * by calling ::free_all_net_cfg_info. * - * @param[in] dh Valid handle to a Meinberg device - * @param[out] p Pointer to a pointer of ::ALL_NET_CFG_INFO + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p Pointer to a pointer of ::ALL_NET_CFG_INFO. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. * * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info @@ -233,7 +310,7 @@ int pcps_time_is_valid( const PCPS_TIME *p ) int mbg_get_all_net_cfg_info( MBG_DEV_HANDLE dh, ALL_NET_CFG_INFO **p ) ; /** - * @brief Write all network settings to a device + * @brief Write all network settings to a device. * * The complementary function ::mbg_get_all_net_cfg_info should * have been used to read the original network settings and @@ -244,10 +321,10 @@ int pcps_time_is_valid( const PCPS_TIME *p ) * * As soon as available, this function should make use of the NET_CFG API. * - * @param[in] dh Valid handle to a Meinberg device - * @param[in] p Pointer to a pointer of ::ALL_NET_CFG_INFO + * @param[in] dh Valid handle to a Meinberg device. + * @param[in] p Pointer to a pointer of ::ALL_NET_CFG_INFO. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. * * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_set_ip4_settings @@ -255,22 +332,22 @@ int pcps_time_is_valid( const PCPS_TIME *p ) int mbg_save_all_net_cfg_info( MBG_DEV_HANDLE dh, ALL_NET_CFG_INFO *p ) ; /** - * @brief Read current network status into an ::ALL_NET_STATUS_INFO structure + * @brief Read current network status into an ::ALL_NET_STATUS_INFO structure. * * Reads the network status of a device via the LAN_IP4 API and * translates the structures into NET_CFG structures. * * As soon as available, this function should make use of the NET_CFG API. * - * A ::ALL_NET_STATUS_INFO and the appropriate number of ::MBG_NET_INTF_LINK_INFO_IDX, + * An ::ALL_NET_STATUS_INFO and the appropriate number of ::MBG_NET_INTF_LINK_INFO_IDX, * ::MBG_NET_INTF_ADDR_INFO_IDX, ::MBG_IP_ADDR_IDX, ::MBG_NET_NAME_IDX and * ::MBG_NET_INTF_ROUTE_INFO_IDX will be allocated and need to be freed later - * by calling ::free_all_net_status_info + * by calling ::free_all_net_status_info. * - * @param[in] dh Valid handle to a Meinberg device - * @param[out] p Pointer to a pointer of ::ALL_NET_STATUS_INFO + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p Pointer to a pointer of ::ALL_NET_STATUS_INFO. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. * * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info @@ -280,13 +357,13 @@ int pcps_time_is_valid( const PCPS_TIME *p ) int mbg_get_all_net_status_info( MBG_DEV_HANDLE dh, ALL_NET_STATUS_INFO **p ) ; /** - * @brief Read all PTP settings and supported configuration parameters + * @brief Read all PTP settings and supported configuration parameters. * * The complementary function ::mbg_save_all_ptp_cfg_info should * be used to write the modified configuration back to the device. * - * @param[in] dh Valid handle to a Meinberg device - * @param[out] *p Pointer to a ::ALL_PTP_CFG_INFO structure to be filled up + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p Address of an ::ALL_PTP_CFG_INFO structure to be filled up. * * @return ::MBG_SUCCESS or error code returned by device I/O control function. * @@ -300,14 +377,14 @@ int pcps_time_is_valid( const PCPS_TIME *p ) int mbg_get_all_ptp_cfg_info( MBG_DEV_HANDLE dh, ALL_PTP_CFG_INFO *p ) ; /** - * @brief Write all PTP settings to a device + * @brief Write all PTP settings to a device. * * The complementary function ::mbg_get_all_ptp_cfg_info should * have been used to read the original PTP settings and supported * configuration parameters. * - * @param[in] dh Valid handle to a Meinberg device - * @param[in] *p Pointer to a valid ::ALL_PTP_CFG_INFO structure + * @param[in] dh Valid handle to a Meinberg device. + * @param[in] p Pointer to a valid ::ALL_PTP_CFG_INFO structure. * * @return ::MBG_SUCCESS or error code returned by device I/O control function. * @@ -320,50 +397,50 @@ int pcps_time_is_valid( const PCPS_TIME *p ) int mbg_save_all_ptp_cfg_info( MBG_DEV_HANDLE dh, const ALL_PTP_CFG_INFO *p ) ; /** - * @brief Read all XMR info into a newly or re-allocated ::ALL_XMULTI_REF_INFO + * @brief Read all XMR info into a newly or re-allocated ::ALL_XMULTI_REF_INFO. * - * @note ::mbg_chk_dev_has_xmr should be called before using this function + * @note ::mbg_chk_dev_has_xmr should be called before using this function. * - * A ::ALL_XMULTI_REF_INFO and a number of ::XMULTI_REF_INSTANCES::n_xmr_settings + * An ::ALL_XMULTI_REF_INFO and a number of ::XMULTI_REF_INSTANCES::n_xmr_settings * of ::XMULTI_REF_INFO_IDX and ::XMR_EXT_SRC_INFO_IDX will be allocated and needs - * to be freed by calling ::free_all_xmulti_ref_info + * to be freed by calling ::free_all_xmulti_ref_info. * - * @param[in] dh Valid handle to a Meinberg device - * @param[out] p Pointer to a pointer of ::ALL_XMULTI_REF_INFO + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p Pointer to a pointer of ::ALL_XMULTI_REF_INFO. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. * * @see ::free_all_xmulti_ref_info */ int mbg_get_all_xmulti_ref_info( MBG_DEV_HANDLE dh, ALL_XMULTI_REF_INFO **p ) ; /** - * @brief Set all extended multi ref settings to a device + * @brief Write all extended multi ref settings to a device. * * The complementary function ::mbg_get_all_xmulti_ref_info should * have been used to read the original extended multi ref info. * - * @param[in] dh Valid handle to a Meinberg device - * @param[out] p Pointer to a ::ALL_XMULTI_REF_INFO structure with all settings + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p Pointer to an ::ALL_XMULTI_REF_INFO structure with all settings. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. * * @see ::mbg_set_gps_xmr_settings_idx */ _NO_MBG_API_ATTR int _MBG_API mbg_save_all_xmulti_ref_info( MBG_DEV_HANDLE dh, ALL_XMULTI_REF_INFO *p ) ; /** - * @brief Read all XMR status info into a newly or re-allocated ::ALL_XMULTI_REF_STATUS + * @brief Read all XMR status info into a newly or re-allocated ::ALL_XMULTI_REF_STATUS. * - * @note ::mbg_chk_dev_has_xmr should be called before using this function + * @note ::mbg_chk_dev_has_xmr should be called before using this function. * - * A ::ALL_XMULTI_REF_STATUS and a number of ::XMULTI_REF_INSTANCES::n_xmr_settings + * An ::ALL_XMULTI_REF_STATUS and a number of ::XMULTI_REF_INSTANCES::n_xmr_settings * of ::XMULTI_REF_STATUS_IDX will be allocated and needs to be freed by calling - * ::free_all_xmulti_ref_status + * ::free_all_xmulti_ref_status. * - * @param[in] dh Valid handle to a Meinberg device - * @param[in] info Pointer to the appropriate info structure - * @param[out] p Pointer to a pointer of ::ALL_XMULTI_REF_STATUS + * @param[in] dh Valid handle to a Meinberg device. + * @param[in] info Pointer to the appropriate info structure. + * @param[out] p Pointer to a pointer of ::ALL_XMULTI_REF_STATUS. * * @return One of the @ref MBG_RETURN_CODES * @@ -372,7 +449,7 @@ int pcps_time_is_valid( const PCPS_TIME *p ) int mbg_get_all_xmulti_ref_status( MBG_DEV_HANDLE dh, const ALL_XMULTI_REF_INFO *info, ALL_XMULTI_REF_STATUS **p ) ; /** - * @brief Read all user capture information and store it into a newly allocated or reused ::ALL_UCAP_INFO + * @brief Read all user capture information and store it into a newly allocated or reused ::ALL_UCAP_INFO. * * @note ::mbg_chk_dev_has_ucap should be called to check if this API is supported. * @@ -380,10 +457,10 @@ int pcps_time_is_valid( const PCPS_TIME *p ) * by calling ::free_all_ucap_info. Existing user captures will not be removed, so the * number of user captures can never decrease. * - * @param[in] dh Valid handle to a Meinberg device - * @param[out] p Pointer to a pointer to ::ALL_UCAP_INFO + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p Pointer to a pointer to ::ALL_UCAP_INFO. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. * * @see ::mbg_chk_dev_has_ucap * @see ::free_all_ucap_info @@ -394,9 +471,31 @@ int pcps_time_is_valid( const PCPS_TIME *p ) void test_xmr( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int verbose ) ; void port_info_from_pcps_serial( PORT_INFO_IDX *p_pii, PCPS_SERIAL pcps_serial, uint32_t supp_baud_rates ) ; void pcps_serial_from_port_info( PCPS_SERIAL *p, const PORT_INFO_IDX *p_pii ) ; + /** + * @brief Unpack a structure with serial port parameters. + * + * @param[in,out] p Address of a structure holding both the + * packed and unpacked information. + */ void pcps_unpack_serial( PCPS_SER_PACK *p ) ; + + /** + * @brief Pack a structure with serial port parameters. + * + * @param[in,out] p Address of a structure holding both the + * packed and unpacked information. + */ void pcps_pack_serial( PCPS_SER_PACK *p ) ; + + /** + * @brief Setup a list of ISA port addresses from a string. + * + * @param[in] s A string with port addresses, separated by comma. + * @param[out] port_vals An array of port addresses to be filled. + * @param[in] n_vals The max number of possible entries in @p port_vals. + */ void pcps_setup_isa_ports( char *s, int *port_vals, int n_vals ) ; + const char *setup_device_type_name( char *s, size_t max_len, MBG_DEV_HANDLE dh, const RECEIVER_INFO *p_ri ) ; const char *setup_asic_features( char *s, size_t max_len, MBG_DEV_HANDLE dh ) ; diff --git a/mbglib/common/gpsdefs.h b/mbglib/common/gpsdefs.h index 6444cf6..71d9043 100644 --- a/mbglib/common/gpsdefs.h +++ b/mbglib/common/gpsdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: gpsdefs.h 1.126 2018/07/05 10:18:34Z martin REL_M $ + * $Id: gpsdefs.h 1.127 2019/09/27 13:10:17Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -13,7 +13,37 @@ * * ----------------------------------------------------------------------- * $Log: gpsdefs.h $ - * Revision 1.126 2018/07/05 10:18:34Z martin + * Revision 1.127 2019/09/27 13:10:17Z martin + * New model codes MSHPS100, BPE_STM, VSI180, + * GNM181, RSCRDU_TTL, RSC2000, FCU200, REL1000_RC. + * Replaced old model CSM100 by MSSB100. + * Replaced old model USYNCPWR by CPC200. + * New PTP configuration structures. + * New PTP SMPTE stuff. + * Some extension of NTP configuration. + * XMR_QL_INFO was added to XMR API. + * Port types SPST and SPDT and some other IO stuff was added. + * New XBP device state 'outdated'. + * New MBG_EXT_SYS_STATUS stuff. + * New MBG_EVENTS stuff. + * New FCU stuff. + * New sysinfo definitions. + * New bit mask GNSS_SV_STAT_DUAL_FREQ_MSK. + * Updated some SyncE definitions. + * New string table initializers. + * New types GPS_WNUM, GPS_WSEC, and GPS_TICK. + * New types MBG_MSG_IDX and MBG_MSG_IDX_32. + * Struct names were added by thomas-b to support forward declarations. + * Added an enumeration MBG_DEV_CPU_TYPES and as well as an + * initializer MBG_DEV_CPU_TYPE_TABLE_INIT for a table indicating + * which CPU type is used on which hardware device. + * Renamed type TM_STATUS_EXT to TM_GPS_STATUS_EXT, which is + * more similar to the name TM_GPS_STATUS, but provided a #define + * to avoid build problems with existing code. + * Moved some structures here that were previously private. + * Moved definitions of ANN_LIMIT and ANN_LIMIT_DCF here. + * Lots of doxygen updates. + * Revision 1.126 2018/07/05 10:18:34 martin * New models GPS_MODEL_PIO180, GPS_MODEL_FCM180, GPS_MODEL_TCR180USB, * GPS_MODEL_SSP100, GPS_MODEL_GNS165, GPS_MODEL_RSC180RDMP, * GPS_MODEL_GPS16X, GPS_MODEL_MSHPS100. @@ -614,7 +644,6 @@ #ifndef _GPSDEFS_H #define _GPSDEFS_H - /* Other headers to be included */ #if defined( HAVE_CONFIG_H ) @@ -622,10 +651,10 @@ #include <config.h> #endif -// CLOCK_MEINBERG is defined in NTP's config.h if configured -// to support Meinberg clocks. +// CLOCK_MEINBERG is defined in the config.h file provided +// by the NTP project to support Meinberg clocks. #if !defined( CLOCK_MEINBERG ) - // avoid having to use these headers in non-Meinberg projects + // Avoid having to use these headers in non-Meinberg projects. #include <words.h> #include <use_pack.h> #endif @@ -647,8 +676,8 @@ /** * @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. + * @todo Check if ::MAX_SVNO_GLONASS is 94 instead of 95, and thus + * ::N_SVNO_GLONASS is 30 instead of 31, as reported by Wikipedia. */ enum GNSS_SVNOS { @@ -688,21 +717,31 @@ enum GNSS_SVNOS * model support the ::RECEIVER_INFO structure which contains * the actual value. */ - #define GPS_TICKS_PER_SEC DEFAULT_GPS_TICKS_PER_SEC ///< see ::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 an SV (Space Vehicle, i.e. satellite) -typedef uint16_t HEALTH; ///< an SV's 6 bit health code -typedef uint16_t CFG; ///< an SV's 4 bit 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; ///< The 6 bit health code for an SV. +typedef uint16_t CFG; ///< The 4 bit configuration code for an SV. +typedef uint16_t IOD; ///< Issue-Of-Data code. + +typedef int16_t GPS_WNUM; ///< Type of a signed extended GPS week number. +typedef int16_t GPS_DNUM; ///< Type of a signed GPS day number as used with ::UTC. +typedef int32_t GPS_WSEC; ///< Type of a signed GPS second-of-week number. +typedef int32_t GPS_TICK; ///< Type of a signed tick-of-second number, see + ///< ::GPS_TICKS_PER_SEC and ::RECEIVER_INFO::ticks_per_sec. + + +typedef uint16_t MBG_MSG_IDX; ///< Standard type of an index number used with binary messages. +typedef uint32_t MBG_MSG_IDX_32; ///< Type of a 32 bit index number used with binary messages in some cases. /* the type of various checksums */ #ifndef _CSUM_DEFINED - typedef uint16_t CSUM; ///< checksum used by some structures stored in non-volatile memory + typedef uint16_t CSUM; ///< Checksum used by some structures stored in non-volatile memory. #define _CSUM_DEFINED #endif @@ -766,6 +805,9 @@ do \ * the associated type of GPS data is not available. * * @see ::BVAR_FLAGS + * @see ::BVAR_FLAG_BITS + * @see ::BVAR_FLAG_NAMES + * @see ::BVAR_FLAG_NAMES_SHORT */ typedef uint16_t BVAR_STAT; @@ -785,15 +827,16 @@ typedef uint16_t BVAR_STAT; * @see ::BVAR_STAT * @see ::BVAR_FLAGS * @see ::BVAR_FLAG_NAMES + * @see ::BVAR_FLAG_NAMES_SHORT */ 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 + 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. }; @@ -805,25 +848,27 @@ enum BVAR_FLAG_BITS * @see ::BVAR_STAT * @see ::BVAR_FLAG_BITS * @see ::BVAR_FLAG_NAMES + * @see ::BVAR_FLAG_NAMES_SHORT */ enum BVAR_FLAGS { - 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 + 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_MASK ( ( 1UL << N_BVAR_BIT ) - 1 ) ///< Bit mask for all defined bits /** - * @brief String initializer for ::BVAR_STAT flag names + * @brief String initializer for long ::BVAR_STAT flag names. * - * @see ::BVAR_STAT + * @see ::BVAR_FLAG_NAMES_SHORT * @see ::BVAR_FLAG_BITS * @see ::BVAR_FLAGS + * @see ::BVAR_STAT */ #define BVAR_FLAG_NAMES \ { \ @@ -834,6 +879,25 @@ enum BVAR_FLAGS "Receiver position" \ } + + +/** + * @brief String initializer for short ::BVAR_STAT flag names. + * + * @see ::BVAR_FLAG_NAMES + * @see ::BVAR_FLAG_BITS + * @see ::BVAR_FLAGS + * @see ::BVAR_STAT + */ +#define BVAR_FLAG_NAMES_SHORT \ +{ \ + "CFGH", \ + "Alm.", \ + "UTC", \ + "IONO", \ + "Rcvr. pos." \ +} + /** @} defgroup group_bvar_stat */ @@ -870,7 +934,7 @@ typedef uint32_t RI_FEATURES; ///< see @ref GPS_FEATURE_MASKS * * @note This may not be supported by some very old devices. */ -typedef struct +typedef struct receiver_info_s { uint16_t model_code; ///< identifier for receiver model, see ::GPS_MODEL_CODES SW_REV sw_rev; ///< software revision and ID @@ -986,7 +1050,7 @@ enum GPS_MODEL_CODES GPS_MODEL_CMC_01, GPS_MODEL_SCU_01, GPS_MODEL_FCU_01, - GPS_MODEL_CSM100, + GPS_MODEL_MSSB100, GPS_MODEL_LNE180SFP, GPS_MODEL_GTS180, GPS_MODEL_GPS180CSM, @@ -999,7 +1063,8 @@ enum GPS_MODEL_CODES GPS_MODEL_GNS181_UC, GPS_MODEL_PSX_4GE, GPS_MODEL_RSC180RDU, - GPS_MODEL_USYNCPWR, + GPS_MODEL_CPC200, // FIXME Try if this works. This entry was originally defined as GPS_MODEL_USYNCPWR + // in 1.124.1.303, which was already obsolete right from the beginning. GPS_MODEL_FDM180M, GPS_MODEL_LSG180, // Line Signal Generator GPS_MODEL_GPS190, @@ -1011,7 +1076,14 @@ enum GPS_MODEL_CODES GPS_MODEL_GNS165, GPS_MODEL_RSC180RDMP, GPS_MODEL_GPS16X, // Some legacy GPS receiver - GPS_MODEL_MSHPS100, // microSYNC based on HPS100 hardware (but) as USB host + GPS_MODEL_MSHPS100, // microSync based on HPS100 hardware (but) as USB host + GPS_MODEL_BPE_STM, // BPE with STM M0 + GPS_MODEL_VSI180, + GPS_MODEL_GNM181, + GPS_MODEL_RSCRDU_TTL, // TTL version of ::GPS_MODEL_RSC180RDU + GPS_MODEL_RSC2000, // Variant of ::GPS_MODEL_RSC180 for LANTIME M2000 + GPS_MODEL_FCU200, // Fan (and power supply) Control Unit + GPS_MODEL_REL1000_RC, N_GPS_MODEL /* If new model codes are added then care must be taken * to update the associated string initializers GPS_MODEL_NAMES @@ -1112,7 +1184,7 @@ enum GPS_MODEL_CODES #define GPS_MODEL_NAME_CMC_01 "CMC_01" #define GPS_MODEL_NAME_SCU_01 "SCU_01" #define GPS_MODEL_NAME_FCU_01 "FCU_01" -#define GPS_MODEL_NAME_CSM100 "CSM100" +#define GPS_MODEL_NAME_MSSB100 "MSSB100" #define GPS_MODEL_NAME_LNE180SFP "LNE180SFP" #define GPS_MODEL_NAME_GTS180 "GTS180" #define GPS_MODEL_NAME_GPS180CSM "GPS180CSM" @@ -1125,7 +1197,7 @@ enum GPS_MODEL_CODES #define GPS_MODEL_NAME_GNS181_UC "GNS181_UC" #define GPS_MODEL_NAME_PSX_4GE "PSX_4GE" #define GPS_MODEL_NAME_RSC180RDU "RSC180RDU" -#define GPS_MODEL_NAME_USYNCPWR "MICROSYNC-PWR" +#define GPS_MODEL_NAME_CPC200 "CPC200" #define GPS_MODEL_NAME_FDM180M "FDM180M" #define GPS_MODEL_NAME_LSG180 "LSG180" #define GPS_MODEL_NAME_GPS190 "GPS190" @@ -1138,6 +1210,13 @@ enum GPS_MODEL_CODES #define GPS_MODEL_NAME_RSC180RDMP "RSC180RDMP" #define GPS_MODEL_NAME_GPS16X "GPS16x" #define GPS_MODEL_NAME_MSHPS100 "MSHPS100" +#define GPS_MODEL_NAME_BPE_STM "BPE" +#define GPS_MODEL_NAME_VSI180 "VSI180" +#define GPS_MODEL_NAME_GNM181 "GNM181" +#define GPS_MODEL_NAME_RSCRDU_TTL "RSC180RDU_TTL" +#define GPS_MODEL_NAME_RSC2000 "RSC2000" +#define GPS_MODEL_NAME_FCU200 "FCU200" +#define GPS_MODEL_NAME_REL1000_RC "REL1000_RC" /* * CARE MUST BE TAKEN that the name string of bus level devices * is limited to 9 characters. Longer strings will not fit into @@ -1237,7 +1316,7 @@ enum GPS_MODEL_CODES GPS_MODEL_NAME_CMC_01, \ GPS_MODEL_NAME_SCU_01, \ GPS_MODEL_NAME_FCU_01, \ - GPS_MODEL_NAME_CSM100, \ + GPS_MODEL_NAME_MSSB100, \ GPS_MODEL_NAME_LNE180SFP, \ GPS_MODEL_NAME_GTS180, \ GPS_MODEL_NAME_GPS180CSM, \ @@ -1250,7 +1329,7 @@ enum GPS_MODEL_CODES GPS_MODEL_NAME_GNS181_UC, \ GPS_MODEL_NAME_PSX_4GE, \ GPS_MODEL_NAME_RSC180RDU, \ - GPS_MODEL_NAME_USYNCPWR, \ + GPS_MODEL_NAME_CPC200, \ GPS_MODEL_NAME_FDM180M, \ GPS_MODEL_NAME_LSG180, \ GPS_MODEL_NAME_GPS190, \ @@ -1262,7 +1341,14 @@ enum GPS_MODEL_CODES GPS_MODEL_NAME_GNS165, \ GPS_MODEL_NAME_RSC180RDMP, \ GPS_MODEL_NAME_GPS16X, \ - GPS_MODEL_NAME_MSHPS100 \ + GPS_MODEL_NAME_MSHPS100, \ + GPS_MODEL_NAME_BPE_STM, \ + GPS_MODEL_NAME_VSI180, \ + GPS_MODEL_NAME_GNM181, \ + GPS_MODEL_NAME_RSCRDU_TTL, \ + GPS_MODEL_NAME_RSC2000, \ + GPS_MODEL_NAME_FCU200, \ + GPS_MODEL_NAME_REL1000_RC \ } @@ -1340,39 +1426,39 @@ enum 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_WWVB ( 1UL << GPS_BIT_MODEL_IS_WWVB ) ///< see ::GPS_BIT_MODEL_IS_WWVB - -#define GPS_MODEL_IS_BUS_LVL_DEV ( 1UL << GPS_BIT_MODEL_IS_BUS_LVL_DEV ) ///< see ::GPS_BIT_MODEL_IS_BUS_LVL_DEV -#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_TIME_TTM ( 1UL << GPS_BIT_MODEL_HAS_TIME_TTM ) ///< see ::GPS_BIT_MODEL_HAS_TIME_TTM -#define GPS_MODEL_HAS_TZDL ( 1UL << GPS_BIT_MODEL_HAS_TZDL ) ///< see ::GPS_BIT_MODEL_HAS_TZDL -#define GPS_MODEL_HAS_TZCODE ( 1UL << GPS_BIT_MODEL_HAS_TZCODE ) ///< see ::GPS_BIT_MODEL_HAS_TZCODE -#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_LEN ( 1UL << GPS_BIT_MODEL_HAS_ANT_CABLE_LEN ) ///< see ::GPS_BIT_MODEL_HAS_ANT_CABLE_LEN -#define GPS_MODEL_HAS_SCU_STAT ( 1UL << GPS_BIT_MODEL_HAS_SCU_STAT ) ///< see ::GPS_BIT_MODEL_HAS_SCU_STAT -#define GPS_MODEL_HAS_SV_INFO ( 1UL << GPS_BIT_MODEL_HAS_SV_INFO ) ///< see ::GPS_BIT_MODEL_HAS_SV_INFO -#define GPS_MODEL_HAS_UP_CONV ( 1UL << GPS_BIT_MODEL_HAS_UP_CONV ) ///< see ::GPS_BIT_MODEL_HAS_UP_CONV -#define GPS_MODEL_HAS_MBG_OS ( 1UL << GPS_BIT_MODEL_HAS_MBG_OS ) ///< see ::GPS_BIT_MODEL_HAS_MBG_OS +#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_WWVB ( 1UL << GPS_BIT_MODEL_IS_WWVB ) ///< See ::GPS_BIT_MODEL_IS_WWVB + +#define GPS_MODEL_IS_BUS_LVL_DEV ( 1UL << GPS_BIT_MODEL_IS_BUS_LVL_DEV ) ///< See ::GPS_BIT_MODEL_IS_BUS_LVL_DEV +#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_TIME_TTM ( 1UL << GPS_BIT_MODEL_HAS_TIME_TTM ) ///< See ::GPS_BIT_MODEL_HAS_TIME_TTM +#define GPS_MODEL_HAS_TZDL ( 1UL << GPS_BIT_MODEL_HAS_TZDL ) ///< See ::GPS_BIT_MODEL_HAS_TZDL +#define GPS_MODEL_HAS_TZCODE ( 1UL << GPS_BIT_MODEL_HAS_TZCODE ) ///< See ::GPS_BIT_MODEL_HAS_TZCODE +#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_LEN ( 1UL << GPS_BIT_MODEL_HAS_ANT_CABLE_LEN ) ///< See ::GPS_BIT_MODEL_HAS_ANT_CABLE_LEN +#define GPS_MODEL_HAS_SCU_STAT ( 1UL << GPS_BIT_MODEL_HAS_SCU_STAT ) ///< See ::GPS_BIT_MODEL_HAS_SCU_STAT +#define GPS_MODEL_HAS_SV_INFO ( 1UL << GPS_BIT_MODEL_HAS_SV_INFO ) ///< See ::GPS_BIT_MODEL_HAS_SV_INFO +#define GPS_MODEL_HAS_UP_CONV ( 1UL << GPS_BIT_MODEL_HAS_UP_CONV ) ///< See ::GPS_BIT_MODEL_HAS_UP_CONV +#define GPS_MODEL_HAS_MBG_OS ( 1UL << GPS_BIT_MODEL_HAS_MBG_OS ) ///< See ::GPS_BIT_MODEL_HAS_MBG_OS #if 0 // ### TODO This has to be discussed - #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_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 #endif // ### TODO FIXME do we need the next one? Should be obsolete -// #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_XMR_HOLDOVER_INTV ( 1UL << GPS_BIT_MODEL_HAS_XMR_HOLDOVER_INTV ) ///< See ::GPS_BIT_MODEL_HAS_XMR_HOLDOVER_INTV //### TODO: should we use an extra flag? #define GPS_MODEL_HAS_POS ( GPS_MODEL_HAS_POS_XYZ | GPS_MODEL_HAS_POS_LLA ) @@ -1742,7 +1828,7 @@ enum GPS_BUILTIN_FEATURE_BITS #define BUILTIN_FEAT_GPS162 ( BUILTIN_FEAT_GPS ) #define BUILTIN_FEAT_PTP270PEX ( GPS_MODEL_IS_BUS_LVL_DEV ) #define BUILTIN_FEAT_FRC511PEX ( GPS_MODEL_IS_BUS_LVL_DEV ) -#define BUILTIN_FEAT_GEN170 ( 0 ) +#define BUILTIN_FEAT_GEN170 ( GPS_MODEL_HAS_TIME_TTM ) #define BUILTIN_FEAT_TCR170PEX ( BUILTIN_FEAT_TCR_2_BUS_LVL ) #define BUILTIN_FEAT_WWVB511 ( BUILTIN_FEAT_WVB_1 ) #define BUILTIN_FEAT_MGR170 ( 0 ) @@ -1794,7 +1880,7 @@ enum GPS_BUILTIN_FEATURE_BITS #define BUILTIN_FEAT_CMC_01 ( 0 ) #define BUILTIN_FEAT_SCU_01 ( 0 ) #define BUILTIN_FEAT_FCU_01 ( 0 ) -#define BUILTIN_FEAT_CSM100 ( GPS_MODEL_HAS_MBG_OS ) +#define BUILTIN_FEAT_MSSB100 ( GPS_MODEL_HAS_MBG_OS ) #define BUILTIN_FEAT_LNE180SFP ( 0 ) #define BUILTIN_FEAT_GTS180 ( 0 ) #define BUILTIN_FEAT_GPS180CSM ( BUILTIN_FEAT_GPS ) @@ -1807,7 +1893,7 @@ enum GPS_BUILTIN_FEATURE_BITS #define BUILTIN_FEAT_GNS181_UC ( BUILTIN_FEAT_GNSS | GPS_MODEL_HAS_UP_CONV ) #define BUILTIN_FEAT_PSX_4GE ( GPS_MODEL_HAS_MBG_OS ) #define BUILTIN_FEAT_RSC180RDU ( GPS_MODEL_HAS_SCU_STAT ) -#define BUILTIN_FEAT_USYNCPWR ( 0 ) +#define BUILTIN_FEAT_CPC200 ( 0 ) #define BUILTIN_FEAT_FDM180M ( GPS_MODEL_HAS_TZDL | GPS_MODEL_HAS_ENABLE_FLAGS ) #define BUILTIN_FEAT_LSG180 ( 0 ) #define BUILTIN_FEAT_GPS190 ( BUILTIN_FEAT_GPS ) @@ -1820,6 +1906,13 @@ enum GPS_BUILTIN_FEATURE_BITS #define BUILTIN_FEAT_RSC180RDMP ( GPS_MODEL_HAS_SCU_STAT ) #define BUILTIN_FEAT_GPS16X ( BUILTIN_FEAT_GPS ) #define BUILTIN_FEAT_MSHPS100 ( GPS_MODEL_HAS_MBG_OS ) +#define BUILTIN_FEAT_BPE_STM ( 0 ) +#define BUILTIN_FEAT_VSI180 ( 0 ) +#define BUILTIN_FEAT_GNM181 ( BUILTIN_FEAT_GNSS ) +#define BUILTIN_FEAT_RSCRDU_TTL ( GPS_MODEL_HAS_SCU_STAT ) +#define BUILTIN_FEAT_RSC2000 ( GPS_MODEL_HAS_SCU_STAT ) +#define BUILTIN_FEAT_FCU200 ( 0 ) +#define BUILTIN_FEAT_REL1000_RC ( BUILTIN_FEAT_REL1000 ) /** * @brief Feature mask used for legacy devices @@ -1921,7 +2014,7 @@ enum GPS_BUILTIN_FEATURE_BITS { GPS_MODEL_CMC_01, BUILTIN_FEAT_CMC_01 }, \ { GPS_MODEL_SCU_01, BUILTIN_FEAT_SCU_01 }, \ { GPS_MODEL_FCU_01, BUILTIN_FEAT_FCU_01 }, \ - { GPS_MODEL_CSM100, BUILTIN_FEAT_CSM100 }, \ + { GPS_MODEL_MSSB100, BUILTIN_FEAT_MSSB100 }, \ { GPS_MODEL_LNE180SFP, BUILTIN_FEAT_LNE180SFP }, \ { GPS_MODEL_GTS180, BUILTIN_FEAT_GTS180 }, \ { GPS_MODEL_GPS180CSM, BUILTIN_FEAT_GPS180CSM }, \ @@ -1934,7 +2027,7 @@ enum GPS_BUILTIN_FEATURE_BITS { GPS_MODEL_GNS181_UC, BUILTIN_FEAT_GNS181_UC }, \ { GPS_MODEL_PSX_4GE, BUILTIN_FEAT_PSX_4GE }, \ { GPS_MODEL_RSC180RDU, BUILTIN_FEAT_RSC180RDU }, \ - { GPS_MODEL_USYNCPWR, BUILTIN_FEAT_USYNCPWR }, \ + { GPS_MODEL_CPC200, BUILTIN_FEAT_CPC200 }, \ { GPS_MODEL_FDM180M, BUILTIN_FEAT_FDM180M }, \ { GPS_MODEL_LSG180, BUILTIN_FEAT_LSG180 }, \ { GPS_MODEL_GPS190, BUILTIN_FEAT_GPS190 }, \ @@ -1947,9 +2040,219 @@ enum GPS_BUILTIN_FEATURE_BITS { GPS_MODEL_RSC180RDMP, BUILTIN_FEAT_RSC180RDMP }, \ { GPS_MODEL_GPS16X, BUILTIN_FEAT_GPS16X }, \ { GPS_MODEL_MSHPS100, BUILTIN_FEAT_MSHPS100 }, \ + { GPS_MODEL_BPE_STM, BUILTIN_FEAT_BPE_STM }, \ + { GPS_MODEL_VSI180, BUILTIN_FEAT_VSI180 }, \ + { GPS_MODEL_GNM181, BUILTIN_FEAT_GNM181 }, \ + { GPS_MODEL_RSCRDU_TTL, BUILTIN_FEAT_RSCRDU_TTL }, \ + { GPS_MODEL_RSC2000, BUILTIN_FEAT_RSC2000 }, \ + { GPS_MODEL_FCU200, BUILTIN_FEAT_FCU200 }, \ + { GPS_MODEL_REL1000_RC, BUILTIN_FEAT_REL1000_RC }, \ { 0, 0 } \ } + + +/** + * @brief Enumeration of CPU types used in Meinberg products. + * + * @see @ref group_dev_cpu_type_names + * @see ::MBG_DEV_CPU_TYPE_NAMES + */ +enum MBG_DEV_CPU_TYPES +{ + MBG_DEV_CPU_TYPE_UNSPEC, ///< Unspecified, unknown, or special (e.g. embedded system) + MBG_DEV_CPU_TYPE_C509, + MBG_DEV_CPU_TYPE_C166_C167, + MBG_DEV_CPU_TYPE_C163, + MBG_DEV_CPU_TYPE_GP4020, + MBG_DEV_CPU_TYPE_XC164_XC167, + MBG_DEV_CPU_TYPE_T89C5XACX, + MBG_DEV_CPU_TYPE_XE167, + MBG_DEV_CPU_TYPE_SAM3U, + MBG_DEV_CPU_TYPE_SAM3S, + MBG_DEV_CPU_TYPE_STM32F0, + MBG_DEV_CPU_TYPE_STM32F4, + MBG_DEV_CPU_TYPE_STM32F7, + N_MBG_DEV_CPU_TYPES +}; + + + +/** + * @defgroup group_dev_cpu_type_names Name strings of CPU types used with Meinberg devices. + * + * Name strings for the CPU types enumerated in ::MBG_DEV_CPU_TYPES. + * + * @see ::MBG_DEV_CPU_TYPES + * @see ::MBG_DEV_CPU_TYPE_NAMES + * + * @{ */ + +#define MBG_DEV_CPU_NAME_UNSPEC "(unspecified)" +#define MBG_DEV_CPU_NAME_C509 "C509" +#define MBG_DEV_CPU_NAME_C166_C167 "C166/C167" +#define MBG_DEV_CPU_NAME_C163 "C163" +#define MBG_DEV_CPU_NAME_GP4020 "GP4020" +#define MBG_DEV_CPU_NAME_XC164_XC167 "XC164/XC167" +#define MBG_DEV_CPU_NAME_T89C5XACX "T89C5xACx" +#define MBG_DEV_CPU_NAME_XE167 "XE167" +#define MBG_DEV_CPU_NAME_SAM3U "SAM3U" +#define MBG_DEV_CPU_NAME_SAM3S "SAM3S" +#define MBG_DEV_CPU_NAME_STM32F0 "STM32F0" +#define MBG_DEV_CPU_NAME_STM32F4 "STM32F4" +#define MBG_DEV_CPU_NAME_STM32F7 "STM32F7" + +/** @} defgroup group_dev_cpu_type_names */ + + + +/** + * @brief Initializer for an array of CPU type name strings + * + * The array should have ::N_MBG_DEV_CPU_TYPES entries. + * + * @see ::MBG_DEV_CPU_TYPES + * @see @ref MBG_DEV_CPU_TYPE_NAMES + */ +#define MBG_DEV_CPU_TYPE_NAMES \ +{ \ + MBG_DEV_CPU_NAME_UNSPEC, \ + MBG_DEV_CPU_NAME_C509, \ + MBG_DEV_CPU_NAME_C166_C167, \ + MBG_DEV_CPU_NAME_C163, \ + MBG_DEV_CPU_NAME_GP4020, \ + MBG_DEV_CPU_NAME_XC164_XC167, \ + MBG_DEV_CPU_NAME_T89C5XACX, \ + MBG_DEV_CPU_NAME_XE167, \ + MBG_DEV_CPU_NAME_SAM3U, \ + MBG_DEV_CPU_NAME_SAM3S, \ + MBG_DEV_CPU_NAME_STM32F0 \ + MBG_DEV_CPU_NAME_STM32F4 \ + MBG_DEV_CPU_NAME_STM32F7 \ +} + + + +/** + * @brief Initializer for a table of CPU type per device. + * + * Last entry is all zero to indicated end of table. + * + * @see ::GPS_MODEL_CODES + * @see ::MBG_DEV_CPU_TYPES + */ +#define MBG_DEV_CPU_TYPE_TABLE_INIT \ +{ \ + { GPS_MODEL_GPS166, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_GPS167, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_GPS167SV, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_GPS167PC, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_GPS167PCI, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_GPS163, MBG_DEV_CPU_TYPE_C163 }, \ + { GPS_MODEL_GPS168PCI, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_GPS161, MBG_DEV_CPU_TYPE_GP4020 }, \ + { GPS_MODEL_GPS169PCI, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_TCR167PCI, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_GPS164, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_GPS170PCI, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_PZF511, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_GPS170, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_TCR511, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_AM511, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_MSF511, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_GRC170, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_GPS170PEX, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_GPS162, MBG_DEV_CPU_TYPE_XE167 }, \ + { GPS_MODEL_PTP270PEX, 0 /* Toradex */ }, \ + { GPS_MODEL_FRC511PEX, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_GEN170, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_TCR170PEX, MBG_DEV_CPU_TYPE_XE167 }, \ + { GPS_MODEL_WWVB511, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_MGR170, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_JJY511, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_PZF600, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_TCR600, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GPS180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GLN170, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_GPS180PEX, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_TCR180PEX, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_PZF180PEX, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_MGR180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_MSF600, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_WWVB600, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_JJY600, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GPS180HS, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GPS180AMC, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_ESI180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_CPE180, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_LNO180, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_GRC180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_LIU, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_DCF600HS, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_DCF600RS, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_MRI, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_BPE, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_GLN180PEX, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_N2X, MBG_DEV_CPU_TYPE_STM32F4 }, \ + { GPS_MODEL_RSC180, MBG_DEV_CPU_TYPE_STM32F4 }, \ + { GPS_MODEL_LNE_GB, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_PPG180, MBG_DEV_CPU_TYPE_STM32F4 }, \ + { GPS_MODEL_SCG, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_MDU300, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_SDI, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_FDM180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_SPT, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_PZF180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_REL1000, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_HPS100, 0 }, \ + { GPS_MODEL_VSG180, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_MSF180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_WWVB180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_CPC180, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_CTC100, 0 }, \ + { GPS_MODEL_TCR180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_LUE180, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_CPC_01, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_TSU_01, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_CMC_01, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_SCU_01, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_FCU_01, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_MSSB100, 0 }, \ + { GPS_MODEL_LNE180SFP, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_GTS180, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_GPS180CSM, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GRC181, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_N2X180, MBG_DEV_CPU_TYPE_STM32F4 }, \ + { GPS_MODEL_GNS181PEX, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_MDU180, MBG_DEV_CPU_TYPE_STM32F4 }, \ + { GPS_MODEL_MDU312, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_GPS165, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GNS181_UC, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_PSX_4GE, 0 }, \ + { GPS_MODEL_RSC180RDU, MBG_DEV_CPU_TYPE_STM32F4 }, \ + { GPS_MODEL_CPC200, MBG_DEV_CPU_TYPE_STM32F0 }, \ + { GPS_MODEL_FDM180M, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_LSG180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GPS190, MBG_DEV_CPU_TYPE_STM32F7 }, \ + { GPS_MODEL_GNS181, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_PIO180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_FCM180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_TCR180USB, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_SSP100, 0 }, \ + { GPS_MODEL_GNS165, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_RSC180RDMP, MBG_DEV_CPU_TYPE_STM32F4 }, \ + { GPS_MODEL_GPS16X, MBG_DEV_CPU_TYPE_UNSPEC }, \ + { GPS_MODEL_MSHPS100, 0 }, \ + { GPS_MODEL_BPE_STM, MBG_DEV_CPU_TYPE_STM32F0 }, \ + { GPS_MODEL_VSI180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GNM181, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_RSCRDU_TTL, 0 }, \ + { GPS_MODEL_RSC2000, 0 }, \ + { GPS_MODEL_FCU200, 0 }, \ + { GPS_MODEL_REL1000_RC, 0 }, \ + { 0, 0 } \ +} + #endif // !defined( MBG_TGT_DOS ) /** @} anchor GPS_BUILTIN_FEATURE_DEFS */ @@ -2271,41 +2574,41 @@ enum 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 -#define GPS_HAS_XBP ( 1UL << GPS_FEAT_XBP ) ///< see ::GPS_FEAT_XBP -#define GPS_HAS_XFEATURE ( 1UL << GPS_FEAT_XFEATURE ) ///< see ::GPS_FEAT_XFEATURE +#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 +#define GPS_HAS_XBP ( 1UL << GPS_FEAT_XBP ) ///< See ::GPS_FEAT_XBP +#define GPS_HAS_XFEATURE ( 1UL << GPS_FEAT_XFEATURE ) ///< See ::GPS_FEAT_XFEATURE // 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 @@ -2352,7 +2655,7 @@ enum MBG_XFEATURE_BITS MBG_XFEATURE_REBOOT, ///< Supports the ::GPS_REBOOT command MBG_XFEATURE_CLK_RES_INFO, ///< Supports the ::GPS_CLK_RES_INFO command, see @ref group_clk_res_info MBG_XFEATURE_UCAP_NET, ///< Supports the ::GPS_UCAP_NET_GLB_INFO and ::GPS_UCAP_NET_RECV_INFO_IDX commands, see @ref group_ucap_net - MBG_XFEATURE_REQ_TTM, ///< Supports TTM requests via GPS_TIME command + MBG_XFEATURE_REQ_TTM, ///< Supports requesting ::TTM via the ::GPS_TIME command MBG_XFEATURE_IO_PORTS, ///< Supports I/O port structures, see @ref group_io_ports MBG_XFEATURE_MONITORING, ///< Supports monitoring / notifications, see @ref group_monitoring MBG_XFEATURE_XHE, ///< Supports XHE external rubidium unit I/O commands @@ -2366,6 +2669,9 @@ enum MBG_XFEATURE_BITS MBG_XFEATURE_DAC_CTRL_PCI, ///< Supports DAC control via PCI or USB bus API. MBG_XFEATURE_DATABASE, ///< Supports database(s), see @ref group_database MBG_XFEATURE_GNSS_MODE, ///< Supports GPS_GNSS_MODE + MBG_XFEATURE_PTP_NG, ///< Supports PTP next gen API, see @ref group_ptp_ng + MBG_XFEATURE_SYS_REF, ///< Supports new system reference API, see @ref group_sys_ref + MBG_XFEATURE_FCU_API, ///< Supports FCU features, see @ref group_fcu_api N_MBG_XFEATURE ///< Number of defined extended features // NOTE If new features are appended here then an appropriate feature // name string has to be appended to ::MBG_XFEATURE_NAMES, and care must @@ -2407,7 +2713,9 @@ enum MBG_XFEATURE_BITS "Firmware Management", \ "DAC control via bus", \ "Database", \ - "GNSS Messages" \ + "GNSS Messages", \ + "PTP Next Gen.", \ + "System Reference" \ } @@ -2435,7 +2743,7 @@ enum MBG_XFEATURE_BITS * @see ::_set_xfeature_bit * @see ::check_xfeature */ -typedef struct +typedef struct mbg_xfeature_buffer_s { uint8_t b[MAX_XFEATURE_BYTES]; @@ -2490,9 +2798,9 @@ enum RECEIVER_INFO_FLAG_BITS */ 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 + 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 }; @@ -2552,7 +2860,7 @@ typedef struct * 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 + * simply continue counting weeks beyond the 1024-week limit to maintain * the receiver's internal time. * * %UTC time differs from GPS time since a number of leap seconds have @@ -2562,9 +2870,9 @@ typedef struct */ typedef struct { - uint16_t wn; ///< the week number since the GPS system has been put into operation - uint32_t sec; ///< the second of that week - uint32_t tick; ///< fractions of a second, 1/::RECEIVER_INFO::ticks_per_sec units + GPS_WNUM wn; ///< The week number since the GPS system has been put into operation. + GPS_WSEC sec; ///< The second of a week. + GPS_TICK tick; ///< Fractions of a second, 1/::RECEIVER_INFO::ticks_per_sec units. } T_GPS; @@ -2577,6 +2885,39 @@ do \ } while ( 0 ) + +/** + * @brief A type of status variable to be used with ::TM_GPS, etc. + * + * @see ::TM_GPS_STATUS_BIT_MASKS + */ +typedef uint16_t TM_GPS_STATUS; + +#define _mbg_swab_tm_gps_status( _p ) _mbg_swab16( _p ) + + + + +/** + * @brief Type of an extended TM status which is mainly used inside the firmware. + * + * @see ::TM_GPS_STATUS_BIT_MASKS + * @see @ref TM_GPS_STATUS_EXT_BIT_MASKS + */ +typedef uint32_t TM_GPS_STATUS_EXT; + +#define _mbg_swab_tm_gps_status_ext( _p ) _mbg_swab32( _p ) + + +/** + * @brief An alias for ::TM_GPS_STATUS_EXT + * + * This has been used in existing source code. + */ +#define TM_STATUS_EXT TM_GPS_STATUS_EXT + + + /** * @brief Local date and time computed from GPS time * @@ -2602,18 +2943,18 @@ typedef struct 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 offset from %UTC [sec] - uint16_t status; ///< status flags, see ::TM_GPS_STATUS_BIT_MASKS + TM_GPS_STATUS status; ///< status flags, see ::TM_GPS_STATUS_BIT_MASKS } TM_GPS; -#define _mbg_swab_tm_gps( _p ) \ -do \ -{ \ - _mbg_swab16( &(_p)->year ); \ - _mbg_swab16( &(_p)->yday ); \ - _mbg_swab32( &(_p)->frac ); \ - _mbg_swab32( &(_p)->offs_from_utc ); \ - _mbg_swab16( &(_p)->status ); \ +#define _mbg_swab_tm_gps( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->year ); \ + _mbg_swab16( &(_p)->yday ); \ + _mbg_swab32( &(_p)->frac ); \ + _mbg_swab32( &(_p)->offs_from_utc ); \ + _mbg_swab_tm_gps_status( &(_p)->status ); \ } while ( 0 ) @@ -2657,51 +2998,68 @@ enum 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_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 + 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 }; /** - * @brief Type of an extended TM status which is mainly used inside the firmware - */ -typedef uint32_t TM_STATUS_EXT; - -/** - * @brief Enumeration of extended status bits used with ::TM_STATUS_EXT + * @brief Extended status flag bits used to define @ref TM_GPS_STATUS_EXT_BIT_MASKS * * @note The lower 16 bits correspond to ::TM_GPS_STATUS_BITS + * + * @see ::TM_GPS_STATUS_BITS + * @see @ref TM_GPS_STATUS_EXT_BIT_MASKS */ -enum TM_GPS_STATUS_BITS_EX +enum TM_GPS_STATUS_EXT_BITS { 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 remaining bits are reserved. }; -// 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 ) + +/** + * @brief Bit masks to be only used with ::TM_GPS_STATUS_EXT. + * + * @note The lower 16 bits correspond to ::TM_GPS_STATUS_BIT_MASKS + * + * @see ::TM_GPS_STATUS_EXT + * @see ::TM_GPS_STATUS_BIT_MASKS + * @see ::TM_GPS_STATUS_EXT_BITS + * + * @anchor TM_GPS_STATUS_EXT_BIT_MASKS @{ */ + +#define TM_SCALE_GPS ( 1UL << TM_BIT_SCALE_GPS ) ///< See ::TM_BIT_SCALE_GPS +#define TM_SCALE_TAI ( 1UL << TM_BIT_SCALE_TAI ) ///< See ::TM_BIT_SCALE_TAI + +/** @} anchor TM_GPS_STATUS_EXT_BIT_MASKS */ + + +#define ANN_LIMIT ( - ( SECS_PER_HOUR - SECS_PER_MIN ) ) +#define ANN_LIMIT_DCF ( - ( SECS_PER_HOUR + SECS_PER_MIN ) ) + #define TM_MSK_TIME_VALID ( TM_UTC | TM_SCALE_GPS | TM_SCALE_TAI ) + /** * @brief A structure used to transmit information on date and time * @@ -2821,7 +3179,7 @@ do \ /* == MAX_SYNTH_FREQ * 10^(MAX_SYNTH_RANGE-1) */ /** - * @brief The synthesizer's phase is only be synchronized if the frequency is below this limit + * @brief The phase of the synthesizer is only synchronized when the frequency is below this limit. */ #define SYNTH_PHASE_SYNC_LIMIT 10000UL ///< 10 kHz @@ -3175,7 +3533,7 @@ enum ENABLE_FLAGS_CODES #ifndef _COM_HS_DEFINED /** - * @brief Enumeration of handshake modes + * @brief Enumeration of handshake modes. */ enum COM_HANSHAKE_MODES { HS_NONE, HS_XONXOFF, HS_RTSCTS, N_COM_HS }; #define _COM_HS_DEFINED @@ -3183,27 +3541,27 @@ enum ENABLE_FLAGS_CODES #ifndef _COM_PARM_DEFINED /** - * @brief A data type to configure a serial port's baud rate + * @brief A data type to configure the baud rate of a serial port. * * @see ::MBG_BAUD_RATES */ typedef int32_t BAUD_RATE; /** - * @brief Indices used to identify a parameter in the framing string + * @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 + * @brief A structure to store the configuration of a serial port. */ typedef struct { - 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 + 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; @@ -3308,19 +3666,19 @@ enum MBG_BAUD_RATE_CODES */ 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 + 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 }; @@ -3383,16 +3741,16 @@ enum MBG_FRAMING_CODES */ 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 + 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 }; @@ -3558,22 +3916,22 @@ enum MBG_COM_CFG_STATUS_BITS * * @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 +#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 */ @@ -3593,7 +3951,7 @@ enum MBG_COM_CFG_STATUS_BITS */ typedef struct { - uint16_t idx; ///< port index, 0..::RECEIVER_INFO::n_com_ports-1 + MBG_MSG_IDX idx; ///< Port index, 0..::RECEIVER_INFO::n_com_ports-1 PORT_SETTINGS port_settings; } PORT_SETTINGS_IDX; @@ -3622,7 +3980,7 @@ typedef struct 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 + uint32_t flags; ///< See ::PORT_INFO_FLAGS } PORT_INFO; @@ -3658,8 +4016,8 @@ enum 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 + 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 }; @@ -3676,7 +4034,7 @@ enum PORT_INFO_FLAGS */ typedef struct { - uint16_t idx; ///< port index, 0..::RECEIVER_INFO::n_com_ports-1 + MBG_MSG_IDX idx; ///< Port index, 0..::RECEIVER_INFO::n_com_ports-1 PORT_INFO port_info; } PORT_INFO_IDX; @@ -3732,7 +4090,7 @@ do \ */ typedef struct { - uint16_t idx; ///< string type index, 0..::RECEIVER_INFO::n_str_type-1 + MBG_MSG_IDX idx; ///< String type index, 0..::RECEIVER_INFO::n_str_type-1 STR_TYPE_INFO str_type_info; } STR_TYPE_INFO_IDX; @@ -3776,12 +4134,12 @@ enum STR_MODES */ enum STR_MODE_MASKS { - 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 - MSK_STR_CR_ON_SEC = ( 1UL << STR_CR_ON_SEC ) ///< see ::STR_CR_ON_SEC + 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 + MSK_STR_CR_ON_SEC = ( 1UL << STR_CR_ON_SEC ) ///< See ::STR_CR_ON_SEC }; @@ -3980,8 +4338,8 @@ enum LGCY_STR_MODES * * 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. + * by a device depends on the device type, and may depend on the + * firmware version of the device. * * 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 @@ -4077,9 +4435,9 @@ enum LGCY_STR_MODES * 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> + * 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 * @@ -4454,11 +4812,11 @@ enum ICODE_TX_CODES ) /** - * @brief IRIG TX formats where UTC offset must be subtracted to yield UTC + * @brief IRIG TX 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) + * 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 \ ( \ @@ -4466,11 +4824,11 @@ enum ICODE_TX_CODES ) /** - * @brief IRIG TX formats where UTC offset must be added to yield UTC + * @brief IRIG TX 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) + * 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 \ ( \ @@ -4925,11 +5283,11 @@ enum ICODE_RX_CODES ) /** - * @brief IRIG RX formats where UTC offset must be subtracted to yield UTC + * @brief IRIG RX 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) + * 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 \ ( \ @@ -4938,11 +5296,11 @@ enum ICODE_RX_CODES ) /** - * @brief IRIG RX formats where UTC offset must be added to yield UTC + * @brief IRIG RX 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) + * 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 \ ( \ @@ -4999,7 +5357,7 @@ enum ICODE_RX_CODES typedef struct { uint16_t icode; ///< IRIG signal code, see ::ICODE_RX_CODES and ::ICODE_TX_CODES - uint16_t flags; ///< see ::IFLAGS_BIT_MASKS + uint16_t flags; ///< See ::IFLAGS_BIT_MASKS } IRIG_SETTINGS; @@ -5038,8 +5396,8 @@ enum 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 + 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 IFLAGS_MASK = ( ( 1UL << N_IFLAGS_BITS ) - 1 ) ///< mask of all known flags }; @@ -5117,8 +5475,8 @@ do \ */ typedef struct { - 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 + 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; @@ -5195,7 +5553,7 @@ do \ /** - * @brief A data type used to read the board's debug status + * @brief A data type used to read the debug status of the device. * * @note This also includes IRIG decoder status. * @@ -5291,7 +5649,7 @@ enum MBG_DEBUG_STATUS_BITS * @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 + * code frame has been configured which provides the %UTC offset (namely * IEEE 1344 or IEEE C37.118). */ typedef int16_t MBG_REF_OFFS; @@ -5372,8 +5730,8 @@ enum MBG_OPT_BITS */ 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 + 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 }; @@ -5448,7 +5806,7 @@ typedef struct /** * @defgroup group_time_scale Time Scale Configuration * - * Used to configure the GPS receiver's basic time scale. + * Used to configure the basic time scale of the GPS receiver. * 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 @@ -5479,9 +5837,9 @@ enum 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 + 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 \ @@ -5604,9 +5962,10 @@ do \ /** * @brief A structure to define on/off cycle times * - * @note The ::MBG_TIME::sec100 field in ::POUT_TIME:on and - * ::POUT_TIME:off is not evaluated by the firmware and thus - * should always be set to 0. + * @note Eventually the ::MBG_TIME::sec100 fields in + * ::POUT_TIME:on and ::POUT_TIME:off are not evaluated + * by the firmware in ::POUT_TIMER mode, and thus + * should be set to 0 for this mode. */ typedef struct { @@ -5694,12 +6053,12 @@ typedef struct uint16_t mode; ///< Mode of operation, see ::POUT_MODES uint16_t mode_param; ///< Optional parameter depending on the mode, see @ref POUT_MODES_PARAM_MASKS - /// Timeout [min] which can be specified for some modes, see ::POUT_MODES_TIMEOUT, ::MAX_POUT_DCF_TIMOUT. + /// @brief Timeout [min] which can be specified for some modes, see ::POUT_MODES_TIMEOUT, ::MAX_POUT_DCF_TIMOUT. /// /// If the clock looses synchronization then the output - /// - is disabled **immediately** if ::POUT_IF_SYNC_ONLY is set in ::POUT_SETTINGS::flags - /// - is disabled after ::POUT_SETTINGS::timeout, if timeout is not 0 (see ::MAX_POUT_DCF_TIMOUT) - /// - stays enabled if timeout is 0 **and** ::POUT_IF_SYNC_ONLY is **not** set + /// - is disabled ***immediately*** if ::POUT_IF_SYNC_ONLY is set in #flags + /// - is disabled after #timeout, if #timeout is not 0 (see ::MAX_POUT_DCF_TIMOUT) + /// - stays enabled if #timeout is 0 ***and*** ::POUT_IF_SYNC_ONLY is ***not*** set in #flags uint16_t timeout; uint16_t flags; ///< @see ::POUT_SETTINGS_FLAGS @@ -5791,41 +6150,52 @@ do \ */ enum POUT_MODES { - /// Output is normally always 'off', or always 'on', if flag ::POUT_INVERTED is set. + /// Output is normally always 'off', or always 'on' in case + /// flag ::POUT_INVERTED is set in ::POUT_SETTINGS::flags. POUT_IDLE, /// Switch 'on' or 'off' at the times specified in ::POUT_DATA::tm. + /// + /// @note Eventually the ::MBG_TIME::sec100 fields in + /// ::POUT_TIME:on and ::POUT_TIME:off are not evaluated + /// by the firmware in ::POUT_TIMER mode, and thus + /// should be always set to 0 in this mode. POUT_TIMER, - /// Generate a pulse at the time specified in the ::POUT_TIME[0]::on field - /// in ::POUT_DATA::tm of the ::POUT_SETTINGS (POUT_SETTINGS::tm[0].on). - /// Pulse length according to ::POUT_SETTINGS::mode_param, in [10 ms] units. + /// Generate a pulse at the time specified in the tm[0].on field + /// in ::POUT_SETTINGS::pout_data. + /// Pulse length as specified in ::POUT_SETTINGS::mode_param, + /// in [10 ms] units. /// See ::MAX_POUT_PULSE_LEN. POUT_SINGLE_SHOT, - /// Generate a cyclic pulse at the interval specified in ::MBG_DATE_TIME::t - /// field of ::POUT_TIME[0]::on in ::POUT_DATA::tm of the ::POUT_SETTINGS - /// (POUT_SETTINGS::tm[0].on.t). - /// Pulse length according to ::POUT_SETTINGS::mode_param, in [10 ms] units. + /// Generate a cyclic pulse at the time specified in the tm[0].on.t + /// field in ::POUT_SETTINGS::pout_data. + /// Pulse length as specified in ::POUT_SETTINGS::mode_param, + /// in [10 ms] units. /// See ::MAX_POUT_PULSE_LEN. POUT_CYCLIC_PULSE, /// Generate a pulse whenever the second changes. - /// Pulse length according to ::POUT_SETTINGS::mode_param, in [10 ms] units. + /// Pulse length as specified in ::POUT_SETTINGS::mode_param, + /// in [10 ms] units. /// See ::MAX_POUT_PULSE_LEN. POUT_PER_SEC, /// Generate a pulse whenever the minute changes. - /// Pulse length according to ::POUT_SETTINGS::mode_param, in [10 ms] units. + /// Pulse length as specified in ::POUT_SETTINGS::mode_param, + /// in [10 ms] units. /// See ::MAX_POUT_PULSE_LEN. POUT_PER_MIN, /// Generate a pulse whenever the hour changes. - /// Pulse length according to ::POUT_SETTINGS::mode_param, in [10 ms] units. + /// Pulse length as specified in ::POUT_SETTINGS::mode_param, + /// in [10 ms] units. /// See ::MAX_POUT_PULSE_LEN. POUT_PER_HOUR, /// Generate DCF77-compatible second marks. + /// Pulse length according to the DCF77 specifications. /// See ::POUT_DCF77_M59, ::POUT_SETTINGS::timeout and ::MAX_POUT_DCF_TIMOUT. POUT_DCF77, @@ -5890,26 +6260,26 @@ enum 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 -#define MSK_POUT_PTTI_PPS ( 1UL << POUT_PTTI_PPS ) ///< see ::POUT_PTTI_PPS -#define MSK_POUT_HAVEQUICK ( 1UL << POUT_HAVEQUICK ) ///< see ::POUT_HAVEQUICK +#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 +#define MSK_POUT_PTTI_PPS ( 1UL << POUT_PTTI_PPS ) ///< See ::POUT_PTTI_PPS +#define MSK_POUT_HAVEQUICK ( 1UL << POUT_HAVEQUICK ) ///< See ::POUT_HAVEQUICK /** @} anchor POUT_MODE_MASKS */ @@ -6198,7 +6568,7 @@ enum POUT_MODES enum POUT_SETTINGS_FLAG_BITS { /// Output level is to be inverted. Can only be used - /// if ::POUT_NOT_INVERTIBLE is **not** set, but is + /// if ::POUT_NOT_INVERTIBLE is ***not*** set, but is /// supported by all ::POUT_MODES. POUT_BIT_INVERTED, @@ -6229,9 +6599,9 @@ enum POUT_SETTINGS_FLAG_BITS */ 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 + 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 }; @@ -6248,7 +6618,7 @@ enum POUT_SETTINGS_FLAGS */ typedef struct { - uint16_t idx; ///< 0..::RECEIVER_INFO::n_prg_out-1 + MBG_MSG_IDX idx; ///< 0..::RECEIVER_INFO::n_prg_out-1 POUT_SETTINGS pout_settings; } POUT_SETTINGS_IDX; @@ -6328,11 +6698,11 @@ enum 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 - POUT_SUPP_PULSE_SHIFT = ( 1UL << POUT_BIT_SUPP_PULSE_SHIFT ) ///< see ::POUT_BIT_SUPP_PULSE_SHIFT, ::POUT_DATA::pulse_shift + 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 + POUT_SUPP_PULSE_SHIFT = ( 1UL << POUT_BIT_SUPP_PULSE_SHIFT ) ///< See ::POUT_BIT_SUPP_PULSE_SHIFT, ::POUT_DATA::pulse_shift }; @@ -6350,7 +6720,7 @@ enum POUT_INFO_FLAG_MASKS */ typedef struct { - uint16_t idx; ///< 0..::RECEIVER_INFO::n_prg_out-1 + MBG_MSG_IDX idx; ///< 0..::RECEIVER_INFO::n_prg_out-1 POUT_INFO pout_info; } POUT_INFO_IDX; @@ -6414,9 +6784,10 @@ do \ */ enum MULTI_REF_TYPES { - /// 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. + /// @brief This ref type must not be used as index. + /// + /// It marks particular ::XMULTI_REF_SETTINGS structures as "unused". + /// This is only supported if bit ::XMRIF_BIT_MRF_NONE_SUPP is set. MULTI_REF_NONE = -1, MULTI_REF_GPS = 0, ///< standard GPS @@ -6437,6 +6808,8 @@ enum MULTI_REF_TYPES MULTI_REF_HAVEQUICK, ///< HaveQuick input MULTI_REF_EXT_OSC, ///< external oscillator disciplined and looped back via 1 PPS I/O MULTI_REF_SYNCE, ///< Synchronous Ethernet, needs (external) ethernet interface + MULTI_REF_VIDEO_IN, ///< Video In (Blackburst, VITC,...) + MULTI_REF_LTC, ///< Linear Time Code (Audio) N_MULTI_REF ///< the number of defined sources, must not exceed ::MAX_N_MULTI_REF_TYPES }; @@ -6473,7 +6846,9 @@ enum MULTI_REF_TYPES "GNSS Receiver", \ "HaveQuick Input", \ "ext. Osc.", \ - "Synchronous Ethernet" \ + "Synchronous Ethernet", \ + "Video Input", \ + "Linear Time Code" \ } /** @@ -6502,7 +6877,9 @@ enum MULTI_REF_TYPES "GNSS", \ "HQI", \ "EXT", \ - "SYNCE" \ + "SYNCE", \ + "VIDEO_IN", \ + "LTC" \ } @@ -6516,26 +6893,29 @@ enum MULTI_REF_TYPES * * @anchor MULTI_REF_TYPE_MASKS @{ */ -#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 -#define HAS_MULTI_REF_SYNCE ( 1UL << MULTI_REF_SYNCE ) ///< see ::MULTI_REF_SYNCE +#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 +#define HAS_MULTI_REF_SYNCE ( 1UL << MULTI_REF_SYNCE ) ///< See ::MULTI_REF_SYNCE +#define HAS_MULTI_REF_VIDEO_IN ( 1UL << MULTI_REF_VIDEO_IN ) ///< See ::MULTI_REF_VIDEO_IN +#define HAS_MULTI_REF_LTC ( 1UL << MULTI_REF_LTC ) ///< See ::MULTI_REF_LTC + /** @} anchor MULTI_REF_TYPE_MASKS */ @@ -6630,15 +7010,15 @@ enum 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 + 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 */ @@ -6700,7 +7080,7 @@ enum MULTI_REF_STATUS_BIT_MASKS */ typedef struct { - uint8_t type; ///< see ::MULTI_REF_TYPES, and note for ::XMRIF_BIT_MRF_NONE_SUPP + 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; @@ -6720,7 +7100,7 @@ do \ typedef struct { XMULTI_REF_ID id; ///< reference time source identifier - uint16_t flags; ///< see ::XMR_SETTINGS_FLAG_MSKS and ::XMR_EXT_SRC_INFO::supp_flags + uint16_t flags; ///< See ::XMR_SETTINGS_FLAG_MSKS and ::XMR_EXT_SRC_INFO::supp_flags 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 @@ -6748,8 +7128,8 @@ do \ */ typedef struct { - 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 + MBG_MSG_IDX idx; ///< The priority level index, 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, 0 == highest. + XMULTI_REF_SETTINGS settings; ///< The settings configured for this level. } XMULTI_REF_SETTINGS_IDX; @@ -6783,13 +7163,13 @@ enum XMR_SETTINGS_FLAG_BITS */ enum XMR_SETTINGS_FLAG_MSKS { - XMRSF_MSK_AUTO_BIAS_MASTER = ( 1UL << XMRSF_BIT_AUTO_BIAS_MASTER ), ///< see ::XMRSF_BIT_AUTO_BIAS_MASTER - XMRSF_MSK_AUTO_BIAS_SLAVE = ( 1UL << XMRSF_BIT_AUTO_BIAS_SLAVE ), ///< see ::XMRSF_BIT_AUTO_BIAS_SLAVE - XMRSF_MSK_ASYMMETRY_STEP_DETECTION = ( 1UL << XMRSF_BIT_ASYMMETRY_STEP_DETECTION ), ///< see ::XMRSF_BIT_ASYMMETRY_STEP_DETECTION - XMRSF_MSK_IS_TRUSTED_SRC = ( 1UL << XMRSF_BIT_IS_TRUSTED_SRC ), ///< see ::XMRSF_BIT_IS_TRUSTED_SRC - XMRSF_MSK_USE_TRUSTED_SRC = ( 1UL << XMRSF_BIT_USE_TRUSTED_SRC ), ///< see ::XMRSF_BIT_USE_TRUSTED_SRC - XMRSF_MSK_IS_TIME_OF_DAY_SRC = ( 1UL << XMRSF_BIT_IS_TIME_OF_DAY_SRC ), ///< see ::XMRSF_BIT_IS_TIME_OF_DAY_SRC - XMRSF_MSK_IS_PHASE_SRC = ( 1UL << XMRSF_BIT_IS_PHASE_SRC ) ///< see ::XMRSF_BIT_IS_PHASE_SRC + XMRSF_MSK_AUTO_BIAS_MASTER = ( 1UL << XMRSF_BIT_AUTO_BIAS_MASTER ), ///< See ::XMRSF_BIT_AUTO_BIAS_MASTER + XMRSF_MSK_AUTO_BIAS_SLAVE = ( 1UL << XMRSF_BIT_AUTO_BIAS_SLAVE ), ///< See ::XMRSF_BIT_AUTO_BIAS_SLAVE + XMRSF_MSK_ASYMMETRY_STEP_DETECTION = ( 1UL << XMRSF_BIT_ASYMMETRY_STEP_DETECTION ), ///< See ::XMRSF_BIT_ASYMMETRY_STEP_DETECTION + XMRSF_MSK_IS_TRUSTED_SRC = ( 1UL << XMRSF_BIT_IS_TRUSTED_SRC ), ///< See ::XMRSF_BIT_IS_TRUSTED_SRC + XMRSF_MSK_USE_TRUSTED_SRC = ( 1UL << XMRSF_BIT_USE_TRUSTED_SRC ), ///< See ::XMRSF_BIT_USE_TRUSTED_SRC + XMRSF_MSK_IS_TIME_OF_DAY_SRC = ( 1UL << XMRSF_BIT_IS_TIME_OF_DAY_SRC ), ///< See ::XMRSF_BIT_IS_TIME_OF_DAY_SRC + XMRSF_MSK_IS_PHASE_SRC = ( 1UL << XMRSF_BIT_IS_PHASE_SRC ) ///< See ::XMRSF_BIT_IS_PHASE_SRC }; @@ -6803,7 +7183,7 @@ typedef struct /** * @deprecated Deprecated by ::XMULTI_REF_INSTANCES::n_inst. - * If ::GPS_HAS_XMRS_MULT_INSTC is *not* set then this field provides + * 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. */ @@ -6811,7 +7191,7 @@ typedef struct /** * @deprecated Deprecated by ::XMULTI_REF_INSTANCES::n_xmr_settings. - * If ::GPS_HAS_XMRS_MULT_INSTC is *not* set then this field + * 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; @@ -6838,8 +7218,8 @@ do \ */ typedef struct { - 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 + MBG_MSG_IDX idx; ///< The priority level index, 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, 0 == highest. + XMULTI_REF_INFO info; ///< Ref. source configuration and capabilities. } XMULTI_REF_INFO_IDX; @@ -6884,8 +7264,8 @@ do \ */ typedef struct { - uint16_t idx; ///< the priority level index (highest == 0), 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1 - XMULTI_REF_STATUS status; ///< status information + MBG_MSG_IDX idx; ///< The priority level index, 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, 0 == highest. + XMULTI_REF_STATUS status; ///< Status information. } XMULTI_REF_STATUS_IDX; @@ -6970,19 +7350,19 @@ enum 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 -#define XMRS_MSK_ITU_LIMIT_VIOLATED ( 1UL << XMRS_BIT_ITU_LIMIT_VIOLATED ) ///< see ::XMRS_BIT_ITU_LIMIT_VIOLATED -#define XMRS_MSK_TRS_LIMIT_VIOLATED ( 1UL << XMRS_BIT_TRS_LIMIT_VIOLATED ) ///< see ::XMRS_BIT_TRS_LIMIT_VIOLATED +#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 +#define XMRS_MSK_ITU_LIMIT_VIOLATED ( 1UL << XMRS_BIT_ITU_LIMIT_VIOLATED ) ///< See ::XMRS_BIT_ITU_LIMIT_VIOLATED +#define XMRS_MSK_TRS_LIMIT_VIOLATED ( 1UL << XMRS_BIT_TRS_LIMIT_VIOLATED ) ///< See ::XMRS_BIT_TRS_LIMIT_VIOLATED /** @} anchor XMR_REF_STATUS_BIT_MASKS */ @@ -7053,7 +7433,7 @@ enum XMR_REF_STATUS_BITS */ typedef struct { - uint32_t flags; ///< see ::XMR_INST_FLAG_BIT_MASKS + uint32_t flags; ///< See ::XMR_INST_FLAG_BIT_MASKS uint16_t n_xmr_settings; ///< number of ::XMULTI_REF_INFO_IDX or ::XMULTI_REF_STATUS_IDX which can be retrieved 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 @@ -7071,12 +7451,37 @@ do \ /** + * @brief Extended information about the reference source of an instance type. + */ +typedef struct +{ + uint8_t integrated [MAX_N_MULTI_REF_TYPES]; ///< See ::SYS_REF_SRC_INTEGRATED + uint8_t peripheral [MAX_N_MULTI_REF_TYPES]; ///< See ::SYS_REF_SRC_PERIPHERAL + uint8_t expansion [MAX_N_MULTI_REF_TYPES]; ///< See ::SYS_REF_SRC_EXPANSION + uint8_t autarkic [MAX_N_MULTI_REF_TYPES]; ///< See ::SYS_REF_SRC_AUTARKIC + uint8_t reserved_1 [MAX_N_MULTI_REF_TYPES]; + uint8_t reserved_2 [MAX_N_MULTI_REF_TYPES]; + uint8_t reserved_3 [MAX_N_MULTI_REF_TYPES]; + uint8_t reserved_4 [MAX_N_MULTI_REF_TYPES]; + +} XMULTI_EXT_REF_INSTANCES; + +#define _mbg_swab_xmulti_ext_ref_instances( _p ) \ +do \ +{ \ +} while ( 0 ) + + + +/** * @brief Enumeration of flag bits used with XMULTI_REF instances * * @see ::XMR_INST_FLAG_BIT_MASKS */ enum XMR_INST_FLAGS { + /// @brief Indicate that the ::MULTI_REF_NONE pseude-type is supported is supported. + /// /// 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 @@ -7084,12 +7489,16 @@ enum XMR_INST_FLAGS /// this was not supported. XMRIF_BIT_MRF_NONE_SUPP, - XMRIF_BIT_HOLDOVER_STATUS_SUPP, ///< ::XMR_HOLDOVER_STATUS and associated types supported + XMRIF_BIT_HOLDOVER_STATUS_SUPP, ///< ::XMR_HOLDOVER_STATUS and associated types supported. - XMRIF_BIT_EXT_SRC_INFO_SUPP, ///< ::XMR_EXT_SRC_INFO structure supported - XMRIF_BIT_GNSS_BIAS_SUPP, ///< ::MULTI_REF_GPS or MULTI_REF_GRC can use XMULTI_REF_SETTINGS::bias + XMRIF_BIT_EXT_SRC_INFO_SUPP, ///< ::XMR_EXT_SRC_INFO structure supported. + XMRIF_BIT_GNSS_BIAS_SUPP, ///< ::MULTI_REF_GPS or MULTI_REF_GRC can use XMULTI_REF_SETTINGS::bias. - N_XMRIF_BITS ///< number of known flag bits + XMRIF_BIT_EXT_REF_INSTANCES_SUPP, ///< Supports ::XMULTI_EXT_REF_INSTANCES structure. + XMRIF_BIT_NOT_CONFIGURABLE, ///< ::XMULTI_REF_SETTINGS cannot be configured. + XMRIF_BIT_NO_STATUS, ///< No status, no stats at all. NOTHING!!! + + N_XMRIF_BITS ///< Number of known flag bits. }; @@ -7102,10 +7511,13 @@ enum 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 - XMRIF_MSK_EXT_SRC_INFO_SUPP = ( 1UL << XMRIF_BIT_EXT_SRC_INFO_SUPP ), ///< see ::XMRIF_BIT_EXT_SRC_INFO_SUPP - XMRIF_MSK_GNSS_BIAS_SUPP = ( 1UL << XMRIF_BIT_GNSS_BIAS_SUPP ) ///< see ::XMRIF_BIT_GNSS_BIAS_SUPP + 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 + XMRIF_MSK_EXT_SRC_INFO_SUPP = ( 1UL << XMRIF_BIT_EXT_SRC_INFO_SUPP ), ///< See ::XMRIF_BIT_EXT_SRC_INFO_SUPP + XMRIF_MSK_GNSS_BIAS_SUPP = ( 1UL << XMRIF_BIT_GNSS_BIAS_SUPP ), ///< See ::XMRIF_BIT_GNSS_BIAS_SUPP + XMRIF_MSK_EXT_REF_INSTANCES_SUPP = ( 1UL << XMRIF_BIT_EXT_REF_INSTANCES_SUPP ), ///< See ::XMRIF_BIT_EXT_REF_INSTANCES_SUPP + XMRIF_MSK_NOT_CONFIGURABLE = ( 1UL << XMRIF_BIT_NOT_CONFIGURABLE ), ///< See ::XMRIF_BIT_NOT_CONFIGURABLE + XMRIF_MSK_NO_STATUS = ( 1UL << XMRIF_BIT_NO_STATUS ) ///< See ::XMRIF_BIT_NO_STATUS }; @@ -7154,7 +7566,7 @@ typedef uint32_t XMR_HOLDOVER_INTV; * 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 +typedef struct xmr_holdover_status_s { 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 @@ -7235,10 +7647,10 @@ enum XMR_HOLDOVER_STATUS_FLAG_BITS */ 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 - XMR_HLDOVR_MSK_TIME_OFFS_VALID = ( 1UL << XMR_HLDOVR_BIT_TIME_OFFS_VALID ) ///< see ::XMR_HLDOVR_BIT_TIME_OFFS_VALID + 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 + XMR_HLDOVR_MSK_TIME_OFFS_VALID = ( 1UL << XMR_HLDOVR_BIT_TIME_OFFS_VALID ) ///< See ::XMR_HLDOVR_BIT_TIME_OFFS_VALID }; @@ -7250,9 +7662,11 @@ enum XMR_HOLDOVER_STATUS_FLAG_MASKS */ enum XMR_EXT_SRC_FEAT_FLAG_BITS { - XMR_EXT_SRC_FEAT_FLAG_BIT_STATS, ///< XMR source provides ::XMR_STATS - XMR_EXT_SRC_FEAT_FLAG_BIT_METRICS, ///< XMR source provides ::XMR_METRICS - XMR_EXT_SRC_FEAT_FLAG_BIT_COASTING, ///< XMR source provides coasting mode + XMR_EXT_SRC_FEAT_FLAG_BIT_STATS, ///< XMR source provides ::XMR_STATS. + XMR_EXT_SRC_FEAT_FLAG_BIT_METRICS, ///< XMR source provides ::XMR_METRICS. + XMR_EXT_SRC_FEAT_FLAG_BIT_COASTING, ///< XMR source supports coasting mode. + XMR_EXT_SRC_FEAT_FLAG_BIT_ADV_METRICS, ///< XMR source supports advanced XMR QL metrics configuration, see ::XMR_QL_LIMITS. + ///< If this feature is not available, ::XMR_METRICS can not be configured. N_XMR_EXT_SRC_FEAT_FLAG_BITS }; @@ -7267,17 +7681,18 @@ enum XMR_EXT_SRC_FEAT_FLAG_BITS */ enum XMR_EXT_SRC_FEAT_FLAG_MSKS { - XMR_EXT_SRC_FEAT_FLAG_MSK_STATS = ( 1UL << XMR_EXT_SRC_FEAT_FLAG_BIT_STATS ), ///< see ::XMR_EXT_SRC_FEAT_FLAG_BIT_STATS - XMR_EXT_SRC_FEAT_FLAG_MSK_METRICS = ( 1UL << XMR_EXT_SRC_FEAT_FLAG_BIT_METRICS ), ///< see ::XMR_EXT_SRC_FEAT_FLAG_BIT_METRICS - XMR_EXT_SRC_FEAT_FLAG_MSK_COASTING = ( 1UL << XMR_EXT_SRC_FEAT_FLAG_BIT_COASTING ) ///< see ::XMR_EXT_SRC_FEAT_FLAG_BIT_COASTING + XMR_EXT_SRC_FEAT_FLAG_MSK_STATS = ( 1UL << XMR_EXT_SRC_FEAT_FLAG_BIT_STATS ), ///< See ::XMR_EXT_SRC_FEAT_FLAG_BIT_STATS. + XMR_EXT_SRC_FEAT_FLAG_MSK_METRICS = ( 1UL << XMR_EXT_SRC_FEAT_FLAG_BIT_METRICS ), ///< See ::XMR_EXT_SRC_FEAT_FLAG_BIT_METRICS. + XMR_EXT_SRC_FEAT_FLAG_MSK_COASTING = ( 1UL << XMR_EXT_SRC_FEAT_FLAG_BIT_COASTING ), ///< See ::XMR_EXT_SRC_FEAT_FLAG_BIT_COASTING. + XMR_EXT_SRC_FEAT_FLAG_MSK_ADV_METRICS = ( 1UL << XMR_EXT_SRC_FEAT_FLAG_BIT_ADV_METRICS ) ///< See ::XMR_EXT_SRC_FEAT_FLAG_BIT_ADV_METRICS. }; typedef struct { - uint16_t supp_flags; ///< indicates which flags are supported by ::XMULTI_REF_SETTINGS::flags, see ::XMR_SETTINGS_FLAG_MSKS - uint16_t feat_flags; ///< see ::XMR_EXT_SRC_FEAT_FLAG_MSKS + uint16_t supp_flags; ///< Indicates which flags are supported by ::XMULTI_REF_SETTINGS::flags, see ::XMR_SETTINGS_FLAG_MSKS. + uint16_t feat_flags; ///< See ::XMR_EXT_SRC_FEAT_FLAG_MSKS. uint32_t reserved_0; } XMR_EXT_SRC_INFO; @@ -7318,9 +7733,9 @@ do \ * @see ::XMR_EXT_SRC_INFO::feat_flags * @see ::XMR_EXT_SRC_FEAT_FLAG_MSK_STATS */ -typedef struct +typedef struct xmr_stats_s { - uint32_t timestamp; ///< time stamp when the record was taken, UTC, seconds since 1970 + uint32_t timestamp; ///< time stamp when the record was taken, %UTC, seconds since 1970 NANO_TIME last_mue; ///< mean value (mue) of prev. interval NANO_TIME last_sigma; ///< standard deviation (sigma) of prev. interval NANO_TIME last_max; ///< maximum value within interval @@ -7330,7 +7745,7 @@ typedef struct NANO_TIME auto_bias; ///< current time automatic bias compensation uint32_t reserved_1; ///< currently reserved, unused, always 0 uint32_t reserved_2; ///< currently reserved, unused, always 0 - uint32_t flags; ///< see ::XMR_STATS_FLAGS_MSKS + uint32_t flags; ///< See ::XMR_STATS_FLAGS_MSKS } XMR_STATS; @@ -7374,9 +7789,9 @@ enum XMR_STATS_FLAGS_BITS */ enum XMR_STATS_FLAGS_MSKS { - XMR_STATS_FLAG_MSK_STEP_DETECTED = ( 1UL << XMR_STATS_FLAG_BIT_STEP_DETECTED ), ///< see ::XMR_STATS_FLAG_BIT_STEP_DETECTED - XMR_STATS_FLAG_MSK_STEP_COMPENSATED = ( 1UL << XMR_STATS_FLAG_BIT_STEP_COMPENSATED ), ///< see ::XMR_STATS_FLAG_BIT_STEP_COMPENSATED - XMR_STATS_FLAG_MSK_AUTO_BIAS_VALID = ( 1UL << XMR_STATS_FLAG_BIT_AUTO_BIAS_VALID ) ///< see ::XMR_STATS_FLAG_BIT_AUTO_BIAS_VALID + XMR_STATS_FLAG_MSK_STEP_DETECTED = ( 1UL << XMR_STATS_FLAG_BIT_STEP_DETECTED ), ///< See ::XMR_STATS_FLAG_BIT_STEP_DETECTED + XMR_STATS_FLAG_MSK_STEP_COMPENSATED = ( 1UL << XMR_STATS_FLAG_BIT_STEP_COMPENSATED ), ///< See ::XMR_STATS_FLAG_BIT_STEP_COMPENSATED + XMR_STATS_FLAG_MSK_AUTO_BIAS_VALID = ( 1UL << XMR_STATS_FLAG_BIT_AUTO_BIAS_VALID ) ///< See ::XMR_STATS_FLAG_BIT_AUTO_BIAS_VALID }; @@ -7402,8 +7817,8 @@ enum XMR_STATS_FLAGS_MSKS */ typedef struct { - uint16_t idx; ///< the priority level index (highest == 0), 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1 - XMR_STATS stats; ///< XMR statistics of the particular source + MBG_MSG_IDX idx; ///< The priority level index, 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, 0 == highest. + XMR_STATS stats; ///< XMR statistics of the particular source. } XMR_STATS_IDX; @@ -7491,6 +7906,7 @@ do \ */ enum ITU_LIMITS { + ITU_LIMIT_NONE, ITU_LIMIT_G811_PRC, ITU_LIMIT_G823_SSU, ITU_LIMIT_G823_SEC, @@ -7511,6 +7927,7 @@ enum ITU_LIMITS */ enum ITU_LIMIT_MASKS { + MSK_ITU_LIMIT_NONE = ( 1UL << ITU_LIMIT_NONE ), MSK_ITU_LIMIT_G811_PRC = ( 1UL << ITU_LIMIT_G811_PRC ), MSK_ITU_LIMIT_G823_SSU = ( 1UL << ITU_LIMIT_G823_SSU ), MSK_ITU_LIMIT_G823_SEC = ( 1UL << ITU_LIMIT_G823_SEC ), @@ -7530,6 +7947,7 @@ enum ITU_LIMIT_MASKS */ #define ITU_LIMIT_SHORT_STRS \ { \ + "None", \ "G811 (PRC)", \ "G823 (SSU)", \ "G823 (SEC)", \ @@ -7540,48 +7958,58 @@ enum ITU_LIMIT_MASKS /** - * @brief supported limits for qualtity metrics + * @brief Supported limits for qualtity metrics * * @see ::XMR_METRICS */ typedef struct { - uint8_t ql_mask; ///< see :ITU_LIMIT_MASKS - uint8_t hysteresis; ///< hysteresis (percent) between yellow and red alarm - uint16_t reserved_0; - uint32_t reserved_1; + uint32_t supp_ql_masks; ///< see :ITU_LIMIT_MASKS. Masks apply to all sources! + uint32_t reserved_0; + uint32_t reserved_1; + uint32_t reserved_2; -} XMR_QL_SETTINGS; +} XMR_QL_LIMITS; + +#define _mbg_swab_xmr_ql_limits( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_ql_masks ); \ +} while ( 0 ) typedef struct { - uint32_t supp_ql_masks; ///< see :ITU_LIMIT_MASKS - uint32_t reserved_0; - uint32_t reserved_1; - XMR_QL_SETTINGS settings; + uint8_t ql_mask; ///< see :ITU_LIMIT_MASKS + uint8_t hysteresis; ///< hysteresis (percent) between yellow and red alarm + uint16_t reserved_0; + uint32_t reserved_1; -} XMR_QL_INFO; +} XMR_QL_SETTINGS; + +#define _mbg_swab_xmr_ql_settings( _p ) \ +do \ +{ \ +} while ( 0 ) typedef struct { - uint16_t idx; + uint32_t idx; XMR_QL_SETTINGS settings; } XMR_QL_SETTINGS_IDX; +#define _mbg_swab_xmr_ql_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_xmr_ql_settings( &(_p)->settings ); \ +} while ( 0 ) -typedef struct -{ - uint16_t idx; - XMR_QL_INFO info; - -} XMR_QL_INFO_IDX; - /** @} defgroup group_multi_ref_ext */ @@ -7609,7 +8037,7 @@ typedef struct { 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 + uint32_t flags; ///< See ::MBG_GPIO_CFG_LIMIT_FLAG_MASKS } MBG_GPIO_CFG_LIMITS; @@ -7645,7 +8073,7 @@ enum 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 + 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 }; @@ -7671,6 +8099,8 @@ enum MBG_GPIO_TYPES MBG_GPIO_TYPE_VIDEO_SYNC_OUT, ///< Video sync signal output (H-Sync, V-Sync, ...) MBG_GPIO_TYPE_STUDIO_CLOCK_OUT, ///< Studio clock output MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT, ///< Digital Audio output (DARS, ...) + MBG_GPIO_TYPE_VIDEO_IN, ///< Video signal output (PAL, NTSC, ...) + MBG_GPIO_TYPE_LTC_OUT, ///< Linear Timecode output N_MBG_GPIO_TYPES ///< Number of known types }; @@ -7686,7 +8116,9 @@ enum MBG_GPIO_TYPES "Video Out", \ "Video Sync Out", \ "Studio Clock Out", \ - "Digital Audio Out" \ + "Digital Audio Out", \ + "Video In", \ + "LTC Out" \ } @@ -7721,9 +8153,9 @@ enum 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 + 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 }; @@ -7917,14 +8349,14 @@ enum MBG_GPIO_FIXED_FREQS */ 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 + 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 }; @@ -8030,10 +8462,10 @@ enum 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 + 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 }; @@ -8191,8 +8623,8 @@ enum 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 + 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 }; @@ -8283,8 +8715,8 @@ enum 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 + 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 }; @@ -8356,14 +8788,14 @@ enum MBG_GPIO_VIDEO_FORMATS */ enum MBG_GPIO_VIDEO_FORMAT_MASKS { - MSK_MBG_GPIO_VIDEO_FORMAT_OFF = ( 1UL << MBG_GPIO_VIDEO_FORMAT_OFF ), ///< see ::MBG_GPIO_VIDEO_FORMAT_OFF - MSK_MBG_GPIO_VIDEO_SD_FORMAT_NTSC = ( 1UL << MBG_GPIO_VIDEO_SD_FORMAT_NTSC ), ///< see ::MBG_GPIO_VIDEO_SD_FORMAT_NTSC - MSK_MBG_GPIO_VIDEO_SD_FORMAT_PAL = ( 1UL << MBG_GPIO_VIDEO_SD_FORMAT_PAL ), ///< see ::MBG_GPIO_VIDEO_SD_FORMAT_PAL - MSK_MBG_GPIO_VIDEO_HD_FORMAT_720_P_50Hz = ( 1UL << MBG_GPIO_VIDEO_HD_FORMAT_720_P_50Hz ), ///< see ::MBG_GPIO_VIDEO_HD_FORMAT_720_P_50Hz - MSK_MBG_GPIO_VIDEO_HD_FORMAT_1080_I_50Hz = ( 1UL << MBG_GPIO_VIDEO_HD_FORMAT_1080_I_50Hz ), ///< see ::MBG_GPIO_VIDEO_HD_FORMAT_1080_I_50Hz - MSK_MBG_GPIO_VIDEO_HD_FORMAT_720_P_59_94Hz = ( 1UL << MBG_GPIO_VIDEO_HD_FORMAT_720_P_59_94Hz ), ///< see ::MBG_GPIO_VIDEO_HD_FORMAT_720_P_59_94Hz - MSK_MBG_GPIO_VIDEO_HD_FORMAT_1080_I_59_94Hz = ( 1UL << MBG_GPIO_VIDEO_HD_FORMAT_1080_I_59_94Hz ), ///< see ::MBG_GPIO_VIDEO_HD_FORMAT_1080_I_59_94Hz - MSK_MBG_GPIO_VIDEO_SD_FORMAT_PAL_M = ( 1UL << MBG_GPIO_VIDEO_SD_FORMAT_PAL_M ) ///< see ::MBG_GPIO_VIDEO_SD_FORMAT_PAL_M + MSK_MBG_GPIO_VIDEO_FORMAT_OFF = ( 1UL << MBG_GPIO_VIDEO_FORMAT_OFF ), ///< See ::MBG_GPIO_VIDEO_FORMAT_OFF + MSK_MBG_GPIO_VIDEO_SD_FORMAT_NTSC = ( 1UL << MBG_GPIO_VIDEO_SD_FORMAT_NTSC ), ///< See ::MBG_GPIO_VIDEO_SD_FORMAT_NTSC + MSK_MBG_GPIO_VIDEO_SD_FORMAT_PAL = ( 1UL << MBG_GPIO_VIDEO_SD_FORMAT_PAL ), ///< See ::MBG_GPIO_VIDEO_SD_FORMAT_PAL + MSK_MBG_GPIO_VIDEO_HD_FORMAT_720_P_50Hz = ( 1UL << MBG_GPIO_VIDEO_HD_FORMAT_720_P_50Hz ), ///< See ::MBG_GPIO_VIDEO_HD_FORMAT_720_P_50Hz + MSK_MBG_GPIO_VIDEO_HD_FORMAT_1080_I_50Hz = ( 1UL << MBG_GPIO_VIDEO_HD_FORMAT_1080_I_50Hz ), ///< See ::MBG_GPIO_VIDEO_HD_FORMAT_1080_I_50Hz + MSK_MBG_GPIO_VIDEO_HD_FORMAT_720_P_59_94Hz = ( 1UL << MBG_GPIO_VIDEO_HD_FORMAT_720_P_59_94Hz ), ///< See ::MBG_GPIO_VIDEO_HD_FORMAT_720_P_59_94Hz + MSK_MBG_GPIO_VIDEO_HD_FORMAT_1080_I_59_94Hz = ( 1UL << MBG_GPIO_VIDEO_HD_FORMAT_1080_I_59_94Hz ), ///< See ::MBG_GPIO_VIDEO_HD_FORMAT_1080_I_59_94Hz + MSK_MBG_GPIO_VIDEO_SD_FORMAT_PAL_M = ( 1UL << MBG_GPIO_VIDEO_SD_FORMAT_PAL_M ) ///< See ::MBG_GPIO_VIDEO_SD_FORMAT_PAL_M }; @@ -8384,12 +8816,12 @@ enum MBG_GPIO_VIDEO_FORMAT_MASKS /** - * @brief Initializers for an array of video output name strings + * @brief Initializers for an array of video format strings * * @see ::MBG_GPIO_VIDEO_FORMATS * @see ::MBG_GPIO_VIDEO_FORMAT_MASKS */ -#define MBG_GPIO_VIDEO_OUT_STRS \ +#define MBG_GPIO_VIDEO_FORMAT_STRS \ { \ "OFF", \ "NTSC (525i)", \ @@ -8424,8 +8856,8 @@ enum MBG_GPIO_VIDEO_OUT_FLAGS */ enum MBG_GPIO_VIDEO_OUT_FLAG_MASKS { - MSK_MBG_GPIO_VIDEO_OUT_HAS_NO_FREE_CONF = ( 1UL << MBG_GPIO_VIDEO_OUT_HAS_NO_FREE_CONF ), ///< see ::MBG_GPIO_VIDEO_OUT_HAS_NO_FREE_CONF - MSK_MBG_GPIO_VIDEO_OUT_HAS_TC_SD = ( 1UL << MBG_GPIO_VIDEO_OUT_HAS_TC_SD ) ///< see ::MBG_GPIO_VIDEO_OUT_HAS_TC_SD + MSK_MBG_GPIO_VIDEO_OUT_HAS_NO_FREE_CONF = ( 1UL << MBG_GPIO_VIDEO_OUT_HAS_NO_FREE_CONF ), ///< See ::MBG_GPIO_VIDEO_OUT_HAS_NO_FREE_CONF + MSK_MBG_GPIO_VIDEO_OUT_HAS_TC_SD = ( 1UL << MBG_GPIO_VIDEO_OUT_HAS_TC_SD ) ///< See ::MBG_GPIO_VIDEO_OUT_HAS_TC_SD }; @@ -8459,10 +8891,10 @@ enum MBG_GPIO_VIDEO_EPOCHS */ enum MBG_GPIO_VIDEO_EPOCH_MASKS { - MSK_SMPTE_TAI_EPOCH_1970 = ( 1UL << SMPTE_TAI_EPOCH_1970 ), ///< see ::SMPTE_TAI_EPOCH_1970 - MSK_SMPTE_TAI_EPOCH_1958 = ( 1UL << SMPTE_TAI_EPOCH_1958 ), ///< see ::SMPTE_TAI_EPOCH_1958 - MSK_SMPTE_UTC_EPOCH_1972 = ( 1UL << SMPTE_UTC_EPOCH_1972 ), ///< see ::SMPTE_UTC_EPOCH_1972 - MSK_SMPTE_GPS_EPOCH_1980 = ( 1UL << SMPTE_GPS_EPOCH_1980 ) ///< see ::SMPTE_GPS_EPOCH_1980 + MSK_SMPTE_TAI_EPOCH_1970 = ( 1UL << SMPTE_TAI_EPOCH_1970 ), ///< See ::SMPTE_TAI_EPOCH_1970 + MSK_SMPTE_TAI_EPOCH_1958 = ( 1UL << SMPTE_TAI_EPOCH_1958 ), ///< See ::SMPTE_TAI_EPOCH_1958 + MSK_SMPTE_UTC_EPOCH_1972 = ( 1UL << SMPTE_UTC_EPOCH_1972 ), ///< See ::SMPTE_UTC_EPOCH_1972 + MSK_SMPTE_GPS_EPOCH_1980 = ( 1UL << SMPTE_GPS_EPOCH_1980 ) ///< See ::SMPTE_GPS_EPOCH_1980 }; @@ -8504,8 +8936,8 @@ enum MBG_GPIO_VIDEO_TC_MODES */ enum MBG_GPIO_VIDEO_TC_MODE_MASKS { - MSK_MBG_GPIO_VIDEO_TC_MODE_NONE = ( 1UL << MBG_GPIO_VIDEO_TC_MODE_NONE ), ///< see ::MBG_GPIO_VIDEO_TC_MODE_NONE - MSK_MBG_GPIO_VIDEO_TC_MODE_VITC = ( 1UL << MBG_GPIO_VIDEO_TC_MODE_VITC ) ///< see ::MBG_GPIO_VIDEO_TC_MODE_VITC + MSK_MBG_GPIO_VIDEO_TC_MODE_NONE = ( 1UL << MBG_GPIO_VIDEO_TC_MODE_NONE ), ///< See ::MBG_GPIO_VIDEO_TC_MODE_NONE + MSK_MBG_GPIO_VIDEO_TC_MODE_VITC = ( 1UL << MBG_GPIO_VIDEO_TC_MODE_VITC ) ///< See ::MBG_GPIO_VIDEO_TC_MODE_VITC }; @@ -8765,9 +9197,9 @@ enum MBG_GPIO_STUDIO_CLOCK_BASE_FREQS */ enum MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_MASKS { - MSK_MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_32KHZ = ( 1UL << MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_32KHZ ), ///< see ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_32KHZ - MSK_MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_44_1KHZ = ( 1UL << MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_44_1KHZ ), ///< see ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_44_1KHZ - MSK_MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_48KHZ = ( 1UL << MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_48KHZ ) ///< see ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_48KHZ + MSK_MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_32KHZ = ( 1UL << MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_32KHZ ), ///< See ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_32KHZ + MSK_MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_44_1KHZ = ( 1UL << MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_44_1KHZ ), ///< See ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_44_1KHZ + MSK_MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_48KHZ = ( 1UL << MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_48KHZ ) ///< See ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_48KHZ }; @@ -8826,21 +9258,21 @@ enum MBG_GPIO_STUDIO_CLOCK_SCALES */ enum MBG_GPIO_STUDIO_CLOCK_SCALE_MASKS { - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_32 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_32 ), ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_32 - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_16 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_16 ), ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_16 - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_8 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_8 ), ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_8 - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_4 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_4 ), ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_4 - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_2 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_2 ), ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_2 - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1 ), ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_1 - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_2 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_2 ), ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_2 - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_4 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_4 ), ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_4 - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_8 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_8 ), ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_8 - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_16 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_16 ), ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_16 - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_32 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_32 ), ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_32 - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_64 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_64 ), ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_64 - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_128 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_128 ), ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_128 - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_256 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_256 ), ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_256 - MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_512 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_512 ) ///< see ::MBG_GPIO_STUDIO_CLOCK_SCALE_512 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_32 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_32 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_32 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_16 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_16 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_16 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_8 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_8 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_8 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_4 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_4 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_4 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_2 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_2 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_2 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_1 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_2 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_2 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_2 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_4 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_4 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_4 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_8 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_8 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_8 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_16 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_16 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_16 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_32 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_32 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_32 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_64 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_64 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_64 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_128 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_128 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_128 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_256 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_256 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_256 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_512 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_512 ) ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_512 }; @@ -8892,7 +9324,7 @@ enum MBG_GPIO_STUDIO_CLOCK_FLAGS */ enum MBG_GPIO_STUDIO_CLOCK_FLAG_MASKS { - MSK_MBG_GPIO_STUDIO_CLOCK_OUTPUT_ENABLED = ( 1UL << MBG_GPIO_STUDIO_CLOCK_OUTPUT_ENABLED ) ///< see ::MBG_GPIO_STUDIO_CLOCK_OUTPUT_ENABLED + MSK_MBG_GPIO_STUDIO_CLOCK_OUTPUT_ENABLED = ( 1UL << MBG_GPIO_STUDIO_CLOCK_OUTPUT_ENABLED ) ///< See ::MBG_GPIO_STUDIO_CLOCK_OUTPUT_ENABLED }; @@ -8990,8 +9422,8 @@ enum MBG_GPIO_DIGITAL_AUDIO_TYPES */ enum MBG_GPIO_DIGITAL_AUDIO_TYPE_MASKS { - MSK_MBG_GPIO_DIGITAL_AUDIO_TYPE_OFF = ( 1UL << MBG_GPIO_DIGITAL_AUDIO_TYPE_OFF ), ///< see ::MBG_GPIO_DIGITAL_AUDIO_TYPE_OFF - MSK_MBG_GPIO_DIGITAL_AUDIO_TYPE_DARS = ( 1UL << MBG_GPIO_DIGITAL_AUDIO_TYPE_DARS ) ///< see ::MBG_GPIO_DIGITAL_AUDIO_TYPE_DARS + MSK_MBG_GPIO_DIGITAL_AUDIO_TYPE_OFF = ( 1UL << MBG_GPIO_DIGITAL_AUDIO_TYPE_OFF ), ///< See ::MBG_GPIO_DIGITAL_AUDIO_TYPE_OFF + MSK_MBG_GPIO_DIGITAL_AUDIO_TYPE_DARS = ( 1UL << MBG_GPIO_DIGITAL_AUDIO_TYPE_DARS ) ///< See ::MBG_GPIO_DIGITAL_AUDIO_TYPE_DARS }; @@ -9029,7 +9461,7 @@ enum MBG_GPIO_DIGITAL_AUDIO_FLAGS */ enum MBG_GPIO_DIGITAL_AUDIO_FLAG_MASKS { - MSK_MBG_GPIO_DIGITAL_AUDIO_RESERVED_FLAG = ( 1UL << MBG_GPIO_DIGITAL_AUDIO_RESERVED_FLAG ) ///< see ::MBG_GPIO_DIGITAL_AUDIO_RESERVED_FLAG + MSK_MBG_GPIO_DIGITAL_AUDIO_RESERVED_FLAG = ( 1UL << MBG_GPIO_DIGITAL_AUDIO_RESERVED_FLAG ) ///< See ::MBG_GPIO_DIGITAL_AUDIO_RESERVED_FLAG }; @@ -9052,6 +9484,8 @@ typedef struct } MBG_GPIO_DIGITAL_AUDIO_OUT_SETTINGS; + + #define _mbg_swab_mbg_gpio_digital_audio_out_settings( _p ) \ do \ { \ @@ -9082,6 +9516,8 @@ typedef struct } MBG_GPIO_DIGITAL_AUDIO_OUT_SUPP; + + #define _mbg_swab_mbg_gpio_digital_audio_out_supp( _p ) \ do \ { \ @@ -9095,6 +9531,262 @@ do \ /** + * @brief Enumeration of physical video input signal sources + * + * Video can be received over a single or differential signals + * + * @see MBG_GPIO_VIDEO_IN_SETTINGS + */ +enum MBG_GPIO_VIDEO_IN_SIGNAL_SRCS +{ + MBG_GPIO_VIDEO_IN_SIGNAL_SRC_SES, ///< single-ended signal video input + MBG_GPIO_VIDEO_IN_SIGNAL_SRC_DIFFERENTIAL, ///< differential signal line video input + N_MBG_GPIO_VIDEO_IN_SIGNAL_SRCS ///< number of possible signal sources +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_VIDEO_IN_SIGNAL_SRCS + * + * Used with ::MBG_GPIO_VIDEO_IN_SETTINGS::tc_mode + * + */ +enum MBG_GPIO_VIDEO_IN_SIGNAL_SRC_MASKS +{ + MSK_MBG_GPIO_VIDEO_IN_SIGNAL_SRC_SES = ( 1UL << MBG_GPIO_VIDEO_IN_SIGNAL_SRC_SES ), ///< See ::MBG_GPIO_VIDEO_IN_SIGNAL_SRC_SES + MSK_MBG_GPIO_VIDEO_IN_SIGNAL_SRC_DIFFERENTIAL = ( 1UL << MBG_GPIO_VIDEO_IN_SIGNAL_SRC_DIFFERENTIAL ) ///< See ::MBG_GPIO_VIDEO_IN_SIGNAL_SRC_DIFFERENTIAL +}; + + + + +/** + * @brief Initializers for an array of video signal input source strings + * + * @see ::MBG_GPIO_VIDEO_IN_SIGNAL_SRCS + * @see ::MBG_GPIO_VIDEO_IN_SIGNAL_SRC_MASKS + */ +#define MBG_GPIO_VIDEO_IN_SIGNAL_SRC_STRS \ +{ \ + "Single-ended signal input", \ + "Differential signal input" \ +} + + + +/** + * @brief Configuration of a GPIO as video input module + * + * Used as sub-structure of ::MBG_GPIO_SETTINGS + * + * @see ::MBG_GPIO_TYPE_VIDEO_IN + * @see ::MBG_GPIO_SETTINGS + */ +typedef struct +{ + uint32_t format; ///< video format, see ::MBG_GPIO_VIDEO_FORMATS + + uint8_t epoch; ///< epoch, see ::MBG_GPIO_VIDEO_EPOCHS + uint8_t signal_src; ///< video input signal source, see ::MBG_GPIO_VIDEO_IN_SIGNAL_SRCS + uint8_t tc_mode; ///< time code mode, see ::MBG_GPIO_VIDEO_TC_MODES + uint8_t tc_line; ///< time code line location, valid lines: 6-22 + + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + uint32_t reserved2; ///< reserved, currently always 0 +} MBG_GPIO_VIDEO_IN_SETTINGS; + + + +#define _mbg_swab_mbg_gpio_video_in_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->format ); \ + _mbg_swab8( &(_p)->epoch ); \ + _mbg_swab8( &(_p)->signal_src ); \ + _mbg_swab8( &(_p)->tc_mode ); \ + _mbg_swab8( &(_p)->tc_line ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ + _mbg_swab32( &(_p)->reserved2 ); \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t supp_formats; ///< supported video formats, see ::MBG_GPIO_VIDEO_FORMAT_MASKS + uint32_t supp_epochs; ///< supported epochs, see ::MBG_GPIO_VIDEO_EPOCH_MASKS + + uint32_t supp_signal_srcs; ///< video input signal sources, see ::MBG_GPIO_VIDEO_IN_SIGNAL_SRC_MASKS + uint32_t supp_tc_modes; ///< time code mode, see ::MBG_GPIO_VIDEO_TC_MODE_MASKS + + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + uint32_t reserved2; ///< reserved, currently always 0 + +} MBG_GPIO_VIDEO_IN_SUPP; + + + +#define _mbg_swab_mbg_gpio_video_in_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_formats ); \ + _mbg_swab32( &(_p)->supp_epochs ); \ + _mbg_swab32( &(_p)->supp_signal_srcs ); \ + _mbg_swab32( &(_p)->supp_tc_modes ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ + _mbg_swab32( &(_p)->reserved2 ); \ + _mbg_swab32( &(_p)->reserved3 ); \ +} while ( 0 ) + + +/** + * @brief Enumeration of types used with GPIO type LTC outputs + * + * Used with ::MBG_GPIO_LTC_OUT_SETTINGS::type, and to + * define ::MBG_GPIO_LTC_OUT_TYPE_MASKS + * + * @see ::MBG_GPIO_LTC_OUT_TYPE_MASKS + * @see ::MBG_GPIO_LTC_OUT_TYPE_STRS + */ +enum MBG_GPIO_LTC_OUT_TYPES +{ + MBG_GPIO_LTC_OUT_OFF, + MBG_GPIO_LTC_OUT_TYPE_24FPS_23_976Hz, + MBG_GPIO_LTC_OUT_TYPE_24FPS, + MBG_GPIO_LTC_OUT_TYPE_25FPS, + MBG_GPIO_LTC_OUT_TYPE_30FPS, + MBG_GPIO_LTC_OUT_TYPE_30FPS_DROP_FRAME, + N_MBG_GPIO_LTC_OUT_TYPES ///< number of known types +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_LTC_OUT_TYPES + * + * Used with :: MBG_GPIO_TYPE_LTC_OUT_SUPP::supp_types + * + * @see ::MBG_GPIO_LTC_OUT_TYPES + */ +enum MBG_GPIO_LTC_OUT_TYPE_MASKS +{ + MSK_MBG_GPIO_LTC_OUT_OFF = ( 1UL << MBG_GPIO_LTC_OUT_OFF ), ///< See ::MBG_GPIO_LTC_OUT_OFF + MSK_MBG_GPIO_LTC_OUT_TYPE_24FPS_23_976Hz = ( 1UL << MBG_GPIO_LTC_OUT_TYPE_24FPS_23_976Hz ), ///< See ::MBG_GPIO_LTC_OUT_TYPE_24FPS_23_976Hz + MSK_MBG_GPIO_LTC_OUT_TYPE_24FPS = ( 1UL << MBG_GPIO_LTC_OUT_TYPE_24FPS ), ///< See ::MBG_GPIO_LTC_OUT_TYPE_24FPS + MSK_MBG_GPIO_LTC_OUT_TYPE_25FPS = ( 1UL << MBG_GPIO_LTC_OUT_TYPE_25FPS ), ///< See ::MBG_GPIO_LTC_OUT_TYPE_25FPS + MSK_MBG_GPIO_LTC_OUT_TYPE_30FPS = ( 1UL << MBG_GPIO_LTC_OUT_TYPE_30FPS ), ///< See ::MBG_GPIO_LTC_OUT_TYPE_30FPS + MSK_MBG_GPIO_LTC_OUT_TYPE_30FPS_DROP_FRAME = ( 1UL << MBG_GPIO_LTC_OUT_TYPE_30FPS_DROP_FRAME ) ///< See ::MBG_GPIO_LTC_OUT_TYPE_30FPS_DROP_FRAME +}; + +/** + * @brief Initializers for an array of ltc out strings + * + * @see ::MBG_GPIO_LTC_OUT_TYPES + */ +#define MBG_GPIO_LTC_OUT_TYPE_STRS \ +{ \ + "OFF", \ + "LTC 24FPS / 23.976Hz", \ + "LTC 24FPS", \ + "LTC 25FPS", \ + "LTC 30FPS", \ + "LTC 30FPS Drop Frame" \ +} + +/** + * @brief Enumeration of flags used with GPIO type LTC outputs + */ +enum MBG_GPIO_LTC_OUT_FLAGS +{ + MBG_GPIO_LTC_OUT_RESERVED_FLAG, ///< reserved + N_MBG_GPIO_LTC_OUT_FLAGS ///< number of known flags +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_LTC_OUT_FLAGS + * + * Used with ::MBG_GPIO_LTC_OUT_SETTINGS::flags + * + * @see ::MBG_GPIO_LTC_OUT_FLAGS + */ +enum MBG_GPIO_LTC_OUT_FLAG_MASKS +{ + MSK_MBG_GPIO_LTC_OUT_RESERVED_FLAG = ( 1UL << MBG_GPIO_LTC_OUT_RESERVED_FLAG ) ///< See ::MBG_GPIO_LTC_OUT_RESERVED_FLAG +}; + + + +/** + * @brief Configuration of a GPIO LTC output + * + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_LTC_OUT + * @see ::MBG_GPIO_SETTINGS + */ +typedef struct +{ + uint32_t type; ///< LTC type, see ::MBG_GPIO_LTC_OUT_TYPES + uint32_t flags; ///< reserved, currently always 0 + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + uint32_t reserved2; ///< reserved, currently always 0 + +} MBG_GPIO_LTC_OUT_SETTINGS; + + + +#define _mbg_swab_mbg_gpio_ltc_out_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->type ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ + _mbg_swab32( &(_p)->reserved2 ); \ +} while ( 0 ) + + + +/** + * @brief Supported options for LTC output + * + * Used as sub-structure of ::MBG_GPIO_LIMITS. + * + * @see ::MBG_GPIO_TYPE_LTC_OUT + * @see ::MBG_GPIO_LIMITS + */ +typedef struct +{ + uint32_t supp_types; ///< Supported LTC types, see ::MBG_GPIO_LTC_OUT_TYPE_MASKS. + uint32_t supp_flags; ///< Reserved, currently always 0. + uint32_t reserved_0; ///< Reserved, currently always 0. + uint32_t reserved_1; ///< Reserved, currently always 0. + uint32_t reserved_2; ///< Reserved, currently always 0. + +} MBG_GPIO_LTC_OUT_SUPP; + + +#define _mbg_swab_mbg_gpio_ltc_out_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_types ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) + + + +/** * @brief Enumeration of general flags used with a GPIO * * @see ::MBG_GPIO_FLAG_MASKS @@ -9102,50 +9794,55 @@ do \ enum MBG_GPIO_FLAGS { MBG_GPIO_DEPENDS_ON_ASS_IO_IDX, ///< indicates that this output depends on GPIO with ::MBG_GPIO_SETTINGS::ass_io_idx and may not be configured independently + MBG_GPIO_PORT_INVISIBLE, ///< gpio is used internally and should not be displayed by config apps N_MBG_GPIO_FLAGS ///< number of known flags }; /** - * @brief Bit masks associated with ::MBG_GPIO_FLAGS + * @brief Bit masks associated with ::MBG_GPIO_FLAGS. * - * Used with ::MBG_GPIO_LIMITS::supp_flags and ::MBG_GPIO_SETTINGS::flags + * Used with ::MBG_GPIO_LIMITS::supp_flags and ::MBG_GPIO_SETTINGS::flags. * * @see ::MBG_GPIO_FLAGS */ enum MBG_GPIO_FLAG_MASKS { - MSK_MBG_GPIO_DEPENDS_ON_ASS_IO_IDX = ( 1UL << MBG_GPIO_DEPENDS_ON_ASS_IO_IDX ) ///< see ::MBG_GPIO_DEPENDS_ON_ASS_IO_IDX + MSK_MBG_GPIO_DEPENDS_ON_ASS_IO_IDX = ( 1UL << MBG_GPIO_DEPENDS_ON_ASS_IO_IDX ), ///< See ::MBG_GPIO_DEPENDS_ON_ASS_IO_IDX + MSK_MBG_GPIO_PORT_INVISIBLE = ( 1UL << MBG_GPIO_PORT_INVISIBLE ) ///< See ::MBG_GPIO_PORT_INVISIBLE }; /** - * @brief A generic structure used to hold a GPIO port's settings + * @brief A generic structure used to hold the settings of a GPIO port. */ typedef struct { - uint32_t type; ///< GPIO type, see ::MBG_GPIO_TYPES + uint32_t type; ///< GPIO type, see ::MBG_GPIO_TYPES. - uint16_t reserved_1; ///< reserved, currently always 0 - uint8_t reserved_2; ///< reserved, currently always 0 - uint8_t ass_io_idx; ///< associated GPIO index, only valid if ::MSK_MBG_GPIO_DEPENDS_ON_ASS_IO_IDX is set in flags field + uint16_t reserved_1; ///< Reserved, currently always 0. + uint8_t reserved_2; ///< Reserved, currently always 0. + uint8_t ass_io_idx; ///< Associated GPIO index, only valid if ::MSK_MBG_GPIO_DEPENDS_ON_ASS_IO_IDX is set in flags field. - uint32_t flags; ///< flags, see ::MBG_GPIO_FLAG_MASKS + uint32_t flags; ///< Flags, see ::MBG_GPIO_FLAG_MASKS. - /// settings depending on the GPIO type, see ::MBG_GPIO_TYPES + /// @brief Settings depending on the GPIO @a #type, see ::MBG_GPIO_TYPES. union { - 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 - MBG_GPIO_VIDEO_OUT_SETTINGS video_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_OUT - MBG_GPIO_VIDEO_SYNC_OUT_SETTINGS video_sync_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_SYNC_OUT - MBG_GPIO_STUDIO_CLOCK_OUT_SETTINGS studio_clk_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_STUDIO_CLOCK_OUT - MBG_GPIO_DIGITAL_AUDIO_OUT_SETTINGS digital_audio_out; ///< if ::MBG_GPIO_SETTINGS::type is ::;MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT + uint32_t b[6]; ///< Just to indicate the size of this union. + 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 + MBG_GPIO_VIDEO_OUT_SETTINGS video_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_OUT + MBG_GPIO_VIDEO_SYNC_OUT_SETTINGS video_sync_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_SYNC_OUT + MBG_GPIO_STUDIO_CLOCK_OUT_SETTINGS studio_clk_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_STUDIO_CLOCK_OUT + MBG_GPIO_DIGITAL_AUDIO_OUT_SETTINGS digital_audio_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT + MBG_GPIO_VIDEO_IN_SETTINGS video_in; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_IN + MBG_GPIO_LTC_OUT_SETTINGS ltc_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_LTC_OUT } u; } MBG_GPIO_SETTINGS; @@ -9172,6 +9869,8 @@ do case MBG_GPIO_TYPE_VIDEO_SYNC_OUT : _mbg_swab_mbg_gpio_video_sync_out_settings( &(_p)->u.video_sync_out ); break; \ case MBG_GPIO_TYPE_STUDIO_CLOCK_OUT : _mbg_swab_mbg_gpio_studio_clock_out_settings( &(_p)->u.studio_clk_out ); break; \ case MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT : _mbg_swab_mbg_gpio_digital_audio_out_settings( &(_p)->u.digital_audio_out ); break; \ + case MBG_GPIO_TYPE_VIDEO_IN : _mbg_swab_mbg_gpio_video_in_settings( &(_p)->u.video_in ); break; \ + case MBG_GPIO_TYPE_LTC_OUT : _mbg_swab_mbg_gpio_ltc_out_settings( &(_p)->u.ltc_out ); break; \ default : break; \ } \ } while ( 0 ) @@ -9179,12 +9878,12 @@ do /** - * @brief A GPIO port's current settings, plus port index + * @brief The current settings of a GPIO port, 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_MSG_IDX_32 idx; ///< GPIO port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1. + MBG_GPIO_SETTINGS settings; ///< Current settings } MBG_GPIO_SETTINGS_IDX; @@ -9198,7 +9897,7 @@ do \ /** - * @brief A generic structure used to specify a GPIO port's limits + * @brief A generic structure used to specify the limits of a GPIO port. */ typedef struct { @@ -9206,18 +9905,21 @@ typedef struct uint32_t reserved; ///< reserved, currently always 0 uint32_t supp_flags; ///< supported flags, see ::MBG_GPIO_FLAG_MASKS - /// limits depending on the GPIO type, see ::MBG_GPIO_TYPES + /// Limits depending on the GPIO type, see ::MBG_GPIO_TYPES. union { - MBG_GPIO_FREQ_IN_SUPP freq_in; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FREQ_IN - MBG_GPIO_FREQ_OUT_SUPP freq_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FREQ_OUT - MBG_GPIO_FIXED_FREQ_OUT_SUPP ff_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FIXED_FREQ_OUT - MBG_GPIO_BITS_IN_SUPP bits_in; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_BITS_IN - MBG_GPIO_BITS_OUT_SUPP bits_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_BITS_OUT - MBG_GPIO_VIDEO_OUT_SUPP video_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_OUT - MBG_GPIO_VIDEO_SYNC_OUT_SUPP video_sync_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_SYNC_OUT - MBG_GPIO_STUDIO_CLOCK_OUT_SUPP studio_clk_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_STUDIO_CLOCK_OUT - MBG_GPIO_DIGITAL_AUDIO_OUT_SUPP digital_audio_out; ///< if ::MBG_GPIO_SETTINGS::type is ::;MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT + uint32_t b[7]; ///< Just to indicate the size of this union. + MBG_GPIO_FREQ_IN_SUPP freq_in; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FREQ_IN + MBG_GPIO_FREQ_OUT_SUPP freq_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FREQ_OUT + MBG_GPIO_FIXED_FREQ_OUT_SUPP ff_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FIXED_FREQ_OUT + MBG_GPIO_BITS_IN_SUPP bits_in; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_BITS_IN + MBG_GPIO_BITS_OUT_SUPP bits_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_BITS_OUT + MBG_GPIO_VIDEO_OUT_SUPP video_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_OUT + MBG_GPIO_VIDEO_SYNC_OUT_SUPP video_sync_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_SYNC_OUT + MBG_GPIO_STUDIO_CLOCK_OUT_SUPP studio_clk_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_STUDIO_CLOCK_OUT + MBG_GPIO_DIGITAL_AUDIO_OUT_SUPP digital_audio_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT + MBG_GPIO_VIDEO_IN_SUPP video_in; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_IN + MBG_GPIO_LTC_OUT_SUPP ltc_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_LTC_OUT } u; } MBG_GPIO_LIMITS; @@ -9242,6 +9944,8 @@ do case MBG_GPIO_TYPE_VIDEO_SYNC_OUT : _mbg_swab_mbg_gpio_video_sync_out_supp( &(_p)->u.video_sync_out ); break; \ case MBG_GPIO_TYPE_STUDIO_CLOCK_OUT : _mbg_swab_mbg_gpio_studio_clock_out_supp( &(_p)->u.studio_clk_out ); break; \ case MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT : _mbg_swab_mbg_gpio_digital_audio_out_supp( &(_p)->u.digital_audio_out ); break; \ + case MBG_GPIO_TYPE_VIDEO_IN : _mbg_swab_mbg_gpio_video_in_supp( &(_p)->u.video_in ); break; \ + case MBG_GPIO_TYPE_LTC_OUT : _mbg_swab_mbg_gpio_ltc_out_supp( &(_p)->u.ltc_out ); break; \ default : break; \ } \ } while ( 0 ) @@ -9249,12 +9953,12 @@ do /** - * @brief A GPIO port's current settings and limits + * @brief The current settings and limits of a GPIO port. */ typedef struct { - MBG_GPIO_SETTINGS settings; ///< current settings - MBG_GPIO_LIMITS limits; ///< limits of this GPIO port + MBG_GPIO_SETTINGS settings; ///< Current settings. + MBG_GPIO_LIMITS limits; ///< Limits of this GPIO port. } MBG_GPIO_INFO; @@ -9268,12 +9972,12 @@ do \ /** - * @brief A GPIO port's current settings and limits, plus port index + * @brief The current settings and limits of a GPIO port, plus port index. */ typedef struct { - 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_MSG_IDX_32 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_IDX; @@ -9291,11 +9995,11 @@ do \ */ typedef struct { - 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 + 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_STATUS; @@ -9316,8 +10020,8 @@ do \ */ typedef struct { - uint16_t idx; ///< port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1 - MBG_GPIO_STATUS status; ///< status information + MBG_MSG_IDX idx; ///< GPIO port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1. + MBG_GPIO_STATUS status; ///< Status information. } MBG_GPIO_STATUS_IDX; @@ -9399,12 +10103,12 @@ enum 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 + 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 }; /* @@ -9455,8 +10159,8 @@ enum HAVEQUICK_FORMAT_MASKS */ typedef struct { - uint16_t format; ///< see ::HAVEQUICK_FORMATS - uint16_t flags; ///< see ::HAVEQUICK_FLAG_MASKS + 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 @@ -9479,7 +10183,7 @@ do \ typedef struct { HAVEQUICK_SETTINGS settings; ///< current settings - uint32_t supp_formats; ///< see ::HAVEQUICK_FORMAT_MASKS + 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 @@ -9518,9 +10222,9 @@ enum 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 + 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 */ @@ -9639,6 +10343,9 @@ enum MBG_EVT_IDS MBG_EVT_ID_UFU_FLASHED, ///< UFU file has been flashed MBG_EVT_ID_UFU_PROGRESS, ///< UFU flashing is in progress MBG_EVT_ID_DATABASE_CONNECTED, ///< Database(s) have been (re-)connected + MBG_EVT_ID_NTP_STATE_SYNC, ///< NTP is sync + MBG_EVT_ID_NTP_STATE_NOT_SYNC, ///< NTP not sync + MBG_EVT_ID_FW_OSV, ///< Firmware has been set to OSV N_MBG_EVT_ID }; @@ -9654,21 +10361,25 @@ enum MBG_EVT_IDS #define ENG_EVT_ID_NAME_ANT_OK "Antenna OK" #define ENG_EVT_ID_NAME_LOW_SATS "Few Sats Only" #define ENG_EVT_ID_NAME_FW_INSTALLED "Firmware installed" -#define ENG_EVT_ID_NAME_PTP_PORT_STATE_UNINITIALIZED "PTP state: UNINITIALIZED" -#define ENG_EVT_ID_NAME_PTP_PORT_STATE_INITIALIZING "PTP state: INITIALIZING" -#define ENG_EVT_ID_NAME_PTP_PORT_STATE_FAULTY "PTP state: FAULTY" -#define ENG_EVT_ID_NAME_PTP_PORT_STATE_DISABLED "PTP state: DISABLED" -#define ENG_EVT_ID_NAME_PTP_PORT_STATE_LISTENING "PTP state: LISTENING" -#define ENG_EVT_ID_NAME_PTP_PORT_STATE_PRE_MASTER "PTP state: PRE_MASTER" -#define ENG_EVT_ID_NAME_PTP_PORT_STATE_MASTER "PTP state: MASTER" -#define ENG_EVT_ID_NAME_PTP_PORT_STATE_PASSIVE "PTP state: PASSIVE" -#define ENG_EVT_ID_NAME_PTP_PORT_STATE_UNCALIBRATED "PTP state: UNCALIBRATED" -#define ENG_EVT_ID_NAME_PTP_PORT_STATE_SLAVE "PTP state: SLAVE" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_UNINITIALIZED "PTP state: Uninitialized" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_INITIALIZING "PTP state: Initializing" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_FAULTY "PTP state: Faulty" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_DISABLED "PTP state: Disabled" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_LISTENING "PTP state: Listening" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_PRE_MASTER "PTP state: Pre-Master" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_MASTER "PTP state: Master" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_PASSIVE "PTP state: Passive" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_UNCALIBRATED "PTP state: Uncalibrated" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_SLAVE "PTP state: Slave" #define ENG_EVT_ID_NAME_FW_ACTIVATED "Firmware activated" #define ENG_EVT_ID_NAME_FW_DELETED "Firmware deleted" #define ENG_EVT_ID_NAME_FW_ROLLBACK "Firmware rollback" #define ENG_EVT_ID_NAME_UFU_FLASHED "UFU flashed" +#define ENG_EVT_ID_NAME_UFU_PROGRESS "UFU is being transferred..." #define ENG_EVT_ID_NAME_DATABASE_CONNECTED "Database(s) connected" +#define ENG_EVT_ID_NAME_NTP_STATE_SYNC "NTP state: Sync to system peer" +#define ENG_EVT_ID_NAME_NTP_STATE_NOT_SYNC "NTP state: Not sync" +#define ENG_EVT_ID_NAME_FW_OSV "Firmware set to OSV" #define MBG_EVT_ID_NAMES_ENG \ @@ -9698,7 +10409,10 @@ enum MBG_EVT_IDS ENG_EVT_ID_NAME_FW_DELETED, \ ENG_EVT_ID_NAME_FW_ROLLBACK, \ ENG_EVT_ID_NAME_UFU_FLASHED, \ - ENG_EVT_ID_NAME_DATABASE_CONNECTED \ + ENG_EVT_ID_NAME_UFU_PROGRESS, \ + ENG_EVT_ID_NAME_DATABASE_CONNECTED, \ + ENG_EVT_ID_NAME_NTP_STATE_SYNC, \ + ENG_EVT_ID_NAME_FW_OSV \ } @@ -9770,6 +10484,11 @@ enum MBG_EVT_LVLS #define MBG_EVT_PTP_PORT_STATE_PASSIVE _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_PASSIVE, MBG_EVT_LVL_INFO ) #define MBG_EVT_PTP_PORT_STATE_UNCALIBRATED _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_UNCALIBRATED, MBG_EVT_LVL_INFO ) #define MBG_EVT_PTP_PORT_STATE_SLAVE _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_SLAVE, MBG_EVT_LVL_INFO ) +#define MBG_EVT_FW_ACTIVATED _mbg_mk_evt_code( MBG_EVT_ID_FW_ACTIVATED, MBG_EVT_LVL_INFO ) +#define MBG_EVT_DATABASE_CONNECTED _mbg_mk_evt_code( MBG_EVT_ID_DATABASE_CONNTECTED, MBG_EVT_LVL_INFO ) +#define MBG_EVT_NTP_STATE_SYNC _mbg_mk_evt_code( MBG_EVT_ID_NTP_STATE_SYNC, MBG_EVT_LVL_INFO ) +#define MBG_EVT_NTP_STATE_NOT_SYNC _mbg_mk_evt_code( MBG_EVT_ID_NTP_STATE_NOT_SYNC, MBG_EVT_LVL_WARN ) +#define MBG_EVT_FW_OSV _mbg_mk_evt_code( MBG_EVT_ID_FW_OSV, MBG_EVT_LVL_INFO ) /** @} anchor MBG_EVENT_CODES */ @@ -9787,13 +10506,13 @@ enum MBG_EVT_LVLS /** * @brief Generic state of an IMS device */ -typedef struct +typedef struct mbg_ims_state_s { 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; ///< see ::MBG_IMS_STATE_FLAG_MASKS + uint32_t flags; ///< See ::MBG_IMS_STATE_FLAG_MASKS } MBG_IMS_STATE; @@ -9826,7 +10545,7 @@ enum MBG_IMS_STATE_FLAG_BITS */ enum MBG_IMS_STATE_FLAG_MASKS { - MBG_IMS_STATE_FLAG_MSK_HAS_FDM = ( 1UL << MBG_IMS_STATE_FLAG_BIT_HAS_FDM ) ///< see ::MBG_IMS_STATE_FLAG_BIT_HAS_FDM + MBG_IMS_STATE_FLAG_MSK_HAS_FDM = ( 1UL << MBG_IMS_STATE_FLAG_BIT_HAS_FDM ) ///< See ::MBG_IMS_STATE_FLAG_BIT_HAS_FDM }; @@ -9834,7 +10553,7 @@ enum MBG_IMS_STATE_FLAG_MASKS /** * @brief Generic state of an IMS sensor */ -typedef struct +typedef struct mbg_ims_sensor_state_s { uint16_t type; ///< sensor type, see ::MBG_IMS_SENSORS uint16_t idx; ///< index of the sensor of this type @@ -9862,7 +10581,7 @@ do \ */ typedef struct { - uint32_t idx; ///< sensor index, 0..::MBG_IMS_STATE::num_sensors-1 + MBG_MSG_IDX_32 idx; ///< sensor index, 0..::MBG_IMS_STATE::num_sensors-1 MBG_IMS_SENSOR_STATE state; ///< sensor state } MBG_IMS_SENSOR_STATE_IDX; @@ -9957,7 +10676,7 @@ do \ * * @note This is only supported if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags */ -typedef struct +typedef struct mbg_ims_fdm_output_state_s { int32_t dac_val; ///< current DAC value, positive or negative uint32_t mode; ///< current output mode, see ::MBG_IMS_FDM_OUTPUT_MODES @@ -9986,7 +10705,7 @@ do \ */ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_IMS_FDM_OUTPUT_STATE state; } MBG_IMS_FDM_OUTPUT_STATE_IDX; @@ -10025,7 +10744,7 @@ do \ */ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_IMS_FDM_OUTPUT_SETTINGS settings; } MBG_IMS_FDM_OUTPUT_SETTINGS_IDX; @@ -10042,7 +10761,7 @@ do \ /** * @brief Specific output settings and limits. */ -typedef struct +typedef struct mbg_ims_fdm_output_info_s { MBG_IMS_FDM_OUTPUT_SETTINGS settings; ///< current settings uint32_t supp_modes; ///< supported modes, see ::MBG_IMS_FDM_OUTPUT_MODE_MASKS @@ -10065,7 +10784,7 @@ do \ */ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_IMS_FDM_OUTPUT_INFO info; } MBG_IMS_FDM_OUTPUT_INFO_IDX; @@ -10102,8 +10821,8 @@ enum MBG_IMS_FDM_OUTPUT_MODES */ enum MBG_IMS_FDM_OUTPUT_MODE_MASKS { - MBG_IMS_FDM_OUTPUT_MODE_MSK_FD = ( 1UL << MBG_IMS_FDM_OUTPUT_MODE_FD ), ///< see ::MBG_IMS_FDM_OUTPUT_MODE_FD - MBG_IMS_FDM_OUTPUT_MODE_MSK_TD = ( 1UL << MBG_IMS_FDM_OUTPUT_MODE_TD ) ///< see ::MBG_IMS_FDM_OUTPUT_MODE_TD + MBG_IMS_FDM_OUTPUT_MODE_MSK_FD = ( 1UL << MBG_IMS_FDM_OUTPUT_MODE_FD ), ///< See ::MBG_IMS_FDM_OUTPUT_MODE_FD + MBG_IMS_FDM_OUTPUT_MODE_MSK_TD = ( 1UL << MBG_IMS_FDM_OUTPUT_MODE_TD ) ///< See ::MBG_IMS_FDM_OUTPUT_MODE_TD }; @@ -10111,7 +10830,7 @@ enum MBG_IMS_FDM_OUTPUT_MODE_MASKS /** * @brief A generic structure used to specify FDM limits */ -typedef struct +typedef struct mbg_ims_fdm_limits_s { uint8_t n_outputs; ///< number of outputs per module uint8_t reserved_0; ///< reserved, currently always 0 @@ -10155,7 +10874,7 @@ do \ * @note This is only supported if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags. * */ -typedef struct +typedef struct mbg_ims_fdm_state_s { MBG_GPIO_FREQ freq; ///< Current frequency @@ -10206,9 +10925,9 @@ enum MBG_IMS_FDM_LINE_FREQS */ enum MBG_IMS_FDM_LINE_FREQ_MASKS { - MBG_IMS_FDM_LINE_FREQ_MSK_AUTO = ( 1UL << MBG_IMS_FDM_LINE_FREQ_AUTO ), ///< see ::MBG_IMS_FDM_LINE_FREQ_AUTO - MBG_IMS_FDM_LINE_FREQ_MSK_50HZ = ( 1UL << MBG_IMS_FDM_LINE_FREQ_50HZ ), ///< see ::MBG_IMS_FDM_LINE_FREQ_50HZ - MBG_IMS_FDM_LINE_FREQ_MSK_60HZ = ( 1UL << MBG_IMS_FDM_LINE_FREQ_60HZ ) ///< see ::MBG_IMS_FDM_LINE_FREQ_60HZ + MBG_IMS_FDM_LINE_FREQ_MSK_AUTO = ( 1UL << MBG_IMS_FDM_LINE_FREQ_AUTO ), ///< See ::MBG_IMS_FDM_LINE_FREQ_AUTO + MBG_IMS_FDM_LINE_FREQ_MSK_50HZ = ( 1UL << MBG_IMS_FDM_LINE_FREQ_50HZ ), ///< See ::MBG_IMS_FDM_LINE_FREQ_50HZ + MBG_IMS_FDM_LINE_FREQ_MSK_60HZ = ( 1UL << MBG_IMS_FDM_LINE_FREQ_60HZ ) ///< See ::MBG_IMS_FDM_LINE_FREQ_60HZ }; @@ -10245,10 +10964,10 @@ enum MBG_IMS_FDM_STATE_FLAG_BITS */ enum MBG_IMS_FDM_STATE_FLAG_MASKS { - MBG_IMS_FDM_STATE_FLAG_MSK_SYNC_AFTER_RESET = ( 1UL << MBG_IMS_FDM_STATE_FLAG_BIT_SYNC_AFTER_RESET ), ///< see ::MBG_IMS_FDM_STATE_FLAG_BIT_SYNC_AFTER_RESET - MBG_IMS_FDM_STATE_FLAG_MSK_PLT_IS_LOCKED = ( 1UL << MBG_IMS_FDM_STATE_FLAG_BIT_PLT_IS_LOCKED ), ///< see ::MBG_IMS_FDM_STATE_FLAG_BIT_PLT_IS_LOCKED - MBG_IMS_FDM_STATE_FLAG_MSK_FD_OVERFLOW = ( 1UL << MBG_IMS_FDM_STATE_FLAG_BIT_FD_OVERFLOW ), ///< see ::MBG_IMS_FDM_STATE_FLAG_BIT_FD_OVERFLOW - MBG_IMS_FDM_STATE_FLAG_MSK_TD_OVERFLOW = ( 1UL << MBG_IMS_FDM_STATE_FLAG_BIT_TD_OVERFLOW ) ///< see ::MBG_IMS_FDM_STATE_FLAG_BIT_TD_OVERFLOW + MBG_IMS_FDM_STATE_FLAG_MSK_SYNC_AFTER_RESET = ( 1UL << MBG_IMS_FDM_STATE_FLAG_BIT_SYNC_AFTER_RESET ), ///< See ::MBG_IMS_FDM_STATE_FLAG_BIT_SYNC_AFTER_RESET + MBG_IMS_FDM_STATE_FLAG_MSK_PLT_IS_LOCKED = ( 1UL << MBG_IMS_FDM_STATE_FLAG_BIT_PLT_IS_LOCKED ), ///< See ::MBG_IMS_FDM_STATE_FLAG_BIT_PLT_IS_LOCKED + MBG_IMS_FDM_STATE_FLAG_MSK_FD_OVERFLOW = ( 1UL << MBG_IMS_FDM_STATE_FLAG_BIT_FD_OVERFLOW ), ///< See ::MBG_IMS_FDM_STATE_FLAG_BIT_FD_OVERFLOW + MBG_IMS_FDM_STATE_FLAG_MSK_TD_OVERFLOW = ( 1UL << MBG_IMS_FDM_STATE_FLAG_BIT_TD_OVERFLOW ) ///< See ::MBG_IMS_FDM_STATE_FLAG_BIT_TD_OVERFLOW }; @@ -10305,7 +11024,7 @@ enum MBG_IMS_FDM_FLAGS */ enum MBG_IMS_FDM_FLAG_MASKS { - MBG_IMS_FDM_FLAG_MASK_CAN_SET_TDEV = ( 1UL << MBG_IMS_FDM_FLAG_CAN_SET_TDEV ) ///< see ::MBG_IMS_FDM_FLAG_CAN_SET_TDEV + MBG_IMS_FDM_FLAG_MASK_CAN_SET_TDEV = ( 1UL << MBG_IMS_FDM_FLAG_CAN_SET_TDEV ) ///< See ::MBG_IMS_FDM_FLAG_CAN_SET_TDEV }; @@ -10313,7 +11032,7 @@ enum MBG_IMS_FDM_FLAG_MASKS /** * @brief Specific FDM settings and limits. */ -typedef struct +typedef struct mbg_ims_fdm_info_s { MBG_IMS_FDM_SETTINGS settings; uint32_t supp_line_freqs; ///< Bit mask of supported line frequencies, see ::MBG_IMS_FDM_LINE_FREQ_MASKS @@ -10588,7 +11307,7 @@ typedef int16_t DAC_VAL; /** * @brief Satellite receiver status information */ -typedef struct +typedef struct stat_info_s { uint16_t mode; ///< Mode of operation, see ::RECEIVER_MODES uint16_t good_svs; ///< Numb. of satellites that can currently be received and used @@ -10615,6 +11334,90 @@ do \ /** + * @brief Bit masks for a legacy GPS SV status. + * + * Used with ::SV_INFO::stat_flags. + */ +enum SV_STAT_FLAG_MASKS +{ + SV_EXISTS = 0x0001, ///< The SV exists physically. + SV_IS_IN_VIEW = 0x0002, ///< SV should be visible at this moment. + SV_CAN_BE_RECEIVED = 0x0004, ///< SV can be tracked. + SV_MIGHT_BE_USED = 0x0008 ///< SV might be used. +}; + +/** + * @brief A combination of ::SV_STAT_FLAG_MASKS indicating an SV is "good". + * + * Used with ::SV_INFO::stat_flags. + */ +#define SV_IS_GOOD ( SV_EXISTS | SV_IS_IN_VIEW | SV_CAN_BE_RECEIVED | SV_MIGHT_BE_USED ) + + + +/** + * @brief A legacy satellite info structure. + * + * Used with pure GPS receivers. Newer GNSS receivers should + * support the ::GNSS_SV_STATUS structure. + * + * @see ::GNSS_SV_STATUS + */ +typedef struct sv_info_s +{ + SVNO svno; ///< The satellite number, ::MIN_SVNO_GPS...::MAX_SVNO_GPS. + int16_t stat_flags; ///< See ::SV_STAT_FLAG_MASKS. + int16_t elev; ///< Elevetion of the satellite [degrees]. + int16_t azim; ///< Azimuth of the satellite [degrees]. + int16_t doppler; ///< Doppler frequency of the satellite [Hz]. + int32_t est_dly; ///< Estimated signal propagation delay [100 ns units]. + int32_t cap_dly; ///< Measured signal propagation delay [100 ns units]. + +} SV_INFO; + + + +/** + * @brief Information on usage of a receiver channel. + * + * Used with pure GPS receivers. + * + * @note Very old GPS receivers which supported only 5 channels + * provided the ::CHANNEL_5 structure instead. + * + * @see ::CHANNEL_5 + */ +typedef struct +{ + int8_t num; ///< The receiver channel index, starting at 0. + int8_t svno; ///< The satellite number, ::MIN_SVNO_GPS...::MAX_SVNO_GPS. + int16_t doppler; ///< Doppler frequency of the satellite [Hz]. + int16_t elev; ///< Elevetion of the satellite [degrees]. + int16_t status; ///< 1: synchronized to data stream from satellite, else 0. + +} CHANNEL; + + + +/** + * @brief Information on usage of a receiver channel. + * + * Very old GPS receivers which supported only 5 channels + * provided this structure instead of the ::CHANNEL structure. + * + * @see ::CHANNEL + */ +typedef struct +{ + int8_t num; ///< The receiver channel index, starting at 0. + int8_t svno; ///< The satellite number, ::MIN_SVNO_GPS...::MAX_SVNO_GPS. + int16_t status; ///< 1: synchronized to data stream from satellite, else 0. + +} CHANNEL_5; + + + +/** * @brief An enumeration of known satellite navigation systems * * @see ::MBG_GNSS_TYPE_MASKS @@ -10640,13 +11443,13 @@ enum MBG_GNSS_TYPES */ enum MBG_GNSS_TYPE_MASKS { - 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 - MBG_GNSS_TYPE_MSK_QZSS = ( 1UL << GNSS_TYPE_QZSS ) ///< see ::GNSS_TYPE_QZSS + 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 + MBG_GNSS_TYPE_MSK_QZSS = ( 1UL << GNSS_TYPE_QZSS ) ///< See ::GNSS_TYPE_QZSS }; @@ -10677,7 +11480,7 @@ enum MBG_GNSS_TYPE_MASKS typedef struct { 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 + uint8_t prio[N_GNSS_MODE_PRIO]; ///< See ::MBG_GNSS_TYPES, unused fields set to 0xFF, idx 0 is highest prio uint32_t flags; ///< unused, currently always 0 (should be named MBG_GNSS_MODE_SETTINGS_FLAG_MASKS) } MBG_GNSS_MODE_SETTINGS; @@ -10710,7 +11513,6 @@ do \ } while ( 0 ) - /** * @brief Flag bits used to define ::MBG_GNSS_MODE_INFO_FLAG_MASKS * @@ -10722,6 +11524,8 @@ enum MBG_GNSS_MODE_INFO_FLAG_BITS MBG_GNSS_FLAG_HAS_PRIORITY, ///< Priority can be configured using the ::MBG_GNSS_MODE_SETTINGS::prio field MBG_GNSS_FLAG_SAT_INFO_IDX_SUPP_SER, ///< The ::GNSS_SAT_INFO_IDX structure is supported by the device MBG_GNSS_FLAG_HAS_SV_STATUS, ///< The ::GNSS_SV_STATUS_IDX structure is supported by the device + MBG_GNSS_FLAG_IS_MULTIBAND, ///< Indicates, that the receiver is a multiband receiver and therefore + ///< supports usage of any combination of GNSS types (even more than 3 types) N_MBG_GNSS_FLAGS }; @@ -10733,20 +11537,20 @@ enum MBG_GNSS_MODE_INFO_FLAG_BITS */ enum MBG_GNSS_MODE_INFO_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 - MBG_GNSS_FLAG_MSK_HAS_SV_STATUS = ( 1UL << MBG_GNSS_FLAG_HAS_SV_STATUS ) ///< see ::MBG_GNSS_FLAG_HAS_SV_STATUS + 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 + MBG_GNSS_FLAG_MSK_HAS_SV_STATUS = ( 1UL << MBG_GNSS_FLAG_HAS_SV_STATUS ), ///< See ::MBG_GNSS_FLAG_HAS_SV_STATUS + MBG_GNSS_FLAG_MSK_IS_MULTIBAND = ( 1UL << MBG_GNSS_FLAG_IS_MULTIBAND ) ///< See ::MBG_GNSS_FLAG_IS_MULTIBAND }; - #define MAX_USED_SATS 32 /** * @brief Satellite information for a particular GNSS type. */ -typedef struct +typedef struct gnss_sat_info_s { uint8_t gnss_type; ///< GNSS type as enumerated in ::MBG_GNSS_TYPES uint8_t reserved; ///< Reserved, currently always 0 @@ -10772,14 +11576,17 @@ do \ */ typedef struct { - /// GNSS system type index according to ::MBG_GNSS_MODE_INFO::supp_gnss_types. + /// @brief GNSS system type index according to ::MBG_GNSS_MODE_INFO::supp_gnss_types. + /// /// I.e., idx 0 corresponds to the GNSS system for which the least significant /// bit is set in ::MBG_GNSS_MODE_INFO::supp_gnss_types, idx 1 corresponds to - /// GNSS system for which the next higher bit is set, etc. This must *not* - /// necessarily match the sequence of the ::MBG_GNSS_TYPES enumeration. - uint16_t idx; + /// GNSS system for which the next higher bit is set, etc. + /// + /// @note This must ***not*** necessarily match the sequence + /// of the ::MBG_GNSS_TYPES enumeration. + MBG_MSG_IDX idx; - GNSS_SAT_INFO gnss_sat_info; ///< see ::GNSS_SAT_INFO + GNSS_SAT_INFO gnss_sat_info; ///< See ::GNSS_SAT_INFO } GNSS_SAT_INFO_IDX; @@ -10803,10 +11610,13 @@ do \ /** * @brief Detailed GNSS satellite status * + * @note Pure GPS receivers may only support the ::SV_INFO structure. + * * @see ::GNSS_SV_STATUS_IDX + * @see ::SV_INFO * @see @ref group_gnss_sv_stat_flags */ -typedef struct +typedef struct gnss_sv_status_s { uint8_t gnss_type; ///< GNSS type as enumerated in ::MBG_GNSS_TYPES uint8_t svno; ///< Satellite number, see ::TODO @@ -10906,6 +11716,16 @@ do \ ( ( (__stat_flags) & 0x00400000UL ) != 0 ) /// Bits 23 to 31 are reserved. +/// +/// However, we use the MSB (bit 31) here as a private extension +/// to indicate that the satellite can be received on two frequencies, +/// and the ionosphere correction is derived from the dual frequency +/// observation. +/// See ::_gnss_sv_stat_dual_freq +#define GNSS_SV_STAT_DUAL_FREQ_MSK 0x80000000UL + +#define _gnss_sv_stat_dual_freq( __stat_flags ) \ + ( ( (__stat_flags) & GNSS_SV_STAT_DUAL_FREQ_MSK ) != 0 ) /** @} defgroup group_gnss_sv_stat_flags */ @@ -10967,7 +11787,7 @@ enum GNSS_SV_STAT_ORBIT_SOURCES */ typedef struct { - uint32_t idx; ///< Range 0..::MBG_GNSS_MODE_INFO::n_sv_status-1 + MBG_MSG_IDX_32 idx; ///< Range 0..::MBG_GNSS_MODE_INFO::n_sv_status-1 GNSS_SV_STATUS gnss_sv_status; } GNSS_SV_STATUS_IDX; @@ -11028,7 +11848,7 @@ typedef uint16_t ANT_CABLE_LEN; /** * @brief The MAC address of a network interface */ -typedef struct +typedef struct mbg_mac_addr_s { uint8_t b[6]; @@ -11242,7 +12062,7 @@ typedef struct 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 + uint16_t flags; ///< See ::MBG_IP4_FLAG_MASKS MBG_VLAN_CFG vlan_cfg; ///< VLAN configuration } IP4_SETTINGS; @@ -11263,8 +12083,8 @@ do \ /** * @brief Simple LAN interface information * - * This structure can be retrieved from a device - * to check the device's capabilities. + * This structure can be obtained from a device + * to check the capabilities of the device. * * It is only supported if the flag ::GPS_HAS_LAN_IP4 is set * in ::RECEIVER_INFO::features. @@ -11279,7 +12099,7 @@ typedef struct 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 flags; ///< See ::MBG_IP4_FLAG_MASKS uint16_t rsvd_1; ///< reserved, currently always 0 } LAN_IF_INFO; @@ -11338,9 +12158,9 @@ enum MBG_IP4_FLAG_BITS */ enum MBG_IP4_FLAG_MASKS { - 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 + 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 */ @@ -11401,10 +12221,10 @@ enum MBG_NET_GLB_CFG_INFO_FLAGS */ enum MBG_NET_GLB_CFG_INFO_MASKS { - MBG_NET_GLB_SUPP_STAGE_2_MASK = (1UL << MBG_NET_GLB_SUPP_STAGE_2), ///< see ::MBG_NET_GLB_SUPP_STAGE_2 - MBG_NET_GLB_SUPP_BONDING_MASK = (1UL << MBG_NET_GLB_SUPP_BONDING), ///< see ::MBG_NET_GLB_SUPP_BONDING - MBG_NET_GLB_SUPP_ADD_CONF_MASK = (1UL << MBG_NET_GLB_SUPP_ADD_CONF), ///< see ::MBG_NET_GLB_SUPP_ADD_CONF - MBG_NET_GLB_SUPP_EXT_ROUTING_MASK = (1UL << MBG_NET_GLB_SUPP_EXT_ROUTING) ///< see ::MBG_NET_GLB_SUPP_EXT_ROUTING + MBG_NET_GLB_SUPP_STAGE_2_MASK = (1UL << MBG_NET_GLB_SUPP_STAGE_2), ///< See ::MBG_NET_GLB_SUPP_STAGE_2 + MBG_NET_GLB_SUPP_BONDING_MASK = (1UL << MBG_NET_GLB_SUPP_BONDING), ///< See ::MBG_NET_GLB_SUPP_BONDING + MBG_NET_GLB_SUPP_ADD_CONF_MASK = (1UL << MBG_NET_GLB_SUPP_ADD_CONF), ///< See ::MBG_NET_GLB_SUPP_ADD_CONF + MBG_NET_GLB_SUPP_EXT_ROUTING_MASK = (1UL << MBG_NET_GLB_SUPP_EXT_ROUTING) ///< See ::MBG_NET_GLB_SUPP_EXT_ROUTING }; @@ -11454,31 +12274,31 @@ enum MBG_NET_INTF_LINK_SPEED_MODES * * @anchor MBG_NET_INTF_LINK_SPEED_MODE_MASKS @{ */ -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_UNKNOWN ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_UNKNOWN ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_UNKNOWN -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10_T_HALF ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10_T_HALF ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_10_T_HALF -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10_T_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10_T_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_10_T_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_100_T_HALF ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_100_T_HALF ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_100_T_HALF -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_100_T_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_100_T_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_100_T_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_1000_T_HALF ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_1000_T_HALF ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_1000_T_HALF -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_1000_T_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_1000_T_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_1000_T_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_1000_KX_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_1000_KX_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_1000_KX_FULL - -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_2500_X_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_2500_X_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_2500_X_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10000_T_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10000_T_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_10000_T_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10000_KX4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10000_KX4_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_10000_KX4_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10000_KR_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10000_KR_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_10000_KR_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10000_R_FEC ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10000_R_FEC ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_10000_R_FEC -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_20000_MLD2_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_20000_MLD2_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_20000_MLD2_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_20000_KR2_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_20000_KR2_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_20000_KR2_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_40000_KR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_40000_KR4_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_40000_KR4_FULL - -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_40000_CR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_40000_CR4_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_40000_CR4_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_40000_SR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_40000_SR4_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_40000_SR4_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_40000_LR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_40000_LR4_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_40000_LR4_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_56000_KR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_56000_KR4_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_56000_KR4_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_56000_CR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_56000_CR4_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_56000_CR4_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_56000_SR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_56000_SR4_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_56000_SR4_FULL -#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_56000_LR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_56000_LR4_FULL ) ///< see ::MBG_NET_INTF_LINK_SPEED_MODE_56000_LR4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_UNKNOWN ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_UNKNOWN ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_UNKNOWN +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10_T_HALF ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10_T_HALF ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_10_T_HALF +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10_T_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10_T_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_10_T_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_100_T_HALF ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_100_T_HALF ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_100_T_HALF +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_100_T_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_100_T_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_100_T_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_1000_T_HALF ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_1000_T_HALF ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_1000_T_HALF +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_1000_T_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_1000_T_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_1000_T_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_1000_KX_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_1000_KX_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_1000_KX_FULL + +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_2500_X_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_2500_X_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_2500_X_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10000_T_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10000_T_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_10000_T_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10000_KX4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10000_KX4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_10000_KX4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10000_KR_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10000_KR_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_10000_KR_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10000_R_FEC ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10000_R_FEC ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_10000_R_FEC +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_20000_MLD2_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_20000_MLD2_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_20000_MLD2_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_20000_KR2_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_20000_KR2_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_20000_KR2_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_40000_KR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_40000_KR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_40000_KR4_FULL + +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_40000_CR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_40000_CR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_40000_CR4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_40000_SR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_40000_SR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_40000_SR4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_40000_LR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_40000_LR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_40000_LR4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_56000_KR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_56000_KR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_56000_KR4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_56000_CR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_56000_CR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_56000_CR4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_56000_SR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_56000_SR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_56000_SR4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_56000_LR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_56000_LR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_56000_LR4_FULL /** @} anchor MBG_NET_INTF_LINK_SPEED_MODE_MASKS */ @@ -11530,13 +12350,13 @@ enum MBG_NET_INTF_LINK_PORT_TYPES */ enum MBG_NET_INTF_LINK_PORT_TYPE_MASKS { - MBG_NET_INTF_LINK_PORT_TYPE_MASK_UNKNOWN = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_UNKNOWN ), ///< see ::MBG_NET_INTF_LINK_PORT_TYPE_UNKNOWN - MBG_NET_INTF_LINK_PORT_TYPE_MASK_TP = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_TP ), ///< see ::MBG_NET_INTF_LINK_PORT_TYPE_TP - MBG_NET_INTF_LINK_PORT_TYPE_MASK_FIBRE = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_FIBRE ), ///< see ::MBG_NET_INTF_LINK_PORT_TYPE_FIBRE - MBG_NET_INTF_LINK_PORT_TYPE_MASK_BNC = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_BNC ), ///< see ::MBG_NET_INTF_LINK_PORT_TYPE_BNC - MBG_NET_INTF_LINK_PORT_TYPE_MASK_AUI = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_AUI ), ///< see ::MBG_NET_INTF_LINK_PORT_TYPE_AUI - MBG_NET_INTF_LINK_PORT_TYPE_MASK_MII = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_MII ), ///< see ::MBG_NET_INTF_LINK_PORT_TYPE_MII - MBG_NET_INTF_LINK_PORT_TYPE_MASK_DA = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_DA ) ///< see ::MBG_NET_INTF_LINK_PORT_TYPE_DA + MBG_NET_INTF_LINK_PORT_TYPE_MASK_UNKNOWN = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_UNKNOWN ), ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_UNKNOWN + MBG_NET_INTF_LINK_PORT_TYPE_MASK_TP = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_TP ), ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_TP + MBG_NET_INTF_LINK_PORT_TYPE_MASK_FIBRE = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_FIBRE ), ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_FIBRE + MBG_NET_INTF_LINK_PORT_TYPE_MASK_BNC = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_BNC ), ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_BNC + MBG_NET_INTF_LINK_PORT_TYPE_MASK_AUI = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_AUI ), ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_AUI + MBG_NET_INTF_LINK_PORT_TYPE_MASK_MII = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_MII ), ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_MII + MBG_NET_INTF_LINK_PORT_TYPE_MASK_DA = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_DA ) ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_DA }; @@ -11575,7 +12395,6 @@ enum MBG_NET_INTF_LINK_PORT_TYPE_MASKS } - /** * @brief Network interface link state bits * @@ -11623,27 +12442,27 @@ enum MBG_NET_INTF_LINK_STATE_BITS * * @anchor MBG_NET_INTF_LINK_STATE_MASKS @{ */ -#define MBG_NET_INTF_LINK_STATE_MASK_UP ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_UP ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_UP -#define MBG_NET_INTF_LINK_STATE_MASK_RUNNING ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_RUNNING ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_RUNNING -#define MBG_NET_INTF_LINK_STATE_MASK_LOWER_UP ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_LOWER_UP ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_LOWER_UP -#define MBG_NET_INTF_LINK_STATE_MASK_DORMANT ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_DORMANT ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_DORMANT -#define MBG_NET_INTF_LINK_STATE_MASK_BROADCAST ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_BROADCAST ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_BROADCAST -#define MBG_NET_INTF_LINK_STATE_MASK_MULTICAST ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_MULTICAST ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_MULTICAST -#define MBG_NET_INTF_LINK_STATE_MASK_ALL_MULTI ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_ALL_MULTI ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_ALL_MULTI -#define MBG_NET_INTF_LINK_STATE_MASK_DEBUG ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_DEBUG ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_DEBUG - -#define MBG_NET_INTF_LINK_STATE_MASK_LOOPBACK ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_LOOPBACK ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_LOOPBACK -#define MBG_NET_INTF_LINK_STATE_MASK_POINT_TO_POINT ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_POINT_TO_POINT ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_POINT_TO_POINT -#define MBG_NET_INTF_LINK_STATE_MASK_NO_ARP ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_NO_ARP ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_NO_ARP -#define MBG_NET_INTF_LINK_STATE_MASK_PROMISC ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_PROMISC ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_PROMISC -#define MBG_NET_INTF_LINK_STATE_MASK_MASTER ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_MASTER ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_MASTER -#define MBG_NET_INTF_LINK_STATE_MASK_SLAVE ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_SLAVE ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_SLAVE -#define MBG_NET_INTF_LINK_STATE_MASK_PORT_SEL ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_PORT_SEL ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_PORT_SEL -#define MBG_NET_INTF_LINK_STATE_MASK_AUTO_MEDIA ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_AUTO_MEDIA ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_AUTO_MEDIA - -#define MBG_NET_INTF_LINK_STATE_MASK_ECHO ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_ECHO ) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_ECHO -#define MBG_NET_INTF_LINK_STATE_MASK_DYNAMIC ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_DYNAMIC) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_DYNAMIC -#define MBG_NET_INTF_LINK_STATE_MASK_NO_TRAILERS ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_NO_TRAILERS) ///< see ::MBG_NET_INTF_LINK_STATE_BIT_NO_TRAILERS +#define MBG_NET_INTF_LINK_STATE_MASK_UP ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_UP ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_UP +#define MBG_NET_INTF_LINK_STATE_MASK_RUNNING ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_RUNNING ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_RUNNING +#define MBG_NET_INTF_LINK_STATE_MASK_LOWER_UP ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_LOWER_UP ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_LOWER_UP +#define MBG_NET_INTF_LINK_STATE_MASK_DORMANT ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_DORMANT ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_DORMANT +#define MBG_NET_INTF_LINK_STATE_MASK_BROADCAST ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_BROADCAST ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_BROADCAST +#define MBG_NET_INTF_LINK_STATE_MASK_MULTICAST ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_MULTICAST ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_MULTICAST +#define MBG_NET_INTF_LINK_STATE_MASK_ALL_MULTI ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_ALL_MULTI ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_ALL_MULTI +#define MBG_NET_INTF_LINK_STATE_MASK_DEBUG ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_DEBUG ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_DEBUG + +#define MBG_NET_INTF_LINK_STATE_MASK_LOOPBACK ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_LOOPBACK ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_LOOPBACK +#define MBG_NET_INTF_LINK_STATE_MASK_POINT_TO_POINT ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_POINT_TO_POINT ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_POINT_TO_POINT +#define MBG_NET_INTF_LINK_STATE_MASK_NO_ARP ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_NO_ARP ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_NO_ARP +#define MBG_NET_INTF_LINK_STATE_MASK_PROMISC ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_PROMISC ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_PROMISC +#define MBG_NET_INTF_LINK_STATE_MASK_MASTER ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_MASTER ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_MASTER +#define MBG_NET_INTF_LINK_STATE_MASK_SLAVE ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_SLAVE ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_SLAVE +#define MBG_NET_INTF_LINK_STATE_MASK_PORT_SEL ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_PORT_SEL ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_PORT_SEL +#define MBG_NET_INTF_LINK_STATE_MASK_AUTO_MEDIA ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_AUTO_MEDIA ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_AUTO_MEDIA + +#define MBG_NET_INTF_LINK_STATE_MASK_ECHO ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_ECHO ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_ECHO +#define MBG_NET_INTF_LINK_STATE_MASK_DYNAMIC ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_DYNAMIC) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_DYNAMIC +#define MBG_NET_INTF_LINK_STATE_MASK_NO_TRAILERS ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_NO_TRAILERS) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_NO_TRAILERS /** @} anchor MBG_NET_INTF_LINK_STATE_MASKS */ @@ -11662,6 +12481,9 @@ enum MBG_NET_INTF_LINK_OPTS MBG_NET_INTF_LINK_OPT_CAN_AUTONEG, MBG_NET_INTF_LINK_OPT_CAN_NTP_HW_TS, MBG_NET_INTF_LINK_OPT_CAN_PTP_HW_TS, + MBG_NET_INTF_LINK_OPT_HAS_NTP_LIC, ///< Indicates, that the physical interface has a license for number of NTP clients + MBG_NET_INTF_LINK_OPT_HAS_PTP_LIC, ///< Indicates, that the physical interface has a license for number of PTP clients + MBG_NET_INTF_LINK_OPT_HAS_SYNCE_STATUS, N_MBG_NET_INTF_LINK_OPTS }; @@ -11674,12 +12496,15 @@ enum MBG_NET_INTF_LINK_OPTS */ enum MBG_NET_INTF_LINK_OPT_MASKS { - MBG_NET_INTF_LINK_OPT_MASK_CAN_SET_MAC = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_SET_MAC ), ///< see ::MBG_NET_INTF_LINK_OPT_CAN_SET_MAC - MBG_NET_INTF_LINK_OPT_MASK_CAN_SYNCE_IN = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_SYNCE_IN ), ///< see ::MBG_NET_INTF_LINK_OPT_CAN_SYNCE_IN - MBG_NET_INTF_LINK_OPT_MASK_CAN_SYNCE_OUT = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_SYNCE_OUT ), ///< see ::MBG_NET_INTF_LINK_OPT_CAN_SYNCE_OUT - MBG_NET_INTF_LINK_OPT_MASK_CAN_AUTONEG = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_AUTONEG ), ///< see ::MBG_NET_INTF_LINK_OPT_CAN_AUTONEG - MBG_NET_INTF_LINK_OPT_MASK_CAN_NTP_HW_TS = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_NTP_HW_TS ), ///< see ::MBG_NET_INTF_LINK_OPT_CAN_NTP_HW_TS - MBG_NET_INTF_LINK_OPT_MASK_CAN_PTP_HW_TS = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_PTP_HW_TS ) ///< see ::MBG_NET_INTF_LINK_OPT_CAN_PTP_HW_TS + MBG_NET_INTF_LINK_OPT_MASK_CAN_SET_MAC = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_SET_MAC ), ///< See ::MBG_NET_INTF_LINK_OPT_CAN_SET_MAC + MBG_NET_INTF_LINK_OPT_MASK_CAN_SYNCE_IN = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_SYNCE_IN ), ///< See ::MBG_NET_INTF_LINK_OPT_CAN_SYNCE_IN + MBG_NET_INTF_LINK_OPT_MASK_CAN_SYNCE_OUT = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_SYNCE_OUT ), ///< See ::MBG_NET_INTF_LINK_OPT_CAN_SYNCE_OUT + MBG_NET_INTF_LINK_OPT_MASK_CAN_AUTONEG = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_AUTONEG ), ///< See ::MBG_NET_INTF_LINK_OPT_CAN_AUTONEG + MBG_NET_INTF_LINK_OPT_MASK_CAN_NTP_HW_TS = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_NTP_HW_TS ), ///< See ::MBG_NET_INTF_LINK_OPT_CAN_NTP_HW_TS + MBG_NET_INTF_LINK_OPT_MASK_CAN_PTP_HW_TS = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_PTP_HW_TS ), ///< See ::MBG_NET_INTF_LINK_OPT_CAN_PTP_HW_TS + MBG_NET_INTF_LINK_OPT_MASK_HAS_NTP_LIC = ( 1UL << MBG_NET_INTF_LINK_OPT_HAS_NTP_LIC ), ///< See ::MBG_NET_INTF_LINK_OPT_HAS_NTP_LIC + MBG_NET_INTF_LINK_OPT_MASK_HAS_PTP_LIC = ( 1UL << MBG_NET_INTF_LINK_OPT_HAS_PTP_LIC ), ///< See ::MBG_NET_INTF_LINK_OPT_HAS_PTP_LIC + MBG_NET_INTF_LINK_OPT_MASK_HAS_SYNCE_STATUS = ( 1UL << MBG_NET_INTF_LINK_OPT_HAS_SYNCE_STATUS ) ///< See ::MBG_NET_INTF_LINK_OPT_HAS_SYNCE_STATUS }; @@ -11714,13 +12539,13 @@ enum MBG_NET_INTF_LINK_BOND_MODES */ enum MBG_NET_INTF_LINK_BOND_MODE_MASKS { - MBG_NET_INTF_LINK_BOND_MODE_MASK_ROUNDROBIN = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_ROUNDROBIN ), ///< see ::MBG_NET_INTF_LINK_BOND_MODE_ROUNDROBIN - MBG_NET_INTF_LINK_BOND_MODE_MASK_ACTIVEBACKUP = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_ACTIVEBACKUP ), ///< see ::MBG_NET_INTF_LINK_BOND_MODE_ACTIVEBACKUP - MBG_NET_INTF_LINK_BOND_MODE_MASK_XOR = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_XOR ), ///< see ::MBG_NET_INTF_LINK_BOND_MODE_XOR - MBG_NET_INTF_LINK_BOND_MODE_MASK_BROADCAST = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_BROADCAST ), ///< see ::MBG_NET_INTF_LINK_BOND_MODE_BROADCAST - MBG_NET_INTF_LINK_BOND_MODE_MASK_8023AD = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_8023AD ), ///< see ::MBG_NET_INTF_LINK_BOND_MODE_8023AD - MBG_NET_INTF_LINK_BOND_MODE_MASK_TLB = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_TLB ), ///< see ::MBG_NET_INTF_LINK_BOND_MODE_TLB - MBG_NET_INTF_LINK_BOND_MODE_MASK_ALB = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_ALB ), ///< see ::MBG_NET_INTF_LINK_BOND_MODE_ALB + MBG_NET_INTF_LINK_BOND_MODE_MASK_ROUNDROBIN = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_ROUNDROBIN ), ///< See ::MBG_NET_INTF_LINK_BOND_MODE_ROUNDROBIN + MBG_NET_INTF_LINK_BOND_MODE_MASK_ACTIVEBACKUP = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_ACTIVEBACKUP ), ///< See ::MBG_NET_INTF_LINK_BOND_MODE_ACTIVEBACKUP + MBG_NET_INTF_LINK_BOND_MODE_MASK_XOR = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_XOR ), ///< See ::MBG_NET_INTF_LINK_BOND_MODE_XOR + MBG_NET_INTF_LINK_BOND_MODE_MASK_BROADCAST = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_BROADCAST ), ///< See ::MBG_NET_INTF_LINK_BOND_MODE_BROADCAST + MBG_NET_INTF_LINK_BOND_MODE_MASK_8023AD = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_8023AD ), ///< See ::MBG_NET_INTF_LINK_BOND_MODE_8023AD + MBG_NET_INTF_LINK_BOND_MODE_MASK_TLB = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_TLB ), ///< See ::MBG_NET_INTF_LINK_BOND_MODE_TLB + MBG_NET_INTF_LINK_BOND_MODE_MASK_ALB = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_ALB ), ///< See ::MBG_NET_INTF_LINK_BOND_MODE_ALB }; @@ -11781,9 +12606,9 @@ enum MBG_NET_INTF_LINK_TYPES */ enum MBG_NET_INTF_LINK_TYPE_MASKS { - MBG_NET_INTF_LINK_TYPE_MASK_PHYS = ( 1UL << MBG_NET_INTF_LINK_TYPE_PHYS ), ///< see ::MBG_NET_INTF_LINK_TYPE_PHYS - MBG_NET_INTF_LINK_TYPE_MASK_VLAN = ( 1UL << MBG_NET_INTF_LINK_TYPE_VLAN ), ///< see ::MBG_NET_INTF_LINK_TYPE_VLAN - MBG_NET_INTF_LINK_TYPE_MASK_BOND = ( 1UL << MBG_NET_INTF_LINK_TYPE_BOND ) ///< see ::MBG_NET_INTF_LINK_TYPE_BOND + MBG_NET_INTF_LINK_TYPE_MASK_PHYS = ( 1UL << MBG_NET_INTF_LINK_TYPE_PHYS ), ///< See ::MBG_NET_INTF_LINK_TYPE_PHYS + MBG_NET_INTF_LINK_TYPE_MASK_VLAN = ( 1UL << MBG_NET_INTF_LINK_TYPE_VLAN ), ///< See ::MBG_NET_INTF_LINK_TYPE_VLAN + MBG_NET_INTF_LINK_TYPE_MASK_BOND = ( 1UL << MBG_NET_INTF_LINK_TYPE_BOND ) ///< See ::MBG_NET_INTF_LINK_TYPE_BOND }; @@ -11811,9 +12636,9 @@ enum MBG_NET_INTF_ADDR_BITS */ enum MBG_NET_INTF_ADDR_MASKS { - MBG_NET_INTF_ADDR_MASK_DHCP4 = ( 1UL << MBG_NET_INTF_ADDR_BIT_DHCP4 ), ///< see ::MBG_NET_INTF_ADDR_BIT_DHCP4 - MBG_NET_INTF_ADDR_MASK_DHCP6 = ( 1UL << MBG_NET_INTF_ADDR_BIT_DHCP6 ), ///< see ::MBG_NET_INTF_ADDR_BIT_DHCP6 - MBG_NET_INTF_ADDR_MASK_AUTOCONF = ( 1UL << MBG_NET_INTF_ADDR_BIT_AUTOCONF ) ///< see ::MBG_NET_INTF_ADDR_BIT_AUTOCONF + MBG_NET_INTF_ADDR_MASK_DHCP4 = ( 1UL << MBG_NET_INTF_ADDR_BIT_DHCP4 ), ///< See ::MBG_NET_INTF_ADDR_BIT_DHCP4 + MBG_NET_INTF_ADDR_MASK_DHCP6 = ( 1UL << MBG_NET_INTF_ADDR_BIT_DHCP6 ), ///< See ::MBG_NET_INTF_ADDR_BIT_DHCP6 + MBG_NET_INTF_ADDR_MASK_AUTOCONF = ( 1UL << MBG_NET_INTF_ADDR_BIT_AUTOCONF ) ///< See ::MBG_NET_INTF_ADDR_BIT_AUTOCONF }; @@ -11903,9 +12728,9 @@ do \ /** * @brief An IPv4 or IPv6 network address */ -typedef struct +typedef struct mbg_ip_addr_s { - uint8_t type; ///< see ::MBG_IP_ADDR_TYPES + 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 @@ -11944,7 +12769,7 @@ do \ */ typedef struct { - uint16_t idx; + MBG_MSG_IDX idx; MBG_IP_ADDR addr; ///< network address } MBG_IP_ADDR_IDX; @@ -11962,7 +12787,7 @@ do \ */ typedef struct { - MBG_IP_ADDR addr; ///< see ::MBG_IP_ADDR + MBG_IP_ADDR addr; ///< See ::MBG_IP_ADDR uint16_t port; ///< UDP or TCP port uint16_t flags; ///< currently always 0 @@ -12002,7 +12827,7 @@ do \ */ typedef struct { - uint16_t idx; + MBG_MSG_IDX idx; MBG_NET_NAME net_name; } MBG_NET_NAME_IDX; @@ -12015,48 +12840,84 @@ do \ } while ( 0 ) +enum MBG_NET_INTF_SYNC_E_FLAGS +{ + MBG_NET_INTF_SYNC_E_FLAG_SYNC_E_ACTIVE, ///< Indicates, whether SyncE is activated + MBG_NET_INTF_SYNC_E_FLAG_SYNC_E_AUTO_QL, ///< Indicates, whether the quality level is determined automatically, + ///< otherwise, the fixed input/output SSMs are being used + N_MBG_NET_INTF_SYNC_E_FLAGS + +}; + + +enum MBG_NET_INTF_SYNC_E_FLAG_MASKS +{ + MBG_NET_INTF_SYNC_E_FLAG_MASK_SYNC_E_ACTIVE = ( 1UL << MBG_NET_INTF_SYNC_E_FLAG_SYNC_E_ACTIVE ), ///< See ::MBG_NET_INTF_SYNC_E_FLAG_SYNC_E_ACTIVE + MBG_NET_INTF_SYNC_E_FLAG_MASK_SYNC_E_AUTO_QL = ( 1UL << MBG_NET_INTF_SYNC_E_FLAG_SYNC_E_AUTO_QL ) ///< See ::MBG_NET_INTF_SYNC_E_FLAG_SYNC_E_AUTO_QL + +}; + + +typedef struct +{ + uint8_t flags; ///< SyncE flags, see ::MBG_NET_INTF_SYNC_E_FLAG_MASKS + uint8_t min_input_ssm; ///< minimum accepted SSM-QL as synchronization input + uint8_t fixed_input_ssm; ///< assumed SSM value for SyncE input (0xFF if taken from network) + ///< or currently incoming SSM in status structs + uint8_t fixed_output_ssm; ///< Fixed SSM output override + + uint8_t current_output_ssm; ///< current quality level for SyncE output (automatically assigned or fixed) + ///< or currently outgoing SSM in status structs + uint8_t sdh_net_opt; ///< SDH network option, see ::SDH_NETWORK_OPTIONS and ::MBG_NET_INTF_LINK_INFO::supp_sdh_net_opts + uint8_t gb_copper_mode; ///< GBit link copper mode, see ::GBIT_LINK_COPPER_MODES and ::MBG_NET_INTF_LINK_INFO::supp_gb_copper_modes + uint8_t local_priority; ///< user defined priority value (0-255) + +} MBG_NET_INTF_SYNC_E_SETTINGS; + /** * @brief Physical network interface link specific settings */ typedef struct { - char name[MBG_IFNAMSIZ]; ///< Interface name - MBG_MAC_ADDR mac_addr; ///< Physical hardware address - MBG_MAC_ADDR broadcast; ///< Physical broadcast address + char name[MBG_IFNAMSIZ]; ///< Interface name + MBG_MAC_ADDR mac_addr; ///< Physical hardware address + MBG_MAC_ADDR broadcast; ///< Physical broadcast address - uint32_t if_index; ///< Interface index assigned by the kernel - uint32_t common_if_index; ///< Common interface index assigned by the lib (associated with the MAC address), - ///< Valid if ::MBG_NET_INTF_LINK_SETTINGS::type is ::MBG_NET_INTF_LINK_TYPE_PHYS - uint32_t ass_if_index; ///< Interface index of the associated physical interface link, - ///< Valid if ::MBG_NET_INTF_LINK_SETTINGS::type is ::MBG_NET_INTF_LINK_TYPE_VLAN + uint32_t if_index; ///< Interface index assigned by the kernel + uint32_t common_if_index; ///< Common interface index assigned by the lib (associated with the MAC address), + ///< Valid if ::MBG_NET_INTF_LINK_SETTINGS::type is ::MBG_NET_INTF_LINK_TYPE_PHYS + uint32_t ass_if_index; ///< Interface index of the associated physical interface link, + ///< Valid if ::MBG_NET_INTF_LINK_SETTINGS::type is ::MBG_NET_INTF_LINK_TYPE_VLAN - uint32_t flags; ///< Reserved, currently 0 - uint32_t states; ///< see @ref MBG_NET_INTF_LINK_STATE_MASKS + uint32_t reserved_1; ///< Reserved, currently 0 + uint32_t states; ///< see @ref MBG_NET_INTF_LINK_STATE_MASKS - uint32_t hw_type; ///< Hardware type of interface (see ::MBG_NET_HW_TYPES) - uint32_t mtu; ///< Max. packet size in bytes - uint32_t txqlen; ///< Transmission queue length (number of packets) - uint32_t speed; ///< Link speed in MBit/s + uint32_t hw_type; ///< Hardware type of interface (see ::MBG_NET_HW_TYPES) + uint32_t mtu; ///< Max. packet size in bytes + uint32_t txqlen; ///< Transmission queue length (number of packets) + uint32_t speed; ///< Link speed in MBit/s - uint8_t type; ///< see ::MBG_NET_INTF_LINK_TYPES - uint8_t duplex; ///< Duplex mode, half (0) or full (1) - uint8_t autoneg; ///< Indicates, whether autonegotiation is enabled or disabled - uint8_t port_type; ///< see ::MBG_NET_INTF_LINK_PORT_TYPES + uint8_t type; ///< See ::MBG_NET_INTF_LINK_TYPES + uint8_t duplex; ///< Duplex mode, half (0) or full (1) + uint8_t autoneg; ///< Indicates, whether autonegotiation is enabled or disabled + uint8_t port_type; ///< See ::MBG_NET_INTF_LINK_PORT_TYPES - uint8_t bond_mode; ///< Bonding mode, see ::MBG_NET_INTF_LINK_BOND_MODES - ///< Valid if ::MBG_NET_INTF_LINK_STATE_MASK_MASTER is set in ::MBG_NET_INTF_LINK_SETTINGS::states - uint8_t bond_state; ///< Status of this interface in the bonding group, see ::MBG_NET_INTF_LINK_BOND_STATES - ///< Valid if MBG_NET_INTF_LINK_STATE_MASK_SLAVE is set in ::MBG_NET_INTF_LINK_SETTINGS::states - uint16_t bond_idx; ///< Interface index of the bonding master link, see ::MBG_NET_INTF_LINK_SETTINGS::if_index - ///< Valid, if MBG_NET_INTF_LINK_STATE_MASK_SLAVE is set in ::MBG_NET_INTF_LINK_SETTINGS::states + uint8_t bond_mode; ///< Bonding mode, see ::MBG_NET_INTF_LINK_BOND_MODES + ///< Valid if ::MBG_NET_INTF_LINK_STATE_MASK_MASTER is set in ::MBG_NET_INTF_LINK_SETTINGS::states + uint8_t bond_state; ///< Status of this interface in the bonding group, see ::MBG_NET_INTF_LINK_BOND_STATES + ///< Valid if MBG_NET_INTF_LINK_STATE_MASK_SLAVE is set in ::MBG_NET_INTF_LINK_SETTINGS::states + uint16_t bond_idx; ///< Interface index of the bonding master link, see ::MBG_NET_INTF_LINK_SETTINGS::if_index + ///< Valid, if MBG_NET_INTF_LINK_STATE_MASK_SLAVE is set in ::MBG_NET_INTF_LINK_SETTINGS::states - uint16_t vlan_cfg; ///< VLAN configuration options, see ::MBG_VLAN_CFG - ///< Valid if ::MBG_NET_INTF_LINK_SETTINGS::type is ::MBG_NET_INTF_LINK_TYPE_VLAN - uint16_t reserved_1; ///< Reserved, currently 0 + uint16_t vlan_cfg; ///< VLAN configuration options, see ::MBG_VLAN_CFG + ///< Valid if ::MBG_NET_INTF_LINK_SETTINGS::type is ::MBG_NET_INTF_LINK_TYPE_VLAN + uint16_t reserved_2; ///< Reserved, currently 0 - uint32_t reserved_2; ///< Reserved, currently 0 - uint32_t reserved_3; ///< Reserved, currently 0 + MBG_NET_INTF_SYNC_E_SETTINGS sync_e; ///< SyncE settings for this port, only valid if ::MBG_NET_INTF_LINK_OPT_MASK_CAN_SYNCE_IN or + ///< ::MBG_NET_INTF_LINK_OPT_MASK_CAN_SYNCE_OUT is set in ::MBG_NET_INTF_LINK_INFO::supp_opts + ///< For network status structs, this can also be the SyncE status, if ::MBG_NET_INTF_LINK_OPT_HAS_SYNCE_STATUS + ///< is set in ::MBG_NET_INTF_LINK_INFO::supp_opts } MBG_NET_INTF_LINK_SETTINGS; @@ -12086,7 +12947,7 @@ do \ */ typedef struct { - uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_INFO::n_supp_intf_link-1 + MBG_MSG_IDX idx; ///< 0..::MBG_NET_GLB_CFG_INFO::n_supp_intf_link-1. MBG_NET_INTF_LINK_SETTINGS settings; } MBG_NET_INTF_LINK_SETTINGS_IDX; @@ -12105,35 +12966,39 @@ do \ */ typedef struct { - MBG_NET_INTF_LINK_SETTINGS link_settings; ///< see ::MBG_NET_INTF_LINK_SETTINGS - uint32_t supp_flags; ///< Reserved, currently 0 - uint32_t supp_states; ///< see @ref MBG_NET_INTF_LINK_STATE_MASKS - uint32_t supp_types; ///< see ::MBG_NET_INTF_LINK_TYPE_MASKS - uint32_t supp_speed_modes; ///< see @ref MBG_NET_INTF_LINK_SPEED_MODE_MASKS - uint32_t supp_port_types; ///< see ::MBG_NET_INTF_LINK_PORT_TYPE_MASKS - uint32_t supp_opts; ///< see ::MBG_NET_INTF_LINK_OPT_MASKS - uint32_t supp_bond_modes; ///< see ::MBG_NET_INTF_LINK_BOND_MODE_MASKS + MBG_NET_INTF_LINK_SETTINGS link_settings; ///< See ::MBG_NET_INTF_LINK_SETTINGS + uint16_t supp_sdh_net_opts; ///< supported SDH network options for SyncE, see ::SDH_NETWORK_OPTION_MASKS + uint16_t supp_gb_copper_modes; ///< supported GBit link copper modes for SyncE, see ::GBIT_LINK_COPPER_MODE_MASKS + uint32_t supp_states; ///< see @ref MBG_NET_INTF_LINK_STATE_MASKS + uint32_t supp_types; ///< See ::MBG_NET_INTF_LINK_TYPE_MASKS + uint32_t supp_speed_modes; ///< see @ref MBG_NET_INTF_LINK_SPEED_MODE_MASKS + uint32_t supp_port_types; ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_MASKS + uint32_t supp_opts; ///< See ::MBG_NET_INTF_LINK_OPT_MASKS + uint32_t supp_bond_modes; ///< See ::MBG_NET_INTF_LINK_BOND_MODE_MASKS + uint16_t lic_ntp_clients; ///< number of supported NTP clients, only valid if ::MBG_NET_INTF_LINK_OPT_MASK_HAS_NTP_LIC + uint16_t lic_ptp_clients; ///< number of supported PTP clients, only valid if ::MBG_NET_INTF_LINK_OPT_MASK_HAS_PTP_LIC uint32_t reserved_1; uint32_t reserved_2; uint32_t reserved_3; - uint32_t reserved_4; } MBG_NET_INTF_LINK_INFO; #define _mbg_swab_net_intf_link_info( _p ) \ do \ { \ _mbg_swab_net_intf_link_settings( &(_p)->link_settings ); \ - _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab16( &(_p)->supp_sdh_net_opts ); \ + _mbg_swab16( &(_p)->supp_gb_copper_mds ); \ _mbg_swab32( &(_p)->supp_states ); \ _mbg_swab32( &(_p)->supp_types ); \ _mbg_swab32( &(_p)->supp_speed_modes ); \ _mbg_swab32( &(_p)->supp_port_types ); \ _mbg_swab32( &(_p)->supp_opts ); \ _mbg_swab32( &(_p)->supp_bond_modes ); \ + _mbg_swab16( &(_p)->lic_ntp_clients ); \ + _mbg_swab16( &(_p)->lic_ptp_clients ); \ _mbg_swab32( &(_p)->reserved_1 ); \ _mbg_swab32( &(_p)->reserved_2 ); \ _mbg_swab32( &(_p)->reserved_3 ); \ - _mbg_swab32( &(_p)->reserved_4 ); \ } while ( 0 ) @@ -12141,10 +13006,10 @@ do \ /** * @brief Query MBG_NET_INTF_LINK_INFO by its index */ -typedef struct +typedef struct mbg_net_intf_link_info_idx_s { - uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_link-1 - MBG_NET_INTF_LINK_INFO info; ///< see ::MBG_NET_INTF_LINK_INFO + MBG_MSG_IDX idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_link-1. + MBG_NET_INTF_LINK_INFO info; ///< See ::MBG_NET_INTF_LINK_INFO. } MBG_NET_INTF_LINK_INFO_IDX; @@ -12168,7 +13033,7 @@ typedef struct uint32_t addr_index; ///< Index of the address on the physical interface it is assigned to uint32_t ass_if_index; ///< Index of the associated interface link, see ::MBG_NET_INTF_LINK_SETTINGS::if_index - uint32_t flags; ///< see ::MBG_NET_INTF_ADDR_MASKS + uint32_t flags; ///< See ::MBG_NET_INTF_ADDR_MASKS MBG_IP_ADDR ip; ///< IP address associated with this interface MBG_IP_ADDR broadcast; ///< Broadcast address associated with this interface @@ -12203,8 +13068,8 @@ do \ */ typedef struct { - uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_addr-1 - MBG_NET_INTF_ADDR_SETTINGS settings; ///< see ::MBG_NET_INTF_ADDR_SETTINGS + MBG_MSG_IDX idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_addr-1. + MBG_NET_INTF_ADDR_SETTINGS settings; ///< See ::MBG_NET_INTF_ADDR_SETTINGS. } MBG_NET_INTF_ADDR_SETTINGS_IDX; @@ -12221,8 +13086,8 @@ do \ */ typedef struct { - MBG_NET_INTF_ADDR_SETTINGS addr_settings; ///< see ::MBG_NET_INTF_ADDR_SETTINGS - uint32_t supp_flags; ///< see ::MBG_NET_INTF_ADDR_MASKS + MBG_NET_INTF_ADDR_SETTINGS addr_settings; ///< See ::MBG_NET_INTF_ADDR_SETTINGS + uint32_t supp_flags; ///< See ::MBG_NET_INTF_ADDR_MASKS uint32_t reserved_1; ///< Reserved, currently 0 uint32_t reserved_2; ///< Reserved, currently 0 @@ -12241,10 +13106,10 @@ do \ /** * @brief Query MBG_NET_INTF_ADDR_INFO by its index */ -typedef struct +typedef struct mbg_net_intf_addr_info_idx_s { - uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_addr-1 - MBG_NET_INTF_ADDR_INFO info; ///< see ::MBG_NET_INTF_ADDR_INFO + MBG_MSG_IDX idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_addr-1. + MBG_NET_INTF_ADDR_INFO info; ///< See ::MBG_NET_INTF_ADDR_INFO. } MBG_NET_INTF_ADDR_INFO_IDX; @@ -12302,8 +13167,8 @@ do \ */ typedef struct { - uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_route-1 - MBG_NET_INTF_ROUTE_SETTINGS settings; ///< see ::MBG_NET_INTF_ROUTE_SETTINGS + MBG_MSG_IDX idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_route-1. + MBG_NET_INTF_ROUTE_SETTINGS settings; ///< See ::MBG_NET_INTF_ROUTE_SETTINGS. } MBG_NET_INTF_ROUTE_SETTINGS_IDX; @@ -12320,7 +13185,7 @@ do \ */ typedef struct { - MBG_NET_INTF_ROUTE_SETTINGS route_settings; ///< see ::MBG_NET_INTF_ROUTE_SETTINGS + MBG_NET_INTF_ROUTE_SETTINGS route_settings; ///< See ::MBG_NET_INTF_ROUTE_SETTINGS uint32_t reserved_1; ///< Reserved, currently 0 uint32_t reserved_2; ///< Reserved, currently 0 uint32_t reserved_3; ///< Reserved, currently 0 @@ -12343,8 +13208,8 @@ do \ */ typedef struct { - uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_route-1 - MBG_NET_INTF_ROUTE_INFO info; ///< see ::MBG_NET_INTF_ROUTE_INFO + MBG_MSG_IDX idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_route-1. + MBG_NET_INTF_ROUTE_INFO info; ///< See ::MBG_NET_INTF_ROUTE_INFO. } MBG_NET_INTF_ROUTE_INFO_IDX; @@ -12399,9 +13264,9 @@ enum MBG_UCAP_NET_TRANSF_MODE */ enum MBG_UCAP_NET_TRANSF_MODE_MASKS { - MBG_UCAP_NET_TRANSF_MODE_MASK_UNKNOWN = ( 1UL << MBG_UCAP_NET_TRANSF_MODE_UNKNOWN ), ///< see ::MBG_UCAP_NET_TRANSF_MODE_UNKNOWN - MBG_UCAP_NET_TRANSF_MODE_MASK_ON_REQ = ( 1UL << MBG_UCAP_NET_TRANSF_MODE_ON_REQ ), ///< see ::MBG_UCAP_NET_TRANSF_MODE_ON_REQ - MBG_UCAP_NET_TRANSF_MODE_MASK_AUTO = ( 1UL << MBG_UCAP_NET_TRANSF_MODE_AUTO ) ///< see ::MBG_UCAP_NET_TRANSF_MODE_AUTO + MBG_UCAP_NET_TRANSF_MODE_MASK_UNKNOWN = ( 1UL << MBG_UCAP_NET_TRANSF_MODE_UNKNOWN ), ///< See ::MBG_UCAP_NET_TRANSF_MODE_UNKNOWN + MBG_UCAP_NET_TRANSF_MODE_MASK_ON_REQ = ( 1UL << MBG_UCAP_NET_TRANSF_MODE_ON_REQ ), ///< See ::MBG_UCAP_NET_TRANSF_MODE_ON_REQ + MBG_UCAP_NET_TRANSF_MODE_MASK_AUTO = ( 1UL << MBG_UCAP_NET_TRANSF_MODE_AUTO ) ///< See ::MBG_UCAP_NET_TRANSF_MODE_AUTO }; @@ -12428,8 +13293,8 @@ enum MBG_UCAP_NET_TRANSF_PROTO */ enum MBG_UCAP_NET_TRANSF_PROTO_MASKS { - MBG_UCAP_NET_TRANSF_PROTO_MASK_UNKNOWN = ( 1UL << MBG_UCAP_NET_TRANSF_PROTO_UNKNOWN ), ///< see ::MBG_UCAP_NET_TRANSF_PROTO_UNKNOWN - MBG_UCAP_NET_TRANSF_PROTO_MASK_UDP = ( 1UL << MBG_UCAP_NET_TRANSF_PROTO_UDP ) ///< see ::MBG_UCAP_NET_TRANSF_PROTO_UDP + MBG_UCAP_NET_TRANSF_PROTO_MASK_UNKNOWN = ( 1UL << MBG_UCAP_NET_TRANSF_PROTO_UNKNOWN ), ///< See ::MBG_UCAP_NET_TRANSF_PROTO_UNKNOWN + MBG_UCAP_NET_TRANSF_PROTO_MASK_UDP = ( 1UL << MBG_UCAP_NET_TRANSF_PROTO_UDP ) ///< See ::MBG_UCAP_NET_TRANSF_PROTO_UDP }; @@ -12453,7 +13318,7 @@ enum MBG_UCAP_NET_SUPP_FLAGS */ enum MBG_UCAP_NET_SUPP_FLAG_MASKS { - MBG_UCAP_NET_SUPP_FLAG_MASK_IPV6 = ( 1UL << MBG_UCAP_NET_SUPP_FLAG_IPV6 ) ///< see ::MBG_UCAP_NET_SUPP_FLAG_IPV6 + MBG_UCAP_NET_SUPP_FLAG_MASK_IPV6 = ( 1UL << MBG_UCAP_NET_SUPP_FLAG_IPV6 ) ///< See ::MBG_UCAP_NET_SUPP_FLAG_IPV6 }; @@ -12492,7 +13357,7 @@ do \ */ typedef struct { - MBG_UCAP_NET_GLB_SETTINGS settings; ///< see ::MBG_UCAP_NET_GLB_SETTINGS + MBG_UCAP_NET_GLB_SETTINGS settings; ///< See ::MBG_UCAP_NET_GLB_SETTINGS uint32_t n_supp_recvs; ///< Number of supported network receivers, see ::MBG_UCAP_NET_RECV_INFO_IDX uint32_t supp_modes; ///< Supported transfer modes, see ::MBG_UCAP_NET_TRANSF_MODE_MASKS @@ -12559,8 +13424,8 @@ do \ */ typedef struct { - uint16_t idx; ///< 0..::MBG_UCAP_NET_GLB_SETTINGS::num_recvs-1 - MBG_UCAP_NET_RECV_SETTINGS settings; ///< see ::MBG_UCAP_NET_RECV_SETTINGS + MBG_MSG_IDX idx; ///< 0..::MBG_UCAP_NET_GLB_SETTINGS::num_recvs-1. + MBG_UCAP_NET_RECV_SETTINGS settings; ///< See ::MBG_UCAP_NET_RECV_SETTINGS. } MBG_UCAP_NET_RECV_SETTINGS_IDX; @@ -12579,7 +13444,7 @@ do \ */ typedef struct { - MBG_UCAP_NET_RECV_SETTINGS settings; ///< see ::MBG_UCAP_NET_RECV_SETTINGS + MBG_UCAP_NET_RECV_SETTINGS settings; ///< See ::MBG_UCAP_NET_RECV_SETTINGS uint32_t reserved_0; ///< Reserved, currently always 0 uint32_t reserved_1; ///< Reserved, currently always 0 @@ -12612,8 +13477,8 @@ do \ */ typedef struct { - uint16_t idx; ///< 0..::MBG_UCAP_NET_GLB_INFO::n_supp_recvs-1 - MBG_UCAP_NET_RECV_INFO info; ///< see ::MBG_UCAP_NET_RECV_INFO + MBG_MSG_IDX idx; ///< 0..::MBG_UCAP_NET_GLB_INFO::n_supp_recvs-1. + MBG_UCAP_NET_RECV_INFO info; ///< See ::MBG_UCAP_NET_RECV_INFO. } MBG_UCAP_NET_RECV_INFO_IDX; @@ -12659,13 +13524,13 @@ enum PTP_NW_PROTS */ enum PTP_NW_PROT_MASKS { - 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 + 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 }; @@ -12723,21 +13588,33 @@ enum PTP_PORT_STATES }; +#define PTP_PORT_ST_STR_UNINITIALIZED "Uninitialized" +#define PTP_PORT_ST_STR_INITIALIZED "Initializing" +#define PTP_PORT_ST_STR_FAULTY "Faulty" +#define PTP_PORT_ST_STR_DISABLED "Disabled" +#define PTP_PORT_ST_STR_LISTENING "Listening" +#define PTP_PORT_ST_STR_PREMASTER "Pre-Master" +#define PTP_PORT_ST_STR_MASTER "Master" +#define PTP_PORT_ST_STR_PASSIVE "Passive" +#define PTP_PORT_ST_STR_UNCALIBRATED "Uncalibrated" +#define PTP_PORT_ST_STR_SLAVE "Slave" + + /** * @brief Name strings for the PTP port states */ -#define PTP_PORT_STATE_STRS \ -{ \ - "UNINITIALIZED", \ - "INITIALIZING", \ - "FAULTY", \ - "DISABLED", \ - "LISTENING", \ - "PRE_MASTER", \ - "MASTER", \ - "PASSIVE", \ - "UNCALIBRATED", \ - "SLAVE" \ +#define PTP_PORT_STATE_STRS \ +{ \ + PTP_PORT_ST_STR_UNINITIALIZED, \ + PTP_PORT_ST_STR_INITIALIZED, \ + PTP_PORT_ST_STR_FAULTY, \ + PTP_PORT_ST_STR_DISABLED, \ + PTP_PORT_ST_STR_LISTENING, \ + PTP_PORT_ST_STR_PREMASTER, \ + PTP_PORT_ST_STR_MASTER, \ + PTP_PORT_ST_STR_PASSIVE, \ + PTP_PORT_ST_STR_UNCALIBRATED, \ + PTP_PORT_ST_STR_SLAVE \ } @@ -12778,8 +13655,8 @@ enum PTP_DELAY_MECHS */ 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 + 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 }; @@ -12961,17 +13838,17 @@ enum PTP_ROLES */ enum PTP_ROLE_MASKS { - 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 - PTP_ROLE_MSK_NTP_SERVER = ( 1UL << PTP_ROLE_NTP_SERVER ), ///< see ::PTP_ROLE_NTP_SERVER - PTP_ROLE_MSK_NTP_CLIENT = ( 1UL << PTP_ROLE_NTP_CLIENT ), ///< see ::PTP_ROLE_NTP_CLIENT - PTP_ROLE_MSK_TIME_MONITOR = ( 1UL << PTP_ROLE_TIME_MONITOR ), ///< see ::PTP_ROLE_TIME_MONITOR - PTP_ROLE_MSK_V1_MASTER = ( 1UL << PTP_ROLE_V1_MASTER ), ///< see ::PTP_ROLE_MULTICAST_MASTER - PTP_ROLE_MSK_V1_SLAVE = ( 1UL << PTP_ROLE_V1_SLAVE ) ///< see ::PTP_ROLE_UNICAST_SLAVE + 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 + PTP_ROLE_MSK_NTP_SERVER = ( 1UL << PTP_ROLE_NTP_SERVER ), ///< See ::PTP_ROLE_NTP_SERVER + PTP_ROLE_MSK_NTP_CLIENT = ( 1UL << PTP_ROLE_NTP_CLIENT ), ///< See ::PTP_ROLE_NTP_CLIENT + PTP_ROLE_MSK_TIME_MONITOR = ( 1UL << PTP_ROLE_TIME_MONITOR ), ///< See ::PTP_ROLE_TIME_MONITOR + PTP_ROLE_MSK_V1_MASTER = ( 1UL << PTP_ROLE_V1_MASTER ), ///< See ::PTP_ROLE_MULTICAST_MASTER + PTP_ROLE_MSK_V1_SLAVE = ( 1UL << PTP_ROLE_V1_SLAVE ) ///< See ::PTP_ROLE_UNICAST_SLAVE }; @@ -13035,7 +13912,7 @@ enum PTP_ROLE_MASKS * @note This usually consists of a 6 byte MAC address with * 2 fixed bytes inserted, or all ones as wildcard. */ -typedef struct +typedef struct ptp_clock_id_s { uint8_t b[8]; @@ -13080,6 +13957,30 @@ typedef struct /** + * @brief A PTP port identity + * + * @note For further information, see IEEE 1588-2008, chapter 5.3.5 + * + * @see ::PTP_CLOCK_ID + * @see ::PTP_PORT_ID + */ +typedef struct ptp_ng_port_identity_s +{ + PTP_CLOCK_ID clock_identity; + PTP_PORT_ID port_number; + uint16_t reserved_1; + uint32_t reserved_2; +} PTP_NG_PORT_IDENTITY; + + +#define _mbg_swab_ptp_ng_port_identity( _p ) \ +{ \ + _mbg_swab_ptp_clock_id( &(_p)->clock_identity ); \ + _mbg_swab_ptp_port_id( &(_p)->port_number ); \ +} + + +/** * @brief PTP clock quality * * @note For further information, see IEEE 1588-2008, chapter 5.3.7 @@ -13087,7 +13988,7 @@ typedef struct typedef struct { uint8_t clock_class; ///< PTP clock class representing the current sync status - int8_t clock_accuracy; ///< see ::PTP_CLOCK_ACCURACIES + int8_t clock_accuracy; ///< See ::PTP_CLOCK_ACCURACIES uint16_t log_variance; ///< PTP offset scaled log variance representing the time stability } PTP_CLOCK_QUALITY; @@ -13105,7 +14006,6 @@ typedef struct * @brief PTP time interval * * @note For further information, see IEEE 1588-2008, chapter 5.3.2 - * */ typedef struct { @@ -13120,6 +14020,76 @@ typedef struct } + +/** + * @brief PTP packet timestamp seconds field. + * + * PTP timestamps used in network packets use an 48 bit (i.e. 6 bytes) only + * seconds fields, so a conversion is required whenever such a seconds field + * is to be read or written. + * + * In the PTP specs this is referenced as @a UInteger48. + * + * This is defined as a structure with an array member to avoid + * potential problems when passing the address as a reference, + * e.g. sizeof( *p ). + * + * @see ::PTP_PKT_TSTAMP + */ +typedef struct +{ + uint8_t b[6]; + +} PTP_PKT_TSTAMP_SECS; + + + +/** + * @brief PTP packet timestamp nanoseconds field. + * + * @see ::PTP_PKT_TSTAMP + */ +typedef uint32_t PTP_PKT_TSTAMP_NSECS; + + + +/** + * @brief PTP packet timestamp. + */ +typedef struct +{ + PTP_PKT_TSTAMP_SECS secs; + PTP_PKT_TSTAMP_NSECS nsecs; + +} PTP_PKT_TSTAMP; + + + +/** + * @brief Data type to store daylight saving flags in TLVs. + * + * @see ::PTP_TLV_DST_FLAG_MSKS + */ +typedef uint8_t PTP_TLV_DST_FLAGS; + + + +/** + * @brief Data type to store leap second flags in TLVs. + * + * @see ::PTP_TLV_LS_FLAG_MSKS + */ +typedef uint8_t PTP_TLV_LS_FLAGS; + + + +/** + * @brief Data type to store time offsets of whole seconds in TLVs. + */ +typedef int32_t PTP_TLV_TIME_OFFS; + + + /** * @brief An enumeration of time scales used with PTP * @@ -13186,7 +14156,7 @@ typedef struct 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 + 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; @@ -13196,14 +14166,14 @@ typedef struct uint16_t clock_offset_scaled_log_variance; uint8_t clock_class; - uint8_t clock_accuracy; ///< see ::PTP_CLOCK_ACCURACIES + uint8_t clock_accuracy; ///< See ::PTP_CLOCK_ACCURACIES uint32_t tsu_secs; ///< current seconds value of time stamp unit uint32_t reserved_2; ///< reserved, currently always 0 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 + 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 @@ -13260,14 +14230,14 @@ enum 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 + 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 }; @@ -13277,11 +14247,11 @@ enum PTP_STATE_FLAG_MASKS */ typedef struct { - uint16_t nw_prot; ///< see ::PTP_NW_PROTS + 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; ///< see ::PTP_DELAY_MECHS + 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 @@ -13456,41 +14426,41 @@ enum PTP_CFG_FLAGS * * @{ */ -#define PTP_CFG_MSK_TIME_SCALE_IS_PTP ( 1UL << PTP_CFG_TIME_SCALE_IS_PTP ) ///< see ::PTP_CFG_TIME_SCALE_IS_PTP -#define PTP_CFG_MSK_V1_HW_COMPAT ( 1UL << PTP_CFG_V1_HW_COMPAT ) ///< see ::PTP_CFG_V1_HW_COMPAT -#define PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE ( 1UL << PTP_CFG_CAN_BE_UNICAST_SLAVE ) ///< see ::PTP_CFG_CAN_BE_UNICAST_SLAVE -#define PTP_CFG_MSK_CAN_BE_MULTICAST_MASTER ( 1UL << PTP_CFG_CAN_BE_MULTICAST_MASTER ) ///< see ::PTP_CFG_CAN_BE_MULTICAST_MASTER -#define PTP_CFG_MSK_CAN_BE_UNICAST_MASTER ( 1UL << PTP_CFG_CAN_BE_UNICAST_MASTER ) ///< see ::PTP_CFG_CAN_BE_UNICAST_MASTER -#define PTP_CFG_MSK_CAN_BE_MULTICAST_AUTO ( 1UL << PTP_CFG_CAN_BE_MULTICAST_AUTO ) ///< see ::PTP_CFG_CAN_BE_MULTICAST_AUTO -#define PTP_CFG_MSK_SUPP_UTC_VALID ( 1UL << PTP_CFG_SUPP_UTC_VALID ) ///< see ::PTP_CFG_SUPP_UTC_VALID -#define PTP_CFG_MSK_CAN_BE_BOTH_MASTER ( 1UL << PTP_CFG_CAN_BE_BOTH_MASTER ) ///< see ::PTP_CFG_CAN_BE_BOTH_MASTER - -#define PTP_CFG_MSK_HYBRID_MASTER ( 1UL << PTP_CFG_HYBRID_MASTER ) ///< see ::PTP_CFG_HYBRID_MASTER -#define PTP_CFG_MSK_HYBRID_SLAVE ( 1UL << PTP_CFG_HYBRID_SLAVE ) ///< see ::PTP_CFG_HYBRID_SLAVE -#define PTP_CFG_MSK_ONE_STEP_MASTER ( 1UL << PTP_CFG_ONE_STEP_MASTER ) ///< see ::PTP_CFG_ONE_STEP_MASTER -#define PTP_CFG_MSK_MNGMNT_MSGS_DISB ( 1UL << PTP_CFG_MNGMNT_MSGS_DISB ) ///< see ::PTP_CFG_MNGMNT_MSGS_DISB -#define PTP_CFG_MSK_SUPP_MCAST_SLAVE_FLAG ( 1UL << PTP_CFG_SUPP_MCAST_SLAVE_FLAG ) ///< see ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG -#define PTP_CFG_MSK_CAN_BE_MULTICAST_SLAVE ( 1UL << PTP_CFG_CAN_BE_MULTICAST_SLAVE ) ///< see ::PTP_CFG_CAN_BE_MULTICAST_SLAVE -#define PTP_CFG_MSK_ONE_STEP_L2 ( 1UL << PTP_CFG_ONE_STEP_L2 ) ///< see ::PTP_CFG_ONE_STEP_L2 -#define PTP_CFG_MSK_ONE_STEP_P2P ( 1UL << PTP_CFG_ONE_STEP_P2P ) ///< see ::PTP_CFG_ONE_STEP_P2P - -#define PTP_CFG_MSK_TSU_RESET ( 1UL << PTP_CFG_TSU_RESET ) ///< see ::PTP_CFG_TSU_RESET -#define PTP_CFG_MSK_NTP_HW_TS_MASTER ( 1UL << PTP_CFG_NTP_HW_TS_MASTER ) ///< see ::PTP_CFG_NTP_HW_TS_MASTER -#define PTP_CFG_MSK_NTP_HW_TS_SLAVE ( 1UL << PTP_CFG_NTP_HW_TS_SLAVE) ///< see ::PTP_CFG_NTP_HW_TS_SLAVE -#define PTP_CFG_MSK_SYNCE_MASTER ( 1UL << PTP_CFG_SYNCE_MASTER ) ///< see ::PTP_CFG_SYNCE_MASTER -#define PTP_CFG_MSK_SYNCE_SLAVE ( 1UL << PTP_CFG_SYNCE_SLAVE ) ///< see ::PTP_CFG_SYNCE_SLAVE -#define PTP_CFG_MSK_HAS_MUX ( 1UL << PTP_CFG_HAS_MUX ) ///< see ::PTP_CFG_HAS_MUX -#define PTP_CFG_MSK_CAN_BE_TIME_MONITOR ( 1UL << PTP_CFG_CAN_BE_TIME_MONITOR ) ///< see ::PTP_CFG_CAN_BE_TIME_MONITOR -#define PTP_CFG_MSK_HAS_STATISTICS ( 1UL << PTP_CFG_HAS_STATISTICS ) ///< see ::PTP_CFG_HAS_STATISTICS - -#define PTP_CFG_MSK_CAN_BE_V1_MASTER ( 1UL << PTP_CFG_CAN_BE_V1_MASTER ) ///< see ::PTP_CFG_CAN_BE_V1_MASTER -#define PTP_CFG_MSK_CAN_BE_V1_SLAVE ( 1UL << PTP_CFG_CAN_BE_V1_SLAVE ) ///< see ::PTP_CFG_CAN_BE_V1_SLAVE -#define PTP_CFG_MSK_HAS_V2_COMMON_DATASETS ( 1UL << PTP_CFG_HAS_V2_COMMON_DATASETS ) ///< see ::PTP_CFG_HAS_V2_COMMON_DATASETS -#define PTP_CFG_MSK_HAS_V1_COMMON_DATASETS ( 1UL << PTP_CFG_HAS_V1_COMMON_DATASETS ) ///< see ::PTP_CFG_HAS_V1_COMMON_DATASETS -#define PTP_CFG_MSK_ATOI ( 1UL << PTP_CFG_ATOI ) ///< see ::PTP_CFG_ATOI -#define PTP_CFG_MSK_HAS_SMPTE_TLV_STATE ( 1UL << PTP_CFG_HAS_SMPTE_TLV_STATE ) ///< see ::PTP_CFG_HAS_SMPTE_TLV_STATE -#define PTP_CFG_MSK_NTP_SW_SERVER ( 1UL << PTP_CFG_NTP_SW_SERVER ) ///< see ::PTP_CFG_NTP_SW_SERVER -#define PTP_CFG_MSK_HAS_EXT_SUPP_FLAGS ( 1UL << PTP_CFG_HAS_EXT_SUPP_FLAGS ) ///< see ::PTP_CFG_CAN_BE_PTP_PROBE +#define PTP_CFG_MSK_TIME_SCALE_IS_PTP ( 1UL << PTP_CFG_TIME_SCALE_IS_PTP ) ///< See ::PTP_CFG_TIME_SCALE_IS_PTP +#define PTP_CFG_MSK_V1_HW_COMPAT ( 1UL << PTP_CFG_V1_HW_COMPAT ) ///< See ::PTP_CFG_V1_HW_COMPAT +#define PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE ( 1UL << PTP_CFG_CAN_BE_UNICAST_SLAVE ) ///< See ::PTP_CFG_CAN_BE_UNICAST_SLAVE +#define PTP_CFG_MSK_CAN_BE_MULTICAST_MASTER ( 1UL << PTP_CFG_CAN_BE_MULTICAST_MASTER ) ///< See ::PTP_CFG_CAN_BE_MULTICAST_MASTER +#define PTP_CFG_MSK_CAN_BE_UNICAST_MASTER ( 1UL << PTP_CFG_CAN_BE_UNICAST_MASTER ) ///< See ::PTP_CFG_CAN_BE_UNICAST_MASTER +#define PTP_CFG_MSK_CAN_BE_MULTICAST_AUTO ( 1UL << PTP_CFG_CAN_BE_MULTICAST_AUTO ) ///< See ::PTP_CFG_CAN_BE_MULTICAST_AUTO +#define PTP_CFG_MSK_SUPP_UTC_VALID ( 1UL << PTP_CFG_SUPP_UTC_VALID ) ///< See ::PTP_CFG_SUPP_UTC_VALID +#define PTP_CFG_MSK_CAN_BE_BOTH_MASTER ( 1UL << PTP_CFG_CAN_BE_BOTH_MASTER ) ///< See ::PTP_CFG_CAN_BE_BOTH_MASTER + +#define PTP_CFG_MSK_HYBRID_MASTER ( 1UL << PTP_CFG_HYBRID_MASTER ) ///< See ::PTP_CFG_HYBRID_MASTER +#define PTP_CFG_MSK_HYBRID_SLAVE ( 1UL << PTP_CFG_HYBRID_SLAVE ) ///< See ::PTP_CFG_HYBRID_SLAVE +#define PTP_CFG_MSK_ONE_STEP_MASTER ( 1UL << PTP_CFG_ONE_STEP_MASTER ) ///< See ::PTP_CFG_ONE_STEP_MASTER +#define PTP_CFG_MSK_MNGMNT_MSGS_DISB ( 1UL << PTP_CFG_MNGMNT_MSGS_DISB ) ///< See ::PTP_CFG_MNGMNT_MSGS_DISB +#define PTP_CFG_MSK_SUPP_MCAST_SLAVE_FLAG ( 1UL << PTP_CFG_SUPP_MCAST_SLAVE_FLAG ) ///< See ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG +#define PTP_CFG_MSK_CAN_BE_MULTICAST_SLAVE ( 1UL << PTP_CFG_CAN_BE_MULTICAST_SLAVE ) ///< See ::PTP_CFG_CAN_BE_MULTICAST_SLAVE +#define PTP_CFG_MSK_ONE_STEP_L2 ( 1UL << PTP_CFG_ONE_STEP_L2 ) ///< See ::PTP_CFG_ONE_STEP_L2 +#define PTP_CFG_MSK_ONE_STEP_P2P ( 1UL << PTP_CFG_ONE_STEP_P2P ) ///< See ::PTP_CFG_ONE_STEP_P2P + +#define PTP_CFG_MSK_TSU_RESET ( 1UL << PTP_CFG_TSU_RESET ) ///< See ::PTP_CFG_TSU_RESET +#define PTP_CFG_MSK_NTP_HW_TS_MASTER ( 1UL << PTP_CFG_NTP_HW_TS_MASTER ) ///< See ::PTP_CFG_NTP_HW_TS_MASTER +#define PTP_CFG_MSK_NTP_HW_TS_SLAVE ( 1UL << PTP_CFG_NTP_HW_TS_SLAVE) ///< See ::PTP_CFG_NTP_HW_TS_SLAVE +#define PTP_CFG_MSK_SYNCE_MASTER ( 1UL << PTP_CFG_SYNCE_MASTER ) ///< See ::PTP_CFG_SYNCE_MASTER +#define PTP_CFG_MSK_SYNCE_SLAVE ( 1UL << PTP_CFG_SYNCE_SLAVE ) ///< See ::PTP_CFG_SYNCE_SLAVE +#define PTP_CFG_MSK_HAS_MUX ( 1UL << PTP_CFG_HAS_MUX ) ///< See ::PTP_CFG_HAS_MUX +#define PTP_CFG_MSK_CAN_BE_TIME_MONITOR ( 1UL << PTP_CFG_CAN_BE_TIME_MONITOR ) ///< See ::PTP_CFG_CAN_BE_TIME_MONITOR +#define PTP_CFG_MSK_HAS_STATISTICS ( 1UL << PTP_CFG_HAS_STATISTICS ) ///< See ::PTP_CFG_HAS_STATISTICS + +#define PTP_CFG_MSK_CAN_BE_V1_MASTER ( 1UL << PTP_CFG_CAN_BE_V1_MASTER ) ///< See ::PTP_CFG_CAN_BE_V1_MASTER +#define PTP_CFG_MSK_CAN_BE_V1_SLAVE ( 1UL << PTP_CFG_CAN_BE_V1_SLAVE ) ///< See ::PTP_CFG_CAN_BE_V1_SLAVE +#define PTP_CFG_MSK_HAS_V2_COMMON_DATASETS ( 1UL << PTP_CFG_HAS_V2_COMMON_DATASETS ) ///< See ::PTP_CFG_HAS_V2_COMMON_DATASETS +#define PTP_CFG_MSK_HAS_V1_COMMON_DATASETS ( 1UL << PTP_CFG_HAS_V1_COMMON_DATASETS ) ///< See ::PTP_CFG_HAS_V1_COMMON_DATASETS +#define PTP_CFG_MSK_ATOI ( 1UL << PTP_CFG_ATOI ) ///< See ::PTP_CFG_ATOI +#define PTP_CFG_MSK_HAS_SMPTE_TLV_STATE ( 1UL << PTP_CFG_HAS_SMPTE_TLV_STATE ) ///< See ::PTP_CFG_HAS_SMPTE_TLV_STATE +#define PTP_CFG_MSK_NTP_SW_SERVER ( 1UL << PTP_CFG_NTP_SW_SERVER ) ///< See ::PTP_CFG_NTP_SW_SERVER +#define PTP_CFG_MSK_HAS_EXT_SUPP_FLAGS ( 1UL << PTP_CFG_HAS_EXT_SUPP_FLAGS ) ///< See ::PTP_CFG_CAN_BE_PTP_PROBE /** @} defgroup group_PTP_CFG_FLAG_MASKS */ @@ -13524,7 +14494,6 @@ enum PTP_CFG_FLAGS_EX PTP_CFG_DISABLE_PTP, ///< [R/W] PTP Port state can be set to DISABLED permanentely PTP_CFG_HAS_NTP_PKTGEN_IPV6, ///< [R/-] PTP packet generator supports IPv6 PTP_CFG_HAS_DELAY_ASYMMETRY_CFG,///< [R/-] PTP stack supports configuration of static delay asymmetry to be compensated - PTP_CFG_HAS_SOFT_NTP, ///< [R/-] PTP device supports software NTP daemon in parallel to PTP N_PTP_CFG_FLAGS_EX }; @@ -13540,11 +14509,10 @@ enum PTP_CFG_FLAGS_EX * * @{ */ -#define PTP_CFG_MSK_CAN_BE_PTP_PROBE ( 1UL << PTP_CFG_CAN_BE_PTP_PROBE ) ///< see ::PTP_CFG_CAN_BE_PTP_PROBE -#define PTP_CFG_MSK_DISABLE_PTP ( 1UL << PTP_CFG_DISABLE_PTP ) ///< see ::PTP_CFG_DISABLE_PTP -#define PTP_CFG_MSK_HAS_NTP_PKTGEN_IPV6 ( 1UL << PTP_CFG_HAS_NTP_PKTGEN_IPV6 ) ///< see ::PTP_CFG_HAS_NTP_PKTGEN_IPV6 -#define PTP_CFG_MSK_HAS_DELAY_ASYMMETRY_CFG ( 1UL << PTP_CFG_HAS_DELAY_ASYMMETRY_CFG ) ///< see ::PTP_CFG_HAS_DELAY_ASYMMETRY_CFG -#define PTP_CFG_MSK_HAS_SOFT_NTP ( 1UL << PTP_CFG_HAS_SOFT_NTP ) ///< see ::PTP_CFG_HAS_SOFT_NTP +#define PTP_CFG_MSK_CAN_BE_PTP_PROBE ( 1UL << PTP_CFG_CAN_BE_PTP_PROBE ) ///< See ::PTP_CFG_CAN_BE_PTP_PROBE +#define PTP_CFG_MSK_DISABLE_PTP ( 1UL << PTP_CFG_DISABLE_PTP ) ///< See ::PTP_CFG_DISABLE_PTP +#define PTP_CFG_MSK_HAS_NTP_PKTGEN_IPV6 ( 1UL << PTP_CFG_HAS_NTP_PKTGEN_IPV6 ) ///< See ::PTP_CFG_HAS_NTP_PKTGEN_IPV6 +#define PTP_CFG_MSK_HAS_DELAY_ASYMMETRY_CFG ( 1UL << PTP_CFG_HAS_DELAY_ASYMMETRY_CFG ) ///< See ::PTP_CFG_HAS_DELAY_ASYMMETRY_CFG /** @} defgroup group_PTP_CFG_FLAG_EX_MASKS */ @@ -13581,7 +14549,7 @@ enum PTP_HW_FEAT_BITS */ enum PTP_HW_FEAT_MASKS { - PTP_HW_FEAT_MSK_SYNCE_EXT_MUX = ( 1UL << PTP_FEAT_SYNCE_EXT_MUX ) ///< see ::PTP_FEAT_SYNCE_EXT_MUX + PTP_HW_FEAT_MSK_SYNCE_EXT_MUX = ( 1UL << PTP_FEAT_SYNCE_EXT_MUX ) ///< See ::PTP_FEAT_SYNCE_EXT_MUX }; @@ -13614,14 +14582,14 @@ enum PTP_OPT_EXTS enum PTP_OPT_EXT_MASKS { 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 - PTP_MSK_OPT_EXT_TELECOM_PHASE = ( 1UL << PTP_OPT_EXT_TELECOM_PHASE ), ///< see ::PTP_OPT_EXT_TELECOM_PHASE - PTP_MSK_OPT_EXT_SMPTE = ( 1UL << PTP_OPT_EXT_SMPTE ), ///< see ::PTP_OPT_EXT_SMPTE - PTP_MSK_OPT_EXT_8021AS = ( 1UL << PTP_OPT_EXT_8021AS ), ///< see ::PTP_OPT_EXT_8021AS - PTP_MSK_OPT_EXT_6185093 = ( 1UL << PTP_OPT_EXT_6185093 ), ///< see ::PTP_OPT_EXT_6185093 - PTP_MSK_OPT_EXT_TELECOM_PTS = ( 1UL << PTP_OPT_EXT_TELECOM_PTS ), ///< see ::PTP_OPT_EXT_TELECOM_PTS - PTP_MSK_OPT_EXT_C37238_2017 = ( 1UL << PTP_OPT_EXT_C37238_2017 ) ///< see ::PTP_MSK_OPT_EXT_C37238_2017 + 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 + PTP_MSK_OPT_EXT_TELECOM_PHASE = ( 1UL << PTP_OPT_EXT_TELECOM_PHASE ), ///< See ::PTP_OPT_EXT_TELECOM_PHASE + PTP_MSK_OPT_EXT_SMPTE = ( 1UL << PTP_OPT_EXT_SMPTE ), ///< See ::PTP_OPT_EXT_SMPTE + PTP_MSK_OPT_EXT_8021AS = ( 1UL << PTP_OPT_EXT_8021AS ), ///< See ::PTP_OPT_EXT_8021AS + PTP_MSK_OPT_EXT_6185093 = ( 1UL << PTP_OPT_EXT_6185093 ), ///< See ::PTP_OPT_EXT_6185093 + PTP_MSK_OPT_EXT_TELECOM_PTS = ( 1UL << PTP_OPT_EXT_TELECOM_PTS ), ///< See ::PTP_OPT_EXT_TELECOM_PTS + PTP_MSK_OPT_EXT_C37238_2017 = ( 1UL << PTP_OPT_EXT_C37238_2017 ) ///< See ::PTP_MSK_OPT_EXT_C37238_2017 }; @@ -13661,19 +14629,19 @@ enum PTP_PRESETS */ 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 - PTP_MSK_PRESETS_TELECOM_PHASE = ( 1UL << PTP_PRESETS_TELECOM_PHASE ), ///< see ::PTP_PRESETS_TELECOM_PHASE - PTP_MSK_PRESETS_SMPTE = ( 1UL << PTP_PRESETS_SMPTE ), ///< see ::PTP_PRESETS_SMPTE - PTP_MSK_PRESETS_AES67 = ( 1UL << PTP_PRESETS_AES67 ), ///< see ::PTP_PRESETS_AES67 - PTP_MSK_PRESETS_8021AS = ( 1UL << PTP_PRESETS_8021AS ), ///< see ::PTP_PRESETS_8021AS - PTP_MSK_PRESETS_6185093 = ( 1UL << PTP_PRESETS_6185093), ///< see ::PTP_PRESETS_6185093 - PTP_MSK_PRESETS_TELECOM_PTS = ( 1UL << PTP_PRESETS_TELECOM_PTS), ///< see ::PTP_PRESETS_TELECOM_PTS - PTP_MSK_PRESETS_DOCSIS_31 = ( 1UL << PTP_PRESETS_DOCSIS_31), ///< see ::PTP_PRESETS_DOCSIS_31 - PTP_MSK_PRESETS_C37238_2017 = ( 1UL << PTP_PRESETS_C37238_2017) ///< see ::PTP_PRESETS_C37238_2017 + 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 + PTP_MSK_PRESETS_TELECOM_PHASE = ( 1UL << PTP_PRESETS_TELECOM_PHASE ), ///< See ::PTP_PRESETS_TELECOM_PHASE + PTP_MSK_PRESETS_SMPTE = ( 1UL << PTP_PRESETS_SMPTE ), ///< See ::PTP_PRESETS_SMPTE + PTP_MSK_PRESETS_AES67 = ( 1UL << PTP_PRESETS_AES67 ), ///< See ::PTP_PRESETS_AES67 + PTP_MSK_PRESETS_8021AS = ( 1UL << PTP_PRESETS_8021AS ), ///< See ::PTP_PRESETS_8021AS + PTP_MSK_PRESETS_6185093 = ( 1UL << PTP_PRESETS_6185093), ///< See ::PTP_PRESETS_6185093 + PTP_MSK_PRESETS_TELECOM_PTS = ( 1UL << PTP_PRESETS_TELECOM_PTS), ///< See ::PTP_PRESETS_TELECOM_PTS + PTP_MSK_PRESETS_DOCSIS_31 = ( 1UL << PTP_PRESETS_DOCSIS_31), ///< See ::PTP_PRESETS_DOCSIS_31 + PTP_MSK_PRESETS_C37238_2017 = ( 1UL << PTP_PRESETS_C37238_2017) ///< See ::PTP_PRESETS_C37238_2017 }; @@ -13692,7 +14660,7 @@ enum PTP_PRESETS_MASKS "Telecom ITU-T G.8265.1", \ "Telecom ITU-T G.8275.1", \ "SMPTE ST 2059-2", \ - "AES67 Media Profile", \ + "AES67 Media", \ "IEEE 802.1AS", \ "Utility IEC 61850-9-3", \ "Telecom ITU-T G.8275.2", \ @@ -13794,7 +14762,8 @@ enum SMPTE_SYSTEM_FRAME_RATES */ typedef struct { - /// Default system frame rate + /// @brief Default system frame rate. + /// /// Default video frame rate of the slave system as a lowest term rational. /// The data type shall be composed of a pair of unsigned Int32 values coded /// in big-endian form where the first shall be the numerator and the second @@ -13802,68 +14771,75 @@ typedef struct /// that represents the frame rate denominator /// For example, 29.97 Hz: (30000/1001) or 25 Hz: (25/1). uint32_t defaultSystemFrameRateNum; + + /// @brief The denominator associated with @a #defaultSystemFrameRateNum. uint32_t defaultSystemFrameRateDenum; - /// Master locking status + + /// @brief Master locking status + /// /// Complementary information to clockClass (0: Not in use, 1: Free Run, /// 2: Cold Locking, 3: Warm Locking, 4: Locked) uint8_t masterLockingStatus; - /// Time Address Flags + + /// @brief Time Address Flags + /// /// Indicates the intended ST 12-1 flags. /// Bit 0: Drop frame (0: Non-drop-frame, 1: Drop-frame) /// Bit 1: Color Frame Identification (0: Not in use, 1: In use) /// Bits 2-7: Reserved uint8_t timeAddressFlags; - /// Current local offset - /// Offset in seconds of Local Time from grandmaster PTP time. For example, - /// if Local Time is Eastern Standard Time (North America) UTC-5 and the - /// number of leap seconds is 35, the value will be -18035 (decimal). uint8_t reserved_1; uint8_t reserved_2; + /// @brief Current local offset. + /// + /// Offset in seconds of Local Time from grandmaster PTP time. For example, + /// if Local Time is Eastern Standard Time (North America) %UTC-5 and the + /// number of leap seconds is 35, the value will be -18035 (decimal). int32_t currentLocalOffset; - /// Jump seconds + + /// @brief Jump seconds. + /// /// The size of the next discontinuity, in seconds, of Local Time. A value /// of zero indicates that no discontinuity is expected. A positive value - /// indicates that the discontinuity will cause the currentLocalOffset to increase. + /// indicates that the discontinuity will cause @a #currentLocalOffset to increase. int32_t jumpSeconds; - /// Time of next jump - /// The value of the seconds portion of the grandmastermaster PTP time at the time - /// that the next discontinuity of the currentLocalOffset will occur. The - /// discontinuity occurs at the start of the second indicated - uint8_t timeOfNextJump[6]; - /// Time of next jam + + /// @brief Time of next jump. + /// + /// The value of the seconds portion of the grandmaster PTP time at the time + /// that the next discontinuity of the @a #currentLocalOffset will occur. The + /// discontinuity occurs at the start of the second indicated. + PTP_PKT_TSTAMP_SECS timeOfNextJump; + + /// @brief Time of next jam. + /// /// The value of the seconds portion of the PTP time corresponding to the next /// scheduled occurrence of the Daily Jam. If no Daily Jam is scheduled, the - /// value of timeOfNextJam shall be zero. - uint8_t timeOfNextJam[6]; - /// Time of previous jam + /// value of @a #timeOfNextJam shall be zero. + PTP_PKT_TSTAMP_SECS timeOfNextJam; + + /// @brief Time of previous jam. + /// /// The value of the seconds portion of the PTP time corresponding to the /// previous occurrence of the Daily Jam. - uint8_t timeOfPreviousJam[6]; - /// Previous jam local offset - /// The value of currentLocalOffset at the previous daily jam time. - /// If a discontinuity of Local Time occurs at the jam time, this parameter - /// reflects the offset after the discontinuity. + PTP_PKT_TSTAMP_SECS timeOfPreviousJam; + uint8_t reserved_3; uint8_t reserved_4; uint32_t reserved_5; - int32_t previousJamLocalOffset; - /// Daylight saving - /// Bit 0: Current Daylight Saving (0: Not in effect, 1: In effect) - /// Bit 1: Daylight Saving at next discontinuity (0: Not in effect, 1: In effect) - /// Bit 2: Daylight Saving at previous daily jam time (0: Not in effect, 1: In effect) - /// Bits 3-7: Reserved - uint8_t daylightSaving; - /// Leap second jump - /// The reason for the forthcoming discontinuity of currentLocalOffset indicated by - /// timeOfNextJump - /// Bit 0: - /// 0: Other than a change in the number of leap seconds (default) - /// 1: A change in number of leap seconds - /// Bits 1-7: Reserved - uint8_t leapSecondJump; + /// @brief Previous jam local offset. + /// + /// The value of @a #currentLocalOffset at the previous daily jam time. + /// If a discontinuity of Local Time occurs at the jam time, this parameter + /// reflects the offset after the discontinuity. + PTP_TLV_TIME_OFFS previousJamLocalOffset; + + PTP_TLV_DST_FLAGS daylightSaving; ///< Daylight saving flags, see ::PTP_TLV_DST_FLAG_MSKS. + + PTP_TLV_LS_FLAGS leapSecondJump; ///< Leap second flags, see ::PTP_TLV_LS_FLAG_MSKS. uint8_t reserved_6; uint8_t reserved_7; @@ -13890,6 +14866,7 @@ do \ } while ( 0 ) + /** * @brief Additional parameters for Telecom8275.1 profile */ @@ -14126,14 +15103,14 @@ enum SDH_NETWORK_OPTIONS /** - * @brief Flag masks used with MBG_SYNC_E_INFO::supp_sdh_network_opts ::FIXME + * @brief Flag masks used with :: MBG_NET_INTF_LINK_INFO::supp_sdh_net_opts * * @see ::SDH_NETWORK_OPTIONS */ enum SDH_NETWORK_OPTION_MASKS { - SDH_NETWORK_OPTION_1_MSK = ( 1UL << SDH_NETWORK_OPTION_1 ), ///< see ::SDH_NETWORK_OPTION_1 - SDH_NETWORK_OPTION_2_MSK = ( 1UL << SDH_NETWORK_OPTION_2 ), ///< see ::SDH_NETWORK_OPTION_2 + SDH_NETWORK_OPTION_1_MSK = ( 1UL << SDH_NETWORK_OPTION_1 ), ///< See ::SDH_NETWORK_OPTION_1 + SDH_NETWORK_OPTION_2_MSK = ( 1UL << SDH_NETWORK_OPTION_2 ), ///< See ::SDH_NETWORK_OPTION_2 }; @@ -14150,10 +15127,8 @@ enum SDH_NETWORK_OPTION_MASKS } - -//##++++ TODO: shouldn't this be merged with / replaced by MBG_NET_LINK_MODES? /** - * @brief Link modes for SyncE on a 1000BASE-T interface + * @brief Link modes for SyncE on a 1000BASE-T interface. * * @see ::GBIT_LINK_COPPER_MODE_MASKS */ @@ -14171,18 +15146,18 @@ enum GBIT_LINK_COPPER_MODES /** - * @brief Flag masks used with MBG_SYNC_E_INFO::supp_gbit_link_copper_modes ::FIXME + * @brief Flag masks used with ::MBG_NET_INTF_LINK_INFO::supp_gb_copper_modes. * * @see ::GBIT_LINK_COPPER_MODES */ enum GBIT_LINK_COPPER_MODE_MASKS { - GBIT_LINK_COPPER_AUTO_MSK = ( 1UL << GBIT_LINK_COPPER_AUTO ), ///< see ::GBIT_LINK_COPPER_AUTO_MSK - GBIT_LINK_COPPER_FORCE_SYNCE_AUTO_MSK = ( 1UL << GBIT_LINK_COPPER_FORCE_SYNCE_AUTO ), ///< see ::GBIT_LINK_COPPER_FORCE_SYNCE_AUTO - GBIT_LINK_COPPER_FORCE_OR_IS_MASTER_MSK = ( 1UL << GBIT_LINK_COPPER_FORCE_OR_IS_MASTER ), ///< see ::GBIT_LINK_COPPER_FORCE_OR_IS_MASTER - GBIT_LINK_COPPER_FORCE_OR_IS_SLAVE_MSK = ( 1UL << GBIT_LINK_COPPER_FORCE_OR_IS_SLAVE ), ///< see ::GBIT_LINK_COPPER_FORCE_OR_IS_SLAVE - GBIT_LINK_COPPER_PREFER_MASTER_MSK = ( 1UL << GBIT_LINK_COPPER_PREFER_MASTER ), ///< see ::GBIT_LINK_COPPER_PREFER_MASTER - GBIT_LINK_COPPER_PREFER_SLAVE_MSK = ( 1UL << GBIT_LINK_COPPER_PREFER_SLAVE ) ///< see ::GBIT_LINK_COPPER_PREFER_SLAVE + GBIT_LINK_COPPER_AUTO_MSK = ( 1UL << GBIT_LINK_COPPER_AUTO ), ///< See ::GBIT_LINK_COPPER_AUTO_MSK + GBIT_LINK_COPPER_FORCE_SYNCE_AUTO_MSK = ( 1UL << GBIT_LINK_COPPER_FORCE_SYNCE_AUTO ), ///< See ::GBIT_LINK_COPPER_FORCE_SYNCE_AUTO + GBIT_LINK_COPPER_FORCE_OR_IS_MASTER_MSK = ( 1UL << GBIT_LINK_COPPER_FORCE_OR_IS_MASTER ), ///< See ::GBIT_LINK_COPPER_FORCE_OR_IS_MASTER + GBIT_LINK_COPPER_FORCE_OR_IS_SLAVE_MSK = ( 1UL << GBIT_LINK_COPPER_FORCE_OR_IS_SLAVE ), ///< See ::GBIT_LINK_COPPER_FORCE_OR_IS_SLAVE + GBIT_LINK_COPPER_PREFER_MASTER_MSK = ( 1UL << GBIT_LINK_COPPER_PREFER_MASTER ), ///< See ::GBIT_LINK_COPPER_PREFER_MASTER + GBIT_LINK_COPPER_PREFER_SLAVE_MSK = ( 1UL << GBIT_LINK_COPPER_PREFER_SLAVE ) ///< See ::GBIT_LINK_COPPER_PREFER_SLAVE }; @@ -14273,17 +15248,17 @@ do \ */ 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; ///< Hostname or IP address of the grandmaster. + PTP_CLOCK_ID gm_clock_id; ///< Clock ID of the master port, or ::PTP_CLOCK_ID_WILDCARD. + PTP_PORT_ID gm_port_id; ///< Target port ID of the 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; @@ -14328,7 +15303,7 @@ enum PTP_UC_MSG_DURATION_LIMITS */ typedef struct { - uint32_t idx; ///< index, 0..PTP_UC_MASTER_CFG_LIMITS::n_supp_master-1 + MBG_MSG_IDX_32 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; @@ -14381,7 +15356,7 @@ do \ */ typedef struct { - uint32_t idx; ///< index, 0..PTP_UC_MASTER_CFG_LIMITS::n_supp_master-1 + MBG_MSG_IDX_32 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; @@ -14418,63 +15393,65 @@ typedef struct typedef struct { - uint32_t status; ///< status word flags (use PacketCounterStat_e) - uint32_t rx; ///< overall Rx packet counter - uint32_t rxPerSec; ///< overall Rx packet counter - uint32_t tx; ///< overall Tx packet counter - uint32_t txPerSec; ///< overall Tx packet counter - /// invalid Rx packet counter + uint32_t status; ///< Status word flags (use PacketCounterStat_e) + uint32_t rx; ///< Overall RX packet counter + uint32_t rxPerSec; ///< Overall RX packet counter + uint32_t tx; ///< Overall TX packet counter + uint32_t txPerSec; ///< Overall TX packet counter + + /// @brief Invalid RX packet counter. + /// /// Indicates one of the following issues: wrong PTP version, wrong domain number, /// message from self, message from other BC port, multicast message in unicast mode /// or message extraction error (size error or inconsistent format). uint32_t errorRx; - uint32_t announceMsgRx; ///< Accepted Announce message Rx counter - uint32_t announceMsgPerSecRx; ///< Accepted Announce message Rx counter - uint32_t announceMsgTx; ///< Announce message Tx counter - uint32_t announceMsgPerSecTx; ///< Announce message Tx counter - uint32_t syncMsgRx; ///< Accepted Sync message Rx counter - uint32_t syncMsgPerSecRx; ///< Accepted Sync message Rx counter - uint32_t syncMsgTx; ///< Sync message Tx counter - uint32_t syncMsgPerSecTx; ///< Sync message Tx counter - uint32_t followUpMsgRx; ///< Accepted Follow-up message Rx counter - uint32_t followUpMsgPerSecRx; ///< Accepted Follow-up message Rx counter - uint32_t followUpMsgTx; ///< Follow-up message Tx counter - uint32_t followUpMsgPerSecTx; ///< Follow-up message Tx counter - uint32_t dlyReqMsgRx; ///< Accepted Delay request message Rx counter - uint32_t dlyReqMsgPerSecRx; ///< Accepted Delay request message Rx counter - uint32_t dlyReqMsgTx; ///< Delay request message Tx counter - uint32_t dlyReqMsgPerSecTx; ///< Delay request message Tx counter - uint32_t dlyRespMsgRx; ///< Accepted Delay response message Rx counter - uint32_t dlyRespMsgPerSecRx; ///< Accepted Delay response message Rx counter - uint32_t dlyRespMsgTx; ///< Delay response message Tx counter - uint32_t dlyRespMsgPerSecTx; ///< Delay response message Tx counter - uint32_t pDlyReqMsgRx; ///< Accepted PDelay Request message Rx counter - uint32_t pDlyReqMsgPerSecRx; ///< Accepted PDelay Request message Rx counter - uint32_t pDlyReqMsgTx; ///< PDelay Request message Tx counter - uint32_t pDlyReqMsgPerSecTx; ///< PDelay Request message Tx counter - uint32_t pDlyRespMsgRx; ///< Accepted PDelay Response message Rx counter - uint32_t pDlyRespMsgPerSecRx; ///< Accepted PDelay Response message Rx counter - uint32_t pDlyRespMsgTx; ///< PDelay Response message Tx counter - uint32_t pDlyRespMsgPerSecTx; ///< PDelay Response message Tx counter - uint32_t pDlyFollowUpRx; ///< Accepted PDelay Follow-Up message Rx counter - uint32_t pDlyFollowUpPerSecRx; ///< Accepted PDelay Follow-Up message Rx counter - uint32_t pDlyFollowUpTx; ///< PDelay Follow-Up message Tx counter - uint32_t pDlyFollowUpPerSecTx; ///< PDelay Follow-Up message Tx counter - uint32_t signallingRx; ///< Accepted Signalling message Rx counter - uint32_t signallingPerSecRx; ///< Accepted Signalling message Rx counter - uint32_t signallingTx; ///< Signalling message Tx counter - uint32_t signallingPerSecTx; ///< Signalling message Tx counter - uint32_t mgmtRx; ///< Accepted Management message Rx counter - uint32_t mgmtPerSecRx; ///< Accepted Management message Rx counter - uint32_t mgmtTx; ///< Management message Tx counter - uint32_t mgmtPerSecTx; ///< Management message Tx counter - uint32_t mgmtErr; ///< Management error counter (rx) - uint32_t annReceptTout; ///< Announce recept timeout count + uint32_t announceMsgRx; ///< Accepted Announce message RX counter + uint32_t announceMsgPerSecRx; ///< Accepted Announce message RX counter + uint32_t announceMsgTx; ///< Announce message TX counter + uint32_t announceMsgPerSecTx; ///< Announce message TX counter + uint32_t syncMsgRx; ///< Accepted Sync message RX counter + uint32_t syncMsgPerSecRx; ///< Accepted Sync message RX counter + uint32_t syncMsgTx; ///< Sync message TX counter + uint32_t syncMsgPerSecTx; ///< Sync message TX counter + uint32_t followUpMsgRx; ///< Accepted Follow-up message RX counter + uint32_t followUpMsgPerSecRx; ///< Accepted Follow-up message RX counter + uint32_t followUpMsgTx; ///< Follow-up message TX counter + uint32_t followUpMsgPerSecTx; ///< Follow-up message TX counter + uint32_t dlyReqMsgRx; ///< Accepted Delay request message RX counter + uint32_t dlyReqMsgPerSecRx; ///< Accepted Delay request message RX counter + uint32_t dlyReqMsgTx; ///< Delay request message TX counter + uint32_t dlyReqMsgPerSecTx; ///< Delay request message TX counter + uint32_t dlyRespMsgRx; ///< Accepted Delay response message RX counter + uint32_t dlyRespMsgPerSecRx; ///< Accepted Delay response message RX counter + uint32_t dlyRespMsgTx; ///< Delay response message TX counter + uint32_t dlyRespMsgPerSecTx; ///< Delay response message TX counter + uint32_t pDlyReqMsgRx; ///< Accepted PDelay Request message RX counter + uint32_t pDlyReqMsgPerSecRx; ///< Accepted PDelay Request message RX counter + uint32_t pDlyReqMsgTx; ///< PDelay Request message TX counter + uint32_t pDlyReqMsgPerSecTx; ///< PDelay Request message TX counter + uint32_t pDlyRespMsgRx; ///< Accepted PDelay Response message RX counter + uint32_t pDlyRespMsgPerSecRx; ///< Accepted PDelay Response message RX counter + uint32_t pDlyRespMsgTx; ///< PDelay Response message TX counter + uint32_t pDlyRespMsgPerSecTx; ///< PDelay Response message TX counter + uint32_t pDlyFollowUpRx; ///< Accepted PDelay Follow-Up message RX counter + uint32_t pDlyFollowUpPerSecRx; ///< Accepted PDelay Follow-Up message RX counter + uint32_t pDlyFollowUpTx; ///< PDelay Follow-Up message TX counter + uint32_t pDlyFollowUpPerSecTx; ///< PDelay Follow-Up message TX counter + uint32_t signallingRx; ///< Accepted Signalling message RX counter + uint32_t signallingPerSecRx; ///< Accepted Signalling message RX counter + uint32_t signallingTx; ///< Signalling message TX counter + uint32_t signallingPerSecTx; ///< Signalling message TX counter + uint32_t mgmtRx; ///< Accepted Management message RX counter + uint32_t mgmtPerSecRx; ///< Accepted Management message RX counter + uint32_t mgmtTx; ///< Management message TX counter + uint32_t mgmtPerSecTx; ///< Management message TX counter + uint32_t mgmtErr; ///< Management error counter (RX) + uint32_t annReceptTout; ///< Announce receipt timeout count uint32_t numUcConn; ///< Number of current Unicast client connections uint32_t maxNumUcConn; ///< Maximum Number of Unicast client connections (due to licence or CPU performance) uint32_t numMsgPerSec; ///< Number of all messages per second (TX/RX) - uint32_t maxMsgPerSec; ///< max allowed number of all messages per second in Multicast/Hybrid mode (due to licence or CPU performance) + uint32_t maxMsgPerSec; ///< Max. allowed number of all messages per second in Multicast/Hybrid mode (due to licence or CPU performance) } MBG_PTP_STATISTICS_STATUS; @@ -14527,6 +15504,7 @@ typedef struct PTP_CLOCK_ID clock_uuid; PTP_PORT_ID port_id; uint16_t reserved_3; + } PTP_V1_UUID; @@ -14564,15 +15542,14 @@ enum PTP_V1_DEFAULT_DATASET_FLAGS */ enum PTP_V1_DEFAULT_DATASET_FLAGS_MASKS { - V1_DFLT_MSK_CLK_FOLLOWUP_CAPABLE = ( 1UL << V1_DFLT_CLK_FOLLOWUP_CAPABLE ), ///< see ::V1_DFLT_CLK_FOLLOWUP_CAPABLE - V1_DFLT_MSK_PREFERRED = ( 1UL << V1_DFLT_PREFERRED ), ///< see ::V1_DFLT_PREFERRED - V1_DFLT_MSK_INITIALIZABLE = ( 1UL << V1_DFLT_INITIALIZABLE ), ///< see ::V1_DFLT_INITIALIZABLE - V1_DFLT_MSK_EXT_TIMING = ( 1UL << V1_DFLT_EXT_TIMING), ///< see ::V1_DFLT_EXT_TIMING - V1_DFLT_MSK_IS_BC = ( 1UL << V1_DFLT_IS_BC ) ///< see ::V1_DFLT_IS_BC + V1_DFLT_MSK_CLK_FOLLOWUP_CAPABLE = ( 1UL << V1_DFLT_CLK_FOLLOWUP_CAPABLE ), ///< See ::V1_DFLT_CLK_FOLLOWUP_CAPABLE + V1_DFLT_MSK_PREFERRED = ( 1UL << V1_DFLT_PREFERRED ), ///< See ::V1_DFLT_PREFERRED + V1_DFLT_MSK_INITIALIZABLE = ( 1UL << V1_DFLT_INITIALIZABLE ), ///< See ::V1_DFLT_INITIALIZABLE + V1_DFLT_MSK_EXT_TIMING = ( 1UL << V1_DFLT_EXT_TIMING), ///< See ::V1_DFLT_EXT_TIMING + V1_DFLT_MSK_IS_BC = ( 1UL << V1_DFLT_IS_BC ) ///< See ::V1_DFLT_IS_BC }; - /** * @brief PTPv1 default dataset containing global information about the device * @@ -14588,6 +15565,7 @@ typedef struct { uint16_t number_ports; uint16_t number_foreign_records; uint32_t flags; + } MBG_PTP_V1_DEFAULT_DATASET; @@ -14605,8 +15583,6 @@ do \ /** * @brief PTPv1 current dataset containing information about the synchronization status of the device - * - * @see ::NANO_TIME */ typedef struct { @@ -14614,6 +15590,7 @@ typedef struct uint16_t reserved_1; NANO_TIME offset_from_master; NANO_TIME one_way_delay; + } MBG_PTP_V1_CURRENT_DATASET; @@ -14652,12 +15629,12 @@ enum PTP_V1_PARENT_DATASET_FLAGS */ enum PTP_V1_PARENT_DATASET_FLAGS_MASKS { - V1_PARENT_MSK_FOLLOWUP_CAPABLE = ( 1UL << V1_PARENT_FOLLOWUP_CAPABLE ), ///< see ::V1_PARENT_FOLLOWUP_CAPABLE - V1_PARENT_MSK_EXT_TIMING = ( 1UL << V1_PARENT_EXT_TIMING ), ///< see ::V1_PARENT_EXT_TIMING - V1_PARENT_MSK_STATS = ( 1UL << V1_PARENT_STATS ), ///< see ::V1_PARENT_STATS - V1_PARENT_MSK_UTC_REASONABLE = ( 1UL << V1_PARENT_UTC_REASONABLE ), ///< see ::V1_PARENT_UTC_REASONABLE - V1_PARENT_MSK_GM_PREFERRED = ( 1UL << V1_PARENT_GM_PREFERRED ), ///< see ::V1_PARENT_GM_PREFERRED - V1_PARENT_MSK_GM_IS_BC = ( 1UL << V1_PARENT_GM_IS_BC ) ///< see ::V1_PARENT_GM_IS_BC + V1_PARENT_MSK_FOLLOWUP_CAPABLE = ( 1UL << V1_PARENT_FOLLOWUP_CAPABLE ), ///< See ::V1_PARENT_FOLLOWUP_CAPABLE + V1_PARENT_MSK_EXT_TIMING = ( 1UL << V1_PARENT_EXT_TIMING ), ///< See ::V1_PARENT_EXT_TIMING + V1_PARENT_MSK_STATS = ( 1UL << V1_PARENT_STATS ), ///< See ::V1_PARENT_STATS + V1_PARENT_MSK_UTC_REASONABLE = ( 1UL << V1_PARENT_UTC_REASONABLE ), ///< See ::V1_PARENT_UTC_REASONABLE + V1_PARENT_MSK_GM_PREFERRED = ( 1UL << V1_PARENT_GM_PREFERRED ), ///< See ::V1_PARENT_GM_PREFERRED + V1_PARENT_MSK_GM_IS_BC = ( 1UL << V1_PARENT_GM_IS_BC ) ///< See ::V1_PARENT_GM_IS_BC }; @@ -14681,7 +15658,7 @@ typedef struct int16_t grandmaster_variance; uint16_t grandmaster_sequence_number; uint16_t reserved_2; - uint32_t flags; ///< see ::PTP_V1_PARENT_DATASET_FLAGS_MASKS + uint32_t flags; ///< See ::PTP_V1_PARENT_DATASET_FLAGS_MASKS } MBG_PTP_V1_PARENT_DATASET; @@ -14724,8 +15701,8 @@ enum PTP_V1_TIME_PROP_DATASET_DATASET_FLAGS */ enum PTP_V1_TIME_PROP_DATASET_FLAGS_MASKS { - V1_TPROP_MSK_LEAP_59 = ( 1UL << V1_TPROP_LEAP_59 ), ///< see ::V1_TPROP_LEAP_59 - V1_TPROP_MSK_LEAP_61 = ( 1UL << V1_TPROP_LEAP_61 ) ///< see ::V1_TPROP_LEAP_61 + V1_TPROP_MSK_LEAP_59 = ( 1UL << V1_TPROP_LEAP_59 ), ///< See ::V1_TPROP_LEAP_59 + V1_TPROP_MSK_LEAP_61 = ( 1UL << V1_TPROP_LEAP_61 ) ///< See ::V1_TPROP_LEAP_61 }; @@ -14738,7 +15715,7 @@ typedef struct { int16_t current_utc_offset; uint16_t epoch_number; - uint32_t flags; ///< see ::PTP_V1_TIME_PROP_DATASET_FLAGS_MASKS + uint32_t flags; ///< See ::PTP_V1_TIME_PROP_DATASET_FLAGS_MASKS } MBG_PTP_V1_TIME_PROPERTIES_DATASET; @@ -14772,7 +15749,7 @@ enum PTP_V1_PORT_DATASET_DATASET_FLAGS */ enum PTP_V1_PORT_DATASET_FLAGS_MASKS { - V1_PORT_DATASET_MSK_BURST_ENB = ( 1UL << V1_PORT_DATASET_BURST_ENB ), ///< see ::V1_PORT_DATASET_BURST_ENB + V1_PORT_DATASET_MSK_BURST_ENB = ( 1UL << V1_PORT_DATASET_BURST_ENB ), ///< See ::V1_PORT_DATASET_BURST_ENB }; @@ -14815,14 +15792,14 @@ do \ /** * @brief Index structure for PTPv1 port dataset * - * @note Port dataset with index 0..::MBG_PTP_V1_DEFAULT_DATASET::number_ports - 1 can be queried from a device + * @note Port datasets with index 0..::MBG_PTP_V1_DEFAULT_DATASET::number_ports-1 can be queried from a device. * * @see ::MBG_PTP_V1_PORT_DATASET */ typedef struct { - uint16_t idx; ///< Index of the port dataset, 0..::MBG_PTP_V1_DEFAULT_DATASET::number_ports - 1 - MBG_PTP_V1_PORT_DATASET port_dataset; ///< see ::MBG_PTP_V1_PORT_DATASET + MBG_MSG_IDX idx; ///< Index of the port dataset, 0..::MBG_PTP_V1_DEFAULT_DATASET::number_ports-1. + MBG_PTP_V1_PORT_DATASET port_dataset; ///< See ::MBG_PTP_V1_PORT_DATASET. } MBG_PTP_V1_PORT_DATASET_IDX; @@ -14892,6 +15869,60 @@ typedef struct /** + * @brief Flags for the PTPv2 NG default dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.1 and 15.5.3.3.1 + * + * @see ::MBG_PTP_V2_DEFAULT_DATASET + */ +enum MBG_PTP_V2_NG_DFLT_DS_FLAGS +{ + MBG_PTP_V2_NG_DFLT_DS_FLAG_TWO_STEP, + MBG_PTP_V2_NG_DFLT_DS_FLAG_SLAVE_ONLY, + N_MBG_PTP_V2_NG_DFLT_DS_FLAGS + +}; + +enum MBG_PTP_V2_NG_DFLT_DS_FLAG_MASKS +{ + MBG_PTP_V2_NG_DFLT_DS_FLAG_MSK_TWO_STEP = ( 1UL << MBG_PTP_V2_NG_DFLT_DS_FLAG_TWO_STEP), + MBG_PTP_V2_NG_DFLT_DS_FLAG_MSK_SLAVE_ONLY = ( 1UL << MBG_PTP_V2_NG_DFLT_DS_FLAG_SLAVE_ONLY) +}; + +/** + * @brief PTPv2 default dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.1 and 15.5.3.3.1 + * + * @see ::MBG_PTP_V2_DEFAULT_DATASET_FLAGS + * @see ::PTP_CLOCK_QUALITY + * @see ::PTP_CLOCK_ID + */ +typedef struct mbg_ptp_v2_ng_default_dataset_s +{ + uint8_t flags; ///< flags field, see ::MBG_PTP_V2_NG_DFLT_DS_FLAGS + uint8_t reserved_1; ///< reserved, currently always 0 + uint16_t number_ports; ///< number of PTP ports on the device + PTP_CLOCK_QUALITY clock_quality; ///< quality of the local clock, see ::PTP_CLOCK_QUALITY + uint8_t priority_1; ///< priority 1 attribute for the local clock + uint8_t priority_2; ///< priority 2 attribute for the local clock + uint8_t domain_number; ///< domain attribute of the local clock + uint8_t reserved_2; ///< reserved, currently always 0 + uint32_t reserved_3; + PTP_CLOCK_ID clock_identity; ///< identity of the local clock, see ::PTP_CLOCK_ID + +} MBG_PTP_V2_NG_DEFAULT_DATASET; + + +#define _mbg_swab_ptp_v2_ng_default_dataset( _p ) \ +{ \ + _mbg_swab16( &(_p)->number_ports ); \ + _mbg_swab_ptp_clock_quality( &(_p)->clock_quality ); \ + _mbg_swab_ptp_clock_id( &(_p)->clock_identity ); \ +} + + +/** * @brief PTPv2 current dataset * * @note For further information, see IEEE 1588-2008, chapters 8.2.2 and 15.5.3.4.1 @@ -14915,6 +15946,32 @@ typedef struct } + +/** + * @brief PTPv2 current dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.2 and 15.5.3.4.1 + * + * @see ::PTP_TIME_INTERVAL + */ +typedef struct mbg_ptp_v2_ng_current_dataset_s +{ + PTP_TIME_INTERVAL offset_from_master; ///< current time difference between master and slave, see ::PTP_TIME_INTERVAL + PTP_TIME_INTERVAL mean_path_delay; ///< current mean propagation time between master and slave, see ::PTP_TIME_INTERVAL + uint16_t steps_removed; ///< number of communication paths between local clock and grandmaster + uint16_t reserved_1; + uint32_t reserved_2; +} MBG_PTP_V2_NG_CURRENT_DATASET; + + +#define _mbg_swab_ptp_v2_ng_current_dataset( _p ) \ +{ \ + _mbg_swab_ptp_time_interval( &(_p)->offset_from_master ); \ + _mbg_swab_ptp_time_interval( &(_p)->mean_path_delay ); \ + _mbg_swab16( &(_p)->steps_removed ); \ +} + + /** * @brief Flags structure for the PTPv2 parent dataset * @@ -14949,14 +16006,14 @@ typedef struct PTP_PORT_IDENTITY parent_port_identity; ///< Identity of the master port, that issues the sync messages, see ::PTP_PORT_IDENTITY MBG_PTP_V2_PARENT_DATASET_FLAGS flags; ///< Flags field, see ::MBG_PTP_V2_PARENT_DATASET_FLAGS uint8_t reserved; ///< Reserved, currently always 0 - uint16_t parent_log_variance; ///< Estimate of the parent clock's PTP variance, only valid if - ///< ::MBG_PTP_V2_PARENT_DATASET_FLAGS::parent_stats is set in ::MBG_PTP_V2_PARENT_DATASET::flags - int32_t parent_phase_change_rate; ///< Estimate of the parent clock's phase change rate, only valid if - ///< ::MBG_PTP_V2_PARENT_DATASET_FLAGS::parent_stats is set in ::MBG_PTP_V2_PARENT_DATASET::flags - uint8_t grandmaster_priority_1; ///< Priority 1 attribute of the grandmaster clock - PTP_CLOCK_QUALITY grandmaster_clock_quality; ///< Quality of the grandmaster clock, see ::PTP_CLOCK_QUALITY - uint8_t grandmaster_priority_2; ///< Priority 2 attribute of the grandmaster clock - PTP_CLOCK_ID grandmaster_identity; ///< Identity of the grandmaster clock, see ::PTP_CLOCK_ID + uint16_t parent_log_variance; ///< Estimate of the PTP variance of the parent clock. Only valid if + ///< ::MBG_PTP_V2_PARENT_DATASET_FLAGS::parent_stats is set in ::MBG_PTP_V2_PARENT_DATASET::flags. + int32_t parent_phase_change_rate; ///< Estimate of the phase change rate of the parent clock. Only valid if + ///< ::MBG_PTP_V2_PARENT_DATASET_FLAGS::parent_stats is set in ::MBG_PTP_V2_PARENT_DATASET::flags. + uint8_t grandmaster_priority_1; ///< Priority 1 attribute of the grandmaster clock. + PTP_CLOCK_QUALITY grandmaster_clock_quality; ///< Quality of the grandmaster clock, see ::PTP_CLOCK_QUALITY. + uint8_t grandmaster_priority_2; ///< Priority 2 attribute of the grandmaster clock. + PTP_CLOCK_ID grandmaster_identity; ///< Identity of the grandmaster clock, see ::PTP_CLOCK_ID. } MBG_PTP_V2_PARENT_DATASET; @@ -14975,6 +16032,63 @@ typedef struct } + +/** + * @brief Flags structure for the PTPv2 NG parent dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.3.3 and 15.5.3.5.1.2 + * + * @see ::MBG_PTP_V2_NG_PARENT_DATASET + */ +enum MBG_PTP_V2_NG_PARENT_DATASET_FLAGS +{ + MBG_PTP_V2_NG_PARENT_DS_FLAG_PARENT_STATS, + N_MBG_PTP_V2_NG_PARENT_DS_FLAGS +}; + +enum MBG_PTP_V2_NG_PARENT_DATASET_FLAG_MASKS +{ + MBG_PTP_V2_NG_PARENT_DS_FLAG_MSK_PARENT_STATS = ( 1UL << MBG_PTP_V2_NG_PARENT_DS_FLAG_PARENT_STATS), +}; + +/** + * @brief PTPv2 NG parent dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.3 and 15.5.3.5.1 + * + * @see ::PTP_NG_PORT_IDENTITY + * @see ::MBG_PTP_V2_NG_PARENT_DATASET_FLAGS + * @see ::PTP_CLOCK_QUALITY + * @see ::PTP_CLOCK_ID + */ +typedef struct mbg_ptp_v2_ng_parent_dataset_s +{ + PTP_NG_PORT_IDENTITY parent_port_identity; ///< Identity of the master port, that issues the sync messages, see ::PTP_NG_PORT_IDENTITY. + uint8_t flags; ///< Flags field, see ::MBG_PTP_V2_NG_PARENT_DATASET_FLAGS. + uint8_t reserved_1; ///< Reserved, currently always 0. + uint16_t parent_log_variance; ///< Estimate of the PTP variance of the parent clock, only valid if + ///< ::MBG_PTP_V2_NG_PARENT_DS_FLAG_MSK_PARENT_STATS is set. + int32_t parent_phase_change_rate; ///< Estimate of the phase change rate of the parent clock, only valid if + ///< ::MBG_PTP_V2_NG_PARENT_DS_FLAG_MSK_PARENT_STATS is set. + PTP_CLOCK_QUALITY grandmaster_clock_quality; ///< Quality of the grandmaster clock, see ::PTP_CLOCK_QUALITY. + uint8_t grandmaster_priority_1; ///< Priority 1 attribute of the grandmaster clock. + uint8_t grandmaster_priority_2; ///< Priority 2 attribute of the grandmaster clock. + uint16_t reserved_2; + PTP_CLOCK_ID grandmaster_identity; ///< Identity of the grandmaster clock, see ::PTP_CLOCK_ID. + +} MBG_PTP_V2_NG_PARENT_DATASET; + + +#define _mbg_swab_ptp_v2_ng_parent_dataset( _p ) \ +{ \ + _mbg_swab_ptp_ng_port_identity( &(_p)->parent_port_identity ); \ + _mbg_swab16( &(_p)->parent_log_variance ); \ + _mbg_swab32( &(_p)->parent_phase_change_rate ); \ + _mbg_swab_ptp_clock_quality( &(_p)->grandmaster_clock_quality ); \ + _mbg_swab_ptp_clock_id( &(_p)->grandmaster_identity ); \ +} + + /** * @brief Flags structure for the PTPv2 time properties dataset * @@ -14984,11 +16098,11 @@ typedef struct */ typedef struct { - uint8_t leap_61 : 1; ///< set, if the last minute of the current UTC day containts 61 seconds - uint8_t leap_59 : 1; ///< set, if the last minute of the current UTC day containts 59 seconds - uint8_t utc_offset_valid : 1; ///< set, if the current UTC offset is known to be correct + uint8_t leap_61 : 1; ///< set, if the last minute of the current %UTC day has 61 seconds + uint8_t leap_59 : 1; ///< set, if the last minute of the current %UTC day has 59 seconds + uint8_t utc_offset_valid : 1; ///< set, if the current %UTC offset is known to be correct uint8_t ptp_timescale : 1; ///< set, if the timescale of the grandmaster clock is PTP - uint8_t time_traceable : 1; ///< set, if timescale and utc offset are traceable to a primary reference + uint8_t time_traceable : 1; ///< set, if timescale and %UTC offset are traceable to a primary reference uint8_t frequency_traceable : 1; ///< set, if the frequency determining the timescale is traceable to a primary reference uint8_t reserved : 2; ///< reserved, currently always 0 @@ -15008,7 +16122,7 @@ typedef struct */ typedef struct { - int16_t current_utc_offset; ///< offset between TAI and UTC in seconds + int16_t current_utc_offset; ///< offset between TAI and %UTC in seconds MBG_PTP_V2_TIME_PROPERTIES_DATASET_FLAGS flags; ///< flags field, see ::MBG_PTP_V2_TIME_PROPERTIES_DATASET_FLAGS uint8_t time_source; ///< source of time used by the grandmaster clock, see ::PTP_TIME_SOURCES @@ -15023,6 +16137,50 @@ typedef struct } +enum MBG_PTP_V2_NG_TIME_PROPERTIES_DATASET_FLAGS +{ + MBG_PTP_V2_NG_TPROP_DS_FLAG_LEAP_61, + MBG_PTP_V2_NG_TPROP_DS_FLAG_LEAP_59, + MBG_PTP_V2_NG_TPROP_DS_FLAG_UTC_OFFSET_VALID, + MBG_PTP_V2_NG_TPROP_DS_FLAG_PTP_TIMESCALE, + MBG_PTP_V2_NG_TPROP_DS_FLAG_TIME_TRACEABLE, + MBG_PTP_V2_NG_TPROP_DS_FLAG_FREQUENCY_TRACEABLE, + N_MBG_PTP_V2_NG_TPROP_DS_FLAGS +}; + +enum MBG_PTP_V2_NG_TIME_PROPERTIES_DATASET_FLAG_MASKS +{ + MBG_PTP_V2_NG_TPROP_DS_FLAG_MSK_LEAP_61 = ( 1UL << MBG_PTP_V2_NG_TPROP_DS_FLAG_LEAP_61), + MBG_PTP_V2_NG_TPROP_DS_FLAG_MSK_LEAP_59 = ( 1UL << MBG_PTP_V2_NG_TPROP_DS_FLAG_LEAP_59), + MBG_PTP_V2_NG_TPROP_DS_FLAG_MSK_UTC_OFFSET_VALID = ( 1UL << MBG_PTP_V2_NG_TPROP_DS_FLAG_UTC_OFFSET_VALID), + MBG_PTP_V2_NG_TPROP_DS_FLAG_MSK_PTP_TIMESCALE = ( 1UL << MBG_PTP_V2_NG_TPROP_DS_FLAG_PTP_TIMESCALE), + MBG_PTP_V2_NG_TPROP_DS_FLAG_MSK_TIME_TRACEABLE = ( 1UL << MBG_PTP_V2_NG_TPROP_DS_FLAG_TIME_TRACEABLE), + MBG_PTP_V2_NG_TPROP_DS_FLAG_MSK_FREQUENCY_TRACEABLE = ( 1UL << MBG_PTP_V2_NG_TPROP_DS_FLAG_FREQUENCY_TRACEABLE) +}; + + +/** + * @brief PTPv2 time properties dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.4 and 15.5.3.6.1 + * + * @see ::MBG_PTP_V2_TIME_PROPERTIES_DATASET_FLAGS + */ +typedef struct mbg_ptp_v2_ng_time_properties_dataset_s +{ + int16_t current_utc_offset; ///< offset between TAI and %UTC in seconds + uint8_t flags; ///< flags field, see ::MBG_PTP_V2_NG_TIME_PROPERTIES_DATASET_FLAGS + uint8_t time_source; ///< source of time used by the grandmaster clock, see ::PTP_TIME_SOURCES + uint32_t reserved; +} MBG_PTP_V2_NG_TIME_PROPERTIES_DATASET; + + +#define _mbg_swab_ptp_v2_ng_time_properties_dataset( _p ) \ +{ \ + _mbg_swab16( &(_p)->current_utc_offset ); \ +} + + /** * @brief PTPv2 port dataset * @@ -15063,17 +16221,67 @@ typedef struct } +typedef struct +{ + int8_t ann_intv; + int8_t sync_intv; + int8_t del_req_intv; + int8_t pdel_req_intv; + +} MBG_PTP_NG_INTV_CFG; + + +#define _mbg_swab_ptp_ng_intv_cfg( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->ann_intv ); \ + _mbg_swab8( &(_p)->sync_intv ); \ + _mbg_swab8( &(_p)->del_req_intv ); \ + _mbg_swab8( &(_p)->pdel_req_intv ); \ +} while ( 0 ) + + +/** + * @brief PTPv2 port dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.5 and 15.5.3.7.1 + * + * @see ::PTP_PORT_IDENTITY + * @see ::PTP_TIME_INTERVAL + * @see ::MBG_PTP_V2_PORT_DATASET_IDX + */ +typedef struct mbg_ptp_v2_ng_port_dataset_s +{ + PTP_TIME_INTERVAL peer_mean_path_delay; ///< estimate of the current one-way propagation delay on the link, only valid if P2P is used, see ::PTP_TIME_INTERVAL + PTP_NG_PORT_IDENTITY port_identity; ///< identity of the local port, see ::PTP_PORT_IDENTITY + MBG_PTP_NG_INTV_CFG intvs; ///< interval settings for this port, see ::MBG_PTP_NG_INTV_CFG + uint8_t port_state; ///< state of the protocol engine associated with this port, see ::PTP_PORT_STATES + uint8_t announce_receipt_timeout; ///< shall be an integral multiple of ::MBG_PTP_V2_PORT_DATASET::log_announce_interval + uint8_t delay_mechanism; ///< propagation delay measuring option, see ::PTP_DELAY_MECHS + uint8_t version_number; ///< PTP version in use on the port + +} MBG_PTP_V2_NG_PORT_DATASET; + + +#define _mbg_swab_ptp_v2_ng_port_dataset( _p ) \ +{ \ + _mbg_swab_ptp_time_interval( &(_p)->peer_mean_path_delay ); \ + _mbg_swab_ptp_ng_port_identity( &(_p)->port_identity ); \ + _mbg_swab_ptp_ng_intv_cfg( &(_p)->intvs ); \ +} + + /** * @brief Index structure for PTPv2 port dataset * - * @note Port dataset with index 0..::MBG_PTP_V2_DEFAULT_DATASET::number_ports - 1 can be queried from a device + * @note Port dataset with index 0..::MBG_PTP_V2_DEFAULT_DATASET::number_ports-1 can be queried from a device. * * @see ::MBG_PTP_V2_PORT_DATASET */ typedef struct { - uint16_t idx; ///< Index of the port dataset, 0..::MBG_PTP_V2_DEFAULT_DATASET::number_ports - 1 - MBG_PTP_V2_PORT_DATASET port_dataset; ///< see ::MBG_PTP_V2_PORT_DATASET + MBG_MSG_IDX idx; ///< Index of the port dataset, 0..::MBG_PTP_V2_DEFAULT_DATASET::number_ports-1. + MBG_PTP_V2_PORT_DATASET port_dataset; ///< See ::MBG_PTP_V2_PORT_DATASET. } MBG_PTP_V2_PORT_DATASET_IDX; @@ -15084,6 +16292,1689 @@ typedef struct _mbg_swab_ptp_v2_port_dataset( &(_p)->port_dataset ); \ } +/** + * @brief Index structure for PTPv2 port dataset + * + * @note Port dataset with index 0..::MBG_PTP_V2_DEFAULT_DATASET::number_ports - 1 can be queried from a device + * + * @see ::MBG_PTP_V2_PORT_DATASET + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; ///< Index of the port dataset, 0..::MBG_PTP_V2_DEFAULT_DATASET::number_ports - 1 + uint32_t reserved; + MBG_PTP_V2_NG_PORT_DATASET port_dataset; ///< See ::MBG_PTP_V2_PORT_DATASET + +} MBG_PTP_V2_NG_PORT_DATASET_IDX; + + +/** + * @defgroup group_ptp_ng Next gen structures and definitions used with PTP/IEEE1588 + * + * @{ */ + +typedef char PTP_INTF[MBG_IFNAMSIZ]; ///< interface name (IPv4/L2) or IPv6 address of logical interface linked to this config + + +/** + * @brief PTP version flags + * + * @see ::PTP_NG_VERSION_MASKS + */ +enum PTP_NG_VERSION_FLAGS +{ + PTP_NG_VERSION_1 = 0, + PTP_NG_VERSION_2, + PTP_NG_VERSION_2_1, + N_PTP_NG_VERSIONS +}; + + +/** + * @brief PTP version flag masks used with ::MBG_PTP_NG_GLB_INFO::supp_versions + * + * @see ::PTP_NG_VERSION_FLAGS + */ +enum PTP_NG_VERSION_MASKS +{ + PTP_NG_VERSION_1_MSK = ( 1UL << PTP_NG_VERSION_1 ), ///< See ::PTP_NG_VERSION_1 + PTP_NG_VERSION_2_MSK = ( 1UL << PTP_NG_VERSION_2 ), ///< See ::PTP_NG_VERSION_2 + PTP_NG_VERSION_2_1_MSK = ( 1UL << PTP_NG_VERSION_2_1 ) ///< See ::PTP_NG_VERSION_2_1 +}; + + +#define PTP_NG_VERSION_STRS \ +{ \ + "PTPv1", \ + "PTPv2", \ + "PTPv2.1" \ +} + + +enum MBG_PTP_NG_FLAGS +{ + MBG_PTP_NG_FLAG_ARB_TIMESCALE, ///< Use arbitrary timescale instead of default PTP (TAI) timescale + MBG_PTP_NG_FLAG_V1_HW_COMPATIBILITY, ///< V1 hardware compatibility is used (fill Sync Message with padding bytes) + MBG_PTP_NG_FLAG_BOUNDARY_CLOCK, ///< Indicates, that an instance is part of a boundary clock setup + MBG_PTP_NG_FLAG_SW_TSTAMPING, ///< No hardware timestamps are used + MBG_PTP_NG_FLAG_MANAGEMENT, ///< PTP Management Messages are enabled + MBG_PTP_NG_FLAG_NO_CLK_ADJ, ///< No Adjustment of the hardware clock in slave mode (measurement only) + MBG_PTP_NG_FLAG_PATH_TRACE, ///< Use path trace TLV + MBG_PTP_NG_FLAG_CUSTOM_PORT_ID, ///< A user-defined CLOCK IDENTITY is used for this PTP instance + MBG_PTP_NG_FLAG_FIXED_QUALITY, ///< A user-defined set of fixed BMCA parameters is configured + MBG_PTP_NG_FLAG_AUTHENTICATION, ///< Use authentication as used in PTP v2.1 + MBG_PTP_NG_FLAG_DELAY_ASYMMETRY, ///< Delay asymmetry configuration is supported + MBG_PTP_NG_FLAG_GLB_CLOCK_ID, ///< Use system-wide clock ID for all instances, otherwise use one ID per phys port + MBG_PTP_NG_FLAG_SERVO_SETTINGS, ///< User-defined servo settings, see ::MBG_PTP_NG_SERVO_SETTINGS + MBG_PTP_NG_FLAG_HYBRID_MODE, ///< Use hybrid mode (DelReq. in unicast) + MBG_PTP_NG_FLAG_PKT_CNTRS, ///< Indicates, that an instance supplies packet counters, see ::MBG_PTP_NG_INSTC_PKT_CNTRS + MBG_PTP_NG_FLAG_MIN_GM_CLK_QUALITY, ///< User-defined set of minimum clock quality parameters for synchronization + MBG_PTP_NG_FLAG_DISABLED, ///< Indicates, that an instance is temporarily disabled + N_MBG_PTP_NG_FLAGS +}; + + +enum MBG_PTP_NG_FLAG_MASKS +{ + MBG_PTP_NG_FLAG_ARB_TIMESCALE_MSK = ( 1UL << MBG_PTP_NG_FLAG_ARB_TIMESCALE ), ///< See ::MBG_PTP_NG_FLAG_ARB_TIMESCALE + MBG_PTP_NG_FLAG_V1_HW_COMPATIBILITY_MSK = ( 1UL << MBG_PTP_NG_FLAG_V1_HW_COMPATIBILITY ), ///< See ::MBG_PTP_NG_FLAG_V1_HW_COMPATIBILITY + MBG_PTP_NG_FLAG_BOUNDARY_CLOCK_MSK = ( 1UL << MBG_PTP_NG_FLAG_BOUNDARY_CLOCK ), ///< See ::MBG_PTP_NG_FLAG_BOUNDARY_CLOCK + MBG_PTP_NG_FLAG_SW_TSTAMPING_MSK = ( 1UL << MBG_PTP_NG_FLAG_SW_TSTAMPING ), ///< See ::MBG_PTP_NG_FLAG_SW_TSTAMPING + MBG_PTP_NG_FLAG_MANAGEMENT_MSK = ( 1UL << MBG_PTP_NG_FLAG_MANAGEMENT ), ///< See ::MBG_PTP_NG_FLAG_MANAGEMENT + MBG_PTP_NG_FLAG_NO_CLK_ADJ_MSK = ( 1UL << MBG_PTP_NG_FLAG_NO_CLK_ADJ ), ///< See ::MBG_PTP_NG_FLAG_NO_CLK_ADJ + MBG_PTP_NG_FLAG_PATH_TRACE_MSK = ( 1UL << MBG_PTP_NG_FLAG_PATH_TRACE ), ///< See ::MBG_PTP_NG_FLAG_PATH_TRACE + MBG_PTP_NG_FLAG_CUSTOM_PORT_ID_MSK = ( 1UL << MBG_PTP_NG_FLAG_CUSTOM_PORT_ID ), ///< See ::MBG_PTP_NG_FLAG_CUSTOM_PORT_ID + MBG_PTP_NG_FLAG_FIXED_QUALITY_MSK = ( 1UL << MBG_PTP_NG_FLAG_FIXED_QUALITY ), ///< See ::MBG_PTP_NG_FLAG_FIXED_QUALITY + MBG_PTP_NG_FLAG_AUTHENTICATION_MSK = ( 1UL << MBG_PTP_NG_FLAG_AUTHENTICATION ), ///< See ::MBG_PTP_NG_FLAG_AUTHENTICATION + MBG_PTP_NG_FLAG_DELAY_ASYMMETRY_MSK = ( 1UL << MBG_PTP_NG_FLAG_DELAY_ASYMMETRY ), ///< See ::MBG_PTP_NG_FLAG_DELAY_ASYMMETRY + MBG_PTP_NG_FLAG_GLB_CLOCK_ID_MSK = ( 1UL << MBG_PTP_NG_FLAG_GLB_CLOCK_ID ), ///< See ::MBG_PTP_NG_FLAG_GLB_CLOCK_ID + MBG_PTP_NG_FLAG_SERVO_SETTINGS_MSK = ( 1UL << MBG_PTP_NG_FLAG_SERVO_SETTINGS ), ///< See ::MBG_PTP_NG_FLAG_SERVO_SETTINGS + MBG_PTP_NG_FLAG_HYBRID_MODE_MSK = ( 1UL << MBG_PTP_NG_FLAG_HYBRID_MODE ), ///< See ::MBG_PTP_NG_FLAG_HYBRID_MODE + MBG_PTP_NG_FLAG_PKT_CNTRS_MSK = ( 1UL << MBG_PTP_NG_FLAG_PKT_CNTRS ), ///< See ::MBG_PTP_NG_FLAG_PKT_CNTRS + MBG_PTP_NG_FLAG_MIN_GM_CLK_QUALITY_MSK = ( 1UL << MBG_PTP_NG_FLAG_MIN_GM_CLK_QUALITY ), ///< See ::MBG_PTP_NG_FLAG_MIN_GM_CLK_QUALITY + MBG_PTP_NG_FLAG_DISABLED_MSK = ( 1UL << MBG_PTP_NG_FLAG_DISABLED ) ///< See ::MBG_PTP_NG_FLAG_DISABLED +}; + + +enum MBG_PTP_NG_V1_FLAGS +{ + MBG_PTP_NG_V1_FLAG_PREFERRED, ///< Set preferred flag in PTPv1 stack + MBG_PTP_NG_V1_FLAG_INITIALIZABLE, ///< Set initializable flag in PTPv1 stack + MBG_PTP_NG_V1_FLAG_EXT_TIMING, ///< Set external timing flag in PTPv1 stack + N_MBG_PTP_NG_V1_FLAGS +}; + + +enum MBG_PTP_NG_V1_FLAG_MASKS +{ + MBG_PTP_NG_V1_FLAG_PREFERRED_MSK = ( 1UL << MBG_PTP_NG_V1_FLAG_PREFERRED ), ///< See ::MBG_PTP_NG_V1_FLAG_PREFERRED + MBG_PTP_NG_V1_FLAG_INITIALIZABLE_MSK = ( 1UL << MBG_PTP_NG_V1_FLAG_INITIALIZABLE ), ///< See ::MBG_PTP_NG_V1_FLAG_INITIALIZABLE + MBG_PTP_NG_V1_FLAG_EXT_TIMING_MSK = ( 1UL << MBG_PTP_NG_V1_FLAG_EXT_TIMING ) ///< See ::MBG_PTP_NG_V1_FLAG_EXT_TIMING +}; + + +/** + * @brief Pre-defined alternate time offset indicators + */ +enum MBG_PTP_NG_ATOIS +{ + MBG_PTP_NG_ATOI_UTC, ///< %UTC (Coordinated Universal Time), meaning an almost empty ATOI (minimum requirement for C37.238-2011). + MBG_PTP_NG_ATOI_CUSTOM, ///< Custom, manually configured ATOI stored as ::TZDL structure. + MBG_PTP_NG_ATOI_CET_CEST, ///< CET/CEST (Central European (Summer) Time). + N_MBG_PTP_NG_ATOIS +}; + + +enum MBG_PTP_NG_ATOI_MASKS +{ + MBG_PTP_NG_ATOI_UTC_MSK = ( 1UL << MBG_PTP_NG_ATOI_UTC ), ///< See ::MBG_PTP_NG_ATOI_UTC + MBG_PTP_NG_ATOI_CUSTOM_MSK = ( 1UL << MBG_PTP_NG_ATOI_CUSTOM ), ///< See ::MBG_PTP_NG_ATOI_CUSTOM + MBG_PTP_NG_ATOI_CET_CEST_MSK = ( 1UL << MBG_PTP_NG_ATOI_CET_CEST ) ///< See ::MBG_PTP_NG_ATOI_CET_CEST +}; + + +#define MBG_PTP_NG_ATOI_SHORT_NAMES \ +{ \ + "UTC", \ + "Custom", \ + "CET/CEST" \ +} + + +#define MBG_PTP_NG_ATOI_NAMES \ +{ \ + "UTC (Coordinated Universal Time)", \ + "Custom", \ + "CET/CEST (Central European [Summer] Time)" \ +} + + + +/** + * @brief Predefined time scales for PTP SMPTE jam event times. + * + * Used with ::MBG_PTP_NG_SMPTE_20592_SETTINGS::event_timescale, + * and to define ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_MASKS. + * + * This is only relevant for the way the ***configuration is stored***, + * and the effective time sent in the SMPTE TLV has to be calculated + * by the appropriate time scale conversion. + * + * @see ::MBG_PTP_NG_SMPTE_20592_SETTINGS::event_timescale + * @see ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_MASKS + */ +enum MBG_PTP_NG_SMPTE_EVT_TIMESCALES +{ + /// @brief Time scale refers to local time. + /// + /// If the local time scale is used to configure the daily jam + /// then the jam occurs at exactly the same time, e.g. always + /// at 2 o'clock according to the configured time zone, regardless + /// whether DST is in effect, or not, and it is not affected by + /// another leap second that might be inserted at some point + /// during operation. + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_LOCAL_TIME, + + /// @brief Time scale refers to %UTC. + /// + /// If %UTC is used for the configuration then the jam always occurs + /// at exactly the same %UTC time, which is not affected by another + /// leap second that might be inserted at some point during operation. + /// + /// However, the local time when the jam occurs depends on the + /// local time zone offset, and on the DST status of the + /// configured time zone. + /// + /// For example, if 3 o'clock %UTC has been configured and the + /// local time zone is CET/CEST (i.e. %UTC+1h/%UTC+2h), + /// the jam occurs at 4 o'clock while DST is not in effect, + /// and at 5 o'clock if DST is in effect. + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_UTC, + + /// @brief Time scale refers to TAI. + /// + /// If the jam times are configured using the TAI time scale, + /// the effective local time sent in the SMPTE TLV depends on + /// the local time zone offset and DST status just as for + /// ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_UTC, but in addition + /// changes whenefer the TAI/%UTC offset changes due to + /// a leap second. + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_TAI, + + /// @brief Time scale refers to GPS system time. + /// + /// Basically the same behavior as with ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_TAI, + /// except that an additional constant offset ::GPS_SEC_BIAS has to be + /// taken into account. + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_GPS, + + ///< The number of predefined SMPTE event time scales. + N_MBG_PTP_NG_SMPTE_EVT_TIMESCALES +}; + + + +/** + * @brief Bit masks of predefined time scales for PTP SMPTE jam event times. + * + * Used with ::MBG_PTP_NG_GLB_INFO::supp_smpte_tscales. + * + * @see ::MBG_PTP_NG_SMPTE_EVT_TIMESCALES + */ +enum MBG_PTP_NG_SMPTE_EVT_TIMESCALE_MASKS +{ + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_LOCAL_TIME_MSK = ( 1UL << MBG_PTP_NG_SMPTE_EVT_TIMESCALE_LOCAL_TIME ), ///< See ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_LOCAL_TIME. + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_UTC_MSK = ( 1UL << MBG_PTP_NG_SMPTE_EVT_TIMESCALE_UTC ), ///< See ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_UTC. + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_TAI_MSK = ( 1UL << MBG_PTP_NG_SMPTE_EVT_TIMESCALE_TAI ), ///< See ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_TAI. + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_GPS_MSK = ( 1UL << MBG_PTP_NG_SMPTE_EVT_TIMESCALE_GPS ) ///< See ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_GPS. +}; + + +#define MBG_PTP_NG_SMPTE_EVT_TIMESCALE_STRS \ +{ \ + "PTP (TAI)", \ + "UTC", \ + "Local Time", \ + "GPS" \ +} + + +typedef struct +{ + uint16_t num_instances; ///< Number of currently configured PTP instances. + uint16_t num_uc_masters; ///< Total number of currently configured unicast masters. + uint32_t flags; ///< Current flags, see ::MBG_PTP_NG_FLAG_MASKS. + + uint32_t reserved_2[6]; ///< Reserved, currently always 0. + +} MBG_PTP_NG_GLB_SETTINGS; + + +#define _mbg_swab_ptp_ng_glb_settings( _p ) \ +{ \ + _mbg_swab16( &(_p)->num_instances ); \ + _mbg_swab16( &(_p)->num_uc_masters ); \ + _mbg_swab32( &(_p)->flags ); \ +} + + + +typedef struct mbg_ptp_ng_glb_info_s +{ + MBG_PTP_NG_GLB_SETTINGS settings; ///< The current global configuration for this firmware. + + PTP_CLOCK_ID system_clock_id; ///< System-wide global clock ID, which can be used by all instances. + ///< Only supp., if ::MBG_PTP_NG_FLAG_GLB_CLOCK_ID_MSK is set in ::MBG_PTP_NG_GLB_INFO::supp_flags. + ///< Only used, if ::MBG_PTP_NG_FLAG_GLB_CLOCK_ID_MSK is set in ::MBG_PTP_NG_GLB_SETTINGS::flags. + + uint16_t num_timestampers; ///< Total number of hardware timestampers for this firmware. + uint16_t max_instances; ///< Maximum number of PTP instances (software) for this firmware. + + uint16_t max_uc_masters; ///< Maximum number of uncast masters that can be configured in total for this firmware. + uint16_t max_instc_uc_masters; ///< Maximum number of unicast masters per instance. + + uint32_t supp_protocols; ///< Bitmask of supported network protocols, see ::PTP_NW_PROT_MASKS. + uint32_t supp_delay_mechs; ///< Bit mask of supported delay mechanisms, see ::PTP_DELAY_MECH_MASKS. + uint32_t supp_profiles; ///< Bit mask of supported PTP profiles, see ::PTP_PRESETS: + uint32_t supp_versions; ///< Bit mask of supported PTP protocol versions, see ::PTP_NG_VERSION_MASKS. + uint32_t supp_roles; ///< Bit mask of supported PTP roles, see ::PTP_ROLE_MASKS. + uint32_t supp_flags; ///< Bit mask of supported flags, see ::MBG_PTP_NG_FLAG_MASKS. + uint32_t supp_v1_flags; ///< Bit mask of supported PTPv1 flags, see ::MBG_PTP_NG_V1_FLAG_MASKS. + uint32_t supp_atois; ///< Bit mask of supported Alternate Time Offset Indicators (ATOIs), see ::MBG_PTP_NG_ATOI_MASKS. + + MBG_PTP_NG_INTV_CFG intvs_min; ///< log2 of minimum intervals [s] + MBG_PTP_NG_INTV_CFG intvs_max; ///< log2 of maximum intervals [s] + + uint16_t max_atois; ///< Maximum number of ATOIs that may be used in parallel, see ::MBG_PTP_NG_ATOI_MASKS. + uint16_t supp_smpte_tscales; ///< Bit mask of supported SMPTE event timescales, see ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_MASKS. + uint32_t reserved_2[7]; ///< Reserved, currently always 0. + +} MBG_PTP_NG_GLB_INFO; + + +#define _mbg_swab_ptp_ng_glb_info( _p ) \ +{ \ + _mbg_swab_ptp_ng_glb_settings( &(_p)->settings ); \ + _mbg_swab16( &(_p)->num_timestampers ); \ + _mbg_swab16( &(_p)->max_instances ); \ + _mbg_swab16( &(_p)->max_uc_masters ); \ + _mbg_swab16( &(_p)->max_instc_uc_masters ); \ + _mbg_swab32( &(_p)->supp_protocols ); \ + _mbg_swab32( &(_p)->supp_delay_mechs ); \ + _mbg_swab32( &(_p)->supp_profiles ); \ + _mbg_swab32( &(_p)->supp_versions ); \ + _mbg_swab32( &(_p)->supp_roles ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->supp_v1_flags ); \ + _mbg_swab32( &(_p)->supp_atois ); \ + _mbg_swab_ptp_ng_intv_cfg( &(_p)->intvs_min ); \ + _mbg_swab_ptp_ng_intv_cfg( &(_p)->intvs_max ); \ + _mbg_swab16( &(_p)->max_atois ); \ +} + + +typedef struct +{ + uint16_t sec_h; ///< Seconds (47:32) + uint16_t reserved_1; + uint32_t reserved_2; + uint32_t sec_l; ///< Seconds (31:0) + uint32_t nsec; ///< Nanoseconds + +} MBG_PTP_NG_TIMESTAMP; + + +#define _mbg_swab_ptp_ng_timestamp( _p ) \ +{ \ + _mbg_swab16( &(_p)->sec_h ); \ + _mbg_swab32( &(_p)->sec_l ); \ + _mbg_swab32( &(_p)->nsec ); \ +} + + +/** + * @brief PTP timestamper modes + * + * @see ::PTP_NG_TSTAMPER_MODE_MASKS + */ +enum PTP_NG_TSTAMPER_MODES +{ + PTP_NG_TSTAMPER_MODE_ALL, ///< Timestamp all incoming packets. + PTP_NG_TSTAMPER_MODE_NTP, ///< Timestamp only NTP packets. + PTP_NG_TSTAMPER_MODE_PTP_V1, ///< Timestamp only PTPv1 packets. + PTP_NG_TSTAMPER_MODE_PTP_V2, ///< Timestamp only PTPv2 (+2.1) packets. + N_PTP_NG_TSTAMPER_MODES +}; + + +/** + * @brief PTP timestamper mode masks used with ::MBG_PTP_NG_TSTAMPER_INFO::supp_modes + * + * @see ::PTP_NG_TSTAMPER_MODES + */ +enum PTP_NG_TSTAMPER_MODE_MASKS +{ + PTP_NG_TSTAMPER_MODE_ALL_MSK = ( 1UL << PTP_NG_TSTAMPER_MODE_ALL ), ///< See ::PTP_NG_TSTAMPER_MODE_ALL + PTP_NG_TSTAMPER_MODE_NTP_MSK = ( 1UL << PTP_NG_TSTAMPER_MODE_NTP ), ///< See ::PTP_NG_TSTAMPER_MODE_NTP + PTP_NG_TSTAMPER_MODE_PTP_V1_MSK = ( 1UL << PTP_NG_TSTAMPER_MODE_PTP_V1 ), ///< See ::PTP_NG_TSTAMPER_MODE_PTP_V1 + PTP_NG_TSTAMPER_MODE_PTP_V2_MSK = ( 1UL << PTP_NG_TSTAMPER_MODE_PTP_V2 ) ///< See ::PTP_NG_TSTAMPER_MODE_PTP_V2 +}; + + +#define PTP_NG_TSTAMPER_MODE_STRS \ +{ \ + "All", \ + "NTP", \ + "PTPv1", \ + "PTPv2" \ +} + + +/** + * @brief PTP timestamper flags + * + * @see ::PTP_NG_TSTAMPER_FLAG_MASKS + */ +enum PTP_NG_TSTAMPER_FLAGS +{ + PTP_NG_TSTAMPER_FLAG_ONE_STEP, ///< timestamp in one-step mode + PTP_NG_TSTAMPER_FLAG_PACKET_GENERATOR, ///< use packet generator to timestamp packets in hardware + PTP_NG_TSTAMPER_FLAG_HYBRID_MODE, ///< use hybrid mode (DelReq. in unicast), only when packet generator is enabled; + ///< otherwise hybrid mode can be enabled/disabled per software instance + PTP_NG_TSTAMPER_FLAG_ALL_DOMAINS, ///< timestamp PTP packets in all domains + PTP_NG_TSTAMPER_FLAG_ALL_PROTOCOLS, ///< timestamp PTP packets of all protocols + PTP_NG_TSTAMPER_FLAG_ALL_IPV6_SCOPES, ///< timestamp PTP packets in all IPv6 multicast scopes + PTP_NG_TSTAMPER_FLAG_SUPP_MULTIPLE_INSTCS, ///< timestamper supports multiple instances (VLANs), not configurable + PTP_NG_TSTAMPER_FLAG_SUPP_P2P_ONE_STEP, ///< timestamper supports P2P one-step mode, not configurable + N_PTP_NG_TSTAMPER_FLAGS +}; + + +/** + * @brief PTP timestamper flag masks used with ::MBG_PTP_NG_TSTAMPER_SETTINGS::flags and ::MBG_PTP_NG_TSTAMPER_INFO::supp_flags + * + * @see ::PTP_NG_TSTAMPER_FLAGS + */ +enum PTP_NG_TSTAMPER_FLAG_MASKS +{ + PTP_NG_TSTAMPER_FLAG_ONE_STEP_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_ONE_STEP ), ///< See ::PTP_NG_TSTAMPER_FLAG_ONE_STEP + PTP_NG_TSTAMPER_FLAG_PACKET_GENERATOR_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_PACKET_GENERATOR ), ///< See ::PTP_NG_TSTAMPER_FLAG_PACKET_GENERATOR + PTP_NG_TSTAMPER_FLAG_HYBRID_MODE_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_HYBRID_MODE ), ///< See ::PTP_NG_TSTAMPER_FLAG_HYBRID_MODE + PTP_NG_TSTAMPER_FLAG_ALL_DOMAINS_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_ALL_DOMAINS ), ///< See ::PTP_NG_TSTAMPER_FLAG_ALL_DOMAINS + PTP_NG_TSTAMPER_FLAG_ALL_PROTOCOLS_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_ALL_PROTOCOLS ), ///< See ::PTP_NG_TSTAMPER_FLAG_ALL_PROTOCOLS + PTP_NG_TSTAMPER_FLAG_ALL_IPV6_SCOPES_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_ALL_IPV6_SCOPES ), ///< See ::PTP_NG_TSTAMPER_FLAG_ALL_IPV6_SCOPES + PTP_NG_TSTAMPER_FLAG_SUPP_MULTIPLE_INSTCS_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_SUPP_MULTIPLE_INSTCS ), ///< See ::PTP_NG_TSTAMPER_FLAG_SUPP_MULTIPLE_INSTCS + PTP_NG_TSTAMPER_FLAG_SUPP_P2P_ONE_STEP_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_SUPP_P2P_ONE_STEP ) ///< See ::PTP_NG_TSTAMPER_FLAG_SUPP_P2P_ONE_STEP +}; + + +typedef struct mbg_ptp_ng_tstamper_settings_s +{ + uint8_t mode; ///< timestamper mode, see ::PTP_NG_TSTAMPER_MODES + uint8_t protocol; ///< current protocol, see ::PTP_NW_PROTS + uint8_t domain; ///< current PTPv2 domain number (0..255) + uint8_t ipv6_multicast_scope; ///< One of the ::IPV6_MULTICAST_SCOPES used for PTP IPv6 multicast. + + uint32_t flags; ///< See ::PTP_NG_TSTAMPER_FLAG_MASKS + + uint32_t reserved_2[6]; ///< reserved, currently always 0 + +} MBG_PTP_NG_TSTAMPER_SETTINGS; + + +#define _mbg_swab_ptp_ng_tstamper_settings( _p ) \ +{ \ + _mbg_swab32( &(_p)->flags ); \ +} + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< padding for 8-byte alignment, some settings contain int64_t + MBG_PTP_NG_TSTAMPER_SETTINGS settings; + +} MBG_PTP_NG_TSTAMPER_SETTINGS_IDX; + + +#define _mbg_swab_ptp_ng_tstamper_settings_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_tstamper_settings( &(_p)->settings ); \ +} + + +typedef struct mbg_ptp_ng_tstamper_info_s +{ + MBG_PTP_NG_TSTAMPER_SETTINGS settings; + + PTP_INTF phys_intf; ///< the physical interface name this timestamper belongs to + uint32_t supp_modes; ///< bitmask of supported timestamper modes, see ::PTP_NG_TSTAMPER_MODE_MASKS + uint32_t supp_protocols; ///< bitmask of supported network protocols, see ::PTP_NW_PROT_MASKS + uint32_t supp_roles; ///< bitmask of supported PTP roles on this timestamper, see ::PTP_ROLE_MASKS + uint32_t supp_flags; ///< bitmask of supported features, see ::PTP_NG_TSTAMPER_FLAG_MASKS + uint32_t max_ptp_packets; ///< Maximum number of PTP generated packets per second + uint32_t max_ntp_packets; ///< Maximum number of NTP generated packets per second + uint16_t max_ptp_uc_slaves; ///< Maximum number of PTP Unicast slaves + uint16_t reserved_1; ///< reserved, currently always 0 + + uint32_t reserved_2[5]; ///< reserved, currently always 0 + +} MBG_PTP_NG_TSTAMPER_INFO; + + +#define _mbg_swab_ptp_ng_tstamper_info( _p ) \ +{ \ + _mbg_swab_ptp_ng_tstamper_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_modes ); \ + _mbg_swab32( &(_p)->supp_protocols ); \ + _mbg_swab32( &(_p)->supp_roles ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< padding for 8-byte alignment, some settings contain int64_t + MBG_PTP_NG_TSTAMPER_INFO info; + +} MBG_PTP_NG_TSTAMPER_INFO_IDX; + + +#define _mbg_swab_ptp_ng_tstamper_info_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_tstamper_info( &(_p)->info ); \ +} + + +typedef struct mbg_ptp_ng_tstamper_status_s +{ + MBG_PTP_NG_TIMESTAMP current_time; ///< current tstamper time + PTP_TIME_INTERVAL offset_from_int_ref; ///< current offset between tstamper time and internal reference + uint8_t utilization; ///< current resource utilization (msg/sec) in % + uint8_t reserved_1[7]; ///< reserved, currently always 0 + + uint32_t reserved_2[12]; ///< reserved, currently always 0 + +} MBG_PTP_NG_TSTAMPER_STATUS; + + +#define _mbg_swab_ptp_ng_tstamper_status( _p ) \ +{ \ + _mbg_swab_ptp_ng_timestamp( &(_p)->current_time ); \ + _mbg_swab_ptp_time_interval( &(_p)->offset_from_int_ref ); \ +} + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< padding for 8-byte alignment, some settings contain int64_t + MBG_PTP_NG_TSTAMPER_STATUS status; + +} MBG_PTP_NG_TSTAMPER_STATUS_IDX; + + +#define _mbg_swab_ptp_ng_tstamper_status_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_tstamper_status( &(_p)->status ); \ +} + + +enum MBG_PTP_NG_SERVO_FLAGS +{ + MBG_PTP_NG_SERVO_FLAG_USE_IIR_FILTER, ///< TODO: Please add describing comment + MBG_PTP_NG_SERVO_FLAG_USE_SPIKE_FILTER, ///< TODO: Please add describing comment + MBG_PTP_NG_SERVO_FLAG_USE_SAMPLE_RATE_CONVERTER, ///< TODO: Please add describing comment + MBG_PTP_NG_SERVO_FLAG_COLD_START, ///< PTP stack starts with a default drift value + N_MBG_PTP_NG_SERVO_FLAGS +}; + + +enum MBG_PTP_NG_SERVO_FLAG_MASKS +{ + MBG_PTP_NG_SERVO_FLAG_USE_IIR_FILTER_MSK = (1UL << MBG_PTP_NG_SERVO_FLAG_USE_IIR_FILTER), ///< See ::MBG_PTP_NG_SERVO_FLAG_USE_IIR_FILTER + MBG_PTP_NG_SERVO_FLAG_USE_SPIKE_FILTER_MSK = (1UL << MBG_PTP_NG_SERVO_FLAG_USE_SPIKE_FILTER), ///< See ::MBG_PTP_NG_SERVO_FLAG_USE_SPIKE_FILTER + MBG_PTP_NG_SERVO_FLAG_USE_SAMPLE_RATE_CONVERTER_MSK = (1UL << MBG_PTP_NG_SERVO_FLAG_USE_SAMPLE_RATE_CONVERTER), ///< See ::MBG_PTP_NG_SERVO_FLAG_USE_SAMPLE_RATE_CONVERTER + MBG_PTP_NG_SERVO_FLAG_COLD_START_MSK = (1UL << MBG_PTP_NG_SERVO_FLAG_COLD_START), ///< See ::MBG_PTP_NG_SERVO_FLAG_COLD_START +}; + + +typedef struct +{ + int64_t inbound_delta_rate_max; ///< TODO: Please add describing comment + int64_t inbound_anti_windup_max; ///< TODO: Please add describing comment + int64_t outbound_delta_rate_max; ///< TODO: Please add describing comment + int64_t outbound_anti_windup_max; ///< TODO: Please add describing comment + + uint8_t reserved_1; ///< reserved, currently always 0 + int8_t lucky_packet_flt_depth; ///< TODO: Please add describing comment + uint16_t lucky_packet_median; ///< TODO: Please add describing comment + uint32_t flags; ///< See ::MBG_PTP_NG_SERVO_FLAG_MASKS + + uint32_t outbound_pi_k; ///< TODO: Please add describing comment + uint32_t outbound_pi_t; ///< TODO: Please add describing comment + + uint16_t iir_m2s_smin; ///< TODO: Please add describing comment + uint16_t iir_path_smin; ///< TODO: Please add describing comment + int8_t iir_log_adj_prd; ///< TODO: Please add describing comment + int8_t iir_log_adj_gain; ///< TODO: Please add describing comment + uint16_t reserved_2; ///< reserved, currently always 0 + + uint32_t inbound_pi_k; ///< TODO: Please add describing comment + uint32_t inbound_pi_t; ///< TODO: Please add describing comment + + int32_t boundary; ///< Sync Boundary in scaledNs [65536000] -> 1 microsecond + int32_t change_epoch_boundary; ///< Max epoch jump in scaledNs before hard time step is done [32768000000000] -> 0.5 sec + + uint8_t adjust_interval; ///< -8..+8 + uint8_t reserved_3; ///< reserved, currently always 0 + uint16_t reserved_4; ///< reserved, currently always 0 + uint32_t reserved_5; ///< reserved, currently always 0 + + uint32_t reserved_6[4]; ///< reserved, currently always 0 + +} MBG_PTP_NG_SERVO_SETTINGS; + + +#define _mbg_swab_ptp_ng_servo_settings( _p ) \ +{ \ + _mbg_swab64( &(_p)->inbound_delta_rate_max ); \ + _mbg_swab64( &(_p)->inbound_anti_windup_max ); \ + _mbg_swab64( &(_p)->outbound_delta_rate_max ); \ + _mbg_swab64( &(_p)->outbound_anti_windup_max ); \ + _mbg_swab16( &(_p)->lucky_packet_median ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->outbound_pi_k ); \ + _mbg_swab32( &(_p)->outbound_pi_t ); \ + _mbg_swab16( &(_p)->iir_m2s_smin ); \ + _mbg_swab16( &(_p)->iir_path_smin ); \ + _mbg_swab32( &(_p)->inbound_pi_k ); \ + _mbg_swab32( &(_p)->inbound_pi_t ); \ + _mbg_swab32( &(_p)->boundary ); \ + _mbg_swab32( &(_p)->change_epoch_boundary ); \ +} + + +typedef struct +{ + uint8_t clk_class_never_sync; ///< Fixed clock class if clock is free running, 0 means automatic + uint8_t clk_class_sync; ///< Fixed clock class if clock is synced, 0 means automatic + uint8_t clk_class_holdover; ///< Fixed clock class if clock is in holdover, 0 means automatic + uint8_t time_source; ///< Fixed PTP Time Source, 0 means automatic + uint8_t clk_accuracy; ///< Fixed clock accuracy, 0 means automatic + + uint8_t reserved_1; ///< Fixed clock accuracy, 0 means automatic + uint16_t fixed_clk_variance; ///< Fixed clock variance, 0 means automatic + + uint32_t reserved_2[4]; ///< reserved, currently always 0 + +} MBG_PTP_NG_FIXED_CLK_QLTY; + + +#define _mbg_swab_ptp_ng_fixed_clk_qlty( _p ) \ +{ \ + _mbg_swab16( &(_p)->fixed_clk_variance ); \ +} + + + +/** + * @brief Additional parameters for PTP Power Profile + */ +typedef struct +{ + uint32_t gm_time_incaccuracy; ///< Pre-defined GM time inaccuracy from master [ns] + uint32_t network_time_incaccuracy; ///< Configurable network inaccuracy from master [ns] + + uint8_t grandmaster_id; ///< [::PTP_POWER_PROFILE_GM_ID_MIN..::PTP_POWER_PROFILE_GM_ID_MAX] + uint8_t reserved[7]; ///< reserved, currently always 0 + +} MBG_PTP_NG_C37238_2011_SETTINGS; + + +#define _mbg_swab_ptp_ng_c37238_2011_settings( _p ) \ +{ \ + _mbg_swab32( &(_p)->gm_time_incaccuracy ); \ + _mbg_swab32( &(_p)->network_time_incaccuracy ); \ +} + + +typedef struct +{ + uint32_t total_inaccuracy; ///< Total inaccuracy in [ns] + uint16_t grandmaster_id; ///< Full 16 Bit Grandmaster ID + uint16_t reserved_1; ///< reserved, currently always 0 + +} MBG_PTP_NG_C37238_2017_SETTINGS; + + +#define _mbg_swab_ptp_ng_c37238_2017_settings( _p ) \ +{ \ + _mbg_swab32( &(_p)->total_inaccuracy ); \ + _mbg_swab16( &(_p)->grandmaster_id ); \ +} + + +/** + * @brief SMPTE System Frame Rates according to SMPTE ST 2059-2 + * + */ +enum MBG_PTP_NG_SMPTE_FRAME_RATES +{ + MBG_PTP_NG_SMPTE_FRAME_RATE_23_98HZ, + MBG_PTP_NG_SMPTE_FRAME_RATE_24HZ, + MBG_PTP_NG_SMPTE_FRAME_RATE_25HZ, + MBG_PTP_NG_SMPTE_FRAME_RATE_29_97HZ, + MBG_PTP_NG_SMPTE_FRAME_RATE_50HZ, + MBG_PTP_NG_SMPTE_FRAME_RATE_59_94HZ, + N_MBG_PTP_NG_SMPTE_FRAME_RATES +}; + + +#define MBG_PTP_NG_SMPTE_FRAME_RATE_STR \ +{ \ + "23.98 Hz", \ + "24 Hz", \ + "25 Hz", \ + "29.97 Hz", \ + "50 Hz", \ + "59.94 Hz" \ +} + + +#define MBG_PTP_NG_SMPTE_FRAME_RATE_NUM \ +{ \ + 24000, \ + 24000, \ + 25000, \ + 30000, \ + 50000, \ + 60000 \ +} + + +#define MBG_PTP_NG_SMPTE_FRAME_RATE_DENUM \ +{ \ + 1001, \ + 1000, \ + 1000, \ + 1001, \ + 1000, \ + 1001 \ +} + + +/** + * @brief SMPTE Time Address Flags according to SMPTE ST 2059-2 + * + */ +enum MBG_PTP_NG_SMPTE_TIME_ADDR_FLAGS +{ + MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_DROP_FRAME, + MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_COLOR_FRAME, + N_MBG_PTP_NG_SMPTE_TIME_ADDR_FLAGS +}; + + +enum MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_MASKS +{ + MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_DROP_FRAME_MSK = ( 1UL << MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_DROP_FRAME ), ///< See ::MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_DROP_FRAME + MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_COLOR_FRAME_MSK = ( 1UL << MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_COLOR_FRAME ) ///< See ::MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_COLOR_FRAME +}; + + +/** + * @brief SMPTE jam modes. + * + * Used with ::MBG_PTP_NG_SMPTE_20592_SETTINGS::next_jam_mode, which determines + * how to interpret the value in ::MBG_PTP_NG_SMPTE_20592_SETTINGS::jam_event. + */ +enum MBG_PTP_NG_SMPTE_JAM_MODES +{ + /// @brief Jam mode is disabled. + MBG_PTP_NG_SMPTE_JAM_MODE_DISABLED, + + /// @brief Daily jam at the specified seconds since midnight. + /// + /// The variable ::MBG_PTP_NG_SMPTE_20592_SETTINGS::jam_event + /// contains the number of seconds since midnight when the + /// jam is to occur. + /// The code in ::MBG_PTP_NG_SMPTE_20592_SETTINGS::event_timescale + /// indicates which time scale 'midnight' refers to. The default + /// timescale should be ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_LOCAL_TIME. + /// See ::MBG_PTP_NG_SMPTE_EVT_TIMESCALES. + MBG_PTP_NG_SMPTE_JAM_MODE_DAILY, + + /// @brief Next jam at the specified next absolute time. + /// + /// The variable ::MBG_PTP_NG_SMPTE_20592_SETTINGS::jam_event + /// contains the absolute time in POSIX time_t-like format when + /// the jam is to occur. + /// The code in ::MBG_PTP_NG_SMPTE_20592_SETTINGS::event_timescale + /// indicates the time scale associated with the time stamp. + /// See ::MBG_PTP_NG_SMPTE_EVT_TIMESCALES. + MBG_PTP_NG_SMPTE_JAM_MODE_SINGLE, + + /// @brief Next jam occurs when the local time is stepped. + /// + /// The variable ::MBG_PTP_NG_SMPTE_20592_SETTINGS::jam_event + /// contains the absolute time in POSIX time_t-like format when + /// the jam is to occur, and this time should match + /// ::MBG_PTP_NG_SMPTE_20592_STATUS::time_of_next_jump. + MBG_PTP_NG_SMPTE_JAM_MODE_NEXT_DISCONT_ON_LOCAL_TIME_CHANGE, + + N_MBG_PTP_NG_SMPTE_JAM_MODES ///< The number of known PTP SMPTE jam modes. +}; + + +#define MBG_PTP_NG_SMPTE_JAM_MODE_STRS \ +{ \ + "Disabled", \ + "Daily Jam Event", \ + "Single Jam Event", \ + "Next discontinuity in Local Time" \ +} + + +/** + * @brief Additional parameters for SMPTE ST 2059-2 profile + * + * This stucture holds the configuration for PTP NG SMPTE profile. + * The status can not be represented by this structure, because it does not contain jam and jump times + */ +typedef struct +{ + uint32_t default_frame_rate_num; ///< See ::MBG_PTP_NG_SMPTE_FRAME_RATES and ::MBG_PTP_NG_SMPTE_FRAME_RATE_NUM. + uint32_t default_frame_rate_denum; ///< See ::MBG_PTP_NG_SMPTE_FRAME_RATES and ::MBG_PTP_NG_SMPTE_FRAME_RATE_DENUM. + + uint32_t time_address_flags; ///< See ::MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_MASKS. + uint16_t reserved; ///< Reserved, currently always 0. + uint8_t next_jam_mode; ///< See ::MBG_PTP_NG_SMPTE_JAM_MODES. + uint8_t event_timescale; ///< See ::MBG_PTP_NG_SMPTE_EVT_TIMESCALES. + + /// @brief Jam event time configuration. + /// + /// Depending on the values of #next_jam_mode (see ::MBG_PTP_NG_SMPTE_JAM_MODES) + /// and #event_timescale (see ::MBG_PTP_NG_SMPTE_EVT_TIMESCALES), + /// this field can contain an absolute time for a single jam event, + /// or a number of seconds since midnight indicating when the + /// daily jam is to occur. + /// + /// The jam time sent in the SMPTE TLVs has to be calculated + /// according to these settings. + int64_t jam_event; + +} MBG_PTP_NG_SMPTE_20592_SETTINGS; + + +#define _mbg_swab_ptp_ng_smpte_20592_settings( _p ) \ +{ \ + _mbg_swab32( &(_p)->default_frame_rate_num ); \ + _mbg_swab32( &(_p)->default_frame_rate_denum ); \ + _mbg_swab32( &(_p)->time_address_flags ); \ + _mbg_swab64( &(_p)->jam_event ); \ +} + + + +enum MBG_PTP_NG_82751_FLAGS +{ + MBG_PTP_NG_82751_FLAG_USE_ALT_MC_ADDRESS, ///< Use Alternative (non-forwardable) multicast address + MBG_PTP_NG_82751_FLAG_PORT_NOT_SLAVE, ///< PTP Instance cannot become a SLAVE + N_MBG_PTP_NG_82751_FLAGS +}; + + +enum MBG_PTP_NG_82751_FLAG_MSKS +{ + MBG_PTP_NG_82751_FLAG_USE_ALT_MC_ADDRESS_MSK = (1UL << MBG_PTP_NG_82751_FLAG_USE_ALT_MC_ADDRESS), ///< See ::MBG_PTP_NG_82751_FLAG_USE_ALT_MC_ADDRESS + MBG_PTP_NG_82751_FLAG_PORT_NOT_SLAVE_MSK = (1UL << MBG_PTP_NG_82751_FLAG_PORT_NOT_SLAVE) ///< See ::MBG_PTP_NG_82751_FLAG_PORT_NOT_SLAVE +}; + + +/** + * @brief Additional parameters for Telecom8275.1 profile + */ +typedef struct +{ + uint8_t port_local_priority; ///< TODO: Please add describing comment + uint8_t default_local_priority; ///< TODO: Please add describing comment + uint16_t reserved; ///< reserved, currently always 0 + + uint32_t flags; ///< Bitmask used with ::MBG_PTP_NG_82751_FLAG_MSKS + +} MBG_PTP_NG_TELECOM_G82751_SETTINGS; + + +#define _mbg_swab_ptp_ng_telecom_g82751_settings( _p ) \ +{ \ + _mbg_swab32( &(_p)->flags ); \ +} + + +/** + * @brief Large Scaled nanoseconds structure (96 bit integer). + * This format is only used by 802.1as. + */ +typedef struct +{ + int64_t ns_l; + int32_t ns_h; + int32_t reserved; // used for alignment +} MBG_PTP_NG_LARGE_SCALED_NS; + + +enum MBG_PTP_NG_8021AS_FLAGS +{ + MBG_PTP_NG_8021AS_FLAG_AS_CAPABLE, ///< this time-aware system and the time-aware system at the other end of the link attached to this port can interoperate with each other via IEEE 802.1AS + N_MBG_PTP_NG_8021AS_FLAGS +}; + + +enum MBG_PTP_NG_8021AS_FLAG_MSKS +{ + MBG_PTP_NG_8021AS_FLAG_AS_CAPABLE_MSK = (1UL << MBG_PTP_NG_8021AS_FLAG_AS_CAPABLE), ///< See ::MBG_PTP_NG_8021AS_FLAG_AS_CAPABLE +}; + + +/** + * @brief Additional parameters for IEEE 802.1AS profile + * TODO: Shall this really be settings or rather status? + */ +typedef struct +{ + PTP_TIME_INTERVAL port_neighbor_prop_delay_thresh; ///< Propagation time threshold, above which a port is not considered capable of participating in the IEEE 802.1AS protocol. + int64_t port_last_gm_phase_change; ///< Current phase difference (offset) to the current GM (in slave and passive state) on the current port. + ///< Will be used as @a last_gm_phase_change after this clock becomes GM. + MBG_PTP_NG_LARGE_SCALED_NS last_gm_phase_change; ///< Global last phase change of the clockSource/GM. Is changed whenever the time base changes. + PTP_NG_PORT_IDENTITY port_as_neighbor; ///< PortId of the current @a asCapable neighbor, only if @a asCapable is true. + int32_t port_last_gm_freq_change; ///< Current frequency rate ratio to the current GM (in slave and passive state). + ///< Will be used as lastGmFreqChange after this clock becomes GM. + int32_t cumulative_scaled_rate_offset; ///< Ratio of the frequency of the clockSource/GM to the frequency of the local clock (rateRatio * 1.0) * (2^41). + int32_t last_gm_freq_change; ///< (rateRatio * 2^41) Fractional frequency offset of the current clockSource/GM to the last clockSource/GM. + ///< Changes whenever the time base changes. + int32_t port_neighbor_rate_ratio; ///< Current rate ratio to the port neighbor in scaled ratio (rateRatio * 2^41). + uint16_t gm_time_base_indicator; ///< Used to identify the time base. If this clock acts as GM, it has to be managed + ///< via shared mem., equivalent to clockSourceTimeBaseIndicator. + uint16_t reserved_1; + uint32_t flags; ///< See ::MBG_PTP_NG_8021AS_FLAGS. + uint32_t reserved_2[2]; + +} MBG_PTP_NG_IEEE_8021AS_SETTINGS; + + + +typedef union +{ + char u[128]; + + MBG_PTP_NG_C37238_2011_SETTINGS c37238_2011; ///< Power Profile C37.238-2011 + MBG_PTP_NG_C37238_2017_SETTINGS c37238_2017; ///< Power Profile C37.238-2017 + MBG_PTP_NG_SMPTE_20592_SETTINGS smpte_20592; ///< SMPTE Profile ST 2059-2 + MBG_PTP_NG_TELECOM_G82751_SETTINGS g82751; ///< Telecom Profile ITU-T. G.8275.1 + MBG_PTP_NG_IEEE_8021AS_SETTINGS ieee8021as; ///< IEEE 802.1AS Profile + +} MBG_PTP_NG_PROFILE_SETTINGS_U; + + +#define _mbg_swab_ptp_ng_profile_settings_u( _profile, _p ) \ +do \ +{ \ + switch ( (_profile) ) \ + { \ + case PTP_PRESETS_POWER: \ + _mbg_swab_ptp_ng_c37238_2011_settings( &(_p)->c37238_2011 ); \ + break; \ + \ + case PTP_PRESETS_C37238_2017: \ + _mbg_swab_ptp_ng_c37238_2017_settings( &(_p)->c37238_2017 ); \ + break; \ + \ + case PTP_PRESETS_SMPTE: \ + _mbg_swab_ptp_ng_smpte_20592_settings( &(_p)->smpte_20592 ); \ + break; \ + \ + case PTP_PRESETS_TELECOM_PHASE: \ + _mbg_swab_ptp_ng_telecom_g82751_settings( &(_p)->g82751 ); \ + break; \ + \ + default: break; \ + } \ +} while ( 0 ) + + + +/** + * @brief A name of a local time zone which can be longer than used in::TZDL. + */ +typedef char MBG_PTP_NG_ATOI_TZ_NAME[12]; + + + +/** + * @brief A structure used to configure a PTP instance. + */ +typedef struct mbg_ptp_ng_instc_settings_s +{ + uint32_t tstamper_idx; ///< Index of the timestamper that is active for this config running on interface @a #intf_label. + uint16_t assigned_port_id; ///< Port ID for this instance. Read-only for user interfaces, must be assigned by the managing process. + uint16_t reserved_1; ///< Reserved, currently always 0. + + PTP_INTF intf_label; ///< Interface name (IPv4/L2) or IPv6 address of logical/VLAN interface linked to this config. + + PTP_PORT_IDENTITY custom_port_id; ///< Overwrite port ID of this PTP port with global clock ID and suitable port ID. + ///< Only used if ::MBG_PTP_NG_FLAG_CUSTOM_PORT_ID_MSK is set in @a #flags. + uint16_t reserved_2; ///< Reserved, currently always 0. + uint8_t log_severity; ///< Sets the log level of the PTP Stack. Range from 0 (errors only) to 4. + uint8_t dsf; ///< Differentiated service field (IPv4) for PTP event messages -> 6 bit (MSB) DSCP, 2 bit ECN. + uint8_t ipv6_multicast_scope; ///< One of the ::IPV6_MULTICAST_SCOPES used for PTP IPv6 multicast. + uint8_t role; ///< One of the supported PTP roles, see ::PTP_ROLES. + + uint8_t profile; ///< Selected PTP preset or profile, see ::PTP_PRESETS. + uint8_t domain_number; ///< The PTP clock domain number, 0..255. + uint8_t reserved_4[6]; ///< Reserved, currently always 0. + + uint8_t delay_mech; ///< See ::PTP_DELAY_MECHS. + uint8_t protocol; ///< See ::PTP_NW_PROTS. + uint8_t priority_1; ///< Default DS priority 1. + uint8_t priority_2; ///< Default DS priority 2. + MBG_PTP_NG_INTV_CFG intvs; ///< Interval settings for this PTP instance. + + uint8_t min_gm_clk_class; ///< Minimum acceptable GM clock class for clock adjustment in slave mode, 0 means accept all. + uint8_t min_gm_clk_accuracy; ///< Minimum acceptable GM clock accuracy for clock adjustment in slave mode, 0 means accept all. + uint16_t min_gm_clk_variance; ///< Minimum acceptable GM clock variance for clock adjustment in slave mode, 0 means accept all. + uint8_t multicast_ttl; ///< Sets the multicast TTL value in IPv4 or multicast hop count in IPv6. 1..255, default 5. + uint8_t unicast_ttl; ///< Sets the unicast TTL value in IPv4 or unicast hop count in IPv6. 1..255, default 128. + uint8_t ann_rcpt_timeout; ///< Announce msg. receipt timeout, see ::PTP_ANN_RCPT_TIMEOUT_LIMITS. + uint8_t v1_clock_stratum; ///< Clock stratum parameter for PTPv1 stack + + char v1_subdomain_name[PTP_SUBDOMAIN_NAME_LENGTH]; ///< Subdomain string for PTPv1 stack. + + uint32_t upper_bound; ///< Sync. state set to uncalibrated if above this limit [ns], default 0 (ignored). + uint32_t lower_bound; ///< Sync. state set to slave if below this limit [ns], default 0 (ignored). + + int32_t fast_locking_boundary; ///< Determines if fast locking is used after a master was selected or changed [ns], in slave mode only. + int32_t delay_asymmetry; ///< Used to compensate asymmetries [ns], default 0. + + MBG_PTP_NG_FIXED_CLK_QLTY fixed_quality; ///< Fixed Clock Quality as manual override used in BMCA. + ///< Only used if ::MBG_PTP_NG_FLAG_FIXED_QUALITY_MSK is set in @a #flags. + MBG_PTP_NG_SERVO_SETTINGS servo_settings; ///< PTP Clock Servo Settings used in slave mode to adjust TSU time. + MBG_PTP_NG_PROFILE_SETTINGS_U profile_settings; ///< Union that includes all profile specific parameters. + ///< The profile type to be used is determined by the @a #profile parameter. + + uint32_t atois; ///< Activated ATOI TLVs, see ::MBG_PTP_NG_GLB_INFO::max_atois and ::MBG_PTP_NG_ATOI_MASKS + uint32_t flags; ///< See ::MBG_PTP_NG_FLAG_MASKS. + + TZDL custom_atoi; ///< Alternate Time Offset Indicator, used to derive local time + ///< from the TAI time of the grandmaster. + MBG_PTP_NG_ATOI_TZ_NAME names[2]; ///< Local time zone names for DST off and DST on. + ///< Can be longer than the names in ::TZDL @a #custom_atoi. + + uint32_t v1_flags; ///< See ::MBG_PTP_NG_V1_FLAG_MASKS. + uint32_t reserved_5[3]; ///< Reserved, currently always 0. + + char alias[32]; ///< A configurable, descriptive name for the PTP instance, just informational. + +} MBG_PTP_NG_INSTC_SETTINGS; + + +#define _mbg_swab_ptp_ng_instc_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->tstamper_idx ); \ + _mbg_swab16( &(_p)->assigned_port_id ); \ + _mbg_swab_ptp_port_identity( &(_p)->custom_port_id ); \ + _mbg_swab_ptp_ng_intv_cfg( &(_p)->intvs ); \ + _mbg_swab16( &(_p)->min_gm_clk_variance ); \ + _mbg_swab32( &(_p)->upper_bound ); \ + _mbg_swab32( &(_p)->lower_bound ); \ + _mbg_swab32( &(_p)->fast_locking_boundary ); \ + _mbg_swab32( &(_p)->delay_asymmetry ); \ + _mbg_swab_ptp_ng_fixed_clk_qlty( &(_p)->fixed_quality ); \ + _mbg_swab_ptp_ng_servo_settings( &(_p)->servo_settings ); \ + _mbg_swab_ptp_ng_profile_settings_u( (_p)->profile, &(_p)->profile_settings ); \ + _mbg_swab32( &(_p)->atois ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab_tzdl( &(_p)->custom_atoi ); \ + _mbg_swab32( &(_p)->v1_flags ); \ +} \ +while(0) + + + +/** + * @brief ::TODO + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< Padding for 8-byte alignment, some settings contain int64_t. + + MBG_PTP_NG_INSTC_SETTINGS settings; + +} MBG_PTP_NG_INSTC_SETTINGS_IDX; + + +#define _mbg_swab_ptp_ng_instc_settings_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_instc_settings( &(_p)->settings ); \ +} + + +/** + * @brief A structure to used to query the current configuration of a PTP Instance + */ +typedef struct mbg_ptp_ng_instc_info_s +{ + MBG_PTP_NG_INSTC_SETTINGS settings; ///< The current configuration. + + uint32_t reserved[4]; ///< Reserved, currently always 0 + +} MBG_PTP_NG_INSTC_INFO; + + +#define _mbg_swab_ptp_ng_instc_info( _p ) \ +{ \ + _mbg_swab_ptp_ng_instc_settings( &(_p)->settings ); \ +} + + +/** + * @brief + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< Padding for 8-byte alignment, some settings contain int64_t. + + MBG_PTP_NG_INSTC_INFO info; + +} MBG_PTP_NG_INSTC_INFO_IDX; + + +#define _mbg_swab_ptp_ng_instc_info_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_instc_info( &(_p)->info ); \ +} + +typedef struct +{ + int64_t min; + int64_t mean; + int64_t median; + int64_t stdDev; +} MBG_PTP_NG_PKT_STATS; + + +#define _mbg_swab_ptp_ng_pkt_stats( _p ) \ +{ \ + _mbg_swab64( &(_p)->min ); \ + _mbg_swab64( &(_p)->mean ); \ + _mbg_swab64( &(_p)->median ); \ + _mbg_swab64( &(_p)->stdDev ); \ +} + + +#define MAX_MBG_PTP_NG_ATOI_STATUS 3 + + +typedef struct +{ + uint8_t key; ///< An index number, see ::MBG_PTP_NG_ATOIS. + uint8_t reserved_1; ///< Reserved, currently always 0. + PTP_PKT_TSTAMP_SECS time_of_next_jump; ///< Time when the next discontinuity will occur, in seconds. + + PTP_TLV_TIME_OFFS current_offset; ///< Offset of the current time scale, in seconds. + PTP_TLV_TIME_OFFS jump_seconds; ///< Size of next discontinuity, in seconds. + + MBG_PTP_NG_ATOI_TZ_NAME display_name; ///< Name of the ATOI timezone. + uint8_t flags; ///< Reserved, currently always 0. + uint8_t reserved_2[3]; ///< Reserved, currently always 0. + +} MBG_PTP_NG_ATOI_STATUS; + + +#define _mbg_swab_ptp_ng_atoi_status( _p ) \ +{ \ + _mbg_swab32( &(_p)->current_offset ); \ + _mbg_swab32( &(_p)->jump_seconds ); \ +} + + +enum MBG_PTP_NG_SMPTE_MASTER_LOCKING_STATUS +{ + MBG_PTP_NG_SMPTE_MASTER_NOT_IN_USE, + MBG_PTP_NG_SMPTE_MASTER_FREE_RUN, + MBG_PTP_NG_SMPTE_MASTER_COLD_LOCKING, + MBG_PTP_NG_SMPTE_MASTER_WARM_LOCKING, + MBG_PTP_NG_SMPTE_MASTER_LOCKED, + N_MBG_PTP_NG_SMPTE_MASTER_LOCKING_STATUS +}; + + +#define MBG_PTP_NG_SMPTE_MASTER_LOCKING_STATUS_STRS \ +{ \ + "Not in use", \ + "Free Run", \ + "Cold Locking", \ + "Warm Locking", \ + "Locked" \ +} + + +typedef struct +{ + uint32_t system_frame_rate_num; ///< See ::MBG_PTP_NG_SMPTE_FRAME_RATES and ::MBG_PTP_NG_SMPTE_FRAME_RATE_NUM. + uint32_t system_frame_rate_denum; ///< See ::MBG_PTP_NG_SMPTE_FRAME_RATES and ::MBG_PTP_NG_SMPTE_FRAME_RATE_DENUM. + + uint32_t time_address_flags; ///< See ::MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_MASKS. + uint8_t master_locking_status; ///< See ::MBG_PTP_NG_SMPTE_MASTER_LOCKING_STATUS. + PTP_TLV_DST_FLAGS daylight_saving; ///< Daylight saving flags, see ::PTP_TLV_DST_FLAG_MSKS. + PTP_TLV_LS_FLAGS leap_second_jump; ///< Leap second Flags, see ::PTP_TLV_LS_FLAG_MSKS. + uint8_t reserved_1; ///< Reserved, currently always 0 + + /// @brief Offset in seconds of Local Time from grandmaster PTP time. + /// + /// For example, if Local Time is Eastern Standard Time (North America) %UTC-5 and the + /// number of leap seconds is 37, the value will be -18037 s. + PTP_TLV_TIME_OFFS current_local_offset; + + /// @brief The size of the next discontinuity in local time, in seconds. + /// + /// A value of 0 indicates that no discontinuity is expected. A positive value + /// indicates that the discontinuity will increase the @a #current_local_offset. + PTP_TLV_TIME_OFFS jump_seconds; + + /// @brief Time at which the next discontinuity of the @a #current_local_offset will occur. + /// + /// Refers to the second portion of the grandmaster PTP time. + /// The discontinuity occurs at the start of the second indicated. + /// If no discontinuity has been scheduled, the value is 0. + PTP_PKT_TSTAMP_SECS time_of_next_jump; + + /// @brief Time at which the next daily jam is to occur. + /// + /// Refers to the second portion of the grandmaster PTP time. + /// If no daily jam has been scheduled, the value is 0. + PTP_PKT_TSTAMP_SECS time_of_next_jam; + + /// @brief Time at which the previous daily jam occurred. + /// + /// Refers to the second portion of the grandmaster PTP time. + /// If the time of the previous jam is unknown, the value is 0. + PTP_PKT_TSTAMP_SECS time_of_previous_jam; + + /// @brief Reserved, currently always 0. + uint16_t reserved_2; + + /// @brief Local time offset at the previous daily jam. + /// + /// The value of @a #current_local_offset at the previous daily jam time. + /// If a discontinuity of local time occurs at the jam time, this parameter + /// reflects the offset after the discontinuity. + PTP_TLV_TIME_OFFS previous_jam_local_offset; + +} MBG_PTP_NG_SMPTE_20592_STATUS; + + +#define _mbg_swab_ptp_ng_smpte_20592_status( _p ) \ +{ \ + _mbg_swab32( &(_p)->system_frame_rate_num ); \ + _mbg_swab32( &(_p)->system_frame_rate_denum ); \ + _mbg_swab32( &(_p)->time_address_flags ); \ + _mbg_swab32( &(_p)->current_local_offset ); \ + _mbg_swab32( &(_p)->jump_seconds ); \ + _mbg_swab32( &(_p)->previous_jam_local_offset ); \ +} + + + +/** + * @brief Daylight saving flags used in PTP TLVs. + * + * Used with ::PTP_TLV_DST_FLAGS. + */ +enum PTP_TLV_DST_FLAG_MSKS +{ + PTP_TLV_DST_FLAG_DST = 0x01, ///< Bit 0: DST currently in effect. + PTP_TLV_DST_FLAG_DST_AT_NEXT_JMP = 0x02, ///< Bit 1: DST in effect at next discontinuity. + PTP_TLV_DST_FLAG_DST_AT_PRV_JAM = 0x04 ///< Bit 2: DST in effect at previous jam time. + // Other bits are reserved. +}; + + + +/** + * @brief Leap second flags used in PTP TLVs. + * + * Used with ::PTP_TLV_LS_FLAGS. + */ +enum PTP_TLV_LS_FLAG_MSKS +{ + PTP_TLV_LS_FLAG_LEAP_SEC = 0x01 ///< Bit 0: Next discontinuity due to leap second. + // Other bits are reserved. +}; + + + +typedef union +{ + char u[128]; + + MBG_PTP_NG_C37238_2011_SETTINGS c37238_2011; ///< Power Profile C37.238-2011 + MBG_PTP_NG_C37238_2017_SETTINGS c37238_2017; ///< Power Profile C37.238-2017 + MBG_PTP_NG_SMPTE_20592_STATUS smpte_20592; ///< SMPTE Profile ST 2059-2 + MBG_PTP_NG_TELECOM_G82751_SETTINGS g82751; ///< Telecom Profile ITU-T. G.8275.1 + MBG_PTP_NG_IEEE_8021AS_SETTINGS ieee8021as; ///< IEEE 802.1AS Profile + +} MBG_PTP_NG_PROFILE_STATUS_U; + + +#define _mbg_swab_ptp_ng_profile_status_u( _profile, _p ) \ +do \ +{ \ + switch ( (_profile) ) \ + { \ + case PTP_PRESETS_POWER: \ + _mbg_swab_ptp_ng_c37238_2011_settings( &(_p)->c37238_2011 ); \ + break; \ + \ + case PTP_PRESETS_C37238_2017: \ + _mbg_swab_ptp_ng_c37238_2017_settings( &(_p)->c37238_2017 ); \ + break; \ + \ + case PTP_PRESETS_SMPTE: \ + _mbg_swab_ptp_ng_smpte_20592_status( &(_p)->smpte_20592 ); \ + break; \ + \ + case PTP_PRESETS_TELECOM_PHASE: \ + _mbg_swab_ptp_ng_telecom_g82751_settings( &(_p)->g82751 ); \ + break; \ + \ + default: break; \ + } \ +} while ( 0 ) + + +enum MBG_PTP_NG_INSTC_STATUS_FLAGS +{ + MBG_PTP_NG_INSTC_STATUS_FLAG_STACK_NOT_RUNNING, ///< Indicates, that the PTP stack for this instance is not running + MBG_PTP_NG_INSTC_STATUS_FLAG_M2S_DELAY_VALID, + MBG_PTP_NG_INSTC_STATUS_FLAG_S2M_DELAY_VALID, + + N_MBG_PTP_NG_INSTC_STATUS_FLAGS +}; + + + +enum MBG_PTP_NG_INSTC_STATUS_FLAG_MASKS +{ + MBG_PTP_NG_INSTC_STATUS_FLAG_STACK_NOT_RUNNING_MSK = (1UL << MBG_PTP_NG_INSTC_STATUS_FLAG_STACK_NOT_RUNNING), ///< See ::MBG_PTP_NG_INSTC_STATUS_FLAG_STACK_NOT_RUNNING + MBG_PTP_NG_INSTC_STATUS_FLAG_M2S_DELAY_VALID_MSK = (1UL << MBG_PTP_NG_INSTC_STATUS_FLAG_M2S_DELAY_VALID), ///< See ::MBG_PTP_NG_INSTC_STATUS_FLAG_M2S_DELAY_VALID + MBG_PTP_NG_INSTC_STATUS_FLAG_S2M_DELAY_VALID_MSK = (1UL << MBG_PTP_NG_INSTC_STATUS_FLAG_S2M_DELAY_VALID), ///< See ::MBG_PTP_NG_INSTC_STATUS_FLAG_S2M_DELAY_VALID +}; + + +/** + * @brief A structure used to read the status of a PTP instance + */ +typedef struct mbg_ptp_ng_instc_status_s +{ + MBG_PTP_NG_PKT_STATS m2s_delay; ///< current statistics of the Master to Slave delay + MBG_PTP_NG_PKT_STATS s2m_delay; ///< current statistics of the Slave to Master delay + uint16_t num_uc_slaves; ///< current number of unicast slaves in unicast master mode + uint8_t utilization; ///< current resource utilization (msg/sec) in % + uint8_t profile; ///< Selected PTP preset or profile, see ::PTP_PRESETS. + uint8_t num_atois; ///< number of valid atois status, see #atoi_status + uint8_t protocol; ///< current network protocol, see ::PTP_NW_PROTS + uint8_t reserved_1[2]; ///< reserved, currently always 0 + MBG_PTP_V2_NG_DEFAULT_DATASET default_ds; ///< the default dataset of the PTP instance + MBG_PTP_V2_NG_CURRENT_DATASET current_ds; ///< the current dataset of the PTP instance + MBG_PTP_V2_NG_PARENT_DATASET parent_ds; ///< the parent dataset of the PTP instance + MBG_PTP_V2_NG_TIME_PROPERTIES_DATASET time_properties_ds; ///< the time properties dataset of the PTP instance + MBG_PTP_V2_NG_PORT_DATASET port_ds; ///< the port dataset of the PTP instance + MBG_PTP_NG_PROFILE_STATUS_U profile_status; ///< Union that includes all profile specific parameters; the profile is selected with the #profile parameter. + MBG_PTP_NG_ATOI_STATUS atoi_status[MAX_MBG_PTP_NG_ATOI_STATUS]; ///< current status of available ATOIs + uint32_t flags; ///< See ::MBG_PTP_NG_INSTC_STATUS_FLAG_MASKS + uint32_t reserved_2[3]; ///< reserved, currently always 0 + +} MBG_PTP_NG_INSTC_STATUS; + + +#define _mbg_swab_ptp_ng_instc_status( _p ) \ +{ \ + unsigned i; \ + _mbg_swab_ptp_ng_pkt_stats( &(_p)->m2s_delay ); \ + _mbg_swab_ptp_ng_pkt_stats( &(_p)->s2m_delay ); \ + _mbg_swab16( &(_p)->num_uc_slaves ); \ + _mbg_swab_ptp_v2_ng_default_dataset( &(_p)->default_ds ); \ + _mbg_swab_ptp_v2_ng_current_dataset( &(_p)->current_ds ); \ + _mbg_swab_ptp_v2_ng_parent_dataset( &(_p)->parent_ds ); \ + _mbg_swab_ptp_v2_ng_time_properties_dataset( &(_p)->time_properties_ds ); \ + _mbg_swab_ptp_v2_ng_port_dataset( &(_p)->port_ds ); \ + _mbg_swab_ptp_ng_profile_status_u( (_p)->profile, &(_p)->profile_status ); \ + for ( i = 0; i < MAX_MBG_PTP_NG_ATOI_STATUS; ++i) \ + _mbg_swab_ptp_ng_atoi_status( &(_p)->atoi_status[i] ); \ + _mbg_swab32( &(_p)->flags ); \ +} + + +/** + * @brief + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< padding for 8-byte alignment, some settings contain int64_t + + MBG_PTP_NG_INSTC_STATUS status; + +} MBG_PTP_NG_INSTC_STATUS_IDX; + + +#define _mbg_swab_ptp_ng_instc_status_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_instc_status( &(_p)->status ); \ +} + + +typedef struct mbg_ptp_ng_instc_pkt_cntrs_s +{ + uint32_t rx_all; ///< overall Rx packet counter + uint32_t rx_announce; ///< Accepted Announce message Rx counter + uint32_t rx_sync; ///< Accepted Sync message Rx counter + uint32_t rx_follow_up; ///< Accepted Follow-up message Rx counter + uint32_t rx_delay_req; ///< Accepted Delay request message Rx counter + uint32_t rx_delay_resp; ///< Accepted Delay response message Rx counter + uint32_t rx_pdelay_req; ///< Accepted PDelay Request message Rx counter + uint32_t rx_pdelay_resp; ///< Accepted PDelay Response message Rx counter + uint32_t rx_pdelay_follow_up; ///< Accepted PDelay Follow-Up message Rx counter + uint32_t rx_signalling; ///< Accepted Signalling message Rx counter + uint32_t rx_management; ///< Accepted Management message Rx counter + uint32_t rx_management_err; ///< Management error counter (rx) + + uint32_t tx_all; ///< overall Tx packet counter + uint32_t tx_announce; ///< Announce message Tx counter + uint32_t tx_sync; ///< Sync message Tx counter + uint32_t tx_follow_up; ///< Follow-up message Tx counter + uint32_t tx_delay_req; ///< Delay request message Tx counter + uint32_t tx_delay_resp; ///< Delay response message Tx counter + uint32_t tx_pdelay_req; ///< PDelay Request message Tx counter + uint32_t tx_pdelay_resp; ///< PDelay Response message Tx counter + uint32_t tx_pdelay_follow_up; ///< PDelay Follow-Up message Tx counter + uint32_t tx_signalling; ///< Signalling message Tx counter + uint32_t tx_management; ///< Management message Tx counter + uint32_t reserved_1; ///< Reserved, currently always 0 + + uint32_t ann_receipt_timeout; ///< Announce receipt timeout counter + uint32_t reserved_2; ///< Reserved, currently always 0 + + // The following counters (msg/second counter) are represented in + // fixed point format. The lower 8 bit represent digits after the + // radix (comma), the higher 24 bits digits before it. That's a + // scaling factor of 1/(2^8). To display the number in decimal + // notation use: + // printf("%d.%d", rxPerSec >> 8, ((rxPerSec & 0xFF) * 100) >> 8) + uint32_t rx_all_per_sec; ///< overall Rx msg/second + uint32_t rx_announce_per_sec; ///< Accepted Announce msg Rx msg/second + uint32_t rx_sync_per_sec; ///< Accepted Sync msg Rx msg/second + uint32_t rx_follow_up_per_sec; ///< Accepted Follow-up msg Rx msg/second + uint32_t rx_delay_req_per_sec; ///< Accepted Delay request msg Rx msg/second + uint32_t rx_delay_resp_per_sec; ///< Accepted Delay response msg Rx msg/second + uint32_t rx_pdelay_req_per_sec; ///< Accepted PDelay Request msg Rx msg/second + uint32_t rx_pdelay_resp_per_sec; ///< Accepted PDelay Response msg Rx msg/second + uint32_t rx_pdelay_follow_up_per_sec; ///< Accepted PDelay Follow-Up msg Rx msg/sec. + uint32_t rx_signalling_per_sec; ///< Accepted Signalling msg Rx msg/second + uint32_t rx_management_per_sec; ///< Accepted Management msg Rx msg/second + uint32_t reserved_3; ///< Reserved, currently always 0 + + uint32_t tx_all_per_sec; ///< overall Tx msg/second + uint32_t tx_announce_per_sec; ///< Announce msg Tx msg/second + uint32_t tx_sync_per_sec; ///< Sync msg Tx msg/second + uint32_t tx_follow_up_per_sec; ///< Follow-up msg Tx msg/second + uint32_t tx_delay_req_per_sec; ///< Delay request msg Tx msg/second + uint32_t tx_delay_resp_per_sec; ///< Delay response msg Tx msg/second + uint32_t tx_pdelay_req_per_sec; ///< PDelay Request msg Tx msg/second + uint32_t tx_pdelay_resp_per_sec; ///< PDelay Response msg Tx msg/second + uint32_t tx_pdelay_follow_up_per_sec; ///< PDelay Follow-Up msg Tx msg/second + uint32_t tx_signalling_per_sec; ///< Signalling msg Tx msg/second + uint32_t tx_management_per_sec; ///< Management msg Tx msg/second + uint32_t reserved_4; ///< Reserved, currently always 0 + +} MBG_PTP_NG_INSTC_PKT_CNTRS; + + +#define _mbg_swab_ptp_ng_instc_pkt_cntrs( _p ) \ +{ \ + _mbg_swab32( &(_p)->rx_all ); \ + _mbg_swab32( &(_p)->rx_announce ); \ + _mbg_swab32( &(_p)->rx_sync ); \ + _mbg_swab32( &(_p)->rx_follow_up ); \ + _mbg_swab32( &(_p)->rx_delay_req ); \ + _mbg_swab32( &(_p)->rx_delay_resp ); \ + _mbg_swab32( &(_p)->rx_pdelay_req ); \ + _mbg_swab32( &(_p)->rx_pdelay_resp ); \ + _mbg_swab32( &(_p)->rx_pdelay_follow_up ); \ + _mbg_swab32( &(_p)->rx_signalling ); \ + _mbg_swab32( &(_p)->rx_management ); \ + _mbg_swab32( &(_p)->rx_management_err ); \ + \ + _mbg_swab32( &(_p)->tx_all ); \ + _mbg_swab32( &(_p)->tx_announce ); \ + _mbg_swab32( &(_p)->tx_sync ); \ + _mbg_swab32( &(_p)->tx_follow_up ); \ + _mbg_swab32( &(_p)->tx_delay_req ); \ + _mbg_swab32( &(_p)->tx_delay_resp ); \ + _mbg_swab32( &(_p)->tx_pdelay_req ); \ + _mbg_swab32( &(_p)->tx_pdelay_resp ); \ + _mbg_swab32( &(_p)->tx_pdelay_follow_up ); \ + _mbg_swab32( &(_p)->tx_signalling ); \ + _mbg_swab32( &(_p)->tx_management ); \ + \ + _mbg_swab32( &(_p)->ann_receipt_timeout ); \ + \ + _mbg_swab32( &(_p)->rx_all_per_sec ); \ + _mbg_swab32( &(_p)->rx_announce_per_sec ); \ + _mbg_swab32( &(_p)->rx_sync_per_sec ); \ + _mbg_swab32( &(_p)->rx_follow_up_per_sec ); \ + _mbg_swab32( &(_p)->rx_delay_req_per_sec ); \ + _mbg_swab32( &(_p)->rx_delay_resp_per_sec ); \ + _mbg_swab32( &(_p)->rx_pdelay_req_per_sec ); \ + _mbg_swab32( &(_p)->rx_pdelay_resp_per_sec ); \ + _mbg_swab32( &(_p)->rx_pdelay_follow_up_per_sec ); \ + _mbg_swab32( &(_p)->rx_signalling_per_sec ); \ + _mbg_swab32( &(_p)->rx_management_per_sec ); \ + \ + _mbg_swab32( &(_p)->tx_all_per_sec ); \ + _mbg_swab32( &(_p)->tx_announce_per_sec ); \ + _mbg_swab32( &(_p)->tx_sync_per_sec ); \ + _mbg_swab32( &(_p)->tx_follow_up_per_sec ); \ + _mbg_swab32( &(_p)->tx_delay_req_per_sec ); \ + _mbg_swab32( &(_p)->tx_delay_resp_per_sec ); \ + _mbg_swab32( &(_p)->tx_pdelay_req_per_sec ); \ + _mbg_swab32( &(_p)->tx_pdelay_resp_per_sec ); \ + _mbg_swab32( &(_p)->tx_pdelay_follow_up_per_sec ); \ + _mbg_swab32( &(_p)->tx_signalling_per_sec ); \ + _mbg_swab32( &(_p)->tx_management_per_sec ); \ +} + + +/** + * @brief + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< padding for 8-byte alignment, some settings contain int64_t + + MBG_PTP_NG_INSTC_PKT_CNTRS cntrs; + +} MBG_PTP_NG_INSTC_PKT_CNTRS_IDX; + + +#define _mbg_swab_ptp_ng_instc_pkt_cntrs_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_instc_pkt_cntrs( &(_p)->cntrs ); \ +} + + +/** + * @brief A structure used to read the status of a unicast slave of an instance running in unicast master mode + * @see ::MBG_PTP_NG_INSTC_STATUS::num_uc_slaves + */ +typedef struct mbg_ptp_ng_uc_slave_status_s +{ + uint8_t addr[IP6_ADDR_BYTES]; ///< IPv4, IPv6 or MAC address + ///< Depending on the appropriate ::MBG_PTP_NG_INSTC_SETTINGS::protocol + + MBG_PTP_NG_INTV_CFG intvs; ///< Granted message intervals + uint32_t ann_duration; ///< Remaining announce message duration + + uint32_t sync_duration; ///< Remaining sync message duration + uint32_t resp_duration; ///< Remaining delay reponse duration + + uint32_t reserved_4[8]; ///< reserved, currently always 0 + +} MBG_PTP_NG_UC_SLAVE_STATUS; + + +#define _mbg_swab_ptp_ng_uc_slave_status( _p ) \ +{ \ + _mbg_swab_ptp_ng_intv_cfg( &(_p)->intvs ); \ + _mbg_swab32( &(_p)->ann_duration ); \ + _mbg_swab32( &(_p)->sync_duration ); \ + _mbg_swab32( &(_p)->resp_duration ); \ +} + + +/** + * @brief + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t instc_idx; + + MBG_PTP_NG_UC_SLAVE_STATUS status; + +} MBG_PTP_NG_UC_SLAVE_STATUS_IDX; + + +#define _mbg_swab_ptp_ng_uc_slave_status_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab32( &(_p)->instc_idx ); \ + _mbg_swab_ptp_ng_uc_slave_status( &(_p)->status ); \ +} + + +/** + * @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 ::MBG_PTP_NG_GLB_INFO::max_uc_masters. + */ +typedef struct mbg_ptp_ng_uc_master_settings_s +{ + uint32_t instc_idx; ///< Index of the PTP instance this master belongs to + uint32_t reserved_1; ///< reserved, currently always 0. + + uint8_t grantor_addr[IP6_ADDR_BYTES]; ///< IPv4, IPv6 or MAC address of the grandmaster, depending on + ///< the associated ::MBG_PTP_NG_INSTC_SETTINGS::protocol value. + + PTP_PORT_IDENTITY gm_port_identity; ///< Specified port identity of master port, or ::PTP_CLOCK_ID_WILDCARD and ::PTP_PORT_ID_WILDCARD. + MBG_PTP_NG_INTV_CFG intvs; ///< Intervals to be requested by the Slave instance for this master. + uint16_t message_duration; ///< Subscription period [s]. + + uint32_t reserved_3[4]; ///< Reserved, currently always 0. + +} MBG_PTP_NG_UC_MASTER_SETTINGS; + + +#define _mbg_swab_ptp_ng_uc_master_settings( _p ) \ +{ \ + _mbg_swab32( &(_p)->instc_idx ); \ + _mbg_swab_ptp_port_identity( &(_p)->gm_port_identity ); \ + _mbg_swab_ptp_ng_intv_cfg( &(_p)->intvs ); \ + _mbg_swab16( &(_p)->message_duration ); \ +} + + +/** + * @brief Configuration settings for a specific PTP unicast master + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< padding for 8-byte alignment, some settings contain int64_t + + MBG_PTP_NG_UC_MASTER_SETTINGS settings; + +} MBG_PTP_NG_UC_MASTER_SETTINGS_IDX; + + +#define _mbg_swab_ptp_ng_uc_master_settings_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_uc_master_settings( &(_p)->settings ); \ +} + + +/** + * @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 mbg_ptp_ng_uc_master_info_s +{ + MBG_PTP_NG_UC_MASTER_SETTINGS settings; + + uint32_t reserved[4]; ///< reserved, currently always 0 + +} MBG_PTP_NG_UC_MASTER_INFO; + + +#define _mbg_swab_ptp_ng_uc_master_info( _p ) \ +{ \ + _mbg_swab_ptp_ng_uc_master_settings( &(_p)->settings ); \ +} + + +/** + * @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. + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< padding for 8-byte alignment, some settings contain int64_t + + MBG_PTP_NG_UC_MASTER_INFO info; + +} MBG_PTP_NG_UC_MASTER_INFO_IDX; + + +#define _mbg_swab_ptp_ng_uc_master_info_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_uc_master_info( &(_p)->info ); \ +} + + +/** @} defgroup group_ptp_ng */ /** @} defgroup group_ptp */ @@ -15117,10 +18008,10 @@ enum 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 + 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 }; @@ -15131,33 +18022,32 @@ enum NTP_ROLE_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 - NTP_PEER, ///< specifies a symmetric-active association should be used with this server - NTP_BROADCASTCLIENT, ///< receive broadcast messages on all interfaces - NTP_MULTICASTCLIENT, ///< receive messages from the given multicast group - NTP_MANYCASTCLIENT, ///< manycast shall be used on the given multicast address to discover peers - NTP_RESTRICTIONS, ///< NTP supports restrictions - NTP_DISCARD, ///< NTP supports "discard" rate limiting - NTP_REFCLOCKS, ///< NTP supports refclocks - NTP_STATISTICS, ///< NTP supports statistics (e.g. clockstats, loopstats, etc...) - NTP_MISCELLANEOUS, ///< NTP supports misc options (e.g. tinker, driftfile, orphan mode, etc...) - NTP_TRUSTED_KEYS, ///< NTP supports specifying trusted symmetric keys - NTP_FIXED_REFCLOCKS, ///< NTP refclocks not configurable - NTP_ADD_CONF, ///< Supports additional NTP configuration (i.e. via script) - + 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 + NTP_PEER, ///< specifies a symmetric-active association should be used with this server + NTP_BROADCASTCLIENT, ///< receive broadcast messages on all interfaces + NTP_MULTICASTCLIENT, ///< receive messages from the given multicast group + NTP_MANYCASTCLIENT, ///< manycast shall be used on the given multicast address to discover peers + NTP_RESTRICTIONS, ///< NTP supports restrictions + NTP_DISCARD, ///< NTP supports "discard" rate limiting + NTP_REFCLOCKS, ///< NTP supports refclocks + NTP_STATISTICS, ///< NTP supports statistics (e.g. clockstats, loopstats, etc...) + NTP_MISCELLANEOUS, ///< NTP supports misc options (e.g. tinker, driftfile, orphan mode, etc...) + NTP_TRUSTED_KEYS, ///< NTP supports specifying trusted symmetric keys + NTP_FIXED_REFCLOCKS, ///< NTP refclocks not configurable + NTP_ADD_CONF, ///< Supports additional NTP configuration (i.e. via script) N_NTP_FLAGS }; @@ -15176,33 +18066,32 @@ enum NTP_FLAGS * * @anchor NTP_FLAG_MASKS @{ */ -#define NTP_MSK_IPV4 ( 1UL << NTP_IPV4 ) ///< see ::NTP_IPV4 -#define NTP_MSK_IPV6 ( 1UL << NTP_IPV6 ) ///< see ::NTP_IPV6 -#define NTP_MSK_SYMM_KEYS ( 1UL << NTP_SYMM_KEYS ) ///< see ::NTP_SYMM_KEYS; if set, ::NTP_SYMM_KEY_LIMITS can be queried -#define NTP_MSK_AUTOKEY ( 1UL << NTP_AUTOKEY ) ///< see ::NTP_AUTOKEY -#define NTP_MSK_BURST ( 1UL << NTP_BURST ) ///< see ::NTP_BURST -#define NTP_MSK_IBURST ( 1UL << NTP_IBURST ) ///< see ::NTP_IBURST -#define NTP_MSK_NO_SELECT ( 1UL << NTP_NO_SELECT ) ///< see ::NTP_NO_SELECT -#define NTP_MSK_PREEMPT ( 1UL << NTP_PREEMPT ) ///< see ::NTP_PREEMPT -#define NTP_MSK_PREFER ( 1UL << NTP_PREFER ) ///< see ::NTP_PREFER -#define NTP_MSK_TRUE ( 1UL << NTP_TRUE ) ///< see ::NTP_TRUE -#define NTP_MSK_BROADCAST ( 1UL << NTP_BROADCAST ) ///< see ::NTP_BROADCAST -#define NTP_MSK_MULTICAST ( 1UL << NTP_MULTICAST ) ///< see ::NTP_MULTICAST -#define NTP_MSK_MANYCAST ( 1UL << NTP_MANYCAST ) ///< see ::NTP_MANYCAST -#define NTP_MSK_POOL ( 1UL << NTP_POOL ) ///< see ::NTP_POOL -#define NTP_MSK_PEER ( 1UL << NTP_PEER ) ///< see ::NTP_PEER -#define NTP_MSK_BROADCASTCLIENT ( 1UL << NTP_BROADCASTCLIENT) ///< see ::NTP_BROADCASTCLIENT -#define NTP_MSK_MULTICASTCLIENT ( 1UL << NTP_MULTICASTCLIENT) ///< see ::NTP_MULTICASTCLIENT -#define NTP_MSK_MANYCASTCLIENT ( 1UL << NTP_MANYCASTCLIENT) ///< see ::NTP_MANYCASTCLIENT -#define NTP_MSK_RESTRICTIONS ( 1UL << NTP_RESTRICTIONS ) ///< see ::NTP_RESTRICTIONS -#define NTP_MSK_DISCARD ( 1UL << NTP_DISCARD ) ///< see ::NTP_DISCARD -#define NTP_MSK_REFCLOCKS ( 1UL << NTP_REFCLOCKS ) ///< see ::NTP_REFCLOCKS -#define NTP_MSK_STATISTICS ( 1UL << NTP_STATISTICS ) ///< see ::NTP_STATISTICS; if set, ::NTP_STATS_GLB_INFO can be queried -#define NTP_MSK_MISCELLANEOUS ( 1UL << NTP_MISCELLANEOUS ) ///< see ::NTP_MISCELLANEOUS -#define NTP_MSK_TRUSTED_KEYS ( 1UL << NTP_TRUSTED_KEYS ) ///< see ::NTP_TRUSTED_KEYS -#define NTP_MSK_FIXED_REFCLOCKS ( 1UL << NTP_FIXED_REFCLOCKS ) ///< see ::NTP_FIXED_REFCLOCKS -#define NTP_MSK_ADD_CONF ( 1UL << NTP_ADD_CONF ) ///< see ::NTP_ADD_CONF - +#define NTP_MSK_IPV4 ( 1UL << NTP_IPV4 ) ///< See ::NTP_IPV4 +#define NTP_MSK_IPV6 ( 1UL << NTP_IPV6 ) ///< See ::NTP_IPV6 +#define NTP_MSK_SYMM_KEYS ( 1UL << NTP_SYMM_KEYS ) ///< See ::NTP_SYMM_KEYS; if set, ::NTP_SYMM_KEY_LIMITS can be queried +#define NTP_MSK_AUTOKEY ( 1UL << NTP_AUTOKEY ) ///< See ::NTP_AUTOKEY +#define NTP_MSK_BURST ( 1UL << NTP_BURST ) ///< See ::NTP_BURST +#define NTP_MSK_IBURST ( 1UL << NTP_IBURST ) ///< See ::NTP_IBURST +#define NTP_MSK_NO_SELECT ( 1UL << NTP_NO_SELECT ) ///< See ::NTP_NO_SELECT +#define NTP_MSK_PREEMPT ( 1UL << NTP_PREEMPT ) ///< See ::NTP_PREEMPT +#define NTP_MSK_PREFER ( 1UL << NTP_PREFER ) ///< See ::NTP_PREFER +#define NTP_MSK_TRUE ( 1UL << NTP_TRUE ) ///< See ::NTP_TRUE +#define NTP_MSK_BROADCAST ( 1UL << NTP_BROADCAST ) ///< See ::NTP_BROADCAST +#define NTP_MSK_MULTICAST ( 1UL << NTP_MULTICAST ) ///< See ::NTP_MULTICAST +#define NTP_MSK_MANYCAST ( 1UL << NTP_MANYCAST ) ///< See ::NTP_MANYCAST +#define NTP_MSK_POOL ( 1UL << NTP_POOL ) ///< See ::NTP_POOL +#define NTP_MSK_PEER ( 1UL << NTP_PEER ) ///< See ::NTP_PEER +#define NTP_MSK_BROADCASTCLIENT ( 1UL << NTP_BROADCASTCLIENT) ///< See ::NTP_BROADCASTCLIENT +#define NTP_MSK_MULTICASTCLIENT ( 1UL << NTP_MULTICASTCLIENT) ///< See ::NTP_MULTICASTCLIENT +#define NTP_MSK_MANYCASTCLIENT ( 1UL << NTP_MANYCASTCLIENT) ///< See ::NTP_MANYCASTCLIENT +#define NTP_MSK_RESTRICTIONS ( 1UL << NTP_RESTRICTIONS ) ///< See ::NTP_RESTRICTIONS +#define NTP_MSK_DISCARD ( 1UL << NTP_DISCARD ) ///< See ::NTP_DISCARD +#define NTP_MSK_REFCLOCKS ( 1UL << NTP_REFCLOCKS ) ///< See ::NTP_REFCLOCKS +#define NTP_MSK_STATISTICS ( 1UL << NTP_STATISTICS ) ///< See ::NTP_STATISTICS; if set, ::NTP_STATS_GLB_INFO can be queried +#define NTP_MSK_MISCELLANEOUS ( 1UL << NTP_MISCELLANEOUS ) ///< See ::NTP_MISCELLANEOUS +#define NTP_MSK_TRUSTED_KEYS ( 1UL << NTP_TRUSTED_KEYS ) ///< See ::NTP_TRUSTED_KEYS +#define NTP_MSK_FIXED_REFCLOCKS ( 1UL << NTP_FIXED_REFCLOCKS ) ///< See ::NTP_FIXED_REFCLOCKS +#define NTP_MSK_ADD_CONF ( 1UL << NTP_ADD_CONF ) ///< See ::NTP_ADD_CONF /** @} anchor NTP_FLAG_MASKS */ @@ -15296,9 +18185,9 @@ enum NTP_RESTR_TYPES */ enum NTP_RESTR_TYPE_MSKS { - NTP_RESTR_TYPE_MSK_DEFAULT = ( 1UL << NTP_RESTR_TYPE_DEFAULT ), ///< see ::NTP_RESTR_TYPE_DEFAULT - NTP_RESTR_TYPE_MSK_SOURCE = ( 1UL << NTP_RESTR_TYPE_SOURCE ), ///< see ::NTP_RESTR_TYPE_SOURCE - NTP_RESTR_TYPE_MSK_ADDRESS = ( 1UL << NTP_RESTR_TYPE_ADDRESS ) ///< see ::NTP_RESTR_TYPE_ADDRESS + NTP_RESTR_TYPE_MSK_DEFAULT = ( 1UL << NTP_RESTR_TYPE_DEFAULT ), ///< See ::NTP_RESTR_TYPE_DEFAULT + NTP_RESTR_TYPE_MSK_SOURCE = ( 1UL << NTP_RESTR_TYPE_SOURCE ), ///< See ::NTP_RESTR_TYPE_SOURCE + NTP_RESTR_TYPE_MSK_ADDRESS = ( 1UL << NTP_RESTR_TYPE_ADDRESS ) ///< See ::NTP_RESTR_TYPE_ADDRESS }; @@ -15343,22 +18232,22 @@ enum NTP_RESTR_FLAGS */ enum NTP_RESTR_FLAG_MSKS { - NTP_RESTR_FLAG_MSK_FLAKE = ( 1UL << NTP_RESTR_FLAG_FLAKE ), ///< see ::NTP_RESTR_FLAG_FLAKE - NTP_RESTR_FLAG_MSK_IGNORE = ( 1UL << NTP_RESTR_FLAG_IGNORE ), ///< see ::NTP_RESTR_FLAG_IGNORE - NTP_RESTR_FLAG_MSK_KOD = ( 1UL << NTP_RESTR_FLAG_KOD ), ///< see ::NTP_RESTR_FLAG_KOD - NTP_RESTR_FLAG_MSK_LIMITED = ( 1UL << NTP_RESTR_FLAG_LIMITED ), ///< see ::NTP_RESTR_FLAG_LIMITED - NTP_RESTR_FLAG_MSK_LOWPRIOTRAP = ( 1UL << NTP_RESTR_FLAG_LOWPRIOTRAP ),///< see ::NTP_RESTR_FLAG_LOWPRIOTRAP - NTP_RESTR_FLAG_MSK_MSSNTP = ( 1UL << NTP_RESTR_FLAG_MSSNTP ), ///< see ::NTP_RESTR_FLAG_MSSNTP - NTP_RESTR_FLAG_MSK_NOMODIFY = ( 1UL << NTP_RESTR_FLAG_NOMODIFY ), ///< see ::NTP_RESTR_FLAG_NOMODIFY - NTP_RESTR_FLAG_MSK_NOQUERY = ( 1UL << NTP_RESTR_FLAG_NOQUERY ), ///< see ::NTP_RESTR_FLAG_NOQUERY - NTP_RESTR_FLAG_MSK_NOPEER = ( 1UL << NTP_RESTR_FLAG_NOPEER ), ///< see ::NTP_RESTR_FLAG_NOPEER - NTP_RESTR_FLAG_MSK_NOSERVE = ( 1UL << NTP_RESTR_FLAG_NOSERVE ), ///< see ::NTP_RESTR_FLAG_NOSERVE - NTP_RESTR_FLAG_MSK_NOTRAP = ( 1UL << NTP_RESTR_FLAG_NOTRAP ), ///< see ::NTP_RESTR_FLAG_NOTRAP - NTP_RESTR_FLAG_MSK_NOTRUST = ( 1UL << NTP_RESTR_FLAG_NOTRUST ), ///< see ::NTP_RESTR_FLAG_NOTRUST - NTP_RESTR_FLAG_MSK_NTPPORT = ( 1UL << NTP_RESTR_FLAG_NTPPORT ), ///< see ::NTP_RESTR_FLAG_NTPPORT - NTP_RESTR_FLAG_MSK_VERSION = ( 1UL << NTP_RESTR_FLAG_VERSION ), ///< see ::NTP_RESTR_FLAG_VERSION - NTP_RESTR_FLAG_MSK_IPV4 = ( 1UL << NTP_RESTR_FLAG_IPV4 ), ///< see ::NTP_RESTR_FLAG_IPV4 - NTP_RESTR_FLAG_MSK_IPV6 = ( 1UL << NTP_RESTR_FLAG_IPV6 ) ///< see ::NTP_RESTR_FLAG_IPV6 + NTP_RESTR_FLAG_MSK_FLAKE = ( 1UL << NTP_RESTR_FLAG_FLAKE ), ///< See ::NTP_RESTR_FLAG_FLAKE + NTP_RESTR_FLAG_MSK_IGNORE = ( 1UL << NTP_RESTR_FLAG_IGNORE ), ///< See ::NTP_RESTR_FLAG_IGNORE + NTP_RESTR_FLAG_MSK_KOD = ( 1UL << NTP_RESTR_FLAG_KOD ), ///< See ::NTP_RESTR_FLAG_KOD + NTP_RESTR_FLAG_MSK_LIMITED = ( 1UL << NTP_RESTR_FLAG_LIMITED ), ///< See ::NTP_RESTR_FLAG_LIMITED + NTP_RESTR_FLAG_MSK_LOWPRIOTRAP = ( 1UL << NTP_RESTR_FLAG_LOWPRIOTRAP ),///< See ::NTP_RESTR_FLAG_LOWPRIOTRAP + NTP_RESTR_FLAG_MSK_MSSNTP = ( 1UL << NTP_RESTR_FLAG_MSSNTP ), ///< See ::NTP_RESTR_FLAG_MSSNTP + NTP_RESTR_FLAG_MSK_NOMODIFY = ( 1UL << NTP_RESTR_FLAG_NOMODIFY ), ///< See ::NTP_RESTR_FLAG_NOMODIFY + NTP_RESTR_FLAG_MSK_NOQUERY = ( 1UL << NTP_RESTR_FLAG_NOQUERY ), ///< See ::NTP_RESTR_FLAG_NOQUERY + NTP_RESTR_FLAG_MSK_NOPEER = ( 1UL << NTP_RESTR_FLAG_NOPEER ), ///< See ::NTP_RESTR_FLAG_NOPEER + NTP_RESTR_FLAG_MSK_NOSERVE = ( 1UL << NTP_RESTR_FLAG_NOSERVE ), ///< See ::NTP_RESTR_FLAG_NOSERVE + NTP_RESTR_FLAG_MSK_NOTRAP = ( 1UL << NTP_RESTR_FLAG_NOTRAP ), ///< See ::NTP_RESTR_FLAG_NOTRAP + NTP_RESTR_FLAG_MSK_NOTRUST = ( 1UL << NTP_RESTR_FLAG_NOTRUST ), ///< See ::NTP_RESTR_FLAG_NOTRUST + NTP_RESTR_FLAG_MSK_NTPPORT = ( 1UL << NTP_RESTR_FLAG_NTPPORT ), ///< See ::NTP_RESTR_FLAG_NTPPORT + NTP_RESTR_FLAG_MSK_VERSION = ( 1UL << NTP_RESTR_FLAG_VERSION ), ///< See ::NTP_RESTR_FLAG_VERSION + NTP_RESTR_FLAG_MSK_IPV4 = ( 1UL << NTP_RESTR_FLAG_IPV4 ), ///< See ::NTP_RESTR_FLAG_IPV4 + NTP_RESTR_FLAG_MSK_IPV6 = ( 1UL << NTP_RESTR_FLAG_IPV6 ) ///< See ::NTP_RESTR_FLAG_IPV6 }; @@ -15395,7 +18284,7 @@ do \ * @brief NTP restriction * * Structure contains all flags and information needed for a valid NTP restriction - * as described at ntp.org's manual page. + * as described in the manual pages at ntp.org. */ typedef struct { @@ -15404,9 +18293,9 @@ typedef struct uint16_t reserved_2; ///< Future use uint32_t flags; ///< Restriction flags, see ::NTP_RESTR_FLAG_MSKS - MBG_HOSTNAME addr; ///< used if ::NTP_RESTR::type == ::NTP_RESTR_TYPE_ADDRESS - ///< can contain a hostname, or an IPv4 or IPv6 address - ///< with or without CIDR extension (eg. 172.16.0.0/16). + MBG_HOSTNAME addr; ///< Used if ::NTP_RESTR::type == ::NTP_RESTR_TYPE_ADDRESS. + ///< Can contain a hostname, or an IPv4 or IPv6 address + ///< with or without CIDR extension (e.g. 172.16.0.0/16). } NTP_RESTR; #define _mbg_swab_ntp_restr( _p ) \ @@ -15470,7 +18359,7 @@ do \ /** - * @brief NTP "discard" rate limiting settings as described at ntp.org's manual + * @brief NTP "discard" rate limiting settings as described at ntp.org. */ typedef struct { @@ -15625,23 +18514,23 @@ enum NTP_REFCLK_TYPES */ enum NTP_REFCLK_TYPE_MSKS { - NTP_REFCLK_TYPE_MSK_LOCAL = ( 1UL << NTP_REFCLK_TYPE_LOCAL ), ///< see ::NTP_REFCLK_TYPE_LOCAL - NTP_REFCLK_TYPE_MSK_TRUETIME = ( 1UL << NTP_REFCLK_TYPE_TRUETIME ), ///< see ::NTP_REFCLK_TYPE_TRUETIME - NTP_REFCLK_TYPE_MSK_PARSE = ( 1UL << NTP_REFCLK_TYPE_PARSE ), ///< see ::NTP_REFCLK_TYPE_PARSE - NTP_REFCLK_TYPE_MSK_NMEA = ( 1UL << NTP_REFCLK_TYPE_NMEA ), ///< see ::NTP_REFCLK_TYPE_NMEA - NTP_REFCLK_TYPE_MSK_PPS = ( 1UL << NTP_REFCLK_TYPE_PPS ), ///< see ::NTP_REFCLK_TYPE_PPS - NTP_REFCLK_TYPE_MSK_SHM = ( 1UL << NTP_REFCLK_TYPE_SHM ) ///< see ::NTP_REFCLK_TYPE_SHM + NTP_REFCLK_TYPE_MSK_LOCAL = ( 1UL << NTP_REFCLK_TYPE_LOCAL ), ///< See ::NTP_REFCLK_TYPE_LOCAL + NTP_REFCLK_TYPE_MSK_TRUETIME = ( 1UL << NTP_REFCLK_TYPE_TRUETIME ), ///< See ::NTP_REFCLK_TYPE_TRUETIME + NTP_REFCLK_TYPE_MSK_PARSE = ( 1UL << NTP_REFCLK_TYPE_PARSE ), ///< See ::NTP_REFCLK_TYPE_PARSE + NTP_REFCLK_TYPE_MSK_NMEA = ( 1UL << NTP_REFCLK_TYPE_NMEA ), ///< See ::NTP_REFCLK_TYPE_NMEA + NTP_REFCLK_TYPE_MSK_PPS = ( 1UL << NTP_REFCLK_TYPE_PPS ), ///< See ::NTP_REFCLK_TYPE_PPS + NTP_REFCLK_TYPE_MSK_SHM = ( 1UL << NTP_REFCLK_TYPE_SHM ) ///< See ::NTP_REFCLK_TYPE_SHM }; /** - * @brief Numbers related to the "fudge" flags used with ntpd's refclock interface + * @brief Numbers related to the "fudge" flags used with ntpd's refclock interface. * * Used with ::NTP_REFCLK_CFG_SETTINGS::drv_flags_enable - * and ::NTP_REFCLK_CFG_SETTINGS::drv_flags_value + * and ::NTP_REFCLK_CFG_SETTINGS::drv_flags_value. * - * The refclock interface provided by ntpd supports a number of flags - * (flag1..flag4) which can be "fudged" in ntp.conf to control specific + * The refclock interface provided by @a ntpd supports a number of flags + * (flag1..flag4) which can be "fudged" in @a ntp.conf to control specific * features of a particular refclock driver, e.g.: * "fudge 127.127.8.0 flag1 1" * @@ -15651,13 +18540,13 @@ enum NTP_REFCLK_TYPE_MSKS * * There are different cases to be distinguished: * - * - if a flag is not specified at all in ntp.conf then + * - If a flag is not specified at all in @a ntp.conf then * the controlled feature is enabled or disabled - * according to the driver's default settings + * according to the driver's default settings. * - * - if a flag is specified as '0' or '1' in ntp.conf then + * - If a flag is specified as '0' or '1' in @a ntp.conf then * the controlled feature is enabled or disabled - * according to the flag's setting. + * according to the value of the flag. * * Thus, the bit mask in ::NTP_REFCLK_CFG_SETTINGS::drv_flags_enable * controls if the associated fudge flag should be specified in ntp.conf, @@ -15723,7 +18612,7 @@ do \ */ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; NTP_REFCLK_CFG_SETTINGS settings; ///< See ::NTP_REFCLK_CFG_SETTINGS } NTP_REFCLK_CFG_SETTINGS_IDX; @@ -15757,7 +18646,7 @@ enum NTP_REFCLK_CFG_FLAGS * * @anchor NTP_REFCLK_CFG_FLAGS_MASKS @{ */ -#define NTP_MSK_REFCLK_CFG_TRUSTTIME ( 1UL << NTP_REFCLK_CFG_TRUSTTIME ) ///< see ::NTP_REFCLK_CFG_TRUSTTIME +#define NTP_MSK_REFCLK_CFG_TRUSTTIME ( 1UL << NTP_REFCLK_CFG_TRUSTTIME ) ///< See ::NTP_REFCLK_CFG_TRUSTTIME /** @} anchor NTP_REFCLK_CFG_FLAGS_MASKS */ @@ -15765,7 +18654,7 @@ enum NTP_REFCLK_CFG_FLAGS /** * @brief NTP refclock configuration and supported refclock types * - * This structure can be used to set a NTP refclock's configuration + * This structure can be used to set an NTP refclock configuration * and get to know its overall supported refclocks. */ typedef struct @@ -15794,7 +18683,7 @@ do \ */ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; NTP_REFCLK_CFG_INFO info; } NTP_REFCLK_CFG_INFO_IDX; @@ -15807,6 +18696,19 @@ do \ } while ( 0 ) +enum NTP_SYMM_KEY_FLAGS +{ + NTP_SYMM_KEY_WHITELIST, ///< The device supports whitelisting for symmetric keys + N_NTP_SYMM_KEY_FLAGS +}; + + +enum NTP_SYMM_KEY_FLAG_MASKS +{ + NTP_SYMM_KEY_WHITELIST_MSK = ( 1UL << NTP_SYMM_KEY_WHITELIST ) ///< See ::NTP_SYMM_KEY_WHITELIST +}; + + /** * @brief Enumeration of NTP supported symmetric key hashing algorithms * @@ -15831,8 +18733,8 @@ enum NTP_SYMM_KEY_HASHES */ enum NTP_SYMM_KEY_HASH_MASKS { - NTP_SYMM_KEY_HASH_MSK_MD5 = ( 1UL << NTP_SYMM_KEY_HASH_MD5 ), ///< see ::NTP_SYMM_KEY_HASH_MD5 - NTP_SYMM_KEY_HASH_MSK_SHA1 = ( 1UL << NTP_SYMM_KEY_HASH_SHA1 ), ///< see ::NTP_SYMM_KEY_HASH_SHA1 + NTP_SYMM_KEY_HASH_MSK_MD5 = ( 1UL << NTP_SYMM_KEY_HASH_MD5 ), ///< See ::NTP_SYMM_KEY_HASH_MD5 + NTP_SYMM_KEY_HASH_MSK_SHA1 = ( 1UL << NTP_SYMM_KEY_HASH_SHA1 ), ///< See ::NTP_SYMM_KEY_HASH_SHA1 }; @@ -15859,7 +18761,7 @@ enum NTP_SYMM_KEY_HASH_MASKS typedef struct { uint16_t supp_hashes; ///< See ::NTP_SYMM_KEY_HASH_MASKS - uint16_t reserved_1; ///< Future use + uint16_t supp_flags; ///< See ::NTP_SYMM_KEY_FLAG_MASKS uint32_t reserved_2; ///< Future use uint32_t reserved_3; ///< Future use uint32_t reserved_4; ///< Future use @@ -15870,6 +18772,7 @@ typedef struct do \ { \ _mbg_swab16( &(_p)->supp_hashes ); \ + _mbg_swab16( &(_p)->supp_flags ); \ } while ( 0 ) @@ -15878,9 +18781,9 @@ do \ /// prepared for hash algorithms like SHA256, SH384, up to SHA512. #define N_NTP_SYMM_KEY_LEN 128 -/// Maximum number of ip addresses which can be assign to each key in -/// order to limit usage -#define N_NTP_SYMM_KEY_MAX_IP_ADDR 8 +/// Maximum number of whitelist entries which can be assigned to one key in +/// order to limit its usage +#define NTP_SYMM_KEY_WHITELIST_LEN 8 @@ -15891,17 +18794,19 @@ do \ */ typedef struct { - uint16_t id; ///< Configurable key id (1..65534) - uint8_t hash; ///< See ::NTP_SYMM_KEY_HASHES - uint8_t reserved_1; ///< Future use + uint16_t id; ///< Configurable key id (1..65534) + uint8_t hash; ///< See ::NTP_SYMM_KEY_HASHES + uint8_t reserved_1; ///< Future use - uint16_t reserved_2; ///< Future use - uint8_t num_ip_addr; ///< Number of configured ip addresses - uint8_t reserved_3; ///< Future use + uint16_t reserved_2; ///< Future use + uint8_t num_whitelist_entries; ///< Number of configured whitelist entries + ///< only valid if ::NTP_SYMM_KEY_WHITELIST_MSK is set in ::NTP_SYMM_KEY_LIMITS::supp_flags + uint8_t reserved_3; ///< Future use - uint8_t key[N_NTP_SYMM_KEY_LEN]; ///< Hashed phrase, see ::N_NTP_SYMM_KEY_LEN + uint8_t key[N_NTP_SYMM_KEY_LEN]; ///< Hashed phrase, see ::N_NTP_SYMM_KEY_LEN - MBG_IP_ADDR ip_addr[N_NTP_SYMM_KEY_MAX_IP_ADDR]; ///< Whitelist of ip addresses see ::N_NTP_SYMM_KEY_MAX_IP_ADDR + MBG_IP_ADDR whitelist_entries[NTP_SYMM_KEY_WHITELIST_LEN]; ///< Whitelist of ip addresses see ::NTP_SYMM_KEY_WHITELIST_LEN + ///< may only be used if ::NTP_SYMM_KEY_WHITELIST_MSK is set in ::NTP_SYMM_KEY_LIMITS::supp_flags } NTP_SYMM_KEY_SETTINGS; @@ -15912,8 +18817,8 @@ do \ \ _mbg_swab16( &(_p)->id ); \ \ - for ( i = 0; i < N_NTP_SYMM_KEY_MAX_IP_ADDR; ++i) \ - _mbg_swab_ip_addr( &(_p)->ip_addr[i] ); \ + for ( i = 0; i < NTP_SYMM_KEY_WHITELIST_LEN; ++i) \ + _mbg_swab_ip_addr( &(_p)->whitelist_entries[i] ); \ } while ( 0 ) @@ -15925,7 +18830,7 @@ do \ */ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; NTP_SYMM_KEY_SETTINGS settings; } NTP_SYMM_KEY_SETTINGS_IDX; @@ -15968,7 +18873,7 @@ do \ */ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; NTP_SYMM_KEY_INFO info; } NTP_SYMM_KEY_INFO_IDX; @@ -16008,7 +18913,7 @@ do \ */ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; NTP_TRUSTED_KEY_SETTINGS settings; } NTP_TRUSTED_KEY_SETTINGS_IDX; @@ -16050,7 +18955,7 @@ do \ */ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; NTP_TRUSTED_KEY_INFO info; } NTP_TRUSTED_KEY_INFO_IDX; @@ -16169,7 +19074,7 @@ typedef struct { uint8_t enable; ///< Generally enable / disable orphan mode uint8_t mode; ///< Stratum level when no ref source available - uint16_t reserved_1; ///< Future use + uint16_t wait_time; ///< Time until stratum is degraded (orphan mode active) in seconds uint32_t reserved_2; ///< Future use @@ -16178,6 +19083,9 @@ typedef struct #define _mbg_swab_ntp_misc_orphan_mode_settings( _p ) \ do \ { \ + _mbg_swab8( &(_p)->enable ); \ + _mbg_swab8( &(_p)->mode ); \ + _mbg_swab16( &(_p)->wait_time ); \ } while ( 0 ) @@ -16257,7 +19165,7 @@ do \ * * This structure can be used to determine possible NTP client settings and the current configuration */ -typedef struct +typedef struct ntp_clnt_mode_info_s { NTP_CLNT_MODE_SETTINGS settings; @@ -16390,9 +19298,9 @@ do \ * * @see ::NTP_PEER_SETTINGS */ -typedef struct +typedef struct ntp_peer_settings_idx_s { - uint32_t idx; + MBG_MSG_IDX_32 idx; NTP_PEER_SETTINGS peer_settings; } NTP_PEER_SETTINGS_IDX; @@ -16434,7 +19342,7 @@ do \ * * This structure should be used to query an NTP server configuration from a device */ -typedef struct +typedef struct ntp_srv_mode_info_s { NTP_SRV_MODE_SETTINGS settings; @@ -16821,17 +19729,17 @@ enum 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 - NTP_SYS_STATE_SUPP_SYS_ASSOC_MSK = ( 1UL << NTP_SYS_STATE_SUPP_SYS_ASSOC ), ///< see ::NTP_SYS_STATE_SUPP_SYS_ASSOC - NTP_SYS_STATE_SUPP_SERVICE_STATE_MSK = ( 1UL << NTP_SYS_STATE_SUPP_SERVICE_STATE ) ///< see ::NTP_SYS_STATE_SUPP_SERVICE_STATE + 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 + NTP_SYS_STATE_SUPP_SYS_ASSOC_MSK = ( 1UL << NTP_SYS_STATE_SUPP_SYS_ASSOC ), ///< See ::NTP_SYS_STATE_SUPP_SYS_ASSOC + NTP_SYS_STATE_SUPP_SERVICE_STATE_MSK = ( 1UL << NTP_SYS_STATE_SUPP_SERVICE_STATE ) ///< See ::NTP_SYS_STATE_SUPP_SERVICE_STATE }; @@ -16869,7 +19777,7 @@ enum MBG_NTP_SERVICE_STATES * * This structure can be requested from a monitoring program to determine the device system status */ -typedef struct +typedef struct ntp_sys_state_s { uint32_t supp_flags; ///< Supported NTP system state values, see ::NTP_SYS_STATE_SUPP_FLAG_MASKS @@ -17143,11 +20051,11 @@ enum 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 + 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 }; @@ -17283,19 +20191,19 @@ enum 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 + 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 }; @@ -17373,19 +20281,19 @@ enum 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 + 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 }; @@ -17397,7 +20305,7 @@ enum NTP_PEER_STATE_SUPP_FLAG_MASKS * * @see ::NTP_PEER_STATE_IDX */ -typedef struct +typedef struct ntp_peer_state_s { uint32_t supp_flags; ///< Supported NTP peer state values, see ::NTP_PEER_STATE_SUPP_FLAG_MASKS @@ -17536,9 +20444,9 @@ do \ * * @see ::NTP_PEER_STATE */ -typedef struct +typedef struct ntp_peer_state_idx_s { - uint32_t idx; ///< The index of the observed NTP peer + MBG_MSG_IDX_32 idx; ///< The index of the observed NTP peer NTP_PEER_STATE peer_state; ///< Peer state, see ::NTP_PEER_STATE } NTP_PEER_STATE_IDX, NTP_REFCLK_STATE_IDX; @@ -17700,7 +20608,7 @@ 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 + uint32_t flags; ///< See ::SHS_FLAG_MASKS } SHS_SETTINGS; @@ -17746,13 +20654,13 @@ do \ */ 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 + NANO_TIME time_diff; ///< Current time difference between the 2 clocks. + TM_GPS_STATUS_EXT clk_status_1; ///< Status of first clock. + TM_GPS_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; @@ -17813,9 +20721,9 @@ enum 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 + 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 */ @@ -17858,7 +20766,7 @@ typedef uint8_t XBP_PORT; * * A generic scheme to address devices connected to cascaded controllers. */ -typedef struct +typedef struct xbp_addr_s { uint8_t hop_count; ///< Used as index to the addr array XBP_PORT addr[MAX_XBP_CASC_LVL]; ///< An array of port numbers on cascaded controllers @@ -17954,6 +20862,7 @@ enum XBP_DEVICE_STATES XBP_DEVICE_STATE_INITIALIZING, XBP_DEVICE_STATE_AVAILABLE, XBP_DEVICE_STATE_DISCONNECTED, + XBP_DEVICE_STATE_OUTDATED, N_XBP_DEVICE_STATES }; @@ -18003,11 +20912,12 @@ enum XBP_SLOT_TYPES * The number of instances supported by a device is specified * in ::XBP_NODE_LIMITS::node_count. */ -typedef struct +typedef struct xbp_node_info_s { XBP_ADDR addr; ///< The address of the specific node - /// ::RECEIVER_INFO of the device connected to this node. + /// @brief ::RECEIVER_INFO of the device connected to this node. + /// /// If no device is available then ::RECEIVER_INFO::model_code /// is set to ::GPS_MODEL_UNKNOWN (== 0). RECEIVER_INFO ri; @@ -18043,7 +20953,7 @@ do \ */ typedef struct { - uint32_t idx; ///< node index, 0..::XBP_NODE_LIMITS::node_count-1 + MBG_MSG_IDX_32 idx; ///< node index, 0..::XBP_NODE_LIMITS::node_count-1 XBP_NODE_INFO node_info; ///< ::RECEIVER_INFO of the device behind this node } XBP_NODE_INFO_IDX; @@ -18128,8 +21038,8 @@ enum MBG_TLV_FEAT_TYPES /// 2) ::MBG_TLV_TYPE_FILE => Firmware file as data blob MBG_TLV_FEAT_TYPE_FW_UPDATE, - /// If announce message's total bytes are 0, it is a diagnostics file - /// request. If its total bytes are not 0, TLV type ::MBG_TLV_TYPE_FILE + /// If the total bytes of aan announce message is 0, it is a diagnostics file + /// request. If the total bytes are not 0, TLV type ::MBG_TLV_TYPE_FILE /// is expected and it should contain a file as data blob. MBG_TLV_FEAT_TYPE_DIAG_FILE, @@ -18530,7 +21440,7 @@ typedef struct * * %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 device 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. @@ -18563,17 +21473,26 @@ 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 of %UTC Parameters @a A0 and @a A1 [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] + GPS_WNUM WNlsf; ///< Week number of nearest leap second, originally + ///< truncated to 8 bit, so the extended number can be + ///< ambiguous unless @a #delta_tls and @a #delta_tlsf + ///< differ, indicating that a leap second is actually + ///< being announced. + + GPS_DNUM DNt; ///< The day-of-week at the end of which a leap second occurs. + ///< Transmitted numbers in the range 1..7 rather than 0..6. + + 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; @@ -18705,6 +21624,373 @@ typedef struct /** + * @defgroup group_sys_ref Reference system configuration + * + * System-wide reference configuration as replacement for XMR to provide an + * improved global API for new meinbergOS systems. + * + * This API is only supported if ::MBG_XFEATURE_SYS_REF is set. + */ + +typedef struct mbg_sys_ref_limits_s +{ + uint32_t num_ref_srcs; ///< Number of reference sources supported by the system, see ::MBG_SYS_REF_SRC_INFO_IDX + uint8_t max_prios; + uint8_t reserved_1[3]; + + uint32_t reserved_2[14]; ///< Reserved, currently always 0 + +} MBG_SYS_REF_LIMITS; + + +#define _mbg_swab_sys_ref_limits( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->num_ref_srcs ); \ + _mbg_swab32( &(_p)->supp_ref_types ); \ +} while ( 0 ) + + +enum MBG_SYS_REF_SRC_FLAGS +{ + SYS_REF_SRC_FLAG_XMR_STATS_SUPP, ///< Indicates, whether XMR stats are supported, read-only + SYS_REF_SRC_FLAG_XMR_ADV_METRICS_SUPP, ///< Indicates, whether advanced XMR metrics are supported, read-only + ///< Refers to the adv. metrics XMR feature, see ::XMR_EXT_SRC_FEAT_FLAG_BIT_ADV_METRICS + SYS_REF_SRC_FLAG_XMR_COASTING_SUPP, ///< Indicates, whether XMR coasting is supported, read-only + N_SYS_REF_SRC_FLAGS +}; + + +enum MBG_SYS_REF_SRC_MASKS +{ + SYS_REF_SRC_MASK_XMR_STATS_SUPP = ( 1UL << SYS_REF_SRC_FLAG_XMR_STATS_SUPP ), ///< See ::SYS_REF_SRC_FLAG_XMR_STATS_SUPP + SYS_REF_SRC_MASK_XMR_ADV_METRICS_SUPP = ( 1UL << SYS_REF_SRC_FLAG_XMR_ADV_METRICS_SUPP ), ///< See ::SYS_REF_SRC_FLAG_XMR_ADV_METRICS_SUPP + SYS_REF_SRC_MASK_XMR_COASTING_SUPP = ( 1UL << SYS_REF_SRC_FLAG_XMR_COASTING_SUPP ) ///< See ::SYS_REF_SRC_FLAG_XMR_COASTING_SUPP +}; + + +enum MBG_SYS_REF_SRC_TYPES +{ + SYS_REF_SRC_INTEGRATED, ///< Integrated reference source, i.e. an SMA or BNC port on the module itself + SYS_REF_SRC_PERIPHERAL, ///< Peripheral reference source, i.e. a port on an MRI (expansion) module + ///< Can only be used, if the equivalent ::SYS_REF_SRC_EXPANSION is equipped + SYS_REF_SRC_EXPANSION, ///< Expansion reference source announced by peripheral modules (i.e. MRI) + ///< Can only be used, if the equivalent ::SYS_REF_SRC_PERIPHERAL has been announced by the clock module + SYS_REF_SRC_AUTARKIC, ///< Autarkic reference source measuring a distinct offset, i.e. an ESI or a PTP (HPS) module + N_SYS_REF_SRC_TYPES +}; + + +#define SYS_REF_SRC_PRIO_UNUSED 0xFF +#define SYS_REF_SRC_INFO_STR_LEN 32 + +#define SYS_REF_SRC_PRQ_UNQUANTIFIED (-1) + +typedef struct mbg_sys_ref_src_settings_s +{ + uint8_t prio; ///< Priority for this reference + ///< must be 0 .. ::MBG_SYS_REF_LIMITS::num_ref_srcs or ::SYS_REF_SRC_PRIO_UNUSED + uint8_t itu_mask; ///< Used mask for ::XMR_METRICS, see ::MBG_SYS_REF_SRC_INFO::supp_itu_masks, only valid if + ///< ::SYS_REF_SRC_MASK_XMR_ADV_METRICS_SUPP is set in ::MBG_SYS_REF_SRC_INFO::supp_flags + uint8_t hysteresis; ///< Hysteresis (percent) between yellow and red alarm for ::XMR_METRICS, only valid if + ///< ::SYS_REF_SRC_MASK_XMR_ADV_METRICS_SUPP is set in ::MBG_SYS_REF_SRC_INFO::supp_flags + uint8_t reserved; ///< Reserved, currently always 0 + + uint32_t xmr_flags; ///< See ::XMR_SETTINGS_FLAG_MSKS + + NANO_TIME bias; ///< time bias, e.g. path delay + NANO_TIME precision; ///< precision of the time source + + uint32_t ro_uid; ///< Read-Only unique ref source identifier. We desperately + ///< need it to not be index dependent when sending settings. + ///< Layout from MSB to LSB: + ///< 8 bit chassis Id - 8 bit slot ID - 8 bit ref type (::MULTI_REF_TYPES) - 8 bit instance number (::XMULTI_REF_INSTANCES::n_inst[ref type]) + + int8_t quantifier; ///< Source precision quantifier (PRQ) to minimize clock switching operations, see ::SYS_REF_SRC_PRQ_UNQUANTIFIED. + ///< The smaller the value the more important is this source in relation to other sources (priorities). + uint8_t reserved_1[3]; + + uint32_t reserved_2[8]; ///< Reserved, currently always 0 + +} MBG_SYS_REF_SRC_SETTINGS; + + +/** + * @brief Default initializer for ::MBG_SYS_REF_SRC_SETTINGS::quantifier and the corresponding ::MULTI_REF_TYPES + * in ::XMULTI_REF_INSTANCES::n_inst. Keep them in sync! + */ +#define SYS_REF_SRC_QUANTIFIERS \ +{ \ + 0, 1, 1, SYS_REF_SRC_PRQ_UNQUANTIFIED, \ + 4, 6, 2, SYS_REF_SRC_PRQ_UNQUANTIFIED, \ + 1, 3, 3, SYS_REF_SRC_PRQ_UNQUANTIFIED, \ + 6, 6, 0, 3, \ + 5, 2, SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, \ + SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, \ + SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, \ + SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED \ +} + + +#define __to_sys_ref_ro_uid(c, s, t, i) \ + (((uint32_t)(c) << 24) | \ + ((uint32_t)(s) << 16) | \ + ((uint32_t)(t) << 8) | \ + ((uint32_t)(i))) + + +#define _mbg_swab_sys_ref_src_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->xmr_flags ); \ + _mbg_swab_nano_time( &(_p)->bias ); \ + _mbg_swab_nano_time( &(_p)->precision ); \ + _mbg_swab32( &(_p)->ro_uid ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SYS_REF_SRC_SETTINGS settings; + +} MBG_SYS_REF_SRC_SETTINGS_IDX; + + +#define _mbg_swab_sys_ref_src_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_sys_ref_src_settings( &(_p)->settings ); \ +} while ( 0 ) + + +#define SYS_REF_SRC_PORT_UNKNOWN 0xFF + + +typedef struct mbg_sys_ref_src_info_s +{ + MBG_SYS_REF_SRC_SETTINGS settings; ///< See ::MBG_SYS_REF_SRC_SETTINGS + + uint8_t ref_type; ///< See ::MULTI_REF_TYPES + uint8_t conn_type; ///< See ::MBG_SYS_REF_SRC_TYPES + uint8_t clock_idx; ///< Index of the associated clock, if #conn_type is ::SYS_REF_SRC_PERIPHERAL, resp. ::SYS_REF_SRC_EXPANSION + uint8_t chassis_idx; ///< Index of the associated IMS chassis, or ::MBG_OWN_EVENT_CHASSIS + + uint8_t slot_type; ///< See ::XBP_NODE_INFO::slot_type, or ::MBG_OWN_EVENT_SLOT_TYPE + uint8_t slot_type_id; ///< See ::XBP_NODE_INFO::slot_type_id, or ::MBG_OWN_EVENT_SLOT_TYPE_ID + uint8_t port_idx; ///< Index of the associated physical port (I/O port), or ::SYS_REF_SRC_PORT_UNKNOWN. + uint8_t inst_num; ///< Instance number of ref_type in slot. See ::XMULTI_REF_INSTANCES::n_inst + + char str[SYS_REF_SRC_INFO_STR_LEN]; ///< String for reference identification + + uint32_t supp_xmr_flags; ///< See ::XMR_SETTINGS_FLAG_MSKS + uint32_t supp_flags; ///< See ::MBG_SYS_REF_SRC_INFO::supp_flags and ::MBG_SYS_REF_SRC_MASKS + uint32_t supp_itu_masks; ///< See ::ITU_LIMIT_MASKS + uint32_t reserved_2[7]; ///< Reserved, currently always 0 + +} MBG_SYS_REF_SRC_INFO; + + +#define _mbg_swab_sys_ref_src_info( _p ) \ +do \ +{ \ + _mbg_swab_sys_ref_src_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_xmr_flags ); \ + _mbg_swab32( &(_p)->supp_itu_masks ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SYS_REF_SRC_INFO info; + +} MBG_SYS_REF_SRC_INFO_IDX; + + +#define _mbg_swab_sys_ref_src_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_sys_ref_src_info( &(_p)->info ); \ +} while ( 0 ) + + + +enum MBG_EST_TIME_QUALITY +{ + MBG_EST_TIME_QUALITY_RES_1, + MBG_EST_TIME_QUALITY_RES_2, + MBG_EST_TIME_QUALITY_RES_3, + MBG_EST_TIME_QUALITY_1ns, + MBG_EST_TIME_QUALITY_10ns, + MBG_EST_TIME_QUALITY_25ns, + MBG_EST_TIME_QUALITY_100ns, + MBG_EST_TIME_QUALITY_250ns, + MBG_EST_TIME_QUALITY_1us, + MBG_EST_TIME_QUALITY_2_5us, + MBG_EST_TIME_QUALITY_10us, + MBG_EST_TIME_QUALITY_25us, + MBG_EST_TIME_QUALITY_100us, + MBG_EST_TIME_QUALITY_250us, + MBG_EST_TIME_QUALITY_1ms, + MBG_EST_TIME_QUALITY_2_5ms, + MBG_EST_TIME_QUALITY_10ms, + MBG_EST_TIME_QUALITY_25ms, + MBG_EST_TIME_QUALITY_100ms, + MBG_EST_TIME_QUALITY_250ms, + MBG_EST_TIME_QUALITY_1s, + MBG_EST_TIME_QUALITY_10s, + MBG_EST_TIME_QUALITY_more_10s, + N_MBG_EST_TIME_QUALITYS +}; + + +#define MBG_EST_TIME_QUALITY_STRS \ +{ \ + "Unknown", \ + "Unknown", \ + "Unknown", \ + "1 ns", \ + "10 ns", \ + "25 ns", \ + "100 ns", \ + "250 ns", \ + "1 us", \ + "2.5 us", \ + "10 us", \ + "25 us", \ + "100 us", \ + "250 us", \ + "1 ms", \ + "2.5 ms", \ + "10 ms", \ + "25 ms", \ + "100 ms", \ + "250 ms", \ + "1 s", \ + "10 s", \ + "> 10 s" \ +} + + +typedef struct mbg_sys_ref_glb_status_s +{ + uint32_t master_idx; ///< Index of currently used reference source, see ::MBG_SYS_REF_SRC_INFO_IDX::idx + uint8_t ref_type; ///< Reference type of the currently used clock, see ::MULTI_REF_TYPES + uint8_t reserved_1[3]; ///< Reserved, currently always 0 + + XMR_HOLDOVER_STATUS holdover_status; ///< See ::XMR_HOLDOVER_STATUS, holdover status of currently used reference source + + uint8_t clock_idx; ///< Index of the currently used clock starting with 0, depends on #master_idx + uint8_t osc_type; ///< Oscillator type of the currently selected clock, see ::GPS_OSC_TYPES + TM_GPS_STATUS tm_gps_status; ///< Status flags from ::TM_GPS of the currently used clock, see ::TM_GPS_STATUS_BIT_MASKS + + uint8_t est_time_quality; ///< Current estimated time quality of the used clock, see ::MBG_EST_TIME_QUALITY + uint8_t reserved_2[3]; ///< Reserved, currently always 0 + uint16_t scaled_log_variance; ///< Current variance of the clock, depending on the oscillator type as defined in IEEE1588 + uint16_t reserved_3; ///< Reserved, currently always 0 + + UTC utc_parms; ///< %UTC offset, leap second information, etc., see ::UTC, + ///< TODO!!! can this be used? contains doubles + + uint32_t reserved_4[8]; ///< Reserved, currently always 0 + +} MBG_SYS_REF_GLB_STATUS; + + +#define _mbg_swab_sys_ref_glb_status( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->master_idx ); \ + _mbg_swab_xmr_holdover_status( &(_p)->holdover_status ); \ + _mbg_swab_tm_gps_status( &(_p)->tm_gps_status ); \ + _mbg_swab32( &(_p)->est_time_quality ); \ + _mbg_swab16( &(_p)->scaled_log_variance ); \ + _mbg_swab_utc_parm( &(_p)->utc_parms ); \ +} while ( 0 ) + + +enum MBG_SYS_REF_SRC_STATUS_SUPP_FLAGS +{ + SYS_REF_SRC_STATUS_SUPP_SSM, ///< Indicates, that ::MBG_SYS_REF_SRC_STATUS::ssm holds a valid value + SYS_REF_SRC_STATUS_SUPP_OUTAGE_CNT, ///< Indicates, that ::MBG_SYS_REF_SRC_STATUS::outage_cnt holds a valid value + SYS_REF_SRC_STATUS_SUPP_XMR_HOLDOVER, ///< Indicates, that ::MBG_SYS_REF_SRC_STATUS::xmr_holdover holds valid values + SYS_REF_SRC_STATUS_SUPP_XMR_STATS, ///< Indicates, that ::MBG_SYS_REF_SRC_STATUS::xmr_stats holds valid values + SYS_REF_SRC_STATUS_SUPP_XMR_METRICS, ///< Indicates, that ::MBG_SYS_REF_SRC_STATUS::xmr_metrics holds valid values + N_SYS_REF_SRC_STATUS_SUPP_FLAGS +}; + + +enum MBG_SYS_REF_SRC_STATUS_SUPP_MASKS +{ + SYS_REF_SRC_STATUS_SUPP_SSM_MASK = ( 1UL << SYS_REF_SRC_STATUS_SUPP_SSM ), ///< See ::SYS_REF_SRC_STATUS_SUPP_SSM + SYS_REF_SRC_STATUS_SUPP_OUTAGE_CNT_MASK = ( 1UL << SYS_REF_SRC_STATUS_SUPP_OUTAGE_CNT ), ///< See ::SYS_REF_SRC_STATUS_SUPP_OUTAGE_CNT + SYS_REF_SRC_STATUS_SUPP_XMR_HOLDOVER_MASK = ( 1UL << SYS_REF_SRC_STATUS_SUPP_XMR_HOLDOVER ), ///< See ::SYS_REF_SRC_STATUS_SUPP_XMR_HOLDOVER + SYS_REF_SRC_STATUS_SUPP_XMR_STATS_MASK = ( 1UL << SYS_REF_SRC_STATUS_SUPP_XMR_STATS ), ///< See ::SYS_REF_SRC_STATUS_SUPP_XMR_STATS + SYS_REF_SRC_STATUS_SUPP_XMR_METRICS_MASK = ( 1UL << SYS_REF_SRC_STATUS_SUPP_XMR_METRICS ) ///< See ::SYS_REF_SRC_STATUS_SUPP_XMR_METRICS +}; + + +typedef struct mbg_sys_ref_src_status_s +{ + char str[SYS_REF_SRC_INFO_STR_LEN]; ///< String for reference identification + + uint32_t xmr_status; ///< See @ref XMR_REF_STATUS_BIT_MASKS + + NANO_TIME offset; ///< time offset from main time base + + uint8_t ssm; ///< synchronization status message, only valid if ::SYS_REF_SRC_STATUS_SUPP_SSM_MASK is set + uint8_t prio; ///< Priority for this reference + uint8_t reserved[2]; ///< Reserved, currently always 0 + + uint32_t outage_cnt; ///< signal outage counter, incremented on loss of signal, only valid if ::SYS_REF_SRC_STATUS_SUPP_OUTAGE_CNT_MASK is set + + XMR_HOLDOVER_STATUS xmr_holdover; ///< See ::XMR_HOLDOVER_STATUS, only valid if ::SYS_REF_SRC_STATUS_SUPP_XMR_HOLDOVER_MASK is set + XMR_STATS xmr_stats; ///< See ::XMR_STATS, only valid if ::SYS_REF_SRC_STATUS_SUPP_XMR_STATS_MASK is set + XMR_METRICS xmr_metrics; ///< See ::XMR_METRICS, only valid if ::SYS_REF_SRC_STATUS_SUPP_XMR_METRICS_MASK is set + + uint32_t supp_flags; ///< See ::MBG_SYS_REF_SRC_STATUS_SUPP_MASKS + + uint32_t reserved_4[8]; ///< Reserved, currently always 0 + +} MBG_SYS_REF_SRC_STATUS; + + +#define _mbg_swab_sys_ref_src_status( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->xmr_status ); \ + _mbg_swab_nano_time( &(_p)->offset ); \ + _mbg_swab32( &(_p)->outage_cnt ); \ + _mbg_swab_xmr_holdover_status( &(_p)->xmr_holdover ); \ + _mbg_swab_xmr_stats( &(_p)->xmr_stats ); \ + _mbg_swab_xmr_metrics( &(_p)->xmr_metrics ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SYS_REF_SRC_STATUS status; + +} MBG_SYS_REF_SRC_STATUS_IDX; + + +#define _mbg_swab_sys_ref_src_status_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_sys_ref_src_status( &(_p)->status ); \ +} while ( 0 ) + + +/** @} defgroup group_sys_ref */ + + +/** * @defgroup group_led_api Meinberg LED API definitions * * @note These structures and definitions are only supported by a device @@ -18771,10 +22057,10 @@ enum MBG_LED_MODES */ enum MBG_LED_MODE_MASKS { - MBG_LED_MODE_MASK_OFF = ( 1UL << MBG_LED_MODE_OFF ), ///< see ::MBG_LED_MODE_OFF - MBG_LED_MODE_MASK_ON = ( 1UL << MBG_LED_MODE_ON ), ///< see ::MBG_LED_MODE_ON - MBG_LED_MODE_MASK_FLASH = ( 1UL << MBG_LED_MODE_FLASH ), ///< see ::MBG_LED_MODE_FLASH - MBG_LED_MODE_MASK_FLASH_5S = ( 1UL << MBG_LED_MODE_FLASH_5S ) ///< see ::MBG_LED_MODE_FLASH_5S + MBG_LED_MODE_MASK_OFF = ( 1UL << MBG_LED_MODE_OFF ), ///< See ::MBG_LED_MODE_OFF + MBG_LED_MODE_MASK_ON = ( 1UL << MBG_LED_MODE_ON ), ///< See ::MBG_LED_MODE_ON + MBG_LED_MODE_MASK_FLASH = ( 1UL << MBG_LED_MODE_FLASH ), ///< See ::MBG_LED_MODE_FLASH + MBG_LED_MODE_MASK_FLASH_5S = ( 1UL << MBG_LED_MODE_FLASH_5S ) ///< See ::MBG_LED_MODE_FLASH_5S }; @@ -18824,10 +22110,10 @@ enum MBG_LED_COLORS */ enum MBG_LED_COLOR_MASKS { - MBG_LED_COLOR_MASK_GREEN = ( 1UL << MBG_LED_COLOR_GREEN ), ///< see ::MBG_LED_COLOR_GREEN - MBG_LED_COLOR_MASK_RED = ( 1UL << MBG_LED_COLOR_RED ), ///< see ::MBG_LED_COLOR_RED - MBG_LED_COLOR_MASK_YELLOW = ( 1UL << MBG_LED_COLOR_YELLOW ), ///< see ::MBG_LED_COLOR_YELLOW - MBG_LED_COLOR_MASK_BLUE = ( 1UL << MBG_LED_COLOR_BLUE ) ///< see ::MBG_LED_COLOR_BLUE + MBG_LED_COLOR_MASK_GREEN = ( 1UL << MBG_LED_COLOR_GREEN ), ///< See ::MBG_LED_COLOR_GREEN + MBG_LED_COLOR_MASK_RED = ( 1UL << MBG_LED_COLOR_RED ), ///< See ::MBG_LED_COLOR_RED + MBG_LED_COLOR_MASK_YELLOW = ( 1UL << MBG_LED_COLOR_YELLOW ), ///< See ::MBG_LED_COLOR_YELLOW + MBG_LED_COLOR_MASK_BLUE = ( 1UL << MBG_LED_COLOR_BLUE ) ///< See ::MBG_LED_COLOR_BLUE }; @@ -18882,8 +22168,8 @@ do \ */ typedef struct { - uint16_t idx; ///< 0..::MBG_LED_LIMITS::num_leds-1 - MBG_LED_SETTINGS settings; ///< LED settings + MBG_MSG_IDX idx; ///< 0..::MBG_LED_LIMITS::num_leds-1. + MBG_LED_SETTINGS settings; ///< LED settings. } MBG_LED_SETTINGS_IDX; @@ -18935,8 +22221,8 @@ do \ */ typedef struct { - uint16_t idx; ///< 0..::MBG_LED_LIMITS::num_leds-1 - MBG_LED_INFO info; ///< LED info + MBG_MSG_IDX idx; ///< 0..::MBG_LED_LIMITS::num_leds-1. + MBG_LED_INFO info; ///< LED info. } MBG_LED_INFO_IDX; @@ -19020,7 +22306,7 @@ enum MBG_LNE_FEAT_BITS */ enum MBG_LNE_FEAT_MASKS { - MBG_LNE_FEAT_MASK_SWITCH_PWR = ( 1UL << MBG_LNE_FEAT_BIT_SWITCH_PWR ) ///< see ::MBG_LNE_FEAT_BIT_SWITCH_PWR + MBG_LNE_FEAT_MASK_SWITCH_PWR = ( 1UL << MBG_LNE_FEAT_BIT_SWITCH_PWR ) ///< See ::MBG_LNE_FEAT_BIT_SWITCH_PWR }; #endif @@ -19060,8 +22346,8 @@ do \ */ typedef struct { - uint16_t idx; ///< 0..::MBG_LNE_LIMITS::num_ports-1 - MBG_LNE_PORT_SETTINGS settings; ///< LNE settings + MBG_MSG_IDX idx; ///< 0..::MBG_LNE_LIMITS::num_ports-1. + MBG_LNE_PORT_SETTINGS settings; ///< LNE settings. } MBG_LNE_PORT_SETTINGS_IDX; @@ -19090,7 +22376,7 @@ typedef struct uint32_t reserved_0; ///< currently reserved, unused, always 0 uint32_t reserved_1; ///< currently reserved, unused, always 0 uint32_t reserved_2; ///< currently reserved, unused, always 0 - uint32_t flags; ///< see ::LNE_PORT_FLAG_MASKS + uint32_t flags; ///< See ::LNE_PORT_FLAG_MASKS } MBG_LNE_PORT_INFO; @@ -19115,8 +22401,8 @@ do \ */ typedef struct { - uint16_t idx; ///< 0..::MBG_LED_LIMITS::num_leds-1 - MBG_LNE_PORT_INFO info; ///< LNE port info + MBG_MSG_IDX idx; ///< 0..::MBG_LED_LIMITS::num_leds-1. + MBG_LNE_PORT_INFO info; ///< LNE port info. } MBG_LNE_PORT_INFO_IDX; @@ -19153,7 +22439,7 @@ enum LNE_PORT_FLAG_BITS */ enum LNE_PORT_FLAG_MASKS { - LNE_PORT_FLAG_MASK_IS_SFP = ( 1UL << LNE_PORT_FLAG_BIT_IS_SFP ) ///< see ::LNE_PORT_FLAG_BIT_IS_SFP + LNE_PORT_FLAG_MASK_IS_SFP = ( 1UL << LNE_PORT_FLAG_BIT_IS_SFP ) ///< See ::LNE_PORT_FLAG_BIT_IS_SFP }; @@ -19187,11 +22473,11 @@ enum MBG_PWR_STATES /** * @brief Device power control * - * Used to change or retrieve a device's power state + * Used to change or retrieve the power state of a device. */ typedef struct { - uint8_t state; ///< see ::MBG_PWR_STATES + uint8_t state; ///< See ::MBG_PWR_STATES uint8_t reserved_0; ///< Currently reserved, unused, always 0 uint16_t reserved_1; ///< Currently reserved, unused, always 0 @@ -19236,6 +22522,9 @@ enum MBG_EXT_SYS_INFO_BITS MBG_EXT_SYS_INFO_BIT_STORAGE_SIZE, MBG_EXT_SYS_INFO_BIT_RELEASE_CANDIDATE, MBG_EXT_SYS_INFO_BIT_OS_TARGET, + MBG_EXT_SYS_INFO_BIT_STATUS, ///< Bit to announce ::MBG_EXT_SYS_STATUS support + MBG_EXT_SYS_INFO_BIT_COMMIT_HASH, + MBG_EXT_SYS_INFO_BIT_OS_NAME, N_MBG_EXT_SYS_INFO_BITS }; @@ -19248,16 +22537,19 @@ enum MBG_EXT_SYS_INFO_BITS */ enum MBG_EXT_SYS_INFO_MSKS { - MBG_EXT_SYS_INFO_MSK_SW_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_SW_REV ), ///< see ::MBG_EXT_SYS_INFO_BIT_SW_REV - MBG_EXT_SYS_INFO_MSK_HW_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_HW_REV ), ///< see ::MBG_EXT_SYS_INFO_BIT_HW_REV - MBG_EXT_SYS_INFO_MSK_OS_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_OS_REV ), ///< see ::MBG_EXT_SYS_INFO_BIT_OS_REV - MBG_EXT_SYS_INFO_MSK_FPGA_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_FPGA_REV ), ///< see ::MBG_EXT_SYS_INFO_BIT_FPGA_REV - MBG_EXT_SYS_INFO_MSK_CORE_MOD_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_CORE_MOD_REV ), ///< see ::MBG_EXT_SYS_INFO_BIT_CORE_MOD_REV - MBG_EXT_SYS_INFO_MSK_OS_TYPE = ( 1UL << MBG_EXT_SYS_INFO_BIT_OS_TYPE ), ///< see ::MBG_EXT_SYS_INFO_BIT_OS_TYPE - MBG_EXT_SYS_INFO_MSK_RAM_SIZE = ( 1UL << MBG_EXT_SYS_INFO_BIT_RAM_SIZE ), ///< see ::MBG_EXT_SYS_INFO_BIT_RAM_SIZE - MBG_EXT_SYS_INFO_MSK_STORAGE_SIZE = ( 1UL << MBG_EXT_SYS_INFO_BIT_STORAGE_SIZE ), ///< see ::MBG_EXT_SYS_INFO_BIT_STORAGE_SIZE - MBG_EXT_SYS_INFO_MSK_RELEASE_CANDIDATE = ( 1UL << MBG_EXT_SYS_INFO_BIT_RELEASE_CANDIDATE ), ///< see ::MBG_EXT_SYS_INFO_BIT_RELEASE_CANDIDATE - MBG_EXT_SYS_INFO_MSK_OS_TARGET = ( 1UL << MBG_EXT_SYS_INFO_BIT_OS_TARGET ) ///< see ::MBG_EXT_SYS_INFO_BIT_OS_TARGET + MBG_EXT_SYS_INFO_MSK_SW_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_SW_REV ), ///< See ::MBG_EXT_SYS_INFO_BIT_SW_REV + MBG_EXT_SYS_INFO_MSK_HW_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_HW_REV ), ///< See ::MBG_EXT_SYS_INFO_BIT_HW_REV + MBG_EXT_SYS_INFO_MSK_OS_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_OS_REV ), ///< See ::MBG_EXT_SYS_INFO_BIT_OS_REV + MBG_EXT_SYS_INFO_MSK_FPGA_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_FPGA_REV ), ///< See ::MBG_EXT_SYS_INFO_BIT_FPGA_REV + MBG_EXT_SYS_INFO_MSK_CORE_MOD_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_CORE_MOD_REV ), ///< See ::MBG_EXT_SYS_INFO_BIT_CORE_MOD_REV + MBG_EXT_SYS_INFO_MSK_OS_TYPE = ( 1UL << MBG_EXT_SYS_INFO_BIT_OS_TYPE ), ///< See ::MBG_EXT_SYS_INFO_BIT_OS_TYPE + MBG_EXT_SYS_INFO_MSK_RAM_SIZE = ( 1UL << MBG_EXT_SYS_INFO_BIT_RAM_SIZE ), ///< See ::MBG_EXT_SYS_INFO_BIT_RAM_SIZE + MBG_EXT_SYS_INFO_MSK_STORAGE_SIZE = ( 1UL << MBG_EXT_SYS_INFO_BIT_STORAGE_SIZE ), ///< See ::MBG_EXT_SYS_INFO_BIT_STORAGE_SIZE + MBG_EXT_SYS_INFO_MSK_RELEASE_CANDIDATE = ( 1UL << MBG_EXT_SYS_INFO_BIT_RELEASE_CANDIDATE ), ///< See ::MBG_EXT_SYS_INFO_BIT_RELEASE_CANDIDATE + MBG_EXT_SYS_INFO_MSK_OS_TARGET = ( 1UL << MBG_EXT_SYS_INFO_BIT_OS_TARGET ), ///< See ::MBG_EXT_SYS_INFO_BIT_OS_TARGET + MBG_EXT_SYS_INFO_MSK_STATUS = ( 1UL << MBG_EXT_SYS_INFO_BIT_STATUS ), ///< See ::MBG_EXT_SYS_INFO_BIT_STATUS + MBG_EXT_SYS_INFO_MSK_COMMIT_HASH = ( 1UL << MBG_EXT_SYS_INFO_BIT_COMMIT_HASH ), ///< See ::MBG_EXT_SYS_INFO_BIT_COMMIT_HASH + MBG_EXT_SYS_INFO_MSK_OS_NAME = ( 1UL << MBG_EXT_SYS_INFO_BIT_OS_NAME ) ///< See ::MBG_EXT_SYS_INFO_BIT_OS_NAME }; @@ -19268,6 +22560,8 @@ enum MBG_EXT_SYS_INFO_PROC_TYPES MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_SAM3u, MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_SAM3s, MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_STM32F4, + MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_STM32F0, + MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_STM32F7, N_MBG_EXT_SYS_INFO_PROC_TYPES }; @@ -19277,7 +22571,9 @@ enum MBG_EXT_SYS_INFO_PROC_TYPES "Cortex A9", \ "Cortex SAM3u", \ "Cortex SAM3s", \ - "Cortex STM32F4" \ + "Cortex STM32F4", \ + "Cortex STM32F0", \ + "Cortex STM32F7" \ } enum MBG_EXT_SYS_INFO_FPGA_TYPES @@ -19350,6 +22646,16 @@ enum MBG_EXT_SYS_INFO_OS_TYPES "any" \ } +/* + * OS target information are only relevant for updates. The unique combination + * of CPU and GEN defines a specific update for this kind of hardware (FPGA) and CPU + * model. This means all microSync single boards (MSSB) do have the same + * update file as CPU and hardware (FPGA) are always equal. + * Several variants (power, telecom, etc...) do effect the real board layout + * (connectors, etc..) but never the update file as long as CPU and GEN are + * equal. The variant member only is informational. + */ + /// CPU mainline #define MBG_EXT_SYS_INFO_CPU_MSK 0xff @@ -19368,6 +22674,7 @@ enum MBG_EXT_SYS_INFO_CPUS MBG_EXT_SYS_INFO_CPU_UNKNOWN, MBG_EXT_SYS_INFO_CPU_HPS_USB_HOST, MBG_EXT_SYS_INFO_CPU_HPS_USB_DEVICE, + MBG_EXT_SYS_INFO_CPU_MSSB_USB_HOST, N_MBG_EXT_SYS_INFO_CPUS }; @@ -19375,7 +22682,8 @@ enum MBG_EXT_SYS_INFO_CPUS { \ "Unknown", \ "HPS USB host", \ - "HPS USB device" \ + "HPS USB device", \ + "microSync SB USB host" \ } #define __CPU_CODEC(cpu, gen, var) \ @@ -19383,25 +22691,75 @@ enum MBG_EXT_SYS_INFO_CPUS (((gen) & MBG_EXT_SYS_INFO_CPU_GEN_MSK) << 4) | \ ((var) & MBG_EXT_SYS_INFO_CPU_VAR_MSK) -/// CPU 1 : HPS USB host -/// Gen 1 : HPS100 -/// Var 0 : Base (4xLED, USB to serial, 2xSMA, SFP, RJ-45) -/// Product(s) : microSYNC HSXXX + +/** + * @defgroup group_os_target_codes OS target codes + * + * Status word, associated bit numbers and bit masks indicating + * whether certain data from the GPS satellites are + * available and valid. + * + * These bits defined are set in ::BVAR_STAT if the corresponding + * parameters are NOT valid and complete. + * + * @see ::MBG_EXT_SYS_INFO_CPUS + * @see ::MBG_OS_TARGET_CODE + * + * @{ */ + +/// - CPU 1 : HPS USB host +/// - Gen 1 : HPS100 +/// - Var 0 : Base (4 x LED, USB to serial, 2 x SMA, SFP, RJ-45) +/// - Product(s) : microSync HSXXX #define HPS_USB_HOST_G1_V0 __CPU_CODEC(MBG_EXT_SYS_INFO_CPU_HPS_USB_HOST, 1, 0) -/// CPU 2 : HPS USB device -/// Gen 1 : HPS100 -/// Var 0 : Base (4xLED, USB to serial, 2xSMA, SFP, RJ-45) -/// Product(s) : HPS100 +/// - CPU 2 : HPS USB device +/// - Gen 1 : HPS100 +/// - Var 0 : Base (4 x LED, USB to serial, 2 x SMA, SFP, RJ-45) +/// - Product(s) : HPS100 #define HPS_USB_DEVICE_G1_V0 __CPU_CODEC(MBG_EXT_SYS_INFO_CPU_HPS_USB_DEVICE, 1, 0) -/// CPU 2 : HPS USB device -/// Gen 1 : HPS100 -/// Var 1 : USB lock (4xLED, USB to serial, SMA, USB lock, SFP, RJ-45) -/// Product(s) : SSP100 +/// - CPU 2 : HPS USB device +/// - Gen 1 : HPS100 +/// - Var 1 : USB lock (4 x LED, USB to serial, SMA, USB lock, SFP, RJ-45) +/// - Product(s) : SSP100 #define HPS_USB_DEVICE_G1_V1 __CPU_CODEC(MBG_EXT_SYS_INFO_CPU_HPS_USB_DEVICE, 1, 1) -typedef struct +/// - CPU 3 : microSync SB USB host +/// - Gen 1 : MSSB100 +/// - Var 0 : Base (10 MHz in, PPS in, 10 MHz sine out, 10 MHz out, +/// 4 x LED, RS232, USB to serial, USB, 4 x SFP, 2 x DFK PPO, +/// 2 x Optocoupler) +/// - Product(s) : microSyncHR, microSyncRX +#define MSSB_USB_HOST_G1_V0 __CPU_CODEC(MBG_EXT_SYS_INFO_CPU_MSSB_USB_HOST, 1, 0) + +/** @} defgroup group_os_target_codes */ + + + +/** + * @brief Meinberg OS release year offset. + * + * If ::MBG_EXT_SYS_INFO_MSK_OS_TYPE is set in ::MBG_EXT_SYS_INFO::supp_members + * then ::MBG_OS_YEAR_CONSTANT needs to be added to the major version code of ::MBG_EXT_SYS_INFO::sw_rev + * to get the meinbergOS release year (4 digits), and its minor version represents the release month (2 digits). + */ +#define MBG_OS_YEAR_CONSTANT 2000 + + +/** + * @brief Bit-coded CPU type information. + * + * - Bits 0..3: CPU Type + * - Bits 4..7: CPU generation + * - Bits 8..15: CPU variant (currently unused) + * + * @see @ref group_os_target_codes + */ +typedef uint16_t MBG_OS_TARGET_CODE; + + +typedef struct mbg_ext_sys_info_s { uint32_t supp_members; ///< ::MBG_EXT_SYS_INFO_MSKS @@ -19422,21 +22780,14 @@ typedef struct uint8_t release_candidate;///< Release candidate number (0 = final release) - /* Reserved for future use, currently 0 */ + /// Reserved for future use, currently 0. uint8_t reserved_rev_3[3]; - /// Layout (see ::MBG_EXT_SYS_INFO_CPU_CODECS) - /// os_target:8 8 Bit CPU - /// os_target:4 4 Bit CPU generation - /// os_target:4 4 Bit CPU variant (currently unused) - uint16_t os_target; + MBG_OS_TARGET_CODE os_target; ///< See @ref group_os_target_codes uint16_t reserved_rev_4; - uint32_t reserved_rev_5; - uint32_t reserved_rev_6; - uint32_t reserved_rev_7; - uint32_t reserved_rev_8; - uint32_t reserved_rev_9; + uint32_t commit_hash; + char os_name[16]; } MBG_EXT_SYS_INFO; @@ -19472,6 +22823,97 @@ do \ } +#define MBG_REVISION_RC_DEVEL ((uint8_t)(-1)) +#define MBG_REVISION_RC_DEVEL_STR "devel" + + +/** + * @brief Bits used to define ::MBG_EXT_SYS_STATUS_MSKS + * + * @see ::MBG_EXT_SYS_STATUS_MSKS + */ +enum MBG_EXT_SYS_STATUS_BITS +{ + MBG_EXT_SYS_STATUS_BIT_UPTIME, + MBG_EXT_SYS_STATUS_BIT_FREE_RAM, + MBG_EXT_SYS_STATUS_BIT_LOAD, + MBG_EXT_SYS_STATUS_BIT_FLAGS, + N_MBG_EXT_SYS_STATUS_BITS +}; + +/** + * @brief Bit masks of supported status values in ::MBG_EXT_SYS_STATUS + * + * Used with ::MBG_EXT_SYS_STATUS::supp_members + * + * @see ::MBG_EXT_SYS_STATUS_BITS + */ +enum MBG_EXT_SYS_STATUS_MSKS +{ + MBG_EXT_SYS_STATUS_MSK_UPTIME = ( 1UL << MBG_EXT_SYS_STATUS_BIT_UPTIME ), ///< See ::MBG_EXT_SYS_STATUS_BIT_UPTIME + MBG_EXT_SYS_STATUS_MSK_FREE_RAM = ( 1UL << MBG_EXT_SYS_STATUS_BIT_FREE_RAM ), ///< See ::MBG_EXT_SYS_STATUS_BIT_FREE_RAM + MBG_EXT_SYS_STATUS_MSK_LOAD = ( 1UL << MBG_EXT_SYS_STATUS_BIT_LOAD ), ///< See ::MBG_EXT_SYS_STATUS_BIT_LOAD + MBG_EXT_SYS_STATUS_MSK_FLAGS = ( 1UL << MBG_EXT_SYS_STATUS_BIT_FLAGS ) ///< See ::MBG_EXT_SYS_STATUS_BIT_FLAGS +}; + +/** + * @brief Bits used to define ::MBG_EXT_SYS_STATUS_FLAGS_MSKS + * + * @see ::MBG_EXT_SYS_STATUS_FLAGS_MSKS + */ + +enum MBG_EXT_SYS_STATUS_FLAGS_BITS +{ + MBG_EXT_SYS_STATUS_FLAG_BIT_CONFIG_CHANGED, ///< Indicates if runtime config is different to startup config + N_MBG_EXT_SYS_STATUS_FLAGS_BITS +}; + +/** + * @brief Bit masks of supported status flags in ::MBG_EXT_SYS_STATUS + * + * Used with ::MBG_EXT_SYS_STATUS::supp_flags + * + * @see ::MBG_EXT_SYS_STATUS_FLAGS_BITS + */ + +enum MBG_EXT_SYS_STATUS_FLAGS_MSKS +{ + MBG_EXT_SYS_STATUS_FLAG_MSK_CONFIG_CHANGED = ( 1UL << MBG_EXT_SYS_STATUS_FLAG_BIT_CONFIG_CHANGED ) ///< See ::MBG_EXT_SYS_STATUS_FLAG_BIT_CONFIG_CHANGED +}; + + +typedef struct mbg_ext_sys_status_s +{ + uint32_t supp_members; ///< Indicates, which members of this struct are supported, see ::MBG_EXT_SYS_STATUS_MSKS + uint32_t uptime; ///< Seconds since boot + + uint32_t free_ram; ///< Free RAM in MB + + uint16_t supp_flags; ///< Indicates, which flags are supported see ::MBG_EXT_SYS_STATUS_FLAGS_MSKS + uint16_t flags; ///< See ::MBG_EXT_SYS_STATUS_FLAGS_MSKS + + uint16_t load_1m; ///< Multiplied by 100 since original value is a double + uint16_t load_5m; ///< Multiplied by 100 since original value is a double + uint16_t load_15m; ///< Multiplied by 100 since original value is a double + uint16_t reserved_2; + + uint32_t reserved_3[10]; + +} MBG_EXT_SYS_STATUS; + +#define _mbg_swab_ext_sys_status( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_members ); \ + _mbg_swab32( &(_p)->uptime ); \ + _mbg_swab32( &(_p)->free_ram ); \ + _mbg_swab16( &(_p)->load_1m ); \ + _mbg_swab16( &(_p)->load_5m ); \ + _mbg_swab16( &(_p)->load_15m ); \ +} while ( 0 ) + + + /** @} defgroup group_ext_sys_info */ @@ -19619,7 +23061,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_LICENSE_PTPV2 license; } MBG_LICENSE_PTPV2_IDX; @@ -19686,7 +23128,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_LICENSE_NTP license; } MBG_LICENSE_NTP_IDX; @@ -19751,7 +23193,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_LICENSE_PTPV1 license; } MBG_LICENSE_PTPV1_IDX; @@ -19821,7 +23263,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_LICENSE_TIME_MONITOR license; } MBG_LICENSE_TIME_MONITOR_IDX; @@ -20025,6 +23467,34 @@ enum MBG_TRANSACTION_TYPES */ MBG_TRANSACTION_TYPE_DATABASE, + /* + * PTP next gen transaction is supported, + * if ::MBG_XFEATURE_PTP_NG is set in ::MBG_XFEATURE_BUFFER and + * (if used in a save function) requires at least and as first command: + * ::GPS_PTP_NG_GLB_INFO + * + * Other commands in any order + * + * - ::GPS_PTP_NG_GLB_INFO + * - ::GPS_PTP_NG_TSTAMPER_INFO_IDX + * - ::GPS_PTP_NG_INSTC_INFO_IDX + * - ::GPS_PTP_NG_INSTC_STATUS_IDX + * - ::GPS_PTP_NG_UC_MASTER_INFO_IDX + * - ::GPS_PTP_NG_UC_SLAVE_STATUS_IDX + */ + MBG_TRANSACTION_TYPE_PTP_NG, + + /* + * Sys ref API is supported, if ::MBG_XFEATURE_SYS_REF is set + * in ::MBG_XFEATURE_BUFFER and supports the following commands: + * + * - ::GPS_SYS_REF_LIMITS + * - ::GPS_SYS_REF_GLB_STATUS + * - ::GPS_SYS_REF_SRC_INFO_IDX + * - ::GPS_SYS_REF_SRC_STATUS_IDX + */ + MBG_TRANSACTION_TYPE_SYS_REF, + MAX_MBG_TRANSACTION_TYPES }; @@ -20063,12 +23533,15 @@ enum MBG_IO_PORT_TYPES MBG_IO_PORT_TYPE_MULTI, MBG_IO_PORT_TYPE_POUT, MBG_IO_PORT_TYPE_SWITCH, - MBG_IO_PORT_TYPE_TIMECODE, ///< e.g. IRIG AM/DC, see ::MBG_IO_PORT_SHAPE_LEVELS + MBG_IO_PORT_TYPE_TIMECODE, ///< e.g. IRIG AM/DC, see ::MBG_IO_PORT_SHAPE_LEVELS MBG_IO_PORT_TYPE_LIGHT, MBG_IO_PORT_TYPE_ANTENNA, MBG_IO_PORT_TYPE_UART, MBG_IO_PORT_TYPE_DCF77, MBG_IO_PORT_TYPE_POWER, + MBG_IO_PORT_TYPE_SPST_RELAY, ///< Single-Pole Single-Throw Relay, two terminals which can be connected or disconnected + MBG_IO_PORT_TYPE_SPDT_RELAY, ///< Single-Pole Double-Throw Relay, common terminal connects to either of two others, never connecting to both at the same time + MBG_IO_PORT_TYPE_SYNTHESIZER, N_MBG_IO_PORT_TYPES }; @@ -20105,7 +23578,10 @@ enum MBG_IO_PORT_TYPES "Antenna", \ "UART", \ "DCF77", \ - "Power" \ + "Power", \ + "SPST Relay", \ + "SPDT Relay", \ + "Synthesizer" \ } @@ -20258,6 +23734,7 @@ enum MBG_IO_PORT_CONN_TYPES MBG_IO_PORT_CONN_TYPE_LED_BUTTON, MBG_IO_PORT_CONN_TYPE_QUAD_LED, MBG_IO_PORT_CONN_TYPE_5_PIN_DFK, + MBG_IO_PORT_CONN_TYPE_SINGLE_LED, N_MBG_IO_PORT_CONN_TYPES }; @@ -20289,6 +23766,7 @@ enum MBG_IO_PORT_CONN_TYPES 1, \ 1, \ 4, \ + 1, \ 1 \ } @@ -20322,7 +23800,8 @@ enum MBG_IO_PORT_CONN_TYPES "XHE SPI", \ "LED Button", \ "Quad LED", \ - "DFK 5-Pin" \ + "DFK 5-Pin", \ + "Single LED" \ } @@ -20551,31 +24030,28 @@ enum MBG_IO_PORT_GRP_ROLE_MSKS /** - * @brief Supported members in ::MBG_IO_PORT_ANTENNA_INFO and ::MBG_IO_PORT_ANTENNA_SETTINGS + * @brief Supported members in ::MBG_IO_PORT_ANT_INFO and ::MBG_IO_PORT_ANT_SETTINGS * - * Used with ::MBG_IO_PORT_ANTENNA_INFO::supp_members + * Used with ::MBG_IO_PORT_ANT_INFO::supp_members * */ enum MBG_IO_PORT_ANT_MEMBERS { - /// Supports ::MBG_IO_PORT_ANT_INFO::gnss_info and ::MBG_IO_PORT_ANT_SETTINGS::gnss_settings - MBG_IO_PORT_ANT_MEMBER_GNSS, - /// Supports ::MBG_IO_PORT_ANT_SETTINGS::ant_cab_len - MBG_IO_PORT_ANT_MEMBER_CAB_LEN, - /// Supports ::MBG_IO_PORT_ANT_SETTINGS::ignore_lock - MBG_IO_PORT_ANT_MEMBER_IGN_LOCK, - /// Supports ::MBG_IO_PORT_ANT_SETTINGS::tr_dist - MBG_IO_PORT_ANT_MEMBER_TR_DIST, + MBG_IO_PORT_ANT_MEMBER_GNSS, ///< Supports ::MBG_IO_PORT_ANT_INFO::gnss_info + ///< and ::MBG_IO_PORT_ANT_SETTINGS::gnss_settings. + MBG_IO_PORT_ANT_MEMBER_CAB_LEN, ///< Supports ::MBG_IO_PORT_ANT_SETTINGS::ant_cab_len. + MBG_IO_PORT_ANT_MEMBER_IGN_LOCK, ///< Supports ::MBG_IO_PORT_ANT_SETTINGS::ignore_lock. + MBG_IO_PORT_ANT_MEMBER_TR_DIST, ///< Supports ::MBG_IO_PORT_ANT_SETTINGS::tr_dist. N_MBG_IO_PORT_ANT_MEMBERS }; enum MBG_IO_PORT_ANT_MEMBER_MSKS { - MBG_IO_PORT_ANT_MEMBER_MSK_GNSS = (1UL << MBG_IO_PORT_ANT_MEMBER_GNSS), /// See ::MBG_IO_PORT_ANT_MEMBER_GNSS - MBG_IO_PORT_ANT_MEMBER_MSK_CAB_LEN = (1UL << MBG_IO_PORT_ANT_MEMBER_CAB_LEN), /// See ::MBG_IO_PORT_ANT_MEMBER_CAB_LEN - MBG_IO_PORT_ANT_MEMBER_MSK_IGN_LOCK = (1UL << MBG_IO_PORT_ANT_MEMBER_IGN_LOCK), /// See ::MBG_IO_PORT_ANT_MEMBER_IGN_LOCK - MBG_IO_PORT_ANT_MEMBER_MSK_TR_DIST = (1UL << MBG_IO_PORT_ANT_MEMBER_TR_DIST) /// See ::MBG_IO_PORT_ANT_MEMBER_TR_DIST + MBG_IO_PORT_ANT_MEMBER_MSK_GNSS = ( 1UL << MBG_IO_PORT_ANT_MEMBER_GNSS ), ///< See ::MBG_IO_PORT_ANT_MEMBER_GNSS + MBG_IO_PORT_ANT_MEMBER_MSK_CAB_LEN = ( 1UL << MBG_IO_PORT_ANT_MEMBER_CAB_LEN ), ///< See ::MBG_IO_PORT_ANT_MEMBER_CAB_LEN + MBG_IO_PORT_ANT_MEMBER_MSK_IGN_LOCK = ( 1UL << MBG_IO_PORT_ANT_MEMBER_IGN_LOCK ), ///< See ::MBG_IO_PORT_ANT_MEMBER_IGN_LOCK + MBG_IO_PORT_ANT_MEMBER_MSK_TR_DIST = ( 1UL << MBG_IO_PORT_ANT_MEMBER_TR_DIST ) ///< See ::MBG_IO_PORT_ANT_MEMBER_TR_DIST }; @@ -20613,6 +24089,33 @@ do \ } while ( 0 ) +typedef struct +{ + IRIG_INFO irig_info; + +} MBG_IO_PORT_TIMECODE_INFO; + +#define _mbg_swab_io_port_timecode_info( _p ) \ +do \ +{ \ + _mbg_swab_irig_info( &(_p)->irig_info ); \ +} while ( 0 ) + +typedef struct +{ + IRIG_SETTINGS irig_settings; + MBG_REF_OFFS ref_offs; ///< Fix %UTC offset of incoming IRIG codde, only for inputs. + +} MBG_IO_PORT_TIMECODE_SETTINGS; + +#define _mbg_swab_io_port_timecode_settings( _p ) \ +do \ +{ \ + _mbg_swab_irig_settings( &(_p)->irig_settings ); \ + _mbg_swab_mbg_ref_offs( &(_p)->ref_offs ); \ +} while ( 0 ) + + /** * @brief IO Port Settings Union * @@ -20631,41 +24134,46 @@ typedef union { MBG_GPIO_SETTINGS gpio_settings; POUT_SETTINGS pout_settings; - IRIG_SETTINGS irig_settings; + MBG_IO_PORT_TIMECODE_SETTINGS timecode_settings; MBG_IO_PORT_ANT_SETTINGS ant_settings; PORT_SETTINGS uart_settings; + SYNTH synth_settings; } MBG_IO_PORT_SETTINGS_U; -#define _mbg_swab_io_port_settings_u( _type, _p, _recv ) \ -do \ -{ \ - switch ( (_type) ) \ - { \ - case MBG_IO_PORT_TYPE_GPIO: \ - _mbg_swab_mbg_gpio_settings( &(_p)->gpio_settings, (_recv) ); \ - break; \ - \ - case MBG_IO_PORT_TYPE_POUT: \ - if ( _recv ) \ - _mbg_swab_pout_settings_on_get( &(_p)->pout_settings ); \ - else _mbg_swab_pout_settings_on_set( &(_p)->pout_settings ); \ - break; \ - \ - case MBG_IO_PORT_TYPE_TIMECODE: \ - _mbg_swab_irig_settings( &(_p)->irig_settings ); \ - break; \ - \ - case MBG_IO_PORT_TYPE_ANTENNA: \ - _mbg_swab_io_port_ant_settings( &(_p)->ant_settings ); \ - break; \ - \ - case MBG_IO_PORT_TYPE_UART: \ - _mbg_swab_port_settings( &(_p)->uart_settings ); \ - break; \ - \ - default: break; \ - } \ +#define _mbg_swab_io_port_settings_u( _type, _p, _recv ) \ +do \ +{ \ + switch ( (_type) ) \ + { \ + case MBG_IO_PORT_TYPE_GPIO: \ + _mbg_swab_mbg_gpio_settings( &(_p)->gpio_settings, (_recv) ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_POUT: \ + if ( _recv ) \ + _mbg_swab_pout_settings_on_get( &(_p)->pout_settings ); \ + else _mbg_swab_pout_settings_on_set( &(_p)->pout_settings ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_TIMECODE: \ + _mbg_swab_io_port_timecode_settings( &(_p)->timecode_settings ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_ANTENNA: \ + _mbg_swab_io_port_ant_settings( &(_p)->ant_settings ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_UART: \ + _mbg_swab_port_settings( &(_p)->uart_settings ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_SYNTHESIZER: \ + _mbg_swab_synth( &(_p)->synth_settings ); \ + break; \ + \ + default: break; \ + } \ } while ( 0 ) @@ -20737,7 +24245,7 @@ do \ */ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_IO_PORT_SETTINGS settings; } MBG_IO_PORT_SETTINGS_IDX; @@ -20753,35 +24261,43 @@ do \ #define MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE (MBG_IO_PORT_SETTINGS_MIN_SIZE + sizeof( uint32_t )) -#define MBG_IO_PORT_SETTINGS_IDX_SIZES \ -{ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_PPS */ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_10MHz */ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_2048KHz */ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( MBG_GPIO_SETTINGS ), /* MBG_IO_PORT_TYPE_GPIO */ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_ETHERNET */ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_TERMINAL */ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_MULTI */ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( POUT_SETTINGS ), /* MBG_IO_PORT_TYPE_POUT */ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SWITCH */ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( IRIG_SETTINGS ), /* MBG_IO_PORT_TYPE_TIMECODE */ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_LIGHT */ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_ANT_SETTINGS ), /* MBG_IO_PORT_TYPE_ANTENNA */ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( PORT_SETTINGS ), /* MBG_IO_PORT_TYPE_UART */ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_DCF77 */ \ - MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE /* MBG_IO_PORT_TYPE_POWER */ \ +#define MBG_IO_PORT_SETTINGS_IDX_SIZES \ +{ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_PPS */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_10MHz */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_2048KHz */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( MBG_GPIO_SETTINGS ), /* MBG_IO_PORT_TYPE_GPIO */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_ETHERNET */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_TERMINAL */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_MULTI */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( POUT_SETTINGS ), /* MBG_IO_PORT_TYPE_POUT */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SWITCH */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_TIMECODE_SETTINGS ), /* MBG_IO_PORT_TYPE_TIMECODE */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_LIGHT */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_ANT_SETTINGS ), /* MBG_IO_PORT_TYPE_ANTENNA */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( PORT_SETTINGS ), /* MBG_IO_PORT_TYPE_UART */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_DCF77 */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_POWER */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SPST_RELAY */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SPDT_RELAY */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( SYNTH ) /* MBG_IO_PORT_TYPE_SYNTHESIZER */ \ } enum MBG_IO_PORT_INFO_BITS { - MBG_IO_PORT_INFO_BIT_IS_ALIGNED ///< Indicates, that this port shall be optically aligned to ::MBG_IO_PORT_INFO::align_rule_idx + MBG_IO_PORT_INFO_BIT_IS_ALIGNED, ///< Indicates, that this port shall be optically aligned to ::MBG_IO_PORT_INFO::align_rule_idx + MBG_IO_PORT_INFO_BIT_PASSED_THROUGH_CFG_NOT_SUPP ///< Indicates, that the output signal of this port (defined in (::MBG_IO_PORT_SETTINGS::data) + ///< can not be configured, if ::MBG_IO_PORT_SETTINGS::op_mode is set to ::MBG_IO_PORT_OP_MODE_PASSTHROUGH + }; enum MBG_IO_PORT_INFO_MASKS { - MBG_IO_PORT_INFO_MASK_IS_ALIGNED = ( 1UL << MBG_IO_PORT_INFO_BIT_IS_ALIGNED ) ///< see ::MBG_IO_PORT_INFO_BIT_IS_ALIGNED + MBG_IO_PORT_INFO_MASK_IS_ALIGNED = ( 1UL << MBG_IO_PORT_INFO_BIT_IS_ALIGNED ), ///< See ::MBG_IO_PORT_INFO_BIT_IS_ALIGNED + MBG_IO_PORT_INFO_MASK_PASSED_THROUGH_CFG_NOT_SUPP = ( 1UL << MBG_IO_PORT_INFO_BIT_PASSED_THROUGH_CFG_NOT_SUPP ) ///< See ::MBG_IO_PORT_INFO_BIT_PASSED_THROUGH_CFG_NOT_SUPP + }; @@ -20815,7 +24331,7 @@ typedef struct uint8_t pos_col; ///< Column position of this port uint8_t pos_row; ///< Row position of this port uint8_t rear; ///< Indicates, whether the port is on the front or rear side - uint32_t pols; ///< Pols which are used by this IO port, only if @p conn_type has more than 1 variable pol + uint32_t pols; ///< Pols which are used by this IO port, only if #conn_type has more than 1 variable pol uint32_t flags; ///< Flags, see ::MBG_IO_PORT_INFO_MASKS uint32_t reserved_2[2]; ///< Future use and padding, currently 0 char use_str[MBG_IO_PORT_STR_SIZE]; ///< Informational string for user interface, i.e. "NTP Status LED" @@ -20861,7 +24377,7 @@ do \ */ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_IO_PORT_INFO info; } MBG_IO_PORT_INFO_IDX; @@ -20878,23 +24394,26 @@ do \ #define MBG_IO_PORT_INFO_IDX_MIN_SIZE (MBG_IO_PORT_INFO_MIN_SIZE + sizeof( uint32_t )) -#define MBG_IO_PORT_INFO_IDX_SIZES \ -{ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_PPS */ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_10MHz */ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_2048KHz */ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( MBG_GPIO_SETTINGS ), /* MBG_IO_PORT_TYPE_GPIO */ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_ETHERNET */ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_TERMINAL */ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_MULTI */ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( POUT_SETTINGS ), /* MBG_IO_PORT_TYPE_POUT */ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SWITCH */ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( IRIG_SETTINGS ), /* MBG_IO_PORT_TYPE_TIMECODE */ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_LIGHT */ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_ANT_SETTINGS ), /* MBG_IO_PORT_TYPE_ANTENNA */ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( PORT_SETTINGS ), /* MBG_IO_PORT_TYPE_UART */ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_DCF77 */ \ - MBG_IO_PORT_INFO_IDX_MIN_SIZE /* MBG_IO_PORT_TYPE_POWER */ \ +#define MBG_IO_PORT_INFO_IDX_SIZES \ +{ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_PPS */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_10MHz */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_2048KHz */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( MBG_GPIO_SETTINGS ), /* MBG_IO_PORT_TYPE_GPIO */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_ETHERNET */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_TERMINAL */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_MULTI */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( POUT_SETTINGS ), /* MBG_IO_PORT_TYPE_POUT */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SWITCH */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_TIMECODE_SETTINGS ), /* MBG_IO_PORT_TYPE_TIMECODE */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_LIGHT */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_ANT_SETTINGS ), /* MBG_IO_PORT_TYPE_ANTENNA */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( PORT_SETTINGS ), /* MBG_IO_PORT_TYPE_UART */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_DCF77 */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_POWER */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SPST_RELAY */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SPDT_RELAY */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( SYNTH ) /* MBG_IO_PORT_TYPE_SYNTHESIZER */ \ } @@ -20917,7 +24436,7 @@ typedef union { MBG_GPIO_LIMITS gpio_limits; POUT_INFO pout_info; - IRIG_INFO irig_info; + MBG_IO_PORT_TIMECODE_INFO timecode_info; PORT_INFO uart_info; MBG_IO_PORT_ANT_INFO ant_info; @@ -20937,7 +24456,7 @@ do \ break; \ \ case MBG_IO_PORT_TYPE_TIMECODE: \ - _mbg_swab_irig_info( &(_p)->irig_info ); \ + _mbg_swab_io_port_timecode_info( &(_p)->timecode_info ); \ break; \ \ case MBG_IO_PORT_TYPE_ANTENNA: \ @@ -20976,7 +24495,8 @@ typedef struct uint16_t port_type; ///< See ::MBG_IO_PORT_TYPES uint16_t reserved_1; ///< Future use and padding, currently 0 uint8_t supp_dirs; ///< See ::MBG_IO_PORT_DIR_MSKS - uint8_t pt_idx; ///< index of the port types (e.g. 0 for PPO0, 1 for PPO1, ...) + uint8_t pt_idx; ///< Index for this specific port type (e.g. 0 for PPO0, 1 for PPO1) + ///< especially interesting for passed through ports uint8_t shape_level; ///< Signal shape/level, see ::MBG_IO_PORT_SHAPE_LEVELS uint8_t reserved_2[1]; ///< Future use and padding, currently 0 uint32_t supp_srcs; ///< See ::MBG_IO_PORT_SRC_MSKS @@ -21006,23 +24526,26 @@ do \ #define MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE (MBG_IO_PORT_TYPE_INFO_MIN_SIZE + 2 * sizeof( uint32_t )) -#define MBG_IO_PORT_TYPE_INFO_IDX_SIZES \ -{ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_PPS */ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_10MHz */ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_2048KHz */ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( MBG_GPIO_LIMITS ), /* MBG_IO_PORT_TYPE_GPIO */ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_ETHERNET */ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_TERMINAL */ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_MULTI */ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( POUT_INFO ), /* MBG_IO_PORT_TYPE_POUT */ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SWITCH */ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( IRIG_INFO ), /* MBG_IO_PORT_TYPE_TIMECODE */ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_LIGHT */ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_ANT_INFO ), /* MBG_IO_PORT_TYPE_ANTENNA */ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( PORT_INFO ), /* MBG_IO_PORT_TYPE_UART */ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_DCF77 */ \ - MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE /* MBG_IO_PORT_TYPE_POWER */ \ +#define MBG_IO_PORT_TYPE_INFO_IDX_SIZES \ +{ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_PPS */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_10MHz */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_2048KHz */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( MBG_GPIO_LIMITS ), /* MBG_IO_PORT_TYPE_GPIO */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_ETHERNET */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_TERMINAL */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_MULTI */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( POUT_INFO ), /* MBG_IO_PORT_TYPE_POUT */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SWITCH */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_TIMECODE_INFO ), /* MBG_IO_PORT_TYPE_TIMECODE */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_LIGHT */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_ANT_INFO ), /* MBG_IO_PORT_TYPE_ANTENNA */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( PORT_INFO ), /* MBG_IO_PORT_TYPE_UART */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_DCF77 */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_POWER */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SPST_RELAY */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SPDT_RELAY */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE /* MBG_IO_PORT_TYPE_SYNTHESIZER */ \ } @@ -21065,13 +24588,13 @@ do \ /** - * @brief Port Type Status Bits + * @brief Port Status Bits * */ enum MBG_IO_PORT_STATUS_BITS { MBG_IO_PORT_STATUS_BIT_DISABLED, ///< See ::MBG_IO_PORT_OP_MODE_DISABLED. Other bits should be 0 in this case - MBG_IO_PORT_STATUS_BIT_CARRIER_DETECTED, ///< Port has physical carrier connection (e.g. BNC cable in BPE's case) + MBG_IO_PORT_STATUS_BIT_CARRIER_DETECTED, ///< Port has physical carrier connection (e.g. BNC cable in case of BPE) MBG_IO_PORT_STATUS_BIT_INPUT_SIGNAL_NEVER_AVAIL, ///< Input signal has NEVER been avail MBG_IO_PORT_STATUS_BIT_INPUT_SIGNAL_AVAIL, ///< Input signal is avail right now MBG_IO_PORT_STATUS_BIT_INPUT_SIGNAL_LOST, ///< Input signal is currently not avail, but has been avail before @@ -21080,6 +24603,8 @@ enum MBG_IO_PORT_STATUS_BITS MBG_IO_PORT_STATUS_BIT_LIGHT_GREEN, ///< LED shows green light MBG_IO_PORT_STATUS_BIT_LIGHT_BLUE, ///< LED shows blue light MBG_IO_PORT_STATUS_BIT_LIGHT_YELLOW, ///< LED shows yellow light + MBG_IO_PORT_STATUS_BIT_TIME_VERIFYING, ///< Received time gets verified + MBG_IO_PORT_STATUS_BIT_TELEGRAM_INCONSISTENT, ///< Received time telegram is inconsistent N_MBG_IO_PORT_STATUS_BITS }; @@ -21103,7 +24628,9 @@ enum MBG_IO_PORT_STATUS_BITS "Red", \ "Green", \ "Blue", \ - "Yellow" \ + "Yellow", \ + "Time gets verified", \ + "Telegram inconsistent" \ } @@ -21129,7 +24656,7 @@ enum MBG_IO_PORT_STATUS_BITS * @see ::_set_io_port_status_bit * @see ::check_feat_supp_byte_array */ -typedef struct +typedef struct mbg_io_port_status_buffer_s { uint8_t b[MAX_IO_PORT_STATUS_BYTES]; @@ -21167,7 +24694,7 @@ typedef struct /** - * @brief IO Port Type Status + * @brief IO Port Status * * @see @ref group_io_ports * @see ::MBG_IO_PORT_SETTINGS_U @@ -21206,7 +24733,7 @@ do \ /** - * @brief IO Port Type Status + * @brief IO Port Status * * @see @ref group_io_ports * @see ::MBG_IO_PORT_SETTINGS_U @@ -21218,13 +24745,13 @@ do \ * @see ::MBG_IO_PORT_TYPE_INFO_IDX * @see ::MBG_IO_PORT_STATUS * - * Indexes from 0..::MBG_IO_PORT_INFO::num_types - 1 are used + * Indexes from 0..::MBG_IO_PORT_LIMITS::num_ports - 1 are used * to query ::MBG_IO_PORT_TYPE_INFO wrapped in ::MBG_IO_PORT_TYPE_INFO_IDX. * */ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_IO_PORT_STATUS status; } MBG_IO_PORT_STATUS_IDX; @@ -21259,6 +24786,7 @@ enum MBG_MONITORING_TYPES MBG_MONITORING_TYPE_SNMP, MBG_MONITORING_TYPE_EMAIL, MBG_MONITORING_TYPE_SYSLOG, + MBG_MONITORING_TYPE_EVENTS, N_MBG_MONITORING_TYPES }; @@ -21266,14 +24794,16 @@ enum MBG_MONITORING_TYPES { \ "SNMP", \ "Email", \ - "Syslog" \ + "Syslog", \ + "Events" \ } enum MBG_MONITORING_TYPE_MSKS { MBG_MONITORING_TYPE_MSK_SNMP = (1UL << MBG_MONITORING_TYPE_SNMP), MBG_MONITORING_TYPE_MSK_EMAIL = (1UL << MBG_MONITORING_TYPE_EMAIL), - MBG_MONITORING_TYPE_MSK_SYSLOG = (1UL << MBG_MONITORING_TYPE_SYSLOG) + MBG_MONITORING_TYPE_MSK_SYSLOG = (1UL << MBG_MONITORING_TYPE_SYSLOG), + MBG_MONITORING_TYPE_MSK_EVENTS = (1UL << MBG_MONITORING_TYPE_EVENTS) }; @@ -21281,7 +24811,7 @@ enum MBG_MONITORING_TYPE_MSKS typedef struct { uint16_t supp_types; ///< See ::MBG_MONITORING_TYPE_MSKS - uint16_t supp_num_events; ///< Supported number of events. See ::MBG_EVENT_TYPES + uint16_t reserved_1; uint32_t reserved_2[3]; } MBG_MONITORING_LIMITS; @@ -21290,7 +24820,6 @@ typedef struct do \ { \ _mbg_swab16( &(_p)->supp_types ); \ - _mbg_swab16( &(_p)->supp_num_events ); \ } while ( 0 ) @@ -21324,6 +24853,7 @@ enum MBG_SNMP_FLAGS { MBG_SNMP_SYSTEM_USER, MBG_SNMP_ADD_CONF, ///< Supports additional SNMP configuration (i.e. via script) + MBG_SNMP_READ_ONLY, ///< Read/Write is not supported, SNMP can be used for monitoring, only N_MBG_SNMP_FLAGS }; @@ -21331,14 +24861,16 @@ enum MBG_SNMP_FLAGS #define MBG_SNMP_FLAG_STRS \ { \ "System user", \ - "Additional config" \ + "Additional config", \ + "Read-Only" \ } enum MBG_SNMP_FLAG_MSKS { MBG_SNMP_SYSTEM_USER_MSK = ( 1UL << MBG_SNMP_SYSTEM_USER ), - MBG_SNMP_ADD_CONF_MSK = ( 1UL << MBG_SNMP_ADD_CONF ) ///< see ::MBG_SNMP_ADD_CONF + MBG_SNMP_ADD_CONF_MSK = ( 1UL << MBG_SNMP_ADD_CONF ), ///< See ::MBG_SNMP_ADD_CONF + MBG_SNMP_READ_ONLY_MSK = ( 1UL << MBG_SNMP_READ_ONLY ) ///< See ::MBG_SNMP_READ_ONLY }; @@ -21374,7 +24906,7 @@ do \ -typedef struct +typedef struct mbg_snmp_glb_info_s { MBG_SNMP_GLB_SETTINGS settings; uint8_t supp_versions; ///< See ::MBG_SNMP_VERSION_MSKS @@ -21383,8 +24915,7 @@ typedef struct uint8_t max_v12_trap_receivers; ///< Only valid if ::MBG_SNMP_GLB_INFO::supp_versions contains ::MBG_SNMP_VERSION_MSK_V1 or ::MBG_SNMP_VERSION_MSK_V2c uint8_t max_v3_trap_receivers; ///< Only valid if ::MBG_SNMP_GLB_INFO::supp_versions contains ::MBG_SNMP_VERSION_MSK_V3 uint8_t reserved_1[1]; - uint16_t supp_flags; ///< See ::MBG_SNMP_FLAG_MSKS - /// MBG_SNMP_SYSTEM_USER_MSK is only relevant for SNMPv3 + uint16_t supp_flags; ///< See ::MBG_SNMP_FLAG_MSKS. ::MBG_SNMP_SYSTEM_USER_MSK is only relevant for SNMPv3. uint32_t reserved_2[2]; } MBG_SNMP_GLB_INFO; @@ -21433,7 +24964,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_SNMP_V12_SETTINGS settings; } MBG_SNMP_V12_SETTINGS_IDX; @@ -21447,7 +24978,7 @@ do \ -typedef struct +typedef struct mbg_snmp_v12_info_s { MBG_SNMP_V12_SETTINGS settings; uint32_t reserved_1[4]; @@ -21464,7 +24995,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_SNMP_V12_INFO info; } MBG_SNMP_V12_INFO_IDX; @@ -21504,7 +25035,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_SNMP_V12_TRAP_SETTINGS settings; } MBG_SNMP_V12_TRAP_SETTINGS_IDX; @@ -21518,7 +25049,7 @@ do \ -typedef struct +typedef struct mbg_snmp_v12_trap_info_s { MBG_SNMP_V12_TRAP_SETTINGS settings; uint32_t reserved_1[4]; @@ -21535,7 +25066,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_SNMP_V12_TRAP_INFO info; } MBG_SNMP_V12_TRAP_INFO_IDX; @@ -21636,7 +25167,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_SNMP_V3_SETTINGS settings; } MBG_SNMP_V3_SETTINGS_IDX; @@ -21650,7 +25181,7 @@ do \ -typedef struct +typedef struct mbg_snmp_v3_info_s { MBG_SNMP_V3_SETTINGS settings; uint32_t reserved_1[4]; @@ -21667,7 +25198,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_SNMP_V3_INFO info; } MBG_SNMP_V3_INFO_IDX; @@ -21705,7 +25236,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_SNMP_V3_TRAP_SETTINGS settings; } MBG_SNMP_V3_TRAP_SETTINGS_IDX; @@ -21719,7 +25250,7 @@ do \ -typedef struct +typedef struct mbg_snmp_v3_trap_info_s { MBG_SNMP_V3_TRAP_SETTINGS settings; uint32_t reserved_1[4]; @@ -21736,7 +25267,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_SNMP_V3_TRAP_INFO info; } MBG_SNMP_V3_TRAP_INFO_IDX; @@ -21750,19 +25281,149 @@ do \ +/* If ::MBG_MONITORING_TYPE_MSK_EVENTS is set in ::MBG_MONITORING_LIMITS::supp_types */ + + +enum MBG_EVENT_STR_FMTS +{ + MBG_EVENT_STR_FMT_JSON, + N_MBG_EVENT_STR_FMTS +}; + + +enum MBG_EVENT_STR_FMT_MSKS +{ + MBG_EVENT_STR_FMT_JSON_MSK = (1UL << MBG_EVENT_STR_FMT_JSON) +}; + + +#define MBG_EVENT_STR_FMT_STRS \ +{ \ + "JSON" \ +} + + +enum MBG_EVENT_DEV_IDS +{ + MBG_EVENT_DEV_ID_NONE, ///< No identifier added to the events + MBG_EVENT_DEV_ID_ALIAS, ///< Add alias from MBG_EVENT_GLB_SETTINGS as identifier to all events + MBG_EVENT_DEV_ID_SERNUM, ///< Add serial number as identifier to all events + N_MBG_EVENT_DEV_IDS +}; + + +enum MBG_EVENT_DEV_ID_MSKS +{ + MBG_EVENT_DEV_ID_NONE_MSK = ( 1UL << MBG_EVENT_DEV_ID_NONE ), ///< See ::MBG_EVENT_DEV_ID_NONE + MBG_EVENT_DEV_ID_ALIAS_MSK = ( 1UL << MBG_EVENT_DEV_ID_ALIAS ), ///< See ::MBG_EVENT_DEV_ID_ALIAS + MBG_EVENT_DEV_ID_SERNUM_MSK = ( 1UL << MBG_EVENT_DEV_ID_SERNUM ) ///< See ::MBG_EVENT_DEV_ID_SERNUM +}; + + +#define MBG_EVENT_DEV_ID_STRS \ +{ \ + "None", \ + "Alias", \ + "Serial Number" \ +} + + +enum MBG_EVENT_GLB_FLAGS +{ + MBG_EVENT_GLB_FLAG_FUE, ///< Forward unknown events. This is not relevant for mbgdevman + ///< that always gets all events. It's important for syslog, SNMP, email, etc.. + ///< to avoid that alarming systems react furious to unknown events. + N_MBG_EVENT_GLB_FLAGS +}; + + +enum MBG_EVENT_GLB_FLAG_MSKS +{ + MBG_EVENT_GLB_FLAG_FUE_MSK = ( 1UL << MBG_EVENT_GLB_FLAG_FUE ) ///< See ::MBG_EVENT_GLB_FLAG_FUE +}; + + +typedef struct +{ + uint8_t format; ///< See ::MBG_EVENT_STR_FMTS + uint8_t dev_id; ///< See ::MBG_EVENT_DEV_IDS + uint8_t flags; ///< See ::MBG_EVENT_GLB_FLAG_MSKS + uint8_t reserved_1[5]; + + char alias[16]; ///< Alias of this device, see ::MBG_EVENT_DEV_ID_ALIAS + + uint32_t reserved_3[4]; + +} MBG_EVENT_GLB_SETTINGS; + +#define _mbg_swab_event_glb_settings( _p ) \ +do \ +{ \ +} while ( 0 ) + + +typedef struct mbg_event_glb_info_s +{ + MBG_EVENT_GLB_SETTINGS settings; ///< See ::MBG_EVENT_GLB_SETTINGS + + uint16_t num_events; ///< Supported number of events. See ::MBG_EVENT_TYPES + uint16_t supp_formats; ///< Supported format (::MBG_EVENT_STR_FMTS) in ::MBG_EVENT_STATUS::data + uint16_t supp_dev_ids; ///< Supported dev ids (::MBG_EVENT_DEV_IDS) that can be added to each ::MBG_EVENT_STATUS::data + uint8_t supp_flags; ///< Supported global settings flags. See ::MBG_EVENT_GLB_FLAG_MSKS + uint8_t reserved_1; + + uint32_t reserved_2[3]; + +} MBG_EVENT_GLB_INFO; + +#define _mbg_swab_event_glb_info( _p ) \ +do \ +{ \ + _mbg_swab_event_glb_settings( (_p) ); \ + _mbg_swab16( &(_p)->num_events ); \ + _mbg_swab16( &(_p)->supp_formats ); \ + _mbg_swab16( &(_p)->supp_dev_ids ); \ +} while ( 0 ) + + + enum MBG_EVENT_TYPES { MBG_EVENT_TYPE_NTP_STATE, MBG_EVENT_TYPE_HEARTBEAT, MBG_EVENT_TYPE_RECEIVER_STATE, + MBG_EVENT_TYPE_LEAP_SECOND, + MBG_EVENT_TYPE_PTP_STATE, + MBG_EVENT_TYPE_SYSREF_MASTER_REF, + MBG_EVENT_TYPE_PS_STATE, + MBG_EVENT_TYPE_REBOOT, + MBG_EVENT_TYPE_MEMORY, + MBG_EVENT_TYPE_CPU_LOAD, + MBG_EVENT_TYPE_TEMPERATURE, + MBG_EVENT_TYPE_NW_LINK, + MBG_EVENT_TYPE_CONFIG, + MBG_EVENT_TYPE_LOGIN, + MBG_EVENT_TYPE_WATCHDOG, N_MBG_EVENT_TYPES }; -#define MBG_EVENT_TYPE_STRS \ -{ \ - "NTP state", \ - "Heartbeat", \ - "Receiver state" \ +#define MBG_EVENT_TYPE_STRS \ +{ \ + "NTP state", \ + "Heartbeat", \ + "Receiver state", \ + "Leap second", \ + "PTP state", \ + "Master reference changed", \ + "Power supply state", \ + "Reboot", \ + "Memory", \ + "CPU load", \ + "Temperature", \ + "Network link", \ + "Configuration", \ + "Login", \ + "Watchdog" \ } @@ -21811,7 +25472,7 @@ do \ */ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_EVENT_SETTINGS settings; } MBG_EVENT_SETTINGS_IDX; @@ -21864,28 +25525,31 @@ enum MBG_EVENT_SUPP_FLAG_MSKS #define MBG_OWN_EVENT_SLOT_TYPE 0xFF ///< See ::MBG_EVENT_INFO::slot_type #define MBG_OWN_EVENT_SLOT_TYPE_ID 0xFF ///< See ::MBG_EVENT_INFO::slot_type_id #define MBG_INV_EVENT_PORT 0xFF ///< See ::MBG_EVENT_INFO::port_idx +#define MBG_INV_EVENT_INST 0xFF ///< See ::MBG_EVENT_INFO::inst_idx /** @} defgroup group_mbg_event_info_indexes */ - typedef struct { - MBG_EVENT_SETTINGS settings; ///< See ::MBG_EVENT_SETTINGS - uint16_t type; ///< See ::MBG_EVENT_TYPES - uint8_t chassis_idx; ///< Index of the associated IMS chassis, or ::MBG_OWN_EVENT_CHASSIS - uint8_t slot_type; ///< See ::XBP_NODE_INFO::slot_type, or ::MBG_OWN_EVENT_SLOT_TYPE - uint8_t port_idx; ///< Index of the associated IO port, or ::MBG_INV_EVENT_PORT - uint8_t value_type; ///< See ::MBG_EVENT_VALUE_TYPES - uint16_t value_dict_entries; ///< Number of entries in value dictionary, see ::MBG_EVENT_VALUE_IDX + MBG_EVENT_SETTINGS settings; ///< See ::MBG_EVENT_SETTINGS + uint16_t type; ///< See ::MBG_EVENT_TYPES + uint8_t chassis_idx; ///< Index of the associated IMS chassis, or ::MBG_OWN_EVENT_CHASSIS + uint8_t slot_type; ///< See ::XBP_NODE_INFO::slot_type, or ::MBG_OWN_EVENT_SLOT_TYPE + uint8_t port_idx; ///< Index of the associated IO port, or ::MBG_INV_EVENT_PORT + uint8_t reserved_1; + uint16_t reserved_2; - uint8_t slot_type_id; ///< See ::XBP_NODE_INFO::slot_type_id, or ::MBG_OWN_EVENT_SLOT_TYPE_ID - uint8_t reserved_1; ///< Future use - uint16_t supp_flags; ///< See ::MBG_EVENT_SUPP_FLAG_MSKS - uint16_t supp_triggers; ///< See ::MBG_MONITORING_TYPE_MSKS - uint16_t reserved_2; ///< Future use + uint8_t slot_type_id; ///< See ::XBP_NODE_INFO::slot_type_id, or ::MBG_OWN_EVENT_SLOT_TYPE_ID + uint8_t inst_idx; ///< Instance index since one port might have multiple instances of the same type. + ///< For example, PTP is hopefully capable to do so one day. + ///< Use ::MBG_INV_EVENT_INST to not show the instance number explicitly, + ///< e.g. you only have got one instance. + uint16_t supp_flags; ///< See ::MBG_EVENT_SUPP_FLAG_MSKS + uint16_t supp_triggers; ///< See ::MBG_MONITORING_TYPE_MSKS + uint16_t reserved_3; ///< Future use - uint32_t reserved_3[6]; + uint32_t reserved_4[8]; } MBG_EVENT_INFO; @@ -21897,7 +25561,6 @@ do \ _mbg_swab16( &(_p)->value_dict_entries ); \ _mbg_swab16( &(_p)->supp_flags ); \ _mbg_swab16( &(_p)->supp_triggers ); \ - _mbg_swab16( &(_p)->flags ); \ } while ( 0 ) @@ -21907,14 +25570,14 @@ do \ * * @note idx represents the event type, see ::MBG_EVENT_TYPES * Before requesting the struct, its availability should be checked - * in ::MBG_MONITORING_LIMITS::supp_num_events. + * in ::MBG_EVENT_GLB_INFO::num_events. * * @see ::MBG_EVENT_TYPES - * @see ::MBG_MONITORING_LIMITS + * @see ::MBG_EVENT_GLB_INFO */ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_EVENT_INFO info; } MBG_EVENT_INFO_IDX; @@ -21927,187 +25590,39 @@ do \ } while ( 0 ) -enum MBG_EVENT_VALUE_TYPES -{ - MBG_EVENT_VALUE_TYPE_NONE, ///< Sounds stupid but think of heartbeat - MBG_EVENT_VALUE_TYPE_INTEGER32, - MBG_EVENT_VALUE_TYPE_UNSIGNED32, - MBG_EVENT_VALUE_TYPE_STRING, - MBG_EVENT_VALUE_TYPE_IRANGE, - MBG_EVENT_VALUE_TYPE_URANGE, - MBG_EVENT_VALUE_TYPE_SELECTION, - N_MBG_EVENT_VALUE_TYPES -}; - - - -#define MBG_EVENT_VALUE_TYPE_STRS \ -{ \ - "None", \ - "Signed32", \ - "Unsigned32", \ - "String", \ - "Signed range", \ - "Unsigned range", \ - "Selection" \ -} - - - -typedef char MBG_EVENT_STR[64]; - - - -typedef struct -{ - int32_t value; - MBG_EVENT_STR string; - -} MBG_EVENT_VALUE_SELECTION; - -#define _mbg_swab_event_value_selection( _p ) \ -do \ -{ \ - _mbg_swab32( &(_p)->value ); \ -} while ( 0 ) - - - -typedef struct -{ - int32_t min; - int32_t max; - -} MBG_EVENT_VALUE_IRANGE; - -#define _mbg_swab_event_value_irange( _p ) \ -do \ -{ \ - _mbg_swab32( &(_p)->min ); \ - _mbg_swab32( &(_p)->max ); \ -} while ( 0 ) - - - -typedef struct -{ - uint32_t min; - uint32_t max; - -} MBG_EVENT_VALUE_URANGE; - -#define _mbg_swab_event_value_urange( _p ) \ -do \ -{ \ - _mbg_swab32( &(_p)->min ); \ - _mbg_swab32( &(_p)->max ); \ -} while ( 0 ) - - -/* - * Maximum size is limited to 68 bytes -> MBG_EVENT_VALUE_SELECTION - * Don't enlarge it due to compatibility reasons!! - */ -typedef union -{ - MBG_EVENT_VALUE_SELECTION selection; - MBG_EVENT_VALUE_IRANGE irange; - MBG_EVENT_VALUE_URANGE urange; - -} MBG_EVENT_VALUE; - -#define _mbg_swab_event_value( _p, _type ) \ -do \ -{ \ - switch ( (_type) ) \ - { \ - case MBG_EVENT_VALUE_TYPE_SELECTION: \ - _mbg_swab_event_value_selection( &(_p)->selection ); \ - break; \ - \ - case MBG_EVENT_VALUE_TYPE_IRANGE: \ - _mbg_swab_event_value_irange( &(_p)->irange ); \ - break; \ - \ - case MBG_EVENT_VALUE_TYPE_URANGE: \ - _mbg_swab_event_value_urange( &(_p)->urange ); \ - break; \ - \ - default: \ - break; \ - } \ -} while ( 0 ) - - +#define MBG_EVT_ST_MAX_DATA_LEN 480 typedef struct { - uint32_t idx; - MBG_EVENT_VALUE value; + uint32_t last_changed; ///< Unix timestamp when this event state has been changed + uint32_t reserved_1[2]; ///< Future use + uint8_t severity; ///< See ::MBG_EVENT_SEVERITIES + uint8_t reserved_2[3]; ///< Future use -} MBG_EVENT_VALUE_IDX; - -#define _mbg_swab_event_value_idx( _p, _type ) \ -do \ -{ \ - _mbg_swab32( &(_p)->idx ); \ - _mbg_swab_event_value( &(_p)->value, (_type) ); \ -} while ( 0 ) - - -/* - * Maximum union size is limited to 64 bytes -> MBG_EVENT_STR - * Don't enlarge the union due to compatibility reasons!! - */ -typedef struct -{ - uint32_t last_changed; ///< Unix timestamp when this event state has been changed - uint32_t reserved_1[3]; ///< Future use - uint8_t severity; ///< See ::MBG_EVENT_SEVERITIES - uint8_t reserved_2[3]; ///< Future use - union - { - int32_t i32; - uint32_t u32; - MBG_EVENT_STR string; - - } u; + uint8_t data[MBG_EVT_ST_MAX_DATA_LEN]; ///< The event value in the configured format, see ::MBG_EVENT_GLB_SETTINGS::format } MBG_EVENT_STATUS; -#define _mbg_swab_event_status( _p, _type ) \ -do \ -{ \ - _mbg_swab32( &(_p)->last_changed ); \ - switch ( (_type) ) \ - { \ - case MBG_EVENT_VALUE_TYPE_INTEGER32: \ - _mbg_swab32( &(_p)->u.i32 ); \ - break; \ - \ - case MBG_EVENT_VALUE_TYPE_UNSIGNED32: \ - _mbg_swab32( &(_p)->u.u32 ); \ - break; \ - \ - default: \ - break; \ - } \ +#define _mbg_swab_event_status( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->last_changed ); \ } while ( 0 ) typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_EVENT_STATUS status; } MBG_EVENT_STATUS_IDX; -#define _mbg_swab_event_status_idx( _p, _type ) \ -do \ -{ \ - _mbg_swab32( &(_p)->idx ); \ - _mbg_swab_event_status( &(_p)->status, (_type) ); \ +#define _mbg_swab_event_status_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_event_status( &(_p)->status ); \ } while ( 0 ) @@ -22160,7 +25675,7 @@ do \ } while ( 0 ) -typedef struct +typedef struct mbg_syslog_glb_info_s { MBG_SYSLOG_GLB_SETTINGS settings; ///< MBG_SYSLOG_GLB_SETTINGS @@ -22204,7 +25719,7 @@ do \ typedef struct { MBG_SYSLOG_SETTINGS settings; - uint32_t idx; + MBG_MSG_IDX_32 idx; } MBG_SYSLOG_SETTINGS_IDX; @@ -22233,7 +25748,7 @@ do \ typedef struct { MBG_SYSLOG_INFO info; ///< See ::MBG_SYSLOG_INFO - uint32_t idx; + MBG_MSG_IDX_32 idx; } MBG_SYSLOG_INFO_IDX; @@ -22254,11 +25769,11 @@ do \ * @note This structure and its definitions are only supported by a device * if ::MBG_XFEATURE_TAINTED_CFG is set in the extended device features. * Feature has a list of configuration counters for several sub-features. - * Each time a sub-feature's config changes, its counter in this structure - * is increased to indicate a config change. Thus, software can read this - * structure and request the changed config. Also use it for push notifications. + * Each time the config of a sub-feature changes, its counter in this structure + * is increased to indicate the config change. Thus, software can read this + * structure and request the changed config. Also used for push notifications. * - * TODO: Add proper Doxygen documentation + * TODO Add proper Doxygen documentation * * @{ */ @@ -22298,6 +25813,9 @@ enum MBG_TAINTED_CFGS MBG_TAINTED_CFG_TZDL, MBG_TAINTED_CFG_CABLE_LENGTH, MBG_TAINTED_CFG_DATABASE, + MBG_TAINTED_CFG_PTP_NG, + MBG_TAINTED_CFG_SYS_REF, + MBG_TAINTED_CFG_TR_DIST, N_MBG_TAINTED_CFGS }; @@ -22367,7 +25885,7 @@ do \ * * @{ */ -typedef enum +typedef enum _mbg_user_perms { USER_PERM_SYSTEM, ///< permission to read/write system related structures ///< ::GPS_SCU_STAT @@ -22404,6 +25922,10 @@ typedef enum ///< ::GPS_XMR_HOLDOVER_STATUS ///< ::GPS_XMR_STATS_IDX ///< ::GPS_XMR_METRICS_IDX + ///< ::GPS_SYS_REF_LIMITS + ///< ::GPS_SYS_REF_GLB_STATUS + ///< ::GPS_SYS_REF_SRC_INFO_IDX + ///< ::GPS_SYS_REF_SRC_STATUS_IDX USER_PERM_SERIAL, ///< permission to read/write serial port related structures ///< ::GPS_PORT_INFO_IDX ///< ::GPS_STR_TYPE_INFO_IDX @@ -22440,7 +25962,6 @@ typedef enum ///< ::GPS_SNMP_V3_TRAP_IDX ///< ::GPS_EVENT_IDX ///< ::GPS_EVENT_STAT_IDX - ///< ::GPS_EVENT_VALUE_IDX ///< ::GPS_NUM_EVT_LOG_ENTRIES ///< ::GPS_FIRST_EVT_LOG_ENTRY ///< ::GPS_NEXT_EVT_LOG_ENTRY @@ -22492,6 +26013,11 @@ typedef enum ///< ::GPS_PTP_V1_PARENT_DS ///< ::GPS_PTP_V1_TIME_PROP_DS ///< ::GPS_PTP_V1_PORT_DS_IDX + ///< ::GPS_PTP_NG_GLB_INFO + ///< ::GPS_PTP_NG_TSTAMPER_INFO_IDX + ///< ::GPS_PTP_NG_INSTC_INFO_IDX + ///< ::GPS_PTP_NG_INSTC_STATUS_IDX + ///< ::GPS_PTP_NG_UC_MASTER_INFO_IDX USER_PERM_FDM, ///< permission to read/write FDM related structures ///< ::GPS_FDM_LIMITS ///< ::GPS_FDM_INFO @@ -22521,10 +26047,10 @@ typedef enum ///< ::MBG_TLV_FEAT_TYPE_UFU ///< ::MBG_TLV_FEAT_TYPE_FW_ROLLBACK USER_PERM_SERVICE, ///< permission to read/write service related structures - ///< ::GPS_SRV_MGMT_INFO - ///< ::GPS_SRV_INFO_IDX - ///< ::GPS_SRV_STATUS_IDX - ///< ::GPS_SRV_CTL_IDX + ///< ::GPS_SVC_MGMT_INFO + ///< ::GPS_SVC_INFO_IDX + ///< ::GPS_SVC_STATUS_IDX + ///< ::GPS_SVC_CTL_IDX USER_PERM_DATABASE, ///< permission to read/write database related structures ///< ::GPS_DATABASE_GLB_INFO ///< ::GPS_DATABASE_INFO_IDX @@ -22559,7 +26085,7 @@ typedef enum } -typedef enum +typedef enum _mbg_user_scopes { USER_SCOPE_STATUS_READ, USER_SCOPE_CONFIG_READ, @@ -22571,12 +26097,19 @@ typedef enum typedef enum { - USER_SCOPE_STATUS_READ_MSK = ( 1UL << USER_SCOPE_STATUS_READ ), ///< see ::USER_SCOPE_STATUS_READ - USER_SCOPE_CONFIG_READ_MSK = ( 1UL << USER_SCOPE_CONFIG_READ ), ///< see ::USER_SCOPE_CONFIG_READ - USER_SCOPE_CONFIG_WRITE_MSK = ( 1UL << USER_SCOPE_CONFIG_WRITE ) ///< see ::USER_SCOPE_CONFIG_WRITE + USER_SCOPE_STATUS_READ_MSK = ( 1UL << USER_SCOPE_STATUS_READ ), ///< See ::USER_SCOPE_STATUS_READ + USER_SCOPE_CONFIG_READ_MSK = ( 1UL << USER_SCOPE_CONFIG_READ ), ///< See ::USER_SCOPE_CONFIG_READ + USER_SCOPE_CONFIG_WRITE_MSK = ( 1UL << USER_SCOPE_CONFIG_WRITE ) ///< See ::USER_SCOPE_CONFIG_WRITE } MBG_USER_SCOPE_MSKS; +/// @brief a combined permission mask to read configuration or status. +/// +/// In most cases the permission to read the configuration includes +/// the permission to read the status, anyway. +#define USER_SCOPE_CONFIG_OR_STATUS_READ_MSK \ + ( USER_SCOPE_CONFIG_READ_MSK | USER_SCOPE_STATUS_READ_MSK ) + #define MAX_USER_PERM_BYTES 64 #define MAX_USER_PERM_BITS MAX_USER_PERM_BYTES * 8 @@ -22624,7 +26157,7 @@ typedef enum * @see ::_set_user_perm * @see ::_check_user_perm */ -typedef struct +typedef struct mbg_user_perm_buf_s { uint8_t b[MAX_USER_PERM_BYTES]; ///< buffer for user permissions, see ::_set_user_perm and ::_check_user_perm @@ -22718,8 +26251,8 @@ typedef enum typedef enum { - USER_MNGMNT_SUPP_USER_CFG_MASK = ( 1UL << USER_MNGMNT_SUPP_USER_CFG ), ///< see ::USER_MNGMNT_SUPP_USER_CFG - USER_MNGMNT_SUPP_USER_LEVEL_CFG_MASK = ( 1UL << USER_MNGMNT_SUPP_USER_LEVEL_CFG ) ///< see ::USER_MNGMNT_SUPP_USER_LEVEL_CFG + USER_MNGMNT_SUPP_USER_CFG_MASK = ( 1UL << USER_MNGMNT_SUPP_USER_CFG ), ///< See ::USER_MNGMNT_SUPP_USER_CFG + USER_MNGMNT_SUPP_USER_LEVEL_CFG_MASK = ( 1UL << USER_MNGMNT_SUPP_USER_LEVEL_CFG ) ///< See ::USER_MNGMNT_SUPP_USER_LEVEL_CFG } MBG_USER_MNGMNT_FLAG_MASKS; @@ -22793,6 +26326,8 @@ typedef enum USER_CFG_FORCE_DISABLE_ON_EXP, ///< user account will immediately be disabled on password expiration, if this flags is not set, ///< the user shall be forced to change the password on the next login attempt USER_CFG_PASSWORD_CHANGED, ///< Indicates, that the password has been changed and needs to be crypted + USER_CFG_CAN_SHELL_SUDO, ///< The user is allowed to increase the privilege level by using sudo tool. + ///< Only relevant if user is allowed to use shell channel. N_USER_CFG_FLAGS } MBG_USER_CFG_FLAGS; @@ -22800,19 +26335,20 @@ typedef enum typedef enum { - USER_CFG_CAN_LOGIN_MASK = ( 1UL << USER_CFG_CAN_LOGIN ), ///< see ::USER_CFG_CAN_LOGIN - USER_CFG_CAN_REMOVE_MASK = ( 1UL << USER_CFG_CAN_REMOVE ), ///< see ::USER_CFG_CAN_REMOVE - USER_CFG_CAN_DISABLE_ON_FAILS_MASK = ( 1UL << USER_CFG_CAN_DISABLE_ON_FAILS ), ///< see ::USER_CFG_CAN_DISABLE_ON_FAILS - USER_CFG_MULTI_SESSION_MASK = ( 1UL << USER_CFG_MULTI_SESSION ), ///< see ::USER_CFG_MULTI_SESSION - USER_CFG_FORCE_CHANGE_ON_WARN_MASK = ( 1UL << USER_CFG_FORCE_CHANGE_ON_WARN ), ///< see ::USER_CFG_FORCE_CHANGE_ON_WARN - USER_CFG_FORCE_DISABLE_ON_EXP_MASK = ( 1UL << USER_CFG_FORCE_DISABLE_ON_EXP ), ///< see ::USER_CFG_FORCE_DISABLE_ON_EXP - USER_CFG_PASSWORD_CHANGED_MASK = ( 1UL << USER_CFG_PASSWORD_CHANGED ) ///< see ::USER_CFG_PASSWORD_CHANGED + USER_CFG_CAN_LOGIN_MASK = ( 1UL << USER_CFG_CAN_LOGIN ), ///< See ::USER_CFG_CAN_LOGIN + USER_CFG_CAN_REMOVE_MASK = ( 1UL << USER_CFG_CAN_REMOVE ), ///< See ::USER_CFG_CAN_REMOVE + USER_CFG_CAN_DISABLE_ON_FAILS_MASK = ( 1UL << USER_CFG_CAN_DISABLE_ON_FAILS ), ///< See ::USER_CFG_CAN_DISABLE_ON_FAILS + USER_CFG_MULTI_SESSION_MASK = ( 1UL << USER_CFG_MULTI_SESSION ), ///< See ::USER_CFG_MULTI_SESSION + USER_CFG_FORCE_CHANGE_ON_WARN_MASK = ( 1UL << USER_CFG_FORCE_CHANGE_ON_WARN ), ///< See ::USER_CFG_FORCE_CHANGE_ON_WARN + USER_CFG_FORCE_DISABLE_ON_EXP_MASK = ( 1UL << USER_CFG_FORCE_DISABLE_ON_EXP ), ///< See ::USER_CFG_FORCE_DISABLE_ON_EXP + USER_CFG_PASSWORD_CHANGED_MASK = ( 1UL << USER_CFG_PASSWORD_CHANGED ), ///< See ::USER_CFG_PASSWORD_CHANGED + USER_CFG_CAN_SHELL_SUDO_MASK = ( 1UL << USER_CFG_CAN_SHELL_SUDO ) ///< See ::USER_CFG_CAN_SHELL_SUDO } MBG_USER_CFG_FLAG_MASKS; -#define MBG_MAX_USER_NAME_LEN 32 /// See manpage useradd -#define MBG_MAX_USER_PASSWORD_LEN 32 +#define MBG_MAX_USER_NAME_LEN 32 ///< See man page for 'useradd'. +#define MBG_MAX_USER_PASSWORD_LEN 128 typedef struct @@ -22835,7 +26371,7 @@ typedef struct MBG_USER_PERM_BUF cfg_read_perm; ///< config read permission configuration, see ::MBG_USER_PERM_BUF and ::MBG_USER_PERMS MBG_USER_PERM_BUF cfg_write_perm; ///< config write permission configuration, see ::MBG_USER_PERM_BUF and ::MBG_USER_PERMS - uint32_t reserved[16]; ///< reserved, currently always 0 + uint32_t reserved[8]; ///< reserved, currently always 0 } MBG_USER_SETTINGS; @@ -22852,8 +26388,8 @@ do \ typedef struct { - uint32_t idx; ///< the index of the user - MBG_USER_SETTINGS settings; ///< settings, see ::MBG_USER_SETTINGS + MBG_MSG_IDX_32 idx; ///< The index of the user. + MBG_USER_SETTINGS settings; ///< Settings, see ::MBG_USER_SETTINGS. } MBG_USER_SETTINGS_IDX; @@ -22880,7 +26416,7 @@ typedef struct uint32_t password_doc; ///< time of last password change (days since 1970) uint32_t supp_flags; ///< supported flags, see ::MBG_USER_CFG_FLAG_MASKS - uint32_t reserved_3[16]; ///< reserved, currently always 0 + uint32_t reserved_3[8]; ///< reserved, currently always 0 } MBG_USER_INFO; @@ -22898,7 +26434,7 @@ do \ typedef struct { - uint32_t idx; ///< the index of the user + MBG_MSG_IDX_32 idx; ///< the index of the user MBG_USER_INFO info; ///< info, see ::MBG_USER_INFO } MBG_USER_INFO_IDX; @@ -22925,10 +26461,10 @@ typedef enum typedef enum { - USER_STAT_PASSWORD_WARN_MASK = ( 1UL << USER_STAT_PASSWORD_WARN ), ///< see ::USER_STAT_PASSWORD_WARN - USER_STAT_PASSWORD_EXP_MASK = ( 1UL << USER_STAT_PASSWORD_EXP ), ///< see ::USER_STAT_PASSWORD_EXP - USER_STAT_DISABLED_ON_EXP_MASK = ( 1UL << USER_STAT_DISABLED_ON_EXP ), ///< see ::USER_STAT_DISABLED_ON_EXP - USER_STAT_DISABLED_ON_MAX_FAILS_MASK = ( 1UL << USER_STAT_DISABLED_ON_MAX_FAILS ) ///< see ::USER_STAT_DISABLED_ON_MAX_FAILS + USER_STAT_PASSWORD_WARN_MASK = ( 1UL << USER_STAT_PASSWORD_WARN ), ///< See ::USER_STAT_PASSWORD_WARN + USER_STAT_PASSWORD_EXP_MASK = ( 1UL << USER_STAT_PASSWORD_EXP ), ///< See ::USER_STAT_PASSWORD_EXP + USER_STAT_DISABLED_ON_EXP_MASK = ( 1UL << USER_STAT_DISABLED_ON_EXP ), ///< See ::USER_STAT_DISABLED_ON_EXP + USER_STAT_DISABLED_ON_MAX_FAILS_MASK = ( 1UL << USER_STAT_DISABLED_ON_MAX_FAILS ) ///< See ::USER_STAT_DISABLED_ON_MAX_FAILS } MBG_USER_STAT_FLAG_MASKS; @@ -22959,7 +26495,7 @@ do \ typedef struct { - uint32_t idx; ///< the index of the user + MBG_MSG_IDX_32 idx; ///< the index of the user MBG_USER_STATUS status; ///< status, see ::MBG_USER_STATUS } MBG_USER_STATUS_IDX; @@ -23070,7 +26606,7 @@ typedef struct typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_SERVICE_SETTINGS settings; } MBG_SERVICE_SETTINGS_IDX; @@ -23122,7 +26658,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_SERVICE_INFO info; } MBG_SERVICE_INFO_IDX; @@ -23150,7 +26686,7 @@ typedef struct typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_SERVICE_STATUS status; } MBG_SERVICE_STATUS_IDX; @@ -23178,13 +26714,30 @@ do \ * @{ */ +enum MBG_FW_GLB_FLAGS +{ + MBG_FW_GLB_FLAG_CAN_SET_OSV, ///< OSV is settable/changeable + N_MBG_FW_GLB_FLAGS +}; + + +enum MBG_FW_GLB_MSKS +{ + MBG_FW_GLB_MSK_CAN_SET_OSV = ( 1UL << MBG_FW_GLB_FLAG_CAN_SET_OSV ) ///< See ::MBG_FW_GLB_FLAG_CAN_SET_OSV +}; + + typedef struct { uint8_t max_fws; ///< Maximum installable firmwares uint8_t installed_fws; ///< Currently installed firmwares uint8_t active_fw; ///< Index of currently active firmware uint8_t osv_fw; ///< Index of OSV firmware - uint32_t reserved_1[15]; + + uint8_t reserved_1[2]; + uint16_t flags; ///< See ::MBG_FW_GLB_MSKS + + uint32_t reserved_2[14]; } MBG_FW_GLB_INFO; @@ -23286,7 +26839,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_FW_INFO info; } MBG_FW_INFO_IDX; @@ -23358,7 +26911,7 @@ enum MBG_FW_UFU_FLASH_CMDS /// ::MBG_FW_UFU_FLASH_CMD::model_code must be set. /// Find the newest firmware version for specific devices identified by - /// the firmware's model code and flash that firmware to all suitable devices. + /// the model code of the firmware, and flash that firmware to all suitable devices. MBG_FW_UFU_FLASH_CMD_TYPE, /// Find the newest firmware version for each single device and flash @@ -23369,16 +26922,20 @@ enum MBG_FW_UFU_FLASH_CMDS }; +/** + * @brief Data used with UFU firmware flash command. + * + * @note Please note that, depending on the command, specific members in + * ::MBG_FW_UFU_FLASH_CMD are valid, all others should be zero and be ignored. + */ typedef struct { - /// Please be aware that, depending on the command, specific members in - /// ::MBG_FW_UFU_FLASH_CMD are valid, all others should be zero and be ignored. uint8_t cmd; ///< See ::MBG_FW_UFU_FLASH_CMDS uint8_t reserved_1; ///< Future use uint16_t ufu_idx; ///< See ::MBG_FW_UFU_FLASH_CMD_DEVICE_UFU XBP_ADDR xbp_addr; ///< See ::MBG_FW_UFU_FLASH_CMD_DEVICE_UFU or ///< ::MBG_FW_UFU_FLASH_CMD_DEVICE - uint16_t model_code; ///< see ::MBG_FW_UFU_FLASH_CMD_TYPE + uint16_t model_code; ///< See ::MBG_FW_UFU_FLASH_CMD_TYPE uint16_t reserved_3; ///< Future use uint32_t reserved_4[4]; ///< Future use @@ -23460,21 +27017,22 @@ enum MBG_DATABASE_SETTINGS_FLAG_MSKS typedef struct { - uint16_t flags; ///< See ::MBG_DATABASE_SETTINGS_FLAG_MSKS - uint16_t port; ///< Remote host port + uint16_t flags; ///< See ::MBG_DATABASE_SETTINGS_FLAG_MSKS. + uint16_t port; ///< Remote host port. uint32_t reserved_2[7]; - char user[MBG_DATABASE_MAX_STR]; ///< Database username - char password[MBG_DATABASE_MAX_STR]; ///< Database password - - /// ::MBG_DATABASE_SETTINGS::host can be set to a remote database server - /// (MySQL, PostgreSQL, etc...) or even to a local file path - /// in case of a SQLite database. In case of a local file database - /// ::MBG_DATABASE_INFO_FLAG_MSK_LOCAL_FILE should be set in ::MBG_DATABASE_INFO::flags - /// to announce its path. Thus, a capable piece of software can fetch it via - /// TLV API. + char user[MBG_DATABASE_MAX_STR]; ///< Database username. + char password[MBG_DATABASE_MAX_STR]; ///< Database password. + + /// @brief Database host. + /// + /// Can be set to a remote database server (MySQL, PostgreSQL, etc.) + /// or even to a local file path in case of a SQLite database. + /// In case of a local file database, ::MBG_DATABASE_INFO_FLAG_MSK_LOCAL_FILE + /// should be set in ::MBG_DATABASE_INFO::flags to announce its path, + /// so a capable piece of software can fetch it via the TLV API. char host[MBG_MAX_HOSTNAME_LEN]; - char dbname[MBG_DATABASE_MAX_STR]; ///< Database name + char dbname[MBG_DATABASE_MAX_STR]; ///< Database name. char reserved_3[MBG_DATABASE_MAX_STR]; char reserved_4[MBG_DATABASE_MAX_STR]; @@ -23490,7 +27048,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_DATABASE_SETTINGS settings; } MBG_DATABASE_SETTINGS_IDX; @@ -23513,7 +27071,7 @@ enum MBG_DATABASE_INFO_FLAGS enum MBG_DATABASE_INFO_FLAG_MSKS { - /// See ::MBG_DATABASE_INFO_FLAG_LOCAL_FILE + /// @brief See ::MBG_DATABASE_INFO_FLAG_LOCAL_FILE MBG_DATABASE_INFO_FLAG_MSK_LOCAL_FILE = ( 1UL << MBG_DATABASE_INFO_FLAG_LOCAL_FILE ) }; @@ -23547,18 +27105,20 @@ typedef struct uint8_t type; ///< See ::MBG_DATABASE_TYPES uint8_t flags; ///< See ::MBG_DATABASE_INFO_FLAG_MSKS - /// Flag field which ::MBG_DATABASE_MEMBER_MSKS are valid. + /// @brief Flag field indicating which ::MBG_DATABASE_MEMBER_MSKS are valid. uint16_t supp_members; - /// Flag field which ::MBG_DATABASE_MEMBER_MSKS are configurable. + /// @brief Flag field which ::MBG_DATABASE_MEMBER_MSKS are configurable. + /// /// Subset of ::MBG_DATABASE_INFO::supp_members. - uint16_t supp_cfgs; + /// @brief Supported settings flags. + /// /// If ::MBG_DATABASE_MEMBER_MSK_FLAGS is set in ::MBG_DATABASE_INFO::supp_members /// and ::MBG_DATABASE_MEMBER_MSK_FLAGS is set in ::MBG_DATABASE_INFO::supp_cfgs, /// this is the flag field of supported ::MBG_DATABASE_SETTINGS_FLAG_MSKS in - /// ::MBG_DATABASE_SETTINGS::flags + /// ::MBG_DATABASE_SETTINGS::flags. uint16_t supp_settings_flags; uint32_t reserved_3[2]; @@ -23577,7 +27137,7 @@ do \ typedef struct { - uint32_t idx; + MBG_MSG_IDX_32 idx; MBG_DATABASE_INFO info; } MBG_DATABASE_INFO_IDX; @@ -23620,6 +27180,309 @@ do \ +/** + * @defgroup group_fcu_api FCU API + * + * @note These structures and definitions allow configuration + * and status monitoring of multiple power supplies and fans. + * Only supported if ::MBG_XFEATURE_FCU_API is set. + * The legacy device FCU_01 does ***not*** support this API. + * + * @{ */ + + +/** + * @brief The maximum number of power supply modules supported by the API. + * + * This is limited e.g. by the number of bits available + * in ::MBG_FCU_SETTINGS::installed_power_supplies. + * Existing FCU modules normally only support a much smaller + * number of power supplies. + */ +#define FCU_MAX_PSU_MODULES 16 +// NOTE Changing the numeric value breaks API compatibility. + + +/** + * @brief The maximum number of fan control modules supported by the API. + * + * This is limited e.g. by the number of bits available + * in ::MBG_FCU_SETTINGS::fan_units_to_disable. + * The number of fan modules supported by a particular FCU module + * is usually smaller. + */ +#define FCU_MAX_FAN_MODULES 16 +// NOTE Changing the numeric value breaks API compatibility. + + +/** + * @brief The maximum number of fan control lines per fan module. + * + * This is an arbitrary maximum number. + * Existing FCU modules normally only support a much smaller + * number of fan modules, e.g. 1 or 4, depending on the fan + * module hardware and the FCU model. + */ +#define FCU_MAX_FANS_CTRL_PER_MODULE 8 +// NOTE Changing the numeric value breaks API compatibility. + + + +/** + * @brief Configuration settings to be sent to an FCU module. + */ +typedef struct +{ + /// @brief Bit mask used to tell the FCU module which slot(s) + /// are known to have a power supply module is physically installed. + /// + /// This tells the FCU that power should be available from those slots, + /// and thus affects the status reported for a power supply slot, + /// i.e. "not available" vs. "OK" or "faulty". + uint16_t installed_power_supplies; + + /// @brief Bit mask of fan modules to be ***disabled*** by the FCU. + /// + /// By default, all fan modules are anyway enabled after + /// power-up, so the control program can explicitly disable + /// selected modules later, if preferred for some reason. + uint16_t fan_units_to_disable; + + uint16_t reserved_0; ///< Currently not used, should be set to 0. + uint16_t reserved_1; ///< Currently not used, should be set to 0. + + uint16_t reserved_2; ///< Currently not used, should be set to 0. + uint16_t reserved_3; ///< Currently not used, should be set to 0. + uint16_t reserved_4; ///< Currently not used, should be set to 0. + uint16_t reserved_5; ///< Currently not used, should be set to 0. + +} MBG_FCU_SETTINGS; + +#define _mbg_swab_fcu_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->installed_power_supplies ); \ + _mbg_swab16( &(_p)->fan_units_to_disable ); \ + _mbg_swab16( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab16( &(_p)->reserved_3 ); \ + _mbg_swab16( &(_p)->reserved_4 ); \ + _mbg_swab16( &(_p)->reserved_5 ); \ +} while ( 0 ) + + + +/** + * @brief Info and current settings to be retrieved from an FCU module. + */ +typedef struct +{ + MBG_FCU_SETTINGS fcu_settings; ///< Current settings. + + /// @brief The number of power supply modules that can be + /// monitored by the particular FCU module. + /// + /// Must not exceed ::FCU_MAX_PSU_MODULES. + uint8_t n_psu_modules; + + /// @brief The number of fan modules that can be monitored + /// by the particular FCU module. + /// + /// Must no exceed ::FCU_MAX_FAN_MODULES. + uint8_t n_fan_modules; + + uint8_t reserved_0; ///< Currently not used, reserved. + uint8_t reserved_1; ///< Currently not used, reserved. + + uint32_t reserved_2; ///< Currently not used, reserved. + + /// @brief The number of fan control lines for each fan module. + /// + /// Some module types may have 1 fan with 1 control line, + /// there may be modules with several fans, each of which + /// has its own control line, and finally there may be modules + /// with several fans that share a single summary control line. + /// The FCU firmware can determine and report these values + /// depending on the hardware it is running on. + uint8_t fan_ctrls_per_module[FCU_MAX_FAN_MODULES]; + + uint32_t reserved_3; ///< Currently not used, reserved. + uint32_t reserved_4; ///< Currently not used, reserved. + uint32_t reserved_5; ///< Currently not used, reserved. + uint32_t reserved_6; ///< Currently not used, reserved. + +} MBG_FCU_INFO; + +#define _mbg_swab_fcu_info( _p ) \ +do \ +{ \ + _mbg_swab_fcu_settings( &(_p)->fcu_settings ); \ + _mbg_swab8( &(_p)->n_psu_modules ); \ + _mbg_swab8( &(_p)->n_fan_modules ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab8( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ + _mbg_swab32( &(_p)->reserved_5 ); \ + _mbg_swab32( &(_p)->reserved_6 ); \ +} while ( 0 ) + + + +/** + * @brief Power supply status information to be retrieved from an FCU module. + * + * ::MBG_FCU_INFO::n_psu_modules are supported by the FCU module, + * but how many and which power supply modules are actually + * monitored depends on the bit mask ::MBG_FCU_SETTINGS::installed_power_supplies + * that has been sent to the FCU module. + */ +typedef struct +{ + uint8_t status; ///< The status, see ::FCU_PSU_STAT_CODES. + uint8_t reserved_0; ///< Currently unused, reserved. + uint16_t reserved_1; ///< Currently unused, reserved. + +} MBG_FCU_PSU_STAT; + +#define _mbg_swab_fcu_psu_stat( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->status ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ +} while ( 0 ) + + + +/** + * @brief Power supply status codes used with ::MBG_FCU_PSU_STAT::status. + */ +enum FCU_PSU_STAT_CODES +{ + /// The bit mask in ::MBG_FCU_SETTINGS::installed_power_supplies + /// indicates there is no PSU module expected in this slot, and + /// the associated voltage sense line is low, es expected. + FCU_PSU_STAT_CODE_NOT_AVAIL, + + /// The bit mask in ::MBG_FCU_SETTINGS::installed_power_supplies + /// indicates there is no PSU module expected in this slot, but + /// the associated voltage sense line is anyway high, so obviously + /// a PSU module is installed which has not yet been registered. + FCU_PSU_STAT_CODE_UNREGISTERED, + + /// The bit mask in ::MBG_FCU_SETTINGS::installed_power_supplies + /// indicates there is a PSU module installed in this slot, and + /// the associated voltage sense line is high, so the PSU works + /// properly. + FCU_PSU_STAT_CODE_OK, + + /// The bit mask in ::MBG_FCU_SETTINGS::installed_power_supplies + /// indicates there is a PSU module installed in this slot, but + /// the associated voltage sense line is low, so the PSU is faulty + /// or has been removed. + FCU_PSU_STAT_CODE_FAIL, + + N_FCU_PSU_STAT_CODE ///< The number of known status codes. +}; + + + +/** + * @brief Power supply status information plus module index. + * + * Monitoring software should poll index 0...::MBG_FCU_INFO::n_psu_modules-1. + */ +typedef struct +{ + MBG_MSG_IDX idx; ///< 0...::MBG_FCU_INFO::n_psu_modules-1. + MBG_FCU_PSU_STAT psu_stat; + +} MBG_FCU_PSU_STAT_IDX; + +#define _mbg_swab_fcu_psu_stat_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_fcu_psu_stat( &(_p)->psu_stat ); \ +} while ( 0 ) + + + +/** + * @brief Fan status information to be retrieved from an FCU module. + * + * ::MBG_FCU_INFO::n_fan_modules are supported by the FCU module, + * but how many fan modules with one or more control lines each + * are actually monitored depends on the FCU device and fan hardware. + */ +typedef struct +{ + /// @brief Indicates how many control lines are checked + /// + /// for the specified module, i.e. how many items + /// of @a #status contain relevant status information. + /// Should correspond to ::MBG_FCU_INFO::fan_ctrls_per_module. + uint8_t n_ctrls; + + uint8_t reserved_0; ///< Currently unused, reserved. + uint16_t reserved_1; ///< Currently unused, reserved. + + uint8_t status[FCU_MAX_FANS_CTRL_PER_MODULE]; ///< See ::FCU_FAN_STAT_CODES. + +} MBG_FCU_FAN_STAT; + +#define _mbg_swab_fcu_fan_stat( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->n_ctrls ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ +} while ( 0 ) + + + +/** + * @brief Fan status codes used with ::MBG_FCU_FAN_STAT::status. + */ +enum FCU_FAN_STAT_CODES +{ + FCU_FAN_STAT_CODE_NOT_AVAIL, ///< No fan installed at the control line of this unit. + FCU_FAN_STAT_CODE_DISABLED, ///< Fan installed but disabled. + FCU_FAN_STAT_CODE_OK, ///< Fan installed and working OK. + FCU_FAN_STAT_CODE_TURNED_OFF, ///< Fan turned off by frontpanel switch. + FCU_FAN_STAT_CODE_FAULTY, ///< Fan installed but fails. + N_FCU_FAN_STAT_CODE ///< The number of known status codes. +}; + + + +/** + * @brief Fan status information plus module index. + * + * Monitoring software should poll index 0...::MBG_FCU_INFO::n_fan_modules-1. + */ +typedef struct +{ + MBG_MSG_IDX idx; ///< 0...::MBG_FCU_INFO::n_fan_modules-1. + MBG_FCU_FAN_STAT fan_stat; + +} MBG_FCU_FAN_STAT_IDX; + +#define _mbg_swab_fcu_fan_stat_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_fcu_fan_stat( &(_p)->fan_stat ); \ +} while ( 0 ) + + +/** @} defgroup group_fcu_api */ + + + #if defined( _USING_BYTE_ALIGNMENT ) #pragma pack() // set default alignment #undef _USING_BYTE_ALIGNMENT diff --git a/mbglib/common/irig_cal.h b/mbglib/common/irig_cal.h index efab5d1..f85c688 100644 --- a/mbglib/common/irig_cal.h +++ b/mbglib/common/irig_cal.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: irig_cal.h 1.4 2018/03/21 14:58:06Z martin REL_M $ + * $Id: irig_cal.h 1.5 2021/03/22 17:57:48Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: irig_cal.h $ - * Revision 1.4 2018/03/21 14:58:06Z martin + * Revision 1.5 2021/03/22 17:57:48Z martin + * Updated a bunch of comments. + * Revision 1.4 2018/03/21 14:58:06 martin * Fixed a compiler warning. * Revision 1.3 2015/08/31 09:35:30Z martin * Quieted a compiler warning. @@ -41,7 +43,7 @@ /* Start of header body */ -#if defined( _USE_PACK ) // set byte alignment +#if defined( _USE_PACK ) // Set byte alignment. #pragma pack( 1 ) #define _USING_BYTE_ALIGNMENT #endif @@ -54,9 +56,9 @@ * codes with similar characteristics, e.g. DCLS or modulated, etc. This function * tries to determine the group index for a given IRIG RX code. * - * @param icode_rx A given IRIG RX code index + * @param[in] icode_rx A given IRIG RX code index. * - * @return The group index [0..N_IRIG_RX_COMP-1], or -1 if the group could not be determined + * @return The group index [0..N_IRIG_RX_COMP-1], or -1 if the group could not be determined. */ static __mbg_inline int mbg_icode_rx_to_group_idx( int icode_rx ) @@ -65,7 +67,7 @@ int mbg_icode_rx_to_group_idx( int icode_rx ) if ( icode_mask & MSK_ICODE_RX_DC ) { - // for DCLS codes check the bit rate + // For DCLS codes check the bit rate. if ( icode_mask & MSK_ICODE_RX_100BPS ) return IRIG_RX_COMP_B0; @@ -76,11 +78,11 @@ int mbg_icode_rx_to_group_idx( int icode_rx ) if ( icode_mask & MSK_ICODE_RX_10000BPS ) return IRIG_RX_COMP_G0; - return -1; // unknown DLCS code + return -1; // Unknown DLCS code. } - // for modulated codes check the carrier frequency + // For modulated codes check the carrier frequency. if ( icode_mask & MSK_ICODE_RX_1KHZ ) return IRIG_RX_COMP_B1; @@ -91,7 +93,7 @@ int mbg_icode_rx_to_group_idx( int icode_rx ) if ( icode_mask & MSK_ICODE_RX_100KHZ ) return IRIG_RX_COMP_G1; - return -1; // unknown modulated code + return -1; // Unknown modulated code. } // mbg_icode_rx_to_group_idx @@ -100,15 +102,15 @@ int mbg_icode_rx_to_group_idx( int icode_rx ) /** * @brief Get generic I/O support info for a certain data type. * - * @param dh Valid handle to a Meinberg device - * @param type One of the enumerated generic I/O data types - * @param *p Pointer to a ::GEN_IO_INFO variable to be filled up + * @param[in] dh Valid handle to a Meinberg device. + * @param[in] type One of the enumerated generic I/O data types. + * @param[out] p Pointer to a ::GEN_IO_INFO variable to be filled up. * * @return ::MBG_SUCCESS or error code returned by device I/O control function. * - * @see mbg_get_cal_rec_irig_rx_num_rec() - * @see mbg_get_cal_rec_irig_rx_comp() - * @see mbg_set_cal_rec_irig_rx_comp() + * @see ::mbg_get_cal_rec_irig_rx_num_rec + * @see ::mbg_get_cal_rec_irig_rx_comp + * @see ::mbg_set_cal_rec_irig_rx_comp */ static __mbg_inline int mbg_get_gen_io_info( MBG_DEV_HANDLE dh, GEN_IO_INFO_TYPE type, GEN_IO_INFO *p ) @@ -131,14 +133,14 @@ int mbg_get_gen_io_info( MBG_DEV_HANDLE dh, GEN_IO_INFO_TYPE type, GEN_IO_INFO * /** * @brief Get supported number of IRIG RX calibration records. * - * @param dh Valid handle to a Meinberg device - * @param p_num_rec Pointer to an int to be filled up + * @param[in] dh Valid handle to a Meinberg device. + * @param[out] p_num_rec Pointer to an @a int to be filled up. * * @return ::MBG_SUCCESS or error code returned by device I/O control function. * - * @see mbg_get_gen_io_info() - * @see mbg_get_cal_rec_irig_rx_comp() - * @see mbg_set_cal_rec_irig_rx_comp() + * @see ::mbg_get_gen_io_info + * @see ::mbg_get_cal_rec_irig_rx_comp + * @see ::mbg_set_cal_rec_irig_rx_comp */ static __mbg_inline int mbg_get_cal_rec_irig_rx_num_rec( MBG_DEV_HANDLE dh, int *p_num_rec ) @@ -161,15 +163,15 @@ int mbg_get_cal_rec_irig_rx_num_rec( MBG_DEV_HANDLE dh, int *p_num_rec ) /** * @brief Retrieve IRIG RX calibration record with specific index. * - * @param dh Valid handle to a Meinberg device - * @param idx index of the calibration record to be retrieved - * @param *p Pointer to a ::CAL_REC_IRIG_RX_COMP variable to be filled up + * @param[in] dh Valid handle to a Meinberg device. + * @param[in] idx Index of the calibration record to be retrieved. + * @param[out] p Pointer to a ::CAL_REC_IRIG_RX_COMP variable to be filled up. * * @return ::MBG_SUCCESS or error code returned by device I/O control function. * - * @see mbg_get_gen_io_info() - * @see mbg_get_cal_rec_irig_rx_num_rec() - * @see mbg_set_cal_rec_irig_rx_comp() + * @see ::mbg_get_gen_io_info + * @see ::mbg_get_cal_rec_irig_rx_num_rec + * @see ::mbg_set_cal_rec_irig_rx_comp */ static __mbg_inline int mbg_get_cal_rec_irig_rx_comp( MBG_DEV_HANDLE dh, uint16_t idx, CAL_REC_IRIG_RX_COMP *p ) @@ -197,14 +199,14 @@ int mbg_get_cal_rec_irig_rx_comp( MBG_DEV_HANDLE dh, uint16_t idx, CAL_REC_IRIG_ /** * @brief Write an IRIG RX calibration record to a device. * - * @param dh Valid handle to a Meinberg device - * @param *p Pointer to a ::CAL_REC_IRIG_RX_COMP variable to be written + * @param[in] dh Valid handle to a Meinberg device. + * @param[in] p Pointer to a ::CAL_REC_IRIG_RX_COMP variable to be written. * * @return ::MBG_SUCCESS or error code returned by device I/O control function. * - * @see mbg_get_gen_io_info() - * @see mbg_get_cal_rec_irig_rx_num_rec() - * @see mbg_get_cal_rec_irig_rx_comp() + * @see ::mbg_get_gen_io_info + * @see ::mbg_get_cal_rec_irig_rx_num_rec + * @see ::mbg_get_cal_rec_irig_rx_comp */ static __mbg_inline int mbg_set_cal_rec_irig_rx_comp( MBG_DEV_HANDLE dh, const CAL_REC_IRIG_RX_COMP *p ) @@ -244,7 +246,7 @@ extern "C" { #endif #if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment + #pragma pack() // Set default alignment. #undef _USING_BYTE_ALIGNMENT #endif diff --git a/mbglib/common/lan_util.c b/mbglib/common/lan_util.c index bd197a7..b31951e 100644 --- a/mbglib/common/lan_util.c +++ b/mbglib/common/lan_util.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: lan_util.c 1.16 2018/04/06 14:58:54Z martin REL_M $ + * $Id: lan_util.c 1.23 2021/07/20 10:27:30Z daniel TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,22 @@ * * ----------------------------------------------------------------------- * $Log: lan_util.c $ - * Revision 1.16 2018/04/06 14:58:54Z martin + * Revision 1.23 2021/07/20 10:27:30Z daniel + * On SOC platforms use alternative method via proc interface to retrieve current IP address of the IPv4 default gateway. + * Revision 1.22 2021/05/18 14:13:48 daniel + * Fixed NUM_WORDS bug again + * Revision 1.21 2021/05/17 13:23:22 daniel + * Fixed bug in definition of NUM_WORDS in snprint_ip6_addr + * Revision 1.20 2021/05/11 10:57:00 udo + * Include get_ip4_gateway() from build if USE_MBG_TSU is defined. + * Revision 1.19 2021/03/22 18:07:30 martin + * Updated a bunch of comments. + * Revision 1.18 2019/11/21 13:36:39 martin + * Use more portable code. + * Avoid unnecessary type casts. + * Revision 1.17 2019/03/21 08:50:27 thomas-b + * Resolved compiler warnings + * Revision 1.16 2018/04/06 14:58:54 martin * Fixed ethtool support for older kernels / build environments. * Revision 1.15 2018/02/28 16:56:39 martin * Make parameters speed and duplex of check_port_status() optional. @@ -114,7 +129,7 @@ #else - // dummy codes, the functions will report an error ... + // Dummy codes, the functions will report an error ... #define SIOCGIFADDR 0 #define SIOCGIFNETMASK 0 #define SIOCGIFBRDADDR 0 @@ -136,20 +151,25 @@ #if DEBUG_NETLINK - // we need a function to output debugging information + // FIXME We need a function to output debugging information. + // Maybe this can be implemented via a function pointer + // that defaults to a wellknown function. #if !defined STANDALONE - #include <ptp2_cnf.h> // for mbglog() from the ARM PTP projects + #include <ptp2_cnf.h> // TODO For mbglog() from the ARM PTP projects #else - // to be provided by the application + // To be provided by the application extern __attribute__( ( format( printf, 2, 3 ) ) ) void mbglog( int priority, const char *fmt, ... ); #endif #endif // DEBUG_NETLINK -// Maximum size of an IPv4 address string in dotted quad format, -// including a terminating 0, and thus the required minimum size -// for a buffer to take such a string. i.e. "aaa.bbb.ccc.ddd\0". +/** + * @brief Maximum size of an IPv4 address string in dotted quad format. + * + * Includes a terminating 0, so the required minimum size + * for a buffer to take such a string. i.e. "aaa.bbb.ccc.ddd\0". + */ #define MAX_IP4_ADDR_STR_SIZE 16 @@ -169,14 +189,14 @@ struct route_info /*HDR*/ /** - * @brief Count the number of sequential bits in an IPv4 net mask + * @brief Count the number of sequential bits in an IPv4 net mask. * - * Counting starts from MSB, i.e. for 0xC0 and 0xC1 the results + * Counting starts from MSB, i.e. for 0xC0 and 0xC1 the results. * are both 2 since only the 2 MSBs are sequentially set. * - * @param[in] p_mask The IPv4 net mask to be evaluated + * @param[in] p_mask The IPv4 net mask to be evaluated. * - * @return The number of sequential MSB bits set in *p_mask + * @return The number of sequential MSB bits set in @p *p_mask. * * @see ::ip4_net_mask_from_cidr */ @@ -201,14 +221,15 @@ int get_ip4_net_mask_bits( const IP4_ADDR *p_mask ) /*HDR*/ /** - * @brief Print an IPv4 address to a dotted quad formatted string + * @brief Print an IPv4 address to a dotted quad formatted string. * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] p_addr The IPv4 address to be evaluated - * @param[in] info An optional string which is prepended to the string, or NULL + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] p_addr The IPv4 address to be evaluated. + * @param[in] info An optional string which is prepended to the string, or @a NULL. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_ip4_cidr_addr * @see ::str_to_ip4_addr @@ -222,7 +243,7 @@ size_t snprint_ip4_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, const if ( info ) n += snprintf_safe( s, max_len, "%s", info ); - // Don't use byte pointers here since this is not safe + // Don't use byte pointers here because this is not safe // for both little and big endian targets. n += snprintf_safe( &s[n], max_len - n, "%u.%u.%u.%u", BYTE_3( ul ), BYTE_2( ul ), @@ -236,17 +257,18 @@ size_t snprint_ip4_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, const /*HDR*/ /** - * @brief Print an IPv4 address plus net mask in CIDR notation to a string + * @brief Print an IPv4 address plus net mask in CIDR notation to a string. * * The printed CIDR string is something like "172.16.3.250/24" * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] p_addr The IPv4 address to be evaluated - * @param[in] p_mask The associated IPv4 net mask - * @param[in] info An optional string which is prepended to the string, or NULL + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] p_addr The IPv4 address to be evaluated. + * @param[in] p_mask The associated IPv4 net mask. + * @param[in] info An optional string which is prepended to the string, or @a NULL. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_ip4_addr * @see ::str_to_ip4_addr @@ -272,13 +294,13 @@ size_t snprint_ip4_cidr_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, /*HDR*/ /** - * @brief Convert a string to an ::IP4_ADDR + * @brief Convert a string to an ::IP4_ADDR. * - * If output parameter is specified as NULL then this function - * can be used to check if the IPv4 address string is formally correct. + * If the output parameter is specified as @a NULL, this function can be used + * to check if the IPv4 address string is formally correct. * - * @param[out] p_addr Pointer to an ::IP4_ADDR variable to be filled, or NULL - * @param[in] s An IPv4 address string to be converted + * @param[out] p_addr Pointer to an ::IP4_ADDR variable to be filled, or @a NULL. + * @param[in] s An IPv4 address string to be converted. * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, @@ -300,25 +322,25 @@ int str_to_ip4_addr( IP4_ADDR *p_addr, const char *s ) { unsigned long ul = strtoul( (char *) cp, (char **) &cp, 10 ); - if ( ul > 0xFFUL ) // invalid number + if ( ul > 0xFFUL ) // Invalid number. return MBG_ERR_PARM_FMT; tmp_ip4_addr |= ul << ( 8 * (3 - i) ); if ( ++i >= 4 ) - break; // done + break; // Done. if ( *cp != '.' ) - return MBG_ERR_PARM_FMT; // invalid string format, dot expected + return MBG_ERR_PARM_FMT; // Invalid string format, dot expected. - cp++; // skip dot + cp++; // Skip dot. } } if ( p_addr ) *p_addr = tmp_ip4_addr; - // success: return the number of evaluated chars + // Success: return the number of evaluated chars. return (int) ( cp - s ); } // str_to_ip4_addr @@ -327,16 +349,16 @@ int str_to_ip4_addr( IP4_ADDR *p_addr, const char *s ) /*HDR*/ /** - * @brief Convert a string in CIDR notation to an ::IP4_ADDR and net mask + * @brief Convert a string in CIDR notation to an ::IP4_ADDR and net mask. * - * If output parameters are specified as NULL then this function + * If the output parameters are specified as @a NULL, this function * can be used to check if the CIDR string is formally correct. * * @param[out] p_addr Pointer to an ::IP4_ADDR variable to be filled with - * the IPv4 address, or NULL + * the IPv4 address, or @a NULL. * @param[out] p_mask Pointer to an ::IP4_ADDR variable to be filled with - * the IPv4 net mask, or NULL - * @param[in] cidr_str The string to be converted, in CIDR format, e.g. "172.16.3.250/24" + * the IPv4 net mask, or @a NULL. + * @param[in] cidr_str The string to be converted, in CIDR format, e.g. "172.16.3.250/24". * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, @@ -361,13 +383,13 @@ int cidr_str_to_ip4_addr_and_net_mask( IP4_ADDR *p_addr, IP4_ADDR *p_mask, l = (int) strlen( cidr_str ); - if ( l < rc ) // input string too short + if ( l < rc ) // Input string too short. return MBG_ERR_PARM_FMT; cp = &cidr_str[rc]; - if ( *cp == 0 ) // end of string + if ( *cp == 0 ) // End of string. { // The string has no CIDR extension, so // assume "/0", i.e. host mask 0.0.0.0; @@ -394,7 +416,7 @@ done: if ( p_mask ) *p_mask = mask; - // success: return the number of evaluated chars + // Success: return the number of evaluated chars. return (int) ( cp - cidr_str ); } // cidr_str_to_ip4_addr_and_net_mask @@ -403,14 +425,14 @@ done: /*HDR*/ /** - * @brief Count the number of sequential bits in an IPv6 net mask + * @brief Count the number of sequential bits in an IPv6 net mask. * * Counting starts from MSB, i.e. for 0xC0 and 0xC1 the results * are both 2 since only the 2 MSBs are sequentially set. * - * @param[in] p_mask The IPv6 net mask to be evaluated + * @param[in] p_mask The IPv6 net mask to be evaluated. * - * @return The number of sequential MSB bits set in *p_mask + * @return The number of sequential MSB bits set in @p *p_mask. * * @see ::ip6_net_mask_from_cidr */ @@ -445,14 +467,15 @@ int get_ip6_net_mask_bits( const IP6_ADDR *p_mask ) /*HDR*/ /** - * @brief Print an IPv6 address in optimized format to a string + * @brief Print an IPv6 address in optimized format to a string. * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] p_addr The IPv6 address to be evaluated - * @param[in] info An optional string which is prepended to the string, or NULL + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] p_addr The IPv6 address to be evaluated. + * @param[in] info An optional string which is prepended to the string, or @a NULL. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_ip6_cidr_addr * @see ::snprint_ip6_cidr_mask_addr @@ -462,11 +485,11 @@ int get_ip6_net_mask_bits( const IP6_ADDR *p_mask ) */ size_t snprint_ip6_addr( char *s, size_t max_len, const IP6_ADDR *p_addr, const char *info ) { - // Copied from inet_ntop.c, and reversed byte order + // Copied from inet_ntop.c, and reversed byte order. IP6_ADDR_STR tmp; char *tp; - #define NUM_WORDS ( (int) ( sizeof( IP6_ADDR_STR ) / sizeof( uint16_t ) ) ) + #define NUM_WORDS ( (int) ( IP6_ADDR_BYTES / sizeof( uint16_t ) ) ) uint16_t words[NUM_WORDS] = { 0 }; int i; size_t n = 0; @@ -523,7 +546,7 @@ size_t snprint_ip6_addr( char *s, size_t max_len, const IP6_ADDR *p_addr, const for ( i = 0; i < NUM_WORDS; i++ ) { - /* Are we inside the best run of 0x00's? */ + // Are we inside the best run of 0x00's? if ( best.base != -1 && i >= best.base && i < ( best.base + best.len ) ) { if (i == best.base) @@ -532,19 +555,19 @@ size_t snprint_ip6_addr( char *s, size_t max_len, const IP6_ADDR *p_addr, const continue; } - /* Are we following an initial run of 0x00s or any real hex? */ + // Are we following an initial run of 0x00s or any real hex? if ( i != 0 ) *tp++ = ':'; - /* Is this address an encapsulated IPv4? */ + // Is this address an encapsulated IPv4? if ( i == 6 && best.base == 0 && ( best.len == 6 || ( best.len == 5 && words[5] == 0xffff ) ) ) - return MBG_ERR_INV_PARM; // we don't support encapsulated IPv4 + return MBG_ERR_INV_PARM; // We don't support encapsulated IPv4. sprintf( tp, "%x", words[i] ); tp += strlen( tp ); } - /* Was it a trailing run of 0x00's? */ + // Was it a trailing run of 0x00's? if ( best.base != -1 && ( best.base + best.len ) == NUM_WORDS ) *tp++ = ':'; @@ -571,17 +594,18 @@ size_t snprint_ip6_addr( char *s, size_t max_len, const IP6_ADDR *p_addr, const /*HDR*/ /** - * @brief Print an IPv6 address plus net mask to string in CIDR notation + * @brief Print an IPv6 address plus net mask to string in CIDR notation. * - * The printed CIDR string is something like "2001:0DB8:0:CD30:EF45::/64" + * The printed CIDR string is something like "2001:0DB8:0:CD30:EF45::/64". * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] p_addr The IPv6 address to be evaluated - * @param[in] p_mask The associated IPv6 net mask - * @param[in] info An optional string which is prepended to the string, or NULL + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] p_addr The IPv6 address to be evaluated. + * @param[in] p_mask The associated IPv6 net mask. + * @param[in] info An optional string which is prepended to the string, or @a NULL. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_ip6_addr * @see ::snprint_ip6_cidr_mask_addr @@ -608,17 +632,18 @@ size_t snprint_ip6_cidr_addr( char *s, size_t max_len, const IP6_ADDR *p_addr, /*HDR*/ /** - * @brief Print an IPv6 address plus number of net mask bits to string in CIDR notation + * @brief Print an IPv6 address plus number of net mask bits to string in CIDR notation. * - * The printed CIDR string is something like "2001:0DB8:0:CD30:EF45::/64" + * The printed CIDR string is something like "2001:0DB8:0:CD30:EF45::/64". * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] p_addr The IPv6 address to be evaluated - * @param[in] cidr_mask_bits The CIDR number of bits specifying the IPv6 net mask - * @param[in] info An optional string which is prepended to the string, or NULL + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] p_addr The IPv6 address to be evaluated. + * @param[in] cidr_mask_bits The CIDR number of bits specifying the IPv6 net mask. + * @param[in] info An optional string which is prepended to the string, or @a NULL. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_ip6_addr * @see ::snprint_ip6_cidr_addr @@ -648,16 +673,16 @@ size_t snprint_ip6_cidr_mask_addr( char *s, size_t max_len, const IP6_ADDR *p_ad /*HDR*/ /** - * @brief Convert a string to an ::IP6_ADDR + * @brief Convert a string to an ::IP6_ADDR. * - * If the output parameter is specified as NULL then this function + * If the output parameter is specified as @a NULL, this function * can be used to check if the string is formally correct. * * On success ::IP6_ADDR variable contains the IPv6 address * in little endian byte order. * - * @param[out] p_addr Pointer to the ::IP6_ADDR variable, or NULL - * @param[in] s A string containing an IPv6 address + * @param[out] p_addr Pointer to the ::IP6_ADDR variable, or @a NULL. + * @param[in] s A string containing an IPv6 address. * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, @@ -672,7 +697,7 @@ size_t snprint_ip6_cidr_mask_addr( char *s, size_t max_len, const IP6_ADDR *p_ad */ int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) { - // copied from inet_pton.c and reversed byte order + // Copied from inet_pton.c, and reversed byte order. IP6_ADDR tmp = { { 0 } }; static const char xdigits[] = "0123456789abcdef"; uint8_t *tp; @@ -684,14 +709,14 @@ int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) unsigned int val; if ( p_addr ) - memset( p_addr, 0, sizeof( *p_addr ) ); // set IP address to :: + memset( p_addr, 0, sizeof( *p_addr ) ); // Set IP address to '::'. startp = tmp.b - 1; tp = startp + sizeof( tmp ); colonp = NULL; - /* Leading :: requires some special handling. */ + // Leading '::' requires some special handling. if ( *s == ':' ) { read_cnt++; @@ -716,7 +741,7 @@ int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) val <<= 4; val |= ( pch - xdigits ); - if ( val > 0xffff ) //### TODO signed? unsigned? + if ( val > 0xffff ) // TODO Signed? unsigned? return MBG_ERR_PARM_FMT; saw_xdigit = 1; @@ -748,7 +773,7 @@ int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) continue; } - if ( ch == '/' ) // cidr notation. we reached the end + if ( ch == '/' ) // CIDR notation. We reached the end. { read_cnt--; break; @@ -801,16 +826,16 @@ int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) /*HDR*/ /** - * @brief Convert a string in CIDR notation to an ::IP6_ADDR and net mask + * @brief Convert a string in CIDR notation to an ::IP6_ADDR and net mask. * - * If output parameters are specified as NULL then this function + * If the output parameters are specified as @a NULL, this function * can be used to check if the CIDR string is formally correct. * * @param[out] p_addr Pointer to an ::IP6_ADDR variable to be filled up - * with the IPv6 address, or NULL + * with the IPv6 address, or @a NULL. * @param[out] p_mask Pointer to an ::IP6_ADDR variable to be filled up - with the net mask bits, or NULL - * @param[in] cidr_str The string to be converted, in CIDR format, e.g. "2001:0DB8:0:CD30::/64" + with the net mask bits, or @a NULL. + * @param[in] cidr_str The string to be converted, in CIDR format, e.g. "2001:0DB8:0:CD30::/64". * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, @@ -839,14 +864,14 @@ int cidr_str_to_ip6_addr_and_net_mask( IP6_ADDR *p_addr, IP6_ADDR *p_mask, const /*HDR*/ /** - * @brief Convert a string in CIDR notation to an ::IP6_ADDR and net mask bits + * @brief Convert a string in CIDR notation to an ::IP6_ADDR and net mask bits. * - * If output parameters are specified as NULL then this function + * If the output parameters are specified as @a NULL, this function * can be used to check if the CIDR string is formally correct. * - * @param[out] p_addr Pointer to an ::IP6_ADDR variable for the IPv6 address, or NULL - * @param[out] p_cidr Pointer to an int variable for the net mask bits, or NULL - * @param[in] cidr_str The string to be converted, in CIDR format, e.g. "2001:0DB8:0:CD30::/64" + * @param[out] p_addr Pointer to an ::IP6_ADDR variable for the IPv6 address, or @a NULL. + * @param[out] p_cidr Pointer to an int variable for the net mask bits, or @a NULL. + * @param[in] cidr_str The string to be converted, in CIDR format, e.g. "2001:0DB8:0:CD30::/64". * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, @@ -869,12 +894,12 @@ int cidr_str_to_ip6_addr_and_cidr_bits( IP6_ADDR *p_addr, int *p_cidr, l = strlen( cidr_str ); - if ( l < rc ) // input string too short + if ( l < rc ) // Input string too short. return MBG_ERR_PARM_FMT; cp = &cidr_str[rc]; - if ( *cp == 0 ) // end of string + if ( *cp == 0 ) // End of string. { // The string has no CIDR extension, so // assume "/0", i.e. host mask :: @@ -896,7 +921,7 @@ done: if ( p_cidr ) *p_cidr = (int) cidr_mask_bits; - // success: return the number of evaluated chars + // Success: return the number of evaluated chars. return (int) ( cp - cidr_str ); } // cidr_str_to_ip6_addr_and_cidr_bits @@ -905,13 +930,13 @@ done: /*HDR*/ /** - * @brief Compute an IPv6 net mask according to the number of CIDR netmask bits + * @brief Compute an IPv6 net mask according to the number of CIDR netmask bits. * * E.g. the 64 bits mentioned in "2001:0DB8:0:CD30::/64" result in 2^64, * corresponding to FFFF:FFFF:FFFF:FFFF:: in IPv6 notation. * - * @param[out] p_mask Pointer to an ::IP6_ADDR variable for the IPv6 netmask - * @param[in] netmask_bits Number of netmask bits from CIDR notation + * @param[out] p_mask Pointer to an ::IP6_ADDR variable for the IPv6 netmask. + * @param[in] netmask_bits Number of netmask bits from CIDR notation. * * @see ::get_ip6_net_mask_bits */ @@ -950,13 +975,13 @@ void ip6_net_mask_from_cidr( IP6_ADDR *p_mask, int netmask_bits ) /*HDR*/ /** - * @brief Determine the network part of an IPv6 address based on the net mask + * @brief Determine the network part of an IPv6 address based on the net mask. * * E.g. IP "2001:0DB8:0:CD30::", net mask "FFFF:FFFF::" yields network part "2001:0DB8::". * - * @param[out] p_net_part The extracted network part of the IPv6 address - * @param[in] p_addr The IPv6 address to be evaluated - * @param[in] p_mask The associated IPv6 net mask + * @param[out] p_net_part The extracted network part of the IPv6 address. + * @param[in] p_addr The IPv6 address to be evaluated. + * @param[in] p_mask The associated IPv6 net mask. */ void ip6_net_part_from_addr( IP6_ADDR *p_net_part, const IP6_ADDR *p_addr, const IP6_ADDR *p_mask ) @@ -972,16 +997,17 @@ void ip6_net_part_from_addr( IP6_ADDR *p_net_part, const IP6_ADDR *p_addr, /*HDR*/ /** - * @brief Print a MAC ID or similar array of octets to a string + * @brief Print a MAC ID or similar array of octets to a string. * - * @param[out] s The string buffer to be filled - * @param[in] max_len Maximum length of the string, i.e. size of the buffer - * @param[in] octets An array of octets - * @param[in] num_octets The number of octets to be printed from the array - * @param[in] sep The separator printed between the bytes, or 0 - * @param[in] info An optional string which is prepended to the output, or NULL + * @param[out] s The string buffer to be filled. + * @param[in] max_len Maximum length of the string, i.e. size of the buffer. + * @param[in] octets An array of octets. + * @param[in] num_octets The number of octets to be printed from the array. + * @param[in] sep The separator printed between the bytes, or 0. + * @param[in] info An optional string which is prepended to the output, or @a NULL. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_mac_addr * @see ::str_to_octets @@ -1012,15 +1038,16 @@ size_t snprint_octets( char *s, size_t max_len, const uint8_t *octets, /*HDR*/ /** - * @brief Print a ::PTP_CLOCK_ID to a string + * @brief Print a ::PTP_CLOCK_ID to a string. * - * @todo Eventually this function should be moved to a different module. + * @todo Maybe this function should be moved to a different module. * - * @param[out] s The string buffer to be filled - * @param[in] max_len Maximum length of the string, i.e. size of the buffer - * @param[in] p The ::PTP_CLOCK_ID to be printed + * @param[out] s The string buffer to be filled. + * @param[in] max_len Maximum length of the string, i.e. size of the buffer. + * @param[in] p The ::PTP_CLOCK_ID to be printed. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_octets */ @@ -1034,13 +1061,14 @@ size_t snprint_ptp_clock_id( char *s, size_t max_len, const PTP_CLOCK_ID *p ) /*HDR*/ /** - * @brief Print a MAC address to a string + * @brief Print a MAC address to a string. * - * @param[out] s The string buffer to be filled - * @param[in] max_len Maximum length of the string, i.e. size of the buffer - * @param[in] p_mac_addr The MAC address to be printed + * @param[out] s The string buffer to be filled. + * @param[in] max_len Maximum length of the string, i.e. size of the buffer. + * @param[in] p_mac_addr The MAC address to be printed. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_octets * @see ::str_to_octets @@ -1056,13 +1084,13 @@ size_t snprint_mac_addr( char *s, size_t max_len, const MBG_MAC_ADDR *p_mac_addr /*HDR*/ /** - * @brief Set a MAC ID or a similar array of octets from a string + * @brief Set a MAC ID or a similar array of octets from a string. * - * @param[out] octets An array of octets to be set up - * @param[in] num_octets The number of octets which can be stored - * @param[in] s The string to be converted + * @param[out] octets An array of octets to be set up. + * @param[in] num_octets The number of octets that can be stored. + * @param[in] s The string to be converted. * - * @return The overall number of octets decoded from the string + * @return The overall number of octets decoded from the string. * * @see ::snprint_octets * @see ::snprint_mac_addr @@ -1073,17 +1101,17 @@ int str_to_octets( uint8_t *octets, int num_octets, const char *s ) char *cp = (char *) s; int i; - // don't use strtok() since that functions modifies the original string + // Don't use strtok() because that functions modifies the original string. for ( i = 0; i < num_octets; ) { octets[i] = (uint8_t) strtoul( cp, &cp, 16 ); i++; if ( *cp == 0 ) - break; // end of string + break; // End of string. if ( ( *cp != MAC_SEP_CHAR ) && ( *cp != MAC_SEP_CHAR_ALT ) ) - break; // invalid character + break; // Invalid character. cp++; } @@ -1096,12 +1124,12 @@ int str_to_octets( uint8_t *octets, int num_octets, const char *s ) /*HDR*/ /** - * @brief Check if an array of octets is all zero + * @brief Check if an array of octets is all zero. * - * @param[in] octets Pointer to the array of octets - * @param[in] num_octets Number of octets + * @param[in] octets Pointer to the array of octets. + * @param[in] num_octets Number of octets. * - * @return true if all bytes are 0, else false + * @return @a true if all bytes are 0, else @a false. * * @see ::snprint_octets * @see ::snprint_mac_addr @@ -1111,12 +1139,12 @@ bool octets_are_all_zero( const uint8_t *octets, int num_octets ) { int i; - // check if any of the bytes is != 0 + // Check if any of the bytes is != 0. for ( i = 0; i < num_octets; i++ ) if ( octets[i] != 0 ) break; - return i == num_octets; // true if *all* bytes are 0 + return i == num_octets; // True if *all* bytes are 0. } // octets_are_all_zero @@ -1124,11 +1152,11 @@ bool octets_are_all_zero( const uint8_t *octets, int num_octets ) /*HDR*/ /** - * @brief Check if a MAC address is all zero + * @brief Check if a MAC address is all zero. * - * @param[in] p_addr Pointer to a MAC address to be checked + * @param[in] p_addr Pointer to a MAC address to be checked. * - * @return true if all bytes of the MAC address are 0, else false + * @return @a true if all bytes of the MAC address are 0, else @a false. * * @see ::octets_are_all_zero */ @@ -1144,13 +1172,13 @@ bool mac_addr_is_all_zero( const MBG_MAC_ADDR *p_addr ) /*HDR*/ /** - * @brief Do a SIOCGxxx IOCTL call to read specific information from a LAN interface + * @brief Do a SIOCGxxx IOCTL call to read specific information from a LAN interface. * - * @param[in] if_name Name of the interface - * @param[in] ioctl_code One of the predefined system SIOCGxxx IOCTL codes + * @param[in] if_name Name of the interface. + * @param[in] ioctl_code One of the predefined system SIOCGxxx IOCTL codes. * @param[out] p_ifreq Pointer to a request buffer * - * @return One of the @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ int do_siocg_ioctl( const char *if_name, int ioctl_code, struct ifreq *p_ifreq ) { @@ -1160,16 +1188,16 @@ int do_siocg_ioctl( const char *if_name, int ioctl_code, struct ifreq *p_ifreq ) if ( strlen( if_name ) > ( IFNAMSIZ - 1 ) ) return MBG_ERR_PARM_FMT; - sock_fd = socket( AF_INET, SOCK_DGRAM, 0 ); //### TODO: or AF_INET6/PF_INET6 for IPv6 + sock_fd = socket( AF_INET, SOCK_DGRAM, 0 ); // TODO Or AF_INET6/PF_INET6 for IPv6. - if ( sock_fd == -1 ) // failed to open socket + if ( sock_fd == MBG_INVALID_SOCK_FD ) // Failed to open socket. return mbg_get_last_socket_error( "failed to open socket in do_siocg_ioctl" ); strncpy_safe( p_ifreq->ifr_name, if_name, sizeof( p_ifreq->ifr_name ) ); rc = ioctl( sock_fd, ioctl_code, p_ifreq ); - if ( rc == -1 ) // ioctl failed, errno has been set appropriately + if ( rc == -1 ) // IOCTL failed, errno has been set appropriately. rc = mbg_get_last_socket_error( "ioctl failed in do_siocg_ioctl" ); else rc = MBG_SUCCESS; @@ -1186,13 +1214,13 @@ int do_siocg_ioctl( const char *if_name, int ioctl_code, struct ifreq *p_ifreq ) /*HDR*/ /** - * @brief Retrieve the index of a specific network interface + * @brief Retrieve the index of a specific network interface. * - * @param[in] if_name Name of the interface - * @param[out] p_intf_idx Pointer to a variable to be filled up + * @param[in] if_name Name of the interface. + * @param[out] p_intf_idx Pointer to a variable to be filled up. * - * @return One of the @ref MBG_RETURN_CODES. - * On error, *p_intf_idx is set to -1. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, @p *p_intf_idx is set to -1. */ int get_port_intf_idx( const char *if_name, int *p_intf_idx ) { @@ -1210,7 +1238,7 @@ int get_port_intf_idx( const char *if_name, int *p_intf_idx ) } #endif - // we get here on error only + // We only get here on error. *p_intf_idx = -1; return rc; @@ -1221,13 +1249,13 @@ int get_port_intf_idx( const char *if_name, int *p_intf_idx ) /*HDR*/ /** - * @brief Retrieve the MAC address of a network interface + * @brief Retrieve the MAC address of a network interface. * - * @param[in] if_name Name of the interface - * @param[out] p_mac_addr Pointer to the MAC address buffer to be filled up + * @param[in] if_name Name of the interface. + * @param[out] p_mac_addr Pointer to the MAC address buffer to be filled up. * - * @return One of the @ref MBG_RETURN_CODES - * On error, the MAC address is set to all 0 + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, the MAC address @p *p_mac_addr is set to all 0. */ int get_port_mac_addr( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) { @@ -1245,7 +1273,7 @@ int get_port_mac_addr( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) } #endif - // we get here on error only + // We only get here on error. memset( p_mac_addr, 0, sizeof( *p_mac_addr ) ); return rc; @@ -1256,13 +1284,13 @@ int get_port_mac_addr( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) /*HDR*/ /** - * @brief Check the link state of a network interface + * @brief Check the link state of a network interface. * - * @param[in] if_name Name of the interface + * @param[in] if_name Name of the interface. * - * @return 1 if link detected on port, - * 0 if no link detected on port, - * one of the @ref MBG_ERROR_CODES in case of an error + * @return 1 if link detected on port,<br> + * 0 if no link detected on port,<br> + * one of the (negative) @ref MBG_ERROR_CODES in case of an error. */ int check_port_link( const char *if_name ) { @@ -1272,7 +1300,7 @@ int check_port_link( const char *if_name ) struct ifreq ifr = { { { 0 } } }; struct ethtool_value edata = { 0 }; - edata.cmd = ETHTOOL_GLINK; // defined in ethtool.h + edata.cmd = ETHTOOL_GLINK; // Defined in ethtool.h. ifr.ifr_data = (caddr_t) &edata; rc = do_siocg_ioctl( if_name, SIOCETHTOOL, &ifr ); @@ -1289,15 +1317,16 @@ int check_port_link( const char *if_name ) /*HDR*/ /** - * @brief Check the state of a network interface + * @brief Check the state of a network interface. * - * @param[in] if_name Name of the interface to check - * @param[out] p_speed Optional pointer to a variable to take up the link speed, may be NULL - * @param[out] p_duplex Optional pointer to a variable to take up the duplex state, may be NULL + * @param[in] if_name Name of the interface to check. + * @param[out] p_speed Optional pointer to a variable to take up the link speed, may be @a NULL. + * @param[out] p_duplex Optional pointer to a variable to take up the duplex state, may be @a NULL. * - * @return 1 if link detected on port, - * 0 if no link detected on port, - * one of the @ref MBG_ERROR_CODES in case of an error + * @return 1 if link detected on port,<br> + * 0 if no link detected on port,<br> + * one of the (negative) @ref MBG_ERROR_CODES in case of an error. + * In case of error, @p *p_duplex is set to -1. */ int check_port_status( const char *if_name, int *p_speed, int *p_duplex ) { @@ -1308,7 +1337,7 @@ int check_port_status( const char *if_name, int *p_speed, int *p_duplex ) struct ethtool_cmd cmd = { 0 }; int ok; - ifr.ifr_data = (void *) &cmd; + ifr.ifr_data = (caddr_t) &cmd; cmd.cmd = ETHTOOL_GSET; // "Get settings" rc = do_siocg_ioctl( if_name, SIOCETHTOOL, &ifr ); @@ -1341,14 +1370,14 @@ int check_port_status( const char *if_name, int *p_speed, int *p_duplex ) static /*HDR*/ /** - * @brief Retrieve some IPv4 address-like info from a network interface + * @brief Retrieve some IPv4 address-like info from a network interface. * - * @param[in] if_name Name of the interface - * @param[out] p_addr Pointer to address field to be filled up - * @param[in] sigioc_code The IOCTL code associated with the address + * @param[in] if_name Name of the interface. + * @param[out] p_addr Pointer to address field to be filled up. + * @param[in] sigioc_code The IOCTL code associated with the address. * - * @return One of the @ref MBG_RETURN_CODES - * On error, *p_addr is set to all 0. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, @p *p_addr is set to 0. * * @see ::get_port_ip4_settings * @see ::get_port_ip4_addr @@ -1374,8 +1403,8 @@ int get_specific_port_ip4_addr( const char *if_name, IP4_ADDR *p_addr, int sigio } #endif - // we get here on error only - *p_addr = 0; // make empty address + // We only get here on error. + *p_addr = 0; // Make empty address. return rc; @@ -1385,13 +1414,13 @@ int get_specific_port_ip4_addr( const char *if_name, IP4_ADDR *p_addr, int sigio /*HDR*/ /** - * @brief Retrieve the IPv4 address of a network interface + * @brief Retrieve the IPv4 address of a network interface. * - * @param[in] if_name Name of the interface - * @param[out] p_addr Pointer to address field to be filled up + * @param[in] if_name Name of the interface. + * @param[out] p_addr Pointer to address field to be filled up. * - * @return One of the @ref MBG_RETURN_CODES - * On error, *p_addr is set to all 0. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, @p *p_addr is set to 0. * * @see ::get_port_ip4_settings * @see ::get_port_ip4_addr_str @@ -1411,13 +1440,13 @@ int get_port_ip4_addr( const char *if_name, IP4_ADDR *p_addr ) /*HDR*/ /** - * @brief Retrieve the IPv4 net mask of a network interface + * @brief Retrieve the IPv4 net mask of a network interface. * - * @param[in] if_name Name of the interface - * @param[out] p_addr Pointer to address field to be filled up + * @param[in] if_name Name of the interface. + * @param[out] p_addr Pointer to address field to be filled up. * - * @return One of the @ref MBG_RETURN_CODES - * On error, *p_addr is set to all 0. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, @p *p_addr is set to 0. * * @see ::get_port_ip4_settings * @see ::get_port_ip4_addr @@ -1437,13 +1466,13 @@ int get_port_ip4_netmask( const char *if_name, IP4_ADDR *p_addr ) /*HDR*/ /** - * @brief Retrieve the IPv4 broadcast address of a network interface + * @brief Retrieve the IPv4 broadcast address of a network interface. * - * @param[in] if_name Name of the interface - * @param[out] p_addr Pointer to address field to be filled up + * @param[in] if_name Name of the interface. + * @param[out] p_addr Pointer to address field to be filled up. * - * @return One of the @ref MBG_RETURN_CODES - * On error, *p_addr is set to all 0. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, @p *p_addr is set to 0. * * @see ::get_port_ip4_settings * @see ::get_port_ip4_addr @@ -1463,13 +1492,15 @@ int get_port_ip4_broad_addr( const char *if_name, IP4_ADDR *p_addr ) #if defined( MBG_TGT_LINUX ) +#if !defined( USE_MBG_SOC) + static /*HDR*/ /** - * @brief Read a requested message from the netlink socket + * @brief Read a requested message from the netlink socket. * - * @return Message length (>= 0) on success, or of the @ref MBG_ERROR_CODES + * @return Message length (>= 0) on success, or of the (negative) @ref MBG_ERROR_CODES. */ -int nl_read( int sock_fd, char *buf_ptr, size_t buf_size, int seq_num, int pid ) +int nl_read( int sock_fd, char *buf_ptr, size_t buf_size, uint32_t seq_num, uint32_t pid ) { struct nlmsghdr *nl_hdr; int read_len = 0; @@ -1477,7 +1508,7 @@ int nl_read( int sock_fd, char *buf_ptr, size_t buf_size, int seq_num, int pid ) do { - // receive response from the kernel, can be several chunks + // Receive response from the kernel, can be several chunks. if ( ( read_len = recv( sock_fd, buf_ptr, buf_size - msg_len, 0 ) ) == -1 ) { int rc = mbg_get_last_socket_error( NULL ); @@ -1490,7 +1521,7 @@ int nl_read( int sock_fd, char *buf_ptr, size_t buf_size, int seq_num, int pid ) nl_hdr = (struct nlmsghdr *) buf_ptr; - // check if the header is valid + // Check if the header is valid. if ( ( NLMSG_OK( nl_hdr, read_len ) == 0 ) || ( nl_hdr->nlmsg_type == NLMSG_ERROR ) ) { #if DEBUG_NETLINK @@ -1500,24 +1531,24 @@ int nl_read( int sock_fd, char *buf_ptr, size_t buf_size, int seq_num, int pid ) return MBG_ERR_DATA_FMT; } - // check if the its the last message + // Check if it's the last message. if ( nl_hdr->nlmsg_type == NLMSG_DONE ) { #if DEBUG_NETLINK - mbglog( LOG_ERR, "%s: Reached last message in received packet", + mbglog( LOG_ERR, "%s: Reached last message in received netlink packet", __func__ ); #endif break; } - // move the pointer to buffer appropriately + // Appropriately move the pointer to the buffer. buf_ptr += read_len; msg_len += read_len; - // check if its a multi part message + // Check if it's a multi part message. if ( ( nl_hdr->nlmsg_flags & NLM_F_MULTI ) == 0 ) { - // return if it's not a multi part message + // Return if it's not a multi part message. #if DEBUG_NETLINK mbglog( LOG_ERR, "%s: Received packet is not a multi part message", __func__ ); @@ -1536,6 +1567,7 @@ int nl_read( int sock_fd, char *buf_ptr, size_t buf_size, int seq_num, int pid ) } // nl_read +#endif #if DEBUG_NETLINK @@ -1558,20 +1590,21 @@ void nl_log_bytes( const char *fnc, const char *info, const void *p, int n_byte #endif +#if !defined( USE_MBG_SOC) static /*HDR*/ int nl_parse_routes( struct nlmsghdr *nl_hdr, struct route_info *rt_info ) { - // parse the route info returned + // Parse the route info returned. struct rtmsg *rt_msg; struct rtattr *rt_attr; int rt_len; rt_msg = (struct rtmsg *) NLMSG_DATA( nl_hdr ); - // If the route is not for AF_INET then return. + // If the route is not for AF_INET, return. // This could be also IPv6 routes. - if ( rt_msg->rtm_family != AF_INET ) //##++ TODO: PF_INET6 for IPv6 + if ( rt_msg->rtm_family != AF_INET ) // TODO PF_INET6 for IPv6 { #if DEBUG_NETLINK mbglog( LOG_ERR, "%s: Route is not AF_INET (%li), but %li", @@ -1580,7 +1613,7 @@ int nl_parse_routes( struct nlmsghdr *nl_hdr, struct route_info *rt_info ) return -1; } - // If the route does not belong to main routing table then return. + // If the route does not belong to main routing table, return. if ( rt_msg->rtm_table != RT_TABLE_MAIN ) { #if DEBUG_NETLINK @@ -1591,7 +1624,7 @@ int nl_parse_routes( struct nlmsghdr *nl_hdr, struct route_info *rt_info ) } - // get the rtattr field + // Get the rtattr field. rt_attr = (struct rtattr *) RTM_RTA( rt_msg ); rt_len = RTM_PAYLOAD( nl_hdr ); @@ -1636,7 +1669,7 @@ int nl_parse_routes( struct nlmsghdr *nl_hdr, struct route_info *rt_info ) case RTA_TABLE: { // The RTA_TABLE attribute was added to the kernel source in 2006 to support - // more than 255 routing tables. Originally the number of the routing table + // more than 255 routing tables. Originally, the number of the routing table // to which an entry belongs had been passed only in struct rtmsg::rtm_table, // which is only 8 bits wide and should still hold the 8 LSBs of the full // routing table number for compatibility, so this should still work for the @@ -1663,33 +1696,37 @@ int nl_parse_routes( struct nlmsghdr *nl_hdr, struct route_info *rt_info ) } // nl_parse_routes +#endif // !defined( USE_MBG_SOC ) + #endif // defined( MBG_TGT_LINUX ) /*HDR*/ /** - * @brief Retrieve the IPv4 gateway (default route) + * @brief Retrieve the IPv4 gateway (default route). * - * @param[out] p_addr Pointer to address field to be filled up + * @param[out] p_addr Pointer to address field to be filled up. * - * @return One of the @ref MBG_RETURN_CODES - * On error, *p_addr is set to all 0. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, @p *p_addr is set to 0. */ int get_ip4_gateway( IP4_ADDR *p_addr ) { int rc = MBG_ERR_NOT_SUPP_ON_OS; #if defined( MBG_TGT_LINUX ) + +#if !defined( USE_MBG_SOC) struct nlmsghdr *nlmsg; struct route_info route_info; - char msg_buf[8192]; // pretty large buffer, why 8192 ? + char msg_buf[8192]; // TODO Pretty large buffer, why 8192 ? int sock_fd; int len; int msg_seq = 0; int idx; - // create socket + // Create socket. if ( ( sock_fd = socket( PF_NETLINK, SOCK_DGRAM, NETLINK_ROUTE ) ) == -1 ) { rc = mbg_get_last_socket_error( NULL ); @@ -1701,21 +1738,21 @@ int get_ip4_gateway( IP4_ADDR *p_addr ) } - // initialize buffer with request message + // Initialize a buffer with a request message. memset( msg_buf, 0, sizeof( msg_buf ) ); - // point the header and the msg structure pointers into the buffer + // Point the header and the msg structure pointers into the buffer. nlmsg = (struct nlmsghdr *) msg_buf; - // fill in the nlmsg header - nlmsg->nlmsg_len = NLMSG_LENGTH( sizeof( struct rtmsg ) ); // length of message - nlmsg->nlmsg_type = RTM_GETROUTE; // get the routes from kernel routing table + // Fill in the nlmsg header. + nlmsg->nlmsg_len = NLMSG_LENGTH( sizeof( struct rtmsg ) ); // Length of message. + nlmsg->nlmsg_type = RTM_GETROUTE; // Get the routes from kernel routing table. - nlmsg->nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST; // the message is a request for dump - nlmsg->nlmsg_seq = msg_seq++; // sequence of the message packet - nlmsg->nlmsg_pid = getpid(); // PID of process sending the request + nlmsg->nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST; // The message is a request for dump. + nlmsg->nlmsg_seq = msg_seq++; // Sequence of the message packet. + nlmsg->nlmsg_pid = getpid(); // PID of process sending the request. - // send the request + // Send the request. if ( send( sock_fd, nlmsg, nlmsg->nlmsg_len, 0 ) == -1 ) { rc = mbg_get_last_socket_error( NULL ); @@ -1726,7 +1763,7 @@ int get_ip4_gateway( IP4_ADDR *p_addr ) goto out; } - // read the response + // Read the response. if ( ( len = nl_read( sock_fd, msg_buf, sizeof( msg_buf ), msg_seq, getpid() ) ) < 0 ) { #if DEBUG_NETLINK @@ -1741,7 +1778,7 @@ int get_ip4_gateway( IP4_ADDR *p_addr ) mbglog( LOG_ERR, "%s: Read %i bytes from netlink socket", __func__, len ); #endif - // parse and print the response + // Parse and print the response. for ( idx = 0; NLMSG_OK( nlmsg, len ); nlmsg = NLMSG_NEXT( nlmsg, len ), idx++ ) { memset( &route_info, 0, sizeof( route_info ) ); @@ -1752,7 +1789,7 @@ int get_ip4_gateway( IP4_ADDR *p_addr ) if ( nl_parse_routes( nlmsg, &route_info ) < 0 ) - continue; // don't check route_info if it has not been set up + continue; // Don't check route_info if it has not been set up. #if DEBUG_NETLINK { @@ -1760,8 +1797,8 @@ int get_ip4_gateway( IP4_ADDR *p_addr ) int l = sizeof( ws ); int n = 0; - // inet_ntoa() uses a static buffer which is overwritten on every call - //##++ TODO: rather than inet_ntoa use inet_ntop which can also handle IPv6 + // inet_ntoa() uses a static buffer which is overwritten on every call. + // TODO Rather than inet_ntoa, use inet_ntop which can also handle IPv6. n += snprintf_safe( &ws[n], l - n, "src %s", (char *) inet_ntoa( route_info.srcAddr ) ); n += snprintf_safe( &ws[n], l - n, ", dst %s", (char *) inet_ntoa( route_info.dstAddr ) ); n += snprintf_safe( &ws[n], l - n, ", gw %s", (char *) inet_ntoa( route_info.gateWay ) ); @@ -1771,8 +1808,8 @@ int get_ip4_gateway( IP4_ADDR *p_addr ) } #endif - // check if default IPv4 gateway - //##++ TODO: rather than inet_ntoa use inet_ntop which can also handle IPv6 + // Check if default IPv4 gateway. + // TODO Rather than inet_ntoa, use inet_ntop which can also handle IPv6. if ( strstr( (char *) inet_ntoa( route_info.dstAddr ), "0.0.0.0" ) ) { *p_addr = ntohl( route_info.gateWay.s_addr ); @@ -1780,7 +1817,7 @@ int get_ip4_gateway( IP4_ADDR *p_addr ) // Actually we could stop searching now. However, in case of debug // we'll continue to examine the rest of the routing message. #if DEBUG_NETLINK - //##++ TODO: rather than inet_ntoa use inet_ntop which can also handle IPv6 + // TODO Rather than inet_ntoa, use inet_ntop which can also handle IPv6 mbglog( LOG_ERR, "%s: Default gateway found: %s", __func__, (char *) inet_ntoa( route_info.gateWay ) ); #else @@ -1793,6 +1830,44 @@ out: if ( sock_fd >= 0 ) close( sock_fd ); +#else + + IP4_ADDR dest, gateway, mask; + unsigned int flags, refcnt, use, metric, mtu, window, irtt; + int fret = 0; + + char name[ IFNAMSIZ ]; + + FILE* f = fopen( "/proc/net/route", "r" ); + + if( !f ) + { + rc = MBG_ERR_IO; + goto out; + } + + while (fret != EOF) + { + fret = fscanf( f, "%s %08X %08X %04X %u %u %u %08X %u %u %u ", + name, (uint32_t*) &dest, (uint32_t*) &gateway, &flags, &refcnt, &use, &metric,(uint32_t*) &mask, &mtu, &window, &irtt ); + + if ( fret == 11 ) + { + if (dest == 0 && gateway != 0) + { + *p_addr = ntohl(gateway); + rc = MBG_SUCCESS; + break; + } + } + } + + fclose(f); + +out: + +#endif + #endif // defined( MBG_TGT_LINUX ) if ( mbg_rc_is_error( rc ) ) @@ -1806,14 +1881,14 @@ out: /*HDR*/ /** - * @brief Retrieve the IPv4 address of a network interface as string + * @brief Retrieve the IPv4 address of a network interface as string. * - * @param[in] if_name Name of the interface - * @param[out] p_addr_buf Pointer to the string buffer to be filled up - * @param[in] buf_size size of the string buffer + * @param[in] if_name Name of the interface. + * @param[out] p_addr_buf Pointer to the string buffer to be filled up. + * @param[in] buf_size Size of the string buffer. * - * @return One of the @ref MBG_RETURN_CODES - * On error, a string according to "0.0.0.0" is generated. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, a string "0.0.0.0" is generated. * * @see ::get_port_ip4_settings * @see ::get_port_ip4_addr @@ -1839,14 +1914,14 @@ int get_port_ip4_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) /*HDR*/ /** - * @brief Retrieve the IPv4 net mask of a network interface as string + * @brief Retrieve the IPv4 net mask of a network interface as string. * - * @param[in] if_name Name of the interface - * @param[out] p_addr_buf Pointer to the string buffer to be filled up - * @param[in] buf_size size of the string buffer + * @param[in] if_name Name of the interface. + * @param[out] p_addr_buf Pointer to the string buffer to be filled up. + * @param[in] buf_size Size of the string buffer. * - * @return One of the @ref MBG_RETURN_CODES - * On error, a string according to "0.0.0.0" is generated. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, a string "0.0.0.0" is generated. * * @see ::get_port_ip4_settings * @see ::get_port_ip4_addr @@ -1872,14 +1947,14 @@ int get_port_ip4_netmask_str( const char *if_name, char *p_addr_buf, int buf_siz /*HDR*/ /** - * @brief Retrieve the IPv4 broadcast address of a network interface as string + * @brief Retrieve the IPv4 broadcast address of a network interface as string. * - * @param[in] if_name Name of the interface - * @param[out] p_addr_buf Pointer to the string buffer to be filled up - * @param[in] buf_size size of the string buffer + * @param[in] if_name Name of the interface. + * @param[out] p_addr_buf Pointer to the string buffer to be filled up. + * @param[in] buf_size Size of the string buffer. * - * @return One of the @ref MBG_RETURN_CODES - * On error, a string according to "0.0.0.0" is generated. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, a string "0.0.0.0" is generated. * * @see ::get_port_ip4_settings * @see ::get_port_ip4_addr @@ -1905,12 +1980,12 @@ int get_port_ip4_broad_addr_str( const char *if_name, char *p_addr_buf, int buf_ /*HDR*/ /** - * @brief Retrieve the current IPv4 settings of a network interface + * @brief Retrieve the current IPv4 settings of a network interface. * - * @param[in] if_name Name of the interface - * @param[out] p Pointer to a IP4_SETTINGS structure to be filled up + * @param[in] if_name Name of the interface. + * @param[out] p Pointer to a ::IP4_SETTINGS structure to be filled up. * - * @return One of the @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::get_port_ip4_addr * @see ::get_port_ip4_addr_str @@ -1945,18 +2020,16 @@ int get_port_ip4_settings( const char *if_name, IP4_SETTINGS *p ) goto out; -#ifndef USE_MBG_TSU rc = get_ip4_gateway( &p->gateway ); if ( mbg_rc_is_error( rc ) ) goto out; -#endif -#if 0 //### TODO +#if 0 // TODO // We could also try to check VLAN and DHCP settings here, // but as of now, this is specific to an application. - // ##++++ The VLAN and DHCP status info collected below + // TODO The VLAN and DHCP status info collected below // just return what has been configured previously by this program, // however, it does not reflect any changes which have been made // manually, e.g. via the command line. @@ -1972,7 +2045,7 @@ int get_port_ip4_settings( const char *if_name, IP4_SETTINGS *p ) out: - // Check linkup independent from success of getting IP4 parameters + // Check link state regardless of the result of getting IP4 parameters. link_up = check_port_link( if_name ); if ( link_up ) diff --git a/mbglib/common/lan_util.h b/mbglib/common/lan_util.h index 474a8a3..54e5ae8 100644 --- a/mbglib/common/lan_util.h +++ b/mbglib/common/lan_util.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: lan_util.h 1.9 2018/02/28 16:55:31Z martin REL_M $ + * $Id: lan_util.h 1.10 2021/03/22 18:07:28Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: lan_util.h $ - * Revision 1.9 2018/02/28 16:55:31Z martin + * Revision 1.10 2021/03/22 18:07:28Z martin + * Updated a bunch of comments. + * Revision 1.9 2018/02/28 16:55:31 martin * Updated function prototypes. * Revision 1.8 2017/10/05 08:20:40 daniel * Introduced check_port_status() function @@ -43,7 +45,7 @@ /* Other headers to be included */ #include <mbg_tgt.h> -#include <gpsdefs.h> // for some Meinberg data structures +#include <gpsdefs.h> // For some Meinberg data structures. #include <stdlib.h> @@ -51,7 +53,7 @@ #include <sys/types.h> #include <sys/socket.h> #include <net/if.h> - #include <ifaddrs.h> // *must* be included *after* net/if.h + #include <ifaddrs.h> // *Must* be included *after* net/if.h. #else // A dummy declaration to prevent from warnings due to usage // of this type with function prototypes. @@ -62,7 +64,7 @@ #endif -#if defined( IFHWADDRLEN ) // usually defined in net/if.h +#if defined( IFHWADDRLEN ) // Usually defined in net/if.h. #if ( IFHWADDRLEN != 6 ) #error Warning: IFHWADDRLEN is not 6! #endif @@ -81,7 +83,7 @@ /* Start of header body */ #if defined( _USE_PACK ) - #pragma pack( 1 ) // set byte alignment + #pragma pack( 1 ) // Set byte alignment. #define _USING_BYTE_ALIGNMENT #endif @@ -91,11 +93,11 @@ extern "C" { #if !defined( MAC_SEP_CHAR ) - #define MAC_SEP_CHAR ':' // character used to separate octets of a MAC ID + #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 + #define MAC_SEP_CHAR_ALT '-' ///< Alternate character used to separate octets of a MAC ID. #endif @@ -115,16 +117,16 @@ extern "C" { /** - * @brief Compute an IP4 net mask according to the number of CIDR netmask 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 + * @param[in] netmask_bits Number of netmask bits from CIDR notation. * - * @return The IPv4 net mask + * @return The IPv4 net mask. * - * @see get_ip4_net_mask_bits() + * @see ::get_ip4_net_mask_bits */ static __mbg_inline IP4_ADDR ip4_net_mask_from_cidr( int netmask_bits ) @@ -136,16 +138,16 @@ IP4_ADDR ip4_net_mask_from_cidr( int netmask_bits ) /** - * @brief Determine the broadcast address for an IP4 address plus net mask + * @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. + * results in broadcast address 172.16.3.255. * - * @param p_addr The full IP4 address - * @param p_mask The IP4 net mask + * @param[in] p_addr The full IP4 address. + * @param[in] p_mask The IP4 net mask. * - * @return The determined IP4 broadcast address + * @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 ) @@ -157,16 +159,16 @@ IP4_ADDR ip4_broad_addr_from_addr( const IP4_ADDR *p_addr, const IP4_ADDR *p_mas /** - * @brief Determine the network part of an IP4 address based on the net mask + * @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 + * @param[in] p_addr The full IP4 address. + * @param[in] p_mask The IP4 net mask. * - * @return The network part of the IP4 address + * @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 ) @@ -180,15 +182,15 @@ IP4_ADDR ip4_net_part_from_addr( const IP4_ADDR *p_addr, const IP4_ADDR *p_mask /** * @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 + * @param[in] p_addr1 The first IP4 address to check. + * @param[in] p_addr2 The second IP4 address to check. + * @param[in] p_mask The IP4 net mask. * - * @return true, if the network parts are matching + * @return @a true, if the network parts are matching, else @a false. */ static __mbg_inline int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, - const IP4_ADDR *p_mask ) + const IP4_ADDR *p_mask ) { return ip4_net_part_from_addr( p_addr1, p_mask ) == ip4_net_part_from_addr( p_addr2, p_mask ); @@ -211,28 +213,29 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, /* by MAKEHDR, do not remove the comments. */ /** - * @brief Count the number of sequential bits in an IPv4 net mask + * @brief Count the number of sequential bits in an IPv4 net mask. * - * Counting starts from MSB, i.e. for 0xC0 and 0xC1 the results + * Counting starts from MSB, i.e. for 0xC0 and 0xC1 the results. * are both 2 since only the 2 MSBs are sequentially set. * - * @param[in] p_mask The IPv4 net mask to be evaluated + * @param[in] p_mask The IPv4 net mask to be evaluated. * - * @return The number of sequential MSB bits set in *p_mask + * @return The number of sequential MSB bits set in @p *p_mask. * * @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 formatted string + * @brief Print an IPv4 address to a dotted quad formatted string. * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] p_addr The IPv4 address to be evaluated - * @param[in] info An optional string which is prepended to the string, or NULL + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] p_addr The IPv4 address to be evaluated. + * @param[in] info An optional string which is prepended to the string, or @a NULL. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_ip4_cidr_addr * @see ::str_to_ip4_addr @@ -241,17 +244,18 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, size_t 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 in CIDR notation to a string + * @brief Print an IPv4 address plus net mask in CIDR notation to a string. * * The printed CIDR string is something like "172.16.3.250/24" * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] p_addr The IPv4 address to be evaluated - * @param[in] p_mask The associated IPv4 net mask - * @param[in] info An optional string which is prepended to the string, or NULL + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] p_addr The IPv4 address to be evaluated. + * @param[in] p_mask The associated IPv4 net mask. + * @param[in] info An optional string which is prepended to the string, or @a NULL. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_ip4_addr * @see ::str_to_ip4_addr @@ -260,13 +264,13 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, size_t 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 + * @brief Convert a string to an ::IP4_ADDR. * - * If output parameter is specified as NULL then this function - * can be used to check if the IPv4 address string is formally correct. + * If the output parameter is specified as @a NULL, this function can be used + * to check if the IPv4 address string is formally correct. * - * @param[out] p_addr Pointer to an ::IP4_ADDR variable to be filled, or NULL - * @param[in] s An IPv4 address string to be converted + * @param[out] p_addr Pointer to an ::IP4_ADDR variable to be filled, or @a NULL. + * @param[in] s An IPv4 address string to be converted. * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, @@ -279,16 +283,16 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, 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 + * @brief Convert a string in CIDR notation to an ::IP4_ADDR and net mask. * - * If output parameters are specified as NULL then this function + * If the output parameters are specified as @a NULL, this function * can be used to check if the CIDR string is formally correct. * * @param[out] p_addr Pointer to an ::IP4_ADDR variable to be filled with - * the IPv4 address, or NULL + * the IPv4 address, or @a NULL. * @param[out] p_mask Pointer to an ::IP4_ADDR variable to be filled with - * the IPv4 net mask, or NULL - * @param[in] cidr_str The string to be converted, in CIDR format, e.g. "172.16.3.250/24" + * the IPv4 net mask, or @a NULL. + * @param[in] cidr_str The string to be converted, in CIDR format, e.g. "172.16.3.250/24". * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, @@ -301,28 +305,29 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, int cidr_str_to_ip4_addr_and_net_mask( IP4_ADDR *p_addr, IP4_ADDR *p_mask, const char *cidr_str ) ; /** - * @brief Count the number of sequential bits in an IPv6 net mask + * @brief Count the number of sequential bits in an IPv6 net mask. * * Counting starts from MSB, i.e. for 0xC0 and 0xC1 the results * are both 2 since only the 2 MSBs are sequentially set. * - * @param[in] p_mask The IPv6 net mask to be evaluated + * @param[in] p_mask The IPv6 net mask to be evaluated. * - * @return The number of sequential MSB bits set in *p_mask + * @return The number of sequential MSB bits set in @p *p_mask. * * @see ::ip6_net_mask_from_cidr */ int get_ip6_net_mask_bits( const IP6_ADDR *p_mask ) ; /** - * @brief Print an IPv6 address in optimized format to a string + * @brief Print an IPv6 address in optimized format to a string. * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] p_addr The IPv6 address to be evaluated - * @param[in] info An optional string which is prepended to the string, or NULL + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] p_addr The IPv6 address to be evaluated. + * @param[in] info An optional string which is prepended to the string, or @a NULL. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_ip6_cidr_addr * @see ::snprint_ip6_cidr_mask_addr @@ -333,17 +338,18 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, size_t snprint_ip6_addr( char *s, size_t max_len, const IP6_ADDR *p_addr, const char *info ) ; /** - * @brief Print an IPv6 address plus net mask to string in CIDR notation + * @brief Print an IPv6 address plus net mask to string in CIDR notation. * - * The printed CIDR string is something like "2001:0DB8:0:CD30:EF45::/64" + * The printed CIDR string is something like "2001:0DB8:0:CD30:EF45::/64". * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] p_addr The IPv6 address to be evaluated - * @param[in] p_mask The associated IPv6 net mask - * @param[in] info An optional string which is prepended to the string, or NULL + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] p_addr The IPv6 address to be evaluated. + * @param[in] p_mask The associated IPv6 net mask. + * @param[in] info An optional string which is prepended to the string, or @a NULL. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_ip6_addr * @see ::snprint_ip6_cidr_mask_addr @@ -354,17 +360,18 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, size_t snprint_ip6_cidr_addr( char *s, size_t max_len, const IP6_ADDR *p_addr, const IP6_ADDR *p_mask, const char *info ) ; /** - * @brief Print an IPv6 address plus number of net mask bits to string in CIDR notation + * @brief Print an IPv6 address plus number of net mask bits to string in CIDR notation. * - * The printed CIDR string is something like "2001:0DB8:0:CD30:EF45::/64" + * The printed CIDR string is something like "2001:0DB8:0:CD30:EF45::/64". * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] p_addr The IPv6 address to be evaluated - * @param[in] cidr_mask_bits The CIDR number of bits specifying the IPv6 net mask - * @param[in] info An optional string which is prepended to the string, or NULL + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] p_addr The IPv6 address to be evaluated. + * @param[in] cidr_mask_bits The CIDR number of bits specifying the IPv6 net mask. + * @param[in] info An optional string which is prepended to the string, or @a NULL. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_ip6_addr * @see ::snprint_ip6_cidr_addr @@ -375,16 +382,16 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, size_t snprint_ip6_cidr_mask_addr( char *s, size_t max_len, const IP6_ADDR *p_addr, const int cidr_mask_bits, const char* info ) ; /** - * @brief Convert a string to an ::IP6_ADDR + * @brief Convert a string to an ::IP6_ADDR. * - * If the output parameter is specified as NULL then this function + * If the output parameter is specified as @a NULL, this function * can be used to check if the string is formally correct. * * On success ::IP6_ADDR variable contains the IPv6 address * in little endian byte order. * - * @param[out] p_addr Pointer to the ::IP6_ADDR variable, or NULL - * @param[in] s A string containing an IPv6 address + * @param[out] p_addr Pointer to the ::IP6_ADDR variable, or @a NULL. + * @param[in] s A string containing an IPv6 address. * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, @@ -400,16 +407,16 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) ; /** - * @brief Convert a string in CIDR notation to an ::IP6_ADDR and net mask + * @brief Convert a string in CIDR notation to an ::IP6_ADDR and net mask. * - * If output parameters are specified as NULL then this function + * If the output parameters are specified as @a NULL, this function * can be used to check if the CIDR string is formally correct. * * @param[out] p_addr Pointer to an ::IP6_ADDR variable to be filled up - * with the IPv6 address, or NULL + * with the IPv6 address, or @a NULL. * @param[out] p_mask Pointer to an ::IP6_ADDR variable to be filled up - with the net mask bits, or NULL - * @param[in] cidr_str The string to be converted, in CIDR format, e.g. "2001:0DB8:0:CD30::/64" + with the net mask bits, or @a NULL. + * @param[in] cidr_str The string to be converted, in CIDR format, e.g. "2001:0DB8:0:CD30::/64". * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, @@ -422,14 +429,14 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, int cidr_str_to_ip6_addr_and_net_mask( IP6_ADDR *p_addr, IP6_ADDR *p_mask, const char *cidr_str ) ; /** - * @brief Convert a string in CIDR notation to an ::IP6_ADDR and net mask bits + * @brief Convert a string in CIDR notation to an ::IP6_ADDR and net mask bits. * - * If output parameters are specified as NULL then this function + * If the output parameters are specified as @a NULL, this function * can be used to check if the CIDR string is formally correct. * - * @param[out] p_addr Pointer to an ::IP6_ADDR variable for the IPv6 address, or NULL - * @param[out] p_cidr Pointer to an int variable for the net mask bits, or NULL - * @param[in] cidr_str The string to be converted, in CIDR format, e.g. "2001:0DB8:0:CD30::/64" + * @param[out] p_addr Pointer to an ::IP6_ADDR variable for the IPv6 address, or @a NULL. + * @param[out] p_cidr Pointer to an int variable for the net mask bits, or @a NULL. + * @param[in] cidr_str The string to be converted, in CIDR format, e.g. "2001:0DB8:0:CD30::/64". * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, @@ -442,40 +449,41 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, int cidr_str_to_ip6_addr_and_cidr_bits( IP6_ADDR *p_addr, int *p_cidr, const char *cidr_str ) ; /** - * @brief Compute an IPv6 net mask according to the number of CIDR netmask bits + * @brief Compute an IPv6 net mask according to the number of CIDR netmask bits. * * E.g. the 64 bits mentioned in "2001:0DB8:0:CD30::/64" result in 2^64, * corresponding to FFFF:FFFF:FFFF:FFFF:: in IPv6 notation. * - * @param[out] p_mask Pointer to an ::IP6_ADDR variable for the IPv6 netmask - * @param[in] netmask_bits Number of netmask bits from CIDR notation + * @param[out] p_mask Pointer to an ::IP6_ADDR variable for the IPv6 netmask. + * @param[in] netmask_bits Number of netmask bits from CIDR notation. * * @see ::get_ip6_net_mask_bits */ void ip6_net_mask_from_cidr( IP6_ADDR *p_mask, int netmask_bits ) ; /** - * @brief Determine the network part of an IPv6 address based on the net mask + * @brief Determine the network part of an IPv6 address based on the net mask. * * E.g. IP "2001:0DB8:0:CD30::", net mask "FFFF:FFFF::" yields network part "2001:0DB8::". * - * @param[out] p_net_part The extracted network part of the IPv6 address - * @param[in] p_addr The IPv6 address to be evaluated - * @param[in] p_mask The associated IPv6 net mask + * @param[out] p_net_part The extracted network part of the IPv6 address. + * @param[in] p_addr The IPv6 address to be evaluated. + * @param[in] p_mask The associated IPv6 net mask. */ void ip6_net_part_from_addr( IP6_ADDR *p_net_part, const IP6_ADDR *p_addr, const IP6_ADDR *p_mask ) ; /** - * @brief Print a MAC ID or similar array of octets to a string + * @brief Print a MAC ID or similar array of octets to a string. * - * @param[out] s The string buffer to be filled - * @param[in] max_len Maximum length of the string, i.e. size of the buffer - * @param[in] octets An array of octets - * @param[in] num_octets The number of octets to be printed from the array - * @param[in] sep The separator printed between the bytes, or 0 - * @param[in] info An optional string which is prepended to the output, or NULL + * @param[out] s The string buffer to be filled. + * @param[in] max_len Maximum length of the string, i.e. size of the buffer. + * @param[in] octets An array of octets. + * @param[in] num_octets The number of octets to be printed from the array. + * @param[in] sep The separator printed between the bytes, or 0. + * @param[in] info An optional string which is prepended to the output, or @a NULL. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_mac_addr * @see ::str_to_octets @@ -484,28 +492,30 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, size_t snprint_octets( char *s, size_t max_len, const uint8_t *octets, int num_octets, char sep, const char *info ) ; /** - * @brief Print a ::PTP_CLOCK_ID to a string + * @brief Print a ::PTP_CLOCK_ID to a string. * - * @todo Eventually this function should be moved to a different module. + * @todo Maybe this function should be moved to a different module. * - * @param[out] s The string buffer to be filled - * @param[in] max_len Maximum length of the string, i.e. size of the buffer - * @param[in] p The ::PTP_CLOCK_ID to be printed + * @param[out] s The string buffer to be filled. + * @param[in] max_len Maximum length of the string, i.e. size of the buffer. + * @param[in] p The ::PTP_CLOCK_ID to be printed. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_octets */ size_t snprint_ptp_clock_id( char *s, size_t max_len, const PTP_CLOCK_ID *p ) ; /** - * @brief Print a MAC address to a string + * @brief Print a MAC address to a string. * - * @param[out] s The string buffer to be filled - * @param[in] max_len Maximum length of the string, i.e. size of the buffer - * @param[in] p_mac_addr The MAC address to be printed + * @param[out] s The string buffer to be filled. + * @param[in] max_len Maximum length of the string, i.e. size of the buffer. + * @param[in] p_mac_addr The MAC address to be printed. * - * @return The overall number of characters printed to the string + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprint_octets * @see ::str_to_octets @@ -514,13 +524,13 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, size_t 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 + * @brief Set a MAC ID or a similar array of octets from a string. * - * @param[out] octets An array of octets to be set up - * @param[in] num_octets The number of octets which can be stored - * @param[in] s The string to be converted + * @param[out] octets An array of octets to be set up. + * @param[in] num_octets The number of octets that can be stored. + * @param[in] s The string to be converted. * - * @return The overall number of octets decoded from the string + * @return The overall number of octets decoded from the string. * * @see ::snprint_octets * @see ::snprint_mac_addr @@ -529,12 +539,12 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, int str_to_octets( uint8_t *octets, int num_octets, const char *s ) ; /** - * @brief Check if an array of octets is all zero + * @brief Check if an array of octets is all zero. * - * @param[in] octets Pointer to the array of octets - * @param[in] num_octets Number of octets + * @param[in] octets Pointer to the array of octets. + * @param[in] num_octets Number of octets. * - * @return true if all bytes are 0, else false + * @return @a true if all bytes are 0, else @a false. * * @see ::snprint_octets * @see ::snprint_mac_addr @@ -543,81 +553,82 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, bool octets_are_all_zero( const uint8_t *octets, int num_octets ) ; /** - * @brief Check if a MAC address is all zero + * @brief Check if a MAC address is all zero. * - * @param[in] p_addr Pointer to a MAC address to be checked + * @param[in] p_addr Pointer to a MAC address to be checked. * - * @return true if all bytes of the MAC address are 0, else false + * @return @a true if all bytes of the MAC address are 0, else @a false. * * @see ::octets_are_all_zero */ bool mac_addr_is_all_zero( const MBG_MAC_ADDR *p_addr ) ; /** - * @brief Do a SIOCGxxx IOCTL call to read specific information from a LAN interface + * @brief Do a SIOCGxxx IOCTL call to read specific information from a LAN interface. * - * @param[in] if_name Name of the interface - * @param[in] ioctl_code One of the predefined system SIOCGxxx IOCTL codes + * @param[in] if_name Name of the interface. + * @param[in] ioctl_code One of the predefined system SIOCGxxx IOCTL codes. * @param[out] p_ifreq Pointer to a request buffer * - * @return One of the @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_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 + * @brief Retrieve the index of a specific network interface. * - * @param[in] if_name Name of the interface - * @param[out] p_intf_idx Pointer to a variable to be filled up + * @param[in] if_name Name of the interface. + * @param[out] p_intf_idx Pointer to a variable to be filled up. * - * @return One of the @ref MBG_RETURN_CODES. - * On error, *p_intf_idx is set to -1. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, @p *p_intf_idx is set to -1. */ int get_port_intf_idx( const char *if_name, int *p_intf_idx ) ; /** - * @brief Retrieve the MAC address of a network interface + * @brief Retrieve the MAC address of a network interface. * - * @param[in] if_name Name of the interface - * @param[out] p_mac_addr Pointer to the MAC address buffer to be filled up + * @param[in] if_name Name of the interface. + * @param[out] p_mac_addr Pointer to the MAC address buffer to be filled up. * - * @return One of the @ref MBG_RETURN_CODES - * On error, the MAC address is set to all 0 + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, the MAC address @p *p_mac_addr is set to all 0. */ int get_port_mac_addr( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) ; /** - * @brief Check the link state of a network interface + * @brief Check the link state of a network interface. * - * @param[in] if_name Name of the interface + * @param[in] if_name Name of the interface. * - * @return 1 if link detected on port, - * 0 if no link detected on port, - * one of the @ref MBG_ERROR_CODES in case of an error + * @return 1 if link detected on port,<br> + * 0 if no link detected on port,<br> + * one of the (negative) @ref MBG_ERROR_CODES in case of an error. */ int check_port_link( const char *if_name ) ; /** - * @brief Check the state of a network interface + * @brief Check the state of a network interface. * - * @param[in] if_name Name of the interface to check - * @param[out] p_speed Optional pointer to a variable to take up the link speed, may be NULL - * @param[out] p_duplex Optional pointer to a variable to take up the duplex state, may be NULL + * @param[in] if_name Name of the interface to check. + * @param[out] p_speed Optional pointer to a variable to take up the link speed, may be @a NULL. + * @param[out] p_duplex Optional pointer to a variable to take up the duplex state, may be @a NULL. * - * @return 1 if link detected on port, - * 0 if no link detected on port, - * one of the @ref MBG_ERROR_CODES in case of an error + * @return 1 if link detected on port,<br> + * 0 if no link detected on port,<br> + * one of the (negative) @ref MBG_ERROR_CODES in case of an error. + * In case of error, @p *p_duplex is set to -1. */ int check_port_status( const char *if_name, int *p_speed, int *p_duplex ) ; /** - * @brief Retrieve the IPv4 address of a network interface + * @brief Retrieve the IPv4 address of a network interface. * - * @param[in] if_name Name of the interface - * @param[out] p_addr Pointer to address field to be filled up + * @param[in] if_name Name of the interface. + * @param[out] p_addr Pointer to address field to be filled up. * - * @return One of the @ref MBG_RETURN_CODES - * On error, *p_addr is set to all 0. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, @p *p_addr is set to 0. * * @see ::get_port_ip4_settings * @see ::get_port_ip4_addr_str @@ -630,13 +641,13 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, int get_port_ip4_addr( const char *if_name, IP4_ADDR *p_addr ) ; /** - * @brief Retrieve the IPv4 net mask of a network interface + * @brief Retrieve the IPv4 net mask of a network interface. * - * @param[in] if_name Name of the interface - * @param[out] p_addr Pointer to address field to be filled up + * @param[in] if_name Name of the interface. + * @param[out] p_addr Pointer to address field to be filled up. * - * @return One of the @ref MBG_RETURN_CODES - * On error, *p_addr is set to all 0. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, @p *p_addr is set to 0. * * @see ::get_port_ip4_settings * @see ::get_port_ip4_addr @@ -649,13 +660,13 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, int get_port_ip4_netmask( const char *if_name, IP4_ADDR *p_addr ) ; /** - * @brief Retrieve the IPv4 broadcast address of a network interface + * @brief Retrieve the IPv4 broadcast address of a network interface. * - * @param[in] if_name Name of the interface - * @param[out] p_addr Pointer to address field to be filled up + * @param[in] if_name Name of the interface. + * @param[out] p_addr Pointer to address field to be filled up. * - * @return One of the @ref MBG_RETURN_CODES - * On error, *p_addr is set to all 0. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, @p *p_addr is set to 0. * * @see ::get_port_ip4_settings * @see ::get_port_ip4_addr @@ -668,24 +679,24 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, int get_port_ip4_broad_addr( const char *if_name, IP4_ADDR *p_addr ) ; /** - * @brief Retrieve the IPv4 gateway (default route) + * @brief Retrieve the IPv4 gateway (default route). * - * @param[out] p_addr Pointer to address field to be filled up + * @param[out] p_addr Pointer to address field to be filled up. * - * @return One of the @ref MBG_RETURN_CODES - * On error, *p_addr is set to all 0. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, @p *p_addr is set to 0. */ int get_ip4_gateway( IP4_ADDR *p_addr ) ; /** - * @brief Retrieve the IPv4 address of a network interface as string + * @brief Retrieve the IPv4 address of a network interface as string. * - * @param[in] if_name Name of the interface - * @param[out] p_addr_buf Pointer to the string buffer to be filled up - * @param[in] buf_size size of the string buffer + * @param[in] if_name Name of the interface. + * @param[out] p_addr_buf Pointer to the string buffer to be filled up. + * @param[in] buf_size Size of the string buffer. * - * @return One of the @ref MBG_RETURN_CODES - * On error, a string according to "0.0.0.0" is generated. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, a string "0.0.0.0" is generated. * * @see ::get_port_ip4_settings * @see ::get_port_ip4_addr @@ -698,14 +709,14 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, 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 + * @brief Retrieve the IPv4 net mask of a network interface as string. * - * @param[in] if_name Name of the interface - * @param[out] p_addr_buf Pointer to the string buffer to be filled up - * @param[in] buf_size size of the string buffer + * @param[in] if_name Name of the interface. + * @param[out] p_addr_buf Pointer to the string buffer to be filled up. + * @param[in] buf_size Size of the string buffer. * - * @return One of the @ref MBG_RETURN_CODES - * On error, a string according to "0.0.0.0" is generated. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, a string "0.0.0.0" is generated. * * @see ::get_port_ip4_settings * @see ::get_port_ip4_addr @@ -718,14 +729,14 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, 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 + * @brief Retrieve the IPv4 broadcast address of a network interface as string. * - * @param[in] if_name Name of the interface - * @param[out] p_addr_buf Pointer to the string buffer to be filled up - * @param[in] buf_size size of the string buffer + * @param[in] if_name Name of the interface. + * @param[out] p_addr_buf Pointer to the string buffer to be filled up. + * @param[in] buf_size Size of the string buffer. * - * @return One of the @ref MBG_RETURN_CODES - * On error, a string according to "0.0.0.0" is generated. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * On error, a string "0.0.0.0" is generated. * * @see ::get_port_ip4_settings * @see ::get_port_ip4_addr @@ -738,12 +749,12 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, 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 + * @brief Retrieve the current IPv4 settings of a network interface. * - * @param[in] if_name Name of the interface - * @param[out] p Pointer to a IP4_SETTINGS structure to be filled up + * @param[in] if_name Name of the interface. + * @param[out] p Pointer to a ::IP4_SETTINGS structure to be filled up. * - * @return One of the @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::get_port_ip4_addr * @see ::get_port_ip4_addr_str @@ -764,7 +775,7 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, #if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment + #pragma pack() // Set default alignment. #undef _USING_BYTE_ALIGNMENT #endif diff --git a/mbglib/common/mbg_arch.h b/mbglib/common/mbg_arch.h index f803e1d..b2cc341 100644 --- a/mbglib/common/mbg_arch.h +++ b/mbglib/common/mbg_arch.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbg_arch.h 1.6 2017/01/27 09:03:16Z martin REL_M $ + * $Id: mbg_arch.h 1.8 2021/04/16 15:48:42Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -14,7 +14,12 @@ * * ----------------------------------------------------------------------- * $Log: mbg_arch.h $ - * Revision 1.6 2017/01/27 09:03:16Z martin + * Revision 1.8 2021/04/16 15:48:42Z martin + * Start to conditionally use inline functions that allow strict + * type checking of the _mbg_swab_... macros. + * Revision 1.7 2021/03/21 18:20:33 martin + * Updated some comments. + * Revision 1.6 2017/01/27 09:03:16 martin * Added macros _mbg_swab8() and _mbg_swab64(). * Fixed macro syntax. * Modified _swab_dummy() to avoid compiler warnings due to unused variables. @@ -69,7 +74,7 @@ -// If no macros required to access unaligned data have yet been defined, +// If yet no specific macros have been defined to access unaligned data, // define some default macros assuming no special handling is required // to access unaligned data. @@ -83,7 +88,7 @@ -// If no macros to convert endianess have yet been defined, define +// If yet no macros have yet been defined to convert endianess, define // some default macros assuming endianess conversion is not required. #if !defined( __le16_to_cpu ) @@ -113,7 +118,7 @@ // The macros below are used to convert the endianess -// of the plug-in cards to the endianess of the host CPU +// of the plug-in devices to the endianess of the host CPU. #define _mbg8_to_cpu( _x ) ( _x ) #define _mbg16_to_cpu( _x ) __le16_to_cpu( _x ) @@ -157,6 +162,16 @@ void mbg_swab_double( double *p ) #define _mbg_swab32( _p ) do { *(_p) = __swab32( *(_p) ); } while ( 0 ) #define _mbg_swab64( _p ) do { *(_p) = __swab64( *(_p) ); } while ( 0 ) + #define _mbg_swab8u _mbg_swab8 + #define _mbg_swab16u _mbg_swab16 + #define _mbg_swab32u _mbg_swab32 + #define _mbg_swab64u _mbg_swab64 + + #define _mbg_swab8s _mbg_swab8 + #define _mbg_swab16s _mbg_swab16 + #define _mbg_swab32s _mbg_swab32 + #define _mbg_swab64s _mbg_swab64 + #define _mbg_swab_double( _p ) mbg_swab_double( _p ) #define _mbg_swab_doubles( _p, _n ) \ @@ -174,6 +189,33 @@ void mbg_swab_double( double *p ) #define _mbg_swab32( _p ) _nop_macro_fnc() #define _mbg_swab64( _p ) _nop_macro_fnc() + #if 0 + // We can enable this section to compile with very strict + // type checking in the byte swap macros, if the specific + // unsigned/signed variants of the low level macros are used + // in the _mbg_swab_... definitions for types and structures. + + static __mbg_inline void _mbg_swab8u( uint8_t *p ) { (void) p; } + static __mbg_inline void _mbg_swab16u( uint16_t *p ) { (void) p; } + static __mbg_inline void _mbg_swab32u( uint32_t *p ) { (void) p; } + static __mbg_inline void _mbg_swab64u( uint64_t *p ) { (void) p; } + + static __mbg_inline void _mbg_swab8s( int8_t *p ) { (void) p; } + static __mbg_inline void _mbg_swab16s( int16_t *p ) { (void) p; } + static __mbg_inline void _mbg_swab32s( int32_t *p ) { (void) p; } + static __mbg_inline void _mbg_swab64s( int64_t *p ) { (void) p; } + #else + #define _mbg_swab8u _mbg_swab8 + #define _mbg_swab16u _mbg_swab16 + #define _mbg_swab32u _mbg_swab32 + #define _mbg_swab64u _mbg_swab64 + + #define _mbg_swab8s _mbg_swab8 + #define _mbg_swab16s _mbg_swab16 + #define _mbg_swab32s _mbg_swab32 + #define _mbg_swab64s _mbg_swab64 + #endif + #define _mbg_swab_double( _p ) _nop_macro_fnc() #define _mbg_swab_doubles( _p, _n ) _nop_macro_fnc() @@ -182,7 +224,6 @@ void mbg_swab_double( double *p ) - /** * @brief A placeholder for yet missing _mbg_swab_..() macros * diff --git a/mbglib/common/mbg_cof.h b/mbglib/common/mbg_cof.h index 3666b1b..174bce3 100644 --- a/mbglib/common/mbg_cof.h +++ b/mbglib/common/mbg_cof.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbg_cof.h 1.2 2017/07/05 14:25:12Z martin REL_M $ + * $Id: mbg_cof.h 1.3 2020/08/25 08:27:05Z thomas-b REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: mbg_cof.h $ - * Revision 1.2 2017/07/05 14:25:12Z martin + * Revision 1.3 2020/08/25 08:27:05Z thomas-b + * Added check of preprocessor define MBG_NO_TYPEOF + * Revision 1.2 2017/07/05 14:25:12 martin * Reformatted code to conform to standard header file format. * Changes tfor improved cross-platform compatibility. * Revision 1.1 2015/09/09 10:42:27 martin @@ -45,7 +47,7 @@ extern "C" { #endif -#if defined( MBG_TGT_POSIX ) +#if defined( MBG_TGT_POSIX ) && !defined ( MBG_NO_TYPEOF ) // A special construct supported by gcc/clang and and implemented // e.g. in the Linux kernel, which is said to be very type-safe: diff --git a/mbglib/common/mbg_serclock_cfg.h b/mbglib/common/mbg_serclock_cfg.h index 5ff0c63..9ec1ddb 100644 --- a/mbglib/common/mbg_serclock_cfg.h +++ b/mbglib/common/mbg_serclock_cfg.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbg_serclock_cfg.h 1.4 2019/04/05 07:29:33Z martin.burnicki REL_M $ + * $Id: mbg_serclock_cfg.h 1.5 2019/09/27 15:59:47Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: mbg_serclock_cfg.h $ + * Revision 1.5 2019/09/27 15:59:47Z martin + * Removed inclusion of obsolete file pcpcsutil.h. * Revision 1.4 2019/04/05 07:29:33Z martin.burnicki * Added some comments. * Removed some obsolete code. @@ -32,7 +34,6 @@ #include <mbg_tgt.h> #include <gpsdefs.h> #include <pcpsdefs.h> -#include <pcpsutil.h> #include <mbgtime.h> #include <mbgpccyc.h> diff --git a/mbglib/common/mbg_tgt.h b/mbglib/common/mbg_tgt.h index d9f84f5..fb8991b 100644 --- a/mbglib/common/mbg_tgt.h +++ b/mbglib/common/mbg_tgt.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbg_tgt.h 1.45 2019/02/11 09:53:02Z martin REL_M $ + * $Id: mbg_tgt.h 1.52 2021/10/05 09:10:44Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,6 +11,22 @@ * * ----------------------------------------------------------------------- * $Log: mbg_tgt.h $ + * Revision 1.52 2021/10/05 09:10:44Z martin + * Clean up definitions _MBG_API_ATTR_EXPORT and _MBG_API_ATTR_IMPORT. + * Revision 1.51 2021/09/13 08:59:55 martin + * New definitions _MBG_API_ATTR_EXPORT and _MBG_API_ATTR_IMPORT. + * Required if variables that are exported by a DLL are to be + * imported into a different DLL. + * Revision 1.50 2021/03/18 11:08:51 martin + * Updated some comments. + * Revision 1.49 2021/03/12 11:51:37 martin + * Corrected the wording of some comments. + * Revision 1.48 2021/02/10 13:34:35 martin + * Defined MBG_TGT_MISSING_STRUCT_TIMESPEC for CVI. + * Revision 1.47 2019/11/12 15:33:59 martin + * Added some doxygen comments. + * Revision 1.46 2019/08/28 12:52:02 martin + * Changes for mingw. * Revision 1.45 2019/02/11 09:53:02Z martin * Support the mingw build environment. * Changed inclusion of winsock2.h/windows.h on Windows. @@ -38,7 +54,7 @@ * MBG_TGT_HAS_DEV_FN is supported on Windows, but * MBG_TGT_HAS_DEV_FN_BASE is not supported. * Enhanced debug support for Windows kernel drivers. - * Include limits.h under Windows. + * Include limits.h on Windows. * Defined MBG_TGT_MISSING_STRUCT_TIMESPEC for Borland C. * Defined __func__ for BC 5 and for DOS, and provide a * common default declaration.. @@ -93,7 +109,7 @@ * 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. + * Fixed a typo which caused an error with 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 @@ -138,7 +154,7 @@ * Revision 1.13 2008/01/30 15:52:22 martin * Modified checking for availability of wchar_t. * Revision 1.13 2008/01/29 15:18:07Z martin - * Recognize DOS target under Watcom compilers. + * Recognize DOS target with Watcom compilers. * Flag Watcom C always supports wchar_t. * Revision 1.12 2008/01/17 09:38:50Z daniel * Added macros to determine whether C language extensions @@ -152,7 +168,7 @@ * Added MBG_PORT_HANDLE type for serial ports. * Added macros for unified inline code syntax. * Revision 1.9 2006/12/08 12:45:54Z martin - * Under Windows include ntddk.h rather than windows.h + * On Windows include ntddk.h rather than windows.h * if building kernel driver . * Revision 1.8 2006/10/25 12:20:45Z martin * Initial support for FreeBSD, NetBSD, and OpenBSD. @@ -619,7 +635,7 @@ extern "C" { #endif // "struct timespec" is supported only since VS2015 - // If it is then also the symbol TIME_UTC should be defined. + // If it is, also the symbol TIME_UTC should be defined. // Functions to read the current time as struct timespec // are timespec_get() and friends, which are also only provided // by VS2015 and later. @@ -633,7 +649,7 @@ extern "C" { #endif #endif - #if ( _MSC_VER >= 1600 ) // TODO Eventually even 1600 doesn't support this. + #if ( _MSC_VER >= 1600 ) // TODO Even 1600 probably doesn't support this. #include <stdint.h> #include <inttypes.h> #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 @@ -862,10 +878,10 @@ extern "C" { // If the build environment doesn't provide an inttypes.h file -// with print format specifiers for 64 bit fixed size types -// then MBG_PRI_64_PREFIX should be defined, which is used -// to define our own C99 compatible format specifiers. -// Eventually, similar definitions are required for 32, 16, +// with print format specifiers for 64 bit fixed size types, +// MBG_PRI_64_PREFIX should be defined, which is used to +// define our own C99 compatible format specifiers. +// Maybe similar definitions are required for 32, 16, // and 8 bit fixed size types. #if defined( MBG_PRI_64_PREFIX ) #define PRIi64 MBG_PRI_64_PREFIX "i" @@ -927,12 +943,15 @@ extern "C" { // CVI uses an own set of functions to support serial ports typedef int MBG_PORT_HANDLE; #define MBG_INVALID_PORT_HANDLE -1 + + // At least CVI 13.02 doesn't provide a declaration of struct timespec. + #define MBG_TGT_MISSING_STRUCT_TIMESPEC 1 #else typedef HANDLE MBG_PORT_HANDLE; #endif // The DWORD_PTR type is not defined in the headers shipping - // with VC6. However, if the SDK is installed then the SDK's + // with VC6. However, if the SDK is installed, the SDK's // headers may declare this type. This is at least the case // in the Oct 2001 SDK which also defines the symbol _W64. #if !defined( _W64 ) @@ -949,12 +968,25 @@ extern "C" { #endif - #if !defined( MBG_TGT_MINGW ) // not required for MinGW - #if defined( MBG_LIB_EXPORT ) - #define _MBG_API_ATTR __declspec( dllexport ) - #else - #define _MBG_API_ATTR __declspec( dllimport ) - #endif + #if !defined( MBG_TGT_MINGW ) // Not required for MinGW + // The definitions below have to be used if a variable + // is exported from one DLL, and imported by a different + // DLL. It has to be used in the header file with the _ext + // symbol, depending on whether the file is included by + // its "parent" .c or .cpp file which implements the + // variable, or by a different file which just references + // the exported variable. + #define _MBG_API_ATTR_EXPORT __declspec( dllexport ) + #define _MBG_API_ATTR_IMPORT __declspec( dllimport ) + #endif + + // The old code below works well when exporting functions + // from a DLL, but fails if a variable is exported from + // one DLL, and imported by a different DLL. + #if defined( MBG_LIB_EXPORT ) + #define _MBG_API_ATTR _MBG_API_ATTR_EXPORT + #else + #define _MBG_API_ATTR _MBG_API_ATTR_IMPORT #endif #elif defined( MBG_TGT_POSIX ) @@ -979,12 +1011,14 @@ extern "C" { /** - * @brief A socket file descriptor type + * @brief A portable socket descriptor type returned by socket(). + * + * @see ::MBG_INVALID_SOCK_FD for the value returned in case of error. */ -#if defined( MBG_TGT_WIN32 ) && !defined( MBG_TGT_MINGW ) +#if defined( MBG_TGT_WIN32 ) // && !defined( MBG_TGT_MINGW ) #if !defined( MBG_TGT_KERNEL ) // we don't need this in kernel space - // usually evaluates to UINT_PTR, which in turn evaluates - // to (unsigned int), or (unsigned __int64). + /// On Windows usually evaluates to @a UINT_PTR, which in turn + /// evaluates to <em>(unsigned int)</em>, or <em>(unsigned __int64)</em>. typedef SOCKET MBG_SOCK_FD; #endif #elif defined( MBG_TGT_POSIX ) @@ -995,7 +1029,17 @@ extern "C" { /** - * @brief A value to mark an ::MBG_SOCK_FD as invalid + * @brief The value returned by the socket() function in case of error. + * + * On Windows usually evaluates to (SOCKET)(~0), + * since the SOCKET type is unsigned. + * For POSIX systems the value is usually -1. + * + * If the @a socket() call returns this value, + * call ::mbg_get_last_socket_error to retrieve + * one of the portable @ref MBG_ERROR_CODES. + * + * @see ::MBG_SOCK_FD for a portable socket descriptor type. */ #if defined( MBG_TGT_WIN32 ) #define MBG_INVALID_SOCK_FD INVALID_SOCKET // usually evaluates to (SOCKET)(~0) since SOCKET is unsigned @@ -1006,7 +1050,10 @@ extern "C" { /** - * @brief The return code of socket functions in case of error + * @brief The return code of networking functions in case of error. + * + * The code is returned by functions like @a select(), + * @a recv(), etc. in case of error. */ #if defined( MBG_TGT_WIN32 ) #define MBG_SOCKET_ERR_RETVAL SOCKET_ERROR // usually evaluates to -1 @@ -1024,6 +1071,14 @@ extern "C" { #define _MBG_API_ATTR #endif +#if !defined( _MBG_API_ATTR_EXPORT ) + #define _MBG_API_ATTR_EXPORT +#endif + +#if !defined( _MBG_API_ATTR_IMPORT ) + #define _MBG_API_ATTR_IMPORT +#endif + #if !defined( _NO_MBG_API ) #define _NO_MBG_API #endif diff --git a/mbglib/common/mbgadjtm_cfg.h b/mbglib/common/mbgadjtm_cfg.h index dfab87d..f546f71 100644 --- a/mbglib/common/mbgadjtm_cfg.h +++ b/mbglib/common/mbgadjtm_cfg.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgadjtm_cfg.h 1.2 2012/03/01 14:51:03Z martin REL_M $ + * $Id: mbgadjtm_cfg.h 1.3 2019/09/27 15:59:46Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: mbgadjtm_cfg.h $ + * Revision 1.3 2019/09/27 15:59:46Z martin + * Removed inclusion of obsolete file pcpcsutil.h. * Revision 1.2 2012/03/01 14:51:03Z martin * Fixed non-Windows build. * Removed global variable adjtm_cfg. @@ -29,7 +31,7 @@ #include <mbg_tgt.h> #include <gpsdefs.h> #include <pcpsdefs.h> -#include <pcpsutil.h> + #include <mbgtime.h> #include <mbgpccyc.h> diff --git a/mbglib/common/mbgdevio.h b/mbglib/common/mbgdevio.h index e550821..6b5242b 100644 --- a/mbglib/common/mbgdevio.h +++ b/mbglib/common/mbgdevio.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgdevio.h 1.47 2018/11/22 14:27:05Z martin REL_M $ + * $Id: mbgdevio.h 1.59 2021/11/08 21:31:51Z martin.burnicki REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,34 @@ * * ----------------------------------------------------------------------- * $Log: mbgdevio.h $ - * Revision 1.47 2018/11/22 14:27:05Z martin + * Revision 1.59 2021/11/08 21:31:51Z martin.burnicki + * Updated function prototypes. + * Revision 1.58 2021/11/08 18:00:06 martin.burnicki + * Changed MBG_DEV_FN to a structure. + * Revision 1.57 2021/10/05 09:11:45 martin + * Account for new definitions _MBG_API_ATTR_EXPORT and _MBG_API_ATTR_IMPORT. + * Revision 1.56 2021/05/04 21:12:16 martin + * Updated function prototypes. + * Revision 1.55 2021/04/29 15:05:54 martin + * Support reading device CPU info. + * Revision 1.54 2021/04/29 14:46:11 martin + * Moved some inline functions to mbgutil.h. + * Revision 1.53 2021/04/29 14:01:33 martin + * Renamed global variable pc_cycles_frequency to mbg_pc_cycles_frequency. + * Use attribute _MBG_API_ATTR with all declarations of global variables. + * Revision 1.52 2021/04/13 15:00:22 martin + * Moved some SYN1588-specific definitions elsewhere. + * Revision 1.51 2021/03/22 18:09:27 martin + * Updated a bunch of comments. + * Revision 1.50 2021/03/12 14:18:07 martin + * Made variable pc_cycles_frequency global. + * mbg_init_pc_cycles_frequency() now provides a return code. + * Updated a bunch of comments. + * Revision 1.49 2020/10/20 10:37:09 martin + * Added some definitions to conditionally support SYN1588. + * Revision 1.48 2020/02/21 15:39:46 martin + * Updated function prototypes. + * Revision 1.47 2018/11/22 14:27:05 martin * Fixed pointer size problems in a mixed 32/64 bit Linux environment. * Removed obolete preprocessor symbol MBG_USE_KERNEL_DRIVER * and use new global symbol MBG_TGT_USE_IOCTL instead. @@ -58,10 +85,10 @@ * Updated function prototypes. * Support on-board event logs. * Fixed a bug which caused a crash when generic I/O calls - * were used under Windows. + * were used on Windows. * Changes for QNX. - * Workaround to make mbgmon (BC) build under Windows. - * Cleaned up CPU set support under Linux. + * Workaround to make mbgmon (BC) build on Windows. + * Cleaned up CPU set support on Linux. * Moved some macros here so they can be used by other modules. * Support reading CORR_INFO, and reading/writing TR_DISTANCE. * Cleaned up handling of pragma pack(). @@ -229,6 +256,11 @@ #define MBGDEVIO_COMPAT_VERSION 0x0210 +#if !defined( SUPP_SYN1588_USR_SPC ) + #define SUPP_SYN1588_USR_SPC 0 +#endif + + #if defined( MBG_TGT_WIN32 ) #if !defined( MBGDEVIO_XHRT_API ) @@ -251,7 +283,7 @@ #define MBGDEVIO_XHRT_API 1 #endif - // Thread support under Linux depends strongly on + // Thread support on Linux depends strongly on // the versions of some libraries, so the symbols // MBGDEVIO_USE_THREAD_API and MBGDEVIO_HAVE_THREAD_AFFINITY // should be set in the project's Makefile, depending on the @@ -289,7 +321,7 @@ #include <pcpsdrvr.h> -#else // other target OSs which access the hardware directly +#else // Other target OSs which access the hardware directly. #include <pcpsdrvr.h> @@ -332,11 +364,23 @@ #define _ext extern #endif +#if defined( MBGDEVIO_STATIC_LIB ) + // We don't build/use a DLL. + #define _MBG_API_ATTR_VAR +#else + // We do build/use a DLL. + #ifdef _MBGDEVIO + #define _MBG_API_ATTR_VAR _MBG_API_ATTR_EXPORT + #else + #define _MBG_API_ATTR_VAR _MBG_API_ATTR_IMPORT + #endif +#endif + /* Start of header body */ #if defined( _USE_PACK ) - #pragma pack( 1 ) // set byte alignment + #pragma pack( 1 ) // Set byte alignment. #define _USING_BYTE_ALIGNMENT #endif @@ -345,13 +389,13 @@ extern "C" { #endif -#if MBG_TGT_USE_IOCTL // TODO should we use a different symbol to control this? +#if MBG_TGT_USE_IOCTL // TODO Should we use a different symbol to control this? typedef MBG_HANDLE MBG_DEV_HANDLE; #define MBG_INVALID_DEV_HANDLE MBG_INVALID_HANDLE -#else // other target OSs which access the hardware directly +#else // Other target OSs which access the hardware directly. typedef PCPS_DDEV *MBG_DEV_HANDLE; @@ -371,7 +415,7 @@ extern "C" { /** - * @brief A string that can take a device file name + * @brief A structure containing a string that can take a device file name. * * The format of the device file name depends on the type of * operating system. @@ -380,11 +424,17 @@ extern "C" { * a regular file name with an index number appended, * e.g. "/dev/mbgclock0". See ::MBGCLOCK_DEV_FN_BASE. * - * Under Windows this is a complex string composed of GUIDs, + * On Windows this is a complex string composed of GUIDs, * bus-specific vendor and device ID numbers, etc., which can't * easily be handled manually. + * + * The string has been encapsulated in a structure to avoid + * confusion when using arrays of device name strings. */ -typedef char MBG_DEV_FN[260]; // Conforming to MAX_PATH in Windows +typedef struct +{ + char s[260]; // Conforming to MAX_PATH on Windows. +} MBG_DEV_FN; #if MBG_TGT_HAS_DEV_FN_BASE @@ -392,23 +442,38 @@ typedef char MBG_DEV_FN[260]; // Conforming to MAX_PATH in Windows #define MBGCLOCK_DEV_FN_BASE "/dev/mbgclock" #define MBGCLOCK_DEV_FN_FMT MBGCLOCK_DEV_FN_BASE "%i" -_ext const char mbg_dev_fn_base[] +_ext _MBG_API_ATTR_VAR const char mbg_dev_fn_base[] #ifdef _DO_INIT = MBGCLOCK_DEV_FN_BASE #endif ; -_ext const char mbg_dev_fn_fmt[] +_ext _MBG_API_ATTR_VAR const char mbg_dev_fn_fmt[] #ifdef _DO_INIT = MBGCLOCK_DEV_FN_FMT #endif ; -#endif +#endif // MBG_TGT_HAS_DEV_FN_BASE -// Definitions specific to the target OS +/** + * @brief Clock frequency of the PC's cycles counter, in [Hz]. + * + * ::mbg_init_pc_cycles_frequency can be called to determine + * the frequency and set up this variable. + * + * If the cycles frequency value is 0, the target platform + * may not support this, or the value couldn't be determined. + * In this case it's not possible to convert a number of cycles + * to an associated time interval. + */ +_ext _MBG_API_ATTR_VAR MBG_PC_CYCLES_FREQUENCY mbg_pc_cycles_frequency; + + + +// Definitions specific to the target OS. #if defined( MBG_TGT_LINUX ) @@ -453,7 +518,7 @@ _ext const char mbg_dev_fn_fmt[] #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 #if !defined( MBG_PROCESS_ID ) @@ -508,7 +573,7 @@ _ext const char mbg_dev_fn_fmt[] /** - * @brief A generic thread info structure + * @brief A generic thread info structure. */ typedef struct { @@ -522,14 +587,14 @@ typedef struct /** - * @brief A generic type of a thread function + * @brief A generic type of a thread function. */ typedef MBG_THREAD_FNC_RET_VAL MBG_THREAD_FNC_ATTR MBG_THREAD_FNC( void * ); /** - * @brief A structure holding a time stamp / cycles count pair + * @brief A structure holding a time stamp / cycles count pair. * * This can be used to extrapolate the current time from the current * system cycles count. @@ -540,15 +605,15 @@ typedef MBG_THREAD_FNC_RET_VAL MBG_THREAD_FNC_ATTR MBG_THREAD_FNC( void * ); */ typedef struct { - PCPS_HR_TIME_CYCLES htc; ///< Cycles count associated with the time stamp - uint64_t pcps_hr_tstamp64; ///< Time stamp read from a device + PCPS_HR_TIME_CYCLES htc; ///< Cycles count associated with the time stamp. + uint64_t pcps_hr_tstamp64; ///< Time stamp read from a device. } MBG_XHRT_VARS; /** - * @brief A status structure provided by the time polling thread function + * @brief A status structure provided by the time polling thread function. * * This can be used to get information from the poll thread function * and extrapolate the current time from the current system cycles count. @@ -572,7 +637,7 @@ typedef struct /** - * @brief A structure used to control a poll thread function + * @brief A structure used to control a poll thread function. * * See @ref mbg_xhrt_poll_group for details and limitations. * @@ -590,23 +655,23 @@ typedef struct /** - * @brief Device matching modes + * @brief Device match 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_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_MODES ///< 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_MODES ///< Nnumber of known modes. }; /** - * @brief An entry for a list of device file names + * @brief An entry for a list of device file names. * * Applications should consider this type as opaque, * and must not rely on the type, number, and order of @@ -616,14 +681,14 @@ typedef struct _MBG_DEV_FN_LIST_ENTRY MBG_DEV_FN_LIST_ENTRY; /** - * @brief The structure behind the ::MBG_DEV_FN_LIST_ENTRY type + * @brief The structure behind the ::MBG_DEV_FN_LIST_ENTRY type. * * Applications should consider this structure as opaque, * and must not rely on the type, number, and order of * the structure members. * - * The definition is still in the header file since it - * is still required by some Windows-specific code. + * The declaration is still in the header file because + * it is still required by some Windows-specific code. */ struct _MBG_DEV_FN_LIST_ENTRY { @@ -635,7 +700,7 @@ struct _MBG_DEV_FN_LIST_ENTRY /** - * @brief An entry for a list of device names + * @brief An entry for a list of device names. * * Applications should consider this type as opaque, * and must not rely on the type, number, and order of @@ -648,14 +713,14 @@ typedef struct _MBG_DEV_NAME_LIST_ENTRY MBG_DEV_NAME_LIST_ENTRY; /** - * @brief The structure behind the ::MBG_DEV_NAME_LIST_ENTRY type + * @brief The structure behind the ::MBG_DEV_NAME_LIST_ENTRY type. * * Applications should actually consider this structure as opaque, * and must not rely on the type, number, and order of * the structure members. * - * The definition is still in the header file since it is still - * used by some Windows-specific code. + * The declaration is still in the header file because + * it is still used by some Windows-specific code. */ struct _MBG_DEV_NAME_LIST_ENTRY { @@ -708,8 +773,8 @@ struct _MBG_DEV_NAME_LIST_ENTRY * "open" function, e.g. "open" on POSIX systems, or ""CreateFile" * on Windows. * - * While the device file name is a complex string under Windows, - * under Linux and similar systems this is just a device node name + * While the device file name is a complex string on Windows, + * on Linux and similar systems this is just a device node name * like "/dev/mbgclock0" which can easily be used to specify a * particular device. See ::MBG_DEV_FN. * @@ -759,9 +824,10 @@ struct _MBG_DEV_NAME_LIST_ENTRY /** * @defgroup mbgdevio_fast_timestamp_fncs Fast API functions reading high resolution timestamps, but no status * - * These functions are fast, but return only the UTC time. No status flags, + * These functions are fast, but return only the %UTC time. No status flags, * no time zone offset. The time stamps are read from a latched counter chain - * in the PCI chip set, so this is only supported by cards whose chip set supports this. + * in the PCI chip set, so this is only supported by devices the chip set + * of which supports this. * * @see ::mbg_chk_dev_has_fast_hr_timestamp * @see ::mbg_get_fast_hr_timestamp @@ -795,6 +861,13 @@ struct _MBG_DEV_NAME_LIST_ENTRY * * These functions can be used to check if a device supports a particular feature. * + * Whether a specific feature is supported or not, depends on the device type, + * and may depend on the firmware version of the device. + * + * The low level device probe routine (e.g. in the kernel driver) determines + * if a particular feature is indeed supported, or not, and these functions + * just query the results of the probe routine. + * * ::MBG_SUCCESS is returned if the requested feature is supported, * ::MBG_ERR_NOT_SUPP_BY_DEV if the feature is not supported, or one of the other * @ref MBG_ERROR_CODES is returned if an error occurred when trying to determine @@ -837,7 +910,7 @@ struct _MBG_DEV_NAME_LIST_ENTRY /** - * @brief The type of functions to check if a feature is supported + * @brief The type of functions to check if a feature is supported. * * @ingroup mbgdevio_chk_supp_fncs * @see @ref mbgdevio_chk_supp_fncs @@ -855,13 +928,13 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); /** * @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 + * If this library is used as a DLL/shared object library, 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 + * @return The version number. * * @see ::mbgdevio_check_version * @see ::MBGDEVIO_VERSION defined in mbgdevio.h @@ -871,7 +944,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); /** * @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 + * If this library is used as a DLL/shared object library, 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 @@ -880,7 +953,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @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 if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE + * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE. * * @see ::mbgdevio_get_version * @see ::MBGDEVIO_VERSION defined in mbgdevio.h @@ -888,6 +961,17 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbgdevio_check_version( int header_version ) ; /** + * @brief Check if support for SYN1588 devices is available. + * + * @return ::MBG_SUCCESS if SYN1588 support is available,<br> + * ::MBG_ERR_NOT_SUPP_BY_DRVR if driver has been built without SYN1588 support, or<br> + * ::MBG_ERR_NOT_SUPP_ON_OS if SYN1588 devices are not at all supported on the OS. + * + * @see ::mbg_dev_fn_from_dev_idx + */ + _MBG_API_ATTR int _MBG_API mbg_chk_if_syn1588_supported( void ) ; + + /** * @brief Check if a device supports the ::RECEIVER_INFO structure and related calls. * * Very old devices may not provide a ::RECEIVER_INFO structure. @@ -902,7 +986,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_setup_receiver_info @@ -923,7 +1007,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs */ @@ -940,7 +1024,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_generic_io @@ -950,7 +1034,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); /** * @brief Check if a device supports the ::mbg_get_asic_version API call. * - * If ::mbg_get_asic_version is supported, or not, depends on + * Whether ::mbg_get_asic_version is supported, or not, depends on * the bus interface chip assembled on the device. * * @note This function should be preferred over ::mbg_dev_has_asic_version, @@ -959,7 +1043,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_asic_version @@ -969,7 +1053,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); /** * @brief Check if a device supports the ::mbg_get_asic_features call. * - * If ::mbg_get_asic_features is supported, or not, depends on + * Whether ::mbg_get_asic_features is supported, or not, depends on * the bus interface chip assembled on the device. * * @note This function should be preferred over ::mbg_dev_has_asic_features, @@ -978,7 +1062,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_asic_features @@ -997,7 +1081,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_xmr_instances @@ -1009,108 +1093,114 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_xmr( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if the device is connected via the ISA bus + * @brief Check if the device is connected via the ISA bus. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the device is connected via the ISA bus, - * else ::MBG_ERR_NOT_SUPP_BY_DEV + * else ::MBG_ERR_NOT_SUPP_BY_DEV. * * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_isa( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if the device is connected via the MCA bus + * @brief Check if the device is connected via the MCA bus. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the device is connected via the MCA bus, - * else ::MBG_ERR_NOT_SUPP_BY_DEV + * else ::MBG_ERR_NOT_SUPP_BY_DEV. * * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_mca( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if the device is connected via the PCI bus + * @brief Check if the device is connected via the PCI bus. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the device is connected via the PCI bus, - * else ::MBG_ERR_NOT_SUPP_BY_DEV + * else ::MBG_ERR_NOT_SUPP_BY_DEV. * * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_pci( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if the device is connected via the PCI Express bus + * @brief Check if the device is connected via the PCI Express bus. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the device is connected via the PCI Express bus, - * else ::MBG_ERR_NOT_SUPP_BY_DEV + * else ::MBG_ERR_NOT_SUPP_BY_DEV. * * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_pci_express( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if the device is connected via the USB bus + * @brief Check if the device is connected via the USB bus. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the device is connected via the USB bus, - * else ::MBG_ERR_NOT_SUPP_BY_DEV + * else ::MBG_ERR_NOT_SUPP_BY_DEV. * * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_usb( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports GNSS configuration + * @brief Check if a device is a GPS receiver. * - * This is usually the case if a device supports reception of - * different satellite systems, e.g. GPS, Glonass, Galileo, etc. + * The function also returns ::MBG_SUCCESS for GNSS receivers + * which can track GPS satellites beside other GNSS systems. * - * @note This function should be preferred over ::mbg_dev_is_gnss, + * A pure GPS receiver is not considered a GNSS receiver, but + * each of Meinberg's GNSS receivers is also a GPS receiver. + * + * @note This function should be preferred over ::mbg_dev_is_gps, * which has been deprecated. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs - * @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_chk_dev_is_gnss( MBG_DEV_HANDLE dh ) ; + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_gps( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device is a GPS receiver + * @brief Check if a device is a GNSS receiver. * - * The function also returns ::MBG_SUCCESS for GNSS receivers - * which can track GPS satellites beside other GNSS systems. + * This is usually the case if a device supports reception of + * different satellite systems, e.g. GPS, Glonass, Galileo, etc. * - * @note This function should be preferred over ::mbg_dev_is_gps, + * A pure GPS receiver is not considered a GNSS receiver, but + * each of Meinberg's GNSS receivers is also a GPS receiver. + * + * @note This function should be preferred over ::mbg_dev_is_gnss, * which has been deprecated. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs + * @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_chk_dev_is_gps( MBG_DEV_HANDLE dh ) ; + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_gnss( MBG_DEV_HANDLE dh ) ; /** * @brief Check if a device is a DCF77 receiver. * - * Beside standard DCF77 receivers which receive the legacy AM signal + * Beside standard DCF77 receivers which receive the legacy AM signal, * there are also PZF receivers which can decode the pseudo-random phase * modulation and thus yield a higher accuracy. See ::mbg_chk_dev_has_pzf. * @@ -1120,7 +1210,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_pzf @@ -1129,10 +1219,10 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_dcf( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports demodulation of the DCF77 PZF code + * @brief Check if a device supports demodulation of the DCF77 PZF code. * * Beside the enhanced PZF correlation receivers which decode the DCF77's - * pseudo-random phase modulation to yield a better accuracy there are also + * pseudo-random phase modulation to yield a better accuracy, there are also * legacy DCF77 receivers which just decode the standard AM signal. * See ::mbg_chk_dev_is_dcf. * @@ -1142,7 +1232,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_corr_info @@ -1153,7 +1243,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_pzf( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device is a MSF receiver + * @brief Check if a device is a MSF receiver. * * @note This function should be preferred over ::mbg_dev_is_msf, * which has been deprecated. @@ -1161,7 +1251,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_is_lwr @@ -1169,7 +1259,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_msf( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device is a WWVB receiver + * @brief Check if a device is a WWVB receiver. * * @note This function should be preferred over ::mbg_dev_is_wwvb, * which has been deprecated. @@ -1177,7 +1267,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_is_lwr @@ -1190,7 +1280,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_is_lwr @@ -1198,7 +1288,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_jjy( MBG_DEV_HANDLE dh ) ; /** - * @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. * @@ -1208,7 +1298,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_is_dcf @@ -1219,7 +1309,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_lwr( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device provides a configurable IRIG input. + * @brief Check if a device is a time code receiver (TCR, IRIG or similar). * * @note This function should be preferred over ::mbg_dev_is_irig_rx, * which has been deprecated. @@ -1227,18 +1317,35 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_irig_rx_info * @see ::mbg_set_irig_rx_settings * @see ::mbg_chk_dev_has_irig_tx * @see ::mbg_chk_dev_has_irig -*/ + */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_tcr( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports simple LAN interface API calls + * @brief Check if a device is a SYN1588 card. + * + * @note This function always fails if the driver package + * has been built without support for SYN1588 cards. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle. + * + * @return ::MBG_SUCCESS if the device is a SYN1588 card, + * ::MBG_ERR_NO_DEV if is is not,<br> + * ::MBG_ERR_NOT_SUPP_BY_DRVR if driver has been built without SYN1588 support, or<br> + * ::MBG_ERR_NOT_SUPP_ON_OS if SYN1588 devices are not at all supported on the OS. + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_syn1588_type( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports simple LAN interface API calls. * * @note This function should be preferred over ::mbg_dev_has_lan_intf, * which has been deprecated. @@ -1246,7 +1353,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_lan_if_info @@ -1257,7 +1364,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_lan_intf( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports PTP configuration/status calls + * @brief Check if a device supports PTP configuration/status calls. * * @note This function should be preferred over ::mbg_dev_has_ptp, * which has been deprecated. @@ -1265,7 +1372,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_all_ptp_cfg_info @@ -1277,7 +1384,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ptp( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports PTP unicast feature/configuration + * @brief Check if a device supports PTP unicast feature/configuration. * * Not all devices which support PTP do also support PTP Unicast. This API * call checks if PTP Unicast is supported in addition to the standard @@ -1289,7 +1396,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_all_ptp_cfg_info @@ -1301,7 +1408,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ptp_unicast( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports the mbg_get_hr_time... functions + * @brief Check if a device supports the mbg_get_hr_time... functions. * * @note This function should be preferred over ::mbg_dev_has_hr_time, * which has been deprecated. @@ -1309,7 +1416,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_hr_time @@ -1319,7 +1426,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_hr_time( MBG_DEV_HANDLE dh ) ; /** - * @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. * * @note This function should be preferred over ::mbg_dev_has_fast_hr_timestamp, * which has been deprecated. @@ -1327,7 +1434,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_fast_hr_timestamp_cycles @@ -1339,7 +1446,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); /** * @brief Check if a device supports configurable time scales. * - * By default the devices return %UTC and/or local time. However, some cards + * By default the devices return %UTC and/or local time. However, some devices * can be configured to return raw GPS time or TAI instead. * * @note This function should be preferred over ::mbg_dev_has_time_scale, @@ -1348,7 +1455,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_time_scale_info @@ -1357,10 +1464,10 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_time_scale( MBG_DEV_HANDLE dh ) ; /* (Intentionally excluded from Doxygen) - * @brief Check if a device supports setting an event time + * @brief Check if a device supports setting an event time. * * This feature is only supported by some special custom firmware - * to preset a %UTC time at which the clock is to generate an output signal. + * to preset a %UTC time at which the device is to generate an output signal. * * @note This function should be preferred over ::mbg_dev_has_event_time, * which has been deprecated. @@ -1368,7 +1475,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_set_event_time @@ -1376,11 +1483,11 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_event_time( MBG_DEV_HANDLE dh ) ; /** - * @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 device doesn't support this but 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. + * If the device doesn't support this but is a GPS card, it provides + * a time capture FIFO buffer and the obsolete ::mbg_get_gps_ucap call + * can be used to retrieve entries from the FIFO buffer. * * @note This function should be preferred over ::mbg_dev_has_ucap, * which has been deprecated. @@ -1388,7 +1495,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_ucap_entries @@ -1399,11 +1506,11 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ucap( MBG_DEV_HANDLE dh ) ; /** - * @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 device's on-board - * time capture FIFO buffer, but the call may not be supported by some - * older GPS devices. + * The ::mbg_clr_ucap_buff call can be used to clear the on-board + * time capture FIFO buffer of the device, but the call may not + * be supported by some older GPS devices. * * @note This function should be preferred over ::mbg_dev_can_clr_ucap_buff, * which has been deprecated. @@ -1411,7 +1518,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_clr_ucap_buff @@ -1419,7 +1526,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_can_clr_ucap_buff( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports timezone configuration using the ::TZDL structure + * @brief Check if a device supports timezone configuration using the ::TZDL structure. * * @note This function should be preferred over ::mbg_dev_has_tzdl, * which has been deprecated. @@ -1427,7 +1534,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_gps_tzdl @@ -1437,7 +1544,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tzdl( MBG_DEV_HANDLE dh ) ; /** - * @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. * * @note This function should be preferred over ::mbg_dev_has_pcps_tzdl, * which has been deprecated. @@ -1445,7 +1552,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_pcps_tzdl @@ -1463,7 +1570,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_tzcode @@ -1481,7 +1588,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * which has been deprecated. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_tzdl @@ -1499,7 +1606,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_is_tcr @@ -1516,7 +1623,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_irig_tx_info @@ -1528,7 +1635,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_tx( MBG_DEV_HANDLE dh ) ; /** - * @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. * * @note This function should be preferred over ::mbg_dev_has_irig_ctrl_bits, * which has been deprecated. @@ -1536,7 +1643,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_irig_ctrl_bits @@ -1544,7 +1651,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh ) ; /** - * @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. * * @note This function should be preferred over ::mbg_dev_has_raw_irig_data, * which has been deprecated. @@ -1552,7 +1659,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_raw_irig_data @@ -1561,7 +1668,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_raw_irig_data( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports the ::mbg_get_irig_time call + * @brief Check if a device supports the ::mbg_get_irig_time call. * * @note This function should be preferred over ::mbg_dev_has_irig_time, * which has been deprecated. @@ -1569,7 +1676,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_irig_time @@ -1577,7 +1684,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_time( MBG_DEV_HANDLE dh ) ; /** - * @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 similar * time code, or a long wave signal. @@ -1588,14 +1695,14 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_signal( MBG_DEV_HANDLE dh ) ; /** - * @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 provided by a long wave receiver. * @@ -1605,17 +1712,82 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_mod( MBG_DEV_HANDLE dh ) ; + /** + * @brief Check if a device supports the "last sync time". + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES. + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_sync_time( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides the receiver position. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES. + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_rcvr_pos( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides the status of buffered variables. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES. + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_bvar_stat( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports the ::mbg_get_ttm_time API call. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES. + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ttm_time( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides one or more serial ports. + * + * @note This function should only be used for legacy devices that + * don't provide a ::RECEIVER_INFO structure. + * Otherwise ::RECEIVER_INFO::n_com_ports should be checked to see + * if and how many serial ports are provided by the device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES. + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_serial( MBG_DEV_HANDLE dh ) ; + /* (Intentionally excluded from Doxygen) - * @brief Check if a device supports higher baud rates than usual + * @brief Check if a device supports higher baud rates than usual. * * Check if a device provides a serial output that supports - * higher baud rates than older cards, i.e. ::DEFAULT_BAUD_RATES_DCF_HS + * higher baud rates than older ones, i.e. ::DEFAULT_BAUD_RATES_DCF_HS * rather than ::DEFAULT_BAUD_RATES_DCF. * * The call ::mbg_get_serial_settings takes care of this, so applications @@ -1627,7 +1799,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_serial_settings @@ -1635,7 +1807,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_serial_hs( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device provides a programmable frequency synthesizer + * @brief Check if a device provides a programmable frequency synthesizer. * * @note This function should be preferred over ::mbg_dev_has_synth, * which has been deprecated. @@ -1643,7 +1815,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_synth @@ -1652,7 +1824,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_synth( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device provides GPIO signal inputs and/or outputs + * @brief Check if a device provides GPIO signal inputs and/or outputs. * * @note This function should be preferred over ::mbg_dev_has_gpio, * which has been deprecated. @@ -1660,7 +1832,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_gpio_cfg_limits @@ -1671,7 +1843,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_gpio( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports configuration of antenna cable length + * @brief Check if a device supports configuration of antenna cable length. * * @note This function should be preferred over ::mbg_dev_has_cab_len, * which has been deprecated. @@ -1679,7 +1851,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_gps_ant_cable_len @@ -1688,7 +1860,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_cab_len( MBG_DEV_HANDLE dh ) ; /** - * @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. with most IRIG code formats). @@ -1699,7 +1871,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_ref_offs @@ -1719,7 +1891,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_opt_info @@ -1728,7 +1900,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_opt_flags( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device support reading/writing of UTC parameters. + * @brief Check if a device supports 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 @@ -1736,11 +1908,11 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * Meinberg GPS and GNSS devices. * * The %UTC parameter set is usually received from the satellites' broadcasts - * and contains the current time offset between GPS time and UTC, plus information + * and contains the current time offset between GPS time and %UTC, plus information * on a pending leap second event. * * It may be useful to overwrite them to do some tests, or for applications - * where a card is freewheeling. + * where the device is freewheeling anyway. * * @note This function should be preferred over ::mbg_dev_has_utc_parm, * which has been deprecated. @@ -1748,7 +1920,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_utc_parm @@ -1757,7 +1929,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_utc_parm( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports reading correlation info + * @brief Check if a device supports reading correlation info. * * The PZF phase modulation decoded by DCF77 PZF receivers is decoded * using a correlation approach, and optionally there's an API call @@ -1770,7 +1942,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_pzf @@ -1779,7 +1951,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_corr_info( MBG_DEV_HANDLE dh ) ; /** - * @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. @@ -1790,7 +1962,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_pzf @@ -1800,7 +1972,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tr_distance( MBG_DEV_HANDLE dh ) ; /** - * @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. * * @note This function should be preferred over ::mbg_dev_has_debug_status, * which has been deprecated. @@ -1808,7 +1980,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_debug_status @@ -1816,7 +1988,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_debug_status( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device provides an on-board event log + * @brief Check if a device provides an on-board event log. * * @note This function should be preferred over ::mbg_dev_has_evt_log, * which has been deprecated. @@ -1824,7 +1996,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_clr_evt_log @@ -1835,19 +2007,19 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_evt_log( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports bus level DAC control commands + * @brief Check if a device supports bus level DAC control commands. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_ERROR_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_dac_ctrl( MBG_DEV_HANDLE dh ) ; /** - * @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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_receiver_info preferably. * @@ -1855,7 +2027,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_receiver_info @@ -1863,7 +2035,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_receiver_info" ) _MBG_API mbg_dev_has_receiver_info( 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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_gps_data preferably. * @@ -1871,7 +2043,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_gps_data @@ -1879,7 +2051,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_gps_data" ) _MBG_API mbg_dev_has_gps_data( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports the ::mbg_generic_io API call + * @brief Check if a device supports the ::mbg_generic_io API call. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_generic_io preferably. * @@ -1887,7 +2059,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_generic_io @@ -1895,7 +2067,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_generic_io" ) _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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_asic_version preferably. * @@ -1903,7 +2075,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_asic_version @@ -1919,7 +2091,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_asic_features @@ -1928,7 +2100,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_asic_features" ) _MBG_API mbg_dev_has_asic_features( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device provides extended multi ref (XMR) inputs. + * @brief Check if a device provides eXtended Multi Ref (XMR) inputs. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_xmr preferably. * @@ -1936,7 +2108,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_xmr @@ -1945,7 +2117,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_xmr" ) _MBG_API mbg_dev_has_xmr( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports GNSS configuration + * @brief Check if a device supports GNSS configuration. * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_gnss preferably. * @@ -1953,7 +2125,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_gnss @@ -1961,7 +2133,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gnss" ) _MBG_API mbg_dev_is_gnss( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device is a GPS receiver + * @brief Check if a device is a GPS receiver. * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_gps preferably. * @@ -1969,7 +2141,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_gps @@ -1977,7 +2149,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gps" ) _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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_dcf preferably. * @@ -1985,7 +2157,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_dcf @@ -1993,7 +2165,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_dcf" ) _MBG_API mbg_dev_is_dcf( MBG_DEV_HANDLE dh, int *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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_pzf preferably. * @@ -2001,7 +2173,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_pzf @@ -2009,7 +2181,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_pzf" ) _MBG_API mbg_dev_has_pzf( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device is a MSF receiver + * @brief Check if a device is a MSF receiver. * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_msf preferably. * @@ -2017,7 +2189,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_msf @@ -2025,7 +2197,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_msf" ) _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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_wwvb preferably. * @@ -2033,7 +2205,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_wwvb @@ -2041,7 +2213,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_wwvb" ) _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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_lwr preferably. * @@ -2049,7 +2221,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_lwr @@ -2065,7 +2237,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_tcr @@ -2073,7 +2245,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_tcr" ) _MBG_API mbg_dev_is_irig_rx( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports simple LAN interface API calls + * @brief Check if a device supports simple LAN interface API calls. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_lan_intf preferably. * @@ -2081,7 +2253,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_lan_intf @@ -2089,7 +2261,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_lan_intf" ) _MBG_API mbg_dev_has_lan_intf( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports PTP configuration/status calls + * @brief Check if a device supports PTP configuration/status calls. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ptp preferably. * @@ -2097,7 +2269,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_ptp @@ -2105,7 +2277,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ptp" ) _MBG_API mbg_dev_has_ptp( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports PTP unicast feature/configuration + * @brief Check if a device supports PTP unicast feature/configuration. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ptp_unicast preferably. * @@ -2113,7 +2285,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_ptp_unicast @@ -2121,7 +2293,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ptp_unicast" ) _MBG_API mbg_dev_has_ptp_unicast( 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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_hr_time preferably. * @@ -2129,7 +2301,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_hr_time @@ -2137,7 +2309,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_hr_time" ) _MBG_API mbg_dev_has_hr_time( MBG_DEV_HANDLE dh, int *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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_fast_hr_timestamp preferably. * @@ -2145,7 +2317,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_fast_hr_timestamp @@ -2153,7 +2325,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_fast_hr_timestamp" ) _MBG_API mbg_dev_has_fast_hr_timestamp( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports configurable time scales + * @brief Check if a device supports configurable time scales. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_time_scale preferably. * @@ -2161,7 +2333,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_time_scale @@ -2169,7 +2341,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_time_scale" ) _MBG_API mbg_dev_has_time_scale( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports setting an event time + * @brief Check if a device supports setting an event time. * * @note This is only supported by some customized devices * @@ -2179,7 +2351,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_event_time @@ -2187,7 +2359,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_event_time" ) _MBG_API mbg_dev_has_event_time( 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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ucap preferably. * @@ -2195,7 +2367,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_ucap @@ -2203,7 +2375,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ucap" ) _MBG_API mbg_dev_has_ucap( 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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_can_clr_ucap_buff preferably. * @@ -2211,14 +2383,14 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_can_clr_ucap_buff */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_can_clr_ucap_buff" ) _MBG_API mbg_dev_can_clr_ucap_buff( 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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tzdl preferably. * @@ -2226,7 +2398,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_tzdl @@ -2234,7 +2406,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tzdl" ) _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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_pcps_tzdl preferably. * @@ -2242,7 +2414,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_pcps_tzdl @@ -2250,7 +2422,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_pcps_tzdl" ) _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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tzcode preferably. * @@ -2258,7 +2430,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_tzcode @@ -2266,7 +2438,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tzcode" ) _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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tz preferably. * @@ -2274,7 +2446,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_tz @@ -2282,7 +2454,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tz" ) _MBG_API mbg_dev_has_tz( 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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig preferably. * @@ -2290,7 +2462,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_irig @@ -2298,7 +2470,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig" ) _MBG_API mbg_dev_has_irig( 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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig_tx preferably. * @@ -2306,7 +2478,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_irig_tx @@ -2314,7 +2486,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_tx" ) _MBG_API mbg_dev_has_irig_tx( MBG_DEV_HANDLE dh, int *p ) ; /** - * @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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig_ctrl_bits preferably. * @@ -2322,7 +2494,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_irig_ctrl_bits @@ -2330,7 +2502,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_ctrl_bits" ) _MBG_API mbg_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh, int *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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_raw_irig_data preferably. * @@ -2338,14 +2510,14 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_raw_irig_data */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_raw_irig_data" ) _MBG_API mbg_dev_has_raw_irig_data( MBG_DEV_HANDLE dh, int *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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig_time preferably. * @@ -2353,7 +2525,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_irig_time @@ -2361,7 +2533,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_time" ) _MBG_API mbg_dev_has_irig_time( 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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_signal preferably. * @@ -2369,7 +2541,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_signal @@ -2377,7 +2549,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_signal" ) _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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_mod preferably. * @@ -2385,7 +2557,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_mod @@ -2393,10 +2565,10 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_mod" ) _MBG_API mbg_dev_has_mod( MBG_DEV_HANDLE dh, int *p ) ; /* (Intentionally excluded from Doxygen) - * @brief Check if a device supports higher baud rates than usual + * @brief Check if a device supports higher baud rates than usual. * * Check if a device provides a serial output that supports - * higher baud rates than older cards, i.e. ::DEFAULT_BAUD_RATES_DCF_HS + * higher baud rates than older ones, i.e. ::DEFAULT_BAUD_RATES_DCF_HS * rather than ::DEFAULT_BAUD_RATES_DCF. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_serial_hs preferably. @@ -2405,7 +2577,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_serial_hs @@ -2413,7 +2585,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_serial_hs" ) _MBG_API mbg_dev_has_serial_hs( 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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_synth preferably. * @@ -2421,7 +2593,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_synth @@ -2429,7 +2601,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_synth" ) _MBG_API mbg_dev_has_synth( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device provides GPIO signal inputs and/or outputs + * @brief Check if a device provides GPIO signal inputs and/or outputs. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_gpio preferably. * @@ -2437,7 +2609,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_gpio @@ -2445,7 +2617,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_gpio" ) _MBG_API mbg_dev_has_gpio( 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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_cab_len preferably. * @@ -2453,7 +2625,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_cab_len @@ -2461,7 +2633,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_cab_len" ) _MBG_API mbg_dev_has_cab_len( 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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ref_offs preferably. * @@ -2469,7 +2641,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_ref_offs @@ -2477,7 +2649,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ref_offs" ) _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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_opt_flags preferably. * @@ -2485,7 +2657,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_opt_flags @@ -2493,7 +2665,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_opt_flags" ) _MBG_API mbg_dev_has_opt_flags( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device support reading/writing of ::UTC parameters + * @brief Check if a device support reading/writing of ::UTC parameters. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_utc_parm preferably. * @@ -2501,7 +2673,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_utc_parm @@ -2509,7 +2681,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_utc_parm" ) _MBG_API mbg_dev_has_utc_parm( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports reading correlation info + * @brief Check if a device supports reading correlation info. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_corr_info preferably. * @@ -2517,7 +2689,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_corr_info @@ -2525,7 +2697,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_corr_info" ) _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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tr_distance preferably. * @@ -2533,7 +2705,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_tr_distance @@ -2541,7 +2713,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tr_distance" ) _MBG_API mbg_dev_has_tr_distance( MBG_DEV_HANDLE dh, int *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. * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_debug_status preferably. * @@ -2549,7 +2721,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_debug_status @@ -2565,7 +2737,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_evt_log @@ -2573,43 +2745,74 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_evt_log" ) _MBG_API mbg_dev_has_evt_log( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Create a device file name associated with an index number + * @brief Check if a string is a valid device file name. + * + * @param[in] s The string to be checked. + * + * @return ::MBG_SUCCESS if @p s is a valid device file name, else ::MBG_ERR_INV_PARM. + * + * @see ::mbg_dev_fn_from_dev_idx + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_fn_is_valid( const char *s ) ; + + /** + * @brief Create a device file name associated with an index number. * - * Create a system-specific device file name string, e.g. "/dev/mbgclock0" - * under Linux and similar systems, which can be used with the - * open() call on systems which support this, and is also appropriate for - * informational messages, e.g.when referring to a specific device. + * Create a system-specific device file name string, e.g. @a /dev/mbgclock0 + * on Linux and similar systems, which can be used with the @a open call + * on systems which support this, and is also appropriate for informational + * messages, e.g. when referring to a specific device. * - * Under Windows a hardware ID string is required to open the device, + * On Windows, a complex hardware ID string is required to open the device, * and the Windows-specific function mbg_svc_get_device_path can be used - * get the hardware ID string associated with a specific device index - * for that purpose. + * to get the hardware ID string associated with a specific device index. * * However, the Windows hardware ID string is not appropriate for * informational messages referring to a device, so this function - * can be used under Windows and other target systems that don't - * support simple device file names to create a generic string - * like "device #0". + * may return an empty string on Windows, or a pseudo device name + * for devices like SYN1588 PCIe NIC devices. * * @param[out] s Pointer to the output buffer. * @param[in] max_len Size of the output buffer. * @param[in] dev_idx The device index number. * - * @see mbg_svc_get_device_path under Windows + * @return The number of characters written to the output buffer, + * except the terminating 0. + * + * @see ::mbg_dev_info_from_dev_idx + * @see mbg_svc_get_device_path on Windows */ _MBG_API_ATTR int _MBG_API mbg_dev_fn_from_dev_idx( char *s, int max_len, int dev_idx ) ; /** - * @brief Open a device by index number + * @brief Create a device info string associated with an index number. + * + * This consists of a generic string such as "Device #0", followed + * by an associated device file name (e.g. "/dev /mbgclock0"), + * if appropriate. + * + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] dev_idx The device index number. + * + * @return The number of characters written to the output buffer, + * except the terminating 0. + * + * @see ::mbg_dev_fn_from_dev_idx + */ + _MBG_API_ATTR int _MBG_API mbg_dev_info_from_dev_idx( char *s, int max_len, int dev_idx ) ; + + /** + * @brief Open a device by index number. * - * If the call fails then ::mbg_get_last_error should be called - * immediately to get the reason why. + * If the call fails, ::mbg_get_last_error should immediately + * be called to get the reason why. * * For details and similar functions see @ref mbgdevio_open_fncs. * * @param[in] dev_idx Device index number, starting from 0. * - * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE. * * @ingroup mbgdevio_open_fncs * @see ::mbg_close_device @@ -2618,19 +2821,19 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device( int dev_idx ) ; /** - * @brief Open a device specified by a device file name + * @brief Open a device specified by a device file name. * * The format the device file name depends on the operating system. * see ::MBG_DEV_FN. * - * If the call fails then ::mbg_get_last_error should be called - * immediately to get the reason why. + * If the call fails, ::mbg_get_last_error should immediately + * be called to get the reason why. * * For details and similar functions see @ref mbgdevio_open_fncs. * - * @param[in] dev_fn The device file name + * @param[in] dev_fn The device file name. * - * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE. * * @ingroup mbgdevio_open_fncs * @see ::mbg_close_device @@ -2640,7 +2843,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_dev_fn( const char *dev_fn ) ; /** - * @brief Open a device specified by a device file name + * @brief Open a device specified by a device file name. * * @deprecated This function is deprecated, use * ::mbg_open_device_by_dev_fn preferably. @@ -2648,14 +2851,14 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * The format the device file name depends on the operating system. * see ::MBG_DEV_FN. * - * If the call fails then ::mbg_get_last_error should be called - * immediately to get the reason why. + * If the call fails, ::mbg_get_last_error should immediately + * be called to get the reason why. * * For details and similar functions see @ref mbgdevio_open_fncs. * - * @param[in] dev_fn The device file name, see ::MBG_DEV_FN + * @param[in] dev_fn The device file name, see ::MBG_DEV_FN. * - * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE. * * @ingroup mbgdevio_open_fncs * @see ::mbg_close_device @@ -2665,12 +2868,12 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR MBG_DEV_HANDLE _DEPRECATED_BY( "mbg_open_device_by_dev_fn" ) _MBG_API mbg_open_device_by_hw_id( const char *dev_fn ) ; /** - * @brief Get the number of devices installed on the computer + * @brief Get the number of devices installed on the computer. * - * The function ::mbg_find_devices_with_names should eventually - * be used preferafly. See @ref mbgdevio_open_fncs. + * The function ::mbg_find_devices_with_names should probably + * be used preferably. See @ref mbgdevio_open_fncs. * - * @return The number of devices found + * @return The number of devices found. * * @see ::mbg_find_devices_with_names * @see ::mbg_open_device @@ -2679,7 +2882,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_find_devices( void ) ; /** - * @brief Allocate memory and set up a list of installed and supported devices + * @brief Allocate memory and set up a list of installed and supported devices. * * Allocate and fill a list with the names of Meinberg devices currently * present in the system. @@ -2690,11 +2893,11 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * When the list is not used anymore it can be freed by calling * ::mbg_free_device_name_list. * - * @param[in] p_list Pointer to a linked list to be allocated. - * @param[in] max_devices Maximum number of devices to be searched for - * (must not exceed ::N_SUPP_DEV_BUS). + * @param[in] p_list Pointer to a linked list to be allocated. + * @param[in] max_devices Maximum number of devices to be searched for + * (must not exceed ::N_SUPP_DEV_BUS). * - * @return The number of present devices + * @return The number of present devices. * * @see ::mbg_free_device_name_list * @see ::mbg_find_devices @@ -2708,27 +2911,27 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * The list may have been set up and allocated before * by ::mbg_find_devices_with_names. * - * @param[in,out] list Linked list of ::MBG_DEV_NAME_LIST_ENTRY entries. + * @param[in,out] list Linked list of ::MBG_DEV_NAME_LIST_ENTRY entries. * * @see ::mbg_find_devices_with_names */ _MBG_API_ATTR void _MBG_API mbg_free_device_name_list( MBG_DEV_NAME_LIST_ENTRY *list ) ; /** - * @brief Split an ::MBG_DEV_NAME into the 'type name' and 'serial number' components + * @brief Split an ::MBG_DEV_NAME into the 'type name' and 'serial number' components. * * See ::MBG_DEV_NAME for the possible formats of a device name. - * If no @p dev_name is passed then the destination buffers are set + * If no @p dev_name is passed, the destination buffers are set * to empty strings. * * The complementary function ::snprint_dev_name can be used * to generate a device name string. * - * @param[in] dev_name The ::MBG_DEV_NAME string to be split up - * @param[out] type_name Output buffer for the type name part, e.g. a ::PCPS_CLOCK_NAME - * @param[in] type_name_size Size of the output buffer for the type name string - * @param[out] sernum Output buffer for the sernum part, e.g. a ::PCPS_SN_STR - * @param[in] sernum_size Size of the output buffer for the sernum string + * @param[in] dev_name The ::MBG_DEV_NAME string to be split up. + * @param[out] type_name Output buffer for the type name part, e.g. a ::PCPS_CLOCK_NAME. + * @param[in] type_name_size Size of the output buffer for the type name string. + * @param[out] sernum Output buffer for the sernum part, e.g. a ::PCPS_SN_STR. + * @param[in] sernum_size Size of the output buffer for the sernum string. * * @see ::snprint_dev_name * @see ::MBG_DEV_NAME @@ -2737,19 +2940,19 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR void _MBG_API mbg_split_dev_name( const MBG_DEV_NAME dev_name, char *type_name, size_t type_name_size, char *sernum, size_t sernum_size ) ; /** - * @brief Return a handle to a device with a particular device name + * @brief Return a handle to a device with a particular device name. * * See ::MBG_DEV_NAME for the possible formats of a device name. * - * If the call fails then ::mbg_get_last_error should be called - * immediately to get the reason why. + * If the call fails, ::mbg_get_last_error should immediately + * be called to get the reason why. * * For details and similar functions see @ref mbgdevio_open_fncs. * - * @param[in] srch_name String with the ::MBG_DEV_NAME of a device to be opened - * @param[in] selection_mode One of the ::MBG_MATCH_MODES + * @param[in] srch_name String with the ::MBG_DEV_NAME of a device to be opened. + * @param[in] selection_mode One of the ::MBG_MATCH_MODES. * - * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE. * * @ingroup mbgdevio_open_fncs * @see ::mbg_close_device @@ -2760,64 +2963,76 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const MBG_DEV_NAME srch_name, int selection_mode ) ; /** - * @brief Close a device handle and set the handle value to ::MBG_INVALID_DEV_HANDLE + * @brief Close a device handle and set the handle value to ::MBG_INVALID_DEV_HANDLE. * - * @param[in,out] dev_handle Pointer to a Meinberg device handle + * @param[in,out] p_dh Pointer to a Meinberg device handle. * * @see @ref mbgdevio_open_fncs */ - _MBG_API_ATTR void _MBG_API mbg_close_device( MBG_DEV_HANDLE *dev_handle ) ; + _MBG_API_ATTR void _MBG_API mbg_close_device( MBG_DEV_HANDLE *p_dh ) ; /** - * @brief Read information about the driver handling a given device + * @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, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ _MBG_API_ATTR int _MBG_API mbg_get_drvr_info( MBG_DEV_HANDLE dh, PCPS_DRVR_INFO *p ) ; /** - * @brief Read detailed device information + * @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 + * @param[out] p Address of a ::PCPS_DEV structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_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 + * @brief Read CPU type info of the device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Address of a ::PCPS_CPU_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + */ + _MBG_API_ATTR int _MBG_API mbg_get_pcps_cpu_info( MBG_DEV_HANDLE dh, PCPS_CPU_INFO *p ) ; + + /** + * @brief Read the current state of the on-board ::PCPS_STATUS_PORT. * - * This function is useful to read the device's status port which - * also includes the ::PCPS_ST_MOD bit reflecting the time code + * This function is useful to read the status port of the device which + * also includes the ::PCPS_ST_MOD bit, which reflects the time code * modulation of long wave receivers. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p A ::PCPS_STATUS_PORT value to be filled up + * @param[out] p A ::PCPS_STATUS_PORT value to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see @ref group_status_port "bitmask" //### TODO check syntax */ _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. + * @brief Generic read function. + * + * 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. * Not all devices support each of the ::PC_GPS_COMMANDS. * - * @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 output buffer + * @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 output buffer. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_generic_write * @see ::mbg_generic_read_gps @@ -2827,8 +3042,10 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_generic_read( MBG_DEV_HANDLE dh, int cmd, void *p, int size ) ; /* (Intentionally excluded from Doxygen) - * Generic read function which writes a GPS command code to a device - * and reads a number of data bytes back into a generic buffer. + * @brief Generic read GPS function. + * + * Writes a GPS command code to a device and reads a number + * of data bytes back into a generic buffer. * The function ::mbg_chk_dev_has_gps_data can be used to check * whether this call is supported by a device. * @@ -2838,10 +3055,10 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] cmd One of the ::PCPS_CMD_CODES supported by the device. - * @param[out] p Pointer to a buffer to be filled up - * @param[in] size Size of the buffer, has to match the expected data size associated with cmd + * @param[out] p Pointer to a buffer to be filled up. + * @param[in] size Size of the buffer, has to match the expected data size associated with @p cmd. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_gps_data * @see ::mbg_generic_write_gps @@ -2852,8 +3069,10 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_generic_read_gps( MBG_DEV_HANDLE dh, int cmd, void *p, int size ) ; /* (Intentionally excluded from Doxygen) - * Generic write function which writes a command code plus an - * associated number of data bytes to a device. + * @brief Generic write function. + * + * Writes a command code plus an associated number + * of data bytes to a device. * * <b>Warning</b>: This is for debugging purposes only! * The specialized API calls should be used preferably. @@ -2861,10 +3080,10 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] cmd One of the ::PCPS_CMD_CODES supported by the device. - * @param[in] p Pointer to a buffer of data to be written - * @param[in] size Size of the buffer, has to match the expected data size associated with cmd + * @param[in] p Pointer to a buffer of data to be written. + * @param[in] size Size of the buffer, has to match the expected data size associated with @p cmd. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_generic_read * @see ::mbg_generic_read_gps @@ -2874,8 +3093,10 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_generic_write( MBG_DEV_HANDLE dh, int cmd, const void *p, int size ) ; /* (Intentionally excluded from Doxygen) - * Generic write function which writes a GPS command code plus an - * associated number of data bytes to a device. + * @brief Generic write GPS function. + * + * Writes a GPS command code plus an associated number + * of data bytes to a device. * The function ::mbg_chk_dev_has_gps_data can be used to check * whether this call is supported by a device. * @@ -2885,10 +3106,10 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] cmd One of the ::PCPS_CMD_CODES supported by the device. - * @param[in] p Pointer to a buffer of data to be written - * @param[in] size Size of the buffer, has to match the expected data size associated with cmd + * @param[in] p Pointer to a buffer of data to be written. + * @param[in] size Size of the buffer, has to match the expected data size associated with @p cmd. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_gps_data * @see ::mbg_generic_read_gps @@ -2899,13 +3120,21 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_generic_write_gps( MBG_DEV_HANDLE dh, int cmd, const void *p, int size ) ; /* (Intentionally excluded from Doxygen) - * Write and/or read generic data to/from a device. + * @brief Write and/or read generic data to/from a device. + * * The function ::mbg_chk_dev_has_generic_io checks * whether this call is supported by a device. * * <b>Warning</b>: This call is for debugging purposes and internal use only! * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] type The type of data to be read/written, see @ref PCPS_CMD_CODES. + * @param[in] in_p Pointer to an input buffer with the data to be written. + * @param[in] in_sz Size of the input buffer, has to match the expected data size associated with @p type. + * @param[out] out_p Pointer to an output buffer to be filled up. + * @param[in] out_sz Size of the output buffer, has to match the expected data size associated with @p type. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_generic_io * @see ::mbg_generic_read @@ -2916,20 +3145,20 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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) only. + * The returned time is local time according to the zone setting onboard + * the device, with a resolution of 10 ms (i.e. 10ths of seconds) only. * - * This call is supported by any device manufactured by Meinberg. + * This call is supported by every device manufactured by Meinberg. * However, for higher accuracy and resolution the @ref mbgdevio_hr_time_fncs or * the @ref mbgdevio_fast_timestamp_fncs group of calls should be used preferably, * if supported by the device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up + * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_legacy_time_fncs * @see ::mbg_get_hr_time @@ -2939,24 +3168,24 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 clock onboard the device to a given date and time. * * The macro ::_pcps_can_set_time checks whether * this call is supported by a device. * * @todo Provide an API function replacing ::_pcps_can_set_time. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] p Pointer to a ::PCPS_STIME structure to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PCPS_STIME structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_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, @@ -2965,7 +3194,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * The macro ::_pcps_has_sync_time checks whether * this call is supported by a device. * - * <b>Note:</b> If that information is not available on the board then + * <b>Note:</b> If that information is not available on the device, * the value of the returned ::PCPS_TIME::sec field is set to 0xFF. * The macro ::_pcps_time_is_read can be used to check whether the * returned information is valid, or "not set". @@ -2973,28 +3202,28 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @todo Provide an API function replacing ::_pcps_has_sync_time. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up + * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_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. * - * <b>Note:</b> This API call is supported under Windows only. + * <b>Note:</b> This API call is supported on Windows only. * The call blocks until the kernel driver detects a second change * reported by the device. The accuracy of this call is limited * to a few milliseconds. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up + * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_legacy_time_fncs * @see ::mbg_get_time @@ -3002,10 +3231,11 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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, including status + * @brief Read the current high resolution time, including status. * * Fills up a ::PCPS_HR_TIME (High Resolution time) structure containing - * the current %UTC time (seconds since 1970), %UTC offset, and status. + * the current %UTC time (seconds since 1970), %UTC offset, and status + * (see @ref PCPS_TIME_STATUS_FLAGS). * * The API call ::mbg_chk_dev_has_hr_time checks whether * this call is supported by a device. @@ -3013,9 +3243,9 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * For details see @ref ::mbgdevio_hr_time_fncs * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::PCPS_HR_TIME structure to be filled up + * @param[out] p Pointer to a ::PCPS_HR_TIME structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_hr_time_fncs * @see @ref mbgdevio_hr_time_fncs @@ -3025,24 +3255,25 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_get_hr_time( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) ; /* (Intentionally excluded from Doxygen ) - * Write a high resolution time stamp ::PCPS_TIME_STAMP to a device - * to configure a %UTC time when the clock shall generate an event. + * @brief Write a high resolution time stamp ::PCPS_TIME_STAMP to a device. + * + * Used to configure a %UTC time when the device shall generate an event. * The API call ::mbg_chk_dev_has_event_time checks whether * this call is supported by a device. * - * <b>Note:</b> This is only supported by some special firmware. + * <b>Note:</b> This is only supported by devices running some special firmware. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::PCPS_TIME_STAMP structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_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 + * @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 @@ -3052,16 +3283,16 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * 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 + * @param[out] p Pointer to a ::PCPS_SERIAL structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_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 + * @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 @@ -3071,9 +3302,9 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * 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 + * @param[in] p Pointer to a ::PCPS_SERIAL structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_save_serial_settings */ @@ -3082,7 +3313,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); /** * @brief Read time zone/daylight saving configuration code from a device. * - * The APIs using ::TZCODE are only supported by some simpler cards + * The APIs using ::TZCODE are only supported by some simpler devices * and allow just a very basic configuration. * * The API call ::mbg_chk_dev_has_tzcode checks whether @@ -3095,7 +3326,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_TZCODE structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_tzcode * @see ::mbg_set_tzcode @@ -3107,8 +3338,8 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); /** * @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. + * The APIs using ::TZCODE are only supported by some simpler devices + * and allow only a very basic configuration. * * The API call ::mbg_chk_dev_has_tzcode checks whether * this call is supported by a device. @@ -3120,7 +3351,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::PCPS_TZCODE structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_tzcode * @see ::mbg_get_tzcode @@ -3145,7 +3376,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_TZDL structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_pcps_tzdl * @see ::mbg_set_pcps_tzdl @@ -3163,13 +3394,13 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * * The API call ::mbg_chk_dev_has_pcps_tzdl checks whether * this call is supported by a device. - * Other cards may support the ::mbg_set_tzcode or ::mbg_set_gps_tzdl + * Other devices may support the ::mbg_set_tzcode or ::mbg_set_gps_tzdl * calls instead. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::PCPS_TZDL structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_pcps_tzdl * @see ::mbg_get_pcps_tzdl @@ -3179,7 +3410,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 @@ -3191,7 +3422,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::MBG_REF_OFFS value to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_ref_offs * @see ::mbg_set_ref_offs @@ -3211,7 +3442,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::MBG_REF_OFFS value to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_ref_offs * @see ::mbg_get_ref_offs @@ -3219,7 +3450,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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. @@ -3230,7 +3461,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::MBG_OPT_INFO structure to be filled up * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_opt_flags * @see ::mbg_set_opt_settings @@ -3249,7 +3480,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::MBG_OPT_SETTINGS structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_opt_flags * @see ::mbg_get_opt_info @@ -3257,7 +3488,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 capabilities + * @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 @@ -3267,9 +3498,9 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * 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 + * @param[out] p Address of an ::IRIG_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_all_irig_rx_info * @see ::mbg_set_irig_rx_settings @@ -3290,12 +3521,12 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * The API call ::mbg_chk_dev_is_tcr checks whether * this call is supported by a device. * ::mbg_get_irig_rx_info should be called first to determine - * the possible settings supported by the device's IRIG input. + * the possible settings supported by the input of the device. * * @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, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_save_all_irig_rx_settings * @see ::mbg_get_irig_rx_info @@ -3307,15 +3538,15 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] pdev Pointer to the device's ::PCPS_DEV structure //### TODO Make this obsolete - * @param[in] p_irig_info Pointer to a ::IRIG_SETTINGS structure to be written - * @param[in] p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written - * @param[in] p_opt_info Pointer to a ::MBG_OPT_SETTINGS structure to be written + * @param[in] pdev Pointer to the ::PCPS_DEV structure of the device. TODO Make this obsolete! + * @param[in] p_irig_info Pointer to a ::IRIG_SETTINGS structure to be read. + * @param[in] p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be read. + * @param[in] p_opt_info Pointer to a ::MBG_OPT_SETTINGS structure to be read. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_save_all_irig_rx_settings * @see ::mbg_set_irig_rx_settings @@ -3333,12 +3564,12 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * the possible settings supported by the IRIG input. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] pdev Pointer to the device's ::PCPS_DEV structure //### TODO Make this obsolete - * @param[out] p_irig_settings Pointer to a ::IRIG_SETTINGS structure to be written - * @param[out] p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written - * @param[out] p_opt_settings Pointer to a ::MBG_OPT_SETTINGS structure to be written + * @param[in] pdev Pointer to the ::PCPS_DEV structure of the device. TODO Make this obsolete! + * @param[out] p_irig_settings Pointer to a ::IRIG_SETTINGS structure to be written. + * @param[out] p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written. + * @param[out] p_opt_settings Pointer to a ::MBG_OPT_SETTINGS structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_all_irig_rx_info * @see ::mbg_set_irig_rx_settings @@ -3357,7 +3588,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * * In some IRIG formats these bits provide some well-known information which can * also be evaluated by the device. For example, in IEEE 1344 or IEEE C37.118 code - * the control function bits are used to provide the year number, UTC offset, + * the control function bits are used to provide the year number, %UTC offset, * DST status, leap second warning, etc. * * For most IRIG code formats, however, these bits are reserved, i.e. not used @@ -3373,7 +3604,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::MBG_IRIG_CTRL_BITS type to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_irig_ctrl_bits */ @@ -3390,9 +3621,9 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * 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_RAW_IRIG_DATA type to be filled up + * @param[out] p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_raw_irig_data * @see ::mbg_get_raw_irig_data_on_sec_change @@ -3402,20 +3633,20 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); /** * @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, + * This function waits until the second of the on-board time rolls over, * and then reads the last recent raw IRIG data from the device. * * The API call ::mbg_chk_dev_has_raw_irig_data checks whether * this call is supported by a device. * * <b>Note:</b> The ::mbg_get_time_sec_change function called - * by this function is supported under Windows only, so this function - * can also be used under Windows only. + * by this function is supported on Windows only, so this function + * can also be used on Windows only. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_raw_irig_data * @see ::mbg_get_raw_irig_data @@ -3428,7 +3659,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * * Reads 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 - * also contains the year number then the year number is also returned, otherwise + * also contains the year number, the year number is also returned, otherwise * the returned year number is 0xFF. * * The API call ::mbg_chk_dev_has_irig_time checks whether @@ -3437,21 +3668,21 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_IRIG_TIME type to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_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 the on-board time capture FIFO buffer. * * The API call ::mbg_chk_dev_can_clr_ucap_buff checks whether * this call is supported by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_can_clr_ucap_buff * @see ::mbg_get_ucap_entries @@ -3460,7 +3691,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 the event capture buffer. * * Reads a ::PCPS_UCAP_ENTRIES structure with the number of user capture * events actually stored in the FIFO buffer, and the maximum number of @@ -3470,9 +3701,9 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * 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_UCAP_ENTRIES structure to be filled up + * @param[out] p Pointer to a ::PCPS_UCAP_ENTRIES structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_ucap * @see ::mbg_get_ucap_entries @@ -3481,12 +3712,12 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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. * - * If no capture event is available in the FIFO buffer then both the seconds + * If no capture event is available in the FIFO buffer, both the seconds * and the fractions of the returned timestamp are 0. * * The API call ::mbg_chk_dev_has_ucap checks whether @@ -3494,12 +3725,12 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * * <b>Note:</b> This call is very much faster than the older ::mbg_get_gps_ucap * call which is obsolete but still supported for compatibility with - * older cards. + * older devices. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_HR_TIME structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_ucap * @see ::mbg_get_ucap_entries @@ -3508,7 +3739,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 time zone/daylight saving parameters. * * This function returns the time zone/daylight saving parameters * in a ::TZDL structure. @@ -3517,13 +3748,13 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * this call is supported by a device. * * <b>Note:</b> In spite of the function name this call may also be - * supported by non-GPS cards. Other cards may support the ::mbg_get_tzcode + * supported by non-GPS devices. Other devices may support the ::mbg_get_tzcode * or ::mbg_get_pcps_tzdl calls instead. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::TZDL structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_tzdl * @see ::mbg_set_gps_tzdl @@ -3534,7 +3765,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 time zone/daylight saving parameters. * * This function writes the time zone/daylight saving parameters * in a ::TZDL structure to a device. @@ -3543,13 +3774,13 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * this call is supported by a device. * * <b>Note:</b> In spite of the function name this call may also be - * supported by non-GPS cards. Other cards may support the ::mbg_set_tzcode + * supported by non-GPS devices. Other devices may support the ::mbg_set_tzcode * or ::mbg_set_pcps_tzdl calls instead. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::TZDL structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_tzdl * @see ::mbg_get_gps_tzdl @@ -3560,12 +3791,12 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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. * * @deprecated This function is deprecated. * * This function is deprecated, but still supported - * for compatibility with older GPS cards. Normally + * for compatibility with older GPS devices. Normally * the software revision is part of the ::RECEIVER_INFO * structure. See ::mbg_setup_receiver_info which takes * care of the different options. @@ -3574,9 +3805,9 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * 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 ::SW_REV structure to be filled up + * @param[out] p Pointer to a ::SW_REV structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_setup_receiver_info * @see ::mbg_chk_dev_is_gps @@ -3594,62 +3825,85 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * The ::BVAR_STAT type reports which parts of the data set are * available in the receiver, and which are not. * - * If the available data set is not complete then the receiver + * If the available data set is not complete, the receiver * stays in COLD BOOT mode until all data have been received * and thus all data sets are valid. * - * The API call ::mbg_chk_dev_is_gps checks whether + * The API call ::mbg_chk_dev_has_bvar_stat 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 ::BVAR_STAT structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * - * @see ::mbg_chk_dev_is_gps + * @see ::mbg_chk_dev_has_bvar_stat * @see ::BVAR_FLAGS */ _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 on-board time using a ::TTM structure. * - * The API call ::mbg_chk_dev_is_gps checks whether + * The API call ::mbg_chk_dev_has_ttm_time checks whether * this call is supported by a device. * - * <b>Note:</b> This API call is pretty slow, so ::mbg_get_hr_time or + * <b>Note:</b> This API call is very slow, so ::mbg_get_hr_time or * ::mbg_get_fast_hr_timestamp or associated calls should be used preferably. * + * <b>Note:</b> This function should be preferred over ::mbg_get_gps_time, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::TTM structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * + * @see ::mbg_chk_dev_has_ttm_time + * @see ::mbg_get_hr_time + * @see ::mbg_get_fast_hr_timestamp + */ + _MBG_API_ATTR int _MBG_API mbg_get_ttm_time( MBG_DEV_HANDLE dh, TTM *p ) ; + + /** + * @brief Read the current on-board time using a ::TTM structure. + * + * The API call ::mbg_chk_dev_has_ttm_time checks whether + * this call is supported by a device. + * + * @deprecated This function is deprecated, use ::mbg_get_ttm_time preferably. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::TTM structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * + * @see ::mbg_chk_dev_has_ttm_time * @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 ) ; + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_get_ttm_time" ) _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. Date and time must be local time - * according to the device's on-board time zone configuration - * (::TZDL). + * according to the time zone configuration (::TZDL) onboard + * the device. * * The API call ::mbg_chk_dev_is_gps 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 ::TTM structure to be written + * @param[in] p Pointer to a ::TTM structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_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 the serial port configuration. * * @deprecated This function is deprecated, use ::mbg_get_serial_settings preferably. * @@ -3664,7 +3918,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PORT_PARM structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_serial_settings */ @@ -3686,7 +3940,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::PORT_PARM structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_save_serial_settings */ @@ -3707,12 +3961,12 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::ANT_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_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 API call ::mbg_chk_dev_is_gps checks whether * this call is supported by a device. @@ -3725,7 +3979,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::TTM structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_ucap_entries * @see ::mbg_get_ucap_event @@ -3734,10 +3988,10 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 signal outputs - * are to be enabled immediately after the device's power-up, or only + * are to be enabled immediately after the device was powered up, or only * after the device has synchronized to its input signal. * * The function ::mbg_chk_dev_has_gps_data can be used to check @@ -3750,7 +4004,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::ENABLE_FLAGS structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::ENABLE_FLAGS * @see ::ENABLE_FLAGS_CODES @@ -3759,10 +4013,10 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 signal outputs - * are to be enabled immediately after the device's power-up, or only + * are to be enabled immediately after the device was powered up, or only * after the device has synchronized to its input signal. * * The function ::mbg_chk_dev_has_gps_data can be used to check @@ -3775,7 +4029,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ENABLE_FLAGS structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::ENABLE_FLAGS * @see ::ENABLE_FLAGS_CODES @@ -3795,42 +4049,42 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::STAT_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::STAT_INFO */ _MBG_API_ATTR int _MBG_API mbg_get_gps_stat_info( MBG_DEV_HANDLE dh, STAT_INFO *p ) ; /** - * @brief Send one of the ::PC_GPS_COMMANDS to a GPS receiver device + * @brief Send one of the ::PC_GPS_COMMANDS to a GPS receiver device. * * The API call ::mbg_chk_dev_is_gps 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 ::GPS_CMD + * @param[in] p Pointer to a ::GPS_CMD. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::PC_GPS_COMMANDS */ _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/GNSS device. * * The returned ::POS structure contains the current position in * ECEF (Earth Centered, Earth Fixed) kartesian coordinates, and in * geographic coordinates with different formats, using the WGS84 * geographic datum. * - * The API call ::mbg_chk_dev_is_gps checks whether + * The API call ::mbg_chk_dev_has_rcvr_pos 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 ::POS structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_set_gps_pos_xyz * @see ::mbg_set_gps_pos_lla @@ -3838,7 +4092,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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/GNSS receiver position using ::XYZ coordinates. * * The structure ::XYZ must specify the new position in ECEF * (Earth Centered, Earth Fixed) kartesian coordinates. @@ -3847,9 +4101,9 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * this call is supported by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] p Position in ::XYZ format to be written + * @param[in] p Position in ::XYZ format to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_set_gps_pos_lla * @see ::mbg_get_gps_pos @@ -3857,7 +4111,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 + * @brief Set the GPS/GNSS receiver position using ::LLA coordinates. * * The structure ::LLA must specify the new position as longitude, * latitude, and altitude, using the WGS84 geographic datum. @@ -3868,7 +4122,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Position in ::LLA format to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_set_gps_pos_xyz * @see ::mbg_get_gps_pos @@ -3876,7 +4130,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_lla( MBG_DEV_HANDLE dh, const LLA p ) ; /** - * @brief Read the configured antenna cable length from a device + * @brief Read the configured 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 @@ -3888,7 +4142,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an ::ANT_CABLE_LEN structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_cab_len * @see ::mbg_set_gps_ant_cable_len @@ -3912,7 +4166,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an ::ANT_CABLE_LEN structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_cab_len * @see ::mbg_get_gps_ant_cable_len @@ -3920,7 +4174,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 API call ::mbg_chk_dev_has_receiver_info checks * whether this call is supported by a device. @@ -3932,7 +4186,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::RECEIVER_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_setup_receiver_info * @see ::mbg_chk_dev_has_receiver_info @@ -3950,9 +4204,9 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] stii Pointer to a an array of string type information to be filled up. - * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device //### TODO Make this obsolete + * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device. TODO Make this obsolete! * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_serial_settings * @see ::mbg_get_gps_all_port_info @@ -3971,9 +4225,9 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] pii Pointer to a an array of port configuration information to be filled up. - * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device //### TODO Make this obsolete + * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device. TODO Make this obsolete! * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_serial_settings * @see ::mbg_get_gps_all_str_type_info @@ -3992,12 +4246,12 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * whether this call is supported by a device. * * <b>Note:</b> The function ::mbg_save_serial_settings should be used preferably - * to write new port configuration to the board. + * to write new port configuration to the device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] p Pointer to a ::PORT_SETTINGS_IDX structure to be written + * @param[in] p Pointer to a ::PORT_SETTINGS_IDX structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_save_serial_settings * @see ::mbg_set_gps_port_settings @@ -4016,13 +4270,13 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * whether this call is supported by a device. * * <b>Note:</b> The function ::mbg_save_serial_settings should be used preferably - * to write new port configuration to the board. + * to write new port configuration to the device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::PORT_SETTINGS structure to be written. * @param[in] idx Index of the serial port to be configured (starting from 0). * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_save_serial_settings * @see ::mbg_set_gps_port_settings_idx @@ -4033,7 +4287,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); /** * @brief Set up a ::RECEIVER_INFO structure for a device. * - * If the device supports the ::RECEIVER_INFO structure then the structure + * If the device supports the ::RECEIVER_INFO structure, the structure * is read from the device, otherwise a structure is set up using * default values depending on the device type. * @@ -4041,19 +4295,19 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * before, and the returned ::PCPS_DEV structure can be passed to this * function. * - * If a NULL pointer is passed instead, the device info is retrieved + * If a @a NULL pointer is passed instead, the device info is retrieved * directly from the device, using the device handle. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] p_dev Optional pointer to a ::PCPS_DEV structure, may be NULL. + * @param[in] p_obs Obsolete pointer kept for compatibility, should be @a NULL. * @param[out] p Pointer to a ::RECEIVER_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_device_info * @see ::mbg_chk_dev_has_receiver_info */ - _MBG_API_ATTR int _MBG_API mbg_setup_receiver_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, RECEIVER_INFO *p ) ; + _MBG_API_ATTR int _MBG_API mbg_setup_receiver_info( MBG_DEV_HANDLE dh, const void *p_obs, RECEIVER_INFO *p ) ; /** * @brief Read the version code of the on-board PCI/PCIe interface ASIC. @@ -4064,14 +4318,14 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCI_ASIC_VERSION type to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_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 API call ::mbg_chk_dev_has_asic_features checks whether * this call is supported by a device. @@ -4079,14 +4333,14 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCI_ASIC_FEATURES type to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_asic_features */ _MBG_API_ATTR int _MBG_API mbg_get_asic_features( MBG_DEV_HANDLE dh, PCI_ASIC_FEATURES *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. @@ -4099,7 +4353,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::MBG_TIME_SCALE_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_set_time_scale_settings * @see ::mbg_chk_dev_has_time_scale @@ -4107,7 +4361,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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. @@ -4123,7 +4377,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::MBG_TIME_SCALE_SETTINGS structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_time_scale_info * @see ::mbg_chk_dev_has_time_scale @@ -4131,7 +4385,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_set_time_scale_settings( MBG_DEV_HANDLE dh, const MBG_TIME_SCALE_SETTINGS *p ) ; /** - * @brief Read a ::UTC parameter structure from a device + * @brief Read a ::UTC parameter structure from a device. * * The API call ::mbg_chk_dev_has_utc_parm checks whether * this call is supported by a device. @@ -4141,7 +4395,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::UTC structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_utc_parm * @see ::mbg_set_utc_parm @@ -4151,10 +4405,10 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); /** * @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 - * written to the device are overwritten by the parameters broadcast - * by the satellites. + * This should only be done for testing, or if a device is operated + * in always freewheeling mode. If the receiver is tracking any satellites, + * the settings written to the device are overwritten by the parameters + * broadcast by the satellites. * * The API call ::mbg_chk_dev_has_utc_parm checks whether * this call is supported by a device. @@ -4164,7 +4418,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a valid ::UTC structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_utc_parm * @see ::mbg_get_utc_parm @@ -4177,25 +4431,25 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * The ::PCPS_TIME_CYCLES structure contains a ::PCPS_TIME structure * and a PC cycles counter value which can be used to compensate the latency * of the call, i.e. the program execution time until the time stamp has actually - * been read from the board. + * been read from the device. * * This call is supported for any card, similar to ::mbg_get_time. However, * the ::mbg_get_hr_time_cycles call should be used preferably if supported by * the device since that call provides much better accuracy than this one. * - * The cycles counter value corresponds to a value returned by QueryPerformanceCounter() - * under Windows, and get_cycles() under Linux. On operating systems or targets which don't + * The cycles counter value corresponds to a value returned by @a QueryPerformanceCounter + * on Windows, and @a get_cycles on Linux. On operating systems or targets which don't * provide a cycles counter the returned cycles value is always 0. * * Applications should first pick up their own cycles counter value and then call * this function. The difference of the cycles counter values corresponds to the - * latency of the call in units of the cycles counter clock frequency, e.g as reported - * by QueryPerformanceFrequency() under Windows. + * latency of the call in units of the cycles counter clock frequency, e.g. as reported + * by @a QueryPerformanceFrequency on Windows. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_TIME_CYCLES structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_legacy_time_fncs * @see ::mbg_get_hr_time_cycles @@ -4211,26 +4465,26 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * The returned ::PCPS_HR_TIME_CYCLES structure contains a ::PCPS_HR_TIME * structure and a PC cycles counter value which can be used to compensate * the latency of the call, i.e. the program execution time until the time stamp - * has actually been read from the board. + * has actually been read from the device. * * The API call ::mbg_chk_dev_has_hr_time checks whether * this call is supported by the device. * * For details see @ref ::mbgdevio_hr_time_fncs * - * The cycles counter value corresponds to a value returned by QueryPerformanceCounter() - * under Windows, and get_cycles() under Linux. On operating systems or targets which don't + * The cycles counter value corresponds to a value returned by @a QueryPerformanceCounter + * on Windows, and @a get_cycles on Linux. On operating systems or targets which don't * provide a cycles counter the returned cycles value is always 0. * * Applications should first pick up their own cycles counter value and then call * this function. The difference of the cycles counter values corresponds to the - * latency of the call in units of the cycles counter clock frequency, e.g as reported - * by QueryPerformanceFrequency() under Windows. + * latency of the call in units of the cycles counter clock frequency, e.g.task as reported + * by @a QueryPerformanceFrequency on Windows. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::PCPS_HR_TIME_CYCLES structure to be filled up + * @param[out] p Pointer to a ::PCPS_HR_TIME_CYCLES structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_hr_time_fncs * @see ::mbg_chk_dev_has_hr_time @@ -4244,7 +4498,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 latency of the call. * * Read a ::PCPS_HR_TIME structure plus cycles counter value, and correct the * time stamp for the latency of the call as described for ::mbg_get_hr_time_cycles, @@ -4253,23 +4507,23 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * The API call ::mbg_chk_dev_has_hr_time checks whether * this call is supported by the device. * - * For details see @ref ::mbgdevio_hr_time_fncs + * For details see @ref ::mbgdevio_hr_time_fncs. * - * The cycles counter value corresponds to a value returned by QueryPerformanceCounter() - * under Windows, and get_cycles() under Linux. On operating systems or targets which don't + * The cycles counter value corresponds to a value returned by @a QueryPerformanceCounter + * on Windows, and @a get_cycles on Linux. On operating systems or targets which don't * provide a cycles counter the returned cycles value is always 0. * * Applications should first pick up their own cycles counter value and then call * this function. The difference of the cycles counter values corresponds to the - * latency of the call in units of the cycles counter clock frequency, e.g as reported - * by QueryPerformanceFrequency() under Windows. + * latency of the call in units of the cycles counter clock frequency, e.g. as reported + * by @a QueryPerformanceFrequency on Windows. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::PCPS_HR_TIME structure to be filled up - * @param[out] hns_latency Optional pointer to an int32_t value to return - * the latency in 100ns units, or NULL, if not used. + * @param[out] p Pointer to a ::PCPS_HR_TIME structure to be filled up. + * @param[out] hns_latency Optional pointer to an @a int32_t value to return + * the latency in 100ns units, or @a NULL, if not used. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_hr_time_fncs * @see ::mbg_chk_dev_has_hr_time @@ -4294,7 +4548,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an ::IRIG_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_set_irig_tx_settings * @see ::mbg_chk_dev_has_irig_tx @@ -4305,7 +4559,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 API call ::mbg_chk_dev_has_irig_tx checks whether * this call is supported by a device. @@ -4313,7 +4567,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to an ::IRIG_INFO structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_irig_tx_info * @see ::mbg_chk_dev_has_irig_tx @@ -4324,7 +4578,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 + * @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. @@ -4335,7 +4589,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::SYNTH structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_synth * @see ::mbg_set_synth @@ -4345,7 +4599,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_get_synth( MBG_DEV_HANDLE dh, SYNTH *p ) ; /** - * @brief Write frequency synthesizer configuration settings to a device + * @brief Write frequency synthesizer configuration settings to a device. * * Write a ::SYNTH structure containing the configuration of an optional * on-board programmable frequency synthesizer. @@ -4356,7 +4610,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::SYNTH structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_synth * @see ::mbg_get_synth @@ -4366,7 +4620,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 API call ::mbg_chk_dev_has_synth checks whether * this call is supported by a device. @@ -4374,7 +4628,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::SYNTH_STATE structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_synth * @see ::mbg_get_synth @@ -4389,7 +4643,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_TIME_STAMP_CYCLES structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_fast_timestamp_fncs * @see ::mbg_chk_dev_has_fast_hr_timestamp @@ -4400,16 +4654,16 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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. + * before it is returned, it is compensated for the latency of the call. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::PCPS_TIME_STAMP structure to be filled up - * @param[out] hns_latency Optionally receives the latency in hectonanoseconds //### TODO Check if hns + * @param[out] p Pointer to a ::PCPS_TIME_STAMP structure to be filled up. + * @param[out] hns_latency Optionally receives the latency in hectonanoseconds. TODO Check if hns. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_fast_timestamp_fncs * @see ::mbg_chk_dev_has_fast_hr_timestamp @@ -4420,7 +4674,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 @@ -4431,7 +4685,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_TIME_STAMP structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @ingroup mbgdevio_fast_timestamp_fncs * @see ::mbg_chk_dev_has_fast_hr_timestamp @@ -4445,22 +4699,22 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @brief Read current configuraton and features provided by the programmable pulse outputs. * * Read a ::POUT_INFO_IDX array of current settings and configuration - * options of the device's programmable pulse outputs. + * options of the programmable pulse outputs of a device. * * A valid ::RECEIVER_INFO associated with the device * has to be passed to this function. * * The function should only be called if the ::RECEIVER_INFO::n_prg_out - * field (i.e. the number of programmable outputs on the board) is not 0. + * field (i.e. the number of programmable outputs of the device) is not 0. * * 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[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] pii Pointer to a an array of ::POUT_INFO_IDX structures to be filled up - * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device //### TODO Make this obsolete + * @param[out] pii Pointer to a an array of ::POUT_INFO_IDX structures to be filled up. + * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device. TODO Make this obsolete! * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_set_gps_pout_settings_idx * @see ::mbg_set_gps_pout_settings @@ -4469,20 +4723,20 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 * is equivalent to ::mbg_set_gps_pout_settings. * * The function should only be called if the ::RECEIVER_INFO::n_prg_out field - * (i.e. the number of programmable outputs on the board) is not 0, and the + * (i.e. the number of programmable outputs of the device) is not 0, and the * output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::POUT_SETTINGS_IDX structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_gps_all_pout_info * @see ::mbg_set_gps_pout_settings @@ -4490,7 +4744,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 explicitly @@ -4498,14 +4752,14 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * is equivalent to ::mbg_set_gps_pout_settings_idx. * * The function should only be called if the ::RECEIVER_INFO::n_prg_out field - * (i.e. the number of programmable outputs on the board) is not 0, and the + * (i.e. the number of programmable outputs of the device) is not 0, and the * output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::POUT_SETTINGS structure to be written. * @param[in] idx Index of the programmable pulse output to be configured (starting from 0 ). * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_gps_all_pout_info * @see ::mbg_set_gps_pout_settings_idx @@ -4513,23 +4767,23 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 the IRQ status of a device. * * IRQ status information includes flags indicating whether IRQs are - * actually enabled, and whether IRQ support by a card is possibly + * actually enabled, and whether IRQ support by a device is possibly * unsafe due to the firmware and interface chip version. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_IRQ_STAT_INFO variable to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see @ref PCPS_IRQ_STAT_INFO_DEFS */ _MBG_API_ATTR int _MBG_API mbg_get_irq_stat_info( MBG_DEV_HANDLE dh, PCPS_IRQ_STAT_INFO *p ) ; /** - * @brief Read LAN interface information from a device + * @brief Read LAN interface information from a device. * * The API call ::mbg_chk_dev_has_lan_intf checks whether * this call is supported by a device. @@ -4537,7 +4791,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::LAN_IF_INFO variable to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_ip4_state @@ -4547,7 +4801,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 API call ::mbg_chk_dev_has_lan_intf checks whether * this call is supported by a device. @@ -4555,7 +4809,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::IP4_SETTINGS variable to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info @@ -4573,7 +4827,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::IP4_SETTINGS variable to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info @@ -4583,7 +4837,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 API call ::mbg_chk_dev_has_lan_intf checks whether * this call is supported by a device. @@ -4591,7 +4845,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p ::IP4_SETTINGS structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info @@ -4600,7 +4854,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_set_ip4_settings( MBG_DEV_HANDLE dh, const IP4_SETTINGS *p ) ; /** - * @brief Read PTP/IEEE1588 status from a device + * @brief Read PTP/IEEE1588 status from a device. * * The API call ::mbg_chk_dev_has_ptp checks whether * this call is supported by a device. @@ -4608,7 +4862,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PTP_STATE variable to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_ptp * @see ::mbg_get_all_ptp_cfg_info @@ -4619,7 +4873,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 API call ::mbg_chk_dev_has_ptp checks whether * this call is supported by a device. @@ -4627,7 +4881,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PTP_CFG_INFO variable to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_ptp * @see ::mbg_get_all_ptp_cfg_info @@ -4646,7 +4900,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p ::PTP_CFG_SETTINGS structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_ptp * @see ::mbg_get_all_ptp_cfg_info @@ -4665,7 +4919,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PTP_UC_MASTER_CFG_LIMITS variable to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_ptp_unicast * @see ::mbg_get_all_ptp_cfg_info @@ -4683,9 +4937,9 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] pii Pointer to a an array of ::PTP_UC_MASTER_INFO_IDX structures to be filled up. - * @param[in] p_umsl Pointer to a ::PTP_UC_MASTER_CFG_LIMITS structure returned by ::mbg_get_ptp_uc_master_cfg_limits + * @param[in] p_umsl Pointer to a ::PTP_UC_MASTER_CFG_LIMITS structure returned by ::mbg_get_ptp_uc_master_cfg_limits. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_ptp_unicast * @see ::mbg_get_all_ptp_cfg_info @@ -4696,7 +4950,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 API call ::mbg_chk_dev_has_ptp_unicast checks whether * this call is supported by a device. @@ -4704,7 +4958,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p ::PTP_UC_MASTER_SETTINGS_IDX structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_ptp_unicast * @see ::mbg_get_all_ptp_cfg_info @@ -4715,26 +4969,26 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 + * from a device immediately after each other. The returned info structure also * contains some cycles counts to be able to determine the execution times * required to read those time stamps. * * The advantage of this call compared to ::mbg_get_time_info_tstamp is - * that this call also returns the card's status. On the other hand, reading - * the HR time from the card may block e.g. if another application accesses - * the board. + * that this call also returns the status of the device. On the other hand, reading + * the HR time from the device may block e.g. if another application accesses + * the device. * * This call makes a ::mbg_get_hr_time_cycles call internally so the API call * ::mbg_chk_dev_has_hr_time can be used to 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_TIME_INFO_HRT structure to be filled up + * @param[out] p Pointer to a ::MBG_TIME_INFO_HRT structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_hr_time * @see ::mbg_get_time_info_tstamp @@ -4742,7 +4996,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 @@ -4752,7 +5006,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::MBG_TIME_INFO_TSTAMP structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_fast_hr_timestamp * @see ::mbg_get_time_info_hrt @@ -4760,7 +5014,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_get_time_info_tstamp( MBG_DEV_HANDLE dh, MBG_TIME_INFO_TSTAMP *p ) ; /** - * @brief Read PZF correlation info from a device + * @brief Read PZF correlation info from a device. * * The API call ::mbg_chk_dev_has_corr_info checks whether * this call is supported by a device. @@ -4768,7 +5022,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::CORR_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_pzf * @see ::mbg_chk_dev_has_corr_info @@ -4776,7 +5030,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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. @@ -4787,7 +5041,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::TR_DISTANCE variable to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_pzf * @see ::mbg_chk_dev_has_tr_distance @@ -4807,7 +5061,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::TR_DISTANCE variable to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_pzf * @see ::mbg_chk_dev_has_tr_distance @@ -4816,11 +5070,11 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_set_tr_distance( MBG_DEV_HANDLE dh, const TR_DISTANCE *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 - * synchronize to the incoming timecode signal. + * This is mainly supported by IRIG timecode receivers, and the status + * word is intended to provide more detailed information why a device + * might not synchronize to an incoming timecode signal. * * See ::MBG_DEBUG_STATUS and related definitions for details. * @@ -4828,23 +5082,23 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * 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_DEBUG_STATUS variable to be filled up + * @param[out] p Pointer to a ::MBG_DEBUG_STATUS variable to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_debug_status */ _MBG_API_ATTR int _MBG_API mbg_get_debug_status( MBG_DEV_HANDLE dh, MBG_DEBUG_STATUS *p ) ; /** - * @brief Clear the device's on-board event log + * @brief Clear the event log buffer onboard a device. * * The API call ::mbg_chk_dev_has_evt_log checks whether * this call is supported by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_get_num_evt_log_entries @@ -4854,11 +5108,11 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 the event log buffer onboard a device. * - * The returned ::MBG_NUM_EVT_LOG_ENTRIES structure tells how many - * event log entries can be saved on the board, and how many entries - * actually have been saved. + * The returned structure ::MBG_NUM_EVT_LOG_ENTRIES indicates how many + * event log entries can be stored on the device, and how many entries + * are actually stored. * * The API call ::mbg_chk_dev_has_evt_log checks whether * this call is supported by a device. @@ -4866,7 +5120,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::MBG_NUM_EVT_LOG_ENTRIES variable to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_clr_evt_log @@ -4876,20 +5130,20 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 API call ::mbg_chk_dev_has_evt_log checks whether * this call is supported by a device. * - * If no (more) event log entry is available on the device then + * If no (more) event log entry is available onboard the device, * 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[out] p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_clr_evt_log @@ -4899,7 +5153,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_get_first_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) ; /** - * @brief Read the next event log entry from a device + * @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. @@ -4907,13 +5161,13 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * The API call ::mbg_chk_dev_has_evt_log checks whether * this call is supported by a device. * - * If no (more) event log entry is available on the device then + * If no (more) event log entry is available onboard the device, * 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[out] p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_clr_evt_log @@ -4923,7 +5177,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_get_next_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) ; /** - * @brief Read the current GNSS mode info including current settings + * @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. @@ -4936,7 +5190,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_set_gps_gnss_mode_settings * @see ::mbg_get_gps_all_gnss_sat_info @@ -4945,7 +5199,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 + * @brief Write the GNSS mode configuration to a device. * * The ::MBG_GNSS_MODE_SETTINGS structure determines the GNSS settings * for a device, e.g. which satellite systems have to be used. @@ -4961,7 +5215,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p_ms Pointer to a ::MBG_GNSS_MODE_SETTINGS structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_gps_gnss_mode_info * @see ::mbg_get_gps_all_gnss_sat_info @@ -4970,7 +5224,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_set_gps_gnss_mode_settings( MBG_DEV_HANDLE dh, const MBG_GNSS_MODE_SETTINGS *p_ms ) ; /** - * @brief Read a ::GNSS_SAT_INFO_IDX array of satellite status information + * @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 be passed to this function. @@ -4979,7 +5233,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] gsii Pointer to a an array of satellite info structures to be filled up. * @param[in] p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure returned by ::mbg_get_gps_gnss_mode_info. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_gps_gnss_mode_info * @see ::mbg_set_gps_gnss_mode_settings @@ -4988,7 +5242,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 ) ; /** - * @brief Read common GPIO configuration limits + * @brief Read common GPIO configuration limits. * * The API call ::mbg_chk_dev_has_gpio checks whether * this call is supported by a device. @@ -4996,7 +5250,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @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, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits @@ -5016,7 +5270,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @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, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits @@ -5027,7 +5281,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 ) ; /** - * @brief Write the configuration for a single GPIO port to a device + * @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. @@ -5038,7 +5292,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @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, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits @@ -5049,13 +5303,13 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_set_gps_gpio_settings_idx( MBG_DEV_HANDLE dh, const MBG_GPIO_SETTINGS_IDX *p ) ; /** - * @brief Read the status of all GPIO signal ports + * @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, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits @@ -5065,12 +5319,12 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 ) ; /** - * @brief Read ::XMULTI_REF_INSTANCES + * @brief Read ::XMULTI_REF_INSTANCES. * * @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, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_gps_all_xmr_status @@ -5081,13 +5335,13 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _MBG_API_ATTR int _MBG_API mbg_get_xmr_instances( MBG_DEV_HANDLE dh, XMULTI_REF_INSTANCES *p ) ; /** - * @brief Read the status of all XMR sources + * @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, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances @@ -5098,13 +5352,13 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 ) ; /** - * @brief Read all XMR settings and capabilities + * @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, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances @@ -5115,7 +5369,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 + * @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. @@ -5126,7 +5380,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::XMULTI_REF_SETTINGS_IDX structure to be written. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances @@ -5137,7 +5391,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 + * @brief Read the current XMR holdover interval from a device. * * The API call ::mbg_chk_dev_has_xmr checks whether * this call is supported by a device. @@ -5146,7 +5400,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[out] 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, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances @@ -5157,7 +5411,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 * a process may be executed. @@ -5165,7 +5419,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] pid The process ID. * @param[out] p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_set_process_affinity * @see ::mbg_set_current_process_affinity_to_cpu @@ -5181,7 +5435,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] pid The process ID. * @param[out] p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_process_affinity * @see ::mbg_set_current_process_affinity_to_cpu @@ -5189,13 +5443,13 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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[in] cpu_num The number of the CPU. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_get_process_affinity * @see ::mbg_set_process_affinity @@ -5211,7 +5465,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] fnc The name of the thread function to be started. * @param[in] arg A generic argument passed to the thread function. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_thread_stop * @see ::mbg_thread_sleep_interruptible @@ -5228,7 +5482,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * * @param[in,out] p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_thread_create * @see ::mbg_thread_sleep_interruptible @@ -5237,7 +5491,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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. @@ -5245,11 +5499,11 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * This function is only implemented for targets that support threads. * * @param[in,out] p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. - * @param[in] sleep_ms The number of milliseconds to sleep + * @param[in] sleep_ms The number of milliseconds to sleep. * - * @return MBG_SUCCESS if the sleep interval has expired normally, - * MBG_ERR_INTR if a signal to terminate has been received, - * or one of the other @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS if the sleep interval has expired normally,<br> + * ::MBG_ERR_INTR if a signal to terminate has been received,<br> + * or one of the other @ref MBG_ERROR_CODES. * * @see ::mbg_thread_create * @see ::mbg_thread_stop @@ -5258,7 +5512,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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. @@ -5268,7 +5522,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in,out] p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. * @param[in] p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_thread_create * @see ::mbg_thread_stop @@ -5277,7 +5531,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 a function which periodically reads * a time stamp / cycles pair from a device. @@ -5288,11 +5542,11 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); * @param[in] dh the Handle of the device to be polled. * @param[in] freq_hz The initial cycles frequency, if known, in Hz. * @param[in] sleep_ms the sleep interval for the poll thread function in ms. - * If this parameter is 0 then the default sleep interval is used. + * If this parameter is 0, the default sleep interval is used. * - * @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. + * @return ::MBG_SUCCESS on success,<br> + * ::MBG_ERR_NOT_SUPP_BY_DEV if the device to poll does not support HR time,<br> + * else the result of ::mbg_thread_create. * * @see ::mbg_xhrt_poll_thread_stop * @see ::mbg_get_xhrt_time_as_pcps_hr_time @@ -5302,7 +5556,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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. * @@ -5318,7 +5572,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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. @@ -5343,14 +5597,14 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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. * See @ref mbg_xhrt_poll_group for details and limitations. * - * Since FILETIME is a Windows-specific type this function is only - * implemented under Windows. + * Since @a FILETIME is a Windows-specific type, this function is only + * implemented on Windows. * * @param[in,out] p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. * @param[out] p_ft Pointer to a FILETIME structure to be filled up. @@ -5369,7 +5623,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 @ref mbg_xhrt_poll_group for details and limitations. @@ -5393,41 +5647,75 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); _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 system's default cycles counter frequency from the kernel driver + * @brief Retrieve the system's default cycles counter frequency from the kernel driver. * - * This API call can be used on systems which don't provide this information in user space. + * This API call can be used on systems that don't provide this information in user space. * * @param[in] dh Handle of the device to which the IOCTL call is sent. * @param[out] p Pointer of a ::MBG_PC_CYCLES_FREQUENCY variable to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @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 ) ; /** - * @brief Retrieve the system's default cycles counter frequency + * @brief Retrieve the system's default cycles counter frequency. * * @note This may not be supported on all target platforms, in which case the * returned frequency is 0 and the ::mbg_get_default_cycles_frequency_from_dev * call should be used instead. * - * @return the default cycles counter frequency in Hz, or 0 if the value is not available. + * @return The default cycles counter frequency in Hz, or 0 if the value is not available. * * @see ::mbg_get_default_cycles_frequency_from_dev */ _MBG_API_ATTR MBG_PC_CYCLES_FREQUENCY _MBG_API mbg_get_default_cycles_frequency( void ) ; + /** + * @brief Retrieve a string with the SYN1588 type name. + * + * @return The type name string, usually "SYN1588". + */ + _MBG_API_ATTR const char * _MBG_API mbg_get_syn1588_type_name( void ) ; + + /** + * @brief Retrieve the content of a SYN1588 NIC's PTP_SYNC_STATUS register. + * + * @note The variable addressed by @p p is unchanged if an error occurred. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle. + * @param[out] p Pointer to a uint32_t variable to be filled. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + */ + _MBG_API_ATTR int _MBG_API mbg_get_syn1588_ptp_sync_status( MBG_DEV_HANDLE dh, uint32_t *p ) ; + /* ----- function prototypes end ----- */ #if defined( MBG_TGT_WIN32 ) + /** + * @brief Implementation of the IOCTL handler for Windows. + * + * In contrast to the POSIX variant, this IOCTL handler expects + * distinct input and output buffers. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] ioctl_code IOCTL code to be passed to the kernel driver. + * @param[in] in_p Pointer to an input buffer with the data to be passed to the kernel driver. + * @param[in] in_sz Size of the input buffer, according to the value of @p ioctl_code. + * @param[out] out_p Pointer to an output buffer to receive data from the kernel driver. + * @param[in] out_sz Size of the output buffer, according to the value of @p ioctl_code. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + */ static __mbg_inline -MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, - const void *in_p, int in_sz, void *out_p, int out_sz ) +MBGDEVIO_RET_VAL do_mbg_ioctl_win32( MBG_DEV_HANDLE dh, int ioctl_code, + const void *in_p, int in_sz, void *out_p, int out_sz ) { DWORD ReturnedLength = 0; @@ -5437,6 +5725,9 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, NULL ) ) { + // An error occurred. + // Save the system error code, and convert it to an associated + // error code of the Meinberg API. DWORD last_error = GetLastError(); int rc = mbg_win32_sys_err_to_mbg( last_error, NULL ); @@ -5446,7 +5737,7 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, // or copying the prototype here results in DLL import/export // mismatch errors. - // do not report a USB device timeout error + // Do not report a USB device timeout error. if ( rc != MBG_ERR_USB_ACCESS ) mbgsvctl_log_mbgdevio_error( ioctl_code, rc ); #endif @@ -5456,23 +5747,33 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, return MBG_SUCCESS; -} // do_mbg_ioctl +} // do_mbg_ioctl_win32 #define _do_mbg_ioctl( _dh, _ioctl, _p, _in_sz, _out_sz ) \ - do_mbg_ioctl( _dh, _ioctl, (LPVOID) _p, _in_sz, (LPVOID) _p, _out_sz ) + do_mbg_ioctl_win32( _dh, _ioctl, (LPVOID) _p, _in_sz, (LPVOID) _p, _out_sz ) #elif defined( MBG_HAS_POSIX_IOCTL ) - // In case of an error ioctl returns -1, and errno has been set - // to a *positive* POSIX error code. - + /** + * @brief Implementation of the IOCTL handler for POSIX systems. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] ioctl_code IOCTL code to be passed to the kernel driver. + * @param[in,out] p Pointer to an input or output buffer, depending on @p ioctl_code. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + */ static __mbg_inline - MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, unsigned long ioctl_code, const void *p ) + MBGDEVIO_RET_VAL do_mbg_ioctl_posix( MBG_DEV_HANDLE dh, unsigned long ioctl_code, const void *p ) { int sys_rc = ioctl( dh, ioctl_code, (void *) p ); - if ( sys_rc == -1 ) // error + // In case of an error, ioctl returns -1, and errno has been set + // to a *positive* POSIX error code as specified in errno.h. + if ( sys_rc == -1 ) { + // Save the system error code, and convert it to an associated + // error code of the Meinberg API. int sys_errno = errno; int rc = mbg_posix_errno_to_mbg( sys_errno, NULL ); @@ -5487,10 +5788,11 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, } return MBG_SUCCESS; - } + + } // do_mbg_ioctl_posix #define _do_mbg_ioctl( _dh, _ioctl, _p, _in_sz, _out_sz ) \ - do_mbg_ioctl( _dh, _ioctl, _p ) + do_mbg_ioctl_posix( _dh, _ioctl, _p ) #endif @@ -5504,21 +5806,21 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, /** * @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_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 + * @param[in] dh Valid handle to a Meinberg device. + * @param[in] info Additional information for the kernel driver depending on + * the IOCTL code, i.e. the low level function to be called: + * - One of the PCPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}. + * - One of the PC_GPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}_GPS. + * - One of the PCPS_GEN_IO_... enumeration codes with ::IOCTL_PCPS_GENERIC_IO. + * @param[in] 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] in_p Pointer to an input buffer passed to the driver, can be @a NULL. + * @param[in] in_sz Size of the input buffer, can be 0 if no buffer is used. + * @param[out] out_p Pointer to an output buffer passed to the driver, can be @a NULL. + * @param[in] 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. + * @return ::MBG_SUCCESS or error code returned by device I/O control function. */ static __mbg_inline int mbgdevio_do_gen_io( MBG_DEV_HANDLE dh, int info, unsigned int ioctl_code, @@ -5719,7 +6021,7 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, #if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX ) // NOTE -// For some reason the code below causes an internal compiler error +// For some reason, the code below causes an internal compiler error // with Borland C++Builder 5.0 release builds. Since we don't need // this function in the BC5 projects anyway we simply exclude it // from build. @@ -5737,12 +6039,12 @@ void mbg_chk_tstamp64_leap_sec( uint64_t *tstamp64, PCPS_TIME_STATUS_X *status ) if ( mbg_rc_is_success( rc ) ) { - // Handle leap second and status + // Handle leap second and status. if ( tm.tm_hour == 0 && tm.tm_min == 0 && tm.tm_sec == 0 ) { if ( *status & PCPS_LS_ANN ) { - // Set leap second enabled flag on rollover to the leap second and clear announce flag + // Set leap second enabled flag on rollover to the leap second and clear announce flag. *status &= ~PCPS_LS_ANN; *status |= PCPS_LS_ENB; @@ -5751,7 +6053,7 @@ void mbg_chk_tstamp64_leap_sec( uint64_t *tstamp64, PCPS_TIME_STATUS_X *status ) *tstamp64 -= MBG_FRAC32_UNITS_PER_SEC; } else - if ( *status & PCPS_LS_ENB ) // Clear bits when leap second expires and 0:00:00 UTC is reached + if ( *status & PCPS_LS_ENB ) // Clear bits when leap second expires and 0:00:00 UTC is reached. *status &= ~( PCPS_LS_ANN | PCPS_LS_ENB ); } } @@ -5766,35 +6068,15 @@ void mbg_chk_tstamp64_leap_sec( uint64_t *tstamp64, PCPS_TIME_STATUS_X *status ) static __mbg_inline -void mbg_init_pc_cycles_frequency( MBG_DEV_HANDLE dh, MBG_PC_CYCLES_FREQUENCY *p ) +int mbg_init_pc_cycles_frequency( MBG_DEV_HANDLE dh ) { - if ( *p == 0 ) - mbg_get_default_cycles_frequency_from_dev( dh, p ); - -} // mbg_init_pc_cycles_frequency - + if ( mbg_pc_cycles_frequency == 0 ) + return mbg_get_default_cycles_frequency_from_dev( dh, &mbg_pc_cycles_frequency ); + return MBG_SUCCESS; -#if MBG_TGT_HAS_64BIT_TYPES - -static __mbg_inline -uint64_t pcps_time_stamp_to_uint64( const PCPS_TIME_STAMP *ts ) -{ - return ( ( (uint64_t) ts->sec ) << 32 ) + ts->frac; - -} // pcps_time_stamp_to_uint64 - - - -static __mbg_inline -void uint64_to_pcps_time_stamp( PCPS_TIME_STAMP *ts, uint64_t n ) -{ - ts->sec = (uint32_t) ( n >> 32 ); - ts->frac = (uint32_t) ( n & 0xFFFFFFFFUL ); - -} // uint64_to_pcps_time_stamp +} // mbg_init_pc_cycles_frequency -#endif #ifdef __cplusplus @@ -5802,7 +6084,7 @@ void uint64_to_pcps_time_stamp( PCPS_TIME_STAMP *ts, uint64_t n ) #endif #if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment + #pragma pack() // Set default alignment. #undef _USING_BYTE_ALIGNMENT #endif @@ -5811,6 +6093,7 @@ void uint64_to_pcps_time_stamp( PCPS_TIME_STAMP *ts, uint64_t n ) #undef _ext #undef _DO_INIT +#undef _MBG_API_ATTR_VAR #endif /* _MBGDEVIO_H */ diff --git a/mbglib/common/mbgerror.c b/mbglib/common/mbgerror.c index 34673c8..2c4be21 100644 --- a/mbglib/common/mbgerror.c +++ b/mbglib/common/mbgerror.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgerror.c 1.7 2019/04/03 12:53:55Z martin REL_M $ + * $Id: mbgerror.c 1.12 2021/03/16 12:20:57Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,17 @@ * * ----------------------------------------------------------------------- * $Log: mbgerror.c $ - * Revision 1.7 2019/04/03 12:53:55Z martin + * Revision 1.12 2021/03/16 12:20:57Z martin + * Updated some comments. + * Revision 1.11 2021/03/12 12:32:15 martin + * Updated some comments. + * Revision 1.10 2019/11/11 09:43:41 martin + * Tiny doxygen change. + * Revision 1.9 2019/08/26 15:15:10 martin + * Translate POSIX ENODATA to MBG_ERR_NO_DATA. + * Revision 1.8 2019/08/20 08:22:51 martin + * Translate win32 ERROR_FILE_NOT_FOUND to MBG_ERR_NO_ENTITY. + * Revision 1.7 2019/04/03 12:53:55 martin * Use new code MBG_ERR_BAD_ADDR. * Revision 1.6 2018/11/22 14:47:15 martin * Support QNX target. @@ -158,7 +168,7 @@ typedef struct #if defined( _MBG_TGT_HAS_POSIX_ERRNO ) /** - * @brief Mappings between Meinberg error codes and POSIX error codes + * @brief Mappings between Meinberg error codes and POSIX error codes. * * Always refer to the symbolic names only. The numeric codes listed * in the comments below are just for a quick reference, and may vary @@ -186,7 +196,7 @@ static ERRNO_CNV_ENTRY posix_errno_table[] = { ENOMEM, MBG_ERR_NO_MEM }, // 12, Out of memory (can't allocate memory). { EACCES, MBG_ERR_ACCESS }, // 13, Permission denied (e.g. when trying to access a device without sufficient permissions). { EFAULT, MBG_ERR_BAD_ADDRESS }, // 14, Bad address (e.g. invalid address in a function argument). - // { ENOTBLK, }, // 15, Block device required (eventually no POSIX error, but supported in Linux and *BSD). + // { ENOTBLK, }, // 15, Block device required (possibly not a POSIX error, but supported on Linux and *BSD). { EBUSY, MBG_ERR_BUSY }, // 16, Device or resource busy. { EEXIST, MBG_ERR_EXIST }, // 17, File exists. // { EXDEV, }, // 18, Cross-device link. @@ -206,6 +216,9 @@ static ERRNO_CNV_ENTRY posix_errno_table[] = // { EPIPE, }, // 32, Broken pipe (writing to a socket, pipe, or FIFO which has no process to read the data). // { EDOM, }, // 33, Math argument out of domain of function. { ERANGE, MBG_ERR_RANGE }, // 34, Math result too large or too small (not representable). +#if defined( ENODATA ) + { ENODATA, MBG_ERR_NO_DATA }, // 61, No (more) data. +#endif #if defined( ETIME ) { ETIME, MBG_ERR_TIMER }, // 62, Timer expired (e.g. stream timeout on USB disconnect). #endif @@ -216,10 +229,10 @@ static ERRNO_CNV_ENTRY posix_errno_table[] = { ENOTSOCK, MBG_ERR_NOT_A_SOCKET }, // 88, Socket operation on non-socket (file descriptor is not a socket). #endif #if defined( ECONNRESET ) - { ECONNRESET, MBG_ERR_CONN_RESET }, // 104, Connection reset by peer + { ECONNRESET, MBG_ERR_CONN_RESET }, // 104, Connection reset by peer. #endif #if defined( ETIMEDOUT ) - { ETIMEDOUT, MBG_ERR_TIMEOUT }, // 110, Connection timed out + { ETIMEDOUT, MBG_ERR_TIMEOUT }, // 110, Connection timed out. #endif { 0, 0 } // end-of-table identifier @@ -234,10 +247,10 @@ static ERRNO_CNV_ENTRY posix_errno_table[] = static ERRNO_CNV_ENTRY posix_h_errno_table[] = { // POSIX codes taken from Linux netdb.h - { HOST_NOT_FOUND, MBG_ERR_HOST_NOT_FOUND }, // The specified host is unknown - // { NO_ADDRESS, }, // Usually same numeric value as NO_DATA - // { NO_DATA, }, // The requested name is valid but does not have an IP address - // { NO_RECOVERY, }, // A nonrecoverable name server error occurred + { HOST_NOT_FOUND, MBG_ERR_HOST_NOT_FOUND }, // The specified host is unknown. + // { NO_ADDRESS, }, // Usually same numeric value as NO_DATA. + // { NO_DATA, }, // The requested name is valid but does not have an IP address. + // { NO_RECOVERY, }, // A nonrecoverable name server error occurred. // { TRY_AGAIN, }, // A temporary error occurred on an authoritative name server. Try again later. { 0, 0 } // end-of-table identifier @@ -313,7 +326,7 @@ static ERRNO_CNV_ENTRY cvi_rs232_error_table[] = #if defined( MBG_TGT_KERNEL ) /** - * @brief Mappings of some NTSTATUS codes to Meinberg error codes + * @brief Mappings of some NTSTATUS codes to Meinberg error codes. * * Kernel space Windows APIs use NTSTATUS codes as return values, * which consist of several bit fields which also provide some severity @@ -403,8 +416,8 @@ static ERRNO_CNV_ENTRY win32_kernel_status_table[] = * - The user space function uses ::win32_sys_err_table to convert this * to a Meinberg error code, which again yields ::MBG_ERR_INV_PARM. * - * @note Eventually it would be possible to defined custom NTSTATUS codes - * in kernel space, e.g. ((NTSTATUS) (0xC0000000 | 0x20000000 | 31)). + * @note It is possible to define custom NTSTATUS codes in kernel space, + * e.g. ((NTSTATUS) (0xC0000000 | 0x20000000 | 31)). * Apparently, such custom error status codes are passed up to user space, * and GetLastError() after the ioctl() call then returns a negative number, * i.e. -31 for the example here. @@ -437,7 +450,7 @@ static ERRNO_CNV_ENTRY mbg_ioctl_to_ntstatus_table[] = #else // Windows user space /** - * @brief Mappings of WIN32 error codes to Meinberg error codes + * @brief Mappings of WIN32 error codes to Meinberg error codes. * * If a WIN32 user space API function encounters an error, * the Windows GetLastError() function has to be called in @@ -461,6 +474,7 @@ static ERRNO_CNV_ENTRY mbg_ioctl_to_ntstatus_table[] = static ERRNO_CNV_ENTRY win32_sys_err_table[] = { // Mappings for some Windows error codes defined in WinError.h + { ERROR_FILE_NOT_FOUND, MBG_ERR_NO_ENTITY }, // 2L: The system cannot find the file specified. { ERROR_PATH_NOT_FOUND, MBG_ERR_NO_ENTITY }, // 3L: The system cannot find the path specified. { ERROR_ACCESS_DENIED, MBG_ERR_ACCESS }, // 5L: Access is denied. { ERROR_INVALID_HANDLE, MBG_ERR_INV_HANDLE }, // 6L: The handle is invalid. @@ -492,7 +506,7 @@ static ERRNO_CNV_ENTRY win32_sys_err_table[] = /** - * @brief Mappings of Winsock error codes to Meinberg error codes + * @brief Mappings of Winsock error codes to Meinberg error codes. * * If a Windows socket (Winsock) function encounters an error, * the Windows WSAGetLastError() function has to be called in @@ -589,10 +603,10 @@ static ERRNO_CNV_ENTRY win32_wsa_err_table[] = static /*HDR*/ /** - * @brief Lookup some error code in a conversion table + * @brief Lookup some error code in a conversion table. * - * @param[in] srch_errno The error number to be looked up in the conversion table - * @param[in] tbl A conversion table + * @param[in] srch_errno The error number to be looked up in the conversion table. + * @param[in] tbl A conversion table. * @param[in] dflt_val The code to be returned if no table entry was found. * * @return @ref MBG_ERROR_CODES associated with the original error code, @@ -615,13 +629,13 @@ int lookup_tbl_errno( int srch_errno, const ERRNO_CNV_ENTRY tbl[], int dflt_val /*HDR*/ /** - * @brief Convert one of the @ref MBG_ERROR_CODES to an OS-specific format + * @brief Convert one of the @ref MBG_ERROR_CODES to an OS-specific format. * * @param[in] err_no One of the @ref MBG_ERROR_CODES. * * @see @ref MBG_ERROR_CODES * - * @return An OS-specific error code + * @return An OS-specific error code. */ int mbg_errno_to_os( int err_no ) { @@ -676,11 +690,12 @@ int mbg_errno_to_os( int err_no ) /*HDR*/ /** - * @brief Return an error string associated with the @ref MBG_ERROR_CODES + * @brief Return an error string associated with the @ref MBG_ERROR_CODES. * - * @param[in] mbg_errno One of the @ref MBG_ERROR_CODES + * @param[in] mbg_errno One of the @ref MBG_ERROR_CODES. * - * @return A constant string describing the error, or NULL for unknown error codes + * @return A constant string describing the error, or a generic string + * "Unknown error" for unknown error codes. */ const char *mbg_strerror( int mbg_errno ) { @@ -704,12 +719,12 @@ const char *mbg_strerror( int mbg_errno ) /*HDR*/ /** - * @brief Check if a value is an error code and print an associated error message + * @brief Check if a value is an error code and print an associated error message. * - * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES - * @param[in] what A string indicated what failed + * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES. + * @param[in] what A string indicated what failed. * - * @return true if rc represented an error code, and a message has been printed, else false + * @return @a true if @p rc represented an error code and a message has been printed, else @a false. */ bool mbg_cond_err_msg( int rc, const char *what ) { @@ -721,23 +736,22 @@ bool mbg_cond_err_msg( int rc, const char *what ) /*HDR*/ /** - * @brief Check if a value is an general or a "not supported" error code and print an associated message + * @brief Check if a value is a general or a "not supported" error code, and print an associated message. * - * If rc contains an error code then an error message is printed, and true is returned. + * If @p rc contains an error code, an error message is printed. * - * If the optional parameter string info2 is not NULL then it should contain - * the name of a feature which has been tested before. In this case, if the error - * code is the specific error ::MBG_ERR_NOT_SUPP_BY_DEV then a "not supported" message - * is printed using info2. + * If the error code is ::MBG_ERR_NOT_SUPP_BY_DEV and the optional parameter + * string @p info is not @a NULL, a specific error message is generated. * - * If info2 is NULL, or the error code is not ::MBG_ERR_NOT_SUPP_BY_DEV then the standard - * error message is printed anyway. + * If @p rc contains a different error code, or the optional parameter + * string @p info is @a NULL, a generic error message is generated that + * includes the string from parameter @p what. * - * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES - * @param[in] what A string indicated what failed - * @param[in] info An optional informational string telling what is not supported (may be NULL). + * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES. + * @param[in] what A string indicated what failed. + * @param[in] info An optional informational string telling what is not supported (may be @a NULL). * - * @return true if rc represented an error code, and a message has been printed, else false + * @return @a true if @p rc represented any error code, and a message has been printed, else @a false. */ bool mbg_cond_err_msg_info( int rc, const char *what, const char *info ) { @@ -763,12 +777,12 @@ bool mbg_cond_err_msg_info( int rc, const char *what, const char *info ) /*HDR*/ /** - * @brief Translate an error code from the Labwindows/CVI RS-232 library to one of the @ref MBG_ERROR_CODES + * @brief Translate an error code from the Labwindows/CVI RS-232 library to one of the @ref MBG_ERROR_CODES. * - * @param[in] cvi_rc An error code returned by a CVI RS-232 library function - * @param[in] info An optional informational text string, or NULL + * @param[in] cvi_rc An error code returned by a CVI RS-232 library function. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. * * @see http://zone.ni.com/reference/en-XX/help/370051V-01/cvi/libref/cvirs232_error_conditions/ */ @@ -795,12 +809,12 @@ int mbg_cvi_rs232_error_to_mbg( int cvi_rc, const char *info ) /*HDR*/ /** - * @brief Translate a Windows NTSTATUS code to one of the @ref MBG_ERROR_CODES + * @brief Translate a Windows NTSTATUS code to one of the @ref MBG_ERROR_CODES. * - * @param[in] st One of the NTSTATUS codes defined in ntstatus.h - * @param[in] info An optional informational text string, or NULL + * @param[in] st One of the NTSTATUS codes defined in ntstatus.h. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_win32_ntstatus_to_mbg( NTSTATUS st, const char *info ) { @@ -820,12 +834,12 @@ int mbg_win32_ntstatus_to_mbg( NTSTATUS st, const char *info ) /*HDR*/ /** - * @brief Translate a Windows non-socket API return code to one of the @ref MBG_RETURN_CODES + * @brief Translate a Windows non-socket API return code to one of the @ref MBG_RETURN_CODES. * - * @param[in] win32_sys_rc A Windows non-socket API error code as returned by GetLastError(), or ERROR_SUCCESS. - * @param[in] info An optional informational text string, or NULL. + * @param[in] win32_sys_rc A Windows non-socket API error code as returned by @a GetLastError, or @a ERROR_SUCCESS. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. */ int mbg_win32_sys_err_to_mbg( DWORD win32_sys_rc, const char *info ) { @@ -850,9 +864,9 @@ int mbg_win32_sys_err_to_mbg( DWORD win32_sys_rc, const char *info ) if ( rc < 0 ) { - // If the error code is negative then this is a user-defined - // error code e.g. returned by an IOCTL call. In this case we - // assume it's one of the + // If the error code is negative, this is a user-defined + // error code e.g. returned by an IOCTL call. In this case + // we assume it's one of the ... goto out; } #endif @@ -877,12 +891,12 @@ out: /*HDR*/ /** - * @brief Translate a Windows socket API error code to one of the @ref MBG_ERROR_CODES + * @brief Translate a Windows socket API error code to one of the @ref MBG_ERROR_CODES. * - * @param[in] wsa_err A Windows socket API error code as returned by WSAGetLastError() - * @param[in] info An optional informational text string, or NULL + * @param[in] wsa_err A Windows socket API error code as returned by @a WSAGetLastError. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_win32_wsa_err_to_mbg( int wsa_err, const char *info ) { @@ -910,12 +924,12 @@ int mbg_win32_wsa_err_to_mbg( int wsa_err, const char *info ) /*HDR*/ /** - * @brief Translate a POSIX errno error code to one of the @ref MBG_ERROR_CODES + * @brief Translate a POSIX errno error code to one of the @ref MBG_ERROR_CODES. * - * @param[in] posix_errno A POSIX error code as usually defined in errno.h - * @param[in] info An optional informational text string, or NULL + * @param[in] posix_errno A POSIX error code as usually defined in errno.h. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_posix_errno_to_mbg( int posix_errno, const char *info ) { @@ -939,19 +953,19 @@ int mbg_posix_errno_to_mbg( int posix_errno, const char *info ) /*HDR*/ /** - * @brief Translate a POSIX h_errno error code to one of the @ref MBG_ERROR_CODES + * @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. + * @a gethostbyname and @a gethostbyaddr. In case of error these functions + * don't set @a errno but @a h_errno to a specific value. * - * The functions gethostbyname() and gethostbyaddr() are obsolete, - * and getaddressinfo() should be used preferably. + * The functions @a gethostbyname and @a gethostbyaddr are obsolete, + * and @a getaddressinfo should be used preferably. * - * @param[in] posix_h_errno An error code as usually defined in netdb.h - * @param[in] info An optional informational text string, or NULL + * @param[in] posix_h_errno An error code as usually defined in netdb.h. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_posix_h_errno_to_mbg( int posix_h_errno, const char *info ) { @@ -975,26 +989,26 @@ int mbg_posix_h_errno_to_mbg( int posix_h_errno, const char *info ) /*HDR*/ /** - * @brief Get and translate last error after non-socket function call + * @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" + * On POSIX systems the "last error" code is always stored in @a errno, but + * e.g. on Windows the "last error" code after a socket function + * has to be retrieved by calling @a WSAGetLastError, whereas the "last error" * code from non-socket POSIX-like functions has to be retrieved - * by calling GetLastError(). + * by calling @a GetLastError. * - * @param[in] info An optional informational text string, or NULL + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_get_last_error( const char *info ) { #if defined( MBG_TGT_WIN32 ) - // Under Windows the "last error" code after a non-socket function + // On Windows the "last error" code after a non-socket function // ("Windows System Errors") has to be retrieved by calling GetLastError(), // whereas the "last error" code from POSIX-like socket functions // ("Windows Sockets Error Codes") has to be retrieved by calling @@ -1021,19 +1035,19 @@ int mbg_get_last_error( const char *info ) /*HDR*/ /** - * @brief Get and translate last error after socket function call + * @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. + * On POSIX systems the "last error" code is always stored in @a errno, but + * e.g. on Windows the "last error" code after a socket function + * has to be retrieved by calling @a WSAGetLastError, whereas the "last error" + * code from non-socket POSIX-like functions is stored in @a errno as usual. * - * @param[in] info An optional informational text string, or NULL + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_get_last_socket_error( const char *info ) { @@ -1045,7 +1059,7 @@ int mbg_get_last_socket_error( const char *info ) #elif defined( MBG_TGT_WIN32 ) #if !defined( MBG_TGT_KERNEL ) - // Under Windows the "last error" code after a POSIX-like socket + // On Windows the "last error" code after a POSIX-like socket // function ("Windows Sockets Error Code") has to be retrieved // by calling WSAGetLastError(), whereas the "last error" code // after a non-socket function ("Windows System Errors") has @@ -1072,20 +1086,20 @@ int mbg_get_last_socket_error( const char *info ) /*HDR*/ /** - * @brief Retrieve and convert last error after gethostbyname() + * @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() + * returned by @a gethostbyname and @a gethostbyaddr. In case of error + * these functions don't set @a errno but @a h_errno on POSIX systems, + * but on Windows the error code can be retrieved by @a WSAGetLastError * as usual. * - * The functions gethostbyname() and gethostbyaddr() are obsolete, - * and getaddressinfo() should be used preferably. + * The functions @a gethostbyname and @a gethostbyaddr are obsolete, + * and @a getaddressinfo should be used preferably. * - * @param[in] info An optional informational text string, or NULL + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_get_gethostbyname_error( const char *info ) { @@ -1157,14 +1171,14 @@ int mbg_gai_error( int rc, const char *info ) /*HDR*/ /** - * @brief Retrieve and convert last zlib internal error code + * @brief Retrieve and convert last zlib internal error code. * - * @param[in] zlib_error zlib internal error code - * @param[in] info An optional informational text string, or NULL - * @param[in] msg An optional zlib specific error msg, or NULL. - * Struct z_stream contains member msg. + * @param[in] zlib_error zlib internal error code. + * @param[in] info An optional informational text string, or @a NULL. + * @param[in] msg An optional zlib specific error msg, or @a NULL. + * Struct @a z_stream contains member msg. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_zlib_error_to_mbg( int zlib_error, const char *info, const char *msg ) { diff --git a/mbglib/common/mbgerror.h b/mbglib/common/mbgerror.h index 817995a..fada6d3 100644 --- a/mbglib/common/mbgerror.h +++ b/mbglib/common/mbgerror.h @@ -1,17 +1,44 @@ /************************************************************************** * - * $Id: mbgerror.h 1.21 2019/03/13 16:17:10Z martin REL_M $ + * $Id: mbgerror.h 1.33 2021/11/03 16:57:02Z martin.burnicki REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * * Description: - * Error codes used with Meinberg devices and drivers. - * The codes can be translated into an OS dependent error code. + * Common error codes used with Meinberg API calls. + * OS-specific error codes can be translated into these codes. * * ----------------------------------------------------------------------- * $Log: mbgerror.h $ - * Revision 1.21 2019/03/13 16:17:10Z martin + * Revision 1.33 2021/11/03 16:57:02Z martin.burnicki + * Added MBG_ERR_NOT_SUPP_BY_DRVR. + * Revision 1.32 2021/04/13 08:27:01 martin + * Updated some comments. + * Revision 1.31 2021/03/16 12:21:53 martin + * Updated some comments. + * Revision 1.30 2021/03/12 12:32:05 martin + * Updated some comments. + * Revision 1.29 2020/05/27 11:30:40 martin + * New NTP exit codes MBG_NTP_EXIT_FAIL_MEM and MBG_NTP_EXIT_FAIL_CRYPTO_API. + * Revision 1.28 2020/05/25 20:52:12 martin + * New NTP exit code MBG_NTP_EXIT_FAIL_TIMEOUT. + * Revision 1.27 2019/12/02 09:26:17 philipp + * Added MBG_ERR_NAME error code + * Revision 1.26 2019/11/11 10:10:10 martin + * Moved exit codes here that are used by NTP tools. + * Should be merged with other exit codes later. + * Revision 1.25 2019/10/09 09:31:04 philipp + * Added MBG_ERR_INV_USER and MBG_ERR_INV_GROUP + * Revision 1.24 2019/08/28 08:02:56 philipp + * Added error code MBG_ERR_IN_PROGRESS + * Revision 1.23 2019/08/26 15:14:34 martin + * Modified msg. text for MBG_ERR_NO_DATA. + * Revision 1.22 2019/08/20 08:20:04 martin + * Fixed build using mingw. + * Changed message text for MBG_ERR_ACCESS, which may also indicate that + * an exclusive resource is in use, not only that permissions are missing. + * Revision 1.21 2019/03/13 16:17:10 martin * New code MBG_ERR_BAD_ADDRESS (for EFAULT). * Revision 1.20 2019/03/13 09:44:30 martin * Moved predefined program exit codes here. @@ -42,7 +69,7 @@ * Changed message text for MBG_ERR_NO_ENTITY. * Replaced old _mbg_err_to_os() macro by new inline functions * mbg_errno_to_os() and mbg_ret_val_to_os(). - * Fixed build under Windows. + * Fixed build on Windows. * Updated doxygen comments. * Updated function prototypes. * Revision 1.14 2017/05/10 15:21:39 martin @@ -105,21 +132,27 @@ #if defined( MBG_TGT_KERNEL ) - #define MBG_TGT_MISSING_DWORD 1 // missing even in kernel space. - #define MBG_TGT_MISSING_NTSTATUS 0 // available in kernel space + #define MBG_TGT_MISSING_DWORD 1 // Missing even in kernel space. + #define MBG_TGT_MISSING_NTSTATUS 0 // Available in kernel space #else // Windows user space - #define MBG_TGT_MISSING_DWORD 0 // available in user space + #define MBG_TGT_MISSING_DWORD 0 // Available in user space. // Some (but not all) Windows build environments provide a // bcrypt.h file which has a definition for NTSTATUS, so we - // use.that if available to avoid duplicate / mismatching + // use that if available to avoid duplicate / mismatching // definitions in case an application uses bcrypt.h anyway. - #if !defined( MBG_TGT_HAS_BCRYPT_H ) // unless already defined elsewhere - #if defined( _MSC_VER ) && ( _MSC_VER >= 1500 ) // at least VS2008 has it + #if !defined( MBG_TGT_HAS_BCRYPT_H ) // Unless already defined elsewhere. + #if defined( _MSC_VER ) && ( _MSC_VER >= 1500 ) // At least VS2008 has it. #define MBG_TGT_HAS_BCRYPT_H 1 - #else // older MSVC versions or other build environments may not have it + #endif + + #if defined( MBG_TGT_MINGW ) // Mingw has it, too. + #define MBG_TGT_HAS_BCRYPT_H 1 + #endif + + #if !defined( MBG_TGT_HAS_BCRYPT_H ) // Other build environments may not have it. #define MBG_TGT_HAS_BCRYPT_H 0 #endif #endif @@ -133,7 +166,7 @@ #endif -#else // non-Windows targets +#else // Non-Windows targets. #define MBG_TGT_MISSING_DWORD 1 #define MBG_TGT_MISSING_NTSTATUS 1 @@ -234,16 +267,16 @@ extern "C" { /** - * @brief Error codes used with Meinberg devices and drivers + * @defgroup MBG_RETURN_CODES Return codes used with Meinberg devices and drivers * * Appropriate error strings can be retrieved via the ::mbg_strerror function. * * @see ::MBG_ERR_STR_TABLE_ENG * - * @anchor MBG_RETURN_CODES @{ */ + * @{ */ -/* ### TODO FIXME - * Under Windows, some message strings are provided as resources appended +/* FIXME TODO + * On Windows, some message strings are provided as resources appended * to the mbgctrl DLL, but the codes specified here have to be translated * to Windows-specific message IDs before the appropriate resource string * can be retrieved. Actually this is done by taking the absolute number @@ -256,16 +289,20 @@ extern "C" { // and returned by the firmware of bus-level devices, so the definitions // must *not* be renumbered. -#define MBG_SUCCESS 0 ///< No error, has to match ::PCPS_SUCCESS +#define MBG_SUCCESS 0 ///< No error, has to match ::PCPS_SUCCESS. + - /** @anchor MBG_ERROR_CODES @{ */ +/** + * @defgroup MBG_ERROR_CODES Error codes used with Meinberg devices and drivers + * + * @{ */ -// Other codes which have to match codes defined in pcpsdefs.h returned by bus-level devices -#define MBG_ERR_STIME -1 ///< Tried to write invalid date/time/status to device, has to match ::PCPS_ERR_STIME -#define MBG_ERR_CFG -2 ///< Tried to write invalid configuration parameters to device, has to match ::PCPS_ERR_CFG (see also ::MBG_ERR_INV_CFG) +// Other codes which have to match codes defined in pcpsdefs.h returned by bus-level devices. +#define MBG_ERR_STIME -1 ///< Tried to write invalid date/time/status to device, has to match ::PCPS_ERR_STIME. +#define MBG_ERR_CFG -2 ///< Tried to write invalid configuration parameters to device, has to match ::PCPS_ERR_CFG (see also ::MBG_ERR_INV_CFG). -// Codes returned by low level functions of the bus-level device driver +// 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. @@ -273,7 +310,7 @@ extern "C" { ///< match the number of bytes expected by the device. #define MBG_ERR_INV_TIME -23 ///< The device has no valid time. -#define MBG_ERR_NO_DATA -24 ///< The device's data output data buffer is empty, though it shouldn't be. +#define MBG_ERR_NO_DATA -24 ///< No (more) data to process, e.g. FIFO empty. #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. @@ -284,12 +321,12 @@ extern "C" { #define MBG_ERR_DEV_NOT_SUPP -29 ///< 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 ///< Command or feature not supported by device. -// #define MBG_ERR_USB_ACCESS -32 ///< USB access failed (FIXME TODO this is B.S., we should return *why*) +// #define MBG_ERR_USB_ACCESS -32 ///< USB access failed (TODO This is B.S., we should return ***why***). #define MBG_ERR_CYCLIC_TIMEOUT -33 ///< Cyclic event (IRQ, etc.) didn't occur in time. #define MBG_ERR_NOT_SUPP_ON_OS -34 ///< Function is not supported on this operating system. #define MBG_ERR_LIB_NOT_COMPATIBLE -35 ///< Installed shared library version not compatible 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_N_COM_EXCEEDS_SUPP -36 ///< Number of COM ports of the device exceeds max. supported by driver. +#define MBG_ERR_N_STR_EXCEEDS_SUPP -37 ///< Number of 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. @@ -333,8 +370,8 @@ extern "C" { #define MBG_ERR_OVERFLOW -77 ///< range or buffer overflow #define MBG_ERR_PIPE -78 ///< pipe error #define MBG_ERR_INTR -79 ///< interrupted function call -#define MBG_ERR_ACCESS -80 ///< Access denied, e.g. when trying to access a file or device without sufficient permissions -#define MBG_ERR_PERM -81 ///< Operation not permitted, e.g. when trying to set the system time without sufficient permissions +#define MBG_ERR_ACCESS -80 ///< Access denied, e.g. to an object that is already in use, or in case of insufficient permissions. +#define MBG_ERR_PERM -81 ///< Operation not permitted, e.g. when trying to set the system time without sufficient permissions. #define MBG_ERR_BUSY -82 ///< Device or resource busy, can't be used #define MBG_ERR_INV_HANDLE -83 ///< invalid file/device handle specified @@ -387,6 +424,13 @@ extern "C" { #define MBG_ERR_STR_SUBSTR -118 ///< Invalid substring in string #define MBG_ERR_BAD_ADDRESS -119 ///< Bad Address (like POSIX EFAULT) +#define MBG_ERR_IN_PROGRESS -120 ///< Long lasting operation in progress +#define MBG_ERR_INV_USER -121 ///< Invalid user +#define MBG_ERR_INV_GROUP -122 ///< Invalid group +#define MBG_ERR_NAME -123 ///< Invalid name + +#define MBG_ERR_NOT_SUPP_BY_DRVR -124 ///< Requested feature is not supported by the driver + // NOTE: New codes have to be appended to this list, and the sequence of codes must not // be changed. Whenever new codes have been defined, appropriate entries have to be added // to the ::MBG_ERR_STR_TABLE_ENG table initializer below, and the Windows-specific message @@ -425,7 +469,7 @@ extern "C" { { MBG_ERR_FW_ID, "Invalid firmware ID" }, \ { MBG_ERR_NBYTES, "Unexpected number of data bytes for this API" }, \ { MBG_ERR_INV_TIME, "The device has no valid time" }, \ - { MBG_ERR_NO_DATA, "The device's data buffer unexpectedly empty" }, \ + { MBG_ERR_NO_DATA, "No (more) data to process" }, \ { MBG_ERR_NOT_READY, "Device not ready" }, \ { MBG_ERR_INV_TYPE, "Unsupported data type" }, \ { MBG_ERR_NO_MEM, "Memory allocation error" }, \ @@ -489,7 +533,12 @@ extern "C" { { MBG_ERR_RSRC_ITEM, "Too many resource items" }, \ { MBG_ERR_BUFFER_TOO_SMALL, "Data buffer too small" }, \ { MBG_ERR_OUTDATED, "Software/Module is too old/outdated. Please update!" }, \ - { MBG_ERR_STR_SUBSTR, "Invalid substring in string" } + { MBG_ERR_STR_SUBSTR, "Invalid substring in string" }, \ + { MBG_ERR_IN_PROGRESS, "Long lasting operation in progress" }, \ + { MBG_ERR_INV_USER, "Invalid user" }, \ + { MBG_ERR_INV_GROUP, "Invalid group" }, \ + { MBG_ERR_NAME, "Invalid name" }, \ + { MBG_ERR_NOT_SUPP_BY_DRVR, "Not supported by the driver" } /** @@ -527,7 +576,7 @@ extern "C" { { MBG_ERR_NBLOCK_WAIT_WR_FD, "Write file descriptor not ready after waiting for port ready" }, \ { MBG_ERR_PIPE, "Pipe error" }, \ { MBG_ERR_INTR, "Interrupted function call" }, \ - { MBG_ERR_ACCESS, "Access denied, insufficient permission" }, \ + { MBG_ERR_ACCESS, "Access denied" }, \ { MBG_ERR_PERM, "Operation not permitted, insufficient rights" }, \ { MBG_ERR_EXIST, "File exists" }, \ { MBG_ERR_NO_ENTITY, "No such file or directory" }, \ @@ -625,6 +674,11 @@ bool mbg_rc_is_success_or_err_perm( int rc ) /** * @brief Predefined exit codes returned by some tools. + * + * Should be merged with ::MBG_NTP_EXIT_CODES. + * + * @see ::MBG_NTP_EXIT_CODES + * @see ::MBG_NTP_EXIT_CODE_STRS */ enum MBG_EXIT_CODES { @@ -638,193 +692,248 @@ enum MBG_EXIT_CODES +/** + * @brief Predefined exit codes returned by some NTP tools. + * + * Should be merged with ::MBG_EXIT_CODES. + * + * @see ::MBG_NTP_EXIT_CODE_STRS + * @see ::MBG_EXIT_CODES + */ +enum MBG_NTP_EXIT_CODES +{ + MBG_NTP_EXIT_SUCCESS, // Success. + MBG_NTP_EXIT_FAIL_USAGE, // Usage printed, invalid parameter? + MBG_NTP_EXIT_FAIL_GENERIC, // General failure, unspecified. + MBG_NTP_EXIT_FAIL_DNS, // Host name lookup failed. + MBG_NTP_EXIT_FAIL_SOCKET, // Failed to open socket. + MBG_NTP_EXIT_FAIL_SEND, // Failed to send packet. + MBG_NTP_EXIT_FAIL_RECEIVE, // Failed to receive packet. + MBG_NTP_EXIT_FAIL_ENCRYPT, // Failed to encrypt a packet. + MBG_NTP_EXIT_FAIL_DECRYPT, // Failed to decrypt an encrypted packet. + MBG_NTP_EXIT_FAIL_CRYPT_NACK, // Failed because received a crypto NACK. + MBG_NTP_EXIT_FAIL_BIND, // Failed to bind to specific address or port. + MBG_NTP_EXIT_FAIL_TIMEOUT, // Timeout that shouldn't occur unless running at full speed. + MBG_NTP_EXIT_FAIL_MEM, // Out of memory. + MBG_NTP_EXIT_FAIL_CRYPTO_API, // Some crypto API call failed for unspecified reason. + N_MBG_NTP_EXIT_CODES +}; + + +/** + * @brief Info strings associated with predefined NTP tool exit codes. + * + * Should be merged with ::MBG_EXIT_CODES. + * + * @see ::MBG_NTP_EXIT_CODES + */ + +#define MBG_NTP_EXIT_CODE_STRS \ +{ \ + "Success", /* MBG_NTP_EXIT_OK */ \ + "Usage printed, e.g. invalid parameter.", /* MBG_NTP_EXIT_FAIL_USAGE */ \ + "Unspecified error.", /* MBG_NTP_EXIT_FAIL_GENERIC */ \ + "Host name lookup failed.", /* MBG_NTP_EXIT_FAIL_DNS */ \ + "Failed to open socket.", /* MBG_NTP_EXIT_FAIL_SOCKET */ \ + "Failed to send packet.", /* MBG_NTP_EXIT_FAIL_SEND */ \ + "Failed to receive packet.", /* MBG_NTP_EXIT_FAIL_RECEIVE */ \ + "Failed to encrypt a packet.", /* MBG_NTP_EXIT_FAIL_ENCRYPT */ \ + "Failed to decrypt an encrypted packet.", /* MBG_NTP_EXIT_FAIL_DECRYPT */ \ + "Received a crypto NACK.", /* MBG_NTP_EXIT_FAIL_CRYPT_NACK */ \ + "Failed to bind to specific address or port.", /* MBG_NTP_EXIT_FAIL_BIND */ \ + "Timeout.", /* MBG_NTP_EXIT_FAIL_TIMEOUT */ \ + "Unspecified crypto API error." /* MBG_NTP_EXIT_FAIL_CRYPTO_API */ \ +} + + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ /** - * @brief Convert one of the @ref MBG_ERROR_CODES to an OS-specific format + * @brief Convert one of the @ref MBG_ERROR_CODES to an OS-specific format. * * @param[in] err_no One of the @ref MBG_ERROR_CODES. * * @see @ref MBG_ERROR_CODES * - * @return An OS-specific error code + * @return An OS-specific error code. */ int mbg_errno_to_os( int err_no ) ; /** - * @brief Return an error string associated with the @ref MBG_ERROR_CODES + * @brief Return an error string associated with the @ref MBG_ERROR_CODES. * - * @param[in] mbg_errno One of the @ref MBG_ERROR_CODES + * @param[in] mbg_errno One of the @ref MBG_ERROR_CODES. * - * @return A constant string describing the error, or NULL for unknown error codes + * @return A constant string describing the error, or a generic string + * "Unknown error" for unknown error codes. */ const char *mbg_strerror( int mbg_errno ) ; /** - * @brief Check if a value is an error code and print an associated error message + * @brief Check if a value is an error code and print an associated error message. * - * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES - * @param[in] what A string indicated what failed + * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES. + * @param[in] what A string indicated what failed. * - * @return true if rc represented an error code, and a message has been printed, else false + * @return @a true if @p rc represented an error code and a message has been printed, else @a false. */ bool mbg_cond_err_msg( int rc, const char *what ) ; /** - * @brief Check if a value is an general or a "not supported" error code and print an associated message + * @brief Check if a value is a general or a "not supported" error code, and print an associated message. * - * If rc contains an error code then an error message is printed, and true is returned. + * If @p rc contains an error code, an error message is printed. * - * If the optional parameter string info2 is not NULL then it should contain - * the name of a feature which has been tested before. In this case, if the error - * code is the specific error ::MBG_ERR_NOT_SUPP_BY_DEV then a "not supported" message - * is printed using info2. + * If the error code is ::MBG_ERR_NOT_SUPP_BY_DEV and the optional parameter + * string @p info is not @a NULL, a specific error message is generated. * - * If info2 is NULL, or the error code is not ::MBG_ERR_NOT_SUPP_BY_DEV then the standard - * error message is printed anyway. + * If @p rc contains a different error code, or the optional parameter + * string @p info is @a NULL, a generic error message is generated that + * includes the string from parameter @p what. * - * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES - * @param[in] what A string indicated what failed - * @param[in] info An optional informational string telling what is not supported (may be NULL). + * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES. + * @param[in] what A string indicated what failed. + * @param[in] info An optional informational string telling what is not supported (may be @a NULL). * - * @return true if rc represented an error code, and a message has been printed, else false + * @return @a true if @p rc represented any error code, and a message has been printed, else @a false. */ bool mbg_cond_err_msg_info( int rc, const char *what, const char *info ) ; /** - * @brief Translate an error code from the Labwindows/CVI RS-232 library to one of the @ref MBG_ERROR_CODES + * @brief Translate an error code from the Labwindows/CVI RS-232 library to one of the @ref MBG_ERROR_CODES. * - * @param[in] cvi_rc An error code returned by a CVI RS-232 library function - * @param[in] info An optional informational text string, or NULL + * @param[in] cvi_rc An error code returned by a CVI RS-232 library function. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. * * @see http://zone.ni.com/reference/en-XX/help/370051V-01/cvi/libref/cvirs232_error_conditions/ */ int mbg_cvi_rs232_error_to_mbg( int cvi_rc, const char *info ) ; /** - * @brief Translate a Windows NTSTATUS code to one of the @ref MBG_ERROR_CODES + * @brief Translate a Windows NTSTATUS code to one of the @ref MBG_ERROR_CODES. * - * @param[in] st One of the NTSTATUS codes defined in ntstatus.h - * @param[in] info An optional informational text string, or NULL + * @param[in] st One of the NTSTATUS codes defined in ntstatus.h. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_win32_ntstatus_to_mbg( NTSTATUS st, const char *info ) ; /** - * @brief Translate a Windows non-socket API return code to one of the @ref MBG_RETURN_CODES + * @brief Translate a Windows non-socket API return code to one of the @ref MBG_RETURN_CODES. * - * @param[in] win32_sys_rc A Windows non-socket API error code as returned by GetLastError(), or ERROR_SUCCESS. - * @param[in] info An optional informational text string, or NULL. + * @param[in] win32_sys_rc A Windows non-socket API error code as returned by @a GetLastError, or @a ERROR_SUCCESS. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. */ int mbg_win32_sys_err_to_mbg( DWORD win32_sys_rc, const char *info ) ; /** - * @brief Translate a Windows socket API error code to one of the @ref MBG_ERROR_CODES + * @brief Translate a Windows socket API error code to one of the @ref MBG_ERROR_CODES. * - * @param[in] wsa_err A Windows socket API error code as returned by WSAGetLastError() - * @param[in] info An optional informational text string, or NULL + * @param[in] wsa_err A Windows socket API error code as returned by @a WSAGetLastError. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_win32_wsa_err_to_mbg( int wsa_err, const char *info ) ; /** - * @brief Translate a POSIX errno error code to one of the @ref MBG_ERROR_CODES + * @brief Translate a POSIX errno error code to one of the @ref MBG_ERROR_CODES. * - * @param[in] posix_errno A POSIX error code as usually defined in errno.h - * @param[in] info An optional informational text string, or NULL + * @param[in] posix_errno A POSIX error code as usually defined in errno.h. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @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 + * @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. + * @a gethostbyname and @a gethostbyaddr. In case of error these functions + * don't set @a errno but @a h_errno to a specific value. * - * The functions gethostbyname() and gethostbyaddr() are obsolete, - * and getaddressinfo() should be used preferably. + * The functions @a gethostbyname and @a gethostbyaddr are obsolete, + * and @a getaddressinfo should be used preferably. * - * @param[in] posix_h_errno An error code as usually defined in netdb.h - * @param[in] info An optional informational text string, or NULL + * @param[in] posix_h_errno An error code as usually defined in netdb.h. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @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 + * @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" + * On POSIX systems the "last error" code is always stored in @a errno, but + * e.g. on Windows the "last error" code after a socket function + * has to be retrieved by calling @a WSAGetLastError, whereas the "last error" * code from non-socket POSIX-like functions has to be retrieved - * by calling GetLastError(). + * by calling @a GetLastError. * - * @param[in] info An optional informational text string, or NULL + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @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 + * @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. + * On POSIX systems the "last error" code is always stored in @a errno, but + * e.g. on Windows the "last error" code after a socket function + * has to be retrieved by calling @a WSAGetLastError, whereas the "last error" + * code from non-socket POSIX-like functions is stored in @a errno as usual. * - * @param[in] info An optional informational text string, or NULL + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @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() + * @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() + * returned by @a gethostbyname and @a gethostbyaddr. In case of error + * these functions don't set @a errno but @a h_errno on POSIX systems, + * but on Windows the error code can be retrieved by @a WSAGetLastError * as usual. * - * The functions gethostbyname() and gethostbyaddr() are obsolete, - * and getaddressinfo() should be used preferably. + * The functions @a gethostbyname and @a gethostbyaddr are obsolete, + * and @a getaddressinfo should be used preferably. * - * @param[in] info An optional informational text string, or NULL + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_get_gethostbyname_error( const char *info ) ; /** - * @brief Retrieve and convert last zlib internal error code + * @brief Retrieve and convert last zlib internal error code. * - * @param[in] zlib_error zlib internal error code - * @param[in] info An optional informational text string, or NULL - * @param[in] msg An optional zlib specific error msg, or NULL. - * Struct z_stream contains member msg. + * @param[in] zlib_error zlib internal error code. + * @param[in] info An optional informational text string, or @a NULL. + * @param[in] msg An optional zlib specific error msg, or @a NULL. + * Struct @a z_stream contains member msg. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_zlib_error_to_mbg( int zlib_error, const char *info, const char *msg ) ; diff --git a/mbglib/common/mbggeo.h b/mbglib/common/mbggeo.h index 29c86d5..9b93617 100644 --- a/mbglib/common/mbggeo.h +++ b/mbglib/common/mbggeo.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbggeo.h 1.14 2017/05/10 15:21:40Z martin REL_M $ + * $Id: mbggeo.h 1.16 2019/06/17 08:04:51Z thomas-b REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -22,7 +22,11 @@ * * ----------------------------------------------------------------------- * $Log: mbggeo.h $ - * Revision 1.14 2017/05/10 15:21:40Z martin + * Revision 1.16 2019/06/17 08:04:51Z thomas-b + * Renamed structs according to Meinberg naming convention + * Revision 1.15 2019/06/06 12:17:14 thomas-b + * Added several struct names to allow forward declaration + * Revision 1.14 2017/05/10 15:21:40 martin * Tiny cleanup. * Revision 1.13 2017/01/27 08:57:58 martin * Fixed macro syntax. @@ -87,7 +91,7 @@ extern "C" { * Longitude East and latitude North are positive angles, South or West * angles are negative. */ -typedef struct +typedef struct dms_s { uint16_t prefix; ///< 'N', 'E', 'S' or 'W' uint16_t deg; ///< [0...90 (lat) or 0...180 (lon)] @@ -110,7 +114,7 @@ do \ /** * @brief A geographic position represented in different formats */ -typedef struct +typedef struct pos_s { XYZ xyz; ///< Always WGS84 ECEF coordinates LLA lla; ///< Longitude, latitude and altitude, depending on the ellipsoid used for reference diff --git a/mbglib/common/mbgioctl.c b/mbglib/common/mbgioctl.c index e81d7fc..759f966 100644 --- a/mbglib/common/mbgioctl.c +++ b/mbglib/common/mbgioctl.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgioctl.c 1.6 2019/04/03 12:59:43Z martin REL_M $ + * $Id: mbgioctl.c 1.10 2021/09/13 13:39:09Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,15 @@ * * ----------------------------------------------------------------------- * $Log: mbgioctl.c $ - * Revision 1.6 2019/04/03 12:59:43Z martin + * Revision 1.10 2021/09/13 13:39:09Z martin + * Removed obsolete function mbgioctl_rc_to_mbg_errno(). + * Revision 1.9 2021/03/16 12:20:53Z martin + * Updated some comments. + * Revision 1.8 2021/03/12 12:32:53 martin + * Updated some comments. + * Revision 1.7 2020/06/18 13:09:07 martin + * Always build with mbgioctl_get_name(). + * Revision 1.6 2019/04/03 12:59:43 martin * Fixed preprocessor conditionals using unknown symbols. * Revision 1.5 2018/11/22 14:57:43 martin * Check new preprocessor symbol MBG_TGT_USE_IOCTL to exclude @@ -44,53 +52,6 @@ #include <mbgerror.h> -#if defined( MBG_TGT_WIN32 ) && !defined( MBG_TGT_KERNEL ) - -/*HDR*/ -int mbgioctl_rc_to_mbg_errno( int sys_errno ) -{ - // FIXME: This is a hack: Under Linux the IOCTL_RC_ERR_... - // code definitions are all negative, but the sys_errno - // number we expect here is positive. So just revert the - // sign to be able to uses the original IOCTL_RC_ERR_... - // definitions for the switch cases. - #if defined( MBG_TGT_LINUX ) - int cmp_rc_code = -sys_errno; - #else - int cmp_rc_code = sys_errno; - #endif - - switch ( cmp_rc_code ) - { - case IOCTL_RC_ERR_PERM: return MBG_ERR_PERM; - case IOCTL_RC_ERR_UNSUPP_IOCTL: return MBG_ERR_INV_DEV_REQUEST; - case IOCTL_RC_ERR_INVAL_PARAM: return MBG_ERR_INV_PARM; - case IOCTL_RC_ERR_NOT_SUPP_BY_DEV: return MBG_ERR_NOT_SUPP_BY_DEV; - case IOCTL_RC_ERR_NO_MEM: return MBG_ERR_NO_MEM; - case IOCTL_RC_ERR_BUSY_IRQ_UNSAFE: return MBG_ERR_IRQ_UNSAFE; // or MBG_ERR_BUSY ? - case IOCTL_RC_ERR_DEV_ACCESS: return MBG_ERR_IO; - - #if defined( MBG_TGT_LINUX ) // Linux-specific codes - case IOCTL_RC_ERR_COPY_TO_USER: return MBG_ERR_COPY_TO_USER; // FIXME - // case IOCTL_RC_ERR_COPY_FROM_USER: return MBG_ERR_COPY_FROM_USER; - #endif // defined( MBG_TGT_LINUX ) - } - - // FIXME: This is another hack: Eventually the error code returned - // in kernel space is remapped to some other code by the kernel, - // so this is is not covered by the switch above, and the error - // code used in kernel may not even be defined in user space. - // E.g. ENOIOCTL for *BSD is only defined in kernel space. - return mbg_posix_errno_to_mbg( sys_errno, NULL ); - -} // mbgioctl_rc_to_mbg_errno - -#endif // defined( MBG_TGT_WIN32 ) && !defined( MBG_TGT_KERNEL ) - - - -#if defined( DEBUG ) || defined( MBG_DEBUG ) - /*HDR*/ const char *mbgioctl_get_name( long code ) { @@ -108,7 +69,6 @@ const char *mbgioctl_get_name( long code ) } // mbgioctl_get_name -#endif // defined( DEBUG ) || defined( MBG_DEBUG ) #endif // MBG_TGT_USE_IOCTL diff --git a/mbglib/common/mbgioctl.h b/mbglib/common/mbgioctl.h index 1fcd7d6..d5c6283 100644 --- a/mbglib/common/mbgioctl.h +++ b/mbglib/common/mbgioctl.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgioctl.h 1.34 2019/04/03 12:28:11Z martin REL_M $ + * $Id: mbgioctl.h 1.38 2021/09/13 13:40:07Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,15 @@ * * ----------------------------------------------------------------------- * $Log: mbgioctl.h $ - * Revision 1.34 2019/04/03 12:28:11Z martin + * Revision 1.38 2021/09/13 13:40:07Z martin + * Removed obsolete function mbgioctl_rc_to_mbg_errno(). + * Revision 1.37 2021/04/29 15:05:39 martin + * Support reading device CPU info. + * Revision 1.36 2021/03/23 08:53:20 martin + * Updated some comments. + * Revision 1.35 2021/03/12 12:32:46 martin + * Updated some comments. + * Revision 1.34 2019/04/03 12:28:11 martin * Removed obsolete definition PCPS_SPIN_BUFFER. * Revision 1.33 2019/02/08 16:06:52 martin * Moved the Windows GUID stuff elsewhere. @@ -41,7 +49,7 @@ * Revision 1.25 2012/10/02 18:45:55 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 + * functions are called by an application, 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 pcpsdev.h which is always included. @@ -50,7 +58,7 @@ * Conditionally use older IOCTL request buffer structures. * Modified generic IOCTL handling such that for calls requiring variable sizes * a fixed request block containing input and output buffer pointers and sizes is - * passed down to the kernel driver. This simplifies implementation under *BSD + * passed down to the kernel driver. This simplifies implementation on *BSD * and also works for other target systems. * Support reading CORR_INFO, and reading/writing TR_DISTANCE. * New code IOCTL_DEV_HAS_PZF. @@ -61,7 +69,7 @@ * Added definitions to set up a table of all known * IOCTL codes and names. * Use MBG_TGT_KERNEL instead of _KDD_. - * Use IOTYPE 'Z' under *BSD since this means passthrough on NetBSD. + * Use IOTYPE 'Z' on *BSD since this means passthrough on NetBSD. * Revision 1.24 2009/12/15 15:34:59Z daniel * Support reading the raw IRIG data bits for firmware versions * which support this feature. @@ -111,7 +119,7 @@ * Support configuration of on-board frequency synthesizer. * Revision 1.9 2004/11/09 12:49:41Z martin * Modifications were required in order to be able to configure IRIG - * settings of cards which provide both IRIG input and output. + * settings of devices which provide both IRIG input and output. * The existing codes have been renamed with .._RX.. and are used to * configure the IRIG receiver (input). New codes have been defined * used to configure the IRIG transmitter. @@ -217,7 +225,7 @@ extern "C" { // looks like it's not possible to return a non-error custom // status code since in case of of success the DeviceIoControl() // function just returns a BOOL indicating success. - // TODO Test this, and eventually move it to mbgerror.h. + // TODO Test this, and maybe move it to mbgerror.h. #define _mbg_krn_errno_to_os( _n ) \ ( ( (_n) == MBG_SUCCESS ) ? STATUS_SUCCESS : \ ( (NTSTATUS) ( STATUS_SEVERITY_ERROR | STATUS_CUSTOM_FLAG | ( (-(_n)) & 0xFFFF ) ) ) ) @@ -332,7 +340,7 @@ extern "C" { #elif defined( MBG_TGT_BSD ) - // Under NetBSD 'Z' marks passthrough IOCTLs, under FreeBSD the code + // On NetBSD 'Z' marks passthrough IOCTLs, on FreeBSD the code // does not seem to matter, so we use 'Z' anyway. #define IOTYPE 'Z' @@ -425,7 +433,7 @@ typedef struct } IOCTL_GENERIC_REQ; -#define _MBG_IOG( _t, _n, _s ) _MBG_IOW( _t, _n, _s ) +#define _MBG_IOG( _t, _n, _s ) _MBG_IOW( _t, _n, _s ) #else @@ -511,8 +519,8 @@ typedef union #define IOCTL_GET_PCPS_DEV _MBG_IOR( IOTYPE, 0x01, PCPS_DEV ) #define IOCTL_GET_PCPS_STATUS_PORT _MBG_IOR( IOTYPE, 0x02, PCPS_STATUS_PORT ) -// Generic read/write operations. We define _MBG_IOW codes since these calls -// eventually pass a generic request structure IOCTL_GENERIC_REQ to the driver. +// Generic read/write operations defined using macro _MBG_IOG. These calls +// pass a generic request structure IOCTL_GENERIC_REQ to the driver. #define IOCTL_PCPS_GENERIC_READ _MBG_IOG( IOTYPE, 0x03, IOCTL_GENERIC_REQ ) #define IOCTL_PCPS_GENERIC_WRITE _MBG_IOG( IOTYPE, 0x04, IOCTL_GENERIC_REQ ) #define IOCTL_PCPS_GENERIC_READ_GPS _MBG_IOG( IOTYPE, 0x05, IOCTL_GENERIC_REQ ) @@ -728,6 +736,7 @@ typedef union #define IOCTL_GET_ALL_GPIO_STATUS _MBG_IOG( IOTYPE, 0xA3, IOCTL_GENERIC_REQ ) // variable size #define IOCTL_CHK_DEV_FEAT _MBG_IOW( IOTYPE, 0xA4, IOCTL_DEV_FEAT_REQ ) +#define IOCTL_GET_PCPS_CPU_INFO _MBG_IOR( IOTYPE, 0xA5, PCPS_CPU_INFO ) // The codes below are subject to changes without notice. They may be supported // by some kernel drivers, but usage is restricted to Meinberg software development. @@ -908,6 +917,7 @@ typedef union _mbg_cn_table_entry( IOCTL_GET_XMR_HOLDOVER_STATUS ), \ _mbg_cn_table_entry( IOCTL_GET_ALL_GPIO_STATUS ), \ _mbg_cn_table_entry( IOCTL_CHK_DEV_FEAT ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_CPU_INFO ), \ \ _mbg_cn_table_entry( IOCTL_MBG_DBG_GET_PORT_ADDR ), \ _mbg_cn_table_entry( IOCTL_MBG_DBG_SET_PORT_ADDR ), \ @@ -937,7 +947,7 @@ typedef union * * How to determine if a calling process has sufficient privileges * depends strongly on the rights management features provided - * by the underlying OS (e.g simple user/group rights, ACLs, + * by the underlying OS (e.g. simple user/group rights, ACLs, * Linux capabilities, Windows privileges) so this needs to be * implemented in the OS-specific code of a driver. * @@ -946,12 +956,12 @@ typedef union */ enum MBG_REQ_PRIVL { - MBG_REQ_PRIVL_NONE, //< e.g. read date/time/sync status - MBG_REQ_PRIVL_EXT_STATUS, //< e.g. read receiver position - MBG_REQ_PRIVL_CFG_READ, //< read device config data - MBG_REQ_PRIVL_CFG_WRITE, //< write config data to the device - MBG_REQ_PRIVL_SYSTEM, //< operations which may affect system operation - N_MBG_REQ_PRIVL //< the number of supported privilege levels + MBG_REQ_PRIVL_NONE, ///< E.g. read date/time/sync status. + MBG_REQ_PRIVL_EXT_STATUS, ///< E.g. read receiver position. + MBG_REQ_PRIVL_CFG_READ, ///< Read device config data. + MBG_REQ_PRIVL_CFG_WRITE, ///< Write config data to the device. + MBG_REQ_PRIVL_SYSTEM, ///< Operations which may affect system operation. + N_MBG_REQ_PRIVL ///< The number of supported privilege levels. }; @@ -964,10 +974,10 @@ int ioctl_get_required_privilege( ulong ioctl_code ) __attribute__((always_inlin /** * @brief Determine the privilege level required to execute a specific IOCTL command. * - * @param ioctl_code The IOCTL code for which to return the privilege level + * @param[in] ioctl_code The IOCTL code for which to return the privilege level. * - * @return One of the enumerated privilege levels - * @return -1 for unknown IOCTL codes + * @return One of the privilege levels enumerated in ::MBG_REQ_PRIVL, + * or -1 for unknown IOCTL codes. */ static __mbg_inline int ioctl_get_required_privilege( ulong ioctl_code ) @@ -998,6 +1008,7 @@ int ioctl_get_required_privilege( ulong ioctl_code ) // Commands returning public status information: case IOCTL_GET_PCPS_DRVR_INFO: case IOCTL_GET_PCPS_DEV: + case IOCTL_GET_PCPS_CPU_INFO: case IOCTL_GET_PCPS_SYNC_TIME: case IOCTL_GET_GPS_SW_REV: case IOCTL_GET_GPS_BVAR_STAT: @@ -1075,7 +1086,7 @@ int ioctl_get_required_privilege( ulong ioctl_code ) return MBG_REQ_PRIVL_NONE; // The next codes are somewhat special since they change something - // on the board but do not affect basic operation: + // on the device but do not affect basic operation: case IOCTL_PCPS_CLR_UCAP_BUFF: case IOCTL_SET_PCPS_EVENT_TIME: // supported by some customized firmware only case IOCTL_CLR_EVT_LOG: @@ -1197,7 +1208,6 @@ int ioctl_get_required_privilege( ulong ioctl_code ) /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ - int mbgioctl_rc_to_mbg_errno( int sys_errno ) ; const char *mbgioctl_get_name( long code ) ; /* ----- function prototypes end ----- */ diff --git a/mbglib/common/mbgklist.h b/mbglib/common/mbgklist.h index 16f3440..88c9cac 100644 --- a/mbglib/common/mbgklist.h +++ b/mbglib/common/mbgklist.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgklist.h 1.4 2018/09/13 05:27:28Z thomas-b REL_M $ + * $Id: mbgklist.h 1.6 2021/08/05 15:05:27Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,14 @@ * * ----------------------------------------------------------------------- * $Log: mbgklist.h $ - * Revision 1.4 2018/09/13 05:27:28Z thomas-b + * Revision 1.6 2021/08/05 15:05:27Z martin + * New typedef MBG_KLIST_HEAD for struct mbg_klist_head. + * New functions mbg_klist_insert_after() and mbg_klist_insert_before() + * provided by Philipp. + * Added some doxygen comments. + * Revision 1.5 2019/08/15 10:33:01 thomas-b + * Start variable names in macros with '_' + * Revision 1.4 2018/09/13 05:27:28 thomas-b * Added macro to get nth item of mbgklist * Revision 1.3 2017/07/05 09:52:39 martin * Safe loop macros added by philipp. @@ -70,8 +77,8 @@ extern "C" { #define mbg_klist_nth_item(head, pos, n) \ do { \ - unsigned i; \ - for (pos = (head)->next, i = 0; i < n; pos = pos->next, ++i); \ + unsigned _i; \ + for (pos = (head)->next, _i = 0; _i < n; pos = pos->next, ++_i); \ } while ( 0 ) #define mbg_klist_entry(ptr, type, member) \ @@ -119,12 +126,12 @@ extern "C" { -struct mbg_klist_head +typedef struct mbg_klist_head { struct mbg_klist_head *prev; struct mbg_klist_head *next; -}; +} MBG_KLIST_HEAD; static __mbg_inline @@ -145,6 +152,63 @@ void __mbg_klist_add_item( struct mbg_klist_head *item, struct mbg_klist_head *p } +/** + * @brief Insert a new list item after the item at the given position. + * + * The position of the list item referenced by @p head + * is left unchanged. + * + * This function is effectively the same as ::mbg_klist_prepend_item, + * the name of which is somewhat misleading. + * + * @param[in,out] head The item at a current list position. + * @param[in] item The item to be inserted. + * + * @see ::mbg_klist_insert_before + */ +static __mbg_inline +void mbg_klist_insert_after( struct mbg_klist_head *head, struct mbg_klist_head *item ) +{ + __mbg_klist_add_item( item, head, head->next ); +} + + +/** + * @brief Insert a new list item before the item at the given position. + * + * The position of the list item referenced by @p head + * is moved behind the new item. + * + * This function is effectively the same as ::mbg_klist_append_item, + * the name of which is somewhat misleading. + * + * @param[in,out] head The item at a current list position. + * @param[in] item The item to be inserted. + * + * @see ::mbg_klist_insert_after + */ +static __mbg_inline +void mbg_klist_insert_before( struct mbg_klist_head *head, struct mbg_klist_head *item ) +{ + __mbg_klist_add_item( item, head->prev, head ); +} + + +/** + * @brief Insert a new list item after the item at the given position. + * + * The position of the list item referenced by @p head + * is left unchanged. + * + * This function is effectively the same as ::mbg_klist_insert_after, + * and its name is somewhat misleading. + * + * @param[in,out] head The item at a current list position. + * @param[in] item The item to be inserted. + * + * @see ::mbg_klist_append_item + * @see ::mbg_klist_insert_after + */ static __mbg_inline void mbg_klist_prepend_item( struct mbg_klist_head *head, struct mbg_klist_head *item ) { @@ -152,6 +216,21 @@ void mbg_klist_prepend_item( struct mbg_klist_head *head, struct mbg_klist_head } +/** + * @brief Insert a new list item before the item at the given position. + * + * The position of the list item referenced by @p head + * is moved behind the new item. + * + * This is effectively the same as ::mbg_klist_insert_before, + * and its name is somewhat misleading. + * + * @param[in,out] head The item at a current list position. + * @param[in] item The item to be inserted. + * + * @see ::mbg_klist_prepend_item + * @see ::mbg_klist_insert_before + */ static __mbg_inline void mbg_klist_append_item( struct mbg_klist_head *head, struct mbg_klist_head *item ) { @@ -240,14 +319,14 @@ int mbg_klist_is_empty( const struct mbg_klist_head *head ) static __mbg_inline void __mbg_klist_add_list( const struct mbg_klist_head *list, struct mbg_klist_head *prev, struct mbg_klist_head *next ) { - struct mbg_klist_head *first = list->next; - struct mbg_klist_head *last = list->prev; + struct mbg_klist_head *_first = list->next; + struct mbg_klist_head *_last = list->prev; - first->prev = prev; - prev->next = first; + _first->prev = prev; + prev->next = _first; - last->next = next; - next->prev = last; + _last->next = next; + next->prev = _last; } diff --git a/mbglib/common/mbgmktm.c b/mbglib/common/mbgmktm.c index afdb195..edded26 100644 --- a/mbglib/common/mbgmktm.c +++ b/mbglib/common/mbgmktm.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgmktm.c 1.2 2017/07/05 10:00:29Z martin REL_M $ + * $Id: mbgmktm.c 1.4 2019/09/27 14:39:27Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,29 @@ * * ----------------------------------------------------------------------- * $Log: mbgmktm.c $ - * Revision 1.2 2017/07/05 10:00:29Z martin + * Revision 1.4 2019/09/27 14:39:27Z martin + * Code cleanup and doxygen updates. + * Revision 1.3 2019/08/21 11:07:13 martin + * ATTENTION: Calling conventions have changed! + * Renamed mbg_mktime() to mbg_mktime64(), which always computes a + * 64 bit timestamp and expects the address of a 64 bit variable to + * take the result. Unlike mktime(), this function now provides a + * proper return code indicating if the conversion was successful, + * or not. + * Also, the 'day' parameter now has to be in the same range as for + * POSIX mktime(), i.e. 1..31, instead of 0..30 as in the previous + * implementation of mbg_mktime. This also has to be taken into + * account wherever this function is called. + * The header file provides an inline function mbg_mktime() which + * is similar to mbg_mktime64() but expects the address of a POSIX + * time_t for the result, which can be 32 bit only on some systems, + * so the mbg_mktime64() function should be used preferably, if + * 64 bit timestamps are used anyway. + * There are also new inline functions mbg_mktime64_from_tm() and + * mbg_mktime_from_tm(), which call the associated generic functions + * but expect a standard POSIX struct tm to provide the date and + * time to be converted. + * Revision 1.2 2017/07/05 10:00:29 martin * Let mbg_mktime() fail if year is out of a range which depends on * the size of the 'time_t' type provided by the build environment. * Allow 0 as valid return value for mbg_mktime(). @@ -24,15 +46,18 @@ #include <mbgmktm.h> #undef _MBGMKTM -#include <assert.h> +#include <mbgerror.h> +#include <stdlib.h> -static const char Days[12] = + + +static const char days_per_month[MONTHS_PER_YEAR] = { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }; -static int YDays[12] = +static int ydays_per_month[MONTHS_PER_YEAR] = { 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334 }; @@ -41,69 +66,109 @@ static int YDays[12] = /*HDR*/ /** - * @brief Compute a linear time_t value from broken down date and time + * @brief Compute a linear ::MBG_TIME64_T value from broken down date and time + * + * This function basically works like the POSIX @a mktime function but + * doesn't apply a local time offset which depends on some timezone setting. + * + * Unlike @a mktime, it expects the address of a variable of type + * ::MBG_TIME64_T, which is always 64 bits wide, even on systems + * where @a time_t is only 32 bits wide. + * + * Also, it does not expect a structure, but a set of variables, which + * makes it more versatile. The expected values are in the same ranges + * as the members of the POSIX <em>struct tm</em> type used by @a mktime. + * + * Another difference is that unlike POSIX @a mktime, which simply returns + * <em>(time_t) -1</em> in case of error, this function provides a + * return code indicating if the calulation succeeded or not, + * and @a -1 can be a valid timestamp indicating a time associated with + * one second before the epoch. * - * This function works like the standard mktime() function but does not - * account for a timezone setting configured for the standard C library. - * Also, it does not take a structure but a set of variables which makes - * it more versatile. The accepted variables are in the same ranges - * as the struct tm members used by mktime(). + * There are also some variants, implemented as inline functions. + * See @ref mbg_mktime_fncs. * - * @param[in] year year number - 1900 - * @param[in] month months since January, 0..11 - * @param[in] day days after 1st, 0..30 - * @param[in] hour 0..23 - * @param[in] min 0..59 - * @param[in] sec 0..59, 60 if leap second + * @param[out] p_t64 Address of a variable to take the result on success, + * i.e. seconds since 1970-01-01 (POSIX @a time_t format, + * but always 64 bits). + * @param[in] year Years since 1900, i.e current year number - 1900. + * @param[in] month Months since January, 0..11 + * @param[in] day Day of the month, 1..31 + * @param[in] hour 0..23 + * @param[in] min 0..59 + * @param[in] sec 0..59, or 60 if inserted leap second * - * @return seconds since 1970-01-01 (Unix time_t format) or ((time_t) -1) if range overflow + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbg_mktime_fncs + * @see @ref mbg_mktime_fncs */ -time_t mbg_mktime( int year, int month, int day, - int hour, int min, int sec ) +int mbg_mktime64( MBG_TIME64_T *p_t64, int year, int month, int day, + int hour, int min, int sec ) { + int rc = MBG_SUCCESS; int leaps; - long days; - time_t secs; + long days; // type must be > 16 bits - // time_t should be at least 4 bytes - assert( sizeof( time_t ) >= 4 ); +#define USE_DIV 1 - if ( sizeof( time_t ) == 4 ) - { - // 32 bit *signed* time_t will roll over after 2038-01-19 03:14:07 - // when the number of seconds reaches 0x7FFFFFFF, so we don't try - // conversions for 2038 or later, though 32 bit *unsigned* time_t - // may still work after year 2100. - if ( year < 70 || year > 137 ) - goto fail; - } - else - if ( sizeof( time_t ) == 8 ) - { - // 64 bit time_t will work for million years. However, it's not - // clear what happes for dates before 1970-01-01T00:00:00 if time_t - // is *unsigned*. - if ( year < 70 ) - goto fail; - } - else - goto fail; +#if USE_DIV + div_t dt; +#endif - min += sec / 60; - sec %= 60; /* Seconds are normalized */ - hour += min / 60; - min %= 60; /* Minutes are normalized */ - day += hour / 24; - hour %= 24; /* Hours are normalized */ + // The day parameter is expected to be in the same range as + // for POSIX mktime(), i.e. 1..31. However, the algorithm below + // expects 0 for the first day of a month, so we just + // decrement the day number. + day--; - year += month / 12; /* Normalize month (not necessarily final) */ +#if USE_DIV + + // normalize seconds + dt = div( sec, SECS_PER_MIN ); + min += dt.quot; + sec = dt.rem; + + // normalize minutes + dt = div( min, MINS_PER_HOUR ); + hour += dt.quot; + min = dt.rem; + + // normalize hours + dt = div( hour, HOURS_PER_DAY ); + day += dt.quot; + hour = dt.rem; + + // normalize month (not necessarily finally) + dt = div( month, MONTHS_PER_YEAR ); + year += dt.quot; + month = dt.rem; + +#else + + // normalize seconds + min += sec / SECS_PER_MIN; + sec %= SECS_PER_MIN; + + // normalize minutes + hour += min / MINS_PER_HOUR; + min %= MINS_PER_HOUR; + + // normalize hours + day += hour / HOURS_PER_DAY; + hour %= HOURS_PER_DAY; + + // normalize month (not necessarily finally) + year += month / 12; month %= 12; - while ( day >= Days[month] ) +#endif + + while ( day >= days_per_month[month] ) { if ( !( year & 3 ) && ( month == 1 ) ) { - if (day > 28) + if ( day > 28 ) { day -= 29; month++; @@ -113,11 +178,11 @@ time_t mbg_mktime( int year, int month, int day, } else { - day -= Days[month]; + day -= days_per_month[month]; month++; } - year += month / 12; /* Normalize month */ + year += month / 12; // normalize month month %= 12; } @@ -127,18 +192,13 @@ time_t mbg_mktime( int year, int month, int day, if ( !( ( year + 70 ) & 3 ) && ( month < 2 ) ) --leaps; - days = year * 365L + leaps + YDays[month] + day; - - secs = days * 86400L + hour * 3600L + min * 60L + sec; - - if ( secs < 0 ) // == 0 is valid for 1970-01-01 00:00:00 - goto fail; + days = year * 365L + leaps + ydays_per_month[month] + day; - return secs; + *p_t64 = (MBG_TIME64_T) days * SECS_PER_DAY + hour * SECS_PER_HOUR + min * SECS_PER_MIN + sec; + // rc is still MBG_SUCCESS at this point. -fail: - return (time_t) -1; + return rc; -} // mbg_mktime +} // mbg_mktime64 diff --git a/mbglib/common/mbgmktm.h b/mbglib/common/mbgmktm.h index 0120622..33d1453 100644 --- a/mbglib/common/mbgmktm.h +++ b/mbglib/common/mbgmktm.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgmktm.h 1.2 2017/07/05 10:02:42Z martin REL_M $ + * $Id: mbgmktm.h 1.5 2019/09/27 14:42:16Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,32 @@ * * ----------------------------------------------------------------------- * $Log: mbgmktm.h $ - * Revision 1.2 2017/07/05 10:02:42Z martin + * Revision 1.5 2019/09/27 14:42:16Z martin + * Updated function prototypes, and cleaned up code. + * Revision 1.4 2019/08/26 11:29:55 martin + * New inline functions mbg_mktime64_from_tm_gps() + * and mbg_mktime_from_tm_gps(). + * Revision 1.3 2019/08/21 11:07:14 martin + * ATTENTION: Calling conventions have changed! + * Renamed mbg_mktime() to mbg_mktime64(), which always computes a + * 64 bit timestamp and expects the address of a 64 bit variable to + * take the result. Unlike mktime(), this function now provides a + * proper return code indicating if the conversion was successful, + * or not. + * Also, the 'day' parameter now has to be in the same range as for + * POSIX mktime(), i.e. 1..31, instead of 0..30 as in the previous + * implementation of mbg_mktime. This also has to be taken into + * account wherever this function is called. + * The header file provides an inline function mbg_mktime() which + * is similar to mbg_mktime64() but expects the address of a POSIX + * time_t for the result, which can be 32 bit only on some systems, + * so the mbg_mktime64() function should be used preferably, if + * 64 bit timestamps are used anyway. + * There are also new inline functions mbg_mktime64_from_tm() and + * mbg_mktime_from_tm(), which call the associated generic functions + * but expect a standard POSIX struct tm to provide the date and + * time to be converted. + * Revision 1.2 2017/07/05 10:02:42 martin * Include time.h. * Updated function prototypes. * Revision 1.1 2006/08/22 08:57:15 martin @@ -24,6 +49,10 @@ /* Other headers to be included */ +#include <mbgtime.h> +#include <timeutil.h> +#include <mbgerror.h> + #include <time.h> @@ -40,34 +69,265 @@ extern "C" { #endif +/** + * @defgroup mbg_mktime_fncs Meinberg functions to replace POSIX mktime + * + * These functions work like the POSIX @a mktime function but don't apply + * a local time offset which depends on some timezone setting. + * + * The basic function ::mbg_mktime64 expects the address of a variable + * of type ::MBG_TIME64_T, which is always 64 bits wide, even on systems + * where @a time_t is only 32 bits wide. + * + * Also, the basic function does not expect a structure, but a set of variables, + * which makes it more versatile. The expected values are in the same ranges + * as the for the members of the POSIX <em>struct tm</em> type used by @a mktime. + * + * Another difference is that unlike @a mktime, which simply returns + * <em>(time_t) -1</em> in case of error, these functions provides a + * return code indicating if the calulation succeeded or not, + * and @a -1 can be a valid timestamp indicating the last second + * before the epoch. + * + * There are also some variants, implemented as inline functions. + * + * The ::mbg_mktime function can be called with the address of a generic + * @a time_t for the calculated time stamp. On systems with a 64 bit @a time_t + * the result is the same as for ::mbg_mktime64, but on systems where + * @a time_t is only 32 bits wide, the returned value is truncated + * and suffers from the <b>Y2038 problem</b>. + * + * The variants ::mbg_mktime64_from_tm and ::mbg_mktime_from_tm are + * similar to ::mbg_mktime64 and ::mbg_mktime, but really expect a + * pointer to a <em>struct tm</em> as input, like the original @a mktime. + * + * @see ::mbg_mktime64 + * @see ::mbg_mktime + * @see ::mbg_mktime64_from_tm + * @see ::mbg_mktime_from_tm + */ + + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ /** - * @brief Compute a linear time_t value from broken down date and time - * - * This function works like the standard mktime() function but does not - * account for a timezone setting configured for the standard C library. - * Also, it does not take a structure but a set of variables which makes - * it more versatile. The accepted variables are in the same ranges - * as the struct tm members used by mktime(). - * - * @param[in] year year number - 1900 - * @param[in] month months since January, 0..11 - * @param[in] day days after 1st, 0..30 - * @param[in] hour 0..23 - * @param[in] min 0..59 - * @param[in] sec 0..59, 60 if leap second - * - * @return seconds since 1970-01-01 (Unix time_t format) or ((time_t) -1) if range overflow + * @brief Compute a linear ::MBG_TIME64_T value from broken down date and time + * + * This function basically works like the POSIX @a mktime function but + * doesn't apply a local time offset which depends on some timezone setting. + * + * Unlike @a mktime, it expects the address of a variable of type + * ::MBG_TIME64_T, which is always 64 bits wide, even on systems + * where @a time_t is only 32 bits wide. + * + * Also, it does not expect a structure, but a set of variables, which + * makes it more versatile. The expected values are in the same ranges + * as the members of the POSIX <em>struct tm</em> type used by @a mktime. + * + * Another difference is that unlike POSIX @a mktime, which simply returns + * <em>(time_t) -1</em> in case of error, this function provides a + * return code indicating if the calulation succeeded or not, + * and @a -1 can be a valid timestamp indicating a time associated with + * one second before the epoch. + * + * There are also some variants, implemented as inline functions. + * See @ref mbg_mktime_fncs. + * + * @param[out] p_t64 Address of a variable to take the result on success, + * i.e. seconds since 1970-01-01 (POSIX @a time_t format, + * but always 64 bits). + * @param[in] year Years since 1900, i.e current year number - 1900. + * @param[in] month Months since January, 0..11 + * @param[in] day Day of the month, 1..31 + * @param[in] hour 0..23 + * @param[in] min 0..59 + * @param[in] sec 0..59, or 60 if inserted leap second + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbg_mktime_fncs + * @see @ref mbg_mktime_fncs */ - time_t mbg_mktime( int year, int month, int day, int hour, int min, int sec ) ; + int mbg_mktime64( MBG_TIME64_T *p_t64, int year, int month, int day, int hour, int min, int sec ) ; /* ----- function prototypes end ----- */ + +static __mbg_inline /*HDR*/ +/** + * @brief Compute a linear time_t value from broken down date and time. + * + * This function is a variant of ::mbg_mktime64, but expects + * the address of a @a time_t variable for the result. + * + * On systems with a 64 bit @a time_t the result is the same as for + * ::mbg_mktime64, but on systems where @a time_t is only 32 bits wide, + * the returned value is truncated and suffers from the <b>Y2038 problem</b>. + * + * Use ::mbg_mktime64 preferably to compute a timestamp + * which is always 64 bits wide. + * + * @param[out] p_t Address of a @a time_t variable to receive the calculated + * timestamp on success, i.e. the seconds since 1970-01-01 + * (POSIX time_t format, but truncated to 32 bits on systems + * with 32 bit @a time_t). + * + * @param[in] year Years since 1900, i.e current year number - 1900. + * @param[in] month Months since January, 0..11 + * @param[in] day Day of the month, 1..31 + * @param[in] hour 0..23 + * @param[in] min 0..59 + * @param[in] sec 0..59, or 60 if leap second + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbg_mktime_fncs + * @see @ref mbg_mktime_fncs + */ +int mbg_mktime( time_t *p_t, int year, int month, int day, + int hour, int min, int sec ) +{ + MBG_TIME64_T t64; + + int rc = mbg_mktime64( &t64, year, month, day, hour, min, sec ); + + // On success we still check if the result is in a valid range + // and convert the result, if required. + if ( mbg_rc_is_success( rc ) ) + rc = mbg_trnc_time64_t_to_time_t( p_t, &t64 ); + + return rc; + +} // mbg_mktime + + + +static __mbg_inline /*HDR*/ +/** + * @brief Compute a 64 bit ::MBG_TIME64_T value from a struct tm. + * + * This function is just a shortcut for ::mbg_mktime64 which takes + * a POSIX-style <em>struct tm</em> as input, and calls ::mbg_mktime64 + * accordingly. + * + * @param[out] p_t Address of an ::MBG_TIME64_T variable to receive the + * calculated timestamp on success, i.e. seconds since + * 1970-01-01 (POSIX @a time_t format, but always 64 bits). + * + * @param[in] p_tm Pointer to a POSIX <em>struct tm</em> providing the date + * and time to be converted. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbg_mktime_fncs + * @see @ref mbg_mktime_fncs + */ +int mbg_mktime64_from_tm( MBG_TIME64_T *p_t, const struct tm *p_tm ) +{ + return mbg_mktime64( p_t, p_tm->tm_year, p_tm->tm_mon, p_tm->tm_mday, + p_tm->tm_hour, p_tm->tm_min, p_tm->tm_sec ); + +} // mbg_mktime64_from_tm + + + +static __mbg_inline /*HDR*/ +/** + * @brief Compute a POSIX time_t value from a struct tm. + * + * This function is just a shortcut for ::mbg_mktime which takes + * a POSIX-style <em>struct tm</em>, and calls ::mbg_mktime accordingly. + * + * Use ::mbg_mktime64_from_tm preferably to compute a timestamp + * which is always 64 bits wide. + * + * @param[out] p_t Address of a @a time_t variable to receive the calculated + * timestamp on success, i.e. the seconds since 1970-01-01 + * (POSIX time_t format, but truncated to 32 bits on systems + * with 32 bit @a time_t). + * + * @param[in] p_tm Pointer to a POSIX <em>struct tm</em> providing the date + * and time to be converted. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbg_mktime_fncs + * @see @ref mbg_mktime_fncs + */ +int mbg_mktime_from_tm( time_t *p_t, const struct tm *p_tm ) +{ + return mbg_mktime( p_t, p_tm->tm_year, p_tm->tm_mon, p_tm->tm_mday, + p_tm->tm_hour, p_tm->tm_min, p_tm->tm_sec ); + +} // mbg_mktime_from_tm + + + +static __mbg_inline /*HDR*/ +/** + * @brief Compute a 64 bit ::MBG_TIME64_T value from ::TM_GPS. + * + * This function is just a shortcut for ::mbg_mktime64 which takes a + * ::TM_GPS structure as input, and calls ::mbg_mktime64 accordingly. + * + * @param[out] p_t Address of an ::MBG_TIME64_T variable to receive the + * calculated timestamp on success, i.e. seconds since + * 1970-01-01 (POSIX @a time_t format, but always 64 bits). + * + * @param[in] p_tm Pointer to a ::TM_GPS structure providing the date + * and time to be converted. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbg_mktime_fncs + * @see @ref mbg_mktime_fncs + */ +int mbg_mktime64_from_tm_gps( MBG_TIME64_T *p_t, const TM_GPS *p_tm ) +{ + return mbg_mktime64( p_t, p_tm->year - 1900, p_tm->month - 1, p_tm->mday, + p_tm->hour, p_tm->min, p_tm->sec ); + +} // mbg_mktime64_from_tm_gps + + + +static __mbg_inline /*HDR*/ +/** + * @brief Compute a POSIX time_t value from ::TM_GPS. + * + * This function is just a shortcut for ::mbg_mktime which takes a + * ::TM_GPS structure as input, and calls ::mbg_mktime accordingly. + * + * Use ::mbg_mktime64_from_tm_gps preferably to compute a timestamp + * which is always 64 bits wide. + * + * @param[out] p_t Address of a @a time_t variable to receive the calculated + * timestamp on success, i.e. the seconds since 1970-01-01 + * (POSIX time_t format, but truncated to 32 bits on systems + * with 32 bit @a time_t). + * + * @param[in] p_tm Pointer to a ::TM_GPS structure providing the date + * and time to be converted. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbg_mktime_fncs + * @see @ref mbg_mktime_fncs + */ +int mbg_mktime_from_tm_gps( time_t *p_t, const TM_GPS *p_tm ) +{ + return mbg_mktime( p_t, p_tm->year - 1900, p_tm->month - 1, p_tm->mday, + p_tm->hour, p_tm->min, p_tm->sec ); + +} // mbg_mktime_from_tm_gps + + + #ifdef __cplusplus } #endif diff --git a/mbglib/common/mbgmutex.h b/mbglib/common/mbgmutex.h index 7a39075..9b2a9e2 100644 --- a/mbglib/common/mbgmutex.h +++ b/mbglib/common/mbgmutex.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgmutex.h 1.5 2018/07/16 14:18:05Z martin REL_M $ + * $Id: mbgmutex.h 1.6 2021/03/12 12:32:39Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,16 +11,18 @@ * * ----------------------------------------------------------------------- * $Log: mbgmutex.h $ - * Revision 1.5 2018/07/16 14:18:05Z martin + * Revision 1.6 2021/03/12 12:32:39Z martin + * Updated some comments. + * Revision 1.5 2018/07/16 14:18:05 martin * Support ID strings for spinlocks and mutexes. * Revision 1.4 2017/07/05 10:05:02 martin * windows.h is now included by mbg_tgt.h. * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. * Revision 1.3 2013/04/11 13:46:58 martin - * Use non-specific spinlock function under Windows. + * Use non-specific spinlock function on 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. + * Fixed build on DOS and QNX usinc dummy defines. * Don't define macros for semaphore destroy functions * if not required/supported on the target OS. * Revision 1.1 2011/04/15 12:26:59 martin diff --git a/mbglib/common/mbgpccyc.h b/mbglib/common/mbgpccyc.h index 842fe32..4ac26a1 100644 --- a/mbglib/common/mbgpccyc.h +++ b/mbglib/common/mbgpccyc.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgpccyc.h 1.8 2019/03/18 08:58:39Z martin REL_M $ + * $Id: mbgpccyc.h 1.9 2021/03/16 12:21:02Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: mbgpccyc.h $ - * Revision 1.8 2019/03/18 08:58:39Z martin + * Revision 1.9 2021/03/16 12:21:02Z martin + * Updated some comments. + * Revision 1.8 2019/03/18 08:58:39 martin * Cleanup and comments. * Revision 1.7 2017/05/10 15:21:41 martin * Tiny cleanup. @@ -135,9 +137,9 @@ extern "C" { // this does not seem to work properly at least with gcc 4.1.2 // shipped with Centos 5. // - // If optimization level 1 or higher is used then function + // If optimization level 1 or higher is used, function // parameters are also passed in registers. If the inline - // code above is used inside a function then the edx register + // code above is used inside a function, the edx register // is clobbered but the gcc 4.1.2 is not aware of this and // assumes edx is unchanged, which may yield faulty results // or even lead to segmentation faults. diff --git a/mbglib/common/mbgsystm.h b/mbglib/common/mbgsystm.h index 44ece8e..c16212d 100644 --- a/mbglib/common/mbgsystm.h +++ b/mbglib/common/mbgsystm.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgsystm.h 1.5 2019/02/08 11:05:48Z martin REL_M $ + * $Id: mbgsystm.h 1.12 2021/05/31 09:51:09Z thomas-b REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,7 +11,23 @@ * * ----------------------------------------------------------------------- * $Log: mbgsystm.h $ - * Revision 1.5 2019/02/08 11:05:48Z martin + * Revision 1.12 2021/05/31 09:51:09Z thomas-b + * Fixed missing include for POSIX systems (we need mbgtime for NSEC_PER_SEC) + * Revision 1.11 2021/05/11 19:04:58 martin + * Changed mbg_sleep_sec() to mbg_sleep_msec(), which expects milliseconds, + * and provided a compatible replacement function mbg_sleep_sec(), which + * in fact just calls mbg_sleep_msec() accordingly. + * Revision 1.10 2021/04/29 10:13:14 martin + * Fixed build on DOS. + * Revision 1.9 2021/04/08 16:41:05 martin + * New inline functions mbg_sys_time_normalize() and mbg_sys_time_add_ns(). + * Revision 1.8 2021/04/08 14:24:25 martin + * Updated a bunch of comments. + * Revision 1.7 2021/03/12 12:32:37 martin + * Updated some comments. + * Revision 1.6 2020/03/31 08:16:38 martin + * Fix for Linux kernel 5.6 which doesn't support getnstimeofday() anymore. + * Revision 1.5 2019/02/08 11:05:48 martin * Commonly use int64_t for MBG_SYS_TIME on Windows, rather than * FILETIME in user space and LARGE_INTEGER in kernel space. * Also use a function pointer to read the Windows system time @@ -41,6 +57,7 @@ #include <mbg_tgt.h> #include <words.h> +#include <mbgtime.h> #if defined( MBG_TGT_POSIX ) @@ -48,8 +65,14 @@ #if defined( MBG_TGT_LINUX ) + // If true, getnstimeofday() has been deprecated and removed, + // and ktime_get_real_ts64() can be used instead. + #define LINUX_KERNEL_HAS_KT64 ( LINUX_VERSION_CODE >= KERNEL_VERSION( 5, 6, 0 ) ) + + // If true, getnstimeofday() is supported and has not yet been deprecated. + #define LINUX_KERNEL_HAS_GETNSTIMEOFDAY ( ( LINUX_VERSION_CODE >= KERNEL_VERSION( 2, 6, 22 ) ) && !LINUX_KERNEL_HAS_KT64 ) + #define LINUX_KERNEL_HAS_MSLEEP ( LINUX_VERSION_CODE >= KERNEL_VERSION( 2, 6, 16 ) ) - #define LINUX_KERNEL_HAS_GETNSTIMEOFDAY ( LINUX_VERSION_CODE >= KERNEL_VERSION( 2, 6, 22 ) ) #define LINUX_KERNEL_HAS_KTIME_H ( LINUX_VERSION_CODE >= KERNEL_VERSION( 2, 6, 16 ) ) #if !LINUX_KERNEL_HAS_MSLEEP @@ -87,7 +110,7 @@ #endif - #else // POSIX user space + #else // POSIX user space. #include <time.h> @@ -105,8 +128,6 @@ #include <timeutil.h> // gstaft_fnc #endif - #include <mbgtime.h> - #elif defined( MBG_TGT_DOS ) #include <dos.h> @@ -130,7 +151,7 @@ extern "C" { /* - * Generic types to hold system timestamps and values for the system uptime.. + * Generic types to hold system timestamps and values for the system uptime. */ #if defined( MBG_TGT_POSIX ) @@ -139,7 +160,7 @@ extern "C" { #elif defined( MBG_TGT_WIN32 ) - typedef int64_t MBG_SYS_TIME; // Number of 100ns units + typedef int64_t MBG_SYS_TIME; // Number of 100ns units. typedef int64_t MBG_SYS_UPTIME; // [s] #elif defined( MBG_TGT_OS2 ) @@ -152,33 +173,49 @@ extern "C" { typedef uint32_t MBG_SYS_TIME; //## dummy typedef long MBG_SYS_UPTIME; //## dummy -#else // other target OSs which access the hardware directly +#else // Other target OSs which access the hardware directly. typedef uint32_t MBG_SYS_TIME; //## dummy typedef long MBG_SYS_UPTIME; //## dummy #endif -//### TODO // 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() - +/** + * @brief Read the current system time as ::MBG_SYS_TIME. + * + * Implementation depends strongly on the target system. + * + * On systems that may not support this, ::MBG_SYS_TIME is + * just some signed integer type which is set to 0. + * + * @param[out] p Address of an ::MBG_SYS_TIME variable to take the result. + */ static __mbg_inline void mbg_get_sys_time( MBG_SYS_TIME *p ) { #if defined( MBG_TGT_POSIX ) - #if defined( MBG_TGT_KERNEL ) // kernel space functions even differ for POSIX systems + #if defined( MBG_TGT_KERNEL ) // Kernel space functions even differ for POSIX systems. - #if defined( MBG_TGT_LINUX ) // Linux kernel space + #if defined( MBG_TGT_LINUX ) // Linux kernel space. - #if ( LINUX_KERNEL_HAS_GETNSTIMEOFDAY ) + #if LINUX_KERNEL_HAS_KT64 + { + struct timespec64 ts; + + ktime_get_real_ts64( &ts ); + + p->secs = ts.tv_sec; + p->nano_secs = ts.tv_nsec; + } + #elif LINUX_KERNEL_HAS_GETNSTIMEOFDAY { - // getnstimeofday() supported struct timespec ts; getnstimeofday( &ts ); @@ -188,7 +225,7 @@ void mbg_get_sys_time( MBG_SYS_TIME *p ) } #else { - // getnstimeofday() *not* supported + // getnstimeofday() is *not* supported. struct timeval tv; do_gettimeofday( &tv ); @@ -198,7 +235,7 @@ void mbg_get_sys_time( MBG_SYS_TIME *p ) } #endif - #elif defined( MBG_TGT_BSD ) // BSD kernel space + #elif defined( MBG_TGT_BSD ) // BSD kernel space. { struct timespec ts; @@ -209,11 +246,11 @@ void mbg_get_sys_time( MBG_SYS_TIME *p ) } #endif - #else // POSIX user space + #else // POSIX user space. { struct timespec ts; - #if defined( CLOCK_REALTIME_PRECISE ) // at least available in FreeBSD + #if defined( CLOCK_REALTIME_PRECISE ) // At least available in FreeBSD. clock_gettime( CLOCK_REALTIME_PRECISE, &ts ); #else clock_gettime( CLOCK_REALTIME, &ts ); @@ -226,9 +263,9 @@ void mbg_get_sys_time( MBG_SYS_TIME *p ) #elif defined( MBG_TGT_WIN32 ) - #if defined( MBG_TGT_KERNEL ) // Windows kernel space + #if defined( MBG_TGT_KERNEL ) // Windows kernel space. ke_query_system_time_fnc( (LARGE_INTEGER *) p ); - #else // Windows user space + #else // Windows user space. { gstaft_fnc( (FILETIME *) p ); } @@ -236,7 +273,7 @@ void mbg_get_sys_time( MBG_SYS_TIME *p ) #else - *p = 0; // dummy + *p = 0; // Dummy. #endif @@ -244,23 +281,32 @@ void mbg_get_sys_time( MBG_SYS_TIME *p ) +/** + * @brief Read the current system uptime as ::MBG_SYS_UPTIME, in seconds. + * + * Implementation depends strongly on the target system. + * + * On systems that may not support this, @p *p is set to -1. + * + * @param[out] p Address of an ::MBG_SYS_UPTIME variable to take the result. + */ static __mbg_inline void mbg_get_sys_uptime( MBG_SYS_UPTIME *p ) { #if defined( MBG_TGT_WIN32 ) - #if defined( MBG_TGT_KERNEL ) // kernel space + #if defined( MBG_TGT_KERNEL ) // Windows kernel space. ULONGLONG time_increment = KeQueryTimeIncrement(); LARGE_INTEGER tick_count; KeQueryTickCount( &tick_count ); - // multiplication by time_increment yields HNS units, - // but we need seconds + // Multiplication by time_increment yields HNS units, + // but we need seconds. *p = ( tick_count.QuadPart * time_increment ) / HNS_PER_SEC; - #else // user space + #else // Windows user space. DWORD tickCount; DWORD timeAdjustment; @@ -268,13 +314,13 @@ void mbg_get_sys_uptime( MBG_SYS_UPTIME *p ) BOOL timeAdjustmentDisabled; if ( !GetSystemTimeAdjustment( &timeAdjustment, &timeIncrement, &timeAdjustmentDisabled ) ) - *p = -1; // failed + *p = -1; // Failed. // ATTENTION: This is compatible with older Windows versions, but // the returned tick count wraps around to zero after 49.7 days. - // A new GetTickCount64() call is available under Windows Vista and newer, - // but the function call had to be imported dynamically since otherwise - // programs refused to start under pre-Vista versions due to undefined DLL symbol. + // A new GetTickCount64() call is available on Windows Vista and newer, + // but the function call had to be imported dynamically because otherwise + // programs refused to start on pre-Vista versions due to undefined DLL symbol. tickCount = GetTickCount(); *p = ( ( (MBG_SYS_UPTIME) tickCount ) * timeIncrement ) / HNS_PER_SEC; @@ -284,11 +330,11 @@ 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 + // TODO 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 - // a specific inline function do_div(). + // In kernel mode, using a simple 64 bit division may result + // in a linker error due to a missing symbol __udivdi3, so we + // use the specific inline function do_div(). // Also, the jiffies counter is not set to 0 at startup but to // a defined initialization value we need to account for. uint64_t tmp = get_jiffies_64() - INITIAL_JIFFIES; @@ -332,19 +378,19 @@ void mbg_get_sys_uptime( MBG_SYS_UPTIME *p ) #elif defined( MBG_TGT_FREEBSD ) { struct timespec ts; - // CLOCK_UPTIME_FAST is specific to FreeBSD + // CLOCK_UPTIME_FAST is specific to FreeBSD. int rc = clock_gettime( CLOCK_UPTIME_FAST, &ts ); *p = ( rc == 0 ) ? ts.tv_sec : -1; } #else // MBG_TGT_NETBSD, ... - *p = -1; //##++ needs to be implemented + *p = -1; // TODO Needs to be implemented. #endif #else - *p = -1; // not supported + *p = -1; // Not supported. #endif @@ -353,18 +399,24 @@ void mbg_get_sys_uptime( MBG_SYS_UPTIME *p ) /** - * @brief Compute delta between two ::MBG_SYS_TIME times, in milliseconds + * @brief Compute delta between two ::MBG_SYS_TIME times, in milliseconds. + * + * Implementation depends strongly on the target system. + * + * On systems that may not support this, 0 is returned. * - * @param[in] t2 the time to be subtracted from - * @param[in] t1 The time to be subtracted + * @param[in] t2 The time to be subtracted from. + * @param[in] t1 The time to be subtracted. * - * @return The time difference in [milliseconds] + * @return The time difference in [milliseconds]. */ static __mbg_inline long mbg_delta_sys_time_ms( const MBG_SYS_TIME *t2, const MBG_SYS_TIME *t1 ) { #if defined( MBG_TGT_POSIX ) + long dt = ( t2->secs - t1->secs ) * 1000; + #if defined ( MBG_TGT_LINUX ) && defined( MBG_TGT_KERNEL ) uint64_t tmp64 = t2->nano_secs - t1->nano_secs; do_div( tmp64, 1000000 ); @@ -372,34 +424,48 @@ long mbg_delta_sys_time_ms( const MBG_SYS_TIME *t2, const MBG_SYS_TIME *t1 ) #else dt += ( t2->nano_secs - t1->nano_secs ) / 1000000; #endif + return dt; + #elif defined( MBG_TGT_WIN32 ) + return (long) ( ( *t2 - *t1 ) / HNS_PER_MS ); + #else + return 0; + #endif } // mbg_delta_sys_time_ms +/** + * @brief Sleep for a specific number of milliseconds. + * + * Implementation depends strongly on the target system. + * + * @param[in] msecs The number of milliseconds to sleep. + */ static __mbg_inline -void mbg_sleep_sec( long sec ) +void mbg_sleep_msec( ulong msecs ) { #if defined( MBG_TGT_POSIX ) - #if defined( MBG_TGT_KERNEL ) // kernel space functions even differ for POSIX systems + #if defined( MBG_TGT_KERNEL ) // Kernel space functions even differ for POSIX systems. - #if defined( MBG_TGT_LINUX ) // Linux kernel space + #if defined( MBG_TGT_LINUX ) // Linux kernel space. - // msleep is not defined in older kernels, so we use this - // only if it is surely supported. + // msleep is not available in older kernels, so we + // use this only if it is really supported. #if LINUX_KERNEL_HAS_MSLEEP - msleep( sec * 1000 ); + msleep( msecs ); #else { DECLARE_WAIT_QUEUE_HEAD( tmp_wait ); - wait_event_interruptible_timeout( tmp_wait, 0, sec * HZ + 1 ); + // Timeout unit is [jiffies]. + wait_event_interruptible_timeout( tmp_wait, 0, ( ( msecs * HZ ) / 1000 ) + 1 ); } #endif @@ -407,7 +473,8 @@ void mbg_sleep_sec( long sec ) struct timeval tv = { 0 }; int ticks; - tv.tv_sec = sec; + tv.tv_sec = msecs / 1000; + tv.tv_usec = ( msecs % 1000 ) * 1000; ticks = tvtohz( &tv ); #if defined( DEBUG ) @@ -421,58 +488,176 @@ void mbg_sleep_sec( long sec ) #elif defined( MBG_TGT_NETBSD ) - int timeo = mstohz( sec * 1000 ); + int timeo = mstohz( msecs ); #if defined( DEBUG ) - printf( "kpause: %i s (%i ticks)\n", sec, timeo ); + printf( "kpause: %i ms (%i ticks)\n", msecs, timeo ); #endif kpause( "pause", 1, timeo, NULL ); #endif - #else // POSIX user space + #else // POSIX user space. - sleep( sec ); + // Depending on the implementation, usleep is only guaranteed to + // work for intervals less than 1000000 us, i.e. less than 1 s. + // So if the interval is 1 s or more, we call sleep() instead. + // + // TODO On newer POSIX systems, we should prefer nanosleep() + // over usleep(), but we'd need to find a safe way to determine + // if nanosleep() is supported by the target system. + + if ( msecs < 1000 ) + usleep( msecs * 1000 ); + else + sleep( msecs / 1000 ); #endif #elif defined( MBG_TGT_WIN32 ) - #if defined( MBG_TGT_KERNEL ) // kernel space + #if defined( MBG_TGT_KERNEL ) // Windows kernel space. LARGE_INTEGER delay; - // we need to pass a negative value to KeDelayExecutionThread() - // since the given time is a relative time interval, not absolute + // We need to pass a negative value to KeDelayExecutionThread() + // because the given time is a relative time interval, not absolute // time. See the API docs for KeDelayExecutionThread(). - delay.QuadPart = - ((LONGLONG) sec * HNS_PER_SEC); + delay.QuadPart = - ( (LONGLONG) msecs * HNS_PER_SEC / 1000 ); KeDelayExecutionThread( KernelMode, FALSE, &delay ); - #else // user space + #else // Windows user space. - // Sleep() expects milliseconds - Sleep( sec * 1000 ); + // Sleep() expects milliseconds. + Sleep( msecs ); #endif #elif defined( MBG_TGT_DOS ) - delay( (unsigned) ( sec * 1000 ) ); + delay( (unsigned) msecs ); #else - // This needs to be implemented for the target OS - // and thus will probably yield a linker error. - do_sleep_sec( sec ); + // This needs to be implemented for the target OS, + // so this code should result in a linker error. + do_sleep_msec( msecs ); #endif +} // mbg_sleep_msec + + + +/** + * @brief Sleep for a specific number of seconds. + * + * @param[in] secs The number of seconds to sleep. + */ +static __mbg_inline +void mbg_sleep_sec( long secs ) +{ + mbg_sleep_msec( secs * 1000 ); + } // mbg_sleep_sec +/** + * @brief Normalize a system timestamp in ::MBG_SYS_TIME format. + * + * Implementation depends on the target system. + * + * It's assumed that the basic system timestamp is always positive, + * but an offset has been added or subtracted without accounting + * for an overflow or underflow. + * + * @param[in] p Pointer to the time stamp to be normalized. + */ +static __mbg_inline +void mbg_sys_time_normalize( MBG_SYS_TIME *p ) +{ + #if defined( MBG_TGT_POSIX ) + + while ( p->nano_secs >= NSEC_PER_SEC ) + { + p->nano_secs -= NSEC_PER_SEC; + p->secs++; + } + + while ( p->nano_secs < 0 ) + { + p->nano_secs += NSEC_PER_SEC; + p->secs--; + } + + #elif defined( MBG_TGT_WIN32 ) + + // Nothing to do for FILETIME. + // Avoid warnings "never used". + (void) p; + + #elif defined( MBG_TGT_DOS ) + + // Nothing to do here. + // This isn't really supported. + (void) p; + + #else + + #error mbg_sys_time_normalize() needs to be implemented for this target. + + #endif + +} // mbg_sys_time_normalize + + + +/** + * @brief Add an amount of nanoseconds to a system timestamp in ::MBG_SYS_TIME format. + * + * Implementation depends on the target system. + * + * It's assumed that the basic system timestamp is always positive. + * + * @param[in] p Pointer to the time stamp to which to add an offset. + * @param[in] ns A number of nanoseconds to be added to @p *p. + */ +static __mbg_inline +void mbg_sys_time_add_ns( MBG_SYS_TIME *p, long ns ) +{ + #if defined( MBG_TGT_POSIX ) + + p->nano_secs += ns; + mbg_sys_time_normalize( p ); + + #elif defined( MBG_TGT_WIN32 ) + + // FILETIME has 100 ns (HNS) units, so we + // have to scale it to nanoseconds before + // the offset is applied, and scale the result + // back to HNS. + // TODO Should we also do some rounding + // to the nearest HNS count? + *p = ( ( (*p) * 100 ) + ns ) / 100; + + #elif defined( MBG_TGT_DOS ) + + // Nothing to do. + // We don't support nanoseconds anyway, + + #else + + #error mbg_sys_time_add_ns() needs to be implemented for this target. + + #endif + +} // mbg_sys_time_add_ns + + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/mbgtime.h b/mbglib/common/mbgtime.h index 0c08da3..286e687 100644 --- a/mbglib/common/mbgtime.h +++ b/mbglib/common/mbgtime.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgtime.h 1.31 2019/02/06 10:08:09Z martin REL_M $ + * $Id: mbgtime.h 1.46 2021/03/16 12:20:48Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,48 @@ * * ----------------------------------------------------------------------- * $Log: mbgtime.h $ - * Revision 1.31 2019/02/06 10:08:09Z martin + * Revision 1.46 2021/03/16 12:20:48Z martin + * Updated some comments. + * Revision 1.45 2021/03/12 12:32:51 martin + * Updated some comments. + * Revision 1.44 2021/03/11 16:08:01 martin + * Fixed some doxygen comments. + * Revision 1.43 2020/09/01 14:48:56 martin + * Fixed build with Borland C. + * Revision 1.42 2020/08/10 16:31:30Z martin + * Fixed 'long long' suffix for Windows builds. + * Revision 1.41 2019/11/27 11:21:39Z martin + * Renamed function n_days() to n_days_since_year_0() + * to make clearer what the function returns, and provided + * a backward-compatible inline function n_days(). + * Updated some doxygen comments. + * Revision 1.40 2019/11/27 11:14:39 martin + * Added definition POSIX_1970_INITIAL_DAY. + * Revision 1.39 2019/11/27 11:09:58 martin + * Added definitions of SMPTE epoch offsets from GPS epoch. + * Revision 1.38 2019/09/27 14:53:20 martin + * New define MONTHS_PER_YEAR. + * New types MBG_TIME32_T MBG_TIME32U_T. + * New inline function mbg_exp_year(). + * New inline functions normalize_gps_wn_dn() and de_normalize_gps_wn_dn(). + * New definitions for different types of leap second tables. + * New function is_valid_leap_second_date() and variants thereof. + * Updated function prototypes. + * Revision 1.37 2019/08/28 13:19:40 martin + * New structures MBG_TZ_INFO and MBG_LS_INFO which + * are used by some new functions in new module mbgtimex.c. + * Revision 1.36 2019/08/02 07:51:30 martin + * New type MBG_TIME64_T. + * Revision 1.35 2019/07/23 07:27:37 martin + * Added definition GPS_INITIAL_DAY. + * Revision 1.34 2019/07/19 08:39:19 martin + * Don't mark frac_sec_from_bin() as deprecated anymore. + * Revision 1.33 2019/07/19 07:49:22Z martin + * Modified dec_frac_to_bin_frac_{16,32} so that no compiler + * warning is emitted if a large data type is passed as an argument. + * Revision 1.32 2019/06/26 10:03:02Z martin + * Updated function prototypes. + * Revision 1.31 2019/02/06 10:08:09 martin * Added symbol HNS_PER_MIN. * Revision 1.30 2018/11/26 12:04:44Z martin * Moved definition NTP_FRAC_PER_SEC here. @@ -50,7 +91,7 @@ * 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. + * Fixed build on 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 @@ -116,11 +157,175 @@ extern "C" { /* Start of header body */ +/** + * @defgroup leap_second_fncs Meinberg leap second support functions + * + * By default, the date and time ***at the end of a leap second*** + * is referred to as <em>leap second date</em>. This is because: + * + * - At this point in time a new TAI offset comes into effect. + * + * - This is precise both in case of an inserted leap second (when the + * numbered seconds are counted 59, 60, 0) as well as for a deleted + * leap second (when the numbered seconds jump from 58 to 0, and + * there is no second numbered 59). + * + * - This complies with the leap second tables published by the + * International Earth Rotation and Reference Systems Service (IERS). + * + * So, for example, instead of 2016-12-31 23:59:59 we expect + * 2017-01-01 00:00:00 as a valid leap second date. + */ + +/** + * @defgroup leap_date_valid_fncs Meinberg functions that check if a leap second date is valid + * @ingroup leap_second_fncs + * + * For detailed hints, see @ref leap_second_fncs. + * + * Actually, only dates at the beginning of January or or July are + * considered valid leap second dates. There are several functions: + * + * @see ::is_valid_leap_second_date_tm A check function that expects a <em>struct tm</em> parameter. + * @see ::is_valid_leap_second_date_tm_gps A check function that expects a ::TM_GPS parameter. + * @see ::is_valid_leap_second_date A generic check function that expects day of month and month. + * + * @see @ref leap_second_fncs + */ + +/** + * @defgroup group_true_gps_wn_fncs Functions to determine a true leap second week number + * @ingroup leap_second_fncs + * + * The ::UTC::WNlsf field originally transmitted by the GPS satellites + * contains only the 8 LSBs of the full leap second week number, covering + * only a range of +/- ~128 weeks from the current week number. + * + * GPS receivers try to derive a full extended week number + * from this truncated week number. + * + * If the %UTC offset fields ::UTC::delta_tls and ::UTC::delta_tlsf + * are different, this means that a leap second is currently being + * announced, and thus the leap second week number is indeed in + * the range of +/- ~128 week of the current week, which means + * the week number can be unambiguously extended by the receiver. + * + * However, if ::UTC::delta_tls and ::UTC::delta_tlsf are the + * same, no leap second is announced, and it's not clear in + * which 256-week cycle the last leap second really occurred. + * These functions can be used to try to resolve this ambiguity, + * and, if possible, determine the true extended week number. + * + * The approach implemented here is based on a suggestion by + * Tom van Baak [[tvb@leapsecond.com]] on the leap seconds mailing + * list, and the fact that previous leap seconds were inserted only + * at the end of June/beginning of July, or end of December/beginning + * of January, and there are no plans to change this in the foreseeable + * future. + * + * The truncated week number is expanded for subsequent 256-week + * cycles, and if the extended week number and given day number + * yield a date that matches one of these well-known leap second + * dates, we have found the correct extended week number. + * + * A test has shown that there are unique results for 25 256-week + * cycles from 1980, i.e. until year 2099, if only leap seconds + * at the beginning of January or July are accepted. If the number of + * 256-week cycles is extended beyond 25 / year 2099, or if leap + * dates at the beginning of April or October are in addition taken + * into account, the results can be ambiguous, i.e. there + * can be more than one match. + * + * For example, both week numbers 1929 (0x0789, real week number) + * and 2185 (0x0889, off by 256 weeks) with correct day 7 yield + * the real leap second date 2017-01-01. + * + * @see ::mbg_find_true_gps_wn_lsf + * @see ::mbg_find_true_gps_wn_lsf_ex + * @see ::find_past_gps_wn_lsf_from_table + */ + + + +/** + * @defgroup group_timestamp_types Data types to store timestamps. + * + * Depending on the build and target environment, the original + * POSIX @a time_t type is usually 32 bits or 64 bits wide. + * If it is only 32 bits wide, timestamps will overflow in 2038. + * + * Using 64 bit types and associated time conversion functions + * avoid a rollover in 2038. + * + * Using a distinct 32 bit type can be useful for API calls which + * return 32 bit timestamps only, which may need to be mapped to + * an extended 64 bit range. + */ + +/** + * @brief A POSIX-like timestamp, 64 bits wide, signed. + * + * Negative numbers can represent times before the epoch. + * + * @ingroup group_timestamp_types + * @see @ref group_timestamp_types + */ +typedef int64_t MBG_TIME64_T; + + +/** + * @brief A POSIX-like timestamp, 32 bits wide, signed. + * + * Negative numbers can represent times before the epoch, + * but rolls over earlier than the unsigned type ::MBG_TIME32U_T. + * + * @ingroup group_timestamp_types + * @see @ref group_timestamp_types + */ +typedef int32_t MBG_TIME32_T; + + +/** + * @brief A POSIX-like timestamp, 32 bits wide, unsigned. + * + * No negative numbers, so times before the epoch + * can't be represented, but rolls over later + * than the signed type ::MBG_TIME32_T. + * + * @ingroup group_timestamp_types + * @see @ref group_timestamp_types + */ +typedef uint32_t MBG_TIME32U_T; + + + +/** + * @brief The number of days from 0000-01-01 until POSIX epoch 1970-01-01. + * + * The number of days as computed by ::n_days_since_year_0 for the + * POSIX time_t epoch, 1970-01-01, which was a Thursday. + * + * @see ::n_days_since_year_0 + */ +#define POSIX_1970_INITIAL_DAY 719162L + + + +/** + * @brief The number of days from 0000-01-01 until GPS epoch. + * + * The number of days as computed by ::n_days_since_year_0 for the + * date of the GPS epoch, 1980-01-06, which was a Sunday. + * + * @see ::n_days_since_year_0 + */ +#define GPS_INITIAL_DAY 722819L + /** - * @brief GPS epoch bias from ordinary time_t epoch + * @brief GPS epoch bias from ordinary POSIX time_t epoch. * - * The Unix time_t epoch is usually 1970-01-01 00:00 whereas + * The POSIX time_t epoch is usually 1970-01-01 00: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> @@ -131,10 +336,10 @@ extern "C" { /** - * @brief NTP epoch bias from ordinary time_t epoch + * @brief NTP epoch bias from ordinary POSIX 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 + * The POSIX time_t epoch is usually 1970-01-01 00:00:00, whereas + * the NTP epoch is 1900-01-01 00:00:00, so the difference is * a constant number of seconds:<br> * * time_t t = ntp_time - ::NTP_SEC_BIAS @@ -147,24 +352,112 @@ extern "C" { -// Modified Julian Day (MJD) numbers for some commonly used epochs. -// To compute the MJD for a given date just compute the days since epoch -// and add the constant number of days according to the epoch, e.g.: -// current_unix_mjd = ( time( NULL ) / SECS_PER_DAY ) + MJD_AT_UNIX_EPOCH; -#define MJD_AT_GPS_EPOCH 44244UL // MJD at 1980-01-06 -#define MJD_AT_UNIX_EPOCH 40587UL // MJD at 1970-01-01 -#define MJD_AT_NTP_EPOCH 40587UL // MJD at 1900-01-01 +/** + * @defgroup group_smpte_epoch_offsets_gps Predefined SMPTE epoch offsets from GPS epoch + * + * With these constants, timestamps of the GPS time scale + * can be converted to a particular time scale used by SMPTE, + * e.g. to calculate a specific video frame number. + * + * @anchor MBG_SMPTE_EPOCH_OFFSETS + * @see ::MBG_GPIO_VIDEO_EPOCHS + * + * @{ */ + + +/** + * @brief SMPTE epoch offset from GPS to 1970-01-01T00:00:00 TAI. + * + * The total offset consists of the difference between GPS epoch + * and POSIX/UTC epoch (::GPS_SEC_BIAS), plus the constant offset + * between GPS time scale and TAI (::GPS_TAI_OFFSET). + * + * @note This is the standard epoch referred to + * by the PTP/IEEE1588 SMPTE extension. + * + * @see ::SMPTE_TAI_EPOCH_1970 + */ +#define SMPTE_GPS_OFFSET_TAI_1970 ( GPS_SEC_BIAS + GPS_TAI_OFFSET ) + + +/** + * @brief SMPTE epoch offset from GPS to 1958-01-01T00:00:00 TAI. + * + * The total offset consists of the difference between GPS epoch + * and POSIX/UTC epoch (::GPS_SEC_BIAS), plus 12 years since 1958, + * 3 of which were leap years that had an additional day, plus the + * constant offset between GPS time scale and TAI (::GPS_TAI_OFFSET). + * + * @note The TAI time scale didn't exist in 1958, and time scales were + * shifted/adjusted/aligned between 1958 and 1972, so this offset is just + * a hypothetic extrapolation into the past, which may be defined or + * implemented in different ways by different manufacturers or projects. + * + * @see ::SMPTE_TAI_EPOCH_1958 + */ +#define SMPTE_GPS_OFFSET_TAI_1958 ( GPS_SEC_BIAS + ( ( 12 * 365 + 3 ) * SECS_PER_DAY ) + GPS_TAI_OFFSET ) -// The constant below defines the Windows FILETIME number (100 ns intervals -// since 1601-01-01) for 1970-01-01, which is usually the epoch for the time_t -// type used by the standard C library. +/** + * @brief SMPTE epoch offset from GPS to 1972-01-01T00:00:00 UTC. + * + * The total offset consists of the difference between GPS epoch + * and POSIX/UTC epoch (::GPS_SEC_BIAS), minus 2 years until 1972, + * none of which were leap years that had an additional day. + * + * @see ::SMPTE_UTC_EPOCH_1972 + */ +#define SMPTE_GPS_OFFSET_UTC_1972 ( GPS_SEC_BIAS - ( ( 2 * 365 + 0 ) * SECS_PER_DAY ) ) + + +/** + * @brief SMPTE epoch offset from GPS to 1980-06-01T00:00:00 GPS. + * + * In this case the SMPTE epoch is the same as the GPS epoch, + * so the offset is 0. + * + * @see ::SMPTE_GPS_EPOCH_1980 + */ +#define SMPTE_GPS_OFFSET_GPS_1980 ( 0 ) + + +/** @} defgroup group_ptp_smpte_epoch_offsets_gps */ + + + +/** + * @defgroup group_mjd_numbers Modified Julian Day (MJD) numbers for some commonly used epochs + * + * To compute the MJD for a given date just compute the days since epoch + * and add the constant number of days according to the epoch, e.g. for POSIX: + * + * current_unix_mjd = ( time( NULL ) / SECS_PER_DAY ) + MJD_AT_POSIX_EPOCH; + * + * @anchor MBG_MJD_NUMBERS + * + * @{ */ + +#define MJD_AT_GPS_EPOCH 44244UL ///< MJD at 1980-01-06, see @ref MBG_MJD_NUMBERS +#define MJD_AT_POSIX_EPOCH 40587UL ///< MJD at 1970-01-01, see @ref MBG_MJD_NUMBERS +#define MJD_AT_NTP_EPOCH 40587UL ///< MJD at 1900-01-01, see @ref MBG_MJD_NUMBERS + +/** @} defgroup group_mjd_numbers */ + + + +/** + * @brief The Windows FILETIME value at the usual POSIX epoch. + * + * The Windows @a FILETIME counts the number of 100 ns intervals + * since 1601-01-01, while the POSIX @a time_t epoch is usually + * (but not necessarily) 1970-01-01. + */ #if !defined( FILETIME_1970 ) // FILETIME represents a 64 bit number, so we need to defined the // constant with an appendix depending on the compiler. #if MBG_TGT_C99 || defined( __GNUC__ ) // syntax introduced by C99 standard - #define FILETIME_1970 0x019db1ded53e8000ULL // Epoch offset from FILETIME to UNIX + #define FILETIME_1970 0x019db1ded53e8000ULL #elif defined( MBG_TGT_WIN32 ) // MSC-specific syntax #define FILETIME_1970 0x019db1ded53e8000ui64 @@ -229,6 +522,7 @@ typedef struct } TIMEOUT; +#define MONTHS_PER_YEAR 12 #define DAYS_PER_WEEK 7 @@ -365,7 +659,7 @@ _ext DAYS_OF_MONTH_TABLE days_of_month // simplify call to n_days with structures #define _n_days( _s ) \ - n_days( (_s)->mday, (_s)->month, (_s)->year ) + n_days_since_year_0( (_s)->mday, (_s)->month, (_s)->year ) #define _is_leap_year( _y ) \ @@ -377,6 +671,95 @@ _ext DAYS_OF_MONTH_TABLE days_of_month +static __mbg_inline /*HDR*/ +/** + * @brief Expand a 2-digit year-of-the-century to a full 4-digit year number. + * + * The resulting year number includes the century and is + * in the range [year_lim ... ( year_lim + 99 )]. + * + * @param[in] year The 2-digit year-of-the-century to be converted. + * + * @param[in] year_lim The smallest 4-digit year number to be returned. + * + * @return The resulting 4 digit year number including century. + */ +int mbg_exp_year( int year, int year_lim ) +{ + int lyear = year + year_lim - ( year_lim % 100 ); + + if ( lyear < year_lim ) + lyear += 100; + + return lyear; + +} // mbg_exp_year + + + +static __mbg_inline /*HDR*/ +/** + * @brief Normalize a GPS week number / day number pair. + * + * GPS navigation data may contain week number / day number pairs where + * the day number is in the range 1..7 rather than 0..6. For example, + * a known leap second date was sent with 1929|7 instead of 1930|0. + * + * To resolve this ambiguity in computations, this function can be used + * to normalize the wn|dn pair. + * + * The complementary function ::de_normalize_gps_wn_dn can be used + * to convert a wn|dn pair back to the common wn|dn format where the + * day number is in the range 1..7. + * + * @param[in,out] p_wn Address of a variable containing the week number. + * @param[in,out] p_dn Address of a variable containing the day number. + * + * @see ::de_normalize_gps_wn_dn + */ +void normalize_gps_wn_dn( GPS_WNUM *p_wn, GPS_DNUM *p_dn ) +{ + if ( *p_dn == 7 ) + { + *p_dn = 0; + (*p_wn)++; + } + +} // normalize_gps_wn_dn + + + +static __mbg_inline /*HDR*/ +/** + * @brief De-normalize a GPS week number / day number pair. + * + * GPS navigation data may contain week number / day number pairs where + * the day number is in the range 1..7 rather than 0..6. For example, + * a known leap second date was sent with 1929|7 instead of 1930|0. + * + * However, the function ::normalize_gps_wn_dn may have been called before + * to normalize the wn|dn pair to simplify computations. + * + * This function can be used to convert a wn|dn pair back to the common + * wn|dn format where the day number is in the range 1..7. + * + * @param[in,out] p_wn Address of a variable containing the week number. + * @param[in,out] p_dn Address of a variable containing the day number. + * + * @see ::normalize_gps_wn_dn + */ +void de_normalize_gps_wn_dn( GPS_WNUM *p_wn, GPS_DNUM *p_dn ) +{ + if ( *p_dn == 0 ) + { + *p_dn = 7; + (*p_wn)--; + } + +} // de_normalize_gps_wn_dn + + + #if !defined( MBG_TGT_KERNEL ) /** @@ -402,6 +785,352 @@ _ext DAYS_OF_MONTH_TABLE days_of_month /** + * @brief DST on/off times pre-computed for a given year. + * + * Used like a cache to avoid redundant expensive computation + * of DST switching times for a given year inside an application. + * Not to be used for data exchange between devices. + * + * By default, switching times @a #t_on and @a #t_off are stored + * as local standard time (i.e. %UTC + @a #offs already applied) + * because this is most suitable for %UTC to local time conversions. + * + * However, for some cases (e.g. with PTP SMPTE) the switching + * times need to be compared to TAI times, so the function + * ::mbg_tz_info_to_tai can be used to convert the switching + * times to TAI. Care must be taken that the TAI switching times + * also need to be updated whenever a leap second event occurrs. + * + * @see ::mbg_set_tz_info_for_year + * @see ::mbg_set_tz_info_for_utc_time64_t + * @see ::mbg_tz_info_to_tai + */ +typedef struct +{ + MBG_TIME64_T t_on; ///< 'DST on' time, local standard time (default), or TAI. + MBG_TIME64_T t_off; ///< 'DST off' time, local standard time (default), or TAI. + int offs; ///< Offset to be added to %UTC to yield local standard time [sec]. + int offs_dl; ///< Additional offset to be added if daylight saving is in effect [sec]. + int year; ///< The year number for which @a #t_on and @a #t_off have been computed. + int auto_flag; ///< A flag indicating that @a #t_on and @a #t_off were computed by automatic rules. + int valid; ///< A flag indicating that the information in this structure has been set up. + +} MBG_TZ_INFO; + + + +/** + * @brief Current %UTC/TAI Offset And Leap Second Information. + * + * The stored information can be retrieved e.g. from the + * ::UTC data set transmitted by the GPS satellites, + * or from an NTP leap second file. + * + * @see ::mbg_set_ls_info_from_gps_utc + */ +typedef struct +{ + /// @brief Time of the nearest leap second, if available, in %UTC time scale. + /// Should match %UTC midnight at the end of the last day in June or December of a given year. + MBG_TIME64_T t64_ls_utc; + + /// @brief Time of the nearest leap second, if available, in TAI time scale. + /// Should be ahead of @a #t64_ls_utc by a number of leap seconds (~37 s in year 2019) + /// that have already been inserted in the past. + MBG_TIME64_T t64_ls_tai; + + /// @brief Number of seconds to be inserted into the %UTC time scale at the leap second transition. + /// This is 0 as long as no leap second announcement is currently available, +1 for a leap + /// second to be inserted, and -1 for a leap second to be deleted, which has yet never happened. + int ls_step; + + int offs_gps_utc; ///< Number of seconds the GPS system time is ahead of %UTC after the leap second transition. + + int offs_tai_utc; ///< Number of seconds TAI is ahead of %UTC after the leap second transition. + + int valid; ///< Indicates that the structure has been set up. + +} MBG_LS_INFO; + + + +/** + * @brief Entry of a leap second table providing timestamps and %UTC/TAI offsets. + * + * There are initializers that can be used to instantiate a table of entries. + * + * @see ::KNOWN_LEAP_SECOND_INFO_NTP + * @see ::KNOWN_LEAP_SECOND_INFO_POSIX + * @see ::LS_TABLE_ENTRY_GPS + */ +typedef struct +{ + /// Timestamp associated with ***the end*** of the leap second, + /// e.g. 2017-01-01 00:00:00 instead of 2016-12-31 23:59:59. + MBG_TIME64_T t_ls; + + /// Number of seconds that %UTC is ***behind*** TAI + /// after the given time. + int utc_tai_offs; + +} LS_TABLE_ENTRY; + + + +/** + * @brief Entry of a leap second table providing GPS timestamps and %UTC/GPS offsets. + * + * There is an initializer that can be used to instantiate a table of entries. + * + * ***Please note*** the table contains normalized wn|dn pairs like 1930|0, + * while the ::UTC info sent by the satellites could be 1929|7. So the wn|dn + * pairs from a GPS receiver should be normalized before being compared. + * + * @see ::KNOWN_LEAP_SECOND_INFO_GPS + * @see ::LS_TABLE_ENTRY + */ +typedef struct +{ + /// Extended GPS week number during which a leap second occurs. + GPS_WNUM wn; + + /// A day-of-week indicating when the leap second occurs. + /// Associated with ***the end*** of the leap second, + /// e.g. 2017-01-01 00:00:00 instead of 2016-12-31 23:59:59. + GPS_DNUM dn; + + /// Number of seconds that %UTC is ***behind*** GPS + /// after the given time. + int gps_tai_offs; + +} LS_TABLE_ENTRY_GPS; + + +#if defined( MBG_TGT_WIN32 ) && ( defined( _MSC_VER ) || defined( __BORLANDC__ ) ) + #define _ls_ntp_ts( _x ) ( _x ## i64 ) +#else + #define _ls_ntp_ts( _x ) ( _x ## LL ) +#endif + + +/** + * @brief Initializer for a table of known leap seconds, with NTP times. + * + * Can be used to initialize a table of ::LS_TABLE_ENTRY entries. + * Values have been copied and can be updated from an NTP leap second file. + * + * The table can be incomplete after another leap second has been scheduled, + * unless this initializer is updated. + * + * The first value is the number of seconds since the NTP epoch, 1900-01-01, + * and the second value indicates how many seconds %UTC is ***behind TAI*** + * after the given date. + * + * There is also an initializer which uses a POSIX time_t for the date, and + * another one where the date is specified by a GPS week number plus day number. + * + * @see ::LS_TABLE_ENTRY + * @see ::KNOWN_LEAP_SECOND_INFO_POSIX + * @see ::KNOWN_LEAP_SECOND_INFO_GPS + */ +#define KNOWN_LEAP_SECOND_INFO_NTP \ +{ \ + { _ls_ntp_ts( 2272060800 ), 10 }, /* 1 Jan 1972 */ \ + { _ls_ntp_ts( 2287785600 ), 11 }, /* 1 Jul 1972 */ \ + { _ls_ntp_ts( 2303683200 ), 12 }, /* 1 Jan 1973 */ \ + { _ls_ntp_ts( 2335219200 ), 13 }, /* 1 Jan 1974 */ \ + { _ls_ntp_ts( 2366755200 ), 14 }, /* 1 Jan 1975 */ \ + { _ls_ntp_ts( 2398291200 ), 15 }, /* 1 Jan 1976 */ \ + { _ls_ntp_ts( 2429913600 ), 16 }, /* 1 Jan 1977 */ \ + { _ls_ntp_ts( 2461449600 ), 17 }, /* 1 Jan 1978 */ \ + { _ls_ntp_ts( 2492985600 ), 18 }, /* 1 Jan 1979 */ \ + { _ls_ntp_ts( 2524521600 ), 19 }, /* 1 Jan 1980 */ \ + { _ls_ntp_ts( 2571782400 ), 20 }, /* 1 Jul 1981 */ \ + { _ls_ntp_ts( 2603318400 ), 21 }, /* 1 Jul 1982 */ \ + { _ls_ntp_ts( 2634854400 ), 22 }, /* 1 Jul 1983 */ \ + { _ls_ntp_ts( 2698012800 ), 23 }, /* 1 Jul 1985 */ \ + { _ls_ntp_ts( 2776982400 ), 24 }, /* 1 Jan 1988 */ \ + { _ls_ntp_ts( 2840140800 ), 25 }, /* 1 Jan 1990 */ \ + { _ls_ntp_ts( 2871676800 ), 26 }, /* 1 Jan 1991 */ \ + { _ls_ntp_ts( 2918937600 ), 27 }, /* 1 Jul 1992 */ \ + { _ls_ntp_ts( 2950473600 ), 28 }, /* 1 Jul 1993 */ \ + { _ls_ntp_ts( 2982009600 ), 29 }, /* 1 Jul 1994 */ \ + { _ls_ntp_ts( 3029443200 ), 30 }, /* 1 Jan 1996 */ \ + { _ls_ntp_ts( 3076704000 ), 31 }, /* 1 Jul 1997 */ \ + { _ls_ntp_ts( 3124137600 ), 32 }, /* 1 Jan 1999 */ \ + { _ls_ntp_ts( 3345062400 ), 33 }, /* 1 Jan 2006 */ \ + { _ls_ntp_ts( 3439756800 ), 34 }, /* 1 Jan 2009 */ \ + { _ls_ntp_ts( 3550089600 ), 35 }, /* 1 Jul 2012 */ \ + { _ls_ntp_ts( 3644697600 ), 36 }, /* 1 Jul 2015 */ \ + { _ls_ntp_ts( 3692217600 ), 37 }, /* 1 Jan 2017 */ \ + /* =============================== */ \ + /* If a new entry is added, don't */ \ + /* forget to update the tables */ \ + /* KNOWN_LEAP_SECOND_INFO_POSIX */ \ + /* and KNOWN_LEAP_SECOND_INFO_GPS */ \ + /* accordingly. */ \ + /* =============================== */ \ + { 0, 0 } /* end-of-table */ \ +} + + + +#define _ls_ntp_to_posix( _x ) ( _ls_ntp_ts( _x ) - NTP_SEC_BIAS ) + +/** + * @brief Initializer for a table of known leap seconds, with POSIX times. + * + * Can be used to initialize a table of ::LS_TABLE_ENTRY entries. Numeric + * values have been copied and can be updated from an NTP leap second file, + * and an appropriate macro is used to convert the NTP times to POSIX. + * + * The table can be incomplete after another leap second has been scheduled, + * unless this initializer is updated. + * + * The resulting first value is the number of seconds since the POSIX epoch, + * 1970-01-01, and the second value indicates how many seconds %UTC is + * ***behind TAI*** after the given date. + * + * There is also an initializer which uses an NTP time for the date, and + * another one where the date is specified by a GPS week number + * plus day number. + * + * @see ::LS_TABLE_ENTRY + * @see ::KNOWN_LEAP_SECOND_INFO_NTP + * @see ::KNOWN_LEAP_SECOND_INFO_GPS + */ +#define KNOWN_LEAP_SECOND_INFO_POSIX \ +{ \ + { _ls_ntp_to_posix( 2272060800 ), 10 }, /* 1 Jan 1972 */ \ + { _ls_ntp_to_posix( 2287785600 ), 11 }, /* 1 Jul 1972 */ \ + { _ls_ntp_to_posix( 2303683200 ), 12 }, /* 1 Jan 1973 */ \ + { _ls_ntp_to_posix( 2335219200 ), 13 }, /* 1 Jan 1974 */ \ + { _ls_ntp_to_posix( 2366755200 ), 14 }, /* 1 Jan 1975 */ \ + { _ls_ntp_to_posix( 2398291200 ), 15 }, /* 1 Jan 1976 */ \ + { _ls_ntp_to_posix( 2429913600 ), 16 }, /* 1 Jan 1977 */ \ + { _ls_ntp_to_posix( 2461449600 ), 17 }, /* 1 Jan 1978 */ \ + { _ls_ntp_to_posix( 2492985600 ), 18 }, /* 1 Jan 1979 */ \ + { _ls_ntp_to_posix( 2524521600 ), 19 }, /* 1 Jan 1980 */ \ + { _ls_ntp_to_posix( 2571782400 ), 20 }, /* 1 Jul 1981 */ \ + { _ls_ntp_to_posix( 2603318400 ), 21 }, /* 1 Jul 1982 */ \ + { _ls_ntp_to_posix( 2634854400 ), 22 }, /* 1 Jul 1983 */ \ + { _ls_ntp_to_posix( 2698012800 ), 23 }, /* 1 Jul 1985 */ \ + { _ls_ntp_to_posix( 2776982400 ), 24 }, /* 1 Jan 1988 */ \ + { _ls_ntp_to_posix( 2840140800 ), 25 }, /* 1 Jan 1990 */ \ + { _ls_ntp_to_posix( 2871676800 ), 26 }, /* 1 Jan 1991 */ \ + { _ls_ntp_to_posix( 2918937600 ), 27 }, /* 1 Jul 1992 */ \ + { _ls_ntp_to_posix( 2950473600 ), 28 }, /* 1 Jul 1993 */ \ + { _ls_ntp_to_posix( 2982009600 ), 29 }, /* 1 Jul 1994 */ \ + { _ls_ntp_to_posix( 3029443200 ), 30 }, /* 1 Jan 1996 */ \ + { _ls_ntp_to_posix( 3076704000 ), 31 }, /* 1 Jul 1997 */ \ + { _ls_ntp_to_posix( 3124137600 ), 32 }, /* 1 Jan 1999 */ \ + { _ls_ntp_to_posix( 3345062400 ), 33 }, /* 1 Jan 2006 */ \ + { _ls_ntp_to_posix( 3439756800 ), 34 }, /* 1 Jan 2009 */ \ + { _ls_ntp_to_posix( 3550089600 ), 35 }, /* 1 Jul 2012 */ \ + { _ls_ntp_to_posix( 3644697600 ), 36 }, /* 1 Jul 2015 */ \ + { _ls_ntp_to_posix( 3692217600 ), 37 }, /* 1 Jan 2017 */ \ + /* =================================================== */ \ + /* If a new entry is added, don't forget to update */ \ + /* the tables KNOWN_LEAP_SECOND_INFO_NTP and */ \ + /* KNOWN_LEAP_SECOND_INFO_GPS accordingly. */ \ + /* =================================================== */ \ + { 0, 0 } /* end-of-table */ \ +} + + + +#define _ls_ntp_to_gps( _x ) \ + ( ( _ls_ntp_ts( _x ) - NTP_SEC_BIAS - GPS_SEC_BIAS ) / SECS_PER_WEEK ), \ + ( ( ( _ls_ntp_ts( _x ) - NTP_SEC_BIAS - GPS_SEC_BIAS ) % SECS_PER_WEEK ) / SECS_PER_DAY ) + +#define _ls_utc_offs_to_gps( _x ) ( (_x) - GPS_TAI_OFFSET ) + +/** + * @brief Initializer for a table of known leap seconds, with GPS times. + * + * Can be used to initialize a table of ::LS_TABLE_ENTRY_GPS entries. Numeric + * values have been copied and can be updated from an NTP leap second file, + * and appropriate macros are used to convert the NTP times to GPS time. + * + * The table can be incomplete after another leap second has been scheduled, + * unless this initializer is updated. + * + * The resulting first value is an extended GPS week number, the second value + * is a day-of-week number, and the third value indicates how many seconds %UTC + * is ***behind GPS*** after the given date. + * + * ***Please note*** the resulting table does not include leap seconds before + * the GPS epoch, and it contains normalized wn|dn pairs like 1930|0, while + * the ::UTC info sent by the satellites could be 1929|7. So the dates from + * a GPS receiver should be normalized before being compared. + * + * There is also an initializer which uses an NTP time for the date, and + * another one where the date is specified by a POSIX time_t value. + * + * @see ::LS_TABLE_ENTRY + * @see ::KNOWN_LEAP_SECOND_INFO_NTP + * @see ::KNOWN_LEAP_SECOND_INFO_POSIX + */ +#define KNOWN_LEAP_SECOND_INFO_GPS \ +{ \ + { _ls_ntp_to_gps( 2571782400 ), _ls_utc_offs_to_gps( 20 ) }, /* 1 Jul 1981 */ \ + { _ls_ntp_to_gps( 2603318400 ), _ls_utc_offs_to_gps( 21 ) }, /* 1 Jul 1982 */ \ + { _ls_ntp_to_gps( 2634854400 ), _ls_utc_offs_to_gps( 22 ) }, /* 1 Jul 1983 */ \ + { _ls_ntp_to_gps( 2698012800 ), _ls_utc_offs_to_gps( 23 ) }, /* 1 Jul 1985 */ \ + { _ls_ntp_to_gps( 2776982400 ), _ls_utc_offs_to_gps( 24 ) }, /* 1 Jan 1988 */ \ + { _ls_ntp_to_gps( 2840140800 ), _ls_utc_offs_to_gps( 25 ) }, /* 1 Jan 1990 */ \ + { _ls_ntp_to_gps( 2871676800 ), _ls_utc_offs_to_gps( 26 ) }, /* 1 Jan 1991 */ \ + { _ls_ntp_to_gps( 2918937600 ), _ls_utc_offs_to_gps( 27 ) }, /* 1 Jul 1992 */ \ + { _ls_ntp_to_gps( 2950473600 ), _ls_utc_offs_to_gps( 28 ) }, /* 1 Jul 1993 */ \ + { _ls_ntp_to_gps( 2982009600 ), _ls_utc_offs_to_gps( 29 ) }, /* 1 Jul 1994 */ \ + { _ls_ntp_to_gps( 3029443200 ), _ls_utc_offs_to_gps( 30 ) }, /* 1 Jan 1996 */ \ + { _ls_ntp_to_gps( 3076704000 ), _ls_utc_offs_to_gps( 31 ) }, /* 1 Jul 1997 */ \ + { _ls_ntp_to_gps( 3124137600 ), _ls_utc_offs_to_gps( 32 ) }, /* 1 Jan 1999 */ \ + { _ls_ntp_to_gps( 3345062400 ), _ls_utc_offs_to_gps( 33 ) }, /* 1 Jan 2006 */ \ + { _ls_ntp_to_gps( 3439756800 ), _ls_utc_offs_to_gps( 34 ) }, /* 1 Jan 2009 */ \ + { _ls_ntp_to_gps( 3550089600 ), _ls_utc_offs_to_gps( 35 ) }, /* 1 Jul 2012 */ \ + { _ls_ntp_to_gps( 3644697600 ), _ls_utc_offs_to_gps( 36 ) }, /* 1 Jul 2015 */ \ + { _ls_ntp_to_gps( 3692217600 ), _ls_utc_offs_to_gps( 37 ) }, /* 1 Jan 2017 */ \ + /* ======================================================================== */ \ + /* If a new entry is added, don't forget to update the tables */ \ + /* KNOWN_LEAP_SECOND_INFO_NTP and KNOWN_LEAP_SECOND_INFO_POSIX */ \ + /* accordingly. */ \ + /* ======================================================================== */ \ + { 0, 0, 0 } /* end-of-tbl */ \ +} + + + +/** + * @brief Number of 256-week-cycles to check for true leap second week number. + * + * The number of 256-week-cycles to check in ::mbg_find_true_gps_wn_lsf + * or find_true_gps_wn_lsf (firmware version of the function), or when trying + * to resolve the ambiguity of the 8 bit truncated week number in ::UTC::WNlsf. + * + * According to some tests, the results are not ambiguous for 25 + * 256-week cycles after 1980 (i.e. until year 2099), if only + * leap second dates at the end of June / beginning of July or + * end of December / beginning of January are taken into account. + * + * @see ::mbg_find_true_gps_wn_lsf (Meinberg API) + * @see find_true_gps_wn_lsf (firmware version of ::mbg_find_true_gps_wn_lsf) + * @see ::ACCEPT_LS_APR_OCT + */ +#define N_GPS_WN_EPOCH 25 + + +#if !defined( ACCEPT_LS_APR_OCT ) + #define ACCEPT_LS_APR_OCT 0 + ///< Should be 0, otherwise ::mbg_find_true_gps_wn_lsf or + ///< find_true_gps_wn_lsf (firmware version of the function) + ///< may fail. + ///< See also ::N_GPS_WN_EPOCH +#endif + + + +/** * @brief Convert a 16 bit binary fraction to a scaled decimal * * @param[in] bin The binary fraction @@ -413,7 +1142,7 @@ _ext DAYS_OF_MONTH_TABLE days_of_month * @see ::dec_frac_to_bin_frac_32 * @see ::bin_frac_32_to_dec_frac */ -static __mbg_inline +static __mbg_inline /*HDR*/ uint32_t bin_frac_16_to_dec_frac( uint16_t bin, uint32_t scale ) { return (uint32_t) ( (MBG_FRAC32_CONVERSION_TYPE) bin * scale @@ -435,7 +1164,7 @@ uint32_t bin_frac_16_to_dec_frac( uint16_t bin, uint32_t scale ) * @see ::dec_frac_to_bin_frac_16 * @see ::bin_frac_16_to_dec_frac */ -static __mbg_inline +static __mbg_inline /*HDR*/ uint32_t bin_frac_32_to_dec_frac( uint32_t bin, uint32_t scale ) { return (uint32_t) ( (MBG_FRAC32_CONVERSION_TYPE) bin * scale @@ -454,18 +1183,18 @@ uint32_t bin_frac_32_to_dec_frac( uint32_t bin, uint32_t scale ) // This could probably be fixed by a different way of // casting, at least for a partial expression. -static __mbg_inline -uint16_t dec_frac_to_bin_frac_16( uint32_t dec, uint32_t scale ) +static __mbg_inline /*HDR*/ +uint16_t dec_frac_to_bin_frac_16( MBG_FRAC32_CONVERSION_TYPE dec, uint32_t scale ) { - return (uint16_t) ( ( ( (MBG_FRAC32_CONVERSION_TYPE) dec * 0x20000 / scale ) + 1 ) >> 1 ); + return (uint16_t) ( ( ( dec * 0x20000 / scale ) + 1 ) >> 1 ); } // dec_frac_to_bin_frac_16 -static __mbg_inline -uint32_t dec_frac_to_bin_frac_32( uint32_t dec, uint32_t scale ) +static __mbg_inline /*HDR*/ +uint32_t dec_frac_to_bin_frac_32( MBG_FRAC32_CONVERSION_TYPE dec, uint32_t scale ) { - return (uint32_t) ( ( ( (MBG_FRAC32_CONVERSION_TYPE) dec * MBG_FRAC32_UNITS_PER_SEC * 2 / scale ) + 1 ) >> 1 ); + return (uint32_t) ( ( ( dec * MBG_FRAC32_UNITS_PER_SEC * 2 / scale ) + 1 ) >> 1 ); } // dec_frac_to_bin_frac_32 @@ -493,10 +1222,14 @@ uint32_t dec_frac_to_bin_frac_32( uint32_t dec, uint32_t scale ) /** * @brief Convert a binary fraction to a scaled decimal * - * Convert a binary fraction (e.g. of a second, as in ::PCPS_TIME_STAMP::frac) - * to a decimal fraction, using a specified scale factor. + * Convert a binary fraction (e.g. as in ::PCPS_TIME_STAMP::frac) + * to a decimal fraction, using a specified scale factor. Depending + * on the @p scale factor, the result can be milliseconds, microseconds, + * nanoseconds, or whatever. * - * @deprecated This function is deprecated, use ::bin_frac_32_to_dec_frac preferably. + * This function is actually just an alias for ::bin_frac_32_to_dec_frac, + * but has been introduced much erlier than the latter, and thus is kept + * for compatibility reasons. * * @param[in] b The binary fraction * @param[in] scale The scale factor @@ -505,8 +1238,8 @@ uint32_t dec_frac_to_bin_frac_32( uint32_t dec, uint32_t scale ) * * @see ::bin_frac_32_to_dec_frac */ -static __mbg_inline -uint32_t _DEPRECATED_BY( "bin_frac_32_to_dec_frac" ) frac_sec_from_bin( uint32_t b, uint32_t scale ) +static __mbg_inline /*HDR*/ +uint32_t frac_sec_from_bin( uint32_t b, uint32_t scale ) { return bin_frac_32_to_dec_frac( b, scale ); @@ -530,13 +1263,107 @@ uint32_t _DEPRECATED_BY( "bin_frac_32_to_dec_frac" ) frac_sec_from_bin( uint32_t * * @see ::MBG_FRAC32_UNITS_PER_SEC */ -static __mbg_inline +static __mbg_inline /*HDR*/ double dfrac_sec_from_bin( uint32_t b ) { return (double) b / (double) MBG_FRAC32_UNITS_PER_SEC; } // dfrac_sec_from_bin + + +static __mbg_inline /*HDR*/ +/** + * @brief Check if a particular date is a valid leap second date. + * + * This generic function expects a day of month, and a month. + * + * @param[in] mday The day of month of the date to be checked, range [1..31]. + * @param[in] month The month of the date to be checked, range [1..12]. + * + * @return @a true if considered valid, else @a false. + * + * @ingroup leap_date_valid_fncs + * @see @ref leap_date_valid_fncs + * @see ::is_valid_leap_second_date_tm_gps + * @see ::is_valid_leap_second_date_tm + */ +bool is_valid_leap_second_date( int mday, int month ) +{ + if ( mday != 1 ) + return false; + + if ( ( month == 1 ) || ( month == 7 ) ) // 1st of January or July + return true; + + #if ACCEPT_LS_APR_OCT + if ( ( month == 4 ) || ( month == 10 ) ) // 1st of April or October + return true; + #endif + + return false; + +} // is_valid_leap_second_date + + + +static __mbg_inline /*HDR*/ +/** + * @brief Check if a particular date in ::TM_GPS format is a valid leap second date. + * + * For detailed hints see @ref leap_date_valid_fncs and @ref leap_date_valid_fncs. + * + * This function expects a ::TM_GPS parameter and calls + * a generic function to actually check the date. + * + * @param[in] p_tm_gps The date to be checked, in ::TM_GPS format. + * + * @return @a true if considered valid, else @a false. + * + * @ingroup leap_date_valid_fncs + * @see @ref leap_date_valid_fncs + * @see ::is_valid_leap_second_date_tm + * @see ::is_valid_leap_second_date + */ +bool is_valid_leap_second_date_tm_gps( const TM_GPS *p_tm_gps ) +{ + return is_valid_leap_second_date( p_tm_gps->mday, p_tm_gps->month ); + +} // is_valid_leap_second_date_tm_gps + + + +static __mbg_inline /*HDR*/ +/** + * @brief Check if a particular date in <em>struct tm</em> format is a valid leap second date. + * + * We expect the date and time immediately ***after*** a leap second, + * i.e. when a new TAI offset becomes valid. For example, we expect + * 2017-01-01 00:00:00 instead of 2016-12-31 23:59:59. + * This should work for both inserted and deleted leap seconds. + * + * By default, only dates at the beginning of January or or July are + * considered valid. + * + * This function expects a <em>struct tm</em> parameter and calls + * a generic function to actually check the date. + * + * @param[in] p_tm The date to be checked, in <em>struct tm</em> format. + * + * @return @a true if considered valid, else @a false. + * + * @ingroup leap_date_valid_fncs + * @see @ref leap_date_valid_fncs + * @see ::is_valid_leap_second_date_tm_gps + * @see ::is_valid_leap_second_date + */ +bool is_valid_leap_second_date_tm( const struct tm *p_tm ) +{ + return is_valid_leap_second_date( p_tm->tm_mday, p_tm->tm_mon + 1 ); + +} // is_valid_leap_second_date_tm + + #endif // !defined( MBG_TGT_KERNEL ) @@ -595,12 +1422,18 @@ double dfrac_sec_from_bin( uint32_t b ) /** * @brief Convert second-of-week to day-of-week and time-of-day * - * @param[in] wsec The second-of-week number to be converted - * @param[out] tm Address of a ::TM_GPS structure which takes the computed results + * @param[in] wsec The second-of-week number to be converted. + * Must not be negative. + * @param[out] tm Address of a ::TM_GPS structure which takes + * the computed results. Updates the fields + * ::TM_GPS::hour, ::TM_GPS::min, ::TM_GPS::sec, + * and ::TM_GPS::wday in the range 0..6, with + * 0 = Sunday. * * @return Pointer to the ::TM_GPS structure that has been passed * * @see ::tm_to_wsec + * @see ::day_of_week_sun06 */ TM_GPS *wsec_to_tm( long wsec, TM_GPS *tm ) ; @@ -644,24 +1477,46 @@ double dfrac_sec_from_bin( uint32_t b ) * @param[in] day_num Number of days from the beginning of that year, may be negative * @param[out] tm Address of a ::TM_GPS structure which takes the computed results */ - void date_of_year ( int year, int day_num, TM_GPS *tm ) ; + void date_of_year( int year, int day_num, TM_GPS *tm ) ; /** - * @brief Compute day-of-week from a given date + * @brief Compute day-of-week for a given date. * - * @todo Specify range of returned day-of-week. Should we just call n_days()? + * ATTENTION: The computed day-of-week is in the range 0..6, + * with 0 = Monday (!). * - * @param[in] day The day-of-month - * @param[in] month The month + * In most cases the function ::day_of_week_sun06 is + * more suitable for applications. + * + * @param[in] day The day-of-month, 0..31 + * @param[in] month The month, 1..12 * @param[in] year The full year number * - * @return The computed day-of-week + * @return The computed day-of-week, 0..6, 0 = Monday (!) * - * @see ::n_days + * @see ::day_of_week_sun06 + * @see ::n_days_since_year_0 */ int day_of_week( int day, int month, int year ) ; /** + * @brief Compute day-of-week for a given date. + * + * The computed day-of-week is in the range 0..6, + * with 0 = Sunday, as expected by most applications. + * + * @param[in] day The day-of-month, 0..31 + * @param[in] month The month, 1..12 + * @param[in] year The full year number + * + * @return The computed day-of-week, 0..6, with 0 = Sunday. + * + * @see ::n_days_since_year_0 + * @see ::wsec_to_tm + */ + int day_of_week_sun06( int day, int month, int year ) ; + + /** * @brief Update a year number by a number of days, accounting for leap years * * @param[in] day_num The number of days to evaluate @@ -674,15 +1529,27 @@ double dfrac_sec_from_bin( uint32_t b ) /** * @brief Compute number of days after Jan 1, 0000 for a given date * - * @param[in] mday The day-of-month - * @param[in] month The month - * @param[in] year The full year number + * @param[in] mday The day-of-month, [1..31] + * @param[in] month The month, [1..12]. + * @param[in] year The full year number, starting from year 0. * * @return The computed number of days * * @see ::day_of_week */ - long n_days( ushort mday, ushort month, ushort year ) ; + long n_days_since_year_0( int mday, int month, int year ) ; + + /** + * @brief Search a table of known past leap second dates for a specific week and day number. + * + * Optionally we return the latest week number we + * have found in the table, so an application can + * start there searching there for future potential + * leap second dates. + * + * @ingroup group_true_gps_wn_fncs + */ + int find_past_gps_wn_lsf_from_table( GPS_WNUM *p_wn, GPS_DNUM dn_t, int srch_all, GPS_WNUM *p_wn_last ) ; /** * @brief Print time with hours, minutes, seconds to a string @@ -744,6 +1611,28 @@ double dfrac_sec_from_bin( uint32_t b ) /* ----- function prototypes end ----- */ +static __mbg_inline /*HDR*/ +/** + * @brief Compute number of days after Jan 1, 0000 for a given date. + * + * @deprecated This function is deprecated. Use ::n_days_since_year_0 + * instead, which has a more meaningful name to avoid usage problems. + * + * @param[in] mday The day-of-month, [1..31] + * @param[in] month The month, [1..12]. + * @param[in] year The full year number, starting from year 0. + * + * @return The computed number of days + * + * @see ::day_of_week + */ +long _DEPRECATED_BY( "n_days_since_year_0" ) n_days( int mday, int month, int year ) +{ + return n_days_since_year_0( mday, month, year ); + +} // n_days + + /* End of header body */ diff --git a/mbglib/common/mbgutil.h b/mbglib/common/mbgutil.h index 1fa1e55..7c28120 100644 --- a/mbglib/common/mbgutil.h +++ b/mbglib/common/mbgutil.h @@ -1,16 +1,35 @@ /************************************************************************** * - * $Id: mbgutil.h 1.21 2018/09/21 08:18:05Z martin REL_M $ + * $Id: mbgutil.h 1.30 2021/11/08 19:59:51Z martin.burnicki REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * - * Description: - * Definitions used with mbgutil.c. + * Definitions used with mbgutil.c. * * ----------------------------------------------------------------------- * $Log: mbgutil.h $ - * Revision 1.21 2018/09/21 08:18:05Z martin + * Revision 1.30 2021/11/08 19:59:51Z martin.burnicki + * Added definition MBG_SYN1588_TYPE_NAME. + * Revision 1.29 2021/10/05 09:11:44 martin + * Account for new definitions _MBG_API_ATTR_EXPORT and _MBG_API_ATTR_IMPORT. + * Revision 1.28 2021/09/13 09:35:10 martin + * Changed default 2-digit year limit from 1980 to 1970. + * Revision 1.27 2021/04/30 11:12:02 martin + * Re-added macro _mbg_strncpy() with proper doxygen comment. + * Revision 1.26 2021/04/29 14:48:07 martin + * Moved some inline functions here. + * Revision 1.25 2021/04/29 13:04:43 martin + * Moved common definitions for year limit here. + * Removed obsolete macro _mbg_strncpy(). + * Updated function prototypes. + * Revision 1.24 2021/03/22 10:13:43 martin + * Updated a bunch of comments. + * Revision 1.23 2020/02/27 13:56:40 martin + * Updated function prototypes/doxygen comments. + * Revision 1.22 2019/07/31 15:55:50 martin + * Updated function prototypes. + * Revision 1.21 2018/09/21 08:18:05 martin * New version code 0x0308, compatibility version still 0x0110. * Revision 1.20 2018/08/13 14:54:24Z martin * Updated function prototypes. @@ -105,11 +124,23 @@ #define _ext extern #endif +#if defined( MBGUTIL_STATIC_LIB ) + // We don't build/use a DLL. + #define _MBG_API_ATTR_VAR +#else + // We do build/use a DLL. + #ifdef _MBGUTIL + #define _MBG_API_ATTR_VAR _MBG_API_ATTR_EXPORT + #else + #define _MBG_API_ATTR_VAR _MBG_API_ATTR_IMPORT + #endif +#endif + /* Start of header body */ #if defined( _USE_PACK ) - #pragma pack( 1 ) // set byte alignment + #pragma pack( 1 ) // Set byte alignment. #define _USING_BYTE_ALIGNMENT #endif @@ -119,12 +150,113 @@ extern "C" { #endif -// The macro below can be used to simplify the API call if -// a string variable is used rather than a char *. +#define MBG_SYN1588_TYPE_NAME "SYN1588" + + + +/** + * @brief A macro to simplify calls to ::mbg_strncpy. + * + * Can be used whenever a string variable is used rather than a char *. + */ #define _mbg_strncpy( _s, _src ) \ mbg_strncpy( _s, sizeof( _s ), _src ) + +#if !defined( MBG_EXP_YEAR_LIMIT_DEFAULT ) + /** + * @brief The default year limit when converting 2 digit year numbers to 4 digits. + */ + #define MBG_EXP_YEAR_LIMIT_DEFAULT 1970 +#endif + + +/** + * @brief A global variable used when converting 2 digit year numbers to 4 digits. + * + * Can be passed to all calls to ::mbg_exp_year to get + * the same conversion results across the whole application. + * + * Defaults to ::MBG_EXP_YEAR_LIMIT_DEFAULT, but can be changed at runtime. + */ +_ext _MBG_API_ATTR_VAR int mbg_exp_year_limit +#ifdef _DO_INIT + = MBG_EXP_YEAR_LIMIT_DEFAULT +#endif +; + + + +#if MBG_TGT_HAS_64BIT_TYPES + +static __mbg_inline +/** + * @brief Convert a @ref PCPS_TIME_STAMP to a 64 bit number. + * + * The 64 bit binary timestamp is composed of 32 bit seconds + * in the high part, and 32 bit binary fractions in the low part, + * so it can easily be used in computations. + * + * @param[in] p_ts Pointer to the ::PCPS_TIME_STAMP to be converted. + * + * @return The 64 bit timestamp. + * + * @see ::uint64_to_pcps_time_stamp + */ +uint64_t pcps_time_stamp_to_uint64( const PCPS_TIME_STAMP *p_ts ) +{ + return ( ( (uint64_t) p_ts->sec ) << 32 ) + p_ts->frac; + +} // pcps_time_stamp_to_uint64 + + + +static __mbg_inline +/** + * @brief Convert a composed 64 bit time stamp to a @ref PCPS_TIME_STAMP. + * + * The 64 bit number which can easily be used in computations + * is split into 32 bit seconds and 32 bit binary fractions. + * + * @param[out] p_ts Address of the ::PCPS_TIME_STAMP to take the result. + * @param[in] n The composed 64 bit binary timestamp. + * + * @see ::pcps_time_stamp_to_uint64 + */ +void uint64_to_pcps_time_stamp( PCPS_TIME_STAMP *p_ts, uint64_t n ) +{ + p_ts->sec = (uint32_t) ( n >> 32 ); + p_ts->frac = (uint32_t) ( n & 0xFFFFFFFFUL ); + +} // uint64_to_pcps_time_stamp + + + +static __mbg_inline +/** + * @brief Compute the difference between two ::PCPS_TIME_STAMP values. + * + * @param[in] p_ts Pointer to the current time stamp. + * @param[in] p_prv_ts Pointer to a previous time stamp. + * + * @return The time difference as double, in microseconds. + */ +double delta_timestamp_us( const PCPS_TIME_STAMP *p_ts, const PCPS_TIME_STAMP *p_prv_ts ) +{ + uint64_t ts = pcps_time_stamp_to_uint64( p_ts ); + uint64_t prv_ts = pcps_time_stamp_to_uint64( p_prv_ts ); + + // We divide by MBG_FRAC32_UNITS_PER_SEC to get the correct fractions + // and we multiply by 1E6 to get the result in microseconds. + return (double) ( (int64_t) ( ts - prv_ts ) ) * 1E6 / MBG_FRAC32_UNITS_PER_SEC; + +} // delta_timestamp_us + +#endif + + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ @@ -133,13 +265,13 @@ extern "C" { /** * @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 + * If this library is used as a DLL/shared object library, 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 + * @return The version number. * * @see ::mbgutil_check_version * @see ::MBGUTIL_VERSION defined in mbgutil.h @@ -149,16 +281,16 @@ extern "C" { /** * @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 + * If this library is used as a DLL/shared object library, 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 ::MBGUTIL_VERSION - * from the mbgutil.h file version used to build the application + * from the mbgutil.h file version used to build the application. * - * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE + * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE. * * @see ::mbgutil_get_version * @see ::MBGUTIL_VERSION defined in mbgutil.h @@ -166,429 +298,459 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbgutil_check_version( int header_version ) ; /** - * @brief A portable, safe implementation of snprintf() + * @brief A portable, safer implementation of snprintf(). * * The output string buffer is in any case properly terminated by 0. - * For a detailed description see ::vsnprintf_safe + * For a detailed description see ::vsnprintf_safe. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] fmt Format string according to subsequent parameters - * @param[in] ... Variable argument list according to the format string + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] fmt Format string according to subsequent parameters. + * @param[in] ... Variable argument list according to the @p fmt format string. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::vsnprintf_safe * @see ::snprintf_safe */ - _MBG_API_ATTR int __attribute__( ( format( printf, 3, 4 ) ) ) _MBG_API mbg_snprintf( char *s, size_t max_len, const char * fmt, ... ) ; + __attribute__( ( format( printf, 3, 4 ) ) ) _MBG_API_ATTR int _MBG_API mbg_snprintf( char *s, size_t max_len, const char * fmt, ... ) ; /** - * @brief A portable, safe implementation of strncpy() + * @brief A portable, safe implementation of strncpy(). * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the destination string buffer - * @param[in] max_len Size of the destination string buffer - * @param[in] src Pointer to the source string buffer + * @param[out] s Pointer to the destination string buffer. + * @param[in] max_len Size of the destination string buffer. + * @param[in] src Pointer to the source string buffer. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _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 + * @brief Write a character multiple times to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] c The character to write to the output buffer - * @param[in] n The number of characters to write to the output buffer + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] c The character to write to the output buffer. + * @param[in] 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 + * @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 ) ; /** - * @brief Write a short date string "dd.mm." to a string buffer + * @brief Write a short date string "dd.mm." to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] mday Day-of-month number, 1..31 - * @param[in] month Month number, 1..12 + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] mday Day-of-month number, 1..31. + * @param[in] month Month number, 1..12. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_date_short( char *s, int max_len, int mday, int month ) ; /** - * @brief Write a date string "dd.mm.yyyy" to a string buffer + * @brief Write a date string "dd.mm.yyyy" to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] mday Day-of-month number, 1..31 - * @param[in] month Month number, 1..12 - * @param[in] year Year number + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] mday Day-of-month number, 1..31. + * @param[in] month Month number, 1..12. + * @param[in] year Year number. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_date( char *s, int max_len, int mday, int month, int year ) ; /** - * @brief Write a short time string "hh:mm" to a string buffer + * @brief Write a short time string "hh:mm" to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] hour Hours number, 0..23 - * @param[in] min Minutes number, 0..59 + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] hour Hours number, 0..23. + * @param[in] min Minutes number, 0..59. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_time_short( char *s, int max_len, int hour, int min ) ; /** - * @brief Write a time string "hh:mm:ss" to a string buffer + * @brief Write a time string "hh:mm:ss" to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] hour Hours number, 0..23 - * @param[in] min Minutes number, 0..59 - * @param[in] sec Seconds number, 0..59, or 60 in case of leap second + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] hour Hours number, 0..23. + * @param[in] min Minutes number, 0..59. + * @param[in] sec Seconds number, 0..59, or 60 in case of leap second. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_time( char *s, int max_len, int hour, int min, int sec ) ; /** - * @brief Write a long time string "hh:mm:ss.cc" to a string buffer + * @brief Write a long time string "hh:mm:ss.cc" to a string buffer. * * Include 100ths of seconds. * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] hour Hours number, 0..23 - * @param[in] min Minutes number, 0..59 - * @param[in] sec Seconds number, 0..59, or 60 in case of leap second - * @param[in] sec100 Hundreths of seconds, 0..99 + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] hour Hours number, 0..23. + * @param[in] min Minutes number, 0..59. + * @param[in] sec Seconds number, 0..59, or 60 in case of leap second. + * @param[in] sec100 Hundreths of seconds, 0..99. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_time_long( char *s, int max_len, int hour, int min, int sec, int sec100 ) ; /** - * @brief Write a full date and time string to a string buffer + * @brief Write a full date and time string to a string buffer. * * The number of space characters between date and time * is determined by the global variable ::mbg_date_time_dist. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::TM_GPS structure providing date and time + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::TM_GPS structure providing date and time. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_tm_gps_date_time( char *s, int max_len, const TM_GPS *pt ) ; /** - * @brief Write the short date given as ::PCPS_TIME structure to a string buffer + * @brief Write the short date given as ::PCPS_TIME structure to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_date_short( char *s, int max_len, const PCPS_TIME *pt ) ; /** - * @brief Write the date given as ::PCPS_TIME structure to a string buffer + * @brief Write the date given as ::PCPS_TIME structure to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_date( char *s, int max_len, const PCPS_TIME *pt ) ; /** - * @brief Write the short time given as ::PCPS_TIME structure to a string buffer + * @brief Write the short time given as ::PCPS_TIME structure to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time_short( char *s, int max_len, const PCPS_TIME *pt ) ; /** - * @brief Write the time given as ::PCPS_TIME structure to a string buffer + * @brief Write the time given as ::PCPS_TIME structure to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time( char *s, int max_len, const PCPS_TIME *pt ) ; /** - * @brief Write the time including sec100ths given as ::PCPS_TIME structure to a string buffer + * @brief Write the time including sec100ths given as ::PCPS_TIME structure to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time_long( char *s, int max_len, const PCPS_TIME *pt ) ; /** - * @brief Write date and time given as ::PCPS_TIME structure to a string buffer + * @brief Write date and time given as ::PCPS_TIME structure to a string buffer. * * The number of space characters between date and time * is determined by the global variable ::mbg_date_time_dist. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time - * @param[in] tz_str Optional time zone string to be appended, currently not used, may be NULL + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time. + * @param[in] tz_str Optional time zone string to be appended, currently not used, may be @a NULL. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_date_time( char *s, int max_len, const PCPS_TIME *pt, const char *tz_str ) ; /** - * @brief Write date derived from seconds-since-epoch to a string buffer + * @brief Write date derived from seconds-since-epoch to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] sec Number of seconds since the epoch to be converted to date and time + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] sec Number of seconds since the epoch to be converted to date and time. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ - _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date( char *s, int max_len, uint32_t sec ) ; + _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date( char *s, int max_len, PCPS_SECONDS sec ) ; /** - * @brief Write time derived from seconds-since-epoch to a string buffer + * @brief Write time derived from seconds-since-epoch to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] sec Number of seconds since the epoch to be converted to date and time + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] sec Number of seconds since the epoch to be converted to date and time. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ - _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_time( char *s, int max_len, PCPS_SECONDS sec ) ; /** - * @brief Write UTC date and time given as ::PCPS_HR_TIME structure to a string buffer + * @brief Write %UTC date and time given as ::PCPS_HR_TIME structure to a string buffer. * * The number of space characters between date and time * is determined by the global variable ::mbg_date_time_dist. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date_time_utc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; /** - * @brief Write local date and time given as ::PCPS_HR_TIME structure to a string buffer + * @brief Write local date and time given as ::PCPS_HR_TIME structure to a string buffer. * * The number of space characters between date and time * is determined by the global variable ::mbg_date_time_dist. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date_time_loc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; /** - * @brief Print binary ::PCPS_FRAC_32 fractions in decimal to a string buffer + * @brief Print binary ::PCPS_FRAC_32 fractions in decimal to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] frac Binary fractions of a second in ::PCPS_FRAC_32 format + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] frac Binary fractions of a second in ::PCPS_FRAC_32 format. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ - _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_frac( char *s, int max_len, PCPS_FRAC_32 frac ) ; /** - * @brief Print the UTC offset from a ::PCPS_HR_TIME structure to a string buffer + * @brief Print the %UTC offset from a ::PCPS_HR_TIME structure to a string buffer. * * The output format is sign - hours - minutes, e.g. "+01:45h". * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date, and UTC offset - * @param[in] info An informational text to be prepended + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date, and %UTC offset. + * @param[in] info An informational text to be prepended. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _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 ) ; /** - * @brief Write a high resolution UTC time stamp including fractions to a string buffer + * @brief Write a high resolution %UTC time stamp including fractions to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_tstamp_utc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; /** - * @brief Write a high resolution local time stamp including fractions to a string buffer + * @brief Write a high resolution local time stamp including fractions to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_tstamp_loc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; /** - * @brief Write a raw high resolution time stamp to a string buffer + * @brief Write a raw high resolution time stamp to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_tstamp_raw( char *s, int max_len, const PCPS_TIME_STAMP *pt ) ; /** - * @brief Write a raw high resolution time stamp plus converted local time to a string buffer + * @brief Write a raw high resolution time stamp plus converted local time to a string buffer. * * The output string also has the time status code appended as hex number. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_raw( char *s, int max_len, const PCPS_HR_TIME *pt ) ; /** - * @brief Write time capture / user capture time stamp to a string buffer + * @brief Write time capture / user capture time stamp to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pt Pointer to a ::PCPS_HR_TIME structure containing a user capture event + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure containing a user capture event. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_ucap( char *s, int max_len, const PCPS_HR_TIME *pt ) ; /** - * @brief Write a geographic coordinate in degrees - minutes - seconds to a string buffer + * @brief Write a geographic coordinate in degrees - minutes - seconds to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] pdms Pointer to a ::DMS structure containing the coordinate - * @param[in] prec Number of digits of the geographic seconds after the decimal separator + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] pdms Pointer to a ::DMS structure containing the coordinate. + * @param[in] prec Number of digits of the geographic seconds after the decimal separator. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pos_dms( char *s, int max_len, const DMS *pdms, int prec ) ; /** - * @brief Write a position's altitude parameter to a string buffer + * @brief Write a position's altitude parameter to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] alt The altitude parameter, in meters + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] alt The altitude parameter, in meters. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pos_alt( char *s, int max_len, double alt ) ; /** - * @brief Write geographic coordinates to a string buffer + * @brief Write geographic coordinates to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] ppos Pointer to a ::POS structure containing the coordinates - * @param[in] prec Number of digits of the geographic seconds after the decimal separator + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] ppos Pointer to a ::POS structure containing the coordinates. + * @param[in] prec Number of digits of the geographic seconds after the decimal separator. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_pos( char *s, int max_len, const POS *ppos, int prec ) ; /** - * @brief Write device info to a string buffer + * @brief Write device info to a string buffer. * * The output string buffer is in any case properly terminated by 0. * - * @param[out] s Pointer to the output buffer - * @param[in] max_len Size of the output buffer - * @param[in] short_name Short device name, e.g. in ::MBG_DEV_NAME format - * @param[in] fw_rev_num The firmware revision number - * @param[in] asic_ver_num The ASIC version number + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] short_name Short device name, e.g. in ::MBG_DEV_NAME format. + * @param[in] fw_rev_num The firmware revision number. + * @param[in] asic_ver_num The ASIC version number. * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. */ _MBG_API_ATTR int _MBG_API mbg_str_dev_name( char *s, int max_len, const char *short_name, uint16_t fw_rev_num, PCI_ASIC_VERSION asic_ver_num ) ; @@ -601,7 +763,7 @@ extern "C" { #if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment + #pragma pack() // Set default alignment. #undef _USING_BYTE_ALIGNMENT #endif @@ -610,6 +772,7 @@ extern "C" { #undef _ext #undef _DO_INIT +#undef _MBG_API_ATTR_VAR #endif /* _MBGUTIL_H */ diff --git a/mbglib/common/myutil.h b/mbglib/common/myutil.h index 1f05d7a..7a778c2 100644 --- a/mbglib/common/myutil.h +++ b/mbglib/common/myutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: myutil.h 1.22 2018/11/21 16:04:27Z martin REL_M $ + * $Id: myutil.h 1.23 2019/08/09 12:04:12Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: myutil.h $ - * Revision 1.22 2018/11/21 16:04:27Z martin + * Revision 1.23 2019/08/09 12:04:12Z martin + * Added _inrange_s() macro and associated structures. + * Updated some doxygen comments. + * Revision 1.22 2018/11/21 16:04:27 martin * Doxygen fixes. * Revision 1.21 2018/11/01 11:10:57 martin * Updated function prototypes. @@ -66,7 +69,7 @@ #include <use_pack.h> -// _CS_FAR should be define far if the csum of far data +// _CS_FAR should be defined far if the csum of far data // structures must be computed #if !defined( _CSFAR ) #define _CSFAR @@ -94,7 +97,7 @@ #define _frac( _x ) ( ( (_x) == 0.0 ) ? 0.0 : ( (_x) - (double) ( (long) (_x) ) ) ) #endif - +/// Return a pointer to the end of a string. #define _eos( _s ) ( &(_s)[strlen( _s )] ) #if !defined( MIN ) @@ -138,44 +141,99 @@ typedef union #endif -// compute the csum of a structure +/// Compute the checksum of a structure. #define _csum( _p ) checksum( (void _CSFAR *)(_p), sizeof( *(_p) ) ) -// set a structure's csum +/// Set a structure's checksum, i.e. the csum field. #define _set_csum( _p ) (_p)->csum = _csum( (_p) ) -// compare a structure's computed csum with its csum field +/// Compare a structure's computed checksum with its csum field. #define _valid_csum( _p ) ( (_p)->csum == _csum( (_p) ) ) -// check if a value is in range +/// Generic check if a value is in range. #define _inrange( _val, _min, _max ) \ ( ( (_val) >= (_min) ) && ( (_val) <= (_max) ) ) -// Return a bit mask with (_n) LSBs set to 1 + +/** + * @brief A structure used to define a set of limits of type 'double'. + */ +typedef struct +{ + double min_val; + double max_val; + +} LIMITS_D; + + +/** + * @brief A structure used to define a set of limits of type 'long'. + * + */ +typedef struct +{ + long min_val; + long max_val; + +} LIMITS_L; + + +/** + * @brief A structure used to define a set of limits of type 'int'. + * + */ +typedef struct +{ + int min_val; + int max_val; + +} LIMITS_I; + + +/** + * @brief Check if a value is in a given range specified by a structure. + * + * @param[in] _val The value to be checked. + * @param[in] _p Address of a structure defining the limits. + * + * @see ::LIMITS_D + * @see ::LIMITS_L + * @see ::LIMITS_I + */ +#define _inrange_s( _val, _p ) \ + ( ( (_val) >= (_p)->min_val ) && ( (_val) <= (_p)->max_val ) ) + + + +/// Return a bit mask with @a n LSBs set to 1. #define _mask( _n ) \ ( ( 1UL << (_n) ) - 1 ) -// Return a bit mask with the (_i)th LSB set to 1 +/// Return a bit mask with the @a i th LSB set to 1. #define _idx_bit( _i ) \ ( 1UL << (_i) ) -// Check if the (_i)th bit is set in a mask (_msk) +/// Check if the @a i th bit is set in a mask @a _msk. #define _is_supported( _i, _msk ) \ ( ( (_msk) & _idx_bit( _i ) ) != 0 ) -// return the sign of a number +/// Return the sign of a number. #define _sgn( _x ) ( ( ( _x ) < 0 ) ? -1 : 1 ) -// macro for linear interpolation y = _m * x + _b between two points ( X1; Y1 ), ( X2; Y2 ) +/// Macro for linear interpolation y = _m * x + _b between two points ( X1; Y1 ), ( X2; Y2 ) #define _m( _Y1, _X1, _Y2, _X2 ) ( ( _Y2 -_Y1 ) / ( _X2 -_X1 ) ) -#define _b( _Y1, _X1, _Y2, _X2 ) ( ( ( _Y1 * _X2 ) - ( _Y2 * _X1 ) ) / ( _X2 -_X1 ) ) +#define _b( _Y1, _X1, _Y2, _X2 ) ( ( ( _Y1 * _X2 ) - ( _Y2 * _X1 ) ) / ( _X2 -_X1 ) ) -/* - * The macro below copies a string, taking care not to - * write past the end of the destination buffer, and - * making sure the string is terminated by 0. +/** + * @brief Copy a string safely. + * + * Copy a string while taking care not to write past the + * end of the destination buffer, and making sure the string + * is properly terminated by 0. + * + * @see ::sn_cpy_str_safe */ #define _strncpy_0( _dst, _src ) \ { \ diff --git a/mbglib/common/nanotime.c b/mbglib/common/nanotime.c index ed57cfd..8b0ff8c 100644 --- a/mbglib/common/nanotime.c +++ b/mbglib/common/nanotime.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: nanotime.c 1.6 2018/12/11 11:55:06Z martin REL_M $ + * $Id: nanotime.c 1.10 2021/10/20 07:27:18Z thomas-b REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,7 +11,20 @@ * * ----------------------------------------------------------------------- * $Log: nanotime.c $ - * Revision 1.6 2018/12/11 11:55:06Z martin + * Revision 1.10 2021/10/20 07:27:18Z thomas-b + * Fixed conversion between fractions of TM_GPS and ns in NANO_TIME_64 + * Revision 1.9 2019/08/21 10:34:55 thomas-b + * Call mbg_mktime64 in conversion from and to NANO_TIME_64, because secs value is int64_t, anyway + * Fixed function call; it does not expect mday - 1 any longer + * Revision 1.8 2019/08/19 10:23:46 martin + * Updated nano_time_64_to_tm_gps() and tm_gps_to_nano_time_64(). + * ATTENTION: tm_gps_to_nano_time_64() now returns MBG_SUCCESS + * on success, or or some negative Meinberg error code, as usual, whereas + * the previous previous version of the function returned 1 on success and + * 0 in case of error, so the conditions to check the return code have to be inverted! + * Revision 1.7 2019/07/08 12:46:16 thomas-b + * Added conversion of the fractions (ns) in tm_gps_to_nano_time_64 and vice versa + * Revision 1.6 2018/12/11 11:55:06 martin * Fixed compiler warnings on Windows. * Revision 1.5 2018/11/21 11:24:19Z martin * Exclude non-essential header files and functions from firmware builds. @@ -334,15 +347,14 @@ void str_ms_to_nano_time_64( const char *s, NANO_TIME_64 *p ) * @param[out] tm_gps The ::TM_GPS to be filled * @param[in] nt The ::NANO_TIME_64 to be converted * - * @return 1 on success, 0 on error + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::tm_gps_to_nano_time_64 */ int nano_time_64_to_tm_gps( TM_GPS *tm_gps, const NANO_TIME_64 *nt ) { struct tm tm = { 0 }; - time_t t = cvt_to_time_t( nt->secs ); - int rc = mbg_gmtime( &tm, &t ); + int rc = mbg_gmtime64( &tm, &nt->secs ); if ( mbg_rc_is_success( rc ) ) { @@ -354,10 +366,12 @@ int nano_time_64_to_tm_gps( TM_GPS *tm_gps, const NANO_TIME_64 *nt ) tm_gps->hour = tm.tm_hour; tm_gps->min = tm.tm_min; tm_gps->sec = tm.tm_sec; - tm_gps->frac = 0; //### TODO convert fractions -#if defined( MBG_TGT_POSIX ) - tm_gps->offs_from_utc = tm.tm_gmtoff; -#endif + + // divide nanoseconds by 100 to get fractions + // fractions should have 100ns resolution due to 10 MHz clock tick + tm_gps->frac = (int32_t)(nt->nano_secs / 100); + + tm_gps->offs_from_utc = 0; } return rc; @@ -373,22 +387,22 @@ int nano_time_64_to_tm_gps( TM_GPS *tm_gps, const NANO_TIME_64 *nt ) * @param[out] nt The ::NANO_TIME_64 to be filled * @param[in] tm The ::TM_GPS to be converted * - * @return 1 on success, 0 on error + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::nano_time_64_to_tm_gps */ int tm_gps_to_nano_time_64( NANO_TIME_64 *nt, const TM_GPS *tm ) { - time_t t = mbg_mktime( tm->year - 1900, tm->month - 1, tm->mday - 1, tm->hour, tm->min, tm->sec ); + int rc; - if ( t != (time_t) -1 ) - { - nt->secs = (uint64_t) t; - nt->nano_secs = 0; //### TODO: convert fractions - return 1; - } + rc = mbg_mktime64( &nt->secs, tm->year - 1900, tm->month - 1, tm->mday, tm->hour, tm->min, tm->sec ); + + // multiply fractions by 100 to get nanoseconds + // fractions should have 100ns resolution due to 10 MHz clock tick + if ( mbg_rc_is_success( rc ) ) + nt->nano_secs = (int64_t)tm->frac * 100; - return 0; + return rc; } // tm_gps_to_nano_time_64 diff --git a/mbglib/common/nanotime.h b/mbglib/common/nanotime.h index 5494e4c..942f3c9 100644 --- a/mbglib/common/nanotime.h +++ b/mbglib/common/nanotime.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: nanotime.h 1.3 2018/11/21 11:27:26Z martin REL_M $ + * $Id: nanotime.h 1.4 2019/08/19 11:10:02Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: nanotime.h $ - * Revision 1.3 2018/11/21 11:27:26Z martin + * Revision 1.4 2019/08/19 11:10:02Z martin + * Updated doxygen comments. + * Revision 1.3 2018/11/21 11:27:26 martin * Include stdlib.h to provide size_t. * Revision 1.2 2018/07/16 12:40:55 martin * Include gpsdefs.h. @@ -146,7 +148,7 @@ extern "C" { * @param[out] tm_gps The ::TM_GPS to be filled * @param[in] nt The ::NANO_TIME_64 to be converted * - * @return 1 on success, 0 on error + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::tm_gps_to_nano_time_64 */ @@ -158,7 +160,7 @@ extern "C" { * @param[out] nt The ::NANO_TIME_64 to be filled * @param[in] tm The ::TM_GPS to be converted * - * @return 1 on success, 0 on error + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::nano_time_64_to_tm_gps */ diff --git a/mbglib/common/pci_asic.h b/mbglib/common/pci_asic.h index 5a3e3d2..896c538 100644 --- a/mbglib/common/pci_asic.h +++ b/mbglib/common/pci_asic.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pci_asic.h 1.31 2018/06/25 12:32:19Z martin REL_M $ + * $Id: pci_asic.h 1.32 2021/03/22 22:40:24Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: pci_asic.h $ - * Revision 1.31 2018/06/25 12:32:19Z martin + * Revision 1.32 2021/03/22 22:40:24Z martin + * Updated some comments. + * Revision 1.31 2018/06/25 12:32:19 martin * Added PCPS_ASIC_STR_FMT format specifier. * Revision 1.30 2018/03/27 12:39:46 martin * Updated minor version for PZF180PEX to 0x01. @@ -111,7 +113,7 @@ /* Start of header body */ #if defined( _USE_PACK ) - #pragma pack( 1 ) // set byte alignment + #pragma pack( 1 ) // Set byte alignment. #define _USING_BYTE_ALIGNMENT #endif @@ -121,7 +123,7 @@ extern "C" { /** - * @brief Set of PCI ASIC registers which are writeable once after power-up + * @brief Set of PCI ASIC registers which are writeable once after power-up. **/ typedef struct { @@ -133,7 +135,7 @@ typedef struct /** - * @brief A PCI ASIC register as 32, 16, or 8 bit accessible union + * @brief A PCI ASIC register as 32, 16, or 8 bit accessible union. */ typedef union { @@ -146,7 +148,7 @@ typedef union /** - * @brief A data type to hold the PCI ASIC version code + * @brief A data type to hold the PCI ASIC version code. */ typedef uint32_t PCI_ASIC_VERSION; @@ -155,7 +157,7 @@ typedef uint32_t PCI_ASIC_VERSION; /** - * @brief A data type to hold the PCI ASIC feature flags mask + * @brief A data type to hold the PCI ASIC feature flags mask. * * @see @ref PCI_ASIC_FEATURE_MASKS */ @@ -166,21 +168,21 @@ typedef uint32_t PCI_ASIC_FEATURES; /** - * @brief Bit masks used with ::PCI_ASIC_FEATURES + * @defgroup PCI_ASIC_FEATURE_MASKS Bit masks used with @ref PCI_ASIC_FEATURES * * @see ::PCI_ASIC_FEATURES * - * @anchor PCI_ASIC_FEATURE_MASKS @{ */ + * @{ */ -#define PCI_ASIC_HAS_MM_IO 0x0001 ///< The device supports memory mapped I/O -#define PCI_ASIC_HAS_PGMB_IRQ 0x0002 ///< The device supports programmable interrupts (yet not used) +#define PCI_ASIC_HAS_MM_IO 0x0001 ///< The device supports memory mapped I/O. +#define PCI_ASIC_HAS_PGMB_IRQ 0x0002 ///< The device supports programmable interrupts (yet not used). -/** @} anchor PCI_ASIC_FEATURE_MASKS */ +/** @} defgroup PCI_ASIC_FEATURE_MASKS */ /** - * @brief The addon-data part of a PCI ASIC + * @brief The addon-data part of a PCI ASIC. */ typedef union { @@ -193,34 +195,34 @@ typedef union /** - * @brief Register layout of a PCI ASIC + * @brief Register layout of a PCI ASIC. */ typedef struct { - PCI_ASIC_CFG cfg; ///< Registers which are writeable from add-on once after power-up - PCI_ASIC_VERSION raw_version; ///< Raw version code - PCI_ASIC_FEATURES features; ///< PCI ASIC feature mask, see @ref PCI_ASIC_FEATURE_MASKS - PCI_ASIC_REG status_port; ///< The status port register - PCI_ASIC_REG control_status; ///< See @ref PCI_ASIC_CONTROL_STATUS_MASKS - PCI_ASIC_REG pci_data; ///< Register used to pass byte from PCI bus to add-on side - PCI_ASIC_REG reserved_1; ///< Currently not implemented / used + PCI_ASIC_CFG cfg; ///< Registers that are writeable from add-on once after power-up. + PCI_ASIC_VERSION raw_version; ///< Raw version code. + PCI_ASIC_FEATURES features; ///< PCI ASIC feature mask, see @ref PCI_ASIC_FEATURE_MASKS. + PCI_ASIC_REG status_port; ///< The status port register. + PCI_ASIC_REG control_status; ///< See @ref PCI_ASIC_CONTROL_STATUS_MASKS. + PCI_ASIC_REG pci_data; ///< Register used to pass byte from PCI bus to add-on side. + PCI_ASIC_REG reserved_1; ///< Currently not implemented / used. - PCI_ASIC_ADDON_DATA addon_data; ///< Register set used to return data from add-on to PCI bus - PCI_ASIC_ADDON_DATA reserved_2; ///< Currently not implemented / used + PCI_ASIC_ADDON_DATA addon_data; ///< Register set used to return data from add-on to PCI bus. + PCI_ASIC_ADDON_DATA reserved_2; ///< Currently not implemented / used. } PCI_ASIC; /** - * @brief Bit masks used with ::PCI_ASIC::control_status + * @defgroup PCI_ASIC_CONTROL_STATUS_MASKS Bit masks used with @ref PCI_ASIC::control_status. * * @see ::PCI_ASIC * - * @anchor PCI_ASIC_CONTROL_STATUS_MASKS @{ */ + * @{ */ /** - * @brief Add-on IRQ flag + * @brief Add-on IRQ flag. * * The IRQ flag for the add-on side is set whenever data is * written to the cmd register. It is cleared if the add-on @@ -231,7 +233,7 @@ typedef struct #define PCI_ASIC_ADD_ON_IRQF 0x00000001UL /** - * @brief PCI IRQ flag + * @brief PCI IRQ flag. * * The IRQ flag for the PCI bus is set whenever the add-on * microcontroller asserts the ASIC's /PCI_IRQ line, or the @@ -243,21 +245,25 @@ typedef struct // NOTE All other bits are reserved for future use. -/** @} anchor PCI_ASIC_CONTROL_STATUS_MASKS */ +/** @} defgroup PCI_ASIC_CONTROL_STATUS_MASKS */ /** - * @brief PCI address range + * @brief PCI address range. * - * The ASIC's address decoder always decodes 8 bits, so - * each device must request at least this number of + * The address decoder of the ASIC always decodes 8 bits, + * so each device must request at least this number of * addresses from the PCI BIOS. */ #define PCI_ASIC_ADDR_RANGE 0x100U -// Initializers for device configurations + +/** + * @defgroup group_pci_initializers Initializers for device configurations + * + * @{ */ #define PCPS_DEV_CLASS_CODE 0x08800000UL #define PCI_ASIC_BADR0_INIT ( ~( PCI_ASIC_ADDR_RANGE - 1 ) | 0x01 ) @@ -312,10 +318,12 @@ typedef struct _hilo_16( PCI_DEV_TCR511PCI ) \ } +/** @} defgroup group_pci_initializers */ + /** - * @brief Version number conversion macro + * @brief Version number conversion macro. * * Handling of the version numbers of the PCI interface * chips has changed between the ASICs used for standard PCI @@ -324,7 +332,7 @@ typedef struct * * This macro can be used to convert both types of * version number into the same format so that the - * version numbers can be handled in the same way + * version numbers can be handled in the same way. */ #define _convert_asic_version_number( _n ) \ ( ( (_n) < 0x100 ) ? ( (_n) << 8 ) : (_n) ) @@ -334,14 +342,14 @@ typedef struct #define PCPS_ASIC_STR_FMT "%u.%02X" // TODO Or should this be "%u.%02u" /** - * @brief Extract the major part of an ASIC version number + * @brief Extract the major part of an ASIC version number. */ #define _pcps_asic_version_major( _v ) \ ( ( (_v) >> 8 ) & 0xFF ) /** - * @brief Extract the minor part of an ASIC version number + * @brief Extract the minor part of an ASIC version number. */ #define _pcps_asic_version_minor( _v ) \ ( (_v) & 0xFF ) @@ -349,7 +357,7 @@ typedef struct /** - * @brief Check whether a version number is correct and matches a required minimum version + * @brief Check whether a version number is correct and matches a required minimum version. */ #define _pcps_asic_version_greater_equal( _v, _v_major, _v_minor ) \ ( \ @@ -360,32 +368,32 @@ typedef struct /** - * @brief ASIC major version numbers + * @brief ASIC major version numbers. * * @see @ref PCI_ASIC_MINOR_VERSION_NUMBERS */ enum PCI_ASIC_MAJOR_VERSION_NUMBERS { - PCI_ASIC_MAJOR_PCI_0, ///< PCI ASIC with CRC bug - PCI_ASIC_MAJOR_PCI_1, ///< fixed version of PCI ASIC - PCI_ASIC_MAJOR_PEX511, ///< PEX EPLD for PEX511 - PCI_ASIC_MAJOR_GPS170PEX, ///< PEX EPLD for GPS170PEX - PCI_ASIC_MAJOR_TCR511PEX, ///< PEX EPLD for TCR511PEX - PCI_ASIC_MAJOR_PTP270PEX, ///< PEX EPLD for PTP270PEX - PCI_ASIC_MAJOR_FRC511PEX, ///< PEX EPLD for FRC511PEX - PCI_ASIC_MAJOR_TCR170PEX, ///< PEX EPLD for TCR170PEX - PCI_ASIC_MAJOR_GPS180PEX, ///< PEX EPLD for GPS180PEX/GPS180AMC - PCI_ASIC_MAJOR_TCR180PEX, ///< PEX EPLD for TCR180PEX - PCI_ASIC_MAJOR_PZF180PEX, ///< PEX EPLD for PZF180PEX - PCI_ASIC_MAJOR_GLN180PEX, ///< PEX EPLD for GLN180PEX - PCI_ASIC_MAJOR_GNS181PEX, ///< PEX EPLD for GNS181PEX - N_PCI_ASIC_MAJOR ///< the number of known codes + PCI_ASIC_MAJOR_PCI_0, ///< PCI ASIC with CRC bug. + PCI_ASIC_MAJOR_PCI_1, ///< Fixed version of PCI ASIC. + PCI_ASIC_MAJOR_PEX511, ///< PEX EPLD for PEX511. + PCI_ASIC_MAJOR_GPS170PEX, ///< PEX EPLD for GPS170PEX. + PCI_ASIC_MAJOR_TCR511PEX, ///< PEX EPLD for TCR511PEX. + PCI_ASIC_MAJOR_PTP270PEX, ///< PEX EPLD for PTP270PEX. + PCI_ASIC_MAJOR_FRC511PEX, ///< PEX EPLD for FRC511PEX. + PCI_ASIC_MAJOR_TCR170PEX, ///< PEX EPLD for TCR170PEX. + PCI_ASIC_MAJOR_GPS180PEX, ///< PEX EPLD for GPS180PEX/GPS180AMC. + PCI_ASIC_MAJOR_TCR180PEX, ///< PEX EPLD for TCR180PEX. + PCI_ASIC_MAJOR_PZF180PEX, ///< PEX EPLD for PZF180PEX. + PCI_ASIC_MAJOR_GLN180PEX, ///< PEX EPLD for GLN180PEX. + PCI_ASIC_MAJOR_GNS181PEX, ///< PEX EPLD for GNS181PEX. + N_PCI_ASIC_MAJOR ///< The number of known codes. }; /** - * @brief ASIC minor version definitions + * @defgroup PCI_ASIC_MINOR_VERSION_NUMBERS ASIC minor version definitions * * The minor number increases when a new EPLD image is released. * At least EPLD images with the defined "required minor" numbers @@ -394,7 +402,7 @@ enum PCI_ASIC_MAJOR_VERSION_NUMBERS * * @see ::PCI_ASIC_MAJOR_VERSION_NUMBERS * - * @anchor PCI_ASIC_MINOR_VERSION_NUMBERS @{ */ + * @{ */ #define PCI_ASIC_CURRENT_MINOR_PEX511 0x04 #define PCI_ASIC_REQUIRED_MINOR_PEX511 0x03 @@ -452,12 +460,12 @@ enum PCI_ASIC_MAJOR_VERSION_NUMBERS #define PCI_ASIC_CURRENT_MINOR_GNS181PEX 0x00 #define PCI_ASIC_REQUIRED_MINOR_GNS181PEX 0x00 -/** @} anchor PCI_ASIC_MINOR_VERSION_NUMBERS */ +/** @} defgroup PCI_ASIC_MINOR_VERSION_NUMBERS */ /** - * @brief A structure holding version information for a specific device + * @brief A structure holding version information for a specific device. * * @see ::DEFAULT_PCI_ASIC_VERSION_INFO_TABLE */ @@ -472,9 +480,9 @@ typedef struct /** - * @brief An initializer for a table of ASIC version information for all known devices + * @brief An initializer for a table of ASIC version information for all known devices. * - * @note GPS180AMC uses the same ASIC as GPS180PEX + * @note GPS180AMC uses the same ASIC as GPS180PEX. * * @see ::PCI_ASIC_VERSION_INFO */ @@ -511,7 +519,7 @@ typedef struct #if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment + #pragma pack() // Set default alignment. #undef _USING_BYTE_ALIGNMENT #endif diff --git a/mbglib/common/pcpsdefs.h b/mbglib/common/pcpsdefs.h index 0d36c5d..3e71254 100644 --- a/mbglib/common/pcpsdefs.h +++ b/mbglib/common/pcpsdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsdefs.h 1.64 2018/06/25 12:34:23Z martin REL_M $ + * $Id: pcpsdefs.h 1.70 2021/03/21 22:35:01Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,19 @@ * * ----------------------------------------------------------------------- * $Log: pcpsdefs.h $ - * Revision 1.64 2018/06/25 12:34:23Z martin + * Revision 1.70 2021/03/21 22:35:01Z martin + * Updated a bunch of comments. + * Revision 1.69 2021/03/18 11:08:15 martin + * Updated some comments. + * Revision 1.68 2021/03/16 12:21:35 martin + * Updated some comments. + * Revision 1.67 2021/03/12 11:08:26 martin + * Updated some comments. + * Revision 1.66 2021/03/11 16:13:45 martin + * Updated some byte swap macros. + * Revision 1.65 2019/07/31 15:41:02 martin + * Doxygen changes. + * Revision 1.64 2018/06/25 12:34:23 martin * Fixed spelling inside a comment. * Revision 1.63 2018/02/28 16:57:38Z martin * Replace references to frac_sec_from_bin() to bin_frac_32_to_dec_frac(). @@ -154,7 +166,7 @@ * size is in fact odd, which might lead to different sizes in C166 and * other environments. * Modifications were required in order to be able to configure IRIG - * settings of cards which provide both IRIG input and output. + * settings of devices which provide both IRIG input and output. * The existing codes have been renamed with .._RX.. and are used to * configure the IRIG receiver (input). New codes have been defined * used to configure the IRIG transmitter. @@ -228,7 +240,7 @@ * Removed PCPS_SERIAL_BYTES and PCPS_TZCODE_BYTES, may use sizeof() * the types instead. * New type PCPS_TIME_SET which can be used to write date and time - * to the clock. + * to the device. * Revision 1.6 2000/06/07 12:09:31 MARTIN * renamed PCPS_SERIAL_GROUP to PCPS_CFG_GROUP * renamed PCPS_ERR_SERIAL to PCPS_ERR_CFG @@ -280,7 +292,7 @@ /* Start of header body */ #if defined( _USE_PACK ) - #pragma pack( 1 ) // set byte alignment + #pragma pack( 1 ) // Set byte alignment. #define _USING_BYTE_ALIGNMENT #endif @@ -290,16 +302,16 @@ */ enum PCPS_REF_TYPES { - PCPS_REF_NONE, ///< unknown, or not defined + PCPS_REF_NONE, ///< Unknown, or not defined. PCPS_REF_DCF, ///< DCF77 long wave signal (Germany), see http://www.meinberg.de/english/info/dcf77.htm PCPS_REF_GPS, ///< GPS satellite system, see http://www.meinberg.de/english/info/gps.htm PCPS_REF_IRIG, ///< IRIG or similar time code, see http://www.meinberg.de/english/info/irig.htm - PCPS_REF_MSF, ///< MSF long wave signal (UK) - PCPS_REF_PTP, ///< PTP/IEEE1588 network protocol - PCPS_REF_FRC, ///< Free Running Clock - PCPS_REF_WWVB, ///< WWVB long wave signal (U.S.) - PCPS_REF_JJY, ///< JJY long wave signal (Japan) - N_PCPS_REF ///< number of defined ref time sources + PCPS_REF_MSF, ///< MSF long wave signal (UK). + PCPS_REF_PTP, ///< PTP/IEEE1588 network protocol. + PCPS_REF_FRC, ///< Free Running Clock. + PCPS_REF_WWVB, ///< WWVB long wave signal (U.S.). + PCPS_REF_JJY, ///< JJY long wave signal (Japan). + N_PCPS_REF ///< Number of defined ref time sources. }; @@ -325,7 +337,7 @@ enum PCPS_REF_TYPES /** - * @brief Initializer for an array of English reference type names + * @brief Initializer for an array of English reference type names. * * @see ::PCPS_REF_TYPES */ @@ -344,7 +356,7 @@ enum PCPS_REF_TYPES /** - * @brief Initializer for a multi-language array of reference type names + * @brief Initializer for a multi-language array of reference type names. * * @see ::PCPS_REF_TYPES */ @@ -364,7 +376,7 @@ enum PCPS_REF_TYPES /** - * @brief Meinberg PCI vendor ID (assigned by the PCI SIG) + * @brief Meinberg PCI vendor ID (assigned by the PCI SIG). * * @see @ref MEINBERG_PCI_DEVICE_IDS */ @@ -372,14 +384,14 @@ enum PCPS_REF_TYPES /** - * @brief PCI device IDs assigned by Meinberg + * @defgroup MEINBERG_PCI_DEVICE_IDS PCI device IDs assigned by Meinberg * * High byte: type of ref time source, see ::PCPS_REF_TYPES * 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 ) @@ -409,69 +421,75 @@ enum PCPS_REF_TYPES #define PCI_DEV_FRC511PEX ( ( PCPS_REF_FRC << 8 ) | 0x01 ) -/** @} anchor MEINBERG_PCI_DEVICE_IDS */ +/** @} defgroup MEINBERG_PCI_DEVICE_IDS */ /** * @defgroup group_status_port Definitions used with the status port * - * The status port register on bus-level cards reflects some hardware + * The status port register on bus-level devices 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). + * with the device (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 + * @note Must not be confused with @ref group_pcps_time_status which + * provides time synchronization status and associated information. * * @{ */ /** - * @brief Type of the status register port + * @brief Type of the status register port. + * + * @see @ref PCPS_STATUS_PORT_BIT_MASKS. */ -typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS +typedef uint8_t PCPS_STATUS_PORT; /** - * @brief Bit masks used with ::PCPS_STATUS_PORT + * @defgroup PCPS_STATUS_PORT_BIT_MASKS Bit masks used with PCPS_STATUS_PORT + * + * Used with ::PCPS_STATUS_PORT. * - * 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 - * and thus should be considered as deprecated. + * The flags ::PCPS_ST_SEC and ::PCPS_ST_MIN are cleared whenever the device + * is read, so they are not very reliable in multitasking environments and + * should therefore be considered deprecated. * * The ::PCPS_ST_IRQF flag was used with old ISA cards to check * if the device has generated an IRQ. * 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 particular card has generated an IRQ on the PC bus. + * if a particular device 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. + * to determine in a portable way whether a device 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 cards 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 */ +#define PCPS_ST_BUSY 0x01 ///< The device is busy filling the output buffer. +#define PCPS_ST_IRQF 0x02 ///< The device has generated an IRQ on the PC bus (ISA cards 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. -/** @} defgroup group_status_port */ +/** @} defgroup PCPS_STATUS_PORT_BIT_MASKS */ /** - * A format string to be used with snprintb() which is available on some Unix - * systems to print information held in a bit coded variable. + * @brief A format string to be used with snprintb(). + * + * The function snprintb() is available on some Unix systems + * to print information held in a bit coded variable. */ #define MBG_PCPS_FMT_STATUS \ "\177\20b\0FREER\0b\1DL_ENB\0b\2SYNCD\0b\3DL_ANN\0b\4UTC\0b\5LS_ANN\0b\6IFTM\0b\7INVT" \ "\0b\x08LS_ENB\0b\11ANT_FAIL\0b\x0aLS_ANN_NEG\0b\x0bSCALE_GPS\0b\x0cSCALE_TAI\0\0" +/** @} defgroup group_status_port */ + /** - * @brief Command codes used to communicate with bus level devices + * @defgroup PCPS_CMD_CODES Command codes used to communicate with bus level devices * * These commands are used for low level access to bus-level devices * manufactured by Meinberg. @@ -480,39 +498,39 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * * 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. + * If checking is required, 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 + * Some commands expect parameters to be passed to the device. In that + * case, the device 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. + * to the device exactly like a command byte. * * Refer to function ::pcps_write 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. + * time and status. Supported by all devices. * * - ::PCPS_GIVE_TIME_NOCLEAR<br> * Same as ::PCPS_GIVE_TIME but the bits ::PCPS_ST_SEC * and ::PCPS_ST_MIN of the status port are not cleared. - * Supported by all clocks except PC31/PS31 with + * Supported by all devices 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 + * of last synchronization of the onboard time, 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. + * used to read the current time with higher resolution. * ::_pcps_has_hr_time checks whether supported. * * - ::PCPS_GIVE_IRIG_TIME<br> @@ -521,20 +539,20 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * ::_pcps_has_irig_time checks whether supported. * * - ::PCPS_SET_TIME<br> - * Set the board date, time and status. This command + * Set the date, time and status on the device. 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 + * Send a high resolution time stamp to the device to + * configure a %UTC time when the device 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_has_event_time checks whether supported, + * requires custom GPS CERN firmware. * * - ::PCPS_IRQ_NONE<br> - * Disable the card's hardware IRQ<br> + * Disable the hardware IRQ of the device<br> * - ::PCPS_IRQ_1_SEC<br> * Enable hardware IRQs once per second<br> * - ::PCPS_IRQ_1_MIN<br> @@ -546,17 +564,17 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * * - ::PCPS_GET_SERIAL<br> * ::PCPS_SET_SERIAL<br> - * Deprecated. Read or write the configuration of a card's + * Deprecated. Read or write the configuration of the * serial port COM0 in ::PCPS_SERIAL format. * ::_pcps_has_serial checks whether supported. - * Newer cards should be configured using the structures ::RECEIVER_INFO, + * Newer devices should be configured using the structures ::RECEIVER_INFO, * ::PORT_INFO, and STR_TYPE_INFO. * ::_pcps_has_receiver_info checks whether these are supported. * * - ::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 + * These commands read or set time zone code onboard + * a DCF77 receiver, and should be used preferably * with older DCF77 receivers which have limited * support of different time zones. * ::_pcps_has_tzcode checks whether supported. @@ -572,8 +590,8 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * - ::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, + * reference time offset from %UTC for devices + * that can't determine the offset automatically, * e.g. from an IRIG input signal. * ::_pcps_has_ref_offs checks whether supported. * @@ -581,10 +599,10 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * ::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 + * When reading, the device returns an ::MBG_OPT_INFO * structure which contains the supported values, * plus the current settings. - * When writing, clocks accepts a ::MBG_OPT_SETTINGS + * When writing, the device accepts an ::MBG_OPT_SETTINGS * structure only which contain the desired settings * of the supported flags only. * ::_pcps_has_opt_flags checks whether supported. @@ -595,12 +613,12 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * ::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 + * When reading, the device 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_has_irig_tx + * When writing, the device accepts an ::IRIG_SETTINGS + * structure only, which only contain the new settings. + * ::_pcps_is_irig_rx and ::_pcps_has_irig_tx * check whether supported. * * - ::PCPS_GET_IRIG_CTRL_BITS<br> @@ -618,7 +636,7 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * ::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 + * status. The commands are only supported if the device * supports the ::RECEIVER_INFO structure and the flag * #GPS_HAS_SYNTH is set in the ::RECEIVER_INFO::features. * ::_pcps_has_synth checks whether supported. @@ -629,13 +647,13 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * ::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. + * commands can be used to check if the device + * responds properly. This is usually done by the + * device probe routine of a driver. * * - ::PCPS_GIVE_SERNUM<br> * Returns ::PCPS_FIFO_SIZE characters of the - * clock's serial number. + * serial number of the device. * ::_pcps_has_sernum checks whether supported. * * - ::PCPS_GENERIC_IO<br> @@ -654,11 +672,11 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * These commands are used by the functions * ::pcps_read_gps and ::pcps_write_gps * to read or write large data structures to - * Meinberg GPS plug-in clocks. + * Meinberg GPS plug-in devices. * ::_pcps_is_gps checks whether supported. * * - ::PCPS_CLR_UCAP_BUFF<br> - * Clear a clock's time capture buffer. + * Clear the time capture buffer onboard a device. * ::_pcps_can_clr_ucap_buff checks whether * supported. * @@ -673,7 +691,7 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * 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 returned structure is all 0. + * available, the returned structure is all 0. * ::_pcps_has_ucap checks whether supported. * * - ::PCPS_GET_CORR_INFO<br> @@ -693,9 +711,9 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * ::_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 have currently - * been saved. + * Read max. number of num event log entries which + * can be saved on the device, and how many entries + * have currently been saved. * ::_pcps_has_evt_log checks whether supported. * * - ::PCPS_FIRST_EVT_LOG_ENTRY<br> @@ -704,99 +722,100 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * ::_pcps_has_evt_log checks whether supported. * * - ::PCPS_FORCE_RESET<br> - * Resets the card's hardware. This may lock up the computer - * and thus should only be used by very specific applications. + * Resets the hardware of the device. This may lock up + * the computer and thus should only be used by very + * specific applications. * - * @anchor PCPS_CMD_CODES @{ */ + * @{ */ -#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 (deprecated) -#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_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 (deprecated). +#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 ///< (-w) Set on-board time, see ::PCPS_STIME. Returns ::MBG_ERR_STIME on error. -#define PCPS_SET_EVENT_TIME 0x14 ///< (-w) Write event time as ::PCPS_TIME_STAMP, only if ::_pcps_has_event_time +#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 ///< (-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_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 ///< (r-) Read serial settings as ::PCPS_SERIAL, deprecated by ::PC_GPS_ALL_PORT_INFO -#define PCPS_SET_SERIAL 0x31 ///< (-w) Write serial settings as ::PCPS_SERIAL, deprecated by ::PC_GPS_PORT_SETTINGS_IDX, returns ::MBG_ERR_CFG on error +#define PCPS_GET_SERIAL 0x30 ///< (r-) Read serial settings as ::PCPS_SERIAL, deprecated by ::PC_GPS_ALL_PORT_INFO. +#define PCPS_SET_SERIAL 0x31 ///< (-w) Write serial settings as ::PCPS_SERIAL, deprecated by ::PC_GPS_PORT_SETTINGS_IDX, returns ::MBG_ERR_CFG on error. -#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, returns ::MBG_ERR_CFG on error +#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, returns ::MBG_ERR_CFG on error. -#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, returns ::MBG_ERR_CFG on error +#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, returns ::MBG_ERR_CFG on error. -#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, returns ::MBG_ERR_CFG on error +#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, returns ::MBG_ERR_CFG on error. -#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, returns ::MBG_ERR_CFG on error +#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, returns ::MBG_ERR_CFG on error. -#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, returns ::MBG_ERR_CFG on error +#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, returns ::MBG_ERR_CFG on error. -#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, returns ::MBG_ERR_CFG on error +#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, returns ::MBG_ERR_CFG on error. -#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, returns ::MBG_ERR_CFG on error +#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, returns ::MBG_ERR_CFG on error. -#define PCPS_GIVE_FW_ID_1 0x40 ///< (r-) Read first ::PCPS_FIFO_SIZE chars of firmware ID -#define PCPS_GIVE_FW_ID_2 0x41 ///< (r-) Read 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_GIVE_FW_ID_1 0x40 ///< (r-) Read first ::PCPS_FIFO_SIZE chars of firmware ID. +#define PCPS_GIVE_FW_ID_2 0x41 ///< (r-) Read 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_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 +#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. /// @note 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_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_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 oldest event as ::PCPS_HR_TIME, only if ::_pcps_has_ucap +#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 oldest 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_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_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_FORCE_RESET 0x80 ///< (-w) No param., reset the device (deprecated, this can lock up the computer!!) +#define PCPS_FORCE_RESET 0x80 ///< (-w) No param., reset the device (deprecated, this can lock up the computer!!). /// @note Command codes 0xF0 through 0xFF are reserved. -/** @} anchor PCPS_CMD_CODES */ +/** @} defgroup PCPS_CMD_CODES */ #if _IS_MBG_FIRMWARE /** - * @brief Deprecated command group codes + * @defgroup PCPS_CMD_GROUP_CODES Deprecated command group codes * * @deprecated These group codes are deprecated. * They should not be used anymore but removed * from existing source code. The explicit 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 @@ -807,7 +826,7 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS #define PCPS_CTRL_GROUP 0x60 #define PCPS_CFG2_GROUP 0x70 -/** @} anchor PCPS_CMD_GROUP_CODES */ +/** @} defgroup PCPS_CMD_GROUP_CODES */ #endif // _IS_MBG_FIRMWARE @@ -876,6 +895,7 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS _mbg_cn_table_entry( PCPS_NUM_EVT_LOG_ENTRIES ), /* 0x67 */ \ _mbg_cn_table_entry( PCPS_FIRST_EVT_LOG_ENTRY ), /* 0x68 */ \ _mbg_cn_table_entry( PCPS_NEXT_EVT_LOG_ENTRY ), /* 0x69 */ \ + \ _mbg_cn_table_entry( PCPS_FORCE_RESET ), /* 0x80 */ \ MBG_CMD_TABLE_EXT, \ _mbg_cn_table_end() \ @@ -884,18 +904,18 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS /** - * @brief Bus level command return codes + * @defgroup PCPS_LEVEL_CMD_RETURN_CODES Bus Level command return codes * * @deprecated These codes are deprecated and @ref MBG_RETURN_CODES should be used * instead which provide corresponding symbols with same numeric values. * - * @anchor PCPS_LEVEL_CMD_RETURN_CODES @{ */ + * @{ */ #define PCPS_SUCCESS 0 ///< OK, no error (see ::MBG_SUCCESS) #define PCPS_ERR_STIME -1 ///< invalid date/time/status passed (see ::MBG_ERR_STIME) #define PCPS_ERR_CFG -2 ///< invalid parms for a cmd writing config parameters (see ::MBG_ERR_CFG) -/** @} anchor PCPS_LEVEL_CMD_RETURN_CODES */ +/** @} defgroup PCPS_LEVEL_CMD_RETURN_CODES */ @@ -904,29 +924,30 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS #endif -/** @brief The size of a bus level device's command/data FIFO */ +/** @brief The size of the command/data buffer of a bus level device. */ #define PCPS_FIFO_SIZE 16 -/** @brief A data buffer for a bus level device's command/data */ +/** @brief The command/data buffer of a bus level device. */ typedef int8_t PCPS_BUFF[PCPS_FIFO_SIZE]; /** @brief The maximum length of an ID string, including terminating 0 */ -#define PCPS_ID_SIZE ( 2 * PCPS_FIFO_SIZE + 1 ) ///< ASCIIZ string +#define PCPS_ID_SIZE ( 2 * PCPS_FIFO_SIZE + 1 ) /** @brief A buffer for an ID string, including terminating 0 */ typedef char PCPS_ID_STR[PCPS_ID_SIZE]; /** @brief The maximum length of a serial number string, including terminating 0 */ -#define PCPS_SN_SIZE ( PCPS_FIFO_SIZE + 1 ) ///< ASCIIZ string +#define PCPS_SN_SIZE ( PCPS_FIFO_SIZE + 1 ) /** @brief A buffer for a serial number string, including terminating 0 */ typedef char PCPS_SN_STR[PCPS_SN_SIZE]; + /** - * @brief Seconds since epoch 1970-01-01, usually %UTC scale + * @brief Seconds since epoch 1970-01-01, usually %UTC scale. * * Used with ::PCPS_TIME_STAMP. * @@ -936,15 +957,12 @@ typedef char PCPS_SN_STR[PCPS_SN_SIZE]; typedef uint32_t PCPS_SECONDS; #define _mbg_swab_pcps_seconds( _p ) \ -do \ -{ \ - _mbg_swab32( _p ); \ -} while ( 0 ) + _mbg_swab32( _p ); /** - * @brief 32 bit binary fraction of a second + * @brief 32 bit binary fraction of a second. * * Used with ::PCPS_TIME_STAMP, e.g. * 0x80000000 == 0.5 s, 0xFFFFFFFF == 0.9999999.. s, etc. @@ -959,20 +977,17 @@ do \ typedef uint32_t PCPS_FRAC_32; #define _mbg_swab_pcps_frac_32( _p ) \ -do \ -{ \ - _mbg_swab32( _p ); \ -} while ( 0 ) + _mbg_swab32( _p ); /** - * @brief A high resolution time stamp + * @brief A high resolution time stamp. */ typedef struct { - PCPS_SECONDS sec; ///< seconds since 1970, usually %UTC scale - PCPS_FRAC_32 frac; ///< binary fractions of second, see ::PCPS_FRAC_32 + PCPS_SECONDS sec; ///< Seconds since 1970, usually %UTC scale. + PCPS_FRAC_32 frac; ///< Binary fractions of second, see ::PCPS_FRAC_32. } PCPS_TIME_STAMP; @@ -987,7 +1002,7 @@ do \ #ifndef PCPS_HRT_FRAC_SCALE /** - * @brief Scale to be used to print ::PCPS_TIME_STAMP::frac values + * @brief Scale to be used to print ::PCPS_TIME_STAMP::frac values. * * The function ::bin_frac_32_to_dec_frac can be used for the conversion. * @@ -998,7 +1013,7 @@ do \ #ifndef PCPS_HRT_FRAC_SCALE_FMT /** - * @brief Format specifier used to print ::PCPS_TIME_STAMP::frac values + * @brief Format specifier used to print ::PCPS_TIME_STAMP::frac values. * * Used to print values scaled with ::bin_frac_32_to_dec_frac called * with ::PCPS_HRT_FRAC_SCALE. @@ -1011,7 +1026,24 @@ do \ /** - * @brief Extended status code + * @defgroup group_pcps_time_status Definitions used with the device time status + * + * @{ */ + +/** + * @brief Basic time synchronization status. + * + * Used by legacy API calls, but also as the lower byte + * of the extended status word ::PCPS_TIME_STATUS_X. + * + * @see ::PCPS_TIME_STATUS_FLAGS_COMMON + * @see ::PCPS_TIME_STATUS_X + */ +typedef uint8_t PCPS_TIME_STATUS; + + +/** + * @brief Extended time synchronization status. * * Low byte corresponds to ::PCPS_TIME_STATUS, high byte * contains additional flags. @@ -1021,7 +1053,8 @@ do \ */ typedef uint16_t PCPS_TIME_STATUS_X; -#define _mbg_swab_pcps_time_status_x( _p ) _mbg_swab16( _p ) +#define _mbg_swab_pcps_time_status_x( _p ) \ + _mbg_swab16( _p ) typedef struct @@ -1039,42 +1072,125 @@ do \ } while ( 0 ) +/** + * @defgroup PCPS_TIME_STATUS_FLAGS Time status flags + * + * @{ */ + +/** + * @brief Legacy time status flags. + * + * Bit masks used with both ::PCPS_TIME_STATUS and ::PCPS_TIME_STATUS_X. + */ +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 currently 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 instead of some local time. + PCPS_LS_ANN = 0x20, ///< Leap second announced, for ***very*** old devices, see ::REV_PCPS_LS_ANN_PC31PS31. + PCPS_IFTM = 0x40, ///< The current time has been set by an API call, for ***very*** old devices, see ::REV_PCPS_IFTM_PC31PS31. + PCPS_INVT = 0x80 ///< Invalid time because battery had been disconnected, or absolute time can't be decoded safely. +}; + + +/** + * @brief Extended time status flags. + * + * Bit masks used with ::PCPS_TIME_STATUS_X only. + */ +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 mask used only with time stamps representing the current on-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 device has been accessed, subsequent accesses may be + * blocked for up to 1.5 msec or less, depending on the device type, to give + * the onboard microprocessor some time to decode the incoming time signal. + * This flag may be set by the device 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 devices. + */ + PCPS_IO_BLOCKED = 0x8000 +}; + +/** @} defgroup PCPS_TIME_STATUS_FLAGS */ + +/** @} defgroup group_pcps_time_status */ + + /** - * @brief Definitions used to report a signal strength + * @defgroup PCPS_SIG_VAL_DEFS Definitions used to report a signal strength * - * @anchor PCPS_SIG_VAL_DEFS @{ */ + * @{ */ /** - * @brief A data type used to report the signal value + * @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: + +/** + * @defgroup PCPS_SIG_BAR_DEFS Definitions used to draw a signal bar + * + * These constants are used to draw a signal bar + * depending on the signal value of a DCF77 receiver. + * + * @{ */ + #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: +/* @} defgroup PCPS_SIG_BAR_DEFS */ + + +/** + * @defgroup PCPS_SIG_BAR_DEFS_NON_LWR Signal bar definitions for non-LWR devices + * + * These constants are used by devices that are not longwave receivers + * (e.g. GPS, GNSS, TCR) to indicate whether 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 */ +/** @} defgroup PCPS_SIG_BAR_DEFS_NON_LWR */ + +/** @} defgroup PCPS_SIG_VAL_DEFS */ /** - * @brief High resolution time including status and local time offset + * @brief High resolution time including status and local time offset. * * Used to read time with high resolution of fractions of seconds and * more detailed information on the local time offset and status. * Should be prefered over ::PCPS_TIME. * * ::_pcps_has_hr_time checks whether the command ::PCPS_GIVE_TIME is - * supported to read a device's current time using this format. + * supported to read the current time using this format. * * Newer devices providing time capture input may also accept the * ::PCPS_GIVE_UCAP_EVENT command to read user capture event times @@ -1084,10 +1200,11 @@ typedef uint8_t PCPS_SIG_VAL; */ typedef struct { - 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, see @ref PCPS_SIG_VAL_DEFS, or capture input 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, see @ref PCPS_SIG_VAL_DEFS, + ///< or capture input channel number. } PCPS_HR_TIME; @@ -1101,23 +1218,10 @@ do \ /** - * @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; - - - -/** - * @brief Local calendar date and time, plus sync status + * @brief Local calendar date and time, plus sync status. * * This legacy structure is supported by all bus level devices but - * has a time resultion of 10 ms only. For more accurate time stamps + * has a time resultion of 10 ms only. For more precise time stamps * the structures ::PCPS_HR_TIME and ::PCPS_TIME_STAMP should be * used preferably. * @@ -1127,26 +1231,26 @@ typedef uint8_t PCPS_TIME_STATUS; */ typedef struct { - uint8_t sec100; ///< hundredths of seconds, 0..99, 10 ms resolution - 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, 10 ms resolution. + uint8_t sec; ///< Seconds, 0..59, or 60 if inserted 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_SIG_VAL signal; ///< signal strength, see @ref PCPS_SIG_VAL_DEFS - int8_t offs_utc; ///< [hours], 0 if not ::_pcps_has_utc_offs + PCPS_TIME_STATUS status; ///< Status bits, see ::PCPS_TIME_STATUS_FLAGS_COMMON. + PCPS_SIG_VAL signal; ///< Signal strength, see @ref PCPS_SIG_VAL_DEFS. + int8_t offs_utc; ///< %UTC offset, [hours], 0 if not ::_pcps_has_utc_offs. } PCPS_TIME; /** - * @brief Date time and status used with the ::PCPS_SET_TIME command + * @brief Date time and status used with the ::PCPS_SET_TIME command. * * Similar to ::PCPS_TIME, but missing the ::PCPS_TIME::signal * and ::PCPS_TIME::offs_utc fields. @@ -1155,17 +1259,17 @@ typedef struct */ typedef struct { - uint8_t sec100; ///< hundredths of seconds, 0..99, 10 ms resolution - 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, 10 ms resolution. + uint8_t sec; ///< Seconds, 0..59, or 60 if inserted 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 ::PCPS_TIME_STATUS_FLAGS_COMMON. } PCPS_STIME; @@ -1191,32 +1295,34 @@ typedef union /** - * @brief Raw IRIG time + * @brief Raw IRIG time. * * Used to read the raw IRIG time from an IRIG receiver card, if the card * supports this. See the ::PCPS_GIVE_IRIG_TIME command. * * The granularity of the value in the ::PCPS_IRIG_TIME::frac field * depends on the update interval at which the structure is updated - * by the firmeware. I.e., if the raw IRIG time is updated only - * once per second, the ::PCPS_IRIG_TIME::frac value can always be 0. + * by the firmeware. Usually, the raw IRIG time is updated only once + * per second, so the ::PCPS_IRIG_TIME::frac value can always be 0. * * @see @ref group_icode * @see ::ICODE_RX_CODES */ typedef struct { - PCPS_TIME_STATUS_X status; ///< status bits, see @ref PCPS_TIME_STATUS_FLAGS - int16_t offs_utc; ///< [minutes], 0 unless supported by the code format, see ::MSK_ICODE_RX_HAS_TZI - 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, may be 60 for leap second - uint8_t min; ///< minutes, 0..59 - uint8_t hour; ///< hours, 0..23 - uint8_t year; ///< 2 digit year number, or ::IRIG_TIME_UNKNOWN_YEAR if year not supported - ///< by the time code, see ::MSK_ICODE_RX_HAS_ANY_SHORT_YEAR - PCPS_SIG_VAL signal; ///< signal strength, see @ref PCPS_SIG_VAL_DEFS - 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; ///< %UTC offset, [minutes]. 0 unless supported + ///< by the code format, see ::MSK_ICODE_RX_HAS_TZI. + 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, may be 60 for leap second. + uint8_t min; ///< Minutes, 0..59. + uint8_t hour; ///< Hours, 0..23. + uint8_t year; ///< 2 digit year number (year of the century), or + ///< ::IRIG_TIME_UNKNOWN_YEAR if year not supported + ///< by the time code, see ::MSK_ICODE_RX_HAS_ANY_SHORT_YEAR. + PCPS_SIG_VAL signal; ///< Signal strength, see @ref PCPS_SIG_VAL_DEFS. + uint8_t reserved; ///< Currently not used, always 0. } PCPS_IRIG_TIME; @@ -1240,93 +1346,28 @@ do \ /** - * @brief Time status flags - * - * @anchor PCPS_TIME_STATUS_FLAGS @{ */ - -/** - * @brief Legacy time status flags - * - * Bit masks used with both ::PCPS_TIME_STATUS and ::PCPS_TIME_STATUS_X - */ -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 currently 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 instead of some local time - 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 had been disconnected, or absolute time can't be decoded safely -}; - - -/** - * @brief Extended time status flags - * - * Bit masks used with ::PCPS_TIME_STATUS_X only - */ -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 -}; - - - -/** - * This bit mask can be used to extract the time scale information out - * of a PCPS_TIME_STATUS_X value. + * This bit mask can be used to extract the time scale information + * from 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 + * @defgroup PCPS_OLD_SERIAL_CFG Legacy definitions used to configure the serial port(s) of a decice * * @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 @{ */ + * @{ */ /** - * @brief Configuration information for a device's serial port + * @brief Configuration information of the serial port of a device. * - * Used with ::PCPS_GET_SERIAL and ::PCPS_SET_SERIAL + * Used with ::PCPS_GET_SERIAL and ::PCPS_SET_SERIAL. * - * The serial interface on some old DCF77 clocks can be configured + * The serial interface on some old DCF77 receivers 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 @@ -1334,16 +1375,16 @@ enum PCPS_TIME_STATUS_FLAGS_EXT * 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. + * the device. * ::_pcps_has_serial checks whether supported. - * For old GPS clocks refer to the comments for the ::PCPS_GET_SERIAL + * For old GPS receiver refer to the comments for the ::PCPS_GET_SERIAL * command. */ typedef uint8_t PCPS_SERIAL; /** - * @brief Deprecated baud rate indices + * @brief Deprecated baud rate indices. * * @deprecated These values are deprecated. * ::MBG_BAUD_RATE_CODES and associated structures @@ -1361,24 +1402,24 @@ enum PCPS_BD_CODES 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 ///< Number of bits to shift left. /** - * @brief Deprecated framing code indices + * @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 + * Unfortunately, these framing codes can ***not*** simply * be replaced by the newer MBG_FRAMING_... definitions - * since the order of indices doesn't match. + * because the order of indices doesn't match. */ enum PCPS_FR_CODES { @@ -1386,16 +1427,16 @@ enum PCPS_FR_CODES 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 ///< Number of bits to shift left. /** - * @brief Deprecated codes for modes of operation + * @brief Deprecated codes for modes of operation. * * @deprecated These values are deprecated. * ::STR_MODES and associated structures @@ -1406,25 +1447,25 @@ enum PCPS_FR_CODES */ 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 + 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. }; -#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 +#define PCPS_MOD_BITS 2 ///< Field with in the cfg byte. +#define PCPS_MOD_SHIFT ( PCPS_BD_BITS + PCPS_FR_BITS ) ///< Number of bits to shift left. -/** @} anchor PCPS_OLD_SERIAL_CFG */ +/** @} defgroup PCPS_OLD_SERIAL_CFG */ /** - * @brief Type of variable to hold a TZ code + * @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. + * This is used with the PCI interface, but differs from the + * ::TZCODE type that is used with the binary protocol. * * @see ::TZCODE * @see ::TZCODE_UNION @@ -1433,25 +1474,25 @@ typedef uint8_t PCPS_TZCODE; /** - * @brief Enumeration of codes used with PCPS_TZCODE + * @brief Enumeration of codes used with PCPS_TZCODE. */ enum PCPS_TZCODES { - PCPS_TZCODE_CET_CEST, ///< default as broadcast 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 + PCPS_TZCODE_CET_CEST, ///< Default, as broadcast 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: */ +// 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 /** - * @brief Daylight changeover specification + * @brief Daylight changeover specification. * * Used as member field of ::PCPS_TZDL only. Most devices supporting * conversion to local time support the ::TZDL structure instead. @@ -1460,11 +1501,11 @@ enum PCPS_TZCODES */ typedef struct { - uint16_t year_or_wday; ///< The full year number, or 0..6 == Sun..Sat if the ::DL_AUTO_FLAG is set - uint8_t month; ///< [1..12] - uint8_t mday; ///< [1..31] - uint8_t hour; ///< [0..23] - uint8_t min; ///< [0..59] + uint16_t year_or_wday; ///< The full year number, or 0..6 == Sun..Sat if the ::DL_AUTO_FLAG is set. + uint8_t month; ///< Month, [1..12]. + uint8_t mday; ///< Day of month, [1..31]. + uint8_t hour; ///< Hour, [0..23]. + uint8_t min; ///< Minute, [0..59]. } PCPS_DL_ONOFF; @@ -1474,14 +1515,15 @@ do \ _mbg_swab16( &(_p)->year_or_wday ); \ } while ( 0 ) + /** - * @brief A flag indicating if DST changeovers are to be computed automatically + * @brief A flag indicating if DST changeovers are to be computed automatically. * - * If ::PCPS_DL_ONOFF::year_or_wday is or'ed with the constant ::DL_AUTO_FLAG - * then start and end of daylight saving time shall be computed automatically + * If ::PCPS_DL_ONOFF::year_or_wday is or'ed with the constant ::DL_AUTO_FLAG, + * 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 + * If that flag is not set, the field contains the full four-digit year number * and the ::PCPS_DL_ONOFF::mday and ::PCPS_DL_ONOFF::month values specify * the exact date of that year. Most devices supporting conversion to local time * support the ::TZDL structure instead. @@ -1493,7 +1535,7 @@ do \ /** - * @brief Specification of a local time zone + * @brief Specification of a local time zone. * * Most devices supporting conversion to local time support * the ::TZDL structure instead. @@ -1503,10 +1545,10 @@ do \ */ typedef struct { - int16_t offs; ///< offset from %UTC to local time [min] (local time = %UTC + offs) - int16_t offs_dl; ///< additional offset if DST enabled [min] (DST time = local time + offs_dl) - PCPS_DL_ONOFF tm_on; ///< date/time when daylight saving starts - PCPS_DL_ONOFF tm_off; ///< date/time when daylight saving ends + int16_t offs; ///< Offset from %UTC to local time [min] (local time = %UTC + offs). + int16_t offs_dl; ///< Additional offset if DST enabled [min] (DST time = local time + offs_dl). + PCPS_DL_ONOFF tm_on; ///< Date/time when daylight saving starts. + PCPS_DL_ONOFF tm_off; ///< Date/time when daylight saving ends. } PCPS_TZDL; @@ -1522,14 +1564,14 @@ do \ /** - * @brief Status of the time capture FIFO buffer + * @brief Status of the time capture FIFO buffer. * * Only supported if ::RECEIVER_INFO::n_ucaps > 0. */ typedef struct { - uint32_t used; ///< the number of saved capture events - uint32_t max; ///< capture buffer size + uint32_t used; ///< The number of saved capture events. + uint32_t max; ///< Capture buffer size. } PCPS_UCAP_ENTRIES; @@ -1548,38 +1590,41 @@ do \ * @{ */ /** - * @brief Receiver distance from transmitter [km] + * @brief Receiver distance from transmitter [km]. */ -typedef uint16_t TR_DISTANCE; ///< Range may vary with receiver type +typedef uint16_t TR_DISTANCE; ///< Range may vary with receiver type. #define _mbg_swab_tr_distance( _p ) \ _mbg_swab16( _p ) /** - * @brief PZF 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 ::PZF_CORR_STATES - char corr_dir; ///< space, '<', or '>', just for information - PCPS_SIG_VAL signal; ///< signal strength, see @ref PCPS_SIG_VAL_DEFS + uint8_t val; ///< Correlation value, or check count if status ==:: PZF_CORR_CHECK. + uint8_t status; ///< Status codes, see ::PZF_CORR_STATES. + char corr_dir; ///< Space, '<', or '>', just for information. + PCPS_SIG_VAL signal; ///< Signal strength, see @ref PCPS_SIG_VAL_DEFS. } CORR_INFO; -#define _mbg_swab_corr_info( _p ) \ - _nop_macro_fnc() +#define _mbg_swab_corr_info( _p ) \ +do \ +{ \ +} while ( 0 ) + /** - * @brief Codes used with ::CORR_INFO::status + * @brief Codes used with ::CORR_INFO::status. */ enum PZF_CORR_STATES { - 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 }; @@ -1613,14 +1658,14 @@ enum PZF_CORR_STATES /** - * @brief GPS Command codes passed via the system bus + * @brief GPS command codes passed via the system bus. * * Codes specifying various types of data that can be read from or * written to Meinberg bus level devices which support this. * Access is done using the low level functions ::pcps_read_gps * and ::pcps_write_gps 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. + * exceeds the size of the I/O buffer of the device and must therefore + * be accessed in several blocks. * * Applications should instead use the API functions declared in mbgdevio.h. * @@ -1632,62 +1677,62 @@ enum PZF_CORR_STATES */ enum PC_GPS_CMD_CODES { - PC_GPS_TZDL, ///< (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_LEN - 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 - PC_GPS_XFEATURE_BUFFER, ///< (r/-) ::MBG_XFEATURE_BUFFER, only if ::GPS_HAS_XFEATURE - PC_GPS_TLV_INFO, ///< (r/-) ::MBG_TLV_INFO, only if ::MBG_XFEATURE_TLV_API + PC_GPS_TZDL, ///< (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_LEN. + 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. + PC_GPS_XFEATURE_BUFFER, ///< (r/-) ::MBG_XFEATURE_BUFFER, only if ::GPS_HAS_XFEATURE. + PC_GPS_TLV_INFO, ///< (r/-) ::MBG_TLV_INFO, only if ::MBG_XFEATURE_TLV_API. // GPS data - 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) + 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). }; @@ -1758,23 +1803,23 @@ enum PC_GPS_CMD_CODES /** - * @brief Codes used with ::PC_GPS_CMD + * @brief Codes used with ::PC_GPS_CMD. * * @note These commands should only used with care, in very rare cases! */ -enum PC_GPS_COMMANDS //##++++++++++++++ +enum PC_GPS_COMMANDS { - PC_GPS_CMD_BOOT = 1, ///< force a GPS receiver 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 + PC_GPS_CMD_BOOT = 1, ///< Force a GPS receiver to boot mode. + PC_GPS_CMD_INIT_SYS, ///< Let the device clear its system variables. + PC_GPS_CMD_INIT_USER, ///< Reset the onboard 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. }; /** - * @brief A type used to store an unambiguous command code + * @brief A type used to store an unambiguous command code. * * In case of the standard @ref PCPS_CMD_CODES the lower byte contains * the command code and the upper byte is 0. @@ -1788,7 +1833,7 @@ typedef uint16_t PCPS_CMD_INFO; #if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment + #pragma pack() // Set default alignment. #undef _USING_BYTE_ALIGNMENT #endif diff --git a/mbglib/common/pcpsdev.h b/mbglib/common/pcpsdev.h index eccb9ca..34cea76 100644 --- a/mbglib/common/pcpsdev.h +++ b/mbglib/common/pcpsdev.h @@ -1,23 +1,37 @@ /************************************************************************** * - * $Id: pcpsdev.h 1.58 2018/11/02 14:58:43Z martin REL_M $ + * $Id: pcpsdev.h 1.65 2021/04/29 15:06:04Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * * Description: - * Definitions used to share information on radio clock devices + * Definitions used to share information on bus level devices * between device drivers which have direct access to the hardware * devices and user space programs which evaluate and present that * information. * * At the bottom of the file there are some macros defined which * should be used to access the structures to extract characteristics - * of an individual clock. + * of an individual device. * * ----------------------------------------------------------------------- * $Log: pcpsdev.h $ - * Revision 1.58 2018/11/02 14:58:43Z martin + * Revision 1.65 2021/04/29 15:06:04Z martin + * Support reading device CPU info. + * Revision 1.64 2021/03/22 18:11:17 martin + * Updated a bunch of comments. + * Revision 1.63 2021/03/12 12:32:43 martin + * Updated some comments. + * Revision 1.62 2021/03/11 16:07:18 martin + * Tiny doxygen fix. + * Revision 1.61 2019/12/20 12:28:25 martin + * New type PCPS_TYPE_NUM. + * Revision 1.60 2019/07/31 15:44:31 martin + * Doxygen changes. + * Revision 1.59 2019/05/08 11:27:36 martin + * Use new symbol PCPS_IRQ_NUM_UNDEFINED. + * Revision 1.58 2018/11/02 14:58:43 martin * Updated a comment. * Revision 1.57 2018/09/21 15:04:23 martin * Added definitions for TCR180USB. @@ -68,7 +82,7 @@ * 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 + * functions are called by an application, 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. @@ -85,10 +99,10 @@ * Moved PC cycles stuff to an new extra header. * Cleaned up handling of pragma pack(). * Introduced generic MBG_SYS_TIME with nanosecond resolution. - * Support struct timespec under Linux, if available. + * Support struct timespec on Linux, if available. * Use MBG_TGT_KERNEL instead of _KDD_. * Added PTP unicast master configuration stuff. - * For compatibility use cpu_counter() instead of cpu_counter_serializing() under NetBSD. + * For compatibility use cpu_counter() instead of cpu_counter_serializing() on NetBSD. * Optionally support timespec for sys time (USE_TIMESPEC). * Support FreeBSD and NetBSD. * Moved MBG_TGT_SUPP_MEM_ACC definition here. @@ -209,7 +223,7 @@ * Support a GPS_DATA interface where sizes are specified * by 16 instead of the original 8 bit quantities, thus allowing * to transfer data blocks which exceed 255 bytes. - * Modified inclusion of header files under Linux. + * Modified inclusion of header files on Linux. * Modified definition of MBG_PC_CYCLES for Linux. * Revision 1.20 2004/04/14 09:09:11 martin * Source code cleanup. @@ -265,7 +279,7 @@ * a custom GPS firmware. * Revision 1.9 2001/10/16 10:11:14 MARTIN * New Macro _pcps_has_serial_hs() which determines whether - * DCF77 clock supports baud rate higher than default. + * DCF77 receivers supports baud rate higher than default. * Re-arranged order of macro definitions. * Revision 1.8 2001/09/03 07:15:05 MARTIN * Added macro to access the firmware revision number. @@ -338,7 +352,7 @@ #if defined( _USE_PACK ) #if !defined( _NO_USE_PACK_INTF ) - #pragma pack( 1 ) // set byte alignment + #pragma pack( 1 ) // Set byte alignment. #define _USING_BYTE_ALIGNMENT #endif #endif @@ -372,7 +386,7 @@ typedef uint16_t MBG_DBG_PORT; /** - * @brief System time plus associated cycles counter values + * @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 @@ -385,9 +399,9 @@ typedef uint16_t MBG_DBG_PORT; */ 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; @@ -402,53 +416,93 @@ do \ /** - * @defgroup group_bus_flag_masks BUS flag masks - * - * @anchor PCPS_BUS_FLAG_MASKS + * @defgroup PCPS_BUS_FLAG_MASKS Bus flag masks * * @{ */ -// The following flags describe the bus types which are -// supported by the plugin clocks. +/** + * @defgroup PCPS_BUS_TYPE_MASKS Bus type masks + * + * The following flags describe the bus types which are + * supported by the bus level devices. + * + * @{ */ #define PCPS_BUS_ISA 0x0001 ///< IBM compatible PC/AT ISA bus #define PCPS_BUS_MCA 0x0002 ///< IBM PS/2 micro channel #define PCPS_BUS_PCI 0x0004 ///< PCI #define PCPS_BUS_USB 0x0008 ///< USB +/** @} defgroup PCPS_BUS_TYPE_MASKS */ - -// The flags below are or'ed to the PC_BUS_PCI code -// in order to indicate which PCI interface chip is used -// on a PCI card. If no flag is set then the S5933 chip is -// installed which has been used for the first generation -// of Meinberg PCI cards. +/** + * @defgroup PCPS_BUS_PCI_INTF_MASKS PCI bus interface masks + * + * These flags are or'ed to the ::PCPS_BUS_PCI code to + * indicate which PCI interface chip is assembled on + * the particular card. + * If none of these flags is set, the S5933 chip is assembled, + * which was used for the first generation of Meinberg PCI cards. + * + * @{ */ #define PCPS_BUS_PCI_CHIP_S5920 0x8000 ///< S5920 PCI interface chip. #define PCPS_BUS_PCI_CHIP_ASIC 0x4000 ///< Meinberg's own PCI interface chip. #define PCPS_BUS_PCI_CHIP_PEX8311 0x2000 ///< PEX8311 PCI Express interface chip #define PCPS_BUS_PCI_CHIP_MBGPEX 0x1000 ///< Meinberg's own PCI Express interface chip +/** @} defgroup PCPS_BUS_PCI_INTF_MASKS */ -// The constants below combine the PCI bus flags: +/** + * @defgroup PCPS_BUS_PCI_MASKS Combined PCI bus interface masks + * + * These constants combine the PCI bus flags. + * + * @{ */ #define PCPS_BUS_PCI_S5933 ( PCPS_BUS_PCI ) #define PCPS_BUS_PCI_S5920 ( PCPS_BUS_PCI | PCPS_BUS_PCI_CHIP_S5920 ) #define PCPS_BUS_PCI_ASIC ( PCPS_BUS_PCI | PCPS_BUS_PCI_CHIP_ASIC ) #define PCPS_BUS_PCI_PEX8311 ( PCPS_BUS_PCI | PCPS_BUS_PCI_CHIP_PEX8311 ) #define PCPS_BUS_PCI_MBGPEX ( PCPS_BUS_PCI | PCPS_BUS_PCI_CHIP_MBGPEX ) +/** @} defgroup PCPS_BUS_PCI_MASKS */ -// The flags below are or'ed to the PCPS_BUS_USB code -// in order to indicate which USB protocol version -// is supported by the device. If no additional flag is set -// then the device has a USB v1 interface. +/** + * @defgroup PCPS_BUS_USB_INTF_MASKS USB interface masks + * + * These flags are or'ed to the ::PCPS_BUS_USB code to + * indicate which USB protocol version is supported by + * the device. If no additional flag is set, the device + * has a USB v1 interface. + * + * @{ */ #define PCPS_BUS_USB_FLAG_V2 0x8000 +/** @} defgroup PCPS_BUS_USB_INTF_MASKS */ -// The constant below combines the PCI bus flags: +/** + * @defgroup PCPS_BUS_USB_MASKS Combined USB interface masks + * + * These constants combine the USB interface flags. + * + * @{ */ #define PCPS_BUS_USB_V2 ( PCPS_BUS_USB | PCPS_BUS_USB_FLAG_V2 ) +/** @} defgroup PCPS_BUS_USB_INTF_MASKS */ -/** @} defgroup group_bus_flag_masks */ +/** @} defgroup PCPS_BUS_USB_MASKS */ +/** + * @brief A data type used to store one of the ::PCPS_TYPES. + * + * Used e.g. for ::PCPS_DEV_TYPE::num. + * + * @see ::PCPS_TYPES + */ +typedef uint16_t PCPS_TYPE_NUM; + /** - * @brief A list of known devices + * @brief A numeric list of known devices. + * + * Used e.g. for ::PCPS_DEV_TYPE::num. + * + * @see ::PCPS_TYPE_NUM */ enum PCPS_TYPES { @@ -493,7 +547,7 @@ enum PCPS_TYPES }; -#define PCPS_CLOCK_NAME_SZ 10 // including terminating 0 +#define PCPS_CLOCK_NAME_SZ 10 // Including terminating 0. typedef char PCPS_CLOCK_NAME[PCPS_CLOCK_NAME_SZ]; @@ -511,24 +565,40 @@ typedef uint16_t PCPS_BUS_FLAGS; */ typedef struct { - uint16_t num; ///< see ::PCPS_TYPES + PCPS_TYPE_NUM num; ///< See ::PCPS_TYPES. PCPS_CLOCK_NAME name; - PCPS_DEV_ID dev_id; ///< see @ref MEINBERG_PCI_DEVICE_IDS and @ref MBG_USB_DEVICE_IDS - PCPS_REF_TYPE ref_type; ///< see ::PCPS_REF_TYPES - PCPS_BUS_FLAGS bus_flags; ///< see @ref PCPS_BUS_FLAG_MASKS + PCPS_DEV_ID dev_id; ///< See @ref MEINBERG_PCI_DEVICE_IDS and @ref MBG_USB_DEVICE_IDS. + PCPS_REF_TYPE ref_type; ///< See ::PCPS_REF_TYPES. + PCPS_BUS_FLAGS bus_flags; ///< See @ref PCPS_BUS_FLAG_MASKS. } PCPS_DEV_TYPE; /** - * @brief Legacy I/O address type, see ::PCPS_SHORT_PORT_RSRC + * @brief Info on the CPU type assembled on the device. + * + * Can be used e.g. to determine the CPU type that has to be + * selected when running a firmware update tool. + */ +typedef struct +{ + uint16_t cpu_type; ///< See ::MBG_DEV_CPU_TYPES. + uint16_t flags; ///< Yet unused, reserved, 0. + uint32_t reserved; ///< Yet unused, reserved, 0. + +} PCPS_CPU_INFO; + + + +/** + * @brief Legacy I/O address type, see ::PCPS_SHORT_PORT_RSRC. */ typedef uint16_t PCPS_SHORT_PORT_ADDR; /** - * @brief An I/O port resource used by a device + * @brief An I/O port resource used by a device. * * This structure has originally been used to store information * on an I/O address range. @@ -550,14 +620,14 @@ typedef struct /** - * @brief The max. number of I/O port resources used by a clock + * @brief The max. number of I/O port resources used by a device. */ #define N_PCPS_PORT_RSRC 2 /** - * @brief A structure used to retrieve an address to be mapped into user space + * @brief A structure used to retrieve an address to be mapped into user space. * * @note This is currently not really supported and probably doesn't work. */ @@ -575,14 +645,18 @@ typedef struct -typedef uint32_t PCPS_ERR_FLAGS; ///< see @ref PCPS_ERR_FLAG_MASKS -typedef uint32_t PCPS_FEATURES; ///< see @ref PCPS_FEATURE_MASKS +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; -typedef uint16_t PCPS_FW_REV_NUM; ///< firmware revision number, MSB major, LSB minor version +typedef uint16_t PCPS_FW_REV_NUM; ///< Firmware revision number, MSB major, LSB minor version. + +#define PCPS_IRQ_NUM_UNDEFINED -1 ///< Indicates the IRQ number is undefined. + + /** - * @brief Device information + * @brief Device information. * * Contains variable device data which depends on a particular instance * of a device, e.g. the firmware which is currently installed, the @@ -596,15 +670,15 @@ typedef uint16_t PCPS_FW_REV_NUM; ///< firmware revision number, MSB major, LSB */ typedef struct { - PCPS_ERR_FLAGS err_flags; ///< See @ref PCPS_ERR_FLAG_MASKS + PCPS_ERR_FLAGS err_flags; ///< See @ref PCPS_ERR_FLAG_MASKS. PCPS_BUS_NUM bus_num; PCPS_SLOT_NUM slot_num; PCPS_SHORT_PORT_RSRC port[N_PCPS_PORT_RSRC]; PCPS_SHORT_PORT_ADDR short_status_port; - int16_t irq_num; + int16_t irq_num; ///< ::PCPS_IRQ_NUM_UNDEFINED if undefined. uint32_t timeout_clk; PCPS_FW_REV_NUM fw_rev_num; - PCPS_FEATURES features; ///< See @ref PCPS_FEATURE_MASKS + PCPS_FEATURES features; ///< See @ref PCPS_FEATURE_MASKS. PCPS_ID_STR fw_id; PCPS_SN_STR sernum; @@ -613,35 +687,33 @@ typedef struct /** - * @brief Possible device initialization error flags + * @defgroup PCPS_ERR_FLAG_MASKS Possible device initialization error flags * - * Used with ::PCPS_DEV_CFG::err_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_IO 0x00000020 ///< I/O resource not registered with resource manager -#define PCPS_EF_IO_RSRC_MEM 0x00000040 ///< Memory resource not registered with resource manager - -/** @} 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_IO 0x00000020 ///< I/O resource not registered with resource manager. +#define PCPS_EF_IO_RSRC_MEM 0x00000040 ///< Memory resource not registered with resource manager. +/** @} defgroup 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 + * Some features of the devices have been introduced with specific + * firmware versions, so depending on the firmware version, a particular + * device may support a feature, or not. The device probe routine + * checks the device type 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 + * can easily be used to query whether a device device actually * supports a function, or not. * * @see ::PCPS_FEATURES @@ -649,7 +721,7 @@ typedef struct * @{ */ /** - * @brief Feature bits for bus-level devices + * @brief Feature bits for bus-level devices. * * @see @ref PCPS_FEATURE_MASKS */ @@ -666,14 +738,14 @@ enum PCPS_FEATURE_BITS PCPS_BIT_HAS_TZCODE, PCPS_BIT_HAS_CABLE_LEN, - PCPS_BIT_HAS_EVENT_TIME, // custom GPS firmware only + PCPS_BIT_HAS_EVENT_TIME, ///< Custom GPS firmware only. PCPS_BIT_HAS_RECEIVER_INFO, PCPS_BIT_CAN_CLR_UCAP_BUFF, PCPS_BIT_HAS_PCPS_TZDL, PCPS_BIT_HAS_UCAP, PCPS_BIT_HAS_IRIG_TX, - PCPS_BIT_HAS_GPS_DATA_16, // use 16 bit size specifiers + PCPS_BIT_HAS_GPS_DATA_16, ///< Use 16 bit size specifiers. PCPS_BIT_HAS_SYNTH, PCPS_BIT_HAS_GENERIC_IO, PCPS_BIT_HAS_TIME_SCALE, @@ -685,60 +757,61 @@ enum PCPS_FEATURE_BITS PCPS_BIT_HAS_IRIG_TIME, PCPS_BIT_HAS_FAST_HR_TSTAMP, PCPS_BIT_HAS_RAW_IRIG_DATA, - PCPS_BIT_HAS_PZF, // can also demodulate DCF77 PZF + 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 + PCPS_BIT_IS_GNSS, ///< Supports several satellite systems and GNSS API calls. - N_PCPS_FEATURE_BITS // must not exceed 32 !! + N_PCPS_FEATURE_BITS // Must not exceed 32 !! }; /** - * @brief Feature bit masks for bus-level devices + * @defgroup PCPS_FEATURE_MASKS Feature bit masks for bus-level devices * - * Used with ::PCPS_DEV_CFG::features + * Used with ::PCPS_DEV_CFG::features. * * @see ::PCPS_FEATURE_BITS + * @see ::PCPS_FEATURE_NAMES * @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_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. + +/** @} defgroup PCPS_FEATURE_MASKS */ #define PCPS_FEATURE_NAMES \ @@ -775,22 +848,27 @@ enum PCPS_FEATURE_BITS "PCPS_IS_GNSS" \ } -/** @} defgroup group_pcps_features */ - -// The constants below define those features which are available -// in ALL firmware versions which have been shipped with a -// specific clock. +/** + * @defgroup group_pcps_dev_features Feature supported by specific devices + * + * These constants define the features that are available + * in ALL firmware versions which have been shipped with a + * specific type of device. + * + * @see ::PCPS_FEATURES + * + * @{ */ #define PCPS_FEAT_PC31PS31 0 -// Some of the features are available in all newer clocks, -// so these have been put together in one definition: #define PCPS_FEAT_LVL2 ( PCPS_CAN_SET_TIME \ | PCPS_HAS_SERIAL \ | PCPS_HAS_SYNC_TIME \ | PCPS_HAS_UTC_OFFS ) + ///< These features are available in many newer clocks, + ///< so they have been put together in one definition. #define PCPS_FEAT_PC32 ( PCPS_FEAT_LVL2 ) @@ -936,7 +1014,9 @@ enum PCPS_FEATURE_BITS | PCPS_CAN_CLR_UCAP_BUFF /* TODO ? */ \ | PCPS_HAS_UCAP /* TODO ? */ \ | PCPS_HAS_GENERIC_IO /* TODO ? */ ) - ///< IRIG TX only supp. if ::GPS_HAS_IRIG_TX + ///< IRIG TX only supported if ::GPS_HAS_IRIG_TX. + +/** @} defgroup group_pcps_dev_features */ @@ -944,8 +1024,8 @@ enum PCPS_FEATURE_BITS // have been implemented starting with the special firmware revision // numbers defined below. // -// If no number is specified for a feature/clock model then the feature -// is either always supported by that clock model, or not at all. +// If no number is specified for a feature/device model, the feature +// is either always supported by that device model, or not at all. // There are some versions of PCI Express cards out there which do not @@ -979,12 +1059,12 @@ enum PCPS_FEATURE_BITS #define REV_HAS_IRIG_CTRL_BITS_TCR511PCI 0x0107 #define REV_HAS_IRIG_CTRL_BITS_TCR51USB 0x0106 -/* This board uses the GPS_DATA interface with 16 bit buffer sizes +/* This device uses the GPS_DATA interface with 16 bit buffer sizes instead of the original 8 bit sizes, thus allowing to transfer - data blocks which exceed 255 bytes (PCPS_HAS_GPS_DATA_16) */ + data blocks that exceed 255 bytes (PCPS_HAS_GPS_DATA_16) */ #define REV_HAS_GPS_DATA_16_GPS169PCI 0x0202 -/* the clock supports a higher baud rate than N_PCPS_BD_DCF */ +/* the device supports a higher baud rate than N_PCPS_BD_DCF */ #define REV_HAS_SERIAL_HS_PCI509 0x0104 /* commands PCPS_GIVE_UCAP_ENTRIES, PCPS_GIVE_UCAP_EVENT */ @@ -1030,9 +1110,11 @@ enum PCPS_FEATURE_BITS /* command PCPS_GIVE_TIME_NOCLEAR: */ // This is supported by all clocks but PC31/PS31 with // firmware versions before v3.0. If such a card shall -// be used then the firmware should be updated to the +// be used, the firmware should be updated to the // last recent version. +/** @} defgroup group_pcps_features */ + /** * @brief Device info structure @@ -1058,9 +1140,9 @@ typedef struct // The macros below simplify access to the data // stored in PCPS_DEV structure and should be used // to extract the desired information. -// If the formal parameter is called _d then a pointer +// If the formal parameter is called _d, a pointer // to device structure PCPS_DEV is expected. -// If the formal parameter is called _c then a pointer +// If the formal parameter is called _c, a pointer // to configuration structure PCPS_DEV_CFG is expected. // Access device type information: @@ -1120,7 +1202,7 @@ typedef struct #define _pcps_sernum( _d ) ( (_d)->cfg.sernum ) -// The macros below handle the device's err_flags. +// The macros below handle the err_flags of a device. #define _pcps_err_flags( _d ) ( (_d)->cfg.err_flags ) #define _pcps_chk_err_flags( _d, _msk ) ( _pcps_err_flags( _d ) & (_msk) ) #define _pcps_set_err_flags( _d, _msk ) ( _pcps_err_flags( _d ) |= (_msk) ) @@ -1162,7 +1244,7 @@ typedef struct #define _pcps_has_ucap( _d ) _pcps_has_feature( (_d), PCPS_HAS_UCAP ) #define _pcps_has_irig_tx( _d ) _pcps_has_feature( (_d), PCPS_HAS_IRIG_TX ) -// The macro below determines whether a DCF77 clock +// The macro below determines whether a DCF77 receiver // supports a higher baud rate than standard #define _pcps_has_serial_hs( _d ) \ ( ( _pcps_type_num( _d ) == PCPS_TYPE_TCR511PEX ) || \ @@ -1250,16 +1332,16 @@ typedef struct // 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 ) ) -//### TODO should also check GPS_MODEL_HAS_XMR_HOLDOVER_INTV, which is a builtin feature flag only +//### TODO Should also check GPS_MODEL_HAS_XMR_HOLDOVER_INTV, which is a builtin feature flag only. #endif // _USE_DEV_MACROS -// There are some versions of IRIG receiver cards which ignore the TFOM code +// There are some versions of IRIG receivers which ignore the TFOM code // of an incoming IRIG signal even if an IRIG code has been configured which -// supports this. In this case these cards synchronize to the incoming IRIG +// supports this. In this case the devices synchronize to the incoming IRIG // 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 +// The intended behaviour is that the IRIG receiver 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 // defined in gpsdefs.h). @@ -1272,17 +1354,17 @@ typedef struct // Some Meinberg PCI Express cards have a PCIe interface chip with an extra -// PCI bridge built into the chip. Unfortunately there are some mainboards out there +// PCI bridge built into the chip. Unfortunately, there are some mainboards out there // which do not handle PCI resources behind this PCI bridge correctly. The symptom is // usually that both I/O address ranges of these cards get the same base address // assigned by the BIOS, and the effect is that in this case a card is not accessible // properly, since both I/O ranges try to respond to the same I/O addresses. // As a consequence, data read from the card is usually garbage. // The only known fix for this is a BIOS update for the mainboard which makes the -// BIOS handle the card's resources properly. +// BIOS handle the resources of the device properly. // The macro below can be used to test if both port base addresses assigned to a card -// are identical, and thus the BIOS is probably faulty:: +// are identical, and thus the BIOS is probably faulty: #define _pcps_pci_cfg_err( _d ) \ ( _pcps_is_pci( _d ) && _pcps_short_port_base( _d, 0 ) && \ ( _pcps_short_port_base( _d, 1 ) == _pcps_short_port_base( _d, 0 ) ) ) @@ -1306,32 +1388,32 @@ typedef struct /** - * @brief Codes used with ::IOCTL_DEV_FEAT_REQ::feat_type + * @brief Codes used with ::IOCTL_DEV_FEAT_REQ::feat_type. */ enum DEV_FEAT_TYPES { - DEV_FEAT_TYPE_BUILTIN, ///< feat_num field contains one of the ::GPS_BUILTIN_FEATURE_BITS - DEV_FEAT_TYPE_REF_TYPE, ///< feat_num field contains one of the ::PCPS_REF_TYPES - DEV_FEAT_TYPE_PCPS, ///< feat_num field contains one of the ::PCPS_FEATURE_BITS - DEV_FEAT_TYPE_RI, ///< feat_num field contains one of the ::GPS_FEATURE_BITS - DEV_FEAT_TYPE_XFEAT, ///< feat_num field contains one of the ::MBG_XFEATURE_BITS - DEV_FEAT_TYPE_TLV_FEAT, ///< feat_num field contains one of the ::MBG_TLV_FEAT_TYPES + DEV_FEAT_TYPE_BUILTIN, ///< feat_num field contains one of the ::GPS_BUILTIN_FEATURE_BITS. + DEV_FEAT_TYPE_REF_TYPE, ///< feat_num field contains one of the ::PCPS_REF_TYPES. + DEV_FEAT_TYPE_PCPS, ///< feat_num field contains one of the ::PCPS_FEATURE_BITS. + DEV_FEAT_TYPE_RI, ///< feat_num field contains one of the ::GPS_FEATURE_BITS. + DEV_FEAT_TYPE_XFEAT, ///< feat_num field contains one of the ::MBG_XFEATURE_BITS. + DEV_FEAT_TYPE_TLV_FEAT, ///< feat_num field contains one of the ::MBG_TLV_FEAT_TYPES. N_DEV_FEAT_TYPES }; /** - * @brief Device driver information + * @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 devices handled by the driver - PCPS_ID_STR id_str; ///< the device driver's ID string + uint16_t ver_num; ///< The version number of the device driver. + uint16_t n_devs; ///< The number of devices handled by the driver. + PCPS_ID_STR id_str; ///< The ID string of the device driver. } PCPS_DRVR_INFO; @@ -1346,7 +1428,7 @@ typedef struct /** - * @brief Time read from a device plus associated system cycles count + * @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. @@ -1361,15 +1443,15 @@ typedef struct /** - * @brief High resolution time stamp plus associated system cycles count + * @brief High resolution time stamp plus associated system cycles count. * - * Contains current high resolution UTC time stamp from a device, plus + * 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; - PCPS_TIME_STAMP tstamp; ///< High resolution time stamp (%UTC) + PCPS_TIME_STAMP tstamp; ///< High resolution time stamp (%UTC). } PCPS_TIME_STAMP_CYCLES; @@ -1383,7 +1465,7 @@ do \ /** - * @brief High resolution time plus associated system cycles count + * @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 @@ -1406,14 +1488,14 @@ do \ /** - * @brief High resolution device time, system time, and associated cycles counts + * @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). + * This structure also contains some status information (e.g. sync status). */ typedef struct { @@ -1432,20 +1514,20 @@ do \ /** - * @brief High resolution device time stamp, system time, and associated cycles counts + * @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). + * Since the time stamp is taken from the fast memory mapped registers of the device, + * this structure does ***not*** provide any 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; @@ -1459,9 +1541,7 @@ do \ /** - * @defgroup group_irq_stat_info IRQ status information - * - * @anchor PCPS_IRQ_STAT_INFO_DEFS + * @defgroup PCPS_IRQ_STAT_INFO_DEFS IRQ status information * * @{ */ @@ -1470,11 +1550,11 @@ typedef uint32_t PCPS_IRQ_STAT_INFO; // Flags used with PCPS_IRQ_STAT_INFO: #define PCPS_IRQ_STAT_ENABLE_CALLED 0x01 #define PCPS_IRQ_STAT_ENABLED 0x02 -#define PCPS_IRQ_STAT_UNSAFE 0x04 // IRQs unsafe with this firmeware version / ASIC +#define PCPS_IRQ_STAT_UNSAFE 0x04 ///< IRQs unsafe with this firmeware and/or ASIC version. #define PCPS_IRQ_STATE_DANGER ( PCPS_IRQ_STAT_ENABLED | PCPS_IRQ_STAT_UNSAFE ) -/** @} defgroup group_irq_stat_info */ +/** @} defgroup PCPS_IRQ_STAT_INFO_DEFS */ @@ -1489,7 +1569,7 @@ typedef uint32_t PCPS_IRQ_STAT_INFO; #if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment + #pragma pack() // Set default alignment. #undef _USING_BYTE_ALIGNMENT #endif @@ -1512,7 +1592,7 @@ void setup_hr_time_cycles_from_timestamp_cycles( PCPS_HR_TIME_CYCLES *p_ht_c, /** - * @brief A string buffer for a unique device ID + * @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] @@ -1526,7 +1606,7 @@ typedef char MBG_DEV_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; /** - * @brief A string format specifier for ::MBG_DEV_NAME + * @brief A string format specifier for ::MBG_DEV_NAME. * * @see ::snprint_dev_name * @see ::MBG_DEV_NAME_FMT diff --git a/mbglib/common/pcpslstr.c b/mbglib/common/pcpslstr.c index f7fab0d..1978c8c 100644 --- a/mbglib/common/pcpslstr.c +++ b/mbglib/common/pcpslstr.c @@ -1,17 +1,24 @@ /************************************************************************** * - * $Id: pcpslstr.c 1.27 2018/12/11 16:02:28Z martin REL_M $ + * $Id: pcpslstr.c 1.30 2021/03/22 23:11:49Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * * Description: * Functions generating commonly used multi-language strings used - * with programs for Meinberg radio clocks. + * with programs for Meinberg devices. * * ----------------------------------------------------------------------- * $Log: pcpslstr.c $ - * Revision 1.27 2018/12/11 16:02:28Z martin + * Revision 1.30 2021/03/22 23:11:49Z martin + * Updated some comments. + * Revision 1.29 2021/03/12 12:32:49 martin + * Updated some comments. + * Revision 1.28 2020/02/27 13:54:09 martin + * pcps_status_strs() now expects an extended status PCPS_TIME_STATUS_X. + * Removed inclusion of obsolete header pcpsutil.h. + * Revision 1.27 2018/12/11 16:02:28 martin * Use standard int types for more compatibility. * Revision 1.26 2018/01/15 18:24:57Z martin * Moved snprint_utc_offs() to timeutil.c. @@ -25,7 +32,7 @@ * Added function sprint_utc_offs(). * Cleaned up get_tz_name(). * Fixed potential compiler warning for sprintf(). - * Fixed build under FreeBSD. + * Fixed build on FreeBSD. * Revision 1.22 2010/06/25 13:57:57Z daniel * Account for time zone offsets with minutes other than 0. * Revision 1.21 2009/03/19 08:06:58Z daniel @@ -92,7 +99,6 @@ #include <pcpslstr.h> #undef _PCPSLSTR -#include <pcpsutil.h> #include <mbgtime.h> #include <timeutil.h> #include <ctry.h> @@ -107,7 +113,7 @@ typedef struct { #if defined( __BORLANDC__ ) && ( __BORLANDC__ < 0x0500 ) - // old BCs don't like "const" inside the structure + // Old BCs don't like "const" inside the structure. LSTR ok; LSTR err; #else @@ -124,9 +130,9 @@ static CLSTR str_dst = { "DST", "Sommerzeit" }; /*HDR*/ /** - * @brief Return a language dependend string for "invalid" + * @brief Return a language dependent string for "invalid". * - * @return A language dependend string for "invalid" + * @return A language dependent string for "invalid" */ const char *inv_str( void ) { @@ -140,14 +146,14 @@ const char *inv_str( void ) static /*HDR*/ /** - * @brief Return a static string with the name of the timezone, depending on the UTC offset + * @brief Determine a time zone name from the device status. + * + * @param[in] pcps_status Status flags read from a device. + * @param[in] utc_offs %UTC offset, [s]. + * @param[in] flags A combination of ::PCPS_TZ_NAME_FLAGS contolling the output string format. + * @param[in] is_msf A Flag used to indicate if the device is an MSF receiver. * - * @param[in] pcps_status Status flags read from a clock device - * @param[in] utc_offs UTC offset in [s] - * @param[in] flags A combination of ::PCPS_TZ_NAME_FLAGS contolling the output string format - * @param[in] is_msf A Flag used to indicate if the clock is an MSF receiver - * - * @return Pointer to a static string which has been set up + * @return Pointer to a static string providing the determined name. * * @see ::pcps_tz_name * @see ::pcps_tz_name_from_hr_time @@ -163,7 +169,7 @@ const char *get_tz_name( PCPS_TIME_STATUS_X pcps_status, long utc_offs, size_t n = 0; if ( ( pcps_status & PCPS_UTC ) && ( utc_offs == 0 ) ) - return tz_name_utc; // no offset, no DST + return tz_name_utc; // No offset, no DST. if ( pcps_status & PCPS_DL_ENB ) { @@ -228,13 +234,13 @@ check_flags: /*HDR*/ /** - * @brief Return a static time zone string depending on the UTC offset from a ::PCPS_TIME structure + * @brief Determine a TZ name from a ::PCPS_TIME structure with status and %UTC offset. * - * @param[in] t A ::PCPS_TIME structure read from a clock device - * @param[in] flags A combination of ::PCPS_TZ_NAME_FLAGS contolling the output string format - * @param[in] is_msf A Flag used to indicate if the clock is an MSF receiver + * @param[in] t A ::PCPS_TIME structure read from a device. + * @param[in] flags A combination of ::PCPS_TZ_NAME_FLAGS contolling the output string format. + * @param[in] is_msf A Flag used to indicate if the is an MSF receiver. * - * @return Pointer to a static string which has been set up + * @return Pointer to a static string providing the determined name. * * @see ::pcps_tz_name_from_hr_time * @see ::pcps_tz_name_hr_status @@ -252,13 +258,13 @@ const char *pcps_tz_name( const PCPS_TIME *t, ulong flags, int is_msf ) /*HDR*/ /** - * @brief Return a static time zone string depending on the UTC offset from a ::PCPS_HR_TIME structure - * - * @param[in] hrt A ::PCPS_HR_TIME structure read from a clock device - * @param[in] flags A combination of ::PCPS_TZ_NAME_FLAGS contolling the output string format - * @param[in] is_msf A Flag used to indicate if the clock is an MSF receiver + * @brief Determine a TZ name from a ::PCPS_HR_TIME structure with status and %UTC offset. + * + * @param[in] hrt A ::PCPS_HR_TIME structure read from a device. + * @param[in] flags A combination of ::PCPS_TZ_NAME_FLAGS contolling the output string format. + * @param[in] is_msf A Flag used to indicate if the is an MSF receiver. * - * @return Pointer to a static string which has been set up + * @return Pointer to a static string providing the determined name. * * @see ::pcps_tz_name * @see ::pcps_tz_name_hr_status @@ -276,16 +282,16 @@ const char *pcps_tz_name_from_hr_time( const PCPS_HR_TIME *hrt, ushort flags, in /*HDR*/ /** - * @brief Return a static time zone string depending on the UTC offset from a ::PCPS_HR_TIME structure + * @brief Determine a TZ name from a ::PCPS_HR_TIME structure with time scale status and %UTC offset. * - * This function can be used to build a name for the time zone if the timescale, - * the %UTC/DST status and the %UTC offset are known, e.g. from plug-in clock devices. + * Can be used to determine a name for the time zone if all of the timescale, + * the %UTC/DST status, and the %UTC offset are known, e.g. from plug-in devices. * - * @param[in] t A ::PCPS_HR_TIME structure read from a clock device - * @param[in] flags A combination of ::PCPS_TZ_NAME_FLAGS contolling the output string format - * @param[in] is_msf A Flag used to indicate if the clock is an MSF receiver + * @param[in] t A ::PCPS_HR_TIME structure read from a device. + * @param[in] flags A combination of ::PCPS_TZ_NAME_FLAGS contolling the output string format. + * @param[in] is_msf A Flag used to indicate if the is an MSF receiver. * - * @return Pointer to a static string which has been set up + * @return Pointer to a static string providing the determined name. * * @see ::pcps_tz_name * @see ::pcps_tz_name_from_hr_time @@ -313,15 +319,15 @@ const char *pcps_tz_name_hr_status( const PCPS_HR_TIME *t, ushort flags, int is_ /*HDR*/ /** - * @brief Return a static time zone string depending on the UTC offset from a ::PCPS_HR_TIME structure + * @brief Determine a simple TZ name only from the clock status in ::PCPS_TIME_STATUS_X format. * * This function can be used to build a name for the time zone - * if only the %UTC/DST status is known, but the UTC offset is not. + * if only the %UTC/DST status is known, but the %UTC offset is not. * This is the case, for example, if the Meinberg standard time string is decoded. * - * @param[in] status Clock status in ::PCPS_TIME_STATUS_X format + * @param[in] status Clock status in ::PCPS_TIME_STATUS_X format. * - * @return Pointer to a static string which has been set up + * @return Pointer to a static string providing the determined name. * * @see ::pcps_tz_name * @see ::pcps_tz_name_from_hr_time @@ -413,7 +419,7 @@ int pcps_str_tm_gps_date_time( char *s, size_t max_len, const TM_GPS *t ) wchar_t *pcps_date_time_wstr( wchar_t *ws, size_t count, const PCPS_TIME *t, ushort year_limit, const wchar_t *tz_str ) { - //#error Remove this error directive and check if the function works properly. + //#error TODO Remove this error directive and check if the function works properly. char tmp_str[80]; pcps_date_time_str( tmp_str, sizeof( tmp_str ), t, year_limit, NULL ); @@ -447,11 +453,18 @@ void pcps_setup_status_str( PCPS_STATUS_STR *pstr, int err_cond, -// to return status strings to be displayed depending on the -// a clocks PCPS_TIME.status. - /*HDR*/ -void pcps_status_strs( ushort status, int status_is_read, +/** + * @brief Set up a set of device status strings. + * + * The strings depend on the status codes and the device type. + * + * @param[in] status Extended status code, see ::PCPS_TIME_STATUS_X. + * @param[in] status_is_read Flag indicating if the @p status has actually been read. + * @param[in] is_gps Flag indicating if the status has been read from a GPS receiver. + * @param[out] pstrs Array of strings to be set up. + */ +void pcps_status_strs( PCPS_TIME_STATUS_X status, int status_is_read, int is_gps, PCPS_STATUS_STRS *pstrs ) { CLSTR clstr_time_inval = DEFAULT_STR_TIME_INVAL; diff --git a/mbglib/common/pcpslstr.h b/mbglib/common/pcpslstr.h index 05f4e14..5c20d11 100644 --- a/mbglib/common/pcpslstr.h +++ b/mbglib/common/pcpslstr.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpslstr.h 1.32 2018/12/11 16:03:11Z martin REL_M $ + * $Id: pcpslstr.h 1.35 2021/03/22 23:11:52Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,14 @@ * * ----------------------------------------------------------------------- * $Log: pcpslstr.h $ - * Revision 1.32 2018/12/11 16:03:11Z martin + * Revision 1.35 2021/03/22 23:11:52Z martin + * Updated some comments. + * Revision 1.34 2021/03/12 12:32:57 martin + * Updated some comments. + * Revision 1.33 2020/02/27 13:52:25 martin + * Account for a renamed library function. + * Updated function prototypes. + * Revision 1.32 2018/12/11 16:03:11 martin * Updated function prototypes. * Revision 1.31 2018/01/15 18:25:16Z martin * Updated function prototypes. @@ -30,8 +37,8 @@ * Added DEFAULT_OPT_NAME_TR_DISTANCE. * Support time slots mode for programmable pulse outputs. * Added strings for programmable output synthesizer mode. - * Fixed build under FreeBSD. - * Also use ANSI umlauts under QNX. + * Fixed build on FreeBSD. + * Also use ANSI umlauts on QNX. * Updated function prototypes. * Revision 1.27 2010/06/28 08:28:17Z stefan * Added greek character mu. @@ -163,36 +170,39 @@ extern "C" { /** - * @brief Flag bits used to define ::PCPS_TZ_NAME_FLAGS + * @brief Flag bits used to define ::PCPS_TZ_NAME_FLAGS. * * @see ::PCPS_TZ_NAME_FLAGS */ enum PCPS_TZ_NAME_BITS { - PCPS_TZ_NAME_BIT_FORCE_UTC_OFFS, ///< always print "UTC+offs" - PCPS_TZ_NAME_BIT_APP_DST, ///< append DST status + PCPS_TZ_NAME_BIT_FORCE_UTC_OFFS, ///< Always print "UTC+offs". + PCPS_TZ_NAME_BIT_APP_DST, ///< Append DST status. N_PCPS_TZ_NAME_FLAG }; /** - * @brief Flag bits used to control the string generated by ::pcps_tz_name + * @brief Flag bits used to control the string generated by ::pcps_tz_name. * - * The flags defined below can be passed to ::pcps_tz_name - * to control the formatting of the generated time zone names + * The flags defined can be passed to ::pcps_tz_name to control + * the formatting of the generated time zone names. * * @see ::pcps_tz_name * @see ::PCPS_TZ_NAME_BITS */ enum PCPS_TZ_NAME_FLAGS { - PCPS_TZ_NAME_FORCE_UTC_OFFS = ( 1UL << PCPS_TZ_NAME_BIT_FORCE_UTC_OFFS ), ///< see ::PCPS_TZ_NAME_FORCE_UTC_OFFS - PCPS_TZ_NAME_APP_DST = ( 1UL << PCPS_TZ_NAME_BIT_APP_DST ), ///< see ::PCPS_TZ_NAME_APP_DST + PCPS_TZ_NAME_FORCE_UTC_OFFS = ( 1UL << PCPS_TZ_NAME_BIT_FORCE_UTC_OFFS ), ///< See ::PCPS_TZ_NAME_FORCE_UTC_OFFS. + PCPS_TZ_NAME_APP_DST = ( 1UL << PCPS_TZ_NAME_BIT_APP_DST ), ///< See ::PCPS_TZ_NAME_APP_DST. }; -// The definitions below are used with pcps_get_status_strs(). +/** + * @defgroup group_status_strs Definitions used with ::pcps_get_status_strs + * + * @{ */ #define N_PCPS_STATUS_STR 3 @@ -207,12 +217,15 @@ typedef struct PCPS_STATUS_STR s[N_PCPS_STATUS_STR]; } PCPS_STATUS_STRS; +/** @} defgroup group_status_strs */ + + -// initializers for commonly use multi-language strings +// Initializers for commonly use multi-language strings. // (type: CLSTR ) -// time adjustment window +// Time adjustment window. #define DEFAULT_STR_TIME_ADJ_STATUS \ { \ @@ -251,7 +264,7 @@ typedef struct } -// ref time window +// Ref time window. #define DEFAULT_STR_REF_TIME_INFO \ { \ @@ -272,9 +285,9 @@ typedef struct } -// Clock status messages: +// Device status messages: -// Time is not valid (i.e. after batt. empty). +// Time is not valid (e.g. after batt. empty). #define DEFAULT_STR_TIME_INVAL_EN \ "Ref. Time is Invalid" @@ -287,7 +300,7 @@ typedef struct DEFAULT_STR_TIME_INVAL_DE \ } -// on-board time has been set manually +// On-board time has been set manually. #define DEFAULT_STR_SET_MANUALLY \ { \ "Time has been set manually", \ @@ -366,7 +379,7 @@ typedef struct } -// menu option: setup (title) +// Menu option: Setup (title). #define DEFAULT_OPT_NAME_SETUP_EN \ "Setup" @@ -381,10 +394,10 @@ typedef struct } -// menu option: setup date/time +// Menu option: Setup date/time. #define DEFAULT_OPT_NAME_SET_TIME_EN \ - "Radio Clock's Date/Time" + "Onboard Date/Time" #define DEFAULT_OPT_NAME_SET_TIME_DE \ "Datum/Zeit der Funkuhr" @@ -408,7 +421,7 @@ typedef struct } -// menu option: setup time zone +// Menu option: Setup time zone. #define TZ_NAME_UTC "UTC" @@ -429,12 +442,12 @@ typedef struct #define DEFAULT_OPT_NAME_TZ \ { \ - "Radio Clock's Time Zone", \ + "Onboard Time Zone", \ "Zeitzone der Funkuhr" \ } -// menu option: setup time zone +// Menu option: Setup time zone. #define DEFAULT_TZCODE_NAME_CET_CEST \ { \ @@ -518,7 +531,7 @@ typedef struct } -// menu option: setup serial parameters +// Menu option: Setup serial parameters. #define DEFAULT_OPT_NAME_SERIAL \ { \ @@ -527,7 +540,7 @@ typedef struct } -// menu option: setup enable flags +// Menu option: Setup enable flags. #define DEFAULT_OPT_NAME_EF \ { \ @@ -536,7 +549,7 @@ typedef struct } -// menu option: setup length of antenna cable +// Menu option: Setup length of antenna cable. #define DEFAULT_OPT_NAME_CAB_LEN \ { \ @@ -545,7 +558,7 @@ typedef struct } -// menu option: setup distance from transmitter +// Menu option: Setup distance from transmitter. #define DEFAULT_OPT_NAME_TR_DISTANCE \ { \ @@ -554,7 +567,7 @@ typedef struct } -// menu option: setup IRIG config +// Menu option: Setup IRIG config. #define DEFAULT_OPT_NAME_IRIG_TX_EN "IRIG Output" #define DEFAULT_OPT_NAME_IRIG_TX_DE "IRIG-Ausgang" @@ -674,7 +687,7 @@ typedef struct } -// menu option: programmable outputs +// Menu option: Programmable outputs. #define DEFAULT_OPT_NAME_POUT \ { \ @@ -683,7 +696,7 @@ typedef struct } -// menu option: frequency synthesizer +// Menu option: Frequency synthesizer. #define DEFAULT_OPT_NAME_SYNTH \ { \ @@ -704,7 +717,7 @@ typedef struct } -// menu option: LAN interface +// Menu option: LAN interface. #define DEFAULT_OPT_NAME_LAN_INTF_EN "LAN Interface" #define DEFAULT_OPT_NAME_LAN_INTF_DE "Netzwerkschnittstelle" @@ -717,7 +730,7 @@ typedef struct -// menu option: PTP configuration +// Menu option: PTP configuration. #define DEFAULT_OPT_NAME_PTP_CFG_EN "PTP Configuration" #define DEFAULT_OPT_NAME_PTP_CFG_DE "PTP-Konfiguration" @@ -730,7 +743,7 @@ typedef struct -// menu option: PTP Unicast configuration +// Menu option: PTP unicast configuration. #define DEFAULT_OPT_NAME_PTP_UC_CFG_EN "PTP Unicast Configuration" #define DEFAULT_OPT_NAME_PTP_UC_CFG_DE "PTP-Unicast-Konfiguration" @@ -863,7 +876,7 @@ typedef struct -// some macros which generate proper function calls +// Some macros which generate proper function calls. #define _pcps_snprint_vernum_dec( _s, _sz, _v ) \ snprintf_safe( (_s), (_sz), "v%u.%02u", \ @@ -891,7 +904,7 @@ typedef struct #define _pcps_snprint_date( _s, _sz, _t, _yl ) \ snprint_ctry_dt( (_s), (_sz), (_t)->mday, (_t)->month, \ - pcps_exp_year( (_t)->year, (_yl) ) ) + mbg_exp_year( (_t)->year, (_yl) ) ) #define _pcps_snprint_time( _s, _sz, _t ) \ snprint_ctry_tm( (_s), (_sz), (_t)->hour, (_t)->min, (_t)->sec ) @@ -1002,20 +1015,20 @@ _ext const char *short_mode_name[N_STR_MODE] /* by MAKEHDR, do not remove the comments. */ /** - * @brief Return a language dependend string for "invalid" + * @brief Return a language dependent string for "invalid". * - * @return A language dependend string for "invalid" + * @return A language dependent string for "invalid" */ const char *inv_str( void ) ; /** - * @brief Return a static time zone string depending on the UTC offset from a ::PCPS_TIME structure + * @brief Determine a TZ name from a ::PCPS_TIME structure with status and %UTC offset. * - * @param[in] t A ::PCPS_TIME structure read from a clock device - * @param[in] flags A combination of ::PCPS_TZ_NAME_FLAGS contolling the output string format - * @param[in] is_msf A Flag used to indicate if the clock is an MSF receiver + * @param[in] t A ::PCPS_TIME structure read from a device. + * @param[in] flags A combination of ::PCPS_TZ_NAME_FLAGS contolling the output string format. + * @param[in] is_msf A Flag used to indicate if the is an MSF receiver. * - * @return Pointer to a static string which has been set up + * @return Pointer to a static string providing the determined name. * * @see ::pcps_tz_name_from_hr_time * @see ::pcps_tz_name_hr_status @@ -1026,13 +1039,13 @@ _ext const char *short_mode_name[N_STR_MODE] const char *pcps_tz_name( const PCPS_TIME *t, ulong flags, int is_msf ) ; /** - * @brief Return a static time zone string depending on the UTC offset from a ::PCPS_HR_TIME structure + * @brief Determine a TZ name from a ::PCPS_HR_TIME structure with status and %UTC offset. + * + * @param[in] hrt A ::PCPS_HR_TIME structure read from a device. + * @param[in] flags A combination of ::PCPS_TZ_NAME_FLAGS contolling the output string format. + * @param[in] is_msf A Flag used to indicate if the is an MSF receiver. * - * @param[in] hrt A ::PCPS_HR_TIME structure read from a clock device - * @param[in] flags A combination of ::PCPS_TZ_NAME_FLAGS contolling the output string format - * @param[in] is_msf A Flag used to indicate if the clock is an MSF receiver - * - * @return Pointer to a static string which has been set up + * @return Pointer to a static string providing the determined name. * * @see ::pcps_tz_name * @see ::pcps_tz_name_hr_status @@ -1043,16 +1056,16 @@ _ext const char *short_mode_name[N_STR_MODE] const char *pcps_tz_name_from_hr_time( const PCPS_HR_TIME *hrt, ushort flags, int is_msf ) ; /** - * @brief Return a static time zone string depending on the UTC offset from a ::PCPS_HR_TIME structure + * @brief Determine a TZ name from a ::PCPS_HR_TIME structure with time scale status and %UTC offset. * - * This function can be used to build a name for the time zone if the timescale, - * the %UTC/DST status and the %UTC offset are known, e.g. from plug-in clock devices. + * Can be used to determine a name for the time zone if all of the timescale, + * the %UTC/DST status, and the %UTC offset are known, e.g. from plug-in devices. * - * @param[in] t A ::PCPS_HR_TIME structure read from a clock device - * @param[in] flags A combination of ::PCPS_TZ_NAME_FLAGS contolling the output string format - * @param[in] is_msf A Flag used to indicate if the clock is an MSF receiver + * @param[in] t A ::PCPS_HR_TIME structure read from a device. + * @param[in] flags A combination of ::PCPS_TZ_NAME_FLAGS contolling the output string format. + * @param[in] is_msf A Flag used to indicate if the is an MSF receiver. * - * @return Pointer to a static string which has been set up + * @return Pointer to a static string providing the determined name. * * @see ::pcps_tz_name * @see ::pcps_tz_name_from_hr_time @@ -1063,15 +1076,15 @@ _ext const char *short_mode_name[N_STR_MODE] const char *pcps_tz_name_hr_status( const PCPS_HR_TIME *t, ushort flags, int is_msf ) ; /** - * @brief Return a static time zone string depending on the UTC offset from a ::PCPS_HR_TIME structure + * @brief Determine a simple TZ name only from the clock status in ::PCPS_TIME_STATUS_X format. * * This function can be used to build a name for the time zone - * if only the %UTC/DST status is known, but the UTC offset is not. + * if only the %UTC/DST status is known, but the %UTC offset is not. * This is the case, for example, if the Meinberg standard time string is decoded. * - * @param[in] status Clock status in ::PCPS_TIME_STATUS_X format + * @param[in] status Clock status in ::PCPS_TIME_STATUS_X format. * - * @return Pointer to a static string which has been set up + * @return Pointer to a static string providing the determined name. * * @see ::pcps_tz_name * @see ::pcps_tz_name_from_hr_time @@ -1084,7 +1097,18 @@ _ext const char *short_mode_name[N_STR_MODE] char *pcps_date_time_str( char *s, size_t max_len, const PCPS_TIME *t, int year_limit, const char *tz_str ) ; int pcps_str_tm_gps_date_time( char *s, size_t max_len, const TM_GPS *t ) ; wchar_t *pcps_date_time_wstr( wchar_t *ws, size_t count, const PCPS_TIME *t, ushort year_limit, const wchar_t *tz_str ) ; - void pcps_status_strs( ushort status, int status_is_read, int is_gps, PCPS_STATUS_STRS *pstrs ) ; + /** + * @brief Set up a set of device status strings. + * + * The strings depend on the status codes and the device type. + * + * @param[in] status Extended status code, see ::PCPS_TIME_STATUS_X. + * @param[in] status_is_read Flag indicating if the @p status has actually been read. + * @param[in] is_gps Flag indicating if the status has been read from a GPS receiver. + * @param[out] pstrs Array of strings to be set up. + */ + void pcps_status_strs( PCPS_TIME_STATUS_X status, int status_is_read, int is_gps, PCPS_STATUS_STRS *pstrs ) ; + char *pcps_port_str( char *s, size_t max_len, const PCPS_DEV *pdev ) ; const char *pcps_tzcode_str( PCPS_TZCODE tzcode ) ; char *pcps_serial_str( char *s, size_t max_len, int i, const RECEIVER_PORT_CFG *p, const RECEIVER_INFO *p_ri, int short_strs ) ; diff --git a/mbglib/common/pcpsmktm.c b/mbglib/common/pcpsmktm.c index 73e1376..811ddbf 100644 --- a/mbglib/common/pcpsmktm.c +++ b/mbglib/common/pcpsmktm.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsmktm.c 1.5 2017/07/05 08:05:11Z martin REL_M $ + * $Id: pcpsmktm.c 1.6 2019/09/27 12:17:19Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: pcpsmktm.c $ - * Revision 1.5 2017/07/05 08:05:11Z martin + * Revision 1.6 2019/09/27 12:17:19Z martin + * Changed pcps_mktime() to pcps_mktime64() with calling convention + * similar to mbg_mktime64(). + * Revision 1.5 2017/07/05 08:05:11 martin * Let pcps_mktime() return a 'time_t' instead of 'long', and made * the PCPS_TIME pointer parameter 'const'. * Added doxygen comments. @@ -32,41 +35,63 @@ #include <mbgmktm.h> - /*HDR*/ /** - * @brief Compute a linear time_t value from ::PCPS_TIME + * @brief Compute a linear ::MBG_TIME64_T value from ::PCPS_TIME. + * + * This function basically works like the POSIX @a mktime function but + * expects the date and time to be converted in ::PCPS_TIME format. + * + * Unlike POSIX @a mktime, which applies a local time offset specified + * as environment variable that is read by the runtime library, this + * function applies the %UTC offset from ::PCPS_TIME::offs_utc when + * converting local time to %UTC. + * + * Unlike @a mktime, this function expects the address of a variable + * of an ::MBG_TIME64_T to take the computed timestamp, and returns + * a result code indicating if the conversion was successful, or not. + * So @a -1 can be a valid timestamp, refering to the time + * one second before the epoch. * - * This function works like the standard mktime() function but does not - * account for a timezone setting configured for the standard C library. - * Instead, since ::PCPS_TIME contains local time with specified UTC offset - * the UTC offset is removed to yield UTC time. + * @note Since ::PCPS_TIME::year actually just contains the year + * of the century, the year number needs to be extended before a + * timestamp can be calculated. * - * @param[in] tp A timestamp in ::PCPS_TIME format + * @param[out] p_t64 Address of a variable to take the result on success, + * i.e. seconds since 1970-01-01 (POSIX @a time_t format, + * but always 64 bits). * - * @return seconds since 1970-01-01 (Unix time_t format) or ((time_t) -1) if range overflow + * @param[in] p_tm Pointer to a ::PCPS_TIME type providing the date + * and time to be converted. + * + * @param[in] year_lim The year limit used when converting a 2 digit year number + * to a full 4 digit year number. See ::mbg_exp_year. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbg_mktime_fncs + * @see @ref mbg_mktime_fncs */ -time_t pcps_mktime( const PCPS_TIME *tp ) +int pcps_mktime64( MBG_TIME64_T *p_t64, const PCPS_TIME *p_tm, int year_lim ) { - time_t secs; - int year = tp->year; + MBG_TIME64_T t64 = 0; + + int year = mbg_exp_year( p_tm->year, year_lim ); // Expand the 2 digit year number. - // Expand 2 digit year number (year of the century) to 4 digits - // including the century. - if ( year < 70 ) - year += 100; + int rc = mbg_mktime64( &t64, year - 1900, p_tm->month - 1, p_tm->mday, + p_tm->hour, p_tm->min, p_tm->sec ); - // Plausibility checks are made by mbg_mktime(). - secs = mbg_mktime( year, tp->month - 1, tp->mday - 1, - tp->hour, tp->min, tp->sec ); + // PCPS_TIME::offs_utc contains a local time, so we + // still have to compensate the local time offset + // to yield %UTC. + if ( mbg_rc_is_success( rc ) ) + t64 -= p_tm->offs_utc * SECS_PER_HOUR; - // Convert to UTC if result is valid. - if ( secs != ( (time_t) -1 ) ) - secs -= tp->offs_utc * 3600UL; + *p_t64 = t64; - return secs; + return rc; -} // pcps_mktime +} // pcps_mktime64 diff --git a/mbglib/common/pcpsmktm.h b/mbglib/common/pcpsmktm.h index bd5bbd3..019fe4f 100644 --- a/mbglib/common/pcpsmktm.h +++ b/mbglib/common/pcpsmktm.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsmktm.h 1.2 2017/07/05 08:18:54Z martin REL_M $ + * $Id: pcpsmktm.h 1.3 2019/09/27 12:17:19Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: pcpsmktm.h $ - * Revision 1.2 2017/07/05 08:18:54Z martin + * Revision 1.3 2019/09/27 12:17:19Z martin + * Changed pcps_mktime() to pcps_mktime64() with calling convention + * similar to mbg_mktime64(). + * Revision 1.2 2017/07/05 08:18:54 martin * Cleaned up to conform to standard header file format. * Updated function prototypes. * Revision 1.1 2001/02/02 15:31:07 MARTIN @@ -25,7 +28,10 @@ #include <pcpsdefs.h> -#include <time.h> +#include <timeutil.h> +#include <mbgtime.h> +#include <mbgerror.h> + #ifdef _PCPSMKTM @@ -50,22 +56,98 @@ extern "C" { /* by MAKEHDR, do not remove the comments. */ /** - * @brief Compute a linear time_t value from ::PCPS_TIME + * @brief Compute a linear ::MBG_TIME64_T value from ::PCPS_TIME. + * + * This function basically works like the POSIX @a mktime function but + * expects the date and time to be converted in ::PCPS_TIME format. + * + * Unlike POSIX @a mktime, which applies a local time offset specified + * as environment variable that is read by the runtime library, this + * function applies the %UTC offset from ::PCPS_TIME::offs_utc when + * converting local time to %UTC. + * + * Unlike @a mktime, this function expects the address of a variable + * of an ::MBG_TIME64_T to take the computed timestamp, and returns + * a result code indicating if the conversion was successful, or not. + * So @a -1 can be a valid timestamp, refering to the time + * one second before the epoch. + * + * @note Since ::PCPS_TIME::year actually just contains the year + * of the century, the year number needs to be extended before a + * timestamp can be calculated. + * + * @param[out] p_t64 Address of a variable to take the result on success, + * i.e. seconds since 1970-01-01 (POSIX @a time_t format, + * but always 64 bits). + * + * @param[in] p_tm Pointer to a ::PCPS_TIME type providing the date + * and time to be converted. * - * This function works like the standard mktime() function but does not - * account for a timezone setting configured for the standard C library. - * Instead, since ::PCPS_TIME contains local time with specified UTC offset - * the UTC offset is removed to yield UTC time. + * @param[in] year_lim The year limit used when converting a 2 digit year number + * to a full 4 digit year number. See ::mbg_exp_year. * - * @param[in] tp A timestamp in ::PCPS_TIME format + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @return seconds since 1970-01-01 (Unix time_t format) or ((time_t) -1) if range overflow + * @ingroup mbg_mktime_fncs + * @see @ref mbg_mktime_fncs */ - time_t pcps_mktime( const PCPS_TIME *tp ) ; + int pcps_mktime64( MBG_TIME64_T *p_t64, const PCPS_TIME *p_tm, int year_lim ) ; /* ----- function prototypes end ----- */ + + +static __mbg_inline /*HDR*/ +/** + * @brief Compute a linear time_t value from broken down date and time. + * + * This function is a variant of ::pcps_mktime64, but expects + * the address of a @a time_t variable for the result. + * See ::pcps_mktime64 for a detailed description. + * + * On systems with a 64 bit @a time_t the result is the same as for + * ::pcps_mktime64, but on systems where @a time_t is only 32 bits wide, + * the returned value is truncated and suffers from the <b>Y2038 problem</b>. + * + * Use ::pcps_mktime64 preferably to compute a timestamp + * which is always 64 bits wide. + * + * @note Since ::PCPS_TIME::year actually just contains the year + * of the century, the year number needs to be extended before a + * timestamp can be calculated. + * + * @param[out] p_t Address of a variable to take the result on success, + * i.e. seconds since 1970-01-01 (POSIX @a time_t format). + * + * @param[in] p_tm Pointer to a ::PCPS_TIME type providing the date + * and time to be converted. + * + * @param[in] year_lim The year limit used when converting a 2 digit year number + * to a full 4 digit year number, e.g. 1970. + * See ::mbg_exp_year. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbg_mktime_fncs + * @see @ref mbg_mktime_fncs + */ +int _DEPRECATED_BY( "pcps_mktime64" ) pcps_mktime( time_t *p_t, const PCPS_TIME *p_tm, int year_lim ) +{ + MBG_TIME64_T t64; + + int rc = pcps_mktime64( &t64, p_tm, year_lim ); + + // On success we still check if the result is in a valid range + // and convert the result, if required. + if ( mbg_rc_is_success( rc ) ) + rc = mbg_trnc_time64_t_to_time_t( p_t, &t64 ); + + return rc; + +} // pcps_mktime + + #ifdef __cplusplus } #endif diff --git a/mbglib/common/ptp_util.h b/mbglib/common/ptp_util.h index 7632316..7014b54 100644 --- a/mbglib/common/ptp_util.h +++ b/mbglib/common/ptp_util.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: ptp_util.h 1.6 2017/05/10 15:26:10Z martin REL_M $ + * $Id: ptp_util.h 1.7 2021/03/16 12:20:39Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: ptp_util.h $ - * Revision 1.6 2017/05/10 15:26:10Z martin + * Revision 1.7 2021/03/16 12:20:39Z martin + * Updated some comments. + * Revision 1.6 2017/05/10 15:26:10 martin * Tiny cleanup. * Revision 1.5 2017/04/25 12:54:21 gregoire.diehl * Merge changes from 1.3.1.7 & 1.4 @@ -68,10 +70,10 @@ extern "C" { * 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:<br> - * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is set then a different flag + * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is set, a different flag * ::PTP_CFG_CAN_BE_MULTICAST_SLAVE needs to be checked to tell if * the multicast slave role is supported, or not.<br> - * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is not set then the device + * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is not set, the device * definitely supports the multicast slave role. * * @param flags bit mask from ::PTP_CFG_INFO::supp_flags, see @ref PTP_CFG_FLAG_MASKS diff --git a/mbglib/common/str_util.c b/mbglib/common/str_util.c index 3c21324..59d17be 100644 --- a/mbglib/common/str_util.c +++ b/mbglib/common/str_util.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: str_util.c 1.5 2018/08/23 13:07:16Z martin REL_M $ + * $Id: str_util.c 1.11 2021/03/22 11:28:52Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,19 @@ * * ----------------------------------------------------------------------- * $Log: str_util.c $ - * Revision 1.5 2018/08/23 13:07:16Z martin + * Revision 1.11 2021/03/22 11:28:52Z martin + * Updated some comments. + * Revision 1.10 2021/03/16 12:20:37 martin + * Updated some comments. + * Revision 1.9 2021/03/12 12:32:24 martin + * Updated some comments. + * Revision 1.8 2021/03/12 11:00:26 martin + * Updated some doxygen comments. + * Revision 1.7 2019/11/27 10:37:33 martin + * Tiny code style fixes. + * Revision 1.6 2019/07/31 15:42:38 martin + * Doxygen changes. + * Revision 1.5 2018/08/23 13:07:16 martin * Moved the snprintf() safety checks to new inline functions that * can also be used called from specific kernel mode functions. * Unified variable naming. @@ -48,15 +60,15 @@ #if defined( MBG_TGT_DOS ) static /*HDR*/ -// Under DOS we use the Borland C/C++ v3.1 compiler by default, which +// On DOS, we use the Borland C/C++ v3.1 compiler by default, which // doesn't provide a vsnprintf() function, so we use a simple replacement // here. Since we share most of the source code between several target -// systems we assume that if our code works properly for other targets -// which really provide a vsnprintf() function then it also works properly -// under DOS. ;-) +// systems, we assume that if our code works properly for other targets +// which really provide a vsnprintf() function, it also works properly +// on DOS. ;-) int vsnprintf( char *s, size_t max_len, const char *fmt, va_list args ) { - (void) max_len; // quiet compiler warning "not used" + (void) max_len; // Quiet compiler warning "not used". return vsprintf( s, fmt, args ); @@ -68,27 +80,29 @@ int vsnprintf( char *s, size_t max_len, const char *fmt, va_list args ) /*HDR*/ /** - * @brief A portable, safe implementation of vsnprintf() + * @brief A portable, safe implementation of vsnprintf(). * - * Unfortunately the behaviour of vsnprintf() and thus snprintf() - * differs in detail across various build environments and run time - * libraries. + * Unfortunately, the behavior of @a vsnprintf and therefore also that + * of @a snprintf differs in detail in different build environments + * and runtime libraries. * - * If the output exceeds the buffer size and thus is truncated then:<br> + * If the output exceeds the buffer size and thus is truncated, then:<br> * - * - Under Windows a negative value is returned and eventually *no* + * - On Windows, a negative value is returned and maybe ***no*** * terminating 0 is written to the output buffer, so the output string * may not be terminated properly. * - * - Some versions of glibc return the number of bytes that *would* - * have been written to the buffer *if* the buffer would have been + * - Some versions of glibc return the number of bytes that ***would*** + * have been written to the buffer ***if*** the buffer would have been * large enough, instead of the true number of characters that have * been written to the buffer. * * So subsequent calls like * - * n = snprintf( s, max_len, ... ); - * n += snprintf( &s[n], max_len - n, ... ); + * @code{.c} + n = snprintf( s, max_len, ... ); + n += snprintf( &s[n], max_len - n, ... ); + * @endcode * * may always work properly, or fail with buffer overruns or stack * corruption depending on the build environment. @@ -97,20 +111,21 @@ int vsnprintf( char *s, size_t max_len, const char *fmt, va_list args ) * characters really written to the string buffer, excluding the * terminating 0. * - * @note The "size_t" type parameter used to specify the buffer size - * can be larger (e.g. "unsigned long") than the "int" type returned - * by mostly all functions of the printf() family. So if a very large + * @note The @a size_t type parameter used to specify the buffer size + * can be larger (e.g. @a unsigned_long) than the @a int type returned + * by mostly all functions of the @a printf family. So if a very large * buffer is specified, and a large number of characters (more than - * MAXINT) are written to that buffer then how can an "int" type + * @a MAXINT) are written to that buffer, how can an @a int type * return the large number of characters written to the buffer? * We also try to workaround this here. * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] fmt Format string according to subsequent parameters - * @param[in] args Variable argument list in va_list format + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for a 0-terminated string. + * @param[in] fmt Format string according to subsequent parameters. + * @param[in] args Variable argument list in @a va_list format. * - * @return Number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprintf_safe * @see ::strncpy_safe @@ -123,7 +138,7 @@ int vsnprintf_safe( char *s, size_t max_len, const char *fmt, va_list args ) size_t n; if ( !mbg_buffer_specs_valid( s, max_len ) ) - return 0; // nothing to do anyway + return 0; // Nothing to do anyway. n = mbg_vsnprintf( s, max_len, fmt, args ); @@ -136,16 +151,17 @@ int vsnprintf_safe( char *s, size_t max_len, const char *fmt, va_list args ) /*HDR*/ /** - * @brief A portable, safe implementation of snprintf() + * @brief A portable, safe implementation of snprintf(). * - * For a detailed description see ::vsnprintf_safe + * For a detailed description see ::vsnprintf_safe. * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] fmt Format string according to subsequent parameters - * @param[in] ... Variable argument list according to the format string + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for a 0-terminated string. + * @param[in] fmt Format string according to subsequent parameters. + * @param[in] ... Variable argument list according to the format string. * - * @return Number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::vsnprintf_safe * @see ::strncpy_safe @@ -153,7 +169,7 @@ int vsnprintf_safe( char *s, size_t max_len, const char *fmt, va_list args ) * @see ::sn_cpy_char_safe */ __attribute__( ( format( printf, 3, 4 ) ) ) -int snprintf_safe( char *s, size_t max_len, const char * fmt, ... ) +int snprintf_safe( char *s, size_t max_len, const char *fmt, ... ) { va_list args; int len; @@ -168,21 +184,22 @@ int snprintf_safe( char *s, size_t max_len, const char * fmt, ... ) -static __mbg_inline +static __mbg_inline /*HDR*/ /* (explicitly excluded from doxygen) - * @brief A portable, safe implementation of a copy function + * @brief A portable, safe implementation of a copy function. * * This is the basic function used to implemment ::strncpy_safe and * ::sn_cpy_safe. This function takes care that the copied string * is always terminated by 0, but any remaining buffer space - * is *not* filled up with '0' characters. + * is ***not*** filled up with '0' characters. * - * @param[out] dst Pointer to the output buffer - * @param[in] src Pointer to the input buffer - * @param[in] n Number of characters to copy at most - * @param[in,out] p_i Pointer to a counter variable + * @param[out] dst Pointer to the output buffer. + * @param[in] src Pointer to the input buffer. + * @param[in] n Number of characters to copy at most. + * @param[in,out] p_i Pointer to a counter variable. * - * @return The number of characters copied. + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::vsnprintf_safe * @see ::snprintf_safe @@ -201,15 +218,15 @@ size_t do_str_copy_safe( char *dst, const char *src, size_t n ) *dst = *src; if ( *dst == 0 ) - break; // just copied the terminating 0, done + break; // Just copied the terminating 0, done. - if ( --n == 0 ) // no more space left in buffer + if ( --n == 0 ) // No more space left in buffer. { - *dst = 0; // force terminating 0 + *dst = 0; // Force terminating 0. break; } - i++; // count normal characters + i++; // Count normal characters. src++; dst++; } @@ -223,21 +240,21 @@ size_t do_str_copy_safe( char *dst, const char *src, size_t n ) /*HDR*/ /** - * @brief A portable, safe implementation of strncpy() + * @brief A portable, safe implementation of strncpy(). * - * In the original implementation of strncpy(), if the length of the + * In the original implementation of @a strncpy, if the length of the * string to be copied into the destination buffer exceeds the specified - * buffer length then the string in the output buffer is not 0-terminated. + * buffer length, the string in the output buffer is not 0-terminated. * * Our implementation always forces a proper termination by 0, but unlike - * the original implementation of strncpy() it does *not* fill the whole + * the original implementation of @a strncpy, it does ***not*** fill the whole * remaining buffer space with '0' characters. * - * @param[out] dst Pointer to the output buffer - * @param[in] src Pointer to the input buffer - * @param[in] max_len Size of the output buffer for 0-terminated string + * @param[out] dst Pointer to the output buffer. + * @param[in] src Pointer to the input buffer. + * @param[in] max_len Size of the output buffer for 0-terminated string. * - * @return Pointer to the destination buffer + * @return Pointer to the destination buffer. * * @see ::vsnprintf_safe * @see ::snprintf_safe @@ -256,17 +273,18 @@ char *strncpy_safe( char *dst, const char *src, size_t max_len ) /*HDR*/ /** - * @brief A function to copy a string safely, returning the number of characters copied + * @brief A function to copy a string safely, returning the number of characters copied. * * This basically works like ::strncpy_safe but instead of a pointer to * the destination buffer it returns the number of characters copied * to the destination buffer. * - * @param[out] dst Pointer to the output buffer - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] src Pointer to the input buffer + * @param[out] dst Pointer to the output buffer. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] src Pointer to the input buffer. * - * @return Number of characters copied to the destination buffer + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::vsnprintf_safe * @see ::snprintf_safe @@ -285,18 +303,19 @@ int sn_cpy_str_safe( char *dst, size_t max_len, const char *src ) /*HDR*/ /** - * @brief A function to copy a character safely to a string buffer + * @brief A function to copy a character safely to a string buffer. * * This basically works like ::sn_cpy_str_safe but expects a character * to be copied to the destination buffer. Appends a terminating 0 to * the string buffer and returns the number of characters copied to * the destination buffer, usually 0 or 1. * - * @param[out] dst Pointer to the output buffer - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] c Character to be copied to the destination buffer + * @param[out] dst Pointer to the output buffer. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] c Character to be copied to the destination buffer. * - * @return Number of characters copied to the destination buffer, without the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::vsnprintf_safe * @see ::snprintf_safe @@ -321,15 +340,15 @@ int sn_cpy_char_safe( char *dst, size_t max_len, char c ) /*HDR*/ /** - * @brief Trim whitespace at the end of a string + * @brief Trim whitespace at the end of a string. * - * @param[in,out] s The string to be trimmed + * @param[in,out] s The string to be trimmed. */ void trim_trailing_whitespace( char *s ) { char *cp; - // set all trailing spaces to 0 + // Set all trailing spaces to 0. for ( cp = &s[strlen( s )]; cp > s; ) { --cp; @@ -346,9 +365,9 @@ void trim_trailing_whitespace( char *s ) /*HDR*/ /** - * @brief Trim whitespace at the beginning of a string + * @brief Trim whitespace at the beginning of a string. * - * @param[in,out] s The string to be trimmed + * @param[in,out] s The string to be trimmed. */ void trim_leading_whitespace( char *s ) { @@ -360,7 +379,7 @@ void trim_leading_whitespace( char *s ) if ( *srcp > ' ' ) break; - // If there are leading spaces then srcp now + // If there are leading spaces, srcp now // points behind the beginning of the string, // otherwise there's nothing to do. if ( srcp > s ) @@ -380,9 +399,9 @@ void trim_leading_whitespace( char *s ) /*HDR*/ /** - * @brief Trim both leading and trailing whitespace from a string + * @brief Trim both leading and trailing whitespace from a string. * - * @param[in,out] s The string to be trimmed + * @param[in,out] s The string to be trimmed. */ void trim_whitespace( char *s ) { @@ -395,17 +414,17 @@ void trim_whitespace( char *s ) /*HDR*/ /** - * @brief Copy array of bytes starting at beginning of buffer + * @brief Copy array of bytes starting at beginning of buffer. * * Can be used if the destination address is in the same buffer * in front of the source address. Even though you would expect - * that memcpy() would also work for this properly, we have seen - * cases where it didn't, and only memmove() worked correctly. - * Anyway, we try to avoid the overhead of memmove(). + * that @a memcpy would also work for this properly, we have seen + * cases where it didn't, and only @a memmove worked correctly. + * Anyway, we try to avoid the overhead of @a memmove. * - * @param[out] dst Destination address behind the source address - * @param[in] src Source address - * @param[in] n_bytes Number of bytes to copy + * @param[out] dst Destination address behind the source address. + * @param[in] src Source address. + * @param[in] n_bytes Number of bytes to copy. * * @see ::mbg_memcpy_reversed */ @@ -423,21 +442,21 @@ void mbg_memcpy( void *dst, const void *src, size_t n_bytes ) /*HDR*/ /** - * @brief Copy an array of bytes in reversed order, starting at end of buffer + * @brief Copy an array of bytes in reversed order, starting at end of buffer. * * Can be used if the destination address is in the same buffer * behind the source address, so the source address would be - * overwritten by a normal memcpy(). + * overwritten by a normal @a memcpy. * - * @param[out] dst Destination address behind the source address - * @param[in] src Source address - * @param[in] n_bytes Number of bytes to copy + * @param[out] dst Destination address behind the source address. + * @param[in] src Source address. + * @param[in] n_bytes Number of bytes to copy. * * @see ::mbg_memcpy */ void mbg_memcpy_reversed( void *dst, const void *src, size_t n_bytes ) { - if ( n_bytes ) // just to be sure it isn't 0 + if ( n_bytes ) // Just to be sure it isn't 0. { uint8_t *dstp = ( (uint8_t *) dst ) + n_bytes; uint8_t *srcp = ( (uint8_t *) src ) + n_bytes; diff --git a/mbglib/common/str_util.h b/mbglib/common/str_util.h index 83c375b..32db822 100644 --- a/mbglib/common/str_util.h +++ b/mbglib/common/str_util.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: str_util.h 1.6 2018/08/23 13:10:26Z martin REL_M $ + * $Id: str_util.h 1.12 2021/03/22 11:27:45Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,19 @@ * * ----------------------------------------------------------------------- * $Log: str_util.h $ - * Revision 1.6 2018/08/23 13:10:26Z martin + * Revision 1.12 2021/03/22 11:27:45Z martin + * Updated some comments. + * Revision 1.11 2021/03/16 12:21:51 martin + * Updated some comments. + * Revision 1.10 2021/03/12 11:00:28 martin + * Updated some doxygen comments. + * Revision 1.9 2020/10/15 13:38:44 martin + * Fixed build on FreeBSD. + * Revision 1.8 2020/02/27 13:57:12 martin + * Updated function prototypes. + * Revision 1.7 2019/07/31 15:42:39 martin + * Doxygen changes. + * Revision 1.6 2018/08/23 13:10:26 martin * New inline functions mbg_buffer_specs_valid() and * mbg_chk_snprint_results() that can also be called * from code used in kernel mode. @@ -40,6 +52,10 @@ #if defined( MBG_TGT_KERNEL ) #include <mbgddmsg.h> + + #if defined( MBG_TGT_FREEBSD ) + #include <sys/stddef.h> // NULL + #endif #else #include <stdlib.h> #include <stdarg.h> @@ -77,13 +93,13 @@ static __mbg_inline /*HDR*/ * passed to another function to specify an output buffer to be filled. * * If no buffer has been specified, or the size of the buffer which - * eventually remains after a previous operation is 0 or even less than 0 - * then no data can be placed in the buffer. + * may remain after a previous operation is 0 or even less than 0, + * no data can be placed in the buffer. * - * @param[in] s The address of the specified buffer + * @param[in] s The address of the specified buffer. * @param[in] max_len The size of the specified buffer. * - * @return true if the buffer address is not NULL and the size is > 0, else false. + * @return @a true if the buffer address is not @a NULL and the size is > 0, else @a false. */ bool mbg_buffer_specs_valid( char *s, size_t max_len ) { @@ -97,22 +113,22 @@ static __mbg_inline /*HDR*/ /** * @brief Check the results of an snprintf()-like function. * - * Implementations of snprintf()-like functions may behave differently + * Implementations of <em>snprintf</em>-like functions may behave differently * and badly if the specified output buffer is too small. * The exact behavior depends on the runtime library shipped with a * specific build environment for a specific operating system, * the version of that runtime library, and may even differ depending * on whether kernel mode or user mode code is compiled. * - * This function can be called after any snprintf()-like function + * This function can be called after any <em>snprintf</em>-like function * to make sure that a valid buffer is always 0-terminated, and the - * number returned to indicate how many bytes have been written to the - * buffer is never less than 0, and never exceeds the real size + * number returned to indicate how many bytes have been written to + * the buffer is never less than 0, and never exceeds the real size * of the buffer. * - * @param[in] n The return code from an snprintf()-like function that has been called before. - * @param[in] s The address of the buffer that had been passed to the snprintf()-like function. - * @param[in] max_len The size of the specified buffer that had been passed to the snprintf()-like function. + * @param[in] n The return code from an <em>snprintf</em>-like function that has been called before. + * @param[in] s The address of the buffer that had been passed to the <em>snprintf</em>-like function. + * @param[in] max_len The size of the specified buffer that had been passed to the <em>snprintf</em>-like function. * * @return The real number of bytes that had been written to the buffer. * @@ -158,27 +174,29 @@ out: /* by MAKEHDR, do not remove the comments. */ /** - * @brief A portable, safe implementation of vsnprintf() + * @brief A portable, safe implementation of vsnprintf(). * - * Unfortunately the behaviour of vsnprintf() and thus snprintf() - * differs in detail across various build environments and run time - * libraries. + * Unfortunately, the behavior of @a vsnprintf and therefore also that + * of @a snprintf differs in detail in different build environments + * and runtime libraries. * - * If the output exceeds the buffer size and thus is truncated then:<br> + * If the output exceeds the buffer size and thus is truncated, then:<br> * - * - Under Windows a negative value is returned and eventually *no* + * - On Windows, a negative value is returned and maybe ***no*** * terminating 0 is written to the output buffer, so the output string * may not be terminated properly. * - * - Some versions of glibc return the number of bytes that *would* - * have been written to the buffer *if* the buffer would have been + * - Some versions of glibc return the number of bytes that ***would*** + * have been written to the buffer ***if*** the buffer would have been * large enough, instead of the true number of characters that have * been written to the buffer. * * So subsequent calls like * - * n = snprintf( s, max_len, ... ); - * n += snprintf( &s[n], max_len - n, ... ); + * @code{.c} + n = snprintf( s, max_len, ... ); + n += snprintf( &s[n], max_len - n, ... ); + * @endcode * * may always work properly, or fail with buffer overruns or stack * corruption depending on the build environment. @@ -187,20 +205,21 @@ out: * characters really written to the string buffer, excluding the * terminating 0. * - * @note The "size_t" type parameter used to specify the buffer size - * can be larger (e.g. "unsigned long") than the "int" type returned - * by mostly all functions of the printf() family. So if a very large + * @note The @a size_t type parameter used to specify the buffer size + * can be larger (e.g. @a unsigned_long) than the @a int type returned + * by mostly all functions of the @a printf family. So if a very large * buffer is specified, and a large number of characters (more than - * MAXINT) are written to that buffer then how can an "int" type + * @a MAXINT) are written to that buffer, how can an @a int type * return the large number of characters written to the buffer? * We also try to workaround this here. * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] fmt Format string according to subsequent parameters - * @param[in] args Variable argument list in va_list format + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for a 0-terminated string. + * @param[in] fmt Format string according to subsequent parameters. + * @param[in] args Variable argument list in @a va_list format. * - * @return Number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::snprintf_safe * @see ::strncpy_safe @@ -210,40 +229,41 @@ out: __attribute__( ( format( printf, 3, 0 ) ) ) int vsnprintf_safe( char *s, size_t max_len, const char *fmt, va_list args ) ; /** - * @brief A portable, safe implementation of snprintf() + * @brief A portable, safe implementation of snprintf(). * - * For a detailed description see ::vsnprintf_safe + * For a detailed description see ::vsnprintf_safe. * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] fmt Format string according to subsequent parameters - * @param[in] ... Variable argument list according to the format string + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for a 0-terminated string. + * @param[in] fmt Format string according to subsequent parameters. + * @param[in] ... Variable argument list according to the format string. * - * @return Number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::vsnprintf_safe * @see ::strncpy_safe * @see ::sn_cpy_str_safe * @see ::sn_cpy_char_safe */ - __attribute__( ( format( printf, 3, 4 ) ) ) int snprintf_safe( char *s, size_t max_len, const char * fmt, ... ) ; + __attribute__( ( format( printf, 3, 4 ) ) ) int snprintf_safe( char *s, size_t max_len, const char *fmt, ... ) ; /** - * @brief A portable, safe implementation of strncpy() + * @brief A portable, safe implementation of strncpy(). * - * In the original implementation of strncpy(), if the length of the + * In the original implementation of @a strncpy, if the length of the * string to be copied into the destination buffer exceeds the specified - * buffer length then the string in the output buffer is not 0-terminated. + * buffer length, the string in the output buffer is not 0-terminated. * * Our implementation always forces a proper termination by 0, but unlike - * the original implementation of strncpy() it does *not* fill the whole + * the original implementation of @a strncpy, it does ***not*** fill the whole * remaining buffer space with '0' characters. * - * @param[out] dst Pointer to the output buffer - * @param[in] src Pointer to the input buffer - * @param[in] max_len Size of the output buffer for 0-terminated string + * @param[out] dst Pointer to the output buffer. + * @param[in] src Pointer to the input buffer. + * @param[in] max_len Size of the output buffer for 0-terminated string. * - * @return Pointer to the destination buffer + * @return Pointer to the destination buffer. * * @see ::vsnprintf_safe * @see ::snprintf_safe @@ -253,17 +273,18 @@ out: char *strncpy_safe( char *dst, const char *src, size_t max_len ) ; /** - * @brief A function to copy a string safely, returning the number of characters copied + * @brief A function to copy a string safely, returning the number of characters copied. * * This basically works like ::strncpy_safe but instead of a pointer to * the destination buffer it returns the number of characters copied * to the destination buffer. * - * @param[out] dst Pointer to the output buffer - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] src Pointer to the input buffer + * @param[out] dst Pointer to the output buffer. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] src Pointer to the input buffer. * - * @return Number of characters copied to the destination buffer + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::vsnprintf_safe * @see ::snprintf_safe @@ -273,18 +294,19 @@ out: int sn_cpy_str_safe( char *dst, size_t max_len, const char *src ) ; /** - * @brief A function to copy a character safely to a string buffer + * @brief A function to copy a character safely to a string buffer. * * This basically works like ::sn_cpy_str_safe but expects a character * to be copied to the destination buffer. Appends a terminating 0 to * the string buffer and returns the number of characters copied to * the destination buffer, usually 0 or 1. * - * @param[out] dst Pointer to the output buffer - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] c Character to be copied to the destination buffer + * @param[out] dst Pointer to the output buffer. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] c Character to be copied to the destination buffer. * - * @return Number of characters copied to the destination buffer, without the terminating 0 + * @return The number of characters written to the output buffer, + * except the terminating 0. * * @see ::vsnprintf_safe * @see ::snprintf_safe @@ -294,53 +316,53 @@ out: int sn_cpy_char_safe( char *dst, size_t max_len, char c ) ; /** - * @brief Trim whitespace at the end of a string + * @brief Trim whitespace at the end of a string. * - * @param[in,out] s The string to be trimmed + * @param[in,out] s The string to be trimmed. */ void trim_trailing_whitespace( char *s ) ; /** - * @brief Trim whitespace at the beginning of a string + * @brief Trim whitespace at the beginning of a string. * - * @param[in,out] s The string to be trimmed + * @param[in,out] s The string to be trimmed. */ void trim_leading_whitespace( char *s ) ; /** - * @brief Trim both leading and trailing whitespace from a string + * @brief Trim both leading and trailing whitespace from a string. * - * @param[in,out] s The string to be trimmed + * @param[in,out] s The string to be trimmed. */ void trim_whitespace( char *s ) ; /** - * @brief Copy array of bytes starting at beginning of buffer + * @brief Copy array of bytes starting at beginning of buffer. * * Can be used if the destination address is in the same buffer * in front of the source address. Even though you would expect - * that memcpy() would also work for this properly, we have seen - * cases where it didn't, and only memmove() worked correctly. - * Anyway, we try to avoid the overhead of memmove(). + * that @a memcpy would also work for this properly, we have seen + * cases where it didn't, and only @a memmove worked correctly. + * Anyway, we try to avoid the overhead of @a memmove. * - * @param[out] dst Destination address behind the source address - * @param[in] src Source address - * @param[in] n_bytes Number of bytes to copy + * @param[out] dst Destination address behind the source address. + * @param[in] src Source address. + * @param[in] n_bytes Number of bytes to copy. * * @see ::mbg_memcpy_reversed */ void mbg_memcpy( void *dst, const void *src, size_t n_bytes ) ; /** - * @brief Copy an array of bytes in reversed order, starting at end of buffer + * @brief Copy an array of bytes in reversed order, starting at end of buffer. * * Can be used if the destination address is in the same buffer * behind the source address, so the source address would be - * overwritten by a normal memcpy(). + * overwritten by a normal @a memcpy. * - * @param[out] dst Destination address behind the source address - * @param[in] src Source address - * @param[in] n_bytes Number of bytes to copy + * @param[out] dst Destination address behind the source address. + * @param[in] src Source address. + * @param[in] n_bytes Number of bytes to copy. * * @see ::mbg_memcpy */ diff --git a/mbglib/common/timeutil.c b/mbglib/common/timeutil.c index 672b188..03c7cc4 100644 --- a/mbglib/common/timeutil.c +++ b/mbglib/common/timeutil.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: timeutil.c 1.10 2019/02/08 10:51:44Z martin REL_M $ + * $Id: timeutil.c 1.15 2021/03/22 11:52:30Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,18 @@ * * ----------------------------------------------------------------------- * $Log: timeutil.c $ - * Revision 1.10 2019/02/08 10:51:44Z martin + * Revision 1.15 2021/03/22 11:52:30Z martin + * Updated some comments. + * Revision 1.14 2021/03/12 12:32:18 martin + * Updated some comments. + * Revision 1.13 2019/09/27 15:22:30 martin + * Fixed naming of some variables, and updated some comments. + * Revision 1.12 2019/09/10 13:13:23 martin + * Fixed doxygen comments. + * Revision 1.11 2019/07/19 14:20:52 martin + * Cleaned up mbg_clock_gettime() and mbg_clock_settime(), + * and let them set an appropriate POSIX error code on error. + * Revision 1.10 2019/02/08 10:51:44 martin * Removed some definitions that are also in the header file. * Fixed a compiler warning. * Revision 1.9 2018/12/18 11:00:48 martin @@ -29,7 +40,7 @@ * Revision 1.4 2017/11/16 11:33:28 philipp * Added functions to print a time_t to ISO format * Revision 1.3 2017/08/24 13:51:48 martin - * Fixed a xcompiler warning under Windows (x64). + * Fixed a xcompiler warning on Windows (x64). * Revision 1.2 2017/07/05 07:10:48Z martin * Added mbg_clock_gettime(), mbg_clock_settime(), * and check_precise_time_api() for Windows. @@ -47,6 +58,7 @@ #if defined( MBG_TGT_WIN32 ) #include <stdio.h> + #include <errno.h> #endif @@ -77,54 +89,82 @@ int snprint_gmtime_error( char *s, size_t max_len, int mbg_errno, time_t t, cons #if defined( MBG_TGT_WIN32 ) /*HDR*/ +/** + * @brief A Windows implementation for POSIX @a clock_gettime. + * + * @param[in] clock_id Identifier of a specific clock, e.g. + * @a CLOCK_REALTIME, @a CLOCK_MONOTONIC, etc. + * @param[out] tp Address of a <em>struct timespec</em> + * to take up the current time. + * + * @return 0 on success, -1 on error, just like the POSIX function. + * In case of an error the POSIX errno variable is set + * appropriately. + */ int mbg_clock_gettime( clockid_t clock_id, struct timespec *tp ) { - // FIXME TODO Should we return a POSIX-compatible return code - // with 0 for success and -1 indicating an error? - // - // If we'd do we had to set "errno" or the value returned - // by Windows' GetLastError() to some specific error code - // that can be retrieved by the application. However, there's - // a problem when timespec_get() is used to implement this. - - // On success, timespec_get() returns the value of the "base" - // parameter that has been passed to timespec_get(), e.g. - // TIME_UTC. On error, it returns 0, but the usual docs for - // timespec_get() don't mention if there's a way to determine - // the reason for the failure, e.g. by retrieving a value - // from"errno" or so. - // - // So for now we return 0 on success as usual, and -1 - // on error, but the caller is unable to determine the - // reason for the fauilure. - - if ( clock_id == CLOCK_REALTIME ) + switch ( clock_id ) { - #if defined( TIME_UTC ) // C11 / VS2015+ - int rc = timespec_get( tp, TIME_UTC ); - return ( rc == 0 ) ? -1 : 0; - #else - FILETIME ft; - unsigned __int64 tmp; - gstaft_fnc( &ft ); - tmp = ( (__int64) ft.dwHighDateTime << 32 ) | ft.dwLowDateTime; - tmp -= FILETIME_1970; // convert to Unix epoch - tmp *= 100; // convert to nanoseconds - tp->tv_sec = (time_t) ( tmp / NSEC_PER_SEC ); - tp->tv_nsec = (long) ( tmp % NSEC_PER_SEC ); - return 0; - #endif + case CLOCK_REALTIME: + case CLOCK_MONOTONIC: + // FIXME TODO CLOCK_MONOTONIC should be implemented separately, + // e.g. using QPC. + { + #if defined( TIME_UTC ) // C11 / VS2015+ + if ( timespec_get( tp, TIME_UTC ) == 0 ) + goto fail; // error + #else + FILETIME ft; + uint64_t u64; + gstaft_fnc( &ft ); + // Always succeeds. + u64 = ( ( (uint64_t) ft.dwHighDateTime ) << 32 ) | ft.dwLowDateTime; + u64 -= FILETIME_1970; // Convert to Unix epoch. + u64 *= 100; // Convert to nanoseconds. + // 'time_t' is 64 bits wide on Windows, if using + // Visual Studio 2005 or newer. + tp->tv_sec = (time_t) ( u64 / NSEC_PER_SEC ); + tp->tv_nsec = (long) ( u64 % NSEC_PER_SEC ); + #endif + } break; + + default: + goto fail; } - else - return -1; // TODO this is e.g. in case of CLOCK_MONOTONIC, we could use QPC then. + + // Just like POSIX clock_gettime(), we return 0 on success. + return 0; + +fail: + // The specified clock_id is not supported. + // Set the POSIX errno variable appropriately + // and return -1 just like clock_gettime() + // does in case of error. + errno = EINVAL; + return -1; } // mbg_clock_gettime /*HDR*/ +/** + * @brief A Windows implementation for POSIX @a clock_settime. + * + * @param[in] clock_id Identifier of a specific clock, i.e. + * @a CLOCK_REALTIME which is the only clock + * supported by this call. + * @param[in] tp Pointer to a struct timespec providing + * the time to be set. + * + * @return 0 on success, -1 on error, just like the POSIX function. + * In case of an error the POSIX errno variable is set + * appropriately. + */ int mbg_clock_settime( clockid_t clock_id, const struct timespec *tp ) { + DWORD dw; + if ( clock_id == CLOCK_REALTIME ) { SYSTEMTIME st; @@ -138,17 +178,41 @@ int mbg_clock_settime( clockid_t clock_id, const struct timespec *tp ) (ULONGLONG) tp->tv_sec * HNS_PER_SEC + (ULONGLONG) tp->tv_nsec / 100; + // According to the MS API docs the FILETIME to be converted + // must be less than 0x8000000000000000. Otherwise, the function + // fails, and apparently sets error code ERROR_INVALID_PARAMETER. if ( !FileTimeToSystemTime( &t.ft, &st ) ) - goto fail; // GetLastError() returns the error code + goto fail; if ( !SetSystemTime( &st ) ) - goto fail; // GetLastError() returns the error code + goto fail; + // Just like POSIX clock_settime(), we return 0 on success. return 0; -} + } fail: - return -1; // TODO this is e.g. in case of CLOCK_MONOTONIC, we could use QPC then. + // One of the Windows API calls above failed, so the + // original error information is a Windows error code. + // Anyway, we try to find an appropriate POSIX error + // code, set the POSIX errno variable accordingly, and + // return -1 just like POSIX clock_settime() does + // in case of error. + + dw = GetLastError(); + + switch ( dw ) + { + case ERROR_PRIVILEGE_NOT_HELD: + errno = EPERM; + break; + + case ERROR_INVALID_PARAMETER: + default: + errno = EINVAL; + } + + return -1; } // mbg_clock_settime @@ -163,7 +227,7 @@ void check_precise_time_api( void ) GSTAFT_FNC tmp_fnc; HINSTANCE h = LoadLibrary( "kernel32.dll" ); - if ( h == NULL ) // TODO error msg + if ( h == NULL ) // TODO Error msg. { info = "Precise system time may not be supported; failed to get handle for kernel32.dll."; goto out; @@ -197,16 +261,17 @@ out: /*HDR*/ /** - * @brief Print a UTC offset into a string + * @brief Print a %UTC offset into a string. * * Format of the string is "[info]+hh[:mm[:ss]]h" * * @param[out] s Address of a string buffer to be filled. * @param[in] max_len Size of the string buffer. - * @param[in] info An optional info string to be prepended, may be NULL. - * @param[in] utc_offs The UTC offset to be printed, in [s]. + * @param[in] info An optional info string to be prepended, may be @a NULL. + * @param[in] utc_offs The %UTC offset to be printed, in [s]. * - * @return The number of characters written to the output buffer, except the terminating 0. + * @return The number of characters written to the string buffer, + * except the terminating 0. */ int snprint_utc_offs( char *s, size_t max_len, const char *info, long utc_offs ) { diff --git a/mbglib/common/timeutil.h b/mbglib/common/timeutil.h index ed87e9f..40f1a14 100644 --- a/mbglib/common/timeutil.h +++ b/mbglib/common/timeutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: timeutil.h 1.10 2019/02/11 09:49:46Z martin REL_M $ + * $Id: timeutil.h 1.16 2021/04/22 08:37:50Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,24 @@ * * ----------------------------------------------------------------------- * $Log: timeutil.h $ - * Revision 1.10 2019/02/11 09:49:46Z martin + * Revision 1.16 2021/04/22 08:37:50Z martin + * Avoid some compiler warnings. + * Revision 1.15 2021/03/22 11:52:33 martin + * Updated some comments. + * Revision 1.14 2019/09/27 15:26:27 martin + * New inline functions mbg_exp_time_t_to_time64_t() and + * mbg_trnc_time64_t_to_time_t(). + * Updated function prototypes and doxygen comments. + * Revision 1.13 2019/09/10 13:10:25 martin + * Fixed doxygen comments. + * Revision 1.12 2019/08/07 09:05:44 martin + * New inline function mbg_gmtime64(). + * Updated doxygen comments. + * Revision 1.11 2019/07/19 14:29:07 martin + * Define CLOCK_MONOTONIC, clock_gettime() and + * clock_settime() on Windows, if appropriate. + * Updated function prototypes. + * Revision 1.10 2019/02/11 09:49:46 martin * Support the mingw build environment. * Fixed build for targets that don't support 64 bit types. * Revision 1.9 2018/12/11 15:36:40 martin @@ -46,6 +63,7 @@ #include <time.h> #include <stddef.h> +#include <assert.h> #ifdef _TIMEUTIL @@ -63,13 +81,17 @@ extern "C" { #endif -// exclude for MinGW #if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_DOS ) + // We don't need this with MinGW. #if !defined( MBG_TGT_MINGW ) typedef int clockid_t; #define clockid_t clockid_t #define CLOCK_REALTIME ( (clockid_t) 0 ) + #define CLOCK_MONOTONIC ( (clockid_t) 1 ) + + #define clock_gettime mbg_clock_gettime + #define clock_settime mbg_clock_settime #endif #endif @@ -80,10 +102,11 @@ extern "C" { #define __const__ const /** - * @brief A pointer to a function returning the system time as FILETIME + * @brief A pointer to a function returning the system time as @a FILETIME. * - * This can be e.g. the standard Windows API call GetSystemTimeAsFileTime() - * or the GetSystemTimeAsPreciseFileTime() API call introduced with Windows 8. + * This can be e.g. the standard Windows API call @a GetSystemTimeAsFileTime + * or the @a GetSystemTimeAsPreciseFileTime API call available on Windows 8 + * and later Windows versions. */ typedef VOID (WINAPI *GSTAFT_FNC)(LPFILETIME lpSystemTimeAsFileTime); @@ -98,28 +121,177 @@ _ext GSTAFT_FNC gstaft_fnc #if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) - typedef int64_t mbg_time_t; // we try to always use 64 bit types + typedef int64_t mbg_time_t; // We try to always use 64 bit types. #else - typedef time_t mbg_time_t; // fall back to the default + typedef time_t mbg_time_t; // Fall back to the default. #endif -static __mbg_inline + +static __mbg_inline /*HDR*/ time_t cvt_to_time_t( mbg_time_t t ) { - // Eventually we can do some epoch check / conversion here. + // Maybe we can do some epoch check / conversion here. return (time_t) t; } // cvt_to_time_t -static __mbg_inline -int mbg_gmtime( struct tm *p_tm, const time_t *p_time ) +static __mbg_inline /*HDR*/ +int mbg_exp_time_t_to_time64_t( MBG_TIME64_T *p_t64, const time_t *p_t ) +{ + if ( sizeof( time_t ) == sizeof( MBG_TIME64_T ) ) + { + // No conversion required. + *p_t64 = *p_t; + return MBG_SUCCESS; + } + + // 'time_t' has 32 bits only. + + *p_t64 = (MBG_TIME64_T) (*p_t); + // FIXME TODO Maybe we should do some + // epoch conversion / range mapping here. + + return MBG_SUCCESS; + +} // mbg_exp_time_t_to_time64_t + + + +static __mbg_inline /*HDR*/ +int mbg_trnc_time64_t_to_time_t( time_t *p_t, const MBG_TIME64_T *p_t64 ) +{ + int rc = MBG_SUCCESS; + + if ( sizeof( time_t ) == sizeof( MBG_TIME64_T ) ) + goto done; // No range check required. + + + if ( sizeof( time_t ) == sizeof( MBG_TIME32_T ) ) + { + // Must check if result in in range. + MBG_TIME64_T t64 = *p_t64; + int64_t upper_limit; + int64_t lower_limit; + + if ( ( (time_t) -1 ) > 0 ) // time_t is unsigned. + { + upper_limit = 0xFFFFFFFFUL; + lower_limit = 0; + } + else // time_t is signed. + { + upper_limit = 0x7FFFFFFFL; + lower_limit = 0x8000000L; + } + + if ( ( t64 > upper_limit ) || ( t64 < lower_limit ) ) + rc = MBG_ERR_OVERFLOW; + + goto done; + } + + rc = MBG_ERR_NOT_SUPP_ON_OS; + goto out; + + +done: + *p_t = (time_t) (*p_t64); + +out: + return rc; + +} // mbg_trnc_time64_t_to_time_t + + + +static __mbg_inline /*HDR*/ +int mbg_cvt_time32_t_to_time64_t( MBG_TIME64_T *p_t64, const MBG_TIME32_T *p_t32 ) +{ + // FIXME TODO Move the checks below to an extra inline function + // which does an epoch conversion, if required. + + // Avoid warnings "never used". + (void) p_t64; + (void) p_t32; + +#if 0 + // time_t should be at least 4 bytes + assert( sizeof( time_t ) >= 4 ); + + if ( sizeof( time_t ) == 4 ) + { + // 32 bit *signed* time_t will roll over after 2038-01-19 03:14:07 + // when the number of seconds reaches 0x7FFFFFFF, so we don't try + // conversions for 2038 or later, though 32 bit *unsigned* time_t + // may still work after year 2100. + if ( year < 70 || year > 137 ) + { + rc = MBG_ERR_RANGE; + goto out; + } + } + else + if ( sizeof( time_t ) == 8 ) + { + // 64 bit time_t will work for million years. However, it's not + // clear what happens for dates before 1970-01-01T00:00:00 if time_t + // is *unsigned*. + if ( year < 70 ) + { + rc = MBG_ERR_RANGE; + goto out; // TODO Maybe we can handle this ... + } + } + else + { + rc = MBG_ERR_NOT_SUPP_ON_OS; + goto out; + } +#endif + + return MBG_SUCCESS; + +} // mbg_cvt_time32_t_to_time64_t + + + + +static __mbg_inline /*HDR*/ +/** + * @brief A replacement function for POSIX @a gmtime. + * + * This function calls the original @a gmtime function, but unlike @a gmtime, + * it expects the address of a <em>struct tm</em> variable which is only filled + * if @a gmtime completed successfully. An appropriate return code + * is provided, indicating whether the conversion succeeded, or not. + * + * The original @a gmtime function returns a @a NULL pointer if the conversion + * fails, so a programs which just uses the pointer without checking it first + * may trap if the conversion fails. This can't happen with this function. + * + * This variant expects the address of a generic @a time_t variable. A @a time_t can + * be 32 bit or 64 bit wide, depending on the build environment and target system. + * Systems with 32 bit @a time_t will <b>suffer from the Y2038 problem</b>. + * + * There is also the ::mbg_gmtime64 variant, which expects a pointer to an + * ::MBG_TIME64_T variable to be converted, which is always 64 bits, even + * on 32 bit systems. + * + * @param[out] p_tm Address of a <em>struct tm</em> variable to take the conversion result. + * @param[in] p_t Address of a @a time_t variable to be converted. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_gmtime64 + */ +int mbg_gmtime( struct tm *p_tm, const time_t *p_t ) { - struct tm *p_tm_tmp = gmtime( p_time ); + struct tm *p_tm_tmp = gmtime( p_t ); - if ( p_tm_tmp == NULL ) // conversion failed + if ( p_tm_tmp == NULL ) // Conversion failed. return mbg_get_last_error( NULL ); *p_tm = *p_tm_tmp; @@ -130,6 +302,46 @@ int mbg_gmtime( struct tm *p_tm, const time_t *p_time ) +static __mbg_inline /*HDR*/ +/** + * @brief A replacement function for POSIX @a gmtime. + * + * This variant of ::mbg_gmtime expects a pointer to an ::MBG_TIME64_T variable + * to be converted, which is always 64 bits, even on 32 bit systems. + * + * Actually, the ::MBG_TIME64_T value is truncated to a native @a time_t, which can + * be 32 bit or 64 bit wide, depending on the build environment and target system. + * So this "just works" on systems with 64 bit @a time_t, but systems with 32 bit @a time_t + * will anyway suffer from the Y2038 problem, unless the @a gmtime call is replaced + * by a function that does a 64 bit conversion even on systems with 32 bit @a time_t. + * + * @param[out] p_tm Address of a <em>struct tm</em> variable to take the conversion result. + * @param[in] p_t64 Pointer to an ::MBG_TIME64_T providing the timestamp to be converted. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_gmtime + */ +int mbg_gmtime64( struct tm *p_tm, const MBG_TIME64_T *p_t64 ) +{ + struct tm *p_tm_tmp; + time_t t = cvt_to_time_t( *p_t64 ); + + // FIXME TODO Need to implement gmtime64() + // which always works with 64 bit timestamps. + p_tm_tmp = gmtime( &t ); + + if ( p_tm_tmp == NULL ) // Conversion failed. + return mbg_get_last_error( NULL ); + + *p_tm = *p_tm_tmp; + + return MBG_SUCCESS; + +} // mbg_gmtime64 + + + #if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) static __mbg_inline /*HDR*/ @@ -245,20 +457,48 @@ int64_t delta_timespec_ll_ns( const struct timespec *ts, /* by MAKEHDR, do not remove the comments. */ int snprint_gmtime_error( char *s, size_t max_len, int mbg_errno, time_t t, const char *calling_fnc ) ; + /** + * @brief A Windows implementation for POSIX @a clock_gettime. + * + * @param[in] clock_id Identifier of a specific clock, e.g. + * @a CLOCK_REALTIME, @a CLOCK_MONOTONIC, etc. + * @param[out] tp Address of a <em>struct timespec</em> + * to take up the current time. + * + * @return 0 on success, -1 on error, just like the POSIX function. + * In case of an error the POSIX errno variable is set + * appropriately. + */ int mbg_clock_gettime( clockid_t clock_id, struct timespec *tp ) ; + + /** + * @brief A Windows implementation for POSIX @a clock_settime. + * + * @param[in] clock_id Identifier of a specific clock, i.e. + * @a CLOCK_REALTIME which is the only clock + * supported by this call. + * @param[in] tp Pointer to a struct timespec providing + * the time to be set. + * + * @return 0 on success, -1 on error, just like the POSIX function. + * In case of an error the POSIX errno variable is set + * appropriately. + */ int mbg_clock_settime( clockid_t clock_id, const struct timespec *tp ) ; + void check_precise_time_api( void ) ; /** - * @brief Print a UTC offset into a string + * @brief Print a %UTC offset into a string. * * Format of the string is "[info]+hh[:mm[:ss]]h" * * @param[out] s Address of a string buffer to be filled. * @param[in] max_len Size of the string buffer. - * @param[in] info An optional info string to be prepended, may be NULL. - * @param[in] utc_offs The UTC offset to be printed, in [s]. + * @param[in] info An optional info string to be prepended, may be @a NULL. + * @param[in] utc_offs The %UTC offset to be printed, in [s]. * - * @return The number of characters written to the output buffer, except the terminating 0. + * @return The number of characters written to the string buffer, + * except the terminating 0. */ int snprint_utc_offs( char *s, size_t max_len, const char *info, long utc_offs ) ; diff --git a/mbglib/common/toolutil.c b/mbglib/common/toolutil.c index 46c8e65..9eba445 100644 --- a/mbglib/common/toolutil.c +++ b/mbglib/common/toolutil.c @@ -1,15 +1,57 @@ /************************************************************************** * - * $Id: toolutil.c 1.10 2019/02/08 10:34:47Z martin REL_M $ + * $Id: toolutil.c 1.22 2021/11/08 21:37:29Z martin.burnicki REL_M $ * - * Description: - * Common functions which can be used with Meinberg command line - * utility programs. + * Common functions that can be used with Meinberg command line + * utility programs. * * ----------------------------------------------------------------------- * $Log: toolutil.c $ - * Revision 1.10 2019/02/08 10:34:47Z martin + * Revision 1.22 2021/11/08 21:37:29Z martin.burnicki + * SYN1588 devices are now enumerated after native Meinberg devices. + * Print build number of SYN1588 device instead of firmware version. + * Use new functions from mbgdevio to reduce dependies on conditional + * preprocessor symbols. + * Revision 1.21 2021/11/08 18:02:46 martin.burnicki + * Account for modified MBG_DEV_FN type. + * Revision 1.20 2021/05/04 20:45:53 martin + * Cleaned up conditional support for SYN1588. + * Revision 1.19 2021/04/29 13:09:18 martin + * Account for definitions that were moved to mbgutil.h. + * Revision 1.18 2021/04/12 22:04:08 martin + * Basic support for serial devices. + * Updated printing of usage information. + * Revision 1.17 2021/03/22 11:25:09 martin + * Updated a bunch of comments. + * Revision 1.16 2021/03/12 10:51:30 martin + * Updated some doxygen comments. + * Revision 1.15 2020/11/04 16:59:12 martin + * Moved inline function delta_timestamps() to the header file + * and renamed it to delta_timestamp_us() because the returned + * value is in microseconds. + * Revision 1.14 2020/10/20 10:45:17 martin + * New function mbg_has_admin_rights() that can be used to check + * if a program is running with admin rights, or not. + * New function mbg_chk_print_no_admin_rights() which conditionally + * prints a warning that SYN1588 devices may not be detected if running + * without admin rights. + * New function mbg_print_no_device_found() that can be called + * to print information that no device has been found. Also + * calls mbg_chk_print_no_admin_rights() to give a hint for + * a possible reason. + * Revision 1.13 2020/02/27 13:34:52 martin + * mbg_print_opt_info() now accepts printf-like format string as + * 2nd argument, plus associated optional parameters. + * mbg_show_pzf_corr_info() now just prints the + * correlation info, but doesn't read it from the device. + * Removed inclusion of obsolete header pcpsutil.h. + * Account for a renamed function. + * Revision 1.12 2019/06/25 15:22:34 martin + * Print the latency value of a HR time at the end of a line for clearer output. + * Revision 1.11 2019/05/08 11:27:35 martin + * Use new symbol PCPS_IRQ_NUM_UNDEFINED. + * Revision 1.10 2019/02/08 10:34:47 martin * Fix for the mingw build environment. * Revision 1.9 2018/12/14 13:13:46 martin * Cleaned up mbg_open_device_by_param(), removed obsolete @@ -74,9 +116,9 @@ #include <toolutil.h> #undef _TOOLUTIL -// include Meinberg headers +// Include Meinberg headers. +#include <mbgutil.h> #include <cfg_hlp.h> -#include <pcpsutil.h> #include <timeutil.h> #include <str_util.h> @@ -84,7 +126,11 @@ #include <mbgsvctl.h> #endif -// include system headers +#if SUPP_SERIAL + #include <mbgserio.h> +#endif + +// Include system headers. #include <stdio.h> #include <stdlib.h> #include <string.h> @@ -101,36 +147,15 @@ -static __mbg_inline -/** - * @brief Compute the difference between two ::PCPS_TIME_STAMP values - * - * @param[in] p_ts Pointer to the current time stamp. - * @param[in] p_prv_ts Pointer to a previous time stamp. - * - * @return The time difference as double, in microseconds. - */ -double delta_timestamps( const PCPS_TIME_STAMP *p_ts, const PCPS_TIME_STAMP *p_prv_ts ) -{ - uint64_t ts = pcps_time_stamp_to_uint64( p_ts ); - uint64_t prv_ts = pcps_time_stamp_to_uint64( p_prv_ts ); - - // We divide by MBG_FRAC32_UNITS_PER_SEC to get the correct fractions - // and we multiply by 1E6 to get the result in microseconds. - return (double) ( (int64_t) ( ts - prv_ts ) ) * 1E6 / MBG_FRAC32_UNITS_PER_SEC; - -} // delta_timestamps - - - /*HDR*/ /** - * @brief Print the program version to a string buffer + * @brief Print the program version to a string buffer. * - * @param[out] s Address of a string buffer to be filled. - * @param[in] max_len Size of the string buffer. + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. * - * @return The number of characters printed to the buffer. + * @return The number of characters written to the string buffer, + * except the terminating 0. */ int mbg_program_version_str( char *s, size_t max_len ) { @@ -147,15 +172,16 @@ int mbg_program_version_str( char *s, size_t max_len ) /*HDR*/ /** - * @brief Print some program info to a string buffer + * @brief Print some program info to a string buffer. * - * @param[out] s Address of a string buffer to be filled. - * @param[in] max_len Size of the string buffer. - * @param[in] pname The program name. - * @param[in] first_year First copyright year. - * @param[in] last_year Last copyright year. + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. + * @param[in] pname The program name. + * @param[in] first_year First copyright year. + * @param[in] last_year Last copyright year. * - * @return The number of characters printed to the buffer. + * @return The number of characters written to the string buffer, + * except the terminating 0. */ int mbg_program_info_str( char *s, size_t max_len, const char *pname, int first_year, int last_year ) @@ -184,18 +210,18 @@ int mbg_program_info_str( char *s, size_t max_len, const char *pname, /*HDR*/ /** - * @brief Print program info to console + * @brief Print program info to console. * - * @param[in] pname The program name. - * @param[in] first_year First copyright year. - * @param[in] last_year Last copyright year. + * @param[in] pname The program name. + * @param[in] first_year First copyright year. + * @param[in] last_year Last copyright year. */ void mbg_print_program_info( const char *pname, int first_year, int last_year ) { char ws[256]; - // If the output has been redirected then make stdout unbuffered, - // e.g. to see the output immediately even though piped through 'tee'. + // If the output has been redirected, make stdout unbuffered, e.g. + // to see the output immediately even though piped through 'tee'. if ( !isatty( fileno( stdout ) ) ) setvbuf( stdout, NULL, _IONBF, 0 ); @@ -209,10 +235,70 @@ void mbg_print_program_info( const char *pname, int first_year, int last_year ) /*HDR*/ /** - * @brief Print usage intro to console + * @brief Check if the program runs with admin rights. + * + * @return @a true if runs with admin rights, else @a false. + */ +bool mbg_has_admin_rights( void ) +{ + #if defined( MBG_TGT_WIN32 ) + return mbg_svc_has_admin_rights(); + #elif defined( MBG_TGT_POSIX ) + return geteuid() == 0; + #else + #error mbg_has_admin_rights() needs to be implemented. + #endif + +} // mbg_has_admin_rights + + + +/*HDR*/ +/** + * @brief Print a warning if program runs without admin rights. + * + * Yet, this is only relevant for the detection of SYN1588 devices. + */ +void mbg_chk_print_no_admin_rights( void ) +{ + #if defined( MBG_TGT_WIN32 ) + if ( mbg_rc_is_success( mbg_chk_if_syn1588_supported() ) ) + if ( !mbg_has_admin_rights() ) + printf( "\n" + "Running without admin rights, so %s devices\n" + "may not be visible, even though supported.\n", + mbg_get_syn1588_type_name() ); + #endif + +} // mbg_chk_print_no_admin_rights + + + +/*HDR*/ +/** + * @brief Print a warning if no device has been found. + * + * If SYN1588 support is enabled, also possibly print + * a warning if running without admin rights, because + * on some systems, SYN1588 devices may not be detected + * without admin rights. + */ +void mbg_print_no_device_found( void ) +{ + printf( "No device found.\n" ); + mbg_chk_print_no_admin_rights(); + printf( "\n" ); + +} // mbg_print_no_device_found + + + +/*HDR*/ +/** + * @brief Print usage intro to console. * - * @param[in] pname The program name. - * @param[in] info An optional additional info string, may be NULL. + * @param[in] pname The program name. + * @param[in] info An optional additional info string, may be @a NULL. */ void mbg_print_usage_intro( const char *pname, const char *info ) { @@ -228,20 +314,32 @@ void mbg_print_usage_intro( const char *pname, const char *info ) /*HDR*/ /** - * @brief Print info on a single program option / argument + * @brief Print info on a single program option / argument. * - * @param[in] opt_name The option name, optional, may be NULL. - * @param[in] opt_info The option info, optional, may be NULL. + * @param[in] opt_name The option name, optional, may be @a NULL. + * @param[in] opt_info_fmt The option info format string, optional, may be @a NULL. + * @param[in] ... Variable argument list according to the @p fmt format string. */ -void mbg_print_opt_info( const char *opt_name, const char *opt_info ) +__attribute__( ( format( printf, 2, 3 ) ) ) +void mbg_print_opt_info( const char *opt_name, const char *opt_info_fmt, ... ) { if ( opt_name == NULL ) opt_name = str_empty; - if ( opt_info == NULL ) - opt_info = str_empty; + printf( " %8s", opt_name ); + + if ( opt_info_fmt ) + { + va_list args; + + printf( " " ); - printf( " %8s %s\n", opt_name, opt_info ); + va_start( args, opt_info_fmt ); + vprintf( opt_info_fmt, args ); + va_end( args ); + } + + printf( "\n" ); } // mbg_print_opt_info @@ -249,7 +347,7 @@ void mbg_print_opt_info( const char *opt_name, const char *opt_info ) /*HDR*/ /** - * @brief Print info on common program help arguments + * @brief Print info on common program help arguments. * * Lists program parameters causing printing * of help / usage information. @@ -257,7 +355,7 @@ void mbg_print_opt_info( const char *opt_name, const char *opt_info ) void mbg_print_help_options( void ) { puts( "where \"opt\" is one of the options:" ); - mbg_print_opt_info( "-? or -h", "print this usage information" ); + mbg_print_opt_info( "-? or -h", "Print this usage information" ); } // mbg_print_help_options @@ -265,22 +363,39 @@ void mbg_print_help_options( void ) /*HDR*/ /** - * @brief Print common info on how to specify devices on the command line + * @brief Print common info on how to specify devices on the command line. + * + * @param[in] mask Bit mask to control for which kind of devices + * information shall be displayed. + * See ::DEV_OPT_PRINT_MASKS. + * + * @see ::DEV_OPT_PRINT_MASKS */ -void mbg_print_device_options( void ) +void mbg_print_device_options( int mask ) { printf( "\n" ); puts( "where \"dev\" can be:" ); - #if MBG_TGT_HAS_DEV_FN_BASE - printf( " a device file name, e.g. \"%s\" or \"%s\"\n", - EXAMPLE_DEV_FN_1, EXAMPLE_DEV_FN_2 ); - #endif - printf( " a device type name, with or with S/N appended, e.g. \"%s\" or \"%s\"\n", - EXAMPLE_DEV_NAME_1, EXAMPLE_DEV_NAME_2 ); + if ( mask & DEV_OPT_PRINT_BUS_LEVEL ) + { + #if MBG_TGT_HAS_DEV_FN_BASE + printf( " A device file name, e.g. \"%s\" or \"%s\"\n", + EXAMPLE_DEV_FN_1, EXAMPLE_DEV_FN_2 ); + #endif + printf( " A device type name, with or with S/N appended, e.g. \"%s\" or \"%s\"\n", + EXAMPLE_DEV_NAME_1, EXAMPLE_DEV_NAME_2 ); + + printf( " A device index, e.g. \"0\", \"1\",\"2\", ...\n" ); + } - printf( " a device index, e.g. \"0\", \"1\",\"2\", ...\n" ); + #if SUPP_SERIAL + if ( mask & DEV_OPT_PRINT_SERIAL ) + { + printf( " The name of a serial port, to which an external device\n"); + printf( " is connected, e.g. %s\n", DEFAULT_SERIAL_DEVICE_NAME ); + } + #endif } // mbg_print_device_options @@ -288,16 +403,16 @@ void mbg_print_device_options( void ) /*HDR*/ /** - * @brief Print program info and default usage information + * @brief Print program info and default usage information. * - * @param[in] pname The program name. - * @param[in] prog_info An optional additional info string, may be NULL. + * @param[in] pname The program name. + * @param[in] prog_info An optional additional info string, may be @a NULL. */ void mbg_print_default_usage( const char *pname, const char *prog_info ) { mbg_print_usage_intro( pname, prog_info ); mbg_print_help_options(); - mbg_print_device_options(); + mbg_print_device_options( DEV_OPT_PRINT_BUS_LEVEL ); puts( "" ); } // mbg_print_default_usage @@ -306,13 +421,13 @@ void mbg_print_default_usage( const char *pname, const char *prog_info ) /*HDR*/ /** - * @brief Retrieve and print some common device info + * @brief Retrieve and print some common device info. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] dev_name A device name string to be printed - * @param[out] p_dev Pointer to a device info structure to be read from the device + * @param[in] dev_name A device name string to be printed. + * @param[out] p_dev Pointer to a device info structure to be read from the device. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_dev ) { @@ -324,7 +439,7 @@ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_ if ( dev_name ) printf( "%s:\n", dev_name ); - // get information about the device + // Get information about the device. rc = mbg_get_device_info( dh, p_dev ); if ( mbg_cond_err_msg( rc, "mbg_get_device_info" ) ) @@ -342,27 +457,31 @@ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_ strcmp( _pcps_sernum( p_dev ), "N/A" ) ) printf( " %s", _pcps_sernum( p_dev ) ); - printf( " (FW " PCPS_FW_STR_FMT, - _pcps_fw_rev_num_major( _pcps_fw_rev_num( p_dev ) ), - _pcps_fw_rev_num_minor( _pcps_fw_rev_num( p_dev ) ) - ); - - if ( chk_sw_rev_name( &ri.sw_rev, 0 ) ) - printf( " \"%s\"", ri.sw_rev.name ); - - if ( _pcps_has_asic_version( p_dev ) ) + if ( mbg_rc_is_success( mbg_chk_dev_is_syn1588_type( dh ) ) ) + printf( " (Build %u", _pcps_fw_rev_num( p_dev ) ); + else { - PCI_ASIC_VERSION av; - int rc = mbg_get_asic_version( dh, &av ); + printf( " (FW " PCPS_FW_STR_FMT, + _pcps_fw_rev_num_major( _pcps_fw_rev_num( p_dev ) ), + _pcps_fw_rev_num_minor( _pcps_fw_rev_num( p_dev ) ) ); - if ( mbg_rc_is_success( rc ) ) + if ( chk_sw_rev_name( &ri.sw_rev, 0 ) ) + printf( " \"%s\"", ri.sw_rev.name ); + + if ( _pcps_has_asic_version( p_dev ) ) { - av = _convert_asic_version_number( av ); // TODO Do we need this? + PCI_ASIC_VERSION av; + int rc = mbg_get_asic_version( dh, &av ); - printf( ", ASIC " PCPS_ASIC_STR_FMT, - _pcps_asic_version_major( av ), - _pcps_asic_version_minor( av ) - ); + if ( mbg_rc_is_success( rc ) ) + { + av = _convert_asic_version_number( av ); // TODO Do we need this? + + printf( ", ASIC " PCPS_ASIC_STR_FMT, + _pcps_asic_version_major( av ), + _pcps_asic_version_minor( av ) + ); + } } } @@ -380,7 +499,7 @@ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_ irq_num = _pcps_irq_num( p_dev ); - if ( irq_num != -1 ) + if ( irq_num != PCPS_IRQ_NUM_UNDEFINED ) printf( ", irq %i", irq_num ); if ( _pcps_fw_has_20ms_bug( p_dev ) ) @@ -401,13 +520,13 @@ out: /*HDR*/ /** - * @brief Print device info and take some action on a specific device + * @brief Print device info and take some action on a specific device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] dev_name A device name string to be printed. * @param[in] fnc Pointer to a callback function that actually takes the action. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ int mbg_handle_device( MBG_DEV_HANDLE dh, const char *dev_name, MBG_DEV_HANDLER_FNC *fnc ) @@ -433,7 +552,7 @@ int mbg_handle_device( MBG_DEV_HANDLE dh, const char *dev_name, /*HDR*/ /** - * @brief Get the number of devices actually present + * @brief Get the number of devices actually present. * * Do a real search only when called for the first time. * @@ -463,16 +582,16 @@ int chk_get_num_devices( void ) * @param[out] p_dh Address of a device handle variable to be set on success. * @param[in] dev_param_str An optional device specification string. This can be: * - A device file name, if the operating system supports this. See ::MBG_DEV_FN. - * - A device model name like "GPS180PEX", eventually with the serial number + * - A device model name like "GPS180PEX", optionally with the serial number * appended after an underscore, as in "GPS180PEX_029511026220". * See ::MBG_DEV_NAME. - * - A device index number as string, e.g "0" or "3". - * - NULL, in which case @p dev_idx has to be a valid device index number. - * @param[in] dev_idx A device index number which is used if @p dev_param_str is NULL. + * - A device index number as string, e.g. "0" or "3". + * - @a NULL, in which case @p dev_idx has to be a valid device index number. + * @param[in] dev_idx A device index number which is used if @p dev_param_str is @a NULL. * @param[out] dev_name_buffer A string buffer to which a device name can be written, see ::MBG_DEV_FN. - * @param[in] dev_name_buffer_size The size of the @p dev_name_buffer buffer + * @param[in] dev_name_buffer_size The size of the @p dev_name_buffer buffer. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_open_device_by_param */ @@ -480,13 +599,13 @@ int mbg_open_device_by_param( MBG_DEV_HANDLE *p_dh, const char *dev_param_str, i char *dev_name_buffer, size_t dev_name_buffer_size ) { MBG_DEV_HANDLE dh = MBG_INVALID_DEV_HANDLE; - int devices_found; + int devices_found = chk_get_num_devices(); int rc = MBG_ERR_GENERIC; if ( dev_name_buffer == NULL || dev_name_buffer_size == 0 ) return MBG_ERR_INV_PARM; - dev_name_buffer[0] = 0; // Make string empty + dev_name_buffer[0] = 0; // Make string empty. if ( dev_param_str ) { @@ -495,21 +614,21 @@ int mbg_open_device_by_param( MBG_DEV_HANDLE *p_dh, const char *dev_param_str, i long l; #if MBG_TGT_HAS_DEV_FN_BASE - // Check if the device parameter represents a device file name - if ( strncmp( dev_param_str, mbg_dev_fn_base, strlen( mbg_dev_fn_base ) ) == 0 ) + // Check if the device parameter represents a Meinberg device file name. + if ( mbg_rc_is_success( mbg_chk_dev_fn_is_valid( dev_param_str ) ) ) { - snprintf_safe( dev_name_buffer, dev_name_buffer_size, "%s", dev_param_str ); + sn_cpy_str_safe( dev_name_buffer, dev_name_buffer_size, dev_param_str ); dh = mbg_open_device_by_dev_fn( dev_param_str ); goto has_tried_to_open; } - #endif + #endif // MBG_TGT_HAS_DEV_FN_BASE // Check if the device parameter string is an index number. endptr = NULL; l = strtol( dev_param_str, &endptr, 0 ); - // If endptr now points past the string then the + // If endptr now points past the string, the // whole string has been interpreted as number. if ( endptr == &dev_param_str[strlen( dev_param_str )] ) { @@ -529,7 +648,7 @@ int mbg_open_device_by_param( MBG_DEV_HANDLE *p_dh, const char *dev_param_str, i } - // Finally assume the device name is a model name, eventually + // Finally assume the device name is a model name, optionally // with serial number appended. snprintf_safe( dev_name_buffer, dev_name_buffer_size, "%s", dev_param_str ); dh = mbg_open_device_by_name( dev_param_str, MBG_MATCH_MODEL ); @@ -543,15 +662,14 @@ open_dev_with_idx: // Try to open the device with the index number which has been derived // from dev_param_str, or has been passed directly by the caller. // First check if the device index is in a valid range. - devices_found = chk_get_num_devices(); - if ( devices_found == 0 ) // no device found + if ( devices_found == 0 ) // No device found. return MBG_ERR_NO_DEV; - if ( dev_idx >= devices_found ) // device index exceeds max + if ( dev_idx >= devices_found ) // Device index exceeds max. return MBG_ERR_NO_DEV; - mbg_dev_fn_from_dev_idx( dev_name_buffer, (int) dev_name_buffer_size, dev_idx ); + mbg_dev_info_from_dev_idx( dev_name_buffer, (int) dev_name_buffer_size, dev_idx ); dh = mbg_open_device( dev_idx ); @@ -580,16 +698,16 @@ out: * @param[out] p_dh Address of a device handle variable to be set on success. * @param[in] dev_param_str An optional device specification string. This can be: * - A device file name, if the operating system supports this. See ::MBG_DEV_FN. - * - A device model name like "GPS180PEX", eventually with the serial number + * - A device model name like "GPS180PEX", optionally with the serial number * appended after an underscore, as in "GPS180PEX_029511026220". * See ::MBG_DEV_NAME. - * - A device index number as string, e.g "0" or "3". - * - NULL, in which case @p dev_idx has to be a valid device index number. - * @param[in] dev_idx A device index number which is used if @p dev_param_str is NULL. + * - A device index number as string, e.g. "0" or "3". + * - @a NULL, in which case @p dev_idx has to be a valid device index number. + * @param[in] dev_idx A device index number which is used if @p dev_param_str is @a NULL. * @param[out] dev_name_buffer A string buffer to which a device name can be written, see ::MBG_DEV_FN. - * @param[in] dev_name_buffer_size The size of the @p dev_name_buffer buffer + * @param[in] dev_name_buffer_size The size of the @p dev_name_buffer buffer. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_open_device_by_param */ @@ -604,12 +722,12 @@ int mbg_open_device_by_param_chk( MBG_DEV_HANDLE *p_dh, const char *dev_param_st int n = 0; n = snprintf_safe( msg, sizeof( msg ), "** Failed to open device" ); - if ( dev_name_buffer[0] ) // string not empty + if ( dev_name_buffer[0] ) // String not empty. n += snprintf_safe( &msg[n], sizeof( msg ) - n, " %s", dev_name_buffer ); else - if ( dev_param_str ) // parameter string has been specified + if ( dev_param_str ) // Parameter string has been specified. n += snprintf_safe( &msg[n], sizeof( msg ) - n, " %s", dev_param_str ); - else // device index number + else // Device index number. n += snprintf_safe( &msg[n], sizeof( msg ) - n, " %i", dev_idx ); n += snprintf_safe( &msg[n], sizeof( msg ) - n, ": %s", mbg_strerror( rc ) ); @@ -624,7 +742,7 @@ int mbg_open_device_by_param_chk( MBG_DEV_HANDLE *p_dh, const char *dev_param_st /*HDR*/ /** - * @brief Main action handler that can be called by utility programs + * @brief Main action handler that can be called by utility programs. * * This function checks the command line parameters passed to the program. * Those which have not been evaluated before are interpreted as device specifiers. @@ -636,21 +754,21 @@ int mbg_open_device_by_param_chk( MBG_DEV_HANDLE *p_dh, const char *dev_param_st * between several devices of the same type (see ::MBG_DEV_NAME), * or just an index number as required for the ::mbg_open_device call. * - * For each of the specified devices the callback function @p fnc is called to - * take some specific action on the device. + * For each of the specified devices, the callback function @p fnc is called + * to take some specific action on the device. * - * If no device has been specified in the argument list then ::mbg_find_devices - * is called to set up a device list, and depending on whether ::CHK_DEV_ALL_DEVICES - * is set in @p chk_dev_flags the callback function @p fnc is either called + * If no device has been specified in the argument list, ::mbg_find_devices is + * called to set up a device list, and depending on whether ::CHK_DEV_ALL_DEVICES + * is set in @p chk_dev_flags, the callback function @p fnc is either called * for every device from the list, or only for the first one. * - * @param[in] argc Number of parameters of the program argument list. - * @param[in] argv Array of program argument strings. - * @param[in] optind Number of the command line arguments that have already been handled. - * @param[in] fnc Pointer to a callback function that actually takes an action on each specified device. - * @param[in] chk_dev_flags Bit mask controlling the behavior of the function, see ::CHK_DEV_FLAGS + * @param[in] argc Number of parameters of the program argument list. + * @param[in] argv Array of program argument strings. + * @param[in] optind Number of the command line arguments that have already been handled. + * @param[in] fnc Pointer to a callback function that actually takes an action on each specified device. + * @param[in] chk_dev_flags Bit mask controlling the behavior of the function, see ::CHK_DEV_FLAGS. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ int mbg_handle_devices( int argc, char *argv[], int optind, MBG_DEV_HANDLER_FNC *fnc, int chk_dev_flags ) @@ -672,10 +790,10 @@ int mbg_handle_devices( int argc, char *argv[], int optind, dev_param_str = argv[i]; rc = mbg_open_device_by_param_chk( &dh, dev_param_str, 0, - tmp_dev_fn, sizeof( tmp_dev_fn ) ); + tmp_dev_fn.s, sizeof( tmp_dev_fn.s ) ); if ( mbg_rc_is_success( rc ) ) - rc = mbg_handle_device( dh, ( devices_specified > 1 ) ? tmp_dev_fn : NULL, fnc ); + rc = mbg_handle_device( dh, ( devices_specified > 1 ) ? tmp_dev_fn.s : NULL, fnc ); // Don't continue if one of the specified devices failed. if ( mbg_rc_is_error( rc ) ) @@ -690,7 +808,7 @@ int mbg_handle_devices( int argc, char *argv[], int optind, if ( chk_dev_flags & CHK_DEV_WITHOUT_DEV ) { - // TODO Check if this branch is useful + // TODO Check if this branch is useful. // We have been called without a device to be used. // This may be useful e.g. if we just want to print // some general usage information. @@ -710,13 +828,13 @@ int mbg_handle_devices( int argc, char *argv[], int optind, devices_found = chk_get_num_devices(); - if ( devices_found == 0 ) // no device found + if ( devices_found == 0 ) // No device found. { // Don't continue without any device, unless // explicitly requested to do so. if ( !( chk_dev_flags & CHK_DEV_WITHOUT_DEV ) ) { - printf( "No device found.\n" ); // TODO + mbg_print_no_device_found(); rc = MBG_ERR_NO_DEV; goto out; } @@ -733,13 +851,13 @@ int mbg_handle_devices( int argc, char *argv[], int optind, for ( i = 0; i < devices_found; i++ ) { - rc = mbg_open_device_by_param_chk( &dh, NULL, i, tmp_dev_fn, sizeof( tmp_dev_fn ) ); + rc = mbg_open_device_by_param_chk( &dh, NULL, i, tmp_dev_fn.s, sizeof( tmp_dev_fn.s ) ); if ( mbg_rc_is_success( rc ) ) - rc = mbg_handle_device( dh, ( devices_found > 1 ) ? tmp_dev_fn : NULL, fnc ); + rc = mbg_handle_device( dh, ( devices_found > 1 ) ? tmp_dev_fn.s : NULL, fnc ); - // If one of the unspecified devices failed we continue anyway - // and don't break here. + // If one of the unspecified devices failed, + // we continue anyway and don't break here. } @@ -752,23 +870,24 @@ out: /*HDR*/ /** - * @brief Print date and time from a ::PCPS_TIME structure to a string + * @brief Print date and time from a ::PCPS_TIME structure to a string. * * @param[out] s Address of a string buffer to be filled. * @param[in] max_len Size of the string buffer. * @param[in] p Pointer to a ::PCPS_TIME structure to be evaluated. * @param[in] verbose Increase verbosity of the output:<br> - * > 0: append UTC offset and status<br> - * > 1: append signal value + * > 0: append %UTC offset and status<br> + * > 1: append signal value. * - * @return The number of characters printed to the buffer. + * @return The number of characters written to the string buffer, + * except the terminating 0. */ int mbg_snprint_date_time( char *s, size_t max_len, const PCPS_TIME *p, int verbose ) { size_t n = 0; n += snprintf_safe( &s[n], max_len - n, "%04u-%02u-%02u %02u:%02u:%02u.%02u", - pcps_exp_year( p->year, mbg_exp_year_limit ), p->month, p->mday, + mbg_exp_year( p->year, mbg_exp_year_limit ), p->month, p->mday, p->hour, p->min, p->sec, p->sec100 ); if ( verbose > 0 ) @@ -786,7 +905,7 @@ int mbg_snprint_date_time( char *s, size_t max_len, const PCPS_TIME *p, int verb /*HDR*/ /** - * @brief Print date and time from a ::PCPS_TIME_STAMP structure to a string + * @brief Print date and time from a ::PCPS_TIME_STAMP structure to a string. * * @param[out] s Address of a string buffer to be filled. * @param[in] max_len Size of the string buffer. @@ -794,7 +913,8 @@ int mbg_snprint_date_time( char *s, size_t max_len, const PCPS_TIME *p, int verb * @param[in] utc_offs A local time offset added to the time stamp before converted to date and time. * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. * - * @return The number of characters printed to the buffer. + * @return The number of characters written to the string buffer, + * except the terminating 0. */ int mbg_snprint_hr_tstamp( char *s, size_t max_len, const PCPS_TIME_STAMP *p, long utc_offs, int show_raw ) @@ -836,9 +956,9 @@ int mbg_snprint_hr_tstamp( char *s, size_t max_len, const PCPS_TIME_STAMP *p, /*HDR*/ /** - * @brief Print date and time from a ::PCPS_HR_TIME structure to a string + * @brief Print date and time from a ::PCPS_HR_TIME structure to a string. * - * Converts the UTC timestamp first to local time according to + * Converts the %UTC timestamp first to local time according to * the ::PCPS_HR_TIME::utc_offs value. * * @param[out] s Address of a string buffer to be filled. @@ -846,7 +966,8 @@ int mbg_snprint_hr_tstamp( char *s, size_t max_len, const PCPS_TIME_STAMP *p, * @param[in] p Pointer to a ::PCPS_HR_TIME structure to be evaluated. * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. * - * @return The number of characters printed to the buffer. + * @return The number of characters written to the string buffer, + * except the terminating 0. */ int mbg_snprint_hr_time( char *s, size_t max_len, const PCPS_HR_TIME *p, int show_raw ) { @@ -856,7 +977,7 @@ int mbg_snprint_hr_time( char *s, size_t max_len, const PCPS_HR_TIME *p, int sho const char *time_scale_name; const char *cp; - // If the local time offset is not 0 then add this to the time stamp + // If the local time offset is not 0, add this to the time stamp // and set up a string telling the offset. if ( p->utc_offs ) { @@ -864,21 +985,21 @@ int mbg_snprint_hr_time( char *s, size_t max_len, const PCPS_HR_TIME *p, int sho cp = ws; } else - cp = ""; // no local time offset + cp = ""; // No local time offset. // Convert the local time stamp to calendar date and time. n = mbg_snprint_hr_tstamp( s, max_len, &ts, p->utc_offs, show_raw ); - // By default the time stamp represents UTC plus an optional local time offset. + // By default, the time stamp represents UTC plus an optional local time offset. time_scale_name = "UTC"; - // However, some cards may be configured to output TAI or GPS time. + // However, some device may have been configured to output TAI or GPS time. if ( p->status & PCPS_SCALE_TAI ) - time_scale_name = "TAI"; // time stamp represents TAI + time_scale_name = "TAI"; // Time stamp represents TAI. else if ( p->status & PCPS_SCALE_GPS ) - time_scale_name = "GPS"; // time stamp represents GPS system time + time_scale_name = "GPS"; // Time stamp represents GPS system time. n += snprintf_safe( &s[n], max_len - n, " %s%s", time_scale_name, cp ); @@ -890,22 +1011,22 @@ int mbg_snprint_hr_time( char *s, size_t max_len, const PCPS_HR_TIME *p, int sho /*HDR*/ /** - * @brief Print date and time from a ::PCPS_TIME_STAMP structure + * @brief Print date and time from a ::PCPS_TIME_STAMP structure. * * First the HR timestamp passed by parameter @p p_ts is printed. * - * If the parameter @p p_prv_ts is not NULL then it should specify + * If the parameter @p p_prv_ts is not @a NULL, it should specify * an earlier timestamp, and the elapsed time since @p p_ts * is appended. * * Finally the latency value is printed in microseconds, unless * parameter @p no_latency is != 0. * - * @param[in] p_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. - * @param[in] hns_latency A latency number in hectonanoseconds, i.e. 100 ns units. - * @param[in] p_prv_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated, may be NULL - * @param[in] no_latency A flag indicating if printing the latency should be suppressed. - * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. + * @param[in] p_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. + * @param[in] hns_latency A latency number in hectonanoseconds, i.e. 100 ns units. + * @param[in] p_prv_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated, may be @a NULL. + * @param[in] no_latency A flag indicating if printing the latency should be suppressed. + * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. * * @see ::mbg_print_hr_time */ @@ -918,7 +1039,7 @@ void mbg_print_hr_timestamp( PCPS_TIME_STAMP *p_ts, int32_t hns_latency, PCPS_TI printf( "HR time %s", ws ); if ( p_prv_ts ) - printf( " (%+.1f us)", delta_timestamps( p_ts, p_prv_ts ) ); + printf( " (%+.1f us)", delta_timestamp_us( p_ts, p_prv_ts ) ); if ( !no_latency ) printf( ", latency: %.1f us", ( (double) hns_latency ) / 10 ); @@ -931,25 +1052,25 @@ void mbg_print_hr_timestamp( PCPS_TIME_STAMP *p_ts, int32_t hns_latency, PCPS_TI /*HDR*/ /** - * @brief Print date and time from a ::PCPS_HR_TIME structure + * @brief Print date and time from a ::PCPS_HR_TIME structure. * * First the HR timestamp passed by parameter @p p_ht is printed. * - * If the parameter @p p_prv_ts is not NULL then it should specify + * If the parameter @p p_prv_ts is not @a NULL, it should specify * an earlier timestamp, and the elapsed time since @p p_ht * is appended. * * Next the latency value is printed in microseconds, unless * parameter @p no_latency is != 0. * - * @param[in] p_ht Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. - * @param[in] hns_latency A latency number in hectonanoseconds, i.e. 100 ns units. - * @param[in] p_prv_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated, may be NULL - * @param[in] no_latency A flag indicating if printing the latency should be suppressed. - * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. - * @param[in] verbose Increase verbosity of the output:<br> + * @param[in] p_ht Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. + * @param[in] hns_latency A latency number in hectonanoseconds, i.e. 100 ns units. + * @param[in] p_prv_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated, may be @a NULL. + * @param[in] no_latency A flag indicating if printing the latency should be suppressed. + * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. + * @param[in] verbose Increase verbosity of the output:<br> * > 0: append status code<br> - * > 1: append signal value + * > 1: append signal value. * * @see ::mbg_print_hr_timestamp */ @@ -962,10 +1083,7 @@ void mbg_print_hr_time( PCPS_HR_TIME *p_ht, int32_t hns_latency, PCPS_TIME_STAMP printf( "HR time %s", ws ); if ( p_prv_ts ) - printf( " (%+.1f us)", delta_timestamps( &p_ht->tstamp, p_prv_ts ) ); - - if ( !no_latency ) - printf( ", latency: %.1f us", ( (double) hns_latency ) / 10 ); + printf( " (%+.1f us)", delta_timestamp_us( &p_ht->tstamp, p_prv_ts ) ); if ( verbose > 0 ) printf( ", st: 0x%04lX", (ulong) p_ht->status ); @@ -973,6 +1091,9 @@ void mbg_print_hr_time( PCPS_HR_TIME *p_ht, int32_t hns_latency, PCPS_TIME_STAMP if ( verbose > 1 ) printf( ", sig: %i", p_ht->signal ); + if ( !no_latency ) + printf( ", latency: %.1f us", ( (double) hns_latency ) / 10 ); + puts( "" ); } // mbg_print_hr_time @@ -981,38 +1102,31 @@ void mbg_print_hr_time( PCPS_HR_TIME *p_ht, int32_t hns_latency, PCPS_TIME_STAMP /*HDR*/ /** - * @brief Retrieve and print PZF correlation info for a device which supports this + * @brief Print PZF correlation info for a device which supports this. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] show_corr_step A flag indicating if correlation step indicators are to be appended + * @param[in] p_ci Pointer to a ::CORR_INFO structure that has been read before. + * @param[in] show_corr_step A flag indicating if correlation step indicators are to be appended. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ -int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, int show_corr_step ) +int mbg_show_pzf_corr_info( const CORR_INFO *p_ci, int show_corr_step ) { - CORR_INFO ci; char ws[80]; const char *cp; - int rc = mbg_get_corr_info( dh, &ci ); - - if ( mbg_cond_err_msg( rc, "mbg_get_corr_info" ) ) - return rc; - - - if ( ci.status < N_PZF_CORR_STATE ) - cp = pzf_corr_state_name[ci.status]; + if ( p_ci->status < N_PZF_CORR_STATE ) + cp = pzf_corr_state_name[p_ci->status]; else { - snprintf_safe( ws, sizeof( ws ), "unknown status code: 0x%02X", ci.status ); + snprintf_safe( ws, sizeof( ws ), "unknown status code: 0x%02X", p_ci->status ); cp = ws; } - printf( "%s, PZF correlation: %u%%", cp, ci.val ); + printf( "%s, PZF correlation: %u%%", cp, p_ci->val ); if ( show_corr_step ) - if ( ci.corr_dir != ' ' ) - printf( " Shift: %c", ci.corr_dir ); + if ( p_ci->corr_dir != ' ' ) + printf( " Shift: %c", p_ci->corr_dir ); return MBG_SUCCESS; @@ -1022,12 +1136,12 @@ int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, int show_corr_step ) /*HDR*/ /** - * @brief Retrieve a ::MBG_GNSS_MODE_INFO structure from a device + * @brief Retrieve a ::MBG_GNSS_MODE_INFO structure from a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::MBG_GNSS_MODE_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ int mbg_get_gps_gnss_mode_info_chk( MBG_DEV_HANDLE dh, MBG_GNSS_MODE_INFO *p ) { diff --git a/mbglib/common/toolutil.h b/mbglib/common/toolutil.h index cb44f6d..b520949 100644 --- a/mbglib/common/toolutil.h +++ b/mbglib/common/toolutil.h @@ -1,16 +1,38 @@ /************************************************************************** * - * $Id: toolutil.h 1.8 2019/03/13 09:44:57Z martin REL_M $ + * $Id: toolutil.h 1.18 2021/11/08 20:26:20Z martin.burnicki REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * - * Description: - * Definitions and prototypes for toolutil.c. + * Definitions and prototypes for toolutil.c. * * ----------------------------------------------------------------------- * $Log: toolutil.h $ - * Revision 1.8 2019/03/13 09:44:57Z martin + * Revision 1.18 2021/11/08 20:26:20Z martin.burnicki + * Updated comment of a function prototype. + * Revision 1.17 2021/05/03 16:14:57 martin + * Provide default definition for SUPP_SERIAL. + * Revision 1.16 2021/04/29 14:46:45 martin + * Moved an inline function to mbgutil.h. + * Revision 1.15 2021/04/29 13:08:22 martin + * Moved common definitions for year limit to mbgutil.h. + * Revision 1.14 2021/04/12 22:03:47 martin + * Basic support for serial devices. + * Changed type of mbg_exp_year_limit to int. + * Revision 1.13 2021/03/22 11:25:11 martin + * Updated a bunch of comments. + * Revision 1.12 2021/03/12 10:51:33 martin + * Updated some doxygen comments. + * Revision 1.11 2020/11/04 16:59:12 martin + * Moved inline function delta_timestamps() to the header file + * and renamed it to delta_timestamp_us() because the returned + * value is in microseconds. + * Revision 1.10 2020/10/20 10:46:05 martin + * Updated function prototypes. + * Revision 1.9 2020/02/27 13:58:53 martin + * Updated function prototypes. + * Revision 1.8 2019/03/13 09:44:57 martin * Moved predefined program exit codes to mbgerror.h. * Revision 1.7 2018/12/14 13:14:52 martin * Updated function prototypes. @@ -43,6 +65,11 @@ #define _TOOLUTIL_H +#if !defined( SUPP_SERIAL ) + #define SUPP_SERIAL 0 +#endif + + /* Other headers to be included */ #include <mbgdevio.h> @@ -86,8 +113,24 @@ extern "C" { enum CHK_DEV_FLAGS { - CHK_DEV_ALL_DEVICES = 0x0001, ///< call callback for all devices - CHK_DEV_WITHOUT_DEV = 0x0002 ///< call callback once if no device found + CHK_DEV_ALL_DEVICES = 0x0001, ///< Call callback for all devices. + CHK_DEV_WITHOUT_DEV = 0x0002 ///< Call callback once if no device found. +}; + + + +/** + * @brief Masks affecting device options to be printed. + * + * This refers to example device names specified on the + * command line. Used with ::mbg_print_device_options. + * + * @see ::mbg_print_device_options + */ +enum DEV_OPT_PRINT_MASKS +{ + DEV_OPT_PRINT_BUS_LEVEL = 0x0001, + DEV_OPT_PRINT_SERIAL = 0x0002 }; @@ -110,18 +153,7 @@ enum CHK_DEV_FLAGS #endif -#if !defined( MBG_EXP_YEAR_LIMIT ) - #define MBG_EXP_YEAR_LIMIT 1980 -#endif - - -_ext uint16_t mbg_exp_year_limit -#ifdef _DO_INIT - = MBG_EXP_YEAR_LIMIT -#endif -; - -_ext int must_print_usage; +_ext bool must_print_usage; _ext const char str_empty[] #ifdef _DO_INIT @@ -139,7 +171,7 @@ _ext const char *pzf_corr_state_name[N_PZF_CORR_STATE] /** - * @brief The type of functions to called to handle a device in a specific way. + * @brief The type of functions to be called to handle a device in a specific way. */ typedef int MBG_DEV_HANDLER_FNC( MBG_DEV_HANDLE, const PCPS_DEV *); @@ -151,55 +183,82 @@ typedef int MBG_DEV_HANDLER_FNC( MBG_DEV_HANDLE, const PCPS_DEV *); /* by MAKEHDR, do not remove the comments. */ /** - * @brief Print the program version to a string buffer + * @brief Print the program version to a string buffer. * - * @param[out] s Address of a string buffer to be filled. - * @param[in] max_len Size of the string buffer. + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. * - * @return The number of characters printed to the buffer. + * @return The number of characters written to the string buffer, + * except the terminating 0. */ int mbg_program_version_str( char *s, size_t max_len ) ; /** - * @brief Print some program info to a string buffer + * @brief Print some program info to a string buffer. * - * @param[out] s Address of a string buffer to be filled. - * @param[in] max_len Size of the string buffer. - * @param[in] pname The program name. - * @param[in] first_year First copyright year. - * @param[in] last_year Last copyright year. + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. + * @param[in] pname The program name. + * @param[in] first_year First copyright year. + * @param[in] last_year Last copyright year. * - * @return The number of characters printed to the buffer. + * @return The number of characters written to the string buffer, + * except the terminating 0. */ int mbg_program_info_str( char *s, size_t max_len, const char *pname, int first_year, int last_year ) ; /** - * @brief Print program info to console + * @brief Print program info to console. * - * @param[in] pname The program name. - * @param[in] first_year First copyright year. - * @param[in] last_year Last copyright year. + * @param[in] pname The program name. + * @param[in] first_year First copyright year. + * @param[in] last_year Last copyright year. */ void mbg_print_program_info( const char *pname, int first_year, int last_year ) ; /** - * @brief Print usage intro to console + * @brief Check if the program runs with admin rights. + * + * @return @a true if runs with admin rights, else @a false. + */ + bool mbg_has_admin_rights( void ) ; + + /** + * @brief Print a warning if program runs without admin rights. * - * @param[in] pname The program name. - * @param[in] info An optional additional info string, may be NULL. + * Yet, this is only relevant for the detection of SYN1588 devices. + */ + void mbg_chk_print_no_admin_rights( void ) ; + + /** + * @brief Print a warning if no device has been found. + * + * If SYN1588 support is enabled, also possibly print + * a warning if running without admin rights, because + * on some systems, SYN1588 devices may not be detected + * without admin rights. + */ + void mbg_print_no_device_found( void ) ; + + /** + * @brief Print usage intro to console. + * + * @param[in] pname The program name. + * @param[in] info An optional additional info string, may be @a NULL. */ void mbg_print_usage_intro( const char *pname, const char *info ) ; /** - * @brief Print info on a single program option / argument + * @brief Print info on a single program option / argument. * - * @param[in] opt_name The option name, optional, may be NULL. - * @param[in] opt_info The option info, optional, may be NULL. + * @param[in] opt_name The option name, optional, may be @a NULL. + * @param[in] opt_info_fmt The option info format string, optional, may be @a NULL. + * @param[in] ... Variable argument list according to the @p fmt format string. */ - void mbg_print_opt_info( const char *opt_name, const char *opt_info ) ; + __attribute__( ( format( printf, 2, 3 ) ) ) void mbg_print_opt_info( const char *opt_name, const char *opt_info_fmt, ... ) ; /** - * @brief Print info on common program help arguments + * @brief Print info on common program help arguments. * * Lists program parameters causing printing * of help / usage information. @@ -207,42 +266,48 @@ typedef int MBG_DEV_HANDLER_FNC( MBG_DEV_HANDLE, const PCPS_DEV *); void mbg_print_help_options( void ) ; /** - * @brief Print common info on how to specify devices on the command line + * @brief Print common info on how to specify devices on the command line. + * + * @param[in] mask Bit mask to control for which kind of devices + * information shall be displayed. + * See ::DEV_OPT_PRINT_MASKS. + * + * @see ::DEV_OPT_PRINT_MASKS */ - void mbg_print_device_options( void ) ; + void mbg_print_device_options( int mask ) ; /** - * @brief Print program info and default usage information + * @brief Print program info and default usage information. * - * @param[in] pname The program name. - * @param[in] prog_info An optional additional info string, may be NULL. + * @param[in] pname The program name. + * @param[in] prog_info An optional additional info string, may be @a NULL. */ void mbg_print_default_usage( const char *pname, const char *prog_info ) ; /** - * @brief Retrieve and print some common device info + * @brief Retrieve and print some common device info. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] dev_name A device name string to be printed - * @param[out] p_dev Pointer to a device info structure to be read from the device + * @param[in] dev_name A device name string to be printed. + * @param[out] p_dev Pointer to a device info structure to be read from the device. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_dev ) ; /** - * @brief Print device info and take some action on a specific device + * @brief Print device info and take some action on a specific device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] dev_name A device name string to be printed. * @param[in] fnc Pointer to a callback function that actually takes the action. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ int mbg_handle_device( MBG_DEV_HANDLE dh, const char *dev_name, MBG_DEV_HANDLER_FNC *fnc ) ; /** - * @brief Get the number of devices actually present + * @brief Get the number of devices actually present. * * Do a real search only when called for the first time. * @@ -256,16 +321,16 @@ typedef int MBG_DEV_HANDLER_FNC( MBG_DEV_HANDLE, const PCPS_DEV *); * @param[out] p_dh Address of a device handle variable to be set on success. * @param[in] dev_param_str An optional device specification string. This can be: * - A device file name, if the operating system supports this. See ::MBG_DEV_FN. - * - A device model name like "GPS180PEX", eventually with the serial number + * - A device model name like "GPS180PEX", optionally with the serial number * appended after an underscore, as in "GPS180PEX_029511026220". * See ::MBG_DEV_NAME. - * - A device index number as string, e.g "0" or "3". - * - NULL, in which case @p dev_idx has to be a valid device index number. - * @param[in] dev_idx A device index number which is used if @p dev_param_str is NULL. + * - A device index number as string, e.g. "0" or "3". + * - @a NULL, in which case @p dev_idx has to be a valid device index number. + * @param[in] dev_idx A device index number which is used if @p dev_param_str is @a NULL. * @param[out] dev_name_buffer A string buffer to which a device name can be written, see ::MBG_DEV_FN. - * @param[in] dev_name_buffer_size The size of the @p dev_name_buffer buffer + * @param[in] dev_name_buffer_size The size of the @p dev_name_buffer buffer. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_open_device_by_param */ @@ -280,23 +345,23 @@ typedef int MBG_DEV_HANDLER_FNC( MBG_DEV_HANDLE, const PCPS_DEV *); * @param[out] p_dh Address of a device handle variable to be set on success. * @param[in] dev_param_str An optional device specification string. This can be: * - A device file name, if the operating system supports this. See ::MBG_DEV_FN. - * - A device model name like "GPS180PEX", eventually with the serial number + * - A device model name like "GPS180PEX", optionally with the serial number * appended after an underscore, as in "GPS180PEX_029511026220". * See ::MBG_DEV_NAME. - * - A device index number as string, e.g "0" or "3". - * - NULL, in which case @p dev_idx has to be a valid device index number. - * @param[in] dev_idx A device index number which is used if @p dev_param_str is NULL. + * - A device index number as string, e.g. "0" or "3". + * - @a NULL, in which case @p dev_idx has to be a valid device index number. + * @param[in] dev_idx A device index number which is used if @p dev_param_str is @a NULL. * @param[out] dev_name_buffer A string buffer to which a device name can be written, see ::MBG_DEV_FN. - * @param[in] dev_name_buffer_size The size of the @p dev_name_buffer buffer + * @param[in] dev_name_buffer_size The size of the @p dev_name_buffer buffer. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. * * @see ::mbg_open_device_by_param */ int mbg_open_device_by_param_chk( MBG_DEV_HANDLE *p_dh, const char *dev_param_str, int dev_idx, char *dev_name_buffer, size_t dev_name_buffer_size ) ; /** - * @brief Main action handler that can be called by utility programs + * @brief Main action handler that can be called by utility programs. * * This function checks the command line parameters passed to the program. * Those which have not been evaluated before are interpreted as device specifiers. @@ -308,40 +373,41 @@ typedef int MBG_DEV_HANDLER_FNC( MBG_DEV_HANDLE, const PCPS_DEV *); * between several devices of the same type (see ::MBG_DEV_NAME), * or just an index number as required for the ::mbg_open_device call. * - * For each of the specified devices the callback function @p fnc is called to - * take some specific action on the device. + * For each of the specified devices, the callback function @p fnc is called + * to take some specific action on the device. * - * If no device has been specified in the argument list then ::mbg_find_devices - * is called to set up a device list, and depending on whether ::CHK_DEV_ALL_DEVICES - * is set in @p chk_dev_flags the callback function @p fnc is either called + * If no device has been specified in the argument list, ::mbg_find_devices is + * called to set up a device list, and depending on whether ::CHK_DEV_ALL_DEVICES + * is set in @p chk_dev_flags, the callback function @p fnc is either called * for every device from the list, or only for the first one. * - * @param[in] argc Number of parameters of the program argument list. - * @param[in] argv Array of program argument strings. - * @param[in] optind Number of the command line arguments that have already been handled. - * @param[in] fnc Pointer to a callback function that actually takes an action on each specified device. - * @param[in] chk_dev_flags Bit mask controlling the behavior of the function, see ::CHK_DEV_FLAGS + * @param[in] argc Number of parameters of the program argument list. + * @param[in] argv Array of program argument strings. + * @param[in] optind Number of the command line arguments that have already been handled. + * @param[in] fnc Pointer to a callback function that actually takes an action on each specified device. + * @param[in] chk_dev_flags Bit mask controlling the behavior of the function, see ::CHK_DEV_FLAGS. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ int mbg_handle_devices( int argc, char *argv[], int optind, MBG_DEV_HANDLER_FNC *fnc, int chk_dev_flags ) ; /** - * @brief Print date and time from a ::PCPS_TIME structure to a string + * @brief Print date and time from a ::PCPS_TIME structure to a string. * * @param[out] s Address of a string buffer to be filled. * @param[in] max_len Size of the string buffer. * @param[in] p Pointer to a ::PCPS_TIME structure to be evaluated. * @param[in] verbose Increase verbosity of the output:<br> - * > 0: append UTC offset and status<br> - * > 1: append signal value + * > 0: append %UTC offset and status<br> + * > 1: append signal value. * - * @return The number of characters printed to the buffer. + * @return The number of characters written to the string buffer, + * except the terminating 0. */ int mbg_snprint_date_time( char *s, size_t max_len, const PCPS_TIME *p, int verbose ) ; /** - * @brief Print date and time from a ::PCPS_TIME_STAMP structure to a string + * @brief Print date and time from a ::PCPS_TIME_STAMP structure to a string. * * @param[out] s Address of a string buffer to be filled. * @param[in] max_len Size of the string buffer. @@ -349,14 +415,15 @@ typedef int MBG_DEV_HANDLER_FNC( MBG_DEV_HANDLE, const PCPS_DEV *); * @param[in] utc_offs A local time offset added to the time stamp before converted to date and time. * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. * - * @return The number of characters printed to the buffer. + * @return The number of characters written to the string buffer, + * except the terminating 0. */ int mbg_snprint_hr_tstamp( char *s, size_t max_len, const PCPS_TIME_STAMP *p, long utc_offs, int show_raw ) ; /** - * @brief Print date and time from a ::PCPS_HR_TIME structure to a string + * @brief Print date and time from a ::PCPS_HR_TIME structure to a string. * - * Converts the UTC timestamp first to local time according to + * Converts the %UTC timestamp first to local time according to * the ::PCPS_HR_TIME::utc_offs value. * * @param[out] s Address of a string buffer to be filled. @@ -364,74 +431,75 @@ typedef int MBG_DEV_HANDLER_FNC( MBG_DEV_HANDLE, const PCPS_DEV *); * @param[in] p Pointer to a ::PCPS_HR_TIME structure to be evaluated. * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. * - * @return The number of characters printed to the buffer. + * @return The number of characters written to the string buffer, + * except the terminating 0. */ int mbg_snprint_hr_time( char *s, size_t max_len, const PCPS_HR_TIME *p, int show_raw ) ; /** - * @brief Print date and time from a ::PCPS_TIME_STAMP structure + * @brief Print date and time from a ::PCPS_TIME_STAMP structure. * * First the HR timestamp passed by parameter @p p_ts is printed. * - * If the parameter @p p_prv_ts is not NULL then it should specify + * If the parameter @p p_prv_ts is not @a NULL, it should specify * an earlier timestamp, and the elapsed time since @p p_ts * is appended. * * Finally the latency value is printed in microseconds, unless * parameter @p no_latency is != 0. * - * @param[in] p_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. - * @param[in] hns_latency A latency number in hectonanoseconds, i.e. 100 ns units. - * @param[in] p_prv_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated, may be NULL - * @param[in] no_latency A flag indicating if printing the latency should be suppressed. - * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. + * @param[in] p_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. + * @param[in] hns_latency A latency number in hectonanoseconds, i.e. 100 ns units. + * @param[in] p_prv_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated, may be @a NULL. + * @param[in] no_latency A flag indicating if printing the latency should be suppressed. + * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. * * @see ::mbg_print_hr_time */ void mbg_print_hr_timestamp( PCPS_TIME_STAMP *p_ts, int32_t hns_latency, PCPS_TIME_STAMP *p_prv_ts, int no_latency, int show_raw ) ; /** - * @brief Print date and time from a ::PCPS_HR_TIME structure + * @brief Print date and time from a ::PCPS_HR_TIME structure. * * First the HR timestamp passed by parameter @p p_ht is printed. * - * If the parameter @p p_prv_ts is not NULL then it should specify + * If the parameter @p p_prv_ts is not @a NULL, it should specify * an earlier timestamp, and the elapsed time since @p p_ht * is appended. * * Next the latency value is printed in microseconds, unless * parameter @p no_latency is != 0. * - * @param[in] p_ht Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. - * @param[in] hns_latency A latency number in hectonanoseconds, i.e. 100 ns units. - * @param[in] p_prv_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated, may be NULL - * @param[in] no_latency A flag indicating if printing the latency should be suppressed. - * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. - * @param[in] verbose Increase verbosity of the output:<br> + * @param[in] p_ht Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. + * @param[in] hns_latency A latency number in hectonanoseconds, i.e. 100 ns units. + * @param[in] p_prv_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated, may be @a NULL. + * @param[in] no_latency A flag indicating if printing the latency should be suppressed. + * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. + * @param[in] verbose Increase verbosity of the output:<br> * > 0: append status code<br> - * > 1: append signal value + * > 1: append signal value. * * @see ::mbg_print_hr_timestamp */ void mbg_print_hr_time( PCPS_HR_TIME *p_ht, int32_t hns_latency, PCPS_TIME_STAMP *p_prv_ts, int no_latency, int show_raw, int verbose ) ; /** - * @brief Retrieve and print PZF correlation info for a device which supports this + * @brief Print PZF correlation info for a device which supports this. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] show_corr_step A flag indicating if correlation step indicators are to be appended + * @param[in] p_ci Pointer to a ::CORR_INFO structure that has been read before. + * @param[in] show_corr_step A flag indicating if correlation step indicators are to be appended. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ - int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, int show_corr_step ) ; + int mbg_show_pzf_corr_info( const CORR_INFO *p_ci, int show_corr_step ) ; /** - * @brief Retrieve a ::MBG_GNSS_MODE_INFO structure from a device + * @brief Retrieve a ::MBG_GNSS_MODE_INFO structure from a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::MBG_GNSS_MODE_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ int mbg_get_gps_gnss_mode_info_chk( MBG_DEV_HANDLE dh, MBG_GNSS_MODE_INFO *p ) ; diff --git a/mbglib/common/usbdefs.h b/mbglib/common/usbdefs.h index ce88cf8..3a1655c 100644 --- a/mbglib/common/usbdefs.h +++ b/mbglib/common/usbdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: usbdefs.h 1.41 2019/03/08 10:51:15Z martin REL_M $ + * $Id: usbdefs.h 1.58 2021/10/14 06:25:53Z isa.wegmann REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,42 @@ * * ----------------------------------------------------------------------- * $Log: usbdefs.h $ - * Revision 1.41 2019/03/08 10:51:15Z martin + * Revision 1.58 2021/10/14 06:25:53Z isa.wegmann + * Add USB Device GPS182 + * Revision 1.57 2021/09/02 12:55:48Z torben.mueller + * added VMX180 model code and name + * Revision 1.56 2021/08/31 10:52:41Z paul.kretz + * added VSG181H model code and name + * Revision 1.55 2021/07/27 11:50:44Z gregoire.diehl + * Fix wrong usb device class for RCG181 + * Revision 1.54 2021/07/26 08:48:10Z isa.wegmann + * Add model GNS191 + * Revision 1.53 2021/06/28 08:28:08Z isa.wegmann + * Add RCG181 + * Revision 1.52 2021/05/07 09:38:43Z isa.wegmann + * Add Model GNS190_UC + * Revision 1.51 2021/05/03 11:29:19Z isa.wegmann + * add Device name for PMU190 + * Revision 1.50 2021/03/16 12:21:42Z martin + * Updated some comments. + * Revision 1.49 2021/01/04 11:47:47 paul.kretz + * Added definitions for SCG181 + * Revision 1.48 2020/07/01 08:28:15Z martin + * Added definitions for GPS190 and GNS190. + * Revision 1.47 2020/03/17 16:45:17 martin + * Added models BPE2XXX, BPE2352, BPE8XXX, BPE6042. + * Added missing device name for GNS181_UC. + * Revision 1.46 2020/03/03 07:21:16 andre.hartmann + * Added definitions for VSG181. + * Revision 1.45 2019/11/15 11:39:21Z philipp + * Added WiseChip OLED Display USB descriptor. + * Revision 1.44 2019/08/07 08:14:14 daniel + * Added support for GNS181_UC. + * Revision 1.43 2019/07/31 13:55:56 martin + * Added support for FCU200. + * Revision 1.42 2019/06/19 08:41:19 martin + * Added support for RSC_02. + * Revision 1.41 2019/03/08 10:51:15 martin * Added support for GNM181. * Renamed class MBG_USB_CLASS_GRC to MBG_USB_CLASS_GNS. * Revision 1.40 2019/01/14 08:37:45 martin @@ -164,7 +199,7 @@ enum MBG_USB_CLASS_CODES MBG_USB_CLASS_SCG, ///< Studio Clock Generator MBG_USB_CLASS_SDI, ///< SDI Input card for IMS MBG_USB_CLASS_FDM, ///< Frequency Deviation Monitor - MBG_USB_CLASS_NIC, ///< ASIX AX88179 Network interface chips on LNE, modified by Meinberg (this *must* be 0x17) + MBG_USB_CLASS_NIC, ///< ASIX AX88179 Network interface chips on LNE, modified by Meinberg (this ***must*** be 0x17) MBG_USB_CLASS_MDU, ///< Modular Distribution Unit MBG_USB_CLASS_SPT, ///< Single Path Through @@ -184,6 +219,9 @@ enum MBG_USB_CLASS_CODES MBG_USB_CLASS_FCM, ///< Fake Clock Module MBG_USB_CLASS_PIO, ///< Programmable Input/Output Module MBG_USB_CLASS_VSI, ///< Video Sync Interface + MBG_USB_CLASS_WSI, ///< WiseChip Semiconductor + MBG_USB_CLASS_RCG, ///< Radio Carrier Generator + MBG_USB_CLASS_VMX, ///< Video Matrix N_MBG_USB_CLASS ///< number of known Meinberg USB device class codes }; @@ -202,7 +240,7 @@ enum MBG_USB_CLASS_CODES * @anchor MBG_USB_DEVICE_IDS @{ */ -// If new devices are defined here then appropriate definitions should also +// If new devices are defined here, appropriate definitions should also // be added to MBG_USB_DEVICE_NAMES and DEFAULT_MBG_USB_DEVICE_NAMES. #define USB_DEV_CPC_01 ( ( MBG_USB_CLASS_CPC << 8 ) | 0x01 ) @@ -232,11 +270,14 @@ enum MBG_USB_CLASS_CODES #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_FCU_01 ( ( MBG_USB_CLASS_FCU << 8 ) | 0x01 ) // Fan (and power supply) Control Unit, doesn't support FCU API. +#define USB_DEV_FCU200 ( ( MBG_USB_CLASS_FCU << 8 ) | 0x02 ) // Fan (and power supply) Control Unit, supports FCU API. #define USB_DEV_CPE_01 ( ( MBG_USB_CLASS_CPE << 8 ) | 0x01 ) #define USB_DEV_GPS180 ( ( MBG_USB_CLASS_GPS << 8 ) | 0x01 ) +#define USB_DEV_GPS190 ( ( MBG_USB_CLASS_GPS << 8 ) | 0x02 ) +#define USB_DEV_GPS182 ( ( MBG_USB_CLASS_GPS << 8 ) | 0x03 ) #define USB_DEV_LNO180 ( ( MBG_USB_CLASS_LNO << 8 ) | 0x01 ) @@ -248,10 +289,15 @@ enum MBG_USB_CLASS_CODES #define USB_DEV_MRI_01 ( ( MBG_USB_CLASS_MRI << 8 ) | 0x01 ) -#define USB_DEV_BPE_01 ( ( MBG_USB_CLASS_BPE << 8 ) | 0x01 ) // BPE with ATMEL M3 -#define USB_DEV_BPE_STM ( ( MBG_USB_CLASS_BPE << 8 ) | 0x02 ) // BPE with STM M0 +#define USB_DEV_BPE_01 ( ( MBG_USB_CLASS_BPE << 8 ) | 0x01 ) // Generic BPE with ATMEL M3 +#define USB_DEV_BPE_STM ( ( MBG_USB_CLASS_BPE << 8 ) | 0x02 ) // Generic BPE with STM M0 +#define USB_DEV_BPE2XXX ( ( MBG_USB_CLASS_BPE << 8 ) | 0x03 ) // Formerly BPE, port extender via jumper field +#define USB_DEV_BPE2352 ( ( MBG_USB_CLASS_BPE << 8 ) | 0x04 ) // Formerly BPE_STM, time code AM and DCLS, plus 1 relay output +#define USB_DEV_BPE8XXX ( ( MBG_USB_CLASS_BPE << 8 ) | 0x05 ) // Formerly BPE, port extender via multiplexer +#define USB_DEV_BPE6042 ( ( MBG_USB_CLASS_BPE << 8 ) | 0x06 ) // Formerly BPE, isolated outputs via multiplexer -#define USB_DEV_RSC_01 ( ( MBG_USB_CLASS_RSC << 8 ) | 0x01 ) +#define USB_DEV_RSC_01 ( ( MBG_USB_CLASS_RSC << 8 ) | 0x01 ) // RSC used with M1000 / M3000 / IMS +#define USB_DEV_RSC_02 ( ( MBG_USB_CLASS_RSC << 8 ) | 0x02 ) // RSC used with M2000 #define USB_DEV_SPT_01 ( ( MBG_USB_CLASS_SPT << 8 ) | 0x01 ) @@ -261,11 +307,13 @@ enum MBG_USB_CLASS_CODES #define USB_DEV_LAN_CPU_SERIAL ( ( MBG_USB_CLASS_SERIAL << 8 ) | 0x01 ) #define USB_DEV_SCG_01 ( ( MBG_USB_CLASS_SCG << 8 ) | 0x01 ) +#define USB_DEV_SCG181 ( ( MBG_USB_CLASS_SCG << 8 ) | 0x02 ) #define USB_DEV_SDI_01 ( ( MBG_USB_CLASS_SDI << 8 ) | 0x01 ) #define USB_DEV_FDM180 ( ( MBG_USB_CLASS_FDM << 8 ) | 0x01 ) ///< FDM for IMS Systems #define USB_DEV_FDM180M ( ( MBG_USB_CLASS_FDM << 8 ) | 0x02 ) ///< FDM for old Lantime Systems (M300/M600/M900) +#define USB_DEV_PMU190 ( ( MBG_USB_CLASS_FDM << 8 ) | 0x03 ) ///< Phasor Measurement Unit (IEEE C37.118), Phasor and Frequency Measurement #define USB_DEV_MDU300 ( ( MBG_USB_CLASS_MDU << 8 ) | 0x01 ) #define USB_DEV_MDU312 ( ( MBG_USB_CLASS_MDU << 8 ) | 0x02 ) @@ -276,6 +324,8 @@ enum MBG_USB_CLASS_CODES #define USB_DEV_SSP100 ( ( MBG_USB_CLASS_HPS << 8 ) | 0x02 ) #define USB_DEV_VSG180 ( ( MBG_USB_CLASS_VSG << 8 ) | 0x01 ) +#define USB_DEV_VSG181 ( ( MBG_USB_CLASS_VSG << 8 ) | 0x02 ) +#define USB_DEV_VSG181H ( ( MBG_USB_CLASS_VSG << 8 ) | 0x03 ) #define USB_DEV_VSI180 ( ( MBG_USB_CLASS_VSI << 8 ) | 0x01 ) @@ -285,6 +335,10 @@ enum MBG_USB_CLASS_CODES #define USB_DEV_GNS181 ( ( MBG_USB_CLASS_GNS << 8 ) | 0x02 ) #define USB_DEV_GNS165 ( ( MBG_USB_CLASS_GNS << 8 ) | 0x03 ) #define USB_DEV_GNM181 ( ( MBG_USB_CLASS_GNS << 8 ) | 0x04 ) +#define USB_DEV_GNS181_UC ( ( MBG_USB_CLASS_GNS << 8 ) | 0x05 ) +#define USB_DEV_GNS190 ( ( MBG_USB_CLASS_GNS << 8 ) | 0x06 ) +#define USB_DEV_GNS190_UC ( ( MBG_USB_CLASS_GNS << 8 ) | 0x07 ) +#define USB_DEV_GNS191 ( ( MBG_USB_CLASS_GNS << 8 ) | 0x08 ) ///< Receiver Modul: Septentrio mosaic-T #define USB_DEV_N2X180 ( ( MBG_USB_CLASS_N2X << 8 ) | 0x01 ) @@ -292,7 +346,13 @@ enum MBG_USB_CLASS_CODES #define USB_DEV_PIO180 ( ( MBG_USB_CLASS_PIO << 8 ) | 0x01 ) ///< Programmable Input/Output Module -// If new devices are defined here then appropriate definitions should also +#define USB_DEV_WSI_UG2864 ( ( MBG_USB_CLASS_WSI << 8 ) | 0x01 ) + +#define USB_DEV_RCG181 ( ( MBG_USB_CLASS_RCG << 8 ) | 0x01 ) ///< Radio Carrier Generator + +#define USB_DEV_VMX180 ( ( MBG_USB_CLASS_VMX << 8 ) | 0x01 ) ///< Video Matrix + +// If new devices are defined here, appropriate definitions should also // be added to MBG_USB_DEVICE_NAMES and DEFAULT_MBG_USB_DEVICE_NAMES. /** @} anchor MBG_USB_DEVICE_IDS */ @@ -336,10 +396,13 @@ enum MBG_USB_CLASS_CODES #define USB_DEV_NAME_ESI_01 "ESI_01" #define USB_DEV_NAME_FCU_01 "FCU_01" +#define USB_DEV_NAME_FCU200 "FCU200" #define USB_DEV_NAME_CPE_01 "CPE_01" #define USB_DEV_NAME_GPS180 "GPS180" +#define USB_DEV_NAME_GPS190 "GPS190" +#define USB_DEV_NAME_GPS182 "GPS182" #define USB_DEV_NAME_LNO180 "LNO180" @@ -353,8 +416,13 @@ enum MBG_USB_CLASS_CODES #define USB_DEV_NAME_BPE_01 "BPE_01" #define USB_DEV_NAME_BPE_STM "BPE" +#define USB_DEV_NAME_BPE2XXX "BPE2XXX" +#define USB_DEV_NAME_BPE2352 "BPE2352" +#define USB_DEV_NAME_BPE8XXX "BPE8XXX" +#define USB_DEV_NAME_BPE6042 "BPE6042" #define USB_DEV_NAME_RSC_01 "RSC_01" +#define USB_DEV_NAME_RSC_02 "RSC_02" #define USB_DEV_NAME_SPT_01 "SPT_01" @@ -363,11 +431,13 @@ enum MBG_USB_CLASS_CODES #define USB_DEV_NAME_LAN_CPU_SERIAL "LAN_CPU_SERIAL" #define USB_DEV_NAME_SCG_01 "SCG_01" +#define USB_DEV_NAME_SCG181 "SCG181" #define USB_DEV_NAME_SDI_01 "SDI_01" #define USB_DEV_NAME_FDM180 "FDM180" #define USB_DEV_NAME_FDM180M "FDM180M" +#define USB_DEV_NAME_PMU190 "PMU190" #define USB_DEV_NAME_MDU300 "MDU300" #define USB_DEV_NAME_MDU312 "MDU312" @@ -378,6 +448,8 @@ enum MBG_USB_CLASS_CODES #define USB_DEV_NAME_SSP100 "SSP100" #define USB_DEV_NAME_VSG180 "VSG180" +#define USB_DEV_NAME_VSG181 "VSG181" +#define USB_DEV_NAME_VSG181H "VSG181H" #define USB_DEV_NAME_VSI180 "VSI180" #define USB_DEV_NAME_GTS180 "GTS180" @@ -386,6 +458,10 @@ enum MBG_USB_CLASS_CODES #define USB_DEV_NAME_GNS181 "GNS181" #define USB_DEV_NAME_GNS165 "GNS165" #define USB_DEV_NAME_GNM181 "GNM181" +#define USB_DEV_NAME_GNS181_UC "GNS181_UC" +#define USB_DEV_NAME_GNS190 "GNS190" +#define USB_DEV_NAME_GNS190_UC "GNS190_UC" +#define USB_DEV_NAME_GNS191 "GNS191" #define USB_DEV_NAME_N2X180 "N2X180" @@ -393,6 +469,12 @@ enum MBG_USB_CLASS_CODES #define USB_DEV_NAME_PIO180 "PIO180" +#define USB_DEV_NAME_WSI_UG2864 "WSI_UG2864" + +#define USB_DEV_NAME_RCG181 "RCG181" + +#define USB_DEV_NAME_VMX180 "VMX180" + /** @} anchor MBG_USB_DEVICE_NAMES */ @@ -459,6 +541,25 @@ enum MBG_USB_CLASS_CODES { USB_DEV_VSI180, USB_DEV_NAME_VSI180 }, \ { USB_DEV_CPC200, USB_DEV_NAME_CPC200 }, \ { USB_DEV_GNM181, USB_DEV_NAME_GNM181 }, \ + { USB_DEV_RSC_02, USB_DEV_NAME_RSC_02 }, \ + { USB_DEV_FCU200, USB_DEV_NAME_FCU200 }, \ + { USB_DEV_GNS181_UC, USB_DEV_NAME_GNS181_UC }, \ + { USB_DEV_WSI_UG2864, USB_DEV_NAME_WSI_UG2864 }, \ + { USB_DEV_VSG181, USB_DEV_NAME_VSG181 }, \ + { USB_DEV_BPE2XXX, USB_DEV_NAME_BPE2XXX }, \ + { USB_DEV_BPE2352, USB_DEV_NAME_BPE2352 }, \ + { USB_DEV_BPE8XXX, USB_DEV_NAME_BPE8XXX }, \ + { USB_DEV_BPE6042, USB_DEV_NAME_BPE6042 }, \ + { USB_DEV_GPS190, USB_DEV_NAME_GPS190 }, \ + { USB_DEV_GNS190, USB_DEV_NAME_GNS190 }, \ + { USB_DEV_SCG181, USB_DEV_NAME_SCG181 }, \ + { USB_DEV_PMU190, USB_DEV_NAME_PMU190 }, \ + { USB_DEV_GNS190_UC, USB_DEV_NAME_GNS190_UC }, \ + { USB_DEV_RCG181, USB_DEV_NAME_RCG181 }, \ + { USB_DEV_GNS191, USB_DEV_NAME_GNS191 }, \ + { USB_DEV_VSG181H, USB_DEV_NAME_VSG181H }, \ + { USB_DEV_VMX180, USB_DEV_NAME_VMX180 }, \ + { USB_DEV_GPS182, USB_DEV_NAME_GPS182 }, \ { 0, /* end of table */ NULL } \ } diff --git a/mbglib/common/words.h b/mbglib/common/words.h index 5550bbb..b90278c 100644 --- a/mbglib/common/words.h +++ b/mbglib/common/words.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: words.h 1.46 2019/02/07 14:38:56Z martin REL_M $ + * $Id: words.h 1.52 2021/03/18 11:08:31Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,19 @@ * * ----------------------------------------------------------------------- * $Log: words.h $ - * Revision 1.46 2019/02/07 14:38:56Z martin + * Revision 1.52 2021/03/18 11:08:31Z martin + * Updated some comments. + * Revision 1.51 2021/03/16 12:20:31 martin + * Updated some comments. + * Revision 1.50 2021/03/12 10:48:34 martin + * Corrected the wording of a comment. + * Revision 1.49 2019/10/23 08:31:48 thomas-b + * Added struct name for NANO_TIME_64 + * Revision 1.48 2019/06/17 08:38:59 thomas-b + * Renamed structs according to Meinberg naming convention + * Revision 1.47 2019/06/06 12:17:14 thomas-b + * Added several struct names to allow forward declaration + * Revision 1.46 2019/02/07 14:38:56 martin * Removed a duplicate definition. * Revision 1.45 2018/11/22 16:38:15 martin * Removed inclusion of mbg_no_tgt.h which is obsolete here. @@ -181,7 +193,7 @@ #if defined( _C166 ) \ || defined( _CC51 ) - #define _BIT_DEFINED 1 // these compilers natively support the "bit" type + #define _BIT_DEFINED 1 // These compilers natively support the "bit" type. #define USE_LONG_FOR_INT32 1 #endif @@ -191,7 +203,7 @@ #if defined( MBG_TGT_HAS_INT_8_16_32 ) - // Define C99 exact size types using non-standard exact-size types + // Define C99 exact size types using non-standard exact-size types. typedef __int8 int8_t; typedef unsigned __int8 uint8_t; @@ -370,7 +382,7 @@ typedef int bool; #endif - // Eventually provoke a build error if the build + // Try to provoke a build error if the build // environment unexpectedly supports "bool" natively. #define bool bool #define true 1 @@ -392,7 +404,7 @@ // and should be fine if it's supported natively. // // However, if "bool" has been substituted above - // by "int"then this is just a hack which may yield + // by "int", this is just a hack which may yield // unexpected results with code like: // return (bit) ( val & 0x10 ); // A safe way of coding would be: @@ -410,7 +422,7 @@ // clang / FreeBSD user space and kernel typedef bool bit; - // Eventually provoke a build error if the build + // Try to provoke a build error if the build // environment unexpectedly supports "bit" natively. #define bit bit @@ -435,27 +447,29 @@ #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 + +// The macros below assume little endianess. + +// These macros expect the name of a variable. #define BYTE_OF( _v, _n ) *( ( (uint8_t *) &(_v) ) + (_n) ) #define WORD_OF( _v, _n ) *( ( (uint16_t *) &(_v) ) + (_n) ) #define FBYTE_OF( _v, _n ) *( ( (uint8_t far *) &(_v) ) + (_n) ) #define FWORD_OF( _v, _n ) *( ( (uint16_t far *) &(_v) ) + (_n) ) -// same as above, but taking pointers +// Same as above, but taking pointers. #define BYTE_OF_P( _p, _n ) *( ( (uint8_t *) (_p) ) + (_n) ) #define WORD_OF_P( _p, _n ) *( ( (uint16_t *) (_p) ) + (_n) ) -// a macro to swap the byte order of a 16 bit value +// A macro to swap the byte order of a 16 bit value. #define _bswap16( _x ) \ ( \ ( ( ( (uint16_t) (_x) ) & 0x00FF ) << 8 ) | \ ( ( ( (uint16_t) (_x) ) & 0xFF00 ) >> 8 ) \ ) -// a macro to swap the byte order of a 32 bit value +// A macro to swap the byte order of a 32 bit value. #define _bswap32( _x ) \ ( \ ( ( ( (uint32_t) (_x) ) & 0x000000FFUL ) << 24 ) | \ @@ -464,7 +478,7 @@ ( ( ( (uint32_t) (_x) ) & 0xFF000000UL ) >> 24 ) \ ) -// a macro to swap the word order of a 32 bit value +// A macro to swap the word order of a 32 bit value. #define _wswap32( _x ) \ ( \ ( ( ( (uint32_t) (_x) ) & 0x0000FFFFUL ) << 16 ) | \ @@ -475,7 +489,7 @@ #define _var_bswap32( _v ) (_v) = _bswap32( _v ) -// The C51 compiler is big-endian, that means the most +// The C51 compiler is big-endian, this means the most // significant byte of a 16 or 32 bit value is stored in // the lowest memory location. Most other systems are // little-endian, so we must use macros to adjust the @@ -537,16 +551,16 @@ typedef struct } MBG_CODE_NAME_TABLE_ENTRY; /** - * @brief A macro defining a ::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 + * @param[in] _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 + * @brief A macro defining an empty ::MBG_CODE_NAME_TABLE_ENTRY. * * This is used to terminate a table. */ @@ -555,31 +569,31 @@ typedef struct /** - * @brief A timestamp with nanosecond resolution + * @brief A timestamp with nanosecond resolution. * - * @note If the structure is to represent a negative value then both the - * fields nano_secs and secs have to be set to the negative values. + * @note If the structure is to represent a negative value, both the + * fields @p nano_secs and @p secs have to be set to the negative values. * Otherwise the sign of the represented number was ambiguous if either - * of the fields was accidentally 0, and only the other field was not 0. + * of the fields was 0 by accident, and only the other field was not 0. * The macro ::_nano_time_negative should always be used to determine * if the sign of the represented value is negative, or not. * - * @note The secs field will roll over on 2038-01-19 03:14:07 + * @note The @p secs field will roll over on 2038-01-19 03:14:07 * if used for the number of seconds since 1970-01-01, just like - * 32 bit POSIX time_t. + * 32 bit POSIX @a time_t. * * @see ::_nano_time_negative * @see ::_nano_time_zero * @see ::NANO_TIME_64 */ -typedef struct +typedef struct nano_time_s { // ATTENTION: - // This structure is and has has been used in public API calls for a long time, + // This structure is and has been used in public API calls for a long time, // so even though the order of member fields is different than in NANO_TIME_64 // this must *NOT* be changed, or API compatibility will get lost! - int32_t nano_secs; ///< [nanoseconds] - int32_t secs; ///< [seconds], usually since 1970-01-01 00:00:00 + int32_t nano_secs; ///< [nanoseconds]. + int32_t secs; ///< [seconds], usually since 1970-01-01 00:00:00. } NANO_TIME; @@ -591,13 +605,13 @@ do \ } while ( 0 ) /** - * Check if the value of the ::NANO_TIME structure _nt is negative + * @brief Check if the value of the ::NANO_TIME structure _nt is negative. */ #define _nano_time_negative( _nt ) \ ( ( (_nt)->secs < 0 ) || ( (_nt)->nano_secs < 0 ) ) /** - * Check if the value of the ::NANO_TIME structure _nt is 0 + * @brief Check if the value of the ::NANO_TIME structure _nt is 0. */ #define _nano_time_zero( _nt ) \ ( ( (_nt)->secs == 0 ) && ( (_nt)->nano_secs == 0 ) ) @@ -605,12 +619,12 @@ do \ /** - * @brief A timestamp with nanosecond resolution, but 64 bit size + * @brief A timestamp with nanosecond resolution, but 64 bit size. * - * @note If the structure is to represent a negative value then both the - * fields nano_secs and secs have to be set to the negative values. + * @note If the structure is to represent a negative value, both the + * fields @p nano_secs and @p secs have to be set to the negative values. * Otherwise the sign of the represented number was ambiguous if either - * of the fields was accidentally 0, and only the other field was not 0. + * of the fields was 0 by accident, and only the other field was not 0. * The macro ::_nano_time_64_negative should always be used to determine * if the sign of the represented value is negative, or not. * @@ -618,14 +632,14 @@ do \ * @see ::_nano_time_64_zero * @see ::NANO_TIME */ -typedef struct +typedef struct nano_time_64_s { // ATTENTION: // This structure is and has been used in public API calls for a long time, - // so even though the order of member fields is different than in NANO_TIME + // so even though the order of member fields is different than in ::NANO_TIME, // this must *NOT* be changed, or API compatibility will get lost! - int64_t secs; ///< [seconds], usually since 1970-01-01 00:00:00 - int64_t nano_secs; ///< [nanoseconds] + int64_t secs; ///< [seconds], usually since 1970-01-01 00:00:00. + int64_t nano_secs; ///< [nanoseconds]. } NANO_TIME_64; @@ -637,20 +651,20 @@ do \ } while ( 0 ) /** - * Check if the value of the ::NANO_TIME_64 structure _nt is negative + * @brief Check if the value of the ::NANO_TIME_64 structure _nt is negative. */ #define _nano_time_64_negative( _nt ) \ ( ( (_nt)->secs < 0 ) || ( (_nt)->nano_secs < 0 ) ) /** - * Check if the value of the ::NANO_TIME_64 structure _nt is 0 + * @brief Check if the value of the ::NANO_TIME_64 structure _nt is 0. */ #define _nano_time_64_zero( _nt ) \ ( ( (_nt)->secs == 0 ) && ( (_nt)->nano_secs == 0 ) ) -// The size_t type can eventually be larger than an int type. +// The size_t type may be larger than an int type. // However, some snprintf-like functions expect a size_t value // to specify the buffer size, but just return an int value. // So we take care that at least the return value is limited @@ -665,7 +679,7 @@ do \ /** - * @brief A helper macro to implement ::STRINGIFY correctly + * @brief A helper macro to implement ::STRINGIFY correctly. * * This just a helper macro which must be defined before * ::STRINGIFY to work correctly, and should not be used alone. @@ -676,20 +690,20 @@ do \ /** - * @brief Make a string from a constant definition + * @brief Make a string from a constant definition. * * This macro can be used e.g. to define a constant string on the * compiler's command line, e.g. like -DVERSION_STRING="v1.0 BETA". * Source code like * @code{.c} - const char version_string[] = VERSION_STRING; + const char version_string[] = VERSION_STRING; * @endcode * * may not work for every compiler since the double quotes * in VERSION_STRING may be removed when the definition is evaluated. * A proper solution is to use the STRINGIFY() macro defined here: * @code{.c} - const char version_string[] = STRINGIFY( VERSION_STRING ); + const char version_string[] = STRINGIFY( VERSION_STRING ); * @endcode */ #define STRINGIFY(x) XSTRINGIFY(x) diff --git a/mbglib/win32/mbg_w32.h b/mbglib/win32/mbg_w32.h index 8eaa17d..70469c0 100644 --- a/mbglib/win32/mbg_w32.h +++ b/mbglib/win32/mbg_w32.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbg_w32.h 1.10 2018/12/04 09:52:48Z martin REL_M $ + * $Id: mbg_w32.h 1.12 2020/09/02 15:10:00Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,11 @@ * * ----------------------------------------------------------------------- * $Log: mbg_w32.h $ + * Revision 1.12 2020/09/02 15:10:00Z martin + * New variable ExDefaultNonPagedPoolType. + * Updated function prototypes. + * Revision 1.11 2020/06/22 11:20:14Z martin + * Refactored precise kernel time API usage. * Revision 1.10 2018/12/04 09:52:48Z martin * Make sure DEBUG_RSRC is always defined. * Revision 1.9 2018/11/22 10:53:18Z martin @@ -58,6 +63,7 @@ #ifdef _MBG_W32 #define _ext + #define _DO_INIT #else #define _ext extern #endif @@ -91,17 +97,6 @@ -/** - * @brief A pointer to a function returning the system time as LARGE_INTEGER. - * - * This is for kernel mode only. The function can be e.g. the standard Windows - * API call KeQuerySystemTime() or the KeQuerySystemTimePrecise() API - * call introduced with Windows 8. - */ -typedef VOID (*KE_QUERY_SYSTEM_TIME_FNC)(PLARGE_INTEGER CurrentTime); - - - #if defined( MBG_TGT_KERNEL ) #if !defined( NTKERNELAPI ) @@ -128,22 +123,44 @@ typedef VOID (*KE_QUERY_SYSTEM_TIME_FNC)(PLARGE_INTEGER CurrentTime); #define MBG_TICKS_PER_SEC ( 10000000 / KeQueryTimeIncrement() ) + +/** + * @brief A pointer to a function returning the system time as LARGE_INTEGER. + * + * This is for kernel mode only. The function can be e.g. the standard Windows + * API call KeQuerySystemTime() or the KeQuerySystemTimePrecise() API + * call introduced with Windows 8. + */ +typedef VOID KE_QUERY_SYSTEM_TIME_FNC( _Out_ PLARGE_INTEGER ); + + +enum KE_QUERY_SYSTEM_TIME_TYPES +{ + KE_QUERY_SYSTEM_TIME_TYPE_WRAPPER_FNC, + KE_QUERY_SYSTEM_TIME_TYPE_NATIVE_FNC, + KE_QUERY_SYSTEM_TIME_TYPE_PRECISE_FNC, + N_KE_QUERY_SYSTEM_TIME_TYPE +}; + + /** - * @brief Get precise Windows system time as FILETIME. + * @brief Get precise Windows system time as LARGE_INTEGER. * * @note This function has been introduced with Windows 8, * so it is not available on older Windows versions. Thus * the API call is imported from ntoskrnl.exe at runtime. * - * @param CurrentTime pointer to a LARGE_INTEGER to be filled + * @param[out] CurrentTime Address of a LARGE_INTEGER to be filled. * - * @see KE_QUERY_SYSTEM_TIME_FNC - * @see import_kernel_precise_time_api() + * @see ::KE_QUERY_SYSTEM_TIME_FNC + * @see ::import_kernel_precise_time_api */ NTKERNELAPI VOID KeQuerySystemTimePrecise( _Out_ PLARGE_INTEGER CurrentTime); +NTKERNELAPI KE_QUERY_SYSTEM_TIME_FNC KeQuerySystemTimePrecise; + #if defined( MBG_TGT_WIN32_PNP ) @@ -283,24 +300,96 @@ extern "C" { /* by MAKEHDR, do not remove the comments. */ clock_t w32_clock( void ) ; + VOID mbg_ke_query_system_time( _Out_ LARGE_INTEGER *p ) ; + /** + * @brief Set up a pointer to a function which reads the Windows system time. + * + * Starting with Windows 8, the Windows kernel provides a function + * ::KeQuerySystemTimePrecise which allows reading the system time + * much more precisely than the original function ::KeQuerySystemTime + * which is even supported on older Windows versions. + * + * This function checks at runtime if the new API call is supported, + * or not, and a global function pointer ::ke_query_system_time_fnc + * is set up accordingly with the address of either function. + * Regardless whether the precise API call is supported or not, + * the function pointer can be used afterwards whenever a driver + * needs to read the current system time. + * + * This function is for kernel mode only. + * + * @see ::ke_query_system_time_fnc + * @see ::ke_query_system_time_type + * @see ::KeQuerySystemTimePrecise + */ + void import_kernel_precise_time_api( void ) ; + /** - * @brief Try to import an API function to read precise Windows system time + * @brief Set the default pool typ for non-pageable memory * - * Check if the Windows API call KeQuerySystemTimePrecise() is available - * in kernel mode. This function has been introduced with Windows 8, so it - * is not available on older Windows versions, and thus the API call is - * imported from ntoskrnl.exe at runtime. + * Older Windows versions provide a pool of non-pageable memory, + * identified by a constant 'NonPagedPool'. However, the memory + * range provided by this pool is executable, which can be a + * security risk. * - * @param fnc address of a function pointer which is set to the imported - * API function, or to NULL if the API call is not supported + * Starting with Windows 8 / Server 2012, Windows provides + * another memory pool identified by the constant 'NonPagedPoolNx', + * the memory of which is not executable, and memory allocations + * have to be made from that pool. * - * @see KeQuerySystemTimePrecise() + * This routine checks the Windows version and sets the global + * variable ExDefaultNonPagedPoolType to 'NonPagedPoolNx', + * if appropriate, and all calls to ExAllocatePool() use that + * variable to specify the pool from which to allocate memory. + * + * This function should be called once from DriverEntry(), before + * any calls to ExAllocatePool() are made. + * + * This function is for kernel mode only. + * + * @see ::ExDefaultNonPagedPoolType */ - void import_kernel_precise_time_api( KE_QUERY_SYSTEM_TIME_FNC *fnc ) ; + void set_default_non_paged_pool_type( void ) ; /* ----- function prototypes end ----- */ + +_ext KE_QUERY_SYSTEM_TIME_FNC *ke_query_system_time_fnc +#ifdef _DO_INIT + = mbg_ke_query_system_time +#endif +; + + +_ext int ke_query_system_time_type +#ifdef _DO_INIT + = KE_QUERY_SYSTEM_TIME_TYPE_WRAPPER_FNC +#endif +; // see ::KE_QUERY_SYSTEM_TIME_TYPES + + +/** + * @brief A variable containing the default memory pool type + * + * Passed to ExAllocatePool() whenever memory is allocated + * using the _pcps_kmalloc() macro. + * + * Its value defaults to 0 (i.e. 'NonPagedPool') after startup, + * which is appropriate for older Windows versions. + * Newer Windows versions require memory allocation e.g. from the + * 'NonPagedPoolNx', so ::setup_default_mem_pool_type should be + * called at startup to adjust this variable, if required. + * + * @see ::setup_default_mem_pool_type + */ +_ext POOL_TYPE ExDefaultNonPagedPoolType +#ifdef _DO_INIT + = NonPagedPool +#endif +; + + #ifdef __cplusplus } #endif @@ -308,6 +397,7 @@ extern "C" { /* End of header body */ #undef _ext +#undef _DO_INIT #endif /* _MBG_W32_H */ diff --git a/mbglib/win32/mbgsvcio.h b/mbglib/win32/mbgsvcio.h index 51e7d2a..ab3b3a7 100644 --- a/mbglib/win32/mbgsvcio.h +++ b/mbglib/win32/mbgsvcio.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgsvcio.h 1.18 2018/09/21 07:39:14Z martin REL_M $ + * $Id: mbgsvcio.h 1.19 2020/06/22 13:08:11Z martin.burnicki REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: mbgsvcio.h $ + * Revision 1.19 2020/06/22 13:08:11Z martin.burnicki + * FT_DWL::dwl is now an int64_t instead of an uint64_t. + * REF_TIME was renamed to FT_DWL_EX. + * New structure FT_DWL_EX_CYCLES. * Revision 1.18 2018/09/21 07:39:14Z martin * New version code 308, compatibility version code still 200. * New define USE_SERIAL_XHRT, still 0 by default. @@ -62,7 +66,8 @@ #include <mbg_tgt.h> #include <words.h> #include <pcpsdefs.h> - +#include <mbgdevio.h> // for MBG_XHRT_VARS +#include <mbgpccyc.h> #ifdef _MBGSVCIO @@ -83,7 +88,7 @@ #define MBGSVCIO_COMPAT_VERSION 0x0200 -#define USE_SERIAL_XHRT 0 // not fully implemented/tested +#define USE_SERIAL_XHRT 0 // FIXME should be 0 by default // not fully implemented/tested #ifdef __cplusplus @@ -102,7 +107,7 @@ extern "C" { typedef union { FILETIME ft; ///< FILETIME structure as provided by the Windows API - uint64_t dwl; ///< used to access as single 64 bit number + int64_t dwl; ///< used to access as single 64 bit number } FT_DWL; @@ -117,7 +122,19 @@ typedef struct int32_t utc_offs; ///< %UTC offset in [sec] PCPS_TIME_STATUS_X status; ///< extended status, see ::PCPS_TIME_STATUS_X -} REF_TIME; +} FT_DWL_EX; + + + +/** + * @brief An extended timestamp plus associated machine cycles. + */ +typedef struct +{ + MBG_PC_CYCLES cycles; + FT_DWL_EX ft_ex; + +} FT_DWL_EX_CYCLES; @@ -126,8 +143,8 @@ typedef struct */ typedef struct { - uint32_t code; ///< error/status code, see ::ERR_INFO_CODES - REF_TIME time; ///< clock's time and status when ::code was updated + uint32_t code; ///< error/status code, see ::ERR_INFO_CODES + FT_DWL_EX time; ///< clock's time and status when ::code was updated } ERR_INFO; diff --git a/mbglib/win32/mbgsvctl.h b/mbglib/win32/mbgsvctl.h index 4a90675..2bde282 100644 --- a/mbglib/win32/mbgsvctl.h +++ b/mbglib/win32/mbgsvctl.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgsvctl.h 1.30 2018/11/29 14:27:30Z martin REL_M $ + * $Id: mbgsvctl.h 1.34 2021/10/25 14:39:59Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,16 @@ * * ----------------------------------------------------------------------- * $Log: mbgsvctl.h $ + * Revision 1.34 2021/10/25 14:39:59Z martin + * Updated function prototypes. + * Revision 1.33 2021/10/20 16:05:27Z martin + * Updated function prototypes. + * Revision 1.32 2021/09/30 13:03:00Z martin.burnicki + * Proper definition of a global variable that is exported + * by this DLL and imported by a different one. + * Revision 1.31 2020/07/22 09:39:51 martin + * Removed obsolete inclusion of mbgdevio.h. + * Updated function prototypes. * Revision 1.30 2018/11/29 14:27:30Z martin * Updated function prototypes. * Revision 1.29 2018/09/21 11:12:49Z martin @@ -114,12 +124,6 @@ /* Other headers to be included */ -#if !defined MBG_OMIT_MBGDEVIO_H - #include <mbgdevio.h> -#else - typedef void* MBG_DEVICE_LIST; -#endif - #include <mbg_tgt.h> #include <use_pack.h> #include <gpsdefs.h> @@ -129,17 +133,28 @@ #include <rs232.h> #include <mbgadjtm_cfg.h> #else - #define MBGADJTM_CFG int //##++++++++++++++ + #define MBGADJTM_CFG int // Dummy declaration. #include <mbgserio.h> #endif - #ifdef _MBGSVCTL #define _ext #else #define _ext extern #endif +#if defined( MBGSVCTL_STATIC_LIB ) + // We don't build/use a DLL. + #define _MBG_API_ATTR_VAR +#else + // We build or use a DLL by default. + #ifdef _MBGSVCTL + #define _MBG_API_ATTR_VAR _MBG_API_ATTR_EXPORT + #else + #define _MBG_API_ATTR_VAR _MBG_API_ATTR_IMPORT + #endif +#endif + /* Start of header body */ @@ -158,6 +173,22 @@ extern "C" { #endif +/** + * @brief The number of SYN1588 devices found in the system. + * + * Will be set by functions like mbg_find_devices(), and can + * be used for a fast check to see if those devices have to be + * accounted for. + * + * On Windows, this variable is exported by the mbgsvctl.dll, + * so it is defined here. + * + * For non-Windows systems, the variable is defined elsewhere. + */ +_ext _MBG_API_ATTR_VAR long syn1588_devices_found; + + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ @@ -166,13 +197,13 @@ extern "C" { /** * @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 + * If this library is used as a DLL/shared object library, 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 + * @return The version number. * * @see ::mbgsvctl_check_version * @see ::MBGSVCTL_VERSION defined in mbgsvctl.h @@ -182,16 +213,16 @@ extern "C" { /** * @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 + * If this library is used as a DLL/shared object library, 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 ::MBGSVCTL_VERSION - * from the mbgsvctl.h file version used to build the application + * @param[in] header_version Version number to be checked, should be ::MBGSVCTL_VERSION + * from the <em>mbgsvctl.h</em> file version used to build the application. * - * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE + * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE. * * @see ::mbgsvctl_get_version * @see ::MBGSVCTL_VERSION defined in mbgsvctl.h @@ -203,7 +234,7 @@ extern "C" { /** * @brief Register an event source. * - * When an application uses the RegisterEventSource() or OpenEventLog() + * When an application uses the @a RegisterEventSource or @a OpenEventLog * function to get a handle to an event log, the event logging service * searches for the specified source name in the registry. A new source * name can be added to the registry by opening a new registry subkey @@ -213,7 +244,7 @@ extern "C" { * @param[in] eventlog_name Name of the to be registered as event source, * e.g. the name of a DLL or application. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ _MBG_API_ATTR int _MBG_API mbg_svc_register_event_source( const char *eventlog_name ) ; @@ -223,11 +254,11 @@ extern "C" { * * TODO * - * @param[in] msg_id One of the message IDs defined in messages.mc, or a system message ID. - * @param[in] err_code ERROR_SUCCESS (==0), or one of the win32 system error codes. - * @param[in] fmt An optional format string, or NULL. - * @param[in] info_1 A string parameter, if required by the format string, else NULL. - * @param[in] info_2 A second string parameter, if required by the format string, else NULL. + * @param[in] msg_id One of the message IDs defined in <em>messages.mc</em>, or a system message ID. + * @param[in] sys_rc @a ERROR_SUCCESS (== 0), or one of the win32 system error codes. + * @param[in] fmt An optional format string, or @a NULL. + * @param[in] info_1 A string parameter, if required by the format string, else @a NULL. + * @param[in] info_2 A second string parameter, if required by the format string, else @a NULL. * * @see ::mbg_svc_log_msg */ @@ -244,8 +275,8 @@ extern "C" { * @param[in] mbg_errno One of the @ref MBG_ERROR_CODES to be converted to a message ID * to be passed to ::mbg_svc_log_msg. * @param[in] fmt An optional format string passed to ::mbg_svc_log_msg. - * @param[in] info_1 A string parameter passed to ::mbg_svc_log_msg, depending on the format string - * @param[in] info_2 Another string parameter passed to ::mbg_svc_log_msg, depending on the format string + * @param[in] info_1 A string parameter passed to ::mbg_svc_log_msg, depending on the format string. + * @param[in] info_2 Another string parameter passed to ::mbg_svc_log_msg, depending on the format string. * * @see ::mbg_svc_log_msg */ @@ -254,36 +285,67 @@ extern "C" { /** * @brief Check if the calling process has admin rights. * - * @note The CheckTokenMembership() API call is used if it is supported - * on the Windows system where the application is running. - * On legacy systems where the API call is not available we call - *::legacy_check_token_membership instead. - * - * @param[in] p_sid Pointer to the Security ID to be checked. + * @note The @a CheckTokenMembership API call is used if it is + * available at runtime. On legacy systems where the API call is + * not available, we call ::legacy_check_token_membership instead. * - * @return true if the calling process has admin rights, else false. + * @return @a true if the calling process has admin rights, else @a false. * * @see ::legacy_check_token_membership */ _MBG_API_ATTR BOOL _MBG_API mbg_svc_has_admin_rights( void ) ; /** - * @brief Free a device list that has been set up by ::mbg_svc_find_devices_with_hw_id + * @brief Check if running on Windows 10 or newer. + * + * The typical API calls used to determine the Windows version + * (@a GetVersionInfoEx, etc.) have been deprecated and may not be + * available in Windows 10 and later. + * + * On the other hand, the new version helper functions declared + * in <em>versionhelpers.h</em> (@a IsWindows10OrGreater, etc.) may return + * fake information depending on whether a manifest has been added + * to an application, and depending on the values in the manifest. + * + * The approach used here should always return true information. + * + * @return ::MBG_SUCCESS if the running Windows version is + * Windows 10, Windows Server 2016, or later,<br> + * ::MBG_ERR_NOT_SUPP_ON_OS if the version is older,<br> + * or one of the @ref MBG_ERROR_CODES, if an error + * occurred when trying to determine the version. + */ + _MBG_API_ATTR int _MBG_API mbg_svc_chk_if_win10_or_newer( void ) ; + + /** + * @brief Free a device list that has been set up by ::mbg_svc_find_devices_with_hw_id. * - * @param[in,out] devices Pointer to the list to be freed. + * @param[in,out] list Pointer to the list to be freed. * * @see ::mbg_svc_find_devices_with_hw_id */ _MBG_API_ATTR void _MBG_API mbg_svc_free_device_list( MBG_DEV_FN_LIST_ENTRY *list ) ; + /** + * @brief Search for supported devices and return the number of devices found. + * + * If SYN1588 support has been compiled in, this function also tries to + * detect those cards (which may require admin rights), and the returned number + * includes the number of detected SYN1588 cards. + * + * In any case, the global variable ::syn1588_devices_found is setup accordingly. + * + * @return The total number of supported devices that have been found. + */ _MBG_API_ATTR int _MBG_API mbg_svc_find_devices( void ) ; + /** - * @brief Search for Meinberg PnP devices and set up a device list + * @brief Search for Meinberg PnP devices and set up a device list. * * The allocated list can be freed by calling ::mbg_svc_free_device_list. * - * @param[out] p_list Pointer to the list to be set up - * @param[in] max_devices Max number of entries to be added to the list // TODO Make this obsolete + * @param[out] p_list Pointer to the list to be set up. + * @param[in] max_devices Max number of entries to be added to the list. TODO Make this obsolete. * * @return The number of Meinberg PnP devices in the list */ @@ -292,21 +354,21 @@ extern "C" { /** * @brief Get a device path string for a device from a global list. * - * The list of devices must bhave been set up before - * by calling ::mbg_find_pnp_devices. + * The list of devices must have been set up before + * by calling ::mbg_svc_find_pnp_devices. * - * @param[in] device_index The index of the device in the list. + * @param[in] dev_idx The index of the device in the list. * - * @return The device path, or NULL if @p device_index is out of range. + * @return The device path, or @a NULL if @p device_index is out of range. */ - _MBG_API_ATTR const char * _MBG_API mbg_svc_get_device_path( unsigned int device_index ) ; + _MBG_API_ATTR const char * _MBG_API mbg_svc_get_device_path( unsigned int dev_idx ) ; /** * @brief Write the time service configuration parameters to the registry. * * @param[in] p A structure with the settings to be written to the registry. * - * @return ERROR_SUCCESS, or a win32 system error code. + * @return @a ERROR_SUCCESS on success, else one of the win32 system error codes. */ _MBG_API_ATTR DWORD _MBG_API mbg_svc_set_mbgadjtm_cfg( const MBGADJTM_CFG *p ) ; @@ -315,7 +377,7 @@ extern "C" { * * @param[out] p A structure to be filled with the settings read from the registry. * - * @return ERROR_SUCCESS, or a win32 system error code. + * @return @a ERROR_SUCCESS on success, else one of the win32 system error codes. */ _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_mbgadjtm_cfg( MBGADJTM_CFG *p ) ; @@ -325,12 +387,13 @@ extern "C" { * * @param[in] p A structure with the settings to be written to the registry. * - * @return ERROR_SUCCESS, or a win32 system error code. + * @return @a ERROR_SUCCESS on success, else one of the win32 system error codes. */ _MBG_API_ATTR DWORD _MBG_API mbg_svc_set_mbg_serclock_cfg( const MBG_SERCLOCK_CFG *p ) ; _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_mbg_serclock_cfg( MBG_SERCLOCK_CFG *p ) ; _MBG_API_ATTR void _MBG_API mbg_svc_get_mbg_serclock_cfg_default( MBG_SERCLOCK_CFG *p ) ; + _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_omit_acc_restr( DWORD *p ) ; _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_msgs_filename( char *s, size_t size ) ; _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_stats_filename( char *s, size_t size ) ; _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_adjtm_filename( char *s, size_t size ) ; @@ -340,8 +403,8 @@ extern "C" { * @param[in] svc_name The name of the service to be queried. * * @return On success, one of the Windows service status codes - * SERVICE_STOPPED, SERVICE_RUNNING, etc., which are - * defined in winsvc.h with values > 0. + * @a SERVICE_STOPPED, @a SERVICE_RUNNING, etc., which are + * defined in <em>winsvc.h</em> with values > 0.<br> * On error, 0 if the service is not installed, or * (DWORD) -1 if there was a problem querying the status. */ @@ -352,7 +415,7 @@ extern "C" { * * @param[in] svc_name The name of the service to be started. * - * @return ERROR_SUCCESS on success, else one of the win32 system error codes. + * @return @a ERROR_SUCCESS on success, else one of the win32 system error codes. * * @see ::mbg_svc_stop * @see ::mbg_svc_pause @@ -365,7 +428,7 @@ extern "C" { * * @param[in] svc_name The name of the service to be stopped. * - * @return ERROR_SUCCESS on success, else one of the win32 system error codes. + * @return @a ERROR_SUCCESS on success, else one of the win32 system error codes. * * @see ::mbg_svc_start * @see ::mbg_svc_pause @@ -378,7 +441,7 @@ extern "C" { * * @param[in] svc_name The name of the service to be paused. * - * @return ERROR_SUCCESS on success, else one of the win32 system error codes. + * @return @a ERROR_SUCCESS on success, else one of the win32 system error codes. * * @see ::mbg_svc_start * @see ::mbg_svc_stop @@ -387,52 +450,52 @@ extern "C" { _MBG_API_ATTR DWORD _MBG_API mbg_svc_pause( const char *svc_name ) ; /** - * @brief Start a named service, log a message on error. + * @brief Continue a named service, log a message on error. * * @param[in] svc_name The name of the service to be continued. * - * @return ERROR_SUCCESS on success, else one of the win32 system error codes. + * @return @a ERROR_SUCCESS on success, else one of the win32 system error codes. * * @see ::mbg_svc_start * @see ::mbg_svc_stop * @see ::mbg_svc_pause - * @see ::mbg_svc_continue */ _MBG_API_ATTR DWORD _MBG_API mbg_svc_continue( const char *svc_name ) ; /** * @brief Install a named service, log a message on error. * - * Most parameters are simply passed to CreateService() + * Most parameters are simply passed to @a CreateService, * which is called to actually create the service. * * @param[in] svc_name The short name of the service. * @param[in] svc_type The service type. * @param[in] svc_start_type The service start type. - * @param[in] svc_disp_name The long (display) name oif the service. + * @param[in] svc_disp_name The long (display) name of the service. * @param[in] svc_description A service description string, actually not used. * @param[in] svc_exe_path Path to the service executable. * @param[in] svc_dependencies String with names of service on which this one depends. * - * @return ERROR_SUCCESS, or a win32 system error code. + * @return @a ERROR_SUCCESS on success, else one of the win32 system error codes. */ _MBG_API_ATTR DWORD _MBG_API mbg_svc_install( const char *svc_name, DWORD svc_type, DWORD svc_start_type, const char *svc_disp_name, const char *svc_description, const char *svc_exe_path, const char *svc_dependencies ) ; /** - * @brief Stop and remove a service, log a message on error + * @brief Stop and remove a service, log a message on error. * * @param[in] svc_name The name of the service to be removed. * - * @return ERROR_SUCCESS, or a win32 system error code. + * @return @a ERROR_SUCCESS on success, else one of the win32 system error codes. */ _MBG_API_ATTR DWORD _MBG_API mbg_svc_remove( const char *svc_name ) ; /** - * @brief Set a service's start mode to AUTO or MANUALLY. + * @brief Set the start mode of a service to @a AUTO or @a MANUALLY. * - * @param[in] svc_name The name of the service to be changed. + * @param[in] svc_name The name of the service to be changed. + * @param[in] autostart Controls if the service shall be automatically started, or not. * - * @return ERROR_SUCCESS, or a win32 system error code. + * @return @a ERROR_SUCCESS on success, else one of the win32 system error codes. */ _MBG_API_ATTR DWORD _MBG_API mbg_svc_set_autostart( const char *svc_name, BOOL autostart ) ; @@ -451,7 +514,7 @@ extern "C" { * @param[in] exe_name The base name of the executable. * @param[in] subdir The subdirectory of the executable. * - * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. */ _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_exe_path( char *path, uint32_t max_len, const char *exe_name, const char *subdir ) ; @@ -472,6 +535,7 @@ extern "C" { /* End of header body */ #undef _ext +#undef _MBG_API_ATTR_VAR #endif // _MBGSVCTL_H diff --git a/mbglib/win32/timecnv.h b/mbglib/win32/timecnv.h index fe5159c..0f12e73 100644 --- a/mbglib/win32/timecnv.h +++ b/mbglib/win32/timecnv.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: timecnv.h 1.15 2018/09/21 08:30:57Z martin REL_M $ + * $Id: timecnv.h 1.17 2021/04/30 14:00:53Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,19 @@ * * ----------------------------------------------------------------------- * $Log: timecnv.h $ + * Revision 1.17 2021/04/30 14:00:53Z martin + * Account for moved inline functions. + * Revision 1.16 2020/06/22 13:49:10Z martin.burnicki + * Preliminarily replaced some macros by type-safe inline functions. + * REF_TIME was renamed to FT_DWL_EX. + * REF_TIME_CYCLES was renamed to FT_DWL_EX_CYCLES. + * SERIAL_TIME_STRING now contains an FT_DWL_EX_CYCLES field only + * instead of distinct fields for time stamp and cycles. + * GET_REF_TIME_FNC now expects an FT_DWL_EX_CYCLES parameter only, + * which includes a cycles field. + * Use MBG_SYS_TIME for system timestamps. + * Removed inclusion of obsolete file pcpcsutil.h. + * Updated function prototypes. * Revision 1.15 2018/09/21 08:30:57Z martin * Changed year_limit from 1990 to 1970. * Revision 1.14 2018/08/08 09:49:20Z martin @@ -66,11 +79,10 @@ /* Other headers to be included */ #include <mbg_tgt.h> +#include <mbgutil.h> #include <gpsdefs.h> #include <pcpsdefs.h> -#include <pcpsutil.h> #include <mbgtime.h> -#include <mbgpccyc.h> #if defined( MBG_TGT_WIN32 ) #include <mbgsvcio.h> @@ -117,37 +129,79 @@ extern "C" { #define STR_ETX "\x3" + +_ext LONGLONG PerfFrequency; + + +static __mbg_inline +int64_t perf_cnt_to_us( MBG_PC_CYCLES cycles ) +{ + double d = ( (double) cycles * (double) ( HNS_PER_SEC / 10 ) / (double) PerfFrequency ); + + return (int64_t) d; + +} // perf_cnt_to_us + + + +static __mbg_inline +int64_t perf_cnt_to_hns( MBG_PC_CYCLES cycles ) +{ + double d = ( (double) cycles * (double) HNS_PER_SEC / (double) PerfFrequency ); + + return (int64_t) d; + +} // perf_cnt_to_hns + + + +static __mbg_inline +int64_t secs_to_hns( int64_t secs ) +{ + return secs * HNS_PER_SEC; + +} // secs_to_hns + + + +#if 1 // FIXME TODO + +#define _perf_cnt_to_us( _v ) perf_cnt_to_us( _v ) + +#define _perf_cnt_to_hns( _v ) perf_cnt_to_hns( _v ) + +#define _secs_to_hns( _v ) secs_to_hns( _v ) + +#else + #define _perf_cnt_to_us( _v ) \ - ( (double) (_v) * (double) ( HNS_PER_SEC / 10 ) / (double) PerfFrequency ) + ( (int64_t) ( (double) (_v) * (double) ( HNS_PER_SEC / 10 ) / (double) PerfFrequency ) ) #define _perf_cnt_to_hns( _v ) \ - ( (double) (_v) * (double) HNS_PER_SEC / (double) PerfFrequency ) + ( (int64_t) ( (double) (_v) * (double) HNS_PER_SEC / (double) PerfFrequency ) ) #define _secs_to_hns( _v ) \ ( ( (LONGLONG) (_v) ) * HNS_PER_SEC ) -#if defined( MBG_TGT_WIN32 ) +#endif -typedef struct -{ - REF_TIME rt; - MBG_PC_CYCLES cycles; -} REF_TIME_CYCLES; +#if defined( MBG_TGT_WIN32 ) #define MAX_TIMESTR_LEN 150 typedef struct { - char timestring[MAX_TIMESTR_LEN]; - REF_TIME sys_time_on_time; - MBG_PC_CYCLES sys_cycles_on_time; -} SERIAL_TIME_STRING; + char time_string[MAX_TIMESTR_LEN]; ///< A serial time string that has been received. + MBG_SYS_TIME_CYCLES sys_time_cyc_on_time; ///< The timestamp associated with the string's on-time character. + int32_t status; + +} TIME_STR_TIME_STAMP; // a pointer to a function that takes a time stamp of the system time -typedef int (*GET_REF_TIME_FNC)( REF_TIME *tp, LARGE_INTEGER *pli ); +typedef int GET_REF_TIME_FNC( MBG_SYS_TIME_CYCLES *p, int32_t *p_utc_offs ); #endif //MBG_TGT_WIN32 @@ -297,11 +351,13 @@ void mbg_pcps_tstamp64_to_filetime( FILETIME *p_ft, const uint64_t *p_ts64 ) void decode_str_wday_std( SYSTEMTIME *pt, const char *s ) ; void decode_str_time_std( SYSTEMTIME *pt, const char *s ) ; int decode_time_str( SYSTEMTIME *pt, long *utc_offs_sec, PCPS_TIME_STATUS_X *status, const char *ts, const MBG_SERCLOCK_CFG *pcfg ) ; - void timestring_to_ref_and_sys_filetime( SERIAL_TIME_STRING *sts, REF_TIME *st, REF_TIME *rt, const MBG_SERCLOCK_CFG *pcfg ) ; + void timestring_to_ref_and_sys_filetime( TIME_STR_TIME_STAMP *tsts, MBG_SYS_TIME *sys_ft, // FIXME naming +FT_DWL_EX *ref_ft, const MBG_SERCLOCK_CFG *p_cfg ) ; + void systemtime_to_pcps_time( PCPS_TIME *pt, const SYSTEMTIME *pst ) ; void pcps_time_to_systemtime( SYSTEMTIME *pst, const PCPS_TIME *pt ) ; - int pcps_time_to_ref_time( REF_TIME *rt, const PCPS_TIME *pt ) ; - void pcps_hr_time_to_ref_time( REF_TIME *rt, const PCPS_HR_TIME *hr_time ) ; + int pcps_time_to_ref_time( FT_DWL_EX *rt, const PCPS_TIME *pt ) ; + void pcps_hr_time_to_ref_time( FT_DWL_EX *rt, const PCPS_HR_TIME *hr_time ) ; void pcps_hr_time_to_pcps_time( PCPS_TIME *ptime, const PCPS_HR_TIME *hr_time ) ; /* ----- function prototypes end ----- */ diff --git a/mbglib/win32/wingetopt.c b/mbglib/win32/wingetopt.c index ed04c44..f7c7d7d 100644 --- a/mbglib/win32/wingetopt.c +++ b/mbglib/win32/wingetopt.c @@ -31,10 +31,10 @@ Code given out at the 1985 UNIFORUM conference in Dallas. errbuf[0] = c; errbuf[1] = '\n';\ fputs(argv[0], stderr);\ fputs(s, stderr);\ - fputc(c, stderr);} - //(void) write(2, argv[0], (unsigned)strlen(argv[0]));\ - //(void) write(2, s, (unsigned)strlen(s));\ - //(void) write(2, errbuf, 2);} + fputc(c, stderr);\ + /* (void) write(2, argv[0], (unsigned)strlen(argv[0])); */ \ + /* (void) write(2, s, (unsigned)strlen(s)); */ \ + /* (void) write(2, errbuf, 2); */ } int opterr = 1; int optind = 1; |