diff options
| author | Martin Burnicki <martin.burnicki@meinberg.de> | 2018-12-12 12:00:00 +0100 |
|---|---|---|
| committer | Martin Burnicki <martin.burnicki@meinberg.de> | 2018-12-12 12:00:00 +0100 |
| commit | 69b29e57d5f476e8d1d4ee913e135519fa992698 (patch) | |
| tree | 573ff4df4e4c067fce17de68438cd52a094d57d6 | |
| parent | 912230275b4e315f35c6e6bb52746ae994a65919 (diff) | |
| download | mbgtools-win-69b29e57d5f476e8d1d4ee913e135519fa992698.tar.gz mbgtools-win-69b29e57d5f476e8d1d4ee913e135519fa992698.zip | |
Update Source files corresponding to mbgtools-lx-4.2.0.
Add program dirs mbgsetsystime, mbgshowsignal, mbgxhrtime,
and test/mbgtcrcal and update associated project files.
Requires dkwin-3.08 or newer.
103 files changed, 52167 insertions, 9584 deletions
diff --git a/mbgctrl/mbgctrl.c b/mbgctrl/mbgctrl.c index edb6608..23eeec1 100644 --- a/mbgctrl/mbgctrl.c +++ b/mbgctrl/mbgctrl.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgctrl.c 1.22.1.14 2012/12/12 10:44:35Z martin TEST $ + * $Id: mbgctrl.c 1.26 2018/12/11 12:07:50Z martin REL_M $ * * Description: * Main file for mbgctrl program which sends commands and @@ -9,38 +9,24 @@ * * ----------------------------------------------------------------------- * $Log: mbgctrl.c $ - * Revision 1.22.1.14 2012/12/12 10:44:35Z martin - * Fixed wording of some message. - * Revision 1.22.1.13 2012/12/05 16:13:37 martin - * Chaged some faulty message texts. - * Revision 1.22.1.12 2012/10/16 10:44:20 martin - * Removed obsolete code. - * Revision 1.22.1.11 2012/07/12 08:37:47 martin - * Account for renamed structure. - * Revision 1.22.1.10 2012/06/01 18:46:21 martin - * Revision 1.22.1.9 2012/06/01 16:55:58 martin - * Account for library symbols moved to a new header. - * Revision 1.22.1.8 2011/09/26 15:58:58 martin - * Started modifications for PTP unicast master configuration. - * Warn if trying to handle serial port cfg but no serial port is supported. - * Modified program version handling. - * Use O_RDWR flag when opening a device. - * Account for modified library functions which can now - * optionally print the raw (hex) HR time stamp. - * Revision 1.22.1.7 2011/04/19 10:02:37 martin - * Syntax fix. - * Revision 1.22.1.6 2011/04/19 09:57:00 martin - * Untabbified and removed trailing spaces. - * Revision 1.22.1.5 2011/03/21 08:32:18 martin - * Fixed compiler warning. - * Revision 1.22.1.4 2011/03/03 10:01:00 daniel - * Support configuring PTP roles. - * Revision 1.22.1.3 2011/02/18 13:35:59 daniel - * Revision 1.22.1.2 2011/02/18 13:35:11 daniel - * Revision 1.22.1.1 2011/02/18 11:27:29 daniel - * Preliminary support for configuring PTP parameters incl. Unicast + * Revision 1.26 2018/12/11 12:07:50Z martin + * Fixed compiler warnings on Windows. + * Revision 1.25 2018/11/15 12:12:37Z martin + * Individual MBG_MICRO_VERSION codes are now obsolete. + * Revision 1.24 2018/09/21 16:12:23 martin + * Account for renamed library symbols. + * Revision 1.23 2017/07/05 19:10:07 martin + * New way to maintain version information. + * Support build under Windows. * Bugfix: accept parameter keyword only when substring is found at the * start of the parameter string. + * Support configuring PTP parameters incl. unicast + * Warn if trying to handle serial port cfg but no serial port is supported. + * Basic support for programmable pulse outputs, including pulse shift feature. + * Yet incomplete support for synthesizer output. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. * Revision 1.22 2009/09/29 14:58:18 martin * Unified and simplified parameter evaluation. * Updated version number to 3.4.0. @@ -114,14 +100,14 @@ #include <deviohlp.h> #include <pcpsmktm.h> #include <pcpsutil.h> -#include <parmpcps.h> -#include <parmgps.h> +#include <cfg_hlp.h> #include <myutil.h> #include <gpsutils.h> #include <cnv_wday.h> #include <toolutil.h> +#include <ptp_util.h> #include <lan_util.h> -//##+++++++++++++++++++++ #include <ptpdflts.h> +#include <str_util.h> // include system headers #include <stdio.h> @@ -131,17 +117,20 @@ #include <ctype.h> -#define MBG_MICRO_VERSION 0 #define MBG_FIRST_COPYRIGHT_YEAR 2001 #define MBG_LAST_COPYRIGHT_YEAR 0 // use default +#define RC_USAGE 1 static const char *pname = "mbgctrl"; static char *dev_name; static int err_unicast_nsupp; -static const char str_unknown[] = "(unknown)"; + +static const char str_spc_not[] = " not"; +static const char str_spc_not_supp[] = " (not supported)"; +static const char str_spc_wildcard[] = " (wildcard)"; static TZDL tzdl_utc = DEFAULT_TZDL_UTC; static TZDL tzdl_cet_cest = DEFAULT_TZDL_CET_CEST_EN; @@ -153,23 +142,118 @@ static const char tz_info_cet_cest[] = TZ_INFO_CET_CEST_EN; static const char tz_info_eet_eest[] = TZ_INFO_EET_EEST_EN; static const char *mode_names[N_STR_MODE] = DEFAULT_ENG_MODE_NAMES; -static const char *time_scale_name[N_MBG_TIME_SCALE] = MBG_TIME_SCALE_STRS; + +static const char *time_scale_names[N_MBG_TIME_SCALE] = MBG_TIME_SCALE_STRS; #define _get_time_scale_name( _i ) \ - ( ( (_i) < N_MBG_TIME_SCALE ) ? time_scale_name[_i] : str_unknown ) + ( ( (_i) < N_MBG_TIME_SCALE ) ? time_scale_names[_i] : str_unknown ) + +static const char * const pout_mode_names_eng[N_POUT_MODES] = DEFAULT_ENG_POUT_NAMES; + +#define _get_pout_mode_name( _i ) \ + ( ( (_i) < N_POUT_MODES ) ? pout_mode_names_eng[_i] : str_unknown ) static const char no_gps_cmd[] = "does not support GPS commands"; static const char no_tzdl[] = "does not support configurable time zone"; static const char no_tz[] = "does not support time zones"; +static const char no_synth[] = "has no synthesizer output"; static const char no_event_time[] = "does not support event times"; static const char no_enable_flags[] = "does not support enable flags"; static const char no_time_scale[] = "does not support a configurable time scale"; -static const char no_lan_intf[] = "does not provide a LAN interface"; +static const char no_lan_intf[] = "has no LAN interface"; static const char no_ptp[] = "does not provide PTP"; static const char no_cab_len[] = "does not support antenna signal delay compensation"; + +/** + * @brief A type used to pass print control flags to functions + * + * @see ::CTRL_FLAG_MASKS + */ +typedef int CTRL_FLAGS; + + +/** + * @brief flag masks used with ::CTRL_FLAGS + * + * @see ::CTRL_FLAGS + */ +enum CTRL_FLAG_MASKS +{ + CTRL_PRINT_ALL = 0x01, + CTRL_PRINT_NEWLINES = 0x02, + CTRL_PRINT_IDX = 0x04, + CTRL_PRINT_ERR = 0x08, + CTRL_PRINT_PLUS = 0x10, + CTRL_NOT_SUPP = 0x20 +}; + + +struct OPT_HANDLER_SPEC_S; + +typedef int HELP_FNC( MBG_DEV_HANDLE, const PCPS_DEV *, const struct OPT_HANDLER_SPEC_S *, CTRL_FLAGS ); +typedef int SET_FNC( MBG_DEV_HANDLE, const char *, int ); +typedef int SHOW_FNC( MBG_DEV_HANDLE, const struct OPT_HANDLER_SPEC_S *, const PCPS_DEV *, const char * ); + +typedef struct OPT_HANDLER_SPEC_S +{ + const char *cmd_name; + MBG_CHK_SUPP_FNC *chk_supp_fnc; + HELP_FNC *help_fnc; + SET_FNC *set_fnc; + SHOW_FNC *show_fnc; + const char *cmd_info; + const char *not_supp_msg; + uint32_t flags; ///< see ::OPT_FLAG_MASKS + +} OPT_HANDLER_SPEC; + + +enum OPT_FLAG_BITS +{ + OPT_SUPP_CMD_IDX_BIT, ///< e.g. COM0=, COM1=, etc. vs. TZ= + N_OPT_FLAG_BITS +}; + +enum OPT_FLAG_MASKS +{ + OPT_SUPP_CMD_IDX = ( 1UL << OPT_SUPP_CMD_IDX_BIT ) ///< see ::OPT_SUPP_CMD_IDX_BIT +}; + +OPT_HANDLER_SPEC ohs_pout = +{ + "POUT", // cmd_name + NULL, // chk_supp_fnc + NULL, // help_fnc + NULL, // set_fnc + NULL, // show_fnc + NULL, // cmd_info + NULL, // not_supp_msg + OPT_SUPP_CMD_IDX // flags +}; + + + +typedef struct +{ + int indent_1; + int indent_2; + int indent_3; + int comm_col_x; +} INDENTS; + +const INDENTS usage_indents = { 2, 4, 6, 30 }; +const INDENTS usage_indents_detailed = { 4, 6, 8, 30 }; +const INDENTS show_indents = { 2, 4, 0, 0 }; + + +#define SHOW_INDENT_1 " " +#define SHOW_INDENT_2 " " + + + typedef struct { const char *name; @@ -220,6 +304,7 @@ static const char *nw_prot_short[] = PTP_NW_PROT_STRS_SHORT; static const char *ptp_roles[] = PTP_ROLE_STRS; static const char *ptp_roles_short[] = PTP_ROLE_STRS_SHORT; +static const PTP_CLOCK_ID clock_id_wildcard = PTP_CLOCK_ID_WILDCARD; //##+++++++++++++++++++ // If unicast is not supported for a PTP device then the device is definitely @@ -231,6 +316,194 @@ static const char *ptp_roles_short[] = PTP_ROLE_STRS_SHORT; ( ( (_i) < N_PTP_ROLES ) ? ptp_roles_short[_i] : str_unknown ) +static const char pout_name_mode[] = "MODE"; +static const char pout_name_len[] = "LEN"; +static const char pout_name_inv[] = "INV"; +static const char pout_name_ois[] = "OIS"; +static const char pout_name_shift[] = "SHIFT"; + + + + + +static /*HDR*/ +__attribute__( ( format( printf, 4, 5 ) ) ) +int usage_line( const INDENTS *p_ind, const OPT_HANDLER_SPEC *p_opt, + const char *cmd_parm, const char *cmd_comment_fmt, ... ) +{ + int n = 0; + + // print left margin, if not 0 + if ( p_ind->indent_1 ) + n += printf( "%*s", p_ind->indent_1, str_empty ); + + // print command name + if ( p_opt ) + n += printf( "%s", p_opt->cmd_name ); + + // print the command parameters, if specified + if ( cmd_parm ) + { + if ( p_opt && ( p_opt->flags & OPT_SUPP_CMD_IDX ) ) + n+= printf( "%s", "<n>" ); + + n += printf( "=%s", cmd_parm ); + } + + // print command comment which can be a format string + // expecting additional parameters + if ( cmd_comment_fmt ) + { + va_list arg_list; + + // indent the comment string + if ( p_ind->indent_2 ) + { + int w = p_ind->indent_2 - n; + + while ( w < 0 ) + w += 8; + + n += printf( "%*s", w, str_empty ); + } + + va_start( arg_list, cmd_comment_fmt ); + n += vprintf( cmd_comment_fmt, arg_list ); + va_end( arg_list ); + } + + n += printf( "\n" ); + + return n; + +} // usage_line + + + +static /*HDR*/ +int print_indent( int i ) +{ + int n = printf( "%*s", i, str_empty ); + + return n; + +} // print_indent + + + +static /*HDR*/ +__attribute__( ( format( printf, 2, 3 ) ) ) +int usage_note( int indent, const char *fmt, ... ) +{ + // print left margin, if not 0 + int n = print_indent( indent ); + + if ( fmt ) + { + va_list arg_list; + + va_start( arg_list, fmt ); + n += vprintf( fmt, arg_list ); + n += printf( "\n" ); + va_end( arg_list ); + } + + return n; + +} // usage_note + + + +typedef const char *(STR_FNC)( int idx ); + + +static /*HDR*/ +void print_bit_mask_list( const char *info_1, const char *info_2, uint32_t supp_mask, + int n_known, const char * const names[], STR_FNC *s_fnc, + int inst_idx, CTRL_FLAGS ctrl_flags, const INDENTS *p_ind ) +{ + const char *str_s_fnc = s_fnc ? s_fnc( inst_idx ) : str_empty; + + print_indent( p_ind->indent_2 ); + + if ( ctrl_flags & CTRL_PRINT_ALL ) + { + supp_mask = ( 1UL << n_known ) - 1; + + if ( supp_mask ) + printf( "Known %s%s: ", info_1, str_s_fnc ); + else + printf( "No %s%s known.", info_1, str_s_fnc ); + } + else + { + if ( supp_mask ) + { + printf( "%s", info_1 ); + + if ( info_2 ) + printf( " %s", info_2 ); + + #if defined( DEBUG ) + printf( " (%04lX)", (ulong) supp_mask ); + #endif + + printf( ":" ); + } + else + { + printf( "No %s.", info_1 ); + + if ( info_2 ) + printf( " %s", info_2 ); + + printf( "." ); + } + } + + + if ( supp_mask ) + { + int n_printed = 0; + int i; + const char *str_sep = ( ctrl_flags & CTRL_PRINT_PLUS ) ? "+" : ", "; + + for ( i = 0; i < n_known; i++ ) + { + const char *cp; + + if ( ( supp_mask & ( 1UL << i ) ) == 0 ) + continue; + + if ( names ) + cp = names[i]; + else + if ( s_fnc ) + cp = s_fnc( i ); + else + cp = str_empty; + + if ( ctrl_flags & ( CTRL_PRINT_NEWLINES | CTRL_PRINT_IDX ) ) + { + printf( "\n" ); + print_indent( p_ind->indent_3 ); + + if ( ctrl_flags & CTRL_PRINT_IDX ) + printf( "%i: ", i ); + + printf( "%s", cp ); + } + else + printf( "%s%s", n_printed ? str_sep : str_empty, cp ); + + n_printed++; + } + } + + printf( "\n" ); + +} // print_bit_mask_list + static /*HDR*/ @@ -247,7 +520,7 @@ int set_tz_code( MBG_DEV_HANDLE dh, PCPS_TZCODE tzcode, const char *s ) { int rc = mbg_set_tzcode( dh, &tzcode ); - if ( mbg_ioctl_err( rc, "mbg_set_tzcode" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_tzcode" ) ) return rc; printf( "The clock's time zone setting has been set to %s.\n", s ); @@ -263,7 +536,7 @@ int set_gps_tzdl( MBG_DEV_HANDLE dh, const TZDL *tzdl, const char *info ) { int rc = mbg_set_gps_tzdl( dh, tzdl ); - if ( mbg_ioctl_err( rc, "set_gps_tzdl" ) ) + if ( mbg_cond_err_msg( rc, "set_gps_tzdl" ) ) return rc; if ( info ) @@ -304,7 +577,7 @@ int set_timezone( MBG_DEV_HANDLE dh, const char *tz_name, const PCPS_DEV *p_dev else { printf( "** Unknown timezone name %s\n", tz_name ); - rc = 1; + rc = RC_USAGE; } if ( tz_info ) @@ -330,7 +603,7 @@ int show_tzdl_offs( MBG_DEV_HANDLE dh, const char *info ) TZDL tzdl; int rc = mbg_get_gps_tzdl( dh, &tzdl ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_tzdl" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_gps_tzdl" ) ) return rc; printf( "%s timezone offset: UTC%+lis", info, (long) tzdl.offs ); @@ -363,6 +636,60 @@ int set_tzdl_offs( MBG_DEV_HANDLE dh, const char *s ) static /*HDR*/ +int show_synth( MBG_DEV_HANDLE dh, const char *info ) +{ + SYNTH synth; + int rc = mbg_get_synth( dh, &synth ); + + if ( mbg_cond_err_msg( rc, "mbg_get_synth" ) ) + return rc; + + printf( "%s synthesizer settings: freq %i.%iE%i Hz, phase %+i.%i deg", info, + synth.freq / 10, synth.freq % 10, synth.range, + synth.phase / 10, abs( synth.phase ) % 10 ); + +/* + int16_t freq; ///< four digits used; scale: 0.1 Hz; e.g. 1234 -> 123.4 Hz + int16_t range; ///< scale factor for freq; 0..::MAX_SYNTH_RANGE + int16_t phase; ///< -::MAX_SYNTH_PHASE..+::MAX_SYNTH_PHASE; >0 -> pulses later +*/ + return MBG_SUCCESS; + +} // show_synth + + + +static /*HDR*/ +int set_synth( MBG_DEV_HANDLE dh, const char *s ) +{ + SYNTH synth = { 0 }; + char *cp; + + long freq = strtol( s, &cp, 10 ) * 10; + + if ( *cp == '.' ) + { + long frac = strtol( ++cp, NULL, 10 ); + if ( frac < 0 || frac > 9 ) + goto fail; + + freq += frac; + } + + synth.freq = (int16_t) freq; + synth.range = 0; + synth.phase = 0; + + return mbg_set_synth( dh, &synth ); + +fail: + return MBG_ERR_INV_PARM; + +} // set_synth + + + +static /*HDR*/ int show_lan_intf( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *info ) { IP4_SETTINGS ip4_settings; @@ -370,7 +697,7 @@ int show_lan_intf( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *info ) int rc = mbg_get_ip4_settings( dh, &ip4_settings ); - if ( mbg_ioctl_err( rc, "mbg_get_ip4_settings" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_ip4_settings" ) ) return rc; printf( "On-board LAN interface settings:" ); @@ -401,31 +728,59 @@ int show_lan_intf( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *info ) static /*HDR*/ +const char *intv_str( int i ) +{ + static char s[20]; + + int abs_i = abs( i ); + ulong ul; + + // Currently the valid range is [-7:+7] + if ( abs_i > 7 ) + return str_empty; + + ul = 1UL << abs_i; + + snprintf_safe( s, sizeof( s ), " (%s%lu s)", ( i < 0 ) ? "1/" : str_empty, ul ); + + return s; + +} // intv_str + + + +static /*HDR*/ int show_ptp_cfg( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *info ) { ALL_PTP_CFG_INFO all_ptp_cfg_info; + PTP_CFG_INFO *pi = &all_ptp_cfg_info.ptp_cfg_info; + PTP_CFG_SETTINGS *ps = &pi->settings; char ws[256]; int unicast_supported; int idx; int rc = mbg_get_all_ptp_cfg_info( dh, &all_ptp_cfg_info ); - if ( mbg_ioctl_err( rc, "mbg_get_all_ptp_cfg_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_all_ptp_cfg_info" ) ) return rc; - unicast_supported = ( all_ptp_cfg_info.ptp_cfg_info.supp_flags & PTP_CFG_MSK_SUPPORT_PTP_UNICAST ) != 0; + unicast_supported = ( pi->supp_flags & PTP_CFG_MSK_SUPPORT_PTP_UNICAST ) != 0; printf( "\nPTP configuration:\n"); - idx = all_ptp_cfg_info.ptp_cfg_info.settings.ptp_role; + idx = ps->ptp_role; printf( " PTP Role : %s (%s)\n", _ptp_role_name_short( idx ), _ptp_role_name( idx ) ); - idx = all_ptp_cfg_info.ptp_cfg_info.settings.nw_prot; + idx = ps->nw_prot; printf( " Network Protocol: %s (%s)\n", nw_prot_short[idx], nw_prot[idx] ); - printf( " Delay Mechanism : %s\n", delay_mech[all_ptp_cfg_info.ptp_cfg_info.settings.delay_mech] ); - printf( " Domain Number : %d\n", all_ptp_cfg_info.ptp_cfg_info.settings.domain_number ); - printf( " V1 HW Compat. : %d\n", ( all_ptp_cfg_info.ptp_cfg_info.settings.flags & PTP_CFG_MSK_V1_HW_COMPAT ) ? 1 : 0 ); + printf( " Delay Mechanism : %s\n", delay_mech[ps->delay_mech] ); + printf( " Domain Number : %d\n", ps->domain_number ); + printf( " V1 HW Compat. : %d\n", ( ps->flags & PTP_CFG_MSK_V1_HW_COMPAT ) ? 1 : 0 ); + + printf( " Sync Msg Intv. : % i%s\n", ps->sync_intv, intv_str( ps->sync_intv) ); + printf( " Ann. Msg Intv. : % i%s\n", ps->ann_intv, intv_str( ps->ann_intv ) ); + printf( " Dly. Req. Intv. : % i%s\n", ps->delay_req_intv, intv_str( ps->delay_req_intv ) ); if ( unicast_supported ) { @@ -436,25 +791,31 @@ int show_ptp_cfg( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *info ) { PTP_UC_MASTER_SETTINGS *p = &all_ptp_cfg_info.all_ptp_uc_master_info_idx[i].info.settings; - printf( "\nPTP unicast master" ); + printf( "\nConfigured PTP unicast master" ); if ( p_uc_limits->n_supp_master > 1 ) printf( " %i", i ); + if ( ps->ptp_role == PTP_ROLE_MULTICAST_SLAVE ) + printf( " (not used for this role)" ); + printf( ":\n"); printf( " GM Host: %s\n", p->gm_host ); snprint_octets( ws, sizeof( ws ), p->gm_clock_id.b, sizeof( p->gm_clock_id.b ), MAC_SEP_CHAR, NULL ); - printf( " GM Clock ID: %s\n", ws ); + printf( " GM Clock ID: %s%s\n", ws, + ( memcmp( &p->gm_clock_id, &clock_id_wildcard, sizeof( p->gm_clock_id ) ) == 0 ) ? + str_spc_wildcard : str_empty ); - printf( " GM Port ID: %d\n\n", p->gm_port_id ); - printf( " Sync Msg Interval [2^x s]: %i\n", p->sync_intv ); - printf( " Ann. Msg Interval [2^x s]: %i\n", p->ann_intv ); - printf( " DelReq Msg Interval [2^x s]: %i\n", p->delay_req_intv ); - printf( " Message Duration: %i s\n", p->message_duration ); - } + printf( " GM Port ID: %d%s\n", p->gm_port_id, + ( p->gm_port_id == PTP_PORT_ID_WILDCARD ) ? str_spc_wildcard : str_empty ); + printf( " Sync Msg Intv. : % i%s\n", p->sync_intv, intv_str( p->sync_intv ) ); + printf( " Ann. Msg Intv. : % i%s\n", p->ann_intv, intv_str( p->ann_intv ) ); + printf( " Dly. Req. Intv. : % i%s\n", p->delay_req_intv, intv_str( p->delay_req_intv ) ); + printf( " Message Duration: %i s\n", p->message_duration ); + } } return MBG_SUCCESS; @@ -512,9 +873,9 @@ static /*HDR*/ * @param p A pointer to a (char *) which is set to the beginning * of the value part of a parameter string * - * @return <0 Syntax error, i.e. missing colon - * 0 No error. If parameter has been found then *p set - * to the parameter value, else to NULL. + * @return ::MBG_SUCCESS on success. If parameter has been found then + * @p *p is set to the parameter value, else to NULL. + * ::MBG_ERR_PARM_FMT if syntax error, i.e. missing colon. */ int chk_parm_name( const char *arg, const char *id, char **p ) { @@ -525,7 +886,7 @@ int chk_parm_name( const char *arg, const char *id, char **p ) cp += strlen( id ); if ( *cp != ':' ) - return -1; + return MBG_ERR_PARM_FMT; cp++; } @@ -533,7 +894,7 @@ int chk_parm_name( const char *arg, const char *id, char **p ) if ( p ) *p = cp; // may be NULL - return 0; + return MBG_SUCCESS; } // chk_parm_name @@ -607,8 +968,8 @@ int chk_int16_parm( const char *arg, const char *id, int16_t *p, int16_t range_m char *cp; int idx = chk_parm_name( arg, id, &cp ); - if ( idx < 0 ) // parameter error - return -1; + if ( mbg_rc_is_error( idx ) ) // parameter error + return idx; if ( cp ) // parameter found { @@ -621,7 +982,7 @@ int chk_int16_parm( const char *arg, const char *id, int16_t *p, int16_t range_m if ( ( tmp < range_min ) || ( tmp > range_max ) ) { printf( "error: %s %i out of range (%i..%i)\n", info, tmp, range_min, range_max ); - return -1; + return MBG_ERR_RANGE; } *p = tmp; @@ -638,7 +999,7 @@ int chk_int16_parm( const char *arg, const char *id, int16_t *p, int16_t range_m static /*HDR*/ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) { - ALL_PTP_CFG_INFO all_ptp_cfg_info; + ALL_PTP_CFG_INFO all_ptp_cfg_info = { { { 0 } } }; ALL_PTP_CFG_INFO prv_all_ptp_cfg_info; PTP_CFG_INFO *p_info; PTP_CFG_SETTINGS *p_settings; @@ -652,8 +1013,7 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) int idx; int unicast_supported; int uc_master_idx = 0; - int16_t tmp_int16; - + const char *err_info = NULL; int rc = mbg_get_all_ptp_cfg_info( dh, &all_ptp_cfg_info ); if ( rc < 0 ) @@ -670,7 +1030,7 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) unicast_supported = ( p_info->supp_flags & PTP_CFG_MSK_SUPPORT_PTP_UNICAST ) != 0; p_uc_limits = &all_ptp_cfg_info.ptp_uc_master_cfg_limits; - // The pointers below need to be updated wnenever uc_master_idx is changed + // The pointers below need to be updated whenever uc_master_idx is changed p_uc_info = &all_ptp_cfg_info.all_ptp_uc_master_info_idx[uc_master_idx].info; p_uc_settings = &p_uc_info->settings; @@ -682,8 +1042,10 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) p_settings->nw_prot = idx; else if ( idx < -1 ) + { + err_info = ptp_name_net; goto fail; - + } // Delay Mechanism idx = chk_tbl_parm( arg, ptp_name_del, delay_mech, N_PTP_DELAY_MECH, p_info->supp_delay_mech, "delay mechanism" ); @@ -692,19 +1054,25 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) p_settings->delay_mech = idx; else if ( idx < -1 ) + { + err_info = ptp_name_del; goto fail; + } // Domain Number idx = chk_parm_name( arg, ptp_name_dom, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error + { + err_info = ptp_name_dom; goto fail; + } if ( cp ) // parameter found { idx = atoi( cp ); - //##+++++ must check range!! + // TODO Must check range!! p_settings->domain_number = idx; } @@ -712,8 +1080,11 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) // V1 Hardware compatibility flag idx = chk_parm_name( arg, ptp_name_v1, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error + { + err_info = ptp_name_v1; goto fail; + } if ( cp ) // parameter found { @@ -739,7 +1110,7 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) //---- unicast stuff ---- // PTP role - supp_mask = _get_supp_ptp_role_idx_msk( p_info->supp_flags ); + supp_mask = get_supp_ptp_role_mask( p_info->supp_flags ); idx = chk_tbl_parm( arg, ptp_name_role, ptp_roles_short, N_PTP_ROLES, supp_mask, "PTP role" ); if ( idx >= 0 ) // valid parameter found @@ -751,14 +1122,20 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) } else if ( idx < -1 ) // parameter error + { + err_info = ptp_name_role; goto fail; + } // GM Host idx = chk_parm_name( arg, ptp_name_gmip, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error + { + err_info = ptp_name_gmip; goto fail; + } if ( cp ) // parameter found { @@ -768,7 +1145,7 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) { // currently IP addresses are accepted only, so check for // a valid IPv4 address - if ( str_to_ip4_addr( &ip4addr, cp ) ) + if ( str_to_ip4_addr( &ip4addr, cp ) > 0 ) { snprint_ip4_addr( ws, sizeof( ws ), &ip4addr, NULL ); printf( " GM IP Address: %s\n", ws ); @@ -777,7 +1154,10 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) strcpy( p_uc_settings->gm_host, ws ); } else + { + err_info = ptp_name_gmip; goto fail; + } } } @@ -785,8 +1165,11 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) // GM Clock ID idx = chk_parm_name( arg, ptp_name_gmid, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error + { + err_info = ptp_name_gmid; goto fail; + } if ( cp ) // parameter found { @@ -795,21 +1178,27 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) else { PTP_CLOCK_ID gm_clock_id; - idx = str_to_octets( gm_clock_id.b, sizeof( gm_clock_id.b ), cp ); + + // Check if specified GM ID is wildcard. + if ( *cp == '*' ) // TODO check if next char is separator + { + gm_clock_id = clock_id_wildcard; + idx = sizeof( gm_clock_id ); + } + else + idx = str_to_octets( gm_clock_id.b, sizeof( gm_clock_id.b ), cp ); if ( idx != sizeof( gm_clock_id ) ) { printf( "Syntax error in specified GM clock ID\n" ); goto fail; } - else - { - p_uc_settings->gm_clock_id = gm_clock_id; - snprint_octets( ws, sizeof( ws ), p_uc_settings->gm_clock_id.b, - sizeof( p_uc_settings->gm_clock_id.b ), MAC_SEP_CHAR, NULL ); - printf( " setting GM Clock ID: %s\n", ws ); - } + p_uc_settings->gm_clock_id = gm_clock_id; + + snprint_octets( ws, sizeof( ws ), p_uc_settings->gm_clock_id.b, + sizeof( p_uc_settings->gm_clock_id.b ), MAC_SEP_CHAR, NULL ); + printf( " setting GM Clock ID: %s\n", ws ); } } @@ -817,8 +1206,11 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) // GM Target Port ID idx = chk_parm_name( arg, ptp_name_pid, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error + { + err_info = ptp_name_pid; goto fail; + } if ( cp ) // parameter found { @@ -826,75 +1218,87 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) err_unicast_nsupp = 1; else { - p_uc_settings->gm_port_id = strtoul( cp, NULL, 0 ); - printf( " setting GM port id: %d\n", p_uc_settings->gm_port_id ); + // Check if specified Port ID is wildcard. + if ( *cp == '*' ) // TODO check if next char is separator + p_uc_settings->gm_port_id = PTP_PORT_ID_WILDCARD; + else + p_uc_settings->gm_port_id = (PTP_PORT_ID) strtoul( cp, NULL, 0 ); + + printf( " setting GM port id: %d%s\n", p_uc_settings->gm_port_id, + ( p_uc_settings->gm_port_id == PTP_PORT_ID_WILDCARD ) ? str_spc_wildcard : str_empty ); } } // Sync Message Rate - idx = chk_int16_parm( arg, ptp_name_smi, &p_uc_settings->sync_intv, + idx = chk_int16_parm( arg, ptp_name_smi, + ( p_settings->ptp_role == PTP_ROLE_MULTICAST_SLAVE ) ? + &p_settings->sync_intv : &p_uc_settings->sync_intv, p_uc_limits->sync_intv_min, p_uc_limits->sync_intv_max, - unicast_supported, "sync intv." ); + 1, "sync intv." ); if ( idx < 0 ) + { + err_info = ptp_name_smi; goto fail; + } // Announce Message Rate - idx = chk_int16_parm( arg, ptp_name_ami, &p_uc_settings->ann_intv, + idx = chk_int16_parm( arg, ptp_name_ami, + ( p_settings->ptp_role == PTP_ROLE_MULTICAST_SLAVE ) ? + &p_settings->ann_intv : &p_uc_settings->ann_intv, p_uc_limits->ann_intv_min, p_uc_limits->ann_intv_max, - unicast_supported, "ann. intv." ); + 1, "ann. intv." ); if ( idx < 0 ) + { + err_info = ptp_name_ami; goto fail; + } - // Delay Message Rate - idx = chk_int16_parm( arg, ptp_name_dri, &p_uc_settings->delay_req_intv, + // Delay Request Interval Rate + idx = chk_int16_parm( arg, ptp_name_dri, + ( p_settings->ptp_role == PTP_ROLE_MULTICAST_SLAVE ) ? + &p_settings->delay_req_intv : &p_uc_settings->delay_req_intv, p_uc_limits->delay_req_intv_min, p_uc_limits->delay_req_intv_max, - unicast_supported, "delay req. intv." ); + 1, "delay req. intv." ); if ( idx < 0 ) + { + err_info = ptp_name_dri; goto fail; + } - // Message Duration //##++++ TODO: should this be added to the structure - tmp_int16 = p_uc_settings->message_duration; - idx = chk_int16_parm( arg, ptp_name_dur, &tmp_int16, + + // Message Duration + idx = chk_int16_parm( arg, ptp_name_dur, (int16_t *) &p_uc_settings->message_duration, PTP_UC_MSG_DURATION_MIN, PTP_UC_MSG_DURATION_MAX, unicast_supported, "msg. duration" ); if ( idx < 0 ) + { + err_info = ptp_name_dur; goto fail; - - p_uc_settings->message_duration = tmp_int16; - -#if 0 //##++++++++++++ - - cp = strstr( arg, ptp_name_dur ); - - if ( cp != NULL ) - { - l = strlen( ptp_name_dur ); - - if ( *(cp+l) != ':' ) - goto fail; // parameter syntax error: name not followed by colon - - l++; - - ptp_unicast_settings.message_duration = atoi( cp+l ); - printf( " setting message duration: %i seconds\n", ptp_unicast_settings.message_duration ); - } -#endif + } - rc = mbg_set_ptp_cfg_settings( dh, p_settings ); + if ( memcmp( &all_ptp_cfg_info, &prv_all_ptp_cfg_info, sizeof( all_ptp_cfg_info ) ) != 0 ) + { + rc = mbg_save_all_ptp_cfg_info( dh, &all_ptp_cfg_info ); - if ( mbg_ioctl_err( rc, "mbg_set_ptp_cfg_settings" ) ) - return rc; + if ( mbg_cond_err_msg( rc, "mbg_save_all_ptp_cfg_info" ) ) + return rc; + } return MBG_SUCCESS; fail: - printf( "Syntax error in argument!\n" ); + printf( "Invalid parameter in argument" ); + + if ( err_info ) + printf( " %s", err_info ); + + printf( "!\n" ); return MBG_ERR_CFG; @@ -905,8 +1309,8 @@ fail: static /*HDR*/ int ip4_check_parm( const char *s, IP4_INFO *p ) { - int l = strlen( p->name ); - int n; + size_t l = strlen( p->name ); + size_t n; if ( strncmp( s, p->name, l ) != 0 ) return 0; // parameter does not match @@ -921,7 +1325,9 @@ int ip4_check_parm( const char *s, IP4_INFO *p ) if ( n < 0 ) goto fail; // parameter syntax error: failed to convert numeric address - return n + l; //##++++++ needs to be verified + n += l; + + return _int_from_size_t( n ); fail: return MBG_ERR_CFG; @@ -947,7 +1353,7 @@ int set_lan_intf( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) int rc = mbg_get_ip4_settings( dh, &prv_ip4_settings ); - if ( mbg_ioctl_err( rc, "mbg_get_ip4_settings" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_ip4_settings" ) ) return rc; if ( strcmp( arg, "DHCP" ) == 0 ) @@ -1028,7 +1434,7 @@ done: // now check static configuration save: rc = mbg_set_ip4_settings( dh, &ip4_settings ); - if ( mbg_ioctl_err( rc, "mbg_set_ip4_settings" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_ip4_settings" ) ) return rc; return MBG_SUCCESS; @@ -1078,7 +1484,7 @@ int set_gps_pos( MBG_DEV_HANDLE dh, const char *gp ) rc = mbg_set_gps_pos_lla ( dh, new_pos_lla ); - if ( mbg_ioctl_err( rc, "mbg_set_gps_pos_lla" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_gps_pos_lla" ) ) return rc; printf( "The clock's receiver position has been set to lat=%+.4f, lon=%+.4f, alt=%.0fm\n", @@ -1119,7 +1525,7 @@ int set_date_time( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, { rc = mbg_get_time( dh, &u.t ); - if ( mbg_ioctl_err( rc, "mbg_get_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_time" ) ) return rc; } @@ -1205,7 +1611,7 @@ int set_date_time( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, rc = mbg_set_gps_time( dh, &ttm ); - if ( mbg_ioctl_err( rc, "mbg_set_gps_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_gps_time" ) ) return rc; } else // is not a GPS card @@ -1241,7 +1647,7 @@ int set_date_time( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, rc = mbg_set_time( dh, &u.stime ); - if ( mbg_ioctl_err( rc, "mbg_set_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_time" ) ) return rc; } @@ -1254,26 +1660,34 @@ int set_date_time( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, static /*HDR*/ -void check_setup_receiver_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, - RECEIVER_INFO *p_ri ) +int check_setup_receiver_info( MBG_DEV_HANDLE dh, RECEIVER_INFO *p_ri ) { + int rc = MBG_SUCCESS; + // Set up the RECEIVER_INFO structure only if this has not been done // before. Check the ticks_per_sec field to see if the structure // has already been set up or not. - if ( p_ri->ticks_per_sec == 0 ) - mbg_setup_receiver_info( dh, p_dev, p_ri ); + if ( p_ri->ticks_per_sec == 0 && p_ri->model_code == 0 ) + { + rc = mbg_setup_receiver_info( dh, NULL, p_ri ); + mbg_cond_err_msg( rc, "mbg_setup_receiver_info" ); + } + + return rc; } // check_setup_receiver_info static /*HDR*/ +// returns a negative error code on failure, or the number of supported COM ports on success int check_get_receiver_port_cfg( MBG_DEV_HANDLE dh, RECEIVER_PORT_CFG *p_rpcfg, const PCPS_DEV *p_dev, RECEIVER_INFO *p_ri ) { - int rc = MBG_SUCCESS; + int rc = check_setup_receiver_info( dh, p_ri ); - check_setup_receiver_info( dh, p_dev, p_ri ); + if ( mbg_rc_is_error( rc ) ) + goto out; // Set up the RECEIVER_PORT_CFG structure only if this has not been done // before. Check whether the number of ports is > 0 and the first port's @@ -1282,10 +1696,13 @@ int check_get_receiver_port_cfg( MBG_DEV_HANDLE dh, RECEIVER_PORT_CFG *p_rpcfg, ( p_rpcfg->pii[0].port_info.port_settings.parm.baud_rate == 0 ) ) { rc = mbg_get_serial_settings( dh, p_dev, p_rpcfg, p_ri ); - - mbg_ioctl_err( rc, "mbg_get_serial_settings" ); + mbg_cond_err_msg( rc, "mbg_get_serial_settings" ); } + if ( mbg_rc_is_success( rc ) ) + rc = p_ri->n_com_ports; + +out: return rc; } // check_get_receiver_port_cfg @@ -1404,7 +1821,7 @@ int save_serial_settings( MBG_DEV_HANDLE dh, unsigned int port_num, const char * // load current settings and supported settings rc = mbg_get_serial_settings( dh, p_dev, &rpcfg, p_ri ); - if ( mbg_ioctl_err( rc, "mbg_get_serial_settings" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_serial_settings" ) ) return rc; @@ -1442,7 +1859,7 @@ int save_serial_settings( MBG_DEV_HANDLE dh, unsigned int port_num, const char * ul = strtoul( cp, &p_tail, 10 ); if ( p_tail != cp ) - p_ps->str_type = ul; + p_ps->str_type = (uint8_t) ul; // TODO check range ? cp = p_tail; @@ -1455,7 +1872,7 @@ int save_serial_settings( MBG_DEV_HANDLE dh, unsigned int port_num, const char * ul = strtoul( cp, &p_tail, 10 ); if ( p_tail != cp ) - p_ps->mode = ul; + p_ps->mode = (uint8_t) ul; // TODO check range ? done_parm_str: @@ -1472,7 +1889,7 @@ done_parm_str: // save new parameters rc = mbg_save_serial_settings( dh, p_dev, &rpcfg, port_num ); - if ( mbg_ioctl_err( rc, "mbg_save_serial_settings" ) ) + if ( mbg_cond_err_msg( rc, "mbg_save_serial_settings" ) ) return rc; @@ -1491,6 +1908,479 @@ invalid: static /*HDR*/ +// returns a negative error code on failure, or the number of supported programmable pulse outputs on success +int check_get_pout_cfg( MBG_DEV_HANDLE dh, ALL_POUT_INFO_IDX api, RECEIVER_INFO *p_ri ) +{ + int rc = check_setup_receiver_info( dh, p_ri ); + + // Set up the ALL_POUT_INFO_IDX structure only if this has not been done + // before. Check whether the number of ports is > 0 and the first port's + // baud rate is still 0 to see if the structure has already been set up. + if ( ( p_ri->n_prg_out > 0 ) && + ( api[0].pout_info.supp_modes == 0 ) ) + { + rc = mbg_get_gps_all_pout_info( dh, api, p_ri ); + mbg_cond_err_msg( rc, "mbg_get_gps_all_pout_info" ); + } + + if ( mbg_rc_is_success( rc ) ) + rc = p_ri->n_prg_out; + + return rc; + +} // check_get_pout_cfg + + + +static /*HDR*/ +int help_pout_arg( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, + const OPT_HANDLER_SPEC *p_opt, CTRL_FLAGS ctrl_flags ) +{ + const INDENTS *p_ind = &usage_indents; + const INDENTS *p_ind_detailed = &usage_indents_detailed; + int rc = MBG_SUCCESS; + int i; + + usage_line( p_ind, p_opt, NULL, "Show settings of the programmable output(s)" ); + usage_line( p_ind, p_opt, "MODE:<m>[,LEN:<l>][,INV:<i>][,OIS:<o>][,SHIFT:<s>]", "Configure programmable output <n>" ); // ### TODO + + printf( "\n" + " where:\n" ); + + printf( " MODE:<m> Specifies the programmable output mode with index <m>, see mbgctrl -?.\n" + " Please note that subsequent parameters may only be appropriate for specific modes.\n\n" ); + + printf( " LEN:<l> Specifies the pulse lenght for modes that support this.\n" + " <l> is an integer value in 10 ms units, i.e. <l> = 20 yields 200 ms.\n\n" ); + + printf( " INV:<i> \"Inverted\" flag specifying if the output level is to be inverted,\n" + " if the output supports this.\n" + " Values for <i>: 1 invert output level, 0 don't invert.\n\n" ); + + printf( " OIS:<o> \"Only If Sync\" flag specifying if the output is to be enabled ONLY\n" + " while the device is synchronized, if the output supports this.\n" + " Values for <o>: 1 enable this feature, 0 disable this feature\n" + " NOTE: This overrides the Enable Flags settings (parameter \"EF\").\n" + " The output is enabled ONLY when the device state changes to \"synchronized\"\n" + " after power-up, and is disabled again when the device enters holdover mode,\n" + " i.e. the reference signal is lost.\n\n" ); + + printf( " SHIFT:<s> Specifies a phase shift of the output slope, if the output supports this.\n" + " <s> is an integer value, in nanoseconds.\n" + " The maximum range is %+li to %+li ns,\n" + " corresponding to %+li to %+li ms.\n" + " The effective resolution depends on the resolution of the device's internal clock,\n" + " which may be e.g. 10 or 20 ns, depending on the device type. See mbgctrl -?.\n\n", + (long) DEFAULT_POUT_PULSE_SHIFT_MIN, (long) DEFAULT_POUT_PULSE_SHIFT_MAX, + (long) DEFAULT_POUT_PULSE_SHIFT_MIN / 1000L, (long) DEFAULT_POUT_PULSE_SHIFT_MAX / 1000L ); + + + if ( dh != MBG_INVALID_DEV_HANDLE ) + { + RECEIVER_INFO ri = { 0 }; + ALL_POUT_INFO_IDX api = { { 0 } }; + int n_pout; + + rc = check_get_pout_cfg( dh, api, &ri ); + + if ( mbg_rc_is_error( rc ) ) + goto out; + + n_pout = rc; + + for ( i = 0; i < n_pout; i++ ) + { + const POUT_INFO *pi = &api[i].pout_info; + + printf( "%*s", p_ind->indent_2, str_empty ); + printf( "Programmable output %i:\n", i ); + + print_bit_mask_list( "Supported modes", NULL, pi->supp_modes, + N_POUT_MODES, pout_mode_names_eng, NULL, 0, + ctrl_flags | CTRL_PRINT_IDX, p_ind_detailed ); + + // ### TODO evaluate more properties + usage_note( p_ind_detailed->indent_2, "Output level can%s be inverted.", + ( pi->flags & POUT_NOT_INVERTIBLE ) ? str_spc_not : str_empty ); + + if ( pi->flags & POUT_FIXED_PULSE_LEN ) + usage_note( p_ind_detailed->indent_2, "Pulse length is fixed and can't be changed." ); + + if ( pi->flags & POUT_SUPP_PULSE_SHIFT ) + usage_note( p_ind_detailed->indent_2, "Output supports pulse shift with resolution %u ns.", + pi->pulse_shift_res ); + + printf( "\n" ); + } + } + else + { +#if 0 // ### TODO + print_bit_mask_list( "modes", str_supp_by_dev, tsi.supp_scales, + N_MBG_TIME_SCALE, time_scale_names, NULL, ctrl_flags | CTRL_PRINT_IDX ); +#endif + } + +out: + return rc; + +} // help_pout_arg + + + +static /*HDR*/ +int eval_pout( MBG_DEV_HANDLE dh, const char *s, int inst_num ) +{ + RECEIVER_INFO ri = { 0 }; + ALL_POUT_INFO_IDX api = { { 0 } }; + ALL_POUT_INFO_IDX prv_api; + POUT_INFO *p_pi = &api[inst_num].pout_info; // ### TODO check inst_num range? + POUT_SETTINGS *p_ps = &p_pi->pout_settings; + const char *err_info = NULL; + char *cp; + int n_pout; + int idx; + int i; + int rc = check_get_pout_cfg( dh, api, &ri ); + + if ( mbg_cond_err_msg( rc, "check_get_pout_cfg" ) ) + return rc; + + n_pout = rc; // Contains now the number of programmable pulse outputs + + // save current settings + memcpy( prv_api, api, sizeof( prv_api ) ); + + // Mode + idx = chk_parm_name( s, pout_name_mode, &cp ); + + if ( mbg_rc_is_error( idx ) ) // parameter error + { + err_info = pout_name_mode; + goto fail; + } + + if ( cp ) // parameter found + { + idx = atoi( cp ); + + if ( idx < 0 || idx >= N_POUT_MODES ) + { + printf( "Programmable output mode %i out of range (0..%i)\n", idx, N_POUT_MODES - 1 ); + goto fail; + } + + if ( !_is_supported( idx, p_pi->supp_modes ) ) + { + printf( "Programmable output mode %i (%s) not supported for output %i\n", + idx, _get_pout_mode_name( idx ), inst_num ); + goto fail; + } + + p_ps->mode = idx; + printf( "Programmable output mode for output %i changed to %s (%i)\n", + inst_num, _get_pout_mode_name( p_ps->mode ), p_ps->mode ); + } + + + // Pulse len + idx = chk_parm_name( s, pout_name_len, &cp ); + + if ( mbg_rc_is_error( idx ) ) // parameter error + { + err_info = pout_name_len; + goto fail; + } + + if ( cp ) // parameter found + { + idx = atoi( cp ); + + if ( !_is_supported( p_ps->mode, POUT_MODES_MODE_PARAM_AS_PULSE_LEN ) ) + { + printf( "Pulse length parameter not supported for mode \"%s\"\n", + _get_pout_mode_name( p_ps->mode ) ); + goto fail; + } + + if ( idx < 0 || idx >= MAX_POUT_PULSE_LEN ) + { + printf( "Pulse length %i out of range (1..%i)\n", idx, MAX_POUT_PULSE_LEN ); + goto fail; + } + + if ( p_pi->flags & POUT_FIXED_PULSE_LEN ) + { + if ( idx != p_ps->mode_param ) + printf( "Warning. pulse length %i (%i ms) is fix and can't be changed!\n", + p_ps->mode_param, p_ps->mode_param * 10 ); + } + else + { + p_ps->mode_param = idx; + printf( "Pulse length for programmable output %i changed to %i (%i ms)\n", + inst_num, p_ps->mode_param, p_ps->mode_param * 10 ); + } + } + + + // "Inverted" flag + idx = chk_parm_name( s, pout_name_inv, &cp ); + + if ( mbg_rc_is_error( idx ) ) // parameter error + { + err_info = pout_name_inv; + goto fail; + } + + if ( cp ) // parameter found + { + idx = atoi( cp ); + + if ( idx < 0 || idx > 1 ) + { + printf( "Invalid flag value %i for parameter %s, must be 0 or 1\n", idx, pout_name_inv ); + goto fail; + } + + if ( p_pi->flags & POUT_NOT_INVERTIBLE ) + { + if ( idx ) + { + printf( "Warning: Output level can't be inverted for output %i\n", inst_num ); + goto fail; + } + } + + if ( idx ) + p_ps->flags |= POUT_INVERTED; + else + p_ps->flags &= ~POUT_INVERTED; + + printf( "Output level for output %i%s inverted\n", + inst_num, idx ? str_empty : str_spc_not ); + } + + + // "Only If Sync" flag + idx = chk_parm_name( s, pout_name_ois, &cp ); + + if ( mbg_rc_is_error( idx ) ) // parameter error + { + err_info = pout_name_ois; + goto fail; + } + + if ( cp ) // parameter found + { + idx = atoi( cp ); + + if ( idx < 0 || idx > 1 ) + { + printf( "Invalid flag value %i for parameter %s, must be 0 or 1\n", idx, pout_name_ois ); + goto fail; + } + + if ( !( p_pi->flags & POUT_SUPP_IF_SYNC_ONLY ) ) + { + if ( idx ) + { + printf( "Warning: \"Only if sync\" flag not supported for output %i\n", inst_num ); + goto fail; + } + } + + if ( idx ) + p_ps->flags |= POUT_IF_SYNC_ONLY; + else + p_ps->flags &= ~POUT_IF_SYNC_ONLY; + + printf( "\"Only if sync\" flag%s set for output %i\n", + idx ? str_empty : str_spc_not, inst_num ); + } + + + // "Pulse Shift" parameter + idx = chk_parm_name( s, pout_name_shift, &cp ); + + if ( mbg_rc_is_error( idx ) ) // parameter error + { + err_info = pout_name_shift; + goto fail; + } + + if ( cp ) // parameter found + { + long pulse_shift = atol( cp ); + + if ( !( p_pi->flags & POUT_SUPP_PULSE_SHIFT ) ) + { + printf( "Warning: pulse shift not supported for output %i\n", inst_num ); + goto fail; + } + + if ( !_is_supported( p_ps->mode, POUT_MODES_DATA_PULSE_SHIFT ) ) + { + printf( "Pulse shift not supported for mode \"%s\"\n", + _get_pout_mode_name( p_ps->mode ) ); + goto fail; + } + + + if ( ( pulse_shift < DEFAULT_POUT_PULSE_SHIFT_MIN ) || + ( pulse_shift > DEFAULT_POUT_PULSE_SHIFT_MAX ) ) + { + printf( "Pulse shift %li ns out of range (%+li..%+li ns)\n", pulse_shift, + (long) DEFAULT_POUT_PULSE_SHIFT_MIN, (long) DEFAULT_POUT_PULSE_SHIFT_MAX ); + goto fail; + } + + if ( p_pi->pulse_shift_res ) + { + long rem = pulse_shift % p_pi->pulse_shift_res; + long l = pulse_shift - rem; + + #if 0 && defined( DEBUG ) + printf( "DEBUG: s %li, rem %li, l %li\n", pulse_shift, rem, l ); + #endif + + if ( l != pulse_shift ) + { + printf( "Warning: pulse shift %+li ns not appropriate for resolution %u ns, truncating to %li ns.\n", + pulse_shift, p_pi->pulse_shift_res, l ); + pulse_shift = l; + } + } + + p_ps->pout_data.pulse_shift = pulse_shift; + + printf( "Pulse shift for programmable output %i changed to %li ns\n", + inst_num, (long) p_ps->pout_data.pulse_shift ); + } + + + for ( i = 0; i < n_pout; i++ ) + { + POUT_SETTINGS *p_ps = &api[i].pout_info.pout_settings; + + if ( memcmp( p_ps, &prv_api[i].pout_info.pout_settings, sizeof( *p_ps ) ) ) + { + // settings for this output have changed + rc = mbg_set_gps_pout_settings( dh, p_ps, i ); + + if ( mbg_rc_is_error( rc ) ) + return rc; + } + } + + return MBG_SUCCESS; + +fail: + printf( "Invalid parameter in argument" ); + + if ( err_info ) + printf( " %s", err_info ); + + printf( "!\n" ); + + return MBG_ERR_CFG; + +} // eval_pout + + + +static /*HDR*/ +int show_pout( MBG_DEV_HANDLE dh, const OPT_HANDLER_SPEC *p_opt, const PCPS_DEV *p_devx, const char *cmd_info ) +{ + const INDENTS *p_ind = &show_indents; + RECEIVER_INFO ri = { 0 }; + ALL_POUT_INFO_IDX api = { { 0 } }; + int i; + int n_pout; + int rc = check_get_pout_cfg( dh, api, &ri ); + + if ( mbg_cond_err_msg( rc, "check_get_pout_cfg" ) ) + return rc; + + n_pout = rc; // Contains now the number of programmable pulse outputs + + print_indent( p_ind->indent_1 ); + printf( "%s:", cmd_info ); + + if ( n_pout ) + { + for ( i = 0; i < n_pout; i++ ) + { + const POUT_INFO *pi = &api[i].pout_info; + const POUT_SETTINGS *ps = &pi->pout_settings; + + // TODO: Actually the code below only shows the current mode, + // and whether the output signal is inverted, or not. + // Full featured code should also display additional parameters + // depending the selected mode. + + printf( "\n" ); + print_indent( p_ind->indent_2 ); + printf( "Output %i: ", i ); + printf( "%s", _get_pout_mode_name( ps->mode ) ); + + // Print pulse len, if supported by the mode + if ( _is_supported( ps->mode, POUT_MODES_MODE_PARAM_AS_PULSE_LEN ) ) + { + // pulse len is 10 ms units, so multiply by 10 to get ms + printf( ", len %u ms", (unsigned int) ps->mode_param * 10 ); + + if ( pi->flags & POUT_FIXED_PULSE_LEN ) + printf( " (fix)" ); + } + + // ### FIXME check more mode_param usage, times etc. + + // If outputs can be inverted then this doesn't depend on the current mode + if ( !( pi->flags & POUT_NOT_INVERTIBLE ) ) + printf( ", %sinverted", ( ps->flags & POUT_INVERTED ) ? str_empty : str_not_spc ); + + + + if ( _is_supported( ps->mode, POUT_MODES_SUPP_IF_SYNC_ONLY ) ) + { + char ws[80]; + const char *cp = NULL; + + if ( _is_supported( ps->mode, POUT_MODES_TIMEOUT ) && + ( ( pi->flags & POUT_SUPP_IF_SYNC_ONLY ) == 0 ) && + ( ps->timeout != 0 ) ) + { + snprintf_safe( ws, sizeof( ws ), "after timeout %i min ", ps->timeout ); + cp = ws; + } + + if ( pi->flags & POUT_SUPP_IF_SYNC_ONLY ) + printf( ", %sdisabled %sif sync. lost", + ( ps->flags & POUT_IF_SYNC_ONLY ) ? str_empty : str_not_spc, + cp ? cp : str_empty ); + } + + + + + if ( pi->flags & POUT_SUPP_PULSE_SHIFT ) + if ( _is_supported( ps->mode, POUT_MODES_DATA_PULSE_SHIFT ) ) + printf( ", shift %li ns, res. %li ns", (long) ps->pout_data.pulse_shift, (long) pi->pulse_shift_res ); + } + } + else + printf( str_spc_not_supp ); + + printf( "\n" ); + + return MBG_SUCCESS; + +} // show_pout + + + +static /*HDR*/ void printf_ef( uint16_t flag, const char *info ) { printf( "%s:%u", info, ( flag == EF_OFF ) ? 0 : 1 ); @@ -1507,7 +2397,7 @@ int show_enable_flags( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *inf rc = mbg_get_gps_enable_flags( dh, &ef ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_enable_flags" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_gps_enable_flags" ) ) return rc; printf( "%s enable flags: ", info ); @@ -1532,7 +2422,7 @@ int show_enable_flags( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *inf static /*HDR*/ int ef_check_parm( const char *s, EF_INFO *p ) { - int l = strlen( p->name ); + size_t l = strlen( p->name ); if ( strncmp( s, p->name, l ) != 0 ) return 0; // parameter does not match @@ -1549,7 +2439,7 @@ int ef_check_parm( const char *s, EF_INFO *p ) l++; - return l; + return _int_from_size_t( l ); fail: @@ -1575,7 +2465,7 @@ int set_enable_flags( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev rc = mbg_get_gps_enable_flags( dh, &ef ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_enable_flags" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_gps_enable_flags" ) ) return rc; // Scan input parameters @@ -1608,7 +2498,7 @@ int set_enable_flags( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev save: rc = mbg_set_gps_enable_flags( dh, &ef ); - if ( mbg_ioctl_err( rc, "mbg_set_gps_enable_flags" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_gps_enable_flags" ) ) return rc; return MBG_SUCCESS; @@ -1622,7 +2512,7 @@ int send_gps_cmd( MBG_DEV_HANDLE dh, ushort cmd ) { int rc = mbg_set_gps_cmd( dh, &cmd ); - if ( mbg_ioctl_err( rc, "mbg_set_gps_cmd" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_gps_cmd" ) ) return rc; printf( "NOTE: the command code %u has been sent to the GPS clock.\n", cmd ); @@ -1639,7 +2529,7 @@ int show_ant_cable_len( MBG_DEV_HANDLE dh, const char *info ) ANT_CABLE_LEN len; int rc = mbg_get_gps_ant_cable_len( dh, &len ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_ant_cable_len" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_gps_ant_cable_len" ) ) return rc; printf( "%s antenna cable length: %u meter(s)", info, len ); @@ -1653,10 +2543,10 @@ int show_ant_cable_len( MBG_DEV_HANDLE dh, const char *info ) static /*HDR*/ int set_ant_cable_len( MBG_DEV_HANDLE dh, const char *s ) { - ANT_CABLE_LEN len = atol( s ); + ANT_CABLE_LEN len = (ANT_CABLE_LEN) atol( s ); // TODO check range ? int rc = mbg_set_gps_ant_cable_len( dh, &len ); - if ( mbg_ioctl_err( rc, "mbg_set_gps_ant_cable_len" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_gps_ant_cable_len" ) ) return rc; return MBG_SUCCESS; @@ -1675,15 +2565,15 @@ int set_event_time( MBG_DEV_HANDLE dh, const char *s ) // set event at current system time + number of seconds event_time = time( NULL ) + strtol( s, NULL, 10 ); - event_ts.sec = event_time; // Unix UTC seconds + event_ts.sec = (uint32_t) event_time; // Unix UTC seconds // TODO: check range / conversion event_ts.frac = 0; // fraction of second, 0xFFFFFFFF == 0.99.. sec rc = mbg_set_event_time( dh, &event_ts ); - if ( mbg_ioctl_err( rc, "mbg_set_event_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_event_time" ) ) return rc; - mbg_snprint_hr_tstamp( ws, sizeof( ws ), &event_ts, 0 ); // raw timestamp? + mbg_snprint_hr_tstamp( ws, sizeof( ws ), &event_ts, 0, 0 ); // raw timestamp? printf( "Event time set to UTC %s\n", ws ); return MBG_SUCCESS; @@ -1697,12 +2587,18 @@ int get_n_time_scale( MBG_DEV_HANDLE dh, MBG_TIME_SCALE_INFO *p_tsci ) { MBG_TIME_SCALE_INFO tsci = { { 0 } }; int rc; - int i; - rc = mbg_dev_has_time_scale( dh, &i ); + rc = mbg_chk_dev_has_time_scale( dh ); - if ( ( rc != MBG_SUCCESS ) || ( i == 0 ) ) - goto done; // failed or not supported + if ( mbg_rc_is_error( rc ) ) + { + if ( rc == MBG_ERR_NOT_SUPP_BY_DEV ) + printf( "This device does not support a configurable time scale.\n" ); + else + mbg_cond_err_msg( rc, "mbg_chk_dev_has_time_scale" ); + + goto done; + } rc = mbg_get_time_scale_info( dh, &tsci ); @@ -1727,7 +2623,7 @@ int show_time_scale( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *info rc = mbg_get_time_scale_info( dh, &tsci ); - if ( mbg_ioctl_err( rc, "mbg_get_time_scale_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_time_scale_info" ) ) return rc; printf( "%s time scale index: %u (%s)", info, tsci.settings.scale, @@ -1749,7 +2645,7 @@ int set_time_scale( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) rc = mbg_get_time_scale_info( dh, &tsci ); - if ( mbg_ioctl_err( rc, "mbg_get_time_scale_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_time_scale_info" ) ) return rc; @@ -1771,7 +2667,7 @@ int set_time_scale( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) rc = mbg_set_time_scale_settings( dh, &tsci.settings ); - if ( mbg_ioctl_err( rc, "mbg_set_time_scale_settings" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_time_scale_settings" ) ) return rc; return MBG_SUCCESS; @@ -1781,17 +2677,14 @@ int set_time_scale( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) static /*HDR*/ -void usage( MBG_DEV_HANDLE dh, PCPS_DEV *p_dev, RECEIVER_INFO *p_ri, +void usage( MBG_DEV_HANDLE dh, PCPS_DEV *p_dev, RECEIVER_INFO *p_ri, RECEIVER_PORT_CFG *p_rpcfg ) { int i; int n_time_scale; if ( p_dev ) - { - check_setup_receiver_info( dh, p_dev, p_ri ); check_get_receiver_port_cfg( dh, p_rpcfg, p_dev, p_ri ); - } printf( "Usage: %s cmd [dev]\n" "\n" @@ -1850,12 +2743,12 @@ void usage( MBG_DEV_HANDLE dh, PCPS_DEV *p_dev, RECEIVER_INFO *p_ri, printf( ", where\n" " <bd> is one of:" ); for ( i = 0; i < N_MBG_BAUD_RATES; i++ ) - printf( " %s", mbg_baud_str[i] ); + printf( " %s", mbg_baud_rate_strs[i] ); printf( "\n" " <f> is one of:" ); for ( i = 0; i < N_MBG_FRAMINGS; i++ ) - printf( " %s", mbg_framing_str[i] ); + printf( " %s", mbg_framing_strs[i] ); printf( "\n <t> optional time string format index" ); @@ -1887,6 +2780,10 @@ void usage( MBG_DEV_HANDLE dh, PCPS_DEV *p_dev, RECEIVER_INFO *p_ri, printf( "\n" ); + help_pout_arg( dh, p_dev, &ohs_pout, 0 ); + + printf( "\n" ); + printf( " EF show clock's enable flags\n" " EF=SERIAL:0,PULSES:1,SYNTH:0 modify clock's enable flags\n" "\n" @@ -1937,17 +2834,17 @@ void usage( MBG_DEV_HANDLE dh, PCPS_DEV *p_dev, RECEIVER_INFO *p_ri, printf( " If the PTP device supports unicast slave mode then the following parameters\n" " can be specified to configure a unicast master to be queried:\n" - " PTP=ROLE:<rl>[,GMIP:<ip>][,GMID:<id>][,PID:<po>][,SMI:<sr>][,AMI:<ar>][,DMI:<dr>][,DUR:<du>] set PTP unicast parameters\n" + " PTP=ROLE:<rl>[,GMIP:<ip>][,GMID:<id>][,PID:<po>][,SMI:<sr>][,AMI:<ar>][,DRI:<dr>][,DUR:<du>] set PTP unicast parameters\n" "\n" " where, e.g.:\n" " ROLE:MCS specifies \"Multicast Slave\" PTP role\n" " ROLE:UCS specifies \"Unicast Slave\" PTP role\n" " GMIP:192.168.1.115 specifies the IP address of the grandmaster\n" - " GMID:FF:FF:FF:FF:FF:FF:FF:FF specifies the Clock ID of the grandmaster, or '*' as wildcard for all FF\n" - " PID:1 specifies the target port ID of the grandmaster port to be used, or '*' for wildcard\n" - " SMI:0 specifies the Sync message interval requested from the grandmaster in 2^x seconds [-6..6]\n" - " AMI:1 specifies the Announce message interval requested from the grandmaster in 2^x seconds [-6..6]\n" - " DMI:1 specifies the DelayRequest message interval requested from the grandmaster in 2^x seconds [-6..6]\n" + " GMID:FF:FF:FF:FF:FF:FF:FF:FF specifies the Clock ID of the grandmaster, or '*' as wildcard for all 'FF'\n" + " PID:1 specifies the target Port ID of the grandmaster port to be used, or '*' for wildcard\n" + " SMI:0 specifies the Sync Message Interval requested from the grandmaster in 2^x seconds [-6..6]\n" + " AMI:1 specifies the Announce Message Interval requested from the grandmaster in 2^x seconds [-6..6]\n" + " DRI:1 specifies the Delay Request Interval requested from the grandmaster in 2^x seconds [-6..6]\n" " DUR:300 specifies the duration in seconds how long the master shall send messages to the slave until a timeout or renewal occurs\n" "\n" ); @@ -1985,27 +2882,27 @@ const char *str_parm_p( const char *s, const char *keyword ) static /*HDR*/ -int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, +int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, RECEIVER_INFO *p_ri, RECEIVER_PORT_CFG *p_rpcfg ) { const char *sdate = NULL; const char *stime = NULL; const char *cp; int i; - int rc = 0; + int rc = MBG_SUCCESS; int error_occurred = 0; must_print_usage = 0; for ( i = 1; i < argc; i++ ) { - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) error_occurred = 1; - if ( rc > 0 ) + if ( rc == RC_USAGE ) must_print_usage = 1; - rc = 0; + rc = MBG_SUCCESS; if ( ( strcmp( argv[i], "-?" ) == 0 ) || ( strcmp( argv[i], "-h" ) == 0 ) || @@ -2078,11 +2975,16 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p { if ( p_dev ) { - check_setup_receiver_info( dh, p_dev, p_ri ); - if ( p_ri->n_com_ports ) + int rc = check_get_receiver_port_cfg( dh, p_rpcfg, p_dev, p_ri ); + + if ( mbg_rc_is_error( rc ) ) { - check_get_receiver_port_cfg( dh, p_rpcfg, p_dev, p_ri ); + // ### TODO print another error? + continue; + } + if ( p_ri->n_com_ports ) + { if ( *cp != 0 ) { printf( "** Invalid parameter: %s\n", argv[i] ); @@ -2109,8 +3011,13 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p char *p_tail; ulong port_num; - check_setup_receiver_info( dh, p_dev, p_ri ); - check_get_receiver_port_cfg( dh, p_rpcfg, p_dev, p_ri ); + rc = check_get_receiver_port_cfg( dh, p_rpcfg, p_dev, p_ri ); + + if ( mbg_rc_is_error( rc ) ) + { + // ### TODO print another error? + continue; + } port_num = strtoul( cp, &p_tail, 10 ); @@ -2125,7 +3032,7 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p if ( port_num >= (ulong) p_ri->n_com_ports ) { - printf( "** COM port number %lu exceeds maximum %u\n", + printf( "** COM port number %lu exceeds maximum %u\n", port_num, p_ri->n_com_ports ); must_print_usage = 1; continue; @@ -2144,6 +3051,58 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p } + cp = str_parm_p( argv[i], "POUT" ); + + if ( cp ) + { + if ( p_dev ) + { + ulong n_pout; + ulong pout_num; + char *p_tail; + + check_setup_receiver_info( dh, p_ri ); + n_pout = p_ri->n_prg_out; + + if ( n_pout == 0 ) + { + printf( "Programmable outputs not supported!\n" ); + continue; + } + + pout_num = strtoul( cp, &p_tail, 10 ); + + if ( p_tail == cp ) // no POUT number specified + { + show_pout( dh, &ohs_pout, p_dev, "Current programmable outputs settings" ); + continue; + } + + cp = p_tail; + + if ( pout_num >= n_pout ) + { + printf( "** Programmable output number %lu exceeds maximum %lu\n", + pout_num, n_pout ); + must_print_usage = 1; + continue; + } + + if ( *cp != '=' ) + { + printf( "** Invalid programmable output specification: %s\n", argv[i] ); + must_print_usage = 1; + continue; + } + + rc = eval_pout( dh, ++cp, (unsigned) pout_num ); + printf( "\n" ); + show_pout( dh, &ohs_pout, p_dev, "Current programmable outputs settings" ); + } + continue; + } + + cp = str_parm_p( argv[i], "EF" ); if ( cp ) @@ -2162,7 +3121,7 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p { rc = set_enable_flags( dh, ++cp, p_dev ); - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) { printf( "*** Warning: invalid enable flag parameter syntax\n" ); must_print_usage = 1; @@ -2196,7 +3155,7 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p { rc = set_time_scale( dh, ++cp, p_dev ); - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) { must_print_usage = 1; continue; @@ -2229,7 +3188,7 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p { rc = set_tzdl_offs( dh, ++cp ); - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) { must_print_usage = 1; continue; @@ -2244,6 +3203,39 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p } + cp = str_parm_p( argv[i], "SYNTH" ); + + if ( cp ) + { + if ( p_dev ) + { + char *info = "Current"; + + if ( !_pcps_has_synth( p_dev ) ) + { + err_msg( p_dev, no_synth ); + continue; + } + + if ( *cp == '=' ) + { + rc = set_synth( dh, ++cp ); + + if ( mbg_rc_is_error( rc ) ) + { + must_print_usage = 1; + continue; + } + + info = "New"; + } + + show_synth( dh, info ); + } + continue; + } + + cp = str_parm_p( argv[i], "LAN" ); if ( cp ) @@ -2262,7 +3254,7 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p { rc = set_lan_intf( dh, ++cp, p_dev ); - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) { must_print_usage = 1; continue; @@ -2295,11 +3287,8 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p { rc = set_ptp_cfg( dh, ++cp, p_dev ); - if ( rc < 0 ) - { - must_print_usage = 1; + if ( mbg_rc_is_error( rc ) ) continue; - } info = "New"; } @@ -2327,7 +3316,7 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p { rc = set_ant_cable_len( dh, ++cp ); - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) { must_print_usage = 1; continue; @@ -2353,9 +3342,9 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p if ( *cp == '=' ) rc = set_event_time( dh, ++cp ); else - rc = -1; + rc = MBG_ERR_PARM_FMT; - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) printf( "*** Warning: invalid event time parameter\n" ); } else @@ -2379,13 +3368,18 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p if ( p_dev ) if ( sdate || stime ) + { rc = set_date_time( dh, p_dev, sdate, stime ); + if ( mbg_rc_is_error( rc ) ) + error_occurred = 1; + } + if ( error_occurred ) - return -1; + return MBG_ERR_GENERIC; if ( must_print_usage ) - return 1; + return RC_USAGE; return MBG_SUCCESS; @@ -2400,9 +3394,10 @@ int main( int argc, char *argv[] ) PCPS_DEV dev = { { 0 } }; PCPS_DEV *pdev = NULL; MBG_DEV_HANDLE dh = MBG_INVALID_DEV_HANDLE; + MBG_DEV_FN tmp_dev_fn; int rc; - mbg_print_program_info( pname, MBG_MICRO_VERSION, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); + mbg_print_program_info( pname, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); // If no arguments have been given, just print usage. if ( argc < 2 ) @@ -2412,25 +3407,17 @@ int main( int argc, char *argv[] ) // pass a device handle, so commands are not evaluated. check_cmd_line( argc, argv, dh, NULL, &ri, &rpcfg ); - if ( dev_name ) - dh = open( dev_name, O_RDWR ); // open specific device - else - dh = mbg_open_device( 0 ); // open first device found - - if ( dh == MBG_INVALID_DEV_HANDLE ) - { - //##++++++++++++++++++++++ - if ( dev_name ) - fprintf( stderr, "%s: ", dev_name ); + rc = mbg_open_device_by_param( &dh, dev_name, 0, 0, + tmp_dev_fn, sizeof( tmp_dev_fn ), 0 ); - perror( "Unable to open device" ); + if ( mbg_rc_is_error( rc ) ) goto fail; - } + // get information about the device - rc = mbg_get_show_dev_info( dh, dev_name, &dev ); + rc = mbg_get_show_dev_info( dh, NULL, &dev ); - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) goto fail; @@ -2448,13 +3435,13 @@ int main( int argc, char *argv[] ) mbg_close_device( &dh ); - return 0; + return MBG_EXIT_CODE_SUCCESS; show_usage: usage( dh, pdev, &ri, &rpcfg ); - return 1; + return MBG_EXIT_CODE_USAGE; fail: - return 2; + return MBG_EXIT_CODE_FAIL; } diff --git a/mbgfasttstamp/mbgfasttstamp.c b/mbgfasttstamp/mbgfasttstamp.c index c9b2d91..4cdb8b2 100644 --- a/mbgfasttstamp/mbgfasttstamp.c +++ b/mbgfasttstamp/mbgfasttstamp.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgfasttstamp.c 1.6.1.8 2013/04/10 15:40:28Z martin TEST martin $ + * $Id: mbgfasttstamp.c 1.8 2018/11/15 12:12:32Z martin REL_M $ * * Description: * Main file for mbgfasttstamp program which demonstrates how to access @@ -9,20 +9,18 @@ * * ----------------------------------------------------------------------- * $Log: mbgfasttstamp.c $ - * Revision 1.6.1.8 2013/04/10 15:40:28Z martin - * Revision 1.6.1.7 2013/01/24 14:39:33Z martin - * Revision 1.6.1.6 2012/06/01 18:46:52 martin - * Added option to sleep between calls. - * Revision 1.6.1.5 2011/12/19 16:09:17 martin - * Revision 1.6.1.4 2011/09/26 16:00:51 martin - * Modified program version handling. - * Account for modified library functions which can now - * optionally print the raw (hex) HR time stamp. - * Started to support signal handler to catch CTRL-C. - * Revision 1.6.1.3 2011/01/28 12:04:07 martin - * Revision 1.6.1.2 2011/01/28 11:51:13 martin - * Revision 1.6.1.1 2011/01/28 11:17:00 martin + * Revision 1.8 2018/11/15 12:12:32Z martin + * Individual MBG_MICRO_VERSION codes are now obsolete. + * Revision 1.7 2017/07/05 18:55:22 martin + * New way to maintain version information. + * Support build under Windows. * Abort if MM access not supported on the target OS. + * Support signal handler to catch CTRL-C. + * Added options to sleep between calls. + * Parameters -u and -s imply -c. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. * Revision 1.6 2010/05/21 12:54:33 martin * Print warning if no cycles supported on the target platform * and thus latencies can not be computed. @@ -47,7 +45,6 @@ // include Meinberg headers #include <mbgdevio.h> -#include <pcpsutil.h> #include <toolutil.h> // common utility functions // include system headers @@ -55,7 +52,6 @@ #include <stdlib.h> -#define MBG_MICRO_VERSION 0 #define MBG_FIRST_COPYRIGHT_YEAR 2007 #define MBG_LAST_COPYRIGHT_YEAR 0 // use default @@ -89,8 +85,8 @@ int show_fast_hr_timestamp( MBG_DEV_HANDLE dh ) int rc = read_raw ? mbg_get_fast_hr_timestamp( dh, &ts ) : mbg_get_fast_hr_timestamp_comp( dh, &ts, &hns_latency ); - if ( mbg_ioctl_err( rc, "mbg_get_fast_hr_timestamp..." ) ) - goto fail; + if ( mbg_cond_err_msg( rc, "mbg_get_fast_hr_timestamp..." ) ) + return rc; mbg_print_hr_timestamp( &ts, hns_latency, NULL, read_raw, 1 ); // raw timestamp? @@ -109,10 +105,7 @@ int show_fast_hr_timestamp( MBG_DEV_HANDLE dh ) // if this_loops is < 0 then loop forever } - return 0; - -fail: - return -1; + return MBG_SUCCESS; } // show_fast_hr_timestamp @@ -142,8 +135,8 @@ int show_fast_hr_timestamp_burst( MBG_DEV_HANDLE dh ) { int rc = mbg_get_fast_hr_timestamp( dh, &ts[i] ); - if ( mbg_ioctl_err( rc, "mbg_get_fast_hr_timestamp" ) ) - goto fail; + if ( mbg_cond_err_msg( rc, "mbg_get_fast_hr_timestamp" ) ) + return rc; } } else @@ -151,8 +144,8 @@ int show_fast_hr_timestamp_burst( MBG_DEV_HANDLE dh ) { int rc = mbg_get_fast_hr_timestamp_comp( dh, &ts[i], &hns_latency[i] ); - if ( mbg_ioctl_err( rc, "mbg_get_fast_hr_timestamp_comp" ) ) - goto fail; + if ( mbg_cond_err_msg( rc, "mbg_get_fast_hr_timestamp_comp" ) ) + return rc; } for ( i = 0; i < this_loops; i++ ) @@ -161,11 +154,7 @@ int show_fast_hr_timestamp_burst( MBG_DEV_HANDLE dh ) mbg_print_hr_timestamp( &ts[i], hns_latency[i], p_prv_ts, read_raw, 0 ); // raw timestamp? } - return 0; - - -fail: - return -1; + return MBG_SUCCESS; } // show_fast_hr_timestamp_burst @@ -174,16 +163,13 @@ fail: static /*HDR*/ int do_mbgfasttstamp( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) { - int supported = 0; - int rc = mbg_dev_has_fast_hr_timestamp( dh, &supported ); + int rc = mbg_chk_dev_has_fast_hr_timestamp( dh ); - if ( mbg_ioctl_err( rc, "mbg_has_fast_hr_timestamp" ) ) - goto done; - - if ( !supported ) + if ( mbg_rc_is_error( rc ) ) { - printf( "This device does not support fast (memory mapped) time stamps.\n" ); - goto done; + mbg_cond_err_msg_info( rc, "mbg_chk_dev_has_fast_hr_timestamp", + "support fast (memory mapped) time stamps" ); + return rc; } if ( burst_read ) @@ -191,13 +177,12 @@ int do_mbgfasttstamp( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) else show_fast_hr_timestamp( dh ); -done: - mbg_close_device( &dh ); - - return rc; + return MBG_SUCCESS; } // do_mbgfasttstamp +static MBG_DEV_HANDLER_FNC do_mbgfasttstamp; + static /*HDR*/ @@ -214,8 +199,8 @@ void usage( void ) mbg_print_opt_info( "-n num", "run num loops" ); mbg_print_opt_info( "-b", "burst read" ); mbg_print_opt_info( "-r", "read raw time stamps, no cycles" ); - mbg_print_opt_info( "-s num", "sleep num seconds between calls" ); - mbg_print_opt_info( "-u num", "sleep num microseconds between calls" ); + mbg_print_opt_info( "-s num", "sleep num seconds between calls (implies -c)" ); + mbg_print_opt_info( "-u num", "sleep num microseconds between calls (implies -c)" ); mbg_print_device_options(); puts( "" ); @@ -228,7 +213,7 @@ int main( int argc, char *argv[] ) int rc; int c; - mbg_print_program_info( pname, MBG_MICRO_VERSION, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); + mbg_print_program_info( pname, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); // check command line parameters while ( ( c = getopt( argc, argv, "bcn:rs:u:h?" ) ) != -1 ) @@ -253,10 +238,12 @@ int main( int argc, char *argv[] ) case 's': sleep_secs = atoi( optarg ); + loops = -1; break; case 'u': sleep_usecs = atoi( optarg ); + loops = -1; break; case 'h': @@ -269,7 +256,7 @@ int main( int argc, char *argv[] ) if ( must_print_usage ) { usage(); - return 1; + return MBG_EXIT_CODE_USAGE; } #if !MBG_TGT_SUPP_MEM_ACC @@ -289,12 +276,8 @@ int main( int argc, char *argv[] ) printf( "\n" ); #endif - // The function below checks which devices have been specified - // on the command, and for each device - // - tries to open the device - // - shows basic device info - // - calls the function passed as last parameter - rc = mbg_check_devices( argc, argv, optind, do_mbgfasttstamp ); + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbgfasttstamp, 0 ); - return abs( rc ); + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; } diff --git a/mbggpscap/mbggpscap.c b/mbggpscap/mbggpscap.c index 8dc8b53..75f73a6 100644 --- a/mbggpscap/mbggpscap.c +++ b/mbggpscap/mbggpscap.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbggpscap.c 1.10.1.7 2013/04/10 15:40:28Z martin TEST martin $ + * $Id: mbggpscap.c 1.14 2018/11/15 12:12:36Z martin REL_M $ * * Description: * Main file for mbggpscap program which demonstrates how to access @@ -13,22 +13,30 @@ * * ----------------------------------------------------------------------- * $Log: mbggpscap.c $ - * Revision 1.10.1.7 2013/04/10 15:40:28Z martin - * Revision 1.10.1.6 2011/09/09 08:28:22Z martin - * Revision 1.10.1.5 2011/09/07 15:12:33 martin - * New option -r which displays raw timestamps and raw status. - * New option -o which forces usage of old API. - * Fixed a bug when displaying the capture event status. TTM and PCPS_HR_TIME - * are using different sets of status flags. - * Revision 1.10.1.4 2011/07/05 15:35:54 martin - * Modified version handling. - * Revision 1.10.1.3 2011/07/05 14:35:18 martin + * Revision 1.14 2018/11/15 12:12:36Z martin + * Individual MBG_MICRO_VERSION codes are now obsolete. + * Revision 1.13 2018/01/10 13:36:35 martin + * Use current API mbg_get_serial_settings() to check + * serial settings. Don't change configuration but just warn + * if capture events might be spit out via a serial port. + * Added some doxygen comments. + * Revision 1.12 2017/11/29 12:49:31 martin + * Added feature to log capture events to a file. + * Revision 1.11 2017/07/05 18:59:14 martin * New way to maintain version information. - * Revision 1.10.1.2 2010/11/12 12:27:17 martin + * Support build under Windows. + * Improved code execution paths. * Improved reading capture events arriving at a high rate. * Support validation of capture signals arriving at a constant rate. - * Revision 1.10.1.1 2010/03/10 16:42:33 martin - * Improved code execution paths. + * Fixed a bug when displaying the capture event status. TTM and + * PCPS_HR_TIME are using different sets of status flags. + * New option -r which displays raw timestamps and raw status. + * New option -o which forces usage of old API. + * New command line option to clear buffer. + * Account for PCPS_HRT_BIN_FRAC_SCALE renamed to MBG_FRAC32_UNITS_PER_SEC. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. * Revision 1.10 2009/09/29 15:02:15 martin * Updated version number to 3.4.0. * Revision 1.9 2009/07/24 09:50:08 martin @@ -60,8 +68,9 @@ // include Meinberg headers #include <mbgdevio.h> -#include <pcpsutil.h> +#include <deviohlp.h> #include <toolutil.h> // common utility functions +#include <str_util.h> // include system headers #include <stdio.h> @@ -72,7 +81,6 @@ #define USLEEP_INTV 10000 // [microseconds] -#define MBG_MICRO_VERSION 0 #define MBG_FIRST_COPYRIGHT_YEAR 2001 #define MBG_LAST_COPYRIGHT_YEAR 0 // use default @@ -84,70 +92,125 @@ static double nom_cap_intv; // nominal capture interval to check [s] static double max_cap_jitter; // max allowed jitter [s] static int raw; static int force_old_api; +static int clear_buffer; +static const char *log_fn; static int has_been_called; static int must_check_intv; +static int query_only; static ulong err_cnt; static PCPS_HR_TIME prv_ucap; static /*HDR*/ +/** + * @brief Show a user capture event in ::PCPS_HR_TIME format + * + * The current API call ::mbg_get_ucap_event provides + * capture events as ::PCPS_HR_TIME structure, but + * there may be older devices which only support the + * obsolete API call ::mbg_get_gps_ucap. + * + * @param[in] ucap The capture event read from a device. + * + * @see ::mbg_get_ucap_event + * @see ::mbg_get_gps_ucap + * @see ::show_gps_ucap + */ void show_ucap_event( const PCPS_HR_TIME *ucap ) { char ws[80]; + char s[400]; + int n; // Print converted date and time to a string: mbg_snprint_hr_time( ws, sizeof( ws ), ucap, raw ); // Print the time stamp, ucap->signal contains the channel number: - printf( "New capture: CH%i: %s", ucap->signal, ws ); + n = snprintf_safe( s, sizeof( s ), "New capture: CH%i: %s", ucap->signal, ws ); if ( must_check_intv && has_been_called ) { + int jitter_exceeded; double abs_delta; double d = ucap->tstamp.sec - prv_ucap.tstamp.sec; - d += ( (double) ucap->tstamp.frac - prv_ucap.tstamp.frac ) / PCPS_HRT_BIN_FRAC_SCALE; + d += ( (double) ucap->tstamp.frac - prv_ucap.tstamp.frac ) / MBG_FRAC32_UNITS_PER_SEC; - printf( " %+.6f", d ); + n += snprintf_safe( &s[n], sizeof( s ) - n, " %+.6f", d ); abs_delta = d - nom_cap_intv; if ( abs_delta < 0.0 ) abs_delta = -abs_delta; + jitter_exceeded = 0; + if ( abs_delta > max_cap_jitter ) + { + jitter_exceeded = 1; err_cnt++; + } if ( err_cnt ) - printf( " ** %lu", err_cnt ); + n += snprintf_safe( &s[n], sizeof( s ) - n, " %lu%s", err_cnt, jitter_exceeded ? " <<" : "" ); } // status bit definitions can be found in pcpsdefs.h. if ( raw ) - printf( ", st: 0x%04X", ucap->status ); + n += snprintf_safe( &s[n], sizeof( s ) - n, ", st: 0x%04X", ucap->status ); if ( ucap->status & PCPS_UCAP_OVERRUN ) // capture events have occurred too fast - printf( " << CAP OVR" ); + n += snprintf_safe( &s[n], sizeof( s ) - n, " << CAP OVR" ); if ( ucap->status & PCPS_UCAP_BUFFER_FULL ) // capture buffer has been full, events lost - printf( " << BUF OVR" ); + n += snprintf_safe( &s[n], sizeof( s ) - n, " << BUF OVR" ); prv_ucap = *ucap; has_been_called = 1; - printf( "\n" ); + printf( "%s\n", s ); -} // show_ucap_event + if ( log_fn ) + { + FILE *fp = fopen( log_fn, "at" ); + if ( fp ) + { + fprintf( fp, "%s\n", s ); + fclose( fp ); + } + else + { + fprintf( stderr, "** Failed to open file %s for writing: %s\n", + log_fn, strerror( errno ) ); + log_fn = NULL; + } + } + +} // show_ucap_event -// The function below is normally outdated, and show_ucap_event() -// above should be used if possible, together with the associated -// API calls. static /*HDR*/ +/** + * @brief Show a user capture event in ::TTM format read from device + * + * This function is actually obsolete since it shows user + * capture events provided as ::TTM structure, as returned + * by the obsolete API call ::mbg_get_gps_ucap. + * + * The current API call ::mbg_get_ucap_event is faster + * and provides capture events as ::PCPS_HR_TIME structure, + * but some very old devices may not support the newer API. + * + * @param[in] ucap The capture event read from a device. + * + * @see ::mbg_get_ucap_event + * @see ::mbg_get_gps_ucap + * @see ::show_ucap_event + */ void show_gps_ucap( const TTM *ucap ) { printf( "New capture: CH%i: %04i-%02i-%02i %2i:%02i:%02i.%07li", @@ -171,41 +234,77 @@ void show_gps_ucap( const TTM *ucap ) static /*HDR*/ -void check_serial_mode( MBG_DEV_HANDLE dh ) +/** + * @brief Check the modes of a device's serial ports + * + * If one of the device's serial ports has been + * configured to send a serial string automatically + * then this is usually to send a capture event string + * automatically as soon as an event has occurred. + * + * As a consequence, those events are removed from the + * on-board FIFO and aren't available anymore when + * an application tries to read capture events via the + * PCI bus, using the API functions ::mbg_get_ucap_event + * or ::mbg_get_gps_ucap. + * + * So we check and print a warning, if this may be the case. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p_dev Pointer do a device info structure for the device. + * + * @see ::mbg_get_ucap_event + * @see ::mbg_get_gps_ucap + */ +void check_serial_mode( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) { - PORT_PARM port_parm; + RECEIVER_INFO ri; + RECEIVER_PORT_CFG rpcfg; int i; - int must_modify = 0; + int must_warn = 0; - // read the clock's current port settings - int rc = mbg_get_gps_port_parm( dh, &port_parm ); + int rc = mbg_setup_receiver_info( dh, p_dev, &ri ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_port_parm" ) ) + if ( mbg_cond_err_msg( rc, "mbg_setup_receiver_info" ) ) return; + if ( ri.n_com_ports == 0 ) // The device provides no serial port + return; // so there's nothing to check. - // If one of the ports has been set to send user captures - // then the user capture buffer will most often be empty - // if we check for captures, so modify the port mode. - for ( i = 0; i < N_COM; i++ ) - { - if ( port_parm.mode[i] == STR_UCAP ) - { - port_parm.mode[i] = STR_UCAP_REQ; - must_modify = 1; - } - } + // read the clock's current serial port settings + rc = mbg_get_serial_settings( dh, p_dev, &rpcfg, &ri ); - if ( !must_modify ) + if ( mbg_cond_err_msg( rc, "mbg_get_serial_settings" ) ) return; - rc = mbg_set_gps_port_parm( dh, &port_parm ); + // Check if one of the serial ports uses STR_AUTO mode. + for ( i = 0; i < ri.n_com_ports; i++ ) + { + PORT_SETTINGS *p = &rpcfg.pii[i].port_info.port_settings; - if ( mbg_ioctl_err( rc, "mbg_set_gps_port_parm" ) ) - return; + if ( p->mode == STR_AUTO ) + { + must_warn = 1; + break; + } + } - printf( "NOTE: the clock's serial port mode has been changed.\n" ); + if ( must_warn ) + fprintf( stderr, + "ATTENTION: At least one of the device's serial ports has been\n" + "configured to send time strings automatically, which can remove\n" + "capture events from the on-board FIFO, so they are unavailable\n" + "to this application\n" + "\n" + "Please change the configuration of the serial port(s) in a way that\n" + "none of the serial ports sends a capture event string automatically.\n" + "\n" + "For example, use the \"mbgctrl\" program to let the serial ports\n" + "transmit the Meinberg standard time string once per second.\n" + "\n" + "See \"mbgctrl -?\" for details.\n" + "\n" ); } // check_serial_mode @@ -215,18 +314,20 @@ static /*HDR*/ int do_mbggpscap( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) { int rc; + int this_clear_buffer = clear_buffer; must_check_intv = continuous && ( nom_cap_intv != 0 ); has_been_called = 0; err_cnt = 0; + if ( !_pcps_has_ucap( p_dev ) && !_pcps_is_gps( p_dev ) ) { printf( "This device type does not provide time capture inputs.\n" ); return 0; } - check_serial_mode( dh ); + check_serial_mode( dh, p_dev ); printf( "Be sure the card has been properly configured to enable capture inputs.\n" ); @@ -263,9 +364,16 @@ int do_mbggpscap( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) ucap_entries.used, ucap_entries.max ); } + if ( this_clear_buffer ) + { + printf( "Clearing on-board FIFO buffer\n" ); + mbg_clr_ucap_buff( dh ); + this_clear_buffer = 0; + } + // If the program is not to run continuously and no // capture events are available then we're through. - if ( !continuous && ucap_entries.used == 0 ) + if ( query_only || ( !continuous && ucap_entries.used == 0 ) ) return 0; @@ -274,6 +382,10 @@ int do_mbggpscap( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) "Reading capture events:\n" ); + if ( must_check_intv ) + if ( max_cap_jitter == 0.0 ) + max_cap_jitter = 0.1e-6; + // Now read out all events from the FIFO and wait // for new events if the FIFO is empty. for (;;) @@ -282,7 +394,7 @@ int do_mbggpscap( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) rc = mbg_get_ucap_event( dh, &ucap_event ); - if ( mbg_ioctl_err( rc, "mbg_get_ucap_event" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_ucap_event" ) ) break; // an error has occurred // If a user capture event has been read then it @@ -308,7 +420,7 @@ int do_mbggpscap( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) rc = mbg_get_gps_ucap( dh, &ucap_ttm ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_ucap" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_gps_ucap" ) ) break; // an error has occurred @@ -334,6 +446,8 @@ int do_mbggpscap( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) } // do_mbggpscap +static MBG_DEV_HANDLER_FNC do_mbggpscap; + static /*HDR*/ @@ -345,8 +459,10 @@ void usage( void ) ); mbg_print_help_options(); mbg_print_opt_info( "-c", "run continuously" ); + mbg_print_opt_info( "-C", "clear capture buffer" ); mbg_print_opt_info( "-i val", "check interval between captures events [s]" ); mbg_print_opt_info( "-j val", "max allowed jitter of capture interval [s]" ); + mbg_print_opt_info( "-q", "query FIFO buffer status only" ); mbg_print_opt_info( "-r", "show raw (hex) timestamp and status)" ); mbg_print_opt_info( "-o", "force usage of old API (for testing only)" ); mbg_print_device_options(); @@ -361,10 +477,10 @@ int main( int argc, char *argv[] ) int rc; int c; - mbg_print_program_info( pname, MBG_MICRO_VERSION, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); + mbg_print_program_info( pname, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); // check command line parameters - while ( ( c = getopt( argc, argv, "ci:j:roh?" ) ) != -1 ) + while ( ( c = getopt( argc, argv, "cCi:j:l:oqrh?" ) ) != -1 ) { switch ( c ) { @@ -372,6 +488,10 @@ int main( int argc, char *argv[] ) continuous = 1; break; + case 'C': + clear_buffer = 1; + break; + case 'i': nom_cap_intv = atof( optarg ); break; @@ -380,14 +500,22 @@ int main( int argc, char *argv[] ) max_cap_jitter = atof( optarg ); break; - case 'r': - raw = 1; + case 'l': + log_fn = optarg; break; case 'o': force_old_api = 1; break; + case 'q': + query_only = 1; + break; + + case 'r': + raw = 1; + break; + case 'h': case '?': default: @@ -398,15 +526,17 @@ int main( int argc, char *argv[] ) if ( must_print_usage ) { usage(); - return 1; + return MBG_EXIT_CODE_USAGE; + } + + if ( nom_cap_intv != 0.0 ) + { + printf( "Nominal capture interval: %f s\n", nom_cap_intv ); + printf( "Maximum allowed capture jitter: %f s\n", max_cap_jitter ); } - // The function below checks which devices have been specified - // on the command, and for each device - // - tries to open the device - // - shows basic device info - // - calls the function passed as last parameter - rc = mbg_check_devices( argc, argv, optind, do_mbggpscap ); + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbggpscap, 0 ); - return abs( rc ); + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; } diff --git a/mbghrtime/mbghrtime.c b/mbghrtime/mbghrtime.c index cf71778..2fa6b5b 100644 --- a/mbghrtime/mbghrtime.c +++ b/mbghrtime/mbghrtime.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbghrtime.c 1.11.1.10 2013/04/10 15:40:29Z martin TEST martin $ + * $Id: mbghrtime.c 1.13 2018/11/15 12:12:34Z martin REL_M $ * * Description: * Main file for mbghrtime program which demonstrates how to access @@ -10,23 +10,17 @@ * * ----------------------------------------------------------------------- * $Log: mbghrtime.c $ - * Revision 1.11.1.10 2013/04/10 15:40:29Z martin - * Revision 1.11.1.9 2011/12/19 16:13:46Z martin - * Revision 1.11.1.8 2011/09/29 16:28:34 martin - * New options -s, -u, -v. - * Print time using new function mbg_print_hr_time(). - * Revision 1.11.1.7 2011/09/07 15:08:55 martin - * Account for modified library functions which can now - * optionally print the raw (hex) HR time stamp. - * Revision 1.11.1.6 2011/07/05 15:35:54 martin - * Modified version handling. - * Revision 1.11.1.5 2011/07/05 14:35:18 martin + * Revision 1.13 2018/11/15 12:12:34Z martin + * Individual MBG_MICRO_VERSION codes are now obsolete. + * Revision 1.12 2017/07/05 19:02:13 martin * New way to maintain version information. - * Revision 1.11.1.4 2011/01/28 12:04:08 martin - * Revision 1.11.1.3 2011/01/28 11:52:51 martin - * Revision 1.11.1.2 2011/01/28 11:51:13 martin - * Revision 1.11.1.1 2011/01/28 11:17:33 martin - * Starrted to support raw and burst. + * Support build under Windows. + * Support raw and burst mode. + * New options -s, -u, -v. + * Parameters -u and -s imply -c. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. * Revision 1.11 2010/05/21 12:54:33 martin * Print warning if no cycles supported on the target platform * and thus latencies can not be computed. @@ -61,7 +55,6 @@ // include Meinberg headers #include <mbgdevio.h> -#include <pcpsutil.h> #include <toolutil.h> // common utility functions // include system headers @@ -71,7 +64,6 @@ -#define MBG_MICRO_VERSION 0 #define MBG_FIRST_COPYRIGHT_YEAR 2001 #define MBG_LAST_COPYRIGHT_YEAR 0 // use default @@ -108,7 +100,7 @@ int show_hr_timestamp( MBG_DEV_HANDLE dh ) int rc = read_raw ? mbg_get_hr_time( dh, &ht ) : mbg_get_hr_time_comp( dh, &ht, &hns_latency ); - if ( mbg_ioctl_err( rc, "mbg_get_hr_time_..." ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_hr_time_..." ) ) goto fail; mbg_print_hr_time( &ht, hns_latency, p, read_raw, verbose, verbose ); @@ -164,7 +156,7 @@ int show_hr_timestamp_burst( MBG_DEV_HANDLE dh ) { int rc = mbg_get_hr_time( dh, &ht[i] ); - if ( mbg_ioctl_err( rc, "mbg_get_hr_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_hr_time" ) ) goto fail; } } @@ -173,7 +165,7 @@ int show_hr_timestamp_burst( MBG_DEV_HANDLE dh ) { int rc = mbg_get_hr_time_comp( dh, &ht[i], &hns_latency[i] ); - if ( mbg_ioctl_err( rc, "mbg_get_hr_time_comp" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_hr_time_comp" ) ) goto fail; } @@ -196,15 +188,15 @@ fail: static /*HDR*/ int do_mbghrtime( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) { - int supported = 0; - int rc = mbg_dev_has_hr_time( dh, &supported ); + int rc = mbg_chk_dev_has_hr_time( dh ); - if ( mbg_ioctl_err( rc, "mbg_dev_has_hr_time" ) ) - goto done; - - if ( !supported ) + if ( mbg_rc_is_error( rc ) ) { - printf( "High resolution time not supported by this device.\n" ); + if ( rc == MBG_ERR_NOT_SUPP_BY_DEV ) // ### TODO not_supp + printf( "High resolution time not supported by this device.\n" ); + else + mbg_cond_err_msg( rc, "mbg_chk_dev_has_hr_time" ); + goto done; } @@ -214,12 +206,12 @@ int do_mbghrtime( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) show_hr_timestamp( dh ); done: - mbg_close_device( &dh ); - return rc; } // do_mbghrtime +static MBG_DEV_HANDLER_FNC do_mbghrtime; + static /*HDR*/ @@ -235,8 +227,8 @@ void usage( void ) mbg_print_opt_info( "-n num", "run num loops" ); mbg_print_opt_info( "-b", "burst read" ); mbg_print_opt_info( "-r", "read raw time stamps, no cycles" ); - mbg_print_opt_info( "-s num", "sleep num seconds between calls" ); - mbg_print_opt_info( "-u num", "sleep num microseconds between calls" ); + mbg_print_opt_info( "-s num", "sleep num seconds between calls (implies -c)" ); + mbg_print_opt_info( "-u num", "sleep num microseconds between calls (implies -c)" ); mbg_print_opt_info( "-v", "increase verbosity" ); mbg_print_device_options(); puts( "" ); @@ -250,7 +242,7 @@ int main( int argc, char *argv[] ) int rc; int c; - mbg_print_program_info( pname, MBG_MICRO_VERSION, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); + mbg_print_program_info( pname, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); // check command line parameters while ( ( c = getopt( argc, argv, "bcn:rs:u:vh?" ) ) != -1 ) @@ -275,10 +267,12 @@ int main( int argc, char *argv[] ) case 's': sleep_secs = atoi( optarg ); + loops = -1; break; case 'u': sleep_usecs = atoi( optarg ); + loops = -1; break; case 'v': @@ -295,7 +289,7 @@ int main( int argc, char *argv[] ) if ( must_print_usage ) { usage(); - return 1; + return MBG_EXIT_CODE_USAGE; } @@ -312,12 +306,8 @@ int main( int argc, char *argv[] ) #endif - // The function below checks which devices have been specified - // on the command, and for each device - // - tries to open the device - // - shows basic device info - // - calls the function passed as last parameter - rc = mbg_check_devices( argc, argv, optind, do_mbghrtime ); + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbghrtime, 0 ); - return abs( rc ); + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; } diff --git a/mbgirigcfg/mbgirigcfg.c b/mbgirigcfg/mbgirigcfg.c new file mode 100644 index 0000000..72ad3a0 --- /dev/null +++ b/mbgirigcfg/mbgirigcfg.c @@ -0,0 +1,750 @@ + +/************************************************************************** + * + * $Id: mbgirigcfg.c 1.14 2018/11/15 12:12:34Z martin REL_M $ + * + * Description: + * Main file for the mbgirigcfg program which can be used to configure + * the IRIG code frame and the UTC offset of the time contained in the + * IRIG code. + * + * ----------------------------------------------------------------------- + * $Log: mbgirigcfg.c $ + * Revision 1.14 2018/11/15 12:12:34Z martin + * Individual MBG_MICRO_VERSION codes are now obsolete. + * Revision 1.13 2018/01/15 15:16:00 martin + * Let snprint_hours_mins() return an int value. + * Revision 1.12 2017/08/18 08:15:44 martin + * Fixed error handling. + * Revision 1.11 2017/07/05 19:05:27 martin + * New way to maintain version information. + * Support build under Windows. + * New parameter -i to let incoming TFOM flag be ignored. + * Accept parameter -? to print usage. + * Use getopt() for option processing. + * Support multiple devices. + * New parameter -X which set ref offs to 'unconfigured'. + * Support specification of minutes for ref offset. + * Use safe string functions. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. + * Revision 1.10 2009/09/29 15:02:15 martin + * Updated version number to 3.4.0. + * Revision 1.9 2009/07/24 09:50:08 martin + * Updated version number to 3.3.0. + * Revision 1.8 2009/06/19 12:38:51 martin + * Updated version number to 3.2.0. + * Revision 1.7 2009/03/19 17:07:16 martin + * Updated version number to 3.1.0. + * Updated copyright year to include 2009. + * Include mbgtime.h for some symbolic constants. + * Revision 1.6 2008/12/22 12:42:58 martin + * Updated description, copyright, revision number and string. + * Use unified functions from toolutil module. + * Accept device name(s) on the command line. + * Don't use printf() without format, which migth produce warnings + * with newer gcc versions. + * Revision 1.5 2007/07/24 09:34:46 martin + * Changes due to renamed library symbols. + * Updated copyright to include 2007. + * Revision 1.4 2006/08/28 10:08:17 martin + * Display TFOM settings only it the selected IRIG code format supports TFOM. + * Revision 1.3 2006/07/03 13:27:31 martin + * Source code cleanup and fixed a typo. + * Revision 1.2 2004/11/08 15:59:10 martin + * Support separate config of IRIG RX and TX. + * Changes due to renamed symbols. + * Revision 1.1 2003/04/25 10:42:10 martin + * + **************************************************************************/ + +// include Meinberg headers +#include <mbgdevio.h> +#include <mbgutil.h> +#include <mbgtime.h> +#include <pcpsmktm.h> +#include <pcpslstr.h> +#include <myutil.h> +#include <toolutil.h> + +// include system headers +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <time.h> + + +#define MBG_FIRST_COPYRIGHT_YEAR 2003 +#define MBG_LAST_COPYRIGHT_YEAR 0 // use default + +static const char pname[] = "mbgirigcfg"; + + +static int glb_argc; +static char **glb_argv; + +static const char str_yes[] = "YES"; +static const char str_no[] = "NO"; +static const char str_not_supp[] = " (not supp. by this frame type)"; + +static const char info_curr[] = "Current"; +static const char info_new[] = "New"; +static const char msg_rx[] = DEFAULT_OPT_NAME_IRIG_RX_EN; +static const char msg_tx[] = DEFAULT_OPT_NAME_IRIG_TX_EN; + +static IRIG_INFO irig_rx_info; +static IRIG_INFO irig_tx_info; +static MBG_REF_OFFS ref_offs; +static MBG_OPT_INFO opt_info; + +static int cfg_err_rx; +static int cfg_err_tx; +static int changed_cfg_rx; +static int changed_cfg_tx; +static int warned_no_rx; +static int warned_no_tx; + +static int must_print_help_info; + +static const char *icode_rx_names[N_ICODE_RX] = DEFAULT_ICODE_RX_NAMES; +static const char *icode_rx_descr[N_ICODE_RX] = DEFAULT_ICODE_RX_DESCRIPTIONS_ENG; + +static const char *icode_tx_names[N_ICODE_TX] = DEFAULT_ICODE_TX_NAMES; +static const char *icode_tx_descr[N_ICODE_TX] = DEFAULT_ICODE_TX_DESCRIPTIONS_ENG; + +static char str_ref_offs_min[16]; // need to be snprint_hours_mins'ed with -MBG_REF_OFFS_MAX +static char str_ref_offs_max[16]; // need to be snprint_hours_mins'ed with +MBG_REF_OFFS_MAX + + + +static /*HDR*/ +int snprint_hours_mins( char *s, size_t max_len, long num_minutes ) +{ + ldiv_t ldt = ldiv( labs( num_minutes ), MINS_PER_HOUR ); + + size_t n = mbg_snprintf( s, max_len, "%c%li", + ( num_minutes < 0 ) ? '-' : '+', ldt.quot ); + + if ( ldt.rem ) + n += mbg_snprintf( &s[n], max_len - n, ":%02li", ldt.rem ); + + n += mbg_snprintf( &s[n], max_len - n, "h" ); + + return _int_from_size_t( n ); + +} // snprint_hours_mins + + + +static /*HDR*/ +void print_cfg_rx( const char *info, const char *msg ) +{ + int idx = irig_rx_info.settings.icode; + char ws[16]; + const char *cp = NULL; + + printf( "%s %s configuration:\n", info, msg ); + + printf( " " DEFAULT_STR_IRIG_FMT_EN ": %s, %s\n", + icode_rx_names[idx], + icode_rx_descr[idx] + ); + + printf( " " DEFAULT_IGNORE_RX_TFOM_EN ": %s%s\n", + ( irig_rx_info.settings.flags & IFLAGS_DISABLE_TFOM ) ? str_yes : str_no, + ( _idx_bit( idx ) & MSK_ICODE_RX_HAS_TFOM ) ? "" : str_not_supp ); + + printf( " " DEFAULT_STR_IRIG_OFFS_EN ": " ); + + if ( labs( ref_offs ) > MBG_REF_OFFS_MAX ) + cp = "** not configured **"; + else + { + snprint_hours_mins( ws, sizeof( ws ), ref_offs ); + cp = ws; + } + + printf( "%s", cp ); + + if ( ( 1UL << idx ) & MSK_ICODE_RX_HAS_TZI ) + printf( " (ignored with code %s)", icode_rx_names[idx] ); + + printf( "\n" ); + + if ( opt_info.supp_flags & MBG_OPT_FLAG_STR_UTC ) + printf( " " DEFAULT_STR_IRIG_TIMESTR_UTC_EN ": %s\n", + ( opt_info.settings.flags & MBG_OPT_FLAG_STR_UTC ) ? + str_yes : str_no ); + +} // print_cfg_rx + + + +static /*HDR*/ +void print_cfg_tx( const char *info, const char *msg ) +{ + int idx = irig_tx_info.settings.icode; + + printf( "%s %s configuration:\n", info, msg ); + + printf( " " DEFAULT_STR_IRIG_FMT_EN ": %s, %s\n", + icode_tx_names[idx], + icode_tx_descr[idx] + ); + + printf( " " DEFAULT_STR_TFOM_ALWAYS_SYNC_EN ": %s%s\n", + ( irig_tx_info.settings.flags & IFLAGS_DISABLE_TFOM ) ? str_yes : str_no, + ( _idx_bit( idx ) & MSK_ICODE_TX_HAS_TFOM ) ? "" : str_not_supp ); + + printf( " " DEFAULT_STR_IRIG_OUTPUT_LOC_TM_EN ": %s\n", + ( irig_tx_info.settings.flags & IFLAGS_TX_GEN_LOCAL_TIME ) ? + str_yes : str_no + ); + +} // print_cfg_tx + + + +static /*HDR*/ +void set_new_icode_rx( char *s ) +{ + int idx = atoi( s ); + + if ( idx >= N_ICODE_RX ) + { + fprintf( stderr, "** IRIG RX code index %i is out of range (0..%i).\n", + idx, N_ICODE_RX - 1 ); + cfg_err_rx = 1; + return; + } + + if ( _is_supported( idx, irig_rx_info.supp_codes ) ) + { + irig_rx_info.settings.icode = idx; + changed_cfg_rx = 1; + } + else + { + fprintf( stderr, "** IRIG RX code \"%s\" not supported by this device.\n", + icode_rx_names[idx] ); + cfg_err_rx = 1; + } + +} // set_new_icode_rx + + + +static /*HDR*/ +void set_new_ref_offs( char *s ) +{ + long new_ref_offs; + char *cp = s; + int is_negative = 0; + + // expected format: [-]hh[:mm] + + // In case of e.g. "-0:30" conversion of the first part "-0" would yield + // 0 and thus the sign would get lost, so we check the sign explicitly. + if ( *cp == '-' ) + is_negative = 1; + + new_ref_offs = strtol( cp, &cp, 10 ); + + if ( cp == s ) // no number found at beginning + goto invalid; + + new_ref_offs *= MINS_PER_HOUR; + + if ( *cp++ == ':' ) // offset minutes seem to follow + { + long tmp = strtol( cp, &cp, 10 ); + + // the value behind the colon should always be positive + if ( tmp < 0 || tmp >= MINS_PER_HOUR ) + goto invalid; + + // apply the minutes offset according to the sign + new_ref_offs += is_negative ? -tmp : tmp; + } + + if ( labs( new_ref_offs ) > MBG_REF_OFFS_MAX ) + { + char ws[16]; + snprint_hours_mins( ws, sizeof( ws ), new_ref_offs ); + fprintf( stderr, "** New IRIG time offset %s exceeds range (%s..%s).\n", + ws, str_ref_offs_min, str_ref_offs_max ); + goto invalid; + } + + ref_offs = (MBG_REF_OFFS) new_ref_offs; + changed_cfg_rx = 1; + + return; + + +invalid: + cfg_err_rx = 1; + +} // set_new_ref_offs + + + +static /*HDR*/ +void set_ref_offs_not_cfgd( void ) +{ + ref_offs = MBG_REF_OFFS_NOT_CFGD; + changed_cfg_rx = 1; + +} // set_ref_offs_not_cfgd + + + +static /*HDR*/ +void set_new_str_utc( char *s ) +{ + int this_cfg_err; + + if ( !( opt_info.supp_flags & MBG_OPT_FLAG_STR_UTC ) ) + return; // not supported + + + this_cfg_err = 0; + + if ( strcmp( s, "1" ) == 0 ) + opt_info.settings.flags |= MBG_OPT_FLAG_STR_UTC; + else + if ( strcmp( s, "0" ) == 0 ) + opt_info.settings.flags &= ~MBG_OPT_FLAG_STR_UTC; + else + this_cfg_err = 1; + + if ( this_cfg_err ) + cfg_err_rx = 1; + else + changed_cfg_rx = 1; + +} // set_new_str_utc + + + +static /*HDR*/ +void set_new_icode_tx( char *s ) +{ + int idx = atoi( s ); + + if ( idx >= N_ICODE_TX ) + { + fprintf( stderr, "** IRIG TX code index %i is out of range (0..%i).\n", + idx, N_ICODE_TX - 1 ); + cfg_err_tx = 1; + return; + } + + if ( _is_supported( idx, irig_tx_info.supp_codes ) ) + { + irig_tx_info.settings.icode = idx; + changed_cfg_tx = 1; + } + else + { + fprintf( stderr, "** IRIG TX code \"%s\" not supported by this device.\n", + icode_tx_names[idx] ); + cfg_err_tx = 1; + } + +} // set_new_icode_tx + + + +static /*HDR*/ +void set_new_irig_tx_local( char *s ) +{ + int this_cfg_err = 0; + + if ( strcmp( s, "1" ) == 0 ) + irig_tx_info.settings.flags |= IFLAGS_TX_GEN_LOCAL_TIME; + else + if ( strcmp( s, "0" ) == 0 ) + irig_tx_info.settings.flags &= ~IFLAGS_TX_GEN_LOCAL_TIME; + else + this_cfg_err = 1; + + if ( this_cfg_err ) + cfg_err_tx = 1; + else + changed_cfg_tx = 1; + +} // set_new_irig_tx_local + + + +static /*HDR*/ +void set_new_tfom_flag( char *s, IRIG_SETTINGS *p, int *changed_flag, int *err_flag ) +{ + if ( !(_idx_bit( p->icode ) & MSK_ICODE_TX_HAS_TFOM ) ) + return; // not supported + + + if ( strcmp( s, "1" ) == 0 ) + p->flags |= IFLAGS_DISABLE_TFOM; + else + if ( strcmp( s, "0" ) == 0 ) + p->flags &= ~IFLAGS_DISABLE_TFOM; + else + { + *err_flag = 1; + return; + } + + *changed_flag = 1; + +} // set_new_tfom_flag + + + +static /*HDR*/ +int chk_dev_rx( const PCPS_DEV *p_dev ) +{ + if ( p_dev ) + { + if ( _pcps_is_irig_rx( p_dev ) ) + return 1; + + if ( !warned_no_rx ) + { + fprintf( stderr, "** This device does not provide an IRIG input.\n" ); + warned_no_rx = 1; + } + + cfg_err_rx = 1; + } + + return 0; + +} // chk_dev_rx + + + +static /*HDR*/ +int chk_dev_tx( const PCPS_DEV *p_dev ) +{ + if ( p_dev ) + { + if ( _pcps_has_irig_tx( p_dev ) ) + return 1; + + if ( !warned_no_tx ) + { + fprintf( stderr, "** This device does not provide an IRIG output.\n" ); + warned_no_tx = 1; + } + + cfg_err_tx = 1; + } + + return 0; + +} // chk_dev_tx + + + +static /*HDR*/ +void check_cmd_line( int argc, char *argv[], const PCPS_DEV *p_dev ) +{ + int c; + + // force checking all parameters since this may be called several times + optind = 1; + + while ( ( c = getopt( argc, argv, "h?" "r:o:u:i:X" "t:l:s:" ) ) != -1 ) + { + switch ( c ) + { + case '?': + case 'h': + must_print_usage = 1; + break; + + + // IRIG receiver options + + case 'r': // IRIG RX code frame + if ( chk_dev_rx( p_dev ) ) + set_new_icode_rx( optarg ); + break; + + case 'o': // incoming time offset from UTC + if ( chk_dev_rx( p_dev ) ) + set_new_ref_offs( optarg ); + break; + + case 'u': // option flag: serial output is always UTC + if ( chk_dev_rx( p_dev ) ) + set_new_str_utc( optarg ); + break; + + case 'i': // option flag: ignore incoming TFOM flag, alway sync + if ( chk_dev_rx( p_dev ) ) + set_new_tfom_flag( optarg, &irig_rx_info.settings, &changed_cfg_rx, &cfg_err_rx ); + break; + + case 'X': // set UTC ref_offs to "not configured" + if ( chk_dev_rx( p_dev ) ) + set_ref_offs_not_cfgd(); + break; + + + // IRIG output options + + case 't': // IRIG TX code frame + if ( chk_dev_tx( p_dev ) ) + set_new_icode_tx( optarg ); + break; + + case 'l': // option flag: transmit local time, not UTC + if ( chk_dev_tx( p_dev ) ) + set_new_irig_tx_local( optarg ); + break; + + case 's': // option flag: send TFOM as always "sync" + if ( chk_dev_tx( p_dev ) ) + set_new_tfom_flag( optarg, &irig_tx_info.settings, &changed_cfg_tx, &cfg_err_tx ); + break; + + } // switch + + } + +} // check_cmd_line + + + +static /*HDR*/ +void usage( void ) +{ + const char *frame_fmt = " %4i %s, %s\n"; + int i; + + printf( + "Usage: %s [-h]|[option] [option] ...\n" + "\n", + pname + ); + + printf( + " -h or -? prints this info\n" + "\n" + ); + + + printf( + "Options supported by IRIG receivers:\n" + "\n" + ); + + printf( + " -r code specifies the IRIG receiver code format, where \"code\" \n" + " can be one a number according to the table below:\n" + ); + + for ( i = 0; i < N_ICODE_RX; i++ ) + printf( frame_fmt, i, icode_rx_names[i], icode_rx_descr[i] ); + + printf( "\n" ); + + printf( + " -o offs specifies the IRIG input time offset from UTC, in hours and optional minute,\n" + " where \"offs\" can be a value in the range %s .. %s.\n" + " When the device is shipped this parameter is set to \"not configured\"\n" + " to prevent the receiver from synchronizing to an IRIG input signal with\n" + " unknown UTC offset immediately after installation, which could cause\n" + " the system time to be set wrong by the time synchronization software.\n" + "\n", + str_ref_offs_min, str_ref_offs_max + ); + + printf( + " -X set the IRIG input time offset from UTC to \"not configured\".\n" + " See also the -o option.\n" + "\n" + ); + + printf( + " -u flag determines whether the time string sent via the\n" + " board's serial output contains always UTC time\n" + " or the same time as received from the IRIG input\n" + " signal. \"flag\" can be \"1\" for always UTC,\n" + " or \"0\" for IRIG time.\n" + "\n" + ); + + printf( + " -i flag If \"flag\" is set to \"1\" then the TFOM qualifier in the\n" + " incoming IRIG signal is ignored, i.e. the receiver even synchronizes\n" + " to an input signal if the TFOM codes says the generator is freewheeling.\n" + " Please note that most IRIG codes do not support a TFOM qualifier.\n" + "\n" + ); + + + printf( + "Options supported by IRIG transmitters:\n" + "\n" + ); + + printf( + " -t code specifies the IRIG transmitter code format, where \"code\" \n" + " can be one a number according to the table below:\n" + ); + + for ( i = 0; i < N_ICODE_TX; i++ ) + printf( frame_fmt, i, icode_tx_names[i], icode_tx_descr[i] ); + + printf( "\n" ); + + printf( + " -l flag determines whether IRIG output shall contain local\n" + " time, or UTC. \"flag\" must be \"1\" for local time,\n" + " or \"0\" for UTC.\n" + "\n" + ); + + printf( + " -s flag If \"flag\" is set to \"1\" then the TFOM qualifier in the\n" + " IRIG output is always set to \"synchronized\". If it is \"0\" \n" + " then the qualifier reflects the current status of the input signal.\n" + " Please note that most IRIG codes do not support a TFOM qualifier.\n" + "\n" + ); + + + printf( + "If no parameters are given the program reports the current settings.\n" + "Please note that not all IRIG codes must be supported by all devices.\n" + ); + +} // usage + + + +static /*HDR*/ +int do_mbgirigcfg( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) +{ + int rc = MBG_SUCCESS; + + cfg_err_rx = 0; + cfg_err_tx = 0; + changed_cfg_rx = 0; + changed_cfg_tx = 0; + warned_no_rx = 0; + warned_no_tx = 0; + + + if ( !_pcps_has_irig( p_dev ) ) + { + fprintf( stderr, "** This device does not provide an IRIG input or output.\n" ); + rc = MBG_ERR_NOT_SUPP_BY_DEV; + must_print_help_info = 1; + goto done; + } + + if ( _pcps_is_irig_rx( p_dev ) ) + { + rc = mbg_get_all_irig_rx_info( dh, p_dev, &irig_rx_info, + &ref_offs, &opt_info ); + if ( mbg_cond_err_msg( rc, "read IRIG input configuration" ) ) + goto done; + } + + if ( _pcps_has_irig_tx( p_dev ) ) + { + rc = mbg_get_irig_tx_info( dh, &irig_tx_info ); + + if ( mbg_cond_err_msg( rc, "read IRIG output configuration" ) ) + goto done; + } + + check_cmd_line( glb_argc, glb_argv, p_dev ); + + if ( cfg_err_rx || cfg_err_tx ) + { + printf( "** Invalid configuration options specified.\n" ); + must_print_help_info = 1; + rc = MBG_ERR_CFG; + goto done; + } + + if ( changed_cfg_rx ) + { + if ( chk_dev_rx( p_dev ) ) + { + print_cfg_rx( info_new, msg_rx ); + + rc = mbg_save_all_irig_rx_settings( dh, p_dev, &irig_rx_info.settings, + &ref_offs, &opt_info.settings ); + if ( mbg_cond_err_msg( rc, "write IRIG input configuration" ) ) + goto done; + } + } + else // RX cfg not changed + if ( _pcps_is_irig_rx( p_dev ) ) + print_cfg_rx( info_curr, msg_rx ); + + + if ( changed_cfg_tx ) + { + if ( chk_dev_tx( p_dev ) ) + { + print_cfg_tx( info_new, msg_tx ); + + rc = mbg_set_irig_tx_settings( dh, &irig_tx_info.settings ); + + if ( mbg_cond_err_msg( rc, "write IRIG output configuration" ) ) + goto done; + } + } + else + if ( _pcps_has_irig_tx( p_dev ) ) + print_cfg_tx( info_curr, msg_tx ); + +done: + return rc; + +} // do_mbgirigcfg + +static MBG_DEV_HANDLER_FNC do_mbgirigcfg; + + + +int main( int argc, char *argv[] ) +{ + int rc; + + mbg_print_program_info( pname, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); + + snprint_hours_mins( str_ref_offs_min, sizeof( str_ref_offs_min ), -MBG_REF_OFFS_MAX ); + snprint_hours_mins( str_ref_offs_max, sizeof( str_ref_offs_max ), MBG_REF_OFFS_MAX ); + + check_cmd_line( argc, argv, NULL ); + + if ( must_print_usage ) + { + usage(); + return MBG_EXIT_CODE_USAGE; + } + + + // We work with copies of the arguments here since the arguments + // are evaluated once more for each device. + glb_argc = argc; + glb_argv = argv; + + // Handle each of the specified devices. + rc = mbg_handle_devices( glb_argc, glb_argv, optind, do_mbgirigcfg, 0 ); + + if ( must_print_help_info ) + printf( "For help type \"%s -h\"\n\n", pname ); + + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; +} diff --git a/mbglib/common/cfg_hlp.c b/mbglib/common/cfg_hlp.c new file mode 100644 index 0000000..5be0080 --- /dev/null +++ b/mbglib/common/cfg_hlp.c @@ -0,0 +1,1818 @@ + +/************************************************************************** + * + * $Id: cfg_hlp.c 1.4 2018/09/19 16:55:08Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Meinberg device configuration helper functions. + * + * ----------------------------------------------------------------------- + * $Log: cfg_hlp.c $ + * 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 + * Renamed setup_port_info_from_port_settings() + * to setup_port_info_from_port_parm(). + * Added function chk_dev_receiver_info(). + * Function free_all_firmware_info() added by thomas-b. + * Syslog option added to monitoring feature by philipp. + * I/O helper structures and API refuctored by philipp. + * Service feature and API added by philipp. + * Database feature support added by philipp. + * Function to free ALL_USER_INFO structure added by thomas-b. + * MBG_EVENT stuff integrated with common/general monitoring + * stuff by philipp. + * Monitoring events refactored and tainted config support + * added by philipp. + * Account for renamed library symbol NSEC_PER_SEC. + * Documented some conversion functions for legacy parameters. + * Doxygen fixes. + * Revision 1.2 2017/07/05 12:17:38 martin + * Support functions for TLV, IMS, GPIO, and + * mbg_snprint_revision() provided by philipp. + * Support functions for network configuration, + * NTP configuration, ALL_UCAP stuff, SNMP and + * MONITORING, as well as ALL_PTP_V2_COMMON_DATASETS + * and ALL_PTP_V1_COMMON_DATASETS provided by thomas-b. + * Support functions for xmulti_ref and IO PORT stuff + * provided by philipp and thomas-b. + * More common GNSS support. + * New functions alloc_dev_hw_id() and chk_free_dev_hw_id(). + * Tried portable printing of int64_t types. + * Account for frac_sec_from_bin() obsoleted by + * bin_frac_32_to_dec_frac(). + * Revision 1.1 2014/04/25 09:14:49 martin + * Initial revision. + * + **************************************************************************/ + +#define _CFG_HLP + #include <cfg_hlp.h> +#undef _CFG_HLP + +#include <mbgerror.h> +#include <timeutil.h> +#include <str_util.h> +#include <myutil.h> +#include <mbgtime.h> + +#if defined( _PRELIMINARY_CODE ) + #include <mbgmktm.h> +#endif + +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <time.h> + + + +/*HDR*/ +/** + * @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 + * contains an identifier string. + * + * 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. + * + * @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 + */ +int chk_sw_rev_name( SW_REV *p, int verbose ) +{ + if ( verbose > 1 ) // more than just verbose + return 1; // just return raw string + + trim_whitespace( p->name ); + + // Some firmware versions have "CC_STANDARD" in their standard version, + // which doesn't provide any valuable information. + // We discard this by default. + if ( strstr( p->name, "CC_STANDARD" ) ) + p->name[0] = 0; + + if ( verbose ) + return 1; // calling app should display string, even if empty + + // calling app should display string only if not empty + return strlen( p->name ) != 0; + +} // chk_sw_rev_name + + + +/*HDR*/ +int get_str_idx( const char *search, + const char *str_table[], + int n_entries ) +{ + int i; + + for ( i = 0; i < n_entries; i++ ) + if ( strcmp( search, str_table[i] ) == 0 ) + return i; + + return -1; + +} // get_str_idx + + + +/*HDR*/ +int get_baud_rate_idx( BAUD_RATE baud_rate ) +{ + int i; + + for ( i = 0; i < N_MBG_BAUD_RATES; i++ ) + if ( baud_rate == mbg_baud_rates[i] ) + return i; + + return -1; + +} // get_baud_rate_idx + + + +/*HDR*/ +int get_framing_idx( const char *framing ) +{ + return get_str_idx( framing, mbg_framing_strs, N_MBG_FRAMINGS ); + +} // get_framing_idx + + + +/*HDR*/ +/** + * @brief Convert ::PORT_PARM::mode to ::PORT_SETTINGS::mode + * + * This function is used to evaluate the code from a mode field of a legacy + * ::PORT_PARM structure and set up the appropriate fields in a ::PORT_SETTINGS + * structure accordingly. + * + * @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 + * a capture string mode. Usually 1 for legacy devices. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::port_parm_mode_from_port_settings (the complementary function) + * @see ::port_settings_from_port_parm + */ +void port_settings_from_port_parm_mode( PORT_SETTINGS *p_ps, uint8_t pp_mode, + int cap_str_idx ) +{ + if ( pp_mode >= LGCY_STR_UCAP ) + { + // If @p 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 + // usually has index 1 for legacy devices. + p_ps->str_type = cap_str_idx; + p_ps->mode = ( pp_mode == LGCY_STR_UCAP ) ? STR_AUTO : STR_ON_REQ; + } + else + { + // If @p 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. + // The mode numbers are compatible in this case. + p_ps->str_type = 0; + p_ps->mode = pp_mode; + } + +} // port_settings_from_port_parm_mode + + + +/*HDR*/ +/** + * @brief Convert a ::PORT_SETTINGS::mode to a legacy ::PORT_PARM::mode + * + * This function is used to derive a a legacy ::PORT_PARM::mode value + * from a ::PORT_SETTINGS structure. + * + * @param[out] pp_mode Pointer to a ::PORT_PARM::mode variable to be updated. + * @param[in] p_ps Pointer to a ::PORT_SETTINGS structure to be evaluated. + * @param[in] cap_str_idx The capture string index number for legacy devices, which is usually 1. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::port_settings_from_port_parm_mode (the complementary function) + * @see ::port_parm_from_port_settings + */ +void port_parm_mode_from_port_settings( uint8_t *pp_mode, const PORT_SETTINGS *p_ps, + int cap_str_idx ) +{ + if ( p_ps->str_type == cap_str_idx ) + { + // If the string type is a capture string + // then convert the mode accordingly. + *pp_mode = ( p_ps->mode == STR_ON_REQ ) ? LGCY_STR_UCAP_REQ : LGCY_STR_UCAP; + } + else + { + // Other string modes are compatible, so just copy the mode. + *pp_mode = p_ps->mode; + } + +} // port_parm_mode_from_port_settings + + + +/*HDR*/ +/** + * @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. + * @param[in] p_pp The ::PORT_PARM structure to be evaluated, contains settings for 2 ports. + * @param[in] cap_str_idx The capture string index number for legacy devices, which is usually 1. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::port_parm_from_port_settings (the complementary function) + * @see ::port_settings_from_port_parm_mode + */ +void port_settings_from_port_parm( PORT_SETTINGS *p_ps, int port_idx, + const PORT_PARM *p_pp, int cap_str_idx ) +{ + // The basic serial settings can simply be copied. + p_ps->parm = p_pp->com[port_idx]; + + // The string mode may need to be translated. + port_settings_from_port_parm_mode( p_ps, p_pp->mode[port_idx], + cap_str_idx ); + +} // port_info_from_port_parm + + + +/*HDR*/ +/** + * @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. + * @param[out] p_ps Pointer to a ::PORT_SETTINGS structure to be updated. + * @param[in] cap_str_idx The capture string index number for legacy devices, which is usually 1. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::port_settings_from_port_parm (the complementary function) + * @see ::port_parm_mode_from_port_settings + */ +void port_parm_from_port_settings( PORT_PARM *p_pp, int port_idx, + const PORT_SETTINGS *p_ps, int cap_str_idx ) +{ + // The basic serial settings can simply be copied. + p_pp->com[port_idx] = p_ps->parm; + + // The string mode may need to be translated. + port_parm_mode_from_port_settings( &p_pp->mode[port_idx], + p_ps, cap_str_idx ); + +} // port_parm_from_port_settings + + + +/*HDR*/ +uint32_t check_valid_port_info( const PORT_INFO *p_pi, + const STR_TYPE_INFO_IDX str_type_info_idx[], + int n_str_type ) +{ + const PORT_SETTINGS *p_ps = &p_pi->port_settings; + int idx; + uint32_t flags = 0; + + + if ( p_pi->supp_baud_rates & ~_mask( N_MBG_BAUD_RATES ) ) + flags |= MBG_PS_MSK_BAUD_RATE_OVR_SW; // dev. supports more baud rates than driver + + idx = get_baud_rate_idx( p_ps->parm.baud_rate ); + + if ( !_inrange( idx, 0, N_MBG_BAUD_RATES ) || + !_is_supported( idx, p_pi->supp_baud_rates ) ) + flags |= MBG_PS_MSK_BAUD_RATE; + + + if ( p_pi->supp_framings & ~_mask( N_MBG_FRAMINGS ) ) + flags |= MBG_PS_MSK_FRAMING_OVR_SW; // dev. supports more framings than driver + + idx = get_framing_idx( p_ps->parm.framing ); + + if ( !_inrange( idx, 0, N_MBG_FRAMINGS ) || + !_is_supported( idx, p_pi->supp_framings ) ) + flags |= MBG_PS_MSK_FRAMING; + + + if ( p_ps->parm.handshake >= N_COM_HS ) + flags |= MBG_PS_MSK_HS_OVR_SW; // handshake index exceeds max. + + if ( p_ps->parm.handshake != HS_NONE ) // currently no device supports any handshake + flags |= MBG_PS_MSK_HS; // handshake mode not supp. by dev. + + + if ( p_pi->supp_str_types & ~_mask( n_str_type ) ) + flags |= MBG_PS_MSK_STR_TYPE_OVR_SW; // firmware error: more string types supported than reported + + idx = p_ps->str_type; + + if ( idx >= n_str_type ) + flags |= MBG_PS_MSK_STR_TYPE_OVR_DEV; // string type index exceeds max. + else + { + if ( !_is_supported( idx, p_pi->supp_str_types ) ) + flags |= MBG_PS_MSK_STR_TYPE; // string type not supported by this port + else + { + // Use the str_type index to get the supported output mode mask + // from the string type info table. This is required to check + // whether the selected mode is supported by the selected + // string type. + ulong supp_modes = str_type_info_idx[idx].str_type_info.supp_modes; + + if ( supp_modes & ~_mask( N_STR_MODE ) ) + flags |= MBG_PS_MSK_STR_MODE_OVR_SW; // dev. supports more string modes than driver + + idx = p_ps->mode; + + if ( idx >= N_STR_MODE ) // mode is always >= 0 + flags |= MBG_PS_MSK_STR_MODE_OVR_SW; // string mode index exceeds max. + else + if ( !_is_supported( idx, supp_modes ) ) + flags |= MBG_PS_MSK_STR_MODE; // string mode not supp. by this string type and port + } + } + + + if ( p_ps->flags != 0 ) /* currently always 0 */ + flags |= MBG_PS_MSK_FLAGS_OVR_SW | MBG_PS_MSK_FLAGS; + + + return flags; + +} // check_valid_port_info + + + +/*HDR*/ +int 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; + +} // valid_port_info + + + +/*HDR*/ +/** + * @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 + * associated settings, and fills up the remaining ::PORT_INFO fields with + * the well-known supported settings, so applications can simple 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[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_parm ::FIXME + */ +int setup_port_info_from_port_parm( PORT_INFO_IDX pii[], const PORT_PARM *p_pp, + const RECEIVER_INFO *p_ri ) +{ + int i; + + for ( i = 0; i < p_ri->n_com_ports; i++ ) + { + PORT_INFO_IDX *p_pii = &pii[i]; + PORT_INFO *p_pi = &p_pii->port_info; + + p_pii->idx = i; + port_settings_from_port_parm( &p_pi->port_settings, i, p_pp, 1 ); + + p_pi->supp_baud_rates = DEFAULT_GPS_BAUD_RATES_C166; + p_pi->supp_framings = DEFAULT_GPS_FRAMINGS_C166; + p_pi->supp_str_types = DEFAULT_SUPP_STR_TYPES_GPS; + } + + return MBG_SUCCESS; + +} // setup_port_info_from_port_parm + + + +/*HDR*/ +int setup_default_str_type_info_idx( STR_TYPE_INFO_IDX stii[], const RECEIVER_INFO *p_ri ) +{ + int i; + + for ( i = 0; i < p_ri->n_str_type; i++ ) + { + STR_TYPE_INFO_IDX *stip = &stii[i]; + stip->idx = i; + stip->str_type_info = default_str_type_info[i]; + } + + return MBG_SUCCESS; + +} // setup_default_str_type_info_idx + + + +/*HDR*/ +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 ); + + if ( p_agi->n_gnss_supp > N_GNSS_TYPES ) + return MBG_ERR_N_GNSS_EXCEEDS_SUPP; + + return MBG_SUCCESS; + +} // chk_set_n_gnss_supp + + + +/*HDR*/ +/** + * @brief + * + * ### Setup GNSS info from stat_info so we can use the same printing routine + */ +void setup_gps_only_sat_info_idx_from_statinfo( 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]; + GNSS_SAT_INFO *p_gsi = &p_gsii->gnss_sat_info; + + memset( p_gsii, 0, sizeof( *p_gsii ) ); + p_gsii->idx = GNSS_TYPE_GPS; + + p_gsi->gnss_type = GNSS_TYPE_GPS; + 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 + + + +/*HDR*/ +/** + * @brief + * + * Setup GNSS info from stat_info so we can use the same printing routine + */ +int setup_gps_only_gnss_info_from_statinfo( ALL_GNSS_INFO *p_agi ) +{ + MBG_GNSS_MODE_INFO *p_gmi = &p_agi->gnss_mode_info; + + memset( p_gmi, 0, sizeof( *p_gmi ) ); + + p_gmi->supp_gnss_types = MBG_GNSS_TYPE_MSK_GPS; + p_gmi->settings.gnss_set = p_gmi->supp_gnss_types; + + 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 ); + + return chk_set_n_gnss_supp( p_agi ); + +} // setup_gps_only_gnss_info_from_statinfo + + + +/*HDR*/ +void chk_free_dev_hw_id( DEVICE_INFO *p ) +{ + if ( p->hw_id ) + { + free( p->hw_id ); + p->hw_id = NULL; + } + +} // chk_free_dev_hw_id + + + +/*HDR*/ +int alloc_dev_hw_id( DEVICE_INFO *p, size_t len ) +{ + if ( p->hw_id ) + return MBG_ERR_ALREADY_ALLOC; + + + p->hw_id = (char *) malloc( len ); + + if ( p->hw_id == NULL ) + return MBG_ERR_NO_MEM; + + return MBG_SUCCESS; + +} // alloc_dev_hw_id + + + +/*HDR*/ +const char *get_fw_id_from_hw_id( const char *hw_id ) +{ + int i; + + for ( i = 0; i < N_SUPP_DEV_TOTAL; i++ ) + { + DEVICE_INFO *p = &device_list[i]; + + if ( strlen( p->fw_id ) && p->hw_id ) //### TODO check if this still works as expected + { + if ( strcmp( hw_id, p->hw_id ) == 0 ) + { + if ( strlen( p->fw_id ) > 0 ) + return p->fw_id; + + #if defined( DEBUG ) + fprintf( stderr, "Length of fw_id is 0 in %s for device %i (%s)\n", + __func__, i, p->hw_id ); + #endif + } + } + } + + return NULL; + +} // get_fw_id_from_hw_id + + + +/*HDR*/ +const char *get_hw_id_from_fw_id( const char *fw_id ) +{ + int i; + + for ( i = 0; i < N_SUPP_DEV_TOTAL; i++ ) + { + DEVICE_INFO *p = &device_list[i]; + + if ( strlen( p->fw_id ) && p->hw_id ) //### TODO check if this still works as expected + { + if ( strcmp( fw_id, p->fw_id ) == 0 ) + { + if ( strlen( p->hw_id ) > 0 ) + return p->hw_id; + + #if defined( DEBUG ) + fprintf( stderr, "Length of hw_id is 0 in %s for device %i (%s)\n", + __func__, i, p->fw_id ); + #endif + } + } + } + + return NULL; + +} // get_hw_id_from_fw_id + + + +/*HDR*/ +/** + * @brief Returns 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) + * + * @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 ) +{ + unsigned i; + MBG_IO_PORT_TYPE_INFO *pti; + + if ( !port ) + return NULL; + + for ( i = 0; i < port->p_info.num_types; ++i ) + { + pti = &port->pt_infos[i]; + + if ( pti->port_type == port_type ) + { + if ( pti->port_type == MBG_IO_PORT_TYPE_GPIO ) + { + if ( pti->data.gpio_limits.type == port->setts->data.gpio_settings.type ) + return pti; + } + else + return pti; + } + } + + return NULL; + +} // get_io_port_type_info + + + +/*HDR*/ +/** + * @brief Initializes 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 + */ +void mbg_tlv_announce_init( MBG_TLV_ANNOUNCE *tlv, MBG_TLV_UID uid, + MBG_TLV_TYPE tlv_feat_type, uint32_t total_bytes ) +{ + memset( tlv, 0, sizeof( *tlv ) ); + tlv->data.uid = uid; + tlv->data.type = tlv_feat_type; + tlv->data.total_bytes = total_bytes; + tlv->data.reserved_1 = 0; + tlv->reserved_1 = 0; + tlv->reserved_2 = 0; + +} // mbg_tlv_announce_init + + + +/*HDR*/ +/** + * @brief Initializes a ::MBG_TLV + * + * @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) + */ +void mbg_tlv_init( MBG_TLV *tlv, MBG_TLV_UID uid, + MBG_TLV_TYPE tlv_type, uint32_t total_bytes ) +{ + memset( tlv, 0, sizeof( *tlv ) ); + tlv->hdr.uid = uid; + tlv->hdr.tlv_type = tlv_type; + tlv->hdr.cur_bytes = 0; + tlv->hdr.trans_bytes = 0; + tlv->hdr.total_bytes = total_bytes; + tlv->hdr.reserved_1 = 0; + tlv->hdr.reserved_2 = 0; + tlv->hdr.reserved_3 = 0; + +} // mbg_tlv_init + + + +/*HDR*/ +/** + * @brief Initializes ::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) + */ +void mbg_tlv_rcv_state_init( MBG_TLV_RCV_STATE *state, MBG_TLV_UID uid, uint32_t total_bytes ) +{ + state->data.uid = uid; + state->data.type = 0; + state->data.total_bytes = total_bytes; + state->data.reserved_1 = 0; + state->read_bytes = 0; + state->reserved_1 = 0; + +} // mbg_tlv_state_init + + + +/*HDR*/ +int mbg_snprint_revision( char *buf, size_t buflen, + const char *prefix, const char *suffix, + uint32_t rev) +{ + size_t bytes = 0; + uint32_t major, minor, patch; + + if ( prefix ) + bytes += snprintf_safe( &buf[bytes], buflen, "%s", prefix ); + + _mbg_decode_revision( rev, major, minor, patch ); + bytes += snprintf_safe( &buf[bytes], buflen - bytes, "%u.%u.%u", + major, minor, patch); + + if ( suffix ) + bytes += snprintf_safe( &buf[bytes], buflen - bytes, "%s", suffix ); + + return _int_from_size_t( bytes ); + +} // mbg_snprint_revision + + + +/*HDR*/ +_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 + // as the current device. + if ( p->n_com_ports > MAX_PARM_PORT ) + return MBG_ERR_N_COM_EXCEEDS_SUPP; + + // Make sure this program supports at least as many string types + // as the current device. + if ( p->n_str_type > MAX_PARM_STR_TYPE ) + return MBG_ERR_N_STR_EXCEEDS_SUPP; + + // Make sure this program supports at least as many programmable + // outputs as the current device. + if ( p->n_prg_out > MAX_PARM_POUT ) + return MBG_ERR_N_STR_EXCEEDS_SUPP; + + return MBG_SUCCESS; + +} // chk_dev_receiver_info + + + +/*HDR*/ +_NO_MBG_API_ATTR int _MBG_API chk_dev_xbp_supp_nodes( const ALL_XBP_INFO *info ) +{ + if ( info ) + { + if ( ( info->limits.features & XBP_FEAT_MASK_NODES ) == XBP_FEAT_MASK_NODES ) + return MBG_SUCCESS; + + return MBG_ERR_NOT_SUPP_BY_DEV; + } + + return MBG_ERR_INV_PARM; + +} // chk_dev_xbp_supp_nodes + + + +/*HDR*/ +_NO_MBG_API_ATTR int _MBG_API chk_dev_net_cfg_supp_stage_2( const ALL_NET_CFG_INFO *info ) +{ + if ( info->glb_cfg_info.feat_flags & MBG_NET_GLB_SUPP_STAGE_2_MASK ) + return MBG_SUCCESS; + + return MBG_ERR_NOT_SUPP_BY_DEV; + +} // chk_dev_net_cfg_supp_stage_2 + + + +/*HDR*/ +_NO_MBG_API_ATTR int _MBG_API chk_dev_ntp_supp_client( const ALL_NTP_CFG_INFO *info ) +{ + if ( ( ( info->glb_info.supp_ntp_roles & NTP_MSK_ROLE_CLIENT ) == NTP_MSK_ROLE_CLIENT ) || + ( ( info->glb_info.supp_ntp_roles & NTP_MSK_ROLE_CLIENT_SERVER ) == NTP_MSK_ROLE_CLIENT_SERVER ) ) + return MBG_SUCCESS; + + return MBG_ERR_NOT_SUPP_BY_DEV; + +} // chk_dev_ntp_supp_client + + +/*HDR*/ +_NO_MBG_API_ATTR int _MBG_API chk_dev_ntp_supp_server( const ALL_NTP_CFG_INFO *info ) +{ + if ( ( ( info->glb_info.supp_ntp_roles & NTP_MSK_ROLE_SERVER ) == NTP_MSK_ROLE_SERVER ) || + ( ( info->glb_info.supp_ntp_roles & NTP_MSK_ROLE_CLIENT_SERVER ) == NTP_MSK_ROLE_CLIENT_SERVER ) ) + return MBG_SUCCESS; + + return MBG_ERR_NOT_SUPP_BY_DEV; + +} // chk_dev_ntp_supp_server + + +/*HDR*/ +_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 MBG_ERR_NOT_SUPP_BY_DEV; + +} // chk_dev_xmulti_ref_supp_mrf_none + + +/*HDR*/ +_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 MBG_ERR_NOT_SUPP_BY_DEV; + +} // chk_dev_xmulti_ref_supp_ext_src_info + + +/*HDR*/ +_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 MBG_ERR_NOT_SUPP_BY_DEV; + +} // 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 + */ +_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 MBG_ERR_NOT_SUPP_BY_DEV; + +} // 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 + */ +_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 MBG_ERR_NOT_SUPP_BY_DEV; + +} // 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 ) + return MBG_SUCCESS; + + return MBG_ERR_NOT_SUPP_BY_DEV; + +} // chk_dev_ims_has_fdm + + +/*HDR*/ +_NO_MBG_API_ATTR int _MBG_API chk_dev_ims_is_volt_out_enabled( const ALL_IMS_STATE *ims_state, unsigned idx ) +{ + 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; + + return MBG_ERR_NOT_SUPP_BY_DEV; + +} // chk_dev_ims_is_volt_out_enabled + + +/*HDR*/ +_NO_MBG_API_ATTR int _MBG_API chk_dev_ims_is_volt_out_overload( const ALL_IMS_STATE *ims_state, unsigned idx ) +{ + 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; + + return MBG_ERR_NOT_SUPP_BY_DEV; + +} // chk_dev_ims_is_volt_out_overload + + +/*HDR*/ +_NO_MBG_API_ATTR int _MBG_API chk_dev_ims_is_pll_locked( const ALL_IMS_STATE *ims_state, unsigned idx ) +{ + 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; + + return MBG_ERR_NOT_SUPP_BY_DEV; + +} // chk_dev_ims_is_pll_locked + + +/*HDR*/ +_NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_supp_ass_idx( const ALL_GPIO_INFO *gpio_info, unsigned idx ) +{ + 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 ) + return MBG_SUCCESS; + + return MBG_ERR_NOT_SUPP_BY_DEV; + +} // chk_dev_gpio_supp_ass_idx + + +/*HDR*/ +_NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_dep_on_ass_idx( const ALL_GPIO_INFO *gpio_info, unsigned idx ) +{ + 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 ) + return MBG_SUCCESS; + + return MBG_ERR_NOT_SUPP_BY_DEV; + +} // chk_dev_gpio_dep_on_ass_idx + + +/*HDR*/ +/** + * @brief Checks whether GPIO supports status function + * + * @param[out] info Pointer to a ::ALL_GPIO_INFO structure to be filled up + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_gpio + * @see ::mbg_chk_dev_has_gpio + * @see ::free_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 ) + return MBG_SUCCESS; + + return MBG_ERR_NOT_SUPP_BY_DEV; + +} // chk_dev_gpio_has_status + + + +/*HDR*/ +/** + * @brief Free an ::ALL_XBP_INFO structure + * + * @param[in] p Pointer to the ::ALL_XBP_INFO structure to be freed + * + * @see ::mbgextio_get_all_xbp_info + */ +void free_all_xbp_info ( ALL_XBP_INFO *p ) +{ + if ( p ) + { + if ( p->node_limits ) + free( p->node_limits ); + + if ( p->node_infos ) + free( p->node_infos ); + + free( p ); + } + +} // free_all_xbp_info + + + +/*HDR*/ +/** + * @brief Free an ::ALL_NET_CFG_INFO structure + * + * @param[in] p Pointer to the ::ALL_NET_CFG_INFO structure to be freed + * + * @see ::mbgextio_get_all_net_cfg_info + */ +void free_all_net_cfg_info ( ALL_NET_CFG_INFO *p ) +{ + if ( p ) + { + if ( p->link_infos ) + free( p->link_infos ); + + if ( p->addr_infos ) + free( p->addr_infos ); + + if ( p->dns_srvrs ) + free( p->dns_srvrs ); + + if ( p->dns_srch_doms ) + free( p->dns_srch_doms ); + + if ( p->route_infos ) + free( p->route_infos ); + + free( p ); + } + +} // free_all_net_cfg_info + + + +/*HDR*/ +/** + * @brief Free an ::ALL_NET_STATUS_INFO structure + * + * @param[in] p Pointer to the ::ALL_NET_STATUS_INFO structure to be freed + * + * @see ::mbgextio_get_all_net_status_info + */ +void free_all_net_status_info ( ALL_NET_STATUS_INFO *p ) +{ + if ( p ) + { + if ( p->link_infos ) + free( p->link_infos ); + + if ( p->addr_infos ) + free( p->addr_infos ); + + if ( p->dns_srvrs ) + free( p->dns_srvrs ); + + if ( p->dns_srch_doms ) + free( p->dns_srch_doms ); + + if ( p->route_infos ) + free( p->route_infos ); + + free( p ); + } + +} // free_all_net_status_info + + + +/*HDR*/ +/** + * @brief Free an ::ALL_SNMP_INFO structure + * + * @param[in] p Pointer to the ::ALL_SNMP_INFO structure to be freed + */ +void free_all_snmp_info ( ALL_SNMP_INFO *p ) +{ + if ( p ) + { + if ( p->v12_infos ) + free( p->v12_infos ); + + if ( p->v12_trap_infos ) + free( p->v12_trap_infos ); + + if ( p->v3_infos ) + free( p->v3_infos ); + + if ( p->v3_trap_infos ) + free( p->v3_trap_infos ); + + free( p ); + } + +} // free_all_snmp_info + + + +/*HDR*/ +/** + * @brief Free an ::ALL_SYSLOG_INFO structure + * + * @param[in] p Pointer to the ::ALL_SYSLOG_INFO structure to be freed + */ +void free_all_syslog_info ( ALL_SYSLOG_INFO *p ) +{ + if ( p ) + { + if ( p->servers ) + { + unsigned i; + MBG_SYSLOG_SERVER *srv; + + for (i = 0; i < p->glb_info.settings.num_servers; ++i) + { + srv = &p->servers[i]; + + if ( srv->release_priv ) + srv->release_priv( srv ); + } + + free( p->servers ); + } + + free( p ); + } + +} // free_all_syslog_info + + + +/*HDR*/ +/** + * @brief Free an ::ALL_MONITORING_INFO structure + * + * @param[in] p Pointer to the ::ALL_MONITORING_INFO structure to be freed + */ +void free_all_monitoring_info ( ALL_MONITORING_INFO *p ) +{ + if ( p ) + { + if ( p->all_snmp_info ) + free_all_snmp_info( p->all_snmp_info ); + + if ( p->all_events ) + free_all_events( p->all_events ); + + if ( p->all_syslog_info ) + free_all_syslog_info( p->all_syslog_info ); + + free ( p ); + } +} + + +/*HDR*/ +/** + * @brief Free an ::ALL_EVENTS structure + * + * @param[in] p Pointer to the ::ALL_EVENTS structure to be freed + */ +void free_all_events( ALL_EVENTS *p ) +{ + if ( p ) + { + if ( p->events ) + { + unsigned i; + MBG_EVENT *evt; + + for (i = 0; i < p->num_events; ++i) + { + evt = &p->events[i]; + + if ( evt->release_priv ) + evt->release_priv( evt ); + + if ( evt->release_backref ) + evt->release_backref( evt ); + + if ( evt->dict_entries ) + free ( evt->dict_entries ); + } + + free( p->events ); + } + + free ( p ); + } +} + + +/*HDR*/ +/** + * @brief Free an ::ALL_XMULTI_REF_INFO structure + * + * @param[in] p Pointer to the ::ALL_XMULTI_REF_INFO structure to be freed + * + * @see ::mbgextio_get_all_xmulti_ref_info + * @see ::mbg_get_all_xmulti_ref_info + */ +void free_all_xmulti_ref_info( ALL_XMULTI_REF_INFO *p ) +{ + if ( p ) + { + if ( p->infos ) + free( p->infos ); + + if ( p->ext_src_infos ) + free( p->ext_src_infos ); + + free ( p ); + } + +} // free_all_xmulti_ref_info + + + +/*HDR*/ +/** + * @brief Free an ::ALL_XMULTI_REF_STATUS structure + * + * @param[in] p Pointer to the ::ALL_XMULTI_REF_STATUS structure to be freed + * + * @see ::mbgextio_get_all_xmulti_ref_status + * @see ::mbg_get_all_xmulti_ref_status + */ +void free_all_xmulti_ref_status( ALL_XMULTI_REF_STATUS *p ) +{ + if ( p ) + { + if ( p->status ) + free( p->status ); + + if ( p->holdover_status ) + free( p->holdover_status ); + + if ( p->stats_idx ) + free( p->stats_idx ); + + if ( p->metrics_idx ) + free( p->metrics_idx ); + + free( p ); + } + +} // free_all_xmulti_ref_status + + + +/*HDR*/ +/** + * @brief Free an ::ALL_PTP_V1_COMMON_DATASETS structure allocated by ::mbgextio_get_all_ptp_v1_common_datasets + * + * @param[in] p Pointer to the ::ALL_PTP_V1_COMMON_DATASETS structure to be freed + * + * @see ::mbgextio_get_all_ptp_v1_common_datasets + */ +void free_all_ptp_v1_common_datasets( ALL_PTP_V1_COMMON_DATASETS *p ) +{ + if ( p ) + { + if ( p->port_datasets ) + free( p->port_datasets ); + + free( p ); + } + +} // free_all_ptp_v1_common_datasets + + + +/*HDR*/ +/** + * @brief Free an ::ALL_PTP_V2_COMMON_DATASETS structure allocated by ::mbgextio_get_all_ptp_v2_common_datasets + * + * @param[in] p Pointer to the ::ALL_PTP_V2_COMMON_DATASETS structure to be freed + * + * @see ::mbgextio_get_all_ptp_v2_common_datasets + */ +void free_all_ptp_v2_common_datasets( ALL_PTP_V2_COMMON_DATASETS *p ) +{ + if ( p ) + { + if ( p->port_datasets ) + free( p->port_datasets ); + + free( p ); + } + +} // free_all_ptp_v2_common_datasets + + + +/*HDR*/ +/** + * @brief Free an ::ALL_NTP_CFG_INFO structure + * + * @param[in] p Pointer to the ::ALL_NTP_CFG_INFO structure to be freed + * + * @see ::mbgextio_get_all_ntp_cfg_info + */ +void free_all_ntp_cfg_info( ALL_NTP_CFG_INFO *p ) +{ + if ( p ) + { + if ( p->symm_key_limits ) + free( p->symm_key_limits ); + + if ( p->symm_key_info_idx ) + free( p->symm_key_info_idx ); + + if ( p->trusted_key_info_idx ) + free( p->trusted_key_info_idx ); + + if ( p->clnt_info ) + free( p->clnt_info ); + + if ( p->peer_settings_idx ) + free( p->peer_settings_idx ); + + if ( p->srv_info ) + free( p->srv_info ); + + if ( p->refclk_info_idx ) + free( p->refclk_info_idx ); + + if ( p->misc_limits ) + free( p->misc_limits ); + + if ( p->orphan_mode_info ) + free( p->orphan_mode_info ); + + free( p ); + } + +} // free_all_ntp_cfg_info + + + +/*HDR*/ +/** + * @brief Free an ::ALL_NTP_STATUS structure + * + * @param[in] p Pointer to the ::ALL_NTP_STATUS structure to be freed + * + * @see ::mbgextio_get_all_ntp_status + */ +void free_all_ntp_status( ALL_NTP_STATUS *p ) +{ + if ( p ) + { + if ( p->refclk_states ) + free( p->refclk_states ); + + if ( p->peer_states ) + free( p->peer_states ); + + free( p ); + } + +} // free_all_ntp_status + + + +/*HDR*/ +/** + * @brief Free memory allocated by ::mbgextio_get_all_ims_info + * + * @param[in] p Pointer to the ::ALL_IMS_INFO structure to be freed + * + * @see ::mbgextio_dev_has_ims + * @see ::mbgextio_get_all_ims_info + * @see ::mbgextio_get_all_ims_state + */ +void free_all_ims_info( ALL_IMS_INFO *p ) +{ + if ( p ) + { + if ( p->fdm_info ) + free( p->fdm_info ); + + if ( p->fdm_limits ) + free( p->fdm_limits ); + + if ( p->fdm_outinfo_idx ) + free( p->fdm_outinfo_idx ); + + free( p ); + } + +} // free_all_ims_info + + + +/*HDR*/ +/** + * @brief Free memory allocated by ::mbgextio_get_all_ims_state + * + * @param[in] p Pointer to the ::ALL_IMS_STATE structure to be freed + * + * @see ::mbgextio_dev_has_ims + * @see ::mbgextio_get_all_ims_info + * @see ::mbgextio_get_all_ims_state + */ +void free_all_ims_state( ALL_IMS_STATE *p ) +{ + if ( p ) + { + if ( p->sensor_state_idx ) + free( p->sensor_state_idx ); + + if ( p->fdm_state ) + free( p->fdm_state ); + + if ( p->fdm_output_state_idx ) + free( p->fdm_output_state_idx ); + + free( p ); + } + +} // free_all_ims_state + + + +/*HDR*/ +/** + * @brief Free memory allocated by ::mbgextio_get_all_gpio_info + * + * @param[in] p Pointer to the ::ALL_GPIO_INFO structure to be freed + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_gpio + * @see ::mbgextio_get_all_gpio_info + */ +void free_all_gpio_info( ALL_GPIO_INFO *p ) +{ + if ( p ) + { + if ( p->infos ) + free( p->infos ); + + free( p ); + } + +} // free_all_gpio_info + + + +/*HDR*/ +/** + * @brief Free memory allocated by ::mbgextio_get_all_io_ports + * + * @param[in] p Pointer to the ::ALL_MBG_IO_PORTS structure to be freed + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_io_ports + * @see ::mbgextio_get_all_io_ports + * @see ::mbgextio_get_all_io_port_status + */ +void free_all_io_ports( ALL_MBG_IO_PORTS *p ) +{ + if ( p ) + { + if ( p->ports ) + { + unsigned i; + MBG_IO_PORT *port; + + for ( i = 0; i < p->num_ports; ++i ) + { + port = &p->ports[i]; + + if ( port->free_priv_data ) + port->free_priv_data( port, port->priv_data ); + + if ( port->pt_infos ) + free( port->pt_infos ); + } + + free( p->ports ); + } + + free( p ); + } + +} // free_all_io_ports + + +/*HDR*/ +/** + * @brief Free memory allocated by ::mbgextio_get_all_gpio_state + * + * @param[in] p Pointer to the ::ALL_GPIO_STATE structure to be freed + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_gpio + * @see ::mbgextio_get_all_gpio_state + */ +void free_all_gpio_state( ALL_GPIO_STATE *p ) +{ + if ( p ) + { + if ( p->states ) + free( p->states ); + + free( p ); + } + +} // free_all_gpio_state + + + +/*HDR*/ +/** + * Allocates memory for a new ::UCAP_ENTRY structure + * + * @return The new allocated ::UCAP_ENTRY or NULL if the calloc call was not successful + */ +UCAP_ENTRY* calloc_ucap_entry( void ) +{ + UCAP_ENTRY *entry = (UCAP_ENTRY *) calloc( 1, sizeof( *entry ) ); + + if ( entry ) + mbg_klist_init( &entry->head ); + + return entry; + +} // calloc_ucap_entry + + +/*HDR*/ +/** + * @brief Free memory allocated by ::mbgextio_get_all_ucap_info + * + * @param[in] p Pointer to the ::ALL_UCAP_INFO structure to freed + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_ucap + * @see ::mbg_chk_dev_has_ucap + * @see ::mbgextio_get_all_ucap_info + * @see ::mbg_get_all_ucap_info + */ +void free_all_ucap_info( ALL_UCAP_INFO *p ) +{ + if ( p ) + { + UCAP_ENTRY *entry; + + while ( !mbg_klist_is_empty( &p->list ) ) + { + entry = mbg_klist_first_entry( &p->list, UCAP_ENTRY, head ); + mbg_klist_delete_item( &entry->head ); + free( entry ); + } + + free( p ); + } + +} // free_all_ucap_info + + +/*HDR*/ +/** + * @brief Free an ::ALL_UCAP_NET_INFO structure + * + * @param[in] p Pointer to the ::ALL_UCAP_NET_INFO structure to be freed + * + * @see ::mbgextio_get_all_ucap_net_info + */ +void free_all_ucap_net_info( ALL_UCAP_NET_INFO *p ) +{ + if ( p ) + { + if ( p->recv_infos ) + free( p->recv_infos ); + + free( p ); + } + +} // free_all_ucap_net_info + + + +/*HDR*/ +/** + * @brief Free an ::ALL_USER_INFO structure + * + * @param[in] p Pointer to the ::ALL_USER_INFO structure to be freed + * + * @see ::mbgextio_get_all_user_info + */ +void free_all_user_info( ALL_USER_INFO *p ) +{ + if ( p ) + { + if ( p->users ) + { + unsigned i; + MBG_USER *usr; + + for ( i = 0; i < p->user_mngmnt_info.settings.num_users; ++i ) + { + usr = &p->users[i]; + + if ( usr->release_priv ) + usr->release_priv( usr ); + + if ( usr->release_backref ) + usr->release_backref( usr ); + } + + free( p->users ); + } + + free( p ); + } +} + + + +/*HDR*/ +/** + * @brief Free an ::ALL_SERVICE_INFO structure + * + * @param[in] p Pointer to the ::ALL_SERVICE_INFO structure to be freed + * + * @see ::mbgextio_get_all_user_info + */ +void free_all_svc_info( ALL_SERVICE_INFO *p ) +{ + if ( p ) + { + if ( p->svcs ) + { + unsigned i; + MBG_SERVICE *svc; + + for ( i = 0; i < p->mgmt_info.num_services; ++i ) + { + svc = &p->svcs[i]; + + if ( svc->release_priv ) + svc->release_priv( svc ); + + if ( svc->release_backref ) + svc->release_backref( svc ); + } + + free( p->svcs ); + } + + free( p ); + } +} + + +/*HDR*/ +/** + * @brief Free an ::ALL_FIRMWARE_INFO structure + * + * @param[in] p Pointer to the ::ALL_FIRMWARE_INFO structure to be freed + * + * @see ::mbgextio_get_all_firmware_info + */ +void free_all_firmware_info( ALL_FIRMWARE_INFO *p ) +{ + if ( p ) + { + if ( p->firmwares ) + { + MBG_FIRMWARE_UFU *ufu; + MBG_FIRMWARE *fw; + unsigned i, j; + + for ( i = 0; i < p->glb_info.installed_fws; ++i ) + { + fw = &p->firmwares[i]; + + for ( j = 0; j < fw->info.num_ufus; ++j ) + { + ufu = &fw->ufus[j]; + + if ( ufu->release_priv ) + ufu->release_priv( ufu ); + } + free( fw->ufus ); + + if ( fw->release_priv ) + fw->release_priv( fw ); + } + + free( p->firmwares ); + } + + free( p ); + } +} + + + +/*HDR*/ +/** + * @brief Free an ::ALL_DATABASE_INFO structure + * + * @param[in] p Pointer to the ::ALL_DATABASE_INFO structure to be freed + * + * @see ::mbgextio_get_all_database_info + */ +void free_all_database_info( ALL_DATABASE_INFO *p ) +{ + if ( !p ) + return; + + if ( p->dbs ) + { + uint8_t i; + MBG_DATABASE *db; + + for ( i = 0; i < p->glb_info.num_dbs; ++i ) + { + db = &p->dbs[i]; + + if ( db->release_priv ) + db->release_priv( db ); + } + + free( p->dbs ); + } + + free( p ); +} + + + +/*HDR*/ +/** + * @brief Set up a ::NTP_TSTAMP structure from a hex string with a time in seconds and binary fractions + * + * @param[in] s A string with a time in seconds since NTP epoch 1900-01-01, + * with binary fractions separated by decimal point, + * e.g. 'dc763e43.73bd5a8f' as printed by the ntpq utility + * @param[out] p Address of a ::NTP_TSTAMP structure to be set up + * + * @see ::str_ntp_hex_to_nano_time_64 + */ +void str_ntp_hex_to_ntp_tstamp( const char *s, NTP_TSTAMP *p ) +{ + char *cp = NULL; + + p->seconds = strtoul( s, &cp, 16 ); + + if ( *cp == '.' ) // fractions may follow + { + cp++; // skip '.' + + p->fractions = strtoul( cp, NULL, 16 ); + } + else + p->fractions = 0; + +} // str_ntp_hex_to_ntp_tstamp + + + +#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + +/*HDR*/ +/** + * @brief Convert a ::NTP_TSTAMP structure to a ::NANO_TIME_64 structure + * + * @param[in] p_nts The ::NTP_TSTAMP structure to be converted + * @param[out] p_nt64 The ::NANO_TIME_64 structure to be filled up + */ +void ntp_tstamp_to_nanotime_64( const NTP_TSTAMP *p_nts, NANO_TIME_64 *p_nt64 ) +{ + p_nt64->secs = p_nts->seconds - NTP_SEC_BIAS; + p_nt64->nano_secs = bin_frac_32_to_dec_frac( p_nts->fractions, NSEC_PER_SEC ); + +} // ntp_tstamp_to_nanotime_64 + + + +/*HDR*/ +/** + * @brief Set up a ::NANO_TIME_64 structure from a hex string with a time in seconds and binary fractions + * + * @param[in] s A string with a time in seconds since epoch 1900-01-01, + * with binary fractions separated by decimal point, + * e.g. 'dc763e43.73bd5a8f' as printed by the ntpq utility + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + * + * @see ::str_ntp_hex_to_ntp_tstamp + */ +void str_ntp_hex_to_nano_time_64( const char *s, NANO_TIME_64 *p ) +{ + NTP_TSTAMP nts = { 0 }; + + str_ntp_hex_to_ntp_tstamp( s, &nts ); + ntp_tstamp_to_nanotime_64( &nts, p ); + +} // str_ntp_hex_to_nano_time_64 + +#endif // !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + + diff --git a/mbglib/common/cfg_hlp.h b/mbglib/common/cfg_hlp.h index a485d98..9df0f5b 100644 --- a/mbglib/common/cfg_hlp.h +++ b/mbglib/common/cfg_hlp.h @@ -1,16 +1,67 @@ /************************************************************************** * - * $Id: cfg_hlp.h 1.2 2012/10/02 18:16:26Z martin REL_M $ + * $Id: cfg_hlp.h 1.6 2018/09/20 11:22:11Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * * Description: * Definitions and prototypes for configuration programs. * + * WARNING: Changing the constants defined here affects the size of + * the related structures and arrays, and thus would break compatibility + * if used in DLLs / shared object libraries. + * + * Care must be taken that the number of objects supported by + * any particular device (which can be only determined at runtime) + * does not exceed the max. number of objects specified here + * for the configuration programs. + * * ----------------------------------------------------------------------- * $Log: cfg_hlp.h $ - * Revision 1.2 2012/10/02 18:16:26Z martin + * Revision 1.6 2018/09/20 11:22:11Z martin + * Renamed some global variables to more common names. + * Added string initializer tables and associated macros + * for some PTP configuration stuff. + * Revision 1.5 2018/07/05 10:37:05Z martin + * Renamed setup_port_info_from_port_settings() + * to setup_port_info_from_port_parm(). + * Initializer for OS targets added by philipp. + * Database feature support added by philipp. + * I/O helper structures and API refuctored by philipp. + * Firmware management wrapper structs added by philipp. + * Syslog option added to monitoring feature by philipp. + * Service feature and API added by philipp. + * Return random UID for TLVs under Windows. + * MBG_EVENT stuff integrated with common/general monitoring + * stuff by philipp. + * Monitoring events refactored and tainted config support + * added by philipp. + * Exclude some function from build in kernel mode. + * Fixed build for NetBSD. + * Supporting MBG_TGT_NO_TGT. + * Updated function prototypes. + * Revision 1.4 2017/07/05 13:22:00 martin + * Definitions for TLV, IMS, and GPIO provided by philipp. + * Definitions for ALL_XPB_INFO, ALL_NET_CFG_INFO, + * ALL_PTP_V2_COMMON_DATASETS, ALL_PTP_V1_COMMON_DATASETS, + * ALL_UCAP and associated stuff provided by thomas-b. + * Definitions for xmulti_ref and IO PORT, SNMP and MONITORING, + * and associated stuff provided by philipp and thomas-b. + * New definitions COMP_SIG_MODES and PCPS_TIME_EXT_FLAGS. + * New inline functions device_id_is_serial() and + * device_id_is_lan(). + * Moved inline function num_bits_set() and a lot of + * global configuration variables here. + * Older defines N_SUPP_DEV, PCPS_MAX_DDEVS, and MBG_MAX_DEVICES + * have been obsoleted by new defines N_SUPP_DEV_BUS, N_SUPP_DEV_EXT, + * and N_SUPP_DEV_TOTAL. + * Updated function prototypes. + * Revision 1.3 2013/09/25 10:02:15 martin + * Added ALL_PTP_CFG_INFO, ALL_GNSS_SAT_INFO_IDX and + * related definitions. + * Added doxygen comments. + * Revision 1.2 2012/10/02 18:16:26 martin * Modified some typedefs to be more compliant with the underlying types. * Revision 1.1 2011/09/21 15:59:59 martin * Initial revision. @@ -24,7 +75,24 @@ /* Other headers to be included */ #include <gpsdefs.h> +#include <mbgklist.h> + +#if !defined( MBG_TGT_KERNEL ) + #include <stdlib.h> + #include <string.h> +#endif + +#if defined( _PRELIMINARY_CODE ) + #if defined( MBG_TGT_POSIX ) + #include <sys/stat.h> + #include <time.h> + #endif // MBG_TGT_POSIX + #if defined( MBG_TGT_LINUX ) + #include <sys/sysinfo.h> + #endif // MBG_TGT_LINUX + +#endif // _PRELIMINARY_CODE #ifdef _CFG_HLP #define _ext @@ -41,79 +109,1516 @@ extern "C" { #endif -/* - * The definitions and types below are used to collect - * all configuration parameters of a clock's serial ports - * that can be handled by this library: - */ +#if 1 // ### TODO cleanup +#define N_SUPP_DEV_BUS 16 +#define N_SUPP_DEV_EXT 1 -/* - * The maximum number of clocks' serial ports and string types - * that can be handled by the configuration programs. - * WARNING: Changing these constants affects the size of the - * structures ALL_PORT_INFO ALL_STR_TYPE_INFO +#define N_SUPP_DEV_TOTAL ( N_SUPP_DEV_BUS + N_SUPP_DEV_EXT ) + +typedef struct _DEVICE_INFO +{ + char *hw_id; + char fw_id[100]; + +} DEVICE_INFO; + +_ext DEVICE_INFO device_list[N_SUPP_DEV_TOTAL]; + +#endif + + + +/** + * @defgroup cfg_hlp_com_parm_cnv_fncs Legacy COM_PARM conversion functions */ -#define MAX_PARM_PORT 4 + +/// @brief The max number of serial ports supported by configuration programs +#define MAX_PARM_PORT 10 + +/// @brief The max number of serial string types supported by configuration programs #define MAX_PARM_STR_TYPE 20 +/// @brief The max number of programmable pulse outputs supported by configuration programs +#define MAX_PARM_POUT 10 + +/// @brief The max number of GNSS settings supported by configuration programs +#define MAX_PARM_GNSS_SAT N_GNSS_TYPES + +/// @brief The max number of PTP unicast masters supported by configuration programs +#define MAX_PARM_PTP_UC_MASTER 3 + +/// @brief The max number of external NTP server associations to be handled by configuration programs +#define MAX_PARM_EXT_NTP_SRVR 20 + +/// @brief The max number of GPIO ports supported by configuration programs +#define MAX_PARM_GPIO 10 + +/// @brief The max number of XMR sources supported by configuration programs +#define MAX_PARM_XMR 10 + +/// @brief The max number of external NTP servers supported by configuration programs +#define MAX_EXT_NTP_SERVERS 20 + +/// @brief The max. number of time monitoring modules supported by configuration programs +/// Each module may support a different number of targets to be monitored. +/// @see ### TODO +#define MAX_MBG_TIME_MON_MODULES 10 + +/// @brief The max. number of time monitoring targets supported by configuration programs +/// This is the sum of all targets from all monitoring modules. +/// @see ### TODO +#define MAX_MBG_TIME_MON_TARGETS 100 + + + +/// @brief An array of configuration settings for all serial ports typedef PORT_INFO_IDX ALL_PORT_INFO_IDX[MAX_PARM_PORT]; + +/// @brief An array of configuration settings for all serial string types typedef STR_TYPE_INFO_IDX ALL_STR_TYPE_INFO_IDX[MAX_PARM_STR_TYPE]; +/** + * @brief All configuration parameters for all serial ports + * + * Used to collect all configuration parameters of a clock's serial ports + * that can be handled by a configuration program. + * + * @see ::RECEIVER_INFO::n_com_ports + * @see ::RECEIVER_INFO::n_str_type + */ typedef struct { - ALL_PORT_INFO_IDX pii; - ALL_STR_TYPE_INFO_IDX stii; - PORT_PARM tmp_pp; + ALL_PORT_INFO_IDX pii; ///< all serial port configuration settings + ALL_STR_TYPE_INFO_IDX stii; ///< all supported serial string types + PORT_PARM tmp_pp; ///< used internally only, for compatibility } RECEIVER_PORT_CFG; -/* - * The definitions and types below are used to collect - * all configuration parameters of a clock's programmable - * pulse outputs that can be handled by this library: + +/** + * @brief All XBP information of a XBP supporting device + * + * This structure represents a list of connected devices + * + * @see ::GPS_HAS_XBP */ +typedef struct +{ + XBP_LIMITS limits; + XBP_NODE_LIMITS* node_limits; + XBP_NODE_INFO_IDX* node_infos; +} ALL_XBP_INFO; -#define MAX_PARM_POUT 4 -#if 1 //##+++++++++++++++++++++++ +/** + * @brief An array of configuration settings for all programmable pulse outputs + * + * Used to collect all configuration parameters of a clock's programmable pulse outputs + * that can be handled by a configuration program. + * + * @see ::RECEIVER_INFO::n_prg_out + */ typedef POUT_INFO_IDX ALL_POUT_INFO_IDX[MAX_PARM_POUT]; -#else + +/** + * @brief All network configuration parameters + * + * Used to collect all configuration parameters for networking + * + * @see ::GPS_HAS_NET_CFG + * @see ::GPS_HAS_LAN_IP4 + */ typedef struct { - POUT_INFO_IDX pii[MAX_PARM_POUT]; -} POUT_CFG; + MBG_NET_GLB_CFG_INFO glb_cfg_info; + MBG_NET_INTF_LINK_INFO_IDX *link_infos; + MBG_NET_INTF_ADDR_INFO_IDX *addr_infos; + MBG_IP_ADDR_IDX *dns_srvrs; + MBG_NET_NAME_IDX *dns_srch_doms; + MBG_NET_INTF_ROUTE_INFO_IDX *route_infos; +} ALL_NET_CFG_INFO; -#endif +typedef ALL_NET_CFG_INFO ALL_NET_STATUS_INFO; -/* - * The definitions and types below are used to collect - * all configuration parameters of PTP device's unicast - * master specification: + +/** + * @brief All SNMP configuration information + * + * Used to collect all configuration parameters for monitoring via SNMP + * Can be used, if ::MBG_MONITORING_TYPE_MSK_SNMP is set in ::MBG_MONITORING_LIMITS::supp_types + * + * @see ::MBG_XFEATURE_MONITORING */ +typedef struct +{ + MBG_SNMP_GLB_INFO glb_info; + MBG_SNMP_V12_INFO_IDX *v12_infos; + MBG_SNMP_V12_TRAP_INFO_IDX *v12_trap_infos; + MBG_SNMP_V3_INFO_IDX *v3_infos; + MBG_SNMP_V3_TRAP_INFO_IDX *v3_trap_infos; -#define MAX_PARM_PTP_UC_MASTER 3 +} ALL_SNMP_INFO; + + + +/** + * @brief All monitoring event data + * + * Used to collect all event data and group related chunks senseful to a single + * event so all data is in one struct. + */ +typedef struct mbg_event +{ + unsigned idx; + 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 */ + void *priv_data; + /* + * Can be used to free/release priv or cookie data (if necessary) + * or do other stuff before event gets freed. But NEVER use release + * to free the event itself!! This is done by the API right after calling + * release. + */ + void (*release_priv)(struct mbg_event*); + void (*release_backref)(struct mbg_event*); + +} MBG_EVENT; + +typedef struct +{ + unsigned num_events; + MBG_EVENT *events; + +} ALL_EVENTS; + + +/** + * @brief All monitoring syslog data + * + * Used to collect all syslog data. + */ + + +typedef struct mbg_syslog_server +{ + unsigned idx; + MBG_SYSLOG_INFO info; + + /* Pointer for the mallocer to connect some private data */ + void *priv_data; + /* + * Can be used to free/release priv or cookie data (if necessary) + * or do other stuff before event gets freed. But NEVER use release + * to free the event itself!! This is done by the API right after calling + * release. + */ + void (*release_priv)(struct mbg_syslog_server*); + +} MBG_SYSLOG_SERVER; + +typedef struct +{ + MBG_SYSLOG_GLB_INFO glb_info; + MBG_SYSLOG_SERVER *servers; + +} ALL_SYSLOG_INFO; + + +/** + * @brief All monitoring information + * + * Used to collect all configuration parameters for monitoring of a device + * Depending on the ::MBG_MONITORING_LIMITS::supp_types, + * the approriate configurations can be found in the sub structures + * + * @see ::MBG_XFEATURE_MONITORING + */ +typedef struct +{ + MBG_MONITORING_LIMITS limits; + ALL_SNMP_INFO *all_snmp_info; + ALL_EVENTS *all_events; + ALL_SYSLOG_INFO *all_syslog_info; +} ALL_MONITORING_INFO; + + + +/// @brief Configuration settings for all unicast master specifications typedef PTP_UC_MASTER_INFO_IDX ALL_PTP_UC_MASTER_INFO_IDX[MAX_PARM_PTP_UC_MASTER]; +/** + * @brief All PTP configuration parameters + * + * Used to collect all configuration parameters for a PTP daemon + * that can be handled by a configuration program. + * + * @see ::GPS_HAS_PTP + * @see ::PTP_UC_MASTER_CFG_LIMITS::n_supp_master + */ +typedef struct +{ + PTP_CFG_INFO ptp_cfg_info; + PTP_UC_MASTER_CFG_LIMITS ptp_uc_master_cfg_limits; + ALL_PTP_UC_MASTER_INFO_IDX all_ptp_uc_master_info_idx; + +} ALL_PTP_CFG_INFO; + + + +/** + * @brief All PTPv1 common datasets for a PTP device + * + * Contains one of each common datasets plus one port dataset + * for each port of a device. The number of port datasets is defined + * in the ::MBG_PTP_V1_DEFAULT_DATASET::number_ports field of the + * ::ALL_PTP_V1_COMMON_DATASETS::default_dataset member. + * + * @see ::MBG_PTP_V1_DEFAULT_DATASET + * @see ::MBG_PTP_V1_CURRENT_DATASET + * @see ::MBG_PTP_V1_PARENT_DATASET + * @see ::MBG_PTP_V1_TIME_PROPERTIES_DATASET + * @see ::MBG_PTP_V1_PORT_DATASET_IDX + */ +typedef struct +{ + MBG_PTP_V1_DEFAULT_DATASET default_dataset; + MBG_PTP_V1_CURRENT_DATASET current_dataset; + MBG_PTP_V1_PARENT_DATASET parent_dataset; + MBG_PTP_V1_TIME_PROPERTIES_DATASET time_properties_dataset; + MBG_PTP_V1_PORT_DATASET_IDX *port_datasets; + +} ALL_PTP_V1_COMMON_DATASETS; + + + +/** + * @brief All PTPv2 common datasets for a PTP device + * + * Contains one of each common datasets plus one port dataset + * for each port of a device. The number of port datasets is defined + * in the ::MBG_PTP_V1_DEFAULT_DATASET::number_ports field of the + * ::ALL_PTP_V1_COMMON_DATASETS::default_dataset member. + * + * @see ::MBG_PTP_V2_DEFAULT_DATASET + * @see ::MBG_PTP_V2_CURRENT_DATASET + * @see ::MBG_PTP_V2_PARENT_DATASET + * @see ::MBG_PTP_V2_TIME_PROPERTIES_DATASET + * @see ::MBG_PTP_V2_PORT_DATASET_IDX + */ +typedef struct +{ + MBG_PTP_V2_DEFAULT_DATASET default_dataset; + MBG_PTP_V2_CURRENT_DATASET current_dataset; + MBG_PTP_V2_PARENT_DATASET parent_dataset; + MBG_PTP_V2_TIME_PROPERTIES_DATASET time_properties_dataset; + MBG_PTP_V2_PORT_DATASET_IDX *port_datasets; + +} ALL_PTP_V2_COMMON_DATASETS; + + + +/** + * @brief An array of configuration settings for all programmable pulse outputs + * + * Used to collect all configuration parameters of a clock's programmable pulse outputs + * that can be handled by a configuration program. + */ +typedef GNSS_SAT_INFO_IDX ALL_GNSS_SAT_INFO_IDX[MAX_PARM_GNSS_SAT]; + + + +/** + * @brief Summary information on all supported GNSS systems + * + * Used to collect all configuration parameters even for devices + * that can receive the signals from multiple satellite systems. + */ +typedef struct +{ + STAT_INFO stat_info; + int n_gnss_supp; + MBG_GNSS_MODE_INFO gnss_mode_info; + ALL_GNSS_SAT_INFO_IDX gnss_sat_info_idx; + +} ALL_GNSS_INFO; + + + +/// @brief Configuration settings for all NTP server associations +typedef NTP_PEER_SETTINGS ALL_NTP_PEER_SETTINGS[MAX_EXT_NTP_SERVERS]; + +/** + * @brief All NTP configuration parameters + * + * Used to collect all configuration parameters for an NTP daemon + * that can be handled by a configuration program. + * + * @see ::GPS_HAS_NTP + */ +typedef struct +{ + ALL_NTP_PEER_SETTINGS all_ntp_peer_settings; + +} NTP_CLIENT_CFG_PEER_SETTINGS; + + +typedef struct +{ + NTP_GLB_INFO glb_info; + NTP_SYMM_KEY_LIMITS *symm_key_limits; + NTP_SYMM_KEY_INFO_IDX *symm_key_info_idx; + NTP_TRUSTED_KEY_INFO_IDX *trusted_key_info_idx; + + NTP_CLNT_MODE_INFO *clnt_info; + NTP_PEER_SETTINGS_IDX *peer_settings_idx; + + NTP_SRV_MODE_INFO *srv_info; + NTP_REFCLK_CFG_INFO_IDX *refclk_info_idx; + NTP_MISC_LIMITS *misc_limits; + NTP_MISC_ORPHAN_MODE_INFO *orphan_mode_info; + +} ALL_NTP_CFG_INFO; + + +typedef struct +{ + NTP_SYS_STATE sys_state; + NTP_REFCLK_STATE_IDX *refclk_states; + NTP_PEER_STATE_IDX *peer_states; +} ALL_NTP_STATUS; + + + +/// @brief Configuration settings for all GPIO ports +typedef MBG_GPIO_INFO_IDX ALL_GPIO_INFO_IDX[MAX_PARM_GPIO]; + +/// @brief Status information on all GPIO ports +typedef MBG_GPIO_STATUS_IDX ALL_GPIO_STATUS_IDX[MAX_PARM_GPIO]; + + + + +/// @brief Status of all XMR inputs +typedef XMULTI_REF_STATUS_IDX ALL_XMULTI_REF_STATUS_IDX[MAX_PARM_XMR]; + +/// @brief Configuration settings for all XMR inputs +typedef XMULTI_REF_INFO_IDX ALL_XMULTI_REF_INFO_IDX[MAX_PARM_XMR]; + + + +typedef struct +{ + XMULTI_REF_INSTANCES instances; + XMULTI_REF_INFO_IDX *infos; + XMR_EXT_SRC_INFO_IDX *ext_src_infos; +} ALL_XMULTI_REF_INFO; + + +typedef struct +{ + XMULTI_REF_STATUS_IDX *status; + XMR_HOLDOVER_STATUS *holdover_status; + XMR_STATS_IDX *stats_idx; + XMR_METRICS_IDX *metrics_idx; + /* ALL_XMULTI_REF_STATUS related flag if at least one ref type supports stats */ + unsigned char has_stats; + /* ALL_XMULTI_REF_STATUS related flag if at least one ref type supports metrics */ + unsigned char has_metrics; +} ALL_XMULTI_REF_STATUS; + + + +typedef struct +{ + MBG_IMS_STATE state; + MBG_IMS_FDM_INFO *fdm_info; + MBG_IMS_FDM_LIMITS *fdm_limits; + MBG_IMS_FDM_OUTPUT_INFO_IDX *fdm_outinfo_idx; +} ALL_IMS_INFO; + + +typedef struct +{ + MBG_IMS_SENSOR_STATE_IDX *sensor_state_idx; + MBG_IMS_FDM_STATE *fdm_state; + MBG_IMS_FDM_OUTPUT_STATE_IDX *fdm_output_state_idx; +} ALL_IMS_STATE; + + + +typedef struct +{ + MBG_GPIO_CFG_LIMITS cfg_limits; + MBG_GPIO_INFO_IDX *infos; +} ALL_GPIO_INFO; + + +typedef struct +{ + MBG_GPIO_STATUS_IDX *states; +} ALL_GPIO_STATE; + + +typedef struct mbg_io_port +{ + unsigned idx; + MBG_IO_PORT_INFO p_info; + MBG_IO_PORT_STATUS status; + MBG_IO_PORT_TYPE_INFO *pt_infos; + /* Shortcut to settings in p_info */ + MBG_IO_PORT_SETTINGS *setts; + void *priv_data; + void (*free_priv_data)(const struct mbg_io_port*, void*); +} MBG_IO_PORT; + + +typedef struct +{ + MBG_IO_PORT_LIMITS limits; + unsigned num_ports; + MBG_IO_PORT *ports; +} ALL_MBG_IO_PORTS; + + +#ifndef MAX_UCAP_ENTRIES +/* + * According to Andre's GPS firmware this is the maximum + * number of user captures that are preserved. + */ +#define MAX_UCAP_ENTRIES 585 +#endif + +typedef struct +{ + struct mbg_klist_head head; + TTM ttm; +} UCAP_ENTRY; + +typedef struct +{ + 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 +{ + MBG_UCAP_NET_GLB_INFO glb_info; + MBG_UCAP_NET_RECV_INFO_IDX *recv_infos; +} ALL_UCAP_NET_INFO; + + +typedef struct mbg_user +{ + unsigned idx; + MBG_USER_INFO info; + MBG_USER_STATUS status; + + char salt[3]; + + /* Pointer for 3rd party to connect some data */ + void *backref; + /* Pointer for the mallocer to connect some private data */ + void *priv_data; + /* + * Can be used to free/release priv or cookie data (if necessary) + * or do other stuff before user gets freed. But NEVER use release + * to free the user itself!! This is done by the API right after calling + * release. + */ + void (*release_priv)(struct mbg_user*); + void (*release_backref)(struct mbg_user*); + +} MBG_USER; + +typedef struct +{ + MBG_USER_MNGMNT_INFO user_mngmnt_info; + MBG_USER *users; ///< system users for internal authentication + MBG_USER *user_levels; ///< global user levels for external authentication (i.e. radius/tacacs+) + +} ALL_USER_INFO; + + +typedef struct mbg_service +{ + unsigned idx; + MBG_SERVICE_INFO info; + MBG_SERVICE_STATUS status; + + /* Pointer for 3rd party to connect some data */ + void *backref; + /* Pointer for the mallocer to connect some private data */ + void *priv_data; + /* + * Can be used to free/release priv or cookie data (if necessary) + * or do other stuff before service gets freed. But NEVER use release + * to free the service itself!! This is done by the API right after calling + * release. + */ + void (*release_priv)(struct mbg_service*); + void (*release_backref)(struct mbg_service*); + +} MBG_SERVICE; + +typedef struct +{ + MBG_SERVICE_MGMT_INFO mgmt_info; + MBG_SERVICE *svcs; + +} ALL_SERVICE_INFO; + + +struct mbg_firmware; +struct mbg_firmware_ufu; + + +typedef struct mbg_firmware +{ + unsigned idx; + MBG_FW_INFO info; + struct mbg_firmware_ufu *ufus; ///< Array of ::MBG_FW_INFO::num_ufus + + /* Pointer for the mallocer to connect some private data */ + void *priv_data; + /* + * Can be used to free/release priv or cookie data (if necessary) + * or do other stuff before firmware gets freed. But NEVER use release + * to free the firmware itself!! This is done by the API right after calling + * release. + */ + void (*release_priv)(struct mbg_firmware*); + +} MBG_FIRMWARE; + + +typedef struct mbg_firmware_ufu +{ + unsigned idx; + MBG_FW_UFU_INFO info; + const struct mbg_firmware *firmware; ///< Backref to firmware + + /* Pointer for the mallocer to connect some private data */ + void *priv_data; + /* + * Can be used to free/release priv data (if necessary) + * or do other stuff before ufu gets freed. But NEVER use release + * to free the ufu itself!! This is done by the API right after calling + * release. + */ + void (*release_priv)(struct mbg_firmware_ufu*); + +} MBG_FIRMWARE_UFU; + + +typedef struct +{ + MBG_FW_GLB_INFO glb_info; + MBG_FIRMWARE *firmwares; /// Array of ::MBG_FW_GLB_INFO::installed_fws + +} ALL_FIRMWARE_INFO; + + +typedef struct mbg_database +{ + unsigned idx; + MBG_DATABASE_INFO info; + + /* Pointer for the mallocer to connect some private data */ + void *priv_data; + + /* + * Can be used to free/release priv data (if necessary) + * or do other stuff before ufu gets freed. But NEVER use release + * to free the ufu itself!! This is done by the API right after calling + * release. + */ + void (*release_priv)(struct mbg_database*); + +} MBG_DATABASE; + + +typedef struct +{ + MBG_DATABASE_GLB_INFO glb_info; + /// Array of ::MBG_DATABASE_GLB_INFO::num_dbs. Yes, until num_dbs!! + /// Databases might have different features and flags set, + /// thus query all info. + MBG_DATABASE *dbs; + +} ALL_DATABASE_INFO; + + +typedef struct +{ + unsigned codec; + const char *products; + +} MBG_EXT_SYS_INFO_CPU_CODEC; + +/// 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"} \ +} + + +/** + * @brief A mode specifying how to interpret a ::PCPS_SIG_VAL + * + * Used with ::PCPS_TIME_EXT::comp_sig_mode. Depending on this mode + * a signal value can be interpreted e.g. as signal strength (with + * long wave or IRIG time code receivers), or as indicator whether an + * antenna is connected (satellite receivers), or a network link is + * available (PTP slaves) or not, and an appropriate status message + * can be displayed. + * + * @see @ref PCPS_SIG_VAL_DEFS + */ +enum COMP_SIG_MODES +{ + COMP_SIG_MODE_NONE, ///< signal value not used + COMP_SIG_MODE_SIGNAL, ///< input signal strength + COMP_SIG_MODE_ANT_CONN, ///< antenna connection state + COMP_SIG_MODE_PORT_LINK, ///< port link state + N_CONN_SIG_MODES +}; + + +/** + * @brief Flag bits indicating if some extended status is available + * + * @see ::PCPS_TIME_EXT_FLAGS + */ +enum PCPS_TIME_EXT_FLAG_BITS +{ + PCPS_TIME_EXT_FLAG_BIT_UTC_VALID, ///< ::PCPS_TIME_EXT::utc_offs field is valid + N_PCPS_TIME_EXT_FLAG_BITS +}; + + +/** + * @brief Flag masks used with ::PCPS_TIME_EXT::flags + * + * @see ::PCPS_TIME_EXT_FLAG_BITS + */ +enum PCPS_TIME_EXT_FLAGS +{ + PCPS_TIME_EXT_FLAG_UTC_VALID = ( 1UL << PCPS_TIME_EXT_FLAG_BIT_UTC_VALID ) ///< see ::PCPS_TIME_EXT_FLAG_BIT_UTC_VALID +}; + + + +_ext BAUD_RATE mbg_baud_rates[N_MBG_BAUD_RATES] +#ifdef _DO_INIT + = MBG_BAUD_RATES +#endif +; + +_ext const char *mbg_baud_rate_strs[N_MBG_BAUD_RATES] +#ifdef _DO_INIT + = MBG_BAUD_STRS +#endif +; + +_ext const char *mbg_framing_strs[N_MBG_FRAMINGS] +#ifdef _DO_INIT + = MBG_FRAMING_STRS +#endif +; + +_ext const char *str_unknown +#ifdef _DO_INIT + = "unknown" +#endif +; + + +_ext const char *str_undefined +#ifdef _DO_INIT + = "(undefined)" +#endif +; + + +_ext const char *str_not_spc +#ifdef _DO_INIT + = "not " +#endif +; + + + +//### TODO +#define DEFAULT_MAX_STR_TYPE 2 // DEFAULT_N_STR_TYPE_GPS ? + +_ext STR_TYPE_INFO default_str_type_info[DEFAULT_MAX_STR_TYPE] +#ifdef _DO_INIT + = { + { DEFAULT_STR_MODES, "Default Time String", "Time", 0 }, + { DEFAULT_STR_MODES_UCAP, "Capture String", "Cap", 0 } + } +#endif +; + + + +_ext const char *mbg_gpio_type_names[N_MBG_GPIO_TYPES] +#ifdef _DO_INIT + = DEFAULT_GPIO_TYPES_SHORT_STRS +#endif +; + +#define _get_gpio_type_name( _i ) \ + ( ( (_i) < N_MBG_GPIO_TYPES ) ? mbg_gpio_type_names[_i] : str_unknown ) + + + +_ext const char *mbg_gpio_port_state_names[N_MBG_GPIO_PORT_STATES] +#ifdef _DO_INIT + = DEFAULT_GPIO_PORT_STATE_NAMES +#endif +; + +#define _get_gpio_port_state_name( _i ) \ + ( ( (_i) < N_MBG_GPIO_PORT_STATES ) ? mbg_gpio_port_state_names[_i] : str_unknown ) + + + +_ext const char *mbg_gpio_signal_shape_names[N_MBG_GPIO_SIGNAL_SHAPES] +#ifdef _DO_INIT + = DEFAULT_GPIO_SIGNAL_SHAPE_NAMES +#endif +; + +#define _get_gpio_signal_shape_name( _i ) \ + ( ( (_i) < N_MBG_GPIO_SIGNAL_SHAPES ) ? mbg_gpio_signal_shape_names[_i] : str_unknown ) + + + +_ext const char *mbg_gpio_fixed_freq_strs[N_MBG_GPIO_FIXED_FREQ] +#ifdef _DO_INIT + = MBG_GPIO_FIXED_FREQ_STRS +#endif +; + +#define _get_gpio_fixed_freq_str( _i ) \ + ( ( (_i) < N_MBG_GPIO_FIXED_FREQ ) ? mbg_gpio_fixed_freq_strs[_i] : str_unknown ) + + + +_ext const char *xmr_holdover_status_mode_names[N_XMR_HOLDOVER_STATUS_MODES] +#ifdef _DO_INIT + = XMR_HOLDOVER_STATUS_MODE_NAMES +#endif +; + +#define _get_xmr_holdover_status_mode_name( _i ) \ + ( ( (_i) < N_XMR_HOLDOVER_STATUS_MODES ) ? xmr_holdover_status_mode_names[_i] : str_unknown ) + + + +_ext const char *ptp_role_strs[N_PTP_ROLES] +#ifdef _DO_INIT + = PTP_ROLE_STRS +#endif +; + +#define _get_ptp_role_str_dflt( _i, _dflt ) \ + ( ( (_i) < N_PTP_ROLES ) ? ptp_role_strs[_i] : _dflt ) + +#define _get_ptp_role_str( _i ) \ + _get_ptp_role_str_dflt( _i, str_unknown ) + + + +_ext const char *ptp_nw_protocol_strs[N_PTP_NW_PROT] +#ifdef _DO_INIT + = PTP_NW_PROT_STRS +#endif +; + +#define _get_ptp_nw_protocol_str_dflt( _i, _dflt ) \ + ( ( (_i) < N_PTP_NW_PROT ) ? ptp_nw_protocol_strs[_i] : _dflt ) + +#define _get_ptp_nw_protocol_str( _i ) \ + _get_ptp_nw_protocol_str_dflt(_i, str_unknown ) + + + +_ext const char *ptp_port_state_strs[N_PTP_PORT_STATE] +#ifdef _DO_INIT + = PTP_PORT_STATE_STRS +#endif +; + +#define _get_ptp_port_state_str_dflt( _i, _dflt ) \ + ( ( (_i) < N_PTP_PORT_STATE ) ? ptp_port_state_strs[_i] : _dflt ) + +#define _get_ptp_port_state_str( _i ) \ + _get_ptp_port_state_str_dflt( _i, str_unknown ) + + + +_ext const char *ptp_clock_accuracy_strs[N_PTP_CLOCK_ACCURACY - PTP_CLOCK_ACCURACY_NUM_BIAS] +#ifdef _DO_INIT + = PTP_CLOCK_ACCURACY_STRS +#endif +; + +#define _get_ptp_clock_accuracy_str_dflt( _i, _dflt ) \ + ( ( ( (_i) >= PTP_CLOCK_ACCURACY_NUM_BIAS ) && ( (_i) < N_PTP_CLOCK_ACCURACY ) ) ? \ + ptp_clock_accuracy_strs[(_i) - PTP_CLOCK_ACCURACY_NUM_BIAS] : _dflt ) + +#define _get_ptp_clock_accuracy_str( _i ) \ + _get_ptp_clock_accuracy_str( _i, str_unknown ) + + + +_ext const char *ptp_delay_mechanism_strs[N_PTP_DELAY_MECH] +#ifdef _DO_INIT + = PTP_DELAY_MECH_NAMES +#endif +; + +#define _get_ptp_delay_mechanism_str_dflt( _i, _dflt ) \ + ( ( (_i) < N_PTP_DELAY_MECH ) ? ptp_delay_mechanism_strs[_i] : _dflt ) + +#define _get_ptp_delay_mechanism_str( _i ) \ + _get_ptp_delay_mechanism_str_dflt( _i, str_unknown ) + -/* function prototypes: */ +// Terminated by { 0, NULL } +_ext const PTP_TABLE ptp_time_source_table[] +#ifdef _DO_INIT + = PTP_TIME_SOURCE_TABLE +#endif +; + + + +/** + * @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 +int num_bits_set( long val ) +{ + int bits_set = 0; + size_t i; + + for ( i = 0; i < ( 8 * sizeof( val ) ); i++ ) + { + if ( val & 1 ) + bits_set++; + + val >>= 1; + } + + return bits_set; + +} // num_bits_set + + + +#if !defined( MBG_TGT_KERNEL ) + +/** + * @brief Check if a device ID refers to a serial port + * + * @param[in] dev_id A string with the device name or port name + * + * @see ::DEFAULT_SERIAL_DEVICE_NAME + * + * @return true if the device id contains the name of a serial port, else false + */ +static __mbg_inline +bool device_id_is_serial( const char *dev_id ) +{ + #if defined( MBG_TGT_NO_TGT ) + return false; //### FIXME + #elif defined( MBG_TGT_WIN32 ) + //##++++ There may be also serial ports under Windows + // which don't have "COM" in their name. + return strstr( dev_id, "COM" ) != NULL; + #elif defined( MBG_TGT_LINUX ) + return strstr( dev_id, "/dev/ttyS" ) != NULL // standard serial device + || strstr( dev_id, "/dev/ttyUSB" ) != NULL; // serial-to-USB adapter + #elif defined( MBG_TGT_FREEBSD ) + return strstr( dev_id, "/dev/ttyu" ) != NULL // dial-in device (standard), FreeBSD 10 and newer + || strstr( dev_id, "/dev/cuau" ) != NULL // dial out device, FreeBSD 10 and newer + || strstr( dev_id, "/dev/ttyd" ) != NULL // dial-in device (standard), before FreeBSD 10 + || strstr( dev_id, "/dev/cuad" ) != NULL; // dial-out device, before FreeBSD 10 + #elif defined( MBG_TGT_NETBSD ) + // TODO This is just an ugly hack which identifies + // some traditional device names as serial ports. + // There are quite a few other possible names. + // See "man 4 com" and "man 4 tty". + return strstr( dev_id, "/dev/tty0" ) != NULL // traditional dial-in devices + || strstr( dev_id, "/dev/dty0" ) != NULL; // traditional dial-out devices + #elif defined( MBG_TGT_QNX_NTO ) + return strstr( dev_id, "/dev/ser" ) != NULL; + #elif defined( MBG_TGT_DOS ) + return strstr( dev_id, "COM" ) != NULL; + #else + #error device_id_is_serial() needs to be implemented for this platform + #endif + +} // device_id_is_serial + + + +/** + * @brief Check if a device ID refers to a LAN connection + * + * @param[in] dev_id A string with the device ID + * + * @return true if the device id specifies a LAN connection, else false + */ +static __mbg_inline +bool device_id_is_lan( const char *dev_id ) +{ + return strstr( dev_id, "LAN" ) != NULL; + +} // device_id_is_lan + +#endif // !defined( MBG_TGT_KERNEL ) + + + +#if defined( _PRELIMINARY_CODE ) + +static __mbg_inline +MBG_TLV_UID mbg_tlv_create_id( void ) +{ +#if defined( MBG_TGT_LINUX ) ///### FIXME for FreeBSD and Windows + struct sysinfo info; + + // Linux specific, implement Windows equivalent + sysinfo( &info ); + return ( (MBG_TLV_UID) ( ( time( NULL ) >> 16 ) | ( info.uptime << 16 ) ) ); +#else + return rand(); +#endif +} // mbg_tlv_create_id + +#endif // defined( _PRELIMINARY_CODE ) + + + +#if !defined( MBG_TGT_KERNEL ) /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ + /** + * @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 + * contains an identifier string. + * + * 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. + * + * @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 + */ + int chk_sw_rev_name( SW_REV *p, int verbose ) ; + + int get_str_idx( const char *search, const char *str_table[], int n_entries ) ; + int get_baud_rate_idx( BAUD_RATE baud_rate ) ; + 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 + * ::PORT_PARM structure and set up the appropriate fields in a ::PORT_SETTINGS + * structure accordingly. + * + * @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 + * a capture string mode. Usually 1 for legacy devices. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::port_parm_mode_from_port_settings (the complementary function) + * @see ::port_settings_from_port_parm + */ + void port_settings_from_port_parm_mode( PORT_SETTINGS *p_ps, uint8_t pp_mode, int cap_str_idx ) ; + + /** + * @brief Convert a ::PORT_SETTINGS::mode to a legacy ::PORT_PARM::mode + * + * This function is used to derive a a legacy ::PORT_PARM::mode value + * from a ::PORT_SETTINGS structure. + * + * @param[out] pp_mode Pointer to a ::PORT_PARM::mode variable to be updated. + * @param[in] p_ps Pointer to a ::PORT_SETTINGS structure to be evaluated. + * @param[in] cap_str_idx The capture string index number for legacy devices, which is usually 1. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::port_settings_from_port_parm_mode (the complementary function) + * @see ::port_parm_from_port_settings + */ + 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 + * + * @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. + * @param[in] p_pp The ::PORT_PARM structure to be evaluated, contains settings for 2 ports. + * @param[in] cap_str_idx The capture string index number for legacy devices, which is usually 1. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::port_parm_from_port_settings (the complementary function) + * @see ::port_settings_from_port_parm_mode + */ + 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 + * + * @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. + * @param[out] p_ps Pointer to a ::PORT_SETTINGS structure to be updated. + * @param[in] cap_str_idx The capture string index number for legacy devices, which is usually 1. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::port_settings_from_port_parm (the complementary function) + * @see ::port_parm_mode_from_port_settings + */ + void port_parm_from_port_settings( PORT_PARM *p_pp, int port_idx, const PORT_SETTINGS *p_ps, int cap_str_idx ) ; + + 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 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 + * associated settings, and fills up the remaining ::PORT_INFO fields with + * the well-known supported settings, so applications can simple 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[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_parm ::FIXME + */ + int setup_port_info_from_port_parm( PORT_INFO_IDX pii[], const PORT_PARM *p_pp, const RECEIVER_INFO *p_ri ) ; + + int setup_default_str_type_info_idx( STR_TYPE_INFO_IDX stii[], const RECEIVER_INFO *p_ri ) ; + int chk_set_n_gnss_supp( ALL_GNSS_INFO *p_agi ) ; + /** + * @brief + * + * ### Setup GNSS info from stat_info so we can use the same printing routine + */ + void setup_gps_only_sat_info_idx_from_statinfo( ALL_GNSS_INFO *p_agi ) ; + + /** + * @brief + * + * Setup GNSS info from stat_info so we can use the same printing routine + */ + int setup_gps_only_gnss_info_from_statinfo( 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 + * + * @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) + * + * @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 ) ; + + /** + * @brief Initializes 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 + */ + 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 + * + * @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) + */ + 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 + * + * @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) + */ + 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) ; + _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 ) ; + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_mrf_none( const ALL_XMULTI_REF_INFO *info ) ; + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_src_info( const ALL_XMULTI_REF_INFO *info ) ; + _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 + */ + _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 + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_source_metrics( 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 ) ; + _NO_MBG_API_ATTR int _MBG_API chk_dev_ims_is_pll_locked( const ALL_IMS_STATE *ims_state, unsigned idx ) ; + _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 + * + * @param[out] info Pointer to a ::ALL_GPIO_INFO structure to be filled up + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_gpio + * @see ::mbg_chk_dev_has_gpio + * @see ::free_all_gpio_info + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_has_status( const ALL_GPIO_INFO *info ) ; + + /** + * @brief Free an ::ALL_XBP_INFO structure + * + * @param[in] p Pointer to the ::ALL_XBP_INFO structure to be freed + * + * @see ::mbgextio_get_all_xbp_info + */ + void free_all_xbp_info ( ALL_XBP_INFO *p ) ; + + /** + * @brief Free an ::ALL_NET_CFG_INFO structure + * + * @param[in] p Pointer to the ::ALL_NET_CFG_INFO structure to be freed + * + * @see ::mbgextio_get_all_net_cfg_info + */ + void free_all_net_cfg_info ( ALL_NET_CFG_INFO *p ) ; + + /** + * @brief Free an ::ALL_NET_STATUS_INFO structure + * + * @param[in] p Pointer to the ::ALL_NET_STATUS_INFO structure to be freed + * + * @see ::mbgextio_get_all_net_status_info + */ + void free_all_net_status_info ( ALL_NET_STATUS_INFO *p ) ; + + /** + * @brief Free an ::ALL_SNMP_INFO structure + * + * @param[in] p Pointer to the ::ALL_SNMP_INFO structure to be freed + */ + void free_all_snmp_info ( ALL_SNMP_INFO *p ) ; + + /** + * @brief Free an ::ALL_SYSLOG_INFO structure + * + * @param[in] p Pointer to the ::ALL_SYSLOG_INFO structure to be freed + */ + void free_all_syslog_info ( ALL_SYSLOG_INFO *p ) ; + + /** + * @brief Free an ::ALL_MONITORING_INFO structure + * + * @param[in] p Pointer to the ::ALL_MONITORING_INFO structure to be freed + */ + void free_all_monitoring_info ( ALL_MONITORING_INFO *p ) ; + + /** + * @brief Free an ::ALL_EVENTS structure + * + * @param[in] p Pointer to the ::ALL_EVENTS structure to be freed + */ + void free_all_events( ALL_EVENTS *p ) ; + + /** + * @brief Free an ::ALL_XMULTI_REF_INFO structure + * + * @param[in] p Pointer to the ::ALL_XMULTI_REF_INFO structure to be freed + * + * @see ::mbgextio_get_all_xmulti_ref_info + * @see ::mbg_get_all_xmulti_ref_info + */ + void free_all_xmulti_ref_info( ALL_XMULTI_REF_INFO *p ) ; + + /** + * @brief Free an ::ALL_XMULTI_REF_STATUS structure + * + * @param[in] p Pointer to the ::ALL_XMULTI_REF_STATUS structure to be freed + * + * @see ::mbgextio_get_all_xmulti_ref_status + * @see ::mbg_get_all_xmulti_ref_status + */ + void free_all_xmulti_ref_status( ALL_XMULTI_REF_STATUS *p ) ; + + /** + * @brief Free an ::ALL_PTP_V1_COMMON_DATASETS structure allocated by ::mbgextio_get_all_ptp_v1_common_datasets + * + * @param[in] p Pointer to the ::ALL_PTP_V1_COMMON_DATASETS structure to be freed + * + * @see ::mbgextio_get_all_ptp_v1_common_datasets + */ + void free_all_ptp_v1_common_datasets( ALL_PTP_V1_COMMON_DATASETS *p ) ; + + /** + * @brief Free an ::ALL_PTP_V2_COMMON_DATASETS structure allocated by ::mbgextio_get_all_ptp_v2_common_datasets + * + * @param[in] p Pointer to the ::ALL_PTP_V2_COMMON_DATASETS structure to be freed + * + * @see ::mbgextio_get_all_ptp_v2_common_datasets + */ + void free_all_ptp_v2_common_datasets( ALL_PTP_V2_COMMON_DATASETS *p ) ; + + /** + * @brief Free an ::ALL_NTP_CFG_INFO structure + * + * @param[in] p Pointer to the ::ALL_NTP_CFG_INFO structure to be freed + * + * @see ::mbgextio_get_all_ntp_cfg_info + */ + void free_all_ntp_cfg_info( ALL_NTP_CFG_INFO *p ) ; + + /** + * @brief Free an ::ALL_NTP_STATUS structure + * + * @param[in] p Pointer to the ::ALL_NTP_STATUS structure to be freed + * + * @see ::mbgextio_get_all_ntp_status + */ + void free_all_ntp_status( ALL_NTP_STATUS *p ) ; + + /** + * @brief Free memory allocated by ::mbgextio_get_all_ims_info + * + * @param[in] p Pointer to the ::ALL_IMS_INFO structure to be freed + * + * @see ::mbgextio_dev_has_ims + * @see ::mbgextio_get_all_ims_info + * @see ::mbgextio_get_all_ims_state + */ + void free_all_ims_info( ALL_IMS_INFO *p ) ; + + /** + * @brief Free memory allocated by ::mbgextio_get_all_ims_state + * + * @param[in] p Pointer to the ::ALL_IMS_STATE structure to be freed + * + * @see ::mbgextio_dev_has_ims + * @see ::mbgextio_get_all_ims_info + * @see ::mbgextio_get_all_ims_state + */ + void free_all_ims_state( ALL_IMS_STATE *p ) ; + + /** + * @brief Free memory allocated by ::mbgextio_get_all_gpio_info + * + * @param[in] p Pointer to the ::ALL_GPIO_INFO structure to be freed + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_gpio + * @see ::mbgextio_get_all_gpio_info + */ + void free_all_gpio_info( ALL_GPIO_INFO *p ) ; + + /** + * @brief Free memory allocated by ::mbgextio_get_all_io_ports + * + * @param[in] p Pointer to the ::ALL_MBG_IO_PORTS structure to be freed + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_io_ports + * @see ::mbgextio_get_all_io_ports + * @see ::mbgextio_get_all_io_port_status + */ + void free_all_io_ports( ALL_MBG_IO_PORTS *p ) ; + + /** + * @brief Free memory allocated by ::mbgextio_get_all_gpio_state + * + * @param[in] p Pointer to the ::ALL_GPIO_STATE structure to be freed + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_gpio + * @see ::mbgextio_get_all_gpio_state + */ + void free_all_gpio_state( ALL_GPIO_STATE *p ) ; + + /** + * Allocates memory for a new ::UCAP_ENTRY structure + * + * @return The new allocated ::UCAP_ENTRY or NULL if the calloc call was not successful + */ + UCAP_ENTRY* calloc_ucap_entry( void ) ; + + /** + * @brief Free memory allocated by ::mbgextio_get_all_ucap_info + * + * @param[in] p Pointer to the ::ALL_UCAP_INFO structure to freed + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_ucap + * @see ::mbg_chk_dev_has_ucap + * @see ::mbgextio_get_all_ucap_info + * @see ::mbg_get_all_ucap_info + */ + void free_all_ucap_info( ALL_UCAP_INFO *p ) ; + + /** + * @brief Free an ::ALL_UCAP_NET_INFO structure + * + * @param[in] p Pointer to the ::ALL_UCAP_NET_INFO structure to be freed + * + * @see ::mbgextio_get_all_ucap_net_info + */ + void free_all_ucap_net_info( ALL_UCAP_NET_INFO *p ) ; + + /** + * @brief Free an ::ALL_USER_INFO structure + * + * @param[in] p Pointer to the ::ALL_USER_INFO structure to be freed + * + * @see ::mbgextio_get_all_user_info + */ + void free_all_user_info( ALL_USER_INFO *p ) ; + + /** + * @brief Free an ::ALL_SERVICE_INFO structure + * + * @param[in] p Pointer to the ::ALL_SERVICE_INFO structure to be freed + * + * @see ::mbgextio_get_all_user_info + */ + void free_all_svc_info( ALL_SERVICE_INFO *p ) ; + + /** + * @brief Free an ::ALL_FIRMWARE_INFO structure + * + * @param[in] p Pointer to the ::ALL_FIRMWARE_INFO structure to be freed + * + * @see ::mbgextio_get_all_firmware_info + */ + void free_all_firmware_info( ALL_FIRMWARE_INFO *p ) ; + + /** + * @brief Free an ::ALL_DATABASE_INFO structure + * + * @param[in] p Pointer to the ::ALL_DATABASE_INFO structure to be freed + * + * @see ::mbgextio_get_all_database_info + */ + void free_all_database_info( ALL_DATABASE_INFO *p ) ; + + /** + * @brief Set up a ::NTP_TSTAMP structure from a hex string with a time in seconds and binary fractions + * + * @param[in] s A string with a time in seconds since NTP epoch 1900-01-01, + * with binary fractions separated by decimal point, + * e.g. 'dc763e43.73bd5a8f' as printed by the ntpq utility + * @param[out] p Address of a ::NTP_TSTAMP structure to be set up + * + * @see ::str_ntp_hex_to_nano_time_64 + */ + void str_ntp_hex_to_ntp_tstamp( const char *s, NTP_TSTAMP *p ) ; + + /** + * @brief Convert a ::NTP_TSTAMP structure to a ::NANO_TIME_64 structure + * + * @param[in] p_nts The ::NTP_TSTAMP structure to be converted + * @param[out] p_nt64 The ::NANO_TIME_64 structure to be filled up + */ + void ntp_tstamp_to_nanotime_64( const NTP_TSTAMP *p_nts, NANO_TIME_64 *p_nt64 ) ; + + /** + * @brief Set up a ::NANO_TIME_64 structure from a hex string with a time in seconds and binary fractions + * + * @param[in] s A string with a time in seconds since epoch 1900-01-01, + * with binary fractions separated by decimal point, + * e.g. 'dc763e43.73bd5a8f' as printed by the ntpq utility + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + * + * @see ::str_ntp_hex_to_ntp_tstamp + */ + void str_ntp_hex_to_nano_time_64( const char *s, NANO_TIME_64 *p ) ; + /* ----- function prototypes end ----- */ +#endif // !defined( MBG_TGT_KERNEL ) + #ifdef __cplusplus } #endif diff --git a/mbglib/common/charcode.h b/mbglib/common/charcode.h new file mode 100644 index 0000000..ca8b9e1 --- /dev/null +++ b/mbglib/common/charcode.h @@ -0,0 +1,275 @@ + +/************************************************************************** + * + * $Id: charcode.h 1.4 2016/08/10 12:25:41Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for pcpslstr.c. + * + * ----------------------------------------------------------------------- + * $Log: charcode.h $ + * Revision 1.4 2016/08/10 12:25:41Z martin + * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. + * Revision 1.3 2015/11/11 14:55:59 martin + * Support Unicode and UTF-8 encodings. + * Revision 1.2 2014/04/24 14:13:17 martin + * Added new codes and conversion table initializers. + * Revision 1.1 2012/11/20 13:41:24 martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _CHARCODE_H +#define _CHARCODE_H + + +/* Other headers to be included */ + +#include <mbg_tgt.h> + +#if MBG_TGT_HAS_WCHAR_T + #include <wchar.h> +#endif + +#ifdef _CHARCODE + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + + +#if defined( MBG_TGT_LINUX ) + + #define MBG_UML_UTF8 + +#elif defined( MBG_TGT_WIN32 ) \ + || defined( MBG_TGT_POSIX ) \ + || defined( MBG_TGT_QNX ) + + #define MBG_UML_ANSI + +#else + + #define MBG_UML_DOS + +#endif + + + +// upper case 'A' umlaut +#define ANSI_UC_A_UML '\xC4' // uppercase ANSI char +#define ANSI_US_A_UML "\xC4" // uppercase ANSI string literal + +#define DOS_UC_A_UML '\x8E' // uppercase DOS char +#define DOS_US_A_UML "\x8E" // uppercase DOS string literal + +#define UNICODE_US_A_UML "\u00C4" // uppercase Unicode string literal + +#define UTF8_US_A_UML "\xc3\x84" // uppercase UTF-8 string literal + + + +// upper case 'O' umlaut +#define ANSI_UC_O_UML '\xD6' // uppercase ANSI char +#define ANSI_US_O_UML "\xD6" // uppercase ANSI string literal + +#define DOS_UC_O_UML '\x99' // uppercase DOS char +#define DOS_US_O_UML "\x99" // uppercase DOS string literal + +#define UNICODE_US_O_UML "\u00D6" // uppercase Unicode string literal + +#define UTF8_US_O_UML "\xc3\x96" // uppercase UTF-8 string literal + + + +// upper case 'U' umlaut +#define ANSI_UC_U_UML '\xDC' // uppercase ANSI char +#define ANSI_US_U_UML "\xDC" // uppercase ANSI string literal + +#define DOS_UC_U_UML '\x9A' // uppercase DOS char +#define DOS_US_U_UML "\x9A" // uppercase DOS string literal + +#define UNICODE_US_U_UML "\u00DC" // uppercase Unicode string literal + +#define UTF8_US_U_UML "\xc3\x9c" // uppercase UTF-8 string literal + + + +// lower case 'a' umlaut +#define ANSI_LC_A_UML '\xE4' // lowercase ANSI char +#define ANSI_LS_A_UML "\xE4" // lowercase ANSI string literal + +#define DOS_LC_A_UML '\x84' // lowercase DOS char +#define DOS_LS_A_UML "\x84" // lowercase DOS string literal + +#define UNICODE_LS_A_UML "\u00E4" // lowercase Unicode string literal + +#define UTF8_LS_A_UML "\xc3\xa4" // lowercase UTF-8 string literal + + + +// lower case 'o' umlaut +#define ANSI_LC_O_UML '\xF6' // lowercase ANSI char +#define ANSI_LS_O_UML "\xF6" // lowercase ANSI string literal + +#define DOS_LC_O_UML '\x94' // lowercase DOS char +#define DOS_LS_O_UML "\x94" // lowercase DOS string literal + +#define UNICODE_LS_O_UML "\u00F6" // lowercase Unicode string literal + +#define UTF8_LS_O_UML "\xc3\xb6" // lowercase UTF-8 string literal + + + +// lower case 'u' umlaut +#define ANSI_LC_U_UML '\xFC' // lowercase ANSI char +#define ANSI_LS_U_UML "\xFC" // lowercase ANSI string literal + +#define DOS_LC_U_UML '\x81' // lowercase DOS char +#define DOS_LS_U_UML "\x81" // lowercase DOS string literal + +#define UNICODE_LS_U_UML "\u00FC" // lowercase Unicode string literal + +#define UTF8_LS_U_UML "\xc3\xbc" // lowercase UTF-8 string literal + + + +// 'sz' umlaut +#define ANSI_LC_SZ_UML '\xDF' // ANSI char +#define ANSI_LS_SZ_UML "\xDF" // ANSI string literal + +#define DOS_LC_SZ_UML '\xE1' // DOS char +#define DOS_LS_SZ_UML "\xE1" // DOS string literal + +#define UNICODE_LS_SZ_UML "\u00DF" // Unicode string literal + +#define UTF8_LS_SZ_UML "\xc3\x9f" // UTF-8 string literal + + + +// degree character +#define ANSI_C_DEGREE '\xB0' // ANSI char +#define ANSI_S_DEGREE "\xB0" // ANSI string literal + +#define DOS_C_DEGREE '\xF8' // DOS char +#define DOS_S_DEGREE "\xF8" // DOS string literal + +#define UNICODE_S_DEGREE "\u00E0" // Unicode string liter + +#define UTF8_S_DEGREE "\xc2\xb0" // UTF-8 string literal + + + +// greek mu character (micro sign) +#define ANSI_C_MU '\xB5' // ANSI char +#define ANSI_S_MU "\xB5" // ANSI string literal + +#define DOS_C_MU '\xE6' // DOS char +#define DOS_S_MU "\xE6" // DOS string literal + +#define UNICODE_S_MU "\u00B5" // Unicode string liter + +#define UTF8_S_MU "\xc2\xb5" // UTF-8 string literal + + + +#if defined( MBG_UML_UTF8 ) + + #define UCAE UTF8_US_A_UML + #define UCOE UTF8_US_O_UML + #define UCUE UTF8_US_U_UML + + #define LCAE UTF8_LS_A_UML + #define LCOE UTF8_LS_O_UML + #define LCUE UTF8_LS_U_UML + + #define LCSZ UTF8_LS_SZ_UML + #define DEG UTF8_S_DEGREE + #define MU UTF8_S_MU + +#elif defined( MBG_UML_ANSI ) + + #define UCAE ANSI_US_A_UML + #define UCOE ANSI_US_O_UML + #define UCUE ANSI_US_U_UML + + #define LCAE ANSI_LS_A_UML + #define LCOE ANSI_LS_O_UML + #define LCUE ANSI_LS_U_UML + + #define LCSZ ANSI_LS_SZ_UML + #define DEG ANSI_S_DEGREE + #define MU ANSI_S_MU + +#elif defined( MBG_UML_DOS ) + + #define UCAE DOS_US_A_UML + #define UCOE DOS_US_O_UML + #define UCUE DOS_US_U_UML + + #define LCAE DOS_LS_A_UML + #define LCOE DOS_LS_O_UML + #define LCUE DOS_LS_U_UML + + #define LCSZ DOS_LS_SZ_UML + #define DEG DOS_S_DEGREE + #define MU DOS_S_MU + +#else + + #error Need to define default encoding for umlauts. + +#endif + + + +// A string initializer which can be used to set up a string +// to check if all umlauts are displayed correctly. +#define UMLAUTS_STRING UCAE UCOE UCUE LCAE LCOE LCUE LCSZ DEG MU + + +#define ANSI_UMLAUTS \ +{ \ + ANSI_UC_A_UML, ANSI_UC_O_UML, ANSI_UC_U_UML, \ + ANSI_LC_A_UML, ANSI_LC_O_UML, ANSI_LC_U_UML, \ + ANSI_LC_SZ_UML, ANSI_C_DEGREE, ANSI_C_MU, 0 \ +} + + +#define DOS_UMLAUTS \ +{ \ + DOS_UC_A_UML, DOS_UC_O_UML, DOS_UC_U_UML, \ + DOS_LC_A_UML, DOS_LC_O_UML, DOS_LC_U_UML, \ + DOS_LC_SZ_UML, DOS_C_DEGREE, DOS_S_MU, 0 \ +} + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + +/* (no header definitions found) */ + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _CHARCODE_H */ diff --git a/mbglib/common/cmp_time_util.c b/mbglib/common/cmp_time_util.c new file mode 100644 index 0000000..4e99cc6 --- /dev/null +++ b/mbglib/common/cmp_time_util.c @@ -0,0 +1,240 @@ + +/************************************************************************** + * + * $Id: cmp_time_util.c 1.3 2018/12/11 12:01:03Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Common device time compare utility functions. + * + * ----------------------------------------------------------------------- + * $Log: cmp_time_util.c $ + * Revision 1.3 2018/12/11 12:01:03Z martin + * Fixed compiler warnings on Windows. + * Revision 1.2 2018/08/08 08:22:23Z martin + * New function mbg_snprint_hr_time_loc(). + * Account for renamed library symbols. + * Removed obsolete code. + * Revision 1.1 2013/07/25 10:42:59 martin + * Initial revision. + * + **************************************************************************/ + +#define _CMP_TIME_UTIL + #include <cmp_time_util.h> +#undef _CMP_TIME_UTIL + +#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 + +#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 + * + * @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 ) +{ + int rc; + const char n_supp_msg[] = "fast (memory mapped) time stamps"; + + rc = chk_feat_supp( dh1, p_dev_1, mbg_chk_dev_has_fast_hr_timestamp, + err_msg_fnc, n_supp_msg ); + + if ( mbg_rc_is_success( rc ) ) + rc = chk_feat_supp( dh2, p_dev_2, mbg_chk_dev_has_fast_hr_timestamp, + err_msg_fnc, n_supp_msg ); + return rc; + +} // chk_fast_tstamp_supp + + + +/*HDR*/ +/** + * @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 + * + * @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 ) +{ + int rc; + + if ( read_fast ) + { + PCPS_TIME_STAMP_CYCLES ts_c1; + PCPS_TIME_STAMP_CYCLES ts_c2; + + rc = mbg_get_fast_hr_timestamp_cycles( dh1, &ts_c1 ); + + if ( mbg_cond_err_msg( rc, "mbg_get_fast_hr_timestamp_cycles 1" ) ) + goto done; + + rc = mbg_get_fast_hr_timestamp_cycles( dh2, &ts_c2 ); + + if ( mbg_cond_err_msg( rc, "mbg_get_fast_hr_timestamp_cycles 2" ) ) + goto done; + + setup_hr_time_cycles_from_timestamp_cycles( p_htc1, &ts_c1 ); + setup_hr_time_cycles_from_timestamp_cycles( p_htc2, &ts_c2 ); + } + else + { + rc = mbg_get_hr_time_cycles( dh1, p_htc1 ); + + if ( mbg_cond_err_msg( rc, "mbg_get_hr_time_cycles 1" ) ) + goto done; + + rc = mbg_get_hr_time_cycles( dh2, p_htc2 ); + + if ( mbg_cond_err_msg( rc, "mbg_get_hr_time_cycles 2" ) ) + goto done; + } + +done: + return rc; + +} // get_htc_timestamps + + + +/*HDR*/ +/** + * @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. + * + * @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 ) +{ + double delta_ts; + double delta_cyc; + + delta_ts = (double) p_htc->t.tstamp.sec + dfrac_sec_from_bin( p_htc->t.tstamp.frac ) + - (double) p_htc_ref->t.tstamp.sec - dfrac_sec_from_bin( p_htc_ref->t.tstamp.frac ); + + #if defined( MBG_TGT_WIN32 ) + { + __int64 dt_t = p_htc->cycles - p_htc_ref->cycles; + delta_cyc = (double) dt_t / (__int64) cyc_freq; + } + #else + delta_cyc = ( (double) ( p_htc->cycles - p_htc_ref->cycles ) ) / cyc_freq; + #endif + + if ( p_delta_ts ) + *p_delta_ts = delta_ts; + + if ( p_delta_cyc ) + *p_delta_cyc = delta_cyc; + + return delta_ts - delta_cyc; + +} // get_htc_delta + + + +/*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. + * + * @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_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. + * + * @see ::mbg_snprint_hr_tstamp + * @see ::mbg_snprint_hr_time_loc + */ +int mbg_snprint_hr_tstamp_ext( char *s, int max_len, + const PCPS_TIME_STAMP *p, int print_raw ) +{ + int n = mbg_snprint_hr_tstamp( s, max_len, p, 0, 0 ); + + if ( print_raw ) + n += snprintf( &s[n], max_len - n, " (0x%08lX.%08lX)", + (ulong) p->sec, + (ulong) p->frac ); + + return n; + +} // mbg_snprint_hr_tstamp_ext + + + +/*HDR*/ +/** + * @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. + * + * @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_STAMP structure to be evaluated. + * + * @return The number of characters printed to the buffer. + * + * @see ::mbg_snprint_hr_tstamp + * @see ::mbg_snprint_hr_tstamp_ext + */ +int mbg_snprint_hr_time_loc( char *s, size_t max_len, const PCPS_HR_TIME *p ) +{ + size_t n = mbg_snprint_hr_tstamp( s, max_len, &p->tstamp, p->utc_offs, 0 ); + + n += snprintf_safe( &s[n], max_len - n, " UTC" ); + + if ( !(p->status & PCPS_UTC ) ) + n += mbg_str_pcps_hr_time_offs( &s[n], (int) ( max_len - n ), p, "" ); + +#if 0 + if(p->utc_offs != 0) + n += mbg_snprintf( n, len_s - n, "(%+02luh", + ( pt->utc_offs < 0 ) ? '-' : '+', + ldt.quot, ldt.rem ); +#endif + + return _int_from_size_t( n ); + +} // mbg_snprint_hr_time_loc + + diff --git a/mbglib/common/cmp_time_util.h b/mbglib/common/cmp_time_util.h new file mode 100644 index 0000000..ad93f7e --- /dev/null +++ b/mbglib/common/cmp_time_util.h @@ -0,0 +1,157 @@ + +/************************************************************************** + * + * $Id: cmp_time_util.h 1.2 2018/08/08 08:23:28Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for cmp_time_util.c. + * + * ----------------------------------------------------------------------- + * $Log: cmp_time_util.h $ + * Revision 1.2 2018/08/08 08:23:28Z martin + * Moved some functions and structures to more convenient files. + * Fixed Windows build. + * Updated function prototypes. + * Revision 1.1 2013/07/25 10:42:59 martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _CMP_TIME_UTIL_H +#define _CMP_TIME_UTIL_H + + +/* Other headers to be included */ + +#include <mbgdevio.h> +#include <deviohlp.h> + +#ifdef _CMP_TIME_UTIL + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#if 0 && defined( _USE_PACK ) // use default alignment + #pragma pack( 1 ) // set byte alignment + #define _USING_BYTE_ALIGNMENT +#endif + + +#ifdef __cplusplus +extern "C" { +#endif + +_ext MBG_PC_CYCLES_FREQUENCY cyc_freq; + +#if defined( MBG_TGT_WIN32 ) + #define snprintf _snprintf +#endif + + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + /** + * @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 + * + * @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 + * + * @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 + */ + 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 + * + * @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. + * + * @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 + * + * This function is mostly similar to ::mbg_snprint_hr_tstamp, but optionally + * appends the raw timestamp instead of inserting it at the beginning. + * + * @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_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. + * + * @see ::mbg_snprint_hr_tstamp + * @see ::mbg_snprint_hr_time_loc + */ + 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 + * + * This function is mostly similar to ::mbg_snprint_hr_tstamp, but optionally + * appends the raw timestamp instead of inserting it at the beginning. + * + * @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_STAMP structure to be evaluated. + * + * @return The number of characters printed to the buffer. + * + * @see ::mbg_snprint_hr_tstamp + * @see ::mbg_snprint_hr_tstamp_ext + */ + int mbg_snprint_hr_time_loc( char *s, size_t max_len, const PCPS_HR_TIME *p ) ; + + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + + +#if defined( _USING_BYTE_ALIGNMENT ) + #pragma pack() // set default alignment + #undef _USING_BYTE_ALIGNMENT +#endif + +/* End of header body */ + + +#undef _ext +#undef _DO_INIT + +#endif /* _CMP_TIME_UTIL_H */ + diff --git a/mbglib/common/cnv_wday.h b/mbglib/common/cnv_wday.h index 7736135..327d69d 100644 --- a/mbglib/common/cnv_wday.h +++ b/mbglib/common/cnv_wday.h @@ -1,7 +1,7 @@ /***************************************************************************/ /* */ -/* File: CNV_WDAY.H $Revision: 1.1 $ */ +/* File: CNV_WDAY.H $Revision: 1.2 $ */ /* */ /* Project: Common C Library */ /* */ @@ -24,18 +24,10 @@ /* */ /***************************************************************************/ - #ifndef _CNV_WDAY_H - /* Other headers to be included */ - - -#ifdef __cplusplus -extern "C" { -#endif - #ifdef _CNV_WDAY #define _ext #else @@ -45,6 +37,10 @@ extern "C" { /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + /* use the following macros if sure that the source value is in range */ @@ -80,11 +76,6 @@ extern "C" { #define _wday_chk_sun17_to_sun06( d ) _inrng( (d), _wday_sun17_to_sun06( (d) ), 1, 0, 7, 6 ) #define _wday_chk_sun06_to_sun17( d ) _inrng( (d), _wday_sun06_to_sun17( (d) ), 0, 1, 6, 7 ) - -/* function prototypes: */ - -/* #include <CNV_WDAY.hdr> not needed yet */ - /* End of header body */ diff --git a/mbglib/common/ctry.h b/mbglib/common/ctry.h index f66b817..816ebaf 100644 --- a/mbglib/common/ctry.h +++ b/mbglib/common/ctry.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: ctry.h 1.13 2012/11/29 12:01:09Z martin REL_M $ + * $Id: ctry.h 1.14 2017/06/23 09:53:27Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,8 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: ctry.h $ - * Revision 1.13 2012/11/29 12:01:09Z martin - * Don't include mbg_tgt.h explicitely since this will anyway be + * Revision 1.14 2017/06/23 09:53:27Z 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 * included by words.h for non-firmware targets. So mbg_tgt.h * must not necessarily be added to firmware projects. * Revision 1.12 2011/06/22 07:37:57Z martin @@ -36,11 +38,11 @@ * Revision 1.4 2000/11/27 14:13:27 MARTIN * New types CLSTR, PLSTR, and PCLSTR. * New macro _lstr() calls lstr_lng() for the current language. - * Definitions associated with ctry_fmt_dt() and ctry_fmt_times() + * Definitions associated with ctry_fmt_dt() and ctry_fmt_times() * have been moved to a new file ctry_fmt.h. * Updated function prototypes. * Revision 1.3 2000/08/17 15:35:02 MARTIN - * No init function by default (previously DOS), + * No init function by default (previously DOS), * Revision 1.2 2000/07/21 09:48:34 MARTIN * Initial revision * diff --git a/mbglib/common/ctrydttm.c b/mbglib/common/ctrydttm.c index d846ed8..5460b4a 100644 --- a/mbglib/common/ctrydttm.c +++ b/mbglib/common/ctrydttm.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: ctrydttm.c 1.5 2008/11/24 16:15:46Z martin REL_M $ + * $Id: ctrydttm.c 1.10 2018/12/11 16:01:46Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,11 +11,22 @@ * * ----------------------------------------------------------------------- * $Log: ctrydttm.c $ + * Revision 1.10 2018/12/11 16:01:46Z martin + * Use standard int types for more compatibility. + * Revision 1.9 2018/12/11 11:49:00Z martin + * Fixed compiler warnings on Windows. + * Revision 1.8 2018/01/02 16:13:55Z martin + * Changed return type of snprint_() functions from size_t to int. + * Revision 1.7 2015/11/09 11:22:12Z martin + * Modified snprint_ctry_dt_short() and fixed snprint_ctry_dt(). + * Revision 1.6 2015/08/31 10:00:46 martin + * Use safe string functions from str_util.c. + * This required renaming of functions and changing parameters. * Revision 1.5 2008/11/24 16:15:46Z martin * Don't use sprintf() without format string. * Revision 1.4 2000/11/27 10:06:27 MARTIN * Renamed local variable wday_str to lstrs_wday. - * If macro USER_LSTR_WDAY is defined, lstrs_wday can be declared + * If macro USER_LSTR_WDAY is defined, lstrs_wday can be declared * externally to override the defaults. * Revision 1.3 2000/09/14 15:13:25 MARTIN * Renamed sprint_short_ctry_dt() to sprint_ctry_dt_short() to match @@ -30,6 +41,7 @@ #undef _CTRYDTTM #include <ctry.h> +#include <str_util.h> #include <stdio.h> @@ -53,45 +65,44 @@ extern LANGUAGE language; /*HDR*/ -ushort sprint_02u( char *s, uchar uc ) +int snprint_02u( char *s, size_t max_len, unsigned int uc ) { - return( sprintf( s, "%02u", uc ) ); + return snprintf_safe( s, max_len, "%02u", uc ); -} // sprint_02u +} // snprint_02u /*HDR*/ -ushort sprint_04u( char *s, ushort us ) +int snprint_04u( char *s, size_t max_len, unsigned int us ) { - return( sprintf( s, "%04u", us ) ); + return snprintf_safe( s, max_len, "%04u", us ); -} // sprint_04u +} // snprint_04u /*HDR*/ -ushort sprint_ctry_wday( char *s, uchar wday, ushort language ) +int snprint_ctry_wday( char *s, size_t max_len, int wday, LANGUAGE language ) { if ( language >= N_LNG ) language = LNG_ENGLISH; - return( sprintf( s, "%s", ( wday < DAYS_PER_WEEK ) ? - lstrs_wday[language][wday] : "--" ) ); + return snprintf_safe( s, max_len, "%s", ( wday < DAYS_PER_WEEK ) ? + lstrs_wday[language][wday] : "--" ); -} // sprint_ctry_wday +} // snprint_ctry_wday /*HDR*/ -ushort sprint_ctry_dt_short( char *s, uchar mday, uchar month ) +int snprint_ctry_dt_short( char *s, size_t max_len, int mday, int month ) { uchar tmp_1; uchar tmp_2; ushort n = 0; - - switch( ctry.dt_fmt ) + switch ( ctry.dt_fmt ) { case DT_FMT_YYYYMMDD: case DT_FMT_MMDDYYYY: @@ -106,79 +117,77 @@ ushort sprint_ctry_dt_short( char *s, uchar mday, uchar month ) } // switch - n = sprint_02u( s, tmp_1 ); - s[n++] = ctry.dt_sep; - n += sprint_02u( &s[n], tmp_2 ); - s[n++] = ctry.dt_sep; - s[n] = 0; + n = snprint_02u( s, max_len, tmp_1 ); + n += sn_cpy_char_safe( &s[n], max_len - n, ctry.dt_sep ); + n += snprint_02u( &s[n], max_len - n, tmp_2 ); - return( n ); + return n; -} // sprint_ctry_dt_short +} // snprint_ctry_dt_short /*HDR*/ -ushort sprint_ctry_dt( char *s, uchar mday, uchar month, ushort year ) +int snprint_ctry_dt( char *s, size_t max_len, int mday, int month, int year ) { - ushort n = 0; - + size_t n = 0; if ( ctry.dt_fmt == DT_FMT_YYYYMMDD ) { - n = sprint_04u( s, year ); - s[n++] = ctry.dt_sep; + n += snprint_04u( &s[n], max_len - n, year ); + n += sn_cpy_char_safe( &s[n], max_len - n, ctry.dt_sep ); } - n += sprint_ctry_dt_short( &s[n], mday, month ); + n += snprint_ctry_dt_short( &s[n], max_len - n, mday, month ); - if ( ctry.dt_fmt == DT_FMT_YYYYMMDD ) - s[--n] = 0; - else - n += sprint_04u( &s[n], year ); + if ( ctry.dt_fmt != DT_FMT_YYYYMMDD ) + { + n += sn_cpy_char_safe( &s[n], max_len - n, ctry.dt_sep ); + n += snprint_04u( &s[n], max_len - n, year ); + } - return( n ); + return _int_from_size_t( n ); -} // sprint_ctry_dt +} // snprint_ctry_dt /*HDR*/ -ushort sprint_ctry_tm_short( char *s, uchar hour, uchar minute ) +int snprint_ctry_tm_short( char *s, size_t max_len, uchar hour, uchar minute ) { - ushort n = sprint_02u( s, hour ); - s[n++] = ctry.tm_sep; - n += sprint_02u( &s[n], minute ); + size_t n = snprint_02u( s, max_len, hour ); + n += sn_cpy_char_safe( &s[n], max_len - n, ctry.tm_sep ); + n += snprint_02u( &s[n], max_len - n, minute ); - return( n ); + return _int_from_size_t( n ); -} // sprint_ctry_tm_short +} // snprint_ctry_tm_short /*HDR*/ -ushort sprint_ctry_tm( char *s, uchar hour, uchar minute, uchar second ) +int snprint_ctry_tm( char *s, size_t max_len, uchar hour, uchar minute, uchar second ) { - ushort n = sprint_ctry_tm_short( s, hour, minute ); - s[n++] = ctry.tm_sep; - n += sprint_02u( &s[n], second ); + size_t n = snprint_ctry_tm_short( s, max_len, hour, minute ); + n += sn_cpy_char_safe( &s[n], max_len - n, ctry.tm_sep ); + n += snprint_02u( &s[n], max_len - n, second ); - return( n ); + return _int_from_size_t( n ); -} // sprint_ctry_tm +} // snprint_ctry_tm /*HDR*/ -ushort sprint_ctry_tm_long( char *s, uchar hour, uchar minute, uchar second, - long frac, ushort frac_digits ) +int snprint_ctry_tm_long( char *s, size_t max_len, uchar hour, uchar minute, + uchar second, long frac, ushort frac_digits ) { - ushort n = sprint_ctry_tm( s, hour, minute, second ); - s[n++] = '.'; - n += sprintf( &s[n], "%0*lu", frac_digits, frac ); + size_t n = snprint_ctry_tm( s, max_len, hour, minute, second ); + n += sn_cpy_char_safe( &s[n], max_len - n, '.' ); + n += snprintf_safe( &s[n], max_len - n, "%0*lu", frac_digits, frac ); - return( n ); + return _int_from_size_t( n ); -} // sprint_ctry_tm_long +} // snprint_ctry_tm_long diff --git a/mbglib/common/ctrydttm.h b/mbglib/common/ctrydttm.h index 8032d89..bbc7bf4 100644 --- a/mbglib/common/ctrydttm.h +++ b/mbglib/common/ctrydttm.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: ctrydttm.h 1.3 2000/09/14 15:13:45Z MARTIN REL_M $ + * $Id: ctrydttm.h 1.7 2018/12/11 16:01:48Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,15 @@ * * ----------------------------------------------------------------------- * $Log: ctrydttm.h $ - * Revision 1.3 2000/09/14 15:13:45Z MARTIN + * Revision 1.7 2018/12/11 16:01:48Z martin + * Updated function prototypes. + * Revision 1.6 2018/01/02 16:15:06Z martin + * Updated function prototypes. + * Revision 1.5 2015/08/31 10:00:46Z martin + * Fixed DOS build. + * Revision 1.4 2015/08/27 16:28:25Z martin + * Updated function prototypes. + * Revision 1.3 2000/09/14 15:13:45 MARTIN * Updated function prototypes. * Revision 1.2 2000/07/21 11:50:43 MARTIN * Initial revision @@ -25,6 +33,8 @@ #include <ctry.h> +#include <stdlib.h> + #ifdef __cplusplus extern "C" { @@ -49,14 +59,14 @@ extern "C" { /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ - ushort sprint_02u( char *s, uchar uc ) ; - ushort sprint_04u( char *s, ushort us ) ; - ushort sprint_ctry_wday( char *s, uchar wday, ushort language ) ; - ushort sprint_ctry_dt_short( char *s, uchar mday, uchar month ) ; - ushort sprint_ctry_dt( char *s, uchar mday, uchar month, ushort year ) ; - ushort sprint_ctry_tm_short( char *s, uchar hour, uchar minute ) ; - ushort sprint_ctry_tm( char *s, uchar hour, uchar minute, uchar second ) ; - ushort sprint_ctry_tm_long( char *s, uchar hour, uchar minute, uchar second, long frac, ushort frac_digits ) ; + int snprint_02u( char *s, size_t max_len, unsigned int uc ) ; + int snprint_04u( char *s, size_t max_len, unsigned int us ) ; + int snprint_ctry_wday( char *s, size_t max_len, int wday, LANGUAGE language ) ; + int snprint_ctry_dt_short( char *s, size_t max_len, int mday, int month ) ; + int snprint_ctry_dt( char *s, size_t max_len, int mday, int month, int year ) ; + int snprint_ctry_tm_short( char *s, size_t max_len, uchar hour, uchar minute ) ; + int snprint_ctry_tm( char *s, size_t max_len, uchar hour, uchar minute, uchar second ) ; + int snprint_ctry_tm_long( char *s, size_t max_len, uchar hour, uchar minute, uchar second, long frac, ushort frac_digits ) ; /* ----- function prototypes end ----- */ diff --git a/mbglib/common/deviohlp.c b/mbglib/common/deviohlp.c index 8de1a19..5f557eb 100644 --- a/mbglib/common/deviohlp.c +++ b/mbglib/common/deviohlp.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: deviohlp.c 1.2 2012/10/15 13:48:35Z martin REL_M $ + * $Id: deviohlp.c 1.7 2018/09/19 16:54:12Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -18,24 +18,22 @@ * * ----------------------------------------------------------------------- * $Log: deviohlp.c $ + * Revision 1.7 2018/09/19 16:54:12Z 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. + * Added some comments. + * Revision 1.5 2018/04/24 16:10:46 martin + * Use predefined symbols to print ASIC version. + * Revision 1.4 2018/01/10 11:49:17 martin + * Removed usage of obsolete symbol MBGDEVIO_SIMPLE. + * Revision 1.3 2017/07/05 13:47:44 martin + * Many configuration functions provided by thomas-b, + * philipp, and martin. * Revision 1.2 2012/10/15 13:48:35Z martin * Added functions mbg_get_all_ptp_cfg_info(), mbg_save_all_ptp_cfg_info(). - * Revision 1.1.1.9 2012/07/18 11:00:46 martin - * Revision 1.1.1.8 2012/07/12 09:07:36Z martin - * Revision 1.1.1.7 2012/07/12 08:38:50Z martin * Account for renamed structure. - * Revision 1.1.1.6 2012/07/10 09:53:57 martin - * Revision 1.1.1.5 2012/04/11 15:45:10Z martin * Updated doxygen comments. - * Revision 1.1.1.4 2011/09/21 14:45:24 martin - * Moved mbgextio support functions to new module extiohlp.c. - * Revision 1.1.1.3 2011/09/20 15:36:02 marvin - * new functions: - * mbg_get_serial_settings - * mbg_set_serial_settings - * include mbgextio.h - * Revision 1.1.1.2 2011/08/05 10:30:28 martin - * Revision 1.1.1.1 2011/08/05 09:55:52 martin * Revision 1.1 2011/08/03 15:37:00Z martin * Initial revision with functions moved here from mbgdevio. * @@ -45,104 +43,281 @@ #include <deviohlp.h> #undef _DEVIOHLP -#include <parmpcps.h> -#include <parmgps.h> +#include <str_util.h> +#include <lan_util.h> +#include <stdio.h> + + +#define DEFAULT_BAUD_RATES_DCF \ +( \ + MBG_PORT_HAS_300 | \ + MBG_PORT_HAS_600 | \ + MBG_PORT_HAS_1200 | \ + MBG_PORT_HAS_2400 | \ + MBG_PORT_HAS_4800 | \ + 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 | \ + MBG_PORT_HAS_38400 \ +) + + +#define DEFAULT_FRAMINGS_DCF \ +( \ + MBG_PORT_HAS_7E2 | \ + MBG_PORT_HAS_8N1 | \ + MBG_PORT_HAS_8N2 | \ + MBG_PORT_HAS_8E1 \ +) + + +/*HDR*/ +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 ) +{ + const char *cp = NULL; + int rc = MBG_SUCCESS; // assume option is supported + + if ( chk_supp_fnc == NULL ) // no check function specified + goto out; + + + // A check function has been specified, so we must call it to check if + // the specific parameter/command is supported by this particular device. + + if ( dh == MBG_INVALID_DEV_HANDLE ) + { + cp = "Tried checking feature support with invalid device handle."; + rc = MBG_ERR_INV_HANDLE; + goto out; + } + + rc = chk_supp_fnc( dh ); + + if ( mbg_rc_is_success( rc ) ) + goto out; // return with success + + + if ( rc == MBG_ERR_NOT_SUPP_BY_DEV ) + { + cp = not_supp_msg; + goto fail; + } + + + cp = "Failed to check if supported"; //##++++ TODO:proper error msg + +fail: + if ( err_msg_fnc && cp ) + err_msg_fnc( p_dev, cp ); + +out: + return rc; + +} // chk_feat_supp /*HDR*/ /** - Read all serial port settings and supported configuration parameters. + * @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, ...). + * + * 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 + * 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 + * 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 + * 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 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbg_get_gps_stat_info + * @see ::mbg_get_gps_gnss_mode_info + * @see ::mbg_get_gps_all_gnss_sat_info + */ +int mbg_chk_get_all_gnss_info( MBG_DEV_HANDLE dh, ALL_GNSS_INFO *p_agi ) +{ + int rc = MBG_ERR_UNSPEC; + + memset( p_agi, 0, sizeof( *p_agi ) ); + + // First we check if the device is a GPS receiver, + // which includes GNSS receivers. + rc = mbg_chk_dev_is_gps( dh ); + + if ( mbg_rc_is_error( rc ) ) + goto out; + + + // Read the STAT_INFO structure which is supported by all GPS + // and GNSS receivers. + rc = mbg_get_gps_stat_info( dh, &p_agi->stat_info ); + + if ( mbg_rc_is_error( rc ) ) + goto out; + + + // Check if the device is a GNSS receiver, i.e. can track satellites + // from different systems (GPS, GLONASS, Beidou, ...). + rc = mbg_chk_dev_is_gnss( dh ); + + if ( mbg_rc_is_success( rc ) ) + { + // The device is a GNSS receiver, i.e. it can track satellites + // from different systems (GPS, GLONASS, Beidou, ...). + // Read some specific GNSS information. + rc = mbg_get_gps_gnss_mode_info( dh, &p_agi->gnss_mode_info ); + + if ( mbg_rc_is_error( rc ) ) + goto out; + + + rc = chk_set_n_gnss_supp( p_agi ); + + if ( mbg_rc_is_error( rc ) ) + goto out; + + + // 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 + // 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 ); - 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 must be passed to this function. +out: + return rc; - The complementary function mbg_save_serial_settings() should be used - to write the modified serial port configuration back to the board. +} // mbg_chk_get_all_gnss_info - @param dh Valid handle to a Meinberg device. - @param *pdev Pointer to a ::PCPS_DEV structure. - @param *pcfg Pointer to a ::RECEIVER_PORT_CFG structure to be filled up. - @param *p_ri Pointer to a ::RECEIVER_INFO structure. - @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() -*/ +/*HDR*/ +/** + * @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. + * + * @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 + * + * @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 *pdev, - RECEIVER_PORT_CFG *pcfg, + const PCPS_DEV *p_dev, + RECEIVER_PORT_CFG *p_rpcfg, const RECEIVER_INFO *p_ri ) { int rc; - int i; - memset( pcfg, 0, sizeof( *pcfg ) ); + memset( p_rpcfg, 0, sizeof( *p_rpcfg ) ); - if ( _pcps_has_receiver_info( pdev ) ) + if ( _pcps_has_receiver_info( p_dev ) ) { - rc = mbg_get_gps_all_port_info( dh, pcfg->pii, p_ri ); - if ( rc != MBG_SUCCESS ) - goto error; + // The device provides a RECEIVER_INFO, so we can simply read all + // serial port configuration and supported string types directly. - rc = mbg_get_gps_all_str_type_info( dh, pcfg->stii, p_ri ); - if ( rc != MBG_SUCCESS ) - goto error; + rc = mbg_get_gps_all_port_info( dh, p_rpcfg->pii, p_ri ); + + if ( mbg_rc_is_error( rc ) ) + goto out; + + rc = mbg_get_gps_all_str_type_info( dh, p_rpcfg->stii, p_ri ); + + if ( mbg_rc_is_error( rc ) ) + goto out; } else { - if ( _pcps_is_gps( pdev ) ) + // The device doesn't support a RECEIVER_INFO, so this is + // an old GPS or non-GPS device. + + if ( _pcps_is_gps( p_dev ) ) { - rc = mbg_get_gps_port_parm( dh, &pcfg->tmp_pp ); - if ( rc != MBG_SUCCESS ) - goto error; + // Read the serial port configuration from an old GPS device using + // a legacy API call and set up current structures accordingly. - for ( i = 0; i < p_ri->n_com_ports; i++ ) - { - PORT_INFO_IDX *p_pii = &pcfg->pii[i]; - PORT_INFO *p_pi = &p_pii->port_info; + rc = mbg_get_gps_port_parm( dh, &p_rpcfg->tmp_pp ); - p_pii->idx = i; - port_settings_from_port_parm( &p_pi->port_settings, - i, &pcfg->tmp_pp, 1 ); + if ( mbg_rc_is_error( rc ) ) + goto out; - p_pi->supp_baud_rates = DEFAULT_GPS_BAUD_RATES_C166; - p_pi->supp_framings = DEFAULT_GPS_FRAMINGS_C166; - p_pi->supp_str_types = DEFAULT_SUPP_STR_TYPES_GPS; - } + rc = setup_port_info_from_port_parm( p_rpcfg->pii, &p_rpcfg->tmp_pp, p_ri ); + + if ( mbg_rc_is_error( rc ) ) + goto out; + + // Also set up default string type information. + rc = setup_default_str_type_info_idx( p_rpcfg->stii, p_ri ); } else - if ( _pcps_has_serial ( pdev ) ) // Not all non-GPS clocks have a serial port! + { + // Not all legacy non-GPS clocks have a serial port. + if ( _pcps_has_serial( p_dev ) ) { + // Read the serial port configuration from an old non-GPS device using + // a legacy API call and set up current structures accordingly. + PCPS_SERIAL ser_code; rc = mbg_get_serial( dh, &ser_code ); - if ( rc != MBG_SUCCESS ) - goto error; + if ( mbg_rc_is_error( rc ) ) + goto out; - port_info_from_pcps_serial( pcfg->pii, ser_code, - _pcps_has_serial_hs( pdev ) ? + port_info_from_pcps_serial( p_rpcfg->pii, ser_code, + _pcps_has_serial_hs( p_dev ) ? DEFAULT_BAUD_RATES_DCF_HS : DEFAULT_BAUD_RATES_DCF ); + // Also set up default string type information. + rc = setup_default_str_type_info_idx( p_rpcfg->stii, p_ri ); } - - for ( i = 0; i < p_ri->n_str_type; i++ ) - { - STR_TYPE_INFO_IDX *stip = &pcfg->stii[i]; - stip->idx = i; - stip->str_type_info = default_str_type_info[i]; } - } - return MBG_SUCCESS; + } + rc = MBG_SUCCESS; -error: +out: return rc; } // mbg_get_serial_settings @@ -151,53 +326,62 @@ error: /*HDR*/ /** - Write the configuration settings for a single serial port to the board. - - Modifications to the serial port configuration should be made only - after mbg_get_serial_settings() had been called to read all serial port - settings and supported configuration parameters. - This function has finally to be called once for every serial port - the configuration of which has been modified. - - 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 - must be passed to this function. - - @param dh Valid handle to a Meinberg device - @param *pdev Pointer to a ::PCPS_DEV structure - @param *pcfg Pointer to a ::RECEIVER_PORT_CFG structure - @param port_num Index of the ::serial port to be saved - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_serial_settings() - @see mbg_get_device_info() - @see mbg_setup_receiver_info() -*/ -int mbg_save_serial_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, - RECEIVER_PORT_CFG *pcfg, int port_num ) + * @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 + * settings and supported configuration parameters. + * This function has finally to be called once for every serial port + * the configuration of which has been modified. + * + * 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. + * + * @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 + * + * @return ::MBG_SUCCESS or error code returned by device I/O control function. + * + * @see ::mbg_get_serial_settings + * @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 rc; - if ( _pcps_has_receiver_info( pdev ) ) + if ( _pcps_has_receiver_info( p_dev ) ) { - rc = mbg_set_gps_port_settings( dh, &pcfg->pii[port_num].port_info.port_settings, port_num ); + // The device provides a ::RECEIVER_INFO, so we can simply write + // the configuration for the specified serial port directly. + rc = mbg_set_gps_port_settings( dh, &p_rpcfg->pii[port_num].port_info.port_settings, port_num ); } else { - if ( _pcps_is_gps( pdev ) ) + // This is a legacy device which doesn't provide a ::RECEIVER_INFO. + if ( _pcps_is_gps( p_dev ) ) { - port_parm_from_port_settings( &pcfg->tmp_pp, port_num, - &pcfg->pii[port_num].port_info.port_settings, 1 ); + // 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, + &p_rpcfg->pii[port_num].port_info.port_settings, 1 ); - rc = mbg_set_gps_port_parm( dh, &pcfg->tmp_pp ); + rc = mbg_set_gps_port_parm( dh, &p_rpcfg->tmp_pp ); } else { + // 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; - pcps_serial_from_port_info( &ser_code, pcfg->pii ); + pcps_serial_from_port_info( &ser_code, p_rpcfg->pii ); rc = mbg_set_serial( dh, &ser_code ); } @@ -211,23 +395,477 @@ int mbg_save_serial_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, /*HDR*/ /** - Read all PTP settings and supported configuration parameters. + * @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, + * ::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 + * + * @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 + * + * @see ::mbg_chk_dev_has_lan_intf + * @see ::mbg_get_lan_if_info + * @see ::mbg_get_ip4_settings + * @see ::free_all_net_cfg_info + */ +int mbg_get_all_net_cfg_info( MBG_DEV_HANDLE dh, ALL_NET_CFG_INFO **p ) +{ + ALL_NET_CFG_INFO *net_cfg_info = *p; + int rc; + + if ( net_cfg_info == NULL ) + { + net_cfg_info = ( ALL_NET_CFG_INFO * )calloc( 1, sizeof( *net_cfg_info ) ); + if ( net_cfg_info == NULL ) + { + rc = MBG_ERR_NO_MEM; + goto out; + } + } + + // TODO Use NET_CFG API as soon as its available for PCI/PCIe devices + rc = mbg_chk_dev_has_lan_intf( dh ); + + if ( mbg_rc_is_success( rc ) ) + { + LAN_IF_INFO lan_if_info; + IP4_SETTINGS ip4_settings; + + if ( net_cfg_info->glb_cfg_info.n_supp_intf_link != 0 ) + goto out; + + rc = mbg_get_lan_if_info( dh, &lan_if_info ); - The complementary function mbg_save_all_ptp_cfg_info() should - be used to write the modified configuration back to the device. + if ( mbg_rc_is_error( rc ) ) + goto out; + + if ( net_cfg_info->link_infos == NULL ) + { + net_cfg_info->link_infos = ( MBG_NET_INTF_LINK_INFO_IDX * )calloc( 1, sizeof( *net_cfg_info->link_infos ) ); + if ( net_cfg_info->link_infos == NULL ) + { + rc = MBG_ERR_NO_MEM; + goto out; + } + } + + net_cfg_info->glb_cfg_info.glb_settings.num_intf_link = 1; + + memset( &net_cfg_info->link_infos[0], 0, sizeof( net_cfg_info->link_infos[0] ) ); + + net_cfg_info->link_infos[0].info.supp_states = MBG_NET_INTF_LINK_STATE_MASK_UP; + net_cfg_info->link_infos[0].info.supp_types = MBG_NET_INTF_LINK_TYPE_MASK_PHYS | MBG_NET_INTF_LINK_TYPE_MASK_VLAN; + net_cfg_info->link_infos[0].info.supp_speed_modes = MBG_NET_INTF_LINK_SPEED_MODE_MASK_10_T_HALF | MBG_NET_INTF_LINK_SPEED_MODE_MASK_10_T_FULL | MBG_NET_INTF_LINK_SPEED_MODE_MASK_100_T_HALF | MBG_NET_INTF_LINK_SPEED_MODE_MASK_100_T_FULL; + net_cfg_info->link_infos[0].info.supp_port_types = MBG_NET_INTF_LINK_PORT_TYPE_MASK_TP; + + snprintf_safe( net_cfg_info->link_infos[0].info.link_settings.name, sizeof( net_cfg_info->link_infos[0].info.link_settings.name ), "lan0" ); + net_cfg_info->link_infos[0].info.link_settings.mac_addr = lan_if_info.mac_addr; + net_cfg_info->link_infos[0].info.link_settings.if_index = 0; + net_cfg_info->link_infos[0].info.link_settings.type = MBG_NET_INTF_LINK_TYPE_PHYS; + net_cfg_info->link_infos[0].info.link_settings.port_type = MBG_NET_INTF_LINK_PORT_TYPE_TP; + + if ( net_cfg_info->glb_cfg_info.n_supp_intf_addr != 0 ) + goto out; + + rc = mbg_get_ip4_settings( dh, &ip4_settings ); + + if ( mbg_rc_is_error( rc ) ) + goto out; + + if( ip4_settings.flags & IP4_MSK_LINK ) + { + net_cfg_info->link_infos->info.link_settings.states |= MBG_NET_INTF_LINK_STATE_MASK_UP; + net_cfg_info->link_infos->info.link_settings.states |= MBG_NET_INTF_LINK_STATE_MASK_LOWER_UP; + } + + if ( net_cfg_info->addr_infos == NULL ) + { + net_cfg_info->addr_infos = ( MBG_NET_INTF_ADDR_INFO_IDX * )calloc( 1, sizeof( *net_cfg_info->addr_infos ) ); + if ( net_cfg_info->addr_infos == NULL ) + { + rc = MBG_ERR_NO_MEM; + goto out; + } + } + + net_cfg_info->glb_cfg_info.glb_settings.num_intf_addr = 1; + + memset( &net_cfg_info->addr_infos[0], 0, sizeof( net_cfg_info->addr_infos[0] ) ); + + net_cfg_info->addr_infos[0].info.supp_flags = MBG_NET_INTF_ADDR_MASK_DHCP4; + + snprintf_safe( net_cfg_info->addr_infos[0].info.addr_settings.label, sizeof( net_cfg_info->addr_infos[0].info.addr_settings.label ), "lan0:0" ); + + if ( ip4_settings.flags & IP4_MSK_VLAN ) + { + net_cfg_info->link_infos = ( MBG_NET_INTF_LINK_INFO_IDX * )realloc( net_cfg_info->link_infos, 2 * sizeof( *net_cfg_info->link_infos ) ); + if ( net_cfg_info->link_infos == NULL ) + { + rc = MBG_ERR_NO_MEM; + goto out; + } + + net_cfg_info->glb_cfg_info.glb_settings.num_intf_link = 2; + + memset(&net_cfg_info->link_infos[1], 0, sizeof(net_cfg_info->link_infos[1])); + + net_cfg_info->link_infos[1].idx = 1; + net_cfg_info->link_infos[1].info.supp_states = MBG_NET_INTF_LINK_STATE_MASK_UP; + net_cfg_info->link_infos[1].info.supp_types = MBG_NET_INTF_LINK_TYPE_MASK_VLAN; + net_cfg_info->link_infos[1].info.supp_speed_modes = MBG_NET_INTF_LINK_SPEED_MODE_MASK_10_T_HALF | MBG_NET_INTF_LINK_SPEED_MODE_MASK_10_T_FULL | MBG_NET_INTF_LINK_SPEED_MODE_MASK_100_T_HALF | MBG_NET_INTF_LINK_SPEED_MODE_MASK_100_T_FULL; + net_cfg_info->link_infos[1].info.supp_port_types = MBG_NET_INTF_LINK_PORT_TYPE_MASK_TP; + + snprintf_safe( net_cfg_info->link_infos[1].info.link_settings.name, sizeof( net_cfg_info->link_infos[1].info.link_settings.name ), "vlan0" ); + net_cfg_info->link_infos[1].info.link_settings.mac_addr = net_cfg_info->link_infos[0].info.link_settings.mac_addr; + net_cfg_info->link_infos[1].info.link_settings.if_index = 1; + net_cfg_info->link_infos[1].info.link_settings.ass_if_index = 0; + net_cfg_info->link_infos[1].info.link_settings.states = net_cfg_info->link_infos[0].info.link_settings.states; + net_cfg_info->link_infos[1].info.link_settings.type = MBG_NET_INTF_LINK_TYPE_VLAN; + net_cfg_info->link_infos[1].info.link_settings.vlan_cfg = ip4_settings.vlan_cfg; + + net_cfg_info->addr_infos[0].info.addr_settings.ass_if_index = 1; + } + + if ( ip4_settings.flags & IP4_MSK_DHCP ) + net_cfg_info->addr_infos[0].info.addr_settings.flags |= MBG_NET_INTF_ADDR_MASK_DHCP4; + + net_cfg_info->addr_infos[0].info.addr_settings.ip.type = MBG_IP_ADDR_TYPE_IP4; + net_cfg_info->addr_infos[0].info.addr_settings.ip.u_addr.ip4_addr = ip4_settings.ip_addr; + + net_cfg_info->addr_infos[0].info.addr_settings.broadcast.type = MBG_IP_ADDR_TYPE_IP4; + net_cfg_info->addr_infos[0].info.addr_settings.broadcast.u_addr.ip4_addr = ip4_settings.broad_addr; + + net_cfg_info->addr_infos[0].info.addr_settings.prefix_bits = get_ip4_net_mask_bits(&ip4_settings.netmask); + + if ( net_cfg_info->glb_cfg_info.n_supp_intf_route == 0 ) + { + if ( net_cfg_info->route_infos == NULL ) + { + net_cfg_info->route_infos = ( MBG_NET_INTF_ROUTE_INFO_IDX * )calloc( 1, sizeof( *net_cfg_info->route_infos ) ); + if ( net_cfg_info->route_infos == NULL ) + { + rc = MBG_ERR_NO_MEM; + goto out; + } + } + + net_cfg_info->glb_cfg_info.glb_settings.num_intf_route = 1; + + memset( &net_cfg_info->route_infos[0], 0, sizeof( net_cfg_info->route_infos[0] ) ); + + net_cfg_info->route_infos[0].info.route_settings.type = MBG_NET_INTF_ROUTE_TYPE_DEFAULT_GATEWAY; + net_cfg_info->route_infos[0].info.route_settings.gateway.type = MBG_IP_ADDR_TYPE_IP4; + net_cfg_info->route_infos[0].info.route_settings.gateway.u_addr.ip4_addr = ip4_settings.gateway; + if ( ip4_settings.gateway != 0 ) + { + if(net_cfg_info->glb_cfg_info.glb_settings.num_intf_link == 2) + net_cfg_info->route_infos[0].info.route_settings.ass_if_index = 1; + } + else net_cfg_info->route_infos[0].info.route_settings.ass_if_index = (uint32_t)-1; + + } + + } + +out: + if ( mbg_rc_is_error( rc ) ) + { + free_all_net_cfg_info( net_cfg_info ); + net_cfg_info = NULL; + } + + *p = net_cfg_info; + + return rc; - @param dh Valid handle to a Meinberg device. - @param *p Pointer to a ::ALL_PTP_CFG_INFO structure. +} // mbg_get_all_net_cfg_info - @return ::MBG_SUCCESS or error code returned by device I/O control function. - @see mbg_save_all_ptp_cfg_info() - @see mbg_get_ptp_cfg_info() - @see mbg_get_ptp_uc_master_cfg_limits() - @see mbg_get_all_ptp_uc_master_info() - @see mbg_dev_has_ptp() - @see mbg_dev_has_ptp_unicast() -*/ + +/*HDR*/ +/** + * @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 + * supported configuration parameters. + * + * The appropriate settings are translated into LAN_IP4 structures + * and send to the device using the appropriate API functions. + * + * 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 + * + * @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 + int rc = mbg_chk_dev_has_lan_intf( dh ); + + if ( mbg_rc_is_success( rc ) ) + { + IP4_SETTINGS ip4_settings; + memset( &ip4_settings, 0, sizeof( ip4_settings ) ); + + if ( p->addr_infos[0].info.addr_settings.ip.type == MBG_IP_ADDR_TYPE_IP4 ) + ip4_settings.ip_addr = p->addr_infos[0].info.addr_settings.ip.u_addr.ip4_addr; + + ip4_settings.netmask = ip4_net_mask_from_cidr( p->addr_infos[0].info.addr_settings.prefix_bits ); + ip4_settings.broad_addr = ip4_broad_addr_from_addr( &ip4_settings.ip_addr, &ip4_settings.netmask ); + + if ( p->route_infos[0].info.route_settings.gateway.type == MBG_IP_ADDR_TYPE_IP4 ) + ip4_settings.gateway = p->route_infos[0].info.route_settings.gateway.u_addr.ip4_addr; + + if ( ( p->glb_cfg_info.glb_settings.num_intf_link > 1 ) && ( p->addr_infos[0].info.addr_settings.ass_if_index == 1 ) ) + { + ip4_settings.flags |= IP4_MSK_VLAN; + ip4_settings.vlan_cfg = p->link_infos[1].info.link_settings.vlan_cfg; + } + + if ( ( p->addr_infos[0].info.addr_settings.flags & MBG_NET_INTF_ADDR_MASK_DHCP4 ) == MBG_NET_INTF_ADDR_MASK_DHCP4 ) + ip4_settings.flags |= IP4_MSK_DHCP; + + rc = mbg_set_ip4_settings( dh, &ip4_settings ); + } + + return rc; + +} // mbg_save_all_net_cfg_info + + + +/*HDR*/ +/** + * @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, + * ::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 + * + * @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 + * + * @see ::mbg_chk_dev_has_lan_intf + * @see ::mbg_get_lan_if_info + * @see ::mbg_get_ip4_state + * @see ::free_all_net_status_info + */ +int mbg_get_all_net_status_info( MBG_DEV_HANDLE dh, ALL_NET_STATUS_INFO **p ) +{ + ALL_NET_STATUS_INFO *net_status_info = *p; + int rc; + + if ( net_status_info == NULL ) + { + net_status_info = ( ALL_NET_STATUS_INFO * )calloc( 1, sizeof( *net_status_info ) ); + if ( net_status_info == NULL ) + { + rc = MBG_ERR_NO_MEM; + goto out; + } + } + + // TODO Use NET_CFG API as soon as its available for PCI/PCIe devices + rc = mbg_chk_dev_has_lan_intf( dh ); + + if ( mbg_rc_is_success( rc ) ) + { + LAN_IF_INFO lan_if_info; + IP4_SETTINGS ip4_state; + + if ( net_status_info->glb_cfg_info.n_supp_intf_link != 0 ) + goto out; + + rc = mbg_get_lan_if_info( dh, &lan_if_info ); + + if ( mbg_rc_is_error( rc ) ) + goto out; + + if ( net_status_info->link_infos == NULL ) + { + net_status_info->link_infos = ( MBG_NET_INTF_LINK_INFO_IDX * )calloc( 1, sizeof( *net_status_info->link_infos ) ); + if ( net_status_info->link_infos == NULL ) + { + rc = MBG_ERR_NO_MEM; + goto out; + } + } + + net_status_info->glb_cfg_info.glb_settings.num_intf_addr = 1; + + memset( &net_status_info->link_infos[0], 0, sizeof( net_status_info->link_infos[0] ) ); + + net_status_info->link_infos[0].info.supp_states = MBG_NET_INTF_LINK_STATE_MASK_UP; + net_status_info->link_infos[0].info.supp_types = MBG_NET_INTF_LINK_TYPE_MASK_PHYS | MBG_NET_INTF_LINK_TYPE_MASK_VLAN; + net_status_info->link_infos[0].info.supp_speed_modes = MBG_NET_INTF_LINK_SPEED_MODE_MASK_10_T_HALF | MBG_NET_INTF_LINK_SPEED_MODE_MASK_10_T_FULL | MBG_NET_INTF_LINK_SPEED_MODE_MASK_100_T_HALF | MBG_NET_INTF_LINK_SPEED_MODE_MASK_100_T_FULL; + net_status_info->link_infos[0].info.supp_port_types = MBG_NET_INTF_LINK_PORT_TYPE_MASK_TP; + + snprintf_safe( net_status_info->link_infos[0].info.link_settings.name, sizeof( net_status_info->link_infos[0].info.link_settings.name ), "lan0" ); + net_status_info->link_infos[0].info.link_settings.mac_addr = lan_if_info.mac_addr; + net_status_info->link_infos[0].info.link_settings.if_index = 0; + net_status_info->link_infos[0].info.link_settings.type = MBG_NET_INTF_LINK_TYPE_PHYS; + net_status_info->link_infos[0].info.link_settings.port_type = MBG_NET_INTF_LINK_PORT_TYPE_TP; + + if ( net_status_info->glb_cfg_info.n_supp_intf_addr != 0 ) + goto out; + + rc = mbg_get_ip4_state( dh, &ip4_state ); + + if ( mbg_rc_is_error( rc ) ) + goto out; + + if( ip4_state.flags & IP4_MSK_LINK ) + { + net_status_info->link_infos[0].info.link_settings.states |= MBG_NET_INTF_LINK_STATE_MASK_UP; + net_status_info->link_infos[0].info.link_settings.states |= MBG_NET_INTF_LINK_STATE_MASK_LOWER_UP; + } + + if ( net_status_info->addr_infos == NULL ) + { + net_status_info->addr_infos = ( MBG_NET_INTF_ADDR_INFO_IDX * )realloc( net_status_info->addr_infos, sizeof( *net_status_info->addr_infos ) ); + if ( net_status_info->addr_infos == NULL ) + { + rc = MBG_ERR_NO_MEM; + goto out; + } + } + + net_status_info->glb_cfg_info.glb_settings.num_intf_addr = 1; + + memset( &net_status_info->addr_infos[0], 0, sizeof( net_status_info->addr_infos[0] ) ); + + net_status_info->addr_infos[0].info.supp_flags = MBG_NET_INTF_ADDR_MASK_DHCP4; + + snprintf_safe( net_status_info->addr_infos[0].info.addr_settings.label, sizeof( net_status_info->addr_infos[0].info.addr_settings.label ), "lan0:0" ); + + if ( ip4_state.flags & IP4_MSK_VLAN ) + { + net_status_info->link_infos = ( MBG_NET_INTF_LINK_INFO_IDX * )realloc( net_status_info->link_infos, 2 * sizeof( *net_status_info->link_infos ) ); + if ( net_status_info->link_infos == NULL ) + { + rc = MBG_ERR_NO_MEM; + goto out; + } + + net_status_info->glb_cfg_info.glb_settings.num_intf_link = 2; + + memset(&net_status_info->link_infos[1], 0, sizeof(net_status_info->link_infos[1])); + + net_status_info->link_infos[1].idx = 1; + net_status_info->link_infos[1].info.supp_states = MBG_NET_INTF_LINK_STATE_MASK_UP; + net_status_info->link_infos[1].info.supp_types = MBG_NET_INTF_LINK_TYPE_MASK_VLAN; + net_status_info->link_infos[1].info.supp_speed_modes = MBG_NET_INTF_LINK_SPEED_MODE_MASK_10_T_HALF | MBG_NET_INTF_LINK_SPEED_MODE_MASK_10_T_FULL | MBG_NET_INTF_LINK_SPEED_MODE_MASK_100_T_HALF | MBG_NET_INTF_LINK_SPEED_MODE_MASK_100_T_FULL; + net_status_info->link_infos[1].info.supp_port_types = MBG_NET_INTF_LINK_PORT_TYPE_MASK_TP; + + snprintf_safe( net_status_info->link_infos[1].info.link_settings.name, sizeof( net_status_info->link_infos[1].info.link_settings.name ), "vlan0" ); + net_status_info->link_infos[1].info.link_settings.mac_addr = net_status_info->link_infos[0].info.link_settings.mac_addr; + net_status_info->link_infos[1].info.link_settings.if_index = 1; + net_status_info->link_infos[1].info.link_settings.ass_if_index = 0; + net_status_info->link_infos[1].info.link_settings.states = net_status_info->link_infos[0].info.link_settings.states; + net_status_info->link_infos[1].info.link_settings.type = MBG_NET_INTF_LINK_TYPE_VLAN; + net_status_info->link_infos[1].info.link_settings.vlan_cfg = ip4_state.vlan_cfg; + + net_status_info->addr_infos[0].info.addr_settings.ass_if_index = 1; + } + + if ( ip4_state.flags & IP4_MSK_DHCP ) + net_status_info->addr_infos[0].info.addr_settings.flags |= MBG_NET_INTF_ADDR_MASK_DHCP4; + + net_status_info->addr_infos[0].info.addr_settings.ip.type = MBG_IP_ADDR_TYPE_IP4; + net_status_info->addr_infos[0].info.addr_settings.ip.u_addr.ip4_addr = ip4_state.ip_addr; + + net_status_info->addr_infos[0].info.addr_settings.broadcast.type = MBG_IP_ADDR_TYPE_IP4; + net_status_info->addr_infos[0].info.addr_settings.broadcast.u_addr.ip4_addr = ip4_state.broad_addr; + + net_status_info->addr_infos[0].info.addr_settings.prefix_bits = get_ip4_net_mask_bits(&ip4_state.netmask); + + if ( net_status_info->glb_cfg_info.n_supp_intf_route == 0 ) + { + if ( net_status_info->route_infos == NULL ) + { + net_status_info->route_infos = ( MBG_NET_INTF_ROUTE_INFO_IDX * )calloc( 1, sizeof( *net_status_info->route_infos ) ); + if ( net_status_info->route_infos == NULL ) + { + rc = MBG_ERR_NO_MEM; + goto out; + } + } + + net_status_info->glb_cfg_info.glb_settings.num_intf_route = 1; + + memset( &net_status_info->route_infos[0], 0, sizeof( net_status_info->route_infos[0] ) ); + + net_status_info->route_infos[0].info.route_settings.type = MBG_NET_INTF_ROUTE_TYPE_DEFAULT_GATEWAY; + net_status_info->route_infos[0].info.route_settings.gateway.type = MBG_IP_ADDR_TYPE_IP4; + net_status_info->route_infos[0].info.route_settings.gateway.u_addr.ip4_addr = ip4_state.gateway; + if ( ip4_state.gateway != 0 ) + { + if(net_status_info->glb_cfg_info.glb_settings.num_intf_link == 2) + net_status_info->route_infos[0].info.route_settings.ass_if_index = 1; + } + else net_status_info->route_infos[0].info.route_settings.ass_if_index = (uint32_t)-1; + + } + + } + +out: + if ( mbg_rc_is_error( rc ) ) + { + free_all_net_status_info( net_status_info ); + net_status_info = NULL; + } + + *p = net_status_info; + + return rc; + +} // mbg_get_all_net_status_info + + + +/*HDR*/ +/** + * @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 + * + * @return ::MBG_SUCCESS or error code returned by device I/O control function. + * + * @see ::mbg_save_all_ptp_cfg_info + * @see ::mbg_get_ptp_cfg_info + * @see ::mbg_get_ptp_uc_master_cfg_limits + * @see ::mbg_get_all_ptp_uc_master_info + * @see ::mbg_chk_dev_has_ptp + * @see ::mbg_chk_dev_has_ptp_unicast + */ int mbg_get_all_ptp_cfg_info( MBG_DEV_HANDLE dh, ALL_PTP_CFG_INFO *p ) { int rc = MBG_SUCCESS; @@ -267,24 +905,23 @@ int mbg_get_all_ptp_cfg_info( MBG_DEV_HANDLE dh, ALL_PTP_CFG_INFO *p ) /*HDR*/ /** - Write all PTP settings and supported configuration parameters - 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 dh Valid handle to a Meinberg device. - @param *p Pointer to a ::ALL_PTP_CFG_INFO structure. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_all_ptp_cfg_info() - @see mbg_set_ptp_cfg_settings() - @see mbg_set_ptp_uc_master_settings_idx() - @see mbg_dev_has_ptp() - @see mbg_dev_has_ptp_unicast() -*/ + * @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 + * + * @return ::MBG_SUCCESS or error code returned by device I/O control function. + * + * @see ::mbg_get_all_ptp_cfg_info + * @see ::mbg_set_ptp_cfg_settings + * @see ::mbg_set_ptp_uc_master_settings_idx + * @see ::mbg_chk_dev_has_ptp + * @see ::mbg_chk_dev_has_ptp_unicast + */ int mbg_save_all_ptp_cfg_info( MBG_DEV_HANDLE dh, const ALL_PTP_CFG_INFO *p ) { int rc = MBG_SUCCESS; @@ -320,3 +957,780 @@ int mbg_save_all_ptp_cfg_info( MBG_DEV_HANDLE dh, const ALL_PTP_CFG_INFO *p ) } // mbg_save_all_ptp_cfg_info + +/*HDR*/ +/** + * @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 + * + * A ::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 + * + * @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 + * + * @see ::free_all_xmulti_ref_info + */ +int mbg_get_all_xmulti_ref_info( MBG_DEV_HANDLE dh, ALL_XMULTI_REF_INFO **p ) +{ + ALL_XMULTI_REF_INFO *xmr_info = *p; + int rc; + + if ( xmr_info == NULL ) + { + xmr_info = ( ALL_XMULTI_REF_INFO * )calloc( 1, sizeof( *xmr_info ) ); + if ( xmr_info == NULL ) + { + rc = MBG_ERR_NO_MEM; + goto out; + } + } + + // 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 ) ) + goto out; + + if ( xmr_info->infos == NULL ) + { + xmr_info->infos = ( XMULTI_REF_INFO_IDX * )calloc( xmr_info->instances.n_xmr_settings, sizeof( *xmr_info->infos ) ); + if ( xmr_info->infos == NULL ) + { + rc = MBG_ERR_NO_MEM; + goto out; + } + } + + rc = mbg_get_gps_all_xmr_info( dh, xmr_info->infos, &xmr_info->instances ); + + if ( mbg_rc_is_error( rc ) ) + goto out; + + 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 + // Has to be changed as soon as low level functions are ready + // TODO!!! + xmr_info->instances.flags &= ~XMRIF_MSK_EXT_SRC_INFO_SUPP; + } + +out: + if ( mbg_rc_is_error( rc ) ) + { + free_all_xmulti_ref_info( xmr_info ); + xmr_info = NULL; + } + + *p = xmr_info; + + return rc; + +} // mbg_get_all_xmulti_ref_info + + +/*HDR*/ +/** + * @brief Set 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 + * + * @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 ) +{ + int rc = MBG_SUCCESS, i; + XMULTI_REF_SETTINGS_IDX settings; + + for (i = 0; ( i < p->instances.n_xmr_settings ) && mbg_rc_is_success( rc ); i++ ) + { + settings.idx = i; + memcpy( &settings.settings, &p->infos[i].info.settings, sizeof( settings.settings ) ); + 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 + if( mbg_rc_is_success( rc ) ) + { + memset( &settings, 0, sizeof( settings ) ); + settings.idx = -1; + settings.settings.id.type = MULTI_REF_NONE; + rc = mbg_set_gps_xmr_settings_idx( dh, &settings ); + } + + return rc; + +} // mbg_save_all_xmulti_ref_info + + +/*HDR*/ +/** + * @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 + * + * A ::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 + * + * @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 + * + * @see ::free_all_xmulti_ref_status + */ +int mbg_get_all_xmulti_ref_status( MBG_DEV_HANDLE dh, const ALL_XMULTI_REF_INFO *info, ALL_XMULTI_REF_STATUS **p ) +{ + ALL_XMULTI_REF_STATUS *xmr_status = *p; + int rc; + + if ( info == NULL ) + return MBG_ERR_INV_PARM; + + if ( xmr_status == NULL ) + { + xmr_status = ( ALL_XMULTI_REF_STATUS * )calloc( 1, sizeof( *xmr_status ) ); + if ( xmr_status == NULL ) + { + rc = MBG_ERR_NO_MEM; + goto out; + } + } + + if ( xmr_status->status == NULL ) + { + xmr_status->status = ( XMULTI_REF_STATUS_IDX* )calloc( info->instances.n_xmr_settings, sizeof( *xmr_status->status ) ); + + if ( xmr_status->status == NULL ) + { + rc = MBG_ERR_NO_MEM; + goto out; + } + } + + rc = mbg_get_gps_all_xmr_status( dh, xmr_status->status, &info->instances ); + + if ( mbg_rc_is_error( rc ) ) + goto out; + + 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 + } + +out: + if ( mbg_rc_is_error( rc ) ) + { + free_all_xmulti_ref_status( xmr_status ); + xmr_status = NULL; + } + + *p = xmr_status; + + return rc; + +} // mbg_get_all_xmulti_ref_status + + + +/*HDR*/ +/** + * @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. + * + * The appropriate number of ::TTM structures will be allocated and needs to be freed + * 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 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbg_chk_dev_has_ucap + * @see ::free_all_ucap_info + */ +int mbg_get_all_ucap_info( MBG_DEV_HANDLE dh, ALL_UCAP_INFO **p ) +{ + int rc; + 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 ( ucap_info == NULL ) + { + ucap_info = ( ALL_UCAP_INFO* )calloc( 1, sizeof( *ucap_info ) ); + if ( ucap_info == NULL ) + { + *p = NULL; + return MBG_ERR_NO_MEM; + } + mbg_klist_init(&ucap_info->list); + } + + do + { + new_entry = calloc_ucap_entry(); + if ( !new_entry ) + { + rc = MBG_ERR_NO_MEM; + goto err_out; + } + + rc = mbg_get_gps_ucap( dh, &new_entry->ttm ); + if ( mbg_rc_is_error( rc ) ) + goto err_out; + + if ( ( (uint8_t)new_entry->ttm.tm.sec == (uint8_t) 0xFF ) ) + { + free ( new_entry ); + new_entry = NULL; + break; + } + + if ( ucap_info->num_ucaps < MAX_UCAP_ENTRIES ) + { + mbg_klist_append_item(&ucap_info->list, &new_entry->head); + ++ucap_info->num_ucaps; + } + else + { + old_entry = mbg_klist_first_entry(&ucap_info->list, UCAP_ENTRY, head); + mbg_klist_delete_item(&old_entry->head); + free(old_entry); + mbg_klist_append_item(&ucap_info->list, &new_entry->head); + } + + } while (1); + + rc = MBG_SUCCESS; + + goto success_out; + +err_out: + free_all_ucap_info( ucap_info ); + ucap_info = NULL; + if ( new_entry ) + free( new_entry ); + +success_out: + *p = ucap_info; + + return rc; + +} // mbg_get_all_ucap_info + + + +#if 0 && defined( DEBUG ) // ### TODO + +/*HDR*/ +void test_gpio( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int verbose ) +{ + int b; + int rc; + unsigned int i; + MBG_GPIO_CFG_LIMITS gpio_cfg_limits = { 0 }; + ALL_GPIO_INFO_IDX all_gpio_info_idx = { { 0 } }; + ALL_GPIO_STATUS_IDX all_gpio_status_idx = { { 0 } }; + + rc = mbg_chk_dev_has_gpio( dh ); + + printf( "\nGPIO chk supp: %i\n", rc ); + + rc = mbg_dev_has_gpio( dh, &b ); + + if ( rc != MBG_SUCCESS || !b ) + { + printf( "GPIO not supported, rc: %i, b: %i\n", rc, b ); + return; + } + + printf( "GPIO supported, rc: %i, b: %i\n", rc, b ); + + printf( "\nChecking GPIO:\n" ); + + rc = mbg_get_gpio_cfg_limits( dh, &gpio_cfg_limits ); + + if ( rc != MBG_SUCCESS ) + { + printf( "Failed to read GPIO limits, rc: %i\n", rc ); + return; + } + + printf( "Number of GPIO ports: %i\n", gpio_cfg_limits.num_io ); + + rc = mbg_get_gps_all_gpio_info( dh, all_gpio_info_idx, &gpio_cfg_limits ); + + if ( rc != MBG_SUCCESS ) + printf( "Failed to read all GPIO info, rc: %i\n", rc ); + + if ( !( gpio_cfg_limits.flags & MBG_GPIO_CFG_LIMIT_FLAG_MASK_STATUS_SUPP ) ) + printf( "GPIO status not supported (flag not set).\n" ); + else + { + rc = mbg_get_gps_all_gpio_status( dh, all_gpio_status_idx, &gpio_cfg_limits ); + + if ( rc != MBG_SUCCESS ) + printf( "Failed to read all GPIO status, rc: %i\n", rc ); + } + + + for ( i = 0; i < gpio_cfg_limits.num_io; i++ ) + { + MBG_GPIO_INFO *p_i = &all_gpio_info_idx[i].info; + MBG_GPIO_STATUS *p_st = &all_gpio_status_idx[i].status; + int gpio_type = p_i->settings.type; + + printf( "GPIO %i: type 0x%02X (%s)", i, + gpio_type, _get_gpio_type_name( gpio_type ) ); + + switch ( gpio_type ) + { + case MBG_GPIO_TYPE_FREQ_IN: // variable frequency input, freq == 0 if input not used + { + MBG_GPIO_FREQ_IN_SETTINGS *p = &p_i->settings.u.freq_in; +#if 0 + MBG_GPIO_FREQ freq; ///< frequency in range ::MBG_GPIO_FREQ_IN_SUPP::freq_min..::MBG_GPIO_FREQ_IN_SUPP::freq_max, or 0 if input is not used + uint32_t csc_limit; ///< max. cycle slip [1/1000 cycle units], see ::MBG_GPIO_FREQ_IN_SUPP::csc_limit_max + uint32_t shape; ///< selected signal shape, see ::MBG_GPIO_SIGNAL_SHAPES + uint32_t reserved; ///< reserved, currently always 0 + uint32_t flags; ///< reserved, currently always 0 +#endif + + } break; + + case MBG_GPIO_TYPE_FREQ_OUT: // variable frequency output + { + MBG_GPIO_FREQ_OUT_SETTINGS *p = &p_i->settings.u.freq_out; + + printf( " %lu.%lu Hz %s, phase %li.%03li deg", + (ulong) p->freq.hz, (ulong) p->freq.frac, + _get_gpio_signal_shape_name( p->shape ), + (long) p->milli_phase / 1000, + labs( (long) p->milli_phase % 1000 ) ); + + } break; + + case MBG_GPIO_TYPE_FIXED_FREQ_OUT: // fixed frequency output + { + MBG_GPIO_FIXED_FREQ_OUT_SETTINGS *p = &p_i->settings.u.ff_out; + +#if 0 +typedef struct +{ + uint32_t freq_idx; ///< fixed frequency index, see ::MBG_GPIO_FIXED_FREQS + uint32_t shape; ///< selected signal shape, see ::MBG_GPIO_SIGNAL_SHAPES + uint32_t reserved; ///< reserved, currently always 0 + uint32_t flags; ///< reserved, currently always 0 + +} MBG_GPIO_FIXED_FREQ_OUT_SETTINGS; +#endif + + printf( " %s %s", _get_gpio_fixed_freq_str( p->freq_idx ), + _get_gpio_signal_shape_name( p->shape ) ); + + } break; + + case MBG_GPIO_TYPE_BITS_IN: // framed data stream input + break; + + case MBG_GPIO_TYPE_BITS_OUT: // framed data stream output + break; + } + + printf( ", status 0x%02X (%s)", + p_st->port_state, _get_gpio_port_state_name( p_st->port_state ) ); + + printf( "\n" ); + } + +#if 0 + rc = mbg_set_gps_gpio_settings_idx( dh, MBG_GPIO_SETTINGS_IDX *p ) +#endif + +} // test_gpio + + + +/*HDR*/ +void test_xmr( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int verbose ) +{ + static const char *multi_ref_names[N_MULTI_REF] = DEFAULT_MULTI_REF_NAMES; + + XMULTI_REF_INSTANCES xmr_instances = { 0 }; + ALL_XMULTI_REF_INFO_IDX all_xmulti_ref_info_idx = { { 0 } }; + ALL_XMULTI_REF_STATUS_IDX all_xmulti_ref_status_idx = { { 0 } }; + XMR_HOLDOVER_STATUS xmr_holdover_status; + + int b; + int rc; + int i; + + rc = mbg_chk_dev_has_xmr( dh ); + + printf( "\nXMR chk supp: %i\n", rc ); + + rc = mbg_dev_has_xmr( dh, &b ); + + if ( rc != MBG_SUCCESS || !b ) + { + printf( "XMR not supported, rc: %i, b: %i\n", rc, b ); + return; + } + + printf( "XMR supported, rc: %i, b: %i\n", rc, b ); + + printf( "\nChecking XMR:\n" ); + + rc = mbg_get_xmr_instances( dh, &xmr_instances ); + + if ( rc != MBG_SUCCESS ) + { + printf( "*** Failed to read XMR instances, rc: %i\n", rc ); + return; + } + + printf( "Slot %u, supp. XMR instances/priority levels: %u, flags: 0x%08lX\n", + xmr_instances.slot_id, xmr_instances.n_xmr_settings, + (ulong) xmr_instances.flags ); + + if ( verbose ) + { +// 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 + } + + + for ( i = 0; i < MAX_N_MULTI_REF_TYPES; i++ ) + { + int n_inst = xmr_instances.n_inst[i]; + + if ( i < N_MULTI_REF ) // a known signal type + { + if ( verbose ) + { + if ( n_inst ) + printf( "%u %s input%s supported\n", n_inst, + multi_ref_names[i], ( n_inst == 1 ) ? "" : "s" ); + else + if ( verbose > 1 ) + printf( "No %s input supported\n", multi_ref_names[i] ); + } + + continue; + } + + // If execution gets here then 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", + n_inst, i ); + } + + rc = mbg_get_gps_all_xmr_info( dh, all_xmulti_ref_info_idx, &xmr_instances ); + + if ( rc != MBG_SUCCESS ) + printf( "*** Failed to read all XMR info, rc: %i\n", rc ); + + rc = mbg_get_gps_all_xmr_status( dh, all_xmulti_ref_status_idx, &xmr_instances ); + + if ( rc != MBG_SUCCESS ) + printf( "*** Failed to read all XMR status, rc: %i\n", rc ); + + for ( i = 0; i < xmr_instances.n_xmr_settings; i++ ) + { + XMULTI_REF_INFO *p = &all_xmulti_ref_info_idx[i].info; + + printf( "XMR %i: %li\n", i, + (long) p->settings.bias.secs ); + +#if 0 + XMULTI_REF_SETTINGS_IDX xmrsi; + xmrsi.settings = p->settings; + xmrsi.settings.precision.nano_secs = i + 40; + xmrsi.settings.bias.secs = 0xA55ACDEF; + xmrsi.settings.bias.nano_secs = 0x12345678; + xmrsi.idx = i; + + rc = mbg_set_gps_xmr_settings_idx( dh, &xmrsi ); + + if ( rc != MBG_SUCCESS ) + printf( "Failed to write XMR settings %i, rc: %i\n", i, rc ); +#endif + } + + if ( !( xmr_instances.flags & XMRIF_MSK_HOLDOVER_STATUS_SUPP ) ) + printf( "*** Warning: XMR holdover status not supported!\n" ); + else + { + rc = mbg_get_xmr_holdover_status( dh, &xmr_holdover_status, &xmr_instances ); + + if ( rc != MBG_SUCCESS ) + printf( "*** Failed to read XMR holdover status, rc: %i\n", rc ); + else + { + printf( "XMR mode: %s, %s%s, %s%s, %s%s\n", + _get_xmr_holdover_status_mode_name( xmr_holdover_status.mode ), + ( xmr_holdover_status.flags & XMR_HLDOVR_MSK_IN_HOLDOVER ) ? "" : str_not_spc, "in holdover", + ( xmr_holdover_status.flags & XMR_HLDOVR_MSK_TRANSITION_ENBD ) ? "" : str_not_spc, "transition enabled", + ( xmr_holdover_status.flags & XMR_HLDOVR_MSK_IN_TRANSITION ) ? "" : str_not_spc, "in transition" + ); + +//##+++++ print_xmr_prio( xmr_holdover_status.curr_prio, "Current", +#if 0 +typedef struct +{ + uint8_t mode; ///< XMR/holdover mode, see ::XMR_HOLDOVER_STATUS_MODES + int8_t curr_prio; ///< current priority level, 0..::XMULTI_REF_INSTANCES::n_xmr_settings, or ::XMR_PRIO_LVL_UNSPEC + int8_t nxt_prio; ///< next priority level after holdover, 0..::XMULTI_REF_INSTANCES::n_xmr_settings, or ::XMR_PRIO_LVL_UNSPEC + uint8_t remote_watchdog; ///< counts down in ::XMR_HLDOVR_PRE_AUTONOMOUS mode + uint32_t reserved; ///< reserved, don't use, currently 0 + XMR_HOLDOVER_INTV elapsed; ///< elapsed time in holdover mode, only valid if ::XMR_HLDOVR_MSK_IN_HOLDOVER is set + XMR_HOLDOVER_INTV interval; ///< current holdover interval, only valid if ::XMR_HLDOVR_MSK_IN_HOLDOVER is set + uint32_t flags; ///< holdover status flags, see ::XMR_HOLDOVER_STATUS_FLAG_MASKS + +} XMR_HOLDOVER_STATUS; +#endif + + } + } + +} // test_xmr + +#endif // defined DEBUG + + + +static const int pcps_to_mbg_framing_tbl[N_PCPS_FR_DCF] = +{ + MBG_FRAMING_8N1, + MBG_FRAMING_7E2, + MBG_FRAMING_8N2, + MBG_FRAMING_8E1 +}; + + + +/*HDR*/ +void port_info_from_pcps_serial( + PORT_INFO_IDX *p_pii, + PCPS_SERIAL pcps_serial, + uint32_t supp_baud_rates +) +{ + PCPS_SER_PACK ser_pack; + PORT_INFO *p_pi; + PORT_SETTINGS *p_ps; + + ser_pack.pack = pcps_serial; + pcps_unpack_serial( &ser_pack ); + + p_pi = &p_pii[0].port_info; + p_ps = &p_pi->port_settings; + + p_ps->parm.baud_rate = mbg_baud_rates[ser_pack.baud]; + + strncpy_safe( p_ps->parm.framing, //### TODO + mbg_framing_strs[pcps_to_mbg_framing_tbl[ser_pack.frame]], + sizeof( p_ps->parm.framing ) ); + + p_ps->parm.handshake = HS_NONE; + + p_ps->str_type = 0; + p_ps->mode = ser_pack.mode; + + p_pi->supp_baud_rates = supp_baud_rates; + p_pi->supp_framings = DEFAULT_FRAMINGS_DCF; + p_pi->supp_str_types = DEFAULT_SUPP_STR_TYPES_DCF; + +} // port_info_from_pcps_serial + + +/*HDR*/ +void pcps_serial_from_port_info( + PCPS_SERIAL *p, + const PORT_INFO_IDX *p_pii +) +{ + PCPS_SER_PACK ser_pack; + const PORT_INFO *p_pi = &p_pii[0].port_info; + const PORT_SETTINGS *p_ps = &p_pi->port_settings; + int framing_idx = get_framing_idx( p_ps->parm.framing ); + int i; + + + ser_pack.baud = get_baud_rate_idx( p_ps->parm.baud_rate ); + + // Translate the common framing index to the corresponding + // number used with the old PCPS_SERIAL parameter. + // This should always return a valid result since the + // framing index is expected to be selected from + // supported framings. + for ( i = 0; i < N_PCPS_FR_DCF; i++ ) + if ( pcps_to_mbg_framing_tbl[i] == framing_idx ) + break; + + ser_pack.frame = i; + + ser_pack.mode = p_ps->mode; + + pcps_pack_serial( &ser_pack ); + + *p = ser_pack.pack; + +} // 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*/ +void pcps_unpack_serial( PCPS_SER_PACK *p ) +{ + uint8_t pack = p->pack; + + p->baud = (uint8_t) ( pack & BITMASK( PCPS_BD_BITS ) ); + p->frame = (uint8_t) ( ( pack >> PCPS_FR_SHIFT ) & BITMASK( PCPS_FR_BITS ) ); + p->mode = (uint8_t) ( ( pack >> PCPS_MOD_SHIFT ) & BITMASK( PCPS_MOD_BITS ) ); + +} // pcps_unpack_serial + + + +/*-------------------------------------------------------------- + * 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*/ +void pcps_pack_serial( PCPS_SER_PACK *p ) +{ + p->pack = (uint8_t) ( ( p->baud & BITMASK( PCPS_BD_BITS ) ) + | ( ( p->frame & BITMASK( PCPS_FR_BITS ) ) << PCPS_FR_SHIFT ) + | ( ( p->mode & BITMASK( PCPS_MOD_BITS ) ) << PCPS_MOD_SHIFT ) ); + +} /* pcps_pack_serial */ + + + +/*-------------------------------------------------------------- + * 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*/ +void pcps_setup_isa_ports( char *s, + int *port_vals, + int n_vals ) +{ + ushort i; + + + for ( i = 0; i < n_vals; i++ ) + { + if ( *s == 0 ) + break; + + *port_vals++ = (uint16_t) strtoul( s, &s, 16 ); + + if ( *s == ',' ) + s++; + } + +} // pcps_setup_isa_ports + + + +/*HDR*/ +const char *setup_device_type_name( char *s, size_t max_len, MBG_DEV_HANDLE dh, + const RECEIVER_INFO *p_ri ) +{ + size_t n = sn_cpy_str_safe( s, max_len, p_ri->model_name ); + + if ( mbg_rc_is_success( mbg_chk_dev_has_asic_version( dh ) ) ) + { + PCI_ASIC_VERSION asic_version; + + if ( mbg_rc_is_success( mbg_get_asic_version( dh, &asic_version ) ) ) + { + asic_version = _convert_asic_version_number( asic_version ); // TODO Do we need this? + + n += snprintf_safe( &s[n], max_len - n, " (PCI ASIC v" PCPS_ASIC_STR_FMT ")", + _pcps_asic_version_major( asic_version ), + _pcps_asic_version_minor( asic_version ) ); + } + } + + return s; + +} // setup_device_type_name + + + +/*HDR*/ +const char *setup_asic_features( char *s, size_t max_len, MBG_DEV_HANDLE dh ) +{ + size_t n = 0; + + if ( mbg_rc_is_success( mbg_chk_dev_has_asic_features( dh ) ) ) + { + PCI_ASIC_FEATURES asic_features; + + if ( mbg_rc_is_success( mbg_get_asic_features( dh, &asic_features ) ) ) + { + if ( asic_features & PCI_ASIC_HAS_MM_IO ) + n += sn_cpy_str_safe( &s[n], max_len - n, "Memory Mapped I/O" ); + + //### if ( asic_features & PCI_ASIC_HAS_PGMB_IRQ ) + // (implement this as loop) + } + } + + if ( n == 0 ) // nothing else printed + sn_cpy_str_safe( s, max_len, str_not_avail ); + + return s; + +} // setup_asic_features + + diff --git a/mbglib/common/deviohlp.h b/mbglib/common/deviohlp.h index f6ed431..c5aa620 100644 --- a/mbglib/common/deviohlp.h +++ b/mbglib/common/deviohlp.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: deviohlp.h 1.2 2012/10/15 13:51:18Z martin REL_M $ + * $Id: deviohlp.h 1.4 2017/07/05 13:50:18Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,15 @@ * * ----------------------------------------------------------------------- * $Log: deviohlp.h $ + * Revision 1.4 2017/07/05 13:50:18Z martin + * Moved definition of PCPS_SER_PACK here. + * Defined function type MBG_ERR_MSG_FNC. + * New structure PCPS_TIME_EXT. + * New inline function pcps_time_is_valid(). + * Updated function prototypes. + * Revision 1.3 2013/09/26 08:25:18Z martin + * Moved ALL_PTP_CFG_INFO definition to cfg_hlp.h. + * Updated doxygen comments. * Revision 1.2 2012/10/15 13:51:18Z martin * Include cfg_hlp.h. * Added structure ALL_PTP_CFG_INFO. @@ -44,114 +53,352 @@ extern "C" { #endif +/** + * @brief A helper structure used with configuration of old DCF77 clocks + * + * @deprecated This structure has been used with some very + * old DCF77 clocks to configure the serial interface. + * It has been deprecated by ::PORT_SETTINGS and ::PORT_INFO. + */ typedef struct { - PTP_CFG_INFO ptp_cfg_info; - PTP_UC_MASTER_CFG_LIMITS ptp_uc_master_cfg_limits; - ALL_PTP_UC_MASTER_INFO_IDX all_ptp_uc_master_info_idx; + PCPS_SERIAL pack; ///< This packed byte is read from or written to the board -} ALL_PTP_CFG_INFO; + 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; -/* function prototypes: */ -/* ----- function prototypes begin ----- */ +typedef int MBG_ERR_MSG_FNC( const PCPS_DEV *p_dev, const char *s ); -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - /** - Read all serial port settings and supported configuration parameters. +/** + * @brief An extended time and status structure + * + * This structure provides monitoring and configuration tools + * with a unified structure containing the current time and + * extended status. The structure needs to be set up depending + * on the capabilities of a particular device and the API calls + * which could be used to retrieve the information. + */ +typedef struct +{ + PCPS_TIME t; ///< current date, time, and limited status + uint8_t comp_sig_mode; ///< 0..::N_CONN_SIG_MODES-1, see ::COMP_SIG_MODES + int16_t comp_sig_val; ///< compensated signal value, see @ref PCPS_SIG_VAL_DEFS + int32_t utc_offs; ///< %UTC offset, always expanded to [seconds] + PCPS_TIME_STATUS_X status_x; ///< extended status, see @see @ref PCPS_TIME_STATUS_FLAGS + uint16_t year; ///< full year number + uint32_t flags; ///< see ::PCPS_TIME_EXT_FLAGS - 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 must be passed to this function. +} PCPS_TIME_EXT; - The complementary function mbg_save_serial_settings() should be used - to write the modified serial port configuration back to the board. - @param dh Valid handle to a Meinberg device. - @param *pdev Pointer to a ::PCPS_DEV structure. - @param *pcfg Pointer to a ::RECEIVER_PORT_CFG structure to be filled up. - @param *p_ri Pointer to a ::RECEIVER_INFO structure. - @return ::MBG_SUCCESS or error code returned by device I/O control function. +/** + * @brief Check if a ::PCPS_TIME structure contains valid date and time + * + * @param[in] p The structure to be checked + * + * @return != 0 if date and time valid, else 0 + */ +static __mbg_inline +int pcps_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 ); - @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 *pdev, RECEIVER_PORT_CFG *pcfg, const RECEIVER_INFO *p_ri ) ; +} // pcps_time_is_valid - /** - Write the configuration settings for a single serial port to the board. - Modifications to the serial port configuration should be made only - after mbg_get_serial_settings() had been called to read all serial port - settings and supported configuration parameters. - This function has finally to be called once for every serial port - the configuration of which has been modified. - 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 - must be passed to this function. +/* ----- function prototypes begin ----- */ - @param dh Valid handle to a Meinberg device - @param *pdev Pointer to a ::PCPS_DEV structure - @param *pcfg Pointer to a ::RECEIVER_PORT_CFG structure - @param port_num Index of the ::serial port to be saved +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ - @return ::MBG_SUCCESS or error code returned by device I/O control function. + 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 + * + * This function should be called preferably to get a summary of + * the GNSS status from GNSS receivers (GPS, GLONASS, ...). + * + * 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 + * 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 + * 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 + * 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 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbg_get_gps_stat_info + * @see ::mbg_get_gps_gnss_mode_info + * @see ::mbg_get_gps_all_gnss_sat_info + */ + int mbg_chk_get_all_gnss_info( MBG_DEV_HANDLE dh, ALL_GNSS_INFO *p_agi ) ; - @see mbg_get_serial_settings() - @see mbg_get_device_info() - @see mbg_setup_receiver_info() -*/ - int mbg_save_serial_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, RECEIVER_PORT_CFG *pcfg, int port_num ) ; + /** + * @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. + * + * @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 + * + * @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 ) ; /** - Read all PTP settings and supported configuration parameters. + * @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 + * settings and supported configuration parameters. + * This function has finally to be called once for every serial port + * the configuration of which has been modified. + * + * 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. + * + * @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 + * + * @return ::MBG_SUCCESS or error code returned by device I/O control function. + * + * @see ::mbg_get_serial_settings + * @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 ) ; - The complementary function mbg_save_all_ptp_cfg_info() should - be used to write the modified configuration back to the device. + /** + * @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, + * ::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 + * + * @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 + * + * @see ::mbg_chk_dev_has_lan_intf + * @see ::mbg_get_lan_if_info + * @see ::mbg_get_ip4_settings + * @see ::free_all_net_cfg_info + */ + int mbg_get_all_net_cfg_info( MBG_DEV_HANDLE dh, ALL_NET_CFG_INFO **p ) ; - @param dh Valid handle to a Meinberg device. - @param *p Pointer to a ::ALL_PTP_CFG_INFO structure. + /** + * @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 + * supported configuration parameters. + * + * The appropriate settings are translated into LAN_IP4 structures + * and send to the device using the appropriate API functions. + * + * 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 + * + * @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 ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @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, + * ::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 + * + * @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 + * + * @see ::mbg_chk_dev_has_lan_intf + * @see ::mbg_get_lan_if_info + * @see ::mbg_get_ip4_state + * @see ::free_all_net_status_info + */ + int mbg_get_all_net_status_info( MBG_DEV_HANDLE dh, ALL_NET_STATUS_INFO **p ) ; - @see mbg_save_all_ptp_cfg_info() - @see mbg_get_ptp_cfg_info() - @see mbg_get_ptp_uc_master_cfg_limits() - @see mbg_get_all_ptp_uc_master_info() - @see mbg_dev_has_ptp() - @see mbg_dev_has_ptp_unicast() -*/ + /** + * @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 + * + * @return ::MBG_SUCCESS or error code returned by device I/O control function. + * + * @see ::mbg_save_all_ptp_cfg_info + * @see ::mbg_get_ptp_cfg_info + * @see ::mbg_get_ptp_uc_master_cfg_limits + * @see ::mbg_get_all_ptp_uc_master_info + * @see ::mbg_chk_dev_has_ptp + * @see ::mbg_chk_dev_has_ptp_unicast + */ int mbg_get_all_ptp_cfg_info( MBG_DEV_HANDLE dh, ALL_PTP_CFG_INFO *p ) ; /** - Write all PTP settings and supported configuration parameters - 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. + * @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 + * + * @return ::MBG_SUCCESS or error code returned by device I/O control function. + * + * @see ::mbg_get_all_ptp_cfg_info + * @see ::mbg_set_ptp_cfg_settings + * @see ::mbg_set_ptp_uc_master_settings_idx + * @see ::mbg_chk_dev_has_ptp + * @see ::mbg_chk_dev_has_ptp_unicast + */ + int mbg_save_all_ptp_cfg_info( MBG_DEV_HANDLE dh, const ALL_PTP_CFG_INFO *p ) ; - @param dh Valid handle to a Meinberg device. - @param *p Pointer to a ::ALL_PTP_CFG_INFO structure. + /** + * @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 + * + * A ::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 + * + * @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 + * + * @see ::free_all_xmulti_ref_info + */ + int mbg_get_all_xmulti_ref_info( MBG_DEV_HANDLE dh, ALL_XMULTI_REF_INFO **p ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @brief Set 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 + * + * @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 ) ; - @see mbg_get_all_ptp_cfg_info() - @see mbg_set_ptp_cfg_settings() - @see mbg_set_ptp_uc_master_settings_idx() - @see mbg_dev_has_ptp() - @see mbg_dev_has_ptp_unicast() -*/ - int mbg_save_all_ptp_cfg_info( MBG_DEV_HANDLE dh, const ALL_PTP_CFG_INFO *p ) ; + /** + * @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 + * + * A ::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 + * + * @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 + * + * @see ::free_all_xmulti_ref_status + */ + 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 + * + * @note ::mbg_chk_dev_has_ucap should be called to check if this API is supported. + * + * The appropriate number of ::TTM structures will be allocated and needs to be freed + * 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 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbg_chk_dev_has_ucap + * @see ::free_all_ucap_info + */ + int mbg_get_all_ucap_info( MBG_DEV_HANDLE dh, ALL_UCAP_INFO **p ) ; + + void test_gpio( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int verbose ) ; + 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 ) ; + void pcps_unpack_serial( PCPS_SER_PACK *p ) ; + void pcps_pack_serial( PCPS_SER_PACK *p ) ; + 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 ) ; /* ----- function prototypes end ----- */ diff --git a/mbglib/common/gpsdefs.h b/mbglib/common/gpsdefs.h index 25eff0f..6444cf6 100644 --- a/mbglib/common/gpsdefs.h +++ b/mbglib/common/gpsdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: gpsdefs.h 1.113 2013/04/04 09:02:01Z martin REL_M Gregoire $ + * $Id: gpsdefs.h 1.126 2018/07/05 10:18:34Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -13,6 +13,207 @@ * * ----------------------------------------------------------------------- * $Log: gpsdefs.h $ + * Revision 1.126 2018/07/05 10:18:34Z 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. + * New builtin features .._MODEL_HAS_UP_CONV, .._MODEL_HAS_MBG_OS. + * BUILTIN_FEAT_DCF_PZF_2 includes GPS_MODEL_IS_DCF_AM. + * Builtin features of some models were updated. + * Removed obsolete MBG_XFEATURE_USB_LOCK. + * New extended features MBG_XFEATURE_TAINTED_CFG, MBG_XFEATURE_PUSH_MSGS, + * MBG_XFEATURE_USER_AUTH, MBG_XFEATURE_USER_MNGMNT, MBG_XFEATURE_SERVICE, + * MBG_XFEATURE_UP_CONV, MBG_XFEATURE_FW_MNGMNT, MBG_XFEATURE_DAC_CTRL_PCI, + * MBG_XFEATURE_DATABASE, MBG_XFEATURE_GNSS_MODE. + * New string mode STR_CR_ON_SEC. + * Renamed legacy string modes to LGCY_STR_ON_REQ, etc. and provided + * compatibility definitions for old firmware builds. + * New XMR_SETTINGS_FLAG_BITS: XMRSF_BIT_IS_TRUSTED_SRC, + * XMRSF_BIT_USE_TRUSTED_SRC, XMRSF_BIT_IS_TIME_OF_DAY_SRC, + * XMRSF_BIT_IS_PHASE_SRC. + * New XMR_REF_STATUS_BITS: XMRS_BIT_TRS_LIMIT_VIOLATED. + * New XMR_INST_FLAGS: XMRIF_BIT_GNSS_BIAS_SUPP. + * New XMR_EXT_SRC_FEAT_FLAG_BITS: XMR_EXT_SRC_FEAT_FLAG_BIT_COASTING. + * Some MBG_EVT_IDS numbers were added. + * Some MBG_IMS_SENSORS were added. + * New MBG_NET_GLB_CFG_INFO_FLAGS: MBG_NET_GLB_SUPP_ADD_CONF, + * MBG_NET_GLB_SUPP_EXT_ROUTING. + * New MBG_NET_INTF_ADDR_BITS: MBG_NET_INTF_ADDR_BIT_AUTOCONF. + * Former PTP_CFG_SETTINGS::reserved field was split into + * PTP_CFG_SETTINGS::delay_asymmetry and PTP_CFG_SETTINGS::flags_ex. + * Former PTP_CFG_INFO::reserved_2 field was renmamed to + * PTP_CFG_INFO::supp_flags_ex. + * New PTP_CFG_FLAGS: PTP_CFG_ATOI, PTP_CFG_HAS_SMPTE_TLV_STATE, + * PTP_CFG_NTP_SW_SERVER, PTP_CFG_HAS_EXT_SUPP_FLAGS. + * New extended flags bits PTP_CFG_FLAGS_EX used with PTP configuration. + * New PTP profile ID PTP_OPT_EXT_C37238_2017. + * Former PTP_POWER_PROFILE_CFG::reserved_2 renamed to + * PTP_POWER_PROFILE_CFG::grandmaster_id_2017. + * New NTP_FLAGS: NTP_ADD_CONF and related definitions. + * NTP refclock configuration and statistics stuff was added. + * Former NTP_SYS_STATE::cfg_counter was renamed to + * NTP_SYS_STATE::service_state. + * IMS slot types were added. + * XBP_NODE_INFO structure was modified. + * New MBG_TLV_FEAT_TYPES: MBG_TLV_FEAT_TYPE_TIMEMON_FULL_STATUS. + * Some new MBG_EXT_SYS_INFO_BITS. + * OS type support was added. + * Extended management transactions support. + * Lots of new I/O port stuff. + * Some new definitions for SNMP support. + * New definitions for event logging. + * New tainted cfg stuff. + * Support for user and permission management. + * Support for services control. + * Support for firmware updates. + * Support for database management. + * Revision 1.125 2017/07/05 18:18:27 martin + * New models GPS_MODEL_CTC100, GPS_MODEL_TCR180, + * GPS_MODEL_LUE180, GPS_MODEL_CPC_01, GPS_MODEL_TSU_01, + * GPS_MODEL_CMC_01, GPS_MODEL_SCU_01, GPS_MODEL_FCU_01, + * GPS_MODEL_CSM100, GPS_MODEL_LNE180SFP, GPS_MODEL_GTS180, + * GPS_MODEL_GPS180CSM, GPS_MODEL_GRC181, GPS_MODEL_N2X180, + * GPS_MODEL_GNS181PEX, GPS_MODEL_MDU180, GPS_MODEL_MDU312, + * GPS_MODEL_GPS165, GPS_MODEL_GNS181_UC, GPS_MODEL_PSX_4GE, + * GPS_MODEL_RSC180RDU, GPS_MODEL_USYNCPWR, GPS_MODEL_FDM180M, + * GPS_MODEL_LSG180, GPS_MODEL_GPS190, GPS_MODEL_GNS181 and + * associated definitions. + * New GPS_BUILTIN_FEATURE_BITS and associated definitions. + * New macros _setup_default_receiver_info_dcf() and + * _setup_default_receiver_info_gps() as well as associated + * definitions which can be used to set up a RECEIVER_INFO + * structure for legacy devices which don't provide it. + * New Receiver_INO feature bit GPS_FEAT_XFEATURE which + * indicates that a new, extended feature set is supported. + * Defined a new st of extended features (MBG_XFEATURE_BITS) + * and associated definitions. + * Moved definitions for NANO_TIME and NANO_TIME_64 to words.h. + * New IRIG TX codes ICODE_TX_A006_A136, ICODE_TX_A007_A137, + * and associated definitions. + * Renamed ICODE_RX_G142_G146 to ICODE_RX_G142, and + * ICODE_RX_G002_G006 to ICODE_RX_G002. + * New IRIG RX codes ICODE_RX_A136_A137, ICODE_RX_A006_A007, + * ICODE_RX_G146, ICODE_RX_G006, and associated definitions. + * New union POUT_DATA union used for varying configuration + * data in POUT_SETTINGS, depending on the output mode. + * New POUT_MODES POUT_PTTI_PPS, POUT_HAVEQUICK, and + * associated definitions. + * Definitions to support a configurable pulse shift + * of some programmable output signals. + * New multiref source MULTI_REF_SYNCE and associated + * definitions. + * Added a number of swab..() macros that were still missing. + * XMR statistics, XMR_QL and some other XMR stuff by andre. + * New GPIO types including video modes, and associated stuff. + * Renamed some structure fields and added some definitions + * related to FDM. + * Added some SCU_STAT_MASKS. + * New GNSS_TYPE_QZSS, and modified MBG_GNSS_MODE_INFO. + * New flag MBG_GNSS_FLAG_HAS_SV_STATUS, structure + * GNSS_SV_STATUS and associated definitions. + * A bunch of new structures and definitions for network + * configuration. + * Many new structures and definitions for NTP configuration. + * New structures and associated definitions used to send + * user capture events over the network (ext_ucap). + * New PTP_ROLES and associated stuff. + * Changed one of PTP_STATE's reserved fields to tsu_secs. + * Changed PTP_ANN_RCPT_TIMEOUT_MAX from 255 to 8. + * New PTP_CFG_FLAGS, PTP_OPT_EXTS flags, PTP_PRESETS_MASKS + * and associated definitions. + * Definitions for PTPv1 and v2 data sets, and PTP statistics. + * Preliminary definitions to support SMPTE and SDH. + * Definition for XBP addressing of devices. + * Definitions to support TLVs. + * Added LED and LNE API definitions. + * MBG_EXT_SYS_INFO_BITS and associated definitions for an + * extended sysinfo API. + * MBG_CLK_RES_INFO and associated stuff for clock resolution + * info. + * Definitions for configuration transaction handling. + * Definitions for a higher level I/O port API. + * Definitions for monitoring / notification. + * Definitions for USB locking. + * Preliminary licensing stuff. + * Defined macros in a safer way. + * Revision 1.124 2015/07/14 14:22:46 martin + * Doxygen fix. + * Revision 1.123 2015/07/06 13:00:10 martin + * Added definitions for VSG180, MSF180, WWVB180, and CPC180. + * Added definitions for PZF180. + * Definitions for SDI and MDU300 added by stephan. + * Definitions for HPS100 added by daniel. + * FDM180 and associated definitions added by paul. + * Started to support eXtended Binary Protocol (XBP). + * Merged daniel and gregoire's changes from the 1.120.2.x branch. + * Defines for IPv6 multicast scopes added by gregoire. + * XMR_EXT_SRC_INFO and associated XMR_SETTINGS_FLAG_MSKS flags + * defined by andre. + * Support XMULTI_REF_INFO::n_prio field again. + * Fixed _mbg_swab_gpio_cfg_limits() macro. + * Added MBG_NET_LINK_OPT_MASK_CAN_SYNCE to MBG_NET_LINK_OPT_MASKS. + * New PTP_ROLE_MASKS PTP_ROLE_NTP_SERVER and PTP_ROLE_NTP_CLIENT. + * Some PTP profile extensions added by daniel. + * Added missing defines for SPT. + * Added definitions for REL1000. + * Moved structure NANO_TIME_64 here. + * Revision 1.122 2014/07/29 08:57:44Z martin + * Updated doxygen comments. + * Revision 1.121 2014/07/17 09:41:50 martin + * Introduced XMR_HOLDOVER_STATUS, MBG_GPIO_STATUS, + * and associated definitions. + * Huge update and cleanup on doxygen comments. + * Revision 1.120 2014/05/27 08:34:40 martin + * Fixed braces in some _mbg_rcvr_is_..() macros. + * Definitions used with extended network cfg, VST, and SHS. + * Introduced XMR_HOLDOVER_STATUS. + * Introduced programmable output mode POUT_GPIO. + * Introduced oscillator type OCXO_SQ. + * Defined some new baud rates. + * Defines for IEEE C37.118.1-2011 CTQ. + * Support for new model SCG by paul. + * Support new model PPG180. + * New SCU control masks. + * New GNSS flag MBG_GNSS_FLAG_SAT_INFO_IDX_SUPP_SER. + * DEFAULT_MULTI_REF_NAMES_SHORT added by udo. + * Definitions used for NTP configuration by thomas-b and marvin. + * MBG_NET_ADDR structures changed to MBG_IP_ADDR, and + * associated symbols defined by marvin. + * Huge rework of comments in doxygen format. + * Revision 1.119 2013/12/05 10:13:13 daniel + * Support new PTP_CFG_FLAGS for 1-step-L2 and 1-step-P2P support + * Revision 1.118 2013/11/19 13:38:35 martin + * Added LAN_IF_TYPE_RSC. + * Revision 1.117 2013/11/18 14:13:39 martin + * Support model LNE_GB. + * Revision 1.116 2013/11/11 09:46:11 martin + * New PTP configuration flags PTP_CFG_SUPP_MCAST_SLAVE_FLAG and + * PTP_CFG_CAN_BE_MULTICAST_SLAVE, plus associated bit masks. + * New XMR_INST_FLAGS and XMR_INST_FLAG_MASKS defined by andre. + * Fixes for big-endian targets. + * Updated doxygen comments. + * Revision 1.115 2013/10/02 15:19:28 martin + * Changed PTP_CFG_SETTINGS::vlan_cfg back to a reserved field, + * and removed associated flag and flag mask. + * Revision 1.114 2013/09/25 11:02:10 martin + * Support models MRI, BPE, GLN180PEX, N2X, RSC180. + * Added feature bit GPS_FEAT_NTP. + * Enhanced VLAN configuration structures. + * Started to support IPv6. + * Renamed PTP_CFG_SETTINGS field "profile" to "selected_presets". + * Renamed PTP_CFG_INFO field "supp_profiles" to "supp_opt_ext". + * New PTP role PTP_ROLE_BOTH_MASTER. + * New PTP flag PTP_FLAG_ONE_STEP. + * Added some new PTP_CFG_FLAGS flags. + * Added PTP_OPT_EXTS and associated definitions. + * Added PTP_PRESETS and associated definitions. + * Added "tzdl" field to PTP_POWER_PROFILE_CFG. + * Made reserved PTP_CFG_SETTINGS field to "opt_ext" field. + * Made reserved PTP_CFG_SETTINGS field to "vlan_cfg" field. + * Made reserved PTP_STATE field to "parent_clock_class" and "parent_clock_accuracy". + * Definitions for MULTI_REF_EXT_OSC added by Andre. + * String initializers for supported HaveQuick formats added by Gregoire. + * Lots of doxygen changes. * Revision 1.113 2013/04/04 09:02:01Z martin * Added definitions to support HaveQuick. * Fixed a typo. @@ -140,7 +341,7 @@ * Added support for new model GLN170. * Revision 1.87 2010/03/10 11:29:37Z martin * Added definitions for GPS180. - * Added multiref source 1 PPS plus associated string. + * Added multi ref source 1 PPS plus associated string. * Revision 1.86 2010/02/17 14:16:42 martin * Added definitions for PZF600 and TCR600. * Revision 1.85 2010/02/15 11:34:36 martin @@ -210,7 +411,7 @@ * Added definitions for PTP270PEX and FRC511PEX. * Revision 1.67 2008/07/17 08:54:52Z martin * Added macros to convert the endianess of structures. - * Added multiref fixed frequency source. + * Added multi ref fixed frequency source. * Revision 1.66 2008/05/19 14:49:07 daniel * Renamed s_addr to start_addr in FPGA_INFO. * Revision 1.65 2008/05/19 09:00:01Z martin @@ -232,7 +433,7 @@ * Added definitions to support GPS170PEX. * Revision 1.60 2007/09/13 12:37:35Z martin * Modified and added initializers for TZDL. - * Added multiref source PTP over E1. + * Added multi ref source PTP over E1. * Added codes for MSF511 and GRC170 devices. * Modified XMULTI_REF_SETTINGS and XMULTI_REF_STATUS structures. * Avoid inclusion of other Meinberg headers in non-Meinberg projects. @@ -430,6 +631,7 @@ #endif + /* Start of header body */ #if defined( _USE_PACK ) @@ -438,12 +640,36 @@ #endif + /* "magic" number */ #define MEINBERG_MAGIC 0x6AAC -#define MIN_SVNO 1 /* min. SV number */ -#define MAX_SVNO 32 /* max. SV number */ -#define N_SVNO ( MAX_SVNO - MIN_SVNO + 1) /* number of possibly active SVs */ +/** + * @brief GNSS satellite numbers + * + * @todo: Check if MAX_SVNO_GLN is 94 instead of 95, and thus + * N_SVNO_GLN is 30 instead of 31, as reported by Wikipedia. + */ +enum GNSS_SVNOS +{ + MIN_SVNO_GPS = 1, ///< min. GPS satellite PRN number + MAX_SVNO_GPS = 32, ///< max. GPS satellite PRN number + N_SVNO_GPS = 32, ///< max. number of active GPS satellites + + MIN_SVNO_WAAS = 33, ///< min. WAAS satellite number + MAX_SVNO_WAAS = 64, ///< max. WAAS satellite number + N_SVNO_WAAS = 32, ///< max. number of active WAAS satellites + + MIN_SVNO_GLONASS = 65, ///< min. Glonass satellite number (64 + sat slot ID) + MAX_SVNO_GLONASS = 95, ///< max. Glonass satellite number (64 + sat slot ID) + N_SVNO_GLONASS = 31 ///< max. number of active Glonass satellites +}; + +// for compatibility with GPS-only software: +#define MIN_SVNO MIN_SVNO_GPS ///< min. SV number +#define MAX_SVNO MAX_SVNO_GPS ///< max. SV number +#define N_SVNO N_SVNO_GPS ///< number of possibly active SVs + #define GPS_ID_STR_LEN 16 @@ -459,17 +685,17 @@ /* * The actual ticks per seconds may vary for different * GPS receiver models. If this is the case, the receiver - * model support the RECEIVER_INFO structure which contains + * model support the ::RECEIVER_INFO structure which contains * the actual value. */ - #define GPS_TICKS_PER_SEC DEFAULT_GPS_TICKS_PER_SEC ///< @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 health code -typedef uint16_t CFG; ///< an SV's configuration code +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 @@ -478,17 +704,17 @@ typedef uint16_t IOD; ///< Issue-Of-Data code #ifndef _CSUM_DEFINED typedef uint16_t CSUM; ///< checksum used by some structures stored in non-volatile memory #define _CSUM_DEFINED - - #define _mbg_swab_csum( _p ) _mbg_swab16( _p ) #endif +#define _mbg_swab_csum( _p ) _mbg_swab16( _p ) + + /** * @brief The type of a GPS command code * - * These command codes can be passed via - * @ref group_gps_cmds_serial "serial port" (see @file gpsserio.h), or - * @ref group_gps_cmds_bus "system bus" (see @file pcpsdefs.h). + * @see ::GPS_CMD_CODES + * @see ::PC_GPS_CMD_CODES */ typedef uint16_t GPS_CMD; @@ -500,23 +726,27 @@ typedef uint16_t GPS_CMD; * * Contains a software revision code, plus an optional * identifier for a customized version. + * + * @see @ref group_ext_sys_info */ typedef struct { uint16_t code; ///< Version number, e.g. 0x0120 means v1.20 - char name[GPS_ID_STR_SIZE]; ///< Optional string identifying a customized version + char name[GPS_ID_STR_SIZE]; ///< Optional string identifying a customized firmware version, should be empty in standard versions uint8_t reserved; ///< Reserved field to yield even structure size + } SW_REV; #define _mbg_swab_sw_rev( _p ) \ +do \ { \ _mbg_swab16( &(_p)->code ); \ -} +} while ( 0 ) /** - * @defgroup group_bvar_stat BVAR_STAT status of buffered GPS data + * @defgroup group_bvar_stat Status of buffered (non-volatile) data * * Status word, associated bit numbers and bit masks indicating * whether certain data from the GPS satellites are @@ -528,11 +758,14 @@ typedef struct * @{ */ /** - * @brief Status flags of battery buffered data received - * from GPS satellites. + * @brief Status flags of battery buffered data + * + * Related to data received from the satellites, or data derived thereof. * * All '0' means OK, single bits set to '1' indicate * the associated type of GPS data is not available. + * + * @see ::BVAR_FLAGS */ typedef uint16_t BVAR_STAT; @@ -540,16 +773,20 @@ typedef uint16_t BVAR_STAT; /** - * @brief Enumeration of bits used with BVAR_STAT + * @brief Enumeration of flag bits used to define ::BVAR_FLAGS * * For each bit which is set this means the associated data set in - * non-volatile memory is not available or incomplete. + * non-volatile memory is not available, or incomplete. * Most data sets will just be re-collected from the data streams sent * by the satellites. However, the receiver position has usually been * computed earlier during normal operation, and will be re-computed * when a sufficient number of satellites can be received. + * + * @see ::BVAR_STAT + * @see ::BVAR_FLAGS + * @see ::BVAR_FLAG_NAMES */ -enum BVAR_BITS +enum BVAR_FLAG_BITS { BVAR_BIT_CFGH_INVALID, ///< Satellite configuration and health parameters incomplete BVAR_BIT_ALM_NOT_COMPLETE, ///< Almanac parameters incomplete @@ -559,15 +796,45 @@ enum BVAR_BITS N_BVAR_BIT ///< number of defined ::BVAR_STAT bits }; -#define BVAR_CFGH_INVALID ( 1UL << BVAR_BIT_CFGH_INVALID ) ///< Configuration and health data (::CFGH) not valid -#define BVAR_ALM_NOT_COMPLETE ( 1UL << BVAR_BIT_ALM_NOT_COMPLETE ) ///< Almanach data (::ALM) not complete -#define BVAR_UTC_INVALID ( 1UL << BVAR_BIT_UTC_INVALID ) ///< ::UTC data not valid -#define BVAR_IONO_INVALID ( 1UL << BVAR_BIT_IONO_INVALID ) ///< Ionospheric correction data (::IONO) not valid -#define BVAR_RCVR_POS_INVALID ( 1UL << BVAR_BIT_RCVR_POS_INVALID ) ///< Receiver position (::POS) not valid + +/** + * @brief Bit masks associated with ::BVAR_FLAG_BITS + * + * Used with ::BVAR_STAT. + * + * @see ::BVAR_STAT + * @see ::BVAR_FLAG_BITS + * @see ::BVAR_FLAG_NAMES + */ +enum BVAR_FLAGS +{ + BVAR_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 -/** @} group_bvar_stat */ + +/** + * @brief String initializer for ::BVAR_STAT flag names + * + * @see ::BVAR_STAT + * @see ::BVAR_FLAG_BITS + * @see ::BVAR_FLAGS + */ +#define BVAR_FLAG_NAMES \ +{ \ + "Sat. config and health", \ + "Almanac", \ + "UTC offset", \ + "Ionospheric correction", \ + "Receiver position" \ +} + +/** @} defgroup group_bvar_stat */ @@ -580,19 +847,21 @@ typedef struct { uint16_t khz_val; ///< the base frequency in [kHz] int16_t range; ///< an optional base 10 exponent + } FIXED_FREQ_INFO; #define _mbg_swab_fixed_freq_info( _p ) \ +do \ { \ _mbg_swab16( &(_p)->khz_val ); \ _mbg_swab16( &(_p)->range ); \ -} +} while ( 0 ) /** * @brief A data type to specify feature flags within ::RECEIVER_INFO */ -typedef uint32_t RI_FEATURES; ///< @see GPS_FEATURE_MASKS +typedef uint32_t RI_FEATURES; ///< see @ref GPS_FEATURE_MASKS @@ -607,21 +876,23 @@ typedef struct SW_REV sw_rev; ///< software revision and ID char model_name[GPS_ID_STR_SIZE]; ///< ASCIIZ, name of receiver model char sernum[GPS_ID_STR_SIZE]; ///< ASCIIZ, serial number - char epld_name[GPS_EPLD_STR_SIZE]; ///< ASCIIZ, file name of EPLD image + char epld_name[GPS_EPLD_STR_SIZE]; ///< ASCIIZ, file name of EPLD image (optional) uint8_t n_channels; ///< number of satellites which can be tracked simultaneously uint32_t ticks_per_sec; ///< resolution of fractions of seconds, see ::GPS_TICKS_PER_SEC - RI_FEATURES features; ///< optional features, see ::GPS_FEATURE_MASKS - FIXED_FREQ_INFO fixed_freq; ///< optional non-standard fixed frequency + RI_FEATURES features; ///< optional features, see @ref GPS_FEATURE_MASKS + FIXED_FREQ_INFO fixed_freq; ///< optional non-standard fixed frequency, may be 0 if not supported uint8_t osc_type; ///< type of installed oscillator, see ::GPS_OSC_TYPES uint8_t osc_flags; ///< oscillator flags, actually not used and always 0 uint8_t n_ucaps; ///< number of user time capture inputs uint8_t n_com_ports; ///< number of on-board serial ports uint8_t n_str_type; ///< max num of string types supported by any port uint8_t n_prg_out; ///< number of programmable pulse outputs - uint16_t flags; ///< additional information, see ::RECEIVER_INFO_FLAG_BITS + uint16_t flags; ///< additional information, see ::RECEIVER_INFO_FLAG_MASKS + } RECEIVER_INFO; #define _mbg_swab_receiver_info( _p ) \ +do \ { \ _mbg_swab16( &(_p)->model_code ); \ _mbg_swab_sw_rev( &(_p)->sw_rev ); \ @@ -629,11 +900,14 @@ typedef struct _mbg_swab32( &(_p)->features ); \ _mbg_swab_fixed_freq_info( &(_p)->fixed_freq ); \ _mbg_swab16( &(_p)->flags ); \ -} +} while ( 0 ) /** - * @brief Known device ID codes for RECEIVER_INFO::model_code + * @brief Known device ID codes for ::RECEIVER_INFO::model_code + * + * @see @ref GPS_MODEL_NAMES + * @see ::DEFAULT_GPS_MODEL_NAMES */ enum GPS_MODEL_CODES { @@ -685,74 +959,206 @@ enum GPS_MODEL_CODES GPS_MODEL_LIU, GPS_MODEL_DCF600HS, GPS_MODEL_DCF600RS, + GPS_MODEL_MRI, + GPS_MODEL_BPE, + GPS_MODEL_GLN180PEX, + GPS_MODEL_N2X, + GPS_MODEL_RSC180, + GPS_MODEL_LNE_GB, + GPS_MODEL_PPG180, + GPS_MODEL_SCG, + GPS_MODEL_MDU300, + GPS_MODEL_SDI, + GPS_MODEL_FDM180, + GPS_MODEL_SPT, + GPS_MODEL_PZF180, + GPS_MODEL_REL1000, + GPS_MODEL_HPS100, + GPS_MODEL_VSG180, + GPS_MODEL_MSF180, + GPS_MODEL_WWVB180, + GPS_MODEL_CPC180, + GPS_MODEL_CTC100, + GPS_MODEL_TCR180, + GPS_MODEL_LUE180, + GPS_MODEL_CPC_01, + GPS_MODEL_TSU_01, + GPS_MODEL_CMC_01, + GPS_MODEL_SCU_01, + GPS_MODEL_FCU_01, + GPS_MODEL_CSM100, + GPS_MODEL_LNE180SFP, + GPS_MODEL_GTS180, + GPS_MODEL_GPS180CSM, + GPS_MODEL_GRC181, + GPS_MODEL_N2X180, + GPS_MODEL_GNS181PEX, + GPS_MODEL_MDU180, + GPS_MODEL_MDU312, + GPS_MODEL_GPS165, + GPS_MODEL_GNS181_UC, + GPS_MODEL_PSX_4GE, + GPS_MODEL_RSC180RDU, + GPS_MODEL_USYNCPWR, + GPS_MODEL_FDM180M, + GPS_MODEL_LSG180, // Line Signal Generator + GPS_MODEL_GPS190, + GPS_MODEL_GNS181, + GPS_MODEL_PIO180, // Programmable I/O module + GPS_MODEL_FCM180, // Fake Clock Module + GPS_MODEL_TCR180USB, + GPS_MODEL_SSP100, // Secure Sync Processor (HPS with USB-Lock) + 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 N_GPS_MODEL /* If new model codes are added then care must be taken - * to update the associated string initializers below - * accordingly, and to check whether the classification macros - * also cover the new model names. */ + * to update the associated string initializers GPS_MODEL_NAMES + * and GPS_MODEL_NAME_TABLE accordingly, and to check whether + * the classification macros also cover the new model names. + * + * CARE MUST BE TAKEN that the name string of bus level devices + * is limited to 9 characters. Longer strings will not fit into + * the name field of the PCPS_DEV_TYPE structure. + */ }; - +/** + * @brief Model name strings used with Meinberg devices + * + * String initializers for each of the device models + * enumerated in ::GPS_MODEL_CODES. + * + * @see ::GPS_MODEL_CODES + * @see ::DEFAULT_GPS_MODEL_NAMES + * + * @anchor GPS_MODEL_NAMES @{ */ + +#define GPS_MODEL_NAME_UNKNOWN "Unknown" +#define GPS_MODEL_NAME_GPS166 "GPS166" +#define GPS_MODEL_NAME_GPS167 "GPS167" +#define GPS_MODEL_NAME_GPS167SV "GPS167SV" +#define GPS_MODEL_NAME_GPS167PC "GPS167PC" +#define GPS_MODEL_NAME_GPS167PCI "GPS167PCI" +#define GPS_MODEL_NAME_GPS163 "GPS163" +#define GPS_MODEL_NAME_GPS168PCI "GPS168PCI" +#define GPS_MODEL_NAME_GPS161 "GPS161" +#define GPS_MODEL_NAME_GPS169PCI "GPS169PCI" +#define GPS_MODEL_NAME_TCR167PCI "TCR167PCI" +#define GPS_MODEL_NAME_GPS164 "GPS164" +#define GPS_MODEL_NAME_GPS170PCI "GPS170PCI" +#define GPS_MODEL_NAME_PZF511 "PZF511" +#define GPS_MODEL_NAME_GPS170 "GPS170" +#define GPS_MODEL_NAME_TCR511 "TCR511" +#define GPS_MODEL_NAME_AM511 "AM511" +#define GPS_MODEL_NAME_MSF511 "MSF511" +#define GPS_MODEL_NAME_GRC170 "GRC170" +#define GPS_MODEL_NAME_GPS170PEX "GPS170PEX" +#define GPS_MODEL_NAME_GPS162 "GPS162" +#define GPS_MODEL_NAME_PTP270PEX "PTP270PEX" +#define GPS_MODEL_NAME_FRC511PEX "FRC511PEX" +#define GPS_MODEL_NAME_GEN170 "GEN170" +#define GPS_MODEL_NAME_TCR170PEX "TCR170PEX" +#define GPS_MODEL_NAME_WWVB511 "WWVB511" +#define GPS_MODEL_NAME_MGR170 "MGR170" +#define GPS_MODEL_NAME_JJY511 "JJY511" +#define GPS_MODEL_NAME_PZF600 "PZF600" +#define GPS_MODEL_NAME_TCR600 "TCR600" +#define GPS_MODEL_NAME_GPS180 "GPS180" +#define GPS_MODEL_NAME_GLN170 "GLN170" +#define GPS_MODEL_NAME_GPS180PEX "GPS180PEX" +#define GPS_MODEL_NAME_TCR180PEX "TCR180PEX" +#define GPS_MODEL_NAME_PZF180PEX "PZF180PEX" +#define GPS_MODEL_NAME_MGR180 "MGR180" +#define GPS_MODEL_NAME_MSF600 "MSF600" +#define GPS_MODEL_NAME_WWVB600 "WWVB600" +#define GPS_MODEL_NAME_JJY600 "JJY600" +#define GPS_MODEL_NAME_GPS180HS "GPS180HS" +#define GPS_MODEL_NAME_GPS180AMC "GPS180AMC" +#define GPS_MODEL_NAME_ESI180 "ESI180" +#define GPS_MODEL_NAME_CPE180 "CPE180" +#define GPS_MODEL_NAME_LNO180 "LNO180" +#define GPS_MODEL_NAME_GRC180 "GRC180" +#define GPS_MODEL_NAME_LIU "LIU" +#define GPS_MODEL_NAME_DCF600HS "DCF600HS" +#define GPS_MODEL_NAME_DCF600RS "DCF600RS" +#define GPS_MODEL_NAME_MRI "MRI" +#define GPS_MODEL_NAME_BPE "BPE" +#define GPS_MODEL_NAME_GLN180PEX "GLN180PEX" +#define GPS_MODEL_NAME_N2X "N2X" +#define GPS_MODEL_NAME_RSC180 "RSC180" +#define GPS_MODEL_NAME_LNE_GB "LNE_GB" +#define GPS_MODEL_NAME_PPG180 "PPG180" +#define GPS_MODEL_NAME_SCG "SCG" +#define GPS_MODEL_NAME_MDU300 "MDU300" +#define GPS_MODEL_NAME_SDI "SDI" +#define GPS_MODEL_NAME_FDM180 "FDM180" +#define GPS_MODEL_NAME_SPT "SPT" +#define GPS_MODEL_NAME_PZF180 "PZF180" +#define GPS_MODEL_NAME_REL1000 "REL1000" +#define GPS_MODEL_NAME_HPS100 "HPS100" +#define GPS_MODEL_NAME_VSG180 "VSG180" +#define GPS_MODEL_NAME_MSF180 "MSF180" +#define GPS_MODEL_NAME_WWVB180 "WWVB180" +#define GPS_MODEL_NAME_CPC180 "CPC180" +#define GPS_MODEL_NAME_CTC100 "CTC100" +#define GPS_MODEL_NAME_TCR180 "TCR180" +#define GPS_MODEL_NAME_LUE180 "LUE180" +#define GPS_MODEL_NAME_CPC_01 "CPC_01" +#define GPS_MODEL_NAME_TSU_01 "TSU_01" +#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_LNE180SFP "LNE180SFP" +#define GPS_MODEL_NAME_GTS180 "GTS180" +#define GPS_MODEL_NAME_GPS180CSM "GPS180CSM" +#define GPS_MODEL_NAME_GRC181 "GRC181" +#define GPS_MODEL_NAME_N2X180 "N2X180" +#define GPS_MODEL_NAME_GNS181PEX "GNS181PEX" +#define GPS_MODEL_NAME_MDU180 "MDU180" +#define GPS_MODEL_NAME_MDU312 "MDU312" +#define GPS_MODEL_NAME_GPS165 "GPS165" +#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_FDM180M "FDM180M" +#define GPS_MODEL_NAME_LSG180 "LSG180" +#define GPS_MODEL_NAME_GPS190 "GPS190" +#define GPS_MODEL_NAME_GNS181 "GNS181" +#define GPS_MODEL_NAME_PIO180 "PIO180" +#define GPS_MODEL_NAME_FCM180 "FCM180" +#define GPS_MODEL_NAME_TCR180USB "TCR180USB" +#define GPS_MODEL_NAME_SSP100 "SSP100" +#define GPS_MODEL_NAME_GNS165 "GNS165" +#define GPS_MODEL_NAME_RSC180RDMP "RSC180RDMP" +#define GPS_MODEL_NAME_GPS16X "GPS16x" +#define GPS_MODEL_NAME_MSHPS100 "MSHPS100" /* - * String initializers for each of the GPS - * receiver models enum'ed above: - */ -#define GPS_MODEL_NAME_UNKNOWN "(unknown)" -#define GPS_MODEL_NAME_GPS166 "GPS166" -#define GPS_MODEL_NAME_GPS167 "GPS167" -#define GPS_MODEL_NAME_GPS167SV "GPS167SV" -#define GPS_MODEL_NAME_GPS167PC "GPS167PC" -#define GPS_MODEL_NAME_GPS167PCI "GPS167PCI" -#define GPS_MODEL_NAME_GPS163 "GPS163" -#define GPS_MODEL_NAME_GPS168PCI "GPS168PCI" -#define GPS_MODEL_NAME_GPS161 "GPS161" -#define GPS_MODEL_NAME_GPS169PCI "GPS169PCI" -#define GPS_MODEL_NAME_TCR167PCI "TCR167PCI" -#define GPS_MODEL_NAME_GPS164 "GPS164" -#define GPS_MODEL_NAME_GPS170PCI "GPS170PCI" -#define GPS_MODEL_NAME_PZF511 "PZF511" -#define GPS_MODEL_NAME_GPS170 "GPS170" -#define GPS_MODEL_NAME_TCR511 "TCR511" -#define GPS_MODEL_NAME_AM511 "AM511" -#define GPS_MODEL_NAME_MSF511 "MSF511" -#define GPS_MODEL_NAME_GRC170 "GRC170" -#define GPS_MODEL_NAME_GPS170PEX "GPS170PEX" -#define GPS_MODEL_NAME_GPS162 "GPS162" -#define GPS_MODEL_NAME_PTP270PEX "PTP270PEX" -#define GPS_MODEL_NAME_FRC511PEX "FRC511PEX" -#define GPS_MODEL_NAME_GEN170 "GEN170" -#define GPS_MODEL_NAME_TCR170PEX "TCR170PEX" -#define GPS_MODEL_NAME_WWVB511 "WWVB511" -#define GPS_MODEL_NAME_MGR170 "MGR170" -#define GPS_MODEL_NAME_JJY511 "JJY511" -#define GPS_MODEL_NAME_PZF600 "PZF600" -#define GPS_MODEL_NAME_TCR600 "TCR600" -#define GPS_MODEL_NAME_GPS180 "GPS180" -#define GPS_MODEL_NAME_GLN170 "GLN170" -#define GPS_MODEL_NAME_GPS180PEX "GPS180PEX" -#define GPS_MODEL_NAME_TCR180PEX "TCR180PEX" -#define GPS_MODEL_NAME_PZF180PEX "PZF180PEX" -#define GPS_MODEL_NAME_MGR180 "MGR180" -#define GPS_MODEL_NAME_MSF600 "MSF600" -#define GPS_MODEL_NAME_WWVB600 "WWVB600" -#define GPS_MODEL_NAME_JJY600 "JJY600" -#define GPS_MODEL_NAME_GPS180HS "GPS180HS" -#define GPS_MODEL_NAME_GPS180AMC "GPS180AMC" -#define GPS_MODEL_NAME_ESI180 "ESI180" -#define GPS_MODEL_NAME_CPE180 "CPE180" -#define GPS_MODEL_NAME_LNO180 "LNO180" -#define GPS_MODEL_NAME_GRC180 "GRC180" -#define GPS_MODEL_NAME_LIU "LIU" -#define GPS_MODEL_NAME_DCF600HS "DCF600HS" -#define GPS_MODEL_NAME_DCF600RS "DCF600RS" + * CARE MUST BE TAKEN that the name string of bus level devices + * is limited to 9 characters. Longer strings will not fit into + * the name field of the PCPS_DEV_TYPE structure. + */ -/* - * The definition below can be used to initialize - * an array of N_GPS_MODEL type name strings. - * Including the trailing 0, each name must not - * exceed GPS_ID_STR_SIZE chars. +/** @} anchor GPS_MODEL_NAMES */ + + + +/** + * @brief An initializer for a table of device names + * + * Can be used to initialize an array of ::N_GPS_MODEL + * type name strings. + * + * @note Including the trailing 0, each name must not + * exceed ::GPS_ID_STR_SIZE chars. + * + * @see ::GPS_MODEL_CODES + * @see @ref GPS_MODEL_NAMES */ #define DEFAULT_GPS_MODEL_NAMES \ { \ @@ -803,10 +1209,803 @@ enum GPS_MODEL_CODES GPS_MODEL_NAME_GRC180, \ GPS_MODEL_NAME_LIU, \ GPS_MODEL_NAME_DCF600HS, \ - GPS_MODEL_NAME_DCF600RS \ + GPS_MODEL_NAME_DCF600RS, \ + GPS_MODEL_NAME_MRI, \ + GPS_MODEL_NAME_BPE, \ + GPS_MODEL_NAME_GLN180PEX, \ + GPS_MODEL_NAME_N2X, \ + GPS_MODEL_NAME_RSC180, \ + GPS_MODEL_NAME_LNE_GB, \ + GPS_MODEL_NAME_PPG180, \ + GPS_MODEL_NAME_SCG, \ + GPS_MODEL_NAME_MDU300, \ + GPS_MODEL_NAME_SDI, \ + GPS_MODEL_NAME_FDM180, \ + GPS_MODEL_NAME_SPT, \ + GPS_MODEL_NAME_PZF180, \ + GPS_MODEL_NAME_REL1000, \ + GPS_MODEL_NAME_HPS100, \ + GPS_MODEL_NAME_VSG180, \ + GPS_MODEL_NAME_MSF180, \ + GPS_MODEL_NAME_WWVB180, \ + GPS_MODEL_NAME_CPC180, \ + GPS_MODEL_NAME_CTC100, \ + GPS_MODEL_NAME_TCR180, \ + GPS_MODEL_NAME_LUE180, \ + GPS_MODEL_NAME_CPC_01, \ + GPS_MODEL_NAME_TSU_01, \ + GPS_MODEL_NAME_CMC_01, \ + GPS_MODEL_NAME_SCU_01, \ + GPS_MODEL_NAME_FCU_01, \ + GPS_MODEL_NAME_CSM100, \ + GPS_MODEL_NAME_LNE180SFP, \ + GPS_MODEL_NAME_GTS180, \ + GPS_MODEL_NAME_GPS180CSM, \ + GPS_MODEL_NAME_GRC181, \ + GPS_MODEL_NAME_N2X180, \ + GPS_MODEL_NAME_GNS181PEX, \ + GPS_MODEL_NAME_MDU180, \ + GPS_MODEL_NAME_MDU312, \ + GPS_MODEL_NAME_GPS165, \ + GPS_MODEL_NAME_GNS181_UC, \ + GPS_MODEL_NAME_PSX_4GE, \ + GPS_MODEL_NAME_RSC180RDU, \ + GPS_MODEL_NAME_USYNCPWR, \ + GPS_MODEL_NAME_FDM180M, \ + GPS_MODEL_NAME_LSG180, \ + GPS_MODEL_NAME_GPS190, \ + GPS_MODEL_NAME_GNS181, \ + GPS_MODEL_NAME_PIO180, \ + GPS_MODEL_NAME_FCM180, \ + GPS_MODEL_NAME_TCR180USB, \ + GPS_MODEL_NAME_SSP100, \ + GPS_MODEL_NAME_GNS165, \ + GPS_MODEL_NAME_RSC180RDMP, \ + GPS_MODEL_NAME_GPS16X, \ + GPS_MODEL_NAME_MSHPS100 \ } + + +/** + * @brief Definitions used to classify devices and built-in features + * + * @see ::GPS_MODEL_CODES + * @see ::GPS_BUILTIN_FEATURE_BITS + * @see @ref GPS_BUILTIN_FEATURE_MASKS + * + * @anchor GPS_BUILTIN_FEATURE_DEFS @{ */ + + +/** + * @brief A data type to hold a mask of @ref GPS_BUILTIN_FEATURE_MASKS + * + * @see @ref GPS_BUILTIN_FEATURE_MASKS + */ +typedef uint32_t BUILTIN_FEATURE_MASK; + + +/** + * @brief Enumeration of classifiers and built-in features + * + * @see ::GPS_MODEL_CODES + * @see @ref GPS_BUILTIN_FEATURE_MASKS + */ +enum GPS_BUILTIN_FEATURE_BITS +{ + GPS_BIT_MODEL_IS_GPS, + GPS_BIT_MODEL_IS_GNSS, + GPS_BIT_MODEL_IS_TCR, + GPS_BIT_MODEL_IS_DCF_AM, + GPS_BIT_MODEL_IS_DCF_PZF, + GPS_BIT_MODEL_IS_MSF, + GPS_BIT_MODEL_IS_JJY, + GPS_BIT_MODEL_IS_WWVB, + + GPS_BIT_MODEL_IS_BUS_LVL_DEV, + GPS_BIT_MODEL_HAS_BVAR_STAT, + GPS_BIT_MODEL_HAS_POS_XYZ, + GPS_BIT_MODEL_HAS_POS_LLA, + GPS_BIT_MODEL_HAS_TIME_TTM, + GPS_BIT_MODEL_HAS_TZDL, + GPS_BIT_MODEL_HAS_TZCODE, + GPS_BIT_MODEL_HAS_ANT_INFO, + + GPS_BIT_MODEL_HAS_ENABLE_FLAGS, + GPS_BIT_MODEL_HAS_STAT_INFO, + GPS_BIT_MODEL_HAS_ANT_CABLE_LEN, + GPS_BIT_MODEL_HAS_SCU_STAT, + GPS_BIT_MODEL_HAS_SV_INFO, + GPS_BIT_MODEL_HAS_UP_CONV, ///< Instead of a standard L1 antenna, a Meinberg antenna/converter can be used with this GNSS device. + GPS_BIT_MODEL_HAS_MBG_OS, ///< This model can be a management CPU for meinbergOS (i.e. v7) + + GPS_BIT_MODEL_HAS_XMR_HOLDOVER_INTV__REMOVE_THIS, // TODO FIXME + +#if 0 //### TODO This has to be discussed + GPS_BIT_MODEL_IS_LNO, + GPS_BIT_MODEL_IS_SCU, +#endif + + N_GPS_BUILTIN_FEATURE_BITS +}; + + + +/** + * @brief Bit masks associated with classifiers and built-in features + * + * @see ::GPS_MODEL_CODES + * @see ::GPS_BUILTIN_FEATURE_BITS + * + * @anchor GPS_BUILTIN_FEATURE_MASKS @{ */ + +#define GPS_MODEL_IS_GPS ( 1UL << GPS_BIT_MODEL_IS_GPS ) ///< see ::GPS_BIT_MODEL_IS_GPS +#define GPS_MODEL_IS_GNSS ( 1UL << GPS_BIT_MODEL_IS_GNSS ) ///< see ::GPS_BIT_MODEL_IS_GNSS +#define GPS_MODEL_IS_TCR ( 1UL << GPS_BIT_MODEL_IS_TCR ) ///< see ::GPS_BIT_MODEL_IS_TCR +#define GPS_MODEL_IS_DCF_AM ( 1UL << GPS_BIT_MODEL_IS_DCF_AM ) ///< see ::GPS_BIT_MODEL_IS_DCF_AM +#define GPS_MODEL_IS_DCF_PZF ( 1UL << GPS_BIT_MODEL_IS_DCF_PZF ) ///< see ::GPS_BIT_MODEL_IS_DCF_PZF +#define GPS_MODEL_IS_MSF ( 1UL << GPS_BIT_MODEL_IS_MSF ) ///< see ::GPS_BIT_MODEL_IS_MSF +#define GPS_MODEL_IS_JJY ( 1UL << GPS_BIT_MODEL_IS_JJY ) ///< see ::GPS_BIT_MODEL_IS_JJY +#define GPS_MODEL_IS_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 +#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 + +//### TODO: should we use an extra flag? +#define GPS_MODEL_HAS_POS ( GPS_MODEL_HAS_POS_XYZ | GPS_MODEL_HAS_POS_LLA ) + +/** @} anchor GPS_BUILTIN_FEATURE_MASKS */ + + +#if 0 //##++ more potential builtin features and classifiers + + GPS_MODEL_HAS_CFGH | \ + GPS_MODEL_HAS_ALM | \ + GPS_MODEL_HAS_EPH | \ + GPS_MODEL_HAS_UTC | \ + GPS_MODEL_HAS_IONO \ + +#define GPS_MODEL_HAS_AUTO_ON // -- +#define GPS_MODEL_HAS_AUTO_OFF // -- +#define GPS_MODEL_HAS_SW_REV // deprecated, use only if ri not supported +#define GPS_MODEL_HAS_BVAR_STAT // req +#define GPS_MODEL_HAS_POS_XYZ // GPS_MODEL_IS_GPS, GPS_MODEL_HAS_POS, GPS_MODEL_HAS_POS_XYZ ? +#define GPS_MODEL_HAS_POS_LLA // GPS_MODEL_IS_GPS, GPS_MODEL_HAS_POS, GPS_MODEL_HAS_POS_LLA ? +#define GPS_MODEL_HAS_TZDL // req +#define GPS_MODEL_HAS_PORT_PARM // deprecated, use only if ri not supported +#define GPS_MODEL_HAS_SYNTH // ri GPS_HAS_SYNTH +#define GPS_MODEL_HAS_ANT_INFO // GPS_MODEL_IS_GPS, also GNSS, or req? +#define GPS_MODEL_HAS_UCAP // ri n_ucap +#define GPS_MODEL_HAS_ENABLE_FLAGS // req +#define GPS_MODEL_HAS_STAT_INFO // req +#define GPS_MODEL_HAS_SWITCH_PARMS // deprecated, use ... +#define GPS_MODEL_HAS_STRING_PARMS // deprecated, use ... +#define GPS_MODEL_HAS_ANT_CABLE_LEN // GPS_MODEL_IS_GPS, also GNSS, or req? +#define GPS_MODEL_HAS_SYNC_OUTAGE_DELAY // custom +#define GPS_MODEL_HAS_PULSE_INFO // custom +#define GPS_MODEL_HAS_OPT_FEATURES // deprecated, use ri +#define GPS_MODEL_HAS_IRIG_TX_SETTINGS // ri GPS_HAS_IRIG_TX +#define GPS_MODEL_HAS_RECEIVER_INFO // -- +#define GPS_MODEL_HAS_STR_TYPE_INFO_IDX // ri n_str_type +#define GPS_MODEL_HAS_PORT_INFO_IDX // ri n_com +#define GPS_MODEL_HAS_PORT_SETTINGS_IDX // ri n_com +#define GPS_MODEL_HAS_POUT_INFO_IDX // ri n_pout +#define GPS_MODEL_HAS_POUT_SETTINGS_IDX // ri n_pout +#define GPS_MODEL_HAS_IRIG_TX_INFO // ri GPS_HAS_IRIG_TX +#define GPS_MODEL_HAS_MULTI_REF_SETTINGS // ri GPS_HAS_MULTI_REF +#define GPS_MODEL_HAS_MULTI_REF_INFO // ri GPS_HAS_MULTI_REF +#define GPS_MODEL_HAS_ROM_CSUM // ? +#define GPS_MODEL_HAS_MULTI_REF_STATUS // ri ... +#define GPS_MODEL_HAS_RCV_TIMEOUT // ri ... +#define GPS_MODEL_HAS_IRIG_RX_SETTINGS // ri ... +#define GPS_MODEL_HAS_IRIG_RX_INFO // ri ... +#define GPS_MODEL_HAS_REF_OFFS // ri ... +#define GPS_MODEL_HAS_DEBUG_STATUS // +#define GPS_MODEL_HAS_XMR_SETTINGS_IDX // +#define GPS_MODEL_HAS_XMR_INFO_IDX // +#define GPS_MODEL_HAS_XMR_STATUS_IDX // +#define GPS_MODEL_HAS_OPT_SETTINGS // +#define GPS_MODEL_HAS_OPT_INFO // +#define GPS_MODEL_HAS_CLR_UCAP_BUFF // +#define GPS_MODEL_HAS_TIME_SCALE // +#define GPS_MODEL_HAS_NAV_ENG_SETTINGS // +#define GPS_MODEL_HAS_RAW_IRIG_DATA // +#define GPS_MODEL_HAS_GPIO_CFG_LIMITS // +#define GPS_MODEL_HAS_GPIO_INFO_IDX // +#define GPS_MODEL_HAS_GPIO_SETTINGS_IDX // +#define GPS_MODEL_HAS_XMR_INSTANCES // +#define GPS_MODEL_HAS_CLR_EVT_LOG // +#define GPS_MODEL_HAS_NUM_EVT_LOG_ENTRIES // +#define GPS_MODEL_HAS_FIRST_EVT_LOG_ENTRY // +#define GPS_MODEL_HAS_NEXT_EVT_LOG_ENTRY // +#define GPS_MODEL_HAS_LNO_STATUS // +#define GPS_MODEL_HAS_IMS_STATE // +#define GPS_MODEL_HAS_IMS_SENSOR_STATE_IDX // +#define GPS_MODEL_HAS_XMR_HOLDOVER_INTV // +#define GPS_MODEL_HAS_HAVEQUICK_RX_SETTINGS // +#define GPS_MODEL_HAS_HAVEQUICK_RX_INFO // +#define GPS_MODEL_HAS_HAVEQUICK_TX_SETTINGS // +#define GPS_MODEL_HAS_HAVEQUICK_TX_INFO // +#define GPS_MODEL_HAS_PTP_CFG // +#define GPS_MODEL_HAS_PTP_STATE // +#define GPS_MODEL_HAS_PTP_UC_MASTER_CFG_LIMITS // +#define GPS_MODEL_HAS_PTP_UC_MASTER_CFG // +#define GPS_MODEL_HAS_NTP_GLB_CFG // +#define GPS_MODEL_HAS_NTP_CLNT_MODE_CFG // +#define GPS_MODEL_HAS_NTP_SRV_MODE_CFG // +#define GPS_MODEL_HAS_NTP_PEER_SETTINGS_IDX // +#define GPS_MODEL_HAS_NTP_SYS_STATE // +#define GPS_MODEL_HAS_NTP_PEER_STATE_IDX // +#define GPS_MODEL_HAS_SHS // +#define GPS_MODEL_HAS_SHS_STATUS // +#define GPS_MODEL_HAS_NET_GLB_CFG // +#define GPS_MODEL_HAS_NET_DNS_SRVR // +#define GPS_MODEL_HAS_NET_DNS_SRCH_DOM // +#define GPS_MODEL_HAS_NET_STAT_DNS_SRVR // +#define GPS_MODEL_HAS_NET_STAT_DNS_SRCH_DOM // +#define GPS_MODEL_HAS_GNSS_SAT_INFO_IDX // + +#define GPS_MODEL_HAS_CFGH // +#define GPS_MODEL_HAS_ALM // +#define GPS_MODEL_HAS_EPH // +#define GPS_MODEL_HAS_UTC // +#define GPS_MODEL_HAS_IONO // +#define GPS_MODEL_HAS_ASCII_MSG // + +#define GPS_MODEL_HAS_GLNS_ALM // +#define GPS_MODEL_HAS_GNSS_SAT_INFO // +//#define GPS_MODEL_HAS_GNSS_MODE // + +#define GPS_MODEL_HAS_IP4_SETTINGS // +#define GPS_MODEL_HAS_LAN_IF_INFO // +#define GPS_MODEL_HAS_IP4_STATE // + +#define GPS_MODEL_HAS_CRYPTED_PACKET // +#define GPS_MODEL_HAS_CRYPTED_RAW_PACKET // + +#define GPS_MODEL_HAS_SECU_INFO // +#define GPS_MODEL_HAS_SECU_SETTINGS // +#define GPS_MODEL_HAS_SECU_PUBLIC_KEY // + +#endif //##++ more potential builtin features and classifiers + + + +/** + * @brief Common builtin features of all GPS receivers + * + * @see ::BUILTIN_FEAT_GPS_BUS_LVL + * @see ::BUILTIN_FEAT_GNSS + */ +#define BUILTIN_FEAT_GPS \ +( \ + GPS_MODEL_IS_GPS | \ + GPS_MODEL_HAS_BVAR_STAT | \ + GPS_MODEL_HAS_POS_XYZ | \ + GPS_MODEL_HAS_POS_LLA | \ + GPS_MODEL_HAS_TIME_TTM | \ + GPS_MODEL_HAS_TZDL | \ + GPS_MODEL_HAS_ANT_INFO | \ + GPS_MODEL_HAS_ENABLE_FLAGS | \ + GPS_MODEL_HAS_STAT_INFO | \ + GPS_MODEL_HAS_ANT_CABLE_LEN | \ + GPS_MODEL_HAS_SV_INFO \ +) + + +/** + * @brief Common builtin features of all GNSS receivers + * + * GNSS includes GPS but optionally other satellite systems, + * and the associated API. + * + * @see ::BUILTIN_FEAT_GNSS_BUS_LVL + * @see ::BUILTIN_FEAT_GPS + */ +#define BUILTIN_FEAT_GNSS \ +( \ + BUILTIN_FEAT_GPS | \ + GPS_MODEL_IS_GNSS \ +) + + + +/** + * @brief Common builtin features of all simple TCR devices + */ +#define BUILTIN_FEAT_TCR_1 \ +( \ + GPS_MODEL_IS_TCR \ +) + + +/** + * @brief Common builtin features of all enhanced TCR devices + */ +#define BUILTIN_FEAT_TCR_2 \ +( \ + GPS_MODEL_IS_TCR | \ + GPS_MODEL_HAS_TIME_TTM | \ + GPS_MODEL_HAS_TZDL | \ + GPS_MODEL_HAS_ANT_INFO | \ + GPS_MODEL_HAS_ENABLE_FLAGS \ +) + + + +/** + * @brief Common builtin features of all simple DCF77 AM receivers + */ +#define BUILTIN_FEAT_DCF_1 \ +( \ + GPS_MODEL_IS_DCF_AM | \ + GPS_MODEL_HAS_TZCODE \ +) + + +/** + * @brief Common builtin features of all enhanced DCF77 AM receivers + */ +#define BUILTIN_FEAT_DCF_2 \ +( \ + GPS_MODEL_IS_DCF_AM | \ + GPS_MODEL_HAS_TIME_TTM | \ + GPS_MODEL_HAS_TZDL | \ + GPS_MODEL_HAS_ANT_INFO | \ + GPS_MODEL_HAS_ENABLE_FLAGS \ +) + + +/** + * @brief Common builtin features of all simple DCF77 PZF receivers + */ +#define BUILTIN_FEAT_DCF_PZF_1 \ +( \ + GPS_MODEL_IS_DCF_PZF | \ + GPS_MODEL_HAS_TZCODE \ +) + + +/** + * @brief Common builtin features of all enhanced DCF77 PZF receivers + */ +#define BUILTIN_FEAT_DCF_PZF_2 \ +( \ + GPS_MODEL_IS_DCF_AM | \ + GPS_MODEL_IS_DCF_PZF | \ + GPS_MODEL_HAS_TIME_TTM | \ + GPS_MODEL_HAS_TZDL | \ + GPS_MODEL_HAS_ANT_INFO | \ + GPS_MODEL_HAS_ENABLE_FLAGS \ +) + + + +/** + * @brief Common builtin features of all simple MSF receivers + */ +#define BUILTIN_FEAT_MSF_1 \ +( \ + GPS_MODEL_IS_MSF | \ + GPS_MODEL_HAS_TZCODE \ +) + + +/** + * @brief Common builtin features of all enhanced MSF receivers + */ +#define BUILTIN_FEAT_MSF_2 \ +( \ + GPS_MODEL_IS_MSF | \ + GPS_MODEL_HAS_TIME_TTM | \ + GPS_MODEL_HAS_TZDL | \ + GPS_MODEL_HAS_ANT_INFO | \ + GPS_MODEL_HAS_ENABLE_FLAGS \ +) + + + +/** + * @brief Common builtin features of all simple WWVB receivers + */ +#define BUILTIN_FEAT_WVB_1 \ +( \ + GPS_MODEL_IS_WWVB | \ + GPS_MODEL_HAS_TZCODE \ +) + + +/** + * @brief Common builtin features of all enhanced WWVB receivers + */ +#define BUILTIN_FEAT_WVB_2 \ +( \ + GPS_MODEL_IS_WWVB | \ + GPS_MODEL_HAS_TZDL \ +) + + + +/** + * @brief Common builtin features of all simple JJY receivers + */ +#define BUILTIN_FEAT_JJY_1 \ +( \ + GPS_MODEL_IS_JJY | \ + GPS_MODEL_HAS_TZCODE \ +) + + + +/** + * @brief Common builtin features of all N2X devices + */ +#define BUILTIN_FEAT_COMM_N2X \ +( \ + GPS_MODEL_HAS_TIME_TTM | \ + GPS_MODEL_HAS_TZDL | \ + GPS_MODEL_HAS_ENABLE_FLAGS \ +) + + + +/** + * @brief Common builtin features of all bus-level GPS receivers + */ +#define BUILTIN_FEAT_GPS_BUS_LVL ( BUILTIN_FEAT_GPS | GPS_MODEL_IS_BUS_LVL_DEV ) + + +/** + * @brief Common builtin features of all bus-level GNSS receivers + */ +#define BUILTIN_FEAT_GNSS_BUS_LVL ( BUILTIN_FEAT_GNSS | GPS_MODEL_IS_BUS_LVL_DEV ) + + +/** + * @brief Common builtin features of all simple, bus-level TCR devices + */ +#define BUILTIN_FEAT_TCR_1_BUS_LVL ( BUILTIN_FEAT_TCR_1 | GPS_MODEL_IS_BUS_LVL_DEV ) + +/** + * @brief Common builtin features of all enhanced, bus-level TCR devices + */ +#define BUILTIN_FEAT_TCR_2_BUS_LVL ( BUILTIN_FEAT_TCR_2 | GPS_MODEL_IS_BUS_LVL_DEV ) + + +/** + * @brief Common builtin features of all simple, bus-level DCF77 AM receivers + */ +#define BUILTIN_FEAT_DCF_1_BUS_LVL ( BUILTIN_FEAT_DCF_1 | GPS_MODEL_IS_BUS_LVL_DEV ) + +/** + * @brief Common builtin features of all enhanced, bus-level DCF77 AM receivers + */ +#define BUILTIN_FEAT_DCF_2_BUS_LVL ( BUILTIN_FEAT_DCF_2 | GPS_MODEL_IS_BUS_LVL_DEV ) + +/** + * @brief Common builtin features of all enhanced, bus-level DCF77 PZF receivers + */ +#define BUILTIN_FEAT_DCF_PZF_2_BUS_LVL ( BUILTIN_FEAT_DCF_PZF_2 | GPS_MODEL_IS_BUS_LVL_DEV ) + + + +/** + * @brief Definitions of builtin features per device type + * + * @see ::GPS_MODEL_CODES + * @see @ref GPS_MODEL_BUILTIN_FEATURES + * + * @anchor GPS_MODEL_BUILTIN_FEATURE_MASKS @{ */ + +#define BUILTIN_FEAT_GPS166 ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GPS167 ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GPS167SV ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GPS167PC ( BUILTIN_FEAT_GPS_BUS_LVL ) +#define BUILTIN_FEAT_GPS167PCI ( BUILTIN_FEAT_GPS_BUS_LVL ) +#define BUILTIN_FEAT_GPS163 ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GPS168PCI ( BUILTIN_FEAT_GPS_BUS_LVL ) +#define BUILTIN_FEAT_GPS161 ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GPS169PCI ( BUILTIN_FEAT_GPS_BUS_LVL ) +#define BUILTIN_FEAT_TCR167PCI ( BUILTIN_FEAT_TCR_2_BUS_LVL ) +#define BUILTIN_FEAT_GPS164 ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GPS170PCI ( BUILTIN_FEAT_GPS_BUS_LVL ) +#define BUILTIN_FEAT_PZF511 ( BUILTIN_FEAT_DCF_PZF_1 ) +#define BUILTIN_FEAT_GPS170 ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_TCR511 ( BUILTIN_FEAT_TCR_1_BUS_LVL | GPS_MODEL_HAS_TIME_TTM ) //### TODO Or full TCR_2? +#define BUILTIN_FEAT_AM511 ( BUILTIN_FEAT_DCF_1 ) +#define BUILTIN_FEAT_MSF511 ( BUILTIN_FEAT_MSF_1 ) +#define BUILTIN_FEAT_GRC170 ( BUILTIN_FEAT_GNSS ) +#define BUILTIN_FEAT_GPS170PEX ( BUILTIN_FEAT_GPS_BUS_LVL ) +#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_TCR170PEX ( BUILTIN_FEAT_TCR_2_BUS_LVL ) +#define BUILTIN_FEAT_WWVB511 ( BUILTIN_FEAT_WVB_1 ) +#define BUILTIN_FEAT_MGR170 ( 0 ) +#define BUILTIN_FEAT_JJY511 ( BUILTIN_FEAT_JJY_1 ) +#define BUILTIN_FEAT_PZF600 ( BUILTIN_FEAT_DCF_PZF_1 ) //### TODO Or full PZF_2? +#define BUILTIN_FEAT_TCR600 ( BUILTIN_FEAT_TCR_1 | GPS_MODEL_HAS_TIME_TTM ) //### TODO Or full TCR_2? +#define BUILTIN_FEAT_GPS180 ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GLN170 ( BUILTIN_FEAT_GNSS) +#define BUILTIN_FEAT_GPS180PEX ( BUILTIN_FEAT_GPS_BUS_LVL ) +#define BUILTIN_FEAT_TCR180PEX ( BUILTIN_FEAT_TCR_2_BUS_LVL ) +#define BUILTIN_FEAT_PZF180PEX ( BUILTIN_FEAT_DCF_PZF_2_BUS_LVL ) +#define BUILTIN_FEAT_MGR180 ( 0 ) +#define BUILTIN_FEAT_MSF600 ( BUILTIN_FEAT_MSF_1 ) //### TODO Or full MSF_2? +#define BUILTIN_FEAT_WWVB600 ( BUILTIN_FEAT_WVB_1 ) //### TODO Or full WVB_2? +#define BUILTIN_FEAT_JJY600 ( BUILTIN_FEAT_JJY_1 ) //### TODO Or full JJY_2? +#define BUILTIN_FEAT_GPS180HS ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GPS180AMC ( BUILTIN_FEAT_GPS_BUS_LVL ) +#define BUILTIN_FEAT_ESI180 ( 0 ) +#define BUILTIN_FEAT_CPE180 ( 0 ) +#define BUILTIN_FEAT_LNO180 ( 0 ) +#define BUILTIN_FEAT_GRC180 ( BUILTIN_FEAT_GNSS ) +#define BUILTIN_FEAT_LIU ( 0 ) +#define BUILTIN_FEAT_DCF600HS ( BUILTIN_FEAT_DCF_2 ) //### TODO +#define BUILTIN_FEAT_DCF600RS ( BUILTIN_FEAT_DCF_2 ) //### TODO +#define BUILTIN_FEAT_MRI ( 0 ) +#define BUILTIN_FEAT_BPE ( 0 ) +#define BUILTIN_FEAT_GLN180PEX ( BUILTIN_FEAT_GNSS_BUS_LVL ) +#define BUILTIN_FEAT_N2X ( BUILTIN_FEAT_COMM_N2X ) +#define BUILTIN_FEAT_RSC180 ( GPS_MODEL_HAS_SCU_STAT ) +#define BUILTIN_FEAT_LNE_GB ( 0 ) +#define BUILTIN_FEAT_PPG180 ( 0 ) +#define BUILTIN_FEAT_SCG ( 0 ) +#define BUILTIN_FEAT_MDU300 ( 0 ) +#define BUILTIN_FEAT_SDI ( 0 ) +#define BUILTIN_FEAT_FDM180 ( GPS_MODEL_HAS_TZDL | GPS_MODEL_HAS_ENABLE_FLAGS ) +#define BUILTIN_FEAT_SPT ( 0 ) +#define BUILTIN_FEAT_PZF180 ( BUILTIN_FEAT_DCF_PZF_2 ) +#define BUILTIN_FEAT_REL1000 ( 0 ) +#define BUILTIN_FEAT_HPS100 ( 0 ) +#define BUILTIN_FEAT_VSG180 ( GPS_MODEL_HAS_TZDL ) +#define BUILTIN_FEAT_MSF180 ( BUILTIN_FEAT_MSF_2 ) +#define BUILTIN_FEAT_WWVB180 ( BUILTIN_FEAT_WVB_2 ) +#define BUILTIN_FEAT_CPC180 ( 0 ) +#define BUILTIN_FEAT_CTC100 ( GPS_MODEL_HAS_MBG_OS ) +#define BUILTIN_FEAT_TCR180 ( BUILTIN_FEAT_TCR_2 ) +#define BUILTIN_FEAT_LUE180 ( 0 ) +#define BUILTIN_FEAT_CPC_01 ( 0 ) +#define BUILTIN_FEAT_TSU_01 ( 0 ) +#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_LNE180SFP ( 0 ) +#define BUILTIN_FEAT_GTS180 ( 0 ) +#define BUILTIN_FEAT_GPS180CSM ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GRC181 ( BUILTIN_FEAT_GNSS ) +#define BUILTIN_FEAT_N2X180 ( BUILTIN_FEAT_COMM_N2X ) +#define BUILTIN_FEAT_GNS181PEX ( BUILTIN_FEAT_GNSS_BUS_LVL ) +#define BUILTIN_FEAT_MDU180 ( GPS_MODEL_HAS_SCU_STAT ) +#define BUILTIN_FEAT_MDU312 ( 0 ) +#define BUILTIN_FEAT_GPS165 ( BUILTIN_FEAT_GPS ) +#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_FDM180M ( GPS_MODEL_HAS_TZDL | GPS_MODEL_HAS_ENABLE_FLAGS ) +#define BUILTIN_FEAT_LSG180 ( 0 ) +#define BUILTIN_FEAT_GPS190 ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GNS181 ( BUILTIN_FEAT_GNSS ) +#define BUILTIN_FEAT_PIO180 ( 0 ) +#define BUILTIN_FEAT_FCM180 ( 0 ) +#define BUILTIN_FEAT_TCR180USB ( 0 ) +#define BUILTIN_FEAT_SSP100 ( GPS_MODEL_HAS_MBG_OS ) +#define BUILTIN_FEAT_GNS165 ( BUILTIN_FEAT_GNSS ) +#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 ) + +/** + * @brief Feature mask used for legacy devices + * + * This code is used to set builtin feature flags + * legacy devices not listed here, so we can simply + * search for ::BUILTIN_FEAT_UNDEFINED to identify + * such devices. The numeric value is just 0, though. + */ +#define BUILTIN_FEAT_UNDEFINED ( 0 ) + +/** @} anchor GPS_MODEL_BUILTIN_FEATURE_MASKS */ + + + +#if !defined( MBG_TGT_DOS ) + +/** + * @brief Initializer for a table of built-in features per device + * + * Last entry is all zero to indicated end of table. + * + * @see ::GPS_MODEL_CODES + * @see @ref GPS_MODEL_BUILTIN_FEATURE_MASKS + */ +#define GPS_MODEL_BUILTIN_FEATURES \ +{ \ + { GPS_MODEL_GPS166, BUILTIN_FEAT_GPS166 }, \ + { GPS_MODEL_GPS167, BUILTIN_FEAT_GPS167 }, \ + { GPS_MODEL_GPS167SV, BUILTIN_FEAT_GPS167SV }, \ + { GPS_MODEL_GPS167PC, BUILTIN_FEAT_GPS167PC }, \ + { GPS_MODEL_GPS167PCI, BUILTIN_FEAT_GPS167PCI }, \ + { GPS_MODEL_GPS163, BUILTIN_FEAT_GPS163 }, \ + { GPS_MODEL_GPS168PCI, BUILTIN_FEAT_GPS168PCI }, \ + { GPS_MODEL_GPS161, BUILTIN_FEAT_GPS161 }, \ + { GPS_MODEL_GPS169PCI, BUILTIN_FEAT_GPS169PCI }, \ + { GPS_MODEL_TCR167PCI, BUILTIN_FEAT_TCR167PCI }, \ + { GPS_MODEL_GPS164, BUILTIN_FEAT_GPS164 }, \ + { GPS_MODEL_GPS170PCI, BUILTIN_FEAT_GPS170PCI }, \ + { GPS_MODEL_PZF511, BUILTIN_FEAT_PZF511 }, \ + { GPS_MODEL_GPS170, BUILTIN_FEAT_GPS170 }, \ + { GPS_MODEL_TCR511, BUILTIN_FEAT_TCR511 }, \ + { GPS_MODEL_AM511, BUILTIN_FEAT_AM511 }, \ + { GPS_MODEL_MSF511, BUILTIN_FEAT_MSF511 }, \ + { GPS_MODEL_GRC170, BUILTIN_FEAT_GRC170 }, \ + { GPS_MODEL_GPS170PEX, BUILTIN_FEAT_GPS170PEX }, \ + { GPS_MODEL_GPS162, BUILTIN_FEAT_GPS162 }, \ + { GPS_MODEL_PTP270PEX, BUILTIN_FEAT_PTP270PEX }, \ + { GPS_MODEL_FRC511PEX, BUILTIN_FEAT_FRC511PEX }, \ + { GPS_MODEL_GEN170, BUILTIN_FEAT_GEN170 }, \ + { GPS_MODEL_TCR170PEX, BUILTIN_FEAT_TCR170PEX }, \ + { GPS_MODEL_WWVB511, BUILTIN_FEAT_WWVB511 }, \ + { GPS_MODEL_MGR170, BUILTIN_FEAT_MGR170 }, \ + { GPS_MODEL_JJY511, BUILTIN_FEAT_JJY511 }, \ + { GPS_MODEL_PZF600, BUILTIN_FEAT_PZF600 }, \ + { GPS_MODEL_TCR600, BUILTIN_FEAT_TCR600 }, \ + { GPS_MODEL_GPS180, BUILTIN_FEAT_GPS180 }, \ + { GPS_MODEL_GLN170, BUILTIN_FEAT_GLN170 }, \ + { GPS_MODEL_GPS180PEX, BUILTIN_FEAT_GPS180PEX }, \ + { GPS_MODEL_TCR180PEX, BUILTIN_FEAT_TCR180PEX }, \ + { GPS_MODEL_PZF180PEX, BUILTIN_FEAT_PZF180PEX }, \ + { GPS_MODEL_MGR180, BUILTIN_FEAT_MGR180 }, \ + { GPS_MODEL_MSF600, BUILTIN_FEAT_MSF600 }, \ + { GPS_MODEL_WWVB600, BUILTIN_FEAT_WWVB600 }, \ + { GPS_MODEL_JJY600, BUILTIN_FEAT_JJY600 }, \ + { GPS_MODEL_GPS180HS, BUILTIN_FEAT_GPS180HS }, \ + { GPS_MODEL_GPS180AMC, BUILTIN_FEAT_GPS180AMC }, \ + { GPS_MODEL_ESI180, BUILTIN_FEAT_ESI180 }, \ + { GPS_MODEL_CPE180, BUILTIN_FEAT_CPE180 }, \ + { GPS_MODEL_LNO180, BUILTIN_FEAT_LNO180 }, \ + { GPS_MODEL_GRC180, BUILTIN_FEAT_GRC180 }, \ + { GPS_MODEL_LIU, BUILTIN_FEAT_LIU }, \ + { GPS_MODEL_DCF600HS, BUILTIN_FEAT_DCF600HS }, \ + { GPS_MODEL_DCF600RS, BUILTIN_FEAT_DCF600RS }, \ + { GPS_MODEL_MRI, BUILTIN_FEAT_MRI }, \ + { GPS_MODEL_BPE, BUILTIN_FEAT_BPE }, \ + { GPS_MODEL_GLN180PEX, BUILTIN_FEAT_GLN180PEX }, \ + { GPS_MODEL_N2X, BUILTIN_FEAT_N2X }, \ + { GPS_MODEL_RSC180, BUILTIN_FEAT_RSC180 }, \ + { GPS_MODEL_LNE_GB, BUILTIN_FEAT_LNE_GB }, \ + { GPS_MODEL_PPG180, BUILTIN_FEAT_PPG180 }, \ + { GPS_MODEL_SCG, BUILTIN_FEAT_SCG }, \ + { GPS_MODEL_MDU300, BUILTIN_FEAT_MDU300 }, \ + { GPS_MODEL_SDI, BUILTIN_FEAT_SDI }, \ + { GPS_MODEL_FDM180, BUILTIN_FEAT_FDM180 }, \ + { GPS_MODEL_SPT, BUILTIN_FEAT_SPT }, \ + { GPS_MODEL_PZF180, BUILTIN_FEAT_PZF180 }, \ + { GPS_MODEL_REL1000, BUILTIN_FEAT_REL1000 }, \ + { GPS_MODEL_HPS100, BUILTIN_FEAT_HPS100 }, \ + { GPS_MODEL_VSG180, BUILTIN_FEAT_VSG180 }, \ + { GPS_MODEL_MSF180, BUILTIN_FEAT_MSF180 }, \ + { GPS_MODEL_WWVB180, BUILTIN_FEAT_WWVB180 }, \ + { GPS_MODEL_CPC180, BUILTIN_FEAT_CPC180 }, \ + { GPS_MODEL_CTC100, BUILTIN_FEAT_CTC100 }, \ + { GPS_MODEL_TCR180, BUILTIN_FEAT_TCR180 }, \ + { GPS_MODEL_LUE180, BUILTIN_FEAT_LUE180 }, \ + { GPS_MODEL_CPC_01, BUILTIN_FEAT_CPC_01 }, \ + { GPS_MODEL_TSU_01, BUILTIN_FEAT_TSU_01 }, \ + { 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_LNE180SFP, BUILTIN_FEAT_LNE180SFP }, \ + { GPS_MODEL_GTS180, BUILTIN_FEAT_GTS180 }, \ + { GPS_MODEL_GPS180CSM, BUILTIN_FEAT_GPS180CSM }, \ + { GPS_MODEL_GRC181, BUILTIN_FEAT_GRC181 }, \ + { GPS_MODEL_N2X180, BUILTIN_FEAT_N2X180 }, \ + { GPS_MODEL_GNS181PEX, BUILTIN_FEAT_GNS181PEX }, \ + { GPS_MODEL_MDU180, BUILTIN_FEAT_MDU180 }, \ + { GPS_MODEL_MDU312, BUILTIN_FEAT_MDU312 }, \ + { GPS_MODEL_GPS165, BUILTIN_FEAT_GPS165 }, \ + { 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_FDM180M, BUILTIN_FEAT_FDM180M }, \ + { GPS_MODEL_LSG180, BUILTIN_FEAT_LSG180 }, \ + { GPS_MODEL_GPS190, BUILTIN_FEAT_GPS190 }, \ + { GPS_MODEL_GNS181, BUILTIN_FEAT_GNS181 }, \ + { GPS_MODEL_PIO180, BUILTIN_FEAT_PIO180 }, \ + { GPS_MODEL_FCM180, BUILTIN_FEAT_FCM180 }, \ + { GPS_MODEL_TCR180USB, BUILTIN_FEAT_TCR180USB }, \ + { GPS_MODEL_SSP100, BUILTIN_FEAT_SSP100 }, \ + { GPS_MODEL_GNS165, BUILTIN_FEAT_GNS165 }, \ + { GPS_MODEL_RSC180RDMP, BUILTIN_FEAT_RSC180RDMP }, \ + { GPS_MODEL_GPS16X, BUILTIN_FEAT_GPS16X }, \ + { GPS_MODEL_MSHPS100, BUILTIN_FEAT_MSHPS100 }, \ + { 0, 0 } \ +} + +#endif // !defined( MBG_TGT_DOS ) + +/** @} anchor GPS_BUILTIN_FEATURE_DEFS */ + + + +/** + * @brief Initialize a ::RECEIVER_INFO structure for legacy DCF77 receivers + * + * Legacy DCF77 receivers may not provide a ::RECEIVER_INFO structure, + * but have well-known properties which can be used to set up a + * default ::RECEIVER_INFO. + * + * @param[in,out] _p Pointer to a ::RECEIVER_INFO STRUCTURE to be set up + * @param[in] _pdev Pointer to a ::PCPS_DEV structure read before + * + * @see ::_setup_default_receiver_info_gps + */ +#define _setup_default_receiver_info_dcf( _p, _pdev ) \ +do \ +{ \ + memset( (_p), 0, sizeof( *(_p) ) ); \ + \ + (_p)->ticks_per_sec = DEFAULT_GPS_TICKS_PER_SEC; \ + (_p)->n_ucaps = 0; \ + (_p)->n_com_ports = _pcps_has_serial( _pdev ) ? 1 : 0; \ + (_p)->n_str_type = ( (_p)->n_com_ports != 0 ) ? \ + DEFAULT_N_STR_TYPE_DCF : 0; \ +} while ( 0 ) + + + +/** + * @brief Initialize a ::RECEIVER_INFO structure for legacy GPS receivers + * + * Legacy GPS receivers may not provide a ::RECEIVER_INFO structure, + * but have well-known properties which can be used to set up a + * default ::RECEIVER_INFO. + * + * @param[in,out] _p Pointer to a ::RECEIVER_INFO STRUCTURE to be set up + * + * @see ::_setup_default_receiver_info_dcf + */ +#define _setup_default_receiver_info_gps( _p ) \ +do \ +{ \ + memset( (_p), 0, sizeof( *(_p) ) ); \ + \ + (_p)->ticks_per_sec = DEFAULT_GPS_TICKS_PER_SEC; \ + (_p)->n_ucaps = 2; \ + (_p)->n_com_ports = DEFAULT_N_COM; \ + (_p)->n_str_type = DEFAULT_N_STR_TYPE_GPS; \ +} while ( 0 ) + + + /* * The macros below can be used to classify a receiver, * e.g. depending on the time source and/or depending on @@ -815,11 +2014,11 @@ enum GPS_MODEL_CODES #define _mbg_rcvr_is_plug_in( _p_ri ) \ ( strstr( (_p_ri)->model_name, "PC" ) || \ - ( strstr( (_p_ri)->model_name, "PEX" ) ) + strstr( (_p_ri)->model_name, "PEX" ) ) #define _mbg_rcvr_is_gps( _p_ri ) \ ( strstr( (_p_ri)->model_name, "GPS" ) || \ - ( strstr( (_p_ri)->model_name, "MGR" ) ) + strstr( (_p_ri)->model_name, "MGR" ) ) #define _mbg_rcvr_is_mobile_gps( _p_ri ) \ ( strstr( (_p_ri)->model_name, "MGR" ) ) @@ -869,7 +2068,7 @@ enum GPS_MODEL_CODES #define _mbg_rcvr_is_glonass( _p_ri ) \ ( strstr( (_p_ri)->model_name, "GRC" ) || \ - ( strstr( (_p_ri)->model_name, "GLN" ) ) + strstr( (_p_ri)->model_name, "GLN" ) ) #define _mbg_rcvr_is_glonass_plug_in( _p_ri ) \ ( _mbg_rcvr_is_glonass( _p_ri ) && \ @@ -883,11 +2082,15 @@ enum GPS_MODEL_CODES _mbg_rcvr_is_plug_in( _p_ri ) ) + /** - * @brief Oscillator classification codes used with RECEIVER_INFO::osc_type + * @brief Known oscillator types used with ::RECEIVER_INFO::osc_type + * + * The sequence of codes does NOT reflect the order of quality. + * New oscillator type codes will just be appended to the enumeration. * - * New codes will just be appended to the enumeration, so the sequence - * of codes does NOT reflect the order of quality. + * @see ::DEFAULT_GPS_OSC_NAMES + * @see ::DEFAULT_GPS_OSC_QUALITY_IDX */ enum GPS_OSC_TYPES { @@ -901,14 +2104,19 @@ enum GPS_OSC_TYPES GPS_OSC_RUBIDIUM, GPS_OSC_TCXO_MQ, GPS_OSC_OCXO_DHQ, + GPS_OSC_OCXO_SQ, N_GPS_OSC }; -/* - * The sequence and number of oscillator names - * listed below must correspond to the enumeration - * above: +/** + * @brief Oscillator type name string initializer + * + * The sequence and number of oscillator names has to + * correspond to the enumeration in ::GPS_OSC_TYPES + * + * @see ::GPS_OSC_TYPES + * @see ::DEFAULT_GPS_OSC_QUALITY_IDX */ #define DEFAULT_GPS_OSC_NAMES \ { \ @@ -921,15 +2129,21 @@ enum GPS_OSC_TYPES "OCXO XHQ", \ "RUBIDIUM", \ "TCXO MQ", \ - "OCXO DHQ" \ + "OCXO DHQ", \ + "OCXO SQ" \ } -/* - * The initializer below can be used to initialize - * an array (e.g. "int osc_quality_idx[N_GPS_OSC]") - * which allows to display the oscillator types - * ordered by quality: +/** + * @brief Oscillator quality index + * + * Can be used to initialize a index array + * (e.g. "int osc_quality_idx[N_GPS_OSC];") + * allowing to display the oscillator types + * ordered by quality + * + * @see ::GPS_OSC_TYPES + * @see ::DEFAULT_GPS_OSC_NAMES */ #define DEFAULT_GPS_OSC_QUALITY_IDX \ { \ @@ -938,6 +2152,7 @@ enum GPS_OSC_TYPES GPS_OSC_TCXO_MQ, \ GPS_OSC_TCXO_HQ, \ GPS_OSC_OCXO_LQ, \ + GPS_OSC_OCXO_SQ, \ GPS_OSC_OCXO_MQ, \ GPS_OSC_OCXO_HQ, \ GPS_OSC_OCXO_DHQ, \ @@ -948,9 +2163,20 @@ enum GPS_OSC_TYPES /** - * @brief Enumeration of device features flags reported in RECEIVER_INFO::features + * @brief Enumeration of device features flags reported in ::RI_FEATURES + * + * Used with ::RECEIVER_INFO::features. Each flags indicates if a device + * supports the associated feature, but due to the limited bit size of + * the ::RI_FEATURES type the number of these features is limited to 32. + * + * To extend the number of possible features the ::MBG_XFEATURE_BITS, the + * ::MBG_XFEATURE_BUFFER structure and associated definitions have been + * introduced, which are supported by devices which have ::GPS_HAS_XFEATURE + * set in ::RI_FEATURES. * - * Each flags indicates if a device supports the associated feature. + * @see ::RI_FEATURES + * @see ::MBG_XFEATURE_BITS + * @see ::MBG_XFEATURE_BUFFER */ enum GPS_FEATURE_BITS { @@ -960,42 +2186,46 @@ enum GPS_FEATURE_BITS GPS_FEAT_DCFMARKS, ///< has DCF77 compatible time mark output GPS_FEAT_IRIG_TX, ///< has on-board IRIG output GPS_FEAT_IRIG_RX, ///< has on-board IRIG input - GPS_FEAT_LAN_IP4, ///< has LAN IPv4 interface - GPS_FEAT_MULTI_REF, ///< has multiple input sources with priorities + GPS_FEAT_LAN_IP4, ///< has simple LAN IPv4 interface, superseded by ::GPS_FEAT_NET_CFG + GPS_FEAT_MULTI_REF, ///< has multiple input sources with priorities, superseded by ::GPS_FEAT_XMULTI_REF GPS_FEAT_RCV_TIMEOUT, ///< timeout after GPS reception has stopped - GPS_FEAT_IGNORE_LOCK, ///< supports "ignore lock", MBG_OPT_BIT_EMU_SYNC can be set alternatively + GPS_FEAT_IGNORE_LOCK, ///< supports "ignore lock", ::MBG_OPT_BIT_EMU_SYNC can be set alternatively GPS_FEAT_5_MHZ, ///< output 5 MHz rather than 100 kHz - GPS_FEAT_XMULTI_REF, ///< has extended multiple input source configuration - GPS_FEAT_OPT_SETTINGS, ///< supports MBG_OPT_SETTINGS + GPS_FEAT_XMULTI_REF, ///< has extended multiple input source configuration, supersedes ::GPS_FEAT_MULTI_REF + GPS_FEAT_OPT_SETTINGS, ///< supports ::MBG_OPT_SETTINGS GPS_FEAT_TIME_SCALE, ///< supports configurable time scale (%UTC, TAI, GPS, ...) - GPS_FEAT_IRIG_CTRL_BITS, ///< supports IRIG control bits + GPS_FEAT_IRIG_CTRL_BITS, ///< supports IRIG control bits (::MBG_IRIG_CTRL_BITS) GPS_FEAT_PTP, ///< has PTP support GPS_FEAT_NAV_ENGINE_SETTINGS, ///< supports navigation engine configuration - GPS_FEAT_RAW_IRIG_DATA, ///< supports reading raw IRIG input data - GPS_FEAT_RAW_IRIG_TIME, ///< supports reading decoded IRIG time + GPS_FEAT_RAW_IRIG_DATA, ///< supports reading raw IRIG input data (::MBG_RAW_IRIG_DATA) + GPS_FEAT_RAW_IRIG_TIME, ///< supports reading decoded IRIG time (::PCPS_IRIG_TIME) GPS_FEAT_PTP_UNICAST, ///< has PTP Unicast support - GPS_FEAT_GPIO, ///< has general purpose in/outputs - GPS_FEAT_XMRS_MULT_INSTC, ///< multiple XMRS instances of the same ref type supported, see ::XMRSF_BIT_MULT_INSTC_SUPP + GPS_FEAT_GPIO, ///< has general purpose inputs/outputs + GPS_FEAT_XMRS_MULT_INSTC, ///< multiple XMRS instances of the same ref type supported (::XMULTI_REF_INSTANCES) GPS_FEAT_10MHZ_DISBD, ///< 10 MHz output is always disabled GPS_FEAT_EVT_LOG, ///< Event logging supported - GPS_FEAT_IMS, ///< Support IMS data structures - GPS_FEAT_HAVEQUICK, ///< Support HaveQuick structures - - N_GPS_FEATURE ///< the number of valid features - /* - * If new features are added then care must be taken to update the associated - * definitions below accordingly, e.g. string initializers and bit masks. - */ + GPS_FEAT_IMS, ///< supports IMS data structures + GPS_FEAT_HAVEQUICK, ///< supports HaveQuick structures + GPS_FEAT_NTP, ///< supports NTP structures + GPS_FEAT_NET_CFG, ///< supports extended network interface configuration, supersedes ::GPS_FEAT_LAN_IP4 + GPS_FEAT_VST, ///< supports VST (Versatile Storage) API and structures + GPS_FEAT_SHS, ///< supports SHS (Secure Hybrid System) API and structures + GPS_FEAT_XBP, ///< supports XBP (eXtended Binary Protocol) API and structures, see @ref group_xbp + GPS_FEAT_XFEATURE, ///< support eXtended features, see @ref group_xfeature + N_GPS_FEATURE ///< the number of known ::GPS_FEATURE_BITS, should now be at its limit, i.e. 32. + + // WARNING: There are no more unassigned feature bits available here. + // New features have to be defined using the ::MBG_XFEATURE_BITS }; /** * @brief Names of device features * - * @see GPS_FEATURE_BITS + * @see ::GPS_FEATURE_BITS */ #define DEFAULT_GPS_FEATURE_NAMES \ { \ @@ -1024,51 +2254,210 @@ enum GPS_FEATURE_BITS "10 MHz Output Disabled", \ "Event Logging", \ "IMS data", \ - "HaveQuick" \ + "HaveQuick", \ + "NTP", \ + "Ext. Network Config", \ + "Versatile Storage", \ + "SHS", \ + "Extended Binary Protocol", \ + "Extended Features" \ +} + + +/** + * @brief Bit masks used with ::RECEIVER_INFO::features + * + * @see ::GPS_FEATURE_BITS + * + * @anchor GPS_FEATURE_MASKS @{ */ + +#define GPS_HAS_PPS ( 1UL << GPS_FEAT_PPS ) ///< see ::GPS_FEAT_PPS +#define GPS_HAS_PPM ( 1UL << GPS_FEAT_PPM ) ///< see ::GPS_FEAT_PPM +#define GPS_HAS_SYNTH ( 1UL << GPS_FEAT_SYNTH ) ///< see ::GPS_FEAT_SYNTH +#define GPS_HAS_DCFMARKS ( 1UL << GPS_FEAT_DCFMARKS ) ///< see ::GPS_FEAT_DCFMARKS +#define GPS_HAS_IRIG_TX ( 1UL << GPS_FEAT_IRIG_TX ) ///< see ::GPS_FEAT_IRIG_TX +#define GPS_HAS_IRIG_RX ( 1UL << GPS_FEAT_IRIG_RX ) ///< see ::GPS_FEAT_IRIG_RX +#define GPS_HAS_LAN_IP4 ( 1UL << GPS_FEAT_LAN_IP4 ) ///< see ::GPS_FEAT_LAN_IP4 +#define GPS_HAS_MULTI_REF ( 1UL << GPS_FEAT_MULTI_REF ) ///< see ::GPS_FEAT_MULTI_REF + +#define GPS_HAS_RCV_TIMEOUT ( 1UL << GPS_FEAT_RCV_TIMEOUT ) ///< see ::GPS_FEAT_RCV_TIMEOUT +#define GPS_HAS_IGNORE_LOCK ( 1UL << GPS_FEAT_IGNORE_LOCK ) ///< see ::GPS_FEAT_IGNORE_LOCK +#define GPS_HAS_5_MHZ ( 1UL << GPS_FEAT_5_MHZ ) ///< see ::GPS_FEAT_5_MHZ +#define GPS_HAS_XMULTI_REF ( 1UL << GPS_FEAT_XMULTI_REF ) ///< see ::GPS_FEAT_XMULTI_REF +#define GPS_HAS_OPT_SETTINGS ( 1UL << GPS_FEAT_OPT_SETTINGS ) ///< see ::GPS_FEAT_OPT_SETTINGS +#define GPS_HAS_TIME_SCALE ( 1UL << GPS_FEAT_TIME_SCALE ) ///< see ::GPS_FEAT_TIME_SCALE +#define GPS_HAS_IRIG_CTRL_BITS ( 1UL << GPS_FEAT_IRIG_CTRL_BITS ) ///< see ::GPS_FEAT_IRIG_CTRL_BITS +#define GPS_HAS_PTP ( 1UL << GPS_FEAT_PTP ) ///< see ::GPS_FEAT_PTP + +#define GPS_HAS_NAV_ENGINE_SETTINGS ( 1UL << GPS_FEAT_NAV_ENGINE_SETTINGS ) ///< see ::GPS_FEAT_NAV_ENGINE_SETTINGS +#define GPS_HAS_RAW_IRIG_DATA ( 1UL << GPS_FEAT_RAW_IRIG_DATA ) ///< see ::GPS_FEAT_RAW_IRIG_DATA +#define GPS_HAS_RAW_IRIG_TIME ( 1UL << GPS_FEAT_RAW_IRIG_TIME ) ///< see ::GPS_FEAT_RAW_IRIG_TIME +#define GPS_HAS_PTP_UNICAST ( 1UL << GPS_FEAT_PTP_UNICAST ) ///< see ::GPS_FEAT_PTP_UNICAST +#define GPS_HAS_GPIO ( 1UL << GPS_FEAT_GPIO ) ///< see ::GPS_FEAT_GPIO +#define GPS_HAS_XMRS_MULT_INSTC ( 1UL << GPS_FEAT_XMRS_MULT_INSTC ) ///< see ::GPS_FEAT_XMRS_MULT_INSTC +#define GPS_HAS_10MHZ_DISBD ( 1UL << GPS_FEAT_10MHZ_DISBD ) ///< see ::GPS_FEAT_10MHZ_DISBD +#define GPS_HAS_EVT_LOG ( 1UL << GPS_FEAT_EVT_LOG ) ///< see ::GPS_FEAT_EVT_LOG + +#define GPS_HAS_IMS ( 1UL << GPS_FEAT_IMS ) ///< see ::GPS_FEAT_IMS +#define GPS_HAS_HAVEQUICK ( 1UL << GPS_FEAT_HAVEQUICK ) ///< see ::GPS_FEAT_HAVEQUICK +#define GPS_HAS_NTP ( 1UL << GPS_FEAT_NTP ) ///< see ::GPS_FEAT_NTP +#define GPS_HAS_NET_CFG ( 1UL << GPS_FEAT_NET_CFG ) ///< see ::GPS_FEAT_NET_CFG +#define GPS_HAS_VST ( 1UL << GPS_FEAT_VST ) ///< see ::GPS_FEAT_VST +#define GPS_HAS_SHS ( 1UL << GPS_FEAT_SHS ) ///< see ::GPS_FEAT_SHS +#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 +#define GPS_HAS_DEBUG_STATUS GPS_HAS_IRIG_RX ///< always supported with IRIG inputs, see ::GPS_HAS_IRIG_RX + +/** @} anchor GPS_FEATURE_MASKS */ + + +/** + * @defgroup group_xfeature Extended feature definitions + * + * @note These structures and definitions are only supported by a device + * if ::GPS_HAS_XFEATURE is set in ::RECEIVER_INFO::features. + * + * @{ */ + + +/** + * @brief The maximum number of feature bits supported by the MBG_XFEATURE API. + * + * Warning: Changing this number breaks API compatibility! + * + * @see ::MBG_XFEATURE_BITS + */ +#define MAX_XFEATURE_BITS 1024 + + + +/** + * @brief Enumeration of defined extended features. + * + * @see ::MBG_XFEATURE_NAMES + * @see ::MBG_XFEATURE_BUFFER + */ +enum MBG_XFEATURE_BITS +{ + MBG_XFEATURE_TLV_API, ///< Supports generic TLV API, see @ref group_tlv_api + MBG_XFEATURE_SAVE_CFG, ///< Supports the ::GPS_SAVE_CFG command + MBG_XFEATURE_LED_API, ///< Supports programmable LED API, see @ref group_led_api + MBG_XFEATURE_LNE_API, ///< Supports specific LNE API, see @ref group_lne_api + MBG_XFEATURE_PWR_CTL_API, ///< Supports power control, see @ref group_pwr_ctl_api + MBG_XFEATURE_EXT_SYS_INFO, ///< Supports extended revision information, see @ref group_ext_sys_info + MBG_XFEATURE_TRANSACTIONS, ///< Supports the ::GPS_BEGIN_TRANSACTION and ::GPS_END_TRANSACTION commands, see also ::MBG_TRANSACTION_TYPES + 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_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 + MBG_XFEATURE_TAINTED_CFG, ///< Supports tainted config structures, see @ref group_tainted_cfg + MBG_XFEATURE_PUSH_MSGS, ///< Supports commands ::GPS_REGISTER_PUSH_MSGS and ::GPS_UNREGISTER_PUSH_MSGS + MBG_XFEATURE_USER_AUTH, ///< Supports user authentication and command ::GPS_AUTH_USER_INFO + MBG_XFEATURE_USER_MNGMNT, ///< Supports user management, see @ref group_user_mngmnt + MBG_XFEATURE_SERVICE, ///< Supports service management, see @ref group_service_mngmnt + MBG_XFEATURE_UP_CONV, ///< Instead of a standard L1 antenna, a Meinberg antenna/converter can be used with this GNSS device. + MBG_XFEATURE_FW_MNGMNT, ///< Supports firmware management, see @ref group_fw_mngmnt + 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 + 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 + // be taken that ::N_MBG_XFEATURE doesn't exceed ::MAX_XFEATURE_BITS. +}; + + + +/** + * @brief Names of extended device features + * + * Can be used to initialize a string array of ::N_MBG_XFEATURE entries, + * so the number of strings must correspond to ::N_MBG_XFEATURE. + * + * @see ::MBG_XFEATURE_BITS + */ +#define MBG_XFEATURE_NAMES \ +{ \ + "Generic TLV API", \ + "Save Config On Card", \ + "Programmable LED API", \ + "LNE API", \ + "Power Control API", \ + "Extended Revision Info", \ + "Transaction commands", \ + "Reboot Command", \ + "Clock Resolution Info", \ + "Extended User Captures", \ + "Request TTM", \ + "I/O Ports", \ + "Monitoring", \ + "XHE Unit", \ + "Tainted Config", \ + "Push Messages", \ + "User Authentication", \ + "User Management", \ + "Service Management", \ + "Antenna Converter", \ + "Firmware Management", \ + "DAC control via bus", \ + "Database", \ + "GNSS Messages" \ } + /** - * @brief Bit masks used with RECEIVER_INFO::features + * @brief Array size required to store all extended features + * + * The number of bytes required to store up to ::MAX_XFEATURE_BITS + * feature bits in a byte array. + */ +#define MAX_XFEATURE_BYTES ( MAX_XFEATURE_BITS / 8 ) + + + +/** + * @brief A structure used to store extended device features. + * + * Up to ::MAX_XFEATURE_BITS totally can be stored, but only + * ::N_MBG_XFEATURE extended features are currently defined. + * The ::_set_xfeature_bit macro should be used by the firmware + * to set a feature bit in the buffer, and the ::check_xfeature + * function should be used to implement API calls which test if an + * extended feature is supported. * - * @see GPS_FEATURE_BITS + * @see ::_set_xfeature_bit + * @see ::check_xfeature */ -enum GPS_FEATURE_MASKS +typedef struct { - GPS_HAS_PPS = ( 1UL << GPS_FEAT_PPS ), ///< see ::GPS_FEAT_PPS - GPS_HAS_PPM = ( 1UL << GPS_FEAT_PPM ), ///< see ::GPS_FEAT_PPM - GPS_HAS_SYNTH = ( 1UL << GPS_FEAT_SYNTH ), ///< see ::GPS_FEAT_SYNTH - GPS_HAS_DCFMARKS = ( 1UL << GPS_FEAT_DCFMARKS ), ///< see ::GPS_FEAT_DCFMARKS - GPS_HAS_IRIG_TX = ( 1UL << GPS_FEAT_IRIG_TX ), ///< see ::GPS_FEAT_IRIG_TX - GPS_HAS_IRIG_RX = ( 1UL << GPS_FEAT_IRIG_RX ), ///< see ::GPS_FEAT_IRIG_RX - GPS_HAS_LAN_IP4 = ( 1UL << GPS_FEAT_LAN_IP4 ), ///< see ::GPS_FEAT_LAN_IP4 - GPS_HAS_MULTI_REF = ( 1UL << GPS_FEAT_MULTI_REF ), ///< see ::GPS_FEAT_MULTI_REF + uint8_t b[MAX_XFEATURE_BYTES]; - GPS_HAS_RCV_TIMEOUT = ( 1UL << GPS_FEAT_RCV_TIMEOUT ), ///< see ::GPS_FEAT_RCV_TIMEOUT - GPS_HAS_IGNORE_LOCK = ( 1UL << GPS_FEAT_IGNORE_LOCK ), ///< see ::GPS_FEAT_IGNORE_LOCK - GPS_HAS_5_MHZ = ( 1UL << GPS_FEAT_5_MHZ ), ///< see ::GPS_FEAT_5_MHZ - GPS_HAS_XMULTI_REF = ( 1UL << GPS_FEAT_XMULTI_REF ), ///< see ::GPS_FEAT_XMULTI_REF - GPS_HAS_OPT_SETTINGS = ( 1UL << GPS_FEAT_OPT_SETTINGS ), ///< see ::GPS_FEAT_OPT_SETTINGS - GPS_HAS_TIME_SCALE = ( 1UL << GPS_FEAT_TIME_SCALE ), ///< see ::GPS_FEAT_TIME_SCALE - GPS_HAS_IRIG_CTRL_BITS = ( 1UL << GPS_FEAT_IRIG_CTRL_BITS ), ///< see ::GPS_FEAT_IRIG_CTRL_BITS - GPS_HAS_PTP = ( 1UL << GPS_FEAT_PTP ), ///< see ::GPS_FEAT_PTP +} MBG_XFEATURE_BUFFER; - GPS_HAS_NAV_ENGINE_SETTINGS = ( 1UL << GPS_FEAT_NAV_ENGINE_SETTINGS ), ///< see ::GPS_FEAT_NAV_ENGINE_SETTINGS - GPS_HAS_RAW_IRIG_DATA = ( 1UL << GPS_FEAT_RAW_IRIG_DATA ), ///< see ::GPS_FEAT_RAW_IRIG_DATA - GPS_HAS_RAW_IRIG_TIME = ( 1UL << GPS_FEAT_RAW_IRIG_TIME ), ///< see ::GPS_FEAT_RAW_IRIG_TIME - GPS_HAS_PTP_UNICAST = ( 1UL << GPS_FEAT_PTP_UNICAST ), ///< see ::GPS_FEAT_PTP_UNICAST - GPS_HAS_GPIO = ( 1UL << GPS_FEAT_GPIO ), ///< see ::GPS_FEAT_GPIO - GPS_HAS_XMRS_MULT_INSTC = ( 1UL << GPS_FEAT_XMRS_MULT_INSTC ), ///< see ::GPS_FEAT_XMRS_MULT_INSTC - GPS_HAS_10MHZ_DISBD = ( 1UL << GPS_FEAT_10MHZ_DISBD ), ///< see ::GPS_FEAT_10MHZ_DISBD - GPS_HAS_EVT_LOG = ( 1UL << GPS_FEAT_EVT_LOG ), ///< see ::GPS_FEAT_EVT_LOG - GPS_HAS_IMS = ( 1UL << GPS_FEAT_IMS ), ///< see ::GPS_FEAT_IMS - GPS_HAS_HAVEQUICK = ( 1UL << GPS_FEAT_HAVEQUICK ), ///< see ::GPS_FEAT_HAVEQUICK - // the next ones are special since they just shadow another flag: - GPS_HAS_REF_OFFS = GPS_HAS_IRIG_RX, ///< always supported with IRIG inputs, see ::GPS_HAS_IRIG_RX - GPS_HAS_DEBUG_INFO = GPS_HAS_IRIG_RX ///< always supported with IRIG inputs, see ::GPS_HAS_IRIG_RX -}; +/** + * @brief Set an extended feature bit in a ::MBG_XFEATURE_BUFFER + * + * Should be used by the firmware only to set one of the ::MBG_XFEATURE_BITS + * in an ::MBG_XFEATURE_BUFFER after power-up. + * + * @param[in] _xf_bit One of the ::MBG_XFEATURE_BITS + * @param[in] _xf_buffp Pointer to an ::MBG_XFEATURE_BUFFER + */ +#define _set_xfeature_bit( _xf_bit, _xf_buffp ) \ + _set_array_bit( _xf_bit, (_xf_buffp)->b, MAX_XFEATURE_BYTES ) + + +/** @} defgroup group_xfeature */ + /* @@ -1085,7 +2474,7 @@ enum GPS_FEATURE_MASKS /** - * @brief Bits to be used with RECEIVER_INFO::flags + * @brief Bits used to define ::RECEIVER_INFO_FLAG_MASKS */ enum RECEIVER_INFO_FLAG_BITS { @@ -1095,14 +2484,21 @@ enum RECEIVER_INFO_FLAG_BITS N_RECEIVER_INFO_FLAG_BITS ///< number of known bits }; -#define GPS_OSC_CFG_SUPP ( 1UL << GPS_BIT_OSC_CFG_SUPP ) -#define GPS_IRIG_FO_IN ( 1UL << GPS_BIT_IRIG_FO_IN ) -#define GPS_HAS_FPGA ( 1UL << GPS_BIT_HAS_FPGA ) + +/** + * @brief Bit masks to be used with ::RECEIVER_INFO::flags + */ +enum RECEIVER_INFO_FLAG_MASKS +{ + GPS_OSC_CFG_SUPP = ( 1UL << GPS_BIT_OSC_CFG_SUPP ), ///< see ::GPS_BIT_OSC_CFG_SUPP + GPS_IRIG_FO_IN = ( 1UL << GPS_BIT_IRIG_FO_IN ), ///< see ::GPS_BIT_IRIG_FO_IN + GPS_HAS_FPGA = ( 1UL << GPS_BIT_HAS_FPGA ) ///< see ::GPS_BIT_HAS_FPGA +}; /* - * If the GPS_HAS_FPGA flag is set in RECEIVER_INFO::flags then the card + * If the ::GPS_HAS_FPGA flag is set in ::RECEIVER_INFO::flags then the card * provides an FPGA and the following information about the FPGA is available: */ #define FPGA_NAME_LEN 31 // max name length @@ -1116,11 +2512,7 @@ typedef union { CSUM csum; uint32_t fsize; - #if _IS_MBG_FIRMWARE - uint32_t start_addr; - #else - uint8_t *start_addr; - #endif + uint32_t start_addr; char name[FPGA_NAME_SIZE]; } hdr; @@ -1138,6 +2530,7 @@ typedef struct { CSUM csum; uint16_t fpga_start_seg; // Number of the 4k block where an FPGA image is located + } FPGA_START_INFO; #define DEFAULT_FPGA_START_SEG 0x60 @@ -1163,23 +2556,25 @@ typedef struct * the receiver's internal time. * * %UTC time differs from GPS time since a number of leap seconds have - * been inserted in the %UTC time scale after the GPS epoche. The number + * been inserted in the %UTC time scale after the GPS epoch. The number * of leap seconds is disseminated by the satellites using the ::UTC * parameter set, which also provides info on pending leap seconds. */ typedef struct { - uint16_t wn; ///< the week number since GPS has been installed + 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; scale: 1/::RECEIVER_INFO::ticks_per_sec + uint32_t tick; ///< fractions of a second, 1/::RECEIVER_INFO::ticks_per_sec units + } T_GPS; #define _mbg_swab_t_gps( _p ) \ +do \ { \ _mbg_swab16( &(_p)->wn ); \ _mbg_swab32( &(_p)->sec ); \ _mbg_swab32( &(_p)->tick ); \ -} +} while ( 0 ) /** @@ -1200,31 +2595,35 @@ typedef struct int16_t year; ///< year number, 0..9999 int8_t month; ///< month, 1..12 int8_t mday; ///< day of month, 1..31 - int16_t yday; ///< day of year, 1..366 + int16_t yday; ///< day of year, 1..365, or 366 in case of leap year int8_t wday; ///< day of week, 0..6 == Sun..Sat int8_t hour; ///< hours, 0..23 int8_t min; ///< minutes, 0..59 - int8_t sec; ///< seconds, 0..59 - int32_t frac; ///< fractions of a second; scale: 1/::RECEIVER_INFO::ticks_per_sec - int32_t offs_from_utc; ///< local time's offset from %UTC - uint16_t status; ///< status flags, see ::TM_GPS_STATUS_BITS + 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; #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 ); \ -} +} while ( 0 ) /** - * @brief Status flags used with TM_GPS::status + * @brief Status flag bits used to define ::TM_GPS_STATUS_BIT_MASKS * * These bits report info on the time conversion from GPS time to %UTC * and/or local time as well as device status info. + * + * @see ::TM_GPS_STATUS_BIT_MASKS */ enum TM_GPS_STATUS_BITS { @@ -1240,31 +2639,43 @@ enum TM_GPS_STATUS_BITS TM_BIT_EXT_SYNC, ///< synchronized externally TM_BIT_HOLDOVER, ///< in holdover mode after previous synchronization TM_BIT_ANT_SHORT, ///< antenna cable short circuited - TM_BIT_NO_WARM, ///< OCXO has not warmed up + TM_BIT_NO_WARM, ///< oscillator control loop not settled TM_BIT_ANT_DISCONN, ///< antenna currently disconnected - TM_BIT_SYN_FLAG, ///< TIME_SYN output is low + TM_BIT_SYN_FLAG, ///< clock not synchronized, reflects the state of the "time sync error" output pin TM_BIT_NO_SYNC, ///< time sync actually not verified TM_BIT_NO_POS ///< position actually not verified, LOCK LED off }; -// bit masks corresponding to the flag bits above -#define TM_UTC ( 1UL << TM_BIT_UTC ) -#define TM_LOCAL ( 1UL << TM_BIT_LOCAL ) -#define TM_DL_ANN ( 1UL << TM_BIT_DL_ANN ) -#define TM_DL_ENB ( 1UL << TM_BIT_DL_ENB ) -#define TM_LS_ANN ( 1UL << TM_BIT_LS_ANN ) -#define TM_LS_ENB ( 1UL << TM_BIT_LS_ENB ) -#define TM_LS_ANN_NEG ( 1UL << TM_BIT_LS_ANN_NEG ) -#define TM_INVT ( 1UL << TM_BIT_INVT ) -#define TM_EXT_SYNC ( 1UL << TM_BIT_EXT_SYNC ) -#define TM_HOLDOVER ( 1UL << TM_BIT_HOLDOVER ) -#define TM_ANT_SHORT ( 1UL << TM_BIT_ANT_SHORT ) -#define TM_NO_WARM ( 1UL << TM_BIT_NO_WARM ) -#define TM_ANT_DISCONN ( 1UL << TM_BIT_ANT_DISCONN ) -#define TM_SYN_FLAG ( 1UL << TM_BIT_SYN_FLAG ) -#define TM_NO_SYNC ( 1UL << TM_BIT_NO_SYNC ) -#define TM_NO_POS ( 1UL << TM_BIT_NO_POS ) +/** + * @brief Status flag masks used with ::TM_GPS::status + * + * These bits report info on the time conversion from GPS time to %UTC + * and/or local time as well as device status info. + * + * @see ::TM_GPS_STATUS_BITS + */ +enum TM_GPS_STATUS_BIT_MASKS +{ + TM_UTC = ( 1UL << TM_BIT_UTC ), ///< see ::TM_BIT_UTC + TM_LOCAL = ( 1UL << TM_BIT_LOCAL ), ///< see ::TM_BIT_LOCAL + TM_DL_ANN = ( 1UL << TM_BIT_DL_ANN ), ///< see ::TM_BIT_DL_ANN + TM_DL_ENB = ( 1UL << TM_BIT_DL_ENB ), ///< see ::TM_BIT_DL_ENB + TM_LS_ANN = ( 1UL << TM_BIT_LS_ANN ), ///< see ::TM_BIT_LS_ANN + TM_LS_ENB = ( 1UL << TM_BIT_LS_ENB ), ///< see ::TM_BIT_LS_ENB + TM_LS_ANN_NEG = ( 1UL << TM_BIT_LS_ANN_NEG ), ///< see ::TM_BIT_LS_ANN_NEG + TM_INVT = ( 1UL << TM_BIT_INVT ), ///< see ::TM_BIT_INVT + + TM_EXT_SYNC = ( 1UL << TM_BIT_EXT_SYNC ), ///< see ::TM_BIT_EXT_SYNC + TM_HOLDOVER = ( 1UL << TM_BIT_HOLDOVER ), ///< see ::TM_BIT_HOLDOVER + TM_ANT_SHORT = ( 1UL << TM_BIT_ANT_SHORT ), ///< see ::TM_BIT_ANT_SHORT + TM_NO_WARM = ( 1UL << TM_BIT_NO_WARM ), ///< see ::TM_BIT_NO_WARM + TM_ANT_DISCONN = ( 1UL << TM_BIT_ANT_DISCONN ), ///< see ::TM_BIT_ANT_DISCONN + TM_SYN_FLAG = ( 1UL << TM_BIT_SYN_FLAG ), ///< see ::TM_BIT_SYN_FLAG + TM_NO_SYNC = ( 1UL << TM_BIT_NO_SYNC ), ///< see ::TM_BIT_NO_SYNC + TM_NO_POS = ( 1UL << TM_BIT_NO_POS ) ///< see ::TM_BIT_NO_POS +}; + /** @@ -1273,7 +2684,7 @@ enum TM_GPS_STATUS_BITS typedef uint32_t TM_STATUS_EXT; /** - * @brief Enumeration of extended status bits used with TM_STATUS_EXT + * @brief Enumeration of extended status bits used with ::TM_STATUS_EXT * * @note The lower 16 bits correspond to ::TM_GPS_STATUS_BITS */ @@ -1284,7 +2695,7 @@ enum TM_GPS_STATUS_BITS_EX // the remaining bits are reserved }; -// The following bits are only used with the TM_STATUS_X type: +// The following bits are only used with the ::TM_STATUS_X type: #define TM_SCALE_GPS ( 1UL << TM_BIT_SCALE_GPS ) #define TM_SCALE_TAI ( 1UL << TM_BIT_SCALE_TAI ) @@ -1304,43 +2715,18 @@ typedef struct int16_t channel; ///< -1: the current on-board time; >= 0 the capture channel number T_GPS t; ///< time in GPS scale and format TM_GPS tm; ///< time converted to %UTC and/or local time according to ::TZDL settings + } TTM; #define _mbg_swab_ttm( _p ) \ +do \ { \ _mbg_swab16( &(_p)->channel ); \ _mbg_swab_t_gps( &(_p)->t ); \ _mbg_swab_tm_gps( &(_p)->tm ); \ -} - - - -/** - * @brief A timestamp with nanosecond resolution - */ -typedef struct -{ - int32_t nano_secs; ///< [nanoseconds] - int32_t secs; ///< [seconds] -} NANO_TIME; - -#define _mbg_swab_nano_time( _p ) \ -{ \ - _mbg_swab32( &(_p)->nano_secs ); \ - _mbg_swab32( &(_p)->secs ); \ -} - -// The macro below checks if a NANO_TIME value is negative. -#define _nano_time_negative( _nt ) \ - ( ( (_nt)->secs < 0 ) || ( (_nt)->nano_secs < 0 ) ) - +} while ( 0 ) -/* Two types of variables used to store a position. Type XYZ is */ -/* used with a position in earth centered, earth fixed (ECEF) */ -/* coordinates whereas type LLA holds such a position converted */ -/* to geographic coordinates as defined by WGS84 (World Geodetic */ -/* System from 1984). */ #ifndef _XYZ_DEFINED /** @@ -1349,7 +2735,9 @@ typedef struct enum XYZ_FIELDS { XP, YP, ZP, N_XYZ }; // x, y, z /** - * @brief An array holding a cartesian position + * @brief A position in cartesian coordinates + * + * Usually earth centered, earth fixed (ECEF) coordinates. */ typedef double XYZ[N_XYZ]; ///< values are in [m], see ::XYZ_FIELDS @@ -1366,7 +2754,12 @@ typedef struct enum LLA_FIELDS { LAT, LON, ALT, N_LLA }; /* latitude, longitude, altitude */ /** - * @brief An array holding a geographic position + * @brief A geographic position based on latitude, longitude, and altitude + * + * The geographic position associated to specific cartesian coordinates + * depends on the characteristics of the ellipsoid used for the computation, + * the so-called geographic datum. GPS uses the WGS84 (World Geodetic System + * from 1984) ellipsoid by default. */ typedef double LLA[N_LLA]; ///< lon, lat in [rad], alt in [m], see ::LLA_FIELDS @@ -1377,35 +2770,35 @@ typedef struct /** - @defgroup group_synth Synthesizer parameters - - Synthesizer frequency is expressed as a - four digit decimal number (freq) to be multiplied by 0.1 Hz and an - base 10 exponent (range). If the effective frequency is less than - 10 kHz its phase is synchronized corresponding to the variable phase. - Phase may be in a range from -360 deg to +360 deg with a resolution - of 0.1 deg, so the resulting numbers to be stored are in a range of - -3600 to +3600. - - Example:<br> - Assume the value of freq is 2345 (decimal) and the value of phase is 900. - If range == 0 the effective frequency is 234.5 Hz with a phase of +90 deg. - If range == 1 the synthesizer will generate a 2345 Hz output frequency - and so on. - - Limitations:<br> - If freq == 0 the synthesizer is disabled. If range == 0 the least - significant digit of freq is limited to 0, 3, 5 or 6. The resulting - frequency is shown in the examples below: - - freq == 1230 --> 123.0 Hz - - freq == 1233 --> 123 1/3 Hz (real 1/3 Hz, NOT 123.3 Hz) - - freq == 1235 --> 123.5 Hz - - freq == 1236 --> 123 2/3 Hz (real 2/3 Hz, NOT 123.6 Hz) - - If range == MAX_RANGE the value of freq must not exceed 1000, so the - output frequency is limited to 10 MHz. - @{ -*/ + * @defgroup group_synth Synthesizer parameters + * + * Synthesizer frequency is expressed as a + * four digit decimal number (freq) to be multiplied by 0.1 Hz and an + * base 10 exponent (range). If the effective frequency is less than + * 10 kHz its phase is synchronized corresponding to the variable phase. + * Phase may be in a range from -360 deg to +360 deg with a resolution + * of 0.1 deg, so the resulting numbers to be stored are in a range of + * -3600 to +3600. + * + * Example:<br> + * Assume the value of freq is 2345 (decimal) and the value of phase is 900. + * If range == 0 the effective frequency is 234.5 Hz with a phase of +90 deg. + * If range == 1 the synthesizer will generate a 2345 Hz output frequency + * and so on. + * + * Limitations:<br> + * If freq == 0 the synthesizer is disabled. If range == 0 the least + * significant digit of freq is limited to 0, 3, 5 or 6. The resulting + * frequency is shown in the examples below: + * - freq == 1230 --> 123.0 Hz + * - freq == 1233 --> 123 1/3 Hz (real 1/3 Hz, NOT 123.3 Hz) + * - freq == 1235 --> 123.5 Hz + * - freq == 1236 --> 123 2/3 Hz (real 2/3 Hz, NOT 123.6 Hz) + * + * If range == ::MAX_SYNTH_RANGE the value of freq must not exceed 1000, so + * the output frequency is limited to 10 MHz (see ::MAX_SYNTH_FREQ_VAL). + * + * @{ */ #define N_SYNTH_FREQ_DIGIT 4 ///< number of digits to edit #define MAX_SYNTH_FREQ 1000 ///< if range == ::MAX_SYNTH_RANGE @@ -1414,12 +2807,13 @@ typedef struct #define MAX_SYNTH_RANGE 5 #define N_SYNTH_RANGE ( MAX_SYNTH_RANGE - MIN_SYNTH_RANGE + 1 ) -#define N_SYNTH_PHASE_DIGIT 4 -#define MAX_SYNTH_PHASE 3600 +#define N_SYNTH_PHASE_DIGIT 4 +#define MAX_SYNTH_PHASE 3600 #define MAX_SYNTH_FREQ_EDIT 9999 ///< max sequence of digits when editing + /** * @brief The maximum frequency that can be configured for the synthesizer */ @@ -1442,7 +2836,7 @@ typedef struct * @brief Synthesizer frequency units * * An initializer for commonly displayed synthesizer frequency units - * (N_SYNTH_RANGE strings) + * (::N_SYNTH_RANGE strings) */ #define DEFAULT_FREQ_RANGES \ { \ @@ -1461,17 +2855,19 @@ typedef struct */ typedef struct { - int16_t freq; ///< four digits used; scale: 0.1; e.g. 1234 -> 123.4 Hz + int16_t freq; ///< four digits used; scale: 0.1 Hz; e.g. 1234 -> 123.4 Hz int16_t range; ///< scale factor for freq; 0..::MAX_SYNTH_RANGE int16_t phase; ///< -::MAX_SYNTH_PHASE..+::MAX_SYNTH_PHASE; >0 -> pulses later + } SYNTH; #define _mbg_swab_synth( _p ) \ +do \ { \ _mbg_swab16( &(_p)->freq ); \ _mbg_swab16( &(_p)->range ); \ _mbg_swab16( &(_p)->phase ); \ -} +} while ( 0 ) /** @@ -1495,42 +2891,51 @@ typedef struct { uint8_t state; ///< state code as enumerated in ::SYNTH_STATES uint8_t flags; ///< reserved, currently always 0 + } SYNTH_STATE; #define _mbg_swab_synth_state( _p ) _nop_macro_fnc() #define SYNTH_FLAG_PHASE_IGNORED 0x01 -/** @} group_synth */ +/** @} defgroup group_synth */ + + /** - * @defgroup group_tzdl Time zone/daylight saving parameters - * - * Example: <br> - * For automatic daylight saving enable/disable in Central Europe, - * the variables are to be set as shown below: <br> - * - offs = 3600L one hour from %UTC - * - offs_dl = 3600L one additional hour if daylight saving enabled - * - tm_on = first Sunday from March 25, 02:00:00h ( year |= DL_AUTO_FLAG ) - * - tm_off = first Sunday from October 25, 03:00:00h ( year |= DL_AUTO_FLAG ) - * - name[0] == "CET " name if daylight saving not enabled - * - name[1] == "CEST " name if daylight saving is enabled - * @{ - */ + * @defgroup group_tzdl Time zone / daylight saving parameters + * + * Example: <br> + * For automatic daylight saving enable/disable in Central Europe, + * the variables are to be set as shown below: <br> + * - offs = 3600L one hour from %UTC + * - offs_dl = 3600L one additional hour if daylight saving enabled + * - tm_on = first Sunday from March 25, 02:00:00h ( year |= ::DL_AUTO_FLAG ) + * - tm_off = first Sunday from October 25, 03:00:00h ( year |= ::DL_AUTO_FLAG ) + * - name[0] == "CET " name if daylight saving not enabled + * - name[1] == "CEST " name if daylight saving is enabled + * + * @{ */ /** * @brief The name of a time zone * - * @note Up to 5 printable characters plus trailing zero + * @note Up to 5 printable characters, plus trailing zero */ typedef char TZ_NAME[6]; /** * @brief Time zone / daylight saving parameters * - * This structure is used to specify how a device is to convert - * on-board %UTC to local time, including computation of beginning - * and end of daylight saving time (DST), if required. + * This structure is used to specify how a device converts on-board %UTC + * to local time, including computation of beginning and end of daylight + * saving time (DST), if required. + * + * @note The ::TZDL structure contains members of type ::TM_GPS to specify + * the times for beginning and end of DST. However, the ::TM_GPS::frac, + * ::TM_GPS::offs_from_utc, and ::TM_GPS::status fields of these ::TZDL::tm_on + * and ::TZDL::tm_off members are ignored for the conversion to local time, + * and thus should be 0. */ typedef struct { @@ -1539,21 +2944,23 @@ typedef struct TM_GPS tm_on; ///< date/time when daylight saving starts TM_GPS tm_off; ///< date/time when daylight saving ends TZ_NAME name[2]; ///< names without and with daylight saving enabled + } TZDL; #define _mbg_swab_tzdl( _p ) \ +do \ { \ _mbg_swab32( &(_p)->offs ); \ _mbg_swab32( &(_p)->offs_dl ); \ _mbg_swab_tm_gps( &(_p)->tm_on ); \ _mbg_swab_tm_gps( &(_p)->tm_off ); \ -} +} while ( 0 ) /** * @brief A flag indicating automatic computation of DST * - * If this flag is or'ed to the year numbers in TZDL::tm_on and TZDL::tm_off + * If this flag is or'ed to the year numbers in ::TZDL::tm_on and ::TZDL::tm_off * then daylight saving is computed automatically year by year. */ #define DL_AUTO_FLAG 0x8000 @@ -1562,13 +2969,13 @@ typedef struct // Below there are some initializers for commonly used TZDL configurations: -#define DEFAULT_TZDL_AUTO_YEAR ( 2007 | DL_AUTO_FLAG ) +#define DEFAULT_TZDL_AUTO_YEAR ( (int16_t) ( 2007L | DL_AUTO_FLAG ) ) -#define DEFAULt_TZDL_OFFS_DL 3600L /**< usually DST is +1 hour */ +#define DEFAULt_TZDL_OFFS_DL 3600L ///< usually DST is +1 hour /** - * An initializer for TZDL::tm_on and TZDL::tm_off for time zones + * An initializer for ::TZDL::tm_on and ::TZDL::tm_off for time zones * which do not observe DST. */ #define DEFAULT_TZDL_TM_ON_OFF_NO_DST \ @@ -1583,22 +2990,22 @@ typedef struct #define DEFAULT_TZDL_UTC \ { \ - 0L, /**< offs */ \ - 0L, /**< offs_dl */ \ - DEFAULT_TZDL_TM_ON_OFF_NO_DST, /**< tm_on */ \ - DEFAULT_TZDL_TM_ON_OFF_NO_DST, /**< tm_off */ \ - DEFAULT_TZDL_NAMES_UTC /**< name[] */ \ + 0L, /* offs */ \ + 0L, /* offs_dl */ \ + DEFAULT_TZDL_TM_ON_OFF_NO_DST, /* tm_on */ \ + DEFAULT_TZDL_TM_ON_OFF_NO_DST, /* tm_off */ \ + DEFAULT_TZDL_NAMES_UTC /* name */ \ } /** - * @brief An initializer for TZDL::tm_on according to the rules for Central Europe + * @brief An initializer for ::TZDL::tm_on according to the rules for Central Europe */ #define DEFAULT_TZDL_TM_ON_CET_CEST \ { DEFAULT_TZDL_AUTO_YEAR, 3, 25, 0, 0, 2, 0, 0, 0L, 0L, 0 } /** - * @brief An initializer for TZDL::tm_off according to the rules for Central Europe + * @brief An initializer for ::TZDL::tm_off according to the rules for Central Europe */ #define DEFAULT_TZDL_TM_OFF_CET_CEST \ { DEFAULT_TZDL_AUTO_YEAR, 10, 25, 0, 0, 3, 0, 0, 0L, 0L, 0 } @@ -1616,20 +3023,20 @@ typedef struct #define DEFAULT_TZDL_CET_CEST_EN \ { \ - DEFAULT_TZDL_OFFS_CET, /**< offs */ \ - DEFAULt_TZDL_OFFS_DL, /**< offs_dl */ \ - DEFAULT_TZDL_TM_ON_CET_CEST, /**< tm_on */ \ - DEFAULT_TZDL_TM_OFF_CET_CEST, /**< tm_off */ \ - DEFAULT_TZDL_NAMES_CET_CEST_EN /**< name[] */ \ + DEFAULT_TZDL_OFFS_CET, /* offs */ \ + DEFAULt_TZDL_OFFS_DL, /* offs_dl */ \ + DEFAULT_TZDL_TM_ON_CET_CEST, /* tm_on */ \ + DEFAULT_TZDL_TM_OFF_CET_CEST, /* tm_off */ \ + DEFAULT_TZDL_NAMES_CET_CEST_EN /* name */ \ } #define DEFAULT_TZDL_CET_CEST_DE \ { \ - DEFAULT_TZDL_OFFS_CET, /**< offs */ \ - DEFAULt_TZDL_OFFS_DL, /**< offs_dl */ \ - DEFAULT_TZDL_TM_ON_CET_CEST, /**< tm_on */ \ - DEFAULT_TZDL_TM_OFF_CET_CEST, /**< tm_off */ \ - DEFAULT_TZDL_NAMES_CET_CEST_DE /**< name[] */ \ + DEFAULT_TZDL_OFFS_CET, /* offs */ \ + DEFAULt_TZDL_OFFS_DL, /* offs_dl */ \ + DEFAULT_TZDL_TM_ON_CET_CEST, /* tm_on */ \ + DEFAULT_TZDL_TM_OFF_CET_CEST, /* tm_off */ \ + DEFAULT_TZDL_NAMES_CET_CEST_DE /* name */ \ } @@ -1659,7 +3066,7 @@ typedef struct DEFAULt_TZDL_OFFS_DL, /* offs_dl */ \ DEFAULT_TZDL_TM_ON_EET_EEST, /* tm_on */ \ DEFAULT_TZDL_TM_OFF_EET_EEST, /* tm_off */ \ - DEFAULT_TZDL_NAMES_EET_EEST_EN /* name[] */ \ + DEFAULT_TZDL_NAMES_EET_EEST_EN /* name */ \ } #define DEFAULT_TZDL_EET_EEST_DE \ @@ -1668,24 +3075,25 @@ typedef struct DEFAULt_TZDL_OFFS_DL, /* offs_dl */ \ DEFAULT_TZDL_TM_ON_EET_EEST, /* tm_on */ \ DEFAULT_TZDL_TM_OFF_EET_EEST, /* tm_off */ \ - DEFAULT_TZDL_NAMES_EET_EEST_DE /* name[] */ \ + DEFAULT_TZDL_NAMES_EET_EEST_DE /* name */ \ } -/** @} group_tzdl */ +/** @} defgroup group_tzdl */ /** - * @brief Antenna status information + * @brief Antenna status and error at reconnect information * * The structure below reflects the status of the antenna, * the times of last disconnect/reconnect, and the board's - * clock offset after the disconnection interval. + * clock offset when it has synchronized again after the + * disconnection interval. * - * @note ANT_INFO::status changes back to ::ANT_RECONN only + * @note ::ANT_INFO::status changes back to ::ANT_RECONN only * after the antenna has been reconnected <b>and</b> the * receiver has re-synchronized to the satellite signal. - * In this case ANT_INFO::delta_t reports the time offset + * In this case ::ANT_INFO::delta_t reports the time offset * before resynchronization, i.e. how much the internal * time has drifted while the antenna was disconnected. */ @@ -1694,20 +3102,22 @@ typedef struct int16_t status; ///< current status of antenna, see ::ANT_STATUS_CODES TM_GPS tm_disconn; ///< time of antenna disconnect TM_GPS tm_reconn; ///< time of antenna reconnect - int32_t delta_t; ///< clock offs at reconn. time in 1/::RECEIVER_INFO::ticks_per_sec + int32_t delta_t; ///< clock offs at reconn. time in 1/::RECEIVER_INFO::ticks_per_sec units + } ANT_INFO; #define _mbg_swab_ant_info( _p ) \ +do \ { \ _mbg_swab16( &(_p)->status ); \ _mbg_swab_tm_gps( &(_p)->tm_disconn ); \ _mbg_swab_tm_gps( &(_p)->tm_reconn ); \ _mbg_swab32( &(_p)->delta_t ); \ -} +} while ( 0 ) /** - * @brief Status code used with ANT_INFO::status + * @brief Status code used with ::ANT_INFO::status */ enum ANT_STATUS_CODES { @@ -1718,23 +3128,15 @@ enum ANT_STATUS_CODES }; -/* Defines used with ENABLE_FLAGS */ - -#define EF_OFF 0x00 /**< outputs off until sync'd */ - -#define EF_SERIAL_BOTH 0x03 /**< both serial ports on */ -#define EF_PULSES_BOTH 0x03 /**< both pulses P_SEC and P_MIN on */ -#define EF_FREQ_ALL 0x07 /**< all fixed freq. outputs on */ -#define EF_SYNTH 0x01 /**< synth. on */ /** * @brief A structure controlling when output signals are enabled * * The structure holds some flags which let the corresponding outputs * be disabled after power-up until the receiver has synchronized - * (flag == ::EF_OFF, the default) or force the outputs to be enabled + * (flags == ::EF_OFF, the default) or force the outputs to be enabled * immediately after power-up. The fixed frequency output is hard-wired - * to be enabled immediately after power-up, so ENABLE_FLAGS::freq must + * to be enabled immediately after power-up, so ::ENABLE_FLAGS::freq must * always be set to ::EF_FREQ_ALL. */ typedef struct @@ -1743,18 +3145,33 @@ typedef struct uint16_t pulses; ///< ::EF_OFF or ::EF_PULSES_BOTH uint16_t freq; ///< always ::EF_FREQ_ALL uint16_t synth; ///< ::EF_OFF or ::EF_SYNTH + } ENABLE_FLAGS; #define _mbg_swab_enable_flags( _p ) \ +do \ { \ _mbg_swab16( &(_p)->serial ); \ _mbg_swab16( &(_p)->pulses ); \ _mbg_swab16( &(_p)->freq ); \ _mbg_swab16( &(_p)->synth ); \ -} +} while ( 0 ) + + +/** + * @brief Codes used with ::ENABLE_FLAGS + **/ +enum ENABLE_FLAGS_CODES +{ + EF_OFF = 0x00, ///< associated outputs off until synchronized + + EF_SERIAL_BOTH = 0x03, ///< both serial ports on, use with ::ENABLE_FLAGS::serial + EF_PULSES_BOTH = 0x03, ///< both pulses P_SEC and P_MIN on, use with ::ENABLE_FLAGS::pulses + EF_FREQ_ALL = 0x07, ///< all fixed freq. outputs on, use with ::ENABLE_FLAGS::freq + EF_SYNTH = 0x01 ///< synthesizer on, use with ::ENABLE_FLAGS::synth +}; -/* A struct used to hold the settings of a serial port: */ #ifndef _COM_HS_DEFINED /** @@ -1766,22 +3183,26 @@ typedef struct #ifndef _COM_PARM_DEFINED /** - * @brief A data type to configure a baud rate + * @brief A data type to configure a serial port's baud rate + * + * @see ::MBG_BAUD_RATES */ typedef int32_t BAUD_RATE; /** * @brief Indices used to identify a parameter in the framing string + * + * @see ::MBG_FRAMING_STRS */ - enum { F_DBITS, F_PRTY, F_STBITS }; + enum MBG_FRAMING_STR_IDXS { F_DBITS, F_PRTY, F_STBITS }; /** * @brief A structure to store the configuration of a serial port */ typedef struct { - BAUD_RATE baud_rate; ///< transmission speed, e.g. 19200L - char framing[4]; ///< ASCIIZ framing string, e.g. "8N1" or "7E2" + 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; @@ -1792,16 +3213,20 @@ typedef struct #define _mbg_swab_baud_rate( _p ) _mbg_swab32( _p ) #define _mbg_swab_com_parm( _p ) \ +do \ { \ _mbg_swab_baud_rate( &(_p)->baud_rate ); \ _mbg_swab16( &(_p)->handshake ); \ -} +} while ( 0 ) /** - * @brief Indices of any supported serial port baud rates + * @brief Enumeration of serial port baud rates * * @note Most clock models and/or serial ports don't support all defined baud rates. + * + * @see ::MBG_BAUD_RATES + * @see ::MBG_BAUD_RATE_MASKS */ enum MBG_BAUD_RATE_CODES { @@ -1813,12 +3238,23 @@ enum MBG_BAUD_RATE_CODES MBG_BAUD_RATE_9600, MBG_BAUD_RATE_19200, MBG_BAUD_RATE_38400, - N_MBG_BAUD_RATES /**< the number of supported baud rates */ + MBG_BAUD_RATE_57600, + MBG_BAUD_RATE_115200, + MBG_BAUD_RATE_230400, + MBG_BAUD_RATE_460800, + MBG_BAUD_RATE_921600, + N_MBG_BAUD_RATES ///< the number of known baud rates }; -/* - * An initializer for a table of baud rate values. - * The values must correspond to the enumeration above. +/** + * @brief An initializer for a table of baud rate values + * + * These values can be used with ::COM_PARM::baud_rate, if the device + * supports the particular baud rate. + * + * The values must correspond to the enumeration ::MBG_BAUD_RATE_CODES + * + * @see ::MBG_BAUD_RATE_CODES */ #define MBG_BAUD_RATES \ { \ @@ -1829,12 +3265,20 @@ enum MBG_BAUD_RATE_CODES 4800L, \ 9600L, \ 19200L, \ - 38400L \ + 38400L, \ + 57600L, \ + 115200L, \ + 230400L, \ + 460800L, \ + 921600L \ } -/* - * An initializer for a table of baud rate strings. - * The values must correspond to the enumeration above. +/** + * @brief An initializer for a table of baud rate strings + * + * The values must correspond to the enumeration ::MBG_BAUD_RATE_CODES + * + * @see ::MBG_BAUD_RATE_CODES */ #define MBG_BAUD_STRS \ { \ @@ -1845,30 +3289,47 @@ enum MBG_BAUD_RATE_CODES "4800", \ "9600", \ "19200", \ - "38400" \ + "38400", \ + "57600", \ + "115200", \ + "230400", \ + "460800", \ + "921600" \ } -/* - * The bit masks below can be used to determine which baud rates - * are supported by a serial port. This may vary between - * different ports of the same device since different - * types of UART are used which must not necessarily support - * each baud rate: +/** + * @brief Bit masks associated with baud rates enumerated in ::MBG_BAUD_RATE_CODES + * + * These bit masks are used e.g. with ::PORT_INFO::supp_baud_rates to + * determine which baud rates are supported by a particular serial port. + * + * @see ::MBG_BAUD_RATE_CODES + * @see ::MBG_FRAMING_MASKS */ -#define MBG_PORT_HAS_300 ( 1UL << MBG_BAUD_RATE_300 ) -#define MBG_PORT_HAS_600 ( 1UL << MBG_BAUD_RATE_600 ) -#define MBG_PORT_HAS_1200 ( 1UL << MBG_BAUD_RATE_1200 ) -#define MBG_PORT_HAS_2400 ( 1UL << MBG_BAUD_RATE_2400 ) -#define MBG_PORT_HAS_4800 ( 1UL << MBG_BAUD_RATE_4800 ) -#define MBG_PORT_HAS_9600 ( 1UL << MBG_BAUD_RATE_9600 ) -#define MBG_PORT_HAS_19200 ( 1UL << MBG_BAUD_RATE_19200 ) -#define MBG_PORT_HAS_38400 ( 1UL << MBG_BAUD_RATE_38400 ) +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 +}; /** - * @brief Indices of any supported serial port framings. + * @brief Enumeration of all known serial port framings * * @note Most clock models and/or serial ports don't support all defined framing types. + * + * @see ::MBG_FRAMING_STRS */ enum MBG_FRAMING_CODES { @@ -1881,13 +3342,21 @@ enum MBG_FRAMING_CODES MBG_FRAMING_7O1, MBG_FRAMING_7O2, MBG_FRAMING_8O1, - MBG_FRAMING_8E2, /**< @note: Most serial ports don't support this! */ - N_MBG_FRAMINGS /**< the number of supported framings */ + MBG_FRAMING_8E2, ///< Note: most serial ports don't support this! + N_MBG_FRAMINGS ///< the number of known framings }; -/* - * An initializer for a table of framing strings. - * The values must correspond to the enumeration above. +/** + * @brief An initializer for a table of known framing strings + * + * These values can be used with ::COM_PARM::framing, if the device + * supports the particular framing. + * + * The values must correspond to the enumeration ::MBG_FRAMING_CODES + * + * @see ::MBG_FRAMING_CODES + * @see ::MBG_FRAMING_MASKS + * @see ::MBG_FRAMING_STR_IDXS */ #define MBG_FRAMING_STRS \ { \ @@ -1903,29 +3372,76 @@ enum MBG_FRAMING_CODES "8E2" \ } -/* - * The bit masks below can be used to determine which framings - * are supported by a serial port. This may vary between - * different ports of the same device since different - * types of UART are used which must not necessarily support - * each framing type: +/** + * @brief Bit masks associated with framings enumerated in ::MBG_FRAMING_CODES + * + * These bit masks are used e.g. with ::PORT_INFO::supp_framings to + * determine which framings are supported by a particular serial port. + * + * @see ::MBG_FRAMING_CODES + * @see ::MBG_FRAMING_STRS */ -#define MBG_PORT_HAS_7N2 ( 1UL << MBG_FRAMING_7N2 ) -#define MBG_PORT_HAS_7E1 ( 1UL << MBG_FRAMING_7E1 ) -#define MBG_PORT_HAS_7E2 ( 1UL << MBG_FRAMING_7E2 ) -#define MBG_PORT_HAS_8N1 ( 1UL << MBG_FRAMING_8N1 ) -#define MBG_PORT_HAS_8N2 ( 1UL << MBG_FRAMING_8N2 ) -#define MBG_PORT_HAS_8E1 ( 1UL << MBG_FRAMING_8E1 ) -#define MBG_PORT_HAS_7O1 ( 1UL << MBG_FRAMING_7O1 ) -#define MBG_PORT_HAS_7O2 ( 1UL << MBG_FRAMING_7O2 ) -#define MBG_PORT_HAS_8O1 ( 1UL << MBG_FRAMING_8O1 ) -#define MBG_PORT_HAS_8E2 ( 1UL << MBG_FRAMING_8E2 ) +enum MBG_FRAMING_MASKS +{ + MBG_PORT_HAS_7N2 = ( 1UL << MBG_FRAMING_7N2 ), ///< see ::MBG_FRAMING_7N2 + MBG_PORT_HAS_7E1 = ( 1UL << MBG_FRAMING_7E1 ), ///< see ::MBG_FRAMING_7E1 + MBG_PORT_HAS_7E2 = ( 1UL << MBG_FRAMING_7E2 ), ///< see ::MBG_FRAMING_7E2 + MBG_PORT_HAS_8N1 = ( 1UL << MBG_FRAMING_8N1 ), ///< see ::MBG_FRAMING_8N1 + MBG_PORT_HAS_8N2 = ( 1UL << MBG_FRAMING_8N2 ), ///< see ::MBG_FRAMING_8N2 + MBG_PORT_HAS_8E1 = ( 1UL << MBG_FRAMING_8E1 ), ///< see ::MBG_FRAMING_8E1 + MBG_PORT_HAS_7O1 = ( 1UL << MBG_FRAMING_7O1 ), ///< see ::MBG_FRAMING_7O1 + MBG_PORT_HAS_7O2 = ( 1UL << MBG_FRAMING_7O2 ), ///< see ::MBG_FRAMING_7O2 + MBG_PORT_HAS_8O1 = ( 1UL << MBG_FRAMING_8O1 ), ///< see ::MBG_FRAMING_8O1 + MBG_PORT_HAS_8E2 = ( 1UL << MBG_FRAMING_8E2 ) ///< see ::MBG_FRAMING_8E2 +}; + + +/** + * @brief Definitions used with the Meinberg binary protocol + * + * @anchor GPS_BIN_PROT_DEFS @{ */ -// Default port settings to be used -// with the binary protocol -#define MBG_DEFAULT_BAUDRATE 19200L -#define MBG_DEFAULT_FRAMING "8N1" +/** + * @brief Framing used with the binary protocol + * + * Different data length, or parity settings would corrupt + * the binary data. + */ +#define MBG_DEFAULT_FRAMING "8N1" + +/** + * @brief The standard baud rate used for the binary protocol + * + * This is supported by most devices. Some new devices may also + * support ::MBG_DEFAULT_BAUDRATE_HS + */ +#define MBG_DEFAULT_BAUDRATE 19200L + +/** + * @brief The high speed baud rate used for the binary protocol + * + * This is not supported by older devices which work + * with ::MBG_DEFAULT_BAUDRATE only. + */ +#define MBG_DEFAULT_BAUDRATE_HS 115200L + + +/** + * @brief Strings used to force connection settings for the binary protocol + * + * If a device supports this and receives one of these ASCII strings + * then it temporarily switches the serial port to some well-known + * baud rate and framing appropriate for the binary protocol. + * + * @anchor GPS_BIN_PROT_CMD_STRS @{ */ + +#define MBG_FORCE_CONN_CMD_STR "\nDFC\n" ///< switch to ::MBG_DEFAULT_BAUDRATE +#define MBG_FORCE_CONN_HS_CMD_STR "\nDFCHS\n" ///< switch to ::MBG_DEFAULT_BAUDRATE_HS + +/** @} anchor GPS_BIN_PROT_CMD_STRS */ + +/** @} anchor GPS_BIN_PROT_DEFS */ @@ -1993,21 +3509,23 @@ typedef struct COM_PARM parm; ///< transmission speed, framing, etc. uint8_t mode; ///< string mode, see ::STR_MODES uint8_t str_type; ///< index of the supported time string formats, see ::STR_TYPE_INFO_IDX - uint32_t flags; ///< @see COM_CFG_STATUS_BITS + uint32_t flags; ///< reserved, don't use, currently 0 + } PORT_SETTINGS; #define _mbg_swab_port_settings( _p ) \ +do \ { \ _mbg_swab_com_parm( &(_p)->parm ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) /** - * @brief Flag bits used to marks individual ::PORT_SETTINGS fields + * @brief Flag bits used to mark individual ::PORT_SETTINGS fields * * These definitions can be used to mark specific fields of a - * PORT_SETTINGS structure, e.g. which fields have changed when + * ::PORT_SETTINGS structure, e.g. which fields have changed when * editing, or which fields have settings which are not valid. */ enum MBG_COM_CFG_STATUS_BITS @@ -2031,22 +3549,33 @@ enum MBG_COM_CFG_STATUS_BITS N_MBG_PS_BIT }; -#define MBG_PS_MSK_BAUD_RATE_OVR_SW ( 1UL << MBG_PS_BIT_BAUD_RATE_OVR_SW ) -#define MBG_PS_MSK_BAUD_RATE_OVR_DEV ( 1UL << MBG_PS_BIT_BAUD_RATE_OVR_DEV ) -#define MBG_PS_MSK_BAUD_RATE ( 1UL << MBG_PS_BIT_BAUD_RATE ) -#define MBG_PS_MSK_FRAMING_OVR_SW ( 1UL << MBG_PS_BIT_FRAMING_OVR_SW ) -#define MBG_PS_MSK_FRAMING_OVR_DEV ( 1UL << MBG_PS_BIT_FRAMING_OVR_DEV ) -#define MBG_PS_MSK_FRAMING ( 1UL << MBG_PS_BIT_FRAMING ) -#define MBG_PS_MSK_HS_OVR_SW ( 1UL << MBG_PS_BIT_HS_OVR_SW ) -#define MBG_PS_MSK_HS ( 1UL << MBG_PS_BIT_HS ) -#define MBG_PS_MSK_STR_TYPE_OVR_SW ( 1UL << MBG_PS_BIT_STR_TYPE_OVR_SW ) -#define MBG_PS_MSK_STR_TYPE_OVR_DEV ( 1UL << MBG_PS_BIT_STR_TYPE_OVR_DEV ) -#define MBG_PS_MSK_STR_TYPE ( 1UL << MBG_PS_BIT_STR_TYPE ) -#define MBG_PS_MSK_STR_MODE_OVR_SW ( 1UL << MBG_PS_BIT_STR_MODE_OVR_SW ) -#define MBG_PS_MSK_STR_MODE_OVR_DEV ( 1UL << MBG_PS_BIT_STR_MODE_OVR_DEV ) -#define MBG_PS_MSK_STR_MODE ( 1UL << MBG_PS_BIT_STR_MODE ) -#define MBG_PS_MSK_FLAGS_OVR_SW ( 1UL << MBG_PS_BIT_FLAGS_OVR_SW ) -#define MBG_PS_MSK_FLAGS ( 1UL << MBG_PS_BIT_FLAGS ) +/** + * @brief Flag bit masks associated with ::MBG_COM_CFG_STATUS_BITS + * + * These definitions can be used to mark specific fields of a + * ::PORT_SETTINGS structure, e.g. which fields have changed when + * editing, or which fields have settings which are not valid. + * + * @anchor MBG_COM_CFG_STATUS_MASKS @{ */ + +#define MBG_PS_MSK_BAUD_RATE_OVR_SW ( 1UL << MBG_PS_BIT_BAUD_RATE_OVR_SW ) ///< see ::MBG_PS_BIT_BAUD_RATE_OVR_SW +#define MBG_PS_MSK_BAUD_RATE_OVR_DEV ( 1UL << MBG_PS_BIT_BAUD_RATE_OVR_DEV ) ///< see ::MBG_PS_BIT_BAUD_RATE_OVR_DEV +#define MBG_PS_MSK_BAUD_RATE ( 1UL << MBG_PS_BIT_BAUD_RATE ) ///< see ::MBG_PS_BIT_BAUD_RATE +#define MBG_PS_MSK_FRAMING_OVR_SW ( 1UL << MBG_PS_BIT_FRAMING_OVR_SW ) ///< see ::MBG_PS_BIT_FRAMING_OVR_SW +#define MBG_PS_MSK_FRAMING_OVR_DEV ( 1UL << MBG_PS_BIT_FRAMING_OVR_DEV ) ///< see ::MBG_PS_BIT_FRAMING_OVR_DEV +#define MBG_PS_MSK_FRAMING ( 1UL << MBG_PS_BIT_FRAMING ) ///< see ::MBG_PS_BIT_FRAMING +#define MBG_PS_MSK_HS_OVR_SW ( 1UL << MBG_PS_BIT_HS_OVR_SW ) ///< see ::MBG_PS_BIT_HS_OVR_SW +#define MBG_PS_MSK_HS ( 1UL << MBG_PS_BIT_HS ) ///< see ::MBG_PS_BIT_HS +#define MBG_PS_MSK_STR_TYPE_OVR_SW ( 1UL << MBG_PS_BIT_STR_TYPE_OVR_SW ) ///< see ::MBG_PS_BIT_STR_TYPE_OVR_SW +#define MBG_PS_MSK_STR_TYPE_OVR_DEV ( 1UL << MBG_PS_BIT_STR_TYPE_OVR_DEV ) ///< see ::MBG_PS_BIT_STR_TYPE_OVR_DEV +#define MBG_PS_MSK_STR_TYPE ( 1UL << MBG_PS_BIT_STR_TYPE ) ///< see ::MBG_PS_BIT_STR_TYPE +#define MBG_PS_MSK_STR_MODE_OVR_SW ( 1UL << MBG_PS_BIT_STR_MODE_OVR_SW ) ///< see ::MBG_PS_BIT_STR_MODE_OVR_SW +#define MBG_PS_MSK_STR_MODE_OVR_DEV ( 1UL << MBG_PS_BIT_STR_MODE_OVR_DEV ) ///< see ::MBG_PS_BIT_STR_MODE_OVR_DEV +#define MBG_PS_MSK_STR_MODE ( 1UL << MBG_PS_BIT_STR_MODE ) ///< see ::MBG_PS_BIT_STR_MODE +#define MBG_PS_MSK_FLAGS_OVR_SW ( 1UL << MBG_PS_BIT_FLAGS_OVR_SW ) ///< see ::MBG_PS_BIT_FLAGS_OVR_SW +#define MBG_PS_MSK_FLAGS ( 1UL << MBG_PS_BIT_FLAGS ) ///< see ::MBG_PS_BIT_FLAGS + +/** @} anchor MBG_COM_CFG_STATUS_MASKS */ @@ -2055,24 +3584,26 @@ enum MBG_COM_CFG_STATUS_BITS * * This structure should be sent to a device to configure * a specific serial port. The number of supported ports - * is RECEIVER_INFO::n_com_port. + * is ::RECEIVER_INFO::n_com_ports. * * @note The ::PORT_INFO_IDX structure should be read from * a device to retrieve the current settings and capabilities. * - * @see STR_TYPE_INFO + * @see ::STR_TYPE_INFO */ typedef struct { - uint16_t idx; ///< port index, 0..RECEIVER_INFO::n_com_port - 1 + uint16_t idx; ///< port index, 0..::RECEIVER_INFO::n_com_ports-1 PORT_SETTINGS port_settings; + } PORT_SETTINGS_IDX; #define _mbg_swab_port_settings_idx( _p ) \ +do \ { \ _mbg_swab16( &(_p)->idx ); \ _mbg_swab_port_settings( &(_p)->port_settings ); \ -} +} while ( 0 ) /** @@ -2082,19 +3613,21 @@ typedef struct * the current settings of a serial port plus its capabilities, * e.g. supported baud rates, supported string formats, etc. * - * @see STR_TYPE_INFO + * @see ::STR_TYPE_INFO */ typedef struct { PORT_SETTINGS port_settings; ///< current configuration of the port - uint32_t supp_baud_rates; ///< bit mask of baud rates supp. by this port, see ::MBG_BAUD_RATE_CODES - uint32_t supp_framings; ///< bit mask of framings supp. by this port, see ::MBG_FRAMING_CODES + uint32_t supp_baud_rates; ///< bit mask of baud rates supp. by this port, see ::MBG_BAUD_RATE_MASKS + uint32_t supp_framings; ///< bit mask of framings supp. by this port, see ::MBG_FRAMING_MASKS uint32_t supp_str_types; ///< bit mask of string types supp. by this port, i.e. bit 0 set if str_type[0] is supp. uint32_t reserved; ///< reserved for future use, currently always 0 - uint32_t flags; ///< @see COM_CFG_STATUS_BITS + uint32_t flags; ///< see ::PORT_INFO_FLAGS + } PORT_INFO; #define _mbg_swab_port_info( _p ) \ +do \ { \ _mbg_swab_port_settings( &(_p)->port_settings ); \ _mbg_swab32( &(_p)->supp_baud_rates ); \ @@ -2102,20 +3635,32 @@ typedef struct _mbg_swab32( &(_p)->supp_str_types ); \ _mbg_swab32( &(_p)->reserved ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) /** - * @brief Flags used with PORT_SETTINGS::flags and PORT_INFO::flags + * @brief Flags bits used to define ::PORT_INFO_FLAGS + * + * @see ::PORT_INFO_FLAGS */ -enum COM_CFG_STATUS_BITS +enum PORT_INFO_FLAG_BITS { - PORT_FLAG_BIT_PORT_INVISIBLE, ///< port is used internally and should not be displayed by config apps - N_PORT_FLAGS ///< the number of defined bits + PORT_INFO_FLAG_BIT_PORT_INVISIBLE, ///< port is used internally and should not be displayed by config apps + PORT_INFO_FLAG_BIT_BIN_PROT_HS, ///< port supports binary protocol at high speed, see ::MBG_DEFAULT_BAUDRATE_HS + N_PORT_INFO_FLAG_BITS ///< the number of defined bits }; -#define PORT_FLAG_PORT_INVISIBLE ( 1UL << PORT_FLAG_BIT_PORT_INVISIBLE ) +/** + * @brief Bit masks used with ::PORT_INFO::flags + * + * @see ::PORT_INFO_FLAG_BITS + */ +enum PORT_INFO_FLAGS +{ + PORT_INFO_FLAG_PORT_INVISIBLE = ( 1UL << PORT_INFO_FLAG_BIT_PORT_INVISIBLE ), ///< see ::PORT_INFO_FLAG_BIT_PORT_INVISIBLE + PORT_INFO_FLAG_BIN_PROT_HS = ( 1UL << PORT_INFO_FLAG_BIT_BIN_PROT_HS ) ///< see ::PORT_INFO_FLAG_BIT_BIN_PROT_HS +}; /** @@ -2124,22 +3669,24 @@ enum COM_CFG_STATUS_BITS * This structure should be read from the device to retrieve the * current settings of a specific serial port plus its capabilities, * e.g. supported baud rates, supported string formats, etc. - * The number of supported ports is RECEIVER_INFO::n_com_port. + * The number of supported ports is ::RECEIVER_INFO::n_com_ports. * * @note The ::PORT_SETTINGS_IDX structure should be send back to * the device to configure the specified serial port. */ typedef struct { - uint16_t idx; ///< port index, 0..RECEIVER_INFO::n_com_port - 1 + uint16_t idx; ///< port index, 0..::RECEIVER_INFO::n_com_ports-1 PORT_INFO port_info; + } PORT_INFO_IDX; #define _mbg_swab_port_info_idx( _p ) \ +do \ { \ _mbg_swab16( &(_p)->idx ); \ _mbg_swab_port_info( &(_p)->port_info ); \ -} +} while ( 0 ) /** @@ -2151,22 +3698,24 @@ typedef struct * The number of string types, and which string types are supported * depends on the device type and firmware version. * - * @note The structure ::STR_TYPE_INFO_IDX should be read repeatedly + * @note Multiple structures ::STR_TYPE_INFO_IDX should be read * to retrieve all supported string types. */ typedef struct { - uint32_t supp_modes; ///< bit mask of modes supp. for this string type + uint32_t supp_modes; ///< bit mask of modes supp. for this string type, see ::STR_MODE_MASKS char long_name[23]; ///< long name of the string format char short_name[11]; ///< short name of the string format uint16_t flags; ///< reserved, currently always 0 + } STR_TYPE_INFO; #define _mbg_swab_str_type_info( _p ) \ +do \ { \ _mbg_swab32( &(_p)->supp_modes ); \ _mbg_swab16( &(_p)->flags ); \ -} +} while ( 0 ) @@ -2176,81 +3725,114 @@ typedef struct * This structure should be read from a device to retrieve information * on a specific supported time string type from an array of supported * string types. The number of supported string types is returned - * in RECEIVER_INFO::n_str_type. + * in ::RECEIVER_INFO::n_str_type. * - * A selected index number can be saved in PORT_SETTINGS::str_type to + * A selected index number can be saved in ::PORT_SETTINGS::str_type to * configure the selected string type for the specific serial port. */ typedef struct { - uint16_t idx; ///< string type index, 0..RECEIVER_INFO::n_str_type - 1 + uint16_t idx; ///< string type index, 0..::RECEIVER_INFO::n_str_type-1 STR_TYPE_INFO str_type_info; + } STR_TYPE_INFO_IDX; #define _mbg_swab_str_type_info_idx( _p ) \ +do \ { \ _mbg_swab16( &(_p)->idx ); \ _mbg_swab_str_type_info( &(_p)->str_type_info ); \ -} +} while ( 0 ) /** - * @brief Modes supported for time string transmission + * @brief Enumeration of modes supported for time string transmission * * This determines e.g. at which point in time a string starts * to be transmitted via the serial port. + * Used with ::PORT_SETTINGS::mode. + * + * @see ::STR_MODE_MASKS */ enum STR_MODES { - STR_ON_REQ, ///< transmission on request by received '?' only + STR_ON_REQ, ///< transmission on request by received '?' character only STR_PER_SEC, ///< transmission automatically if second changes STR_PER_MIN, ///< transmission automatically if minute changes STR_AUTO, ///< transmission automatically if required, e.g. on capture event STR_ON_REQ_SEC, ///< transmission if second changes and a request has been received before + STR_CR_ON_SEC, ///< transmisson automatically if second changes, but carriage return (0x13) on time N_STR_MODE ///< the number of known modes }; +/** + * @brief Bit masks associated with ::STR_MODES + * + * Used with ::STR_TYPE_INFO::supp_modes to indicate which + * transmission modes are supported by the particular string type. + * + * @see ::STR_MODES + */ +enum STR_MODE_MASKS +{ + 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 +}; + + +/** + * @brief Initializer for short name strings associated with ::STR_MODES + * + * @see ::STR_MODES + */ #define DEFAULT_SHORT_MODE_NAMES \ { \ "'?'", \ "1 sec", \ "1 min", \ "auto", \ - "'?' sec" \ + "'?' sec", \ + "<CR> on sec" \ } -/* - * Default initializers for English mode string names. Initializers - * for multi-language strings can be found in pcpslstr.h. +/** + * @brief Default initializers for English mode name strings + * + * Initializers for multi-language strings can be found in pcpslstr.h. + * + * @see ::STR_MODES */ #define ENG_MODE_NAME_STR_ON_REQ "on request '?' only" #define ENG_MODE_NAME_STR_PER_SEC "per second" #define ENG_MODE_NAME_STR_PER_MIN "per minute" #define ENG_MODE_NAME_STR_AUTO "automatically" #define ENG_MODE_NAME_STR_ON_REQ_SEC "sec after request" +#define ENG_MODE_NAME_STR_CR_ON_SEC "per second, <CR> on second change" + +/** + * @brief Initializer for an English mode name string table + * + * Initializers for multi-language strings can be found in pcpslstr.h. + * + * @see ::STR_MODES + */ #define DEFAULT_ENG_MODE_NAMES \ { \ ENG_MODE_NAME_STR_ON_REQ, \ ENG_MODE_NAME_STR_PER_SEC, \ ENG_MODE_NAME_STR_PER_MIN, \ ENG_MODE_NAME_STR_AUTO, \ - ENG_MODE_NAME_STR_ON_REQ_SEC \ + ENG_MODE_NAME_STR_ON_REQ_SEC, \ + ENG_MODE_NAME_STR_CR_ON_SEC \ } -/* - * The definitions below are used to set up bit masks - * which restrict the modes which can be used with - * a given string type: - */ -#define MSK_STR_ON_REQ ( 1UL << STR_ON_REQ ) -#define MSK_STR_PER_SEC ( 1UL << STR_PER_SEC ) -#define MSK_STR_PER_MIN ( 1UL << STR_PER_MIN ) -#define MSK_STR_AUTO ( 1UL << STR_AUTO ) -#define MSK_STR_ON_REQ_SEC ( 1UL << STR_ON_REQ_SEC ) - /* * The modes below are supported by most string types: @@ -2275,8 +3857,56 @@ enum STR_MODES /** + * @brief The number of string types supported by legacy DCF77 receivers + * + * For receivers supporting a ::RECEIVER_INFO this should be determined + * from ::RECEIVER_INFO::n_str_type. + * + * @see ::DEFAULT_SUPP_STR_TYPES_DCF + */ +#define DEFAULT_N_STR_TYPE_DCF 1 + +/** + * @brief Bit mask of string types supported by legacy DCF77 receivers + * + * For receivers supporting a ::RECEIVER_INFO this should be determined + * from ::PORT_INFO::supp_str_types. + * + * @see ::DEFAULT_N_STR_TYPE_DCF + */ +#define DEFAULT_SUPP_STR_TYPES_DCF \ + ( ( 1UL << DEFAULT_N_STR_TYPE_DCF ) - 1 ) + + + +/** + * @brief The number of string types supported by legacy GPS receivers + * + * For receivers supporting a ::RECEIVER_INFO this should be determined + * from ::RECEIVER_INFO::n_str_type. + * + * @see ::DEFAULT_SUPP_STR_TYPES_GPS + */ +#define DEFAULT_N_STR_TYPE_GPS 2 + +/** + * @brief Bit mask of string types supported by legacy GPS receivers + * + * For receivers supporting a ::RECEIVER_INFO this should be determined + * from ::PORT_INFO::supp_str_types. + * + * @see ::DEFAULT_N_STR_TYPE_GPS + */ +#define DEFAULT_SUPP_STR_TYPES_GPS \ + ( ( 1UL << DEFAULT_N_STR_TYPE_GPS ) - 1 ) + + + +/* * The number of serial ports which are at least available - * even with very old GPS receiver models + * even with very old GPS receiver models. For devices providing + * a ::RECEIVER_INFO structure the number of provided COM ports + * is available in ::RECEIVER_INFO::n_com_ports. */ #define DEFAULT_N_COM 2 @@ -2289,18 +3919,22 @@ enum STR_MODES #endif /** - * @brief A The structure used to store the configuration of both serial ports + * @brief A The structure used to store the configuration of two serial ports * - * @deprecated This structure is deprecated, ::PORT_SETTINGS and related structures - * should be used instead, if supported by the device. + * @deprecated This structure is deprecated and should only be used + * with legacy GPS receivers that don't provide a ::RECEIVER_INFO structure. + * + * @see ::PORT_SETTINGS and ::PORT_INFO for current devices */ typedef struct { - COM_PARM com[DEFAULT_N_COM]; /**< COM0 and COM1 settings */ - uint8_t mode[DEFAULT_N_COM]; /**< COM0 and COM1 output mode */ + COM_PARM com[DEFAULT_N_COM]; ///< COM0 and COM1 settings + uint8_t mode[DEFAULT_N_COM]; ///< COM0 and COM1 output mode, see ::LGCY_STR_MODES + } PORT_PARM; #define _mbg_swab_port_parm( _p ) \ +do \ { \ int i; \ for ( i = 0; i < DEFAULT_N_COM; i++ ) \ @@ -2308,98 +3942,167 @@ typedef struct _mbg_swab_com_parm( &(_p)->com[i] ); \ /* no need to swap mode byte */ \ } \ -} +} while ( 0 ) -/* - * The codes below were used with the obsolete - * PORT_PARM.mode above. They are defined for - * compatibility with older devices only: - */ -enum -{ - /* STR_ON_REQ, defined above */ - /* STR_PER_SEC, defined above */ - /* STR_PER_MIN, defined above */ - N_STR_MODE_0 = STR_AUTO, /* COM0 and COM1 */ - STR_UCAP = N_STR_MODE_0, - STR_UCAP_REQ, - N_STR_MODE_1 /* COM1 only */ -}; - - - -/** - @defgroup group_icode IRIG codes - - The following definitions are used to configure an optional - on-board IRIG input or output. Which frame types are supported - by a device depends on the device type, and may eventually - depend on the device's firmware version. - - All IRIG frames transport the day-of-year number plus the time-of-day, - and include a control field segment which can transport user defined - information. - - Some newer IRIG frames are compatible with older frame types but support - well defined extensions like the year number, local time offset, DST status, - etc., in the control fields: - - - Supported IRIG signal code types: - - \b A002: 1000 bps, DCLS, time-of-year - - \b A003: 1000 bps, DCLS, time-of-year, SBS - - \b A132: 1000 bps, 10 kHz carrier, time-of-year - - \b A133: 1000 bps, 10 kHz carrier, time-of-year, SBS - - \b B002: 100 bps, DCLS, time-of-year - - \b B003: 100 bps, DCLS, time-of-year, SBS - - \b B122: 100 bps, 1 kHz carrier, time-of-year - - \b B123: 100 bps, 1 kHz carrier, time-of-year, SBS - - \b B006: 100 bps, DCLS, complete date - - \b B007: 100 bps, DCLS, complete date, SBS - - \b B126: 100 bps, 1 kHz carrier, complete date - - \b B127: 100 bps, 1 kHz carrier, complete date, SBS - - \b B220/1344: 100 bps, DCLS, manchester encoded, IEEE1344 extensions - - \b B222: 100 bps, DCLS, manchester encoded, time-of-year - - \b B223: 100 bps, DCLS, manchester encoded, time-of-year, SBS - - \b G002: 10 kbps, DCLS, time-of-year - - \b G142: 10 kbps, 100 kHz carrier, time-of-year - - \b G006: 10 kbps, DCLS, complete date - - \b G146: 10 kbps, 100 kHz carrier, complete date - - \b AFNOR: 100 bps, 1 kHz carrier, SBS, complete date - - <b> AFNOR DC:</b> 100 bps, DCLS, SBS, complete date - - \b IEEE1344: 100 bps, 1 kHz carrier, time-of-year, SBS, IEEE1344 extensions (B120) - - <b> IEEE1344 DC:</b> 100 bps, DCLS, time-of-year, SBS, IEEE1344 extensions (B000) - - \b C37.118: like IEEE1344, but %UTC offset with reversed sign - - \b C37.118 DC: like IEEE1344 DC, but %UTC offset with reversed sign - - - time-of-year: day-of-year, hours, minutes, seconds - - complete date: time-of-year plus year number - - SBS: straight binary seconds, second-of-day - - AFNOR codes are based on the french standard AFNOR NF S87-500 - - IEEE1344 codes are defined in IEEE standard 1344-1995. The code frame is compatible - with B002/B122 but provides some well defined extensions in the control field which - include a quality indicator (time figure of merit, TFOM), year number, DST and leap - second status, and local time offset from %UTC. - - C37.118 codes are defined in IEEE standard C37.118-2005 which includes a revised version - of the IEEE 1344 standard from 1995. These codes provide the same extensions as IEEE 1344 - but unfortunately define the %UTC offset with reversed sign. - - @note There are 3rd party IRIG devices out there which apply the %UTC offset as specified - in C37.118, but claim to be compatible with IEEE 1344. So if local time is transmitted - by the IRIG signal then care must be taken that the %UTC offset is evaluated by the IRIG - receiver in the same way as computed by the IRIG generator. Otherwise the %UTC - time computed by the receiver may be <b>wrong</b>. - @{ + +/** + * @brief Deprecated codes for serial string modes + * + * @deprecated These codes have been used with the + * deprecated ::PORT_PARM::mode field and are still + * defined for compatibility reasons. + * + * @see ::STR_MODES */ +enum LGCY_STR_MODES +{ + LGCY_STR_ON_REQ, ///< On request '?' only, same as ::STR_ON_REQ, COM0 and COM1 + LGCY_STR_PER_SEC, ///< Per second, same as ::STR_PER_SEC, COM0 and COM1 + LGCY_STR_PER_MIN, ///< Per minute, same as ::STR_PER_MIN, COM0 and COM1 + LGCY_STR_UCAP, ///< Automatically, when a capture event has occurred, COM1 only + LGCY_STR_UCAP_REQ, ///< On request only, if a capture event is available, COM1 only + N_LGCY_STR_MODES ///< Number of legacy string modes +}; + +#if _IS_MBG_FIRMWARE // Old symbols for source code compatibility ... + #define STR_UCAP LGCY_STR_UCAP // Same numeric value as ::STR_AUTO + #define STR_UCAP_REQ LGCY_STR_UCAP_REQ // Same numeric value as ::STR_ON_REQ_SEC, but different function + + #define N_STR_MODE_0 ( LGCY_STR_PER_MIN + 1 ) // Number of modes supp. for COM0 + #define N_STR_MODE_1 N_LGCY_STR_MODES // Number of modes supp. for COM1 +#endif + + + +/** + * @defgroup group_icode IRIG time codes + * + * The following definitions are used to configure an optional + * on-board IRIG input or output. Which frame types are supported + * by a device depends on the device type, and may eventually + * depend on the device's firmware version. + * + * All IRIG frames transport the day-of-year number plus the time-of-day, + * and include a control field segment which can transport user defined + * information. + * + * Some newer IRIG frames are compatible with older frame types but support + * well defined extensions like the year number, local time offset, DST status, + * etc., in the control fields: + * + * The following specification can be found in IRIG Standard 200-04 (September 2004): + * + * Format A: 1k pps + * Format B: 100 pps + * Format D: 1 ppm + * Format E: 10 pps + * Format G: 10k pps + * Format H: 1 pps + * + * 1st digit: Modulation Frequency + * 0 Pulse width code + * 1 Sine wave, amplitude modulated + * 2 Manchester modulated + * + * 2nd digit: Frequency / Resolution + * 0: No carrier / index count interval + * 1: 100 Hz / 10 ms + * 2: 1 kHz / 1 ms + * 3: 10 kHz / 0.1 ms + * 4: 100 kHz / 10 ms + * 5: 1 MHz / 1 ms + * + * 3rd digit: Coded expressions + * 0: DOY+TOD, CF, SBS + * 1: DOY+TOD, CF + * 2: DOY+TOD + * 3: DOY+TOD, SBS + * 4: DOY+TOD, Year, CF, SBS + * 5: DOY+TOD, Year, CF + * 6: DOY+TOD, Year + * 7: DOY+TOD, Year, SBS + * + * + * Table of Permissible Code Formats + * + * Letter 1st digit 2nd digit 3rd digit + * ---------------------------------------------- + * A 0,1,2 0,3,4,5 0,1,2,3,4,5,6,7 + * B 0,1,2 0,2,3,4,5 0,1,2,3,4,5,6,7 + * D 0,1 0,1,2 1,2 + * E 0,1 0,1,2 1,2,5,6 + * G 0,1,2 0,4,5 1,2,5,6 + * H 0,1 0,1,2 1,2 + * + * - Known IRIG signal code types: + * - \b A002: 1000 bps, DCLS, time-of-year + * - \b A003: 1000 bps, DCLS, time-of-year, SBS + * - \b A132: 1000 bps, 10 kHz carrier, time-of-year + * - \b A133: 1000 bps, 10 kHz carrier, time-of-year, SBS + * - \b B002: 100 bps, DCLS, time-of-year + * - \b B003: 100 bps, DCLS, time-of-year, SBS + * - \b B122: 100 bps, 1 kHz carrier, time-of-year + * - \b B123: 100 bps, 1 kHz carrier, time-of-year, SBS + * - \b B006: 100 bps, DCLS, complete date + * - \b B007: 100 bps, DCLS, complete date, SBS + * - \b B126: 100 bps, 1 kHz carrier, complete date + * - \b B127: 100 bps, 1 kHz carrier, complete date, SBS + * - \b B220/1344: 100 bps, DCLS, manchester encoded, IEEE1344 extensions + * - \b B222: 100 bps, DCLS, manchester encoded, time-of-year + * - \b B223: 100 bps, DCLS, manchester encoded, time-of-year, SBS + * - \b G002: 10 kbps, DCLS, time-of-year + * - \b G142: 10 kbps, 100 kHz carrier, time-of-year + * - \b G006: 10 kbps, DCLS, complete date + * - \b G146: 10 kbps, 100 kHz carrier, complete date + * - \b AFNOR: 100 bps, 1 kHz carrier, SBS, complete date + * - \b AFNOR DC: 100 bps, DCLS, SBS, complete date + * - \b IEEE1344: 100 bps, 1 kHz carrier, time-of-year, SBS, IEEE 1344 extensions (B120) + * - \b IEEE1344 DC: 100 bps, DCLS, time-of-year, SBS, IEEE 1344 extensions (B000) + * - \b C37.118: like IEEE 1344, but %UTC offset applied with reversed sign + * - \b C37.118 DC: like IEEE 1344 DC, but %UTC offset applied with reversed sign + * + * - time-of-year: day-of-year, hours, minutes, seconds + * - complete date: time-of-year plus year number + * - SBS: straight binary seconds, second-of-day + * + * AFNOR codes are based on the french standard AFNOR NF S87-500 + * + * IEEE 1344 codes are defined in IEEE standard 1344-1995. The code frame is compatible + * with B002/B122 but provides some well defined extensions in the control field which + * include a quality indicator (time figure of merit, TFOM), year number, DST and leap + * second status, and local time offset from %UTC. + * + * IEEE C37.118 codes are defined in IEEE standard C37.118-2005 which includes a revised version + * of the IEEE 1344 standard from 1995. These codes provide the same extensions as IEEE 1344 + * but unfortunately determine that the %UTC offset has to be applied with reversed sign. + * + * For example, if a -6 hours UTC offset is transmitted in the time code:<br> + * IEEE 1344: (IRIG time 14:43:27 h) - (offs -6 h) = (UTC 20:43:27)<br> + * IEEE C37.118: (IRIG time 14:43:27 h) + (offs -6 h) = (UTC 08:43:27)<br> + * + * @see @ref MSK_ICODE_RX_UTC_OFFS_ADD and @ref MSK_ICODE_RX_UTC_OFFS_SUB + * + * @note There are 3rd party IRIG devices out there which apply the %UTC offset as specified + * in IEEE C37.118-2005, but claim to be compatible with IEEE 1344. So if local time is transmitted + * by the timecode then care must be taken that the %UTC offset is evaluated by the timecode + * receiver in the same way as computed by the timecode generator. Otherwise the %UTC + * time computed by the receiver may be <b>wrong</b>. + * + * @{ */ /** * @brief Known IRIG TX code formats * - * Definitions used with IRIG transmitters which usually output both - * the unmodulated and the modulated IRIG signals at the same time. + * Used with ::IRIG_SETTINGS::icode for IRIG transmitters. + * For IRIG receivers see ::ICODE_RX_CODES. + * + * Meinberg timecode transmitters always generate the unmodulated (DCLS) + * and usually the modulated timecode signals internally at the same time, + * so the code definitions always refer to both. + * + * @note Not all device may provide both the modulated and unmodulated + * signal externally. */ enum ICODE_TX_CODES { @@ -2420,89 +4123,111 @@ enum ICODE_TX_CODES ICODE_TX_TXC101, ICODE_TX_E002_E112, ICODE_TX_NASA36, + ICODE_TX_A006_A136, + ICODE_TX_A007_A137, N_ICODE_TX ///< number of known codes }; /** - * Initializers for format name strings. + * @brief Initializers for TX timecode format name strings + * + * @see ::ICODE_TX_CODES */ -#define DEFAULT_ICODE_TX_NAMES \ -{ \ - "B002+B122", \ - "B003+B123", \ - "A002+A132", \ - "A003+A133", \ - "AFNOR NF S87-500", \ - "IEEE1344", \ - "B220(1344) DCLS", \ - "B222 DCLS", \ - "B223 DCLS", \ - "B006+B126", \ - "B007+B127", \ - "G002+G142", \ - "G006+G146", \ - "C37.118", \ - "TXC-101 DTR-6", \ - "E002+E112", \ - "NASA 36" \ -} - -/** - * Initializers for short name strings which must not - * be longer than 10 printable characters. +#define DEFAULT_ICODE_TX_NAMES \ +{ \ + /* B002_B122 */ "B002+B122", \ + /* B003_B123 */ "B003+B123", \ + /* A002_A132 */ "A002+A132", \ + /* A003_A133 */ "A003+A133", \ + /* AFNOR */ "AFNOR NF S87-500", \ + /* IEEE1344 */ "IEEE 1344", \ + /* B2201344 */ "B220(1344) DCLS", \ + /* B222 */ "B222 DCLS", \ + /* B223 */ "B223 DCLS", \ + /* B006_B126 */ "B006+B126", \ + /* B007_B127 */ "B007+B127", \ + /* G002_G142 */ "G002+G142", \ + /* G006_G146 */ "G006+G146", \ + /* C37118 */ "IEEE C37.118", \ + /* TXC101 */ "TXC-101 DTR-6", \ + /* E002_E112 */ "E002+E112", \ + /* NASA36 */ "NASA 36", \ + /* A006_A136 */ "A006+A136", \ + /* A007_A137 */ "A007+A137" \ +} + +/** + * @brief Initializers for short TX timecode format name strings + * + * @note Must not be longer than 10 printable characters + * + * @see ::ICODE_TX_CODES */ #define DEFAULT_ICODE_TX_NAMES_SHORT \ { \ - "B002+B122", \ - "B003+B123", \ - "A002+A132", \ - "A003+A133", \ - "AFNOR NF-S", \ - "IEEE1344", \ - "B220/1344", \ - "B222 DC", \ - "B223 DC", \ - "B006+B126", \ - "B007+B127", \ - "G002+G142", \ - "G006+G146", \ - "C37.118", \ - "TXC-101", \ - "E002+E112", \ - "NASA 36" \ -} - - -/** - * Initializers for English format description strings. - */ -#define DEFAULT_ICODE_TX_DESCRIPTIONS_ENG \ -{ \ - "100 bps, DCLS or 1 kHz carrier", \ - "100 bps, DCLS or 1 kHz carrier, SBS", \ - "1000 bps, DCLS or 10 kHz carrier", \ - "1000 bps, DCLS or 10 kHz carrier, SBS", \ - "100 bps, DCLS or 1 kHz carrier, SBS, complete date", \ - "100 bps, DCLS or 1 kHz carrier, SBS, complete date, time zone info", \ - "100 bps, Manchester enc., DCLS only, SBS, complete date, time zone info", \ - "100 bps, Manchester enc., DCLS only", \ - "100 bps, Manchester enc., DCLS only, SBS", \ - "100 bps, DCLS or 1 kHz carrier, complete date", \ - "100 bps, DCLS or 1 kHz carrier, complete date, SBS", \ - "10 kbps, DCLS or 100 kHz carrier", \ - "10 kbps, DCLS or 100 kHz carrier, complete date", \ - "like IEEE1344, but UTC offset with reversed sign", \ - "code from TV time sync device TXC-101 DTR-6", \ - "10 bps, DCLS or 100 Hz carrier", \ - "100 bps, DCLS or 1 kHz carrier" \ + /* B002_B122 */ "B002+B122", \ + /* B003_B123 */ "B003+B123", \ + /* A002_A132 */ "A002+A132", \ + /* A003_A133 */ "A003+A133", \ + /* AFNOR */ "AFNOR NF S", \ + /* IEEE1344 */ "IEEE 1344", \ + /* B2201344 */ "B220/1344", \ + /* B222 */ "B222 DC", \ + /* B223 */ "B223 DC", \ + /* B006_B126 */ "B006+B126", \ + /* B007_B127 */ "B007+B127", \ + /* G002_G142 */ "G002+G142", \ + /* G006_G146 */ "G006+G146", \ + /* C37118 */ "C37.118", \ + /* TXC101 */ "TXC-101", \ + /* E002_E112 */ "E002+E112", \ + /* NASA36 */ "NASA 36", \ + /* A006_A136 */ "A006+A136", \ + /* A007_A137 */ "A007+A137" \ } -/* - * The definitions below are used to set up bit masks - * which restrict the IRIG formats which are supported - * by a given IRIG transmitter device: - */ + +/** + * @brief Initializers for English TX format description strings + * + * @see ::ICODE_TX_CODES + */ +#define DEFAULT_ICODE_TX_DESCRIPTIONS_ENG \ +{ \ + /* B002_B122 */ "100 bps, DCLS or 1 kHz carrier", \ + /* B003_B123 */ "100 bps, DCLS or 1 kHz carrier, SBS", \ + /* A002_A132 */ "1000 bps, DCLS or 10 kHz carrier", \ + /* A003_A133 */ "1000 bps, DCLS or 10 kHz carrier, SBS", \ + /* AFNOR */ "100 bps, DCLS or 1 kHz carrier, complete date, SBS", \ + /* IEEE1344 */ "100 bps, DCLS or 1 kHz carrier, 2 digit year number, SBS, UTC offset, DST and Leap sec status", \ + /* B2201344 */ "100 bps, Manchester enc., DCLS only, 2 digit year number, SBS, UTC offset, DST and Leap sec status", \ + /* B222 */ "100 bps, Manchester enc., DCLS only", \ + /* B223 */ "100 bps, Manchester enc., DCLS only, SBS", \ + /* B006_B126 */ "100 bps, DCLS or 1 kHz carrier, 2 digit year number", \ + /* B007_B127 */ "100 bps, DCLS or 1 kHz carrier, 2 digit year number, SBS", \ + /* G002_G142 */ "10 kbps, DCLS or 100 kHz carrier", \ + /* G006_G146 */ "10 kbps, DCLS or 100 kHz carrier, 2 digit year number", \ + /* C37118 */ "100 bps, DCLS or 1 kHz carrier, 2 digit year number, SBS, UTC offs. reverse to 1344, DST/Leap sec status", \ + /* TXC101 */ "code from TV time sync device TXC-101 DTR-6", \ + /* E002_E112 */ "10 bps, DCLS or 100 Hz carrier", \ + /* NASA36 */ "100 bps, DCLS or 1 kHz carrier", \ + /* A006_A136 */ "1000 bps, DCLS or 10 kHz carrier, 2 digit year number", \ + /* A007_A137 */ "1000 bps, DCLS or 10 kHz carrier, 2 digit year number, SBS" \ +} + + +/** + * @brief Bit masks used with ::IRIG_INFO::supp_codes for TX + * + * These bit masks are used with timecode receivers only + * + * @see @ref ICODE_TX_CODES + * @see @ref ICODE_RX_CODES + * @see @ref ICODE_RX_MASKS + * + * @anchor ICODE_TX_MASKS @{ */ + #define MSK_ICODE_TX_B002_B122 ( 1UL << ICODE_TX_B002_B122 ) #define MSK_ICODE_TX_B003_B123 ( 1UL << ICODE_TX_B003_B123 ) #define MSK_ICODE_TX_A002_A132 ( 1UL << ICODE_TX_A002_A132 ) @@ -2520,19 +4245,24 @@ enum ICODE_TX_CODES #define MSK_ICODE_TX_TXC101 ( 1UL << ICODE_TX_TXC101 ) #define MSK_ICODE_TX_E002_E112 ( 1UL << ICODE_TX_E002_E112 ) #define MSK_ICODE_TX_NASA36 ( 1UL << ICODE_TX_NASA36 ) +#define MSK_ICODE_TX_A006_A136 ( 1UL << ICODE_TX_A006_A136 ) +#define MSK_ICODE_TX_A007_A137 ( 1UL << ICODE_TX_A007_A137 ) + +/** @} anchor ICODE_TX_MASKS */ + /** - * A mask of IRIG formats with manchester encoded DC output: + * @brief A mask of IRIG TX formats with manchester encoded DC output */ #define MSK_ICODE_TX_DC_MANCH \ ( \ - MSK_ICODE_TX_B2201344 | \ - MSK_ICODE_TX_B222 | \ + MSK_ICODE_TX_B2201344 | \ + MSK_ICODE_TX_B222 | \ MSK_ICODE_TX_B223 \ ) /** - * A mask of IRIG formats with 100 Hz carrier: + * @brief A mask of IRIG TX formats with 100 Hz carrier */ #define MSK_ICODE_TX_100HZ \ ( \ @@ -2540,7 +4270,7 @@ enum ICODE_TX_CODES ) /** - * A mask of IRIG formats with 1 kHz carrier: + * @brief A mask of IRIG TX formats with 1 kHz carrier */ #define MSK_ICODE_TX_1KHZ \ ( \ @@ -2558,25 +4288,27 @@ enum ICODE_TX_CODES ) /** - * A mask of IRIG formats with 10 kHz carrier: + * @brief A mask of IRIG TX formats with 10 kHz carrier */ #define MSK_ICODE_TX_10KHZ \ ( \ MSK_ICODE_TX_A002_A132 | \ - MSK_ICODE_TX_A003_A133 \ + MSK_ICODE_TX_A003_A133 | \ + MSK_ICODE_TX_A006_A136 | \ + MSK_ICODE_TX_A007_A137 \ ) /** - * A mask of IRIG formats with 100 kHz carrier: + * @brief A mask of IRIG TX formats with 100 kHz carrier */ #define MSK_ICODE_TX_100KHZ \ ( \ - MSK_ICODE_TX_G002_G142 | \ + MSK_ICODE_TX_G002_G142 | \ MSK_ICODE_TX_G006_G146 \ ) /** - * A mask of IRIG formats with 10 bps data rate: + * @brief A mask of IRIG TX formats with 10 bps data rate */ #define MSK_ICODE_TX_10BPS \ ( \ @@ -2584,58 +4316,191 @@ enum ICODE_TX_CODES ) /** - * A mask of IRIG formats with 100 bps data rate: + * @brief A mask of IRIG TX formats with 100 bps data rate */ #define MSK_ICODE_TX_100BPS \ ( \ - MSK_ICODE_TX_B002_B122 | \ - MSK_ICODE_TX_B003_B123 | \ - MSK_ICODE_TX_AFNOR | \ - MSK_ICODE_TX_IEEE1344 | \ - MSK_ICODE_TX_B006_B126 | \ - MSK_ICODE_TX_B007_B127 | \ + MSK_ICODE_TX_B002_B122 | \ + MSK_ICODE_TX_B003_B123 | \ + MSK_ICODE_TX_AFNOR | \ + MSK_ICODE_TX_IEEE1344 | \ + MSK_ICODE_TX_B006_B126 | \ + MSK_ICODE_TX_B007_B127 | \ MSK_ICODE_TX_C37118 \ ) /** - * A mask of IRIG formats with 1000 bps data rate: + * @brief A mask of IRIG TX formats with 1000 bps data rate */ #define MSK_ICODE_TX_1000BPS \ ( \ - MSK_ICODE_TX_A002_A132 | \ - MSK_ICODE_TX_A003_A133 \ + MSK_ICODE_TX_A002_A132 | \ + MSK_ICODE_TX_A003_A133 | \ + MSK_ICODE_TX_A006_A136 | \ + MSK_ICODE_TX_A007_A137 \ ) /** - * A mask of IRIG formats with 10 kbps data rate: + * @brief A mask of IRIG TX formats with 10 kbps data rate */ #define MSK_ICODE_TX_10000BPS \ ( \ - MSK_ICODE_TX_G002_G142 | \ + MSK_ICODE_TX_G002_G142 | \ MSK_ICODE_TX_G006_G146 \ ) /** - * A mask of IRIG formats which support TFOM: + * @brief A mask of IRIG TX formats supporting 10ths of seconds + */ +#define MSK_ICODE_TX_HAS_SEC10THS \ +( \ + MSK_ICODE_TX_A002_A132 | \ + MSK_ICODE_TX_A003_A133 | \ + MSK_ICODE_TX_G002_G142 | \ + MSK_ICODE_TX_G006_G146 | \ + MSK_ICODE_TX_A006_A136 | \ + MSK_ICODE_TX_A007_A137 \ +) + +/** + * @brief A mask of IRIG TX formats supporting 100ths of seconds + */ +#define MSK_ICODE_TX_HAS_SEC100THS \ +( \ + MSK_ICODE_TX_G002_G142 | \ + MSK_ICODE_TX_G006_G146 \ +) + +/** + * @brief A mask of IRIG TX formats providing a short year number after P5 + * + * The IEEE codes, the AFNOR codes, and some IRIG codes provide a + * 2 digit year number after position identifier P5. However, some + * IRIG G codes provide a 100ths-of-seconds field after P5,and + * eventually provide a year number after P6. + * + * @see @ref MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P6 + * @see @ref MSK_ICODE_TX_HAS_ANY_SHORT_YEAR + */ +#define MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P5 \ +( \ + MSK_ICODE_TX_AFNOR | \ + MSK_ICODE_TX_IEEE1344 | \ + MSK_ICODE_TX_B2201344 | \ + MSK_ICODE_TX_B006_B126 | \ + MSK_ICODE_TX_B007_B127 | \ + MSK_ICODE_TX_C37118 | \ + MSK_ICODE_TX_A006_A136 | \ + MSK_ICODE_TX_A007_A137 \ +) + +/** + * @brief A mask of IRIG TX formats providing a short year number after P6 + * + * While most time codes that provide a year number do this after P5, + * there are some IRIG codes which provide a 100ths-of-seconds field + * at that position, and eventually provide a year number after P6. + * + * @see @ref MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P5 + * @see @ref MSK_ICODE_TX_HAS_ANY_SHORT_YEAR + */ + #define MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P6 \ +( \ + MSK_ICODE_TX_G006_G146 \ +) + +/** + * @brief A mask of IRIG TX formats providing a short year number in general + * + * Depending on the code format, the year number can be transmitted + * either after position identifier P5, or after P6. + * + * @see @ref MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P5 + * @see @ref MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P6 + */ +#define MSK_ICODE_TX_HAS_ANY_SHORT_YEAR \ +( \ + MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P5 | \ + MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P6 \ +) + +/** + * @brief A mask of IRIG TX formats supporting TFOM */ #define MSK_ICODE_TX_HAS_TFOM \ ( \ - MSK_ICODE_TX_IEEE1344 | \ + MSK_ICODE_TX_IEEE1344 | \ MSK_ICODE_TX_C37118 \ ) /** - * A mask of IRIG formats which support time zone information: + * @brief A mask of IRIG TX formats supporting CTQ continuous time quality + * + * This has been introduced in IEEE C37.118.1-2011 + */ +#define MSK_ICODE_TX_HAS_CTQ \ +( \ + MSK_ICODE_TX_IEEE1344 | \ + MSK_ICODE_TX_C37118 \ +) + +/** + * @brief A mask of IRIG TX formats supporting time zone information */ #define MSK_ICODE_TX_HAS_TZI \ ( \ - MSK_ICODE_TX_IEEE1344 | \ + MSK_ICODE_TX_IEEE1344 | \ MSK_ICODE_TX_C37118 \ ) /** - * The default mask of IRIG formats supported by - * IRIG transmitters: + * @brief IRIG 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) + */ +#define MSK_ICODE_TX_UTC_OFFS_SUB \ +( \ + MSK_ICODE_TX_IEEE1344 \ +) + +/** + * @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) + */ +#define MSK_ICODE_TX_UTC_OFFS_ADD \ +( \ + MSK_ICODE_TX_C37118 \ +) + +/** + * @brief A mask of IRIG TX formats supporting a day of week number + */ +#define MSK_ICODE_TX_HAS_AFNOR_WDAY \ +( \ + MSK_ICODE_TX_AFNOR | \ + MSK_ICODE_TX_AFNOR_DC \ +) + +/** + * @brief A mask of IRIG TX formats supporting a date (day-of-month, month) + */ +#define MSK_ICODE_TX_HAS_AFNOR_DATE \ +( \ + MSK_ICODE_TX_AFNOR | \ + MSK_ICODE_TX_AFNOR_DC \ +) + + +/** + * @brief The default mask of IRIG TX formats supported by IRIG transmitters + * + * @note The formats which are actually supported should be retrieved + * from the device */ #if !defined( SUPP_MSK_ICODE_TX ) #define SUPP_MSK_ICODE_TX \ @@ -2653,9 +4518,14 @@ enum ICODE_TX_CODES /** * @brief Known IRIG RX code formats * - * Definitions used with IRIG receivers which decode - * two similar IRIG codes (with or without SBS) - * at the same time. + * Used with ::IRIG_SETTINGS::icode for IRIG receivers. + * For IRIG transmitters see ::ICODE_TX_CODES. + * + * The SBS value is redundant and can easily by computed + * from the time-of-day, so Meinberg time code receivers + * usually don't evaluate the SBS field anyway, and thus + * it makes no difference if a code with or withour SBS + * is supplied. */ enum ICODE_RX_CODES { @@ -2669,8 +4539,8 @@ enum ICODE_RX_CODES ICODE_RX_IEEE1344_DC, ///< DCLS ICODE_RX_B126_B127, ///< modulated ICODE_RX_B006_B007, ///< DCLS - ICODE_RX_G142_G146, ///< modulated - ICODE_RX_G002_G006, ///< DCLS + ICODE_RX_G142, ///< modulated (G143 is undefined, SBS not supported with Gxxx) + ICODE_RX_G002, ///< DCLS (G003 is undefined, SBS not supported with Gxxx) ICODE_RX_C37118, ///< modulated ICODE_RX_C37118_DC, ///< DCLS ICODE_RX_TXC101, ///< modulated @@ -2679,95 +4549,126 @@ enum ICODE_RX_CODES ICODE_RX_E002, ///< DCLS ICODE_RX_NASA36, ///< modulated ICODE_RX_NASA36_DC, ///< DCLS + ICODE_RX_A136_A137, ///< modulated + ICODE_RX_A006_A007, ///< DCLS + ICODE_RX_G146, ///< modulated (G147 is undefined, SBS not supported with Gxxx) + ICODE_RX_G006, ///< DCLS (G007 is undefined, SBS not supported with Gxxx) N_ICODE_RX ///< the number of known codes }; /** - * Initializers for format name strings. + * @brief Initializers for RX timecode format name strings + * + * @see ::ICODE_RX_CODES */ #define DEFAULT_ICODE_RX_NAMES \ { \ - "B122/B123", \ - "A132/A133", \ - "B002/B003 (DCLS)", \ - "A002/A003 (DCLS)", \ - "AFNOR NF S87-500", \ - "AFNOR NF S87-500 (DCLS)", \ - "IEEE1344", \ - "IEEE1344 (DCLS)", \ - "B126/B127", \ - "B006/B007 (DCLS)", \ - "G142/G146", \ - "G002/G006 (DCLS)", \ - "C37.118", \ - "C37.118 (DCLS)", \ - "TXC-101 DTR-6", \ - "TXC-101 DTR-6 (DCLS)", \ - "E112", \ - "E002 (DCLS)", \ - "NASA-36", \ - "NASA-36 (DCLS)" \ -} - -/** - * Initializers for short name strings which must not - * be longer than 11 printable characters. - */ -#define DEFAULT_ICODE_RX_NAMES_SHORT \ -{ \ - "B122/B123", \ - "A132/A133", \ - "B002/B003", \ - "A002/A003", \ - "AFNOR NF-S", \ - "AFNOR DC", \ - "IEEE1344", \ - "IEEE1344 DC", \ - "B126/B127", \ - "B006/B007", \ - "G142/G146", \ - "G002/G006", \ - "C37.118", \ - "C37.118 DC", \ - "TXC-101", \ - "TXC-101 DC", \ - "E112", \ - "E002 DC", \ - "NASA-36", \ - "NASA-36 DC" \ -} - - -/** - * Initializers for English format description strings. - */ -#define DEFAULT_ICODE_RX_DESCRIPTIONS_ENG \ -{ \ - "100 bps, 1 kHz carrier, SBS optionally", \ - "1000 bps, 10 kHz carrier, SBS optionally", \ - "100 bps, DCLS, SBS optionally", \ - "1000 bps, DCLS, SBS optionally", \ - "100 bps, 1 kHz carrier, SBS, complete date", \ - "100 bps, DCLS, SBS, complete date", \ - "100 bps, 1 kHz carrier, SBS, time zone info", \ - "100 bps, DCLS, SBS, time zone info", \ - "100 bps, 1 kHz carrier, complete date, SBS optionally", \ - "100 bps, DCLS, complete date, SBS optionally", \ - "10 kbps, 100 kHz carrier, complete date optionally", \ - "10 kbps, DCLS, complete date optionally", \ - "like IEEE1344, but UTC offset with reversed sign", \ - "like IEEE1344 DC, but UTC offset with reversed sign", \ - "code from TV time sync device TXC-101 DTR-6", \ - "DC code from TV time sync device TXC-101 DTR-6", \ - "10 bps, 100 Hz carrier", \ - "10 bps, DCLS", \ - "100 bps, 1 kHz carrier", \ - "100 bps, DCLS" \ + /* B122_B123 */ "B122/B123", \ + /* A132_A133 */ "A132/A133", \ + /* B002_B003 */ "B002/B003 (DCLS)", \ + /* A002_A003 */ "A002/A003 (DCLS)", \ + /* AFNOR */ "AFNOR NF S87-500", \ + /* AFNOR_DC */ "AFNOR NF S87-500 (DCLS)", \ + /* IEEE1344 */ "IEEE1344", \ + /* IEEE1344_DC */ "IEEE1344 (DCLS)", \ + /* B126_B127 */ "B126/B127", \ + /* B006_B007 */ "B006/B007 (DCLS)", \ + /* G142 */ "G142", \ + /* G002 */ "G002 (DCLS)", \ + /* C37118 */ "C37.118", \ + /* C37118_DC */ "C37.118 (DCLS)", \ + /* TXC101 */ "TXC-101 DTR-6", \ + /* TXC101_DC */ "TXC-101 DTR-6 (DCLS)", \ + /* E112 */ "E112", \ + /* E002 */ "E002 (DCLS)", \ + /* NASA36 */ "NASA-36", \ + /* NASA36_DC */ "NASA-36 (DCLS)", \ + /* A136_A137 */ "A136/A137", \ + /* A006_A007 */ "A006/A007 (DCLS)", \ + /* G146 */ "G146", \ + /* G006 */ "G006 (DCLS)" \ } -/* - * Bit masks corresponding to the enumeration above: +/** + * @brief Initializers for short RX timecode format name strings + * + * @note Must not be longer than 11 printable characters + * + * @see ::ICODE_RX_CODES */ +#define DEFAULT_ICODE_RX_NAMES_SHORT \ +{ \ + /* B122_B123 */ "B122/B123", \ + /* A132_A133 */ "A132/A133", \ + /* B002_B003 */ "B002/B003", \ + /* A002_A003 */ "A002/A003", \ + /* AFNOR */ "AFNOR NF S", \ + /* AFNOR_DC */ "AFNOR DC", \ + /* IEEE1344 */ "IEEE1344", \ + /* IEEE1344_DC */ "IEEE1344 DC", \ + /* B126_B127 */ "B126/B127", \ + /* B006_B007 */ "B006/B007", \ + /* G142 */ "G142", \ + /* G002 */ "G002 DC", \ + /* C37118 */ "C37.118", \ + /* C37118_DC */ "C37.118 DC", \ + /* TXC101 */ "TXC-101", \ + /* TXC101_DC */ "TXC-101 DC", \ + /* E112 */ "E112", \ + /* E002 */ "E002 DC", \ + /* NASA36 */ "NASA-36", \ + /* NASA36_DC */ "NASA-36 DC", \ + /* A136_A137 */ "A136/A137", \ + /* A006_A007 */ "A006/A007", \ + /* G146 */ "G146", \ + /* G006 */ "G006 DC" \ +} + + +/** + * @brief Initializers for English RX format description strings + * + * @see ::ICODE_RX_CODES + */ +#define DEFAULT_ICODE_RX_DESCRIPTIONS_ENG \ +{ \ + /* B122_B123 */ "100 bps, 1 kHz carrier, SBS optionally", \ + /* A132_A133 */ "1000 bps, 10 kHz carrier, SBS optionally", \ + /* B002_B003 */ "100 bps, DCLS, SBS optionally", \ + /* A002_A003 */ "1000 bps, DCLS, SBS optionally", \ + /* AFNOR */ "100 bps, 1 kHz carrier, complete date, SBS", \ + /* AFNOR_DC */ "100 bps, DCLS, complete date, SBS", \ + /* IEEE1344 */ "100 bps, 1 kHz carrier, SBS, time zone info", \ + /* IEEE1344_DC */ "100 bps, DCLS, SBS, time zone info", \ + /* B126_B127 */ "100 bps, 1 kHz carrier, 2 digit year number, SBS optionally", \ + /* B006_B007 */ "100 bps, DCLS, 2 digit year number, SBS optionally", \ + /* G142 */ "10 kbps, 100 kHz carrier", \ + /* G002 */ "10 kbps, DCLS", \ + /* C37118 */ "like IEEE1344, but UTC offset with reversed sign", \ + /* C37118_DC */ "like IEEE1344 DC, but UTC offset with reversed sign", \ + /* TXC101 */ "code from TV time sync device TXC-101 DTR-6", \ + /* TXC101_DC */ "DC code from TV time sync device TXC-101 DTR-6", \ + /* E112 */ "10 bps, 100 Hz carrier", \ + /* E002 */ "10 bps, DCLS", \ + /* NASA36 */ "100 bps, 1 kHz carrier", \ + /* NASA36_DC */ "100 bps, DCLS", \ + /* A136_A137 */ "1000 bps, 10 kHz carrier, 2 digit year number, SBS optionally", \ + /* A006_A007 */ "1000 bps, DCLS, 2 digit year number, SBS optionally", \ + /* G146 */ "10 kbps, 100 kHz carrier, 2 digit year number", \ + /* G006 */ "10 kbps, DCLS, 2 digit year number" \ +} + +/** + * @brief Bit masks used with ::IRIG_INFO::supp_codes for RX + * + * These bit masks are used with timecode receivers only + * + * @see @ref ICODE_RX_CODES + * @see @ref ICODE_TX_CODES + * @see @ref ICODE_TX_MASKS + * + * @anchor ICODE_RX_MASKS @{ */ + #define MSK_ICODE_RX_B122_B123 ( 1UL << ICODE_RX_B122_B123 ) #define MSK_ICODE_RX_A132_A133 ( 1UL << ICODE_RX_A132_A133 ) #define MSK_ICODE_RX_B002_B003 ( 1UL << ICODE_RX_B002_B003 ) @@ -2778,8 +4679,8 @@ enum ICODE_RX_CODES #define MSK_ICODE_RX_IEEE1344_DC ( 1UL << ICODE_RX_IEEE1344_DC ) #define MSK_ICODE_RX_B126_B127 ( 1UL << ICODE_RX_B126_B127 ) #define MSK_ICODE_RX_B006_B007 ( 1UL << ICODE_RX_B006_B007 ) -#define MSK_ICODE_RX_G142_G146 ( 1UL << ICODE_RX_G142_G146 ) -#define MSK_ICODE_RX_G002_G006 ( 1UL << ICODE_RX_G002_G006 ) +#define MSK_ICODE_RX_G142 ( 1UL << ICODE_RX_G142 ) +#define MSK_ICODE_RX_G002 ( 1UL << ICODE_RX_G002 ) #define MSK_ICODE_RX_C37118 ( 1UL << ICODE_RX_C37118 ) #define MSK_ICODE_RX_C37118_DC ( 1UL << ICODE_RX_C37118_DC ) #define MSK_ICODE_RX_TXC101 ( 1UL << ICODE_RX_TXC101 ) @@ -2788,9 +4689,16 @@ enum ICODE_RX_CODES #define MSK_ICODE_RX_E002 ( 1UL << ICODE_RX_E002 ) #define MSK_ICODE_RX_NASA36 ( 1UL << ICODE_RX_NASA36 ) #define MSK_ICODE_RX_NASA36_DC ( 1UL << ICODE_RX_NASA36_DC ) +#define MSK_ICODE_RX_A136_A137 ( 1UL << ICODE_RX_A136_A137 ) +#define MSK_ICODE_RX_A006_A007 ( 1UL << ICODE_RX_A006_A007 ) +#define MSK_ICODE_RX_G146 ( 1UL << ICODE_RX_G146 ) +#define MSK_ICODE_RX_G006 ( 1UL << ICODE_RX_G006 ) + +/** @} anchor ICODE_RX_MASKS */ + /** - * A mask of IRIG DCLS formats: + * @brief A mask of IRIG RX DCLS formats */ #define MSK_ICODE_RX_DC \ ( \ @@ -2799,24 +4707,25 @@ enum ICODE_RX_CODES MSK_ICODE_RX_AFNOR_DC | \ MSK_ICODE_RX_IEEE1344_DC | \ MSK_ICODE_RX_B006_B007 | \ - MSK_ICODE_RX_G002_G006 | \ + MSK_ICODE_RX_G002 | \ MSK_ICODE_RX_C37118_DC | \ MSK_ICODE_RX_TXC101_DC | \ MSK_ICODE_RX_E002 | \ - MSK_ICODE_RX_NASA36_DC \ + MSK_ICODE_RX_NASA36_DC | \ + MSK_ICODE_RX_A006_A007 | \ + MSK_ICODE_RX_G006 \ ) /** - * A mask of IRIG formats with 100 Hz carrier: + * @brief A mask of IRIG RX formats with 100 Hz carrier */ #define MSK_ICODE_RX_100HZ \ ( \ - MSK_ICODE_RX_E112 | \ - MSK_ICODE_RX_E002 \ + MSK_ICODE_RX_E112 \ ) /** - * A mask of IRIG formats with 1 kHz carrier: + * @brief A mask of IRIG RX formats with 1 kHz carrier */ #define MSK_ICODE_RX_1KHZ \ ( \ @@ -2830,23 +4739,25 @@ enum ICODE_RX_CODES ) /** - * A mask of IRIG formats with 10 kHz carrier: + * @brief A mask of IRIG RX formats with 10 kHz carrier */ #define MSK_ICODE_RX_10KHZ \ ( \ - MSK_ICODE_RX_A132_A133 \ + MSK_ICODE_RX_A132_A133 | \ + MSK_ICODE_RX_A136_A137 \ ) /** - * A mask of IRIG formats with 100 kHz carrier: + * @brief A mask of IRIG RX formats with 100 kHz carrier */ #define MSK_ICODE_RX_100KHZ \ ( \ - MSK_ICODE_RX_G142_G146 \ + MSK_ICODE_RX_G142 | \ + MSK_ICODE_RX_G146 \ ) /** - * A mask of IRIG formats with 10 bps data rate: + * @brief A mask of IRIG RX formats with 10 bps data rate */ #define MSK_ICODE_RX_10BPS \ ( \ @@ -2855,7 +4766,7 @@ enum ICODE_RX_CODES ) /** - * A mask of IRIG formats with 100 bps data rate: + * @brief A mask of IRIG RX formats with 100 bps data rate */ #define MSK_ICODE_RX_100BPS \ ( \ @@ -2876,25 +4787,110 @@ enum ICODE_RX_CODES ) /** - * A mask of IRIG formats with 1000 bps data rate: + * @brief A mask of IRIG RX formats with 1000 bps data rate */ #define MSK_ICODE_RX_1000BPS \ ( \ - MSK_ICODE_RX_A132_A133 | \ - MSK_ICODE_RX_A002_A003 \ + MSK_ICODE_RX_A132_A133 | \ + MSK_ICODE_RX_A002_A003 | \ + MSK_ICODE_RX_A136_A137 | \ + MSK_ICODE_RX_A006_A007 \ ) /** - * A mask of IRIG formats with 10 kbps data rate: + * @brief A mask of IRIG RX formats with 10 kbps data rate */ #define MSK_ICODE_RX_10000BPS \ ( \ - MSK_ICODE_RX_G142_G146 | \ - MSK_ICODE_RX_G002_G006 \ + MSK_ICODE_RX_G142 | \ + MSK_ICODE_RX_G002 | \ + MSK_ICODE_RX_G146 | \ + MSK_ICODE_RX_G006 \ +) + +/** + * @brief A mask of IRIG RX formats supporting 10ths of seconds + */ +#define MSK_ICODE_RX_HAS_SEC10THS \ +( \ + MSK_ICODE_RX_A132_A133 | \ + MSK_ICODE_RX_A002_A003 | \ + MSK_ICODE_RX_G142 | \ + MSK_ICODE_RX_G002 | \ + MSK_ICODE_RX_A136_A137 | \ + MSK_ICODE_RX_A006_A007 | \ + MSK_ICODE_RX_G146 | \ + MSK_ICODE_RX_G006 \ +) + +/** + * @brief A mask of IRIG RX formats which support 100ths of seconds + */ +#define MSK_ICODE_RX_HAS_SEC100THS \ +( \ + MSK_ICODE_RX_G142 | \ + MSK_ICODE_RX_G002 | \ + MSK_ICODE_RX_G146 | \ + MSK_ICODE_RX_G006 \ ) /** - * A mask of IRIG formats which support TFOM: + * @brief A mask of IRIG RX formats supporting a 2 digit year number after P5 + * + * Note: This macro specifies ONLY the codes where the year number + * is transmitted after position identifier P5. + * + * @see ::MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P6 + * @see ::MSK_ICODE_RX_HAS_ANY_SHORT_YEAR + */ +#define MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P5 \ +( \ + MSK_ICODE_RX_AFNOR | \ + MSK_ICODE_RX_AFNOR_DC | \ + MSK_ICODE_RX_IEEE1344 | \ + MSK_ICODE_RX_IEEE1344_DC | \ + MSK_ICODE_RX_B126_B127 | \ + MSK_ICODE_RX_B006_B007 | \ + MSK_ICODE_RX_C37118 | \ + MSK_ICODE_RX_C37118_DC | \ + MSK_ICODE_RX_A136_A137 | \ + MSK_ICODE_RX_A006_A007 \ +) + +/** + * @brief A mask of IRIG RX formats supporting a 2 digit year number after P6 + * + * Note: This macro specifies ONLY the codes where the year number + * is transmitted after position identifier P6. + * + * @see ::MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P5 + * @see ::MSK_ICODE_RX_HAS_ANY_SHORT_YEAR + */ +#define MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P6 \ +( \ + MSK_ICODE_RX_G146 | \ + MSK_ICODE_RX_G006 \ +) + +/** + * @brief A mask of IRIG RX formats providing any 2 digit year number + * + * Note: Different sets of code frames may provide a year number + * in different locations of the transmitted code. + * + * @see ::MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P5 + * @see ::MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P6 + */ +#define MSK_ICODE_RX_HAS_ANY_SHORT_YEAR \ +( \ + MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P5 | \ + MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P6 \ +) + + + +/** + * @brief A mask of IRIG RX formats supporting TFOM time quality indicator */ #define MSK_ICODE_RX_HAS_TFOM \ ( \ @@ -2905,7 +4901,20 @@ enum ICODE_RX_CODES ) /** - * A mask of IRIG formats which support time zone information: + * @brief A mask of IRIG RX formats supporting CTQ continuous time quality + * + * This has been introduced in IEEE C37.118.1-2011 + */ +#define MSK_ICODE_RX_HAS_CTQ \ +( \ + MSK_ICODE_RX_IEEE1344 | \ + MSK_ICODE_RX_IEEE1344_DC | \ + MSK_ICODE_RX_C37118 | \ + MSK_ICODE_RX_C37118_DC \ +) + +/** + * @brief A mask of IRIG RX formats supporting time zone information */ #define MSK_ICODE_RX_HAS_TZI \ ( \ @@ -2916,8 +4925,55 @@ enum ICODE_RX_CODES ) /** - * The default mask of IRIG formats supported by - * IRIG receivers: + * @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) + */ +#define MSK_ICODE_RX_UTC_OFFS_SUB \ +( \ + MSK_ICODE_RX_IEEE1344 | \ + MSK_ICODE_RX_IEEE1344_DC \ +) + +/** + * @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) + */ +#define MSK_ICODE_RX_UTC_OFFS_ADD \ +( \ + MSK_ICODE_RX_C37118 | \ + MSK_ICODE_RX_C37118_DC \ +) + +/** + * @brief A mask of IRIG RX formats supporting a day of week number + */ +#define MSK_ICODE_RX_HAS_AFNOR_WDAY \ +( \ + MSK_ICODE_RX_AFNOR | \ + MSK_ICODE_RX_AFNOR_DC \ +) + +/** + * @brief A mask of IRIG RX formats supporting a date (day-of-month, month) + */ +#define MSK_ICODE_RX_HAS_AFNOR_DATE \ +( \ + MSK_ICODE_RX_AFNOR | \ + MSK_ICODE_RX_AFNOR_DC \ +) + + +/** + * @brief The default mask of IRIG RX formats supported by IRIG receivers + * + * @note The formats which are actually supported should be retrieved + * from the device */ #if !defined( SUPP_MSK_ICODE_RX ) #define SUPP_MSK_ICODE_RX \ @@ -2931,50 +4987,62 @@ enum ICODE_RX_CODES ) #endif -/** @} group_icode */ +/** @} defgroup group_icode */ /** * @brief Configuration settings of an IRIG input or output * - * @see group_icode + * @see @ref group_icode */ typedef struct { - uint16_t icode; ///< IRIG signal code, see ::ICODE_RX_CODES - uint16_t flags; ///< see ::IFLAGS_BITS + uint16_t icode; ///< IRIG signal code, see ::ICODE_RX_CODES and ::ICODE_TX_CODES + uint16_t flags; ///< see ::IFLAGS_BIT_MASKS + } IRIG_SETTINGS; #define _mbg_swab_irig_settings( _p ) \ +do \ { \ _mbg_swab16( &(_p)->icode ); \ _mbg_swab16( &(_p)->flags ); \ -} +} while ( 0 ) /** - * @brief Bits used with IRIG_SETTINGS::flags + * @brief Flag bits used to define ::IFLAGS_BIT_MASKS * - * @note The presence or absence of the ::IFLAGS_BIT_DISABLE_TFOM flag for the IRIG RX - * settings of some PCI cards may not be evaluated correctly by some firmware - * versions for those cards, even if an IRIG code has been configured which supports - * this flag. See the comments near the declaration of the _pcps_incoming_tfom_ignored() - * macro in pcpsdev.h for details. + * @see ::IFLAGS_BIT_MASKS */ enum IFLAGS_BITS { IFLAGS_BIT_DISABLE_TFOM, ///< for RX ignore, for TX don't generate TFOM flag - IFLAGS_BIT_TX_GEN_LOCAL_TIME, ///< TX output local time, not %UTC + IFLAGS_BIT_TX_GEN_LOCAL_TIME, ///< TX output local time instead of %UTC N_IFLAGS_BITS ///< number of known bits }; -#define IFLAGS_DISABLE_TFOM ( 1UL << IFLAGS_BIT_DISABLE_TFOM ) -#define IFLAGS_TX_GEN_LOCAL_TIME ( 1UL << IFLAGS_BIT_TX_GEN_LOCAL_TIME ) -#define IFLAGS_MASK ( ( 1UL << N_IFLAGS_BITS ) - 1 ) ///< mask of all known flags +/** + * @brief Bit masks used with ::IRIG_SETTINGS::flags + * + * @note The presence or absence of the ::IFLAGS_DISABLE_TFOM flag for the IRIG RX + * settings of some PCI cards may not be evaluated correctly by some firmware + * versions for those cards, even if an IRIG code has been configured which supports + * this flag. See the comments near the declaration of the ::_pcps_incoming_tfom_ignored + * macro in pcpsdev.h for details. + * + * @see ::IFLAGS_BITS + */ +enum IFLAGS_BIT_MASKS +{ + IFLAGS_DISABLE_TFOM = ( 1UL << IFLAGS_BIT_DISABLE_TFOM ), ///< see ::IFLAGS_BIT_DISABLE_TFOM + IFLAGS_TX_GEN_LOCAL_TIME = ( 1UL << IFLAGS_BIT_TX_GEN_LOCAL_TIME ), ///< see ::IFLAGS_BIT_TX_GEN_LOCAL_TIME + IFLAGS_MASK = ( ( 1UL << N_IFLAGS_BITS ) - 1 ) ///< mask of all known flags +}; /** @@ -2986,14 +5054,16 @@ enum IFLAGS_BITS typedef struct { IRIG_SETTINGS settings; ///< current settings - uint32_t supp_codes; ///< bit mask of supported codes + uint32_t supp_codes; ///< see @ref ICODE_TX_MASKS and @ref ICODE_RX_MASKS + } IRIG_INFO; #define _mbg_swab_irig_info( _p ) \ +do \ { \ _mbg_swab_irig_settings( &(_p)->settings ); \ _mbg_swab32( &(_p)->supp_codes ); \ -} +} while ( 0 ) /** @@ -3003,6 +5073,7 @@ typedef struct * which is supported by some IRIG receivers. Delay compensation * depends on the basic frame type, so there are different records * required for the different frame type groups. + * * @{ */ /** @@ -3028,14 +5099,15 @@ typedef struct } IRIG_RX_COMP; #define _mbg_swab_irig_rx_comp( _p ) \ +do \ { \ int i; \ for ( i = 0; i < N_IRIG_RX_COMP_VAL; i++ ) \ _mbg_swab16( &(_p)->c[i] ); \ -} +} while ( 0 ) -/** The absolute value of the maximum compensation value accepted by a device */ +/** The absolute value of the maximum compensation value accepted by a device */ #define IRIG_RX_COMP_MAX 999 // [100 ns units], i.e. valid range is +/-99.9 us @@ -3045,19 +5117,21 @@ typedef struct */ typedef struct { - uint16_t type; ///< record type @see CAL_REC_TYPES + uint16_t type; ///< record type, see ::CAL_REC_TYPES uint16_t idx; ///< index if several records of same type are supported, see ::IRIG_RX_COMP_GROUPS + } CAL_REC_HDR; #define _mbg_swab_cal_rec_hdr( _p ) \ +do \ { \ _mbg_swab16( &(_p)->type ); \ _mbg_swab16( &(_p)->idx ); \ -} +} while ( 0 ) /** - * @brief Types to be used with CAL_REC_HDR::type + * @brief Types to be used with ::CAL_REC_HDR::type */ enum CAL_REC_TYPES { @@ -3068,7 +5142,7 @@ enum CAL_REC_TYPES /** - * @brief Types to be used with CAL_REC_HDR::idx + * @brief Types to be used with ::CAL_REC_HDR::idx * * IRIG frame type groups to be distinguished for delay compensation. */ @@ -3104,27 +5178,30 @@ enum IRIG_RX_COMP_GROUPS */ typedef struct { - CAL_REC_HDR hdr; + CAL_REC_HDR hdr; ///< data header IRIG_RX_COMP comp_data; ///< IRIG receiver delay compensation } CAL_REC_IRIG_RX_COMP; #define _mbg_swab_cal_rec_irig_rx_comp( _p ) \ +do \ { \ _mbg_swab_cal_rec_hdr( &(_p)->hdr ); \ _mbg_swab_irig_rx_comp( &(_p)->comp_data ); \ -} +} while ( 0 ) -/** @} group_irig_comp */ +/** @} defgroup group_irig_comp */ /** * @brief A data type used to read the board's debug status * - * @note This also include IRIG decoder status. + * @note This also includes IRIG decoder status. + * + * @see @ref MBG_DEBUG_STATUS_BIT_MASKS */ -typedef uint32_t MBG_DEBUG_STATUS; ///< @see MBG_DEBUG_STATUS_BITS +typedef uint32_t MBG_DEBUG_STATUS; #define _mbg_swab_debug_status( _p ) \ _mbg_swab32( _p ) @@ -3132,29 +5209,33 @@ typedef uint32_t MBG_DEBUG_STATUS; ///< @see MBG_DEBUG_STATUS_BITS /** - * @brief Enumeration of bits used with ::MBG_DEBUG_STATUS + * @brief Enumeration of flag bits used for debug status + * + * @see @ref MBG_DEBUG_STATUS_BIT_MASKS */ enum MBG_DEBUG_STATUS_BITS { - MBG_IRIG_BIT_WARMED_UP, /**< Osc has warmed up */ - MBG_IRIG_BIT_PPS_ACTIVE, /**< PPS output is active */ - MBG_IRIG_BIT_INV_CONFIG, /**< Invalid config, e.g. data csum error */ - MBG_IRIG_BIT_MSG_DECODED, /**< IRIG msg could be decoded */ - MBG_IRIG_BIT_MSG_INCONSISTENT, /**< IRIG msg contains inconsistent data */ - MBG_IRIG_BIT_LOOP_LOCKED, /**< Decoder control loop is locked */ - MBG_IRIG_BIT_JITTER_TOO_LARGE, /**< Phase jitter too large */ - MBG_IRIG_BIT_INV_REF_OFFS, /**< %UTC ref offset not configured */ - - MBG_SYS_BIT_INV_TIME, /**< Internal time not valid/set */ - MBG_SYS_BIT_TIME_SET_VIA_API, /**< On board time set externally */ - MBG_SYS_BIT_INV_RTC, /**< On board RTC invalid */ - MBG_SYS_BIT_CPU_PLL_FAILED, /**< The CPU's PLL watchdog */ - - N_MBG_DEBUG_BIT + MBG_IRIG_BIT_WARMED_UP, ///< Osc has warmed up + MBG_IRIG_BIT_PPS_ACTIVE, ///< PPS output is active + MBG_IRIG_BIT_INV_CONFIG, ///< Invalid config, e.g. data csum error + MBG_IRIG_BIT_MSG_DECODED, ///< IRIG msg could be decoded + MBG_IRIG_BIT_MSG_INCONSISTENT, ///< IRIG msg contains inconsistent data + MBG_IRIG_BIT_LOOP_LOCKED, ///< Decoder control loop is locked + MBG_IRIG_BIT_JITTER_TOO_LARGE, ///< Phase jitter too large + MBG_IRIG_BIT_INV_REF_OFFS, ///< %UTC ref offset not configured + + MBG_SYS_BIT_INV_TIME, ///< Internal time not valid/set + MBG_SYS_BIT_TIME_SET_VIA_API, ///< On board time set externally + MBG_SYS_BIT_INV_RTC, ///< On board RTC invalid + MBG_SYS_BIT_CPU_PLL_FAILED, ///< The CPU's PLL watchdog + + N_MBG_DEBUG_BIT ///< The number of known bits }; /** * @brief Initializers for debug status bit strings + * + * @see ::MBG_DEBUG_STATUS_BITS */ #define MBG_DEBUG_STATUS_STRS \ { \ @@ -3174,6 +5255,12 @@ enum MBG_DEBUG_STATUS_BITS } +/** + * @brief Bit masks used with ::MBG_DEBUG_STATUS + * + * @see ::MBG_DEBUG_STATUS_BITS + * + * @anchor MBG_DEBUG_STATUS_BIT_MASKS @{ */ #define MBG_IRIG_MSK_WARMED_UP ( 1UL << MBG_IRIG_BIT_WARMED_UP ) #define MBG_IRIG_MSK_PPS_ACTIVE ( 1UL << MBG_IRIG_BIT_PPS_ACTIVE ) @@ -3189,6 +5276,7 @@ enum MBG_DEBUG_STATUS_BITS #define MBG_SYS_MSK_INV_RTC ( 1UL << MBG_SYS_BIT_INV_RTC ) #define MBG_SYS_MSK_CPU_PLL_FAILED ( 1UL << MBG_SYS_BIT_CPU_PLL_FAILED ) +/** @} anchor MBG_DEBUG_STATUS_BIT_MASKS */ /** @@ -3198,10 +5286,15 @@ enum MBG_DEBUG_STATUS_BITS * For some types of signal (e.g. most IRIG frame formats) this can't be * determined automatically. * + * Valid range: -::MBG_REF_OFFS_MAX..::MBG_REF_OFFS_MAX, or ::MBG_REF_OFFS_NOT_CFGD + * * @note There's a special flag ::MBG_REF_OFFS_NOT_CFGD indicating that - * this parameter is unconfigured + * this parameter is unconfigured, in which case a Meinberg time code + * receiver refuses to synchronize to the time code signal unless a time + * code frame has been configured which provides the UTC offset (namely + * IEEE 1344 or IEEE C37.118). */ -typedef int16_t MBG_REF_OFFS; ///< -::MBG_REF_OFFS_MAX..::MBG_REF_OFFS_MAX, or ::MBG_REF_OFFS_NOT_CFGD +typedef int16_t MBG_REF_OFFS; #define _mbg_swab_mbg_ref_offs( _p ) _mbg_swab16( (_p) ) @@ -3218,7 +5311,8 @@ typedef int16_t MBG_REF_OFFS; ///< -::MBG_REF_OFFS_MAX..::MBG_REF_OFFS_MAX, or * (time offset from %UTC) has not yet been configured. This is usually * the case for IRIG receiver devices right after they have been shipped. */ -#define MBG_REF_OFFS_NOT_CFGD 0x8000 +#define MBG_REF_OFFS_NOT_CFGD ( (MBG_REF_OFFS) 0x8000 ) + /** @@ -3228,13 +5322,15 @@ typedef int16_t MBG_REF_OFFS; ///< -::MBG_REF_OFFS_MAX..::MBG_REF_OFFS_MAX, or */ typedef struct { - uint32_t flags; ///< @see MBG_OPT_BITS + uint32_t flags; ///< @see ::MBG_OPT_FLAGS + } MBG_OPT_SETTINGS; #define _mbg_swab_mbg_opt_settings( _p ) \ +do \ { \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) /** @@ -3245,48 +5341,68 @@ typedef struct */ typedef struct { - MBG_OPT_SETTINGS settings; - uint32_t supp_flags; ///< bit mask of supported flags, see ::MBG_OPT_BITS + MBG_OPT_SETTINGS settings; ///< current settings + uint32_t supp_flags; ///< bit mask of supported flags, see ::MBG_OPT_FLAGS + } MBG_OPT_INFO; #define _mbg_swab_mbg_opt_info( _p ) \ +do \ { \ _mbg_swab_mbg_opt_settings( &(_p)->settings ); \ _mbg_swab32( &(_p)->supp_flags ); \ -} +} while ( 0 ) +/** + * @brief Enumeration of flag bits used to define ::MBG_OPT_FLAGS + */ enum MBG_OPT_BITS { - MBG_OPT_BIT_STR_UTC, /**< serial string contains %UTC time */ - MBG_OPT_BIT_EMU_SYNC, /**< emulate/pretend to be synchronized, alternatively - ::GPS_FEAT_IGNORE_LOCK may be supported */ + MBG_OPT_BIT_STR_UTC, ///< serial time string contains %UTC time + MBG_OPT_BIT_EMU_SYNC, ///< always pretend to be synchronized, alternatively ::GPS_FEAT_IGNORE_LOCK may be supported N_MBG_OPT_BIT }; -/* - * Bit masks corresponding to the enumeration above: + +/** + * @brief Bit masks according to ::MBG_OPT_BITS + * + * Used with ::MBG_OPT_SETTINGS::flags and ::MBG_OPT_INFO::supp_flags. */ -#define MBG_OPT_FLAG_STR_UTC ( 1UL << MBG_OPT_BIT_STR_UTC ) -#define MBG_OPT_FLAG_EMU_SYNC ( 1UL << MBG_OPT_BIT_EMU_SYNC ) +enum MBG_OPT_FLAGS +{ + MBG_OPT_FLAG_STR_UTC = ( 1UL << MBG_OPT_BIT_STR_UTC ), ///< see ::MBG_OPT_BIT_STR_UTC + MBG_OPT_FLAG_EMU_SYNC = ( 1UL << MBG_OPT_BIT_EMU_SYNC ) ///< see ::MBG_OPT_BIT_EMU_SYNC +}; /** * @brief Bit coded return type for ::PCPS_GET_IRIG_CTRL_BITS * - * This type returns the control bits an IRIG receiver has decoded - * from an incoming time code signal. + * The control bits a time code receiver has decoded from + * the incoming time code signal. + * + * @note ::MBG_RAW_IRIG_DATA is more versatile and should + * be used preferably, if supported. + * + * @see ::MBG_RAW_IRIG_DATA */ typedef uint32_t MBG_IRIG_CTRL_BITS; #define _mbg_swab_irig_ctrl_bits( _p ) _mbg_swab32( _p ) -// The following macro extracts the 4 bit TFOM code from the -// IRIG control bits read from a card. This only works if the received -// IRIG code is a code which supports TFOM, this is currently -// only IEEE1344. +/** + * @brief Extract the TFOM code from ::MBG_IRIG_CTRL_BITS + * + * The resulting code is only valid if the configured IRIG code frame format + * supports this. See @ref MSK_ICODE_TX_HAS_TFOM and @ref MSK_ICODE_RX_HAS_TFOM + * + * As specified in the IEEE 1344 standard as "Time Quality", the TFOM code is + * the range 0x0 (locked, maximum accuracy) to 0xF (failed, data unreliable). + */ #define _pcps_tfom_from_irig_ctrl_bits( _p ) \ ( ( ( *(_p) ) >> 24 ) & 0x0F ) @@ -3307,13 +5423,21 @@ typedef uint32_t MBG_IRIG_CTRL_BITS; typedef struct { uint8_t data_bytes[RAW_IRIG_SIZE]; + } MBG_RAW_IRIG_DATA; -// The following macro extracts the 4 bit TFOM code from the raw -// data bits read from a card. This only works if the received -// IRIG code is a code which supports TFOM, this is currently -// only IEEE1344. -#define _pcps_tfom_from_raw_irig_data( _p ) \ +#define _mbg_swab_mbg_raw_irig_data( _p ) _nop_macro_fnc() + +/** + * @brief Extract the TFOM code from ::MBG_RAW_IRIG_DATA + * + * The resulting code is only valid if the configured IRIG code frame format + * supports this. See @ref MSK_ICODE_TX_HAS_TFOM and @ref MSK_ICODE_RX_HAS_TFOM + * + * As specified in the IEEE 1344 standard as "Time Quality", the TFOM code is + * the range 0x0 (locked, maximum accuracy) to 0xF (failed, data unreliable). + */ +#define _pcps_tfom_from_raw_irig_data( _p ) \ ( ( ( (_p)->data_bytes[9] >> 2 ) & 0x08 ) \ | ( ( (_p)->data_bytes[9] >> 4 ) & 0x04 ) \ | ( ( (_p)->data_bytes[9] >> 6 ) & 0x02 ) \ @@ -3322,35 +5446,43 @@ typedef struct /** - @defgroup group_time_scale Time Scale Configuration - - The structures and defines can be used to configure the GPS receiver's - basic time scale. By default this is %UTC which can optionally - be converted to some local time. However, some applications - prefer TAI or pure GPS time. This can be configured using the - structures below if the GPS_HAS_TIME_SCALE flag is set in - RECEIVER_INFO::features. - @{ -*/ + * @defgroup group_time_scale Time Scale Configuration + * + * Used to configure the GPS receiver's basic time scale. + * By default this is %UTC which can optionally be converted + * to some local time. However, some applications prefer + * TAI or pure GPS time. This can be configured using the + * structures below if the ::GPS_HAS_TIME_SCALE flag is set + * in ::RECEIVER_INFO::features. + * + * @{ */ /** * @brief Known time scales * - * @note See also the extended status bits ::TM_SCALE_GPS - * and ::TM_SCALE_TAI indicating the active time scale setting + * @see ::MBG_TIME_SCALE_MASKS + * @see ::TM_SCALE_GPS + * @see ::TM_SCALE_TAI */ enum MBG_TIME_SCALES { MBG_TIME_SCALE_DEFAULT, ///< %UTC or local time according to ::UTC parameters and ::TZDL configuration MBG_TIME_SCALE_GPS, ///< GPS time as sent by the satellites, monotonical - MBG_TIME_SCALE_TAI, ///< TAI, i.e. GPS time plus constant offset (::GPS_TAI_OFFSET) + MBG_TIME_SCALE_TAI, ///< TAI, i.e. GPS time plus constant offset (see ::GPS_TAI_OFFSET) N_MBG_TIME_SCALE }; -#define MBG_TIME_SCALE_MSK_DEFAULT ( 1UL << MBG_TIME_SCALE_DEFAULT ) -#define MBG_TIME_SCALE_MSK_GPS ( 1UL << MBG_TIME_SCALE_GPS ) -#define MBG_TIME_SCALE_MSK_TAI ( 1UL << MBG_TIME_SCALE_TAI ) - +/** + * @brief Bit masks for known time scales + * + * @see ::MBG_TIME_SCALES + */ +enum MBG_TIME_SCALE_MASKS +{ + MBG_TIME_SCALE_MSK_DEFAULT = ( 1UL << MBG_TIME_SCALE_DEFAULT ), ///< see ::MBG_TIME_SCALE_DEFAULT + MBG_TIME_SCALE_MSK_GPS = ( 1UL << MBG_TIME_SCALE_GPS ), ///< see ::MBG_TIME_SCALE_GPS + MBG_TIME_SCALE_MSK_TAI = ( 1UL << MBG_TIME_SCALE_TAI ) ///< see ::MBG_TIME_SCALE_TAI +}; #define MBG_TIME_SCALE_STRS \ { \ @@ -3372,8 +5504,9 @@ enum MBG_TIME_SCALES */ typedef struct { - uint8_t scale; ///< current time scale code from enum MBG_TIME_SCALES - uint8_t flags; ///< reserved, currently always 0 + uint8_t scale; ///< current time scale code, see ::MBG_TIME_SCALES + uint8_t flags; ///< reserved, don't use, currently always 0 + } MBG_TIME_SCALE_SETTINGS; #define _mbg_swab_mbg_time_scale_settings( _p ) \ @@ -3386,26 +5519,33 @@ typedef struct typedef struct { MBG_TIME_SCALE_SETTINGS settings; ///< current settings - MBG_TIME_SCALE_SETTINGS max_settings; ///< numb. of scales, all supported flags - uint32_t supp_scales; ///< bit masks of supported scales + MBG_TIME_SCALE_SETTINGS max_settings; ///< number of scales, all supported flags + uint32_t supp_scales; ///< bit masks of supported scales, see ::MBG_TIME_SCALE_MASKS + } MBG_TIME_SCALE_INFO; #define _mbg_swab_mbg_time_scale_info( _p ) \ +do \ { \ _mbg_swab_mbg_time_scale_settings( &(_p)->settings ); \ _mbg_swab_mbg_time_scale_settings( &(_p)->max_settings ); \ _mbg_swab32( &(_p)->supp_scales ); \ -} +} while ( 0 ) -/** @} group_time_scale */ +/** @} defgroup group_time_scale */ -/* - * The structures below are required to setup the programmable + +/** + * @defgroup group_pout_api Programmable Output API + * + * These structures below are used to configure the programmable * pulse outputs which are provided by some GPS receivers. * The number of programmable pulse outputs supported by a GPS - * receiver is reported in the RECEIVER_INFO::n_str_type field. - */ + * receiver is reported in the RECEIVER_INFO::n_prg_out field. + * + * @{ */ + /** * @brief A calendar date including full year number @@ -3415,12 +5555,14 @@ typedef struct uint8_t mday; ///< 1..28,29,30,31 uint8_t month; ///< 1..12 uint16_t year; ///< including century + } MBG_DATE; #define _mbg_swab_mbg_date( _p ) \ +do \ { \ _mbg_swab16( &(_p)->year ); \ -} +} while ( 0 ) /** @@ -3431,7 +5573,8 @@ typedef struct uint8_t hour; ///< 0..23 uint8_t min; ///< 0..59 uint8_t sec; ///< 0..59,60 - uint8_t sec100; ///< reserved, currently always 0 + uint8_t sec100; ///< 100ths of seconds + } MBG_TIME; #define _mbg_swab_mbg_time( _p ) \ @@ -3447,29 +5590,38 @@ typedef struct MBG_TIME t; ///< time to switch uint8_t wday; ///< reserved, currently always 0 uint8_t flags; ///< reserved, currently 0 + } MBG_DATE_TIME; #define _mbg_swab_mbg_date_time( _p ) \ +do \ { \ _mbg_swab_mbg_date( &(_p)->d ); \ _mbg_swab_mbg_time( &(_p)->t ); \ -} +} while ( 0 ) /** * @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. */ typedef struct { MBG_DATE_TIME on; ///< date and time to switch on MBG_DATE_TIME off; ///< date and time to switch off + } POUT_TIME; #define _mbg_swab_pout_time( _p ) \ +do \ { \ _mbg_swab_mbg_date_time( &(_p)->on ); \ _mbg_swab_mbg_date_time( &(_p)->off ); \ -} +} while ( 0 ) + /** @@ -3480,73 +5632,120 @@ typedef struct #define N_POUT_TIMES 3 /** + * @brief A Generic data field for programmable output settings + */ +typedef union +{ + /// Switching times. See ::POUT_MODES_DATA_TM, ::POUT_MODES_DATA_TM_0 + POUT_TIME tm[N_POUT_TIMES]; + + uint8_t b[N_POUT_TIMES * sizeof( POUT_TIME )]; + + /// Only if ::POUT_SUPP_PULSE_SHIFT is set, this field can be used to + /// configure the time interval in [ns] by which output pulse slopes are + /// to be shifted. The configured pulse shift must be in the range + /// ::DEFAULT_POUT_PULSE_SHIFT_MIN through ::DEFAULT_POUT_PULSE_SHIFT_MAX. + /// The resolution / steps at which the pulse shift interval can be configured + /// is returned in ::POUT_INFO::pulse_shift_res. + /// @see ::POUT_MODES_DATA_PULSE_SHIFT + int32_t pulse_shift; + +} POUT_DATA; + +#define DEFAULT_POUT_PULSE_SHIFT_MIN -500000000L ///< Default minimum value for ::POUT_DATA::pulse_shift, in [ns] +#define DEFAULT_POUT_PULSE_SHIFT_MAX 499000000L ///< Default maximum value for ::POUT_DATA::pulse_shift, in [ns] + + +/** + * @brief Convert ::POUT_DATA endianess depending on the mode + * + * Assuming the mode is passed to the macro with correct endianess. + */ +#define _mbg_swab_pout_data( _p, _mode ) \ +do \ +{ \ + uint32_t mode_mask = 1UL << _mode; \ + \ + if ( mode_mask & POUT_MODES_DATA_TM ) \ + { \ + int i; \ + \ + for ( i = 0; i < N_POUT_TIMES; i++ ) \ + _mbg_swab_pout_time( &(_p)->tm[i] ); \ + } \ + else \ + { \ + if ( mode_mask & POUT_MODES_DATA_TM_0 ) \ + _mbg_swab_pout_time( &(_p)->tm[0] ); \ + else \ + if ( mode_mask & POUT_MODES_DATA_PULSE_SHIFT ) \ + _mbg_swab32( &(_p)->pulse_shift ); \ + } \ + \ +} while ( 0 ) + + + +/** * @brief Configuration settings for a single programmable pulse output */ typedef struct { - uint16_t mode; ///< mode of operation, see ::POUT_MODES - uint16_t pulse_len; ///< 10 msec units, or COM port number - uint16_t timeout; ///< [min], for DCF77 emulation mode only - uint16_t flags; ///< @see POUT_SETTINGS_FLAG_BITS - POUT_TIME tm[N_POUT_TIMES]; ///< switching times, or other data, see ::POUT_DATA + 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. + /// + /// 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 + uint16_t timeout; + + uint16_t flags; ///< @see ::POUT_SETTINGS_FLAGS + POUT_DATA pout_data; ///< Additional configuration data, see ::POUT_DATA + } POUT_SETTINGS; /** - * @brief A Generic data field for programmable output settings - * - * If the mode is set to ::POUT_TIME_SLOTS then POUT_SETTINGS::tm must be - * interpreted as ::POUT_DATA, i.e. just an array of bytes. We can not change - * the type of the tm field to a union for compatibility reasons ... :( + * @brief Convert ::POUT_SETTINGS endianess after reading from a device */ -typedef union -{ - uint8_t b[N_POUT_TIMES * sizeof( POUT_TIME )]; -} POUT_DATA; +#define _mbg_swab_pout_settings_on_get( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->mode ); \ + _mbg_swab16( &(_p)->mode_param ); \ + _mbg_swab16( &(_p)->timeout ); \ + _mbg_swab16( &(_p)->flags ); \ + _mbg_swab_pout_data( &(_p)->pout_data, (_p)->mode ); \ +} while ( 0 ) -// When reading data from a device we first need to correct the endianess -// of the mode first, and correct the endianess of the tm field only -// if the tm field is not interpreted as POUT_DATA. -#define _mbg_swab_pout_settings_on_get( _p ) \ -{ \ - _mbg_swab16( &(_p)->mode ); \ - _mbg_swab16( &(_p)->pulse_len ); \ - _mbg_swab16( &(_p)->timeout ); \ - _mbg_swab16( &(_p)->flags ); \ - \ - if ( (_p)->mode != POUT_TIME_SLOTS ) \ - { \ - int i; \ - \ - for ( i = 0; i < N_POUT_TIMES; i++ ) \ - _mbg_swab_pout_time( &(_p)->tm[i] ); \ - } \ -} - -// When writing data to a device we first need to check the mode, -// and correct the endianess of the tm field only if the tm field -// is not interpreted as POUT_DATA. Finally we can also correct -// the endianess of the mode field. -#define _mbg_swab_pout_settings_on_set( _p ) \ -{ \ - if ( (_p)->mode != POUT_TIME_SLOTS ) \ - { \ - int i; \ - \ - for ( i = 0; i < N_POUT_TIMES; i++ ) \ - _mbg_swab_pout_time( &(_p)->tm[i] ); \ - } \ - \ - _mbg_swab16( &(_p)->mode ); \ - _mbg_swab16( &(_p)->pulse_len ); \ - _mbg_swab16( &(_p)->timeout ); \ - _mbg_swab16( &(_p)->flags ); \ -} +/** + * @brief Convert ::POUT_SETTINGS endianess before writing to a device + */ +#define _mbg_swab_pout_settings_on_set( _p ) \ +do \ +{ \ + _mbg_swab_pout_data( &(_p)->pout_data, (_p)->mode ); \ + _mbg_swab16( &(_p)->mode ); \ + _mbg_swab16( &(_p)->mode_param ); \ + _mbg_swab16( &(_p)->timeout ); \ + _mbg_swab16( &(_p)->flags ); \ +} while ( 0 ) -// In POUT_TIME_SLOTS mode the number of time slots per minute is stored -// in the pulse_len field. Valid numbers all numbers n in the range 1..60 -// for which the remainder of 60 / n is 0. +/** + * @brief Definitions used with ::POUT_TIME_SLOTS mode + * + * If ::POUT_SETTINGS::mode is set to ::POUT_TIME_SLOTS then the number + * of time slots per minute is stored in ::POUT_SETTINGS::mode_param. + * Valid numbers are all numbers n in the range ::MIN_TIME_SLOTS_PER_MINUTE + * to ::MAX_TIME_SLOTS_PER_MINUTE for which the remainder of 60 / n is 0. + * @see ::POUT_MODES_MODE_PARAM_AS_SLOTS_PER_MIN + * + * @anchor POUT_TIME_SLOTS_MODE_DEFS @{ */ + #define MIN_TIME_SLOTS_PER_MINUTE 1 #define MAX_TIME_SLOTS_PER_MINUTE 60 #define TIME_SLOT_REGISTER_IN_SEC 60 @@ -3563,45 +5762,313 @@ typedef union ( ( 60 % (_n) ) == 0 ) \ ) +/** @} anchor POUT_TIME_SLOTS_MODE_DEFS */ + + #define MAX_POUT_PULSE_LEN 1000 ///< 10 secs, in 10 msec units #define MAX_POUT_DCF_TIMOUT ( 48 * 60 ) ///< 48 hours, in minutes + /** - * @brief Operation modes for a programmable pulse output + * @brief Enumeration of known operation modes for programmable pulse outputs * - * These codes are used with POUT_SETTINGS::mode. + * These codes are used with ::POUT_SETTINGS::mode. One or more of + * the remaining fields in ::POUT_SETTINGS are evaluated depending + * on the selected mode. Unused fields should be set to 0. + * + * Unless ::POUT_NOT_INVERTIBLE is set in ::POUT_INFO::flags + * the output signal level can be inverted if ::POUT_INVERTED + * is set in ::POUT_SETTINGS::flags. * * @note Not every programmable pulse output supports all modes. + * + * @see @ref POUT_MODE_MASKS + * @see @ref POUT_MODES_PARAM_MASKS + * @see @ref ENG_POUT_NAMES + * @see @ref ENG_POUT_HINTS */ enum POUT_MODES { - POUT_IDLE, ///< always off, or on if ::POUT_INVERTED flag is set - POUT_TIMER, ///< switch on/off at configured times - POUT_SINGLE_SHOT, ///< pulse at time POUT_SETTINGS::tm[0].on - POUT_CYCLIC_PULSE, ///< pulse every POUT_SETTINGS::tm[0].on.t interval - POUT_PER_SEC, ///< pulse if second changes - POUT_PER_MIN, ///< pulse if minute changes - POUT_PER_HOUR, ///< pulse if hour changes - POUT_DCF77, ///< emulate DCF77 signal - POUT_POS_OK, ///< on if pos. OK (nav_solved) - POUT_TIME_SYNC, ///< on if time sync (time_syn) - POUT_ALL_SYNC, ///< on if pos. OK and time sync - POUT_TIMECODE, ///< IRIG/AFNOR DCLS output - POUT_TIMESTR, ///< COM port number in pulse_len field - POUT_10MHZ, ///< 10 MHz fixed frequency - POUT_DCF77_M59, ///< DCF77-like signal with 500 ms pulse in 59th second - POUT_SYNTH, ///< programmable synthesizer frequency - POUT_TIME_SLOTS, ///< programmable time slots during each minute + /// Output is normally always 'off', or always 'on', if flag ::POUT_INVERTED is set. + POUT_IDLE, + + /// Switch 'on' or 'off' at the times specified in ::POUT_DATA::tm. + 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. + /// 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. + /// 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. + /// 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. + /// 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. + /// See ::MAX_POUT_PULSE_LEN. + POUT_PER_HOUR, + + /// Generate DCF77-compatible second marks. + /// See ::POUT_DCF77_M59, ::POUT_SETTINGS::timeout and ::MAX_POUT_DCF_TIMOUT. + POUT_DCF77, + + /// Output switched on if receiver position verified (condition nav_solved). + POUT_POS_OK, + + /// Output switched on if time synchronized (condition time_syn). + POUT_TIME_SYNC, + + /// Output switched on if both position verified and time synchronized. + POUT_ALL_SYNC, + + /// IRIG/AFNOR DCLS time code signal mapped to this output. + POUT_TIMECODE, + + /// Serial time string of one one of the serial ports mapped to this output. + /// ::POUT_SETTINGS::mode_param contains the number of the COM port. + /// See ::MAX_POUT_TIMESTR_PORTS. + POUT_TIMESTR, + + /// 10 MHz fixed frequency output. + POUT_10MHZ, + + /// DCF77-like signal with extra 500 ms pulse in the 59th second + /// (the original DCF77 signal has no such pulse). See ::POUT_DCF77, + /// ::POUT_SETTINGS::timeout and ::MAX_POUT_DCF_TIMOUT. + POUT_DCF77_M59, + + /// Output signal generated by the programmable frequency synthesizer. + POUT_SYNTH, + + /// Programmable time slots during each minute. + /// ::POUT_SETTINGS::mode_param specifies the time slots per minute. + /// Uses ::POUT_DATA. ::TODO + POUT_TIME_SLOTS, + + /// A GPIO input or output signal is reflected at this pulse output. + /// ::POUT_SETTINGS::mode_param specifies the GPIO number which must + /// be in the range 0..::MBG_GPIO_CFG_LIMITS::num_io. + POUT_GPIO, + + /// A 1 PPS signal with a fixed 20 us pulse length + POUT_PTTI_PPS, + + /// A HaveQuick signal as configured in ::HAVEQUICK_SETTINGS::format + POUT_HAVEQUICK, + + // New modes have to be added here at the end of the enumeration, and the + // POUT_MODE_MASKS, the POUT_MODES_PARAM_MASKS as well as string initializers + // (also in pcpslstr.h) have to be updated accordingly. N_POUT_MODES ///< the number of known modes }; -/* - * Default initializers for English pulse mode names. Initializers - * for multi-language strings can be found in pcpslstr.h. +/** + * @brief Bit masks associated with ::POUT_MODES + * + * Used with ::POUT_INFO::supp_modes to specify which ::POUT_MODES + * are supported for a particular programmable output. + * + * @see ::POUT_MODES + * + * @anchor POUT_MODE_MASKS @{ */ + +#define MSK_POUT_IDLE ( 1UL << POUT_IDLE ) ///< see ::POUT_IDLE +#define MSK_POUT_TIMER ( 1UL << POUT_TIMER ) ///< see ::POUT_TIMER +#define MSK_POUT_SINGLE_SHOT ( 1UL << POUT_SINGLE_SHOT ) ///< see ::POUT_SINGLE_SHOT +#define MSK_POUT_CYCLIC_PULSE ( 1UL << POUT_CYCLIC_PULSE ) ///< see ::POUT_CYCLIC_PULSE +#define MSK_POUT_PER_SEC ( 1UL << POUT_PER_SEC ) ///< see ::POUT_PER_SEC +#define MSK_POUT_PER_MIN ( 1UL << POUT_PER_MIN ) ///< see ::POUT_PER_MIN +#define MSK_POUT_PER_HOUR ( 1UL << POUT_PER_HOUR ) ///< see ::POUT_PER_HOUR +#define MSK_POUT_DCF77 ( 1UL << POUT_DCF77 ) ///< see ::POUT_DCF77 +#define MSK_POUT_POS_OK ( 1UL << POUT_POS_OK ) ///< see ::POUT_POS_OK +#define MSK_POUT_TIME_SYNC ( 1UL << POUT_TIME_SYNC ) ///< see ::POUT_TIME_SYNC +#define MSK_POUT_ALL_SYNC ( 1UL << POUT_ALL_SYNC ) ///< see ::POUT_ALL_SYNC +#define MSK_POUT_TIMECODE ( 1UL << POUT_TIMECODE ) ///< see ::POUT_TIMECODE +#define MSK_POUT_TIMESTR ( 1UL << POUT_TIMESTR ) ///< see ::POUT_TIMESTR +#define MSK_POUT_10MHZ ( 1UL << POUT_10MHZ ) ///< see ::POUT_10MHZ +#define MSK_POUT_DCF77_M59 ( 1UL << POUT_DCF77_M59 ) ///< see ::POUT_DCF77_M59 +#define MSK_POUT_SYNTH ( 1UL << POUT_SYNTH ) ///< see ::POUT_SYNTH +#define MSK_POUT_TIME_SLOTS ( 1UL << POUT_TIME_SLOTS ) ///< see ::POUT_TIME_SLOTS +#define MSK_POUT_GPIO ( 1UL << POUT_GPIO ) ///< see ::POUT_GPIO +#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 */ + + + +/** + * @brief Bit masks indicating which parameters relevant for which ::POUT_MODES + * + * @see ::POUT_MODES + * @see @ref POUT_MODE_MASKS + * + * @anchor POUT_MODES_PARAM_MASKS @{ */ + + +/** + * @brief POUT modes which use the full ::POUT_DATA::tm array as parameter + */ +#define POUT_MODES_DATA_TM \ +( \ + MSK_POUT_TIMER \ +) + + +/** + * @brief POUT modes which use only ::POUT_DATA::tm[0] as parameter */ +#define POUT_MODES_DATA_TM_0 \ +( \ + MSK_POUT_SINGLE_SHOT | \ + MSK_POUT_CYCLIC_PULSE \ +) + + +/** + * @brief POUT modes which use ::POUT_SETTINGS::mode_param as pulse length + * + * @see ::MAX_POUT_PULSE_LEN + */ +#define POUT_MODES_MODE_PARAM_AS_PULSE_LEN \ +( \ + MSK_POUT_SINGLE_SHOT | \ + MSK_POUT_CYCLIC_PULSE | \ + MSK_POUT_PER_SEC | \ + MSK_POUT_PER_MIN | \ + MSK_POUT_PER_HOUR \ +) + + +/** + * @brief POUT modes which use ::POUT_SETTINGS::mode_param as COM port index number + */ +#define POUT_MODES_MODE_PARAM_AS_COM_IDX \ +( \ + MSK_POUT_TIMESTR \ +) + + +/** + * @brief POUT modes which use ::POUT_SETTINGS::mode_param as time slots per minute + * + * @see @ref POUT_TIME_SLOTS_MODE_DEFS + */ +#define POUT_MODES_MODE_PARAM_AS_SLOTS_PER_MIN \ +( \ + MSK_POUT_TIME_SLOTS \ +) + + +/** + * @brief POUT modes which use ::POUT_SETTINGS::mode_param as GPIO index number + */ +#define POUT_MODES_MODE_PARAM_AS_GPIO_IDX \ +( \ + MSK_POUT_GPIO \ +) + + +/** + * @brief POUT modes which use ::POUT_SETTINGS::timeout + */ +#define POUT_MODES_TIMEOUT \ +( \ + MSK_POUT_DCF77 | \ + MSK_POUT_DCF77_M59 \ +) + + +/** + * @brief POUT modes which which support ::POUT_TIMEBASE_UTC + */ +#define POUT_MODES_SUPP_TIMEBASE_UTC \ +( \ + MSK_POUT_DCF77 | \ + MSK_POUT_DCF77_M59 \ +) + + +/** + * @brief POUT modes which use ::POUT_DATA::pulse_shift + * + * @note: Supported only if ::POUT_SUPP_PULSE_SHIFT is set + */ +#define POUT_MODES_DATA_PULSE_SHIFT \ +( \ + MSK_POUT_PER_SEC | \ + MSK_POUT_PER_MIN | \ + MSK_POUT_PER_HOUR \ +) + + +/** + * @brief POUT modes which support ::POUT_SUPP_IF_SYNC_ONLY + * + * Even if ::POUT_SUPP_IF_SYNC_ONLY is set in ::POUT_INFO::flags + * the associated flag ::POUT_IF_SYNC_ONLY in ::POUT_SETTINGS::flags + * may be evaluated depending on the mode. + * + * Modes ::POUT_POS_OK, ::POUT_TIME_SYNC, and ::MSK_POUT_ALL_SYNC + * are explicitly excluded. + * + * For modes ::MSK_POUT_DCF77 and ::MSK_POUT_DCF77_M59 see also + * ::POUT_SETTINGS::timeout. + */ +#define POUT_MODES_SUPP_IF_SYNC_ONLY \ +( \ + MSK_POUT_IDLE | \ + MSK_POUT_TIMER | \ + MSK_POUT_SINGLE_SHOT | \ + MSK_POUT_CYCLIC_PULSE | \ + MSK_POUT_PER_SEC | \ + MSK_POUT_PER_MIN | \ + MSK_POUT_PER_HOUR | \ + MSK_POUT_DCF77 | \ + MSK_POUT_TIMECODE | \ + MSK_POUT_TIMESTR | \ + MSK_POUT_10MHZ | \ + MSK_POUT_DCF77_M59 | \ + MSK_POUT_SYNTH | \ + MSK_POUT_TIME_SLOTS | \ + MSK_POUT_GPIO | \ + MSK_POUT_PTTI_PPS | \ + MSK_POUT_HAVEQUICK \ +) + +/** @} anchor POUT_MODES_PARAM_MASKS */ + + + +/** + * @brief Name strings associated with ::POUT_MODES + * + * Default initializers for English programmable output mode names. + * Initializers for multi-language strings can be found in pcpslstr.h. + * + * @see ::POUT_MODES + * @see ::DEFAULT_ENG_POUT_NAMES + * + * @anchor ENG_POUT_NAMES @{ */ + #define ENG_POUT_NAME_IDLE "Idle" #define ENG_POUT_NAME_TIMER "Timer" #define ENG_POUT_NAME_SINGLE_SHOT "Single Shot" @@ -3614,12 +6081,24 @@ enum POUT_MODES #define ENG_POUT_NAME_TIME_SYNC "Time Sync" #define ENG_POUT_NAME_ALL_SYNC "All Sync" #define ENG_POUT_NAME_TIMECODE "DCLS Time Code" -#define ENG_POUT_NAME_TIMESTR "COM Time String" +#define ENG_POUT_NAME_TIMESTR "Serial Time String" #define ENG_POUT_NAME_10MHZ "10 MHz Frequency" #define ENG_POUT_NAME_DCF77_M59 "DCF77-like M59" #define ENG_POUT_NAME_SYNTH "Synthesizer Frequency" #define ENG_POUT_NAME_TIME_SLOTS "Time Slots per Minute" +#define ENG_POUT_NAME_GPIO "GPIO Signal" +#define ENG_POUT_PTTI_PPS "PTTI 1 PPS" +#define ENG_POUT_HAVEQUICK "HaveQuick" + +/** @} anchor ENG_POUT_NAMES */ + + +/** + * @brief An initializer for a table of English POUT name strings + * + * @see @ref ENG_POUT_NAMES + */ #define DEFAULT_ENG_POUT_NAMES \ { \ ENG_POUT_NAME_IDLE, \ @@ -3638,10 +6117,24 @@ enum POUT_MODES ENG_POUT_NAME_10MHZ, \ ENG_POUT_NAME_DCF77_M59, \ ENG_POUT_NAME_SYNTH, \ - ENG_POUT_NAME_TIME_SLOTS \ + ENG_POUT_NAME_TIME_SLOTS, \ + ENG_POUT_NAME_GPIO, \ + ENG_POUT_PTTI_PPS, \ + ENG_POUT_HAVEQUICK \ } +/** + * @brief Hint strings associated with ::POUT_MODES + * + * Default initializers for English programmable output mode hints. + * Initializers for multi-language strings can be found in pcpslstr.h. + * + * @see ::POUT_MODES + * @see ::DEFAULT_ENG_POUT_HINTS + * + * @anchor ENG_POUT_HINTS @{ */ + #define ENG_POUT_HINT_IDLE "Constant output level" #define ENG_POUT_HINT_TIMER "Switch based on configured on/off times" #define ENG_POUT_HINT_SINGLE_SHOT "Generate a single pulse of determined length" @@ -3659,7 +6152,18 @@ enum POUT_MODES #define ENG_POUT_HINT_DCF77_M59 "DCF77 time marks with 500 ms pulse in 59th second" #define ENG_POUT_HINT_SYNTH "Frequency generated by programmable synthesizer" #define ENG_POUT_HINT_TIME_SLOTS "Output enabled during specified time slots per minute" +#define ENG_POUT_HINT_GPIO "Duplicated signal of the specified GPIO input or output" +#define ENG_POUT_HINT_PTTI_PPS "Generate 20us Pulse at beginning of the second" +#define ENG_POUT_HINT_HAVEQUICK "Duplicated HaveQuick Signal" + +/** @} anchor ENG_POUT_HINTS */ + +/** + * @brief An initializer for a table of English POUT hint strings + * + * @see @ref ENG_POUT_HINTS + */ #define DEFAULT_ENG_POUT_HINTS \ { \ ENG_POUT_HINT_IDLE, \ @@ -3678,48 +6182,58 @@ enum POUT_MODES ENG_POUT_HINT_10MHZ, \ ENG_POUT_HINT_DCF77_M59, \ ENG_POUT_HINT_SYNTH, \ - ENG_POUT_HINT_TIME_SLOTS \ + ENG_POUT_HINT_TIME_SLOTS, \ + ENG_POUT_HINT_GPIO, \ + ENG_POUT_HINT_PTTI_PPS, \ + ENG_POUT_HINT_HAVEQUICK \ } -/* - * The definitions below are used to set up bit masks - * which restrict the modes which can be used with - * a given programmable output: - */ -#define MSK_POUT_IDLE ( 1UL << POUT_IDLE ) -#define MSK_POUT_TIMER ( 1UL << POUT_TIMER ) -#define MSK_POUT_SINGLE_SHOT ( 1UL << POUT_SINGLE_SHOT ) -#define MSK_POUT_CYCLIC_PULSE ( 1UL << POUT_CYCLIC_PULSE ) -#define MSK_POUT_PER_SEC ( 1UL << POUT_PER_SEC ) -#define MSK_POUT_PER_MIN ( 1UL << POUT_PER_MIN ) -#define MSK_POUT_PER_HOUR ( 1UL << POUT_PER_HOUR ) -#define MSK_POUT_DCF77 ( 1UL << POUT_DCF77 ) -#define MSK_POUT_POS_OK ( 1UL << POUT_POS_OK ) -#define MSK_POUT_TIME_SYNC ( 1UL << POUT_TIME_SYNC ) -#define MSK_POUT_ALL_SYNC ( 1UL << POUT_ALL_SYNC ) -#define MSK_POUT_TIMECODE ( 1UL << POUT_TIMECODE ) -#define MSK_POUT_TIMESTR ( 1UL << POUT_TIMESTR ) -#define MSK_POUT_10MHZ ( 1UL << POUT_10MHZ ) -#define MSK_POUT_DCF77_M59 ( 1UL << POUT_DCF77_M59 ) -#define MSK_POUT_SYNTH ( 1UL << POUT_SYNTH ) -#define MSK_POUT_TIME_SLOTS ( 1UL << POUT_TIME_SLOTS ) - - -/** - * @brief Bits used with POUT_SETTINGS::flags + +/** + * @brief Flag bits used to define ::POUT_SETTINGS_FLAGS + * + * @see ::POUT_SETTINGS_FLAGS */ enum POUT_SETTINGS_FLAG_BITS { - POUT_BIT_INVERTED, ///< output level has to be inverted - POUT_BIT_IF_SYNC_ONLY, ///< disable output in holdover mode - POUT_BIT_TIMEBASE_UTC, ///< use %UTC, only applicable for DCF77 output + /// Output level is to be inverted. Can only be used + /// if ::POUT_NOT_INVERTIBLE is **not** set, but is + /// supported by all ::POUT_MODES. + POUT_BIT_INVERTED, + + /// Enable output **only** while synchronized. This even overrides + /// the settings in ::ENABLE_FLAGS::pulses, so if this flag is set + /// the output is only enabled if the clock is synchronized, and is + /// disabled when synchronization is lost, i.e. the device enters + /// holdover mode. + /// This flag can only be used with outputs that have ::POUT_SUPP_IF_SYNC_ONLY + /// set, and is only supported for the ::POUT_MODES specified in + /// ::POUT_MODES_SUPP_IF_SYNC_ONLY. + POUT_BIT_IF_SYNC_ONLY, + + /// Output %UTC time instead of local time for DCF77 emulation. + /// This flag can only be used with outputs that have ::POUT_SUPP_DCF77_UTC + /// set, and is only supported for the ::POUT_MODES specified in + /// ::POUT_MODES_SUPP_TIMEBASE_UTC (e.g. ::POUT_DCF77 or ::POUT_DCF77_M59). + POUT_BIT_TIMEBASE_UTC, + N_POUT_SETTINGS_FLAG_BITS ///< Number of known flag bits }; -#define POUT_INVERTED ( 1UL << POUT_BIT_INVERTED ) -#define POUT_IF_SYNC_ONLY ( 1UL << POUT_BIT_IF_SYNC_ONLY ) -#define POUT_TIMEBASE_UTC ( 1UL << POUT_BIT_TIMEBASE_UTC ) + +/** + * @brief Flag bit masks used with ::POUT_SETTINGS::flags + * + * @see ::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 +}; + /** @@ -3734,21 +6248,24 @@ enum POUT_SETTINGS_FLAG_BITS */ typedef struct { - uint16_t idx; ///< 0..RECEIVER_INFO::n_prg_out - 1 + uint16_t idx; ///< 0..::RECEIVER_INFO::n_prg_out-1 POUT_SETTINGS pout_settings; + } POUT_SETTINGS_IDX; #define _mbg_swab_pout_settings_idx_on_set( _p ) \ +do \ { \ _mbg_swab16( &(_p)->idx ); \ _mbg_swab_pout_settings_on_set( &(_p)->pout_settings ); \ -} +} while ( 0 ) #define _mbg_swab_pout_settings_idx_on_get( _p ) \ +do \ { \ _mbg_swab16( &(_p)->idx ); \ _mbg_swab_pout_settings_on_get( &(_p)->pout_settings ); \ -} +} while ( 0 ) /** @@ -3764,48 +6281,64 @@ typedef struct typedef struct { POUT_SETTINGS pout_settings; - uint32_t supp_modes; ///< bit mask of modes supp. by this output, see ::POUT_MODES - uint8_t timestr_ports; ///< bit mask of COM ports supported for mode ::POUT_TIMESTR, see ::MAX_POUT_TIMESTR_PORTS - uint8_t reserved_0; ///< reserved for future use, currently 0 - uint16_t reserved_1; ///< reserved for future use, currently 0 - uint32_t flags; ///< @see POUT_INFO_FLAG_BITS + uint32_t supp_modes; ///< bit mask of modes supp. by this output, see @ref POUT_MODE_MASKS + uint8_t timestr_ports; ///< bit mask of COM ports supported for mode ::POUT_TIMESTR, see ::MAX_POUT_TIMESTR_PORTS + uint8_t pulse_shift_res; ///< pulse shift resolution, in [ns], only if ::POUT_SUPP_PULSE_SHIFT, see ::POUT_DATA::pulse_shift + uint16_t reserved_1; ///< reserved for future use, currently unused and always 0 + uint32_t flags; ///< @see ::POUT_INFO_FLAG_MASKS + } POUT_INFO; #define _mbg_swab_pout_info_on_get( _p ) \ +do \ { \ _mbg_swab_pout_settings_on_get( &(_p)->pout_settings ); \ _mbg_swab32( &(_p)->supp_modes ); \ + _mbg_swab8( &(_p)->timestr_ports ); \ + _mbg_swab8( &(_p)->pulse_shift_res ); \ _mbg_swab16( &(_p)->reserved_1 ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) -/** - * The max number of COM ports that can be handled by POUT_INFO::timestr_ports - */ -#define MAX_POUT_TIMESTR_PORTS 8 +#define MAX_POUT_TIMESTR_PORTS 8 ///< The max number of COM ports that can be handled by ::POUT_INFO::timestr_ports + /** - * @brief Bits used with POUT_INFO::flags + * @brief Flag bits used to define ::POUT_INFO_FLAG_MASKS + * + * @see ::POUT_INFO_FLAG_MASKS */ enum POUT_INFO_FLAG_BITS { - POUT_BIT_SUPP_IF_SYNC_ONLY, ///< supports disabling outputs in holdover mode - POUT_BIT_SUPP_DCF77_UTC, ///< supports %UTC output in DCF77 mode - POUT_BIT_FIXED_PULSE_LEN, ///< pulse length is fixed to the value reported in settings - POUT_BIT_NOT_INVERTIBLE, ///< output level can not be inverted + POUT_BIT_SUPP_IF_SYNC_ONLY, ///< ::POUT_IF_SYNC_ONLY is supported for this output + POUT_BIT_SUPP_DCF77_UTC, ///< ::POUT_SUPP_DCF77_UTC is supported for this output + POUT_BIT_FIXED_PULSE_LEN, ///< pulse length is limited to the value ::POUT_SETTINGS::mode_param + POUT_BIT_NOT_INVERTIBLE, ///< output level can't be inverted, thus ::POUT_INVERTED is not supported for this output + POUT_BIT_SUPP_PULSE_SHIFT, ///< output slopes can be shifted, see ::POUT_DATA::pulse_shift N_POUT_INFO_FLAG_BITS ///< number of known flag bits }; -#define POUT_SUPP_IF_SYNC_ONLY ( 1UL << POUT_BIT_SUPP_IF_SYNC_ONLY ) -#define POUT_SUPP_DCF77_UTC ( 1UL << POUT_BIT_SUPP_DCF77_UTC ) -#define POUT_FIXED_PULSE_LEN ( 1UL << POUT_BIT_FIXED_PULSE_LEN ) -#define POUT_NOT_INVERTIBLE ( 1UL << POUT_BIT_NOT_INVERTIBLE ) + +/** + * @brief Flag bit masks used with ::POUT_INFO::flags + * + * @see ::POUT_INFO_FLAG_BITS + */ +enum POUT_INFO_FLAG_MASKS +{ + POUT_SUPP_IF_SYNC_ONLY = ( 1UL << POUT_BIT_SUPP_IF_SYNC_ONLY ), ///< see ::POUT_BIT_SUPP_IF_SYNC_ONLY, ::POUT_IF_SYNC_ONLY + POUT_SUPP_DCF77_UTC = ( 1UL << POUT_BIT_SUPP_DCF77_UTC ), ///< see ::POUT_BIT_SUPP_DCF77_UTC, ::POUT_SUPP_DCF77_UTC + POUT_FIXED_PULSE_LEN = ( 1UL << POUT_BIT_FIXED_PULSE_LEN ), ///< see ::POUT_BIT_FIXED_PULSE_LEN + POUT_NOT_INVERTIBLE = ( 1UL << POUT_BIT_NOT_INVERTIBLE ), ///< see ::POUT_BIT_NOT_INVERTIBLE, ::POUT_INVERTED + POUT_SUPP_PULSE_SHIFT = ( 1UL << POUT_BIT_SUPP_PULSE_SHIFT ) ///< see ::POUT_BIT_SUPP_PULSE_SHIFT, ::POUT_DATA::pulse_shift +}; + /** - * @brief Current settings and general capabilities of a specific serial port + * @brief Current settings and general capabilities of a specific programmable pulse output * * This structure should be read from the device to retrieve the * current settings of a specific programmable output plus its capabilities, @@ -3817,56 +6350,109 @@ enum POUT_INFO_FLAG_BITS */ typedef struct { - uint16_t idx; ///< 0..RECEIVER_INFO::n_prg_out - 1 + uint16_t idx; ///< 0..::RECEIVER_INFO::n_prg_out-1 POUT_INFO pout_info; + } POUT_INFO_IDX; #define _mbg_swab_pout_info_idx_on_get( _p ) \ +do \ { \ _mbg_swab16( &(_p)->idx ); \ _mbg_swab_pout_info_on_get( &(_p)->pout_info ); \ -} +} while ( 0 ) +/** @} defgroup group_pout_api */ -/* - * The codes below are used with devices which support multiple - * ref time sources at the same time. The priorities of the - * supported ref time sources is configurable. - */ /** - * @brief All possibly supported ref time sources + * @defgroup group_multi_ref_all Support for multiple reference time sources + * + * Some devices can evaluate and synchronize to several different types + * of input signal, and eventually even several signals of the same type, + * e.g. several 1 PPS input signals. + * + * There are two different ways to configure multi ref devices. + * + * Newer devices which have the ::GPS_HAS_XMULTI_REF flag set in + * ::RECEIVER_INFO::features support the newer XMULTI_REF_... structures + * which provide a more flexible API, see @ref group_multi_ref_ext + * + * Older devices may have the ::GPS_FEAT_MULTI_REF flag set in which + * case an older API is supported, see @ref group_multi_ref_old + * + * Symbols defined in @ref group_multi_ref_common can be used + * with both APIs. + * + * @see @ref group_multi_ref_common + * @see @ref group_multi_ref_old + * @see @ref group_multi_ref_ext + * @{ */ + +/** + * @defgroup group_multi_ref_common Common multi ref definitions + * + * Common definitions used with both the old and the extended + * multi ref API. + * + * @{ */ + +/** + * @brief Enumeration of all known types of reference time source + * + * All known types of input signal which may possibly be supported + * by devices which support several different input signals, i.e. + * have the ::GPS_HAS_MULTI_REF or ::GPS_HAS_XMULTI_REF bit set + * in ::RECEIVER_INFO::features. Not all devices support each known + * type of input signal. * - * @see MULTI_REF_TYPE_MASKS + * @see @ref group_multi_ref_all + * @see ::DEFAULT_MULTI_REF_NAMES + * @see ::DEFAULT_MULTI_REF_NAMES_SHORT + * @see @ref MULTI_REF_TYPE_MASKS */ enum MULTI_REF_TYPES { - MULTI_REF_NONE = -1, ///< nothing, undefined - MULTI_REF_GPS = 0, ///< standard GPS - MULTI_REF_10MHZ, ///< 10 MHz input frequency - MULTI_REF_PPS, ///< 1 PPS input signal - MULTI_REF_10MHZ_PPS, ///< combined 10 MHz plus PPS - MULTI_REF_IRIG, ///< IRIG input - MULTI_REF_NTP, ///< Network Time Protocol (NTP) - MULTI_REF_PTP, ///< Precision Time Protocol (PTP, IEEE1588) - MULTI_REF_PTP_E1, ///< PTP over E1 - MULTI_REF_FREQ, ///< fixed frequency - MULTI_REF_PPS_STRING, ///< PPS in addition to string - MULTI_REF_GPIO, ///< variable input signal via GPIO - MULTI_REF_INTERNAL, ///< reserved, used internally by firmware only - MULTI_REF_PZF, ///< DCF77 PZF providing much more accuracy than a standard LWR - MULTI_REF_LWR, ///< long wave receiver. e.g. DCF77 AM, WWVB, MSF, JJY - MULTI_REF_GRC, ///< Glonass / GPS receiver - MULTI_REF_HAVEQUICK, ///< HaveQuick input - N_MULTI_REF ///< the number of defined sources, can not exceed bit number of uint32_t - 1 + /// This ref type must not be used as index, but marks particular + /// ::XMULTI_REF_SETTINGS structures as "unused". It is only + /// supported if bit ::XMRIF_BIT_MRF_NONE_SUPP is set. + MULTI_REF_NONE = -1, + + MULTI_REF_GPS = 0, ///< standard GPS + MULTI_REF_10MHZ, ///< 10 MHz input frequency + MULTI_REF_PPS, ///< 1 PPS input signal + MULTI_REF_10MHZ_PPS, ///< combined 10 MHz plus PPS + MULTI_REF_IRIG, ///< IRIG input + MULTI_REF_NTP, ///< Network Time Protocol (NTP) + MULTI_REF_PTP, ///< Precision Time Protocol (PTP/IEEE1588) + MULTI_REF_PTP_E1, ///< PTP over E1 + MULTI_REF_FREQ, ///< fixed frequency + MULTI_REF_PPS_STRING, ///< 1 PPS in addition to time string + MULTI_REF_GPIO, ///< variable input signal via GPIO + MULTI_REF_INTERNAL, ///< reserved, used internally by firmware only + MULTI_REF_PZF, ///< DCF77 PZF providing much more accuracy than a standard LWR + MULTI_REF_LWR, ///< long wave receiver. e.g. DCF77 AM, WWVB, MSF, JJY + MULTI_REF_GRC, ///< Glonass / GPS receiver + MULTI_REF_HAVEQUICK, ///< HaveQuick input + MULTI_REF_EXT_OSC, ///< external oscillator disciplined and looped back via 1 PPS I/O + MULTI_REF_SYNCE, ///< Synchronous Ethernet, needs (external) ethernet interface + N_MULTI_REF ///< the number of defined sources, must not exceed ::MAX_N_MULTI_REF_TYPES }; +/** + * @brief Theoretical maximum number of multi ref input signal types + * + * Actually only ::N_MULTI_REF types have been defined, but ::N_MULTI_REF + * must not exceed the number of bits which can be hold by a uint32_t type. + */ +#define MAX_N_MULTI_REF_TYPES 32 + /** - * @brief Names of supported ref time sources + * @brief Names of known ref time sources * - * @see MULTI_REF_TYPES + * @see ::MULTI_REF_TYPES */ #define DEFAULT_MULTI_REF_NAMES \ { \ @@ -3884,50 +6470,94 @@ enum MULTI_REF_TYPES "(reserved)", \ "DCF77 PZF Receiver", \ "Long Wave Receiver", \ - "GLONASS/GPS Receiver", \ - "HaveQuick Input" \ + "GNSS Receiver", \ + "HaveQuick Input", \ + "ext. Osc.", \ + "Synchronous Ethernet" \ +} + +/** + * @brief Short names of supported ref time sources + * + * Used e.g. to configure a particular input signal type + * + * @see ::MULTI_REF_TYPES + */ +#define DEFAULT_MULTI_REF_NAMES_SHORT \ +{ \ + "GPS", \ + "FRQ", \ + "PPS", \ + "10MHZ+PPS", \ + "TCR", \ + "NTP", \ + "PTP", \ + "PTP_E1", \ + "FIXED_FREQ", \ + "STRING+PPS", \ + "GPIO", \ + "(reserved)", \ + "PZF", \ + "LWR", \ + "GNSS", \ + "HQI", \ + "EXT", \ + "SYNCE" \ } /** - * @brief Bit masks according to enumerated ref time sources + * @brief Bit masks associated with multi ref types * - * @see MULTI_REF_TYPES - */ -enum MULTI_REF_TYPE_MASKS -{ - HAS_MULTI_REF_GPS = ( 1UL << MULTI_REF_GPS ), ///< see ::MULTI_REF_GPS - HAS_MULTI_REF_10MHZ = ( 1UL << MULTI_REF_10MHZ ), ///< see ::MULTI_REF_10MHZ - HAS_MULTI_REF_PPS = ( 1UL << MULTI_REF_PPS ), ///< see ::MULTI_REF_PPS - HAS_MULTI_REF_10MHZ_PPS = ( 1UL << MULTI_REF_10MHZ_PPS ), ///< see ::MULTI_REF_10MHZ_PPS - HAS_MULTI_REF_IRIG = ( 1UL << MULTI_REF_IRIG ), ///< see ::MULTI_REF_IRIG - HAS_MULTI_REF_NTP = ( 1UL << MULTI_REF_NTP ), ///< see ::MULTI_REF_NTP - HAS_MULTI_REF_PTP = ( 1UL << MULTI_REF_PTP ), ///< see ::MULTI_REF_PTP - HAS_MULTI_REF_PTP_E1 = ( 1UL << MULTI_REF_PTP_E1 ), ///< see ::MULTI_REF_PTP_E1 + * Used to indicate which multi ref types are supported, e.g. + * in ::XMULTI_REF_INFO::supp_ref or ::MULTI_REF_INFO::supp_ref. + * + * @see ::MULTI_REF_TYPES + * + * @anchor MULTI_REF_TYPE_MASKS @{ */ - HAS_MULTI_REF_FREQ = ( 1UL << MULTI_REF_FREQ ), ///< see ::MULTI_REF_FREQ - HAS_MULTI_REF_PPS_STRING = ( 1UL << MULTI_REF_PPS_STRING ), ///< see ::MULTI_REF_PPS_STRING - HAS_MULTI_REF_GPIO = ( 1UL << MULTI_REF_GPIO ), ///< see ::MULTI_REF_GPIO - HAS_MULTI_REF_INTERNAL = ( 1UL << MULTI_REF_INTERNAL ), ///< see ::MULTI_REF_INTERNAL - HAS_MULTI_REF_PZF = ( 1UL << MULTI_REF_PZF ), ///< see ::MULTI_REF_PZF - HAS_MULTI_REF_LWR = ( 1UL << MULTI_REF_LWR ), ///< see ::MULTI_REF_LWR - HAS_MULTI_REF_GRC = ( 1UL << MULTI_REF_GRC ), ///< see ::MULTI_REF_GRC - HAS_MULTI_REF_HAVEQUICK = ( 1UL << MULTI_REF_HAVEQUICK ) ///< see ::MULTI_REF_HAVEQUICK -}; +#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 -/* - * There are 2 different ways to configure multi ref support - * provided by some devices. +#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 + +/** @} anchor MULTI_REF_TYPE_MASKS */ + +/** @} defgroup group_multi_ref_common */ + + + +/** + * @defgroup group_multi_ref_old Definitions used with the old multi ref API + * + * This API has been deprecated by a newer one which should be used preferably. * - * Newer devices which have the GPS_FEAT_XMULTI_REF flag set - * in RECEIVER_INFO::features support the newer XMULTI_REF_... - * structures which provide a more flexible interface. + * @see @ref group_multi_ref_ext * - * Older devices which have the GPS_FEAT_MULTI_REF flag set - * support these MULTI_REF_... structures below where - * the number of supported input sources and priorities - * is limited to N_MULTI_REF_PRIO. + * @{ */ + +/** + * @brief Maximum number of input sources + * + * The number of supported input sources and priorities is + * limited to this value if the old API is used, i.e. if only + * the ::GPS_FEAT_MULTI_REF flag is set. */ #define N_MULTI_REF_PRIO 4 @@ -3938,12 +6568,13 @@ enum MULTI_REF_TYPE_MASKS * The number stored in prio[0] of the array indicates the ref time * source with highest priority. If that source fails, the device * falls back to the source indicated by prio[1]. Each field of - * the prio[] array must be set to one of the values 0..N_MULTI_REF-1, - * or to -1 (0xFF) if the value is not assigned. + * the prio[] array has to be set to one of the values 0..::N_MULTI_REF-1, + * or to ::MULTI_REF_NONE if no time source is specified. */ typedef struct { uint8_t prio[N_MULTI_REF_PRIO]; + } MULTI_REF_SETTINGS; @@ -3955,20 +6586,25 @@ typedef struct typedef struct { MULTI_REF_SETTINGS settings; ///< current settings - uint32_t supp_ref; ///< bit mask of supported sources, see ::MULTI_REF_TYPE_MASKS - uint16_t n_levels; ///< supp. levels, 0..N_MULTI_REF_PRIO-1 + uint32_t supp_ref; ///< bit mask of supported sources, see @ref MULTI_REF_TYPE_MASKS + uint16_t n_levels; ///< supported priority levels, 0..::N_MULTI_REF_PRIO-1 uint16_t flags; ///< reserved, currently always 0 + } MULTI_REF_INFO; /** * @brief A data type used to query MULTI_REF status information + * + * @see ::MULTI_REF_STATUS_BIT_MASKS */ -typedef uint16_t MULTI_REF_STATUS; ///< @see MULTI_REF_STATUS_BITS +typedef uint16_t MULTI_REF_STATUS; /** - * @brief Bits and associated masks used with ::MULTI_REF_STATUS + * @brief Enumeration of multi ref status bits + * + * @see ::MULTI_REF_STATUS_BIT_MASKS */ enum MULTI_REF_STATUS_BITS { @@ -3976,53 +6612,106 @@ enum MULTI_REF_STATUS_BITS WRN_COLD_BOOT, ///< GPS is in cold boot mode WRN_WARM_BOOT, ///< GPS is in warm boot mode WRN_ANT_DISCONN, ///< antenna is disconnected - WRN_10MHZ_UNLOCK, ///< impossible to lock to external 10MHz reference - WRN_1PPS_UNLOCK, ///< impossible to lock to external 1PPS reference + WRN_10MHZ_UNLOCK, ///< impossible to lock to external 10 MHz reference + WRN_1PPS_UNLOCK, ///< impossible to lock to external 1 PPS reference WRN_GPS_UNLOCK, ///< impossible to lock to GPS - WRN_10MHZ_MISSING, ///< external 10MHz signal not available - WRN_1PPS_MISSING, ///< external 1PPS signal not available + WRN_10MHZ_MISSING, ///< external 10 MHz signal not available + WRN_1PPS_MISSING, ///< external 1 PPS signal not available N_MULTI_REF_STATUS_BITS ///< the number of known bits }; -#define MSK_WRN_COLD_BOOT ( 1UL << WRN_COLD_BOOT ) -#define MSK_WRN_WARM_BOOT ( 1UL << WRN_WARM_BOOT ) -#define MSK_WRN_ANT_DISCONN ( 1UL << WRN_ANT_DISCONN ) -#define MSK_WRN_10MHZ_UNLOCK ( 1UL << WRN_10MHZ_UNLOCK ) -#define MSK_WRN_1PPS_UNLOCK ( 1UL << WRN_1PPS_UNLOCK ) -#define MSK_WRN_GPS_UNLOCK ( 1UL << WRN_GPS_UNLOCK ) -#define MSK_WRN_10MHZ_MISSING ( 1UL << WRN_10MHZ_MISSING ) -#define MSK_WRN_1PPS_MISSING ( 1UL << WRN_1PPS_MISSING ) -#define MSK_WRN_MODULE_MODE ( 1UL << WRN_MODULE_MODE ) + +/** + * @brief Bit masks associated with ::MULTI_REF_STATUS_BITS + * + * Used with ::MULTI_REF_STATUS. + * + * @see ::MULTI_REF_STATUS_BITS + */ +enum MULTI_REF_STATUS_BIT_MASKS +{ + MSK_WRN_COLD_BOOT = ( 1UL << WRN_COLD_BOOT ), ///< see ::WRN_COLD_BOOT + MSK_WRN_WARM_BOOT = ( 1UL << WRN_WARM_BOOT ), ///< see ::WRN_WARM_BOOT + MSK_WRN_ANT_DISCONN = ( 1UL << WRN_ANT_DISCONN ), ///< see ::WRN_ANT_DISCONN + MSK_WRN_10MHZ_UNLOCK = ( 1UL << WRN_10MHZ_UNLOCK ), ///< see ::WRN_10MHZ_UNLOCK + MSK_WRN_1PPS_UNLOCK = ( 1UL << WRN_1PPS_UNLOCK ), ///< see ::WRN_1PPS_UNLOCK + MSK_WRN_GPS_UNLOCK = ( 1UL << WRN_GPS_UNLOCK ), ///< see ::WRN_GPS_UNLOCK + MSK_WRN_10MHZ_MISSING = ( 1UL << WRN_10MHZ_MISSING ), ///< see ::WRN_10MHZ_MISSING + MSK_WRN_1PPS_MISSING = ( 1UL << WRN_1PPS_MISSING ), ///< see ::WRN_1PPS_MISSING + MSK_WRN_MODULE_MODE = ( 1UL << WRN_MODULE_MODE ) ///< see ::WRN_MODULE_MODE +}; + +/** @} defgroup group_multi_ref_old */ /** - * @defgroup group_xmr_cfg Extended multiref configuration stuff + * @defgroup group_multi_ref_ext Extended multi ref definitions + * + * If the ::GPS_HAS_XMULTI_REF feature is set in ::RECEIVER_INFO::features then + * the XMULTI_REF (extended multi ref, XMR) feature and API are supported and + * have to be used in favor of the older multi ref API (see @ref group_multi_ref_old). + * + * Devices supporting the XMULTI_REF feature provide a number of + * priority levels addressed by the priority index, starting at 0 + * for highest priority. A single reference time source from the set + * of supported sources can be assigned to each priority level. + * + * These structures are used to configure the individual time source for each + * priority level, and retrieve the status of the time source at each priority level. + * + * If ::GPS_HAS_XMRS_MULT_INSTC is also set in ::RECEIVER_INFO::features then + * ::XMULTI_REF_INSTANCES can be used to find out which types of input source + * are supported (::XMULTI_REF_INSTANCES::n_inst array entries != 0), and + * how many priority levels are supported to which an input source can be + * assigned (::XMULTI_REF_INSTANCES::n_xmr_settings). * - * If the RECEIVER_INFO::features flag GPS_FEAT_XMULTI_REF is set - * then the following XMULTI_REF_... data structures must be used - * instead of the older MULTI_REF_... structures. + * If ::XMRIF_MSK_HOLDOVER_STATUS_SUPP is set in ::XMULTI_REF_INSTANCES::flags + * then ::XMR_HOLDOVER_STATUS can be used to monitor the switching between + * different time sources when they become available or unavailable. * - * Those devices support a number of priority levels addressed by - * the priority index, starting at 0 for highest priority. A single - * reference time source from the set of supported sources can be - * assigned to each priority level. + * If an XMR time source at a high priority level becomes unavailable the + * XMR control function tries to find and switch to a different time source + * at a lower level of the priority list, which is still available. * - * These structures are used to configure the individual - * time source for each priority level, and retrieve the status - * of the time source at each priority level. + * On the other hand, if a time source at a higher priority level becomes + * available again, the XMR control function switches over to the time source + * at the higher priority even if the current time source is still available. + * + * If the accuracy of the time source at the next priority level is better than + * the accuracy of the time source at the current priority level then switching + * can be done immediately. However, if the next time source is worse than + * the current one it makes more sense to switch only after a certain holdover + * interval. + * + * The holdover interval is computed so that the time error due to the expected + * drift of the previously disciplined time base grows until it reaches the + * accuracy level of the next available reference time source. + * + * Only if the time source at the current priority level is still unavailable + * when the holdover interval expires the reference time source is switched + * to the time source at the next available priority level. * * @{ */ + /** * @brief Identifier for a reference source */ typedef struct { - uint8_t type; ///< @see MULTI_REF_TYPES + 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; +#define _mbg_swab_xmulti_ref_id( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->type ); \ + _mbg_swab8( &(_p)->instance ); \ +} while ( 0 ) + /** @@ -4030,52 +6719,137 @@ typedef struct */ typedef struct { - XMULTI_REF_ID id; ///< time source identifier - uint16_t flags; ///< reserved, currently always 0 - NANO_TIME bias; ///< time bias, e.g. path delay - NANO_TIME precision; ///< precision of the time source - uint32_t fine_limit; ///< smooth control if below this limit + XMULTI_REF_ID id; ///< reference time source identifier + uint16_t flags; ///< 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 + } XMULTI_REF_SETTINGS; +#define _mbg_swab_xmulti_ref_settings( _p ) \ +do \ +{ \ + _mbg_swab_xmulti_ref_id( &(_p)->id ); \ + _mbg_swab16( &(_p)->flags ); \ + _mbg_swab_nano_time( &(_p)->bias ); \ + _mbg_swab_nano_time( &(_p)->precision ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + /** - * @brief Reference source configuration settings for a specific priority level + * @brief Reference source configuration for a specific priority level * - * @note After configuring, a structure with idx == 0xFFFF (-1) must be sent - * to let the changes become effective. + * @note After all other ::XMULTI_REF_SETTINGS_IDX configuration structures + * have been sent to a device, an additional structure with idx == -1 (0xFFFF) + * has to be sent to let the new settings come into effect. */ typedef struct { - uint16_t idx; ///< the priority level index, highest == 0 - XMULTI_REF_SETTINGS settings; ///< the settings configured for this level + uint16_t idx; ///< the priority level index (highest == 0), 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1 + XMULTI_REF_SETTINGS settings; ///< the settings configured for this level + } XMULTI_REF_SETTINGS_IDX; +#define _mbg_swab_xmulti_ref_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_xmulti_ref_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +/** + * @brief Bit masks used to define ::XMR_SETTINGS_FLAG_MSKS + */ +enum XMR_SETTINGS_FLAG_BITS +{ + XMRSF_BIT_AUTO_BIAS_MASTER, ///< src is allowed to operate as zero asymmetry master + XMRSF_BIT_AUTO_BIAS_SLAVE, ///< accept static bias correction from zero asymmetry master + XMRSF_BIT_ASYMMETRY_STEP_DETECTION, ///< static bias auto correction in case of step + XMRSF_BIT_IS_TRUSTED_SRC, ///< src can be used as a trusted src for spoofing detection + XMRSF_BIT_USE_TRUSTED_SRC, ///< use a trusted source for consistency check and spoofing detection + XMRSF_BIT_IS_TIME_OF_DAY_SRC, ///< src can be used for time of day synchronization + XMRSF_BIT_IS_PHASE_SRC, ///< src can be used for phase synchronization + N_XMRSF_BITS ///< number of known flag bits +}; + + +/** + * @brief Bit masks used with ::XMULTI_REF_SETTINGS::flags and ::XMR_EXT_SRC_INFO::supp_flags + */ +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 +}; + /** - * @brief Reference source configuration settings and capabilities + * @brief Reference source capabilities and current configuration */ typedef struct { - XMULTI_REF_SETTINGS settings; ///< current settings - uint32_t supp_ref; ///< bit mask of supported sources, see ::MULTI_REF_TYPES - uint8_t n_supp_ref; ///< number of supported ref time sources - uint8_t n_prio; ///< number of supported priority levels - uint16_t flags; ///< currently always 0 + XMULTI_REF_SETTINGS settings; ///< current settings + + /** + * @deprecated Deprecated by ::XMULTI_REF_INSTANCES::n_inst. + * If ::GPS_HAS_XMRS_MULT_INSTC is *not* set then this field provides + * a bit mask of supported sources (see @ref MULTI_REF_TYPE_MASKS), + * and only a single instance of each source signal type is supported. + */ + uint32_t supp_ref; + + /** + * @deprecated Deprecated by ::XMULTI_REF_INSTANCES::n_xmr_settings. + * If ::GPS_HAS_XMRS_MULT_INSTC is *not* set then this field + * reports the number of priority levels supported by the device. + */ + uint8_t n_supp_ref; + + uint8_t n_prio; ///< reserved, don't use, currently always 0 //##++++ TODO: check which devices support/use this field + uint16_t flags; ///< reserved, don't use, currently always 0 + } XMULTI_REF_INFO; +#define _mbg_swab_xmulti_ref_info( _p ) \ +do \ +{ \ + _mbg_swab_xmulti_ref_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_ref ); \ + _mbg_swab8( &(_p)->n_supp_ref ); \ + _mbg_swab8( &(_p)->n_prio ); \ + _mbg_swab16( &(_p)->flags ); \ +} while ( 0 ) + /** - * @brief Reference source configuration settings and capabilities for a specific priority level + * @brief Reference source capabilities and current configuration for a specific priority level */ typedef struct { - uint16_t idx; ///< the priority level index, highest == 0 - XMULTI_REF_INFO info; ///< ref source cfg and capabilities + uint16_t idx; ///< the priority level index (highest == 0), 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1 + XMULTI_REF_INFO info; ///< ref source configuration and capabilities + } XMULTI_REF_INFO_IDX; +#define _mbg_swab_xmulti_ref_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_xmulti_ref_info( &(_p)->info ); \ +} while ( 0 ) + /** @@ -4083,14 +6857,26 @@ typedef struct */ typedef struct { - XMULTI_REF_ID id; ///< time source identifier, see ::MULTI_REF_TYPES - uint16_t status; ///< status bits, see ::XMR_REF_STATUS_BITS - NANO_TIME offset; ///< time offset from main time base - uint16_t flags; ///< flags, see ::XMR_REF_FLAG_BITS - uint8_t ssm; ///< synchronization status message (if supported by src.) - uint8_t soc; ///< signal outage counter (updated on loss of signal) + XMULTI_REF_ID id; ///< time source identifier + uint16_t status; ///< status bits, see @ref XMR_REF_STATUS_BIT_MASKS + NANO_TIME offset; ///< time offset from main time base @todo specify sign vs. earlier/later + uint16_t flags; ///< flags, see ::XMR_QL // TODO ### + uint8_t ssm; ///< synchronization status message, if supported by signal source + uint8_t soc; ///< signal outage counter, incremented on loss of signal + } XMULTI_REF_STATUS; +#define _mbg_swab_xmulti_ref_status( _p ) \ +do \ +{ \ + _mbg_swab_xmulti_ref_id( &(_p)->id ); \ + _mbg_swab16( &(_p)->status ); \ + _mbg_swab_nano_time( &(_p)->offset ); \ + _mbg_swab16( &(_p)->flags ); \ + _mbg_swab8( &(_p)->ssm ); \ + _mbg_swab8( &(_p)->soc ); \ +} while ( 0 ) + /** @@ -4098,46 +6884,114 @@ typedef struct */ typedef struct { - uint16_t idx; /**< the priority level index, highest == 0 */ - XMULTI_REF_STATUS status; /**< status information */ + uint16_t idx; ///< the priority level index (highest == 0), 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1 + XMULTI_REF_STATUS status; ///< status information } XMULTI_REF_STATUS_IDX; +#define _mbg_swab_xmulti_ref_status_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_xmulti_ref_status( &(_p)->status ); \ +} while ( 0 ) + /** - * @brief Bits and bit masks used with XMULTI_REF_STATUS::status + * @brief ::TODO + * + * Used with the ::... field of ::XMULTI_REF_STATUS::flags + * + * @see ::XMULTI_REF_STATUS::flags + * @see ::XMR_QL_TDEV_MASK + * @see ::_GET_XMR_QL_TDEV + * @see ::_PUT_XMR_QL_TDEV + * @see ::XMR_QL_MTIE_MASK + * @see ::_GET_XMR_QL_MTIE + * @see ::_PUT_XMR_QL_MTIE + */ +enum XMR_QL +{ + XMR_QL_UNKNOWN, + XMR_QL_GREEN, + XMR_QL_YELLOW, + XMR_QL_RED, + N_XMR_QL +}; + +#define XMR_QL_TDEV_MASK ( 0x03 << 0 ) +#define XMR_QL_MTIE_MASK ( 0x03 << 2 ) + +#define _GET_XMR_QL_TDEV( _x ) ( ( ( _x ) & XMR_QL_TDEV_MASK ) >> 0 ) +#define _PUT_XMR_QL_TDEV( _x, _ql ) \ +do { \ + ( _x ) = ( ( _x ) & ~XMR_QL_TDEV_MASK ) | ( ( ( _ql ) << 0 ) & XMR_QL_TDEV_MASK ); \ +} while ( 0 ) + + +#define _GET_XMR_QL_MTIE( _x ) ( ( ( _x ) & XMR_QL_MTIE_MASK ) >> 2 ) +#define _PUT_XMR_QL_MTIE( _x, _ql ) \ +do { \ + ( _x ) = ( ( _x ) & ~XMR_QL_MTIE_MASK ) | ( ( ( _ql ) << 2 ) & XMR_QL_MTIE_MASK ); \ +} while ( 0 ) + + + +/** + * @brief XMULTI_REF status bits */ enum XMR_REF_STATUS_BITS { - XMRS_BIT_NOT_SUPP, ///< ref type cfg'd for this level is not supported - XMRS_BIT_NO_CONN, ///< input signal is disconnected - XMRS_BIT_NO_SIGNAL, ///< no input signal - XMRS_BIT_IS_MASTER, ///< reference is master source - XMRS_BIT_IS_LOCKED, ///< locked to input signal - XMRS_BIT_IS_ACCURATE, ///< oscillator control has reached full accuracy - XMRS_BIT_NOT_SETTLED, ///< reference time signal not settled - XMRS_BIT_NOT_PHASE_LOCKED, ///< oscillator not phase locked to PPS - XMRS_BIT_NUM_SRC_EXC, ///< number of available sources exceeds what can be handled - XMRS_BIT_IS_EXTERNAL, ///< this ref source is on extension card - XMRS_BIT_LOW_JITTER, ///< this ref source has low jitter - N_XMRS_BITS ///< number of know status bits -}; - -#define XMRS_MSK_NOT_SUPP ( 1UL << XMRS_BIT_NOT_SUPP ) -#define XMRS_MSK_NO_CONN ( 1UL << XMRS_BIT_NO_CONN ) -#define XMRS_MSK_NO_SIGNAL ( 1UL << XMRS_BIT_NO_SIGNAL ) -#define XMRS_MSK_IS_MASTER ( 1UL << XMRS_BIT_IS_MASTER ) -#define XMRS_MSK_IS_LOCKED ( 1UL << XMRS_BIT_IS_LOCKED ) -#define XMRS_MSK_IS_ACCURATE ( 1UL << XMRS_BIT_IS_ACCURATE ) -#define XMRS_MSK_NOT_SETTLED ( 1UL << XMRS_BIT_NOT_SETTLED ) -#define XMRS_MSK_NOT_PHASE_LOCKED ( 1UL << XMRS_BIT_NOT_PHASE_LOCKED ) -#define XMRS_MSK_NUM_SRC_EXC ( 1UL << XMRS_BIT_NUM_SRC_EXC ) -#define XMRS_MSK_IS_EXTERNAL ( 1UL << XMRS_BIT_IS_EXTERNAL ) -#define XMRS_MSK_LOW_JITTER ( 1UL << XMRS_BIT_LOW_JITTER ) + XMRS_BIT_NOT_SUPP, ///< ref type cfg'd for this level is not supported + XMRS_BIT_NO_CONN, ///< input signal is disconnected + XMRS_BIT_NO_SIGNAL, ///< no input signal + XMRS_BIT_IS_MASTER, ///< reference is master source + XMRS_BIT_IS_LOCKED, ///< locked to input signal + XMRS_BIT_IS_ACCURATE, ///< oscillator control has reached full accuracy + XMRS_BIT_NOT_SETTLED, ///< reference time signal not settled + XMRS_BIT_NOT_PHASE_LOCKED, ///< oscillator not phase locked to PPS + XMRS_BIT_NUM_SRC_EXC, ///< number of available sources exceeds what can be handled + XMRS_BIT_IS_EXTERNAL, ///< this ref source is on extension card + XMRS_BIT_LOW_JITTER, ///< this ref source has low jitter + XMRS_BIT_ITU_LIMIT_VIOLATED, ///< ITU limits violated (valid if device has ::XMR_METRICS) + XMRS_BIT_TRS_LIMIT_VIOLATED, ///< Trusted source offset limit violated (valid if device has ::XMRSF_MSK_USE_TRUSTED_SRC) + N_XMRS_BITS ///< number of know status bits +}; -/* - * Initializers for XMRS status bit strings. + + +/** + * @brief Bit masks associated with ::XMR_REF_STATUS_BITS + * + * Used with ::XMULTI_REF_STATUS::status. + * + * @see ::XMR_REF_STATUS_BITS + * + * @anchor XMR_REF_STATUS_BIT_MASKS @{ */ + +#define XMRS_MSK_NOT_SUPP ( 1UL << XMRS_BIT_NOT_SUPP ) ///< see ::XMRS_BIT_NOT_SUPP +#define XMRS_MSK_NO_CONN ( 1UL << XMRS_BIT_NO_CONN ) ///< see ::XMRS_BIT_NO_CONN +#define XMRS_MSK_NO_SIGNAL ( 1UL << XMRS_BIT_NO_SIGNAL ) ///< see ::XMRS_BIT_NO_SIGNAL +#define XMRS_MSK_IS_MASTER ( 1UL << XMRS_BIT_IS_MASTER ) ///< see ::XMRS_BIT_IS_MASTER +#define XMRS_MSK_IS_LOCKED ( 1UL << XMRS_BIT_IS_LOCKED ) ///< see ::XMRS_BIT_IS_LOCKED +#define XMRS_MSK_IS_ACCURATE ( 1UL << XMRS_BIT_IS_ACCURATE ) ///< see ::XMRS_BIT_IS_ACCURATE +#define XMRS_MSK_NOT_SETTLED ( 1UL << XMRS_BIT_NOT_SETTLED ) ///< see ::XMRS_BIT_NOT_SETTLED +#define XMRS_MSK_NOT_PHASE_LOCKED ( 1UL << XMRS_BIT_NOT_PHASE_LOCKED ) ///< see ::XMRS_BIT_NOT_PHASE_LOCKED +#define XMRS_MSK_NUM_SRC_EXC ( 1UL << XMRS_BIT_NUM_SRC_EXC ) ///< see ::XMRS_BIT_NUM_SRC_EXC +#define XMRS_MSK_IS_EXTERNAL ( 1UL << XMRS_BIT_IS_EXTERNAL ) ///< see ::XMRS_BIT_IS_EXTERNAL +#define XMRS_MSK_LOW_JITTER ( 1UL << XMRS_BIT_LOW_JITTER ) ///< see ::XMRS_BIT_LOW_JITTER +#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 */ + + + +/** + * @brief XMRS status bit name strings + * + * @see ::XMR_REF_STATUS_BITS */ #define MBG_XMRS_STATUS_STRS \ { \ @@ -4151,30 +7005,15 @@ enum XMR_REF_STATUS_BITS "Phase not locked", \ "Number sources exceeds limit", \ "Is external", \ - "Low jitter" \ + "Low jitter", \ + "ITU Limit violated", \ + "TRS Limit violated" \ } -/** - * @brief Bits and masks used with XMULTI_REF_STATUS::flags - * - * @note This API is only supported if bit ::GPS_FEAT_XMRS_MULT_INSTC - * is set in RECEIVER_INFO::features. - */ -enum XMR_REF_FLAG_BITS -{ - XMRSF_BIT_MULT_INSTC_SUPP, ///< multiple instances of the same ref type supported - XMRSF_BIT_IS_EXTERNAL, ///< this ref source is on extension card - N_XMRS_FLAGS -}; - -#define XMRSF_MSK_MULT_INSTC_SUPP ( 1UL << XMRSF_BIT_MULT_INSTC_SUPP ) -#define XMRSF_MSK_IS_EXTERNAL ( 1UL << XMRSF_BIT_IS_EXTERNAL ) - - /* - * An initializer for a XMULTI_REF_STATUS variable + * An initializer for a ::XMULTI_REF_STATUS variable * with status invalid / not used */ #define XMULTI_REF_STATUS_INVALID \ @@ -4186,41 +7025,574 @@ enum XMR_REF_FLAG_BITS } + /** - * @brief The number of supported instances of each ref source type + * @brief General info on supported XMR sources and instances + * + * @note This structure is only supported if ::GPS_HAS_XMRS_MULT_INSTC + * is set in ::RECEIVER_INFO::features. + * + * The field ::XMULTI_REF_INSTANCES::n_xmr_settings reports the maximum number + * of entries that can be held by the input source table provided by this device. + * The input source table entry with the lowest index has the highest priority, + * and values 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1 can be used as index + * when reading ::XMULTI_REF_INFO_IDX or ::XMULTI_REF_STATUS_IDX from the device, + * or when writing ::XMULTI_REF_SETTINGS_IDX to the device to configure + * the priority/order of input sources. + * + * An input source table entry is empty if ::XMULTI_REF_ID::type is set to + * ::MULTI_REF_NONE in ::XMULTI_REF_SETTINGS::id, and accordingly + * in ::XMULTI_REF_STATUS::id. * - * @note This structure is only supported if bit ::GPS_FEAT_XMRS_MULT_INSTC - * is set in RECEIVER_INFO::features. + * The array ::XMULTI_REF_INSTANCES::n_inst reports how many instances are supported + * for every known reference type. For example, if 2 PPS input signals were supported + * then ::XMULTI_REF_INSTANCES::n_inst[::MULTI_REF_PPS] was set to 2. Even though + * this array can hold up to ::MAX_N_MULTI_REF_TYPES entries, the number entries + * which are actually used is ::N_MULTI_REF, according to the number of known + * reference signal types, which is less or equal than ::MAX_N_MULTI_REF_TYPES. */ typedef struct { - uint32_t flags; ///< reserved, currently always 0 - uint16_t n_xmr_settings; ///< number of configurable multi ref settings - uint8_t slot_id; ///< current slot ID of board (0..15) - uint8_t reserved; ///< reserved, currently always 0 - uint8_t n_inst[32]; ///< ::N_MULTI_REF entries used, but can not exceed bit number of uint32_t - 1 + uint32_t flags; ///< see ::XMR_INST_FLAG_BIT_MASKS + uint16_t n_xmr_settings; ///< number of ::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 + uint8_t n_inst[MAX_N_MULTI_REF_TYPES]; ///< the number of supported instances of each input signal type + } XMULTI_REF_INSTANCES; +#define _mbg_swab_xmulti_ref_instances( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab16( &(_p)->n_xmr_settings ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of flag bits used with XMULTI_REF instances + * + * @see ::XMR_INST_FLAG_BIT_MASKS + */ +enum XMR_INST_FLAGS +{ + /// This flag indicates that configuration programs may set + /// ::XMULTI_REF_ID::type to ::MULTI_REF_NONE in ::XMULTI_REF_SETTINGS::id + /// for unused priority levels, and that this will be reflected in + /// ::XMULTI_REF_STATUS::id accordingly. With some older firmware versions + /// this was not supported. + XMRIF_BIT_MRF_NONE_SUPP, + + XMRIF_BIT_HOLDOVER_STATUS_SUPP, ///< ::XMR_HOLDOVER_STATUS and associated types supported + + 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 +}; + + +/** + * @brief Bit masks associated with ::XMR_INST_FLAGS + * + * Used with ::XMULTI_REF_INSTANCES::flags. + * + * @see ::XMR_INST_FLAGS + */ +enum XMR_INST_FLAG_BIT_MASKS +{ + XMRIF_MSK_MRF_NONE_SUPP = ( 1UL << XMRIF_BIT_MRF_NONE_SUPP ), ///< see ::XMRIF_BIT_MRF_NONE_SUPP + XMRIF_MSK_HOLDOVER_STATUS_SUPP = ( 1UL << XMRIF_BIT_HOLDOVER_STATUS_SUPP ), ///< see ::XMRIF_BIT_HOLDOVER_STATUS_SUPP + 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 +}; + + + +/** + * @brief XMR holdover interval, or elapsed holdover time, in [s] + */ +typedef uint32_t XMR_HOLDOVER_INTV; + +#define _mbg_swab_xmr_holdover_intv( _p ) \ + _mbg_swab32( _p ) + + + +/** + * @brief A code used to indicate that a input source table index is unspecified + */ +#define XMR_PRIO_LVL_UNSPEC -1 + + + +/** + * @brief XMR holdover status + * + * Only supported if ::XMRIF_MSK_HOLDOVER_STATUS_SUPP is set in ::XMULTI_REF_INSTANCES::flags + * + * Reports the current holdover status including the elapsed holdover time + * and the currently active holdover interval, as well as the indices of the + * current and next XMR time source. + * + * The flag ::XMR_HLDOVR_MSK_IN_HOLDOVER is set if holdover mode is currently active. + * + * The fields ::XMR_HOLDOVER_STATUS::curr_prio and ::XMR_HOLDOVER_STATUS::nxt_prio + * specify the current or next priority level which can be in the range + * 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, or ::XMR_PRIO_LVL_UNSPEC if the + * index is undefined, e.g. because no input source is available to which can + * be switched after the holdover interval. + * + * The ::XMR_HOLDOVER_STATUS::mode field indicates the current XMR/holdover mode + * which is usually ::XMR_HLDOVR_AUTONOMOUS. However, in certain applications + * XMR switching is controlled remotely, in which case ::XMR_HOLDOVER_STATUS::mode + * is set to ::XMR_HLDOVR_REMOTE. + * + * If the device is in remote mode and needs to switch XMR sources then mode changes + * to ::XMR_HLDOVR_PRE_AUTONOMOUS, and the ::XMR_HOLDOVER_STATUS::remote_watchdog + * starts to count down. If the watchdog expires before a remote switch command + * has been received the device switches to ::XMR_HLDOVR_AUTONOMOUS. + */ +typedef struct +{ + uint8_t mode; ///< XMR/holdover mode, see ::XMR_HOLDOVER_STATUS_MODES + int8_t curr_prio; ///< current priority level, 0..::XMULTI_REF_INSTANCES::n_xmr_settings, or ::XMR_PRIO_LVL_UNSPEC + int8_t nxt_prio; ///< next priority level after holdover, 0..::XMULTI_REF_INSTANCES::n_xmr_settings, or ::XMR_PRIO_LVL_UNSPEC + uint8_t remote_watchdog; ///< counts down in ::XMR_HLDOVR_PRE_AUTONOMOUS mode + uint32_t time_offset_ns; ///< estimated time offset in holdover operation + XMR_HOLDOVER_INTV elapsed; ///< elapsed time in holdover mode, only valid if ::XMR_HLDOVR_MSK_IN_HOLDOVER is set + XMR_HOLDOVER_INTV interval; ///< current holdover interval, only valid if ::XMR_HLDOVR_MSK_IN_HOLDOVER is set + uint32_t flags; ///< holdover status flags, see ::XMR_HOLDOVER_STATUS_FLAG_MASKS + +} XMR_HOLDOVER_STATUS; + +#define _mbg_swab_xmr_holdover_status( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->mode ); \ + _mbg_swab8( &(_p)->curr_prio ); \ + _mbg_swab8( &(_p)->nxt_prio ); \ + _mbg_swab8( &(_p)->remote_watchdog ); \ + _mbg_swab32( &(_p)->time_offset_ns ); \ + _mbg_swab_xmr_holdover_intv( &(_p)->elapsed ); \ + _mbg_swab_xmr_holdover_intv( &(_p)->interval ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + + +/** + * @brief XMR holdover status modes + * + * Used with ::XMR_HOLDOVER_STATUS::mode. + * + * @see ::XMR_HOLDOVER_STATUS_MODE_NAMES + */ +enum XMR_HOLDOVER_STATUS_MODES +{ + XMR_HLDOVR_AUTONOMOUS, ///< autonomous mode, XMR sources are selected automatically by the device + XMR_HLDOVR_PRE_AUTONOMOUS, ///< going to switch to autonomous mode when ::XMR_HOLDOVER_STATUS::remote_watchdog reaches 0 + XMR_HLDOVR_REMOTE, ///< remote mode, XMR switching done by external command/control + N_XMR_HOLDOVER_STATUS_MODES ///< the number of known modes +}; + + +/** + * @brief String initializers for XMR holdover status mode + * + * @see ::XMR_HOLDOVER_STATUS_MODES + */ +#define XMR_HOLDOVER_STATUS_MODE_NAMES \ +{ \ + "Autonomous", \ + "Pre-Autonomous", \ + "Remote" \ +} + + + +/** + * @brief XMR holdover status flag bits + * + * Used to define ::XMR_HOLDOVER_STATUS_FLAG_MASKS. + */ +enum XMR_HOLDOVER_STATUS_FLAG_BITS +{ + XMR_HLDOVR_BIT_IN_HOLDOVER, ///< the device is currently in holdover mode + XMR_HLDOVR_BIT_TRANSITION_ENBD, ///< timebase is in transition (being slewed) after sources have been switched + XMR_HLDOVR_BIT_IN_TRANSITION, ///< transition is currently active, slewing in progress + XMR_HLDOVR_BIT_TIME_OFFS_VALID, ///< values in field ::XMR_HOLDOVER_STATUS::time_offset_ns are valid + N_XMR_HOLDOVER_STATUS_FLAG_BITS ///< the number of known status flags +}; + + +/** + * @brief XMR holdover status flag masks + * + * Used with ::XMR_HOLDOVER_STATUS::flags. + */ +enum XMR_HOLDOVER_STATUS_FLAG_MASKS +{ + XMR_HLDOVR_MSK_IN_HOLDOVER = ( 1UL << XMR_HLDOVR_BIT_IN_HOLDOVER ), ///< see ::XMR_HLDOVR_BIT_IN_HOLDOVER + XMR_HLDOVR_MSK_TRANSITION_ENBD = ( 1UL << XMR_HLDOVR_BIT_TRANSITION_ENBD ), ///< see ::XMR_HLDOVR_BIT_TRANSITION_ENBD + XMR_HLDOVR_MSK_IN_TRANSITION = ( 1UL << XMR_HLDOVR_BIT_IN_TRANSITION ), ///< see ::XMR_HLDOVR_BIT_IN_TRANSITION + XMR_HLDOVR_MSK_TIME_OFFS_VALID = ( 1UL << XMR_HLDOVR_BIT_TIME_OFFS_VALID ) ///< see ::XMR_HLDOVR_BIT_TIME_OFFS_VALID +}; + + + +/** + * @brief XMR source feature flag bits + * + * Used to define ::XMR_EXT_SRC_FEAT_FLAG_MSKS + */ +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 + N_XMR_EXT_SRC_FEAT_FLAG_BITS +}; + + + +/** + * @brief XMR source feature flag bit masks + * + * Used with ::XMR_EXT_SRC_INFO::feat_flags. + * + * @see ::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 +}; + + + +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 + uint32_t reserved_0; + +} XMR_EXT_SRC_INFO; + +#define _mbg_swab_xmr_ext_src_info( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->supp_flags ); \ + _mbg_swab16( &(_p)->feat_flags ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ +} while ( 0 ) + + + +typedef struct +{ + uint16_t idx; // + XMR_EXT_SRC_INFO info; // + +} XMR_EXT_SRC_INFO_IDX; // + +#define _mbg_swab_xmr_ext_src_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_xmr_ext_src_info( &(_p)->info ); \ +} while ( 0 ) + + + +/** + * @brief XMR statistics for a particular source + * + * This structure is only provided by an XMR source which has + * ::XMR_EXT_SRC_FEAT_FLAG_MSK_STATS set in ::XMR_EXT_SRC_INFO::feat_flags. + * + * @see ::XMR_STATS_IDX + * @see ::XMR_EXT_SRC_INFO::feat_flags + * @see ::XMR_EXT_SRC_FEAT_FLAG_MSK_STATS + */ +typedef struct +{ + 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 + NANO_TIME last_min; ///< minimum value within interval + NANO_TIME reserved_0; ///< currently reserved, unused, always 0 + NANO_TIME step_comp_val; ///< current step compensation value + 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 + +} XMR_STATS; + +#define _mbg_swab_xmr_stats( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->timestamp ); \ + _mbg_swab_nano_time( &(_p)->last_mue ); \ + _mbg_swab_nano_time( &(_p)->last_sigma ); \ + _mbg_swab_nano_time( &(_p)->last_max ); \ + _mbg_swab_nano_time( &(_p)->last_min ); \ + _mbg_swab_nano_time( &(_p)->reserved_0 ); \ + _mbg_swab_nano_time( &(_p)->step_comp_val ); \ + _mbg_swab_nano_time( &(_p)->auto_bias ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of bits used to define ::XMR_STATS_FLAGS_MSKS + * + * @see ::XMR_STATS_FLAGS_MSKS + */ +enum XMR_STATS_FLAGS_BITS +{ + XMR_STATS_FLAG_BIT_STEP_DETECTED, ///< A time step was detected at the input source + XMR_STATS_FLAG_BIT_STEP_COMPENSATED, ///< A time step was compensated at the input source + XMR_STATS_FLAG_BIT_AUTO_BIAS_VALID, ///< The value in ::XMR_STATS::auto_bias is valid + N_XMR_STATS_FLAGS_BITS +}; + + /** - * @brief Holdover interval while switching XMR sources + * @brief Flag bit masks used with ::XMR_STATS::flags * - * @note This parameter can be sent to a device to specify a holdover - * interval during which the sync state shall be kept when switching - * to a different time source. + * @see ::XMR_STATS_FLAGS_BITS */ -typedef uint32_t XMR_HOLDOVER_INTV; ///< [s] */ +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 +}; -/** @} group_xmr_cfg */ + +/** + * @brief String initializers for XMR Stats Flags + * + * @see ::XMR_STATS_FLAGS_MSKS + */ +#define DEFAULT_XMR_STATS_FLAG_NAMES \ +{ \ + "Step Detected", \ + "Step Compensated", \ + "Auto BIAS valid" \ +} /** + * @brief XMR statistics for a particular source, with index + * + * @see ::XMR_STATS + */ +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 + +} XMR_STATS_IDX; + +#define _mbg_swab_xmr_stats_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_xmr_stats( &(_p)->stats ); \ +} while ( 0 ) + + + +#define MAX_XMR_METRICS 20 + +typedef struct +{ + uint32_t timestamp; + uint32_t flags; ///< idx bit set if mtie[idx] is valid + uint8_t mtie_scale; ///< scale factors of MTIE + uint8_t tdev_scale; ///< scale factors of TDEV + uint16_t reserved_0; ///< currently unused + uint32_t reserved_1; ///< currently unused + uint32_t reserved_2; ///< currently unused + uint32_t mtie[MAX_XMR_METRICS]; ///< mtie scaled 32 bit fixed point unsigned + uint32_t tdev[MAX_XMR_METRICS]; ///< tdev scaled 32 bit fixed point unsigned + +} XMR_METRICS; + +#define _mbg_swab_xmr_metrics( _p ) \ +do \ +{ \ + int i; \ + \ + _mbg_swab32( &(_p)->timestamp ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab8( &(_p)->mtie_scale ); \ + _mbg_swab8( &(_p)->tdev_scale ); \ + _mbg_swab16( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + \ + for ( i = 0; i < MAX_XMR_METRICS; i++ ) \ + _mbg_swab32( &(_p)->mtie[i] ); \ + \ + for ( i = 0; i < MAX_XMR_METRICS; i++ ) \ + _mbg_swab32( &(_p)->tdev[i] ); \ + \ +} while ( 0 ) + + + +// conversion factor scaled FPU32 to double +#define _fpu32_to_double_fac( _x ) ( 1.0 / ( 4294967296.0 * ( _x ) ) ) + + + +/** + * @brief XMR timing metrics for a particular source, with index + * + * @see ::XMR_METRICS + */ +typedef struct +{ + uint16_t idx; + XMR_METRICS metrics; + +} XMR_METRICS_IDX; + +#define _mbg_swab_xmr_metrics_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_xmr_metrics( &(_p)->metrics ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of ITU limit masks + * + * Used for detection of ::XMR_METRICS mask violation. + * + * @see ::ITU_LIMIT_MASKS + * @see ::XMR_METRICS + */ +enum ITU_LIMITS +{ + ITU_LIMIT_G811_PRC, + ITU_LIMIT_G823_SSU, + ITU_LIMIT_G823_SEC, + ITU_LIMIT_G8272_PRTC, + ITU_LIMIT_G82721_EPRTC, + N_ITU_LIMITS +} ; + + + +/** + * @brief Enumeration of ITU limit masks + * + * Used for detection of ::XMR_METRICS mask violation. + * + * @see ::ITU_LIMITS + * @see ::XMR_METRICS + */ +enum ITU_LIMIT_MASKS +{ + 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 ), + MSK_ITU_LIMIT_G8272_PRTC = ( 1UL << ITU_LIMIT_G8272_PRTC ), + MSK_ITU_LIMIT_G82721_EPRTC = ( 1UL << ITU_LIMIT_G82721_EPRTC ) +}; + + + +/** + * @brief String initializers for ITU limit masks + * + * Used for detection of ::XMR_METRICS mask violation. + * + * @see ::ITU_LIMITS + * @see ::XMR_METRICS + */ +#define ITU_LIMIT_SHORT_STRS \ +{ \ + "G811 (PRC)", \ + "G823 (SSU)", \ + "G823 (SEC)", \ + "G8272 (PRTC)", \ + "G82721 (ePRTC)" \ +} + + + +/** + * @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; + +} XMR_QL_SETTINGS; + + + +typedef struct +{ + uint32_t supp_ql_masks; ///< see :ITU_LIMIT_MASKS + uint32_t reserved_0; + uint32_t reserved_1; + XMR_QL_SETTINGS settings; + +} XMR_QL_INFO; + + + +typedef struct +{ + uint16_t idx; + XMR_QL_SETTINGS settings; + +} XMR_QL_SETTINGS_IDX; + + + +typedef struct +{ + uint16_t idx; + XMR_QL_INFO info; + +} XMR_QL_INFO_IDX; + + +/** @} defgroup group_multi_ref_ext */ + +/** @} defgroup group_multi_ref_all */ + + +/** * @defgroup group_gpio GPIO port configuration stuff * * @note This is only supported if ::GPS_HAS_GPIO is set - * in the RECEIVER_INFO::features mask. + * in the ::RECEIVER_INFO::features mask. * * @{ */ @@ -4229,17 +7601,53 @@ typedef uint32_t XMR_HOLDOVER_INTV; ///< [s] */ * @brief General GPIO config info to be read from a device * * Used to query from a device how many GPIO ports are supported - * by the device, then index 0..num_io-1 configuration or status - * records can be read from or written to the device. + * by the device, then index 0..::MBG_GPIO_CFG_LIMITS::num_io-1 + * configuration or status records can be read from or written to + * the device. */ typedef struct { - uint32_t num_io; /**< number of supported GPIO ports */ - uint32_t reserved; /**< currently always 0 */ - uint32_t flags; /**< currently always 0 */ + uint32_t num_io; ///< number of supported GPIO ports + uint32_t reserved; ///< reserved, currently always 0 + uint32_t flags; ///< see ::MBG_GPIO_CFG_LIMIT_FLAG_MASKS } MBG_GPIO_CFG_LIMITS; +#define _mbg_swab_mbg_gpio_cfg_limits( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->num_io ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief GPIO limits flag bits used to define ::MBG_GPIO_CFG_LIMIT_FLAG_MASKS + * + * @see ::MBG_GPIO_CFG_LIMIT_FLAG_MASKS + */ +enum MBG_GPIO_CFG_LIMIT_FLAG_BITS +{ + MBG_GPIO_CFG_LIMIT_FLAG_BIT_STATUS_SUPP, ///< indicates that ::MBG_GPIO_STATUS is supported + N_MBG_GPIO_CFG_LIMIT_FLAG_BITS +}; + + + +/** + * @brief GPIO limits flag masks associated with ::MBG_GPIO_CFG_LIMIT_FLAG_BITS + * + * Used with ::MBG_GPIO_CFG_LIMITS::flags + * + * @see ::MBG_GPIO_CFG_LIMIT_FLAG_BITS + */ +enum MBG_GPIO_CFG_LIMIT_FLAG_MASKS +{ + MBG_GPIO_CFG_LIMIT_FLAG_MASK_STATUS_SUPP = ( 1UL << MBG_GPIO_CFG_LIMIT_FLAG_BIT_STATUS_SUPP ), ///< see ::MBG_GPIO_CFG_LIMIT_FLAG_BIT_STATUS_SUPP +}; + /** @@ -4248,48 +7656,89 @@ typedef struct * Usually a specific GPIO port can only be either an input * or an output, and supports only a single signal type. * This is due to hardware limitations, i.e. input or output - * circuitry required for the given signal + * circuitry required for the given signal. + * + * @see ::DEFAULT_GPIO_TYPES_SHORT_STRS */ enum MBG_GPIO_TYPES { - MBG_GPIO_TYPE_FREQ_IN, /**< variable frequency input */ - MBG_GPIO_TYPE_FREQ_OUT, /**< variable frequency output */ - MBG_GPIO_TYPE_FIXED_FREQ_OUT, /**< fixed frequency output */ - MBG_GPIO_TYPE_BITS_IN, /**< framed data stream input */ - MBG_GPIO_TYPE_BITS_OUT, /**< framed data stream output */ - N_MBG_GPIO_TYPES /**< number of known types */ + MBG_GPIO_TYPE_FREQ_IN, ///< Variable frequency input, freq == 0 if input not used + MBG_GPIO_TYPE_FREQ_OUT, ///< Variable frequency output + MBG_GPIO_TYPE_FIXED_FREQ_OUT, ///< Fixed frequency output + MBG_GPIO_TYPE_BITS_IN, ///< Framed data stream input + MBG_GPIO_TYPE_BITS_OUT, ///< Framed data stream output + MBG_GPIO_TYPE_VIDEO_OUT, ///< Video signal output (PAL, NTSC, ...) + 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, ...) + N_MBG_GPIO_TYPES ///< Number of known types }; -#define DEFAULT_GPIO_TYPES_SHORT_STRS \ -{ \ - "Freq. In", \ - "Freq. Out", \ - "Fixed Freq Out", \ - "BITS In", \ - "BITS Out" \ + +#define DEFAULT_GPIO_TYPES_SHORT_STRS \ +{ \ + "Freq. In", \ + "Freq. Out", \ + "Fixed Freq Out", \ + "BITS In", \ + "BITS Out", \ + "Video Out", \ + "Video Sync Out", \ + "Studio Clock Out", \ + "Digital Audio Out" \ } /** - * @brief Enumeration of signal shapes + * @brief Enumeration of known signal shapes * * Used to specify the signal shape of an input or output * frequency signal. + * + * @see ::MBG_GPIO_SIGNAL_SHAPE_MASKS + * @see ::DEFAULT_GPIO_SIGNAL_SHAPE_NAMES */ enum MBG_GPIO_SIGNAL_SHAPES { - MBG_GPIO_SIGNAL_SHAPE_UNSPECIFIED, /**< unknown or unspecified signal shape */ - MBG_GPIO_SIGNAL_SHAPE_SINE, /**< sine wave */ - MBG_GPIO_SIGNAL_SHAPE_SQUARE, /**< square wave */ - N_MBG_GPIO_SIGNAL_SHAPES /**< number of known signal shapes */ + MBG_GPIO_SIGNAL_SHAPE_UNSPECIFIED, ///< unknown or unspecified signal shape + MBG_GPIO_SIGNAL_SHAPE_SINE, ///< sine wave + MBG_GPIO_SIGNAL_SHAPE_SQUARE, ///< square wave + N_MBG_GPIO_SIGNAL_SHAPES ///< number of known signal shapes +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_SIGNAL_SHAPES + * + * Used e.g. with ::MBG_GPIO_FREQ_IN_SUPP::supp_shapes, + * ::MBG_GPIO_FREQ_OUT_SUPP::supp_shapes, + * and ::MBG_GPIO_FIXED_FREQ_OUT_SUPP::supp_shapes. + * + * @see ::MBG_GPIO_SIGNAL_SHAPES + */ +enum MBG_GPIO_SIGNAL_SHAPE_MASKS +{ + MBG_GPIO_SIGNAL_SHAPE_MSK_UNSPECIFIED = ( 1UL << MBG_GPIO_SIGNAL_SHAPE_UNSPECIFIED ), ///< see ::MBG_GPIO_SIGNAL_SHAPE_UNSPECIFIED + MBG_GPIO_SIGNAL_SHAPE_MSK_SINE = ( 1UL << MBG_GPIO_SIGNAL_SHAPE_SINE ), ///< see ::MBG_GPIO_SIGNAL_SHAPE_SINE + MBG_GPIO_SIGNAL_SHAPE_MSK_SQUARE = ( 1UL << MBG_GPIO_SIGNAL_SHAPE_SQUARE ) ///< see ::MBG_GPIO_SIGNAL_SHAPE_SQUARE }; -/** Bit masks of signal shapes, corresponding to enum MBG_GPIO_SIGNAL_SHAPES */ -#define MBG_GPIO_SIGNAL_SHAPE_MSK_UNSPECIFIED ( 1UL << MBG_GPIO_SIGNAL_SHAPE_UNSPECIFIED ) -#define MBG_GPIO_SIGNAL_SHAPE_MSK_SINE ( 1UL << MBG_GPIO_SIGNAL_SHAPE_SINE ) -#define MBG_GPIO_SIGNAL_SHAPE_MSK_SQUARE ( 1UL << MBG_GPIO_SIGNAL_SHAPE_SQUARE ) + + +/** + * @brief String initializers for GPIO signal shapes + * + * @see ::MBG_GPIO_SIGNAL_SHAPES + */ +#define DEFAULT_GPIO_SIGNAL_SHAPE_NAMES \ +{ \ + "(unspec. shape)", \ + "Sine wave", \ + "Rectangle pulse" \ +} @@ -4300,376 +7749,1626 @@ enum MBG_GPIO_SIGNAL_SHAPES */ typedef struct { - uint32_t hz; /**< integral number, Hz */ - uint32_t frac; /**< fractional part, binary */ + uint32_t hz; ///< integral number [Hz] + uint32_t frac; ///< fractional part, binary (0x80000000 --> 0.5, 0xFFFFFFFF --> 0.9999999...) } MBG_GPIO_FREQ; +#define _mbg_swab_mbg_gpio_freq( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->hz ); \ + _mbg_swab32( &(_p)->frac); \ +} while ( 0 ) + /** * @brief Configuration of a GPIO variable frequency input * - * @see MBG_GPIO_TYPE_FREQ_IN + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_FREQ_IN + * @see ::MBG_GPIO_SETTINGS */ typedef struct { - MBG_GPIO_FREQ freq; /**< frequency */ - uint32_t csc_limit; /**< max. cycle slip [1/1000 cycle units] */ - uint32_t shape; /**< signal shape, see ::MBG_GPIO_SIGNAL_SHAPES */ - uint32_t reserved; /**< currently always 0 */ - uint32_t flags; /**< currently always 0 */ + MBG_GPIO_FREQ freq; ///< frequency in range ::MBG_GPIO_FREQ_IN_SUPP::freq_min..::MBG_GPIO_FREQ_IN_SUPP::freq_max, or 0 if input is not used + uint32_t csc_limit; ///< max. cycle slip [1/1000 cycle units], see ::MBG_GPIO_FREQ_IN_SUPP::csc_limit_max + uint32_t shape; ///< selected signal shape, see ::MBG_GPIO_SIGNAL_SHAPES + uint32_t reserved; ///< reserved, currently always 0 + uint32_t flags; ///< reserved, currently always 0 } MBG_GPIO_FREQ_IN_SETTINGS; +#define _mbg_swab_mbg_gpio_freq_in_settings( _p ) \ +do \ +{ \ + _mbg_swab_mbg_gpio_freq( &(_p)->freq ); \ + _mbg_swab32( &(_p)->csc_limit ); \ + _mbg_swab32( &(_p)->shape ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + /** * @brief Supported options for a variable frequency GPIO input * - * @see MBG_GPIO_TYPE_FREQ_IN + * Used as sub-structure of ::MBG_GPIO_LIMITS. + * + * @see ::MBG_GPIO_TYPE_FREQ_IN + * @see ::MBG_GPIO_LIMITS */ typedef struct { - //##++++++++++++++++ - uint32_t freq_min; /**< minimum output frequency [Hz] */ - uint32_t freq_max; /**< maximum output frequency [Hz] */ - uint32_t csc_limit_max; /**< max. milli_phase, unspecified if 0 */ - uint32_t supp_shapes; /**< bit mask of supported signal shapes, see ::MBG_GPIO_SIGNAL_SHAPES */ - uint32_t reserved; /**< currently always 0 */ - uint32_t flags; /**< currently always 0 */ + uint32_t freq_min; ///< minimum output frequency [Hz] + uint32_t freq_max; ///< maximum output frequency [Hz] + uint32_t csc_limit_max; ///< 1/1000 units of the signal period, limited due to 10 ns sampling interval, see ::MBG_GPIO_FREQ_IN_SETTINGS::csc_limit //##++++++++++++++++ + uint32_t supp_shapes; ///< bit mask of supported signal shapes, see ::MBG_GPIO_SIGNAL_SHAPE_MASKS + uint32_t supp_limits; ///< supported ITU limit masks for BITS signal see ::ITU_LIMIT_MASKS + uint32_t flags; ///< reserved, currently always 0 } MBG_GPIO_FREQ_IN_SUPP; +#define _mbg_swab_mbg_gpio_freq_in_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->freq_min ); \ + _mbg_swab32( &(_p)->freq_max ); \ + _mbg_swab32( &(_p)->csc_limit_max ); \ + _mbg_swab32( &(_p)->supp_shapes ); \ + _mbg_swab32( &(_p)->supp_limits ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + /** * @brief Configuration of a GPIO variable frequency output * - * @see MBG_GPIO_TYPE_FREQ_OUT + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_FREQ_OUT + * @see ::MBG_GPIO_SETTINGS */ typedef struct { - MBG_GPIO_FREQ freq; /**< frequency */ - int32_t milli_phase; /**< phase [1/1000 degree units] */ - uint32_t shape; /**< signal shape, see ::MBG_GPIO_SIGNAL_SHAPES */ - uint32_t reserved; /**< currently always 0 */ - uint32_t flags; /**< currently always 0 */ + MBG_GPIO_FREQ freq; ///< frequency, see ::MBG_GPIO_FREQ_OUT_SUPP::freq_min and ::MBG_GPIO_FREQ_OUT_SUPP::freq_max + int32_t milli_phase; ///< phase [1/1000 degree units], see ::MBG_GPIO_FREQ_OUT_SUPP::milli_phase_max + uint32_t shape; ///< selected signal shape, see ::MBG_GPIO_SIGNAL_SHAPES + uint32_t reserved; ///< reserved, currently always 0 + uint32_t flags; ///< reserved, currently always 0 } MBG_GPIO_FREQ_OUT_SETTINGS; +#define _mbg_swab_mbg_gpio_freq_out_settings( _p ) \ +do \ +{ \ + _mbg_swab_mbg_gpio_freq( &(_p)->freq ); \ + _mbg_swab32( &(_p)->milli_phase ); \ + _mbg_swab32( &(_p)->shape ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + /** * @brief Supported options for a variable frequency GPIO output * - * @see MBG_GPIO_TYPE_FREQ_OUT + * Used as sub-structure of ::MBG_GPIO_LIMITS. + * + * @see ::MBG_GPIO_TYPE_FREQ_OUT + * @see ::MBG_GPIO_LIMITS */ typedef struct { - uint32_t freq_min; /**< minimum output frequency [Hz] */ - uint32_t freq_max; /**< maximum output frequency [Hz] */ - uint32_t freq_resolution; /**< frequency resolution [Hz], unspecified if 0 */ - uint32_t milli_phase_max; /**< max. abs. milli_phase */ - uint32_t supp_shapes; /**< bit mask of supported signal shapes, see ::MBG_GPIO_SIGNAL_SHAPES */ - uint32_t reserved; /**< currently always 0 */ - uint32_t flags; /**< currently always 0 */ + uint32_t freq_min; ///< minimum output frequency [Hz], see ::MBG_GPIO_FREQ_OUT_SETTINGS::freq + uint32_t freq_max; ///< maximum output frequency [Hz], see ::MBG_GPIO_FREQ_OUT_SETTINGS::freq + uint32_t freq_resolution; ///< frequency resolution [Hz], unspecified if 0 + uint32_t milli_phase_max; ///< max. abs. milli_phase, see ::MBG_GPIO_FREQ_OUT_SETTINGS::milli_phase + uint32_t supp_shapes; ///< bit mask of supported signal shapes, see ::MBG_GPIO_SIGNAL_SHAPE_MASKS + uint32_t reserved; ///< reserved, currently always 0 + uint32_t flags; ///< reserved, currently always 0 } MBG_GPIO_FREQ_OUT_SUPP; +#define _mbg_swab_mbg_gpio_freq_out_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->freq_min ); \ + _mbg_swab32( &(_p)->freq_max ); \ + _mbg_swab32( &(_p)->freq_resolution ); \ + _mbg_swab32( &(_p)->milli_phase_max ); \ + _mbg_swab32( &(_p)->supp_shapes ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + /** - * @brief Supported fixed frequencies + * @brief Enumeration of predefined fixed frequencies + * + * @see ::MBG_GPIO_FIXED_FREQ_MASKS + * @see ::MBG_GPIO_FIXED_FREQ_STRS */ -enum MBG_GPIO_FIXED_FREQ +enum MBG_GPIO_FIXED_FREQS { - MBG_GPIO_FIXED_FREQ_8kHz, /**< 8kHz */ - MBG_GPIO_FIXED_FREQ_48kHz, /**< 48kHz */ - MBG_GPIO_FIXED_FREQ_1MHz, /**< 1MHz */ - MBG_GPIO_FIXED_FREQ_1544kHz, /**< 1.544MHz */ - MBG_GPIO_FIXED_FREQ_2048kHz, /**< 2.048MHz */ - MBG_GPIO_FIXED_FREQ_5MHz, /**< 5MHz */ - MBG_GPIO_FIXED_FREQ_10MHz, /**< 10MHz */ - MBG_GPIO_FIXED_FREQ_19440kHz, /**< 19.44MHz */ - N_MBG_GPIO_FIXED_FREQ /**< number of known frequencies */ + MBG_GPIO_FIXED_FREQ_8kHz, ///< 8 kHz + MBG_GPIO_FIXED_FREQ_48kHz, ///< 48 kHz + MBG_GPIO_FIXED_FREQ_1MHz, ///< 1 MHz + MBG_GPIO_FIXED_FREQ_1544kHz, ///< 1.544 MHz + MBG_GPIO_FIXED_FREQ_2048kHz, ///< 2.048 MHz + MBG_GPIO_FIXED_FREQ_5MHz, ///< 5 MHz + MBG_GPIO_FIXED_FREQ_10MHz, ///< 10 MHz + MBG_GPIO_FIXED_FREQ_19440kHz, ///< 19.44 MHz + N_MBG_GPIO_FIXED_FREQ ///< number of predefined fixed frequencies }; -/** Bit masks of supported fixed frequencies */ -#define MSK_MBG_GPIO_FIXED_FREQ_8kHz ( 1UL << MBG_GPIO_FIXED_FREQ_8kHz ) -#define MSK_MBG_GPIO_FIXED_FREQ_48kHz ( 1UL << MBG_GPIO_FIXED_FREQ_48kHz ) -#define MSK_MBG_GPIO_FIXED_FREQ_1MHz ( 1UL << MBG_GPIO_FIXED_FREQ_1MHz ) -#define MSK_MBG_GPIO_FIXED_FREQ_1544kHz ( 1UL << MBG_GPIO_FIXED_FREQ_1544kHz ) -#define MSK_MBG_GPIO_FIXED_FREQ_2048kHz ( 1UL << MBG_GPIO_FIXED_FREQ_2048kHz ) -#define MSK_MBG_GPIO_FIXED_FREQ_5MHz ( 1UL << MBG_GPIO_FIXED_FREQ_5MHz ) -#define MSK_MBG_GPIO_FIXED_FREQ_10MHz ( 1UL << MBG_GPIO_FIXED_FREQ_10MHz ) -#define MSK_MBG_GPIO_FIXED_FREQ_19440kHz ( 1UL << MBG_GPIO_FIXED_FREQ_19440kHz ) -/* - * Initializers for GPIO fixed frequency strings. +/** + * @brief Bit masks associated with ::MBG_GPIO_FIXED_FREQS + * + * @see ::MBG_GPIO_FIXED_FREQS + * @see ::MBG_GPIO_FIXED_FREQ_STRS + */ +enum MBG_GPIO_FIXED_FREQ_MASKS +{ + MSK_MBG_GPIO_FIXED_FREQ_8kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_8kHz ), ///< see ::MBG_GPIO_FIXED_FREQ_8kHz + MSK_MBG_GPIO_FIXED_FREQ_48kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_48kHz ), ///< see ::MBG_GPIO_FIXED_FREQ_48kHz + MSK_MBG_GPIO_FIXED_FREQ_1MHz = ( 1UL << MBG_GPIO_FIXED_FREQ_1MHz ), ///< see ::MBG_GPIO_FIXED_FREQ_1MHz + MSK_MBG_GPIO_FIXED_FREQ_1544kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_1544kHz ), ///< see ::MBG_GPIO_FIXED_FREQ_1544kHz + MSK_MBG_GPIO_FIXED_FREQ_2048kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_2048kHz ), ///< see ::MBG_GPIO_FIXED_FREQ_2048kHz + MSK_MBG_GPIO_FIXED_FREQ_5MHz = ( 1UL << MBG_GPIO_FIXED_FREQ_5MHz ), ///< see ::MBG_GPIO_FIXED_FREQ_5MHz + MSK_MBG_GPIO_FIXED_FREQ_10MHz = ( 1UL << MBG_GPIO_FIXED_FREQ_10MHz ), ///< see ::MBG_GPIO_FIXED_FREQ_10MHz + MSK_MBG_GPIO_FIXED_FREQ_19440kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_19440kHz ) ///< see ::MBG_GPIO_FIXED_FREQ_19440kHz +}; + + +/** + * @brief Initializers for an array of GPIO fixed frequency name strings + * + * @see ::MBG_GPIO_FIXED_FREQS + * @see ::MBG_GPIO_FIXED_FREQ_MASKS */ #define MBG_GPIO_FIXED_FREQ_STRS \ { \ - "8kHz", \ - "48kHz", \ - "1MHz", \ - "1544kHz", \ - "2048kHz", \ - "5MHz", \ - "10MHz", \ - "19440kHz" \ + "8 kHz", \ + "48 kHz", \ + "1 MHz", \ + "1544 kHz", \ + "2048 kHz", \ + "5 MHz", \ + "10 MHz", \ + "19440 kHz" \ } + /** * @brief Configuration of a GPIO fixed frequency output * - * @see MBG_GPIO_TYPE_FIXED_FREQ_OUT + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_FIXED_FREQ_OUT + * @see ::MBG_GPIO_SETTINGS */ typedef struct { - uint32_t freq_idx; /**< fixed frequency index, see ::MBG_GPIO_FIXED_FREQ */ - uint32_t shape; /**< signal shape, see ::MBG_GPIO_SIGNAL_SHAPES */ - uint32_t reserved; /**< currently always 0 */ - uint32_t flags; /**< currently always 0 */ + uint32_t freq_idx; ///< fixed frequency index, see ::MBG_GPIO_FIXED_FREQS + uint32_t shape; ///< selected signal shape, see ::MBG_GPIO_SIGNAL_SHAPES + uint32_t reserved; ///< reserved, currently always 0 + uint32_t flags; ///< reserved, currently always 0 } MBG_GPIO_FIXED_FREQ_OUT_SETTINGS; +#define _mbg_swab_mbg_gpio_fixed_freq_out_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->freq_idx ); \ + _mbg_swab32( &(_p)->shape ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + /** * @brief Supported options for a fixed frequency output * - * @see MBG_GPIO_TYPE_FIXED_FREQ_OUT + * Used as sub-structure of ::MBG_GPIO_LIMITS. + * + * @see ::MBG_GPIO_TYPE_FIXED_FREQ_OUT + * @see ::MBG_GPIO_LIMITS */ typedef struct { - uint32_t supp_freq; /**< bit mask of supported fixed frequencies, see ::MBG_GPIO_FIXED_FREQ */ - uint32_t supp_shapes; /**< bit mask of supported signal shapes, see ::MBG_GPIO_SIGNAL_SHAPES */ - uint32_t reserved; /**< currently always 0 */ - uint32_t supp_flags; /**< currently always 0 */ + uint32_t supp_freq; ///< bit mask of supported fixed frequencies, see ::MBG_GPIO_FIXED_FREQ_MASKS + uint32_t supp_shapes; ///< bit mask of supported signal shapes, see ::MBG_GPIO_SIGNAL_SHAPE_MASKS + uint32_t reserved; ///< reserved, currently always 0 + uint32_t supp_flags; ///< reserved, currently always 0 } MBG_GPIO_FIXED_FREQ_OUT_SUPP; +#define _mbg_swab_mbg_gpio_fixed_freq_out_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_freq ); \ + _mbg_swab32( &(_p)->supp_shapes ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + /** - * @brief Definitions for MBG_GPIO_BITS::format + * @brief Enumeration of BITS signal formats + * + * Used with ::MBG_GPIO_BITS_IN_SETTINGS::format and ::MBG_GPIO_BITS_OUT_SETTINGS::format + * + * @see ::MBG_GPIO_BITS_FORMAT_MASKS */ enum MBG_GPIO_BITS_FORMATS { - MBG_GPIO_BITS_E1_FRAMED, /**< 2.048MBit */ - MBG_GPIO_BITS_T1_FRAMED, /**< 1.544MBit */ - MBG_GPIO_BITS_E1_TIMING, /**< 2.048MHz */ - MBG_GPIO_BITS_T1_TIMING, /**< 2.048MHz */ - N_MBG_GPIO_BITS_FORMATS /**< number of formats */ + MBG_GPIO_BITS_E1_FRAMED, ///< 2.048 MBit + MBG_GPIO_BITS_T1_FRAMED, ///< 1.544 MBit + MBG_GPIO_BITS_E1_TIMING, ///< 2.048 MHz + MBG_GPIO_BITS_T1_TIMING, ///< 2.048 MHz + N_MBG_GPIO_BITS_FORMATS ///< number of defined formats +}; + + +/** + * @brief Bit masks associated with ::MBG_GPIO_BITS_FORMATS + * + * Used with ::MBG_GPIO_BITS_IN_SUPP::supp_fmts and ::MBG_GPIO_BITS_OUT_SUPP::supp_fmts. + * + * @see ::MBG_GPIO_BITS_FORMATS + */ +enum MBG_GPIO_BITS_FORMAT_MASKS +{ + MSK_MBG_GPIO_BITS_E1_FRAMED = ( 1UL << MBG_GPIO_BITS_E1_FRAMED ), ///< see ::MBG_GPIO_BITS_E1_FRAMED + MSK_MBG_GPIO_BITS_T1_FRAMED = ( 1UL << MBG_GPIO_BITS_T1_FRAMED ), ///< see ::MBG_GPIO_BITS_T1_FRAMED + MSK_MBG_GPIO_BITS_E1_TIMING = ( 1UL << MBG_GPIO_BITS_E1_TIMING ), ///< see ::MBG_GPIO_BITS_E1_TIMING + MSK_MBG_GPIO_BITS_T1_TIMING = ( 1UL << MBG_GPIO_BITS_T1_TIMING ) ///< see ::MBG_GPIO_BITS_T1_TIMING +}; + + +/** + * @brief Initializers for an array of GPIO bit format strings + * + * @see ::MBG_GPIO_BITS_FORMATS + * @see ::MBG_GPIO_BITS_FORMAT_MASKS + */ +#define MBG_GPIO_BITS_FORMAT_STRS \ +{ \ + "E1 Framed", \ + "T1 Framed", \ + "E1 Timing", \ + "T1 Timing" \ +} + + + +/** + * @brief Minimum and maximum known SSM values + * + * Values according to ITU G.704-1998 + * + * Used with ::MBG_GPIO_BITS_IN_SETTINGS::quality::e1.ssm + * and ::MBG_GPIO_BITS_OUT_SETTINGS::ssm. + */ +enum GPIO_SSM_VALS +{ + GPIO_SSM_UNKNOWN, ///< Quality unknown, existing synchronization network + GPIO_SSM_RSVD_1, ///< (reserved) + GPIO_SSM_G_811, ///< Rec. G.811 + GPIO_SSM_RSVD_3, ///< (reserved) + GPIO_SSM_SSU_A, ///< SSU-A + GPIO_SSM_RSVD_5, ///< (reserved) + GPIO_SSM_RSVD_6, ///< (reserved) + GPIO_SSM_RSVD_7, ///< (reserved) + GPIO_SSM_SSU_B, ///< SSU-B + GPIO_SSM_RSVD_9, ///< (reserved) + GPIO_SSM_RSVD_10, ///< (reserved) + GPIO_SSM_RSVD_SETS, ///< Synchronous Equipment Timing Source (SETS) + GPIO_SSM_RSVD_12, ///< (reserved) + GPIO_SSM_RSVD_13, ///< (reserved) + GPIO_SSM_RSVD_14, ///< (reserved) + GPIO_SSM_DONT_USE, ///< don't use + N_GPIO_SSM_VALS }; -#define MSK_MBG_GPIO_BITS_E1_FRAMED ( 1UL << MBG_GPIO_BITS_E1_FRAMED ) -#define MSK_MBG_GPIO_BITS_T1_FRAMED ( 1UL << MBG_GPIO_BITS_T1_FRAMED ) -#define MSK_MBG_GPIO_BITS_E1_TIMING ( 1UL << MBG_GPIO_BITS_E1_TIMING ) -#define MSK_MBG_GPIO_BITS_T1_TIMING ( 1UL << MBG_GPIO_BITS_T1_TIMING ) + + +/** + * @brief Minimum and maximum SA BITS groups + * + * Used with ::MBG_GPIO_BITS_IN_SETTINGS::quality::e1::sa_bits + * and ::MBG_GPIO_BITS_OUT_SETTINGS::sa_bits. + */ +enum GPIO_SA_BITS_GROUPS +{ + MIN_SA_BITS_GROUP = 4, + MAX_SA_BITS_GROUP = 8 +}; /** * @brief Configuration of a GPIO as BITS input module * - * @see MBG_GPIO_TYPE_BITS_IN + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_BITS_IN + * @see ::MBG_GPIO_SETTINGS */ typedef struct { - uint32_t format; /**< signal type, see ::MBG_GPIO_BITS_FORMATS */ - uint32_t reserved; - uint32_t csc_limit; /**< max. cycle slip [1/1000 cycle units] */ + uint32_t format; ///< signal format, see ::MBG_GPIO_BITS_FORMATS + uint32_t reserved; ///< reserved, currently always 0 + uint32_t csc_limit; ///< max. cycle slip [1/1000 cycle units] - union + union quality { - struct + struct e1 { - uint8_t ssm; /**< minimum E1 SSM ( 0...15 ) for acceptance */ - uint8_t sa_bits; /**< Sa Bits group ( 4...8 ) carrying SSM */ - uint16_t reserve; - } e1; /**< used with E1 formats */ + uint8_t ssm; ///< minimum E1 SSM for acceptance, 0..::N_GPIO_SSM_VALS-1 + uint8_t sa_bits; ///< sa bits group carrying SSM, ::MIN_SA_BITS_GROUP..::MAX_SA_BITS_GROUP + uint16_t reserved; ///< reserved, currently always 0 + } e1; ///< used with E1 formats - struct + struct t1 { uint8_t min_boc; - uint8_t reserve_0; - uint16_t reserve_1; - } t1; /**< used with T1 formats */ + uint8_t reserved_0; ///< reserved, currently always 0 + uint16_t reserved_1; ///< reserved, currently always 0 + } t1; ///< used with T1 formats - uint32_t u32; /**< dummy to force at least 32 bit alignment */ + uint32_t u32; ///< dummy to force at least 32 bit alignment } quality; - uint32_t err_msk; /**< controls which types of error can be ignored, see enum MBG_GPIO_BITS_ERR */ - uint32_t flags; /**< currently always 0 */ + uint32_t err_msk; ///< controls which types of error can be ignored, see ::MBG_GPIO_BITS_ERR_MASKS + uint32_t flags; ///< reserved, currently always 0 } MBG_GPIO_BITS_IN_SETTINGS; +#define _mbg_swab_mbg_gpio_bits_in_settings( _p, _recv ) \ +do \ +{ \ + uint32_t f = (_p)->format; \ + if ( (_recv) ) \ + _mbg_swab32( &f); \ + _mbg_swab32( &(_p)->format ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->csc_limit ); \ + switch( f ) \ + { \ + case MBG_GPIO_BITS_E1_FRAMED : \ + case MBG_GPIO_BITS_E1_TIMING : \ + _mbg_swab8( &(_p)->quality.e1.ssm ); \ + _mbg_swab8( &(_p)->quality.e1.sa_bits ); \ + _mbg_swab16( &(_p)->quality.e1.reserved ); \ + break; \ + \ + case MBG_GPIO_BITS_T1_FRAMED : \ + case MBG_GPIO_BITS_T1_TIMING : \ + _mbg_swab8( &(_p)->quality.t1.min_boc ); \ + _mbg_swab8( &(_p)->quality.t1.reserved_0 ); \ + _mbg_swab16( &(_p)->quality.t1.reserved_1 ); \ + break; \ + \ + default: \ + break; \ + } \ + _mbg_swab32( &(_p)->err_msk ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of BITS input error conditions + */ +enum MBG_GPIO_BITS_ERRS +{ + MBG_GPIO_BITS_ERR_LOS, ///< loss of signal + MBG_GPIO_BITS_ERR_LOF, ///< loss of frame + N_MBG_GPIO_BITS_ERRS ///< number of known errors +}; + /** - * @brief Definitions for MBG_GPIO_BITS_IN_SETTINGS::err_msk + * @brief Bit masks associated with BITS input error conditions + * + * Used with ::MBG_GPIO_BITS_IN_SETTINGS::err_msk + * + * @see ::MBG_GPIO_BITS_ERRS */ -enum MBG_GPIO_BITS_ERR +enum MBG_GPIO_BITS_ERR_MASKS { - MBG_GPIO_BITS_ERR_LOS, /**< loss of signal error */ - MBG_GPIO_BITS_ERR_LOF, /**< loss of frame */ - N_MBG_GPIO_BITS_ERR /**< number of formats */ + 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 }; -#define MSK_MBG_GPIO_BITS_ERR_LOS ( 1UL << MBG_GPIO_BITS_ERR_LOS ) -#define MSK_MBG_GPIO_BITS_ERR_LOF ( 1UL << MBG_GPIO_BITS_ERR_LOF ) - /** * @brief Supported options of a BITS GPIO input * - * @see MBG_GPIO_TYPE_BITS_IN + * Used as sub-structure of ::MBG_GPIO_LIMITS. + * + * @see ::MBG_GPIO_TYPE_BITS_IN + * @see ::MBG_GPIO_LIMITS */ typedef struct { - uint32_t supp_fmts; ///< bit mask of supported formats, see ::MBG_GPIO_BITS_FORMATS - uint32_t reserved; ///< reserved, currently always 0 + uint32_t supp_fmts; ///< bit mask of supported formats, see ::MBG_GPIO_BITS_FORMAT_MASKS + uint32_t reserved; ///< reserved, currently always 0 } MBG_GPIO_BITS_IN_SUPP; +#define _mbg_swab_mbg_gpio_bits_in_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_fmts ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + /** * @brief Configuration of a GPIO as BITS output module * - * @see MBG_GPIO_TYPE_BITS_OUT + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_BITS_OUT + * @see ::MBG_GPIO_SETTINGS */ typedef struct { - uint32_t format; /**< signal type, enum MBG_GPIO_BITS_FORMATS */ - uint32_t flags; /**< flags for encoder control etc. */ - uint8_t sa_bits; /**< number of SA Bit group for E1 SSM ( 4...8 ) */ - uint8_t ssm; /**< ssm for E1 mode 0..0x0F */ - uint8_t boc; /**< boc for T1 mode 0..0x1F */ - uint8_t reserved_0; - uint32_t reserved_1; - uint32_t reserved_2; - uint32_t reserved_3; + uint32_t format; ///< signal format, see ::MBG_GPIO_BITS_FORMATS + uint32_t flags; ///< flags for encoder control etc., see ::MBG_GPIO_BITS_OUT_FLAG_MASKS + uint8_t sa_bits; ///< number of SA bit group for E1 SSM, ::MIN_SA_BITS_GROUP..::MAX_SA_BITS_GROUP + uint8_t ssm; ///< ssm for E1 mode, 0..::N_GPIO_SSM_VALS-1 + uint8_t boc; ///< boc for T1 mode, 0..0x1F //##++++++++++++++ + uint8_t reserved_0; ///< reserved, currently always 0 + uint32_t reserved_1; ///< reserved, currently always 0 + uint32_t reserved_2; ///< reserved, currently always 0 + uint32_t reserved_3; ///< reserved, currently always 0 } MBG_GPIO_BITS_OUT_SETTINGS; +#define _mbg_swab_mbg_gpio_bits_out_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->format ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab8( &(_p)->sa_bits ); \ + _mbg_swab8( &(_p)->ssm ); \ + _mbg_swab8( &(_p)->boc ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of flags used with BITS type GPIO outputs + * + * @see ::MBG_GPIO_BITS_OUT_FLAG_MASKS + * @see ::MBG_GPIO_BITS_OUT_FLAG_STRS + */ +enum MBG_GPIO_BITS_OUT_FLAGS +{ + MBG_GPIO_BITS_OUT_FLAG_HDB3, ///< enable HDB3 encoding (E1 mode only) + MBG_GPIO_BITS_OUT_FLAG_B8ZS, ///< enable B8ZS encoding (T1 mode only) + N_MBG_GPIO_BITS_OUT_FLAGS ///< number of known flags +}; + /** - * @brief Definitions for MBG_GPIO_BITS_OUT_SETTINGS::flags + * @brief Bit masks associated with ::MBG_GPIO_BITS_OUT_FLAGS + * + * Used with ::MBG_GPIO_BITS_OUT_SETTINGS::flags + * + * @see ::MBG_GPIO_BITS_OUT_FLAGS + * @see ::MBG_GPIO_BITS_OUT_FLAG_STRS */ -enum MBG_GPIO_BITS_OUT_FLAG +enum MBG_GPIO_BITS_OUT_FLAG_MASKS { - MBG_GPIO_BITS_OUT_FLAG_HDB3, /**< enable HDB3 encoding ( E1 mode only ) */ - MBG_GPIO_BITS_OUT_FLAG_B8ZS, /**< enable B8ZS encoding ( T1 mode only ) */ - N_MBG_GPIO_BITS_OUT_FLAG /**< number of flags */ + 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 }; -#define MSK_MBG_GPIO_BITS_OUT_FLAG_HDB3 ( 1UL << MBG_GPIO_BITS_OUT_FLAG_HDB3 ) -#define MSK_MBG_GPIO_BITS_OUT_FLAG_B8ZS ( 1UL << MBG_GPIO_BITS_OUT_FLAG_B8ZS ) + +/** + * @brief String initializers for an array of GPIO BITS out flags + * + * @see ::MBG_GPIO_BITS_OUT_FLAGS + * @see ::MBG_GPIO_BITS_OUT_FLAG_MASKS + */ +#define MBG_GPIO_BITS_OUT_FLAG_STRS \ +{ \ + "HDB3", \ + "B8ZS" \ +} /** - * @brief Supported options of a BITS GPIO output + * @brief Supported options of a BITS type GPIO output + * + * Used as sub-structure of ::MBG_GPIO_LIMITS. * - * @see MBG_GPIO_TYPE_BITS_OUT + * @see ::MBG_GPIO_TYPE_BITS_OUT + * @see ::MBG_GPIO_LIMITS */ typedef struct { - uint32_t supp_fmts; /**< bit mask of supported formats, see ::MBG_GPIO_BITS_FORMATS */ - uint32_t reserved; /**< currently always 0 */ + uint32_t supp_fmts; ///< bit mask of supported formats, see ::MBG_GPIO_BITS_FORMAT_MASKS + uint32_t supp_flags; ///< bit mask of supported flags, see ::MBG_GPIO_BITS_OUT_FLAG_MASKS + } MBG_GPIO_BITS_OUT_SUPP; +#define _mbg_swab_mbg_gpio_bits_out_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_fmts ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of Video signal formats + * + * Used with ::MBG_GPIO_VIDEO_OUT_SETTINGS::format + * + * @see ::MBG_GPIO_VIDEO_FORMAT_MASKS + */ +enum MBG_GPIO_VIDEO_FORMATS +{ + MBG_GPIO_VIDEO_FORMAT_OFF, ///< OFF + MBG_GPIO_VIDEO_SD_FORMAT_NTSC, ///< NTSC 525i + MBG_GPIO_VIDEO_SD_FORMAT_PAL, ///< PAL standard (Germany) 625i + MBG_GPIO_VIDEO_HD_FORMAT_720_P_50Hz, ///< SMPTE296M-3 720p at 50 Hz + MBG_GPIO_VIDEO_HD_FORMAT_1080_I_50Hz, ///< SMPTE274M-6 1080i at 50 Hz + MBG_GPIO_VIDEO_HD_FORMAT_720_P_59_94Hz, ///< SMPTE296M-1 720p at 59.94 Hz + MBG_GPIO_VIDEO_HD_FORMAT_1080_I_59_94Hz, ///< SMPTE274M-7 1080i at 59.94 Hz + MBG_GPIO_VIDEO_SD_FORMAT_PAL_M, ///< PAL M (Brazil) 525i + N_MBG_GPIO_VIDEO_FORMATS ///< number of defined video formats +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_VIDEO_FORMATS + * + * Used with ::MBG_GPIO_VIDEO_OUT_SUPP::supp_formats + * + * @see ::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 +}; + + +/** + * @brief A combination of bit masks for SD video formats + * @see ::MBG_GPIO_VIDEO_FORMAT_MASKS + */ +#define MBG_GPIO_VIDEO_SD_FORMATS ( MSK_MBG_GPIO_VIDEO_FORMAT_OFF | MSK_MBG_GPIO_VIDEO_SD_FORMAT_NTSC | MSK_MBG_GPIO_VIDEO_SD_FORMAT_PAL | \ + MSK_MBG_GPIO_VIDEO_SD_FORMAT_PAL_M ) + +/** + * @brief A combination of bit masks for HD video formats + * @see ::MBG_GPIO_VIDEO_FORMAT_MASKS + */ +#define MBG_GPIO_VIDEO_HD_FORMATS ( MSK_MBG_GPIO_VIDEO_FORMAT_OFF | MSK_MBG_GPIO_VIDEO_HD_FORMAT_720_P_50Hz | MSK_MBG_GPIO_VIDEO_HD_FORMAT_1080_I_50Hz | \ + MSK_MBG_GPIO_VIDEO_HD_FORMAT_720_P_59_94Hz | MSK_MBG_GPIO_VIDEO_HD_FORMAT_1080_I_59_94Hz ) + + + +/** + * @brief Initializers for an array of video output name strings + * + * @see ::MBG_GPIO_VIDEO_FORMATS + * @see ::MBG_GPIO_VIDEO_FORMAT_MASKS + */ +#define MBG_GPIO_VIDEO_OUT_STRS \ +{ \ + "OFF", \ + "NTSC (525i)", \ + "PAL (625i)", \ + "720p 50 Hz", \ + "1080i 50 Hz", \ + "720p 59.94 Hz", \ + "1080i 59.94 Hz", \ + "PAL M (525i)" \ +} + + + +/** + * @brief Enumeration of flags used with video type GPIO outputs + */ +enum MBG_GPIO_VIDEO_OUT_FLAGS +{ + MBG_GPIO_VIDEO_OUT_HAS_NO_FREE_CONF, ///< if set, Out1: HD, Out2: SD + MBG_GPIO_VIDEO_OUT_HAS_TC_SD, ///< supports Time Code for SD Black Bursts + N_MBG_GPIO_VIDEO_OUT_FLAGS ///< number of known flags +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_VIDEO_OUT_FLAGS + * + * Used with ::MBG_GPIO_VIDEO_OUT_SETTINGS::flags + * + * @see ::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 +}; + + + +/** + * @brief Enumeration of epochs used with video type GPIO outputs + * + * Used with ::MBG_GPIO_VIDEO_OUT_SETTINGS::epoch, and used to + * define ::MBG_GPIO_VIDEO_EPOCH_MASKS + * + * @see ::MBG_GPIO_VIDEO_EPOCH_MASKS + * @see ::MBG_GPIO_VIDEO_EPOCH_STRS + */ +enum MBG_GPIO_VIDEO_EPOCHS +{ + SMPTE_TAI_EPOCH_1970, ///< 1970-01-01 00:00:00 + SMPTE_TAI_EPOCH_1958, ///< 1958-01-01 00:00:00 + SMPTE_UTC_EPOCH_1972, ///< 1972-01-01 00:00:00 + SMPTE_GPS_EPOCH_1980, ///< 1980-01-06 00:00:00 + N_MBG_GPIO_VIDEO_EPOCHS ///< number of known epochs +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_VIDEO_EPOCHS + * + * Used with :: MBG_GPIO_VIDEO_OUT_SUPP::supp_epochs + * + * @see ::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 +}; + + + +/** + * @brief Initializers for an array of video epoch strings + * + * @see ::MBG_GPIO_VIDEO_EPOCHS + */ +#define MBG_GPIO_VIDEO_EPOCH_STRS \ +{ \ + "TAI D1970-01-01 T00:00:00", \ + "TAI D1958-01-01 T00:00:00", \ + "UTC D1972-01-01 T00:00:00", \ + "GPS D1980-01-06 T00:00:00" \ +} + + + +/** + * @brief Enumeration of time code modes used with video type GPIO outputs + * + * Used with ::MBG_GPIO_VIDEO_OUT_SETTINGS::tc_mode + * + */ +enum MBG_GPIO_VIDEO_TC_MODES +{ + MBG_GPIO_VIDEO_TC_MODE_NONE, ///< None + MBG_GPIO_VIDEO_TC_MODE_VITC, ///< Vertical Interval Time Code + N_MBG_GPIO_VIDEO_TC_MODES +}; + + +/** + * @brief Bit masks associated with ::MBG_GPIO_VIDEO_TC_MODES + * + * Used with ::MBG_GPIO_VIDEO_OUT_SETTINGS::tc_mode + * + */ +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 +}; + + +/** + * @brief Initializers for an array of video time code modes + * + * @see ::MBG_GPIO_VIDEO_TC_MODES + */ +#define MBG_GPIO_VIDEO_TC_MODE_STRS \ +{ \ + "None", \ + "VITC" \ +} + + + +/** + * @brief Configuration of a GPIO as video output module + * + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_VIDEO_OUT + * @see ::MBG_GPIO_SETTINGS + */ +typedef struct +{ + uint32_t format; ///< video format, see ::MBG_GPIO_VIDEO_FORMATS + uint32_t flags; ///< flags, see ::MBG_GPIO_VIDEO_OUT_FLAG_MASKS + int32_t phase_offset; ///< Phase offset in [ns] + uint8_t epoch; ///< epoch, see ::MBG_GPIO_VIDEO_EPOCHS + + uint8_t tc_mode; ///< time code mode, see ::MBG_GPIO_VIDEO_TC_MODES + uint8_t tc_line0; ///< first time code line location, valid lines: 6-22 + uint8_t tc_line1; ///< second time code line location, valid lines: 6-22 + + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + +} MBG_GPIO_VIDEO_OUT_SETTINGS; + +#define _mbg_swab_mbg_gpio_video_out_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->format ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->phase_offset ); \ + _mbg_swab8( &(_p)->epoch ); \ + _mbg_swab8( &(_p)->tc_mode ); \ + _mbg_swab8( &(_p)->tc_line0 ); \ + _mbg_swab8( &(_p)->tc_line1 ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ +} while ( 0 ) + + + +/** + * @brief Supported options of a video type GPIO output + * + * Used as sub-structure of ::MBG_GPIO_LIMITS. + * + * @see ::MBG_GPIO_TYPE_VIDEO_OUT + * @see ::MBG_GPIO_LIMITS + */ +typedef struct +{ + uint32_t supp_formats; ///< supported video formats, see ::MBG_GPIO_VIDEO_FORMAT_MASKS + uint32_t supp_flags; ///< supported flags, see ::MBG_GPIO_VIDEO_OUT_FLAG_MASKS + uint32_t supp_epochs; ///< supported epochs, see ::MBG_GPIO_VIDEO_EPOCH_MASKS + + uint8_t supp_tc_modes; ///< supported tc_modes, see ::MBG_GPIO_VIDEO_TC_MODE_MASKS + + uint8_t reserved0; ///< reserved, currently always 0 + uint8_t reserved2; ///< reserved, currently always 0 + uint16_t reserved3; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + +} MBG_GPIO_VIDEO_OUT_SUPP; + +#define _mbg_swab_mbg_gpio_video_out_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_formats ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->supp_epochs ); \ + _mbg_swab8( &(_p)->supp_tc_modes ); \ + _mbg_swab8( &(_p)->reserved0 ); \ + _mbg_swab16( &(_p)->reserved2 ); \ + _mbg_swab16( &(_p)->reserved3 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of types used with video sync GPIO outputs + * Depends on configured video output + */ +enum MBG_GPIO_VIDEO_SYNC_TYPES +{ + MBG_GPIO_VIDEO_SYNC_TYPE_OFF, ///< Output Off + MBG_GPIO_VIDEO_SYNC_TYPE_SD_HSYNC, ///< SD horizontal sync + MBG_GPIO_VIDEO_SYNC_TYPE_SD_VSYNC, ///< SD vertical sync + MBG_GPIO_VIDEO_SYNC_TYPE_SD_FRAME, ///< SD frame/field sync + MBG_GPIO_VIDEO_SYNC_TYPE_SD_BLANK, ///< SD blanking interval + MBG_GPIO_VIDEO_SYNC_TYPE_HD_HSYNC, ///< HD horizontal sync + MBG_GPIO_VIDEO_SYNC_TYPE_HD_VSYNC, ///< HD vertical sync + MBG_GPIO_VIDEO_SYNC_TYPE_HD_FRAME, ///< HD frame/field sync + MBG_GPIO_VIDEO_SYNC_TYPE_HD_BLANK, ///< HD blanking interval + N_MBG_GPIO_VIDEO_SYNC_TYPES ///< number of known types +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_VIDEO_SYNC_TYPES + * + * Used with ::MBG_GPIO_VIDEO_SYNC_OUT_SUPP::supp_types + * + * @see ::MBG_GPIO_VIDEO_SYNC_TYPES + */ +enum MBG_GPIO_VIDEO_SYNC_TYPE_MASKS +{ + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_OFF = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_OFF ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_HSYNC = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_SD_HSYNC ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_VSYNC = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_SD_VSYNC ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_FRAME = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_SD_FRAME ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_BLANK = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_SD_BLANK ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_HSYNC = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_HD_HSYNC ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_VSYNC = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_HD_VSYNC ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_FRAME = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_HD_FRAME ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_BLANK = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_HD_BLANK ) +}; + + + +/** + * @brief Initializers for an array of video sync output name strings + * + * @see ::MBG_GPIO_VIDEO_SYNC_TYPES + * @see ::MBG_GPIO_VIDEO_SYNC_TYPE_MASKS + */ +#define MBG_GPIO_VIDEO_SYNC_OUT_STRS \ +{ \ + "OFF", \ + "SD H-Sync", \ + "SD V-Sync", \ + "SD Frame", \ + "SD Blank", \ + "HD H-Sync", \ + "HD V-Sync", \ + "HD Frame", \ + "HD Blank" \ +} + + + +/** + * @brief A combination of bit masks for SD video sync types + * @see ::MBG_GPIO_VIDEO_SYNC_TYPE_MASKS + */ +#define MBG_GPIO_VIDEO_SYNC_SD_TYPES ( MSK_MBG_GPIO_VIDEO_SYNC_TYPE_OFF | MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_HSYNC | MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_VSYNC | \ + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_FRAME | MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_BLANK ) + +/** + * @brief A combination of bit masks for HD video sync types + * @see ::MBG_GPIO_VIDEO_SYNC_TYPE_MASKS + */ +#define MBG_GPIO_VIDEO_SYNC_HD_TYPES ( MSK_MBG_GPIO_VIDEO_SYNC_TYPE_OFF | MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_HSYNC | MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_VSYNC | \ + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_FRAME | MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_BLANK ) + + + +/** + * @brief Configuration of a GPIO as sync output module + * + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_VIDEO_SYNC_OUT + * @see ::MBG_GPIO_SETTINGS + */ +typedef struct +{ + uint32_t type; ///< sync type, see :: MBG_GPIO_SYNC_TYPES + uint32_t flags; ///< flags, currently always 0 + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + uint32_t reserved2; ///< reserved, currently always 0 + uint32_t reserved3; ///< reserved, currently always 0 + +} MBG_GPIO_VIDEO_SYNC_OUT_SETTINGS; + +#define _mbg_swab_mbg_gpio_video_sync_out_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->type ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ + _mbg_swab32( &(_p)->reserved2 ); \ + _mbg_swab32( &(_p)->reserved3 ); \ +} while ( 0 ) + + + +/** + * @brief Supported options of a sync type GPIO output + * + * Used as sub-structure of ::MBG_GPIO_LIMITS. + * + * @see ::MBG_GPIO_TYPE_VIDEO_SYNC_OUT + * @see ::MBG_GPIO_LIMITS + */ +typedef struct +{ + uint32_t supp_types; ///< supported types, see ::MBG_GPIO_VIDEO_SYNC_TYPE_MASKS + uint32_t supp_flags; ///< supported flags, currently always 0 + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + +} MBG_GPIO_VIDEO_SYNC_OUT_SUPP; + +#define _mbg_swab_mbg_gpio_video_sync_out_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_types ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of studio clock base frequencies + * + * Used with ::MBG_GPIO_STUDIO_CLOCK_OUT_SETTINGS::base_freq + * + * @see ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_MASKS + */ +enum MBG_GPIO_STUDIO_CLOCK_BASE_FREQS +{ + MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_32KHZ, ///< 32 kHz base frequency + MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_44_1KHZ, ///< 44.1 kHz base frequency + MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_48KHZ, ///< 48 kHz base frequency + N_MBG_GPIO_STUDIO_CLOCK_BASE_FREQS ///< number of defined base frequencies +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQS + * + * Used with ::MBG_GPIO_STUDIO_CLOCK_OUT_SUPP::supp_base_freqs + * + * @see ::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 +}; + + /** - * @brief A generic structure used to configure a GPIO port + * @brief Initializers for an array of base frequencies of studio clock output name strings + * + * @see ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQS + * @see ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_MASKS + */ +#define MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_STRS \ +{ \ + "32 kHz", \ + "44.1 kHz", \ + "48 kHz" \ +} + + + +/** + * @brief Enumeration of studio clock scales + * + * Used with ::MBG_GPIO_STUDIO_CLOCK_OUT_SETTINGS::scale + * Multiply scale with base frequency + * + * @see ::MBG_GPIO_STUDIO_CLOCK_SCALE_MASKS + */ +enum MBG_GPIO_STUDIO_CLOCK_SCALES +{ + MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_32, + MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_16, + MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_8, + MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_4, + MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_2, + MBG_GPIO_STUDIO_CLOCK_SCALE_1, + MBG_GPIO_STUDIO_CLOCK_SCALE_2, + MBG_GPIO_STUDIO_CLOCK_SCALE_4, + MBG_GPIO_STUDIO_CLOCK_SCALE_8, + MBG_GPIO_STUDIO_CLOCK_SCALE_16, + MBG_GPIO_STUDIO_CLOCK_SCALE_32, + MBG_GPIO_STUDIO_CLOCK_SCALE_64, + MBG_GPIO_STUDIO_CLOCK_SCALE_128, + MBG_GPIO_STUDIO_CLOCK_SCALE_256, + MBG_GPIO_STUDIO_CLOCK_SCALE_512, + N_MBG_GPIO_STUDIO_CLOCK_SCALES ///< number of defined scales +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_STUDIO_CLOCK_SCALES + * + * Used with ::MBG_GPIO_STUDIO_CLOCK_OUT_SUPP::supp_scales[N_MBG_GPIO_STUDIO_CLOCK_BASE_FREQS] + * + * @see ::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 +}; + + + +/** + * @brief Initializers for an array of scales of studio clock output name strings + * + * @see ::MBG_GPIO_STUDIO_CLOCK_SCALES + * @see ::MBG_GPIO_STUDIO_CLOCK_SCALE_MASKS + */ +#define MBG_GPIO_STUDIO_CLOCK_SCALE_STRS \ +{ \ + "1/32", \ + "1/16", \ + "1/8", \ + "1/4", \ + "1/2", \ + "1", \ + "2", \ + "4", \ + "8", \ + "16", \ + "32", \ + "64", \ + "128", \ + "256", \ + "512" \ +} + + + +/** + * @brief Enumeration of flags used with studio clock type GPIO outputs + */ +enum MBG_GPIO_STUDIO_CLOCK_FLAGS +{ + MBG_GPIO_STUDIO_CLOCK_OUTPUT_ENABLED, ///< if set, enables output + N_MBG_GPIO_STUDIO_CLOCK_FLAGS ///< number of known flags +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_STUDIO_CLOCK_FLAGS + * + * Used with ::MBG_GPIO_STUDIO_CLOCK_OUT_SETTINGS::flags + * + * @see ::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 +}; + + + +/** + * @brief Configuration of a GPIO as studio clock output module + * + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_STUDIO_CLOCK_OUT + * @see ::MBG_GPIO_SETTINGS + */ +typedef struct +{ + uint32_t base_freq; ///< base frequency, see ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQS + uint32_t scale; ///< scale, see ::MBG_GPIO_STUDIO_CLOCK_SCALES + uint32_t flags; ///< flags, see ::MBG_GPIO_STUDIO_CLOCK_FLAGS + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + +} MBG_GPIO_STUDIO_CLOCK_OUT_SETTINGS; + +#define _mbg_swab_mbg_gpio_studio_clock_out_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->base_freq ); \ + _mbg_swab32( &(_p)->scale ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ +} while ( 0 ) + + + +#define MAX_SUPP_BASE_FREQUENCIES 8 ///< max. supported base frequencies for studio clock outputs + +/** + * @brief Configuration of a GPIO as studio clock output module + * + * Used as sub-structure of ::MBG_GPIO_LIMITS. + * + * @see ::MBG_GPIO_TYPE_STUDIO_CLOCK_OUT + * @see ::MBG_GPIO_LIMITS */ typedef struct { - uint32_t type; /**< GPIO type, see ::MBG_GPIO_TYPES */ - uint32_t reserved; /**< currently always 0 */ - uint32_t flags; /**< currently always 0 */ + uint8_t supp_base_freqs; ///< supported base frequencies, see ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_MASKS + uint8_t reserved0; ///< reserved, currently always 0 + uint16_t reserved1; ///< reserved, currently always 0 + uint16_t supp_scales[MAX_SUPP_BASE_FREQUENCIES]; ///< supported scales for each base frequency, see ::MBG_GPIO_STUDIO_CLOCK_SCALE_MASKS + uint32_t supp_flags; ///< supported flags, see::MBG_GPIO_STUDIO_CLOCK_FLAG_MASKS + uint32_t reserved2; ///< reserved, currently always 0 + +} MBG_GPIO_STUDIO_CLOCK_OUT_SUPP; + +#define _mbg_swab_mbg_gpio_studio_clock_out_supp( _p ) \ +do \ +{ \ + uint8_t idx; \ + _mbg_swab8( &(_p)->supp_base_freqs ); \ + _mbg_swab8( &(_p)->reserved0 ); \ + _mbg_swab16( &(_p)->reserved1 ); \ + for( idx = 0; idx < MAX_SUPP_BASE_FREQUENCIES; idx++ ) \ + _mbg_swab16( &(_p)->supp_scales[idx] ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->reserved2 ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of types used with GPIO type digital audio outputs + * + * Used with ::MBG_GPIO_DIGITAL_AUDIO_OUT_SETTINGS::type, and to + * define ::MBG_GPIO_DIGITAL_AUDIO_TYPE_MASKS + * + * @see ::MBG_GPIO_DIGITAL_AUDIO_TYPE_MASKS + * @see ::MBG_GPIO_DIGITAL_AUDIO_TYPE_STRS + */ +enum MBG_GPIO_DIGITAL_AUDIO_TYPES +{ + MBG_GPIO_DIGITAL_AUDIO_TYPE_OFF, + MBG_GPIO_DIGITAL_AUDIO_TYPE_DARS, ///< DARS + N_MBG_GPIO_DIGITAL_AUDIO_TYPES ///< number of known types +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_DIGITAL_AUDIO_TYPES + * + * Used with :: MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT_SUPP::supp_types + * + * @see ::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 +}; + + + +/** + * @brief Initializers for an array of video epoch strings + * + * @see ::MBG_GPIO_VIDEO_EPOCHS + */ +#define MBG_GPIO_DIGITAL_AUDIO_TYPE_STRS \ +{ \ + "OFF", \ + "DARS" \ +} + + - union /**< settings depending on the GPIO type, see ::MBG_GPIO_TYPES */ +/** + * @brief Enumeration of flags used with GPIO type digital audio outputs + */ +enum MBG_GPIO_DIGITAL_AUDIO_FLAGS +{ + MBG_GPIO_DIGITAL_AUDIO_RESERVED_FLAG, ///< reserved + N_MBG_GPIO_DIGITAL_AUDIO_FLAGS ///< number of known flags +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_DIGITAL_AUDIO_FLAGS + * + * Used with ::MBG_GPIO_DIGITAL_AUDIO_OUT_SETTINGS::flags + * + * @see ::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 +}; + + + +/** + * @brief Configuration of a GPIO digital audio output + * + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT + * @see ::MBG_GPIO_SETTINGS + */ +typedef struct +{ + uint32_t type; ///< digital audio type, see ::MBG_GPIO_DIGITAL_AUDIO_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_DIGITAL_AUDIO_OUT_SETTINGS; + +#define _mbg_swab_mbg_gpio_digital_audio_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 digital audio output + * + * Used as sub-structure of ::MBG_GPIO_LIMITS. + * + * @see ::MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT + * @see ::MBG_GPIO_LIMITS + */ +typedef struct +{ + uint32_t supp_types; ///< supported digital audio types, see ::MBG_GPIO_DIGITAL_AUDIO_TYPE_MASKS + uint32_t supp_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_DIGITAL_AUDIO_OUT_SUPP; + +#define _mbg_swab_mbg_gpio_digital_audio_out_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_types ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ + _mbg_swab32( &(_p)->reserved2 ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of general flags used with a GPIO + * + * @see ::MBG_GPIO_FLAG_MASKS + */ +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 + N_MBG_GPIO_FLAGS ///< number of known flags +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_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 +}; + + + +/** + * @brief A generic structure used to hold a GPIO port's settings + */ +typedef struct +{ + 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 + + uint32_t flags; ///< flags, see ::MBG_GPIO_FLAG_MASKS + + /// settings depending on the GPIO type, see ::MBG_GPIO_TYPES + union { - MBG_GPIO_FREQ_IN_SETTINGS freq_in; /**< if type is MBG_GPIO_TYPE_FREQ_IN */ - MBG_GPIO_FREQ_OUT_SETTINGS freq_out; /**< if type is MBG_GPIO_TYPE_FREQ_OUT */ - MBG_GPIO_FIXED_FREQ_OUT_SETTINGS ff_out; /**< if type is MBG_GPIO_TYPE_FIXED_FREQ_OUT */ - MBG_GPIO_BITS_IN_SETTINGS bits_in; /**< if type is MBG_GPIO_TYPE_BITS_IN */ - MBG_GPIO_BITS_OUT_SETTINGS bits_out; /**< if type is MBG_GPIO_TYPE_BITS_OUT */ + MBG_GPIO_FREQ_IN_SETTINGS freq_in; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FREQ_IN + MBG_GPIO_FREQ_OUT_SETTINGS freq_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FREQ_OUT + MBG_GPIO_FIXED_FREQ_OUT_SETTINGS ff_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FIXED_FREQ_OUT + MBG_GPIO_BITS_IN_SETTINGS bits_in; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_BITS_IN + MBG_GPIO_BITS_OUT_SETTINGS bits_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_BITS_OUT + 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 } u; } MBG_GPIO_SETTINGS; +#define _mbg_swab_mbg_gpio_settings( _p, _recv ) \ +do \ +{ \ + uint32_t t = (_p)->type; \ + if ( (_recv) ) \ + _mbg_swab32( &t ); \ + _mbg_swab32( &(_p)->type ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab8( &(_p)->reserved_2 ); \ + _mbg_swab8( &(_p)->ass_io_idx ); \ + _mbg_swab32( &(_p)->flags ); \ + switch( t ) \ + { \ + case MBG_GPIO_TYPE_FREQ_IN : _mbg_swab_mbg_gpio_freq_in_settings( &(_p)->u.freq_in ); break; \ + case MBG_GPIO_TYPE_FREQ_OUT : _mbg_swab_mbg_gpio_freq_out_settings( &(_p)->u.freq_out ); break; \ + case MBG_GPIO_TYPE_FIXED_FREQ_OUT : _mbg_swab_mbg_gpio_fixed_freq_out_settings( &(_p)->u.ff_out ); break; \ + case MBG_GPIO_TYPE_BITS_IN : _mbg_swab_mbg_gpio_bits_in_settings( &(_p)->u.bits_in, (_recv) ); break; \ + case MBG_GPIO_TYPE_BITS_OUT : _mbg_swab_mbg_gpio_bits_out_settings( &(_p)->u.bits_out ); break; \ + case MBG_GPIO_TYPE_VIDEO_OUT : _mbg_swab_mbg_gpio_video_out_settings( &(_p)->u.video_out ); break; \ + 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; \ + default : break; \ + } \ +} while ( 0 ) + + + +/** + * @brief A GPIO port's current settings, plus port index + */ +typedef struct +{ + uint32_t idx; ///< port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1 + MBG_GPIO_SETTINGS settings; ///< current settings + +} MBG_GPIO_SETTINGS_IDX; + +#define _mbg_swab_mbg_gpio_settings_idx( _p, _recv ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_mbg_gpio_settings( &(_p)->settings, (_recv ) ); \ +} while ( 0 ) + /** - * @brief A generic structure used to describe a GPIO ports limiting values + * @brief A generic structure used to specify a GPIO port's limits */ typedef struct { - uint32_t type; /**< GPIO type, see ::MBG_GPIO_TYPES */ - uint32_t reserved; /**< currently always 0 */ - uint32_t supp_flags; /**< supported flags */ + uint32_t type; ///< GPIO type, see ::MBG_GPIO_TYPES + uint32_t reserved; ///< reserved, currently always 0 + uint32_t supp_flags; ///< supported flags, see ::MBG_GPIO_FLAG_MASKS - union /**< 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 type is MBG_GPIO_TYPE_FREQ_IN */ - MBG_GPIO_FREQ_OUT_SUPP freq_out; /**< if type is MBG_GPIO_TYPE_FREQ_OUT */ - MBG_GPIO_FIXED_FREQ_OUT_SUPP ff_out; /**< if type is MBG_GPIO_TYPE_FIXED_FREQ_OUT */ - MBG_GPIO_BITS_IN_SUPP bits_in; /**< if type is MBG_GPIO_TYPE_BITS_IN */ - MBG_GPIO_BITS_OUT_SUPP bits_out; /**< if type is MBG_GPIO_TYPE_BITS_OUT */ + MBG_GPIO_FREQ_IN_SUPP freq_in; ///< if ::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 } u; } MBG_GPIO_LIMITS; +#define _mbg_swab_mbg_gpio_limits( _p, _recv ) \ +do \ +{ \ + uint32_t t = (_p)->type; \ + if ( (_recv) ) \ + _mbg_swab32( &t ); \ + _mbg_swab32( &(_p)->type ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + switch( t ) \ + { \ + case MBG_GPIO_TYPE_FREQ_IN : _mbg_swab_mbg_gpio_freq_in_supp( &(_p)->u.freq_in ); break; \ + case MBG_GPIO_TYPE_FREQ_OUT : _mbg_swab_mbg_gpio_freq_out_supp( &(_p)->u.freq_out ); break; \ + case MBG_GPIO_TYPE_FIXED_FREQ_OUT : _mbg_swab_mbg_gpio_fixed_freq_out_supp( &(_p)->u.ff_out ); break; \ + case MBG_GPIO_TYPE_BITS_IN : _mbg_swab_mbg_gpio_bits_in_supp( &(_p)->u.bits_in ); break; \ + case MBG_GPIO_TYPE_BITS_OUT : _mbg_swab_mbg_gpio_bits_out_supp( &(_p)->u.bits_out ); break; \ + case MBG_GPIO_TYPE_VIDEO_OUT : _mbg_swab_mbg_gpio_video_out_supp( &(_p)->u.video_out ); break; \ + 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; \ + default : break; \ + } \ +} while ( 0 ) + + + +/** + * @brief A GPIO port's current settings and limits + */ +typedef struct +{ + MBG_GPIO_SETTINGS settings; ///< current settings + MBG_GPIO_LIMITS limits; ///< limits of this GPIO port + +} MBG_GPIO_INFO; + + +#define _mbg_swab_mbg_gpio_info( _p, _recv ) \ +do \ +{ \ + _mbg_swab_mbg_gpio_settings( &(_p)->settings, (_recv) ); \ + _mbg_swab_mbg_gpio_limits( &(_p)->limits, (_recv) ); \ +} while ( 0 ) /** - * @brief A structure used to configure a specific GPIO port + * @brief A GPIO port's current settings and limits, plus port index */ typedef struct { - uint32_t idx; /**< port number, 0..(MBG_GPIO_CFG_LIMITS::num_io - 1) */ - MBG_GPIO_SETTINGS settings; /**< configuration settings */ + uint32_t idx; ///< port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1 + MBG_GPIO_INFO info; ///< limits and current settings of this GPIO port -} MBG_GPIO_SETTINGS_IDX; +} MBG_GPIO_INFO_IDX; + +#define _mbg_swab_mbg_gpio_info_idx( _p, _recv ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_mbg_gpio_info( &(_p)->info, (_recv) ); \ +} while ( 0 ) /** - * @brief A structure used query the current GPIO port settings and capabilities + * @brief Status information on a single GPIO port */ typedef struct { - MBG_GPIO_SETTINGS settings; /**< current configuration */ - MBG_GPIO_LIMITS limits; /**< supp. and max. values */ + uint8_t port_state; ///< see ::MBG_GPIO_PORT_STATES + uint8_t reserved_0; ///< reserved, currently unused and always 0 + uint16_t reserved_1; ///< reserved, currently unused and always 0 + uint32_t reserved_2; ///< reserved, currently unused and always 0 + uint32_t reserved_3; ///< reserved, currently unused and always 0 -} MBG_GPIO_INFO; +} MBG_GPIO_STATUS; + +#define _mbg_swab_mbg_gpio_status( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->port_state ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) /** - * @brief A structure used to query configuration and capabilities of a specific GPIO port + * @brief Status information on a specific GPIO port */ typedef struct { - uint32_t idx; /**< port number, 0..(MBG_GPIO_CFG_LIMITS::num_io - 1) */ - MBG_GPIO_INFO info; /**< current settings and capabilities of this GPIO port */ + uint16_t idx; ///< port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1 + MBG_GPIO_STATUS status; ///< status information -} MBG_GPIO_INFO_IDX; +} MBG_GPIO_STATUS_IDX; + +#define _mbg_swab_mbg_gpio_status_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_mbg_gpio_status( &(_p)->status ); \ +} while ( 0 ) -/** @} group_gpio */ + +/** + * @brief GPIO port states + * + * Used with ::MBG_GPIO_STATUS::port_state + * + * @see ::DEFAULT_GPIO_PORT_STATE_NAMES + */ +enum MBG_GPIO_PORT_STATES +{ + MBG_GPIO_PORT_UNUSED, ///< configured as unused input + MBG_GPIO_PORT_OUTPUT_ENBD, ///< configured output signal enabled + MBG_GPIO_INPUT_SIG_AVAIL, ///< input signal is available + N_MBG_GPIO_PORT_STATES ///< number of known port states +}; /** - * @defgroup group_havequick GPIO port configuration stuff + * @brief String initializers for GPIO port state names + * + * @see ::MBG_GPIO_PORT_STATES + */ +#define DEFAULT_GPIO_PORT_STATE_NAMES \ +{ \ + "unused", \ + "output enabled", \ + "input signal available" \ +} + + +/** @} defgroup group_gpio */ + + + +/** + * @defgroup group_havequick HaveQuick definitions * * @note This is only supported if the ::GPS_HAS_HAVEQUICK bit is set - * in the RECEIVER_INFO::features mask. + * in the ::RECEIVER_INFO::features mask. * * @{ */ @@ -4677,8 +9376,8 @@ typedef struct /** * @brief Enumeration of HaveQuick formats * - * @see HAVEQUICK_SETTINGS::format - * @see HAVEQUICK_FORMAT_MASKS + * @see ::HAVEQUICK_SETTINGS::format + * @see ::HAVEQUICK_FORMAT_MASKS */ enum HAVEQUICK_FORMATS { @@ -4693,10 +9392,10 @@ enum HAVEQUICK_FORMATS /** - * @brief Bit masks associated to enumerated HaveQuick formats + * @brief Bit masks associated with the enumerated HaveQuick formats * - * @see HAVEQUICK_INFO::supp_formats - * @see HAVEQUICK_FORMATS + * @see ::HAVEQUICK_INFO::supp_formats + * @see ::HAVEQUICK_FORMATS */ enum HAVEQUICK_FORMAT_MASKS { @@ -4708,6 +9407,48 @@ enum HAVEQUICK_FORMAT_MASKS HQ_MSK_STANAG4430_EXTD = ( 1UL << HQ_FMT_STANAG4430_EXTD ) ///< see ::HQ_FMT_STANAG4430_EXTD }; +/* + * String initializers for each Havequick format + */ +#define HQ_FMT_NAME_STANAG4246_1 "STANAG4246 1" +#define HQ_FMT_NAME_STANAG4246_2 "STANAG4246 2" +#define HQ_FMT_NAME_STANAG4246_PTTI "STANAG4246 PTTI" +#define HQ_FMT_NAME_STANAG4372_SATURN_1 "STANAG4372 SATURN 1" +#define HQ_FMT_NAME_STANAG4372_SATURN_2 "STANAG4372 SATURN 2" +#define HQ_FMT_NAME_STANAG4430_EXTD "STANAG4430 EXTD" + +#define HQ_FMT_SHRT_NAME_STANAG4246_1 "STG4246 1" +#define HQ_FMT_SHRT_NAME_STANAG4246_2 "STG4246 2" +#define HQ_FMT_SHRT_NAME_STANAG4246_PTTI "STG4246 PTTI" +#define HQ_FMT_SHRT_NAME_STANAG4372_SATURN_1 "STG4372 SATURN1" +#define HQ_FMT_SHRT_NAME_STANAG4372_SATURN_2 "STG4372 SATURN2" +#define HQ_FMT_SHRT_NAME_STANAG4430_EXTD "STG4430 EXTD" + +/* + * The definition below can be used to initialize + * an array of ::N_HQ_FMT name strings. + */ +#define DEFAULT_HQ_FMT_NAMES \ +{ \ + HQ_FMT_NAME_STANAG4246_1, \ + HQ_FMT_NAME_STANAG4246_2, \ + HQ_FMT_NAME_STANAG4246_PTTI, \ + HQ_FMT_NAME_STANAG4372_SATURN_1, \ + HQ_FMT_NAME_STANAG4372_SATURN_2, \ + HQ_FMT_NAME_STANAG4430_EXTD \ +} + +#define DEFAULT_HQ_SHRT_FMT_NAMES \ +{ \ + HQ_FMT_SHRT_NAME_STANAG4246_1, \ + HQ_FMT_SHRT_NAME_STANAG4246_2, \ + HQ_FMT_SHRT_NAME_STANAG4246_PTTI, \ + HQ_FMT_SHRT_NAME_STANAG4372_SATURN_1, \ + HQ_FMT_SHRT_NAME_STANAG4372_SATURN_2, \ + HQ_FMT_SHRT_NAME_STANAG4430_EXTD \ +} + + /** * @brief Configuration settings for a HaveQuick input or output @@ -4718,9 +9459,19 @@ typedef struct 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 + uint32_t reserved_1; ///< reserved, currently always 0 + } HAVEQUICK_SETTINGS; +#define _mbg_swab_havequick_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->format ); \ + _mbg_swab16( &(_p)->flags ); \ + _mbg_swab32( &(_p)->offset ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ +} while ( 0 ) /** * @brief Current settings and capabilities of a HaveQuick input or output @@ -4731,13 +9482,23 @@ typedef struct uint32_t supp_formats; ///< see ::HAVEQUICK_FORMAT_MASKS uint16_t supp_flags; ///< mask of flags supported in settings, see ::HAVEQUICK_FLAG_MASKS uint16_t reserved; ///< reserved, currently always 0 + } HAVEQUICK_INFO; +#define _mbg_swab_havequick_info( _p ) \ +do \ +{ \ + _mbg_swab_havequick_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_formats ); \ + _mbg_swab16( &(_p)->supp_flags ); \ + _mbg_swab16( &(_p)->reserved ); \ +} while ( 0 ) + /** * @brief Known HaveQuick control flags * - * @see HAVEQUICK_FLAG_MASKS + * @see ::HAVEQUICK_FLAG_MASKS */ enum HAVEQUICK_FLAG_BITS { @@ -4749,11 +9510,11 @@ enum HAVEQUICK_FLAG_BITS /** - * @brief Bit masks associated to HaveQuick control flags + * @brief Bit masks associated with HaveQuick control flags * - * @see HQ_SETTINGS::flags - * @see HQ_INFO::flags - * @see HAVEQUICK_FLAG_BITS + * @see ::HAVEQUICK_SETTINGS::flags + * @see ::HAVEQUICK_INFO::supp_flags + * @see ::HAVEQUICK_FLAG_BITS */ enum HAVEQUICK_FLAG_MASKS { @@ -4762,59 +9523,64 @@ enum HAVEQUICK_FLAG_MASKS HQ_MSK_USE_EXT_PPS = ( 1UL << HQ_FLAG_USE_EXT_PPS ) ///< see ::HQ_FLAG_USE_EXT_PPS }; - -/** @} group_havequick */ +/** @} defgroup group_havequick */ /** * @defgroup group_evt_log Event logging support * - * @note This is only available if ::GPS_HAS_EVT_LOG is set in RECEIVER_INFO::features. + * @note This is only available if ::GPS_HAS_EVT_LOG is set in ::RECEIVER_INFO::features. * * @{ */ -/** @brief Number of event log entries that can be stored and yet have been saved */ +/** + * @brief Number of event log entries that can be stored and yet have been saved + */ typedef struct { - uint32_t used; /**< current number of saved log entries */ - uint32_t max; /**< max number of log entries which can be saved */ + uint32_t used; ///< current number of saved log entries + uint32_t max; ///< max number of log entries which can be saved + } MBG_NUM_EVT_LOG_ENTRIES; #define _mbg_swab_mbg_num_evt_log_entries( _p ) \ +do \ { \ _mbg_swab32( &(_p)->used ); \ _mbg_swab32( &(_p)->max ); \ -} +} while ( 0 ) typedef uint16_t MBG_EVT_CODE; -#define _mbg_swab_evt_code( _p ) _mbg_swab16( _p ); +#define _mbg_swab_evt_code( _p ) _mbg_swab16( _p ) typedef uint16_t MBG_EVT_INFO; -#define _mbg_swab_evt_info( _p ) _mbg_swab16( _p ); +#define _mbg_swab_evt_info( _p ) _mbg_swab16( _p ) /** * @brief An event log entry */ - typedef struct - { - uint32_t time; /**< like time_t, seconds since 1970 */ - MBG_EVT_CODE code; /**< event ID or'ed with severity level */ - MBG_EVT_INFO info; /**< optional event info, depending on event ID */ - } MBG_EVT_LOG_ENTRY; +typedef struct +{ + uint32_t time; ///< like time_t, seconds since 1970 + MBG_EVT_CODE code; ///< event ID or'ed with severity level, see @ref MBG_EVENT_CODES + MBG_EVT_INFO info; ///< optional event info, depending on event ID + +} MBG_EVT_LOG_ENTRY; #define _mbg_swab_mbg_evt_log_entry( _p ) \ +do \ { \ _mbg_swab32( &(_p)->time ); \ _mbg_swab_evt_code( &(_p)->code ); \ _mbg_swab_evt_info( &(_p)->info ); \ -} +} while ( 0 ) -// MBG_EVT_LOG_ENTRY::code is a combination of some bits used for the ID, +// ::MBG_EVT_LOG_ENTRY::code is a combination of some bits used for the ID, // plus some bits used for the severity/level. The sum of bits must not -// exceed (8 * sizeof MBG_EVT_LOG_ENTRY::code): +// exceed (8 * sizeof ::MBG_EVT_LOG_ENTRY::code): #define MBG_EVT_ID_BITS 13 #define MBG_EVT_LVL_BITS 3 @@ -4839,53 +9605,110 @@ typedef uint16_t MBG_EVT_INFO; /** * @brief Enumeration of event IDs + * + * @see @ref MBG_EVENT_CODES + * @see @ref MBG_EVT_ID_BITS + * @see @ref MBG_EVT_LVL_BITS */ enum MBG_EVT_IDS { - MBG_EVT_ID_NONE, /**< no event (empty entry) */ - MBG_EVT_ID_POW_UP_RES, /**< power up reset */ - MBG_EVT_ID_WDOG_RES, /**< watchdog reset */ - MBG_EVT_ID_COLD_BOOT, /**< entering cold boot mode */ - MBG_EVT_ID_WARM_BOOT, /**< entering warm boot mode */ - MBG_EVT_ID_NORMAL_OP, /**< entering normal operation */ - MBG_EVT_ID_ANT_DISCONN, /**< antenna disconnect detected */ - MBG_EVT_ID_ANT_SHORT, /**< antenna short circuit detected */ - MBG_EVT_ID_ANT_OK, /**< antenna OK after failure */ - MBG_EVT_ID_LOW_SATS, /**< no satellites can be received though antenna not failing */ + MBG_EVT_ID_NONE, ///< no event (empty entry) + MBG_EVT_ID_POW_UP_RES, ///< power up reset + MBG_EVT_ID_WDOG_RES, ///< watchdog reset + MBG_EVT_ID_COLD_BOOT, ///< entering cold boot mode + MBG_EVT_ID_WARM_BOOT, ///< entering warm boot mode + MBG_EVT_ID_NORMAL_OP, ///< entering normal operation + MBG_EVT_ID_ANT_DISCONN, ///< antenna disconnect detected + MBG_EVT_ID_ANT_SHORT, ///< antenna short circuit detected + MBG_EVT_ID_ANT_OK, ///< antenna OK after failure + MBG_EVT_ID_LOW_SATS, ///< no satellites can be received though antenna not failing + MBG_EVT_ID_FW_INSTALLED, ///< Firmware has successfully been installed + MBG_EVT_ID_PTP_PORT_STATE_UNINITIALIZED, ///< PTP state changed to UNINITIALIZED + MBG_EVT_ID_PTP_PORT_STATE_INITIALIZING, ///< PTP state changed to INITIALIZING + MBG_EVT_ID_PTP_PORT_STATE_FAULTY, ///< PTP state changed to FAULTY + MBG_EVT_ID_PTP_PORT_STATE_DISABLED, ///< PTP state changed to DISABLED + MBG_EVT_ID_PTP_PORT_STATE_LISTENING, ///< PTP state changed to LISTENING + MBG_EVT_ID_PTP_PORT_STATE_PRE_MASTER, ///< PTP state changed to PRE_MASTER + MBG_EVT_ID_PTP_PORT_STATE_MASTER, ///< PTP state changed to MASTER + MBG_EVT_ID_PTP_PORT_STATE_PASSIVE, ///< PTP state changed to PASSIVE + MBG_EVT_ID_PTP_PORT_STATE_UNCALIBRATED, ///< PTP state changed to UNCALIBRATED + MBG_EVT_ID_PTP_PORT_STATE_SLAVE, ///< PTP state changed to SLAVE + MBG_EVT_ID_FW_ACTIVATED, ///< Firmware has been activated + MBG_EVT_ID_FW_DELETED, ///< Firmware has been deleted + MBG_EVT_ID_FW_ROLLBACK, ///< Firmware reset to factory defaults + 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 N_MBG_EVT_ID }; -#define ENG_EVT_ID_NAME_NONE "No event" -#define ENG_EVT_ID_NAME_POW_UP_RES "Power Up Reset" -#define ENG_EVT_ID_NAME_WDOG_RES "Watchdog Reset" -#define ENG_EVT_ID_NAME_COLD_BOOT "Cold Boot" -#define ENG_EVT_ID_NAME_WARM_BOOT "Warm Boot" -#define ENG_EVT_ID_NAME_NORMAL_OP "Normal Operation" -#define ENG_EVT_ID_NAME_ANT_DISCONN "Antenna Disconn." -#define ENG_EVT_ID_NAME_ANT_SHORT "Ant. Short-Circ." -#define ENG_EVT_ID_NAME_ANT_OK "Antenna OK" -#define ENG_EVT_ID_NAME_LOW_SATS "Few Sats Only" - - -#define MBG_EVT_ID_NAMES_ENG \ -{ \ - ENG_EVT_ID_NAME_NONE, \ - ENG_EVT_ID_NAME_POW_UP_RES, \ - ENG_EVT_ID_NAME_WDOG_RES, \ - ENG_EVT_ID_NAME_COLD_BOOT, \ - ENG_EVT_ID_NAME_WARM_BOOT, \ - ENG_EVT_ID_NAME_NORMAL_OP, \ - ENG_EVT_ID_NAME_ANT_DISCONN, \ - ENG_EVT_ID_NAME_ANT_SHORT, \ - ENG_EVT_ID_NAME_ANT_OK, \ - ENG_EVT_ID_NAME_LOW_SATS \ +#define ENG_EVT_ID_NAME_NONE "No event" +#define ENG_EVT_ID_NAME_POW_UP_RES "Power Up Reset" +#define ENG_EVT_ID_NAME_WDOG_RES "Watchdog Reset" +#define ENG_EVT_ID_NAME_COLD_BOOT "Cold Boot" +#define ENG_EVT_ID_NAME_WARM_BOOT "Warm Boot" +#define ENG_EVT_ID_NAME_NORMAL_OP "Normal Operation" +#define ENG_EVT_ID_NAME_ANT_DISCONN "Antenna Disconn." +#define ENG_EVT_ID_NAME_ANT_SHORT "Ant. Short-Circ." +#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_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_DATABASE_CONNECTED "Database(s) connected" + + +#define MBG_EVT_ID_NAMES_ENG \ +{ \ + ENG_EVT_ID_NAME_NONE, \ + ENG_EVT_ID_NAME_POW_UP_RES, \ + ENG_EVT_ID_NAME_WDOG_RES, \ + ENG_EVT_ID_NAME_COLD_BOOT, \ + ENG_EVT_ID_NAME_WARM_BOOT, \ + ENG_EVT_ID_NAME_NORMAL_OP, \ + ENG_EVT_ID_NAME_ANT_DISCONN, \ + ENG_EVT_ID_NAME_ANT_SHORT, \ + ENG_EVT_ID_NAME_ANT_OK, \ + ENG_EVT_ID_NAME_LOW_SATS, \ + ENG_EVT_ID_NAME_FW_INSTALLED, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_UNINITIALIZED, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_INITIALIZING, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_FAULTY, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_DISABLED, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_LISTENING, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_PRE_MASTER, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_MASTER, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_PASSIVE, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_UNCALIBRATED, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_SLAVE, \ + ENG_EVT_ID_NAME_FW_ACTIVATED, \ + ENG_EVT_ID_NAME_FW_DELETED, \ + ENG_EVT_ID_NAME_FW_ROLLBACK, \ + ENG_EVT_ID_NAME_UFU_FLASHED, \ + ENG_EVT_ID_NAME_DATABASE_CONNECTED \ } /** * @brief Enumeration of event severity levels + * + * @see @ref MBG_EVENT_CODES + * @see @ref MBG_EVT_ID_BITS + * @see @ref MBG_EVT_LVL_BITS */ enum MBG_EVT_LVLS { @@ -4918,27 +9741,46 @@ enum MBG_EVT_LVLS } -/** @brief Predefined event codes with associated severity levels */ +/** + * @brief Predefined event codes with associated severity levels + * + * @see ::MBG_EVT_IDS + * @see ::MBG_EVT_LVLS + * + * @anchor MBG_EVENT_CODES @{ */ + +#define MBG_EVT_NONE _mbg_mk_evt_code( MBG_EVT_ID_NONE, MBG_EVT_LVL_NONE ) +#define MBG_EVT_POW_UP_RES _mbg_mk_evt_code( MBG_EVT_ID_POW_UP_RES, MBG_EVT_LVL_WARN ) +#define MBG_EVT_WDOG_RES _mbg_mk_evt_code( MBG_EVT_ID_WDOG_RES, MBG_EVT_LVL_CRIT ) +#define MBG_EVT_COLD_BOOT _mbg_mk_evt_code( MBG_EVT_ID_COLD_BOOT, MBG_EVT_LVL_ERR ) +#define MBG_EVT_WARM_BOOT _mbg_mk_evt_code( MBG_EVT_ID_WARM_BOOT, MBG_EVT_LVL_ERR ) +#define MBG_EVT_NORMAL_OP _mbg_mk_evt_code( MBG_EVT_ID_NORMAL_OP, MBG_EVT_LVL_INFO ) +#define MBG_EVT_ANT_DISCONN _mbg_mk_evt_code( MBG_EVT_ID_ANT_DISCONN, MBG_EVT_LVL_CRIT ) +#define MBG_EVT_ANT_SHORT _mbg_mk_evt_code( MBG_EVT_ID_ANT_SHORT, MBG_EVT_LVL_CRIT ) +#define MBG_EVT_ANT_OK _mbg_mk_evt_code( MBG_EVT_ID_ANT_OK, MBG_EVT_LVL_INFO ) +#define MBG_EVT_LOW_SATS _mbg_mk_evt_code( MBG_EVT_ID_LOW_SATS, MBG_EVT_LVL_WARN ) +#define MBG_EVT_FW_INSTALLED _mbg_mk_evt_code( MBG_EVT_ID_FW_INSTALLED, MBG_EVT_LVL_INFO ) +#define MBG_EVT_PTP_PORT_STATE_UNINITIALIZED _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_UNINITIALIZED, MBG_EVT_LVL_WARN ) +#define MBG_EVT_PTP_PORT_STATE_INITIALIZING _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_INITIALIZING, MBG_EVT_LVL_INFO ) +#define MBG_EVT_PTP_PORT_STATE_FAULTY _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_FAULTY, MBG_EVT_LVL_ERR ) +#define MBG_EVT_PTP_PORT_STATE_DISABLED _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_DISABLED, MBG_EVT_LVL_INFO ) +#define MBG_EVT_PTP_PORT_STATE_LISTENING _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_LISTENING, MBG_EVT_LVL_INFO ) +#define MBG_EVT_PTP_PORT_STATE_PRE_MASTER _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_PRE_MASTER, MBG_EVT_LVL_INFO ) +#define MBG_EVT_PTP_PORT_STATE_MASTER _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_MASTER, MBG_EVT_LVL_INFO ) +#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_NONE _mbg_mk_evt_code( MBG_EVT_ID_NONE, MBG_EVT_LVL_NONE ) -#define MBG_EVT_POW_UP_RES _mbg_mk_evt_code( MBG_EVT_ID_POW_UP_RES, MBG_EVT_LVL_WARN ) -#define MBG_EVT_WDOG_RES _mbg_mk_evt_code( MBG_EVT_ID_WDOG_RES, MBG_EVT_LVL_CRIT ) -#define MBG_EVT_COLD_BOOT _mbg_mk_evt_code( MBG_EVT_ID_COLD_BOOT, MBG_EVT_LVL_ERR ) -#define MBG_EVT_WARM_BOOT _mbg_mk_evt_code( MBG_EVT_ID_WARM_BOOT, MBG_EVT_LVL_ERR ) -#define MBG_EVT_NORMAL_OP _mbg_mk_evt_code( MBG_EVT_ID_NORMAL_OP, MBG_EVT_LVL_INFO ) -#define MBG_EVT_ANT_DISCONN _mbg_mk_evt_code( MBG_EVT_ID_ANT_DISCONN, MBG_EVT_LVL_CRIT ) -#define MBG_EVT_ANT_SHORT _mbg_mk_evt_code( MBG_EVT_ID_ANT_SHORT, MBG_EVT_LVL_CRIT ) -#define MBG_EVT_ANT_OK _mbg_mk_evt_code( MBG_EVT_ID_ANT_OK, MBG_EVT_LVL_INFO ) -#define MBG_EVT_LOW_SATS _mbg_mk_evt_code( MBG_EVT_ID_LOW_SATS, MBG_EVT_LVL_WARN ) +/** @} anchor MBG_EVENT_CODES */ -/** @} group_evt_log */ +/** @} defgroup group_evt_log */ /** * @defgroup group_ims IMS support * - * @note This is only available if ::GPS_HAS_IMS is set in RECEIVER_INFO::features. + * @note This is only supported if ::GPS_HAS_IMS is set in ::RECEIVER_INFO::features. * * @{ */ @@ -4947,20 +9789,45 @@ enum MBG_EVT_LVLS */ typedef struct { - uint8_t chassis_id; /**< chassis ID, 0 if installed on the backplane */ - uint8_t slot_id; /**< slot number on the chassis */ - uint16_t num_sensors; /**< number of sensors provided by the device */ - uint32_t reserved; /**< currently unused, always 0 */ - uint32_t flags; /**< currently unused, always 0 */ + 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 } MBG_IMS_STATE; #define _mbg_swab_mbg_ims_state( _p ) \ +do \ { \ _mbg_swab16( &(_p)->num_sensors ); \ _mbg_swab32( &(_p)->reserved ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) + + + +/** + * @brief Enumeration of bits used to define ::MBG_IMS_STATE_FLAG_MASKS + * + * @see ::MBG_IMS_STATE_FLAG_MASKS + */ +enum MBG_IMS_STATE_FLAG_BITS +{ + MBG_IMS_STATE_FLAG_BIT_HAS_FDM, ///< device supports FDM API + N_MBG_IMS_STATE_FLAG_BITS +}; + + +/** + * @brief Bit masks used with ::MBG_IMS_STATE::flags + * + * @see ::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 +}; @@ -4969,16 +9836,17 @@ typedef struct */ typedef struct { - uint16_t type; /**< sensor type, see ::MBG_IMS_SENSORS */ - uint16_t idx; /**< index of the sensor of this type */ - int32_t val; /**< sensor value, in units according to the type */ - int16_t exp; /**< 10s exponent of the sensor value */ - uint16_t reserved; /**< currently unused, always 0 */ - uint32_t flags; /**< currently unused, always 0 */ + uint16_t type; ///< sensor type, see ::MBG_IMS_SENSORS + uint16_t idx; ///< index of the sensor of this type + int32_t val; ///< sensor value, in units according to the type + int16_t exp; ///< 10s exponent of the sensor value + uint16_t reserved; ///< currently unused, always 0 + uint32_t flags; ///< currently unused, always 0 } MBG_IMS_SENSOR_STATE; #define _mbg_swab_mbg_ims_sensor_state( _p ) \ +do \ { \ _mbg_swab16( &(_p)->type ); \ _mbg_swab16( &(_p)->idx ); \ @@ -4986,7 +9854,7 @@ typedef struct _mbg_swab16( &(_p)->exp ); \ _mbg_swab16( &(_p)->reserved ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) /** @@ -4994,43 +9862,476 @@ typedef struct */ typedef struct { - uint32_t idx; /**< sensor index, 0..MBG_IMS_STATE::num_sensors - 1 */ - MBG_IMS_SENSOR_STATE state; /**< sensor state */ + uint32_t idx; ///< sensor index, 0..::MBG_IMS_STATE::num_sensors-1 + MBG_IMS_SENSOR_STATE state; ///< sensor state } MBG_IMS_SENSOR_STATE_IDX; #define _mbg_swab_mbg_ims_sensor_state_idx( _p ) \ +do \ { \ _mbg_swab32( &(_p)->idx ); \ _mbg_swab_mbg_ims_sensor_state( &(_p)->state ); \ -} +} while ( 0 ) /** * @brief IMS sensor types + * + * Used with ::MBG_IMS_SENSOR_STATE::type */ enum MBG_IMS_SENSORS { - MBG_IMS_SENSOR_TEMP_C, /**< temperature in degrees C */ - MBG_IMS_SENSOR_VOLTAGE, /**< voltage in val/exp, output state in flags */ - MBG_IMS_SENSOR_PLL, /**< control voltage in val/exp, lock state in flags */ - N_MBG_IMS_SENSORS /**< number of supported sensor types */ + MBG_IMS_SENSOR_TEMP_C, ///< temperature in degrees Celsius + MBG_IMS_SENSOR_VOLTAGE, ///< voltage in val/exp, output state in flags + MBG_IMS_SENSOR_PLL, ///< control voltage in val/exp, lock state in flags + MBG_IMS_SENSOR_VOLTAGE_INPUT, ///< input voltage in val/exp, output state in flags + MBG_IMS_SENSOR_VOLTAGE_OUTPUT, ///< output voltage in val/exp, output state in flags + MBG_IMS_SENSOR_VOLTAGE_SUPPLY, ///< supply voltage in val/exp, output state in flags + MBG_IMS_SENSOR_CURRENT, ///< generic current in val/exp, output state in flags + MBG_IMS_SENSOR_CURRENT_BOARD_SUPPLY, ///< board supply current in val/exp, output state in flags + MBG_IMS_SENSOR_CURRENT_OSC_SUPPLY, ///< oscillator supply current in val/exp, output state in flags + N_MBG_IMS_SENSORS ///< number of supported sensor types +}; + + + +/** + * @brief IMS sensor state flags for voltage + * + * Used with ::MBG_IMS_SENSOR_STATE::flags in case ::MBG_IMS_SENSOR_STATE::type + * is ::MBG_IMS_SENSOR_VOLTAGE. + */ +enum MBG_IMS_SENSOR_STATE_FLAG_MASK_VOLTAGE +{ + MBG_IMS_SENSOR_VOLTAGE_OUT_ENB = 0x01, ///< output is enabled + MBG_IMS_SENSOR_VOLTAGE_OUT_OVR = 0x02 ///< output overload +}; + + +/** + * @brief IMS sensor state flags for PLL + * + * Used with ::MBG_IMS_SENSOR_STATE::flags in case ::MBG_IMS_SENSOR_STATE::type + * is ::MBG_IMS_SENSOR_PLL. + */ +enum MBG_IMS_SENSOR_STATE_FLAG_MASK_PLL +{ + MBG_IMS_SENSOR_PLL_LOCKED = 0x01 ///< PLL is locked +}; + + + +/** + * @brief DAC limit specs + */ +typedef struct +{ + int32_t dac_val_min; ///< min. possible DAC Value, positive or negative + int32_t dac_val_max; ///< max. possible DAC Value, positive or negative + + int32_t u_min; ///< min. possible real voltage range [mV], positive or negative, depending on ::MBG_DAC_SPECS::dac_val_min + int32_t u_max; ///< max. possible real voltage range [mV], positive or negative, depending on ::MBG_DAC_SPECS::dac_val_max + + uint32_t reserved_0; ///< reserved, currently always 0 + uint32_t reserved_1; ///< reserved, currently always 0 + +} MBG_DAC_SPECS; + +#define _mbg_swab_mbg_dac_specs( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->dac_val_min ); \ + _mbg_swab32( &(_p)->dac_val_max ); \ + _mbg_swab32( &(_p)->u_min ); \ + _mbg_swab32( &(_p)->u_max ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ +} while ( 0 ) + + + +/** + * @brief Output state of FDM device. + * + * @note This is only supported if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags + */ +typedef struct +{ + int32_t dac_val; ///< current DAC value, positive or negative + uint32_t mode; ///< current output mode, see ::MBG_IMS_FDM_OUTPUT_MODES + + MBG_DAC_SPECS dac_specs; ///< DAC specific limits + + uint32_t reserved_0; ///< reserved, currently always 0 + uint32_t reserved_1; ///< reserved, currently always 0 + +} MBG_IMS_FDM_OUTPUT_STATE; + +#define _mbg_swab_mbg_ims_fdm_output_state( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->dac_val ); \ + _mbg_swab32( &(_p)->mode ); \ + _mbg_swab_mbg_dac_specs( &(_p)->dac_specs ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ +} while ( 0 ) + + + +/** + * @brief Output state of FDM device plus index. + */ +typedef struct +{ + uint32_t idx; + MBG_IMS_FDM_OUTPUT_STATE state; + +} MBG_IMS_FDM_OUTPUT_STATE_IDX; + +#define _mbg_swab_mbg_ims_fdm_output_state_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_mbg_ims_fdm_output_state( &(_p)->state ); \ +} while ( 0 ) + + + +/** + * @brief Output settings of FDM device + * + * @note This is only supported if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags + */ +typedef struct +{ + uint32_t mode; ///< mode, see ::MBG_IMS_FDM_OUTPUT_MODES + uint32_t reserved; ///< reserved, currently always 0 + +} MBG_IMS_FDM_OUTPUT_SETTINGS; + +#define _mbg_swab_mbg_ims_fdm_output_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->mode ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + + +/** + * @brief Output settings for FDM devices plus index. + */ +typedef struct +{ + uint32_t idx; + MBG_IMS_FDM_OUTPUT_SETTINGS settings; + +} MBG_IMS_FDM_OUTPUT_SETTINGS_IDX; + +#define _mbg_swab_mbg_ims_fdm_output_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_mbg_ims_fdm_output_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +/** + * @brief Specific output settings and limits. + */ +typedef struct +{ + MBG_IMS_FDM_OUTPUT_SETTINGS settings; ///< current settings + uint32_t supp_modes; ///< supported modes, see ::MBG_IMS_FDM_OUTPUT_MODE_MASKS + MBG_DAC_SPECS dac_specs; ///< DAC specific limits + +} MBG_IMS_FDM_OUTPUT_INFO; + +#define _mbg_swab_mbg_ims_fdm_output_info( _p ) \ +do \ +{ \ + _mbg_swab_mbg_ims_fdm_output_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_modes ); \ + _mbg_swab_mbg_dac_specs( &(_p)->dac_specs ); \ +} while ( 0 ) + + + +/** + * @brief Specific output settings and limits, plus index. + */ +typedef struct +{ + uint32_t idx; + MBG_IMS_FDM_OUTPUT_INFO info; + +} MBG_IMS_FDM_OUTPUT_INFO_IDX; + +#define _mbg_swab_mbg_ims_fdm_output_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_mbg_ims_fdm_output_info( &(_p)->info ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of known output modes + * + * Used with ::MBG_IMS_FDM_OUTPUT_STATE::mode + * + * @see ::MBG_IMS_FDM_OUTPUT_MODE_MASKS + */ +enum MBG_IMS_FDM_OUTPUT_MODES +{ + MBG_IMS_FDM_OUTPUT_MODE_FD, ///< Analog output reflects frequency deviation + MBG_IMS_FDM_OUTPUT_MODE_TD, ///< Analog output reflects time deviation + N_MBG_IMS_FDM_OUTPUT_MODES ///< Number of known output modes }; -// Definitions used with MBG_IMS_SENSOR_STATE::flags: +/** + * @brief Bit masks used with ::MBG_IMS_FDM_OUTPUT_STATE::mode + * + * @see ::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 +}; + + + +/** + * @brief A generic structure used to specify FDM limits + */ +typedef struct +{ + uint8_t n_outputs; ///< number of outputs per module + uint8_t reserved_0; ///< reserved, currently always 0 + uint16_t reserved_1; ///< reserved, currently always 0 + + uint32_t fd_neg_limit; ///< min. frequency deviation limit, 1/::MBG_IMS_FDM_LIMITS::fd_scale Hz units + uint32_t fd_pos_limit; ///< max. frequency deviation limit, 1/::MBG_IMS_FDM_LIMITS::fd_scale Hz units + uint32_t fd_scale; ///< scale for ::MBG_IMS_FDM_LIMITS::fd_neg_limit and ::MBG_IMS_FDM_LIMITS::fd_pos_limit + + uint32_t td_neg_limit; ///< min. time deviation limit, 1/::MBG_IMS_FDM_LIMITS::td_scale s units + uint32_t td_pos_limit; ///< max. time deviation limit, 1/::MBG_IMS_FDM_LIMITS::td_scale s units + uint32_t td_scale; ///< scale for ::MBG_IMS_FDM_LIMITS::td_neg_limit and ::MBG_IMS_FDM_LIMITS::td_pos_limit + + uint32_t reserved_2; ///< reserved, currently always 0 + +} MBG_IMS_FDM_LIMITS; + +#define _mbg_swab_mbg_ims_fdm_limits( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->n_outputs ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + \ + _mbg_swab32( &(_p)->fd_neg_limit ); \ + _mbg_swab32( &(_p)->fd_pos_limit ); \ + _mbg_swab32( &(_p)->fd_scale ); \ + \ + _mbg_swab32( &(_p)->td_neg_limit ); \ + _mbg_swab32( &(_p)->td_pos_limit ); \ + _mbg_swab32( &(_p)->td_scale ); \ + \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) + + + +/** + * @brief State of FDM device + * + * @note This is only supported if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags. + * + */ +typedef struct +{ + MBG_GPIO_FREQ freq; ///< Current frequency + + NANO_TIME_64 t_ref; ///< Current reference time + NANO_TIME_64 t_plt; ///< Current power line time + NANO_TIME_64 t_sync; ///< Last sync Time (reference time) -// if MBG_IMS_SENSOR_STATE::type == MBG_IMS_SENSOR_VOLTAGE: -#define MBG_IMS_SENSOR_VOLTAGE_OUT_ENB 0x01 // output is enabled -#define MBG_IMS_SENSOR_VOLTAGE_OUT_OVR 0x02 // output overload + uint32_t line_freq; ///< Nominal line frequency, see ::MBG_IMS_FDM_LINE_FREQS + uint32_t flags; ///< Flags, see ::MBG_IMS_FDM_STATE_FLAG_MASKS + uint32_t reserved; ///< Reserved, currently always 0 -// if MBG_IMS_SENSOR_STATE::type == MBG_IMS_SENSOR_PLL: -#define MBG_IMS_SENSOR_PLL_LOCKED 0x01 +} MBG_IMS_FDM_STATE; +#define _mbg_swab_mbg_ims_fdm_state( _p ) \ +do \ +{ \ + _mbg_swab_mbg_gpio_freq( &(_p)->freq ); \ + _mbg_swab_nano_time_64( &(_p)->t_ref ); \ + _mbg_swab_nano_time_64( &(_p)->t_plt ); \ + _mbg_swab_nano_time_64( &(_p)->t_sync ); \ + _mbg_swab32( &(_p)->line_freq ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration known line frequencies + * + * Used with ::MBG_IMS_FDM_STATE::line_freq + * + * @see ::MBG_IMS_FDM_LINE_FREQ_MASKS + */ +enum MBG_IMS_FDM_LINE_FREQS +{ + MBG_IMS_FDM_LINE_FREQ_AUTO, ///< Auto detect line frequency + MBG_IMS_FDM_LINE_FREQ_50HZ, ///< 50Hz line frequency + MBG_IMS_FDM_LINE_FREQ_60HZ, ///< 60Hz line frequency + N_MBG_IMS_FDM_LINE_FREQS ///< number of known line frequencies +}; -/** @} group_ims */ + +/** + * @brief Bit masks corresponding to defined line frequencies + * + * @see ::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 +}; + + +/** + * @brief Initializers for an array of line freq. name strings + * + * @see ::MBG_IMS_FDM_LINE_FREQS + */ +#define MBG_IMS_FDM_LINE_FREQ_STRS \ +{ \ + "Auto", \ + "50 Hz", \ + "60 Hz", \ +} + + +/** + * @brief Enumeration of flag bits used to define ::MBG_IMS_FDM_STATE_FLAG_MASKS + */ +enum MBG_IMS_FDM_STATE_FLAG_BITS +{ + MBG_IMS_FDM_STATE_FLAG_BIT_SYNC_AFTER_RESET, ///< if sync'ed after reset + MBG_IMS_FDM_STATE_FLAG_BIT_PLT_IS_LOCKED, ///< Power Line Time is locked + MBG_IMS_FDM_STATE_FLAG_BIT_FD_OVERFLOW, ///< Frequency deviation overflow occurred + MBG_IMS_FDM_STATE_FLAG_BIT_TD_OVERFLOW, ///< Time deviation overflow occurred + N_MBG_IMS_FDM_STATE_FLAG_BITS ///< number of known state flag bits +}; + + +/** + * @brief Bit masks used with ::MBG_IMS_FDM_STATE::flags + * + * @see ::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 +}; + + + +/** + * @brief FDM device settings + * + * @note This is only supported if ::MBG_IMS_STATE_FLAG_BIT_HAS_FDM is set in ::MBG_IMS_STATE::flags. + * + */ +typedef struct +{ + uint32_t fd_neg_limit; ///< min. frequency deviation limit in 1 mHz steps + uint32_t fd_pos_limit; ///< max. frequency deviation limit in 1 mHz steps + + uint32_t td_neg_limit; ///< min. time deviation limit in 1 ms steps + uint32_t td_pos_limit; ///< max. time deviation limit in 1 ms steps + + uint32_t line_freq; ///< nominal line frequency, see ::MBG_IMS_FDM_LINE_FREQS + uint32_t reserved; ///< reserved, currently always 0 + +} MBG_IMS_FDM_SETTINGS; + +#define _mbg_swab_mbg_ims_fdm_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->fd_neg_limit ); \ + _mbg_swab32( &(_p)->fd_pos_limit ); \ + _mbg_swab32( &(_p)->td_neg_limit ); \ + _mbg_swab32( &(_p)->td_pos_limit ); \ + _mbg_swab32( &(_p)->line_freq ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + + + +/** + * @brief IMS FDM flags + * + * @see ::MBG_IMS_FDM_FLAG_MASKS + */ +enum MBG_IMS_FDM_FLAGS +{ + MBG_IMS_FDM_FLAG_CAN_SET_TDEV, ///< Device supports command GPS_FDM_SET_TD + N_MBG_IMS_FDM_FLAGS ///< Number of known FDM flags +}; + + + +/** + * @brief IMS FDM flag masks + * + * @see ::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 +}; + + + +/** + * @brief Specific FDM settings and limits. + */ +typedef struct +{ + MBG_IMS_FDM_SETTINGS settings; + uint32_t supp_line_freqs; ///< Bit mask of supported line frequencies, see ::MBG_IMS_FDM_LINE_FREQ_MASKS + uint32_t reserved; ///< Reserved, currently always 0 + uint32_t flags; ///< Flags, see ::MBG_IMS_FDM_FLAG_MASKS + +} MBG_IMS_FDM_INFO; + +#define _mbg_swab_mbg_ims_fdm_info( _p ) \ +do \ +{ \ + _mbg_swab_mbg_ims_fdm_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_line_freqs ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + +/** @} defgroup group_ims */ @@ -5044,9 +10345,9 @@ enum MBG_IMS_SENSORS * _pcps_has_generic_io() or the corresponding function * mbg_dev_has_generic_io() should be used by applications to * check whether a particular bus-level device supports this. + * * @{ */ - typedef uint16_t GEN_IO_INFO_TYPE; #define _mbg_swab_gen_io_info_type( _p ) \ @@ -5055,58 +10356,52 @@ typedef uint16_t GEN_IO_INFO_TYPE; /** - * @brief The data structure used with the PCPS_GEN_IO_GET_INFO command + * @brief The data structure used with the ::PCPS_GEN_IO_GET_INFO command * - * type specifier in order to query from a device which of the other - * specified types is supported, and how many data sets are being - * used by the device. The GEN_IO_INFO_TYPE must be passed to the - * call which returns a GEN_IO_INFO structure filled by the device. + * Used to determine how many data sets of a specific type are supported + * by the device. */ typedef struct { - GEN_IO_INFO_TYPE type; // a PCPS_GEN_IO_GET_INFO type from the enum above + GEN_IO_INFO_TYPE type; // see ::PCPS_GEN_IO_TYPES uint16_t num; // supported number of data sets of the specified type } GEN_IO_INFO; #define _mbg_swab_gen_io_info( _p ) \ +do \ { \ _mbg_swab_gen_io_info_type( &(_p)->type ); \ _mbg_swab16( &(_p)->num ); \ -} +} while ( 0 ) /** - * @brief Data types used with GEN_IO_INFO::type + * @brief Data types used with ::GEN_IO_INFO::type * - * The first type specifier, PCPS_GEN_IO_GET_INFO, can + * The first type specifier, ::PCPS_GEN_IO_GET_INFO, can * be used to find out which of the other data types are * supported, and how many data sets of the specified type * are supported by a device. */ enum PCPS_GEN_IO_TYPES { - PCPS_GEN_IO_GET_INFO, /**< GEN_IO_INFO (read only) */ - PCPS_GEN_IO_CAL_REC_IRIG_RX_COMP, /**< CAL_REC_IRIG_RX_COMP (read/write) */ - N_PCPS_GEN_IO_TYPE /**< number of known types */ + PCPS_GEN_IO_GET_INFO, ///< ::GEN_IO_INFO (read only) + PCPS_GEN_IO_CAL_REC_IRIG_RX_COMP, ///< ::CAL_REC_IRIG_RX_COMP (read/write) + N_PCPS_GEN_IO_TYPE ///< number of known types }; -/** @} group_generic_io */ - +/** @} defgroup group_generic_io */ -/*------------------------------------------------------------------------*/ -/* - * The types below are not used with all devices: - */ typedef uint16_t ROM_CSUM; /* The ROM checksum */ -typedef uint16_t RCV_TIMEOUT; /* [min] (only if HAS_RCV_TIMEOUT) */ -typedef uint16_t IGNORE_LOCK; /* (only if GPS_HAS_IGNORE_LOCK) */ +typedef uint16_t RCV_TIMEOUT; /* [min] (only if ::HAS_RCV_TIMEOUT) */ +typedef uint16_t IGNORE_LOCK; /* (only if ::GPS_HAS_IGNORE_LOCK) */ /* - * Originally IGNORE_LOG above has been a boolean value (equal or + * Originally ::IGNORE_LOG above has been a boolean value (equal or * not equal 0) which was evaluated the same way for all ports. * * Due to special firmware requirements it has been changed to a @@ -5135,53 +10430,111 @@ typedef uint16_t IGNORE_LOCK; /* (only if GPS_HAS_IGNORE_LOCK) */ ( (_il) & ( _ignore_lock_for_port(_n) | IGNORE_LOCK_FOR_ALL_PORTS ) ) -/*------------------------------------------------------------------------*/ -/* +/** + * @defgroup group_scu Definitions used with SCU devices + * * The structures below are used with the SCU multiplexer board - * in a redundant system: - */ + * in a redundant system. + * + * @see ::GPS_MODEL_IS_SCU + * + * @{ */ typedef struct { - uint32_t hw_id; // hardware identification - uint32_t fw_id; // firmware identification - uint16_t flags; // reserved currently 0 - uint8_t clk0_info; // reference clock 0 type - uint8_t clk1_info; // reference clock 1 type - uint16_t epld_status; // epld status word, see defintions below - uint16_t epld_control; // epld control word, see defintions below + uint32_t hw_id; ///< hardware identification + uint32_t fw_id; ///< firmware identification + uint16_t flags; ///< reserved currently 0 + uint8_t clk0_info; ///< reference clock 0 type + uint8_t clk1_info; ///< reference clock 1 type + uint16_t epld_status; ///< EPLD status word, see ::SCU_STAT_MASKS + uint16_t epld_control; ///< EPLD control word, see ::SCU_CTRL_MASKS + } SCU_STAT_INFO; +#define _mbg_swab_scu_stat_info( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->hw_id ); \ + _mbg_swab32( &(_p)->fw_id ); \ + _mbg_swab16( &(_p)->flags ); \ + _mbg_swab8( &(_p)->clk0_info ); \ + _mbg_swab8( &(_p)->clk1_info ); \ + _mbg_swab16( &(_p)->epld_status ); \ + _mbg_swab16( &(_p)->epld_control ); \ +} while ( 0 ) + + + typedef struct { - uint16_t epld_control_mask; // control mask, determines which bit is to be changed - uint16_t epld_control_value; // control value, determines value of bits to be changed - uint32_t flags; // reserved, currently 0 + uint16_t epld_control_mask; ///< control mask, determines which bit is to be changed, see ::SCU_CTRL_MASKS + uint16_t epld_control_value; ///< control value, determines value of bits to be changed, see ::SCU_CTRL_MASKS + uint32_t flags; ///< reserved, currently 0 + } SCU_STAT_SETTINGS; -// definitions for status word bit masks -#define MSK_EPLD_STAT_TS1 0x0001 // state of time sync signal clk_1 -#define MSK_EPLD_STAT_TS2 0x0002 // state of time sync signal clk_2 -#define MSK_EPLD_STAT_TL_ERROR 0x0004 // state of time limit error input -#define MSK_EPLD_STAT_PSU1_OK 0x0008 // state of power supply 1 monitoring input -#define MSK_EPLD_STAT_PSU2_OK 0x0010 // state of power supply 2 monitoring input -#define MSK_EPLD_STAT_AUTO 0x0020 // AUTOMATIC/REMOTE or MANUAL Mode -#define MSK_EPLD_STAT_SEL 0x0040 // select bit for output MUX, ( clk_1 = 0 ) -#define MSK_EPLD_STAT_ENA 0x0080 // enable Bit for output MUX, set if enabled -#define MSK_EPLD_STAT_ACO 0x4000 // Access control override bit -#define MSK_EPLD_STAT_WDOG_OK 0x8000 // WDT_OK set to zero if watchdog expired +#define _mbg_swab_scu_stat_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->epld_control_mask ); \ + _mbg_swab16( &(_p)->epld_control_value ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Bit masks used to check the SCU EPLD status + * + * Used with ::SCU_STAT_INFO::epld_status + */ +enum SCU_STAT_MASKS +{ + MSK_EPLD_STAT_TS1 = 0x0001, ///< state of time sync signal clk_1 + MSK_EPLD_STAT_TS2 = 0x0002, ///< state of time sync signal clk_2 + MSK_EPLD_STAT_TL_ERROR = 0x0004, ///< state of time limit error input + MSK_EPLD_STAT_PSU1_OK = 0x0008, ///< state of power supply 1 monitoring input + MSK_EPLD_STAT_PSU2_OK = 0x0010, ///< state of power supply 2 monitoring input + MSK_EPLD_STAT_AUTO = 0x0020, ///< AUTOMATIC/REMOTE or MANUAL Mode + MSK_EPLD_STAT_SEL = 0x0040, ///< select bit for output MUX, ( clk_1 = 0 ) + MSK_EPLD_STAT_ENA = 0x0080, ///< enable Bit for output MUX, set if enabled + MSK_EPLD_STAT_HAS_LAN = 0x0100, ///< indicates that the device has a network interface + MSK_EPLD_STAT_RESERVED0 = 0x0200, ///< reserved, DO NOT USE! + MSK_EPLD_STAT_RESERVED1 = 0x0400, ///< reserved, DO NOT USE! + MSK_EPLD_STAT_HAS_4_PSUS = 0x0800, ///< indicates 4 power supplies instead of 2 + MSK_EPLD_STAT_PSU3_OK = 0x1000, ///< state of power supply 3 monitoring input + MSK_EPLD_STAT_PSU4_OK = 0x2000, ///< state of power supply 4 monitoring input + MSK_EPLD_STAT_ACO = 0x4000, ///< Access control override bit + MSK_EPLD_STAT_WDOG_OK = 0x8000 ///< WDT_OK set to zero if watchdog expired +}; + -#define MSK_EPLD_CNTL_SEL_REM 0x0800 // remote select for output MUX ( clk_1 = 0 ) -#define MSK_EPLD_CNTL_DIS_REM 0x1000 // remote disable for output MUX -#define MSK_EPLD_CNTL_REMOTE 0x2000 // must be set to enable remote operation -#define MSK_EPLD_CNTL_SEL_SNMP 0x4000 // select clk for comm. ( clk1 = 0 ) -#define MSK_EPLD_CNTL_ENA_SNMP 0x8000 // connect COM0 channels to XPORT +/** + * @brief Bit masks used to control the SCU EPLD + * + * Used with ::SCU_STAT_INFO::epld_control, ::SCU_STAT_SETTINGS::epld_control_mask, + * and ::SCU_STAT_SETTINGS::epld_control_value. + */ +enum SCU_CTRL_MASKS +{ + MSK_EPLD_CTL_DISB_SERIAL = 0x0001, ///< disable serial output on error + MSK_EPLD_CTL_DISB_PPS = 0x0002, ///< disable PPS output on error + MSK_EPLD_CTL_DISB_10MHZ = 0x0004, ///< disable 10 MHz output on error + + MSK_EPLD_CNTL_SEL_REM = 0x0800, ///< remote select for output MUX (clk_1 = 0) + MSK_EPLD_CNTL_DIS_REM = 0x1000, ///< remote disable for output MUX + MSK_EPLD_CNTL_REMOTE = 0x2000, ///< must be set to enable remote operation + MSK_EPLD_CNTL_SEL_SNMP = 0x4000, ///< select clk for comm. (clk1 = 0) + MSK_EPLD_CNTL_ENA_SNMP = 0x8000, ///< connect COM0 channels to XPORT +}; + /** - * @brief Definitions for SCU_STAT_INFO::clk0_info and SCU_STAT_INFO::clk1_info + * @brief Definitions for ::SCU_STAT_INFO::clk0_info and ::SCU_STAT_INFO::clk1_info * * Can be used to determine the reference clock type connected to the SCU input channels. */ @@ -5194,36 +10547,41 @@ enum SCU_CLK_INFO_TYPES N_SCU_CLK_INFO ///< number of known types }; +/** @} defgroup group_scu */ + /*------------------------------------------------------------------------*/ +#define REMOTE 0x10 +#define BOOT 0x20 + /** * @brief Satellite receiver modes of operation. * - * @note Some of the code combinations are obsolete with recent + * @note Some of the code combinations are deprecated with recent * satellite receivers. However, this doesn't matter since the mode * is just read from the receiver. */ -#define REMOTE 0x10 -#define BOOT 0x20 - -#define TRACK ( 0x01 ) -#define AUTO_166 ( 0x02 ) -#define WARM_166 ( 0x03 | BOOT ) -#define COLD_166 ( 0x04 | BOOT ) -#define AUTO_BC ( 0x05 | REMOTE ) -#define WARM_BC ( 0x06 | REMOTE | BOOT ) -#define COLD_BC ( 0x07 | REMOTE | BOOT ) -#define UPDA_166 ( 0x08 | BOOT ) -#define UPDA_BC ( 0x09 | REMOTE | BOOT ) +enum RECEIVER_MODES +{ + TRACK = ( 0x01 ), + AUTO_166 = ( 0x02 ), + WARM_166 = ( 0x03 | BOOT ), + COLD_166 = ( 0x04 | BOOT ), + AUTO_BC = ( 0x05 | REMOTE ), + WARM_BC = ( 0x06 | REMOTE | BOOT ), + COLD_BC = ( 0x07 | REMOTE | BOOT ), + UPDA_166 = ( 0x08 | BOOT ), + UPDA_BC = ( 0x09 | REMOTE | BOOT ) +}; typedef int16_t DAC_VAL; #define _mbg_swab_dac_val( _p ) \ - _mbg_swab16( _p ); + _mbg_swab16( _p ) @@ -5232,21 +10590,23 @@ typedef int16_t DAC_VAL; */ typedef struct { - uint16_t mode; /**< Mode of operation, see predefined codes */ - uint16_t good_svs; /**< Numb. of satellites that can currently be received and used */ - uint16_t svs_in_view; /**< Numb. of satellites that should be in view according to the almanac data */ - DAC_VAL dac_val; /**< Oscillator fine DAC value */ - DAC_VAL dac_cal; /**< Oscillator calibration DAC value ( see #OSC_DAC_RANGE, #OSC_DAC_BIAS ) */ + uint16_t mode; ///< Mode of operation, see ::RECEIVER_MODES + uint16_t good_svs; ///< Numb. of satellites that can currently be received and used + uint16_t svs_in_view; ///< Numb. of satellites that should be visible above the horizon + DAC_VAL dac_val; ///< Oscillator fine DAC value + DAC_VAL dac_cal; ///< Oscillator calibration DAC value ( see ::OSC_DAC_RANGE, ::OSC_DAC_BIAS ) + } STAT_INFO; #define _mbg_swab_stat_info( _p ) \ +do \ { \ _mbg_swab16( &(_p)->mode ); \ _mbg_swab16( &(_p)->good_svs ); \ _mbg_swab16( &(_p)->svs_in_view ); \ _mbg_swab_dac_val( &(_p)->dac_val ); \ _mbg_swab_dac_val( &(_p)->dac_cal ); \ -} +} while ( 0 ) #define OSC_DAC_RANGE 4096UL @@ -5256,6 +10616,9 @@ typedef struct /** * @brief An enumeration of known satellite navigation systems + * + * @see ::MBG_GNSS_TYPE_MASKS + * @see ::GNSS_TYPE_STRS */ enum MBG_GNSS_TYPES { @@ -5263,89 +10626,362 @@ enum MBG_GNSS_TYPES GNSS_TYPE_GLONASS, ///< GLONASS, Russia GNSS_TYPE_BEIDOU, ///< BEIDOU, China GNSS_TYPE_GALILEO, ///< GALILEO, Europe + GNSS_TYPE_WAAS, ///< WAAS, Wide Area Augmentation System + GNSS_TYPE_EGNOS, ///< EGNOS, European Geostationary Navigation Overlay Service + GNSS_TYPE_QZSS, ///< QZSS, Quasi Zenith Satellite System N_GNSS_TYPES ///< Number of defined codes }; + +/** + * @brief Bit masks associated with ::MBG_GNSS_TYPES + * + * @see ::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 +}; + + +/** + * @brief Name strings for the the known satellite navigation systems + * + * @see ::MBG_GNSS_TYPES + */ #define GNSS_TYPE_STRS \ { \ "GPS", \ "GLONASS", \ - "BEIDOU" , \ - "GALILEO" \ + "BEIDOU", \ + "GALILEO", \ + "WAAS", \ + "EGNOS", \ + "QZSS" \ } -#define MBG_GNSS_TYPE_MSK_GPS ( 1UL << GNSS_TYPE_GPS ) -#define MBG_GNSS_TYPE_MSK_GLONASS ( 1UL << GNSS_TYPE_GLONASS ) -#define MBG_GNSS_TYPE_MSK_BEIDOU ( 1UL << GNSS_TYPE_BEIDOU ) -#define MBG_GNSS_TYPE_MSK_GALILEO ( 1UL << GNSS_TYPE_GALILEO ) - #define N_GNSS_MODE_PRIO 8 +/** + * @brief GNSS mode settings + * + * @see ::MBG_GNSS_TYPES + */ typedef struct { - uint32_t gnss_set; /**< current set of GNSS types */ - uint8_t prio[N_GNSS_MODE_PRIO]; /**< index 0 for highest priority, use GNSS enumeration above, init with 0xFF if not supported */ - uint32_t flags; /**< see below */ + uint32_t gnss_set; ///< bit mask of currently used GNSS systems, see ::MBG_GNSS_TYPE_MASKS + uint8_t prio[N_GNSS_MODE_PRIO]; ///< see ::MBG_GNSS_TYPES, unused fields set to 0xFF, idx 0 is highest prio + uint32_t flags; ///< unused, currently always 0 (should be named MBG_GNSS_MODE_SETTINGS_FLAG_MASKS) + } MBG_GNSS_MODE_SETTINGS; #define _mbg_swab_mbg_gnss_mode_settings( _p ) \ +do \ { \ _mbg_swab32( &(_p)->gnss_set ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) typedef struct { - MBG_GNSS_MODE_SETTINGS settings; /**< current GNSS mode settings */ - uint32_t supp_gnss_types; /**< bit masks of supported GNSS types */ - uint32_t flags; /**< indicates which of the defined flags are supported by the device */ + MBG_GNSS_MODE_SETTINGS settings; ///< Current GNSS mode settings + uint32_t supp_gnss_types; ///< Bit masks of supported GNSS types, see ::MBG_GNSS_TYPE_MASKS + uint16_t flags; ///< See ::MBG_GNSS_MODE_INFO_FLAG_MASKS + uint16_t n_sv_status; ///< Number of ::GNSS_SV_STATUS_IDX structures that can be read (only if ::MBG_GNSS_FLAG_MSK_HAS_SV_STATUS) + } MBG_GNSS_MODE_INFO; #define _mbg_swab_mbg_gnss_mode_info( _p ) \ +do \ { \ _mbg_swab_mbg_gnss_mode_settings( &(_p)->settings ); \ _mbg_swab32( &(_p)->supp_gnss_types ); \ - _mbg_swab32( &(_p)->flags ); \ -} + _mbg_swab16( &(_p)->flags ); \ + _mbg_swab16( &(_p)->n_sv_status ); \ +} while ( 0 ) + /** - * @brief Flags used with MBG_GNSS_MODE_SETTINGS::flags and MBG_GNSS_MODE_INFO::flags + * @brief Flag bits used to define ::MBG_GNSS_MODE_INFO_FLAG_MASKS + * + * @see ::MBG_GNSS_MODE_INFO_FLAG_MASKS */ -enum MBG_GNSS_MODE_FLAG_BITS +enum MBG_GNSS_MODE_INFO_FLAG_BITS { - MBG_GNSS_FLAG_EXCLUSIVE, ///< (read only) only one of the supported GNSS systems can be used at the same time - MBG_GNSS_FLAG_HAS_PRIORITY, ///< (read only) priority can be configured using the MBG_GNSS_MODE_SETTINGS::prio field + MBG_GNSS_FLAG_EXCLUSIVE, ///< Only one of the supported GNSS systems can be used at the same time + 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 N_MBG_GNSS_FLAGS }; -#define MBG_GNSS_FLAG_MSK_EXCLUSIVE ( 1UL << MBG_GNSS_FLAG_EXCLUSIVE ) -#define MBG_GNSS_FLAG_MSK_HAS_PRIORITY ( 1UL << MBG_GNSS_FLAG_HAS_PRIORITY ) +/** + * @brief Flag masks used with ::MBG_GNSS_MODE_INFO::flags + * + * @see ::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 +}; -#define MAX_USED_SATS 32 + +#define MAX_USED_SATS 32 /** - * @brief SV information from a certain GNSS type. + * @brief Satellite information for a particular GNSS type. */ typedef struct { - uint8_t gnss_type; /**< GNSS type from the enumeration above */ - uint8_t reserved; - uint16_t good_svs; - uint16_t svs_in_view; - uint8_t svs[MAX_USED_SATS]; + uint8_t gnss_type; ///< GNSS type as enumerated in ::MBG_GNSS_TYPES + uint8_t reserved; ///< Reserved, currently always 0 + uint16_t good_svs; ///< Num. of satellites that can currently be received and used + uint16_t svs_in_view; ///< Num. of satellites that should be visible above the horizon + uint8_t svs[MAX_USED_SATS]; ///< IDs of the satellites actually used for navigation, 0 == not used + } GNSS_SAT_INFO; #define _mbg_swab_gnss_sat_info( _p ) \ +do \ { \ _mbg_swab16( &(_p)->good_svs ); \ _mbg_swab16( &(_p)->svs_in_view ); \ -} +} while ( 0 ) + + + +/** + * @brief One of several sets of satellite information for a particular GNSS type. + * + * + */ +typedef struct +{ + /// 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_SAT_INFO gnss_sat_info; ///< see ::GNSS_SAT_INFO + +} GNSS_SAT_INFO_IDX; + +#define _mbg_swab_gnss_sat_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_gnss_sat_info( &(_p)->gnss_sat_info ); \ +} while ( 0 ) + + + +/** + * @defgroup group_gnss_sv_status GNSS Satellite Status + * + * @note These structures and associated types are only supported by a device + * if ::MBG_GNSS_FLAG_MSK_HAS_SV_STATUS is set // ::FIXME + * + * @{ */ + +/** + * @brief Detailed GNSS satellite status + * + * @see ::GNSS_SV_STATUS_IDX + * @see @ref group_gnss_sv_stat_flags + */ +typedef struct +{ + uint8_t gnss_type; ///< GNSS type as enumerated in ::MBG_GNSS_TYPES + uint8_t svno; ///< Satellite number, see ::TODO + uint8_t cn_ratio; ///< Carrier-to-noise ratio [dbHz] + int8_t elev; ///< Elevation [deg], range: -90..90 deg + + int16_t azim; ///< Azimuth [deg], range: 0..360 deg + int16_t pr_residual; ///< Pseudo range residual [m] + + uint32_t stat_flags; ///< see @ref group_gnss_sv_stat_flags + +} GNSS_SV_STATUS; + +#define _mbg_swab_gnss_sv_status( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->gnss_type ); \ + _mbg_swab8( &(_p)->svno ); \ + _mbg_swab8( &(_p)->cn_ratio ); \ + _mbg_swab8( &(_p)->elev ); \ + _mbg_swab16( &(_p)->azim ); \ + _mbg_swab16( &(_p)->pr_residual ); \ + _mbg_swab32( &(_p)->stat_flags ); \ +} while ( 0 ) + + + +/** + * @defgroup group_gnss_sv_stat_flags GNSS status flags encoding + * + * Used with ::GNSS_SV_STATUS::stat_flags. + * + * @{ */ + +/// Bits 0 to 2 are a 3 bit quality indicator, see ::GNSS_SV_STAT_QUALITY_INDS +#define _gnss_sv_stat_quality_ind( __stat_flags ) \ + ( (uint8_t) ( (__stat_flags) & 0x00000007UL ) ) + +/// Bit 3 is set if the SV is actually used for navigation +#define _gnss_sv_stat_sv_used( __stat_flags ) \ + ( ( (__stat_flags) & 0x00000008UL ) != 0 ) + +/// Bits 4 and 5 are a 2 bit health code, see ::GNSS_SV_STAT_HEALTH_CODES +#define _gnss_sv_stat_health_code( __stat_flags ) \ + ( (uint8_t) ( ( (__stat_flags) & 0x00000030UL ) >> 4 ) ) + +/// Bit 6 is set if differential correction is available for this SV +#define _gnss_sv_stat_diff_corr( __stat_flags ) \ + ( ( (__stat_flags) & 0x00000040UL ) != 0 ) + +/// Bit 7 is set if carrier smoothed pseudorange is used for this SV +#define _gnss_sv_stat_smoothed( __stat_flags ) \ + ( ( (__stat_flags) & 0x00000080UL ) != 0 ) + +/// Bits 8 to 10 are a 3 bit code indicating the orbit source, see ::GNSS_SV_STAT_ORBIT_SOURCES +#define _gnss_sv_stat_orbit_src( __stat_flags ) \ + ( (uint8_t) ( ( (__stat_flags) & 0x00000700UL ) >> 8 ) ) + +/// Bit 11 is set if ephemeris parameters are available for this SV +#define _gnss_sv_stat_eph_avail( __stat_flags ) \ + ( ( (__stat_flags) & 0x00000800UL ) != 0 ) + +/// Bit 12 is set if almanac parameters are available for this SV +#define _gnss_sv_stat_alm_avail( __stat_flags ) \ + ( ( (__stat_flags) & 0x00001000UL ) != 0 ) + +/// Bit 13 is set if AssistNow Offline data is available for this SV +#define _gnss_sv_stat_ano_avail( __stat_flags ) \ + ( ( (__stat_flags) & 0x00002000UL ) != 0 ) + +/// Bit 14 is set if AssistNow Autonomous data is available for this SV +#define _gnss_sv_stat_aop_avail( __stat_flags ) \ + ( ( (__stat_flags) & 0x00004000UL ) != 0 ) + +/// Bit 15 is reserved. + +/// Bit 16 is set if SBAS corrections have been used for this SV +#define _gnss_sv_stat_sbas_corr_used( __stat_flags ) \ + ( ( (__stat_flags) & 0x00010000UL ) != 0 ) + +/// Bit 17 is set if RTCM corrections have been used for this SV +#define _gnss_sv_stat_rtcm_corr_used( __stat_flags ) \ + ( ( (__stat_flags) & 0x00020000UL ) != 0 ) + +/// Bits 18 and 19 are reserved. + +/// Bit 20 is set if pseudorange corrections have been used for this SV +#define _gnss_sv_stat_pr_corr_used( __stat_flags ) \ + ( ( (__stat_flags) & 0x00100000UL ) != 0 ) + +/// Bit 21 is set if carrier range corrections have been used for this SV +#define _gnss_sv_stat_cr_corr_used( __stat_flags ) \ + ( ( (__stat_flags) & 0x00200000UL ) != 0 ) + +/// Bit 22 is set if range rate (doppler) corrections have been used for this SV +#define _gnss_sv_stat_do_corr_used( __stat_flags ) \ + ( ( (__stat_flags) & 0x00400000UL ) != 0 ) + +/// Bits 23 to 31 are reserved. + +/** @} defgroup group_gnss_sv_stat_flags */ + + +/** + * @brief Quality indicators used with ::GNSS_SV_STATUS::stat_flags + * + * @see ::_gnss_sv_stat_quality_ind + */ +enum GNSS_SV_STAT_QUALITY_INDS +{ + GNSS_SV_STAT_NO_SIGNAL, ///< No signal + GNSS_SV_STAT_SEARCHING, ///< Searching signal + GNSS_SV_STAT_ACQUIRED, ///< Signal acquired + GNSS_SV_STAT_UNUSABLE, ///< Signal detected but unusable + GNSS_SV_STAT_CODE_LOCKED, ///< Code locked and time synchronized + GNSS_SV_STAT_CODE_CARRIER_LOCKED, ///< Code and carrier locked, and time synchronized + GNSS_SV_STAT_CODE_CARRIER_LOCKED_2, ///< Code and carrier locked, and time synchronized + GNSS_SV_STAT_CODE_CARRIER_LOCKED_3 ///< Code and carrier locked, and time synchronized +}; + + +/** + * @brief Health indicators used with ::GNSS_SV_STATUS::stat_flags + * + * @see ::_gnss_sv_stat_health_code + */ +enum GNSS_SV_STAT_HEALTH_CODES +{ + GNSS_SV_STAT_HEALTH_UNKNOWN, ///< Health status unknown + GNSS_SV_STAT_HEALTH_OK, ///< Healthy + GNSS_SV_STAT_HEALTH_NOT_OK ///< Unhealthy +}; + + +/** + * @brief Orbit source codes used with ::GNSS_SV_STATUS::stat_flags + * + * @see ::_gnss_sv_stat_orbit_src + */ +enum GNSS_SV_STAT_ORBIT_SOURCES +{ + GNSS_SV_STAT_ORBIT_SRC_UNKNOWN, ///< Orbit source unknown + GNSS_SV_STAT_ORBIT_SRC_EPH, ///< Ephemeris data used for orbit + GNSS_SV_STAT_ORBIT_SRC_ALM, ///< Almanac data used for orbit + GNSS_SV_STAT_ORBIT_SRC_ASSN_OFFL, ///< AssistNow Offline orbit is used + GNSS_SV_STAT_ORBIT_SRC_ASSN_AUTO, ///< AssistNow Autonomous orbit is used + GNSS_SV_STAT_ORBIT_OTHER_1, ///< Other orbit information is used + GNSS_SV_STAT_ORBIT_OTHER_2, ///< Other orbit information is used + GNSS_SV_STAT_ORBIT_OTHER_3 ///< Other orbit information is used +}; + + + +/** + * @brief Detailed GNSS satellite status, plus index + * + * @see ::GNSS_SV_STATUS + */ +typedef struct +{ + uint32_t idx; ///< Range 0..::MBG_GNSS_MODE_INFO::n_sv_status-1 + GNSS_SV_STATUS gnss_sv_status; + +} GNSS_SV_STATUS_IDX; + +#define _mbg_swab_gnss_sv_status_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_gnss_sv_status( &(_p)->gnss_sv_status ); \ +} while ( 0 ) + + +/** @} defgroup group_gnss_sv_status */ + #ifndef _IDENT_DEFINED @@ -5361,11 +10997,14 @@ typedef struct #endif #define _mbg_swab_ident( _p ) \ +do \ { \ int i; \ for ( i = 0; i < 4; i++ ) \ _mbg_swab32( &(_p)->lw[i] ); \ -} +} while ( 0 ) + + /** * @brief A data type used to configure the length of an antenna cable [m] @@ -5377,14 +11016,28 @@ typedef uint16_t ANT_CABLE_LEN; /** - * @defgroup group_ip4_cfg Simple configuration and status - * of an optional LAN interface. + * @defgroup group_net_cfg Network configuration stuff * - * @note This is only supported if the flag ::GPS_HAS_LAN_IP4 is set - * in RECEIVER_INFO::features. + * @{ */ + +/** + * @defgroup group_net_basic_types Basic network parameter types * * @{ */ +/** + * @brief The MAC address of a network interface + */ +typedef struct +{ + uint8_t b[6]; + +} MBG_MAC_ADDR; + +#define _mbg_swab_mbg_mac_addr( _p ) \ + _nop_macro_fnc() + + /** * @brief An IPv4 address @@ -5392,40 +11045,155 @@ typedef uint16_t ANT_CABLE_LEN; typedef uint32_t IP4_ADDR; #define _mbg_swab_ip4_addr( _p ) \ - _mbg_swab32( _p ); + _mbg_swab32( _p ) + + +/** @brief The number of bits used for an IPv6 address */ +#define IP6_ADDR_BITS 128 + +/** @brief The number of bytes used for an IPv6 address */ +#define IP6_ADDR_BYTES ( IP6_ADDR_BITS / 8 ) // == 16 /** - * @brief Settings of an IPv4 network interface + * @brief An IPv6 address */ typedef struct { - IP4_ADDR ip_addr; /**< the IP address */ - IP4_ADDR netmask; /**< the network mask */ - IP4_ADDR broad_addr; /**< the broadcast address */ - IP4_ADDR gateway; /**< the default gateway */ - uint16_t flags; /**< flags as specified below */ - uint16_t vlan_cfg; /**< VLAN configuration, see below */ + uint8_t b[IP6_ADDR_BYTES]; ///< bytes holding the address bits (not the string notation), b[0] == LSBs -} IP4_SETTINGS; +} IP6_ADDR; -#define _mbg_swab_ip4_settings( _p ) \ -{ \ - _mbg_swab_ip4_addr( &(_p)->ip_addr ); \ - _mbg_swab_ip4_addr( &(_p)->netmask ); \ - _mbg_swab_ip4_addr( &(_p)->broad_addr ); \ - _mbg_swab_ip4_addr( &(_p)->gateway ); \ - _mbg_swab16( &(_p)->flags ); \ - _mbg_swab16( &(_p)->vlan_cfg ); \ +#define _mbg_swab_ip6_addr( _p ) _nop_macro_fnc() + + + +/** + * @brief An IPv6 address plus number of netmask bits + */ +typedef struct +{ + IP6_ADDR addr; ///< bit mask of the bytes holding the address bits, b[0] == LSBs + uint8_t prefix; ///< Number of subnet mask bits for CIDR notation, e.g. 24 for /24 + uint8_t reserved[3]; ///< Reserved, alignment, currently 0 + +} IP6_ADDR_CIDR; + + + +/** @brief The max number of chars required for an IPv6 address string */ +#define MAX_IP6_ADDR_STR_LEN 43 ///< e.g. 2001:0db8:85a3:08d3:1319:8a2e:0370:7344/128 + +/** @brief Buffer size required to store an IPv6 address string */ +#define IP6_ADDR_STR_SIZE ( MAX_IP6_ADDR_STR_LEN + 1 ) ///< ::MAX_IP6_ADDR_STR_LEN + terminating 0 + +/** @brief A buffer for an IPv6 address string */ +typedef char IP6_ADDR_STR[IP6_ADDR_STR_SIZE]; + + + +/** + * @brief Possible IPv6 Multicast Scopes + * + * If the first (most significant) byte of an IPv6 address is 0xFF this + * indicates that the address is a multicast address, and in this case + * the second byte determines the scope for which the specified address + * is valid. These scope ID numbers are assigned in RFC 7346 which + * supersedes RFC 4291. + * + * @see ::IPV6_MULTICAST_SCOPE_NAME_TABLE_ENTRIES + */ +enum IPV6_MULTICAST_SCOPES +{ + IPV6_MULTICAST_SCOPE_INTF_LOCAL = 0x01, ///< Interface-Local scope + IPV6_MULTICAST_SCOPE_LINK_LOCAL, ///< Link-Local scope + IPV6_MULTICAST_SCOPE_REALM_LOCAL, ///< Realm-Local scope + IPV6_MULTICAST_SCOPE_ADMIN_LOCAL, ///< Admin-Local scope + IPV6_MULTICAST_SCOPE_SITE_LOCAL, ///< Site-Local scope + IPV6_MULTICAST_SCOPE_ORGA_LOCAL = 0x08, ///< Organization-Local scope + IPV6_MULTICAST_SCOPE_GLOBAL_SCOPE = 0x0E ///< Global scope +}; + + +/** + * @brief Name strings for IPv6 multicast scopes + * + * This can e.g. be used to initialize an array of ::MBG_CODE_NAME_TABLE_ENTRY elements. + * + * @see ::IPV6_MULTICAST_SCOPES + */ +#define IPV6_MULTICAST_SCOPE_NAME_TABLE_ENTRIES \ +{ \ + { IPV6_MULTICAST_SCOPE_INTF_LOCAL, "FF01 - Interface-Local Scope" }, \ + { IPV6_MULTICAST_SCOPE_LINK_LOCAL, "FF02 - Link-Local Scope" }, \ + { IPV6_MULTICAST_SCOPE_REALM_LOCAL, "FF03 - Realm-Local Scope" }, \ + { IPV6_MULTICAST_SCOPE_ADMIN_LOCAL, "FF04 - Admin-Local Scope" }, \ + { IPV6_MULTICAST_SCOPE_SITE_LOCAL, "FF05 - Site-Local Scope" }, \ + { IPV6_MULTICAST_SCOPE_ORGA_LOCAL, "FF08 - Organization-Local Scope" }, \ + { IPV6_MULTICAST_SCOPE_GLOBAL_SCOPE, "FF0E - Global Scope" }, \ + { 0, NULL } \ } + +/** + * @brief The maximum length of a fully qualified host/domain domain name (FQDN) + * + * In theory each single component (host name, domain name, top level domain name) + * of a FQDN can have up to 63 characters, but the overall length is limited to + * 255 characters (see RFC-1123). We specify one more character for the trailing 0. + */ +#define MBG_MAX_HOSTNAME_LEN 256 + + +/** + * @brief A buffer for a fully qualified domain name (FQDN) or a numeric IP address string + */ +typedef char MBG_HOSTNAME[MBG_MAX_HOSTNAME_LEN]; ///< ASCIIZ format + +#define _mbg_swab_mbg_host_name( _p ) _nop_macro_fnc() + + +/** @} defgroup group_net_basic_types */ + + + +/** + * @brief The maximum length of an interface name + * + * We use an extra name here for the Meinberg-specific structures + * to avoid a name clash with system definitions, e.g. Linux systems + * define IFNAMSIZ usually as 16 in linux/if.h. + */ +#define MBG_IFNAMSIZ 16 + + +/** + * @brief Hardware type for identification of physical interfaces + * + */ +enum MBG_NET_HW_TYPES +{ + MBG_NET_HW_TYPE_UNKNOWN, + MBG_ARPHRD_ETHER, + N_MBG_NET_HW_TYPES +}; + + +/** + * @defgroup group_vlan_cfg Definitions used with VLAN configuration + * + * @{ */ + /** - * @brief Definitions used with IP4_SETTINGS::vlan_cfg + * @brief VLAN configuration * - * @note IP4_SETTINGS::vlan_cfg contains a combination of - * a VLAN ID number plus a VLAN priority code. + * @note This is a combination of a VLAN ID number plus a VLAN priority code. */ +typedef uint16_t MBG_VLAN_CFG; + +#define _mbg_swab_mbg_vlan_cfg( _p ) _mbg_swab16( _p ) + #define VLAN_ID_BITS 12 ///< number of bits to hold the ID #define N_VLAN_ID ( 1 << VLAN_ID_BITS ) ///< number of ID values #define MIN_VLAN_ID 0 ///< minimum ID value @@ -5442,7 +11210,7 @@ typedef struct #define MAX_VLAN_PRIORITY ( N_VLAN_PRIORITY - 1 ) ///< maximum priority // vlan_priority = ( vlan_cfg >> VLAN_PRIORITY_SHIFT ) & VLAN_PRIORITY_MSK -#define VLAN_PRIORITY_SHIFT ( ( 8 * sizeof( uint16_t ) ) - VLAN_PRIORITY_BITS ) +#define VLAN_PRIORITY_SHIFT ( ( 8 * sizeof( MBG_VLAN_CFG ) ) - VLAN_PRIORITY_BITS ) #define VLAN_PRIORITY_MSK ( ( 1 << VLAN_PRIORITY_BITS ) - 1 ) /** @@ -5452,103 +11220,121 @@ typedef struct #define _decode_vlan_priority( _cfg ) ( ( (_cfg) >> VLAN_PRIORITY_SHIFT ) & VLAN_PRIORITY_MSK ) #define _encode_vlan_cfg( _id, _prty ) ( ( (_id) << VLAN_ID_SHIFT ) | ( (_prty) << VLAN_PRIORITY_SHIFT ) ) +/** @} defgroup group_vlan_cfg */ -#if 0 //##++ currently not used - -/* Misc configuration */ - -typedef struct -{ - uint16_t id; /* service ID, see below */ - uint16_t index; /* used if several same svcs must be cfg'd, e.g. DNS */ - char host[50]; /* see below */ - -} IP_CFG; - - - -/* Description of a service running on a device */ - -typedef struct -{ - uint16_t id; /* service ID, see below */ - uint16_t socket; /* the socket on which the service is listening */ - uint32_t flags; /* see below */ - -} IP_SERVICE; - -#endif // 0 +/** + * @defgroup group_ip4_cfg Simple IPv4-only configuration or status + * + * This is only supported if the flag ::GPS_HAS_LAN_IP4 is set + * in ::RECEIVER_INFO::features. + * @see @ref group_ext_net_cfg Extended network configuration and status + * + * @{ */ /** - * @brief A structure to holds the MAC address of a LAN interface + * @brief Settings of an IPv4-only network interface */ typedef struct { - uint8_t b[6]; -} MBG_MAC_ADDR; + IP4_ADDR ip_addr; ///< the IP address + IP4_ADDR netmask; ///< the network mask + IP4_ADDR broad_addr; ///< the broadcast address + IP4_ADDR gateway; ///< the default gateway + uint16_t flags; ///< see ::MBG_IP4_FLAG_MASKS + MBG_VLAN_CFG vlan_cfg; ///< VLAN configuration + +} IP4_SETTINGS; + +#define _mbg_swab_ip4_settings( _p ) \ +do \ +{ \ + _mbg_swab_ip4_addr( &(_p)->ip_addr ); \ + _mbg_swab_ip4_addr( &(_p)->netmask ); \ + _mbg_swab_ip4_addr( &(_p)->broad_addr ); \ + _mbg_swab_ip4_addr( &(_p)->gateway ); \ + _mbg_swab16( &(_p)->flags ); \ + _mbg_swab_mbg_vlan_cfg( &(_p)->vlan_cfg ); \ +} while ( 0 ) /** - * @brief LAN interface information + * @brief Simple LAN interface information * * This structure can be retrieved from a device * to check the device's capabilities. + * + * It is only supported if the flag ::GPS_HAS_LAN_IP4 is set + * in ::RECEIVER_INFO::features. + * + * @see @ref group_ext_net_cfg Extended network configuration and status */ typedef struct { - uint16_t type; ///< type of LAN interface, see below + uint16_t type; ///< type of LAN interface, see ::LAN_IF_TYPES MBG_MAC_ADDR mac_addr; ///< MAC address - uint16_t ver_code; ///< version number, high byte.low byte, in hex + uint16_t ver_code; ///< version number (hex) char ver_str[GPS_ID_STR_SIZE]; ///< version string char sernum[GPS_ID_STR_SIZE]; ///< serial number uint32_t rsvd_0; ///< reserved, currently always 0 - uint16_t flags; ///< flags as specified below + uint16_t flags; ///< see ::MBG_IP4_FLAG_MASKS uint16_t rsvd_1; ///< reserved, currently always 0 } LAN_IF_INFO; #define _mbg_swab_lan_if_info( _p ) \ +do \ { \ _mbg_swab16( &(_p)->type ); \ _mbg_swab16( &(_p)->ver_code ); \ _mbg_swab32( &(_p)->rsvd_0 ); \ _mbg_swab16( &(_p)->flags ); \ _mbg_swab16( &(_p)->rsvd_1 ); \ -} - +} while ( 0 ) /** - * @brief Codes used with LAN_IF_INFO::type + * @brief Codes used with ::LAN_IF_INFO::type */ enum LAN_IF_TYPES { - LAN_IF_TYPE_XPORT, ///< LAN interface on an XPORT + LAN_IF_TYPE_XPORT, ///< LAN interface on an XPORT, superseded by RSC devices LAN_IF_TYPE_PTP, ///< LAN interface is a special PTP interface + LAN_IF_TYPE_RSC, ///< RSC device, supersedes XPORT N_LAN_IF_TYPE ///< number of defined LAN interface types }; /** - * @brief Enumeration of flag bits used with IP4_SETTINGS::flags and LAN_IF_INFO::flags + * @brief Enumeration of flag bits used with ::IP4_SETTINGS::flags and ::LAN_IF_INFO::flags * - * @see MBG_IP4_FLAG_MASKS + * @see ::MBG_IP4_FLAG_MASKS */ enum MBG_IP4_FLAG_BITS { - IP4_BIT_DHCP, ///< DHCP supported (LAN_IF_INFO) / enabled (IP4_SETTINGS) - IP4_BIT_LINK, ///< used only in IP4_SETTINGS to report link state - IP4_BIT_VLAN, ///< VLAN supported (LAN_IF_INFO) / enabled (IP4_SETTINGS) - N_IP4_BIT ///< number of defined flag bits + /// In ::LAN_IF_INFO::flags this reports if DHCP is supported by the device. + /// If supported then it can also be used with ::IP4_SETTINGS::flags to enable + /// or disable DHCP for the network interface. + IP4_BIT_DHCP, + + /// Only used with ::IP4_SETTINGS::flags. Set if port link has been established. + IP4_BIT_LINK, + + /// In ::LAN_IF_INFO::flags this reports if VLAN is supported by the device. + /// If supported then it can also be used with ::IP4_SETTINGS::flags to enable + /// or disable VLAN for the network interface. + IP4_BIT_VLAN, + + N_IP4_BIT ///< number of defined flag bits }; + /** - * @brief Bit masks used with IP4_SETTINGS::flags and LAN_IF_INFO::flags + * @brief Bit masks used with ::IP4_SETTINGS::flags and ::LAN_IF_INFO::flags * - * @see MBG_IP4_FLAG_BITS + * @see ::MBG_IP4_FLAG_BITS */ enum MBG_IP4_FLAG_MASKS { @@ -5557,7 +11343,1289 @@ enum MBG_IP4_FLAG_MASKS IP4_MSK_VLAN = ( 1UL << IP4_BIT_VLAN ), ///< see ::IP4_BIT_VLAN }; -/** @} group_ip4_cfg */ +/** @} defgroup group_ip4_cfg */ + + + +/** + * @defgroup group_ext_net_cfg_types Types used for extended network configuration and status + * + * @{ */ + +/** + * @brief Enumeration of types used with ::MBG_IP_ADDR::type + */ +enum MBG_IP_ADDR_TYPES +{ + MBG_IP_ADDR_TYPE_UNKNOWN, + MBG_IP_ADDR_TYPE_IP4, + MBG_IP_ADDR_TYPE_IP6, + N_MBG_IP_ADDR_TYPES +}; + +/* + * Default initializers for English mode string names. Initializers + * for multi-language strings can be found in tmonlstr.h. + */ +#define MBG_IP_ADDR_TYPE_STR_ENG_UNKNOWN "unknown" +#define MBG_IP_ADDR_TYPE_STR_ENG_IP4 "IPv4" +#define MBG_IP_ADDR_TYPE_STR_ENG_IP6 "IPv6" + +#define MBG_IP_ADDR_TYPE_NAMES_ENG \ +{ \ + MBG_IP_ADDR_TYPE_STR_ENG_UNKNOWN, \ + MBG_IP_ADDR_TYPE_STR_ENG_IP4, \ + MBG_IP_ADDR_TYPE_STR_ENG_IP6 \ +} + + +/** + * @brief Feature flag bits used to define ::MBG_NET_GLB_CFG_INFO_MASKS + * + * @see ::MBG_NET_GLB_CFG_INFO_MASKS + */ +enum MBG_NET_GLB_CFG_INFO_FLAGS +{ + MBG_NET_GLB_SUPP_STAGE_2, ///< Supports commands which have been added in stage 2 + MBG_NET_GLB_SUPP_BONDING, ///< Supports bonding + MBG_NET_GLB_SUPP_ADD_CONF, ///< Supports additional network configuration (i.e. via script) + MBG_NET_GLB_SUPP_EXT_ROUTING, ///< Supports extended routing (multiple default gateways, routing tables) + N_MBG_NET_GLB_INFO_FLAGS +}; + + +/** + * @brief Flag masks used with ::MBG_NET_GLB_CFG_INFO::feat_flags + * + * @see ::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 +}; + + + +/** + * @brief Network interface link speed mode enumeration + * + * @see @ref MBG_NET_INTF_LINK_SPEED_MODE_MASKS + */ +enum MBG_NET_INTF_LINK_SPEED_MODES +{ + MBG_NET_INTF_LINK_SPEED_MODE_UNKNOWN, ///< Unknown speed mode + MBG_NET_INTF_LINK_SPEED_MODE_10_T_HALF, ///< 10baseT Half Duplex (10 MBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_10_T_FULL, ///< 10baseT Full Duplex (10 MBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_100_T_HALF, ///< 100baseT Half Duplex (100 MBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_100_T_FULL, ///< 100baseT Full Duplex (100 MBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_1000_T_HALF, ///< 1000baseT Half Duplex (1 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_1000_T_FULL, ///< 1000baseT Full Duplex (1 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_1000_KX_FULL, ///< 1000baseKX Full Duplex (1 GBit/s) + + MBG_NET_INTF_LINK_SPEED_MODE_2500_X_FULL, ///< 2500baseX Full Duplex (2.5 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_10000_T_FULL, ///< 10000baseT Full Duplex (10 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_10000_KX4_FULL, ///< 10000baseKX4 Full Duplex (10 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_10000_KR_FULL, ///< 10000baseKR Full Duplex (10 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_10000_R_FEC, ///< 10000baseR FEC (forward error correction) (10 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_20000_MLD2_FULL, ///< 20000baseMLD2 Full Duplex (20 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_20000_KR2_FULL, ///< 20000baseKR2 Full Duplex (20 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_40000_KR4_FULL, ///< 40000baseKR4 Full Duplex (40 GBit/s) + + MBG_NET_INTF_LINK_SPEED_MODE_40000_CR4_FULL, ///< 40000baseCR4 Full Duplex (40 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_40000_SR4_FULL, ///< 40000baseSR4 Full Duplex (40 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_40000_LR4_FULL, ///< 40000baseLR4 Full Duplex (40 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_56000_KR4_FULL, ///< 56000baseKR4 Full Duplex (56 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_56000_CR4_FULL, ///< 56000baseCR4 Full Duplex (56 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_56000_SR4_FULL, ///< 56000baseSR4 Full Duplex (56 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_56000_LR4_FULL, ///< 56000baseLR4 Full Duplex (56 GBit/s) + + N_MBG_NET_INTF_LINK_SPEED_MODES +}; + + + +/** + * @brief Network interface link speed mode masks + * + * @see ::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 + +/** @} anchor MBG_NET_INTF_LINK_SPEED_MODE_MASKS */ + + + +/** + * @brief Network interface link speeds [Mb/s] + * + * @see @ref MBG_NET_INTF_LINK_SPEED_MODE_MASKS + */ +enum MBG_NET_INTF_LINK_SPEEDS +{ + MBG_NET_INTF_LINK_SPEED_UNKNOWN = 0UL, + MBG_NET_INTF_LINK_SPEED_10 = 10UL, + MBG_NET_INTF_LINK_SPEED_100 = 100UL, + MBG_NET_INTF_LINK_SPEED_1000 = 1000UL, + MBG_NET_INTF_LINK_SPEED_2500 = 2500UL, + MBG_NET_INTF_LINK_SPEED_10000 = 10000UL, + MBG_NET_INTF_LINK_SPEED_20000 = 20000UL, + MBG_NET_INTF_LINK_SPEED_40000 = 40000UL, + MBG_NET_INTF_LINK_SPEED_56000 = 56000UL +}; + + + +/** + * @brief Network interface link port types + * + * @see ::MBG_NET_INTF_LINK_PORT_TYPE_MASKS + */ +enum MBG_NET_INTF_LINK_PORT_TYPES +{ + MBG_NET_INTF_LINK_PORT_TYPE_UNKNOWN, ///< Unknown port type + MBG_NET_INTF_LINK_PORT_TYPE_TP, ///< Twisted Pair (TP) copper cable + MBG_NET_INTF_LINK_PORT_TYPE_FIBRE, ///< Fibre Optic (FO) cable + MBG_NET_INTF_LINK_PORT_TYPE_BNC, ///< Coaxial BNC cable + MBG_NET_INTF_LINK_PORT_TYPE_AUI, ///< Attachment Unit Interface (AUI), externel transceiver + MBG_NET_INTF_LINK_PORT_TYPE_MII, ///< Media Independent Interface (MII), external receiver + MBG_NET_INTF_LINK_PORT_TYPE_DA, ///< Direct attach SFP+ connection + N_MBG_NET_INTF_LINK_PORT_TYPES +}; + + + +/** + * @brief Network interface link port masks + * + * @see ::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 +}; + + + +/** + * @brief Initializers for network interface link port type long strings + * + * @see ::MBG_NET_INTF_LINK_PORT_TYPES + */ +#define MBG_NET_INTF_LINK_PORT_TYPE_LONG_STRS \ +{ \ + "Unknown", \ + "Twisted Pair", \ + "Fibre Optic", \ + "Coaxial BNC", \ + "Attachment Unit Interface", \ + "Media Independent Interface", \ + "Direct Attach SFP+" \ +} + + +/** + * @brief Initializers for network interface link port type short strings + * + * @see ::MBG_NET_INTF_LINK_PORT_TYPES + */ +#define MBG_NET_INTF_LINK_PORT_TYPE_SHORT_STRS \ +{ \ + "Unknown", \ + "TP", \ + "FO", \ + "BNC", \ + "AUI", \ + "MII", \ + "DA" \ +} + + + +/** + * @brief Network interface link state bits + * + * @see @ref MBG_NET_INTF_LINK_STATE_MASKS + * + * @note See official Linux kernel documentation + * https://www.kernel.org/doc/Documentation/networking/operstates.txt + * for states below and explanations. Windows supports this in nearly the same way + * using similar names struct IP_ADAPTER_ADDRESSES which is explained at + * http://msdn.microsoft.com/en-us/library/windows/desktop/aa366058%28v=vs.85%29.aspx + */ +enum MBG_NET_INTF_LINK_STATE_BITS +{ + MBG_NET_INTF_LINK_STATE_BIT_UP, + MBG_NET_INTF_LINK_STATE_BIT_RUNNING, + MBG_NET_INTF_LINK_STATE_BIT_LOWER_UP, + MBG_NET_INTF_LINK_STATE_BIT_DORMANT, + MBG_NET_INTF_LINK_STATE_BIT_BROADCAST, + MBG_NET_INTF_LINK_STATE_BIT_MULTICAST, + MBG_NET_INTF_LINK_STATE_BIT_ALL_MULTI, + MBG_NET_INTF_LINK_STATE_BIT_DEBUG, + + MBG_NET_INTF_LINK_STATE_BIT_LOOPBACK, + MBG_NET_INTF_LINK_STATE_BIT_POINT_TO_POINT, + MBG_NET_INTF_LINK_STATE_BIT_NO_ARP, + MBG_NET_INTF_LINK_STATE_BIT_PROMISC, + MBG_NET_INTF_LINK_STATE_BIT_MASTER, + MBG_NET_INTF_LINK_STATE_BIT_SLAVE, + MBG_NET_INTF_LINK_STATE_BIT_PORT_SEL, + MBG_NET_INTF_LINK_STATE_BIT_AUTO_MEDIA, + + MBG_NET_INTF_LINK_STATE_BIT_ECHO, + MBG_NET_INTF_LINK_STATE_BIT_DYNAMIC, + MBG_NET_INTF_LINK_STATE_BIT_NO_TRAILERS, + + N_MBG_NET_INTF_LINK_STATE_BITS +}; + + + +/** + * @brief Network interface link state masks + * + * @see ::MBG_NET_INTF_LINK_STATE_BITS (reclined to Linux' if.h, Windows is similiar) + * + * @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 + +/** @} anchor MBG_NET_INTF_LINK_STATE_MASKS */ + + + +/** + * @brief Network interface link option bits + * + * @see ::MBG_NET_INTF_LINK_OPT_MASKS + */ +enum MBG_NET_INTF_LINK_OPTS +{ + MBG_NET_INTF_LINK_OPT_CAN_SET_MAC, + MBG_NET_INTF_LINK_OPT_CAN_SYNCE_IN, + MBG_NET_INTF_LINK_OPT_CAN_SYNCE_OUT, + 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, + N_MBG_NET_INTF_LINK_OPTS +}; + + + +/** + * @brief Network interface link option masks + * + * @see ::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 +}; + + + +/** + * @brief Network interface link bonding mode + * + * Used with ::MBG_NET_INTF_LINK_SETTINGS::bond_mode + * + * @note if_bonding.h contains bonding modes under Linux, found no hint under Windows. + * BUT: Something similiar (concerning naming) can be configured under Windows + * via GUI in device manager, if supported. + */ +enum MBG_NET_INTF_LINK_BOND_MODES +{ + MBG_NET_INTF_LINK_BOND_MODE_ROUNDROBIN, + MBG_NET_INTF_LINK_BOND_MODE_ACTIVEBACKUP, + MBG_NET_INTF_LINK_BOND_MODE_XOR, + MBG_NET_INTF_LINK_BOND_MODE_BROADCAST, + MBG_NET_INTF_LINK_BOND_MODE_8023AD, + MBG_NET_INTF_LINK_BOND_MODE_TLB, + MBG_NET_INTF_LINK_BOND_MODE_ALB, + N_MBG_NET_INTF_LINK_BOND_MODES +}; + + + +/** + * @brief Network interface link bonding mode masks + * + * @see ::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 +}; + + + +/** + * @brief Network interface link bonding mode name strings + * + * @see ::MBG_NET_INTF_LINK_BOND_MODES + */ +#define MBG_NET_INTF_LINK_BOND_MODE_STRS \ +{ \ + "Round Robin", \ + "Active Backup", \ + "XOR", \ + "Broadcast", \ + "802.3ad (LACP)", \ + "TLB", \ + "ALB" \ +} + + + +/** + * @brief Network interface link bonding states + * + * Used with ::MBG_NET_INTF_LINK_SETTINGS::bond_state + */ +enum MBG_NET_INTF_LINK_BOND_STATES +{ + MBG_NET_INTF_LINK_BOND_STATE_ACTIVE, + MBG_NET_INTF_LINK_BOND_STATE_BACKUP, + N_MBG_NET_INTF_LINK_BOND_STATES +}; + + +/** + * @brief Network interface link type bits + * + * Used with ::MBG_NET_INTF_LINK_SETTINGS::type + * + * @see ::MBG_NET_INTF_LINK_TYPE_MASKS + */ +enum MBG_NET_INTF_LINK_TYPES +{ + MBG_NET_INTF_LINK_TYPE_PHYS, ///< Real physical network interface + MBG_NET_INTF_LINK_TYPE_VLAN, ///< VLAN interface, assigned to physical interface + MBG_NET_INTF_LINK_TYPE_BOND, ///< Bonding interface, which acts as bonding master + N_MBG_NET_INTF_LINK_TYPE_BITS +}; + + +/** + * @brief Network interface link type masks + * + * Used with ::MBG_NET_INTF_LINK_INFO::supp_types + * + * @see ::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 +}; + + +/** + * @brief Network interface address bits + * + * @see ::MBG_NET_INTF_ADDR_MASKS + * + * Used with ::MBG_NET_INTF_ADDR_INFO::supp_flags and ::MBG_NET_INTF_ADDR_SETTINGS::flags + */ +enum MBG_NET_INTF_ADDR_BITS +{ + MBG_NET_INTF_ADDR_BIT_DHCP4, ///< Address has been automatically assigned by DHCP via IPv4 + MBG_NET_INTF_ADDR_BIT_DHCP6, ///< Address has been automatically assigned by DHCP via IPv6 + MBG_NET_INTF_ADDR_BIT_AUTOCONF, ///< Address is an autoconf address, which should be ignored in the configuration + N_MBG_NET_INTF_ADDR_FLAGS +}; + + + +/** + * @brief Network interface address masks + * + * @see ::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 +}; + + +enum MBG_NET_INTF_ROUTE_TYPES +{ + MBG_NET_INTF_ROUTE_TYPE_UNKNOWN, + MBG_NET_INTF_ROUTE_TYPE_DEFAULT_GATEWAY, + MBG_NET_INTF_ROUTE_TYPE_DEST_GATEWAY, + MBG_NET_INTF_ROUTE_TYPE_DEST_ADDR, + N_MBG_NET_INTF_ROUTE_TYPES +}; + +/** @} defgroup group_ext_net_cfg_types */ + + + +/** + * @defgroup group_ext_net_cfg Extended network configuration and status + * + * This is only supported if the flag ::GPS_HAS_NET_CFG is set + * in ::RECEIVER_INFO::features. + * + * @{ */ + +/** + * @brief Global network configuration settings + */ +typedef struct +{ + MBG_HOSTNAME hostname; ///< hostname, eventually FQDN including domain name + + uint8_t num_intf_link; ///< number of detected/configured physical network interfaces (links), see ::MBG_NET_INTF_LINK_INFO_IDX + uint8_t num_intf_addr; ///< number of configured interface addresses, see ::MBG_NET_INTF_ADDR_INFO_IDX + uint8_t num_dns_srvr; ///< number of configured DNS servers, see ::MBG_IP_ADDR_IDX + uint8_t num_dns_srch_dom; ///< number of configured DNS search domains, see ::MBG_NET_NAME_IDX + uint8_t num_intf_route; ///< number of configured interface routes, see ::MBG_NET_INTF_ROUTE_INFO_IDX + + uint8_t reserved; ///< currently reserved, always 0 + uint16_t flags; ///< currently reserved, always 0 + +} MBG_NET_GLB_CFG_SETTINGS; + +#define _mbg_swab_net_glb_cfg_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + +/** + * @brief Global current network settings and supported features + */ +typedef struct +{ + MBG_NET_GLB_CFG_SETTINGS glb_settings; + uint16_t n_supp_intf_link; ///< max. number of supported physical network interfaces (links), see ::MBG_NET_INTF_LINK_SETTINGS_IDX, ::MBG_NET_INTF_LINK_INFO_IDX + uint16_t n_supp_intf_addr; ///< max. number of supported interface addresses, see ::MBG_NET_INTF_ADDR_SETTINGS_IDX, ::MBG_NET_INTF_ADDR_INFO_IDX + uint16_t n_supp_dns_srvr; ///< max. number of supported DNS server addresses, using ::MBG_IP_ADDR_IDX records + uint16_t n_supp_dns_srch_dom; ///< max. number of supported DNS search domain records, using ::MBG_NET_NAME_IDX records + uint16_t n_supp_intf_route; ///< max. number of supported interface routes, see ::MBG_NET_INTF_ROUTE_SETTINGS_IDX, ::MBG_NET_INTF_ROUTE_INFO_IDX + uint16_t max_hostname_len; ///< max. length of hostname including trailing 0; if set to 0, max. length is 256 (see rfc1123) + uint32_t reserved_1; ///< currently reserved, always 0 + uint32_t reserved_2; ///< currently reserved, always 0 + uint32_t feat_flags; ///< Feature flags, see ::MBG_NET_GLB_CFG_INFO_MASKS + uint32_t flags_2; ///< currently reserved, always 0 + +} MBG_NET_GLB_CFG_INFO; + +#define _mbg_swab_net_glb_cfg_info( _p ) \ +do \ +{ \ + _mbg_swab_net_glb_cfg_settings( &(_p)->glb_settings ); \ + _mbg_swab16( &(_p)->n_supp_intf_link ); \ + _mbg_swab16( &(_p)->n_supp_intf_addr ); \ + _mbg_swab16( &(_p)->n_supp_dns_srvr ); \ + _mbg_swab16( &(_p)->n_supp_dns_srch_dom ); \ + _mbg_swab16( &(_p)->n_supp_intf_route ); \ + _mbg_swab16( &(_p)->max_hostname_len ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->feat_flags ); \ + _mbg_swab32( &(_p)->flags_2 ); \ +} while ( 0 ) + + + +/** + * @brief An IPv4 or IPv6 network address + */ +typedef struct +{ + uint8_t type; ///< see ::MBG_IP_ADDR_TYPES + uint8_t reserved_1; ///< reserved, currently always 0 @todo Do we need this as scope indicator? + uint16_t reserved_2; ///< reserved, currently always 0 + + union u_addr + { + IP4_ADDR ip4_addr; ///< IPv4 address if ::MBG_IP_ADDR::type == MBG_IP_ADDR_TYPE_IP4 + IP6_ADDR ip6_addr; ///< IPv6 address if ::MBG_IP_ADDR::type == MBG_IP_ADDR_TYPE_IP6 + } u_addr; + +} MBG_IP_ADDR; + +#define _mbg_swab_ip_addr( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->type ); \ + _mbg_swab8( &(_p)->reserved_1 ); \ + _mbg_swab16( &(_p)->reserved_2 ); \ + \ + switch ( (_p)->type ) \ + { \ + case MBG_IP_ADDR_TYPE_IP4: \ + _mbg_swab_ip4_addr( &(_p)->u_addr.ip4_addr ); \ + break; \ + \ + case MBG_IP_ADDR_TYPE_IP6: \ + _mbg_swab_ip6_addr( &(_p)->u_addr.ip6_addr ); \ + break; \ + } \ + \ +} while ( 0 ) + + + +/** + * @brief An IPv4 or IPv6 network address, plus index + */ +typedef struct +{ + uint16_t idx; + MBG_IP_ADDR addr; ///< network address + +} MBG_IP_ADDR_IDX; + +#define _mbg_swab_ip_addr_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_ip_addr( &(_p)->addr ); \ +} while ( 0 ) + + +/** + * @brief An IPv4 or IPv6 network address plus UDP or TCP port number + */ +typedef struct +{ + MBG_IP_ADDR addr; ///< see ::MBG_IP_ADDR + + uint16_t port; ///< UDP or TCP port + uint16_t flags; ///< currently always 0 + //##+++++ TODO should the flags field indicate if the port is UDP and/or TCP? + +} MBG_IP_ADDR_PORT; + +#define _mbg_swab_ip_addr_port( _p ) \ +do \ +{ \ + _mbg_swab_ip_addr( &(_p)->addr ); \ + _mbg_swab16( &(_p)->port ); \ + _mbg_swab16( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Network host or domain name + */ +typedef struct +{ + MBG_HOSTNAME name; + +} MBG_NET_NAME; + +#define _mbg_swab_net_name( _p ) \ +do \ +{ \ + _mbg_swab_mbg_host_name( &(_p)->name ); \ +} while ( 0 ) + + + +/** + * @brief Network host or domain name, plus index + */ +typedef struct +{ + uint16_t idx; + MBG_NET_NAME net_name; + +} MBG_NET_NAME_IDX; + +#define _mbg_swab_net_name_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_net_name( &(_p)->net_name ); \ +} while ( 0 ) + + + +/** + * @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 + + 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 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 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 + + uint32_t reserved_2; ///< Reserved, currently 0 + uint32_t reserved_3; ///< Reserved, currently 0 + +} MBG_NET_INTF_LINK_SETTINGS; + +#define _mbg_swab_net_intf_link_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->if_index ); \ + _mbg_swab32( &(_p)->common_if_index ); \ + _mbg_swab32( &(_p)->ass_if_index ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->states ); \ + _mbg_swab32( &(_p)->hw_type ); \ + _mbg_swab32( &(_p)->mtu ); \ + _mbg_swab32( &(_p)->txqlen ); \ + _mbg_swab32( &(_p)->speed ); \ + _mbg_swab16( &(_p)->bond_idx ); \ + _mbg_swab16( &(_p)->vlan_cfg ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) + + + +/** + * @brief Link (physical interface) specific settings, plus index + */ +typedef struct +{ + uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_INFO::n_supp_intf_link-1 + MBG_NET_INTF_LINK_SETTINGS settings; + +} MBG_NET_INTF_LINK_SETTINGS_IDX; + +#define _mbg_swab_net_intf_link_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_net_intf_link_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +/** + * @brief Link (physical interface) specific settings, flags and supported features + */ +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 + 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_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_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ +} while ( 0 ) + + + +/** + * @brief Query MBG_NET_INTF_LINK_INFO by its index + */ +typedef struct +{ + 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_NET_INTF_LINK_INFO_IDX; + +#define _mbg_swab_net_intf_link_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_net_intf_link_info( &(_p)->info ); \ +} while ( 0 ) + + +/** + * @brief Network interface address specific settings, flags and supported features + * + * @note Use if_index to identify uniquely its associated network link. + */ +typedef struct +{ + char label[MBG_IFNAMSIZ]; ///< Interface label + + 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 + + MBG_IP_ADDR ip; ///< IP address associated with this interface + MBG_IP_ADDR broadcast; ///< Broadcast address associated with this interface + + uint8_t prefix_bits; ///< Number of subnet mask bits for CIDR notation, e.g. 24 for /24 + uint8_t reserved_1; ///< Reserved, currently 0 + uint16_t reserved_2; ///< Reserved, currently 0 + + uint32_t reserved_3; ///< Reserved, currently 0 + uint32_t reserved_4; ///< Reserved, currently 0 + uint32_t reserved_5; ///< Reserved, currently 0 + +} MBG_NET_INTF_ADDR_SETTINGS; + +#define _mbg_swab_net_intf_addr_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->addr_index ); \ + _mbg_swab32( &(_p)->ass_if_index ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab_ip_addr( &(_p)->ip ); \ + _mbg_swab_ip_addr( &(_p)->broadcast ); \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ + _mbg_swab32( &(_p)->reserved_5 ); \ +} while ( 0 ) + + +/** + * @brief Query MBG_NET_INTF_ADDR_SETTINGS by its index + */ +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_NET_INTF_ADDR_SETTINGS_IDX; + +#define _mbg_swab_net_intf_addr_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_net_intf_addr_settings( &(_p)->settings ); \ +} while ( 0 ) + + +/** + * @brief Network interface address specific settings, flags and supported features + */ +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 + uint32_t reserved_1; ///< Reserved, currently 0 + uint32_t reserved_2; ///< Reserved, currently 0 + +} MBG_NET_INTF_ADDR_INFO; + +#define _mbg_swab_net_intf_addr_info( _p ) \ +do \ +{ \ + _mbg_swab_net_intf_addr_settings( &(_p)->addr_settings ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) + + +/** + * @brief Query MBG_NET_INTF_ADDR_INFO by its index + */ +typedef struct +{ + 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_NET_INTF_ADDR_INFO_IDX; + +#define _mbg_swab_net_intf_addr_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_net_intf_addr_info( &(_p)->info ); \ +} while ( 0 ) + + +/** + * @brief Network interface route specific settings + * + * @note Use link_mac and ass_addr_idx to identify the associated network address and network link (via address) + */ +typedef struct +{ + uint8_t type; ///< Type of the route entry, see ::MBG_NET_INTF_ROUTE_TYPES + uint8_t reserved_1; ///< Reserved, currently 0 + uint16_t reserved_2; ///< Reserved, currently 0 + + MBG_IP_ADDR gateway; ///< Gateway IP address, only used if type is + ///< ::MBG_NET_INTF_ROUTE_TYPE_DEFAULT_GATEWAY or ::MBG_NET_INTF_ROUTE_TYPE_DEST_GATEWAY + MBG_IP_ADDR dst; ///< Destination IP address, only used if ::MBG_NET_INTF_ROUTE_SETTINGS::type is + ///< ::MBG_NET_INTF_ROUTE_TYPE_DEST_GATEWAY or ::MBG_NET_INTF_ROUTE_TYPE_DEST_ADDR + uint8_t dst_prefix_bits; ///< Prefix Bits for the destination address + + uint32_t ass_if_index; ///< Index of the associated interface link, see ::MBG_NET_INTF_LINK_SETTINGS::if_index + uint32_t ass_addr_index; ///< Index of the associated interface address, see ::MBG_NET_INTF_ADDR_SETTINGS::addr_index, + ///< Valid if ::MBG_NET_INTF_ROUTE_SETTINGS::type is ::MBG_NET_INTF_ROUTE_TYPE_DEST_GATEWAY or ::MBG_NET_INTF_ROUTE_TYPE_DEST_ADDR + + uint32_t reserved_3; ///< Reserved, currently 0 + uint32_t reserved_4; ///< Reserved, currently 0 + uint32_t reserved_5; ///< Reserved, currently 0 + +} MBG_NET_INTF_ROUTE_SETTINGS; + +#define _mbg_swab_net_intf_route_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab_ip_addr( &(_p)->gateway ); \ + _mbg_swab_ip_addr( &(_p)->dst ); \ + _mbg_swab32( &(_p)->ass_if_index ); \ + _mbg_swab32( &(_p)->ass_addr_index ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ + _mbg_swab32( &(_p)->reserved_5 ); \ +} while ( 0 ) + + +/** + * @brief Query MBG_NET_INTF_ROUTE_SETTINGS by its index + */ +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_NET_INTF_ROUTE_SETTINGS_IDX; + +#define _mbg_swab_net_intf_route_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_net_intf_route_settings( &(_p)->settings ); \ +} while ( 0 ) + + +/** + * @brief Network interface address specific settings + */ +typedef struct +{ + 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 + uint32_t reserved_4; ///< Reserved, currently 0 +} MBG_NET_INTF_ROUTE_INFO; + +#define _mbg_swab_net_intf_route_info( _p ) \ +do \ +{ \ + _mbg_swab_net_intf_route_settings( &(_p)->route_settings ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ +} while ( 0 ) + + +/** + * @brief Query MBG_NET_INTF_ROUTE_INFO by its index + */ +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_NET_INTF_ROUTE_INFO_IDX; + +#define _mbg_swab_net_intf_route_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_net_intf_route_info( &(_p)->info ); \ +} while ( 0 ) + + +/** @} defgroup group_ext_net_cfg */ + +/** @} defgroup group_net_cfg */ + + + + + +/** + * @defgroup group_ucap_net User Captures via Network + * + * @note Group for the user capture via network feature + * Only supported if ::MBG_XFEATURE_UCAP_NET is set in extended features + * Corresponding GPS commands are ::GPS_UCAP_NET_GLB_INFO and ::GPS_UCAP_NET_RECV_INFO_IDX + * + * @{ */ + + +#define MBG_UCAP_NET_DEFAULT_UDP_PORT 50815 + +/** + * @brief Transfer mode for user captures via network + * + * @see ::MBG_UCAP_NET_TRANSF_MODE_MASKS + * + * Used with ::MBG_UCAP_NET_RECV_SETTINGS::mode + */ +enum MBG_UCAP_NET_TRANSF_MODE +{ + MBG_UCAP_NET_TRANSF_MODE_UNKNOWN, ///< Unknown transfer mode + MBG_UCAP_NET_TRANSF_MODE_ON_REQ, ///< User captures will be transferred on request only + MBG_UCAP_NET_TRANSF_MODE_AUTO, ///< User captures are being transferred automatically + N_MBG_UCAP_NET_TRANSF_MODES +}; + + +/** + * @brief Masks for transfer mode used with ::MBG_UCAP_NET_GLB_INFO::supp_modes + * + * @see ::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 +}; + + + +/** + * @brief Transfer protocol for user captures via network + * + * @see ::MBG_UCAP_NET_TRANSF_PROTO_MASKS + * + * Used with ::MBG_UCAP_NET_RECV_SETTINGS::proto + */ +enum MBG_UCAP_NET_TRANSF_PROTO +{ + MBG_UCAP_NET_TRANSF_PROTO_UNKNOWN, ///< Unknown transfer mode + MBG_UCAP_NET_TRANSF_PROTO_UDP, ///< User captures are transferred via UDP + N_MBG_UCAP_NET_TRANSF_PROTOS +}; + + +/** + * @brief Masks for transfer protocol used with ::MBG_UCAP_NET_GLB_INFO::supp_protos + * + * @see ::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 +}; + + + +/** + * @brief Supported flags for user captures via network + * + * @see ::MBG_UCAP_NET_SUPP_FLAG_MASKS + */ +enum MBG_UCAP_NET_SUPP_FLAGS +{ + MBG_UCAP_NET_SUPP_FLAG_IPV6, + N_MBG_UCAP_NET_SUPP_FLAGS +}; + + +/** + * @brief Masks for supported flags used with ::MBG_UCAP_NET_GLB_INFO::supp_flags + * + * @see ::MBG_UCAP_NET_TRANSF_PROTO + */ +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 +}; + + +/** + * @brief Global settings for user captures via network + * + * @note This structure shall be used to set the current global settings of a device + * with GPS command ::GPS_UCAP_NET_GLB_INFO. + */ +typedef struct +{ + uint32_t num_recvs; ///< Number of configured network receivers, see ::MBG_UCAP_NET_RECV_INFO_IDX + 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_UCAP_NET_GLB_SETTINGS; + + +#define _mbg_swab_ucap_net_glb_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->num_recvs ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) + + + +/** + * @brief Global settings, features and flags for user captures via network + * + * @note This structure shall be used to read the current global settings from a device + * with GPS command ::GPS_UCAP_NET_GLB_INFO. + */ +typedef struct +{ + 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 + uint32_t supp_protos; ///< Supported transfer protocols, see ::MBG_UCAP_NET_TRANSF_PROTO_MASKS + uint32_t reserved_0; ///< Reserved, currently always 0 + uint32_t reserved_1; ///< Reserved, currently always 0 + uint32_t supp_flags; ///< Supported flags, see ::MBG_UCAP_NET_SUPP_FLAG_MASKS + +} MBG_UCAP_NET_GLB_INFO; + + +#define _mbg_swab_ucap_net_glb_info( _p ) \ +do \ +{ \ + _mbg_swab_ucap_net_glb_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->n_supp_recvs ); \ + _mbg_swab32( &(_p)->supp_modes ); \ + _mbg_swab32( &(_p)->supp_protos ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + + +/** + * @brief Settings for receivers of user captures via network + */ +typedef struct +{ + uint8_t mode; ///< Transfer mode, see ::MBG_UCAP_NET_TRANSF_MODE + uint8_t proto; ///< Transfer protocol, see ::MBG_UCAP_NET_TRANSF_PROTO + uint16_t reserved_1; ///< Reserved, currently always 0 + + uint32_t reserved_2; ///< Reserved, currently always 0 + uint32_t reserved_3; ///< Reserved, currently always 0 + uint32_t ucaps; ///< Bit mask for active user captures + + MBG_IP_ADDR_PORT addr; ///< Destination IP and port address of the network receiver, see ::MBG_IP_ADDR_PORT + +} MBG_UCAP_NET_RECV_SETTINGS; + + +#define _mbg_swab_ucap_net_recv_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->ucaps ); \ + _mbg_swab_ip_addr_port( &(_p)->addr ); \ +} while ( 0 ) + + + +/** + * @brief Settings for receivers of user captures via network + * + * @note This structure shall be used to write the settings to the device + * with GPS command ::GPS_UCAP_NET_RECV_INFO_IDX. + * This can be done for index 0 to ::MBG_UCAP_NET_GLB_SETTINGS::num_recvs-1. + * + * @see ::MBG_UCAP_NET_RECV_SETTINGS + */ +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_UCAP_NET_RECV_SETTINGS_IDX; + + +#define _mbg_swab_ucap_net_recv_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_ucap_net_recv_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +/** + * @brief Settings, features and flags for receivers of user captures via network + */ +typedef struct +{ + 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 + uint32_t reserved_2; ///< Reserved, currently always 0 + uint32_t reserved_3; ///< Reserved, currently always 0 + +} MBG_UCAP_NET_RECV_INFO; + + +#define _mbg_swab_ucap_net_recv_info( _p ) \ +do \ +{ \ + _mbg_swab_ucap_net_recv_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) + + + +/** + * @brief Settings, features and flags for receivers of user captures via network + * + * @note This structure shall be used to read the current settings from the device + * with GPS command ::GPS_UCAP_NET_RECV_INFO_IDX. + * This can be done for index 0 to ::MBG_UCAP_NET_GLB_SETTINGS::num_recvs-1. + * + * @see ::MBG_UCAP_NET_RECV_INFO + */ +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_UCAP_NET_RECV_INFO_IDX; + + +#define _mbg_swab_ucap_net_recv_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_ucap_net_recv_info( &(_p)->info ); \ +} while ( 0 ) + +/** @} defgroup ext_ucap */ @@ -5569,7 +12637,7 @@ enum MBG_IP4_FLAG_MASKS /** * @brief Enumeration of protocols possibly used with PTP * - * @see PTP_NW_PROT_MASKS + * @see ::PTP_NW_PROT_MASKS */ enum PTP_NW_PROTS { @@ -5587,7 +12655,7 @@ enum PTP_NW_PROTS /** * @brief Bit masks for enumerated protocols possibly used with PTP * - * @see PTP_NW_PROTS + * @see ::PTP_NW_PROTS */ enum PTP_NW_PROT_MASKS { @@ -5605,7 +12673,7 @@ enum PTP_NW_PROT_MASKS /** * @brief Name strings for the protocols possibly used with PTP * - * @see PTP_NW_PROTS + * @see ::PTP_NW_PROTS */ #define PTP_NW_PROT_STRS \ { \ @@ -5622,7 +12690,7 @@ enum PTP_NW_PROT_MASKS /** * @brief Short name strings for the protocols possibly used with PTP * - * @see PTP_NW_PROTS + * @see ::PTP_NW_PROTS */ #define PTP_NW_PROT_STRS_SHORT \ { \ @@ -5680,6 +12748,7 @@ typedef struct { uint8_t value; ///< the parameter value const char *name; ///< the parameter name + } PTP_TABLE; @@ -5691,8 +12760,8 @@ typedef struct * in the published specs for IEEE1588. In addition, the specs * define code 0x14 for "disabled". * - * @see PTP_DELAY_MECH_MASKS - * @see PTP_DELAY_MECH_NAMES + * @see ::PTP_DELAY_MECH_MASKS + * @see ::PTP_DELAY_MECH_NAMES */ enum PTP_DELAY_MECHS { @@ -5703,14 +12772,14 @@ enum PTP_DELAY_MECHS /** - * @brief Bit masks associated to enumerated PTP delay mechanisms + * @brief Bit masks associated with enumerated PTP delay mechanisms * - * @see PTP_DELAY_MECH_MASKS + * @see ::PTP_DELAY_MECH_MASKS */ enum PTP_DELAY_MECH_MASKS { PTP_DELAY_MECH_MSK_E2E = ( 1UL << PTP_DELAY_MECH_E2E ), ///< see ::PTP_DELAY_MECH_E2E - PTP_DELAY_MECH_MSK_P2P = ( 1UL << PTP_DELAY_MECH_E2E ) ///< see ::PTP_DELAY_MECH_E2E + PTP_DELAY_MECH_MSK_P2P = ( 1UL << PTP_DELAY_MECH_P2P ) ///< see ::PTP_DELAY_MECH_P2P }; @@ -5720,7 +12789,7 @@ enum PTP_DELAY_MECH_MASKS /** * @brief Name strings for the PTP delay mechanisms * - * @see PTP_DELAY_MECHS + * @see ::PTP_DELAY_MECHS */ #define PTP_DELAY_MECH_NAMES \ { \ @@ -5736,7 +12805,7 @@ enum PTP_DELAY_MECH_MASKS * @note This enumeration does not start at 0 but with a bias * specified by ::PTP_CLOCK_ACCURACY_NUM_BIAS. * - * @see PTP_CLOCK_ACCURACY_STRS + * @see ::PTP_CLOCK_ACCURACY_STRS */ enum PTP_CLOCK_ACCURACIES { @@ -5764,6 +12833,8 @@ enum PTP_CLOCK_ACCURACIES PTP_CLOCK_ACCURACY_RESERVED_3, PTP_CLOCK_ACCURACY_RESERVED_4, N_PTP_CLOCK_ACCURACY + //##++++ TODO: Add a code for 0xFE (unknown), or eventually + // redesign the lookup of associated strings completely. }; @@ -5774,7 +12845,7 @@ enum PTP_CLOCK_ACCURACIES * specified by ::PTP_CLOCK_ACCURACY_NUM_BIAS, so this bias needs * to be accounted for when accessing a string table. * - * @see PTP_CLOCK_ACCURACIES + * @see ::PTP_CLOCK_ACCURACIES */ #define PTP_CLOCK_ACCURACY_STRS \ { \ @@ -5807,7 +12878,7 @@ enum PTP_CLOCK_ACCURACIES /** * @brief Codes to specify the type of a time source used with PTP * - * @see PTP_TIME_SOURCE_TABLE + * @see ::PTP_TIME_SOURCE_TABLE */ enum PTP_TIME_SOURCES { @@ -5826,7 +12897,7 @@ enum PTP_TIME_SOURCES /** * @brief A table of PTP time source codes plus associated name strings * - * @see PTP_TIME_SOURCES + * @see ::PTP_TIME_SOURCES */ #define PTP_TIME_SOURCE_TABLE \ { \ @@ -5845,12 +12916,17 @@ enum PTP_TIME_SOURCES /** * @brief An enumeration of roles which can be taken by a PTP node * - * @note A role in this context specifies a certain mode of operation. + * A role in this context specifies a certain mode of operation. * Depending on its specification a devices may not be able to take * each of the specified roles. * - * @see PTP_ROLE_STRS - * @see PTP_ROLE_STRS_SHORT + * @note: A device in MULTICAST_AUTO role can be either master or slave, + * so the port state needs to be checked to determine the current + * mode of operation. + * + * @see ::PTP_ROLE_MASKS + * @see ::PTP_ROLE_STRS + * @see ::PTP_ROLE_STRS_SHORT */ enum PTP_ROLES { @@ -5859,24 +12935,61 @@ enum PTP_ROLES PTP_ROLE_MULTICAST_MASTER, ///< multicast master PTP_ROLE_UNICAST_MASTER, ///< unicast master PTP_ROLE_MULTICAST_AUTO, ///< multicast master or slave (auto selection) + PTP_ROLE_BOTH_MASTER, ///< simultanous multicast and unicast master + PTP_ROLE_NTP_SERVER, ///< NTP Unicast Server + PTP_ROLE_NTP_CLIENT, ///< NTP Unicast Client + PTP_ROLE_TIME_MONITOR, ///< Net Sync Monitor for external PTP or NTP devices + PTP_ROLE_V1_MASTER, ///< PTPv1 Master in Multicast mode + PTP_ROLE_V1_SLAVE, ///< PTPv1 Slave in Multicast mode N_PTP_ROLES ///< number of defined roles }; -#define PTP_ROLE_MSK_MULTICAST_SLAVE ( 1UL << PTP_ROLE_MULTICAST_SLAVE ) -#define PTP_ROLE_MSK_UNICAST_SLAVE ( 1UL << PTP_ROLE_UNICAST_SLAVE ) -#define PTP_ROLE_MSK_MULTICAST_MASTER ( 1UL << PTP_ROLE_MULTICAST_MASTER ) -#define PTP_ROLE_MSK_UNICAST_MASTER ( 1UL << PTP_ROLE_UNICAST_MASTER ) -#define PTP_ROLE_MSK_MULTICAST_AUTO ( 1UL << PTP_ROLE_MULTICAST_AUTO ) -#define PTP_ROLE_MSK_SLAVES ( PTP_ROLE_MSK_MULTICAST_SLAVE | PTP_ROLE_MSK_UNICAST_SLAVE ) -#define PTP_ROLE_MSK_MASTERS ( PTP_ROLE_MSK_MULTICAST_MASTER | PTP_ROLE_MSK_UNICAST_MASTER ) +/** + * @brief Bit mask associated with ::PTP_ROLES + * + * A role in this context specifies a certain mode of operation. + * Depending on its specification a devices may not be able to take + * each of the specified roles. + * + * @note: A device in MULTICAST_AUTO role can be either master or slave, + * so the port state needs to be checked to determine the current + * mode of operation. + * + * @see ::PTP_ROLES + * @see ::get_supp_ptp_role_mask + */ +enum 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 +}; + + +#define PTP_ROLE_MSK_SLAVES ( PTP_ROLE_MSK_MULTICAST_SLAVE \ + | PTP_ROLE_MSK_UNICAST_SLAVE \ + | PTP_ROLE_MSK_MULTICAST_AUTO ) + +#define PTP_ROLE_MSK_MASTERS ( PTP_ROLE_MSK_MULTICAST_MASTER \ + | PTP_ROLE_MSK_UNICAST_MASTER \ + | PTP_ROLE_MSK_MULTICAST_AUTO \ + | PTP_ROLE_BOTH_MASTER ) /** * @brief Name strings for defined PTP roles * - * @see PTP_ROLES - * @see PTP_ROLE_STRS_SHORT + * @see ::PTP_ROLES + * @see ::PTP_ROLE_STRS_SHORT */ #define PTP_ROLE_STRS \ { \ @@ -5884,15 +12997,21 @@ enum PTP_ROLES "Unicast Slave", \ "Multicast Master", \ "Unicast Master", \ - "Multicast (Auto)" \ + "Multicast (Auto)", \ + "UC+MC Master", \ + "NTP Server", \ + "NTP Client", \ + "Sync Monitor", \ + "V1 Master", \ + "V1 Slave" \ } /** * @brief Short name strings for defined PTP roles * - * @see PTP_ROLES - * @see PTP_ROLE_STRS + * @see ::PTP_ROLES + * @see ::PTP_ROLE_STRS */ #define PTP_ROLE_STRS_SHORT \ { \ @@ -5900,7 +13019,13 @@ enum PTP_ROLES "UCS", \ "MCM", \ "UCM", \ - "MC" \ + "MCA", \ + "UMM", \ + "NSV", \ + "NCL", \ + "MON", \ + "V1M", \ + "V1S" \ } @@ -5913,6 +13038,7 @@ enum PTP_ROLES typedef struct { uint8_t b[8]; + } PTP_CLOCK_ID; #define _mbg_swab_ptp_clock_id( _p ) _nop_macro_fnc() // nothing to swap @@ -5922,9 +13048,6 @@ typedef struct /** * @brief A PTP port ID - * - * @note This usually consists of a 6 byte MAC address with - * 2 fixed bytes inserted, or all ones as wildcard. */ typedef uint16_t PTP_PORT_ID; @@ -5934,6 +13057,70 @@ typedef uint16_t PTP_PORT_ID; /** + * @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_CLOCK_ID clock_identity; + PTP_PORT_ID port_number; + +} PTP_PORT_IDENTITY; + + +#define _mbg_swab_ptp_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 + */ +typedef struct +{ + uint8_t clock_class; ///< PTP clock class representing the current sync status + int8_t clock_accuracy; ///< see ::PTP_CLOCK_ACCURACIES + uint16_t log_variance; ///< PTP offset scaled log variance representing the time stability + +} PTP_CLOCK_QUALITY; + + +#define _mbg_swab_ptp_clock_quality( _p ) \ +{ \ + _mbg_swab8( &(_p)->clock_class ); \ + _mbg_swab8( &(_p)->clock_accuracy ); \ + _mbg_swab16( &(_p)->log_variance ); \ +} + + +/** + * @brief PTP time interval + * + * @note For further information, see IEEE 1588-2008, chapter 5.3.2 + * + */ +typedef struct +{ + int64_t scaled_nanoseconds; + +} PTP_TIME_INTERVAL; + + +#define _mbg_swab_ptp_time_interval( _p ) \ +{ \ + _mbg_swab64( &(_p)->scaled_nanoseconds ); \ +} + + +/** * @brief An enumeration of time scales used with PTP * * @note The standard time scale used by PTP is TAI, which is a linear time scale. @@ -5941,8 +13128,8 @@ typedef uint16_t PTP_PORT_ID; * can observe leap seconds. For the arbitrary time scale the %UTC offset is unspecified, * so arbitrary time can be %UTC, or something else. * - * @see PTP_TIMESCALE_NAMES - * @see PTP_TIMESCALE_NAMES_SHORT + * @see ::PTP_TIMESCALE_NAMES + * @see ::PTP_TIMESCALE_NAMES_SHORT */ enum PTP_TIME_SCALES { @@ -5968,8 +13155,8 @@ enum PTP_TIME_SCALES /** * @brief A table of name strings for the PTP time scales * - * @see PTP_TIME_SCALES - * @see PTP_TIMESCALE_NAMES_SHORT + * @see ::PTP_TIME_SCALES + * @see ::PTP_TIMESCALE_NAMES_SHORT */ #define PTP_TIMESCALE_NAMES \ { \ @@ -5980,8 +13167,8 @@ enum PTP_TIME_SCALES /** * @brief A table of short name strings for the PTP time scales * - * @see PTP_TIME_SCALES - * @see PTP_TIMESCALE_NAMES + * @see ::PTP_TIME_SCALES + * @see ::PTP_TIMESCALE_NAMES */ #define PTP_TIMESCALE_NAMES_SHORT \ { \ @@ -6011,7 +13198,7 @@ typedef struct uint8_t clock_class; uint8_t clock_accuracy; ///< see ::PTP_CLOCK_ACCURACIES - uint32_t reserved_1; ///< reserved, currently always 0 + 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 @@ -6022,11 +13209,15 @@ typedef struct int16_t utc_offset; ///< %UTC offset observed against TAI DAC_VAL osc_dac_cal; ///< disciplination value of the oscillator - uint32_t reserved_3; ///< reserved, currently always 0 + uint8_t parent_clock_class; ///< clock class of the parent node + uint8_t parent_clock_accuracy; ///< clock accuracy of the parent node, see ::PTP_CLOCK_ACCURACIES + + uint16_t reserved_3; ///< reserved, currently always 0 } PTP_STATE; #define _mbg_swab_ptp_state( _p ) \ +do \ { \ _mbg_swab16( &(_p)->nw_prot ); \ _mbg_swab32( &(_p)->flags ); \ @@ -6036,18 +13227,18 @@ typedef struct _mbg_swab_nano_time( &(_p)->delay_asymmetry ); \ _mbg_swab_ptp_clock_id( &(_p)->gm_id ); \ _mbg_swab16( &(_p)->clock_offset_scaled_log_variance ); \ - _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->tsu_secs ); \ _mbg_swab32( &(_p)->reserved_2 ); \ _mbg_swab16( &(_p)->utc_offset ); \ _mbg_swab_dac_val( &(_p)->osc_dac_cal ); \ - _mbg_swab32( &(_p)->reserved_3 ); \ -} + _mbg_swab16( &(_p)->reserved_3 ); \ +} while ( 0 ) /** * @brief Flags bits used with PTP_STATE::flags * - * @see PTP_STATE_FLAG_MASKS + * @see ::PTP_STATE_FLAG_MASKS */ enum PTP_STATE_FLAGS { @@ -6058,13 +13249,14 @@ enum PTP_STATE_FLAGS PTP_FLAG_LS_ANN_NEG, ///< the announced leap second is negative PTP_FLAG_IS_UNICAST, ///< the port currently operates in unicast mode PTP_FLAG_UTC_VALID, ///< %UTC parameters are valid + PTP_FLAG_ONE_STEP, ///< One-Step Clock active N_PTP_STATE_FLAGS ///< the number of defined flag bits }; /** * @brief Flags masks used with PTP_STATE::flags * - * @see PTP_STATE_FLAGS + * @see ::PTP_STATE_FLAGS */ enum PTP_STATE_FLAG_MASKS { @@ -6074,7 +13266,8 @@ enum PTP_STATE_FLAG_MASKS 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_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 }; @@ -6085,7 +13278,7 @@ enum PTP_STATE_FLAG_MASKS typedef struct { uint16_t nw_prot; ///< see ::PTP_NW_PROTS - uint8_t profile; ///< PTP profile, currently only 0 = default + 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 @@ -6099,7 +13292,7 @@ typedef struct uint8_t dflt_clk_class_sync_warm; // 6:255 uint8_t ann_rcpt_timeout; ///< announce msg. receipt timeout, see ::PTP_ANN_RCPT_TIMEOUT_LIMITS - uint8_t reserved_1; ///< reserved, currently always 0 + uint8_t opt_ext; ///< optional configuration extension, see ::PTP_OPT_EXTS int16_t sync_intv; ///< log2 of the sync interval [s] int16_t ann_intv; ///< log2 of the announce interval [s] @@ -6108,22 +13301,26 @@ typedef struct uint32_t upper_bound; ///< sync state set to false if above this limit [ns] uint32_t lower_bound; ///< sync state set to true if below this limit [ns] - uint32_t reserved_2; ///< reserved, currently always 0 - uint32_t flags; ///< see ::PTP_CFG_FLAGS + int16_t delay_asymmetry; ///< static delay asymmetry [ns] to be compensated, only supported if + ///< ::PTP_CFG_MSK_HAS_DELAY_ASYMMETRY_CFG is set in ::PTP_CFG_INFO::supp_flags_ex + uint16_t flags_ex; ///< see @ref PTP_CFG_FLAG_EX_MASKS + uint32_t flags; ///< see @ref PTP_CFG_FLAG_MASKS } PTP_CFG_SETTINGS; -#define _mbg_swab_ptp_cfg_settings( _p ) \ -{ \ - _mbg_swab16( &(_p)->nw_prot ); \ - _mbg_swab16( &(_p)->sync_intv ); \ - _mbg_swab16( &(_p)->ann_intv ); \ - _mbg_swab16( &(_p)->delay_req_intv ); \ - _mbg_swab32( &(_p)->upper_bound ); \ - _mbg_swab32( &(_p)->lower_bound ); \ - _mbg_swab32( &(_p)->reserved_3 ); \ - _mbg_swab32( &(_p)->flags ); \ -} +#define _mbg_swab_ptp_cfg_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->nw_prot ); \ + _mbg_swab16( &(_p)->sync_intv ); \ + _mbg_swab16( &(_p)->ann_intv ); \ + _mbg_swab16( &(_p)->delay_req_intv ); \ + _mbg_swab32( &(_p)->upper_bound ); \ + _mbg_swab32( &(_p)->lower_bound ); \ + _mbg_swab16( &(_p)->delay_asymmetry ); \ + _mbg_swab16( &(_p)->flags_ex ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) @@ -6133,7 +13330,7 @@ typedef struct enum PTP_ANN_RCPT_TIMEOUT_LIMITS { PTP_ANN_RCPT_TIMEOUT_MIN = 2, - PTP_ANN_RCPT_TIMEOUT_MAX = 255, + PTP_ANN_RCPT_TIMEOUT_MAX = 8, DEFAULT_PTP_ANN_RCPT_TIMEOUT = 3 }; @@ -6148,7 +13345,7 @@ typedef struct uint8_t ptp_proto_version; ///< PTP protocol version, 1, or 2, usually 2 for v2 uint8_t reserved_1; ///< reserved, currently always 0 - uint16_t reserved_2; ///< reserved, currently always 0 + uint16_t supp_flags_ex; ///< A bit mask of extended supported features, see @ref PTP_CFG_FLAG_EX_MASKS int16_t sync_intv_min; ///< log2 of minimum sync interval [s] int16_t sync_intv_max; ///< log2 of maximum sync interval [s] @@ -6157,17 +13354,18 @@ typedef struct int16_t delay_req_intv_min; ///< log2 of minimum delay request interval [s] int16_t delay_req_intv_max; ///< log2 of maximum delay request interval [s] - uint32_t supp_flags; ///< a bit mask of supported features, see ::PTP_CFG_FLAGS - uint32_t supp_nw_prot; ///< a bit mask of supported network protocols, see ::PTP_NW_PROTS - uint32_t supp_profiles; ///< a bit mask of supported profiles, see ::PTP_PROFILES - uint32_t supp_delay_mech; ///< a bit mask of supported delay mechanisms, see ::PTP_DELAY_MECHS + uint32_t supp_flags; ///< a bit mask of supported features, see @ref PTP_CFG_FLAG_MASKS + uint32_t supp_nw_prot; ///< a bit mask of supported network protocols, see ::PTP_NW_PROT_MASKS + uint32_t supp_opt_ext; ///< a bit mask of supported optional extensions, see ::PTP_OPT_EXT_MASKS + uint32_t supp_delay_mech; ///< a bit mask of supported delay mechanisms, see ::PTP_DELAY_MECH_MASKS } PTP_CFG_INFO; #define _mbg_swab_ptp_cfg_info( _p ) \ +do \ { \ _mbg_swab_ptp_cfg_settings( &(_p)->settings ); \ - _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab16( &(_p)->supp_flags_ex ); \ _mbg_swab16( &(_p)->sync_intv_min ); \ _mbg_swab16( &(_p)->sync_intv_max ); \ _mbg_swab16( &(_p)->ann_intv_min ); \ @@ -6176,111 +13374,330 @@ typedef struct _mbg_swab16( &(_p)->delay_req_intv_max ); \ _mbg_swab32( &(_p)->supp_flags ); \ _mbg_swab32( &(_p)->supp_nw_prot ); \ - _mbg_swab32( &(_p)->supp_profiles ); \ + _mbg_swab32( &(_p)->supp_opt_ext ); \ _mbg_swab32( &(_p)->supp_delay_mech ); \ -} +} while ( 0 ) /** - * @brief Flags used with PTP_CFG_SETTINGS::flags and PTP_CFG_INFO::supp_flags + * @brief Flags bits used with PTP configuration + * + * Flags labeled [R/-] can only be used with ::PTP_CFG_INFO::supp_flags + * to indicate that the associated feature is supported in general. * - * @see PTP_CFG_FLAG_MASKS + * If a flag labeled [R/W] is set in ::PTP_CFG_INFO::supp_flags then + * this flag can also be used with ::PTP_CFG_SETTINGS::flags to control + * the associated feature. + * + * @note Originally, all devices supported the multicast slave role, so + * there was no extra flag to indicate this. However, some newer devices + * may not support the multicast slave role, so two new flags have been + * introduced to cope with this: + * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is set then a different flag + * ::PTP_CFG_CAN_BE_MULTICAST_SLAVE needs to be checked to tell if + * the multicast slave role is supported, or not. + * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is not set then the device + * definitely supports the multicast slave role. + * + * @see @ref PTP_CFG_FLAG_MASKS */ enum PTP_CFG_FLAGS { - PTP_CFG_TIME_SCALE_IS_PTP, ///< time scale is PTP/TAI, else arbitrary - PTP_CFG_V1_HW_COMPAT, ///< maybe required for certain NIC chips, not used by Meinberg - PTP_CFG_CAN_BE_UNICAST_SLAVE, ///< the PTP port can take the role of a unicast slave - PTP_CFG_CAN_BE_MULTICAST_MASTER, ///< the PTP port can take the role of a multicast master - PTP_CFG_CAN_BE_UNICAST_MASTER, ///< the PTP port can take the role of a unicast master - PTP_CFG_CAN_BE_MULTICAST_AUTO, ///< the PTP port can automatically become multicast master or slave - PTP_CFG_SUPP_UTC_VALID, ///< %UTC valid bit in PTP_STATE::flags is supported + PTP_CFG_TIME_SCALE_IS_PTP, ///< [R/W] time scale is PTP/TAI, else arbitrary + PTP_CFG_V1_HW_COMPAT, ///< [R/W] maybe required for certain NIC chips, not used by Meinberg + PTP_CFG_CAN_BE_UNICAST_SLAVE, ///< [R/-] supports unicast slave role, see ::PTP_ROLE_UNICAST_SLAVE + PTP_CFG_CAN_BE_MULTICAST_MASTER, ///< [R/-] supports multicast master role, see ::PTP_ROLE_MULTICAST_MASTER + PTP_CFG_CAN_BE_UNICAST_MASTER, ///< [R/-] supports unicast master, see ::PTP_ROLE_UNICAST_MASTER + PTP_CFG_CAN_BE_MULTICAST_AUTO, ///< [R/-] can automatically become multicast master or slave, see ::PTP_CFG_CAN_BE_MULTICAST_AUTO + PTP_CFG_SUPP_UTC_VALID, ///< [R/-] ::PTP_FLAG_UTC_VALID bit in ::PTP_STATE::flags is supported + PTP_CFG_CAN_BE_BOTH_MASTER, ///< [R/-] supports unicast and multicast master role at the same time, see ::PTP_CFG_CAN_BE_BOTH_MASTER + + PTP_CFG_HYBRID_MASTER, ///< [R/W] supports hybrid mode in master roles + PTP_CFG_HYBRID_SLAVE, ///< [R/W] supports hybrid mode in slave roles + PTP_CFG_ONE_STEP_MASTER, ///< [R/W] supports one-step mode in master roles + PTP_CFG_MNGMNT_MSGS_DISB, ///< [R/W] supports disabling of PTP management messages + PTP_CFG_SUPP_MCAST_SLAVE_FLAG, ///< [R/-] indicates that ::PTP_CFG_CAN_BE_MULTICAST_SLAVE flag is supported and can be checked + PTP_CFG_CAN_BE_MULTICAST_SLAVE, ///< [R/-] if ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG bit set, indicates if multicast slave role is supported + PTP_CFG_ONE_STEP_L2, ///< [R/-] supports the combination of One-Step and Layer2 mode + PTP_CFG_ONE_STEP_P2P, ///< [R/-] supports the combination of One-Step and P2P Delay Mechanism + + PTP_CFG_TSU_RESET, ///< [R/-] supports TSU reset via register cmd + PTP_CFG_NTP_HW_TS_MASTER, ///< [R/-] supports the NTP HW time stamping in Master mode + PTP_CFG_NTP_HW_TS_SLAVE, ///< [R/-] supports the NTP HW time stamping in Slave mode + PTP_CFG_SYNCE_MASTER, ///< [R/-] Hardware supports Synchronous Ethernet Out + PTP_CFG_SYNCE_SLAVE, ///< [R/-] Hardware supports Synchronous Ethernet In + PTP_CFG_HAS_MUX, ///< [R/-] Hardware supports multiplexed signal outputs + PTP_CFG_CAN_BE_TIME_MONITOR, ///< [R/-] can be Monitoring device for external PTP or NTP devices //### TODO Shouldn't this be an XFEATURE flag? + PTP_CFG_HAS_STATISTICS, ///< [R/-] ::MBG_PTP_STATISTICS_INFO can be queried + + PTP_CFG_CAN_BE_V1_MASTER, ///< [R/-] supports PTPv1 MASTER role + PTP_CFG_CAN_BE_V1_SLAVE, ///< [R/-] supports PTPv1 SLAVE role + PTP_CFG_HAS_V2_COMMON_DATASETS, ///< [R/-] PTPv2 common dataset structures (see IEEE1588-2008, chapter 8.2) can be queried + PTP_CFG_HAS_V1_COMMON_DATASETS, ///< [R/-] PTPv1 common dataset structures can be queried + PTP_CFG_ATOI, ///< [R/-] supports the configurable usage of the Alternate Time Offset Indicator TLV + PTP_CFG_HAS_SMPTE_TLV_STATE, ///< [R/-] SMPTE TLV structure can be queried in slave state + PTP_CFG_NTP_SW_SERVER, ///< [R/W] PTP Module can run as NTP Server in Software mode in parallel to PTP HW time stamp modes + PTP_CFG_HAS_EXT_SUPP_FLAGS, ///< [R/-] PTP Config has extended supp_flags + N_PTP_CFG_FLAGS ///< the number of defined flags }; + /** - * @brief Bit masks associated to ::PTP_CFG_FLAGS + * @defgroup group_PTP_CFG_FLAG_MASKS Bit masks used with PTP_CFG_INFO::supp_flags and PTP_CFG_SETTINGS::flags + * + * @see ::PTP_CFG_INFO::supp_flags + * @see ::PTP_CFG_SETTINGS::flags + * @see ::PTP_CFG_FLAGS + * + * @anchor PTP_CFG_FLAG_MASKS + * + * @{ */ + +#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 */ + + + +/** + * @brief Extended flags bits used with PTP configuration + * + * Flags labeled [R/-] can only be used with ::PTP_CFG_INFO::supp_flags + * to indicate that the associated feature is supported in general. + * + * If a flag labeled [R/W] is set in ::PTP_CFG_INFO::supp_flags then + * this flag can also be used with ::PTP_CFG_SETTINGS::flags to control + * the associated feature. + * + * @note Originally, all devices supported the multicast slave role, so + * there was no extra flag to indicate this. However, some newer devices + * may not support the multicast slave role, so two new flags have been + * introduced to cope with this: + * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is set then a different flag + * ::PTP_CFG_CAN_BE_MULTICAST_SLAVE needs to be checked to tell if + * the multicast slave role is supported, or not. + * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is not set then the device + * definitely supports the multicast slave role. + * + * @see @ref PTP_CFG_FLAG_EX_MASKS */ -enum PTP_CFG_FLAG_MASKS +enum PTP_CFG_FLAGS_EX { - PTP_CFG_MSK_TIME_SCALE_IS_PTP = ( 1UL << PTP_CFG_TIME_SCALE_IS_PTP ), ///< see ::PTP_CFG_TIME_SCALE_IS_PTP - PTP_CFG_MSK_V1_HW_COMPAT = ( 1UL << PTP_CFG_V1_HW_COMPAT ), ///< see ::PTP_CFG_V1_HW_COMPAT - PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE = ( 1UL << PTP_CFG_CAN_BE_UNICAST_SLAVE ), ///< see ::PTP_CFG_CAN_BE_UNICAST_SLAVE - PTP_CFG_MSK_CAN_BE_MULTICAST_MASTER = ( 1UL << PTP_CFG_CAN_BE_MULTICAST_MASTER ), ///< see ::PTP_CFG_CAN_BE_MULTICAST_MASTER - PTP_CFG_MSK_CAN_BE_UNICAST_MASTER = ( 1UL << PTP_CFG_CAN_BE_UNICAST_MASTER ), ///< see ::PTP_CFG_CAN_BE_UNICAST_MASTER - PTP_CFG_MSK_CAN_BE_MULTICAST_AUTO = ( 1UL << PTP_CFG_CAN_BE_MULTICAST_AUTO ), ///< see ::PTP_CFG_CAN_BE_MULTICAST_AUTO - PTP_CFG_MSK_SUPP_UTC_VALID = ( 1UL << PTP_CFG_SUPP_UTC_VALID ) ///< see ::PTP_CFG_SUPP_UTC_VALID + PTP_CFG_CAN_BE_PTP_PROBE, ///< [R/W] PTP can be used in slave mode although not in slave capable slot + 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 }; -/** @brief A bit mask of the role bits within the flag bits */ -#define PTP_CFG_MSK_SUPPORT_PTP_ROLES ( PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE | \ - PTP_CFG_MSK_CAN_BE_MULTICAST_MASTER | \ - PTP_CFG_MSK_CAN_BE_UNICAST_MASTER | \ - PTP_CFG_MSK_CAN_BE_MULTICAST_AUTO ) + +/** + * @defgroup group_PTP_CFG_FLAG_EX_MASKS Bit masks used with PTP_CFG_INFO::supp_flags_ex and PTP_CFG_SETTINGS::flags_ex + * + * @see ::PTP_CFG_INFO::supp_flags_ex + * @see ::PTP_CFG_SETTINGS::flags_ex // TODO Is this correct? + * @see ::PTP_CFG_FLAGS_EX + * + * @anchor PTP_CFG_FLAG_EX_MASKS + * + * @{ */ + +#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 + +/** @} defgroup group_PTP_CFG_FLAG_EX_MASKS */ + + /** @brief A bit mask of the unicast role bits within the flag bits */ #define PTP_CFG_MSK_SUPPORT_PTP_UNICAST ( PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE | \ PTP_CFG_MSK_CAN_BE_UNICAST_MASTER ) + + +/** + * @brief Register in TSU-GbE FPGA to determine board features of the current TSU board revision + */ +typedef uint16_t PTP_HW_FEATURES; + + + +/** + * @brief Bits used to define ::PTP_HW_FEAT_MASKS + */ +enum PTP_HW_FEAT_BITS +{ + PTP_FEAT_SYNCE_EXT_MUX, ///< [R] supports SyncE and external signal multiplexer + N_PTP_HW_FEAT ///< the number of defined features +}; + + +// TODO fix comment linkage /** - * @brief Derive a "supported PTP roles" bit mask from PTP_CFG_INFO::supp_flags + * @brief Bit masks used with ::PTP_HW_FEATURES * - * There's no explicite flag to indicate that the role of a multicast slave - * is supported, since this role is always supported. The sequence of flags - * indicating that a specific optional role is supported matches the enumerated - * roles above, but don't start at bit 0. So we compine the optional flag bits - * with the LSB always set for the implicite multicast slave role to yield - * a bit mask which according to the enumerated roles. + * @see ::PTP_HW_FEAT_BITS */ -#define _get_supp_ptp_role_idx_msk( _f ) \ - ( 1UL | ( ( (_f) & PTP_CFG_MSK_SUPPORT_PTP_ROLES ) >> ( PTP_CFG_CAN_BE_UNICAST_SLAVE - 1 ) ) ) +enum PTP_HW_FEAT_MASKS +{ + PTP_HW_FEAT_MSK_SYNCE_EXT_MUX = ( 1UL << PTP_FEAT_SYNCE_EXT_MUX ) ///< see ::PTP_FEAT_SYNCE_EXT_MUX +}; + /** - * @brief Flags used with PTP_CFG_SETTINGS::profile and PTP_CFG_INFO::supp_profiles + * @brief Known optional PTP protocol extensions, see ::PTP_CFG_SETTINGS::opt_ext * - * @see PTP_PROFILE_STRS + * @see ::PTP_OPT_EXT_MASKS */ -enum PTP_PROFILES +enum PTP_OPT_EXTS { - PTP_PROFILE_CUSTOM, ///< customizable, always supported - PTP_PROFILE_DFLT_E2E, ///< pure IEEE1588-2008 (PTPv2) with E2E - PTP_PROFILE_DFLT_P2P, ///< pure IEEE1588-2008 (PTPv2) with P2P - PTP_PROFILE_POWER, ///< IEEE C37.238 profile extension - PTP_PROFILE_TELECOM, ///< ITU-T G.8265.1 profile extension - N_PTP_PROFILES ///< number of supported profiles + PTP_OPT_EXT_NONE, ///< no extension used + PTP_OPT_EXT_POWER, ///< IEEE C37.238-2011 profile extension + PTP_OPT_EXT_TELECOM, ///< ITU-T G.8265.1 profile extension + PTP_OPT_EXT_TELECOM_PHASE, ///< ITU-T G.8275.1 profile extension + PTP_OPT_EXT_SMPTE, ///< SMPTE ST 2059-2 profile extension + PTP_OPT_EXT_8021AS, ///< IEEE 802.1AS profile extension + PTP_OPT_EXT_6185093, ///< IEC/IEEE FDIS 61850-9-3 Power Utility profile extension + PTP_OPT_EXT_TELECOM_PTS, ///< ITU-T G.8275.2 profile extension + PTP_OPT_EXT_C37238_2017, ///< IEEE C37.238-2017 profile extension + N_PTP_OPT_EXT ///< number of known optional extensions }; /** - * @brief Flags used with PTP_CFG_SETTINGS::profile and PTP_CFG_INFO::supp_profiles + * @brief Flag masks used with ::PTP_CFG_INFO::supp_opt_ext * - * @see PTP_PROFILES + * @see ::PTP_OPT_EXTS */ -enum PTP_PROFILE_MASKS +enum PTP_OPT_EXT_MASKS { - PTP_MSK_PROFILE_CUSTOM = ( 1UL << PTP_PROFILE_CUSTOM ), ///< see ::PTP_PROFILE_CUSTOM - PTP_MSK_PROFILE_DFLT_E2E = ( 1UL << PTP_PROFILE_DFLT_E2E ), ///< see ::PTP_PROFILE_DFLT_E2E - PTP_MSK_PROFILE_DFLT_P2P = ( 1UL << PTP_PROFILE_DFLT_P2P ), ///< see ::PTP_PROFILE_DFLT_P2P - PTP_MSK_PROFILE_POWER = ( 1UL << PTP_PROFILE_POWER ), ///< see ::PTP_PROFILE_POWER - PTP_MSK_PROFILE_TELECOM = ( 1UL << PTP_PROFILE_TELECOM ) ///< see ::PTP_PROFILE_TELECOM + 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 }; + /** - * @brief Name strings for defined PTP profiles + * @brief Enumeration of PTP cfg presets used with ::PTP_CFG_SETTINGS::selected_presets + * + * This can be used by configuration programs to determine + * the last recently selected presets. * - * @see PTP_PROFILES + * @see ::PTP_PRESETS_STRS + * @see ::PTP_PRESETS_MASKS */ -#define PTP_PROFILE_STRS \ -{ \ - "Custom", \ - "Default E2E", \ - "Default P2P", \ - "Power", \ - "Telecom" \ +enum PTP_PRESETS +{ + PTP_PRESETS_CUSTOM, ///< customizable, always supported + PTP_PRESETS_DFLT_E2E, ///< pure IEEE1588-2008 (PTPv2) with E2E + PTP_PRESETS_DFLT_P2P, ///< pure IEEE1588-2008 (PTPv2) with P2P + PTP_PRESETS_POWER, ///< IEEE C37.238 profile extension, only if ::PTP_MSK_OPT_EXT_POWER is set + PTP_PRESETS_TELECOM, ///< ITU-T G.8265.1 profile extension, only if ::PTP_MSK_OPT_EXT_TELECOM is set + PTP_PRESETS_TELECOM_PHASE, ///< ITU-T G.8275.1 profile extension, only if ::PTP_MSK_OPT_EXT_TELECOM_PHASE is set + PTP_PRESETS_SMPTE, ///< SMPTE ST 2059-2 profile extension, only if ::PTP_MSK_OPT_EXT_SMPTE is set + PTP_PRESETS_AES67, ///< AES67 media profile + PTP_PRESETS_8021AS, ///< IEEE 802.1AS -like profile, only if ::PTP_MSK_OPT_EXT_8021AS is set + PTP_PRESETS_6185093, ///< IEC/IEEE FDIS 61850-9-3, only if ::PTP_MSK_OPT_EXT_6185093 is set + PTP_PRESETS_TELECOM_PTS, ///< ITU-T G.8275.2 profile extension, only if ::PTP_MSK_OPT_EXT_TELECOM_PTS is set + PTP_PRESETS_DOCSIS_31, ///< only if ::PTP_MSK_OPT_EXT_TELECOM_PHASE is set + PTP_PRESETS_C37238_2017, ///< only if ::PTP_MSK_OPT_EXT_C37238_2017 is set + N_PTP_PRESETS ///< number of supported presets +}; + + +/** + * @brief Flag masks used with ::PTP_CFG_INFO::supp_opt_ext + * + * @see ::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 + +}; + + +/** + * @brief Name strings for defined PTP presets + * + * @see ::PTP_PRESETS + */ +#define PTP_PRESETS_STRS \ +{ \ + "Custom", \ + "Default E2E IEEE1588-2008", \ + "Default P2P IEEE1588-2008", \ + "Power IEEE C37.238-2011", \ + "Telecom ITU-T G.8265.1", \ + "Telecom ITU-T G.8275.1", \ + "SMPTE ST 2059-2", \ + "AES67 Media Profile", \ + "IEEE 802.1AS", \ + "Utility IEC 61850-9-3", \ + "Telecom ITU-T G.8275.2", \ + "DOCSIS 3.1", \ + "Power IEEE C37.238-2017" \ } @@ -6294,22 +13711,518 @@ enum PTP_PROFILE_MASKS typedef struct { uint32_t network_incaccuracy; ///< Pre-defined network inaccuracy from master in [ns] - uint8_t grandmaster_id; ///< [PTP_POWER_PROFILE_GM_ID_MIN..PTP_POWER_PROFILE_GM_ID_MAX] + uint8_t grandmaster_id; ///< [::PTP_POWER_PROFILE_GM_ID_MIN..::PTP_POWER_PROFILE_GM_ID_MAX] uint8_t reserved_1; - uint16_t reserved_2; + uint16_t grandmaster_id_2017; ///< Grandmaster ID defined in C.37.2017 is now 16 Bits + TZDL tzdl; } PTP_POWER_PROFILE_CFG; +#define _mbg_swab_ptp_power_profile_cfg( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->network_incaccuracy ); \ + _mbg_swab8( &(_p)->grandmaster_id ); \ + _mbg_swab8( &(_p)->reserved_1 ); \ + _mbg_swab16( &(_p)->grandmaster_id_2017 ); \ + _mbg_swab_tzdl( &(_p)->tzdl ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + +#if defined( _PRELIMINARY_CODE ) + +// TODO: These definitions are preliminary and maybe subject to changes. /** - * @brief A host's fully qualified domain name (FQDN), or a numeric IP address string + * @brief SMPTE System Frame Rates according to SMPTE ST 2059-2 * - * In theory each single component (host name, domain name, top level domain name) - * of a FQDN can have up to 63 characters, but the overall length is limited to - * 255 characters. We specify one more character for the trailing 0. + * @see ::TODO + */ +enum SMPTE_SYSTEM_FRAME_RATES +{ + SMPTE_23_98HZ, + SMPTE_24HZ, + SMPTE_25HZ, + SMPTE_29_97HZ, + SMPTE_50HZ, + SMPTE_59_94HZ, + N_SMPTE_SYSTEM_FRAME_RATES +}; + + +#define SMPTE_SYSTEM_FRAME_RATE_STR \ +{ \ + "24Hz (23.98)", \ + "24Hz", \ + "25Hz", \ + "30Hz (29.97)", \ + "50Hz", \ + "60Hz (59.94)" \ +} + + +#define SMPTE_FRAME_RATE_NUM \ +{ \ + 24000, \ + 24000, \ + 25000, \ + 30000, \ + 50000, \ + 60000, \ +} + +#define SMPTE_FRAME_RATE_DENUM \ +{ \ + 1001, \ + 1000, \ + 1000, \ + 1001, \ + 1000, \ + 1001, \ +} + + +/** + * @brief Additional parameters for SMPTE ST 2059-2 profile + * + * This stucture holds the synchronization metadata required for the SMPTE profile. + * This structure is only used for internal storage of the data. The data is + * distributed through a network by using management messages and the dedicated + * organization extension TLV defined in the SMPTE profile. + */ +typedef struct +{ + /// 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 + /// shall be the denominator. The denominator shall be the smallest value + /// that represents the frame rate denominator + /// For example, 29.97 Hz: (30000/1001) or 25 Hz: (25/1). + uint32_t defaultSystemFrameRateNum; + uint32_t defaultSystemFrameRateDenum; + /// 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 + /// 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; + + int32_t currentLocalOffset; + /// 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. + 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 + /// 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 + /// 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. + 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; + + uint8_t reserved_6; + uint8_t reserved_7; + + uint32_t reserved_8; + uint32_t reserved_9; + uint32_t reserved_10; + +} PTP_SMPTE_PROFILE_CFG; + +#define _mbg_swab_ptp_smpte_profile_cfg( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->defaultSystemFrameRateNum ); \ + _mbg_swab32( &(_p)->defaultSystemFrameRateDenum ); \ + _mbg_swab32( &(_p)->currentLocalOffset ); \ + _mbg_swab32( &(_p)->jumpSeconds ); \ + _mbg_swab32( &(_p)->reserved_5 ); \ + _mbg_swab32( &(_p)->previousJamLocalOffset ); \ + _mbg_swab32( &(_p)->reserved_8 ); \ + _mbg_swab32( &(_p)->reserved_8 ); \ + _mbg_swab32( &(_p)->reserved_9 ); \ + _mbg_swab32( &(_p)->reserved_10 ); \ +} while ( 0 ) + + +/** + * @brief Additional parameters for Telecom8275.1 profile + */ +typedef struct +{ + uint8_t use_alternate_multicast_address; + uint8_t reserved_1; + uint8_t reserved_2; + uint8_t reserved_3; + uint32_t reserved_4; + +} PTP_TELECOMG8275_PROFILE_CFG; + +#define _mbg_swab_ptp_telecom8275_profile_cfg( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->use_alternate_multicast_mac_address ); \ + _mbg_swab8( &(_p)->reserved_1 ); \ + _mbg_swab8( &(_p)->reserved_2 ); \ + _mbg_swab8( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ +} while ( 0 ) + + + +/** + * @brief A type which holds one of the ITU-T SSM codes + * + * @see ::ITU_SSM_CODES + */ +typedef uint16_t ITU_SSM_CODE; + + + +/** + * @brief ITU-T SSM codes acc. to Recommendation G.781 + * + * @see ::ITU_SSM_CODE + */ +enum ITU_SSM_CODES +{ + ITU_SSM_CODE_STU_UKN, + ITU_SSM_CODE_PRS, + ITU_SSM_CODE_PRC, + ITU_SSM_CODE_INV3, + ITU_SSM_CODE_SSU_A_TNC, + ITU_SSM_CODE_INV5, + ITU_SSM_CODE_INV6, + ITU_SSM_CODE_ST2, + ITU_SSM_CODE_SSU_B, + ITU_SSM_CODE_INV9, + ITU_SSM_CODE_ST3, + ITU_SSM_CODE_SEC, + ITU_SSM_CODE_SMC, + ITU_SSM_CODE_ST3E, + ITU_SSM_CODE_PROV, + ITU_SSM_CODE_DNU_DUS, + N_ITU_SSM_CODES +}; + + +#define N_SSM_CODES_OPTION_1 5 +#define N_SSM_CODES_OPTION_2 9 + + +/** + * @brief Name strings for SSM codes, network option I + * + * @see ::ITU_SSM_CODES + */ +#define ITU_SSM_CODE_OPT_1_STRS \ +{ \ + "", \ + "", \ + "QL-PRC", \ + "", \ + "QL-SSU-A", \ + "", \ + "", \ + "", \ + "QL-SSU-B", \ + "", \ + "", \ + "QL-SEC", \ + "", \ + "", \ + "", \ + "QL-DNU" \ +} + + + +/** + * @brief Name strings for SSM codes, network option II + * + * @see ::ITU_SSM_CODES + */ +#define ITU_SSM_CODE_OPT_2_STRS \ +{ \ + "QL-STU", \ + "QL-PRS", \ + "", \ + "", \ + "QL-TNC", \ + "", \ + "", \ + "QL-ST2", \ + "", \ + "", \ + "QL-ST3", \ + "", \ + "QL-SMC", \ + "QL-ST3E", \ + "QL-PROV", \ + "QL-DUS" \ +} + + + +/** + * @brief Name strings for SSM codes, option I and II combined + * + * @see ::ITU_SSM_CODES + */ +#define ITU_SSM_CODE_STRS_COMBINED \ +{ \ + "QL-STU/UKN", \ + "QL-PRS", \ + "QL-PRC", \ + "QL-INV3", \ + "QL-SSU-A/TNC", \ + "QL-INV5", \ + "QL-INV6", \ + "QL-ST2", \ + "QL-SSU-B", \ + "QL-INV9", \ + "QL-EEC2/ST3", \ + "QL-EEC1/SEC", \ + "QL-SMC", \ + "QL-ST3E", \ + "QL-PROV", \ + "QL-DNU/DUS", \ +} + + + +/** + * @brief Maximum T1 SSM only quality levels + * + * @see ::T1_SSM_QLVL + * @see ::T1_SSM_QLVL_STRS + * @see ::T1_SSM_QLVL_ARRAY + */ +#define MAX_T1_SSM_QLVL 8 + + + +/** + * @brief T1 SSM only quality level (6 bit encoded) + * + * @see ::MAX_T1_SSM_QLVL + * @see ::T1_SSM_QLVL_STRS + * @see ::T1_SSM_QLVL_ARRAY + */ +enum T1_SSM_QLVL +{ + T1_SSM_QLVL_ST1_TRACE = 2, + T1_SSM_QLVL_SYNC_TRACE_UNKNOWN = 4, + T1_SSM_QLVL_ST2_TRACE = 6, + T1_SSM_QLVL_ST3_TRACE = 8, + T1_SSM_QLVL_SONET_MIN_CLOCK_TRACE = 17, + T1_SSM_QLVL_ST4_TRACE = 20, + T1_SSM_QLVL_DNU_FOR_SYNC = 24, + T1_SSM_QLVL_RESERVED = 32 +}; + + + +/** + * @brief T1 SSM only quality level array + * + * @see ::MAX_T1_SSM_QLVL + * @see ::T1_SSM_QLVL_STRS + * @see ::T1_SSM_QLVL + */ +#define T1_SSM_QLVL_ARRAY \ +{ \ + T1_SSM_QLVL_ST1_TRACE, \ + T1_SSM_QLVL_SYNC_TRACE_UNKNOWN, \ + T1_SSM_QLVL_ST2_TRACE, \ + T1_SSM_QLVL_ST3_TRACE, \ + T1_SSM_QLVL_SONET_MIN_CLOCK_TRACE, \ + T1_SSM_QLVL_ST4_TRACE, \ + T1_SSM_QLVL_DNU_FOR_SYNC, \ + T1_SSM_QLVL_RESERVED \ +} + + + +/** + * @brief Name strings for T1 SSM quality levels + * + * @see ::MAX_T1_SSM_QLVL + * @see ::T1_SSM_QLVL + * @see ::T1_SSM_QLVL_ARRAY + */ +#define T1_SSM_QLVL_STRS \ +{ \ + "Stratum 1 traceable", \ + "Synchronized traceability unknown", \ + "Stratum 2 traceable", \ + "Stratum 3 traceable", \ + "SONET minimum clock traceable", \ + "Stratum 4 traceable", \ + "Do not use for sync", \ + "Reserved for network sync" \ +} + + + +/** + * @brief SDH network options + * + * @see ::SDH_NETWORK_OPTION_MASKS + */ +enum SDH_NETWORK_OPTIONS +{ + SDH_NETWORK_OPTION_1, + SDH_NETWORK_OPTION_2, + N_SDH_NETWORK_OPTIONS + +}; + + + +/** + * @brief Flag masks used with MBG_SYNC_E_INFO::supp_sdh_network_opts ::FIXME + * + * @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 +}; + + + +/** + * @brief Name strings for SDH network options + * + * @see ::SDH_NETWORK_OPTIONS + */ +#define SDH_NETWORK_OPTION_STRS \ +{ \ + "SDH Network Opt. 1", \ + "SDH Network Opt. 2", \ +} + + + +//##++++ TODO: shouldn't this be merged with / replaced by MBG_NET_LINK_MODES? +/** + * @brief Link modes for SyncE on a 1000BASE-T interface + * + * @see ::GBIT_LINK_COPPER_MODE_MASKS + */ +enum GBIT_LINK_COPPER_MODES +{ + GBIT_LINK_COPPER_AUTO, // valid if synce is disabled + GBIT_LINK_COPPER_FORCE_SYNCE_AUTO, + GBIT_LINK_COPPER_FORCE_OR_IS_MASTER, // Used in both structures, settings and status + GBIT_LINK_COPPER_FORCE_OR_IS_SLAVE, // Used in both structures, settings and status + GBIT_LINK_COPPER_PREFER_MASTER, + GBIT_LINK_COPPER_PREFER_SLAVE, + N_GBIT_LINK_COPPER_MODES +}; + + + +/** + * @brief Flag masks used with MBG_SYNC_E_INFO::supp_gbit_link_copper_modes ::FIXME + * + * @see ::GBIT_LINK_COPPER_MODES */ -typedef char MBG_HOSTNAME[256]; +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 +}; + + + +//##++++ TODO: shouldn't this be merged with MBG_NET_LINK_ROLE_BITS / MBG_NET_LINK_ROLE_MASKS? +/** + * @brief Link status for SyncE on a 1000BASE-T interface + * + * @see ::TODO + */ +enum GBIT_LINK_STATUS +{ + GBIT_LINK_COPPER_IS_MASTER, ///< GBIT Link is currently clock master + GBIT_LINK_COPPER_IS_SLAVE, ///< GBIT Link is currently clock slave + GBIT_LINK_COPPER_CFG_FAULT, ///< GBIT Link has a configruation fault (conflict with link partner + GBIT_LINK_COPPER_IS_FE, ///< Link is running on Fast Ethernet (no MASTER/SLAVE decision) + GBIT_LINK_DOWN, ///< Currently no link + GBIT_LINK_FIBER, ///< GBIT Linkup on SFP interface + N_GBIT_LINK_STATUS +}; + + +#define GBIT_LINK_STATUS_STRS \ +{ \ + "MASTER (1000BASE-T)", \ + "SLAVE (1000BASE-T)", \ + "CFG FAULT", \ + "AUTO (100BASE-TX)", \ + "LINK DOWN", \ + "AUTO (SFP LINK UP)", \ +} + +#else // !defined( _PRELIMINARY_CODE ), dummy declarations + +typedef int PTP_SMPTE_PROFILE_CFG; +typedef int PTP_TELECOMG8275_PROFILE_CFG; +typedef int ITU_SSM_CODE; + +#endif // defined( _PRELIMINARY_CODE ) + /** @@ -6331,6 +14244,7 @@ typedef struct } PTP_UC_MASTER_CFG_LIMITS; #define _mbg_swab_ptp_uc_master_cfg_limits( _p ) \ +do \ { \ _mbg_swab16( &(_p)->n_supp_master ); \ _mbg_swab16( &(_p)->sync_intv_min ); \ @@ -6342,7 +14256,8 @@ typedef struct _mbg_swab16( &(_p)->reserved_0 ); \ _mbg_swab32( &(_p)->supp_flags ); \ _mbg_swab32( &(_p)->reserved_1 ); \ -} +} while ( 0 ) + /** @@ -6351,7 +14266,7 @@ typedef struct * This structure is used on a unicast slave to specify the settings of * a unicast master polled by the slave. The number of unicast masters * which can be specified depends on the capabilities of the slave device - * and is returned in PTP_UC_MASTER_CFG_LIMITS::n_supp_master. + * and is returned in ::PTP_UC_MASTER_CFG_LIMITS::n_supp_master. * * The structure ::PTP_UC_MASTER_SETTINGS_IDX should be sent to the device * to save the configuration. @@ -6373,6 +14288,7 @@ typedef struct } PTP_UC_MASTER_SETTINGS; #define _mbg_swab_ptp_uc_master_settings( _p ) \ +do \ { \ _mbg_swab_ptp_clock_id( &(_p)->gm_clock_id ); \ _mbg_swab_ptp_port_id( &(_p)->gm_port_id ); \ @@ -6384,7 +14300,8 @@ typedef struct _mbg_swab16( &(_p)->reserved_0 ); \ _mbg_swab32( &(_p)->reserved_1 ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) + /** @@ -6411,16 +14328,18 @@ enum PTP_UC_MSG_DURATION_LIMITS */ typedef struct { - uint32_t idx; ///< index, 0..PTP_UC_MASTER_CFG_LIMITS::n_supp_master - 1 + uint32_t idx; ///< index, 0..PTP_UC_MASTER_CFG_LIMITS::n_supp_master-1 PTP_UC_MASTER_SETTINGS settings; ///< specification for the unicast master with that index } PTP_UC_MASTER_SETTINGS_IDX; #define _mbg_swab_ptp_uc_master_settings_idx( _p ) \ +do \ { \ _mbg_swab32( &(_p)->idx ); \ _mbg_swab_ptp_uc_master_settings( &(_p)->settings ); \ -} +} while ( 0 ) + /** @@ -6438,11 +14357,13 @@ typedef struct } PTP_UC_MASTER_INFO; #define _mbg_swab_ptp_uc_master_info( _p ) \ +do \ { \ _mbg_swab_ptp_uc_master_settings( &(_p)->settings ); \ _mbg_swab32( &(_p)->reserved ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) + /** @@ -6460,19 +14381,3182 @@ typedef struct */ typedef struct { - uint32_t idx; ///< index, 0..PTP_UC_MASTER_CFG_LIMITS::n_supp_master - 1 + uint32_t idx; ///< index, 0..PTP_UC_MASTER_CFG_LIMITS::n_supp_master-1 PTP_UC_MASTER_INFO info; ///< capabilities and current settings } PTP_UC_MASTER_INFO_IDX; #define _mbg_swab_ptp_uc_master_info_idx( _p ) \ +do \ { \ _mbg_swab32( &(_p)->idx ); \ _mbg_swab_ptp_uc_master_info( &(_p)->info ); \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t counter_cfg; + uint32_t flags; + uint32_t reserved_1; + uint32_t reserved_2; + +} MBG_PTP_STATISTICS_SETTINGS; + + + +typedef struct +{ + MBG_PTP_STATISTICS_SETTINGS settings; + uint32_t supp_flags; ///< Supported settings, currently 0 + uint32_t reserved_1; + +} MBG_PTP_STATISTICS_INFO; + + + +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 + /// 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 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) + +} MBG_PTP_STATISTICS_STATUS; + + + +enum PTP_V1_COMM_IDS +{ + V1_PTP_CLOSED, + V1_PTP_ETHER, + /* reserved */ + V1_PTP_FFBUS = 4, + V1_PTP_PROFIBUS, + V1_PTP_LON, + V1_PTP_DNET, + V1_PTP_SDS, + V1_PTP_CONTROLNET, + V1_PTP_CANOPEN, + /* reserved */ + V1_PTP_IEEE1394 = 243, + V1_PTP_IEEE802_11A, + V1_PTP_IEEE_WIRELESS, + V1_PTP_INFINIBAND, + V1_PTP_BLUETOOTH, + V1_PTP_IEEE802_15_1, + V1_PTP_IEEE1451_3, + V1_PTP_IEEE1451_5, + V1_PTP_USB, + V1_PTP_ISA, + V1_PTP_PCI, + V1_PTP_VXI, + V1_PTP_DEFAULT +}; + + + +#define PTP_CODE_STRING_LENGTH 4 +#define PTP_SUBDOMAIN_NAME_LENGTH 16 + + +/** + * @brief PTPv1 UUID structure used in ::MBG_PTP_V1_DEFAULT_DATASET + * + * @see ::MBG_PTP_V1_DEFAULT_DATASET + */ +typedef struct +{ + uint8_t communication_technology; + uint8_t reserved_1; + uint16_t reserved_2; + PTP_CLOCK_ID clock_uuid; + PTP_PORT_ID port_id; + uint16_t reserved_3; +} PTP_V1_UUID; + + +#define _mbg_swab_ptp_v1_uuid( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab_ptp_clock_id( &(_p)->clock_uuid ); \ + _mbg_swab_ptp_port_id( &(_p)->port_id ); \ + _mbg_swab16( &(_p)->reserved_3 ); \ +} while ( 0 ) + + + +/** + * @brief PTPv1 default dataset flags + * + * @see ::PTP_V1_DEFAULT_DATASET_FLAGS_MASKS + */ +enum PTP_V1_DEFAULT_DATASET_FLAGS +{ + V1_DFLT_CLK_FOLLOWUP_CAPABLE, + V1_DFLT_PREFERRED, + V1_DFLT_INITIALIZABLE, + V1_DFLT_EXT_TIMING, + V1_DFLT_IS_BC +}; + + + +/** + * @brief PTPv1 default dataset flag masks used with ::MBG_PTP_V1_DEFAULT_DATASET::flags + * + * @see ::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 +}; + + + +/** + * @brief PTPv1 default dataset containing global information about the device + * + * @see ::PTP_V1_UUID + */ +typedef struct { + PTP_V1_UUID uuid; + uint8_t clock_stratum; + uint8_t clock_identifier[PTP_CODE_STRING_LENGTH]; + uint16_t clock_variance; + int8_t sync_interval; + uint8_t subdomain_name[PTP_SUBDOMAIN_NAME_LENGTH]; + uint16_t number_ports; + uint16_t number_foreign_records; + uint32_t flags; +} MBG_PTP_V1_DEFAULT_DATASET; + + +#define _mbg_swab_ptp_v1_default_dataset( _p ) \ +do \ +{ \ + _mbg_swab_ptp_v1_uuid( &(_p)->uuid ); \ + _mbg_swab16( &(_p)->clock_variance ); \ + _mbg_swab16( &(_p)->number_ports ); \ + _mbg_swab16( &(_p)->number_foreign_records ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief PTPv1 current dataset containing information about the synchronization status of the device + * + * @see ::NANO_TIME + */ +typedef struct +{ + uint16_t steps_removed; + uint16_t reserved_1; + NANO_TIME offset_from_master; + NANO_TIME one_way_delay; +} MBG_PTP_V1_CURRENT_DATASET; + + +#define _mbg_swab_ptp_v1_current_dataset( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->steps_removed ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab_nano_time( &(_p)->offset_from_master ); \ + _mbg_swab_nano_time( &(_p)->one_way_delay ); \ +} while ( 0 ) + + + +/** + * @brief PTPv1 parent dataset flags + * + * @see ::PTP_V1_PARENT_DATASET_FLAGS_MASKS + */ +enum PTP_V1_PARENT_DATASET_FLAGS +{ + V1_PARENT_FOLLOWUP_CAPABLE, + V1_PARENT_EXT_TIMING, + V1_PARENT_STATS, + V1_PARENT_UTC_REASONABLE, + V1_PARENT_GM_PREFERRED, + V1_PARENT_GM_IS_BC +}; + + + +/** + * @brief PTPv1 parent dataset flag masks used with ::MBG_PTP_V1_PARENT_DATASET::flags + * + * @see ::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 +}; + + + +/** + * @brief PTPv1 parent dataset containing information about the master (parent) of the device + * + * @see ::PTP_V1_UUID + */ +typedef struct +{ + PTP_V1_UUID uuid; + uint16_t parent_last_sync_sequence_number; + int16_t parent_variance; + int16_t observed_variance; + uint16_t reserved_1; + int32_t observed_drift; + PTP_V1_UUID grandmaster_uuid; + uint8_t grandmaster_stratum; + uint8_t grandmaster_identifier[PTP_CODE_STRING_LENGTH]; + int16_t grandmaster_variance; + uint16_t grandmaster_sequence_number; + uint16_t reserved_2; + uint32_t flags; ///< see ::PTP_V1_PARENT_DATASET_FLAGS_MASKS + +} MBG_PTP_V1_PARENT_DATASET; + + +#define _mbg_swab_ptp_v1_parent_dataset( _p ) \ +do \ +{ \ + _mbg_swab_ptp_v1_uuid( &(_p)->uuid ); \ + _mbg_swab16( &(_p)->parent_last_sync_sequence_number ); \ + _mbg_swab16( &(_p)->parent_variance ); \ + _mbg_swab16( &(_p)->observed_variance ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->observed_drift ); \ + _mbg_swab_ptp_v1_uuid( &(_p)->grandmaster_uuid ); \ + _mbg_swab16( &(_p)->grandmaster_variance ); \ + _mbg_swab16( &(_p)->grandmaster_sequence_number ); \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief PTPv1 time drop dataset flags + * + * @see ::PTP_V1_TIME_PROP_DATASET_FLAGS_MASKS + */ +enum PTP_V1_TIME_PROP_DATASET_DATASET_FLAGS +{ + V1_TPROP_LEAP_59, + V1_TPROP_LEAP_61 +}; + + + +/** + * @brief PTPv1 time drop dataset flag masks used with ::MBG_PTP_V1_TIME_PROPERTIES_DATASET::flags + * + * @see ::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 +}; + + + +/** + * @brief PTPv1 time drop dataset + * + */ +typedef struct +{ + int16_t current_utc_offset; + uint16_t epoch_number; + uint32_t flags; ///< see ::PTP_V1_TIME_PROP_DATASET_FLAGS_MASKS + +} MBG_PTP_V1_TIME_PROPERTIES_DATASET; + + +#define _mbg_swab_ptp_v1_time_properties_dataset( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->current_utc_offset ); \ + _mbg_swab16( &(_p)->epoch_number ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief PTPv1 port dataset flags + * + * @see ::PTP_V1_PORT_DATASET_FLAGS_MASKS + */ +enum PTP_V1_PORT_DATASET_DATASET_FLAGS +{ + V1_PORT_DATASET_BURST_ENB, +}; + + + +/** + * @brief PTPv1 port dataset flag masks used with ::MBG_PTP_V1_PORT_DATASET::flags + * + * @see ::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 +}; + + + +/** + * @brief PTPv1 port dataset containing information about the appropriate port of the device + * + * @see ::PTP_V1_UUID + */ +typedef struct +{ + uint8_t port_state; + uint8_t reserved_1; + uint16_t last_sync_event_sequence_number; + uint16_t last_general_event_sequence_number; + uint16_t reserved_2; + uint32_t subdomain_address; + uint16_t event_port_address; + uint16_t general_port_address; + PTP_V1_UUID uuid; + uint32_t flags; +} MBG_PTP_V1_PORT_DATASET; + + +#define _mbg_swab_ptp_v1_port_dataset( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->last_sync_event_sequence_number ); \ + _mbg_swab16( &(_p)->last_general_event_sequence_number ); \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->subdomain_address ); \ + _mbg_swab16( &(_p)->event_port_address ); \ + _mbg_swab16( &(_p)->general_port_address ); \ + _mbg_swab_ptp_v1_uuid( &(_p)->uuid ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @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 + * + * @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_PTP_V1_PORT_DATASET_IDX; + + +#define _mbg_swab_ptp_v1_port_dataset_idx( _p ) \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_ptp_v1_port_dataset( &(_p)->port_dataset ); \ +} + + +/** + * @brief Flags structure for the 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 + */ +typedef struct +{ + uint8_t two_step : 1; ///< indicates, whether the clock is a two-step clock + uint8_t slave_only : 1; ///< indicates, whether the clock is a slave-only clock + uint8_t reserved : 6; ///< reserved, currently always 0 + +} MBG_PTP_V2_DEFAULT_DATASET_FLAGS; + +#define _mbg_swab_ptp_v2_default_dataset_flags( _p ) \ + _nop_macro_fnc() + + +/** + * @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_DEFAULT_DATASET_FLAGS flags; ///< flags field, see ::MBG_PTP_V2_DEFAULT_DATASET_FLAGS + uint8_t reserved_1; ///< reserved, currently always 0 + uint16_t number_ports; ///< number of PTP ports on the device + uint8_t priority_1; ///< priority 1 attribute for the local clock + PTP_CLOCK_QUALITY clock_quality; ///< quality of the local clock, see ::PTP_CLOCK_QUALITY + uint8_t priority_2; ///< priority 2 attribute for the local clock + PTP_CLOCK_ID clock_identity; ///< identity of the local clock, see ::PTP_CLOCK_ID + uint8_t domain_number; ///< domain attribute of the local clock + uint8_t reserved_2; ///< reserved, currently always 0 + +} MBG_PTP_V2_DEFAULT_DATASET; + + +#define _mbg_swab_ptp_v2_default_dataset( _p ) \ +{ \ + _mbg_swab_ptp_v2_default_dataset_flags( &(_p)->flags ); \ + _mbg_swab8( &(_p)->reserved_1 ); \ + _mbg_swab16( &(_p)->number_ports ); \ + _mbg_swab8( &(_p)->priority_1 ); \ + _mbg_swab_ptp_clock_quality( &(_p)->clock_quality ); \ + _mbg_swab8( &(_p)->priority_2 ); \ + _mbg_swab_ptp_clock_id( &(_p)->clock_identity ); \ + _mbg_swab8( &(_p)->domain_number ); \ + _mbg_swab8( &(_p)->reserved_2 ); \ +} + + +/** + * @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 +{ + uint16_t steps_removed; ///< number of communication paths between local clock and grandmaster + 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 + +} MBG_PTP_V2_CURRENT_DATASET; + + +#define _mbg_swab_ptp_v2_current_dataset( _p ) \ +{ \ + _mbg_swab16( &(_p)->steps_removed ); \ + _mbg_swab_ptp_time_interval( &(_p)->offset_from_master ); \ + _mbg_swab_ptp_time_interval( &(_p)->mean_path_delay ); \ +} + + +/** + * @brief Flags structure for the PTPv2 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_PARENT_DATASET + */ +typedef struct +{ + uint8_t parent_stats : 1; ///< indicates whether the variance and change rate values are valid + uint8_t reserved : 7; ///< reserved, currently always 0 + +} MBG_PTP_V2_PARENT_DATASET_FLAGS; + +#define _mbg_swab_ptp_v2_parent_dataset_flags( _p )\ + _nop_macro_fnc() + + + +/** + * @brief PTPv2 parent dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.3 and 15.5.3.5.1 + * + * @see ::PTP_PORT_IDENTITY + * @see ::MBG_PTP_V2_PARENT_DATASET_FLAGS + * @see ::PTP_CLOCK_QUALITY + * @see ::PTP_CLOCK_ID + */ +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 + +} MBG_PTP_V2_PARENT_DATASET; + + +#define _mbg_swab_ptp_v2_parent_dataset( _p ) \ +{ \ + _mbg_swab_ptp_port_identity( &(_p)->parent_port_identity ); \ + _mbg_swab_ptp_v2_parent_dataset_flags( &(_p)->flags ); \ + _mbg_swab8( &(_p)->reserved ); \ + _mbg_swab16( &(_p)->parent_log_variance ); \ + _mbg_swab32( &(_p)->parent_phase_change_rate ); \ + _mbg_swab8( &(_p)->grandmaster_priority_1 ); \ + _mbg_swab_ptp_clock_quality( &(_p)->grandmaster_clock_quality ); \ + _mbg_swab8( &(_p)->grandmaster_priority_2 ); \ + _mbg_swab_ptp_clock_id( &(_p)->grandmaster_identity ); \ +} + + +/** + * @brief Flags structure for the 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 + */ +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 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 frequency_traceable : 1; ///< set, if the frequency determining the timescale is traceable to a primary reference + uint8_t reserved : 2; ///< reserved, currently always 0 + +} MBG_PTP_V2_TIME_PROPERTIES_DATASET_FLAGS; + + +#define _mbg_swab_ptp_v2_time_properties_dataset_flags( _p ) \ + _nop_macro_fnc() + + +/** + * @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 +{ + 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 + +} MBG_PTP_V2_TIME_PROPERTIES_DATASET; + + +#define _mbg_swab_ptp_v2_time_properties_dataset( _p ) \ +{ \ + _mbg_swab16( &(_p)->current_utc_offset ); \ + _mbg_swab_ptp_v2_time_properties_dataset_flags( &(_p)->flags ); \ + _mbg_swab8( &(_p)->time_source ); \ +} + + +/** + * @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 +{ + PTP_PORT_IDENTITY port_identity; ///< identity of the local port, see ::PTP_PORT_IDENTITY + uint8_t port_state; ///< state of the protocol engine associated with this port, see ::PTP_PORT_STATES + int8_t log_min_delay_req_interval; ///< minimum delay request interval for this port + 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 + int8_t log_announce_interval; ///< announce interval to be used by this port + uint8_t announce_receipt_timeout; ///< shall be an integral multiple of ::MBG_PTP_V2_PORT_DATASET::log_announce_interval + int8_t log_sync_interval; ///< mean sync interval to be used for multicast messages + uint8_t delay_mechanism; ///< propagation delay measuring option, see ::PTP_DELAY_MECHS + int8_t log_min_pdelay_req_interval; ///< minimum peer delay request interval for this port + uint8_t version_number : 4; ///< PTP version in use on the port + uint8_t reserved : 4; ///< reserved, currently always 0 + +} MBG_PTP_V2_PORT_DATASET; + + +#define _mbg_swab_ptp_v2_port_dataset( _p ) \ +{ \ + _mbg_swab_ptp_port_identity( &(_p)->port_identity ); \ + _mbg_swab8( &(_p)->port_state ); \ + _mbg_swab8( &(_p)->log_min_delay_req_interval ); \ + _mbg_swab_ptp_time_interval( &(_p)->peer_mean_path_delay ); \ + _mbg_swab8( &(_p)->log_announce_interval ); \ + _mbg_swab8( &(_p)->announce_receipt_timeout ); \ + _mbg_swab8( &(_p)->log_sync_interval ); \ + _mbg_swab8( &(_p)->delay_mechanism ); \ + _mbg_swab8( &(_p)->log_min_pdelay_req_interval ); \ +} + + +/** + * @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 +{ + 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_PTP_V2_PORT_DATASET_IDX; + + +#define _mbg_swab_ptp_v2_port_dataset_idx( _p ) \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_ptp_v2_port_dataset( &(_p)->port_dataset ); \ +} + + +/** @} defgroup group_ptp */ + + + +/** + * @defgroup group_ntp Definitions used with NTP + * + * @{ */ + + +/** + * @brief Enumeration of known NTP roles + * + * @see ::NTP_GLB_SETTINGS::ntp_role + */ +enum NTP_ROLES +{ + NTP_ROLE_NONE = 0, ///< NTP services disabled + NTP_ROLE_CLIENT, ///< NTP client + NTP_ROLE_SERVER, ///< NTP server + NTP_ROLE_CLIENT_SERVER, ///< both NTP client and server + N_NTP_ROLES ///< number of supported roles +}; + + +/** + * @brief Flag masks associated with NTP roles + * + * @see ::NTP_GLB_INFO::supp_ntp_roles + */ +enum NTP_ROLE_MASKS +{ + NTP_MSK_ROLE_NONE = ( 1UL << NTP_ROLE_NONE ), ///< see ::NTP_ROLE_NONE + NTP_MSK_ROLE_CLIENT = ( 1UL << NTP_ROLE_CLIENT ), ///< see ::NTP_ROLE_CLIENT + NTP_MSK_ROLE_SERVER = ( 1UL << NTP_ROLE_SERVER ), ///< see ::NTP_ROLE_SERVER + NTP_MSK_ROLE_CLIENT_SERVER = ( 1UL << NTP_ROLE_CLIENT_SERVER ), ///< see ::NTP_ROLE_CLIENT_SERVER +}; + + +/** + * @brief Enumeration of global NTP flags + * + * @see @ref NTP_FLAG_MASKS + */ +enum NTP_FLAGS +{ + NTP_IPV4, ///< NTP via IPv4/UDP + NTP_IPV6, ///< NTP via IPv6/UDP + NTP_SYMM_KEYS, ///< support symmetric key authentication (MD5) + NTP_AUTOKEY, ///< include authentication fields encrypted using the autokey scheme + NTP_BURST, ///< send a burst of eight packets at each polling cycle + NTP_IBURST, ///< send a burst of eight packets at the first polling cycle + NTP_NO_SELECT, ///< marks a server as not to be selected for time synchronization + NTP_PREEMPT, ///< specifies the association as preemptable rather than the default persistent + NTP_PREFER, ///< marks a server as preferred peer for time synchronization + NTP_TRUE, ///< force the association to assume truechimer status; always survive the selection and clustering algorithms + NTP_BROADCAST, ///< transmission via broadcast, point to multipoint + NTP_MULTICAST, ///< transmission via multicast, point to multipoint + NTP_MANYCAST, ///< transmission via manycast, point to multipoint + NTP_POOL, ///< peer shall be treated as a pool server + 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 +}; + + + +/** + * @brief Flag masks associated with ::NTP_FLAGS + * + * Used with ::NTP_GLB_INFO::supp_flags, ::NTP_GLB_SETTINGS::flags, NTP_CLNT_MODE_INFO::supp_flags, + * ::NTP_CLNT_MODE_INFO::supp_peer_flags, ::NTP_CLNT_MODE_SETTINGS::flags, ::NTP_PEER_SETTINGS::flags, + * ::NTP_SRV_MODE_SETTINGS::flags, and ::NTP_SRV_MODE_INFO::supp_flags. + * + * @todo We may need structures to configure symmetric keys, and autokey certificates. + * + * @see ::NTP_FLAGS + * + * @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 + +/** @} anchor NTP_FLAG_MASKS */ + + +#define NTP_DEF_ADD_CONF_PATH "/etc/mbg" +#define NTP_DEF_ADD_CONF_FILENAME "ntp.conf.add" +#define NTP_DEF_ADD_CONF_FILE NTP_DEF_ADD_CONF_PATH "/" NTP_DEF_ADD_CONF_FILENAME + + + +/** + * @brief Global configuration settings of an NTP device (client/server) + * + * This structure should be sent to an NTP device to configure global settings + */ +typedef struct +{ + uint8_t ntp_role; ///< one of the supported NTP roles, see ::NTP_ROLES + uint8_t num_symm_keys; ///< number of configured symm keys + uint8_t num_trusted_keys; ///< number of activated symm keys + uint8_t reserved_1; ///< reserved, currently 0 + + uint32_t reserved_2; ///< reserved, currently 0 + uint32_t reserved_3; ///< reserved, currently 0 + + uint32_t flags; ///< NTP flags, see @ref NTP_FLAG_MASKS + +} NTP_GLB_SETTINGS; + +#define _mbg_swab_ntp_glb_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + +/** + * @brief Global configuration info of an NTP device (client/server) + * + * This structure can be used to determine possible configurations of an NTP device + */ +typedef struct +{ + NTP_GLB_SETTINGS settings; ///< current configuration settings + + uint8_t max_symm_keys; ///< number of available symm keys that can be generated, see ::NTP_SYMM_KEY_INFO_IDX + uint8_t max_trusted_keys; ///< number of available trusted keys, see ::NTP_TRUSTED_KEY_INFO_IDX + + uint16_t reserved_2; ///< reserved, currently 0 + uint32_t reserved_3; ///< reserved, currently 0 + + uint32_t supp_ntp_roles; ///< supported NTP roles, see ::NTP_ROLE_MASKS + uint32_t supp_flags; ///< supported NTP flags, see @ref NTP_FLAG_MASKS + +} NTP_GLB_INFO; + +#define _mbg_swab_ntp_glb_info( _p ) \ +do \ +{ \ + _mbg_swab_ntp_glb_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_ntp_roles ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + +#if defined( _PRELIMINARY_CODE ) + +/** + * @brief Enumeration of supported NTP restriction types/keywords + * + * Used with ::NTP_RESTR::type + * + * @see https://www.eecis.udel.edu/~mills/ntp/html/accopt.html#restrict + * @see ::NTP_RESTR_TYPE_MSKS + */ +enum NTP_RESTR_TYPES +{ + NTP_RESTR_TYPE_DEFAULT, + NTP_RESTR_TYPE_SOURCE, + NTP_RESTR_TYPE_ADDRESS, + N_NTP_RESTR_TYPES +}; + + + +/** + * @brief Bit masks associated with ::NTP_RESTR_TYPES + * + * Used with ::NTP_RESTR_LIMITS::supp_types + * + * @see ::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 +}; + + + +/** + * @brief Enumeration of supported NTP restriction flags + * + * Used to define ::NTP_RESTR_FLAG_MSKS + * + * @see https://www.eecis.udel.edu/~mills/ntp/html/accopt.html#restrict + * @see ::NTP_RESTR_FLAG_MSKS + */ +enum NTP_RESTR_FLAGS +{ + NTP_RESTR_FLAG_FLAKE, + NTP_RESTR_FLAG_IGNORE, + NTP_RESTR_FLAG_KOD, + NTP_RESTR_FLAG_LIMITED, + NTP_RESTR_FLAG_LOWPRIOTRAP, + NTP_RESTR_FLAG_MSSNTP, + NTP_RESTR_FLAG_NOMODIFY, + NTP_RESTR_FLAG_NOQUERY, + NTP_RESTR_FLAG_NOPEER, + NTP_RESTR_FLAG_NOSERVE, + NTP_RESTR_FLAG_NOTRAP, + NTP_RESTR_FLAG_NOTRUST, + NTP_RESTR_FLAG_NTPPORT, + NTP_RESTR_FLAG_VERSION, + NTP_RESTR_FLAG_IPV4, ///< This default restriction only applies to IPv4 + NTP_RESTR_FLAG_IPV6, ///< This default restriction only applies to IPv6 + N_NTP_RESTR_FLAGS +}; + + + +/** + * @brief Flag masks associated with ::NTP_RESTR_FLAGS + * + * Used with ::NTP_RESTR::flags and ::NTP_RESTR_LIMITS::supp_flags + * + * @see ::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 +}; + + + +/** + * @brief General NTP restriction limits to be read from a device + * + * Used to query from a device how many NTP restrictions are supported + * by the device, then index 0..::NTP_RESTR_LIMITS::cur_restrs-1 + * restriction records can be read from a device. A maximum of + * ::NTP_RESTR_LIMITS::max_restrs can be configured at all. + */ +typedef struct +{ + uint16_t max_restrs; ///< Number of maximum supported restrictions + uint16_t cur_restrs; ///< Number of currently configured restrictions + uint32_t supp_types; ///< Supported restriction types, see ::NTP_RESTR_TYPE_MSKS + uint32_t supp_flags; ///< Supported restriction flags, see ::NTP_RESTR_FLAG_MSKS + uint32_t reserved; ///< Future use + +} NTP_RESTR_LIMITS; + +#define _mbg_swab_ntp_restr_limits( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->max_restrs ); \ + _mbg_swab16( &(_p)->cur_restrs ); \ + _mbg_swab32( &(_p)->supp_types ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + +/** + * @brief NTP restriction + * + * Structure contains all flags and information needed for a valid NTP restriction + * as described at ntp.org's manual page. + */ +typedef struct +{ + uint8_t type; ///< Restriction type, see ::NTP_RESTR_TYPES + uint8_t reserved_1; ///< Future use + 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). +} NTP_RESTR; + +#define _mbg_swab_ntp_restr( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab_ntp_restr_discard( &(_p)->u.discard ); \ +} while ( 0 ) + + + +/** + * @brief NTP restriction, plus index + * + * @see ::NTP_RESTR + */ +typedef struct +{ + uint32_t idx; + NTP_RESTR restr; + +} NTP_RESTR_IDX; + +#define _mbg_swab_ntp_restr_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_restr( &(_p)->restr ); \ +} while ( 0 ) + + + +/** + * @brief General NTP "discard" rate limiting limits to be read from a device + * + * Used to query from a device what range of values is supported + * for the NTP "discard" rate limiting configuration. + */ +typedef struct +{ + uint8_t avg_min; ///< Minimum value for avg + uint8_t avg_max; ///< Maximum value for avg + uint8_t min_min; ///< Minimum value for min + uint8_t min_max; ///< Maximum value for min + uint16_t monitor_min; ///< Maximum value for min + uint16_t monitor_max; ///< Maximum value for min + + uint32_t reserved; ///< Future use + +} NTP_DISCARD_LIMITS; + +#define _mbg_swab_ntp_discard_limits( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->monitor_min ); \ + _mbg_swab16( &(_p)->monitor_max ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + + + +/** + * @brief NTP "discard" rate limiting settings as described at ntp.org's manual + */ +typedef struct +{ + uint8_t avg; ///< Specify the minimum average interpacket spacing in log2 s. + uint8_t min; ///< Specify the minimum interpacket spacing (guard time) in seconds. + uint16_t monitor; ///< ### TODO Which is the unit of this field? + uint32_t reserved; ///< Possible future use + +} NTP_DISCARD_SETTINGS; + +#define _mbg_swab_ntp_discard_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->monitor ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + + +/** + * @brief Enumeration of NTP supported statistics + * + * @see ::NTP_GLB_STATS_MASKS + */ +enum NTP_GLB_STATS_FLAGS +{ + NTP_GLB_STATS_FLAG_ENABLE, ///< NTP stats can generally be enabled or disabled + NTP_GLB_STATS_FLAG_CLOCKSTATS, ///< NTP supports clockstats + NTP_GLB_STATS_FLAG_CRYPTOSTATS, ///< NTP supports cryptostats + NTP_GLB_STATS_FLAG_LOOPSTATS, ///< NTP supports loopstats + NTP_GLB_STATS_FLAG_PEERSTATS, ///< NTP supports peerstats + NTP_GLB_STATS_FLAG_RAWSTATS, ///< NTP supports rawstats + NTP_GLB_STATS_FLAG_SYSSTATS, ///< NTP supports sysstats + NTP_GLB_STATS_FLAG_FILEGEN, ///< NTP supports sets of files + ///< If flag is set there are structures needed + ///< that are not avail right now. Future use + N_NTP_GLB_STATS_FLAGS +}; + + + +/** + * @brief Flag masks associated with ::NTP_GLB_STATS_FLAGS + * + * @see ::NTP_GLB_STATS_FLAGS + */ +enum NTP_GLB_STATS_MASKS +{ + NTP_GLB_STATS_MSK_ENABLE = ( 1UL << NTP_GLB_STATS_FLAG_ENABLE ), ///< See ::NTP_GLB_STATS_FLAG_ENABLE + NTP_GLB_STATS_MSK_CLOCKSTATS = ( 1UL << NTP_GLB_STATS_FLAG_CLOCKSTATS ), ///< See ::NTP_GLB_STATS_FLAG_CLOCKSTATS + NTP_GLB_STATS_MSK_CRYPTOSTATS = ( 1UL << NTP_GLB_STATS_FLAG_CRYPTOSTATS ), ///< See ::NTP_GLB_STATS_FLAG_CRYPTOSTATS + NTP_GLB_STATS_MSK_LOOPSTATS = ( 1UL << NTP_GLB_STATS_FLAG_LOOPSTATS ), ///< See ::NTP_GLB_STATS_FLAG_LOOPSTATS + NTP_GLB_STATS_MSK_PEERSTATS = ( 1UL << NTP_GLB_STATS_FLAG_PEERSTATS ), ///< See ::NTP_GLB_STATS_FLAG_PEERSTATS + NTP_GLB_STATS_MSK_RAWSTATS = ( 1UL << NTP_GLB_STATS_FLAG_RAWSTATS ), ///< See ::NTP_GLB_STATS_FLAG_RAWSTATS + NTP_GLB_STATS_MSK_SYSSTATS = ( 1UL << NTP_GLB_STATS_FLAG_SYSSTATS ), ///< See ::NTP_GLB_STATS_FLAG_SYSSTATS + NTP_GLB_STATS_MSK_FILEGEN = ( 1UL << NTP_GLB_STATS_FLAG_FILEGEN ) ///< See ::NTP_GLB_STATS_FLAG_FILEGEN +}; + + + +/** + * @brief Global NTP statistics settings to be read from / written to a device + * + * ::NTP_GLB_STATS_MSK_ENABLE is the switch to enable / disable statistics in + * general. In case the bit is set all other bits stand for special statistic + * types that can be enabled or disabled by setting or deleting its specific bit. + */ +typedef struct +{ + uint32_t flags; ///< See ::NTP_GLB_STATS_MASKS + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + +} NTP_STATS_GLB_SETTINGS; + +#define _mbg_swab_ntp_stats_glb_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) + + +/** + * @brief NTP statistics settings + * + * This structure can be used to determine possible NTP statistic options + * and can be queried if ::NTP_MSK_STATISTICS bit is set in ::NTP_GLB_INFO::supp_flags. + */ +typedef struct +{ + NTP_STATS_GLB_SETTINGS settings; ///< See ::NTP_STATS_GLB_SETTINGS + + uint32_t supp_stats; ///< See ::NTP_GLB_STATS_MASKS + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + uint32_t reserved_3; ///< Future use + +} NTP_STATS_GLB_INFO; + +#define _mbg_swab_ntp_stats_glb_info( _p ) \ +do \ +{ \ + _mbg_swab_ntp_stats_glb_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_stats ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) + + +#else // !defined( _PRELIMINARY_CODE ), dummy declarations + + typedef int NTP_RESTR_LIMITS; + typedef int NTP_RESTR; + typedef int NTP_RESTR_IDX; + typedef int NTP_DISCARD_LIMITS; + typedef int NTP_DISCARD_SETTINGS; + typedef int NTP_STATS_GLB_SETTINGS; + typedef int NTP_STATS_GLB_INFO; + +#endif // defined( _PRELIMINARY_CODE ) + + +/** + * @brief Enumeration of supported refclock types + * + * Used with ::NTP_REFCLK_CFG_SETTINGS::type + * + * @see https://www.eecis.udel.edu/~mills/ntp/html/refclock.html + * @see ::NTP_REFCLK_TYPE_MSKS + */ +enum NTP_REFCLK_TYPES +{ + NTP_REFCLK_TYPE_LOCAL, ///< NTP local clock + NTP_REFCLK_TYPE_TRUETIME, ///< NTP Truetime driver + NTP_REFCLK_TYPE_PARSE, ///< NTP parse driver + NTP_REFCLK_TYPE_NMEA, ///< NTP NMEA driver + NTP_REFCLK_TYPE_PPS, ///< NTP atom driver (standalone PPS) + NTP_REFCLK_TYPE_SHM, ///< NTP shared memory driver + N_NTP_REFCLK_TYPES +}; + + + +/** + * @brief Bit masks associated with ::NTP_REFCLK_TYPES + * + * Used with ::NTP_REFCLK_CFG_INFO::supp_refclk_types + * + * @see ::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 +}; + + +/** + * @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 + * + * The refclock interface provided by ntpd supports a number of flags + * (flag1..flag4) which can be "fudged" in ntp.conf to control specific + * features of a particular refclock driver, e.g.: + * "fudge 127.127.8.0 flag1 1" + * + * Which feature is controlled by which flag depends on the refclock + * driver type, so usually each flag has a different meaning for + * different refclock types. + * + * There are different cases to be distinguished: + * + * - if a flag is not specified at all in ntp.conf then + * the controlled feature is enabled or disabled + * according to the driver's default settings + * + * - if a flag is specified as '0' or '1' in ntp.conf then + * the controlled feature is enabled or disabled + * according to the flag's setting. + * + * Thus, the bit mask in ::NTP_REFCLK_CFG_SETTINGS::drv_flags_enable + * controls if the associated fudge flag should be specified in ntp.conf, + * and if it is specified then the associated bit in + * ::NTP_REFCLK_CFG_SETTINGS::drv_flags_value controls if the fudge flag + * is set to 0 or 1. + * + * @anchor NTP_FUDGE_FLAG_NUMBERS @{ */ + +#define NTP_MIN_REFCLOCK_FUDGE_FLAG 1 ///< minimum refclock fudge flag number, associated with bit 0 +#define N_NTP_REFCLOCK_FUDGE_FLAGS 4 ///< the number of supported fudge flags + +/** @} anchor NTP_FUDGE_FLAG_NUMBERS */ + + +/** + * @brief NTP refclock specific settings + * + * Used to configure a NTP refclock. + */ +typedef struct +{ + uint8_t type; ///< See ::NTP_REFCLK_TYPES + uint8_t instance; ///< Refclock instance of the specified type. Usually up to 4 instances of the same type are supported by ntpd. + uint8_t mode; ///< Driver specific "mode" ::FIXME Flag to enable "mode"? + int8_t stratum; ///< Stratum number to be fudged; -1 if unspecified and thus default is to be used + + int8_t refid[4]; ///< Reference id used by driver ::FIXME Flag to enable "refid"? + + uint8_t minpoll; ///< Minimum polling interval, [log2 seconds], 0 if unused/unspecified + uint8_t maxpoll; ///< Maximum polling interval, [log2 seconds], 0 if unused/unspecified + uint8_t reserved_1; ///< Future use + uint8_t reserved_2; ///< Future use + + NANO_TIME_64 time1; ///< Driver specific + NANO_TIME_64 time2; ///< Driver specific + + uint16_t drv_flags_enable; ///< Enable/disable driver specific flags, see @ref NTP_FUDGE_FLAG_NUMBERS + uint16_t drv_flags_value; ///< 0 or 1, if (drv_flags_enable & x) == 1, see @ref NTP_FUDGE_FLAG_NUMBERS + + uint32_t flags; ///< See @ref NTP_FLAG_MASKS. Only flags specified in ::FIXME can be used here. + + uint32_t reserved_3; ///< Future use + +} NTP_REFCLK_CFG_SETTINGS; + +#define _mbg_swab_ntp_refclk_cfg_settings( _p ) \ +do \ +{ \ + _mbg_swab_nano_time_64( &(_p)->time1 ); \ + _mbg_swab_nano_time_64( &(_p)->time2 ); \ + _mbg_swab16( &(_p)->drv_flags_enable ); \ + _mbg_swab16( &(_p)->drv_flags_value ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief NTP refclock settings index + * + * @see ::NTP_REFCLK_CFG_SETTINGS + */ +typedef struct +{ + uint32_t idx; + NTP_REFCLK_CFG_SETTINGS settings; ///< See ::NTP_REFCLK_CFG_SETTINGS + +} NTP_REFCLK_CFG_SETTINGS_IDX; + +#define _mbg_swab_ntp_refclk_cfg_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_refclk_cfg_settings( &(_p)->settings ); \ +} while ( 0 ) + +/** + * @brief Enumeration of NTP refclock config flags + * + * @see @ref NTP_REFCLK_CFG_FLAGS + */ +enum NTP_REFCLK_CFG_FLAGS +{ + NTP_REFCLK_CFG_TRUSTTIME, ///< Trusttime of refclk configurable + + N_NTP_REFCLK_CFG_FLAGS +}; + + +/** + * @brief Flag masks associated with ::NTP_REFCLK_CFG_FLAGS + * + * Used with ::NTP_REFCLK_CFG_INFO::supp_cfgs, + * + * @see ::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 + + +/** @} anchor NTP_REFCLK_CFG_FLAGS_MASKS */ + +/** + * @brief NTP refclock configuration and supported refclock types + * + * This structure can be used to set a NTP refclock's configuration + * and get to know its overall supported refclocks. + */ +typedef struct +{ + NTP_REFCLK_CFG_SETTINGS settings; ///< See ::NTP_REFCLK_CFG_SETTINGS + + uint8_t supp_cfgs; ///< See @ref NTP_REFCLK_CFG_FLAGS + uint8_t reserved; ///< Future use + uint16_t supp_refclk_types; ///< See ::NTP_REFCLK_TYPE_MSKS + +} NTP_REFCLK_CFG_INFO; + +#define _mbg_swab_ntp_refclk_cfg_info( _p ) \ +do \ +{ \ + _mbg_swab_ntp_refclk_cfg_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_refclk_types ); \ +} while ( 0 ) + + + +/** + * @brief NTP refclock info, with index + * + * @see ::NTP_REFCLK_CFG_INFO + */ +typedef struct +{ + uint32_t idx; + NTP_REFCLK_CFG_INFO info; + +} NTP_REFCLK_CFG_INFO_IDX; + +#define _mbg_swab_ntp_refclk_cfg_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_refclk_cfg_info( &(_p)->info ); \ +} while ( 0 ) + + +/** + * @brief Enumeration of NTP supported symmetric key hashing algorithms + * + * @see ::NTP_SYMM_KEY_HASH_MASKS + * + * @note Support of external libraries (e.g.: OpenSSL) may be needed for + * some hashing algorithms. + */ +enum NTP_SYMM_KEY_HASHES +{ + NTP_SYMM_KEY_HASH_MD5, ///< NTP supports MD5 as key hashing algorithm + NTP_SYMM_KEY_HASH_SHA1, ///< NTP supports SHA1 as key hashing algorithm + N_NTP_SYMM_KEY_HASHES +}; + + + +/** + * @brief Flag masks associated with ::NTP_SYMM_KEY_HASHES + * + * @see ::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 +}; + + +/** + * @brief Name strings for defined NTP symm key hashes + * + * @see ::NTP_SYMM_KEY_HASHES + */ +#define NTP_SYMM_KEY_HASHES_STRS \ +{ \ + "MD5", \ + "SHA1" \ +} + + + +/** + * @brief General NTP symmetric key limits to be read from a device + * + * ::NTP_SYMM_KEY_LIMITS::supp_hashes specifies supported hashing algorithms + * to create keys with. See ::NTP_SYMM_KEY_HASH_MASKS. Structure can be queried + * if ::NTP_MSK_SYMM_KEYS is set in ::NTP_GLB_INFO::supp_flags + */ +typedef struct +{ + uint16_t supp_hashes; ///< See ::NTP_SYMM_KEY_HASH_MASKS + uint16_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + uint32_t reserved_3; ///< Future use + uint32_t reserved_4; ///< Future use + +} NTP_SYMM_KEY_LIMITS; + +#define _mbg_swab_ntp_symm_key_limits( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->supp_hashes ); \ +} while ( 0 ) + + + +/// Maximum length of a symmetric key. 128 byte was chosen to be +/// 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 + + + +/** + * @brief NTP symmetric key specific settings + * + * This structure is used to configure a symmetric key for NTP. + */ +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 reserved_2; ///< Future use + uint8_t num_ip_addr; ///< Number of configured ip addresses + uint8_t reserved_3; ///< Future use + + 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 + +} NTP_SYMM_KEY_SETTINGS; + +#define _mbg_swab_ntp_symm_key_settings( _p ) \ +do \ +{ \ + unsigned i; \ + \ + _mbg_swab16( &(_p)->id ); \ + \ + for ( i = 0; i < N_NTP_SYMM_KEY_MAX_IP_ADDR; ++i) \ + _mbg_swab_ip_addr( &(_p)->ip_addr[i] ); \ +} while ( 0 ) + + + +/** + * @brief NTP symmetric key settings, with index + * + * @see ::NTP_SYMM_KEY_SETTINGS + */ +typedef struct +{ + uint32_t idx; + NTP_SYMM_KEY_SETTINGS settings; + +} NTP_SYMM_KEY_SETTINGS_IDX; + +#define _mbg_swab_ntp_symm_key_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_symm_key_settings( &(_p)->settings ); \ +} while ( 0 ) + + +/** + * @brief NTP symmkey info + * + * This structure is used to query a symmetric key for NTP. + */ +typedef struct +{ + NTP_SYMM_KEY_SETTINGS settings; + + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + uint32_t reserved_3; ///< Future use + uint32_t reserved_4; ///< Future use + +} NTP_SYMM_KEY_INFO; + +#define _mbg_swab_ntp_symm_key_info( _p ) \ +do \ +{ \ + _mbg_swab_ntp_symm_key_settings( &(_p)->settings ); \ +} while ( 0 ) + + +/** + * @brief NTP symm key info, with index + * + * @see ::NTP_SYMM_KEY_INFO + */ +typedef struct +{ + uint32_t idx; + NTP_SYMM_KEY_INFO info; + +} NTP_SYMM_KEY_INFO_IDX; + +#define _mbg_swab_ntp_symm_key_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_symm_key_info( &(_p)->info ); \ +} while ( 0 ) + + +/** + * @brief NTP trusted key settings + * + * This structure is used to configure a trusted symmetric key for NTP. + */ +typedef struct +{ + uint16_t id; ///< Configurable key id (1..65534) + uint16_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + +} NTP_TRUSTED_KEY_SETTINGS; + +#define _mbg_swab_ntp_trusted_key_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->id ); \ +} while ( 0 ) + + +/** + * @brief NTP trusted key settings, with index + * + * @see ::NTP_TRUSTED_KEY_SETTINGS + */ +typedef struct +{ + uint32_t idx; + NTP_TRUSTED_KEY_SETTINGS settings; + +} NTP_TRUSTED_KEY_SETTINGS_IDX; + +#define _mbg_swab_ntp_trusted_key_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_trusted_key_settings( &(_p)->settings ); \ +} while ( 0 ) + +/** + * @brief NTP trusted key info + * + * This structure is used to query a trusted symmetric key for NTP. + */ +typedef struct +{ + NTP_TRUSTED_KEY_SETTINGS settings; + + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + uint32_t reserved_3; ///< Future use + uint32_t reserved_4; ///< Future use + +} NTP_TRUSTED_KEY_INFO; + +#define _mbg_swab_ntp_trusted_key_info( _p ) \ +do \ +{ \ + _mbg_swab_ntp_trusted_key_settings( &(_p)->settings ); \ +} while ( 0 ) + + +/** + * @brief NTP trusted key info, with index + * + * @see ::NTP_TRUSTED_KEY_INFO + */ +typedef struct +{ + uint32_t idx; + NTP_TRUSTED_KEY_INFO info; + +} NTP_TRUSTED_KEY_INFO_IDX; + +#define _mbg_swab_ntp_trusted_key_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_trusted_key_info( &(_p)->info ); \ +} while ( 0 ) + + +/** + * @brief Enumeration of NTP supported (various) misc options + * + * @see ::NTP_MISC_MSKS + */ +enum NTP_MISC_FLAGS +{ + NTP_MISC_FLAG_DRIFTFILE, ///< NTP supports driftfile + NTP_MISC_FLAG_ORPHAN_MODE, ///< NTP supports orphan mode + NTP_MISC_FLAG_LEAPFILE, ///< NTP supports leapfile + N_NTP_MISC_FLAGS +}; + + + +/** + * @brief Flag masks associated with ::NTP_MISC_FLAGS + * + * @see ::NTP_MISC_FLAGS + */ +enum NTP_MISC_MSKS +{ + NTP_MISC_MSK_DRIFTFILE = ( 1UL << NTP_MISC_FLAG_DRIFTFILE ), ///< See ::NTP_MISC_FLAG_DRIFTFILE + NTP_MISC_MSK_ORPHAN_MODE = ( 1UL << NTP_MISC_FLAG_ORPHAN_MODE ), ///< See ::NTP_MISC_FLAG_ORPHAN_MODE + NTP_MISC_MSK_LEAPFILE = ( 1UL << NTP_MISC_FLAG_LEAPFILE ) ///< See ::NTP_MISC_FLAG_LEAPFILE +}; + + + +/** + * @brief General NTP misc limits to be read from a device + * + * This structure can be used to determine various NTP options + * and can be queried if ::NTP_MSK_MISCELLANEOUS bit is set in ::NTP_GLB_INFO::supp_flags. + */ +typedef struct +{ + uint32_t supp_flags; ///< See ::NTP_MISC_MSKS + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + +} NTP_MISC_LIMITS; + +#define _mbg_swab_ntp_misc_limits( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + + +/** + * @brief NTP driftfile settings to be read from / written to a device + * + * If ::NTP_MISC_MSK_DRIFTFILE is set in ::NTP_MISC_LIMITS::supp_flags + * ::NTP_MISC_DRIFTFILE_SETTINGS can be read / written. + */ +typedef struct +{ + uint8_t enable; ///< Enable / disable writing a driftfile + uint8_t reserved_1; ///< Future use + uint16_t reserved_2; ///< Future use + +} NTP_MISC_DRIFTFILE_SETTINGS; + +#define _mbg_swab_ntp_misc_driftfile_settings( _p ) \ +do \ +{ \ +} while ( 0 ) + + +/** + * @brief Enumeration of NTP supported (various) misc options + * + * @see ::NTP_ORPHAN_MODE_MSK + */ +enum NTP_ORPHAN_MODE_FLAGS +{ + NTP_ORPHAN_MODE_FLAG_SUPP_DISABLE, ///< Orphan Mode support disabling + + N_NTP_ORPHAN_MODE_FLAGS +}; + + + +/** + * @brief Flag masks associated with ::NTP_ORPHAN_MODE_FLAGS + * + * @see ::NTP_ORPHAN_MODE_FLAGS + */ +enum NTP_ORPHAN_MODE_MSK +{ + NTP_ORPHAN_MODE_MSK_SUPP_DISABLE = ( 1UL << NTP_ORPHAN_MODE_FLAG_SUPP_DISABLE ) ///< See ::NTP_ORPHAN_MODE_FLAG_SUPP_DISABLE +}; + + +/** + * @brief NTP orphan mode settings to be read from / written to a device + * + * If ::NTP_MISC_MSK_ORPHAN_MODE is set in ::NTP_MISC_LIMITS::supp_flags + * ::NTP_MISC_ORPHAN_MODE_SETTINGS can be read / written. + */ +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 + + uint32_t reserved_2; ///< Future use + +} NTP_MISC_ORPHAN_MODE_SETTINGS; + +#define _mbg_swab_ntp_misc_orphan_mode_settings( _p ) \ +do \ +{ \ +} while ( 0 ) + + +/** + * @brief NTP orphan mode info + * + */ +typedef struct +{ + NTP_MISC_ORPHAN_MODE_SETTINGS settings; ///< See ::NTP_MISC_ORPHAN_MODE_SETTINGS + + uint32_t supp_flags; ///< See ::NTP_ORPHAN_MODE_MSK + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + uint32_t reserved_3; ///< Future use + +} NTP_MISC_ORPHAN_MODE_INFO; + +#define _mbg_swab_ntp_misc_orphan_mode_info( _p ) \ +do \ +{ \ + _mbg_swab_ntp_misc_orphan_mode_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + +/** + * @brief NTP leapfile settings to be read from / written to a device + * + * If ::NTP_MISC_MSK_LEAPFILE is set in ::NTP_MISC_LIMITS::supp_flags + * ::NTP_MISC_LEAPFILE_SETTINGS can be read / written. + */ +typedef struct +{ + uint8_t enable; ///< Generally enable / disable leapfile + uint8_t reserved_1; ///< Stratum level when no ref source available + uint16_t reserved_2; ///< Future use + +} NTP_MISC_LEAPFILE_SETTINGS; + +#define _mbg_swab_ntp_misc_leapfile_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->reserved_2 ); \ +} while ( 0 ) + + +/** + * @brief Client settings of an NTP device + * + * This structure should be sent to an NTP client to configure client parameters + */ +typedef struct +{ + uint8_t num_peers; ///< number available peers + uint8_t reserved_1; ///< reserved, currently 0 + uint16_t reserved_2; ///< reserved, currently 0 + + uint32_t reserved_3; ///< reserved, currently 0 + + uint32_t flags; ///< NTP flags, see @ref NTP_FLAG_MASKS + +} NTP_CLNT_MODE_SETTINGS; + +#define _mbg_swab_ntp_clnt_mode_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Client settings info of an NTP device + * + * This structure can be used to determine possible NTP client settings and the current configuration + */ +typedef struct +{ + NTP_CLNT_MODE_SETTINGS settings; + + uint8_t n_supp_peers; ///< maximal number of configurable peers + uint8_t n_supp_pref_peers; ///< maximal number of configurable preferred ref sources + uint8_t poll_intv_min; ///< minimal supported NTP polling interval + uint8_t poll_intv_max; ///< maximal supported NTP polling interval + + uint32_t reserved_1; ///< reserved, currently 0 + uint32_t reserved_2; ///< reserved, currently 0 + + uint32_t supp_flags; ///< supported NTP flags, see @ref NTP_FLAG_MASKS + uint32_t supp_peer_flags; ///< supported NTP flags for peers, see @ref NTP_FLAG_MASKS + +} NTP_CLNT_MODE_INFO; + +#define _mbg_swab_ntp_clnt_mode_info( _p ) \ +do \ +{ \ + _mbg_swab_ntp_clnt_mode_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->supp_peer_flags ); \ +} while ( 0 ) + + + +/** + * @brief General NTP peer settings limits to be read from a device + * + * Used to query from a device how many NTP associations are supported + * by the device, then index 0..::NTP_PEER_LIMITS::n_cur_peers-1 + * peer records can be read from a device. A maximum of + * ::NTP_PEER_LIMITS::n_supp_peers can be configured at all. + */ +typedef struct +{ + uint16_t n_supp_peers; ///< maximum number of configurable peers + uint16_t n_cur_peers; ///< current number of configured peers + + uint8_t poll_intv_min; ///< minimum supported NTP polling interval + uint8_t poll_intv_max; ///< maximum supported NTP polling interval + uint8_t reserved_1; ///< reserved, currently 0 + uint8_t reserved_2; ///< reserved, currently 0 + + uint32_t supp_assoc_types; ///< supported types of NTP associations + uint32_t reserved_3; ///< reserved, currently 0 + + uint32_t supp_flags_server; ///< supported flags for unicast associations + uint32_t supp_flags_peer; ///< supported flags for unicast symmetric-active assocations + uint32_t supp_flags_pool; ///< supported flags for unicast pool associations + uint32_t supp_flags_broadcast; ///< supported flags for broadcast associations + uint32_t supp_flags_multicast; ///< supported flags for multicast associations + uint32_t supp_flags_manycast; ///< supported flags for manycast associations + uint32_t supp_flags_broadcastclient; ///< supported flags for broadcast client associations + uint32_t supp_flags_multicastclient; ///< supported flags for multicast client associations + uint32_t supp_flags_manycastclient; ///< supported flags for manycast client associations + uint32_t reserved_4; ///< reserved, currently 0 + uint32_t reserved_5; ///< reserved, currently 0 + uint32_t reserved_6; ///< reserved, currently 0 + +} NTP_PEER_LIMITS; + +#define _mbg_swab_ntp_peer_limits( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->n_supp_peers ); \ + _mbg_swab16( &(_p)->n_cur_peers ); \ + _mbg_swab32( &(_p)->supp_assoc_types ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->supp_flags_server ); \ + _mbg_swab32( &(_p)->supp_flags_peer ); \ + _mbg_swab32( &(_p)->supp_flags_pool ); \ + _mbg_swab32( &(_p)->supp_flags_broadcast ); \ + _mbg_swab32( &(_p)->supp_flags_multicast ); \ + _mbg_swab32( &(_p)->supp_flags_manycast ); \ + _mbg_swab32( &(_p)->supp_flags_broadcastclient ); \ + _mbg_swab32( &(_p)->supp_flags_multicastclient ); \ + _mbg_swab32( &(_p)->supp_flags_manycastclient ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ + _mbg_swab32( &(_p)->reserved_5 ); \ + _mbg_swab32( &(_p)->reserved_6 ); \ +} while ( 0 ) + + + +/** + * @brief Peer settings for NTP devices to configure an upload NTP server + * + * This structure should be read from the NTP client device to retrieve the + * current settings and capabilities. The number of supported peers is + * ::NTP_CLNT_MODE_INFO::n_supp_peers. + * + * @note The ::NTP_PEER_SETTINGS_IDX structure should be send back + * to the device to save the configuration. + */ +typedef struct +{ + MBG_HOSTNAME hostname; ///< hostname or IP address of the peer, not used + ///< when the NTP_BROADCASTCLIENT flag is set + + uint8_t min_poll; ///< minimal configurable NTP polling interval + uint8_t max_poll; ///< maximal configurable NTP polling interval + uint8_t ttl; ///< time-to-live to use with broadcast/multicast/manycast + uint8_t reserved_1; ///< reserved, currently 0 + + uint32_t key; ///< ID of the symmetric key used with this association, + ///< this must be in the range 1-65534, 0 = disabled + uint32_t reserved_3; ///< reserved, currently 0 + uint32_t reserved_4; ///< reserved, currently 0 + + uint32_t flags; ///< additional options configured, see @ref NTP_FLAG_MASKS + +} NTP_PEER_SETTINGS; + +#define _mbg_swab_ntp_peer_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->key ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Peer settings for NTP devices + * + * @see ::NTP_PEER_SETTINGS + */ +typedef struct +{ + uint32_t idx; + NTP_PEER_SETTINGS peer_settings; + +} NTP_PEER_SETTINGS_IDX; + +#define _mbg_swab_ntp_peer_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_peer_settings( &(_p)->peer_settings ); \ +} while ( 0 ) + + +/** + * @brief Server settings of an NTP device + * + * This structure should be sent to an NTP server to configure server parameters + */ +typedef struct +{ + uint8_t num_refclks; ///< number of available refclks @ref NTP_REFCLK_CFG_INFO + uint8_t reserved_1; ///< reserved, currently 0 + uint16_t reserved_2; ///< reserved, currently 0 + + uint32_t reserved_3; ///< reserved, currently 0 + + uint32_t flags; ///< NTP flags, see @ref NTP_FLAG_MASKS + +} NTP_SRV_MODE_SETTINGS; + +#define _mbg_swab_ntp_srv_mode_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + +/** + * @brief Server settings info of an NTP device + * + * This structure should be used to query an NTP server configuration from a device + */ +typedef struct +{ + NTP_SRV_MODE_SETTINGS settings; + + uint8_t max_refclks; ///< number of supported refclks @ref NTP_REFCLK_CFG_INFO + uint8_t reserved_1; ///< reserved, currently 0 + uint16_t reserved_2; ///< reserved, currently 0 + + uint32_t reserved_3; ///< reserved, currently 0 + + uint32_t supp_flags; ///< supported NTP flags, see @ref NTP_FLAG_MASKS + +} NTP_SRV_MODE_INFO; + +#define _mbg_swab_ntp_srv_mode_info( _p ) \ +do \ +{ \ + _mbg_swab_ntp_srv_mode_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + +/** + * @brief Structure that represents a timestamp in NTP Short Format + * + * Maximal value for seconds is 65535. + * Resolution of fractions is 15 microseconds. + */ +typedef struct +{ + uint16_t seconds; + uint16_t fractions; + +} NTP_SHORT_TSTAMP; + +#define _mbg_swab_ntp_short_tstamp( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->seconds ); \ + _mbg_swab16( &(_p)->fractions ); \ +} + + + +/** + * @brief Structure that represents a timestamp in NTP Timestamp Format + */ +typedef struct +{ + uint32_t seconds; ///< seconds since NTP epoch, see ::NTP_SEC_BIAS + uint32_t fractions; ///< binary fractional part of a second, 0xFFFFFFFF -> 0.9999999... s (resolution 2^-32s =~ 233 ps) + +} NTP_TSTAMP; + +#define _mbg_swab_ntp_tstamp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->seconds ); \ + _mbg_swab32( &(_p)->fractions ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of known NTP implementations + * + * Used with ::NTP_SYS_STATE::impl_type + */ +enum NTP_IMPL +{ + NTP_IMPL_UNKNOWN = 0, ///< Unknown NTP implementation + NTP_IMPL_NTPD, ///< Network Time Protocol daemon (ntpd) + NTP_IMPL_NTPDATE, ///< NTP client only (ntpdate) + NTP_IMPL_SNTP, ///< Simple Network Time Protocol (sntp) + NTP_IMPL_W32TIME, ///< Windows time service (w32time) + NTP_IMPL_MBGNTP, ///< Meinberg NTP implementation (mbgntp) + N_NTP_IMPLS +}; + +/* + * Default initializers for English leapsecond string names. Initializers + * for multi-language strings can be found in tmonlstr.h. + */ +#define MBG_NTP_IMPL_STR_ENG "Implemetation Type:" + +#define MBG_NTP_IMPL_STR_ENG_UNKNOWN "Unknown NTP implementation" +#define MBG_NTP_IMPL_STR_ENG_NTPD "Network Time Protocol daemon (ntpd)" +#define MBG_NTP_IMPL_STR_ENG_NTPDATE "NTP client only (ntpdate)" +#define MBG_NTP_IMPL_STR_ENG_SNTP "Simple Network Time Protocol (sntp)" +#define MBG_NTP_IMPL_STR_ENG_W32TIME "Windows time service (w32time)" +#define MBG_NTP_IMPL_STR_ENG_MBGNTP "Meinberg NTP implementation (mbgntp)" + + +#define MBG_NTP_IMPL_NAMES_ENG \ +{ \ + MBG_NTP_IMPL_STR_ENG_UNKNOWN, \ + MBG_NTP_IMPL_STR_ENG_NTPD, \ + MBG_NTP_IMPL_STR_ENG_NTPDATE, \ + MBG_NTP_IMPL_STR_ENG_SNTP, \ + MBG_NTP_IMPL_STR_ENG_W32TIME, \ + MBG_NTP_IMPL_STR_ENG_MBGNTP \ +} + + + +/** + * @brief Enumeration of CPU types using NTP + * + * Used with ::NTP_SYS_STATE::cpu_type + */ +enum NTP_CPU_TYPES +{ + NTP_CPU_TYPE_UNKNOWN = 0, + NTP_CPU_TYPE_X86, + NTP_CPU_TYPE_I386, + NTP_CPU_TYPE_I486, + NTP_CPU_TYPE_I586, + NTP_CPU_TYPE_I686, + NTP_CPU_TYPE_X64, + NTP_CPU_TYPE_X86_64, + NTP_CPU_TYPE_AMD64, + NTP_CPU_TYPE_SUN4U, + NTP_CPU_TYPE_ARM, + N_NTP_CPU_TYPES +}; + + + +/** + * @brief Name strings for known CPU types using NTP + * + * @see ::NTP_CPU_TYPES + */ +#define NTP_CPU_TYPES_STRS \ +{ \ + "Unknown", \ + "x86", \ + "i386", \ + "i486", \ + "i586", \ + "i686", \ + "x64", \ + "x86_64", \ + "amd64", \ + "sun4u", \ + "arm" \ +} + + + +/** + * @brief Enumeration of operating systems using NTP + * + * Used with ::NTP_SYS_STATE::system +*/ +enum NTP_SYSTEMS +{ + NTP_SYSTEM_UNKNOWN = 0, + NTP_SYSTEM_NONE, + NTP_SYSTEM_WINDOWS, + NTP_SYSTEM_LINUX, + NTP_SYSTEM_BSD, + NTP_SYSTEM_SOLARIS, + N_NTP_SYSTEMS +}; + + + +/** + * @brief Name strings for operating systens using NTP + * + * @see ::NTP_SYSTEMS + */ +#define NTP_SYSTEMS_STRS \ +{ \ + "Unknown", \ + "No OS", \ + "Windows", \ + "Linux", \ + "BSD", \ + "Solaris" \ +} + + + +/** + * @brief Enumeration of NTP leap indication bits + * + * Used with ::NTP_SYS_STATE::leap_ind + * + */ +enum NTP_LI_BITS +{ + NTP_LEAP_NONE = 0, ///< normal synchronized state + NTP_LEAP_ADD_SEC, ///< insert second after 23:59:59 of the current day + NTP_LEAP_DEL_SEC, ///< delete second 23:59:59 of the current day + NTP_LEAP_ALARM, ///< never synchronized + N_NTP_LI_BITS +}; + + + +/* + * Default initializers for English leapsecond string names. Initializers + * for multi-language strings can be found in tmonlstr.h. + */ +#define MBG_NTP_LEAP_STR_ENG "Leapsecond indication:" + +#define MBG_NTP_LEAP_STR_ENG_NONE "None" +#define MBG_NTP_LEAP_STR_ENG_ADD_SEC "Insert second" +#define MBG_NTP_LEAP_STR_ENG_DEL_SEC "Delete second" +#define MBG_NTP_LEAP_STR_ENG_ALARM "Alarm" + +#define MBG_NTP_LEAP_NAMES_ENG \ +{ \ + MBG_NTP_LEAP_STR_ENG_NONE, \ + MBG_NTP_LEAP_STR_ENG_ADD_SEC, \ + MBG_NTP_LEAP_STR_ENG_DEL_SEC, \ + MBG_NTP_LEAP_STR_ENG_ALARM \ +} + + + +/** + * @brief Enumeration of NTP synchronization source bits + * + * Used with ::NTP_SYS_STATE::sys_sync_src + * + */ +enum NTP_SYNC_SRC_BITS +{ + NTP_SYNC_SRC_UNSPEC = 0, ///< not yet synchronized + NTP_SYNC_SRC_PPS, ///< pulse-per-second signal (Cs, Ru, GPS, etc.) + NTP_SYNC_SRC_LF_RADIO, ///< VLF/LF radio (WWVB, DCF77, etc.) + NTP_SYNC_SRC_HF_RADIO, ///< MF/HF radio (WWV, etc.) + NTP_SYNC_SRC_UHF_RADIO, ///< VHF/UHF radio/satellite (GPS, Galileo, etc.) + NTP_SYNC_SRC_LOCAL, ///< local timecode (IRIG, LOCAL driver, etc.) + NTP_SYNC_SRC_NTP, ///< NTP + NTP_SYNC_SRC_OTHER, ///< other (IEEE 1588, openntp, crony, etc.) + NTP_SYNC_SRC_WRISTWATCH, ///< eyeball and wristwatch + NTP_SYNC_SRC_TELEPHONE, ///< telephone modem (ACTS, PTB, etc.) + N_NTP_SYNC_SRC_BITS +}; + + + +/* + * Default initializers for English sync source string names. Initializers + * for multi-language strings can be found in tmonlstr.h. + */ +#define MBG_NTP_SYNC_SRC_STR_ENG_LABEL "Sync Source:" + +#define MBG_NTP_SYNC_SRC_STR_ENG_UNSPEC "Not yet synchronized" +#define MBG_NTP_SYNC_SRC_STR_ENG_PPS "Pulse per second signal" +#define MBG_NTP_SYNC_SRC_STR_ENG_LF_RADIO "VLF/LF radio" +#define MBG_NTP_SYNC_SRC_STR_ENG_HF_RADIO "MF/HF radio" +#define MBG_NTP_SYNC_SRC_STR_ENG_UHF_RADIO "VHF/UHF radio/satellite" +#define MBG_NTP_SYNC_SRC_STR_ENG_LOCAL "local timecode" +#define MBG_NTP_SYNC_SRC_STR_ENG_NTP "NTP" +#define MBG_NTP_SYNC_SRC_STR_ENG_OTHER "other" +#define MBG_NTP_SYNC_SRC_STR_ENG_WRISTWATCH "eyeball and wristwatch" +#define MBG_NTP_SYNC_SRC_STR_ENG_TELEPHONE "telephone modem" + +#define MBG_NTP_SYNC_SRC_NAMES_ENG \ +{ \ + MBG_NTP_SYNC_SRC_STR_ENG_UNSPEC, \ + MBG_NTP_SYNC_SRC_STR_ENG_PPS, \ + MBG_NTP_SYNC_SRC_STR_ENG_LF_RADIO, \ + MBG_NTP_SYNC_SRC_STR_ENG_HF_RADIO, \ + MBG_NTP_SYNC_SRC_STR_ENG_UHF_RADIO, \ + MBG_NTP_SYNC_SRC_STR_ENG_LOCAL, \ + MBG_NTP_SYNC_SRC_STR_ENG_NTP, \ + MBG_NTP_SYNC_SRC_STR_ENG_OTHER, \ + MBG_NTP_SYNC_SRC_STR_ENG_WRISTWATCH, \ + MBG_NTP_SYNC_SRC_STR_ENG_TELEPHONE \ +} + + + +/** + * @brief Enumeration of NTP system event message bits + * + * Used with ::NTP_SYS_STATE::sys_rec_evt + * + */ +enum NTP_SYS_EVT_BITS +{ + NTP_SYS_EVT_UNSPEC = 0, ///< unspecified NTP event + NTP_SYS_EVT_FREQ_NOT_SET, ///< frequency file not available + NTP_SYS_EVT_FREQ_SET, ///< frequency set from frequency file + NTP_SYS_EVT_SPIKE_DETECT, ///< spike detected + NTP_SYS_EVT_FREQ_MODE, ///< initial frequency training mode + NTP_SYS_EVT_CLOCK_SYNC, ///< clock synchronized + NTP_SYS_EVT_RESTART, ///< program restart + NTP_SYS_EVT_PANIC_STOP, ///< clock error more than 600 s + NTP_SYS_EVT_NO_SYSTEM_PEER, ///< no system peer + NTP_SYS_EVT_LEAP_ARMED, ///< leap second armed from file or autokey + NTP_SYS_EVT_LEAP_DISARMED, ///< leap second disarmed + NTP_SYS_EVT_LEAP_EVENT, ///< leap event + NTP_SYS_EVT_CLOCK_STEP, ///< clock stepped + NTP_SYS_EVT_KERNEL, ///< kernel information message + NTP_SYS_EVT_TAI, ///< leapsecond values update from file + NTP_SYS_EVT_STALE_LS_VALUES, ///< new NIST leapseconds file needed + N_NTP_SYS_EVT_BITS +}; + + + +/* + * Default initializers for English sync source string names. Initializers + * for multi-language strings can be found in tmonlstr.h. + */ +#define MBG_NTP_SYS_EVT_STR_ENG_CNT_LABEL "System Event Counter:" +#define MBG_NTP_SYS_EVT_STR_ENG_MSG_LABEL "System Event Message:" + +#define MBG_NTP_SYS_EVT_STR_ENG_UNSPEC "Unspecified NTP event" +#define MBG_NTP_SYS_EVT_STR_ENG_FREQ_NOT_SET "Frequency file not available" +#define MBG_NTP_SYS_EVT_STR_ENG_FREQ_SET "Frequency set from frequency file" +#define MBG_NTP_SYS_EVT_STR_ENG_SPIKE_DETECT "Spike detected" +#define MBG_NTP_SYS_EVT_STR_ENG_FREQ_MODE "Initial frequency training mode" +#define MBG_NTP_SYS_EVT_STR_ENG_CLOCK_SYNC "Clock synchronized" +#define MBG_NTP_SYS_EVT_STR_ENG_RESTART "Program restart" +#define MBG_NTP_SYS_EVT_STR_ENG_PANIC_STOP "Clock error more than 600 s" +#define MBG_NTP_SYS_EVT_STR_ENG_NO_SYSTEM_PEER "No system peer" +#define MBG_NTP_SYS_EVT_STR_ENG_LEAP_ARMED "Leap second armed from file or autokey" +#define MBG_NTP_SYS_EVT_STR_ENG_LEAP_DISARMED "Leap second disarmed" +#define MBG_NTP_SYS_EVT_STR_ENG_LEAP_EVENT "Leap event" +#define MBG_NTP_SYS_EVT_STR_ENG_CLOCK_STEP "Clock stepped" +#define MBG_NTP_SYS_EVT_STR_ENG_KERNEL "Kernel information message" +#define MBG_NTP_SYS_EVT_STR_ENG_TAI "Leap second values update from file" +#define MBG_NTP_SYS_EVT_STR_ENG_STALE_LS_VALUES "New NIST leapseconds file needed" + + +#define MBG_NTP_SYS_EVT_NAMES_ENG \ +{ \ + MBG_NTP_SYS_EVT_STR_ENG_UNSPEC, \ + MBG_NTP_SYS_EVT_STR_ENG_FREQ_NOT_SET, \ + MBG_NTP_SYS_EVT_STR_ENG_FREQ_SET, \ + MBG_NTP_SYS_EVT_STR_ENG_SPIKE_DETECT, \ + MBG_NTP_SYS_EVT_STR_ENG_FREQ_MODE, \ + MBG_NTP_SYS_EVT_STR_ENG_CLOCK_SYNC, \ + MBG_NTP_SYS_EVT_STR_ENG_RESTART, \ + MBG_NTP_SYS_EVT_STR_ENG_PANIC_STOP, \ + MBG_NTP_SYS_EVT_STR_ENG_NO_SYSTEM_PEER, \ + MBG_NTP_SYS_EVT_STR_ENG_LEAP_ARMED, \ + MBG_NTP_SYS_EVT_STR_ENG_LEAP_DISARMED, \ + MBG_NTP_SYS_EVT_STR_ENG_LEAP_EVENT, \ + MBG_NTP_SYS_EVT_STR_ENG_CLOCK_STEP, \ + MBG_NTP_SYS_EVT_STR_ENG_KERNEL, \ + MBG_NTP_SYS_EVT_STR_ENG_TAI, \ + MBG_NTP_SYS_EVT_STR_ENG_STALE_LS_VALUES \ } -/** @} group_ptp */ + +/** + * @brief Enumeration of supported NTP system state values + * + * @see ::NTP_SYS_STATE_SUPP_FLAG_MASKS + */ +enum NTP_SYS_STATE_SUPP_FLAGS +{ + NTP_SYS_STATE_SUPP_STD = 0, ///< supports standard values of ::NTP_SYS_STATE, all fields except below and reserved + NTP_SYS_STATE_SUPP_EVENTS, ///< supports sys state events (::NTP_SYS_STATE::sys_evt_cnt, ::NTP_SYS_STATE::sys_rec_evt) + NTP_SYS_STATE_SUPP_PRECISION, ///< supports precision indication, see ::NTP_SYS_STATE::precision + NTP_SYS_STATE_SUPP_ROOT_DELAY, ///< supports root delay to syspeer, see ::NTP_SYS_STATE::root_delay + NTP_SYS_STATE_SUPP_ROOT_DISP, ///< supports root dispersion, see ::NTP_SYS_STATE::root_disp + NTP_SYS_STATE_SUPP_FREQ, ///< supports frequency offset, see ::NTP_SYS_STATE::freq + NTP_SYS_STATE_SUPP_SYS_JITTER, ///< supports combined jitter, see ::NTP_SYS_STATE::sys_jitter + NTP_SYS_STATE_SUPP_CLK_JITTER, ///< supports clock jitter, see ::NTP_SYS_STATE::clk_jitter + NTP_SYS_STATE_SUPP_CLK_WANDER, ///< supports clock wander, see ::NTP_SYS_STATE::clk_wander + NTP_SYS_STATE_SUPP_SYS_ASSOC, ///< supports sys assoc ID as sys peer, see ::NTP_SYS_STATE::sys_assoc + NTP_SYS_STATE_SUPP_SERVICE_STATE, ///< supports service state, see ::NTP_SYS_STATE::service_state + N_NTP_SYS_STATE_SUPP_FLAGS +}; + + + +/** + * @brief Flag masks for NTP_SYS_STATE_SUPP_FLAGS + * + * Used with ::NTP_SYS_STATE::supp_flags + * + * @see ::NTP_SYS_STATE_SUPP_FLAGS + */ +enum NTP_SYS_STATE_SUPP_FLAG_MASKS +{ + NTP_SYS_STATE_SUPP_STD_MSK = ( 1UL << NTP_SYS_STATE_SUPP_STD ), ///< see ::NTP_SYS_STATE_SUPP_STD + NTP_SYS_STATE_SUPP_EVENTS_MSK = ( 1UL << NTP_SYS_STATE_SUPP_EVENTS ), ///< see ::NTP_SYS_STATE_SUPP_EVENTS + NTP_SYS_STATE_SUPP_PRECISION_MSK = ( 1UL << NTP_SYS_STATE_SUPP_PRECISION ), ///< see ::NTP_SYS_STATE_SUPP_PRECISION + NTP_SYS_STATE_SUPP_ROOT_DELAY_MSK = ( 1UL << NTP_SYS_STATE_SUPP_ROOT_DELAY ), ///< see ::NTP_SYS_STATE_SUPP_ROOT_DELAY + NTP_SYS_STATE_SUPP_ROOT_DISP_MSK = ( 1UL << NTP_SYS_STATE_SUPP_ROOT_DISP ), ///< see ::NTP_SYS_STATE_SUPP_ROOT_DISP + NTP_SYS_STATE_SUPP_FREQ_MSK = ( 1UL << NTP_SYS_STATE_SUPP_FREQ ), ///< see ::NTP_SYS_STATE_SUPP_FREQ + NTP_SYS_STATE_SUPP_SYS_JITTER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_SYS_JITTER ), ///< see ::NTP_SYS_STATE_SUPP_SYS_JITTER + NTP_SYS_STATE_SUPP_CLK_JITTER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_CLK_JITTER ), ///< see ::NTP_SYS_STATE_SUPP_CLK_JITTER + NTP_SYS_STATE_SUPP_CLK_WANDER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_CLK_WANDER ), ///< see ::NTP_SYS_STATE_SUPP_CLK_WANDER + 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 +}; + + +/** + * @brief Enumeration of supported NTP service state values + */ +enum MBG_NTP_SERVICE_STATES +{ + MBG_NTP_SERVICE_INIT, + MBG_NTP_SERVICE_SYNC, + MBG_NTP_SERVICE_ASYNC, + MBG_NTP_SERVICE_STOPPED, + N_MBG_NTP_SERVICE_STATES +}; + +/* + * Default initializers for NTP service state string names. + */ + +#define MBG_NTP_SERVICE_INIT_STR "NTP service initializing" +#define MBG_NTP_SERVICE_SYNC_STR "NTP service synchronized" +#define MBG_NTP_SERVICE_ASYNC_STR "NTP service not synchronized" +#define MBG_NTP_SERVICE_STOPPED_STR "NTP service stopped" + +#define MBG_NTP_SERVICE_STATES_STRS \ +{ \ + MBG_NTP_SERVICE_INIT_STR, \ + MBG_NTP_SERVICE_SYNC_STR, \ + MBG_NTP_SERVICE_ASYNC_STR, \ + MBG_NTP_SERVICE_STOPPED_STR \ +} + +/** + * @brief Structure that represents the current system status of an NTP device + * + * This structure can be requested from a monitoring program to determine the device system status + */ +typedef struct +{ + uint32_t supp_flags; ///< Supported NTP system state values, see ::NTP_SYS_STATE_SUPP_FLAG_MASKS + + uint8_t leap_ind; ///< Leap indicator, see ::NTP_LI_BITS + uint8_t sys_sync_src; ///< Current synchronization source, see ::NTP_SYNC_SRC_BITS + uint8_t sys_evt_cnt; ///< Number of events, since the last time the event code changed + uint8_t sys_rec_evt; ///< Most recent event message, see ::NTP_SYS_EVT_BITS + + uint8_t impl_type; ///< NTP implementation type, see ::NTP_IMPL + uint8_t major_version; ///< Major version number + uint8_t minor_version; ///< Minor version number + uint8_t micro_version; ///< Micro version number + + uint16_t patch_lvl; ///< Patch level number + uint8_t cpu_type; ///< Processor type, see ::NTP_CPU_TYPES + uint8_t system; ///< Operating system, see ::NTP_SYSTEMS + + uint8_t stratum; ///< Current stratum level of the system + int8_t precision; ///< Precision of the system clock (2^precision) + uint16_t sys_assoc; ///< Association ID of the current system peer, do not use NTP_SYS_STATE::sys_peer if this is supported + + int32_t root_delay; ///< [us] Total roundtrip delay to the system peer + int32_t root_disp; ///< [us] Total dispersion to the system peer + + MBG_IP_ADDR ref_id; ///< Reference ID of the current system peer, see ::MBG_IP_ADDR + + NTP_TSTAMP ref_time; ///< Last time the system time has been adjusted, see ::NTP_TSTAMP + NTP_TSTAMP sys_time; ///< Current system time, see ::NTP_TSTAMP + + uint16_t sys_peer; ///< Index of the current system peer + uint8_t poll; ///< Current polling interval for the system peer (tc) + uint8_t minpoll; ///< Minimal polling interval for the system peer (mintc) + + int64_t offset; ///< [ns] Combined offset to the system peer + + int32_t freq; ///< [ppb] Frequency offset relative to hardware clock + int32_t sys_jitter; ///< [us] Combined jitter of the system + int32_t clk_jitter; ///< [us] Jitter of the clock + int32_t clk_wander; ///< [ppb] Frequency wander of the clock + + uint8_t service_state; ///< Current state of the NTP service see ::MBG_NTP_SERVICE_STATES + uint8_t reserved_1; ///< Reserved, currently always 0 + uint16_t reserved_2; ///< Reserved, currently always 0 + + uint32_t reserved_3; ///< Reserved, currently always 0 + +} NTP_SYS_STATE; + +#define _mbg_swab_ntp_sys_state( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_flags ); \ + \ + _mbg_swab8( &(_p)->leap_ind ); \ + _mbg_swab8( &(_p)->sys_sync_src ); \ + _mbg_swab8( &(_p)->sys_evt_cnt ); \ + _mbg_swab8( &(_p)->sys_rec_evt ); \ + \ + _mbg_swab8( &(_p)->impl_type ); \ + _mbg_swab8( &(_p)->major_version ); \ + _mbg_swab8( &(_p)->minor_version ); \ + _mbg_swab8( &(_p)->micro_version ); \ + \ + _mbg_swab16( &(_p)->patch_lvl ); \ + _mbg_swab8( &(_p)->cpu_type ); \ + _mbg_swab8( &(_p)->system ); \ + \ + _mbg_swab8( &(_p)->stratum ); \ + _mbg_swab8( &(_p)->precision ); \ + _mbg_swab16( &(_p)->sys_assoc ); \ + \ + _mbg_swab32( &(_p)->root_delay ); \ + _mbg_swab32( &(_p)->root_disp ); \ + \ + _mbg_swab_ip_addr( &(_p)->ref_id ); \ + \ + _mbg_swab_ntp_tstamp( &(_p)->ref_time ); \ + _mbg_swab_ntp_tstamp( &(_p)->sys_time ); \ + \ + _mbg_swab16( &(_p)->sys_peer ); \ + _mbg_swab8( &(_p)->poll ); \ + _mbg_swab8( &(_p)->minpoll ); \ + \ + _mbg_swab64( &(_p)->offset ); \ + \ + _mbg_swab32( &(_p)->freq ); \ + _mbg_swab32( &(_p)->sys_jitter ); \ + _mbg_swab32( &(_p)->clk_jitter ); \ + _mbg_swab32( &(_p)->clk_wander ); \ + \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + \ +} while ( 0 ) + + + +/** + * @brief Enumeration of NTP mode bits + * + * Used with ::NTP_PEER_STATE::host_mode and ::NTP_PEER_STATE::peer_mode + * + */ +enum NTP_MODE_BITS +{ + NTP_MODE_RESERVED = 0, + NTP_MODE_SYMM_ACT, + NTP_MODE_SYMM_PASS, + NTP_MODE_CLIENT, + NTP_MODE_SERVER, + NTP_MODE_BROADCAST, + NTP_MODE_CONTROL, + NTP_MODE_PRIVATE, + N_NTP_MODE_BITS +}; + + + +/* + * Default initializers for English NTP peer mode string names. Initializers + * for multi-language strings can be found in tmonlstr.h. + */ +#define MBG_NTP_MODE_STR_ENG_HOST_LABEL "Host Mode:" +#define MBG_NTP_MODE_STR_ENG_PEER_LABEL "Peer Mode:" + +#define MBG_NTP_PEER_MODE_STR_ENG_RESERVED "Reserved" +#define MBG_NTP_PEER_MODE_STR_ENG_SYMM_ACT "Symm Act" +#define MBG_NTP_PEER_MODE_STR_ENG_SYMM_PASS "Symm Pass" +#define MBG_NTP_PEER_MODE_STR_ENG_CLIENT "Client" +#define MBG_NTP_PEER_MODE_STR_ENG_SERVER "Server" +#define MBG_NTP_PEER_MODE_STR_ENG_BROADCAST "Broadcast" +#define MBG_NTP_PEER_MODE_STR_ENG_CONTROL "Control" +#define MBG_NTP_PEER_MODE_STR_ENG_PRIVATE "Private" + +#define MBG_NTP_MODE_STAT_NAMES_ENG \ +{ \ + MBG_NTP_PEER_MODE_STR_ENG_RESERVED, \ + MBG_NTP_PEER_MODE_STR_ENG_SYMM_ACT, \ + MBG_NTP_PEER_MODE_STR_ENG_SYMM_PASS, \ + MBG_NTP_PEER_MODE_STR_ENG_CLIENT, \ + MBG_NTP_PEER_MODE_STR_ENG_SERVER, \ + MBG_NTP_PEER_MODE_STR_ENG_BROADCAST, \ + MBG_NTP_PEER_MODE_STR_ENG_CONTROL, \ + MBG_NTP_PEER_MODE_STR_ENG_PRIVATE \ +} + + + +/** + * @brief Enumeration of NTP peer reach status + * + * Used with ::NTP_PEER_STATE::peer_reach_stat + */ +enum NTP_REACH_STAT_BITS +{ + NTP_REACH_STAT_UNKNOWN = 0, ///< unknown reach status + NTP_REACH_STAT_NO_LINK, ///< no network connection + NTP_REACH_STAT_DNS_UNREACH, ///< DNS server could not be reached + NTP_REACH_STAT_DNS_UNRESOLVED, ///< DNS name could not be resolved + NTP_REACH_STAT_PEER_UNREACH, ///< peer could not be reached + NTP_REACH_STAT_PEER_NOT_SYNC, ///< peer is not sync (leap alarm, stratum 16) + NTP_REACH_STAT_PEER_BAD_QUALITY, ///< peer has bad quality (dispersion, ...) + NTP_REACH_STAT_OK, ///< reach status is fine + N_NTP_REACH_STAT_BITS +}; + + + +/* + * Default initializers for English reach status string names. Initializers + * for multi-language strings can be found in tmonlstr.h. + */ +#define MBG_NTP_PEER_REACH_STAT_STR_ENG_LABEL "Reach State:" + +#define MBG_NTP_PEER_REACH_STAT_STR_ENG_UNKNOWN "Unknown" +#define MBG_NTP_PEER_REACH_STAT_STR_ENG_NO_LINK "No link" +#define MBG_NTP_PEER_REACH_STAT_STR_ENG_DNS_UNREACH "DNS Server unreached" +#define MBG_NTP_PEER_REACH_STAT_STR_ENG_DNS_UNRESOLVED "DNS name not resolved" +#define MBG_NTP_PEER_REACH_STAT_STR_ENG_PEER_UNREACH "Peer not reached" +#define MBG_NTP_PEER_REACH_STAT_STR_ENG_PEER_NOT_SYNC "Peer not sync" +#define MBG_NTP_PEER_REACH_STAT_STR_ENG_PEER_BAD_QUALITY "Peer has bad quality" +#define MBG_NTP_PEER_REACH_STAT_STR_ENG_OK "Good" + +#define MBG_NTP_PEER_REACH_STAT_NAMES_ENG \ +{ \ + MBG_NTP_PEER_REACH_STAT_STR_ENG_UNKNOWN, \ + MBG_NTP_PEER_REACH_STAT_STR_ENG_NO_LINK, \ + MBG_NTP_PEER_REACH_STAT_STR_ENG_DNS_UNREACH, \ + MBG_NTP_PEER_REACH_STAT_STR_ENG_DNS_UNRESOLVED, \ + MBG_NTP_PEER_REACH_STAT_STR_ENG_PEER_UNREACH, \ + MBG_NTP_PEER_REACH_STAT_STR_ENG_PEER_NOT_SYNC, \ + MBG_NTP_PEER_REACH_STAT_STR_ENG_PEER_BAD_QUALITY, \ + MBG_NTP_PEER_REACH_STAT_STR_ENG_OK \ +} + + + +/** + * @brief Enumeration of NTP peer selection status + * + * Used with ::NTP_PEER_STATE::peer_sel_stat + * + */ +enum NTP_PEER_SEL_STATUS_BITS +{ + NTP_PEER_SEL_REJECT = 0, ///< discarded as not valid (TEST10-TEST13) + NTP_PEER_SEL_FALSETICK, ///< discarded by intersection algorithm + NTP_PEER_SEL_EXCESS, ///< discarded by table overflow (not used) + NTP_PEER_SEL_OUTLYER, ///< discarded by the cluster algorithm + NTP_PEER_SEL_CANDIDATE, ///< included by the combine algorithm + NTP_PEER_SEL_BACKUP, ///< backup (more than tos maxclock sources) + NTP_PEER_SEL_SYS_PEER, ///< system peer + NTP_PEER_SEL_PPS_PEER, ///< PPS peer (when the prefer peer is valid) + N_NTP_PEER_SEL_STATUS_BITS +}; + + + +/* + * Default initializers for English peer select status string names. Initializers + * for multi-language strings can be found in tmonlstr.h. + */ +#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_LABEL "Selected Status:" + +#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_REJECT "Not valid" +#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_FALSETICK "Falsetick" +#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_EXCESS "Excess" +#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_OUTLYER "Outlyer" +#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_CANDIDATE "Candidate" +#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_BACKUP "Backup" +#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_SYS_PEER "System Peer" +#define MBG_NTP_PEER_SEL_STATUS_STR_ENG_PPS_PEER "PPS Peer" + +#define MBG_NTP_PEER_SEL_STATUS_NAMES_ENG \ +{ \ + MBG_NTP_PEER_SEL_STATUS_STR_ENG_REJECT, \ + MBG_NTP_PEER_SEL_STATUS_STR_ENG_FALSETICK, \ + MBG_NTP_PEER_SEL_STATUS_STR_ENG_EXCESS, \ + MBG_NTP_PEER_SEL_STATUS_STR_ENG_OUTLYER, \ + MBG_NTP_PEER_SEL_STATUS_STR_ENG_CANDIDATE, \ + MBG_NTP_PEER_SEL_STATUS_STR_ENG_BACKUP, \ + MBG_NTP_PEER_SEL_STATUS_STR_ENG_SYS_PEER, \ + MBG_NTP_PEER_SEL_STATUS_STR_ENG_PPS_PEER \ +} + + + +/** + * @brief Enumeration of NTP peer status codes + * + * @see ::NTP_PEER_STATUS_FLAG_MASKS + * + */ +enum NTP_PEER_STATUS_FLAGS +{ + NTP_PEER_STATUS_BCST = 0, ///< broadcast association + NTP_PEER_STATUS_REACH, ///< host reachable + NTP_PEER_STATUS_AUTHENB, ///< authentication enabled + NTP_PEER_STATUS_AUTH, ///< authentication ok + NTP_PEER_STATUS_CONFIG, ///< persistent association + N_NTP_PEER_STATUS_FLAGS +}; + + +/** + * @brief Flag masks for NTP_PEER_STATUS_FLAGS + * + * Used with ::NTP_PEER_STATE::peer_status_flags + * + * @see ::NTP_PEER_STATUS_FLAGS + */ +enum NTP_PEER_STATUS_FLAG_MASKS +{ + NTP_PEER_STATUS_BCST_MSK = ( 1UL << NTP_PEER_STATUS_BCST ), ///< see ::NTP_PEER_STATUS_BCST + NTP_PEER_STATUS_REACH_MSK = ( 1UL << NTP_PEER_STATUS_REACH ), ///< see ::NTP_PEER_STATUS_REACH + NTP_PEER_STATUS_AUTHENB_MSK = ( 1UL << NTP_PEER_STATUS_AUTHENB ), ///< see ::NTP_PEER_STATUS_AUTHENB + NTP_PEER_STATUS_AUTH_MSK = ( 1UL << NTP_PEER_STATUS_AUTH ), ///< see ::NTP_PEER_STATUS_AUTH + NTP_PEER_STATUS_CONFIG_MSK = ( 1UL << NTP_PEER_STATUS_CONFIG ), ///< see ::NTP_PEER_STATUS_CONFIG +}; + + +/* + * Default initializers for English peer status string names. Initializers + * for multi-language strings can be found in tmonlstr.h. + */ +#define MBG_NTP_PEER_STATUS_STR_ENG_LABEL "Peer Status:" + +#define MBG_NTP_PEER_STATUS_STR_ENG_BCST "Broadcast association" +#define MBG_NTP_PEER_STATUS_STR_ENG_REACH "Host reachable" +#define MBG_NTP_PEER_STATUS_STR_ENG_AUTHENB "Authentication enabled" +#define MBG_NTP_PEER_STATUS_STR_ENG_CONFIG "Persistant assosiation" + +#define MBG_NTP_PEER_STATUS_NAMES_ENG \ +{ \ + MBG_NTP_PEER_STATUS_STR_ENG_BCST, \ + MBG_NTP_PEER_STATUS_STR_ENG_REACH, \ + MBG_NTP_PEER_STATUS_STR_ENG_REACH, \ + MBG_NTP_PEER_STATUS_STR_ENG_AUTHENB, \ + MBG_NTP_PEER_STATUS_STR_ENG_CONFIG \ +} + + + +/** + * @brief Enumeration of NTP peer event message codes + * + * Used with ::NTP_PEER_STATE::peer_rec_evt + * + */ +enum NTP_PEER_EVT_BITS +{ + NTP_PEER_EVT_UNSPEC = 0, ///< unspecified NTP event + NTP_PEER_EVT_MOBILIZE, ///< association mobilized + NTP_PEER_EVT_DEMOBILIZE, ///< association demobilized + NTP_PEER_EVT_UNREACHABLE, ///< server unreachable + NTP_PEER_EVT_REACHABLE, ///< server reachable + NTP_PEER_EVT_RESTART, ///< association restart + NTP_PEER_EVT_NO_REPLY, ///< no server found (ntpdate mode) + NTP_PEER_EVT_RATE_EXCEEDED, ///< rate exceeded (kiss code RATE) + NTP_PEER_EVT_ACCESS_DENIED, ///< access denied (kiss code DENY) + NTP_PEER_EVT_LEAP_ARMED, ///< leap armed from server LI code + NTP_PEER_EVT_SYS_PEER, ///< become system peer + NTP_PEER_EVT_CLOCK_EVENT, ///< see clock status word + NTP_PEER_EVT_BAD_AUTH, ///< authentication failure + NTP_PEER_EVT_POPCORN, ///< popcorn spike suppressor + NTP_PEER_EVT_INTERLEAVE_MODE, ///< entering interleave mode + NTP_PEER_EVT_INTERLEAVE_ERROR, ///< interleave error (recovered) + N_NTP_PEER_EVT_BITS +}; + + + +/* + * Default initializers for English event message codes. Initializers + * for multi-language strings can be found in tmonlstr.h. + */ +#define MBG_NTP_PEER_EVT_STR_ENG_CNT_LABEL "Peer Event Counter:" +#define MBG_NTP_PEER_EVT_STR_ENG_MSG_LABEL "Peer Event Message:" + +#define MBG_NTP_PEER_EVT_STR_ENG_UNSPEC "Unspecified NTP event" +#define MBG_NTP_PEER_EVT_STR_ENG_MOBILIZE "Association mobilized" +#define MBG_NTP_PEER_EVT_STR_ENG_DEMOBILIZE "Association demobilized" +#define MBG_NTP_PEER_EVT_STR_ENG_UNREACHABLE "Server unreachable" +#define MBG_NTP_PEER_EVT_STR_ENG_REACHABLE "Server reachable" +#define MBG_NTP_PEER_EVT_STR_ENG_RESTART "Association restart" +#define MBG_NTP_PEER_EVT_STR_ENG_NO_REPLY "No server found" +#define MBG_NTP_PEER_EVT_STR_ENG_RATE_EXCEEDED "Rate exceeded" +#define MBG_NTP_PEER_EVT_STR_ENG_ACCESS_DENIED "Access denied" +#define MBG_NTP_PEER_EVT_STR_ENG_LEAP_ARMED "Leap second armed from LI code" +#define MBG_NTP_PEER_EVT_STR_ENG_SYS_PEER "Become system Peer" +#define MBG_NTP_PEER_EVT_STR_ENG_CLOCK_EVENT "Clock event" +#define MBG_NTP_PEER_EVT_STR_ENG_BAD_AUTH "Authentication failure" +#define MBG_NTP_PEER_EVT_STR_ENG_POPCORN "Popcorn Spike suspressor" +#define MBG_NTP_PEER_EVT_STR_ENG_INTERLEAVE_MODE "Entering Interleave mode" +#define MBG_NTP_PEER_EVT_STR_ENG_INTERLEAVE_ERROR "Interleave error" + + +#define MBG_NTP_PEER_EVT_NAMES_ENG \ +{ \ + MBG_NTP_PEER_EVT_STR_ENG_UNSPEC, \ + MBG_NTP_PEER_EVT_STR_ENG_MOBILIZE, \ + MBG_NTP_PEER_EVT_STR_ENG_DEMOBILIZE, \ + MBG_NTP_PEER_EVT_STR_ENG_UNREACHABLE, \ + MBG_NTP_PEER_EVT_STR_ENG_REACHABLE, \ + MBG_NTP_PEER_EVT_STR_ENG_RESTART, \ + MBG_NTP_PEER_EVT_STR_ENG_NO_REPLY, \ + MBG_NTP_PEER_EVT_STR_ENG_RATE_EXCEEDED, \ + MBG_NTP_PEER_EVT_STR_ENG_ACCESS_DENIED, \ + MBG_NTP_PEER_EVT_STR_ENG_LEAP_ARMED, \ + MBG_NTP_PEER_EVT_STR_ENG_SYS_PEER, \ + MBG_NTP_PEER_EVT_STR_ENG_CLOCK_EVENT, \ + MBG_NTP_PEER_EVT_STR_ENG_BAD_AUTH, \ + MBG_NTP_PEER_EVT_STR_ENG_POPCORN, \ + MBG_NTP_PEER_EVT_STR_ENG_INTERLEAVE_MODE, \ + MBG_NTP_PEER_EVT_STR_ENG_INTERLEAVE_ERROR \ +} + + +/** + * @brief Enumeration of NTP flash status bit codes + * + * @see ::NTP_FLASH_STAT_FLAG_MASKS + * + */ +enum NTP_FLASH_STAT_FLAGS +{ + NTP_FLASH_STAT_PKT_DUP = 0, ///< duplicate packet + NTP_FLASH_STAT_PKT_BOGUS, ///< bogus packet + NTP_FLASH_STAT_PKT_UNSYNC, ///< server not synchronized + NTP_FLASH_STAT_PKT_DENIED, ///< access denied + NTP_FLASH_STAT_PKT_AUTH, ///< authentication failure + NTP_FLASH_STAT_PKT_STRATUM, ///< invalid leap or stratum + NTP_FLASH_STAT_PKT_HEADER, ///< header distance exceeded + NTP_FLASH_STAT_PKT_AUTOKEY, ///< Autokey sequence error + NTP_FLASH_STAT_PKT_CRYPTO, ///< Autokey protocol error + NTP_FLASH_STAT_PEER_STRATUM, ///< invalid header or stratum + NTP_FLASH_STAT_PEER_DIST, ///< distance threshold exceeded + NTP_FLASH_STAT_PEER_LOOP, ///< synchronization loop + NTP_FLASH_STAT_PEER_UNREACH, ///< unreachable or nonselect + N_NTP_FLASH_STAT_FLAGS +}; + + + +/** + * @brief Flag masks for ::NTP_FLASH_STAT_FLAGS + * + * Used with ::NTP_PEER_STATE::flash_stat_flags + * + * @see ::NTP_FLASH_STAT_FLAGS + */ +enum NTP_FLASH_STAT_FLAG_MASKS +{ + NTP_FLASH_STAT_PKT_DUP_MSK = ( 1UL << NTP_FLASH_STAT_PKT_DUP ), ///< see ::NTP_FLASH_STAT_PKT_DUP + NTP_FLASH_STAT_PKT_BOGUS_MSK = ( 1UL << NTP_FLASH_STAT_PKT_BOGUS ), ///< see ::NTP_FLASH_STAT_PKT_BOGUS + NTP_FLASH_STAT_PKT_UNSYNC_MSK = ( 1UL << NTP_FLASH_STAT_PKT_UNSYNC ), ///< see ::NTP_FLASH_STAT_PKT_UNSYNC + NTP_FLASH_STAT_PKT_DENIED_MSK = ( 1UL << NTP_FLASH_STAT_PKT_DENIED ), ///< see ::NTP_FLASH_STAT_PKT_DENIED + NTP_FLASH_STAT_PKT_AUTH_MSK = ( 1UL << NTP_FLASH_STAT_PKT_AUTH ), ///< see ::NTP_FLASH_STAT_PKT_AUTH + NTP_FLASH_STAT_PKT_STRATUM_MSK = ( 1UL << NTP_FLASH_STAT_PKT_STRATUM ), ///< see ::NTP_FLASH_STAT_PKT_STRATUM + NTP_FLASH_STAT_PKT_HEADER_MSK = ( 1UL << NTP_FLASH_STAT_PKT_HEADER ), ///< see ::NTP_FLASH_STAT_PKT_HEADER + NTP_FLASH_STAT_PKT_AUTOKEY_MSK = ( 1UL << NTP_FLASH_STAT_PKT_AUTOKEY ), ///< see ::NTP_FLASH_STAT_PKT_AUTOKEY + NTP_FLASH_STAT_PKT_CRYPTO_MSK = ( 1UL << NTP_FLASH_STAT_PKT_CRYPTO ), ///< see ::NTP_FLASH_STAT_PKT_CRYPTO + NTP_FLASH_STAT_PEER_STRATUM_MSK = ( 1UL << NTP_FLASH_STAT_PEER_STRATUM ), ///< see ::NTP_FLASH_STAT_PEER_STRATUM + NTP_FLASH_STAT_PEER_DIST_MSK = ( 1UL << NTP_FLASH_STAT_PEER_DIST ), ///< see ::NTP_FLASH_STAT_PEER_DIST + NTP_FLASH_STAT_PEER_LOOP_MSK = ( 1UL << NTP_FLASH_STAT_PEER_LOOP ), ///< see ::NTP_FLASH_STAT_PEER_LOOP + NTP_FLASH_STAT_PEER_UNREACH_MSK = ( 1UL << NTP_FLASH_STAT_PEER_UNREACH ), ///< see ::NTP_FLASH_STAT_PEER_UNREACH +}; + + + +/* + * Default initializers for English ntp flash state mask. Initializers + * for multi-language strings can be found in tmonlstr.h. + */ +#define MBG_NTP_FLASH_STR_ENG_LABEL "Flash Status:" + +#define MBG_NTP_FLASH_STR_ENG_PKT_DUP "Duplicate packet" +#define MBG_NTP_FLASH_STR_ENG_PKT_BOGUS "Bogus packet" +#define MBG_NTP_FLASH_STR_ENG_PKT_UNSYNC "Server not synchronized" +#define MBG_NTP_FLASH_STR_ENG_PKT_DENIED "Access denied" +#define MBG_NTP_FLASH_STR_ENG_PKT_AUTH "Authentication failure" +#define MBG_NTP_FLASH_STR_ENG_PKT_STRATUM "Invalid leap or stratum" +#define MBG_NTP_FLASH_STR_ENG_PKT_HEADER "Header distance exceeded" +#define MBG_NTP_FLASH_STR_ENG_PKT_AUTOKEY "Autokey sequence error" +#define MBG_NTP_FLASH_STR_ENG_PKT_CRYPTO "Autokey protocol error" +#define MBG_NTP_FLASH_STR_ENG_PEER_STRATUM "Invalid header or stratum" +#define MBG_NTP_FLASH_STR_ENG_PEER_DIST "Distance threshold exceeded" +#define MBG_NTP_FLASH_STR_ENG_PEER_LOOP "Synchronization loop" +#define MBG_NTP_FLASH_STR_ENG_PEER_UNREACH "Unreachable or nonselect" + + +#define MBG_NTP_FLASH_NAMES_ENG \ +{ \ + MBG_NTP_FLASH_STR_ENG_PKT_DUP, \ + MBG_NTP_FLASH_STR_ENG_PKT_BOGUS, \ + MBG_NTP_FLASH_STR_ENG_PKT_UNSYNC, \ + MBG_NTP_FLASH_STR_ENG_PKT_DENIED, \ + MBG_NTP_FLASH_STR_ENG_PKT_AUTH, \ + MBG_NTP_FLASH_STR_ENG_PKT_STRATUM, \ + MBG_NTP_FLASH_STR_ENG_PKT_HEADER, \ + MBG_NTP_FLASH_STR_ENG_PKT_AUTOKEY, \ + MBG_NTP_FLASH_STR_ENG_PKT_CRYPTO, \ + MBG_NTP_FLASH_STR_ENG_PEER_STRATUM, \ + MBG_NTP_FLASH_STR_ENG_PEER_DIST, \ + MBG_NTP_FLASH_STR_ENG_PEER_LOOP, \ + MBG_NTP_FLASH_STR_ENG_PEER_UNREACH \ +} + + + +/** + * @brief Enumeration of supported NTP peer state values + * + * @see ::NTP_PEER_STATE_SUPP_FLAG_MASKS + */ +enum NTP_PEER_STATE_SUPP_FLAGS +{ + NTP_PEER_STATE_SUPP_STD, ///< supports standard values of ::NTP_PEER_STATE, all fields except below and reserved + NTP_PEER_STATE_SUPP_ASS_ID, ///< supports association ID, see ::NTP_PEER_STATE::ass_id + NTP_PEER_STATE_SUPP_EVENTS, ///< supports peer state events (NTP_PEER_STATE::peer_evt_cnt, NTP_PEER_STATE::peer_rec_evt) + NTP_PEER_STATE_SUPP_REACH_STAT, ///< supports peer reach status, see ::NTP_PEER_STATE::peer_reach_stat + NTP_PEER_STATE_SUPP_PRECISION, ///< supports precision indication, see ::NTP_PEER_STATE::precision + NTP_PEER_STATE_SUPP_ROOT_DELAY, ///< supports root delay to syspeer, see ::NTP_PEER_STATE::root_delay + NTP_PEER_STATE_SUPP_ROOT_DISP, ///< supports root dispersion, see ::NTP_PEER_STATE::root_disp + NTP_PEER_STATE_SUPP_HEADWAY, ///< supports headway, see ::NTP_PEER_STATE::headway + NTP_PEER_STATE_SUPP_FLASH_STAT, ///< supports flash status word, see ::NTP_PEER_STATE::flash_stat_flags + NTP_PEER_STATE_SUPP_KEY_ID, ///< supports symmetric key id, see ::NTP_PEER_STATE::key_id + NTP_PEER_STATE_SUPP_DISP, ///< supports filter dispersion, see ::NTP_PEER_STATE::disp + NTP_PEER_STATE_SUPP_JITTER, ///< supports filter jitter, see ::NTP_PEER_STATE::jitter + NTP_PEER_STATE_SUPP_XLEAVE, ///< supports interleave delay, see ::NTP_PEER_STATE::xleave + N_NTP_PEER_STATE_SUPP_FLAGS +}; + + +/** + * @brief Flag masks for NTP_PEER_STATE_SUPP_FLAGS + * + * Used with ::NTP_PEER_STATE::supp_flags + * + * @see ::NTP_PEER_STATE_SUPP_FLAGS + */ +enum NTP_PEER_STATE_SUPP_FLAG_MASKS +{ + NTP_PEER_STATE_SUPP_STD_MSK = ( 1UL << NTP_PEER_STATE_SUPP_STD ), ///< see ::NTP_PEER_STATE_SUPP_STD + NTP_PEER_STATE_SUPP_ASS_ID_MSK = ( 1UL << NTP_PEER_STATE_SUPP_ASS_ID ), ///< see ::NTP_PEER_STATE_SUPP_ASS_ID + NTP_PEER_STATE_SUPP_EVENTS_MSK = ( 1UL << NTP_PEER_STATE_SUPP_EVENTS ), ///< see ::NTP_PEER_STATE_SUPP_EVENTS + NTP_PEER_STATE_SUPP_REACH_STAT_MSK = ( 1UL << NTP_PEER_STATE_SUPP_REACH_STAT ), ///< see ::NTP_PEER_STATE_SUPP_REACH_STAT + NTP_PEER_STATE_SUPP_PRECISION_MSK = ( 1UL << NTP_PEER_STATE_SUPP_PRECISION ), ///< see ::NTP_PEER_STATE_SUPP_PRECISION + NTP_PEER_STATE_SUPP_ROOT_DELAY_MSK = ( 1UL << NTP_PEER_STATE_SUPP_ROOT_DELAY ), ///< see ::NTP_PEER_STATE_SUPP_ROOT_DELAY + NTP_PEER_STATE_SUPP_ROOT_DISP_MSK = ( 1UL << NTP_PEER_STATE_SUPP_ROOT_DISP ), ///< see ::NTP_PEER_STATE_SUPP_ROOT_DISP + NTP_PEER_STATE_SUPP_HEADWAY_MSK = ( 1UL << NTP_PEER_STATE_SUPP_HEADWAY ), ///< see ::NTP_PEER_STATE_SUPP_HEADWAY + NTP_PEER_STATE_SUPP_FLASH_STAT_MSK = ( 1UL << NTP_PEER_STATE_SUPP_FLASH_STAT ), ///< see ::NTP_PEER_STATE_SUPP_FLASH_STAT + NTP_PEER_STATE_SUPP_KEY_ID_MSK = ( 1UL << NTP_PEER_STATE_SUPP_KEY_ID ), ///< see ::NTP_PEER_STATE_SUPP_KEY_ID + NTP_PEER_STATE_SUPP_DISP_MSK = ( 1UL << NTP_PEER_STATE_SUPP_DISP ), ///< see ::NTP_PEER_STATE_SUPP_DISP + NTP_PEER_STATE_SUPP_JITTER_MSK = ( 1UL << NTP_PEER_STATE_SUPP_JITTER ), ///< see ::NTP_PEER_STATE_SUPP_JITTER + NTP_PEER_STATE_SUPP_XLEAVE_MSK = ( 1UL << NTP_PEER_STATE_SUPP_XLEAVE ), ///< see ::NTP_PEER_STATE_SUPP_XLEAVE +}; + + + +/** + * @brief Structure that represents the status of an NTP peer + * + * This structure should be requested via ::NTP_PEER_STATE_IDX + * + * @see ::NTP_PEER_STATE_IDX + */ +typedef struct +{ + uint32_t supp_flags; ///< Supported NTP peer state values, see ::NTP_PEER_STATE_SUPP_FLAG_MASKS + + uint16_t ass_id; ///< Association ID of the peer + uint16_t peer_status_flags; ///< Peer status flags, see ::NTP_PEER_STATUS_FLAG_MASKS + + uint8_t leap_ind; ///< Leap indicator, see ::NTP_LI_BITS + uint8_t peer_sel_stat; ///< Current selection status of the peer, see ::NTP_PEER_SEL_STATUS_BITS + uint8_t peer_evt_cnt; ///< Number of events, since the last time the event code changed + uint8_t peer_rec_evt; ///< Most recent event message, see ::NTP_PEER_EVT_BITS + + uint8_t peer_reach_stat; ///< Current reach status of the peer, see ::NTP_REACH_STAT_BITS + uint8_t reserved_1; ///< Reserved, currently always 0 + uint16_t reserved_2; ///< Reserved, currently always 0 + + MBG_IP_ADDR_PORT src_addr; ///< Source address of the NTP peer, see ::MBG_IP_ADDR_PORT + MBG_IP_ADDR_PORT dst_addr; ///< Destination address of the NTP peer, see ::MBG_IP_ADDR_PORT + + uint8_t stratum; ///< Current stratum level of the NTP peer + int8_t precision; ///< Precision of the peer clock (2^precision) + uint16_t reserved_3; ///< Reserved, currently always 0 + + int32_t root_delay; ///< [us] Total roundtrip delay to the system peer of the NTP peer + int32_t root_disp; ///< [us] Total dispersion to the system peer of the NTP peer + + MBG_IP_ADDR ref_id; ///< Reference ID of the NTP peer, see ::MBG_IP_ADDR + + NTP_TSTAMP ref_time; ///< Last time the NTP peers time has been adjusted, see ::NTP_TSTAMP + NTP_TSTAMP rec_time; ///< Current system time of the NTP peer, see ::NTP_TSTAMP + + uint8_t reach; ///< Shift register for the last 8 polling intervals + uint8_t reserved_4; ///< Reserved, currently always 0 + uint16_t unreach; ///< Counter for the number of unsuccessful polling intervals + + uint8_t host_mode; ///< NTP mode of the requesting host, see ::NTP_MODE_BITS + uint8_t peer_mode; ///< NTP mode of the peer, see ::NTP_MODE_BITS + uint8_t host_poll; ///< Host NTP polling interval + uint8_t peer_poll; ///< Peer NTP polling interval + + uint8_t headway; ///< Indicator for the KoD packet, TODO: further investigation + uint8_t reserved_5; ///< Reserved, currently always 0 + uint16_t flash_stat_flags; ///< Flash status flags, see ::NTP_FLASH_STAT_FLAG_MASKS + + uint16_t key_id; ///< ID of symmetric authentication key + uint16_t reserved_6; ///< Reserved, currently always 0 + + int64_t offset; ///< [ns] filter offset to this NTP peer + int64_t delay; ///< [ns] filter delay to this NTP peer + + int32_t disp; ///< [us] filter dispersion of the NTP peer + int32_t jitter; ///< [us] filter jitter of the NTP peer + + uint32_t xleave; ///< [ns] interleave delay of the NTP peer + + uint8_t n_filter_values; ///< Number of filter values available, currently always 0 + uint8_t reserved_7; ///< Reserved, currently always 0 + uint16_t reserved_8; ///< Reserved, currently always 0 + + uint32_t reserved_9; ///< Reserved, currently always 0 + +} NTP_PEER_STATE, NTP_REFCLK_STATE; + + + +#define _mbg_swab_ntp_peer_state( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_flags ); \ + \ + _mbg_swab16( &(_p)->ass_id ); \ + _mbg_swab16( &(_p)->peer_status_flags ); \ + \ + _mbg_swab8( &(_p)->leap_ind ); \ + _mbg_swab8( &(_p)->peer_sel_stat ); \ + _mbg_swab8( &(_p)->peer_evt_cnt ); \ + _mbg_swab8( &(_p)->peer_rec_evt ); \ + \ + _mbg_swab8( &(_p)->peer_reach_stat ); \ + _mbg_swab8( &(_p)->reserved_1 ); \ + _mbg_swab16( &(_p)->reserved_2 ); \ + \ + _mbg_swab_ip_addr_port( &(_p)->src_addr ); \ + _mbg_swab_ip_addr_port( &(_p)->dst_addr ); \ + \ + _mbg_swab8( &(_p)->stratum ); \ + _mbg_swab8( &(_p)->precision ); \ + _mbg_swab16( &(_p)->reserved_3 ); \ + \ + _mbg_swab32( &(_p)->root_delay ); \ + _mbg_swab32( &(_p)->root_disp ); \ + \ + _mbg_swab_ip_addr( &(_p)->ref_id ); \ + \ + _mbg_swab_ntp_tstamp( &(_p)->ref_time ); \ + _mbg_swab_ntp_tstamp( &(_p)->rec_time ); \ + \ + _mbg_swab8( &(_p)->reach ); \ + _mbg_swab8( &(_p)->reserved_4 ); \ + _mbg_swab16( &(_p)->unreach ); \ + \ + _mbg_swab8( &(_p)->host_mode ); \ + _mbg_swab8( &(_p)->peer_mode ); \ + _mbg_swab8( &(_p)->host_poll ); \ + _mbg_swab8( &(_p)->peer_poll ); \ + \ + _mbg_swab8( &(_p)->headway ); \ + _mbg_swab8( &(_p)->reserved_5 ); \ + _mbg_swab16( &(_p)->flash_stat_flags ); \ + \ + _mbg_swab16( &(_p)->key_id ); \ + _mbg_swab16( &(_p)->reserved_6 ); \ + \ + _mbg_swab64( &(_p)->offset ); \ + _mbg_swab64( &(_p)->delay ); \ + \ + _mbg_swab32( &(_p)->disp ); \ + _mbg_swab32( &(_p)->jitter ); \ + \ + _mbg_swab32( &(_p)->xleave ); \ + \ + _mbg_swab8( &(_p)->n_filter_values ); \ + _mbg_swab8( &(_p)->reserved_7 ); \ + _mbg_swab16( &(_p)->reserved_8 ); \ + \ + _mbg_swab32( &(_p)->reserved_9 ); \ + \ +} while ( 0 ) + +#define _mbg_swab_ntp_refclk_state ( _p ) _mbg_swab_ntp_peer_state( _p ) + + +/** + * @brief Structure that contains an index value and the NTP peer state + * + * This structure can be requested by a monitoring program to observe the status of configured NTP peers + * + * @see ::NTP_PEER_STATE + */ +typedef struct +{ + uint32_t idx; ///< The index of the observed NTP peer + NTP_PEER_STATE peer_state; ///< Peer state, see ::NTP_PEER_STATE + +} NTP_PEER_STATE_IDX, NTP_REFCLK_STATE_IDX; + + +#define _mbg_swab_ntp_peer_state_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_peer_state( &(_p)->peer_state ); \ +} while ( 0 ) + + +#define _mbg_swab_ntp_refclk_state_idx( _p ) _mbg_swab_ntp_peer_state_idx( _p ) + + +/** @} defgroup group_ntp */ + /** @@ -6483,7 +17567,7 @@ typedef struct #define MAX_LNO_OUTPUT 4 /** - * @brief LNO status + * @brief LNO state */ typedef struct { @@ -6499,6 +17583,7 @@ typedef struct } LNO_STATE; #define _mbg_swab_lno_state( _p ) \ +do \ { \ int i; \ \ @@ -6508,11 +17593,11 @@ typedef struct _mbg_swab_16( &(_p)->max_sine_lvl ); \ _mbg_swab_16( &(_p)->reserved_0 ); \ _mbg_swab_16( &(_p)->flags ); \ -} +} while ( 0 ) /** - * @brief Flags used with LNO_STATE::flags + * @brief Flags used with ::LNO_STATE::flags */ enum LNO_STATE_FLAG_BITS { @@ -6522,10 +17607,824 @@ enum LNO_STATE_FLAG_BITS #define LNO_FLAG_PLL_LOCKED ( 1UL << LNO_FLAG_BIT_PLL_LOCKED ) -/** @} group_lno */ +/** @} defgroup group_lno */ -/*------------------------------------------------------------------------*/ + +/** + * @defgroup group_vst Definitions used with Versatile Storage + * + * Versatile storage is used to store binary data on a device where the storage + * device must not necessarily know about the data structure. It just stores + * a piece of data, and retrieves it on demand. + * + * The structures and associated API calls are only supported if the + * ::GPS_HAS_VST bit is set in ::RECEIVER_INFO::features. + * + * @{ */ + +/** + * @brief Known common VST data types + */ +enum VST_DATA_TYPES +{ + VST_DATA_TYPE_MAC_ADDR, //##++++++++++++ This is just an example. More to be added. + N_VST_DATA_TYPES +}; + + +/** + * @brief + */ +typedef struct +{ + uint16_t data_type; ///< data type identifier, see ::VST_DATA_TYPES for common types + uint16_t idx; ///< Index for several sets of the same type + uint16_t data_len; ///< length of the data set appended to the header + uint16_t reserved; ///< reserved, currently always 0 + +} VST_HEADER; + +#define _mbg_swab_vst_header( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->data_type ); \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab16( &(_p)->data_len ); \ + _mbg_swab16( &(_p)->reserved ); \ +} while ( 0 ) + +/** @} defgroup group_vst */ + + + +/** + * @defgroup group_shs Definitions used with SHS devices + * + * An SHS (Secure Hybrid System) device compares the times from 2 sources + * and eventually sets an alarm (warning and/or error) flag if the difference + * between the 2 time sources exceeds a configurable limit. + * + * These structures and associated definitions are used to query the SHS + * capabilities, configure the SHS device according to its capabilities, + * and query the SHS status. + * + * The structures and associated API calls are only supported if the + * ::GPS_HAS_SHS bit is set in ::RECEIVER_INFO::features. + * + * The ::SHS_INFO structure can be read to retrieve the capabilities and + * current settings of the device. The ::SHS_SETTINGS structure can then + * be set up according to the capabilities, and be written back to configure + * the device. + * + * If ::SHS_SETTINGS::err_limit and/or ::SHS_SETTINGS::warn_limit are + * not 0 then the SHS device checks if the time difference between the + * 2 clocks exceeds these limits and sets ::SHS_STATUS::shs_state + * as appropriate. + * + * If indicated by ::SHS_INFO::supp_flags the SHS device can also take + * certain actions if the time difference exceeds the error limit. + * If this happens then the same flags are set in ::SHS_STATUS::flags + * to indicate the action has been taken. + * + * @{ */ + +/** + * @brief Current configuration of an SHS controller + * + * @see ::SHS_INFO + * @see ::SHS_STATUS + */ +typedef struct +{ + NANO_TIME err_limit; ///< time difference limit above which an error is indicated + NANO_TIME warn_limit; ///< time difference limit above which a warning is indicated + uint32_t reserved; ///< reserved, currently always 0 + uint32_t flags; ///< see ::SHS_FLAG_MASKS + +} SHS_SETTINGS; + +#define _mbg_swab_shs_settings( _p ) \ +do \ +{ \ + _mbg_swab_nano_time( &(_p)->err_limit ); \ + _mbg_swab_nano_time( &(_p)->warn_limit ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Current SHS settings and general SHS capabilities + * + * @see ::SHS_SETTINGS + * @see ::SHS_STATUS + */ +typedef struct +{ + SHS_SETTINGS settings; ///< current configuration settings + NANO_TIME max_limit; ///< if not 0, the max. allowed value for ::SHS_SETTINGS::err_limit and ::SHS_SETTINGS::warn_limit + uint32_t reserved; ///< reserved, currently always 0 + uint32_t supp_flags; ///< indicates which flags are supported for ::SHS_SETTINGS::flags, see ::SHS_FLAG_MASKS + +} SHS_INFO; + +#define _mbg_swab_shs_info( _p ) \ +do \ +{ \ + _mbg_swab_shs_settings( &(_p)->settings ); \ + _mbg_swab_nano_time( &(_p)->max_limit ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Current SHS status + */ +typedef struct +{ + NANO_TIME time_diff; ///< current time difference between the 2 clocks + TM_STATUS_EXT clk_status_1; ///< status of first clock + TM_STATUS_EXT clk_status_2; ///< status of second clock + uint8_t shs_state; ///< see ::SHS_STATES + uint8_t reserved_1; ///< reserved, currently always 0 + uint16_t reserved_2; ///< reserved, currently always 0 + uint32_t flags; ///< see ::SHS_FLAG_MASKS + +} SHS_STATUS; + +#define _mbg_swab_shs_status( _p ) \ +do \ +{ \ + _mbg_swab_nano_time( &(_p)->time_diff ); \ + _mbg_swab32( &(_p)->clk_status_1 ); \ + _mbg_swab32( &(_p)->clk_status_2 ); \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief SHS configuration flag bits + * + * Codes used with ::SHS_STATUS::shs_state + */ +enum SHS_STATES +{ + SHS_STATE_DISABLED, ///< time difference not checked, eventually no limits configured + SHS_STATE_OK, ///< time difference OK, below warning limit + SHS_STATE_WARNING, ///< time difference exceeds warning limit + SHS_STATE_ERROR, ///< time difference exceeds error limit + SHS_STATE_FATAL, ///< one or both time sources disconnected + N_SHS_STATES +}; + + + +/** + * @brief SHS flag bits + * + * @see ::SHS_FLAG_MASKS + */ +enum SHS_FLAG_BITS +{ + SHS_FLAG_BIT_DISB_SERIAL, ///< disable serial output in state ::SHS_STATE_ERROR + SHS_FLAG_BIT_DISB_PPS, ///< disable PPS output in state ::SHS_STATE_ERROR + SHS_FLAG_BIT_DISB_10MHZ, ///< disable 10 MHz output in state ::SHS_STATE_ERROR + N_SHS_FLAG_BITS +}; + + +/** + * @brief SHS flag masks + * + * With ::SHS_INFO::supp_flags these flags indicate what is supported + * by the SHS controller, e.g. what action can be taken automatically. + * Each bit set in ::SHS_INFO::supp_flags can be set by a configuration + * tool in ::SHS_SETTINGS::flags to enable the associated feature. + * If a corresponding bit is set in ::SHS_STATUS::flags this means the + * associated feature has been enabled, e.g. an action has been taken. + * + * @see ::SHS_FLAG_BITS + */ +enum SHS_FLAG_MASKS +{ + SHS_FLAG_DISB_SERIAL = ( 1UL << SHS_FLAG_BIT_DISB_SERIAL ), ///< see ::SHS_FLAG_BIT_DISB_SERIAL + SHS_FLAG_DISB_PPS = ( 1UL << SHS_FLAG_BIT_DISB_PPS ), ///< see ::SHS_FLAG_BIT_DISB_PPS + SHS_FLAG_DISB_10MHZ = ( 1UL << SHS_FLAG_BIT_DISB_10MHZ ) ///< see ::SHS_FLAG_BIT_DISB_10MHZ +}; + +/** @} defgroup group_shs */ + + + +/** + * @defgroup group_xbp eXtended Binary Protocol definitions + * + * @note These structures are only supported if ::GPS_HAS_XBP is set + * in ::RECEIVER_INFO::features. + * + * @{ */ + +/** + * @brief An XBP port specifier + * + * Each controller can provide up to 255 ports with numbers 0..254. + * XBP port number ::XBP_PORT_RESERVED is reserved to mark unused ports. + */ +typedef uint8_t XBP_PORT; + + +/** + * @brief An identifier used to mark an XBP port unused + */ +#define XBP_PORT_RESERVED ( (XBP_PORT) -1 ) + + +/** + * @brief Maximum XBP bus/controller cascading level + * + * Should be 7 so the total size of ::XBP_ADDR is 8 bytes. + */ +#define MAX_XBP_CASC_LVL 7 + + +/** + * @brief An XBP address specifier + * + * A generic scheme to address devices connected to cascaded controllers. + */ +typedef struct +{ + 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 + +} XBP_ADDR; + +#define _mbg_swab_xbp_addr( _p ) _nop_macro_fnc() // only single bytes + + + +/** + * @brief A structure used to report XBP features and limits + */ +typedef struct +{ + uint32_t features; ///< Mask of XBP features, see ::XBP_FEAT_MASKS + uint32_t flags; ///< XBP flags, currently not used + uint32_t reserved_0; ///< reserved, currently not used + uint32_t reserved_1; ///< reserved, currently not used + uint32_t reserved_2; ///< reserved, currently not used + uint32_t reserved_3; ///< reserved, currently not used + +} XBP_LIMITS; + +#define _mbg_swab_xbp_limits( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->features ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of bits used to define ::XBP_FEAT_MASKS + */ +enum XBP_FEAT_BITS +{ + XBP_FEAT_BIT_NODES, ///< Supports ::XBP_NODE_LIMITS and associated structures + N_XBP_FEAT_BITS +}; + + +/** + * @brief XBP feature masks used with ::XBP_LIMITS::features + * + * @see ::XBP_FEAT_BITS + */ +enum XBP_FEAT_MASKS +{ + XBP_FEAT_MASK_NODES = ( 1UL << XBP_FEAT_BIT_NODES ) ///< See ::XBP_FEAT_BIT_NODES +}; + + + +/** + * @brief Information on available XBP nodes + * + * Only supported if ::XBP_FEAT_MASK_NODES is set in ::XBP_LIMITS::features. + */ +typedef struct +{ + uint32_t node_count; ///< Number of XBP nodes available in the system + uint32_t reserved_0; ///< Currently reserved, always 0 + uint32_t reserved_1; ///< Currently reserved, always 0 + // TODO: do we need additional fields here? + +} XBP_NODE_LIMITS; + +#define _mbg_swab_xbp_node_limits( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->node_count ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ +} while ( 0 ) + + + +/** + * @brief Possible states of an XBP device + * + * Used with ::XBP_NODE_INFO::state. + */ +enum XBP_DEVICE_STATES +{ + XBP_DEVICE_STATE_UNKNOWN, + XBP_DEVICE_STATE_NOT_AVAILABLE, + XBP_DEVICE_STATE_INITIALIZING, + XBP_DEVICE_STATE_AVAILABLE, + XBP_DEVICE_STATE_DISCONNECTED, + N_XBP_DEVICE_STATES +}; + + +/** + * @brief Possible IMS slot types of an XBP device + * + * Used with ::XBP_NODE_INFO::slot_type. + */ +enum XBP_SLOT_TYPES +{ + XBP_SLOT_TYPE_UNKNOWN, ///< Unknown slot type, i.e. slot type not supp. + XBP_SLOT_TYPE_PWR, ///< Slot for power supply units + XBP_SLOT_TYPE_CLK, ///< Slot for reference clocks + XBP_SLOT_TYPE_SCU, ///< Slot for switch card units + XBP_SLOT_TYPE_CPU, ///< Slot for processing units + XBP_SLOT_TYPE_MRI, ///< Slot for MRI (multi reference input) cards + XBP_SLOT_TYPE_ESI, ///< Slot for ESI (extended reference input) cards + XBP_SLOT_TYPE_IO, ///< Slot for all other input/output cards + N_XBP_SLOT_TYPES +}; + + +#define XBP_SLOT_TYPE_STRS \ +{ \ + "Unknown", \ + "PWR", \ + "CLK", \ + "SCU", \ + "CPU", \ + "MRI", \ + "ESI", \ + "IO" \ +} + + +/// Maximum string length (including terminating zero) of a full XBP slot name +/// which consists of ::XBP_NODE_INFO::slot_type and ::XBP_NODE_INFO::slot_type_id +/// Examples: "CLK1", "MRI2", ... +#define XBP_MAX_SLOT_NAME 5 + + +/** + * @brief Information on a specific XBP node + * + * Only supported if ::XBP_FEAT_MASK_NODES is set in ::XBP_LIMITS::features. + * The number of instances supported by a device is specified + * in ::XBP_NODE_LIMITS::node_count. + */ +typedef struct +{ + XBP_ADDR addr; ///< The address of the specific node + + /// ::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; + + uint8_t state; ///< The device state, see ::XBP_DEVICE_STATES + + uint8_t slot_type; ///< The IMS slot type, see ::XBP_SLOT_TYPES + uint8_t slot_type_id; ///< ID depending on the ::XBP_NODE_INFO::slot_type, i.e. 1 for CLK1 + + uint8_t reserved; ///< Currently reserved, always 0 + uint16_t flags; ///< Currently reserved, always 0 + +} XBP_NODE_INFO; + +#define _mbg_swab_xbp_node_info( _p ) \ +do \ +{ \ + _mbg_swab_xbp_addr( &(_p)->addr ); \ + _mbg_swab_receiver_info( &(_p)->ri ); \ + _mbg_swab8( &(_p)->state ); \ + _mbg_swab8( &(_p)->slot_type ); \ + _mbg_swab8( &(_p)->slot_type_id ); \ + _mbg_swab8( &(_p)->reserved ); \ + _mbg_swab16( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Information on an XBP node with specific index + * + * Only supported if ::XBP_FEAT_MASK_NODES is set in ::XBP_LIMITS::features. + */ +typedef struct +{ + uint32_t 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; + +#define _mbg_swab_xbp_node_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_xbp_node_info( &(_p)->node_info ); \ +} while ( 0 ) + + +/** @} defgroup group_xbp */ + + + +/** + * @defgroup group_tlv_api Meinberg TLV API definitions + * + * @note These structures and definitions are only supported by a device + * if ::MBG_XFEATURE_TLV_API is set in the extended device features. + * + * @{ */ + + +/** + * @brief A data type used to hold a unique ID (UID) for a TLV transaction + */ +typedef uint32_t MBG_TLV_UID; + +#define _mbg_swab_tlv_uid( _p ) \ + _mbg_swab32( _p ) + + + +/** + * @brief A data type to hold one of the ::MBG_TLV_TYPES or ::MBG_TLV_FEAT_TYPES + * + * @see ::MBG_TLV_TYPES + * @see ::MBG_TLV_FEAT_TYPES + */ +typedef uint32_t MBG_TLV_TYPE; + +#define _mbg_swab_tlv_type( _p ) \ + _mbg_swab32( _p ) + + + +/** + * @defgroup group_tlv_feat Meinberg TLV feature definitions + * + * @{ */ + + +/** + * @brief The maximum number of TLV feature types. + * + * Warning: Changing this number breaks API compatibility! + * + * @see ::MBG_TLV_FEAT_TYPES + */ +#define MAX_MBG_TLV_FEAT_TYPES 128 //### TODO Is this sufficient? + + +/** + * @brief Enumeration of known TLV feature types. + * + * TLV feature types are used to specify the content of a binary TLV message + * so that the receiver knows how to interpret the content. + * + * Used with ::MBG_TLV_INFO::supp_tlv_feat and ::MBG_TLV_DATA::type. ### TODO + * + * @see ::MBG_TLV_FEAT_BUFFER + * @see ::MBG_TLV_FEAT_TYPE_NAMES + * @see ::MBG_TLV_TYPES + * @see ::MBG_TLV_TYPE + */ +enum MBG_TLV_FEAT_TYPES +{ + /// Expects two TLV types in order: + /// 1) ::MBG_TLV_TYPE_STR => Firmware version as string + /// 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 + /// is expected and it should contain a file as data blob. + MBG_TLV_FEAT_TYPE_DIAG_FILE, + + /// Only used as action trigger on a remote site, expects no data. + MBG_TLV_FEAT_TYPE_FW_ROLLBACK, + + /// Expects two TLV types in order: + /// 1) ::MBG_TLV_TYPE_STR => Full qualified path including filename on target system + /// 2) ::MBG_TLV_TYPE_FILE => File as data blob + MBG_TLV_FEAT_TYPE_FILE_TRANSFER, + + /// 1) ::MBG_TLV_TYPE_STR => Command line call as string + MBG_TLV_FEAT_TYPE_EXEC_CMD, + + /// 1) ::MBG_TLV_TYPE_FILE => Encrypted license file as data blob + MBG_TLV_FEAT_TYPE_LICENSE_UPGRADE, + + /// 1) ::MBG_TLV_TYPE_BLOB => ::MBG_LICENSE_LIMITS, see @ref group_license_limits + MBG_TLV_FEAT_TYPE_LICENSE_LIMITS, + + /// 1) ::MBG_TLV_TYPE_BLOB => ::MBG_LICENSE_PTPV2_IDX, see @ref group_license_limits + MBG_TLV_FEAT_TYPE_LICENSE_PTPV2_IDX, + + /// 1) ::MBG_TLV_TYPE_BLOB => ::MBG_LICENSE_NTP_IDX, see @ref group_license_limits + MBG_TLV_FEAT_TYPE_LICENSE_NTP_IDX, + + /// Expects two TLV types in order: + /// 1) ::MBG_TLV_TYPE_STR => Full qualified path including filename on target system + MBG_TLV_FEAT_TYPE_FILE_REQUEST, + + /// 1) ::MBG_TLV_TYPE_BLOB => ::MBG_LICENSE_PTPV1_IDX, see @ref group_license_limits + MBG_TLV_FEAT_TYPE_LICENSE_PTPV1_IDX, + + /// 1) ::MBG_TLV_TYPE_BLOB => ::MBG_LICENSE_TIME_MONITOR_IDX, see @ref group_license_limits + MBG_TLV_FEAT_TYPE_LICENSE_TIME_MONITOR_IDX, + + /// used to receive full TimeMon Status structure + MBG_TLV_FEAT_TYPE_TIMEMON_FULL_STATUS, + + /// 1) ::MBG_TLV_TYPE_BLOB => Unified Firmware Update (UFU) file, see mbg_ufu.h + MBG_TLV_FEAT_TYPE_UFU, + + N_MBG_TLV_FEAT_TYPES + // NOTE If new TLV feature types are appended here then an appropriate + // name string has to be appended to ::MBG_TLV_FEAT_TYPE_NAMES, and care must + // be taken that ::N_MBG_TLV_FEAT_TYPES doesn't exceed ::MAX_MBG_TLV_FEAT_TYPES. +}; + + +/** + * @brief Names of TLV API features + * + * Can be used to initialize a string array of ::N_MBG_TLV_FEAT_TYPES entries, + * so the number of strings must correspond to ::N_MBG_TLV_FEAT_TYPES. + * + * @see ::MBG_TLV_FEAT_TYPES + */ +#define MBG_TLV_FEAT_TYPE_NAMES \ +{ \ + "TLV Firmware Update", \ + "TLV Diagnostics File", \ + "TLV Firmware Rollback", \ + "TLV File Transfer", \ + "TLV Execute Command", \ + "TLV License Upgrade", \ + "TLV License Limits", \ + "TLV License PTPV2", \ + "TLV License NTP", \ + "TLV File Request", \ + "TLV License PTPV1 IDX", \ + "TLV License Sync Monitor", \ + "TLV Sync Monitor Full Status", \ + "TLV Unified Firmware Update" \ +} + + + +/** + * @brief Array size required to store up to ::MAX_MBG_TLV_FEAT_TYPES bits + * + * The number of bytes required to store up to ::MAX_MBG_TLV_FEAT_TYPES + * feature bits in a byte array. + */ +#define MAX_MBG_TLV_FEAT_BYTES ( MAX_MBG_TLV_FEAT_TYPES / 8 ) + + +/** + * @brief A structure used to store a bit mask of supported TLV context types. + * + * Bit masks for up to ::MAX_MBG_TLV_FEAT_TYPES totally can be stored, + * but only ::N_MBG_TLV_FEAT_TYPES types are currently defined. + * The ::_set_tlv_feat_bit macro should be used by the firmware + * to set a bit mask in the buffer, and the ::check_tlv_feat_supp + * function should be used to implement API calls which test if an + * extended TLV context type is supported. + * + * @see ::_set_tlv_feat_bit + * @see ::check_tlv_feat_supp + */ +typedef struct +{ + uint8_t b[MAX_MBG_TLV_FEAT_BYTES]; + +} MBG_TLV_FEAT_BUFFER; + + + +/** + * @brief Set a TLV context type bit in a ::MBG_TLV_FEAT_BUFFER + * + * Should be used by the firmware only to set one of the ::MBG_TLV_FEAT_TYPES + * bits in an ::MBG_TLV_FEAT_BUFFER after power-up. + * + * @param[in] _tlv_feat_type One of the ::MBG_TLV_FEAT_TYPES + * @param[in] _tlv_feat_buffp Pointer to a ::MBG_TLV_FEAT_BUFFER + */ +#define _set_tlv_feat_bit( _tlv_feat_type, _tlv_feat_buffp ) \ + _set_array_bit( _tlv_feat_type, (_tlv_feat_buffp)->supp_tlv_feat.b, MAX_MBG_TLV_FEAT_BYTES ) + + +/** @} defgroup group_tlv_feat */ + + + +/** + * @brief A structure used to query current TLV capabilities + * + * This is only supported by a device if the ::MBG_XFEATURE_TLV_API bit + * is set in the extended device features. + */ +typedef struct +{ + uint32_t reserved; ///< Future use + uint32_t flags; ///< Future use + MBG_TLV_FEAT_BUFFER supp_tlv_feat; ///< A byte array of supported TLV feature bits, see ::MBG_TLV_FEAT_TYPES + +} MBG_TLV_INFO; + +#define _mbg_swab_tlv_info( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of known TLV types + * + * Used with ::MBG_TLV_TYPE types, e.g. in ::MBG_TLV_HDR::tlv_type + * or ::MBG_TLV_DATA::type. + * + * @see ::MBG_TLV_FEAT_TYPES + * @see ::MBG_TLV_TYPE + */ +enum MBG_TLV_TYPES +{ + MBG_TLV_TYPE_STR, + MBG_TLV_TYPE_FILE, + MBG_TLV_TYPE_BLOB, ///< In fact, a file is also a blob but + ///< give the child a different name to avoid confusion. + ///< Use this for getting/setting fixed structures! + N_MBG_TLV_TYPES +}; + + + +/** + * @brief General TLV data structure + * + * Structure containing common, additional data required to send + * an announce message for following TLVs. + */ +typedef struct +{ + MBG_TLV_UID uid; ///< Unique ID identifying following TLVs, 0 if empty/not set. + MBG_TLV_TYPE type; ///< One of the ::MBG_TLV_TYPES or ::MBG_TLV_FEAT_TYPES depending on the type of message. + uint32_t total_bytes; ///< Number of all bytes including header(s) that are related to a TLV block transaction. + uint32_t reserved_1; ///< Reserved for future use + +} MBG_TLV_DATA; + +#define _mbg_swab_tlv_data( _p ) \ +do \ +{ \ + _mbg_swab_tlv_uid( &(_p)->uid ); \ + _mbg_swab_tlv_type( &(_p)->type ); \ + _mbg_swab32( &(_p)->total_bytes ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ +} while ( 0 ) + + + +/** + * @brief Structure containing state information while reading TLV data. + */ +typedef struct +{ + MBG_TLV_DATA data; ///< See ::MBG_TLV_DATA + uint32_t read_bytes; ///< Number of bytes read + uint32_t reserved_1; ///< Future use + +} MBG_TLV_RCV_STATE; + + + +/** + * @brief A structure initiating a TLV transfer + * + * ::MBG_TLV_ANNOUNCE should be sent first, before starting a + * TLV transfer, to inform the remote site about following TLVs. + * Following sequence of TLVs is not fixed and implementation + * dependent. + */ +typedef struct +{ + MBG_TLV_DATA data; ///< See ::MBG_TLV_DATA + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + +} MBG_TLV_ANNOUNCE; + +#define _mbg_swab_tlv_announce( _p ) \ +do \ +{ \ + _mbg_swab_tlv_data( &(_p)->data ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) + + + +#define MSG_TLV_MAX_VALUE_SIZE 480 + +/** + * @brief TLV header structure containing information on current TLV transaction + */ +typedef struct +{ + MBG_TLV_UID uid; ///< Unique source ID. See ::MBG_TLV_DATA::uid + MBG_TLV_UID tlv_type; ///< "Subtype" identifying current TLV, see ::MBG_TLV_TYPES + uint32_t cur_bytes; ///< Number of bytes in ::MBG_TLV::value + uint32_t trans_bytes; ///< Number of bytes transferred so far related to this TLV type. + uint32_t total_bytes; ///< Number of total bytes (size) of this TLV type without header. + ///< It is fixed and must not be changed during a TLV transaction. + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + uint32_t reserved_3; ///< Future use + +} MBG_TLV_HDR; + +#define _mbg_swab_tlv_header( _p ) \ +do \ +{ \ + _mbg_swab_tlv_uid( &(_p)->uid ); \ + _mbg_swab_tlv_type( &(_p)->tlv_type ); \ + _mbg_swab32( &(_p)->cur_bytes ); \ + _mbg_swab32( &(_p)->trans_bytes ); \ + _mbg_swab32( &(_p)->total_bytes ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) + + + +/** + * @brief TLV structure containing information on current TLV transaction and its current data. + */ +typedef struct +{ + MBG_TLV_HDR hdr; ///< See ::MBG_TLV_HDR + uint8_t value[MSG_TLV_MAX_VALUE_SIZE]; ///< See ::MSG_TLV_MAX_VALUE_SIZE + +} MBG_TLV; + +#define _mbg_swab_tlv( _p ) \ +do \ +{ \ + _mbg_swab_tlv_header( &(_p)->hdr ); \ +} while ( 0 ) + +/** @} defgroup group_tlv_api */ + + + +/** + * @defgroup group_gps_nav_data Definitions used with navigational data received from GPS satellites + * + * @note These structures and definitions are only supported by a device + * if ::GPS_MODEL_IS_GPS is set in the @ref GPS_BUILTIN_FEATURE_MASKS + * + * @{ */ + /** * @brief Ephemeris parameters of one specific satellite @@ -6572,6 +18471,7 @@ typedef struct uint8_t L2code; ///< code on L2 channel [---] uint8_t L2flag; ///< L2 P data flag [---] + } EPH; @@ -6601,6 +18501,7 @@ typedef struct double deltai; ///< +- [rad] double af0; ///< +- Clock Correction Coefficient 0 [sec] double af1; ///< +- Clock Correction Coefficient 1 [sec/sec] + } ALM; @@ -6610,15 +18511,16 @@ typedef struct */ typedef struct { - CSUM csum; ///< checksum of the remaining bytes - int16_t valid; ///< flag data are valid + CSUM csum; ///< checksum of the remaining bytes + int16_t valid; ///< flag data are valid + + T_GPS tot_51; ///< time of transmission, page 51 + T_GPS tot_63; ///< time of transmission, page 63 + T_GPS t0a; ///< complete reference time almanac - T_GPS tot_51; ///< time of transmission, page 51 - T_GPS tot_63; ///< time of transmission, page 63 - T_GPS t0a; ///< complete reference time almanac + CFG cfg[N_SVNO_GPS]; ///< 4 bit SV configuration code from page 63 + HEALTH health[N_SVNO_GPS]; ///< 6 bit SV health codes from pages 51, 63 - CFG cfg[N_SVNO]; ///< SV configuration from page 63 - HEALTH health[N_SVNO]; ///< SV health from pages 51, 63 } CFGH; @@ -6646,17 +18548,18 @@ typedef struct * after the next leap second event defined by WNlsf and DNt. * * The fields WNlsf and DNt specify the GPS week number and the day number - * in that week at the end of which a leap second is scheduled. + * in that week for the end of which a leap second has been scheduled. * * @note: The satellites transmit WNlsf only as a signed 8 bit value, so it - * can only define a point in time which is ± 127 weeks off the current time. + * can only define a point in time which is +/- 127 weeks off the current time. * The firmware tries to expand this based on the current week number, but * the result is ambiguous if the leap second occurs or occurred more * than 127 weeks in the future or past. * - * So the leap second date should only be evaluated if the fields delta_tls - * and delta_tlsf are different, in which case there is an actual leap second - * announcement inside the ± 127 week range. + * So the leap second date should <b>only</b> be evaluated and displayed + * in a user interface if the fields delta_tls and delta_tlsf have + * different values, in which case there is indeed a leap second announcement + * inside the +/- 127 week range. */ typedef struct { @@ -6671,9 +18574,11 @@ typedef struct int16_t DNt; ///< The day number at the end of which a leap second occurs int8_t delta_tls; ///< Current %UTC offset to GPS system time [sec] int8_t delta_tlsf; ///< Future %UTC offset to GPS system time after next leap second transition [sec] + } UTC; #define _mbg_swab_utc_parm( _p ) \ +do \ { \ _mbg_swab_csum( &(_p)->csum ); \ _mbg_swab16( &(_p)->valid ); \ @@ -6682,7 +18587,7 @@ typedef struct _mbg_swab_double( &(_p)->A1 ); \ _mbg_swab16( &(_p)->WNlsf ); \ _mbg_swab16( &(_p)->DNt ); \ -} +} while ( 0 ) @@ -6703,6 +18608,7 @@ typedef struct double beta_1; ///< Ionosph. Corr. Coeff. Beta 1 [sec/deg] double beta_2; ///< Ionosph. Corr. Coeff. Beta 2 [sec/deg^2] double beta_3; ///< Ionosph. Corr. Coeff. Beta 3 [sec/deg^3] + } IONO; @@ -6715,8 +18621,11 @@ typedef struct CSUM csum; ///< checksum of the remaining bytes */ int16_t valid; ///< flag data are valid char s[23]; ///< 22 chars GPS ASCII message plus trailing zero + } ASCII_MSG; +/** @} defgroup group_gps_nav_data */ + enum GPS_PLATFORMS @@ -6768,11 +18677,13 @@ typedef struct int32_t fixedPosY; // cm int32_t fixedPosZ; // cm uint32_t fixedPosVar; // cm - uint32_t flags; // currently 0 - uint32_t reserved; // currently 0 + uint32_t flags; // currently 0 + uint32_t reserved; // currently 0 + } NAV_TIME_MODE_SETTINGS; + /** * Navigation Engine settings to set configuration * parameters of a dynamic platform model. @@ -6788,9 +18699,4927 @@ typedef struct uint32_t flags; // currently 0 uint32_t reserved; // currently 0 NAV_TIME_MODE_SETTINGS nav_time_mode_settings; + } NAV_ENGINE_SETTINGS; + +/** + * @defgroup group_led_api Meinberg LED API definitions + * + * @note These structures and definitions are only supported by a device + * if ::MBG_XFEATURE_LED_API is set in the extended device features. + * + * @{ */ + + +/** + * @brief General LED info to be read from a device + * + * Used to query from a device how many LEDs are supported + * by the device, then index 0..::MBG_LED_LIMITS::num_leds-1 + * ::MBG_LED_INFO_IDX or ::MBG_LED_SETTINGS_IDX structures + * can be read from or written to the device. + * + * @see ::MBG_LED_SETTINGS_IDX + * @see ::MBG_LED_INFO_IDX + */ +typedef struct +{ + uint8_t num_leds; ///< Number of supported LEDs, see ::MBG_LED_SETTINGS_IDX::idx and ::MBG_LED_INFO_IDX::idx + uint8_t reserved_0; ///< Currently reserved, unused, always 0 + uint16_t reserved_1; ///< Currently reserved, unused, always 0 + uint32_t reserved_2; ///< Currently reserved, unused, always 0 + +} MBG_LED_LIMITS; + +#define _mbg_swab_mbg_led_limits( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->num_leds ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) + + + +/** + * @brief Possible modes of LEDs + * + * Used with ::MBG_LED_SETTINGS::mode + * + * @see ::MBG_LED_MODE_MASKS + */ +enum MBG_LED_MODES +{ + MBG_LED_MODE_OFF, + MBG_LED_MODE_ON, + MBG_LED_MODE_FLASH, + MBG_LED_MODE_FLASH_5S, + N_MBG_LED_MODES +}; + + + +/** + * @brief Bit masks associated with LED modes + * + * Used with ::MBG_LED_INFO::supp_modes + * + * @see ::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 +}; + + +/** + * @brief Names of LED modes + * + * Can be used to initialize a string array of ::N_MBG_LED_MODES entries, + * so the number of strings must correspond to ::N_MBG_LED_MODES. + * + * @see ::MBG_LED_MODES + * @see ::MBG_LED_MODE_MASKS + */ +#define MBG_LED_MODE_STRS \ +{ \ + "Off", \ + "On", \ + "Flash", \ + "Flash 5s" \ +} + + + +/** + * @brief Possible colors of LEDs + * + * Used with ::MBG_LED_SETTINGS::color + * + * @see ::MBG_LED_COLOR_MASKS + */ +enum MBG_LED_COLORS +{ + MBG_LED_COLOR_GREEN, + MBG_LED_COLOR_RED, + MBG_LED_COLOR_YELLOW, + MBG_LED_COLOR_BLUE, + N_MBG_LED_COLORS +}; + + + +/** + * @brief Bit masks of possible LED colors + * + * Used with ::MBG_LED_INFO::supp_colors + * + * @see ::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 +}; + + + +/** + * @brief Names of LED colors + * + * Can be used to initialize a string array of ::N_MBG_LED_COLORS entries, + * so the number of strings must correspond to ::N_MBG_LED_COLORS. + * + * @see ::MBG_LED_COLORS + * @see ::MBG_LED_COLOR_MASKS + */ +#define MBG_LED_COLOR_STRS \ +{ \ + "Green", \ + "Red", \ + "Yellow", \ + "Blue" \ +} + + + +/** + * @brief Configuration settings for a single LED + * + * @see ::MBG_LED_SETTINGS_IDX + */ +typedef struct +{ + uint8_t mode; ///< LED mode, see ::MBG_LED_MODES + uint8_t color; ///< LED color, see ::MBG_LED_COLORS + uint16_t reserved; ///< Currently reserved, unused, always 0 + +} MBG_LED_SETTINGS; + +#define _mbg_swab_mbg_led_settings( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->mode ); \ + _mbg_swab8( &(_p)->color ); \ + _mbg_swab16( &(_p)->reserved ); \ +} while ( 0 ) + + + +/** + * @brief Configuration settings for a single LED, plus index + * + * @see ::MBG_LED_SETTINGS + * @see ::MBG_LED_LIMITS + */ +typedef struct +{ + uint16_t idx; ///< 0..::MBG_LED_LIMITS::num_leds-1 + MBG_LED_SETTINGS settings; ///< LED settings + +} MBG_LED_SETTINGS_IDX; + +#define _mbg_swab_mbg_led_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_mbg_led_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +/** + * @brief Current settings and general capabilities of an LED + * + * This structure should be read from the device to retrieve the + * current settings of an LED plus its capabilities, e.g. the + * supported modes, colors, etc. + * + * @see ::MBG_LED_INFO_IDX + */ +typedef struct +{ + MBG_LED_SETTINGS settings; ///< Current LED settings + uint32_t supp_modes; ///< Supported modes, see ::MBG_LED_MODE_MASKS + uint32_t supp_colors; ///< Supported colors, see ::MBG_LED_COLOR_MASKS + uint32_t reserved; ///< Currently reserved, unused, always 0 + uint32_t flags; ///< Currently reserved, unused, always 0 + +} MBG_LED_INFO; + +#define _mbg_swab_mbg_led_info( _p ) \ +do \ +{ \ + _mbg_swab_mbg_led_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_modes ); \ + _mbg_swab32( &(_p)->supp_colors ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Current settings and general capabilities of an LED, plus index + * + * @see ::MBG_LED_INFO + * @see ::MBG_LED_LIMITS + */ +typedef struct +{ + uint16_t idx; ///< 0..::MBG_LED_LIMITS::num_leds-1 + MBG_LED_INFO info; ///< LED info + +} MBG_LED_INFO_IDX; + +#define _mbg_swab_mbg_led_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_mbg_led_info( &(_p)->info ); \ +} while ( 0 ) + +/** @} defgroup group_led_api */ + + + +/** + * @defgroup group_lne_api Definitions specific to LNE devices + * + * @note These structures and definitions are only supported by a device + * if ::MBG_XFEATURE_LNE_API is set in the extended device features. + * + * @{ */ + + +/** + * @brief General info to be read from an LNE device + * + * Used to query from a device e.g. how many LNE ports are provided + * by the device, then index 0..::MBG_LNE_LIMITS::num_ports-1 + * ::MBG_LNE_PORT_INFO_IDX or ::MBG_LNE_PORT_SETTINGS_IDX structures + * can be read from or written to the device. + * + * @see ::MBG_LNE_PORT_SETTINGS_IDX + * @see ::MBG_LNE_PORT_INFO_IDX + */ +typedef struct +{ + uint8_t num_ports; ///< Number of supported ports, see ::MBG_LNE_PORT_SETTINGS_IDX::idx and ::MBG_LNE_PORT_INFO_IDX::idx + uint8_t reserved_0; ///< Currently reserved, unused, always 0 + uint16_t reserved_1; ///< Currently reserved, unused, always 0 + uint32_t features; // ### TODO Mask of supported features, see ::MBG_LNE_FEAT_MASKS + ///< Currently reserved, unused, always 0 + uint32_t reserved_2; ///< Currently reserved, unused, always 0 + +} MBG_LNE_LIMITS; + +#define _mbg_swab_mbg_lne_limits( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->num_ports ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->features ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) + + + +#if 0 //### TODO //################# + +/** + * @brief LNE feature bits + * + * Used to define ::MBG_LNE_FEAT_MASKS + * + * @see ::MBG_LNE_FEAT_MASKS + */ +enum MBG_LNE_FEAT_BITS +{ + MBG_LNE_FEAT_BIT_SWITCH_PWR, ///< Power switching off all LNE ports at once supported, see ::MBG_LNE_PWR_STATE + N_MBG_LNE_FEAT_BITS +}; + + + +/** + * @brief LNE feature bit masks + * + * Used with ::MBG_LNE_LIMITS::features + * + * @see ::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 +}; + +#endif + + + +/** + * @brief Configuration settings for a single LNE port + * + * @see ::MBG_LNE_PORT_SETTINGS_IDX + */ +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; ///< currently reserved, unused, always 0 + +} MBG_LNE_PORT_SETTINGS; + +#define _mbg_swab_mbg_lne_port_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Configuration settings for a single LNE port, plus index + * + * @see ::MBG_LNE_PORT_SETTINGS + * @see ::MBG_LNE_LIMITS + */ +typedef struct +{ + uint16_t idx; ///< 0..::MBG_LNE_LIMITS::num_ports-1 + MBG_LNE_PORT_SETTINGS settings; ///< LNE settings + +} MBG_LNE_PORT_SETTINGS_IDX; + +#define _mbg_swab_mbg_lne_port_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_mbg_lne_port_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +/** + * @brief Current settings and general capabilities of an LNE port + * + * This structure should be read from the device to retrieve the + * current settings of an LNE port plus its capabilities, ### e.g. the + * supported modes, colors, etc. + * + * @see ::MBG_LNE_PORT_INFO_IDX + */ +typedef struct +{ + MBG_LNE_PORT_SETTINGS settings; ///< Current LNE port settings + MBG_MAC_ADDR mac_addr; ///< The MAC address assigned to this port + 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 + +} MBG_LNE_PORT_INFO; + +#define _mbg_swab_mbg_lne_port_info( _p ) \ +do \ +{ \ + _mbg_swab_mbg_lne_port_settings( &(_p)->settings ); \ + _mbg_swab_mbg_mac_addr( &(_p)->mac_addr ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Current settings and general capabilities of an LNE port, plus index + * + * @see ::MBG_LNE_PORT_INFO + * @see ::MBG_LNE_LIMITS + */ +typedef struct +{ + uint16_t idx; ///< 0..::MBG_LED_LIMITS::num_leds-1 + MBG_LNE_PORT_INFO info; ///< LNE port info + +} MBG_LNE_PORT_INFO_IDX; + +#define _mbg_swab_mbg_lne_port_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_mbg_lne_port_info( &(_p)->info ); \ +} while ( 0 ) + + + +/** + * @brief LNE port flag bits + * + * Used to define ::LNE_PORT_FLAG_MASKS + * + * @see ::LNE_PORT_FLAG_MASKS + */ +enum LNE_PORT_FLAG_BITS +{ + LNE_PORT_FLAG_BIT_IS_SFP, + N_LNE_PORT_FLAG_BITS +}; + + + +/** + * @brief LNE port flag bit masks + * + * Used with ::MBG_LNE_PORT_INFO::flags + * + * @see ::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 +}; + + +/** @} defgroup group_lne_api */ + + + +/** + * @defgroup group_pwr_ctl_api Definitions for power control API + * + * @note These structures and definitions are only supported by a device + * if ::MBG_XFEATURE_PWR_CTL_API is set in the extended device features. + * + * @{ */ + + +/** + * @brief Device power states + * + * Used with ::MBG_PWR_CTL::state. + */ +enum MBG_PWR_STATES +{ + MBG_PWR_STATE_OFF, + MBG_PWR_STATE_ON, + N_MBG_PWR_STATES +}; + + + +/** + * @brief Device power control + * + * Used to change or retrieve a device's power state + */ +typedef struct +{ + 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 + +} MBG_PWR_CTL; + +#define _mbg_swab_mbg_pwr_ctl( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->state ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ +} while ( 0 ) + +/** @} defgroup group_pwr_ctl_api */ + + + + +/** + * @defgroup group_ext_sys_info Extended system information + * + * @note This structure and its definitions are only supported by a device + * if ::MBG_XFEATURE_EXT_SYS_INFO is set in the extended device features. + * + * @{ */ + + +/** + * @brief Bits used to define ::MBG_EXT_SYS_INFO_MSKS + * + * @see ::MBG_EXT_SYS_INFO_MSKS + */ +enum MBG_EXT_SYS_INFO_BITS +{ + MBG_EXT_SYS_INFO_BIT_SW_REV, + MBG_EXT_SYS_INFO_BIT_HW_REV, + MBG_EXT_SYS_INFO_BIT_OS_REV, + MBG_EXT_SYS_INFO_BIT_FPGA_REV, + MBG_EXT_SYS_INFO_BIT_CORE_MOD_REV, + MBG_EXT_SYS_INFO_BIT_OS_TYPE, + MBG_EXT_SYS_INFO_BIT_RAM_SIZE, + MBG_EXT_SYS_INFO_BIT_STORAGE_SIZE, + MBG_EXT_SYS_INFO_BIT_RELEASE_CANDIDATE, + MBG_EXT_SYS_INFO_BIT_OS_TARGET, + N_MBG_EXT_SYS_INFO_BITS +}; + +/** + * @brief Bit masks of supported revision numbers + * + * Used with ::MBG_EXT_SYS_INFO::supp_members + * + * @see ::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 +}; + + +enum MBG_EXT_SYS_INFO_PROC_TYPES +{ + MBG_EXT_SYS_INFO_PROC_TYPE_NONE, + MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_A9, + MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_SAM3u, + MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_SAM3s, + MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_STM32F4, + N_MBG_EXT_SYS_INFO_PROC_TYPES +}; + +#define MBG_EXT_SYS_INFO_PROC_STRS \ +{ \ + "None", \ + "Cortex A9", \ + "Cortex SAM3u", \ + "Cortex SAM3s", \ + "Cortex STM32F4" \ +} + +enum MBG_EXT_SYS_INFO_FPGA_TYPES +{ + MBG_EXT_SYS_INFO_FPGA_TYPE_NONE, + MBG_EXT_SYS_INFO_FPGA_TYPE_CYCLONE5_SOC, ///< System on chip + MBG_EXT_SYS_INFO_FPGA_TYPE_CYCLONE5, ///< Stand alone FPGA + MBG_EXT_SYS_INFO_FPGA_TYPE_CYCLONE4GX15, + MBG_EXT_SYS_INFO_FPGA_TYPE_CYLCONE4CE22, + N_MBG_EXT_SYS_INFO_FPGA_TYPES +}; + +#define MBG_EXT_SYS_INFO_FPGA_STRS \ +{ \ + "None", \ + "Cyclone5 SoC", \ + "Cyclone5", \ + "Cyclone4GX15", \ + "Cyclone4CE22" \ +} + +enum MBG_EXT_SYS_INFO_CORE_MOD_TYPES +{ + MBG_EXT_SYS_INFO_CORE_MOD_TYPE_NONE, + MBG_EXT_SYS_INFO_CORE_MOD_TYPE_UBX_LEA_M8F, ///< u-blox GNSS module without Galileo support + MBG_EXT_SYS_INFO_CORE_MOD_TYPE_UBX_LEA_M8T, ///< u-blox GNSS module with Galileo support + N_MBG_EXT_SYS_INFO_CORE_MOD_TYPES +}; + +#define MBG_EXT_SYS_INFO_CORE_MOD_STRS \ +{ \ + "None", \ + "u-blox LEA-M8F", \ + "u-blox LEA-M8T" \ +} + +/* + * OS Type can be used a GPS_MODEL_CODE + */ +enum MBG_EXT_SYS_INFO_OS_TYPES +{ + MBG_EXT_SYS_INFO_OS_TYPE_NONE, + MBG_EXT_SYS_INFO_OS_TYPE_PICO_OS, + MBG_EXT_SYS_INFO_OS_TYPE_NANO_OS, + MBG_EXT_SYS_INFO_OS_TYPE_MICRO_OS, + MBG_EXT_SYS_INFO_OS_TYPE_SYNC_OS, + MBG_EXT_SYS_INFO_OS_TYPE_ANY_OS, + N_MBG_EXT_SYS_INFO_OS_TYPES +}; + + +#define MBG_EXT_SYS_INFO_OS_SHORT_STRS \ +{ \ + " ", \ + "p", \ + "n", \ + "u", \ + "s", \ + "x" \ +} + + +#define MBG_EXT_SYS_INFO_OS_STRS \ +{ \ + "none", \ + "pico", \ + "nano", \ + "micro", \ + "sync", \ + "any" \ +} + +/// CPU mainline +#define MBG_EXT_SYS_INFO_CPU_MSK 0xff + +/// CPU generation +#define MBG_EXT_SYS_INFO_CPU_GEN_MSK 0xf + +/// CPU variant +#define MBG_EXT_SYS_INFO_CPU_VAR_MSK 0xf + +#define _mbg_ext_sys_info_get_cpu(var) (((var) >> 8) & MBG_EXT_SYS_INFO_CPU_MSK) +#define _mbg_ext_sys_info_get_cpu_gen(var) (((var) >> 4) & MBG_EXT_SYS_INFO_CPU_GEN_MSK) +#define _mbg_ext_sys_info_get_cpu_var(var) ((var) & MBG_EXT_SYS_INFO_CPU_VAR_MSK) + +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, + N_MBG_EXT_SYS_INFO_CPUS +}; + +#define MBG_EXT_SYS_INFO_CPU_STRS \ +{ \ + "Unknown", \ + "HPS USB host", \ + "HPS USB device" \ +} + +#define __CPU_CODEC(cpu, gen, var) \ + (((cpu) & MBG_EXT_SYS_INFO_CPU_MSK) << 8) | \ + (((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 +#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 +#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 +#define HPS_USB_DEVICE_G1_V1 __CPU_CODEC(MBG_EXT_SYS_INFO_CPU_HPS_USB_DEVICE, 1, 1) + +typedef struct +{ + uint32_t supp_members; ///< ::MBG_EXT_SYS_INFO_MSKS + + uint32_t sw_rev; + uint32_t hw_rev; + uint32_t os_rev; + uint32_t fpga_rev; + + uint16_t proc_type; ///< See ::MBG_EXT_SYS_INFO_PROC_TYPES + uint16_t fpga_type; ///< See ::MBG_EXT_SYS_INFO_FPGA_TYPES + uint16_t core_mod_type; ///< See ::MBG_EXT_SYS_INFO_CORE_MOD_TYPES + uint16_t mbg_os_type; ///< See ::MBG_EXT_SYS_INFO_OS_TYPES + + uint32_t core_mod_rev; + + uint32_t ram_size; ///< RAM size in MB + uint32_t storage_size; ///< Storage size in MB + + uint8_t release_candidate;///< Release candidate number (0 = final release) + + /* 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; + + 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; + +} MBG_EXT_SYS_INFO; + +#define _mbg_swab_ext_sys_info( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_members ); \ + _mbg_swab32( &(_p)->sw_rev ); \ + _mbg_swab32( &(_p)->hw_rev ); \ + _mbg_swab32( &(_p)->os_rev ); \ + _mbg_swab32( &(_p)->fpga_rev ); \ + _mbg_swab16( &(_p)->proc_type ); \ + _mbg_swab16( &(_p)->fpga_type ); \ + _mbg_swab16( &(_p)->core_mod_type ); \ + _mbg_swab16( &(_p)->os_type ); \ + _mbg_swab16( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->core_mod_rev ); \ + _mbg_swab32( &(_p)->ram_size ); \ + _mbg_swab32( &(_p)->storage_size ); \ + _mbg_swab16( &(_p)->os_target ); \ +} while ( 0 ) + + +#define _mbg_encode_revision( _major, _minor, _patch ) \ + ( ( (_major) << 24) | ( (_minor) << 16 ) | (_patch) ) + + +#define _mbg_decode_revision( _rev, _major, _minor, _patch ) \ +{ \ + (_major) = ( (_rev) >> 24 ) & 0xff; \ + (_minor) = ( (_rev) >> 16 ) & 0xff; \ + (_patch) = (_rev) & 0xffff; \ +} + + +/** @} defgroup group_ext_sys_info */ + + +/** + * @defgroup group_license_limits License information + * + * @note This is probably obsolete. + * + * @{ */ + + +#define MBG_MAX_LICENSES 32 + + +/** + * @brief General license information to be read from a device + * + * Used to query from a device how many and which different license types + * are supported. If a special type is supported (licenses[MBG_LICENSE_BASE_TYPES] > 0), its + * license specific information can be queried from 0..licenses[MBG_LICENSE_BASE_TYPES]-1 via + * its license specific [...]_IDX structures and TLV API command codes. + * See ::MBG_XFEATURE_TLV_API and ::MBG_TLV_FEAT_TYPES. + */ +typedef struct +{ + uint8_t licenses[MBG_MAX_LICENSES]; ///< To get the number of supported licenses + ///< of a specific type you need to access the array + ///< with the specififc license index defined at ::MBG_LICENSE_BASE_TYPES. +} MBG_LICENSE_LIMITS; + + +enum MBG_LICENSE_BASE_TYPES +{ + MBG_LICENSE_BASE_TYPE_PTPV2, + MBG_LICENSE_BASE_TYPE_NTP, + MBG_LICENSE_BASE_TYPE_PTPV1, + MBG_LICENSE_BASE_TYPE_TIME_MONITOR, + N_MBG_LICENSE_BASE_TYPES +}; + + +/** + * @brief Bits used to define ::MBG_LICENSE_BASE_MSKS + * + * @see ::MBG_LICENSE_BASE_MSKS + */ +enum MBG_LICENSE_BASE_FLAGS +{ + MBG_LICENSE_BASE_FLAG_SUPP_UPGRADE, ///< License supports upgrading / modifying + N_MBG_LICENSE_BASE_FLAGS +}; + + +/** + * @brief Bit masks of common supported base license flags + * + * Used with ::MBG_LICENSE_BASE::supp_flags + * + * @see ::MBG_LICENSE_BASE_FLAGS + */ +enum MBG_LICENSE_BASE_MSKS +{ + MBG_LICENSE_BASE_MSK_SUPP_UPGRADE = ( 1UL << MBG_LICENSE_BASE_FLAG_SUPP_UPGRADE ) ///< See ::MBG_LICENSE_BASE_FLAG_SUPP_UPGRADE +}; + + +/** + * @brief Common license information + * + * Should be part of each individual license type. + */ +typedef struct +{ + uint8_t type; ///< See ::MBG_LICENSE_BASE_TYPES + uint8_t reserved_1; ///< Reserved for future use, currently 0 + uint16_t reserved_2; ///< Reserved for future use, currently 0 + uint32_t supp_flags; ///< See ::MBG_LICENSE_BASE_MSKS + uint32_t reserved_3; ///< Reserved for future use, currently 0 + uint32_t reserved_4; ///< Reserved for future use, currently 0 + +} MBG_LICENSE_BASE; + +#define _mbg_swab_license_base( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + +/** + * @brief Bits used to define ::MBG_LICENSE_PTPV2_MEMBER_MSKS + * + * @see ::MBG_LICENSE_PTPV2_MEMBER_MSKS + */ +enum MBG_LICENSE_PTPV2_MEMBERS +{ + MBG_LICENSE_PTPV2_MEMBER_MAX_UCLIENTS, + MBG_LICENSE_PTPV2_MEMBER_MAX_MTRANS, + N_MBG_LICENSE_PTPV2_MEMBERS +}; + + +/** + * @brief Bit masks of PTPV2 license specific members + * + * Used with ::MBG_LICENSE_PTPV2::supp_members + * + * @see ::MBG_LICENSE_PTPV2_MEMBERS + */ +enum MBG_LICENSE_PTPV2_MEMBER_MSKS +{ + MBG_LICENSE_PTPV2_MEMBER_MSK_MAX_UCLIENTS = ( 1UL << MBG_LICENSE_PTPV2_MEMBER_MAX_UCLIENTS ), ///< See ::MBG_LICENSE_PTPV2_MEMBER_MAX_UCLIENTS + MBG_LICENSE_PTPV2_MEMBER_MSK_MAX_MTRANS = ( 1UL << MBG_LICENSE_PTPV2_MEMBER_MAX_MTRANS ) ///< See ::MBG_LICENSE_PTPV2_MEMBER_MAX_MTRANS +}; + + +/** + * @brief PTPV2 specific license information + * + */ +typedef struct +{ + MBG_LICENSE_BASE base; ///< See ::MBG_LICENSE_BASE + uint32_t supp_members; ///< See ::MBG_LICENSE_PTPV2_MEMBER_MSKS + uint32_t reserved_1; ///< Reserved for future use, currently 0 + uint16_t max_uclients; ///< Maximal number of supported unicast clients. + uint16_t reserved_2; ///< Reserved for future use, currently 0 + uint32_t max_mtrans; ///< Maximal number of supported multicast transactions per second. + uint32_t reserved_3; ///< Reserved for future use, currently 0 + uint32_t reserved_4; ///< Reserved for future use, currently 0 + uint32_t reserved_5; ///< Reserved for future use, currently 0 + uint32_t reserved_6; ///< Reserved for future use, currently 0 + +} MBG_LICENSE_PTPV2; + +#define _mbg_swab_license_ptpv2( _p ) \ +do \ +{ \ + _mbg_swab_license_base( &(_p)->base ); \ + _mbg_swab32( &(_p)->supp_members ); \ + _mbg_swab16( &(_p)->max_uclients ); \ + _mbg_swab32( &(_p)->max_mtrans ); \ +} while ( 0 ) + + +typedef struct +{ + uint32_t idx; + MBG_LICENSE_PTPV2 license; + +} MBG_LICENSE_PTPV2_IDX; + +#define _mbg_swab_license_ptpv2_idx( _p ) \ +do \ +{ \ + _mbg_swab_license_ptpv2( &(_p)->license ); \ + _mbg_swab32( &(_p)->idx ); \ +} while ( 0 ) + + +/** + * @brief Bits used to define ::MBG_LICENSE_NTP_MEMBER_MSKS + * + * @see ::MBG_LICENSE_NTP_MEMBER_MSKS + */ +enum MBG_LICENSE_NTP_MEMBERS +{ + MBG_LICENSE_NTP_MEMBER_MAX_RPS, + N_MBG_LICENSE_NTP_MEMBERS +}; + + +/** + * @brief Bit masks of NTP license specific members + * + * Used with ::MBG_LICENSE_NTP::supp_members + * + * @see ::MBG_LICENSE_PTPV2_MEMBERS + */ +enum MBG_LICENSE_NTP_MEMBER_MSKS +{ + MBG_LICENSE_NTP_MEMBER_MSK_MAX_RPS = ( 1UL << MBG_LICENSE_NTP_MEMBER_MAX_RPS ) ///< See ::MBG_LICENSE_NTP_MEMBER_MAX_RPS +}; + + +/** + * @brief NTP specific license information + */ +typedef struct +{ + MBG_LICENSE_BASE base; ///< See ::MBG_LICENSE_BASE + uint32_t supp_members; ///< See ::MBG_LICENSE_NTP_MEMBER_MSKS + uint32_t max_rps; ///< Maximum number of supported NTP requests per second + uint32_t reserved_1; ///< Reserved for future use, currently 0 + uint32_t reserved_2; ///< Reserved for future use, currently 0 + uint32_t reserved_3; ///< Reserved for future use, currently 0 + uint32_t reserved_4; ///< Reserved for future use, currently 0 + uint32_t reserved_5; ///< Reserved for future use, currently 0 + uint32_t reserved_6; ///< Reserved for future use, currently 0 + +} MBG_LICENSE_NTP; + +#define _mbg_swab_license_ntp( _p ) \ +do \ +{ \ + _mbg_swab_license_base( &(_p)->base ); \ + _mbg_swab32( &(_p)->supp_members ); \ + _mbg_swab32( &(_p)->max_rps ); \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t idx; + MBG_LICENSE_NTP license; + +} MBG_LICENSE_NTP_IDX; + +#define _mbg_swab_license_ntp_idx( _p ) \ +do \ +{ \ + _mbg_swab_license_ntp( &(_p)->license ); \ + _mbg_swab32( &(_p)->idx ); \ +} while ( 0 ) + +/** + * @brief Bits used to define ::MBG_LICENSE_PTPV1_MEMBER_MSKS + * + * @see ::MBG_LICENSE_PTPV1_MEMBER_MSKS + */ +enum MBG_LICENSE_PTPV1_MEMBERS +{ + MBG_LICENSE_PTPV1_MEMBER_MAX_RPS, + N_MBG_LICENSE_PTPV1_MEMBERS +}; + + +/** + * @brief Bit masks of PTPV1 license specific members + * + * Used with ::MBG_LICENSE_PTPV1::supp_members + * + * @see ::MBG_LICENSE_PTPV2_MEMBERS + */ +enum MBG_LICENSE_PTPV1_MEMBER_MSKS +{ + MBG_LICENSE_PTPV1_MEMBER_MSK_MAX_RPS = ( 1UL << MBG_LICENSE_PTPV1_MEMBER_MAX_RPS ) ///< See ::MBG_LICENSE_PTPV1_MEMBER_MAX_RPS +}; + + +/** + * @brief NTP specific license information + */ +typedef struct +{ + MBG_LICENSE_BASE base; ///< See ::MBG_LICENSE_BASE + uint32_t supp_members; ///< See ::MBG_LICENSE_PTPV1_MEMBER_MSKS + uint32_t max_rps; ///< Maximum number of supported PTPv1 delay requests per second + uint32_t reserved_1; ///< Reserved for future use, currently 0 + uint32_t reserved_2; ///< Reserved for future use, currently 0 + uint32_t reserved_3; ///< Reserved for future use, currently 0 + uint32_t reserved_4; ///< Reserved for future use, currently 0 + uint32_t reserved_5; ///< Reserved for future use, currently 0 + uint32_t reserved_6; ///< Reserved for future use, currently 0 + +} MBG_LICENSE_PTPV1; + +#define _mbg_swab_license_ptpv1( _p ) \ +do \ +{ \ + _mbg_swab_license_base( &(_p)->base ); \ + _mbg_swab32( &(_p)->supp_members ); \ + _mbg_swab32( &(_p)->max_rps ); \ +} while ( 0 ) + + +typedef struct +{ + uint32_t idx; + MBG_LICENSE_PTPV1 license; + +} MBG_LICENSE_PTPV1_IDX; + +#define _mbg_swab_license_ptpv1_idx( _p ) \ +do \ +{ \ + _mbg_swab_license_ptpv1( &(_p)->license ); \ + _mbg_swab32( &(_p)->idx ); \ +} while ( 0 ) + +/** + * @brief Bits used to define ::MBG_LICENSE_TIME_MONITOR_MEMBER_MSKS + * + * @see ::MBG_LICENSE_TIME_MONITOR_MEMBER_MSKS + */ +enum MBG_LICENSE_TIME_MONITOR_MEMBERS +{ + MBG_LICENSE_TIME_MONITOR_MEMBER_MAX_PTPV2_CLIENTS, + MBG_LICENSE_TIME_MONITOR_MEMBER_MAX_NTP_CLIENTS, + N_MBG_LICENSE_TIME_MONITOR_MEMBERS +}; + + +/** + * @brief Bit masks of Sync Monitor license specific members + * + * Used with ::MBG_LICENSE_TIME_MONITOR::supp_members + * + * @see ::MBG_LICENSE_TIME_MONITOR_MEMBERS + */ +enum MBG_LICENSE_TIME_MONITOR_MEMBER_MSKS +{ + MBG_LICENSE_TIME_MONITOR_MEMBER_MSK_MAX_PTPV2_CLIENTS = ( 1UL << MBG_LICENSE_TIME_MONITOR_MEMBER_MAX_PTPV2_CLIENTS ), ///< See ::MBG_LICENSE_TIME_MONITOR_MEMBER_MAX_PTPV2_CLIENTS + MBG_LICENSE_TIME_MONITOR_MEMBER_MSK_MAX_NTP_CLIENTS = ( 1UL << MBG_LICENSE_TIME_MONITOR_MEMBER_MAX_NTP_CLIENTS ) ///< See ::MBG_LICENSE_TIME_MONITOR_MEMBER_MAX_NTP_CLIENTS +}; + + +/** + * @brief Sync Monitor specific license information + * + */ +typedef struct +{ + MBG_LICENSE_BASE base; ///< See ::MBG_LICENSE_BASE + uint32_t supp_members; ///< See ::MBG_LICENSE_TIME_MONITOR_MEMBER_MSKS + uint32_t reserved_1; ///< Reserved for future use, currently 0 + uint16_t max_ptpv2_clients; ///< Maximum number of supported PTPv2 clients to be monitored + uint16_t max_ntp_clients; ///< Maximum number of supported NTP clients to be monitored + uint32_t reserved_2; ///< Reserved for future use, currently 0 + uint32_t reserved_3; ///< Reserved for future use, currently 0 + uint32_t reserved_4; ///< Reserved for future use, currently 0 + uint32_t reserved_5; ///< Reserved for future use, currently 0 + uint32_t reserved_6; ///< Reserved for future use, currently 0 + +} MBG_LICENSE_TIME_MONITOR; + +#define _mbg_swab_license_time_monitor( _p ) \ +do \ +{ \ + _mbg_swab_license_base( &(_p)->base ); \ + _mbg_swab32( &(_p)->supp_members ); \ + _mbg_swab16( &(_p)->max_ptpv2_clients ); \ + _mbg_swab16( &(_p)->max_ntp_clients ); \ +} while ( 0 ) + + +typedef struct +{ + uint32_t idx; + MBG_LICENSE_TIME_MONITOR license; + +} MBG_LICENSE_TIME_MONITOR_IDX; + +#define _mbg_swab_license_time_monitor_idx( _p ) \ +do \ +{ \ + _mbg_swab_license_time_monitor( &(_p)->license ); \ + _mbg_swab32( &(_p)->idx ); \ +} while ( 0 ) + +/** @} defgroup group_license_limits */ + + + +/** + * @defgroup group_clk_res_info Clock resolution info + * + * @note This structure and its definitions are only supported by a device + * if ::MBG_XFEATURE_CLK_RES_INFO is set in the extended device features. + * + * @{ */ + +/** + * @brief Clock resolution information + * + * @see @ref group_clk_res_info + */ +typedef struct +{ + uint32_t base_clk; ///< Base clock of the internal time base [MHz] + uint32_t num_clk_phase; ///< Number of multi-phase clock signals + uint32_t reserved_9; + uint32_t reserved_8; + uint32_t reserved_7; + uint32_t reserved_6; + uint32_t reserved_5; + uint32_t reserved_4; + uint32_t reserved_3; + uint32_t reserved_2; + uint32_t reserved_1; + uint32_t reserved_0; + +} MBG_CLK_RES_INFO; + +#define _mbg_swab_mbg_clk_res_info( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->base_clk ); \ + _mbg_swab32( &(_p)->num_clk_phase ); \ + _mbg_swab32( &(_p)->reserved_9 ); \ + _mbg_swab32( &(_p)->reserved_8 ); \ + _mbg_swab32( &(_p)->reserved_7 ); \ + _mbg_swab32( &(_p)->reserved_6 ); \ + _mbg_swab32( &(_p)->reserved_5 ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ +} while ( 0 ) + +/** @} defgroup group_clk_res_info */ + + + +/** + * @brief Type of upcoming transaction sequence + * + * Used in combination with ::GPS_BEGIN_TRANSACTION and ::GPS_END_TRANSACTION + * to announce which type of transaction is going to be started. Thus the receiver + * can prepare for following actions. + */ +enum MBG_TRANSACTION_TYPES +{ + MBG_TRANSACTION_TYPE_NONE, + /* ### TODO FIXME + * Network transaction requires at least and as first command: + * - ::GPS_NET_GLB_CFG (::MBG_NET_GLB_CFG_INFO) + * Depending on ::MBG_NET_GLB_CFG_INFO::glb_settings and its num_[...] + * members there are a couple of index commands which should be handled in any order: + * - ::GPS_NET_DNS_SRVR (::MBG_IP_ADDR_IDX) + * - ::GPS_NET_DNS_SRCH_DOM (::MBG_NET_NAME_IDX) + * - ::GPS_NET_INTF_LINK_IDX (::MBG_NET_INTF_LINK_INFO_IDX) + * - ::GPS_NET_INTF_ADDR_IDX (::MBG_NET_INTF_ADDR_INFO_IDX) + * - ::GPS_NET_INTF_ROUTE_IDX (::MBG_NET_INTF_ROUTE_INFO_IDX) + */ + MBG_TRANSACTION_TYPE_NETWORK, + MBG_TRANSACTION_TYPE_PTP, + /* + * Commands in any order if supp. by ::MBG_SNMP_GLB_INFO::max_[...] + * and ::MBG_SNMP_GLB_INFO::supp_versions + * + * Should be used within ::MBG_TRANSACTION_TYPE_MONITORING but may also be + * used stand-alone. + * + * - ::GPS_SNMP_GLB_SETTINGS + * - ::GPS_SNMP_V12_SETTINGS_IDX + * - ::GPS_SNMP_V12_TRAP_SETTINGS_IDX + * - ::GPS_SNMP_V3_SETTINGS_IDX + * - ::GPS_SNMP_V3_TRAP_SETTINGS_IDX + */ + MBG_TRANSACTION_TYPE_MONITORING_SNMP, + /* + * NTP transaction requires at least and as first command: + * ::GPS_NTP_GLB_CFG + * Commands in any order if supp. by ::MBG_NTP_GLB_INFO + * and ::MBG_SNMP_GLB_INFO::supp_versions + * + * - ::GPS_NTP_REFCLK_CFG + * - ::GPS_NTP_MISC_LIMITS + * - ::GPS_NTP_MISC_ORPHAN_MODE + * - ::GPS_NTP_SYMM_KEY_LIMITS + * - ::GPS_NTP_SYMM_KEY_CFG + * - ::GPS_NTP_TRUSTED_KEY_CFG + * - ::GPS_NTP_CLNT_MODE_CFG + * - ::GPS_NTP_SRV_MODE_CFG + * - ::GPS_NTP_PEER_SETTINGS_IDX + * - ::GPS_NTP_SYS_STATE + * - ::GPS_NTP_PEER_STATE_IDX + */ + MBG_TRANSACTION_TYPE_NTP, + /* + * IO Port transaction used to read or write ALL_IO_PORT_INFO + * Commands related to this transaction: + * + * - ::GPS_IO_PORT_LIMITS + * - ::GPS_IO_PORT_SETTINGS_IDX + * - ::GPS_IO_PORT_INFO_IDX + * - ::GPS_IO_PORT_TYPE_INFO_IDX + * - ::GPS_IO_PORT_STATUS_IDX + */ + MBG_TRANSACTION_TYPE_IO_PORT, + /* + * Commands in any order if ::MBG_XFEATURE_MONITORING is set in + * ::MBG_XFEATURE_BUFFER. + * + * Transactions ::MBG_TRANSACTION_TYPE_MONITORING_SNMP and + * ::MBG_TRANSACTION_TYPE_EVENTS may also be opened within + * ::MBG_TRANSACTION_TYPE_MONITORING transaction. + * + * - ::GPS_MONITORING_LIMITS + * - ::GPS_MONITORING_STATUS + */ + MBG_TRANSACTION_TYPE_MONITORING, + /* + * Commands in any order if ::MBG_XFEATURE_MONITORING is set in + * ::MBG_XFEATURE_BUFFER. + * + * Should be used within ::MBG_TRANSACTION_TYPE_MONITORING but may also be + * used stand-alone. + * + * - ::GPS_EVENT_IDX + * - ::GPS_EVENT_STAT_IDX + */ + MBG_TRANSACTION_TYPE_EVENTS, + + /* + * User Management transaction is supported, + * if ::MBG_XFEATURE_MONITORING is set in ::MBG_XFEATURE_BUFFER and + * requires at least and as first command: ::GPS_USER_MNGMNT_INFO + * + * Other commands in any order + * + * - ::GPS_USER_INFO_IDX + * - ::GPS_USER_LEVEL_INFO_IDX + * - ::GPS_USER_STATUS_IDX + */ + MBG_TRANSACTION_TYPE_USER_MNGMNT, + + /* + * Should be used within ::MBG_TRANSACTION_TYPE_MONITORING but may also be + * used stand-alone. + * + * - ::GPS_SYSLOG_GLB_INFO + * - ::GPS_SYSLOG_INFO_IDX + */ + MBG_TRANSACTION_TYPE_MONITORING_SYSLOG, + + /* + * Firmware Management transaction is supported, + * if ::MBG_XFEATURE_FW_MNGMNT is set in ::MBG_XFEATURE_BUFFER and + * requires at least and as first command: ::GPS_FW_GLB_INFO + * + * Other commands in any order + * + * - ::GPS_FW_INFO_IDX + * - ::GPS_FW_UFU_INFO_IDX + */ + MBG_TRANSACTION_TYPE_FIRMWARE_MNGMNT, + + /* + * Database transaction is supported, + * if ::MBG_XFEATURE_DATABASE is set in ::MBG_XFEATURE_BUFFER and + * requires at least and as first command: ::GPS_DATABASE_GLB_INFO + * + * Other commands in any order + * + * - ::GPS_DATABASE_GLB_INFO + * - ::GPS_DATABASE_INFO_IDX + */ + MBG_TRANSACTION_TYPE_DATABASE, + + MAX_MBG_TRANSACTION_TYPES +}; + + +#define MBG_TRANSACTION_MSK_SET 0x8000 ///< Only relevant when starting a transaction +#define MBG_TRANSACTION_MSK_SUCCESS 0x4000 ///< Only relevant when ending a transaction + +#define _mbg_is_set_transaction( _type ) ( ( _type ) & MBG_TRANSACTION_MSK_SET ) +#define _mbg_transaction_type_set( _type ) ( ( _type ) |= MBG_TRANSACTION_MSK_SET ) + +#define _mbg_transaction_success( _type ) ( ( _type ) & MBG_TRANSACTION_MSK_SUCCESS ) +#define _mbg_transaction_set_success( _type ) ( ( _type ) |= MBG_TRANSACTION_MSK_SUCCESS ) + + +/** + * @defgroup group_io_ports IO Port API + * + * @note This structure and its definitions are only supported by a device + * if ::MBG_XFEATURE_IO_PORTS is set in the extended device features. + * + * @{ */ + +/** + * @brief IO Port types + * + * Used with ::MBG_IO_PORT_TYPE_INFO::port_type and ::MBG_IO_PORT_SETTINGS::port_type + */ +enum MBG_IO_PORT_TYPES +{ + MBG_IO_PORT_TYPE_PPS, + MBG_IO_PORT_TYPE_10MHz, + MBG_IO_PORT_TYPE_2048KHz, + MBG_IO_PORT_TYPE_GPIO, + MBG_IO_PORT_TYPE_ETHERNET, + MBG_IO_PORT_TYPE_TERMINAL, + 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_LIGHT, + MBG_IO_PORT_TYPE_ANTENNA, + MBG_IO_PORT_TYPE_UART, + MBG_IO_PORT_TYPE_DCF77, + MBG_IO_PORT_TYPE_POWER, + N_MBG_IO_PORT_TYPES +}; + +/** + * @brief Port type to be used for an undefined/unassigned port + * + * Only use this for ::MBG_IO_PORT_SETTINGS::port_type + * if ::MBG_IO_PORT_SETTINGS::op_mode is ::MBG_IO_PORT_OP_MODE_NONE + */ +#define MBG_IO_PORT_TYPE_NONE ( (uint16_t) -1 ) + + +/** + * @brief Strings descriptions for ::MBG_IO_PORT_TYPES + * + * Can be used to initialize a string array of ::N_MBG_IO_PORT_TYPES entries, + * so the number of strings must correspond to ::N_MBG_IO_PORT_TYPES. + * + * @see ::MBG_IO_PORT_TYPES + */ +#define MBG_IO_PORT_TYPE_STRS \ +{ \ + "PPS", \ + "10 MHz", \ + "2048 KHz", \ + "GPIO", \ + "Ethernet", \ + "Terminal", \ + "Multi", \ + "Prog. Output", \ + "Switch", \ + "Timecode", \ + "Light", \ + "Antenna", \ + "UART", \ + "DCF77", \ + "Power" \ +} + + +/** + * @brief Port directions (input or output) + * + * @see ::MBG_IO_PORT_DIR_MSKS + */ +enum MBG_IO_PORT_DIRS +{ + MBG_IO_PORT_DIR_NONE = -1, ///< Only use this for ::MBG_IO_PORT_SETTINGS::direction if ::MBG_IO_PORT_SETTINGS::op_mode is ::MBG_IO_PORT_OP_MODE_NONE + MBG_IO_PORT_DIR_IN, ///< Port is input like PPS In + MBG_IO_PORT_DIR_OUT, ///< Port is output like 10Mhz + MBG_IO_PORT_DIR_IN_OUT, ///< Port can be in- & output in parallel like network port + N_MBG_IO_PORT_DIRS +}; + + +/** + * @brief Strings descriptions for ::MBG_IO_PORT_DIRS + * + * Can be used to initialize a string array of ::N_MBG_IO_PORT_DIRS entries, + * so the number of strings must correspond to ::N_MBG_IO_PORT_DIRS. + * + * @see ::MBG_IO_PORT_DIRS + */ +#define MBG_IO_PORT_DIR_STRS \ +{ \ + "Input", \ + "Output", \ + "Input/Output" \ +} + + +/** + * @brief Bit masks of Meinberg I/O port directions + * + * Used with ::MBG_IO_PORT_TYPE_INFO::supp_dirs + * + * @see ::MBG_IO_PORT_DIRS + */ +enum MBG_IO_PORT_DIR_MSKS +{ + MBG_IO_PORT_MSK_DIR_IN = ( 1UL << MBG_IO_PORT_DIR_IN ), ///< See ::MBG_IO_PORT_DIR_IN + MBG_IO_PORT_MSK_DIR_OUT = ( 1UL << MBG_IO_PORT_DIR_OUT ), ///< See ::MBG_IO_PORT_DIR_OUT + MBG_IO_PORT_MSK_DIR_IN_OUT = ( 1UL << MBG_IO_PORT_DIR_IN_OUT ) ///< See ::MBG_IO_PORT_DIR_IN_OUT +}; + + +/** + * @brief Port type sources + * + * Configurable sources for an I/O port type + * + * @see ::MBG_IO_PORT_SRC_MSKS + */ +enum MBG_IO_PORT_SRCS +{ + MBG_IO_PORT_SRC_NONE = -1, ///< Only use this for ::MBG_IO_PORT_SETTINGS::source if ::MBG_IO_PORT_SETTINGS::op_mode is ::MBG_IO_PORT_OP_MODE_NONE + MBG_IO_PORT_SRC_STATIC, ///< Static, not configurable + MBG_IO_PORT_SRC_LOCAL, ///< Locally generated, e.g. on (carrier) board + MBG_IO_PORT_SRC_ASSOC_CLOCK, ///< Fixed (wired) clock from back plane (e.g. refclock 1 in M500 IMS) + MBG_IO_PORT_SRC_ACTIVE_CLOCK, ///< Switched clock from back plane (e.g. selected by RSC) + MBG_IO_PORT_SRC_CLK1, ///< Clock 1 fixed (CPU board only) + MBG_IO_PORT_SRC_CLK2, ///< Clock 2 fixed (CPU board only) + MBG_IO_PORT_SRC_ARC, ///< Any rate converter + MBG_IO_PORT_SRC_OSC, ///< Oscillator + MBG_IO_PORT_SRC_SYNCE, ///< SyncE + MBG_IO_PORT_SRC_SWITCH_CARD, ///< Switch Card Unit fixed (SCU, RSC, ...) + MBG_IO_PORT_SRC_CONFIGURABLE, ///< configurable + MBG_IO_PORT_SRC_EXTERNAL, ///< external (e.g. for inputs) + N_MBG_IO_PORT_SRCS +}; + + +/** + * @brief Strings descriptions for ::MBG_IO_PORT_SRCS + * + * Can be used to initialize a string array of ::N_MBG_IO_PORT_SRCS entries, + * so the number of strings must correspond to ::N_MBG_IO_PORT_SRCS. + * + * @see ::MBG_IO_PORT_SRCS + */ +#define MBG_IO_PORT_SRC_STRS \ +{ \ + "Static", \ + "Locally generated", \ + "Associated clock", \ + "Active clock", \ + "Clock 1 fixed", \ + "Clock 2 fixed", \ + "Any rate converter", \ + "Oscillator", \ + "SyncE", \ + "Switch card", \ + "Configurable", \ + "External" \ +} + + +/** + * @brief Bit masks of Meinberg I/O port attitudes + * + * Used with ::MBG_IO_PORT_TYPE_INFO::supp_srcs + * + * @see ::MBG_IO_PORT_SRCS + */ +enum MBG_IO_PORT_SRC_MSKS +{ + MBG_IO_PORT_SRC_MSK_STATIC = (1UL << MBG_IO_PORT_SRC_STATIC), ///< See ::MBG_IO_PORT_SRC_STATIC + MBG_IO_PORT_SRC_MSK_LOCAL = (1UL << MBG_IO_PORT_SRC_LOCAL), ///< See ::MBG_IO_PORT_SRC_LOCAL + MBG_IO_PORT_SRC_MSK_ASSOC_CLOCK = (1UL << MBG_IO_PORT_SRC_ASSOC_CLOCK), ///< See ::MBG_IO_PORT_SRC_ASSOC_CLOCK + MBG_IO_PORT_SRC_MSK_ACTIVE_CLOCK = (1UL << MBG_IO_PORT_SRC_ACTIVE_CLOCK), ///< See ::MBG_IO_PORT_SRC_ACTIVE_CLOCK + MBG_IO_PORT_SRC_MSK_CLK1 = (1UL << MBG_IO_PORT_SRC_CLK1), ///< See ::MBG_IO_PORT_SRC_CLK1 + MBG_IO_PORT_SRC_MSK_CLK2 = (1UL << MBG_IO_PORT_SRC_CLK2), ///< See ::MBG_IO_PORT_SRC_CLK2 + MBG_IO_PORT_SRC_MSK_ARC = (1UL << MBG_IO_PORT_SRC_ARC), ///< See ::MBG_IO_PORT_SRC_ARC + MBG_IO_PORT_SRC_MSK_OSC = (1UL << MBG_IO_PORT_SRC_OSC), ///< See ::MBG_IO_PORT_SRC_OSC + MBG_IO_PORT_SRC_MSK_SYNCE = (1UL << MBG_IO_PORT_SRC_SYNCE), ///< See ::MBG_IO_PORT_SRC_SYNCE + MBG_IO_PORT_SRC_MSK_SWITCH_CARD = (1UL << MBG_IO_PORT_SRC_SWITCH_CARD), ///< See ::MBG_IO_PORT_SRC_SWITCH_CARD + MBG_IO_PORT_SRC_MSK_CONFIGURABLE = (1UL << MBG_IO_PORT_SRC_CONFIGURABLE), ///< See ::MBG_IO_PORT_SRC_CONFIGURABLE + MBG_IO_PORT_SRC_MSK_EXTERNAL = (1UL << MBG_IO_PORT_SRC_EXTERNAL) ///< See ::MBG_IO_PORT_SRC_EXTERNAL +}; + + +/** + * @brief Port connector types + * + * Used with ::MBG_IO_PORT_INFO::conn_type + * + */ +enum MBG_IO_PORT_CONN_TYPES +{ + MBG_IO_PORT_CONN_TYPE_SMA, + MBG_IO_PORT_CONN_TYPE_BNC, + MBG_IO_PORT_CONN_TYPE_DSUB25, + MBG_IO_PORT_CONN_TYPE_RJ45, + MBG_IO_PORT_CONN_TYPE_SFP, + MBG_IO_PORT_CONN_TYPE_USB_MICRO_B, + MBG_IO_PORT_CONN_TYPE_USB_A, + MBG_IO_PORT_CONN_TYPE_USB_B, + MBG_IO_PORT_CONN_TYPE_SMA_ANT, + MBG_IO_PORT_CONN_TYPE_RJ45_ETH, + MBG_IO_PORT_CONN_TYPE_2_PIN_DFK, + MBG_IO_PORT_CONN_TYPE_3_PIN_DFK, + MBG_IO_PORT_CONN_TYPE_16_PIN_DFK, + MBG_IO_PORT_CONN_TYPE_BNC_ISO, + MBG_IO_PORT_CONN_TYPE_DSUB9, + MBG_IO_PORT_CONN_TYPE_FIBRE_ST, + MBG_IO_PORT_CONN_TYPE_XHE_SPI, + MBG_IO_PORT_CONN_TYPE_LED_BUTTON, + MBG_IO_PORT_CONN_TYPE_QUAD_LED, + MBG_IO_PORT_CONN_TYPE_5_PIN_DFK, + N_MBG_IO_PORT_CONN_TYPES +}; + + +/** + * @brief Number of variable pols of the connector type, see ::MBG_IO_PORT_INFO::pols + * + * Used with ::MBG_IO_PORT_INFO::conn_type and ::MBG_IO_PORT_INFO::pols + * + */ +#define MBG_IO_PORT_CONN_TYPE_VAR_POLS \ +{ \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 16, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 4, \ + 1 \ +} + + +/** + * @brief Strings descriptions for ::MBG_IO_PORT_CONN_TYPES + * + * Can be used to initialize a string array of ::N_MBG_IO_PORT_CONN_TYPES entries, + * so the number of strings must correspond to ::N_MBG_IO_PORT_CONN_TYPES. + * + * @see ::MBG_IO_PORT_CONN_TYPES + */ +#define MBG_IO_PORT_CONN_TYPE_STRS \ +{ \ + "SMA", \ + "BNC", \ + "D-Sub 25", \ + "RJ45", \ + "SFP", \ + "USB Micro B", \ + "USB A", \ + "USB B", \ + "SMA Antenna", \ + "RJ45 Ethernet", \ + "DFK 2-Pin", \ + "DFK 3-Pin", \ + "DFK 16-Pin", \ + "BNC isolated", \ + "D-Sub 9", \ + "Fibre ST", \ + "XHE SPI", \ + "LED Button", \ + "Quad LED", \ + "DFK 5-Pin" \ +} + + +enum MBG_IO_PORT_FLAGS +{ + MBG_IO_PORT_FLAG_HORIZONTAL_LAYOUT, ///< Modules (rows and columns) are layouted horizontally + MBG_IO_PORT_FLAG_FRONT_PORTS, ///< Device has ports at the front side + MBG_IO_PORT_FLAG_REAR_PORTS, ///< Device has ports at the rear side + MBG_IO_PORT_FLAG_NO_LABEL, ///< Device does not have a label + MBG_IO_PORT_FLAG_NO_GRASP, ///< Device does not have a grasp + N_MBG_IO_PORT_FLAGS +}; + + +enum MBG_IO_PORT_MSKS +{ + MBG_IO_PORT_MSK_HORIZONTAL_LAYOUT = ( 1UL << MBG_IO_PORT_FLAG_HORIZONTAL_LAYOUT ), ///< See ::MBG_IO_PORT_FLAG_HORIZONTAL_LAYOUT + MBG_IO_PORT_MSK_FRONT_PORTS = ( 1UL << MBG_IO_PORT_FLAG_FRONT_PORTS ), ///< See ::MBG_IO_PORT_FLAG_FRONT_PORTS + MBG_IO_PORT_MSK_REAR_PORTS = ( 1UL << MBG_IO_PORT_FLAG_REAR_PORTS ), ///< See ::MBG_IO_PORT_FLAG_REAR_PORTS + MBG_IO_PORT_MSK_NO_LABEL = ( 1UL << MBG_IO_PORT_FLAG_NO_LABEL ), ///< See ::MBG_IO_PORT_FLAG_REAR_PORTS + MBG_IO_PORT_MSK_NO_GRASP = ( 1UL << MBG_IO_PORT_FLAG_NO_GRASP ) ///< See ::MBG_IO_PORT_FLAG_NO_GRASP +}; + + +enum MBG_IO_PORT_BG_COLOURS +{ + MBG_IO_PORT_BG_COLOUR_SILVER, + MBG_IO_PORT_BG_COLOUR_BLACK, + MBG_IO_PORT_BG_COLOUR_BLUE, + N_MBG_IO_PORT_BG_COLOURS +}; + + +#define MBG_IO_PORT_BG_COLOUR_STRS \ +{ \ + "Silver", \ + "Black", \ + "Blue" \ +} + + +/** + * @brief Enumeration of known signal shapes/levels + * + * Used to specify the signal shape/level of an I/O port. + * + * @see ::MBG_IO_PORT_SHAPE_LEVEL_STRS + */ +enum MBG_IO_PORT_SHAPE_LEVELS +{ + MBG_IO_PORT_SHAPE_LEVEL_NONE, ///< Unknown or unspecified signal shape. + ///< Must be zero for backward compatibility. + MBG_IO_PORT_SHAPE_LEVEL_SINE, ///< Sine wave + MBG_IO_PORT_SHAPE_LEVEL_SQUARE, ///< Square wave + N_MBG_IO_PORT_SHAPE_LEVELS ///< Number of known signal shapes +}; + + +/** + * @brief String initializers for I/O port shapes/levels + * + * @see ::MBG_IO_PORT_SHAPE_LEVELS + */ +#define MBG_IO_PORT_SHAPE_LEVEL_STRS \ +{ \ + "None", \ + "Sine wave", \ + "Rectangle Pulse" \ +} + + +/** + * @brief IO Port Limits + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_INFO + * @see ::MBG_IO_PORT_INFO_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + */ +typedef struct +{ + uint8_t num_ports; + uint8_t num_cols; ///< Number of port columns this device supports + uint8_t num_rows; ///< Number of port rows this device supports + uint8_t bg_colour; ///< Background colour of the IO ports, see ::MBG_IO_PORT_BG_COLOURS + + uint32_t reserved; ///< Reserved, currently 0 + uint32_t flags; ///< See ::MBG_IO_PORT_MSKS + + uint8_t label_col; ///< Column position of the device label, consider ::MBG_IO_PORT_MSK_NO_LABEL + uint8_t label_row; ///< Row position of the device label, consider ::MBG_IO_PORT_MSK_NO_LABEL + uint8_t grasp_col; ///< Column position of the device grasp, consider ::MBG_IO_PORT_MSK_NO_GRASP + uint8_t grasp_row; ///< Row position of the device grasp, consider ::MBG_IO_PORT_MSK_NO_GRASP + + uint8_t label_rear; ///< Indicates, that the label is on the rear side + uint8_t grasp_rear; ///< Indicates, that the grasp is on the rear side + uint16_t reserved_2; ///< Reserved, currently 0 + + uint32_t reserved_3[7]; ///< Reserved, currently 0 + +} MBG_IO_PORT_LIMITS; + +#define _mbg_swab_io_port_limits( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Port Operation Bits + * + * Used with ::MBG_IO_PORT_SETTINGS::op_mode + * + * For now, there is a per port operation mode setting which + * is quite equal to ::ENABLE_FLAGS. + * + * @see ::MBG_IO_PORT_OP_MODE_MSKS + */ +enum MBG_IO_PORT_OP_MODE_BITS +{ + MBG_IO_PORT_OP_MODE_NONE = -1, ///< Current mode cannot be determined + MBG_IO_PORT_OP_MODE_DISABLED, ///< Disabled port + MBG_IO_PORT_OP_MODE_ALWAYS, ///< Always enable port + MBG_IO_PORT_OP_MODE_IF_SYNC_ONLY, ///< Enable port if sync only + MBG_IO_PORT_OP_MODE_AFTER_SYNC, ///< Always enable port after being sync once + MBG_IO_PORT_OP_MODE_ENABLED, ///< Enabled + MBG_IO_PORT_OP_MODE_PASSTHROUGH, ///< Forwarded signals from backplane (e.g. PPS of BPE) + N_MBG_IO_PORT_OP_MODE_BITS +}; + + +/** + * @brief Strings descriptions for ::MBG_IO_PORT_OP_MODE_BITS + * + * Can be used to initialize a string array of ::N_MBG_IO_PORT_OP_MODE_BITS entries, + * so the number of strings must correspond to ::N_MBG_IO_PORT_OP_MODE_BITS. + * + * @see ::MBG_IO_PORT_OP_MODE_BITS + */ +#define MBG_IO_PORT_OP_MODE_STRS \ +{ \ + "Disabled", \ + "Always enabled", \ + "If sync only", \ + "Always after sync", \ + "Enabled", \ + "Passed through" \ +} + + + +/** + * @brief Masks for ::MBG_IO_PORT_OP_MODE_BITS + * + * Used with ::MBG_IO_PORT_INFO::supp_op_modes + * + * @see ::MBG_IO_PORT_OP_MODE_BITS + */ +enum MBG_IO_PORT_OP_MODE_MSKS +{ + MBG_IO_PORT_OP_MODE_MSK_DISABLED = (1UL << MBG_IO_PORT_OP_MODE_DISABLED), ///< See ::MBG_IO_PORT_OP_MODE_DISABLED + MBG_IO_PORT_OP_MODE_MSK_ALWAYS = (1UL << MBG_IO_PORT_OP_MODE_ALWAYS), ///< See ::MBG_IO_PORT_OP_MODE_ALWAYS + MBG_IO_PORT_OP_MODE_MSK_IF_SYNC_ONLY = (1UL << MBG_IO_PORT_OP_MODE_IF_SYNC_ONLY), ///< See ::MBG_IO_PORT_OP_MODE_IF_SYNC_ONLY + MBG_IO_PORT_OP_MODE_MSK_AFTER_SYNC = (1UL << MBG_IO_PORT_OP_MODE_AFTER_SYNC), ///< See ::MBG_IO_PORT_OP_MODE_AFTER_SYNC + MBG_IO_PORT_OP_MODE_MSK_ENABLED = (1UL << MBG_IO_PORT_OP_MODE_ENABLED), ///< See ::MBG_IO_PORT_OP_MODE_ENABLED + MBG_IO_PORT_OP_MODE_MSK_PASSTHROUGH = (1UL << MBG_IO_PORT_OP_MODE_PASSTHROUGH) ///< See ::MBG_IO_PORT_OP_MODE_PASSTHROUGH +}; + + +/** + * @brief Physical or logical group role bits + * + * Used with ::MBG_IO_PORT_STATUS::phys_grp_role, ::MBG_IO_PORT_STATUS::log_grp_role + * + * @see ::MBG_IO_PORT_GRP_ROLE_MSKS + */ +enum MBG_IO_PORT_GRP_ROLE_BITS +{ + MBG_IO_PORT_GRP_ROLE_NONE, ///< No group role, only possible if port is not assigned to any group + MBG_IO_PORT_GRP_ROLE_MASTER, ///< Master port in group, i.e. configurable port of LIU + MBG_IO_PORT_GRP_ROLE_SLAVE, ///< Slave port in group, i.e. non-configurable port of LIU + MBG_IO_PORT_GRP_ROLE_PASSIVE, ///< Passive port in group, i.e. passive port of network group (i.e. SFP or RJ45) + N_MBG_IO_PORT_GRP_ROLE_BITS +}; + + +/** + * @brief Strings descriptions for ::MBG_IO_PORT_GRP_ROLE_BITS + * + * Can be used to initialize a string array of ::N_MBG_IO_PORT_GRP_ROLE_BITS entries, + * so the number of strings must correspond to ::N_MBG_IO_PORT_GRP_ROLE_BITS. + * + * @see ::MBG_IO_PORT_GRP_ROLE_BITS + */ +#define MBG_IO_PORT_GRP_ROLE_STRS \ +{ \ + "None", \ + "Master", \ + "Slave", \ + "Passive" \ +} + + +/** + * @brief Masks for ::MBG_IO_PORT_GRP_ROLE_BITS + * + * Used with ::MBG_IO_PORT_INFO::supp_phys_grp_roles + * + * @see ::MBG_IO_PORT_GRP_ROLE_BITS + */ +enum MBG_IO_PORT_GRP_ROLE_MSKS +{ + MBG_IO_PORT_GRP_ROLE_MSK_NONE = (1UL << MBG_IO_PORT_GRP_ROLE_NONE), ///< See ::MBG_IO_PORT_GRP_ROLE_NONE + MBG_IO_PORT_GRP_ROLE_MSK_MASTER = (1UL << MBG_IO_PORT_GRP_ROLE_MASTER), ///< See ::MBG_IO_PORT_GRP_ROLE_MASTER + MBG_IO_PORT_GRP_ROLE_MSK_SLAVE = (1UL << MBG_IO_PORT_GRP_ROLE_SLAVE), ///< See ::MBG_IO_PORT_GRP_ROLE_SLAVE + MBG_IO_PORT_GRP_ROLE_MSK_PASSIVE = (1UL << MBG_IO_PORT_GRP_ROLE_PASSIVE) ///< See ::MBG_IO_PORT_GRP_ROLE_PASSIVE +}; + + +/** + * @brief Supported members in ::MBG_IO_PORT_ANTENNA_INFO and ::MBG_IO_PORT_ANTENNA_SETTINGS + * + * Used with ::MBG_IO_PORT_ANTENNA_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, + 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 +}; + + +typedef struct +{ + uint32_t supp_members; + MBG_GNSS_MODE_INFO gnss_info; + +} MBG_IO_PORT_ANT_INFO; + +#define _mbg_swab_io_port_ant_info( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_members ); \ + _mbg_swab_mbg_gnss_mode_info( &(_p)->gnss_info ); \ +} while ( 0 ) + +typedef struct +{ + MBG_GNSS_MODE_SETTINGS gnss_settings; + ANT_CABLE_LEN ant_cab_len; + IGNORE_LOCK ignore_lock; + /* Do not include pcpsdefs.h -> Use the non-typedefed type */ + uint16_t tr_dist; + +} MBG_IO_PORT_ANT_SETTINGS; + +#define _mbg_swab_io_port_ant_settings( _p ) \ +do \ +{ \ + _mbg_swab_mbg_gnss_mode_settings( &(_p)->gnss_settings ); \ + _mbg_swab_ant_cable_len( &(_p)->ant_cab_len ); \ + _mbg_swab16( &(_p)->ignore_lock ); \ + _mbg_swab16( &(_p)->tr_dist ); \ +} while ( 0 ) + + +/** + * @brief IO Port Settings Union + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_INFO + * @see ::MBG_IO_PORT_INFO_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + */ +typedef union +{ + MBG_GPIO_SETTINGS gpio_settings; + POUT_SETTINGS pout_settings; + IRIG_SETTINGS irig_settings; + MBG_IO_PORT_ANT_SETTINGS ant_settings; + PORT_SETTINGS uart_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; \ + } \ +} while ( 0 ) + + +#define MBG_IO_PORT_SETTINGS_MIN_SIZE 32 + + +/** + * @brief IO Port Settings + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_INFO + * @see ::MBG_IO_PORT_INFO_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + */ +typedef struct +{ + uint16_t port_type; ///< ::MBG_IO_PORT_TYPES + uint8_t direction; ///< ::MBG_IO_PORT_DIRS + uint8_t source; ///< ::MBG_IO_PORT_SRCS + uint8_t op_mode; ///< ::MBG_IO_PORT_OP_MODE_BITS + uint8_t pt_idx; ///< index of the port types (e.g. 0 for PPO0, 1 for PPO1, ...) + uint8_t reserved_1[2]; ///< Future use and padding, currently 0 + uint32_t reserved_2[6]; ///< Future use and padding, currently 0 + + /* + * Struct members above represent minimum amount of data to be sent. + * See ::MBG_IO_PORT_SETTINGS_MIN_SIZE + */ + + MBG_IO_PORT_SETTINGS_U data; ///< Data union for settings' type + +} MBG_IO_PORT_SETTINGS; + +#define _mbg_swab_io_port_settings( _p, _recv ) \ +do \ +{ \ + uint16_t t = (_p)->port_type; \ + if ( (_recv) ) \ + _mbg_swab16( &t ); \ + _mbg_swab16( &(_p)->port_type ); \ + _mbg_swab_io_port_settings_u( t, &(_p)->data, (_recv) ); \ +} while ( 0 ) + + + + +/** + * @brief IO Port Settings Index + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_INFO + * @see ::MBG_IO_PORT_INFO_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + * + * Indexes from 0..::MBG_IO_PORT_LIMITS::num_ports - 1 are used + * to set ::MBG_IO_PORT_SETTINGS wrapped in ::MBG_IO_PORT_SETTINGS_IDX. + */ +typedef struct +{ + uint32_t idx; + MBG_IO_PORT_SETTINGS settings; + +} MBG_IO_PORT_SETTINGS_IDX; + +#define _mbg_swab_io_port_settings_idx( _p, _recv ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_io_port_settings( &(_p)->settings, (_recv) ); \ +} while ( 0 ) + + +#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 */ \ +} + + +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 +}; + + +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 +}; + + +#define MBG_NO_PHYS_GROUP 0xFF +#define MBG_NO_LOG_GROUP 0xFF +#define MBG_IO_PORT_STR_SIZE 16 + +/** + * @brief IO Port Info + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_INFO_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + */ +typedef struct +{ + uint8_t num_types; ///< See ::MBG_IO_PORT_TYPE_INFO + uint8_t conn_type; ///< See ::MBG_IO_PORT_CONN_TYPES + uint8_t reserved_1; ///< Future use and padding, currently 0 + uint8_t align_rule_idx; ///< Index of the ::MBG_IO_PORT_INFO_IDX this port shall be optically aligned to + uint16_t supp_op_modes; ///< See ::MBG_IO_PORT_OP_MODE_MSKS + uint16_t supp_phys_grp_roles; ///< Supported roles in ::MBG_IO_PORT_STATUS::phys_grp_role, see ::MBG_IO_PORT_GRP_ROLE_MSKS + uint8_t phys_grp; ///< Physical group number (i.e. SFP/RJ45 on HPS100), or ::MBG_NO_PHYS_GROUP + 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 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" + char rel_str[MBG_IO_PORT_STR_SIZE]; ///< Internally used relation string, i.e. "lan0", "fpga0" or "/dev/ttyS0" + MBG_IO_PORT_SETTINGS settings; ///< See ::MBG_IO_PORT_SETTINGS + +} MBG_IO_PORT_INFO; + +#define _mbg_port_has_phys_group( _p ) ( ( _p )->phys_grp != MBG_NO_PHYS_GROUP ) + +#define _mbg_swab_io_port_info( _p, _recv ) \ +do \ +{ \ + _mbg_swab16( &(_p)->supp_op_modes ); \ + _mbg_swab16( &(_p)->supp_phys_grp_roles ); \ + _mbg_swab32( &(_p)->pols ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab_io_port_settings( &(_p)->settings, (_recv) ); \ +} while ( 0 ) + + + +#define MBG_IO_PORT_INFO_MIN_SIZE ( 60 + MBG_IO_PORT_SETTINGS_MIN_SIZE ) + + +/** + * @brief IO Port Info Index + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_U + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + * + * Indexes from 0..::MBG_IO_PORT_LIMITS::num_ports - 1 are used + * to query ::MBG_IO_PORT_INFO wrapped in ::MBG_IO_PORT_INFO_IDX. + */ +typedef struct +{ + uint32_t idx; + MBG_IO_PORT_INFO info; + +} MBG_IO_PORT_INFO_IDX; + +#define _mbg_swab_io_port_info_idx( _p, _recv ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_io_port_info( &(_p)->info, (_recv) ); \ +} while ( 0 ) + + + +#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 */ \ +} + + +/** + * @brief IO Port Type Info Union + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_INFO + * @see ::MBG_IO_PORT_INFO_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + */ +typedef union +{ + MBG_GPIO_LIMITS gpio_limits; + POUT_INFO pout_info; + IRIG_INFO irig_info; + PORT_INFO uart_info; + MBG_IO_PORT_ANT_INFO ant_info; + +} MBG_IO_PORT_TYPE_INFO_U; + +#define _mbg_swab_io_port_type_info_u( _type, _p, _recv ) \ +do \ +{ \ + switch ( (_type) ) \ + { \ + case MBG_IO_PORT_TYPE_GPIO: \ + _mbg_swab_mbg_gpio_limits( &(_p)->gpio_limits, (_recv) ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_POUT: \ + _mbg_swab_pout_info_on_get( &(_p)->pout_info ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_TIMECODE: \ + _mbg_swab_irig_info( &(_p)->irig_info ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_ANTENNA: \ + _mbg_swab_io_port_ant_info( &(_p)->ant_info ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_UART: \ + _mbg_swab_port_info( &(_p)->uart_info ); \ + break; \ + \ + default: break; \ + } \ +} while ( 0 ) + + + +#define MBG_IO_PORT_TYPE_INFO_MIN_SIZE 32 + + +/** + * @brief IO Port Type Info + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_INFO_IDX + * @see ::MBG_IO_PORT_TYPE_INFO_U + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + */ +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 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 + uint32_t reserved_3[5]; ///< Future use and padding, currently 0 + + /* + * Struct members above represent minimum amount of data to be sent. + * See ::MBG_IO_PORT_TYPE_INFO_MIN_SIZE + */ + + MBG_IO_PORT_TYPE_INFO_U data; ///< Port type specific data + +} MBG_IO_PORT_TYPE_INFO; + +#define _mbg_swab_io_port_type_info( _p, _recv ) \ +do \ +{ \ + uint16_t t = (_p)->port_type; \ + if ( (_recv) ) \ + _mbg_swab16( &t ); \ + _mbg_swab16( &(_p)->port_type ); \ + _mbg_swab_io_port_type_info_u( t, &(_p)->data, (_recv) ); \ + _mbg_swab32( &(_p)->supp_srcs ); \ +} while ( 0 ) + + +#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 */ \ +} + + +/** + * @brief IO Port Type Info Index + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_U + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + * + * Indexes from 0..::MBG_IO_PORT_INFO::num_types - 1 are used + * to query ::MBG_IO_PORT_TYPE_INFO wrapped in ::MBG_IO_PORT_TYPE_INFO_IDX. + * + */ +typedef struct +{ + uint32_t port_idx; + uint32_t port_type_idx; + MBG_IO_PORT_TYPE_INFO info; + +} MBG_IO_PORT_TYPE_INFO_IDX; + +#define _mbg_swab_io_port_type_info_idx( _p, _recv ) \ +do \ +{ \ + _mbg_swab32( &(_p)->port_idx ); \ + _mbg_swab32( &(_p)->port_type_idx ); \ + _mbg_swab_io_port_type_info( &(_p)->info, (_recv) ); \ +} while ( 0 ) + + + +#define MAX_IO_PORT_STATUS_BITS 64 + + +/** + * @brief Port Type 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_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 + MBG_IO_PORT_STATUS_BIT_SHORT_CIRCUIT, ///< Short circuit + MBG_IO_PORT_STATUS_BIT_LIGHT_RED, ///< LED shows red light + 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 + N_MBG_IO_PORT_STATUS_BITS +}; + + +/** + * @brief Strings descriptions for ::MBG_IO_PORT_STATUS_BITS + * + * Can be used to initialize a string array of ::N_MBG_IO_PORT_STATUS_BITS entries, + * so the number of strings must correspond to ::N_MBG_IO_PORT_STATUS_BITS. + * + * @see ::MBG_IO_PORT_STATUS_BITS + */ +#define MBG_IO_PORT_STATUS_STRS \ +{ \ + "Disabled", \ + "Carrier detected", \ + "Input signal has never been avail", \ + "Input signal is avail", \ + "Input signal is currently lost", \ + "Short circuit", \ + "Red", \ + "Green", \ + "Blue", \ + "Yellow" \ +} + + +/** + * @brief Array size required to store all status bits + * + * The number of bytes required to store up to ::MAX_IO_PORT_STATUS_BITS + * feature bits in a byte array. + */ +#define MAX_IO_PORT_STATUS_BYTES ( MAX_IO_PORT_STATUS_BITS / 8 ) + + +/** + * @brief A structure used to store port status bits + * + * Up to ::MAX_IO_PORT_STATUS_BITS totally can be stored, but only + * ::N_MBG_IO_PORT_STATUS_BITS are currently defined. + * + * The ::_set_io_port_status_bit macro should be used by the firmware + * to set a status bit in the buffer, and the ::check_feat_supp_byte_array + * to check if a bit is set + * + * @see ::_set_io_port_status_bit + * @see ::check_feat_supp_byte_array + */ +typedef struct +{ + uint8_t b[MAX_IO_PORT_STATUS_BYTES]; + +} MBG_IO_PORT_STATUS_BUFFER; + +#define _mbg_swab_io_port_status_buffer( _p ) \ + _nop_macro_fnc() + + + +/** + * @brief Set an port status bit in a ::MBG_IO_PORT_STATUS_BUFFER + * + * Should be used by the firmware only to set one of the ::N_MBG_IO_PORT_STATUS_BITS + * in an ::MBG_IO_PORT_STATUS_BUFFER after power-up. + * + * @param[in] _status_bit One of the ::MBG_IO_PORT_STATUS_BITS + * @param[in] _status_buffp Pointer to an ::MBG_IO_PORT_STATUS_BUFFER + */ +#define _set_io_port_status_bit( _status_bit, _status_buffp ) \ + _set_array_bit( _status_bit, (_status_buffp)->b, MAX_IO_PORT_STATUS_BYTES ) + + +/** + * @brief Clear a port status bit in a ::MBG_IO_PORT_STATUS_BUFFER + * + * Should be used by the firmware only to set one of the ::N_MBG_IO_PORT_STATUS_BITS + * in an ::MBG_IO_PORT_STATUS_BUFFER after power-up. + * + * @param[in] _status_bit One of the ::MBG_IO_PORT_STATUS_BITS + * @param[in] _status_buffp Pointer to an ::MBG_IO_PORT_STATUS_BUFFER + */ +#define _clear_io_port_status_bit( _status_bit, _status_buffp ) \ + _clear_array_bit( _status_bit, (_status_buffp)->b, MAX_IO_PORT_STATUS_BYTES ) + + +/** + * @brief IO Port Type Status + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_U + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS_IDX + * + */ +typedef struct +{ + MBG_IO_PORT_STATUS_BUFFER supp_stati; ///< Supported ::MBG_IO_PORT_STATUS_BITS in ::MBG_IO_PORT_STATUS_BUFFER + MBG_IO_PORT_STATUS_BUFFER status; ///< See ::MBG_IO_PORT_STATUS_BUFFER + + uint8_t reserved; ///< Future use + uint8_t phys_grp_role; ///< Physical group role state, see ::MBG_IO_PORT_GRP_ROLE_BITS + uint8_t log_grp; ///< Logical group number (i.e. bond0), or ::MBG_NO_LOG_GROUP + uint8_t log_grp_role; ///< Logical group role (i.e. bond master, bond slave), see ::MBG_IO_PORT_GRP_ROLE_BITS + + uint32_t reserved_2[4]; ///< Future use, currently 0 + +} MBG_IO_PORT_STATUS; + +#define _mbg_port_has_log_group( _p ) ( ( _p )->log_grp != MBG_NO_LOG_GROUP ) + +#define _mbg_swab_io_port_status( _p ) \ +do \ +{ \ + _mbg_swab_io_port_status_buffer( &(_p)->supp_stati ); \ + _mbg_swab_io_port_status_buffer( &(_p)->status ); \ +} while ( 0 ) + + + +/** + * @brief IO Port Type Status + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_U + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * + * Indexes from 0..::MBG_IO_PORT_INFO::num_types - 1 are used + * to query ::MBG_IO_PORT_TYPE_INFO wrapped in ::MBG_IO_PORT_TYPE_INFO_IDX. + * + */ +typedef struct +{ + uint32_t idx; + MBG_IO_PORT_STATUS status; + +} MBG_IO_PORT_STATUS_IDX; + +#define _mbg_swab_io_port_status_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_io_port_status( &(_p)->status ); \ +} while ( 0 ) + + +/** @} defgroup group_io_ports */ + + + +/** + * @defgroup group_monitoring Monitoring / notification + * + * @note This structure and its definitions are only supported by a device + * if ::MBG_XFEATURE_MONITORING is set in the extended device features. + * + * TODO: Add proper Doxygen documentation + * + * @{ */ + + +#define MBG_MONITORING_STR_SIZE 32 + +enum MBG_MONITORING_TYPES +{ + MBG_MONITORING_TYPE_SNMP, + MBG_MONITORING_TYPE_EMAIL, + MBG_MONITORING_TYPE_SYSLOG, + N_MBG_MONITORING_TYPES +}; + +#define MBG_MONITORING_TYPE_STRS \ +{ \ + "SNMP", \ + "Email", \ + "Syslog" \ +} + +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) +}; + + + +typedef struct +{ + uint16_t supp_types; ///< See ::MBG_MONITORING_TYPE_MSKS + uint16_t supp_num_events; ///< Supported number of events. See ::MBG_EVENT_TYPES + uint32_t reserved_2[3]; + +} MBG_MONITORING_LIMITS; + +#define _mbg_swab_monitoring_limits( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->supp_types ); \ + _mbg_swab16( &(_p)->supp_num_events ); \ +} while ( 0 ) + + + +/* If ::MBG_MONITORING_TYPE_MSK_SNMP is set in ::MBG_MONITORING_LIMITS::supp_types */ + +enum MBG_SNMP_VERSIONS +{ + MBG_SNMP_VERSION_V1, + MBG_SNMP_VERSION_V2c, + MBG_SNMP_VERSION_V3, + N_MBG_SNMP_VERSIONS +}; + +#define MBG_SNMP_VERSION_STRS \ +{ \ + "Version 1", \ + "Version 2c", \ + "Version 3" \ +} + +enum MBG_SNMP_VERSION_MSKS +{ + MBG_SNMP_VERSION_MSK_V1 = (1UL << MBG_SNMP_VERSION_V1), + MBG_SNMP_VERSION_MSK_V2c = (1UL << MBG_SNMP_VERSION_V2c), + MBG_SNMP_VERSION_MSK_V3 = (1UL << MBG_SNMP_VERSION_V3) +}; + + +enum MBG_SNMP_FLAGS +{ + MBG_SNMP_SYSTEM_USER, + MBG_SNMP_ADD_CONF, ///< Supports additional SNMP configuration (i.e. via script) + N_MBG_SNMP_FLAGS +}; + + +#define MBG_SNMP_FLAG_STRS \ +{ \ + "System user", \ + "Additional config" \ +} + + +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 +}; + + +#define SNMP_DEF_ADD_CONF_PATH "/etc/mbg" +#define SNMP_DEF_ADD_CONF_FILENAME "snmp.conf.add" +#define SNMP_DEF_ADD_CONF_FILE SNMP_DEF_ADD_CONF_PATH "/" SNMP_DEF_ADD_CONF_FILENAME + + + +typedef struct +{ + uint8_t num_v12_settings; ///< Number of configured v1/v2 settings, see ::MBG_SNMP_V12_INFO_IDX + uint8_t num_v3_settings; ///< Number of configured v1/v2 trap receivers, see ::MBG_SNMP_V12_TRAP_INFO_IDX + uint8_t num_v12_trap_receivers; ///< Number of configured v3 settings, see ::MBG_SNMP_V3_INFO_IDX + uint8_t num_v3_trap_receivers; ///< Number of configured v3 trap receivers, see ::MBG_SNMP_V3_TRAP_INFO_IDX + uint16_t listening_port; ///< snmpd listening port, 161 by default + uint16_t reserved_1; + uint32_t reserved_2[3]; + char location[MBG_MONITORING_STR_SIZE]; + char contact[MBG_MONITORING_STR_SIZE]; + char name[MBG_MONITORING_STR_SIZE]; + char description[MBG_MONITORING_STR_SIZE]; + char reserved_3[MBG_MONITORING_STR_SIZE]; ///< Future use + char reserved_4[MBG_MONITORING_STR_SIZE]; ///< Future use + +} MBG_SNMP_GLB_SETTINGS; + +#define _mbg_swab_snmp_glb_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->listening_port ); \ +} while ( 0 ) + + + +typedef struct +{ + MBG_SNMP_GLB_SETTINGS settings; + uint8_t supp_versions; ///< See ::MBG_SNMP_VERSION_MSKS + uint8_t max_v12_settings; ///< 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_settings; ///< Only valid if ::MBG_SNMP_GLB_INFO::supp_versions contains ::MBG_SNMP_VERSION_MSK_V3 + 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 + uint32_t reserved_2[2]; + +} MBG_SNMP_GLB_INFO; + +#define _mbg_swab_snmp_glb_info( _p ) \ +do \ +{ \ + _mbg_swab_snmp_glb_settings( &(_p)->settings ); \ + _mbg_swab16( &(_p)->supp_flags ); \ +} while ( 0 ) + + + +enum MBG_SNMP_ACCESS_TYPES +{ + MBG_SNMP_ACCESS_TYPE_RO, + MBG_SNMP_ACCESS_TYPE_RW, + N_MBG_SNMP_ACCESS_TYPES +}; + + +#define MBG_SNMP_ACCESS_TYPE_STRS \ +{ \ + "Read-only", \ + "Read-write" \ +} + + + +typedef struct +{ + uint8_t version; ///< See ::MBG_SNMP_VERSIONS + uint8_t access_type; ///< See ::MBG_SNMP_ACCESS_TYPES, ignore in trap settings + uint8_t reserved_1[2]; + uint32_t reserved_2[3]; + char community[MBG_MONITORING_STR_SIZE]; + +} MBG_SNMP_V12_SETTINGS; + +#define _mbg_swab_snmp_v12_settings( _p ) \ +do \ +{ \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t idx; + MBG_SNMP_V12_SETTINGS settings; + +} MBG_SNMP_V12_SETTINGS_IDX; + +#define _mbg_swab_snmp_v12_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v12_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct +{ + MBG_SNMP_V12_SETTINGS settings; + uint32_t reserved_1[4]; + +} MBG_SNMP_V12_INFO; + +#define _mbg_swab_snmp_v12_info( _p ) \ +do \ +{ \ + _mbg_swab_snmp_v12_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t idx; + MBG_SNMP_V12_INFO info; + +} MBG_SNMP_V12_INFO_IDX; + +#define _mbg_swab_snmp_v12_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v12_info( &(_p)->info ); \ +} while ( 0 ) + + + +typedef struct +{ + uint8_t timeout; ///< In seconds + uint8_t retries; + uint16_t reserved_1; + uint32_t reserved_2[3]; + char reserved_3[MBG_MONITORING_STR_SIZE]; ///< Future use + char reserved_4[MBG_MONITORING_STR_SIZE]; ///< Future use + MBG_SNMP_V12_SETTINGS v12_settings; + MBG_HOSTNAME receiver_addr; + uint16_t dest_port; ///< receiver destination port, 162 by default + uint16_t reserved_5; + +} MBG_SNMP_V12_TRAP_SETTINGS; + +#define _mbg_swab_snmp_v12_trap_settings( _p ) \ +do \ +{ \ + _mbg_swab_snmp_v12_settings( &(_p)->v12_settings ); \ + _mbg_swab16( &(_p)->dest_port ); \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t idx; + MBG_SNMP_V12_TRAP_SETTINGS settings; + +} MBG_SNMP_V12_TRAP_SETTINGS_IDX; + +#define _mbg_swab_snmp_v12_trap_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v12_trap_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct +{ + MBG_SNMP_V12_TRAP_SETTINGS settings; + uint32_t reserved_1[4]; + +} MBG_SNMP_V12_TRAP_INFO; + +#define _mbg_swab_snmp_v12_trap_info( _p ) \ +do \ +{ \ + _mbg_swab_snmp_v12_trap_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t idx; + MBG_SNMP_V12_TRAP_INFO info; + +} MBG_SNMP_V12_TRAP_INFO_IDX; + +#define _mbg_swab_snmp_v12_trap_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v12_trap_info( &(_p)->info ); \ +} while ( 0 ) + + + +enum MBG_SNMP_V3_SEC_LEVELS +{ + MBG_SNMP_V3_SEC_LEVEL_NO_AUTH_NO_PRIV, + MBG_SNMP_V3_SEC_LEVEL_AUTH_NO_PRIV, + MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV, + N_MBG_SNMP_V3_SEC_LEVELS +}; + +#define MBG_SNMP_V3_SEC_LEVEL_STRS \ +{ \ + "No auth no priv", \ + "Auth no priv", \ + "Auth priv" \ +} + + +enum MBG_SNMP_V3_AUTH_PROTOCOLS +{ + MBG_SNMP_V3_AUTH_PROTOCOL_NONE, + MBG_SNMP_V3_AUTH_PROTOCOL_MD5, + MBG_SNMP_V3_AUTH_PROTOCOL_SHA, + N_MBG_SNMP_V3_AUTH_PROTOCOLS +}; + +#define MBG_SNMP_V3_AUTH_PROTOCOL_STRS \ +{ \ + "None", \ + "MD5", \ + "SHA" \ +} + + +enum MBG_SNMP_V3_PRIV_PROTOCOLS +{ + MBG_SNMP_V3_PRIV_PROTOCOL_NONE, + MBG_SNMP_V3_PRIV_PROTOCOL_DES, + MBG_SNMP_V3_PRIV_PROTOCOL_AES, + N_MBG_SNMP_V3_PRIV_PROTOCOLS +}; + + +#define MBG_SNMP_V3_PRIV_PROTOCOL_STRS \ +{ \ + "None", \ + "DES", \ + "AES" \ +} + + + +typedef struct +{ + uint8_t access_type; ///< See ::MBG_SNMP_ACCESS_TYPES, ignore in trap settings + uint8_t sec_level; ///< See ::MBG_SNMP_V3_SEC_LEVELS + uint8_t auth_protocol; ///< See ::MBG_SNMP_V3_AUTH_PROTOCOLS if ::MBG_SNMP_V3_SETTINGS::sec_level + ///< is ::MBG_SNMP_V3_SEC_LEVEL_AUTH_NO_PRIV or ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV + uint8_t priv_protocol; ///< See ::MBG_SNMP_V3_PRIV_PROTOCOLS if ::MBG_SNMP_V3_SETTINGS::sec_level + ///< is ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV + uint16_t flags; ///< See ::MBG_SNMP_FLAG_MSKS + uint16_t reserved_0; + uint32_t reserved_1[3]; + char user_name[MBG_MONITORING_STR_SIZE]; ///< User name used for authentication, always required. + char auth_passwd[MBG_MONITORING_STR_SIZE]; ///< Password associated with ::MBG_SNMP_V3_SETTINGS::user_name, if ::MBG_SNMP_V3_SETTINGS::auth_protocol + ///< is ::MBG_SNMP_V3_SEC_LEVEL_AUTH_NO_PRIV or ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV + char sec_engine_id[MBG_MONITORING_STR_SIZE]; ///< Mandatory for traps only + char context_engine_id[MBG_MONITORING_STR_SIZE]; ///< Ignore + char context_name[MBG_MONITORING_STR_SIZE]; ///< Ignore + char reserved_2[MBG_MONITORING_STR_SIZE]; ///< Future use + char reserved_3[MBG_MONITORING_STR_SIZE]; ///< Future use + char priv_passwd[MBG_MONITORING_STR_SIZE]; ///< Encryption passwd if ::MBG_SNMP_V3_SETTINGS::auth_protocol is ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV + uint32_t boots; ///< Number of system/deamon restarts -> Ignore + uint32_t time; ///< Timeticks since last "boots" event -> Ignore + uint32_t reserved_4[2]; + +} MBG_SNMP_V3_SETTINGS; + +#define _mbg_swab_snmp_v3_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->boots ); \ + _mbg_swab32( &(_p)->time ); \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t idx; + MBG_SNMP_V3_SETTINGS settings; + +} MBG_SNMP_V3_SETTINGS_IDX; + +#define _mbg_swab_snmp_v3_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v3_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct +{ + MBG_SNMP_V3_SETTINGS settings; + uint32_t reserved_1[4]; + +} MBG_SNMP_V3_INFO; + +#define _mbg_swab_snmp_v3_info( _p ) \ +do \ +{ \ + _mbg_swab_snmp_v3_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t idx; + MBG_SNMP_V3_INFO info; + +} MBG_SNMP_V3_INFO_IDX; + +#define _mbg_swab_snmp_v3_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v3_info( &(_p)->info ); \ +} while ( 0 ) + + + +typedef struct +{ + uint8_t timeout; ///< In seconds + uint8_t retries; + uint8_t reserved_1[2]; + uint32_t reserved_2[3]; + MBG_SNMP_V3_SETTINGS v3_settings; + MBG_HOSTNAME receiver_addr; + uint16_t dest_port; ///< receiver destination port, 162 by default + uint16_t reserved_3; + +} MBG_SNMP_V3_TRAP_SETTINGS; + +#define _mbg_swab_snmp_v3_trap_settings( _p ) \ +do \ +{ \ + _mbg_swab_snmp_v3_settings( &(_p)->v3_settings ); \ + _mbg_swab16( &(_p)->dest_port ); \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t idx; + MBG_SNMP_V3_TRAP_SETTINGS settings; + +} MBG_SNMP_V3_TRAP_SETTINGS_IDX; + +#define _mbg_swab_snmp_v3_trap_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v3_trap_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct +{ + MBG_SNMP_V3_TRAP_SETTINGS settings; + uint32_t reserved_1[4]; + +} MBG_SNMP_V3_TRAP_INFO; + +#define _mbg_swab_snmp_v3_trap_info( _p ) \ +do \ +{ \ + _mbg_swab_snmp_v3_trap_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t idx; + MBG_SNMP_V3_TRAP_INFO info; + +} MBG_SNMP_V3_TRAP_INFO_IDX; + +#define _mbg_swab_snmp_v3_trap_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v3_trap_info( &(_p)->info ); \ +} while ( 0 ) + + + +enum MBG_EVENT_TYPES +{ + MBG_EVENT_TYPE_NTP_STATE, + MBG_EVENT_TYPE_HEARTBEAT, + MBG_EVENT_TYPE_RECEIVER_STATE, + N_MBG_EVENT_TYPES +}; + +#define MBG_EVENT_TYPE_STRS \ +{ \ + "NTP state", \ + "Heartbeat", \ + "Receiver state" \ +} + + +enum MBG_EVENT_SEVERITIES +{ + MBG_EVENT_SEVERITY_OK, + MBG_EVENT_SEVERITY_INFO, + MBG_EVENT_SEVERITY_WARNING, + MBG_EVENT_SEVERITY_ERROR, + MBG_EVENT_SEVERITY_CRITICAL, + N_MBG_EVENT_SEVERITIES +}; + +#define MBG_EVENT_SEVERITY_STRS \ +{ \ + "OK", \ + "Info", \ + "Warning", \ + "Error", \ + "Critical" \ +} + +typedef struct +{ + uint16_t triggers; ///< See ::MBG_MONITORING_TYPE_MSKS if set in ::MBG_MONITORING_LIMITS::supp_types + uint16_t interval; ///< [s], only if ::MBG_EVENT_SUPP_FLAG_INTERVAL is set in ::MBG_EVENT_INFO::supp_flags, else 0. + uint16_t reserved_1; + uint16_t reserved_2; + uint32_t reserved_3[6]; + +} MBG_EVENT_SETTINGS; + +#define _mbg_swab_event_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->triggers ); \ + _mbg_swab16( &(_p)->interval ); \ +} while ( 0 ) + + + +/** + * @brief Structure for monitoring event settings + * + * @see ::MBG_EVENT_INFO_IDX + */ +typedef struct +{ + uint32_t idx; + MBG_EVENT_SETTINGS settings; + +} MBG_EVENT_SETTINGS_IDX; + +#define _mbg_swab_event_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_event_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +enum MBG_EVENT_SUPP_FLAGS +{ + MBG_EVENT_SUPP_FLAG_INTERVAL, ///< Event can be sent cyclically + N_MBG_EVENT_SUPP_FLAGS +}; + + +enum MBG_EVENT_SUPP_FLAG_MSKS +{ + MBG_EVENT_SUPP_FLAG_MSK_INTERVAL = ( 1UL << MBG_EVENT_SUPP_FLAG_INTERVAL ) +}; + + + +/** + * @defgroup group_mbg_event_info_indexes Monitoring Event Info Indexes + * + * It's very important to understand how to use event indexes properly. + * In general, think of a management master system (MMS) + * like a LANTIME that is able to send its own events like "NTP not sync" + * and that is even able to send/forward events from other IMS modules + * like "CLK1 Antenna Disconnected". In case it is an event of the MMS + * itself, indexes in ::MBG_EVENT_INFO should be set to its "own" values below. + * But in case it is an event of an "IMS slave card" like a GPS180 + * at least ::MBG_EVENT_INFO::slot_type and ::MBG_EVENT_INFO::slot_type_id + * should be set. Most events will likely not support a port or a foreign + * chassis, so set ::MBG_EVENT_INFO::port_idx to ::MBG_INV_EVENT_PORT and/or + * ::MBG_EVENT_INFO::chassis_idx to ::MBG_OWN_EVENT_CHASSIS. + * Please be aware that there are IMS modules like SSP100 that tend to be + * "IMS slave cards", but they are, in fact, MMS because most of the time + * they are not connected to the main CPU via USB and + * therefore they send their "own" events. + * + * @{ */ + +#define MBG_OWN_EVENT_CHASSIS 0xFF ///< See ::MBG_EVENT_INFO::chassis_idx +#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 + +/** @} 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 + + 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 + + uint32_t reserved_3[6]; + +} MBG_EVENT_INFO; + +#define _mbg_swab_event_info( _p ) \ +do \ +{ \ + _mbg_swab_event_settings( &(_p)->settings ); \ + _mbg_swab16( &(_p)->type ); \ + _mbg_swab16( &(_p)->value_dict_entries ); \ + _mbg_swab16( &(_p)->supp_flags ); \ + _mbg_swab16( &(_p)->supp_triggers ); \ + _mbg_swab16( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Structure for monitoring event info + * + * @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. + * + * @see ::MBG_EVENT_TYPES + * @see ::MBG_MONITORING_LIMITS + */ +typedef struct +{ + uint32_t idx; + MBG_EVENT_INFO info; + +} MBG_EVENT_INFO_IDX; + +#define _mbg_swab_event_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_event_info( &(_p)->info ); \ +} 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 ) + + + +typedef struct +{ + uint32_t idx; + MBG_EVENT_VALUE value; + +} 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; + +} 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; \ + } \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t 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) ); \ +} while ( 0 ) + + + +enum MBG_SYSLOG_FLAGS +{ + MBG_SYSLOG_FLAG_NULL_TIMESTAMP, ///< Receiver should use his own timestamp + N_MBG_SYSLOG_FLAGS +}; + + +enum MBG_SYSLOG_FLAG_MSKS +{ + MBG_SYSLOG_FLAG_MSK_NULL_TIMESTAMP = (1UL << MBG_SYSLOG_FLAG_NULL_TIMESTAMP), ///< See ::MBG_SYSLOG_FLAG_NULL_TIMESTAMP +}; + + +enum MBG_SYSLOG_PROTOCOLS +{ + MBG_SYSLOG_PROTOCOL_UDP, + MBG_SYSLOG_PROTOCOL_TCP, + N_MBG_SYSLOG_PROTOCOLS +}; + +#define MBG_SYSLOG_PROTOCOL_STRS \ +{ \ + "UDP", \ + "TCP" \ +} + + +enum MBG_SYSLOG_PROTOCOL_MSKS +{ + MBG_SYSLOG_PROTOCOL_MSK_UDP = (1UL << MBG_SYSLOG_PROTOCOL_UDP), ///< See ::MBG_SYSLOG_PROTOCOL_UDP + MBG_SYSLOG_PROTOCOL_MSK_TCP = (1UL << MBG_SYSLOG_PROTOCOL_TCP) ///< See ::MBG_SYSLOG_PROTOCOL_TCP +}; + + +typedef struct +{ + uint8_t num_servers; ///< Number of configured servers + uint8_t reserved_1[3]; + uint32_t reserved_2[3]; + +} MBG_SYSLOG_GLB_SETTINGS; + +#define _mbg_swab_syslog_glb_settings( _p ) \ +do \ +{ \ +} while ( 0 ) + + +typedef struct +{ + MBG_SYSLOG_GLB_SETTINGS settings; ///< MBG_SYSLOG_GLB_SETTINGS + + uint8_t max_servers; ///< Maximum number of configurable servers + uint8_t reserved_1[3]; + uint32_t supp_flags; ///< See ::MBG_SYSLOG_FLAG_MSKS + uint32_t supp_protocols; ///< See ::MBG_SYSLOG_PROTOCOL_MSKS + + uint32_t reserved_2[5]; + +} MBG_SYSLOG_GLB_INFO; + +#define _mbg_swab_syslog_glb_info( _p ) \ +do \ +{ \ + _mbg_swab_syslog_glb_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->supp_protocols ); \ +} while ( 0 ) + + +typedef struct +{ + char host[MBG_MAX_HOSTNAME_LEN]; + uint8_t protocol; ///< See ::MBG_SYSLOG_PROTOCOLS + uint8_t reserved_1; + uint16_t port; ///< Protocol port + uint32_t flags; ///< See ::MBG_SYSLOG_FLAG_MSKS + uint32_t reserved_3[6]; + +} MBG_SYSLOG_SETTINGS; + +#define _mbg_swab_syslog_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->port ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_SYSLOG_SETTINGS settings; + uint32_t idx; + +} MBG_SYSLOG_SETTINGS_IDX; + +#define _mbg_swab_syslog_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab_syslog_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->idx ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_SYSLOG_SETTINGS settings; ///< See ::MBG_SYSLOG_SETTINGS + uint32_t reserved[8]; + +} MBG_SYSLOG_INFO; + +#define _mbg_swab_syslog_info( _p ) \ +do \ +{ \ + _mbg_swab_syslog_settings( &(_p)->settings ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_SYSLOG_INFO info; ///< See ::MBG_SYSLOG_INFO + uint32_t idx; + +} MBG_SYSLOG_INFO_IDX; + +#define _mbg_swab_syslog_info_idx( _p ) \ +do \ +{ \ + _mbg_swab_syslog_info( &(_p)->info ); \ + _mbg_swab32( &(_p)->idx ); \ +} while ( 0 ) + + +/** @} defgroup group_monitoring */ + + +/** + * @defgroup group_tainted_cfg Tainted config + * + * @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. + * + * TODO: Add proper Doxygen documentation + * + * @{ */ + + +#define MBG_TAINTED_CFG_BYTES 256 +#define MBG_TAINTED_CFG_FLAG_BYTES (MBG_TAINTED_CFG_BYTES >> 3) + +/** + * @brief Array positions in ::MBG_TAINTED_CFG::tainted_cfgs + * + */ +enum MBG_TAINTED_CFGS +{ + MBG_TAINTED_CFG_INV = -1, + MBG_TAINTED_CFG_SNMP, + MBG_TAINTED_CFG_EMAIL, + MBG_TAINTED_CFG_SYSLOG, + MBG_TAINTED_CFG_EVENTS, + MBG_TAINTED_CFG_IOPORTS, + MBG_TAINTED_CFG_NTP, + MBG_TAINTED_CFG_XBP, + MBG_TAINTED_CFG_NETWORK, + MBG_TAINTED_CFG_USERS, + MBG_TAINTED_CFG_FIRMWARE, + MBG_TAINTED_CFG_XMR, + MBG_TAINTED_CFG_TIMECODE_RX, + MBG_TAINTED_CFG_TIMECODE_TX, + MBG_TAINTED_CFG_HAVEQUICK, + MBG_TAINTED_CFG_GPIO, + MBG_TAINTED_CFG_UART, + MBG_TAINTED_CFG_PROG_OUT, + MBG_TAINTED_CFG_VAR_SYNTH, + MBG_TAINTED_CFG_TIMESCALE, + MBG_TAINTED_CFG_IGNLOCK, + MBG_TAINTED_CFG_GNSSMODE, + MBG_TAINTED_CFG_EF, + MBG_TAINTED_CFG_TZDL, + MBG_TAINTED_CFG_CABLE_LENGTH, + MBG_TAINTED_CFG_DATABASE, + N_MBG_TAINTED_CFGS +}; + +typedef struct +{ + uint8_t tainted_cfgs[MBG_TAINTED_CFG_BYTES]; ///< See ::MBG_TAINTED_CFGS + uint8_t supp_cfgs[MBG_TAINTED_CFG_FLAG_BYTES]; ///< See ::MBG_TAINTED_CFGS + uint32_t reserved[4]; ///< Future use + +} MBG_TAINTED_CFG; + +#define _mbg_swab_tainted_cfg( _p ) do {} while ( 0 ) + +#define _mbg_tainted_cfg_increase(c, cfg) \ +do \ +{ \ + if ( ( c >= MBG_TAINTED_CFG_BYTES ) || ( c >= N_MBG_TAINTED_CFGS ) ) \ + break; \ + \ + ++(cfg)->tainted_cfgs[ c ]; \ + \ +} while ( 0 ); + +/** + * @brief Set a supported tainted config bit in a ::MBG_TAINTED_CFG::supp_cfgs + * + * Should be used by the firmware only to set one of the supported ::N_MBG_TAINTED_CFGS + * bits in :MBG_TAINTED_CFG::supp_cfgs. + * + * @param[in] _cfg_bit One of the ::MBG_TAINTED_CFGS + * @param[in] _tainted_cfg Pointer to ::MBG_TAINTED_CFG + */ +#define _set_supp_tainted_cfg_bit( _cfg_bit, _tainted_cfg ) \ + _set_array_bit( _cfg_bit, (_tainted_cfg)->supp_cfgs, MBG_TAINTED_CFG_FLAG_BYTES ) + +/** + * @brief Clear a supported tainted config bit in a ::MBG_TAINTED_CFG::supp_cfgs + * + * Should be used by the firmware only to clear one of the supported ::N_MBG_TAINTED_CFGS + * bits in :MBG_TAINTED_CFG::supp_cfgs. + * + * @param[in] _cfg_bit One of the ::MBG_TAINTED_CFGS + * @param[in] _tainted_cfg Pointer to ::MBG_TAINTED_CFG + */ +#define _clear_supp_tainted_cfg_bit( _cfg_bit, _tainted_cfg ) \ + _clear_array_bit( _cfg_bit, (_tainted_cfg)->supp_cfgs, MBG_TAINTED_CFG_FLAG_BYTES ) + +/** + * @brief Check for a supported tainted config bit in a ::MBG_TAINTED_CFG::supp_cfgs + * + * @param[in] _cfg_bit One of the ::MBG_TAINTED_CFGS + * @param[in] _tainted_cfg Pointer to ::MBG_TAINTED_CFG + */ +#define _check_supp_tainted_cfg_bit( _cfg_bit, _tainted_cfg ) \ + check_feat_supp_byte_array( _cfg_bit, (_tainted_cfg)->supp_cfgs, MBG_TAINTED_CFG_FLAG_BYTES ) + +/** @} defgroup group_tainted_cfg */ + + +/** + * @defgroup group_user_mngmnt User Management + * + * @note These structures and definitions provide an extended user management + * for Meinberg devices based on the Linux user management and the files + * /etc/passwd and /etc/shadow. They are only supported by a device, + * if ::MBG_XFEATURE_USER_MNGMNT is set in the extended device features. + * + * @{ */ + +typedef enum +{ + USER_PERM_SYSTEM, ///< permission to read/write system related structures + ///< ::GPS_SCU_STAT + ///< ::GPS_TIME_SCALE + ///< ::GPS_TZDL + ///< ::PZF_TZCODE + ///< ::GPS_REBOOT + ///< ::MBG_TLV_FEAT_TYPE_DIAG_FILE + ///< ::GPS_TAINTED_CFG + ///< ::GPS_XBP_LIMITS + ///< ::GPS_XBP_NODE_LIMITS + ///< ::GPS_XBP_NODE_INFO_IDX + USER_PERM_RECEIVER, ///< permission to read/write receiver related structures + ///< ::GPS_TIME + ///< ::GPS_ANT_CABLE_LENGTH + ///< ::GPS_GNSS_MODE + ///< ::GPS_IGNORE_LOCK + ///< ::GPS_SAVE_CFG + ///< ::GPS_POS_XYZ + ///< ::GPS_POS_LLA + ///< ::GPS_STAT_INFO + ///< ::GPS_SV_INFO + ///< ::GPS_GNSS_SAT_INFO_IDX + ///< ::GPS_GNSS_SV_STATUS_IDX + ///< ::GPS_CLR_EVT_LOG + ///< ::GPS_NUM_EVT_LOG_ENTRIES + ///< ::GPS_FIRST_EVT_LOG_ENTRY + ///< ::GPS_NEXT_EVT_LOG_ENTRY + USER_PERM_MRS, ///< permission to read/write MRS related structures + ///< ::GPS_XMR_INSTANCES + ///< ::GPS_XMR_INFO_IDX + ///< ::GPS_XMR_EXT_SRC_INFO_IDX + ///< ::GPS_XMR_STATUS_IDX + ///< ::GPS_XMR_HOLDOVER_STATUS + ///< ::GPS_XMR_STATS_IDX + ///< ::GPS_XMR_METRICS_IDX + USER_PERM_SERIAL, ///< permission to read/write serial port related structures + ///< ::GPS_PORT_INFO_IDX + ///< ::GPS_STR_TYPE_INFO_IDX + USER_PERM_IOPORTS, ///< permission to read/write IO port related structures + ///< ::GPS_IRIG_RX_INFO + ///< ::GPS_RAW_IRIG_DATA + ///< ::GPS_REF_OFFS + ///< ::GPS_IRIG_RX_SETTINGS + ///< ::GPS_IRIG_TX_INFO + ///< ::GPS_SYNTH + ///< ::GPS_ENABLE_FLAGS + ///< ::GPS_IRIG_TX_SETTINGS + ///< ::GPS_POUT_INFO_IDX + ///< ::GPS_POUT_SETTINGS_IDX + ///< ::GPS_GPIO_CFG_LIMITS + ///< ::GPS_GPIO_INFO_IDX + ///< ::GPS_GPIO_SETTINGS_IDX + ///< ::GPS_GPIO_STATUS_IDX + ///< ::GPS_IO_PORT_LIMITS + ///< ::GPS_IO_PORT_INFO_IDX + ///< ::GPS_IO_PORT_TYPE_INFO_IDX + ///< ::GPS_IO_PORT_SETTINGS_IDX + ///< ::GPS_IO_PORT_STATUS_IDX + ///< ::GPS_UCAP_NET_GLB_INFO + ///< ::GPS_UCAP_NET_RECV_INFO_IDX + ///< ::GPS_CLR_UCAP_BUFF + ///< ::GPS_UCAP + USER_PERM_MONITORING, ///< permission to read/write monitoring related structures + ///< ::GPS_MONITORING_LIMITS + ///< ::GPS_SNMP_GLB + ///< ::GPS_SNMP_V12_IDX + ///< ::GPS_SNMP_V12_TRAP_IDX + ///< ::GPS_SNMP_V3_IDX + ///< ::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 + ///< ::GPS_CLR_EVT_LOG + ///< ::GPS_SYSLOG_GLB_INFO + ///< ::GPS_SYSLOG_INFO_IDX + USER_PERM_NETWORK, ///< permission to read/write network related structures + ///< ::GPS_NET_GLB_CFG + ///< ::GPS_NET_STAT_GLB_CFG + ///< ::GPS_NET_INTF_LINK_IDX + ///< ::GPS_NET_STAT_INTF_LINK_IDX + ///< ::GPS_NET_INTF_ADDR_IDX + ///< ::GPS_NET_STAT_INTF_ADDR_IDX + ///< ::GPS_NET_INTF_ROUTE_IDX + ///< ::GPS_NET_STAT_INTF_ROUTE_IDX + ///< ::GPS_NET_DNS_SRVR + ///< ::GPS_NET_STAT_DNS_SRVR + ///< ::GPS_NET_DNS_SRCH_DOM + ///< ::GPS_NET_STAT_DNS_SRCH_DOM + ///< ::GPS_LAN_IF_INFO + ///< ::GPS_IP4_SETTINGS + ///< ::GPS_IP4_STATE + USER_PERM_NTP, ///< permission to read/write NTP related structures + ///< ::GPS_NTP_GLB_CFG + ///< ::GPS_NTP_SYS_STATE + ///< ::GPS_NTP_SYMM_KEY_LIMITS + ///< ::GPS_NTP_SYMM_KEY_CFG + ///< ::GPS_NTP_TRUSTED_KEY_CFG + ///< ::GPS_NTP_CLNT_MODE_CFG + ///< ::GPS_NTP_PEER_SETTINGS_IDX + ///< ::GPS_NTP_PEER_STATE_IDX + ///< ::GPS_NTP_SRV_MODE_CFG + ///< ::GPS_NTP_REFCLK_CFG + ///< ::GPS_NTP_REFCLK_STATE_IDX + ///< ::GPS_NTP_MISC_LIMITS + ///< ::GPS_NTP_MISC_ORPHAN_MODE + USER_PERM_PTP, ///< permission to read/write PTP related structures + ///< ::GPS_PTP_CFG + ///< ::GPS_PTP_STATE + ///< ::GPS_PTP_UC_MASTER_CFG_LIMITS + ///< ::GPS_PTP_UC_MASTER_CFG + ///< ::GPS_PTP_V2_DEFAULT_DS + ///< ::GPS_PTP_V2_CURRENT_DS + ///< ::GPS_PTP_V2_PARENT_DS + ///< ::GPS_PTP_V2_TIME_PROP_DS + ///< ::GPS_PTP_V2_PORT_DS_IDX + ///< ::GPS_PTP_V1_DEFAULT_DS + ///< ::GPS_PTP_V1_CURRENT_DS + ///< ::GPS_PTP_V1_PARENT_DS + ///< ::GPS_PTP_V1_TIME_PROP_DS + ///< ::GPS_PTP_V1_PORT_DS_IDX + USER_PERM_FDM, ///< permission to read/write FDM related structures + ///< ::GPS_FDM_LIMITS + ///< ::GPS_FDM_INFO + ///< ::GPS_FDM_STATE + ///< ::GPS_FDM_SETTINGS + ///< ::GPS_FDM_OUTPUT_INFO_IDX + ///< ::GPS_FDM_OUTPUT_SETTINGS_IDX + ///< ::GPS_FDM_OUTPUT_STATE_IDX + ///< ::GPS_FDM_SET_TD + USER_PERM_SENSORS, ///< permission to read sensors related structures + ///< ::GPS_IMS_STATE + ///< ::GPS_IMS_SENSOR_STATE_IDX + USER_PERM_PASSWORD, ///< permission to read/change the user password + USER_PERM_USERS, ///< permission to read/write user related structures + ///< ::GPS_USER_MNGMNT_INFO + ///< ::GPS_USER_INFO_IDX + ///< ::GPS_USER_LEVEL_INFO_IDX + ///< ::GPS_USER_STATUS_IDX + USER_PERM_FIRMWARE, ///< permission to read/write firmware of a device + ///< ::GPS_FW_GLB_INFO + ///< ::GPS_FW_INFO_IDX + ///< ::GPS_FW_UFU_INFO_IDX + ///< ::GPS_FW_ACTIVATE + ///< ::GPS_FW_DELETE + ///< ::GPS_FW_UFU_FLASH + ///< ::MBG_TLV_FEAT_TYPE_FW_UPDATE + ///< ::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 + USER_PERM_DATABASE, ///< permission to read/write database related structures + ///< ::GPS_DATABASE_GLB_INFO + ///< ::GPS_DATABASE_INFO_IDX + N_USER_PERMS + +} MBG_USER_PERMS; + + +/** + * @brief Strings for defined user permissions + * + * @see ::MBG_USER_PERMS + */ +#define MBG_USER_PERM_STRS \ +{ \ + "System", \ + "Receiver", \ + "Ref. Sources", \ + "Serial Ports", \ + "IO Ports", \ + "Monitoring", \ + "Network", \ + "NTP", \ + "PTP", \ + "FDM", \ + "Sensors", \ + "Password", \ + "Users", \ + "Firmware", \ + "Services", \ + "Database" \ +} + + +typedef enum +{ + USER_SCOPE_STATUS_READ, + USER_SCOPE_CONFIG_READ, + USER_SCOPE_CONFIG_WRITE, + N_USER_SCOPES + +} MBG_USER_SCOPES; + + +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 + +} MBG_USER_SCOPE_MSKS; + + +#define MAX_USER_PERM_BYTES 64 +#define MAX_USER_PERM_BITS MAX_USER_PERM_BYTES * 8 + + +typedef enum +{ + USER_CHANNEL_WEB_INTERFACE, + USER_CHANNEL_MBGDEVMAN, + USER_CHANNEL_SHELL, + USER_CHANNEL_SNMP, + USER_CHANNEL_NETCONF, + N_USER_CHANNELS + +} MBG_USER_CHANNELS; + + +#define MAX_USER_CHANNEL_BYTES 16 +#define MAX_USER_CHANNEL_BITS MAX_USER_CHANNEL_BYTES * 8 + + +/** + * @brief Strings for defined user channels + * + * @see ::MBG_USER_CHANNELS + */ +#define MBG_USER_CHANNEL_STRS \ +{ \ + "Web Interface", \ + "Device Manager", \ + "Shell", \ + "SNMP", \ + "Netconf" \ +} + + +/** + * @brief A structure used to store user permissions. + * + * Up to ::MAX_USER_PERM_BITS totally can be stored. + * There should be one ::MBG_USER_PERM_BUF for status permissions, + * read configuration and write configuration permissions, each. + * + * @see ::MBG_USER_PERMS + * @see ::_set_user_perm + * @see ::_check_user_perm + */ +typedef struct +{ + uint8_t b[MAX_USER_PERM_BYTES]; ///< buffer for user permissions, see ::_set_user_perm and ::_check_user_perm + +} MBG_USER_PERM_BUF; + + +/** + * @brief Set a user permission in a ::MBG_USER_PERM_BUF + * + * @param[in] _user_perm_bit One of ::MBG_USER_PERMS + * @param[in] _user_perm_buffp Pointer to an ::MBG_USER_PERM_BUF + */ +#define _set_user_perm( _user_perm_bit, _user_perm_buffp ) \ + _set_array_bit( _user_perm_bit, (_user_perm_buffp)->b, MAX_USER_PERM_BYTES ) + + +/** + * @brief Unset a user permission in a ::MBG_USER_PERM_BUF + * + * @param[in] _user_perm_bit One of ::MBG_USER_PERMS + * @param[in] _user_perm_buffp Pointer to an ::MBG_USER_PERM_BUF + */ +#define _clear_user_perm( _user_perm_bit, _user_perm_buffp ) \ + _clear_array_bit( _user_perm_bit, (_user_perm_buffp)->b, MAX_USER_PERM_BYTES ) + + +/** + * @brief Check a user permission in a ::MBG_USER_PERM_BUF + * + * @param[in] _user_perm_bit One of ::MBG_USER_PERMS + * @param[in] _user_perm_buffp Pointer to an ::MBG_USER_PERM_BUF + */ +#define _check_user_perm( _user_perm_bit, _user_perm_buffp ) \ + check_feat_supp_byte_array( _user_perm_bit, (_user_perm_buffp)->b, MAX_USER_PERM_BYTES ) + + +/** + * @brief A structure used to store user channels. + * + * Up to ::MAX_USER_CHANNEL_BITS totally can be stored. + * + * @see ::MBG_USER_CHANNELS + * @see ::_set_user_channel + * @see ::_check_user_channel + */ +typedef struct +{ + uint8_t b[MAX_USER_CHANNEL_BYTES]; ///< buffer for user channels, see ::_set_user_channel and ::_check_user_channel + +} MBG_USER_CHANNEL_BUF; + + +/** + * @brief Set a user channel in a ::MBG_USER_CHANNEL_BUF + * + * @param[in] _user_channel_bit One of ::MBG_USER_CHANNELS + * @param[in] _user_channel_buffp Pointer to an ::MBG_USER_CHANNEL_BUF + */ +#define _set_user_channel( _user_channel_bit, _user_channel_buffp ) \ + _set_array_bit( _user_channel_bit, (_user_channel_buffp)->b, MAX_USER_CHANNEL_BYTES ) + + +/** + * @brief Unset a user channel in a ::MBG_USER_CHANNEL_BUF + * + * @param[in] _user_channel_bit One of ::MBG_USER_CHANNELS + * @param[in] _user_channel_buffp Pointer to an ::MBG_USER_CHANNEL_BUF + */ +#define _clear_user_channel( _user_channel_bit, _user_channel_buffp ) \ + _clear_array_bit( _user_channel_bit, (_user_channel_buffp)->b, MAX_USER_CHANNEL_BYTES ) + + +/** + * @brief Check a user channel in a ::MBG_USER_CHANNEL_BUF + * + * @param[in] _user_channel_bit One of ::MBG_USER_CHANNELS + * @param[in] _user_channel_buffp Pointer to an ::MBG_USER_CHANNEL_BUF + */ +#define _check_user_channel( _user_channel_bit, _user_channel_buffp ) \ + check_feat_supp_byte_array( _user_channel_bit, (_user_channel_buffp)->b, MAX_USER_CHANNEL_BYTES ) + + +typedef enum +{ + USER_MNGMNT_SUPP_USER_CFG, ///< device supports user configuration, otherwise users are static + USER_MNGMNT_SUPP_USER_LEVEL_CFG, ///< device supports user level configuration, otherwise user levels are static + N_USER_MNGMNT_FLAGS + +} MBG_USER_MNGMNT_FLAGS; + + +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 + +} MBG_USER_MNGMNT_FLAG_MASKS; + + +typedef struct +{ + uint32_t num_users; ///< current number of users + uint32_t num_levels; ///< current number of users + uint32_t reserved_1[2]; ///< reserved, currently always 0 + + uint32_t flags; ///< flags, see ::MBG_USER_MNGMNT_FLAG_MASKS + + uint32_t reserved_2[16]; ///< reserved, currently always 0 + +} MBG_USER_MNGMNT_SETTINGS; + + +#define _mbg_swab_user_mngmnt_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->num_users ); \ + _mbg_swab32( &(_p)->num_levels ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_USER_MNGMNT_SETTINGS settings; ///< settings, see ::MBG_USER_MNGMNT_SETTINGS + + uint32_t n_supp_users; ///< supported number of users + uint32_t n_supp_levels; ///< supported number of user levels + + MBG_USER_CHANNEL_BUF supp_user_channels; ///< supported channels for internal users + MBG_USER_CHANNEL_BUF supp_lvl_channels; ///< supported channels for external users + MBG_USER_PERM_BUF supp_perms; ///< supported user permissions + + uint32_t supp_flags; ///< supported flags, see ::MBG_USER_MNGMNT_FLAG_MASKS + + uint32_t reserved[16]; ///< reserved, currently always 0 + +} MBG_USER_MNGMNT_INFO; + + +#define _mbg_swab_user_mngmnt_info( _p ) \ +do \ +{ \ + _mbg_swab_user_mngmnt_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->n_supp_users ); \ + _mbg_swab32( &(_p)->n_supp_levels ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + +typedef enum +{ + USER_TYPE_USER, ///< standard system user + USER_TYPE_LEVEL, ///< user level for external authentication and as template for new users + N_USER_TYPES + +} MBG_USER_TYPE; + + +typedef enum +{ + USER_CFG_CAN_LOGIN, ///< the user is allowed to login (should not be set for root) + USER_CFG_CAN_REMOVE, ///< the user can be removed (should not be set for root) + USER_CFG_CAN_DISABLE_ON_FAILS, ///< the user supports the disabling after a number of login fails, see ::MBG_USER_SETTINGS::max_fails + USER_CFG_MULTI_SESSION, ///< allow user to login more than once (i.e. via TCP & Web) + USER_CFG_FORCE_CHANGE_ON_WARN, ///< user shall be forced to change the password on password warning + 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 + N_USER_CFG_FLAGS + +} MBG_USER_CFG_FLAGS; + + +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 + +} MBG_USER_CFG_FLAG_MASKS; + + +#define MBG_MAX_USER_NAME_LEN 32 /// See manpage useradd +#define MBG_MAX_USER_PASSWORD_LEN 32 + + +typedef struct +{ + char name[MBG_MAX_USER_NAME_LEN]; ///< user name + char password[MBG_MAX_USER_PASSWORD_LEN]; ///< user password, should only be set if it shall be changed + + uint32_t level_id; ///< unique id for user level, only used if ::MBG_USER_INFO::type is ::USER_TYPE_LEVEL + + uint32_t warn_days; ///< number of days, after which the user shall be warned about an upcoming password expiration, + uint32_t exp_days; ///< number of days, after which the password becomes invalid, see ::MBG_USER_INFO::password_doc, + uint32_t max_fails; ///< maximum number of login fails, before the user is disabled, + ///< only supported if ::USER_CFG_CAN_DISABLE_ON_FAILS_MASK + ///< all above values shall only be used, if they are not 0 + uint32_t flags; ///< flags, see ::MBG_USER_CFG_FLAG_MASKS + + MBG_USER_CHANNEL_BUF channels; ///< Channels, that are allowed for this user, see ::MBG_USER_CHANNEL_BUF + + MBG_USER_PERM_BUF stat_read_perm; ///< status read permission configuration, see ::MBG_USER_PERM_BUF and ::MBG_USER_PERMS + 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 + +} MBG_USER_SETTINGS; + + +#define _mbg_swab_user_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->warn_days ); \ + _mbg_swab32( &(_p)->exp_days ); \ + _mbg_swab32( &(_p)->max_fails ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + +typedef struct +{ + uint32_t idx; ///< the index of the user + MBG_USER_SETTINGS settings; ///< settings, see ::MBG_USER_SETTINGS + +} MBG_USER_SETTINGS_IDX; + + +#define _mbg_swab_user_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_user_settings( &(_p)->settings ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_USER_SETTINGS settings; + + uint8_t type; ///< type, see ::MBG_USER_TYPE + uint8_t reserved_1; ///< reserved, currently always 0 + uint16_t reserved_2; ///< reserved, currently always 0 + + uint32_t uid; ///< user id assigned by the OS + uint32_t gid; ///< group id + + 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 + +} MBG_USER_INFO; + + +#define _mbg_swab_user_info( _p ) \ +do \ +{ \ + _mbg_swab_user_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->uid ); \ + _mbg_swab32( &(_p)->gid ); \ + _mbg_swab32( &(_p)->password_doc ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + +typedef struct +{ + uint32_t idx; ///< the index of the user + MBG_USER_INFO info; ///< info, see ::MBG_USER_INFO + +} MBG_USER_INFO_IDX; + + +#define _mbg_swab_user_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_user_info( &(_p)->info ); \ +} while ( 0 ) + + +typedef enum +{ + USER_STAT_PASSWORD_WARN, ///< the user shall be warned about upcoming password expiration + USER_STAT_PASSWORD_EXP, ///< the user password has expired + USER_STAT_DISABLED_ON_EXP, ///< the user is disabled, because the password has expired + USER_STAT_DISABLED_ON_MAX_FAILS, ///< the user is disabled, because the max number of login fails has been exceeded + N_USER_STAT_FLAGS + +} MBG_USER_STAT_FLAGS; + + +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 + +} MBG_USER_STAT_FLAG_MASKS; + + +typedef struct +{ + uint32_t flags; ///< flags, see ::MBG_USER_STAT_FLAG_MASKS + uint32_t login_cnt; ///< current number of active logins + uint32_t num_fails; ///< current number of unsuccessful login attempts + + MBG_USER_PERM_BUF stat_read_perm; ///< current status read permissions, see ::MBG_USER_PERM_BUF and ::MBG_USER_PERMS + MBG_USER_PERM_BUF cfg_read_perm; ///< current config read permissions, see ::MBG_USER_PERM_BUF and ::MBG_USER_PERMS + MBG_USER_PERM_BUF cfg_write_perm; ///< current config write permissions, see ::MBG_USER_PERM_BUF and ::MBG_USER_PERMS + + uint32_t reserved[16]; ///< reserved, currently always 0 + +} MBG_USER_STATUS; + + +#define _mbg_swab_user_status( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->login_cnt ); \ + _mbg_swab32( &(_p)->num_fails ); \ +} while ( 0 ) + + +typedef struct +{ + uint32_t idx; ///< the index of the user + MBG_USER_STATUS status; ///< status, see ::MBG_USER_STATUS + +} MBG_USER_STATUS_IDX; + + +#define _mbg_swab_user_status_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_user_status( &(_p)->status ); \ +} while ( 0 ) + + +/** @} defgroup group_user_mngmnt */ + + + +/** + * @defgroup group_service_mngmnt Service Management + * + * @note These structures and definitions provide extended service management + * for Meinberg devices based on Linux / Windows. + * if ::MBG_XFEATURE_SERVICE is set in the extended device features. + * + * @{ */ + + +typedef enum +{ + MBG_SVC_TYPE_NTP, // Device supports NTP service (ntpd, or OpenNTP, etc ...) + MBG_SVC_TYPE_SNMP, // Device supports SNMP service (net-snmp, etc...) + N_MBG_SVC_TYPES + +} MBG_SERVICE_TYPES; + + +#define MBG_SERVICE_TYPE_STRS \ +{ \ + "NTP", \ + "SNMP" \ +} + + +typedef enum +{ + MBG_SVC_NTP_MSK = ( 1UL << MBG_SVC_TYPE_NTP ), ///< See ::MBG_SVC_TYPE_NTP + MBG_SVC_SNMP_MSK = ( 1UL << MBG_SVC_TYPE_SNMP ) ///< See ::MBG_SVC_TYPE_SNMP + +} MBG_SERVICE_MSKS; + + +typedef struct +{ + uint8_t num_services; ///< Current number of supported services + uint8_t reserved_1[3]; + uint32_t reserved_2[3]; + +} MBG_SERVICE_MGMT_INFO; + + +#define _mbg_swab_svc_mgmt_info( _p ) do {} while ( 0 ) + + +#define MBG_SVC_NAME_LEN 32 +#define MBG_SVC_CMD_LEN 192 + + +typedef enum +{ + MBG_SVC_UNKNOWN, + MBG_SVC_RUNNING, + MBG_SVC_STOPPED, + N_MBG_SVC_STATES + +} MBG_SERVICE_STATE; + + +#define MBG_SERVICE_STATE_STRS \ +{ \ + "Unknown", \ + "Running", \ + "Stopped" \ +} + + +typedef enum +{ + MBG_SVC_START, + MBG_SVC_STOP, + MBG_SVC_RESTART, + N_MBG_SVC_CTLS + +} MBG_SERVICE_CTL; + + +typedef struct +{ + char cmdline[MBG_SVC_CMD_LEN]; + uint8_t enabled; + uint8_t reserved_1[3]; + uint32_t reserved_2[3]; + +} MBG_SERVICE_SETTINGS; + + +#define _mbg_swab_svc_settings( _p ) do {} while ( 0 ) + + +typedef struct +{ + uint32_t idx; + MBG_SERVICE_SETTINGS settings; + +} MBG_SERVICE_SETTINGS_IDX; + + +#define _mbg_swab_svc_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_svc_settings( &(_p)->settings ); \ +} while ( 0 ) + + +typedef enum +{ + MBG_SVC_CAN_BE_DISABLED, + MBG_SVC_CAN_EDIT_CMDLINE, + N_MBG_SVC_FLAGS + +} MBG_SERVICE_INFO_FLAGS; + + +typedef enum +{ + MBG_SVC_MSK_CAN_BE_DISABLED = ( 1UL << MBG_SVC_CAN_BE_DISABLED ), ///< See ::MBG_SVC_CAN_BE_DISABLED + MBG_SVC_MSK_CAN_EDIT_CMDLINE = ( 1UL << MBG_SVC_CAN_EDIT_CMDLINE ) ///< See ::MBG_SVC_CAN_EDIT_CMDLINE + +} MBG_SERVICE_INFO_MSKS; + + +typedef struct +{ + MBG_SERVICE_SETTINGS settings; + uint8_t type; + uint8_t flags; ///< See ::MBG_SERVICE_INFO_MSKS + uint8_t reserved_1[2]; + char name[MBG_SVC_NAME_LEN]; + uint32_t reserved_2[5]; + +} MBG_SERVICE_INFO; + + +#define _mbg_swab_svc_info( _p ) \ +do \ +{ \ + _mbg_swab_svc_settings( &(_p)->settings ); \ +} while ( 0 ) + + +typedef struct +{ + uint32_t idx; + MBG_SERVICE_INFO info; + +} MBG_SERVICE_INFO_IDX; + + +#define _mbg_swab_svc_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_svc_info( &(_p)->info ); \ +} while ( 0 ) + + +typedef struct +{ + uint8_t state; ///< See ::MBG_SERVICE_STATE + uint8_t reserved_1[3]; + uint32_t reserved_2[3]; + +} MBG_SERVICE_STATUS; + + +#define _mbg_swab_svc_status( _p ) do {} while ( 0 ) + + +typedef struct +{ + uint32_t idx; + MBG_SERVICE_STATUS status; + +} MBG_SERVICE_STATUS_IDX; + + +#define _mbg_swab_svc_status_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_svc_status( &(_p)->status ); \ +} while ( 0 ) + + +/** @} defgroup group_service_mngmnt */ + + + +/** + * @defgroup group_fw_mngmnt Firmware Management + * + * @note These structures and definitions provide extended firmware management + * for Meinberg devices based on Linux / Windows. + * if ::MBG_XFEATURE_FW_MNGMNT is set in the extended device features. + * + * @{ */ + + +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]; + +} MBG_FW_GLB_INFO; + + +#define _mbg_swab_fw_glb_info( _p ) \ +do \ +{ \ +} while ( 0 ) + + +enum MBG_FW_FLAGS +{ + MBG_FW_FLAG_OSV, ///< Originally Shipped Version + MBG_FW_FLAG_ACTIVE, ///< Version is active (currently running) + MBG_FW_FLAG_UNERASABLE, ///< Firmware cannot be erased / deleted (e.g. OSV) + MBG_FW_FLAG_IMMUTABLE, ///< Single files (e.g. UFUs) within firmware cannot be + ///< updated, added, deleted, etc... + N_MBG_FW_FLAGS +}; + + +enum MBG_FW_FLAG_MSKS +{ + MBG_FW_FLAG_MSK_OSV = (1UL << MBG_FW_FLAG_OSV), ///< See ::MBG_FW_FLAG_OSV + MBG_FW_FLAG_MSK_ACTIVE = (1UL << MBG_FW_FLAG_ACTIVE), ///< See ::MBG_FW_FLAG_ACTIVE + MBG_FW_FLAG_MSK_UNERASABLE = (1UL << MBG_FW_FLAG_UNERASABLE), ///< See ::MBG_FW_FLAG_UNERASABLE + MBG_FW_FLAG_MSK_IMMUTABLE = (1UL << MBG_FW_FLAG_IMMUTABLE) ///< See ::MBG_FW_FLAG_IMMUTABLE +}; + + +enum MBG_FW_FILES +{ + MBG_FW_FILE_UNKNOWN, ///< Indicate there are unknown files (older FW scans newer files) + MBG_FW_FILE_INCREMENTAL, ///< Indicate there are incremental update files + MBG_FW_FILE_MEINBERG_DTB, ///< Meinberg device tree describes e.g. front connectors + MBG_FW_FILE_PRELOADER, ///< Whatever preloader magic file + MBG_FW_FILE_ROOTFS, ///< Root filesystem + MBG_FW_FILE_KERNEL_DTB, ///< Kernel device tree + MBG_FW_FILE_RBF, ///< FPGA firmware binary + MBG_FW_FILE_INITRD, ///< Initial ramdisk + MBG_FW_FILE_VERSION_TXT, ///< File containing firmware version + MBG_FW_FILE_KERNEL, ///< Kernel (not necessarily Linux) + N_MBG_FW_FILES +}; + + +#define MBG_FW_FILE_STRS \ +{ \ + "Unknown file(s)", \ + "Incremental file(s)", \ + "Meinberg device tree", \ + "Preloader", \ + "Root filesystem", \ + "Kernel device tree", \ + "FPGA firmware binary", \ + "Initial ramdisk", \ + "Version.txt", \ + "Kernel" \ +} + + +enum MBG_FW_FILE_MSKS +{ + MBG_FW_FILE_MSK_UNKNOWN = (1UL << MBG_FW_FILE_UNKNOWN), ///< See ::MBG_FW_FILE_UNKNOWN + MBG_FW_FILE_MSK_INCREMENTAL = (1UL << MBG_FW_FILE_INCREMENTAL), ///< See ::MBG_FW_FILE_INCREMENTAL + MBG_FW_FILE_MSK_MEINBERG_DTB = (1UL << MBG_FW_FILE_MEINBERG_DTB), ///< See ::MBG_FW_FILE_MEINBERG_DTB + MBG_FW_FILE_MSK_PRELOADER = (1UL << MBG_FW_FILE_PRELOADER), ///< See ::MBG_FW_FILE_PRELOADER + MBG_FW_FILE_MSK_ROOTFS = (1UL << MBG_FW_FILE_ROOTFS), ///< See ::MBG_FW_FILE_ROOTFS + MBG_FW_FILE_MSK_KERNEL_DTB = (1UL << MBG_FW_FILE_KERNEL_DTB), ///< See ::MBG_FW_FILE_KERNEL_DTB + MBG_FW_FILE_MSK_RBF = (1UL << MBG_FW_FILE_RBF), ///< See ::MBG_FW_FILE_RBF + MBG_FW_FILE_MSK_INITRD = (1UL << MBG_FW_FILE_INITRD), ///< See ::MBG_FW_FILE_INITRD + MBG_FW_FILE_MSK_VERSION_TXT = (1UL << MBG_FW_FILE_VERSION_TXT), ///< See ::MBG_FW_FILE_VERSION_TXT + MBG_FW_FILE_MSK_KERNEL = (1UL << MBG_FW_FILE_KERNEL) ///< See ::MBG_FW_FILE_KERNEL +}; + + +typedef struct +{ + uint32_t revision; ///< Main revision information + uint32_t flags; ///< See ::MBG_FW_FLAG_MSKS + uint16_t num_ufus; ///< Number of available UFUs + uint16_t reserved_1; + uint8_t release_candidate; ///< Release candidate revision information + uint8_t reserved_2[3]; + uint32_t files; ///< Single file (list) flags, See ::MBG_FW_FILE_MSKS + uint32_t reserved_3[11]; + +} MBG_FW_INFO; + + +#define _mbg_swab_fw_info( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->revision ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab16( &(_p)->num_ufus ); \ +} while ( 0 ) + + +typedef struct +{ + uint32_t idx; + MBG_FW_INFO info; + +} MBG_FW_INFO_IDX; + + +#define _mbg_swab_fw_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_fw_info( &(_p)->info ); \ +} while ( 0 ) + + +typedef struct +{ + uint32_t revision; ///< Main revision information + uint8_t release_candidate; ///< Release candidate revision information + uint8_t reserved_1[3]; + uint16_t model_code; ///< One of ::GPS_MODEL_CODES + uint16_t reserved_2; + uint32_t reserved_3[5]; + +} MBG_FW_UFU_INFO; + + +#define _mbg_swab_fw_ufu_info( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->revision ); \ + _mbg_swab16( &(_p)->model_code ); \ +} while ( 0 ) + + +typedef struct +{ + uint16_t fw_idx; ///< 0...::MBG_FW_GLB_INFO::installed_fws - 1 + uint16_t ufu_idx; ///< 0...::MBG_FW_INFO::num_ufus-1 + MBG_FW_UFU_INFO info; ///< See ::MBG_FW_UFU_INFO + +} MBG_FW_UFU_INFO_IDX; + + +#define _mbg_swab_fw_ufu_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->fw_idx ); \ + _mbg_swab16( &(_p)->ufu_idx ); \ + _mbg_swab_fw_ufu_info( &(_p)->info ); \ +} while ( 0 ) + + +/** + * @brief Command types used to flash UFU(S) to device(s) + */ +enum MBG_FW_UFU_FLASH_CMDS +{ + /// ::MBG_FW_UFU_FLASH_CMD::ufu_idx and ::MBG_FW_UFU_FLASH_CMD::xbp_addr must be set. + /// Send one specific UFU to a specific device identified by its XBP address + MBG_FW_UFU_FLASH_CMD_DEVICE_UFU, + + /// ::MBG_FW_UFU_FLASH_CMD::ufu_idx must be set. + /// Send one specific UFU to all suitable devices that fit the model code. + MBG_FW_UFU_FLASH_CMD_UFU_ALL, + + /// ::MBG_FW_UFU_FLASH_CMD::xbp_addr must be set. + /// Find the newest firmware version for a device identified by its XBP address + /// and flash it. + MBG_FW_UFU_FLASH_CMD_DEVICE, + + /// ::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. + MBG_FW_UFU_FLASH_CMD_TYPE, + + /// Find the newest firmware version for each single device and flash + /// each device with a corresponding firmware. + MBG_FW_UFU_FLASH_CMD_ALL, + + N_MBG_FW_UFU_FLASH_CMDS +}; + + +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 reserved_3; ///< Future use + uint32_t reserved_4[4]; ///< Future use + +} MBG_FW_UFU_FLASH_CMD; + + +#define _mbg_swab_fw_ufu_flash_cmd( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->ufu_idx ); \ + _mbg_swab16( &(_p)->model_code ); \ +} while ( 0 ) + + +/** @} defgroup group_fw_mngmnt */ + + + +/** + * @defgroup group_database Database(s) + * + * @note These structures and definitions provide database functionality + * if ::MBG_XFEATURE_DATABASE is set in the extended device features. + * + * @{ */ + + +enum MBG_DATABASE_TYPES +{ + MBG_DATABASE_TYPE_SQLITE, ///< SQLite + MBG_DATABASE_TYPE_MYSQL, ///< MySQL + MBG_DATABASE_TYPE_POSTGRESQL, ///< PostgreSQL + N_MBG_DATABASE_TYPES +}; + + +#define MBG_DATABASE_TYPE_STRS \ +{ \ + "SQLite", \ + "MySQL", \ + "PostgreSQL" \ +} + + +typedef struct +{ + uint8_t num_dbs; ///< Number of configurable databases + uint8_t reserved_1; + uint16_t reserved_2; + uint32_t reserved_3[3]; + +} MBG_DATABASE_GLB_INFO; + + +#define _mbg_swab_database_glb_info( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->supp_dbs ); \ +} while ( 0 ) + + +enum MBG_DATABASE_SETTINGS_FLAGS +{ + MBG_DATABASE_SETTINGS_FLAG_ENABLE, ///< Enable, disable logging to database + MBG_DATABASE_SETTINGS_FLAG_SAVE_PERSIST, ///< Save database (cyclically) to a persistent storage + N_MBG_DATABASE_SETTINGS_FLAGS +}; + + +enum MBG_DATABASE_SETTINGS_FLAG_MSKS +{ + MBG_DATABASE_SETTINGS_FLAG_MSK_ENABLE = (1UL << MBG_DATABASE_SETTINGS_FLAG_ENABLE), ///< See ::MBG_DATABASE_SETTINGS_FLAG_ENABLE + MBG_DATABASE_SETTINGS_FLAG_MSK_SAVE_PERSIST = (1UL << MBG_DATABASE_SETTINGS_FLAG_SAVE_PERSIST) ///< See ::MBG_DATABASE_SETTINGS_FLAG_SAVE_PERSIST +}; + + +#define MBG_DATABASE_MAX_STR 32 + + +typedef struct +{ + 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 host[MBG_MAX_HOSTNAME_LEN]; + + char dbname[MBG_DATABASE_MAX_STR]; ///< Database name + char reserved_3[MBG_DATABASE_MAX_STR]; + char reserved_4[MBG_DATABASE_MAX_STR]; + +} MBG_DATABASE_SETTINGS; + + +#define _mbg_swab_database_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->port ); \ +} while ( 0 ) + + +typedef struct +{ + uint32_t idx; + MBG_DATABASE_SETTINGS settings; + +} MBG_DATABASE_SETTINGS_IDX; + + +#define _mbg_swab_database_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_database_settings( &(_p)->settings ); \ +} while ( 0 ) + + +enum MBG_DATABASE_INFO_FLAGS +{ + MBG_DATABASE_INFO_FLAG_LOCAL_FILE, ///< Database is a local file only + N_MBG_DATABASE_INFO_FLAGS +}; + + +enum MBG_DATABASE_INFO_FLAG_MSKS +{ + /// See ::MBG_DATABASE_INFO_FLAG_LOCAL_FILE + MBG_DATABASE_INFO_FLAG_MSK_LOCAL_FILE = ( 1UL << MBG_DATABASE_INFO_FLAG_LOCAL_FILE ) +}; + + +enum MBG_DATABASE_MEMBERS +{ + MBG_DATABASE_MEMBER_FLAGS, ///< ::MBG_DATABASE_SETTINGS::flags is valid + MBG_DATABASE_MEMBER_PORT, ///< ::MBG_DATABASE_SETTINGS::port is valid + MBG_DATABASE_MEMBER_USER, ///< ::MBG_DATABASE_SETTINGS::user is valid + MBG_DATABASE_MEMBER_PASSWORD, ///< ::MBG_DATABASE_SETTINGS::password is valid + MBG_DATABASE_MEMBER_HOST, ///< ::MBG_DATABASE_SETTINGS::host is valid + MBG_DATABASE_MEMBER_DBNAME, ///< ::MBG_DATABASE_SETTINGS::dbname is valid + N_MBG_DATABASE_MEMBERS +}; + + +enum MBG_DATABASE_MEMBER_MSKS +{ + MBG_DATABASE_MEMBER_MSK_FLAGS = (1UL << MBG_DATABASE_MEMBER_FLAGS), ///< See ::MBG_DATABASE_MEMBER_FLAGS + MBG_DATABASE_MEMBER_MSK_PORT = (1UL << MBG_DATABASE_MEMBER_PORT), ///< See ::MBG_DATABASE_MEMBER_PORT + MBG_DATABASE_MEMBER_MSK_USER = (1UL << MBG_DATABASE_MEMBER_USER), ///< See ::MBG_DATABASE_MEMBER_USER + MBG_DATABASE_MEMBER_MSK_PASSWORD = (1UL << MBG_DATABASE_MEMBER_PASSWORD), ///< See ::MBG_DATABASE_MEMBER_PASSWORD + MBG_DATABASE_MEMBER_MSK_HOST = (1UL << MBG_DATABASE_MEMBER_HOST), ///< See ::MBG_DATABASE_MEMBER_HOST + MBG_DATABASE_MEMBER_MSK_DBNAME = (1UL << MBG_DATABASE_MEMBER_DBNAME) ///< See ::MBG_DATABASE_MEMBER_DBNAME +}; + + +typedef struct +{ + MBG_DATABASE_SETTINGS settings; ///< See ::MBG_DATABASE_SETTINGS + 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. + uint16_t supp_members; + + /// Flag field which ::MBG_DATABASE_MEMBER_MSKS are configurable. + /// Subset of ::MBG_DATABASE_INFO::supp_members. + + uint16_t supp_cfgs; + + /// 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 + uint16_t supp_settings_flags; + + uint32_t reserved_3[2]; + +} MBG_DATABASE_INFO; + + +#define _mbg_swab_database_info( _p ) \ +do \ +{ \ + _mbg_swab_database_settings( &(_p)->settings ); \ + _mbg_swab16( &(_p)->supp_members ); \ + _mbg_swab16( &(_p)->supp_cfgs ); \ +} while ( 0 ) + + +typedef struct +{ + uint32_t idx; + MBG_DATABASE_INFO info; + +} MBG_DATABASE_INFO_IDX; + + +#define _mbg_swab_database_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_database_info( &(_p)->info ); \ +} while ( 0 ) + + +enum MBG_DATABASE_CMDS +{ + MBG_DATABASE_CMD_RESET_SV_LOGS, + N_MBG_DATABASE_CMDS +}; + + +typedef struct +{ + uint32_t cmd; ///< See ::MBG_DATABASE_CMDS + uint32_t length; ///< Payload data length of ::MBG_DATABASE_CMD::payload + uint32_t reserved[2]; ///< Future use + unsigned char payload[240]; ///< Payload data + +} MBG_DATABASE_CMD; + + +#define _mbg_swab_database_cmd( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->cmd ); \ + _mbg_swab32( &(_p)->length ); \ +} while ( 0 ) + + +/** @} defgroup group_database */ + + + #if defined( _USING_BYTE_ALIGNMENT ) #pragma pack() // set default alignment #undef _USING_BYTE_ALIGNMENT diff --git a/mbglib/common/gpsutils.h b/mbglib/common/gpsutils.h index c2143ca..0454429 100644 --- a/mbglib/common/gpsutils.h +++ b/mbglib/common/gpsutils.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: gpsutils.h 1.7 2010/07/15 09:32:09Z martin REL_M $ + * $Id: gpsutils.h 1.8 2017/07/05 13:58:25Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: gpsutils.h $ - * Revision 1.7 2010/07/15 09:32:09Z martin + * Revision 1.8 2017/07/05 13:58:25Z martin + * Include stddef.h. + * Updated function prototypes. + * Revision 1.7 2010/07/15 09:32:09 martin * Use DEG character definition from pcpslstr.h. * Revision 1.6 2005/02/18 10:32:33Z martin * Check more predefined macros to determine if compiling for Windows. @@ -34,6 +37,8 @@ #include <mbggeo.h> +#include <stddef.h> + #ifdef _GPSUTILS #define _ext @@ -45,28 +50,174 @@ /* Start of header body */ - -/* function prototypes: */ - #ifdef __cplusplus extern "C" { #endif + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ - void swap_double( double *d ) ; - void swap_eph_doubles( EPH *ephp ) ; - void swap_alm_doubles( ALM *almp ) ; - void swap_utc_doubles( UTC *utcp ) ; - void swap_iono_doubles( IONO *ionop ) ; - void swap_pos_doubles( POS *posp ) ; - void sprint_dms( char *s, DMS *pdms, int prec ) ; - void sprint_alt( char *s, double alt ) ; - void sprint_pos_geo( char *s, POS *ppos, const char *sep, int prec ) ; - void sprint_fixed_freq( char *s, FIXED_FREQ_INFO *p_ff ) ; + /** + * @brief Swap the bytes of a single variable of type "double" + * + * The memory layout of a "double" on Meinberg bus level devices + * and computers usually differs. This function can be used to + * fix this and is usually called from inside API functions, + * if required. + * + * @param[in,out] p Pointer to a "double" to be swapped + * + * @see ::swap_eph_doubles + * @see ::swap_alm_doubles + * @see ::swap_utc_doubles + * @see ::swap_iono_doubles + * @see ::swap_pos_doubles + */ + void swap_double( double *p ) ; + + /** + * @brief Swap the "double" fields in an ::EPH structure + * + * See comments for ::swap_double + * + * @param[in,out] p Pointer to an ::EPH structure to be converted + * + * @see ::swap_double + * @see ::swap_alm_doubles + * @see ::swap_utc_doubles + * @see ::swap_iono_doubles + * @see ::swap_pos_doubles + */ + void swap_eph_doubles( EPH *p ) ; + + /** + * @brief Swap the "double" fields in an ::ALM structure + * + * See comments for ::swap_double + * + * @param[in,out] p Pointer to an ::ALM structure to be converted + * + * @see ::swap_double + * @see ::swap_eph_doubles + * @see ::swap_utc_doubles + * @see ::swap_iono_doubles + * @see ::swap_pos_doubles + */ + void swap_alm_doubles( ALM *p ) ; + + /** + * @brief Swap the "double" fields in a ::UTC structure + * + * See comments for ::swap_double + * + * @param[in,out] p Pointer to a ::UTC structure to be converted + * + * @see ::swap_double + * @see ::swap_eph_doubles + * @see ::swap_alm_doubles + * @see ::swap_iono_doubles + * @see ::swap_pos_doubles + */ + void swap_utc_doubles( UTC *p ) ; + + /** + * @brief Swap the "double" fields in a ::IONO structure + * + * See comments for ::swap_double + * + * @param[in,out] p Pointer to a ::IONO structure to be converted + * + * @see ::swap_double + * @see ::swap_eph_doubles + * @see ::swap_alm_doubles + * @see ::swap_utc_doubles + * @see ::swap_pos_doubles + */ + void swap_iono_doubles( IONO *p ) ; + + /** + * @brief Swap the "double" fields in a ::POS structure + * + * See comments for ::swap_double + * + * @param[in,out] p Pointer to a ::POS structure to be converted + * + * @see ::swap_double + * @see ::swap_eph_doubles + * @see ::swap_alm_doubles + * @see ::swap_utc_doubles + * @see ::swap_iono_doubles + */ + void swap_pos_doubles( POS *p ) ; + + /** + * @brief Print the ::DMS part of a geo position 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] p Pointer to a ::DMS structure to be printed + * @param[in] prec Precision, i.e. number of fractions of the seconds + * + * @return Length of the string in the buffer + * + * @see snprint_dms + * @see snprint_alt + * @see snprint_pos_geo + * @see snprint_fixed_freq + */ + size_t snprint_dms( char *s, size_t max_len, const DMS *p, int prec ) ; + + /** + * @brief Print the altitude part of a geo position 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] alt The altitude value to be printed, in [m] + * + * @return Length of the string in the buffer + * + * @see snprint_dms + * @see snprint_pos_geo + * @see snprint_fixed_freq + */ + size_t snprint_alt( char *s, size_t max_len, double alt ) ; + + /** + * @brief Print a geo position in ::POS format 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] p Pointer to a ::POS structure to be printed + * @param[in] sep Separator character for the ::DMS part + * @param[in] prec Precision, i.e. number of fractions of the seconds of the ::DMS part + * + * @return Length of the string in the buffer + * + * @see snprint_dms + * @see snprint_alt + * @see snprint_fixed_freq + */ + size_t snprint_pos_geo( char *s, size_t max_len, const POS *p, char sep, int prec ) ; + + /** + * @brief Print a formatted ::FIXED_FREQ_INFO 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] p_ff Pointer to a ::FIXED_FREQ_INFO structure to be printed + * + * @return Length of the string in the buffer + * + * @see snprint_dms + * @see snprint_alt + * @see snprint_pos_geo + */ + size_t snprint_fixed_freq( char *s, size_t max_len, FIXED_FREQ_INFO *p_ff ) ; + /* ----- function prototypes end ----- */ diff --git a/mbglib/common/irig_cal.h b/mbglib/common/irig_cal.h new file mode 100644 index 0000000..efab5d1 --- /dev/null +++ b/mbglib/common/irig_cal.h @@ -0,0 +1,257 @@ + +/************************************************************************** + * + * $Id: irig_cal.h 1.4 2018/03/21 14:58:06Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and inline functions to calibrate IRIG inputs. + * + * ----------------------------------------------------------------------- + * $Log: irig_cal.h $ + * Revision 1.4 2018/03/21 14:58:06Z martin + * Fixed a compiler warning. + * Revision 1.3 2015/08/31 09:35:30Z martin + * Quieted a compiler warning. + * Revision 1.2 2012/01/17 09:58:36Z martin + * Added new function mbg_icode_rx_to_group_idx(). + * Do a pausibility check in mbg_get_cal_rec_irig_rx_num_rec(). + * Revision 1.1 2011/11/23 17:50:02 martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _IRIG_CAL_H +#define _IRIG_CAL_H + + +/* Other headers to be included */ + +#include <mbgdevio.h> +#include <use_pack.h> + + +#ifdef _IRIG_CAL + #define _ext +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#if defined( _USE_PACK ) // set byte alignment + #pragma pack( 1 ) + #define _USING_BYTE_ALIGNMENT +#endif + + +/** + * @brief Get the IRIG calibration group index for a given IRIG RX code. + * + * There are calibration data records available for different groups of IRIG RX + * 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 + * + * @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 ) +{ + ulong icode_mask = 1UL << icode_rx; + + if ( icode_mask & MSK_ICODE_RX_DC ) + { + // for DCLS codes check the bit rate + + if ( icode_mask & MSK_ICODE_RX_100BPS ) + return IRIG_RX_COMP_B0; + + if ( icode_mask & MSK_ICODE_RX_1000BPS ) + return IRIG_RX_COMP_A0; + + if ( icode_mask & MSK_ICODE_RX_10000BPS ) + return IRIG_RX_COMP_G0; + + return -1; // unknown DLCS code + } + + + // for modulated codes check the carrier frequency + + if ( icode_mask & MSK_ICODE_RX_1KHZ ) + return IRIG_RX_COMP_B1; + + if ( icode_mask & MSK_ICODE_RX_10KHZ ) + return IRIG_RX_COMP_A1; + + if ( icode_mask & MSK_ICODE_RX_100KHZ ) + return IRIG_RX_COMP_G1; + + return -1; // unknown modulated code + +} // mbg_icode_rx_to_group_idx + + + +/** + * @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 + * + * @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() + */ +static __mbg_inline +int mbg_get_gen_io_info( MBG_DEV_HANDLE dh, GEN_IO_INFO_TYPE type, GEN_IO_INFO *p ) +{ + int rc; + + _mbg_swab_gen_io_info_type( &type ); + + rc = mbg_generic_io( dh, PCPS_GEN_IO_GET_INFO, &type, sizeof( type ), p, sizeof( *p ) ); + + if ( rc == MBG_SUCCESS ) + _mbg_swab_gen_io_info( p ); + + return rc; + +} // mbg_get_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 + * + * @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() + */ +static __mbg_inline +int mbg_get_cal_rec_irig_rx_num_rec( MBG_DEV_HANDLE dh, int *p_num_rec ) +{ + GEN_IO_INFO tmp = { 0 }; + int rc = mbg_get_gen_io_info( dh, PCPS_GEN_IO_CAL_REC_IRIG_RX_COMP, &tmp ); + + if ( rc == MBG_SUCCESS ) + { + _mbg_swab_gen_io_info( &tmp ); + *p_num_rec = ( tmp.type == PCPS_GEN_IO_CAL_REC_IRIG_RX_COMP ) ? tmp.num : 0; + } + + return rc; + +} // mbg_get_cal_rec_irig_rx_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 + * + * @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() + */ +static __mbg_inline +int mbg_get_cal_rec_irig_rx_comp( MBG_DEV_HANDLE dh, uint16_t idx, CAL_REC_IRIG_RX_COMP *p ) +{ + CAL_REC_HDR hdr; + int rc; + + hdr.type = CAL_REC_TYPE_IRIG_RX_COMP; + hdr.idx = idx; + + _mbg_swab_cal_rec_hdr( &hdr ); + + rc = mbg_generic_io( dh, PCPS_GEN_IO_CAL_REC_IRIG_RX_COMP, + &hdr, sizeof( hdr ), p, sizeof( *p ) ); + + if ( rc == MBG_SUCCESS ) + _mbg_swab_cal_rec_irig_rx_comp( p ); + + return rc; + +} // mbg_get_cal_rec_irig_rx_comp + + + +/** + * @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 + * + * @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() + */ +static __mbg_inline +int mbg_set_cal_rec_irig_rx_comp( MBG_DEV_HANDLE dh, const CAL_REC_IRIG_RX_COMP *p ) +{ + int rc; + + #if defined( MBG_ARCH_BIG_ENDIAN ) + CAL_REC_IRIG_RX_COMP tmp = *p; + _mbg_swab_cal_rec_irig_rx_comp( &tmp ); + p = &tmp; + #endif + + rc = mbg_generic_io( dh, PCPS_GEN_IO_CAL_REC_IRIG_RX_COMP, + p, sizeof( *p ), NULL, 0 ); + + return rc; + +} // mbg_set_cal_rec_irig_rx_comp + + + +#ifdef __cplusplus +extern "C" { +#endif + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + +/* (no header definitions found) */ + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + +#if defined( _USING_BYTE_ALIGNMENT ) + #pragma pack() // set default alignment + #undef _USING_BYTE_ALIGNMENT +#endif + +/* End of header body */ + + +#undef _ext + +#endif /* _IRIG_CAL_H */ + diff --git a/mbglib/common/lan_util.c b/mbglib/common/lan_util.c index cca8a0a..bd197a7 100644 --- a/mbglib/common/lan_util.c +++ b/mbglib/common/lan_util.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: lan_util.c 1.6 2013/03/19 10:24:51Z martin REL_M $ + * $Id: lan_util.c 1.16 2018/04/06 14:58:54Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,49 @@ * * ----------------------------------------------------------------------- * $Log: lan_util.c $ - * Revision 1.6 2013/03/19 10:24:51Z martin + * Revision 1.16 2018/04/06 14:58:54Z 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. + * Doxygen fixes. + * Revision 1.14 2018/01/30 17:20:07 martin + * Fixed a compiler warning where a char was used as array index. + * Revision 1.13 2017/10/05 08:20:40 daniel + * Introduced check_port_status() function + * Revision 1.12 2017/07/05 14:07:56 martin + * IPv6 support functions added by hannes. + * Function snprint_ip4_cidr_mask() fixed by hannes. It now behaves + * as expected and appends the CIDR mask bits to the IP address now. + * Mostly use safe string functions from str_util.c. + * New function snprint_ptp_clock_id(). + * Compiler warnings due to uninitialized vars quieted by thomas-b. + * Renamed check_octets_not_all_zero() to octets_are_all_zero(), + * which returns a bool now. + * Renamed check_mac_addr_not_all_zero() to mac_addr_all_zero(), + * which returns a bool now. + * Removed get_port_mac_addr_check(). + * Removed definitions of old MBG_LU_... return codes, and + * only use standard MBG_RETURN_CODES instead. + * Fixed macro definition syntax to quiet clang compiler warnings. + * Let get_port_ip4_settings() check port link even if it + * returns an error (changed by daniel). + * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. + * Doxygen comments. + * Revision 1.11 2015/04/01 14:31:14 hannes + * Fix: cidr_str_to_ip4_addr_and_net_mask: Defaults correctly to + * netmask 0.0.0.0 (/0) for no CIDR extension in cidr_str. + * Revision 1.10 2014/10/17 12:45:48 martin + * Let str_to_ip4_addr() return 0 if an empty string has been passed. + * Revision 1.9 2014/09/24 08:31:00 martin + * Exclude get_ip4_gateway() from build if USE_MBG_TSU is defined. + * Fixed some compiler warnings. + * Added and modified some comments. + * Revision 1.8 2013/10/02 07:19:13 martin + * New function get_port_intf_idx. + * Fixed naming.of local netlink support functions. + * Revision 1.7 2013/05/22 16:49:42 martin + * Fixed some return codes. + * Revision 1.6 2013/03/19 10:24:51 martin * Fixed bugs in get_ip4_gateway(): A skipped routing entry was * taken as default route, and thus a wrong default route 0.0.0.0 * could be returned erraneously. Also, malloc() was used without @@ -34,12 +76,17 @@ #include <lan_util.h> #undef _LAN_UTIL +#include <words.h> +#include <str_util.h> +#include <mbgerror.h> + #include <stdio.h> #include <string.h> +#include <ctype.h> -#if defined ( MBG_TGT_UNIX ) +#if defined( MBG_TGT_POSIX ) - #if defined ( MBG_TGT_LINUX ) + #if defined( MBG_TGT_LINUX ) #include <linux/types.h> @@ -60,8 +107,8 @@ #endif #include <unistd.h> + #include <syslog.h> #include <sys/ioctl.h> - #include <sys/errno.h> #include <arpa/inet.h> #include <netinet/in.h> @@ -80,7 +127,11 @@ #if !defined( DEBUG_NETLINK ) - #define DEBUG_NETLINK ( 0 && defined( DEBUG ) && defined( MBG_TGT_LINUX ) ) + #if ( 0 && defined( DEBUG ) && defined( MBG_TGT_LINUX ) ) + #define DEBUG_NETLINK 1 + #else + #define DEBUG_NETLINK 0 + #endif #endif @@ -90,7 +141,7 @@ #include <ptp2_cnf.h> // for mbglog() from the ARM PTP projects #else // to be provided by the application - extern void mbglog( int priority, const char *fmt, ... ); + extern __attribute__( ( format( printf, 2, 3 ) ) ) void mbglog( int priority, const char *fmt, ... ); #endif #endif // DEBUG_NETLINK @@ -102,7 +153,7 @@ #define MAX_IP4_ADDR_STR_SIZE 16 -#if defined ( MBG_TGT_LINUX ) +#if defined( MBG_TGT_LINUX ) struct route_info { @@ -115,45 +166,19 @@ struct route_info #endif -#if defined( __BORLANDC__ ) \ - && ( __BORLANDC__ <= 0x410 ) // BC3.1 defines 0x410 ! - -#include <stdarg.h> - -// Declare a snprintf() function if not provided by the -// build environment, though this implementation actually -// does not check the string length ... - -static /*HDR*/ -int snprintf( char *s, size_t max_len, const char *fmt, ... ) -{ - int n; - va_list arg_list; - - va_start( arg_list, fmt ); - n = vsprintf( s, fmt, arg_list ); - va_end( arg_list ); - - return n; - -} // snprintf - -#endif - - /*HDR*/ /** - * @brief Count the number of sequential bits set starting from MSB + * @brief Count the number of sequential bits in an IPv4 net mask * - * E.g. for 0xC0 and 0xC1 the results are both 2 since only - * the 2 MSBs are sequentially set. + * Counting starts from MSB, i.e. for 0xC0 and 0xC1 the results + * are both 2 since only the 2 MSBs are sequentially set. * - * @param p_mask The IP4 net mask + * @param[in] p_mask The IPv4 net mask to be evaluated * - * @return The number of sequential MSB bits set in val + * @return The number of sequential MSB bits set in *p_mask * - * @see ip4_net_mask_from_cidr + * @see ::ip4_net_mask_from_cidr */ int get_ip4_net_mask_bits( const IP4_ADDR *p_mask ) { @@ -176,30 +201,30 @@ int get_ip4_net_mask_bits( const IP4_ADDR *p_mask ) /*HDR*/ /** - * @brief Print an IPv4 address to a dotted quad format string. + * @brief Print an IPv4 address to a dotted quad formatted string * - * @param s The string buffer into which to print - * @param max_len Maximum length of the string, i.e. size of the buffer - * @param p_addr The IPv4 address - * @param info An optional string which is prepended to the string, or NULL + * @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 * * @return The overall number of characters printed to the string * - * @see snprint_ip4_cidr_addr - * @see str_to_ip4_addr - * @see cidr_str_to_ip4_addr_and_net_mask + * @see ::snprint_ip4_cidr_addr + * @see ::str_to_ip4_addr + * @see ::cidr_str_to_ip4_addr_and_net_mask */ -int snprint_ip4_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, const char *info ) +size_t snprint_ip4_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, const char *info ) { - int n = 0; + size_t n = 0; ulong ul = *p_addr; if ( info ) - n += snprintf( s, max_len, "%s", info ); + n += snprintf_safe( s, max_len, "%s", info ); // Don't use byte pointers here since this is not safe // for both little and big endian targets. - n += snprintf( &s[n], max_len - n, "%lu.%lu.%lu.%lu", + n += snprintf_safe( &s[n], max_len - n, "%u.%u.%u.%u", BYTE_3( ul ), BYTE_2( ul ), BYTE_1( ul ), BYTE_0( ul ) ); @@ -211,35 +236,33 @@ int snprint_ip4_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, const cha /*HDR*/ /** - * @brief Print an IPv4 address plus net mask to string in CIDR notation. + * @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 s The string buffer into which to print - * @param max_len Maximum length of the string, i.e. size of the buffer - * @param p_addr The IPv4 address - * @param p_mask The IPv4 net mask - * @param info An optional string which is prepended to the string, or NULL + * @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 * * @return The overall number of characters printed to the string * - * @see snprint_ip4_addr - * @see str_to_ip4_addr - * @see cidr_str_to_ip4_addr_and_net_mask + * @see ::snprint_ip4_addr + * @see ::str_to_ip4_addr + * @see ::cidr_str_to_ip4_addr_and_net_mask */ -int snprint_ip4_cidr_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, - const IP4_ADDR *p_mask, const char *info ) +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 ) { int cidr_mask_bits; - IP4_ADDR normalized_addr = ip4_net_part_from_addr( p_addr, p_mask ); - - int n = snprint_ip4_addr( s, max_len, &normalized_addr, info ); + size_t n = snprint_ip4_addr( s, max_len, p_addr, info ); cidr_mask_bits = get_ip4_net_mask_bits( p_mask ); if ( ( cidr_mask_bits >= MIN_IP4_CIDR_NETMASK_BITS ) && ( cidr_mask_bits <= MAX_IP4_CIDR_NETMASK_BITS ) ) - n += snprintf( &s[n], max_len - n, "/%i", cidr_mask_bits ); + n += snprintf_safe( &s[n], max_len - n, "/%i", cidr_mask_bits ); return n; @@ -249,49 +272,54 @@ int 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. * - * @param p_addr Pointer to the IP4_ADDR variable, or NULL, in which case this - * function can be used to check if the string is formally correct. - * @param s The string to be converted + * @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 * - * @return >= 0 on success, number of characters evaluated from the input string - * -1 if invalid number found in string - * -2 if separator is not a dot '.' + * @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, + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. * - * @see snprint_ip4_addr - * @see snprint_ip4_cidr_addr - * @see cidr_str_to_ip4_addr_and_net_mask + * @see ::snprint_ip4_addr + * @see ::snprint_ip4_cidr_addr + * @see ::cidr_str_to_ip4_addr_and_net_mask */ int str_to_ip4_addr( IP4_ADDR *p_addr, const char *s ) { IP4_ADDR tmp_ip4_addr = 0; - const char *cp; + const char *cp = s; int i; - for ( i = 0, cp = (char *) s; ; ) + if ( strlen( s ) ) { - unsigned long ul = strtoul( (char *) cp, (char **) &cp, 10 ); + for ( i = 0; ; ) + { + unsigned long ul = strtoul( (char *) cp, (char **) &cp, 10 ); - if ( ul > 255 ) // invalid number - return -1; + if ( ul > 0xFFUL ) // invalid number + return MBG_ERR_PARM_FMT; - tmp_ip4_addr |= ul << ( 8 * (3 - i) ); + tmp_ip4_addr |= ul << ( 8 * (3 - i) ); - if ( ++i >= 4 ) - break; // done + if ( ++i >= 4 ) + break; // done - if ( *cp != '.' ) - return -2; // invalid string format, dot expected + if ( *cp != '.' ) + 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 - return cp - s; + return (int) ( cp - s ); } // str_to_ip4_addr @@ -299,22 +327,24 @@ 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. - * - * @param p_addr Pointer to an IP4_ADDR variable for the IP4 address, - * or NULL, in which case this function can be used - * to check if the string is formally correct. - * @param p_mask Pointer to an IP4_ADDR variable for the net mask, - * or NULL, in which case this function can be used - * to check if the string is formally correct. - * @param cidr_str The string to be converted, in CIDR format, e.g. "172.16.3.250/24" - * - * @return >= 0 on success, number of characters evaluated from the input string - * one of the ::MBG_LU_CODES on error - * - * @see snprint_ip4_addr - * @see snprint_ip4_cidr_addr - * @see str_to_ip4_addr + * @brief Convert a string in CIDR notation to an ::IP4_ADDR and net mask + * + * If output parameters are specified as NULL then 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 + * @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" + * + * @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, + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. + * + * @see ::snprint_ip4_addr + * @see ::snprint_ip4_cidr_addr + * @see ::str_to_ip4_addr */ int cidr_str_to_ip4_addr_and_net_mask( IP4_ADDR *p_addr, IP4_ADDR *p_mask, const char *cidr_str ) @@ -325,14 +355,14 @@ int cidr_str_to_ip4_addr_and_net_mask( IP4_ADDR *p_addr, IP4_ADDR *p_mask, int l; int rc = str_to_ip4_addr( p_addr, cidr_str ); - if ( rc < 0 ) // return current error + if ( mbg_rc_is_error( rc ) ) return rc; - l = strlen( cidr_str ); + l = (int) strlen( cidr_str ); if ( l < rc ) // input string too short - return MBG_LU_ERR_FMT; + return MBG_ERR_PARM_FMT; cp = &cidr_str[rc]; @@ -340,14 +370,14 @@ int cidr_str_to_ip4_addr_and_net_mask( IP4_ADDR *p_addr, IP4_ADDR *p_mask, if ( *cp == 0 ) // end of string { // The string has no CIDR extension, so - // assume "/0", i.e. host mask 255.255.255.255; - mask = (IP4_ADDR) -1; + // assume "/0", i.e. host mask 0.0.0.0; + mask = (IP4_ADDR) 0; goto done; } if ( *cp != '/' ) - return MBG_LU_ERR_FMT; + return MBG_ERR_PARM_FMT; cp++; @@ -355,7 +385,7 @@ int cidr_str_to_ip4_addr_and_net_mask( IP4_ADDR *p_addr, IP4_ADDR *p_mask, if ( ( cidr_mask_bits < MIN_IP4_CIDR_NETMASK_BITS ) || ( cidr_mask_bits > MAX_IP4_CIDR_NETMASK_BITS ) ) - return MBG_LU_ERR_RANGE; + return MBG_ERR_RANGE; mask = ip4_net_mask_from_cidr( (int) cidr_mask_bits ); @@ -365,7 +395,7 @@ done: *p_mask = mask; // success: return the number of evaluated chars - return cp - cidr_str; + return (int) ( cp - cidr_str ); } // cidr_str_to_ip4_addr_and_net_mask @@ -373,36 +403,605 @@ done: /*HDR*/ /** - * @brief Print a MAC ID or similar array of octets to a string. + * @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 + * + * @return The number of sequential MSB bits set in *p_mask + * + * @see ::ip6_net_mask_from_cidr + */ +int get_ip6_net_mask_bits( const IP6_ADDR *p_mask ) +{ + int i; + int cnt = 0; + uint8_t msb_mask = IP6_MSB_MASK; + + for ( i = IP6_ADDR_BYTES - 1 ; i >= 0; i-- ) + { + if ( p_mask->b[i] == 0xff ) + cnt += 8; + else + { + for ( ; cnt < MAX_IP6_CIDR_NETMASK_BITS; cnt++ ) + { + if ( ( p_mask->b[i] & msb_mask ) == 0 ) + break; + + msb_mask >>= 1; + } + break; + } + } + + return cnt; + +} // get_ip6_net_mask_bits + + + +/*HDR*/ +/** + * @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 + * + * @return The overall number of characters printed to the string + * + * @see ::snprint_ip6_cidr_addr + * @see ::snprint_ip6_cidr_mask_addr + * @see ::str_to_ip6_addr + * @see ::cidr_str_to_ip6_addr_and_cidr_bits + * @see ::cidr_str_to_ip6_addr_and_net_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 + + IP6_ADDR_STR tmp; + char *tp; + #define NUM_WORDS ( (int) ( sizeof( IP6_ADDR_STR ) / sizeof( uint16_t ) ) ) + uint16_t words[NUM_WORDS] = { 0 }; + int i; + size_t n = 0; + struct + { + int base; + int len; + } best = { 0 }, cur = { 0 }; + + /* + * Preprocess: + * Copy the input (bytewise) array into a wordwise array. + * Find the longest run of 0x00's in p_addr->b[] for :: shorthanding. + */ + for ( i = IP6_ADDR_BYTES - 1; i >= 0; i-- ) + words[(IP6_ADDR_BYTES - 1 - i) / 2] |= (p_addr->b[i] << ((1 - ((IP6_ADDR_BYTES - 1 - i) % 2)) << 3)); + + best.base = -1; + cur.base = -1; + + for ( i = 0; i < NUM_WORDS; i++ ) + { + if ( words[i] == 0 ) + { + if ( cur.base == -1 ) + cur.base = i, cur.len = 1; + else + cur.len++; + } + else + { + if ( cur.base != -1 ) + { + if ( best.base == -1 || cur.len > best.len ) + best = cur; + + cur.base = -1; + } + } + } + + if ( cur.base != -1 ) + { + if ( best.base == -1 || cur.len > best.len ) + best = cur; + } + + if ( best.base != -1 && best.len < 2 ) + best.base = -1; + + // Format the result. + + tp = tmp; + + for ( i = 0; i < NUM_WORDS; i++ ) + { + /* 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) + *tp++ = ':'; + + continue; + } + + /* Are we following an initial run of 0x00s or any real hex? */ + if ( i != 0 ) + *tp++ = ':'; + + /* 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 + + sprintf( tp, "%x", words[i] ); + tp += strlen( tp ); + } + + /* Was it a trailing run of 0x00's? */ + if ( best.base != -1 && ( best.base + best.len ) == NUM_WORDS ) + *tp++ = ':'; + + *tp++ = '\0'; + + /* + * Check for overflow, copy, and we're done. + */ + if ( ( tp - tmp ) > (int) max_len ) + return MBG_ERR_OVERFLOW; + + if ( info ) + n += snprintf_safe( s, max_len, "%s", info ); + + n += snprintf_safe( &s[n], max_len - n, "%s", tmp ); + + return n; + + #undef NUM_WORDS + +} // snprint_ip6_addr + + + +/*HDR*/ +/** + * @brief Print an IPv6 address plus net mask to string in CIDR notation * - * @param s The string buffer into which to print - * @param max_len Maximum length of the string, i.e. size of the buffer - * @param octets An array of octets - * @param num_octets The number of octets to be printed from the array - * @param sep The separator printed between the bytes, or 0 - * @param info An optional string which is prepended to the output, or NULL + * 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 + * + * @return The overall number of characters printed to the string + * + * @see ::snprint_ip6_addr + * @see ::snprint_ip6_cidr_mask_addr + * @see ::str_to_ip6_addr + * @see ::cidr_str_to_ip6_addr_and_cidr_bits + * @see ::cidr_str_to_ip6_addr_and_net_mask + */ +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 ) +{ + size_t n = snprint_ip6_addr( s, max_len, p_addr, info ); + + int cidr_mask_bits = get_ip6_net_mask_bits( p_mask ); + + if ( ( cidr_mask_bits >= MIN_IP6_CIDR_NETMASK_BITS ) && + ( cidr_mask_bits <= MAX_IP6_CIDR_NETMASK_BITS ) ) + n += snprintf_safe( &s[n], max_len - n, "/%i", cidr_mask_bits ); + + return n; + +} // snprint_ip6_cidr_addr + + + +/*HDR*/ +/** + * @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" + * + * @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 + * + * @return The overall number of characters printed to the string + * + * @see ::snprint_ip6_addr + * @see ::snprint_ip6_cidr_addr + * @see ::str_to_ip6_addr + * @see ::cidr_str_to_ip6_addr_and_cidr_bits + * @see ::cidr_str_to_ip6_addr_and_net_mask + */ +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 ) +{ + size_t n; + IP6_ADDR mask; + + ip6_net_mask_from_cidr( &mask, cidr_mask_bits ); + + n = snprint_ip6_addr( s, max_len, p_addr, info ); + + if ( ( cidr_mask_bits >= MIN_IP6_CIDR_NETMASK_BITS ) && + ( cidr_mask_bits <= MAX_IP6_CIDR_NETMASK_BITS ) ) + n += snprintf_safe( &s[n], max_len - n, "/%i", cidr_mask_bits ); + + return n; + +} // snprint_ip6_cidr_mask_addr + + + +/*HDR*/ +/** + * @brief Convert a string to an ::IP6_ADDR + * + * If the output parameter is specified as NULL then 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 + * + * @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, + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. + * + * @see ::snprint_ip6_addr + * @see ::snprint_ip6_cidr_addr + * @see ::snprint_ip6_cidr_mask_addr + * @see ::str_to_ip6_addr + * @see ::cidr_str_to_ip6_addr_and_cidr_bits + * @see ::cidr_str_to_ip6_addr_and_net_mask + */ +int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) +{ + // copied from inet_pton.c and reversed byte order + IP6_ADDR tmp = { { 0 } }; + static const char xdigits[] = "0123456789abcdef"; + uint8_t *tp; + uint8_t *startp; + uint8_t *colonp; + int ch; + int saw_xdigit; + int read_cnt = 0; + unsigned int val; + + if ( p_addr ) + 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. */ + if ( *s == ':' ) + { + read_cnt++; + + if ( *++s != ':' ) + return MBG_ERR_PARM_FMT; + } + + saw_xdigit = 0; + val = 0; + + while ( ( ch = tolower( (int) *s++ ) ) != '\0' ) + { + const char *pch; + + read_cnt++; + + pch = strchr( xdigits, ch ); + + if ( pch != NULL ) + { + val <<= 4; + val |= ( pch - xdigits ); + + if ( val > 0xffff ) //### TODO signed? unsigned? + return MBG_ERR_PARM_FMT; + + saw_xdigit = 1; + continue; + } + + if ( ch == ':' ) + { + if ( !saw_xdigit ) + { + if ( colonp ) + return MBG_ERR_PARM_FMT; + + colonp = tp; + continue; + + } + else + if ( *s == '\0' ) + return MBG_ERR_PARM_FMT; + + if ( tp - sizeof( uint16_t ) < startp ) + return MBG_ERR_PARM_FMT; + + *tp-- = (uint8_t) ( val >> 8 ) & 0xff; + *tp-- = (uint8_t) val & 0xff; + saw_xdigit = 0; + val = 0; + continue; + } + + if ( ch == '/' ) // cidr notation. we reached the end + { + read_cnt--; + break; + } + + return MBG_ERR_PARM_FMT; + } + + if ( saw_xdigit ) + { + if ( tp - sizeof( uint16_t ) < startp ) + return MBG_ERR_PARM_FMT; + + *tp-- = (uint8_t) (val >> 8) & 0xff; + *tp-- = (uint8_t) val & 0xff; + } + + if ( colonp != NULL ) + { + /* + * Since some memmove()'s erroneously fail to handle + * overlapping regions, we'll do the shift by hand. + */ + const size_t n = colonp - tp; + size_t i; + + if ( tp == startp ) + return MBG_ERR_PARM_FMT; + + for ( i = 0; i <= n; i++ ) + { + startp[i] = colonp[i - n]; + colonp[i - n] = 0; + } + + tp = startp; + } + + if ( tp != startp ) + return MBG_ERR_PARM_FMT; + + if ( p_addr ) + *p_addr = tmp; + + return read_cnt; + +} // str_to_ip6_addr + + + +/*HDR*/ +/** + * @brief Convert a string in CIDR notation to an ::IP6_ADDR and net mask + * + * If output parameters are specified as NULL then 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 + * @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" + * + * @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, + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. + * + * @see ::snprint_ip4_addr + * @see ::snprint_ip4_cidr_addr + * @see ::str_to_ip4_addr + */ +int cidr_str_to_ip6_addr_and_net_mask( IP6_ADDR *p_addr, IP6_ADDR *p_mask, const char *cidr_str ) +{ + int mask = 0; + int rc = cidr_str_to_ip6_addr_and_cidr_bits( p_addr, &mask, cidr_str ); + + if ( mbg_rc_is_error( rc ) ) + return rc; + + if ( p_mask ) + ip6_net_mask_from_cidr( p_mask, mask ); + + return rc; + +} // cidr_str_to_ip6_addr_and_net_mask + + + +/*HDR*/ +/** + * @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 + * 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" + * + * @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, + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. + * + * @see ::snprint_ip6_addr + * @see ::snprint_ip6_cidr_addr + * @see ::str_to_ip6_addr + */ +int cidr_str_to_ip6_addr_and_cidr_bits( IP6_ADDR *p_addr, int *p_cidr, + const char *cidr_str ) +{ + long cidr_mask_bits; + const char *cp; + ssize_t l; + int rc = str_to_ip6_addr( p_addr, cidr_str ); + + if ( mbg_rc_is_error( rc ) ) + return rc; + + l = strlen( cidr_str ); + + if ( l < rc ) // input string too short + return MBG_ERR_PARM_FMT; + + cp = &cidr_str[rc]; + + if ( *cp == 0 ) // end of string + { + // The string has no CIDR extension, so + // assume "/0", i.e. host mask :: + cidr_mask_bits = 0; + goto done; + } + + if ( *cp != '/' ) + return MBG_ERR_PARM_FMT; + + cp++; + cidr_mask_bits = strtol( (char *) cp, (char **) &cp, 10 ); + + if ( ( cidr_mask_bits < MIN_IP6_CIDR_NETMASK_BITS ) || + ( cidr_mask_bits > MAX_IP6_CIDR_NETMASK_BITS ) ) + return MBG_ERR_RANGE; + +done: + if ( p_cidr ) + *p_cidr = (int) cidr_mask_bits; + + // success: return the number of evaluated chars + return (int) ( cp - cidr_str ); + +} // cidr_str_to_ip6_addr_and_cidr_bits + + + +/*HDR*/ +/** + * @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 + * + * @see ::get_ip6_net_mask_bits + */ +void ip6_net_mask_from_cidr( IP6_ADDR *p_mask, int netmask_bits ) +{ + int i = 0; + + if ( p_mask ) + { + memset( p_mask, 0, sizeof( *p_mask ) ); + + if ( netmask_bits < 0 ) + netmask_bits = 0; + else + if ( netmask_bits >= IP6_ADDR_BITS ) + netmask_bits = IP6_ADDR_BITS; + + for ( i = IP6_ADDR_BYTES - 1; i >= 0; i-- ) + { + if ( netmask_bits > 8 ) + { + p_mask->b[i] = 0xff; + netmask_bits -= 8; + } + else + { + p_mask->b[i] = (0xff << ( 8 - netmask_bits ) ) & 0xff; + netmask_bits = 0; + } + } + } + +} // ip6_net_mask_from_cidr + + + +/*HDR*/ +/** + * @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 + */ +void ip6_net_part_from_addr( IP6_ADDR *p_net_part, const IP6_ADDR *p_addr, + const IP6_ADDR *p_mask ) +{ + int i; + + for ( i = IP6_ADDR_BYTES; i-- > 0; ) + p_net_part->b[i] = p_addr->b[i] & p_mask->b[i]; + +} // ip6_net_part_from_addr + + + +/*HDR*/ +/** + * @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 * * @return The overall number of characters printed to the string * - * @see snprint_mac_addr - * @see str_to_octets - * @see check_octets_not_all_zero + * @see ::snprint_mac_addr + * @see ::str_to_octets + * @see ::octets_are_all_zero */ -int snprint_octets( char *s, size_t max_len, const uint8_t *octets, - int num_octets, char sep, const char *info ) +size_t snprint_octets( char *s, size_t max_len, const uint8_t *octets, + int num_octets, char sep, const char *info ) { - int n = 0; + size_t n = 0; int i; if ( info ) - n += snprintf( s, max_len, "%s", info ); + n += snprintf_safe( s, max_len, "%s", info ); for ( i = 0; i < num_octets; i++ ) { if ( i && sep ) - n += snprintf( &s[n], max_len - n, "%c", sep ); + n += snprintf_safe( &s[n], max_len - n, "%c", sep ); - n += snprintf( &s[n], max_len - n, "%02X", octets[i] ); + n += snprintf_safe( &s[n], max_len - n, "%02X", octets[i] ); } return n; @@ -413,19 +1012,41 @@ int snprint_octets( char *s, size_t max_len, const uint8_t *octets, /*HDR*/ /** - * @brief Print a MAC address to a string. + * @brief Print a ::PTP_CLOCK_ID to a string + * + * @todo Eventually this function should be moved to a different module. * - * @param s The string buffer into which to print - * @param max_len Maximum length of the string, i.e. size of the buffer - * @param p_mac_addr The MAC address to be printed + * @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 * - * @see snprint_octets - * @see str_to_octets - * @see check_octets_not_all_zero + * @see ::snprint_octets */ -int snprint_mac_addr( char *s, size_t max_len, const MBG_MAC_ADDR *p_mac_addr ) +size_t snprint_ptp_clock_id( char *s, size_t max_len, const PTP_CLOCK_ID *p ) +{ + return snprint_octets( s, max_len, p->b, sizeof( *p ), ':', NULL ); + +} // snprint_ptp_clock_id + + + +/*HDR*/ +/** + * @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 + * + * @return The overall number of characters printed to the string + * + * @see ::snprint_octets + * @see ::str_to_octets + * @see ::octets_are_all_zero + */ +size_t snprint_mac_addr( char *s, size_t max_len, const MBG_MAC_ADDR *p_mac_addr ) { return snprint_octets( s, max_len, p_mac_addr->b, sizeof( *p_mac_addr ), MAC_SEP_CHAR, NULL ); @@ -435,17 +1056,17 @@ int 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 octets An array of octets to be set up - * @param num_octets The number of octets which can be stored - * @param s The string to be converted + * @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 * * @return The overall number of octets decoded from the string * - * @see snprint_octets - * @see snprint_mac_addr - * @see check_octets_not_all_zero + * @see ::snprint_octets + * @see ::snprint_mac_addr + * @see ::octets_are_all_zero */ int str_to_octets( uint8_t *octets, int num_octets, const char *s ) { @@ -475,158 +1096,161 @@ int str_to_octets( uint8_t *octets, int num_octets, const char *s ) /*HDR*/ /** - * @brief Check if an array of octets is valid, i.e. != 0 + * @brief Check if an array of octets is all zero * - * @param octets Pointer to the array of octets - * @param num_octets Number of octets + * @param[in] octets Pointer to the array of octets + * @param[in] num_octets Number of octets * - * @return MBG_LU_SUCCESS octets are valid, i.e. not all 0 - * MBG_LU_ERR_NOT_SET octets are invalid, i.e. all 0 + * @return true if all bytes are 0, else false * - * @see snprint_octets - * @see snprint_mac_addr - * @see str_to_octets + * @see ::snprint_octets + * @see ::snprint_mac_addr + * @see ::str_to_octets */ -int check_octets_not_all_zero( const uint8_t *octets, int num_octets ) +bool octets_are_all_zero( const uint8_t *octets, int num_octets ) { int i; - // check if any of the MAC adddress bytes is != 0 + // check if any of the bytes is != 0 for ( i = 0; i < num_octets; i++ ) if ( octets[i] != 0 ) break; - if ( i == num_octets ) // *all* bytes are 0 - return MBG_LU_ERR_NOT_SET; - - return 0; + return i == num_octets; // true if *all* bytes are 0 -} // check_octets_not_all_zero +} // octets_are_all_zero /*HDR*/ /** - * @brief Check if an array of octets is valid, i.e. != 0 + * @brief Check if a MAC address is all zero * - * @param p_addr Pointer to a MAC address + * @param[in] p_addr Pointer to a MAC address to be checked * - * @return MBG_LU_SUCCESS MAC address is valid, i.e. not all 0 - * MBG_LU_ERR_NOT_SET MAC address is invalid, i.e. all 0 + * @return true if all bytes of the MAC address are 0, else false * - * @see check_octets_not_all_zero + * @see ::octets_are_all_zero */ -int check_mac_addr_not_all_zero( const MBG_MAC_ADDR *p_addr ) +bool mac_addr_is_all_zero( const MBG_MAC_ADDR *p_addr ) { - return check_octets_not_all_zero( p_addr->b, sizeof( p_addr->b ) ); + return octets_are_all_zero( p_addr->b, sizeof( p_addr->b ) ); -} // check_mac_addr_not_all_zero +} // mac_addr_is_all_zero -#if defined( MBG_TGT_UNIX ) +#if defined( MBG_TGT_POSIX ) /*HDR*/ /** * @brief Do a SIOCGxxx IOCTL call to read specific information from a LAN interface * - * @param if_name Name of the interface - * @param ioctl_code One of the predefined system SIOCGxxx IOCTL codes - * @param p_ifreq Pointer to a request buffer + * @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 ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES */ int do_siocg_ioctl( const char *if_name, int ioctl_code, struct ifreq *p_ifreq ) { - int fd; + int sock_fd; int rc; if ( strlen( if_name ) > ( IFNAMSIZ - 1 ) ) - return MBG_LU_ERR_PORT_NAME; + return MBG_ERR_PARM_FMT; - fd = socket( AF_INET, SOCK_DGRAM, 0 ); + sock_fd = socket( AF_INET, SOCK_DGRAM, 0 ); //### TODO: or AF_INET6/PF_INET6 for IPv6 - if ( fd < 0 ) - return MBG_LU_ERR_SOCKET; + if ( sock_fd == -1 ) // failed to open socket + return mbg_get_last_socket_error( "failed to open socket in do_siocg_ioctl" ); - strcpy( p_ifreq->ifr_name, if_name ); + strncpy_safe( p_ifreq->ifr_name, if_name, sizeof( p_ifreq->ifr_name ) ); - rc = ioctl( fd, ioctl_code, p_ifreq ); + rc = ioctl( sock_fd, ioctl_code, p_ifreq ); - if ( rc < 0 ) - rc = MBG_LU_ERR_IOCTL; + 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; - close( fd ); + close( sock_fd ); - return MBG_LU_SUCCESS; + return rc; } // do_siocg_ioctl -#endif // defined( MBG_TGT_UNIX ) +#endif // defined( MBG_TGT_POSIX ) /*HDR*/ /** - * @brief Retrieve the MAC address of a network interface - * - * @param if_name Name of the interface - * @param p_mac_addr Pointer to the MAC address buffer to be filled up + * @brief Retrieve the index of a specific network interface * - * @return one of the ::MBG_LU_CODES - * on error the MAC addr is set to all 0 + * @param[in] if_name Name of the interface + * @param[out] p_intf_idx Pointer to a variable to be filled up * - * @see get_port_mac_addr_check + * @return One of the @ref MBG_RETURN_CODES. + * On error, *p_intf_idx is set to -1. */ -int get_port_mac_addr( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) +int get_port_intf_idx( const char *if_name, int *p_intf_idx ) { - int rc = MBG_LU_ERR_NSUPP; + int rc = MBG_ERR_NOT_SUPP_ON_OS; #if defined( MBG_TGT_LINUX ) struct ifreq ifr = { { { 0 } } }; - rc = do_siocg_ioctl( if_name, SIOCGIFHWADDR, &ifr ); - - if ( rc != MBG_LU_SUCCESS ) - goto fail; - - memcpy( p_mac_addr, ifr.ifr_hwaddr.sa_data, sizeof( *p_mac_addr ) ); - - return rc; + rc = do_siocg_ioctl( if_name, SIOCGIFINDEX, &ifr ); -fail: + if ( mbg_rc_is_success( rc ) ) + { + *p_intf_idx = ifr.ifr_ifindex; + return rc; + } #endif - memset( p_mac_addr, 0, sizeof( *p_mac_addr ) ); + // we get here on error only + *p_intf_idx = -1; return rc; -} // get_port_mac_addr +} // get_port_intf_idx /*HDR*/ /** - * @brief Retrieve and check the MAC address of a network interface - * - * @param if_name Name of the interface - * @param p_mac_addr Pointer to the MAC address buffer to be filled up + * @brief Retrieve the MAC address of a network interface * - * @return one of the ::MBG_LU_CODES - * on error the MAC addr is set to all 0 + * @param[in] if_name Name of the interface + * @param[out] p_mac_addr Pointer to the MAC address buffer to be filled up * - * @see get_port_mac_addr + * @return One of the @ref MBG_RETURN_CODES + * On error, the MAC address is set to all 0 */ -int get_port_mac_addr_check( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) +int get_port_mac_addr( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) { - int rc = get_port_mac_addr( if_name, p_mac_addr ); + int rc = MBG_ERR_NOT_SUPP_ON_OS; + + #if defined( MBG_TGT_LINUX ) + struct ifreq ifr = { { { 0 } } }; - if ( rc == MBG_LU_SUCCESS ) - rc = check_octets_not_all_zero( p_mac_addr->b, sizeof( *p_mac_addr ) ); + rc = do_siocg_ioctl( if_name, SIOCGIFHWADDR, &ifr ); + + if ( mbg_rc_is_success( rc ) ) + { + memcpy( p_mac_addr, ifr.ifr_hwaddr.sa_data, sizeof( *p_mac_addr ) ); + return rc; + } + #endif + + // we get here on error only + memset( p_mac_addr, 0, sizeof( *p_mac_addr ) ); return rc; -} // get_port_mac_addr_check +} // get_port_mac_addr @@ -634,76 +1258,123 @@ int get_port_mac_addr_check( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) /** * @brief Check the link state of a network interface * - * @param if_name Name of the interface + * @param[in] if_name Name of the interface * - * @return 1 link detected on port - * 0 no link detected on port - * one of the ::MBG_LU_CODES in case of an error + * @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 */ int check_port_link( const char *if_name ) { + int rc = MBG_ERR_NOT_SUPP_ON_OS; + #if defined( MBG_TGT_LINUX ) struct ifreq ifr = { { { 0 } } }; struct ethtool_value edata = { 0 }; - int rc; edata.cmd = ETHTOOL_GLINK; // defined in ethtool.h ifr.ifr_data = (caddr_t) &edata; rc = do_siocg_ioctl( if_name, SIOCETHTOOL, &ifr ); - if ( rc == MBG_LU_SUCCESS ) - rc = edata.data != 0; + if ( mbg_rc_is_success( rc ) ) + rc = ( edata.data == 0 ) ? 0 : 1; + #endif - return rc; + return rc; - #else +} // check_port_link + + + +/*HDR*/ +/** + * @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 + * + * @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 + */ +int check_port_status( const char *if_name, int *p_speed, int *p_duplex ) +{ + int rc = MBG_ERR_NOT_SUPP_ON_OS; + + #if defined( MBG_TGT_LINUX ) + struct ifreq ifr = { { { 0 } } }; + struct ethtool_cmd cmd = { 0 }; + int ok; + + ifr.ifr_data = (void *) &cmd; + cmd.cmd = ETHTOOL_GSET; // "Get settings" + + rc = do_siocg_ioctl( if_name, SIOCETHTOOL, &ifr ); + + ok = mbg_rc_is_success( rc ); + + if ( p_speed ) + { + #if defined( ETH_TEST_FL_EXTERNAL_LB_DONE ) + // ethtool_cmd_speed() is only provided by kernels ~3.7-rc1 and + // newer, which should also define ETH_TEST_FL_EXTERNAL_LB_DONE. + // The function assembles a 32 bit value from two 16 bit fields. + *p_speed = ok ? ethtool_cmd_speed( &cmd ) : 0; // [MHz] + #else + // Older kernels only provide a single 16 bit 'speed' field. + *p_speed = ok ? cmd.speed : 0; // [MHz] + #endif + } - return MBG_LU_ERR_NSUPP; + if ( p_duplex ) + *p_duplex = ok ? cmd.duplex : -1; // 0x00 == half, 0x01 == full #endif -} // check_port_link + return rc; + +} // check_port_status static /*HDR*/ /** - * @brief Retrieve some IPv4 address like info from a network interface - * - * @param if_name Name of the interface - * @param p_addr Pointer to address field to be filled up - * @param sigioc_code the ioctl code associated to the address - * - * @return one of the ::MBG_LU_CODES - * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str + * @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 + * + * @return One of the @ref MBG_RETURN_CODES + * On error, *p_addr is set to all 0. + * + * @see ::get_port_ip4_settings + * @see ::get_port_ip4_addr + * @see ::get_port_ip4_addr_str + * @see ::get_port_ip4_netmask + * @see ::get_port_ip4_netmask_str + * @see ::get_port_ip4_broad_addr + * @see ::get_port_ip4_broad_addr_str */ int get_specific_port_ip4_addr( const char *if_name, IP4_ADDR *p_addr, int sigioc_code ) { - int rc = MBG_LU_ERR_NSUPP; + int rc = MBG_ERR_NOT_SUPP_ON_OS; #if defined( MBG_TGT_LINUX ) struct ifreq ifr = { { { 0 } } }; rc = do_siocg_ioctl( if_name, sigioc_code, &ifr ); - if ( rc != MBG_LU_SUCCESS ) - goto fail; - - *p_addr = ntohl( ( (struct sockaddr_in *) &ifr.ifr_addr )->sin_addr.s_addr ); - - return rc; - -fail: + if ( mbg_rc_is_success( rc ) ) + { + *p_addr = ntohl( ( (struct sockaddr_in *) &ifr.ifr_addr )->sin_addr.s_addr ); + return rc; + } #endif + // we get here on error only *p_addr = 0; // make empty address return rc; @@ -716,18 +1387,19 @@ fail: /** * @brief Retrieve the IPv4 address of a network interface * - * @param if_name Name of the interface - * @param p_addr Pointer to address field to be filled up + * @param[in] if_name Name of the interface + * @param[out] p_addr Pointer to address field to be filled up * - * @return one of the ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES + * On error, *p_addr is set to all 0. * - * @see get_port_ip4_settings - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr + * @see ::get_port_ip4_settings + * @see ::get_port_ip4_addr_str + * @see ::get_port_ip4_netmask + * @see ::get_port_ip4_netmask_str + * @see ::get_port_ip4_broad_addr + * @see ::get_port_ip4_broad_addr_str + * @see ::get_specific_port_ip4_addr */ int get_port_ip4_addr( const char *if_name, IP4_ADDR *p_addr ) { @@ -741,18 +1413,19 @@ int get_port_ip4_addr( const char *if_name, IP4_ADDR *p_addr ) /** * @brief Retrieve the IPv4 net mask of a network interface * - * @param if_name Name of the interface - * @param p_addr Pointer to address field to be filled up + * @param[in] if_name Name of the interface + * @param[out] p_addr Pointer to address field to be filled up * - * @return one of the ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES + * On error, *p_addr is set to all 0. * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr + * @see ::get_port_ip4_settings + * @see ::get_port_ip4_addr + * @see ::get_port_ip4_addr_str + * @see ::get_port_ip4_netmask_str + * @see ::get_port_ip4_broad_addr + * @see ::get_port_ip4_broad_addr_str + * @see ::get_specific_port_ip4_addr */ int get_port_ip4_netmask( const char *if_name, IP4_ADDR *p_addr ) { @@ -766,18 +1439,19 @@ int get_port_ip4_netmask( const char *if_name, IP4_ADDR *p_addr ) /** * @brief Retrieve the IPv4 broadcast address of a network interface * - * @param if_name Name of the interface - * @param p_addr Pointer to address field to be filled up + * @param[in] if_name Name of the interface + * @param[out] p_addr Pointer to address field to be filled up * - * @return one of the ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES + * On error, *p_addr is set to all 0. * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr + * @see ::get_port_ip4_settings + * @see ::get_port_ip4_addr + * @see ::get_port_ip4_addr_str + * @see ::get_port_ip4_netmask + * @see ::get_port_ip4_netmask_str + * @see ::get_port_ip4_broad_addr_str + * @see ::get_specific_port_ip4_addr */ int get_port_ip4_broad_addr( const char *if_name, IP4_ADDR *p_addr ) { @@ -792,39 +1466,42 @@ int get_port_ip4_broad_addr( const char *if_name, IP4_ADDR *p_addr ) static /*HDR*/ /** * @brief Read a requested message from the netlink socket + * + * @return Message length (>= 0) on success, or of the @ref MBG_ERROR_CODES */ -int readNlSock( int sockFd, char *bufPtr, size_t buf_size, int seqNum, int pId ) +int nl_read( int sock_fd, char *buf_ptr, size_t buf_size, int seq_num, int pid ) { - struct nlmsghdr *nlHdr; - int readLen = 0; - int msgLen = 0; + struct nlmsghdr *nl_hdr; + int read_len = 0; + int msg_len = 0; do { // receive response from the kernel, can be several chunks - if ( ( readLen = recv( sockFd, bufPtr, buf_size - msgLen, 0 ) ) < 0 ) + if ( ( read_len = recv( sock_fd, buf_ptr, buf_size - msg_len, 0 ) ) == -1 ) { + int rc = mbg_get_last_socket_error( NULL ); #if DEBUG_NETLINK mbglog( LOG_ERR, "%s: Failed to receive netlink packet: %s", - __func__, strerror( errno ) ); + __func__, mbg_strerror( rc ) ); #endif - return -1; + return rc; } - nlHdr = (struct nlmsghdr *) bufPtr; + nl_hdr = (struct nlmsghdr *) buf_ptr; // check if the header is valid - if ( ( NLMSG_OK( nlHdr, readLen ) == 0 ) || ( nlHdr->nlmsg_type == NLMSG_ERROR ) ) + if ( ( NLMSG_OK( nl_hdr, read_len ) == 0 ) || ( nl_hdr->nlmsg_type == NLMSG_ERROR ) ) { #if DEBUG_NETLINK mbglog( LOG_ERR, "%s: Invalid header in received netlink packet", __func__ ); #endif - return -1; + return MBG_ERR_DATA_FMT; } // check if the its the last message - if ( nlHdr->nlmsg_type == NLMSG_DONE ) + if ( nl_hdr->nlmsg_type == NLMSG_DONE ) { #if DEBUG_NETLINK mbglog( LOG_ERR, "%s: Reached last message in received packet", @@ -834,11 +1511,11 @@ int readNlSock( int sockFd, char *bufPtr, size_t buf_size, int seqNum, int pId ) } // move the pointer to buffer appropriately - bufPtr += readLen; - msgLen += readLen; + buf_ptr += read_len; + msg_len += read_len; // check if its a multi part message - if ( ( nlHdr->nlmsg_flags & NLM_F_MULTI ) == 0 ) + if ( ( nl_hdr->nlmsg_flags & NLM_F_MULTI ) == 0 ) { // return if it's not a multi part message #if DEBUG_NETLINK @@ -848,110 +1525,110 @@ int readNlSock( int sockFd, char *bufPtr, size_t buf_size, int seqNum, int pId ) break; } - } while ( ( nlHdr->nlmsg_seq != seqNum ) || ( nlHdr->nlmsg_pid != pId ) ); + } while ( ( nl_hdr->nlmsg_seq != seq_num ) || ( nl_hdr->nlmsg_pid != pid ) ); #if DEBUG_NETLINK mbglog( LOG_ERR, "%s: Received packet has len %i", - __func__, msgLen ); + __func__, msg_len ); #endif - return msgLen; + return msg_len; -} // readNlSock +} // nl_read #if DEBUG_NETLINK static /*HDR*/ -void log_netlink_bytes( const char *fnc, const char *info, const void *p, int n_bytes ) +void nl_log_bytes( const char *fnc, const char *info, const void *p, int n_bytes ) { char ws[80]; - int n = 0; + size_t n = 0; int i; for ( i = 0; i < n_bytes; i++ ) - n += snprintf( &ws[n], sizeof( ws ) - n, " %i", BYTE_OF( *p, i ) ); + n += snprintf_safe( &ws[n], sizeof( ws ) - n, " %i", BYTE_OF( * (uint8_t *) p, i ) ); mbglog( LOG_INFO, "%s: attibute %s, copying %i bytes:%s", fnc, info, n_bytes, ws ); -} // log_netlink_bytes +} // nl_log_bytes #endif static /*HDR*/ -int parseRoutes( struct nlmsghdr *nlHdr, struct route_info *rtInfo ) +int nl_parse_routes( struct nlmsghdr *nl_hdr, struct route_info *rt_info ) { // parse the route info returned - struct rtmsg *rtMsg; - struct rtattr *rtAttr; - int rtLen; + struct rtmsg *rt_msg; + struct rtattr *rt_attr; + int rt_len; - rtMsg = (struct rtmsg *) NLMSG_DATA( nlHdr ); + rt_msg = (struct rtmsg *) NLMSG_DATA( nl_hdr ); // If the route is not for AF_INET then return. // This could be also IPv6 routes. - if ( rtMsg->rtm_family != AF_INET ) + 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", - __func__, (long) AF_INET, (long) rtMsg->rtm_family ); + __func__, (long) AF_INET, (long) rt_msg->rtm_family ); #endif return -1; } // If the route does not belong to main routing table then return. - if ( rtMsg->rtm_table != RT_TABLE_MAIN ) + if ( rt_msg->rtm_table != RT_TABLE_MAIN ) { #if DEBUG_NETLINK mbglog( LOG_ERR, "%s: Route does not belong to main table (%li), but %li", - __func__, (long) RT_TABLE_MAIN, (long) rtMsg->rtm_table ); + __func__, (long) RT_TABLE_MAIN, (long) rt_msg->rtm_table ); #endif return -1; } // get the rtattr field - rtAttr = (struct rtattr *) RTM_RTA( rtMsg ); - rtLen = RTM_PAYLOAD( nlHdr ); + rt_attr = (struct rtattr *) RTM_RTA( rt_msg ); + rt_len = RTM_PAYLOAD( nl_hdr ); - for ( ; RTA_OK( rtAttr, rtLen ); rtAttr = RTA_NEXT( rtAttr, rtLen ) ) + for ( ; RTA_OK( rt_attr, rt_len ); rt_attr = RTA_NEXT( rt_attr, rt_len ) ) { #if DEBUG_NETLINK - mbglog( LOG_ERR, "rtAttr at %p, %i bytes left", rtAttr, rtLen ); + mbglog( LOG_ERR, "rt_attr at %p, %i bytes left", rt_attr, rt_len ); #endif - switch ( rtAttr->rta_type ) + switch ( rt_attr->rta_type ) { case RTA_OIF: - if_indextoname( *(int *)RTA_DATA( rtAttr ), rtInfo->ifName ); + if_indextoname( *(int *)RTA_DATA( rt_attr ), rt_info->ifName ); #if DEBUG_NETLINK mbglog( LOG_ERR, "%s: attibute RTA_OIF, IF name: %s", - __func__, rtInfo->ifName ); + __func__, rt_info->ifName ); #endif break; case RTA_GATEWAY: - memcpy( &rtInfo->gateWay, RTA_DATA( rtAttr ), sizeof( rtInfo->gateWay ) ); + memcpy( &rt_info->gateWay, RTA_DATA( rt_attr ), sizeof( rt_info->gateWay ) ); #if DEBUG_NETLINK - log_netlink_bytes( __func__, "RTA_GATEWAY", &rtInfo->gateWay, sizeof( rtInfo->gateWay ) ); + nl_log_bytes( __func__, "RTA_GATEWAY", &rt_info->gateWay, sizeof( rt_info->gateWay ) ); #endif break; case RTA_PREFSRC: - memcpy( &rtInfo->srcAddr , RTA_DATA( rtAttr ), sizeof( rtInfo->srcAddr ) ); + memcpy( &rt_info->srcAddr , RTA_DATA( rt_attr ), sizeof( rt_info->srcAddr ) ); #if DEBUG_NETLINK - log_netlink_bytes( __func__, "RTA_PREFSRC", &rtInfo->srcAddr, sizeof( rtInfo->srcAddr ) ); + nl_log_bytes( __func__, "RTA_PREFSRC", &rt_info->srcAddr, sizeof( rt_info->srcAddr ) ); #endif break; case RTA_DST: - memcpy( &rtInfo->dstAddr, RTA_DATA( rtAttr ), sizeof( rtInfo->dstAddr ) ); + memcpy( &rt_info->dstAddr, RTA_DATA( rt_attr ), sizeof( rt_info->dstAddr ) ); #if DEBUG_NETLINK - log_netlink_bytes( __func__, "RTA_DST", &rtInfo->dstAddr, sizeof( rtInfo->dstAddr ) ); + nl_log_bytes( __func__, "RTA_DST", &rt_info->dstAddr, sizeof( rt_info->dstAddr ) ); #endif break; @@ -969,22 +1646,22 @@ int parseRoutes( struct nlmsghdr *nlHdr, struct route_info *rtInfo ) // used by the compiler. Unfortunately RTA_TABLE is part of an enum, so you // can't simply use #ifdef RTA_TABLE to include this code conditionally. uint32_t rta_table; - memcpy( &rta_table, RTA_DATA( rtAttr ), sizeof( rta_table ) ); + memcpy( &rta_table, RTA_DATA( rt_attr ), sizeof( rta_table ) ); mbglog( LOG_ERR, "%s: attibute RTA_TABLE %i (%i)", - __func__, rta_table, rtMsg->rtm_table ); + __func__, rta_table, rt_msg->rtm_table ); } break; default: mbglog( LOG_ERR, "%s: Found unknown route type %li", - __func__, (long) rtAttr->rta_type ); + __func__, (long) rt_attr->rta_type ); #endif } } return 0; -} // parseRoutes +} // nl_parse_routes #endif // defined( MBG_TGT_LINUX ) @@ -994,87 +1671,87 @@ int parseRoutes( struct nlmsghdr *nlHdr, struct route_info *rtInfo ) /** * @brief Retrieve the IPv4 gateway (default route) * - * @param 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 ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES + * On error, *p_addr is set to all 0. */ int get_ip4_gateway( IP4_ADDR *p_addr ) { - int ret_val = MBG_LU_ERR_NOT_SET; + int rc = MBG_ERR_NOT_SUPP_ON_OS; #if defined( MBG_TGT_LINUX ) - struct nlmsghdr *nlMsg; + struct nlmsghdr *nlmsg; struct route_info route_info; - char msgBuf[8192]; // pretty large buffer - - int sock; + char msg_buf[8192]; // pretty large buffer, why 8192 ? + int sock_fd; int len; - int msgSeq = 0; + int msg_seq = 0; int idx; // create socket - if ( ( sock = socket( PF_NETLINK, SOCK_DGRAM, NETLINK_ROUTE ) ) < 0 ) + if ( ( sock_fd = socket( PF_NETLINK, SOCK_DGRAM, NETLINK_ROUTE ) ) == -1 ) { + rc = mbg_get_last_socket_error( NULL ); #if DEBUG_NETLINK mbglog( LOG_ERR, "%s: Failed to create netlink socket: %s", - __func__, strerror( errno ) ); + __func__, mbg_strerror( rc ) ); #endif - ret_val = MBG_LU_ERR_SOCKET; goto out; } - // initialize the buffer - memset( msgBuf, 0, sizeof( msgBuf ) ); + // initialize buffer with request message + memset( msg_buf, 0, sizeof( msg_buf ) ); // point the header and the msg structure pointers into the buffer - nlMsg = (struct nlmsghdr *) msgBuf; + 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 + 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 = msgSeq++; // 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 - if ( send( sock, nlMsg, nlMsg->nlmsg_len, 0 ) < 0 ) + if ( send( sock_fd, nlmsg, nlmsg->nlmsg_len, 0 ) == -1 ) { + rc = mbg_get_last_socket_error( NULL ); #if DEBUG_NETLINK mbglog( LOG_ERR, "%s: Failed to write to netlink socket: %s", - __func__, strerror( errno ) ); + __func__, mbg_strerror( rc ) ); #endif - ret_val = -1; goto out; } // read the response - if ( ( len = readNlSock( sock, msgBuf, sizeof( msgBuf ), msgSeq, getpid() ) ) < 0 ) + if ( ( len = nl_read( sock_fd, msg_buf, sizeof( msg_buf ), msg_seq, getpid() ) ) < 0 ) { #if DEBUG_NETLINK mbglog( LOG_ERR, "%s: Failed to read from netlink socket", __func__ ); #endif - ret_val = -1; + rc = len; goto out; } #if DEBUG_NETLINK - mbglog( LOG_ERR, "%s: Read %i bytes from netlink socket", __func__ ); + mbglog( LOG_ERR, "%s: Read %i bytes from netlink socket", __func__, len ); #endif // parse and print the response - for ( idx = 0; NLMSG_OK( nlMsg, len ); nlMsg = NLMSG_NEXT( nlMsg, len ), idx ++ ) + for ( idx = 0; NLMSG_OK( nlmsg, len ); nlmsg = NLMSG_NEXT( nlmsg, len ), idx++ ) { memset( &route_info, 0, sizeof( route_info ) ); #if DEBUG_NETLINK - mbglog( LOG_ERR, "\nnlMsg at %p, %i bytes left", nlMsg, len ); + mbglog( LOG_ERR, "\nnl_msg at %p, %i bytes left", nlmsg, len ); #endif - if ( parseRoutes( nlMsg, &route_info ) < 0 ) + if ( nl_parse_routes( nlmsg, &route_info ) < 0 ) continue; // don't check route_info if it has not been set up #if DEBUG_NETLINK @@ -1084,9 +1761,10 @@ int get_ip4_gateway( IP4_ADDR *p_addr ) int n = 0; // inet_ntoa() uses a static buffer which is overwritten on every call - n += snprintf( &ws[n], l - n, "src %s", (char *) inet_ntoa( route_info.srcAddr ) ); - n += snprintf( &ws[n], l - n, ", dst %s", (char *) inet_ntoa( route_info.dstAddr ) ); - n += snprintf( &ws[n], l - n, ", gw %s", (char *) inet_ntoa( route_info.gateWay ) ); + //##++ 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 ) ); mbglog( LOG_ERR, "%s: route %i: %s, if \"%s\"", __func__, idx, ws, route_info.ifName ); @@ -1094,13 +1772,15 @@ 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 if ( strstr( (char *) inet_ntoa( route_info.dstAddr ), "0.0.0.0" ) ) { *p_addr = ntohl( route_info.gateWay.s_addr ); - ret_val = MBG_LU_SUCCESS; + rc = MBG_SUCCESS; // 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 mbglog( LOG_ERR, "%s: Default gateway found: %s", __func__, (char *) inet_ntoa( route_info.gateWay ) ); #else @@ -1110,16 +1790,15 @@ int get_ip4_gateway( IP4_ADDR *p_addr ) } out: - if ( sock >= 0 ) - close( sock ); + if ( sock_fd >= 0 ) + close( sock_fd ); #endif // defined( MBG_TGT_LINUX ) - - if ( ret_val != MBG_LU_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) *p_addr = 0; - return ret_val; + return rc; } // get_ip4_gateway @@ -1129,19 +1808,20 @@ out: /** * @brief Retrieve the IPv4 address of a network interface as string * - * @param if_name Name of the interface - * @param p_addr_buf Pointer to the string buffer to be filled up - * @param buf_size size of the string buffer + * @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 ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES + * On error, a string according to "0.0.0.0" is generated. * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr + * @see ::get_port_ip4_settings + * @see ::get_port_ip4_addr + * @see ::get_port_ip4_netmask + * @see ::get_port_ip4_netmask_str + * @see ::get_port_ip4_broad_addr + * @see ::get_port_ip4_broad_addr_str + * @see ::get_specific_port_ip4_addr */ int get_port_ip4_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) { @@ -1161,19 +1841,20 @@ int get_port_ip4_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) /** * @brief Retrieve the IPv4 net mask of a network interface as string * - * @param if_name Name of the interface - * @param p_addr_buf Pointer to the string buffer to be filled up - * @param buf_size size of the string buffer + * @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 ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES + * On error, a string according to "0.0.0.0" is generated. * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr + * @see ::get_port_ip4_settings + * @see ::get_port_ip4_addr + * @see ::get_port_ip4_addr_str + * @see ::get_port_ip4_netmask + * @see ::get_port_ip4_broad_addr + * @see ::get_port_ip4_broad_addr_str + * @see ::get_specific_port_ip4_addr */ int get_port_ip4_netmask_str( const char *if_name, char *p_addr_buf, int buf_size ) { @@ -1193,19 +1874,20 @@ int get_port_ip4_netmask_str( const char *if_name, char *p_addr_buf, int buf_siz /** * @brief Retrieve the IPv4 broadcast address of a network interface as string * - * @param if_name Name of the interface - * @param p_addr_buf Pointer to the string buffer to be filled up - * @param buf_size size of the string buffer + * @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 ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES + * On error, a string according to "0.0.0.0" is generated. * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_specific_port_ip4_addr + * @see ::get_port_ip4_settings + * @see ::get_port_ip4_addr + * @see ::get_port_ip4_addr_str + * @see ::get_port_ip4_netmask + * @see ::get_port_ip4_netmask_str + * @see ::get_port_ip4_broad_addr + * @see ::get_specific_port_ip4_addr */ int get_port_ip4_broad_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) { @@ -1225,45 +1907,52 @@ int get_port_ip4_broad_addr_str( const char *if_name, char *p_addr_buf, int buf_ /** * @brief Retrieve the current IPv4 settings of a network interface * - * @param if_name Name of the interface - * @param p Pointer to a IP4_SETTINGS structure to be filled up + * @param[in] if_name Name of the interface + * @param[out] p Pointer to a IP4_SETTINGS structure to be filled up * - * @return 0 on success, < 0 on error + * @return One of the @ref MBG_RETURN_CODES * - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr + * @see ::get_port_ip4_addr + * @see ::get_port_ip4_addr_str + * @see ::get_port_ip4_netmask + * @see ::get_port_ip4_netmask_str + * @see ::get_port_ip4_broad_addr + * @see ::get_port_ip4_broad_addr_str + * @see ::get_specific_port_ip4_addr */ int get_port_ip4_settings( const char *if_name, IP4_SETTINGS *p ) { int link_up; - int ret_val = 0; + int rc; memset( p, 0, sizeof( *p ) ); - if ( get_port_ip4_addr( if_name, &p->ip_addr ) ) - ret_val = -1; + rc = get_port_ip4_addr( if_name, &p->ip_addr ); - if ( get_port_ip4_netmask( if_name, &p->netmask ) ) - ret_val = -1; + if ( mbg_rc_is_error( rc ) ) + goto out; - if ( get_port_ip4_broad_addr( if_name, &p->broad_addr ) ) - ret_val = -1; - if ( get_ip4_gateway( &p->gateway ) ) - ret_val = -1; + rc = get_port_ip4_netmask( if_name, &p->netmask ); + if ( mbg_rc_is_error( rc ) ) + goto out; - link_up = check_port_link( if_name ); - if ( link_up ) - p->flags |= IP4_MSK_LINK; + rc = get_port_ip4_broad_addr( if_name, &p->broad_addr ); + + if ( mbg_rc_is_error( rc ) ) + goto out; + + +#ifndef USE_MBG_TSU + rc = get_ip4_gateway( &p->gateway ); -#if 0 //##+++++ + if ( mbg_rc_is_error( rc ) ) + goto out; +#endif + +#if 0 //### TODO // We could also try to check VLAN and DHCP settings here, // but as of now, this is specific to an application. @@ -1281,7 +1970,15 @@ int get_port_ip4_settings( const char *if_name, IP4_SETTINGS *p ) p->flags |= IP4_MSK_DHCP; #endif - return ret_val; +out: + + // Check linkup independent from success of getting IP4 parameters + link_up = check_port_link( if_name ); + + if ( link_up ) + p->flags |= IP4_MSK_LINK; + + return rc; } // get_port_ip4_settings diff --git a/mbglib/common/lan_util.h b/mbglib/common/lan_util.h index d3e39a5..474a8a3 100644 --- a/mbglib/common/lan_util.h +++ b/mbglib/common/lan_util.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: lan_util.h 1.4 2013/02/19 15:15:53Z martin REL_M $ + * $Id: lan_util.h 1.9 2018/02/28 16:55:31Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,20 @@ * * ----------------------------------------------------------------------- * $Log: lan_util.h $ - * Revision 1.4 2013/02/19 15:15:53Z martin + * Revision 1.9 2018/02/28 16:55:31Z martin + * Updated function prototypes. + * Revision 1.8 2017/10/05 08:20:40 daniel + * Introduced check_port_status() function + * Revision 1.7 2017/07/05 14:10:58 martin + * Some definitions used with IPv6 added by hannes. + * Removed definitions of old MBG_LU_... return codes. + * Standard MBG_RETURN_CODES are now used instead. + * Updated function prototypes. + * Revision 1.6 2014/09/24 08:32:58 martin + * Fixed a POSIX header file dependency. + * Revision 1.5 2013/10/02 07:20:36 martin + * Updated function prototypes. + * Revision 1.4 2013/02/19 15:15:53 martin * Added some inline functions. * Redefined return codes as named enum. * Updated function prototypes. @@ -30,14 +43,15 @@ /* Other headers to be included */ #include <mbg_tgt.h> -#include <gpsdefs.h> +#include <gpsdefs.h> // for some Meinberg data structures #include <stdlib.h> -#if defined( MBG_TGT_UNIX ) +#if defined( MBG_TGT_POSIX ) #include <sys/types.h> #include <sys/socket.h> #include <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. @@ -85,24 +99,7 @@ extern "C" { #endif -/** - * @brief Return codes for the LAN utility functions - */ -enum MBG_LU_CODES -{ - MBG_LU_SUCCESS = 0, ///< success - MBG_LU_ERR_NSUPP = -1, ///< function not supported - MBG_LU_ERR_PORT_NAME = -2, ///< port name exceeds max length - MBG_LU_ERR_SOCKET = -3, ///< failed to open socket - MBG_LU_ERR_IOCTL = -4, ///< IOCTL call failed - MBG_LU_ERR_NOT_SET = -5, ///< octets are all 0 - MBG_LU_ERR_BUFF_SZ = -6, ///< buffer size too small - MBG_LU_ERR_FMT = -7, ///< parameter format not correct - MBG_LU_ERR_RANGE = -8 ///< range for some parameter exceeded -}; - - -#define MAX_IP4_BITS ( 8 * sizeof( IP4_ADDR ) ) +#define MAX_IP4_BITS ( 8 * (int) sizeof( IP4_ADDR ) ) #define IP4_MSB_MASK ( 1UL << ( MAX_IP4_BITS - 1 ) ) @@ -110,6 +107,12 @@ enum MBG_LU_CODES #define MAX_IP4_CIDR_NETMASK_BITS MAX_IP4_BITS +#define IP6_MSB_MASK ( 1UL << ( 8 - 1 ) ) + +#define MIN_IP6_CIDR_NETMASK_BITS 0 +#define MAX_IP6_CIDR_NETMASK_BITS IP6_ADDR_BITS + + /** * @brief Compute an IP4 net mask according to the number of CIDR netmask bits @@ -119,7 +122,7 @@ enum MBG_LU_CODES * * @param netmask_bits Number of netmask bits from CIDR notation * - * @return The IP4 net mask + * @return The IPv4 net mask * * @see get_ip4_net_mask_bits() */ @@ -202,357 +205,553 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, -/* function prototypes: */ - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ /** - * @brief Count the number of sequential bits set starting from MSB + * @brief Count the number of sequential bits in an IPv4 net mask * - * E.g. for 0xC0 and 0xC1 the results are both 2 since only - * the 2 MSBs are sequentially set. + * Counting starts from MSB, i.e. for 0xC0 and 0xC1 the results + * are both 2 since only the 2 MSBs are sequentially set. * - * @param p_mask The IP4 net mask + * @param[in] p_mask The IPv4 net mask to be evaluated * - * @return The number of sequential MSB bits set in val + * @return The number of sequential MSB bits set in *p_mask * - * @see ip4_net_mask_from_cidr + * @see ::ip4_net_mask_from_cidr */ int get_ip4_net_mask_bits( const IP4_ADDR *p_mask ) ; /** - * @brief Print an IPv4 address to a dotted quad format string. + * @brief Print an IPv4 address to a dotted quad formatted string * - * @param s The string buffer into which to print - * @param max_len Maximum length of the string, i.e. size of the buffer - * @param p_addr The IPv4 address - * @param info An optional string which is prepended to the string, or NULL + * @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 * * @return The overall number of characters printed to the string * - * @see snprint_ip4_cidr_addr - * @see str_to_ip4_addr - * @see cidr_str_to_ip4_addr_and_net_mask + * @see ::snprint_ip4_cidr_addr + * @see ::str_to_ip4_addr + * @see ::cidr_str_to_ip4_addr_and_net_mask */ - int snprint_ip4_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, const char *info ) ; + 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 to string in CIDR notation. + * @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 s The string buffer into which to print - * @param max_len Maximum length of the string, i.e. size of the buffer - * @param p_addr The IPv4 address - * @param p_mask The IPv4 net mask - * @param info An optional string which is prepended to the string, or NULL + * @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 * * @return The overall number of characters printed to the string * - * @see snprint_ip4_addr - * @see str_to_ip4_addr - * @see cidr_str_to_ip4_addr_and_net_mask + * @see ::snprint_ip4_addr + * @see ::str_to_ip4_addr + * @see ::cidr_str_to_ip4_addr_and_net_mask */ - int snprint_ip4_cidr_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, const IP4_ADDR *p_mask, const char *info ) ; + 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 * - * @param p_addr Pointer to the IP4_ADDR variable, or NULL, in which case this - * function can be used to check if the string is formally correct. - * @param s The string to be converted + * If output parameter is specified as NULL then this function + * can be used to check if the IPv4 address string is formally correct. * - * @return >= 0 on success, number of characters evaluated from the input string - * -1 if invalid number found in string - * -2 if separator is not a dot '.' + * @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 * - * @see snprint_ip4_addr - * @see snprint_ip4_cidr_addr - * @see cidr_str_to_ip4_addr_and_net_mask + * @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, + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. + * + * @see ::snprint_ip4_addr + * @see ::snprint_ip4_cidr_addr + * @see ::cidr_str_to_ip4_addr_and_net_mask */ int str_to_ip4_addr( IP4_ADDR *p_addr, const char *s ) ; /** - * @brief Convert a string in CIDR notation to an IP4_ADDR and net mask. + * @brief Convert a string in CIDR notation to an ::IP4_ADDR and net mask + * + * If output parameters are specified as NULL then this function + * can be used to check if the CIDR string is formally correct. * - * @param p_addr Pointer to an IP4_ADDR variable for the IP4 address, - * or NULL, in which case this function can be used - * to check if the string is formally correct. - * @param p_mask Pointer to an IP4_ADDR variable for the net mask, - * or NULL, in which case this function can be used - * to check if the string is formally correct. - * @param cidr_str The string to be converted, in CIDR format, e.g. "172.16.3.250/24" + * @param[out] p_addr Pointer to an ::IP4_ADDR variable to be filled with + * the IPv4 address, or 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" * - * @return >= 0 on success, number of characters evaluated from the input string - * one of the ::MBG_LU_CODES on error + * @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, + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. * - * @see snprint_ip4_addr - * @see snprint_ip4_cidr_addr - * @see str_to_ip4_addr + * @see ::snprint_ip4_addr + * @see ::snprint_ip4_cidr_addr + * @see ::str_to_ip4_addr */ int cidr_str_to_ip4_addr_and_net_mask( IP4_ADDR *p_addr, IP4_ADDR *p_mask, const char *cidr_str ) ; /** - * @brief Print a MAC ID or similar array of octets to a string. + * @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 + * + * @return The number of sequential MSB bits set in *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 * - * @param s The string buffer into which to print - * @param max_len Maximum length of the string, i.e. size of the buffer - * @param octets An array of octets - * @param num_octets The number of octets to be printed from the array - * @param sep The separator printed between the bytes, or 0 - * @param info An optional string which is prepended to the output, or NULL + * @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 + * + * @return The overall number of characters printed to the string + * + * @see ::snprint_ip6_cidr_addr + * @see ::snprint_ip6_cidr_mask_addr + * @see ::str_to_ip6_addr + * @see ::cidr_str_to_ip6_addr_and_cidr_bits + * @see ::cidr_str_to_ip6_addr_and_net_mask + */ + 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 + * + * 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 + * + * @return The overall number of characters printed to the string + * + * @see ::snprint_ip6_addr + * @see ::snprint_ip6_cidr_mask_addr + * @see ::str_to_ip6_addr + * @see ::cidr_str_to_ip6_addr_and_cidr_bits + * @see ::cidr_str_to_ip6_addr_and_net_mask + */ + 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 + * + * 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 + * + * @return The overall number of characters printed to the string + * + * @see ::snprint_ip6_addr + * @see ::snprint_ip6_cidr_addr + * @see ::str_to_ip6_addr + * @see ::cidr_str_to_ip6_addr_and_cidr_bits + * @see ::cidr_str_to_ip6_addr_and_net_mask + */ + 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 + * + * If the output parameter is specified as NULL then 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 + * + * @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, + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. + * + * @see ::snprint_ip6_addr + * @see ::snprint_ip6_cidr_addr + * @see ::snprint_ip6_cidr_mask_addr + * @see ::str_to_ip6_addr + * @see ::cidr_str_to_ip6_addr_and_cidr_bits + * @see ::cidr_str_to_ip6_addr_and_net_mask + */ + 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 + * + * If output parameters are specified as NULL then 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 + * @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" + * + * @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, + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. + * + * @see ::snprint_ip4_addr + * @see ::snprint_ip4_cidr_addr + * @see ::str_to_ip4_addr + */ + 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 + * + * If output parameters are specified as NULL then 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" + * + * @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, + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. + * + * @see ::snprint_ip6_addr + * @see ::snprint_ip6_cidr_addr + * @see ::str_to_ip6_addr + */ + 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 + * + * 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 + * + * @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 + * + * 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 + */ + 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 + * + * @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 + * + * @return The overall number of characters printed to the string + * + * @see ::snprint_mac_addr + * @see ::str_to_octets + * @see ::octets_are_all_zero + */ + 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 + * + * @todo Eventually 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 * * @return The overall number of characters printed to the string * - * @see snprint_mac_addr - * @see str_to_octets - * @see check_octets_not_all_zero + * @see ::snprint_octets */ - int snprint_octets( char *s, size_t max_len, const uint8_t *octets, int num_octets, char sep, const char *info ) ; + 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 s The string buffer into which to print - * @param max_len Maximum length of the string, i.e. size of the buffer - * @param p_mac_addr The MAC address to be printed + * @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 * - * @see snprint_octets - * @see str_to_octets - * @see check_octets_not_all_zero + * @see ::snprint_octets + * @see ::str_to_octets + * @see ::octets_are_all_zero */ - int snprint_mac_addr( char *s, size_t max_len, const MBG_MAC_ADDR *p_mac_addr ) ; + 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 octets An array of octets to be set up - * @param num_octets The number of octets which can be stored - * @param s The string to be converted + * @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 * * @return The overall number of octets decoded from the string * - * @see snprint_octets - * @see snprint_mac_addr - * @see check_octets_not_all_zero + * @see ::snprint_octets + * @see ::snprint_mac_addr + * @see ::octets_are_all_zero */ int str_to_octets( uint8_t *octets, int num_octets, const char *s ) ; /** - * @brief Check if an array of octets is valid, i.e. != 0 + * @brief Check if an array of octets is all zero * - * @param octets Pointer to the array of octets - * @param num_octets Number of octets + * @param[in] octets Pointer to the array of octets + * @param[in] num_octets Number of octets * - * @return MBG_LU_SUCCESS octets are valid, i.e. not all 0 - * MBG_LU_ERR_NOT_SET octets are invalid, i.e. all 0 + * @return true if all bytes are 0, else false * - * @see snprint_octets - * @see snprint_mac_addr - * @see str_to_octets + * @see ::snprint_octets + * @see ::snprint_mac_addr + * @see ::str_to_octets */ - int check_octets_not_all_zero( const uint8_t *octets, int num_octets ) ; + bool octets_are_all_zero( const uint8_t *octets, int num_octets ) ; /** - * @brief Check if an array of octets is valid, i.e. != 0 + * @brief Check if a MAC address is all zero * - * @param p_addr Pointer to a MAC address + * @param[in] p_addr Pointer to a MAC address to be checked * - * @return MBG_LU_SUCCESS MAC address is valid, i.e. not all 0 - * MBG_LU_ERR_NOT_SET MAC address is invalid, i.e. all 0 + * @return true if all bytes of the MAC address are 0, else false * - * @see check_octets_not_all_zero + * @see ::octets_are_all_zero */ - int check_mac_addr_not_all_zero( const MBG_MAC_ADDR *p_addr ) ; + 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 * - * @param if_name Name of the interface - * @param ioctl_code One of the predefined system SIOCGxxx IOCTL codes - * @param p_ifreq Pointer to a request buffer + * @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 ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES */ int do_siocg_ioctl( const char *if_name, int ioctl_code, struct ifreq *p_ifreq ) ; /** - * @brief Retrieve the MAC address of a network interface - * - * @param if_name Name of the interface - * @param p_mac_addr Pointer to the MAC address buffer to be filled up + * @brief Retrieve the index of a specific network interface * - * @return one of the ::MBG_LU_CODES - * on error the MAC addr is set to all 0 + * @param[in] if_name Name of the interface + * @param[out] p_intf_idx Pointer to a variable to be filled up * - * @see get_port_mac_addr_check + * @return One of the @ref MBG_RETURN_CODES. + * On error, *p_intf_idx is set to -1. */ - int get_port_mac_addr( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) ; + int get_port_intf_idx( const char *if_name, int *p_intf_idx ) ; /** - * @brief Retrieve and check the MAC address of a network interface - * - * @param if_name Name of the interface - * @param p_mac_addr Pointer to the MAC address buffer to be filled up + * @brief Retrieve the MAC address of a network interface * - * @return one of the ::MBG_LU_CODES - * on error the MAC addr is set to all 0 + * @param[in] if_name Name of the interface + * @param[out] p_mac_addr Pointer to the MAC address buffer to be filled up * - * @see get_port_mac_addr + * @return One of the @ref MBG_RETURN_CODES + * On error, the MAC address is set to all 0 */ - int get_port_mac_addr_check( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) ; + int get_port_mac_addr( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) ; /** * @brief Check the link state of a network interface * - * @param if_name Name of the interface + * @param[in] if_name Name of the interface * - * @return 1 link detected on port - * 0 no link detected on port - * one of the ::MBG_LU_CODES in case of an error + * @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 */ int check_port_link( const char *if_name ) ; /** + * @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 + * + * @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 + */ + int check_port_status( const char *if_name, int *p_speed, int *p_duplex ) ; + + /** * @brief Retrieve the IPv4 address of a network interface * - * @param if_name Name of the interface - * @param p_addr Pointer to address field to be filled up + * @param[in] if_name Name of the interface + * @param[out] p_addr Pointer to address field to be filled up * - * @return one of the ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES + * On error, *p_addr is set to all 0. * - * @see get_port_ip4_settings - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr + * @see ::get_port_ip4_settings + * @see ::get_port_ip4_addr_str + * @see ::get_port_ip4_netmask + * @see ::get_port_ip4_netmask_str + * @see ::get_port_ip4_broad_addr + * @see ::get_port_ip4_broad_addr_str + * @see ::get_specific_port_ip4_addr */ int get_port_ip4_addr( const char *if_name, IP4_ADDR *p_addr ) ; /** * @brief Retrieve the IPv4 net mask of a network interface * - * @param if_name Name of the interface - * @param p_addr Pointer to address field to be filled up + * @param[in] if_name Name of the interface + * @param[out] p_addr Pointer to address field to be filled up * - * @return one of the ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES + * On error, *p_addr is set to all 0. * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr + * @see ::get_port_ip4_settings + * @see ::get_port_ip4_addr + * @see ::get_port_ip4_addr_str + * @see ::get_port_ip4_netmask_str + * @see ::get_port_ip4_broad_addr + * @see ::get_port_ip4_broad_addr_str + * @see ::get_specific_port_ip4_addr */ int get_port_ip4_netmask( const char *if_name, IP4_ADDR *p_addr ) ; /** * @brief Retrieve the IPv4 broadcast address of a network interface * - * @param if_name Name of the interface - * @param p_addr Pointer to address field to be filled up + * @param[in] if_name Name of the interface + * @param[out] p_addr Pointer to address field to be filled up * - * @return one of the ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES + * On error, *p_addr is set to all 0. * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr + * @see ::get_port_ip4_settings + * @see ::get_port_ip4_addr + * @see ::get_port_ip4_addr_str + * @see ::get_port_ip4_netmask + * @see ::get_port_ip4_netmask_str + * @see ::get_port_ip4_broad_addr_str + * @see ::get_specific_port_ip4_addr */ int get_port_ip4_broad_addr( const char *if_name, IP4_ADDR *p_addr ) ; /** * @brief Retrieve the IPv4 gateway (default route) * - * @param p_addr Pointer to address field to be filled up + * @param[out] p_addr Pointer to address field to be filled up * - * @return one of the ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES + * On error, *p_addr is set to all 0. */ int get_ip4_gateway( IP4_ADDR *p_addr ) ; /** * @brief Retrieve the IPv4 address of a network interface as string * - * @param if_name Name of the interface - * @param p_addr_buf Pointer to the string buffer to be filled up - * @param buf_size size of the string buffer + * @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 ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES + * On error, a string according to "0.0.0.0" is generated. * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr + * @see ::get_port_ip4_settings + * @see ::get_port_ip4_addr + * @see ::get_port_ip4_netmask + * @see ::get_port_ip4_netmask_str + * @see ::get_port_ip4_broad_addr + * @see ::get_port_ip4_broad_addr_str + * @see ::get_specific_port_ip4_addr */ int get_port_ip4_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) ; /** * @brief Retrieve the IPv4 net mask of a network interface as string * - * @param if_name Name of the interface - * @param p_addr_buf Pointer to the string buffer to be filled up - * @param buf_size size of the string buffer + * @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 ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES + * On error, a string according to "0.0.0.0" is generated. * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr + * @see ::get_port_ip4_settings + * @see ::get_port_ip4_addr + * @see ::get_port_ip4_addr_str + * @see ::get_port_ip4_netmask + * @see ::get_port_ip4_broad_addr + * @see ::get_port_ip4_broad_addr_str + * @see ::get_specific_port_ip4_addr */ int get_port_ip4_netmask_str( const char *if_name, char *p_addr_buf, int buf_size ) ; /** * @brief Retrieve the IPv4 broadcast address of a network interface as string * - * @param if_name Name of the interface - * @param p_addr_buf Pointer to the string buffer to be filled up - * @param buf_size size of the string buffer + * @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 ::MBG_LU_CODES + * @return One of the @ref MBG_RETURN_CODES + * On error, a string according to "0.0.0.0" is generated. * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_specific_port_ip4_addr + * @see ::get_port_ip4_settings + * @see ::get_port_ip4_addr + * @see ::get_port_ip4_addr_str + * @see ::get_port_ip4_netmask + * @see ::get_port_ip4_netmask_str + * @see ::get_port_ip4_broad_addr + * @see ::get_specific_port_ip4_addr */ int get_port_ip4_broad_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) ; /** * @brief Retrieve the current IPv4 settings of a network interface * - * @param if_name Name of the interface - * @param p Pointer to a IP4_SETTINGS structure to be filled up + * @param[in] if_name Name of the interface + * @param[out] p Pointer to a IP4_SETTINGS structure to be filled up * - * @return 0 on success, < 0 on error + * @return One of the @ref MBG_RETURN_CODES * - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr + * @see ::get_port_ip4_addr + * @see ::get_port_ip4_addr_str + * @see ::get_port_ip4_netmask + * @see ::get_port_ip4_netmask_str + * @see ::get_port_ip4_broad_addr + * @see ::get_port_ip4_broad_addr_str + * @see ::get_specific_port_ip4_addr */ int get_port_ip4_settings( const char *if_name, IP4_SETTINGS *p ) ; diff --git a/mbglib/common/mbg_arch.h b/mbglib/common/mbg_arch.h index 4bc92fd..f803e1d 100644 --- a/mbglib/common/mbg_arch.h +++ b/mbglib/common/mbg_arch.h @@ -1,16 +1,26 @@ /************************************************************************** * - * $Id: mbg_arch.h 1.4 2012/10/02 18:32:00Z martin REL_M $ + * $Id: mbg_arch.h 1.6 2017/01/27 09:03:16Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * * Description: * Definitions to support different computer hardware architectures. * + * For a good summary of predefined macros which can be used to determine + * the build environment, the target environment, and architecture, see: + * http://sourceforge.net/p/predef/wiki/Home/ + * * ----------------------------------------------------------------------- * $Log: mbg_arch.h $ - * Revision 1.4 2012/10/02 18:32:00Z martin + * Revision 1.6 2017/01/27 09:03:16Z martin + * Added macros _mbg_swab8() and _mbg_swab64(). + * Fixed macro syntax. + * Modified _swab_dummy() to avoid compiler warnings due to unused variables. + * Revision 1.5 2014/03/11 16:01:55 martin + * Added a comment. + * Revision 1.4 2012/10/02 18:32:00 martin * Include words.h and, conditionally, stdlib.h. * Use generic preprocessor symbol MBG_TGT_KERNEL. * Revision 1.3 2009/06/12 13:12:37Z martin @@ -64,7 +74,7 @@ // to access unaligned data. #if !defined( _mbg_put_unaligned ) - #define _mbg_put_unaligned( _v, _p ) ((void)( *(_p) = (_v) )) + #define _mbg_put_unaligned( _v, _p ) do { ((void)( *(_p) = (_v) )); } while ( 0 ) #endif #if !defined( _mbg_get_unaligned ) @@ -117,8 +127,9 @@ -// swap a double type variable bytewise e.g. to convert the endianess - +/** + * @brief Swap a 'double' type variable bytewise e.g. to convert the endianess + */ static __mbg_inline void mbg_swab_double( double *p ) { @@ -141,22 +152,27 @@ void mbg_swab_double( double *p ) #if defined( MBG_ARCH_BIG_ENDIAN ) - #define _mbg_swab16( _p ) *(_p) = __swab16( *(_p) ) - #define _mbg_swab32( _p ) *(_p) = __swab32( *(_p) ) + #define _mbg_swab8( _p ) _nop_macro_fnc() // always a dummy, but for completeness ... + #define _mbg_swab16( _p ) do { *(_p) = __swab16( *(_p) ); } while ( 0 ) + #define _mbg_swab32( _p ) do { *(_p) = __swab32( *(_p) ); } while ( 0 ) + #define _mbg_swab64( _p ) do { *(_p) = __swab64( *(_p) ); } while ( 0 ) #define _mbg_swab_double( _p ) mbg_swab_double( _p ) #define _mbg_swab_doubles( _p, _n ) \ + do \ { \ int i; \ for ( i = 0; i < (_n); i++ ) \ _mbg_swab_double( &_p[i] ); \ - } + } while ( 0 ) #else + #define _mbg_swab8( _p ) _nop_macro_fnc() #define _mbg_swab16( _p ) _nop_macro_fnc() #define _mbg_swab32( _p ) _nop_macro_fnc() + #define _mbg_swab64( _p ) _nop_macro_fnc() #define _mbg_swab_double( _p ) _nop_macro_fnc() @@ -164,4 +180,16 @@ void mbg_swab_double( double *p ) #endif + + + +/** + * @brief A placeholder for yet missing _mbg_swab_..() macros + * + * We don't just use the _nop_macro_fnc() macros here to avoid + * compiler warnings 'unused variable'. + */ +#define _mbg_swab_dummy( _x ) do { (void) _x; } while ( 0 ) + + #endif /* _MBG_ARCH_H */ diff --git a/mbglib/common/mbg_cof.h b/mbglib/common/mbg_cof.h new file mode 100644 index 0000000..3666b1b --- /dev/null +++ b/mbglib/common/mbg_cof.h @@ -0,0 +1,83 @@ + +/************************************************************************** + * + * $Id: mbg_cof.h 1.2 2017/07/05 14:25:12Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Container macros (see Linux Kernel) + * + * ----------------------------------------------------------------------- + * $Log: mbg_cof.h $ + * Revision 1.2 2017/07/05 14:25:12Z 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 + * Initial revision by philipp. + * + **************************************************************************/ + +#ifndef _MBG_COF_H +#define _MBG_COF_H + +/* Other headers to be included */ + +#include <mbg_tgt.h> + +#if !defined( MBG_TGT_KERNEL ) + #include <stddef.h> // for offsetof() +#endif + + +#ifdef _MBG_COF + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + + +#if defined( MBG_TGT_POSIX ) + + // A special construct supported by gcc/clang and and implemented + // e.g. in the Linux kernel, which is said to be very type-safe: + #define mbg_container_of( _ptr, _type, _member ) ({ \ + const typeof( ((_type *)0)->_member ) *__mptr = (_ptr); \ + (_type *)((char *)__mptr - offsetof(_type,_member));}) + +#else + + // A different implementation in ANSI C, which supports type-checking anyway: + #define mbg_container_of( _ptr, _type, _member ) \ + ( (_type *)( (char *)(1 ? (_ptr) : &((_type *)0)->_member) - offsetof( _type, _member ))) + +#endif + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + +/* (no header definitions found) */ + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _MBG_COF_H */ diff --git a/mbglib/common/mbg_serclock_cfg.h b/mbglib/common/mbg_serclock_cfg.h new file mode 100644 index 0000000..8d2dad0 --- /dev/null +++ b/mbglib/common/mbg_serclock_cfg.h @@ -0,0 +1,149 @@ + +/************************************************************************** + * + * $Id: mbg_serclock_cfg.h 1.3 2018/11/29 14:31:47Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for serial clock evaluation configuration. + * + * ----------------------------------------------------------------------- + * $Log: mbg_serclock_cfg.h $ + * Revision 1.3 2018/11/29 14:31:47Z martin + * New preprocessor symbol MBG_SUPP_LANCLOCK to + * conditionally include lanclock stuff. + * Revision 1.2 2018/08/08 09:44:01Z martin + * Renamed MBG_SERCLOCK_CFG::ref_offs_min to ref_offs_mins. + * Added MBG_LANCLOCK_CFG structure for XPORT devices. + * Revision 1.1 2011/09/23 13:56:32 martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _MBG_SERCLOCK_CFG_H +#define _MBG_SERCLOCK_CFG_H + +/* Other headers to be included */ + +#include <mbg_tgt.h> +#include <gpsdefs.h> +#include <pcpsdefs.h> +#include <pcpsutil.h> +#include <mbgtime.h> +#include <mbgpccyc.h> + +#if !defined( MBG_SUPP_LANCLOCK ) + #define MBG_SUPP_LANCLOCK 0 +#endif + +#if MBG_SUPP_LANCLOCK + #include <secudefs.h> +#endif + +#if defined( MBG_TGT_WIN32 ) + #include <rs232.h> + #include <mbgdevio.h> +#endif //MBG_TGT_WIN32 + +#include <use_pack.h> + + +#ifdef _MBG_SERCLOCK_CFG + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#if defined( _USE_PACK ) + #pragma pack( 1 ) // set byte alignment + #define _USING_BYTE_ALIGNMENT +#endif + + +#ifdef __cplusplus +extern "C" { +#endif + + +#if !defined( _RS232_H ) + +// TODO: use a more appropriate type + +typedef struct +{ + char ComName[20]; //##+++ modified, 7 in rs232.h under Windows + char Framing[4]; + long Baudrate; +} COMSTRUCT; + +#endif + + +typedef struct +{ + COMSTRUCT port; + uint32_t telegram_type; + uint32_t ref_type; + uint32_t flags; + MBG_REF_OFFS ref_offs_mins; + +} MBG_SERCLOCK_CFG; + + +// Bit masks used with MBG_SERCLOCK_CFG::flags: +enum +{ + SERCLOCK_FORCE_UTC, // string contains always UTC time + SERCLOCK_READ_NORMAL, // don't use special timeout settings + SERCLOCK_STRING_PER_MINUTE, // account for serial string once per minute + N_SERCLOCK_FLAGS +}; + +#define MSK_SERCLOCK_FORCE_UTC ( 1UL << SERCLOCK_FORCE_UTC ) +#define MSK_SERCLOCK_READ_NORMAL ( 1UL << SERCLOCK_READ_NORMAL ) +#define MSK_SERCLOCK_STRING_PER_MINUTE ( 1UL << SERCLOCK_STRING_PER_MINUTE ) + + +#if 0 // TODO + +typedef struct +{ + IP4_ADDR ip4_addr; + PASSWORD password; + uint32_t flags; + +} ; + +#endif + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + +/* (No header definitions found) */ + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + + +#if defined( _USING_BYTE_ALIGNMENT ) + #pragma pack() // set default alignment + #undef _USING_BYTE_ALIGNMENT +#endif + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _MBG_SERCLOCK_CFG_H */ diff --git a/mbglib/common/mbg_tgt.h b/mbglib/common/mbg_tgt.h index 7970e57..fa72dbb 100644 --- a/mbglib/common/mbg_tgt.h +++ b/mbglib/common/mbg_tgt.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbg_tgt.h 1.29 2013/02/01 14:50:46Z martin REL_M $ + * $Id: mbg_tgt.h 1.44 2018/12/11 15:34:15Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,7 +11,132 @@ * * ----------------------------------------------------------------------- * $Log: mbg_tgt.h $ - * Revision 1.29 2013/02/01 14:50:46Z martin + * Revision 1.44 2018/12/11 15:34:15Z martin + * Older Visual Studio versions don't support _strtoi64(). + * Revision 1.43 2018/11/22 11:28:01Z martin + * New preprocessor symbol MBG_TGT_USE_IOCTL. + * Provide 'uintptr_t' for old Linux kernels. + * Removed obsolete Windows driver stuff. + * Revision 1.42 2018/09/20 09:40:21 martin + * Define MBG_TGT_MISSTNG_STRTOLL and + * MBG_TGT_MISSING_LLDDIV_T, if appropriate. + * Revision 1.41 2018/08/23 10:49:56Z martin + * Enhanced handling of Windows DDK builds. + * Revision 1.40 2018/07/02 16:57:49Z martin + * Removed obsolete define MBG_USE_MM_IO_FOR_PCI. + * Revision 1.39 2018/06/25 10:52:00 martin + * Support MBG_TGT_NO_TGT. + * Default settings for KERNEL_HAS_BOOL and KERNEL_HAS_TRUE_FALSE + * for Linux can be overridden by project settings. + * Renamed MBG_PRE64_PREFIX to MBG_PRI_64_PREFIX. + * MBG_PRI_64_PREFIX_L or MBG_PRI_64_PREFIX_LL can be used + * to override the defaults with specific project settings. + * 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. + * Defined MBG_TGT_MISSING_STRUCT_TIMESPEC for Borland C. + * Defined __func__ for BC 5 and for DOS, and provide a + * common default declaration.. + * Updated some comments. + * Revision 1.38 2017/08/08 13:07:31 martin + * Proper fix for PRId64 and others. + * Define _CRT_SECURE_NO_WARNINGS only if not already defined. + * Revision 1.37 2017/07/10 07:08:45 thomas-b + * Define PRId64 if it is not defined in inttypes.h + * Revision 1.36 2017/07/04 12:35:11 martin + * Fixed build for Windows kernel space. + * Don't define ssize_t if HAVE_SSIZE_T is already defined. + * Added definition for _NO_MBG_API. + * Fixed missing 'bool' type for old Linux kernels. + * Fixed missing 'struct timespec' for DOS. + * Evaluate preprocessor symbol KERNEL_HAS_BOOL to avoid + * compiler errors due to duplicate definitions in specific + * Linux kernels patched by the distro maintainers. + * Provide ssize_t for C++Builder 5. + * Improved Visual Studio version checking. + * New define MBG_TGT_HAS_NODE_NAME. + * Revision 1.35 2016/08/05 12:21:34 martin + * Conditionally define a macro _DEPRECATED_BY which can be used to + * tag functions as deprecated, so compilers can emit appropriate warnings. + * New symbol MBG_TGT_HAS_ABS64. + * Moved some compatibility definitions from gpsserio.h here. + * Define ssize_t for Windows, if required. + * Conditionally provided struct timespec for Windows. + * Added compatible 64 bit type print format specifiers. + * Include inttypes.h for all targets providing also stdint.h. + * Added some MSVC version code information. + * Fixes for FreeBSD. + * Fixed some spelling. + * Tmp workaround for 2.6.32-5-sparc64. + * Proper fix required. + * Revision 1.34.1.26 2016/08/05 10:38:10 martin + * Revision 1.34.1.25 2016/08/04 14:51:25Z martin + * Moved some compatibility definitions from gpsserio.h to mbg_tgt.h. + * Revision 1.34.1.24 2016/08/02 13:10:58 martin + * Define ssize_t for Windows, if required. + * Revision 1.34.1.23 2016/07/18 14:41:27Z martin + * New symbol MBG_TGT_HAS_ABS64. + * Revision 1.34.1.22 2016/07/14 09:00:58Z martin + * Conditionally provided struct timespec for Windows. + * Revision 1.34.1.21 2016/07/07 10:01:28Z martin + * Modified inclusion of Windows header files. + * Revision 1.34.1.20 2016/06/06 12:59:03 thomas-b + * Include all necessary Windows headers in the needed sequence + * Revision 1.34.1.19 2016/04/26 14:53:06 martin + * Revision 1.34.1.18 2016/04/26 13:31:08Z martin + * Added compatible 64 bit type print format specifiers. + * Revision 1.34.1.17 2016/04/25 14:46:20Z martin + * Include inttypes.h for all targets providing also stdint.h. + * Revision 1.34.1.16 2016/03/02 12:26:15 martin + * *** empty log message *** + * Revision 1.34.1.15 2016/02/26 09:12:11 paul + * Revision 1.34.1.14 2015/12/10 12:34:14Z martin + * *** empty log message *** + * Revision 1.34.1.13 2015/12/01 14:55:52 martin + * Revision 1.34.1.12 2015/12/01 14:54:08Z martin + * *** empty log message *** + * Revision 1.34.1.11 2015/12/01 14:52:20 martin + * *** empty log message *** + * Revision 1.34.1.10 2015/12/01 14:43:44 martin + * *** empty log message *** + * Revision 1.34.1.9 2015/12/01 13:55:09 martin + * Conditionally define a macro _DEPRECATED_BY which can be used to + * tag functions as deprecated, so compilers can emit appropriate warnings. + * Revision 1.34.1.8 2015/10/28 13:45:25 martin + * Added some MSVC version code information. + * Revision 1.34.1.7 2015/10/19 09:34:56 martin + * Fixed some spelling. + * Revision 1.34.1.6 2015/10/15 12:49:10 marvin + * Revision 1.34.1.5 2015/10/08 08:55:16Z martin + * Revision 1.34.1.4 2015/10/05 15:07:23Z marvin + * Unicode support. + * Revision 1.34.1.3 2015/09/21 08:58:27Z martin + * *** empty log message *** + * Revision 1.34.1.2 2015/09/18 14:53:25 martin + * Fixes for FreeBSD. + * Revision 1.34.1.1 2015/04/07 15:40:59 martin + * Tmp workaround for 2.6.32-5-sparc64. + * Proper fix required. + * Revision 1.34 2015/03/03 13:32:49 martin + * Provide __func__ for MS Visual Studio. + * Revision 1.33 2015/03/02 11:27:59Z martin + * Windows only: + * Define _CRT_SECURE_NO_WARNINGS to quiet compiler warnings. + * Define WIN32_LEAN_AND_MEAN only if it hasn't been defined before. + * Revision 1.32 2014/06/24 09:21:44 martin + * Update for newer C++Builder versions. + * Revision 1.31 2014/05/27 10:23:33 martin + * Finer control of which types are required for or already + * available on particular target systems. + * First definitions to support SunOS/Solaris. + * Revision 1.30 2014/04/01 12:55:58 martin + * Define MBG_TGT_WIN32 also for MS resource compiler. + * New target MBG_TGT_POSIX. + * Always include winsock2.h and windows.h for MBG_TGT_WIN32. + * Always include unistd.h for MBG_TGT_POSIX. + * Define empty __attribute__ macro for non-gcc environments. + * Revision 1.29 2013/02/01 14:50:46 martin * Fixed a typo which caused an error under Borland CBuilder 5. * Revision 1.28 2012/12/12 10:03:16Z martin * Fix for Borland C 3.1. @@ -60,9 +185,9 @@ * Recognize DOS target under 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 + * Added macros to determine whether C language extensions * (e.g. C94, C99) are supported by the target environment. - * Added macro to check whether wchar_t and friends are + * Added macro to check whether wchar_t and friends are * supported, and some compatibility stuff. * Revision 1.11 2007/10/31 16:58:03 martin * Fixed __mbg_inline for Borland C (DOS). @@ -71,7 +196,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 + * Under 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. @@ -88,7 +213,7 @@ * Revision 1.3 2003/04/09 13:37:20Z martin * Added definition for _MBG_API. * Revision 1.2 2003/02/24 16:08:45Z martin - * Don't setup for Win32 PNP if explicitely configured non-PNP. + * Don't setup for Win32 PNP if explicitly configured non-PNP. * Revision 1.1 2002/02/19 13:46:20Z MARTIN * Initial revision * @@ -100,6 +225,10 @@ /* Other headers to be included */ +#ifdef MBG_TGT_NO_TGT + #include <mbg_no_tgt.h> +#else + #ifdef _MBG_TGT #define _ext #else @@ -109,6 +238,25 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + +// The prefix required in a printf() format string to print an +// int64_t type (i.e. "%li", "%lli", "I64i", etc.) may vary depending +// on the compiler type and version, and the associated run time library. +// For user space applications this is usually defined in the header +// files provided by the build environment, but for kernel code there +// are often no such defines, but there are some commonly used defaults. +// This is a hack that can be used to override these defaults in the +// project settings for kernel code, e.g. in the Makefile. +#if defined( MBG_PRI_64_PREFIX_L ) + #define MBG_PRI_64_PREFIX "l" +#elif defined( MBG_PRI_64_PREFIX_LL ) + #define MBG_PRI_64_PREFIX "ll" +#endif + + #if defined( _CVI_ ) #define MBG_TGT_CVI @@ -128,7 +276,7 @@ #if ( _WIN32_WINNT >= 0x0500 ) // Win2k and above #if !defined( MBG_TGT_WIN32_NON_PNP ) - // only if not explicitely disabled + // only if not explicitly disabled #define MBG_TGT_WIN32_PNP #endif #endif @@ -154,6 +302,11 @@ // MS Visual C++ #define MBG_TGT_WIN32 +#elif defined( RC_INVOKED ) + + // MS resource compiler + #define MBG_TGT_WIN32 + #elif defined( __WINDOWS_386__ ) // Watcom C/C++ for target Win32 @@ -168,6 +321,7 @@ // Watcom C/C++ for target OS/2 #define MBG_TGT_OS2 + #define MBG_TGT_USE_IOCTL 1 #elif defined( __linux ) @@ -194,6 +348,17 @@ // GCC for target OpenBSD #define MBG_TGT_OPENBSD +#elif defined( __sun ) // Oracle Solaris or other SunOS derived operating system + + // __SUNPRO_C Oracle Solaris Studio C compiler, __SUNPRO_C value is the version number + // __SUNPRO_CC Oracle Solaris Studio C++ compiler, __SUNPRO_CC value is the version number + // __sparc generate code for SPARC (R) architecture (32-bit or 64-bit) + // __sparcv9 generate code for 64-bit SPARC architecture + // __i386 generate code for 32-bit x86 architecture + // __amd64 generate code for 64-bit x64 architecture + + #define MBG_TGT_SUNOS + #elif defined( __QNX__ ) // any compiler for target QNX @@ -220,7 +385,7 @@ #if defined( MBG_TGT_FREEBSD ) \ - || defined( MBG_TGT_NETBSD ) \ + || defined( MBG_TGT_NETBSD ) \ || defined( MBG_TGT_OPENBSD ) #define MBG_TGT_BSD @@ -230,16 +395,46 @@ #endif -#if defined( MBG_TGT_LINUX ) \ - || defined( MBG_TGT_BSD ) +#if defined( MBG_TGT_LINUX ) \ + || defined( MBG_TGT_BSD ) \ + || defined( MBG_TGT_QNX_NTO ) \ + || defined( MBG_TGT_SUNOS ) + + #define MBG_TGT_POSIX #define MBG_TGT_UNIX + #endif +#if defined( MBG_TGT_WIN32 ) + + #if !defined( _CRT_SECURE_NO_WARNINGS ) + #define _CRT_SECURE_NO_WARNINGS 1 + #endif + + #include <limits.h> + + #define MBG_TGT_HAS_DEV_FN 1 + #define MBG_TGT_HAS_DEV_FN_BASE 0 + #define MBG_TGT_USE_IOCTL 1 + +#endif // Some definitions depending on the build environment ... -#if defined( __GNUC__ ) +#define FUNC_UNKNOWN "func_???" + +#if defined( __GNUC__ ) || defined( __clang__ ) + + #if defined( __clang__ ) + #define _CLANG_VERSION ( __clang_major__ * 10000 \ + + __clang_minor__ * 100 \ + + __clang_patchlevel__ ) + #endif // defined( __clang__ ) + + #define _GCC_VERSION ( __GNUC__ * 10000 \ + + __GNUC_MINOR__ * 100 \ + + __GNUC_PATCHLEVEL__ ) #if defined( __i386__ ) @@ -260,7 +455,6 @@ #elif defined( __sparc__ ) #define MBG_ARCH_SPARC - #define MBG_USE_MM_IO_FOR_PCI 1 #define _NO_USE_PACK_INTF @@ -272,26 +466,115 @@ #if defined( MBG_TGT_LINUX ) - #if defined( __KERNEL__ ) + #if defined( MBG_TGT_KERNEL ) + #include <linux/types.h> + #include <linux/version.h> + + #if ( LINUX_VERSION_CODE <= KERNEL_VERSION( 2, 6, 4 ) ) || \ + ( LINUX_VERSION_CODE >= KERNEL_VERSION( 2, 6, 4 ) ) // must be true for 2.6.32-5-sparc64 + #define _ULONG_DEFINED 1 + #define _USHORT_DEFINED 1 + #define _UINT_DEFINED 1 + #endif + + // The 'bool' type is supported by the vanilla Linux kernel 2.6.19 and later. + #if ( LINUX_VERSION_CODE < KERNEL_VERSION( 2, 6, 19 ) ) + + // However, looks like at least the RedHat folks have backported this + // to 2.6.18, so KERNEL_HAS_BOOL can be defined to avoid a compiler error + // due to a duplicate definition. + #if !defined( KERNEL_HAS_BOOL ) + typedef _Bool bool; + #define bool bool + #endif + + // Similar for 'true' and 'false'. + #if !defined( KERNEL_HAS_TRUE_FALSE ) + enum + { + false, + true + }; + #define falso false + #define true true + #endif + + #endif + + // The 'uintptr_t' type has been introduced + // after v2.6.24-rc1 and before v2.6.24-rc2. + #if ( LINUX_VERSION_CODE < KERNEL_VERSION( 2, 6, 24 ) ) + typedef unsigned long uintptr_t; + #define uintptr_t uintptr_t + #endif + + // String formatter codes like "PRIi64" for int64_t types + // don't seem to be defined in Linux kernel mode, so we + // define the required "ll" or "l" modifier here as a hack. + // Code below uses this to define appropriate "PRIi64"-like + // definitions as "lli" or "li". + #if !defined( MBG_PRI_64_PREFIX ) + // Please note that e.g. Linux 2.6.16 on Itanium (ia64) + // with gcc 4.1.2 expects "%li" to print an int64_t. + // This may be a bug in the specific gcc version, though. + #define MBG_PRI_64_PREFIX "ll" + #endif + #else - #include <sys/types.h> + #include <stdint.h> + #include <inttypes.h> #include <stdbool.h> + + #if defined( __u_char_defined ) + #define _ULONG_DEFINED 1 + #define _USHORT_DEFINED 1 + #define _UINT_DEFINED 1 + #endif + #endif + #define MBG_TGT_HAS_DEV_FN 1 + #define MBG_TGT_HAS_DEV_FN_BASE 1 + #define MBG_TGT_USE_IOCTL 1 + #elif defined( MBG_TGT_BSD ) - #include <sys/types.h> + #if defined( MBG_TGT_KERNEL ) + #include <sys/types.h> + #else + #include <stdint.h> + #include <inttypes.h> + #include <stdbool.h> + #endif + + #define MBG_TGT_HAS_DEV_FN 1 + #define MBG_TGT_HAS_DEV_FN_BASE 1 + #define MBG_TGT_USE_IOCTL 1 + + #if defined( MBG_TGT_FREEBSD ) && defined( MBG_TGT_KERNEL ) + #if !defined( MBG_PRI_64_PREFIX ) + // String formatter codes like "PRIi64" for int64_t types + // don't seem to be defined in FreeBSD kernel mode, so we + // define the required "ll" or "l" modifier here as a hack. + // Code below uses this to define appropriate "PRIi64"-like + // definitions as "lli" or "li". + #define MBG_PRI_64_PREFIX "l" + #endif + #endif #elif defined( MBG_TGT_QNX_NTO ) // QNX 6.x (Neutrino) + #include <unistd.h> #include <stdint.h> + #include <inttypes.h> #include <stdbool.h> #else #include <stdint.h> + #include <inttypes.h> #include <stdbool.h> #endif @@ -300,34 +583,166 @@ #define MBG_TGT_HAS_WCHAR_T 1 - #define __mbg_inline __inline__ + + #if defined( __clang__ ) + #define _DEPRECATED_BY( _s ) __attribute__((deprecated("use \"" _s "\" instead"))) // works with clang 3.4.1 + #elif ( _GCC_VERSION > 40500 ) // gcc 4.5.0 and newer + #define _DEPRECATED_BY( _s ) __attribute__((deprecated("use \"" _s "\" instead"))) + #elif ( _GCC_VERSION > 30100 ) // gcc 3.1 and newer + #define _DEPRECATED_BY( _s ) __attribute__((deprecated)) + #else + // Not supported at all, use empty default definiton below. + #endif + + #if ( _GCC_VERSION > 30100 ) // gcc 3.1 and newer + #define __mbg_inline __inline__ __attribute__((always_inline)) + #else + // Not supported at all, use empty default definiton below. + #define __mbg_inline __inline__ + #endif #elif defined( _MSC_VER ) // Known predifined MS compiler version codes: + // 1910: MSVC++ 15.0 (Visual Studio 2017) + // 1900: MSVC++ 14.0 (Visual Studio 2015) + // 1800: MSVC++ 12.0 (Visual Studio 2013) // 1700: MSVC++ 11.0 (Visual Studio 2012) // 1600: MSVC++ 10.0 (Visual Studio 2010) // 1500: MSVC++ 9.0 (Visual Studio 2008) - // 1400: MSVC++ 8.0 (Visual Studio 2005) - // 1310: MSVC++ 7.1 (Visual Studio 2003) - // 1300: MSVC++ 7.0 + // 1400: MSVC++ 8.0 (Visual Studio 2005, Windows Server 2003 SP1 DDK - AMD64) + // 1310: MSVC++ 7.1 (Visual Studio .NET 2003, Windows Server 2003 DDK) + // 1300: MSVC++ 7.0 (Visual Studio .NET 2002, Windows XP SP1 DDK / DDK 2600) // 1200: MSVC++ 6.0 // 1100: MSVC++ 5.0 - #if ( _MSC_VER >= 1600 ) + // Enable this to get compile-time messages on the compiler version + #if 0 + #if ( _MSC_VER >= 1910 ) + #error >= 1910: MSVC++ 15.0 (Visual Studio 2017), or later + #elif ( _MSC_VER >= 1900 ) + #error 1900: MSVC++ 14.0 (Visual Studio 2015) + #elif ( _MSC_VER >= 1800 ) + #error 1800: MSVC++ 12.0 (Visual Studio 2013) + #elif ( _MSC_VER >= 1700 ) + #error 1700: MSVC++ 11.0 (Visual Studio 2012) + #elif ( _MSC_VER >= 1600 ) + #error 1600: MSVC++ 10.0 (Visual Studio 2010) + #elif ( _MSC_VER >= 1500 ) + #error 1500: MSVC++ 9.0 (Visual Studio 2008) + #elif ( _MSC_VER >= 1400 ) + #error STRINGIFY( _MSC_VER ) MSVC++ 8.0 (Visual Studio 2005, Windows Server 2003 SP1 DDK - AMD64) + #elif ( _MSC_VER >= 1310 ) + #error 1310: MSVC++ 7.1 (Visual Studio .NET 2003, Windows Server 2003 DDK) + #elif ( _MSC_VER >= 1300 ) + #error 1300: MSVC++ 7.0 (Visual Studio .NET 2002, Windows XP SP1 DDK / DDK 2600) + #elif ( _MSC_VER >= 1200 ) + #error 1200: MSVC++ 6.0 + #elif ( _MSC_VER >= 1100 ) + #error 1100: MSVC++ 5.0 + #else + #error <1100: Older than MSVC 4 + #endif + #endif + + // "struct timespec" is supported only since VS2015 + // If it is then 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. + // As of VS2015, only TIME_UTC is supported to read + // the UTC system time, there is no equivalent for + // the POSIX CLOCK_MONOTONIC. However, QPC can be used + // to get monotonic time stamps and intervals. + #if ( _MSC_VER < 1900 ) + #if !defined( HAVE_STRUCT_TIMESPEC ) + #define MBG_TGT_MISSING_STRUCT_TIMESPEC 1 + #endif + #endif + + #if ( _MSC_VER >= 1600 ) // TODO Eventually even 1600 doesn't support this. #include <stdint.h> - #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 + #include <inttypes.h> + #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 + + #if !defined( PRId64 ) + #define MBG_PRI_64_PREFIX "I64" + #endif #else - #define MBG_TGT_HAS_INT_8_16_32 1 + #define MBG_TGT_HAS_INT_8_16_32 1 + #define MBG_PRI_64_PREFIX "I64" #endif - // no bool support anyway - #define MBG_TGT_MISSING_BOOL_TYPE 1 + #if !defined( __cplusplus ) + // no bool support anyway + #define MBG_TGT_MISSING_BOOL_TYPE 1 + #endif - #define MBG_TGT_HAS_WCHAR_T 1 + #define MBG_TGT_HAS_WCHAR_T 1 #define __mbg_inline __forceinline + // At least up to VS2008 the C99 builtin symbol __func__ + // is not supported. Some VS versions support __FUNCTION__ + // instead, but at least VC6 doesn't support this, either. + // of the current function instead. + #if ( _MSC_VER >= 1300 ) + #define __func__ __FUNCTION__ + #else + #define __func__ FUNC_UNKNOWN + #endif + + // The "deprecated" attribute should be supported since Visual Studio 2005, + // but doesn't seem to be supported e.g. by the compiler shipped with the + // "Windows Server 2003 SP1 DDK", which is used to build kernel drivers + // and defines the same _MSC_VER number as VS2005. For now we assume + // that this is supported by compilers shipped with newer DDKs. + // The _DDK_BUILD_ symbol has to be explicitly defined in the "sources" + // file of the DDK project. + #if ( ( _MSC_VER >= 1500 ) || \ + ( ( _MSC_VER >= 1400 ) && !defined( _DDK_BUILD_ ) ) ) + #define _DEPRECATED_BY( _s ) __declspec(deprecated("deprecated, use \"" _s "\"")) + #endif + + // availability of _abs64() + #if ( _MSC_VER >= 1310 ) + // This is supported at least since Visual Studio 2008 + // and Windows Server 2003 SP1 DDK. + #define MBG_TGT_HAS_ABS64 1 + #endif + + #if !defined ( HAVE_SSIZE_T ) + + // ssize_t support + #if ( _MSC_VER >= 1500 ) + // ssize_t may not be defined, but SSIZE_T is + #include <basetsd.h> + typedef SSIZE_T ssize_t; + #else + // At least VC6 hasn't SIZE_T, either, but size_t + // is typedef'ed as unsigned int, so we just typedef + // the signed variant here. + typedef int ssize_t; + #endif + + #define HAVE_SSIZE_T 1 + + #endif // !defined ( HAVE_SSIZE_T ) + + #if ( _MSC_VER <= 1500 ) + // At least MSVC++ 9.0 / Visual Studio 2008 and older + // don't provide lldiv_t and lldiv(). + #define MBG_TGT_MISSING_LLDIV_T 1 + #endif + + #if ( _MSC_VER <= 1400 ) + #define MBG_TGT_MISSING_STRTOLL 1 + #elif ( _MSC_VER <= 1600 ) + // At least MSVC++ 10.0 / Visual Studio 2010 and older + // don't provide strtoll(), but may provide _strtoi64 instead. + #define strtoll _strtoi64 + #endif + #elif defined( _CVI_ ) // 1000 for CVI v10.0 (CVI 2010) @@ -340,6 +755,7 @@ #if ( _CVI_ >= 910 ) // LabWindows/CVI 2009 is the first version providing stdint.h. #include <stdint.h> + #include <inttypes.h> #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 #else #define USE_LONG_FOR_INT32 1 @@ -353,32 +769,72 @@ // Inline code is not supported, though the inline keyword // is silently accepted since CVI v9.0 -#elif defined( __BORLANDC__ ) +#elif defined( __BORLANDC__ ) // or __CODEGEARC__ in newer versions - // 0x0570 Borland Developer Studio 2006 - // 0x0550 Borland C/C++ 5.5 (C++ Builder 5.0) - // 0x0410 Borland C/C++ 3.1 - // 0x0400 Borland C/C++ 3.0 // 0x0200 Borland C/C++ 2.0 - - #if ( __BORLANDC__ >= 0x570 ) - // at least Borland Developer Studio 2006 supports C99 + // 0x0400 Borland C/C++ 3.0 + // 0x0410 Borland C/C++ 3.1 + // 0x0550 Borland C/C++ 5.5 (C++Builder 5.0) + + // Next codes are in addition defined as __CODEGEARC__ + // See http://docwiki.embarcadero.com + + // 0x0570 for Borland Developer Studio 2006 (BDS 2006) + // 0x0590 for C++Builder 2007 + // 0x0591 for update 1 to C++Builder 2007 + // 0x0592 for RAD Studio 2007 + // 0x0593 for the December update to RAD Studio 2007 + // 0x0610 for C++Builder 2009 and for C++Builder 2009 Update 1 + // 0x0620 for C++Builder 2010 and for C++Builder 2010 Update 1 + // 0x0621 for C++Builder 2010 Update 2 + // 0x0630 for C++Builder XE + // 0x0631 for C++Builder XE Update 1 + // 0x0640 for C++Builder XE2 + // 0x0650 for C++Builder XE3 + + #if ( __BORLANDC__ >= 0x630 ) + // C++Builder XE starts to provide stdbool.h #include <stdint.h> + #include <inttypes.h> #include <stdbool.h> - #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 + #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 + #elif ( __BORLANDC__ >= 0x570 ) + // BDS/Borland C++ Builder 2006 starts to provide at least stdint.h + #include <stdint.h> + #include <inttypes.h> + #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 + #if !defined( __cplusplus ) + #define MBG_TGT_MISSING_BOOL_TYPE 1 + #endif #elif ( __BORLANDC__ >= 0x0550 ) - #define MBG_TGT_HAS_INT_8_16_32 1 - #define MBG_TGT_MISSING_BOOL_TYPE 1 + #define MBG_TGT_HAS_INT_8_16_32 1 + #define MBG_PRI_64_PREFIX "I64" + #if !defined( __cplusplus ) + #define MBG_TGT_MISSING_BOOL_TYPE 1 + #endif + #define __func__ FUNC_UNKNOWN #else // e.g. BC 3.1 or earlier #if ( __BORLANDC__ <= 0x410 ) - #define MBG_TGT_MISSING_64_BIT_TYPES 1 - #define MBG_TGT_MISSING_BOOL_TYPE 1 - #define USE_LONG_FOR_INT32 1 + #define MBG_TGT_MISSING_64_BIT_TYPES 1 + #define MBG_TGT_MISSING_BOOL_TYPE 1 + #define USE_LONG_FOR_INT32 1 + #define MBG_TGT_MISSING_STRUCT_TIMESPEC 1 + #define __func__ __FILE__ ":" STRINGIFY(__LINE__) + + typedef int ssize_t; #endif #endif + #if ( __BORLANDC__ <= 0x0550 ) + // At least CBuilder 5 and earlier. + #define MBG_TGT_MISSING_STRTOLL 1 + #define MBG_TGT_MISSING_LLDIV_T 1 + #endif + #define MBG_TGT_HAS_WCHAR_T defined( MBG_TGT_WIN32 ) + #define MBG_TGT_MISSING_STRUCT_TIMESPEC 1 + #if defined( __cplusplus ) #define __mbg_inline inline // standard C++ syntax #elif ( __BORLANDC__ > 0x410 ) // BC3.1 defines 0x410 ! @@ -387,6 +843,11 @@ #define __mbg_inline // up to BC3.1 not supported for C #endif + #if !defined ( HAVE_SSIZE_T ) + typedef int ssize_t; // required at least for C++ Builder 5 + #define HAVE_SSIZE_T 1 + #endif + #elif defined( __WATCOMC__ ) // 1050 v10.5 @@ -399,15 +860,16 @@ #include <sys/types.h> - #define MBG_TGT_MISSING_64_BIT_TYPES 1 + #define MBG_TGT_MISSING_64_BIT_TYPES 1 #elif ( __WATCOMC__ > 1230 ) // Open Watcom C 1.3 and above #include <stdint.h> + #include <inttypes.h> #elif !defined( __WATCOM_INT64__ ) // Watcom C 11 - #define MBG_TGT_MISSING_64_BIT_TYPES 1 + #define MBG_TGT_MISSING_64_BIT_TYPES 1 #endif @@ -418,11 +880,39 @@ #endif +#if !defined( MBG_TGT_USE_IOCTL ) + #define MBG_TGT_USE_IOCTL 0 +#endif + + +// 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, +// and 8 bit fixed size types. +#if defined( MBG_PRI_64_PREFIX ) + #define PRIi64 MBG_PRI_64_PREFIX "i" + #define PRId64 MBG_PRI_64_PREFIX "d" + #define PRIo64 MBG_PRI_64_PREFIX "o" + #define PRIu64 MBG_PRI_64_PREFIX "u" + #define PRIx64 MBG_PRI_64_PREFIX "x" + #define PRIX64 MBG_PRI_64_PREFIX "X" +#endif + +#if !defined( __GNUC__ ) && !defined( __attribute__ ) + #define __attribute__( _x ) +#endif + +#if !defined( _DEPRECATED_BY ) + #define _DEPRECATED_BY( _s ) // empty definition +#endif + #if defined( MBG_TGT_WIN32 ) #if defined( _AMD64_ ) - // This is used for AMD64 architecture and for + // This is used for AMD64 architecture and for // Intel XEON CPUs with 64 bit extension. #define MBG_TGT_WIN32_PNP_X64 #define WIN32_FLAVOR "x64" @@ -433,10 +923,29 @@ #if defined( _KDD_ ) #define MBG_TGT_KERNEL + #include <ntddk.h> + + #if defined( DBG ) && DBG + #define DEBUG 1 + #endif + + #define _MBG_API #else // This must not be used for kernel drivers. + + // Prevent inclusion of obsolete winsock.h in windows.h + #if !defined( WIN32_LEAN_AND_MEAN ) + #define WIN32_LEAN_AND_MEAN 1 + #endif + #if !defined( _WINSOCKAPI_ ) + #define _WINSOCKAPI_ + #endif + #include <windows.h> + #include <winsock2.h> + #include <ws2tcpip.h> + typedef HANDLE MBG_HANDLE; #define MBG_INVALID_HANDLE INVALID_HANDLE_VALUE @@ -457,9 +966,15 @@ typedef DWORD DWORD_PTR; #endif - #endif + // socklen_t support + #if ( _MSC_VER < 1500 ) + // At least VS2008 has a socklen_t type + typedef int socklen_t; + #endif - #define _MBG_API WINAPI + #define _MBG_API WINAPI + + #endif #if defined( MBG_LIB_EXPORT ) #define _MBG_API_ATTR __declspec( dllexport ) @@ -467,7 +982,11 @@ #define _MBG_API_ATTR __declspec( dllimport ) #endif -#elif defined( MBG_TGT_UNIX ) +#elif defined( MBG_TGT_POSIX ) + + #if !defined( MBG_TGT_KERNEL ) + #include <unistd.h> + #endif typedef int MBG_HANDLE; typedef int MBG_PORT_HANDLE; @@ -484,6 +1003,44 @@ #endif +/** + * @brief A socket file descriptor type + */ +#if defined( MBG_TGT_WIN32 ) + #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). + typedef SOCKET MBG_SOCK_FD; + #endif +#elif defined( MBG_TGT_POSIX ) + typedef int MBG_SOCK_FD; //### TODO + //### TODO typedef int SOCKET; +#endif + + + +/** + * @brief A value to mark an ::MBG_SOCK_FD as invalid + */ +#if defined( MBG_TGT_WIN32 ) + #define MBG_INVALID_SOCK_FD INVALID_SOCKET // usually evaluates to (SOCKET)(~0) since SOCKET is unsigned +#elif defined( MBG_TGT_POSIX ) + #define MBG_INVALID_SOCK_FD -1 +#endif + + + +/** + * @brief The return code of socket functions in case of error + */ +#if defined( MBG_TGT_WIN32 ) + #define MBG_SOCKET_ERR_RETVAL SOCKET_ERROR // usually evaluates to -1 +#elif defined( MBG_TGT_POSIX ) + #define MBG_SOCKET_ERR_RETVAL -1 +#endif + + + #if !defined( _MBG_API ) #define _MBG_API #endif @@ -492,6 +1049,10 @@ #define _MBG_API_ATTR #endif +#if !defined( _NO_MBG_API ) + #define _NO_MBG_API +#endif + #if !defined( _NO_MBG_API_ATTR ) #define _NO_MBG_API_ATTR #endif @@ -500,10 +1061,26 @@ #define MBG_INVALID_PORT_HANDLE MBG_INVALID_HANDLE #endif -#if !defined( MBG_USE_MM_IO_FOR_PCI ) - #define MBG_USE_MM_IO_FOR_PCI 0 +#if !defined( MBG_TGT_HAS_DEV_FN ) + #define MBG_TGT_HAS_DEV_FN 0 +#endif + +#if !defined( MBG_TGT_HAS_DEV_FN_BASE ) + #define MBG_TGT_HAS_DEV_FN_BASE 0 #endif +#if defined( MBG_TGT_MISSING_STRUCT_TIMESPEC ) + + #include <time.h> + + struct timespec + { + time_t tv_sec; + long tv_nsec; + }; + +#endif // defined( MBG_TGT_MISSING_STRUCT_TIMESPEC ) + // The macros below are defined in order to be able to check if // certain C language extensions are available on the target system: @@ -538,17 +1115,6 @@ -/* End of header body */ - -#undef _ext - - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ @@ -562,5 +1128,10 @@ extern "C" { } #endif +/* End of header body */ + +#undef _ext + +#endif // !defined( MBG_TGT_NO_TGT ) -#endif /* _MBG_TGT_H */ +#endif // !defined( _MBG_TGT_H ) diff --git a/mbglib/common/mbgadjtm_cfg.h b/mbglib/common/mbgadjtm_cfg.h new file mode 100644 index 0000000..dfab87d --- /dev/null +++ b/mbglib/common/mbgadjtm_cfg.h @@ -0,0 +1,118 @@ + +/************************************************************************** + * + * $Id: mbgadjtm_cfg.h 1.2 2012/03/01 14:51:03Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for mbgadjtm configuration. + * + * ----------------------------------------------------------------------- + * $Log: mbgadjtm_cfg.h $ + * Revision 1.2 2012/03/01 14:51:03Z martin + * Fixed non-Windows build. + * Removed global variable adjtm_cfg. + * Revision 1.1.1.2 2012/03/01 14:51:03Z martin + * Fixed build for non-Windows. + * Revision 1.1.1.1 2011/11/07 13:30:05 martin + * Revision 1.1 2011/09/23 13:56:32 martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _MBGADJTM_CFG_H +#define _MBGADJTM_CFG_H + +/* Other headers to be included */ + +#include <mbg_tgt.h> +#include <gpsdefs.h> +#include <pcpsdefs.h> +#include <pcpsutil.h> +#include <mbgtime.h> +#include <mbgpccyc.h> + +#if defined( MBG_TGT_WIN32 ) + #include <rs232.h> + #include <mbgdevio.h> +#else + #define DWORD uint32_t +#endif //MBG_TGT_WIN32 + +#include <use_pack.h> + + +#ifdef _MBGADJTM_CFG + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#if defined( _USE_PACK ) + #pragma pack( 1 ) // set byte alignment + #define _USING_BYTE_ALIGNMENT +#endif + + +#ifdef __cplusplus +extern "C" { +#endif + + + +typedef struct +{ + char hardware_id[256]; + DWORD ignore_sync; + DWORD sync_radius; + DWORD repeat_count; + DWORD max_diff; + DWORD set_local_time; + DWORD gen_statistics; + DWORD notification_limit; + DWORD set_mm_timer; + DWORD evt_handling_enabled; + DWORD async_evt_cmd_delay; + char async_evt_cmd[256]; + char sync_evt_cmd[256]; + DWORD allow_initial_timestep; + DWORD allow_timestep_on_refclk_jump; + DWORD flags; +} MBGADJTM_CFG; + +// Bit masks used with MBGADJTM_CFG::flags: +#define MBGADJTM_CFG_LOG_DETAILS 0x00000001 +#define MBGADJTM_CFG_START_PAUSED 0x00000002 + + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + +/* (No header definitions found) */ + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + + +#if defined( _USING_BYTE_ALIGNMENT ) + #pragma pack() // set default alignment + #undef _USING_BYTE_ALIGNMENT +#endif + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _MBGADJTM_CFG_H */ diff --git a/mbglib/common/mbgdevio.h b/mbglib/common/mbgdevio.h index 40aeba5..e550821 100644 --- a/mbglib/common/mbgdevio.h +++ b/mbglib/common/mbgdevio.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgdevio.h 1.40 2012/10/02 18:40:30Z martin REL_M $ + * $Id: mbgdevio.h 1.47 2018/11/22 14:27:05Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,45 @@ * * ----------------------------------------------------------------------- * $Log: mbgdevio.h $ + * Revision 1.47 2018/11/22 14:27:05Z 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. + * Revision 1.46 2018/11/14 12:24:40 martin + * Renamed a preprocessor symbol to avoid a name clash. + * Revision 1.45 2018/09/21 08:59:17 martin + * New version code 0x0308, compatibility version still 0x0210. + * Account for a renamed library function. + * Updated function prototypes. + * Revision 1.44 2018/08/07 15:09:25Z martin + * New version code 0x0370, compatibility version still 0x0210. + * Revision 1.43 2018/07/05 08:50:48 martin + * Added missing linkage attribute for mbg_open_device(). + * Reworked handling of IOCTL return codes. + * Modified test if cpu_set_t and associated definitions are available. + * Use standard errno conversion functions. + * Removed usage of obsolete symbol MBGDEVIO_SIMPLE. + * Updated function prototypes. + * Revision 1.42 2017/07/05 15:20:32 martin + * New MBGDEVIO_VERSION 0x0400, compatibility version unchanged. + * Account for MBG_ERROR_CODES returned by the ioctl functions. + * New type MBG_DEV_FN used for device file names, formerly often + * referred to as 'hardware ID'. + * New type MBG_DEV_NAME used for unique device names, composed of + * device type name and serial number appended after an underscore. + * Renamed and reworked list handling for device lists. + * Use functions from new module timeutil. + * windows.h is now included in mbg_tgt.h. + * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. + * Account for PCPS_HRT_BIN_FRAC_SCALE renamed to MBG_FRAC32_UNITS_PER_SEC. + * Fixed macro definition syntax to avoid clang compiler warnings. + * Exclude mbg_chk_tstamp64_leap_sec() for BC builds for now. + * Lots of new doxygen comments and groups. + * Updated function prototypes. + * Revision 1.41 2013/09/26 08:54:54 martin + * Defined thread function type MBG_THREAD_FNC. + * Defined check-if-supported function type MBG_CHK_SUPP_FNC. + * Updated function prototypes. * Revision 1.40 2012/10/02 18:40:30Z martin * There are some g++ versions which fail to compile source code using * the macros provided by Linux to define IOCTL codes. If only the API @@ -33,7 +72,7 @@ * Made xhrt leap second check an inline function. * Fixed macro to avoid compiler warning. * Revision 1.39 2009/12/15 15:34:59Z daniel - * Support reading the raw IRIG data bits for firmware versions + * Support reading the raw IRIG data bits for firmware versions * which support this feature. * Revision 1.38.1.2 2009/12/10 09:58:53Z daniel * Revision 1.38.1.1 2009/12/10 09:45:29Z daniel @@ -129,11 +168,11 @@ * PC high resolution timer cycles. * Updated function prototypes. * Revision 1.9 2003/06/19 08:50:05Z martin - * Definition of MBGDEVIO_VERSION number to allow DLL + * Definition of MBGDEVIO_VERSION number to allow DLL * API version checking. * Replaced some defines by typedefs. * Renamed USE_DOS_TSR to MBG_USE_DOS_TSR. - * New preprocessor symbol MBG_USE_KERNEL_DRIVER which + * New preprocessor symbol MBG_USE_KERNEL_DRIVER which * is defined only for targets which use IOCTLs. * Don't include pcps_dos.h here. * Updated function prototypes. @@ -171,20 +210,24 @@ #include <mbg_tgt.h> #include <mbg_arch.h> +#include <cfg_hlp.h> +#include <timeutil.h> #include <mbgmutex.h> #include <mbgerror.h> #include <mbggeo.h> #include <pcpsdev.h> #include <pci_asic.h> #include <use_pack.h> + #include <time.h> +#include <stdio.h> +#include <errno.h> -#define MBGDEVIO_VERSION 0x0307 +#define MBGDEVIO_VERSION 0x0308 #define MBGDEVIO_COMPAT_VERSION 0x0210 -#define MBG_MAX_DEVICES 8 #if defined( MBG_TGT_WIN32 ) @@ -200,11 +243,7 @@ #define MBGDEVIO_HAVE_THREAD_AFFINITY 1 #endif - #define MBG_USE_KERNEL_DRIVER 1 - #include <windows.h> - #define MBGDEVIO_RET_VAL DWORD - #define _mbgdevio_cnv_ret_val( _v ) (_v) #elif defined( MBG_TGT_LINUX ) @@ -219,7 +258,6 @@ // target envionment. Otherwise thread support is disabled // as per default. - #define MBG_USE_KERNEL_DRIVER 1 #include <sys/ioctl.h> #include <fcntl.h> #include <sched.h> @@ -230,14 +268,11 @@ #elif defined( MBG_TGT_BSD ) - #define MBG_USE_KERNEL_DRIVER 1 #include <sys/ioctl.h> #include <fcntl.h> #elif defined( MBG_TGT_OS2 ) - #define MBG_USE_KERNEL_DRIVER 1 - #elif defined( MBG_TGT_QNX_NTO ) #include <sys/types.h> @@ -261,7 +296,9 @@ #endif -#if defined( MBG_USE_KERNEL_DRIVER ) +#if MBG_TGT_USE_IOCTL + + #include <mbgioctl.h> #include <stdlib.h> #include <string.h> @@ -281,8 +318,16 @@ #define MBGDEVIO_HAVE_THREAD_AFFINITY 0 #endif +#if ( 0 && defined( DEBUG ) ) + #define DEBUG_IOCTL_CALLS 1 +#else + #define DEBUG_IOCTL_CALLS 0 +#endif + + #ifdef _MBGDEVIO #define _ext + #define _DO_INIT #else #define _ext extern #endif @@ -296,16 +341,11 @@ #endif -// If MBGDEVIO_SIMPLE != 0 then some complex configuration -// API calls are excluded from build, which would otherwise -// require some additional mbglib modules to be linked -// to the application. -#if !defined( MBGDEVIO_SIMPLE ) - #define MBGDEVIO_SIMPLE 0 +#ifdef __cplusplus +extern "C" { #endif - -#if defined( MBG_USE_KERNEL_DRIVER ) +#if MBG_TGT_USE_IOCTL // TODO should we use a different symbol to control this? typedef MBG_HANDLE MBG_DEV_HANDLE; @@ -326,34 +366,60 @@ #if !defined( _mbgdevio_cnv_ret_val ) - #define _mbgdevio_cnv_ret_val( _v ) \ - ( ( (_v) < 0 ) ? (_v) : MBG_SUCCESS ) + #define _mbgdevio_cnv_ret_val( _v ) (_v) #endif -#define _mbgdevio_vars() \ - MBGDEVIO_RET_VAL rc +/** + * @brief A string that can take a device file name + * + * The format of the device file name depends on the type of + * operating system. + * + * On Linux and similar systems this is something like + * 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, + * bus-specific vendor and device ID numbers, etc., which can't + * easily be handled manually. + */ +typedef char MBG_DEV_FN[260]; // Conforming to MAX_PATH in Windows -#define _mbgdevio_ret_val \ - _mbgdevio_cnv_ret_val( rc ) +#if MBG_TGT_HAS_DEV_FN_BASE +#define MBGCLOCK_DEV_FN_BASE "/dev/mbgclock" +#define MBGCLOCK_DEV_FN_FMT MBGCLOCK_DEV_FN_BASE "%i" -/** - The type below is used to store a unique ID for a device which - is made up of the device model name and its serial number, i.e.: - Format: [model_name]_[serial_number], e.g. "GPS170PCI_028210040670" - */ -typedef char MBG_HW_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; +_ext const char mbg_dev_fn_base[] +#ifdef _DO_INIT + = MBGCLOCK_DEV_FN_BASE +#endif +; + +_ext const char mbg_dev_fn_fmt[] +#ifdef _DO_INIT + = MBGCLOCK_DEV_FN_FMT +#endif +; + +#endif +// Definitions specific to the target OS + #if defined( MBG_TGT_LINUX ) #define MBG_PROCESS_ID pid_t #define _mbg_get_current_process() 0 - #if defined( __cpu_set_t_defined ) + // __cpu_set_t_defined used to be defined by GNU's glibc. + // However, at least with glibc-2.26 this doesn't seem to be + // the case anymore, so we test alternatively if CPU_SETSIZE + // is defined. + #if defined( __cpu_set_t_defined ) || defined( CPU_SETSIZE ) #define MBG_CPU_SET cpu_set_t #define MBG_CPU_SET_SIZE CPU_SETSIZE #define _mbg_cpu_clear( _ps ) CPU_ZERO( (_ps) ) @@ -387,12 +453,9 @@ typedef char MBG_HW_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; #if !defined( MBG_TGT_WIN32 ) - - #define FILETIME int // just a dummy to avoid build errors - + #define FILETIME int // just a dummy to avoid build errors #endif - #if !defined( MBG_PROCESS_ID ) #define MBG_PROCESS_ID int #endif @@ -414,7 +477,7 @@ typedef char MBG_HW_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; #endif #if !defined( _mbg_cpu_set ) - #define _mbg_cpu_set( _i, _ps ) ( *(_ps) |= ( 1UL << (_i) ) ) + #define _mbg_cpu_set( _i, _ps ) ( *(_ps) |= ( (MBG_CPU_SET) 1UL << (_i) ) ) #endif #if !defined( _mbg_cpu_isset ) @@ -443,23 +506,57 @@ typedef char MBG_HW_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; #endif + +/** + * @brief A generic thread info structure + */ typedef struct { MBG_THREAD_ID thread_id; #if defined( MBG_TGT_WIN32 ) HANDLE exit_request; #endif + } MBG_THREAD_INFO; +/** + * @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 + * + * This can be used to extrapolate the current time from the current + * system cycles count. + * + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * @see @ref mbg_xhrt_poll_group + */ typedef struct { - PCPS_HR_TIME_CYCLES htc; - uint64_t pcps_hr_tstamp64; + 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 + * + * This can be used to get information from the poll thread function + * and extrapolate the current time from the current system cycles count. + * + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * @see @ref mbg_xhrt_poll_group + */ typedef struct { MBG_XHRT_VARS vars; @@ -469,3146 +566,4870 @@ typedef struct int sleep_ms; MBG_CRIT_SECT crit_sect; MBG_DEV_HANDLE dh; + } MBG_XHRT_INFO; + +/** + * @brief A structure used to control a poll thread function + * + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * @see ::mbg_xhrt_poll_thread_create + * @see ::mbg_xhrt_poll_thread_stop + * @see @ref mbg_xhrt_poll_group + */ typedef struct { MBG_XHRT_INFO xhrt_info; MBG_THREAD_INFO ti; + } MBG_POLL_THREAD_INFO; /** - Match modes to decide how to proceed if a certain - model type with certain serial number can not be found + * @brief Device matching modes + * + * Match modes to determine how to proceed if a device with + * particular model type and serial number has not been detected. */ -enum MBG_MATCH_MODE +enum MBG_MATCH_MODES { - MBG_MATCH_ANY, /**< open the next available device on the system */ - MBG_MATCH_MODEL, /**< open the next available device on the system with the same clock type */ - MBG_MATCH_EXACTLY, /**< force opening exactly the requested device otherwise exit with failure */ - N_MBG_MATCH_MODE /**< number of known modes */ + MBG_MATCH_ANY, ///< use the next device available on the system + MBG_MATCH_MODEL, ///< use the next available device of the same type + MBG_MATCH_EXACTLY, ///< use only exactly the excat matching device, otherwise fail + N_MBG_MATCH_MODES ///< number of known modes }; -typedef struct _MBG_DEVICE_LIST -{ - char *device_path; /**< Hardware ID depending on the calling function */ - struct _MBG_DEVICE_LIST *next; - -} MBG_DEVICE_LIST; - +/** + * @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 + * the structure members. + */ +typedef struct _MBG_DEV_FN_LIST_ENTRY MBG_DEV_FN_LIST_ENTRY; -typedef struct _MBG_DEVICENAME_LIST +/** + * @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. + */ +struct _MBG_DEV_FN_LIST_ENTRY { - char device_name[40]; /**< readable name */ - struct _MBG_DEVICENAME_LIST *next; - -} MBG_DEVICENAME_LIST; + char *dev_fn_ptr; ///< Address of an OS-specific device file name + ///< that can be used with an OS-specific open call. + MBG_DEV_FN_LIST_ENTRY *next; +}; -/* function prototypes: */ +/** + * @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 + * the structure members. + * + * @see ::mbg_find_devices_with_names + * @see ::mbg_free_device_name_list + */ +typedef struct _MBG_DEV_NAME_LIST_ENTRY MBG_DEV_NAME_LIST_ENTRY; -#ifdef __cplusplus -extern "C" { -#endif -/* ----- function prototypes begin ----- */ +/** + * @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. + */ +struct _MBG_DEV_NAME_LIST_ENTRY +{ + char dev_name[40]; ///< Readable device name (Should be ::MBG_DEV_NAME, which is smaller, though) + MBG_DEV_NAME_LIST_ENTRY *next; +}; -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - /** - Get the version number of the precompiled DLL/shared object library. - If this library is used as a DLL/shared object library then the version - number can be checked to see if the header files which are actually used - to build an application are compatible with the header files which have - been used to build the library, and thus the API function are called - in the correct way. +/** + * @defgroup mbgdevio_open_fncs API functions that can be used to open a device + * + * Each of these functions can be used to open a device to obtain a valid + * ::MBG_DEV_HANDLE handle which can be used with subsequent API calls to + * access the particular device. + * + * If the device fails to be opened then each of these functions returns + * ::MBG_INVALID_DEV_HANDLE, and an OS-specific "last error" code is set + * accordingly. The caller can then use ::mbg_get_last_error immediately + * to retrieve the OS-specific error code, convert it, and return the + * associated Meinberg-specific error code. See @ref MBG_ERROR_CODES. + * + * Operating systems maintain a list of devices that are currently + * present in a system. The function ::mbg_open_device expects a number + * that is used as an index to this list. If only a single supported device + * is present then index 0 can always be used to open that device. + * + * The function ::mbg_find_devices can be used to retrieve the number of + * devices statically present in the system, and the highest index number + * that can be used is the number of devices - 1. + * + * In a plug-and-play system the device list maintained by the operating + * system may change over time, for example if a USB device is plugged in + * or out during operation. In this case index numbers may change, and may + * not always refer to the same device. + * + * So the function ::mbg_open_device_by_name can be used instead to open + * a specific device identified by model name and optionally serial number. + * See ::MBG_DEV_NAME for the format of such device name. + * + * If a list of unique device names is required e.g. to set up a + * device selection dialog in a GUI application then the function + * ::mbg_find_devices_with_names can be used to allocate and set up + * such a list. When the list has been evaluated and isn't needed + * anymore then ::mbg_free_device_name_list should be called to free + * the allocated memory. + * + * Inside the operating system the device is always identified by a + * device file name which can be used internally with an OS-specific + * "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 + * like "/dev/mbgclock0" which can easily be used to specify a + * particular device. See ::MBG_DEV_FN. + * + * On such systems the function ::mbg_open_device_by_dev_fn can be used + * to open a device specified by a device file name. + * + * @see ::mbg_open_device + * @see ::mbg_find_devices + * @see ::mbg_open_device_by_name + * @see ::mbg_find_devices_with_names + * @see ::mbg_open_device_by_dev_fn + * @see ::mbg_close_device + */ - @return the version number - @see mbgdevio_check_version() - @see ::MBGDEVIO_VERSION defined in mbgdevio.h - */ - _MBG_API_ATTR int _MBG_API mbgdevio_get_version( void ) ; +/** + * @defgroup mbgdevio_hr_time_fncs API functions reading high resolution time, plus status + * + * These functions return a high resolution time, including status flags and + * local time offset according to the time zone configuration on the device. + * + * The API call ::mbg_chk_dev_has_hr_time checks if these functions are supported + * by a device. + * + * Due to the extended information returned to the caller these function + * require interaction with the on-board microcontroller, and thus take + * longer to execute than the @ref mbgdevio_fast_timestamp_fncs. + * + * <b>Note:</b> These API calls provides better accuracy and higher resolution + * than the the standard functions in @ref mbgdevio_legacy_time_fncs. + * + * The ::mbg_get_hr_time function doesn't account for the latency + * which is introduced when accessing the board. + * + * The ::mbg_get_hr_time_cycles and ::mbg_get_hr_time_comp calls + * provide ways to account for and/or compensate the latency. + * + * @see ::mbg_chk_dev_has_hr_time + * @see ::mbg_get_hr_time + * @see ::mbg_get_hr_time_cycles + * @see ::mbg_get_hr_time_comp + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs + */ - /** - @brief Check if the DLL/shared library is compatible with a given version. - If this library is used as a DLL/shared object library then the version - number can be checked to see if the header files which are actually used - to build an application are compatible with the header files which have - been used to build the library, and thus the API function are called - in the correct way. +/** + * @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, + * 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. + * + * @see ::mbg_chk_dev_has_fast_hr_timestamp + * @see ::mbg_get_fast_hr_timestamp + * @see ::mbg_get_fast_hr_timestamp_cycles + * @see ::mbg_get_fast_hr_timestamp_comp + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_legacy_time_fncs + */ - @param header_version Version number to be checked, should be ::MBGDEVIO_VERSION - from the mbgdevio.h file used to build the application - @return ::MBG_SUCCESS if compatible, ::MBG_ERR_LIB_NOT_COMPATIBLE if not. +/** + * @defgroup mbgdevio_legacy_time_fncs Legacy API functions to read the time + * + * These functions are supported by all devices, but return time only + * as a ::PCPS_TIME structure, which provides local time according to the + * local time zone configured on the device, and with 10 ms resolution only. + * + * <b>Note:</b> The @ref mbgdevio_hr_time_fncs or @ref mbgdevio_fast_timestamp_fncs + * should be used preferably, if the device supports these. + * + * @see ::mbg_get_time + * @see ::mbg_get_time_cycles + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + */ - @see mbgdevio_get_version() - @see ::MBGDEVIO_VERSION defined in mbgdevio.h - */ - _MBG_API_ATTR int _MBG_API mbgdevio_check_version( int header_version ) ; - /** - @brief Open a device by index, starting from 0. +/** + * @defgroup mbgdevio_chk_supp_fncs mbgdevio functions used to check if a particular feature is supported + * @ingroup chk_supp_fncs + * + * These functions can be used to check if a device supports a particular feature. + * + * ::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 + * if the feature is supported, e.g. if an IOCTL call failed for some reason. + * + * @see ::MBG_CHK_SUPP_FNC + */ - This function is <b>out of date</b>, mbg_open_device_by_name() - should be used instead. - See the <b>note</b> for mbg_find_device() for details. +/** + * @defgroup mbgdevio_chk_supp_fncs_deprecated Deprecated mbgdevio functions to check if a particular feature is supported + * @ingroup chk_supp_fncs + * + * @deprecated These functions are deprecated. Use the @ref mbgdevio_chk_supp_fncs preferably. + * + * These are the original functions that were introduced to check if a device supports + * a particular feature. The functions are deprecated, but will be kept for compatibility. + * + * The functions return ::MBG_SUCCESS if the information could be retrieved with out error, + * and an error code otherwise, e.g. if the IOCTL call itself failed. + * + * Only in case of success an integer variable the address of which has to be passed to the + * function is set to 1 or 0 depending on whether the requested feature is supported, or not. + * So the calling application always has to check 2 values after such a function has been called. + * + * To make applications simpler the @ref mbgdevio_chk_supp_fncs have been introduced instead, + * which can be used in a much easier way. + * + * @see @ref mbgdevio_chk_supp_fncs + */ - @param device_index index of the device, use 0 for the first device. - */ - _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device( unsigned int device_index ) ; - /** - @brief Get the number of supported devices installed on the computer. - This function is <b>out of date</b>, mbg_find_devices_with_names() - should be used instead. +/** + * @defgroup mbg_xhrt_poll_group Extrapolation of high resolution time stamps + * + * ::TODO + */ - <b>Note:</b> This function is out of date since it may not work - correctly for Meinberg devices which are disconnected and reconnected - while the system is running (e.g. USB devices). However, the function - will be kept for compatibility reasons and works correctly if all - Meinberg devices are connected at system boot and are not disconnected - and reconnected during operation - @return The number of devices found - @see mbg_find_devices_with_names() - */ - _MBG_API_ATTR int _MBG_API mbg_find_devices( void ) ; +/** + * @brief The type of functions to check if a feature is supported + * + * @ingroup mbgdevio_chk_supp_fncs + * @see @ref mbgdevio_chk_supp_fncs + */ +typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); - /** - @brief Allocate memory and set up a list of installed and supported devices. - This function should be used preferably instead of mbg_find_devices(). - @param device_list Pointer to a linked list of type ::MBG_DEVICENAME_LIST - with device names. The list will be allocated by this - function and has to be freed after usage by calling - mbg_free_device_name_list(). - @param max_devices Maximum number of devices the function should look for - (can not exceed ::MBG_MAX_DEVICES). - @return number of present devices +/* ----- function prototypes begin ----- */ - @see ::MBG_HW_NAME for the format of the unique names - @see mbg_free_device_name_list() - @see mbg_find_devices() - */ - _MBG_API_ATTR int _MBG_API mbg_find_devices_with_names( MBG_DEVICENAME_LIST **device_list, int max_devices ) ; +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ /** - @brief Free the memory allocated for a ::MBG_DEVICENAME_LIST. + * @brief Get the version number of the precompiled DLL/shared object library. + * + * If this library is used as a DLL/shared object library then the version + * number can be checked to see if the header files which are actually used + * to build an application are compatible with the header files which have + * been used to build the library, and thus the API function are called + * in the correct way. + * + * @return The version number + * + * @see ::mbgdevio_check_version + * @see ::MBGDEVIO_VERSION defined in mbgdevio.h + */ + _MBG_API_ATTR int _MBG_API mbgdevio_get_version( void ) ; - The list may have been set up and allocated before - by mbg_find_devices_with_names(). + /** + * @brief Check if the DLL/shared library is compatible with a given version. + * + * If this library is used as a DLL/shared object library then the version + * number can be checked to see if the header files which are actually used + * to build an application are compatible with the header files which have + * been used to build the library, and thus the API functions are called + * in the correct way. + * + * @param[in] header_version Version number to be checked, should be ::MBGDEVIO_VERSION + * from the mbgdevio.h file version used to build the application + * + * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE + * + * @see ::mbgdevio_get_version + * @see ::MBGDEVIO_VERSION defined in mbgdevio.h + */ + _MBG_API_ATTR int _MBG_API mbgdevio_check_version( int header_version ) ; - @param *list Linked list of type ::MBG_DEVICENAME_LIST + /** + * @brief Check if a device supports the ::RECEIVER_INFO structure and related calls. + * + * Very old devices may not provide a ::RECEIVER_INFO structure. + * The ::mbg_setup_receiver_info call should be used preferably to set up + * a ::RECEIVER_INFO for a device. That function uses this call to determine + * whether a ::RECEIVER_INFO can be read directly from a device, or sets up + * a default structure using default values depending on the device type. + * + * @note This function should be preferred over ::mbg_dev_has_receiver_info, + * which has been deprecated. + * + * @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 + * @see ::mbg_setup_receiver_info + * @see ::mbg_get_gps_receiver_info + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_receiver_info( MBG_DEV_HANDLE dh ) ; - @see mbg_find_devices_with_names() - */ - _MBG_API_ATTR void _MBG_API mbg_free_device_name_list( MBG_DEVICENAME_LIST *list) ; + /** + * @brief Check if a device supports large configuration data structures. + * + * Such structures have been introduced with the first Meinberg GPS receivers. + * Mostly all configuration structures are large data structures, and mostly all + * current devices support this, but some old devices may not. + * + * @note This function should be preferred over ::mbg_dev_has_gps_data, + * which has been deprecated. + * + * @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_gps_data( MBG_DEV_HANDLE dh ) ; /** - @brief Return a handle to a device with a certain unique name. + * @brief Check if a device supports the ::mbg_generic_io API call. + * + * <b>Warning</b>: This call is for debugging purposes and internal use only! + * + * @note This function should be preferred over ::mbg_dev_has_generic_io, + * which has been deprecated. + * + * @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 + * @see ::mbg_generic_io + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_generic_io( MBG_DEV_HANDLE dh ) ; - The names of the devices that are installed on the system can be retrieved by - the function mbg_find_devices_with_names(). + /** + * @brief Check if a device supports the ::mbg_get_asic_version API call. + * + * If ::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, + * which has been deprecated. + * + * @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 + * @see ::mbg_get_asic_version + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_asic_version( MBG_DEV_HANDLE dh ) ; - This function should be used preferably instead of mbg_open_device(). + /** + * @brief Check if a device supports the ::mbg_get_asic_features call. + * + * If ::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, + * which has been deprecated. + * + * @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 + * @see ::mbg_get_asic_features + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_asic_features( MBG_DEV_HANDLE dh ) ; - @param hw_name String with the unique name of the device to be opened - @param selection_mode One of the enum values of ::MBG_MATCH_MODE + /** + * @brief Check if a device provides eXtended Multi Ref (XMR) inputs. + * + * Devices providing XMR inputs can receive or decode different timing + * signals in parallel, and the supported sources can be prioritized. + * + * @note This function should be preferred over ::mbg_dev_has_xmr, + * which has been deprecated. + * + * @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 + * @see ::mbg_get_xmr_instances + * @see ::mbg_get_gps_all_xmr_status + * @see ::mbg_get_gps_all_xmr_info + * @see ::mbg_set_gps_xmr_settings_idx + * @see ::mbg_get_xmr_holdover_status + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_xmr( MBG_DEV_HANDLE dh ) ; - @return On success, the function returns a handle to the device, otherwise ::MBG_INVALID_DEV_HANDLE + /** + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_isa( MBG_DEV_HANDLE dh ) ; - @see ::MBG_HW_NAME for the format of the unique names. - @see ::MBG_MATCH_MODE - @see mbg_find_devices_with_names() - */ - _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const char* hw_name, int selection_mode ) //##++++ -; + /** + * @brief 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 + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_mca( MBG_DEV_HANDLE dh ) ; /** - @brief Close a handle to a device and set the handle value to ::MBG_INVALID_DEV_HANDLE. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_pci( MBG_DEV_HANDLE dh ) ; - @param dev_handle Handle to a Meinberg device. - */ - _MBG_API_ATTR void _MBG_API mbg_close_device( MBG_DEV_HANDLE *dev_handle ) ; + /** + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_pci_express( MBG_DEV_HANDLE dh ) ; /** - @brief Read information about the driver handling a given device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_usb( MBG_DEV_HANDLE dh ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_DRVR_INFO structure which is filled up. + /** + * @brief Check if a device supports GNSS configuration + * + * 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_gnss, + * which has been deprecated. + * + * @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 + * @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 ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function - */ - _MBG_API_ATTR int _MBG_API mbg_get_drvr_info( MBG_DEV_HANDLE dh, PCPS_DRVR_INFO *p ) ; + /** + * @brief Check if a device is a GPS receiver + * + * 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_gps, + * which has been deprecated. + * + * @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_is_gps( MBG_DEV_HANDLE dh ) ; /** - @brief Read detailed device information. + * @brief Check if a device is a DCF77 receiver. + * + * 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. + * + * @note This function should be preferred over ::mbg_dev_is_dcf, + * which has been deprecated. + * + * @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 + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_chk_dev_is_lwr + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_dcf( MBG_DEV_HANDLE dh ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_DEV structure to be filled up + /** + * @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 + * legacy DCF77 receivers which just decode the standard AM signal. + * See ::mbg_chk_dev_is_dcf. + * + * @note This function should be preferred over ::mbg_dev_has_pzf, + * which has been deprecated. + * + * @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 + * @see ::mbg_chk_dev_has_corr_info + * @see ::mbg_chk_dev_has_tr_distance + * @see ::mbg_chk_dev_is_dcf + * @see ::mbg_chk_dev_is_lwr + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_pzf( MBG_DEV_HANDLE dh ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function - */ - _MBG_API_ATTR int _MBG_API mbg_get_device_info( MBG_DEV_HANDLE dh, PCPS_DEV *p ) ; + /** + * @brief Check if a device is a MSF receiver + * + * @note This function should be preferred over ::mbg_dev_is_msf, + * which has been deprecated. + * + * @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 + * @see ::mbg_chk_dev_is_lwr + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_msf( MBG_DEV_HANDLE dh ) ; /** - @brief Read the current state of the on-board ::PCPS_STATUS_PORT. + * @brief Check if a device is a WWVB receiver + * + * @note This function should be preferred over ::mbg_dev_is_wwvb, + * which has been deprecated. + * + * @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 + * @see ::mbg_chk_dev_is_lwr + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_wwvb( MBG_DEV_HANDLE dh ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_STATUS_PORT value to be filled up + /** + * @brief Check if a device is a JJY receiver. + * + * @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 + * @see ::mbg_chk_dev_is_lwr + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_jjy( MBG_DEV_HANDLE dh ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function + /** + * @brief Check if a device is any long wave signal receiver + * + * Long wave receivers include e.g. DCF77, MSF, WWVB, or JJY. + * + * @note This function should be preferred over ::mbg_dev_is_lwr, + * which has been deprecated. + * + * @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 + * @see ::mbg_chk_dev_is_dcf + * @see ::mbg_chk_dev_is_msf + * @see ::mbg_chk_dev_is_wwvb + * @see ::mbg_chk_dev_is_jjy + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_lwr( MBG_DEV_HANDLE dh ) ; - @see \ref group_status_port "bitmask" - */ - _MBG_API_ATTR int _MBG_API mbg_get_status_port( MBG_DEV_HANDLE dh, PCPS_STATUS_PORT *p ) ; + /** + * @brief Check if a device provides a configurable IRIG input. + * + * @note This function should be preferred over ::mbg_dev_is_irig_rx, + * which has been deprecated. + * + * @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 + * @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 ) ; - /* (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 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. + * + * @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 + * @see ::mbg_get_lan_if_info + * @see ::mbg_get_ip4_state + * @see ::mbg_get_ip4_settings + * @see ::mbg_set_ip4_settings + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_lan_intf( MBG_DEV_HANDLE dh ) ; - <b>Warning</b>: This is for debugging purposes only! - The specialized API calls should be used preferably. - A specific device may not support any command code. + /** + * @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. + * + * @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 + * @see ::mbg_get_all_ptp_cfg_info + * @see ::mbg_get_ptp_state + * @see ::mbg_get_ptp_cfg_info + * @see ::mbg_set_ptp_cfg_settings + * @see ::mbg_chk_dev_has_ptp_unicast + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ptp( MBG_DEV_HANDLE dh ) ; - @param dh Valid handle to a Meinberg device - @param cmd Can be any \ref group_cmd_bytes "command byte" supported by the device - @param *p Pointer to a buffer to be filled up - @param size Size of the buffer *p + /** + * @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 + * PTP multicast. + * + * @note This function should be preferred over ::mbg_dev_has_ptp_unicast, + * which has been deprecated. + * + * @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 + * @see ::mbg_get_all_ptp_cfg_info + * @see ::mbg_get_ptp_uc_master_cfg_limits + * @see ::mbg_get_all_ptp_uc_master_info + * @see ::mbg_set_ptp_uc_master_settings_idx + * @see ::mbg_get_ptp_state + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ptp_unicast( MBG_DEV_HANDLE dh ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @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. + * + * @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 + * @see ::mbg_get_hr_time + * @see ::mbg_get_hr_time_cycles + * @see ::mbg_get_hr_time_comp + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_hr_time( MBG_DEV_HANDLE dh ) ; - @see mbg_generic_write() - @see mbg_generic_read_gps() - @see mbg_generic_write_gps() - @see mbg_generic_io() - */ - _MBG_API_ATTR int _MBG_API mbg_generic_read( MBG_DEV_HANDLE dh, int cmd, void *p, int size ) ; + /** + * @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. + * + * @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 + * @see ::mbg_get_fast_hr_timestamp_cycles + * @see ::mbg_get_fast_hr_timestamp_comp + * @see ::mbg_get_fast_hr_timestamp + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_fast_hr_timestamp( MBG_DEV_HANDLE dh ) ; - /* (Intentionally excluded from Doxygen) - Generic read function which writes a GPS command code to a device - and reads a number of replied data to a generic buffer. - The macro _pcps_has_gps_data() or the API call mbg_dev_has_gps_data() - check whether this call is supported by a device. - - <b>Warning</b>: This is for debugging purposes only! - The specialized API calls should be used preferably. - A specific device may not support any GPS command code. - - @param dh Valid handle to a Meinberg device - @param cmd Can be any \ref group_cmd_bytes "command byte" supported by the device. - @param *p Pointer to a buffer to be filled up - @param size Size of the buffer *p - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_gps_data() - @see mbg_generic_write_gps() - @see mbg_generic_read() - @see mbg_generic_write() - @see mbg_generic_io() - */ - _MBG_API_ATTR int _MBG_API mbg_generic_read_gps( MBG_DEV_HANDLE dh, int cmd, void *p, int size ) ; + /** + * @brief Check if a device supports configurable time scales. + * + * By default the devices return %UTC and/or local time. However, some cards + * can be configured to return raw GPS time or TAI instead. + * + * @note This function should be preferred over ::mbg_dev_has_time_scale, + * which has been deprecated. + * + * @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 + * @see ::mbg_get_time_scale_info + * @see ::mbg_set_time_scale_settings + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_time_scale( MBG_DEV_HANDLE dh ) ; /* (Intentionally excluded from Doxygen) - Generic write function which 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. - A specific device may not support any command code. - - @param dh Valid handle to a Meinberg device - @param cmd Can be any \ref group_cmd_bytes "command byte" supported by the device. - @param *p Pointer to a buffer to be written - @param size Size of the buffer *p - - @return ::MBG_SUCCESS or error code returned by device I/O control function. + * @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. + * + * @note This function should be preferred over ::mbg_dev_has_event_time, + * which has been deprecated. + * + * @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 + * @see ::mbg_set_event_time + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_event_time( MBG_DEV_HANDLE dh ) ; - @see mbg_generic_read() - @see mbg_generic_read_gps() - @see mbg_generic_write_gps() - @see mbg_generic_io() - */ - _MBG_API_ATTR int _MBG_API mbg_generic_write( MBG_DEV_HANDLE dh, int cmd, const void *p, int size ) ; + /** + * @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. + * + * @note This function should be preferred over ::mbg_dev_has_ucap, + * which has been deprecated. + * + * @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 + * @see ::mbg_get_ucap_entries + * @see ::mbg_get_ucap_event + * @see ::mbg_clr_ucap_buff + * @see ::mbg_get_gps_ucap + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ucap( MBG_DEV_HANDLE dh ) ; - /* (Intentionally excluded from Doxygen) - Generic write function which writes a GPS command code plus an - associated number of data bytes to a device. - The macro _pcps_has_gps_data() or the API call mbg_dev_has_gps_data() - check whether this call is supported by a device. - - <b>Warning</b>: This is for debugging purposes only! - The specialized API calls should be used preferably. - A specific device may not support any GPS command code. - - @param dh Valid handle to a Meinberg device - @param cmd Can be any \ref group_cmd_bytes "command byte" supported by the device. - @param *p Pointer to a buffer to be written - @param size Size of the buffer *p - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_gps_data() - @see mbg_generic_read_gps() - @see mbg_generic_read() - @see mbg_generic_write() - @see mbg_generic_io() - */ - _MBG_API_ATTR int _MBG_API mbg_generic_write_gps( MBG_DEV_HANDLE dh, int cmd, const void *p, int size ) ; + /** + * @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. + * + * @note This function should be preferred over ::mbg_dev_can_clr_ucap_buff, + * which has been deprecated. + * + * @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 + * @see ::mbg_clr_ucap_buff + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_can_clr_ucap_buff( MBG_DEV_HANDLE dh ) ; - /* (Intentionally excluded from Doxygen) - Write and/or read generic data to/from a device. - The macro _pcps_has_generic_io() or the API call mbg_dev_has_generic_io() - check whether this call is supported by a device. + /** + * @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. + * + * @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 + * @see ::mbg_get_gps_tzdl + * @see ::mbg_set_gps_tzdl + * @see ::mbg_chk_dev_has_tz + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tzdl( MBG_DEV_HANDLE dh ) ; - <b>Warning</b>: This call is for debugging purposes and internal use only! + /** + * @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. + * + * @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 + * @see ::mbg_get_pcps_tzdl + * @see ::mbg_set_pcps_tzdl + * @see ::mbg_chk_dev_has_tz + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_pcps_tzdl( MBG_DEV_HANDLE dh ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @brief Check if a device supports timezone configuration using the ::PCPS_TZCODE type. + * + * @note This function should be preferred over ::mbg_dev_has_tzcode, + * which has been deprecated. + * + * @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 + * @see ::mbg_get_tzcode + * @see ::mbg_set_tzcode + * @see ::mbg_chk_dev_has_tz + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tzcode( MBG_DEV_HANDLE dh ) ; - @see mbg_dev_has_generic_io() - @see mbg_generic_read() - @see mbg_generic_write() - @see mbg_generic_read_gps() - @see mbg_generic_write_gps() - */ - _MBG_API_ATTR int _MBG_API mbg_generic_io( MBG_DEV_HANDLE dh, int type, const void *in_p, int in_sz, void *out_p, int out_sz ) ; + /** + * @brief Check if a device supports any kind of timezone configuration. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @note This function should be preferred over ::mbg_dev_has_tz, + * 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 + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_has_tzdl + * @see ::mbg_chk_dev_has_pcps_tzdl + * @see ::mbg_chk_dev_has_tzcode + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tz( MBG_DEV_HANDLE dh ) ; /** - @brief Read a ::PCPS_TIME structure returning the current date/time/status. + * @brief Check if a device provides either an IRIG input or output. + * + * @note This function should be preferred over ::mbg_dev_has_irig, + * which has been deprecated. + * + * @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 + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig_tx + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig( MBG_DEV_HANDLE dh ) ; - 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). + /** + * @brief Check if a device provides a configurable IRIG output. + * + * @note This function should be preferred over ::mbg_dev_has_irig, + * which has been deprecated. + * + * @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 + * @see ::mbg_get_irig_tx_info + * @see ::mbg_set_irig_tx_settings + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig + * @see @ref group_icode + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_tx( MBG_DEV_HANDLE dh ) ; - This call is supported by any device manufactured by Meinberg. - However, for higher accuracy and resolution the mbg_get_hr_time..() or - mbg_get_fast_hr_timestamp..() group of calls should be used preferably - if supported by the device. + /** + * @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. + * + * @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 + * @see ::mbg_get_irig_ctrl_bits + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_TIME structure to be filled up + /** + * @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. + * + * @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 + * @see ::mbg_get_raw_irig_data + * @see ::mbg_get_raw_irig_data_on_sec_change + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_raw_irig_data( MBG_DEV_HANDLE dh ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @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. + * + * @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 + * @see ::mbg_get_irig_time + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_time( MBG_DEV_HANDLE dh ) ; - @see mbg_get_hr_time() - @see mbg_set_time() - @see mbg_get_sync_time() - */ - _MBG_API_ATTR int _MBG_API mbg_get_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ; + /** + * @brief 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. + * + * @note This function should be preferred over ::mbg_dev_has_signal, + * which has been deprecated. + * + * @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_signal( MBG_DEV_HANDLE dh ) ; /** - @brief Set the device's on-board clock to a given date and time. + * @brief Check if a device provides a modulation signal + * + * Modulation signals are e.g. the second marks provided by a long wave receiver. + * + * @note This function should be preferred over ::mbg_dev_has_mod, + * which has been deprecated. + * + * @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_mod( MBG_DEV_HANDLE dh ) ; - The macro _pcps_can_set_time() checks whether this call - is supported by a device. + /* (Intentionally excluded from Doxygen) + * @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 + * rather than ::DEFAULT_BAUD_RATES_DCF. + * + * The call ::mbg_get_serial_settings takes care of this, so applications + * which use that call as suggested don't need to use this call directly. + * + * @note This function should be preferred over ::mbg_dev_has_serial_hs, + * which has been deprecated. + * + * @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 + * @see ::mbg_get_serial_settings + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_serial_hs( MBG_DEV_HANDLE dh ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_STIME structure to be written + /** + * @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. + * + * @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 + * @see ::mbg_get_synth + * @see ::mbg_set_synth + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_synth( MBG_DEV_HANDLE dh ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @brief Check if a device provides GPIO signal inputs and/or outputs + * + * @note This function should be preferred over ::mbg_dev_has_gpio, + * which has been deprecated. + * + * @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 + * @see ::mbg_get_gpio_cfg_limits + * @see ::mbg_get_gps_all_gpio_info + * @see ::mbg_set_gps_gpio_settings_idx + * @see ::mbg_get_gps_all_gpio_status + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_gpio( MBG_DEV_HANDLE dh ) ; - @see mbg_get_time() - */ - _MBG_API_ATTR int _MBG_API mbg_set_time( MBG_DEV_HANDLE dh, const PCPS_STIME *p ) ; + /** + * @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. + * + * @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 + * @see ::mbg_get_gps_ant_cable_len + * @see ::mbg_set_gps_ant_cable_len + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_cab_len( MBG_DEV_HANDLE dh ) ; /** - @brief Read the time when the device has last recently synchronized. + * @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). + * + * @note This function should be preferred over ::mbg_dev_has_ref_offs, + * which has been deprecated. + * + * @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 + * @see ::mbg_get_ref_offs + * @see ::mbg_set_ref_offs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ref_offs( MBG_DEV_HANDLE dh ) ; - Fills a ::PCPS_TIME structure with the date/time/status reporting - when the device was synchronized the last time to its time source, - e.g. the DCF77 signal, the GPS satellites, or similar. - The macro _pcps_has_sync_time() or the API call mbg_dev_has_sync_time() - check whether this call is supported by a device. + /** + * @brief Check if a device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS. + * + * These structures contain optional settings, controlled by flags. + * See ::MBG_OPT_SETTINGS and associated definitions. + * + * @note This function should be preferred over ::mbg_dev_has_opt_flags, + * which has been deprecated. + * + * @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 + * @see ::mbg_get_opt_info + * @see ::mbg_set_opt_settings + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_opt_flags( MBG_DEV_HANDLE dh ) ; - The macro _pcps_has_sync_time() checks whether this call - is supported by a device. + /** + * @brief Check if a device support reading/writing of UTC parameters. + * + * This API call checks if a device supports reading/writing a GPS %UTC + * parameter set via the PC bus. Reading/writing these parameters via the + * serial port using the Meinberg binary data protocol is supported by all + * 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 + * 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. + * + * @note This function should be preferred over ::mbg_dev_has_utc_parm, + * which has been deprecated. + * + * @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 + * @see ::mbg_get_utc_parm + * @see ::mbg_set_utc_parm + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_utc_parm( MBG_DEV_HANDLE dh ) ; - <b>Note:</b> If that information is not available on the board then - 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 available. + /** + * @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 + * supported which can be used to retrieve the correlation value + * and thus determine the quality of the input signal. + * + * @note This function should be preferred over ::mbg_dev_has_corr_info, + * which has been deprecated. + * + * @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 + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_get_corr_info + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_corr_info( MBG_DEV_HANDLE dh ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_TIME structure to be filled up + /** + * @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. + * + * @note This function should be preferred over ::mbg_dev_has_tr_distance, + * which has been deprecated. + * + * @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 + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_get_tr_distance + * @see ::mbg_set_tr_distance + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tr_distance( MBG_DEV_HANDLE dh ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @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. + * + * @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 + * @see ::mbg_get_debug_status + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_debug_status( MBG_DEV_HANDLE dh ) ; - @see mbg_get_time() - */ - _MBG_API_ATTR int _MBG_API mbg_get_sync_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ; + /** + * @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. + * + * @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 + * @see ::mbg_clr_evt_log + * @see ::mbg_get_num_evt_log_entries + * @see ::mbg_get_first_evt_log_entry + * @see ::mbg_get_next_evt_log_entry + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_evt_log( MBG_DEV_HANDLE dh ) ; /** - @brief Wait until the next second change, then return current time. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_dac_ctrl( MBG_DEV_HANDLE dh ) ; - Returns time in a ::PCPS_TIME structure similar to mbg_get_time(). + /** + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_receiver_info + */ + _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 ) ; - <b>Note:</b> This API call is supported under Windows only. - The call blocks until the kernel driver detects a second change - reported by the device. + /** + * @brief Check if a device supports large configuration data structures + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_gps_data preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_gps_data + */ + _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 ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_TIME structure to be filled up + /** + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_generic_io + */ + _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 ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_asic_version + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_asic_version" ) _MBG_API mbg_dev_has_asic_version( MBG_DEV_HANDLE dh, int *p ) ; - @see mbg_get_time() - */ - _MBG_API_ATTR int _MBG_API mbg_get_time_sec_change( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ; + /** + * @brief Check if a device supports the ::mbg_get_asic_features call. + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_asic_features preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_asic_features + * @see ::mbg_get_asic_features + */ + _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 Read the card's current time with high resolution, plus status. + * @brief Check if a device provides extended multi ref (XMR) inputs. + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_xmr preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_xmr + * @see @ref group_multi_ref_ext + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_xmr" ) _MBG_API mbg_dev_has_xmr( MBG_DEV_HANDLE dh, int *p ) ; - Fills up a ::PCPS_HR_TIME (High Resolution time) structure containing - the current %UTC time (seconds since 1970), %UTC offset, and status. - The macro _pcps_has_hr_time() or the API call mbg_dev_has_hr_time() - check whether this call is supported by a device. + /** + * @brief Check if a device supports GNSS configuration + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_gnss preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_gnss + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gnss" ) _MBG_API mbg_dev_is_gnss( MBG_DEV_HANDLE dh, int *p ) ; - <b>Note:</b> This API call provides a higher accuracy and resolution - than mbg_get_time(). However, it does not account for the latency - which is introduced when accessing the board. - The mbg_get_hr_time_cycles() and mbg_get_hr_time_comp() calls - provide ways to account for and/or compensate the latency. + /** + * @brief Check if a device is a GPS receiver + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_gps preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_gps + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gps" ) _MBG_API mbg_dev_is_gps( MBG_DEV_HANDLE dh, int *p ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_HR_TIME structure to be filled up + /** + * @brief Check if a device is a DCF77 receiver + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_dcf preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_dcf + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_dcf" ) _MBG_API mbg_dev_is_dcf( MBG_DEV_HANDLE dh, int *p ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @brief Check if a device supports demodulation of the DCF77 PZF code + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_pzf preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_pzf + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_pzf" ) _MBG_API mbg_dev_has_pzf( MBG_DEV_HANDLE dh, int *p ) ; - @see mbg_dev_has_hr_time() - @see mbg_get_time() - @see mbg_get_hr_time_cycles() - @see mbg_get_hr_time_comp() - */ - _MBG_API_ATTR int _MBG_API mbg_get_hr_time( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) ; + /** + * @brief Check if a device is a MSF receiver + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_msf preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_msf + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_msf" ) _MBG_API mbg_dev_is_msf( MBG_DEV_HANDLE dh, int *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. - The macro _pcps_has_event_time() or the API call mbg_dev_has_event_time() - check whether this call is supported by a device. + /** + * @brief Check if a device is a WWVB receiver + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_wwvb preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_wwvb + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_wwvb" ) _MBG_API mbg_dev_is_wwvb( MBG_DEV_HANDLE dh, int *p ) ; - <b>Note:</b> This is only supported by some special firmware. + /** + * @brief Check if a device is any long wave signal receiver + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_lwr preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_lwr + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_lwr" ) _MBG_API mbg_dev_is_lwr( MBG_DEV_HANDLE dh, int *p ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_TIME_STAMP structure to be written + /** + * @brief Check if a device provides a configurable IRIG input. + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_tcr preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_tcr + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_tcr" ) _MBG_API mbg_dev_is_irig_rx( MBG_DEV_HANDLE dh, int *p ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @brief Check if a device supports simple LAN interface API calls + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_lan_intf preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_lan_intf + */ + _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 ) ; - @see mbg_dev_has_event_time() - */ - _MBG_API_ATTR int _MBG_API mbg_set_event_time( MBG_DEV_HANDLE dh, const PCPS_TIME_STAMP *p ) ; + /** + * @brief Check if a device supports PTP configuration/status calls + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ptp preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_ptp + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ptp" ) _MBG_API mbg_dev_has_ptp( MBG_DEV_HANDLE dh, int *p ) ; /** - @brief Read the serial port configuration from an old type of device. + * @brief Check if a device supports PTP unicast feature/configuration + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ptp_unicast preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_ptp_unicast + */ + _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 ) ; - <b>Note:</b> Direct usage of this function is obsolete. + /** + * @brief Check if a device supports the HR_TIME functions + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_hr_time preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_hr_time + */ + _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 ) ; - The generic API function mbg_get_serial_settings() should be used instead - which fully supports the capabilities of current devices. + /** + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_fast_hr_timestamp + */ + _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 ) ; - The macro _pcps_has_serial() checks whether this call - is supported by a device. + /** + * @brief Check if a device supports configurable time scales + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_time_scale preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_time_scale + */ + _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 ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_SERIAL structure to be filled up + /** + * @brief Check if a device supports setting an event time + * + * @note This is only supported by some customized devices + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_event_time preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_event_time + */ + _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 ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_ucap + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ucap" ) _MBG_API mbg_dev_has_ucap( MBG_DEV_HANDLE dh, int *p ) ; - @see \ref group_cmd_bytes - @see mbg_get_serial_settings() - */ - _MBG_API_ATTR int _MBG_API mbg_get_serial( MBG_DEV_HANDLE dh, PCPS_SERIAL *p ) ; + /** + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @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 Write the serial port configuration to an old type of device. + * @brief Check if a device supports timezone configuration using the ::TZDL structure + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tzdl preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_tzdl + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tzdl" ) _MBG_API mbg_dev_has_tzdl( MBG_DEV_HANDLE dh, int *p ) ; - <b>Note:</b> Direct usage of this function is obsolete. + /** + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_pcps_tzdl + */ + _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 ) ; - The generic API function mbg_save_serial_settings() should be used instead - which fully supports the capabilities of current devices. + /** + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_tzcode + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tzcode" ) _MBG_API mbg_dev_has_tzcode( MBG_DEV_HANDLE dh, int *p ) ; - The macro _pcps_has_serial() checks whether this call - is supported by a device. + /** + * @brief Check if a device supports any kind of timezone configuration + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tz preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_tz + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tz" ) _MBG_API mbg_dev_has_tz( MBG_DEV_HANDLE dh, int *p ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_SERIAL structure to be written + /** + * @brief Check if a device provides either an IRIG input or output + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_irig + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig" ) _MBG_API mbg_dev_has_irig( MBG_DEV_HANDLE dh, int *p ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @brief Check if a device provides a configurable IRIG output + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig_tx preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_irig_tx + */ + _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 ) ; - @see \ref group_cmd_bytes - @see mbg_save_serial_settings() - */ - _MBG_API_ATTR int _MBG_API mbg_set_serial( MBG_DEV_HANDLE dh, const PCPS_SERIAL *p ) ; + /** + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_irig_ctrl_bits + */ + _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 Read time zone/daylight saving configuration code from a device. + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @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 ) ; - The APIs using TZCODE are only supported by some simpler cards - and allow just a very basic configuration. + /** + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_irig_time + */ + _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 ) ; - The macro _pcps_has_tzcode() or the API call mbg_dev_has_tzcode() - check whether this call is supported by a device. + /** + * @brief Check if a device provides the level of its inputs signal + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_signal preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_signal + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_signal" ) _MBG_API mbg_dev_has_signal( MBG_DEV_HANDLE dh, int *p ) ; - Other cards may support the mbg_get_pcps_tzdl() or mbg_get_gps_tzdl() - calls instead which allow for a more detailed configuration of the - time zone and daylight saving settings. + /** + * @brief Check if a device provides a modulation signal + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_mod preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_mod + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_mod" ) _MBG_API mbg_dev_has_mod( MBG_DEV_HANDLE dh, int *p ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_TZCODE structure to be filled up + /* (Intentionally excluded from Doxygen) + * @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 + * rather than ::DEFAULT_BAUD_RATES_DCF. + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_serial_hs preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_serial_hs + */ + _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 ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @brief Check if a device provides a programmable frequency synthesizer + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_synth preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_synth + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_synth" ) _MBG_API mbg_dev_has_synth( MBG_DEV_HANDLE dh, int *p ) ; - @see mbg_dev_has_tzcode() - @see mbg_set_tzcode() - @see mbg_get_pcps_tzdl() - @see mbg_get_gps_tzdl() - @see \ref group_cmd_bytes - */ - _MBG_API_ATTR int _MBG_API mbg_get_tzcode( MBG_DEV_HANDLE dh, PCPS_TZCODE *p ) ; + /** + * @brief Check if a device provides GPIO signal inputs and/or outputs + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_gpio preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_gpio + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_gpio" ) _MBG_API mbg_dev_has_gpio( MBG_DEV_HANDLE dh, int *p ) ; /** - @brief Write time zone/daylight saving configuration code to a device. + * @brief Check if a device supports configuration of antenna cable length + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_cab_len preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_cab_len + */ + _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 ) ; - The APIs using TZCODE are only supported by some simpler cards - and allow just a very basic configuration. + /** + * @brief Check if a device provides a configurable ref time offset + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ref_offs preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_ref_offs + */ + _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 ) ; - The macro _pcps_has_tzcode() or the API call mbg_dev_has_tzcode() - check whether this call is supported by a device. + /** + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_opt_flags + */ + _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 ) ; - Other cards may support the mbg_set_pcps_tzdl() or mbg_set_gps_tzdl() - calls instead which allow for a more detailed configuration of the - time zone and daylight saving settings. + /** + * @brief Check if a device support reading/writing of ::UTC parameters + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_utc_parm preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_utc_parm + */ + _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 ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_TZCODE structure to be written + /** + * @brief Check if a device supports reading correlation info + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_corr_info preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_corr_info + */ + _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 ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @brief Check if a device supports configurable distance from transmitter + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tr_distance preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_tr_distance + */ + _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 ) ; - @see mbg_dev_has_tzcode() - @see mbg_get_tzcode() - @see mbg_set_pcps_tzdl() - @see mbg_set_gps_tzdl() - @see \ref group_cmd_bytes - */ - _MBG_API_ATTR int _MBG_API mbg_set_tzcode( MBG_DEV_HANDLE dh, const PCPS_TZCODE *p ) ; + /** + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_debug_status + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_debug_status" ) _MBG_API mbg_dev_has_debug_status( MBG_DEV_HANDLE dh, int *p ) ; /** - @brief Read time zone/daylight saving parameters from a device. + * @brief Check if a device provides an on-board event log. + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_evt_log preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_evt_log + */ + _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 ) ; - This function fills up a ::PCPS_TZDL structure which supports a more - detailed configuration of time zone and daylight saving than the TZCODE - structure. + /** + * @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. + * + * Under Windows a 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. + * + * 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". + * + * @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 + */ + _MBG_API_ATTR int _MBG_API mbg_dev_fn_from_dev_idx( char *s, int max_len, int dev_idx ) ; - The macro _pcps_has_pcps_tzdl() or the API call mbg_dev_has_pcps_tzdl() - check whether this call is supported by a device. + /** + * @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. + * + * 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 + * + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs + */ + _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device( int dev_idx ) ; - Other cards may support the mbg_get_tzcode() or mbg_get_gps_tzdl() - calls instead. + /** + * @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. + * + * For details and similar functions see @ref mbgdevio_open_fncs. + * + * @param[in] dev_fn The device file name + * + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs + * @see ::MBG_DEV_FN + */ + _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_dev_fn( const char *dev_fn ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_TZDL structure to be filled up + /** + * @brief Open a device specified by a device file name + * + * @deprecated This function is deprecated, use + * ::mbg_open_device_by_dev_fn preferably. + * + * 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. + * + * For details and similar functions see @ref mbgdevio_open_fncs. + * + * @param[in] dev_fn The device file name, see ::MBG_DEV_FN + * + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs + * @see ::MBG_DEV_FN + */ + _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 ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @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. + * + * @return The number of devices found + * + * @see ::mbg_find_devices_with_names + * @see ::mbg_open_device + * @see @ref mbgdevio_open_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_find_devices( void ) ; - @see mbg_dev_has_pcps_tzdl() - @see mbg_set_pcps_tzdl() - @see mbg_get_tzcode() - @see mbg_get_gps_tzdl() - @see \ref group_cmd_bytes - */ - _MBG_API_ATTR int _MBG_API mbg_get_pcps_tzdl( MBG_DEV_HANDLE dh, PCPS_TZDL *p ) ; + /** + * @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. + * + * This can be used e.g. to populate a device selection dialog + * in a configuration program. + * + * 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). + * + * @return The number of present devices + * + * @see ::mbg_free_device_name_list + * @see ::mbg_find_devices + * @see ::MBG_DEV_NAME + */ + _MBG_API_ATTR int _MBG_API mbg_find_devices_with_names( MBG_DEV_NAME_LIST_ENTRY **p_list, int max_devices ) ; /** - @brief Write time zone/daylight saving parameters to a device. + * @brief Free the memory allocated for a list of ::MBG_DEV_NAME_LIST_ENTRY entries. + * + * 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. + * + * @see ::mbg_find_devices_with_names + */ + _MBG_API_ATTR void _MBG_API mbg_free_device_name_list( MBG_DEV_NAME_LIST_ENTRY *list ) ; - This function passes a ::PCPS_TZDL structure to a device which supports - a more detailed configuration of time zone and daylight saving than the - TZCODE structure. + /** + * @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 + * 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 + * + * @see ::snprint_dev_name + * @see ::MBG_DEV_NAME + * @see ::MBG_DEV_NAME_FMT + */ + _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 ) ; - The macro _pcps_has_pcps_tzdl() or the API call mbg_dev_has_pcps_tzdl() - check whether this call is supported by a device. - Other cards may support the mbg_set_tzcode() or mbg_set_gps_tzdl() - calls instead. + /** + * @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. + * + * 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 + * + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs + * @see ::MBG_DEV_NAME + * @see ::MBG_MATCH_MODES + */ + _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const MBG_DEV_NAME srch_name, int selection_mode ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_TZDL structure to be written + /** + * @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 + * + * @see @ref mbgdevio_open_fncs + */ + _MBG_API_ATTR void _MBG_API mbg_close_device( MBG_DEV_HANDLE *dev_handle ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @brief Read information about the driver handling a given device + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p A ::PCPS_DRVR_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, 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 ) ; - @see mbg_dev_has_pcps_tzdl() - @see mbg_get_pcps_tzdl() - @see mbg_set_tzcode() - @see mbg_set_gps_tzdl() - @see \ref group_cmd_bytes - */ - _MBG_API_ATTR int _MBG_API mbg_set_pcps_tzdl( MBG_DEV_HANDLE dh, const PCPS_TZDL *p ) ; + /** + * @brief Read detailed device information + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] *p A ::PCPS_DEV structure to be filled up + * + * @return ::MBG_SUCCESS on success, 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 %UTC offset configuration of the reference time from a device. + * @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 + * 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 + * + * @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 ) ; - 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 - signal) does not provide this information. + /* (Intentionally excluded from Doxygen) + * Generic read function which writes a command code to a device + * and reads a number of replied data to a generic buffer. + * + * <b>Warning</b>: This is for debugging purposes only! + * The specialized API calls should be used preferably. + * 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 + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_generic_write + * @see ::mbg_generic_read_gps + * @see ::mbg_generic_write_gps + * @see ::mbg_generic_io + */ + _MBG_API_ATTR int _MBG_API mbg_generic_read( MBG_DEV_HANDLE dh, int cmd, void *p, int size ) ; - The macro _pcps_has_ref_offs() or the API call mbg_dev_has_ref_offs() - check whether this call is supported by a device. + /* (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. + * The function ::mbg_chk_dev_has_gps_data can be used to check + * whether this call is supported by a device. + * + * <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 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 + * + * @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 + * @see ::mbg_generic_read + * @see ::mbg_generic_write + * @see ::mbg_generic_io + */ + _MBG_API_ATTR int _MBG_API mbg_generic_read_gps( MBG_DEV_HANDLE dh, int cmd, void *p, int size ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_REF_OFFS value to be filled up + /* (Intentionally excluded from Doxygen) + * Generic write function which 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. + * 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 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 + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_generic_read + * @see ::mbg_generic_read_gps + * @see ::mbg_generic_write_gps + * @see ::mbg_generic_io + */ + _MBG_API_ATTR int _MBG_API mbg_generic_write( MBG_DEV_HANDLE dh, int cmd, const void *p, int size ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /* (Intentionally excluded from Doxygen) + * Generic write function which 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. + * + * <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 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 + * + * @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 + * @see ::mbg_generic_read + * @see ::mbg_generic_write + * @see ::mbg_generic_io + */ + _MBG_API_ATTR int _MBG_API mbg_generic_write_gps( MBG_DEV_HANDLE dh, int cmd, const void *p, int size ) ; - @see mbg_dev_has_ref_offs() - @see mbg_set_ref_offs() - @see ::PCPS_GET_REF_OFFS - */ - _MBG_API_ATTR int _MBG_API mbg_get_ref_offs( MBG_DEV_HANDLE dh, MBG_REF_OFFS *p ) ; + /* (Intentionally excluded from Doxygen) + * 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 + * + * @see ::mbg_chk_dev_has_generic_io + * @see ::mbg_generic_read + * @see ::mbg_generic_write + * @see ::mbg_generic_read_gps + * @see ::mbg_generic_write_gps + */ + _MBG_API_ATTR int _MBG_API mbg_generic_io( MBG_DEV_HANDLE dh, int type, const void *in_p, int in_sz, void *out_p, int out_sz ) ; /** - @brief Write the %UTC offset configuration of the reference time to a device. + * @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. + * + * This call is supported by any 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 + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_legacy_time_fncs + * @see ::mbg_get_hr_time + * @see ::mbg_set_time + * @see ::mbg_get_sync_time + */ + _MBG_API_ATTR int _MBG_API mbg_get_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ; - 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 - signal) does not provide this information. + /** + * @brief Set the device's on-board clock to a given date and time. + * + * The macro ::_pcps_can_set_time checks whether + * this call is supported by a device. + * + * @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 + * + * @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 ) ; - The macro _pcps_has_ref_offs() or the API call mbg_dev_has_ref_offs() - check whether this call is supported by a device. + /** + * @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, + * e.g. the DCF77 signal, the GPS satellites, or similar. + * + * 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 + * 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". + * + * @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 + * + * @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 ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_REF_OFFS value to be written + /** + * @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. + * 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 + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_legacy_time_fncs + * @see ::mbg_get_time + */ + _MBG_API_ATTR int _MBG_API mbg_get_time_sec_change( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @brief Read the card's current time with high resolution, 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 API call ::mbg_chk_dev_has_hr_time checks whether + * this call is supported by a device. + * + * 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 + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_hr_time_fncs + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_get_hr_time( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) ; - @see mbg_dev_has_ref_offs() - @see mbg_get_ref_offs() - @see ::PCPS_SET_REF_OFFS - */ - _MBG_API_ATTR int _MBG_API mbg_set_ref_offs( MBG_DEV_HANDLE dh, const MBG_REF_OFFS *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. + * 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. + * + * @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 + * + * @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 a ::MBG_OPT_INFO structure containing optional settings, controlled by flags. + * @brief Read the serial port configuration from an old type of device + * + * @deprecated Direct usage of this function is deprecated. The generic + * API function ::mbg_get_serial_settings should be used instead + * which fully supports the capabilities of current devices. + * + * The macro ::_pcps_has_serial checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::PCPS_SERIAL structure to be filled up + * + * @return ::MBG_SUCCESS on success, 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 ) ; - The ::MBG_OPT_INFO structure contains a mask of supported flags plus the current - settings of those flags. - The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags() - check whether this call is supported by a device. + /** + * @brief Write the serial port configuration to an old type of device + * + * @deprecated Direct usage of this function is deprecated. The generic + * API function ::mbg_save_serial_settings should be used instead + * which fully supports the capabilities of current devices. + * + * The macro ::_pcps_has_serial checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PCPS_SERIAL structure to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_save_serial_settings + */ + _MBG_API_ATTR int _MBG_API mbg_set_serial( MBG_DEV_HANDLE dh, const PCPS_SERIAL *p ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_OPT_INFO structure to be filled up + /** + * @brief Read time zone/daylight saving configuration code from a device. + * + * The APIs using ::TZCODE are only supported by some simpler cards + * and allow just a very basic configuration. + * + * The API call ::mbg_chk_dev_has_tzcode checks whether + * this call is supported by a device. + * + * Other devices may support the ::mbg_get_pcps_tzdl or ::mbg_get_gps_tzdl + * calls instead which allow for a more detailed configuration of the + * time zone and daylight saving settings. + * + * @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 + * + * @see ::mbg_chk_dev_has_tzcode + * @see ::mbg_set_tzcode + * @see ::mbg_get_pcps_tzdl + * @see ::mbg_get_gps_tzdl + */ + _MBG_API_ATTR int _MBG_API mbg_get_tzcode( MBG_DEV_HANDLE dh, PCPS_TZCODE *p ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @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 API call ::mbg_chk_dev_has_tzcode checks whether + * this call is supported by a device. + * + * Other devices may support the ::mbg_set_pcps_tzdl or ::mbg_set_gps_tzdl + * calls instead which allow for a more detailed configuration of the + * time zone and daylight saving settings. + * + * @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 + * + * @see ::mbg_chk_dev_has_tzcode + * @see ::mbg_get_tzcode + * @see ::mbg_set_pcps_tzdl + * @see ::mbg_set_gps_tzdl + */ + _MBG_API_ATTR int _MBG_API mbg_set_tzcode( MBG_DEV_HANDLE dh, const PCPS_TZCODE *p ) ; - @see mbg_dev_has_opt_flags() - @see mbg_set_opt_settings() - */ - _MBG_API_ATTR int _MBG_API mbg_get_opt_info( MBG_DEV_HANDLE dh, MBG_OPT_INFO *p ) ; + /** + * @brief Read time zone/daylight saving parameters from a device. + * + * This function fills up a ::PCPS_TZDL structure which supports a more + * detailed configuration of time zone and daylight saving than the ::TZCODE + * structure. + * + * The API call ::mbg_chk_dev_has_pcps_tzdl checks whether + * this call is supported by a device. + * + * Other devices may support the ::mbg_get_tzcode or ::mbg_get_gps_tzdl + * calls instead. + * + * @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 + * + * @see ::mbg_chk_dev_has_pcps_tzdl + * @see ::mbg_set_pcps_tzdl + * @see ::mbg_get_tzcode + * @see ::mbg_get_gps_tzdl + */ + _MBG_API_ATTR int _MBG_API mbg_get_pcps_tzdl( MBG_DEV_HANDLE dh, PCPS_TZDL *p ) ; /** - @brief Write a ::MBG_OPT_SETTINGS structure containing optional device settings. + * @brief Write time zone/daylight saving parameters to a device. + * + * This function passes a ::PCPS_TZDL structure to a device which supports + * a more detailed configuration of time zone and daylight saving than the + * ::TZCODE structure. + * + * 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 + * 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 + * + * @see ::mbg_chk_dev_has_pcps_tzdl + * @see ::mbg_get_pcps_tzdl + * @see ::mbg_set_tzcode + * @see ::mbg_set_gps_tzdl + */ + _MBG_API_ATTR int _MBG_API mbg_set_pcps_tzdl( MBG_DEV_HANDLE dh, const PCPS_TZDL *p ) ; - The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags() - check whether this call is supported by a device. - The ::MBG_OPT_INFO structure should be read first to check which of the specified - flag is supported by a device. + /** + * @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 + * signal) does not provide this information. + * + * The API call ::mbg_chk_dev_has_ref_offs 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 ::MBG_REF_OFFS value to be filled up. + * + * @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 + */ + _MBG_API_ATTR int _MBG_API mbg_get_ref_offs( MBG_DEV_HANDLE dh, MBG_REF_OFFS *p ) ; - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_OPT_SETTINGS structure to be written + /** + * @brief Write the %UTC offset configuration of the reference time to a device. + * + * This parameter is used to specify the %UTC offset of an incoming + * reference time signal if a kind of time signal e.g. an IRIG input + * signal) does not provide this information. + * + * The API call ::mbg_chk_dev_has_ref_offs 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 ::MBG_REF_OFFS value to be written. + * + * @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 + */ + _MBG_API_ATTR int _MBG_API mbg_set_ref_offs( MBG_DEV_HANDLE dh, const MBG_REF_OFFS *p ) ; - @return ::MBG_SUCCESS or error code returned by device I/O control function. + /** + * @brief Read a ::MBG_OPT_INFO structure containing optional settings, controlled by flags + * + * The ::MBG_OPT_INFO structure contains a mask of supported flags plus the current + * settings of those flags. + * + * The API call ::mbg_chk_dev_has_opt_flags 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 ::MBG_OPT_INFO structure to be filled up + * + * @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 + */ + _MBG_API_ATTR int _MBG_API mbg_get_opt_info( MBG_DEV_HANDLE dh, MBG_OPT_INFO *p ) ; - @see mbg_dev_has_opt_flags() - @see mbg_get_opt_info() - */ + /** + * @brief Write a ::MBG_OPT_SETTINGS structure containing optional device settings. + * + * The API call ::mbg_chk_dev_has_opt_flags checks whether + * this call is supported by a device. + * + * ::mbg_get_opt_info should be called first to check which of + * the specified flags is supported by a device. + * + * @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 + * + * @see ::mbg_chk_dev_has_opt_flags + * @see ::mbg_get_opt_info + */ _MBG_API_ATTR int _MBG_API mbg_set_opt_settings( MBG_DEV_HANDLE dh, const MBG_OPT_SETTINGS *p ) ; /** - @brief Read the current IRIG input settings plus the supported settings. - - Calling this function directly is usually obsolete. The function - mbg_get_all_irig_rx_info() should be used instead which also reads some - other associated parameters affecting the behaviour of the IRIG input. - - The macro _pcps_is_irig_rx() or the API call mbg_dev_is_irig_rx() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an ::IRIG_INFO structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_all_irig_rx_info() - @see mbg_set_irig_rx_settings() - @see mbg_dev_is_irig_rx() - @see mbg_dev_has_irig_tx() - @see mbg_dev_has_irig() - @see \ref group_icode - */ + * @brief Read the current IRIG input settings plus capabilities + * + * @deprecated Calling this function directly is deprecated. The function + * ::mbg_get_all_irig_rx_info should be used instead which also reads some + * other associated parameters affecting the behaviour of the IRIG input. + * + * The API call ::mbg_chk_dev_is_tcr checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] *p An ::IRIG_INFO structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_get_all_irig_rx_info + * @see ::mbg_set_irig_rx_settings + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_has_irig + * @see @ref group_icode + */ _MBG_API_ATTR int _MBG_API mbg_get_irig_rx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p ) ; /** - @brief Write an ::IRIG_SETTINGS structure to a device to configure an IRIG input. - - Calling this function directly is usually obsolete. The function - mbg_set_all_irig_rx_info() should be used instead which also writes some - other associated parameters affecting the behaviour of the IRIG input. - - The macro _pcps_is_irig_rx() or the API call mbg_dev_is_irig_rx() - check whether this call is supported by a device. - The ::IRIG_INFO structure should be read first to determine the possible - settings supported by this card's IRIG input. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::IRIG_SETTINGS structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_set_all_irig_rx_info() - @see mbg_get_irig_rx_info() - @see mbg_dev_is_irig_rx() - @see mbg_dev_has_irig_tx() - @see mbg_dev_has_irig() - @see \ref group_icode - */ + * @brief Write an ::IRIG_SETTINGS structure to a device to configure an IRIG input. + * + * @deprecated Calling this function directly is deprecated. The function + * ::mbg_save_all_irig_rx_settings should be used instead which also writes some + * other associated parameters affecting the behaviour of the IRIG input. + * + * The API call ::mbg_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. + * + * @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 + * + * @see ::mbg_save_all_irig_rx_settings + * @see ::mbg_get_irig_rx_info + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_has_irig + * @see @ref group_icode + */ _MBG_API_ATTR int _MBG_API mbg_set_irig_rx_settings( MBG_DEV_HANDLE dh, const IRIG_SETTINGS *p ) ; /** - @brief Read all IRIG input configuration information from a device. - - @param dh Valid handle to a Meinberg device - @param pdev Pointer to the device's ::PCPS_DEV structure - @param p_irig_info Pointer to a ::IRIG_SETTINGS structure to be written - @param p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written - @param p_opt_info Pointer to a ::MBG_OPT_SETTINGS structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_save_all_irig_rx_settings() - @see mbg_set_irig_rx_settings() - @see mbg_set_ref_offs() - @see mbg_set_opt_settings() -*/ + * @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 + * + * @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 + * @see ::mbg_set_ref_offs + * @see ::mbg_set_opt_settings + */ _MBG_API_ATTR int _MBG_API mbg_get_all_irig_rx_info( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, IRIG_INFO *p_irig_info, MBG_REF_OFFS *p_ref_offs, MBG_OPT_INFO *p_opt_info ) ; /** - @brief Write all IRIG input configuration settings to a device. - - The macro _pcps_is_irig_rx() or the API call mbg_dev_is_irig_rx() - check whether this call is supported by a device. - The ::IRIG_INFO structure should be read first to determine the possible - settings supported by this card's IRIG input. - - @param dh Valid handle to a Meinberg device - @param pdev Pointer to the device's ::PCPS_DEV structure - @param p_irig_settings Pointer to a ::IRIG_SETTINGS structure to be written - @param p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written - @param p_opt_settings Pointer to a ::MBG_OPT_SETTINGS structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_all_irig_rx_info() - @see mbg_set_irig_rx_settings() - @see mbg_set_ref_offs() - @see mbg_set_opt_settings() -*/ + * @brief Write all IRIG input configuration settings to a device. + * + * The API call ::mbg_chk_dev_is_tcr checks whether + * this call is supported by a device. + * ::mbg_get_all_irig_rx_info should be called before to determine + * 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 + * + * @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 + * @see ::mbg_set_ref_offs + * @see ::mbg_set_opt_settings + */ _MBG_API_ATTR int _MBG_API mbg_save_all_irig_rx_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const IRIG_SETTINGS *p_irig_settings, const MBG_REF_OFFS *p_ref_offs, const MBG_OPT_SETTINGS *p_opt_settings ) ; /** - @brief Check if a device supports the mbg_get_irig_ctrl_bits() call. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_irig_ctrl_bits() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Read the control function bits received from an incoming IRIG signal. - - This function fills a ::MBG_IRIG_CTRL_BITS structure with the control function - bits decoded from the incoming IRIG signal. - - The meaning of these bits depends on the type of IRIG code frame format. - - 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, - DST status, leap second warning, etc. - - For most IRIG code formats, however, these bits are reserved, i.e. not used - at all, or application defined, depending on the configuration of the IRIG - generator providing the IRIG signal. - - In the latter case the application has to evaluate the received control function - bits and can use this function to retrieve these bits from the receiver device. - - The macro _pcps_has_irig_ctrl_bits() or the API call mbg_dev_has_irig_ctrl_bits() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_IRIG_CTRL_BITS type to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_irig_ctrl_bits() -*/ + * @brief Read the control function bits received from an incoming IRIG signal. + * + * This function fills an ::MBG_IRIG_CTRL_BITS structure with the control function + * bits decoded from the incoming IRIG signal. + * + * The meaning of these bits depends on the type of IRIG code frame format. + * + * 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, + * DST status, leap second warning, etc. + * + * For most IRIG code formats, however, these bits are reserved, i.e. not used + * at all, or application defined, depending on the configuration of the IRIG + * generator providing the IRIG signal. + * + * In the latter case the application has to evaluate the received control function + * bits and can use this function to retrieve these bits from the receiver device. + * + * The API call ::mbg_chk_dev_has_irig_ctrl_bits 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 ::MBG_IRIG_CTRL_BITS type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_irig_ctrl_bits + */ _MBG_API_ATTR int _MBG_API mbg_get_irig_ctrl_bits( MBG_DEV_HANDLE dh, MBG_IRIG_CTRL_BITS *p ) ; /** - @brief Check if a device supports the mbg_get_raw_irig_data() call. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_raw_irig_data() - @see mbg_get_raw_irig_data_on_sec_change() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_raw_irig_data( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Read raw IRIG data from an IRIG receiver. - - This function fills a ::MBG_RAW_IRIG_DATA structure with the raw data bits received - from the incoming IRIG signal. This enables an application itself to decode the - information provided by the IRIG signal. - - The macro _pcps_has_raw_irig_data() or the API call mbg_dev_has_raw_irig_data() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_raw_irig_data() - @see mbg_get_raw_irig_data_on_sec_change() -*/ + * @brief Read raw IRIG data from an IRIG receiver. + * + * This function reads an ::MBG_RAW_IRIG_DATA structure with the raw data bits received + * from the incoming IRIG signal. This enables an application itself to decode the + * information provided by the IRIG signal. + * + * The API call ::mbg_chk_dev_has_raw_irig_data 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 ::MBG_RAW_IRIG_DATA type to be filled up + * + * @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 + */ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data( MBG_DEV_HANDLE dh, MBG_RAW_IRIG_DATA *p ) ; /** - @brief Wait for second changeover then read raw IRIG data from an IRIG receiver. - - This function waits until the second of the device's on-board time rolls over, and - then reads the last recent raw IRIG data from the device. - - The macro _pcps_has_raw_irig_data() or the API call mbg_dev_has_raw_irig_data() - check whether this call is supported by a device. - - <b>Note:</b> The mbg_get_time_sec_change() function called by this function is - supported under Windows only, so this function can also only be used under Windows. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_raw_irig_data() - @see mbg_get_raw_irig_data() - @see mbg_get_time_sec_change() -*/ + * @brief Wait for second changeover then read raw IRIG data from an IRIG receiver. + * + * This function waits until the second of the device's on-board time rolls over, + * and then reads the last recent raw IRIG data from the device. + * + * 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. + * + * @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 + * + * @see ::mbg_chk_dev_has_raw_irig_data + * @see ::mbg_get_raw_irig_data + * @see ::mbg_get_time_sec_change + */ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data_on_sec_change( MBG_DEV_HANDLE dh, MBG_RAW_IRIG_DATA *p ) ; /** - @brief Check if a device supports the mbg_get_irig_time() call. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_irig_time() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_irig_time( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Read the IRIG time and day-of-year number from an IRIG receiver. - - Fills up a ::PCPS_IRIG_TIME structure with the raw IRIG day-of-year number - and time decoded from the latest IRIG input frame. If the configured IRIG code - also contains the year number then the year number is also returned, otherwise - the returned year number is 0xFF. - - The macro _pcps_has_irig_time() or the API call mbg_dev_has_irig_time() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_IRIG_TIME type to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_irig_time() -*/ + * @brief Read the IRIG time and day-of-year number from an IRIG receiver. + * + * 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 + * the returned year number is 0xFF. + * + * The API call ::mbg_chk_dev_has_irig_time checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::PCPS_IRIG_TIME type to be filled up. + * + * @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. - - The macro _pcps_can_clr_ucap_buff() or the API call mbg_dev_can_clr_ucap_buff() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_can_clr_ucap_buff() - @see mbg_get_ucap_entries() - @see mbg_get_ucap_event() - */ + * @brief Clear a device's 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 + * + * @see ::mbg_chk_dev_can_clr_ucap_buff + * @see ::mbg_get_ucap_entries + * @see ::mbg_get_ucap_event + */ _MBG_API_ATTR int _MBG_API mbg_clr_ucap_buff( MBG_DEV_HANDLE dh ) ; /** - @brief Read information on a device's event capture buffer. - - Fills a ::PCPS_UCAP_ENTRIES structure with the number of user capture - events actually stored in the FIFO buffer, and the maximum number of - events that can be held by the buffer. - - The macro _pcps_has_ucap() or the API call mbg_dev_has_ucap() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_UCAP_ENTRIES structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_ucap() - @see mbg_get_ucap_entries() - @see mbg_get_ucap_event() - */ + * @brief Read information on a device's 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 + * events that can be held by the buffer. + * + * The API call ::mbg_chk_dev_has_ucap checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::PCPS_UCAP_ENTRIES structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ucap + * @see ::mbg_get_ucap_entries + * @see ::mbg_get_ucap_event + */ _MBG_API_ATTR int _MBG_API mbg_get_ucap_entries( MBG_DEV_HANDLE dh, PCPS_UCAP_ENTRIES *p ) ; /** - @brief Retrieve a single time capture event from the on-board FIFO buffer. - - 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 - and the fractions of the returned timestamp are 0. - - The macro _pcps_has_ucap() or the API call mbg_dev_has_ucap() - check whether this call is supported by a device. - - <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. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_HR_TIME structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_ucap() - @see mbg_get_ucap_entries() - @see mbg_clr_ucap_buff() - */ + * @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 + * and the fractions of the returned timestamp are 0. + * + * The API call ::mbg_chk_dev_has_ucap checks whether + * this call is supported by a device. + * + * <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. + * + * @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 + * + * @see ::mbg_chk_dev_has_ucap + * @see ::mbg_get_ucap_entries + * @see ::mbg_clr_ucap_buff + */ _MBG_API_ATTR int _MBG_API mbg_get_ucap_event( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) ; /** - @brief Read the card's time zone/daylight saving parameters. - - This function returns the time zone/daylight saving parameters - in a ::TZDL structure. - - The macro _pcps_has_tzdl() or the API call mbg_dev_has_tzdl() - check whether 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() - or mbg_get_pcps_tzdl() calls instead. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::TZDL structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_tzdl() - @see mbg_set_gps_tzdl() - @see mbg_get_tzcode() - @see mbg_get_pcps_tzdl() - @see \ref group_tzdl - */ + * @brief Read the card's time zone/daylight saving parameters + * + * This function returns the time zone/daylight saving parameters + * in a ::TZDL structure. + * + * The API call ::mbg_chk_dev_has_tzdl checks whether + * 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 + * 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 + * + * @see ::mbg_chk_dev_has_tzdl + * @see ::mbg_set_gps_tzdl + * @see ::mbg_get_tzcode + * @see ::mbg_get_pcps_tzdl + * @see @ref group_tzdl + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_tzdl( MBG_DEV_HANDLE dh, TZDL *p ) ; /** - @brief Write the card's time zone/daylight saving parameters. - - This function writes the time zone/daylight saving parameters - in a ::TZDL structure to a device. - - The macro _pcps_has_tzdl() or the API call mbg_dev_has_tzdl() - check whether 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() - or mbg_set_pcps_tzdl() calls instead. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::TZDL structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_tzdl() - @see mbg_get_gps_tzdl() - @see mbg_set_tzcode() - @see mbg_set_pcps_tzdl() - @see \ref group_tzdl - */ + * @brief Write the card's time zone/daylight saving parameters. + * + * This function writes the time zone/daylight saving parameters + * in a ::TZDL structure to a device. + * + * The API call ::mbg_chk_dev_has_tzdl checks whether + * 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 + * 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 + * + * @see ::mbg_chk_dev_has_tzdl + * @see ::mbg_get_gps_tzdl + * @see ::mbg_set_tzcode + * @see ::mbg_set_pcps_tzdl + * @see @ref group_tzdl + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_tzdl( MBG_DEV_HANDLE dh, const TZDL *p ) ; /** - @brief Retrieve the software revision of a GPS receiver. - - This call is obsolete but still supported for compatibility - with older GPS cards. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> The function mbg_get_gps_receiver_info() should - be used instead, if supported by the card. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::SW_REV structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_is_gps() - @see mbg_get_gps_receiver_info() - */ + * @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 + * the software revision is part of the ::RECEIVER_INFO + * structure. See ::mbg_setup_receiver_info which takes + * care of the different options. + * + * 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[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 + * + * @see ::mbg_setup_receiver_info + * @see ::mbg_chk_dev_is_gps + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_sw_rev( MBG_DEV_HANDLE dh, SW_REV *p ) ; /** - @brief Retrieve the status of the battery buffered GPS variables. - - These GPS variables hold some parameters sent by the GPS satellites - which are required for proper operation. If the saved set of parameters - is not complete then the GPS receiver stays in COLD BOOT mode until - all data have been received and thus all data sets are valid. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::BVAR_STAT structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. -*/ + * @brief Retrieve the status of the battery buffered GPS variables. + * + * GPS receivers require some navigational data set to be available + * to be able to decode position and time accurately. This data set + * is transmitted periodically by the satellites, so it can + * simply be collected if it's not available. + * + * 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 + * 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 + * 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 + * + * @see ::mbg_chk_dev_is_gps + * @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. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This API call is pretty slow, so the mbg_get_hr_time_..() - or mbg_get_fast_hr_timestamp...() group of calls should be used preferably. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::TTM structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_hr_time() - @see mbg_get_fast_hr_timestamp() -*/ + * @brief Read the current board time using a ::TTM structure + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> This API call is pretty slow, so ::mbg_get_hr_time or + * ::mbg_get_fast_hr_timestamp or associated calls should be used 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 + * + * @see ::mbg_get_hr_time + * @see ::mbg_get_fast_hr_timestamp + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_time( MBG_DEV_HANDLE dh, TTM *p ) ; /** - @brief Set the time on a GPS receiver device. - - Write a ::TTM structure to a GPS receiver in order to set the - on-board date and time. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::TTM structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. -*/ + * @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). + * + * 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 + * + * @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. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This function is obsolete since it is only - supported by a certain class of devices and can handle only - up to 2 ports. The generic function mbg_get_serial_settings() - should be used instead. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PORT_PARM structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_serial_settings() -*/ + * @brief Read a ::PORT_PARM structure with a device's serial port configuration. + * + * @deprecated This function is deprecated, use ::mbg_get_serial_settings preferably. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> This function is deprecated since it is only + * supported by a certain class of devices and can handle only + * up to 2 serial ports. The generic function ::mbg_get_serial_settings + * should be used instead. + * + * @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 + * + * @see ::mbg_get_serial_settings + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_port_parm( MBG_DEV_HANDLE dh, PORT_PARM *p ) ; /** - @brief Write a ::PORT_PARM structure to configure the on-board serial ports. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This function is obsolete since it is only - supported by a certain class of devices and can handle only - up to 2 ports. The generic function mbg_save_serial_settings() - should be used instead. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PORT_PARM structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_save_serial_settings() -*/ + * @brief Write a ::PORT_PARM structure to configure the on-board serial ports. + * + * @deprecated This function is deprecated, use ::mbg_save_serial_settings preferably. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> This function is deprecated since it is only + * supported by a certain class of devices and can handle only + * up to 2 ports. The generic function ::mbg_save_serial_settings + * should be used instead. + * + * @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 + * + * @see ::mbg_save_serial_settings + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_parm( MBG_DEV_HANDLE dh, const PORT_PARM *p ) ; /** - @brief Read an ::ANT_INFO structure to retrieve an extended GPS antenna status. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> Normally the current antenna connection status can also be - determined by evaluation of the ::PCPS_TIME::signal or ::PCPS_HR_TIME::signal - fields. The "disconnected" status reported by ANT_INFO disappears only if - the antenna has been reconnected <b>and</b> the receiver has synchronized - to the GPS satellites again. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ANT_INFO structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. -*/ + * @brief Read an ::ANT_INFO structure to retrieve an extended GPS antenna status. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> Normally the current antenna connection status can also be + * determined by evaluation of the ::PCPS_TIME::signal or ::PCPS_HR_TIME::signal + * fields. The "disconnected" status reported by ::ANT_INFO disappears only if + * the antenna has been reconnected <b>and</b> the receiver has synchronized + * to the GPS satellites again. + * + * @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 + */ _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. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This call is pretty slow and has been obsoleted by - mbg_get_ucap_event() which should be used preferably, if supported - by the device. Anyway, this call is still supported for compatibility - with older devices. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::TTM structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_ucap_entries() - @see mbg_get_ucap_event() - @see mbg_clr_ucap_buff() -*/ + * @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. + * + * <b>Note:</b> This call is pretty slow and has been obsoleted by + * ::mbg_get_ucap_event which should be used preferably, if supported + * by the device. Anyway, this call is still supported for compatibility + * with older devices which don't support ::mbg_get_ucap_event. + * + * @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_get_ucap_entries + * @see ::mbg_get_ucap_event + * @see ::mbg_clr_ucap_buff + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_ucap( MBG_DEV_HANDLE dh, TTM *p ) ; /** - @brief Read the ::ENABLE_FLAGS structure controlling when outputs are to be enabled. - - The ::ENABLE_FLAGS structure controls whether certain outputs - shall be enabled immediately after the card's power-up, or only - after the card has synchronized to its input signal. - - The macro _pcps_has_gps_data() or the API call mbg_dev_has_gps_data() - check whether this call is supported by a device. - - <b>Note:</b> Not all of the input signals specified for the - ::ENABLE_FLAGS structure can be modified individually. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::ENABLE_FLAGS structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see ::ENABLE_FLAGS - @see mbg_set_gps_enable_flags() -*/ + * @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 + * after the device has synchronized to its input signal. + * + * The function ::mbg_chk_dev_has_gps_data can be used to check + * whether this call is supported by a device. + * + * <b>Note:</b> Not all of the input signals specified for the + * ::ENABLE_FLAGS structure can be modified individually. + * See ::ENABLE_FLAGS_CODES. + * + * @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 + * + * @see ::ENABLE_FLAGS + * @see ::ENABLE_FLAGS_CODES + * @see ::mbg_set_gps_enable_flags + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_enable_flags( MBG_DEV_HANDLE dh, ENABLE_FLAGS *p ) ; /** - @brief Write an ENABLE_FLAGS structure to configure when outputs shall be enabled. - - The ::ENABLE_FLAGS structure controls whether certain outputs - shall be enabled immediately after the card's power-up, or only - after the card has synchronized to its input signal. - - The macro _pcps_has_gps_data() or the API call mbg_dev_has_gps_data() - check whether this call is supported by a device. - - <b>Note:</b> Not all of the input signals specified for the - ENABLE_FLAGS structure can be modified individually. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ENABLE_FLAGS structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see ENABLE_FLAGS - @see mbg_get_gps_enable_flags() -*/ + * @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 + * after the device has synchronized to its input signal. + * + * The function ::mbg_chk_dev_has_gps_data can be used to check + * whether this call is supported by a device. + * + * <b>Note:</b> Not all of the input signals specified for the + * ::ENABLE_FLAGS structure can be modified individually. + * See ::ENABLE_FLAGS_CODES. + * + * @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 + * + * @see ::ENABLE_FLAGS + * @see ::ENABLE_FLAGS_CODES + * @see ::mbg_get_gps_enable_flags + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_enable_flags( MBG_DEV_HANDLE dh, const ENABLE_FLAGS *p ) ; /** - @brief Read the extended GPS receiver status from a device. - - The ::STAT_INFO structure reports the status of the GPS receiver, - including mode of operation and number of visible/usable satellites. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::STAT_INFO structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see ::STAT_INFO -*/ + * @brief Read the extended GPS receiver status from a device. + * + * The ::STAT_INFO structure reports the status of the GPS receiver, + * including mode of operation and number of visible/usable satellites. + * + * 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[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 + * + * @see ::STAT_INFO + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_stat_info( MBG_DEV_HANDLE dh, STAT_INFO *p ) ; /** - @brief Send a ::GPS_CMD to a GPS receiver device. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::GPS_CMD - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see ::PC_GPS_CMD_BOOT, ::PC_GPS_CMD_INIT_SYS, ::PC_GPS_CMD_INIT_USER, ::PC_GPS_CMD_INIT_DAC -*/ + * @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 + * + * @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. - - 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 macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device. - @param *p Pointer to a ::POS structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_set_gps_pos_xyz() - @see mbg_set_gps_pos_lla() -*/ + * @brief Read the current geographic position from a GPS device. + * + * The returned ::POS structure contains the current position in + * ECEF (Earth Centered, Earth Fixed) kartesian coordinates, and in + * geographic coordinates with different formats, using the WGS84 + * geographic datum. + * + * 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[out] p Pointer to a ::POS structure to be filled up. + * + * @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 + */ _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. - - The structure ::XYZ must specify the new position in ECEF - (Earth Centered, Earth Fixed) kartesian coordinates. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device. - @param p Position in ::XYZ format to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_set_gps_pos_lla() - @see mbg_get_gps_pos() -*/ + * @brief Set the GPS receiver position using ::XYZ coordinates + * + * The structure ::XYZ must specify the new position in ECEF + * (Earth Centered, Earth Fixed) kartesian coordinates. + * + * 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 Position in ::XYZ format to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_set_gps_pos_lla + * @see ::mbg_get_gps_pos + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_xyz( MBG_DEV_HANDLE dh, const XYZ p ) ; /** - @brief Set the GPS receiver position using ::LLA coordinates. - - The structure LLA must specify the new position as longitude, latitude, - and altitude, using the WGS84 geographic datum. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device. - @param p Position in ::LLA format to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_set_gps_pos_xyz() - @see mbg_get_gps_pos() -*/ + * @brief Set the GPS receiver position using ::LLA coordinates + * + * The structure ::LLA must specify the new position as longitude, + * latitude, and altitude, using the WGS84 geographic datum. + * + * The 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 Position in ::LLA format to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_set_gps_pos_xyz + * @see ::mbg_get_gps_pos + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_lla( MBG_DEV_HANDLE dh, const LLA p ) ; /** - @brief Read the configured GPS antenna cable length from a device. - - The antenna cable length parameter is used to compensate the propagation - delay of the RF signal over the antenna cable, which is about 5 ns/m. - - The macro _pcps_has_cab_len() or the API call mbg_dev_has_cab_len() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device. - @param *p ::ANT_CABLE_LEN structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_cab_len() - @see mbg_set_gps_ant_cable_len() -*/ + * @brief Read the configured antenna cable length from a device + * + * The antenna cable length parameter is used by GPS/GNSS receivers + * to compensate the propagation delay of the RF signal over the antenna + * cable, which is about 5 ns/m. + * + * The API call ::mbg_chk_dev_has_cab_len 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 an ::ANT_CABLE_LEN structure to be filled up. + * + * @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 + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_ant_cable_len( MBG_DEV_HANDLE dh, ANT_CABLE_LEN *p ) ; /** - @brief Write the GPS antenna cable length configuration to a device. - - The antenna cable length parameter is used to compensate the propagation - delay of the RF signal over the antenna cable, which is about 5 ns/m. - - The macro _pcps_has_cab_len() or the API call mbg_dev_has_cab_len() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device. - @param *p ::ANT_CABLE_LEN structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_cab_len() - @see mbg_get_gps_ant_cable_len() -*/ + * @brief Write the GPS antenna cable length configuration to a device. + * + * The antenna cable length parameter is used by GPS/GNSS receivers + * to compensate the propagation delay of the RF signal over the antenna + * cable, which is about 5 ns/m. + * + * The API call ::mbg_chk_dev_has_cab_len checks whether + * this call is supported by a device. + * + * @note Different devices may accept different maximum values, so the + * written value should be re-read using ::mbg_get_gps_ant_cable_len + * to check if the parameter has been accepted. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[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 + * + * @see ::mbg_chk_dev_has_cab_len + * @see ::mbg_get_gps_ant_cable_len + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_ant_cable_len( MBG_DEV_HANDLE dh, const ANT_CABLE_LEN *p ) ; /** - @brief Read the ::RECEIVER_INFO structure from a device. - - The macro _pcps_has_receiver_info() or the API call mbg_dev_has_receiver_info() - check whether this call is supported by a device. - - <b>Note:</b> Applications should call mbg_setup_receiver_info() - preferably, which also sets up a basic ::RECEIVER_INFO structure - for devices which don't provide that structure by themselves. - - @param dh Valid handle to a Meinberg device. - @param *p Pointer to a ::RECEIVER_INFO structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_setup_receiver_info() -*/ + * @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. + * + * <b>Note:</b> Applications should call ::mbg_setup_receiver_info + * preferably, which also sets up a basic ::RECEIVER_INFO structure + * for devices which don't provide that structure by themselves. + * + * @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 + * + * @see ::mbg_setup_receiver_info + * @see ::mbg_chk_dev_has_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_receiver_info( MBG_DEV_HANDLE dh, RECEIVER_INFO *p ) ; /** - @brief Read a ::STR_TYPE_INFO_IDX array of supported string types. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure passed to this function. - - <b>Note:</b> The function mbg_get_serial_settings() should be used preferably - to get retrieve the current port settings and configuration options. - - @param dh Valid handle to a Meinberg device. - @param stii Pointer to a an array of string type information to be filled up - @param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info() - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_setup_receiver_info() - @see mbg_get_gps_all_port_info() - @see mbg_get_serial_settings() -*/ + * @brief Read a ::STR_TYPE_INFO_IDX array of supported string types. + * + * A valid ::RECEIVER_INFO associated with the device + * has to be passed to this function. + * + * <b>Note:</b> The function ::mbg_get_serial_settings should be used preferably + * to get retrieve the current port settings and configuration options. + * + * @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 + * + * @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 + * @see ::mbg_setup_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_str_type_info( MBG_DEV_HANDLE dh, STR_TYPE_INFO_IDX stii[], const RECEIVER_INFO *p_ri ) ; /** - @brief Read a ::PORT_INFO_IDX array of supported serial port configurations. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure passed to this function. - - <b>Note:</b> The function mbg_get_serial_settings() should be used preferably - to get retrieve the current port settings and configuration options. - - @param dh Valid handle to a Meinberg device. - @param pii Pointer to a an array of port configuration information to be filled up - @param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info() - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_setup_receiver_info() - @see mbg_get_gps_all_str_type_info() - @see mbg_get_serial_settings() -*/ + * @brief Read a ::PORT_INFO_IDX array of supported serial port configurations. + * + * A valid ::RECEIVER_INFO associated with the device + * has to be passed to this function. + * + * <b>Note:</b> The function ::mbg_get_serial_settings should be used preferably + * to get retrieve the current port settings and configuration options. + * + * @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 + * + * @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 + * @see ::mbg_setup_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_port_info( MBG_DEV_HANDLE dh, PORT_INFO_IDX pii[], const RECEIVER_INFO *p_ri ) ; /** - @brief Write the configuration for a single serial port to a device. - - The ::PORT_SETTINGS_IDX structure contains both the ::PORT_SETTINGS - and the port index value. Except for the parameter types this call is - equivalent to mbg_set_gps_port_settings(). - - The macro _pcps_has_receiver_info() or the API call mbg_dev_has_receiver_info() - check 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. - - @param dh Valid handle to a Meinberg device. - @param *p Pointer to a ::PORT_SETTINGS_IDX structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_save_serial_settings() - @see mbg_set_gps_port_settings() - @see mbg_dev_has_receiver_info() -*/ + * @brief Write the configuration for a single serial port to a device. + * + * The ::PORT_SETTINGS_IDX structure contains both the ::PORT_SETTINGS + * and the port index value. Except for the parameter types this call is + * equivalent to ::mbg_set_gps_port_settings. + * + * The API call ::mbg_chk_dev_has_receiver_info checks + * 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. + * + * @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 + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_save_serial_settings + * @see ::mbg_set_gps_port_settings + * @see ::mbg_chk_dev_has_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings_idx( MBG_DEV_HANDLE dh, const PORT_SETTINGS_IDX *p ) ; /** - @brief Write the configuration for a single serial port to a device. - - The ::PORT_SETTINGS structure does not contain the port index, so the - the port index must be given separately. Except for the parameter types - this call is equivalent to mbg_set_gps_port_settings_idx(). - - The macro _pcps_has_receiver_info() or the API call mbg_dev_has_receiver_info() - check 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. - - @param dh Valid handle to a Meinberg device. - @param *p Pointer to a ::PORT_SETTINGS structure to be filled up - @param idx Index of the serial port to be configured (starting from 0 ). - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_save_serial_settings() - @see mbg_set_gps_port_settings_idx() - @see mbg_dev_has_receiver_info() -*/ + * @brief Write the configuration for a single serial port to a device. + * + * The ::PORT_SETTINGS structure does not contain the port index, so the + * the port index must be given separately. Except for the parameter types + * this call is equivalent to ::mbg_set_gps_port_settings_idx. + * + * The API call ::mbg_chk_dev_has_receiver_info checks + * 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. + * + * @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 + * + * @see ::mbg_save_serial_settings + * @see ::mbg_set_gps_port_settings_idx + * @see ::mbg_chk_dev_has_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings( MBG_DEV_HANDLE dh, const PORT_SETTINGS *p, int idx ) ; /** - @brief Set up a ::RECEIVER_INFO structure for a device. - - If the device supports the ::RECEIVER_INFO structure then the structure - is read from the device, otherwise a structure is set up using - default values depending on the device type. - The function mbg_get_device_info() must have been called before, - and the returned PCPS_DEV structure passed to this function. - - @param dh Valid handle to a Meinberg device. - @param *pdev Pointer to a ::PCPS_DEV structure returned by mbg_get_device_info() - @param *p Pointer to a ::RECEIVER_INFO structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_device_info() - @see mbg_dev_has_receiver_info() -*/ - _MBG_API_ATTR int _MBG_API mbg_setup_receiver_info( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, RECEIVER_INFO *p ) ; + * @brief Set up a ::RECEIVER_INFO structure for a device. + * + * If the device supports the ::RECEIVER_INFO structure then the structure + * is read from the device, otherwise a structure is set up using + * default values depending on the device type. + * + * Optionally, the function ::mbg_get_device_info may have been called + * 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 + * 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[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 + * + * @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 ) ; /** - @brief Read the version code of the on-board PCI/PCIe interface ASIC. - - The macro _pcps_has_asic_version() or the API call mbg_dev_has_asic_version() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCI_ASIC_VERSION type to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function - - @see mbg_dev_has_asic_version() -*/ + * @brief Read the version code of the on-board PCI/PCIe interface ASIC. + * + * The API call ::mbg_chk_dev_has_asic_version 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 ::PCI_ASIC_VERSION type to be filled up. + * + * @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. - - The macro _pcps_has_asic_features() or the API call mbg_dev_has_asic_features() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device. - @param *p Pointer to a ::PCI_ASIC_FEATURES type to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_asic_features() -*/ + * @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. + * + * @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 + * + * @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 Check if a device supports configurable time scales. - - By default the cards return UTC and/or local time. However, some cards - can be configured to return raw GPS time or TAI instead. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_time_scale_info() - @see mbg_set_time_scale_settings() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_time_scale( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Read the current time scale settings and which time scales are supported. - - The ::MBG_TIME_SCALE_INFO structure tells which time scale settings are supported - by a device, and which time scale is currently configured. - - The macro _pcps_has_time_scale() or the API call mbg_dev_has_time_scale() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_time_scale(). - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_TIME_SCALE_INFO structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_set_time_scale_settings() - @see mbg_dev_has_time_scale() -*/ + * @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. + * + * The API call ::mbg_chk_dev_has_time_scale checks whether + * this call is supported by a device. + * + * See also the notes for ::mbg_chk_dev_has_time_scale. + * + * @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 + * + * @see ::mbg_set_time_scale_settings + * @see ::mbg_chk_dev_has_time_scale + */ _MBG_API_ATTR int _MBG_API mbg_get_time_scale_info( MBG_DEV_HANDLE dh, MBG_TIME_SCALE_INFO *p ) ; /** - @brief Write the time scale configuration to a device. - - 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. - - The macro _pcps_has_time_scale() or the API call mbg_dev_has_time_scale() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_time_scale(). - - The function mbg_get_time_scale_info() should have been called before - in order to determine which time scales are supported by the card. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_TIME_SCALE_SETTINGS structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_time_scale_info() - @see mbg_dev_has_time_scale() -*/ - _MBG_API_ATTR int _MBG_API mbg_set_time_scale_settings( MBG_DEV_HANDLE dh, MBG_TIME_SCALE_SETTINGS *p ) ; - - /** - @brief Check if a device support reading/writing of UTC parameters. - - This API call checks if a device supports reading/writing a GPS UTC - parameter set via the PC bus. Reading/writing these parameters via the - serial port using the Meinberg binary data protocol is supported by all - Meinberg GPS 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 - 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. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_utc_parm() - @see mbg_set_utc_parm() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_utc_parm( MBG_DEV_HANDLE dh, int *p ) ; + * @brief 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. + * + * The API call ::mbg_chk_dev_has_time_scale checks whether + * this call is supported by a device. + * + * See also the notes for ::mbg_chk_dev_has_time_scale. + * + * The function ::mbg_get_time_scale_info should have been called before + * in order to determine which time scales are supported by the card. + * + * @param[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 + * + * @see ::mbg_get_time_scale_info + * @see ::mbg_chk_dev_has_time_scale + */ + _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. - - The macro _pcps_has_utc_parm() or the API call mbg_dev_has_utc_parm() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_utc_parm(). - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::UTC structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_utc_parm() - @see mbg_set_utc_parm() -*/ + * @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. + * + * See also the notes for ::mbg_chk_dev_has_utc_parm. + * + * @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 + * + * @see ::mbg_chk_dev_has_utc_parm + * @see ::mbg_set_utc_parm + */ _MBG_API_ATTR int _MBG_API mbg_get_utc_parm( MBG_DEV_HANDLE dh, UTC *p ) ; /** - @brief Write a ::UTC parameter structure to a device. - - 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 broadcasted - by the satellites. - - The macro _pcps_has_utc_parm() or the API call mbg_dev_has_utc_parm() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_utc_parm(). - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a valid ::UTC structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_utc_parm() - @see mbg_get_utc_parm() -*/ - _MBG_API_ATTR int _MBG_API mbg_set_utc_parm( MBG_DEV_HANDLE dh, UTC *p ) ; + * @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. + * + * The API call ::mbg_chk_dev_has_utc_parm checks whether + * this call is supported by a device. + * + * See also the notes for mbg_chk_dev_has_utc_parm. + * + * @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 + * + * @see ::mbg_chk_dev_has_utc_parm + * @see ::mbg_get_utc_parm + */ + _MBG_API_ATTR int _MBG_API mbg_set_utc_parm( MBG_DEV_HANDLE dh, const UTC *p ) ; /** - @brief Read the current time plus the associated PC cycles from a device. - - The ::PCPS_TIME_CYCLES structure contains a ::PCPS_TIME structure - and a PC cycle 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. - - This call is supported for any card, similar to mbg_get_time(). However, - the mbg_get_hr_time_cyles() call should be used preferably if supported by - the device since that call provides much better accuracy than this one. - - The cycle counter value corresponds to a value returned by QueryPerformanceCounter() - under Windows, and get_cycles() under 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 cycle counter value and then call - this function. The difference of the cycle counter values corresponds to the - latency of the call in units of the cycle counter clock frequency, e.g as reported - by QueryPerformanceFrequency() under Windows. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_TIME_CYCLES structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_hr_time_cycles() - @see mbg_get_hr_time_comp() - @see mbg_get_hr_time() - @see mbg_get_time() -*/ + * @brief Read the current time plus the associated PC cycles from a device. + * + * The ::PCPS_TIME_CYCLES structure contains a ::PCPS_TIME structure + * and a PC 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. + * + * 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 + * 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. + * + * @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 + * + * @ingroup mbgdevio_legacy_time_fncs + * @see ::mbg_get_hr_time_cycles + * @see ::mbg_get_hr_time_comp + * @see ::mbg_get_hr_time + * @see ::mbg_get_time + */ _MBG_API_ATTR int _MBG_API mbg_get_time_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_CYCLES *p ) ; /** - @brief Read the current high resolution time plus the associated PC cycles from a device. - - The ::PCPS_HR_TIME_CYCLES structure contains a ::PCPS_HR_TIME structure - and a PC cycle counter value which can be used to compensate the latency - of the call, i.e. the program execution time until the time stamp has actually - been read from the board. - - The macro _pcps_has_hr_time() or the API call mbg_dev_has_hr_time() - check whether this call is supported by a device. - - The cycle counter value corresponds to a value returned by QueryPerformanceCounter() - under Windows, and get_cycles() under 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 cycle counter value and then call - this function. The difference of the cycle counter values corresponds to the - latency of the call in units of the cycle counter clock frequency, e.g as reported - by QueryPerformanceFrequency() under Windows. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_HR_TIME_CYCLES structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_hr_time_comp() - @see mbg_get_hr_time() - @see mbg_get_time_cycles() - @see mbg_get_time() -*/ + * @brief Read the current high resolution time plus the associated PC cycles from a device. + * + * 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. + * + * 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 + * 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. + * + * @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 + * + * @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 + * @see ::mbg_get_hr_time + * @see ::mbg_get_hr_time_cycles + * @see ::mbg_get_hr_time_comp + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs + */ _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. - - Read a ::PCPS_HR_TIME structure plus cycle counter value, and correct the - time stamp for the latency of the call as described for mbg_get_hr_time_cycles(), - then return the compensated time stamp and optionally the latency. - - The macro _pcps_has_hr_time() or the API call mbg_dev_has_hr_time() - check whether this call is supported by a device. - - The cycle counter value corresponds to a value returned by QueryPerformanceCounter() - under Windows, and get_cycles() under 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 cycle counter value and then call - this function. The difference of the cycle counter values corresponds to the - latency of the call in units of the cycle counter clock frequency, e.g as reported - by QueryPerformanceFrequency() under Windows. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_HR_TIME structure to be filled up - @param *hns_latency Optional pointer to an int32_t value to return - the latency in 100ns units. Pass NULL if not used. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_hr_time_comp() - @see mbg_get_hr_time() - @see mbg_get_time_cycles() - @see mbg_get_time() -*/ + * @brief Read the current high resolution time, and compensate the call's latency. + * + * 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, + * then return the compensated time stamp, and optionally the latency. + * + * 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 + * 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. + * + * @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. + * + * @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 + * @see ::mbg_get_hr_time + * @see ::mbg_get_hr_time_cycles + * @see ::mbg_get_hr_time_comp + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs + */ _MBG_API_ATTR int _MBG_API mbg_get_hr_time_comp( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p, int32_t *hns_latency ) ; /** - @brief Read the current IRIG output settings plus the supported settings. - - The returned ::IRIG_INFO structure contains the configuration of an IRIG output - plus the possible settings supported by that output. - - The macro _pcps_has_irig_tx() or the API call mbg_dev_has_irig_tx() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an ::IRIG_INFO structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_set_irig_tx_settings() - @see mbg_dev_has_irig_tx() - @see mbg_dev_is_irig_rx() - @see mbg_dev_has_irig() - @see \ref group_icode -*/ + * @brief Read the current IRIG output settings plus the supported settings. + * + * The returned ::IRIG_INFO structure contains the configuration of an IRIG output + * plus the possible settings supported by that output. + * + * The API call ::mbg_chk_dev_has_irig_tx 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 an ::IRIG_INFO structure to be filled up. + * + * @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 + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig + * @see @ref group_icode + */ _MBG_API_ATTR int _MBG_API mbg_get_irig_tx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p ) ; /** - @brief Write an ::IRIG_SETTINGS structure to a device to configure the IRIG output. - - The macro _pcps_has_irig_tx() or the API call mbg_dev_has_irig_tx() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an ::IRIG_INFO structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_irig_tx_info() - @see mbg_dev_has_irig_tx() - @see mbg_dev_is_irig_rx() - @see mbg_dev_has_irig() - @see \ref group_icode -*/ + * @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. + * + * @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 + * + * @see ::mbg_get_irig_tx_info + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig + * @see @ref group_icode + */ _MBG_API_ATTR int _MBG_API mbg_set_irig_tx_settings( MBG_DEV_HANDLE dh, const IRIG_SETTINGS *p ) ; /** - @brief Read the current frequency synthesizer settings from a device. - - Read a ::SYNTH structure containing the configuration of an optional - on-board programmable frequency synthesizer. - - The macro _pcps_has_synth() or the API call mbg_dev_has_synth() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::SYNTH structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_synth() - @see mbg_set_synth() - @see mbg_get_synth_state() - @see \ref group_synth -*/ + * @brief Read the current frequency synthesizer settings from a device + * + * Read a ::SYNTH structure containing the configuration of an optional + * on-board programmable frequency synthesizer. + * + * The API call ::mbg_chk_dev_has_synth 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 ::SYNTH structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_synth + * @see ::mbg_set_synth + * @see ::mbg_get_synth_state + * @see @ref group_synth + */ _MBG_API_ATTR int _MBG_API mbg_get_synth( MBG_DEV_HANDLE dh, SYNTH *p ) ; /** - @brief Write some frequency synthesizer settings to a device. - - Write a ::SYNTH structure containing the configuration of an optional - on-board programmable frequency synthesizer. - - The macro _pcps_has_synth() or the API call mbg_dev_has_synth() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::SYNTH structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_synth() - @see mbg_get_synth() - @see mbg_get_synth_state() - @see \ref group_synth -*/ + * @brief Write frequency synthesizer configuration settings to a device + * + * Write a ::SYNTH structure containing the configuration of an optional + * on-board programmable frequency synthesizer. + * + * The API call ::mbg_chk_dev_has_synth 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 ::SYNTH structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_synth + * @see ::mbg_get_synth + * @see ::mbg_get_synth_state + * @see @ref group_synth + */ _MBG_API_ATTR int _MBG_API mbg_set_synth( MBG_DEV_HANDLE dh, const SYNTH *p ) ; /** - @brief Read the current status of the on-board frequency synthesizer. - - The macro _pcps_has_synth() or the API call mbg_dev_has_synth() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::SYNTH_STATE structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_synth() - @see mbg_get_synth() - @see mbg_set_synth() - @see \ref group_synth -*/ + * @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. + * + * @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 + * + * @see ::mbg_chk_dev_has_synth + * @see ::mbg_get_synth + * @see ::mbg_set_synth + * @see @ref group_synth + */ _MBG_API_ATTR int _MBG_API mbg_get_synth_state( MBG_DEV_HANDLE dh, SYNTH_STATE *p ) ; /** - @brief Check if a device supports the mbg_get_fast_hr_timestamp_...() calls. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_fast_hr_timestamp_cycles() - @see mbg_get_fast_hr_timestamp_comp() - @see mbg_get_fast_hr_timestamp() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_fast_hr_timestamp( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Read a high resolution ::PCPS_TIME_STAMP_CYCLES structure via memory mapped access. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_TIME_STAMP_CYCLES structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_fast_hr_timestamp() - @see mbg_get_fast_hr_timestamp_comp() - @see mbg_get_fast_hr_timestamp() -*/ + * @brief Read a high resolution ::PCPS_TIME_STAMP_CYCLES structure via memory mapped access. + * + * @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 + * + * @ingroup mbgdevio_fast_timestamp_fncs + * @see ::mbg_chk_dev_has_fast_hr_timestamp + * @see ::mbg_get_fast_hr_timestamp_comp + * @see ::mbg_get_fast_hr_timestamp + * @see @ref mbgdevio_fast_timestamp_fncs + */ _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. - - The retrieved ::PCPS_TIME_STAMP is read from memory mapped registers, - and timestamp is compensated for the call's latency before it is returned. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_TIME_STAMP structure to be filled up - @param *hns_latency Optionally receive the latency in hectonanoseconds - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_fast_hr_timestamp() - @see mbg_get_fast_hr_timestamp_cycles() - @see mbg_get_fast_hr_timestamp() -*/ + * @brief Read a high resolution timestamp and compensate the latency of the call + * + * The retrieved ::PCPS_TIME_STAMP is read from memory mapped registers, + * and timestamp is compensated for the call's latency before it is returned. + * + * @param[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 + * + * @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 + * @see ::mbg_get_fast_hr_timestamp_cycles + * @see ::mbg_get_fast_hr_timestamp + * @see @ref mbgdevio_fast_timestamp_fncs + */ _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. - - 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 - used as cycles counter it may take quite some time to read the cycles count - on some hardware architectures, so this call can be used to yield lower - latencies, under the restriction to be unable to determine the exact latency. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_TIME_STAMP structure to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_fast_hr_timestamp() - @see mbg_get_fast_hr_timestamp_comp() - @see mbg_get_fast_hr_timestamp_cycles() -*/ + * @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 + * used as cycles counter it may take quite some time to read the cycles count + * on some hardware architectures, so this call can be used to yield lower + * latencies, under the restriction to be unable to determine the exact latency. + * + * @param[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 + * + * @ingroup mbgdevio_fast_timestamp_fncs + * @see ::mbg_chk_dev_has_fast_hr_timestamp + * @see ::mbg_get_fast_hr_timestamp_comp + * @see ::mbg_get_fast_hr_timestamp_cycles + * @see @ref mbgdevio_fast_timestamp_fncs + */ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP *p ) ; /** - @brief Check if a device is a GPS receiver. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_is_gps( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device is a DCF77 receiver. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_is_dcf( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device is a MSF receiver. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_is_msf( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device is a WWVB receiver. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_is_wwvb( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device is any long wave signal receiver. - - Long wave receivers include e.g. DCF77, MSF, WWVB, or JJY. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_is_lwr( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device provides a configurable IRIG input. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_irig_rx_info() - @see mbg_set_irig_rx_settings() - @see mbg_dev_has_irig_tx() - @see mbg_dev_has_irig() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_is_irig_rx( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports the HR_TIME functions. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_hr_time() - @see mbg_get_hr_time_cycles() - @see mbg_get_hr_time_comp() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_hr_time( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports configuration of antenna cable length. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_gps_ant_cable_len() - @see mbg_set_gps_ant_cable_len() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_cab_len( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports timezone configuration using the ::TZDL structure. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_gps_tzdl() - @see mbg_set_gps_tzdl() - @see mbg_dev_has_tz() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_tzdl( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_pcps_tzdl() - @see mbg_set_pcps_tzdl() - @see mbg_dev_has_tz() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_pcps_tzdl( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports timezone configuration using the ::PCPS_TZCODE type. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_tzcode() - @see mbg_set_tzcode() - @see mbg_dev_has_tz() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_tzcode( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports any kind of timezone configuration. - - This can be used e.g. to check if a specifig dialog or menu has to - be displayed. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_tzdl() - @see mbg_dev_has_pcps_tzdl() - @see mbg_dev_has_tzcode() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_tz( MBG_DEV_HANDLE dh, int *p ) ; - - /* (Intentionally excluded from Doxygen) - Check if a device supports setting an event time, i.e. - configure a %UTC time when the clock shall generate an event. - - <b>Note:</b> This is only supported by some special firmware. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_set_event_time() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_event_time( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports the ::RECEIVER_INFO structure and related calls. - - @note Older GPS devices may not support that structure. - - The mbg_get_gps_receiver_info() call uses this call to decide whether a - ::RECEIVER_INFO can be read directly from a device, or whether a default - structure has to be set up using default values depending on the device type. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_gps_receiver_info() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_receiver_info( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports the mbg_clr_ucap_buff() call. - - The mbg_clr_ucap_buff() call can be used to clear a card's on-board - time capture FIFO buffer. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_clr_ucap_buff() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_can_clr_ucap_buff( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports the mbg_get_ucap_entries() and mbg_get_ucap_event() calls. - - If the card does not but it is a GPS card then the card provides - a time capture FIFO buffer and the obsolete mbg_get_gps_ucap() - call can be used to retrieve entries from the FIFO buffer. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_ucap_entries() - @see mbg_get_ucap_event() - @see mbg_clr_ucap_buff() - @see mbg_get_gps_ucap() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_ucap( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device provides a configurable IRIG output. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_irig_tx_info() - @see mbg_set_irig_tx_settings() - @see mbg_dev_is_irig_rx() - @see mbg_dev_has_irig() - @see \ref group_icode - -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_irig_tx( MBG_DEV_HANDLE dh, int *p ) ; - - /* (Intentionally excluded from Doxygen) - Check if a device provides a serial output supporting - higher baud rates than older cards, i.e. ::DEFAULT_BAUD_RATES_DCF_HS - rather than ::DEFAULT_BAUD_RATES_DCF. - - The mbg_get_serial_settings() takes care of this, so applications - which use that call as suggested won't need to use this call directly. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_serial_settings() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_serial_hs( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device provides the level of its inputs signal. - - This is useful to display the signal level of e.g. an IRIG or longwave signal. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_signal( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device provides a modulation signal. - - Modulation signals are e.g. the second marks of a DCF77 AM receiver. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_mod( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device provides either an IRIG input or output. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_is_irig_rx() - @see mbg_dev_has_irig_tx() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_irig( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device provides a configurable ref time offset. - - This may be required to convert the received time to %UTC, if the input - signal doesn't specify this (e.g. most IRIG code formats). - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_ref_offs() - @see mbg_set_ref_offs() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_ref_offs( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS. - - These structures containing optional settings, controlled by flags. - See ::MBG_OPT_SETTINGS and related definitions. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_opt_info() - @see mbg_set_opt_settings() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_opt_flags( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports large configuration data structures. - - Such structures have been introduced with the first Meinberg GPS receivers. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_gps_data( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device provides a programmable frequency synthesizer. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_synth() - @see mbg_set_synth() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_synth( MBG_DEV_HANDLE dh, int *p ) ; - - /* (Intentionally excluded from Doxygen) - @brief Check if a device supports the mbg_generic_io() call. - - <b>Warning</b>: That call is for debugging purposes and internal use only! - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_generic_io() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_generic_io( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports the mbg_get_asic_version() call. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_asic_version() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_asic_version( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports the mbg_get_asic_features() call. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_asic_features() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_asic_features( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Read current configuraton and features provided by the programmable pulse outputs. - - Reads a ::POUT_INFO_IDX array of current settings and configuration - options of the device's programmable pulse outputs. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure 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. - - The array passed to this function to receive the returned data - must be able to hold at least ::RECEIVER_INFO::n_prg_out elements. - - @param dh Valid handle to a Meinberg device. - @param pii Pointer to a an array of ::POUT_INFO_IDX structures to be filled up - @param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info() - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_set_gps_pout_settings_idx() - @see mbg_set_gps_pout_settings() - @see mbg_setup_receiver_info() -*/ + * @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. + * + * 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. + * + * 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 + * + * @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 + * @see ::mbg_setup_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_pout_info( MBG_DEV_HANDLE dh, POUT_INFO_IDX pii[], const RECEIVER_INFO *p_ri ) ; /** - @brief Write the configuration for a single programmable pulse output - - 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 - output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. - - @param dh Valid handle to a Meinberg device. - @param *p Pointer to a ::POUT_SETTINGS_IDX structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_gps_all_pout_info() - @see mbg_set_gps_pout_settings() -*/ + * @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 + * 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 + * + * @see ::mbg_get_gps_all_pout_info + * @see ::mbg_set_gps_pout_settings + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings_idx( MBG_DEV_HANDLE dh, const POUT_SETTINGS_IDX *p ) ; /** - @brief Write the configuration for a single programmable pulse output - - The ::POUT_SETTINGS structure does not contain the index of the - programmable output to be configured, so the index must explicitely - be passed to this function. Except for the parameter types this call - 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 - output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. - - @param dh Valid handle to a Meinberg device. - @param *p Pointer to a ::POUT_SETTINGS structure to be written - @param idx Index of the programmable pulse output to be configured (starting from 0 ). - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_gps_all_pout_info() - @see mbg_set_gps_pout_settings_idx() -*/ + * @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 + * be passed to this function. Except for the parameter types this call + * 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 + * 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 + * + * @see ::mbg_get_gps_all_pout_info + * @see ::mbg_set_gps_pout_settings_idx + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings( MBG_DEV_HANDLE dh, const POUT_SETTINGS *p, int idx ) ; /** - @brief Read a device's IRQ status information. - - IRQ status information includes flags indicating whether IRQs are - actually enabled, and whether IRQ support by a card is possibly - unsafe due to the firmware and interface chip version. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PCPS_IRQ_STAT_INFO variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - */ + * @brief Read a device's IRQ status information. + * + * IRQ status information includes flags indicating whether IRQs are + * actually enabled, and whether IRQ support by a card is possibly + * unsafe due to the firmware and interface chip version. + * + * @param[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 + * + * @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 Check if a device provides simple LAN interface API calls. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_lan_if_info() - @see mbg_get_ip4_state() - @see mbg_get_ip4_settings() - @see mbg_set_ip4_settings() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_lan_intf( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Read LAN interface information from a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::LAN_IF_INFO variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_lan_intf() - @see mbg_get_ip4_state() - @see mbg_get_ip4_settings() - @see mbg_set_ip4_settings() - */ + * @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. + * + * @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 + * + * @see ::mbg_chk_dev_has_lan_intf + * @see ::mbg_get_ip4_state + * @see ::mbg_get_ip4_settings + * @see ::mbg_set_ip4_settings + */ _MBG_API_ATTR int _MBG_API mbg_get_lan_if_info( MBG_DEV_HANDLE dh, LAN_IF_INFO *p ) ; /** - @brief Read LAN IPv4 state from a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::IP4_SETTINGS variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_lan_intf() - @see mbg_get_lan_if_info() - @see mbg_get_ip4_settings() - @see mbg_set_ip4_settings() - */ + * @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. + * + * @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 + * + * @see ::mbg_chk_dev_has_lan_intf + * @see ::mbg_get_lan_if_info + * @see ::mbg_get_ip4_settings + * @see ::mbg_set_ip4_settings + */ _MBG_API_ATTR int _MBG_API mbg_get_ip4_state( MBG_DEV_HANDLE dh, IP4_SETTINGS *p ) ; /** - @brief Read LAN IPv4 settings from a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::IP4_SETTINGS variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_lan_intf() - @see mbg_get_lan_if_info() - @see mbg_get_ip4_state() - @see mbg_set_ip4_settings() - */ + * @brief Read LAN IPv4 settings from a device. + * + * The API call ::mbg_chk_dev_has_lan_intf 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 ::IP4_SETTINGS variable to be filled up. + * + * @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 + * @see ::mbg_get_ip4_state + * @see ::mbg_set_ip4_settings + */ _MBG_API_ATTR int _MBG_API mbg_get_ip4_settings( MBG_DEV_HANDLE dh, IP4_SETTINGS *p ) ; /** - @brief Write LAN IPv4 settings to a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device. - @param *p ::IP4_SETTINGS structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_lan_intf() - @see mbg_get_lan_if_info() - @see mbg_get_ip4_settings() -*/ + * @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. + * + * @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 + * + * @see ::mbg_chk_dev_has_lan_intf + * @see ::mbg_get_lan_if_info + * @see ::mbg_get_ip4_settings + */ _MBG_API_ATTR int _MBG_API mbg_set_ip4_settings( MBG_DEV_HANDLE dh, const IP4_SETTINGS *p ) ; /** - @brief Check if a device provides PTP configuration/status calls. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_all_ptp_cfg_info - @see mbg_get_ptp_state - @see mbg_get_ptp_cfg_info - @see mbg_set_ptp_cfg_settings - @see mbg_dev_has_ptp_unicast -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_ptp( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device provides PTP unicast feature/configuration. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_all_ptp_cfg_info - @see mbg_get_ptp_uc_master_cfg_limits - @see mbg_get_all_ptp_uc_master_info - @see mbg_set_ptp_uc_master_settings_idx - @see mbg_get_ptp_state -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_ptp_unicast( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Read PTP/IEEE1588 status from a device. - - The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PTP_STATE variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_ptp - @see mbg_get_all_ptp_cfg_info - @see mbg_get_ptp_cfg_info - @see mbg_set_ptp_cfg_settings - @see mbg_dev_has_ptp_unicast - */ + * @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. + * + * @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 + * + * @see ::mbg_chk_dev_has_ptp + * @see ::mbg_get_all_ptp_cfg_info + * @see ::mbg_get_ptp_cfg_info + * @see ::mbg_set_ptp_cfg_settings + * @see ::mbg_chk_dev_has_ptp_unicast + */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_state( MBG_DEV_HANDLE dh, PTP_STATE *p ) ; /** - @brief Read PTP/IEEE1588 config info and current settings from a device. - - The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PTP_CFG_INFO variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_ptp - @see mbg_get_all_ptp_cfg_info - @see mbg_get_ptp_state - @see mbg_set_ptp_cfg_settings - @see mbg_dev_has_ptp_unicast - */ + * @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. + * + * @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 + * + * @see ::mbg_chk_dev_has_ptp + * @see ::mbg_get_all_ptp_cfg_info + * @see ::mbg_get_ptp_state + * @see ::mbg_set_ptp_cfg_settings + * @see ::mbg_chk_dev_has_ptp_unicast + */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_cfg_info( MBG_DEV_HANDLE dh, PTP_CFG_INFO *p ) ; /** - @brief Write PTP/IEEE1588 configuration settings to a device. - - The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device. - @param *p ::PTP_CFG_SETTINGS structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_ptp - @see mbg_get_all_ptp_cfg_info - @see mbg_get_ptp_state - @see mbg_get_ptp_cfg_info - @see mbg_dev_has_ptp_unicast -*/ + * @brief Write PTP/IEEE1588 configuration settings to a device. + * + * The API call ::mbg_chk_dev_has_ptp checks whether + * this call is supported by a device. + * + * @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 + * + * @see ::mbg_chk_dev_has_ptp + * @see ::mbg_get_all_ptp_cfg_info + * @see ::mbg_get_ptp_state + * @see ::mbg_get_ptp_cfg_info + * @see ::mbg_chk_dev_has_ptp_unicast + */ _MBG_API_ATTR int _MBG_API mbg_set_ptp_cfg_settings( MBG_DEV_HANDLE dh, const PTP_CFG_SETTINGS *p ) ; /** - @brief Read PTP/IEEE1588 unicast master configuration limits from a device. - - The macro _pcps_has_ri_ptp_unicast() or the API call mbg_dev_has_ptp_unicast() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PTP_UC_MASTER_CFG_LIMITS variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_ptp_unicast - @see mbg_get_all_ptp_cfg_info - @see mbg_get_all_ptp_uc_master_info - @see mbg_set_ptp_uc_master_settings_idx - @see mbg_get_ptp_state - */ + * @brief Read PTP/IEEE1588 unicast master configuration limits from a device. + * + * The API call ::mbg_chk_dev_has_ptp_unicast 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 ::PTP_UC_MASTER_CFG_LIMITS variable to be filled up. + * + * @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 + * @see ::mbg_get_all_ptp_uc_master_info + * @see ::mbg_set_ptp_uc_master_settings_idx + * @see ::mbg_get_ptp_state + */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_uc_master_cfg_limits( MBG_DEV_HANDLE dh, PTP_UC_MASTER_CFG_LIMITS *p ) ; /** - @brief Read PTP Unicast master settings and configuration options. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure 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. - - The array passed to this function to receive the returned data - must be able to hold at least ::RECEIVER_INFO::n_prg_out elements. - - @param dh Valid handle to a Meinberg device. - @param pii Pointer to a an array of ::PTP_UC_MASTER_INFO_IDX structures to be filled up - @param p_umsl Pointer to a ::PTP_UC_MASTER_CFG_LIMITS structure returned by mbg_get_ptp_uc_master_cfg_limits() - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_ptp_unicast - @see mbg_get_all_ptp_cfg_info - @see mbg_get_ptp_uc_master_cfg_limits - @see mbg_set_ptp_uc_master_settings_idx - @see mbg_get_ptp_state -*/ + * @brief Read PTP Unicast master settings and configuration options. + * + * The array passed to this function to receive the returned data + * must be able to hold at least ::PTP_UC_MASTER_CFG_LIMITS::n_supp_master elements. + * + * @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 + * + * @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 + * @see ::mbg_get_ptp_uc_master_cfg_limits + * @see ::mbg_set_ptp_uc_master_settings_idx + * @see ::mbg_get_ptp_state + */ _MBG_API_ATTR int _MBG_API mbg_get_all_ptp_uc_master_info( MBG_DEV_HANDLE dh, PTP_UC_MASTER_INFO_IDX pii[], const PTP_UC_MASTER_CFG_LIMITS *p_umsl ) ; /** - @brief Write PTP/IEEE1588 unicast configuration settings to a device. - - The macro _pcps_has_ri_ptp_unicast() or the API call mbg_dev_has_ptp_unicast() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device. - @param *p ::PTP_UC_MASTER_SETTINGS_IDX structure to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_ptp_unicast - @see mbg_get_all_ptp_cfg_info - @see mbg_get_ptp_uc_master_cfg_limits - @see mbg_get_all_ptp_uc_master_info - @see mbg_get_ptp_state -*/ + * @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. + * + * @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 + * + * @see ::mbg_chk_dev_has_ptp_unicast + * @see ::mbg_get_all_ptp_cfg_info + * @see ::mbg_get_ptp_uc_master_cfg_limits + * @see ::mbg_get_all_ptp_uc_master_info + * @see ::mbg_get_ptp_state + */ _MBG_API_ATTR int _MBG_API mbg_set_ptp_uc_master_settings_idx( MBG_DEV_HANDLE dh, const PTP_UC_MASTER_SETTINGS_IDX *p ) ; /** - @brief Read both system time and associated device time from the kernel driver. - - 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 - 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. - - This call makes a mbg_get_hr_time_cycles() call internally so the macro - _pcps_has_hr_time() or the API call mbg_dev_has_hr_time() can be - used to check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_TIME_INFO_HRT variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_hr_time() - @see mbg_get_time_info_tstamp() - */ + * @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 + * 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. + * + * 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 + * + * @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 + */ _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. - - This call is similar to mbg_get_time_info_hrt() except that a - mbg_get_fast_hr_timestamp_cycles() call is made internally, so the macro - _pcps_has_fast_hr_timestamp() or the API call mbg_dev_has_fast_hr_timestamp() - can be used to check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_TIME_INFO_TSTAMP variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_fast_hr_timestamp() - @see mbg_get_time_info_hrt() - */ + * @brief Read both system time and associated device timestamp from the kernel driver + * + * This call is similar to ::mbg_get_time_info_hrt except that a + * ::mbg_get_fast_hr_timestamp_cycles call is made internally, so + * the API call ::mbg_chk_dev_has_fast_hr_timestamp 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_TSTAMP structure to be filled up. + * + * @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 + */ _MBG_API_ATTR int _MBG_API mbg_get_time_info_tstamp( MBG_DEV_HANDLE dh, MBG_TIME_INFO_TSTAMP *p ) ; /** - @brief Check if a device supports demodulation of the DCF77 PZF code. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_corr_info() - @see mbg_dev_has_tr_distance() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_pzf( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports reading correlation info. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_pzf() - @see mbg_get_corr_info() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_corr_info( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Check if a device supports configurable distance from transmitter. - - The distance from transmitter parameter is used to compensate - the RF propagation delay, mostly with long wave receivers. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_pzf() - @see mbg_get_tr_distance() - @see mbg_set_tr_distance() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_tr_distance( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Read PZF correlation info from a device. - - The macro _pcps_has_corr_info() or the API call mbg_dev_has_corr_info() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::CORR_INFO variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_pzf() - @see mbg_dev_has_corr_info() - */ + * @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. + * + * @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 + * + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_chk_dev_has_corr_info + */ _MBG_API_ATTR int _MBG_API mbg_get_corr_info( MBG_DEV_HANDLE dh, CORR_INFO *p ) ; /** - @brief Read configurable "distance from transmitter" parameter from a device. - - The distance from transmitter parameter is used to compensate - the RF propagation delay, mostly with long wave receivers. - - The macro _pcps_has_tr_distance() or the API call mbg_dev_has_tr_distance() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::TR_DISTANCE variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_pzf() - @see mbg_dev_has_tr_distance() - @see mbg_set_tr_distance() - */ + * @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. + * + * The API call ::mbg_chk_dev_has_tr_distance 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 ::TR_DISTANCE variable to be filled up. + * + * @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 + * @see ::mbg_set_tr_distance + */ _MBG_API_ATTR int _MBG_API mbg_get_tr_distance( MBG_DEV_HANDLE dh, TR_DISTANCE *p ) ; /** - @brief Write configurable "distance from transmitter" parameter to a device. - - The distance from transmitter parameter is used to compensate - the RF propagation delay, mostly with long wave receivers. - - The macro _pcps_has_tr_distance() or the API call mbg_dev_has_tr_distance() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::TR_DISTANCE variable to be written - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_pzf() - @see mbg_dev_has_tr_distance() - @see mbg_get_tr_distance() - */ + * @brief Write configurable "distance from transmitter" parameter to a device. + * + * The distance from transmitter parameter is used to compensate + * the RF propagation delay, mostly with long wave receivers. + * + * The API call ::mbg_chk_dev_has_tr_distance 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 ::TR_DISTANCE variable to be written. + * + * @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 + * @see ::mbg_get_tr_distance + */ _MBG_API_ATTR int _MBG_API mbg_set_tr_distance( MBG_DEV_HANDLE dh, const TR_DISTANCE *p ) ; /** - @brief Check if a device provides a debug status word to be read. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_debug_status() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_debug_status( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Read a debug status word from a device. - - 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. - - See ::MBG_DEBUG_STATUS and related definitions for details. - - The macro _pcps_has_debug_status() or the API call mbg_dev_has_debug_status() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_DEBUG_STATUS variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_debug_status() - */ + * @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. + * + * See ::MBG_DEBUG_STATUS and related definitions for details. + * + * The API call ::mbg_chk_dev_has_debug_status 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 ::MBG_DEBUG_STATUS variable to be filled up + * + * @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 Check if a device provides an on-board event log. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_clr_evt_log() - @see mbg_get_num_evt_log_entries() - @see mbg_get_first_evt_log_entry() - @see mbg_get_next_evt_log_entry() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_evt_log( MBG_DEV_HANDLE dh, int *p ) ; - - /** - @brief Clear the card's on-board event log. - - The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_evt_log() - @see mbg_get_num_evt_log_entries() - @see mbg_get_first_evt_log_entry() - @see mbg_get_next_evt_log_entry() - */ + * @brief Clear the device's on-board event log + * + * 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 + * + * @see ::mbg_chk_dev_has_evt_log + * @see ::mbg_get_num_evt_log_entries + * @see ::mbg_get_first_evt_log_entry + * @see ::mbg_get_next_evt_log_entry + */ _MBG_API_ATTR int _MBG_API mbg_clr_evt_log( MBG_DEV_HANDLE dh ) ; /** - @brief Read details about a device's on-board event log buffer. - - The returned ::MBG_NUM_EVT_LOG_ENTRIES structure tells how many event log - entries which can be saved on the board, and how many entries actually - have been saved. - - The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - check whether this call is supported by a device. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_NUM_EVT_LOG_ENTRIES variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_evt_log() - @see mbg_clr_evt_log() - @see mbg_get_first_evt_log_entry() - @see mbg_get_next_evt_log_entry() - */ + * @brief Read details about a device's on-board event log buffer + * + * The returned ::MBG_NUM_EVT_LOG_ENTRIES structure tells how many + * event log entries can be saved on the board, and how many entries + * actually have been saved. + * + * 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. + * @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 + * + * @see ::mbg_chk_dev_has_evt_log + * @see ::mbg_clr_evt_log + * @see ::mbg_get_first_evt_log_entry + * @see ::mbg_get_next_evt_log_entry + */ _MBG_API_ATTR int _MBG_API mbg_get_num_evt_log_entries( MBG_DEV_HANDLE dh, MBG_NUM_EVT_LOG_ENTRIES *p ) ; /** - @brief Read the first (oldest) event log entry from a device. - - @note Subsequent reads should be made using mbg_get_next_evt_log_entry(). - - The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - check whether this call is supported by a device. - - If no (more) event log entry is available on the device then - the returned MBG_EVT_LOG_ENTRY::code is MBG_EVT_ID_NONE. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_evt_log() - @see mbg_clr_evt_log() - @see mbg_get_num_evt_log_entries() - @see mbg_get_next_evt_log_entry() - */ + * @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 + * 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 + * + * @see ::mbg_chk_dev_has_evt_log + * @see ::mbg_clr_evt_log + * @see ::mbg_get_num_evt_log_entries + * @see ::mbg_get_next_evt_log_entry + */ _MBG_API_ATTR int _MBG_API mbg_get_first_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) ; /** - @brief Read the next event log entry from a device. - - @note The first read should be made using mbg_get_first_evt_log_entry() - to set the on-board read index to the oldest entry. - - The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - check whether this call is supported by a device. - - If no (more) event log entry is available on the device then - the returned MBG_EVT_LOG_ENTRY::code is MBG_EVT_ID_NONE. - - @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_dev_has_evt_log() - @see mbg_clr_evt_log() - @see mbg_get_num_evt_log_entries() - @see mbg_get_first_evt_log_entry() - */ + * @brief Read the next event log entry from a device + * + * @note The first read should be made using ::mbg_get_first_evt_log_entry + * to set the on-board read index to the oldest entry. + * + * The 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 + * 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 + * + * @see ::mbg_chk_dev_has_evt_log + * @see ::mbg_clr_evt_log + * @see ::mbg_get_num_evt_log_entries + * @see ::mbg_get_first_evt_log_entry + */ _MBG_API_ATTR int _MBG_API mbg_get_next_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) ; /** - @brief Read the CPU affinity of a process. + * @brief Read the current GNSS mode info including current settings + * + * The ::MBG_GNSS_MODE_INFO structure tells which GNSS systems are supported + * by a device, and also includes the settings currently in effect. + * + * The API call ::mbg_chk_dev_is_gnss can be used to check whether + * this call is supported by a device. + * + * See also the notes for ::mbg_chk_dev_is_gnss. + * + * @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 + * + * @see ::mbg_set_gps_gnss_mode_settings + * @see ::mbg_get_gps_all_gnss_sat_info + * @see ::mbg_chk_dev_is_gnss + */ + _MBG_API_ATTR int _MBG_API mbg_get_gps_gnss_mode_info( MBG_DEV_HANDLE dh, MBG_GNSS_MODE_INFO *p_mi ) ; - This means on which of the available CPUs or CPU cores the process can be executed. + /** + * @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. + * + * The function ::mbg_get_gps_gnss_mode_info should have been called before + * to determine which GNSS settings are supported by the device. + * + * The API call ::mbg_chk_dev_is_gnss can be used to check whether + * this call is supported by a device. + * + * See also the notes for ::mbg_chk_dev_is_gnss. + * + * @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 + * + * @see ::mbg_get_gps_gnss_mode_info + * @see ::mbg_get_gps_all_gnss_sat_info + * @see ::mbg_chk_dev_is_gnss + */ + _MBG_API_ATTR int _MBG_API mbg_set_gps_gnss_mode_settings( MBG_DEV_HANDLE dh, const MBG_GNSS_MODE_SETTINGS *p_ms ) ; - @param pid The process ID. - @param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. + /** + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @see ::mbg_get_gps_gnss_mode_info + * @see ::mbg_set_gps_gnss_mode_settings + * @see ::mbg_chk_dev_is_gnss + */ + _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gnss_sat_info( MBG_DEV_HANDLE dh, GNSS_SAT_INFO_IDX gsii[], const MBG_GNSS_MODE_INFO *p_mi ) ; - @return ::MBG_SUCCESS or error code returned by the system call. + /** + * @brief Read common GPIO configuration limits + * + * The API call ::mbg_chk_dev_has_gpio checks whether + * this call is supported by a device. + * + * @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 + * + * @see ::mbg_chk_dev_has_gpio + * @see ::mbg_get_gpio_cfg_limits + * @see ::mbg_get_gps_all_gpio_info + * @see ::mbg_set_gps_gpio_settings_idx + * @see ::mbg_get_gps_all_gpio_status + */ + _MBG_API_ATTR int _MBG_API mbg_get_gpio_cfg_limits( MBG_DEV_HANDLE dh, MBG_GPIO_CFG_LIMITS *p ) ; - @see mbg_set_process_affinity() - @see mbg_set_current_process_affinity_to_cpu() - */ - _MBG_API_ATTR int _MBG_API mbg_get_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p ) ; + /** + * @brief Get all GPIO settings and capabilities. + * + * The API call ::mbg_chk_dev_has_gpio checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] gii An array of ::MBG_GPIO_STATUS_IDX structures to be filled up. + * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_gpio + * @see ::mbg_get_gpio_cfg_limits + * @see ::mbg_get_gps_all_gpio_info + * @see ::mbg_set_gps_gpio_settings_idx + * @see ::mbg_get_gps_all_gpio_status + */ + _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gpio_info( MBG_DEV_HANDLE dh, MBG_GPIO_INFO_IDX gii[], const MBG_GPIO_CFG_LIMITS *p_gcl ) ; /** - @brief Set the CPU affinity of a process. + * @brief Write the configuration for a single GPIO port to a device + * + * The ::MBG_GPIO_SETTINGS_IDX structure contains both the ::MBG_GPIO_SETTINGS + * and the port index value. + * + * The API call ::mbg_chk_dev_has_gpio 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 ::MBG_GPIO_SETTINGS_IDX structure to be written. + * + * @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 + * @see ::mbg_get_gps_all_gpio_info + * @see ::mbg_set_gps_gpio_settings_idx + * @see ::mbg_get_gps_all_gpio_status + */ + _MBG_API_ATTR int _MBG_API mbg_set_gps_gpio_settings_idx( MBG_DEV_HANDLE dh, const MBG_GPIO_SETTINGS_IDX *p ) ; - This determines on which of the available CPUs - the process is allowed to be executed. + /** + * @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 + * + * @see ::mbg_chk_dev_has_gpio + * @see ::mbg_get_gpio_cfg_limits + * @see ::mbg_get_gps_all_gpio_info + * @see ::mbg_set_gps_gpio_settings_idx + */ + _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gpio_status( MBG_DEV_HANDLE dh, MBG_GPIO_STATUS_IDX gsi[], const MBG_GPIO_CFG_LIMITS *p_gcl ) ; - @param pid The process ID. - @param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. + /** + * @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 + * + * @see ::mbg_chk_dev_has_xmr + * @see ::mbg_get_gps_all_xmr_status + * @see ::mbg_get_gps_all_xmr_info + * @see ::mbg_set_gps_xmr_settings_idx + * @see ::mbg_get_xmr_holdover_status + */ + _MBG_API_ATTR int _MBG_API mbg_get_xmr_instances( MBG_DEV_HANDLE dh, XMULTI_REF_INSTANCES *p ) ; - @return ::MBG_SUCCESS or error code returned by the system call. + /** + * @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 + * + * @see ::mbg_chk_dev_has_xmr + * @see ::mbg_get_xmr_instances + * @see ::mbg_get_gps_all_xmr_info + * @see ::mbg_set_gps_xmr_settings_idx + * @see ::mbg_get_xmr_holdover_status + */ + _MBG_API_ATTR int _MBG_API mbg_get_gps_all_xmr_status( MBG_DEV_HANDLE dh, XMULTI_REF_STATUS_IDX xmrsi[], const XMULTI_REF_INSTANCES *p_xmri ) ; - @see mbg_get_process_affinity() - @see mbg_set_current_process_affinity_to_cpu() - */ - _MBG_API_ATTR int _MBG_API mbg_set_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p ) ; + /** + * @brief 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 + * + * @see ::mbg_chk_dev_has_xmr + * @see ::mbg_get_xmr_instances + * @see ::mbg_get_gps_all_xmr_status + * @see ::mbg_set_gps_xmr_settings_idx + * @see ::mbg_get_xmr_holdover_status + */ + _MBG_API_ATTR int _MBG_API mbg_get_gps_all_xmr_info( MBG_DEV_HANDLE dh, XMULTI_REF_INFO_IDX xmrii[], const XMULTI_REF_INSTANCES *p_xmri ) ; /** - @brief Set the CPU affinity of a process for a single CPU only. + * @brief Write a single XMR setting to a device + * + * The ::XMULTI_REF_SETTINGS_IDX structure contains both the ::XMULTI_REF_SETTINGS + * and the index value. + * + * The API call ::mbg_chk_dev_has_xmr 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 ::XMULTI_REF_SETTINGS_IDX structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_xmr + * @see ::mbg_get_xmr_instances + * @see ::mbg_get_gps_all_xmr_status + * @see ::mbg_get_gps_all_xmr_info + * @see ::mbg_get_xmr_holdover_status + */ + _MBG_API_ATTR int _MBG_API mbg_set_gps_xmr_settings_idx( MBG_DEV_HANDLE dh, const XMULTI_REF_SETTINGS_IDX *p ) ; - This means the process may only be executed on that single CPU. + /** + * @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. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @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 + * + * @see ::mbg_chk_dev_has_xmr + * @see ::mbg_get_xmr_instances + * @see ::mbg_get_gps_all_xmr_status + * @see ::mbg_get_gps_all_xmr_info + * @see ::mbg_set_gps_xmr_settings_idx + */ + _MBG_API_ATTR int _MBG_API mbg_get_xmr_holdover_status( MBG_DEV_HANDLE dh, XMR_HOLDOVER_STATUS *p, const XMULTI_REF_INSTANCES *p_xmri ) ; - @param cpu_num The number of the CPU. + /** + * @brief Read the CPU affinity of a process + * + * This means on which of the available CPUs or CPU cores + * a process may be executed. + * + * @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 + * + * @see ::mbg_set_process_affinity + * @see ::mbg_set_current_process_affinity_to_cpu + */ + _MBG_API_ATTR int _MBG_API mbg_get_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p ) ; - @return ::MBG_SUCCESS or error code returned by the system call. + /** + * @brief Set the CPU affinity of a process. + * + * This determines on which of the available CPUs + * or CPU cores the process is allowed to be executed. + * + * @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 + * + * @see ::mbg_get_process_affinity + * @see ::mbg_set_current_process_affinity_to_cpu + */ + _MBG_API_ATTR int _MBG_API mbg_set_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p ) ; - @see mbg_get_process_affinity() - @see mbg_set_process_affinity() - */ + /** + * @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 + * + * @see ::mbg_get_process_affinity + * @see ::mbg_set_process_affinity + */ _MBG_API_ATTR int _MBG_API mbg_set_current_process_affinity_to_cpu( int cpu_num ) ; /** - @brief Create a new execution thread for the current process. - - This function is only implemented for targets which support threads. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure to be filled up. - @param fnc The name of the thread function to be started. - @param arg A generic argument passed to the thread function. - - @return ::MBG_SUCCESS or error code returned by the system call. - - @see mbg_thread_stop() - @see mbg_thread_sleep_interruptible() - @see mbg_thread_set_affinity() - */ - _MBG_API_ATTR int _MBG_API mbg_thread_create( MBG_THREAD_INFO *p_ti, MBG_THREAD_FNC_RET_VAL (MBG_THREAD_FNC_ATTR *fnc)(void *), void *arg ) ; + * @brief Create a new execution thread for the current process. + * + * This function is only implemented for targets that support threads. + * + * @param[in] p_ti Pointer to a ::MBG_THREAD_INFO structure to be filled up. + * @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 + * + * @see ::mbg_thread_stop + * @see ::mbg_thread_sleep_interruptible + * @see ::mbg_thread_set_affinity + */ + _MBG_API_ATTR int _MBG_API mbg_thread_create( MBG_THREAD_INFO *p_ti, MBG_THREAD_FNC fnc, void *arg ) ; /** - @brief Stop a thread which has been created by mbg_thread_create(). - - Wait until the thread has finished and release all resources. - This function is only implemented for targets which support threads. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. - - @return ::MBG_SUCCESS or error code returned by the system call. - - @see mbg_thread_create() - @see mbg_thread_sleep_interruptible() - @see mbg_thread_set_affinity() - */ + * @brief Stop a thread which has been created by ::mbg_thread_create. + * + * Wait until the thread has finished and release all resources. + * + * This function is only implemented for targets that support threads. + * + * @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 + * + * @see ::mbg_thread_create + * @see ::mbg_thread_sleep_interruptible + * @see ::mbg_thread_set_affinity + */ _MBG_API_ATTR int _MBG_API mbg_thread_stop( MBG_THREAD_INFO *p_ti ) ; /** - @brief Let the current thread sleep for a certain interval. - - The sleep is interrupted if a signal is received indicating - the thread should terminate. - - This function is only implemented for targets which support threads. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. - @param sleep_ms The number of milliseconds to sleep - @return 0 if the sleep interval has expired normally - 1 if a signal to terminate has been received - <0 if an error has occurred - - @see mbg_thread_create() - @see mbg_thread_stop() - @see mbg_thread_set_affinity() - */ + * @brief Let the current thread sleep for a certain interval + * + * The sleep is interrupted if a signal is received indicating + * the thread should terminate. + * + * 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 + * + * @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 + * + * @see ::mbg_thread_create + * @see ::mbg_thread_stop + * @see ::mbg_thread_set_affinity + */ _MBG_API_ATTR int _MBG_API mbg_thread_sleep_interruptible( MBG_THREAD_INFO *p_ti, ulong sleep_ms ) ; /** - @brief Set the CPU affinity of a single thread. - - This determines on which of the available CPUs the thread - is allowed to be executed. - - This function is only implemented for targets which support thread affinity. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. - @param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. - - @return ::MBG_SUCCESS or error code returned by the system call. - - @see mbg_thread_create() - @see mbg_thread_stop() - @see mbg_thread_sleep_interruptible() - */ + * @brief Set the CPU affinity of a single thread + * + * This determines on which of the available CPUs the thread + * is allowed to be executed. + * + * This function is only implemented for targets that support thread affinity. + * + * @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 + * + * @see ::mbg_thread_create + * @see ::mbg_thread_stop + * @see ::mbg_thread_sleep_interruptible + */ _MBG_API_ATTR int _MBG_API mbg_thread_set_affinity( MBG_THREAD_INFO *p_ti, MBG_CPU_SET *p ) ; /** - @brief Set up a ::MBG_POLL_THREAD_INFO structure and start a new thread. - - The new thread runs the mbg_xhrt_poll_thread_fnc() function. - - This function is only implemented for targets which support threads. - - @param *p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. - @param dh the handle of the device to be polled. - @param freq_hz The initial cycles frequency, if known, in Hz. - @param sleep_ms the sleep interval for the poll thread function in ms. - If this parameter is 0 then the default sleep interval is used. - - @return ::MBG_SUCCESS on success, - ::MBG_ERR_NOT_SUPP_BY_DEV if the device to poll does not support HR time - else the result of mbg_thread_create() - - @see mbg_xhrt_poll_thread_fnc() - @see mbg_xhrt_poll_thread_stop() - @see mbg_get_xhrt_time_as_pcps_hr_time() - @see mbg_get_xhrt_time_as_filetime() - @see mbg_get_xhrt_cycles_frequency() - */ + * @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. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. + * @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. + * + * @return ::MBG_SUCCESS on success, + * ::MBG_ERR_NOT_SUPP_BY_DEV if the device to poll does not support HR time + * else the result of ::mbg_thread_create. + * + * @see ::mbg_xhrt_poll_thread_stop + * @see ::mbg_get_xhrt_time_as_pcps_hr_time + * @see ::mbg_get_xhrt_time_as_filetime + * @see ::mbg_get_xhrt_cycles_frequency + */ _MBG_API_ATTR int _MBG_API mbg_xhrt_poll_thread_create( MBG_POLL_THREAD_INFO *p_pti, MBG_DEV_HANDLE dh, MBG_PC_CYCLES_FREQUENCY freq_hz, int sleep_ms ) ; /** - @brief Stop a polling thread started by mbg_xhrt_poll_thread_create(). - - This call also releases all associated resources. - - @param *p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. - - @return the result of mbg_thread_stop() - - @see mbg_xhrt_poll_thread_fnc() - @see mbg_xhrt_poll_thread_create() - @see mbg_get_xhrt_time_as_pcps_hr_time() - @see mbg_get_xhrt_time_as_filetime() - @see mbg_get_xhrt_cycles_frequency() - */ + * @brief Stop a polling thread started by ::mbg_xhrt_poll_thread_create + * + * This call also releases all associated resources. + * + * @param[in,out] p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. + * + * @return The result of ::mbg_thread_stop. + * + * @see ::mbg_xhrt_poll_thread_create + * @see ::mbg_get_xhrt_time_as_pcps_hr_time + * @see ::mbg_get_xhrt_time_as_filetime + * @see ::mbg_get_xhrt_cycles_frequency + */ _MBG_API_ATTR int _MBG_API mbg_xhrt_poll_thread_stop( MBG_POLL_THREAD_INFO *p_pti ) ; /** - @brief Retrieve an extrapolated time stamp in PCPS_HR_TIME format. - - 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 mbg_xhrt_poll_thread_fnc() for details and limitations. - - This function is only implemented for targets which support threads. - - @param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. - @param *p_hrt Pointer to a ::PCPS_HR_TIME structure to be filled up. - - @return MBG_SUCCESS or another return value from the polling thread's IOCTL call. - - @see mbg_xhrt_poll_thread_fnc() - @see mbg_xhrt_poll_thread_create() - @see mbg_xhrt_poll_thread_stop() - @see mbg_get_xhrt_time_as_filetime() - @see mbg_get_xhrt_cycles_frequency() - */ + * @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. + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. + * @param[out] p_hrt Pointer to a ::PCPS_HR_TIME structure to be filled up. + * + * @return The return code from the API call used by the polling thread + * to read the time from the device, usually ::mbg_get_hr_time_cycles, + * so ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * + * @ingroup mbg_xhrt_poll_group + * @see ::mbg_xhrt_poll_thread_create + * @see ::mbg_xhrt_poll_thread_stop + * @see ::mbg_get_xhrt_time_as_filetime + * @see ::mbg_get_xhrt_cycles_frequency + * @see @ref mbg_xhrt_poll_group + */ _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. - - 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 mbg_xhrt_poll_thread_fnc() for details and limitations. - - Since FILETIME is a Windows specific type this function is only - implemented under Windows. - - @param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. - @param *p_ft Pointer to a ::FILETIME structure to be filled up. - - @return MBG_SUCCESS or another return value from the polling thread's IOCTL call. - - @see mbg_xhrt_poll_thread_fnc() - @see mbg_xhrt_poll_thread_create() - @see mbg_xhrt_poll_thread_stop() - @see mbg_get_xhrt_time_as_pcps_hr_time() - @see mbg_get_xhrt_cycles_frequency() - */ + * @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. + * + * @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. + * + * @return The return code from the API call used by the polling thread + * to read the time from the device, usually ::mbg_get_hr_time_cycles, + * so ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * + * @ingroup mbg_xhrt_poll_group + * @see ::mbg_xhrt_poll_thread_create + * @see ::mbg_xhrt_poll_thread_stop + * @see ::mbg_get_xhrt_time_as_pcps_hr_time + * @see ::mbg_get_xhrt_cycles_frequency + * @see @ref mbg_xhrt_poll_group + */ _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. - - The frequency is determined by the device polling thread. - See mbg_xhrt_poll_thread_fnc() for details and limitations. - - This function is only implemented for targets which support threads. - - @param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. - @param *p_freq_hz Pointer to a ::MBG_PC_CYCLES_FREQUENCY variable in which the frequency is returned. - @return a status code from the polling thread: MBG_SUCCESS or an IOCTL error code. - - @see mbg_xhrt_poll_thread_fnc() - @see mbg_xhrt_poll_thread_create() - @see mbg_xhrt_poll_thread_stop() - @see mbg_get_xhrt_time_as_pcps_hr_time() - @see mbg_get_xhrt_time_as_filetime() - */ + * @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. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. + * @param[out] p_freq_hz Pointer to a ::MBG_PC_CYCLES_FREQUENCY variable in which the frequency is returned. + * + * @return The return code from the API call used by the polling thread + * to read the time from the device, usually ::mbg_get_hr_time_cycles, + * so ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * + * @ingroup mbg_xhrt_poll_group + * @see ::mbg_xhrt_poll_thread_create + * @see ::mbg_xhrt_poll_thread_stop + * @see ::mbg_get_xhrt_time_as_pcps_hr_time + * @see ::mbg_get_xhrt_time_as_filetime + * @see @ref mbg_xhrt_poll_group + */ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_cycles_frequency( MBG_XHRT_INFO *p, MBG_PC_CYCLES_FREQUENCY *p_freq_hz ) ; /** - @brief Retrieve the default system's cycles counter frequency from the kernel driver. - - This API call can be used on systems which don't provide this information in user space. - - @param dh handle of the device to which the IOCTL call is sent. - @param *p Pointer of a ::MBG_PC_CYCLES_FREQUENCY variable to be filled up. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_default_cycles_frequency() - */ + * @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. + * + * @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 + * + * @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. - - @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. - - @return the default cycles counter frequency in Hz, or 0 if the value is not available. - - @see mbg_get_default_cycles_frequency_from_dev() -*/ + * @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. + * + * @see ::mbg_get_default_cycles_frequency_from_dev + */ _MBG_API_ATTR MBG_PC_CYCLES_FREQUENCY _MBG_API mbg_get_default_cycles_frequency( void ) ; /* ----- function prototypes end ----- */ -#ifdef __cplusplus -} -#endif - #if defined( MBG_TGT_WIN32 ) static __mbg_inline -MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, +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 ) { - DWORD ReturnedLength; + DWORD ReturnedLength = 0; if ( !DeviceIoControl( dh, ioctl_code, (LPVOID) in_p, in_sz, out_p, out_sz, @@ -3616,18 +5437,19 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, NULL ) ) { - DWORD rc = GetLastError(); - -#if 0 //##++++++++++++++++++++++++ -// We can't call mbgsvctl_log_mbgdevio_error() here (for now). -// Is is defined in mbgsvctl.h, and including mbgsvc.h here, -// or copying the prototype here results in DLL import/export -// mismatch errors. - - // do not report a USB device timeout error - if ( rc != _mbg_err_to_os( MBG_ERR_USB_ACCESS ) ) - mbgsvctl_log_mbgdevio_error( ioctl_code, rc ); -#endif + DWORD last_error = GetLastError(); + int rc = mbg_win32_sys_err_to_mbg( last_error, NULL ); + + #if 0 //### TODO FIXME + // We can't call mbgsvctl_log_mbgdevio_error() here (for now). + // Is is defined in mbgsvctl.h, and including mbgsvctl.h here, + // or copying the prototype here results in DLL import/export + // mismatch errors. + + // do not report a USB device timeout error + if ( rc != MBG_ERR_USB_ACCESS ) + mbgsvctl_log_mbgdevio_error( ioctl_code, rc ); + #endif return rc; } @@ -3639,10 +5461,36 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, #define _do_mbg_ioctl( _dh, _ioctl, _p, _in_sz, _out_sz ) \ do_mbg_ioctl( _dh, _ioctl, (LPVOID) _p, _in_sz, (LPVOID) _p, _out_sz ) -#elif defined( MBG_TGT_UNIX ) +#elif defined( MBG_HAS_POSIX_IOCTL ) + + // In case of an error ioctl returns -1, and errno has been set + // to a *positive* POSIX error code. + + static __mbg_inline + MBGDEVIO_RET_VAL do_mbg_ioctl( 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 + { + int sys_errno = errno; + int rc = mbg_posix_errno_to_mbg( sys_errno, NULL ); + + #if DEBUG_IOCTL_CALLS + fprintf( stderr, "IOCTL %s (0x%08lX) error: %s (errno: %i) --> %s (rc: %i)\n", + mbgioctl_get_name( ioctl_code ), (ulong) ioctl_code, + strerror( sys_errno ), sys_errno, + mbg_strerror( rc ), rc ); + #endif + + return rc; + } + + return MBG_SUCCESS; + } #define _do_mbg_ioctl( _dh, _ioctl, _p, _in_sz, _out_sz ) \ - ioctl( _dh, _ioctl, _p ) + do_mbg_ioctl( _dh, _ioctl, _p ) #endif @@ -3651,30 +5499,33 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, // The code below depends on whether the target device is accessed via // IOCTLs to a device driver, or the hardware is accessed directly. -#if defined( MBG_USE_KERNEL_DRIVER ) // using IOCTL to access device driver - -/** - @brief Send a generic IOCTL command to the driver. - - @param dh Valid handle to a Meinberg device - @param info Additional information for the kernel driver depending on - the IOCTL code, i.e. the low level function to be called: <br> - one of the PCPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}<br> - one of the PC_GPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}_GPS<br> - one of the PCPS_GEN_IO_... enumeration codes with IOCTL_PCPS_GENERIC_IO - @param ioctl One of the IOCTL_GENERIC_... codes telling the kernel driver - which low level function to use, e.g. normal read or write, - large (GPS) data read or write, or generic I/O. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. -*/ +#if MBG_TGT_USE_IOCTL + + /** + * @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 + * + * @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, const void *in_p, int in_sz, void *out_p, int out_sz ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; // Generic IOCTL calls always need to pass some info beside // the I/O buffers down to the driver, which usually is @@ -3687,11 +5538,16 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, IOCTL_GENERIC_REQ req = { 0 }; - req.info = info; - req.in_p = in_p; + req.in_p = (uintptr_t) in_p; + req.out_p = (uintptr_t) out_p; req.in_sz = in_sz; - req.out_p = out_p; req.out_sz = out_sz; + req.info = info; + + #if DEBUG_IOCTL_CALLS + printf( "inp: %p --> 0x%" PRIx64 " (%lu)\n", in_p, req.in_p, (ulong) req.in_sz ); + printf( "outp: %p --> 0x%" PRIx64 " (%lu)\n", out_p, req.out_p, (ulong) req.out_sz ); + #endif rc = _do_mbg_ioctl( dh, ioctl_code, &req, sizeof( req ), 0 ); @@ -3704,7 +5560,7 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, p_buff = (IOCTL_GENERIC_BUFFER *) malloc( buff_size ); if ( p_buff == NULL ) - return _mbg_err_to_os( MBG_ERR_NO_MEM ); + return MBG_ERR_NO_MEM; p_buff->ctl.info = info; p_buff->ctl.data_size_in = in_sz; @@ -3724,7 +5580,7 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, #endif - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbgdevio_do_gen_io @@ -3751,8 +5607,10 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, #define _mbgdevio_write_cmd( _dh, _cmd, _ioctl ) \ _do_mbgdevio_write( _dh, _cmd, _ioctl, NULL, 0 ) + #define _mbgdevio_read_gps _do_mbgdevio_read #define _mbgdevio_read_gps_var _mbgdevio_read_var + #define _mbgdevio_write_gps _do_mbgdevio_write #define _mbgdevio_write_gps_var _mbgdevio_write_var @@ -3772,12 +5630,12 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, mbgdevio_do_gen_io( _dh, _cmd, IOCTL_PCPS_GENERIC_WRITE_GPS, _p, _sz, NULL, 0 ) -#else // accessing hardware device directly +#else // !MBG_TGT_USE_IOCTL, accessing hardware device directly - #define _mbgdevio_chk_cond( _cond ) \ - { \ - if ( !(_cond) ) \ - return _mbg_err_to_os( MBG_ERR_NOT_SUPP_BY_DEV ); \ + #define _mbgdevio_chk_cond( _cond ) \ + { \ + if ( !(_cond) ) \ + return MBG_ERR_NOT_SUPP_BY_DEV; \ } #define _mbgdevio_read( _dh, _cmd, _ioctl, _p, _sz ) \ @@ -3826,7 +5684,7 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, #define _mbgdevio_gen_write_gps( _dh, _cmd, _p, _sz ) \ _mbgdevio_write_gps( _dh, _cmd, -1, _p, _sz ) -#endif +#endif // !MBG_TGT_USE_IOCTL @@ -3858,38 +5716,52 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, -#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_UNIX ) +#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX ) + +// NOTE +// 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. + +#if !defined( __BORLANDC__ ) static __mbg_inline void mbg_chk_tstamp64_leap_sec( uint64_t *tstamp64, PCPS_TIME_STATUS_X *status ) { if ( *status & ( PCPS_LS_ANN | PCPS_LS_ENB ) ) { - time_t t = (uint32_t) ( *tstamp64 >> 32 ); - struct tm tm = *gmtime( &t ); + struct tm tm = { 0 }; + time_t t = cvt_to_time_t( (uint32_t) ( (*tstamp64) >> 32 ) ); + int rc = mbg_gmtime( &tm, &t ); - // Handle leap second and status - if ( tm.tm_hour == 0 && tm.tm_min == 0 && tm.tm_sec == 0 ) + if ( mbg_rc_is_success( rc ) ) { - if ( *status & PCPS_LS_ANN ) + // Handle leap second and status + if ( tm.tm_hour == 0 && tm.tm_min == 0 && tm.tm_sec == 0 ) { - // Set leap second enabled flag on rollover to the leap second and clear announce flag - *status &= ~PCPS_LS_ANN; - *status |= PCPS_LS_ENB; - - // Decrement interpolated second to avoid automated overflow during the leap second. - // Second 59 appears for the second time. - *tstamp64 -= PCPS_HRT_BIN_FRAC_SCALE; + if ( *status & PCPS_LS_ANN ) + { + // Set leap second enabled flag on rollover to the leap second and clear announce flag + *status &= ~PCPS_LS_ANN; + *status |= PCPS_LS_ENB; + + // Decrement interpolated second to avoid automated overflow during the leap second. + // Second 59 appears for the second time. + *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 + *status &= ~( PCPS_LS_ANN | PCPS_LS_ENB ); } - else - 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 ); } } } // mbg_chk_tstamp64_leap_sec -#endif // defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_UNIX ) +#endif // !defined( __BORLANDC__ ) + +#endif // defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX ) @@ -3925,6 +5797,10 @@ void uint64_to_pcps_time_stamp( PCPS_TIME_STAMP *ts, uint64_t n ) #endif +#ifdef __cplusplus +} +#endif + #if defined( _USING_BYTE_ALIGNMENT ) #pragma pack() // set default alignment #undef _USING_BYTE_ALIGNMENT @@ -3934,6 +5810,7 @@ void uint64_to_pcps_time_stamp( PCPS_TIME_STAMP *ts, uint64_t n ) #undef _ext +#undef _DO_INIT #endif /* _MBGDEVIO_H */ diff --git a/mbglib/common/mbgdevio_import.c b/mbglib/common/mbgdevio_import.c new file mode 100644 index 0000000..51637e0 --- /dev/null +++ b/mbglib/common/mbgdevio_import.c @@ -0,0 +1,116 @@ + +/************************************************************************** + * + * $Id: mbgdevio_import.c 1.1 2015/11/06 15:28:12Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Import mbgdevio API functions dynamically at runtime. + * This removes dependencies on the availability of the + * mbgdevio DLL. + * + * ----------------------------------------------------------------------- + * $Log: mbgdevio_import.c $ + * Revision 1.1 2015/11/06 15:28:12Z martin + * Initial revision. + * + **************************************************************************/ + +#define _MBGDEVIO_IMPORT + #include <mbgdevio_import.h> +#undef _MBGDEVIO_IMPORT + + +static const char *mbgdevio_dll_name = "mbgdevio.dll"; +static HINSTANCE mbgdevio_dll_handle; + + + +// The STRINGIFY() macro can be used to convert a macro argument +// to a string. The XSTRINGIFY() macro is simply a helper macro +// which should not be used alone. +#define STRINGIFY(x) XSTRINGIFY(x) +#define XSTRINGIFY(x) #x + + +#define _import_mbgdevio_fnc_chk( _f ) \ +{ \ + fnc_##_f = (fnc_##_f##_t *) \ + GetProcAddress( mbgdevio_dll_handle, STRINGIFY( _f ) ); \ + \ + if ( fnc_##_f == NULL ) \ + if ( rc == ERROR_SUCCESS ) \ + rc = GetLastError(); \ +} + + +#define _unimport_mbgdevio_fnc( _f ) \ + fnc_##_f = NULL; + + + + +static /*HDR*/ +DWORD mbg_svc_load_dll( const char *dll_name, HINSTANCE *ph ) +{ + if ( *ph == NULL ) + { + // Try to load the DLL. + *ph = LoadLibrary( dll_name ); + + // If unsuccessfull, we can't go on. + if ( *ph == NULL ) + return GetLastError(); + } + + return ERROR_SUCCESS; + +} // mbg_svc_load_dll + + + +static /*HDR*/ +void mbg_unimport_mbgdevio_api( void ) +{ + if ( mbgdevio_dll_handle ) + { + // Be sure to import the same list of functions + // in mbg_import_mbgdevio_api. + _unimport_mbgdevio_fnc( mbg_get_time ); + _unimport_mbgdevio_fnc( mbg_get_hr_time ); + + FreeLibrary( mbgdevio_dll_handle ); + mbgdevio_dll_handle = NULL; + } + +} // mbg_unimport_mbgdevio_api + + + +/*HDR*/ +DWORD mbg_import_mbgdevio_api( void ) +{ + DWORD rc; + + rc = mbg_svc_load_dll( mbgdevio_dll_name, &mbgdevio_dll_handle ); + + if ( rc == ERROR_SUCCESS ) + { + // Be sure to unimport the same list of functions + // in mbg_unimport_mbgdevio_api. + _import_mbgdevio_fnc_chk( mbg_get_time ); + _import_mbgdevio_fnc_chk( mbg_get_hr_time ); + } + + if ( rc != ERROR_SUCCESS ) + mbg_unimport_mbgdevio_api(); // clean up + else + atexit( mbg_unimport_mbgdevio_api ); + + return rc; + +} // mbg_import_mbgdevio_api + + + diff --git a/mbglib/common/mbgdevio_import.h b/mbglib/common/mbgdevio_import.h new file mode 100644 index 0000000..bf1299d --- /dev/null +++ b/mbglib/common/mbgdevio_import.h @@ -0,0 +1,112 @@ + +/************************************************************************** + * + * $Id: mbgdevio_import.h 1.1 2015/11/06 15:28:22Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for mbgdevio_import.c. + * + * To avoid dependencies on the availability of a particular DLL at + * runtime, an application can dynamically import every function it + * needs from that DLL at program start and set up some pointers + * to the imported functions, and call the API functions *only* + * via those pointers. + * + * This works well if the DLL is available and all functions could + * be imported, but if the DLL is not available, or not all functions + * could be imported then some or all function pointers are NULL, + * and the application will trap whenever it tries to call such + * function via the unassigned pointer. + * + * This source module provides the mbg_import_mbgdevio_api() function + * which returns 0 if all API functions could be imported successfully. + * So an application can call this function at startup, and use the + * imported functions *only* if the import finished successfully. + * + * ----------------------------------------------------------------------- + * $Log: mbgdevio_import.h $ + * Revision 1.1 2015/11/06 15:28:22Z martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _MBGDEVIO_IMPORT_H +#define _MBGDEVIO_IMPORT_H + + +/* Other headers to be included */ + +#include <mbgdevio.h> + + +#ifdef _MBGDEVIO_IMPORT + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + + +// To import API functions dynamically we need a function typedef +// for each function prototype, and a function pointer variable. +// To simplify the source code we use the following naming conventions: +// +// Function name: mbg_get_time (original name from mbgdevio.h) +// Function type: mbg_get_time_t (according prototype of the original function) +// Function pointer: mbg_get_time_t *fnc_mbg_get_time (function pointer variable) +// +// A list of function types which have to match the prototypes +// in mbgdevio.h. These typedefs will probably be moved +// to mbgdevio.h later. + +typedef _MBG_API_ATTR int (_MBG_API fnc_mbg_get_time_t)( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ; +typedef _MBG_API_ATTR int (_MBG_API fnc_mbg_get_hr_time_t)( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) ; + + +// A list of function pointer variables using the function types above. +// For each API function to be imported there must be an appropriate +// function pointer variable. + +_ext fnc_mbg_get_time_t *fnc_mbg_get_time; +_ext fnc_mbg_get_hr_time_t *fnc_mbg_get_hr_time; + +// Whenever new variables are added here the import and unimport +// entries in the functions mbg_import_mbgdevio_api() and +// mbg_unimport_mbgdevio_api() need to be updated accordingly. +// Otherwise the functions will not be imported, thus the function +// pointer will always be NULL, and the application will trap if +// the function is called via the pointer. + + + +/* function prototypes: */ + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + DWORD mbg_import_mbgdevio_api( void ) ; + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _MBGDEVIO_IMPORT_H */ diff --git a/mbglib/common/mbgerror.c b/mbglib/common/mbgerror.c new file mode 100644 index 0000000..c0f1a3f --- /dev/null +++ b/mbglib/common/mbgerror.c @@ -0,0 +1,1191 @@ + +/************************************************************************** + * + * $Id: mbgerror.c 1.6 2018/11/22 14:47:15Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Meinberg Library to communicate with USB devices from user space + * + * ----------------------------------------------------------------------- + * $Log: mbgerror.c $ + * Revision 1.6 2018/11/22 14:47:15Z martin + * Support QNX target. + * New function mbg_win32_ntstatus_to_mbg(). + * Added and renamed static code conversion tables. + * Added and updated doxygen comments. + * Revision 1.5 2018/09/21 09:44:38 martin + * Renamed mbg_win32_last_err_to_mbg() to + * mbg_win32_sys_err_to_mbg(). + * Translate win32 error codes ERROR_BUFFER_OVERFLOW + * and ERROR_INSUFFICIENT_BUFFER. + * Updated some comments. + * Revision 1.4 2018/06/25 14:21:09Z martin + * Cleaned up definition and usage of control macros. + * Distinguish between kernel mode and user mode on Windows. + * Support some new error codes. + * Revision 1.3 2017/07/05 09:20:07 martin + * Fixed a bug where POSIX error ENODEV wasn't mapped at all, but + * EXDEV was instead translated erraneously to MBG_ERR_NO_DEV. + * Mapped POSIX error ENOSPC to MBG_ERR_NO_SPACE, and EFAULT + * to MBG_ERR_INV_PARM. + * Mapped Windows WSA error codes WSAEFAULT and WSAEINVAL + * to MBG_ERR_INV_PARM. + * Renamed mbg_ioctl_err() to mbg_cond_err_msg(). + * New function mbg_cond_err_msg_info() which takes an optional + * info string which is printed if the error code to be checked + * is MBG_ERR_NOT_SUPP_BY_DEV. + * Fixed build in Windows kernel mode. + * Fixed syntax error in CVI-specific code. + * Quieted some compiler warnings. + * Revision 1.2 2016/08/05 12:25:44Z martin + * Added some functions. + * Revision 1.1 2014/03/07 12:08:14 martin + * Initial revision. + * + **************************************************************************/ + +#define _MBGERROR + #include <mbgerror.h> +#undef _MBGERROR + +#include <mbg_tgt.h> + +#if defined( MBG_TGT_WIN32 ) + + #if !defined( MBG_TGT_KERNEL ) + #include <errno.h> + #include <stdio.h> + + #define _MBG_TGT_HAS_POSIX_ERRNO 1 + #define _MBG_TGT_HAS_WIN32_ERR_API 1 + #else + #include <mbgddmsg.h> + + #define _MBG_TGT_OMIT_LAST_ERROR 1 + #define _MBG_TGT_OMIT_ERR_MSG 1 // Not (yet) supported in Windows kernel mode + #endif + +#elif defined( MBG_TGT_CVI ) + + // Nothing to do here. + +#elif defined( MBG_TGT_LINUX ) + + #if !defined( MBG_TGT_KERNEL ) + #include <errno.h> + #include <stdio.h> + #include <string.h> + #include <netdb.h> + + #define _MBG_TGT_HAS_POSIX_ERRNO 1 + #define _MBG_TGT_HAS_POSIX_H_ERRNO 1 + #else + #include <asm/errno.h> + + #define _MBG_TGT_HAS_POSIX_ERRNO 1 + #define _MBG_TGT_OMIT_LAST_ERROR 1 + #define _MBG_TGT_OMIT_ERR_MSG 1 + #endif + +#elif defined( MBG_TGT_BSD ) + + #if !defined( MBG_TGT_KERNEL ) + #include <errno.h> + #include <stdio.h> + #include <string.h> + #include <netdb.h> + + #define _MBG_TGT_HAS_POSIX_ERRNO 1 + #define _MBG_TGT_HAS_POSIX_H_ERRNO 1 + #else + #include <sys/errno.h> + #if defined( MBG_TGT_FREEBSD ) + #include <sys/stddef.h> // NULL + #elif defined( MBG_TGT_NETBSD ) + #include <sys/null.h> // NULL + #endif + + #define _MBG_TGT_HAS_POSIX_ERRNO 1 + #define _MBG_TGT_OMIT_LAST_ERROR 1 + #define _MBG_TGT_OMIT_ERR_MSG 1 + #endif + +#elif defined( MBG_TGT_QNX_NTO ) // QNX 6.x only, but not QNX 4.x + + #include <stdio.h> + #include <errno.h> + #include <string.h> + #include <netdb.h> + + #define _MBG_TGT_HAS_POSIX_ERRNO 1 + #define _MBG_TGT_HAS_POSIX_H_ERRNO 1 + +#elif defined( MBG_TGT_DOS ) + + #include <stdio.h> + #include <stdlib.h> + #include <stddef.h> + #include <errno.h> + + #define _MBG_TGT_HAS_POSIX_ERRNO 1 + #define _MBG_TGT_OMIT_SOCKET_ERRORS 1 // No network socket support by OS + +#endif + +#if defined( USE_MBG_ZLIB ) + #include <zlib.h> +#endif + +#if !defined( DEBUG ) + // FIXME This should be done globally across projects. + #define DEBUG 0 +#endif + + +typedef struct +{ + int srch_errno; + int mapped_errno; + +} ERRNO_CNV_ENTRY; + + + +#if defined( _MBG_TGT_HAS_POSIX_ERRNO ) + +/** + * @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 + * depending on the OS type and version. + * + * Linux: /usr/include/asm-generic/errno.h<br> + * FreeBSD/NetBSD: /usr/include/sys/errno.h + * + * @see ::mbg_posix_errno_to_mbg + * @see POSIX spec at http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_03 + */ +static ERRNO_CNV_ENTRY posix_errno_table[] = +{ + { EPERM, MBG_ERR_PERM }, // 1, Operation not permitted (e.g. when trying to set time without sufficient permissions). + { ENOENT, MBG_ERR_NO_ENTITY }, // 2, No such file or directory. + // { ESRCH, }, // 3, No such process. + { EINTR, MBG_ERR_INTR }, // 4, Interrupted function call. + { EIO, MBG_ERR_IO }, // 5, Input/output error (from physical device). + { ENXIO, MBG_ERR_NOT_FOUND }, // 6, No such device or address (refering to a device that doesn't exist, or request beyond its capabilities) of the device. + // { E2BIG, }, // 7, Argument list too long (or lack of space in an output buffer, or argument exceeds system-imposed maximum. + // { ENOEXEC, }, // 8, Exec format error (executable file format error). + // { EBADF, }, // 9, Bad file number/descriptor (or a read (write) tried on a file only open for writing (reading)). + // { ECHILD, }, // 10, No child processes (when waiting for child process). + { EAGAIN, MBG_ERR_AGAIN }, // 11, Try again, resource temporarily unavailable (later calls may complete normally, maybe same as EWOULDBLOCK). + { 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_INV_PARM }, // 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). + { EBUSY, MBG_ERR_BUSY }, // 16, Device or resource busy. + { EEXIST, MBG_ERR_EXIST }, // 17, File exists. + // { EXDEV, }, // 18, Cross-device link. + { ENODEV, MBG_ERR_NO_DEV }, // 19, ### No such device (operation not supported by device). + // { ENOTDIR, }, // 20, Not a directory (when a directory was expected for the operation). + // { EISDIR, }, // 21, Is a directory (when a directory was *not* expected for the operation). + { EINVAL, MBG_ERR_INV_PARM }, // 22, Invalid argument (was supplied to a function). + // { ENFILE, }, // 23, Too many files open in system (file table overflow). + // { EMFILE, }, // 24, Too many open files (or file descriptor value too large). + { ENOTTY, MBG_ERR_NOT_SUPP_BY_DEV }, // 25, ### Not a typewriter (actually means "inappropriate I/O control for device"). + // { ETXTBSY, }, // 26, Text file busy ("text" actually means "binary program file"). + // { EFBIG, }, // 27, File too large. + { ENOSPC, MBG_ERR_NO_SPACE }, // 28, No space left on device (when writing a file or extending directory). + { ESPIPE, MBG_ERR_PIPE }, // 29, Illegal seek (when attempting to access the file offset associated with a pipe or FIFO). + // { EROFS, }, // 30, Read-only file system. + // { EMLINK, }, // 31, Too many links (link count of a single file exceed). + // { 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( ETIME ) + { ETIME, MBG_ERR_TIMER }, // 62, Timer expired (e.g. stream timeout on USB disconnect). +#endif +#if defined( EOVERFLOW ) + { EOVERFLOW, MBG_ERR_OVERFLOW }, // 75, Value too large for defined data type (can't be stored). +#endif +#if defined( ENOTSOCK ) + { 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 +#endif +#if defined( ETIMEDOUT ) + { ETIMEDOUT, MBG_ERR_TIMEOUT }, // 110, Connection timed out +#endif + { 0, 0 } // end-of-table identifier + +}; // posix_errno_table + +#endif // defined( _MBG_TGT_HAS_POSIX_ERRNO ) + + + +#if defined( _MBG_TGT_HAS_POSIX_H_ERRNO ) + +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 + // { TRY_AGAIN, }, // A temporary error occurred on an authoritative name server. Try again later. + { 0, 0 } // end-of-table identifier + +}; // posix_h_errno_table + +#endif // defined( _MBG_TGT_HAS_POSIX_H_ERRNO ) + + + +#if defined( MBG_TGT_CVI ) + +static ERRNO_CNV_ENTRY cvi_rs232_error_table[] = +{ + // { kRS_UnknownSysError, }, // Unknown system error. + // { kRS_InvalidPortNum, }, // In valid port number. + // { kRS_PortNotOpen, }, // Port is not open. + // { kRS_UnknownIOError, }, // Unknown I/O error. + // { kRS_InternalError, }, // Unexpected internal error. + // { kRS_NoPortFound, }, // No serial port found. + // { kRS_CanNotOpenPort, }, // Cannot open port. + // { kRS_NullPointerPassed, }, // A NULL pointer was passed when a non-NULL pointer was expected. + // { kRS_OutOfMemory, }, // Out of memory. + // { kRS_OutOfSystemResources, }, // Unable to allocate system resources. + // { kRS_InvalidParameter, }, // Invalid parameter. + // { kRS_InvalidBaudRate, }, // Invalid baud rate. + // { kRS_InvalidParity, }, // Invalid parity. + // { kRS_InvalidDataBits, }, // Invalid number of data bits. + // { kRS_InvalidStopBits, }, // Invalid number of stop bits. + // { kRS_BadFileHandle, }, // Bad file handle. + // { kRS_FileIOError, }, // File I/O error. + // { kRS_InvalidCount, }, // Invalid count; must be greater than or equal to 0. + // { kRS_InvalidIntLevel, }, // Invalid interrupt level. + // { kRS_IOTimeOut, }, // I/O operation timed out. + // { kRS_InvalidBreakTime, }, // Break time must be a positive value. + // { kRS_InvalidInQSize, }, // Requested input queue size must be 0 or greater. + // { kRS_InvalidOutQSize, }, // Requested output queue size must be 0 or greater. + // { kRS_GeneralIOFailure, }, // General I/O error. + // { kRS_InvalidBufferPointer, }, // Buffer parameter is NULL. + // { kRS_VISALibrariesMissing, }, // A necessary run-time library could not be found or loaded. + // { kRS_NoAckReceived, }, // Packet was sent, but no acknowledgment was received. + // { kRS_MaxRetriesBeforeSend, }, // Packet was not sent within retry limit. + // { kRS_MaxRetriesBeforeReceived, }, // Packet was not received within retry limit. + // { kRS_UnexpectedEOT, }, // End of transmission character encountered when start of data character expected. + // { kRS_CanNotReadPackNum, }, // Unable to read packet number. + // { kRS_InconsistentPackNum, }, // Inconsistent packet number. + // { kRS_CanNotReadPackData, }, // Unable to read packet data. + // { kRS_CanNotReadCheckSum, }, // Unable to read checksum. + // { kRS_CheckSumError, }, // Checksum received did not match computed checksum. + // { kRS_PackSizeGTInQ, }, // Packet size exceeds input queue size. + // { kRS_OpenFileError, }, // Error opening file. + // { kRS_ReadFileError, }, // Error reading file. + // { kRS_NoInitNegAck, }, // Did not receive initial negative acknowledgment character. + // { kRS_NoAckAfterEOT, }, // Did not receive acknowledgment after end of transmission character was sent. + // { kRS_WriteFileError, }, // Error writing to file. + // { kRS_NoSOHorEOT, }, // Did not receive either a start of data or end of transmission character when expected. + // { kRS_TransferCancelled, }, // Transfer was canceled because CAN ASCII character was received. + // { kRS_InvalidStartDelay, }, // Invalid start delay. + // { kRS_InvalidMaxTries, }, // Invalid maximum number of retries. + // { kRS_InvalidWaitPeriod, }, // Invalid wait period. + // { kRS_InvalidPacketSize, }, // Invalid packet size. + // { kRS_CanNotReadCRC, }, // Unable to read Cyclical Redundancy Check. + // { kRS_CRCError, }, // Cyclical Redundancy Check error. + { 0, 0 } // end-of-table identifier + +}; // cvi_rs232_error_table + +#endif // defined( MBG_TGT_CVI ) + + + +#if defined( MBG_TGT_WIN32 ) + +#if defined( MBG_TGT_KERNEL ) + +/** + * @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 + * and facility codes, similar to the message IDs used with text resources. + * The status codes and associated message texts are defined + * in the ntstatus.h file shipped with the various Windows DDKs. + * + * Please note that WIN32 user space API function return a different + * set of error codes on failure. See ::win32_sys_err_table. + * + * @see ::mbg_ioctl_to_ntstatus_table + * @see ::win32_kernel_status_table + * @see ::win32_sys_err_table + * @see ::win32_wsa_err_table + * @see @ref MBG_ERROR_CODES + */ +static ERRNO_CNV_ENTRY win32_kernel_status_table[] = +{ + { STATUS_INVALID_PARAMETER, MBG_ERR_INV_PARM, }, // 0xC000000DL, An invalid parameter was passed to a service or function. + { STATUS_INVALID_DEVICE_REQUEST, MBG_ERR_INV_DEV_REQUEST }, // 0xC0000010L, The specified request is not a valid operation for the target device. + { STATUS_DEVICE_BUSY, MBG_ERR_IRQ_UNSAFE }, // 0x80000011L, The device is currently busy. + { STATUS_NO_MEMORY, MBG_ERR_NO_MEM }, // 0xC0000017L, Not enough memory available to complete the specified operation. + { STATUS_NO_DATA_DETECTED, MBG_ERR_NOT_SUPP_BY_DEV }, // 0x80000022L, (normally used with tape access, but mis-used here) + { STATUS_ACCESS_DENIED, MBG_ERR_PERM }, // 0xC0000022L, A process has requested access to an object, but has not been granted those access rights. + { STATUS_IO_DEVICE_ERROR, MBG_ERR_IO }, // 0xC0000185L, The I/O device reported an I/O error. + + { STATUS_BUFFER_TOO_SMALL, MBG_ERR_BUFFER_TOO_SMALL }, // 0xC0000023L, The buffer is too small to contain the entry. No information has been written to the buffer. + // { STATUS_CANCELLED, }, // 0xC0000120L, The I/O request was canceled. + // { STATUS_DELETE_PENDING, }, // 0xC0000056L, A non close operation has been requested of a file object with a delete pending. + // { STATUS_DEVICE_CONFIGURATION_ERROR, }, // 0xC0000182L, The I/O device is configured incorrectly or the configuration parameters to the driver are incorrect. + { STATUS_DEVICE_NOT_READY, MBG_ERR_NOT_READY }, // 0xC00000A3L, The device (drive) is not ready for use. + // { STATUS_INSUFFICIENT_RESOURCES, }, // 0xC000009AL, Insufficient system resources exist to complete the API. + // { STATUS_MORE_PROCESSING_REQUIRED, }, // 0xC0000016L, The specified IRP cannot be disposed of because the I/O operation is not complete. + // { STATUS_NOT_IMPLEMENTED, }, // 0xC0000002L, The requested operation is not implemented. + // { STATUS_NOT_SUPPORTED, }, // 0xC00000BBL, The network request is not supported. + // { STATUS_NO_SUCH_DEVICE, }, // 0xC000000EL, A device which does not exist was specified. + // { STATUS_OBJECT_NAME_NOT_FOUND, }, // 0xC0000034L, Object Name not found. + // { STATUS_PENDING, }, // 0x00000103L, The operation that was requested is pending completion. + { STATUS_TIMEOUT, MBG_ERR_TIMEOUT }, // 0x00000102L, STATUS_TIMEOUT + // { STATUS_UNSUCCESSFUL, }, // 0xC0000001L, The requested operation was unsuccessful. + { 0, 0 } // end-of-table identifier + +}; // win32_kernel_status_table + + + +#if !_USE_WIN32_PRIVATE_STATUS_CODES + +/** + * @brief Windows IOCTL error conversion table. + * + * The IOCTL handler of a Meinberg kernel driver actually calls + * some Meinberg mbglib functions to access a device, and those + * functions normally return one of the @ref MBG_RETURN_CODES. + * + * However, when the Windows kernel calls the driver's IOCTL handler + * it expects an NTSTATUS code to be returned, so this table can be + * used in an IOCTL handler to map a Meinberg return code to a + * predefined NTSTATUS code that can be returned. + * + * To make things worse, Windows then remaps the NTSTATUS code to one + * of the WIN32 error codes when it passes the IOCTL results up to the + * user space function that submitted the IOCTL request. + * + * The user space function can then convert the returned code back + * to one of the @ref MBG_RETURN_CODES. + * + * For the mapping of NTSTATUS codes to WIN32 error codes + * done by Windows when it passes an IOCTL return code from kernel + * space to user space, see: + * https://support.microsoft.com/en-us/help/113996/info-mapping-nt-status-error-codes-to-win32-error-codes + * + * So care should be taken that the table entries here are defined + * such that in spite of the mnumerous conversions the same error code + * that was returned by a driver function is finally returned by the + * Meinberg user space API call. For example: + * + * - Driver function returns ::MBG_ERR_INV_PARM error. + * + * - Table ::mbg_ioctl_to_ntstatus_table is used to convert this to + * STATUS_INVALID_PARAMETER, which is returned by the IOCTL handler + * in kernel space. + * + * - Windows converts this to ERROR_INVALID_PARAMETER when it passes + * the error code up to user space. + * + * - 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)). + * 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. + * This had to be tested, though, and could be used to pass Meinberg error + * codes directly up to user space, without the need for a multiple conversion. + * However, there's no guarantee that this always works, and would still + * work in future Windows versions. + * + * @see ::win32_kernel_status_table + * @see ::win32_sys_err_table + * @see ::win32_wsa_err_table + * @see @ref MBG_ERROR_CODES + */ +static ERRNO_CNV_ENTRY mbg_ioctl_to_ntstatus_table[] = +{ + { MBG_ERR_INV_PARM, STATUS_INVALID_PARAMETER }, // ERROR_INVALID_PARAMETER + { MBG_ERR_INV_DEV_REQUEST, STATUS_INVALID_DEVICE_REQUEST }, // ERROR_BAD_COMMAND + { MBG_ERR_IRQ_UNSAFE, STATUS_DEVICE_BUSY }, // ERROR_BUSY + { MBG_ERR_NO_MEM, STATUS_NO_MEMORY }, // ERROR_NOT_ENOUGH_MEMORY + { MBG_ERR_NOT_SUPP_BY_DEV, STATUS_NO_DATA_DETECTED }, // ERROR_NO_DATA_DETECTED (mis-used here) + { MBG_ERR_PERM, STATUS_ACCESS_DENIED }, // ERROR_ACCESS_DENIED + { MBG_ERR_IO, STATUS_IO_DEVICE_ERROR }, // ERROR_IO_DEVICE + { 0, 0 } // end-of-table identifier + +}; // mbg_ioctl_to_ntstatus_table + +#endif // !_USE_WIN32_PRIVATE_STATUS_CODES + + +#else // Windows user space + +/** + * @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 + * most cases to retrieve an associated error code, which is + * a positive integer number. + * + * Existing error codes and associated message texts + * are defined in the WinError.h file shipped with the + * various SDKs and IDEs. + * + * Please note that Windows socket functions return a different + * set of error codes on failure, and WSAGetLastError() has to + * be called to retrieve the associated error code. + * See ::win32_wsa_err_table. + * + * @see ::win32_wsa_err_table + * @see ::mbg_ioctl_to_ntstatus_table + * @see ::win32_kernel_status_table + * @see @ref MBG_ERROR_CODES + */ +static ERRNO_CNV_ENTRY win32_sys_err_table[] = +{ + // Mappings for some Windows error codes defined in WinError.h + { 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. + { ERROR_NOT_ENOUGH_MEMORY, MBG_ERR_NO_MEM }, // 8L: Not enough storage is available to process this command. + { ERROR_OUTOFMEMORY, MBG_ERR_NO_MEM }, // 14L: Not enough storage is available to complete this operation. + // { ERROR_WRITE_PROTECT, }, // 19L: The media is write protected. + // { ERROR_BAD_UNIT, }, // 20L: The system cannot find the device specified. + { ERROR_NOT_READY, MBG_ERR_NOT_READY }, // 21L: The device is not ready. + { ERROR_WRITE_FAULT, MBG_ERR_IO }, // 29L: The system cannot write to the specified device. + { ERROR_READ_FAULT, MBG_ERR_IO }, // 30L: The system cannot read from the specified device. + { ERROR_GEN_FAILURE, MBG_ERR_UNSPEC }, // 31L: A device attached to the system is not functioning. + // { ERROR_SHARING_VIOLATION, }, // 32L: The process cannot access the file because it is being used by another process. + // { ERROR_LOCK_VIOLATION, }, // 33L: The process cannot access the file because another process has locked a portion of the file. + // { ERROR_NOT_SUPPORTED, }, // 50L: The request is not supported. + // { ERROR_DUP_NAME, }, // 52L: A duplicate name exists on the network. + // { ERROR_BAD_DEV_TYPE, }, // 66L: The network resource type is not correct. + { ERROR_INVALID_PARAMETER, MBG_ERR_INV_PARM }, // 87L: The parameter is incorrect. + { ERROR_BUFFER_OVERFLOW, MBG_ERR_OVERFLOW }, // 111L: The file name is too long. + { ERROR_INSUFFICIENT_BUFFER, MBG_ERR_BUFFER_TOO_SMALL }, // 122L: The data area passed to a system call is too small. + { ERROR_BUSY, MBG_ERR_BUSY }, // 170L: The requested resource is in use. + // { ERROR_NOACCESS, }, // 998L: Invalid access to memory location. + { ERROR_NO_DATA_DETECTED, MBG_ERR_NOT_SUPP_BY_DEV }, // 1104L: No more data is on the tape. (mis-used here) + { ERROR_IO_DEVICE, MBG_ERR_IO }, // 1117L: The request could not be performed because of an I/O device error. + { ERROR_PRIVILEGE_NOT_HELD, MBG_ERR_PERM }, // 1314L: A required privilege is not held by the client. + { 0, 0 } // end-of-table identifier + +}; // win32_sys_err_table + + + +/** + * @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 + * most cases to retrieve an associated error code, which is + * a positive integer number. + * + * Existing error codes and associated message texts are + * defined in the Winsock2.h file shipped with the various + * SDKs and IDEs. + * + * Please note that the standard WIN32 API functions return a + * different set of error codes on failure, and GetLastError() + * has to be called to retrieve the associated error code. + * See ::win32_err_table. + * + * @see ::win32_sys_err_table + * @see ::mbg_ioctl_to_ntstatus_table + * @see ::win32_kernel_status_table + * @see @ref MBG_ERROR_CODES + */ +static ERRNO_CNV_ENTRY win32_wsa_err_table[] = +{ + { WSAEINTR, MBG_ERR_INTR }, // 10004L A blocking operation was interrupted by a call to WSACancelBlockingCall. + // { WSAEBADF // 10009L The file handle supplied is not valid. + // { WSAEACCES // 10013L An attempt was made to access a socket in a way forbidden by its access permissions. + { WSAEFAULT, MBG_ERR_INV_PARM }, // 10014L The system detected an invalid pointer address in attempting to use a pointer argument in a call. + { WSAEINVAL, MBG_ERR_INV_PARM }, // 10022L An invalid argument was supplied. + // { WSAEMFILE // 10024L Too many open sockets. + { WSAEWOULDBLOCK, MBG_ERR_AGAIN }, // 10035L A non-blocking socket operation could not be completed immediately. + // { WSAEINPROGRESS // 10036L A blocking operation is currently executing. + // { WSAEALREADY // 10037L An operation was attempted on a non-blocking socket that already had an operation in progress. + { WSAENOTSOCK, MBG_ERR_NOT_A_SOCKET }, // 10038L An operation was attempted on something that is not a socket. + // { WSAEDESTADDRREQ // 10039L A required address was omitted from an operation on a socket. + // { WSAEMSGSIZE // 10040L A message sent on a datagram socket was larger than the internal message buffer or some other network limit, or the buffer used to receive a datagram into was smaller than the datagram itself. + // { WSAEPROTOTYPE // 10041L A protocol was specified in the socket function call that does not support the semantics of the socket type requested. + // { WSAENOPROTOOPT // 10042L An unknown, invalid, or unsupported option or level was specified in a getsockopt or setsockopt call. + // { WSAEPROTONOSUPPORT // 10043L The requested protocol has not been configured into the system, or no implementation for it exists. + // { WSAESOCKTNOSUPPORT // 10044L The support for the specified socket type does not exist in this address family. + // { WSAEOPNOTSUPP // 10045L The attempted operation is not supported for the type of object referenced. + // { WSAEPFNOSUPPORT // 10046L The protocol family has not been configured into the system or no implementation for it exists. + // { WSAEAFNOSUPPORT // 10047L An address incompatible with the requested protocol was used. + // { WSAEADDRINUSE // 10048L Only one usage of each socket address (protocol/network address/port) is normally permitted. + // { WSAEADDRNOTAVAIL // 10049L The requested address is not valid in its context. + // { WSAENETDOWN // 10050L A socket operation encountered a dead network. + // { WSAENETUNREACH // 10051L A socket operation was attempted to an unreachable network. + // { WSAENETRESET // 10052L The connection has been broken due to keep-alive activity detecting a failure while the operation was in progress. + // { WSAECONNABORTED // 10053L An established connection was aborted by the software in your host machine. + { WSAECONNRESET, MBG_ERR_CONN_RESET }, // 10054L An existing connection was forcibly closed by the remote host. + // { WSAENOBUFS // 10055L An operation on a socket could not be performed because the system lacked sufficient buffer space or because a queue was full. + // { WSAEISCONN // 10056L A connect request was made on an already connected socket. + // { WSAENOTCONN // 10057L A request to send or receive data was disallowed because the socket is not connected and (when sending on a datagram socket using a sendto call) no address was supplied. + // { WSAESHUTDOWN // 10058L A request to send or receive data was disallowed because the socket had already been shut down in that direction with a previous shutdown call. + // { WSAETOOMANYREFS // 10059L Too many references to some kernel object. + // { WSAETIMEDOUT // 10060L A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond. + // { WSAECONNREFUSED // 10061L No connection could be made because the target machine actively refused it. + // { WSAELOOP // 10062L Cannot translate name. + // { WSAENAMETOOLONG // 10063L Name component or name was too long. + // { WSAEHOSTDOWN // 10064L A socket operation failed because the destination host was down. + // { WSAEHOSTUNREACH // 10065L A socket operation was attempted to an unreachable host. + // { WSAENOTEMPTY // 10066L Cannot remove a directory that is not empty. + // { WSAEPROCLIM // 10067L A Windows Sockets implementation may have a limit on the number of applications that may use it simultaneously. + // { WSAEUSERS // 10068L Ran out of quota. + // { WSAEDQUOT // 10069L Ran out of disk quota. + // { WSAESTALE // 10070L File handle reference is no longer available. + // { WSAEREMOTE // 10071L Item is not available locally. + // { WSASYSNOTREADY // 10091L WSAStartup cannot function at this time because the underlying system it uses to provide network services is currently unavailable. + // { WSAVERNOTSUPPORTED // 10092L The Windows Sockets version requested is not supported. + { WSANOTINITIALISED, MBG_ERR_SOCK_INIT }, // 10093L Either the application has not called WSAStartup, or WSAStartup failed. + // { WSAEDISCON // 10101L Returned by WSARecv or WSARecvFrom to indicate the remote party has initiated a graceful shutdown sequence. + // { WSAENOMORE // 10102L No more results can be returned by WSALookupServiceNext. + // { WSAECANCELLED // 10103L A call to WSALookupServiceEnd was made while this call was still processing. The call has been canceled. + // { WSAEINVALIDPROCTABLE // 10104L The procedure call table is invalid. + // { WSAEINVALIDPROVIDER // 10105L The requested service provider is invalid. + // { WSAEPROVIDERFAILEDINIT // 10106L The requested service provider could not be loaded or initialized. + // { WSASYSCALLFAILURE // 10107L A system call that should never fail has failed. + // { WSASERVICE_NOT_FOUND // 10108L No such service is known. The service cannot be found in the specified name space. + // { WSATYPE_NOT_FOUND // 10109L The specified class was not found. + // { WSA_E_NO_MORE // 10110L No more results can be returned by WSALookupServiceNext. + // { WSA_E_CANCELLED // 10111L A call to WSALookupServiceEnd was made while this call was still processing. The call has been canceled. + // { WSAEREFUSED // 10112L A database query failed because it was actively refused. + { WSAHOST_NOT_FOUND, MBG_ERR_HOST_NOT_FOUND }, // 11001L No such host is known. + // { WSATRY_AGAIN // 11002L This is usually a temporary error during hostname resolution and means that the local server did not receive a response from an authoritative server. + // { WSANO_RECOVERY // 11003L A non-recoverable error occurred during a database lookup. + // { WSANO_DATA // 11004L The requested name is valid, but no data of the requested type was found. + { 0, 0 } // end-of-table identifier + +}; // win32_wsa_err_table + +#endif // Windows user space + +#endif // defined( MBG_TGT_WIN32 ) + + + +static /*HDR*/ +/** + * @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] dflt_val The code to be returned if no table entry was found. + * + * @return @ref MBG_ERROR_CODES associated with the original error code, + * or @p dflt_val if original code not found in table. + */ +int lookup_tbl_errno( int srch_errno, const ERRNO_CNV_ENTRY tbl[], int dflt_val ) +{ + const ERRNO_CNV_ENTRY *p; + + for ( p = tbl; p->srch_errno || p->mapped_errno; p++ ) + if ( p->srch_errno == srch_errno ) + return p->mapped_errno; + + return dflt_val; + +} // lookup_tbl_errno + + +#if !_USE_WIN32_PRIVATE_STATUS_CODES + +/*HDR*/ +/** + * @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 + */ +int mbg_errno_to_os( int err_no ) +{ + #if defined( MBG_TGT_KERNEL ) + + #if defined( MBG_TGT_WIN32 ) + + if ( err_no == MBG_SUCCESS ) + return STATUS_SUCCESS; + + return lookup_tbl_errno( err_no, mbg_ioctl_to_ntstatus_table, STATUS_UNSUCCESSFUL ); + + #elif defined( MBG_TGT_LINUX ) + + #elif defined( MBG_TGT_FREEBSD ) + + #elif defined( MBG_TGT_NETBSD ) + + #else + + #error this needs to be implemented + + #endif + + #else // user space + + #if 0 + #if defined( MBG_TGT_WIN32 ) // FIXME TODO + // Windows uses specially encoded numbers + return ( -err_no | 0xE0000000L ); + + #elif defined( MBG_TGT_BSD ) + + return -err_no; + + #else + + return err_no; + + #endif + #endif // 0 + + #endif + + return err_no; + +} // mbg_errno_to_os + +#endif // _USE_WIN32_PRIVATE_STATUS_CODES + + + +/*HDR*/ +/** + * @brief Return an error string associated with 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 + */ +const char *mbg_strerror( int mbg_errno ) +{ + static const MBG_CODE_NAME_TABLE_ENTRY tbl[] = MBG_ERR_STR_TABLE_ENG; + + const MBG_CODE_NAME_TABLE_ENTRY *p; + + for ( p = tbl; p->name; p++ ) + { + if ( mbg_errno == p->code ) + return p->name; + } + + return "Unknown error"; + +} // mbg_strerror + + + +#if !defined( _MBG_TGT_OMIT_ERR_MSG ) + +/*HDR*/ +/** + * @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 + * + * @return true if rc represented an error code, and a message has been printed, else false + */ +bool mbg_cond_err_msg( int rc, const char *what ) +{ + return mbg_cond_err_msg_info( rc, what, NULL ); + +} // mbg_cond_err_msg + + + +/*HDR*/ +/** + * @brief Check if a value is an 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 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 info2 is NULL, or the error code is not ::MBG_ERR_NOT_SUPP_BY_DEV then the standard + * error message is printed anyway. + * + * @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). + * + * @return true if rc represented an error code, and a message has been printed, else false + */ +bool mbg_cond_err_msg_info( int rc, const char *what, const char *info ) +{ + if ( mbg_rc_is_error( rc ) ) + { + if ( info && ( rc == MBG_ERR_NOT_SUPP_BY_DEV ) ) + fprintf( stderr, "This device does not %s.\n", info ); + else + fprintf( stderr, "** %s failed: %s (rc: %i)\n", what, mbg_strerror( rc ), rc ); + + return true; + } + + return false; + +} // mbg_cond_err_msg_info + +#endif // !defined( _MBG_TGT_OMIT_ERR_MSG ) + + + +#if defined( MBG_TGT_CVI ) + +/*HDR*/ +/** + * @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 + * + * @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 ) +{ + #if DEBUG + if ( info ) + fprintf( stderr, "%s, CVI RS-232 rc: %i\n", info, cvi_rc ); + #else + (void) info; // avoid compiler warning + #endif + + return ( cvi_rc < 0 ) ? lookup_tbl_errno( cvi_rc, cvi_rs232_error_table, MBG_ERR_UNKNOWN ) : MBG_SUCCESS; + +} // mbg_cvi_rs232_error_to_mbg + +#endif + + + +#if defined( MBG_TGT_WIN32 ) + +#if defined( MBG_TGT_KERNEL ) + +/*HDR*/ +/** + * @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 + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_win32_ntstatus_to_mbg( NTSTATUS st, const char *info ) +{ + #if DEBUG + if ( info ) + _mbgddmsg_2( DEBUG, MBG_LOG_INFO, "%s, ntstatus: 0x%08lX\n", info, (long) st ); + #else + (void) info; // avoid compiler warning + #endif + + return lookup_tbl_errno( st, win32_kernel_status_table, MBG_ERR_UNKNOWN ); + +} // mbg_win32_ntstatus_to_mbg + + +#else // Windows user space + +/*HDR*/ +/** + * @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. + * + * @return One of the @ref MBG_RETURN_CODES + */ +int mbg_win32_sys_err_to_mbg( DWORD win32_sys_rc, const char *info ) +{ + int rc = MBG_SUCCESS; + + if ( win32_sys_rc == ERROR_SUCCESS ) + goto out; + + if ( win32_sys_rc & STATUS_CUSTOM_FLAG_MASK ) + { + // This is a user-defined error code or message ID, e.g. returned by an IOCTL + // call. The lower 16 bits contain the (positive) error code while the upper + // 16 bits contain flags as specified for the Windows API in winerror.h. + // So we assume the error code is just the absolute value of one of the + // @ref MBG_ERROR_CODES, and we return the negated value. + rc = - (int) ( win32_sys_rc & 0xFFFF ); + goto out; + } + +#if 0 // TODO FIXME + rc = (int) win32_sys_rc; + + 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 + goto out; + } +#endif + + rc = lookup_tbl_errno( win32_sys_rc, win32_sys_err_table, MBG_ERR_UNKNOWN ); + +out: + #if DEBUG + if ( info ) + fprintf( stderr, "%s, win32_sys_rc: 0x%08lX (%i) --> %i (%s)\n", + info, (long) win32_sys_rc, (int) win32_sys_rc, + rc, mbg_strerror( rc ) ); + #else + (void) info; // avoid compiler warning + #endif + + return rc; + +} // mbg_win32_sys_err_to_mbg + + + +/*HDR*/ +/** + * @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 + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_win32_wsa_err_to_mbg( int wsa_err, const char *info ) +{ + #if DEBUG + if ( info ) + fprintf( stderr, "%s, wsa_err: %i\n", info, wsa_err ); + #else + (void) info; // avoid compiler warning + #endif + + // The WSA error code is only retrieved after an error has occurred, so + // we don't need care for the success case here. + return lookup_tbl_errno( wsa_err, win32_wsa_err_table, MBG_ERR_UNKNOWN ); + +} // mbg_win32_wsa_err_to_mbg + +#endif // Windows user space + +#endif // defined( MBG_TGT_WIN32 ) + + + + +#if defined( _MBG_TGT_HAS_POSIX_ERRNO ) + +/*HDR*/ +/** + * @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 + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_posix_errno_to_mbg( int posix_errno, const char *info ) +{ + #if DEBUG && !defined( MBG_TGT_KERNEL ) + if ( info ) + fprintf( stderr, "%s: %s (errno: %i)\n", info, + strerror( posix_errno ), posix_errno ); + #else + (void) info; // avoid compiler warning + #endif + + return lookup_tbl_errno( posix_errno, posix_errno_table, MBG_ERR_UNKNOWN ); + +} // mbg_posix_errno_to_mbg + +#endif // defined( _MBG_TGT_HAS_POSIX_ERRNO ) + + + +#if defined( _MBG_TGT_HAS_POSIX_H_ERRNO ) + +/*HDR*/ +/** + * @brief Translate a POSIX h_errno error code to one of the @ref MBG_ERROR_CODES + * + * This function is specific to translate error codes returned by + * gethostbyname() and gethostbyaddr(). In case of error these functions + * don't set errno but h_errno to a specific value. + * + * The functions gethostbyname() and gethostbyaddr() are obsolete, + * and getaddressinfo() should be used preferably. + * + * @param[in] posix_h_errno An error code as usually defined in netdb.h + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_posix_h_errno_to_mbg( int posix_h_errno, const char *info ) +{ + #if DEBUG && !defined( MBG_TGT_KERNEL ) + if ( info ) + fprintf( stderr, "%s: %s (h_errno: %i)\n", info, + hstrerror( posix_h_errno ), posix_h_errno ); + #else + (void) info; // avoid compiler warning + #endif + + return lookup_tbl_errno( posix_h_errno, posix_h_errno_table, MBG_ERR_UNKNOWN ); + +} // mbg_posix_h_errno_to_mbg + +#endif // defined( _MBG_TGT_HAS_POSIX_H_ERRNO ) + + + +#if !defined( _MBG_TGT_OMIT_LAST_ERROR ) + +/*HDR*/ +/** + * @brief Get and translate last error after non-socket function call + * + * Retrieve the "last error" code after a non-socket function has been called + * and translate to one of the @ref MBG_ERROR_CODES. + * + * On POSIX systems the "last error" code is always stored in errno, but + * e.g. under Windows the "last error" code after a socket function + * has to be retrieved by calling WSAGetLastError(), whereas the "last error" + * code from non-socket POSIX-like functions has to be retrieved + * by calling GetLastError(). + * + * @param[in] info An optional informational text string, or NULL + * + * @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 + // ("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 + // WSAGetLastError(). + return mbg_win32_sys_err_to_mbg( GetLastError(), info ); + + #elif defined( MBG_TGT_POSIX ) + + // On POSIX systems the "last error" code is always stored in errno. + return mbg_posix_errno_to_mbg( errno, info ); + + #else + + // ### TODO #error This function is not supported for this target. + return mbg_posix_errno_to_mbg( errno, info ); + + #endif + +} // mbg_get_last_error + + + +#if !defined( _MBG_TGT_OMIT_SOCKET_ERRORS ) + +/*HDR*/ +/** + * @brief Get and translate last error after socket function call + * + * Retrieve the "last error" code after a socket function has been called + * and translate to one of the @ref MBG_ERROR_CODES. + * + * On POSIX systems the "last error" code is always stored in errno, but + * e.g. under Windows the "last error" code after a socket function + * has to be retrieved by calling WSAGetLastError, whereas the "last error" + * code from non-socket POSIX-like functions is stored in errno as usual. + * + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_get_last_socket_error( const char *info ) +{ + #if defined( MBG_TGT_CVI ) + + #warning This needs to be implemented for CVI + return MBG_ERR_UNKNOWN; + + #elif defined( MBG_TGT_WIN32 ) + + #if !defined( MBG_TGT_KERNEL ) + // Under 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 + // to be retrieved by calling GetLastError(). + return mbg_win32_wsa_err_to_mbg( WSAGetLastError(), info ); + #else + return MBG_ERR_GENERIC; // TODO should we only work with NTSTATUS codes in kernel mode? + #endif + + #elif defined( MBG_TGT_POSIX ) + + // On POSIX systems the "last error" code is always stored in errno. + return mbg_posix_errno_to_mbg( errno, info ); + + #else + + #error This function is not supported for this target. + + #endif + +} // mbg_get_last_socket_error + + + +/*HDR*/ +/** + * @brief Retrieve and convert last error after gethostbyname() + * + * This function is specific to retrieve and translate error codes + * returned by gethostbyname() and gethostbyaddr(). In case of error + * these functions don't set errno but h_errno on POSIX systems, but + * under Windows the error code can be retrieved by WSAGetLastError() + * as usual. + * + * The functions gethostbyname() and gethostbyaddr() are obsolete, + * and getaddressinfo() should be used preferably. + * + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_get_gethostbyname_error( const char *info ) +{ + #if defined( MBG_TGT_CVI ) + + #warning This needs to be implemented for CVI + return MBG_ERR_UNKNOWN; + + #elif defined( MBG_TGT_WIN32 ) + + #if !defined( MBG_TGT_KERNEL ) + return mbg_win32_wsa_err_to_mbg( WSAGetLastError(), info ); + #else + return MBG_ERR_GENERIC; + #endif + + #elif defined( MBG_TGT_POSIX ) + + return mbg_posix_h_errno_to_mbg( h_errno, info ); + + #else + + #error This function is not supported for this target. + + #endif + +} // mbg_get_gethostbyname_error + +#endif // !defined( _MBG_TGT_OMIT_SOCKET_ERRORS ) + +#endif // !defined( _MBG_TGT_OMIT_LAST_ERROR ) + + + +#if 0 // not yet finished +// error handler for getaddressinfo() +/* + * Handle specific error returned by getaddressinfo() + */ + /*HDR*/ +int mbg_gai_error( int rc, const char *info ) +{ + #if defined( MBG_TGT_CVI ) + + #warning This needs to be implemented for CVI + return MBG_ERR_UNKNOWN; + + #elif defined( MBG_TGT_WIN32 ) + + return mbg_win32_wsa_err_to_mbg( WSAGetLastError(), info ); + + #elif defined( MBG_TGT_POSIX ) + + return mbg_posix_h_errno_to_mbg( h_errno, info ); + + #else + + return MBG_ERR_UNKNOWN; + + #endif + +} // mbg_get_gai_error + +#endif + + + +#if defined( USE_MBG_ZLIB ) + +/*HDR*/ +/** + * @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. + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_zlib_error_to_mbg( int zlib_error, const char *info, const char *msg ) +{ + #if DEBUG + if ( info && msg ) + fprintf( stderr, "%s: %s (zlib_error: %d)\n", info, + msg, zlib_error ); + #endif + + switch ( zlib_error ) + { + case Z_ERRNO: return mbg_get_last_error( info ); + case Z_MEM_ERROR: return MBG_ERR_NO_MEM; + /* + * All other zlib error codes are not specified any further. + * So, it's hard to guess what they mean and we return MBG_UNSPEC so far. + */ + default: + return MBG_ERR_UNKNOWN; + } + +} // mbg_zlib_error_to_mbg + +#endif // defined( USE_MBG_ZLIB ) + + diff --git a/mbglib/common/mbgerror.h b/mbglib/common/mbgerror.h index f15878d..d839fb2 100644 --- a/mbglib/common/mbgerror.h +++ b/mbglib/common/mbgerror.h @@ -1,8 +1,7 @@ /************************************************************************** * - * $Id: mbgerror.h 1.6 2012/10/02 18:42:26Z martin REL_M $ - * $Name: $ + * $Id: mbgerror.h 1.18 2018/11/22 11:25:56Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -12,6 +11,55 @@ * * ----------------------------------------------------------------------- * $Log: mbgerror.h $ + * Revision 1.18 2018/11/22 11:25:56Z martin + * New error code MBG_ERR_STR_SUBSTR merged from 1.15.1.x branch. + * Refactored surrogate definitions. + * Updated function prototypes. + * Revision 1.17 2018/09/21 09:49:57 martin + * Renamed MBG_ERR_FIFO to MBG_ERR_NO_DATA. + * Added strings for MBG_ERR_NO_DRIVER and MBG_ERR_DRV_VERSION. + * New code MBG_ERR_BUFFER_TOO_SMALL. + * MBG_ERR_OUTDATED error code added by philipp. + * Added some Windows stuff. + * Updated function prototypes. + * Revision 1.16 2018/06/25 14:26:38Z martin + * Some new error codes were introduced. + * New macro mbg_rc_is_success_or_err_perm(). + * New control macro _USE_WIN32_PRIVATE_STATUS_CODES. + * Split table initializers for error strings into two + * separate initializers to avoid overhead on target + * systems which don't support extended functions. + * Updated comments, string tables, and function prototypes. + * Revision 1.15 2017/07/05 09:27:25 martin + * New error code MBG_ERR_PARM_FMT. + * 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. + * Updated doxygen comments. + * Updated function prototypes. + * Revision 1.14 2017/05/10 15:21:39 martin + * Tiny cleanup. + * Revision 1.13 2017/02/28 15:23:14 gregoire + * error code MBG_ERR_INV_IDX added + * Revision 1.12 2017/01/10 15:54:56 philipp + * Fixed syntax error + * Revision 1.11 2017/01/10 14:26:31 philipp + * Added error MBG_ERR_NOT_CONFIGURED + * Revision 1.10 2016/12/16 12:40:33 thomas-b + * Added MBG_ERR_NO_SPACE + * Revision 1.9 2016/10/31 17:41:55 martin + * New error code MBG_ERR_DATA_FMT. + * Revision 1.8 2016/08/05 12:29:20 martin + * Re-enabled some symbols which have been commented out. + * Added new codes, and initializers for code/string conversion tables. + * Updated doxygen comments. + * Updated function prorotypes. + * Revision 1.7 2014/05/27 13:32:47Z martin + * Defined additional common error codes which can be + * translated from OS specific codes. + * Function prototypes from new module mbgerror.c. + * Comments in doxygen style. * Revision 1.6 2012/10/02 18:42:26Z martin * New codes MBG_ERR_N_POUT_EXCEEDS_SUPP and * MBG_ERR_N_UC_MSTR_EXCEEDS_SUPP. @@ -39,6 +87,7 @@ /* Other headers to be included */ #include <mbg_tgt.h> +#include <words.h> #ifdef _MBGERROR #define _ext @@ -50,115 +99,699 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + +#if defined( MBG_TGT_WIN32 ) + + #if defined( MBG_TGT_KERNEL ) + #define MBG_SYS_RC_SUCCESS STATUS_SUCCESS + #else + #define MBG_SYS_RC_SUCCESS ERROR_SUCCESS + #endif + +#elif defined( MBG_TGT_POSIX ) + + #define MBG_SYS_RC_SUCCESS 0 + +#else + + #define MBG_SYS_RC_SUCCESS 0 + +#endif + + +#if !defined( _USE_WIN32_PRIVATE_STATUS_CODES ) // FIXME + #define _USE_WIN32_PRIVATE_STATUS_CODES 0 +#endif + + +#if defined( MBG_TGT_WIN32 ) + +#define STATUS_SEVERITY_SUCCESS 0x0 +#define STATUS_SEVERITY_INFORMATIONAL 0x1 +#define STATUS_SEVERITY_WARNING 0x2 +#define STATUS_SEVERITY_ERROR 0x3 + +#define STATUS_SEVERITY_SHIFT_BITS 30 +#define STATUS_SEVERITY_SHIFT_MASK 0x03 + +#define STATUS_SEVERITY_SUCCESS_MASK ( STATUS_SEVERITY_SUCCESS << STATUS_SEVERITY_SHIFT_BITS ) +#define STATUS_SEVERITY_INFORMATIONAL_MASK ( STATUS_SEVERITY_INFORMATIONAL << STATUS_SEVERITY_SHIFT_BITS ) +#define STATUS_SEVERITY_WARNING_MASK ( STATUS_SEVERITY_WARNING << STATUS_SEVERITY_SHIFT_BITS ) +#define STATUS_SEVERITY_ERROR_MASK ( STATUS_SEVERITY_ERROR << STATUS_SEVERITY_SHIFT_BITS ) + +#define _get_win_msg_severity( _st ) ( ( (_st) >> STATUS_SEVERITY_SHIFT_BITS ) & STATUS_SEVERITY_SHIFT_MASK ) + + + +#define STATUS_CUSTOM_FLAG 0x1 + +#define STATUS_CUSTOM_FLAG_SHIFT_BITS 29 +#define STATUS_CUSTOM_FLAG_SHIFT_MASK 0x01 + +#define STATUS_CUSTOM_FLAG_MASK ( STATUS_CUSTOM_FLAG << STATUS_CUSTOM_FLAG_SHIFT_BITS ) + +#define _get_win_msg_custom_flag( _st ) ( ( (_st) >> STATUS_CUSTOM_FLAG_SHIFT_BITS ) & STATUS_CUSTOM_FLAG_SHIFT_MASK ) + +#define _win_msg_is_custom( _st ) ( _get_win_msg_custom_flag( _st ) != 0 ) + + + +#define _mbg_msg_id_inf( num ) ((DWORD) ( STATUS_SEVERITY_INFORMATIONAL_MASK | STATUS_CUSTOM_FLAG_MASK | num ) ) +#define _mbg_msg_id_wrn( num ) ((DWORD) ( STATUS_SEVERITY_WARNING_MASK | STATUS_CUSTOM_FLAG_MASK | num ) ) +#define _mbg_msg_id_err( num ) ((DWORD) ( STATUS_SEVERITY_ERROR_MASK | STATUS_CUSTOM_FLAG_MASK | num ) ) + +#endif // defined( MBG_TGT_WIN32 ) + + + +// Surrogate declarations for target-specific types +// that are used in common function prototypes. +// Without these declarations we'd get compiler errors +// on targets that don't have them. + +#if !defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_KERNEL ) + // Even required in Windows kernel space. + typedef uint32_t DWORD; + #define DWORD DWORD +#endif + +#if !( defined( MBG_TGT_WIN32 ) && defined( MBG_TGT_KERNEL ) ) + // Always required, except in Windows kernel space. + typedef void *NTSTATUS; + #define NTSTATUS NTSTATUS +#endif + + + + /** - @defgroup group_error_codes Error codes - - Error codes used with Meinberg devices and drivers. - The codes will be translated into an OS dependent error code, - when they are returned to the calling function. - - For Windows, these codes are made positive and or'ed with 0xE0000000 afterwards. - - Example: Code -19 (#MBG_ERR_GENERIC) will be converted to 0xE0000013 under Windows. - - @note Attention: - These error codes below must match exactly the corresponding codes that are evaluated in user space. - For Windows, they are located in messages.mc/.h in mbgsvctl.dll - - @{ -*/ - - -#define MBG_SUCCESS PCPS_SUCCESS /**< 0, no error */ - -// The codes below are defined in pcpsdefs.h and returned by the firmware: -#define MBG_ERR_STIME PCPS_ERR_STIME /**< -1, invalid date/time/status passed */ -#define MBG_ERR_CFG PCPS_ERR_CFG /**< -2, invalid parms with a PCPS_CFG_GROUP cmd */ - -// Codes returned by the driver's low level functions: -#define MBG_ERR_GENERIC -19 /**< Generic error */ -#define MBG_ERR_TIMEOUT -20 /**< Timeout accessing the board */ -#define MBG_ERR_FW_ID -21 /**< Invalid firmware ID */ -#define MBG_ERR_NBYTES -22 /**< The number of parameter bytes - passed to the board did not match - the number of bytes expected. */ -#define MBG_ERR_INV_TIME -23 /**< The device's time is not valid */ -#define MBG_ERR_FIFO -24 /**< The device's FIFO is empty, though - it shouldn't be */ -#define MBG_ERR_NOT_READY -25 /**< Board is temporary unable to respond - (during initialization after RESET) */ -#define MBG_ERR_INV_TYPE -26 /**< Board did not recognize data type */ - - -// Codes returned by the driver's high level functions: -#define MBG_ERR_NO_MEM -27 /**< Failed to allocate memory */ -#define MBG_ERR_CLAIM_RSRC -28 /**< Failed to claim port or mem resource */ -#define MBG_ERR_DEV_NOT_SUPP -29 /**< Specified device type not supported by driver */ -#define MBG_ERR_INV_DEV_REQUEST -30 /**< IOCTL call not supported by driver */ -#define MBG_ERR_NOT_SUPP_BY_DEV -31 /**< Cmd or feature not supported by device */ -#define MBG_ERR_USB_ACCESS -32 /**< USB access failed */ -#define MBG_ERR_CYCLIC_TIMEOUT -33 /**< Cyclic event (IRQ, etc.) didn't occur */ -#define MBG_ERR_NOT_SUPP_ON_OS -34 /**< The function is not supported on this operating system */ -#define MBG_ERR_LIB_NOT_COMPATIBLE -35 /**< The installed version of the DLL/shared object is not - compatible with version used to build the application */ -#define MBG_ERR_N_COM_EXCEEDS_SUPP -36 /**< The number of COM ports provided by the device - exceeds the maximum supported by the driver */ -#define MBG_ERR_N_STR_EXCEEDS_SUPP -37 /**< The number of string formats supported by the device - exceeds the maximum supported by the driver */ -#define MBG_ERR_IRQ_UNSAFE -38 /**< The enabled IRQs are unsafe with this firmware/ASIC version */ -#define MBG_ERR_N_POUT_EXCEEDS_SUPP -39 /**< The number of programmable outputs provided by the device - exceeds the maximum supported by the driver */ + * @brief Error 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 + * 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 + * of an error code and have it or'ed with 0xE0000000 afterwards, e.g. + * ::MBG_ERR_GENERIC (-19) will yield Windows code 0xE0000013. + * * See ::_mbg_err_to_os + */ + +// NOTE: Some of these codes have to match codes which are defined in pcpsdefs.h +// 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 + + /** @anchor MBG_ERROR_CODES @{ */ + +// Other codes which have to match codes defined in pcpsdefs.h returned by bus-level devices +#define MBG_ERR_STIME -1 ///< 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 +#define MBG_ERR_GENERIC -19 ///< Generic error. +#define MBG_ERR_TIMEOUT -20 ///< Timeout accessing the device. +#define MBG_ERR_FW_ID -21 ///< Invalid firmware ID. +#define MBG_ERR_NBYTES -22 ///< The number of parameter bytes passed to the device did not + ///< match the number of bytes expected by the device. + +#define MBG_ERR_INV_TIME -23 ///< The device 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_NOT_READY -25 ///< Bus-level device is temp. unable to respond e.g. during init. after RESET. +#define MBG_ERR_INV_TYPE -26 ///< Bus-level device didn't recognize data type. + + +// Codes returned by the high level API functions +#define MBG_ERR_NO_MEM -27 ///< Failed to allocate memory. +#define MBG_ERR_CLAIM_RSRC -28 ///< Failed to claim port or mem resource. +#define MBG_ERR_DEV_NOT_SUPP -29 ///< 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_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_IRQ_UNSAFE -38 ///< Enabled IRQ of bus-level device is unsafe with this firmware/ASIC version. +#define MBG_ERR_N_POUT_EXCEEDS_SUPP -39 ///< Num. prog. outputs of the device exceeds max. supp. by driver. // Legacy codes used with DOS TSRs only: -#define MBG_ERR_INV_INTNO -40 /**< Invalid interrupt number */ -#define MBG_ERR_NO_DRIVER -41 /**< A driver could not be found */ -#define MBG_ERR_DRV_VERSION -42 /**< The driver is too old */ +#define MBG_ERR_INV_INTNO -40 ///< Invalid interrupt number. +#define MBG_ERR_NO_DRIVER -41 ///< No driver could be found. +#define MBG_ERR_DRV_VERSION -42 ///< The driver is too old. + +#define MBG_ERR_COPY_TO_USER -43 ///< Kernel driver failed to copy data from kernel to user space. +#define MBG_ERR_COPY_FROM_USER -44 ///< Kernel driver failed to copy data from use to kernel space. -#define MBG_ERR_COPY_TO_USER -43 /**< kernel driver failed to copy data from kernel to user space */ -#define MBG_ERR_COPY_FROM_USER -44 /**< kernel driver failed to copy data from use to kernel space */ // More codes returned by the driver's high level functions: +#define MBG_ERR_N_UC_MSTR_EXCEEDS_SUPP -45 ///< Num. PTP unicast masters of the device exceeds max. supp. by driver. +#define MBG_ERR_N_GNSS_EXCEEDS_SUPP -46 ///< Num. of GNSS systems supp. by device exceeds max. supp. by driver. +#define MBG_ERR_N_GPIO_EXCEEDS_SUPP -47 ///< Num. of GPIO ports supp. by device exceeds max. supp. by driver. +#define MBG_ERR_N_XMR_EXCEEDS_SUPP -48 ///< Num. of XMR sources supp. by device exceeds max. supp. by driver. -#define MBG_ERR_N_UC_MSTR_EXCEEDS_SUPP -39 /**< The number of PTP unicast masters supported by the device - exceeds the maximum supported by the driver */ -/** @} group_error_codes */ +#define MBG_ERR_UNSPEC -60 ///< Unspecified error. -// Depending on the operating system, the codes above have to be converted before -// they are sent up to user space -#if defined( MBG_TGT_WIN32 ) - #if !defined( STATUS_SUCCESS ) // not in kernel mode - #define STATUS_SUCCESS 0 - #endif +#define MBG_ERR_HDR_CSUM -61 ///< Binary protocol header checksum error. +#define MBG_ERR_DATA_CSUM -62 ///< Binary protocol data checksum error. +#define MBG_ERR_RCVD_NACK -63 ///< Binary protocol received reply msg with a NACK code. +#define MBG_ERR_RCVD_NO_ACK -64 ///< Binary protocol received reply msg without expected ACK code. //### TODO +#define MBG_ERR_CONN_TYPE -65 ///< Binary protocol no valid/supported connection type specified. +#define MBG_ERR_BYTES_WRITTEN -66 ///< Binary protocol failed to write all bytes. +#define MBG_ERR_AUTH -67 ///< Binary protocol failed authentication. + +#define MBG_ERR_SOCK_INIT -68 ///< Socket interface not initialized, or failed to initialize. +#define MBG_ERR_INV_SOCK_FD -69 ///< Invalid socket when tried to open network socket. +#define MBG_ERR_NOT_A_SOCKET -70 ///< Socket descriptor is not a socket. +#define MBG_ERR_NBLOCK_WAIT_SLCT -71 ///< Select timed out when waiting for non-blocking network port to become ready. +#define MBG_ERR_NBLOCK_WAIT_WR_FD -72 ///< Write fd not set after select when waiting for non-blocking network port to become ready. + +#define MBG_ERR_IO -73 ///< Input/output error. +#define MBG_ERR_INV_PARM -74 ///< Invalid parameter. +#define MBG_ERR_NO_DEV -75 ///< No such device, or attempted an inappropriate function. +#define MBG_ERR_NOT_FOUND -76 ///< Specified item not found. + +#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_BUSY -82 ///< Device or resource busy, can't be used +#define MBG_ERR_INV_HANDLE -83 ///< invalid file/device handle specified + +#define MBG_ERR_XBP_CASC_LVL -84 ///< too many XBP cascading levels +#define MBG_ERR_ENCRYPT -85 ///< encryption failed +#define MBG_ERR_DECRYPT -86 ///< decryption failed + +#define MBG_ERR_DISCONN -87 ///< connection closed by remote site / host +#define MBG_ERR_INV_CFG -88 ///< invalid/inconsistent configuration parameters read from device, see also ::MBG_ERR_CFG +#define MBG_ERR_RANGE -89 ///< input parameter was out of range + +#define MBG_ERR_INV_TLV_ANN_BYTES -90 ///< number of announced TLV bytes doesn't match number of transferred bytes +#define MBG_ERR_INV_TLV_SIZE -91 ///< ### TODO +#define MBG_ERR_INV_TLV_UID -92 ///< ### TODO + +#define MBG_ERR_EXIST -93 ///< File exists +#define MBG_ERR_DATA_SIZE -94 ///< the received data size toesn't match the expected data size +#define MBG_ERR_NO_ENTITY -95 ///< no such file or directory +#define MBG_ERR_ALREADY_ALLOC -96 ///< pointer already allocated when trying to allocate memory +#define MBG_ERR_HOST_NOT_FOUND -97 ///< host not found +#define MBG_ERR_CONN_RESET -98 ///< connection reset by peer +#define MBG_ERR_DATA_FMT -99 ///< invalid data format + +#define MBG_ERR_NO_SPACE -100 ///< insufficient disk space left on the device +#define MBG_ERR_NOT_CONFIGURED -101 ///< configuration option is not active/configured +#define MBG_ERR_INV_IDX -102 ///< invalid index value used + +#define MBG_ERR_PARM_FMT -103 ///< parameter string format error +#define MBG_ERR_UNKNOWN -104 ///< Unknown error code from external API. + +#define MBG_ERR_PAM -105 ///< PAM error while authenticating user +#define MBG_ERR_TIMER -106 ///< Timer expired (e.g. stream timeout on USB disconnect) + +#define MBG_ERR_AGAIN -107 ///< Try again (later). For example, a blocking operation + ///< on a non-blocking socket. + +#define MBG_ERR_STR_CHAR -108 ///< Invalid character in string +#define MBG_ERR_STR_LEN -109 ///< Wrong string length +#define MBG_ERR_SN_GCODE_LEN -110 ///< Invalid device group code length +#define MBG_ERR_SN_GCODE_UNKN -111 ///< Unknown device group code +#define MBG_ERR_SN_GCODE_WRONG -112 ///< Wrong device group code in S/N +#define MBG_ERR_SN_LEN -113 ///< Wrong serial number string length +#define MBG_ERR_SN_VRFY -114 ///< Serial number could not be verified + +#define MBG_ERR_RSRC_ITEM -115 ///< Too many resource items +#define MBG_ERR_BUFFER_TOO_SMALL -116 ///< Buffer is too small. + +#define MBG_ERR_OUTDATED -117 + +#define MBG_ERR_STR_SUBSTR -118 ///< Invalid substring in string + + +// 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 +// texts specified in messages.mc/.h from which the resources appended to mbgsvctl.dll +// are generated have to be updated accordingly. + +/** @} anchor MBG_ERROR_CODES */ + +/** @} anchor MBG_RETURN_CODES */ - #define _mbg_err_to_os( _c ) \ - ( ( _c == MBG_SUCCESS ) ? STATUS_SUCCESS : ( abs( _c ) | 0xE0000000 ) ) -#endif -// If no specific conversion has been defined -// then use the original codes. -#if !defined( _mbg_err_to_os ) - #define _mbg_err_to_os( _c ) ( _c ) +/** + * @brief A basic subset of strings associated with @ref MBG_RETURN_CODES + * + * This initializer provides only the strings for basic error codes + * that are supported on all target systems. + * + * See the @ref MBG_ERR_STR_TABLE_EXT_ENG initializer for error strings + * associated with errors from network and other extended functions. + * + * The generic @ref MBG_ERR_STR_TABLE_ENG initializer should be used + * preferebly since it provides only the basic subset or the full + * set of strings depending on the target system. + * + * @see @ref MBG_ERR_STR_TABLE_ENG + * @see @ref MBG_ERR_STR_TABLE_EXT_ENG + * @see @ref MBG_RETURN_CODES + */ +#define MBG_ERR_STR_TABLE_BASE_ENG \ + { MBG_SUCCESS, "Success" }, \ + { MBG_ERR_STIME, "Invalid date/time for device" }, \ + { MBG_ERR_CFG, "Invalid configuration parameters for device" }, \ + { MBG_ERR_GENERIC, "Generic error" }, \ + { MBG_ERR_TIMEOUT, "Timeout" }, \ + { 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_NOT_READY, "Device not ready" }, \ + { MBG_ERR_INV_TYPE, "Unsupported data type" }, \ + { MBG_ERR_NO_MEM, "Memory allocation error" }, \ + { MBG_ERR_CLAIM_RSRC, "Faild to claim resources" }, \ + { MBG_ERR_DEV_NOT_SUPP, "Device not supported" }, \ + { MBG_ERR_INV_DEV_REQUEST, "Request not supported" }, \ + { MBG_ERR_NOT_SUPP_BY_DEV, "Not supported by device" }, \ + { MBG_ERR_CYCLIC_TIMEOUT, "Cyclic message timeout" }, \ + { MBG_ERR_NOT_SUPP_ON_OS, "Not supported by OS" }, \ + { MBG_ERR_LIB_NOT_COMPATIBLE, "Shared lib not compatible" }, \ + { MBG_ERR_N_COM_EXCEEDS_SUPP, "Num. COM ports exceeds supported" }, \ + { MBG_ERR_N_STR_EXCEEDS_SUPP, "Num. string formats exceeds supported" }, \ + { MBG_ERR_IRQ_UNSAFE, "Unsafe IRQ support" }, \ + { MBG_ERR_N_POUT_EXCEEDS_SUPP, "Num prog. outputs exceeds supported" }, \ + { MBG_ERR_INV_INTNO, "Invalid interrupt number" }, \ + { MBG_ERR_NO_DRIVER, "Driver not found" }, \ + { MBG_ERR_DRV_VERSION, "Driver too old" }, \ + { MBG_ERR_N_UC_MSTR_EXCEEDS_SUPP, "Num. PTP Unicast masters exceeds supported" }, \ + { MBG_ERR_N_GNSS_EXCEEDS_SUPP, "Num. GNSS systems exceeds supported" }, \ + { MBG_ERR_N_GPIO_EXCEEDS_SUPP, "Num. GPIO ports exceeds supported" }, \ + { MBG_ERR_N_XMR_EXCEEDS_SUPP, "Num. XMR sources exceeds supported" }, \ + { MBG_ERR_UNSPEC, "Unspecified error" }, \ + { MBG_ERR_HDR_CSUM, "Header checksum error" }, \ + { MBG_ERR_DATA_CSUM, "Data checksum error" }, \ + { MBG_ERR_RCVD_NACK, "Received NACK message" }, \ + { MBG_ERR_RCVD_NO_ACK, "Didn't receive ACK message" }, \ + { MBG_ERR_CONN_TYPE, "Invalid I/O connection type" }, \ + { MBG_ERR_BYTES_WRITTEN, "Failed to write all bytes" }, \ + { MBG_ERR_IO, "Input/output error" }, \ + { MBG_ERR_INV_PARM, "Invalid parameter passed to function" }, \ + { MBG_ERR_NO_DEV, "No such device, or attempted an inappropriate function." }, \ + { MBG_ERR_NOT_FOUND, "Specified item not found" }, \ + { MBG_ERR_OVERFLOW, "Buffer overflow" }, \ + { MBG_ERR_BUSY, "Device busy" }, \ + { MBG_ERR_INV_HANDLE, "Invalid handle" }, \ + { MBG_ERR_XBP_CASC_LVL, "Too many XBP cascading levels" }, \ + { MBG_ERR_ENCRYPT, "Encryption failed" }, \ + { MBG_ERR_DECRYPT, "Decryption failed" }, \ + { MBG_ERR_DISCONN, "Connection closed by remote site/host" }, \ + { MBG_ERR_INV_CFG, "Invalid/inconsistent configuration read from device" }, \ + { MBG_ERR_RANGE, "Input parameter was out of range" }, \ + { MBG_ERR_INV_TLV_ANN_BYTES, "TLV num of transferred bytes differs from num of announced bytes" }, \ + { MBG_ERR_INV_TLV_SIZE, "MBG_ERR_INV_TLV_SIZE" }, /* ### TODO */ \ + { MBG_ERR_INV_TLV_UID, "MBG_ERR_INV_TLV_UID" }, /* ### TODO */ \ + { MBG_ERR_DATA_SIZE, "Received data size mismatch" }, \ + { MBG_ERR_ALREADY_ALLOC, "Memory already allocated" }, \ + { MBG_ERR_DATA_FMT, "Invalid data format" }, \ + { MBG_ERR_NOT_CONFIGURED, "Configuration is not active and/or configured" }, \ + { MBG_ERR_INV_IDX, "Invalid or unsupported index value used"}, \ + { MBG_ERR_PARM_FMT, "Parameter string format error" }, \ + { MBG_ERR_UNKNOWN, "Unknown error code from external API" }, \ + { MBG_ERR_PAM, "PAM authentication error" }, \ + { MBG_ERR_TIMER, "Timer expired" }, \ + { MBG_ERR_AGAIN, "Try again (later)" }, \ + { MBG_ERR_STR_CHAR, "Invalid character in string" }, \ + { MBG_ERR_STR_LEN, "Wrong string length" }, \ + { MBG_ERR_SN_GCODE_LEN, "Invalid device group code length" }, \ + { MBG_ERR_SN_GCODE_UNKN, "Unknown device group code" }, \ + { MBG_ERR_SN_GCODE_WRONG, "Wrong device group code in S/N" }, \ + { MBG_ERR_SN_VRFY, "Serial number could not be verified" }, \ + { 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" } + + +/** + * @brief A subset of extended strings associated with @ref MBG_RETURN_CODES + * + * This initializer provides only the strings associated with extended + * errors from network and other extended functions. + * + * See the @ref MBG_ERR_STR_TABLE_BASE_ENG initializer for error strings + * associated with basic error codes that are supported on all target systems. + * + * The generic @ref MBG_ERR_STR_TABLE_ENG initializer should be used + * preferebly since it provides only the basic subset or the full + * set of strings depending on the target system. + * + * @see @ref MBG_ERR_STR_TABLE_ENG + * @see @ref MBG_ERR_STR_TABLE_BASE_ENG + * @see @ref MBG_RETURN_CODES + */ +#if defined( MBG_TGT_DOS ) + +#define MBG_ERR_STR_TABLE_EXT_ENG \ + { 0, NULL } + +#else + +#define MBG_ERR_STR_TABLE_EXT_ENG \ + { MBG_ERR_COPY_TO_USER, "Error copying to user space" }, \ + { MBG_ERR_COPY_FROM_USER, "Error copying from user space" }, \ + { MBG_ERR_AUTH, "Authentication failed" }, \ + { MBG_ERR_SOCK_INIT, "Failed to initialize socket" }, \ + { MBG_ERR_INV_SOCK_FD, "Invalid socket descriptor" }, \ + { MBG_ERR_NOT_A_SOCKET, "Not a socket descriptor" }, \ + { MBG_ERR_NBLOCK_WAIT_SLCT, "Select timed out waiting for port ready" }, \ + { 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_PERM, "Operation not permitted, insufficient rights" }, \ + { MBG_ERR_EXIST, "File exists" }, \ + { MBG_ERR_NO_ENTITY, "No such file or directory" }, \ + { MBG_ERR_HOST_NOT_FOUND, "Host not found" }, \ + { MBG_ERR_CONN_RESET, "Connection reset by peer" }, \ + { MBG_ERR_NO_SPACE, "Insufficient disk space" }, \ + { MBG_ERR_PAM, "PAM authentication was not successful" }, \ + { MBG_ERR_TIMER, "Timer expired" } \ + #endif -/* function prototypes: */ +/** + * @brief Strings associated with @ref MBG_RETURN_CODES + * + * @see @ref MBG_RETURN_CODES + */ +#define MBG_ERR_STR_TABLE_ENG \ +{ \ + MBG_ERR_STR_TABLE_BASE_ENG, \ + MBG_ERR_STR_TABLE_EXT_ENG, \ + { 0, NULL } /* end of table */ \ +} + + + +#if defined( __mbg_inline ) + +static __mbg_inline +/** + * @brief Check if the code returned by a function indicates an error + * + * @param[in] rc One of the @ref MBG_RETURN_CODES + * + * @see ::mbg_rc_is_success + * @see @ref MBG_RETURN_CODES + */ +bool mbg_rc_is_error( int rc ) +{ + // MBG_SUCCESS is 0, and all Meinberg error codes are < 0. + return rc < MBG_SUCCESS; + +} // mbg_rc_is_error + + + +static __mbg_inline +/** + * @brief Check if the code returned by a function indicates success + * + * @param[in] rc One of the @ref MBG_RETURN_CODES + * + * @see ::mbg_rc_is_error + * @see @ref MBG_RETURN_CODES + */ +bool mbg_rc_is_success( int rc ) +{ + // There are functions which don't only return MBG_SUCCESS + // on success but some arbitrary positive number, e.g. the + // number of bytes sent. So success just means "not an error". + return !mbg_rc_is_error( rc ); + +} // mbg_rc_is_success + + + +static __mbg_inline +/** + * @brief Check if a return code indicates success, or the specific code @ref MBG_ERR_PERM + * + * @param[in] rc One of the @ref MBG_RETURN_CODES + * + * @see ::mbg_rc_is_success + * @see @ref MBG_RETURN_CODES + */ +bool mbg_rc_is_success_or_err_perm( int rc ) +{ + return mbg_rc_is_success( rc ) || ( rc == MBG_ERR_PERM ); + +} // mbg_rc_is_success_or_err_perm + + +#else + + #define mbg_rc_is_error( _rc ) ( (_rc) < MBG_SUCCESS ) + #define mbg_rc_is_success( _rc ) ( !mbg_rc_is_error( _rc ) ) + + #define mbg_rc_is_success_or_err_perm( _rc ) ( mbg_rc_is_success( _rc ) || ( (_rc) == MBG_ERR_PERM ) ) -#ifdef __cplusplus -extern "C" { #endif + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ -/* (no header definitions found) */ + /** + * @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 + */ + int mbg_errno_to_os( int err_no ) ; + + /** + * @brief Return an error string associated with 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 + */ + const char *mbg_strerror( int mbg_errno ) ; + + /** + * @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 + * + * @return true if rc represented an error code, and a message has been printed, else 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 + * + * If rc contains an error code then an error message is printed, and true is returned. + * + * 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 info2 is NULL, or the error code is not ::MBG_ERR_NOT_SUPP_BY_DEV then the standard + * error message is printed anyway. + * + * @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). + * + * @return true if rc represented an error code, and a message has been printed, else 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 + * + * @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 + * + * @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 + * + * @param[in] st One of the NTSTATUS codes defined in ntstatus.h + * @param[in] info An optional informational text string, or NULL + * + * @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 + * + * @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. + * + * @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 + * + * @param[in] wsa_err A Windows socket API error code as returned by WSAGetLastError() + * @param[in] info An optional informational text string, or NULL + * + * @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 + * + * @param[in] posix_errno A POSIX error code as usually defined in errno.h + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ + int mbg_posix_errno_to_mbg( int posix_errno, const char *info ) ; + + /** + * @brief Translate a POSIX h_errno error code to one of the @ref MBG_ERROR_CODES + * + * This function is specific to translate error codes returned by + * gethostbyname() and gethostbyaddr(). In case of error these functions + * don't set errno but h_errno to a specific value. + * + * The functions gethostbyname() and gethostbyaddr() are obsolete, + * and getaddressinfo() should be used preferably. + * + * @param[in] posix_h_errno An error code as usually defined in netdb.h + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ + int mbg_posix_h_errno_to_mbg( int posix_h_errno, const char *info ) ; + + /** + * @brief Get and translate last error after non-socket function call + * + * Retrieve the "last error" code after a non-socket function has been called + * and translate to one of the @ref MBG_ERROR_CODES. + * + * On POSIX systems the "last error" code is always stored in errno, but + * e.g. under Windows the "last error" code after a socket function + * has to be retrieved by calling WSAGetLastError(), whereas the "last error" + * code from non-socket POSIX-like functions has to be retrieved + * by calling GetLastError(). + * + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ + int mbg_get_last_error( const char *info ) ; + + /** + * @brief Get and translate last error after socket function call + * + * Retrieve the "last error" code after a socket function has been called + * and translate to one of the @ref MBG_ERROR_CODES. + * + * On POSIX systems the "last error" code is always stored in errno, but + * e.g. under Windows the "last error" code after a socket function + * has to be retrieved by calling WSAGetLastError, whereas the "last error" + * code from non-socket POSIX-like functions is stored in errno as usual. + * + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ + int mbg_get_last_socket_error( const char *info ) ; + + /** + * @brief Retrieve and convert last error after gethostbyname() + * + * This function is specific to retrieve and translate error codes + * returned by gethostbyname() and gethostbyaddr(). In case of error + * these functions don't set errno but h_errno on POSIX systems, but + * under Windows the error code can be retrieved by WSAGetLastError() + * as usual. + * + * The functions gethostbyname() and gethostbyaddr() are obsolete, + * and getaddressinfo() should be used preferably. + * + * @param[in] info An optional informational text string, or NULL + * + * @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 + * + * @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. + * + * @return One of the @ref MBG_ERROR_CODES + */ + int mbg_zlib_error_to_mbg( int zlib_error, const char *info, const char *msg ) ; + /* ----- function prototypes end ----- */ + + +#if _USE_WIN32_PRIVATE_STATUS_CODES + +static __mbg_inline /*HDR*/ +/** + * @brief Convert one of the @ref MBG_RETURN_CODES to an OS-specific code + * + * @param[in] rc One of the @ref MBG_RETURN_CODES. + * + * @see @ref MBG_RETURN_CODES + * + * @return An OS-specific success or error code + */ +int mbg_ret_val_to_os( int rc ) +{ + return mbg_rc_is_success( rc ) ? MBG_SYS_RC_SUCCESS : mbg_errno_to_os( rc ); + +} // mbg_ret_val_to_os + +#endif // _USE_WIN32_PRIVATE_STATUS_CODES + + #ifdef __cplusplus } #endif diff --git a/mbglib/common/mbggeo.h b/mbglib/common/mbggeo.h index c3bdb40..29c86d5 100644 --- a/mbglib/common/mbggeo.h +++ b/mbglib/common/mbggeo.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbggeo.h 1.11 2011/06/22 10:18:10Z martin REL_M $ + * $Id: mbggeo.h 1.14 2017/05/10 15:21:40Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,7 @@ * * Terms used: * - * WGS84 world geodetic system of 1984 + * WGS84 World Geodetic System of 1984 * * XYZ WGS84 earth centered, earth fixed (ECEF) kartesian * coordinates @@ -22,7 +22,14 @@ * * ----------------------------------------------------------------------- * $Log: mbggeo.h $ - * Revision 1.11 2011/06/22 10:18:10Z martin + * Revision 1.14 2017/05/10 15:21:40Z martin + * Tiny cleanup. + * Revision 1.13 2017/01/27 08:57:58 martin + * Fixed macro syntax. + * Revision 1.12 2016/10/31 16:50:56 martin + * Fixed a typo. + * Updated doxygen comments. + * Revision 1.11 2011/06/22 10:18:10 martin * Cleaned up handling of pragma pack(). * Revision 1.10 2008/09/03 14:54:28 martin * Added macros to swap endianess of structures. @@ -34,7 +41,7 @@ * Revision 1.7 2003/02/14 13:23:04Z martin * Omit inclusion of mystd.h. * Revision 1.6 2003/01/13 15:17:15 martin - * Structures were defined with default alignment which + * Structures were defined with default alignment which * could result in different data sizes on different platforms. * Revision 1.5 2002/12/18 14:46:41Z martin * Removed variable USER_POS meinberg. @@ -69,106 +76,136 @@ #define _USING_BYTE_ALIGNMENT #endif +#ifdef __cplusplus +extern "C" { +#endif + /** - Geographic longitude or latitude in [degrees, minutes, seconds] - longitude East latitude North and positve, South or West angles negative + * @brief Geographic longitude or latitude in [degrees, minutes, seconds] + * + * Longitude East and latitude North are positive angles, South or West + * angles are negative. */ typedef struct { - uint16_t prefix; /**< 'N', 'E', 'S' or 'W' */ - uint16_t deg; /**< [0...90 (lat) or 0...180 (lon)] */ - uint16_t min; /**< [0...59] */ - double sec; /**< [0...59.999] */ + uint16_t prefix; ///< 'N', 'E', 'S' or 'W' + uint16_t deg; ///< [0...90 (lat) or 0...180 (lon)] + uint16_t min; ///< [0...59] + double sec; ///< [0...59.99999...] + } DMS; -// The corresponding macro _mbg_swab_dms() is defined in gpsdefs.h. #define _mbg_swab_dms( _p ) \ +do \ { \ _mbg_swab16( &(_p)->prefix ); \ _mbg_swab16( &(_p)->deg ); \ _mbg_swab16( &(_p)->min ); \ _mbg_swab_double( &(_p)->sec ); \ -} +} while ( 0 ) +/** + * @brief A geographic position represented in different formats + */ typedef struct { - XYZ xyz; /**< always WGS84 ECEF coordinates */ - LLA lla; /**< depending on the ellipsoid used for reference */ - DMS longitude; /**< longitude in degrees, minutes, seconds */ - DMS latitude; /**< latitude in degrees, minutes, seconds */ - int16_t ellipsoid; /**< ellipsoid used for reference */ + XYZ xyz; ///< Always WGS84 ECEF coordinates + LLA lla; ///< Longitude, latitude and altitude, depending on the ellipsoid used for reference + DMS longitude; ///< Longitude broken down to degrees, minutes, seconds + DMS latitude; ///< Latitude broken down to degrees, minutes, seconds + int16_t ellipsoid; ///< Ellipsoid used for reference, see ::ELLIPSOIDS + } POS; #define _mbg_swab_pos( _p ) \ +do \ { \ _mbg_swab_xyz( (_p)->xyz ); \ _mbg_swab_lla( (_p)->lla ); \ _mbg_swab_dms( &(_p)->longitude ); \ _mbg_swab_dms( &(_p)->latitude ); \ _mbg_swab16( &(_p)->ellipsoid ); \ -} +} while ( 0 ) +/** + * @brief A structure used internally to compute a geographic position + * + * Also contains intermediate results useful for the computation. + */ typedef struct { - CSUM csum; /* checksum of the remaining bytes */ - int16_t valid; /* flag data are valid */ + CSUM csum; ///< Checksum of the remaining bytes + int16_t valid; ///< Indicator if data is valid - char name[40]; - POS pos; /* the position in WGS84 ECEF coords and LLA */ + char name[40]; ///< Informational string + POS pos; ///< The position in WGS84 ECEF coords and ::LLA double det; -/* The components below hold the results of intermediate terms */ -/* computed in complete_user_pos(). */ + // The components below hold the results of intermediate terms + // computed in complete_user_pos(). -/* The sin.., cos.., nt.. and ut.. variables are used to compute the */ -/* enu_dcos[] parameters of a SV structure in xyz_to_ead(). */ + // The sin.., cos.., nt.. and ut.. variables are used to compute the + // enu_dcos[] parameters of a SV structure in xyz_to_ead(). -/* The e_radius.. variables are used to compute the latitude, longitude */ -/* and altitude from ECEF coordinates in lla_to_xyz(). */ + // The e_radius.. variables are used to compute the latitude, longitude + // and altitude from ECEF coordinates in lla_to_xyz(). - double sin_lat; /* sin( latitude ) */ - double cos_lat; /* cos( latitude ) */ - double sin_lon; /* sin( longitude ) */ - double cos_lon; /* cos( longitude ) */ + double sin_lat; ///< sin( latitude ) + double cos_lat; ///< cos( latitude ) + double sin_lon; ///< sin( longitude ) + double cos_lon; ///< cos( longitude ) - double nt1; /* -sin_lat * cos_lon */ - double nt2; /* -sin_lat * sin_lon */ - double utx; /* cos_lat * cos_lon */ - double uty; /* cos_lat * sin_lon */ + double nt1; ///< -sin_lat * cos_lon + double nt2; ///< -sin_lat * sin_lon + double utx; ///< cos_lat * cos_lon + double uty; ///< cos_lat * sin_lon - double e_radius; /* N */ - double e_radius_alt; /* N + h */ + double e_radius; ///< N + double e_radius_alt; ///< N + h } USER_POS; +/** + * @brief Characteristics of a geographic reference ellipsoid + */ typedef struct { - CSUM csum; /* checksum of the remaining bytes */ - int16_t valid; /* flag data are valid */ + CSUM csum; ///< Checksum of the remaining bytes + int16_t valid; ///< Indicator if data is valid char name[40]; - XYZ dxyz; /* offset from the WGS84 ECEF coords */ - double a; /* semi major axis */ - double rcp_f; /* reciproke of flatness */ + XYZ dxyz; ///< Offset from the WGS84 ECEF coords + double a; ///< Semi major axis + double rcp_f; ///< Reciproke of flatness + + // The variables below are computed in the init_mbggeo() function: -/* the variables below will be computed in the init_mbggeo() function: */ + double f; ///< Flatness + double b; ///< Semi minor axis + double sqr_e; ///< Square of numerical eccentricity - double f; /* flatness */ - double b; /* semi minor axis */ - double sqr_e; /* square of numerical eccentricity */ } ELLIPSOID; -enum { WGS84, BESSEL, N_ELLIPSOIDS }; +/** + * @brief An enumeration of known ellipsoids + */ +enum ELLIPSOIDS +{ + WGS84, + BESSEL, + N_ELLIPSOIDS +}; + _ext ELLIPSOID ellipsoid[N_ELLIPSOIDS] #ifdef _DO_INIT @@ -191,15 +228,15 @@ _ext ELLIPSOID ellipsoid[N_ELLIPSOIDS] ; -/* WGS84 constants used */ +// WGS84 constants used -_ext double OMEGADOTe /* earth's rotation rate [rad/sec] */ +_ext double OMEGADOTe // Earth's rotation rate [rad/sec] #ifdef _DO_INIT = 7.2921151467e-5 #endif ; -_ext double mue /* earth's gravitational constant [m^3/sec^2] */ +_ext double mue // Earth's gravitational constant [m^3/sec^2] #ifdef _DO_INIT = 3.986005e14 #endif @@ -249,18 +286,12 @@ _ext double d2r ; -/* variables for simplifying computations */ +// Variables for simplifying computations _ext double gps_two_pi; -_ext double sqrt_mue; /* sqrt( mue ) */ - - +_ext double sqrt_mue; // sqrt( mue ) -/* function prototypes: */ -#ifdef __cplusplus -extern "C" { -#endif /* ----- function prototypes begin ----- */ diff --git a/mbglib/common/mbgioctl.h b/mbglib/common/mbgioctl.h new file mode 100644 index 0000000..b99cacc --- /dev/null +++ b/mbglib/common/mbgioctl.h @@ -0,0 +1,1239 @@ + +/************************************************************************** + * + * $Id: mbgioctl.h 1.32 2018/11/22 15:01:44Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions used with device driver IOCTL. + * + * ----------------------------------------------------------------------- + * $Log: mbgioctl.h $ + * Revision 1.32 2018/11/22 15:01:44Z martin + * Refactored structure IOCTL_GENERIC_REQ using fixed size integer + * types only to avoid pointer size problems in a mixed 32/64 bit + * Linux environment. + * Revision 1.31 2018/11/06 17:20:25 martin + * Updated function prototypes and a comment. + * Revision 1.30 2018/08/24 10:03:46Z martin + * Removed code that was commented out. + * Added a comment. + * Revision 1.29 2018/08/08 15:36:50Z martin + * Renamed a local macro for clarity. + * Revision 1.28 2018/07/05 09:02:29Z martin + * Always use DMA-capable buffers as required by Linux kernels 4.9+. + * Moved definition of PCPS_IO_BUFFER and some related + * types to new header file pcpsiobf.h. + * Common, OS-specific definitions for IOCTL return codes. + * Updated function prototypes. + * Revision 1.27 2017/07/05 09:37:18 martin + * Definitions to support GPIO ports and XMR. + * Support new way to check if specific feature supported. + * Moved some IOCTL-related definitions from pcpsdev.h here. + * Added some doxygen comments. + * Revision 1.26 2013/09/26 08:27:04Z martin + * Support GNSS API. + * 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 + * 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. + * Support on-board event logs. + * Support debug status. + * 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 + * and also works for other target systems. + * Support reading CORR_INFO, and reading/writing TR_DISTANCE. + * New code IOCTL_DEV_HAS_PZF. + * Support PTP unicast configuration. + * Changed the names of a few IOCTL codes to follow general naming conventions. + * Added definitions to support privilege level requirements for IOCTLs. + * Use native alignment to avoid problems on Sparc and IA64. + * 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. + * Revision 1.24 2009/12/15 15:34:59Z daniel + * Support reading the raw IRIG data bits for firmware versions + * which support this feature. + * Revision 1.23 2009/09/29 15:08:41Z martin + * Support retrieving time discipline info. + * Revision 1.22 2009/08/17 13:48:17 martin + * Moved specific definition of symbol _HAVE_IOCTL_WITH_SIZE from + * mbgdevio.c here and renamed it to _MBG_SUPP_VAR_ACC_SIZE. + * Revision 1.21 2009/06/19 12:18:53 martin + * Added PCPS_GIVE_IRIG_TIME command and associated definitions. + * Fixed a declaration which might have led to syntax errors. + * Revision 1.20 2009/06/09 10:02:36Z daniel + * Support PTP configuration and state. + * Support simple LAN interface configuration. + * Revision 1.19 2009/03/19 15:17:59 martin + * Support reading MM timestamps without cycles. + * Support UTC parms and configurable time scales. + * For consistent naming renamed IOCTL_GET_FAST_HR_TIMESTAMP + * to IOCTL_GET_FAST_HR_TIMESTAMP_CYCLES. + * Added IOCTL_DEV_HAS_IRIG_CTRL_BITS and IOCTL_GET_IRIG_CTRL_BITS. + * Revision 1.18 2008/12/11 10:32:56Z martin + * Added _cmd_from_ioctl_code() macro for Linux. + * Added IOCTL codes for .._has_asic_version() and .._has_asic_features(). + * Added IOCTL codes for ..._is_msf(), .._is_lwr(), .._is_wwvb(). + * Added IOCTL codes IOCTL_GET_IRQ_STAT_INFO, IOCTL_GET_CYCLES_FREQUENCY, + * IOCTL_HAS_FAST_HR_TIMESTAMP, and IOCTL_GET_FAST_HR_TIMESTAMP. + * Revision 1.17 2008/01/17 09:35:15 daniel + * Added ioctl calls IOCTL_GET_MAPPED_MEM_ADDR and + * IOCTL_UNMAP_MAPPED_MEM. + * Cleanup for PCI ASIC version and features. + * Revision 1.16 2007/09/25 10:37:04Z martin + * Added macro _cmd_from_ioctl_code() for Windows. + * Revision 1.15 2007/05/21 15:00:01Z martin + * Unified naming convention for symbols related to ref_offs. + * Revision 1.14 2007/03/02 10:27:03 martin + * Preliminary support for *BSD. + * Preliminary _cmd_from_ioctl(). + * Revision 1.13 2006/03/10 10:36:54 martin + * Added support for programmable pulse outputs. + * Revision 1.12 2005/06/02 10:22:05Z martin + * Added IOCTL code IOCTL_GET_SYNTH_STATE. + * Added IOCTL codes IOCTL_DEV_HAS_GENERIC_IO, + * IOCTL_PCPS_GENERIC_IO, and IOCTL_GET_SYNTH_STATE. + * Revision 1.11 2005/01/14 10:21:11Z martin + * Added IOCTLs which query device features. + * Revision 1.10 2004/12/09 11:03:36Z martin + * 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. + * 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. + * Renamed IOCTL_GET_GPS_STAT to IOCTL_GET_GPS_BVAR_STAT. + * Use more specific data types than generic types. + * Modified IOCTL codes used for hardware debugging. + * Revision 1.8 2004/09/06 15:46:04Z martin + * Changed definition of IOCTL codes to support syntax used + * with Linux kernel 2.6.x. + * Account for renamed symbols. + * Revision 1.7 2004/04/07 10:08:11 martin + * Added IOCTL codes used to trigger hardware debug events. + * Revision 1.6 2003/12/22 15:37:18Z martin + * Added codes to read ASIC version, and read times + * with associated cycle counter values. + * Revision 1.5 2003/06/19 09:02:30Z martin + * New codes IOCTL_GET_PCPS_UCAP_ENTRIES and IOCTL_GET_PCPS_UCAP_EVENT. + * Renamed IOCTL_PCPS_CLR_CAP_BUFF to IOCTL_PCPS_CLR_UCAP_BUFF. + * Cleaned up IOCTL code names related to PCPS_TZDL. + * Reordered upper IOCTL code numbers again. + * Revision 1.4 2003/04/09 13:50:39Z martin + * Re-organized IOCTL codes. + * Supports Win32. + * Added missing pragma pack(). + * Revision 1.3 2003/02/14 13:20:08Z martin + * Include mbggeo.h instead of mygeo.h. + * Revision 1.2 2001/11/30 09:52:48 martin + * Added support for event_time which, however, requires + * a custom GPS firmware. + * Revision 1.1 2001/03/05 16:34:22 MARTIN + * Initial revision + * + **************************************************************************/ + +#ifndef _MBGIOCTL_H +#define _MBGIOCTL_H + + +/* Other headers to be included */ + +#include <mbg_tgt.h> +#include <cfg_hlp.h> +#include <mbgerror.h> +#include <mbggeo.h> +#include <pcpsdev.h> +#include <pci_asic.h> +#include <pcpsiobf.h> + +#if defined( MBG_TGT_LINUX ) + #include <linux/ioctl.h> +#endif + +#if defined( MBG_TGT_BSD ) + #include <sys/ioccom.h> +#endif + +#if defined( MBG_TGT_WIN32 ) + + #if !defined( MBG_TGT_KERNEL ) + #include <winioctl.h> + #endif + + #if !defined( MBG_TGT_WIN32_NON_PNP ) + #ifdef _MBGIOCTL + #include <initguid.h> // instance the GUID + #else + #include <guiddef.h> // just define the GUID + #endif + #endif + +#endif + + + +/* Start of header body */ + +// We have to use native alignment here! + +#ifdef __cplusplus +extern "C" { +#endif + + +#if defined( MBG_ARCH_X86 ) && defined( DEBUG ) && DEBUG + #define USE_DEBUG_PORT 1 +#else + #define USE_DEBUG_PORT 0 +#endif + + +#if defined( MBG_TGT_POSIX ) && !defined( MBG_TGT_QNX_NTO ) + #define MBG_HAS_POSIX_IOCTL 1 +#endif + + +// A kernel driver's IOCTL handler should return some system-specific +// error code in case of failure. +// We define the most appropriate return codes for specific error +// conditions here, and the IOCTL caller has to map them back to +// one of the @ref MBG_ERROR_CODES. + +#if defined( MBG_TGT_WIN32 ) && defined( MBG_TGT_KERNEL ) + +#if _USE_WIN32_PRIVATE_STATUS_CODES + + // We let the kernel driver's IOCTL handler return private error + // codes in NTSTATUS format, so the DeviceIoControl() function in + // user space fails, and the error code returned by a subsequent + // GetLastError() returns the original custom error code. This + // seems to work well but is an undocumented feature. Also, it + // 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. + #define _mbg_krn_errno_to_os( _n ) \ + ( ( (_n) == MBG_SUCCESS ) ? STATUS_SUCCESS : \ + ( (NTSTATUS) ( STATUS_SEVERITY_ERROR | STATUS_CUSTOM_FLAG | ( (-(_n)) & 0xFFFF ) ) ) ) + +#else + + // We let the kernel driver's IOCTL handler return system error + // codes in NTSTATUS format, so the DeviceIoControl() function + // in user space fails, and a standard Win32 error code is + // returned by a subsequent GetLastError() call. + // + // ::mbg_errno_to_os in kernel mode uses ::mbg_ioctl_to_ntstatus_table + // to lookup a system NTSTATUS code which is passed up to user space. + // + // The Windows kernel maps that NTSTATUS code to some Win32 error code + // which can be retrieved by calling GetLastError() if DeviceIoControl() + // has failed. + // + // ::mbg_get_last_error in user space calls GetLastError() and + // uses ::win32_error_table to lookup one of the @ref MBG_ERROR_CODES + // associated with the retrieved Win32 error. + // Ideally, this should correspond to the Meinberg error code + // that has been used in kernel mode to lookup the NTSTATUS code. + #define _mbg_krn_errno_to_os( _n ) \ + mbg_errno_to_os( _n ) + +#endif // _USE_WIN32_PRIVATE_STATUS_CODES + +#endif // defined( MBG_TGT_WIN32 ) && defined( MBG_TGT_KERNEL ) + + + +#if defined( MBG_TGT_KERNEL ) + +#define IOCTL_RC_SUCCESS MBG_SYS_RC_SUCCESS + +#if defined( MBG_TGT_LINUX ) + + // super user rights required + #define IOCTL_RC_ERR_PERM -EPERM // MBG_ERR_PERM + + #define IOCTL_RC_ERR_UNSUPP_IOCTL -ENODEV // MBG_ERR_INV_DEV_REQUEST ## + + #define IOCTL_RC_ERR_INVAL_PARAM -EINVAL // MBG_ERR_INV_PARM + + #define IOCTL_RC_ERR_NOT_SUPP_BY_DEV -ENOTTY // MBG_ERR_NOT_SUPP_BY_DEV + + #define IOCTL_RC_ERR_NO_MEM -ENOMEM // MBG_ERR_NO_MEM + + #define IOCTL_RC_ERR_BUSY_IRQ_UNSAFE -EBUSY // MBG_ERR_BUSY, MBG_ERR_IRQ_UNSAFE + + #define IOCTL_RC_ERR_DEV_ACCESS -EIO // rc from low level routine + + // Linux-specific codes + #define IOCTL_RC_ERR_COPY_TO_USER -EFAULT // MBG_ERR_COPY_TO_USER + #define IOCTL_RC_ERR_COPY_FROM_USER -EFAULT // MBG_ERR_COPY_FROM_USER + +#elif defined( MBG_TGT_BSD ) // FIXME specific + + // super user rights required + #define IOCTL_RC_ERR_PERM EPERM // MBG_ERR_PERM + + #if defined( ENOIOCTL ) // E.g. FreeBSD, ... + #define IOCTL_RC_ERR_UNSUPP_IOCTL ENOIOCTL // TODO or ENODEV? MBG_ERR_INV_DEV_REQUEST + #else + #define IOCTL_RC_ERR_UNSUPP_IOCTL ENODEV // MBG_ERR_INV_DEV_REQUEST + #endif + + #define IOCTL_RC_ERR_INVAL_PARAM EINVAL // MBG_ERR_INV_PARM + + #define IOCTL_RC_ERR_NOT_SUPP_BY_DEV ENOTTY // MBG_ERR_NOT_SUPP_BY_DEV + + #define IOCTL_RC_ERR_NO_MEM ENOMEM // MBG_ERR_NO_MEM + + #define IOCTL_RC_ERR_BUSY_IRQ_UNSAFE EBUSY // MBG_ERR_BUSY, MBG_ERR_IRQ_UNSAFE + + #define IOCTL_RC_ERR_DEV_ACCESS EIO // TODO or EFAULT? rc from low level routine + +#elif defined( MBG_TGT_WIN32 ) + + #define IOCTL_RC_ERR_PERM _mbg_krn_errno_to_os( MBG_ERR_PERM ) + + #define IOCTL_RC_ERR_UNSUPP_IOCTL _mbg_krn_errno_to_os( MBG_ERR_INV_DEV_REQUEST ) + + #define IOCTL_RC_ERR_INVAL_PARAM _mbg_krn_errno_to_os( MBG_ERR_INV_PARM ) + + #define IOCTL_RC_ERR_NOT_SUPP_BY_DEV _mbg_krn_errno_to_os( MBG_ERR_NOT_SUPP_BY_DEV ) + + #define IOCTL_RC_ERR_NO_MEM _mbg_krn_errno_to_os( MBG_ERR_NO_MEM ) + + #define IOCTL_RC_ERR_BUSY_IRQ_UNSAFE _mbg_krn_errno_to_os( MBG_ERR_IRQ_UNSAFE ) + + #define IOCTL_RC_ERR_DEV_ACCESS _mbg_krn_errno_to_os( rc ) + +#endif + +#endif // defined( MBG_TGT_KERNEL ) + + + +#if defined( MBG_TGT_LINUX ) + + // a magic number used to generate IOCTL cmd codes + #define IOTYPE 'M' + + #define _MBG_IO _IO + #define _MBG_IOR _IOR + #define _MBG_IOW _IOW + + #define _cmd_from_ioctl_code( _ioc ) \ + _IOC_NR( _ioc ) + +#elif defined( MBG_TGT_BSD ) + + // Under NetBSD 'Z' marks passthrough IOCTLs, under FreeBSD the code + // does not seem to matter, so we use 'Z' anyway. + #define IOTYPE 'Z' + + #define _MBG_IO _IO + #define _MBG_IOR _IOR + #define _MBG_IOW _IOW + +#elif defined( MBG_TGT_WIN32 ) + + #if !defined( _MBG_SUPP_VAR_ACC_SIZE ) + // Windows supports IOCTL commands where the sizes of + // input and output buffer can be specified dynamically. + #define _MBG_SUPP_VAR_ACC_SIZE 1 + #endif + + #ifdef DEFINE_GUID // don't break compiles of drivers that + // include this header but don't want the + // GUIDs + + // ClassGuid = { 78A1C341-4539-11d3-B88D-00C04FAD5171 } + DEFINE_GUID( GUID_MEINBERG_DEVICE, + 0x78A1C341L, 0x4539, 0x11D3, + 0xB8, 0x8D, 0x00, 0xC0, 0x4F, 0xAD, 0x51, 0x71 ); + #endif + + // Device type in the "User Defined" range." + #define PCPS_TYPE 40000 + + // IOCTL function codes from 0x800 to 0xFFF are for customer use. + #define _MBG_IOCTL_BIAS 0x930 + + #define _MBG_IO( _t, _n ) \ + CTL_CODE( PCPS_TYPE, _MBG_IOCTL_BIAS + _n, METHOD_BUFFERED, FILE_READ_ACCESS ) + + #define _MBG_IOR( _t, _n, _sz ) \ + _MBG_IO( _t, _n ) + + #define _MBG_IOW _MBG_IOR + + #define _cmd_from_ioctl_code( _ioc ) \ + ( ( ( (_ioc) >> 2 ) & 0x0FFF ) - _MBG_IOCTL_BIAS ) + +#endif + + +#if !defined( _MBG_SUPP_VAR_ACC_SIZE ) + // Many operating systems don't support specifying the sizes of IOCTL + // input and output buffers dynamically, so we disable this by default. + #define _MBG_SUPP_VAR_ACC_SIZE 0 +#endif + + + +// The structure below is used by the IOCTL_PCPS_GENERIC_... calls. + +#if defined( MBG_TGT_LINUX ) + #if defined( MBG_ARCH_ARM ) || defined( MBG_ARCH_SPARC ) + #define USE_IOCTL_GENERIC_REQ 0 + #endif +#endif + +#if defined( MBG_TGT_WIN32 ) + // required for 32bit/64 bit compatibility + #define USE_IOCTL_GENERIC_REQ 0 +#endif + +#if !defined( USE_IOCTL_GENERIC_REQ ) + #define USE_IOCTL_GENERIC_REQ 1 +#endif + + +#if USE_IOCTL_GENERIC_REQ + +/** + * @brief A structure used to pass generic IOCTL requests to the kernel driver + * + * In a mixed 32/64 bit environment we may have 32 bit pointers in user space + * but 64 bit pointers in kernel space, so if we defined buffer addresses as + * usual pointers, and buffer sizes as size_t the memory layout of this structure + * would be different in 32 bit and 64 bit builds, so we use only fixed-size types + * to avoid this and make sure the structure has always the same size. + * + * @note Pointers should generally be cast to 'uintptr_t' before being copied + * into the 64 bit address fields. This makes sure 32 bit pointers are expanded + * to 64 bit in an unsigned way, i.e. with the extended bytes always set to 0x00. + * Without this cast a pointer might be extended with 0xFF if the MSB of the + * original 32 bit pointer is set, which would result in an incompatible 64 bit + * address in kernel space. + * In an environment where pointers have 64 bit anyway an 'uintptr_t' cast wouldn't + * be required, but it doesn't hurt, either. + */ +typedef struct +{ + uint64_t in_p; ///< Address of the input buffer. + uint64_t out_p; ///< Address of the output buffer. + uint32_t in_sz; ///< Size of the input buffer. + uint32_t out_sz; ///< Size of the output buffer. + uint32_t info; ///< E.g. cmd code for the device. + uint32_t reserved; ///< Reserved, yet not used. + +} IOCTL_GENERIC_REQ; + +#define _MBG_IOG( _t, _n, _s ) _MBG_IOW( _t, _n, _s ) + +#else + +/** + * @brief Control structure used for generic IOCTL requests + * + * Used by the IOCTL_PCPS_GENERIC_... calls. + * + * @note Is slower, but avoids OS-specific problems occurring + * with IOCTL_GENERIC_REQ. + */ +typedef struct +{ + uint32_t info; + uint32_t data_size_in; + uint32_t data_size_out; + +} IOCTL_GENERIC_CTL; + + +/** + * @brief Data buffer used for generic IOCTL requests + * + * Used by the IOCTL_PCPS_GENERIC_... calls. + * + * @note Is slower, but avoids OS-specific problems occurring + * with IOCTL_GENERIC_REQ. + */ +typedef struct +{ + IOCTL_GENERIC_CTL ctl; + uint8_t data[1]; + +} IOCTL_GENERIC_BUFFER; + +#define _MBG_IOG( _t, _n, _s ) _MBG_IO( _t, _n ) + +#endif + + + +/** + * @brief Request buffer used to query a device feature + */ +typedef struct +{ + uint32_t feat_type; ///< See ::DEV_FEAT_TYPES + uint32_t feat_num; ///< Number and range depending on ::IOCTL_DEV_FEAT_REQ::feat_type value + +} IOCTL_DEV_FEAT_REQ; + + + +typedef union +{ + PCPS_STATUS_PORT pcps_status_port; + PCPS_TIME_STAMP pcps_time_stamp; + PCPS_TIME_STAMP_CYCLES pcps_time_stamp_cycles; + +} PCPS_SPIN_BUFFER; + + + +typedef union +{ + IOCTL_DEV_FEAT_REQ dev_feat_req; + + PCPS_MAPPED_MEM mapped_mem; + + #if USE_IOCTL_GENERIC_REQ + IOCTL_GENERIC_REQ req; + #else + IOCTL_GENERIC_CTL ctl; + #endif + + int i; + +} IOCTL_BUFFER; + + + +/** + * @defgroup group_ioctl_codes IOCTL codes used by Meinberg drivers + * + * @see ::IOCTL_CODES_TABLE + * + * @anchor IOCTL_CODES + * + * @{ */ + +// read general driver info, device info, and status port +#define IOCTL_GET_PCPS_DRVR_INFO _MBG_IOR( IOTYPE, 0x00, PCPS_DRVR_INFO ) +#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. +#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 ) +#define IOCTL_PCPS_GENERIC_WRITE_GPS _MBG_IOG( IOTYPE, 0x06, IOCTL_GENERIC_REQ ) + +// normal direct read/write operations +#define IOCTL_GET_PCPS_TIME _MBG_IOR( IOTYPE, 0x10, PCPS_TIME ) +#define IOCTL_SET_PCPS_TIME _MBG_IOW( IOTYPE, 0x11, PCPS_STIME ) + +#define IOCTL_GET_PCPS_SYNC_TIME _MBG_IOR( IOTYPE, 0x12, PCPS_TIME ) + +#define IOCTL_GET_PCPS_TIME_SEC_CHANGE _MBG_IOR( IOTYPE, 0x13, PCPS_TIME ) + +#define IOCTL_GET_PCPS_HR_TIME _MBG_IOR( IOTYPE, 0x14, PCPS_HR_TIME ) + +// the next one is supported with custom GPS firmware only: +#define IOCTL_SET_PCPS_EVENT_TIME _MBG_IOW( IOTYPE, 0x15, PCPS_TIME_STAMP ) + +#define IOCTL_GET_PCPS_SERIAL _MBG_IOR( IOTYPE, 0x16, PCPS_SERIAL ) +#define IOCTL_SET_PCPS_SERIAL _MBG_IOW( IOTYPE, 0x17, PCPS_SERIAL ) + +#define IOCTL_GET_PCPS_TZCODE _MBG_IOR( IOTYPE, 0x18, PCPS_TZCODE ) +#define IOCTL_SET_PCPS_TZCODE _MBG_IOW( IOTYPE, 0x19, PCPS_TZCODE ) + +#define IOCTL_GET_PCPS_TZDL _MBG_IOR( IOTYPE, 0x1A, PCPS_TZDL ) +#define IOCTL_SET_PCPS_TZDL _MBG_IOW( IOTYPE, 0x1B, PCPS_TZDL ) + +#define IOCTL_GET_REF_OFFS _MBG_IOR( IOTYPE, 0x1C, MBG_REF_OFFS ) +#define IOCTL_SET_REF_OFFS _MBG_IOW( IOTYPE, 0x1D, MBG_REF_OFFS ) + +#define IOCTL_GET_MBG_OPT_INFO _MBG_IOR( IOTYPE, 0x1E, MBG_OPT_INFO ) +#define IOCTL_SET_MBG_OPT_SETTINGS _MBG_IOW( IOTYPE, 0x1F, MBG_OPT_SETTINGS ) + +#define IOCTL_GET_PCPS_IRIG_RX_INFO _MBG_IOR( IOTYPE, 0x20, IRIG_INFO ) +#define IOCTL_SET_PCPS_IRIG_RX_SETTINGS _MBG_IOW( IOTYPE, 0x21, IRIG_SETTINGS ) + +#define IOCTL_PCPS_CLR_UCAP_BUFF _MBG_IO( IOTYPE, 0x22 ) +#define IOCTL_GET_PCPS_UCAP_ENTRIES _MBG_IOR( IOTYPE, 0x23, PCPS_UCAP_ENTRIES ) +#define IOCTL_GET_PCPS_UCAP_EVENT _MBG_IOR( IOTYPE, 0x24, PCPS_HR_TIME ) + + +#define IOCTL_GET_GPS_TZDL _MBG_IOR( IOTYPE, 0x25, TZDL ) +#define IOCTL_SET_GPS_TZDL _MBG_IOW( IOTYPE, 0x26, TZDL ) + +#define IOCTL_GET_GPS_SW_REV _MBG_IOR( IOTYPE, 0x27, SW_REV ) + +#define IOCTL_GET_GPS_BVAR_STAT _MBG_IOR( IOTYPE, 0x28, BVAR_STAT ) + +#define IOCTL_GET_GPS_TIME _MBG_IOR( IOTYPE, 0x29, TTM ) +#define IOCTL_SET_GPS_TIME _MBG_IOW( IOTYPE, 0x2A, TTM ) + +#define IOCTL_GET_GPS_PORT_PARM _MBG_IOR( IOTYPE, 0x2B, PORT_PARM ) +#define IOCTL_SET_GPS_PORT_PARM _MBG_IOW( IOTYPE, 0x2C, PORT_PARM ) + +#define IOCTL_GET_GPS_ANT_INFO _MBG_IOR( IOTYPE, 0x2D, ANT_INFO ) + +#define IOCTL_GET_GPS_UCAP _MBG_IOR( IOTYPE, 0x2E, TTM ) + +#define IOCTL_GET_GPS_ENABLE_FLAGS _MBG_IOR( IOTYPE, 0x2F, ENABLE_FLAGS ) +#define IOCTL_SET_GPS_ENABLE_FLAGS _MBG_IOW( IOTYPE, 0x30, ENABLE_FLAGS ) + +#define IOCTL_GET_GPS_STAT_INFO _MBG_IOR( IOTYPE, 0x31, STAT_INFO ) + +#define IOCTL_SET_GPS_CMD _MBG_IOW( IOTYPE, 0x32, GPS_CMD ) + +#define IOCTL_GET_GPS_IDENT _MBG_IOR( IOTYPE, 0x33, IDENT ) + +#define IOCTL_GET_GPS_POS _MBG_IOR( IOTYPE, 0x34, POS ) +#define IOCTL_SET_GPS_POS_XYZ _MBG_IOW( IOTYPE, 0x35, XYZ ) +#define IOCTL_SET_GPS_POS_LLA _MBG_IOW( IOTYPE, 0x36, LLA ) + +#define IOCTL_GET_GPS_ANT_CABLE_LEN _MBG_IOR( IOTYPE, 0x37, ANT_CABLE_LEN ) +#define IOCTL_SET_GPS_ANT_CABLE_LEN _MBG_IOW( IOTYPE, 0x38, ANT_CABLE_LEN ) + +#define IOCTL_GET_GPS_RECEIVER_INFO _MBG_IOR( IOTYPE, 0x39, RECEIVER_INFO ) +#define IOCTL_GET_GPS_ALL_STR_TYPE_INFO _MBG_IOG( IOTYPE, 0x3A, IOCTL_GENERIC_REQ ) // variable size +#define IOCTL_GET_GPS_ALL_PORT_INFO _MBG_IOG( IOTYPE, 0x3B, IOCTL_GENERIC_REQ ) // variable size + +#define IOCTL_SET_GPS_PORT_SETTINGS_IDX _MBG_IOW( IOTYPE, 0x3C, PORT_SETTINGS_IDX ) + +#define IOCTL_GET_PCI_ASIC_VERSION _MBG_IOR( IOTYPE, 0x3D, PCI_ASIC_VERSION ) + +#define IOCTL_GET_PCPS_TIME_CYCLES _MBG_IOR( IOTYPE, 0x3E, PCPS_TIME_CYCLES ) +#define IOCTL_GET_PCPS_HR_TIME_CYCLES _MBG_IOR( IOTYPE, 0x3F, PCPS_HR_TIME_CYCLES ) + +#define IOCTL_GET_PCPS_IRIG_TX_INFO _MBG_IOR( IOTYPE, 0x40, IRIG_INFO ) +#define IOCTL_SET_PCPS_IRIG_TX_SETTINGS _MBG_IOW( IOTYPE, 0x41, IRIG_SETTINGS ) + +#define IOCTL_GET_SYNTH _MBG_IOR( IOTYPE, 0x42, SYNTH ) +#define IOCTL_SET_SYNTH _MBG_IOW( IOTYPE, 0x43, SYNTH ) + + +#define IOCTL_DEV_IS_GPS _MBG_IOR( IOTYPE, 0x44, int ) +#define IOCTL_DEV_IS_DCF _MBG_IOR( IOTYPE, 0x45, int ) +#define IOCTL_DEV_IS_IRIG_RX _MBG_IOR( IOTYPE, 0x46, int ) + +#define IOCTL_DEV_HAS_HR_TIME _MBG_IOR( IOTYPE, 0x47, int ) +#define IOCTL_DEV_HAS_CAB_LEN _MBG_IOR( IOTYPE, 0x48, int ) +#define IOCTL_DEV_HAS_TZDL _MBG_IOR( IOTYPE, 0x49, int ) +#define IOCTL_DEV_HAS_PCPS_TZDL _MBG_IOR( IOTYPE, 0x4A, int ) +#define IOCTL_DEV_HAS_TZCODE _MBG_IOR( IOTYPE, 0x4B, int ) +#define IOCTL_DEV_HAS_TZ _MBG_IOR( IOTYPE, 0x4C, int ) +#define IOCTL_DEV_HAS_EVENT_TIME _MBG_IOR( IOTYPE, 0x4D, int ) +#define IOCTL_DEV_HAS_RECEIVER_INFO _MBG_IOR( IOTYPE, 0x4E, int ) +#define IOCTL_DEV_CAN_CLR_UCAP_BUFF _MBG_IOR( IOTYPE, 0x4F, int ) +#define IOCTL_DEV_HAS_UCAP _MBG_IOR( IOTYPE, 0x50, int ) +#define IOCTL_DEV_HAS_IRIG_TX _MBG_IOR( IOTYPE, 0x51, int ) +#define IOCTL_DEV_HAS_SERIAL_HS _MBG_IOR( IOTYPE, 0x52, int ) +#define IOCTL_DEV_HAS_SIGNAL _MBG_IOR( IOTYPE, 0x53, int ) +#define IOCTL_DEV_HAS_MOD _MBG_IOR( IOTYPE, 0x54, int ) +#define IOCTL_DEV_HAS_IRIG _MBG_IOR( IOTYPE, 0x55, int ) +#define IOCTL_DEV_HAS_REF_OFFS _MBG_IOR( IOTYPE, 0x56, int ) +#define IOCTL_DEV_HAS_OPT_FLAGS _MBG_IOR( IOTYPE, 0x57, int ) +#define IOCTL_DEV_HAS_GPS_DATA _MBG_IOR( IOTYPE, 0x58, int ) +#define IOCTL_DEV_HAS_SYNTH _MBG_IOR( IOTYPE, 0x59, int ) +#define IOCTL_DEV_HAS_GENERIC_IO _MBG_IOR( IOTYPE, 0x5A, int ) + +#define IOCTL_PCPS_GENERIC_IO _MBG_IOG( IOTYPE, 0x5B, IOCTL_GENERIC_REQ ) + +#define IOCTL_GET_SYNTH_STATE _MBG_IOR( IOTYPE, 0x5C, SYNTH_STATE ) + +#define IOCTL_GET_GPS_ALL_POUT_INFO _MBG_IOG( IOTYPE, 0x5D, IOCTL_GENERIC_REQ ) // variable size +#define IOCTL_SET_GPS_POUT_SETTINGS_IDX _MBG_IOW( IOTYPE, 0x5E, POUT_SETTINGS_IDX ) + +#define IOCTL_GET_MAPPED_MEM_ADDR _MBG_IOR( IOTYPE, 0x5F, PCPS_MAPPED_MEM ) +#define IOCTL_UNMAP_MAPPED_MEM _MBG_IOR( IOTYPE, 0x60, PCPS_MAPPED_MEM ) + +#define IOCTL_GET_PCI_ASIC_FEATURES _MBG_IOR( IOTYPE, 0x61, PCI_ASIC_FEATURES ) + +#define IOCTL_DEV_HAS_PCI_ASIC_FEATURES _MBG_IOR( IOTYPE, 0x62, int ) +#define IOCTL_DEV_HAS_PCI_ASIC_VERSION _MBG_IOR( IOTYPE, 0x63, int ) + +#define IOCTL_DEV_IS_MSF _MBG_IOR( IOTYPE, 0x64, int ) +#define IOCTL_DEV_IS_LWR _MBG_IOR( IOTYPE, 0x65, int ) +#define IOCTL_DEV_IS_WWVB _MBG_IOR( IOTYPE, 0x66, int ) + +#define IOCTL_GET_IRQ_STAT_INFO _MBG_IOR( IOTYPE, 0x67, PCPS_IRQ_STAT_INFO ) +#define IOCTL_GET_CYCLES_FREQUENCY _MBG_IOR( IOTYPE, 0x68, MBG_PC_CYCLES_FREQUENCY ) + +#define IOCTL_DEV_HAS_FAST_HR_TIMESTAMP _MBG_IOR( IOTYPE, 0x69, int ) +#define IOCTL_GET_FAST_HR_TIMESTAMP_CYCLES _MBG_IOR( IOTYPE, 0x6A, PCPS_TIME_STAMP_CYCLES ) +#define IOCTL_GET_FAST_HR_TIMESTAMP _MBG_IOR( IOTYPE, 0x6B, PCPS_TIME_STAMP ) + +#define IOCTL_DEV_HAS_GPS_TIME_SCALE _MBG_IOR( IOTYPE, 0x6C, int ) +#define IOCTL_GET_GPS_TIME_SCALE_INFO _MBG_IOR( IOTYPE, 0x6D, MBG_TIME_SCALE_INFO ) +#define IOCTL_SET_GPS_TIME_SCALE_SETTINGS _MBG_IOW( IOTYPE, 0x6E, MBG_TIME_SCALE_SETTINGS ) + +#define IOCTL_DEV_HAS_GPS_UTC_PARM _MBG_IOR( IOTYPE, 0x6F, int ) +#define IOCTL_GET_GPS_UTC_PARM _MBG_IOR( IOTYPE, 0x70, UTC ) +#define IOCTL_SET_GPS_UTC_PARM _MBG_IOW( IOTYPE, 0x71, UTC ) + +#define IOCTL_DEV_HAS_IRIG_CTRL_BITS _MBG_IOR( IOTYPE, 0x72, int ) +#define IOCTL_GET_IRIG_CTRL_BITS _MBG_IOR( IOTYPE, 0x73, MBG_IRIG_CTRL_BITS ) + +#define IOCTL_DEV_HAS_LAN_INTF _MBG_IOR( IOTYPE, 0x74, int ) +#define IOCTL_GET_LAN_IF_INFO _MBG_IOR( IOTYPE, 0x75, LAN_IF_INFO ) +#define IOCTL_GET_IP4_STATE _MBG_IOR( IOTYPE, 0x76, IP4_SETTINGS ) +#define IOCTL_GET_IP4_SETTINGS _MBG_IOR( IOTYPE, 0x77, IP4_SETTINGS ) +#define IOCTL_SET_IP4_SETTINGS _MBG_IOW( IOTYPE, 0x78, IP4_SETTINGS ) + +#define IOCTL_DEV_IS_PTP _MBG_IOR( IOTYPE, 0x79, int ) +#define IOCTL_DEV_HAS_PTP _MBG_IOR( IOTYPE, 0x7A, int ) +#define IOCTL_GET_PTP_STATE _MBG_IOR( IOTYPE, 0x7B, PTP_STATE ) +#define IOCTL_GET_PTP_CFG_INFO _MBG_IOR( IOTYPE, 0x7C, PTP_CFG_INFO ) +#define IOCTL_SET_PTP_CFG_SETTINGS _MBG_IOW( IOTYPE, 0x7D, PTP_CFG_SETTINGS ) + +#define IOCTL_DEV_HAS_IRIG_TIME _MBG_IOR( IOTYPE, 0x7E, int ) +#define IOCTL_GET_IRIG_TIME _MBG_IOR( IOTYPE, 0x7F, PCPS_IRIG_TIME ) + +#define IOCTL_GET_TIME_INFO_HRT _MBG_IOR( IOTYPE, 0x80, MBG_TIME_INFO_HRT ) +#define IOCTL_GET_TIME_INFO_TSTAMP _MBG_IOR( IOTYPE, 0x81, MBG_TIME_INFO_TSTAMP ) + +#define IOCTL_DEV_HAS_RAW_IRIG_DATA _MBG_IOR( IOTYPE, 0x82, int ) +#define IOCTL_GET_RAW_IRIG_DATA _MBG_IOR( IOTYPE, 0x83, MBG_RAW_IRIG_DATA ) + +#define IOCTL_DEV_HAS_PTP_UNICAST _MBG_IOR( IOTYPE, 0x84, int ) +#define IOCTL_PTP_UC_MASTER_CFG_LIMITS _MBG_IOR( IOTYPE, 0x85, PTP_UC_MASTER_CFG_LIMITS ) +#define IOCTL_GET_ALL_PTP_UC_MASTER_INFO _MBG_IOG( IOTYPE, 0x86, IOCTL_GENERIC_REQ ) // variable size +#define IOCTL_SET_PTP_UC_MASTER_SETTINGS_IDX _MBG_IOW( IOTYPE, 0x87, PTP_UC_MASTER_SETTINGS_IDX ) + +#define IOCTL_DEV_HAS_PZF _MBG_IOR( IOTYPE, 0x88, int ) +#define IOCTL_DEV_HAS_CORR_INFO _MBG_IOR( IOTYPE, 0x89, int ) +#define IOCTL_DEV_HAS_TR_DISTANCE _MBG_IOR( IOTYPE, 0x8A, int ) +#define IOCTL_GET_CORR_INFO _MBG_IOR( IOTYPE, 0x8B, CORR_INFO ) +#define IOCTL_GET_TR_DISTANCE _MBG_IOR( IOTYPE, 0x8C, TR_DISTANCE ) +#define IOCTL_SET_TR_DISTANCE _MBG_IOW( IOTYPE, 0x8D, TR_DISTANCE ) + +#define IOCTL_DEV_HAS_DEBUG_STATUS _MBG_IOR( IOTYPE, 0x8E, int ) +#define IOCTL_GET_DEBUG_STATUS _MBG_IOR( IOTYPE, 0x8F, MBG_DEBUG_STATUS ) + +#define IOCTL_DEV_HAS_EVT_LOG _MBG_IOR( IOTYPE, 0x90, int ) +#define IOCTL_CLR_EVT_LOG _MBG_IO( IOTYPE, 0x91 ) +#define IOCTL_GET_NUM_EVT_LOG_ENTRIES _MBG_IOR( IOTYPE, 0x92, MBG_NUM_EVT_LOG_ENTRIES ) +#define IOCTL_GET_FIRST_EVT_LOG_ENTRY _MBG_IOR( IOTYPE, 0x93, MBG_EVT_LOG_ENTRY ) +#define IOCTL_GET_NEXT_EVT_LOG_ENTRY _MBG_IOR( IOTYPE, 0x94, MBG_EVT_LOG_ENTRY ) + +#define IOCTL_DEV_IS_GNSS _MBG_IOR( IOTYPE, 0x95, int ) +#define IOCTL_GET_GNSS_MODE_INFO _MBG_IOR( IOTYPE, 0x96, MBG_GNSS_MODE_INFO ) +#define IOCTL_SET_GNSS_MODE_SETTINGS _MBG_IOW( IOTYPE, 0x97, MBG_GNSS_MODE_SETTINGS ) +#define IOCTL_GET_ALL_GNSS_SAT_INFO _MBG_IOG( IOTYPE, 0x98, IOCTL_GENERIC_REQ ) // variable size + +#define IOCTL_DEV_HAS_GPIO _MBG_IOR( IOTYPE, 0x99, int ) +#define IOCTL_GET_GPIO_CFG_LIMITS _MBG_IOR( IOTYPE, 0x9A, MBG_GPIO_CFG_LIMITS ) +#define IOCTL_GET_ALL_GPIO_INFO _MBG_IOG( IOTYPE, 0x9B, IOCTL_GENERIC_REQ ) // variable size +#define IOCTL_SET_GPIO_SETTINGS_IDX _MBG_IOW( IOTYPE, 0x9C, MBG_GPIO_SETTINGS_IDX ) + +#define IOCTL_DEV_HAS_XMR _MBG_IOR( IOTYPE, 0x9D, int ) +#define IOCTL_GET_XMR_INSTANCES _MBG_IOR( IOTYPE, 0x9E, XMULTI_REF_INSTANCES ) +#define IOCTL_GET_ALL_XMR_INFO _MBG_IOG( IOTYPE, 0x9F, IOCTL_GENERIC_REQ ) // variable size +#define IOCTL_SET_XMR_SETTINGS_IDX _MBG_IOW( IOTYPE, 0xA0, XMULTI_REF_SETTINGS_IDX ) +#define IOCTL_GET_ALL_XMR_STATUS _MBG_IOG( IOTYPE, 0xA1, IOCTL_GENERIC_REQ ) // variable size +#define IOCTL_GET_XMR_HOLDOVER_STATUS _MBG_IOR( IOTYPE, 0xA2, XMR_HOLDOVER_STATUS ) + +#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 ) + +// 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. +// Unrestricted usage may cause system malfunction !! +#define IOCTL_MBG_DBG_GET_PORT_ADDR _MBG_IOR( IOTYPE, 0xF0, uint16_t ) +#define IOCTL_MBG_DBG_SET_PORT_ADDR _MBG_IOW( IOTYPE, 0xF1, uint16_t ) +#define IOCTL_MBG_DBG_SET_BIT _MBG_IOW( IOTYPE, 0xF2, uint8_t ) +#define IOCTL_MBG_DBG_CLR_BIT _MBG_IOW( IOTYPE, 0xF3, uint8_t ) +#define IOCTL_MBG_DBG_CLR_ALL _MBG_IO( IOTYPE, 0xF4 ) + +/** @} defgroup group_ioctl_codes */ + + + +/** + * @brief An initializer for a table of IOCTL codes and associated names. + * + * This can e.g. initialize an array of ::MBG_CODE_NAME_TABLE_ENTRY elements + * and may be helpful when debugging. + * + * @see @ref IOCTL_CODES + */ +#define IOCTL_CODES_TABLE \ +{ \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_DRVR_INFO ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_DEV ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_STATUS_PORT ), \ + _mbg_cn_table_entry( IOCTL_PCPS_GENERIC_READ ), \ + _mbg_cn_table_entry( IOCTL_PCPS_GENERIC_WRITE ), \ + _mbg_cn_table_entry( IOCTL_PCPS_GENERIC_READ_GPS ), \ + _mbg_cn_table_entry( IOCTL_PCPS_GENERIC_WRITE_GPS ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_TIME ), \ + _mbg_cn_table_entry( IOCTL_SET_PCPS_TIME ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_SYNC_TIME ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_TIME_SEC_CHANGE ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_HR_TIME ), \ + _mbg_cn_table_entry( IOCTL_SET_PCPS_EVENT_TIME ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_SERIAL ), \ + _mbg_cn_table_entry( IOCTL_SET_PCPS_SERIAL ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_TZCODE ), \ + _mbg_cn_table_entry( IOCTL_SET_PCPS_TZCODE ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_TZDL ), \ + _mbg_cn_table_entry( IOCTL_SET_PCPS_TZDL ), \ + _mbg_cn_table_entry( IOCTL_GET_REF_OFFS ), \ + _mbg_cn_table_entry( IOCTL_SET_REF_OFFS ), \ + _mbg_cn_table_entry( IOCTL_GET_MBG_OPT_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_MBG_OPT_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_IRIG_RX_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_PCPS_IRIG_RX_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_PCPS_CLR_UCAP_BUFF ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_UCAP_ENTRIES ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_UCAP_EVENT ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_TZDL ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_TZDL ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_SW_REV ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_BVAR_STAT ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_TIME ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_TIME ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_PORT_PARM ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_PORT_PARM ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_ANT_INFO ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_UCAP ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_ENABLE_FLAGS ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_ENABLE_FLAGS ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_STAT_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_CMD ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_IDENT ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_POS ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_POS_XYZ ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_POS_LLA ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_ANT_CABLE_LEN ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_ANT_CABLE_LEN ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_RECEIVER_INFO ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_ALL_STR_TYPE_INFO ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_ALL_PORT_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_PORT_SETTINGS_IDX ), \ + _mbg_cn_table_entry( IOCTL_GET_PCI_ASIC_VERSION ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_TIME_CYCLES ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_HR_TIME_CYCLES ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_IRIG_TX_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_PCPS_IRIG_TX_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_GET_SYNTH ), \ + _mbg_cn_table_entry( IOCTL_SET_SYNTH ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_GPS ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_DCF ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_IRIG_RX ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_HR_TIME ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_CAB_LEN ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_TZDL ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_PCPS_TZDL ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_TZCODE ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_TZ ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_EVENT_TIME ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_RECEIVER_INFO ), \ + _mbg_cn_table_entry( IOCTL_DEV_CAN_CLR_UCAP_BUFF ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_UCAP ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_IRIG_TX ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_SERIAL_HS ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_SIGNAL ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_MOD ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_IRIG ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_REF_OFFS ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_OPT_FLAGS ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_GPS_DATA ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_SYNTH ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_GENERIC_IO ), \ + _mbg_cn_table_entry( IOCTL_PCPS_GENERIC_IO ), \ + _mbg_cn_table_entry( IOCTL_GET_SYNTH_STATE ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_ALL_POUT_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_POUT_SETTINGS_IDX ), \ + _mbg_cn_table_entry( IOCTL_GET_MAPPED_MEM_ADDR ), \ + _mbg_cn_table_entry( IOCTL_UNMAP_MAPPED_MEM ), \ + _mbg_cn_table_entry( IOCTL_GET_PCI_ASIC_FEATURES ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_PCI_ASIC_FEATURES ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_PCI_ASIC_VERSION ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_MSF ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_LWR ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_WWVB ), \ + _mbg_cn_table_entry( IOCTL_GET_IRQ_STAT_INFO ), \ + _mbg_cn_table_entry( IOCTL_GET_CYCLES_FREQUENCY ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_FAST_HR_TIMESTAMP ), \ + _mbg_cn_table_entry( IOCTL_GET_FAST_HR_TIMESTAMP_CYCLES ), \ + _mbg_cn_table_entry( IOCTL_GET_FAST_HR_TIMESTAMP ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_GPS_TIME_SCALE ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_TIME_SCALE_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_TIME_SCALE_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_GPS_UTC_PARM ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_UTC_PARM ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_UTC_PARM ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_IRIG_CTRL_BITS ), \ + _mbg_cn_table_entry( IOCTL_GET_IRIG_CTRL_BITS ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_LAN_INTF ), \ + _mbg_cn_table_entry( IOCTL_GET_LAN_IF_INFO ), \ + _mbg_cn_table_entry( IOCTL_GET_IP4_STATE ), \ + _mbg_cn_table_entry( IOCTL_GET_IP4_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_SET_IP4_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_PTP ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_PTP ), \ + _mbg_cn_table_entry( IOCTL_GET_PTP_STATE ), \ + _mbg_cn_table_entry( IOCTL_GET_PTP_CFG_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_PTP_CFG_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_IRIG_TIME ), \ + _mbg_cn_table_entry( IOCTL_GET_IRIG_TIME ), \ + _mbg_cn_table_entry( IOCTL_GET_TIME_INFO_HRT ), \ + _mbg_cn_table_entry( IOCTL_GET_TIME_INFO_TSTAMP ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_RAW_IRIG_DATA ), \ + _mbg_cn_table_entry( IOCTL_GET_RAW_IRIG_DATA ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_PTP_UNICAST ), \ + _mbg_cn_table_entry( IOCTL_PTP_UC_MASTER_CFG_LIMITS ), \ + _mbg_cn_table_entry( IOCTL_GET_ALL_PTP_UC_MASTER_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_PTP_UC_MASTER_SETTINGS_IDX ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_PZF ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_CORR_INFO ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_TR_DISTANCE ), \ + _mbg_cn_table_entry( IOCTL_GET_CORR_INFO ), \ + _mbg_cn_table_entry( IOCTL_GET_TR_DISTANCE ), \ + _mbg_cn_table_entry( IOCTL_SET_TR_DISTANCE ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_DEBUG_STATUS ), \ + _mbg_cn_table_entry( IOCTL_GET_DEBUG_STATUS ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_EVT_LOG ), \ + _mbg_cn_table_entry( IOCTL_CLR_EVT_LOG ), \ + _mbg_cn_table_entry( IOCTL_GET_NUM_EVT_LOG_ENTRIES ), \ + _mbg_cn_table_entry( IOCTL_GET_FIRST_EVT_LOG_ENTRY ), \ + _mbg_cn_table_entry( IOCTL_GET_NEXT_EVT_LOG_ENTRY ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_GNSS ), \ + _mbg_cn_table_entry( IOCTL_GET_GNSS_MODE_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_GNSS_MODE_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_GET_ALL_GNSS_SAT_INFO ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_GPIO ), \ + _mbg_cn_table_entry( IOCTL_GET_GPIO_CFG_LIMITS ), \ + _mbg_cn_table_entry( IOCTL_GET_ALL_GPIO_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_GPIO_SETTINGS_IDX ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_XMR ), \ + _mbg_cn_table_entry( IOCTL_GET_XMR_INSTANCES ), \ + _mbg_cn_table_entry( IOCTL_GET_ALL_XMR_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_XMR_SETTINGS_IDX ), \ + _mbg_cn_table_entry( IOCTL_GET_ALL_XMR_STATUS ), \ + _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_MBG_DBG_GET_PORT_ADDR ), \ + _mbg_cn_table_entry( IOCTL_MBG_DBG_SET_PORT_ADDR ), \ + _mbg_cn_table_entry( IOCTL_MBG_DBG_SET_BIT ), \ + _mbg_cn_table_entry( IOCTL_MBG_DBG_CLR_BIT ), \ + _mbg_cn_table_entry( IOCTL_MBG_DBG_CLR_ALL ), \ + \ + _mbg_cn_table_end() \ +} + + +#if !defined( _cmd_from_ioctl_code ) + #define _cmd_from_ioctl_code( _ioctl_code ) _ioctl_code +#endif + + + +/** + * @brief Privilege levels for IOCTL codes. + * + * IOCTLs can be used to do different things ranging from simply + * reading a timestamp up to forcing a GPS receiver into boot mode + * which may completely mess up the time keeping on the PC. + * + * These codes are used to determine a privilege level required + * to execute a specific IOCTL command. + * + * 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, + * Linux capabilities, Windows privileges) so this needs to be + * implemented in the OS-specific code of a driver. + * + * Implementation should be done in a way which introduces as low + * latency as possible when reading time stamps from a device. + */ +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 +}; + + +#if defined( __GNUC__ ) +// Avoid "no previous prototype" with some gcc versions. +static __mbg_inline +int ioctl_get_required_privilege( ulong ioctl_code ) __attribute__((always_inline)); +#endif + +/** + * @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 + * + * @return One of the enumerated privilege levels + * @return -1 for unknown IOCTL codes + */ +static __mbg_inline +int ioctl_get_required_privilege( ulong ioctl_code ) +{ + // To provide best maintainability the sequence of cases in ioctl_switch() + // should match the sequence of the cases here, which also makes sure + // commands requiring lowest latency are handled first. + + switch ( ioctl_code ) + { + // Commands requiring lowest latency: + case IOCTL_GET_FAST_HR_TIMESTAMP: + case IOCTL_GET_PCPS_HR_TIME: + case IOCTL_GET_FAST_HR_TIMESTAMP_CYCLES: + case IOCTL_GET_PCPS_HR_TIME_CYCLES: + case IOCTL_GET_PCPS_UCAP_EVENT: + // Other low latency commands: + case IOCTL_GET_PCPS_TIME: + case IOCTL_GET_PCPS_TIME_CYCLES: + case IOCTL_GET_PCPS_STATUS_PORT: + case IOCTL_GET_PCPS_TIME_SEC_CHANGE: + case IOCTL_GET_GPS_TIME: + case IOCTL_GET_GPS_UCAP: + case IOCTL_GET_TIME_INFO_HRT: + case IOCTL_GET_TIME_INFO_TSTAMP: + return MBG_REQ_PRIVL_NONE; + + // Commands returning public status information: + case IOCTL_GET_PCPS_DRVR_INFO: + case IOCTL_GET_PCPS_DEV: + case IOCTL_GET_PCPS_SYNC_TIME: + case IOCTL_GET_GPS_SW_REV: + case IOCTL_GET_GPS_BVAR_STAT: + case IOCTL_GET_GPS_ANT_INFO: + case IOCTL_GET_GPS_STAT_INFO: + case IOCTL_GET_GPS_IDENT: + case IOCTL_GET_GPS_RECEIVER_INFO: + case IOCTL_GET_PCI_ASIC_VERSION: + case IOCTL_GET_SYNTH_STATE: + case IOCTL_GET_PCPS_UCAP_ENTRIES: + case IOCTL_GET_PCI_ASIC_FEATURES: + case IOCTL_GET_IRQ_STAT_INFO: + case IOCTL_GET_CYCLES_FREQUENCY: + case IOCTL_GET_IRIG_CTRL_BITS: + case IOCTL_GET_IP4_STATE: + case IOCTL_GET_PTP_STATE: + case IOCTL_GET_CORR_INFO: + case IOCTL_GET_DEBUG_STATUS: + case IOCTL_GET_NUM_EVT_LOG_ENTRIES: + case IOCTL_GET_FIRST_EVT_LOG_ENTRY: + case IOCTL_GET_NEXT_EVT_LOG_ENTRY: + #if _MBG_SUPP_VAR_ACC_SIZE + case IOCTL_GET_ALL_GNSS_SAT_INFO: + #endif + return MBG_REQ_PRIVL_NONE; + + // Commands returning device capabilities and features: + case IOCTL_DEV_IS_GPS: + case IOCTL_DEV_IS_DCF: + case IOCTL_DEV_IS_MSF: + case IOCTL_DEV_IS_WWVB: + case IOCTL_DEV_IS_LWR: + case IOCTL_DEV_IS_GNSS: + case IOCTL_DEV_IS_IRIG_RX: + case IOCTL_DEV_HAS_HR_TIME: + case IOCTL_DEV_HAS_CAB_LEN: + case IOCTL_DEV_HAS_TZDL: + case IOCTL_DEV_HAS_PCPS_TZDL: + case IOCTL_DEV_HAS_TZCODE: + case IOCTL_DEV_HAS_TZ: + case IOCTL_DEV_HAS_EVENT_TIME: + case IOCTL_DEV_HAS_RECEIVER_INFO: + case IOCTL_DEV_CAN_CLR_UCAP_BUFF: + case IOCTL_DEV_HAS_UCAP: + case IOCTL_DEV_HAS_IRIG_TX: + case IOCTL_DEV_HAS_SERIAL_HS: + case IOCTL_DEV_HAS_SIGNAL: + case IOCTL_DEV_HAS_MOD: + case IOCTL_DEV_HAS_IRIG: + case IOCTL_DEV_HAS_REF_OFFS: + case IOCTL_DEV_HAS_OPT_FLAGS: + case IOCTL_DEV_HAS_GPS_DATA: + case IOCTL_DEV_HAS_SYNTH: + case IOCTL_DEV_HAS_GENERIC_IO: + case IOCTL_DEV_HAS_PCI_ASIC_FEATURES: + case IOCTL_DEV_HAS_PCI_ASIC_VERSION: + case IOCTL_DEV_HAS_FAST_HR_TIMESTAMP: + case IOCTL_DEV_HAS_GPS_TIME_SCALE: + case IOCTL_DEV_HAS_GPS_UTC_PARM: + case IOCTL_DEV_HAS_IRIG_CTRL_BITS: + case IOCTL_DEV_HAS_LAN_INTF: + case IOCTL_DEV_IS_PTP: + case IOCTL_DEV_HAS_PTP: + case IOCTL_DEV_HAS_IRIG_TIME: + case IOCTL_DEV_HAS_RAW_IRIG_DATA: + case IOCTL_DEV_HAS_PTP_UNICAST: + case IOCTL_DEV_HAS_PZF: + case IOCTL_DEV_HAS_CORR_INFO: + case IOCTL_DEV_HAS_TR_DISTANCE: + case IOCTL_DEV_HAS_DEBUG_STATUS: + case IOCTL_DEV_HAS_EVT_LOG: + case IOCTL_DEV_HAS_GPIO: + case IOCTL_DEV_HAS_XMR: + case IOCTL_CHK_DEV_FEAT: + return MBG_REQ_PRIVL_NONE; + + // The next codes are somewhat special since they change something + // on the board 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: + return MBG_REQ_PRIVL_NONE; + + // Status information which may not be available for everybody: + case IOCTL_GET_GPS_POS: + return MBG_REQ_PRIVL_EXT_STATUS; + + // Reading device configuration: + case IOCTL_GET_PCPS_SERIAL: + case IOCTL_GET_PCPS_TZCODE: + case IOCTL_GET_PCPS_TZDL: + case IOCTL_GET_REF_OFFS: + case IOCTL_GET_MBG_OPT_INFO: + case IOCTL_GET_PCPS_IRIG_RX_INFO: + case IOCTL_GET_GPS_TZDL: + case IOCTL_GET_GPS_PORT_PARM: + case IOCTL_GET_GPS_ENABLE_FLAGS: + case IOCTL_GET_GPS_ANT_CABLE_LEN: + case IOCTL_GET_PCPS_IRIG_TX_INFO: + case IOCTL_GET_SYNTH: + case IOCTL_GET_GPS_TIME_SCALE_INFO: + case IOCTL_GET_GPS_UTC_PARM: + case IOCTL_GET_LAN_IF_INFO: + case IOCTL_GET_IP4_SETTINGS: + case IOCTL_GET_PTP_CFG_INFO: + case IOCTL_GET_IRIG_TIME: + case IOCTL_GET_RAW_IRIG_DATA: + case IOCTL_PTP_UC_MASTER_CFG_LIMITS: + case IOCTL_GET_TR_DISTANCE: + // generic read functions + case IOCTL_PCPS_GENERIC_READ: + case IOCTL_PCPS_GENERIC_READ_GPS: + #if _MBG_SUPP_VAR_ACC_SIZE + // These codes are only supported on target systems where a variable size of + // the IOCTL buffer can be specified in the IOCTL call. On other systems the + // generic IOCTL functions are used instead. + case IOCTL_GET_GPS_ALL_STR_TYPE_INFO: + case IOCTL_GET_GPS_ALL_PORT_INFO: + case IOCTL_GET_GPS_ALL_POUT_INFO: + case IOCTL_GET_ALL_PTP_UC_MASTER_INFO: + case IOCTL_GET_ALL_GPIO_INFO: + case IOCTL_GET_ALL_GPIO_STATUS: + case IOCTL_GET_ALL_XMR_STATUS: + case IOCTL_GET_ALL_XMR_INFO: + #endif + case IOCTL_GET_GNSS_MODE_INFO: + case IOCTL_GET_GPIO_CFG_LIMITS: + case IOCTL_GET_XMR_INSTANCES: + case IOCTL_GET_XMR_HOLDOVER_STATUS: + return MBG_REQ_PRIVL_CFG_READ; + + // Writing device configuration: + case IOCTL_SET_PCPS_SERIAL: + case IOCTL_SET_PCPS_TZCODE: + case IOCTL_SET_PCPS_TZDL: + case IOCTL_SET_REF_OFFS: + case IOCTL_SET_MBG_OPT_SETTINGS: + case IOCTL_SET_PCPS_IRIG_RX_SETTINGS: + case IOCTL_SET_GPS_TZDL: + case IOCTL_SET_GPS_PORT_PARM: + case IOCTL_SET_GPS_ENABLE_FLAGS: + case IOCTL_SET_GPS_ANT_CABLE_LEN: + case IOCTL_SET_GPS_PORT_SETTINGS_IDX: + case IOCTL_SET_PCPS_IRIG_TX_SETTINGS: + case IOCTL_SET_SYNTH: + case IOCTL_SET_GPS_POUT_SETTINGS_IDX: + case IOCTL_SET_IP4_SETTINGS: + case IOCTL_SET_PTP_CFG_SETTINGS: + case IOCTL_SET_PTP_UC_MASTER_SETTINGS_IDX: + case IOCTL_SET_TR_DISTANCE: + case IOCTL_SET_GNSS_MODE_SETTINGS: + case IOCTL_SET_GPIO_SETTINGS_IDX: + return MBG_REQ_PRIVL_CFG_WRITE; + + // Operations which may severely affect system operation: + case IOCTL_SET_PCPS_TIME: + case IOCTL_SET_GPS_TIME: + case IOCTL_SET_GPS_POS_XYZ: + case IOCTL_SET_GPS_POS_LLA: + case IOCTL_SET_GPS_TIME_SCALE_SETTINGS: + case IOCTL_SET_GPS_UTC_PARM: + case IOCTL_SET_GPS_CMD: + case IOCTL_SET_XMR_SETTINGS_IDX: + // generic write operations can do anything + case IOCTL_PCPS_GENERIC_WRITE: + case IOCTL_PCPS_GENERIC_WRITE_GPS: + case IOCTL_PCPS_GENERIC_IO: + return MBG_REQ_PRIVL_SYSTEM; + + // The next codes are somewhat special and normally + // not used by the driver software: + case IOCTL_GET_MAPPED_MEM_ADDR: + case IOCTL_UNMAP_MAPPED_MEM: + return MBG_REQ_PRIVL_SYSTEM; + + #if USE_DEBUG_PORT + // The codes below are used for debugging only. + // Unrestricted usage may cause system malfunction !! + case IOCTL_MBG_DBG_GET_PORT_ADDR: + case IOCTL_MBG_DBG_SET_PORT_ADDR: + case IOCTL_MBG_DBG_SET_BIT: + case IOCTL_MBG_DBG_CLR_BIT: + case IOCTL_MBG_DBG_CLR_ALL: + return MBG_REQ_PRIVL_SYSTEM; + #endif + + } // switch + + return -1; // unsupported code, should always be denied + +} // ioctl_get_required_privilege + + + +/* ----- function prototypes begin ----- */ + +/* 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 ----- */ + +#ifdef __cplusplus +} +#endif + + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _MBGIOCTL_H */ diff --git a/mbglib/common/mbgklist.h b/mbglib/common/mbgklist.h new file mode 100644 index 0000000..16f3440 --- /dev/null +++ b/mbglib/common/mbgklist.h @@ -0,0 +1,326 @@ + +/************************************************************************** + * + * $Id: mbgklist.h 1.4 2018/09/13 05:27:28Z thomas-b REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Userspace implementation of Linux Kernel's list.h + * + * ----------------------------------------------------------------------- + * $Log: mbgklist.h $ + * Revision 1.4 2018/09/13 05:27:28Z 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. + * Check if 'typeof' is supported based on the type of compiler. + * Reformatted code to conform to standard header file format. + * Updated function prototypes. + * Revision 1.2 2015/10/06 07:08:45 philipp + * Added functions to loop containers of list entries + * Revision 1.1 2015/09/09 10:42:27 martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _MBGKLIST_H +#define _MBGKLIST_H + +/* Other headers to be included */ + +#include <mbg_cof.h> + + +#ifdef _MBGKLIST + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + + +#define MBG_KLIST_INIT(name) { &(name), &(name) } + +#define MBG_KLIST_DECLARE(name) \ + struct mbg_klist_head name = MBG_KLIST_INIT(name) + +#define mbg_klist_for_each(head, pos) \ + for (pos = (head)->next; pos != (head); pos = pos->next) + +#define mbg_klist_for_each_safe(head, pos, n) \ + for (pos = (head)->next, n = (pos)->next; \ + pos != (head); \ + pos = n, n = pos->next) + +#define mbg_klist_for_each_rev(head, pos) \ + for (pos = (head)->prev; pos != (head); pos = pos->prev) + +#define mbg_klist_for_each_rev_safe(head, pos, n) \ + for (pos = (head)->prev, n = (pos)->prev; \ + pos != (head); \ + pos = n, n = pos->prev) + +#define mbg_klist_nth_item(head, pos, n) \ + do { \ + unsigned i; \ + for (pos = (head)->next, i = 0; i < n; pos = pos->next, ++i); \ + } while ( 0 ) + +#define mbg_klist_entry(ptr, type, member) \ + mbg_container_of(ptr, type, member) + +#define mbg_klist_first_entry(ptr, type, member) \ + mbg_klist_entry((ptr)->next, type, member) + +#define mbg_klist_last_entry(ptr, type, member) \ + mbg_klist_entry((ptr)->prev, type, member) + + + +#if defined( __GNUC__ ) || defined( __clang__ ) // "typeof" supported + +#define mbg_klist_next_entry(pos, member) \ + mbg_klist_entry((pos)->member.next, typeof(*pos), member) + +#define mbg_klist_prev_entry(pos, member) \ + mbg_klist_entry((pos)->member.prev, typeof(*pos), member) + +#define mbg_klist_for_each_entry(head, pos, member) \ + for (pos = mbg_klist_first_entry(head, typeof(*pos), member); \ + &pos->member != (head); \ + pos = mbg_klist_next_entry(pos, member)) + +#define mbg_klist_for_each_entry_rev(head, pos, member) \ + for (pos = mbg_klist_last_entry(head, typeof(*pos), member); \ + &pos->member != (head); \ + pos = mbg_klist_prev_entry(pos, member)) + +#define mbg_klist_for_each_entry_safe(head, pos, n, member) \ + for (pos = mbg_klist_first_entry(head, typeof(*pos), member), \ + n = mbg_klist_next_entry(pos, member); \ + &pos->member != (head); \ + pos = n, n = mbg_klist_next_entry(pos, member)) + +#define mbg_klist_for_each_entry_rev_safe(head, pos, n, member) \ + for (pos = mbg_klist_last_entry(head, typeof(*pos), member), \ + n = mbg_klist_prev_entry(pos, member); \ + &pos->member != (head); \ + pos = n, n = mbg_klist_prev_entry(pos, member)) + +#endif + + + +struct mbg_klist_head +{ + struct mbg_klist_head *prev; + struct mbg_klist_head *next; +}; + + + +static __mbg_inline +void mbg_klist_init( struct mbg_klist_head *head ) +{ + head->next = head; + head->prev = head; +} + + +static __mbg_inline +void __mbg_klist_add_item( struct mbg_klist_head *item, struct mbg_klist_head *prev, struct mbg_klist_head *next ) +{ + next->prev = item; + item->next = next; + item->prev = prev; + prev->next = item; +} + + +static __mbg_inline +void mbg_klist_prepend_item( struct mbg_klist_head *head, struct mbg_klist_head *item ) +{ + __mbg_klist_add_item( item, head, head->next ); +} + + +static __mbg_inline +void mbg_klist_append_item( struct mbg_klist_head *head, struct mbg_klist_head *item ) +{ + __mbg_klist_add_item( item, head->prev, head ); +} + + +static __mbg_inline +void __mbg_klist_delete_item( struct mbg_klist_head *prev, struct mbg_klist_head *next ) +{ + next->prev = prev; + prev->next = next; +} + + +static __mbg_inline +void mbg_klist_delete_item( struct mbg_klist_head *item ) +{ + __mbg_klist_delete_item( item->prev, item->next ); +} + + +static __mbg_inline +void mbg_klist_delete_item_init( struct mbg_klist_head *item ) +{ + __mbg_klist_delete_item( item->prev, item->next ); + mbg_klist_init( item ); +} + + +static __mbg_inline +void mbg_klist_replace_item( struct mbg_klist_head *old, struct mbg_klist_head *item ) +{ + item->next = old->next; + item->next->prev = item; + item->prev = old->prev; + item->prev->next = item; +} + + +static __mbg_inline +void mbg_klist_replace_item_init( struct mbg_klist_head *old, struct mbg_klist_head *item ) +{ + mbg_klist_replace_item( old, item ); + mbg_klist_init( item ); +} + + +static __mbg_inline +void mbg_klist_move_prepend_item( struct mbg_klist_head *head, struct mbg_klist_head *item ) +{ + mbg_klist_delete_item( item ); + mbg_klist_prepend_item( head, item ); +} + + +static __mbg_inline +void mbg_klist_move_append_item( struct mbg_klist_head *head, struct mbg_klist_head *item ) +{ + mbg_klist_delete_item( item ); + mbg_klist_append_item( head, item ); +} + + +static __mbg_inline +int mbg_klist_is_first( const struct mbg_klist_head *head, const struct mbg_klist_head *item ) +{ + return ( ( item->prev == head ) ? 1 : 0 ); +} + + +static __mbg_inline +int mbg_klist_is_last( const struct mbg_klist_head *head, const struct mbg_klist_head *item ) +{ + return ( ( item->next == head ) ? 1 : 0 ); +} + + +static __mbg_inline +int mbg_klist_is_empty( const struct mbg_klist_head *head ) +{ + return ( ( head->next == head ) ? 1 : 0 ); +} + + +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; + + first->prev = prev; + prev->next = first; + + last->next = next; + next->prev = last; +} + + +static __mbg_inline +void mbg_klist_prepend_list( struct mbg_klist_head *head, const struct mbg_klist_head *list ) +{ + if ( !mbg_klist_is_empty( list ) ) + __mbg_klist_add_list( list, head, head->next ); +} + + +static __mbg_inline +void mbg_klist_append_list( struct mbg_klist_head *head, const struct mbg_klist_head *list ) +{ + if ( !mbg_klist_is_empty( list ) ) + __mbg_klist_add_list( list, head->prev, head ); +} + + +static __mbg_inline +void mbg_klist_prepend_list_init( struct mbg_klist_head *head, struct mbg_klist_head *list ) +{ + if ( !mbg_klist_is_empty( list ) ) + { + __mbg_klist_add_list( list, head, head->next ); + mbg_klist_init( list ); + } +} + + +static __mbg_inline +void mbg_klist_append_list_init( struct mbg_klist_head *head, struct mbg_klist_head *list ) +{ + if ( !mbg_klist_is_empty( list ) ) + { + __mbg_klist_add_list( list, head->prev, head ); + mbg_klist_init( list ); + } +} + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + /** + * @brief Sort a list + * + * @param[in] priv Private data, opaque to ::mbg_klist_sort, passed to @p cmp + * @param[in] head The list to sort + * @param[in] cmp The elements comparison function + * + * This function implements "merge sort", which has O(nlog(n)) + * complexity. + * + * The comparison function @p cmp must return a negative value if a + * should sort before b, and a positive value if a should sort after + * b. If a and b are equivalent, and their original relative + * ordering is to be preserved, cmp must return 0. + */ + void mbg_klist_sort( void *priv, struct mbg_klist_head *head, int (*cmp)( void *priv, struct mbg_klist_head *a, struct mbg_klist_head *b ) ) ; + + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _MBGKLIST_H */ diff --git a/mbglib/common/mbgmktm.c b/mbglib/common/mbgmktm.c new file mode 100644 index 0000000..afdb195 --- /dev/null +++ b/mbglib/common/mbgmktm.c @@ -0,0 +1,144 @@ + +/************************************************************************** + * + * $Id: mbgmktm.c 1.2 2017/07/05 10:00:29Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Function to convert broken down time to Unix time (seconds since 1970) + * + * ----------------------------------------------------------------------- + * $Log: mbgmktm.c $ + * Revision 1.2 2017/07/05 10:00:29Z 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(). + * Added some doxygen comments. + * Revision 1.1 2006/08/22 08:57:15 martin + * Former function totalsec() moved here from pcpsmktm.c. + * + **************************************************************************/ + +#define _MBGMKTM + #include <mbgmktm.h> +#undef _MBGMKTM + +#include <assert.h> + + +static const char Days[12] = +{ + 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 +}; + +static int YDays[12] = +{ + 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334 +}; + + + +/*HDR*/ +/** + * @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 + */ +time_t mbg_mktime( int year, int month, int day, + int hour, int min, int sec ) +{ + int leaps; + long days; + time_t secs; + + // 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 ) + 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; + + min += sec / 60; + sec %= 60; /* Seconds are normalized */ + hour += min / 60; + min %= 60; /* Minutes are normalized */ + day += hour / 24; + hour %= 24; /* Hours are normalized */ + + year += month / 12; /* Normalize month (not necessarily final) */ + month %= 12; + + while ( day >= Days[month] ) + { + if ( !( year & 3 ) && ( month == 1 ) ) + { + if (day > 28) + { + day -= 29; + month++; + } + else + break; + } + else + { + day -= Days[month]; + month++; + } + + year += month / 12; /* Normalize month */ + month %= 12; + } + + year -= 70; + leaps = ( year + 2 ) / 4; + + 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; + + return secs; + + +fail: + return (time_t) -1; + +} // mbg_mktime + diff --git a/mbglib/common/mbgmktm.h b/mbglib/common/mbgmktm.h new file mode 100644 index 0000000..0120622 --- /dev/null +++ b/mbglib/common/mbgmktm.h @@ -0,0 +1,79 @@ + +/************************************************************************** + * + * $Id: mbgmktm.h 1.2 2017/07/05 10:02:42Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for mbgmktm.c. + * + * ----------------------------------------------------------------------- + * $Log: mbgmktm.h $ + * Revision 1.2 2017/07/05 10:02:42Z martin + * Include time.h. + * Updated function prototypes. + * Revision 1.1 2006/08/22 08:57:15 martin + * Former function totalsec() moved here from pcpsmktm.c. + * + **************************************************************************/ + +#ifndef _MBGMKTM_H +#define _MBGMKTM_H + + +/* Other headers to be included */ + +#include <time.h> + + +#ifdef _MBGMKTM + #define _ext +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + +/* ----- 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 + */ + time_t mbg_mktime( int year, int month, int day, int hour, int min, int sec ) ; + + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + +/* End of header body */ + +#undef _ext + +#endif /* _MBGMKTM_H */ diff --git a/mbglib/common/mbgmutex.h b/mbglib/common/mbgmutex.h index 86fd058..7a39075 100644 --- a/mbglib/common/mbgmutex.h +++ b/mbglib/common/mbgmutex.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgmutex.h 1.2 2012/03/08 12:19:01Z martin REL_M $ + * $Id: mbgmutex.h 1.5 2018/07/16 14:18:05Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,6 +11,13 @@ * * ----------------------------------------------------------------------- * $Log: mbgmutex.h $ + * Revision 1.5 2018/07/16 14:18:05Z 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. * 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. @@ -40,21 +47,25 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + #if defined( MBG_TGT_KERNEL ) // definitions used in kernel space #if defined( MBG_TGT_WIN32 ) // Windows kernel space typedef KSPIN_LOCK MBG_SPINLOCK; - #define _mbg_spin_lock_init( _spl ) KeInitializeSpinLock( _spl ) + #define _mbg_spin_lock_init( _spl, _n ) KeInitializeSpinLock( _spl ) // _mbg_spin_lock_destroy is not supported - #define _mbg_spin_lock_acquire( _spl ) KeAcquireSpinLockAtDpcLevel( _spl ) - #define _mbg_spin_lock_release( _spl ) KeReleaseSpinLockFromDpcLevel( _spl ) + #define _mbg_spin_lock_acquire( _spl ) KeAcquireSpinLock( _spl, &OldIrql ) + #define _mbg_spin_lock_release( _spl ) KeReleaseSpinLock( _spl, OldIrql ) #define _MBG_SPINLOCK_DEFINED 1 typedef FAST_MUTEX MBG_MUTEX; - #define _mbg_mutex_init( _pmtx ) ExInitializeFastMutex( _pmtx ) + #define _mbg_mutex_init( _pmtx, _n ) ExInitializeFastMutex( _pmtx ) // _mbg_mutex_destroy( _pmtx ) is not supported #define _mbg_mutex_acquire( _pmtx ) ExAcquireFastMutex( _pmtx ) #define _mbg_mutex_release( _pmtx ) ExReleaseFastMutex( _pmtx ) @@ -73,7 +84,7 @@ #endif typedef spinlock_t MBG_SPINLOCK; - #define _mbg_spin_lock_init( _spl ) spin_lock_init( _spl ) + #define _mbg_spin_lock_init( _spl, _n ) spin_lock_init( _spl ) // _mbg_spin_lock_destroy is not supported #define _mbg_spin_lock_acquire( _spl ) spin_lock( _spl ) #define _mbg_spin_lock_release( _spl ) spin_unlock( _spl ) @@ -82,7 +93,7 @@ typedef struct semaphore MBG_MUTEX; - #define _mbg_mutex_init( _pmtx ) sema_init( _pmtx, 1 ) + #define _mbg_mutex_init( _pmtx, _n ) sema_init( _pmtx, 1 ) // _mbg_mutex_destroy( _pmtx ) is not supported #define _mbg_mutex_acquire( _pmtx ) down_interruptible( _pmtx ) #define _mbg_mutex_release( _pmtx ) up( _pmtx ) @@ -95,7 +106,7 @@ #include <sys/mutex.h> typedef struct mtx MBG_SPINLOCK; - #define _mbg_spin_lock_init( _spl ) mtx_init( _spl, "mbg_spin_lock", NULL, MTX_SPIN ) + #define _mbg_spin_lock_init( _spl, _n ) mtx_init( _spl, _n, NULL, MTX_SPIN ) #define _mbg_spin_lock_destroy( _spl ) mtx_destroy( _spl ) #define _mbg_spin_lock_acquire( _spl ) mtx_lock_spin( _spl ) #define _mbg_spin_lock_release( _spl ) mtx_unlock_spin( _spl ) @@ -104,7 +115,7 @@ typedef struct mtx MBG_MUTEX; - #define _mbg_mutex_init( _pmtx ) mtx_init( _pmtx, "mbg_mutex", NULL, MTX_DEF ) + #define _mbg_mutex_init( _pmtx, _n ) mtx_init( _pmtx, _n, NULL, MTX_DEF ) #define _mbg_mutex_destroy( _pmtx ) mtx_destroy( _pmtx ) #define _mbg_mutex_acquire( _pmtx ) mtx_lock( _pmtx ) #define _mbg_mutex_release( _pmtx ) mtx_unlock( _pmtx ) @@ -119,7 +130,7 @@ // For earlier NetBSD versions see 'man 9 lockinit'. typedef kmutex_t MBG_SPINLOCK; - #define _mbg_spin_lock_init( _spl ) mutex_init( _spl, MUTEX_DEFAULT, IPL_HIGH ) + #define _mbg_spin_lock_init( _spl, _n ) mutex_init( _spl, MUTEX_DEFAULT, IPL_HIGH ) #define _mbg_spin_lock_destroy( _spl ) mutex_destroy( _spl ) #define _mbg_spin_lock_acquire( _spl ) mutex_spin_enter( _spl ) #define _mbg_spin_lock_release( _spl ) mutex_spin_exit( _spl ) @@ -128,7 +139,7 @@ typedef kmutex_t MBG_MUTEX; - #define _mbg_mutex_init( _pmtx ) mutex_init( _pmtx, MUTEX_DEFAULT, IPL_NONE ) + #define _mbg_mutex_init( _pmtx, _n ) mutex_init( _pmtx, MUTEX_DEFAULT, IPL_NONE ) #define _mbg_mutex_destroy( _spl ) mutex_destroy( _spl ) #define _mbg_mutex_acquire( _pmtx ) mutex_enter( _pmtx ) #define _mbg_mutex_release( _pmtx ) mutex_exit( _pmtx ) @@ -141,12 +152,10 @@ #if defined( MBG_TGT_WIN32 ) // Windows user space - #include <windows.h> - // definitions used with mutexes typedef HANDLE MBG_MUTEX; - #define _mbg_mutex_init( _pm ) *(_pm) = CreateMutex( NULL, FALSE, NULL ) - #define _mbg_mutex_destroy( _pm ) CloseHandle( *(_pm) ); *(_pm) = INVALID_HANDLE_VALUE + #define _mbg_mutex_init( _pm, _n ) *(_pm) = CreateMutex( NULL, FALSE, NULL ) + #define _mbg_mutex_destroy( _pm ) do { CloseHandle( *(_pm) ); *(_pm) = INVALID_HANDLE_VALUE; } while ( 0 ) #define _mbg_mutex_acquire( _pm ) WaitForSingleObject( *(_pm), INFINITE ) #define _mbg_mutex_release( _pm ) ReleaseMutex( *(_pm) ) @@ -154,14 +163,14 @@ // definitions used with critical sections typedef CRITICAL_SECTION MBG_CRIT_SECT; - #define _mbg_crit_sect_init( _pcs ) InitializeCriticalSection( (_pcs) ) + #define _mbg_crit_sect_init( _pcs, _n ) InitializeCriticalSection( (_pcs) ) #define _mbg_crit_sect_destroy( _pcs ) DeleteCriticalSection( (_pcs) ) #define _mbg_crit_sect_enter( _pcs ) EnterCriticalSection( (_pcs) ) #define _mbg_crit_sect_leave( _pcs ) LeaveCriticalSection( (_pcs) ) #define _MBG_CRIT_SECT_DEFINED 1 - #elif defined( MBG_TGT_UNIX ) // Unix user space use pthread library + #elif defined( MBG_TGT_POSIX ) // Unix user space use pthread library #include <pthread.h> @@ -170,7 +179,7 @@ // PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP /* Recursive */ // PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP /* Errorcheck */ typedef pthread_mutex_t MBG_MUTEX; - #define _mbg_mutex_init( _pm ) pthread_mutex_init( (_pm), NULL ) + #define _mbg_mutex_init( _pm, _n ) pthread_mutex_init( (_pm), NULL ) #define _mbg_mutex_destroy( _pm ) pthread_mutex_destroy( (_pm) ) #define _mbg_mutex_acquire( _pm ) pthread_mutex_lock( (_pm) ) #define _mbg_mutex_release( _pm ) pthread_mutex_unlock( (_pm) ) @@ -192,10 +201,10 @@ #if !defined( _MBG_SPINLOCK_DEFINED ) - #define _mbg_spin_lock_init( _spl ) _nop_macro_fnc() - // _mbg_spin_lock_destroy is not supported - #define _mbg_spin_lock_acquire( _spl ) _nop_macro_fnc() - #define _mbg_spin_lock_release( _spl ) _nop_macro_fnc() + #define _mbg_spin_lock_init( _spl, _n ) _nop_macro_fnc() + // _mbg_spin_lock_destroy is not supported + #define _mbg_spin_lock_acquire( _spl ) _nop_macro_fnc() + #define _mbg_spin_lock_release( _spl ) _nop_macro_fnc() #endif @@ -206,7 +215,7 @@ typedef MBG_CRIT_SECT MBG_MUTEX; - #define _mbg_mutex_init( _pm ) _nop_macro_fnc() + #define _mbg_mutex_init( _pm, _n ) _nop_macro_fnc() // _mbg_mutex_destroy( _pmtx ) is not supported #define _mbg_mutex_acquire( _pm ) _nop_macro_fnc() #define _mbg_mutex_release( _pm ) _nop_macro_fnc() @@ -231,13 +240,6 @@ #endif - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/mbgpccyc.h b/mbglib/common/mbgpccyc.h index 71d1235..14add0a 100644 --- a/mbglib/common/mbgpccyc.h +++ b/mbglib/common/mbgpccyc.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgpccyc.h 1.2 2012/03/12 13:45:57Z martin REL_M $ + * $Id: mbgpccyc.h 1.7 2017/05/10 15:21:41Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,17 @@ * * ----------------------------------------------------------------------- * $Log: mbgpccyc.h $ - * Revision 1.2 2012/03/12 13:45:57Z martin + * Revision 1.7 2017/05/10 15:21:41Z martin + * Tiny cleanup. + * Revision 1.6 2016/08/09 16:01:10 martin + * Syntax fix. + * Revision 1.5 2016/02/17 16:04:18 martin + * Include header file missing for FreeBSD. + * Revision 1.4 2015/10/19 09:16:45 martin + * Fixed some spelling. + * Revision 1.3 2014/10/08 13:10:14 martin + * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. + * Revision 1.2 2012/03/12 13:45:57 martin * Added cycles support for Linux/IA64, FreeBSD and NetBSD * in kernel space. * Use get_cycles() in Linux kernel mode if no special cycles support @@ -39,6 +49,7 @@ #if defined( MBG_TGT_FREEBSD ) #if defined( MBG_TGT_KERNEL ) #if defined( MBG_ARCH_X86 ) + #include <sys/time.h> #include <machine/clock.h> /* for symbol 'tsc_freq' */ #endif #endif @@ -61,13 +72,17 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + /** * @brief Generic types to hold PC cycle counter values. * * The cycle counter value is usually derived from the PC CPU's TSC or some other * timer hardware on the mainboard. */ -#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_UNIX ) +#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX ) typedef int64_t MBG_PC_CYCLES; typedef uint64_t MBG_PC_CYCLES_FREQUENCY; @@ -104,7 +119,7 @@ // which would copy the output regs edx:eax as a 64 bit // number to a variable x. // - // The "=A" expression should implicitely tell the compiler + // The "=A" expression should implicitly tell the compiler // the edx and eax registers have been clobbered. However, // this does not seem to work properly at least with gcc 4.1.2 // shipped with Centos 5. @@ -116,14 +131,14 @@ // assumes edx is unchanged, which may yield faulty results // or even lead to segmentation faults. // - // A possible workaround could be to mark edx explicitely as + // A possible workaround could be to mark edx explicitly as // being clobbered in the asm inline code, but unfortunately // other gcc versions report an error if a register which is - // implicitely (by "=A") known to be clobbered is also listed - // explicitely to be clobbered. + // implicitly (by "=A") known to be clobbered is also listed + // explicitly to be clobbered. // // So the code below is a workaround which tells the compiler - // implicitely that the eax ("=a") and edx ("=d") registers + // implicitly that the eax ("=a") and edx ("=d") registers // are being used and thus clobbered. union @@ -195,7 +210,7 @@ void mbg_get_pc_cycles( MBG_PC_CYCLES *p ) #define MBG_PC_CYCLES_SUPPORTED 1 - #elif defined( MBG_TGT_NETBSD ) && defined ( MBG_TGT_KERNEL ) + #elif defined( MBG_TGT_NETBSD ) && defined( MBG_TGT_KERNEL ) *p = cpu_counter(); //##++ or cpu_counter_serializing() @@ -278,12 +293,6 @@ MBG_PC_CYCLES mbg_delta_pc_cycles( const MBG_PC_CYCLES *p1, const MBG_PC_CYCLES -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/mbgsystm.h b/mbglib/common/mbgsystm.h new file mode 100644 index 0000000..7d3fe54 --- /dev/null +++ b/mbglib/common/mbgsystm.h @@ -0,0 +1,498 @@ + +/************************************************************************** + * + * $Id: mbgsystm.h 1.4 2018/07/16 12:32:58Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Generic functions and definitions to deal with the computer's + * system time, and prototypes for mbgsystm.c. + * + * ----------------------------------------------------------------------- + * $Log: mbgsystm.h $ + * Revision 1.4 2018/07/16 12:32:58Z martin + * Fixed do_div() for 32 bit ARM Linux kernel. + * Include another header file on NetBSD. + * Revision 1.3 2017/07/26 14:26:17 martin + * Fixed build for NetBSD. + * Revision 1.2 2017/07/04 12:26:57 martin + * More detailed control of inclusion of other headers. + * Made mbg_delta_sys_time_ms() as inline function here. + * Updated function prototypes. + * Cleanup. + * Revision 1.1 2015/09/15 13:21:00Z martin + * Initial revision. + * Moved existing code from different modules here. + * + **************************************************************************/ + +#ifndef _MBGSYSTM_H +#define _MBGSYSTM_H + + +/* Other headers to be included */ + +#include <mbg_tgt.h> +#include <words.h> + +#if defined( MBG_TGT_POSIX ) + + #if defined( MBG_TGT_KERNEL ) + + #if defined( MBG_TGT_LINUX ) + + #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 + #include <linux/wait.h> + #include <linux/sched.h> + #endif + + // We need the prototype for getnstimeofday(). In newer kernels + // (e.g. 4.x) this is available via linux/ktime.h, which in turn + // includes linux/timekeeping.h, which declares the prototype. + #if LINUX_KERNEL_HAS_KTIME_H + #include <linux/ktime.h> + #endif + + // In older kernel versions the prototype for getnstimeofday() + // is declared in linux/time.h, so we include that one anyway. + #include <linux/time.h> + + #include <linux/delay.h> + #include <linux/jiffies.h> + + #elif defined( MBG_TGT_BSD ) + + #if defined( MBG_TGT_FREEBSD ) + #include <sys/libkern.h> + #endif + + #if defined( MBG_TGT_NETBSD ) + #include <sys/param.h> // mstohz + #include <sys/kernel.h> // hz + #include <sys/proc.h> // kpause + #endif + + #include <sys/time.h> + + #endif + + #else // POSIX user space + + #include <time.h> + + #if defined( MBG_TGT_LINUX ) + #include <sys/sysinfo.h> + #endif + + #endif + +#elif defined( MBG_TGT_WIN32 ) + + #if defined( MBG_TGT_KERNEL ) + #include <mbg_w32.h> + #endif + + #include <mbgtime.h> + +#elif defined( MBG_TGT_DOS ) + + #include <dos.h> + +#endif + + +#ifdef _MBGSYSTM + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + +/** + Define generic types to hold PC cycle counter values and system timestamps. + The generic types are defined using native types used by the target operating + systems. + + The cycle counter value is usually derived from the PC CPU's TSC or some other + timer hardware on the mainboard. + */ +#if defined( MBG_TGT_POSIX ) + + typedef NANO_TIME_64 MBG_SYS_TIME; + typedef int64_t MBG_SYS_UPTIME; // [s] + +#elif defined( MBG_TGT_WIN32 ) + + typedef LARGE_INTEGER MBG_SYS_TIME; + typedef int64_t MBG_SYS_UPTIME; // [s] + +#elif defined( MBG_TGT_OS2 ) + + typedef uint32_t MBG_SYS_TIME; //## dummy + typedef long MBG_SYS_UPTIME; //## dummy + +#elif defined( MBG_TGT_DOS ) + + typedef uint32_t MBG_SYS_TIME; //## dummy + typedef long MBG_SYS_UPTIME; //## dummy + +#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() + + + +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_LINUX ) // Linux kernel space + + #if ( LINUX_KERNEL_HAS_GETNSTIMEOFDAY ) + { + // getnstimeofday() supported + struct timespec ts; + + getnstimeofday( &ts ); + + p->secs = ts.tv_sec; + p->nano_secs = ts.tv_nsec; + } + #else + { + // getnstimeofday() *not* supported + struct timeval tv; + + do_gettimeofday( &tv ); + + p->secs = tv.tv_sec; + p->nano_secs = tv.tv_usec * 1000; + } + #endif + + #elif defined( MBG_TGT_BSD ) // BSD kernel space + { + struct timespec ts; + + nanotime( &ts ); + + p->secs = ts.tv_sec; + p->nano_secs = ts.tv_nsec; + } + #endif + + #else // POSIX user space + { + struct timespec ts; + + #if defined( CLOCK_REALTIME_PRECISE ) // at least available in FreeBSD + clock_gettime( CLOCK_REALTIME_PRECISE, &ts ); + #else + clock_gettime( CLOCK_REALTIME, &ts ); + #endif + + p->secs = ts.tv_sec; + p->nano_secs = ts.tv_nsec; + } + #endif + + #elif defined( MBG_TGT_WIN32 ) + + #if defined( MBG_TGT_KERNEL ) // Windows kernel space + #if defined( MBG_TGT_WIN32_PNP ) && !defined( MBG_TGT_WIN32_PNP_X64 ) + extern KE_QUERY_SYSTEM_TIME_FNC ke_query_system_time_fnc; + ke_query_system_time_fnc( p ); + #else + KeQuerySystemTime( p ); + #endif + #else // Windows user space + { + FILETIME ft; + GetSystemTimeAsFileTime( &ft ); + p->LowPart = ft.dwLowDateTime; + p->HighPart = ft.dwHighDateTime; + } + #endif + + #else + + *p = 0; // dummy + + #endif + +} // mbg_get_sys_time + + + +static __mbg_inline +void mbg_get_sys_uptime( MBG_SYS_UPTIME *p ) +{ + #if defined( MBG_TGT_WIN32 ) + + #if defined( MBG_TGT_KERNEL ) // kernel space + + ULONGLONG time_increment = KeQueryTimeIncrement(); + LARGE_INTEGER tick_count; + + KeQueryTickCount( &tick_count ); + + // multiplication by time_increment yields HNS units, + // but we need seconds + *p = ( tick_count.QuadPart * time_increment ) / HNS_PER_SEC; + + #else // user space + + DWORD tickCount; + DWORD timeAdjustment; + DWORD timeIncrement; + BOOL timeAdjustmentDisabled; + + if ( !GetSystemTimeAdjustment( &timeAdjustment, &timeIncrement, &timeAdjustmentDisabled ) ) + *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. + tickCount = GetTickCount(); + + *p = ( ( (MBG_SYS_UPTIME) tickCount ) * timeIncrement ) / HNS_PER_SEC; + + #endif + + #elif defined( MBG_TGT_LINUX ) + + #if defined( MBG_TGT_KERNEL ) + // getrawmonotonic() can possibly be used for this in newer kernels + { + // Using a simple 64 bit division may result in a linker error + // in kernel mode due to a missing symbol __udivdi3, so we use + // a 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; + do_div( tmp, HZ ); + *p = tmp; + } + #else + { + struct sysinfo si; + int rc = sysinfo( &si ); + *p = ( rc == 0 ) ? si.uptime : -1; + } + #endif + + #elif defined( MBG_TGT_BSD ) + + #if defined( MBG_TGT_KERNEL ) + { + struct timespec ts; + #if 0 //##+++++++ + { + struct bintime bt; + + binuptime( &bt ); + #if defined( DEBUG ) + printf( "binuptime: %lli.%09lli\n", + (long long) bt.sec, + (long long) bt.frac ); + #endif + } + #endif + + nanouptime( &ts ); + #if defined( DEBUG ) + printf( "nanouptime: %lli.%09lli\n", + (long long) ts.tv_sec, + (long long) ts.tv_nsec ); + #endif + *p = ts.tv_sec; + } + #elif defined( MBG_TGT_FREEBSD ) + { + struct timespec ts; + // 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 + + #endif + + #else + + *p = -1; // not supported + + #endif + +} // mbg_get_sys_uptime + + + +/** + * @brief Compute delta between two ::MBG_SYS_TIME times, in milliseconds + * + * @param[in] t2 the time to be subtracted from + * @param[in] t1 The time to be subtracted + * + * @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 ); + dt += tmp64; + #else + dt += ( t2->nano_secs - t1->nano_secs ) / 1000000; + #endif + return dt; + #elif defined( MBG_TGT_WIN32 ) + return (long) ( ( t2->QuadPart - t1->QuadPart ) / HNS_PER_MS ); + #else + return 0; + #endif + +} // mbg_delta_sys_time_ms + + + +static __mbg_inline +void mbg_sleep_sec( long sec ) +{ + #if defined( MBG_TGT_POSIX ) + + #if defined( MBG_TGT_KERNEL ) // kernel space functions even differ for POSIX systems + + #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. + #if LINUX_KERNEL_HAS_MSLEEP + msleep( sec * 1000 ); + #else + { + DECLARE_WAIT_QUEUE_HEAD( tmp_wait ); + wait_event_interruptible_timeout( tmp_wait, 0, sec * HZ + 1 ); + } + #endif + + #elif defined( MBG_TGT_FREEBSD ) + + struct timeval tv = { 0 }; + int ticks; + tv.tv_sec = sec; + ticks = tvtohz( &tv ); + + #if defined( DEBUG ) + printf( "pause: %lli.%06lli (%i ticks)\n", + (long long) tv.tv_sec, + (long long) tv.tv_usec, + ticks ); + #endif + + pause( "pause", ticks ); + + #elif defined( MBG_TGT_NETBSD ) + + int timeo = mstohz( sec * 1000 ); + + #if defined( DEBUG ) + printf( "kpause: %i s (%i ticks)\n", sec, timeo ); + #endif + + kpause( "pause", 1, timeo, NULL ); + + #endif + + #else // POSIX user space + + sleep( sec ); + + #endif + + #elif defined( MBG_TGT_WIN32 ) + + #if defined( MBG_TGT_KERNEL ) // 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 + // time. See the API docs for KeDelayExecutionThread(). + delay.QuadPart = - ((LONGLONG) sec * HNS_PER_SEC); + + KeDelayExecutionThread( KernelMode, FALSE, &delay ); + + #else // user space + + // Sleep() expects milliseconds + Sleep( sec * 1000 ); + + #endif + + #elif defined( MBG_TGT_DOS ) + + delay( (unsigned) ( sec * 1000 ) ); + + #else + + // This needs to be implemented for the target OS + // and thus will probably yield a linker error. + do_sleep_sec( sec ); + + #endif + +} // mbg_sleep_sec + + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + +/* (no header definitions found) */ + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _MBGSYSTM_H */ diff --git a/mbglib/common/mbgtime.h b/mbglib/common/mbgtime.h index 7b9d2f4..f8f7a62 100644 --- a/mbglib/common/mbgtime.h +++ b/mbglib/common/mbgtime.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgtime.h 1.18 2012/10/02 18:51:11Z martin REL_M $ + * $Id: mbgtime.h 1.30 2018/11/26 12:04:44Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,43 @@ * * ----------------------------------------------------------------------- * $Log: mbgtime.h $ - * Revision 1.18 2012/10/02 18:51:11Z martin + * Revision 1.30 2018/11/26 12:04:44Z martin + * Moved definition NTP_FRAC_PER_SEC here. + * Revision 1.29 2018/02/28 16:58:10 martin + * Removed reference to frac_sec_from_bin(). + * Revision 1.28 2018/01/15 18:18:49 martin + * Renamed symbol NSECS_PER_SEC to NSEC_PER_SEC + * according to namings of similar symbols. + * Revision 1.27 2017/11/29 11:14:57 gregoire + * Added Multiplier MSEC_TO_NSEC_MULTIPLIER, MSEC_TO_USEC_MULTIPLIER + * Revision 1.26 2017/11/16 13:33:46 philipp + * Added USEC_PER_SEC define + * Revision 1.25 2017/08/15 15:48:59 martin + * Define NSECS_PER_SEC only if it hasn't been defined before. + * Revision 1.24 2017/07/04 14:02:25 martin + * Made definitions of some constants signed to avoid + * signed/unsigned compiler warnings. + * Moved some macros and inline functions for fraction + * conversion here. They are excluded from build in kernel + * mode, though, since some kernels don't support this properly. + * Moved some NANO_TIME- and NANO_TIME_64-related inline + * functions to new module nanotime.c. + * Renamed PCPS_HRT_BIN_FRAC_SCALE to MBG_FRAC32_UNITS_PER_SEC. + * Updated function prototypes. + * Doxygen stuff. + * Revision 1.23 2017/03/16 12:26:13 martin + * Updated function prototypes. + * Revision 1.22 2017/01/25 13:10:55 gregoire.diehl + * nano_time_64_to_double and double_to_nano_time_64 added + * Revision 1.21 2016/12/15 17:44:59Z martin + * Changed conditions to include time.h. + * Fixed spelling. + * Removed trailing spaces. + * Revision 1.20 2014/05/27 08:09:19 martin + * Added NTP_SEC_BIAS. + * Revision 1.19 2013/05/22 16:47:01 martin + * Added some useful macros. + * Revision 1.18 2012/10/02 18:51:11 martin * Include <time.h> for WIN32 target and firmware only * Fixed build under QNX, DOS, and FreeBSD. * Revision 1.17 2010/08/06 13:03:03 martin @@ -59,10 +95,7 @@ #include <gpsdefs.h> -#if _IS_MBG_FIRMWARE \ - || defined( MBG_TGT_WIN32 ) \ - || defined( MBG_TGT_DOS ) \ - || defined( MBG_TGT_QNX_NTO ) +#if !defined( MBG_TGT_KERNEL ) || defined( MBG_TGT_WIN32 ) #include <time.h> #endif @@ -73,6 +106,7 @@ extern "C" { #ifdef _MBGTIME #define _ext + #define _DO_INIT #else #define _ext extern #endif @@ -81,13 +115,34 @@ extern "C" { /* Start of header body */ -// The Unix time_t epoche is usually 1970-01-01 00:00 whereas -// the GPS epoche is 1980-01-06 00:00, so the difference is 10 years, -// plus 2 days due to leap years (1972 and 1976), plus the difference -// of the day-of-month (6 - 1). -#define GPS_SEC_BIAS 315964800UL // ( ( ( 10UL * 365UL ) + 2 + 5 ) * SECS_PER_DAY ) +/** + * @brief GPS epoch bias from ordinary time_t epoch + * + * The Unix time_t epoch is usually 1970-01-01 00:00 whereas + * the GPS epoch is 1980-01-06 00:00, so the difference is 10 years, + * plus 2 days due to leap years (1972 and 1976), plus the difference + * of the day-of-month (6 - 1), so:<br> + * + * time_t t = ( gps_week * ::SECS_PER_WEEK ) + sec_of_week + ::GPS_SEC_BIAS + */ +#define GPS_SEC_BIAS 315964800UL // ( ( ( 10UL * 365UL ) + 2 + 5 ) * SECS_PER_DAY ) + + +/** + * @brief NTP epoch bias from ordinary time_t epoch + * + * The Unix time_t epoch is usually 1970-01-01 00:00 whereas + * the NTP epoch is 1900-01-01 00:00, so the difference is + * a constant number of seconds:<br> + * + * time_t t = ntp_time - ::NTP_SEC_BIAS + */ +#define NTP_SEC_BIAS 2208988800UL + +#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + #define NTP_FRAC_PER_SEC (uint64_t) 4294967296.0 +#endif -// time_t t = ( gps_week * SECS_PER_WEEK ) + sec_of_week + GPS_SEC_BIAS // Modified Julian Day (MJD) numbers for some commonly used epochs. @@ -100,7 +155,7 @@ extern "C" { // The constant below defines the Windows FILETIME number (100 ns intervals -// since 1601-01-01) for 1970-01-01, which is usually the epoche for the time_t +// since 1601-01-01) for 1970-01-01, which is usually the epoch for the time_t // type used by the standard C library. #if !defined( FILETIME_1970 ) // FILETIME represents a 64 bit number, so we need to defined the @@ -169,6 +224,7 @@ typedef struct clock_t start; clock_t stop; short is_set; + } TIMEOUT; @@ -191,84 +247,113 @@ typedef struct #define SEC100S_PER_DAY ( SEC100S_PER_SEC * SECS_PER_DAY ) #if !defined( MSEC_PER_SEC ) - #define MSEC_PER_SEC 1000L + #define MSEC_PER_SEC 1000L #endif -#define MSEC_PER_MIN ( MSEC_PER_SEC * SECS_PER_MIN ) -#define MSEC_PER_HOUR ( MSEC_PER_SEC * SECS_PER_HOUR ) -#define MSEC_PER_DAY ( MSEC_PER_SEC * SECS_PER_DAY ) +#define MSEC_PER_MIN ( MSEC_PER_SEC * SECS_PER_MIN ) +#define MSEC_PER_HOUR ( MSEC_PER_SEC * SECS_PER_HOUR ) +#define MSEC_PER_DAY ( MSEC_PER_SEC * SECS_PER_DAY ) -#define NSECS_PER_SEC 1000000000UL +#if !defined( USEC_PER_SEC ) + #define USEC_PER_SEC 1000000L +#endif + +#if !defined( NSEC_PER_SEC ) + #define NSEC_PER_SEC 1000000000L +#endif #if !defined( HNS_PER_SEC ) - #define HNS_PER_SEC 10000000UL + #define HNS_PER_SEC 10000000L #endif #if !defined( HNS_PER_MS ) - #define HNS_PER_MS 10000UL + #define HNS_PER_MS 10000L #endif +#define MSEC_TO_NSEC_MULTIPLIER ( NSEC_PER_SEC / MSEC_PER_SEC ) +#define MSEC_TO_USEC_MULTIPLIER ( USEC_PER_SEC / MSEC_PER_SEC ) + + +/** + * @brief A table with the days of month + * + * First row is for standard years, second row is + * for leap years. + * + * @see DAYS_OF_MONTH_TABLE_INIT + */ +typedef char DAYS_OF_MONTH_TABLE[2][12]; + + +/** + * @brief An initializer for a ::DAYS_OF_MONTH_TABLE + */ +#define DAYS_OF_MONTH_TABLE_INIT \ +{ \ + { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }, \ + { 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 } \ +} + + + _ext TM_GPS dhms; _ext TM_GPS datum; _ext const char *short_time_fmt -#ifdef _MBGTIME +#ifdef _DO_INIT = "%2i:%02i" #endif ; _ext const char *time_fmt -#ifdef _MBGTIME +#ifdef _DO_INIT = "%2i:%02i:%02i" #endif ; _ext const char *long_time_fmt -#ifdef _MBGTIME +#ifdef _DO_INIT = "%2i:%02i:%02i.%02i" #endif ; _ext const char *date_fmt -#ifdef _MBGTIME +#ifdef _DO_INIT = "%2i.%02i.%04i" #endif ; _ext const char *day_date_fmt -#ifdef _MBGTIME +#ifdef _DO_INIT = "%s, %2i.%02i.%04i" #endif ; _ext const char *day_name_eng[] -#ifdef _MBGTIME +#ifdef _DO_INIT = { "Su", "Mo", "Tu", "We", "Th", "Fr", "Sa" } #endif ; _ext const char *day_name_ger[] -#ifdef _MBGTIME +#ifdef _DO_INIT = { "So", "Mo", "Di", "Mi", "Do", "Fr", "Sa" } #endif ; _ext const TM_GPS init_tm -#ifdef _MBGTIME +#ifdef _DO_INIT = { 1980, 1, 1, 0, 0, 0, 0, 0, 0, 0 } #endif ; -_ext char days_of_month[2][12] -#ifdef _MBGTIME - = { - { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }, - { 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 } - } +_ext DAYS_OF_MONTH_TABLE days_of_month +#ifdef _DO_INIT + = DAYS_OF_MONTH_TABLE_INIT #endif ; @@ -278,34 +363,379 @@ _ext char days_of_month[2][12] n_days( (_s)->mday, (_s)->month, (_s)->year ) +#define _is_leap_year( _y ) \ + ( ( ( ( (_y) % 4 ) == 0 ) && ( ( (_y) % 100 ) != 0 ) ) || ( ( (_y) % 400 ) == 0 ) ) + + +#define _get_days_of_month( _y, _m ) \ + days_of_month[ _is_leap_year( _y ) ][_m] + + + +#if !defined( MBG_TGT_KERNEL ) + +/** + * @brief Data type used for intermediate results on 32 bit multiplications + * + * We need 64 bits for intermediate integer results to avoid a range overflow + * from 32 x 32 bit multiplications. On systems which don't support 64 bit types + * we use the "double" type as a workaround. + */ +#if defined( MBG_TGT_MISSING_64_BIT_TYPES ) + #define MBG_FRAC32_CONVERSION_TYPE double +#else + #define MBG_FRAC32_CONVERSION_TYPE int64_t +#endif + +/** + * @brief Constant used to convert e.g. ::PCPS_TIME_STAMP::frac values + * + * Max value of ::PCPS_TIME_STAMP::frac + 1, used for scaling + */ +#define MBG_FRAC32_UNITS_PER_SEC ( (MBG_FRAC32_CONVERSION_TYPE) 4294967296.0 ) // == 0x100000000 + + + +/** + * @brief Convert a 16 bit binary fraction to a scaled decimal + * + * @param[in] bin The binary fraction + * @param[in] scale The scale factor + * + * @return The calculated number + * + * @see ::dec_frac_to_bin_frac_16 + * @see ::dec_frac_to_bin_frac_32 + * @see ::bin_frac_32_to_dec_frac + */ +static __mbg_inline +uint32_t bin_frac_16_to_dec_frac( uint16_t bin, uint32_t scale ) +{ + return (uint32_t) ( (MBG_FRAC32_CONVERSION_TYPE) bin * scale + / 0x10000UL ); + +} // bin_frac_16_to_dec_frac + + + +/** + * @brief Convert a 32 bit binary fraction to a scaled decimal + * + * @param[in] bin The binary fraction + * @param[in] scale The scale factor + * + * @return The calculated number + * + * @see ::dec_frac_to_bin_frac_32 + * @see ::dec_frac_to_bin_frac_16 + * @see ::bin_frac_16_to_dec_frac + */ +static __mbg_inline +uint32_t bin_frac_32_to_dec_frac( uint32_t bin, uint32_t scale ) +{ + return (uint32_t) ( (MBG_FRAC32_CONVERSION_TYPE) bin * scale + / MBG_FRAC32_UNITS_PER_SEC ); + +} // bin_frac_32_to_dec_frac + + + +#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + +// On targets which don't provide 64 bit data types +// MBG_FRAC32_CONVERSION_TYPE is defined as double, +// in which case the ">> 1" operation in the 2 functions +// below yields an "invalid use of floating point" error. +// 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 ) +{ + return (uint16_t) ( ( ( (MBG_FRAC32_CONVERSION_TYPE) 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 ) +{ + return (uint32_t) ( ( ( (MBG_FRAC32_CONVERSION_TYPE) dec * MBG_FRAC32_UNITS_PER_SEC * 2 / scale ) + 1 ) >> 1 ); + +} // dec_frac_to_bin_frac_32 + +#endif // !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + + + +#define bin_frac_32_to_msec( _bin ) bin_frac_32_to_dec_frac( (_bin), 1000L ) +#define bin_frac_32_to_usec( _bin ) bin_frac_32_to_dec_frac( (_bin), 1000000L ) +#define bin_frac_32_to_nsec( _bin ) bin_frac_32_to_dec_frac( (_bin), 1000000000L ) +#define bin_frac_16_to_msec( _bin ) bin_frac_16_to_dec_frac( (_bin), 1000L ) +#define bin_frac_16_to_usec( _bin ) bin_frac_16_to_dec_frac( (_bin), 1000000L ) +#define bin_frac_16_to_nsec( _bin ) bin_frac_16_to_dec_frac( (_bin), 1000000000L ) + + +#define msec_to_bin_frac_32( _msec ) dec_frac_to_bin_frac_32( (_msec), 1000L ) +#define usec_to_bin_frac_32( _usec ) dec_frac_to_bin_frac_32( (_usec), 1000000L ) +#define nsec_to_bin_frac_32( _nsec ) dec_frac_to_bin_frac_32( (_nsec), 1000000000L ) +#define msec_to_bin_frac_16( _msec ) dec_frac_to_bin_frac_16( (_msec), 1000L ) +#define usec_to_bin_frac_16( _usec ) dec_frac_to_bin_frac_16( (_usec), 1000000L ) +#define nsec_to_bin_frac_16( _nsec ) dec_frac_to_bin_frac_16( (_nsec), 1000000000L ) + + + +/** + * @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. + * + * @deprecated This function is deprecated, use ::bin_frac_32_to_dec_frac preferably. + * + * @param[in] b The binary fraction + * @param[in] scale The scale factor + * + * @return The calculated number + * + * @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 ) +{ + return bin_frac_32_to_dec_frac( b, scale ); + +} // frac_sec_from_bin + + + +/** + * @brief Convert a binary fraction to "double" fractions + * + * Convert a binary fraction (e.g. of a second, as in ::PCPS_TIME_STAMP::frac) + * to a "double" with the units of seconds.<br> + * E.g. a 0xFFFFFFFF fraction yields 0.9999999999.... + * + * @note Excluded from build for kernel drivers which usually + * don't support floating point operations. + * + * @param[in] b The binary fraction + * + * @return The calculated fraction + * + * @see ::MBG_FRAC32_UNITS_PER_SEC + */ +static __mbg_inline +double dfrac_sec_from_bin( uint32_t b ) +{ + return (double) b / (double) MBG_FRAC32_UNITS_PER_SEC; + +} // dfrac_sec_from_bin + +#endif // !defined( MBG_TGT_KERNEL ) + + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ + /** + * @brief Set a timeout object to specified interval + * + * @param[out] t The timeout object + * @param[in] clk The current time, in clock_t ticks + * @param[in] interval The interval until expiration, in clock_t ticks + */ void set_timeout( TIMEOUT *t, clock_t clk, clock_t interval ) ; + + /** + * @brief Stretch a timeout specified in given timeout object + * + * @param[in,out] t The timeout object + * @param[in] interval The interval until expiration, in clock_t ticks + */ void stretch_timeout( TIMEOUT *t, clock_t interval ) ; + + /** + * @brief Check if a timeout object has expired + * + * @param[in] t The timeout object + * @param[in] clk The current time, in clock_t ticks + * + * @return 1 if timeout expired, else 0 + */ bit check_timeout( TIMEOUT *t, clock_t clk ) ; - int err_tm( TM_GPS *tm ) ; + + /** + * @brief Check if a ::TM_GPS structure contains a valid date and time + * + * @param[in] tm The date/time structure to be checked + * + * @return 0 if date/time is valid, else a negative number indicating + * which field was found invalid + */ + int err_tm( const TM_GPS *tm ) ; + + /** + * @brief Set the time in a ::TM_GPS structure to 00:00:00.000 + * + * @param[in,out] tm The date/time structure to be set + * + * @return Pointer to the ::TM_GPS structure that has been passed + */ TM_GPS *clear_time( TM_GPS *tm ) ; + + /** + * @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 + * + * @return Pointer to the ::TM_GPS structure that has been passed + * + * @see ::tm_to_wsec + */ TM_GPS *wsec_to_tm( long wsec, TM_GPS *tm ) ; - long tm_to_wsec( TM_GPS *tm ) ; + + /** + * @brief Compute second-of-week from day-of-week and time-of-day + * + * @todo Specify input / output ranges + * + * @param[in] tm Address of a ::TM_GPS structure providing day-of-week and time-of-day + * + * @return The computed second-of-week number + * + * @see ::wsec_to_tm + */ + long tm_to_wsec( const TM_GPS *tm ) ; + + /** + * @brief Check if a specific year is a leap year + * + * @param[in] y The full year number + * + * @return != 0 if the year is a leap year, else 0 + */ int is_leap_year( int y ) ; + + /** + * @brief Compute the day-of-year from a given date + * + * @param[in] day The day-of-month + * @param[in] month The month + * @param[in] year The full year number + * + * @return The computed day-of-year + */ int day_of_year( int day, int month, int year ) ; + + /** + * @brief Compute a date from a given year and day-of-year + * + * @param[in] year The full year number + * @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 ) ; + + /** + * @brief Compute day-of-week from a given date + * + * @todo Specify range of returned day-of-week. Should we just call n_days()? + * + * @param[in] day The day-of-month + * @param[in] month The month + * @param[in] year The full year number + * + * @return The computed day-of-week + * + * @see ::n_days + */ int day_of_week( 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 + * @param[in] year The year number to start with + * + * @return The computed year number + */ int days_to_years( long *day_num, int year ) ; + + /** + * @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 + * + * @return The computed number of days + * + * @see ::day_of_week + */ long n_days( ushort mday, ushort month, ushort year ) ; - double nano_time_to_double( const NANO_TIME *p ) ; - void double_to_nano_time( NANO_TIME *p, double d ) ; + + /** + * @brief Print time with hours, minutes, seconds to a string + * + * @param[out] s Address of a string buffer to be filled + * @param[in] tm Address of a ::TM_GPS structure providing date and time + */ int sprint_time( char *s, const TM_GPS *tm ) ; - int sprint_short_time( char *s, TM_GPS *time ) ; + + /** + * @brief Print time with hours, minutes to a string + * + * @param[out] s Address of a string buffer to be filled + * @param[in] tm Address of a ::TM_GPS structure providing date and time + */ + int sprint_short_time( char *s, const TM_GPS *tm ) ; + + /** + * @brief Print date to a string + * + * @param[out] s Address of a string buffer to be filled + * @param[in] tm Address of a ::TM_GPS structure providing date and time + */ int sprint_date( char *s, const TM_GPS *tm ) ; + + /** + * @brief Print day-of-week and date to a string + * + * @param[out] s Address of a string buffer to be filled + * @param[in] tm Address of a ::TM_GPS structure providing date and time + */ int sprint_day_date( char *s, const TM_GPS *tm ) ; + + /** + * @brief Print day-of-week, date and time to a string + * + * @param[out] s Address of a string buffer to be filled + * @param[in] tm Address of a ::TM_GPS structure providing date and time + */ int sprint_tm( char *s, const TM_GPS *tm ) ; - void sscan_time( char *s, TM_GPS *tm ) ; + + /** + * @brief Extract a time from a string + * + * @param[in] s A time string in format hh:mm:ss + * @param[out] tm Address of a ::TM_GPS structure which takes the extracted time + */ + void sscan_time( const char *s, TM_GPS *tm ) ; + + /** + * @brief Extract a date from a string + * + * @param[in] s A date string in format dd.mm. or dd.mm.yyyy + * @param[out] tm Address of a ::TM_GPS structure which takes the extracted date + */ void sscan_date( char *s, TM_GPS *tm ) ; + /* ----- function prototypes end ----- */ @@ -313,6 +743,7 @@ _ext char days_of_month[2][12] #undef _ext +#undef _DO_INIT #ifdef __cplusplus } diff --git a/mbglib/common/mbgutil.h b/mbglib/common/mbgutil.h new file mode 100644 index 0000000..1fa1e55 --- /dev/null +++ b/mbglib/common/mbgutil.h @@ -0,0 +1,615 @@ + +/************************************************************************** + * + * $Id: mbgutil.h 1.21 2018/09/21 08:18:05Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions used with mbgutil.c. + * + * ----------------------------------------------------------------------- + * $Log: mbgutil.h $ + * Revision 1.21 2018/09/21 08:18:05Z martin + * New version code 0x0308, compatibility version still 0x0110. + * Revision 1.20 2018/08/13 14:54:24Z martin + * Updated function prototypes. + * Revision 1.19 2018/08/07 15:09:11Z martin + * New version code 0x0370, compatibility version still 0x0110. + * Revision 1.18 2017/07/05 16:44:35 martin + * New version code 0x0400, compatibility version still 0x0110. + * Include timeutil.h. + * windows.h is now included in mbg_tgt.h. + * Updated function prototypes. + * Revision 1.17 2012/10/15 10:08:32 martin + * Include stdlib.h. + * Cleaned up handling of pragma pack(). + * Revision 1.16 2009/08/14 10:11:53Z daniel + * New version code 306, compatibility version still 110. + * Revision 1.15 2009/06/09 08:57:47Z daniel + * Rev No. 305 + * Revision 1.14 2009/03/19 09:06:00Z daniel + * New version code 304, compatibility version still 110. + * Revision 1.13 2009/01/12 09:35:41Z daniel + * New version code 303, compatibility version still 110. + * Updated function prototypes. + * Revision 1.12 2008/01/17 10:15:26Z daniel + * New version code 302, compatibility version still 110. + * Revision 1.11 2007/10/16 10:01:17Z daniel + * New version code 301, compatibility version still 110. + * Revision 1.9 2007/03/21 16:48:31Z martin + * New version code 219, compatibility version still 110. + * Revision 1.8 2006/08/09 13:18:18Z martin + * New version code 218, compatibility version still 110. + * Revision 1.7 2006/06/08 10:48:52Z martin + * New version code 217, compatibility version still 110. + * Added macro _mbg_strncpy(). + * Revision 1.6 2006/05/10 10:56:54Z martin + * Updated function prototypes. + * Revision 1.5 2006/05/02 13:24:49Z martin + * New version code 216, compatibility version still 110. + * Revision 1.4 2006/01/11 12:24:05Z martin + * New version code 215, compatibility version still 110. + * Revision 1.3 2005/12/15 10:01:51Z martin + * New version 214, compatibility version still 110. + * Revision 1.2 2005/02/18 15:13:42Z martin + * Updated function prototypes. + * Revision 1.1 2005/02/18 10:39:49Z martin + * Initial revision + * + **************************************************************************/ + +#ifndef _MBGUTIL_H +#define _MBGUTIL_H + + +/* Other headers to be included */ + +#include <mbg_tgt.h> +#include <timeutil.h> +#include <use_pack.h> +#include <pcpsdefs.h> +#include <mbggeo.h> +#include <pci_asic.h> + +#include <stdlib.h> + + +#define MBGUTIL_VERSION 0x0308 + +#define MBGUTIL_COMPAT_VERSION 0x0110 + + +#if defined( MBG_TGT_WIN32 ) + + +#elif defined( MBG_TGT_LINUX ) + + +#elif defined( MBG_TGT_OS2 ) + + +#elif defined( MBG_TGT_DOS ) + + #if !defined( MBG_USE_DOS_TSR ) + #endif + +#else + +#endif + +#ifdef _MBGUTIL + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#if defined( _USE_PACK ) + #pragma pack( 1 ) // set byte alignment + #define _USING_BYTE_ALIGNMENT +#endif + + +#ifdef __cplusplus +extern "C" { +#endif + + +// The macro below can be used to simplify the API call if +// a string variable is used rather than a char *. +#define _mbg_strncpy( _s, _src ) \ + mbg_strncpy( _s, sizeof( _s ), _src ) + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + /** + * @brief Get the version number of the precompiled DLL/shared object library. + * + * If this library is used as a DLL/shared object library then the version + * number can be checked to see if the header files which are actually used + * to build an application are compatible with the header files which have + * been used to build the library, and thus the API function are called + * in the correct way. + * + * @return The version number + * + * @see ::mbgutil_check_version + * @see ::MBGUTIL_VERSION defined in mbgutil.h + */ + _MBG_API_ATTR int _MBG_API mbgutil_get_version( void ) ; + + /** + * @brief Check if the DLL/shared library is compatible with a given version. + * + * If this library is used as a DLL/shared object library then the version + * number can be checked to see if the header files which are actually used + * to build an application are compatible with the header files which have + * been used to build the library, and thus the API 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 + * + * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE + * + * @see ::mbgutil_get_version + * @see ::MBGUTIL_VERSION defined in mbgutil.h + */ + _MBG_API_ATTR int _MBG_API mbgutil_check_version( int header_version ) ; + + /** + * @brief A portable, safe implementation of snprintf() + * + * The output string buffer is in any case properly terminated by 0. + * 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 + * + * @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, ... ) ; + + /** + * @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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 ) ; + + /** + * @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 + * + * @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 ) ; + + /** + * @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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 ) ; + + /** + * @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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 + * + * 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 + * + * @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 ) ; + + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + + +#if defined( _USING_BYTE_ALIGNMENT ) + #pragma pack() // set default alignment + #undef _USING_BYTE_ALIGNMENT +#endif + +/* End of header body */ + + +#undef _ext +#undef _DO_INIT + +#endif /* _MBGUTIL_H */ + diff --git a/mbglib/common/myutil.h b/mbglib/common/myutil.h index 52489d5..1f05d7a 100644 --- a/mbglib/common/myutil.h +++ b/mbglib/common/myutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: myutil.h 1.15 2012/10/02 18:51:52Z martin REL_M $ + * $Id: myutil.h 1.22 2018/11/21 16:04:27Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,21 @@ * * ----------------------------------------------------------------------- * $Log: myutil.h $ - * Revision 1.15 2012/10/02 18:51:52Z martin + * Revision 1.22 2018/11/21 16:04:27Z martin + * Doxygen fixes. + * Revision 1.21 2018/11/01 11:10:57 martin + * Updated function prototypes. + * Revision 1.20 2017/03/22 15:09:03Z andre.hartmann + * added macros for lin. interpolation + * Revision 1.19 2017/01/27 12:24:08Z martin + * Moved STRINGIFY() macro to words.h. + * Revision 1.18 2014/10/20 12:30:38 martin + * Moved macro _isdigit() to words.h. + * Revision 1.17 2014/07/15 06:19:48Z andre + * added function _sgn( _x ), returns sign of _x + * Revision 1.16 2013/12/16 13:32:57Z martin + * Don't redefine MIN and MAX. + * Revision 1.15 2012/10/02 18:51:52 martin * Updated handling of pragma pack(). * Revision 1.14 2011/02/16 14:02:35 martin * Added STRINGIFY() macro. @@ -74,21 +88,6 @@ #endif -// The two macros below can be used to define a constant string on the -// compiler's command line, e.g. like -DVERSION_STRING="v1.0 BETA". -// Source code like -// const char version_string[] = VERSION_STRING; -// 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 below: -// const char version_string[] = STRINGIFY( VERSION_STRING ); -// The XSTRINGIFY() macro is simply a helper macro which should not -// be used alone. -#define STRINGIFY(x) XSTRINGIFY(x) -#define XSTRINGIFY(x) #x - - - #if MBG_TGT_HAS_64BIT_TYPES #define _frac( _x ) ( ( (_x) == 0.0 ) ? 0.0 : ( (_x) - (double) ( (int64_t) (_x) ) ) ) #else @@ -96,12 +95,16 @@ #endif -#define _isdigit( _c ) ( (_c) >= '0' && (_c) <= '9' ) - #define _eos( _s ) ( &(_s)[strlen( _s )] ) -#define MIN( _x, _y ) ( ( (_x) < (_y) ) ? (_x) : (_y) ) -#define MAX( _x, _y ) ( ( (_x) > (_y) ) ? (_x) : (_y) ) +#if !defined( MIN ) + #define MIN( _x, _y ) ( ( (_x) < (_y) ) ? (_x) : (_y) ) +#endif + +#if !defined( MAX ) + #define MAX( _x, _y ) ( ( (_x) > (_y) ) ? (_x) : (_y) ) +#endif + #define SWAP( _x, _y ) { temp = (_x); (_x) = (_y); (_y) = temp; } #define SQR( _x ) ( (_x) * (_x) ) @@ -160,6 +163,14 @@ typedef union #define _is_supported( _i, _msk ) \ ( ( (_msk) & _idx_bit( _i ) ) != 0 ) +// 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 ) +#define _m( _Y1, _X1, _Y2, _X2 ) ( ( _Y2 -_Y1 ) / ( _X2 -_X1 ) ) +#define _b( _Y1, _X1, _Y2, _X2 ) ( ( ( _Y1 * _X2 ) - ( _Y2 * _X1 ) ) / ( _X2 -_X1 ) ) + /* * The macro below copies a string, taking care not to @@ -201,9 +212,24 @@ extern "C" { /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ + /** + * @brief Replace whitespace ' ' characters by 0 characters. + * + * @param[in,out] s The string to be modified. + */ void spaces_to_zeros( char *s ) ; + + /** + * @brief Create a simple checksum. + * + * @param[in] vp Pointer to a data block + * @param[in] n Size of the datablock to calulate the checksum from. + * + * @return The computed checksum. + */ CSUM checksum( const void _CSFAR *vp, int n ) ; + /* ----- function prototypes end ----- */ #ifdef __cplusplus diff --git a/mbglib/common/nanotime.c b/mbglib/common/nanotime.c new file mode 100644 index 0000000..ed57cfd --- /dev/null +++ b/mbglib/common/nanotime.c @@ -0,0 +1,397 @@ + +/************************************************************************** + * + * $Id: nanotime.c 1.6 2018/12/11 11:55:06Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Meinberg Library module providing functions to handle NANO_TIME + * and NANO_TIME_64. + * + * ----------------------------------------------------------------------- + * $Log: nanotime.c $ + * Revision 1.6 2018/12/11 11:55:06Z 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. + * Moved inclusion of stdlib.h to the header file. + * Revision 1.4 2018/09/20 09:46:57 martin + * Fixed build for some targets. + * Moved version dependencies to mbg:tgt.h. + * Revision 1.3 2018/07/16 12:39:42Z martin + * Functions nano_time_64_to_tm_gps() and tm_gps_to_nano_time_64() + * were moved here. + * Account for renamed library symbol NSEC_PER_SEC. + * Even VS2010 doesn't provide strtoll(). + * Revision 1.2 2017/06/12 13:54:04 martin + * Fixed build under Windows. + * Revision 1.1 2017/06/12 08:49:09Z martin + * Initial revision. + * + **************************************************************************/ + +#define _NANOTIME + #include <nanotime.h> +#undef _NANOTIME + +#include <mbgtime.h> + +#if !_IS_MBG_FIRMWARE + #include <mbgerror.h> + #include <mbgmktm.h> + #include <str_util.h> + #include <timeutil.h> +#endif + + + +/*HDR*/ +/** + * @brief Convert a ::NANO_TIME time to double + * + * @param[in] p Address of a ::NANO_TIME structure to be converted + * + * @return The computed number of seconds with fractions, as double + * + * @see ::double_to_nano_time + */ +double nano_time_to_double( const NANO_TIME *p ) +{ + double d = p->secs; + + d += ( (double) p->nano_secs ) / 1e9; + + return d; + +} // nano_time_to_double + + + +/*HDR*/ +/** + * @brief Setup a ::NANO_TIME structure from a time provided as double + * + * @param[out] p Address of a ::NANO_TIME structure to be set up + * @param[in] d The time to be converted, in seconds with fractions, as double + * + * @see ::nano_time_to_double + */ +void double_to_nano_time( NANO_TIME *p, double d ) +{ + p->secs = (int32_t) d; + + d -= (double) p->secs; + + p->nano_secs = (int32_t) ( d * 1e9 ); + +} // double_to_nano_time + + + +#if !_IS_MBG_FIRMWARE + +/*HDR*/ +/** + * @brief Print nano time into 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] nt The ::NANO_TIME to be printed + */ +size_t snprint_nano_time( char *s, size_t max_len, const NANO_TIME *nt ) +{ + size_t n = snprintf_safe( s, max_len, "%c%li.%09li", + _nano_time_negative( nt ) ? '-' : '+', + labs( (long) nt->secs ), + labs( (long) nt->nano_secs ) ); + return n; + +} // snprint_nano_time + +#endif + + + +#if !_IS_MBG_FIRMWARE && !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + +/*HDR*/ +/** + * @brief Normalize a ::NANO_TIME_64 time + * + * After normalization, the following can be assumed:<br> + * - nano_secs is in the range [-10^9 + 1, 10^9 - 1]<br> + * - if secs is not 0, secs and nano_secs have the same sign + * + * @param[in,out] nt The ::NANO_TIME_64 to be normalized + */ +void normalize_nano_time_64( NANO_TIME_64 *nt ) +{ + int64_t additional_secs; + + // Step 1: Make sure nano seconds are in the interval [-10^9 + 1, 10^9 - 1] + additional_secs = nt->nano_secs / NSEC_PER_SEC; + nt->nano_secs -= additional_secs * NSEC_PER_SEC; + nt->secs += additional_secs; + + // Step 2: Make sure seconds and nanoseconds have same sign if seconds is not 0 + if ( nt->secs > 0 && nt->nano_secs < 0 ) + { + nt->secs -= 1; + nt->nano_secs += NSEC_PER_SEC; + } + else if ( nt->secs < 0 && nt->nano_secs > 0 ) + { + nt->secs += 1; + nt->nano_secs -= NSEC_PER_SEC; + } + +} // normalize_nano_time_64 + + + +/*HDR*/ +/** + * @brief Convert a ::NANO_TIME_64 time to double + * + * @param[in] p Address of a ::NANO_TIME_64 structure to be converted + * + * @return The computed number of seconds with fractions, as double + * + * @see ::double_to_nano_time_64 + */ +double nano_time_64_to_double( const NANO_TIME_64 *p ) +{ + double d = (double) p->secs; + + d += ( (double) p->nano_secs ) / 1e9; + + return d; + +} // nano_time_64_to_double + + + +/*HDR*/ +/** + * @brief Setup a ::NANO_TIME_64 structure from a time as double + * + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + * @param[in] d The time to be converted, in seconds with fractions, as double + * + * @see ::nano_time_64_to_double + */ +void double_to_nano_time_64( NANO_TIME_64 *p, double d ) +{ + p->secs = (int32_t) d; + + d -= (double) p->secs; + + p->nano_secs = (int32_t) ( d * 1e9 ); + +} // double_to_nano_time_64 + + + +/*HDR*/ +/** + * @brief Print a normalized ::NANO_TIME_64 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] nt The ::NANO_TIME_64 to be printed + */ +size_t snprint_nano_time_64( char *s, size_t max_len, const NANO_TIME_64 *nt ) +{ + size_t n = snprintf_safe( s, max_len, "%c%" PRId64 ".%09" PRId64, + _nano_time_negative( nt ) ? '-' : '+', + _abs64( nt->secs ), + _abs64( nt->nano_secs ) ); + return n; + +} // snprint_nano_time_64 + + + +static __mbg_inline /*HDR*/ +/** + * @brief Generic function to divide ::NANO_TIME_64 value + * + * @param[in,out] p Address of a ::NANO_TIME_64 structure to be divided + * @param[in] div The number by which to divide + * @param[in] mul The complementary number to div, i.e. mul = 1000000000 / div + */ +void div_nano_time_64( NANO_TIME_64 *p, long div, long mul ) +{ + #if defined( MBG_TGT_MISSING_LLDIV_T ) + //### TODO: Test this code + int64_t rem = p->secs % div; + p->secs /= div; + p->nano_secs = ( rem * mul ) + ( p->nano_secs / div ); + #else + lldiv_t lldt = lldiv( p->secs, div ); + p->secs = lldt.quot; + p->nano_secs = ( lldt.rem * mul ) + ( p->nano_secs / div ); + #endif + +} // div_nano_time_64 + + + +#if !defined( MBG_TGT_MISSING_STRTOLL ) + +static __mbg_inline /*HDR*/ +/** + * @brief Generic function to set up a ::NANO_TIME_64 structure from a string + * + * @param[in] s A string with a time in seconds, with fractions separated by decimal point + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + * @param[in] base The base of the conversion, i.e. 10 for a string with decimal numbers, or 16 for a hex string + * @param[in] frac_digits The number of fractions required to represent 1 nanosecond, e.g. + * 9 for a decimal string like 0.000000001, or + * TODO for a hex string like 0x00000000.00000000 + */ +void str_to_nano_time_64( const char *s, NANO_TIME_64 *p, int base, int frac_digits ) +{ + char *cp = NULL; + + p->secs = strtoll( s, &cp, base ); + + if ( *cp == '.' ) // fractions may follow + { + char *ep = NULL; + + cp++; // skip '.' + + p->nano_secs = strtoll( cp, &ep, base ); + + if ( p->nano_secs ) // only if fractions not 0 + { + int l = (int) ( ep - cp ); + + while ( l < frac_digits ) + { + p->nano_secs *= base; + l++; + } + + while ( l > frac_digits ) + { + p->nano_secs /= base; + l--; + } + + if ( p->secs < 0 ) + p->nano_secs = -p->nano_secs; + } + } + +} // str_to_nano_time_64 + + + +/*HDR*/ +/** + * @brief Set up a ::NANO_TIME_64 structure from a string with a time in seconds and fractions + * + * @param[in] s A string with a time in seconds, with fractions separated by decimal point + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + */ +void str_s_to_nano_time_64( const char *s, NANO_TIME_64 *p ) +{ + str_to_nano_time_64( s, p, 10, 9 ); + +} // str_s_to_nano_time_64 + + + +/*HDR*/ +/** + * @brief Set up a ::NANO_TIME_64 structure from a string with a time in milliseconds and fractions + * + * @param[in] s A string with a time in milliseconds, with fractions separated by decimal point + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + */ +void str_ms_to_nano_time_64( const char *s, NANO_TIME_64 *p ) +{ + // First do the same conversion as for a string representing seconds + str_s_to_nano_time_64( s, p ); + + // Now we have the value in milliseconds + // Divide by 1000 to get seconds + div_nano_time_64( p, 1000, 1000000UL ); + +} // str_ms_to_nano_time_64 + +#endif // !defined( MBG_TGT_MISSING_STRTOLL ) + + + +/*HDR*/ +/** + * @brief Convert ::NANO_TIME_64 to ::TM_GPS + * + * @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 + * + * @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 ); + + if ( mbg_rc_is_success( rc ) ) + { + tm_gps->year = tm.tm_year + 1900; + tm_gps->month = tm.tm_mon + 1; + tm_gps->mday = tm.tm_mday; + tm_gps->yday = tm.tm_yday; + tm_gps->wday = tm.tm_wday; + 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 + } + + return rc; + +} // nano_time_64_to_tm_gps + + + +/*HDR*/ +/** + * @brief Convert ::TM_GPS to ::NANO_TIME_64 + * + * @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 + * + * @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 ); + + if ( t != (time_t) -1 ) + { + nt->secs = (uint64_t) t; + nt->nano_secs = 0; //### TODO: convert fractions + return 1; + } + + return 0; + +} // tm_gps_to_nano_time_64 + +#endif // !_IS_MBG_FIRMWARE && !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + + diff --git a/mbglib/common/nanotime.h b/mbglib/common/nanotime.h new file mode 100644 index 0000000..5494e4c --- /dev/null +++ b/mbglib/common/nanotime.h @@ -0,0 +1,180 @@ + +/************************************************************************** + * + * $Id: nanotime.h 1.3 2018/11/21 11:27:26Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for nanotime.c + * + * ----------------------------------------------------------------------- + * $Log: nanotime.h $ + * Revision 1.3 2018/11/21 11:27:26Z martin + * Include stdlib.h to provide size_t. + * Revision 1.2 2018/07/16 12:40:55 martin + * Include gpsdefs.h. + * Updated function prototypes. + * Revision 1.1 2017/06/12 08:49:09 martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _NANOTIME_H +#define _NANOTIME_H + +/* Other headers to be included */ + +#include <words.h> // implicitly includes mbg_tgt.h, if required, + // and defines some basic structures +#include <gpsdefs.h> + +#include <stdlib.h> + +#ifdef _NANOTIME + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + + + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + /** + * @brief Convert a ::NANO_TIME time to double + * + * @param[in] p Address of a ::NANO_TIME structure to be converted + * + * @return The computed number of seconds with fractions, as double + * + * @see ::double_to_nano_time + */ + double nano_time_to_double( const NANO_TIME *p ) ; + + /** + * @brief Setup a ::NANO_TIME structure from a time provided as double + * + * @param[out] p Address of a ::NANO_TIME structure to be set up + * @param[in] d The time to be converted, in seconds with fractions, as double + * + * @see ::nano_time_to_double + */ + void double_to_nano_time( NANO_TIME *p, double d ) ; + + /** + * @brief Print nano time into 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] nt The ::NANO_TIME to be printed + */ + size_t snprint_nano_time( char *s, size_t max_len, const NANO_TIME *nt ) ; + + /** + * @brief Normalize a ::NANO_TIME_64 time + * + * After normalization, the following can be assumed:<br> + * - nano_secs is in the range [-10^9 + 1, 10^9 - 1]<br> + * - if secs is not 0, secs and nano_secs have the same sign + * + * @param[in,out] nt The ::NANO_TIME_64 to be normalized + */ + void normalize_nano_time_64( NANO_TIME_64 *nt ) ; + + /** + * @brief Convert a ::NANO_TIME_64 time to double + * + * @param[in] p Address of a ::NANO_TIME_64 structure to be converted + * + * @return The computed number of seconds with fractions, as double + * + * @see ::double_to_nano_time_64 + */ + double nano_time_64_to_double( const NANO_TIME_64 *p ) ; + + /** + * @brief Setup a ::NANO_TIME_64 structure from a time as double + * + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + * @param[in] d The time to be converted, in seconds with fractions, as double + * + * @see ::nano_time_64_to_double + */ + void double_to_nano_time_64( NANO_TIME_64 *p, double d ) ; + + /** + * @brief Print a normalized ::NANO_TIME_64 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] nt The ::NANO_TIME_64 to be printed + */ + size_t snprint_nano_time_64( char *s, size_t max_len, const NANO_TIME_64 *nt ) ; + + /** + * @brief Set up a ::NANO_TIME_64 structure from a string with a time in seconds and fractions + * + * @param[in] s A string with a time in seconds, with fractions separated by decimal point + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + */ + void str_s_to_nano_time_64( const char *s, NANO_TIME_64 *p ) ; + + /** + * @brief Set up a ::NANO_TIME_64 structure from a string with a time in milliseconds and fractions + * + * @param[in] s A string with a time in milliseconds, with fractions separated by decimal point + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + */ + void str_ms_to_nano_time_64( const char *s, NANO_TIME_64 *p ) ; + + /** + * @brief Convert ::NANO_TIME_64 to ::TM_GPS + * + * @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 + * + * @see ::tm_gps_to_nano_time_64 + */ + int nano_time_64_to_tm_gps( TM_GPS *tm_gps, const NANO_TIME_64 *nt ) ; + + /** + * @brief Convert ::TM_GPS to ::NANO_TIME_64 + * + * @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 + * + * @see ::nano_time_64_to_tm_gps + */ + int tm_gps_to_nano_time_64( NANO_TIME_64 *nt, const TM_GPS *tm ) ; + + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _NANOTIME_H */ diff --git a/mbglib/common/parmgps.c b/mbglib/common/parmgps.c deleted file mode 100644 index 187cd4e..0000000 --- a/mbglib/common/parmgps.c +++ /dev/null @@ -1,242 +0,0 @@ - -/************************************************************************** - * - * $Id: parmgps.c 1.5 2008/10/21 10:47:26Z martin REL_M $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Functions to handle/convert Meinberg GPS specific parameters. - * - * ----------------------------------------------------------------------- - * $Log: parmgps.c $ - * Revision 1.5 2008/10/21 10:47:26Z martin - * Renamed check_port_info() to check_valid_port_info() - * to avoid naming conflicts. - * Revision 1.4 2008/09/15 14:11:25 martin - * New function check_port_info() which returns a bit mask indicating - * which fields of a PORT_SETTINGS structure are not valid. - * This is based on code taken from valid_port_info(), which now calls - * check_port_info() and returns a value compatible to the earlier version. - * Revision 1.3 2004/11/09 14:21:36 martin - * Redefined some data types using C99 fixed-size definitions. - * Revision 1.2 2002/02/19 13:30:23Z MARTIN - * Bug fix in port_settings_from_port_parm_mode(). - * Revision 1.1 2002/01/30 10:30:26 MARTIN - * Initial revision - * - **************************************************************************/ - -#define _PARMGPS - #include <parmgps.h> -#undef _PARMGPS - -#include <myutil.h> -#include <string.h> - - - -/*HDR*/ -int get_str_idx( const char *search, - const char *str_table[], - int n_entries ) -{ - int i; - - for ( i = 0; i < n_entries; i++ ) - if ( strcmp( search, str_table[i] ) == 0 ) - return i; - - return -1; - -} // get_str_idx - - - -/*HDR*/ -int get_baud_rate_idx( BAUD_RATE baud_rate ) -{ - int i; - - for ( i = 0; i < N_MBG_BAUD_RATES; i++ ) - if ( baud_rate == mbg_baud_rate[i] ) - return i; - - return -1; - -} // get_baud_rate_idx - - - -/*HDR*/ -int get_framing_idx( const char *framing ) -{ - return get_str_idx( framing, mbg_framing_str, N_MBG_FRAMINGS ); - -} // get_framing_idx - - - -/*HDR*/ -void port_settings_from_port_parm_mode( - PORT_SETTINGS *p_ps, - uint8_t pp_mode, - int str_type_cap - ) -{ - if ( pp_mode >= STR_UCAP ) - { - p_ps->str_type = str_type_cap; - p_ps->mode = ( pp_mode == STR_UCAP ) ? STR_AUTO : STR_ON_REQ; - } - else - { - p_ps->str_type = 0; - p_ps->mode = pp_mode; - } - -} // port_settings_from_port_parm_mode - - - -/*HDR*/ -void port_parm_mode_from_port_settings( - uint8_t *pp_mode, - const PORT_SETTINGS *p_ps, - int str_type_cap - ) -{ - if ( p_ps->str_type == str_type_cap ) - *pp_mode = ( p_ps->mode == STR_ON_REQ ) ? STR_UCAP_REQ : STR_UCAP; - else - *pp_mode = p_ps->mode; - -} // port_parm_mode_from_port_settings - - - -/*HDR*/ -void port_settings_from_port_parm( - PORT_SETTINGS *p_ps, - int port_num, - const PORT_PARM *p_pp, - int cap_str_idx -) -{ - p_ps->parm = p_pp->com[port_num]; - - port_settings_from_port_parm_mode( p_ps, p_pp->mode[port_num], - cap_str_idx ); - -} // port_info_from_port_parm - - - -/*HDR*/ -void port_parm_from_port_settings( - PORT_PARM *p_pp, - int port_num, - const PORT_SETTINGS *p_ps, - int cap_str_idx -) -{ - p_pp->com[port_num] = p_ps->parm; - - port_parm_mode_from_port_settings( &p_pp->mode[port_num], - p_ps, cap_str_idx ); - -} // port_parm_from_port_settings - - - -/*HDR*/ -int check_valid_port_info( const PORT_INFO *p_pi, - const STR_TYPE_INFO_IDX str_type_info_idx[], - int n_str_type ) - -{ - const PORT_SETTINGS *p_ps = &p_pi->port_settings; - int idx; - int flags = 0; - - - if ( p_pi->supp_baud_rates & ~_mask( N_MBG_BAUD_RATES ) ) - flags |= MBG_PS_MSK_BAUD_RATE_OVR_SW; // dev. supports more baud rates than driver - - idx = get_baud_rate_idx( p_ps->parm.baud_rate ); - - if ( !_inrange( idx, 0, N_MBG_BAUD_RATES ) || - !_is_supported( idx, p_pi->supp_baud_rates ) ) - flags |= MBG_PS_MSK_BAUD_RATE; - - - if ( p_pi->supp_framings & ~_mask( N_MBG_FRAMINGS ) ) - flags |= MBG_PS_MSK_FRAMING_OVR_SW; // dev. supports more framings than driver - - idx = get_framing_idx( p_ps->parm.framing ); - - if ( !_inrange( idx, 0, N_MBG_FRAMINGS ) || - !_is_supported( idx, p_pi->supp_framings ) ) - flags |= MBG_PS_MSK_FRAMING; - - - if ( p_ps->parm.handshake >= N_COM_HS ) - flags |= MBG_PS_MSK_HS_OVR_SW; // handshake index exceeds max. - - if ( p_ps->parm.handshake != HS_NONE ) // currently no device supports any handshake - flags |= MBG_PS_MSK_HS; // handshake mode not supp. by dev. - - - if ( p_pi->supp_str_types & ~_mask( n_str_type ) ) - flags |= MBG_PS_MSK_STR_TYPE_OVR_SW; // firmware error: more string types supported than reported - - idx = p_ps->str_type; - - if ( idx >= n_str_type ) - flags |= MBG_PS_MSK_STR_TYPE_OVR_DEV; // string type index exceeds max. - else - { - if ( !_is_supported( idx, p_pi->supp_str_types ) ) - flags |= MBG_PS_MSK_STR_TYPE; // string type not supported by this port - else - { - // Use the str_type index to get the supported output mode mask - // from the string type info table. This is required to check - // whether the selected mode is supported by the selected - // string type. - ulong supp_modes = str_type_info_idx[idx].str_type_info.supp_modes; - - if ( supp_modes & ~_mask( N_STR_MODE ) ) - flags |= MBG_PS_MSK_STR_MODE_OVR_SW; // dev. supports more string modes than driver - - idx = p_ps->mode; - - if ( idx >= N_STR_MODE ) // mode is always >= 0 - flags |= MBG_PS_MSK_STR_MODE_OVR_SW; // string mode index exceeds max. - else - if ( !_is_supported( idx, supp_modes ) ) - flags |= MBG_PS_MSK_STR_MODE; // string mode not supp. by this string type and port - } - } - - - if ( p_ps->flags != 0 ) /* currently always 0 */ - flags |= MBG_PS_MSK_FLAGS_OVR_SW | MBG_PS_MSK_FLAGS; - - - return flags; - -} // check_valid_port_info - - - -/*HDR*/ -int 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; - -} // valid_port_info - - diff --git a/mbglib/common/parmgps.h b/mbglib/common/parmgps.h deleted file mode 100644 index 6f9b29b..0000000 --- a/mbglib/common/parmgps.h +++ /dev/null @@ -1,142 +0,0 @@ - -/************************************************************************** - * - * $Id: parmgps.h 1.8 2012/10/15 10:06:37Z martin REL_M $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for parmgps.c. - * - * ----------------------------------------------------------------------- - * $Log: parmgps.h $ - * Revision 1.8 2012/10/15 10:06:37Z martin - * Cleaned up handling of pragma pack(). - * Revision 1.7 2011/02/16 10:12:13 martin - * Fixed macro syntax for _setup_default_receiver_info_gps(). - * Revision 1.6 2008/10/21 10:41:09Z martin - * Renamed check_port_info() to check_valid_port_info() - * to avoid naming conflicts. - * Revision 1.5 2008/09/10 16:22:32 martin - * Updated function prototypes. - * Revision 1.4 2004/11/09 14:22:34 martin - * Updated function prototypes. - * Revision 1.3 2004/05/19 07:50:16Z martin - * Use symbolic constant as initializer. - * Revision 1.2 2004/04/14 09:21:23Z martin - * Pack structures 1 byte aligned. - * Revision 1.1 2002/01/30 10:33:38Z MARTIN - * Initial revision - * - **************************************************************************/ - -#ifndef _PARMGPS_H -#define _PARMGPS_H - - -/* Other headers to be included */ - -#include <gpsdefs.h> -#include <use_pack.h> - - -#ifdef _PARMGPS - #define _ext - #define _DO_INIT -#else - #define _ext extern -#endif - - -/* Start of header body */ - -#if defined( _USE_PACK ) - #pragma pack( 1 ) // set byte alignment - #define _USING_BYTE_ALIGNMENT -#endif - - -#ifdef __cplusplus -extern "C" { -#endif - - -#define DEFAULT_N_STR_TYPE_GPS 2 - -#define DEFAULT_SUPP_STR_TYPES_GPS \ - ( ( 1UL << DEFAULT_N_STR_TYPE_GPS ) - 1 ) - - -/* - * The macro below can be used to initialize a - * RECEIVER_INFO structure for old GPS receiver models - * which don't supply that structure. - * - * Parameters: (RECEIVER_INFO *) _p - */ -#define _setup_default_receiver_info_gps( _p ) \ -do \ -{ \ - memset( (_p), 0, sizeof( *(_p) ) ); \ - \ - (_p)->ticks_per_sec = DEFAULT_GPS_TICKS_PER_SEC; \ - (_p)->n_ucaps = 2; \ - (_p)->n_com_ports = DEFAULT_N_COM; \ - (_p)->n_str_type = DEFAULT_N_STR_TYPE_GPS; \ -} while ( 0 ) - - -_ext BAUD_RATE mbg_baud_rate[N_MBG_BAUD_RATES] -#ifdef _DO_INIT - = MBG_BAUD_RATES -#endif -; - -_ext const char *mbg_baud_str[N_MBG_BAUD_RATES] -#ifdef _DO_INIT - = MBG_BAUD_STRS -#endif -; - -_ext const char *mbg_framing_str[N_MBG_FRAMINGS] -#ifdef _DO_INIT - = MBG_FRAMING_STRS -#endif -; - - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - int get_str_idx( const char *search, const char *str_table[], int n_entries ) ; - int get_baud_rate_idx( BAUD_RATE baud_rate ) ; - int get_framing_idx( const char *framing ) ; - void port_settings_from_port_parm_mode( PORT_SETTINGS *p_ps, uint8_t pp_mode, int str_type_cap ) ; - void port_parm_mode_from_port_settings( uint8_t *pp_mode, const PORT_SETTINGS *p_ps, int str_type_cap ) ; - void port_settings_from_port_parm( PORT_SETTINGS *p_ps, int port_num, const PORT_PARM *p_pp, int cap_str_idx ) ; - void port_parm_from_port_settings( PORT_PARM *p_pp, int port_num, const PORT_SETTINGS *p_ps, int cap_str_idx ) ; - int check_valid_port_info( const PORT_INFO *p, const STR_TYPE_INFO_IDX str_type_info_idx[], int n_str_type ) ; - int valid_port_info( const PORT_INFO *p, const STR_TYPE_INFO_IDX str_type_info_idx[], int n_str_type ) ; - -/* ----- function prototypes end ----- */ - - -#ifdef __cplusplus -} -#endif - - -#if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment - #undef _USING_BYTE_ALIGNMENT -#endif - -/* End of header body */ - -#undef _ext -#undef _DO_INIT - -#endif /* _PARMGPS_H */ - diff --git a/mbglib/common/parmpcps.c b/mbglib/common/parmpcps.c deleted file mode 100644 index 1d017a2..0000000 --- a/mbglib/common/parmpcps.c +++ /dev/null @@ -1,115 +0,0 @@ - -/************************************************************************** - * - * $Id: parmpcps.c 1.4 2004/11/09 14:24:15Z martin REL_M $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Functions to handle/convert parameters used by Meinberg plug-in - * radio clocks. - * - * ----------------------------------------------------------------------- - * $Log: parmpcps.c $ - * Revision 1.4 2004/11/09 14:24:15Z martin - * Redefined interface data types using C99 fixed-size definitions. - * Revision 1.3 2003/04/17 10:43:35Z martin - * Moved some definitions to parmpcps.h. - * Removed some functions which are now in mbgdevio.c. - * Revision 1.2 2002/03/25 09:03:43Z MARTIN - * Fixed a bug where the wrong framing was configured for DCF77 clocks. - * Revision 1.1 2002/02/19 14:00:19 MARTIN - * Initial revision - * - **************************************************************************/ - -#define _PARMPCPS - #include <parmpcps.h> -#undef _PARMPCPS - -#include <parmgps.h> -#include <pcpsutil.h> -#include <myutil.h> - -#include <string.h> - - -static const int pcps_to_mbg_framing_tbl[N_PCPS_FR_DCF] = -{ - MBG_FRAMING_8N1, - MBG_FRAMING_7E2, - MBG_FRAMING_8N2, - MBG_FRAMING_8E1 -}; - - - -/*HDR*/ -void port_info_from_pcps_serial( - PORT_INFO_IDX *p_pii, - PCPS_SERIAL pcps_serial, - uint32_t supp_baud_rates -) -{ - PCPS_SER_PACK ser_pack; - PORT_INFO *p_pi; - PORT_SETTINGS *p_ps; - - ser_pack.pack = pcps_serial; - pcps_unpack_serial( &ser_pack ); - - p_pi = &p_pii[0].port_info; - p_ps = &p_pi->port_settings; - - p_ps->parm.baud_rate = mbg_baud_rate[ser_pack.baud]; - - _strncpy_0( p_ps->parm.framing, - mbg_framing_str[pcps_to_mbg_framing_tbl[ser_pack.frame]] ); - - p_ps->parm.handshake = HS_NONE; - - p_ps->str_type = 0; - p_ps->mode = ser_pack.mode; - - p_pi->supp_baud_rates = supp_baud_rates; - p_pi->supp_framings = DEFAULT_FRAMINGS_DCF; - p_pi->supp_str_types = DEFAULT_SUPP_STR_TYPES_DCF; - -} // port_info_from_pcps_serial - - -/*HDR*/ -void pcps_serial_from_port_info( - PCPS_SERIAL *p, - const PORT_INFO_IDX *p_pii -) -{ - PCPS_SER_PACK ser_pack; - const PORT_INFO *p_pi = &p_pii[0].port_info; - const PORT_SETTINGS *p_ps = &p_pi->port_settings; - int framing_idx = get_framing_idx( p_ps->parm.framing ); - int i; - - - ser_pack.baud = get_baud_rate_idx( p_ps->parm.baud_rate ); - - // Translate the common framing index to the corresponding - // number used with the old PCPS_SERIAL parameter. - // This should always return a valid result since the - // framing index is expected to be selected from - // supported framings. - for ( i = 0; i < N_PCPS_FR_DCF; i++ ) - if ( pcps_to_mbg_framing_tbl[i] == framing_idx ) - break; - - ser_pack.frame = i; - - ser_pack.mode = p_ps->mode; - - pcps_pack_serial( &ser_pack ); - - *p = ser_pack.pack; - -} // pcps_serial_from_port_info - - diff --git a/mbglib/common/parmpcps.h b/mbglib/common/parmpcps.h deleted file mode 100644 index 5eb30cb..0000000 --- a/mbglib/common/parmpcps.h +++ /dev/null @@ -1,163 +0,0 @@ - -/************************************************************************** - * - * $Id: parmpcps.h 1.8 2012/10/15 10:05:38Z martin REL_M $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for parmpcps.c. - * - * ----------------------------------------------------------------------- - * $Log: parmpcps.h $ - * Revision 1.8 2012/10/15 10:05:38Z martin - * Cleaned up handling of pragma pack(). - * Revision 1.7 2011/04/01 10:30:51 martin - * Fixed macro syntax for _setup_default_receiver_info_dcf(). - * Revision 1.6 2011/02/16 10:13:12 martin - * Fixed macro syntax for _setup_default_receiver_info_pcps(). - * Revision 1.5 2004/11/09 14:24:58Z martin - * Updated function prototypes. - * Revision 1.4 2004/05/19 07:52:25Z martin - * Fixed macro setting default number of string types. - * Revision 1.3 2004/04/14 09:21:44Z martin - * Pack structures 1 byte aligned. - * Revision 1.2 2003/04/17 10:42:46Z martin - * Moved typedef RECEIVER_PORT_CFG to pcpsdev.h. - * Moved some definitions from parmpcps.c here. - * Removed some global variables. - * Updated function prototypes. - * Revision 1.1 2002/02/19 14:00:19Z MARTIN - * Initial revision - * - **************************************************************************/ - -#ifndef _PARMPCPS_H -#define _PARMPCPS_H - -/* Other headers to be included */ - -#include <pcpsdev.h> -#include <use_pack.h> - - -#ifdef _PARMPCPS - #define _ext - #define _DO_INIT -#else - #define _ext extern -#endif - - -/* Start of header body */ - -#if defined( _USE_PACK ) - #pragma pack( 1 ) // set byte alignment - #define _USING_BYTE_ALIGNMENT -#endif - - -#ifdef __cplusplus -extern "C" { -#endif - - -#define DEFAULT_BAUD_RATES_DCF \ -( \ - MBG_PORT_HAS_300 | \ - MBG_PORT_HAS_600 | \ - MBG_PORT_HAS_1200 | \ - MBG_PORT_HAS_2400 | \ - MBG_PORT_HAS_4800 | \ - 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 | \ - MBG_PORT_HAS_38400 \ -) - - -#define DEFAULT_FRAMINGS_DCF \ -( \ - MBG_PORT_HAS_7E2 | \ - MBG_PORT_HAS_8N1 | \ - MBG_PORT_HAS_8N2 | \ - MBG_PORT_HAS_8E1 \ -) - - -#define DEFAULT_N_STR_TYPE_DCF 1 - -#define DEFAULT_SUPP_STR_TYPES_DCF \ - ( ( 1UL << DEFAULT_N_STR_TYPE_DCF ) - 1 ) - - -/* - * The macro below can be used to initialize a - * RECEIVER_INFO structure for DCF77 receivers - * which don't supply that structure. - * - * Parameters: (RECEIVER_INFO *) _p - */ -#define _setup_default_receiver_info_dcf( _p, _pdev ) \ -do \ -{ \ - memset( (_p), 0, sizeof( *(_p) ) ); \ - \ - (_p)->ticks_per_sec = DEFAULT_GPS_TICKS_PER_SEC; \ - (_p)->n_ucaps = 0; \ - (_p)->n_com_ports = _pcps_has_serial( _pdev ) ? 1 : 0; \ - (_p)->n_str_type = ( (_p)->n_com_ports != 0 ) ? \ - DEFAULT_N_STR_TYPE_DCF : 0; \ -} while ( 0 ) - - -#define DEFAULT_MAX_STR_TYPE 2 //##++ DEFAULT_N_STR_TYPE_GPS - -_ext STR_TYPE_INFO default_str_type_info[DEFAULT_MAX_STR_TYPE] -#ifdef _DO_INIT - = { - { DEFAULT_STR_MODES, "Default Time String", "Time", 0 }, - { DEFAULT_STR_MODES_UCAP, "Capture String", "Cap", 0 } - } -#endif -; - - - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - 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 ) ; - -/* ----- function prototypes end ----- */ - - -#ifdef __cplusplus -} -#endif - - -#if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment - #undef _USING_BYTE_ALIGNMENT -#endif - -/* End of header body */ - - -#undef _ext -#undef _DO_INIT - -#endif /* _PARMPCPS_H */ diff --git a/mbglib/common/pci_asic.h b/mbglib/common/pci_asic.h index 8eb6371..5a3e3d2 100644 --- a/mbglib/common/pci_asic.h +++ b/mbglib/common/pci_asic.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pci_asic.h 1.22 2011/10/05 09:46:12Z martin REL_M $ + * $Id: pci_asic.h 1.31 2018/06/25 12:32:19Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,26 @@ * * ----------------------------------------------------------------------- * $Log: pci_asic.h $ - * Revision 1.22 2011/10/05 09:46:12Z martin + * Revision 1.31 2018/06/25 12:32:19Z 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. + * Revision 1.29 2017/07/04 14:18:03 martin + * Updated minor version for PTP270PEX. + * Revision 1.28 2017/05/10 15:24:21 martin + * Tiny cleanup. + * Revision 1.27 2017/04/25 11:36:30 martin + * Renamed GRC181PEX to GNS181PEX. + * Revision 1.26 2016/09/15 14:55:02 martin + * Support GRC181PEX. + * Added doxgen comments. + * Revision 1.25 2014/10/17 11:38:39 martin + * Updated version info for GPS180PEX. + * Revision 1.24 2013/10/01 15:29:39 martin + * Updated version info for PTP270PEX. + * Revision 1.23 2013/06/26 15:57:07Z martin + * Support GLN180PEX. + * Revision 1.22 2011/10/05 09:46:12 martin * Updated version info for GPS180PEX. * Revision 1.21 2011/09/13 07:36:21Z martin * Updated version info for GPS180PEX. @@ -36,7 +55,7 @@ * Modified syntax of macro _convert_asic_version_number(). * Added macros to deal with the ASIC version number. * Added definition PCI_ASIC_HAS_PGMB_IRQ. - * Added ASIC revision numbers for PEX511, TCR511PEX, and GPS170PEX + * Added ASIC revision numbers for PEX511, TCR511PEX, and GPS170PEX * which fix an IRQ bug with these cards. * Added definitions for PTP270PEX, FRC511PEX, and TCR170PEX. * Revision 1.12 2008/07/21 10:30:00Z martin @@ -62,7 +81,7 @@ * Revision 1.4 2004/10/14 15:01:23 martin * Added support for TCR167PCI. * Revision 1.3 2003/05/13 14:38:55Z MARTIN - * Added ushort fields to unions PCI_ASIC_REG and + * Added ushort fields to unions PCI_ASIC_REG and * PCI_ASIC_ADDON_DATA. * Revision 1.2 2003/04/03 10:56:38 martin * Use unions for registers. @@ -96,77 +115,145 @@ #define _USING_BYTE_ALIGNMENT #endif +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Set of PCI ASIC registers which are writeable once after power-up + **/ typedef struct { uint32_t cfg_class_rev_id; uint16_t cfg_badr_0; uint16_t cfg_dev_id; + } PCI_ASIC_CFG; +/** + * @brief A PCI ASIC register as 32, 16, or 8 bit accessible union + */ typedef union { uint32_t ul; uint16_t us[2]; uint8_t b[4]; + } PCI_ASIC_REG; + +/** + * @brief A data type to hold the PCI ASIC version code + */ typedef uint32_t PCI_ASIC_VERSION; + #define _mbg_swab_asic_version( _p ) _mbg_swab32( _p ) + + +/** + * @brief A data type to hold the PCI ASIC feature flags mask + * + * @see @ref PCI_ASIC_FEATURE_MASKS + */ typedef uint32_t PCI_ASIC_FEATURES; + #define _mbg_swab_asic_features( _p ) _mbg_swab32( _p ) -#define PCI_ASIC_HAS_MM_IO 0x0001 -#define PCI_ASIC_HAS_PGMB_IRQ 0x0002 +/** + * @brief Bit masks used with ::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) + +/** @} anchor PCI_ASIC_FEATURE_MASKS */ + + + +/** + * @brief The addon-data part of a PCI ASIC + */ typedef union { uint32_t ul[4]; uint16_t us[8]; uint8_t b[16]; + } PCI_ASIC_ADDON_DATA; + +/** + * @brief Register layout of a PCI ASIC + */ typedef struct { - PCI_ASIC_CFG cfg; // writeable from add-on once after power-up - PCI_ASIC_VERSION raw_version; - PCI_ASIC_FEATURES features; - PCI_ASIC_REG status_port; - PCI_ASIC_REG control_status; // codes defined below - PCI_ASIC_REG pci_data; // pass byte from PCI bus to add-on - PCI_ASIC_REG reserved_1; - - PCI_ASIC_ADDON_DATA addon_data; // returns data from add-on to PCI bus - PCI_ASIC_ADDON_DATA reserved_2; // currently not implemented + 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_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; -// The following bits are used with the control_status register. -// All other bits are reserved for future use. -// 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 -// microcontroller writes this bit back to the control_status -// register. If the bit is set, the add-on signals /ADD_ON_IRQ -// and ADD_ON_BUSY are asserted. +/** + * @brief Bit masks used with ::PCI_ASIC::control_status + * + * @see ::PCI_ASIC + * + * @anchor PCI_ASIC_CONTROL_STATUS_MASKS @{ */ + +/** + * @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 + * microcontroller writes this bit back to the control_status + * register. If the bit is set, the add-on signals /ADD_ON_IRQ + * and ADD_ON_BUSY are asserted. + */ #define PCI_ASIC_ADD_ON_IRQF 0x00000001UL -// The IRQ flag for the PCI bus is set whenever the add-on -// microcontroller asserts the ASIC's /PCI_IRQ line, or the -// add-on microcontroller sets this bit to 1. It is cleared -// if this bit is written back from the PCI side. If the bit -// is set, an IRQ is asserted on the PCI bus. +/** + * @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 + * add-on microcontroller sets this bit to 1. It is cleared + * if this bit is written back from the PCI side. If the bit + * is set, an IRQ is asserted on the PCI bus. + */ #define PCI_ASIC_PCI_IRQF 0x00010000UL +// NOTE All other bits are reserved for future use. + +/** @} anchor PCI_ASIC_CONTROL_STATUS_MASKS */ + -// The ASIC's address decoder always decodes 8 bits, so -// each device must request at least that number of -// addresses from the PCI BIOS: + +/** + * @brief PCI address range + * + * The ASIC's address decoder 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 @@ -225,34 +312,44 @@ typedef struct _hilo_16( PCI_DEV_TCR511PCI ) \ } -/* - Handling of the version numbers of the PCI interface - chips has changed between the ASICs used for standard PCI - and the EPLDs used to configure the PEX8311 chip - for a specific device. - The macro below 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: -*/ + +/** + * @brief Version number conversion macro + * + * Handling of the version numbers of the PCI interface + * chips has changed between the ASICs used for standard PCI + * and the EPLDs used to configure the PEX8311 chip + * for a specific device. + * + * 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 + */ #define _convert_asic_version_number( _n ) \ ( ( (_n) < 0x100 ) ? ( (_n) << 8 ) : (_n) ) -/* - * Macros to extract the major and minor part of an ASIC version number */ +#define PCPS_ASIC_STR_FMT "%u.%02X" // TODO Or should this be "%u.%02u" +/** + * @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 + */ #define _pcps_asic_version_minor( _v ) \ ( (_v) & 0xFF ) -/* - * Macros to 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 ) \ ( \ @@ -261,87 +358,126 @@ typedef struct ) -/* - The low byte of the converted version number is handled - as a minor version, whereas the remaining upper bytes are - interpreted as a major number which may be specific - for a device. -*/ -enum + +/** + * @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 - PCI_ASIC_MAJOR_TCR180PEX, // PEX EPLD for TCR180PEX - PCI_ASIC_MAJOR_PZF180PEX, // PEX EPLD for PZF180PEX - 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 }; -/* - The minor number increases when a new EPLD image is released. - At least EPLD images with the following "required minor" numbers - should be installed for proper operation. The "current minor" - numbers can be used to check if a newer EPLD image is available: -*/ + + +/** + * @brief 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 + * should be installed for proper operation. The "current minor" + * numbers can be used to check if a newer EPLD image is available. + * + * @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 -#define PCI_ASIC_FIX_HRT_MINOR_PEX511 0x04 // increases HRT accuracy -#define PCI_ASIC_FIX_IRQ_MINOR_PEX511 0x03 // fixes IRQ problem -#define PCI_ASIC_HR_TIME_MINOR_PEX511 0x02 // supports HR time with PEX511 +#define PCI_ASIC_FIX_HRT_MINOR_PEX511 0x04 // Increases HRT accuracy +#define PCI_ASIC_FIX_IRQ_MINOR_PEX511 0x03 // Fixes IRQ problem +#define PCI_ASIC_HR_TIME_MINOR_PEX511 0x02 // Supports HR time with PEX511 #define PCI_ASIC_CURRENT_MINOR_GPS170PEX 0x05 #define PCI_ASIC_REQUIRED_MINOR_GPS170PEX 0x03 -#define PCI_ASIC_ENH_HRT_MINOR_GPS170PEX 0x05 // enhanced MM HRT accuracy -#define PCI_ASIC_FIX_HRT_MINOR_GPS170PEX 0x04 // increases MM HRT accuracy -#define PCI_ASIC_FIX_IRQ_MINOR_GPS170PEX 0x03 // fixes IRQ problem +#define PCI_ASIC_ENH_HRT_MINOR_GPS170PEX 0x05 // Enhanced MM HRT accuracy +#define PCI_ASIC_FIX_HRT_MINOR_GPS170PEX 0x04 // Increases MM HRT accuracy +#define PCI_ASIC_FIX_IRQ_MINOR_GPS170PEX 0x03 // Fixes IRQ problem #define PCI_ASIC_CURRENT_MINOR_TCR511PEX 0x04 #define PCI_ASIC_REQUIRED_MINOR_TCR511PEX 0x03 // 0x04 // EPLD sources shared with PEX511 0x04 -#define PCI_ASIC_FIX_IRQ_MINOR_TCR511PEX 0x03 // fixes IRQ problem, increases HRT accuracy +#define PCI_ASIC_FIX_IRQ_MINOR_TCR511PEX 0x03 // Fixes IRQ problem, increases HRT accuracy -#define PCI_ASIC_CURRENT_MINOR_PTP270PEX 0x02 +#define PCI_ASIC_CURRENT_MINOR_PTP270PEX 0x06 #define PCI_ASIC_REQUIRED_MINOR_PTP270PEX 0x01 -// 0x02 // increased accuracy of IRIG DCLS slopes -// 0x01 // supports inversion of ucap slopes +// 0x06 // Supports 1 PPS pulse shift +// 0x05 // ... +// 0x04 // ... +// 0x03 // ... +// 0x02 // Increased accuracy of IRIG DCLS slopes +// 0x01 // Supports inversion of ucap slopes #define PCI_ASIC_CURRENT_MINOR_FRC511PEX 0x01 #define PCI_ASIC_REQUIRED_MINOR_FRC511PEX 0x01 #define PCI_ASIC_CURRENT_MINOR_TCR170PEX 0x03 #define PCI_ASIC_REQUIRED_MINOR_TCR170PEX 0x02 -#define PCI_ASIC_FIX_EE_ACCESS_TCR170PEX 0x02 // fixes EE access problem after reset -#define PCI_ASIC_FIX_FO_IN_LEVEL_TCR170PEX 0x03 // correct polarity for fiber optic input +#define PCI_ASIC_FIX_EE_ACCESS_TCR170PEX 0x02 // Fixes EE access problem after reset +#define PCI_ASIC_FIX_FO_IN_LEVEL_TCR170PEX 0x03 // Correct polarity for fiber optic input -#define PCI_ASIC_CURRENT_MINOR_GPS180PEX 0x05 +#define PCI_ASIC_CURRENT_MINOR_GPS180PEX 0x06 #define PCI_ASIC_REQUIRED_MINOR_GPS180PEX 0x01 -// 0x01 // updated VHDL compiler and associated PCI primitives +// 0x01 // Updated VHDL compiler and associated PCI primitives // 0x02 // I/O using 3.3V LVTTL // 0x03 // GPS TIC pulse len now 1 sample clock // 0x04 // Enabled PCI IRQ line which had unintentionally been disabled earlier // 0x05 // Increased accuracy of synthesizer output +// 0x06 // T0 AUX Capture used by firmware v2.0x #define PCI_ASIC_CURRENT_MINOR_TCR180PEX 0x00 #define PCI_ASIC_REQUIRED_MINOR_TCR180PEX 0x00 -#define PCI_ASIC_CURRENT_MINOR_PZF180PEX 0x00 +#define PCI_ASIC_CURRENT_MINOR_PZF180PEX 0x01 #define PCI_ASIC_REQUIRED_MINOR_PZF180PEX 0x00 +// 0x01 // ... + +#define PCI_ASIC_CURRENT_MINOR_GLN180PEX 0x00 +#define PCI_ASIC_REQUIRED_MINOR_GLN180PEX 0x00 + +#define PCI_ASIC_CURRENT_MINOR_GNS181PEX 0x00 +#define PCI_ASIC_REQUIRED_MINOR_GNS181PEX 0x00 + +/** @} anchor PCI_ASIC_MINOR_VERSION_NUMBERS */ + +/** + * @brief A structure holding version information for a specific device + * + * @see ::DEFAULT_PCI_ASIC_VERSION_INFO_TABLE + */ typedef struct { unsigned int dev_type_num; unsigned int major; unsigned int current_minor; unsigned int required_minor; + } PCI_ASIC_VERSION_INFO; + +/** + * @brief An initializer for a table of ASIC version information for all known devices + * + * @note GPS180AMC uses the same ASIC as GPS180PEX + * + * @see ::PCI_ASIC_VERSION_INFO + */ #define DEFAULT_PCI_ASIC_VERSION_INFO_TABLE \ { \ { PCPS_TYPE_PEX511, PCI_ASIC_MAJOR_PEX511, PCI_ASIC_CURRENT_MINOR_PEX511, PCI_ASIC_REQUIRED_MINOR_PEX511 }, \ @@ -353,16 +489,13 @@ typedef struct { PCPS_TYPE_GPS180PEX, PCI_ASIC_MAJOR_GPS180PEX, PCI_ASIC_CURRENT_MINOR_GPS180PEX, PCI_ASIC_REQUIRED_MINOR_GPS180PEX }, \ { PCPS_TYPE_TCR180PEX, PCI_ASIC_MAJOR_TCR180PEX, PCI_ASIC_CURRENT_MINOR_TCR180PEX, PCI_ASIC_REQUIRED_MINOR_TCR180PEX }, \ { PCPS_TYPE_PZF180PEX, PCI_ASIC_MAJOR_PZF180PEX, PCI_ASIC_CURRENT_MINOR_PZF180PEX, PCI_ASIC_REQUIRED_MINOR_PZF180PEX }, \ + { PCPS_TYPE_GLN180PEX, PCI_ASIC_MAJOR_GLN180PEX, PCI_ASIC_CURRENT_MINOR_GLN180PEX, PCI_ASIC_REQUIRED_MINOR_GLN180PEX }, \ + { PCPS_TYPE_GPS180AMC, PCI_ASIC_MAJOR_GPS180PEX, PCI_ASIC_CURRENT_MINOR_GPS180PEX, PCI_ASIC_REQUIRED_MINOR_GPS180PEX }, \ + { PCPS_TYPE_GNS181PEX, PCI_ASIC_MAJOR_GNS181PEX, PCI_ASIC_CURRENT_MINOR_GNS181PEX, PCI_ASIC_REQUIRED_MINOR_GNS181PEX }, \ { 0 } \ } -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ @@ -388,4 +521,3 @@ extern "C" { #undef _DO_INIT #endif /* _PCI_ASIC_H */ - diff --git a/mbglib/common/pcpsdefs.h b/mbglib/common/pcpsdefs.h index 5726f58..0d36c5d 100644 --- a/mbglib/common/pcpsdefs.h +++ b/mbglib/common/pcpsdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsdefs.h 1.50 2013/01/30 15:59:54Z martin REL_M $ + * $Id: pcpsdefs.h 1.64 2018/06/25 12:34:23Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,49 @@ * * ----------------------------------------------------------------------- * $Log: pcpsdefs.h $ - * Revision 1.50 2013/01/30 15:59:54Z martin + * Revision 1.64 2018/06/25 12:34:23Z 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(). + * Revision 1.62 2017/07/04 16:24:53 martin + * Moved definitions PCPS_HRT_FRAC_SCALE and PCPS_HRT_FRAC_SCALE_FMT + * back here. + * New types PCPS_SECONDS and PCPS_FRAC_32. + * Fixed typo, wording, and doxygen comments. + * Revision 1.61 2017/04/25 11:38:38 martin + * Renamed GRC181PEX to GNS181PEX. + * Revision 1.60 2017/03/17 12:00:05 martin + * Moved definitions of PCPS_HRT_FRAC_CONVERSION_TYPE, + * PCPS_HRT_BIN_FRAC_SCALE, and PCPS_HRT_FRAC_SCALE_FMT + * to cfg_hlp.h. + * Revision 1.59 2017/01/27 08:11:19 martin + * Fixed macro syntax. + * Revision 1.58 2016/11/08 16:42:52 martin + * New GPS cmd codes PC_GPS_XFEATURE_BUFFER and PC_GPS_TLV_INFO. + * Revision 1.57 2016/11/08 16:40:39 martin + * Doxygen cleanup. + * Revision 1.56 2016/10/26 13:22:41 martin + * Added definitions for GRC181PEX. + * New symbol IRIG_TIME_UNKNOWN_YEAR. + * Removed trailing spaces. + * Updated doxygen comments. + * Revision 1.55 2014/07/17 10:52:24 martin + * Increased safety of firmware builds. + * Revision 1.54 2014/07/17 09:54:19 martin + * New command codes PC_GPS_XMR_HOLDOVER_STATUS + * and PC_GPS_ALL_GPIO_STATUS. + * Huge update and cleanup on doxygen comments. + * Revision 1.53 2014/05/27 10:13:20 martin + * Support GPS180AMC. + * Moved some signal constant definitions to pcpsdefs.h. + * Simplified declaration of code/name tables. + * Huge rework of comments in doxygen format. + * Revision 1.52 2013/09/26 09:02:52Z martin + * Support GNSS API. + * Updated doxygen comments. + * Revision 1.51 2013/06/25 09:51:39 martin + * Support GLN180PEX. + * Revision 1.50 2013/01/30 15:59:54 martin * Updated and fixed some doxygen comments. * Revision 1.49 2012/10/02 18:53:02 martin * Added structure PCPS_TIME_STATUS_X_MASKS. @@ -25,7 +67,7 @@ * Support GPIO configuration. * Support PZF180PEX. * Added commands to read CORR_INFO, read/write TR_DISTANCE, - * PCPS_SYNC_PZF status, and associated structures. + * PCPS_SYNC_PZF status, and associated structures. * Added an initializer for a table of GPS command code/names. * Added definitions MBG_PCPS_FMT_STATUS. * Updated some comments. @@ -70,12 +112,12 @@ * Added new REF type PCPS_REF_MSF. * Revision 1.35 2008/01/17 09:18:46Z daniel * Made comments compatible for doxygen parser. - * No sourcecode changes. + * No sourcecode changes. * Revision 1.34 2007/07/17 08:22:47Z martin * Added support for TCR511PEX and GPS170PEX. * Revision 1.33 2007/05/20 21:39:51Z martin * Added support for PEX511. - * Added PCPS_GET_STATUS_PORT cmd code for devices + * Added PCPS_GET_STATUS_PORT cmd code for devices * that do not support a hardware status port. * Revision 1.32 2007/03/29 12:57:32Z martin * Renamed some TZCODE numbers for unique naming conventions. @@ -107,14 +149,14 @@ * Support configuration of on-board frequency synthesizer. * Revision 1.21 2004/11/09 12:55:32Z martin * Redefined interface data types using C99 fixed-size definitions. - * Added workaround macros for some structure sizes because the C166 - * compiler always reports an even structure size even if the structure - * size is in fact odd, which might lead to different sizes in C166 and + * Added workaround macros for some structure sizes because the C166 + * compiler always reports an even structure size even if the structure + * 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 + * Modifications were required in order to be able to configure IRIG * settings of cards 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 + * 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. * Renamed PC_GPS_STAT to PC_GPS_BVAR_STAT. * Use more specific data types than generic types. @@ -132,12 +174,12 @@ * fill level. * Revision 1.16 2003/04/03 10:48:53 martin * Support for PCI510, GPS169PCI, and TCR510PCI. - * New codes PCPS_GET_REF_OFFS, PCPS_SET_REF_OFFS + * New codes PCPS_GET_REF_OFFS, PCPS_SET_REF_OFFS * and related structures. * New codes PCPS_GET_OPT_INFO, PCPS_SET_OPT_SETTINGS * and related structures. * New codes PCPS_GET_IRIG_INFO, PCPS_SET_IRIG_SETTINGS. - * Preliminary PCPS_TZDL structure and cmd codes + * Preliminary PCPS_TZDL structure and cmd codes * to read/write that structure. * Revision 1.15 2002/08/08 13:24:03 MARTIN * Moved definition of ref time sources here. @@ -201,8 +243,8 @@ * Changes before put under RCS control: * * Revision 1.5 2000/03/24 - * Introduced PCPS_GIVE_SERNUM - * Cleaned up for definitions for serial parameter byte + * Introduced PCPS_GIVE_SERNUM. + * Cleaned up for definitions for serial parameter byte. * Reviewed and updated comments. * * 1998/07/22 @@ -211,7 +253,7 @@ * Reviewed and updated comments. * * 1997/06/12 - * GPS definitions added. + * Added GPS definitions. * * 1996/01/25 * PCPS_TIME redefined from an array of bytes to a structure. @@ -227,6 +269,13 @@ #include <words.h> #include <use_pack.h> +#ifndef _USE_PCPSPRIV + #define _USE_PCPSPRIV _IS_MBG_FIRMWARE +#endif + +#if _USE_PCPSPRIV + #include <pcpspriv.h> +#endif /* Start of header body */ @@ -239,25 +288,30 @@ /** * @brief Enumeration of the ref time signal sources used by Meinberg devices */ -enum +enum PCPS_REF_TYPES { - PCPS_REF_NONE, /**< (unknown or not defined) */ - PCPS_REF_DCF, /**< see http://www.meinberg.de/english/info/dcf77.htm */ - PCPS_REF_GPS, /**< see http://www.meinberg.de/english/info/gps.htm */ - PCPS_REF_IRIG, /**< see http://www.meinberg.de/english/info/irig.htm */ - PCPS_REF_MSF, /**< MSF Receiver (UK) */ - PCPS_REF_PTP, /**< PTP/IEEE1588 network protocol */ - PCPS_REF_FRC, /**< Free Running Clock */ - PCPS_REF_WWVB, /**< WWVB Receiver (US) */ - PCPS_REF_JJY, /**< JJY Receiver (Japan) */ - N_PCPS_REF /**< number of valid ref time sources */ + PCPS_REF_NONE, ///< unknown, or not defined + PCPS_REF_DCF, ///< 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 }; -/* Initializers for the reference source names */ +/** + * @defgroup group_pcps_ref_type_names Reference type names + * + * @see ::PCPS_REF_TYPES + * + * @{ */ -#define PCPS_REF_NAME_NONE_ENG "unknown" -#define PCPS_REF_NAME_NONE_GER "nicht bekannt" +#define PCPS_REF_NAME_NONE_ENG "unknown" +#define PCPS_REF_NAME_NONE_GER "nicht bekannt" #define PCPS_REF_NAME_DCF "DCF77" #define PCPS_REF_NAME_GPS "GPS" #define PCPS_REF_NAME_IRIG "IRIG" @@ -267,7 +321,14 @@ enum #define PCPS_REF_NAME_WWVB "WWVB" #define PCPS_REF_NAME_JJY "JJY" +/** @} @defgroup group_pcps_ref_type_names */ + +/** + * @brief Initializer for an array of English reference type names + * + * @see ::PCPS_REF_TYPES + */ #define PCPS_REF_NAMES_ENG \ { \ PCPS_REF_NAME_NONE_ENG, \ @@ -282,6 +343,11 @@ enum } +/** + * @brief Initializer for a multi-language array of reference type names + * + * @see ::PCPS_REF_TYPES + */ #define PCPS_REF_NAMES_LSTR \ { \ { PCPS_REF_NAME_NONE_ENG, PCPS_REF_NAME_NONE_GER }, \ @@ -298,14 +364,23 @@ enum /** - * @brief Meinberg PCI vendor ID (assigned by PCI SIG) + * @brief Meinberg PCI vendor ID (assigned by the PCI SIG) + * + * @see @ref MEINBERG_PCI_DEVICE_IDS */ #define PCI_VENDOR_MEINBERG 0x1360 -/* PCI device ID numbers (assigned by Meinberg) * - * High byte: type of ref time source - * Low Byte: enumeration of device types - */ + +/** + * @brief PCI device IDs assigned by Meinberg + * + * High byte: type of ref time source, 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 ) #define PCI_DEV_PCI510 ( ( PCPS_REF_DCF << 8 ) | 0x03 ) @@ -319,6 +394,9 @@ enum #define PCI_DEV_GPS170PCI ( ( PCPS_REF_GPS << 8 ) | 0x04 ) #define PCI_DEV_GPS170PEX ( ( PCPS_REF_GPS << 8 ) | 0x05 ) #define PCI_DEV_GPS180PEX ( ( PCPS_REF_GPS << 8 ) | 0x06 ) +#define PCI_DEV_GLN180PEX ( ( PCPS_REF_GPS << 8 ) | 0x07 ) +#define PCI_DEV_GPS180AMC ( ( PCPS_REF_GPS << 8 ) | 0x08 ) +#define PCI_DEV_GNS181PEX ( ( PCPS_REF_GPS << 8 ) | 0x09 ) #define PCI_DEV_TCR510PCI ( ( PCPS_REF_IRIG << 8 ) | 0x01 ) #define PCI_DEV_TCR167PCI ( ( PCPS_REF_IRIG << 8 ) | 0x02 ) @@ -331,37 +409,56 @@ enum #define PCI_DEV_FRC511PEX ( ( PCPS_REF_FRC << 8 ) | 0x01 ) +/** @} anchor MEINBERG_PCI_DEVICE_IDS */ -// definitions used for the status port register -// (not to be intermixed with PCPS_TIME_STATUS) -typedef uint8_t PCPS_STATUS_PORT; /**< see @ref group_status_port "Bitmask" */ /** - * @defgroup group_status_port Bit masks of PCPS_STATUS_PORT + * @defgroup group_status_port Definitions used with the status port + * + * The status port register on bus-level cards reflects some hardware + * signals (e.g. DCF-77 modulation), and flags used for communication + * with the card (e.g. the BUSY flag, ::PCPS_ST_BUSY). + * + * @note Must not be confused with ::PCPS_TIME_STATUS which returns + * the synchronization status and associated information * - * Bit definitions used with the #PCPS_STATUS_PORT register. + * @{ */ + +/** + * @brief Type of the status register port + */ +typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS + + +/** + * @brief Bit masks used with ::PCPS_STATUS_PORT * - * The flags #PCPS_ST_SEC and #PCPS_ST_MIN are cleared whenever the clock - * is read, so they are not very reliable in multitasking environments. + * 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. * - * @note The PCPS_ST_IRQF flag originates from old ISA cards. + * 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 certain card has generated an IRQ on the PC bus. + * if a particular card has generated an IRQ on the PC bus. * - * The macro _pcps_ddev_has_gen_irq() cares about this and should be used + * The macro ::_pcps_ddev_has_gen_irq cares about this and should be used * to determine in a portable way whether a card has generated an IRQ. * - * @{ */ + * @anchor PCPS_STATUS_PORT_BIT_MASKS @{ */ + +#define PCPS_ST_BUSY 0x01 ///< the clock is busy filling the output FIFO +#define PCPS_ST_IRQF 0x02 ///< the clock has generated an IRQ on the PC bus (ISA 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 -#define PCPS_ST_BUSY 0x01 /**< the clock is busy filling the output FIFO */ -#define PCPS_ST_IRQF 0x02 /**< the clock has generated an IRQ on the PC bus (ISA only)*/ -#define PCPS_ST_MOD 0x20 /**< the raw demodulated DCF77 signal */ -#define PCPS_ST_SEC 0x40 /**< seconds have changed since last reading */ -#define PCPS_ST_MIN 0x80 /**< minutes have changed since last reading */ +/** @} anchor PCPS_STATUS_PORT_BIT_MASKS */ + +/** @} defgroup group_status_port */ -/** @} group_status_port */ /** * A format string to be used with snprintb() which is available on some Unix @@ -373,624 +470,556 @@ typedef uint8_t PCPS_STATUS_PORT; /**< see @ref group_status_port "Bitmask" */ -/** @defgroup group_cmd_bytes Command bytes used to access the device - - The commands described below are used to access computer peripherals - manufactured by Meinberg. - - The header files pcpsdev.h and pcpsdrvr.h contain macros which can be - used to check if a detected device supports a certain feature or command. - If checking is required then the name of the macro is given in the - comments below. - - Some commands expect parameters to be passed to the board. In that - case, the board returns the number of parameter bytes expected when - the command code is passed. Every parameter byte has to be supplied - to the board exactly like a command byte. - Refer to function pcps_write_data() and the macro _pcps_write_var() - for details. - - - - #PCPS_GIVE_TIME<br> - Return a PCPS_TIME structure with current date, - time and status. Supported by all clocks. - - - #PCPS_GIVE_TIME_NOCLEAR<br> - Same as #PCPS_GIVE_TIME but the bits #PCPS_ST_SEC - and #PCPS_ST_MIN (see pcpsdev.h) of the status - port are not cleared. - Supported by all clocks except PC31/PS31 with - firmware version older than v3.0. - This is mainly used by the DOS TSR and should - not be used in other environments. - - - #PCPS_GIVE_SYNC_TIME<br> - Return a ::PCPS_TIME structure with date and time - of last synchronization of the clock or - the last time set via the interface. - _pcps_has_sync_time() checks whether supported. - - - #PCPS_GIVE_HR_TIME<br> - Return a PCPS_HR_TIME structure with current - date, time and status. This command should be - used to read the clock with higher resolution. - _pcps_has_hr_time() checks whether supported. - - - #PCPS_GIVE_IRIG_TIME<br> - Return a PCPS_IRIG_TIME structure with day-of-year, - time and status as decoded from the IRIG signal. - _pcps_has_irig_time() checks whether supported. - - - #PCPS_SET_TIME<br> - Set the board date, time and status. This - command expects sizeof( ::PCPS_STIME ) parameter - bytes. - _pcps_can_set_time() checks whether supported. - - - #PCPS_SET_EVENT_TIME<br> - Send a high resolution time stamp to the clock to - configure a %UTC time when the clock shall generate - some event. This command expects a PCPS_TIME_STAMP - parameter. - _pcps_has_event_time() checks whether supported. - (requires custom GPS CERN firmware) - - - #PCPS_IRQ_NONE<br> - Disable the board's hardware IRQ<br> - - #PCPS_IRQ_1_SEC<br> - Enable hardware IRQs once per second<br> - - #PCPS_IRQ_1_MIN<br> - Enable hardware IRQs once per minute<br> - - #PCPS_IRQ_10_MIN<br> - Enable hardware IRQs once per 10 minutes<br> - - #PCPS_IRQ_30_MIN<br> - Enable hardware IRQs once per 30 minutes<br> - - - #PCPS_GET_SERIAL<br> - #PCPS_SET_SERIAL<br> - These commands read or set the configuration - of a clock's serial port COM0. The commands - expect PCPS_SERIAL_BYTES parameter bytes and - should be used preferably with the DCF77 - clocks which have only one COM port. - _pcps_has_serial() checks whether supported. - Recent GPS clocks' COM ports should be cfg'd - using the structures RECEIVER_INFO, PORT_INFO, - and STR_TYPE_INFO. - _pcps_has_receiver_info() checks whether - these are supported. If they are not, then - the code #PC_GPS_PORT_PARM together with the - #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA - commands should be used. - - - #PCPS_GET_TZCODE<br> - #PCPS_SET_TZCODE<br> - These commands read or set a DCF77 clock's - time zone code and should be used preferably - with the newer DCF77 clocks which have limited - support of different time zones. - _pcps_has_tzcode() checks whether supported. - A GPS clock's time zone must be cfg'd using - the code #PC_GPS_TZDL together with the - #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA - commands. - - - #PCPS_GET_PCPS_TZDL<br> - #PCPS_SET_PCPS_TZDL<br> - These commands read or set a DCF77 clock's - time zone / daylight saving configuration. - _pcps_has_pcps_tzdl() checks whether supported. - A GPS clock's time zone must be cfg'd using - the code #PC_GPS_TZDL together with the - #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA - commands. - - - #PCPS_GET_REF_OFFS<br> - #PCPS_SET_REF_OFFS<br> - These commands can be used to configure the - reference time offset from %UTC for clocks - which can't determine the offset automatically, - e.g. from an IRIG input signal. - _pcps_has_ref_offs() checks whether supported. - - - #PCPS_GET_OPT_INFO<br> - #PCPS_SET_OPT_SETTINGS<br> - These commands can be used to configure some - optional settings, controlled by flags. - When reading, the clock returns a MBG_OPT_INFO - structure which contains the supported values, - plus the current settings. - When writing, clocks accepts a MBG_OPT_SETTINGS - structure only which contain the desired settings - of the supported flags only. - _pcps_has_opt_flags() checks whether supported. - - - #PCPS_GET_IRIG_RX_INFO<br> - #PCPS_SET_IRIG_RX_SETTINGS<br> - #PCPS_GET_IRIG_TX_INFO<br> - #PCPS_SET_IRIG_TX_SETTINGS<br> - These commands can be used to configure IRIG - inputs and outputs.<br> - When reading, the clock returns an IRIG_INFO - structure which contains the supported values, - plus the current settings.<br> - When writing, clocks accepts an IRIG_SETTINGS - structure only which contain the desired settings - only. _pcps_is_irig_rx() and _pcps_is_irig_tx() - check whether supported. - - - #PCPS_GET_IRIG_CTRL_BITS<br> - This command can be used to retrieve the control function - bits of the latest IRIG input frame. Those bits may carry - some well-known information as in the IEEE1344 code, but - may also contain some customized information, depending on - the IRIG frame type and the configuration of the IRIG generator. - So these bits are returned as-is and must be interpreted - by the application. - _pcps_has_irig_ctrl_bits() checks whether supported. - - - #PCPS_GET_SYNTH<br> - #PCPS_SET_SYNTH<br> - #PCPS_GET_SYNTH_STATE<br> - These commands can be used to configure an on-board - frequency synthesizer and query the synthesizer - status. The commands are only supported if the board - supports the RECEIVER_INFO structure and the flag - #GPS_HAS_SYNTH is set in the RECEIVER_INFO::features. - _pcps_has_synth() checks whether supported. - The structures SYNTH and SYNTH_STATE used with these - commands are defined in gpsdefs.h. - - - #PCPS_GIVE_FW_ID_1<br> - #PCPS_GIVE_FW_ID_2<br> - Returns the first/second block of PCPS_FIFO_SIZE - characters of the firmware ID string. These - commands can be used to check if the board - responds properly. This is done by the clock - detection functions. - - - #PCPS_GIVE_SERNUM<br> - Returns PCPS_FIFO_SIZE characters of the - clock's serial number. - _pcps_has_sernum() checks whether supported. - - - #PCPS_GENERIC_IO<br> - Generic I/O read and write. Can be used to query - specific data, e.g. a selected element of an array. - _pcps_has_generic_io() checks whether supported. - - - #PCPS_GET_DEBUG_STATUS<br> - This command reads a MBG_DEBUG_STATUS structure - which represents the internal status of the - IRIG decoder and some additional debug info. - _pcps_has_debug_status() checks whether supported. - - - #PCPS_READ_GPS_DATA<br> - #PCPS_WRITE_GPS_DATA<br> - These commands are used by the functions - pcps_read_gps_data() and pcps_write_gps_data() - to read or write large data structures to - Meinberg GPS plug-in clocks. - _pcps_is_gps() checks whether supported. - - - #PCPS_CLR_UCAP_BUFF<br> - Clear a clock's time capture buffer. - _pcps_can_clr_ucap_buff() checks whether - supported. - - - #PCPS_GIVE_UCAP_ENTRIES<br> - Read a PCPS_UCAP_ENTRIES structure which - reports the max number of entries and the - currently used number of entries in the - user capture buffer. - _pcps_has_ucap() checks whether supported. - - - #PCPS_GIVE_UCAP_EVENT<br> - Read capture events using a PCPS_HR_TIME - structure. This is faster than reading using the - GPS command #PC_GPS_UCAP. If no capture event is - available then the structure is filled with 0s. - _pcps_has_ucap() checks whether supported. - - - #PCPS_GET_CORR_INFO<br> - Read PZF correlation info using a CORR_INFO - structure. - _pcps_has_pzf() checks whether supported. - - - #PCPS_GET_TR_DISTANCE<br> - #PCPS_SET_TR_DISTANCE<br> - Read or write distance from the RF transmitter. - This is used to compensate the RF propagation delay - for PZF receivers. - _pcps_has_tr_distance() checks whether supported. - - - #PCPS_CLR_EVT_LOG<br> - Clear on-board event log. - _pcps_has_evt_log() checks whether supported. - - - #PCPS_NUM_EVT_LOG_ENTRIES<br> - Read max number of num event log entries which can - be saved on the board, and how many entries actually - have been saved. - _pcps_has_evt_log() checks whether supported. - - - #PCPS_FIRST_EVT_LOG_ENTRY<br> - - #PCPS_NEXT_EVT_LOG_ENTRY<br> - Read first (oldest) or next event log entry. - _pcps_has_evt_log() checks whether supported. - - - #PCPS_FORCE_RESET<br> - Resets the microprocessor on the device. This is - for special test scenarios only and should not be - used by standard applications since this may lock up - the PC. - - The command codes listed above are defined below. - - @{ */ - - -#if _IS_MBG_FIRMWARE //##++ - -// These group codes are obsolete and should be removed. -// The explicite command codes defined below should be used instead. -#define PCPS_GIVE_TIME_GROUP 0x00 -#define PCPS_SET_TIME_GROUP 0x10 -#define PCPS_IRQ_GROUP 0x20 -#define PCPS_CFG_GROUP 0x30 -#define PCPS_GIVE_DATA_GROUP 0x40 -#define PCPS_GPS_DATA_GROUP 0x50 -#define PCPS_CTRL_GROUP 0x60 -#define PCPS_CFG2_GROUP 0x70 - -#endif - +/** + * @brief Command codes used to communicate with bus level devices + * + * These commands are used for low level access to bus-level devices + * manufactured by Meinberg. + * + * Applications should instead use the API functions declared in mbgdevio.h. + * + * The header files pcpsdev.h and pcpsdrvr.h contain macros which can be + * used to check if a detected device supports a certain feature or command. + * If checking is required then the name of the macro is given in the + * comments associated with the command codes. + * + * Some commands expect parameters to be passed to the board. In that + * case, the board returns the number of parameter bytes expected when + * the command code is passed. Every parameter byte has to be supplied + * to the board exactly like a command byte. + * + * Refer to function ::pcps_write and the macro ::_pcps_write_var + * for details. + * + * - ::PCPS_GIVE_TIME<br> + * Return a ::PCPS_TIME structure with current date, + * time and status. Supported by all clocks. + * + * - ::PCPS_GIVE_TIME_NOCLEAR<br> + * Same as ::PCPS_GIVE_TIME but the bits ::PCPS_ST_SEC + * and ::PCPS_ST_MIN of the status port are not cleared. + * Supported by all clocks except PC31/PS31 with + * firmware version older than v3.0. + * This is mainly used by the DOS TSR and should + * not be used in other environments. + * + * - ::PCPS_GIVE_SYNC_TIME<br> + * Return a ::PCPS_TIME structure with date and time + * of last synchronization of the clock or + * the last time set via the interface. + * ::_pcps_has_sync_time checks whether supported. + * + * - ::PCPS_GIVE_HR_TIME<br> + * Return a ::PCPS_HR_TIME structure with current + * date, time and status. This command should be + * used to read the clock with higher resolution. + * ::_pcps_has_hr_time checks whether supported. + * + * - ::PCPS_GIVE_IRIG_TIME<br> + * Return a ::PCPS_IRIG_TIME structure with day-of-year, + * time and status as decoded from the IRIG signal. + * ::_pcps_has_irig_time checks whether supported. + * + * - ::PCPS_SET_TIME<br> + * Set the board date, time and status. This command + * expects sizeof( ::PCPS_STIME ) parameter bytes. + * ::_pcps_can_set_time checks whether supported. + * + * - ::PCPS_SET_EVENT_TIME<br> + * Send a high resolution time stamp to the clock to + * configure a %UTC time when the clock shall generate + * some event. This command expects a ::PCPS_TIME_STAMP + * parameter. + * ::_pcps_has_event_time checks whether supported. + * (requires custom GPS CERN firmware) + * + * - ::PCPS_IRQ_NONE<br> + * Disable the card's hardware IRQ<br> + * - ::PCPS_IRQ_1_SEC<br> + * Enable hardware IRQs once per second<br> + * - ::PCPS_IRQ_1_MIN<br> + * Enable hardware IRQs once per minute (deprecated)<br> + * - ::PCPS_IRQ_10_MIN<br> + * Enable hardware IRQs once per 10 minutes (deprecated)<br> + * - ::PCPS_IRQ_30_MIN<br> + * Enable hardware IRQs once per 30 minutes (deprecated)<br> + * + * - ::PCPS_GET_SERIAL<br> + * ::PCPS_SET_SERIAL<br> + * Deprecated. Read or write the configuration of a card's + * serial port COM0 in ::PCPS_SERIAL format. + * ::_pcps_has_serial checks whether supported. + * Newer cards 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 + * with older DCF77 receivers which have limited + * support of different time zones. + * ::_pcps_has_tzcode checks whether supported. + * Most newer devices support the ::TZDL structure which can be + * read or written using ::PC_GPS_TZDL. + * + * - ::PCPS_GET_PCPS_TZDL<br> + * ::PCPS_SET_PCPS_TZDL<br> + * Read or write time zone / daylight saving information + * in ::PCPS_TZDL format. + * ::_pcps_has_pcps_tzdl checks whether supported. + * + * - ::PCPS_GET_REF_OFFS<br> + * ::PCPS_SET_REF_OFFS<br> + * These commands can be used to configure the + * reference time offset from %UTC for clocks + * which can't determine the offset automatically, + * e.g. from an IRIG input signal. + * ::_pcps_has_ref_offs checks whether supported. + * + * - ::PCPS_GET_OPT_INFO<br> + * ::PCPS_SET_OPT_SETTINGS<br> + * These commands can be used to configure some + * optional settings, controlled by flags. + * When reading, the clock returns a ::MBG_OPT_INFO + * structure which contains the supported values, + * plus the current settings. + * When writing, clocks accepts a ::MBG_OPT_SETTINGS + * structure only which contain the desired settings + * of the supported flags only. + * ::_pcps_has_opt_flags checks whether supported. + * + * - ::PCPS_GET_IRIG_RX_INFO<br> + * ::PCPS_SET_IRIG_RX_SETTINGS<br> + * ::PCPS_GET_IRIG_TX_INFO<br> + * ::PCPS_SET_IRIG_TX_SETTINGS<br> + * These commands can be used to configure IRIG + * inputs and outputs.<br> + * When reading, the clock returns an ::IRIG_INFO + * structure which contains the supported values, + * plus the current settings.<br> + * When writing, clocks accepts an ::IRIG_SETTINGS + * structure only which contain the desired settings + * only. ::_pcps_is_irig_rx and ::_pcps_has_irig_tx + * check whether supported. + * + * - ::PCPS_GET_IRIG_CTRL_BITS<br> + * This command can be used to retrieve the control function + * bits of the latest IRIG input frame. Those bits may carry + * some well-known information as in the IEEE 1344 code, but + * may also contain some customized information, depending on + * the IRIG frame type and the configuration of the IRIG generator. + * So these bits are returned as-is and must be interpreted + * by the application. + * ::_pcps_has_irig_ctrl_bits checks whether supported. + * + * - ::PCPS_GET_SYNTH<br> + * ::PCPS_SET_SYNTH<br> + * ::PCPS_GET_SYNTH_STATE<br> + * These commands can be used to configure an on-board + * frequency synthesizer and query the synthesizer + * status. The commands are only supported if the board + * supports the ::RECEIVER_INFO structure and the flag + * #GPS_HAS_SYNTH is set in the ::RECEIVER_INFO::features. + * ::_pcps_has_synth checks whether supported. + * The structures ::SYNTH and ::SYNTH_STATE used with these + * commands are defined in gpsdefs.h. + * + * - ::PCPS_GIVE_FW_ID_1<br> + * ::PCPS_GIVE_FW_ID_2<br> + * Returns the first/second block of ::PCPS_FIFO_SIZE + * characters of the firmware ID string. These + * commands can be used to check if the board + * responds properly. This is done by the clock + * detection functions. + * + * - ::PCPS_GIVE_SERNUM<br> + * Returns ::PCPS_FIFO_SIZE characters of the + * clock's serial number. + * ::_pcps_has_sernum checks whether supported. + * + * - ::PCPS_GENERIC_IO<br> + * Generic I/O read and write. Can be used to query + * specific data, e.g. a selected element of an array. + * ::_pcps_has_generic_io checks whether supported. + * + * - ::PCPS_GET_DEBUG_STATUS<br> + * This command reads an ::MBG_DEBUG_STATUS structure + * which represents the internal status of the + * IRIG decoder and some additional debug info. + * ::_pcps_has_debug_status checks whether supported. + * + * - ::PCPS_READ_GPS_DATA<br> + * ::PCPS_WRITE_GPS_DATA<br> + * These commands are used by the functions + * ::pcps_read_gps and ::pcps_write_gps + * to read or write large data structures to + * Meinberg GPS plug-in clocks. + * ::_pcps_is_gps checks whether supported. + * + * - ::PCPS_CLR_UCAP_BUFF<br> + * Clear a clock's time capture buffer. + * ::_pcps_can_clr_ucap_buff checks whether + * supported. + * + * - ::PCPS_GIVE_UCAP_ENTRIES<br> + * Read a ::PCPS_UCAP_ENTRIES structure which + * reports the max number of entries and the + * currently used number of entries in the + * user capture buffer. + * ::_pcps_has_ucap checks whether supported. + * + * - ::PCPS_GIVE_UCAP_EVENT<br> + * Read capture events using a PCPS_HR_TIME + * structure. This is faster than reading using the + * GPS command ::PC_GPS_UCAP. If no capture event is + * available then the returned structure is all 0. + * ::_pcps_has_ucap checks whether supported. + * + * - ::PCPS_GET_CORR_INFO<br> + * Read PZF correlation info using a ::CORR_INFO + * structure. + * ::_pcps_has_pzf checks whether supported. + * + * - ::PCPS_GET_TR_DISTANCE<br> + * ::PCPS_SET_TR_DISTANCE<br> + * Read or write distance from the RF transmitter. + * This is used to compensate the RF propagation delay + * for PZF receivers. + * ::_pcps_has_tr_distance checks whether supported. + * + * - ::PCPS_CLR_EVT_LOG<br> + * Clear on-board event log. + * ::_pcps_has_evt_log checks whether supported. + * + * - ::PCPS_NUM_EVT_LOG_ENTRIES<br> + * Read max. number of num event log entries which can + * be saved on the board, and how many entries have currently + * been saved. + * ::_pcps_has_evt_log checks whether supported. + * + * - ::PCPS_FIRST_EVT_LOG_ENTRY<br> + * ::PCPS_NEXT_EVT_LOG_ENTRY<br> + * Read first (oldest) or next event log entry. + * ::_pcps_has_evt_log checks whether supported. + * + * - ::PCPS_FORCE_RESET<br> + * Resets the card's hardware. 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 -#define PCPS_GIVE_TIME_NOCLEAR 0x01 -#define PCPS_GIVE_SYNC_TIME 0x02 // only supported if _pcps_has_sync_time() -#define PCPS_GIVE_HR_TIME 0x03 // only supported if _pcps_has_hr_time() -#define PCPS_GIVE_IRIG_TIME 0x04 // only supported if _pcps_has_irig_time() +#define PCPS_SET_TIME 0x10 ///< (-w) Set on-board time, see ::PCPS_STIME. Returns ::MBG_ERR_STIME on error. -#define PCPS_SET_TIME 0x10 -/* on error, return PCPS_ERR_STIME */ +#define PCPS_SET_EVENT_TIME 0x14 ///< (-w) Write event time as ::PCPS_TIME_STAMP, only if ::_pcps_has_event_time -/* Attention: The code below can be used EXCLUSIVELY */ -/* with a GPS167PCI with customized CERN firmware !! */ -/* _pcps_has_event_time() checks whether supported. */ -#define PCPS_SET_EVENT_TIME 0x14 +#define PCPS_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 -#define PCPS_IRQ_1_SEC 0x21 -#define PCPS_IRQ_1_MIN 0x22 -#define PCPS_IRQ_10_MIN 0x24 -#define PCPS_IRQ_30_MIN 0x28 +#define PCPS_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 -#define PCPS_SET_SERIAL 0x31 -/* on error, return PCPS_ERR_CFG */ +#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 -typedef uint8_t PCPS_SERIAL; +#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_TZCODE 0x32 -#define PCPS_SET_TZCODE 0x33 -/* on error, return PCPS_ERR_CFG */ +#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 -typedef uint8_t PCPS_TZCODE; +#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 -/** - * @brief Enumeration of codes used with PCPS_TZCODE - */ -enum PCPS_TZCODES -{ - PCPS_TZCODE_CET_CEST, /* default as broadcasted by DCF77 (UTC+1h/UTC+2h) */ - PCPS_TZCODE_CET, /* always CET (UTC+1h), discard DST */ - PCPS_TZCODE_UTC, /* always %UTC */ - PCPS_TZCODE_EET_EEST, /* East European Time, CET/CEST + 1h */ - N_PCPS_TZCODE /* the number of valid codes */ -}; +#define PCPS_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 -/* the definitions below are for compatibily only: */ -#define PCPS_TZCODE_MEZMESZ PCPS_TZCODE_CET_CEST -#define PCPS_TZCODE_MEZ PCPS_TZCODE_CET -#define PCPS_TZCODE_OEZ PCPS_TZCODE_EET_EEST +#define PCPS_GET_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_GET_PCPS_TZDL 0x34 -#define PCPS_SET_PCPS_TZDL 0x35 -/* on error, return PCPS_ERR_CFG */ +#define PCPS_GET_STATUS_PORT 0x4B ///< (r-) Read ::PCPS_STATUS_PORT +#define PCPS_GET_DEBUG_STATUS 0x4C ///< (r-) Read ::MBG_DEBUG_STATUS, only if ::_pcps_has_debug_status +/// @note Command codes 0x4D, 0x4E, and 0x4F are reserved. -/** - * The structures below can be used to configure a clock's - * time zone/daylight saving setting. This structure is shorter - * than the TZDL structure used with GPS clocks. - */ -typedef struct -{ - // The year_or_wday field below contains the full year number - // or 0..6 == Sun..Sat if the DL_AUTO_FLAG is set; see below. - uint16_t year_or_wday; - uint8_t month; - uint8_t mday; - uint8_t hour; - uint8_t min; -} PCPS_DL_ONOFF; +#define 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 _mbg_swab_pcps_dl_onoff( _p ) \ -{ \ - _mbg_swab16( &(_p)->year_or_wday ); \ -} +#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 -/** - * If the field year_or_wday is or'ed with the constant DL_AUTO_FLAG - * defined below then this means that start and end of daylight saving - * time shall be computed automatically for each year. In this case - * the remaining bits represent the day-of-week after the specified - * mday/month at which the change shall occur. If that flag is not set - * then the field contains the full four-digit year number and the - * mday/month values specify the exact date of that year. - */ -#define DL_AUTO_FLAG 0x8000 // also defined in gpsdefs.h +#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 -typedef struct -{ - int16_t offs; /**< offset from %UTC to local time [min] */ - int16_t offs_dl; /**< additional offset if DST enabled [min] */ - PCPS_DL_ONOFF tm_on; /**< date/time when daylight saving starts */ - PCPS_DL_ONOFF tm_off; /**< date/time when daylight saving ends */ -} PCPS_TZDL; +#define 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 _mbg_swab_pcps_tzdl( _p ) \ -{ \ - _mbg_swab16( &(_p)->offs ); \ - _mbg_swab16( &(_p)->offs_dl ); \ - _mbg_swab_pcps_dl_onoff( &(_p)->tm_on ); \ - _mbg_swab_pcps_dl_onoff( &(_p)->tm_off ); \ -} +#define PCPS_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 */ -#define PCPS_GET_REF_OFFS 0x36 -#define PCPS_SET_REF_OFFS 0x37 -/* on error, return PCPS_ERR_CFG */ -/* The associated type MBG_REF_OFFS is defined in gpsdefs.h. */ +#if _IS_MBG_FIRMWARE -#define PCPS_GET_OPT_INFO 0x38 -#define PCPS_SET_OPT_SETTINGS 0x39 -/* on error, return PCPS_ERR_CFG */ +/** + * @brief 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 @{ */ -/* The associated structures MBG_OPT_INFO and MBG_OPT_SETTINGS - are defined in gpsdefs.h. */ +#define PCPS_GIVE_TIME_GROUP 0x00 +#define PCPS_SET_TIME_GROUP 0x10 +#define PCPS_IRQ_GROUP 0x20 +#define PCPS_CFG_GROUP 0x30 +#define PCPS_GIVE_DATA_GROUP 0x40 +#define PCPS_GPS_DATA_GROUP 0x50 +#define PCPS_CTRL_GROUP 0x60 +#define PCPS_CFG2_GROUP 0x70 +/** @} anchor PCPS_CMD_GROUP_CODES */ -#define PCPS_GET_IRIG_RX_INFO 0x3A -#define PCPS_SET_IRIG_RX_SETTINGS 0x3B -/* on error, return PCPS_ERR_CFG */ +#endif // _IS_MBG_FIRMWARE -#define PCPS_GET_IRIG_TX_INFO 0x3C -#define PCPS_SET_IRIG_TX_SETTINGS 0x3D -/* on error, return PCPS_ERR_CFG */ -/* The associated structures IRIG_INFO and IRIG_SETTINGS - are defined in gpsdefs.h. */ +#if !defined( MBG_CMD_TABLE_EXT ) + #define MBG_CMD_TABLE_EXT _mbg_cn_table_end() +#endif -#define PCPS_GET_SYNTH 0x3E -#define PCPS_SET_SYNTH 0x3F -/* on error, return PCPS_ERR_CFG */ +/** + * @brief An initializer for a table of code/name entries of non-GPS commands. + * + * This can e.g. initialize an array of ::MBG_CODE_NAME_TABLE_ENTRY elements + * and may be helpful when debugging. + * + * @see @ref PCPS_CMD_CODES + */ +#define PCPS_CMD_CODES_TABLE \ +{ \ + _mbg_cn_table_entry( PCPS_GIVE_TIME ), /* 0x00 */ \ + _mbg_cn_table_entry( PCPS_GIVE_TIME_NOCLEAR ), /* 0x01 */ \ + _mbg_cn_table_entry( PCPS_GIVE_SYNC_TIME ), /* 0x02 */ \ + _mbg_cn_table_entry( PCPS_GIVE_HR_TIME ), /* 0x03 */ \ + _mbg_cn_table_entry( PCPS_GIVE_IRIG_TIME ), /* 0x04 */ \ + _mbg_cn_table_entry( PCPS_SET_TIME ), /* 0x10 */ \ + _mbg_cn_table_entry( PCPS_SET_EVENT_TIME ), /* 0x14 */ \ + _mbg_cn_table_entry( PCPS_IRQ_NONE ), /* 0x20 */ \ + _mbg_cn_table_entry( PCPS_IRQ_1_SEC ), /* 0x21 */ \ + _mbg_cn_table_entry( PCPS_IRQ_1_MIN ), /* 0x22 */ \ + _mbg_cn_table_entry( PCPS_IRQ_10_MIN ), /* 0x24 */ \ + _mbg_cn_table_entry( PCPS_IRQ_30_MIN ), /* 0x28 */ \ + _mbg_cn_table_entry( PCPS_GET_SERIAL ), /* 0x30 */ \ + _mbg_cn_table_entry( PCPS_SET_SERIAL ), /* 0x31 */ \ + _mbg_cn_table_entry( PCPS_GET_TZCODE ), /* 0x32 */ \ + _mbg_cn_table_entry( PCPS_SET_TZCODE ), /* 0x33 */ \ + _mbg_cn_table_entry( PCPS_GET_PCPS_TZDL ), /* 0x34 */ \ + _mbg_cn_table_entry( PCPS_SET_PCPS_TZDL ), /* 0x35 */ \ + _mbg_cn_table_entry( PCPS_GET_REF_OFFS ), /* 0x36 */ \ + _mbg_cn_table_entry( PCPS_SET_REF_OFFS ), /* 0x37 */ \ + _mbg_cn_table_entry( PCPS_GET_OPT_INFO ), /* 0x38 */ \ + _mbg_cn_table_entry( PCPS_SET_OPT_SETTINGS ), /* 0x39 */ \ + _mbg_cn_table_entry( PCPS_GET_IRIG_RX_INFO ), /* 0x3A */ \ + _mbg_cn_table_entry( PCPS_SET_IRIG_RX_SETTINGS ), /* 0x3B */ \ + _mbg_cn_table_entry( PCPS_GET_IRIG_TX_INFO ), /* 0x3C */ \ + _mbg_cn_table_entry( PCPS_SET_IRIG_TX_SETTINGS ), /* 0x3D */ \ + _mbg_cn_table_entry( PCPS_GET_SYNTH ), /* 0x3E */ \ + _mbg_cn_table_entry( PCPS_SET_SYNTH ), /* 0x3F */ \ + _mbg_cn_table_entry( PCPS_GIVE_FW_ID_1 ), /* 0x40 */ \ + _mbg_cn_table_entry( PCPS_GIVE_FW_ID_2 ), /* 0x41 */ \ + _mbg_cn_table_entry( PCPS_GIVE_SERNUM ), /* 0x42 */ \ + _mbg_cn_table_entry( PCPS_GENERIC_IO ), /* 0x43 */ \ + _mbg_cn_table_entry( PCPS_GET_SYNTH_STATE ), /* 0x44 */ \ + _mbg_cn_table_entry( PCPS_GET_IRIG_CTRL_BITS ), /* 0x45 */ \ + _mbg_cn_table_entry( PCPS_GET_RAW_IRIG_DATA ), /* 0x46 */ \ + _mbg_cn_table_entry( PCPS_GET_STATUS_PORT ), /* 0x4B */ \ + _mbg_cn_table_entry( PCPS_GET_DEBUG_STATUS ), /* 0x4C */ \ + _mbg_cn_table_entry( PCPS_READ_GPS_DATA ), /* 0x50 */ \ + _mbg_cn_table_entry( PCPS_WRITE_GPS_DATA ), /* 0x51 */ \ + _mbg_cn_table_entry( PCPS_CLR_UCAP_BUFF ), /* 0x60 */ \ + _mbg_cn_table_entry( PCPS_GIVE_UCAP_ENTRIES ), /* 0x61 */ \ + _mbg_cn_table_entry( PCPS_GIVE_UCAP_EVENT ), /* 0x62 */ \ + _mbg_cn_table_entry( PCPS_GET_CORR_INFO ), /* 0x63 */ \ + _mbg_cn_table_entry( PCPS_GET_TR_DISTANCE ), /* 0x64 */ \ + _mbg_cn_table_entry( PCPS_SET_TR_DISTANCE ), /* 0x65 */ \ + _mbg_cn_table_entry( PCPS_CLR_EVT_LOG ), /* 0x66 */ \ + _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() \ +} -/* The associated structure SYNTH is defined in gpsdefs.h. */ -#define PCPS_GIVE_FW_ID_1 0x40 -#define PCPS_GIVE_FW_ID_2 0x41 -#define PCPS_GIVE_SERNUM 0x42 -#define PCPS_GENERIC_IO 0x43 -#define PCPS_GET_SYNTH_STATE 0x44 -#define PCPS_GET_IRIG_CTRL_BITS 0x45 -#define PCPS_GET_RAW_IRIG_DATA 0x46 +/** + * @brief 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 */ -#define PCPS_GET_STATUS_PORT 0x4B -#define PCPS_GET_DEBUG_STATUS 0x4C -// expects sizeof( MBG_DEBUG_STATUS ) chars -// Command codes 0x4D, 0x4E, and 0x4F are reserved. +#if !defined( BITMASK ) + #define BITMASK( b ) ( ( 1 << b ) - 1 ) +#endif -#define PCPS_READ_GPS_DATA 0x50 -#define PCPS_WRITE_GPS_DATA 0x51 -#define PCPS_CLR_UCAP_BUFF 0x60 -#define PCPS_GIVE_UCAP_ENTRIES 0x61 -#define PCPS_GIVE_UCAP_EVENT 0x62 +/** @brief The size of a bus level device's command/data FIFO */ +#define PCPS_FIFO_SIZE 16 -typedef struct -{ - uint32_t used; /**< the number of saved capture events */ - uint32_t max; /**< capture buffer size */ -} PCPS_UCAP_ENTRIES; +/** @brief A data buffer for a bus level device's command/data */ +typedef int8_t PCPS_BUFF[PCPS_FIFO_SIZE]; -#define _mbg_swab_pcps_ucap_entries( _p ) \ -{ \ - _mbg_swab32( &(_p)->used ); \ - _mbg_swab32( &(_p)->max ); \ -} +/** @brief The maximum length of an ID string, including terminating 0 */ +#define PCPS_ID_SIZE ( 2 * PCPS_FIFO_SIZE + 1 ) ///< ASCIIZ string +/** @brief A buffer for an ID string, including terminating 0 */ +typedef char PCPS_ID_STR[PCPS_ID_SIZE]; -#define PCPS_GET_CORR_INFO 0x63 // read CORR_INFO structure, only if _pcps_has_pzf() -#define PCPS_GET_TR_DISTANCE 0x64 // read TR_DISTANCE, only if _pcps_has_tr_distance() -#define PCPS_SET_TR_DISTANCE 0x65 // write TR_DISTANCE, only if _pcps_has_tr_distance() +/** @brief The maximum length of a serial number string, including terminating 0 */ +#define PCPS_SN_SIZE ( PCPS_FIFO_SIZE + 1 ) ///< ASCIIZ string -#define PCPS_CLR_EVT_LOG 0x66 // clear on-board event log, only if _pcps_has_evt_log() -#define PCPS_NUM_EVT_LOG_ENTRIES 0x67 // read num event log entries, only if _pcps_has_evt_log() -#define PCPS_FIRST_EVT_LOG_ENTRY 0x68 // read first (oldest) event log entry, only if _pcps_has_evt_log() -#define PCPS_NEXT_EVT_LOG_ENTRY 0x69 // read next event log entry, only if _pcps_has_evt_log() +/** @brief A buffer for a serial number string, including terminating 0 */ +typedef char PCPS_SN_STR[PCPS_SN_SIZE]; /** - special -- use with care ! -*/ -#define PCPS_FORCE_RESET 0x80 - -// Command codes 0xF0 through 0xFF are reserved. + * @brief Seconds since epoch 1970-01-01, usually %UTC scale + * + * Used with ::PCPS_TIME_STAMP. + * + * @see ::PCPS_FRAC_32 + * @see ::PCPS_TIME_STAMP + */ +typedef uint32_t PCPS_SECONDS; -/** @} group_cmd_bytes */ +#define _mbg_swab_pcps_seconds( _p ) \ +do \ +{ \ + _mbg_swab32( _p ); \ +} while ( 0 ) -#if !defined( MBG_CMD_TABLE_EXT ) - #define MBG_CMD_TABLE_EXT { 0, NULL } -#endif /** - * @brief An initializer for a table of code/name entries of non-GPS commands. + * @brief 32 bit binary fraction of a second * - * This can e.g. be assigned to an array of MBG_CODE_NAME_TABLE_ENTRY elements - * and may be helpful when debugging. + * Used with ::PCPS_TIME_STAMP, e.g. + * 0x80000000 == 0.5 s, 0xFFFFFFFF == 0.9999999.. s, etc. + * Use ::bin_frac_32_to_dec_frac for conversion. + * + * @see ::bin_frac_32_to_dec_frac + * @see ::PCPS_SECONDS + * @see ::PCPS_TIME_STAMP + * @see ::PCPS_HRT_FRAC_SCALE + * @see ::PCPS_HRT_FRAC_SCALE_FMT */ -#define MBG_CMD_TABLE \ -{ \ - { PCPS_GIVE_TIME, "PCPS_GIVE_TIME" }, /* 00 */ \ - { PCPS_GIVE_TIME_NOCLEAR, "PCPS_GIVE_TIME_NOCLEAR" }, /* 01 */ \ - { PCPS_GIVE_SYNC_TIME, "PCPS_GIVE_SYNC_TIME" }, /* 02 */ \ - { PCPS_GIVE_HR_TIME, "PCPS_GIVE_HR_TIME" }, /* 03 */ \ - { PCPS_GIVE_IRIG_TIME, "PCPS_GIVE_IRIG_TIME" }, /* 04 */ \ - { PCPS_SET_TIME, "PCPS_SET_TIME" }, /* 10 */ \ - { PCPS_SET_EVENT_TIME, "PCPS_SET_EVENT_TIME" }, /* 14 */ \ - { PCPS_IRQ_NONE, "PCPS_IRQ_NONE" }, /* 20 */ \ - { PCPS_IRQ_1_SEC, "PCPS_IRQ_1_SEC" }, /* 21 */ \ - { PCPS_IRQ_1_MIN, "PCPS_IRQ_1_MIN" }, /* 22 */ \ - { PCPS_IRQ_10_MIN, "PCPS_IRQ_10_MIN" }, /* 24 */ \ - { PCPS_IRQ_30_MIN, "PCPS_IRQ_30_MIN" }, /* 28 */ \ - { PCPS_GET_SERIAL, "PCPS_GET_SERIAL" }, /* 30 */ \ - { PCPS_SET_SERIAL, "PCPS_SET_SERIAL" }, /* 31 */ \ - { PCPS_GET_TZCODE, "PCPS_GET_TZCODE" }, /* 32 */ \ - { PCPS_SET_TZCODE, "PCPS_SET_TZCODE" }, /* 33 */ \ - { PCPS_GET_PCPS_TZDL, "PCPS_GET_PCPS_TZDL" }, /* 34 */ \ - { PCPS_SET_PCPS_TZDL, "PCPS_SET_PCPS_TZDL" }, /* 35 */ \ - { PCPS_GET_REF_OFFS, "PCPS_GET_REF_OFFS" }, /* 36 */ \ - { PCPS_SET_REF_OFFS, "PCPS_SET_REF_OFFS" }, /* 37 */ \ - { PCPS_GET_OPT_INFO, "PCPS_GET_OPT_INFO" }, /* 38 */ \ - { PCPS_SET_OPT_SETTINGS, "PCPS_SET_OPT_SETTINGS" }, /* 39 */ \ - { PCPS_GET_IRIG_RX_INFO, "PCPS_GET_IRIG_RX_INFO" }, /* 3A */ \ - { PCPS_SET_IRIG_RX_SETTINGS, "PCPS_SET_IRIG_RX_SETTINGS" }, /* 3B */ \ - { PCPS_GET_IRIG_TX_INFO, "PCPS_GET_IRIG_TX_INFO" }, /* 3C */ \ - { PCPS_SET_IRIG_TX_SETTINGS, "PCPS_SET_IRIG_TX_SETTINGS" }, /* 3D */ \ - { PCPS_GET_SYNTH, "PCPS_GET_SYNTH" }, /* 3E */ \ - { PCPS_SET_SYNTH, "PCPS_SET_SYNTH" }, /* 3F */ \ - { PCPS_GIVE_FW_ID_1, "PCPS_GIVE_FW_ID_1" }, /* 40 */ \ - { PCPS_GIVE_FW_ID_2, "PCPS_GIVE_FW_ID_2" }, /* 41 */ \ - { PCPS_GIVE_SERNUM, "PCPS_GIVE_SERNUM" }, /* 42 */ \ - { PCPS_GENERIC_IO, "PCPS_GENERIC_IO" }, /* 43 */ \ - { PCPS_GET_SYNTH_STATE, "PCPS_GET_SYNTH_STATE" }, /* 44 */ \ - { PCPS_GET_IRIG_CTRL_BITS, "PCPS_GET_IRIG_CTRL_BITS" }, /* 45 */ \ - { PCPS_GET_RAW_IRIG_DATA, "PCPS_GET_RAW_IRIG_DATA" }, /* 46 */ \ - { PCPS_GET_STATUS_PORT, "PCPS_GET_STATUS_PORT" }, /* 4B */ \ - { PCPS_GET_DEBUG_STATUS, "PCPS_GET_DEBUG_STATUS" }, /* 4C */ \ - { PCPS_READ_GPS_DATA, "PCPS_READ_GPS_DATA" }, /* 50 */ \ - { PCPS_WRITE_GPS_DATA, "PCPS_WRITE_GPS_DATA" }, /* 51 */ \ - { PCPS_CLR_UCAP_BUFF, "PCPS_CLR_UCAP_BUFF" }, /* 60 */ \ - { PCPS_GIVE_UCAP_ENTRIES, "PCPS_GIVE_UCAP_ENTRIES" }, /* 61 */ \ - { PCPS_GIVE_UCAP_EVENT, "PCPS_GIVE_UCAP_EVENT" }, /* 62 */ \ - { PCPS_GET_CORR_INFO, "PCPS_GET_CORR_INFO" }, /* 63 */ \ - { PCPS_GET_TR_DISTANCE, "PCPS_GET_TR_DISTANCE" }, /* 64 */ \ - { PCPS_SET_TR_DISTANCE, "PCPS_SET_TR_DISTANCE" }, /* 65 */ \ - { PCPS_CLR_EVT_LOG, "PCPS_CLR_EVT_LOG" }, /* 66 */ \ - { PCPS_NUM_EVT_LOG_ENTRIES, "PCPS_NUM_EVT_LOG_ENTRIES" }, /* 67 */ \ - { PCPS_FIRST_EVT_LOG_ENTRY, "PCPS_FIRST_EVT_LOG_ENTRY" }, /* 68 */ \ - { PCPS_NEXT_EVT_LOG_ENTRY, "PCPS_NEXT_EVT_LOG_ENTRY" }, /* 69 */ \ - { PCPS_FORCE_RESET, "PCPS_FORCE_RESET" }, /* 80 */ \ - MBG_CMD_TABLE_EXT, \ - { 0, NULL } \ -} - +typedef uint32_t PCPS_FRAC_32; +#define _mbg_swab_pcps_frac_32( _p ) \ +do \ +{ \ + _mbg_swab32( _p ); \ +} while ( 0 ) -/* Codes returned when commands with parameters have been passed */ -/* to the board */ -#define PCPS_SUCCESS 0 /**< OK, no error */ -#define PCPS_ERR_STIME -1 /**< invalid date/time/status passed */ -#define PCPS_ERR_CFG -2 /**< invalid parms for a cmd writing config parameters */ - - - -#ifndef BITMASK - #define BITMASK( b ) ( ( 1 << b ) - 1 ) -#endif - - -/** The size of the plug-in card's on-board FIFO */ -#define PCPS_FIFO_SIZE 16 - -typedef int8_t PCPS_BUFF[PCPS_FIFO_SIZE]; - - -#define PCPS_ID_SIZE ( 2 * PCPS_FIFO_SIZE + 1 ) /**< ASCIIZ string */ -typedef char PCPS_ID_STR[PCPS_ID_SIZE]; - - -#define PCPS_SN_SIZE ( PCPS_FIFO_SIZE + 1 ) /**< ASCIIZ string */ -typedef char PCPS_SN_STR[PCPS_SN_SIZE]; /** - * The structure has been introduced to be able to handle - * high resolution time stamps. + * @brief A high resolution time stamp */ typedef struct { - uint32_t sec; /**< seconds since 1970 (UTC) */ - uint32_t frac; /**< fractions of second ( 0xFFFFFFFF == 0.9999.. sec) */ -} PCPS_TIME_STAMP; + PCPS_SECONDS sec; ///< seconds since 1970, usually %UTC scale + PCPS_FRAC_32 frac; ///< binary fractions of second, see ::PCPS_FRAC_32 -#define _mbg_swab_pcps_time_stamp( _p ) \ -{ \ - _mbg_swab32( &(_p)->sec ); \ - _mbg_swab32( &(_p)->frac ); \ -} +} PCPS_TIME_STAMP; +#define _mbg_swab_pcps_time_stamp( _p ) \ +do \ +{ \ + _mbg_swab_pcps_seconds( &(_p)->sec ); \ + _mbg_swab_pcps_frac_32( &(_p)->frac ); \ +} while ( 0 ) -// Depending on the target environment define a data type -// which can be used to convert binary fractions without -// range overflow. -#if defined( MBG_TGT_UNIX ) - #define PCPS_HRT_FRAC_CONVERSION_TYPE int64_t -#elif defined( MBG_TGT_WIN32 ) - #define PCPS_HRT_FRAC_CONVERSION_TYPE int64_t -#elif defined( __WATCOMC__ ) && ( __WATCOMC__ >= 1100 ) - #define PCPS_HRT_FRAC_CONVERSION_TYPE int64_t -#else - #define PCPS_HRT_FRAC_CONVERSION_TYPE double -#endif -// Max value of PCPS_TIME_STAMP::frac + 1 used for scaling -#define PCPS_HRT_BIN_FRAC_SCALE ( (PCPS_HRT_FRAC_CONVERSION_TYPE) 4294967296.0 ) // == 0x100000000 - - -// The scale and format to be used to print the fractions -// of a second as returned in the PCPS_TIME_STAMP structure. -// The function frac_sec_from_bin() can be used for -// the conversion. #ifndef PCPS_HRT_FRAC_SCALE + /** + * @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. + * + * @see ::PCPS_HRT_FRAC_SCALE_FMT + */ #define PCPS_HRT_FRAC_SCALE 10000000UL #endif #ifndef PCPS_HRT_FRAC_SCALE_FMT + /** + * @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. + * + * @see ::PCPS_HRT_FRAC_SCALE + */ #define PCPS_HRT_FRAC_SCALE_FMT "%07lu" #endif -typedef uint16_t PCPS_TIME_STATUS_X; /**< extended status */ +/** + * @brief Extended status code + * + * Low byte corresponds to ::PCPS_TIME_STATUS, high byte + * contains additional flags. + * + * @see ::PCPS_TIME_STATUS + * @see @ref PCPS_TIME_STATUS_FLAGS + */ +typedef uint16_t PCPS_TIME_STATUS_X; #define _mbg_swab_pcps_time_status_x( _p ) _mbg_swab16( _p ) @@ -1003,89 +1032,147 @@ typedef struct } PCPS_TIME_STATUS_X_MASKS; #define _mbg_swab_pcps_time_status_x_masks( _p ) \ +do \ { \ _mbg_swab_pcps_time_status_x( &(_p)->set_mask ); \ _mbg_swab_pcps_time_status_x( &(_p)->clr_mask ); \ -} +} while ( 0 ) + + + +/** + * @brief Definitions used to report a signal strength + * + * @anchor PCPS_SIG_VAL_DEFS @{ */ + +/** + * @brief A data type used to report the signal value + */ +typedef uint8_t PCPS_SIG_VAL; + +// The following constants are used to draw a signal bar +// depending on a DCF77 clock's signal value: +#define PCPS_SIG_BIAS 55 +#define PCPS_SIG_ERR 1 +#define PCPS_SIG_MIN 20 +#define PCPS_SIG_MAX 68 + +// These constants are used by non-DCF77 devices to indicate +// if an input signal is available or not: +#define PCPS_SIG_LVL_SIG_NOT_AVAIL 0 +#define PCPS_SIG_LVL_SIG_AVAIL 128 + +/** @} anchor PCPS_SIG_VAL_DEFS */ /** - * The structure has been introduced to be able to read the - * current time with higher resolution of fractions of seconds and - * more detailed information on the time zone and status. - * The structure is returned if the new command #PCPS_GIVE_HR_TIME - * is written to the board. - * _pcps_has_hr_time() checks whether supported. - * - * Newer GPS boards also accept the #PCPS_GIVE_UCAP_EVENT command - * to return user capture event times using this format. In this - * case, the "signal" field contains the number of the capture - * input line, e.g. 0 or 1. - * _pcps_has_ucap() checks whether supported. + * @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. + * + * Newer devices providing time capture input may also accept the + * ::PCPS_GIVE_UCAP_EVENT command to read user capture event times + * using this format. In this case, the "signal" field contains + * the number of the capture input line, e.g. 0 or 1. + * ::_pcps_has_ucap checks whether this is supported. */ typedef struct { - PCPS_TIME_STAMP tstamp; /**< High resolution time stamp (UTC) */ - int32_t utc_offs; /**< %UTC offs [sec] (loc_time = %UTC + utc_offs) */ - PCPS_TIME_STATUS_X status; /**< status flags as defined below */ - uint8_t signal; /**< for normal time, the relative RF signal level, for ucap, the channel number */ + PCPS_TIME_STAMP tstamp; ///< High resolution time stamp (%UTC) + int32_t utc_offs; ///< %UTC offs [sec] (loc_time = tstamp + utc_offs) + PCPS_TIME_STATUS_X status; ///< status bits, see @ref PCPS_TIME_STATUS_FLAGS + PCPS_SIG_VAL signal; ///< signal strength, see @ref PCPS_SIG_VAL_DEFS, or capture input channel number + } PCPS_HR_TIME; #define _mbg_swab_pcps_hr_time( _p ) \ +do \ { \ _mbg_swab_pcps_time_stamp( &(_p)->tstamp ); \ _mbg_swab32( &(_p)->utc_offs ); \ _mbg_swab_pcps_time_status_x( &(_p)->status ); \ -} +} while ( 0 ) +/** + * @brief Time synchronization status + * + * Used by legacy API calls. New API calls provide + * an extended status word ::PCPS_TIME_STATUS_X. + * + * @see ::PCPS_TIME_STATUS_FLAGS_COMMON + * @see ::PCPS_TIME_STATUS_X + */ typedef uint8_t PCPS_TIME_STATUS; -/** - The standard structure used to read times from the board. - The time has a resultion of 10 ms. -*/ -typedef struct PCPS_TIME_s + + +/** + * @brief Local calendar date and time, plus sync status + * + * This legacy structure is supported by all bus level devices but + * has a time resultion of 10 ms only. For more accurate time stamps + * the structures ::PCPS_HR_TIME and ::PCPS_TIME_STAMP should be + * used preferably. + * + * @see ::PCPS_HR_TIME + * @see ::PCPS_TIME_STAMP + * @see ::PCPS_STIME + */ +typedef struct { - uint8_t sec100; /**< hundredths of seconds, 0..99 */ - uint8_t sec; /**< seconds, 0..59, or 60 if leap second */ - uint8_t min; /**< minutes, 0..59 */ - uint8_t hour; /**< hours, 0..23 */ - - uint8_t mday; /**< day of month, 0..31 */ - uint8_t wday; /**< day of week, 1..7, 1 = Monday */ - uint8_t month; /**< month, 1..12 */ - uint8_t year; /**< year of the century, 0..99 */ - - PCPS_TIME_STATUS status; /**< status bits, see below */ - uint8_t signal; /**< relative signal strength, range depends on device type */ - int8_t offs_utc; /**< [hours], 0 if !_pcps_has_utc_offs() */ + uint8_t sec100; ///< hundredths of seconds, 0..99, 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 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; -/** - The structure is passed as parameter with the PCPS_SET_TIME cmd -*/ -typedef struct PCPS_STIME_s + +/** + * @brief Date time and status used with the ::PCPS_SET_TIME command + * + * Similar to ::PCPS_TIME, but missing the ::PCPS_TIME::signal + * and ::PCPS_TIME::offs_utc fields. + * + * @see ::PCPS_TIME + */ +typedef struct { - uint8_t sec100; /**< hundredths of seconds, 0..99 */ - uint8_t sec; /**< seconds, 0..59, or 60 if leap second */ - uint8_t min; /**< minutes, 0..59 */ - uint8_t hour; /**< hours, 0..23 */ + uint8_t sec100; ///< hundredths of seconds, 0..99, 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 mday; ///< day of month, 0..31 + uint8_t wday; ///< day of week, 1..7, 1 = Monday + uint8_t month; ///< month, 1..12 + uint8_t year; ///< year of the century, 0..99 - uint8_t mday; /**< day of month, 0..31 */ - uint8_t wday; /**< day of week, 1..7, 1 = Monday */ - uint8_t month; /**< month, 1..12 */ - uint8_t year; /**< year of the century, 0..99 */ + PCPS_TIME_STATUS status; ///< status bits, see ::PCPS_TIME_STATUS_FLAGS_COMMON - PCPS_TIME_STATUS status; /**< status bits, see below */ } PCPS_STIME; #ifdef _C166 - // This is a workaround to specify some structure sizes. The C166 compiler - // always reports an even structure size although the structure size may - // be odd due to the number of bytes. This might lead to errors between + // This is a workaround to specify some structure sizes. The C166 compiler + // always reports an even structure size although the structure size may + // be odd due to the number of bytes. This might lead to errors between // the C166 and other build environments. #define sizeof_PCPS_TIME ( sizeof( PCPS_TIME ) - 1 ) #define sizeof_PCPS_STIME ( sizeof( PCPS_STIME ) - 1 ) @@ -1098,129 +1185,174 @@ typedef union { PCPS_TIME t; PCPS_STIME stime; + } PCPS_TIME_UNION; /** - The structure below can be 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 .frac field depends on - the update interval of the structure as implementation - in the firmware. I.e. if the raw IRIG time is updated - only once per second, the .frac value can always be 0. -*/ -typedef struct PCPS_IRIG_TIME_s + * @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. + * + * @see @ref group_icode + * @see ::ICODE_RX_CODES + */ +typedef struct { - PCPS_TIME_STATUS_X status; /**< status bits, see below */ - int16_t offs_utc; /**< [minutes] */ - uint16_t yday; /**< day of year, 1..365/366 */ - uint16_t frac; /**< fractions of seconds, 0.1 ms units */ - uint8_t sec; /**< seconds, 0..59, or 60 if leap second */ - uint8_t min; /**< minutes, 0..59 */ - uint8_t hour; /**< hours, 0..23 */ - uint8_t year; /**< 2 digit year number, 0xFF if year not supp. by the IRIG code */ - uint8_t signal; /**< relative signal strength, range depends on device type */ - uint8_t reserved; /**< currently not used, always 0 */ + PCPS_TIME_STATUS_X status; ///< status bits, see @ref PCPS_TIME_STATUS_FLAGS + int16_t offs_utc; ///< [minutes], 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_IRIG_TIME; #define _mbg_swab_pcps_irig_time( _p ) \ +do \ { \ _mbg_swab_pcps_time_status_x( &(_p)->status ); \ _mbg_swab16( &(_p)->offs_utc ); \ _mbg_swab16( &(_p)->yday ); \ _mbg_swab16( &(_p)->frac ); \ -} - - +} while ( 0 ) /** - * Bit masks used with both PCPS_TIME_STATUS and PCPS_TIME_STATUS_X + * @brief A constant representing a 2 digit unknown IRIG year number + * + * Used with ::PCPS_IRIG_TIME::year */ -#define PCPS_FREER 0x01 /**< DCF77 clock running on xtal */ - /**< GPS receiver has not verified its position */ - -#define PCPS_DL_ENB 0x02 /**< daylight saving enabled */ - -#define PCPS_SYNCD 0x04 /**< clock has sync'ed at least once after pwr up */ - -#define PCPS_DL_ANN 0x08 /**< a change in daylight saving is announced */ - -#define PCPS_UTC 0x10 /**< a special %UTC firmware is installed */ +#define IRIG_TIME_UNKNOWN_YEAR 0xFF -#define PCPS_LS_ANN 0x20 /**< leap second announced */ - /**< (requires firmware rev. REV_PCPS_LS_ANN_...) */ - -#define PCPS_IFTM 0x40 /**< the current time was set via PC */ - /**< (requires firmware rev. REV_PCPS_IFTM_...) */ - -#define PCPS_INVT 0x80 /**< invalid time because battery was disconn'd */ /** - * Bit masks used only with PCPS_TIME_STATUS_X - */ -#define PCPS_LS_ENB 0x0100 /**< current second is leap second */ -#define PCPS_ANT_FAIL 0x0200 /**< antenna failure */ -#define PCPS_LS_ANN_NEG 0x0400 /**< announced leap second is negative */ -#define PCPS_SCALE_GPS 0x0800 /**< time stamp is GPS scale */ -#define PCPS_SCALE_TAI 0x1000 /**< time stamp is TAI scale */ + * @brief Time status flags + * + * @anchor PCPS_TIME_STATUS_FLAGS @{ */ /** - * Bit masks used only with time stamps representing user capture events + * @brief Legacy time status flags + * + * Bit masks used with both ::PCPS_TIME_STATUS and ::PCPS_TIME_STATUS_X */ -#define PCPS_UCAP_OVERRUN 0x2000 /**< events interval too short */ -#define PCPS_UCAP_BUFFER_FULL 0x4000 /**< events read too slow */ +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 +}; -/** - * Bit masks used only with time stamps representing the current board time. - * A DCF77 PZF receiver can set this bit if it is actually synchronized - * using PZF correlation and thus provides higher accuracy than AM receivers. - */ -#define PCPS_SYNC_PZF 0x2000 /**< same code as PCPS_UCAP_OVERRUN */ /** - * Immediately after a clock has been accessed, subsequent accesses - * are blocked for up to 1.5 msec to give the clock's microprocessor - * some time to decode the incoming time signal. - * The flag below is set if a program tries to read the PCPS_HR_TIME - * during this interval. In this case the read function returns the - * proper time stamp which is taken if the command byte is written, - * however, the read function returns with delay. - * This flag is not supported by all clocks. + * @brief Extended time status flags + * + * Bit masks used with ::PCPS_TIME_STATUS_X only */ -#define PCPS_IO_BLOCKED 0x8000 +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. -*/ + */ #define PCPS_SCALE_MASK ( PCPS_SCALE_TAI | PCPS_SCALE_GPS ) +/** @} anchor PCPS_TIME_STATUS_FLAGS */ + + + /** - * Some DCF77 clocks have a serial interface that can be controlled - * using the commands PCPS_SET_SERIAL and PCPS_GET_SERIAL. Both commands - * use a parameter byte describing transmission speed, framing and mode - * of operation. The parameter byte can be build using the constants - * defined below, by or'ing one of the constants of each group, shifted - * to the right position. PCPS_GET_SERIAL expects that parameter byte - * and PCPS_GET_SERIAL returns the current configuration from the board. - * _pcps_has_serial() checks whether supported. - * For GPS clocks, please refer to the comments for the PCPS_GET_SERIAL + * @brief Legacy definitions used to configure a device's serial port + * + * @deprecated This structure and the associated command codes + * are deprecated. ::PORT_SETTINGS, ::PORT_INFO and associated + * definitions should be used instead, if supported. + * + * @anchor PCPS_OLD_SERIAL_CFG @{ */ + +/** + * @brief Configuration information for a device's serial port + * + * Used with ::PCPS_GET_SERIAL and ::PCPS_SET_SERIAL + * + * The serial interface on some old DCF77 clocks can be configured + * using the commands ::PCPS_SET_SERIAL and ::PCPS_GET_SERIAL. + * Both commands use a parameter byte describing transmission speed, + * framing and mode of operation. The parameter byte can be assembled + * using the constants defined in ::PCPS_BD_CODES, ::PCPS_FR_CODES, + * and ::PCPS_MOD_CODES, by or'ing one of the constants of each group, + * shifted to the right position. ::PCPS_GET_SERIAL expects that parameter + * byte and ::PCPS_GET_SERIAL returns the current configuration from + * the board. + * ::_pcps_has_serial checks whether supported. + * For old GPS clocks refer to the comments for the ::PCPS_GET_SERIAL * command. */ +typedef uint8_t PCPS_SERIAL; + /** - * Baud rate indices. The values below are obsolete and should - * be replaced by the codes named MBG_BAUD_RATE_... which are - * defined in gpsdefs.h. The resulting index numbers, however, - * have not changed. + * @brief Deprecated baud rate indices + * + * @deprecated These values are deprecated. + * ::MBG_BAUD_RATE_CODES and associated structures + * should be used preferably. + * + * The sequence of codes matches the sequence + * defined in ::MBG_BAUD_RATE_CODES. */ -enum +enum PCPS_BD_CODES { PCPS_BD_300, PCPS_BD_600, @@ -1229,95 +1361,225 @@ enum PCPS_BD_4800, PCPS_BD_9600, PCPS_BD_19200, - N_PCPS_BD /* number of codes */ + N_PCPS_BD ///< number of codes }; -#define PCPS_BD_BITS 4 /* field with in the cfg byte */ -#define PCPS_BD_SHIFT 0 /* num of bits to shift left */ +#define PCPS_BD_BITS 4 ///< field with in the cfg byte +#define PCPS_BD_SHIFT 0 ///< num of bits to shift left -/* - * Initializers for a table of all baud rate strings - * and values can be found in gpsdefs.h. - */ /** - * Unfortunately, the framing codes below can not simply be - * replaced by the newer MBG_FRAMING_... definitions since - * the order of indices does not match. + * @brief Deprecated framing code indices + * + * @deprecated These values are deprecated. + * ::MBG_FRAMING_CODES and associated structures + * should be used preferably. + * + * Unfortunately, these framing codes can *not* simply + * be replaced by the newer MBG_FRAMING_... definitions + * since the order of indices doesn't match. */ -enum +enum PCPS_FR_CODES { PCPS_FR_8N1, PCPS_FR_7E2, PCPS_FR_8N2, PCPS_FR_8E1, - N_PCPS_FR_DCF /* number of valid codes */ + N_PCPS_FR_DCF ///< number of valid codes +}; + +#define PCPS_FR_BITS 2 ///< field with in the cfg byte +#define PCPS_FR_SHIFT PCPS_BD_BITS ///< num of bits to shift left + + + +/** + * @brief Deprecated codes for modes of operation + * + * @deprecated These values are deprecated. + * ::STR_MODES and associated structures + * should be used preferably. + * + * The sequence of codes matches the sequence + * defined in ::STR_MODES. + */ +enum PCPS_MOD_CODES +{ + PCPS_MOD_REQ, ///< time string on request '?' only + PCPS_MOD_SEC, ///< time string once per second + PCPS_MOD_MIN, ///< time string once per minute + PCPS_MOD_RSVD, ///< reserved + N_PCPS_MOD_DCF ///< number of possible codes }; -#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_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 -/* - * An initializer for a table of framing strings is only defined for - * the new MBG_FRAMING_... definitions. For editing the serial port - * configuration, the old codes above should be translated to the new - * codes to unify handling inside the edit functions. +/** @} anchor PCPS_OLD_SERIAL_CFG */ + + + +/** + * @brief Type of variable to hold a TZ code + * + * This is used with the PCI interface but differs from ::TZCODE + * which is used with the binary protocol. + * + * @see ::TZCODE + * @see ::TZCODE_UNION */ +typedef uint8_t PCPS_TZCODE; -/** - Modes of operation - * Indices for modes of operation. The values below are obsolete - * and should be replaced by the codes named STR_... which are - * defined in gpsdefs.h. The resulting index numbers, however, - * have not changed. +/** + * @brief Enumeration of codes used with PCPS_TZCODE */ -enum +enum PCPS_TZCODES { - PCPS_MOD_REQ, /* time string on request '?' only */ - PCPS_MOD_SEC, /* time string once per second */ - PCPS_MOD_MIN, /* time string once per minute */ - PCPS_MOD_RSVD, /* reserved */ - N_PCPS_MOD_DCF /* number of possible codes */ + PCPS_TZCODE_CET_CEST, ///< default as 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 }; -#define PCPS_MOD_BITS 2 /* field with in the cfg byte */ -#define PCPS_MOD_SHIFT ( PCPS_BD_BITS + PCPS_FR_BITS ) - /* num of bits to shift left */ +/* the definitions below are for compatibily only: */ +#define PCPS_TZCODE_MEZMESZ PCPS_TZCODE_CET_CEST +#define PCPS_TZCODE_MEZ PCPS_TZCODE_CET +#define PCPS_TZCODE_OEZ PCPS_TZCODE_EET_EEST + + +/** + * @brief Daylight changeover specification + * + * Used as member field of ::PCPS_TZDL only. Most devices supporting + * conversion to local time support the ::TZDL structure instead. + * + * @see ::TZDL + */ +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] + +} PCPS_DL_ONOFF; + +#define _mbg_swab_pcps_dl_onoff( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->year_or_wday ); \ +} while ( 0 ) + +/** + * @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 + * for each year. In this case the remaining bits represent the day-of-week + * after the specified mday/month at which the change shall occur. + * If that flag is not set then the field contains the full four-digit year number + * and the ::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. + * + * @see ::TZDL + * @see ::PCPS_TZDL + */ +#define DL_AUTO_FLAG 0x8000 // also defined in gpsdefs.h /** - * Some definitions used with PZF receivers + * @brief Specification of a local time zone + * + * Most devices supporting conversion to local time support + * the ::TZDL structure instead. + * + * @see ::DL_AUTO_FLAG + * @see ::TZDL */ +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 + +} PCPS_TZDL; + +#define _mbg_swab_pcps_tzdl( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->offs ); \ + _mbg_swab16( &(_p)->offs_dl ); \ + _mbg_swab_pcps_dl_onoff( &(_p)->tm_on ); \ + _mbg_swab_pcps_dl_onoff( &(_p)->tm_off ); \ +} while ( 0 ) + -/* receiver distance from transmitter [km] */ -typedef uint16_t TR_DISTANCE; + +/** + * @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 + +} PCPS_UCAP_ENTRIES; + +#define _mbg_swab_pcps_ucap_entries( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->used ); \ + _mbg_swab32( &(_p)->max ); \ +} while ( 0 ) + + + +/** + * @defgroup group_pzf_supp Definitions used with PZF receivers + * + * @{ */ + +/** + * @brief Receiver distance from transmitter [km] + */ +typedef uint16_t TR_DISTANCE; ///< Range may vary with receiver type #define _mbg_swab_tr_distance( _p ) \ _mbg_swab16( _p ) - -/* correlation status info */ +/** + * @brief PZF correlation status info + */ typedef struct { - uint8_t val; /**< correlation value, or check count if status == PZF_CORR_CHECK */ - uint8_t status; /**< status codes, see below */ - char corr_dir; /**< space, '<', or '>' */ - uint8_t signal; /**< signal level, may always be 0 for devices which do not support this */ + uint8_t val; ///< correlation value, or check count if status ==:: PZF_CORR_CHECK + uint8_t status; ///< status codes, see ::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() -/** Codes used with CORR_INFO::status: */ -enum +/** + * @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 }; @@ -1346,142 +1608,182 @@ enum { PZF_CORR_STATE_NAME_FINE_ENG, PZF_CORR_STATE_NAME_FINE_GER } \ } +/** @} defgroup group_pzf_supp */ -/** @defgroup group_gps_cmds_bus GPS commands passed via the system bus - - This enumeration defines the various types of data that can be read - from or written to Meinberg bus level devices which support this. - Access should be done using the functions pcps_read_gps_data() - and pcps_write_gps_data() since the size of some of the structures - exceeds the size of the device's I/O buffer and must therefore be - accessed in several blocks. - - The structures to be used are defined in gpsdefs.h. Not all structures - are supported, yet. Check the R/W indicators for details. - * @{ */ -enum -{ // R/W data type description - // system data ----------------------------------------------- - PC_GPS_TZDL = 0, // R/W TZDL time zone / daylight saving - PC_GPS_SW_REV, // R/- SW_REV software revision - PC_GPS_BVAR_STAT, // R/- BVAR_STAT status of buffered variables - PC_GPS_TIME, // R/W TTM curr. time - PC_GPS_POS_XYZ, // -/W XYZ curr. pos. in ECEF coords - PC_GPS_POS_LLA, // -/W LLA curr. pos. in geogr. coords - PC_GPS_PORT_PARM, // R/W PORT_PARM param. of the serial ports - PC_GPS_ANT_INFO, // R/- ANT_INFO time diff after ant. disconn. - PC_GPS_UCAP, // R/- TTM user capture - PC_GPS_ENABLE_FLAGS, // R/W ENABLE_FLAGS controls when to enable outp. - PC_GPS_STAT_INFO, // R/- GPS_STAT_INFO - PC_GPS_CMD, // -/W GPS_CMD commands as described below - PC_GPS_IDENT, // R/- GPS_IDENT serial number - PC_GPS_POS, // R/- POS position XYZ, LLA, and DMS - PC_GPS_ANT_CABLE_LEN, // R/W ANT_CABLE_LEN used to compensate delay - // The codes below are supported by new GPS receiver boards: - PC_GPS_RECEIVER_INFO, // R/- RECEIVER_INFO rcvr model info - PC_GPS_ALL_STR_TYPE_INFO, // R/- n*STR_TYPE_INFO_IDX all string types - PC_GPS_ALL_PORT_INFO, // R/- n*PORT_INFO_IDX all port info - PC_GPS_PORT_SETTINGS_IDX, // -/W PORT_SETTINGS_IDX port settings only - PC_GPS_ALL_POUT_INFO, // R/- n*POUT_INFO_IDX all pout info - PC_GPS_POUT_SETTINGS_IDX, // -/W POUT_SETTINGS_IDX pout settings only - PC_GPS_TIME_SCALE, // R/W MBG_TIME_SCALE_{SETTINGS|INFO}, only if PCPS_HAS_TIME_SCALE - PC_GPS_LAN_IF_INFO, // R/- LAN_IF_INFO LAN interface info, only if PCPS_HAS_LAN_INTF - PC_GPS_IP4_STATE, // R/- IP4_SETTINGS LAN interface state, only if PCPS_HAS_LAN_INTF - PC_GPS_IP4_SETTINGS, // R/W IP4_SETTINGS LAN interface configuration, only if PCPS_HAS_LAN_INTF - PC_GPS_PTP_STATE, // R/- PTP_STATE, only if PCPS_HAS_PTP - PC_GPS_PTP_CFG, // R/W PTP_CFG_{SETTINGS|INFO}, only if PCPS_HAS_PTP - PC_GPS_PTP_UC_MASTER_CFG_LIMITS, // R/- PTP_UC_MASTER_CFG_LIMITS, only if can be unicast master - PC_GPS_ALL_PTP_UC_MASTER_INFO, // R/- n*PTP_UC_MASTER_INFO_IDX, only if can be unicast master - PC_GPS_PTP_UC_MASTER_SETTINGS_IDX, // -/W PTP_UC_MASTER_SETTINGS_IDX, only if can be unicast master - PC_GPS_GPIO_CFG_LIMITS, // R/- MBG_GPIO_CFG_LIMITS, only if PCPS_HAS_GPIO - PC_GPS_ALL_GPIO_INFO, // R/- n*MBG_GPIO_INFO, all GPIO info, only if PCPS_HAS_GPIO - PC_GPS_GPIO_SETTINGS_IDX, // -/W MBG_GPIO_SETTINGS_IDX, GPIO cfg for a specific port, only if PCPS_HAS_GPIO +/** + * @brief GPS Command codes passed via the system bus + * + * 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. + * + * Applications should instead use the API functions declared in mbgdevio.h. + * + * The structures to be used are defined in gpsdefs.h. Not all structures + * are supported, yet. Check the r/w indicators for details. + * + * @see @ref PCPS_CMD_CODES + * @see ::PC_GPS_CMD_CODES_TABLE + */ +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 // GPS data - PC_GPS_CFGH = 0x80, // -/- CFGH SVs' config. and health codes - PC_GPS_ALM, // -/- SV_ALM one SV's num and almanac - PC_GPS_EPH, // -/- SV_EPH one SV's num and ephemeris - PC_GPS_UTC, // R/W UTC %UTC corr. param., only if PCPS_HAS_UTC_PARM - PC_GPS_IONO, // -/- IONO ionospheric corr. param. - PC_GPS_ASCII_MSG // -/- ASCII_MSG the GPS ASCII message + PC_GPS_CFGH = 0x80, ///< (-/-) ::CFGH, SVs' config. and health codes (yet not used) + PC_GPS_ALM, ///< (-/-) ::SV_ALM, one SV's num and almanac (yet not used) + PC_GPS_EPH, ///< (-/-) ::SV_EPH, one SV's num and ephemeris (yet not used) + PC_GPS_UTC, ///< (r/w) ::UTC, %UTC corr. param., only if ::PCPS_HAS_UTC_PARM + PC_GPS_IONO, ///< (-/-) ::IONO, ionospheric corr. param. (yet not used) + PC_GPS_ASCII_MSG ///< (-/-) ::ASCII_MSG, the GPS ASCII message (yet not used) }; -/** @} group_gps_cmds_bus */ - /** * @brief An initializer for a table of code/name entries of GPS commands. * - * This can e.g. be assigned to an array of MBG_CODE_NAME_TABLE_ENTRY elements + * This can e.g. be assigned to an array of ::MBG_CODE_NAME_TABLE_ENTRY elements * and may be helpful when debugging. + * + * @see ::PC_GPS_CMD_CODES */ -#define MBG_PC_GPS_CMD_TABLE \ -{ \ - { PC_GPS_TZDL, "PC_GPS_TZDL" }, \ - { PC_GPS_SW_REV, "PC_GPS_SW_REV" }, \ - { PC_GPS_BVAR_STAT, "PC_GPS_BVAR_STAT" }, \ - { PC_GPS_TIME, "PC_GPS_TIME" }, \ - { PC_GPS_POS_XYZ, "PC_GPS_POS_XYZ" }, \ - { PC_GPS_POS_LLA, "PC_GPS_POS_LLA" }, \ - { PC_GPS_PORT_PARM, "PC_GPS_PORT_PARM" }, \ - { PC_GPS_ANT_INFO, "PC_GPS_ANT_INFO" }, \ - { PC_GPS_UCAP, "PC_GPS_UCAP" }, \ - { PC_GPS_ENABLE_FLAGS, "PC_GPS_ENABLE_FLAGS" }, \ - { PC_GPS_STAT_INFO, "PC_GPS_STAT_INFO" }, \ - { PC_GPS_CMD, "PC_GPS_CMD" }, \ - { PC_GPS_IDENT, "PC_GPS_IDENT" }, \ - { PC_GPS_POS, "PC_GPS_POS" }, \ - { PC_GPS_ANT_CABLE_LEN, "PC_GPS_ANT_CABLE_LEN" }, \ - { PC_GPS_RECEIVER_INFO, "PC_GPS_RECEIVER_INFO" }, \ - { PC_GPS_ALL_STR_TYPE_INFO, "PC_GPS_ALL_STR_TYPE_INFO" }, \ - { PC_GPS_ALL_PORT_INFO, "PC_GPS_ALL_PORT_INFO" }, \ - { PC_GPS_PORT_SETTINGS_IDX, "PC_GPS_PORT_SETTINGS_IDX" }, \ - { PC_GPS_ALL_POUT_INFO, "PC_GPS_ALL_POUT_INFO" }, \ - { PC_GPS_POUT_SETTINGS_IDX, "PC_GPS_POUT_SETTINGS_IDX" }, \ - { PC_GPS_TIME_SCALE, "PC_GPS_TIME_SCALE" }, \ - { PC_GPS_LAN_IF_INFO, "PC_GPS_LAN_IF_INFO" }, \ - { PC_GPS_IP4_STATE, "PC_GPS_IP4_STATE" }, \ - { PC_GPS_IP4_SETTINGS, "PC_GPS_IP4_SETTINGS" }, \ - { PC_GPS_PTP_STATE, "PC_GPS_PTP_STATE" }, \ - { PC_GPS_PTP_CFG, "PC_GPS_PTP_CFG" }, \ - { PC_GPS_PTP_UC_MASTER_CFG_LIMITS, "PC_GPS_PTP_UC_MASTER_CFG_LIMITS" }, \ - { PC_GPS_ALL_PTP_UC_MASTER_INFO, "PC_GPS_ALL_PTP_UC_MASTER_INFO" }, \ - { PC_GPS_PTP_UC_MASTER_SETTINGS_IDX, "PC_GPS_PTP_UC_MASTER_SETTINGS_IDX" }, \ - { PC_GPS_GPIO_CFG_LIMITS, "PC_GPS_GPIO_CFG_LIMITS" }, \ - { PC_GPS_ALL_GPIO_INFO, "PC_GPS_ALL_GPIO_INFO" }, \ - { PC_GPS_GPIO_SETTINGS_IDX, "PC_GPS_GPIO_SETTINGS_IDX" }, \ - { PC_GPS_CFGH, "PC_GPS_CFGH" }, \ - { PC_GPS_ALM, "PC_GPS_ALM" }, \ - { PC_GPS_EPH, "PC_GPS_EPH" }, \ - { PC_GPS_UTC, "PC_GPS_UTC" }, \ - { PC_GPS_IONO, "PC_GPS_IONO" }, \ - { PC_GPS_ASCII_MSG, "PC_GPS_ASCII_MSG" }, \ - { 0, NULL } \ +#define PC_GPS_CMD_CODES_TABLE \ +{ \ + _mbg_cn_table_entry( PC_GPS_TZDL ), \ + _mbg_cn_table_entry( PC_GPS_SW_REV ), \ + _mbg_cn_table_entry( PC_GPS_BVAR_STAT ), \ + _mbg_cn_table_entry( PC_GPS_TIME ), \ + _mbg_cn_table_entry( PC_GPS_POS_XYZ ), \ + _mbg_cn_table_entry( PC_GPS_POS_LLA ), \ + _mbg_cn_table_entry( PC_GPS_PORT_PARM ), \ + _mbg_cn_table_entry( PC_GPS_ANT_INFO ), \ + _mbg_cn_table_entry( PC_GPS_UCAP ), \ + _mbg_cn_table_entry( PC_GPS_ENABLE_FLAGS ), \ + _mbg_cn_table_entry( PC_GPS_STAT_INFO ), \ + _mbg_cn_table_entry( PC_GPS_CMD ), \ + _mbg_cn_table_entry( PC_GPS_IDENT ), \ + _mbg_cn_table_entry( PC_GPS_POS ), \ + _mbg_cn_table_entry( PC_GPS_ANT_CABLE_LEN ), \ + _mbg_cn_table_entry( PC_GPS_RECEIVER_INFO ), \ + _mbg_cn_table_entry( PC_GPS_ALL_STR_TYPE_INFO ), \ + _mbg_cn_table_entry( PC_GPS_ALL_PORT_INFO ), \ + _mbg_cn_table_entry( PC_GPS_PORT_SETTINGS_IDX ), \ + _mbg_cn_table_entry( PC_GPS_ALL_POUT_INFO ), \ + _mbg_cn_table_entry( PC_GPS_POUT_SETTINGS_IDX ), \ + _mbg_cn_table_entry( PC_GPS_TIME_SCALE ), \ + _mbg_cn_table_entry( PC_GPS_LAN_IF_INFO ), \ + _mbg_cn_table_entry( PC_GPS_IP4_STATE ), \ + _mbg_cn_table_entry( PC_GPS_IP4_SETTINGS ), \ + _mbg_cn_table_entry( PC_GPS_PTP_STATE ), \ + _mbg_cn_table_entry( PC_GPS_PTP_CFG ), \ + _mbg_cn_table_entry( PC_GPS_PTP_UC_MASTER_CFG_LIMITS ), \ + _mbg_cn_table_entry( PC_GPS_ALL_PTP_UC_MASTER_INFO ), \ + _mbg_cn_table_entry( PC_GPS_PTP_UC_MASTER_SETTINGS_IDX ), \ + _mbg_cn_table_entry( PC_GPS_GPIO_CFG_LIMITS ), \ + _mbg_cn_table_entry( PC_GPS_ALL_GPIO_INFO ), \ + _mbg_cn_table_entry( PC_GPS_GPIO_SETTINGS_IDX ), \ + _mbg_cn_table_entry( PC_GPS_GNSS_MODE ), \ + _mbg_cn_table_entry( PC_GPS_ALL_GNSS_SAT_INFO ), \ + _mbg_cn_table_entry( PC_GPS_XMR_INSTANCES ), \ + _mbg_cn_table_entry( PC_GPS_XMR_SETTINGS_IDX ), \ + _mbg_cn_table_entry( PC_GPS_ALL_XMR_INFO ), \ + _mbg_cn_table_entry( PC_GPS_ALL_XMR_STATUS ), \ + _mbg_cn_table_entry( PC_GPS_XMR_HOLDOVER_STATUS ), \ + _mbg_cn_table_entry( PC_GPS_ALL_GPIO_STATUS ), \ + _mbg_cn_table_entry( PC_GPS_XFEATURE_BUFFER ), \ + _mbg_cn_table_entry( PC_GPS_TLV_INFO ), \ + \ + _mbg_cn_table_entry( PC_GPS_CFGH ), \ + _mbg_cn_table_entry( PC_GPS_ALM ), \ + _mbg_cn_table_entry( PC_GPS_EPH ), \ + _mbg_cn_table_entry( PC_GPS_UTC ), \ + _mbg_cn_table_entry( PC_GPS_IONO ), \ + _mbg_cn_table_entry( PC_GPS_ASCII_MSG ), \ + _mbg_cn_table_end() \ } -/** codes used with PC_GPS_CMD */ -enum +/** + * @brief Codes used with ::PC_GPS_CMD + * + * @note These commands should only used with care, in very rare cases! + */ +enum PC_GPS_COMMANDS //##++++++++++++++ { - PC_GPS_CMD_BOOT = 1, /**< force the clock to boot mode */ - PC_GPS_CMD_INIT_SYS, /**< let the clock clear its system variables */ - PC_GPS_CMD_INIT_USER, /**< reset the clock's user parameters to defaults */ - PC_GPS_CMD_INIT_DAC, /**< initialize the oscillator disciplining values */ - N_PC_GPS_CMD /**< no command, just the number of known commands */ + PC_GPS_CMD_BOOT = 1, ///< force 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 }; -// The type below can be used to store an unambiguous command code. -// In case of the standard PCPS_... commands the lower byte contains -// the command code and the upper byte is 0. -// In case of a GPS command the lower byte contains PCPS_READ_GPS_DATA -// or PCPS_WRITE_GPS_DATA, as appropriate, and the upper byte contains -// the associated PC_GPS_... type 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. + * In case of a GPS command the lower byte contains ::PCPS_READ_GPS_DATA + * or ::PCPS_WRITE_GPS_DATA, as appropriate, and the upper byte contains + * the associated type code from ::PC_GPS_CMD_CODES. + * + * Used internally by the firmware only. + */ typedef uint16_t PCPS_CMD_INFO; diff --git a/mbglib/common/pcpsdev.h b/mbglib/common/pcpsdev.h index b13d07a..eccb9ca 100644 --- a/mbglib/common/pcpsdev.h +++ b/mbglib/common/pcpsdev.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsdev.h 1.51 2013/01/25 15:44:21Z martin REL_M $ + * $Id: pcpsdev.h 1.58 2018/11/02 14:58:43Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -17,7 +17,48 @@ * * ----------------------------------------------------------------------- * $Log: pcpsdev.h $ - * Revision 1.51 2013/01/25 15:44:21Z martin + * Revision 1.58 2018/11/02 14:58:43Z martin + * Updated a comment. + * Revision 1.57 2018/09/21 15:04:23 martin + * Added definitions for TCR180USB. + * Added define MBG_DEV_NAME_FMT and macro _tlv_feat_buffp(); + * Defined a print format for firmware versions. + * Renamed macro _must_do_fw_workaround_20ms() + * to _pcps_fw_has_20ms_bug(). + * More unified resource handling. + * Renamed a number of symbols. + * Updated naming for device feature stuff. + * Added doxygen comments. + * Revision 1.56 2017/07/04 16:31:08 martin + * New types PCPS_CLOCK_NAME and MBG_DEV_NAME. + * Definitions used with new feature check implementation. + * Changed some macros and definitions to clean up + * I/O port usage and storage. + * Moved some definitions used with IOCTLs to mbgioctl.h. + * Revision 1.55 2017/04/25 11:36:40 martin + * Renamed GRC181PEX to GNS181PEX. + * Revision 1.54 2017/01/27 09:10:57 martin + * Support GPS180AMC. + * Support GRC181PEX. + * Support GPIO ports. + * IRIG TX support for GPS180PEX and TCR180PEX only + * if GPS_HAS_IRIG_TX flag is set. + * New type PCPS_FW_REV_NUM. + * Moved some code to new module mbgsystm.h. + * Moved NANO_TIME_64 to gpsdefs.h. + * Moved inline function num_bits_set() to cfg_hlp.h. + * Added macro _ri_addr(). + * Added macro _pcps_has_ri_xmr(). + * Fixed macro syntax. + * Doxygen stuff. + * Removed trailing spaces. + * Cleanup. + * Revision 1.53 2013/11/08 08:46:00 martin + * Doxygen comment updates. + * Revision 1.52 2013/09/26 09:06:47Z martin + * Support GLN180PEX and GNSS API. + * Added inline fnc num_bits_set(). + * Revision 1.51 2013/01/25 15:44:21 martin * Added inline function setup_hr_time_cycles_from_timestamp_cycles() which sets * up a PCPS_HR_TIME_CYCLES structure from PCPS_TIME_STAMP_CYCLES. * Revision 1.50 2012/10/02 19:00:46 martin @@ -88,7 +129,7 @@ * Moved some inline functions dealing with MBG_PC_CYCLES * from mbgdevio.h here. * Merged the code from _pcps_get_cycles() and _pcps_get_cycles_frequency() - * to the mbg_get_pc_cycles...() inline functions which now replace the + * to the mbg_get_pc_cycles...() inline functions which now replace the * _pcps_get_cycles...() macros. * Fixed cycles code for non-x86 architectures. * Revision 1.39 2008/12/05 16:24:24Z martin @@ -99,7 +140,7 @@ * Defined firmware version numbers which fix an IRQ problem with PEX511, * TCR511PEX, and GPS170PEX cards. The fix also requires specific ASIC * versions specified in pci_asic.h. - * Defined firmware versions at which PCI511 and PEX511 start + * Defined firmware versions at which PCI511 and PEX511 start * to support HR time. * Support mapped I/O resources. * Changed MBG_PC_CYCLES type for Windows to int64_t. @@ -119,11 +160,11 @@ * _psps_has_asic_version(), _pcps_has_asic_features(). * Revision 1.37 2008/01/17 09:58:11Z daniel * Made comments compatible for doxygen parser. - * No sourcecode changes. + * No sourcecode changes. * Revision 1.36 2007/09/26 09:34:38Z martin * Added support for USB in general and new USB device USB5131. * Added new types PCPS_DEV_ID and PCPS_REF_TYPE. - * Removed old PCPS_ERR_... codes. Use MBG_ERR_... codes + * Removed old PCPS_ERR_... codes. Use MBG_ERR_... codes * from mbgerror.h instead. The old values haven't changed. * Revision 1.35 2007/07/17 08:22:47Z martin * Added support for TCR511PEX and GPS170PEX. @@ -136,15 +177,15 @@ * Preliminary support for *BSD. * Preliminary support for USB. * Revision 1.32 2006/10/23 08:47:55Z martin - * Don't use abs() in _pcps_ref_offs_out_of_range() since this might + * Don't use abs() in _pcps_ref_offs_out_of_range() since this might * not work properly for 16 bit integers and value 0x8000. * Revision 1.31 2006/06/14 12:59:13Z martin * Added support for TCR511PCI. * Revision 1.30 2006/04/05 14:58:41 martin * Support higher baud rates for PCI511. * Revision 1.29 2006/04/03 07:29:07Z martin - * Added a note about the missing PCPS_ST_IRQF signal - * on PCI510 cards. + * Added a note about the missing PCPS_ST_IRQF signal + * on PCI510 cards. * Revision 1.28 2006/03/10 10:32:56Z martin * Added support for PCI511. * Added support for programmable pulse outputs. @@ -165,8 +206,8 @@ * New type PCPS_STATUS_PORT. * Removed obsolete inclusion of asm/timex.h for Linux. * Revision 1.21 2004/09/06 15:19:49Z martin - * Support a GPS_DATA interface where sizes are specified - * by 16 instead of the original 8 bit quantities, thus allowing + * 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 definition of MBG_PC_CYCLES for Linux. @@ -245,6 +286,7 @@ #include <mbg_tgt.h> #include <mbgtime.h> +#include <mbgsystm.h> #include <mbgpccyc.h> #include <pcpsdefs.h> #include <gpsdefs.h> @@ -255,20 +297,10 @@ #include <string.h> #endif -#if defined( MBG_TGT_WIN32 ) - - #include <mbg_w32.h> - -#elif defined( MBG_TGT_LINUX ) +#if defined( MBG_TGT_LINUX ) - #if defined( MBG_TGT_KERNEL ) - #include <linux/delay.h> - #include <linux/time.h> - #else + #if !defined( MBG_TGT_KERNEL ) #include <unistd.h> - #include <time.h> - #include <sys/time.h> - #include <sys/sysinfo.h> #endif #elif defined( MBG_TGT_FREEBSD ) @@ -286,10 +318,7 @@ #elif defined( MBG_TGT_NETBSD ) - #if defined( MBG_TGT_KERNEL ) - #include <sys/param.h> // mstohz - #include <sys/kernel.h> // hz - #else + #if !defined( MBG_TGT_KERNEL ) #include <unistd.h> #include <sys/time.h> #endif @@ -315,83 +344,20 @@ #endif -#if defined( MBG_TGT_UNIX ) - #define USE_GENERIC_SYS_TIME 1 -#else - #define USE_GENERIC_SYS_TIME 0 -#endif - - -#if USE_GENERIC_SYS_TIME - - typedef struct - { - uint64_t sec; - uint64_t nsec; - } NANO_TIME_64; - - typedef NANO_TIME_64 MBG_SYS_TIME; - -#endif - - - -/** - Define generic types to hold PC cycle counter values and system timestamps. - The generic types are defined using native types used by the target operating - systems. - - The cycle counter value is usually derived from the PC CPU's TSC or some other - timer hardware on the mainboard. - */ -#if defined( MBG_TGT_WIN32 ) - - #define MBG_TGT_SUPP_MEM_ACC 1 - - typedef int64_t MBG_SYS_UPTIME; // [s] - - typedef LARGE_INTEGER MBG_SYS_TIME; - -#elif defined( MBG_TGT_LINUX ) +#if defined( MBG_TGT_LINUX ) #define MBG_TGT_SUPP_MEM_ACC 1 - typedef int64_t MBG_SYS_UPTIME; // [s] - #elif defined( MBG_TGT_BSD ) #define MBG_TGT_SUPP_MEM_ACC 1 - typedef int64_t MBG_SYS_UPTIME; // [s] +#elif defined( MBG_TGT_WIN32 ) - #if defined( MBG_TGT_NETBSD ) - #ifdef __LP64__ - #define MBG_MEM_ADDR uint64_t - #else - #define MBG_MEM_ADDR uint32_t - #endif - #endif - -#elif defined( MBG_TGT_OS2 ) - - typedef long MBG_SYS_UPTIME; //## dummy - - typedef uint32_t MBG_SYS_TIME; //## dummy + #define MBG_TGT_SUPP_MEM_ACC 1 #elif defined( MBG_TGT_DOS ) - #define MBG_MEM_ADDR uint32_t // 64 bit not supported, nor required. - - typedef long MBG_SYS_UPTIME; //## dummy - - typedef uint32_t MBG_SYS_TIME; //## dummy - -#else // other target OSs which access the hardware directly - - typedef long MBG_SYS_UPTIME; //## dummy - - typedef uint32_t MBG_SYS_TIME; //## dummy - #endif @@ -400,331 +366,54 @@ #endif -// MBG_SYS_TIME is always read in native machine endianess, -// so no endianess conversion is required. -#define _mbg_swab_mbg_sys_time( _p ) \ - _nop_macro_fnc() +typedef uint8_t MBG_DBG_DATA; +typedef uint16_t MBG_DBG_PORT; /** - The structure holds a system timestamp in a format depending on the target OS - plus two cycles counter values which can be taken before and after reading - the system time. These cycles values can be used to determine the execution - time required to read the system time. - - Limitations of the operating system need to be taken into account, - e.g. the Windows system time may increase once every ~16 ms only. - */ + * @brief System time plus associated cycles counter values + * + * The structure holds a system timestamp in a format depending on the target OS + * plus two cycles counter values which can be taken before and after reading + * the system time. These cycles values can be used to determine the execution + * time required to read the system time. + * + * Limitations of the operating system need to be taken into account, + * e.g. the Windows system time may increase once every ~16 ms or ~1 ms only, + * depending on the Windows version. + */ typedef struct { - MBG_PC_CYCLES cyc_before; /**< cycles count before sys time is read */ - MBG_PC_CYCLES cyc_after; /**< cycles count after sys time has been read */ - MBG_SYS_TIME sys_time; /**< system time stamp */ + MBG_PC_CYCLES cyc_before; ///< cycles count before sys time is read + MBG_PC_CYCLES cyc_after; ///< cycles count after sys time has been read + MBG_SYS_TIME sys_time; ///< system time stamp + } MBG_SYS_TIME_CYCLES; #define _mbg_swab_mbg_sys_time_cycles( _p ) \ +do \ { \ _mbg_swab_mbg_pc_cycles( &(_p)->cyc_before ); \ _mbg_swab_mbg_pc_cycles( &(_p)->cyc_after ); \ _mbg_swab_mbg_sys_time( &(_p)->sys_time ); \ -} - - - - -static __mbg_inline -void mbg_get_sys_time( MBG_SYS_TIME *p ) -{ - #if defined( MBG_TGT_WIN32 ) - - #if defined( MBG_TGT_KERNEL ) // kernel space - #if defined( MBG_TGT_WIN32_PNP ) && !defined( MBG_TGT_WIN32_PNP_X64 ) - extern KE_QUERY_SYSTEM_TIME_FNC ke_query_system_time_fnc; - ke_query_system_time_fnc( p ); - #else - KeQuerySystemTime( p ); - #endif - #else // user space - { - FILETIME ft; - GetSystemTimeAsFileTime( &ft ); - p->LowPart = ft.dwLowDateTime; - p->HighPart = ft.dwHighDateTime; - } - #endif - - #elif defined( MBG_TGT_LINUX ) - - #if defined( MBG_TGT_KERNEL ) - - #if ( LINUX_VERSION_CODE >= KERNEL_VERSION( 2, 6, 22 ) ) //##+++++++++++++ - { - // getnstimeofday() supported - struct timespec ts; - - getnstimeofday( &ts ); - - p->sec = ts.tv_sec; - p->nsec = ts.tv_nsec; - } - #else - { - // getnstimeofday() *not* supported - struct timeval tv; - - do_gettimeofday( &tv ); - - p->sec = tv.tv_sec; - p->nsec = tv.tv_usec * 1000; - } - #endif - - #else // Linux user space - { - struct timespec ts; - - clock_gettime( CLOCK_REALTIME, &ts ); - - p->sec = ts.tv_sec; - p->nsec = ts.tv_nsec; - } - #endif - - #elif defined( MBG_TGT_BSD ) - - struct timespec ts; - - #if defined( MBG_TGT_KERNEL ) - nanotime( &ts ); - #else - #if defined( MBG_TGT_FREEBSD ) - clock_gettime( CLOCK_REALTIME_PRECISE, &ts ); - #else // MBG_TGT_NETBSD, ... - clock_gettime( CLOCK_REALTIME, &ts ); - #endif - #endif - - p->sec = ts.tv_sec; - p->nsec = ts.tv_nsec; - - #else - - *p = 0; - - #endif - -} // mbg_get_sys_time +} while ( 0 ) -static __mbg_inline -void mbg_get_sys_uptime( MBG_SYS_UPTIME *p ) -{ - #if defined( MBG_TGT_WIN32 ) - - #if defined( MBG_TGT_KERNEL ) // kernel space - - ULONGLONG time_increment = KeQueryTimeIncrement(); - LARGE_INTEGER tick_count; - - KeQueryTickCount( &tick_count ); - - // multiplication by time_increment yields HNS units, - // but we need seconds - *p = ( tick_count.QuadPart * time_increment ) / HNS_PER_SEC; - - #else // user space - - DWORD tickCount; - DWORD timeAdjustment; - DWORD timeIncrement; - BOOL timeAdjustmentDisabled; - - if ( !GetSystemTimeAdjustment( &timeAdjustment, &timeIncrement, &timeAdjustmentDisabled ) ) - *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. - tickCount = GetTickCount(); - - *p = ( ( (MBG_SYS_UPTIME) tickCount ) * timeIncrement ) / HNS_PER_SEC; - - #endif - - #elif defined( MBG_TGT_LINUX ) - - #if defined( MBG_TGT_KERNEL ) - { - // 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(). - // 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; - do_div( tmp, HZ ); - *p = tmp; - } - #else - { - struct sysinfo si; - int rc = sysinfo( &si ); - *p = ( rc == 0 ) ? si.uptime : -1; - } - #endif - - #elif defined( MBG_TGT_BSD ) - - #if defined( MBG_TGT_KERNEL ) - { - struct timespec ts; - #if 0 //##+++++++ - { - struct bintime bt; - - binuptime( &bt ); - #if defined( DEBUG ) - printf( "binuptime: %lli.%09lli\n", - (long long) bt.sec, - (long long) bt.frac ); - #endif - } - #endif - - nanouptime( &ts ); - #if defined( DEBUG ) - printf( "nanouptime: %lli.%09lli\n", - (long long) ts.tv_sec, - (long long) ts.tv_nsec ); - #endif - *p = ts.tv_sec; - } - #elif defined( MBG_TGT_FREEBSD ) - { - struct timespec ts; - // 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 - - #endif - - #else - - *p = -1; // not supported - - #endif - -} // mbg_get_sys_uptime - - - -static __mbg_inline -void mbg_sleep_sec( long sec ) -{ - #if defined( MBG_TGT_WIN32 ) - - #if defined( MBG_TGT_KERNEL ) // 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 - // time. See the API docs for KeDelayExecutionThread(). - delay.QuadPart = - ((LONGLONG) sec * HNS_PER_SEC); - - KeDelayExecutionThread( KernelMode, FALSE, &delay ); - #else // user space - // Sleep() expects milliseconds - Sleep( sec * 1000 ); - #endif - - #elif defined( MBG_TGT_LINUX ) - - #if defined( MBG_TGT_KERNEL ) - // msleep is not defined in older kernels, so we use this - // only if it is surely supported. - #if ( LINUX_VERSION_CODE >= KERNEL_VERSION( 2, 6, 16 ) ) //##+++++ - msleep( sec * 1000 ); - #else - { - DECLARE_WAIT_QUEUE_HEAD( tmp_wait ); - wait_event_interruptible_timeout( tmp_wait, 0, sec * HZ + 1 ); - } - #endif - #else - sleep( sec ); - #endif - - #elif defined( MBG_TGT_BSD ) - - #if defined( MBG_TGT_KERNEL ) - #if defined( MBG_TGT_FREEBSD ) - struct timeval tv = { 0 }; - int ticks; - tv.tv_sec = sec; - ticks = tvtohz( &tv ); - #if defined( DEBUG ) - printf( "pause: %lli.%06lli (%i ticks)\n", - (long long) tv.tv_sec, - (long long) tv.tv_usec, - ticks ); - #endif - pause( "pause", ticks ); - #elif defined( MBG_TGT_NETBSD ) - int timeo = mstohz( sec * 1000 ); - #if defined( DEBUG ) - printf( "kpause: %i s (%i ticks)\n", sec, timeo ); - #endif - kpause( "pause", 1, timeo, NULL ); - #endif - #else - sleep( sec ); - #endif - - #elif defined( MBG_TGT_QNX_NTO ) - - // Actually only tested under Neutrino. - sleep( sec ); - - #elif defined( MBG_TGT_DOS ) - - delay( (unsigned) ( sec * 1000 ) ); - - #else - - // This needs to be implemented for the target OS - // and thus will probably yield a linker error. - do_sleep_sec( sec ); - - #endif - -} // mbg_sleep_sec - - - -#if !defined( MBG_MEM_ADDR ) - // By default a memory address is stored - // as a 64 bit quantitiy. - #define MBG_MEM_ADDR uint64_t -#endif - - -typedef uint8_t MBG_DBG_DATA; -typedef uint16_t MBG_DBG_PORT; - +/** + * @defgroup group_bus_flag_masks BUS flag masks + * + * @anchor PCPS_BUS_FLAG_MASKS + * + * @{ */ // The following flags describe the bus types which are // supported by the plugin clocks. -#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 +#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 // The flags below are or'ed to the PC_BUS_PCI code @@ -732,10 +421,10 @@ typedef uint16_t MBG_DBG_PORT; // 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. -#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 +#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 // The constants below combine the PCI bus flags: #define PCPS_BUS_PCI_S5933 ( PCPS_BUS_PCI ) @@ -754,9 +443,13 @@ typedef uint16_t MBG_DBG_PORT; // The constant below combines the PCI bus flags: #define PCPS_BUS_USB_V2 ( PCPS_BUS_USB | PCPS_BUS_USB_FLAG_V2 ) +/** @} defgroup group_bus_flag_masks */ + -/** A list of known radio clocks. */ +/** + * @brief A list of known devices + */ enum PCPS_TYPES { PCPS_TYPE_PC31, @@ -792,120 +485,175 @@ enum PCPS_TYPES PCPS_TYPE_TCR600USB, PCPS_TYPE_MSF600USB, PCPS_TYPE_WVB600USB, + PCPS_TYPE_GLN180PEX, + PCPS_TYPE_GPS180AMC, + PCPS_TYPE_GNS181PEX, + PCPS_TYPE_TCR180USB, N_PCPS_DEV_TYPE }; #define PCPS_CLOCK_NAME_SZ 10 // including terminating 0 +typedef char PCPS_CLOCK_NAME[PCPS_CLOCK_NAME_SZ]; + typedef uint16_t PCPS_DEV_ID; typedef uint16_t PCPS_REF_TYPE; typedef uint16_t PCPS_BUS_FLAGS; /** - The structure contains the characteristics of each - of the clocks listed above. These fields are always the - same for a single type of clock and do not change with - firmware version, port address, etc. - */ + * @brief Device type specification + * + * Contains the characteristics of one of the ::PCPS_TYPES. + * These specifications are always the same for a particular + * type of device and do not change with firmware version, + * port address, etc. + */ typedef struct { - uint16_t num; - char name[PCPS_CLOCK_NAME_SZ]; - PCPS_DEV_ID dev_id; - PCPS_REF_TYPE ref_type; - PCPS_BUS_FLAGS bus_flags; + uint16_t 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_TYPE; -#if !defined( MBG_TGT_UNIX ) || defined( MBG_ARCH_X86 ) - typedef uint16_t PCPS_PORT_ADDR; -#else - typedef uint64_t PCPS_PORT_ADDR; -#endif - +/** + * @brief Legacy I/O address type, see ::PCPS_SHORT_PORT_RSRC + */ +typedef uint16_t PCPS_SHORT_PORT_ADDR; /** - The structure below describes an I/O port resource - used by a clock. -*/ + * @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. + * However, the 16 bits provided by ::PCPS_SHORT_PORT_ADDR may + * not be sufficient to hold an address on some target platforms, + * so this is only kept to maintain API compatibility when + * reporting I/O addresses to user space via ::PCPS_DEV_CFG + * and thus ::PCPS_DEV structures. + * A different structure is actually being used internally + * by the kernel drivers. + */ typedef struct { - PCPS_PORT_ADDR base; + PCPS_SHORT_PORT_ADDR base; uint16_t num; -} PCPS_PORT_RSRC; -/** The max number of I/O port resources used by a clock. */ +} PCPS_SHORT_PORT_RSRC; + + + +/** + * @brief The max. number of I/O port resources used by a clock + */ #define N_PCPS_PORT_RSRC 2 +/** + * @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. + */ typedef struct { - MBG_MEM_ADDR user_virtual_address; + void *user_virtual_address; // TODO #if defined( MBG_TGT_LINUX ) uint64_t len; uint64_t pfn_offset; #else ulong len; #endif + } PCPS_MAPPED_MEM; -typedef uint32_t PCPS_ERR_FLAGS; /**< see \ref group_err_flags "Error flags" */ -typedef uint32_t PCPS_FEATURES; /**< see \ref group_features "Features" */ +typedef uint32_t PCPS_ERR_FLAGS; ///< see @ref PCPS_ERR_FLAG_MASKS +typedef uint32_t PCPS_FEATURES; ///< see @ref PCPS_FEATURE_MASKS typedef uint16_t PCPS_BUS_NUM; typedef uint16_t PCPS_SLOT_NUM; +typedef uint16_t PCPS_FW_REV_NUM; ///< firmware revision number, MSB major, LSB minor version /** - The structure below contains data which depends - on a individual instance of the clock, e.g. - the firmware which is currently installed, the - port address which has been configured, etc. -*/ + * @brief Device information + * + * Contains variable device data which depends on a particular instance + * of a device, e.g. the firmware which is currently installed, the + * port address which has actually been assigned, etc. + * + * @note This structure only contains an incomplete subset of + * information for newer devices, e.g. no memory resources, + * and no extended device features. + * However, adding the missing information would break + * compatibility of some API functions. + */ typedef struct { - PCPS_ERR_FLAGS err_flags; /**< See \ref group_err_flags "Error flags" */ + PCPS_ERR_FLAGS err_flags; ///< See @ref PCPS_ERR_FLAG_MASKS PCPS_BUS_NUM bus_num; PCPS_SLOT_NUM slot_num; - PCPS_PORT_RSRC port[N_PCPS_PORT_RSRC]; - uint16_t status_port; + PCPS_SHORT_PORT_RSRC port[N_PCPS_PORT_RSRC]; + PCPS_SHORT_PORT_ADDR short_status_port; int16_t irq_num; uint32_t timeout_clk; - uint16_t fw_rev_num; - PCPS_FEATURES features; /**< See \ref group_features "Feature flags" */ + PCPS_FW_REV_NUM fw_rev_num; + PCPS_FEATURES features; ///< See @ref PCPS_FEATURE_MASKS PCPS_ID_STR fw_id; PCPS_SN_STR sernum; + } PCPS_DEV_CFG; -/** @defgroup group_err_flags Error flags in PCPS_DEV_CFG - Flags used with PCPS_DEV_CFG::err_flags - @{ -*/ -#define PCPS_EF_TIMEOUT 0x00000001 /**< timeout occured */ -#define PCPS_EF_INV_EPROM_ID 0x00000002 /**< invalid EPROM ID */ -#define PCPS_EF_IO_INIT 0x00000004 /**< I/O intf not init'd */ -#define PCPS_EF_IO_CFG 0x00000008 /**< I/O intf not cfg'd */ -#define PCPS_EF_IO_ENB 0x00000010 /**< I/O intf not enabled */ -#define PCPS_EF_IO_RSRC 0x00000020 /**< I/O not registered w/ rsrcmgr */ -/** @} */ - -/** @defgroup group_features Feature flags used with PCPS_FEATURES - - Some features of the radio clocks have been introduced with - specific firmware versions, so depending on the firmware version - a clock may support a feature or not. The clock detection function - checks the clock model and firmware version and updates the field - PCPS_DEV_CFG::features accordingly. There are some macros which - can easily be used to query whether a clock device actually - supports a function, or not. The definitions define - the possible features. - @{ -*/ -enum + + +/** + * @brief Possible device initialization error flags + * + * Used with ::PCPS_DEV_CFG::err_flags + * + * @see ::PCPS_ERR_FLAGS + * + * @anchor PCPS_ERR_FLAG_MASKS @{ */ + +#define PCPS_EF_TIMEOUT 0x00000001 ///< timeout occured +#define PCPS_EF_INV_FW_ID 0x00000002 ///< invalid firmware ID +#define PCPS_EF_IO_INIT 0x00000004 ///< I/O interface not initialized +#define PCPS_EF_IO_CFG 0x00000008 ///< I/O interface not configured +#define PCPS_EF_IO_ENB 0x00000010 ///< I/O interface not enabled +#define PCPS_EF_IO_RSRC_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 */ + + + +/** + * @defgroup group_pcps_features Feature flags used with PCPS_FEATURES + * + * Some features of the radio clocks have been introduced with + * specific firmware versions, so depending on the firmware version + * a clock may support a feature or not. The clock detection function + * checks the clock model and firmware version and updates the field + * ::PCPS_DEV_CFG::features accordingly. There are some macros which + * can easily be used to query whether a clock device actually + * supports a function, or not. + * + * @see ::PCPS_FEATURES + * + * @{ */ + +/** + * @brief Feature bits for bus-level devices + * + * @see @ref PCPS_FEATURE_MASKS + */ +enum PCPS_FEATURE_BITS { PCPS_BIT_CAN_SET_TIME, PCPS_BIT_HAS_SERIAL, @@ -939,41 +687,58 @@ enum PCPS_BIT_HAS_RAW_IRIG_DATA, PCPS_BIT_HAS_PZF, // can also demodulate DCF77 PZF PCPS_BIT_HAS_EVT_LOG, + PCPS_BIT_IS_GNSS, // supports several satellite systems and GNSS API calls - N_PCPS_FEATURE // must not exceed 32 !! + N_PCPS_FEATURE_BITS // must not exceed 32 !! }; -#define PCPS_CAN_SET_TIME ( 1UL << PCPS_BIT_CAN_SET_TIME ) -#define PCPS_HAS_SERIAL ( 1UL << PCPS_BIT_HAS_SERIAL ) -#define PCPS_HAS_SYNC_TIME ( 1UL << PCPS_BIT_HAS_SYNC_TIME ) -#define PCPS_HAS_TZDL ( 1UL << PCPS_BIT_HAS_TZDL ) -#define PCPS_HAS_IDENT ( 1UL << PCPS_BIT_HAS_IDENT ) -#define PCPS_HAS_UTC_OFFS ( 1UL << PCPS_BIT_HAS_UTC_OFFS ) -#define PCPS_HAS_HR_TIME ( 1UL << PCPS_BIT_HAS_HR_TIME ) -#define PCPS_HAS_SERNUM ( 1UL << PCPS_BIT_HAS_SERNUM ) -#define PCPS_HAS_TZCODE ( 1UL << PCPS_BIT_HAS_TZCODE ) -#define PCPS_HAS_CABLE_LEN ( 1UL << PCPS_BIT_HAS_CABLE_LEN ) -#define PCPS_HAS_EVENT_TIME ( 1UL << PCPS_BIT_HAS_EVENT_TIME ) -#define PCPS_HAS_RECEIVER_INFO ( 1UL << PCPS_BIT_HAS_RECEIVER_INFO ) -#define PCPS_CAN_CLR_UCAP_BUFF ( 1UL << PCPS_BIT_CAN_CLR_UCAP_BUFF ) -#define PCPS_HAS_PCPS_TZDL ( 1UL << PCPS_BIT_HAS_PCPS_TZDL ) -#define PCPS_HAS_UCAP ( 1UL << PCPS_BIT_HAS_UCAP ) -#define PCPS_HAS_IRIG_TX ( 1UL << PCPS_BIT_HAS_IRIG_TX ) -#define PCPS_HAS_GPS_DATA_16 ( 1UL << PCPS_BIT_HAS_GPS_DATA_16 ) -#define PCPS_HAS_SYNTH ( 1UL << PCPS_BIT_HAS_SYNTH ) -#define PCPS_HAS_GENERIC_IO ( 1UL << PCPS_BIT_HAS_GENERIC_IO ) -#define PCPS_HAS_TIME_SCALE ( 1UL << PCPS_BIT_HAS_TIME_SCALE ) -#define PCPS_HAS_UTC_PARM ( 1UL << PCPS_BIT_HAS_UTC_PARM ) -#define PCPS_HAS_IRIG_CTRL_BITS ( 1UL << PCPS_BIT_HAS_IRIG_CTRL_BITS ) -#define PCPS_HAS_LAN_INTF ( 1UL << PCPS_BIT_HAS_LAN_INTF ) -#define PCPS_HAS_PTP ( 1UL << PCPS_BIT_HAS_PTP ) -#define PCPS_HAS_IRIG_TIME ( 1UL << PCPS_BIT_HAS_IRIG_TIME ) -#define PCPS_HAS_FAST_HR_TSTAMP ( 1UL << PCPS_BIT_HAS_FAST_HR_TSTAMP ) -#define PCPS_HAS_RAW_IRIG_DATA ( 1UL << PCPS_BIT_HAS_RAW_IRIG_DATA ) -#define PCPS_HAS_PZF ( 1UL << PCPS_BIT_HAS_PZF ) -#define PCPS_HAS_EVT_LOG ( 1UL << PCPS_BIT_HAS_EVT_LOG ) +/** + * @brief Feature bit masks for bus-level devices + * + * Used with ::PCPS_DEV_CFG::features + * + * @see ::PCPS_FEATURE_BITS + * @see ::PCPS_FEATURES + * + * @anchor PCPS_FEATURE_MASKS @{ */ + +#define PCPS_CAN_SET_TIME ( 1UL << PCPS_BIT_CAN_SET_TIME ) ///< see ::PCPS_BIT_CAN_SET_TIME +#define PCPS_HAS_SERIAL ( 1UL << PCPS_BIT_HAS_SERIAL ) ///< see ::PCPS_BIT_HAS_SERIAL +#define PCPS_HAS_SYNC_TIME ( 1UL << PCPS_BIT_HAS_SYNC_TIME ) ///< see ::PCPS_BIT_HAS_SYNC_TIME +#define PCPS_HAS_TZDL ( 1UL << PCPS_BIT_HAS_TZDL ) ///< see ::PCPS_BIT_HAS_TZDL +#define PCPS_HAS_IDENT ( 1UL << PCPS_BIT_HAS_IDENT ) ///< see ::PCPS_BIT_HAS_IDENT +#define PCPS_HAS_UTC_OFFS ( 1UL << PCPS_BIT_HAS_UTC_OFFS ) ///< see ::PCPS_BIT_HAS_UTC_OFFS +#define PCPS_HAS_HR_TIME ( 1UL << PCPS_BIT_HAS_HR_TIME ) ///< see ::PCPS_BIT_HAS_HR_TIME +#define PCPS_HAS_SERNUM ( 1UL << PCPS_BIT_HAS_SERNUM ) ///< see ::PCPS_BIT_HAS_SERNUM + +#define PCPS_HAS_TZCODE ( 1UL << PCPS_BIT_HAS_TZCODE ) ///< see ::PCPS_BIT_HAS_TZCODE +#define PCPS_HAS_CABLE_LEN ( 1UL << PCPS_BIT_HAS_CABLE_LEN ) ///< see ::PCPS_BIT_HAS_CABLE_LEN +#define PCPS_HAS_EVENT_TIME ( 1UL << PCPS_BIT_HAS_EVENT_TIME ) ///< see ::PCPS_BIT_HAS_EVENT_TIME +#define PCPS_HAS_RECEIVER_INFO ( 1UL << PCPS_BIT_HAS_RECEIVER_INFO ) ///< see ::PCPS_BIT_HAS_RECEIVER_INFO +#define PCPS_CAN_CLR_UCAP_BUFF ( 1UL << PCPS_BIT_CAN_CLR_UCAP_BUFF ) ///< see ::PCPS_BIT_CAN_CLR_UCAP_BUFF +#define PCPS_HAS_PCPS_TZDL ( 1UL << PCPS_BIT_HAS_PCPS_TZDL ) ///< see ::PCPS_BIT_HAS_PCPS_TZDL +#define PCPS_HAS_UCAP ( 1UL << PCPS_BIT_HAS_UCAP ) ///< see ::PCPS_BIT_HAS_UCAP +#define PCPS_HAS_IRIG_TX ( 1UL << PCPS_BIT_HAS_IRIG_TX ) ///< see ::PCPS_BIT_HAS_IRIG_TX + +#define PCPS_HAS_GPS_DATA_16 ( 1UL << PCPS_BIT_HAS_GPS_DATA_16 ) ///< see ::PCPS_BIT_HAS_GPS_DATA_16 +#define PCPS_HAS_SYNTH ( 1UL << PCPS_BIT_HAS_SYNTH ) ///< see ::PCPS_BIT_HAS_SYNTH +#define PCPS_HAS_GENERIC_IO ( 1UL << PCPS_BIT_HAS_GENERIC_IO ) ///< see ::PCPS_BIT_HAS_GENERIC_IO +#define PCPS_HAS_TIME_SCALE ( 1UL << PCPS_BIT_HAS_TIME_SCALE ) ///< see ::PCPS_BIT_HAS_TIME_SCALE +#define PCPS_HAS_UTC_PARM ( 1UL << PCPS_BIT_HAS_UTC_PARM ) ///< see ::PCPS_BIT_HAS_UTC_PARM +#define PCPS_HAS_IRIG_CTRL_BITS ( 1UL << PCPS_BIT_HAS_IRIG_CTRL_BITS ) ///< see ::PCPS_BIT_HAS_IRIG_CTRL_BITS +#define PCPS_HAS_LAN_INTF ( 1UL << PCPS_BIT_HAS_LAN_INTF ) ///< see ::PCPS_BIT_HAS_LAN_INTF +#define PCPS_HAS_PTP ( 1UL << PCPS_BIT_HAS_PTP ) ///< see ::PCPS_BIT_HAS_PTP + +#define PCPS_HAS_IRIG_TIME ( 1UL << PCPS_BIT_HAS_IRIG_TIME ) ///< see ::PCPS_BIT_HAS_IRIG_TIME +#define PCPS_HAS_FAST_HR_TSTAMP ( 1UL << PCPS_BIT_HAS_FAST_HR_TSTAMP ) ///< see ::PCPS_BIT_HAS_FAST_HR_TSTAMP +#define PCPS_HAS_RAW_IRIG_DATA ( 1UL << PCPS_BIT_HAS_RAW_IRIG_DATA ) ///< see ::PCPS_BIT_HAS_RAW_IRIG_DATA +#define PCPS_HAS_PZF ( 1UL << PCPS_BIT_HAS_PZF ) ///< see ::PCPS_BIT_HAS_PZF +#define PCPS_HAS_EVT_LOG ( 1UL << PCPS_BIT_HAS_EVT_LOG ) ///< see ::PCPS_BIT_HAS_EVT_LOG +#define PCPS_IS_GNSS ( 1UL << PCPS_BIT_IS_GNSS ) ///< see ::PCPS_BIT_IS_GNSS + +/** @} anchor PCPS_FEATURE_MASKS */ #define PCPS_FEATURE_NAMES \ @@ -1006,10 +771,11 @@ enum "PCPS_HAS_FAST_HR_TSTAMP", \ "PCPS_HAS_RAW_IRIG_DATA", \ "PCPS_HAS_PZF", \ - "PCPS_HAS_EVT_LOG" \ + "PCPS_HAS_EVT_LOG", \ + "PCPS_IS_GNSS" \ } -/** @} */ +/** @} defgroup group_pcps_features */ @@ -1126,9 +892,13 @@ enum #define PCPS_FEAT_WWVB51USB ( PCPS_FEAT_MSF51USB ) -#define PCPS_FEAT_GPS180PEX ( PCPS_FEAT_GPS170PEX | PCPS_HAS_FAST_HR_TSTAMP ) +#define PCPS_FEAT_GPS180PEX ( ( PCPS_FEAT_GPS170PEX | PCPS_HAS_FAST_HR_TSTAMP ) \ + & ~PCPS_HAS_IRIG_TX ) + ///< IRIG TX only supp. if ::GPS_HAS_IRIG_TX -#define PCPS_FEAT_TCR180PEX ( PCPS_FEAT_TCR170PEX | PCPS_HAS_FAST_HR_TSTAMP ) +#define PCPS_FEAT_TCR180PEX ( ( PCPS_FEAT_TCR170PEX | PCPS_HAS_FAST_HR_TSTAMP ) \ + & ~PCPS_HAS_IRIG_TX ) + ///< IRIG TX only supp. if ::GPS_HAS_IRIG_TX #define PCPS_FEAT_DCF600USB ( PCPS_FEAT_USB5131 ) @@ -1153,6 +923,23 @@ enum #define PCPS_FEAT_WVB600USB ( PCPS_FEAT_WWVB51USB ) +#define PCPS_FEAT_GLN180PEX ( PCPS_FEAT_GPS180PEX | PCPS_IS_GNSS ) + +#define PCPS_FEAT_GPS180AMC ( PCPS_FEAT_GPS180PEX ) + +#define PCPS_FEAT_GNS181PEX ( PCPS_FEAT_GLN180PEX ) + +#define PCPS_FEAT_TCR180USB ( PCPS_FEAT_TCR600USB \ + | PCPS_HAS_TZDL \ + | PCPS_HAS_RECEIVER_INFO \ + | PCPS_HAS_GPS_DATA_16 \ + | PCPS_CAN_CLR_UCAP_BUFF /* TODO ? */ \ + | PCPS_HAS_UCAP /* TODO ? */ \ + | PCPS_HAS_GENERIC_IO /* TODO ? */ ) + ///< IRIG TX only supp. if ::GPS_HAS_IRIG_TX + + + // Some features of the API used to access Meinberg plug-in devices // have been implemented starting with the special firmware revision // numbers defined below. @@ -1162,12 +949,12 @@ enum // There are some versions of PCI Express cards out there which do not -// safely support hardware IRQs. The following firmware versions are required +// safely support hardware IRQs. The following firmware versions are required // for safe IRQ operation: #define REV_HAS_IRQ_FIX_MINOR_PEX511 0x0106 #define REV_HAS_IRQ_FIX_MINOR_TCR511PEX 0x0105 #define REV_HAS_IRQ_FIX_MINOR_GPS170PEX 0x0104 -// Additionally there are certain revisions of the bus interface logic +// Additionally there are certain revisions of the bus interface logic // required. The associated version codes are defined in pci_asic.h. // The macro below can be used to check whether the required versions are there: @@ -1192,8 +979,8 @@ enum #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 - instead of the original 8 bit sizes, thus allowing to transfer +/* This board 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) */ #define REV_HAS_GPS_DATA_16_GPS169PCI 0x0202 @@ -1248,16 +1035,26 @@ enum /** - The structure has been defined to pass all - information on a clock device from a device driver - to a user program. */ + * @brief Device info structure + * + * Used to pass all information on a bus-level device + * from a device driver to a user space application. + */ typedef struct { PCPS_DEV_TYPE type; PCPS_DEV_CFG cfg; + } PCPS_DEV; +#if 1 || defined( MBG_TGT_KERNEL ) //### FIXME + #define _USE_DEV_MACROS 1 +#else + #define _USE_DEV_MACROS 0 +#endif + + // The macros below simplify access to the data // stored in PCPS_DEV structure and should be used // to extract the desired information. @@ -1281,6 +1078,7 @@ typedef struct #define _pcps_is_irig_rx( _d ) ( _pcps_ref_type( _d ) == PCPS_REF_IRIG ) #define _pcps_is_ptp( _d ) ( _pcps_ref_type( _d ) == PCPS_REF_PTP ) #define _pcps_is_frc( _d ) ( _pcps_ref_type( _d ) == PCPS_REF_FRC ) +#define _pcps_is_gnss( _d ) _pcps_has_feature( (_d), PCPS_IS_GNSS ) #define _pcps_is_lwr( _d ) ( _pcps_is_dcf( _d ) || _pcps_is_msf( _d ) || _pcps_is_wwvb( _d ) ) @@ -1304,12 +1102,11 @@ typedef struct #define _pcps_bus_num( _d ) ( (_d)->cfg.bus_num ) #define _pcps_slot_num( _d ) ( (_d)->cfg.slot_num ) -#define _pcps_cfg_port_rsrc( _c, _n ) ( (_c)->port[_n] ) -#define _pcps_port_rsrc( _d, _n ) _pcps_cfg_port_rsrc( &(_d)->cfg, (_n) ) -#define _pcps_port_rsrc_unused( _d ) ( (_d)->base == 0 || (_d)->num == 0 ) +#define _pcps_cfg_short_port_rsrc( _c, _n ) ( (_c)->port[_n] ) +#define _pcps_short_port_rsrc( _d, _n ) _pcps_cfg_short_port_rsrc( &(_d)->cfg, (_n) ) -#define _pcps_cfg_port_base( _c, _n ) ( _pcps_cfg_port_rsrc( (_c), (_n) ).base ) -#define _pcps_port_base( _d, _n ) ( _pcps_port_rsrc( (_d), (_n) ).base ) +#define _pcps_cfg_short_port_base( _c, _n ) ( _pcps_cfg_short_port_rsrc( (_c), (_n) ).base ) +#define _pcps_short_port_base( _d, _n ) ( _pcps_short_port_rsrc( (_d), (_n) ).base ) #define _pcps_cfg_irq_num( _c ) ( (_c)->irq_num ) #define _pcps_irq_num( _d ) _pcps_cfg_irq_num( &(_d)->cfg ) @@ -1330,12 +1127,19 @@ typedef struct #define _pcps_clr_err_flags( _d, _msk ) ( _pcps_err_flags( _d ) &= ~(_msk) ) -// Query whether a special feature is supported: +#if _USE_DEV_MACROS + +/// Check whether a special feature is supported #define _pcps_has_feature( _d, _f ) ( ( (_d)->cfg.features & (_f) ) != 0 ) -// Query whether a special feature is supported according to RECEIVER_INFO: +/// Check whether a special feature is supported according to ::RECEIVER_INFO #define _pcps_has_ri_feature( _p_ri, _f ) ( ( (_p_ri)->features & (_f) ) != 0 ) +#define _ri_addr( _p ) &(_p)->xdev_features.receiver_info +#define _xfeat_addr( _p ) &(_p)->xdev_features.xfeature_buffer +#define _tlv_info_addr( _p ) &(_p)->xdev_features.tlv_info +#define _tlv_feat_buffp( _p ) &(_p)->xdev_features.tlv_info.supp_tlv_feat + #define _pcps_can_set_time( _d ) _pcps_has_feature( (_d), PCPS_CAN_SET_TIME ) #define _pcps_has_serial( _d ) _pcps_has_feature( (_d), PCPS_HAS_SERIAL ) @@ -1441,6 +1245,14 @@ typedef struct #define _pcps_has_stat_info_svs( _d ) _pcps_is_gps( _d ) +#define _pcps_has_ri_gpio( _p_ri ) _pcps_has_ri_feature( (_p_ri), GPS_HAS_GPIO ) + +// We only report that XMR is supported if all required features are supported. +#define _pcps_has_ri_xmr( _p_ri ) ( _pcps_has_ri_feature( (_p_ri), GPS_HAS_XMULTI_REF ) && \ + _pcps_has_ri_feature( (_p_ri), GPS_HAS_XMRS_MULT_INSTC ) ) +//### 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 @@ -1449,7 +1261,7 @@ typedef struct // signal even if the TFOM code reports the IRIG generator is not synchronized. // The intended behaviour is that the IRIG receiver card changes its status // to "freewheeling" in this case, unless it has been configured to ignore -// the TFOM code of the incoming IRIG signal (see the IFLAGS_DISABLE_TFOM flag +// the TFOM code of the incoming IRIG signal (see the ::IFLAGS_DISABLE_TFOM flag // defined in gpsdefs.h). // The macro below can be used to check based on the device info if a specific @@ -1463,28 +1275,29 @@ typedef struct // 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 efeect is that in this case a card is not accessible +// 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. +// 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. // 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:: #define _pcps_pci_cfg_err( _d ) \ - ( _pcps_is_pci( _d ) && ( _pcps_port_base( _d, 1 ) == _pcps_port_base( _d, 0 ) ) ) + ( _pcps_is_pci( _d ) && _pcps_short_port_base( _d, 0 ) && \ + ( _pcps_short_port_base( _d, 1 ) == _pcps_short_port_base( _d, 0 ) ) ) -// There are some versions of GPS PCI firmware which may occasionally return -// a HR time stamp which is wrong by 20 milliseconds, if the HR time is read -// right after some GPS data. As a workaround for that bug an application -// must wait at least 1.5 ms and then just read the PCPS_TIME structure +// There are some old firmware versions of GPS PCI cards which may occasionally +// return a HR time stamp which is wrong by 20 milliseconds, if the HR time is +// read right after some GPS data. As a workaround for that bug an application +// must wait at least 1.5 ms and then just read the PCPS_TIME structure // in order to re-initialize the software interface state. -// This has been fixed in more recent versions of the affected firmware, -// but this macro can be used to let an application determine whether it -// must account for this bug with a given card and firmware version. -#define _must_do_fw_workaround_20ms( _d ) \ +// This has been fixed in more recent versions of the affected firmware. +// This macro can be used to let an application determine whether it has to +// account for this bug with a given card and firmware version. +#define _pcps_fw_has_20ms_bug( _d ) \ ( \ ( _pcps_type_num( _d ) == PCPS_TYPE_GPS168PCI && _pcps_fw_rev_num( _d ) < 0x0102 ) || \ ( _pcps_type_num( _d ) == PCPS_TYPE_GPS167PCI && _pcps_fw_rev_num( _d ) < 0x0420 ) \ @@ -1493,13 +1306,33 @@ typedef struct /** - The structure is used to return info - on the device driver.*/ + * @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 + N_DEV_FEAT_TYPES +}; + + + +/** + * @brief Device driver information + * + * Used to pass info on the device driver to + * a user space application. + */ typedef struct { - uint16_t ver_num; /**< the device driver's version number */ - uint16_t n_devs; /**< the number of radio clocks handled by the driver */ - PCPS_ID_STR id_str; /**< the device driver's ID string */ + uint16_t ver_num; ///< the device driver's version number + uint16_t n_devs; ///< the number of devices handled by the driver + PCPS_ID_STR id_str; ///< the device driver's ID string + } PCPS_DRVR_INFO; @@ -1513,98 +1346,124 @@ typedef struct /** - The structure is used to read the current time from - a device, combined with an associated PC cycle counter value - to compensate program execution time. - */ + * @brief Time read from a device plus associated system cycles count + * + * Contains current time from a device, plus an associated PC + * cycles counter value useful to compensate execution time. + */ typedef struct { MBG_PC_CYCLES cycles; PCPS_TIME t; + } PCPS_TIME_CYCLES; /** - The structure is used to read a high resolution UTC time stamp - plus associated PC cycles counter value to compensate the latency. - */ + * @brief High resolution time stamp plus associated system cycles count + * + * Contains current high resolution UTC time stamp from a device, plus + * an associated PC cycles counter value useful to compensate execution time. + */ typedef struct { MBG_PC_CYCLES cycles; - PCPS_TIME_STAMP tstamp; /**< High resolution time stamp (UTC) */ + PCPS_TIME_STAMP tstamp; ///< High resolution time stamp (%UTC) + } PCPS_TIME_STAMP_CYCLES; #define _mbg_swab_pcps_time_stamp_cycles( _p ) \ +do \ { \ _mbg_swab_mbg_pc_cycles( &(_p)->cycles ); \ _mbg_swab_pcps_time_stamp( &(_p)->tstamp ); \ -} +} while ( 0 ) /** - The structure is used to read the current high resolution time - from a device, combined with an associated PC cycle counter value - to compensate program execution time. - */ + * @brief High resolution time plus associated system cycles count + * + * Contains current high resolution %UTC time from a device, including + * local time offset and status, plus an associated PC cycles counter value + * useful to compensate execution time. + */ typedef struct { MBG_PC_CYCLES cycles; PCPS_HR_TIME t; + } PCPS_HR_TIME_CYCLES; #define _mbg_swab_pcps_hr_time_cycles( _p ) \ +do \ { \ _mbg_swab_mbg_pc_cycles( &(_p)->cycles ); \ _mbg_swab_pcps_hr_time( &(_p)->t ); \ -} +} while ( 0 ) /** - The structure below can be used to let the kernel driver read - the current system time plus the associated HR time from a plugin card - as close as possibly, and return the results to a user space application - which can then compute the time difference and latencies. - This structure also contains the card's status information (e.g. sync status). - */ + * @brief High resolution device time, system time, and associated cycles counts + * + * Used to let the kernel driver read the current system time plus the associated + * high resolution time from a bus-level device as close as possible, and return + * the results to the caller which can then compute the time difference, taking + * into account the latencies determined from the cycles counts. + * + * This structure also contains the card's status information (e.g. sync status). + */ typedef struct { - PCPS_HR_TIME_CYCLES ref_hr_time_cycles; /**< HR time read from the card, plus cycles */ - MBG_SYS_TIME_CYCLES sys_time_cycles; /**< system timestamp plus associated cycles */ + PCPS_HR_TIME_CYCLES ref_hr_time_cycles; ///< HR time read from the card, plus cycles + MBG_SYS_TIME_CYCLES sys_time_cycles; ///< system time stamp plus associated cycles + } MBG_TIME_INFO_HRT; #define _mbg_swab_mbg_time_info_hrt( _p ) \ +do \ { \ _mbg_swab_pcps_hr_time_cycles( &(_p)->ref_hr_time_cycles ); \ _mbg_swab_mbg_sys_time_cycles( &(_p)->sys_time_cycles ); \ -} +} while ( 0 ) /** - The structure below can be used to let the kernel driver read - the current system time plus an associated HR timestamp from a plugin card - as close as possibly, and return the results to a user space application - which can then compute the time difference and latencies. - Since the card's time stamp is usually taken using the fast memory mapped - access this structure does *not* contain the card's status information - (e.g. sync status). - */ + * @brief High resolution device time stamp, system time, and associated cycles counts + * + * Used to let the kernel driver read the current system time plus the associated + * high resolution time stamp from a bus-level device as close as possible, and return + * the results to the caller which can then compute the time difference, taking + * into account the latencies determined from the cycles counts. + * + * Since the card's time stamp is taken from the fast memory mapped registers + * this structure does *not* contain the card's status information (e.g. sync status). + */ typedef struct { - PCPS_TIME_STAMP_CYCLES ref_tstamp_cycles; /**< HR timestamp from the card, plus cycles */ - MBG_SYS_TIME_CYCLES sys_time_cycles; /**< system timestamp plus associated cycles */ + PCPS_TIME_STAMP_CYCLES ref_tstamp_cycles; ///< HR timestamp from the card, plus cycles + MBG_SYS_TIME_CYCLES sys_time_cycles; ///< system timestamp plus associated cycles + } MBG_TIME_INFO_TSTAMP; #define _mbg_swab_mbg_time_info_tstamp( _p ) \ +do \ { \ _mbg_swab_pcps_time_stamp_cycles( &(_p)->ref_tstamp_cycles ); \ _mbg_swab_mbg_sys_time_cycles( &(_p)->sys_time_cycles ); \ -} +} while ( 0 ) + +/** + * @defgroup group_irq_stat_info IRQ status information + * + * @anchor PCPS_IRQ_STAT_INFO_DEFS + * + * @{ */ typedef uint32_t PCPS_IRQ_STAT_INFO; @@ -1615,78 +1474,26 @@ typedef uint32_t PCPS_IRQ_STAT_INFO; #define PCPS_IRQ_STATE_DANGER ( PCPS_IRQ_STAT_ENABLED | PCPS_IRQ_STAT_UNSAFE ) +/** @} defgroup group_irq_stat_info */ + + + +#define PCPS_FW_STR_FMT "%X.%02X" + #define _pcps_fw_rev_num_major( _v ) \ - ( ( (_v) >> 8 ) & 0xFF ) + ( (_v) >> 8 ) #define _pcps_fw_rev_num_minor( _v ) \ ( (_v) & 0xFF ) + #if defined( _USING_BYTE_ALIGNMENT ) #pragma pack() // set default alignment #undef _USING_BYTE_ALIGNMENT #endif -// We must use native alignment here! - -// The structure below is used by the IOCTL_PCPS_GENERIC_... calls. - -#if defined( MBG_TGT_LINUX ) - #if defined( MBG_ARCH_ARM ) || defined( MBG_ARCH_SPARC ) - #define USE_IOCTL_GENERIC_REQ 0 - #endif -#endif - -#if defined( MBG_TGT_WIN32 ) - // required for 32bit/64 bit compatibility - #define USE_IOCTL_GENERIC_REQ 0 -#endif - -#if !defined( USE_IOCTL_GENERIC_REQ ) - #define USE_IOCTL_GENERIC_REQ 1 -#endif - - -#if USE_IOCTL_GENERIC_REQ - -// This does not yet work properly under Linux/Sparc where the kernel may be 64 bit -// while user space is 32 bit, which leads to different sizes for pointers and size_t. - -typedef struct -{ - ulong info; - const void *in_p; - size_t in_sz; - void *out_p; - size_t out_sz; - -} IOCTL_GENERIC_REQ; - -#define _MBG_IOG( _t, _n, _s ) _MBG_IOW( _t, _n, _s ) - -#else - -// The structure below is used by the IOCTL_PCPS_GENERIC_... calls. -typedef struct -{ - uint32_t info; - uint32_t data_size_in; - uint32_t data_size_out; -} IOCTL_GENERIC_CTL; - -typedef struct -{ - IOCTL_GENERIC_CTL ctl; - uint8_t data[1]; -} IOCTL_GENERIC_BUFFER; - -#define _MBG_IOG( _t, _n, _s ) _MBG_IO( _t, _n ) - -#endif - - - #if !defined( MBG_TGT_KERNEL ) static __mbg_inline @@ -1703,6 +1510,30 @@ void setup_hr_time_cycles_from_timestamp_cycles( PCPS_HR_TIME_CYCLES *p_ht_c, #endif + +/** + * @brief A string buffer for a unique device ID + * + * The unique ID is made up of the device model name + * and its serial number, i.e. [model_name]_[serial_number] + * E.g.: "GPS170PCI_028210040670" + * + * @see ::snprint_dev_name + * @see ::MBG_DEV_NAME_FMT + */ +typedef char MBG_DEV_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; + + + +/** + * @brief A string format specifier for ::MBG_DEV_NAME + * + * @see ::snprint_dev_name + * @see ::MBG_DEV_NAME_FMT + */ +#define MBG_DEV_NAME_FMT "%s_%s" + + /* End of header body */ #undef _ext diff --git a/mbglib/common/pcpsiobf.h b/mbglib/common/pcpsiobf.h new file mode 100644 index 0000000..e0af290 --- /dev/null +++ b/mbglib/common/pcpsiobf.h @@ -0,0 +1,167 @@ + +/************************************************************************** + * + * $Id: pcpsiobf.h 1.2 2018/01/18 14:52:52Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions an I/O buffer that can be used in kernel space + * and user space, on targets that support IOCTL as well as + * on targets that don't. + * + * ----------------------------------------------------------------------- + * $Log: pcpsiobf.h $ + * Revision 1.2 2018/01/18 14:52:52Z martin + * Fix for C++ builds. + * Revision 1.1 2018/01/15 10:31:26Z martin + * Initial revision with structures moved from mbgioctl.h here. + * + **************************************************************************/ + +#ifndef _PCPSIOBF_H +#define _PCPSIOBF_H + +#include <pcpsdev.h> +#include <cfg_hlp.h> +#include <mbggeo.h> + + +/* Start of header body */ + +// We must *not* use byte-alignment here. + + +#ifdef __cplusplus +extern "C" { +#endif + + +/** + * @brief A wrapper struct for the ::LLA array type + * + * Simplifies usage of macros which expect ponters to structures + * rather than the address of an array. + * + * @see ::LLA + */ +typedef struct +{ + LLA lla; +} LLAs; + + + +/** + * @brief A wrapper struct for the ::XYZ array type. + * + * Simplifies usage of macros which expect ponters to structures + * rather than the address of an array. + * + * @see ::XYZ + */ +typedef struct +{ + XYZ xyz; +} XYZs; + + + +/** + * @brief An I/O buffer for bus level devices + * + * Can be used in kernel space and user space, on targets that + * support IOCTL calls as well as on targets that don't. + */ +typedef union +{ + PCPS_STATUS_PORT pcps_status_port; + PCPS_ID_STR fw_id; + PCPS_SN_STR sernum; + PCPS_TIME pcps_time; + PCPS_STIME pcps_stime; + PCPS_HR_TIME pcps_hr_time; + PCPS_TIME_STAMP pcps_time_stamp; + PCPS_SERIAL pcps_serial; + PCPS_TZCODE pcps_tzcode; + PCPS_TZDL pcps_tzdl; + MBG_REF_OFFS mbg_ref_offs; + MBG_OPT_INFO mbg_opt_info; + MBG_OPT_SETTINGS mbg_opt_settings; + IRIG_INFO irig_info; + IRIG_SETTINGS irig_settings; + PCPS_UCAP_ENTRIES pcps_ucap_entries; + TZDL tzdl; + SW_REV sw_rev; + BVAR_STAT bvar_stat; + TTM ttm; + PORT_PARM port_parm; + ANT_INFO ant_info; + ENABLE_FLAGS enable_flags; + STAT_INFO stat_info; + RECEIVER_INFO receiver_info; + GPS_CMD gps_cmd; + IDENT ident; + POS pos; + XYZs xyzs; + LLAs llas; + ANT_CABLE_LEN ant_cable_len; + PORT_SETTINGS_IDX port_settings_idx; + SYNTH synth; + SYNTH_STATE synth_state; + ALL_POUT_INFO_IDX all_pout_info_idx; + POUT_SETTINGS_IDX pout_settings_idx; + ALL_STR_TYPE_INFO_IDX all_str_type_info_idx; + ALL_PORT_INFO_IDX all_port_info_idx; + ALL_PTP_UC_MASTER_INFO_IDX all_ptp_uc_master_info_idx; + MBG_TIME_SCALE_INFO mbg_time_scale_info; + MBG_TIME_SCALE_SETTINGS mbg_time_scale_settings; + UTC utc; + MBG_IRIG_CTRL_BITS mbg_irig_ctrl_bits; + LAN_IF_INFO lan_if_info; + IP4_SETTINGS ip4_settings; + PTP_STATE ptp_state; + PTP_CFG_INFO ptp_cfg_info; + PTP_CFG_SETTINGS ptp_cfg_settings; + PCPS_IRIG_TIME pcps_irig_time; + MBG_RAW_IRIG_DATA mbg_raw_irig_data; + PTP_UC_MASTER_CFG_LIMITS ptp_uc_master_cfg_limits; + PTP_UC_MASTER_SETTINGS_IDX ptp_uc_master_settings_idx; + PCPS_TIME_CYCLES pcps_time_cycles; + PCPS_HR_TIME_CYCLES pcps_hr_time_cycles; + MBG_DBG_PORT mbg_dbg_port; + MBG_DBG_DATA mbg_dbg_data; + MBG_PC_CYCLES_FREQUENCY mbg_pc_cycles_frequency; + MBG_TIME_INFO_HRT mbg_time_info_hrt; + MBG_TIME_INFO_TSTAMP mbg_time_info_tstamp; + CORR_INFO corr_info; + TR_DISTANCE tr_distance; + MBG_DEBUG_STATUS debug_status; + MBG_NUM_EVT_LOG_ENTRIES num_evt_log_entries; + MBG_EVT_LOG_ENTRY evt_log_entry; + MBG_GNSS_MODE_SETTINGS gnss_mode_settings; + MBG_GNSS_MODE_INFO gnss_mode_info; + ALL_GNSS_SAT_INFO_IDX all_gnss_sat_info_idx; + MBG_GPIO_CFG_LIMITS mbg_gpio_cfg_limits; + ALL_GPIO_INFO_IDX all_gpio_info_idx; + ALL_GPIO_STATUS_IDX all_gpio_status_idx; + MBG_GPIO_SETTINGS_IDX mbg_gpio_settings_idx; + XMULTI_REF_INSTANCES xmulti_ref_instances; + ALL_XMULTI_REF_STATUS_IDX all_xmulti_ref_status_idx; + ALL_XMULTI_REF_INFO_IDX all_xmulti_ref_info_idx; + XMULTI_REF_SETTINGS_IDX xmulti_ref_settings_idx; + XMR_HOLDOVER_STATUS xmr_holdover_status; + +} PCPS_IO_BUFFER; + + +#ifdef __cplusplus +} +#endif + + +/* End of header body */ + +#undef _ext + +#endif /* _PCPSIOBF_H */ diff --git a/mbglib/common/pcpslstr.c b/mbglib/common/pcpslstr.c index 615b716..f7fab0d 100644 --- a/mbglib/common/pcpslstr.c +++ b/mbglib/common/pcpslstr.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpslstr.c 1.23 2012/10/15 13:09:35Z martin REL_M $ + * $Id: pcpslstr.c 1.27 2018/12/11 16:02:28Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,6 +11,16 @@ * * ----------------------------------------------------------------------- * $Log: pcpslstr.c $ + * Revision 1.27 2018/12/11 16:02:28Z 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. + * New function pcps_str_tm_gps_date_time(). + * Revision 1.25 2017/07/05 07:43:53 martin + * Use safe string functions from str_util.c. + * Started to add doxygen comments. + * Revision 1.24 2014/03/13 14:32:27 martin + * Fixed compiler warning. * Revision 1.23 2012/10/15 13:09:35Z martin * Added function sprint_utc_offs(). * Cleaned up get_tz_name(). @@ -38,7 +48,7 @@ * Revision 1.15 2007/07/20 10:55:27Z martin * Some modifications to avoid compiler warnings. * Revision 1.14 2007/03/30 13:23:42 martin - * In pcps_status_strs() handle case where time has been + * In pcps_status_strs() handle case where time has been * set manually. * Revision 1.13 2007/03/29 12:58:18Z martin * Moved some definitions to the header file to make them public. @@ -84,6 +94,7 @@ #include <pcpsutil.h> #include <mbgtime.h> +#include <timeutil.h> #include <ctry.h> #include <stdio.h> @@ -106,61 +117,50 @@ typedef struct } CLSTR_STATUS; -static const char *tz_name_utc = TZ_NAME_UTC; +static const char tz_name_utc[] = TZ_NAME_UTC; static CLSTR str_dst = { "DST", "Sommerzeit" }; /*HDR*/ +/** + * @brief Return a language dependend string for "invalid" + * + * @return A language dependend string for "invalid" + */ const char *inv_str( void ) { static CLSTR s = { "** invalid **", "** ung" LCUE "ltig **" }; return _lstr( s ); -} /* inv_str */ - - - -/*HDR*/ -int sprint_utc_offs( char *s, const char *info, long utc_offs ) -{ - int n = 0; - - // utc_offs is in [s] - char utc_offs_sign = ( utc_offs < 0 ) ? '-' : '+'; - ulong abs_utc_offs = labs( utc_offs ); - ulong utc_offs_hours = abs_utc_offs / SECS_PER_HOUR; - ulong tmp = abs_utc_offs % SECS_PER_HOUR; - ulong utc_offs_mins = tmp / MINS_PER_HOUR; - ulong utc_offs_secs = tmp % MINS_PER_HOUR; - - if ( info ) - n += sprintf( &s[n], "%s", info ); - - n += sprintf( &s[n], "%c%lu", utc_offs_sign, utc_offs_hours ); - - if ( utc_offs_mins || utc_offs_secs ) - n += sprintf( &s[n], ":%02lu", utc_offs_mins ); - - if ( utc_offs_secs ) - n += sprintf( &s[n], ":%02lu", utc_offs_secs ); - - n += sprintf( &s[n], "h" ); - - return n; - -} // sprint_utc_offs +} // inv_str static /*HDR*/ +/** + * @brief Return a static string with the name of the timezone, depending on the UTC offset + * + * @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 + * + * @see ::pcps_tz_name + * @see ::pcps_tz_name_from_hr_time + * @see ::pcps_tz_name_hr_status + * @see ::pcps_tz_name_from_status + * @see ::PCPS_TZ_NAME_FLAGS + */ const char *get_tz_name( PCPS_TIME_STATUS_X pcps_status, long utc_offs, - ushort flags, int is_msf ) + ulong flags, int is_msf ) { static char ws[40]; const char *cp = NULL; - int n = 0; + size_t n = 0; if ( ( pcps_status & PCPS_UTC ) && ( utc_offs == 0 ) ) return tz_name_utc; // no offset, no DST @@ -195,7 +195,7 @@ const char *get_tz_name( PCPS_TIME_STATUS_X pcps_status, long utc_offs, } } - n = sprint_utc_offs( ws, tz_name_utc, utc_offs ); + n = snprint_utc_offs( ws, sizeof( ws ), tz_name_utc, utc_offs ); check_flags: if ( cp ) @@ -203,31 +203,46 @@ check_flags: if ( flags == 0 ) return cp; - strcpy( ws, cp ); + n = sn_cpy_str_safe( ws, sizeof( ws ), cp ); if ( flags & PCPS_TZ_NAME_FORCE_UTC_OFFS ) { - n = strlen( ws ); - n += sprintf( &ws[n], "%*c(", pcps_time_tz_dist, ' ' ); - n += sprint_utc_offs( &ws[n], tz_name_utc, utc_offs ); - sprintf( &ws[n], ")" ); + n += snprintf_safe( &ws[n], sizeof( ws ) - n, "%*c(", pcps_time_tz_dist, ' ' ); + n += snprint_utc_offs( &ws[n], sizeof( ws ) - n, tz_name_utc, utc_offs ); + n += sn_cpy_char_safe( &ws[n], sizeof( ws ) - n, ')' ); } } if ( flags & PCPS_TZ_NAME_APP_DST ) { if ( pcps_status & PCPS_DL_ENB ) - sprintf( _eos( ws ), ",%*c%s", pcps_time_tz_dist, - ' ', _lstr( str_dst ) ); + snprintf_safe( &ws[n], sizeof( ws ) - n, ",%*c%s", pcps_time_tz_dist, + ' ', _lstr( str_dst ) ); } return ws; -} + +} // get_tz_name /*HDR*/ -const char *pcps_tz_name( const PCPS_TIME *t, ushort flags, int is_msf ) +/** + * @brief Return a static time zone string depending on the UTC offset from a ::PCPS_TIME structure + * + * @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 + * + * @return Pointer to a static string which has been set up + * + * @see ::pcps_tz_name_from_hr_time + * @see ::pcps_tz_name_hr_status + * @see ::pcps_tz_name_from_status + * @see ::get_tz_name + * @see ::PCPS_TZ_NAME_FLAGS + */ +const char *pcps_tz_name( const PCPS_TIME *t, ulong flags, int is_msf ) { return get_tz_name( t->status, t->offs_utc * SECS_PER_HOUR, flags, is_msf ); @@ -236,6 +251,21 @@ const char *pcps_tz_name( const PCPS_TIME *t, ushort 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 + * + * @return Pointer to a static string which has been set up + * + * @see ::pcps_tz_name + * @see ::pcps_tz_name_hr_status + * @see ::pcps_tz_name_from_status + * @see ::get_tz_name + * @see ::PCPS_TZ_NAME_FLAGS + */ const char *pcps_tz_name_from_hr_time( const PCPS_HR_TIME *hrt, ushort flags, int is_msf ) { return get_tz_name( hrt->status, hrt->utc_offs, flags, is_msf ); @@ -244,22 +274,36 @@ const char *pcps_tz_name_from_hr_time( const PCPS_HR_TIME *hrt, ushort flags, in -// The function below 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 clocks. - /*HDR*/ +/** + * @brief Return a static time zone string depending on the UTC offset from a ::PCPS_HR_TIME structure + * + * 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. + * + * @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 + * + * @return Pointer to a static string which has been set up + * + * @see ::pcps_tz_name + * @see ::pcps_tz_name_from_hr_time + * @see ::pcps_tz_name_from_status + * @see ::get_tz_name + * @see ::PCPS_TZ_NAME_FLAGS + */ const char *pcps_tz_name_hr_status( const PCPS_HR_TIME *t, ushort flags, int is_msf ) { static char ws[40]; if ( t->status & PCPS_SCALE_GPS ) - strcpy( ws, "GPS" ); + strncpy_safe( ws, "GPS", sizeof( ws ) ); else if ( t->status & PCPS_SCALE_TAI ) - strcpy( ws, "TAI" ); + strncpy_safe( ws, "TAI", sizeof( ws ) ); else - return pcps_tz_name_from_hr_time( t, flags, is_msf); + return pcps_tz_name_from_hr_time( t, flags, is_msf ); return ws; @@ -267,13 +311,25 @@ const char *pcps_tz_name_hr_status( const PCPS_HR_TIME *t, ushort flags, int is_ -// The function below 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. This is the case, for example, -// if the Meinberg standard time string is decoded. - /*HDR*/ -const char *pcps_tz_name_from_status( ushort status ) +/** + * @brief Return a static time zone string depending on the UTC offset from a ::PCPS_HR_TIME structure + * + * 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. + * 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 + * + * @return Pointer to a static string which has been set up + * + * @see ::pcps_tz_name + * @see ::pcps_tz_name_from_hr_time + * @see ::pcps_tz_name_hr_status + * @see ::get_tz_name + * @see ::PCPS_TZ_NAME_FLAGS + */ +const char *pcps_tz_name_from_status( PCPS_TIME_STATUS_X status ) { if ( status & PCPS_UTC ) return tz_name_utc; @@ -285,33 +341,39 @@ const char *pcps_tz_name_from_status( ushort status ) /*HDR*/ -char *pcps_date_time_str( char *s, const PCPS_TIME *t, - ushort year_limit, const char *tz_str ) +char *pcps_date_time_str( char *s, size_t max_len, const PCPS_TIME *t, + int year_limit, const char *tz_str ) { if ( !_pcps_time_is_read( t ) ) - strcpy( s, str_not_avail ); + strncpy_safe( s, str_not_avail, max_len ); else { - char *cp; + size_t n; int i; - _pcps_sprint_wday( s, t, language ); - cp = _eos( s ); - *cp++ = ','; + _pcps_snprint_wday( s, max_len, t, language ); + n = strlen( s ); + + n += sn_cpy_char_safe( &s[n], max_len - n, ',' ); + for ( i = 0; i < pcps_wday_date_dist; i++ ) - *cp++ = ' '; - _pcps_sprint_date( cp, t, year_limit ); - cp = _eos( s ); + n += sn_cpy_char_safe( &s[n], max_len - n, ' ' ); + + _pcps_snprint_date( &s[n], max_len - n, t, year_limit ); + n = strlen( s ); + for ( i = 0; i < pcps_date_time_dist; i++ ) - *cp++ = ' '; - _pcps_sprint_time_long( cp, t ); + n += sn_cpy_char_safe( &s[n], max_len - n, ' ' ); + + _pcps_snprint_time_long( &s[n], max_len - n, t ); + n = strlen( s ); if ( tz_str ) { - cp = _eos( s ); for ( i = 0; i < pcps_time_tz_dist; i++ ) - *cp++ = ' '; - strcpy( cp, tz_str ); + n += sn_cpy_char_safe( &s[n], max_len - n, ' ' ); + + n += sn_cpy_str_safe( &s[n], max_len - n, tz_str ); } } @@ -321,37 +383,49 @@ char *pcps_date_time_str( char *s, const PCPS_TIME *t, +/*HDR*/ +int pcps_str_tm_gps_date_time( char *s, size_t max_len, const TM_GPS *t ) +{ + size_t n; + int i; + + n = snprint_ctry_wday( s, max_len, t->wday, language ); + n += sn_cpy_str_safe( &s[n], max_len - n, ", " ); + + n += snprintf_safe( &s[n], max_len - n, "%04i-%02i-%02i", + t->year, t->month, t->mday ); + + for ( i = 0; i < pcps_wday_date_dist; i++ ) + n += sn_cpy_char_safe( &s[n], max_len - n, ' ' ); + + n += snprintf_safe( &s[n], max_len - n, "%02i:%02i:%02i.%07i", + t->hour, t->min, t->sec, t->frac ); + + return _int_from_size_t ( n ); + +} // pcps_str_tm_gps_date_time + + + #if MBG_TGT_HAS_WCHAR_T && defined( MBG_TGT_WIN32 ) /*HDR*/ -wchar_t *pcps_date_time_wstr( wchar_t *ws, const PCPS_TIME *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 ) { - char stemp[80]; - wchar_t wstemp[80]; + //#error Remove this error directive and check if the function works properly. + char tmp_str[80]; - if ( !_pcps_time_is_read( t ) ) - mbstowcs( ws, str_not_avail, 32 ); - else - { - char *cp; - int i; + pcps_date_time_str( tmp_str, sizeof( tmp_str ), t, year_limit, NULL ); - _pcps_sprint_wday( stemp, t, language ); - cp = _eos( stemp ); - *cp++ = ','; - for ( i = 0; i < pcps_wday_date_dist; i++ ) - *cp++ = ' '; - _pcps_sprint_date( cp, t, year_limit ); - cp = _eos( stemp ); - for ( i = 0; i < pcps_date_time_dist; i++ ) - *cp++ = ' '; - _pcps_sprint_time_long( cp, t ); + mbstowcs( ws, tmp_str, count ); + ws[count - 1] = L'0'; // force terminating 0 - mbstowcs( wstemp, stemp, sizeof( wstemp ) ); - - if ( tz_str ) - _snwprintf( ws, sizeof( wstemp ) + 32, L"%s %s", wstemp, tz_str ); + if ( tz_str ) + { + size_t n = wcslen( ws ); + _snwprintf( &ws[n], count - n, L" %s", tz_str ); + ws[count - 1] = L'0'; // force terminating 0 } return ws; @@ -445,16 +519,16 @@ void pcps_status_strs( ushort status, int status_is_read, /*HDR*/ -char *pcps_port_str( char *s, const PCPS_DEV *pdev ) +char *pcps_port_str( char *s, size_t max_len, const PCPS_DEV *pdev ) { - ushort port = _pcps_port_base( pdev, 0 ); + ushort port = _pcps_short_port_base( pdev, 0 ); - ushort n = sprintf( s, "%3Xh", port ); + size_t n = snprintf_safe( s, max_len, "%3Xh", port ); - port = _pcps_port_base( pdev, 1 ); + port = _pcps_short_port_base( pdev, 1 ); if ( port ) - sprintf( &s[n], ", %3Xh", port ); + snprintf_safe( &s[n], max_len - n, ", %3Xh", port ); return s; @@ -475,25 +549,26 @@ const char *pcps_tzcode_str( PCPS_TZCODE tzcode ) /*HDR*/ -char *pcps_serial_str( char *s, int i, const RECEIVER_PORT_CFG *p, +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 ) { const PORT_SETTINGS *p_ps = &p->pii[i].port_info.port_settings; const STR_TYPE_INFO *p_sti = &p->stii[p_ps->str_type].str_type_info; + size_t n; - sprintf( s, "%lu,%s", (ulong) p_ps->parm.baud_rate, p_ps->parm.framing ); + n = snprintf_safe( s, max_len, "%lu,%s", (ulong) p_ps->parm.baud_rate, p_ps->parm.framing ); if ( short_strs ) - sprintf( _eos( s ), ",%s", short_mode_name[p_ps->mode] ); + n += snprintf_safe( &s[n], max_len - n, ",%s", short_mode_name[p_ps->mode] ); else { if ( p_ri->n_str_type > 1 ) - sprintf( _eos( s ), ", %s", p_sti->long_name ); + n += snprintf_safe( &s[n], max_len - n, ", %s", p_sti->long_name ); - sprintf( _eos( s ), ", %s", _lstr( mode_name[p_ps->mode] ) ); + n += snprintf_safe( &s[n], max_len - n, ", %s", _lstr( mode_name[p_ps->mode] ) ); } - return( s ); + return s; } // pcps_serial_str diff --git a/mbglib/common/pcpslstr.h b/mbglib/common/pcpslstr.h index 650799d..05f4e14 100644 --- a/mbglib/common/pcpslstr.h +++ b/mbglib/common/pcpslstr.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpslstr.h 1.28 2012/10/15 13:01:23Z martin REL_M $ + * $Id: pcpslstr.h 1.32 2018/12/11 16:03:11Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,20 @@ * * ----------------------------------------------------------------------- * $Log: pcpslstr.h $ - * Revision 1.28 2012/10/15 13:01:23Z martin + * Revision 1.32 2018/12/11 16:03:11Z martin + * Updated function prototypes. + * Revision 1.31 2018/01/15 18:25:16Z martin + * Updated function prototypes. + * Revision 1.30 2017/07/05 17:37:03 martin + * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. + * Account for new modes for programmable pulse outputs. + * Started to add doxygen comments. + * Fixed typos, wording, and doxygen comments. + * Updated function prototypes. + * Revision 1.29 2012/11/20 10:47:29 martin + * Moved some code definitions for special chars + * to new header charcode.h. + * Revision 1.28 2012/10/15 13:01:23 martin * Include cfg_hlp.h. * Made all declarations extern C. * Added menu titles for PTP and PTP Unicast configuration. @@ -80,7 +93,7 @@ * Updated function prototypes. * Revision 1.6 2002/12/18 13:57:53 martin * Some definitions and variables made global. - * Added some new macros _pcps_sprint_vernum...() + * Added some new macros _pcps_sprint_vernum...() * and _pcps_sprint_dev_id(). * Revision 1.5 2002/02/19 10:01:36Z MARTIN * New initializers for string mode names. @@ -108,15 +121,13 @@ /* Other headers to be included */ -#include <mbg_tgt.h> +#include <str_util.h> +#include <charcode.h> #include <cfg_hlp.h> -#include <parmpcps.h> +#include <pcpsdev.h> #include <ctrydttm.h> #include <cnv_wday.h> -#if MBG_TGT_HAS_WCHAR_T - #include <wchar.h> -#endif #ifdef _PCPSLSTR #define _ext @@ -132,92 +143,53 @@ extern "C" { #endif -// upper case 'A' umlaut -#define ANSI_UC_A_UML '\xC4' // single char -#define ANSI_US_A_UML "\xC4" // string - -// upper case 'O' umlaut -#define ANSI_UC_O_UML '\xD6' // single char -#define ANSI_US_O_UML "\xD6" // string - -// upper case 'U' umlaut -#define ANSI_UC_U_UML '\xDC' // single char -#define ANSI_US_U_UML "\xDC" // string - -// lower case 'a' umlaut -#define ANSI_LC_A_UML '\xE4' // single char -#define ANSI_LS_A_UML "\xE4" // string - -// lower case 'o' umlaut -#define ANSI_LC_O_UML '\xF6' // single char -#define ANSI_LS_O_UML "\xF6" // string - -// lower case 'u' umlaut -#define ANSI_LC_U_UML '\xFC' // single char -#define ANSI_LS_U_UML "\xFC" // string - -// 'sz' umlaut -#define ANSI_LC_SZ_UML '\xDF' // single char -#define ANSI_LS_SZ_UML "\xDF" // string - -// degree character -#define ANSI_C_DEGREE '\xB0' // single char -#define ANSI_S_DEGREE "\xB0" // string - -// greek mu character -#define ANSI_C_MU '\xB5' //single char -#define ANSI_S_MU "\xB5" //string #if defined( MBG_TGT_WIN32 ) \ - || defined( MBG_TGT_UNIX ) \ + || defined( MBG_TGT_POSIX ) \ || defined( MBG_TGT_QNX ) + #define DEFAULT_PCPS_WDAY_DATE_DIST 1 #define DEFAULT_PCPS_DATE_TIME_DIST 2 #define DEFAULT_PCPS_TIME_TZ_DIST 1 - #define UCAE ANSI_US_A_UML - #define UCOE ANSI_US_O_UML - #define UCUE ANSI_US_U_UML - - #define LCAE ANSI_LS_A_UML - #define LCOE ANSI_LS_O_UML - #define LCUE ANSI_LS_U_UML - - #define LCSZ ANSI_LS_SZ_UML - #define DEG ANSI_S_DEGREE - #define MU ANSI_S_MU #else + #define DEFAULT_PCPS_WDAY_DATE_DIST 1 #define DEFAULT_PCPS_DATE_TIME_DIST 2 #define DEFAULT_PCPS_TIME_TZ_DIST 1 - #define UCAE "\x8E" - #define UCOE "\x99" - #define UCUE "\x9A" - - #define LCAE "\x84" - #define LCOE "\x94" - #define LCUE "\x81" - - #define LCSZ "\xE1" - #define DEG "\xF8" - #define MU "\xE6" #endif -// The flags defined below can be passed to pcps_tz_name() -// in order to control the generation of time zone names -enum +/** + * @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 }; -// bit masks corresponding to the flags above -#define PCPS_TZ_NAME_FORCE_UTC_OFFS ( 1UL << PCPS_TZ_NAME_BIT_FORCE_UTC_OFFS ) -#define PCPS_TZ_NAME_APP_DST ( 1UL << PCPS_TZ_NAME_BIT_APP_DST ) + +/** + * @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 + * + * @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 +}; + // The definitions below are used with pcps_get_status_strs(). @@ -472,7 +444,7 @@ typedef struct #define DEFAULT_TZCODE_HINT_CET_CEST \ { \ - "Central European Time or Summer Time, as broadcasted by DCF77", \ + "Central European Time or Summer Time, as broadcast by DCF77", \ "Mitteleurop" LCAE "ische Zeit oder Sommerzeit, wie von DCF77 gesendet" \ } @@ -484,7 +456,7 @@ typedef struct #define DEFAULT_TZCODE_HINT_GMT_BST \ { \ - "Greenwich Mean Time or British Summer Time, as broadcasted by MSF", \ + "Greenwich Mean Time or British Summer Time, as broadcast by MSF", \ "Westeurop" LCAE "ische Zeit oder britische Sommerzeit, wie von MSF gesendet" \ } @@ -805,13 +777,16 @@ typedef struct #define GER_POUT_NAME_DCF77 "DCF77-Zeitmarken" #define GER_POUT_NAME_POS_OK "Position OK" #define GER_POUT_NAME_TIME_SYNC "Zeit synchron" -#define GER_POUT_NAME_ALL_SYNC "alles synchron" +#define GER_POUT_NAME_ALL_SYNC "Alles synchron" #define GER_POUT_NAME_TIMECODE "DCLS-Zeitcode" -#define GER_POUT_NAME_TIMESTR "COM-Zeittelegramm" +#define GER_POUT_NAME_TIMESTR "Serielles Zeittelegramm" #define GER_POUT_NAME_10MHZ "Festfrequenz 10 MHz" #define GER_POUT_NAME_DCF77_M59 "DCF77-Zeitmarken mit 59. Impuls" -#define GER_POUT_NAME_SYNTH "Frequenz-Synthesizer" +#define GER_POUT_NAME_SYNTH "Synthesizer-Frequenz" #define GER_POUT_NAME_TIME_SLOTS "Zeitschlitze pro Minute" +#define GER_POUT_NAME_GPIO "GPIO-Signal" +#define GER_POUT_PTTI_PPS "PTTI 1 PPS" +#define GER_POUT_HAVEQUICK "HaveQuick" #define DEFAULT_GER_POUT_NAMES \ { \ @@ -831,7 +806,10 @@ typedef struct GER_POUT_NAME_10MHZ, \ GER_POUT_NAME_DCF77_M59, \ GER_POUT_NAME_SYNTH, \ - GER_POUT_NAME_TIME_SLOTS \ + GER_POUT_NAME_TIME_SLOTS, \ + GER_POUT_NAME_GPIO, \ + GER_POUT_PTTI_PPS, \ + GER_POUT_HAVEQUICK \ } /* @@ -855,6 +833,9 @@ typedef struct #define GER_POUT_HINT_DCF77_M59 "Zeitmarken wie DCF77, aber mit 500 ms Impuls in 59. Sekunde" #define GER_POUT_HINT_SYNTH "Durch programmierbaren Synthesizer erzeugte Frequenz" #define GER_POUT_HINT_TIME_SLOTS "Programmierbare Zeitslots, die in jeder Minute aktiviert werden" +#define GER_POUT_HINT_GPIO "Signal des spezifizierten GPIO-Ein- oder Ausgangs" +#define GER_POUT_HINT_PTTI_PPS "20 us-Impuls zum Sekundenbeginn" +#define GER_POUT_HINT_HAVEQUICK "Dupliziertes HaveQuick-Signal" #define DEFAULT_GER_POUT_HINTS \ { \ @@ -874,83 +855,79 @@ typedef struct GER_POUT_HINT_10MHZ, \ GER_POUT_HINT_DCF77_M59, \ GER_POUT_HINT_SYNTH, \ - GER_POUT_HINT_TIME_SLOTS \ + GER_POUT_HINT_TIME_SLOTS, \ + GER_POUT_HINT_GPIO, \ + GER_POUT_HINT_PTTI_PPS, \ + GER_POUT_HINT_HAVEQUICK \ } // some macros which generate proper function calls -#define _pcps_sprint_vernum_dec( _s, _v ) \ - sprintf( (_s), "v%u.%02u", \ - ( (unsigned) (_v) ) / 100, \ - ( (unsigned) (_v) ) % 100 ) +#define _pcps_snprint_vernum_dec( _s, _sz, _v ) \ + snprintf_safe( (_s), (_sz), "v%u.%02u", \ + ( (unsigned) (_v) ) / 100, \ + ( (unsigned) (_v) ) % 100 ) -#define _pcps_sprint_vernum_hex( _s, _v ) \ - sprintf( (_s), "v%X.%02X", \ - ( (unsigned) (_v) ) >> 8, \ +#define _pcps_snprint_vernum_hex( _s, _sz, _v ) \ + snprintf_safe( (_s), (_sz), "v%X.%02X", \ + ( (unsigned) (_v) ) >> 8, \ ( (unsigned) (_v) ) & 0xFF ) #if defined( MBG_TGT_WIN32 ) - #define _pcps_sprint_vernum _pcps_sprint_vernum_dec + #define _pcps_snprint_vernum _pcps_snprint_vernum_dec #else - #define _pcps_sprint_vernum _pcps_sprint_vernum_hex + #define _pcps_snprint_vernum _pcps_snprint_vernum_hex #endif -#define _pcps_sprint_dev_id( _s, _n ) \ - sprintf( (_s), "%04Xh", _n ) +#define _pcps_snprint_dev_id( _s, _sz, _n ) \ + snprintf_safe( (_s), (_sz), "%04Xh", _n ) -#define _pcps_sprint_wday( _s, _t, _l ) \ - sprint_ctry_wday( (_s), _wday_mon17_to_sun06( (_t)->wday ), (_l) ) +#define _pcps_snprint_wday( _s, _sz, _t, _l ) \ + snprint_ctry_wday( (_s), (_sz), _wday_mon17_to_sun06( (_t)->wday ), (_l) ) -#define _pcps_sprint_date( _s, _t, _yl ) \ - sprint_ctry_dt( (_s), (_t)->mday, (_t)->month, \ - pcps_exp_year( (_t)->year, (_yl) ) ) +#define _pcps_snprint_date( _s, _sz, _t, _yl ) \ + snprint_ctry_dt( (_s), (_sz), (_t)->mday, (_t)->month, \ + pcps_exp_year( (_t)->year, (_yl) ) ) -#define _pcps_sprint_time( _s, _t ) \ - sprint_ctry_tm( (_s), (_t)->hour, (_t)->min, (_t)->sec ) +#define _pcps_snprint_time( _s, _sz, _t ) \ + snprint_ctry_tm( (_s), (_sz), (_t)->hour, (_t)->min, (_t)->sec ) -#define _pcps_sprint_time_long( _s, _t ) \ - sprint_ctry_tm_long( (_s), (_t)->hour, (_t)->min, (_t)->sec, (_t)->sec100, 2 ) +#define _pcps_snprint_time_long( _s, _sz, _t ) \ + snprint_ctry_tm_long( (_s), (_sz), (_t)->hour, (_t)->min, (_t)->sec, (_t)->sec100, 2 ) -#define _cput_pcps_date( _t, _yl ) \ -{ \ - char s[80]; \ - _pcps_sprint_date( s, (_t), (_yl) ); \ - cputs( s ); \ +#define _cput_pcps_date( _t, _yl ) \ +{ \ + char s[80]; \ + _pcps_snprint_date( s, sizeof( s ), (_t), (_yl) ); \ + cputs( s ); \ } -#define _cput_pcps_time( _t ) \ -{ \ - char s[80]; \ - _pcps_sprint_time( s, (_t) ); \ - cputs( s ); \ +#define _cput_pcps_time( _t ) \ +{ \ + char s[80]; \ + _pcps_snprint_time( s, sizeof( s ), (_t) ); \ + cputs( s ); \ } -#define _cput_pcps_time_long( _t ) \ -{ \ - char s[80]; \ - _pcps_sprint_time_long( s, (_t) ); \ - cputs( s ); \ +#define _cput_pcps_time_long( _t ) \ +{ \ + char s[80]; \ + _pcps_snprint_time_long( s, sizeof( s ), (_t) ); \ + cputs( s ); \ } -#define _cput_pcps_date_and_time( _t, _yl, _tz ) \ -{ \ - char s[80]; \ - cputs( pcps_date_time_str( s, (_t), (_yl), (_tz) ) ); \ +#define _cput_pcps_date_and_time( _t, _yl, _tz ) \ +{ \ + char s[80]; \ + cputs( pcps_date_time_str( s, sizeof( s ), (_t), (_yl), (_tz) ) ); \ } -_ext const char *str_not_avail -#ifdef _DO_INIT - = "N/A" -#endif -; - - _ext CLSTR lstr_cet #ifdef _DO_INIT = { TZ_NAME_CET, TZ_NAME_MEZ } @@ -1024,18 +1001,93 @@ _ext const char *short_mode_name[N_STR_MODE] /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ + /** + * @brief Return a language dependend string for "invalid" + * + * @return A language dependend string for "invalid" + */ const char *inv_str( void ) ; - int sprint_utc_offs( char *s, const char *info, long utc_offs ) ; - const char *pcps_tz_name( const PCPS_TIME *t, ushort flags, int is_msf ) ; + + /** + * @brief Return a static time zone string depending on the UTC offset from a ::PCPS_TIME structure + * + * @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 + * + * @return Pointer to a static string which has been set up + * + * @see ::pcps_tz_name_from_hr_time + * @see ::pcps_tz_name_hr_status + * @see ::pcps_tz_name_from_status + * @see ::get_tz_name + * @see ::PCPS_TZ_NAME_FLAGS + */ + 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 + * + * @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 + * + * @see ::pcps_tz_name + * @see ::pcps_tz_name_hr_status + * @see ::pcps_tz_name_from_status + * @see ::get_tz_name + * @see ::PCPS_TZ_NAME_FLAGS + */ 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 + * + * 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. + * + * @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 + * + * @return Pointer to a static string which has been set up + * + * @see ::pcps_tz_name + * @see ::pcps_tz_name_from_hr_time + * @see ::pcps_tz_name_from_status + * @see ::get_tz_name + * @see ::PCPS_TZ_NAME_FLAGS + */ const char *pcps_tz_name_hr_status( const PCPS_HR_TIME *t, ushort flags, int is_msf ) ; - const char *pcps_tz_name_from_status( ushort status ) ; - char *pcps_date_time_str( char *s, const PCPS_TIME *t, ushort year_limit, const char *tz_str ) ; - wchar_t *pcps_date_time_wstr( wchar_t *ws, const PCPS_TIME *t, ushort year_limit, const wchar_t *tz_str ) ; + + /** + * @brief Return a static time zone string depending on the UTC offset from a ::PCPS_HR_TIME structure + * + * 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. + * 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 + * + * @return Pointer to a static string which has been set up + * + * @see ::pcps_tz_name + * @see ::pcps_tz_name_from_hr_time + * @see ::pcps_tz_name_hr_status + * @see ::get_tz_name + * @see ::PCPS_TZ_NAME_FLAGS + */ + const char *pcps_tz_name_from_status( PCPS_TIME_STATUS_X status ) ; + + 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 ) ; - char *pcps_port_str( char *s, const PCPS_DEV *pdev ) ; + 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, int i, const RECEIVER_PORT_CFG *p, const RECEIVER_INFO *p_ri, int short_strs ) ; + 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 ) ; /* ----- function prototypes end ----- */ diff --git a/mbglib/common/pcpsmktm.c b/mbglib/common/pcpsmktm.c index 90404a8..73e1376 100644 --- a/mbglib/common/pcpsmktm.c +++ b/mbglib/common/pcpsmktm.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsmktm.c 1.4 2006/12/14 15:27:49Z martin REL_M $ + * $Id: pcpsmktm.c 1.5 2017/07/05 08:05:11Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,11 @@ * * ----------------------------------------------------------------------- * $Log: pcpsmktm.c $ - * Revision 1.4 2006/12/14 15:27:49Z martin + * Revision 1.5 2017/07/05 08:05:11Z martin + * Let pcps_mktime() return a 'time_t' instead of 'long', and made + * the PCPS_TIME pointer parameter 'const'. + * Added doxygen comments. + * Revision 1.4 2006/12/14 15:27:49 martin * Include time.h. * Revision 1.3 2006/08/22 09:10:03 martin * Renamed function totalsec() to mbg_mktime() and moved it @@ -27,25 +31,40 @@ #include <mbgmktm.h> -#include <time.h> /*HDR*/ -long pcps_mktime( PCPS_TIME *tp ) +/** + * @brief Compute a linear time_t value from ::PCPS_TIME + * + * 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] tp A timestamp in ::PCPS_TIME format + * + * @return seconds since 1970-01-01 (Unix time_t format) or ((time_t) -1) if range overflow + */ +time_t pcps_mktime( const PCPS_TIME *tp ) { time_t secs; int year = tp->year; + // Expand 2 digit year number (year of the century) to 4 digits + // including the century. if ( year < 70 ) year += 100; + // Plausibility checks are made by mbg_mktime(). secs = mbg_mktime( year, tp->month - 1, tp->mday - 1, tp->hour, tp->min, tp->sec ); - if ( secs != -1 ) - secs -= tp->offs_utc * 3600; + // Convert to UTC if result is valid. + if ( secs != ( (time_t) -1 ) ) + secs -= tp->offs_utc * 3600UL; - return( secs ); + return secs; } // pcps_mktime diff --git a/mbglib/common/pcpsmktm.h b/mbglib/common/pcpsmktm.h index 086be75..bd5bbd3 100644 --- a/mbglib/common/pcpsmktm.h +++ b/mbglib/common/pcpsmktm.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsmktm.h 1.1 2001/02/02 15:31:07Z MARTIN REL_M $ + * $Id: pcpsmktm.h 1.2 2017/07/05 08:18:54Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: pcpsmktm.h $ - * Revision 1.1 2001/02/02 15:31:07Z MARTIN + * Revision 1.2 2017/07/05 08:18:54Z martin + * Cleaned up to conform to standard header file format. + * Updated function prototypes. + * Revision 1.1 2001/02/02 15:31:07 MARTIN * **************************************************************************/ @@ -22,9 +25,12 @@ #include <pcpsdefs.h> +#include <time.h> + #ifdef _PCPSMKTM #define _ext + #define _DO_INIT #else #define _ext extern #endif @@ -32,25 +38,31 @@ /* Start of header body */ -//_ext PCPS_TIME tx; - -/* End of header body */ - -#undef _ext - - -/* function prototypes: */ - #ifdef __cplusplus extern "C" { #endif + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ - long pcps_mktime( PCPS_TIME *tp ) ; + /** + * @brief Compute a linear time_t value from ::PCPS_TIME + * + * 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] tp A timestamp in ::PCPS_TIME format + * + * @return seconds since 1970-01-01 (Unix time_t format) or ((time_t) -1) if range overflow + */ + time_t pcps_mktime( const PCPS_TIME *tp ) ; + /* ----- function prototypes end ----- */ @@ -58,5 +70,9 @@ extern "C" { } #endif +/* End of header body */ + +#undef _ext +#undef _DO_INIT #endif /* _PCPSMKTM_H */ diff --git a/mbglib/common/pcpsutil.c b/mbglib/common/pcpsutil.c deleted file mode 100644 index 91109e0..0000000 --- a/mbglib/common/pcpsutil.c +++ /dev/null @@ -1,162 +0,0 @@ - -/************************************************************************** - * - * $Id: pcpsutil.c 1.14 2011/06/29 11:03:44Z martin REL_M $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Utility functions used with programs for Meinberg devices. - * - * ----------------------------------------------------------------------- - * $Log: pcpsutil.c $ - * Revision 1.14 2011/06/29 11:03:44Z martin - * Updated a comment. - * Revision 1.13 2009/03/09 13:39:45 martin - * Made pcps_exp_year() an inline function. - * Revision 1.12 2008/12/10 19:59:48 martin - * Made frac_sec_from_bin() an inline function. - * Revision 1.11 2008/11/25 10:00:25 martin - * Use new definitions of fraction conversion type and scale - * from pcpsdefs.h. - * Revision 1.10 2006/06/29 10:38:24Z martin - * New function pcps_time_is_valid(). - * Modified pcps_str_to_port(), doesn't add a 0 entry to the list anymore. - * Fixed a compiler warning related to type conversion. - * Revision 1.9 2005/01/14 10:14:31Z martin - * Changed type of ISA port addr to int. - * Revision 1.8 2004/11/09 14:29:27Z martin - * Rewrote functions using C99 fixed-size definitions. - * Revision 1.7 2003/04/17 10:08:59Z martin - * Added some type casts to fix compiler warnings. - * Revision 1.6 2001/11/28 14:39:16Z MARTIN - * In frac_sec_from_bin(), define the divisor as floating point - * constant to avoid a domain errors on 16 bit systems. - * Revision 1.5 2001/09/17 07:28:01 MARTIN - * New function frac_sec_from_bin() to convert - * PCPS_HR_TIME fractions. - * Revision 1.4 2001/03/01 14:01:09 MARTIN - * Modified parameters for pcps_setup_isa_ports(). - * Revision 1.3 2000/08/31 14:05:30 MARTIN - * Replaced pcps_str_to_port() by pcps_setup_isa_ports(). - * Revision 1.2 2000/07/21 13:42:54 MARTIN - * Initial revision - * - **************************************************************************/ - -#define _PCPSUTIL - #include <pcpsutil.h> -#undef _PCPSUTIL - -#include <stdlib.h> - - -/*-------------------------------------------------------------- - * Name: pcps_time_is_valid() - * - * 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*/ -int pcps_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_time_is_valid */ - - - -/*-------------------------------------------------------------- - * 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*/ -void pcps_setup_isa_ports( char *s, - int *port_vals, - int n_vals ) -{ - ushort i; - - - for ( i = 0; i < n_vals; i++ ) - { - if ( *s == 0 ) - break; - - *port_vals++ = (uint16_t) strtoul( s, &s, 16 ); - - if ( *s == ',' ) - s++; - } - -} // pcps_setup_isa_ports - - - -/*-------------------------------------------------------------- - * 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*/ -void pcps_unpack_serial( PCPS_SER_PACK *p ) -{ - uint8_t pack = p->pack; - - p->baud = (uint8_t) ( pack & BITMASK( PCPS_BD_BITS ) ); - p->frame = (uint8_t) ( ( pack >> PCPS_FR_SHIFT ) & BITMASK( PCPS_FR_BITS ) ); - p->mode = (uint8_t) ( ( pack >> PCPS_MOD_SHIFT ) & BITMASK( PCPS_MOD_BITS ) ); - -} // pcps_unpack_serial - - - -/*-------------------------------------------------------------- - * 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*/ -void pcps_pack_serial( PCPS_SER_PACK *p ) -{ - p->pack = (uint8_t) ( ( p->baud & BITMASK( PCPS_BD_BITS ) ) - | ( ( p->frame & BITMASK( PCPS_FR_BITS ) ) << PCPS_FR_SHIFT ) - | ( ( p->mode & BITMASK( PCPS_MOD_BITS ) ) << PCPS_MOD_SHIFT ) ); - -} /* pcps_pack_serial */ - - - diff --git a/mbglib/common/pcpsutil.h b/mbglib/common/pcpsutil.h index 41982df..1a892f4 100644 --- a/mbglib/common/pcpsutil.h +++ b/mbglib/common/pcpsutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsutil.h 1.15.1.1 2013/01/24 14:42:52Z martin TEST $ + * $Id: pcpsutil.h 1.25 2018/12/11 16:06:02Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,28 @@ * * ----------------------------------------------------------------------- * $Log: pcpsutil.h $ - * Revision 1.15.1.1 2013/01/24 14:42:52Z martin + * Revision 1.25 2018/12/11 16:06:02Z martin + * Use standard int types for more compatibility. + * Revision 1.24 2018/09/17 12:34:20Z martin + * Fixed a compiler warning. + * Revision 1.23 2017/05/10 15:26:09Z martin + * Tiny cleanup. + * Revision 1.22 2017/03/17 11:45:51 martin + * Moved binary fraction conversion functions to cfg_hlp.h. + * Revision 1.21 2015/10/26 16:09:58 martin + * Moved definition of PCPS_SER_PACK to deviohlp.h. + * The .c file is now obsolete, so there are no prototypes anymore. + * Revision 1.20 2014/07/22 12:22:27Z martin + * Fixed a compiler warning. + * Revision 1.19 2014/07/14 15:43:23Z martin + * Updated doxygen comment. + * Revision 1.18 2014/06/26 14:52:50 martin + * Fixed build on targets not supporting 64 bit types. + * Updated some comments to doxygen format. + * Revision 1.17 2014/05/27 10:39:33Z martin + * More inline functions to convert binary fractions by thomas-b. + * Moved definitions of some signal constants to pcpsdefs.h. + * Revision 1.16 2013/03/04 15:51:02Z martin * Added dfrac_sec_from_bin(). * Revision 1.15 2012/10/15 09:41:32 martin * Cleaned up handling of pragma pack(). @@ -72,49 +93,26 @@ #define _USING_BYTE_ALIGNMENT #endif - -// The following constants are used to draw a signal bar -// depending on a DCF77 clock's signal value: -#define PCPS_SIG_BIAS 55 -#define PCPS_SIG_ERR 1 -#define PCPS_SIG_MIN 20 -#define PCPS_SIG_MAX 68 - - -// the structure below is used with a DCF77 clock's serial interface -typedef struct -{ - PCPS_SERIAL pack; // this byte is passed to the board as parameter - - uint8_t baud; // the other bytes can hold the unpacked values - uint8_t frame; - uint8_t mode; - -} PCPS_SER_PACK; - +#ifdef __cplusplus +extern "C" { +#endif -/*-------------------------------------------------------------- - * Name: pcps_exp_year() - * - * Purpose: Convert a 2-digit year number to a 4-digit - * year number. The resulting year number is in - * the range [year_lim ... ( year_lim + 99 )]. +/** + * @brief Expand a 2-digit year number to a 4-digit year number * - * Input: year the 2-digit year number - * year_lim the smallest 4-digit year number - * to be returned + * The resulting year number includes the century and is + * in the range [year_lim ... ( year_lim + 99 )]. * - * Output: -- + * @param[in] year The 2-digit year number to be converted + * @param[in] year_lim The smallest 4-digit year number to be returned * - * Ret value: the calculated 4-digit year num - *+-------------------------------------------------------------*/ - + * @return The resulting 4 digit year number including century + */ static __mbg_inline -uint16_t pcps_exp_year( uint8_t year, uint16_t year_lim ) +int pcps_exp_year( int year, int year_lim ) { - uint16_t lyear = (uint16_t) ( (uint16_t) year + year_lim - - ( year_lim % 100 ) ); + int lyear = year + year_lim - ( year_lim % 100 ); if ( lyear < year_lim ) lyear += 100; @@ -125,21 +123,12 @@ uint16_t pcps_exp_year( uint8_t year, uint16_t year_lim ) -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ - int pcps_time_is_valid( const PCPS_TIME *p ) ; - void pcps_setup_isa_ports( char *s, int *port_vals, int n_vals ) ; - void pcps_unpack_serial( PCPS_SER_PACK *p ) ; - void pcps_pack_serial( PCPS_SER_PACK *p ) ; +/* (no header definitions found) */ /* ----- function prototypes end ----- */ @@ -148,42 +137,6 @@ extern "C" { #endif -/*-------------------------------------------------------------- - * Name: frac_sec_from_bin() - * - * Purpose: Convert a fraction of a second from binary - * format (as returned in a PCPS_HR_TIME structure - * to a decimal fraction, using a specified scale - * factor. See also the definitions of - * PCPS_HRT_FRAC_SCALE and PCPS_HRT_FRAC_SCALE_FMT - * in the header file. - * - * Input: b the binary fraction - * scale the scale factor - * - * Output: -- - * - * Ret value: the calculated number - *+-------------------------------------------------------------*/ - -static __mbg_inline -uint32_t frac_sec_from_bin( uint32_t b, uint32_t scale ) -{ - return (uint32_t) ( (PCPS_HRT_FRAC_CONVERSION_TYPE) b * scale - / PCPS_HRT_BIN_FRAC_SCALE ); - -} // frac_sec_from_bin - - - -static __mbg_inline -double dfrac_sec_from_bin( uint32_t b ) -{ - return (double) b / (double) PCPS_HRT_BIN_FRAC_SCALE; - -} // dfrac_sec_from_bin - - #if defined( _USING_BYTE_ALIGNMENT ) #pragma pack() // set default alignment diff --git a/mbglib/common/ptp_util.h b/mbglib/common/ptp_util.h new file mode 100644 index 0000000..7632316 --- /dev/null +++ b/mbglib/common/ptp_util.h @@ -0,0 +1,190 @@ + +/************************************************************************** + * + * $Id: ptp_util.h 1.6 2017/05/10 15:26:10Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for ptp_util.c. + * + * ----------------------------------------------------------------------- + * $Log: ptp_util.h $ + * Revision 1.6 2017/05/10 15:26:10Z martin + * Tiny cleanup. + * Revision 1.5 2017/04/25 12:54:21 gregoire.diehl + * Merge changes from 1.3.1.7 & 1.4 + * Revision 1.4 2016/11/10 09:05:26Z martin + * Support for PTP Time Monitor role added by udo. + * Support for NTP modes added by daniel. + * Updated some comments. + * Revision 1.3 2013/09/12 11:05:44 martin + * Added inline function get_supp_ptp_role_mask(). + * Revision 1.2 2013/08/06 12:08:06 udo + * new ptp_clock_id_from_str() + * Revision 1.1 2011/11/14 16:03:39 martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _PTP_UTIL_H +#define _PTP_UTIL_H + + +/* Other headers to be included */ +#include <stdio.h> +#include <lan_util.h> +#include <gpsdefs.h> + + +#ifdef _PTP_UTIL + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#if defined( _USE_PACK ) + #pragma pack( 1 ) // set byte alignment + #define _USING_BYTE_ALIGNMENT +#endif + +#ifdef __cplusplus +extern "C" { +#endif + + +/** + * @brief Derive a "supported PTP roles" bit mask from ::PTP_CFG_INFO::supp_flags + * + * The relevant bits used with ::PTP_CFG_INFO::supp_flags have not been + * defined sequentially, so we need to test them individually to put a + * supported roles bit mask together. + * + * @note Originally, all devices supported the multicast slave role, so + * there was no extra flag to indicate this. However, some newer devices + * may not support the multicast slave role, so two new flags have been + * introduced to cope with this:<br> + * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is set then a different flag + * ::PTP_CFG_CAN_BE_MULTICAST_SLAVE needs to be checked to tell if + * the multicast slave role is supported, or not.<br> + * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is not set then the device + * definitely supports the multicast slave role. + * + * @param flags bit mask from ::PTP_CFG_INFO::supp_flags, see @ref PTP_CFG_FLAG_MASKS + * + * @return bit mask of supported PTP roles, see ::PTP_ROLE_MASKS + */ +static __mbg_inline +uint32_t get_supp_ptp_role_mask( uint32_t flags ) +{ + uint32_t role_mask = 0; + + if ( flags & PTP_CFG_MSK_SUPP_MCAST_SLAVE_FLAG ) + { + // multicast slave role is only supported + // if a different flag is also set + if ( flags & PTP_CFG_MSK_CAN_BE_MULTICAST_SLAVE ) + role_mask |= PTP_ROLE_MSK_MULTICAST_SLAVE; + } + else // multicast slave role is definitely supported + role_mask |= PTP_ROLE_MSK_MULTICAST_SLAVE; + + if ( flags & PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE ) + role_mask |= PTP_ROLE_MSK_UNICAST_SLAVE; + + if ( flags & PTP_CFG_MSK_CAN_BE_MULTICAST_MASTER ) + role_mask |= PTP_ROLE_MSK_MULTICAST_MASTER; + + if ( flags & PTP_CFG_MSK_CAN_BE_UNICAST_MASTER ) + role_mask |= PTP_ROLE_MSK_UNICAST_MASTER; + + if ( flags & PTP_CFG_MSK_CAN_BE_MULTICAST_AUTO ) + role_mask |= PTP_ROLE_MSK_MULTICAST_AUTO; + + if ( flags & PTP_CFG_MSK_CAN_BE_BOTH_MASTER ) + role_mask |= PTP_ROLE_MSK_BOTH_MASTER; + + if ( flags & PTP_CFG_MSK_NTP_HW_TS_MASTER ) + role_mask |= PTP_ROLE_MSK_NTP_SERVER; + + if ( flags & PTP_CFG_MSK_NTP_HW_TS_SLAVE ) + role_mask |= PTP_ROLE_MSK_NTP_CLIENT; + + if ( flags & PTP_CFG_MSK_CAN_BE_TIME_MONITOR ) + role_mask |= PTP_ROLE_MSK_TIME_MONITOR; + + if ( flags & PTP_CFG_MSK_CAN_BE_V1_MASTER ) + role_mask |= PTP_ROLE_MSK_V1_MASTER; + + if ( flags & PTP_CFG_MSK_CAN_BE_V1_SLAVE ) + role_mask |= PTP_ROLE_MSK_V1_SLAVE; + + return role_mask; + +} // get_supp_ptp_role_mask + + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + /** + * @brief Get the MAC addr from a PTP clock ID + * + * The clock ID is usually the MAC ID with 2 octets + * 0xFF and 0xFE inserted in the middle. + * + * @param p_mac_addr The MAC ID to be filled up + * @param p_clock_id The PTP clock ID + */ + void mac_from_ptp_clock_id( MBG_MAC_ADDR *p_mac_addr, const PTP_CLOCK_ID *p_clock_id ) ; + + /** + * @brief Get the PTP clock ID from the MAC addr + * + * The clock ID is usually the MAC ID with 2 octets + * 0xFF and 0xFE inserted in the middle. + * + * @param p_clock_id The PTP clock ID + * @param p_mac_addr The MAC ID to be filled up + */ + void ptp_clock_id_from_mac( PTP_CLOCK_ID *p_clock_id, const MBG_MAC_ADDR *p_mac_addr ) ; + + /** + * @brief Get the PTP clock ID from a string + * + * The clock ID is usually the MAC ID with 2 octets + * 0xFF and 0xFE inserted in the middle. + * + * @param p_clock_id The PTP clock ID + * @param p_str The UUID as string with format e.g. 0050C2FFFED287DE + */ + void ptp_clock_id_from_str( PTP_CLOCK_ID *p_clock_id, const char *p_str ) ; + + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + + +#if defined( _USING_BYTE_ALIGNMENT ) + #pragma pack() // set default alignment + #undef _USING_BYTE_ALIGNMENT +#endif + +/* End of header body */ + + +#undef _ext +#undef _DO_INIT + +#endif /* _PTP_UTIL_H */ + diff --git a/mbglib/common/secudefs.h b/mbglib/common/secudefs.h new file mode 100644 index 0000000..7bf1d94 --- /dev/null +++ b/mbglib/common/secudefs.h @@ -0,0 +1,87 @@ + +/************************************************************************** + * + * $Id: secudefs.h 1.4 2006/08/22 15:32:28Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Check the current compiler type to decide if pragma pack() is + * required to pack cross-platform data structures. + * + * ----------------------------------------------------------------------- + * $Log: secudefs.h $ + * Revision 1.4 2006/08/22 15:32:28Z martin + * Added standard file header. + * Use C99 fixed-size types in structures. + * Revision 1.3 2004/09/20 12:52:16 andre + * control codes moved to gpspriv.h + * Revision 1.2 2004/06/01 11:19:21Z andre + * Revision 1.1 2004/05/05 11:11:43Z andre + * Initial revision + * + **************************************************************************/ + +#ifndef _SECUDEFS_H +#define _SECUDEFS_H + +#include <words.h> +#include <use_pack.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/* Start of header body */ + + + +#if defined( _USE_PACK ) // set byte alignment + #pragma pack( 1 ) +#endif + + +typedef uint16_t METHOD_CODE; // number of crypto method +typedef char PASSWORD[32]; // password max 256 Bit +typedef char PUBLIC_KEY[32]; // public key max 256 Bit + +// info structure requested before password encryption +// to be requested from xport +typedef struct { + uint32_t flags; // + uint32_t supp_flags; // bitmask for supported crypto methods + uint32_t status; // status locked / open +} SECU_INFO; + + +// public key structure to be requested from xport +// immediately before sending SECU_SETTINGS +typedef struct { + uint32_t flags; + PUBLIC_KEY public_key; +} SECU_PUBLIC_KEY; + + +// password settings to be sent to xport +typedef struct { + uint32_t flags; // store flag etc. + METHOD_CODE method_code; // method code according to enum + PUBLIC_KEY public_key; // own public key if key exchange required + PASSWORD password; // current password + PASSWORD new_password; // new password if password shall be set +} SECU_SETTINGS; + +// bitmasks to be used with secu_settings.flags +#define MSK_FLAG_CHANGE_PASSWORD 0x0001 + + + +#if defined( _USE_PACK ) + #pragma pack() +#endif + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/mbglib/common/str_util.c b/mbglib/common/str_util.c new file mode 100644 index 0000000..3c21324 --- /dev/null +++ b/mbglib/common/str_util.c @@ -0,0 +1,452 @@ + +/************************************************************************** + * + * $Id: str_util.c 1.5 2018/08/23 13:07:16Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Meinberg Library module providing portable, safe string functions. + * + * ----------------------------------------------------------------------- + * $Log: str_util.c $ + * Revision 1.5 2018/08/23 13:07:16Z martin + * Moved the snprintf() safety checks to new inline functions that + * can also be used called from specific kernel mode functions. + * Unified variable naming. + * More common __attribute__ syntax. + * Revision 1.4 2018/06/25 13:22:42 martin + * Many functios return int rather than size_t, like standard + * library functions. + * do_str_copy_safe() now returns the number of chars copied. + * Revision 1.3 2016/10/24 08:10:04 thomas-b + * Fixed counter var check in mbg_memcpy_reversed + * Revision 1.2 2016/08/05 12:31:04 martin + * New functions mbg_memcpy() and mbg_memcpy_reversed(). + * Moved string trim functions from cfg_util module here. + * Fixed some compiler warnings. + * Revision 1.1 2015/08/25 15:57:21 martin + * Initial revision. + * + **************************************************************************/ + +#define _STR_UTIL + #include <str_util.h> +#undef _STR_UTIL + +#include <stdio.h> +#include <string.h> + + +#if defined( MBG_TGT_WIN32 ) && !defined( MBG_TGT_CVI ) + #define mbg_vsnprintf _vsnprintf +#else + #define mbg_vsnprintf vsnprintf +#endif + + +#if defined( MBG_TGT_DOS ) + +static /*HDR*/ +// Under 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. ;-) +int vsnprintf( char *s, size_t max_len, const char *fmt, va_list args ) +{ + (void) max_len; // quiet compiler warning "not used" + + return vsprintf( s, fmt, args ); + +} // vsnprintf + +#endif + + + +/*HDR*/ +/** + * @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. + * + * If the output exceeds the buffer size and thus is truncated then:<br> + * + * - Under Windows a negative value is returned and eventually *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 + * 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, ... ); + * + * may always work properly, or fail with buffer overruns or stack + * corruption depending on the build environment. + * This wrapper function takes care that strings are always terminated + * properly, and that the returned value always matches the number of + * 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 + * buffer is specified, and a large number of characters (more than + * MAXINT) are written to that buffer then how can an "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 + * + * @return Number of characters written to the output buffer, except the terminating 0 + * + * @see ::snprintf_safe + * @see ::strncpy_safe + * @see ::sn_cpy_str_safe + * @see ::sn_cpy_char_safe + */ +__attribute__( ( format( printf, 3, 0 ) ) ) +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 + + n = mbg_vsnprintf( s, max_len, fmt, args ); + + // Do some common checks to avoid subsequent buffer overflows, etc. + return mbg_chk_snprint_results( n, s, max_len ); + +} // vsnprintf_safe + + + +/*HDR*/ +/** + * @brief A portable, safe implementation of snprintf() + * + * 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 + * + * @return 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, ... ) +{ + va_list args; + int len; + + va_start( args, fmt ); + len = vsnprintf_safe( s, max_len, fmt, args ); + va_end( args); + + return len; + +} // snprintf_safe + + + +static __mbg_inline +/* (explicitly excluded from doxygen) + * @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. + * + * @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. + * + * @see ::vsnprintf_safe + * @see ::snprintf_safe + * @see ::strncpy_safe + * @see ::sn_cpy_str_safe + * @see ::sn_cpy_char_safe + */ +size_t do_str_copy_safe( char *dst, const char *src, size_t n ) +{ + size_t i = 0; + + if ( n > 0 ) + { + for (;;) + { + *dst = *src; + + if ( *dst == 0 ) + break; // just copied the terminating 0, done + + if ( --n == 0 ) // no more space left in buffer + { + *dst = 0; // force terminating 0 + break; + } + + i++; // count normal characters + src++; + dst++; + } + } + + return i; + +} // do_str_copy_safe + + + +/*HDR*/ +/** + * @brief A portable, safe implementation of strncpy() + * + * In the original implementation of 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. + * + * Our implementation always forces a proper termination by 0, but unlike + * the original implementation of 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 + * + * @return Pointer to the destination buffer + * + * @see ::vsnprintf_safe + * @see ::snprintf_safe + * @see ::sn_cpy_str_safe + * @see ::sn_cpy_char_safe + */ +char *strncpy_safe( char *dst, const char *src, size_t max_len ) +{ + do_str_copy_safe( dst, src, max_len ); + + return dst; + +} // strncpy_safe + + + +/*HDR*/ +/** + * @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 + * + * @return Number of characters copied to the destination buffer + * + * @see ::vsnprintf_safe + * @see ::snprintf_safe + * @see ::strncpy_safe + * @see ::sn_cpy_char_safe + */ +int sn_cpy_str_safe( char *dst, size_t max_len, const char *src ) +{ + size_t n = do_str_copy_safe( dst, src, max_len ); + + return _int_from_size_t( n ); + +} // sn_cpy_str_safe + + + +/*HDR*/ +/** + * @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 + * + * @return Number of characters copied to the destination buffer, without the terminating 0 + * + * @see ::vsnprintf_safe + * @see ::snprintf_safe + * @see ::strncpy_safe + * @see ::sn_cpy_str_safe + */ +int sn_cpy_char_safe( char *dst, size_t max_len, char c ) +{ + size_t n; + char tmp_str[2]; + + tmp_str[0] = c; + tmp_str[1] = 0; + + n = do_str_copy_safe( dst, tmp_str, max_len ); + + return _int_from_size_t( n ); + +} // sn_cpy_char_safe + + + +/*HDR*/ +/** + * @brief Trim whitespace at the end of a string + * + * @param[in,out] s The string to be trimmed + */ +void trim_trailing_whitespace( char *s ) +{ + char *cp; + + // set all trailing spaces to 0 + for ( cp = &s[strlen( s )]; cp > s; ) + { + --cp; + + if ( *cp >= ' ' ) + break; + + *cp = 0; + } + +} // trim_trailing_whitespace + + + +/*HDR*/ +/** + * @brief Trim whitespace at the beginning of a string + * + * @param[in,out] s The string to be trimmed + */ +void trim_leading_whitespace( char *s ) +{ + char *srcp; + char *dstp; + + // Search the first non-space character. + for ( srcp = s; *srcp; srcp++ ) + if ( *srcp > ' ' ) + break; + + // If there are leading spaces then srcp now + // points behind the beginning of the string, + // otherwise there's nothing to do. + if ( srcp > s ) + { + // Copy the remaining string. + dstp = s; + + while ( *srcp ) + *dstp++ = *srcp++; + + *dstp = 0; + } + +} // trim_leading_whitespace + + + +/*HDR*/ +/** + * @brief Trim both leading and trailing whitespace from a string + * + * @param[in,out] s The string to be trimmed + */ +void trim_whitespace( char *s ) +{ + trim_trailing_whitespace( s ); + trim_leading_whitespace( s ); + +} // trim_whitespace + + + +/*HDR*/ +/** + * @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(). + * + * @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 ) +{ + uint8_t *dstp = (uint8_t *) dst; + uint8_t *srcp = (uint8_t *) src; + + while ( n_bytes-- ) + *dstp++ = *srcp++; + +} // mbg_memcpy + + + +/*HDR*/ +/** + * @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(). + * + * @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 + { + uint8_t *dstp = ( (uint8_t *) dst ) + n_bytes; + uint8_t *srcp = ( (uint8_t *) src ) + n_bytes; + + while ( n_bytes-- ) + *(--dstp) = *(--srcp); + } + +} // mbg_memcpy_reversed + + + diff --git a/mbglib/common/str_util.h b/mbglib/common/str_util.h new file mode 100644 index 0000000..83c375b --- /dev/null +++ b/mbglib/common/str_util.h @@ -0,0 +1,362 @@ + +/************************************************************************** + * + * $Id: str_util.h 1.6 2018/08/23 13:10:26Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for str_util.c + * + * ----------------------------------------------------------------------- + * $Log: str_util.h $ + * Revision 1.6 2018/08/23 13:10:26Z martin + * New inline functions mbg_buffer_specs_valid() and + * mbg_chk_snprint_results() that can also be called + * from code used in kernel mode. + * Updated function prototypes. + * Revision 1.5 2018/06/25 13:24:15 martin + * Updated function prototypes. + * Revision 1.4 2017/05/10 15:26:10 martin + * Tiny cleanup. + * Revision 1.3 2016/12/14 16:22:24 martin + * Added macro _sn_cpy_str_safe() to simplify calls. + * Revision 1.2 2016/08/05 12:33:17 martin + * Moved string trim functions from cfg_util module here. + * Added variable str_not_avail. + * Fixed some spelling. + * Updated function prototypes. + * Revision 1.1 2015/08/25 15:57:43 martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _STR_UTIL_H +#define _STR_UTIL_H + +/* Other headers to be included */ + +#include <words.h> // implicitly includes mbg_tgt.h for non-firmware projects + +#if defined( MBG_TGT_KERNEL ) + #include <mbgddmsg.h> +#else + #include <stdlib.h> + #include <stdarg.h> +#endif + + +#ifdef _STR_UTIL + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + + +_ext const char *str_not_avail +#ifdef _DO_INIT + = "N/A" +#endif +; + + + +static __mbg_inline /*HDR*/ +/** + * @brief Check if the buffer plus size parameters passed to a function are valid. + * + * This function can be used to check parameters that have been + * 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. + * + * @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. + */ +bool mbg_buffer_specs_valid( char *s, size_t max_len ) +{ + return s != NULL && max_len > 0; + +} // mbg_buffer_specs_valid + + + +static __mbg_inline /*HDR*/ +/** + * @brief Check the results of an snprintf()-like function. + * + * Implementations of snprintf()-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 + * 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 + * 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. + * + * @return The real number of bytes that had been written to the buffer. + * + * @see ::vsnprintf_safe + * @see ::mbg_kdd_vsnprintf + * @see ::mbg_buffer_specs_valid + */ +int mbg_chk_snprint_results( size_t n, char *s, size_t max_len ) +{ + if ( !mbg_buffer_specs_valid( s, max_len ) ) + return 0; // Buffer parameters are not valid. + + + // Force proper worst-case termination of the output string. + s[max_len - 1] = 0; + + // If n is > 0, but less than the specified buffer size we + // assume the value is correct. + if ( n > 0 && n < max_len ) + goto out; + + // Determine the real string length, but don't just call strlen() + // since that function may not be available in kernel mode. + for ( n = 0; s[n]; n++ ); + +out: + // Most snprintf()-like functions take a "size_t" to specify the buffer size, + // but just return an "int", which may be a smaller data type than "size_t", + // so we do a conversion here, if required, and try to do the conversion + // in a safe way. + return _int_from_size_t( n ); + +} // mbg_chk_snprint_results + + + +#define _sn_cpy_str_safe( _dst, _src ) sn_cpy_str_safe( _dst, sizeof( _dst ), _src ) + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + /** + * @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. + * + * If the output exceeds the buffer size and thus is truncated then:<br> + * + * - Under Windows a negative value is returned and eventually *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 + * 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, ... ); + * + * may always work properly, or fail with buffer overruns or stack + * corruption depending on the build environment. + * This wrapper function takes care that strings are always terminated + * properly, and that the returned value always matches the number of + * 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 + * buffer is specified, and a large number of characters (more than + * MAXINT) are written to that buffer then how can an "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 + * + * @return Number of characters written to the output buffer, except the terminating 0 + * + * @see ::snprintf_safe + * @see ::strncpy_safe + * @see ::sn_cpy_str_safe + * @see ::sn_cpy_char_safe + */ + __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() + * + * 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 + * + * @return 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, ... ) ; + + /** + * @brief A portable, safe implementation of strncpy() + * + * In the original implementation of 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. + * + * Our implementation always forces a proper termination by 0, but unlike + * the original implementation of 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 + * + * @return Pointer to the destination buffer + * + * @see ::vsnprintf_safe + * @see ::snprintf_safe + * @see ::sn_cpy_str_safe + * @see ::sn_cpy_char_safe + */ + 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 + * + * 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 + * + * @return Number of characters copied to the destination buffer + * + * @see ::vsnprintf_safe + * @see ::snprintf_safe + * @see ::strncpy_safe + * @see ::sn_cpy_char_safe + */ + 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 + * + * 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 + * + * @return Number of characters copied to the destination buffer, without the terminating 0 + * + * @see ::vsnprintf_safe + * @see ::snprintf_safe + * @see ::strncpy_safe + * @see ::sn_cpy_str_safe + */ + int sn_cpy_char_safe( char *dst, size_t max_len, char c ) ; + + /** + * @brief Trim whitespace at the end of a string + * + * @param[in,out] s The string to be trimmed + */ + void trim_trailing_whitespace( char *s ) ; + + /** + * @brief Trim whitespace at the beginning of a string + * + * @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 + * + * @param[in,out] s The string to be trimmed + */ + void trim_whitespace( char *s ) ; + + /** + * @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(). + * + * @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 + * + * 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(). + * + * @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 ) ; + + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _STR_UTIL_H */ diff --git a/mbglib/common/timeutil.c b/mbglib/common/timeutil.c new file mode 100644 index 0000000..3c40ad2 --- /dev/null +++ b/mbglib/common/timeutil.c @@ -0,0 +1,356 @@ + +/************************************************************************** + * + * $Id: timeutil.c 1.8 2018/12/11 15:02:57Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Meinberg Library module for safe time conversion routines. + * + * ----------------------------------------------------------------------- + * $Log: timeutil.c $ + * Revision 1.8 2018/12/11 15:02:57Z martin + * Cast to avoid build error on Windows. + * Revision 1.7 2018/01/30 09:51:35Z martin + * Let snprint_gmtime_error() return an int instead of size_t. + * Updated mbg_clock_gettime(): + * Revision 1.6 2018/01/15 18:31:08Z martin + * Account for renamed library symbol NSEC_PER_SEC. + * Moved function snprint_utc_offs() here. + * Changed return type of some printing functions to int. + * Revision 1.5 2017/11/16 13:34:09 philipp + * Extended ISO printing helper functions + * 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). + * Revision 1.2 2017/07/05 07:10:48Z martin + * Added mbg_clock_gettime(), mbg_clock_settime(), + * and check_precise_time_api() for Windows. + * Revision 1.1 2016/07/15 14:14:19Z martin + * Initial revision + * + **************************************************************************/ + +#define _TIMEUTIL + #include <timeutil.h> +#undef _TIMEUTIL + +#include <mbgtime.h> +#include <str_util.h> + +#if defined( MBG_TGT_WIN32 ) + #include <stdio.h> +#endif + + + +/*HDR*/ +int snprint_gmtime_error( char *s, size_t max_len, int mbg_errno, time_t t, const char *calling_fnc ) +{ + size_t n = snprintf_safe( s, max_len, "gmtime() call failed" ); + + if ( calling_fnc ) + n += snprintf_safe( &s[n], max_len - n, " in %s", calling_fnc ); + + #if defined( MBG_TGT_MISSING_64_BIT_TYPES ) + //### TODO E.g. in VC6 time_t is only 32 bit anyway. + n += snprintf_safe( &s[n], max_len - n, " for time_t %lu: %s", + (unsigned long) t, mbg_strerror( mbg_errno ) ); + #else + n += snprintf_safe( &s[n], max_len - n, " for time_t %" PRIu64 ": %s", + (uint64_t) t, mbg_strerror( mbg_errno ) ); + #endif + + return _int_from_size_t( n ); + +} // snprint_gmtime_error + + + +#if defined( MBG_TGT_WIN32 ) + +typedef int clockid_t; +#define clockid_t clockid_t + +#define CLOCK_REALTIME ( (clockid_t) 0 ) + +/*HDR*/ +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 ) + { + #if defined( TIME_UTC ) // C11 / VS2015+ + int rc = timespec_get( tp, TIME_UTC ); + return ( rc == 0 ) ? -1 : 0; + #else + #define EPOCH_HNS 116444736000000000i64 + FILETIME ft; + unsigned __int64 tmp; + gstaft_fnc( &ft ); + tmp = ( (__int64) ft.dwHighDateTime << 32 ) | ft.dwLowDateTime; + tmp -= EPOCH_HNS; // 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 + } + else + return -1; // TODO this is e.g. in case of CLOCK_MONOTONIC, we could use QPC then. + +} // mbg_clock_gettime + + + +/*HDR*/ +int mbg_clock_settime( clockid_t clock_id, const struct timespec *tp ) +{ + if ( clock_id == CLOCK_REALTIME ) + { +#if 0 // ### TODO FIXME This needs to be implemented. + #if defined( TIME_UTC ) // C11 / VS2015+ + int rc = timespec_get( res, TIME_UTC ); // TODO Check this code + return ( rc == 0 ) ? -1 : 0 // rc == 0 means error + #else + #define EPOCH_HNS 116444736000000000i64 + FILETIME ft; + unsigned __int64 tmp; + gstaft_fnc( &ft ); + tmp = ( (__int64) ft.dwHighDateTime << 32 ) | ft.dwLowDateTime; + tmp -= EPOCH_HNS; // convert to Unix epoch + tmp *= 100; // convert to nanoseconds + res->tv_sec = ( tmp / NSEC_PER_SEC ); + res->tv_nsec = ( tmp % NSEC_PER_SEC ); + return 0; + #endif +#endif + + return 0; // FIXME this is actually not true + } + else + return -1; // TODO this is e.g. in case of CLOCK_MONOTONIC, we could use QPC then. + +} // mbg_clock_settime + + + +bool force_legacy_gstaft; + + +/*HDR*/ +void check_precise_time_api( void ) +{ + const char *info =""; + GSTAFT_FNC tmp_fnc; + HINSTANCE h = LoadLibrary( "kernel32.dll" ); + + if ( h == NULL ) + { + info = "Precise system time may not be supported; failed to get handle for kernel32.dll."; + goto out; + } + + tmp_fnc = (GSTAFT_FNC) GetProcAddress( h, "GetSystemTimePreciseAsFileTime" ); + + if ( tmp_fnc == NULL ) + { + info = "Precise system time NOT supported"; + goto out; + } + + if ( force_legacy_gstaft ) + { + info = "Precise system time is supported, but legacy function used by request"; + goto out; + } + + gstaft_fnc = tmp_fnc; + info = "Precise system time is supported and used"; + +out: + printf( "%s\n", info ); + +} // check_precise_time_api + +#endif + + + +/*HDR*/ +/** + * @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]. + * + * @return The number of characters written to the output buffer, except the terminating 0. + */ +int snprint_utc_offs( char *s, size_t max_len, const char *info, long utc_offs ) +{ + size_t n = 0; + + // utc_offs is in [s] + char utc_offs_sign = ( utc_offs < 0 ) ? '-' : '+'; + ulong abs_utc_offs = labs( utc_offs ); + ulong utc_offs_hours = abs_utc_offs / SECS_PER_HOUR; + ulong tmp = abs_utc_offs % SECS_PER_HOUR; + ulong utc_offs_mins = tmp / MINS_PER_HOUR; + ulong utc_offs_secs = tmp % MINS_PER_HOUR; + + if ( info ) + n += snprintf_safe( &s[n], max_len - n, "%s", info ); + + n += snprintf_safe( &s[n], max_len - n, "%c%lu", utc_offs_sign, utc_offs_hours ); + + if ( utc_offs_mins || utc_offs_secs ) + n += snprintf_safe( &s[n], max_len - n, ":%02lu", utc_offs_mins ); + + if ( utc_offs_secs ) + n += snprintf_safe( &s[n], max_len - n, ":%02lu", utc_offs_secs ); + + n += sn_cpy_str_safe( &s[n], max_len - n, "h" ); + + return _int_from_size_t( n ); + +} // snprint_utc_offs + + + +/*HDR*/ +int snprint_time_t_to_iso( time_t tstamp, int offs_hours, char *buf, size_t len ) +{ + struct tm tm = { 0 }; + size_t n; + int rc; + + if ( offs_hours ) + tstamp += offs_hours * SECS_PER_HOUR; + + rc = mbg_gmtime( &tm, &tstamp ); + + if ( mbg_rc_is_error( rc ) ) + { + // TODO Error: conversion failed. + } + + n = snprintf_safe( buf, len, "%04d-%02d-%02d, %02d:%02d:%02d", + tm.tm_year + 1900, tm.tm_mon + 1, tm.tm_mday, + tm.tm_hour, tm.tm_min, tm.tm_sec ); + + return _int_from_size_t( n ); + +} // snprint_time_t_to_iso + + + +static __mbg_inline /*HDR*/ +int __to_iso_frac( time_t tstamp, int offset, time_t frac, + const char* fmt, char *buf, size_t max_len ) +{ + size_t n = snprint_time_t_to_iso( tstamp, offset, buf, max_len ); + n += snprintf_safe( &buf[n], max_len - n, fmt, frac ); + + return _int_from_size_t( n ); + +} // __to_iso_frac + + + +/*HDR*/ +int snprint_time_t_to_iso_ms( time_t tstamp, int offs_hours, time_t frac, + char *buf, size_t len ) +{ + tstamp += frac / MSEC_PER_SEC; + frac %= MSEC_PER_SEC; + + return __to_iso_frac( tstamp, offs_hours, frac, ".%03lu", buf, len ); + +} // snprint_time_t_to_iso_ms + + + +/*HDR*/ +int snprint_time_t_to_iso_us( time_t tstamp, int offs_hours, time_t frac, + char *buf, size_t len ) +{ + tstamp += frac / USEC_PER_SEC; + frac %= USEC_PER_SEC; + + return __to_iso_frac( tstamp, offs_hours, frac, ".%06lu", buf, len ); + +} // snprint_time_t_to_iso_us + + + +/*HDR*/ +int snprint_time_t_to_iso_ns( time_t tstamp, int offs_hours, time_t frac, + char *buf, size_t len ) +{ + tstamp += frac / NSEC_PER_SEC; + frac %= NSEC_PER_SEC; + + return __to_iso_frac( tstamp, offs_hours, frac, ".%09lu", buf, len ); + +} // snprint_time_t_to_iso_ns + + + +/*HDR*/ +int snprint_ntp_tstamp_to_iso_ms( const NTP_TSTAMP *ts, char *buf, size_t len ) +{ + time_t secs = cvt_to_time_t( ts->seconds ) - NTP_SEC_BIAS; + time_t fracs = bin_frac_32_to_msec( ts->fractions ); + + return snprint_time_t_to_iso_ms( secs, 0, fracs, buf, len ); + +} // snprint_ntp_tstamp_to_iso_ms + + + +/*HDR*/ +int snprint_ntp_tstamp_to_iso_us( const NTP_TSTAMP *ts, char *buf, size_t len ) +{ + time_t secs = cvt_to_time_t( ts->seconds ) - NTP_SEC_BIAS; + time_t fracs = bin_frac_32_to_usec( ts->fractions ); + + return snprint_time_t_to_iso_us( secs, 0, fracs, buf, len ); + +} // snprint_ntp_tstamp_to_iso_us + + + +/*HDR*/ +int snprint_ntp_tstamp_to_iso_ns( const NTP_TSTAMP *ts, char *buf, size_t len ) +{ + time_t secs = cvt_to_time_t( ts->seconds ) - NTP_SEC_BIAS; + time_t fracs = bin_frac_32_to_nsec( ts->fractions ); + + return snprint_time_t_to_iso_ns( secs, 0, fracs, buf, len ); + +} // snprint_ntp_tstamp_to_iso_ns + diff --git a/mbglib/common/timeutil.h b/mbglib/common/timeutil.h new file mode 100644 index 0000000..92a38d2 --- /dev/null +++ b/mbglib/common/timeutil.h @@ -0,0 +1,265 @@ + +/************************************************************************** + * + * $Id: timeutil.h 1.9 2018/12/11 15:36:40Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for timeutil.c + * + * ----------------------------------------------------------------------- + * $Log: timeutil.h $ + * Revision 1.9 2018/12/11 15:36:40Z martin + * _cvt_to_time_t() now expects an int64_t type parameter. + * Revision 1.8 2018/11/29 15:32:04Z martin + * Moved some inline functions here. + * Include mbgtime.h. + * Revision 1.7 2018/01/30 09:54:12Z martin + * Updated function prototypes. + * Revision 1.6 2018/01/15 18:31:21Z martin + * Updated function prototypes. + * Revision 1.5 2017/11/16 13:34:09 philipp + * Extended ISO printing helper functions + * Revision 1.4 2017/11/16 11:33:28 philipp + * Added functions to print a time_t to ISO format + * Revision 1.3 2017/07/05 07:15:00 martin + * Provide basic support for clock_gettime()/clock_settime() + * compatible functions for Windows. + * Updated function prototypes. + * Revision 1.1 2016/07/15 14:14:20Z martin + * Initial revision + * + **************************************************************************/ + +#ifndef _TIMEUTIL_H +#define _TIMEUTIL_H + +/* Other headers to be included */ + +#include <gpsdefs.h> +#include <mbgerror.h> +#include <mbgtime.h> + +#include <time.h> +#include <stddef.h> + + +#ifdef _TIMEUTIL + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + + +#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_DOS ) + +typedef int clockid_t; +#define clockid_t clockid_t + +#define CLOCK_REALTIME ( (clockid_t) 0 ) + +#endif + + + +#if defined( MBG_TGT_WIN32 ) + +#define __const__ const + +/** + * @brief A pointer to a function returning the system time as FILETIME + * + * This can be e.g. the standard Windows API call GetSystemTimeAsFileTime() + * or the GetSystemTimeAsPreciseFileTime() API call introduced with Windows 8. + */ +typedef VOID (WINAPI *GSTAFT_FNC)(LPFILETIME lpSystemTimeAsFileTime); + +_ext GSTAFT_FNC gstaft_fnc +#ifdef _DO_INIT + = GetSystemTimeAsFileTime +#endif +; + +#endif + + +static __mbg_inline +time_t cvt_to_time_t( int64_t t ) +{ + // Eventually we can do some epoch check here. + return (time_t) t; + +} // cvt_to_time_t + + + +static __mbg_inline +int mbg_gmtime( struct tm *p_tm, const time_t *p_time ) +{ + struct tm *p_tm_tmp = gmtime( p_time ); + + if ( p_tm_tmp == NULL ) // conversion failed + return mbg_get_last_error( NULL ); + + *p_tm = *p_tm_tmp; + + return MBG_SUCCESS; + +} // mbg_gmtime + + + +static __mbg_inline /*HDR*/ +double ntp_tstamp_to_double( const NTP_TSTAMP *t ) +{ + return (double) t->seconds + ( ( (double) t->fractions ) / NTP_FRAC_PER_SEC ); + +} // ntp_tstamp_to_double + + + +static __mbg_inline /*HDR*/ +ulong ntp_frac_to_nsec( uint32_t frac ) +{ + uint64_t tmp = ( (uint64_t) frac * NSEC_PER_SEC ) / NTP_FRAC_PER_SEC; + +#if 0 // TODO Currently not supported + if ( tmp >= NSEC_PER_SEC ) + mbglog( LOG_WARNING, "Range overflow in ntp_frac_to_nsec: 0x%X -> %Lu", + frac, tmp ); +#endif + + return (ulong) tmp; + +} // ntp_frac_to_nsec + + + +static __mbg_inline /*HDR*/ +uint32_t nsec_to_ntp_frac( ulong nsec ) +{ + uint64_t tmp; + + tmp = ( (uint64_t) nsec * NTP_FRAC_PER_SEC ) / NSEC_PER_SEC; + +#if 0 // TODO Currently not supported + if ( tmp >= NTP_FRAC_PER_SEC ) + mbglog( LOG_WARNING, "Range overflow in nsec_to_ntp_frac: %lu -> 0x%LX", + (ulong) nsec, tmp ); +#endif + + return (uint32_t) tmp; + +} // nsec_to_ntp_frac + + + +static __mbg_inline /*HDR*/ +void timespec_to_ntp_tstamp( NTP_TSTAMP *t_ntp, const struct timespec *t_ts ) +{ + t_ntp->seconds = (uint32_t) t_ts->tv_sec + NTP_SEC_BIAS; + t_ntp->fractions = nsec_to_ntp_frac( t_ts->tv_nsec ); + +} // timespec_to_ntp_tstamp + + + +static __mbg_inline /*HDR*/ +void ntp_tstamp_to_timespec( struct timespec *t_ts, const NTP_TSTAMP *t_ntp ) +{ + t_ts->tv_sec = t_ntp->seconds - NTP_SEC_BIAS; + t_ts->tv_nsec = ntp_frac_to_nsec( t_ntp->fractions ); + +} // ntp_tstamp_to_timespec + + + +static __mbg_inline /*HDR*/ +int timespec_is_set( const struct timespec *p ) +{ + return p->tv_sec != 0 || p->tv_nsec != 0; + +} // timespec_is_set + + + +// +// compute the difference of two timespec variables +// +static __mbg_inline /*HDR*/ +double delta_timespec_d_s( const struct timespec *ts, + const struct timespec *ts_ref ) +{ + return ( (double) ts->tv_sec - (double) ts_ref->tv_sec ) + + ( (double) ts->tv_nsec - (double) ts_ref->tv_nsec ) / NSEC_PER_SEC; + +} // delta_timespec_d_s + + + +static __mbg_inline /*HDR*/ +int64_t delta_timespec_ll_ns( const struct timespec *ts, + const struct timespec *ts_ref ) +{ + int64_t tmp = ts->tv_sec - ts_ref->tv_sec; + tmp = ( tmp * NSEC_PER_SEC ) + ( ts->tv_nsec - ts_ref->tv_nsec ); + + return tmp; + +} // delta_timespec_ll_ns + + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* 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 ) ; + int mbg_clock_gettime( clockid_t clock_id, struct timespec *tp ) ; + 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 + * + * 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]. + * + * @return The number of characters written to the output buffer, except the terminating 0. + */ + int snprint_utc_offs( char *s, size_t max_len, const char *info, long utc_offs ) ; + + int snprint_time_t_to_iso( time_t tstamp, int offs_hours, char *buf, size_t len ) ; + int snprint_time_t_to_iso_ms( time_t tstamp, int offs_hours, time_t frac, char *buf, size_t len ) ; + int snprint_time_t_to_iso_us( time_t tstamp, int offs_hours, time_t frac, char *buf, size_t len ) ; + int snprint_time_t_to_iso_ns( time_t tstamp, int offs_hours, time_t frac, char *buf, size_t len ) ; + int snprint_ntp_tstamp_to_iso_ms( const NTP_TSTAMP *ts, char *buf, size_t len ) ; + int snprint_ntp_tstamp_to_iso_us( const NTP_TSTAMP *ts, char *buf, size_t len ) ; + int snprint_ntp_tstamp_to_iso_ns( const NTP_TSTAMP *ts, char *buf, size_t len ) ; + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _TIMEUTIL_H */ diff --git a/mbglib/common/toolutil.c b/mbglib/common/toolutil.c index 3cdd2bb..7e4bd46 100644 --- a/mbglib/common/toolutil.c +++ b/mbglib/common/toolutil.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: toolutil.c 1.4.1.4 2013/02/05 15:27:30Z martin TEST $ + * $Id: toolutil.c 1.8 2018/11/15 12:20:44Z martin REL_M $ * * Description: * Common functions which can be used with Meinberg command line @@ -9,11 +9,38 @@ * * ----------------------------------------------------------------------- * $Log: toolutil.c $ - * Revision 1.4.1.4 2013/02/05 15:27:30Z martin - * Revision 1.4.1.3 2013/02/05 15:24:46 martin - * Revision 1.4.1.2 2013/02/05 14:39:38 martin - * Revision 1.4.1.1 2013/02/05 14:37:56Z martin - * Started to supported Windows target. + * Revision 1.8 2018/11/15 12:20:44Z martin + * Individual MBG_MICRO_VERSION codes are now obsolete. + * Revision 1.7 2018/07/03 14:47:31 martin + * Print a message if an old card with 20 ms timing bug is detected. + * Revision 1.6 2018/06/25 13:45:26 martin + * Distinguish between MBG_TGT_HAS_DEV_FN and + * MBG_TGT_HAS_DEV_FN_BASE. + * Use some predefined string formats. + * Check parameters in mbg_open_device_by_param(). + * Some string print functions now return int rather than + * size_t, like standard library functions. + * Use snprint_utc_offs() from timeutil.c. + * Revision 1.5 2017/07/05 07:32:38 martin + * Renamed mbg_check_devices() to mbg_handle_devices() and added + * a new parameter which controls if only one or all devices + * should be handled if no device has been specified. + * New function mbg_open_device_by_param() which can be used e.g. to + * check if a parameter string is an device file name (MBG_DEV_FN), + * or a device index number, or a device name in MBG_DEV_NAME format, + * and calls the appropriate open function to open the device. + * Made mbg_snprint_hr_tstamp() more versatile by passing a new + * optional UTC offset parameter. + * Account for PCPS_HRT_BIN_FRAC_SCALE renamed to MBG_FRAC32_UNITS_PER_SEC. + * Account for frac_sec_from_bin() obsoleted by bin_frac_32_to_dec_frac(). + * Print device options with OS-specific device names. + * Print special firmware version info, if appropriate. + * Reworked error checking after opening device. + * mbg_print_program_info() which is usually called first after program + * start now makes stdout unbuffered if output is redirected. + * Use safe string functions from str_util.c. + * Support Windows and QNX Neutrino targets. + * Added doxygen comments. * Revision 1.4 2012/10/15 09:33:48 martin * Use common way to handle version information. * Open device with O_RDWR flag. @@ -39,43 +66,104 @@ #undef _TOOLUTIL // include Meinberg headers +#include <cfg_hlp.h> #include <pcpsutil.h> +#include <timeutil.h> +#include <str_util.h> + +#if defined( MBG_TGT_WIN32 ) + #include <mbgsvctl.h> +#endif // include system headers #include <stdio.h> #include <stdlib.h> #include <string.h> +#include <errno.h> + + + +#if defined( MBG_TGT_WIN32 ) + #define isatty _isatty + #define fileno _fileno +#endif + 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 PCPS_HRT_BIN_FRAC_SCALE to get the correct fractions - // and we multiply by 1E6 to get the result in microseconds - return (double) ( (int64_t) ( ts - prv_ts ) ) * 1E6 / PCPS_HRT_BIN_FRAC_SCALE; + + // 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*/ -int mbg_program_info_str( char *s, size_t max_len, const char *pname, - int micro_version, int first_year, int last_year ) +/** + * @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. + * + * @return The number of characters printed to the buffer. + */ +int mbg_program_version_str( char *s, size_t max_len ) { int n; + n = snprintf_safe( s, max_len, "%i.%i.%i", MBG_MAJOR_VERSION_CODE, + MBG_MINOR_VERSION_CODE, MBG_MICRO_VERSION_CODE ); + + return n; + +} // mbg_program_version_str + + + +/*HDR*/ +/** + * @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. + * + * @return The number of characters printed to the buffer. + */ +int mbg_program_info_str( char *s, size_t max_len, const char *pname, + int first_year, int last_year ) +{ + int n = 0; + if ( last_year == 0 ) last_year = MBG_CURRENT_COPYRIGHT_YEAR; - n = snprintf( s, max_len, "%s v%i.%i.%i copyright Meinberg ", pname, - MBG_MAJOR_VERSION_CODE, MBG_MINOR_VERSION_CODE, micro_version ); + n += snprintf_safe( &s[n], max_len - n, "%s v", pname ); + + n += mbg_program_version_str( &s[n], max_len - n ); + + n += snprintf_safe( &s[n], max_len - n, " copyright Meinberg " ); if ( first_year != last_year ) - n += snprintf( &s[n], max_len - n, "%04i-", first_year ); + n += snprintf_safe( &s[n], max_len - n, "%04i-", first_year ); - n += snprintf( &s[n], max_len - n, "%04i", last_year ); + n += snprintf_safe( &s[n], max_len - n, "%04i", last_year ); return n; @@ -84,13 +172,23 @@ int mbg_program_info_str( char *s, size_t max_len, const char *pname, /*HDR*/ -void mbg_print_program_info( const char *pname, int micro_version, int first_year, int last_year ) +/** + * @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. + */ +void mbg_print_program_info( const char *pname, int first_year, int last_year ) { char ws[256]; - #if defined( MBG_MICRO_VERSION_CODE_DEV ) - micro_version = MBG_MICRO_VERSION_CODE_DEV; - #endif - mbg_program_info_str( ws, sizeof( ws ), pname, micro_version, first_year, last_year ); + + // If the output has been redirected then make stdout unbuffered, + // e.g. to see the output immediately even though piped through 'tee'. + if ( !isatty( fileno( stdout ) ) ) + setvbuf( stdout, NULL, _IONBF, 0 ); + + mbg_program_info_str( ws, sizeof( ws ), pname, first_year, last_year ); printf( "\n%s\n\n", ws ); @@ -99,6 +197,12 @@ void mbg_print_program_info( const char *pname, int micro_version, int first_yea /*HDR*/ +/** + * @brief Print usage intro to console + * + * @param[in] pname The program name. + * @param[in] info An optional additional info string, may be NULL. + */ void mbg_print_usage_intro( const char *pname, const char *info ) { printf( "Usage: %s [[opt] [opt] ...] [[dev] [dev] ...]\n\n", pname ); @@ -112,13 +216,19 @@ void mbg_print_usage_intro( const char *pname, const char *info ) /*HDR*/ +/** + * @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. + */ void mbg_print_opt_info( const char *opt_name, const char *opt_info ) { if ( opt_name == NULL ) - opt_name = ""; + opt_name = str_empty; if ( opt_info == NULL ) - opt_info = ""; + opt_info = str_empty; printf( " %8s %s\n", opt_name, opt_info ); @@ -127,9 +237,15 @@ void mbg_print_opt_info( const char *opt_name, const char *opt_info ) /*HDR*/ +/** + * @brief Print info on common program help arguments + * + * Lists program parameters causing printing + * of help / usage information. + */ void mbg_print_help_options( void ) { - puts( "where opt is one of the options:" ); + puts( "where \"opt\" is one of the options:" ); mbg_print_opt_info( "-? or -h", "print this usage information" ); } // mbg_print_help_options @@ -137,17 +253,35 @@ void mbg_print_help_options( void ) /*HDR*/ +/** + * @brief Print common info on how to specify devices on the command line + */ void mbg_print_device_options( void ) { - puts( "\nwhere dev is the name of a device, e.g.:\n" - " /dev/mbgclock0" - ); + 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 ); + + printf( " a device index, e.g. \"0\", \"1\",\"2\", ...\n" ); } // mbg_print_device_options /*HDR*/ +/** + * @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. + */ void mbg_print_default_usage( const char *pname, const char *prog_info ) { mbg_print_usage_intro( pname, prog_info ); @@ -159,30 +293,21 @@ void mbg_print_default_usage( const char *pname, const char *prog_info ) -// test if ioctl error and print msg if true - -/*HDR*/ -int mbg_ioctl_err( int rc, const char *descr ) -{ - if ( rc < 0 ) - { - fprintf( stderr, "** IOCTL error %i: ", rc ); - perror( descr ); - return -1; - } - - return 0; - -} // mbg_ioctl_err - - - /*HDR*/ +/** + * @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 + * + * @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 ) { + RECEIVER_INFO ri; unsigned long port; int irq_num; - int ret_val = 0; int rc; if ( dev_name ) @@ -191,31 +316,39 @@ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_ // get information about the device rc = mbg_get_device_info( dh, p_dev ); - if ( mbg_ioctl_err( rc, "mbg_get_device_info" ) ) - goto fail; + if ( mbg_cond_err_msg( rc, "mbg_get_device_info" ) ) + goto out; + + rc = mbg_setup_receiver_info( dh, p_dev, &ri ); + + if ( mbg_cond_err_msg( rc, "mbg_setup_receiver_info" ) ) + goto out; printf( "%s", _pcps_type_name( p_dev ) ); - if ( strlen( _pcps_sernum( p_dev ) ) && + if ( strlen( _pcps_sernum( p_dev ) ) && strcmp( _pcps_sernum( p_dev ), "N/A" ) ) printf( " %s", _pcps_sernum( p_dev ) ); - printf( " (FW %X.%02X", + 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 ) ) { PCI_ASIC_VERSION av; int rc = mbg_get_asic_version( dh, &av ); - if ( rc == MBG_SUCCESS ) + if ( mbg_rc_is_success( rc ) ) { - av = _convert_asic_version_number( av ); + av = _convert_asic_version_number( av ); // TODO Do we need this? - printf( ", ASIC %u.%02u", + printf( ", ASIC " PCPS_ASIC_STR_FMT, _pcps_asic_version_major( av ), _pcps_asic_version_minor( av ) ); @@ -224,12 +357,12 @@ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_ printf( ")" ); - port = _pcps_port_base( p_dev, 0 ); + port = _pcps_short_port_base( p_dev, 0 ); if ( port ) printf( " at port 0x%03lX", port ); - port = _pcps_port_base( p_dev, 1 ); + port = _pcps_short_port_base( p_dev, 1 ); if ( port ) printf( "/0x%03lX", port ); @@ -239,170 +372,462 @@ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_ if ( irq_num != -1 ) printf( ", irq %i", irq_num ); - goto done; + if ( _pcps_fw_has_20ms_bug( p_dev ) ) + printf( "\n** Warning: %s v" PCPS_FW_STR_FMT " has a 20 ms timing bug. Please upgrade the firmware!", + _pcps_type_name( p_dev ), + _pcps_fw_rev_num_major( _pcps_fw_rev_num( p_dev ) ), + _pcps_fw_rev_num_minor( _pcps_fw_rev_num( p_dev ) ) ); -fail: - ret_val = -1; + rc = MBG_SUCCESS; -done: - puts( "" ); - return ret_val; +out: + puts( str_empty ); + return rc; } // mbg_get_show_dev_info /*HDR*/ -int mbg_check_device( MBG_DEV_HANDLE dh, const char *dev_name, - int (*fnc)( MBG_DEV_HANDLE, const PCPS_DEV *) ) +/** + * @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 + */ +int mbg_handle_device( MBG_DEV_HANDLE dh, const char *dev_name, + MBG_DEV_HANDLER_FNC *fnc ) { PCPS_DEV dev; - int ret_val = 0; + int rc; - if ( dh == MBG_INVALID_DEV_HANDLE ) - { - if ( dev_name ) - fprintf( stderr, "%s: ", dev_name ); + rc = mbg_get_show_dev_info( dh, dev_name, &dev ); - perror( "Unable to open device" ); - return -1; - } + if ( mbg_rc_is_success( rc ) ) + if ( fnc ) + rc = fnc( dh, &dev ); - if ( mbg_get_show_dev_info( dh, dev_name, &dev ) < 0 ) - goto fail; + mbg_close_device( &dh ); - if ( fnc ) - ret_val = fnc( dh, &dev ); + puts( "" ); - goto done; + return rc; -fail: - ret_val = -1; +} // mbg_handle_device -done: - mbg_close_device( &dh ); - puts( "" ); - return ret_val; -} // mbg_check_device +/*HDR*/ +/** + * @brief Get the number of devices actually present + * + * Do a real search only when called for the first time. + * + * @return The number of devices currently present. + */ +int chk_get_num_devices( void ) +{ + static int num_devices; + static bool has_searched_devices; + + if ( !has_searched_devices ) + { + num_devices = mbg_find_devices(); + has_searched_devices = true; + } + + return num_devices; + +} // chk_get_num_devices /*HDR*/ -int mbg_check_devices( int argc, char *argv[], int optind, int (*fnc)( MBG_DEV_HANDLE, const PCPS_DEV *) ) +int mbg_open_device_by_param( MBG_DEV_HANDLE *p_dh, const char *dev_param_str, + int dev_idx, int devices_specified, + char *dev_name_buffer, size_t dev_name_buffer_size, + int chk_dev_flags ) { - MBG_DEV_HANDLE dh; - int ret_val = 0; - int num_devices = argc - optind; + MBG_DEV_HANDLE dh = MBG_INVALID_DEV_HANDLE; + int devices_found; + int rc = MBG_ERR_GENERIC; - if ( num_devices == 0 ) // no device name given on the command line + if ( dev_name_buffer == NULL || dev_name_buffer_size == 0 ) + return MBG_ERR_INV_PARM; + + dev_name_buffer[0] = 0; // Make string empty + + if ( dev_param_str ) { - // No devices specified on the command line, so - // try to find devices. - int devices = mbg_find_devices(); + // A device parameter string has been specified. + // This can be: + // - A device file name, see ::MBG_DEV_FN + // - A device model name like "GPS180PEX", eventually 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". + + char *endptr; + 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 ) + { + snprintf_safe( dev_name_buffer, dev_name_buffer_size, "%s", dev_param_str ); + dh = mbg_open_device_by_dev_fn( dev_param_str ); + goto out_chk; + } + #endif + + + // 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 + // whole string has been interpreted as number. + if ( endptr == &dev_param_str[strlen( dev_param_str )] ) + { + long l_max = (long) ( ( (unsigned int) -1 ) >> 1 ); + + if ( l > l_max ) + { + // The decoded number exceeds the maximum number + // that can be passed to ::mbg_open_device. + rc = MBG_ERR_RANGE; + goto out; + } + + // We use the decoded number as device index. + dev_idx = (int) l; + goto open_dev_with_idx; + } + + + // Finally assume the device name is a model name, eventually + // 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 ); + goto out_chk; + } + + + // No device has been specified on the command line. - if ( devices == 0 ) +#if 0 // TODO + if ( chk_dev_flags & CHK_DEV_WITHOUT_DEV ) + { + // 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. + if ( fnc ) + { + *p_dh = MBG_INVALID_DEV_HANDLE; + rc = fnc( *p_dh, NULL ); + } + else { - printf( "No device found.\n" ); - return 1; + // TODO Should we report an error if we have been called + // without callback function and without device? } + goto out; + } +#endif + + +open_dev_with_idx: + devices_found = chk_get_num_devices(); - // Handle only first device found. - dh = mbg_open_device( 0 ); - ret_val = mbg_check_device( dh, NULL, fnc ); + 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 ) ) + return MBG_ERR_NO_DEV; + + // We may continue even if no device is available, + // but have to process the callback loop only once. + devices_found = 1; } - else + + // Unless explicitly requested to handle all devices + // we have found, we only handle the first one. + if ( !( chk_dev_flags & CHK_DEV_ALL_DEVICES ) ) + devices_found = 1; + + + // Try to open the device with the specified index number. + mbg_dev_fn_from_dev_idx( dev_name_buffer, (int) dev_name_buffer_size, dev_idx ); + dh = mbg_open_device( dev_idx ); + +out_chk: + // Now check if the "open" function we've just called before + // was successful. + if ( dh == MBG_INVALID_DEV_HANDLE ) { - int i; - // One or more device names have been specified + char msg[256]; + int n = 0; + rc = mbg_get_last_error( NULL ); + + n = snprintf_safe( msg, sizeof( msg ), "** Failed to open device" ); + + if ( dev_name_buffer[0] ) // string not empty + n += snprintf_safe( &msg[n], sizeof( msg ) - n, " %s", dev_name_buffer ); + + n += snprintf_safe( &msg[n], sizeof( msg ) - n, ": %s", mbg_strerror( rc ) ); + fprintf( stderr, "%s\n\n", msg ); + goto out; + } + + rc = MBG_SUCCESS; + + +out: + *p_dh = dh; + + return rc; + +} // mbg_open_device_by_param + + + +/*HDR*/ +/** + * @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. + * + * Device specifiers can be device file names like "/dev/mbgclock0" on target + * platforms that support such device names, see ::MBG_DEV_FN, + * or device type names like "GPS180PEX" which can optionally have a serial + * number appended, like "GPS180PEX_029511026220", to be able to distinguish + * 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. + * + * 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 + * 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 + * + * @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 ) +{ + MBG_DEV_FN tmp_dev_fn; + MBG_DEV_HANDLE dh; + int devices_specified = argc - optind; + int devices_found = 0; + const char *dev_param_str = NULL; + int rc = MBG_ERR_NO_DEV; + int i; + + if ( devices_specified ) + { + // One or more device names have been specified // on the command line, so handle each device. for ( i = optind; i < argc; i++ ) { - // Print device name only if output for several devices - // shall be displayed. - const char *fn = ( num_devices > 1 ) ? argv[i] : NULL; - - #if defined( MBG_TGT_WIN32 ) - mbg_find_devices(); - dh = mbg_open_device_by_name( argv[i], MBG_MATCH_MODEL ); - #else - dh = open( argv[i], O_RDWR ); - #endif - ret_val = mbg_check_device( dh, fn, fnc ); - - if ( ret_val ) + dev_param_str = argv[i]; + + rc = mbg_open_device_by_param( &dh, dev_param_str, 0, devices_specified, + tmp_dev_fn, sizeof( tmp_dev_fn ), chk_dev_flags ); + + if ( mbg_rc_is_success( rc ) ) + rc = mbg_handle_device( dh, ( devices_specified > 1 ) ? tmp_dev_fn : NULL, fnc ); + + // Don't continue if one of the specified devices failed. + if ( mbg_rc_is_error( rc ) ) break; } + + goto out; } - return ret_val; -} // mbg_check_devices + // No device has been specified on the command line. + + if ( chk_dev_flags & CHK_DEV_WITHOUT_DEV ) + { + // 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. + if ( fnc ) + { + dh = MBG_INVALID_DEV_HANDLE; + rc = fnc( dh, NULL ); + } + else + { + // TODO Should we report an error if we have been called + // without callback function and without device? + } + goto out; + } + + + devices_found = chk_get_num_devices(); + + 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 + rc = MBG_ERR_NO_DEV; + goto out; + } + + // We may continue even if no device is available, + // but must process the callback loop only once. + devices_found = 1; + } + + // Unless explicitly requested to handle all devices + // we have found, we only handle the first one. + if ( !( chk_dev_flags & CHK_DEV_ALL_DEVICES ) ) + devices_found = 1; + + for ( i = 0; i < devices_found; i++ ) + { + rc = mbg_open_device_by_param( &dh, NULL, i, 0, tmp_dev_fn, + sizeof( tmp_dev_fn ), chk_dev_flags ); + + if ( mbg_rc_is_success( rc ) ) + rc = mbg_handle_device( dh, ( devices_found > 1 ) ? tmp_dev_fn : NULL, fnc ); + + // If one of the unspecified devices failed we continue anyway + // and don't break here. + } + + +out: + return rc; + +} // mbg_handle_devices /*HDR*/ -int mbg_snprint_date_time( char *s, int len_s, const PCPS_TIME *p, int verbose ) +/** + * @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 + * + * @return The number of characters printed to the buffer. + */ +int mbg_snprint_date_time( char *s, size_t max_len, const PCPS_TIME *p, int verbose ) { - int n = 0; + size_t n = 0; - n += snprintf( s + n, len_s - n, "%04u-%02u-%02u %02u:%02u:%02u.%02u", - pcps_exp_year( p->year, mbg_exp_year_limit ), p->month, p->mday, - p->hour, p->min, p->sec, p->sec100 - ); + 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, + p->hour, p->min, p->sec, p->sec100 ); - if ( verbose ) - n += snprintf( s + n, len_s - n, " (UTC%+ih), st: %02Xh", - p->offs_utc, p->status ); + if ( verbose > 0 ) + n += snprintf_safe( &s[n], max_len - n, " (UTC%+ih), st: %02Xh", + p->offs_utc, p->status ); - return n; + if ( verbose > 1 ) + n += snprintf_safe( &s[n], max_len - n, ", sig: %i", p->signal ); + + return _int_from_size_t( n ); } // mbg_snprint_date_time /*HDR*/ -int mbg_snprint_hr_tstamp( char *s, int len_s, const PCPS_TIME_STAMP *p, int show_raw ) +/** + * @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. + * @param[in] p Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. + * @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. + */ +int mbg_snprint_hr_tstamp( char *s, size_t max_len, const PCPS_TIME_STAMP *p, + long utc_offs, int show_raw ) { - int n = 0; + long l; + time_t t; + struct tm tm = { 0 }; + size_t n = 0; + int rc; + + if ( show_raw ) + n += snprintf_safe( &s[n], max_len - n, "raw: 0x%08lX.%08lX, ", + (ulong) p->sec, (ulong) p->frac ); // We'll use the standard C library functions to convert the seconds // to broken-down calendar date and time. - time_t t = p->sec; + l = (long) p->sec + utc_offs; + t = cvt_to_time_t( l ); // Our time stamp may be UTC, or have been converted to local time. - // Anyway, since we don't want to account for the system's time zone - // settings, we always use the gmtime() function for conversion: - struct tm *tmp = gmtime( &t ); - - if ( show_raw ) - n += snprintf( s + n, len_s - n, "raw: 0x%08lX.%08lX, ", - (ulong) p->sec, - (ulong) p->frac ); - - n += snprintf( s + n, len_s - n, "%04i-%02i-%02i %02i:%02i:%02i." PCPS_HRT_FRAC_SCALE_FMT, - tmp->tm_year + 1900, - tmp->tm_mon + 1, - tmp->tm_mday, - tmp->tm_hour, - tmp->tm_min, - tmp->tm_sec, - (ulong) frac_sec_from_bin( p->frac, PCPS_HRT_FRAC_SCALE ) - ); + // Anyway, since we don't want to account for the system's time zone + // settings, we always use the gmtime() function for conversion, + // or our own wrapper, respectively: + rc = mbg_gmtime( &tm, &t ); + + if ( mbg_rc_is_success( rc ) ) + n += snprintf_safe( &s[n], max_len - n, "%04i-%02i-%02i %02i:%02i:%02i." PCPS_HRT_FRAC_SCALE_FMT, + tm.tm_year + 1900, tm.tm_mon + 1, tm.tm_mday, + tm.tm_hour, tm.tm_min, tm.tm_sec, + (ulong) bin_frac_32_to_dec_frac( p->frac, PCPS_HRT_FRAC_SCALE ) ); + else + n += snprint_gmtime_error( &s[n], max_len - n, rc, t, __func__ ); - return n; + return _int_from_size_t( n ); } // mbg_snprint_hr_tstamp /*HDR*/ -int mbg_snprint_hr_time( char *s, int len_s, const PCPS_HR_TIME *p, int show_raw ) +/** + * @brief Print date and time from a ::PCPS_HR_TIME structure to a string + * + * 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. + * @param[in] max_len Size of the string buffer. + * @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. + */ +int mbg_snprint_hr_time( char *s, size_t max_len, const PCPS_HR_TIME *p, int show_raw ) { char ws[80]; PCPS_TIME_STAMP ts = p->tstamp; - int n; + size_t n; const char *time_scale_name; const char *cp; @@ -410,19 +835,7 @@ int mbg_snprint_hr_time( char *s, int len_s, const PCPS_HR_TIME *p, int show_raw // and set up a string telling the offset. if ( p->utc_offs ) { - ldiv_t ldt; - - ts.sec += p->utc_offs; - - // The local time offset is in seconds and may be negative, so we - // convert to absolute hours and minutes first. - ldt = ldiv( labs( p->utc_offs ) / 60, 60 ); - - snprintf( ws, sizeof( ws ), "%c%lu:%02luh", - ( p->utc_offs < 0 ) ? '-' : '+', - ldt.quot, - ldt.rem - ); + snprint_utc_offs( ws, sizeof( ws ), NULL, p->utc_offs ); cp = ws; } else @@ -430,7 +843,7 @@ int mbg_snprint_hr_time( char *s, int len_s, const PCPS_HR_TIME *p, int show_raw // Convert the local time stamp to calendar date and time. - n = mbg_snprint_hr_tstamp( s, len_s, &ts, show_raw ); + 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. time_scale_name = "UTC"; @@ -442,21 +855,41 @@ int mbg_snprint_hr_time( char *s, int len_s, const PCPS_HR_TIME *p, int show_raw if ( p->status & PCPS_SCALE_GPS ) time_scale_name = "GPS"; // time stamp represents GPS system time - n += snprintf( s + n, len_s - n, " %s%s", time_scale_name, cp ); + n += snprintf_safe( &s[n], max_len - n, " %s%s", time_scale_name, cp ); - return n; + return _int_from_size_t( n ); } // mbg_snprint_hr_time /*HDR*/ +/** + * @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 + * 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. + * + * @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 ) { char ws[80]; - mbg_snprint_hr_tstamp( ws, sizeof( ws ), p_ts, show_raw ); + mbg_snprint_hr_tstamp( ws, sizeof( ws ), p_ts, 0, show_raw ); printf( "HR time %s", ws ); if ( p_prv_ts ) @@ -465,13 +898,36 @@ void mbg_print_hr_timestamp( PCPS_TIME_STAMP *p_ts, int32_t hns_latency, PCPS_TI if ( !no_latency ) printf( ", latency: %.1f us", ( (double) hns_latency ) / 10 ); - puts( "" ); + puts( str_empty ); } // mbg_print_hr_timestamp /*HDR*/ +/** + * @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 + * 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> + * > 0: append status code<br> + * > 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 ) { @@ -486,9 +942,12 @@ void mbg_print_hr_time( PCPS_HR_TIME *p_ht, int32_t hns_latency, PCPS_TIME_STAMP if ( !no_latency ) printf( ", latency: %.1f us", ( (double) hns_latency ) / 10 ); - if ( verbose ) + if ( verbose > 0 ) printf( ", st: 0x%04lX", (ulong) p_ht->status ); + if ( verbose > 1 ) + printf( ", sig: %i", p_ht->signal ); + puts( "" ); } // mbg_print_hr_time @@ -496,7 +955,15 @@ void mbg_print_hr_time( PCPS_HR_TIME *p_ht, int32_t hns_latency, PCPS_TIME_STAMP /*HDR*/ -int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int show_corr_step ) +/** + * @brief Retrieve and 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 + * + * @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 ) { CORR_INFO ci; char ws[80]; @@ -504,7 +971,7 @@ int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int show_c int rc = mbg_get_corr_info( dh, &ci ); - if ( mbg_ioctl_err( rc, "mbg_get_corr_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_corr_info" ) ) return rc; @@ -512,12 +979,11 @@ int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int show_c cp = pzf_corr_state_name[ci.status]; else { - snprintf( ws, sizeof( ws ) - 1, "(unknown, code: 0x%02X)", ci.status ); - ws[sizeof( ws ) - 1] = 0; // force terminating 0 + snprintf_safe( ws, sizeof( ws ), "unknown status code: 0x%02X", ci.status ); cp = ws; } - printf( "PZF correlation: %u%%, status: %s", ci.val, cp ); + printf( "%s, PZF correlation: %u%%", cp, ci.val ); if ( show_corr_step ) if ( ci.corr_dir != ' ' ) @@ -528,3 +994,24 @@ int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int show_c } // mbg_show_pzf_corr_info + +/*HDR*/ +/** + * @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 + */ +int mbg_get_gps_gnss_mode_info_chk( MBG_DEV_HANDLE dh, MBG_GNSS_MODE_INFO *p ) +{ + int rc = mbg_get_gps_gnss_mode_info( dh, p ); + mbg_cond_err_msg( rc, "mbg_get_gps_gnss_mode_info" ); + + return rc; + +} // mbg_get_gps_gnss_mode_info_chk + + + diff --git a/mbglib/common/toolutil.h b/mbglib/common/toolutil.h index 2f02c73..60a48ae 100644 --- a/mbglib/common/toolutil.h +++ b/mbglib/common/toolutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: toolutil.h 1.3.1.1 2013/02/05 14:38:26Z martin TEST martin $ + * $Id: toolutil.h 1.6 2018/11/15 12:21:10Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,8 +10,18 @@ * * ----------------------------------------------------------------------- * $Log: toolutil.h $ - * Revision 1.3.1.1 2013/02/05 14:38:26Z martin - * Started to support Windows target. + * Revision 1.6 2018/11/15 12:21:10Z martin + * Updated function prototypes. + * Revision 1.5 2018/06/25 13:47:45 martin + * Updated function prototypes. + * Revision 1.4 2017/07/05 07:38:06 martin + * Support Windows target. + * Defined function type MBG_DEV_HANDLER_FNC. + * Defined some OS-specific strings e.g. for example + * file and device names used in help messages. + * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. + * Doxygen comments. + * Updated function prototypes. * Revision 1.3 2012/10/15 09:36:22 martin * Use common way to handle version information. * Added string table with PZF state names. @@ -34,7 +44,7 @@ #include <mbgdevio.h> #include <mbgversion.h> -#if defined( MBG_TGT_UNIX) +#if defined( MBG_TGT_POSIX ) #include <unistd.h> @@ -69,10 +79,38 @@ extern "C" { #endif + +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 +}; + + + +#if MBG_TGT_HAS_DEV_FN + #define EXAMPLE_DEV_FN_1 MBGCLOCK_DEV_FN_BASE "0" + #define EXAMPLE_DEV_FN_1_TCR EXAMPLE_DEV_FN_1 + #define EXAMPLE_DEV_FN_2 MBGCLOCK_DEV_FN_BASE "3" +#endif + +#define EXAMPLE_DEV_NAME_1 "gps180pex" +#define EXAMPLE_DEV_NAME_1_TCR "tcr167pci" +#define EXAMPLE_DEV_NAME_2 "tcr170pex_027911002000" + + +#if defined( MBG_TGT_POSIX ) + #define ROOT_PRIVILEGES_STR "with root privileges" +#else + #define ROOT_PRIVILEGES_STR "as administrator" +#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 @@ -81,6 +119,13 @@ _ext uint16_t mbg_exp_year_limit _ext int must_print_usage; +_ext const char str_empty[] +#ifdef _DO_INIT + = "" +#endif +; + + _ext const char *pzf_corr_state_name[N_PZF_CORR_STATE] #ifdef _DO_INIT = PZF_CORR_STATE_NAMES_ENG @@ -88,28 +133,277 @@ _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. + */ +typedef int MBG_DEV_HANDLER_FNC( MBG_DEV_HANDLE, const PCPS_DEV *); + + + +/** + * @brief Exit codes returned by the command line tools + */ +enum MBG_EXIT_CODES +{ + MBG_EXIT_CODE_SUCCESS, ///< Device handled successfully for requested action + MBG_EXIT_CODE_USAGE, ///< Device not handled successfully, usage printed + MBG_EXIT_CODE_NOT_SUPP, ///< Not supported on the running OS + MBG_EXIT_CODE_FAIL, ///< Action failed for device + MBG_EXIT_CODE_INV_TIME, ///< Device has no valid time to set the system time with + N_MBG_EXIT_CODES +}; + + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ - int mbg_program_info_str( char *s, size_t max_len, const char *pname, int micro_version, int first_year, int last_year ) ; - void mbg_print_program_info( const char *pname, int micro_version, int first_year, int last_year ) ; + /** + * @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. + * + * @return The number of characters printed to the buffer. + */ + int mbg_program_version_str( char *s, size_t max_len ) ; + + /** + * @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] micro_version Micro version code for the application. + * @param[in] first_year First copyright year. + * @param[in] last_year Last copyright year. + * + * @return The number of characters printed to the buffer. + */ + 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 + * + * @param[in] pname The program name. + * @param[in] micro_version Micro version code for the application. + * @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 + * + * @param[in] pname The program name. + * @param[in] info An optional additional info string, may be NULL. + */ void mbg_print_usage_intro( const char *pname, const char *info ) ; + + /** + * @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. + */ void mbg_print_opt_info( const char *opt_name, const char *opt_info ) ; + + /** + * @brief Print info on common program help arguments + * + * Lists program parameters causing printing + * of help / usage information. + */ void mbg_print_help_options( void ) ; + + /** + * @brief Print common info on how to specify devices on the command line + */ void mbg_print_device_options( void ) ; + + /** + * @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. + */ void mbg_print_default_usage( const char *pname, const char *prog_info ) ; - int mbg_ioctl_err( int rc, const char *descr ) ; + + /** + * @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 + * + * @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 ) ; - int mbg_check_device( MBG_DEV_HANDLE dh, const char *dev_name, int (*fnc)( MBG_DEV_HANDLE, const PCPS_DEV *) ) ; - int mbg_check_devices( int argc, char *argv[], int optind, int (*fnc)( MBG_DEV_HANDLE, const PCPS_DEV *) ) ; - int mbg_snprint_date_time( char *s, int len_s, const PCPS_TIME *p, int verbose ) ; - int mbg_snprint_hr_tstamp( char *s, int len_s, const PCPS_TIME_STAMP *p, int show_raw ) ; - int mbg_snprint_hr_time( char *s, int len_s, const PCPS_HR_TIME *p, int show_raw ) ; + + /** + * @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 + */ + 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 + * + * Do a real search only when called for the first time. + * + * @return The number of devices currently present. + */ + int chk_get_num_devices( void ) ; + + int mbg_open_device_by_param( MBG_DEV_HANDLE *p_dh, const char *dev_param_str, int dev_idx, int devices_specified, char *dev_name_buffer, size_t dev_name_buffer_size, int chk_dev_flags ) ; + /** + * @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. + * + * Device specifiers can be device file names like "/dev/mbgclock0" on target + * platforms that support such device names, see ::MBG_DEV_FN, + * or device type names like "GPS180PEX" which can optionally have a serial + * number appended, like "GPS180PEX_029511026220", to be able to distinguish + * 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. + * + * 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 + * 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 + * + * @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 + * + * @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 + * + * @return The number of characters printed to the buffer. + */ + 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 + * + * @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_STAMP structure to be evaluated. + * @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. + */ + 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 + * + * 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. + * @param[in] max_len Size of the string buffer. + * @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. + */ + 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 + * + * 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 + * 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. + * + * @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 + * + * 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 + * 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> + * > 0: append status code<br> + * > 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 ) ; - int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int show_corr_step ) ; + + /** + * @brief Retrieve and 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 + * + * @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 ) ; + + /** + * @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 + */ + int mbg_get_gps_gnss_mode_info_chk( MBG_DEV_HANDLE dh, MBG_GNSS_MODE_INFO *p ) ; + /* ----- function prototypes end ----- */ diff --git a/mbglib/common/usbdefs.h b/mbglib/common/usbdefs.h index 40d1193..4ca60ef 100644 --- a/mbglib/common/usbdefs.h +++ b/mbglib/common/usbdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: usbdefs.h 1.18 2013/01/24 11:29:21Z joerg REL_M $ + * $Id: usbdefs.h 1.37 2018/11/01 10:53:29Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,57 @@ * * ----------------------------------------------------------------------- * $Log: usbdefs.h $ - * Revision 1.18 2013/01/24 11:29:21Z joerg + * Revision 1.37 2018/11/01 10:53:29Z martin + * Added some missing device name strings. + * Revision 1.36 2018/10/30 12:22:26 paul.kretz + * Added definitions for BPE_STM + * Revision 1.35 2018/09/07 13:04:47Z philipp + * Added USB_DEV_GRC165 which, in fact, is USB_DEV_GNS165 + * Revision 1.34 2017/12/12 07:37:47 philipp + * Added definitions for SSP100 + * Revision 1.33 2017/09/19 12:30:17 martin + * Added definitions for TCR180USB. + * Revision 1.32 2017/09/15 08:25:48 paul.kretz + * Added Class code and device ID for PIO180. + * Revision 1.31 2017/09/13 14:14:27Z paul.kretz + * Added ID, name string and table entry for FCM180 + * Revision 1.30 2017/05/17 09:52:53Z thomas.fasse + * Device BITS was rennamed to LSG180. + * Revision 1.29 2017/05/16 07:19:40Z thomas.fasse + * Added ID, name string and table entry for LIU variant BITS by Paul + * Revision 1.28 2017/04/04 10:43:34Z paul.kretz + * Added ID, name string and table entry for FDM180M + * Added missing table entry for MicroSync power supply module + * Revision 1.27 2017/03/28 09:37:15Z paul.kretz + * Added ID, name string and table entry for MicroSync power supply module + * Revision 1.26 2017/02/13 09:57:45Z paul.kretz + * Added ID, name string and table entry for PZF180. + * Revision 1.25 2016/11/11 09:24:04Z lars.meihost + * Added ID, name string and table entry for TCR180. + * Revision 1.24 2016/11/04 11:49:15Z paul.kretz + * Added device ID and associated class code for MDU312 + * Revision 1.23 2016/09/26 07:28:10Z paul.kretz + * Added class code and device for N2X180 + * Revision 1.22 2016/07/06 13:55:15Z martin + * Definitions for IMS-SPT, REL1000, MDU300, and SDI added by stephan. + * Class code and device ID for LUE added by daniel-vdh. + * Class code and device ID for HPS added by daniel. + * Device IDs and associated class codes for SCG, FDM180, CPC180, + * VSG180, and GTS180 added by paul. + * Removed obsolete multiple definitions for FTDI serial interface chips. + * Added a new definition for unique FTDI chip. + * Added definitions for serial refclocks. + * Added definitions for LNE180SFP, GRC180 and GRC181. + * Added definitions USB_VENDOR_WILDCARD and USB_PROD_WILDCARD. + * Added device name string and string table initializers. + * Doxygen fixes. + * Revision 1.21 2014/01/16 15:26:09 daniel + * Added class codes and devices for USB to serial adapters and ASIX network chips + * Revision 1.20 2013/10/08 09:13:04 daniel + * Added definition and class code for RSC. + * Revision 1.19 2013/06/04 10:45:53 daniel + * Added class codes and device IDs for IMS devices MRI and BPE + * Revision 1.18 2013/01/24 11:29:21 joerg * Added class code and device ID for LNE-GB * Revision 1.17 2012/08/08 07:53:29Z daniel * Added class code and device ID for LIU @@ -65,73 +115,333 @@ extern "C" { #endif -/* Meinberg's USB vendor ID number (assigned by USB-IF Administration) */ +/** Meinberg's USB vendor ID number (assigned by USB-IF administration) */ #define USB_VENDOR_MEINBERG 0x1938 +#define USB_VENDOR_WILDCARD 0 +#define USB_PROD_WILDCARD 0 -/* - * USB device class codes (assigned by Meinberg) + +/** + * @brief USB device class codes assigned by Meinberg */ -enum +enum MBG_USB_CLASS_CODES { - MBG_USB_CLASS_NONE, // (unknown or not defined) - MBG_USB_CLASS_CPC, // Control Panel Controller - MBG_USB_CLASS_TSU, // Time Stamp Unit - MBG_USB_CLASS_DCF, // DCF77 Radio Clock - MBG_USB_CLASS_CMC, // nCipher Crypto Module Carrier - MBG_USB_CLASS_TCR, // IRIG Time Code Receiver - MBG_USB_CLASS_MSF, // MSF Radio Clock - MBG_USB_CLASS_WWVB, // WWVB Radio Clock - MBG_USB_CLASS_SCU, // Meinberg Signal Changeover Unit - MBG_USB_CLASS_ESI, // External Synchronization Interface - MBG_USB_CLASS_FCU, // Fan Control Unit - MBG_USB_CLASS_CPE, // Configurable Port Expander - MBG_USB_CLASS_GPS, // GPS Receiver - MBG_USB_CLASS_LNO, // Low Phase Noise Option - MBG_USB_CLASS_LIU, // Line Interface Unit - MBG_USB_CLASS_LNE, // LNE-GB - N_MBG_USB_CLASS // number of known device class codes + MBG_USB_CLASS_NONE, ///< (unknown or not defined) + MBG_USB_CLASS_CPC, ///< Control Panel Controller + MBG_USB_CLASS_TSU, ///< Time Stamp Unit + MBG_USB_CLASS_DCF, ///< DCF77 Radio Clock + MBG_USB_CLASS_CMC, ///< nCipher Crypto Module Carrier + MBG_USB_CLASS_TCR, ///< IRIG Time Code Receiver + MBG_USB_CLASS_MSF, ///< MSF Radio Clock + MBG_USB_CLASS_WWVB, ///< WWVB Radio Clock + + MBG_USB_CLASS_SCU, ///< Meinberg Signal Changeover Unit + MBG_USB_CLASS_ESI, ///< External Synchronization Interface + MBG_USB_CLASS_FCU, ///< Fan Control Unit + MBG_USB_CLASS_CPE, ///< Configurable Port Expander + MBG_USB_CLASS_GPS, ///< GPS Receiver + MBG_USB_CLASS_LNO, ///< Low Phase Noise Option + MBG_USB_CLASS_LIU, ///< Line Interface Unit + MBG_USB_CLASS_LNE, ///< LNE-GB + + MBG_USB_CLASS_MRI, ///< MRS Input card for IMS + MBG_USB_CLASS_BPE, ///< IMS Backplane Port Expander + MBG_USB_CLASS_RSC, ///< RSC Redundant Switch Control + MBG_USB_CLASS_SERIAL, ///< USB to Serial controller, FTDI chip connected to Meinberg serial device + 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_MDU, ///< Modular Distribution Unit + MBG_USB_CLASS_SPT, ///< Single Path Through + MBG_USB_CLASS_REL, ///< Relais Error Card + MBG_USB_CLASS_LUE, ///< Lantime USB Expansion + MBG_USB_CLASS_HPS, ///< High Performance Synchronization Card (PTP/NTP) + MBG_USB_CLASS_VSG, ///< Video Sync Generator + MBG_USB_CLASS_GTS, ///< Greenwich Time Signal + MBG_USB_CLASS_GRC, ///< GNSS receivers (GPS, GLONASS, ... ) + + MBG_USB_CLASS_N2X, ///< NTP/PTP receiver + MBG_USB_CLASS_USYNC, ///< MicroSync + MBG_USB_CLASS_FCM, ///< Fake Clock Module + MBG_USB_CLASS_PIO, ///< Programmable Input/Output Module + + N_MBG_USB_CLASS ///< number of known Meinberg USB device class codes }; -/* - * USB device ID numbers (assigned by Meinberg) - * High byte: USB device class as specified above - * Low byte: enumeration of device of a class +/** + * @brief USB device ID numbers assigned by Meinberg + * + * High byte: USB device class, see ::MBG_USB_CLASS_CODES<br> + * Low byte: enumeration of devices of a class + * + * @see @ref MBG_USB_DEVICE_NAMES + * @see ::DEFAULT_MBG_USB_DEVICE_NAMES + * @see ::MBG_USB_CLASS_CODES + * + * @anchor MBG_USB_DEVICE_IDS @{ + */ + +// If new devices are defined here then 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 ) +#define USB_DEV_CPC180 ( ( MBG_USB_CLASS_CPC << 8 ) | 0x02 ) + +#define USB_DEV_TSU_01 ( ( MBG_USB_CLASS_TSU << 8 ) | 0x01 ) + +#define USB_DEV_USB5131 ( ( MBG_USB_CLASS_DCF << 8 ) | 0x01 ) +#define USB_DEV_DCF600USB ( ( MBG_USB_CLASS_DCF << 8 ) | 0x02 ) +#define USB_DEV_PZF180 ( ( MBG_USB_CLASS_DCF << 8 ) | 0x03 ) + +#define USB_DEV_CMC ( ( MBG_USB_CLASS_CMC << 8 ) | 0x01 ) + +#define USB_DEV_TCR51USB ( ( MBG_USB_CLASS_TCR << 8 ) | 0x01 ) +#define USB_DEV_TCR600USB ( ( MBG_USB_CLASS_TCR << 8 ) | 0x02 ) +#define USB_DEV_TCR180 ( ( MBG_USB_CLASS_TCR << 8 ) | 0x03 ) +#define USB_DEV_TCR180USB ( ( MBG_USB_CLASS_TCR << 8 ) | 0x04 ) + +#define USB_DEV_MSF51USB ( ( MBG_USB_CLASS_MSF << 8 ) | 0x01 ) +#define USB_DEV_MSF600USB ( ( MBG_USB_CLASS_MSF << 8 ) | 0x02 ) + +#define USB_DEV_WWVB51USB ( ( MBG_USB_CLASS_WWVB << 8 ) | 0x01 ) +#define USB_DEV_WVB600USB ( ( MBG_USB_CLASS_WWVB << 8 ) | 0x02 ) + +#define USB_DEV_SCU_USB ( ( MBG_USB_CLASS_SCU << 8 ) | 0x01 ) + +#define USB_DEV_ESI_01 ( ( MBG_USB_CLASS_ESI << 8 ) | 0x01 ) + +#define USB_DEV_FCU_01 ( ( MBG_USB_CLASS_FCU << 8 ) | 0x01 ) + +#define USB_DEV_CPE_01 ( ( MBG_USB_CLASS_CPE << 8 ) | 0x01 ) + +#define USB_DEV_GPS180 ( ( MBG_USB_CLASS_GPS << 8 ) | 0x01 ) + +#define USB_DEV_LNO180 ( ( MBG_USB_CLASS_LNO << 8 ) | 0x01 ) + +#define USB_DEV_LIU_01 ( ( MBG_USB_CLASS_LIU << 8 ) | 0x01 ) +#define USB_DEV_LSG180 ( ( MBG_USB_CLASS_LIU << 8 ) | 0x02 ) + +#define USB_DEV_LNE_01 ( ( MBG_USB_CLASS_LNE << 8 ) | 0x01 ) // LNE with standard copper +#define USB_DEV_LNE180SFP ( ( MBG_USB_CLASS_LNE << 8 ) | 0x02 ) // LNE with SFP (fiber optic) + +#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_RSC_01 ( ( MBG_USB_CLASS_RSC << 8 ) | 0x01 ) + +#define USB_DEV_SPT_01 ( ( MBG_USB_CLASS_SPT << 8 ) | 0x01 ) + +#define USB_DEV_REL_01 ( ( MBG_USB_CLASS_REL << 8 ) | 0x01 ) + +/// LANTIME CPU quad FTDI serial interface chip +#define USB_DEV_LAN_CPU_SERIAL ( ( MBG_USB_CLASS_SERIAL << 8 ) | 0x01 ) + +#define USB_DEV_SCG_01 ( ( MBG_USB_CLASS_SCG << 8 ) | 0x01 ) + +#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_MDU300 ( ( MBG_USB_CLASS_MDU << 8 ) | 0x01 ) +#define USB_DEV_MDU312 ( ( MBG_USB_CLASS_MDU << 8 ) | 0x02 ) + +#define USB_DEV_LUE_01 ( ( MBG_USB_CLASS_LUE << 8 ) | 0x01 ) + +#define USB_DEV_HPS100 ( ( MBG_USB_CLASS_HPS << 8 ) | 0x01 ) +#define USB_DEV_SSP100 ( ( MBG_USB_CLASS_HPS << 8 ) | 0x02 ) + +#define USB_DEV_VSG180 ( ( MBG_USB_CLASS_VSG << 8 ) | 0x01 ) + +#define USB_DEV_GTS180 ( ( MBG_USB_CLASS_GTS << 8 ) | 0x01 ) + +// Eventually these GRC* devices should be named GNS*. +#define USB_DEV_GRC180 ( ( MBG_USB_CLASS_GRC << 8 ) | 0x01 ) +#define USB_DEV_GRC181 ( ( MBG_USB_CLASS_GRC << 8 ) | 0x02 ) +#define USB_DEV_GRC165 ( ( MBG_USB_CLASS_GRC << 8 ) | 0x03 ) + +#define USB_DEV_N2X180 ( ( MBG_USB_CLASS_N2X << 8 ) | 0x01 ) + +#define USB_DEV_USYNCPWR ( ( MBG_USB_CLASS_USYNC << 8 ) | 0x01 ) ///< MicroSync Power Supply Module + +#define USB_DEV_FCM180 ( ( MBG_USB_CLASS_FCM << 8 ) | 0x01 ) ///< Fake Clock Module + +#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 +// be added to MBG_USB_DEVICE_NAMES and DEFAULT_MBG_USB_DEVICE_NAMES. + +/** @} anchor MBG_USB_DEVICE_IDS */ + + + +/** + * @brief Device name strings for Meinberg USB devices + * + * @see @ref MBG_USB_DEVICE_IDS + * @see ::DEFAULT_MBG_USB_DEVICE_NAMES + * + * @anchor MBG_USB_DEVICE_NAMES @{ */ -#define USB_DEV_CPC_01 ( ( MBG_USB_CLASS_CPC << 8 ) | 0x01 ) -#define USB_DEV_TSU_01 ( ( MBG_USB_CLASS_TSU << 8 ) | 0x01 ) +#define USB_DEV_NAME_CPC_01 "CPC_01" +#define USB_DEV_NAME_CPC180 "CPC180" + +#define USB_DEV_NAME_TSU_01 "TSU_01" + +#define USB_DEV_NAME_USB5131 "USB5131" +#define USB_DEV_NAME_DCF600USB "DCF600USB" +#define USB_DEV_NAME_PZF180 "PZF180" + +#define USB_DEV_NAME_CMC "CMC" + +#define USB_DEV_NAME_TCR51USB "TCR51USB" +#define USB_DEV_NAME_TCR600USB "TCR600USB" +#define USB_DEV_NAME_TCR180 "TCR180" +#define USB_DEV_NAME_TCR180USB "TCR180USB" + +#define USB_DEV_NAME_MSF51USB "MSF51USB" +#define USB_DEV_NAME_MSF600USB "MSF600USB" + +#define USB_DEV_NAME_WWVB51USB "WWVB51USB" +#define USB_DEV_NAME_WVB600USB "WVB600USB" + +#define USB_DEV_NAME_SCU_USB "SCU_USB" + +#define USB_DEV_NAME_ESI_01 "ESI_01" + +#define USB_DEV_NAME_FCU_01 "FCU_01" + +#define USB_DEV_NAME_CPE_01 "CPE_01" + +#define USB_DEV_NAME_GPS180 "GPS180" -#define USB_DEV_USB5131 ( ( MBG_USB_CLASS_DCF << 8 ) | 0x01 ) -#define USB_DEV_DCF600USB ( ( MBG_USB_CLASS_DCF << 8 ) | 0x02 ) +#define USB_DEV_NAME_LNO180 "LNO180" -#define USB_DEV_CMC ( ( MBG_USB_CLASS_CMC << 8 ) | 0x01 ) +#define USB_DEV_NAME_LIU_01 "LIU_01" +#define USB_DEV_NAME_LSG180 "LSG180" -#define USB_DEV_TCR51USB ( ( MBG_USB_CLASS_TCR << 8 ) | 0x01 ) -#define USB_DEV_TCR600USB ( ( MBG_USB_CLASS_TCR << 8 ) | 0x02 ) +#define USB_DEV_NAME_LNE_01 "LNE_01" +#define USB_DEV_NAME_LNE180SFP "LNE180SFP" -#define USB_DEV_MSF51USB ( ( MBG_USB_CLASS_MSF << 8 ) | 0x01 ) -#define USB_DEV_MSF600USB ( ( MBG_USB_CLASS_MSF << 8 ) | 0x02 ) +#define USB_DEV_NAME_MRI_01 "MRI_01" -#define USB_DEV_WWVB51USB ( ( MBG_USB_CLASS_WWVB << 8 ) | 0x01 ) -#define USB_DEV_WVB600USB ( ( MBG_USB_CLASS_WWVB << 8 ) | 0x02 ) +#define USB_DEV_NAME_BPE_01 "BPE_01" +#define USB_DEV_NAME_BPE_STM "BPE" -#define USB_DEV_SCU_USB ( ( MBG_USB_CLASS_SCU << 8 ) | 0x01 ) +#define USB_DEV_NAME_RSC_01 "RSC_01" -#define USB_DEV_ESI_01 ( ( MBG_USB_CLASS_ESI << 8 ) | 0x01 ) +#define USB_DEV_NAME_SPT_01 "SPT_01" -#define USB_DEV_FCU_01 ( ( MBG_USB_CLASS_FCU << 8 ) | 0x01 ) +#define USB_DEV_NAME_REL_01 "REL_01" -#define USB_DEV_CPE_01 ( ( MBG_USB_CLASS_CPE << 8 ) | 0x01 ) +#define USB_DEV_NAME_LAN_CPU_SERIAL "LAN_CPU_SERIAL" -#define USB_DEV_GPS180 ( ( MBG_USB_CLASS_GPS << 8 ) | 0x01 ) +#define USB_DEV_NAME_SCG_01 "SCG_01" -#define USB_DEV_LNO180_01 ( ( MBG_USB_CLASS_LNO << 8 ) | 0x01 ) +#define USB_DEV_NAME_SDI_01 "SDI_01" + +#define USB_DEV_NAME_FDM180 "FDM180" +#define USB_DEV_NAME_FDM180M "FDM180M" + +#define USB_DEV_NAME_MDU300 "MDU300" +#define USB_DEV_NAME_MDU312 "MDU312" + +#define USB_DEV_NAME_LUE_01 "LUE_01" + +#define USB_DEV_NAME_HPS100 "HPS100" +#define USB_DEV_NAME_SSP100 "SSP100" + +#define USB_DEV_NAME_VSG180 "VSG180" + +#define USB_DEV_NAME_GTS180 "GTS180" + +#define USB_DEV_NAME_GRC180 "GRC180" +#define USB_DEV_NAME_GRC181 "GRC181" +#define USB_DEV_NAME_GRC165 "GRC165" + +#define USB_DEV_NAME_N2X180 "N2X180" + +#define USB_DEV_NAME_USYNCPWR "MICROSYNC-PWR" + +#define USB_DEV_NAME_FCM180 "FCM180" + +#define USB_DEV_NAME_PIO180 "PIO180" + +/** @} anchor MBG_USB_DEVICE_NAMES */ + + + +/** + * @brief Initializer for a table of USB device IDs and name strings + * + * Can be used e.g. to initialize an array of ::MBG_CODE_NAME_TABLE_ENTRY. + * + * @see @ref MBG_USB_DEVICE_IDS + * @see @ref MBG_USB_DEVICE_NAMES + */ +#define DEFAULT_MBG_USB_DEVICE_NAMES \ +{ \ + { USB_DEV_CPC_01, USB_DEV_NAME_CPC_01 }, \ + { USB_DEV_CPC180, USB_DEV_NAME_CPC180 }, \ + { USB_DEV_TSU_01, USB_DEV_NAME_TSU_01 }, \ + { USB_DEV_USB5131, USB_DEV_NAME_USB5131 }, \ + { USB_DEV_DCF600USB, USB_DEV_NAME_DCF600USB }, \ + { USB_DEV_CMC, USB_DEV_NAME_CMC }, \ + { USB_DEV_TCR51USB, USB_DEV_NAME_TCR51USB }, \ + { USB_DEV_TCR600USB, USB_DEV_NAME_TCR600USB }, \ + { USB_DEV_TCR180, USB_DEV_NAME_TCR180 }, \ + { USB_DEV_MSF51USB, USB_DEV_NAME_MSF51USB }, \ + { USB_DEV_MSF600USB, USB_DEV_NAME_MSF600USB }, \ + { USB_DEV_WWVB51USB, USB_DEV_NAME_WWVB51USB }, \ + { USB_DEV_WVB600USB, USB_DEV_NAME_WVB600USB }, \ + { USB_DEV_SCU_USB, USB_DEV_NAME_SCU_USB }, \ + { USB_DEV_ESI_01, USB_DEV_NAME_ESI_01 }, \ + { USB_DEV_FCU_01, USB_DEV_NAME_FCU_01 }, \ + { USB_DEV_CPE_01, USB_DEV_NAME_CPE_01 }, \ + { USB_DEV_GPS180, USB_DEV_NAME_GPS180 }, \ + { USB_DEV_LNO180, USB_DEV_NAME_LNO180 }, \ + { USB_DEV_LIU_01, USB_DEV_NAME_LIU_01 }, \ + { USB_DEV_LNE_01, USB_DEV_NAME_LNE_01 }, \ + { USB_DEV_MRI_01, USB_DEV_NAME_MRI_01 }, \ + { USB_DEV_BPE_01, USB_DEV_NAME_BPE_01 }, \ + { USB_DEV_RSC_01, USB_DEV_NAME_RSC_01 }, \ + { USB_DEV_SPT_01, USB_DEV_NAME_SPT_01 }, \ + { USB_DEV_REL_01, USB_DEV_NAME_REL_01 }, \ + { USB_DEV_LAN_CPU_SERIAL, USB_DEV_NAME_LAN_CPU_SERIAL }, \ + { USB_DEV_SCG_01, USB_DEV_NAME_SCG_01 }, \ + { USB_DEV_SDI_01, USB_DEV_NAME_SDI_01 }, \ + { USB_DEV_FDM180, USB_DEV_NAME_FDM180 }, \ + { USB_DEV_MDU300, USB_DEV_NAME_MDU300 }, \ + { USB_DEV_LUE_01, USB_DEV_NAME_LUE_01 }, \ + { USB_DEV_HPS100, USB_DEV_NAME_HPS100 }, \ + { USB_DEV_VSG180, USB_DEV_NAME_VSG180 }, \ + { USB_DEV_LNE180SFP, USB_DEV_NAME_LNE180SFP }, \ + { USB_DEV_GTS180, USB_DEV_NAME_GTS180 }, \ + { USB_DEV_GRC180, USB_DEV_NAME_GRC180 }, \ + { USB_DEV_GRC181, USB_DEV_NAME_GRC181 }, \ + { USB_DEV_N2X180, USB_DEV_NAME_N2X180 }, \ + { USB_DEV_MDU312, USB_DEV_NAME_MDU312 }, \ + { USB_DEV_PZF180, USB_DEV_NAME_PZF180 }, \ + { USB_DEV_USYNCPWR, USB_DEV_NAME_USYNCPWR }, \ + { USB_DEV_FDM180M, USB_DEV_NAME_FDM180M }, \ + { USB_DEV_LSG180, USB_DEV_NAME_LSG180 }, \ + { USB_DEV_FCM180, USB_DEV_NAME_FCM180 }, \ + { USB_DEV_PIO180, USB_DEV_NAME_PIO180 }, \ + { USB_DEV_TCR180USB, USB_DEV_NAME_TCR180USB }, \ + { USB_DEV_SSP100, USB_DEV_NAME_SSP100 }, \ + { USB_DEV_GRC165, USB_DEV_NAME_GRC165 }, \ + { USB_DEV_BPE_STM, USB_DEV_NAME_BPE_STM }, \ + { 0, /* end of table */ NULL } \ +} -#define USB_DEV_LIU_01 ( ( MBG_USB_CLASS_LIU << 8 ) | 0x01 ) -#define USB_DEV_LNE_01 ( ( MBG_USB_CLASS_LNE << 8 ) | 0x01 ) enum { diff --git a/mbglib/common/words.h b/mbglib/common/words.h index b840491..48812cc 100644 --- a/mbglib/common/words.h +++ b/mbglib/common/words.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: words.h 1.31 2012/11/29 11:54:39Z martin REL_M $ + * $Id: words.h 1.45 2018/11/22 16:38:15Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,45 @@ * * ----------------------------------------------------------------------- * $Log: words.h $ + * Revision 1.45 2018/11/22 16:38:15Z martin + * Removed inclusion of mbg_no_tgt.h which is obsolete here. + * Revision 1.44 2018/06/25 09:21:02 martin + * Support MBG_TGT_NO_TGT. + * Improved STRINGIFY() macro. + * Revision 1.43 2018/01/29 10:30:23 martin + * Modified some comments. + * Revision 1.42 2017/07/26 14:28:50Z martin + * Fixed build for NetBSD. + * Revision 1.41 2017/07/05 12:06:35 martin + * Moved macro _int_from_size_t() here. + * Revision 1.40 2017/06/12 11:14:25 martin + * Empty _DEPRECATED_BY definition for firmware targets. + * Revision 1.39 2017/03/15 10:01:09 martin + * Added comments how to represent negative numbers in NANO_TIME + * and NANO_TIME_64 structures. + * Added macros _nano_time_zero() and _nano_time_64_zero(). + * Revision 1.38 2017/02/22 11:56:33 martin + * Made MBG_CODE_NAME_TABLE_ENTRY::code signed to + * avoid signed/unsigned warnings with some code tables. + * Revision 1.37 2017/01/27 12:24:35Z martin + * Moved STRINGIFY() macro here. + * Revision 1.36 2017/01/27 08:59:43 martin + * Fixed macro syntax. + * Revision 1.35 2016/08/05 12:17:21 martin + * Moved definitions for NANO_TIME and NANO_TIME_64 here. + * New macro _nano_time_64_negative(). + * Conditionally define _abs64() macro. + * Include <inttypes.h> for Keil ARMCC target. + * Added some conditional debugging code. + * Fixed some spelling. + * Revision 1.34 2014/10/20 12:31:20 martin + * Moved macro _isdigit() here. + * Revision 1.33 2014/05/27 10:18:35Z martin + * Finer control of which types are required for or already + * available on particular target systems. + * Added macros helpful to simplify declarations of code/name tables. + * Revision 1.32 2014/01/07 15:43:52 martin + * Define __mbg_inline for ARM firmware targets. * Revision 1.31 2012/11/29 11:54:39Z martin * Removed #if sizeof() definitions which may cause build errors * with some older compilers. @@ -113,12 +152,18 @@ #include <mbg_tgt.h> #else #if defined( __ARMCC_VERSION ) // Keil RealView Compiler for ARM + #define __mbg_inline __inline #include <stdint.h> + #include <inttypes.h> #include <stdbool.h> #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 #else #define MBG_TGT_MISSING_64_BIT_TYPES 1 #endif + + #if !defined( _DEPRECATED_BY ) + #define _DEPRECATED_BY( _s ) // empty definition + #endif #endif @@ -185,9 +230,9 @@ #if defined( MBG_TGT_MISSING_64_BIT_TYPES ) // The build environment does not support 64 bit types. However, - // 64 bit types need to be defined to avoid build errors + // 64 bit types need to be defined to avoid build errors e.g. // if these types are formally used in function prototypes. - // We explicitely use abnormal data types to hopefully + // We explicitly use abnormal data types to hopefully // cause compiler errors in case these types are // unexpectedly used to generate real code for a target // platform which does not support 64 bit types. @@ -197,8 +242,8 @@ #else // Define C99 types using non-standard exact-size types - // which are usually supported by build envonronments - // supporting 64 bit types but no C99 types. + // which are usually supported by build environments that + // support 64 bit types but don't support C99 types. typedef __int64 int64_t; typedef unsigned __int64 uint64_t; @@ -216,67 +261,177 @@ #define MBG_TGT_HAS_64BIT_TYPES 1 + #if !defined( MBG_TGT_HAS_ABS64 ) + #define _abs64( _i ) ( (int64_t) ( ( (_i) < 0 ) ? -(_i) : (_i) ) ) + #endif + #endif // Some commonly used types -typedef unsigned char uchar; +#if !defined( _UCHAR_DEFINED ) + typedef unsigned char uchar; + #define uchar uchar +#endif -#if !defined( MBG_TGT_LINUX ) \ - && !( defined ( MBG_TGT_NETBSD ) \ - && defined ( MBG_TGT_KERNEL ) ) +#if !defined( _USHORT_DEFINED ) typedef unsigned short ushort; + #define ushort ushort +#endif + +#if !defined( _UINT_DEFINED ) typedef unsigned int uint; + #define uint uint +#endif + +#if !defined( _ULONG_DEFINED ) typedef unsigned long ulong; + #define ulong ulong #endif -typedef double udouble; +#if !defined( _UDOUBLE_DEFINED ) + typedef double udouble; + #define udouble udouble +#endif -typedef unsigned char byte; -typedef unsigned short word; -typedef unsigned long longword; -typedef unsigned long dword; +#if !defined( _BYTE_DEFINED ) + typedef unsigned char byte; + #define byte byte +#endif +#if !defined( _WORD_DEFINED ) + typedef unsigned short word; + #define word word +#endif -#if !defined( _BIT_DEFINED ) +#if !defined( _LONGWORD_DEFINED ) + typedef unsigned long longword; + #define longword longword +#endif + +#if !defined( _DWORD_DEFINED ) +// typedef unsigned long dword; +// #define dword dword +#endif + + +#if defined( MBG_TGT_MISSING_BOOL_TYPE ) + //#error MBG_TGT_MISSING_BOOL_TYPE is defined + // BDS/Borland C++ Builder 2006 (non-C++ mode) + // Borland C++ Builder 5 (non-C++ mode) + // BC 3.1 + // VC6 + // DDKbuild + // VS2008 +#endif - // We need to implement a "bit" type. Preferably we use "bool" - // to do this, but this is only supported by C++ compilers, and - // by C compilers supporting the C99 standard. +#if defined( __cplusplus ) + //#error __cplusplus is defined +#endif - #if !defined( MBG_TGT_MISSING_BOOL_TYPE ) && \ - ( defined( __cplusplus ) || defined( __bool_true_false_are_defined ) ) +#if defined( __bool_true_false_are_defined ) + //#error __bool_true_false_are_defined is defined + // Keil armcc + // gcc / Linux user space + // clang / FreeBSD user space and kernel +#endif - typedef bool bit; - #else // C99 types not supported +#if defined( MBG_TGT_MISSING_BOOL_TYPE ) /* from mbg_tgt.h */ \ + || ( !defined( __cplusplus ) /* C++ */ \ + && !defined( __bool_true_false_are_defined ) /* C99 */ \ + && !defined( _LINUX_TYPES_H ) ) /* Linux kernel */ \ + && !( defined( MBG_TGT_NETBSD ) && defined( _SYS_TYPES_H_ ) ) /* NetBSD kernel */ - // Falling back to use "int" for "bit". This prevents error - // messages if "bit" is used in function prototypes, but may - // yield unexpected results for code like: - // return (bit) ( val & 0x10 ); - typedef int bit; + // There's no native support for a "bool" type, so we + // need a substitute. + #if defined( _BIT_DEFINED ) + // A native "bit" type is supported, so we use it for bool. + //#error substituting bit for bool + // C166 + typedef bit bool; + #else + // Fall back to "int". This is just a hack which + // may yield unexpected results with code like: + // return (bool) ( val & 0x10 ); + // A safe way of coding would be: + // return (bool) ( ( val & 0x10 ) != 0 ); + //#error substituting int for bool + // Borland C++ Builder 5 + // BC 3.1 + // VC6 + // DDKbuild + // VS2008 + typedef int bool; #endif + // Eventually provoke a build error if the build + // environment unexpectedly supports "bool" natively. + #define bool bool + #define true 1 + #define false 0 +#else + //#error native bool type supported + // Borland C++ Builder 5 and newer (C++ mode only) + // Keil armcc + // gcc / Linux user space + // gcc / Linux kernel + // clang / FreeBSD user space and kernel +#endif + + +#if !defined( _BIT_DEFINED ) + + // There's no native support for a "bit" type, so we + // need a substitute. The "bool" type would fit best + // 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 + // unexpected results with code like: + // return (bit) ( val & 0x10 ); + // A safe way of coding would be: + // return (bit) ( ( val & 0x10 ) != 0 ); + + //#error substituting bool for bit + // Keil armcc + // Borland C++ Builder 5 + // BC 3.1 + // VC6 + // DDKbuild + // VS2008 + // gcc / Linux user space + // gcc / Linux kernel + // clang / FreeBSD user space and kernel + typedef bool bit; + + // Eventually provoke a build error if the build + // environment unexpectedly supports "bit" natively. + #define bit bit + #define _BIT_REDEFINED 1 +#else + //#error native bit type supported + // C166 #endif -#define BYTE_0( _x ) ( ( (ulong) (_x) ) & 0xFF ) -#define BYTE_1( _x ) ( ( ( (ulong) (_x) ) >> 8 ) & 0xFF ) -#define BYTE_2( _x ) ( ( ( (ulong) (_x) ) >> 16 ) & 0xFF ) -#define BYTE_3( _x ) ( ( ( (ulong) (_x) ) >> 24 ) & 0xFF ) + +#define BYTE_0( _x ) ( (uint8_t ) ( (_x) & 0xFF ) ) +#define BYTE_1( _x ) ( (uint8_t ) ( ( ( (uint16_t) (_x) ) >> 8 ) & 0xFF ) ) +#define BYTE_2( _x ) ( (uint8_t ) ( ( ( (uint32_t) (_x) ) >> 16 ) & 0xFF ) ) +#define BYTE_3( _x ) ( (uint8_t ) ( ( ( (uint32_t) (_x) ) >> 24 ) & 0xFF ) ) -#define HI_BYTE( _x ) ( (_x) >> 8 ) -#define LO_BYTE( _x ) ( (_x) & 0xFF ) +#define HI_BYTE( _x ) ( (uint8_t ) ( (_x) >> 8 ) ) +#define LO_BYTE( _x ) ( (uint8_t ) ( (_x) & 0xFF ) ) -#define HI_WORD( _x ) ( (_x) >> 16 ) -#define LO_WORD( _x ) ( (_x) & 0xFFFF ) +#define HI_WORD( _x ) ( (uint16_t ) ( (_x) >> 16 ) ) +#define LO_WORD( _x ) ( (uint16_t ) ( (_x) & 0xFFFF ) ) // the macros below assume little endianess // these macros expect the name of a variable @@ -333,9 +488,36 @@ typedef unsigned long dword; #endif + +#define _set_array_bit( _n, _byte_array, _max_bytes ) \ +do \ +{ \ + int byte_idx = (_n) >> 3; \ + \ + if ( byte_idx < _max_bytes ) \ + _byte_array[byte_idx] |= ( 1 << ( (_n) & 0x07 ) ); \ + \ +} while ( 0 ) + + +#define _clear_array_bit( _n, _byte_array, _max_bytes ) \ +do \ +{ \ + int byte_idx = (_n) >> 3; \ + \ + if ( byte_idx < _max_bytes ) \ + _byte_array[byte_idx] &= ~( 1 << ( (_n) & 0x07 ) ); \ + \ +} while ( 0 ) + + + +#define _isdigit( _c ) ( (_c) >= '0' && (_c) <= '9' ) + + // A macro function which can safely be used without // side effects as a macro doing nothing. -// This is useful to define debug macros away in +// This is useful to define debug macros away in // release builds, etc. #if !defined( _nop_macro_fnc ) #define _nop_macro_fnc() do {} while (0) @@ -347,10 +529,172 @@ typedef unsigned long dword; */ typedef struct { - ulong code; + long code; const char *name; + } MBG_CODE_NAME_TABLE_ENTRY; +/** + * @brief A macro defining a ::MBG_CODE_NAME_TABLE_ENTRY + * + * The stringified parameter is used for the name. + * + * @param _n The symbolic name of the numeric code + */ +#define _mbg_cn_table_entry( _n ) { _n, #_n } + +/** + * @brief A macro defining an empty ::MBG_CODE_NAME_TABLE_ENTRY + * + * This is used to terminate a table. + */ +#define _mbg_cn_table_end() { 0, NULL } + + + +/** + * @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. + * 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. + * 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 + * if used for the number of seconds since 1970-01-01, just like + * 32 bit POSIX time_t. + * + * @see ::_nano_time_negative + * @see ::_nano_time_zero + * @see ::NANO_TIME_64 + */ +typedef struct +{ + // ATTENTION: + // This structure is and has 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 + +} NANO_TIME; + +#define _mbg_swab_nano_time( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->nano_secs ); \ + _mbg_swab32( &(_p)->secs ); \ +} while ( 0 ) + +/** + * 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 + */ +#define _nano_time_zero( _nt ) \ + ( ( (_nt)->secs == 0 ) && ( (_nt)->nano_secs == 0 ) ) + + + +/** + * @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. + * 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. + * The macro ::_nano_time_64_negative should always be used to determine + * if the sign of the represented value is negative, or not. + * + * @see ::_nano_time_64_negative + * @see ::_nano_time_64_zero + * @see ::NANO_TIME + */ +typedef struct +{ + // 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 + // 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] + +} NANO_TIME_64; + +#define _mbg_swab_nano_time_64( _p ) \ +do \ +{ \ + _mbg_swab64( &(_p)->secs ); \ + _mbg_swab64( &(_p)->nano_secs ); \ +} while ( 0 ) + +/** + * 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 + */ +#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. +// 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 +// to MAXINT. +#if defined( MBG_TGT_WIN32 ) + #define _int_from_size_t( _n ) \ + ( ( (_n) > INT_MAX ) ? INT_MAX : (int) (_n) ) +#else + #define _int_from_size_t( _n ) (_n) +#endif + + + +/** + * @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. + * + * @see ::STRINGIFY + */ +#define XSTRINGIFY(x) #x + + +/** + * @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; + * @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 ); + * @endcode + */ +#define STRINGIFY(x) XSTRINGIFY(x) + +// The XSTRINGIFY() macro is just a helper macro to implement STRINGIFY() +// and should not be used alone. +#define XSTRINGIFY(x) #x /* End of header body */ diff --git a/mbglib/lib/bc/mbgdevio.lib b/mbglib/lib/bc/mbgdevio.lib Binary files differindex e45f718..787d738 100644 --- a/mbglib/lib/bc/mbgdevio.lib +++ b/mbglib/lib/bc/mbgdevio.lib diff --git a/mbglib/lib/bc/mbgsvcio.lib b/mbglib/lib/bc/mbgsvcio.lib Binary files differindex 86b966f..14263eb 100644 --- a/mbglib/lib/bc/mbgsvcio.lib +++ b/mbglib/lib/bc/mbgsvcio.lib diff --git a/mbglib/lib/bc/mbgsvctl.lib b/mbglib/lib/bc/mbgsvctl.lib Binary files differindex b4a0210..136d929 100644 --- a/mbglib/lib/bc/mbgsvctl.lib +++ b/mbglib/lib/bc/mbgsvctl.lib diff --git a/mbglib/lib/msc/mbgdevio.lib b/mbglib/lib/msc/mbgdevio.lib Binary files differindex d273251..455ce4e 100644 --- a/mbglib/lib/msc/mbgdevio.lib +++ b/mbglib/lib/msc/mbgdevio.lib diff --git a/mbglib/lib/msc/mbgsvcio.lib b/mbglib/lib/msc/mbgsvcio.lib Binary files differindex c4987be..1df34d3 100644 --- a/mbglib/lib/msc/mbgsvcio.lib +++ b/mbglib/lib/msc/mbgsvcio.lib diff --git a/mbglib/lib/msc/mbgsvctl.lib b/mbglib/lib/msc/mbgsvctl.lib Binary files differindex 0a2f61d..055247a 100644 --- a/mbglib/lib/msc/mbgsvctl.lib +++ b/mbglib/lib/msc/mbgsvctl.lib diff --git a/mbglib/lib/msc/mbgutil.lib b/mbglib/lib/msc/mbgutil.lib Binary files differindex fe570bc..e25110b 100644 --- a/mbglib/lib/msc/mbgutil.lib +++ b/mbglib/lib/msc/mbgutil.lib diff --git a/mbglib/lib64/msc/mbgdevio.lib b/mbglib/lib64/msc/mbgdevio.lib Binary files differindex 8e443b7..cc7f21a 100644 --- a/mbglib/lib64/msc/mbgdevio.lib +++ b/mbglib/lib64/msc/mbgdevio.lib diff --git a/mbglib/lib64/msc/mbgsvcio.lib b/mbglib/lib64/msc/mbgsvcio.lib Binary files differindex e9c4cd6..76af96b 100644 --- a/mbglib/lib64/msc/mbgsvcio.lib +++ b/mbglib/lib64/msc/mbgsvcio.lib diff --git a/mbglib/lib64/msc/mbgsvctl.lib b/mbglib/lib64/msc/mbgsvctl.lib Binary files differindex 538e203..d530bc9 100644 --- a/mbglib/lib64/msc/mbgsvctl.lib +++ b/mbglib/lib64/msc/mbgsvctl.lib diff --git a/mbglib/lib64/msc/mbgutil.lib b/mbglib/lib64/msc/mbgutil.lib Binary files differindex 82ea1e1..96296fb 100644 --- a/mbglib/lib64/msc/mbgutil.lib +++ b/mbglib/lib64/msc/mbgutil.lib diff --git a/mbglib/win32/mbg_w32.h b/mbglib/win32/mbg_w32.h index ebdc119..8eaa17d 100644 --- a/mbglib/win32/mbg_w32.h +++ b/mbglib/win32/mbg_w32.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbg_w32.h 1.7 2012/05/30 13:28:43Z martin TEST $ + * $Id: mbg_w32.h 1.10 2018/12/04 09:52:48Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,14 @@ * * ----------------------------------------------------------------------- * $Log: mbg_w32.h $ + * 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 + * Removed obsolete Windows driver stuff. + * Revision 1.8 2018/09/21 10:59:26Z martin + * Renamed PCPS_DDEV field from irp to p_irp. + * Use common message functions. + * Removed obsolete code. * Revision 1.7 2012/05/30 13:28:43Z martin * Cleanup. * Revision 1.6 2012/05/29 14:39:53Z martin @@ -57,6 +65,11 @@ /* Start of header body */ +#if !defined( DEBUG_RSRC ) + #define DEBUG_RSRC 0 +#endif + + #if USE_PGMB_IRQ typedef struct @@ -104,17 +117,9 @@ typedef VOID (*KE_QUERY_SYSTEM_TIME_FNC)(PLARGE_INTEGER CurrentTime); #endif -#if 0 //##++ - #define _x_evt_msg _evt_msg -#else - #define _x_evt_msg _dbg_evt_msg -#endif - - // definitions for clock() support in kernel drivers -#define clock_t ulong #define clock w32_clock @@ -226,7 +231,7 @@ KeQuerySystemTimePrecise( _Out_ PLARGE_INTEGER CurrentTime); #define _pcps_ddev_data_win_pnp \ - DEVICE_OBJECT *physical_device_object; \ + DEVICE_OBJECT *physical_device_object; \ USB_REMOVE_LOCK remove_lock; \ \ struct \ @@ -260,8 +265,7 @@ KeQuerySystemTimePrecise( _Out_ PLARGE_INTEGER CurrentTime); DRIVER_OBJECT *DriverObject; \ DEVICE_OBJECT *DeviceObject; \ UNICODE_STRING win32DeviceName; \ - WCHAR wcs_msg[512]; \ - IRP *irp; \ + IRP *p_irp; \ _pgmb_irq_vars \ _pcps_ddev_data_win_pnp diff --git a/mbglib/win32/mbgsvcio.h b/mbglib/win32/mbgsvcio.h new file mode 100644 index 0000000..51e7d2a --- /dev/null +++ b/mbglib/win32/mbgsvcio.h @@ -0,0 +1,259 @@ + +/************************************************************************** + * + * $Id: mbgsvcio.h 1.18 2018/09/21 07:39:14Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for mbgsvcio.c. + * + * ----------------------------------------------------------------------- + * $Log: mbgsvcio.h $ + * 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. + * Updated function prototypes. + * Revision 1.17 2014/07/10 15:03:14Z martin + * Moved some definitions here. + * Updated function prototypes. + * Revision 1.16 2009/08/14 09:28:13Z daniel + * New version code 306, compatibility version code still 200. + * Revision 1.15 2009/06/09 08:57:47Z daniel + * Rev No. 305 + * Revision 1.14 2009/03/19 09:06:40Z daniel + * New version code 304, compatibility version code still 200. + * Revision 1.13 2009/01/12 09:40:18Z daniel + * New version code 303, compatibility version code still 200. + * Added comments in doxygen format. + * Revision 1.12 2008/01/17 10:14:41Z daniel + * New version code 302, compatibility version code still 200. + * Revision 1.11 2007/10/16 10:16:27Z daniel + * New version code 301, compatibility version code still 200. + * Revision 1.10 2007/09/24 15:28:17Z martin + * New version code 300, compatibility version code still 200. + * Revision 1.9 2007/03/22 09:52:18Z martin + * New version code 219, compatibility version code still 200. + * Removed obsolete headers. + * Revision 1.8 2006/08/09 13:38:02Z martin + * New version code 218, compatibility version still 200. + * Revision 1.7 2006/06/08 12:23:54Z martin + * New version code 217, compatibility version still 200. + * Revision 1.6 2006/05/02 12:52:17Z martin + * New version code 216, compatibility version still 200. + * Revision 1.5 2006/01/11 12:04:32Z martin + * New version code 215, compatibility version still 200. + * Revision 1.4 2005/12/15 09:16:38Z martin + * New version code 214, compatibility version still 200. + * Revision 1.3 2005/07/20 07:38:39Z martin + * New version code 213. + * Revision 1.2 2005/02/16 15:34:40Z martin + * New version 2.12. + * Revision 1.1 2004/07/01 10:00:51Z martin + * + **************************************************************************/ + +#ifndef _MBGSVCIO_H +#define _MBGSVCIO_H + + +/* Other headers to be included */ + +#include <mbg_tgt.h> +#include <words.h> +#include <pcpsdefs.h> + + + +#ifdef _MBGSVCIO + #define _ext +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#if defined( _USE_PACK ) // set byte alignment + #pragma pack( 1 ) +#endif + +#define MBGSVCIO_VERSION 0x0308 + +#define MBGSVCIO_COMPAT_VERSION 0x0200 + + +#define USE_SERIAL_XHRT 0 // not fully implemented/tested + + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief A union used to access a FILETIME as 64 bit number + * + * @note using this union may be tricky. Even though no problems + * have been observed, yet, the MS docs clearly say there may be + * alignment problems under 64 bit Windows. + * If the FILETIME members are not 32 bit aligned then accessing + * the dwl member will yield wrong values. + */ +typedef union +{ + FILETIME ft; ///< FILETIME structure as provided by the Windows API + uint64_t dwl; ///< used to access as single 64 bit number + +} FT_DWL; + + + +/** + * @brief A timestamp in Windows format, plus %UTC offset and clock status + */ +typedef struct +{ + FT_DWL ftdwl; ///< time stamp, based on %UTC + int32_t utc_offs; ///< %UTC offset in [sec] + PCPS_TIME_STATUS_X status; ///< extended status, see ::PCPS_TIME_STATUS_X + +} REF_TIME; + + + +/** + * @brief Error information retrieved from the time adjustment service + */ +typedef struct +{ + uint32_t code; ///< error/status code, see ::ERR_INFO_CODES + REF_TIME time; ///< clock's time and status when ::code was updated + +} ERR_INFO; + + +/** + * @brief Codes used with ::ERR_INFO::code + */ +enum ERR_INFO_CODES +{ + MBG_SVC_NO_ERROR, ///< No current error condition + MBG_SVC_ERR_OPEN_CLOCK_DEV, ///< Failed to open clock device + MBG_SVC_ERR_OPEN_SERIAL_PORT, ///< Failed to open serial port + MBG_SVC_ERR_SAME_REF_TIME, ///< Clock device always returns same time (hardware failure) + MBG_SVC_ERR_REF_TIME_STEP, ///< Time on the clock device has jumped, service stopped disciplining system time + N_MBG_SVC_ERR_CODE ///< the number of known codes +}; + + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + /** + * @brief Get the version number of the precompiled DLL/shared object library. + * + * If this library is used as a DLL/shared object library then the version + * number can be checked to see if the header files which are actually used + * to build an application are compatible with the header files which have + * been used to build the library, and thus the API function are called + * in the correct way. + * + * @return The version number + * + * @see ::mbgsvcio_check_version + * @see ::MBGSVCIO_VERSION defined in mbgsvcio.h. + */ + _MBG_API_ATTR int _MBG_API mbgsvcio_get_version( void ) ; + + /** + * @brief Check if the DLL/shared library is compatible with a given version. + * + * If this library is used as a DLL/shared object library then the version + * number can be checked to see if the header files which are actually used + * to build an application are compatible with the header files which have + * been used to build the library, and thus the API functions are called + * in the correct way. + * + * @param[in] header_version Version number to be checked, should be ::MBGSVCIO_VERSION + * from the mbgsvcio.h file version used to build the application + * + * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE + * + * @see ::mbgsvcio_get_version + * @see ::MBGSVCIO_VERSION defined in mbgsvcio.h + */ + _MBG_API_ATTR int _MBG_API mbgsvcio_check_version( int header_version ) ; + + /** + * @brief Query the status of the Meinberg time adjustment service "mbgadjtm.exe" + * + * @return 1, if the service has the state "SERVICE_RUNNING", otherwise 0. + */ + _MBG_API_ATTR int _MBG_API mbg_time_adjustment_active( void ) ; + + /** + * @brief Read the ::ERROR_INFO structure from the Meinberg time adjustment service + * + * @param[out] p Pointer to an ::ERROR_INFO structure to be filled on success + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ + _MBG_API_ATTR int _MBG_API mbg_get_time_adjustment_err_info( ERR_INFO *p ) ; + + /** + * @brief Check if the reference clock is accessible. + * + * @return 1 if the reference clock is accessible<br> + * 0 if the reference time is invalid (all 0), or the device is inaccessible.<br> + * One of the @ref MBG_ERROR_CODES if the shared memory area is not accessible. + */ + _MBG_API_ATTR int _MBG_API mbg_ref_time_accessible( void ) ; + + /** + * @brief Read the current refclock's state from the time adjustment service. + * + * This function should be used preferably over ::mbg_get_ref_time_status, + * which is deprecated since the return code from that function can't be + * reliably classified as bit coded clock status code, or error number. + * + * @param[out] p_status Pointer to a ::PCPS_TIME_STATUS_X to be filled on success, or NULL. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::PCPS_TIME_STATUS_X + */ + _MBG_API_ATTR int _MBG_API mbg_get_ref_time_status_ex( PCPS_TIME_STATUS_X *p_status ) ; + + /** + * @brief Read the current refclock's state from the time adjustment service. + * + * @deprecated This function is deprecated since its return code can't + * be reliably classified as bit coded clock status code, or error number. + * + * @return A ::PCPS_TIME_STATUS_X status code, or -1 in case of an error. + * + * @see ::mbg_get_ref_time_status_ex + * @see ::PCPS_TIME_STATUS_X + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_get_ref_time_status_ex" ) _MBG_API mbg_get_ref_time_status( void ) ; + + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + +#if defined( _USE_PACK ) // set default alignment + #pragma pack() +#endif + +/* End of header body */ + +#undef _ext + +#endif // _MBGSVCIO_H + diff --git a/mbglib/win32/mbgsvctl.h b/mbglib/win32/mbgsvctl.h new file mode 100644 index 0000000..4a90675 --- /dev/null +++ b/mbglib/win32/mbgsvctl.h @@ -0,0 +1,477 @@ + +/************************************************************************** + * + * $Id: mbgsvctl.h 1.30 2018/11/29 14:27:30Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for servio.c + * + * ----------------------------------------------------------------------- + * $Log: mbgsvctl.h $ + * Revision 1.30 2018/11/29 14:27:30Z martin + * Updated function prototypes. + * Revision 1.29 2018/09/21 11:12:49Z martin + * New version code 308, compatibility version code still 214. + * Moved definitions of MBGADJTM_CFG, MBG_SERCLOCK_CFG + * and related stuff elsewhere. + * Updated function prototypes. + * Revision 1.28 2009/12/15 15:35:09Z daniel + * New version code 307, compatibility version code still 214. + * Include mbgserio.h. + * Windows.h is now included elsewhere. + * Revision 1.27 2009/08/14 09:28:41 daniel + * New version code 306, compatibility version code still 214. + * Revision 1.26 2009/06/09 08:57:47Z daniel + * Rev No. 305 + * Revision 1.25 2009/03/19 09:07:26Z daniel + * New version code 304, compatibility version code still 214. + * Revision 1.24 2009/01/28 10:38:15Z daniel + * Added serial flag SERCLOCK_STRING_PER_MINUTE and + * bit mask MSK_SERCLOCK_STRING_PER_MINUTE. + * Revision 1.23 2009/01/12 10:14:23Z daniel + * New version code 303, compatibility version code still 214. + * Changed UINT to uint32_t and LPTSTR to char*. + * Added MBGADJTM_CFG parameters allow_timestep_on_refclk_jump + * and allow_initial_timestep. + * Avoid including mbgdevio.h when MBG_OMIT_MBGDEVIO_H is defined. + * Updated function prototypes. + * Revision 1.22 2008/01/30 07:53:58Z daniel + * New version code 302, compatibility version code still 214. + * Added new members to MBGADJTM_CFG structure to + * support service event handling. + * Revision 1.21 2007/10/16 10:09:51Z daniel + * New file version 3,1,0,0, product version 3,1,0,0. + * New version code 301, compatibility version code still 214. + * Revision 1.20 2007/09/26 14:46:43Z martin + * New version code 300, compatibility version code still 214. + * Identify selected device by hardware ID instead of device index. + * Removed obsolete references to ASCII log file. + * Updated function prototypes. + * Revision 1.19 2007/03/21 16:46:27Z martin + * New version code 219, compatibility version code still 214. + * Changes due to renamed library symbols. + * Updated function prototypes. + * Revision 1.18 2006/10/31 16:24:09Z martin + * Added a serial port flag which prevents the read thread from + * using special timeout settings. + * Revision 1.17 2006/08/09 13:31:11Z martin + * New version code 218, compatibility version code still 214. + * Revision 1.16 2006/06/08 10:36:10Z martin + * New version code 217, compatibility version code still 214. + * Revision 1.15 2006/05/23 19:35:15Z martin + * Updated function prototypes. + * Revision 1.14 2006/05/02 10:08:51Z martin + * New version code 216, compatibility version code still 214. + * Revision 1.13 2006/01/11 11:45:05Z martin + * New version code 215, compatibility version code still 214. + * Revision 1.12 2005/12/15 09:02:05Z martin + * New version 214 and compatibility version 214. + * New service registry parameter "flags" which controls + * logging time adjustment details, and starting paused. + * Updated function prototypes. + * Revision 1.11.1.1 2005/11/28 17:08:34Z martin + * Revision 1.11 2005/07/20 07:23:58Z martin + * New version 213 and compatibility version 213. + * New service cfg parameters notification_limit and + * set_mm_timer. + * Updated function prototypes. + * Revision 1.10 2004/04/27 13:46:40Z martin + * New member flags in MBG_SERCLOCK_CFG. + * Revision 1.9 2004/04/27 07:17:47Z martin + * Changed type of MBG_SERCLOCK_CFG::ref_offs. + * Removed function prototypes that are used in exe-File only + * New definition MBGSVCIO_COMPAT_VERSION. + * Pack structures 1 byte aligned. + * Updated function protoypes. + * Revision 1.8 2003/12/22 15:55:57Z martin + * New DLL interface version number. + * Updated function prototypes. + * Revision 1.7 2003/12/10 10:41:50Z martin + * New DLL interface version number. + * Revision 1.6 2003/10/31 11:11:11Z martin + * New DLL interface version number. + * New structures with config parameters. + * Updated function prototypes. + * Revision 1.5 2003/09/23 09:58:36Z martin + * Updated function prototypes. + * Revision 1.4 2003/04/09 15:24:01Z martin + * Module renamed from servio.h. + * Include standard names and reg paths. + * Updated function prototypes. + * Revision 1.3 2002/09/30 07:54:35Z martin + * Updated function prototypes by MAKEHDR. + * Revision 1.2 2002/02/22 10:35:11Z Daniel + * Revision 1.1 2002/02/18 10:52:18Z Daniel + * Initial revision + * + **************************************************************************/ + +#ifndef _MBGSVCTL_H +#define _MBGSVCTL_H + + +/* 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> +#include <timecnv.h> + +#if defined( MBG_TGT_WIN32 ) + #include <rs232.h> + #include <mbgadjtm_cfg.h> +#else + #define MBGADJTM_CFG int //##++++++++++++++ + #include <mbgserio.h> +#endif + + +#ifdef _MBGSVCTL + #define _ext +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#if defined( _USE_PACK ) // set byte alignment + #pragma pack( 1 ) +#endif + + +#define MBGSVCTL_VERSION 0x0308 + +#define MBGSVCTL_COMPAT_VERSION 0x0214 + + +#ifdef __cplusplus +extern "C" { +#endif + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + /** + * @brief Get the version number of the precompiled DLL/shared object library. + * + * If this library is used as a DLL/shared object library then the version + * number can be checked to see if the header files which are actually used + * to build an application are compatible with the header files which have + * been used to build the library, and thus the API function are called + * in the correct way. + * + * @return The version number + * + * @see ::mbgsvctl_check_version + * @see ::MBGSVCTL_VERSION defined in mbgsvctl.h + */ + _MBG_API_ATTR int _MBG_API mbgsvctl_get_version( void ) ; + + /** + * @brief Check if the DLL/shared library is compatible with a given version. + * + * If this library is used as a DLL/shared object library then the version + * number can be checked to see if the header files which are actually used + * to build an application are compatible with the header files which have + * been used to build the library, and thus the API 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 + * + * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE + * + * @see ::mbgsvctl_get_version + * @see ::MBGSVCTL_VERSION defined in mbgsvctl.h + */ + _MBG_API_ATTR int _MBG_API mbgsvctl_check_version( int header_version ) ; + + _MBG_API_ATTR void _MBG_API mbgsvctl_log_mbgdevio_error( DWORD ioctl, DWORD sys_rc ) ; + _MBG_API_ATTR int _MBG_API snprint_system_time( char *s, size_t max_len, const SYSTEMTIME *st ) ; + /** + * @brief Register an event source. + * + * When an application uses the RegisterEventSource() or 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 + * under the application key and adding registry values to the new + * subkey. + * + * @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. + */ + _MBG_API_ATTR int _MBG_API mbg_svc_register_event_source( const char *eventlog_name ) ; + + _MBG_API_ATTR void _MBG_API mbg_svc_snprint_cfg( char *s, size_t max_len, MBGADJTM_CFG *curr_adjtm_cfg, MBGADJTM_CFG *prev_adjtm_cfg, MBG_SERCLOCK_CFG *curr_serclock_cfg, MBG_SERCLOCK_CFG *prev_serclock_cfg ) ; + /** + *@brief Generate a log message according to a message ID. + * + * 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. + * + * @see ::mbg_svc_log_msg + */ + _MBG_API_ATTR void _MBG_API mbg_svc_log_msg( DWORD msg_id, DWORD sys_rc, const char *fmt, const char *info_1, const char *info_2 ) ; + + /** + *@brief Generate a log message depending on a Meinberg error code. + * + * Unlike the ::mbg_svc_log_msg which expects a message ID as specified + * e.g. in @ref MBG_WIN_MSG_IDS, this function just expects one of the + * @ref MBG_ERROR_CODES which is converted to a message ID and passed + * to ::mbg_svc_log_msg to actually generate the log message. + * + * @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 + * + * @see ::mbg_svc_log_msg + */ + _MBG_API_ATTR void _MBG_API mbg_svc_log_mbg_error( int mbg_errno, const char *fmt, const char *info_1, const char *info_2 ) ; + + /** + * @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. + * + * @return true if the calling process has admin rights, else 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 + * + * @param[in,out] devices 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 ) ; + + _MBG_API_ATTR int _MBG_API mbg_svc_find_devices( void ) ; + /** + * @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 + * + * @return The number of Meinberg PnP devices in the list + */ + _MBG_API_ATTR int _MBG_API mbg_svc_find_devices_with_hw_id( MBG_DEV_FN_LIST_ENTRY **p_list, int max_devices ) ; + + /** + * @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. + * + * @param[in] device_index The index of the device in the list. + * + * @return The device path, or 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 ) ; + + /** + * @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. + */ + _MBG_API_ATTR DWORD _MBG_API mbg_svc_set_mbgadjtm_cfg( const MBGADJTM_CFG *p ) ; + + /** + * @brief Read the time service configuration parameters from the registry. + * + * @param[out] p A structure to be filled with the settings read from the registry. + * + * @return ERROR_SUCCESS, or a win32 system error code. + */ + _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_mbgadjtm_cfg( MBGADJTM_CFG *p ) ; + + _MBG_API_ATTR void _MBG_API mbg_svc_get_mbgadjtm_cfg_default( MBGADJTM_CFG *p ) ; + /** + * @brief Write the configuration parameters for a serial clock 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. + */ + _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_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 ) ; + /** + * @brief Query the status of a service with specified name. + * + * @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. + * On error, 0 if the service is not installed, or + * (DWORD) -1 if there was a problem querying the status. + */ + _MBG_API_ATTR DWORD _MBG_API mbg_svc_query_status( const char *svc_name ) ; + + /** + * @brief Start a named service, log a message on error. + * + * @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. + * + * @see ::mbg_svc_stop + * @see ::mbg_svc_pause + * @see ::mbg_svc_continue + */ + _MBG_API_ATTR DWORD _MBG_API mbg_svc_start( const char *svc_name ) ; + + /** + * @brief Stop a named service, log a message on error. + * + * @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. + * + * @see ::mbg_svc_start + * @see ::mbg_svc_pause + * @see ::mbg_svc_continue + */ + _MBG_API_ATTR DWORD _MBG_API mbg_svc_stop( const char *svc_name ) ; + + /** + * @brief Pause a named service, log a message on error. + * + * @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. + * + * @see ::mbg_svc_start + * @see ::mbg_svc_stop + * @see ::mbg_svc_continue + */ + _MBG_API_ATTR DWORD _MBG_API mbg_svc_pause( const char *svc_name ) ; + + /** + * @brief Start 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. + * + * @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() + * 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_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. + */ + _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 + * + * @param[in] svc_name The name of the service to be removed. + * + * @return ERROR_SUCCESS, or a win32 system error code. + */ + _MBG_API_ATTR DWORD _MBG_API mbg_svc_remove( const char *svc_name ) ; + + /** + * @brief Set a service's start mode to AUTO or MANUALLY. + * + * @param[in] svc_name The name of the service to be changed. + * + * @return ERROR_SUCCESS, or a win32 system error code. + */ + _MBG_API_ATTR DWORD _MBG_API mbg_svc_set_autostart( const char *svc_name, BOOL autostart ) ; + + _MBG_API_ATTR DWORD _MBG_API mbg_svc_set_description( const char *svc_name, const char *svc_descr ) ; + _MBG_API_ATTR DWORD _MBG_API mbg_svc_set_ctry_code( const DWORD *p ) ; + _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_ctry_code( DWORD *p ) ; + _MBG_API_ATTR void _MBG_API mbg_svc_get_ctry_code_default( DWORD *p ) ; + _MBG_API_ATTR const char * _MBG_API mbg_svc_name_time_adjustment( void ) ; + _MBG_API_ATTR const char * _MBG_API mbg_svc_name_clock_kernel_driver( void ) ; + _MBG_API_ATTR const char * _MBG_API mbg_svc_name_ntp( void ) ; + /** + * @brief Get the path of an executable file. + * + * @param[out] path The output buffer to be filled with the path. + * @param[in] max_len The size of the output buffer AKA maximum path length. + * @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. + */ + _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_exe_path( char *path, uint32_t max_len, const char *exe_name, const char *subdir ) ; + + _MBG_API_ATTR DWORD _MBG_API mbg_svc_install_time_adjustment( void ) ; + _MBG_API_ATTR DWORD _MBG_API mbg_svc_uninstall_time_adjustment( void ) ; + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + + +#if defined( _USE_PACK ) // set default alignment + #pragma pack() +#endif + +/* End of header body */ + +#undef _ext + +#endif // _MBGSVCTL_H + diff --git a/mbglib/win32/rs232.h b/mbglib/win32/rs232.h new file mode 100644 index 0000000..0f72f2e --- /dev/null +++ b/mbglib/win32/rs232.h @@ -0,0 +1,137 @@ + +/************************************************************************** + * + * $Id: rs232.h 1.13 2018/08/16 12:57:40Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for template.c. + * + * ----------------------------------------------------------------------- + * $Log: rs232.h $ + * Revision 1.13 2018/08/16 12:57:40Z martin + * Updated function prototypes to avoid compiler warnings. + * Revision 1.12 2012/01/12 14:46:06Z martin + * Removed German umlauts in old RCS log entries. + * Revision 1.11 2006/11/01 15:42:38Z martin + * Picked up Andre's new method SetComParameter(). + * Revision 1.10 2006/10/30 14:47:51Z martin + * Updated function prototypes. + * Revision 1.9 2004/04/14 08:39:46Z martin + * Pack structures 1 byte aligned. + * Revision 1.8 2003/10/21 08:24:29Z martin + * Changed "bool" to "BOOL" to avoid compiler warnings. + * Revision 1.7 2003/10/16 12:44:36Z martin + * Don't define class if compiled without _cplusplus. + * Revision 1.6 2003/03/27 16:11:17 Daniel + * removed obsolete header files + * Revision 1.5 2003/03/10 09:26:02Z Daniel + * increased buffer size for ComName + * Revision 1.4 2002/11/26 10:24:22Z martin + * Port handle made public. + * New variables which keep transmission times per + * bit and per char in 100 nsec units, and bits per char. + * Use standard file template. + * Revision 1.3 2001/09/12 09:50:12Z Udo + * Fehler korrigiert: + * Schutz gegen rekursiven Include + * undef _ext ergaenzt + * Revision 1.2 2001/02/14 11:19:58Z WERNER + * Clear_Error Funktion zugefuegt + * Revision 1.1 2000/08/29 07:47:38Z WERNER + * Initial revision + * + **************************************************************************/ + +#ifndef _RS232_H +#define _RS232_H + + +/* Other headers to be included */ + +#include <use_pack.h> + +#include <windows.h> + + +#ifdef _RS232 + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#if defined( _USE_PACK ) // set byte alignment + #pragma pack( 1 ) +#endif + + +typedef struct +{ + char ComName[7]; + char Framing[4]; + long Baudrate; +} COMSTRUCT; + + +#ifdef __cplusplus + +class Comport{ +public: + HANDLE Handle; + ULONG bits_per_char; // mostly 10 or 11, depending on the framing + ULONG bit_time; // 100 nsec units required to transmit 1 bit and 1 char, + ULONG char_time; // depending on transmission speed and bits per char. + + class InitException { }; + Comport( COMSTRUCT *Cpnt ); // Konstruktor + ~Comport(void); // Destruktor + + void SetComParameter( COMSTRUCT *Cpnt ); + int Read( LPSTR lpszBlock, DWORD dwMaxLength ); + int Write( LPSTR lpszBlock, DWORD dwMaxLength ); + BOOL RxClear( void ); + BOOL TxClear( void ); + DWORD ClearError( void ); +}; + +#endif + +/* function prototypes: */ + +#ifdef __cplusplus +extern "C" { +#endif + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + HANDLE mbg_open_serial( const char *device_name ) ; + void mbg_log_com_error( DWORD dwErrorFlags, COMSTAT *pComStat ) ; + DWORD mbg_clear_comm_error( HANDLE h ) ; + int mbg_setup_port_list( int max_port_num, void (*callbackfnc)( const char *dev_name ) ) ; + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + + +#if defined( _USE_PACK ) // set default alignment + #pragma pack() +#endif + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _RS232_H */ + diff --git a/mbglib/win32/timecnv.h b/mbglib/win32/timecnv.h new file mode 100644 index 0000000..fe5159c --- /dev/null +++ b/mbglib/win32/timecnv.h @@ -0,0 +1,326 @@ + +/************************************************************************** + * + * $Id: timecnv.h 1.15 2018/09/21 08:30:57Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for timecnv.c. + * + * ----------------------------------------------------------------------- + * $Log: timecnv.h $ + * 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 + * Support non-Windows builds. + * Moved some definitions to more appropriate headers. + * New Windows-specific inline functions + * mbg_pcps_time_stamp_to_filetime() and + * mbg_pcps_tstamp64_to_filetime(). + * Updated function prototypes. + * Revision 1.13 2009/03/17 09:27:08Z daniel + * Updated function prototypes. + * Revision 1.12 2009/01/12 13:57:36Z daniel + * Uses ULL instead of LLU. + * FILETIME_1970 with 64 bit suffix is different for GnuC and VC. + * Added perf_count_on_time in SERIAL_TIME_STRING. + * Revision 1.11 2006/05/04 14:13:38Z martin + * Added initializers for time string format names. + * Added macro _secs_to_hns(). + * Revision 1.10 2006/05/02 10:39:09Z martin + * Moved some definitions here and renamed some symbols. + * Added new definitions for unified parsing of time strings. + * Cleanup and renamed field in SERIAL_TIME_STRING. + * Updated function prototypes. + * Revision 1.9 2005/11/15 14:36:33Z martin + * Use new type PCPS_TIME_STATUS_X in REF_TIME. + * Updated function prototypes. + * Revision 1.8 2005/06/09 10:35:18Z martin + * Moved declaration of serclock_cfg elsewhere. + * Revision 1.7 2004/04/27 07:41:47Z martin + * Moved some macros here. + * Moved some constants from other files here. + * Pack structures 1 byte aligned. + * Updated function prototypes. + * Revision 1.6 2004/02/12 10:16:21Z martin + * Updated function prototypes. + * Revision 1.5 2004/01/06 16:26:56Z martin + * Updated function prototypes. + * Revision 1.4 2003/12/19 16:13:10Z martin + * New parameter for GET_REF_TIME_FNC type. + * Revision 1.3 2003/09/12 12:47:41Z Daniel + * added include file mbgsvctl.h + * Revision 1.2 2002/09/30 12:17:12 martin + * Added structure SERIAL_TIME_STRING. + * Added type of function to get REF_TIME. + * Updated function prototypes. + * Revision 1.1 2002/08/28 10:47:36Z Daniel + * Initial revision + * + **************************************************************************/ + +#ifndef _TIMECNV_H +#define _TIMECNV_H + +/* Other headers to be included */ + +#include <mbg_tgt.h> +#include <gpsdefs.h> +#include <pcpsdefs.h> +#include <pcpsutil.h> +#include <mbgtime.h> +#include <mbgpccyc.h> + +#if defined( MBG_TGT_WIN32 ) + #include <mbgsvcio.h> + #include <mbgdevio.h> + #include <mbg_serclock_cfg.h> + #include <rs232.h> +#endif //MBG_TGT_WIN32 + +#include <use_pack.h> + + +#ifdef _TIMECNV + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#if defined( _USE_PACK ) + #pragma pack( 1 ) // set byte alignment + #define _USING_BYTE_ALIGNMENT +#endif + + +#ifdef __cplusplus +extern "C" { +#endif + +// ASCII definitions + +#define ASCII_STX 0x02 +#define ASCII_ETX 0x03 +#define ASCII_BEL 0x07 +#define ASCII_BS 0x08 +#define ASCII_LF 0x0A +#define ASCII_CR 0x0D +#define ASCII_XON 0x11 +#define ASCII_XOFF 0x13 + +#define STR_STX "\x2" +#define STR_ETX "\x3" + + +#define _perf_cnt_to_us( _v ) \ + ( (double) (_v) * (double) ( HNS_PER_SEC / 10 ) / (double) PerfFrequency ) + +#define _perf_cnt_to_hns( _v ) \ + ( (double) (_v) * (double) HNS_PER_SEC / (double) PerfFrequency ) + +#define _secs_to_hns( _v ) \ + ( ( (LONGLONG) (_v) ) * HNS_PER_SEC ) + +#if defined( MBG_TGT_WIN32 ) + +typedef struct +{ + REF_TIME rt; + MBG_PC_CYCLES cycles; +} REF_TIME_CYCLES; + + + +#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; + + +// 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 ); + +#endif //MBG_TGT_WIN32 + +// supported time string formats + +enum +{ + SF_MBG_STD, + SF_SAT, + SF_INTERFLEX, + N_SF +}; + + +// Initializers for the time string format names + +#define SF_NAME_MBG_STD_ENG "Meinberg Time String" +#define SF_NAME_MBG_STD_GER "Meinberg Zeittelegramm" + +#define SF_NAME_SAT_ENG "SAT Time String" +#define SF_NAME_SAT_GER "SAT Zeittelegramm" + +#define SF_NAME_INTERFLEX_ENG "Interflex Time String" +#define SF_NAME_INTERFLEX_GER "Interflex Zeittelegramm" + + +#define SF_NAMES_ENG \ +{ \ + SF_NAME_MBG_STD_ENG, \ + SF_NAME_SAT_ENG, \ + SF_NAME_INTERFLEX_ENG \ +} + + +#define SF_NAMES_LSTR \ +{ \ + { SF_NAME_MBG_STD_ENG, SF_NAME_MBG_STD_GER }, \ + { SF_NAME_SAT_ENG, SF_NAME_SAT_GER }, \ + { SF_NAME_INTERFLEX_ENG, SF_NAME_INTERFLEX_GER } \ +} + + + +// a structure to store the characteristics of a time string + +typedef struct +{ + const char *chk_fmt; // to check the format, len must be str len + char skip_char; + char first_char; + char on_time_char; +} TS_SPEC; + + +#define TS_SPEC_MBG_STD \ +{ \ + STR_STX "D:__.__.__;T:_;U:__.__.__;____" STR_ETX, \ + '_', \ + ASCII_STX, \ + ASCII_STX \ +} + +#define TS_SPEC_SAT \ +{ \ + STR_STX "__.__.__/_/__:__:__________" STR_ETX, \ + '_', \ + ASCII_STX, \ + ASCII_STX \ +} + +#define TS_SPEC_INTERFLEX \ +{ \ + STR_STX "IFD:__.__.__;T:_;U:__.__.__;____" STR_ETX, \ + '_', \ + ASCII_STX, \ + ASCII_STX \ +} + + +// Default initializer for an array of N_SF TS_SPECs + +#define DEFAULT_TS_SPECS \ +{ \ + TS_SPEC_MBG_STD, \ + TS_SPEC_SAT, \ + TS_SPEC_INTERFLEX \ +} + +#if defined( MBG_TGT_WIN32 ) + +_ext TS_SPEC ts_spec[N_SF] +#ifdef _DO_INIT + = DEFAULT_TS_SPECS +#endif +; + + +_ext ushort year_limit +#ifdef _DO_INIT + = 1970 +#endif +; + +#endif //MBG_TGT_WIN32 + + + +#if defined( MBG_TGT_WIN32 ) + +static __mbg_inline +void mbg_pcps_time_stamp_to_filetime( FILETIME *p_ft, const PCPS_TIME_STAMP *p_ts ) +{ + uint64_t ts64; + uint32_t frac; + + frac = bin_frac_32_to_dec_frac( p_ts->frac, PCPS_HRT_FRAC_SCALE ); + ts64 = ( (uint64_t) p_ts->sec ) * HNS_PER_SEC + FILETIME_1970 + frac; + + p_ft->dwHighDateTime = (uint32_t) ( ts64 >> 32 ); + p_ft->dwLowDateTime = (uint32_t) ( ts64 & 0xFFFFFFFFUL ); + +} // mbg_pcps_time_stamp_to_filetime + + + +static __mbg_inline +void mbg_pcps_tstamp64_to_filetime( FILETIME *p_ft, const uint64_t *p_ts64 ) +{ + PCPS_TIME_STAMP ts; + + uint64_to_pcps_time_stamp( &ts, *p_ts64 ); + mbg_pcps_time_stamp_to_filetime( p_ft, &ts ); + +} // mbg_pcps_tstamp64_to_filetime + + + +/* function prototypes: */ + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + int check_time_string( const char *ts, int len, int sf ) ; + void decode_str_date_std( SYSTEMTIME *pt, const char *s ) ; + 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 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 ) ; + void pcps_hr_time_to_pcps_time( PCPS_TIME *ptime, const PCPS_HR_TIME *hr_time ) ; + +/* ----- function prototypes end ----- */ + +#endif //MBG_TGT_WIN32 + +#ifdef __cplusplus +} +#endif + + +#if defined( _USING_BYTE_ALIGNMENT ) + #pragma pack() // set default alignment + #undef _USING_BYTE_ALIGNMENT +#endif + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _TIMECNV_H */ diff --git a/mbgsetsystime/mbgsetsystime.c b/mbgsetsystime/mbgsetsystime.c new file mode 100644 index 0000000..319e3f8 --- /dev/null +++ b/mbgsetsystime/mbgsetsystime.c @@ -0,0 +1,373 @@ + +/************************************************************************** + * + * $Id: mbgsetsystime.c 1.12 2018/11/15 12:12:35Z martin REL_M $ + * + * Description: + * Main file for mbgsetsystime program which reads the current date + * and time from a Meinberg device and sets the system time accordingly. + * The program returns 0 if successfull, otherwise a value greater + * than 0. + * + * Be careful if using this program while (x)ntpd is running because + * (x)ntpd does not like time steps and may react unexpectedly. + * + * ----------------------------------------------------------------------- + * $Log: mbgsetsystime.c $ + * Revision 1.12 2018/11/15 12:12:35Z martin + * Individual MBG_MICRO_VERSION codes are now obsolete. + * Revision 1.11 2018/10/30 14:49:55 martin + * Account for renamed library function in Windows-specific code. + * Revision 1.10 2018/01/15 18:21:49Z martin + * Changed return type of snprintf_timespec() to int. + * Account for renamed library symbol NSEC_PER_SEC. + * Revision 1.9 2017/07/05 18:24:44 martin + * New way to maintain version information. + * Support build under Windows. + * Use high resolution time if the device supports it. + * Use codes and inline functions from mbgerror.h. + * Use functions from new module timeutil. + * Account for frac_sec_from_bin() obsoleted by bin_frac_32_to_dec_frac(). + * Proper return codes and exit codes. + * Revision 1.8 2009/09/29 15:02:15 martin + * Updated version number to 3.4.0. + * Revision 1.7 2009/07/24 09:50:09 martin + * Updated version number to 3.3.0. + * Revision 1.6 2009/06/19 12:38:52 martin + * Updated version number to 3.2.0. + * Revision 1.5 2009/03/19 17:04:26 martin + * Updated version number to 3.1.0. + * Updated copyright year to include 2009. + * Revision 1.4 2008/12/22 12:43:31 martin + * Updated description, copyright, revision number and string. + * Use unified functions from toolutil module. + * Accept device name(s) on the command line. + * Don't use printf() without format, which migth produce warnings + * with newer gcc versions. + * Revision 1.3 2007/07/24 09:33:01 martin + * Updated copyright to include 2007. + * Revision 1.2 2003/04/25 10:28:05 martin + * Use new functions from mbgdevio library. + * New program version v2.1. + * Revision 1.1 2001/09/17 15:08:46 martin + * + **************************************************************************/ + +// include Meinberg headers +#include <mbgdevio.h> +#include <pcpsmktm.h> +#include <pcpsutil.h> +#include <toolutil.h> +#include <timeutil.h> +#include <str_util.h> +#include <mbgerror.h> + +// include system headers +#include <stdio.h> +#include <stdlib.h> + +#include <sys/types.h> + + +#define MBG_FIRST_COPYRIGHT_YEAR 2001 +#define MBG_LAST_COPYRIGHT_YEAR 0 // use default + +static const char *pname = "mbgsetsystime"; + + + +static /*HDR*/ +int sn_printf_timespec( char *s, size_t max_len, const struct timespec *p_ts ) +{ + struct tm tm = { 0 }; + int rc = mbg_gmtime( &tm, &p_ts->tv_sec ); + + if ( mbg_rc_is_error( rc ) ) // conversion failed + return sn_cpy_str_safe( s, max_len, "(invalid time)" ); + + return snprintf_safe( s, max_len, "%04i-%02i-%02i %02i:%02i:%02i.%09li UTC", + tm.tm_year + 1900, tm.tm_mon + 1, tm.tm_mday, + tm.tm_hour, tm.tm_min, tm.tm_sec, + (long) p_ts->tv_nsec ); + +} // sn_printf_timespec + + + +static /*HDR*/ +int set_system_time( const struct timespec *p_ts ) +{ + char ws[100]; + +#if defined( MBG_TGT_WIN32 ) + #define clock_settime mbg_clock_settime //### TODO cleanup +#endif + + int rc = clock_settime( CLOCK_REALTIME, p_ts ); + + sn_printf_timespec( ws, sizeof( ws ), p_ts ); + + if ( rc < 0 ) // usually 0 on success, -1 on error + { + rc = mbg_get_last_error( NULL ); + + fprintf( stderr, "Failed to set system time to %s: %s\n", ws, mbg_strerror( rc ) ); + return rc; + } + + printf( "Date/time set to %s\n", ws ); + + return MBG_SUCCESS; + +} // set_system_time + + + +static /*HDR*/ +int set_system_time_from_pcps_time( const PCPS_TIME *p_t ) +{ + struct tm tm = { 0 }; + time_t t_rev; + time_t t; + int rc; + + t = pcps_mktime( p_t ); + + if ( t == (time_t) -1 ) // error + { + fprintf( stderr, "Failed to convert %02u.%02u.%02u %02u:%02u:%02u.%02u (UTC%+02ih) to system time\n", + p_t->mday, p_t->month, p_t->year, + p_t->hour, p_t->min, p_t->sec, p_t->sec100, + p_t->offs_utc + ); + return MBG_ERR_OVERFLOW; + } + + t_rev = t + p_t->offs_utc * SECS_PER_HOUR; + + rc = mbg_gmtime( &tm, &t_rev ); + + if ( mbg_rc_is_error( rc ) ) + return rc; + + if ( ( tm.tm_year % 100 != p_t->year ) || + ( tm.tm_mon + 1 != p_t->month ) || + ( tm.tm_mday != p_t->mday ) || + ( tm.tm_hour != p_t->hour ) || + ( tm.tm_min != p_t->min ) || + ( tm.tm_sec != p_t->sec ) ) + { + fprintf( stderr, "reversely computed date/time differs from original\n" ); + return MBG_ERR_RANGE; + } + + #if defined( MBG_TGT_WIN32 ) + { + SYSTEMTIME st; + + union + { + FILETIME ft; + ULONGLONG ull; + } u; + + // Convert seconds and fractions to 100 ns units. + u.ull = FILETIME_1970 + + (ULONGLONG) t * 10 * 1000 * 1000 + + (ULONGLONG) (ulong) p_t->sec100 * 100000; + + if ( !FileTimeToSystemTime( &u.ft, &st ) ) + { + int err = mbg_win32_sys_err_to_mbg( GetLastError(), NULL ); + + fprintf( stderr, "Failed to convert FILETIME to system time: %s\n", + mbg_strerror( err ) ); + return err; + } + + if ( !SetSystemTime( &st ) ) + { + #if 0 + LPVOID lpMsgBuf; + DWORD last_error = GetLastError(); + + FormatMessage( FORMAT_MESSAGE_ALLOCATE_BUFFER | + FORMAT_MESSAGE_FROM_SYSTEM | + FORMAT_MESSAGE_IGNORE_INSERTS, + NULL, + last_error, + MAKELANGID( LANG_NEUTRAL, SUBLANG_DEFAULT ), // Default language + (LPTSTR) &lpMsgBuf, + 0, + NULL + ); + + fprintf( stderr, "Failed to set system time: %s (code 0x%08lX)\n", + lpMsgBuf, (ulong) last_error ); + + // Free the buffer. + LocalFree( lpMsgBuf ); + #else + int err = mbg_win32_sys_err_to_mbg( GetLastError(), NULL ); + + fprintf( stderr, "Failed to set system time: err %i\n", err ); + #endif + return err; + } + + return MBG_SUCCESS; + } + #else // assuming POSIX + { + struct timespec ts; + + ts.tv_sec = t; + ts.tv_nsec = (long) p_t->sec100 * ( NSEC_PER_SEC / 100 ); // convert to nanoseconds + + return set_system_time( &ts ); + } + #endif + +} // set_system_time_from_pcps_time + + + +static /*HDR*/ +int do_set_system_time_from_pcps_time( MBG_DEV_HANDLE dh ) +{ + PCPS_TIME t; + + int rc = mbg_get_time( dh, &t ); + + if ( mbg_cond_err_msg( rc, "mbg_get_time" ) ) + return rc; + + if ( t.status & PCPS_INVT ) + { + // This may happen if the radio clock's battery + // has been discharged or disconnected. + printf( "Radio clock has no valid date/time.\n" ); + return MBG_ERR_INV_TIME; + } + + rc = set_system_time_from_pcps_time( &t ); + + return rc; + +} // do_set_system_time_from_pcps_time + + + +static /*HDR*/ +int do_set_system_time_from_pcps_hr_time( MBG_DEV_HANDLE dh ) +{ + PCPS_HR_TIME ht; + struct timespec ts = { 0 }; + + int rc = mbg_get_hr_time( dh, &ht ); + + if ( mbg_cond_err_msg( rc, "mbg_get_hr_time" ) ) + return rc; + + if ( ht.status & PCPS_INVT ) + { + // This may happen if the radio clock's battery + // has been discharged or disconnected. + printf( "Radio clock has no valid date/time.\n" ); + return MBG_ERR_INV_TIME; + } + + ts.tv_sec = ht.tstamp.sec; + ts.tv_nsec = bin_frac_32_to_dec_frac( ht.tstamp.frac, NSEC_PER_SEC ); + + return set_system_time( &ts ); + +} // do_set_system_time_from_pcps_hr_time + + + +static /*HDR*/ +int do_mbgsetsystime( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) +{ + static int system_time_has_been_set; + + int rc = MBG_SUCCESS; + + if ( system_time_has_been_set ) + goto done; + + rc = mbg_chk_dev_has_hr_time( dh ); + + if ( mbg_rc_is_success( rc ) ) + rc = do_set_system_time_from_pcps_hr_time( dh ); + else + rc = do_set_system_time_from_pcps_time( dh ); + + if ( mbg_rc_is_success( rc ) ) + system_time_has_been_set = 1; + + puts( "" ); + +done: + return rc; + +} // do_mbgsetsystime + +static MBG_DEV_HANDLER_FNC do_mbgsetsystime; + + + +static /*HDR*/ +void usage( void ) +{ + mbg_print_usage_intro( pname, + "This program can be used to set the system time to the card's time.\n" + "This should be done only at boot time, before the NTP daemon is started.\n" + "Please *don't* run this program while ntpd is already active." + ); + mbg_print_help_options(); + mbg_print_device_options(); + puts( "" ); + +} // usage + + + +int main( int argc, char *argv[] ) +{ + int c; + int rc; + + mbg_print_program_info( pname, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); + + // check command line parameters + while ( ( c = getopt( argc, argv, "h?" ) ) != -1 ) + { + switch ( c ) + { + case 'h': + case '?': + default: + must_print_usage = 1; + } + } + + if ( must_print_usage ) + { + usage(); + return MBG_EXIT_CODE_USAGE; + } + + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbgsetsystime, 0 ); + + // determine the exit code based on the return code + + if ( mbg_rc_is_success( rc ) ) + return MBG_EXIT_CODE_SUCCESS; // success + + if ( rc == MBG_ERR_INV_TIME ) + return MBG_EXIT_CODE_INV_TIME; // device has no valid time to set the system time with + + return MBG_EXIT_CODE_FAIL; // any error occurred +} diff --git a/mbgshowsignal/mbgshowsignal.c b/mbgshowsignal/mbgshowsignal.c new file mode 100644 index 0000000..5896dd2 --- /dev/null +++ b/mbgshowsignal/mbgshowsignal.c @@ -0,0 +1,188 @@ + +/************************************************************************** + * + * $Id: mbgshowsignal.c 1.10 2018/11/15 12:12:36Z martin REL_M $ + * + * Description: + * Main file for mbgshowsignal program which demonstrates how to + * access a Meinberg device via IOCTL calls and show the modulation + * signal (second marks) of a longwave receiver, e.g. for DCF77. + * + * ----------------------------------------------------------------------- + * $Log: mbgshowsignal.c $ + * Revision 1.10 2018/11/15 12:12:36Z martin + * Individual MBG_MICRO_VERSION codes are now obsolete. + * Revision 1.9 2017/07/05 18:31:14 martin + * New way to maintain version information. + * Support build under Windows. + * Update modulation status continuously. + * Show PZF correlation state. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. + * Revision 1.8 2009/09/29 15:02:15 martin + * Updated version number to 3.4.0. + * Revision 1.7 2009/07/24 09:50:09 martin + * Updated version number to 3.3.0. + * Revision 1.6 2009/06/19 12:38:52 martin + * Updated version number to 3.2.0. + * Revision 1.5 2009/03/19 17:04:26 martin + * Updated version number to 3.1.0. + * Updated copyright year to include 2009. + * Revision 1.4 2008/12/22 12:44:43 martin + * Changed ealier program name mbgdcfmod to mbgshowsignal. + * Updated description, copyright, revision number and string. + * Use unified functions from toolutil module. + * Accept device name(s) on the command line. + * Don't use printf() without format, which migth produce warnings + * with newer gcc versions. + * Revision 1.3 2007/07/24 09:32:11 martin + * Updated copyright to include 2007. + * Revision 1.2 2003/04/25 10:28:05 martin + * Use new functions from mbgdevio library. + * New program version v2.1. + * Revision 1.1 2001/09/17 15:08:09 martin + * + **************************************************************************/ + +// include Meinberg headers +#include <mbgdevio.h> +#include <toolutil.h> // common utility functions + +// include system headers +#include <stdio.h> +#include <stdlib.h> +#include <time.h> + + +#define MBG_FIRST_COPYRIGHT_YEAR 2001 +#define MBG_LAST_COPYRIGHT_YEAR 0 // use default + +static const char *pname = "mbgshowsignal"; + + + +static /*HDR*/ +int show_modulation( MBG_DEV_HANDLE dh ) +{ + static time_t prv_sys_t; + time_t sys_t; + PCPS_STATUS_PORT status_port; // current value of the clock's status port + PCPS_TIME t; + int signal; + + bool dev_has_pzf = mbg_chk_dev_has_pzf( dh ) == MBG_SUCCESS; + + int rc = mbg_get_status_port( dh, &status_port ); // read status port + + if ( mbg_cond_err_msg( rc, "mbg_get_status_port" ) ) + return rc; + + // show signal only once per second + sys_t = time( NULL ); + + if ( sys_t != prv_sys_t ) + { + rc = mbg_get_time( dh, &t ); + + if ( mbg_cond_err_msg( rc, "mbg_get_time" ) ) + return rc; + + prv_sys_t = sys_t; + } + + // The current value of the modulation (second mark) is returned + // in a single bit of the status port, so ignore the other bits. + printf( "\rMod: %c", ( status_port & PCPS_ST_MOD ) ? '*' : '_' ); + + signal = t.signal - PCPS_SIG_BIAS; + + if ( signal < 0 ) + signal = 0; + else + if ( signal > PCPS_SIG_MAX ) + signal = PCPS_SIG_MAX; + + printf( " Signal: %u%% ", signal * 100 / PCPS_SIG_MAX ); + + if ( dev_has_pzf ) + rc = mbg_show_pzf_corr_info( dh, 1 ); + + printf( " " ); + + return rc; + +} // show_modulation + + + +static /*HDR*/ +int do_mbgshowsignal( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) +{ + int rc = mbg_chk_dev_has_mod( dh ); + + if ( mbg_rc_is_error( rc ) ) + { + mbg_cond_err_msg_info( rc, "mbg_dev_has_mod", + "support monitoring signal modulation" ); + return rc; + } + + printf( "\nMonitoring signal modulation:\n" ); + + for (;;) + if ( mbg_rc_is_error( rc = show_modulation( dh ) ) ) + break; + + return rc; + +} // do_mbgshowsignal + +static MBG_DEV_HANDLER_FNC do_mbgshowsignal; + + + +static /*HDR*/ +void usage( void ) +{ + mbg_print_usage_intro( pname, + "This program displays the modulation signal of cards which receive\n" + "a slowly modulated input signal, e.g. the longwave signal from DCF77.\n" + ); + mbg_print_help_options(); + mbg_print_device_options(); + puts( "" ); + +} // usage + + + +int main( int argc, char *argv[] ) +{ + int c; + int rc; + + mbg_print_program_info( pname, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); + + // check command line parameters + while ( ( c = getopt( argc, argv, "h?" ) ) != -1 ) + { + switch ( c ) + { + case 'h': + case '?': + default: + must_print_usage = 1; + } + } + + if ( must_print_usage ) + { + usage(); + return MBG_EXIT_CODE_USAGE; + } + + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbgshowsignal, 0 ); + + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; +} diff --git a/mbgstatus/mbgstatus.c b/mbgstatus/mbgstatus.c index d4df10c..654367b 100644 --- a/mbgstatus/mbgstatus.c +++ b/mbgstatus/mbgstatus.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgstatus.c 1.13.1.25 2013/02/05 14:36:47Z martin TEST martin $ + * $Id: mbgstatus.c 1.17 2018/11/15 12:12:37Z martin REL_M $ * * Description: * Main file for mbgstatus program which demonstrates how to @@ -10,49 +10,22 @@ * * ----------------------------------------------------------------------- * $Log: mbgstatus.c $ - * Revision 1.13.1.25 2013/02/05 14:36:47Z martin - * Revision 1.13.1.24 2012/04/11 16:26:44Z martin - * Revision 1.13.1.23 2012/04/10 15:56:40 martin - * Revision 1.13.1.22 2012/02/14 13:40:02 martin - * Use library function to print MAC address. - * Revision 1.13.1.21 2012/01/17 13:35:41 martin - * More control of amount of output by verbosity level. - * Revision 1.13.1.20 2012/01/16 16:41:25 martin - * Revision 1.13.1.19 2011/10/28 13:46:14 martin - * Revision 1.13.1.18 2011/10/28 13:05:03 martin - * Revision 1.13.1.17 2011/10/05 15:10:56 martin - * Show PZF correlation state. - * Revision 1.13.1.16 2011/10/05 13:03:34 martin - * Adapted PZF correlation/signal/status display. - * Revision 1.13.1.15 2011/10/05 11:57:42 martin - * Revision 1.13.1.14 2011/09/29 16:30:03 martin - * Started to support PZF. - * Optionally show hex status. - * Changed what is displayed in certain levels of verbosity. - * Revision 1.13.1.13 2011/09/07 15:08:55 martin - * Account for modified library functions which can now - * optionally print the raw (hex) HR time stamp. - * Revision 1.13.1.12 2011/07/08 11:02:47 martin - * Revision 1.13.1.11 2011/07/05 15:35:55 martin - * Modified version handling. - * Revision 1.13.1.10 2011/07/05 14:35:19 martin + * Revision 1.17 2018/11/15 12:12:37Z martin + * Individual MBG_MICRO_VERSION codes are now obsolete. + * Revision 1.16 2018/07/03 15:28:55 martin + * Use -L rather than -l to display unique names of installed devices + * Now use -l to list installed devices. + * Also read and print TTM in verbose mode. + * Use specific API call to read IRIG debug status. + * Revision 1.15 2017/12/21 15:57:43 martin + * Improved displaying of UTC/leap second parameters. + * Revision 1.14 2017/07/05 18:34:46 martin * New way to maintain version information. - * Revision 1.13.1.9 2011/04/20 16:08:27 martin - * Use snprint_ip4_addr() from module lan_util. - * Revision 1.13.1.8 2011/03/03 10:01:23 daniel - * Indicate Unicast role in PTP port state - * Revision 1.13.1.7 2011/02/07 12:10:58 martin - * Use mbg_get_ptp_status() API call. - * Revision 1.13.1.6 2010/11/25 14:54:51 martin - * Revision 1.13.1.5 2010/11/05 12:54:22 martin - * Introduce "verbose" flag and associated command line parameter -v. - * Revision 1.13.1.4 2010/10/15 11:28:56 martin - * Display UTC offs from IRIG signal. - * Revision 1.13.1.3 2010/08/30 08:22:24 martin - * Revision 1.13.1.2 2010/08/11 15:06:49 martin - * Preliminarily display raw IRIG data, if supported by the device. - * Revision 1.13.1.1 2010/02/17 14:11:43 martin - * Cosmetics ... + * Support build under Windows. + * Show many more details, at different verbosity levels. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. * Revision 1.13 2009/09/29 15:02:16 martin * Updated version number to 3.4.0. * Revision 1.12 2009/07/24 14:02:59 martin @@ -101,24 +74,32 @@ // include Meinberg headers #include <mbgdevio.h> +#include <mbgutil.h> #include <mbgtime.h> #include <pcpslstr.h> -#include <pcpsutil.h> #include <toolutil.h> // common utility functions #include <lan_util.h> +#include <deviohlp.h> +#include <timeutil.h> +#include <str_util.h> +#include <nanotime.h> // include system headers #include <stdio.h> #include <stdlib.h> -#define MBG_MICRO_VERSION 0 #define MBG_FIRST_COPYRIGHT_YEAR 2001 #define MBG_LAST_COPYRIGHT_YEAR 0 // use current year by default static const char *pname = "mbgstatus"; +static int loops; +static int list_only; // list only which devices are installed +static int list_only_unique_names; // list only the unique names of all devices +static long sleep_secs; +static long sleep_usecs; static unsigned int verbose; static const char *ref_name[N_PCPS_REF]= PCPS_REF_NAMES_ENG; @@ -130,6 +111,8 @@ static int year_limit = 1990; static int max_ref_offs_h = MBG_REF_OFFS_MAX / MINS_PER_HOUR; static int invt_reason; +static const char *wdays[7] = { "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" }; + LANGUAGE language; CTRY ctry; @@ -167,7 +150,8 @@ void print_pcps_time( const char *s, const PCPS_TIME *tp, const char *tail ) if ( s ) printf( fmt, s ); - printf( fmt, pcps_date_time_str( ws, tp, year_limit, pcps_tz_name( tp, PCPS_TZ_NAME_FORCE_UTC_OFFS, 0 ) ) ); + printf( fmt, pcps_date_time_str( ws, sizeof( ws ), tp, year_limit, + pcps_tz_name( tp, PCPS_TZ_NAME_FORCE_UTC_OFFS, 0 ) ) ); if ( ( verbose > 0 ) && _pcps_time_is_read( tp ) ) printf( ", st: 0x%02lX", (ulong) tp->status ); @@ -184,7 +168,7 @@ void print_dms( const char *s, const DMS *p, const char *tail ) { const char *fmt = "%s"; - printf( "%s %c %3i deg %02i min %05.2f sec", + printf( "%s %c %3i deg %02i min %06.3f sec", s, p->prefix, p->deg, @@ -312,7 +296,8 @@ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char * int signal; int i; int rc = mbg_get_time( dh, &t ); - if ( mbg_ioctl_err( rc, "mbg_get_time" ) ) + + if ( mbg_cond_err_msg( rc, "mbg_get_time" ) ) return; @@ -320,12 +305,12 @@ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char * if ( ( verbose > 0 ) && _pcps_has_hr_time( pdev ) ) { - PCPS_HR_TIME ht; + PCPS_HR_TIME ht = { { 0 } }; char ws[80]; rc = mbg_get_hr_time( dh, &ht ); - if ( mbg_ioctl_err( rc, "mbg_get_hr_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_hr_time" ) ) return; mbg_snprint_hr_time( ws, sizeof( ws ), &ht, 0 ); // raw timestamp? @@ -337,6 +322,25 @@ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char * printf( "%s", tail ); } + if ( ( verbose > 1 ) && _pcps_is_gps( pdev ) ) + { + TTM ttm = { 0 }; + char ws[80]; + int n; + + rc = mbg_get_gps_time( dh, &ttm ); + + if ( mbg_cond_err_msg( rc, "mbg_get_gps_time" ) ) + return; + + n = pcps_str_tm_gps_date_time( ws, sizeof( ws ), &ttm.tm ); + n += snprint_utc_offs( &ws[n], sizeof( ws ) - n, " UTC", ttm.tm.offs_from_utc ); + + printf( "TTM time: %s", ws ); + printf( ", TTM st: 0x%04X", ttm.tm.status ); + printf( "%s", tail ); + } + signal = t.signal - PCPS_SIG_BIAS; if ( signal < 0 ) @@ -350,7 +354,7 @@ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char * if ( _pcps_has_pzf( pdev ) ) { - mbg_show_pzf_corr_info( dh, pdev, 0 ); + mbg_show_pzf_corr_info( dh, 0 ); printf( "\n" ); } @@ -360,7 +364,7 @@ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char * rc = mbg_get_irig_time( dh, &it ); - if ( !mbg_ioctl_err( rc, "mbg_get_irig_time" ) ) + if ( !mbg_cond_err_msg( rc, "mbg_get_irig_time" ) ) printf( "Raw IRIG time: yday %u, %02u:%02u:%02u\n", it.yday, it.hour, it.min, it.sec ); } @@ -391,7 +395,7 @@ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char * rc = mbg_get_ref_offs( dh, &ref_offs ); - if ( !mbg_ioctl_err( rc, "mbg_get_ref_offs" ) ) + if ( !mbg_cond_err_msg( rc, "mbg_get_ref_offs" ) ) { if ( _pcps_ref_offs_out_of_range( ref_offs ) ) invt_reason = 2; @@ -410,7 +414,7 @@ void show_sync_time( MBG_DEV_HANDLE dh, const char *tail ) PCPS_TIME t; int rc = mbg_get_sync_time( dh, &t ); - if ( mbg_ioctl_err( rc, "mbg_get_sync_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_sync_time" ) ) return; print_pcps_time( "Last sync: ", &t, tail ); @@ -423,41 +427,114 @@ static /*HDR*/ void show_ext_stat_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *tail ) { const char *fmt = "%s"; - RECEIVER_INFO ri; - STAT_INFO si = { 0 }; + RECEIVER_INFO ri = { 0 }; + ALL_GNSS_INFO agi = { { 0 } }; + GNSS_SAT_INFO *p_gsi; char ws[80]; - char *mode_name; + const char *cp; + int i; + int rc; - int rc = mbg_setup_receiver_info( dh, p_dev, &ri ); + // first collect all information - if ( mbg_ioctl_err( rc, "mbg_setup_receiver_info" ) ) + rc = mbg_setup_receiver_info( dh, p_dev, &ri ); + + if ( mbg_cond_err_msg( rc, "mbg_setup_receiver_info" ) ) return; - if ( _pcps_has_stat_info( p_dev ) ) + if ( mbg_rc_is_success( mbg_chk_dev_is_gps( dh ) ) ) { - rc = mbg_get_gps_stat_info( dh, &si ); + rc = mbg_chk_get_all_gnss_info( dh, &agi ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_stat_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_chk_get_gnss_info" ) ) return; + } + // now print information + if ( verbose ) + printf( "Feature mask: 0x%08lX\n", (ulong) ri.features ); + + if ( _pcps_has_stat_info( p_dev ) ) + { if ( _pcps_has_stat_info_mode( p_dev ) ) { - switch ( si.mode ) + switch ( agi.stat_info.mode ) { - case AUTO_166: mode_name = "Normal Operation"; break; - case WARM_166: mode_name = "Warm Boot"; break; - case COLD_166: mode_name = "Cold Boot"; break; + case AUTO_166: cp = "Normal Operation"; break; + case WARM_166: cp = "Warm Boot"; break; + case COLD_166: cp = "Cold Boot"; break; default: // This should never happen! - sprintf( ws, "Unknown mode of operation: %02Xh", si.mode ); - mode_name = ws; + snprintf_safe( ws, sizeof( ws ), "%s mode of operation: %02Xh", + str_unknown, agi.stat_info.mode ); + cp = ws; } // switch + + printf( "%s", cp ); } + } + + if ( agi.n_gnss_supp ) + { + #if defined( DEBUG ) // TODO + int must_print_sv_list = _pcps_has_stat_info_svs( p_dev ) && verbose; + #else + int must_print_sv_list = _pcps_is_gnss( p_dev ) && verbose; + #endif + int print_multi_lines = ( agi.n_gnss_supp > 1 ) || must_print_sv_list; + + // print multiple lines + // otherwise append to line + printf( print_multi_lines ? ":\n" : ", " ); + + for ( i = 0; i < agi.n_gnss_supp; i++ ) + { + static const char * const gnss_type_names[N_GNSS_TYPES] = GNSS_TYPE_STRS; + int gnss_type; + + p_gsi = &agi.gnss_sat_info_idx[i].gnss_sat_info; + gnss_type = p_gsi->gnss_type; + + if ( gnss_type >= N_GNSS_TYPES ) + { + mbg_snprintf( ws, sizeof( ws ), "(%s GNSS type %i): ", str_unknown, gnss_type ); + cp = ws; + } + else + cp = gnss_type_names[gnss_type]; + + if ( print_multi_lines ) + printf( " " ); + + if ( agi.gnss_mode_info.settings.gnss_set & ( 1UL << gnss_type ) ) + { + printf( "%i %s sats tracked, %i expected to be visible\n", p_gsi->good_svs, cp, p_gsi->svs_in_view ); + + if ( must_print_sv_list ) + { + int sat_idx; + + for ( sat_idx = 0; sat_idx < MAX_USED_SATS; sat_idx++ ) + { + int sat_num = p_gsi->svs[sat_idx]; + + #if !defined( DEBUG ) + if ( sat_num == 0 ) + break; + #endif - if ( _pcps_has_stat_info_svs( p_dev ) ) - printf( "%s, %i sats in view, %i sats used\n", mode_name, si.svs_in_view, si.good_svs ); + printf( "%s%i", ( sat_idx == 0 ) ? " Sats: " : ", ", sat_num ); + } + + if ( sat_idx ) // the satellite list has been printed + printf( "\n" ); + } + } + else + printf( "%s reception disabled by configuration\n", cp ); + } } if ( verbose ) @@ -467,8 +544,8 @@ void show_ext_stat_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *t if ( _pcps_has_stat_info( p_dev ) ) { printf( ", DAC cal: %+i, fine: %+i", - (int) ( si.dac_cal - OSC_DAC_BIAS ), - (int) ( si.dac_val - OSC_DAC_BIAS ) ); + (int) ( agi.stat_info.dac_cal - OSC_DAC_BIAS ), + (int) ( agi.stat_info.dac_val - OSC_DAC_BIAS ) ); } puts( "" ); @@ -484,10 +561,10 @@ void show_ext_stat_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *t static /*HDR*/ void show_gps_pos( MBG_DEV_HANDLE dh, const char *tail ) { - POS pos; + POS pos = { { 0 } }; int rc = mbg_get_gps_pos( dh, &pos ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_pos" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_gps_pos" ) ) return; print_position( "Receiver Position:", &pos, tail ); @@ -499,49 +576,85 @@ void show_gps_pos( MBG_DEV_HANDLE dh, const char *tail ) static /*HDR*/ void show_utc_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) { - UTC utc; + UTC utc = { 0 }; + struct tm tm = { 0 }; + char tmp_str[80]; + long t_ls_long; + time_t t_ls; int rc = mbg_get_utc_parm( dh, &utc ); - if ( mbg_ioctl_err( rc, "mbg_get_utc_parm" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_utc_parm" ) ) return; + if ( !utc.valid ) { puts( "** UTC parameters not valid" ); - return; + goto out; } + + t_ls_long = (long) utc.WNlsf * SECS_PER_WEEK + + (long) utc.DNt * SECS_PER_DAY + + GPS_SEC_BIAS - 1; + t_ls = cvt_to_time_t( t_ls_long ); + + rc = mbg_gmtime( &tm, &t_ls ); + + if ( mbg_rc_is_success( rc ) ) + mbg_snprintf( tmp_str, sizeof( tmp_str ), "at UTC midnight at the end of %s, %04i-%02i-%02i", + wdays[tm.tm_wday], tm.tm_year + 1900, tm.tm_mon + 1, tm.tm_mday ); + else + snprint_gmtime_error( tmp_str, sizeof( tmp_str ), rc, t_ls, __func__ ); + if ( verbose > 1 ) { - //##++++ utc.delta_tls = utc.delta_tlsf - 1; + printf( "UTC correction parameters:\n" ); + + //##++++++++++ utc.delta_tls = utc.delta_tlsf - 1; - printf( "CSUM: %04X, valid: %04X\n", utc.csum, utc.valid ); - printf( "t0t: %u|%u.%07u, A0: %g A1: %g\n", + printf( " CSUM: %04X, valid: %04X\n", utc.csum, utc.valid ); + printf( " t0t: %u|%u.%07u, A0: %g A1: %g\n", utc.t0t.wn, utc.t0t.sec, utc.t0t.tick, utc.A0, utc.A1 ); - printf( "WNlsf: %u, DN: %u, offs: %i/%i\n", + printf( " WNlsf: %u, DN: %u, offs: %i/%i\n", utc.WNlsf, utc.DNt, utc.delta_tls, utc.delta_tlsf ); } if ( utc.delta_tls != utc.delta_tlsf ) { - // a leap second is currently being announced - time_t t_ls = (time_t) utc.WNlsf * SECS_PER_WEEK - + (time_t) utc.DNt * SECS_PER_DAY - + GPS_SEC_BIAS - 1; - - struct tm *tm = gmtime( &t_ls ); - - printf( "UTC offset transition from %is to %is due to leap second\n" - "%s at UTC midnight at the end of %04i-%02i-%02i.\n", + // A leap second is currently being announced + printf( "GPS/UTC offset transition from %is to %is due to leap second\n" + "%s %s.\n", utc.delta_tls, utc.delta_tlsf, ( utc.delta_tls < utc.delta_tlsf ) ? "insertion" : "deletion", - tm->tm_year + 1900, tm->tm_mon + 1, tm->tm_mday + tmp_str ); + goto out; + } + + + if ( ( utc.WNlsf == 0 ) && ( utc.DNt == 0 ) ) + { + if ( verbose ) + printf( "Leap second information not set\n" ); + + goto out; + } + + + if ( verbose ) + { + printf( "Last leap second eventually %s\n", tmp_str ); + goto out; } - else - printf( "UTC offset parameter: %is, no leap second announced.\n", utc.delta_tls ); + + + printf( "GPS/UTC offset parameter: %is, no leap second announced.\n", utc.delta_tls ); + +out: + return; } // show_utc_info @@ -554,7 +667,7 @@ void show_irig_ctrl_bits( MBG_DEV_HANDLE dh ) int rc = mbg_get_irig_ctrl_bits( dh, &irig_ctrl_bits ); - if ( mbg_ioctl_err( rc, "mbg_get_irig_ctrl_bits" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_irig_ctrl_bits" ) ) return; printf( "IRIG control bits: %08lX (hex, LSB first)", (ulong) irig_ctrl_bits ); @@ -566,18 +679,18 @@ void show_irig_ctrl_bits( MBG_DEV_HANDLE dh ) static /*HDR*/ -char *str_raw_irig_utc_offs_hours( char *s, int max_len, const MBG_RAW_IRIG_DATA *p ) +char *str_raw_irig_utc_offs_hours( char *s, size_t max_len, const MBG_RAW_IRIG_DATA *p ) { - int n; + size_t n; long offs = ( p->data_bytes[8] & 0x08 ) | ( ( p->data_bytes[8] >> 2 ) & 0x04 ) | ( ( p->data_bytes[8] >> 4 ) & 0x02 ) | ( ( p->data_bytes[8] >> 6 ) & 0x01 ); - n = snprintf( s, max_len, "%c%li", ( p->data_bytes[8] & 0x80 ) ? '-' : '+', offs ); + n = mbg_snprintf( s, max_len, "%c%li", ( p->data_bytes[8] & 0x80 ) ? '-' : '+', offs ); if ( p->data_bytes[8] & 0x02 ) - n += snprintf( &s[n], max_len - n, "%s", ".5" ); + n += mbg_snprintf( &s[n], max_len - n, "%s", ".5" ); return s; @@ -594,7 +707,7 @@ void show_raw_irig_data( MBG_DEV_HANDLE dh ) int rc = mbg_get_raw_irig_data( dh, &raw_irig_data ); - if ( mbg_ioctl_err( rc, "mbg_get_raw_irig_data" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_raw_irig_data" ) ) return; printf( "Raw IRIG data:" ); @@ -618,9 +731,9 @@ void show_irig_debug_status( MBG_DEV_HANDLE dh ) MBG_DEBUG_STATUS st; int i; - int rc = _mbg_generic_read_var( dh, PCPS_GET_DEBUG_STATUS, st ); + int rc = mbg_get_debug_status( dh, &st ); - if ( mbg_ioctl_err( rc, "show_irig_debug_status" ) ) + if ( mbg_cond_err_msg( rc, "show_irig_debug_status" ) ) return; printf( "Debug status (hex): %08lX\n", (ulong) st ); @@ -642,12 +755,12 @@ void show_lan_intf_state( MBG_DEV_HANDLE dh ) int rc = mbg_get_ip4_state( dh, &ip4_settings ); - if ( mbg_ioctl_err( rc, "mbg_get_ip4_state" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_ip4_state" ) ) return; rc = mbg_get_lan_if_info( dh, &lan_if_info ); - if ( mbg_ioctl_err( rc, "mbg_get_lan_if_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_lan_if_info" ) ) return; @@ -678,58 +791,214 @@ void show_lan_intf_state( MBG_DEV_HANDLE dh ) static /*HDR*/ void show_ptp_state( MBG_DEV_HANDLE dh ) { - static const char *ptp_stat_str[N_PTP_PORT_STATE] = PTP_PORT_STATE_STRS; + static const char *ptp_role_strs[N_PTP_ROLES] = PTP_ROLE_STRS; + static const char *ptp_state_strs[N_PTP_PORT_STATE] = PTP_PORT_STATE_STRS; + static const char *ptp_nw_prot_strs[N_PTP_NW_PROT] = PTP_NW_PROT_STRS; + static const char *ptp_delay_mech_names[N_PTP_DELAY_MECH] = PTP_DELAY_MECH_NAMES; + static const PTP_TABLE ptp_time_source_tbl[] = PTP_TIME_SOURCE_TABLE; + static const char *ptp_clock_accuracy_strs[] = PTP_CLOCK_ACCURACY_STRS; + char ws[100]; const char *cp; - int ptp_state_available; + int must_show_slave_mode_info; + int must_show_master_mode_info; + int slave_mode_active; + int master_mode_active; + int any_mode_active; + int utc_offset_valid; PTP_STATE ptp_state; PTP_CFG_INFO ptp_info; + int tmp; int rc = mbg_get_ptp_state( dh, &ptp_state ); - if ( mbg_ioctl_err( rc, "mbg_get_ptp_state" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_ptp_state" ) ) return; rc = mbg_get_ptp_cfg_info( dh, &ptp_info ); - if ( mbg_ioctl_err( rc, "mbg_get_ptp_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_ptp_info" ) ) return; - printf( "PTP port status:\n" ); - ptp_state_available = ( ptp_state.port_state == PTP_PORT_STATE_SLAVE ); + // set up some flags controlling which information to be shown - printf( " Port mode: %s%s\n", ( ptp_state_available && ptp_info.settings.ptp_role == PTP_ROLE_UNICAST_SLAVE ) ? "Unicast" : "", - ( ptp_state.port_state < N_PTP_PORT_STATE ) ? ptp_stat_str[ptp_state.port_state] : "(undefined)" ); + must_show_slave_mode_info = ( verbose > 1 ) || + ( ( ( 1UL << ptp_info.settings.ptp_role ) & PTP_ROLE_MSK_SLAVES ) != 0 ); - cp = ptp_state_available ? ws : str_not_avail; + must_show_master_mode_info = ( verbose > 1 ) || + ( ( ( 1UL << ptp_info.settings.ptp_role ) & PTP_ROLE_MSK_MASTERS ) != 0 ); -//##++++++++++ - snprintf( ws, sizeof( ws ), "%02X-%02X-%02X-%02X-%02X-%02X", - ptp_state.gm_id.b[0], - ptp_state.gm_id.b[1], - ptp_state.gm_id.b[2], - ptp_state.gm_id.b[5], - ptp_state.gm_id.b[6], - ptp_state.gm_id.b[7] - ); - printf( " Grandmaster MAC: %s\n", cp ); + slave_mode_active = ( ptp_state.port_state == PTP_PORT_STATE_UNCALIBRATED ) + || ( ptp_state.port_state == PTP_PORT_STATE_SLAVE ); + master_mode_active = ( ptp_state.port_state == PTP_PORT_STATE_PRE_MASTER ) + || ( ptp_state.port_state == PTP_PORT_STATE_MASTER ) + || ( ptp_state.port_state == PTP_PORT_STATE_PASSIVE ); - snprintf( ws, sizeof( ws ), "%c%li.%09li s", - _nano_time_negative( &ptp_state.path_delay ) ? '-' : '+', - labs( (long) ptp_state.path_delay.secs ), - labs( (long) ptp_state.path_delay.nano_secs ) - ); - printf( " PTP path delay: %s\n", cp ); + any_mode_active = slave_mode_active || master_mode_active; + + + // PTP role and port state + + printf( "PTP port state:\n" ); + + printf( " Port mode: " ); + + if ( any_mode_active ) + printf( "%s", ( ptp_state.flags & PTP_FLAG_MSK_IS_UNICAST ) ? + "Unicast " : "Multicast " ); + + if ( ptp_state.port_state < N_PTP_PORT_STATE ) + printf( "%s", ptp_state_strs[ptp_state.port_state] ); + else + printf( "%s, code %i", str_undefined, ptp_state.port_state ); + + if ( !any_mode_active || ( verbose > 1 ) ) + printf( " in %s role", + ( ptp_info.settings.ptp_role < N_PTP_ROLES ) ? + ptp_role_strs[ptp_info.settings.ptp_role] : str_undefined ); + + printf( "\n" ); + + + if ( !any_mode_active || verbose ) + { + printf( " PTP protocol: " ); + + // If not fully synchronized then not all fields of the PTP_STATE + // structure may have been filled, so we show configuration settings + // in this case. + + if ( ptp_state.ptp_prot_version ) + printf( "v%i, ", ptp_state.ptp_prot_version ); + + tmp = any_mode_active ? ptp_state.nw_prot : ptp_info.settings.nw_prot; + printf( "%s", ( tmp < N_PTP_NW_PROT ) ? + ptp_nw_prot_strs[tmp] : str_undefined ); + + printf( ", %s step", + ( ptp_state.flags & PTP_FLAG_MSK_ONE_STEP ) ? "one" : "two" ); + + tmp = any_mode_active ? ptp_state.domain_number : ptp_info.settings.domain_number; + printf( ", domain %i", tmp ); + + tmp = any_mode_active ? ptp_state.delay_mech : ptp_info.settings.delay_mech; + printf( ", delay mech. %s", ( tmp < N_PTP_DELAY_MECH ) ? + ptp_delay_mech_names[tmp] : str_undefined ); + + tmp = any_mode_active ? ptp_state.log_delay_req_intv : ptp_info.settings.delay_req_intv; + printf( ", dly req. intv. 2^%i s", tmp ); + + printf( "\n" ); + } + + + if ( must_show_slave_mode_info ) + { + cp = ( slave_mode_active || ( verbose > 1 ) ) ? ws : str_not_avail; + + snprint_octets( ws, sizeof( ws ), ptp_state.gm_id.b, + sizeof( ptp_state.gm_id.b ), MAC_SEP_CHAR_ALT, NULL ); + printf( " Grandmaster ID: %s\n", cp ); + + snprint_nano_time( ws, sizeof( ws ), &ptp_state.offset ); + printf( " PTP time offset: %s\n", cp ); + + snprint_nano_time( ws, sizeof( ws ), &ptp_state.path_delay ); + printf( " PTP path delay: %s\n", cp ); + + if ( verbose > 1 ) + { + snprint_nano_time( ws, sizeof( ws ), &ptp_state.mean_path_delay ); + printf( " Mean path delay: %s\n", cp ); + + snprint_nano_time( ws, sizeof( ws ), &ptp_state.delay_asymmetry ); + printf( " Delay asymmetry: %s\n", cp ); + } + } + + + // PTP time scale + + cp = NULL; + + if ( ptp_state.flags & PTP_FLAG_MSK_TIMESCALE_IS_PTP ) // this is the default + { + if ( must_show_master_mode_info || verbose ) + cp = "TAI (standard)"; + } + else // unusual case, print info if available + if ( any_mode_active ) + cp = "arbitrary (non-standard)"; + + if ( cp ) + printf( " PTP time scale: %s\n", cp ); + + + // UTC offset and leap second status + + utc_offset_valid = ( ptp_state.flags & PTP_FLAG_MSK_UTC_VALID ) != 0; + + printf( " PTP UTC offset: " ); + + if ( !utc_offset_valid ) + printf( " %s", str_unknown ); // UTC offset not valid + + if ( utc_offset_valid || ( verbose > 1 ) ) + { + printf( utc_offset_valid ? " " : " (" ); + + printf( "%+i s", ptp_state.utc_offset ); + + if ( ptp_state.flags & PTP_FLAG_MSK_LS_ANN ) // leap second is announced + { + // distinguish between leap second insertion and deletion + printf( ", leap second %s scheduled", + ( ptp_state.flags & PTP_FLAG_MSK_LS_ANN_NEG ) ? "deletion" : "insertion" ); + } + + if ( !utc_offset_valid ) + printf( ")" ); + } + + printf( "\n" ); + + + if ( verbose > 1 ) + { + const PTP_TABLE *p_tbl; + + printf( "PTP clock state:\n" ); + + for ( p_tbl = ptp_time_source_tbl; p_tbl->name; p_tbl++ ) + if ( p_tbl->value == ptp_state.time_source ) + break; + + printf( " Time source: %s\n", p_tbl->name ? p_tbl->name : str_unknown ); + + printf( " Clock class: %i\n", ptp_state.clock_class ); + + tmp = N_PTP_CLOCK_ACCURACY - PTP_CLOCK_ACCURACY_NUM_BIAS; + + if ( ( ptp_state.clock_accuracy >= PTP_CLOCK_ACCURACY_NUM_BIAS ) && + ( ptp_state.clock_accuracy < N_PTP_CLOCK_ACCURACY ) ) + cp = ptp_clock_accuracy_strs[ptp_state.clock_accuracy - PTP_CLOCK_ACCURACY_NUM_BIAS]; + else + cp = str_undefined; + + printf( " Clock accuracy: %s\n", cp ); + +#if 0 + time_source + clock_class + clock_accuracy +#endif + printf( " Offs sc. log var: %u", ptp_state.clock_offset_scaled_log_variance ); + printf( "\n" ); + } - snprintf( ws, sizeof( ws ), "%c%li.%09li s", - _nano_time_negative( &ptp_state.offset ) ? '-' : '+', - labs( (long) ptp_state.offset.secs ), - labs( (long) ptp_state.offset.nano_secs ) - ); - printf( " PTP time offset: %s\n", cp ); } // show_ptp_state @@ -742,8 +1011,8 @@ int check_irq_unsafe( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) int ret_val = 0; int rc = mbg_get_irq_stat_info( dh, &irq_stat_info ); - if ( mbg_ioctl_err( rc, "mbg_get_irq_stat_info" ) ) - return -1; + if ( mbg_cond_err_msg( rc, "mbg_get_irq_stat_info" ) ) + return rc; if ( irq_stat_info & PCPS_IRQ_STAT_UNSAFE ) { @@ -795,40 +1064,65 @@ int do_mbgstatus( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) if ( check_irq_unsafe( dh, p_dev ) < 0 ) goto done; - if ( _pcps_has_gps_data( p_dev ) ) - show_ext_stat_info( dh, p_dev, NULL ); + if ( list_only ) + goto done; + + for (;;) + { + if ( _pcps_has_gps_data( p_dev ) ) + show_ext_stat_info( dh, p_dev, NULL ); - show_time_and_status( dh, p_dev, "\n" ); - show_sync_time( dh, "\n" ); + show_time_and_status( dh, p_dev, "\n" ); + show_sync_time( dh, "\n" ); - if ( _pcps_is_gps( p_dev ) ) - show_gps_pos( dh, "\n" ); + if ( _pcps_is_gps( p_dev ) ) + show_gps_pos( dh, "\n" ); - if ( _pcps_has_utc_parm( p_dev ) && ( _pcps_is_gps( p_dev ) || ( verbose > 0 ) ) ) - show_utc_info( dh, p_dev ); + if ( _pcps_has_utc_parm( p_dev ) && ( _pcps_is_gps( p_dev ) || ( verbose > 0 ) ) ) + show_utc_info( dh, p_dev ); - if ( verbose && _pcps_has_irig_ctrl_bits( p_dev ) ) - show_irig_ctrl_bits( dh ); + if ( verbose && _pcps_has_irig_ctrl_bits( p_dev ) ) + show_irig_ctrl_bits( dh ); - if ( verbose && _pcps_has_raw_irig_data( p_dev ) ) - show_raw_irig_data( dh ); + if ( verbose && ( mbg_chk_dev_has_raw_irig_data( dh ) == MBG_SUCCESS ) ) + show_raw_irig_data( dh ); - if ( verbose && _pcps_is_irig_rx( p_dev ) ) - show_irig_debug_status( dh ); + if ( verbose && _pcps_is_irig_rx( p_dev ) ) + show_irig_debug_status( dh ); - if ( _pcps_has_lan_intf( p_dev ) ) - show_lan_intf_state( dh ); + if ( mbg_chk_dev_has_lan_intf( dh ) == MBG_SUCCESS ) + show_lan_intf_state( dh ); - if ( _pcps_has_ptp( p_dev ) ) - show_ptp_state( dh ); + if ( _pcps_has_ptp( p_dev ) ) + show_ptp_state( dh ); - show_invt_reason(); + show_invt_reason(); + + if ( loops > 0 ) + loops--; + + if ( loops == 0 ) + break; + + if ( sleep_secs ) + sleep( sleep_secs ); + else + if ( sleep_usecs ) + usleep( sleep_usecs ); + + printf( "\n" ); + + // if this_loops is < 0 then loop forever + } done: + return ret_val; } // do_mbgstatus +static MBG_DEV_HANDLER_FNC do_mbgstatus; + static /*HDR*/ @@ -839,6 +1133,13 @@ void usage( void ) "The displayed information depends on the type of the card." ); mbg_print_help_options(); + mbg_print_opt_info( "-c", "run continuously" ); + mbg_print_opt_info( "-l", "list devices only" ); + mbg_print_opt_info( "-L", "list unique names of all devices" ); + mbg_print_opt_info( "-n num", "run num loops" ); + mbg_print_opt_info( "-s num", "sleep num seconds between calls (implies -c)" ); + mbg_print_opt_info( "-u num", "sleep num microseconds between calls (implies -c)" ); + mbg_print_opt_info( "-v", "increase verbosity" ); mbg_print_device_options(); puts( "" ); @@ -856,13 +1157,39 @@ int main( int argc, char *argv[] ) ctry.dt_fmt = DT_FMT_YYYYMMDD; ctry.dt_sep = '-'; - mbg_print_program_info( pname, MBG_MICRO_VERSION, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); + mbg_print_program_info( pname, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); // check command line parameters - while ( ( c = getopt( argc, argv, "vh?" ) ) != -1 ) + while ( ( c = getopt( argc, argv, "clLn:s:u:vh?" ) ) != -1 ) { switch ( c ) { + case 'c': + loops = -1; + break; + + case 'l': + list_only = 1; + break; + + case 'L': + list_only_unique_names = 1; + break; + + case 'n': + loops = atoi( optarg ); + break; + + case 's': + sleep_secs = atoi( optarg ); + loops = -1; + break; + + case 'u': + sleep_usecs = atoi( optarg ); + loops = -1; + break; + case 'v': verbose++; break; @@ -877,19 +1204,38 @@ int main( int argc, char *argv[] ) if ( must_print_usage ) { usage(); - return 1; + return MBG_EXIT_CODE_USAGE; } + if ( list_only_unique_names ) + { + MBG_DEV_NAME_LIST_ENTRY *list_head = NULL; + int n_dev = mbg_find_devices_with_names( &list_head, N_SUPP_DEV_BUS ); + + if ( n_dev ) + { + MBG_DEV_NAME_LIST_ENTRY *pos; + + printf( "Unique names of devices found:\n" ); + + for ( pos = list_head; pos; pos = pos->next ) + printf( " %s\n", pos->dev_name ); + } + else + printf( "No device found.\n" ); + + mbg_free_device_name_list( list_head ); + printf( "\n" ); + + return MBG_EXIT_CODE_SUCCESS; + } + if ( verbose ) pcps_date_time_dist = 1; - // The function below checks which devices have been specified - // on the command, and for each device - // - tries to open the device - // - shows basic device info - // - calls the function passed as last parameter - rc = mbg_check_devices( argc, argv, optind, do_mbgstatus ); + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbgstatus, CHK_DEV_ALL_DEVICES ); - return abs( rc ); + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; } diff --git a/mbgversion.h b/mbgversion.h index 433b942..1e122c8 100644 --- a/mbgversion.h +++ b/mbgversion.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgversion.h 1.3 2013/01/03 12:09:30Z martin REL_M $ + * $Id: mbgversion.h 1.10 2018/08/07 13:15:33Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,23 @@ * * ----------------------------------------------------------------------- * $Log: mbgversion.h $ - * Revision 1.3 2013/01/03 12:09:30Z martin + * Revision 1.10 2018/08/07 13:15:33Z martin + * Cleaned up version definitions. + * Revision 1.9 2018/06/25 15:53:14 martin + * New version code 4.2.0. + * Changed copyright year to 2018. + * Revision 1.8 2017/07/03 09:05:11 martin + * New version code 4.0.0. + * Revision 1.7 2017/01/31 13:04:21 martin + * Include words.h instead of mbg_tgt.h + * Revision 1.6 2017/01/27 12:05:34 martin + * Changed copyright year to 2017. + * New file format. + * Revision 1.5 2015/12/17 14:40:04 martin + * Changed copyright year to 2015. + * Revision 1.4 2014/01/06 11:08:10 martin + * Changed copyright year to 2014. + * Revision 1.3 2013/01/03 12:09:30 martin * Changed copyright year to 2013. * Revision 1.2 2012/01/17 10:10:54 martin * Changed current copyright year to 2012. @@ -19,19 +35,45 @@ * **************************************************************************/ -#define MBG_CURRENT_COPYRIGHT_YEAR 2013 -#define MBG_CURRENT_COPYRIGHT_YEAR_STR "2013" +#include <words.h> // also includes mbg_tgt.h -#define MBG_MAJOR_VERSION_CODE 3 -#define MBG_MINOR_VERSION_CODE 4 +// -------------------------------------------------------------------- +// The following definitions have to be updated to reflect the +// copyright year, and the software version numbers. +// -------------------------------------------------------------------- -#define MBG_MAIN_VERSION_STR "3.4" +#define MBG_CURRENT_COPYRIGHT_YEAR 2018 -// The codes below should only fe defined in development/pre-release versions -#define MBG_MICRO_VERSION_CODE_DEV 99 -#define MBG_MICRO_VERSION_STR_DEV "99" +#define MBG_MAJOR_VERSION_CODE 4 +#define MBG_MINOR_VERSION_CODE 2 +#define MBG_MICRO_VERSION_CODE 0 +#if defined( MBG_TGT_WIN32 ) + #define MBG_BUILD_VERSION_CODE 1 +#endif -#define MBG_MAIN_VERSION_CODE ( ( MBG_MAJOR_VERSION_CODE << 8 ) | MBG_MINOR_VERSION_CODE ) -#define MBG_VERSION_CODE( _micro ) ( (uint16_t) ( ( MBG_MAIN_VERSION_CODE << 8 ) | (_micro) ) ) +// -------------------------------------------------------------------- +// The following definitions are derived from the definitions above. +// -------------------------------------------------------------------- + +#define MBG_CURRENT_COPYRIGHT_YEAR_STR STRINGIFY( MBG_CURRENT_COPYRIGHT_YEAR ) + +#define MBG_MAJOR_VERSION_STR STRINGIFY( MBG_MAJOR_VERSION_CODE ) +#define MBG_MINOR_VERSION_STR STRINGIFY( MBG_MINOR_VERSION_CODE ) +#define MBG_MICRO_VERSION_STR STRINGIFY( MBG_MICRO_VERSION_CODE ) + +#if defined( MBG_BUILD_VERSION_CODE ) + #define MBG_BUILD_VERSION_STR STRINGIFY( MBG_BUILD_VERSION_CODE ) +#endif + + +#define MBG_MAIN_VERSION_CODE ( ( MBG_MAJOR_VERSION_CODE << 8 ) | MBG_MINOR_VERSION_CODE ) +#define MBG_MAIN_VERSION_STR MBG_MAJOR_VERSION_STR "." MBG_MINOR_VERSION_STR + +#if defined( MBG_BUILD_VERSION_STR ) + #define MBG_FULL_VERSION_STR MBG_MAIN_VERSION_STR "." MBG_MICRO_VERSION_STR "." MBG_BUILD_VERSION_STR +#else + #define MBG_FULL_VERSION_STR MBG_MAIN_VERSION_STR "." MBG_MICRO_VERSION_STR +#endif + diff --git a/mbgxhrtime/mbgxhrtime.c b/mbgxhrtime/mbgxhrtime.c new file mode 100644 index 0000000..150dab1 --- /dev/null +++ b/mbgxhrtime/mbgxhrtime.c @@ -0,0 +1,341 @@ + +/************************************************************************** + * + * $Id: mbgxhrtime.c 1.7 2018/11/15 12:12:35Z martin REL_M $ + * + * Description: + * Main file for mbgxhrtime program which demonstrates how to retrieve + * fast and accurate timestamps. + * + * This program starts a polling thread which reads a high resolution + * time stamp and associated CPU cycles counter value once per second + * and saves that data pair. + * + * Current time stamps are then computed by taking the current CPU + * cycles value and extrapolating the time from the last data pair. + * + * This is very much faster than accessing the PCI card for every + * single time stamp. + * + * Notes: + * + * 1.) This approach works / makes sense only with cards which support + * high resolution time stamps (HR time). If a card doesn't support + * that then this program prints a warning. + * + * 2.) Under Linux extrapolation is done using the time stamp counter + * (TSC) registers provided by Pentium CPUs and newer/compatible + * types as the cycles counter. On SMP / multicore CPUs those + * counters may not be synchronized, so this works only correctly + * if all cycles counter values are taken from the same CPU. + * To achieve this the process CPU affinity is by default set to + * the first CPU at program start, which means all threads of this + * process are executed only on that CPU. + * + * 3.) Under Linux there's no easy way to find the accurate clock + * frequency of the cycles counter, so the polling thread computes + * the frequency from the time differences of 2 subsequent polls + * of the PCI card. If the time extrapolation function is called + * before the cycles clock frequency has been determined the + * returned time stamp is always 0. + * + * ----------------------------------------------------------------------- + * $Log: mbgxhrtime.c $ + * Revision 1.7 2018/11/15 12:12:35Z martin + * Individual MBG_MICRO_VERSION codes are now obsolete. + * Revision 1.6 2017/07/05 18:38:18 martin + * New way to maintain version information. + * Support build under Windows. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. + * Revision 1.5 2009/09/29 14:25:07 martin + * Display measured and default PC cycles frequency. + * Updated version number to 3.4.0. + * Revision 1.4 2009/07/24 09:50:09 martin + * Updated version number to 3.3.0. + * Revision 1.3 2009/06/19 12:38:52 martin + * Updated version number to 3.2.0. + * Revision 1.2 2009/03/19 17:04:26 martin + * Updated version number to 3.1.0. + * Updated copyright year to include 2009. + * Revision 1.1 2008/12/22 11:05:24 martin + * Initial revision. + * + **************************************************************************/ + +// include Meinberg headers +#include <mbgdevio.h> +#include <toolutil.h> // common utility functions + +// include system headers +#include <time.h> +#include <stdio.h> +#include <stdlib.h> + +#if !defined( MBG_TGT_WIN32 ) + #include <unistd.h> + #include <pthread.h> + #include <sched.h> +#endif + +#if !defined( MBGDEVIO_USE_THREAD_API ) + #error Symbol MBGDEVIO_USE_THREAD_API needs to be defined, see the Makefile. +#endif + +#if !defined( USE_PROCESS_AFFINITY ) + #define USE_PROCESS_AFFINITY 1 +#endif + + +#define MBG_FIRST_COPYRIGHT_YEAR 2008 +#define MBG_LAST_COPYRIGHT_YEAR 0 // use default + +static const char *pname = "mbgxhrtime"; + + +static int loops; + + + +#if USE_PROCESS_AFFINITY + +static /*HDR*/ +void print_cpu_set( const char *info, MBG_CPU_SET *p_cpu_set ) +{ + int min_cpu = MBG_CPU_SET_SIZE + 1; + int max_cpu = 0; + int i; + + for ( i = 0; i < MBG_CPU_SET_SIZE; i++ ) + { + if ( !_mbg_cpu_isset( i, p_cpu_set ) ) + continue; + + if ( i < min_cpu ) + min_cpu = i; + + if ( i > max_cpu ) + max_cpu = i; + } + + printf( "%s: CPU%i", info, min_cpu ); + + if ( max_cpu == min_cpu ) + printf( " only" ); + else + printf( "...CPU%i", max_cpu ); + + printf( "\n" ); + +} // print_cpu_set + + + +/*HDR*/ +void check_set_process_affinity_mask( MBG_PROCESS_ID pid, int cpu_num ) +{ + MBG_CPU_SET cpu_set; + + int rc = mbg_get_process_affinity( pid, &cpu_set ); + + if ( rc < 0 ) + { + perror( "Failed to get process affinity mask" ); + exit( 1 ); + } + + print_cpu_set( "Initial process affinity mask", &cpu_set ); + + _mbg_cpu_clear( &cpu_set ); + _mbg_cpu_set( cpu_num, &cpu_set ); + + rc = mbg_set_process_affinity( pid, &cpu_set ); + + if ( rc < 0 ) + { + perror( "Failed to set process affinity mask" ); + exit( 1 ); + } + + printf( "Process affinity mask set for CPU%i only\n", cpu_num ); + +} // check_set_process_affinity_mask + +#endif + + + +static /*HDR*/ +int do_mbgxhrtime( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) +{ + MBG_PC_CYCLES_FREQUENCY freq_hz = 0; + MBG_PC_CYCLES_FREQUENCY default_freq_hz = 0; + int this_loops = loops; + MBG_POLL_THREAD_INFO poll_thread_info = { { { { 0 } } } }; + int rc; + + if ( !_pcps_has_hr_time( p_dev ) ) + { + printf( "High resolution time not supported by this device.\n" ); + return 0; + } + + mbg_get_default_cycles_frequency_from_dev( dh, &default_freq_hz ); + + rc = mbg_xhrt_poll_thread_create( &poll_thread_info, dh, 0, 0 ); + + if ( rc != MBG_SUCCESS ) + return rc; + + + for (;;) + { + static int has_printed_msg = 0; + + PCPS_HR_TIME hrt; + char ws[80]; + MBG_PC_CYCLES cyc_1; + MBG_PC_CYCLES cyc_2; + double latency; + + rc = mbg_get_xhrt_cycles_frequency( &poll_thread_info.xhrt_info, &freq_hz ); + + if ( rc != MBG_SUCCESS ) + goto fail; + + if ( freq_hz == 0 ) + { + if ( !has_printed_msg ) + { + printf( "Waiting until PC cycles frequency has been computed ... " ); + has_printed_msg = 1; + } + + usleep( 50000 ); + continue; + } + + if ( has_printed_msg ) + { + puts( "" ); + + printf( "PC cycles freq: %.6f MHz", ( (double) (int64_t) freq_hz ) / 1E6 ); + + if ( default_freq_hz ) + printf( ", default: %.6f MHz", ( (double) (int64_t) default_freq_hz ) / 1E6 ); + + printf( "\n" ); + + has_printed_msg = 0; + } + + // get an extrapolated time stamp bracketed by + // mbg_get_pc_cycles() calls to compute the latency + mbg_get_pc_cycles( &cyc_1 ); + rc = mbg_get_xhrt_time_as_pcps_hr_time( &poll_thread_info.xhrt_info, &hrt ); + mbg_get_pc_cycles( &cyc_2 ); + + if ( rc != MBG_SUCCESS ) + goto fail; + + // compute the latency + latency = ( (double) cyc_2 - (double) cyc_1 ) / (double) (int64_t) freq_hz * 1E6; + + // convert to human readable date and time + mbg_snprint_hr_time( ws, sizeof( ws ), &hrt, 0 ); // raw timestamp? + printf( "t: %s (%.3f us)\n", ws, latency ); + + if ( this_loops > 0 ) + this_loops--; + + if ( this_loops == 0 ) + break; + + // if this_loops is < 0 then loop forever + } + + goto done; + +fail: + fprintf( stderr, "** Aborting: xhrt function returned %i\n", rc ); + +done: + mbg_xhrt_poll_thread_stop( &poll_thread_info ); + + return rc; + +} // do_mbgxhrtime + +static MBG_DEV_HANDLER_FNC do_mbgxhrtime; + + + +static /*HDR*/ +void usage( void ) +{ + mbg_print_usage_intro( pname, + "This example program reads fast extrapolated high resolution time stamps.\n" + "\n" + "The program starts an extra polling thread which reads a high resolution\n" + "time stamp plus associated PC cycles counter at regular intervals.\n" + "The returned time stamps are extrapolated using the current PC cycles\n" + "count value plus the last time stamp/cycles pair read by the polling thread.\n" + "\n" + "This is very much faster than accessing the card every time a time stamp\n" + "needs to be retrieved.\n" + "This works only for devices which support high resolution time (HR time)." + ); + mbg_print_help_options(); + mbg_print_opt_info( "-c", "run continuously" ); + mbg_print_opt_info( "-n num", "run num loops" ); + mbg_print_device_options(); + puts( "" ); + +} // usage + + + +int main( int argc, char *argv[] ) +{ + int rc; + int c; + + mbg_print_program_info( pname, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); + + // check command line parameters + while ( ( c = getopt( argc, argv, "cn:h?" ) ) != -1 ) + { + switch ( c ) + { + case 'c': + loops = -1; + break; + + case 'n': + loops = atoi( optarg ); + break; + + case 'h': + case '?': + default: + must_print_usage = 1; + } + } + + if ( must_print_usage ) + { + usage(); + return MBG_EXIT_CODE_USAGE; + } + + #if USE_PROCESS_AFFINITY + check_set_process_affinity_mask( _mbg_get_current_process(), 0 ); + puts( "" ); + #endif + + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbgxhrtime, 0 ); + + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; +} diff --git a/test/mbgcmptime/mbgcmptime.c b/test/mbgcmptime/mbgcmptime.c index 7052048..2b614d9 100644 --- a/test/mbgcmptime/mbgcmptime.c +++ b/test/mbgcmptime/mbgcmptime.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgcmptime.c 1.1.1.3 2013/03/20 11:14:14Z martin TEST $ + * $Id: mbgcmptime.c 1.3 2018/11/15 12:39:28Z martin REL_M $ * * Description: * Main file for mbgcmptime program which compares the time on 2 devices @@ -11,26 +11,41 @@ * * ----------------------------------------------------------------------- * $Log: mbgcmptime.c $ - * Revision 1.1.1.3 2013/03/20 11:14:14Z martin - * Revision 1.1.1.2 2013/02/01 16:26:50 martin - * Revision 1.1.1.1 2013/01/29 14:23:40 martin - * Tried to fix negative range overflow. + * Revision 1.3 2018/11/15 12:39:28Z martin + * Individual MBG_MICRO_VERSION codes are now obsolete. + * Revision 1.2 2018/08/08 09:01:45 martin + * New option -a to compensate an initial offset automatically. + * New option -C which to append a marker '#' to the output if status changed. + * New option -L to specify a time offset limit. If the time offset change + * exceeds the specified limit then a marker '<<' is appended to the output. + * New option -q for quiet operation, i.e. output lines on the console + * are overwritten unless the previous line has a marker appended. + * New option -o to specify an output file that provides the full log + * even is -q is used, too. + * Options -s and -u also imply continuous mode. + * Fixed Windows build. + * Moved some common code to cmp_time_util module. + * Moved output unbuffering to toolutil.c::mbg_check_devices(), and account + * for additional parameter expected by the current version of that function. + * Use new, safe library functions. + * Close device handle when done. + * Proper return codes and exit codes. * Revision 1.1 2013/01/25 10:26:13 martin * Initial revision. * **************************************************************************/ // include Meinberg headers +#include <cmp_time_util.h> #include <mbgdevio.h> -#include <pcpsutil.h> #include <toolutil.h> // common utility functions +#include <str_util.h> // include system headers #include <stdio.h> #include <stdlib.h> #include <math.h> -#define MBG_MICRO_VERSION 0 #define MBG_FIRST_COPYRIGHT_YEAR 2013 #define MBG_LAST_COPYRIGHT_YEAR 0 // use default @@ -45,146 +60,183 @@ static long sleep_usecs; static int print_raw; static double warn_limit; static double chk_limit; -static MBG_PC_CYCLES_FREQUENCY cyc_freq; +static int auto_offset; +static int check_status; +static int quiet; + +static const char *log_fn; + +MBG_PC_CYCLES_FREQUENCY cyc_freq; // must not be static! static const char *ref_device_name; static MBG_DEV_HANDLE dh_ref; +static PCPS_DEV dev_info_ref; + +static const char term_clreol[] = "\x1B[0K"; // ANSI escape sequence for clreol + + + +static /*HDR*/ +FILE *fopen_log( const char *mode ) +{ + FILE *fp = fopen( log_fn, mode ); + + if ( fp == NULL ) + { + fprintf( stderr, "Failed to open log file %s: %s. Giving up logging.\n", log_fn, strerror( errno ) ); + log_fn = NULL; + } + + return fp; + +} // fopen_log + static /*HDR*/ int do_mbgcmptime( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) { - int supported = 0; - PCPS_HR_TIME_CYCLES htc1; - PCPS_HR_TIME_CYCLES htc2; + PCPS_HR_TIME_CYCLES prv_htc1 = { 0 }; + PCPS_HR_TIME_CYCLES prv_htc2 = { 0 }; + PCPS_HR_TIME_CYCLES htc1 = { 0 }; + PCPS_HR_TIME_CYCLES htc2 = { 0 }; double delta_ts; double delta_cyc; double delta_t; - double prv_delta_t; + double prv_delta_t = 0.0; int prv_delta_t_avail = 0; int this_loops = loops; int rc; - int n; + size_t n; char ws[256]; + char ws1[128]; + char ws2[128]; + char ws3[64]; + int add_marker; if ( read_fast ) { - rc = mbg_dev_has_fast_hr_timestamp( dh, &supported ); + rc = chk_fast_tstamp_supp( dh, p_dev, dh_ref, &dev_info_ref, NULL ); //### TODO err_msg_fnc ? - if ( mbg_ioctl_err( rc, "mbg_has_fast_hr_timestamp" ) ) - goto done; - - if ( !supported ) + if ( mbg_rc_is_error( rc ) ) { - printf( "This device does not support fast (memory mapped) time stamps.\n" ); - printf( "** Falling back to raw mode.\n" ); - read_fast = 0; - } - - rc = mbg_dev_has_fast_hr_timestamp( dh_ref, &supported ); + if ( rc != MBG_ERR_NOT_SUPP_BY_DEV ) + goto done; - if ( mbg_ioctl_err( rc, "mbg_has_fast_hr_timestamp" ) ) - goto done; - - if ( !supported ) - { - printf( "The ref device does not support fast (memory mapped) time stamps.\n" ); - printf( "** Falling back to raw mode.\n" ); + //##+++++++++ msg .... read_fast = 0; -} + } } rc = mbg_get_default_cycles_frequency_from_dev( dh, &cyc_freq ); - if ( mbg_ioctl_err( rc, "mbg_get_default_cycles_frequency_from_dev" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_default_cycles_frequency_from_dev" ) ) goto done; - for (;;) { - if ( read_fast ) - { - PCPS_TIME_STAMP_CYCLES ts_c1; - PCPS_TIME_STAMP_CYCLES ts_c2; - - rc = mbg_get_fast_hr_timestamp_cycles( dh, &ts_c1 ); - - if ( mbg_ioctl_err( rc, "mbg_get_fast_hr_timestamp_cycles 1" ) ) - break; + rc = get_htc_timestamps( dh, &htc1, dh_ref, &htc2, read_fast ); - rc = mbg_get_fast_hr_timestamp_cycles( dh_ref, &ts_c2 ); + if ( rc != MBG_SUCCESS ) + break; - if ( mbg_ioctl_err( rc, "mbg_get_fast_hr_timestamp_cycles 2" ) ) - break; + delta_t = get_htc_delta( &htc1, &htc2, &delta_ts, &delta_cyc ); - setup_hr_time_cycles_from_timestamp_cycles( &htc1, &ts_c1 ); - setup_hr_time_cycles_from_timestamp_cycles( &htc2, &ts_c2 ); - } - else + if ( auto_offset ) { - rc = mbg_get_hr_time_cycles( dh, &htc1 ); + static double initial_offset; + static int initial_offset_set; - if ( mbg_ioctl_err( rc, "mbg_get_hr_time_cycles 1" ) ) - break; - - rc = mbg_get_hr_time_cycles( dh_ref, &htc2 ); + if ( !initial_offset_set ) + { + initial_offset = delta_t; + initial_offset_set = 1; + printf( "Initial offset: %.1f us\n", initial_offset * 1e6 ); + } - if ( mbg_ioctl_err( rc, "mbg_get_hr_time_cycles 2" ) ) - break; + delta_t -= initial_offset; } - n = 0; + n = mbg_snprint_hr_tstamp_ext( ws1, sizeof( ws1 ), &htc1.t.tstamp, print_raw ); - n += mbg_snprint_hr_tstamp( &ws[n], sizeof( ws ) - n, &htc1.t.tstamp, 0 ); + if ( check_status ) + snprintf_safe( ws1 + n, sizeof( ws1 ) - n, " st: %04X", htc1.t.status ); - if ( print_raw ) - n += snprintf( &ws[n], sizeof( ws ) - n, " (0x%08lX.%08lX)", - (ulong) htc1.t.tstamp.sec, - (ulong) htc1.t.tstamp.frac ); + n = mbg_snprint_hr_tstamp_ext( ws2, sizeof( ws2 ), &htc2.t.tstamp, print_raw ); - n += snprintf( &ws[n], sizeof( ws ) - n, ", " ); + if ( check_status ) + snprintf_safe( ws2 + n, sizeof( ws2 ) - n, " st: %04X", htc2.t.status ); - n += mbg_snprint_hr_tstamp( &ws[n], sizeof( ws ) - n, &htc2.t.tstamp, 0 ); + snprintf_safe( ws3, sizeof( ws3 ), "%+.1f us", delta_t * 1e6 ); - if ( print_raw ) - n += snprintf( &ws[n], sizeof( ws ) - n, " (0x%08lX.%08lX)", - (ulong) htc2.t.tstamp.sec, - (ulong) htc2.t.tstamp.frac ); + n = 0; - delta_ts = (double) htc2.t.tstamp.sec + dfrac_sec_from_bin( htc2.t.tstamp.frac ) - - (double) htc1.t.tstamp.sec - dfrac_sec_from_bin( htc1.t.tstamp.frac ); + n += snprintf_safe( &ws[n], sizeof( ws ) - n, "%s, %s", ws1, ws2 ); - #if defined( MBG_TGT_WIN32 ) - { - __int64 dt_t = htc2.cycles - htc1.cycles; - delta_cyc = (double) dt_t / (__int64) cyc_freq; - } - #else - delta_cyc = ( (double) ( htc2.cycles - htc1.cycles ) ) / cyc_freq; - #endif - delta_t = delta_ts - delta_cyc; + n += snprintf_safe( &ws[n], sizeof( ws ) - n, " ts: %.1f us, cyc: %.1f us, delta: %s", + delta_ts * 1e6, delta_cyc * 1e6, ws3 ); - n += snprintf( &ws[n], sizeof( ws ) - n, " ts: %.1f us, cyc: %.1f us, delta: %+.1f us", - delta_ts * 1e6, delta_cyc * 1e6, delta_t * 1e6 ); + add_marker = 0; if ( ( warn_limit > 0.0 ) && ( fabs( delta_t ) > warn_limit ) ) - n += snprintf( &ws[n], sizeof( ws ) - n, " *" ); + { + n += sn_cpy_str_safe( &ws[n], sizeof( ws ) - n, " *" ); + add_marker = 1; + } if ( prv_delta_t_avail ) { double ddelta_t = delta_t - prv_delta_t; if ( ( chk_limit > 0.0 ) && ( fabs( ddelta_t ) > chk_limit ) ) - n += snprintf( &ws[n], sizeof( ws ) - n, " <<" ); + { + n += sn_cpy_str_safe( &ws[n], sizeof( ws ) - n, " <<" ); + add_marker = 1; + } + + if ( check_status ) + { + if ( ( htc1.t.status != prv_htc1.t.status ) + || ( htc2.t.status != prv_htc2.t.status ) ) + { + n += sn_cpy_str_safe( &ws[n], sizeof( ws ) - n, " #" ); + add_marker = 1; + } + } } #if defined( DEBUG ) if ( htc2.t.tstamp.sec != htc1.t.tstamp.sec ) - n += snprintf( &ws[n], sizeof( ws ) - n, " X" ); + { + n += sn_cpy_str_safe( &ws[n], sizeof( ws ) - n, " X" ); + add_marker = 1; + } #endif - printf( "%s\n", ws ); + if ( add_marker ) + n += sn_cpy_str_safe( &ws[n], sizeof( ws ) - n, " !!" ); + + if ( quiet ) + { + // Overwrite last line, and only append new line if the + // current line has a marker appended, so it's visible + // on the console that something unexpected has happened. + printf( "\r%s%s%s", ws, term_clreol, ( add_marker ) ? "\n" : "" ); + } + else + printf( "%s\n", ws ); + + if ( log_fn ) + { + FILE *fp = fopen_log( "a" ); + + if ( fp ) + { + fprintf( fp, "%s\n", ws ); + fclose( fp ); + } + } if ( this_loops > 0 ) this_loops--; @@ -192,6 +244,8 @@ int do_mbgcmptime( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) if ( this_loops == 0 ) break; + prv_htc1 = htc1; + prv_htc2 = htc2; prv_delta_t = delta_t; prv_delta_t_avail = 1; @@ -206,8 +260,6 @@ int do_mbgcmptime( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) } done: - mbg_close_device( &dh ); - return rc; } // do_mbgcmptime @@ -218,25 +270,42 @@ static /*HDR*/ void usage( void ) { mbg_print_usage_intro( pname, - "This example program reads fast high resolution time stamps.\n" - "\n" - "This is done using memory mapped I/O in the kernel driver, so\n" - "this works only with cards which support memory mapped I/O." + "Compare the time on two devices by reading the time stamps plus cycles from\n" + "both devices immediately after each other, and compensate the execution delay\n" + "based on the returned cycles counts.\n" + "The device to be used as reference has to be specified by parameter -i (see\n" + "below), whereas the device under test is specified as last parameter on the\n" + "command line." ); mbg_print_help_options(); - mbg_print_opt_info( "-i dev", "reference device the test card's time shall be compared" ); + mbg_print_opt_info( "-i dev", "reference device the test card's time shall be compared to" ); mbg_print_opt_info( "-l limit", "append a marker '*' to the output if delta exceeds limit [us]" ); mbg_print_opt_info( "-L limit", "append a marker '<<' to the output if delta changes [us]" ); + mbg_print_opt_info( "-C", "append a marker '#' to the output if status changed" ); mbg_print_opt_info( "-f", "read fast (memory mapped) timestamps" ); mbg_print_opt_info( "-c", "run continuously" ); mbg_print_opt_info( "-n num", "run num loops" ); - mbg_print_opt_info( "-b", "burst read" ); mbg_print_opt_info( "-r", "read raw time stamps, no cycles" ); - mbg_print_opt_info( "-s num", "sleep num seconds between calls" ); - mbg_print_opt_info( "-u num", "sleep num microseconds between calls" ); + mbg_print_opt_info( "-s num", "sleep num seconds between calls (implies -c)" ); + mbg_print_opt_info( "-u num", "sleep num microseconds between calls (implies -c)" ); + mbg_print_opt_info( "-o file", "also log output to <file>" ); + mbg_print_opt_info( "-q", "quiet, only log errors to console (use -o to specify file for full log)" ); + mbg_print_opt_info( "-a", "auto-compensate initial offset" ); mbg_print_device_options(); puts( "" ); + printf( "\nExamples:\n\n" ); + printf( + "Run once and compare the time from both /dev/mbgclock1 and /dev/mbgclock2\n" + "to the time from /dev/mbgclock0:\n\n" + " %s -i /dev/mbgclock0 /dev/mbgclock1 /dev/mbgclock2\n\n", pname + ); + printf( + "Run continuously in 1 s intervals and compare the time from /dev/mbgclock1\n" + "to the time from /dev/mbgclock0:\n\n" + " %s -s 1 -i /dev/mbgclock0 /dev/mbgclock1\n\n", pname + ); + } // usage @@ -246,13 +315,21 @@ int main( int argc, char *argv[] ) int rc; int c; - mbg_print_program_info( pname, MBG_MICRO_VERSION, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); + mbg_print_program_info( pname, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); // check command line parameters - while ( ( c = getopt( argc, argv, "i:l:L:fcn:rs:u:h?" ) ) != -1 ) + while ( ( c = getopt( argc, argv, "acCfi:l:L:n:o:qrs:u:h?" ) ) != -1 ) { switch ( c ) { + case 'a': + auto_offset = 1; + break; + + case 'C': + check_status = 1; + break; + case 'i': ref_device_name = optarg; break; @@ -277,16 +354,26 @@ int main( int argc, char *argv[] ) loops = atoi( optarg ); break; + case 'o': + log_fn = optarg; + break; + + case 'q': + quiet = 1; + break; + case 'r': read_raw = 1; break; case 's': sleep_secs = atoi( optarg ); + loops = -1; break; case 'u': sleep_usecs = atoi( optarg ); + loops = -1; break; case 'h': @@ -299,47 +386,58 @@ int main( int argc, char *argv[] ) if ( must_print_usage ) { usage(); - return 1; + return MBG_EXIT_CODE_USAGE; } #if !MBG_TGT_SUPP_MEM_ACC - printf( "** Memory mapped access not supported on this target platform.\n\n" ); - return 1; + fprintf( stderr, "** Memory mapped access not supported on this target platform.\n\n" ); + return MBG_EXIT_CODE_NOT_SUPP; #endif #if !MBG_PC_CYCLES_SUPPORTED - printf( "** Warning: No cycles support to compute real latencies on this platform!\n" ); - return 1; + fprintf( stderr, "** Warning: No cycles support to compute real latencies on this platform!\n" ); + return MBG_EXIT_CODE_NOT_SUPP; #endif + if ( quiet ) // make stdout unbuffered + setvbuf( stdout, NULL, _IONBF, 0 ); + + + if ( log_fn ) + { + // Create new or truncate existing log file. + FILE *fp = fopen_log( "w" ); + + if ( fp ) + fclose( fp ); + } if ( ref_device_name ) { #if defined( MBG_TGT_WIN32 ) - dh_ref = mbg_open_device_by_name( ref_device_name, MBG_MATCH_MODEL); - #else // if defined( MBG_TGT_UNIX ) + dh_ref = mbg_open_device_by_name( ref_device_name, MBG_MATCH_MODEL ); + #else // if defined( MBG_TGT_POSIX ) dh_ref = open( ref_device_name, O_RDONLY ); #endif if ( dh_ref < 0 ) { - fprintf( stderr, "Failed to open ref device %s, exiting.\n", ref_device_name ); + fprintf( stderr, "** Failed to open ref device %s, exiting.\n", ref_device_name ); exit( EXIT_FAILURE ); } #if defined( DEBUG ) fprintf( stderr, "Ref device %s opened successfully.\n", ref_device_name ); #endif + + mbg_get_device_info( dh_ref, &dev_info_ref ); + //##+++ TODO: error checking } - // The function below checks which devices have been specified - // on the command, and for each device - // - tries to open the device - // - shows basic device info - // - calls the function passed as last parameter - rc = mbg_check_devices( argc, argv, optind, do_mbgcmptime ); + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbgcmptime, 0 ); mbg_close_device( &dh_ref ); - return abs( rc ); + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; } diff --git a/test/mbgtcrcal/mbgtcrcal.c b/test/mbgtcrcal/mbgtcrcal.c new file mode 100644 index 0000000..f25c913 --- /dev/null +++ b/test/mbgtcrcal/mbgtcrcal.c @@ -0,0 +1,380 @@ + +/************************************************************************** + * + * $Id: mbgtcrcal.c 1.12 2018/12/11 16:15:39Z martin REL_M $ + * + * Description: + * Main file for mbgtcrcal program which can be used to calibrate + * the IRIG input of some TCR cards. + * + * ----------------------------------------------------------------------- + * $Log: mbgtcrcal.c $ + * Revision 1.12 2018/12/11 16:15:39Z martin + * Fixed compiler warning on Windows. + * Revision 1.11 2018/12/11 11:57:32Z martin + * Fixed compiler warnings on Windows. + * Revision 1.10 2018/11/15 12:39:29Z martin + * Individual MBG_MICRO_VERSION codes are now obsolete. + * Revision 1.9 2017/07/03 17:33:50 martin + * Account for renamed library symbols. + * Revision 1.8 2017/06/22 15:26:55 martin + * Proper return codes and exit codes. + * Revision 1.7 2016/10/20 14:12:42 martin + * Unified usage information. + * Revision 1.6 2016/08/10 12:54:07 martin + * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. + * Revision 1.5 2016/07/22 09:53:54 martin + * Use new, safe library functions. + * Revision 1.4 2013/12/04 10:00:14 martin + * Fixed build under Windows. + * Revision 1.3 2013/07/22 16:26:42Z martin + * Updated a comment. + * Revision 1.2 2013/07/11 08:28:44 martin + * Account for modified function call parameter list. + * Revision 1.1 2012/01/17 14:04:22 martin + * Initial revision. + * + **************************************************************************/ + +// include Meinberg headers +#include <irig_cal.h> +#include <toolutil.h> // common utility functions +#include <str_util.h> + +// include system headers +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <errno.h> + + +#define MBG_FIRST_COPYRIGHT_YEAR 2012 +#define MBG_LAST_COPYRIGHT_YEAR 0 // use default + + +static const char *pname = "mbgtcrcal"; + +static int verbose; + +static const char *icode_rx_names[N_ICODE_RX] = DEFAULT_ICODE_RX_NAMES; +static const char *irig_comp_names[N_IRIG_RX_COMP] = DEFAULT_IRIG_RX_COMP_NAMES; + +static double cal_val; // [microseconds] +static int must_set_cal_val; +static size_t max_label_len; // determined at runtime + + + +static /*HDR*/ +char *str_comp_data( char *s, int max_len, int comp_data ) +{ + div_t dt = div( comp_data, 10 ); + + snprintf_safe( s, max_len, "%i.%i", dt.quot, abs ( dt.rem ) ); + + return s; + +} // str_comp_data + + + +static /*HDR*/ +void print_cal_recs( int num_rec, int curr_group_idx, CAL_REC_IRIG_RX_COMP cal_rec_comp[] ) +{ + int idx; + char ws[20]; + + for ( idx = 0; idx < num_rec; idx++ ) + { + CAL_REC_IRIG_RX_COMP *p = &cal_rec_comp[idx]; + int l = (int) ( max_label_len - strlen( irig_comp_names[idx] ) + 1 ); + + printf( " Signal group %i (%s)%-*c %s", idx, irig_comp_names[idx], l, ':', + str_comp_data( ws, sizeof( ws ), p->comp_data.c[0] ) ); + + if ( verbose ) + { + int i; + + for ( i = 1; i < N_IRIG_RX_COMP_VAL; i++ ) + printf( ", %s", str_comp_data( ws, sizeof( ws ), p->comp_data.c[i] ) ); + } + + printf( " us\n" ); + } + +} // print_cal_recs + + + +static /*HDR*/ +int do_mbgtcrcal( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) +{ + IRIG_INFO irig_rx_info; + CAL_REC_IRIG_RX_COMP cal_rec_comp[N_IRIG_RX_COMP] = { { { 0 } } }; + CAL_REC_IRIG_RX_COMP *p; + int ret_val = MBG_SUCCESS; + int num_rec = 0; + int rc; + uint16_t idx; + char ws[20]; + int curr_group_idx; + + + // check if this device provides an IRIG input + if ( !_pcps_is_irig_rx( p_dev ) ) + { + printf( "This device does not provide an IRIG input.\n" ); + goto done; + } + + + // read the current IRIG input configuration + rc = mbg_get_irig_rx_info( dh, &irig_rx_info ); + + if ( rc != MBG_SUCCESS ) + { + printf( "** Failed to read IRIG RX configuration, rc: %i\n", rc ); + goto done; + } + + + // check if the currently configured IRIG code is supported by this program + if ( irig_rx_info.settings.icode >= N_ICODE_RX ) + { + printf( "IRIG code %i configured on this device exceeds the maximum code supported by this program (%i)!\n", + irig_rx_info.settings.icode, N_ICODE_RX - 1 ); + goto done; + } + + // determine the compensation code group for the current IRIG code + curr_group_idx = mbg_icode_rx_to_group_idx( irig_rx_info.settings.icode ); + + if ( curr_group_idx < 0 ) + printf( "Warning: Unable to assign IRIG RX code %s to a know compensation code group.\n", + icode_rx_names[irig_rx_info.settings.icode] ); + + // We may continue here and display the current settings, + // but we will not be able to assign and save new settings. + + + if ( !_pcps_has_generic_io( p_dev ) ) + { + printf( "This device does not support IRIG calibration\n" ); + goto done; + } + + + // read current compensation settings + rc = mbg_get_cal_rec_irig_rx_num_rec( dh, &num_rec ); + + #if defined( DEBUG ) + printf( "mbg_get_cal_rec_irig_rx_num_rec() returned %i", rc ); + + if ( rc == MBG_SUCCESS ) + printf( ", irig_rx_num_rec: %i", num_rec ); + + printf( "\n" ); + #endif + + if ( rc != MBG_SUCCESS ) + { + printf( "** Failed to read number of IRIG RX calibration records, rc: %i\n", rc ); + goto done; + } + + + // do some plausibility checks + + if ( curr_group_idx >= num_rec ) + { + printf( "** Warning: the compensation group index for the current IRIG code (%i)\n" + "exceeds the number of records supported by the card (%i).\n", + curr_group_idx, num_rec - 1 ); + } + + + if ( num_rec > N_IRIG_RX_COMP ) + { + printf( "** The number of calibration records actually supported by the card (%i)\n" + "exceeds the number of records supported by this program (%i).\n", + num_rec, N_IRIG_RX_COMP ); + num_rec = N_IRIG_RX_COMP; + } + + + if ( num_rec == 0 ) + { + printf( "** This card does not support any IRIG RX calibration records\n" ); + goto done; + } + + + // determine the maximum length of the group names to be displayed later + for ( idx = 0; idx < num_rec; idx++ ) + { + size_t l = strlen( irig_comp_names[idx] ); + + if ( l > max_label_len ) + max_label_len = l; + } + + + for ( idx = 0; idx < num_rec; idx++ ) + { + p = &cal_rec_comp[idx]; + + rc = mbg_get_cal_rec_irig_rx_comp( dh, idx, p ); + + if ( rc != MBG_SUCCESS ) + { + printf( "** Failed to read IRIG RX calibration record #%i. rc = %i\n", idx, rc ); + goto done; + } + + if ( p->hdr.type != CAL_REC_TYPE_IRIG_RX_COMP ) + { + printf( "** Calibration record header type is %i, no %i as expected.\n", + p->hdr.type, CAL_REC_TYPE_IRIG_RX_COMP ); + goto done; + } + } + + printf( "\nCurrent compensation settings:\n" ); + + print_cal_recs( num_rec, curr_group_idx, cal_rec_comp ); + + printf( "\nCurrent IRIG code: %s --> group %i compensation effective\n", + icode_rx_names[irig_rx_info.settings.icode], + curr_group_idx ); + + if ( !must_set_cal_val ) + goto done; + + if ( curr_group_idx < 0 ) + goto done; + + if ( curr_group_idx >= num_rec ) + goto done; + + + printf( "\n" ); + + // save new calibration setting effective for the current IRIG code + p = &cal_rec_comp[curr_group_idx]; + p->hdr.type = CAL_REC_TYPE_IRIG_RX_COMP; // just to be sure + memset( &p->comp_data, 0, sizeof( p->comp_data ) ); + p->comp_data.c[0] = (int16_t) ( cal_val * 10 ); // us to hns + + rc = mbg_set_cal_rec_irig_rx_comp( dh, p ); + + if ( rc != MBG_SUCCESS ) + { + printf( "** Failed to save new IRIG calibration setting for group %s.\n", + irig_comp_names[curr_group_idx] ); + goto done; + } + + + printf( "IRIG calibration setting for code group %s has been set to %s us.\n", + irig_comp_names[curr_group_idx], str_comp_data( ws, sizeof( ws ), p->comp_data.c[0] ) ); + + +done: + mbg_close_device( &dh ); + + return ret_val; + +} // do_mbgtcrcal + + + +static /*HDR*/ +void usage( void ) +{ + char ws[20]; + + mbg_print_usage_intro( pname, + "Show or set IRIG RX calibration parameters of devices which support this." ); + + mbg_print_help_options(); + mbg_print_opt_info( "-c val", "set calibration value \'val\'" ); + mbg_print_opt_info( "-v", "increase verbosity" ); + puts( "" ); + + printf( "Example usage:\n" + "\n" + "%s -c 10 compensate +10.0 us on default device\n" + "%s -c -12.1 [dev] compensate -12.1 us on specific device [dev]\n" + "\n" + "where [dev] can be e.g. \"%s\" or \"%s\", depending on the installed card(s)\n", + pname, pname, EXAMPLE_DEV_NAME_1_TCR, EXAMPLE_DEV_NAME_2 ); + puts( "" ); + + printf( "New settings become effective for a group of IRIG codes with similar characteristics\n" + "to which the currently configured IRIG RX code belongs. Calibration values are\n" + "in microseconds, with 0.1 us resolution, in the range +/-%s us.\n", + str_comp_data( ws, sizeof( ws ), IRIG_RX_COMP_MAX ) + ); + puts( "" ); + +} // usage + + + +int main( int argc, char *argv[] ) +{ + int rc; + int c; + + mbg_print_program_info( pname, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); + + // check command line parameters + while ( ( c = getopt( argc, argv, "c:vh?" ) ) != -1 ) + { + switch ( c ) + { + case 'c': + cal_val = atof( optarg ); + must_set_cal_val = 1; + break; + + case 'v': + verbose++; + break; + + case 'h': + case '?': + default: + must_print_usage = 1; + } + } + + #if defined( MBG_TGT_POSIX ) + if ( geteuid() != 0 ) + must_print_usage = 1; + #endif + + if ( must_print_usage ) + { + printf( "This program must be run " ROOT_PRIVILEGES_STR " to work correctly.\n" ); + #if defined( DEBUG ) + if ( !must_print_usage ) + printf( "(Built with DEBUG, so resuming anyway)\n" ); + #else + must_print_usage = 1; + #endif + printf( "\n" ); + } + + if ( must_print_usage ) + { + usage(); + return MBG_EXIT_CODE_USAGE; + } + + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbgtcrcal, 0 ); + + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; +} diff --git a/vc6/mbgcmptime/mbgcmptime.dsp b/vc6/mbgcmptime/mbgcmptime.dsp index 6ad0884..d1c2b2f 100644 --- a/vc6/mbgcmptime/mbgcmptime.dsp +++ b/vc6/mbgcmptime/mbgcmptime.dsp @@ -50,7 +50,7 @@ BSC32=bscmake.exe # ADD BSC32 /nologo LINK32=link.exe # ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 -# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbgcmptime.exe" +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbgcmptime.exe" !ELSEIF "$(CFG)" == "mbgcmptime - Win32 Debug" @@ -74,7 +74,7 @@ BSC32=bscmake.exe # ADD BSC32 /nologo LINK32=link.exe # ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /pdbtype:sept -# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbgcmptime.exe" /pdbtype:sept +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbgcmptime.exe" /pdbtype:sept !ENDIF @@ -87,10 +87,38 @@ LINK32=link.exe # PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat" # Begin Source File +SOURCE=..\..\mbglib\common\cfg_hlp.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\cmp_time_util.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\deviohlp.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\lan_util.c +# End Source File +# Begin Source File + SOURCE=..\..\test\mbgcmptime\mbgcmptime.c # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgerror.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.c +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\toolutil.c # End Source File # Begin Source File @@ -103,14 +131,42 @@ SOURCE=..\..\mbglib\win32\wingetopt.c # PROP Default_Filter "h;hpp;hxx;hm;inl" # Begin Source File +SOURCE=..\..\mbglib\common\cfg_hlp.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\cmp_time_util.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\deviohlp.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\gpsdefs.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\lan_util.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbg_arch.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbg_cof.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_klist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_serclock_cfg.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbg_tgt.h # End Source File # Begin Source File @@ -119,6 +175,10 @@ SOURCE=..\..\mbglib\win32\mbg_w32.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgadjtm_cfg.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgdevio.h # End Source File # Begin Source File @@ -131,6 +191,14 @@ SOURCE=..\..\mbglib\common\mbggeo.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgioctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgklist.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgmutex.h # End Source File # Begin Source File @@ -139,14 +207,42 @@ SOURCE=..\..\mbglib\common\mbgpccyc.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\win32\mbgsvcio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgsystm.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgtime.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgutil.h +# End Source File +# Begin Source File + SOURCE=..\..\mbgversion.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\myutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\parmgps.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\parmpcps.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\pci_asic.h # End Source File # Begin Source File @@ -159,10 +255,30 @@ SOURCE=..\..\mbglib\common\pcpsdev.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\pcpsiobf.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\pcpsutil.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\win32\rs232.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\timecnv.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\toolutil.h # End Source File # Begin Source File @@ -190,5 +306,9 @@ SOURCE=..\..\mbglib\common\words.h SOURCE=..\..\mbglib\lib\msc\mbgdevio.lib # End Source File +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgutil.lib +# End Source File # End Target # End Project diff --git a/vc6/mbgctrl/mbgctrl.dsp b/vc6/mbgctrl/mbgctrl.dsp index b69af7b..7eacdb1 100644 --- a/vc6/mbgctrl/mbgctrl.dsp +++ b/vc6/mbgctrl/mbgctrl.dsp @@ -50,7 +50,7 @@ BSC32=bscmake.exe # ADD BSC32 /nologo LINK32=link.exe # ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 -# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbgctrl.exe" +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbgctrl.exe" !ELSEIF "$(CFG)" == "mbgctrl - Win32 Debug" @@ -66,7 +66,7 @@ LINK32=link.exe # PROP Ignore_Export_Lib 0 # PROP Target_Dir "" # ADD BASE CPP /nologo /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /GZ /c -# ADD CPP /nologo /W3 /Gm /GX /ZI /Od /I "..\.." /I "..\..\mbgctrl" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /GZ /c +# ADD CPP /nologo /W3 /Gm /GX /ZI /Od /I "..\.." /I "..\..\mbgctrl" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /FR /YX /FD /GZ /c # ADD BASE RSC /l 0x407 /d "_DEBUG" # ADD RSC /l 0x407 /d "_DEBUG" BSC32=bscmake.exe @@ -74,7 +74,7 @@ BSC32=bscmake.exe # ADD BSC32 /nologo LINK32=link.exe # ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /pdbtype:sept -# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbgctrl.exe" /pdbtype:sept +# ADD LINK32 ws2_32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbgctrl.exe" /pdbtype:sept !ENDIF @@ -87,6 +87,10 @@ LINK32=link.exe # PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat" # Begin Source File +SOURCE=..\..\mbglib\common\cfg_hlp.c +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\deviohlp.c # End Source File # Begin Source File @@ -99,15 +103,15 @@ SOURCE=..\..\mbgctrl\mbgctrl.c # End Source File # Begin Source File -SOURCE=..\..\mbglib\common\parmgps.c +SOURCE=..\..\mbglib\common\mbgerror.c # End Source File # Begin Source File -SOURCE=..\..\mbglib\common\parmpcps.c +SOURCE=..\..\mbglib\common\str_util.c # End Source File # Begin Source File -SOURCE=..\..\mbglib\common\pcpsutil.c +SOURCE=..\..\mbglib\common\timeutil.c # End Source File # Begin Source File @@ -123,14 +127,46 @@ SOURCE=..\..\mbglib\win32\wingetopt.c # PROP Default_Filter "h;hpp;hxx;hm;inl" # Begin Source File +SOURCE=..\..\mbglib\common\cfg_hlp.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\cnv_wday.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\deviohlp.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\gpsdefs.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\gpsutils.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\lan_util.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbg_arch.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbg_cof.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_klist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_serclock_cfg.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbg_tgt.h # End Source File # Begin Source File @@ -139,6 +175,10 @@ SOURCE=..\..\mbglib\win32\mbg_w32.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgadjtm_cfg.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgdevio.h # End Source File # Begin Source File @@ -151,6 +191,14 @@ SOURCE=..\..\mbglib\common\mbggeo.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgioctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgklist.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgmutex.h # End Source File # Begin Source File @@ -159,14 +207,34 @@ SOURCE=..\..\mbglib\common\mbgpccyc.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\win32\mbgsvcio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgsystm.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgtime.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgutil.h +# End Source File +# Begin Source File + SOURCE=..\..\mbgversion.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\myutil.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\pci_asic.h # End Source File # Begin Source File @@ -179,10 +247,38 @@ SOURCE=..\..\mbglib\common\pcpsdev.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\pcpsiobf.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsmktm.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\pcpsutil.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\ptp_util.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\rs232.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\timecnv.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\toolutil.h # End Source File # Begin Source File @@ -210,5 +306,9 @@ SOURCE=..\..\mbglib\common\words.h SOURCE=..\..\mbglib\lib\msc\mbgdevio.lib # End Source File +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgutil.lib +# End Source File # End Target # End Project diff --git a/vc6/mbgfasttstamp/mbgfasttstamp.dsp b/vc6/mbgfasttstamp/mbgfasttstamp.dsp index b25ae74..be051f5 100644 --- a/vc6/mbgfasttstamp/mbgfasttstamp.dsp +++ b/vc6/mbgfasttstamp/mbgfasttstamp.dsp @@ -50,7 +50,7 @@ BSC32=bscmake.exe # ADD BSC32 /nologo LINK32=link.exe # ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 -# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbgfasttstamp.exe" +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbgfasttstamp.exe" !ELSEIF "$(CFG)" == "mbgfasttstamp - Win32 Debug" @@ -74,7 +74,7 @@ BSC32=bscmake.exe # ADD BSC32 /nologo LINK32=link.exe # ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /pdbtype:sept -# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbgfasttstamp.exe" /pdbtype:sept +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbgfasttstamp.exe" /pdbtype:sept !ENDIF @@ -87,10 +87,26 @@ LINK32=link.exe # PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat" # Begin Source File +SOURCE=..\..\mbglib\common\cfg_hlp.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgerror.c +# End Source File +# Begin Source File + SOURCE=..\..\mbgfasttstamp\mbgfasttstamp.c # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\str_util.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.c +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\toolutil.c # End Source File # Begin Source File @@ -103,6 +119,10 @@ SOURCE=..\..\mbglib\win32\wingetopt.c # PROP Default_Filter "h;hpp;hxx;hm;inl" # Begin Source File +SOURCE=..\..\mbglib\common\cfg_hlp.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\gpsdefs.h # End Source File # Begin Source File @@ -111,6 +131,18 @@ SOURCE=..\..\mbglib\common\mbg_arch.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbg_cof.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_klist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_serclock_cfg.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbg_tgt.h # End Source File # Begin Source File @@ -119,6 +151,10 @@ SOURCE=..\..\mbglib\win32\mbg_w32.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgadjtm_cfg.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgdevio.h # End Source File # Begin Source File @@ -131,6 +167,14 @@ SOURCE=..\..\mbglib\common\mbggeo.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgioctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgklist.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgmutex.h # End Source File # Begin Source File @@ -139,14 +183,34 @@ SOURCE=..\..\mbglib\common\mbgpccyc.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\win32\mbgsvcio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgsystm.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgtime.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgutil.h +# End Source File +# Begin Source File + SOURCE=..\..\mbgversion.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\myutil.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\pci_asic.h # End Source File # Begin Source File @@ -159,10 +223,30 @@ SOURCE=..\..\mbglib\common\pcpsdev.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\pcpsiobf.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\pcpsutil.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\win32\rs232.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\timecnv.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\toolutil.h # End Source File # Begin Source File @@ -190,5 +274,9 @@ SOURCE=..\..\mbglib\common\words.h SOURCE=..\..\mbglib\lib\msc\mbgdevio.lib # End Source File +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgutil.lib +# End Source File # End Target # End Project diff --git a/vc6/mbggpscap/mbggpscap.dsp b/vc6/mbggpscap/mbggpscap.dsp index eae5591..c59afc0 100644 --- a/vc6/mbggpscap/mbggpscap.dsp +++ b/vc6/mbggpscap/mbggpscap.dsp @@ -50,7 +50,7 @@ BSC32=bscmake.exe # ADD BSC32 /nologo LINK32=link.exe # ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 -# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbggpscap.exe" +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbggpscap.exe" !ELSEIF "$(CFG)" == "mbggpscap - Win32 Debug" @@ -74,7 +74,7 @@ BSC32=bscmake.exe # ADD BSC32 /nologo LINK32=link.exe # ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /pdbtype:sept -# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbggpscap.exe" /pdbtype:sept +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbggpscap.exe" /pdbtype:sept !ENDIF @@ -87,10 +87,34 @@ LINK32=link.exe # PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat" # Begin Source File +SOURCE=..\..\mbglib\common\cfg_hlp.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\deviohlp.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\lan_util.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgerror.c +# End Source File +# Begin Source File + SOURCE=..\..\mbggpscap\mbggpscap.c # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\str_util.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.c +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\toolutil.c # End Source File # Begin Source File @@ -103,14 +127,42 @@ SOURCE=..\..\mbglib\win32\wingetopt.c # PROP Default_Filter "h;hpp;hxx;hm;inl" # Begin Source File +SOURCE=..\..\mbglib\common\cfg_hlp.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\deviohlp.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\gpsdefs.h # End Source File # Begin Source File +SOURCE=..\..\..\..\..\..\..\WINDDK\2600\inc\w2k\guiddef.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\lan_util.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbg_arch.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbg_cof.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_klist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_serclock_cfg.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbg_tgt.h # End Source File # Begin Source File @@ -119,6 +171,10 @@ SOURCE=..\..\mbglib\win32\mbg_w32.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgadjtm_cfg.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgdevio.h # End Source File # Begin Source File @@ -131,6 +187,14 @@ SOURCE=..\..\mbglib\common\mbggeo.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgioctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgklist.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgmutex.h # End Source File # Begin Source File @@ -139,14 +203,34 @@ SOURCE=..\..\mbglib\common\mbgpccyc.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\win32\mbgsvcio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgsystm.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgtime.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgutil.h +# End Source File +# Begin Source File + SOURCE=..\..\mbgversion.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\myutil.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\pci_asic.h # End Source File # Begin Source File @@ -159,10 +243,30 @@ SOURCE=..\..\mbglib\common\pcpsdev.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\pcpsiobf.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\pcpsutil.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\win32\rs232.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\timecnv.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\toolutil.h # End Source File # Begin Source File @@ -190,5 +294,9 @@ SOURCE=..\..\mbglib\common\words.h SOURCE=..\..\mbglib\lib\msc\mbgdevio.lib # End Source File +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgutil.lib +# End Source File # End Target # End Project diff --git a/vc6/mbghrtime/mbghrtime.dsp b/vc6/mbghrtime/mbghrtime.dsp index 6d5415b..34277c3 100644 --- a/vc6/mbghrtime/mbghrtime.dsp +++ b/vc6/mbghrtime/mbghrtime.dsp @@ -50,7 +50,7 @@ BSC32=bscmake.exe # ADD BSC32 /nologo LINK32=link.exe # ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 -# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbghrtime.exe" +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbghrtime.exe" !ELSEIF "$(CFG)" == "mbghrtime - Win32 Debug" @@ -74,7 +74,7 @@ BSC32=bscmake.exe # ADD BSC32 /nologo LINK32=link.exe # ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /pdbtype:sept -# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbghrtime.exe" /pdbtype:sept +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbghrtime.exe" /pdbtype:sept !ENDIF @@ -87,10 +87,26 @@ LINK32=link.exe # PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat" # Begin Source File +SOURCE=..\..\mbglib\common\cfg_hlp.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgerror.c +# End Source File +# Begin Source File + SOURCE=..\..\mbghrtime\mbghrtime.c # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\str_util.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.c +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\toolutil.c # End Source File # Begin Source File @@ -103,6 +119,10 @@ SOURCE=..\..\mbglib\win32\wingetopt.c # PROP Default_Filter "h;hpp;hxx;hm;inl" # Begin Source File +SOURCE=..\..\mbglib\common\cfg_hlp.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\gpsdefs.h # End Source File # Begin Source File @@ -111,6 +131,18 @@ SOURCE=..\..\mbglib\common\mbg_arch.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbg_cof.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_klist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_serclock_cfg.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbg_tgt.h # End Source File # Begin Source File @@ -119,6 +151,10 @@ SOURCE=..\..\mbglib\win32\mbg_w32.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgadjtm_cfg.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgdevio.h # End Source File # Begin Source File @@ -131,6 +167,14 @@ SOURCE=..\..\mbglib\common\mbggeo.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgioctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgklist.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgmutex.h # End Source File # Begin Source File @@ -139,14 +183,34 @@ SOURCE=..\..\mbglib\common\mbgpccyc.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\win32\mbgsvcio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgsystm.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\mbgtime.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgutil.h +# End Source File +# Begin Source File + SOURCE=..\..\mbgversion.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\myutil.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\pci_asic.h # End Source File # Begin Source File @@ -159,10 +223,30 @@ SOURCE=..\..\mbglib\common\pcpsdev.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\pcpsiobf.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\pcpsutil.h # End Source File # Begin Source File +SOURCE=..\..\mbglib\win32\rs232.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\timecnv.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.h +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\toolutil.h # End Source File # Begin Source File @@ -190,5 +274,9 @@ SOURCE=..\..\mbglib\common\words.h SOURCE=..\..\mbglib\lib\msc\mbgdevio.lib # End Source File +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgutil.lib +# End Source File # End Target # End Project diff --git a/vc6/mbgirigcfg/mbgirigcfg.dsp b/vc6/mbgirigcfg/mbgirigcfg.dsp new file mode 100644 index 0000000..f0e9c58 --- /dev/null +++ b/vc6/mbgirigcfg/mbgirigcfg.dsp @@ -0,0 +1,310 @@ +# Microsoft Developer Studio Project File - Name="mbgirigcfg" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Console Application" 0x0103 + +CFG=mbgirigcfg - Win32 Debug +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mbgirigcfg.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mbgirigcfg.mak" CFG="mbgirigcfg - Win32 Debug" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mbgirigcfg - Win32 Release" (based on "Win32 (x86) Console Application") +!MESSAGE "mbgirigcfg - Win32 Debug" (based on "Win32 (x86) Console Application") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mbgirigcfg - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /c +# ADD CPP /nologo /W3 /GX /O2 /I "..\.." /I "..\..\mbgirigcfg" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /c +# ADD BASE RSC /l 0x407 /d "NDEBUG" +# ADD RSC /l 0x407 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbgirigcfg.exe" + +!ELSEIF "$(CFG)" == "mbgirigcfg - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /GZ /c +# ADD CPP /nologo /W3 /Gm /GX /ZI /Od /I "..\.." /I "..\..\mbgirigcfg" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /GZ /c +# ADD BASE RSC /l 0x407 /d "_DEBUG" +# ADD RSC /l 0x407 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /pdbtype:sept +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbgirigcfg.exe" /pdbtype:sept + +!ENDIF + +# Begin Target + +# Name "mbgirigcfg - Win32 Release" +# Name "mbgirigcfg - Win32 Debug" +# Begin Group "Source Files" + +# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat" +# Begin Source File + +SOURCE=..\..\mbglib\common\cfg_hlp.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgerror.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbgirigcfg\mbgirigcfg.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\toolutil.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\wingetopt.c +# End Source File +# End Group +# Begin Group "Header Files" + +# PROP Default_Filter "h;hpp;hxx;hm;inl" +# Begin Source File + +SOURCE=..\..\mbglib\common\cfg_hlp.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\charcode.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\cnv_wday.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\ctry.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\ctrydttm.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\gpsdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_arch.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_cof.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_klist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_serclock_cfg.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_tgt.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbg_w32.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgadjtm_cfg.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgdevio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgerror.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbggeo.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgioctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgklist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgmutex.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgpccyc.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvcio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgsystm.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgtime.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbgversion.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\myutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\parmpcps.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pci_asic.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsdev.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsiobf.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpslstr.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsmktm.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\rs232.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\timecnv.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\toolutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\usbdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\use_pack.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\wingetopt.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\words.h +# End Source File +# End Group +# Begin Group "Resource Files" + +# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe" +# End Group +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgdevio.lib +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgutil.lib +# End Source File +# End Target +# End Project diff --git a/vc6/mbgsetsystime/mbgsetsystime.dsp b/vc6/mbgsetsystime/mbgsetsystime.dsp new file mode 100644 index 0000000..ef2e38e --- /dev/null +++ b/vc6/mbgsetsystime/mbgsetsystime.dsp @@ -0,0 +1,302 @@ +# Microsoft Developer Studio Project File - Name="mbgsetsystime" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Console Application" 0x0103 + +CFG=mbgsetsystime - Win32 Debug +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mbgsetsystime.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mbgsetsystime.mak" CFG="mbgsetsystime - Win32 Debug" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mbgsetsystime - Win32 Release" (based on "Win32 (x86) Console Application") +!MESSAGE "mbgsetsystime - Win32 Debug" (based on "Win32 (x86) Console Application") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mbgsetsystime - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /c +# ADD CPP /nologo /W3 /GX /O2 /I "..\.." /I "..\..\mbgsetsystime" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /c +# ADD BASE RSC /l 0x407 /d "NDEBUG" +# ADD RSC /l 0x407 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbgsetsystime.exe" + +!ELSEIF "$(CFG)" == "mbgsetsystime - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /GZ /c +# ADD CPP /nologo /W3 /Gm /GX /ZI /Od /I "..\.." /I "..\..\mbgsetsystime" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /FR /YX /FD /GZ /c +# ADD BASE RSC /l 0x407 /d "_DEBUG" +# ADD RSC /l 0x407 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /pdbtype:sept +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbgsetsystime.exe" /pdbtype:sept + +!ENDIF + +# Begin Target + +# Name "mbgsetsystime - Win32 Release" +# Name "mbgsetsystime - Win32 Debug" +# Begin Group "Source Files" + +# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat" +# Begin Source File + +SOURCE=..\..\mbglib\common\cfg_hlp.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgerror.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgmktm.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbgsetsystime\mbgsetsystime.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsmktm.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\toolutil.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\wingetopt.c +# End Source File +# End Group +# Begin Group "Header Files" + +# PROP Default_Filter "h;hpp;hxx;hm;inl" +# Begin Source File + +SOURCE=..\..\mbglib\common\cfg_hlp.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\gpsdefs.h +# End Source File +# Begin Source File + +SOURCE="..\..\..\..\..\..\ms-ddk\2600\inc\w2k\guiddef.h" +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_arch.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_cof.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_klist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_serclock_cfg.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_tgt.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbg_w32.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgadjtm_cfg.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgdevio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgerror.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbggeo.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgioctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgklist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgmktm.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgmutex.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgpccyc.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvcio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgsystm.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgtime.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbgversion.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\myutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pci_asic.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsdev.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsiobf.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsmktm.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\rs232.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\timecnv.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\toolutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\usbdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\use_pack.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\wingetopt.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\words.h +# End Source File +# End Group +# Begin Group "Resource Files" + +# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe" +# End Group +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgdevio.lib +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgutil.lib +# End Source File +# End Target +# End Project diff --git a/vc6/mbgshowsignal/mbgshowsignal.dsp b/vc6/mbgshowsignal/mbgshowsignal.dsp new file mode 100644 index 0000000..92bf62a --- /dev/null +++ b/vc6/mbgshowsignal/mbgshowsignal.dsp @@ -0,0 +1,282 @@ +# Microsoft Developer Studio Project File - Name="mbgshowsignal" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Console Application" 0x0103 + +CFG=mbgshowsignal - Win32 Debug +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mbgshowsignal.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mbgshowsignal.mak" CFG="mbgshowsignal - Win32 Debug" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mbgshowsignal - Win32 Release" (based on "Win32 (x86) Console Application") +!MESSAGE "mbgshowsignal - Win32 Debug" (based on "Win32 (x86) Console Application") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mbgshowsignal - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /c +# ADD CPP /nologo /W3 /GX /O2 /I "..\.." /I "..\..\mbgshowsignal" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /c +# ADD BASE RSC /l 0x407 /d "NDEBUG" +# ADD RSC /l 0x407 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbgshowsignal.exe" + +!ELSEIF "$(CFG)" == "mbgshowsignal - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /GZ /c +# ADD CPP /nologo /W3 /Gm /GX /ZI /Od /I "..\.." /I "..\..\mbgshowsignal" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /GZ /c +# ADD BASE RSC /l 0x407 /d "_DEBUG" +# ADD RSC /l 0x407 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /pdbtype:sept +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbgshowsignal.exe" /pdbtype:sept + +!ENDIF + +# Begin Target + +# Name "mbgshowsignal - Win32 Release" +# Name "mbgshowsignal - Win32 Debug" +# Begin Group "Source Files" + +# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat" +# Begin Source File + +SOURCE=..\..\mbglib\common\cfg_hlp.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgerror.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbgshowsignal\mbgshowsignal.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\toolutil.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\wingetopt.c +# End Source File +# End Group +# Begin Group "Header Files" + +# PROP Default_Filter "h;hpp;hxx;hm;inl" +# Begin Source File + +SOURCE=..\..\mbglib\common\cfg_hlp.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\gpsdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_arch.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_cof.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_klist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_serclock_cfg.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_tgt.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbg_w32.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgadjtm_cfg.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgdevio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgerror.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbggeo.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgioctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgklist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgmutex.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgpccyc.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvcio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgsystm.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgtime.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbgversion.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\myutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pci_asic.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsdev.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsiobf.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\rs232.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\timecnv.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\toolutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\usbdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\use_pack.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\wingetopt.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\words.h +# End Source File +# End Group +# Begin Group "Resource Files" + +# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe" +# End Group +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgdevio.lib +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgutil.lib +# End Source File +# End Target +# End Project diff --git a/vc6/mbgstatus/mbgstatus.dsp b/vc6/mbgstatus/mbgstatus.dsp index a6b640e..325b266 100644 --- a/vc6/mbgstatus/mbgstatus.dsp +++ b/vc6/mbgstatus/mbgstatus.dsp @@ -42,7 +42,7 @@ RSC=rc.exe # PROP Ignore_Export_Lib 0 # PROP Target_Dir "" # ADD BASE CPP /nologo /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /c -# ADD CPP /nologo /W3 /GX /O2 /I "..\.." /I "..\..\mbgstatus" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /c +# ADD CPP /nologo /W3 /GX /O2 /I "..\.." /I "..\..\mbgstatus" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /FR /YX /FD /c # ADD BASE RSC /l 0x407 /d "NDEBUG" # ADD RSC /l 0x407 /d "NDEBUG" BSC32=bscmake.exe @@ -50,7 +50,7 @@ BSC32=bscmake.exe # ADD BSC32 /nologo LINK32=link.exe # ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 -# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbgstatus.exe" +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbgstatus.exe" !ELSEIF "$(CFG)" == "mbgstatus - Win32 Debug" @@ -66,7 +66,7 @@ LINK32=link.exe # PROP Ignore_Export_Lib 0 # PROP Target_Dir "" # ADD BASE CPP /nologo /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /GZ /c -# ADD CPP /nologo /W3 /Gm /GX /ZI /Od /I "..\.." /I "..\..\mbgstatus" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /GZ /c +# ADD CPP /nologo /W3 /Gm /GX /ZI /Od /I "..\.." /I "..\..\mbgstatus" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /FR /YX /FD /GZ /c # ADD BASE RSC /l 0x407 /d "_DEBUG" # ADD RSC /l 0x407 /d "_DEBUG" BSC32=bscmake.exe @@ -74,7 +74,7 @@ BSC32=bscmake.exe # ADD BSC32 /nologo LINK32=link.exe # ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /pdbtype:sept -# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbgstatus.exe" /pdbtype:sept +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbgstatus.exe" /pdbtype:sept !ENDIF @@ -87,6 +87,10 @@ LINK32=link.exe # PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat" # Begin Source File +SOURCE=..\..\mbglib\common\cfg_hlp.c +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\ctry.c # End Source File # Begin Source File @@ -95,18 +99,42 @@ SOURCE=..\..\mbglib\common\ctrydttm.c # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\deviohlp.c +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\lan_util.c # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\mbgerror.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgmktm.c +# End Source File +# Begin Source File + SOURCE=..\..\mbgstatus\mbgstatus.c # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\nanotime.c +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\pcpslstr.c # End Source File # Begin Source File +SOURCE=..\..\mbglib\common\str_util.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.c +# End Source File +# Begin Source File + SOURCE=..\..\mbglib\common\toolutil.c # End Source File # Begin Source File @@ -117,6 +145,190 @@ SOURCE=..\..\mbglib\win32\wingetopt.c # Begin Group "Header Files" # PROP Default_Filter "h;hpp;hxx;hm;inl" +# Begin Source File + +SOURCE=..\..\mbglib\common\cfg_hlp.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\charcode.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\cnv_wday.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\ctry.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\ctrydttm.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\deviohlp.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\gpsdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\lan_util.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_arch.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_cof.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_klist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_serclock_cfg.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_tgt.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbg_w32.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgadjtm_cfg.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgdevio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgerror.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbggeo.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgioctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgklist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgmktm.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgmutex.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgpccyc.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvcio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgsystm.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgtime.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbgversion.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\myutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\nanotime.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pci_asic.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsdev.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsiobf.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpslstr.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\rs232.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\timecnv.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\toolutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\usbdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\use_pack.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\wingetopt.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\words.h +# End Source File # End Group # Begin Group "Resource Files" @@ -126,5 +338,9 @@ SOURCE=..\..\mbglib\win32\wingetopt.c SOURCE=..\..\mbglib\lib\msc\mbgdevio.lib # End Source File +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgutil.lib +# End Source File # End Target # End Project diff --git a/vc6/mbgtcrcal/mbgtcrcal.dsp b/vc6/mbgtcrcal/mbgtcrcal.dsp new file mode 100644 index 0000000..00ee173 --- /dev/null +++ b/vc6/mbgtcrcal/mbgtcrcal.dsp @@ -0,0 +1,286 @@ +# Microsoft Developer Studio Project File - Name="mbgtcrcal" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Console Application" 0x0103 + +CFG=mbgtcrcal - Win32 Debug +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mbgtcrcal.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mbgtcrcal.mak" CFG="mbgtcrcal - Win32 Debug" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mbgtcrcal - Win32 Release" (based on "Win32 (x86) Console Application") +!MESSAGE "mbgtcrcal - Win32 Debug" (based on "Win32 (x86) Console Application") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mbgtcrcal - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /c +# ADD CPP /nologo /W3 /GX /O2 /I "..\.." /I "..\..\mbgtcrcal" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /c +# ADD BASE RSC /l 0x407 /d "NDEBUG" +# ADD RSC /l 0x407 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbgtcrcal.exe" + +!ELSEIF "$(CFG)" == "mbgtcrcal - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /GZ /c +# ADD CPP /nologo /W3 /Gm /GX /ZI /Od /I "..\.." /I "..\..\mbgtcrcal" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /GZ /c +# ADD BASE RSC /l 0x407 /d "_DEBUG" +# ADD RSC /l 0x407 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /pdbtype:sept +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbgtcrcal.exe" /pdbtype:sept + +!ENDIF + +# Begin Target + +# Name "mbgtcrcal - Win32 Release" +# Name "mbgtcrcal - Win32 Debug" +# Begin Group "Source Files" + +# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat" +# Begin Source File + +SOURCE=..\..\mbglib\common\cfg_hlp.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgerror.c +# End Source File +# Begin Source File + +SOURCE=..\..\test\mbgtcrcal\mbgtcrcal.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\toolutil.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\wingetopt.c +# End Source File +# End Group +# Begin Group "Header Files" + +# PROP Default_Filter "h;hpp;hxx;hm;inl" +# Begin Source File + +SOURCE=..\..\mbglib\common\cfg_hlp.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\gpsdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\irig_cal.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_arch.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_cof.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_klist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_serclock_cfg.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_tgt.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbg_w32.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgadjtm_cfg.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgdevio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgerror.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbggeo.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgioctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgklist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgmutex.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgpccyc.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvcio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgsystm.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgtime.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbgversion.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\myutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pci_asic.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsdev.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsiobf.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\rs232.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\timecnv.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\toolutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\usbdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\use_pack.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\wingetopt.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\words.h +# End Source File +# End Group +# Begin Group "Resource Files" + +# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe" +# End Group +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgdevio.lib +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgutil.lib +# End Source File +# End Target +# End Project diff --git a/vc6/mbgtools-win.dsw b/vc6/mbgtools-win.dsw index d3fb367..4fad013 100644 --- a/vc6/mbgtools-win.dsw +++ b/vc6/mbgtools-win.dsw @@ -63,6 +63,42 @@ Package=<4> ############################################################################### +Project: "mbgirigcfg"=".\mbgirigcfg\mbgirigcfg.dsp" - Package Owner=<4> + +Package=<5> +{{{ +}}} + +Package=<4> +{{{ +}}} + +############################################################################### + +Project: "mbgsetsystime"=".\mbgsetsystime\mbgsetsystime.dsp" - Package Owner=<4> + +Package=<5> +{{{ +}}} + +Package=<4> +{{{ +}}} + +############################################################################### + +Project: "mbgshowsignal"=".\mbgshowsignal\mbgshowsignal.dsp" - Package Owner=<4> + +Package=<5> +{{{ +}}} + +Package=<4> +{{{ +}}} + +############################################################################### + Project: "mbgstatus"=".\mbgstatus\mbgstatus.dsp" - Package Owner=<4> Package=<5> @@ -75,6 +111,30 @@ Package=<4> ############################################################################### +Project: "mbgtcrcal"=".\mbgtcrcal\mbgtcrcal.dsp" - Package Owner=<4> + +Package=<5> +{{{ +}}} + +Package=<4> +{{{ +}}} + +############################################################################### + +Project: "mbgxhrtime"=".\mbgxhrtime\mbgxhrtime.dsp" - Package Owner=<4> + +Package=<5> +{{{ +}}} + +Package=<4> +{{{ +}}} + +############################################################################### + Global: Package=<5> diff --git a/vc6/mbgxhrtime/mbgxhrtime.dsp b/vc6/mbgxhrtime/mbgxhrtime.dsp new file mode 100644 index 0000000..03f8d57 --- /dev/null +++ b/vc6/mbgxhrtime/mbgxhrtime.dsp @@ -0,0 +1,286 @@ +# Microsoft Developer Studio Project File - Name="mbgxhrtime" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Console Application" 0x0103 + +CFG=mbgxhrtime - Win32 Debug +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mbgxhrtime.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mbgxhrtime.mak" CFG="mbgxhrtime - Win32 Debug" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mbgxhrtime - Win32 Release" (based on "Win32 (x86) Console Application") +!MESSAGE "mbgxhrtime - Win32 Debug" (based on "Win32 (x86) Console Application") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mbgxhrtime - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /c +# ADD CPP /nologo /W3 /GX /O2 /I "..\.." /I "..\..\mbgxhrtime" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /c +# ADD BASE RSC /l 0x407 /d "NDEBUG" +# ADD RSC /l 0x407 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /machine:I386 /out:"../bin/Release/mbgxhrtime.exe" + +!ELSEIF "$(CFG)" == "mbgxhrtime - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /GZ /c +# ADD CPP /nologo /W3 /Gm /GX /ZI /Od /I "..\.." /I "..\..\mbgxhrtime" /I "..\..\mbglib\common" /I "..\..\mbglib\win32" /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /FR /YX /FD /GZ /c +# ADD BASE RSC /l 0x407 /d "_DEBUG" +# ADD RSC /l 0x407 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /pdbtype:sept +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib ws2_32.lib /nologo /subsystem:console /debug /machine:I386 /out:"../bin/Debug/mbgxhrtime.exe" /pdbtype:sept + +!ENDIF + +# Begin Target + +# Name "mbgxhrtime - Win32 Release" +# Name "mbgxhrtime - Win32 Debug" +# Begin Group "Source Files" + +# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat" +# Begin Source File + +SOURCE=..\..\mbglib\common\cfg_hlp.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgerror.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbgxhrtime\mbgxhrtime.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\toolutil.c +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\wingetopt.c +# End Source File +# End Group +# Begin Group "Header Files" + +# PROP Default_Filter "h;hpp;hxx;hm;inl" +# Begin Source File + +SOURCE=..\..\mbglib\common\cfg_hlp.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\gpsdefs.h +# End Source File +# Begin Source File + +SOURCE="..\..\..\..\..\..\ms-ddk\2600\inc\w2k\guiddef.h" +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_arch.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_cof.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_klist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_serclock_cfg.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbg_tgt.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbg_w32.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgadjtm_cfg.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgdevio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgerror.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbggeo.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgioctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgklist.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgmutex.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgpccyc.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvcio.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\mbgsvctl.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgsystm.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgtime.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\mbgutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbgversion.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\myutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pci_asic.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsdev.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsiobf.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\pcpsutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\rs232.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\str_util.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\timecnv.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\timeutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\toolutil.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\usbdefs.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\use_pack.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\win32\wingetopt.h +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\common\words.h +# End Source File +# End Group +# Begin Group "Resource Files" + +# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe" +# End Group +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgdevio.lib +# End Source File +# Begin Source File + +SOURCE=..\..\mbglib\lib\msc\mbgutil.lib +# End Source File +# End Target +# End Project |