diff options
| author | Martin Burnicki <martin.burnicki@meinberg.de> | 2013-06-26 12:00:00 +0200 |
|---|---|---|
| committer | Martin Burnicki <martin.burnicki@meinberg.de> | 2013-06-26 12:00:00 +0200 |
| commit | 8f723519051654b6e765123ed90260fc25df0f79 (patch) | |
| tree | ab791952c69ccc7c85645e553ea1d729867a3d48 | |
| parent | 68a194ac1bedb990f4fdc3da748ee5bc7c2e3a58 (diff) | |
| download | mbgtools-fbsd-8f723519051654b6e765123ed90260fc25df0f79.tar.gz mbgtools-fbsd-8f723519051654b6e765123ed90260fc25df0f79.zip | |
Update some files to current versionsmbgtools-fbsd-dev-2013-06-26
Also add some mbglib files, and remove an obsolete file.
63 files changed, 8255 insertions, 4074 deletions
diff --git a/mbgctrl/mbgctrl.c b/mbgctrl/mbgctrl.c index aba17f5..36c808b 100755 --- a/mbgctrl/mbgctrl.c +++ b/mbgctrl/mbgctrl.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgctrl.c 1.22.1.8 2011/09/26 15:58:58 martin TEST martin $ + * $Id: mbgctrl.c 1.22.1.14 2012/12/12 10:44:35 martin TEST $ * * Description: * Main file for mbgctrl program which sends commands and @@ -9,6 +9,17 @@ * * ----------------------------------------------------------------------- * $Log: mbgctrl.c $ + * Revision 1.22.1.14 2012/12/12 10:44:35 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. @@ -110,6 +121,7 @@ #include <cnv_wday.h> #include <toolutil.h> #include <lan_util.h> +//##+++++++++++++++++++++ #include <ptpdflts.h> // include system headers #include <stdio.h> @@ -123,9 +135,8 @@ #define MBG_FIRST_COPYRIGHT_YEAR 2001 #define MBG_LAST_COPYRIGHT_YEAR 0 // use default -static const char *pname = "mbgctrl"; -#define SIM_PTP_CFG ( 0 && DEBUG ) //##+++ +static const char *pname = "mbgctrl"; static char *dev_name; @@ -158,135 +169,6 @@ static const char no_lan_intf[] = "does not provide a LAN interface"; static const char no_ptp[] = "does not provide PTP"; static const char no_cab_len[] = "does not support antenna signal delay compensation"; -#define N_SUPP_UNICAST_MASTER 1 - - -#define DEFAULT_MC_SYNC_INTV_MIN -6 // [log2 s] -#define DEFAULT_MC_SYNC_INTV_MAX 6 // [log2 s] - -#define DEFAULT_MC_ANN_INTV_MIN -6 // [log2 s] -#define DEFAULT_MC_ANN_INTV_MAX 6 // [log2 s] - -#define DEFAULT_MC_DELAY_REQ_INTV_MIN -6 // [log2 s] -#define DEFAULT_MC_DELAY_REQ_INTV_MAX 6 // [log2 s] - - -#define DEFAULT_UC_SYNC_INTV_MIN -6 // [log2 s] -#define DEFAULT_UC_SYNC_INTV_MAX 6 // [log2 s] - -#define DEFAULT_UC_ANN_INTV_MIN -6 // [log2 s] -#define DEFAULT_UC_ANN_INTV_MAX 6 // [log2 s] - -#define DEFAULT_UC_DELAY_REQ_INTV_MIN -6 // [log2 s] -#define DEFAULT_UC_DELAY_REQ_INTV_MAX 6 // [log2 s] - - - -#define DEFAULT_MC_SYNC_INTV 0 // [log2 s] -#define DEFAULT_MC_ANN_INTV 1 // [log2 s] -#define DEFAULT_MC_DELAY_REQ_INTV 3 // [log2 s] - -#define DEFAULT_UC_SYNC_INTV 0 // [log2 s] -#define DEFAULT_UC_ANN_INTV 1 // [log2 s] -#define DEFAULT_UC_DELAY_REQ_INTV 3 // [log2 s] -#define DEFAULT_UC_MSG_DURATION 300 // [s] - - - -#define DEFAULT_PTP_CFG_SETTINGS \ -{ \ - PTP_NW_PROT_BIT_UDP_IPV4, /* nw_prot */ \ - 0, /* profile */ \ - 0, /* domain_number */ \ - PTP_DELAY_MECH_BIT_E2E, /* delay_mech */ \ - PTP_ROLE_MULTICAST_SLAVE, /* ptp_role */ \ - 128, /* priority_1 */ \ - 128, /* priority_2 */ \ - 52, /* dflt_clk_class_unsync_cold */ \ - 7, /* dflt_clk_class_unsync_warm */ \ - 6, /* dflt_clk_class_sync_cold */ \ - 6, /* dflt_clk_class_sync_warm */ \ - 0, /* reserved_1 */ \ - 0, /* reserved_2 */ \ - DEFAULT_MC_SYNC_INTV, /* sync_intv [log2 s]*/ \ - DEFAULT_MC_ANN_INTV, /* ann_intv [log2 s] */ \ - DEFAULT_MC_DELAY_REQ_INTV, /* delay_req_intv [log2 s] */ \ - 0, /* upper_bound, not used */ \ - 0, /* lower_bound, not used */ \ - 0, /* reserved_3 */ \ - 0 /* flags */ \ -} - -//##++++++++++ -#define DEFAULT_PTP_SLAVE_SUPP_FLAGS 0 -#define DEFAULT_PTP_SLAVE_SUPP_NW_PROT 0 -#define DEFAULT_PTP_SLAVE_SUPP_PROFILES 0 -#define DEFAULT_PTP_SLAVE_SUPP_DELAY_MECH 0 - -#define DEFAULT_PTP_CFG_INFO_SLAVE \ -{ \ - DEFAULT_PTP_CFG_SETTINGS, /* ptp_cfg_settings */ \ - 2, /* ptp_proto_version */ \ - 0, /* reserved_1 */ \ - 0, /* reserved_2 */ \ - DEFAULT_MC_SYNC_INTV_MIN, /* sync_intv_min */ \ - DEFAULT_MC_SYNC_INTV_MAX, /* sync_intv_max */ \ - DEFAULT_MC_ANN_INTV_MIN, /* ann_intv_min */ \ - DEFAULT_MC_ANN_INTV_MIN, /* ann_intv_max */ \ - DEFAULT_MC_DELAY_REQ_INTV_MIN, /* delay_req_intv_min */ \ - DEFAULT_MC_DELAY_REQ_INTV_MIN, /* delay_req_intv_max */ \ - DEFAULT_PTP_SLAVE_SUPP_FLAGS, /* supp_flags */ \ - DEFAULT_PTP_SLAVE_SUPP_NW_PROT, /* supp_nw_prot */ \ - DEFAULT_PTP_SLAVE_SUPP_PROFILES, /* supp_profiles */ \ - DEFAULT_PTP_SLAVE_SUPP_DELAY_MECH /* supp_delay_mech */ \ -} - -#define DEFAULT_PTP_UC_MASTER_CFG_LIMITS \ -{ \ - 1, /* n_supp_master */ \ - -6, /* sync_intv_min */ \ - 6, /* sync_intv_max */ \ - -6, /* ann_intv_min */ \ - 6, /* ann_intv_max */ \ - -6, /* delay_req_intv_min */ \ - 6, /* delay_req_intv_max */ \ - 0, /* reserved_0 */ \ - 0, /* supp_flags */ \ - 0 /* reserved_1 */ \ -} - - -#define DEFAULT_PTP_UC_MASTER_SETTINGS \ -{ \ - "0.0.0.0", /* gm_host */ \ - PTP_CLOCK_ID_WILDCARD, /* gm_clock_id */ \ - PTP_PORT_ID_WILDCARD, /* gm_port_id */ \ - DEFAULT_UC_SYNC_INTV, /* sync_intv [log2 s] */ \ - DEFAULT_UC_ANN_INTV, /* ann_intv [log2 s] */ \ - DEFAULT_UC_DELAY_REQ_INTV, /* delay_req_intv [log2 s] */ \ - 0, /* fix_offset, [ns] */ \ - DEFAULT_UC_MSG_DURATION, /* message_duration [s] */ \ - 0, /* reserved_1 */ \ - 0 /* flags */ \ -} - - -#define DEFAULT_PTP_UC_MASTER_INFO \ -{ \ - DEFAULT_PTP_UC_MASTER_SETTINGS, /* settings */ \ - 0, /* reserved */ \ - 0 /* flags */ \ -} - - - -#if SIM_PTP_CFG - static PTP_CFG_INFO sim_ptp_cfg_info = DEFAULT_PTP_CFG_INFO_SLAVE; - static PTP_UC_MASTER_CFG_LIMITS sim_ptp_uc_master_cfg_limits = DEFAULT_PTP_UC_MASTER_CFG_LIMITS; - static PTP_UC_MASTER_INFO sim_ptp_uc_master_info[N_SUPP_UNICAST_MASTER] = { DEFAULT_PTP_UC_MASTER_INFO }; -#endif - - typedef struct { @@ -338,6 +220,8 @@ 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; + +//##+++++++++++++++++++ // If unicast is not supported for a PTP device then the device is definitely // a multicast slave, in which case index 0 returns the correct role name. #define _ptp_role_name( _i ) \ @@ -550,7 +434,7 @@ int show_ptp_cfg( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *info ) for ( i = 0; i < p_uc_limits->n_supp_master; i++ ) { - PTP_UC_MASTER_SETTINGS *p = &all_ptp_cfg_info.all_ptp_uc_master_info[i].info.settings; + PTP_UC_MASTER_SETTINGS *p = &all_ptp_cfg_info.all_ptp_uc_master_info_idx[i].info.settings; printf( "\nPTP unicast master" ); @@ -787,7 +671,7 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) 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 - p_uc_info = &all_ptp_cfg_info.all_ptp_uc_master_info[uc_master_idx].info; + p_uc_info = &all_ptp_cfg_info.all_ptp_uc_master_info_idx[uc_master_idx].info; p_uc_settings = &p_uc_info->settings; @@ -972,7 +856,7 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) goto fail; - // Message Duration + // 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, PTP_UC_MSG_DURATION_MIN, PTP_UC_MSG_DURATION_MAX, @@ -1001,31 +885,11 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) #endif -#if SIM_PTP_CFG - sim_ptp_cfg_info.settings = *p_settings; - rc = 0; -#else rc = mbg_set_ptp_cfg_settings( dh, p_settings ); -#endif if ( mbg_ioctl_err( rc, "mbg_set_ptp_cfg_settings" ) ) return rc; - -#if 0 //##+++++++++ - if ( unicast_supported ) - { - #if SIM_PTP_CFG - #error test - rc = MBG_SUCCESS; - #else - rc = mbg_set_ptp_unicast_cfg_settings( dh, &ptp_unicast_settings ); - #endif - if ( mbg_ioctl_err( rc, "mbg_set_ptp_unicast_cfg_settings" ) ) - return rc; - } -#endif - return MBG_SUCCESS; @@ -2034,7 +1898,7 @@ void usage( MBG_DEV_HANDLE dh, PCPS_DEV *p_dev, RECEIVER_INFO *p_ri, " 0: only after the card has synchronized to its incoming signal\n" " 1: immediately after power-up\n" "\n" - " Please note enable flags may not be supported by any device\n" + " Please note that not every device supports enable flags.\n" "\n" ); @@ -2051,7 +1915,7 @@ void usage( MBG_DEV_HANDLE dh, PCPS_DEV *p_dev, RECEIVER_INFO *p_ri, " If no broadcast address is specified then the default broadcast address\n" " is computed from the IP address and the network mask.\n" "\n" - " Please note a LAN interface may not be provided by any board type.\n" + " Please note that not every device provides a LAN interface.\n" " Also, the IP values above are examples only. The real values to be used\n" " depend on the settings of the network to which the card is attached.\n" "\n" @@ -2572,10 +2436,6 @@ int main( int argc, char *argv[] ) pdev = &dev; - #if SIM_PTP_CFG - pdev->cfg.features |= PCPS_HAS_PTP; - #endif - rc = check_cmd_line( argc, argv, dh, pdev, &ri, &rpcfg ); if ( rc < 0 ) diff --git a/mbgfasttstamp/mbgfasttstamp.c b/mbgfasttstamp/mbgfasttstamp.c index 46273bc..b066f93 100755 --- a/mbgfasttstamp/mbgfasttstamp.c +++ b/mbgfasttstamp/mbgfasttstamp.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgfasttstamp.c 1.6.1.5 2011/12/19 16:09:17 martin TEST $ + * $Id: mbgfasttstamp.c 1.6.1.8 2013/04/10 15:40:28 martin TEST $ * * Description: * Main file for mbgfasttstamp program which demonstrates how to access @@ -9,6 +9,10 @@ * * ----------------------------------------------------------------------- * $Log: mbgfasttstamp.c $ + * Revision 1.6.1.8 2013/04/10 15:40:28 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. @@ -49,7 +53,6 @@ // include system headers #include <stdio.h> #include <stdlib.h> -#include <unistd.h> #define MBG_MICRO_VERSION 0 @@ -64,20 +67,8 @@ static const char *pname = "mbgfasttstamp"; static int loops; static int burst_read; static int read_raw; -static int exit_requested; - - - -static /*HDR*/ -void sighandler( int sig ) -{ - #if defined( DEBUG ) - printf( "Caught signal %i, exiting.\n", sig ); - #endif - - exit_requested = 1; - -} // sighandler +static long sleep_secs; +static long sleep_usecs; @@ -101,7 +92,7 @@ int show_fast_hr_timestamp( MBG_DEV_HANDLE dh ) if ( mbg_ioctl_err( rc, "mbg_get_fast_hr_timestamp..." ) ) goto fail; - mbg_print_hr_timestamp( &ts, hns_latency, NULL, read_raw, 0 ); // raw timestamp? + mbg_print_hr_timestamp( &ts, hns_latency, NULL, read_raw, 1 ); // raw timestamp? if ( this_loops > 0 ) this_loops--; @@ -109,6 +100,12 @@ int show_fast_hr_timestamp( MBG_DEV_HANDLE dh ) if ( this_loops == 0 ) break; + if ( sleep_secs ) + sleep( sleep_secs ); + else + if ( sleep_usecs ) + usleep( sleep_usecs ); + // if this_loops is < 0 then loop forever } @@ -217,6 +214,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_device_options(); puts( "" ); @@ -232,7 +231,7 @@ int main( int argc, char *argv[] ) mbg_print_program_info( pname, MBG_MICRO_VERSION, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); // check command line parameters - while ( ( c = getopt( argc, argv, "bcn:rh?" ) ) != -1 ) + while ( ( c = getopt( argc, argv, "bcn:rs:u:h?" ) ) != -1 ) { switch ( c ) { @@ -252,6 +251,14 @@ int main( int argc, char *argv[] ) read_raw = 1; break; + case 's': + sleep_secs = atoi( optarg ); + break; + + case 'u': + sleep_usecs = atoi( optarg ); + break; + case 'h': case '?': default: diff --git a/mbggpscap/mbggpscap.c b/mbggpscap/mbggpscap.c index c619bd3..eaf6744 100755 --- a/mbggpscap/mbggpscap.c +++ b/mbggpscap/mbggpscap.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbggpscap.c 1.10.1.6 2011/09/09 08:28:22 martin TEST $ + * $Id: mbggpscap.c 1.10.1.8 2013/06/25 09:53:47 martin TRASH martin $ * * Description: * Main file for mbggpscap program which demonstrates how to access @@ -13,7 +13,9 @@ * * ----------------------------------------------------------------------- * $Log: mbggpscap.c $ - * Revision 1.10.1.6 2011/09/09 08:28:22 martin + * Revision 1.10.1.8 2013/06/25 09:53:47 martin + * Revision 1.10.1.7 2013/04/10 15:40:28 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. @@ -65,7 +67,6 @@ // include system headers #include <stdio.h> #include <stdlib.h> -#include <unistd.h> #include <time.h> @@ -87,6 +88,7 @@ static int force_old_api; static int has_been_called; static int must_check_intv; +static int query_only; static ulong err_cnt; static PCPS_HR_TIME prv_ucap; @@ -265,7 +267,7 @@ int do_mbggpscap( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) // 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; @@ -347,6 +349,7 @@ void usage( void ) mbg_print_opt_info( "-c", "run continuously" ); 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(); @@ -364,7 +367,7 @@ int main( int argc, char *argv[] ) mbg_print_program_info( pname, MBG_MICRO_VERSION, 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, "ci:j:qroh?" ) ) != -1 ) { switch ( c ) { @@ -380,6 +383,10 @@ int main( int argc, char *argv[] ) max_cap_jitter = atof( optarg ); break; + case 'q': + query_only = 1; + break; + case 'r': raw = 1; break; diff --git a/mbghrtime/mbghrtime.c b/mbghrtime/mbghrtime.c index 698e4d2..914bbde 100755 --- a/mbghrtime/mbghrtime.c +++ b/mbghrtime/mbghrtime.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbghrtime.c 1.11.1.9 2011/12/19 16:13:46 martin TEST $ + * $Id: mbghrtime.c 1.11.1.10 2013/04/10 15:40:29 martin TEST $ * * Description: * Main file for mbghrtime program which demonstrates how to access @@ -10,7 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: mbghrtime.c $ - * Revision 1.11.1.9 2011/12/19 16:13:46 martin + * Revision 1.11.1.10 2013/04/10 15:40:29 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(). @@ -67,8 +68,6 @@ #include <time.h> #include <stdio.h> #include <stdlib.h> -#include <unistd.h> -#include <sys/time.h> // gettimeofday() diff --git a/mbgirigcfg/mbgirigcfg.c b/mbgirigcfg/mbgirigcfg.c index 9751a4b..f789279 100755 --- a/mbgirigcfg/mbgirigcfg.c +++ b/mbgirigcfg/mbgirigcfg.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgirigcfg.c 1.10.1.12 2011/07/19 12:59:06 martin TEST $ + * $Id: mbgirigcfg.c 1.10.1.14 2012/04/11 16:12:43 martin TEST $ * * Description: * Main file for the mbgirigcfg program which can be used to configure @@ -10,6 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: mbgirigcfg.c $ + * Revision 1.10.1.14 2012/04/11 16:12:43 martin + * Added parameter -X which set ref offs to "unconfigured". + * Revision 1.10.1.13 2012/04/10 15:56:40 martin * Revision 1.10.1.12 2011/07/19 12:59:06 martin * Revision 1.10.1.11 2011/07/07 15:08:35 martin * Removed obsolete code. @@ -126,20 +129,11 @@ int get_cfg( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev ) int rc_tx = MBG_SUCCESS; if ( _pcps_is_irig_rx( pdev ) ) - { - rc_rx = mbg_get_irig_rx_info( dh, &irig_rx_info ); - - if ( rc_rx == MBG_SUCCESS && _pcps_has_ref_offs( pdev ) ) - rc_rx = mbg_get_ref_offs( dh, &ref_offs ); - - if ( rc_rx == MBG_SUCCESS && _pcps_has_opt_flags( pdev ) ) - rc_rx = mbg_get_opt_info( dh, &opt_info ); - } + rc_rx = mbg_get_all_irig_rx_info( dh, pdev, &irig_rx_info, + &ref_offs, &opt_info ); if ( _pcps_has_irig_tx( pdev ) ) - { rc_tx = mbg_get_irig_tx_info( dh, &irig_tx_info ); - } if ( rc_rx != MBG_SUCCESS ) @@ -164,20 +158,10 @@ int save_cfg( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev ) int rc_tx = MBG_SUCCESS; if ( _pcps_is_irig_rx( pdev ) ) - { - rc_rx = mbg_set_irig_rx_settings( dh, &irig_rx_info.settings ); - - if ( rc_rx == MBG_SUCCESS && _pcps_has_ref_offs( pdev ) ) - rc_rx = mbg_set_ref_offs( dh, &ref_offs ); - - if ( rc_rx == MBG_SUCCESS && _pcps_has_opt_flags( pdev ) ) - rc_rx = mbg_set_opt_settings( dh, &opt_info.settings ); - } - + rc_rx = mbg_save_all_irig_rx_settings( dh, pdev, &irig_rx_info.settings, + &ref_offs, &opt_info.settings ); if ( rc_rx == MBG_SUCCESS && _pcps_has_irig_tx( pdev ) ) - { rc_tx = mbg_set_irig_tx_settings( dh, &irig_tx_info.settings ); - } if ( rc_rx != MBG_SUCCESS ) printf( "** Error writing IRIG RX configuration.\n" ); @@ -186,7 +170,7 @@ int save_cfg( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev ) printf( "** Error writing IRIG TX configuration.\n" ); if ( rc_rx != MBG_SUCCESS || rc_tx != MBG_SUCCESS ) - return -1; + return -1; //##++ return MBG_SUCCESS; @@ -305,6 +289,16 @@ void set_new_ref_offs( char *s ) 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; @@ -461,7 +455,7 @@ void check_cmd_line( int argc, char *argv[], const PCPS_DEV *pdev ) // force checking all parameters since this may be called several times optind = 1; - while ( ( c = getopt( argc, argv, "h?" "r:o:u:i:" "t:l:s:" ) ) != -1 ) + while ( ( c = getopt( argc, argv, "h?" "r:o:u:i:X" "t:l:s:" ) ) != -1 ) { switch ( c ) { @@ -493,6 +487,11 @@ void check_cmd_line( int argc, char *argv[], const PCPS_DEV *pdev ) 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( pdev ) ) + set_ref_offs_not_cfgd(); + break; + // IRIG output options @@ -554,12 +553,22 @@ void usage( void ) printf( " -o offs specifies the IRIG input time offset from UTC, in hours,\n" - " where \"offs\" can be a value in the range %+i..%+i\n" + " where \"offs\" can be a value in the range %+i..%+i.\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", -max_ref_offs_h, max_ref_offs_h ); 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" @@ -576,6 +585,7 @@ void usage( void ) "\n" ); + printf( "Options supported by IRIG transmitters:\n" "\n" diff --git a/mbglib/bsd/mbg_bsd.h b/mbglib/bsd/mbg_bsd.h deleted file mode 100755 index 9efef59..0000000 --- a/mbglib/bsd/mbg_bsd.h +++ /dev/null @@ -1,49 +0,0 @@ - -/************************************************************************** - * - * $Id: mbg_bsd.h 1.1.1.1 2011/02/04 14:44:33 martin TEST $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * OS dependend definitions/redefinitions for *BSD. - * - * ----------------------------------------------------------------------- - * $Log: mbg_bsd.h $ - * Revision 1.1.1.1 2011/02/04 14:44:33 martin - * Revision 1.1 2011/01/26 16:09:33 martin - * Initial revision. - * - **************************************************************************/ - -#ifndef _MBG_BSD_H -#define _MBG_BSD_H - - -/* Other headers to be included */ - -#include <sys/types.h> -#include <sys/bus.h> -#include <machine/bus.h> - - -#ifdef _MBG_BSD - #define _ext -#else - #define _ext extern -#endif - - -/* Start of header body */ - -// definitions for clock() support in kernel drivers -// extern unsigned long volatile jiffies; //##++ this is just a workaround to build without errors -// #define clock() jiffies - - -/* End of header body */ - -#undef _ext - -#endif /* _MBG_BSD_H */ - diff --git a/mbglib/bsd/pci_bsd.h b/mbglib/bsd/pci_bsd.h index f032234..aaad78c 100755 --- a/mbglib/bsd/pci_bsd.h +++ b/mbglib/bsd/pci_bsd.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pci_bsd.h 1.1 2011/01/26 16:09:33 martin TEST $ + * $Id: pci_bsd.h 1.2 2012/11/07 10:23:46 martin TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,6 +11,8 @@ * * ----------------------------------------------------------------------- * $Log: pci_bsd.h $ + * Revision 1.2 2012/11/07 10:23:46 martin + * Cleanup. * Revision 1.1 2011/01/26 16:09:33 martin * Initial revision. * @@ -24,9 +26,6 @@ #include <pcidefs.h> -#include <mbg_bsd.h> -//##++ #include <linux/pci.h> - #ifdef _PCI_BSD #define _ext @@ -37,12 +36,6 @@ /* Start of header body */ -//##++ update comment -// The pcibios_..() calls use below are not supported by -// recent 2.6.x kernels. However, those kernels should use -// the PNP PCI interface anyway, whereas the functions below -// are only used by non-PNP environments. - #define _mbg_pci_find_bios( _p1, _p2, _p3 ) \ ( pcibios_present() ? PCI_SUCCESS : PCI_NO_SUCCESS ) diff --git a/mbglib/bsd/rsrc_bsd.c b/mbglib/bsd/rsrc_bsd.c index a1b14d1..9859620 100755 --- a/mbglib/bsd/rsrc_bsd.c +++ b/mbglib/bsd/rsrc_bsd.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: rsrc_bsd.c 1.1.1.1 2011/02/07 15:28:32 martin TEST $ + * $Id: rsrc_bsd.c 1.1.1.1 2011/02/07 15:28:32 martin TEST martin $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * diff --git a/mbglib/bsd/rsrc_bsd.h b/mbglib/bsd/rsrc_bsd.h index ba1af48..57b0555 100755 --- a/mbglib/bsd/rsrc_bsd.h +++ b/mbglib/bsd/rsrc_bsd.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: rsrc_bsd.h 1.1 2011/01/26 16:09:34 martin TEST $ + * $Id: rsrc_bsd.h 1.2 2012/11/07 10:24:10 martin TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: rsrc_bsd.h $ + * Revision 1.2 2012/11/07 10:24:10 martin + * Removed obsolete include. * Revision 1.1 2011/01/26 16:09:34 martin * Initial revision. * @@ -21,7 +23,6 @@ /* Other headers to be included */ -#include <mbg_bsd.h> #include <rsrc.h> #include <words.h> diff --git a/mbglib/common/cfg_hlp.h b/mbglib/common/cfg_hlp.h index 9706dba..b7c4033 100755 --- a/mbglib/common/cfg_hlp.h +++ b/mbglib/common/cfg_hlp.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: cfg_hlp.h 1.1 2011/09/21 15:59:59 martin TEST $ + * $Id: cfg_hlp.h 1.2 2012/10/02 18:16:26 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: cfg_hlp.h $ + * 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. * @@ -55,13 +57,13 @@ extern "C" { #define MAX_PARM_PORT 4 #define MAX_PARM_STR_TYPE 20 -typedef PORT_INFO_IDX ALL_PORT_INFO[MAX_PARM_PORT]; -typedef STR_TYPE_INFO_IDX ALL_STR_TYPE_INFO[MAX_PARM_STR_TYPE]; +typedef PORT_INFO_IDX ALL_PORT_INFO_IDX[MAX_PARM_PORT]; +typedef STR_TYPE_INFO_IDX ALL_STR_TYPE_INFO_IDX[MAX_PARM_STR_TYPE]; typedef struct { - ALL_PORT_INFO pii; - ALL_STR_TYPE_INFO stii; + ALL_PORT_INFO_IDX pii; + ALL_STR_TYPE_INFO_IDX stii; PORT_PARM tmp_pp; } RECEIVER_PORT_CFG; @@ -75,8 +77,18 @@ typedef struct #define MAX_PARM_POUT 4 -typedef POUT_INFO_IDX ALL_POUT_INFO[MAX_PARM_POUT]; +#if 1 //##+++++++++++++++++++++++ +typedef POUT_INFO_IDX ALL_POUT_INFO_IDX[MAX_PARM_POUT]; + +#else + +typedef struct +{ + POUT_INFO_IDX pii[MAX_PARM_POUT]; +} POUT_CFG; + +#endif /* @@ -87,7 +99,7 @@ typedef POUT_INFO_IDX ALL_POUT_INFO[MAX_PARM_POUT]; #define MAX_PARM_PTP_UC_MASTER 3 -typedef PTP_UC_MASTER_INFO_IDX ALL_PTP_UC_MASTER_INFO[MAX_PARM_PTP_UC_MASTER]; +typedef PTP_UC_MASTER_INFO_IDX ALL_PTP_UC_MASTER_INFO_IDX[MAX_PARM_PTP_UC_MASTER]; diff --git a/mbglib/common/chk_time_info.c b/mbglib/common/chk_time_info.c new file mode 100755 index 0000000..78f6ff6 --- /dev/null +++ b/mbglib/common/chk_time_info.c @@ -0,0 +1,155 @@ + +/************************************************************************** + * + * $Id: chk_time_info.c 1.2 2013/03/04 16:01:01 martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * NTP shared memory support functions. + * + * ----------------------------------------------------------------------- + * $Log: chk_time_info.c $ + * Revision 1.2 2013/03/04 16:01:01 martin + * Use common function setup_hr_time_cycles_from_timestamp_cycles(). + * Made snprint_chk_time_info() more flexible. + * Revision 1.1 2012/05/29 09:52:26 martin + * Initial revision. + * + **************************************************************************/ + +#define _CHK_TIME_INFO + #include <chk_time_info.h> +#undef _CHK_TIME_INFO + +#include <toolutil.h> +#include <stdio.h> + + +//##++++++ +extern MBG_PC_CYCLES_FREQUENCY cyc_freq; + + +static /*HDR*/ +MBG_PC_CYCLES do_filter( FILTER *p, MBG_PC_CYCLES cyc ) +{ + if ( p->entries < MAX_FILTER_ENTRIES ) + p->entries++; + + if ( ++( p->index ) >= MAX_FILTER_ENTRIES ) + p->index = 0; + + // update the sum of filter entries + p->sum -= p->cyc[p->index]; // subtract oldest sample + p->cyc[p->index] = cyc; // save new sample + p->sum += cyc; // add new sample + + return p->sum / p->entries; // return mean value + +} /* do_filter */ + + + +/*HDR*/ +int mbg_chk_time_info( MBG_DEV_HANDLE dh, MBG_CHK_TIME_INFO *p, FILTER *p_filter, int fast_ts_only ) +{ + MBG_PC_CYCLES tmp; + PCPS_TIME_STAMP *p_ref_ts; + MBG_PC_CYCLES *p_ref_cyc; + MBG_SYS_TIME_CYCLES *p_sys_tic; + int rc; + + memset( p, 0, sizeof( *p ) ); + + if ( fast_ts_only ) + { + MBG_TIME_INFO_TSTAMP tsi; + + rc = mbg_get_time_info_tstamp( dh, &tsi ); + setup_hr_time_cycles_from_timestamp_cycles( &p->hrti.ref_hr_time_cycles, &tsi.ref_tstamp_cycles ); + p->hrti.sys_time_cycles = tsi.sys_time_cycles; + } + else + rc = mbg_get_time_info_hrt( dh, &p->hrti ); + + if ( rc < 0 ) + return rc; + + + p_ref_ts = &p->hrti.ref_hr_time_cycles.t.tstamp; + p_ref_cyc = &p->hrti.ref_hr_time_cycles.cycles; + p_sys_tic = &p->hrti.sys_time_cycles; + + p->d_ref = (double) p_ref_ts->sec + ( (double) p_ref_ts->frac ) / (double) PCPS_HRT_BIN_FRAC_SCALE; + p->d_sys = (double) p_sys_tic->sys_time.sec + (double) p_sys_tic->sys_time.nsec / 1e9; + + p->ltcy_cyc = mbg_delta_pc_cycles( p_ref_cyc, &p_sys_tic->cyc_after ); + p->exec_cyc = mbg_delta_pc_cycles( &p_sys_tic->cyc_after, &p_sys_tic->cyc_before ); + p->exec_cyc_limit = p_filter ? do_filter( p_filter, p->exec_cyc ) : 0; + + if ( cyc_freq ) + { + p->ltcy_sec = ( (double) p->ltcy_cyc ) / (double) cyc_freq; + p->exec_sec = ( (double) p->exec_cyc ) / (double) cyc_freq; + p->exec_sec_limit = ( (double) p->exec_cyc_limit ) / (double) cyc_freq; + } + + // Compensate latencies between time stamps -> + // normalize ref time to system time stamp + p->d_ref_comp = p->d_ref - p->ltcy_sec; + + // Try to set the limit to 1.7 of the mean execution cycles. + tmp = ( 7 * p->exec_cyc_limit ) / 10; + + // If execution takes only a few cycles make sure the limit + // is above the mean number of cycles. + if ( tmp == 0 ) + tmp++; + + p->exec_cyc_limit += tmp; + + return MBG_SUCCESS; + +} // mbg_chk_time_info + + + +/*HDR*/ +int snprint_chk_time_info( char *s, size_t max_len, const MBG_CHK_TIME_INFO *p, const PCPS_DEV *p_dev, + int frac_digits, int print_raw ) +{ + size_t n = 0; + + if ( p_dev ) + n += snprintf( &s[n], max_len - n, "%-9s: ", _pcps_type_name( p_dev ) ); + + n += mbg_snprint_hr_tstamp( &s[n], max_len - n, &p->hrti.ref_hr_time_cycles.t.tstamp, 0 ); // raw timestamp? + + n += snprintf( &s[n], max_len - n, ": %.*f-%.*f: ", + frac_digits, p->d_ref, + frac_digits, p->d_sys ); + + if ( print_raw ) + n += snprintf( &s[n], max_len - n, "%+.*f->", + frac_digits, p->d_ref - p->d_sys ); + + n += snprintf( &s[n], max_len - n, "%+.*f, ltcy: ", + frac_digits, p->d_ref_comp - p->d_sys ); + + + if ( cyc_freq ) // print latency and execution time in microseconds + { + n += snprintf( &s[n], max_len - n, "%.2f us, exec: %.2f us, limit: %.2f us", + p->ltcy_sec * 1e6, p->exec_sec * 1e6, p->exec_sec_limit * 1e6 ); + } + else // print latency and execution time in cycles only + { + n += snprintf( &s[n], max_len - n, "%lli cyc, exec: %lli cyc, limit: %lli cyc", + (long long) p->ltcy_cyc, (long long) p->exec_cyc, + (long long) p->exec_cyc_limit ); + } + + return n; + +} // snprint_chk_time_info + diff --git a/mbglib/common/chk_time_info.h b/mbglib/common/chk_time_info.h new file mode 100755 index 0000000..260691e --- /dev/null +++ b/mbglib/common/chk_time_info.h @@ -0,0 +1,112 @@ + +/************************************************************************** + * + * $Id: chk_time_info.h 1.2 2013/03/04 16:02:31 martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for chk_time_info.c. + * + * ----------------------------------------------------------------------- + * $Log: chk_time_info.h $ + * Revision 1.2 2013/03/04 16:02:31 martin + * Updated function prototypes. + * Revision 1.1 2012/05/29 09:52:27 martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _CHK_TIME_INFO_H +#define _CHK_TIME_INFO_H + + +/* Other headers to be included */ + +#include <mbgdevio.h> + + +#ifdef _CHK_TIME_INFO + #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 + + +#if !defined( MAX_FILTER_ENTRIES ) + #define MAX_FILTER_ENTRIES 32 +#endif + + +typedef struct +{ + MBG_PC_CYCLES cyc[MAX_FILTER_ENTRIES]; + MBG_PC_CYCLES sum; + int entries; + int index; +} FILTER; + + +typedef struct +{ + MBG_TIME_INFO_HRT hrti; + + MBG_PC_CYCLES ltcy_cyc; + MBG_PC_CYCLES exec_cyc; + MBG_PC_CYCLES exec_cyc_limit; + + double ltcy_sec; + double exec_sec; + double exec_sec_limit; + + double d_sys; + double d_ref; + double d_ref_comp; + +} MBG_CHK_TIME_INFO; + + + +/* function prototypes: */ + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + int mbg_chk_time_info( MBG_DEV_HANDLE dh, MBG_CHK_TIME_INFO *p, FILTER *p_filter, int fast_ts_only ) ; + int snprint_chk_time_info( char *s, size_t max_len, const MBG_CHK_TIME_INFO *p, const PCPS_DEV *p_dev, int frac_digits, int print_raw ) ; + +/* ----- 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 /* _CHK_TIME_INFO_H */ + diff --git a/mbglib/common/ctry.c b/mbglib/common/ctry.c index ef647d0..73cbe3f 100755 --- a/mbglib/common/ctry.c +++ b/mbglib/common/ctry.c @@ -19,7 +19,6 @@ * by giving the different strings as function arguments. * Revision 1.6 2007/03/29 12:21:51 martin * New functions lstr_idx() and lstr_array_idx(). - * Revision 1.1 2010/06/01 07:57:03 philipp * Revision 1.5 2004/10/26 07:39:37Z martin * Use C99 fixed-size definitions where appropriate. * Revision 1.4 2001/09/14 12:02:12 MARTIN diff --git a/mbglib/common/ctry.h b/mbglib/common/ctry.h index 189d1a5..8406a76 100755 --- a/mbglib/common/ctry.h +++ b/mbglib/common/ctry.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: ctry.h 1.12 2011/06/22 07:37:57 martin REL_M $ + * $Id: ctry.h 1.13 2012/11/29 12:01:09 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,11 @@ * * ----------------------------------------------------------------------- * $Log: ctry.h $ - * Revision 1.12 2011/06/22 07:37:57 martin + * Revision 1.13 2012/11/29 12:01:09 martin + * Don't include mbg_tgt.h explicitely 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 * Cleaned up handling of pragma pack(). * Revision 1.11 2010/07/15 08:33:41 martin * Added some macros implemented by Stefan. @@ -48,7 +52,6 @@ /* Other headers to be included */ -#include <mbg_tgt.h> #include <words.h> #if defined( MBG_TGT_NETWARE ) diff --git a/mbglib/common/deviohlp.c b/mbglib/common/deviohlp.c index b101460..6261ca8 100755 --- a/mbglib/common/deviohlp.c +++ b/mbglib/common/deviohlp.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: deviohlp.c 1.1.1.4 2011/09/21 14:45:24 martin TEST $ + * $Id: deviohlp.c 1.2 2012/10/15 13:48:35 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -18,6 +18,15 @@ * * ----------------------------------------------------------------------- * $Log: deviohlp.c $ + * Revision 1.2 2012/10/15 13:48:35 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 @@ -202,25 +211,22 @@ int mbg_save_serial_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, /*HDR*/ /** - 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 must be passed to this function. + Read all PTP settings and supported configuration parameters. - The complementary function mbg_save_serial_settings() should be used - to write the modified serial port configuration back to the board. + The complementary function mbg_save_all_ptp_cfg_info() should + be used to write the modified configuration back to the device. @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. + @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_device_info() - @see mbg_setup_receiver_info() - @see mbg_save_serial_settings() + @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() */ int mbg_get_all_ptp_cfg_info( MBG_DEV_HANDLE dh, ALL_PTP_CFG_INFO *p ) { @@ -247,7 +253,7 @@ int mbg_get_all_ptp_cfg_info( MBG_DEV_HANDLE dh, ALL_PTP_CFG_INFO *p ) return MBG_ERR_N_UC_MSTR_EXCEEDS_SUPP; } - rc = mbg_get_all_ptp_uc_master_info( dh, p->all_ptp_uc_master_info, + rc = mbg_get_all_ptp_uc_master_info( dh, p->all_ptp_uc_master_info_idx, &p->ptp_uc_master_cfg_limits ); if ( rc < 0 ) return rc; @@ -258,3 +264,59 @@ int mbg_get_all_ptp_cfg_info( MBG_DEV_HANDLE dh, ALL_PTP_CFG_INFO *p ) } // mbg_get_all_ptp_cfg_info + +/*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() +*/ +int mbg_save_all_ptp_cfg_info( MBG_DEV_HANDLE dh, const ALL_PTP_CFG_INFO *p ) +{ + int rc = MBG_SUCCESS; + + rc = mbg_set_ptp_cfg_settings( dh, &p->ptp_cfg_info.settings ); + + if ( rc < 0 ) + return rc; + + + if ( p->ptp_cfg_info.supp_flags & PTP_CFG_MSK_SUPPORT_PTP_UNICAST ) + { + int i; + + for ( i = 0; i < p->ptp_uc_master_cfg_limits.n_supp_master; i++ ) + { + PTP_UC_MASTER_SETTINGS_IDX s; + + memset( &s, 0, sizeof( s ) ); + + s.idx = i; + s.settings = p->all_ptp_uc_master_info_idx[i].info.settings; + + rc = mbg_set_ptp_uc_master_settings_idx( dh, &s ); + + if ( rc < 0 ) + return rc; + } + } + + return MBG_SUCCESS; + +} // mbg_save_all_ptp_cfg_info + + diff --git a/mbglib/common/deviohlp.h b/mbglib/common/deviohlp.h index 158f549..a622c07 100755 --- a/mbglib/common/deviohlp.h +++ b/mbglib/common/deviohlp.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: deviohlp.h 1.1.1.5 2011/09/21 16:00:22 martin TEST $ + * $Id: deviohlp.h 1.2 2012/10/15 13:51:18 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,16 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: deviohlp.h $ - * Revision 1.1.1.5 2011/09/21 16:00:22 martin - * Revision 1.1.1.4 2011/09/21 14:44:50 martin + * Revision 1.2 2012/10/15 13:51:18 martin + * Include cfg_hlp.h. + * Added structure ALL_PTP_CFG_INFO. * Updated function prototypes. - * Revision 1.1.1.3 2011/09/20 15:36:03 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:58 martin * Revision 1.1 2011/08/03 15:36:44Z martin * Initial revision with functions moved here from mbgdevio. * @@ -54,7 +48,7 @@ typedef struct { PTP_CFG_INFO ptp_cfg_info; PTP_UC_MASTER_CFG_LIMITS ptp_uc_master_cfg_limits; - ALL_PTP_UC_MASTER_INFO all_ptp_uc_master_info; + ALL_PTP_UC_MASTER_INFO_IDX all_ptp_uc_master_info_idx; } ALL_PTP_CFG_INFO; @@ -118,28 +112,46 @@ typedef struct int mbg_save_serial_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, RECEIVER_PORT_CFG *pcfg, int port_num ) ; /** - Read all serial port settings and supported configuration parameters. + Read all PTP 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 must 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. + The complementary function mbg_save_all_ptp_cfg_info() should + be used to write the modified configuration back to the device. @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. + @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_device_info() - @see mbg_setup_receiver_info() - @see mbg_save_serial_settings() + @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() */ 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. + + @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() +*/ + int mbg_save_all_ptp_cfg_info( MBG_DEV_HANDLE dh, const ALL_PTP_CFG_INFO *p ) ; + /* ----- function prototypes end ----- */ diff --git a/mbglib/common/gpsdefs.h b/mbglib/common/gpsdefs.h index 6d49cf8..5266ee0 100755 --- a/mbglib/common/gpsdefs.h +++ b/mbglib/common/gpsdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: gpsdefs.h 1.99 2011/12/09 09:22:03 martin REL_M $ + * $Id: gpsdefs.h 1.113.1.11 2013/06/26 15:49:24 martin TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -13,6 +13,86 @@ * * ----------------------------------------------------------------------- * $Log: gpsdefs.h $ + * Revision 1.113.1.11 2013/06/26 15:49:24 martin + * Started to support IPv6. + * Revision 1.113.1.10 2013/06/26 08:17:18 martin + * Revision 1.113.1.9 2013/06/25 10:13:59 martin + * Temp. workaround for DOS. + * Revision 1.113.1.8 2013/06/21 13:59:51Z martin + * Revision 1.113.1.7 2013/06/21 13:51:35 martin + * Renamed and reversed meaning of management msg control flag. + * Started to support PTP presets properly. + * Not yet finished. + * Revision 1.113.1.6 2013/06/18 12:24:52 martin + * Support GLN180PEX. + * Fixed some typos. + * Revision 1.113.1.5 2013/06/18 11:01:50 udo + * Revision 1.113.1.4 2013/06/18 08:57:36 daniel + * Added new PTP roles and CFG flags for Hybrid mode, simultanous UC/MC mode, + * 1-step and selectable management + * Revision 1.113.1.3 2013/06/17 13:12:26 daniel + * Added model codes and names for MRI and BPE + * Revision 1.113.1.2 2013/04/25 14:43:10 Gregoire + * DEFAULT_HQ_SHRT_FMT_NAMES added + * Revision 1.113.1.1 2013/04/11 14:21:05Z Gregoire + * string initializers for supported havequick formats added + * Revision 1.113 2013/04/04 09:02:01Z martin + * Added definitions to support HaveQuick. + * Fixed a typo. + * Revision 1.112 2013/02/19 15:39:13 martin + * New PTP settings field ann_rcpt_timeout and associated + * values PTP_ANN_RCPT_TIMEOUT_LIMITS. + * Changed many defines to named enums to simplify references + * with doxygen. + * Updated doxygen comments. + * Revision 1.111 2013/02/01 15:37:36 martin + * Added and modified a huge number of doxygen comments. + * Revision 1.110 2013/01/16 15:23:25 martin + * Fixed 2 comments which were interchanged. + * Revision 1.109 2013/01/11 10:39:34 martin + * Added definitions for IMS. + * Support XMR_HOLDOVER_INTV. + * New XMRS status bit XMRS_BIT_LOW_JITTER / XMRS_MSK_LOW_JITTER. + * Added framing type 8E2, though most UARTs don't support this. + * Added enum names and updated comments for doxygen. + * Revision 1.108 2012/10/30 11:31:16 martin + * Defined PTP_UC_MSG_DURATION_MIN and PTP_UC_MSG_DURATION_MAX. + * Fixed some doxygen comments. + * Changes by andre: changed reserved field to ssm and boc in BITS_OUT settings. + * Revision 1.107 2012/10/12 07:40:12 martin + * New PTP state flags PTP_FLAG_MSK_UTC_VALID and + * PTP_CFG_MSK_SUPP_UTC_VALID. + * Revision 1.106 2012/10/02 18:22:10 martin + * Added default baud rate and framing for binary protocol. + * Added definitions for IRIG codes E002/E112 and NASA36. + * Reworked GPIO structures. + * Added definitions for GRC, LIU, DCF600RS, and DCF600HS. + * New flag POUT_FIXED_PULSE_LEN. + * New flag POUT_NOT_INVERTIBLE. + * Unified capitalization in MBG_XMRS_STATUS_STRS. + * Revision 1.105 2012/06/01 16:31:16 martin + * Some TIME_SLOT definitions added by marvin. + * Moved some PTP configuration defaults and limits to ptpdflts.h. + * Revision 1.104 2012/04/11 16:02:55Z martin + * Fixed some doxygen comments. + * Revision 1.103 2012/04/02 11:08:57Z martin + * Extended description of GPS UTC/leap second data. + * Revision 1.102 2012/03/16 11:43:31 martin + * Fixed a potential compiler warning. + * Revision 1.101 2012/03/06 16:56:01Z martin + * Added support for PTP multicast auto role. + * Merged Daniel's definitions for PTP profile support. + * Support time slot mode for programmable pulse outputs. + * Support LNO180. + * Moved definition of MBG_MAC_ADDR here. + * Use MBG_MAC_ADDR in definition of LAN_IF_INFO. + * Revision 1.100 2012/01/17 13:33:55 martin + * Added new IRIG RX delay compensation code groups for G0xx and G1xx codes. + * As a consequence the value of N_IRIG_RX_COMP has changed. + * Added definition of IRIG_RX_COMP_MAX. + * Updated IRIG code classification macros. + * Removed obsolete/unused definition of CAL_REC_INFO. + * Added some comments. * Revision 1.99 2011/12/09 09:22:03 martin * Fixed a typo. * Revision 1.98 2011/11/25 14:58:34 martin @@ -228,7 +308,7 @@ * Added ROM_CSUM, RCV_TIMEOUT, and IGNORE_LOCK types. * Revision 1.44 2006/05/18 09:34:41Z martin * Added definitions for POUT max. pulse_len and max timeout. - * Changed comment for POUT_SETTINGS::timeout: + * Changed comment for POUT_SETTINGS::timeout. * Units are minutes, not seconds. * Added definition for MAX_POUT_TIME_STR_PORTS. * Added definitions for POUT mode 10MHz. @@ -301,7 +381,7 @@ * Revision 1.20 2003/04/03 11:03:44Z martin * Extended definitions for IRIG support. * Revision 1.19 2003/01/31 13:38:20 MARTIN - * Modified type of RECEIVER_INFO.fixed_freq field. + * Modified type of RECEIVER_INFO::fixed_freq field. * Revision 1.18 2002/10/28 09:24:07 MARTIN * Added/renamed some POUT related symbols. * Revision 1.17 2002/09/05 10:58:39 MARTIN @@ -396,7 +476,7 @@ #define GPS_EPLD_STR_SIZE ( GPS_EPLD_STR_LEN + 1 ) -#define DEFAULT_GPS_TICKS_PER_SEC 10000000L /* system time base */ +#define DEFAULT_GPS_TICKS_PER_SEC 10000000L ///< system time base, see ::GPS_TICKS_PER_SEC #if !defined( GPS_TICKS_PER_SEC ) /* @@ -405,20 +485,21 @@ * model support the RECEIVER_INFO structure which contains * the actual value. */ - #define GPS_TICKS_PER_SEC DEFAULT_GPS_TICKS_PER_SEC + #define GPS_TICKS_PER_SEC DEFAULT_GPS_TICKS_PER_SEC ///< @see DEFAULT_GPS_TICKS_PER_SEC + #endif -typedef uint16_t SVNO; /* the number of a SV */ -typedef uint16_t HEALTH; /* a SV's health code */ -typedef uint16_t CFG; /* a SV's configuration code */ -typedef uint16_t IOD; /* Issue-Of-Data code */ +typedef uint16_t SVNO; ///< the number of an SV (Space Vehicle, i.e. satellite) +typedef uint16_t HEALTH; ///< an SV's health code +typedef uint16_t CFG; ///< an SV's configuration code +typedef uint16_t IOD; ///< Issue-Of-Data code /* the type of various checksums */ #ifndef _CSUM_DEFINED - typedef uint16_t CSUM; + typedef uint16_t CSUM; ///< checksum used by some structures stored in non-volatile memory #define _CSUM_DEFINED #define _mbg_swab_csum( _p ) _mbg_swab16( _p ) @@ -429,8 +510,8 @@ typedef uint16_t IOD; /* Issue-Of-Data code */ * @brief The type of a GPS command code * * These command codes can be passed via - * @ref gps_cmds_serial "serial port" (see @file gpsserio.h), or - * @ref gps_cmds_bus "system bus" (see @file pcpsdefs.h). + * @ref group_gps_cmds_serial "serial port" (see @file gpsserio.h), or + * @ref group_gps_cmds_bus "system bus" (see @file pcpsdefs.h). */ typedef uint16_t GPS_CMD; @@ -445,9 +526,9 @@ typedef uint16_t GPS_CMD; */ typedef struct { - uint16_t code; /**< Version number, e.g. 0x0120 means v1.20 */ - char name[GPS_ID_STR_SIZE]; /**< Optional string identifying a customized version */ - uint8_t reserved; /**< Reserved field to yield even structure size */ + uint16_t code; ///< Version number, e.g. 0x0120 means v1.20 + char name[GPS_ID_STR_SIZE]; ///< Optional string identifying a customized version + uint8_t reserved; ///< Reserved field to yield even structure size } SW_REV; #define _mbg_swab_sw_rev( _p ) \ @@ -481,38 +562,47 @@ typedef uint16_t BVAR_STAT; #define _mbg_swab_bvar_stat( _p ) _mbg_swab16( (_p) ) -/** @brief Enumeration of bits used with BVAR_STAT */ -enum -{ - BVAR_BIT_CFGH_INVALID, - BVAR_BIT_ALM_NOT_COMPLETE, - BVAR_BIT_UTC_INVALID, - BVAR_BIT_IONO_INVALID, - BVAR_BIT_RCVR_POS_INVALID, - N_BVAR_BIT /**< @brief number of defined ::BVAR_STAT bits */ +/** + * @brief Enumeration of bits used with BVAR_STAT + * + * For each bit which is set this means the associated data set in + * non-volatile memory is not available or incomplete. + * Most data sets will just be re-collected from the data streams sent + * by the satellites. However, the receiver position has usually been + * computed earlier during normal operation, and will be re-computed + * when a sufficient number of satellites can be received. + */ +enum BVAR_BITS +{ + BVAR_BIT_CFGH_INVALID, ///< Satellite configuration and health parameters incomplete + BVAR_BIT_ALM_NOT_COMPLETE, ///< Almanac parameters incomplete + BVAR_BIT_UTC_INVALID, ///< %UTC offset parameters incomplete + BVAR_BIT_IONO_INVALID, ///< Ionospheric correction parameters incomplete + BVAR_BIT_RCVR_POS_INVALID, ///< No valid receiver position available + N_BVAR_BIT ///< number of defined ::BVAR_STAT bits }; -#define BVAR_CFGH_INVALID ( 1UL << BVAR_BIT_CFGH_INVALID ) /**< @brief Configuration and health data (::CFGH) not valid */ -#define BVAR_ALM_NOT_COMPLETE ( 1UL << BVAR_BIT_ALM_NOT_COMPLETE ) /**< @brief Almanach data (::ALM) not complete */ -#define BVAR_UTC_INVALID ( 1UL << BVAR_BIT_UTC_INVALID ) /**< @brief UTC data not valid */ -#define BVAR_IONO_INVALID ( 1UL << BVAR_BIT_IONO_INVALID ) /**< @brief Ionospheric correction data (::IONO) not valid */ -#define BVAR_RCVR_POS_INVALID ( 1UL << BVAR_BIT_RCVR_POS_INVALID ) /**< @brief Receiver position (::POS) not valid */ +#define BVAR_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 -#define BVAR_MASK ( ( 1UL << N_BVAR_BIT ) - 1 ) /**< @brief Bit mask for all defined bits */ +#define BVAR_MASK ( ( 1UL << N_BVAR_BIT ) - 1 ) ///< Bit mask for all defined bits /** @} group_bvar_stat */ /** - A structure used to hold a fixed frequency value. - frequ[kHz] = khz_val * 10^range -*/ - + * @brief A structure used to hold a fixed frequency value + * + * @note frequ[kHz] = khz_val * 10^range + */ typedef struct { - uint16_t khz_val; /* the base frequency in [kHz] */ - int16_t range; /* an optional base 10 exponent */ + uint16_t khz_val; ///< the base frequency in [kHz] + int16_t range; ///< an optional base 10 exponent } FIXED_FREQ_INFO; #define _mbg_swab_fixed_freq_info( _p ) \ @@ -522,38 +612,36 @@ typedef struct } -typedef uint32_t RI_FEATURES; // type of RECEIVER_INFO::features field +/** + * @brief A data type to specify feature flags within ::RECEIVER_INFO + */ +typedef uint32_t RI_FEATURES; ///< @see GPS_FEATURE_MASKS -/* - * The following code defines features and properties - * of the various GPS receivers. Older GPS receivers - * may require a recent firmvare version to support - * this, or may not support this at all. - */ /** - * The structure is ordered in a way that all fields - * except chars or arrays of chars are word-aligned. + * @brief A structure used to identify a device type and supported features + * + * @note This may not be supported by some very old devices. */ typedef struct { - uint16_t model_code; /**< identifier for receiver model */ - SW_REV sw_rev; /**< software revision and ID */ - char model_name[GPS_ID_STR_SIZE]; /**< ASCIIZ, name of receiver model */ - char sernum[GPS_ID_STR_SIZE]; /**< ASCIIZ, serial number */ - char epld_name[GPS_EPLD_STR_SIZE]; /**< ASCIIZ, file name of EPLD image */ - uint8_t n_channels; /**< number of sats to be tracked simultaneously */ - uint32_t ticks_per_sec; /**< resolution of fractions of seconds */ - RI_FEATURES features; /**< optional features, see below */ - FIXED_FREQ_INFO fixed_freq; /**< optional non-standard fixed frequency */ - uint8_t osc_type; /**< type of installed oscillator, see below */ - uint8_t osc_flags; /**< oscillator flags, see below */ - uint8_t n_ucaps; /**< number of user time capture inputs */ - uint8_t n_com_ports; /**< number of on-board serial ports */ - uint8_t n_str_type; /**< max num of string types supported by any port */ - uint8_t n_prg_out; /**< number of programmable pulse outputs */ - uint16_t flags; /**< additional information, see below */ + uint16_t model_code; ///< identifier for receiver model, see ::GPS_MODEL_CODES + SW_REV sw_rev; ///< software revision and ID + char model_name[GPS_ID_STR_SIZE]; ///< ASCIIZ, name of receiver model + char sernum[GPS_ID_STR_SIZE]; ///< ASCIIZ, serial number + char epld_name[GPS_EPLD_STR_SIZE]; ///< ASCIIZ, file name of EPLD image + 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 + uint8_t osc_type; ///< type of installed oscillator, see ::GPS_OSC_TYPES + uint8_t osc_flags; ///< oscillator flags, actually not used and always 0 + uint8_t n_ucaps; ///< number of user time capture inputs + uint8_t n_com_ports; ///< number of on-board serial ports + uint8_t n_str_type; ///< max num of string types supported by any port + uint8_t n_prg_out; ///< number of programmable pulse outputs + uint16_t flags; ///< additional information, see ::RECEIVER_INFO_FLAG_BITS } RECEIVER_INFO; #define _mbg_swab_receiver_info( _p ) \ @@ -568,9 +656,9 @@ typedef struct /** - * Valid codes for RECEIVER_INFO.model_code: + * @brief Known device ID codes for RECEIVER_INFO::model_code */ -enum +enum GPS_MODEL_CODES { GPS_MODEL_UNKNOWN, GPS_MODEL_GPS166, @@ -615,6 +703,14 @@ enum GPS_MODEL_GPS180AMC, GPS_MODEL_ESI180, GPS_MODEL_CPE180, + GPS_MODEL_LNO180, + GPS_MODEL_GRC180, + GPS_MODEL_LIU, + GPS_MODEL_DCF600HS, + GPS_MODEL_DCF600RS, + GPS_MODEL_MRI, + GPS_MODEL_BPE, + GPS_MODEL_GLN180PEX, N_GPS_MODEL /* If new model codes are added then care must be taken * to update the associated string initializers below @@ -672,6 +768,14 @@ enum #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" /* * The definition below can be used to initialize @@ -723,7 +827,15 @@ enum GPS_MODEL_NAME_GPS180HS, \ GPS_MODEL_NAME_GPS180AMC, \ GPS_MODEL_NAME_ESI180, \ - GPS_MODEL_NAME_CPE180 \ + GPS_MODEL_NAME_CPE180, \ + GPS_MODEL_NAME_LNO180, \ + GPS_MODEL_NAME_GRC180, \ + GPS_MODEL_NAME_LIU, \ + GPS_MODEL_NAME_DCF600HS, \ + GPS_MODEL_NAME_DCF600RS, \ + GPS_MODEL_NAME_MRI, \ + GPS_MODEL_NAME_BPE, \ + GPS_MODEL_NAME_GLN180PEX \ } @@ -804,12 +916,12 @@ enum /** - * The classification codes for oscillators below - * are used with RECEIVER_INFO.osc_type. New codes - * must be appended to the enumeration, so the sequence - * of codes does NOT reflect the order of quality: + * @brief Oscillator classification codes used with RECEIVER_INFO::osc_type + * + * New codes will just be appended to the enumeration, so the sequence + * of codes does NOT reflect the order of quality. */ -enum +enum GPS_OSC_TYPES { GPS_OSC_UNKNOWN, GPS_OSC_TCXO_LQ, @@ -867,50 +979,56 @@ enum -/* - * Codes to be used with RECEIVER_INFO.osc_flags - * are not yet used/required, so they are reserved - * for future use. - */ - - /** - * The codes below enumerate some features which may be - * supported by a given clock, or not. - */ -enum -{ - GPS_FEAT_PPS, /**< has pulse per second output */ - GPS_FEAT_PPM, /**< has pulse per minute output */ - GPS_FEAT_SYNTH, /**< has programmable synthesizer output */ - GPS_FEAT_DCFMARKS, /**< has DCF77 compatible time mark output */ - GPS_FEAT_IRIG_TX, /**< has on-board IRIG output */ - GPS_FEAT_IRIG_RX, /**< has on-board IRIG input */ - GPS_FEAT_LAN_IP4, /**< has LAN IPv4 interface */ - GPS_FEAT_MULTI_REF, /**< has multiple input sources with priorities */ - - GPS_FEAT_RCV_TIMEOUT, /**< timeout after GPS reception has stopped */ - GPS_FEAT_IGNORE_LOCK, /**< supports "ignore lock", MBG_OPT_BIT_EMU_SYNC can be set alternatively */ - GPS_FEAT_5_MHZ, /**< output 5 MHz rather than 100 kHz */ - GPS_FEAT_XMULTI_REF, /**< has extended multiple input source configuration */ - GPS_FEAT_OPT_SETTINGS, /**< supports MBG_OPT_SETTINGS */ - GPS_FEAT_TIME_SCALE, /**< supports configurable time scale (UTC, TAI, GPS, ...) */ - GPS_FEAT_IRIG_CTRL_BITS, /**< supports IRIG control bits */ - GPS_FEAT_PTP, /**< has PTP support */ - - GPS_FEAT_NAV_ENGINE_SETTINGS, /**< supports navigation engine configuration */ - GPS_FEAT_RAW_IRIG_DATA, /**< supports reading raw IRIG input data */ - GPS_FEAT_RAW_IRIG_TIME, /**< supports reading decoded IRIG time */ - GPS_FEAT_PTP_UNICAST, /**< has PTP Unicast support */ - GPS_FEAT_GPIO, /**< has general purpose in/outputs */ - GPS_FEAT_XMRS_MULT_INSTC, /**< multiple XMRS instances of the same ref type supported, @see XMRSF_BIT_MULT_INSTC_SUPP */ - GPS_FEAT_10MHZ_DISBD, /**< 10 MHz output is always disabled */ - GPS_FEAT_EVT_LOG, /**< Event logging supported */ - - N_GPS_FEATURE /**< the number of valid features */ + * @brief Enumeration of device features flags reported in RECEIVER_INFO::features + * + * Each flags indicates if a device supports the associated feature. + */ +enum GPS_FEATURE_BITS +{ + GPS_FEAT_PPS, ///< has pulse per second output + GPS_FEAT_PPM, ///< has pulse per minute output + GPS_FEAT_SYNTH, ///< has programmable synthesizer output + GPS_FEAT_DCFMARKS, ///< has DCF77 compatible time mark output + GPS_FEAT_IRIG_TX, ///< has on-board IRIG output + GPS_FEAT_IRIG_RX, ///< has on-board IRIG input + GPS_FEAT_LAN_IP4, ///< has LAN IPv4 interface + GPS_FEAT_MULTI_REF, ///< has multiple input sources with priorities + + GPS_FEAT_RCV_TIMEOUT, ///< timeout after GPS reception has stopped + GPS_FEAT_IGNORE_LOCK, ///< supports "ignore lock", MBG_OPT_BIT_EMU_SYNC can be set alternatively + GPS_FEAT_5_MHZ, ///< output 5 MHz rather than 100 kHz + GPS_FEAT_XMULTI_REF, ///< has extended multiple input source configuration + GPS_FEAT_OPT_SETTINGS, ///< supports MBG_OPT_SETTINGS + GPS_FEAT_TIME_SCALE, ///< supports configurable time scale (%UTC, TAI, GPS, ...) + GPS_FEAT_IRIG_CTRL_BITS, ///< supports IRIG control bits + GPS_FEAT_PTP, ///< has PTP support + + GPS_FEAT_NAV_ENGINE_SETTINGS, ///< supports navigation engine configuration + GPS_FEAT_RAW_IRIG_DATA, ///< supports reading raw IRIG input data + GPS_FEAT_RAW_IRIG_TIME, ///< supports reading decoded IRIG time + GPS_FEAT_PTP_UNICAST, ///< has PTP Unicast support + GPS_FEAT_GPIO, ///< has general purpose in/outputs + GPS_FEAT_XMRS_MULT_INSTC, ///< multiple XMRS instances of the same ref type supported, see ::XMRSF_BIT_MULT_INSTC_SUPP + GPS_FEAT_10MHZ_DISBD, ///< 10 MHz output is always disabled + GPS_FEAT_EVT_LOG, ///< Event logging supported + + 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. + */ }; +/** + * @brief Names of device features + * + * @see GPS_FEATURE_BITS + */ #define DEFAULT_GPS_FEATURE_NAMES \ { \ "Pulse Per Second", \ @@ -936,40 +1054,50 @@ enum "General Purpose I/O", \ "Multiple XMRS Instances", \ "10 MHz Output Disabled", \ - "Event Logging" \ + "Event Logging", \ + "IMS data", \ + "HaveQuick" \ } -/* - * Bit masks used with RECEIVER_INFO.features - * (others are reserved): - */ -#define GPS_HAS_PPS ( 1UL << GPS_FEAT_PPS ) -#define GPS_HAS_PPM ( 1UL << GPS_FEAT_PPM ) -#define GPS_HAS_SYNTH ( 1UL << GPS_FEAT_SYNTH ) -#define GPS_HAS_DCFMARKS ( 1UL << GPS_FEAT_DCFMARKS ) -#define GPS_HAS_IRIG_TX ( 1UL << GPS_FEAT_IRIG_TX ) -#define GPS_HAS_IRIG_RX ( 1UL << GPS_FEAT_IRIG_RX ) -#define GPS_HAS_LAN_IP4 ( 1UL << GPS_FEAT_LAN_IP4 ) -#define GPS_HAS_MULTI_REF ( 1UL << GPS_FEAT_MULTI_REF ) -#define GPS_HAS_RCV_TIMEOUT ( 1UL << GPS_FEAT_RCV_TIMEOUT ) -#define GPS_HAS_IGNORE_LOCK ( 1UL << GPS_FEAT_IGNORE_LOCK ) -#define GPS_HAS_5_MHZ ( 1UL << GPS_FEAT_5_MHZ ) -#define GPS_HAS_XMULTI_REF ( 1UL << GPS_FEAT_XMULTI_REF ) -#define GPS_HAS_OPT_SETTINGS ( 1UL << GPS_FEAT_OPT_SETTINGS ) -#define GPS_HAS_TIME_SCALE ( 1UL << GPS_FEAT_TIME_SCALE ) -#define GPS_HAS_IRIG_CTRL_BITS ( 1UL << GPS_FEAT_IRIG_CTRL_BITS ) -#define GPS_HAS_PTP ( 1UL << GPS_FEAT_PTP ) -#define GPS_HAS_NAV_ENGINE_SETTINGS ( 1UL << GPS_FEAT_NAV_ENGINE_SETTINGS ) -#define GPS_HAS_RAW_IRIG_DATA ( 1UL << GPS_FEAT_RAW_IRIG_DATA ) -#define GPS_HAS_RAW_IRIG_TIME ( 1UL << GPS_FEAT_RAW_IRIG_TIME ) -#define GPS_HAS_PTP_UNICAST ( 1UL << GPS_FEAT_PTP_UNICAST ) -#define GPS_HAS_GPIO ( 1UL << GPS_FEAT_GPIO ) -#define GPS_HAS_XMRS_MULT_INSTC ( 1UL << GPS_FEAT_XMRS_MULT_INSTC ) -#define GPS_HAS_10MHZ_DISBD ( 1UL << GPS_FEAT_10MHZ_DISBD ) -#define GPS_HAS_EVT_LOG ( 1UL << GPS_FEAT_EVT_LOG ) - -#define GPS_HAS_REF_OFFS GPS_HAS_IRIG_RX +/** + * @brief Bit masks used with RECEIVER_INFO::features + * @name GPS_FEATURE_MASKS + * @see GPS_FEATURE_BITS + */ +#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 + +// 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_INFO GPS_HAS_IRIG_RX ///< always supported with IRIG inputs, see ::GPS_HAS_IRIG_RX /* @@ -985,12 +1113,20 @@ enum } -/* - * Codes to be used with RECEIVER_INFO::flags: +/** + * @brief Bits to be used with RECEIVER_INFO::flags */ -#define GPS_OSC_CFG_SUPP 0x0001 // GPS_OSC_CFG supported -#define GPS_IRIG_FO_IN 0x0002 // IRIG input via fiber optics -#define GPS_HAS_FPGA 0x0004 // device provides on-board FPGA +enum RECEIVER_INFO_FLAG_BITS +{ + GPS_BIT_OSC_CFG_SUPP, ///< oscillator cfg is supported, see ::RECEIVER_INFO::osc_type + GPS_BIT_IRIG_FO_IN, ///< IRIG input via fiber optics + GPS_BIT_HAS_FPGA, ///< device provides on-board FPGA + N_RECEIVER_INFO_FLAG_BITS ///< number of known bits +}; + +#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 ) @@ -1044,18 +1180,27 @@ typedef struct /** - Date and time referred to the linear time scale defined by GPS. - GPS time is defined by the number of weeks since midnight from - January 5, 1980 to January 6, 1980 plus the number of seconds of - the current week plus fractions of a second. GPS time differs from - UTC because UTC is corrected with leap seconds while GPS time scale - is continuous. -*/ + * @brief A structure used to hold time in GPS format + * + * Date and time refer to the linear time scale defined by GPS, with + * the epoch starting at %UTC midnight at the beginning of January 6, 1980. + * + * GPS time is counted by the week numbers since the epoch, plus second + * of the week, plus fraction of the second. The week number transmitted + * by the satellites rolls over from 1023 to 0, but Meinberg devices + * just continue to count the weeks beyond the 1024 week limit to keep + * the receiver's internal time. + * + * %UTC time differs from GPS time since a number of leap seconds have + * been inserted in the %UTC time scale after the GPS epoche. The number + * of leap seconds is disseminated by the satellites using the ::UTC + * parameter set, which also provides info on pending leap seconds. + */ typedef struct { - uint16_t wn; /**< the week number since GPS has been installed */ - uint32_t sec; /**< the second of that week */ - uint32_t tick; /**< fractions of a second; scale: 1/GPS_TICKS_PER_SEC */ + uint16_t wn; ///< the week number since GPS has been installed + uint32_t sec; ///< the second of that week + uint32_t tick; ///< fractions of a second; scale: 1/::RECEIVER_INFO::ticks_per_sec } T_GPS; #define _mbg_swab_t_gps( _p ) \ @@ -1067,26 +1212,31 @@ typedef struct /** - Local date and time computed from GPS time. The current number - of leap seconds have to be added to get UTC from GPS time. - Additional corrections could have been made according to the - time zone/daylight saving parameters (TZDL, see below) defined - by the user. The status field can be checked to see which corrections - have been applied. -*/ + * @brief Local date and time computed from GPS time + * + * The current number of leap seconds have to be added to get %UTC + * from GPS time. Additional corrections could have been made according + * to the time zone/daylight saving parameters ::TZDL defined by the user. + * The status field can be checked to see which corrections + * have actually been applied. + * + * @note Conversion from GPS time to %UTC and/or local time can only be + * done if some valid ::UTC correction parameters are available in the + * receiver's non-volatile memory. + */ typedef struct { - int16_t year; /**< year number, 0..9999 */ - int8_t month; /**< month, 1..12 */ - int8_t mday; /**< day of month, 1..31 */ - int16_t yday; /**< day of year, 1..366 */ - int8_t wday; /**< day of week, 0..6 == Sun..Sat */ - int8_t hour; /**< hours, 0..23 */ - int8_t min; /**< minutes, 0..59 */ - int8_t sec; /**< seconds, 0..59 */ - int32_t frac; /**< fractions of a second; scale: 1/GPS_TICKS_PER_SEC */ - int32_t offs_from_utc; /**< local time's offset from UTC */ - uint16_t status; /**< status flags */ + int16_t year; ///< year number, 0..9999 + int8_t month; ///< month, 1..12 + int8_t mday; ///< day of month, 1..31 + int16_t yday; ///< day of year, 1..366 + int8_t wday; ///< day of week, 0..6 == Sun..Sat + int8_t hour; ///< hours, 0..23 + int8_t min; ///< minutes, 0..59 + int8_t sec; ///< seconds, 0..59 + int32_t frac; ///< fractions of a second; scale: 1/::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 } TM_GPS; #define _mbg_swab_tm_gps( _p ) \ @@ -1099,44 +1249,34 @@ typedef struct } -/* status flag bits used with conversion from GPS time to local time */ - -enum -{ - TM_BIT_UTC, /* UTC correction has been made */ - TM_BIT_LOCAL, /* UTC has been converted to local time */ - TM_BIT_DL_ANN, /* state of daylight saving is going to change */ - TM_BIT_DL_ENB, /* daylight saving is enabled */ - TM_BIT_LS_ANN, /* leap second will be inserted */ - TM_BIT_LS_ENB, /* current second is leap second */ - TM_BIT_LS_ANN_NEG, /* set in addition to TM_LS_ANN if leap sec negative */ - TM_BIT_INVT, /* invalid time, e.g. if RTC battery empty */ - - TM_BIT_EXT_SYNC, /* sync'd externally */ - TM_BIT_HOLDOVER, /* holdover mode after previous sync. */ - TM_BIT_ANT_SHORT, /* antenna cable short circuited */ - TM_BIT_NO_WARM, /* OCXO has not warmed up */ - TM_BIT_ANT_DISCONN, /* antenna currently disconnected */ - TM_BIT_SYN_FLAG, /* TIME_SYN output is low */ - TM_BIT_NO_SYNC, /* time sync actually not verified */ - TM_BIT_NO_POS /* position actually not verified, LOCK LED off */ -}; - -// Type of an extended TM status which is mainly used by the firmware. -typedef uint32_t TM_STATUS_EXT; // extended status, mainly used by the firmware - -// The lower 16 bits of the TM_STATUS_X type correspond to those defined above, -// and the upper bits are defined below: -enum -{ - TM_BIT_SCALE_GPS = 16, - TM_BIT_SCALE_TAI - // the remaining bits are reserved +/** + * @brief Status flags 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. + */ +enum TM_GPS_STATUS_BITS +{ + TM_BIT_UTC, ///< %UTC correction has been made + TM_BIT_LOCAL, ///< %UTC has been converted to local time according to ::TZDL settings + TM_BIT_DL_ANN, ///< state of daylight saving is going to change + TM_BIT_DL_ENB, ///< daylight saving is in effect + TM_BIT_LS_ANN, ///< leap second pending + TM_BIT_LS_ENB, ///< current second is leap second + TM_BIT_LS_ANN_NEG, ///< set in addition to ::TM_BIT_LS_ANN if leap sec is negative + TM_BIT_INVT, ///< invalid time, e.g. if RTC battery bas been empty + + TM_BIT_EXT_SYNC, ///< synchronized externally + TM_BIT_HOLDOVER, ///< in holdover mode after previous synchronization + TM_BIT_ANT_SHORT, ///< antenna cable short circuited + TM_BIT_NO_WARM, ///< OCXO has not warmed up + TM_BIT_ANT_DISCONN, ///< antenna currently disconnected + TM_BIT_SYN_FLAG, ///< TIME_SYN output is low + TM_BIT_NO_SYNC, ///< time sync actually not verified + TM_BIT_NO_POS ///< position actually not verified, LOCK LED off }; - -/* bit masks corresponding to the flag bits above */ - +// 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 ) @@ -1155,20 +1295,44 @@ enum #define TM_NO_SYNC ( 1UL << TM_BIT_NO_SYNC ) #define TM_NO_POS ( 1UL << TM_BIT_NO_POS ) + +/** + * @brief Type of an extended TM status which is mainly used inside the firmware + */ +typedef uint32_t TM_STATUS_EXT; + +/** + * @brief Enumeration of extended status bits used with TM_STATUS_EXT + * + * @note The lower 16 bits correspond to ::TM_GPS_STATUS_BITS + */ +enum TM_GPS_STATUS_BITS_EX +{ + TM_BIT_SCALE_GPS = 16, ///< time scale configured to return GPS time + TM_BIT_SCALE_TAI ///< time scale configured to return TAI + // the remaining bits are reserved +}; + // The following bits are only used with the TM_STATUS_X type: #define TM_SCALE_GPS ( 1UL << TM_BIT_SCALE_GPS ) #define TM_SCALE_TAI ( 1UL << TM_BIT_SCALE_TAI ) #define TM_MSK_TIME_VALID ( TM_UTC | TM_SCALE_GPS | TM_SCALE_TAI ) + /** * @brief A structure used to transmit information on date and time + * + * This structure can be used to transfer the current time, in which + * case the channel field has to be set to -1, or an event capture time + * retrieved from the on-board FIFO, in which case the channel field + * contains the index of the time capture input, e.g. 0 or 1. */ typedef struct { - int16_t channel; /**< -1: the current time; 0, 1: capture 0, 1 */ - T_GPS t; /**< time in GPS format */ - TM_GPS tm; /**< that time converted to local time */ + int16_t channel; ///< -1: the current on-board time; >= 0 the capture channel number + T_GPS t; ///< time in GPS scale and format + TM_GPS tm; ///< time converted to %UTC and/or local time according to ::TZDL settings } TTM; #define _mbg_swab_ttm( _p ) \ @@ -1180,10 +1344,13 @@ typedef struct +/** + * @brief A timestamp with nanosecond resolution + */ typedef struct { - int32_t nano_secs; // [nanoseconds] - int32_t secs; // [seconds] + int32_t nano_secs; ///< [nanoseconds] + int32_t secs; ///< [seconds] } NANO_TIME; #define _mbg_swab_nano_time( _p ) \ @@ -1205,11 +1372,15 @@ typedef struct /* System from 1984). */ #ifndef _XYZ_DEFINED - /* sequence and number of components of a cartesian position */ - enum { XP, YP, ZP, N_XYZ }; + /** + * @brief Sequence and number of components of a cartesian position + */ + enum XYZ_FIELDS { XP, YP, ZP, N_XYZ }; // x, y, z - /** @brief An array holding a cartesian position */ - typedef double XYZ[N_XYZ]; /**< values are in [m] */ + /** + * @brief An array holding a cartesian position + */ + typedef double XYZ[N_XYZ]; ///< values are in [m], see ::XYZ_FIELDS #define _XYZ_DEFINED #endif @@ -1218,11 +1389,15 @@ typedef struct #ifndef _LLA_DEFINED - /* sequence and number of components of a geographic position */ - enum { LAT, LON, ALT, N_LLA }; /* latitude, longitude, altitude */ + /** + * @brief Sequence and number of components of a geographic position + */ + enum LLA_FIELDS { LAT, LON, ALT, N_LLA }; /* latitude, longitude, altitude */ - /** @brief An array holding a geographic position */ - typedef double LLA[N_LLA]; /**< lon, lat in [rad], alt in [m] */ + /** + * @brief An array holding a geographic position + */ + typedef double LLA[N_LLA]; ///< lon, lat in [rad], alt in [m], see ::LLA_FIELDS #define _LLA_DEFINED #endif @@ -1261,8 +1436,8 @@ typedef struct @{ */ -#define N_SYNTH_FREQ_DIGIT 4 /**< number of digits to edit */ -#define MAX_SYNTH_FREQ 1000 /**< if range == MAX_SYNTH_RANGE */ +#define N_SYNTH_FREQ_DIGIT 4 ///< number of digits to edit +#define MAX_SYNTH_FREQ 1000 ///< if range == ::MAX_SYNTH_RANGE #define MIN_SYNTH_RANGE 0 #define MAX_SYNTH_RANGE 5 @@ -1272,24 +1447,32 @@ typedef struct #define MAX_SYNTH_PHASE 3600 -#define MAX_SYNTH_FREQ_EDIT 9999 /**< max sequence of digits when editing */ +#define MAX_SYNTH_FREQ_EDIT 9999 ///< max sequence of digits when editing -/** @brief The maximum frequency that can be configured for the synthesizer */ -#define MAX_SYNTH_FREQ_VAL 10000000UL /**< 10 MHz */ +/** + * @brief The maximum frequency that can be configured for the synthesizer + */ +#define MAX_SYNTH_FREQ_VAL 10000000UL ///< 10 MHz /* == MAX_SYNTH_FREQ * 10^(MAX_SYNTH_RANGE-1) */ -/** @brief The synthesizer's phase is only be synchronized if the frequency is below this limit */ -#define SYNTH_PHASE_SYNC_LIMIT 10000UL /**< 10 kHz */ +/** + * @brief The synthesizer's phase is only be synchronized if the frequency is below this limit + */ +#define SYNTH_PHASE_SYNC_LIMIT 10000UL ///< 10 kHz /** - the position of the decimal point if the frequency is - printed as 4 digit value */ + * A Macro used to determine the position of the decimal point + * when printing the synthesizer frequency as 4 digit value + */ #define _synth_dp_pos_from_range( _r ) \ ( ( ( N_SYNTH_RANGE - (_r) ) % ( N_SYNTH_FREQ_DIGIT - 1 ) ) + 1 ) /** - An initializer for commonly displayed synthesizer frequency units - (N_SYNTH_RANGE strings) */ + * @brief Synthesizer frequency units + * + * An initializer for commonly displayed synthesizer frequency units + * (N_SYNTH_RANGE strings) + */ #define DEFAULT_FREQ_RANGES \ { \ "Hz", \ @@ -1302,11 +1485,14 @@ typedef struct +/** + * @brief Synthesizer configuration parameters + */ typedef struct { - int16_t freq; /**< four digits used; scale: 0.1; e.g. 1234 -> 123.4 Hz */ - int16_t range; /**< scale factor for freq; 0..MAX_SYNTH_RANGE */ - int16_t phase; /**< -MAX_SYNTH_PHASE..+MAX_SYNTH_PHASE; >0 -> pulses later */ + int16_t freq; ///< four digits used; scale: 0.1; 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 ) \ @@ -1318,23 +1504,26 @@ typedef struct /** - The definitions below can be used to query the - current synthesizer state. + * @brief Enumeration of synthesizer states */ -enum +enum SYNTH_STATES { - SYNTH_DISABLED, /**< disbled by cfg, i.e. freq == 0.0 */ - SYNTH_OFF, /**< not enabled after power-up */ - SYNTH_FREE, /**< enabled, but not synchronized */ - SYNTH_DRIFTING, /**< has initially been sync'd, but now running free */ - SYNTH_SYNC, /**< fully synchronized */ - N_SYNTH_STATE /**< the number of known states */ + SYNTH_DISABLED, ///< disbled by cfg, i.e. freq == 0.0 + SYNTH_OFF, ///< not enabled after power-up + SYNTH_FREE, ///< enabled, but not synchronized + SYNTH_DRIFTING, ///< has initially been sync'd, but now running free + SYNTH_SYNC, ///< fully synchronized + N_SYNTH_STATE ///< the number of known states }; + +/** + * @brief A structure used to report the synthesizer state + */ typedef struct { - uint8_t state; /**< state code as enumerated above */ - uint8_t flags; /**< reserved, currently always 0 */ + uint8_t state; ///< state code as enumerated in ::SYNTH_STATES + uint8_t flags; ///< reserved, currently always 0 } SYNTH_STATE; #define _mbg_swab_synth_state( _p ) _nop_macro_fnc() @@ -1344,30 +1533,41 @@ typedef struct /** @} 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 + * @{ + */ -/** the name of a time zone, 5 characters plus trailing zero */ +/** + * @brief The name of a time zone + * + * @note Up to 5 printable characters plus trailing zero + */ typedef char TZ_NAME[6]; +/** + * @brief Time zone / daylight saving parameters + * + * This structure is used to specify how a device is to convert + * on-board %UTC to local time, including computation of beginning + * and end of daylight saving time (DST), if required. + */ typedef struct { - int32_t offs; /**< offset from UTC to local time [sec] */ - int32_t offs_dl; /**< additional offset if daylight saving enabled [sec] */ - TM_GPS tm_on; /**< date/time when daylight saving starts */ - TM_GPS tm_off; /**< date/time when daylight saving ends */ - TZ_NAME name[2]; /**< names without and with daylight saving enabled */ + int32_t offs; ///< standard offset from %UTC to local time [sec] + int32_t offs_dl; ///< additional offset if daylight saving enabled [sec] + TM_GPS tm_on; ///< date/time when daylight saving starts + TM_GPS tm_off; ///< date/time when daylight saving ends + TZ_NAME name[2]; ///< names without and with daylight saving enabled } TZDL; #define _mbg_swab_tzdl( _p ) \ @@ -1380,8 +1580,10 @@ typedef struct /** - If the year in tzdl.tm_on and tzdl.tm_off is or'ed with that constant, - the receiver automatically generates daylight saving year by year. + * @brief A flag indicating automatic computation of DST + * + * If this flag is or'ed to the year numbers in TZDL::tm_on and TZDL::tm_off + * then daylight saving is computed automatically year by year. */ #define DL_AUTO_FLAG 0x8000 @@ -1395,14 +1597,14 @@ typedef struct /** - The symbol below can be used to initialize both the tm_on - and tm_off fields for time zones which do not switch to DST: + * An initializer for TZDL::tm_on and TZDL::tm_off for time zones + * which do not observe DST. */ #define DEFAULT_TZDL_TM_ON_OFF_NO_DST \ { DEFAULT_TZDL_AUTO_YEAR, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0 } -// Settings used with UTC: +// Settings used with %UTC: #define TZ_INFO_UTC "UTC (Universal Time, Coordinated)" @@ -1419,13 +1621,14 @@ typedef struct /** - The symbols below specify beginning and end of DST for - Central Europe, as constituted by the European Parliament: - */ - + * @brief An initializer for TZDL::tm_on according to the rules for Central Europe + */ #define DEFAULT_TZDL_TM_ON_CET_CEST \ { DEFAULT_TZDL_AUTO_YEAR, 3, 25, 0, 0, 2, 0, 0, 0L, 0L, 0 } +/** + * @brief An initializer for TZDL::tm_off according to the rules for Central Europe + */ #define DEFAULT_TZDL_TM_OFF_CET_CEST \ { DEFAULT_TZDL_AUTO_YEAR, 10, 25, 0, 0, 3, 0, 0, 0L, 0L, 0 } @@ -1499,17 +1702,28 @@ typedef struct /** @} group_tzdl */ + + /** + * @brief Antenna status 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. + * + * @note ANT_INFO::status changes back to ::ANT_RECONN only + * after the antenna has been reconnected <b>and</b> the + * receiver has re-synchronized to the satellite signal. + * In this case ANT_INFO::delta_t reports the time offset + * before resynchronization, i.e. how much the internal + * time has drifted while the antenna was disconnected. */ typedef struct { - int16_t status; /**< current status of antenna */ - TM_GPS tm_disconn; /**< time of antenna disconnect */ - TM_GPS tm_reconn; /**< time of antenna reconnect */ - int32_t delta_t; /**< clock offs. at reconn. time in #GPS_TICKS_PER_SEC */ + int16_t status; ///< current status of antenna, see ::ANT_STATUS_CODES + TM_GPS tm_disconn; ///< time of antenna disconnect + TM_GPS tm_reconn; ///< time of antenna reconnect + int32_t delta_t; ///< clock offs at reconn. time in 1/::RECEIVER_INFO::ticks_per_sec } ANT_INFO; #define _mbg_swab_ant_info( _p ) \ @@ -1522,15 +1736,17 @@ typedef struct /** - The status field may be set to one of the values below: -*/ -enum + * @brief Status code used with ANT_INFO::status + */ +enum ANT_STATUS_CODES { - ANT_INVALID, /**< struct not set yet because ant. has not been disconn. */ - ANT_DISCONN, /**< ant. now disconn., tm_reconn and delta_t not set */ - ANT_RECONN /**< ant. has been disconn. and reconn., all fields valid */ + ANT_INVALID, ///< No other fields valid since antenna has not yet been disconnected + ANT_DISCONN, ///< Antenna is disconnected, tm_reconn and delta_t not yet set + ANT_RECONN, ///< Antenna has been disconnect, and receiver sync. after reconnect, so all fields valid + N_ANT_STATUS_CODES ///< the number of known status codes }; + /* Defines used with ENABLE_FLAGS */ #define EF_OFF 0x00 /**< outputs off until sync'd */ @@ -1541,19 +1757,21 @@ enum #define EF_SYNTH 0x01 /**< synth. on */ /** - The structure holds some flags which let - the corresponding outputs be disabled after power-up until - the receiver has synchronized (flag == 0x00, the default) or force - the outputs to be enabled immediately after power-up. The fixed - frequency output is hard-wired to be enabled immediately after - power-up, so the code for freq must always be 0x03. -*/ + * @brief A structure controlling when output signals are enabled + * + * The structure holds some flags which let the corresponding outputs + * be disabled after power-up until the receiver has synchronized + * (flag == ::EF_OFF, the default) or force the outputs to be enabled + * immediately after power-up. The fixed frequency output is hard-wired + * to be enabled immediately after power-up, so ENABLE_FLAGS::freq must + * always be set to ::EF_FREQ_ALL. + */ typedef struct { - uint16_t serial; /**< #EF_OFF or #EF_SERIAL_BOTH */ - uint16_t pulses; /**< #EF_OFF or #EF_PULSES_BOTH */ - uint16_t freq; /**< always #EF_FREQ_ALL */ - uint16_t synth; /**< #EF_OFF or #EF_SYNTH */ + uint16_t serial; ///< ::EF_OFF or ::EF_SERIAL_BOTH + uint16_t pulses; ///< ::EF_OFF or ::EF_PULSES_BOTH + uint16_t freq; ///< always ::EF_FREQ_ALL + uint16_t synth; ///< ::EF_OFF or ::EF_SYNTH } ENABLE_FLAGS; #define _mbg_swab_enable_flags( _p ) \ @@ -1568,22 +1786,33 @@ typedef struct /* A struct used to hold the settings of a serial port: */ #ifndef _COM_HS_DEFINED - /* types of handshake */ - enum { HS_NONE, HS_XONXOFF, HS_RTSCTS, N_COM_HS }; + /** + * @brief Enumeration of handshake modes + */ + enum COM_HANSHAKE_MODES { HS_NONE, HS_XONXOFF, HS_RTSCTS, N_COM_HS }; #define _COM_HS_DEFINED #endif #ifndef _COM_PARM_DEFINED + /** + * @brief A data type to configure a baud rate + */ typedef int32_t BAUD_RATE; - /* indices used to identify a parameter in the framing string */ + /** + * @brief Indices used to identify a parameter in the framing string + */ enum { F_DBITS, F_PRTY, F_STBITS }; + /** + * @brief A structure to store the configuration of a serial port + */ typedef struct { - BAUD_RATE baud_rate; /* e.g. 19200L */ - char framing[4]; /* e.g. "8N1" */ - int16_t handshake; /* a numeric value, only HS_NONE supported yet */ + BAUD_RATE baud_rate; ///< transmission speed, e.g. 19200L + char framing[4]; ///< ASCIIZ framing string, e.g. "8N1" or "7E2" + int16_t handshake; ///< handshake mode, yet only ::HS_NONE supported + } COM_PARM; #define _COM_PARM_DEFINED @@ -1598,12 +1827,12 @@ typedef struct } -/* - * Indices of any supported baud rates. - * Note that not each baud rate must be supported by - * any clock model and/or port: +/** + * @brief Indices of any supported serial port baud rates + * + * @note Most clock models and/or serial ports don't support all defined baud rates. */ -enum +enum MBG_BAUD_RATE_CODES { MBG_BAUD_RATE_300, MBG_BAUD_RATE_600, @@ -1613,7 +1842,7 @@ enum MBG_BAUD_RATE_9600, MBG_BAUD_RATE_19200, MBG_BAUD_RATE_38400, - N_MBG_BAUD_RATES /* the number of supported baud rates */ + N_MBG_BAUD_RATES /**< the number of supported baud rates */ }; /* @@ -1665,12 +1894,12 @@ enum #define MBG_PORT_HAS_38400 ( 1UL << MBG_BAUD_RATE_38400 ) -/* - * Indices of any supported framings. - * Note that not each framing must be supported by - * any clock model and/or port: +/** + * @brief Indices of any supported serial port framings. + * + * @note Most clock models and/or serial ports don't support all defined framing types. */ -enum +enum MBG_FRAMING_CODES { MBG_FRAMING_7N2, MBG_FRAMING_7E1, @@ -1681,7 +1910,8 @@ enum MBG_FRAMING_7O1, MBG_FRAMING_7O2, MBG_FRAMING_8O1, - N_MBG_FRAMINGS /* the number of supported framings */ + MBG_FRAMING_8E2, /**< @note: Most serial ports don't support this! */ + N_MBG_FRAMINGS /**< the number of supported framings */ }; /* @@ -1698,7 +1928,8 @@ enum "8E1", \ "7O1", \ "7O2", \ - "8O1" \ + "8O1", \ + "8E2" \ } /* @@ -1717,6 +1948,13 @@ enum #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 ) + + +// Default port settings to be used +// with the binary protocol +#define MBG_DEFAULT_BAUDRATE 19200L +#define MBG_DEFAULT_FRAMING "8N1" @@ -1773,17 +2011,18 @@ enum ) -/* - * The structure below is more flexible if different receiver - * models have different numbers of serial ports, so the old - * structure PORT_PARM will become obsolete. +/** + * @brief Configuration settings of a serial port + * + * @note This should be used preferably instead of + * ::PORT_PARM, which is deprecated. */ typedef struct { - COM_PARM parm; /* speed, framing, etc. */ - uint8_t mode; /* per second, per minute, etc. */ - uint8_t str_type; /* type of the output string */ - uint32_t flags; /* reserved for future use, currently 0 */ + COM_PARM parm; ///< transmission speed, framing, etc. + uint8_t mode; ///< string mode, see ::STR_MODES + uint8_t str_type; ///< index of the supported time string formats, see ::STR_TYPE_INFO_IDX + uint32_t flags; ///< @see COM_CFG_STATUS_BITS } PORT_SETTINGS; #define _mbg_swab_port_settings( _p ) \ @@ -1793,29 +2032,31 @@ typedef struct } -/* - * The definitions below can be used to mark specific fields of a - * PORT_SETTINGS structure, e.g. when editing build a mask indicating - * which of the fields have changed or which are not valid. - */ -enum -{ - MBG_PS_BIT_BAUD_RATE_OVR_SW, /* Baud rate index exceeds num supp by driver SW */ - MBG_PS_BIT_BAUD_RATE_OVR_DEV, /* Baud rate index exceeds num supp by device */ - MBG_PS_BIT_BAUD_RATE, /* Baud rate not supp by given port */ - MBG_PS_BIT_FRAMING_OVR_SW, /* Framing index exceeds num supp by driver SW */ - MBG_PS_BIT_FRAMING_OVR_DEV, /* Framing index exceeds num supp by device */ - MBG_PS_BIT_FRAMING, /* Framing not supp by given port */ - MBG_PS_BIT_HS_OVR_SW, /* Handshake index exceeds num supp by driver SW */ - MBG_PS_BIT_HS, /* Handshake mode not supp by given port */ - MBG_PS_BIT_STR_TYPE_OVR_SW, /* String type index exceeds num supp by driver SW */ - MBG_PS_BIT_STR_TYPE_OVR_DEV, /* String type index exceeds num supp by device */ - MBG_PS_BIT_STR_TYPE, /* String type not supp by given port */ - MBG_PS_BIT_STR_MODE_OVR_SW, /* String mode index exceeds num supp by driver SW */ - MBG_PS_BIT_STR_MODE_OVR_DEV, /* String mode index exceeds num supp by device */ - MBG_PS_BIT_STR_MODE, /* String mode not supp by given port and string type */ - MBG_PS_BIT_FLAGS_OVR_SW, /* Flags not supp by driver SW */ - MBG_PS_BIT_FLAGS, /* Flags not supp by device */ +/** + * @brief Flag bits used to marks individual ::PORT_SETTINGS fields + * + * These definitions can be used to mark specific fields of a + * PORT_SETTINGS structure, e.g. which fields have changed when + * editing, or which fields have settings which are not valid. + */ +enum MBG_COM_CFG_STATUS_BITS +{ + MBG_PS_BIT_BAUD_RATE_OVR_SW, ///< Baud rate index exceeds num supp by driver SW + MBG_PS_BIT_BAUD_RATE_OVR_DEV, ///< Baud rate index exceeds num supp by device + MBG_PS_BIT_BAUD_RATE, ///< Baud rate not supp by given port + MBG_PS_BIT_FRAMING_OVR_SW, ///< Framing index exceeds num supp by driver SW + MBG_PS_BIT_FRAMING_OVR_DEV, ///< Framing index exceeds num supp by device + MBG_PS_BIT_FRAMING, ///< Framing not supp by given port + MBG_PS_BIT_HS_OVR_SW, ///< Handshake index exceeds num supp by driver SW + MBG_PS_BIT_HS, ///< Handshake mode not supp by given port + MBG_PS_BIT_STR_TYPE_OVR_SW, ///< String type index exceeds num supp by driver SW + MBG_PS_BIT_STR_TYPE_OVR_DEV, ///< String type index exceeds num supp by device + MBG_PS_BIT_STR_TYPE, ///< String type not supp by given port + MBG_PS_BIT_STR_MODE_OVR_SW, ///< String mode index exceeds num supp by driver SW + MBG_PS_BIT_STR_MODE_OVR_DEV, ///< String mode index exceeds num supp by device + MBG_PS_BIT_STR_MODE, ///< String mode not supp by given port and string type + MBG_PS_BIT_FLAGS_OVR_SW, ///< Flags not supp by driver SW + MBG_PS_BIT_FLAGS, ///< Flags not supp by device N_MBG_PS_BIT }; @@ -1838,13 +2079,21 @@ enum -/* - * The structure below adds an index number to the structure - * above to allow addressing of several instances: +/** + * @brief Configuration settings of a specific serial port + * + * This structure should be sent to a device to configure + * a specific serial port. The number of supported ports + * is RECEIVER_INFO::n_com_port. + * + * @note The ::PORT_INFO_IDX structure should be read from + * a device to retrieve the current settings and capabilities. + * + * @see STR_TYPE_INFO */ typedef struct { - uint16_t idx; /* 0..RECEIVER_INFO.n_com_port-1 */ + uint16_t idx; ///< port index, 0..RECEIVER_INFO::n_com_port - 1 PORT_SETTINGS port_settings; } PORT_SETTINGS_IDX; @@ -1855,21 +2104,23 @@ typedef struct } -/* - * The structure below holds the current settings - * for a port, plus additional informaton on the - * port's capabilities. This can be read by setup - * programs to allow setup of supported features - * only. +/** + * @brief Current settings and general capabilities of a serial port + * + * @note This structure should be read from a device to retrieve + * the current settings of a serial port plus its capabilities, + * e.g. supported baud rates, supported string formats, etc. + * + * @see STR_TYPE_INFO */ typedef struct { - PORT_SETTINGS port_settings; /* COM port settings as defined above */ - uint32_t supp_baud_rates; /* bit mask of baud rates supp. by this port */ - uint32_t supp_framings; /* bit mask of framings supp. by this port */ - uint32_t supp_str_types; /* bit mask, bit 0 set if str_type[0] supp. */ - uint32_t reserved; /* reserved for future use, currently 0 */ - uint32_t flags; /* reserved for future use, currently 0 */ + PORT_SETTINGS port_settings; ///< current configuration of the port + uint32_t supp_baud_rates; ///< bit mask of baud rates supp. by this port, see ::MBG_BAUD_RATE_CODES + uint32_t supp_framings; ///< bit mask of framings supp. by this port, see ::MBG_FRAMING_CODES + 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 } PORT_INFO; #define _mbg_swab_port_info( _p ) \ @@ -1886,23 +2137,30 @@ typedef struct /** * @brief Flags used with PORT_SETTINGS::flags and PORT_INFO::flags */ -enum +enum COM_CFG_STATUS_BITS { - PORT_FLAG_BIT_PORT_INVISIBLE, /**< this port is used internally and should not be displayed by config apps */ - N_PORT_FLAGS /**< the number of defined bits */ + PORT_FLAG_BIT_PORT_INVISIBLE, ///< port is used internally and should not be displayed by config apps + N_PORT_FLAGS ///< the number of defined bits }; #define PORT_FLAG_PORT_INVISIBLE ( 1UL << PORT_FLAG_BIT_PORT_INVISIBLE ) -/* - * The structure below adds an index number to the structure - * above to allow addressing of several instances: +/** + * @brief Current settings and general capabilities of a specific serial port + * + * This structure should be read from the device to retrieve the + * current settings of a specific serial port plus its capabilities, + * e.g. supported baud rates, supported string formats, etc. + * The number of supported ports is RECEIVER_INFO::n_com_port. + * + * @note The ::PORT_SETTINGS_IDX structure should be send back to + * the device to configure the specified serial port. */ typedef struct { - uint16_t idx; /* 0..RECEIVER_INFO.n_com_port-1 */ + uint16_t idx; ///< port index, 0..RECEIVER_INFO::n_com_port - 1 PORT_INFO port_info; } PORT_INFO_IDX; @@ -1913,17 +2171,24 @@ typedef struct } -/* - * The structure below keeps information for a given - * string type, e.g. which modes can be used with that - * string type: +/** + * @brief Information on a supported string format + * + * Information includes the name of the string format, which + * transmission modes are supported, etc. + * + * The number of string types, and which string types are supported + * depends on the device type and firmware version. + * + * @note The structure ::STR_TYPE_INFO_IDX should be read repeatedly + * to retrieve all supported string types. */ typedef struct { - uint32_t supp_modes; /* bit mask of modes supp. with this string type */ - char long_name[23]; /* long name of the string format */ - char short_name[11]; /* short name of the string format */ - uint16_t flags; /* reserved, currently always 0 */ + uint32_t supp_modes; ///< bit mask of modes supp. for this string type + 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 ) \ @@ -1934,13 +2199,20 @@ typedef struct -/* - * The structure below adds an index number to the structure - * above to allow addressing of several instances: +/** + * @brief Information on a specific supported string format + * + * This structure should be read from a device to retrieve information + * on a specific supported time string type from an array of supported + * string types. The number of supported string types is returned + * in RECEIVER_INFO::n_str_type. + * + * A selected index number can be saved in PORT_SETTINGS::str_type to + * configure the selected string type for the specific serial port. */ typedef struct { - uint16_t idx; /* 0..RECEIVER_INFO.n_str_type-1 */ + uint16_t idx; ///< string type index, 0..RECEIVER_INFO::n_str_type - 1 STR_TYPE_INFO str_type_info; } STR_TYPE_INFO_IDX; @@ -1951,19 +2223,20 @@ typedef struct } -/* - * The codes below define valid modes for time strings, - * i.e. the condition when a string is being sent - * via the serial port: +/** + * @brief 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. */ -enum +enum STR_MODES { - STR_ON_REQ, /* on request only */ - STR_PER_SEC, /* automatically if second changes */ - STR_PER_MIN, /* automatically if minute changes */ - STR_AUTO, /* automatically if required, e.g. on capture event */ - STR_ON_REQ_SEC, /* if second changes and a request has been received */ - N_STR_MODE /* the number of valid modes */ + STR_ON_REQ, ///< transmission on request by received '?' only + STR_PER_SEC, ///< transmission automatically if second changes + STR_PER_MIN, ///< transmission automatically if minute changes + STR_AUTO, ///< transmission automatically if required, e.g. on capture event + STR_ON_REQ_SEC, ///< transmission if second changes and a request has been received before + N_STR_MODE ///< the number of known modes }; @@ -2031,8 +2304,8 @@ enum /** - * The number of serial ports which were available - * with all GPS receiver models: + * The number of serial ports which are at least available + * even with very old GPS receiver models */ #define DEFAULT_N_COM 2 @@ -2045,8 +2318,10 @@ enum #endif /** - * The structure used to store the modes of both serial ports:<br> - * <b>(now obsolete)</b> + * @brief A The structure used to store the configuration of both serial ports + * + * @deprecated This structure is deprecated, ::PORT_SETTINGS and related structures + * should be used instead, if supported by the device. */ typedef struct { @@ -2123,8 +2398,8 @@ enum - <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 + - \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 @@ -2135,24 +2410,27 @@ enum 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. + 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. + 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 + @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 + 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 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: */ -enum + * the unmodulated and the modulated IRIG signals at the same time. + */ +enum ICODE_TX_CODES { ICODE_TX_B002_B122, ICODE_TX_B003_B123, @@ -2160,15 +2438,18 @@ enum ICODE_TX_A003_A133, ICODE_TX_AFNOR, ICODE_TX_IEEE1344, - ICODE_TX_B2201344, // DCLS only - ICODE_TX_B222, // DCLS only - ICODE_TX_B223, // DCLS only + ICODE_TX_B2201344, ///< DCLS only + ICODE_TX_B222, ///< DCLS only + ICODE_TX_B223, ///< DCLS only ICODE_TX_B006_B126, ICODE_TX_B007_B127, ICODE_TX_G002_G142, ICODE_TX_G006_G146, ICODE_TX_C37118, - N_ICODE_TX /**< number of code types */ + ICODE_TX_TXC101, + ICODE_TX_E002_E112, + ICODE_TX_NASA36, + N_ICODE_TX ///< number of known codes }; @@ -2190,7 +2471,10 @@ enum "B007+B127", \ "G002+G142", \ "G006+G146", \ - "C37.118" \ + "C37.118", \ + "TXC-101 DTR-6", \ + "E002+E112", \ + "NASA 36" \ } /** @@ -2212,7 +2496,10 @@ enum "B007+B127", \ "G002+G142", \ "G006+G146", \ - "C37.118" \ + "C37.118", \ + "TXC-101", \ + "E002+E112", \ + "NASA 36" \ } @@ -2234,7 +2521,10 @@ enum "100 bps, DCLS or 1 kHz carrier, complete date, SBS", \ "10 kbps, DCLS or 100 kHz carrier", \ "10 kbps, DCLS or 100 kHz carrier, complete date", \ - "like IEEE1344, but UTC offset with reversed sign" \ + "like IEEE1344, but UTC offset with reversed sign", \ + "code from TV time sync device TXC-101 DTR-6", \ + "10 bps, DCLS or 100 Hz carrier", \ + "100 bps, DCLS or 1 kHz carrier" \ } /* @@ -2256,6 +2546,9 @@ enum #define MSK_ICODE_TX_G002_G142 ( 1UL << ICODE_TX_G002_G142 ) #define MSK_ICODE_TX_G006_G146 ( 1UL << ICODE_TX_G006_G146 ) #define MSK_ICODE_TX_C37118 ( 1UL << ICODE_TX_C37118 ) +#define MSK_ICODE_TX_TXC101 ( 1UL << ICODE_TX_TXC101 ) +#define MSK_ICODE_TX_E002_E112 ( 1UL << ICODE_TX_E002_E112 ) +#define MSK_ICODE_TX_NASA36 ( 1UL << ICODE_TX_NASA36 ) /** * A mask of IRIG formats with manchester encoded DC output: @@ -2268,6 +2561,14 @@ enum ) /** + * A mask of IRIG formats with 100 Hz carrier: + */ +#define MSK_ICODE_TX_100HZ \ +( \ + MSK_ICODE_TX_E002_E112 \ +) + +/** * A mask of IRIG formats with 1 kHz carrier: */ #define MSK_ICODE_TX_1KHZ \ @@ -2281,7 +2582,8 @@ enum MSK_ICODE_TX_B223 | \ MSK_ICODE_TX_B006_B126 | \ MSK_ICODE_TX_B007_B127 | \ - MSK_ICODE_TX_C37118 \ + MSK_ICODE_TX_C37118 | \ + MSK_ICODE_TX_NASA36 \ ) /** @@ -2303,6 +2605,14 @@ enum ) /** + * A mask of IRIG formats with 10 bps data rate: + */ +#define MSK_ICODE_TX_10BPS \ +( \ + MSK_ICODE_TX_E002_E112 \ +) + +/** * A mask of IRIG formats with 100 bps data rate: */ #define MSK_ICODE_TX_100BPS \ @@ -2370,29 +2680,35 @@ enum /** + * @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. */ -enum -{ - ICODE_RX_B122_B123, // modulated - ICODE_RX_A132_A133, // modulated - ICODE_RX_B002_B003, // DCLS - ICODE_RX_A002_A003, // DCLS - ICODE_RX_AFNOR, // modulated - ICODE_RX_AFNOR_DC, // DCLS - ICODE_RX_IEEE1344, // modulated - ICODE_RX_IEEE1344_DC, // DCLS - ICODE_RX_B126_B127, // modulated - ICODE_RX_B006_B007, // DCLS - ICODE_RX_G142_G146, // modulated - ICODE_RX_G002_G006, // DCLS - ICODE_RX_C37118, // modulated - ICODE_RX_C37118_DC, // DCLS - ICODE_RX_TXC_101, // modulated - ICODE_RX_TXC_101_DC, // DCLS - N_ICODE_RX /* the number of valid signal code types */ +enum ICODE_RX_CODES +{ + ICODE_RX_B122_B123, ///< modulated + ICODE_RX_A132_A133, ///< modulated + ICODE_RX_B002_B003, ///< DCLS + ICODE_RX_A002_A003, ///< DCLS + ICODE_RX_AFNOR, ///< modulated + ICODE_RX_AFNOR_DC, ///< DCLS + ICODE_RX_IEEE1344, ///< modulated + ICODE_RX_IEEE1344_DC, ///< DCLS + ICODE_RX_B126_B127, ///< modulated + ICODE_RX_B006_B007, ///< DCLS + ICODE_RX_G142_G146, ///< modulated + ICODE_RX_G002_G006, ///< DCLS + ICODE_RX_C37118, ///< modulated + ICODE_RX_C37118_DC, ///< DCLS + ICODE_RX_TXC101, ///< modulated + ICODE_RX_TXC101_DC, ///< DCLS + ICODE_RX_E112, ///< modulated + ICODE_RX_E002, ///< DCLS + ICODE_RX_NASA36, ///< modulated + ICODE_RX_NASA36_DC, ///< DCLS + N_ICODE_RX ///< the number of known codes }; /** @@ -2415,7 +2731,11 @@ enum "C37.118", \ "C37.118 (DCLS)", \ "TXC-101 DTR-6", \ - "TXC-101 DTR-6 (DCLS)" \ + "TXC-101 DTR-6 (DCLS)", \ + "E112", \ + "E002 (DCLS)", \ + "NASA-36", \ + "NASA-36 (DCLS)" \ } /** @@ -2439,7 +2759,11 @@ enum "C37.118", \ "C37.118 DC", \ "TXC-101", \ - "TXC-101 DC" \ + "TXC-101 DC", \ + "E112", \ + "E002 DC", \ + "NASA-36", \ + "NASA-36 DC" \ } @@ -2463,7 +2787,11 @@ enum "like IEEE1344, but UTC offset with reversed sign", \ "like IEEE1344 DC, but UTC offset with reversed sign", \ "code from TV time sync device TXC-101 DTR-6", \ - "DC code from TV time sync device TXC-101 DTR-6" \ + "DC code from TV time sync device TXC-101 DTR-6", \ + "10 bps, 100 Hz carrier", \ + "10 bps, DCLS", \ + "100 bps, 1 kHz carrier", \ + "100 bps, DCLS" \ } /* @@ -2483,8 +2811,12 @@ enum #define MSK_ICODE_RX_G002_G006 ( 1UL << ICODE_RX_G002_G006 ) #define MSK_ICODE_RX_C37118 ( 1UL << ICODE_RX_C37118 ) #define MSK_ICODE_RX_C37118_DC ( 1UL << ICODE_RX_C37118_DC ) -#define MSK_ICODE_RX_TXC_101 ( 1UL << ICODE_RX_TXC_101 ) -#define MSK_ICODE_RX_TXC_101_DC ( 1UL << ICODE_RX_TXC_101_DC ) +#define MSK_ICODE_RX_TXC101 ( 1UL << ICODE_RX_TXC101 ) +#define MSK_ICODE_RX_TXC101_DC ( 1UL << ICODE_RX_TXC101_DC ) +#define MSK_ICODE_RX_E112 ( 1UL << ICODE_RX_E112 ) +#define MSK_ICODE_RX_E002 ( 1UL << ICODE_RX_E002 ) +#define MSK_ICODE_RX_NASA36 ( 1UL << ICODE_RX_NASA36 ) +#define MSK_ICODE_RX_NASA36_DC ( 1UL << ICODE_RX_NASA36_DC ) /** * A mask of IRIG DCLS formats: @@ -2497,7 +2829,19 @@ enum MSK_ICODE_RX_IEEE1344_DC | \ MSK_ICODE_RX_B006_B007 | \ MSK_ICODE_RX_G002_G006 | \ - MSK_ICODE_RX_C37118_DC \ + MSK_ICODE_RX_C37118_DC | \ + MSK_ICODE_RX_TXC101_DC | \ + MSK_ICODE_RX_E002 | \ + MSK_ICODE_RX_NASA36_DC \ +) + +/** + * A mask of IRIG formats with 100 Hz carrier: + */ +#define MSK_ICODE_RX_100HZ \ +( \ + MSK_ICODE_RX_E112 | \ + MSK_ICODE_RX_E002 \ ) /** @@ -2509,7 +2853,9 @@ enum MSK_ICODE_RX_AFNOR | \ MSK_ICODE_RX_IEEE1344 | \ MSK_ICODE_RX_B126_B127 | \ - MSK_ICODE_RX_C37118 \ + MSK_ICODE_RX_C37118 | \ + MSK_ICODE_RX_TXC101 | \ + MSK_ICODE_RX_NASA36 \ ) /** @@ -2529,6 +2875,15 @@ enum ) /** + * A mask of IRIG formats with 10 bps data rate: + */ +#define MSK_ICODE_RX_10BPS \ +( \ + MSK_ICODE_RX_E002_E112 | \ + MSK_ICODE_RX_E002_E002 \ +) + +/** * A mask of IRIG formats with 100 bps data rate: */ #define MSK_ICODE_RX_100BPS \ @@ -2542,7 +2897,11 @@ enum MSK_ICODE_RX_B126_B127 | \ MSK_ICODE_RX_B006_B007 | \ MSK_ICODE_RX_C37118 | \ - MSK_ICODE_RX_C37118_DC \ + MSK_ICODE_RX_C37118_DC | \ + MSK_ICODE_RX_TXC101 | \ + MSK_ICODE_RX_TXC101_DC | \ + MSK_ICODE_RX_NASA36 | \ + MSK_ICODE_RX_NASA36_DC \ ) /** @@ -2559,7 +2918,8 @@ enum */ #define MSK_ICODE_RX_10000BPS \ ( \ - MSK_ICODE_RX_G142_G146 \ + MSK_ICODE_RX_G142_G146 | \ + MSK_ICODE_RX_G002_G006 \ ) /** @@ -2605,13 +2965,14 @@ enum /** - * The structure below is used to configure an optional - * on-board IRIG output: + * @brief Configuration settings of an IRIG input or output + * + * @see group_icode */ typedef struct { - uint16_t icode; /**< IRIG signal code, see \ref group_icode */ - uint16_t flags; /**< see \ref group_irig_flags */ + uint16_t icode; ///< IRIG signal code, see ::ICODE_RX_CODES + uint16_t flags; ///< see ::IFLAGS_BITS } IRIG_SETTINGS; #define _mbg_swab_irig_settings( _p ) \ @@ -2621,35 +2982,40 @@ typedef struct } + /** - * @defgroup group_irig_flags Bit Masks used with IRIG_SETTINGS::flags + * @brief Bits used with IRIG_SETTINGS::flags * - * (others are reserved) - * @{ + * @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. */ -#define IFLAGS_DISABLE_TFOM 0x0001 /**< RX ignore/TX don't gen TFOM */ -#define IFLAGS_TX_GEN_LOCAL_TIME 0x0002 /**< gen local time, not UTC */ +enum IFLAGS_BITS +{ + IFLAGS_BIT_DISABLE_TFOM, ///< for RX ignore, for TX don't generate TFOM flag + IFLAGS_BIT_TX_GEN_LOCAL_TIME, ///< TX output local time, not %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 0x0003 /**< flags above or'ed */ +#define IFLAGS_MASK ( ( 1UL << N_IFLAGS_BITS ) - 1 ) ///< mask of all known 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. -/** @} group_irig_flags */ /** * @brief Current IRIG settings and supported codes * - * Used to query the IRIG current IRIG settings + * Used to query the current IRIG settings * plus a mask of supported codes. */ typedef struct { - IRIG_SETTINGS settings; - uint32_t supp_codes; /**< bit mask of supported codes */ + IRIG_SETTINGS settings; ///< current settings + uint32_t supp_codes; ///< bit mask of supported codes } IRIG_INFO; #define _mbg_swab_irig_info( _p ) \ @@ -2671,14 +3037,23 @@ typedef struct /** * The number of coefficients of a compensation record * for a single frame type group, and the structure - * which contains those coefficients + * which contains those coefficients. */ #define N_IRIG_RX_COMP_VAL 4 -/** @brief A structure which stores compensation values. */ +/** + * @brief A structure used to store compensation values + */ typedef struct { - int16_t c[N_IRIG_RX_COMP_VAL]; /**< compensation values [100 ns units] */ + /** + * @brief Delay compensation values [100 ns units] + * + * @note Only the first value is actually used to compensate + * a delay, so the remaining values should be 0. + */ + int16_t c[N_IRIG_RX_COMP_VAL]; + } IRIG_RX_COMP; #define _mbg_swab_irig_rx_comp( _p ) \ @@ -2689,25 +3064,18 @@ typedef struct } -/** @brief Structure used to retrieve the number of calibration records. */ -typedef struct -{ - uint16_t num; /**< number of records supported by the device, */ - uint16_t rec_size; /**< size of one record, in bytes */ -} CAL_REC_INFO; +/** 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 -#define _mbg_swab_cal_rec_info( _p ) \ -{ \ - _mbg_swab16( &(_p)->num ); \ - _mbg_swab16( &(_p)->rec_size ); \ -} -/** @brief Structure used to retrieve the number of records for a given type */ +/** + * @brief Structure used to retrieve the number of records for a given type + */ typedef struct { - uint16_t type; /**< record type */ - uint16_t idx; /**< index if several records of same type are supported */ + uint16_t type; ///< record type @see CAL_REC_TYPES + uint16_t idx; ///< index if several records of same type are supported, see ::IRIG_RX_COMP_GROUPS } CAL_REC_HDR; #define _mbg_swab_cal_rec_hdr( _p ) \ @@ -2717,12 +3085,14 @@ typedef struct } -/** @brief Types to be used with CAL_REC_HDR::type */ -enum +/** + * @brief Types to be used with CAL_REC_HDR::type + */ +enum CAL_REC_TYPES { - CAL_REC_TYPE_UNDEF, /**< undefined */ - CAL_REC_TYPE_IRIG_RX_COMP, /**< IRIG receiver delay compensation */ - N_CAL_REC_TYPE /**< number of known types */ + CAL_REC_TYPE_UNDEF, ///< undefined type + CAL_REC_TYPE_IRIG_RX_COMP, ///< IRIG receiver delay compensation + N_CAL_REC_TYPE ///< number of known types }; @@ -2731,32 +3101,40 @@ enum * * IRIG frame type groups to be distinguished for delay compensation. */ -enum +enum IRIG_RX_COMP_GROUPS { - IRIG_RX_COMP_B1, /**< codes B1xx, AFNOR, IEEE1344 */ - IRIG_RX_COMP_A1, /**< code A1xx */ - IRIG_RX_COMP_B0, /**< codes B0xx, AFNOR DC, IEEE1344 DC */ - IRIG_RX_COMP_A0, /**< code A0xx */ - N_IRIG_RX_COMP /**< number of compensation values */ + IRIG_RX_COMP_B1, ///< codes B1xx, AFNOR, IEEE1344 + IRIG_RX_COMP_A1, ///< code A1xx + IRIG_RX_COMP_B0, ///< codes B0xx, AFNOR DC, IEEE1344 DC + IRIG_RX_COMP_A0, ///< code A0xx + IRIG_RX_COMP_G1, ///< code G14x + IRIG_RX_COMP_G0, ///< code G00x + N_IRIG_RX_COMP ///< number of compensation values }; -/** @brief Initializers for format name strings. */ +/** + * @brief Initializers for format name strings + */ #define DEFAULT_IRIG_RX_COMP_NAMES \ { \ "B1xx/AFNOR/IEEE1344", \ "A1xx", \ "B0xx/AFNOR DC/IEEE1344 DC", \ "A0xx", \ + "G14X", \ + "G00X", \ } -/** @brief Structure used to transfer calibration records. */ +/** + * @brief Structure used to transfer calibration records + */ typedef struct { CAL_REC_HDR hdr; - IRIG_RX_COMP comp_data; /**< IRIG receiver delay compensation */ + IRIG_RX_COMP comp_data; ///< IRIG receiver delay compensation } CAL_REC_IRIG_RX_COMP; @@ -2770,17 +3148,22 @@ typedef struct -// The type below is used to read the board's debug status -// which also include IRIG decoder status: -typedef uint32_t MBG_DEBUG_STATUS; +/** + * @brief A data type used to read the board's debug status + * + * @note This also include IRIG decoder status. + */ +typedef uint32_t MBG_DEBUG_STATUS; ///< @see MBG_DEBUG_STATUS_BITS #define _mbg_swab_debug_status( _p ) \ _mbg_swab32( _p ) -// The debug status is bit coded as defined below: -enum +/** + * @brief Enumeration of bits used with ::MBG_DEBUG_STATUS + */ +enum MBG_DEBUG_STATUS_BITS { MBG_IRIG_BIT_WARMED_UP, /**< Osc has warmed up */ MBG_IRIG_BIT_PPS_ACTIVE, /**< PPS output is active */ @@ -2789,7 +3172,7 @@ enum MBG_IRIG_BIT_MSG_INCONSISTENT, /**< IRIG msg contains inconsistent data */ MBG_IRIG_BIT_LOOP_LOCKED, /**< Decoder control loop is locked */ MBG_IRIG_BIT_JITTER_TOO_LARGE, /**< Phase jitter too large */ - MBG_IRIG_BIT_INV_REF_OFFS, /**< UTC ref offset not configured */ + MBG_IRIG_BIT_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 */ @@ -2799,8 +3182,8 @@ enum N_MBG_DEBUG_BIT }; -/* - * Initializers for IRIG status bit strings. +/** + * @brief Initializers for debug status bit strings */ #define MBG_DEBUG_STATUS_STRS \ { \ @@ -2837,24 +3220,44 @@ enum -typedef int16_t MBG_REF_OFFS; /**< -MBG_REF_OFFS_MAX..MBG_REF_OFFS_MAX */ +/** + * @brief A data type used to configure the ref offset + * + * The ref offset if the offset of the incoming reference time from %UTC. + * For some types of signal (e.g. most IRIG frame formats) this can't be + * determined automatically. + * + * @note There's a special flag ::MBG_REF_OFFS_NOT_CFGD indicating that + * this parameter is unconfigured + */ +typedef int16_t MBG_REF_OFFS; ///< -::MBG_REF_OFFS_MAX..::MBG_REF_OFFS_MAX, or ::MBG_REF_OFFS_NOT_CFGD #define _mbg_swab_mbg_ref_offs( _p ) _mbg_swab16( (_p) ) -/** the maximum allowed positive / negative offset */ +/** + * @brief The maximum allowed positive / negative ref offset + */ #define MBG_REF_OFFS_MAX ( ( 12L * 60 ) + 30 ) // [minutes] /** - * the following value is used to indicate that the ref offset - * value has not yet been configured + * @brief A flag indicating that the ref offset has not yet been configured + * + * If this flag is set in ::MBG_REF_OFFS this means the ref offset + * (time offset from %UTC) has not yet been configured. This is usually + * the case for IRIG receiver devices right after they have been shipped. */ #define MBG_REF_OFFS_NOT_CFGD 0x8000 +/** + * @brief A structure used to configure optional settings + * + * Optional settings are a generic way to configure some extended settings. + */ typedef struct { - uint32_t flags; + uint32_t flags; ///< @see MBG_OPT_BITS } MBG_OPT_SETTINGS; #define _mbg_swab_mbg_opt_settings( _p ) \ @@ -2863,10 +3266,16 @@ typedef struct } +/** + * @brief A structure used to configure optional settings + * + * This structure includes the current settings, and a bit mask + * indicating which flags are supported. + */ typedef struct { MBG_OPT_SETTINGS settings; - uint32_t supp_flags; + uint32_t supp_flags; ///< bit mask of supported flags, see ::MBG_OPT_BITS } MBG_OPT_INFO; #define _mbg_swab_mbg_opt_info( _p ) \ @@ -2876,11 +3285,11 @@ typedef struct } -enum +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 string contains %UTC time */ + MBG_OPT_BIT_EMU_SYNC, /**< emulate/pretend to be synchronized, alternatively + ::GPS_FEAT_IGNORE_LOCK may be supported */ N_MBG_OPT_BIT }; @@ -2892,8 +3301,13 @@ enum -// bit coded return type for PCPS_GET_IRIG_CTRL_BITS -typedef uint32_t MBG_IRIG_CTRL_BITS; +/** + * @brief Bit coded return type for ::PCPS_GET_IRIG_CTRL_BITS + * + * This type returns the control bits an IRIG receiver has decoded + * from an incoming time code signal. + */ +typedef uint32_t MBG_IRIG_CTRL_BITS; #define _mbg_swab_irig_ctrl_bits( _p ) _mbg_swab32( _p ) @@ -2910,14 +3324,15 @@ typedef uint32_t MBG_IRIG_CTRL_BITS; #define RAW_IRIG_SIZE 16 /** - The buffer below can be used to get the raw data bits - from the IRIG decoder. A maximum number of RAW_IRIG_SIZE - bytes can be filled. If less bytes are used then the rest - of the bytes are filled with zeros. - - The first IRIG bit received from the transmitter is saved - in the MSB (bit 7) of data_bytes[0], etc. -*/ + * @brief A buffer used to read raw IRIG data bits from an IRIG receiver + * + * Used to get the raw data bits from the IRIG decoder. A maximum number + * of ::RAW_IRIG_SIZE bytes can be filled up, depending on the IRIG code. + * If less bytes are used then the rest of the bytes are filled with zeros. + * + * @note The first IRIG bit received from the transmitter is saved + * in the MSB (bit 7) of data_bytes[0], etc. + */ typedef struct { uint8_t data_bytes[RAW_IRIG_SIZE]; @@ -2939,7 +3354,7 @@ 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 + 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 @@ -2947,11 +3362,17 @@ typedef struct @{ */ -enum +/** + * @brief Known time scales + * + * @note See also the extended status bits ::TM_SCALE_GPS + * and ::TM_SCALE_TAI indicating the active time scale setting + */ +enum MBG_TIME_SCALES { - MBG_TIME_SCALE_DEFAULT, /**< UTC or local time, t_gps - deltat_ls */ - MBG_TIME_SCALE_GPS, /**< GPS time, monotonical */ - MBG_TIME_SCALE_TAI, /**< TAI, t_gps + GPS_TAI_OFFSET seconds */ + MBG_TIME_SCALE_DEFAULT, ///< %UTC or local time according to ::UTC parameters and ::TZDL configuration + MBG_TIME_SCALE_GPS, ///< GPS time as sent by the satellites, monotonical + MBG_TIME_SCALE_TAI, ///< TAI, i.e. GPS time plus constant offset (::GPS_TAI_OFFSET) N_MBG_TIME_SCALE }; @@ -2959,9 +3380,6 @@ enum #define MBG_TIME_SCALE_MSK_GPS ( 1UL << MBG_TIME_SCALE_GPS ) #define MBG_TIME_SCALE_MSK_TAI ( 1UL << MBG_TIME_SCALE_TAI ) -// See also the extended status bits TM_SCALE_GPS and TM_SCALE_TAI -// indicating the active time scale setting. - #define MBG_TIME_SCALE_STRS \ { \ @@ -2973,26 +3391,32 @@ enum /** - The fixed time offset between the GPS and TAI time scales, in seconds -*/ -#define GPS_TAI_OFFSET 19 /**< [s], TAI = GPS + GPS_TAI_OFFSET */ + * @brief The constant time offset between the GPS and TAI time scales, in seconds + */ +#define GPS_TAI_OFFSET 19 ///< [s], TAI = GPS + GPS_TAI_OFFSET +/** + * @brief Time scale configuration settings + */ typedef struct { - uint8_t scale; /**< current time scale code from the enum above */ - uint8_t flags; /**< reserved, currently always 0 */ + uint8_t scale; ///< current time scale code from enum MBG_TIME_SCALES + uint8_t flags; ///< reserved, currently always 0 } MBG_TIME_SCALE_SETTINGS; #define _mbg_swab_mbg_time_scale_settings( _p ) \ _nop_macro_fnc() +/** + * @brief Time scale configuration settings plus capabilities + */ typedef struct { - MBG_TIME_SCALE_SETTINGS settings; /**< current settings */ - MBG_TIME_SCALE_SETTINGS max_settings; /**< numb. of scales, all supported flags */ - uint32_t supp_scales; /**< bit masks of supported scales */ + MBG_TIME_SCALE_SETTINGS settings; ///< current settings + MBG_TIME_SCALE_SETTINGS max_settings; ///< numb. of scales, all supported flags + uint32_t supp_scales; ///< bit masks of supported scales } MBG_TIME_SCALE_INFO; #define _mbg_swab_mbg_time_scale_info( _p ) \ @@ -3009,17 +3433,17 @@ typedef struct * The structures below are required to setup the programmable * pulse outputs which are provided by some GPS receivers. * The number of programmable pulse outputs supported by a GPS - * receiver is reported in the RECEIVER_INFO.n_str_type field. + * receiver is reported in the RECEIVER_INFO::n_str_type field. */ /** - * The structure is used to define a date of year: + * @brief A calendar date including full year number */ typedef struct { - uint8_t mday; /* 1..28,29,30,31 */ - uint8_t month; /* 1..12 */ - uint16_t year; /* including century */ + uint8_t mday; ///< 1..28,29,30,31 + uint8_t month; ///< 1..12 + uint16_t year; ///< including century } MBG_DATE; #define _mbg_swab_mbg_date( _p ) \ @@ -3029,14 +3453,14 @@ typedef struct /** - * The structure is used to define a time of day: + * @brief The time of day including hundredths of seconds */ typedef struct { - uint8_t hour; /**< 0..23 */ - uint8_t min; /**< 0..59 */ - uint8_t sec; /**< 0..59,60 */ - uint8_t sec100; /**< reserved, currently always 0 */ + uint8_t hour; ///< 0..23 + uint8_t min; ///< 0..59 + uint8_t sec; ///< 0..59,60 + uint8_t sec100; ///< reserved, currently always 0 } MBG_TIME; #define _mbg_swab_mbg_time( _p ) \ @@ -3044,15 +3468,14 @@ typedef struct /** - * The structure defines a single date and time - * for switching operations: + * @brief Date and time specification for switching operations */ typedef struct { - MBG_DATE d; /* date to switch */ - MBG_TIME t; /* time to switch */ - uint8_t wday; /* reserved, currently always 0 */ - uint8_t flags; /* reserved, currently 0 */ + MBG_DATE d; ///< date to switch + MBG_TIME t; ///< time to switch + uint8_t wday; ///< reserved, currently always 0 + uint8_t flags; ///< reserved, currently 0 } MBG_DATE_TIME; #define _mbg_swab_mbg_date_time( _p ) \ @@ -3063,13 +3486,12 @@ typedef struct /** - * The structure defines times and dates - * for an on/off cycle: + * @brief A structure to define on/off cycle times */ typedef struct { - MBG_DATE_TIME on; /* time and date to switch on */ - MBG_DATE_TIME off; /* time and date to switch off */ + MBG_DATE_TIME on; ///< date and time to switch on + MBG_DATE_TIME off; ///< date and time to switch off } POUT_TIME; #define _mbg_swab_pout_time( _p ) \ @@ -3080,64 +3502,128 @@ typedef struct /** - * The number of POUT_TIMEs for each programmable pulse output + * @brief The number of ::POUT_TIME settings for each programmable pulse output + * + * @note This can't be changed without breaking compatibility of the API */ -#define N_POUT_TIMES 3 +#define N_POUT_TIMES 3 /** - * The structure is used to configure a single programmable - * pulse output. + * @brief Configuration settings for a single programmable pulse output */ typedef struct { - uint16_t mode; /**< mode of operation, codes defined below */ - uint16_t pulse_len; /**< 10 msec units, or COM port number */ - uint16_t timeout; /**< [min], for dcf_mode */ - uint16_t flags; /**< see below */ - POUT_TIME tm[N_POUT_TIMES]; /**< switching times */ + 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 } POUT_SETTINGS; -#define _mbg_swab_pout_settings( _p ) \ -{ \ - int i; \ - _mbg_swab16( &(_p)->mode ); \ - _mbg_swab16( &(_p)->pulse_len ); \ - _mbg_swab16( &(_p)->timeout ); \ - _mbg_swab16( &(_p)->flags ); \ - \ - for ( i = 0; i < N_POUT_TIMES; i++ ) \ - _mbg_swab_pout_time( &(_p)->tm[i] ); \ +/** + * @brief A Generic data field for programmable output settings + * + * If the mode is set to ::POUT_TIME_SLOTS then POUT_SETTINGS::tm must be + * interpreted as ::POUT_DATA, i.e. just an array of bytes. We can not change + * the type of the tm field to a union for compatibility reasons ... :( + */ +typedef union +{ + uint8_t b[N_POUT_TIMES * sizeof( POUT_TIME )]; +} POUT_DATA; + +// 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 ); \ } -#define MAX_POUT_PULSE_LEN 1000 /**< 10 secs, in 10 msec units */ -#define MAX_POUT_DCF_TIMOUT ( 48 * 60 ) /**< 48 hours, in minutes */ + +// In POUT_TIME_SLOTS mode the number of time slots per minute is stored +// in the pulse_len field. Valid numbers all numbers n in the range 1..60 +// for which the remainder of 60 / n is 0. +#define MIN_TIME_SLOTS_PER_MINUTE 1 +#define MAX_TIME_SLOTS_PER_MINUTE 60 +#define TIME_SLOT_REGISTER_IN_SEC 60 + +#define TIMEOUT_DIVIDED_BY 10 +#define TIME_SLOT_SWITCH_OFF_BUFFER_MIN 50 / TIMEOUT_DIVIDED_BY +#define TIME_SLOT_SWITCH_OFF_BUFFER_MAX 500 / TIMEOUT_DIVIDED_BY +#define TIME_SLOT_SWITCH_OFF_BUFFER_STD 500 / TIMEOUT_DIVIDED_BY +#define TIME_SLOT_SWITCH_OFF_BUFFER_STEP_SIZE 50 / TIMEOUT_DIVIDED_BY + +#define _valid_time_slots_per_minute( _n ) \ + ( ( (_n) >= MIN_TIME_SLOTS_PER_MINUTE ) && \ + ( (_n) <= MAX_TIME_SLOTS_PER_MINUTE ) && \ + ( ( 60 % (_n) ) == 0 ) \ + ) + + +#define MAX_POUT_PULSE_LEN 1000 ///< 10 secs, in 10 msec units +#define MAX_POUT_DCF_TIMOUT ( 48 * 60 ) ///< 48 hours, in minutes /** - * These codes are defined for POUT_SETTINGS.mode to setup - * the basic mode of operation for a single programmable pulse - * output: - */ -enum -{ - POUT_IDLE, /**< always off, or on if POUT_INVERTED */ - POUT_TIMER, /**< switch on/off at configured times */ - POUT_SINGLE_SHOT, /**< pulse at time POUT_SETTINGS.tm[0].on */ - POUT_CYCLIC_PULSE, /**< pulse every POUT_SETTINGS.tm[0].on.t interval */ - POUT_PER_SEC, /**< pulse if second changes */ - POUT_PER_MIN, /**< pulse if minute changes */ - POUT_PER_HOUR, /**< pulse if hour changes */ - POUT_DCF77, /**< emulate DCF77 signal */ - POUT_POS_OK, /**< on if pos. OK (nav_solved) */ - POUT_TIME_SYNC, /**< on if time sync (time_syn) */ - POUT_ALL_SYNC, /**< on if pos. OK and time sync */ - POUT_TIMECODE, /**< IRIG/AFNOR DCLS output */ - POUT_TIMESTR, /**< COM port number in pulse_len field */ - POUT_10MHZ, /**< 10 MHz fixed frequency */ - POUT_DCF77_M59, /**< DCF77-like signal with 500 ms pulse in 59th second */ - POUT_SYNTH, /**< programmable synthesizer frequency */ - N_POUT_MODES + * @brief Operation modes for a programmable pulse output + * + * These codes are used with POUT_SETTINGS::mode. + * + * @note Not every programmable pulse output supports all modes. + */ +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 + N_POUT_MODES ///< the number of known modes }; @@ -3161,6 +3647,7 @@ enum #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 DEFAULT_ENG_POUT_NAMES \ { \ @@ -3179,7 +3666,8 @@ enum ENG_POUT_NAME_TIMESTR, \ ENG_POUT_NAME_10MHZ, \ ENG_POUT_NAME_DCF77_M59, \ - ENG_POUT_NAME_SYNTH \ + ENG_POUT_NAME_SYNTH, \ + ENG_POUT_NAME_TIME_SLOTS \ } @@ -3199,6 +3687,7 @@ enum #define ENG_POUT_HINT_10MHZ "10 MHz fixed output frequency" #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 DEFAULT_ENG_POUT_HINTS \ { \ @@ -3217,7 +3706,8 @@ enum ENG_POUT_HINT_TIMESTR, \ ENG_POUT_HINT_10MHZ, \ ENG_POUT_HINT_DCF77_M59, \ - ENG_POUT_HINT_SYNTH \ + ENG_POUT_HINT_SYNTH, \ + ENG_POUT_HINT_TIME_SLOTS \ } @@ -3242,87 +3732,128 @@ enum #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 ) -/* - * The codes below are used with POUT_SETTINGS::flags: +/** + * @brief Bits used with POUT_SETTINGS::flags */ -#define POUT_INVERTED 0x0001 // invert output level -#define POUT_IF_SYNC_ONLY 0x0002 // disable in holdover mode -#define POUT_TIMEBASE_UTC 0x0004 // use UTC, only applicable for DCF77 output +enum POUT_SETTINGS_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 + 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 ) /** - Since a clock may support more than one programmable - pulse output, setup tools must use the structure below - to read/set pulse output configuration. - The number of outputs supported by a receiver model - can be queried using the RECEIVER_INFO structure. + * @brief Configuration settings for a specific programmable pulse output + * + * This structure can be used to send configuration settings for a specific + * programmable output to a device. + * The number of supported outputs is RECEIVER_INFO::n_prg_out. + * + * @note The ::POUT_INFO_IDX structure should be read from + * a device to retrieve the current settings and capabilities. */ typedef struct { - uint16_t idx; /**< 0..RECEIVER_INFO.n_prg_out-1 */ + uint16_t idx; ///< 0..RECEIVER_INFO::n_prg_out - 1 POUT_SETTINGS pout_settings; } POUT_SETTINGS_IDX; -#define _mbg_swab_pout_settings_idx( _p ) \ -{ \ - _mbg_swab16( &(_p)->idx ); \ - _mbg_swab_pout_settings( &(_p)->pout_settings ); \ +#define _mbg_swab_pout_settings_idx_on_set( _p ) \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_pout_settings_on_set( &(_p)->pout_settings ); \ +} + +#define _mbg_swab_pout_settings_idx_on_get( _p ) \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_pout_settings_on_get( &(_p)->pout_settings ); \ } /** - The structure below holds the current settings - for a programmable pulse output, plus additional - informaton on the output's capabilities. - This can be read by setup programs to allow setup - of supported features only. + * @brief Current settings and general capabilities of a programmable pulse output + * + * This structure should be read from the device to retrieve the + * current settings of a programmable pulse output plus its capabilities, + * e.g. the supported output modes, etc. + * + * @note The ::POUT_INFO_IDX structure should be used to read + * current settings and capabilities of a specific output. */ typedef struct { POUT_SETTINGS pout_settings; - uint32_t supp_modes; /**< bit mask of modes supp. by this output */ - uint8_t timestr_ports; /**< bit mask of COM ports supported for POUT_TIMESTR */ - uint8_t reserved_0; /**< reserved for future use, currently 0 */ - uint16_t reserved_1; /**< reserved for future use, currently 0 */ - uint32_t flags; /**< see below */ + uint32_t supp_modes; ///< bit mask of modes supp. by this output, see ::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 } POUT_INFO; -#define _mbg_swab_pout_info( _p ) \ -{ \ - _mbg_swab_pout_settings( &(_p)->pout_settings ); \ - _mbg_swab32( &(_p)->supp_modes ); \ - _mbg_swab16( &(_p)->reserved_1 ); \ - _mbg_swab32( &(_p)->flags ); \ +#define _mbg_swab_pout_info_on_get( _p ) \ +{ \ + _mbg_swab_pout_settings_on_get( &(_p)->pout_settings ); \ + _mbg_swab32( &(_p)->supp_modes ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->flags ); \ } -/** The max number of COM ports that can be handled by POUT_INFO::timestr_ports */ +/** + * The max number of COM ports that can be handled by POUT_INFO::timestr_ports + */ #define MAX_POUT_TIMESTR_PORTS 8 -/* - * The codes below are used with POUT_INFO::flags: +/** + * @brief Bits used with POUT_INFO::flags */ -#define POUT_SUPP_IF_SYNC_ONLY 0x0001 // supports disabling outputs in holdover mode -#define POUT_SUPP_DCF77_UTC 0x0002 // supports UTC output in DCF77 mode +enum POUT_INFO_FLAG_BITS +{ + POUT_BIT_SUPP_IF_SYNC_ONLY, ///< 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 + 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 ) /** - The structure below adds an index number to the structure - above to allow addressing of several instances: + * @brief Current settings and general capabilities of a specific serial port + * + * This structure should be read from the device to retrieve the + * current settings of a specific programmable output plus its capabilities, + * e.g. supported modes of operation, etc. + * The number of supported ports is RECEIVER_INFO::n_prg_out. + * + * @note The ::POUT_SETTINGS_IDX structure should be send back to + * the device to configure the specified programmable pulse output. */ typedef struct { - uint16_t idx; /**< 0..RECEIVER_INFO.n_prg_out-1 */ + uint16_t idx; ///< 0..RECEIVER_INFO::n_prg_out - 1 POUT_INFO pout_info; } POUT_INFO_IDX; -#define _mbg_swab_pout_info_idx( _p ) \ -{ \ - _mbg_swab16( &(_p)->idx ); \ - _mbg_swab_pout_info( &(_p)->pout_info ); \ +#define _mbg_swab_pout_info_idx_on_get( _p ) \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_pout_info_on_get( &(_p)->pout_info ); \ } @@ -3335,30 +3866,36 @@ typedef struct /** * @brief All possibly supported ref time sources - */ -enum -{ - 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 */ - N_MULTI_REF /**< the number of defined sources, can not exceed bit number of uint32_t - 1 */ + * + * @see 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 }; -/* - * Names of supported ref time sources +/** + * @brief Names of supported ref time sources + * + * @see MULTI_REF_TYPES */ #define DEFAULT_MULTI_REF_NAMES \ { \ @@ -3375,28 +3912,37 @@ enum "Var. freq. via GPIO", \ "(reserved)", \ "DCF77 PZF Receiver", \ - "Long Wave Receiver" \ + "Long Wave Receiver", \ + "GLONASS/GPS Receiver", \ + "HaveQuick Input" \ } -/* - * Bit masks used to indicate supported reference sources - */ -#define HAS_MULTI_REF_GPS ( 1UL << MULTI_REF_GPS ) -#define HAS_MULTI_REF_10MHZ ( 1UL << MULTI_REF_10MHZ ) -#define HAS_MULTI_REF_PPS ( 1UL << MULTI_REF_PPS ) -#define HAS_MULTI_REF_10MHZ_PPS ( 1UL << MULTI_REF_10MHZ_PPS ) -#define HAS_MULTI_REF_IRIG ( 1UL << MULTI_REF_IRIG ) -#define HAS_MULTI_REF_NTP ( 1UL << MULTI_REF_NTP ) -#define HAS_MULTI_REF_PTP ( 1UL << MULTI_REF_PTP ) -#define HAS_MULTI_REF_PTP_E1 ( 1UL << MULTI_REF_PTP_E1 ) - -#define HAS_MULTI_REF_FREQ ( 1UL << MULTI_REF_FREQ ) -#define HAS_MULTI_REF_PPS_STRING ( 1UL << MULTI_REF_PPS_STRING ) -#define HAS_MULTI_REF_GPIO ( 1UL << MULTI_REF_GPIO ) -#define HAS_MULTI_REF_INTERNAL ( 1UL << MULTI_REF_INTERNAL ) -#define HAS_MULTI_REF_PZF ( 1UL << MULTI_REF_PZF ) -#define HAS_MULTI_REF_LWR ( 1UL << MULTI_REF_LWR ) +/** + * @brief Bit masks according to enumerated ref time sources + * + * @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 + + 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 +}; /* @@ -3412,19 +3958,17 @@ enum * the number of supported input sources and priorities * is limited to N_MULTI_REF_PRIO. */ - #define N_MULTI_REF_PRIO 4 /** - The structure below is used to configure the priority of - the supported ref sources. - - The number stored in prio[0] of the array indicates the ref time - source with highest priority. If that source fails, the device - falls back to the source indicated by prio[1]. Each field of - the prio[] array must be set to one of the values 0..N_MULTI_REF-1, - or to -1 (0xFF) if the value is not assigned. + * @brief A structure used to configure the priority of the supported ref sources + * + * The number stored in prio[0] of the array indicates the ref time + * source with highest priority. If that source fails, the device + * falls back to the source indicated by prio[1]. Each field of + * the prio[] array must be set to one of the values 0..N_MULTI_REF-1, + * or to -1 (0xFF) if the value is not assigned. */ typedef struct { @@ -3433,41 +3977,40 @@ typedef struct /** - The structure below is used to query the MULTI_REF configuration, - plus the supported ref sources. + * @brief A structure used to query MULTI_REF configuration parameters + * + * This also includes a bit mask of supported ref sources. */ typedef struct { - MULTI_REF_SETTINGS settings; /* current settings */ - uint32_t supp_ref; /* supp. HAS_MULTI_REF_... codes or'ed */ - uint16_t n_levels; /* supp. levels, 0..N_MULTI_REF_PRIO */ - uint16_t flags; /* reserved, currently 0 */ + MULTI_REF_SETTINGS settings; ///< current settings + uint32_t supp_ref; ///< bit mask of supported sources, see ::MULTI_REF_TYPE_MASKS + uint16_t n_levels; ///< supp. levels, 0..N_MULTI_REF_PRIO-1 + uint16_t flags; ///< reserved, currently always 0 } MULTI_REF_INFO; -/* - * The type below is used to query the MULTI_REF status information, +/** + * @brief A data type used to query MULTI_REF status information */ -typedef uint16_t MULTI_REF_STATUS; /* flag bits as defined below */ +typedef uint16_t MULTI_REF_STATUS; ///< @see MULTI_REF_STATUS_BITS -/* - * The bits and associated bit masks below are used with the - * MULTI_REF_STATUS type. Each bit is set if the associated - * condition is true and is reset if the condition is not true: +/** + * @brief Bits and associated masks used with ::MULTI_REF_STATUS */ -enum +enum MULTI_REF_STATUS_BITS { - WRN_MODULE_MODE, /* selected input mode was invalid, set to default */ - WRN_COLD_BOOT, /* GPS is in cold boot mode */ - WRN_WARM_BOOT, /* GPS is in warm boot mode */ - WRN_ANT_DISCONN, /* antenna is disconnected */ - WRN_10MHZ_UNLOCK, /* impossible to lock to external 10MHz reference */ - WRN_1PPS_UNLOCK, /* impossible to lock to external 1PPS reference */ - WRN_GPS_UNLOCK, /* impossible to lock to GPS */ - WRN_10MHZ_MISSING, /* external 10MHz signal not available */ - WRN_1PPS_MISSING, /* external 1PPS signal not available */ - N_MULTI_REF_STATUS_BITS + WRN_MODULE_MODE, ///< selected input mode was invalid, set to default + WRN_COLD_BOOT, ///< GPS is in cold boot mode + WRN_WARM_BOOT, ///< GPS is in warm boot mode + WRN_ANT_DISCONN, ///< antenna is disconnected + WRN_10MHZ_UNLOCK, ///< impossible to lock to external 10MHz reference + WRN_1PPS_UNLOCK, ///< impossible to lock to external 1PPS reference + WRN_GPS_UNLOCK, ///< impossible to lock to GPS + WRN_10MHZ_MISSING, ///< external 10MHz signal not available + WRN_1PPS_MISSING, ///< external 1PPS signal not available + N_MULTI_REF_STATUS_BITS ///< the number of known bits }; #define MSK_WRN_COLD_BOOT ( 1UL << WRN_COLD_BOOT ) @@ -3505,9 +4048,8 @@ enum */ typedef struct { - uint8_t type; /**< 0..N_MULTI_REF-1 from the enum above */ - uint8_t instance; /**< instance number, if multiple instances are supported, else 0 */ - + uint8_t type; ///< @see MULTI_REF_TYPES + uint8_t instance; ///< instance number, if multiple instances are supported, else 0 } XMULTI_REF_ID; @@ -3517,12 +4059,11 @@ 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; ///< 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_SETTINGS; @@ -3535,9 +4076,8 @@ typedef struct */ 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 + XMULTI_REF_SETTINGS settings; ///< the settings configured for this level } XMULTI_REF_SETTINGS_IDX; @@ -3547,12 +4087,11 @@ typedef struct */ typedef struct { - XMULTI_REF_SETTINGS settings; /**< current settings */ - uint32_t supp_ref; /**< bit mask of or'ed HAS_MULTI_REF_... codes */ - uint8_t n_supp_ref; /**< number of supported ref time sources */ - uint8_t n_prio; /**< number of supported priority levels */ - uint16_t flags; /**< currently always 0 */ - + XMULTI_REF_SETTINGS settings; ///< current settings + 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_INFO; @@ -3562,9 +4101,8 @@ typedef struct */ 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 + XMULTI_REF_INFO info; ///< ref source cfg and capabilities } XMULTI_REF_INFO_IDX; @@ -3574,35 +4112,17 @@ typedef struct */ typedef struct { - XMULTI_REF_ID id; /**< time source identifier */ - uint16_t status; /**< flag bits as defined below */ - NANO_TIME offset; /**< time offset from main time base */ - uint16_t flags; /**< see flags specified below */ - uint8_t ssm; /**< synchronization status message ( if supported by src. )*/ - uint8_t soc; /**< signal outage counter ( updt. on loss of signal ) */ + XMULTI_REF_ID id; ///< time source identifier, 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_STATUS; /** - * @brief Bits and masks used with XMULTI_REF_STATUS::flags - * - * @note This API is only supported if bit GPS_HAS_XMRS_MULT_INSTC - * is set in RECEIVER_INFO::features. - */ -enum -{ - 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 ) - - - -/** * @brief Status information on a ref time source at a specific priority level */ typedef struct @@ -3616,24 +4136,21 @@ typedef struct /** * @brief Bits and bit masks used with XMULTI_REF_STATUS::status - * - * @note Flags XMRS_BIT_MULT_INSTC_SUPP and XMRS_BIT_NUM_SRC_EXC - * are set in the status flags for every priority if the associated - * condition is met. */ -enum -{ - XMRS_BIT_NOT_SUPP, /**< ref type cfg'd for this level is not supported */ - XMRS_BIT_NO_CONN, /**< input signal is disconnected */ - XMRS_BIT_NO_SIGNAL, /**< no input signal */ - XMRS_BIT_IS_MASTER, /**< reference is master source */ - XMRS_BIT_IS_LOCKED, /**< locked to input signal */ - XMRS_BIT_IS_ACCURATE, /**< oscillator control has reached full accuracy */ - XMRS_BIT_NOT_SETTLED, /**< reference time signal not settled */ - XMRS_BIT_NOT_PHASE_LOCKED, /**< oscillator not phase locked to PPS */ - XMRS_BIT_NUM_SRC_EXC, /**< number of available sources exceeds what can be handled */ - XMRS_BIT_IS_EXTERNAL, /**< this ref source is on extension card */ - N_XMRS_BITS /**< number of know status bits */ +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 ) @@ -3646,6 +4163,7 @@ enum #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 ) /* * Initializers for XMRS status bit strings. @@ -3655,16 +4173,35 @@ enum "Ref type not supported", \ "No connection", \ "No signal", \ - "Is Master", \ + "Is master", \ "Is locked", \ - "Is accuracte", \ + "Is accurate", \ "Not settled", \ "Phase not locked", \ "Number sources exceeds limit", \ - "Is external" \ + "Is external", \ + "Low jitter" \ } +/** + * @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 * with status invalid / not used @@ -3681,18 +4218,29 @@ enum /** * @brief The number of supported instances of each ref source type * - * @note This structure is only supported if bit GPS_HAS_XMRS_MULT_INSTC + * @note This structure is only supported if bit ::GPS_FEAT_XMRS_MULT_INSTC * is set in RECEIVER_INFO::features. */ typedef struct { - uint32_t flags; /**< currently always 0 */ - uint16_t n_xmr_settings; /**< number of configurable multi ref settings */ - uint8_t slot_id; /**< current slot ID of board ( 0..15 ) */ - uint8_t reserved; /**< reserved */ - uint8_t n_inst[32]; /**< N_MULTI_REF entries used, but can not exceed bit number of uint32_t - 1 */ + uint32_t flags; ///< 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 } XMULTI_REF_INSTANCES; + +/** + * @brief Holdover interval while switching XMR sources + * + * @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. + */ +typedef uint32_t XMR_HOLDOVER_INTV; ///< [s] */ + + /** @} group_xmr_cfg */ @@ -3700,10 +4248,18 @@ typedef struct /** * @defgroup group_gpio GPIO port configuration stuff * + * @note This is only supported if ::GPS_HAS_GPIO is set + * in the RECEIVER_INFO::features mask. + * * @{ */ + /** * @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. */ typedef struct { @@ -3716,7 +4272,60 @@ typedef struct /** + * @brief Enumeration of GPIO types + * + * 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 + */ +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 */ +}; + + +#define DEFAULT_GPIO_TYPES_SHORT_STRS \ +{ \ + "Freq. In", \ + "Freq. Out", \ + "Fixed Freq Out", \ + "BITS In", \ + "BITS Out" \ +} + + + +/** + * @brief Enumeration of signal shapes + * + * Used to specify the signal shape of an input or output + * frequency signal. + */ +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 */ +}; + +/** 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 A structure used to specify a variable frequency + * + * Used to specify a variable frequency for GPIO input or output */ typedef struct { @@ -3726,139 +4335,320 @@ typedef struct } MBG_GPIO_FREQ; + /** - * @brief A structure used to specify a fixed frequency + * @brief Configuration of a GPIO variable frequency input + * + * @see MBG_GPIO_TYPE_FREQ_IN */ typedef struct { - uint32_t frq_bit; /**< fixed freq. bit mask ( see enum ) */ - uint32_t reserved; /**< reserved */ + 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_FIXED_FREQ; +} MBG_GPIO_FREQ_IN_SETTINGS; /** - * @brief A structure used to specify a framed datastream + * @brief Supported options for a variable frequency GPIO input + * + * @see MBG_GPIO_TYPE_FREQ_IN */ typedef struct { - uint32_t format; /**< format bit mask ( see enum and bit mask ! ) */ - uint32_t reserved; /**< reserved */ + //##++++++++++++++++ + 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 */ + +} MBG_GPIO_FREQ_IN_SUPP; + -} MBG_GPIO_BITS; /** - * @brief A structure used to configure a GPIO as frequency output + * @brief Configuration of a GPIO variable frequency output + * + * @see MBG_GPIO_TYPE_FREQ_OUT */ typedef struct { MBG_GPIO_FREQ freq; /**< frequency */ int32_t milli_phase; /**< phase [1/1000 degree units] */ - uint32_t type; /**< sine, rectangle, etc. */ //##++++++++++++++ + 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_OUT_SETTINGS; + /** - * @brief A structure used to configure a GPIO as frequency output + * @brief Supported options for a variable frequency GPIO output + * + * @see MBG_GPIO_TYPE_FREQ_OUT */ - typedef struct { - MBG_GPIO_FREQ freq; /**< frequency */ - uint32_t csc_limit; /**< max. cycle slip [1/1000 cycle units] */ - uint32_t type; /**< sine, rectangle, etc. */ //##++++++++++++++ - 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 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 */ -} MBG_GPIO_FREQ_IN_SETTINGS; +} MBG_GPIO_FREQ_OUT_SUPP; /** - * @brief A structure used to configure a GPIO as fixed frequency output + * @brief Supported fixed frequencies + */ +enum MBG_GPIO_FIXED_FREQ +{ + MBG_GPIO_FIXED_FREQ_8kHz, /**< 8kHz */ + MBG_GPIO_FIXED_FREQ_48kHz, /**< 48kHz */ + MBG_GPIO_FIXED_FREQ_1MHz, /**< 1MHz */ + MBG_GPIO_FIXED_FREQ_1544kHz, /**< 1.544MHz */ + MBG_GPIO_FIXED_FREQ_2048kHz, /**< 2.048MHz */ + MBG_GPIO_FIXED_FREQ_5MHz, /**< 5MHz */ + MBG_GPIO_FIXED_FREQ_10MHz, /**< 10MHz */ + MBG_GPIO_FIXED_FREQ_19440kHz, /**< 19.44MHz */ + N_MBG_GPIO_FIXED_FREQ /**< number of known frequencies */ +}; + +/** 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. + */ +#define MBG_GPIO_FIXED_FREQ_STRS \ +{ \ + "8kHz", \ + "48kHz", \ + "1MHz", \ + "1544kHz", \ + "2048kHz", \ + "5MHz", \ + "10MHz", \ + "19440kHz" \ +} + + +/** + * @brief Configuration of a GPIO fixed frequency output + * + * @see MBG_GPIO_TYPE_FIXED_FREQ_OUT */ typedef struct { - MBG_GPIO_FIXED_FREQ freq; /**< frequency */ - uint32_t reserved_0; /**< supported frequencies bit mask, see enum */ - uint32_t type; /**< sine, rectangle, etc. */ //##++++++++++++++ - uint32_t reserved_1; /**< currently always 0 */ - uint32_t flags; /**< currently always 0 */ + 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 */ } MBG_GPIO_FIXED_FREQ_OUT_SETTINGS; /** - * @brief A structure used to configure a GPIO as BITS module + * @brief Supported options for a fixed frequency output + * + * @see MBG_GPIO_TYPE_FIXED_FREQ_OUT */ +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 */ + +} MBG_GPIO_FIXED_FREQ_OUT_SUPP; + + + +/** + * @brief Definitions for MBG_GPIO_BITS::format + */ +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 */ +}; + +#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 Configuration of a GPIO as BITS input module + * + * @see MBG_GPIO_TYPE_BITS_IN + */ typedef struct { - MBG_GPIO_BITS bits; /**< DS Settings for building integrated timing supply */ - uint32_t csc_limit; /**< max. cycle slip [1/1000 cycle units] */ + uint32_t format; /**< signal type, see ::MBG_GPIO_BITS_FORMATS */ + uint32_t reserved; + uint32_t csc_limit; /**< max. cycle slip [1/1000 cycle units] */ union { struct { - uint8_t ssm; /**< minimum E1 SSM ( 0...15 ) for acceptance */ - uint8_t sa_bits; /**< Sa Bits group ( 4...8 ) carrying SSM */ + 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; + } e1; /**< used with E1 formats */ struct { uint8_t min_boc; uint8_t reserve_0; uint16_t reserve_1; - } t1; + } t1; /**< used with T1 formats */ + + uint32_t u32; /**< dummy to force at least 32 bit alignment */ - uint32_t u32; } quality; - uint32_t err_msk; /**< error mask msk, see enum */ - uint32_t flags; /**< currently always 0 */ + uint32_t err_msk; /**< controls which types of error can be ignored, see enum MBG_GPIO_BITS_ERR */ + uint32_t flags; /**< currently always 0 */ + } MBG_GPIO_BITS_IN_SETTINGS; /** - * @brief A structure used to configure a GPIO port + * @brief Definitions for MBG_GPIO_BITS_IN_SETTINGS::err_msk + */ +enum MBG_GPIO_BITS_ERR +{ + 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 */ +}; + +#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 + */ +typedef struct +{ + uint32_t supp_fmts; ///< bit mask of supported formats, see ::MBG_GPIO_BITS_FORMATS + uint32_t reserved; ///< reserved, currently always 0 + +} MBG_GPIO_BITS_IN_SUPP; + + + +/** + * @brief Configuration of a GPIO as BITS output module + * + * @see MBG_GPIO_TYPE_BITS_OUT */ typedef struct { - uint32_t mode; /** frequency out, frequency in, pulse out, etc. */ + 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; + +} MBG_GPIO_BITS_OUT_SETTINGS; + + +/** + * @brief Definitions for MBG_GPIO_BITS_OUT_SETTINGS::flags + */ +enum MBG_GPIO_BITS_OUT_FLAG +{ + 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 */ +}; + +#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 Supported options of a BITS GPIO output + * + * @see MBG_GPIO_TYPE_BITS_OUT + */ +typedef struct +{ + uint32_t supp_fmts; /**< bit mask of supported formats, see ::MBG_GPIO_BITS_FORMATS */ + uint32_t reserved; /**< currently always 0 */ +} MBG_GPIO_BITS_OUT_SUPP; + + +/** + * @brief A generic structure used to configure a GPIO port + */ +typedef struct +{ + uint32_t type; /**< GPIO type, see ::MBG_GPIO_TYPES */ uint32_t reserved; /**< currently always 0 */ uint32_t flags; /**< currently always 0 */ - union + union /**< settings depending on the GPIO type, see ::MBG_GPIO_TYPES */ { - MBG_GPIO_FREQ_OUT_SETTINGS freq_out; /** if type is frequency output */ - MBG_GPIO_FREQ_IN_SETTINGS freq_in; /** if type is frequency input */ - MBG_GPIO_FIXED_FREQ_OUT_SETTINGS ff_out; /** if type is fixed frequency output */ - MBG_GPIO_BITS_IN_SETTINGS bits_in; /** if type is framed ds. in */ + 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 */ } u; } MBG_GPIO_SETTINGS; + /** - * @brief A structure used to describe a GPIO ports limiting values + * @brief A generic structure used to describe a GPIO ports limiting values */ typedef struct { - uint32_t supp_modes; /**< supported modes */ - uint32_t reserved; - uint32_t supp_flags; /**< supported flags */ + uint32_t type; /**< GPIO type, see ::MBG_GPIO_TYPES */ + uint32_t reserved; /**< currently always 0 */ + uint32_t supp_flags; /**< supported flags */ - union + union /**< limits depending on the GPIO type, see ::MBG_GPIO_TYPES */ { - MBG_GPIO_FREQ_OUT_SETTINGS freq_out; /** max. freq. values for output */ - MBG_GPIO_FREQ_IN_SETTINGS freq_in; /** max. freq. values for input */ - MBG_GPIO_FIXED_FREQ_OUT_SETTINGS ff_out; /** max. ff values for output */ - MBG_GPIO_BITS_IN_SETTINGS bits_in; /** if type is framed ds. in */ + MBG_GPIO_FREQ_IN_SUPP freq_in; /**< if type is MBG_GPIO_TYPE_FREQ_IN */ + MBG_GPIO_FREQ_OUT_SUPP freq_out; /**< if type is MBG_GPIO_TYPE_FREQ_OUT */ + MBG_GPIO_FIXED_FREQ_OUT_SUPP ff_out; /**< if type is MBG_GPIO_TYPE_FIXED_FREQ_OUT */ + MBG_GPIO_BITS_IN_SUPP bits_in; /**< if type is MBG_GPIO_TYPE_BITS_IN */ + MBG_GPIO_BITS_OUT_SUPP bits_out; /**< if type is MBG_GPIO_TYPE_BITS_OUT */ } u; } MBG_GPIO_LIMITS; @@ -3884,6 +4674,7 @@ typedef struct { MBG_GPIO_SETTINGS settings; /**< current configuration */ MBG_GPIO_LIMITS limits; /**< supp. and max. values */ + } MBG_GPIO_INFO; @@ -3895,107 +4686,178 @@ 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 */ + } MBG_GPIO_INFO_IDX; +/** @} group_gpio */ + + /** - * @brief Definitions for MBG_GPIO_SETTINGS::mode - */ -enum -{ - MBG_GPIO_SIGNAL_TYPE_FREQ_OUT, /**< variable frequency output */ - MBG_GPIO_SIGNAL_TYPE_FREQ_IN, /**< variable frequency inputs */ - MBG_GPIO_SIGNAL_TYPE_FIXED_FREQ_OUT, /**< fixed frequency outputs */ - MBG_GPIO_SIGNAL_TYPE_FIXED_FREQ_IN, /**< fixed frequency input */ - MBG_GPIO_SIGNAL_TYPE_BITS_OUT, /**< framed data stream output */ - MBG_GPIO_SIGNAL_TYPE_BITS_IN, /**< framed data stream input */ - N_MBG_GPIO_SIGNAL_TYPES /**< number of known modes */ -}; + * @defgroup group_havequick GPIO port configuration stuff + * + * @note This is only supported if the ::GPS_HAS_HAVEQUICK bit is set + * in the RECEIVER_INFO::features mask. + * + * @{ */ +/** + * @brief Enumeration of HaveQuick formats + * + * @see HAVEQUICK_SETTINGS::format + * @see HAVEQUICK_FORMAT_MASKS + */ +enum HAVEQUICK_FORMATS +{ + HQ_FMT_STANAG4246_1, + HQ_FMT_STANAG4246_2, + HQ_FMT_STANAG4246_PTTI, + HQ_FMT_STANAG4372_SATURN_1, + HQ_FMT_STANAG4372_SATURN_2, + HQ_FMT_STANAG4430_EXTD, + N_HQ_FMT ///< number of known formats +}; + /** - * @brief Definitions for MBG_GPIO_FF_OUT_SETTINGS::frq_bit + * @brief Bit masks associated to enumerated HaveQuick formats + * + * @see HAVEQUICK_INFO::supp_formats + * @see HAVEQUICK_FORMATS */ -enum +enum HAVEQUICK_FORMAT_MASKS { - 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 */ + HQ_MSK_STANAG4246_1 = ( 1UL << HQ_FMT_STANAG4246_1 ), ///< see ::HQ_FMT_STANAG4246_1 + HQ_MSK_STANAG4246_2 = ( 1UL << HQ_FMT_STANAG4246_2 ), ///< see ::HQ_FMT_STANAG4246_2 + HQ_MSK_STANAG4246_PTTI = ( 1UL << HQ_FMT_STANAG4246_PTTI ), ///< see ::HQ_FMT_STANAG4246_PTTI + HQ_MSK_STANAG4372_SATURN_1 = ( 1UL << HQ_FMT_STANAG4372_SATURN_1 ), ///< see ::HQ_FMT_STANAG4372_SATURN_1 + HQ_MSK_STANAG4372_SATURN_2 = ( 1UL << HQ_FMT_STANAG4372_SATURN_2 ), ///< see ::HQ_FMT_STANAG4372_SATURN_2 + HQ_MSK_STANAG4430_EXTD = ( 1UL << HQ_FMT_STANAG4430_EXTD ) ///< see ::HQ_FMT_STANAG4430_EXTD }; -/**< Bit Masks to be used with MBG_GPIO_FF_OUT_SETTINGS::frq_bit */ -#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 ) +/* + * 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" /* - * Initializers for GPIO fixed frequency strings. + * The definition below can be used to initialize + * an array of N_HQ_FMT name strings. */ -#define MBG_GPIO_FIXED_FREQ_STRS \ -{ \ - "8kHz", \ - "48kHz", \ - "1MHz", \ - "1544kHz", \ - "2048kHz", \ - "5MHz", \ - "10MHz", \ - "19440kHz" \ +#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 Definitions for MBG_GPIO_BITS::format + * @brief Configuration settings for a HaveQuick input or output */ -enum +typedef struct { - 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 /**< number of formats */ -}; + uint16_t format; ///< see ::HAVEQUICK_FORMATS + uint16_t flags; ///< see ::HAVEQUICK_FLAG_MASKS + int32_t offset; ///< Tx: unused, Rx: offset of incoming time in [s] + uint32_t reserved_0; ///< reserved, currently always 0 + uint32_t reserved_1; ///< reserved, currently always 0 +} HAVEQUICK_SETTINGS; + +#define _mbg_swab_havequick_settings( _p ) \ +{ \ + _mbg_swab16( &(_p)->format ); \ + _mbg_swab16( &(_p)->flags ); \ + _mbg_swab32( &(_p)->offset ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ +} -#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 Current settings and capabilities of a HaveQuick input or output + */ +typedef struct +{ + HAVEQUICK_SETTINGS settings; ///< current settings + uint32_t supp_formats; ///< see ::HAVEQUICK_FORMAT_MASKS + uint16_t supp_flags; ///< mask of flags supported in settings, see ::HAVEQUICK_FLAG_MASKS + uint16_t reserved; ///< reserved, currently always 0 +} HAVEQUICK_INFO; + +#define _mbg_swab_havequick_info( _p ) \ +{ \ + _mbg_swab_havequick_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_formats ); \ + _mbg_swab16( &(_p)->supp_flags ); \ + _mbg_swab16( &(_p)->reserved ); \ +} /** - * @brief Definitions for MBG_GPIO_BITS_IN_SETTINGS::quality.err + * @brief Known HaveQuick control flags + * + * @see HAVEQUICK_FLAG_MASKS */ -enum +enum HAVEQUICK_FLAG_BITS { - 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 */ + HQ_FLAG_TX_GEN_LOCAL_TIME, + HQ_FLAG_SIGNAL_INVERTED, + HQ_FLAG_USE_EXT_PPS, + N_HQ_FLAG_BITS }; -#define MSK_MBG_GPIO_BITS_ERR_LOS ( 1UL << MBG_GPIO_BITS_ERR_LOS ) -#define MSK_MBG_GPIO_BITS_ERR_LOF ( 1UL << MBG_GPIO_BITS_ERR_LOF ) + +/** + * @brief Bit masks associated to HaveQuick control flags + * + * @see HQ_SETTINGS::flags + * @see HQ_INFO::flags + * @see HAVEQUICK_FLAG_BITS + */ +enum HAVEQUICK_FLAG_MASKS +{ + HQ_MSK_TX_GEN_LOCAL_TIME = ( 1UL << HQ_FLAG_TX_GEN_LOCAL_TIME ), ///< see ::HQ_FLAG_TX_GEN_LOCAL_TIME + HQ_MSK_SIGNAL_INVERTED = ( 1UL << HQ_FLAG_SIGNAL_INVERTED ), ///< see ::HQ_FLAG_SIGNAL_INVERTED + HQ_MSK_USE_EXT_PPS = ( 1UL << HQ_FLAG_USE_EXT_PPS ) ///< see ::HQ_FLAG_USE_EXT_PPS +}; -/** @} group_gpio */ +/** @} 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. * * @{ */ @@ -4019,7 +4881,9 @@ typedef uint16_t MBG_EVT_CODE; typedef uint16_t MBG_EVT_INFO; #define _mbg_swab_evt_info( _p ) _mbg_swab16( _p ); -/** @brief An event log entry */ +/** + * @brief An event log entry + */ typedef struct { uint32_t time; /**< like time_t, seconds since 1970 */ @@ -4042,8 +4906,8 @@ typedef uint16_t MBG_EVT_INFO; #define MBG_EVT_ID_BITS 13 #define MBG_EVT_LVL_BITS 3 -#define MBG_EVT_ID_MASK ( ( 1UL << MBG_EVT_ID_BITS ) - 1 ) -#define MBG_EVT_LVL_MASK ( ( 1UL << MBG_EVT_LVL_BITS ) - 1 ) +#define MBG_EVT_ID_MASK ( (MBG_EVT_CODE) ( 1UL << MBG_EVT_ID_BITS ) - 1 ) +#define MBG_EVT_LVL_MASK ( (MBG_EVT_CODE) ( 1UL << MBG_EVT_LVL_BITS ) - 1 ) // Combine an ID and Level to a code which can be stored @@ -4060,8 +4924,10 @@ typedef uint16_t MBG_EVT_INFO; ( ( (_code) >> MBG_EVT_ID_BITS ) & MBG_EVT_LVL_MASK ) -/** @brief Enumeration of event IDs */ -enum +/** + * @brief Enumeration of event IDs + */ +enum MBG_EVT_IDS { MBG_EVT_ID_NONE, /**< no event (empty entry) */ MBG_EVT_ID_POW_UP_RES, /**< power up reset */ @@ -4105,8 +4971,10 @@ enum -/** @brief Enumeration of event severity levels */ -enum +/** + * @brief Enumeration of event severity levels + */ +enum MBG_EVT_LVLS { MBG_EVT_LVL_NONE, MBG_EVT_LVL_DEBUG, @@ -4150,10 +5018,109 @@ enum #define MBG_EVT_ANT_OK _mbg_mk_evt_code( MBG_EVT_ID_ANT_OK, MBG_EVT_LVL_INFO ) #define MBG_EVT_LOW_SATS _mbg_mk_evt_code( MBG_EVT_ID_LOW_SATS, MBG_EVT_LVL_WARN ) - /** @} group_evt_log */ + +/** + * @defgroup group_ims IMS support + * + * @note This is only available if ::GPS_HAS_IMS is set in RECEIVER_INFO::features. + * + * @{ */ + +/** + * @brief Generic state of an IMS device + */ +typedef struct +{ + uint8_t chassis_id; /**< chassis ID, 0 if installed on the backplane */ + uint8_t slot_id; /**< slot number on the chassis */ + uint16_t num_sensors; /**< number of sensors provided by the device */ + uint32_t reserved; /**< currently unused, always 0 */ + uint32_t flags; /**< currently unused, always 0 */ + +} MBG_IMS_STATE; + +#define _mbg_swab_mbg_ims_state( _p ) \ +{ \ + _mbg_swab16( &(_p)->num_sensors ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} + + + +/** + * @brief Generic state of an IMS sensor + */ +typedef struct +{ + uint16_t type; /**< sensor type, see ::MBG_IMS_SENSORS */ + uint16_t idx; /**< index of the sensor of this type */ + int32_t val; /**< sensor value, in units according to the type */ + int16_t exp; /**< 10s exponent of the sensor value */ + uint16_t reserved; /**< currently unused, always 0 */ + uint32_t flags; /**< currently unused, always 0 */ + +} MBG_IMS_SENSOR_STATE; + +#define _mbg_swab_mbg_ims_sensor_state( _p ) \ +{ \ + _mbg_swab16( &(_p)->type ); \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab32( &(_p)->val ); \ + _mbg_swab16( &(_p)->exp ); \ + _mbg_swab16( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} + + +/** + * @brief Generic state of an IMS sensor, with sensor index + */ +typedef struct +{ + uint32_t idx; /**< sensor index, 0..MBG_IMS_STATE::num_sensors - 1 */ + MBG_IMS_SENSOR_STATE state; /**< sensor state */ + +} MBG_IMS_SENSOR_STATE_IDX; + +#define _mbg_swab_mbg_ims_sensor_state_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_mbg_ims_sensor_state( &(_p)->state ); \ +} + + + +/** + * @brief IMS sensor types + */ +enum MBG_IMS_SENSORS +{ + MBG_IMS_SENSOR_TEMP_C, /**< temperature in degrees 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 */ +}; + + + +// Definitions used with MBG_IMS_SENSOR_STATE::flags: + +// if MBG_IMS_SENSOR_STATE::type == MBG_IMS_SENSOR_VOLTAGE: +#define MBG_IMS_SENSOR_VOLTAGE_OUT_ENB 0x01 // output is enabled +#define MBG_IMS_SENSOR_VOLTAGE_OUT_OVR 0x02 // output overload + +// if MBG_IMS_SENSOR_STATE::type == MBG_IMS_SENSOR_PLL: +#define MBG_IMS_SENSOR_PLL_LOCKED 0x01 + + +/** @} group_ims */ + + + /** * @defgroup group_generic_io Generic I/O support. * @@ -4205,7 +5172,7 @@ typedef struct * supported, and how many data sets of the specified type * are supported by a device. */ -enum +enum PCPS_GEN_IO_TYPES { PCPS_GEN_IO_GET_INFO, /**< GEN_IO_INFO (read only) */ PCPS_GEN_IO_CAL_REC_IRIG_RX_COMP, /**< CAL_REC_IRIG_RX_COMP (read/write) */ @@ -4296,20 +5263,22 @@ typedef struct #define MSK_EPLD_CNTL_SEL_REM 0x0800 // remote select for output MUX ( clk_1 = 0 ) #define MSK_EPLD_CNTL_DIS_REM 0x1000 // remote disable for output MUX #define MSK_EPLD_CNTL_REMOTE 0x2000 // must be set to enable remote operation -#define MSK_EPLD_CNTL_SEL_SNMP 0x4000 // connect COM0 channels to XPORT -#define MSK_EPLD_CNTL_ENA_SNMP 0x8000 // select clk for comm. ( clk1 = 0 ) +#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 -/* - * Definitions for clk0_info and clk1_info, can be used to determine - * the reference clock type connected to SCU input channel 0 and 1: +/** + * @brief Definitions for SCU_STAT_INFO::clk0_info and SCU_STAT_INFO::clk1_info + * + * Can be used to determine the reference clock type connected to the SCU input channels. */ -enum +enum SCU_CLK_INFO_TYPES { - SCU_CLK_INFO_GPS, // ref. clock is GPS receiver - SCU_CLK_INFO_DCF_PZF, // ref. clock is DCF77 PZF receiver - SCU_CLK_INFO_DCF_AM, // ref. clock is DCF77 AM receiver - SCU_CLK_INFO_TCR // ref. clock is IRIG time code receiver + SCU_CLK_INFO_GPS, ///< ref. clock is GPS receiver + SCU_CLK_INFO_DCF_PZF, ///< ref. clock is DCF77 PZF receiver + SCU_CLK_INFO_DCF_AM, ///< ref. clock is DCF77 AM receiver + SCU_CLK_INFO_TCR, ///< ref. clock is IRIG time code receiver + N_SCU_CLK_INFO ///< number of known types }; @@ -4375,13 +5344,13 @@ typedef struct /** * @brief An enumeration of known satellite navigation systems */ -enum +enum MBG_GNSS_TYPES { - GNSS_TYPE_GPS, /**< GPS, United States */ - GNSS_TYPE_GLONASS, /**< GLONASS, Russia */ - GNSS_TYPE_BEIDOU, /**< BEIDOU, China */ - GNSS_TYPE_GALILEO, /**< GALILEO, Europe */ - N_GNSS_TYPES /**< Number of defined codes */ + GNSS_TYPE_GPS, ///< GPS, United States + GNSS_TYPE_GLONASS, ///< GLONASS, Russia + GNSS_TYPE_BEIDOU, ///< BEIDOU, China + GNSS_TYPE_GALILEO, ///< GALILEO, Europe + N_GNSS_TYPES ///< Number of defined codes }; #define GNSS_TYPE_STRS \ @@ -4433,10 +5402,10 @@ typedef struct /** * @brief Flags used with MBG_GNSS_MODE_SETTINGS::flags and MBG_GNSS_MODE_INFO::flags */ -enum +enum MBG_GNSS_MODE_FLAG_BITS { - MBG_GNSS_FLAG_EXCLUSIVE, /**< (read only) only one of the supported GNSS systems can be used at the same time */ - MBG_GNSS_FLAG_HAS_PRIORITY, /**< (read only) priority can be configured using the MBG_GNSS_MODE_SETTINGS::prio field */ + MBG_GNSS_FLAG_EXCLUSIVE, ///< (read only) only one of the supported GNSS systems can be used at the same time + MBG_GNSS_FLAG_HAS_PRIORITY, ///< (read only) priority can be configured using the MBG_GNSS_MODE_SETTINGS::prio field N_MBG_GNSS_FLAGS }; @@ -4498,7 +5467,7 @@ typedef uint16_t ANT_CABLE_LEN; * @defgroup group_ip4_cfg Simple configuration and status * of an optional LAN interface. * - * @note This is only supported if the flag GPS_HAS_LAN_IP4 is set + * @note This is only supported if the flag ::GPS_HAS_LAN_IP4 is set * in RECEIVER_INFO::features. * * @{ */ @@ -4544,20 +5513,20 @@ typedef struct * @note IP4_SETTINGS::vlan_cfg contains a combination of * a VLAN ID number plus a VLAN priority code. */ -#define VLAN_ID_BITS 12 //< number of bits to hold the ID -#define N_VLAN_ID ( 1 << VLAN_ID_BITS ) //< number of ID values -#define MIN_VLAN_ID 0 //< minimum ID value -#define MAX_VLAN_ID ( N_VLAN_ID - 1 ) //< maximum ID value +#define VLAN_ID_BITS 12 ///< number of bits to hold the ID +#define N_VLAN_ID ( 1 << VLAN_ID_BITS ) ///< number of ID values +#define MIN_VLAN_ID 0 ///< minimum ID value +#define MAX_VLAN_ID ( N_VLAN_ID - 1 ) ///< maximum ID value // vlan_id = ( vlan_cfg >> VLAN_ID_SHIFT ) & VLAN_ID_MSK #define VLAN_ID_SHIFT 0 #define VLAN_ID_MSK ( ( 1 << VLAN_ID_BITS ) - 1 ) -#define VLAN_PRIORITY_BITS 3 //< number of bits to hold priority -#define N_VLAN_PRIORITY ( 1 << VLAN_PRIORITY_BITS ) //< number of priority values -#define MIN_VLAN_PRIORITY 0 //< minimum priority -#define MAX_VLAN_PRIORITY ( N_VLAN_PRIORITY - 1 ) //< maximum priority +#define VLAN_PRIORITY_BITS 3 ///< number of bits to hold priority +#define N_VLAN_PRIORITY ( 1 << VLAN_PRIORITY_BITS ) ///< number of priority values +#define MIN_VLAN_PRIORITY 0 ///< minimum priority +#define MAX_VLAN_PRIORITY ( N_VLAN_PRIORITY - 1 ) ///< maximum priority // vlan_priority = ( vlan_cfg >> VLAN_PRIORITY_SHIFT ) & VLAN_PRIORITY_MSK #define VLAN_PRIORITY_SHIFT ( ( 8 * sizeof( uint16_t ) ) - VLAN_PRIORITY_BITS ) @@ -4599,6 +5568,46 @@ typedef struct +/** @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_BYTE ( IP6_ADDR_BITS / 8 ) // == 16 + +/** + * @brief An IPv6 address + */ +typedef struct +{ + uint8_t b[IP6_ADDR_BYTE]; ///< bytes holding the address bits, b[0] == LSBs + uint8_t cidr_net_mask; ///< number of CIDR net mask bits, 0..IP6_ADDR_BITS + uint8_t reserved; ///< not yet used, always 0 + uint16_t flags; ///< not yet used, always 0 +} IP6_ADDR; + + + +/** @brief The max number of chars required for an IPv6 address string */ +#define MAX_IP6_ADDR_STR_LEN 43 ///< e.g. 2001:0db8:85a3:08d3:1319:8a2e:0370:7344/128 + +/** @brief Buffer size required to store an IPv6 address string */ +#define IP6_ADDR_STR_SIZE ( MAX_IP6_ADDR_STR_LEN + 1 ) ///< MAX_IP6_ADDR_STR_LEN + terminating 0 + +/** @brief A buffer for an IPv6 address string */ +typedef char IP6_ADDR_STR[IP6_ADDR_STR_SIZE]; + + + +/** + * @brief A structure to holds the MAC address of a LAN interface + */ +typedef struct +{ + uint8_t b[6]; +} MBG_MAC_ADDR; + + + /** * @brief LAN interface information * @@ -4607,14 +5616,14 @@ typedef struct */ typedef struct { - uint16_t type; //< type of LAN interface, see below - uint8_t mac_addr[6]; //< MAC address - uint16_t ver_code; //< version number, high byte.low byte, in hex - char ver_str[GPS_ID_STR_SIZE]; //< version string - char sernum[GPS_ID_STR_SIZE]; //< serial number - uint32_t rsvd_0; //< reserved, currently always 0 - uint16_t flags; //< flags as specified below - uint16_t rsvd_1; //< reserved, currently always 0 + uint16_t type; ///< type of LAN interface, see below + MBG_MAC_ADDR mac_addr; ///< MAC address + uint16_t ver_code; ///< version number, high byte.low byte, in hex + char ver_str[GPS_ID_STR_SIZE]; ///< version string + char sernum[GPS_ID_STR_SIZE]; ///< serial number + uint32_t rsvd_0; ///< reserved, currently always 0 + uint16_t flags; ///< flags as specified below + uint16_t rsvd_1; ///< reserved, currently always 0 } LAN_IF_INFO; @@ -4632,28 +5641,38 @@ typedef struct /** * @brief Codes used with LAN_IF_INFO::type */ -enum +enum LAN_IF_TYPES { - LAN_IF_TYPE_XPORT, //< LAN interface on an XPORT - LAN_IF_TYPE_PTP, //< LAN interface is a special PTP interface - N_LAN_IF_TYPE //< number of defined LAN interface types + LAN_IF_TYPE_XPORT, ///< LAN interface on an XPORT + LAN_IF_TYPE_PTP, ///< LAN interface is a special PTP interface + N_LAN_IF_TYPE ///< number of defined LAN interface types }; /** - * @brief Flags 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 */ -enum +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 + 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 }; -#define IP4_MSK_DHCP ( 1UL << IP4_BIT_DHCP ) -#define IP4_MSK_LINK ( 1UL << IP4_BIT_LINK ) -#define IP4_MSK_VLAN ( 1UL << IP4_BIT_VLAN ) +/** + * @brief Bit masks used with IP4_SETTINGS::flags and LAN_IF_INFO::flags + * + * @see MBG_IP4_FLAG_BITS + */ +enum MBG_IP4_FLAG_MASKS +{ + IP4_MSK_DHCP = ( 1UL << IP4_BIT_DHCP ), ///< see ::IP4_BIT_DHCP + IP4_MSK_LINK = ( 1UL << IP4_BIT_LINK ), ///< see ::IP4_BIT_LINK + IP4_MSK_VLAN = ( 1UL << IP4_BIT_VLAN ), ///< see ::IP4_BIT_VLAN +}; /** @} group_ip4_cfg */ @@ -4666,33 +5685,44 @@ enum /** * @brief Enumeration of protocols possibly used with PTP + * + * @see PTP_NW_PROT_MASKS + */ +enum PTP_NW_PROTS +{ + PTP_NW_PROT_RESERVED, ///< reserved + PTP_NW_PROT_UDP_IPV4, ///< IPv4 + PTP_NW_PROT_UDP_IPV6, ///< IPv6 + PTP_NW_PROT_IEEE_802_3, ///< Ethernet (raw layer 2) + PTP_NW_PROT_DEVICE_NET, ///< DeviceNet + PTP_NW_PROT_CONTROL_NET, ///< ControlNet + PTP_NW_PROT_PROFINET, ///< ProfiNet + N_PTP_NW_PROT ///< number of defined protocols +}; + + +/** + * @brief Bit masks for enumerated protocols possibly used with PTP + * + * @see PTP_NW_PROTS */ -enum +enum PTP_NW_PROT_MASKS { - PTP_NW_PROT_BIT_RESERVED, //< reserved - PTP_NW_PROT_BIT_UDP_IPV4, //< IPv4 - PTP_NW_PROT_BIT_UDP_IPV6, //< IPv6 - PTP_NW_PROT_BIT_IEEE_802_3, //< Ethernet (raw layer 2) - PTP_NW_PROT_BIT_DEVICE_NET, //< DeviceNet - PTP_NW_PROT_BIT_CONTROL_NET, //< ControlNet - PTP_NW_PROT_BIT_PROFINET, //< ProfiNet - N_PTP_NW_PROT //< number of defined protocols + PTP_NW_PROT_MSK_RESERVED = ( 1UL << PTP_NW_PROT_RESERVED ), ///< see ::PTP_NW_PROT_RESERVED + PTP_NW_PROT_MSK_UDP_IPV4 = ( 1UL << PTP_NW_PROT_UDP_IPV4 ), ///< see ::PTP_NW_PROT_UDP_IPV4 + PTP_NW_PROT_MSK_UDP_IPV6 = ( 1UL << PTP_NW_PROT_UDP_IPV6 ), ///< see ::PTP_NW_PROT_UDP_IPV6 + PTP_NW_PROT_MSK_IEEE_802_3 = ( 1UL << PTP_NW_PROT_IEEE_802_3 ), ///< see ::PTP_NW_PROT_IEEE_802_3 + PTP_NW_PROT_MSK_DEVICE_NET = ( 1UL << PTP_NW_PROT_DEVICE_NET ), ///< see ::PTP_NW_PROT_DEVICE_NET + PTP_NW_PROT_MSK_CONTROL_NET = ( 1UL << PTP_NW_PROT_CONTROL_NET ), ///< see ::PTP_NW_PROT_CONTROL_NET + PTP_NW_PROT_MSK_PROFINET = ( 1UL << PTP_NW_PROT_PROFINET ) ///< see ::PTP_NW_PROT_PROFINET }; -#define PTP_NW_PROT_MSK_RESERVED ( 1UL << PTP_NW_PROT_BIT_RESERVED ) -#define PTP_NW_PROT_MSK_UDP_IPV4 ( 1UL << PTP_NW_PROT_BIT_UDP_IPV4 ) -#define PTP_NW_PROT_MSK_UDP_IPV6 ( 1UL << PTP_NW_PROT_BIT_UDP_IPV6 ) -#define PTP_NW_PROT_MSK_IEEE_802_3 ( 1UL << PTP_NW_PROT_BIT_IEEE_802_3 ) -#define PTP_NW_PROT_MSK_DEVICE_NET ( 1UL << PTP_NW_PROT_BIT_DEVICE_NET ) -#define PTP_NW_PROT_MSK_CONTROL_NET ( 1UL << PTP_NW_PROT_BIT_CONTROL_NET ) -#define PTP_NW_PROT_MSK_PROFINET ( 1UL << PTP_NW_PROT_BIT_PROFINET ) -#if !defined( DEFAULT_PTP_NW_PROT_MASK ) - #define DEFAULT_PTP_NW_PROT_MASK ( PTP_NW_PROT_MSK_UDP_IPV4 | PTP_NW_PROT_MSK_IEEE_802_3 ) -#endif /** * @brief Name strings for the protocols possibly used with PTP + * + * @see PTP_NW_PROTS */ #define PTP_NW_PROT_STRS \ { \ @@ -4708,10 +5738,12 @@ enum /** * @brief Short name strings for the protocols possibly used with PTP + * + * @see PTP_NW_PROTS */ #define PTP_NW_PROT_STRS_SHORT \ { \ - "RES", \ + "RSV", \ "IP4", \ "IP6", \ "ETH", \ @@ -4724,19 +5756,19 @@ enum /** * @brief Possible states of a PTP port */ -enum -{ - PTP_PORT_STATE_UNINITIALIZED, //< uninitialized - PTP_PORT_STATE_INITIALIZING, //< currently initializing - PTP_PORT_STATE_FAULTY, //< faulty - PTP_PORT_STATE_DISABLED, //< disabled - PTP_PORT_STATE_LISTENING, //< listening for PTP packets - PTP_PORT_STATE_PRE_MASTER, //< going to become master - PTP_PORT_STATE_MASTER, //< master - PTP_PORT_STATE_PASSIVE, //< passive - PTP_PORT_STATE_UNCALIBRATED, //< uncalibrated - PTP_PORT_STATE_SLAVE, //< slave - N_PTP_PORT_STATE //< number of defined port states +enum PTP_PORT_STATES +{ + PTP_PORT_STATE_UNINITIALIZED, ///< uninitialized + PTP_PORT_STATE_INITIALIZING, ///< currently initializing + PTP_PORT_STATE_FAULTY, ///< faulty + PTP_PORT_STATE_DISABLED, ///< disabled + PTP_PORT_STATE_LISTENING, ///< listening for PTP packets + PTP_PORT_STATE_PRE_MASTER, ///< going to become master + PTP_PORT_STATE_MASTER, ///< master + PTP_PORT_STATE_PASSIVE, ///< passive + PTP_PORT_STATE_UNCALIBRATED, ///< uncalibrated + PTP_PORT_STATE_SLAVE, ///< slave + N_PTP_PORT_STATE ///< number of defined port states }; @@ -4763,53 +5795,69 @@ enum */ typedef struct { - uint8_t value; //< the parameter value - const char *name; //< the parameter name + uint8_t value; ///< the parameter value + const char *name; ///< the parameter name } PTP_TABLE; + /** * @brief An enumeration of PTP delay mechanisms * * @note This is different than the numeric values specified * in the published specs for IEEE1588. In addition, the specs - * define 0x14 for "disabled". + * define code 0x14 for "disabled". + * + * @see PTP_DELAY_MECH_MASKS + * @see PTP_DELAY_MECH_NAMES */ -enum +enum PTP_DELAY_MECHS { - PTP_DELAY_MECH_BIT_E2E, //< End-to-End (in PTP2 specs: 0x01) - PTP_DELAY_MECH_BIT_P2P, //< Peer-to-Peer (in PTP2 specs: 0x02) - N_PTP_DELAY_MECH //< number of defined delay mechanisms + PTP_DELAY_MECH_E2E, ///< End-to-End (in PTP2 specs: 0x01) + PTP_DELAY_MECH_P2P, ///< Peer-to-Peer (in PTP2 specs: 0x02) + N_PTP_DELAY_MECH ///< number of defined delay mechanisms }; -#define PTP_DELAY_MECH_MSK_E2E ( 1UL << PTP_DELAY_MECH_BIT_E2E ) -#define PTP_DELAY_MECH_MSK_P2P ( 1UL << PTP_DELAY_MECH_BIT_P2P ) -#if !defined( DEFAULT_PTP_DELAY_MECH_MASK ) - #define DEFAULT_PTP_DELAY_MECH_MASK ( PTP_DELAY_MECH_MSK_E2E | PTP_DELAY_MECH_MSK_P2P ) -#endif +/** + * @brief Bit masks associated to enumerated PTP delay mechanisms + * + * @see PTP_DELAY_MECH_MASKS + */ +enum PTP_DELAY_MECH_MASKS +{ + PTP_DELAY_MECH_MSK_E2E = ( 1UL << PTP_DELAY_MECH_E2E ), ///< see ::PTP_DELAY_MECH_E2E + PTP_DELAY_MECH_MSK_P2P = ( 1UL << PTP_DELAY_MECH_E2E ) ///< see ::PTP_DELAY_MECH_E2E +}; + + +#define PTP_DELAY_MECH_NAME_E2E "E2E" +#define PTP_DELAY_MECH_NAME_P2P "P2P" /** * @brief Name strings for the PTP delay mechanisms + * + * @see PTP_DELAY_MECHS */ #define PTP_DELAY_MECH_NAMES \ { \ - "E2E", \ - "P2P" \ + PTP_DELAY_MECH_NAME_E2E, \ + PTP_DELAY_MECH_NAME_P2P \ } -#define PTP_CLOCK_ACCURACY_NUM_BIAS 0x20 - /** * @brief An enumeration of accuracy classes used with PTP * * @note This enumeration does not start at 0 but with a bias - * specified by PTP_CLOCK_ACCURACY_NUM_BIAS. + * specified by ::PTP_CLOCK_ACCURACY_NUM_BIAS. + * + * @see PTP_CLOCK_ACCURACY_STRS */ -enum +enum PTP_CLOCK_ACCURACIES { + PTP_CLOCK_ACCURACY_NUM_BIAS = 0x20, PTP_CLOCK_ACCURACY_25ns = PTP_CLOCK_ACCURACY_NUM_BIAS, PTP_CLOCK_ACCURACY_100ns, PTP_CLOCK_ACCURACY_250ns, @@ -4840,8 +5888,10 @@ enum * @brief Name strings for PTP accuracy classes * * @note The enumeration does not start at 0 but with a bias - * specified by PTP_CLOCK_ACCURACY_NUM_BIAS, so this bias needs + * specified by ::PTP_CLOCK_ACCURACY_NUM_BIAS, so this bias needs * to be accounted for when accessing a string table. + * + * @see PTP_CLOCK_ACCURACIES */ #define PTP_CLOCK_ACCURACY_STRS \ { \ @@ -4873,20 +5923,27 @@ enum /** * @brief Codes to specify the type of a time source used with PTP - */ -#define PTP_TIME_SOURCE_ATOMIC_CLOCK 0x10 -#define PTP_TIME_SOURCE_GPS 0x20 -#define PTP_TIME_SOURCE_TERRESTRIAL_RADIO 0x30 -#define PTP_TIME_SOURCE_PTP 0x40 -#define PTP_TIME_SOURCE_NTP 0x50 -#define PTP_TIME_SOURCE_HAND_SET 0x60 -#define PTP_TIME_SOURCE_OTHER 0x90 -#define PTP_TIME_SOURCE_INTERNAL_OSCILLATOR 0xA0 + * + * @see PTP_TIME_SOURCE_TABLE + */ +enum PTP_TIME_SOURCES +{ + PTP_TIME_SOURCE_ATOMIC_CLOCK = 0x10, + PTP_TIME_SOURCE_GPS = 0x20, + PTP_TIME_SOURCE_TERRESTRIAL_RADIO = 0x30, + PTP_TIME_SOURCE_PTP = 0x40, + PTP_TIME_SOURCE_NTP = 0x50, + PTP_TIME_SOURCE_HAND_SET = 0x60, + PTP_TIME_SOURCE_OTHER = 0x90, + PTP_TIME_SOURCE_INTERNAL_OSCILLATOR = 0xA0 +}; /** * @brief A table of PTP time source codes plus associated name strings + * + * @see PTP_TIME_SOURCES */ #define PTP_TIME_SOURCE_TABLE \ { \ @@ -4908,38 +5965,71 @@ enum * @note 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. - */ -enum -{ - PTP_ROLE_MULTICAST_SLAVE, //< slave in multicast mode - PTP_ROLE_UNICAST_SLAVE, //< slave in unicast mode - PTP_ROLE_MULTICAST_MASTER, //< multicast master - PTP_ROLE_UNICAST_MASTER, //< unicast master - N_PTP_ROLES //< number of defined roles + * + * @see PTP_ROLE_STRS + * @see PTP_ROLE_STRS_SHORT + */ +enum PTP_ROLES +{ + PTP_ROLE_MULTICAST_SLAVE, ///< slave in multicast mode + PTP_ROLE_UNICAST_SLAVE, ///< slave in unicast mode + PTP_ROLE_MULTICAST_MASTER, ///< multicast master + PTP_ROLE_UNICAST_MASTER, ///< unicast master + PTP_ROLE_MULTICAST_AUTO, ///< multicast master or slave (auto selection) + PTP_ROLE_BOTH_MASTER, ///< simultanous multicast and unicast master + PTP_ROLE_HYBRID_MASTER, ///< multicast sync and unicast delay response as master + PTP_ROLE_HYBRID_SLAVE, ///< multicast sync and unicast delay request as slave + 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_BOTH_MASTER ( 1UL << PTP_ROLE_BOTH_MASTER ) +#define PTP_ROLE_MSK_HYBRID_MASTER ( 1UL << PTP_ROLE_HYBRID_MASTER ) +#define PTP_ROLE_MSK_HYBRID_SLAVE ( 1UL << PTP_ROLE_HYBRID_SLAVE ) + +#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 Name strings for defined PTP roles + * + * @see PTP_ROLES + * @see PTP_ROLE_STRS_SHORT */ #define PTP_ROLE_STRS \ { \ "Multicast Slave", \ "Unicast Slave", \ "Multicast Master", \ - "Unicast Master" \ + "Unicast Master", \ + "Multicast (Auto)" \ + "UC/MC Master" \ + "Hybrid Master" \ + "Hybrid Slave" \ } /** * @brief Short name strings for defined PTP roles + * + * @see PTP_ROLES + * @see PTP_ROLE_STRS */ #define PTP_ROLE_STRS_SHORT \ { \ "MCS", \ "UCS", \ "MCM", \ - "UCM" \ + "UCM", \ + "MC" \ + "UMM" \ + "HM" \ + "HS" \ } @@ -4976,13 +6066,17 @@ typedef uint16_t PTP_PORT_ID; * @brief An enumeration of time scales used with PTP * * @note The standard time scale used by PTP is TAI, which is a linear time scale. - * The protocol provides a UTC offset to be able to convert TAI to compute UTC, which - * can observe leap seconds. For the arbitrary time scale the UTC offset is unspecified. + * The protocol provides a %UTC offset to be able to convert TAI to compute %UTC, which + * can observe leap seconds. For the arbitrary time scale the %UTC offset is unspecified, + * so arbitrary time can be %UTC, or something else. + * + * @see PTP_TIMESCALE_NAMES + * @see PTP_TIMESCALE_NAMES_SHORT */ -enum +enum PTP_TIME_SCALES { - PTP_TIMESCALE_PTP, /* default */ - PTP_TIMESCALE_ARB, + PTP_TIMESCALE_PTP, ///< PTP default, TAI + PTP_TIMESCALE_ARB, ///< arbitrary time scale, maybe %UTC N_PTP_TIMESCALE }; @@ -5002,6 +6096,9 @@ enum /** * @brief A table of name strings for the PTP time scales + * + * @see PTP_TIME_SCALES + * @see PTP_TIMESCALE_NAMES_SHORT */ #define PTP_TIMESCALE_NAMES \ { \ @@ -5011,6 +6108,9 @@ enum /** * @brief A table of short name strings for the PTP time scales + * + * @see PTP_TIME_SCALES + * @see PTP_TIMESCALE_NAMES */ #define PTP_TIMESCALE_NAMES_SHORT \ { \ @@ -5025,34 +6125,33 @@ enum */ typedef struct { - //##++++ Do we need a port identifier ?? - uint16_t nw_prot; /**< one of the enumerated protocols (@see N_PTP_NW_PROT) */ - uint8_t ptp_prot_version; /**< PTP protocol version, 1, or 2, usually 2 for v2 */ - uint8_t port_state; /**< one of the enumerated port states (@see N_PTP_PORT_STATE ) */ - uint32_t flags; /**< bit masks as defined below */ - NANO_TIME offset; /**< estimated time offset from the upstream time source */ + uint16_t nw_prot; ///< one of the enumerated protocols, see ::PTP_NW_PROTS + uint8_t ptp_prot_version; ///< PTP protocol version, 1, or 2, usually 2 for v2 + uint8_t port_state; ///< one of the enumerated port states, see ::PTP_PORT_STATES + uint32_t flags; ///< see ::PTP_STATE_FLAGS + NANO_TIME offset; ///< estimated time offset from the upstream time source NANO_TIME path_delay; NANO_TIME mean_path_delay; NANO_TIME delay_asymmetry; - PTP_CLOCK_ID gm_id; /**< identifier ot the upstream time source */ + PTP_CLOCK_ID gm_id; ///< identifier ot the upstream time source uint16_t clock_offset_scaled_log_variance; uint8_t clock_class; - uint8_t clock_accuracy; /**< one of the enumerated accuracy class codes (@see N_PTP_CLOCK_ACCURACY) */ + uint8_t clock_accuracy; ///< see ::PTP_CLOCK_ACCURACIES - uint32_t reserved_1; /**< reserved, currently always 0 */ - uint32_t reserved_2; /**< reserved, currently always 0 */ + uint32_t reserved_1; ///< reserved, currently always 0 + uint32_t reserved_2; ///< reserved, currently always 0 - uint8_t domain_number; /**< the PTP clock domain number, 0:3 */ - uint8_t time_source; /**< one of the defined codes PTP_TIME_SOURCE_... */ - uint8_t delay_mech; /**< PTP_DELAY_MECH_BIT_E2E or PTP_DELAY_MECH_BIT_P2P */ + uint8_t domain_number; ///< the PTP clock domain number, 0:3 + uint8_t time_source; ///< see ::PTP_TIME_SOURCES + uint8_t delay_mech; ///< see ::PTP_DELAY_MECHS int8_t log_delay_req_intv; - int16_t utc_offset; /**< UTC offset observed against TAI */ - DAC_VAL osc_dac_cal; /**< disiplination value of the oscillator */ + 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 */ + uint32_t reserved_3; ///< reserved, currently always 0 } PTP_STATE; @@ -5075,56 +6174,39 @@ typedef struct /** - * @brief Flag bits used with PTP_STATE::flags - */ -enum -{ - PTP_FLAG_BIT_SLAVE_ONLY, /**< the port can only be slave */ - PTP_FLAG_BIT_IS_SLAVE, /**< the port is currently slave */ - PTP_FLAG_BIT_TIMESCALE_IS_PTP, /**< the timescale is PTP standard, not arbitrary */ - PTP_FLAG_BIT_LS_ANN, /**< a leap second is being announced */ - PTP_FLAG_BIT_LS_ANN_NEG, /**< the announced leap second is negative */ - PTP_FLAG_BIT_IS_UNICAST, /**< the port currently operates in unicast mode */ - N_PTP_FLAG_BIT /**< the number of defined flag bits */ + * @brief Flags bits used with PTP_STATE::flags + * + * @see PTP_STATE_FLAG_MASKS + */ +enum PTP_STATE_FLAGS +{ + PTP_FLAG_SLAVE_ONLY, ///< the port can only be slave + PTP_FLAG_IS_SLAVE, ///< the port is currently slave + PTP_FLAG_TIMESCALE_IS_PTP, ///< the timescale is PTP standard, not arbitrary + PTP_FLAG_LS_ANN, ///< a leap second is being announced + PTP_FLAG_LS_ANN_NEG, ///< the announced leap second is negative + PTP_FLAG_IS_UNICAST, ///< the port currently operates in unicast mode + PTP_FLAG_UTC_VALID, ///< %UTC parameters are valid + PTP_FLAG_ONE_STEP, ///< One-Step Clock active + N_PTP_STATE_FLAGS ///< the number of defined flag bits }; -#define PTP_FLAG_MSK_SLAVE_ONLY ( 1UL << PTP_FLAG_BIT_SLAVE_ONLY ) -#define PTP_FLAG_MSK_IS_SLAVE ( 1UL << PTP_FLAG_BIT_IS_SLAVE ) -#define PTP_FLAG_MSK_TIMESCALE_IS_PTP ( 1UL << PTP_FLAG_BIT_TIMESCALE_IS_PTP ) -#define PTP_FLAG_MSK_LS_ANN ( 1UL << PTP_FLAG_BIT_LS_ANN ) -#define PTP_FLAG_MSK_LS_ANN_NEG ( 1UL << PTP_FLAG_BIT_LS_ANN_NEG ) -#define PTP_FLAG_MSK_IS_UNICAST ( 1UL << PTP_FLAG_BIT_IS_UNICAST ) - - - -#define PTP_SYNC_INTERVAL_MIN -6 -#define PTP_SYNC_INTERVAL_MAX 6 - -#define PTP_DELAY_REQ_INTERVAL_MIN -6 -#define PTP_DELAY_REQ_INTERVAL_MAX 6 - -#define PTP_DEFAULT_UC_SYNC_INTV_MIN -4 -#define PTP_DEFAULT_UC_SYNC_INTV_MAX 4 - -#define PTP_DEFAULT_UC_DLY_REQ_INTV_MIN -4 -#define PTP_DEFAULT_UC_DLY_REQ_INTV_MAX 4 - -#define PTP_DEFAULT_UC_ANN_INTV_MIN -4 -#define PTP_DEFAULT_UC_ANN_INTV_MAX 4 - /** - * @defgroup group_ptp_uc_msg_duration_limits Unicast PTP masters send messages - * to a unicast slave only for a given interval as requested by the particular - * slave, which is called message duration. These symbols define the minimum and - * maximum message duration configured on a slave for a specific unicast master, - * i.e. for PTP_UC_MASTER_SETTINGS::message_duration. - * @{ */ - -#define PTP_UC_MSG_DURATION_MIN 10 //< minimum message duration [s] -#define PTP_UC_MSG_DURATION_MAX 1000 //< maximum message duration [s] -#define PTP_UC_MSG_DURATION_DEFAULT 60 //< default, though the specs say 300 s - -/** @} group_ptp_uc_msg_duration_limits */ + * @brief Flags masks used with PTP_STATE::flags + * + * @see PTP_STATE_FLAGS + */ +enum PTP_STATE_FLAG_MASKS +{ + PTP_FLAG_MSK_SLAVE_ONLY = ( 1UL << PTP_FLAG_SLAVE_ONLY ), ///< see ::PTP_FLAG_SLAVE_ONLY + PTP_FLAG_MSK_IS_SLAVE = ( 1UL << PTP_FLAG_IS_SLAVE ), ///< see ::PTP_FLAG_IS_SLAVE + PTP_FLAG_MSK_TIMESCALE_IS_PTP = ( 1UL << PTP_FLAG_TIMESCALE_IS_PTP ), ///< see ::PTP_FLAG_TIMESCALE_IS_PTP + PTP_FLAG_MSK_LS_ANN = ( 1UL << PTP_FLAG_LS_ANN ), ///< see ::PTP_FLAG_LS_ANN + PTP_FLAG_MSK_LS_ANN_NEG = ( 1UL << PTP_FLAG_LS_ANN_NEG ), ///< see ::PTP_FLAG_LS_ANN_NEG + PTP_FLAG_MSK_IS_UNICAST = ( 1UL << PTP_FLAG_IS_UNICAST ), ///< see ::PTP_FLAG_IS_UNICAST + PTP_FLAG_MSK_UTC_VALID = ( 1UL << PTP_FLAG_UTC_VALID ), ///< see ::PTP_FLAG_UTC_VALID + PTP_FLAG_MSK_ONE_STEP = ( 1UL << PTP_FLAG_ONE_STEP ) ///< see ::PTP_FLAG_ONE_STEP +}; @@ -5133,33 +6215,32 @@ enum */ typedef struct { - //##++++ Do we need a port identifier ?? - uint16_t nw_prot; /**< one of the enumerated and supported protocols (@see N_PTP_NW_PROT) */ - uint8_t profile; /**< PTP profile, currently only 0 = default */ - uint8_t domain_number; /**< the PTP clock domain number, 0:3 */ + uint16_t nw_prot; ///< see ::PTP_NW_PROTS + uint8_t selected_presets; ///< selected PTP presets, see ::PTP_PRESETS + uint8_t domain_number; ///< the PTP clock domain number, 0:3 - uint8_t delay_mech; /**< PTP_DELAY_MECH_BIT_E2E or PTP_DELAY_MECH_BIT_P2P, if supported */ - uint8_t ptp_role; /**< one of the enumerated PTP roles (@see N_PTP_ROLES) */ - uint8_t priority_1; /**< priority 1 */ - uint8_t priority_2; /**< priority 2 */ + uint8_t delay_mech; ///< see ::PTP_DELAY_MECHS + uint8_t ptp_role; ///< one of the supported PTP roles, see ::PTP_ROLES + uint8_t priority_1; ///< priority 1 + uint8_t priority_2; ///< priority 2 uint8_t dflt_clk_class_unsync_cold; // 6:255 uint8_t dflt_clk_class_unsync_warm; // 6:255 uint8_t dflt_clk_class_sync_cold; // 6:255 uint8_t dflt_clk_class_sync_warm; // 6:255 - uint8_t reserved_1; /**< reserved, currently always 0 */ - uint8_t reserved_2; /**< reserved, currently always 0 */ - int16_t sync_intv; /**< log2 of the sync interval [s] */ + uint8_t ann_rcpt_timeout; ///< announce msg. receipt timeout, see ::PTP_ANN_RCPT_TIMEOUT_LIMITS + uint8_t opt_ext; ///< optional configuration extension, see ::PTP_OPT_EXTS + int16_t sync_intv; ///< log2 of the sync interval [s] - int16_t ann_intv; /**< log2 of the announce interval [s] */ - int16_t delay_req_intv; /**< log2 of the delay request interval [s] */ + int16_t ann_intv; ///< log2 of the announce interval [s] + int16_t delay_req_intv; ///< log2 of the delay request interval [s] - uint32_t upper_bound; /**< sync state set to false if above this limit [ns] */ - uint32_t lower_bound; /**< sync state set to true if below this limit [ns] */ + uint32_t upper_bound; ///< sync state set to false if above this limit [ns] + uint32_t lower_bound; ///< sync state set to true if below this limit [ns] - uint32_t reserved_3; /**< reserved, currently always 0 */ - uint32_t flags; /**< bit masks as defined below */ + uint32_t reserved_2; ///< reserved, currently always 0 + uint32_t flags; ///< see ::PTP_CFG_FLAGS } PTP_CFG_SETTINGS; @@ -5178,27 +6259,39 @@ typedef struct /** - * @brief A structure to used to query the current configurration and capabilities of a PTP port + * @brief Possible values for PTP_CFG_SETTINGS::ann_rcpt_timeout + */ +enum PTP_ANN_RCPT_TIMEOUT_LIMITS +{ + PTP_ANN_RCPT_TIMEOUT_MIN = 2, + PTP_ANN_RCPT_TIMEOUT_MAX = 255, + DEFAULT_PTP_ANN_RCPT_TIMEOUT = 3 +}; + + + +/** + * @brief A structure to used to query the current configuration and capabilities of a PTP port */ typedef struct { - PTP_CFG_SETTINGS settings; /**< the current configuration */ + PTP_CFG_SETTINGS settings; ///< the current configuration - uint8_t ptp_proto_version; /**< PTP protocol version, 1, or 2, usually 2 for v2 */ - uint8_t reserved_1; /**< reserved, currently always 0 */ - uint16_t reserved_2; /**< reserved, currently always 0 */ + uint8_t ptp_proto_version; ///< PTP protocol version, 1, or 2, usually 2 for v2 + uint8_t reserved_1; ///< reserved, currently always 0 + uint16_t reserved_2; ///< reserved, currently always 0 - int16_t sync_intv_min; /**< log2 of minimum sync interval [s] */ - int16_t sync_intv_max; /**< log2 of maximum sync interval [s] */ - int16_t ann_intv_min; /**< log2 of minimum announce interval [s] */ - int16_t ann_intv_max; /**< log2 of maximum announce interval [s] */ - int16_t delay_req_intv_min; /**< log2 of minimum delay request interval [s] */ - int16_t delay_req_intv_max; /**< log2 of maximum delay request interval [s] */ + int16_t sync_intv_min; ///< log2 of minimum sync interval [s] + int16_t sync_intv_max; ///< log2 of maximum sync interval [s] + int16_t ann_intv_min; ///< log2 of minimum announce interval [s] + int16_t ann_intv_max; ///< log2 of maximum announce interval [s] + int16_t delay_req_intv_min; ///< log2 of minimum delay request interval [s] + int16_t delay_req_intv_max; ///< log2 of maximum delay request interval [s] - uint32_t supp_flags; /**< a bit mask of supported features (see below) */ - uint32_t supp_nw_prot; /**< a bit mask of supported network protocols */ - uint32_t supp_profiles; /**< a bit mask of supported profiles */ - uint32_t supp_delay_mech; /**< a bit mask of supported delay mechanisms */ + uint32_t supp_flags; ///< a bit mask of supported features, see ::PTP_CFG_FLAGS + 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; @@ -5222,28 +6315,53 @@ typedef struct /** * @brief Flags used with PTP_CFG_SETTINGS::flags and PTP_CFG_INFO::supp_flags - */ -enum -{ - PTP_CFG_BIT_TIME_SCALE_IS_PTP, /**< time scale is PTP/TAI, else arbitrary */ - PTP_CFG_BIT_V1_HW_COMPAT, /**< maybe required for certain NIC chips, not used by Meinberg */ - PTP_CFG_BIT_CAN_BE_UNICAST_SLAVE, /**< the PTP port can take the role of a unicast slave */ - PTP_CFG_BIT_CAN_BE_MULTICAST_MASTER, /**< the PTP port can take the role of a multicast master */ - PTP_CFG_BIT_CAN_BE_UNICAST_MASTER, /**< the PTP port can take the role of a unicast master */ - N_PTP_CFG_BIT /**< the number of defined bits */ + * + * @see 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_CAN_BE_BOTH_MASTER, ///< the PTP port can take the role of a unicast and multicast master + PTP_CFG_CAN_BE_HYBRID_MASTER, ///< the PTP port can take the role of a hybrid master + PTP_CFG_CAN_BE_HYBRID_SLAVE, ///< the PTP port can take the role of a hybrid slave + PTP_CFG_ONE_STEP_MASTER, ///< the PTP port supports one-step clock in master mode + PTP_CFG_MNGMNT_MSGS_DISB, ///< disable PTP management messages + N_PTP_CFG_FLAGS ///< the number of defined flags }; -#define PTP_CFG_MSK_TIME_SCALE_IS_PTP ( 1UL << PTP_CFG_BIT_TIME_SCALE_IS_PTP ) -#define PTP_CFG_MSK_V1_HW_COMPAT ( 1UL << PTP_CFG_BIT_V1_HW_COMPAT ) -#define PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE ( 1UL << PTP_CFG_BIT_CAN_BE_UNICAST_SLAVE ) -#define PTP_CFG_MSK_CAN_BE_MULTICAST_MASTER ( 1UL << PTP_CFG_BIT_CAN_BE_MULTICAST_MASTER ) -#define PTP_CFG_MSK_CAN_BE_UNICAST_MASTER ( 1UL << PTP_CFG_BIT_CAN_BE_UNICAST_MASTER ) +/** + * @brief Bit masks associated to ::PTP_CFG_FLAGS + */ +enum PTP_CFG_FLAG_MASKS +{ + PTP_CFG_MSK_TIME_SCALE_IS_PTP = ( 1UL << PTP_CFG_TIME_SCALE_IS_PTP ), ///< see ::PTP_CFG_TIME_SCALE_IS_PTP + PTP_CFG_MSK_V1_HW_COMPAT = ( 1UL << PTP_CFG_V1_HW_COMPAT ), ///< see ::PTP_CFG_V1_HW_COMPAT + PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE = ( 1UL << PTP_CFG_CAN_BE_UNICAST_SLAVE ), ///< see ::PTP_CFG_CAN_BE_UNICAST_SLAVE + PTP_CFG_MSK_CAN_BE_MULTICAST_MASTER = ( 1UL << PTP_CFG_CAN_BE_MULTICAST_MASTER ), ///< see ::PTP_CFG_CAN_BE_MULTICAST_MASTER + PTP_CFG_MSK_CAN_BE_UNICAST_MASTER = ( 1UL << PTP_CFG_CAN_BE_UNICAST_MASTER ), ///< see ::PTP_CFG_CAN_BE_UNICAST_MASTER + PTP_CFG_MSK_CAN_BE_MULTICAST_AUTO = ( 1UL << PTP_CFG_CAN_BE_MULTICAST_AUTO ), ///< see ::PTP_CFG_CAN_BE_MULTICAST_AUTO + PTP_CFG_MSK_SUPP_UTC_VALID = ( 1UL << PTP_CFG_SUPP_UTC_VALID ), ///< see ::PTP_CFG_SUPP_UTC_VALID + PTP_CFG_MSK_CAN_BE_BOTH_MASTER = ( 1UL << PTP_CFG_CAN_BE_BOTH_MASTER ), ///< see ::PTP_CFG_CAN_BE_BOTH_MASTER + PTP_CFG_MSK_CAN_BE_HYBRID_MASTER = ( 1UL << PTP_CFG_CAN_BE_HYBRID_MASTER ), ///< see ::PTP_CFG_CAN_BE_HYBRID_MASTER + PTP_CFG_MSK_CAN_BE_HYBRID_SLAVE = ( 1UL << PTP_CFG_CAN_BE_HYBRID_SLAVE ), ///< see ::PTP_CFG_CAN_BE_HYBRID_SLAVE + PTP_CFG_MSK_ONE_STEP_MASTER = ( 1UL << PTP_CFG_ONE_STEP_MASTER ), ///< see ::PTP_CFG_ONE_STEP_MASTER + PTP_CFG_MSK_MNGMNT_MSGS_DISB = ( 1UL << PTP_CFG_MNGMNT_MSGS_DISB ) ///< see ::PTP_CFG_MNGMNT_MSGS_DISB +}; +/** @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_UNICAST_MASTER | \ + PTP_CFG_MSK_CAN_BE_MULTICAST_AUTO ) +/** @brief A bit mask of the unicast role bits within the flag bits */ #define PTP_CFG_MSK_SUPPORT_PTP_UNICAST ( PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE | \ PTP_CFG_MSK_CAN_BE_UNICAST_MASTER ) @@ -5258,8 +6376,125 @@ enum * a bit mask which according to the enumerated roles. */ #define _get_supp_ptp_role_idx_msk( _f ) \ - ( 1UL | ( ( (_f) & PTP_CFG_MSK_SUPPORT_PTP_ROLES ) >> ( PTP_CFG_BIT_CAN_BE_UNICAST_SLAVE - 1 ) ) ) -//##+++++++++ #define _get_supp_ptp_roles( _r ) ((((_r) & ~3UL) >> PTP_CFG_BIT_V1_HW_COMPAT ) | 1UL) + ( 1UL | ( ( (_f) & PTP_CFG_MSK_SUPPORT_PTP_ROLES ) >> ( PTP_CFG_CAN_BE_UNICAST_SLAVE - 1 ) ) ) + + + +/** + * @brief Known optional PTP protocol extensions, see ::PTP_CFG_SETTINGS::opt_ext + * + * @see PTP_PROFILE_STRS + * @see PTP_OPT_EXT_MASKS + */ +enum PTP_OPT_EXTS +{ + PTP_OPT_EXT_NONE, ///< no extension used + PTP_OPT_EXT_POWER, ///< IEEE C37.238 profile extension + PTP_OPT_EXT_TELECOM, ///< ITU-T G.8265.1 profile extension + N_PTP_OPT_EXT ///< number of known optional extension +}; + + +/** + * @brief Flag masks used with PTP_CFG_INFO::supp_opt_ext + * + * @see PTP_OPT_EXTS + */ +enum PTP_OPT_EXT_MASKS +{ + // no bit mask is used for PTP_OPT_EXT_NONE, so bit 0 corresponds to + 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 +}; + + + +#if !defined( USE_NEW_PTP_PRESETS ) + //##++++ by default use definitions in ptp2_cnf.h for now + #define USE_NEW_PTP_PRESETS 1 +#endif + +#if USE_NEW_PTP_PRESETS + +/** + * @brief Enumeration of PTP configuration presets + * + * This can be used by configuration programs + * + * @see PTP_PRESETS_STRS + * @see PTP_PRESETS_MASKS + */ +enum PTP_PRESETS +{ + PTP_PRESETS_CUSTOM, ///< customizable, always supported + PTP_PRESETS_DFLT_E2E, ///< pure IEEE1588-2008 (PTPv2) with E2E + PTP_PRESETS_DFLT_P2P, ///< pure IEEE1588-2008 (PTPv2) with P2P + PTP_PRESETS_POWER, ///< IEEE C37.238 profile extension, only if ::PTP_MSK_OPT_EXT_POWER is set + PTP_PRESETS_TELECOM, ///< ITU-T G.8265.1 profile extension, only if ::PTP_MSK_OPT_EXT_TELECOM is set + N_PTP_PRESETS ///< number of supported profiles +}; + + +/** + * @brief Flags used with PTP_CFG_SETTINGS::profile and PTP_CFG_INFO::supp_profiles + * + * @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 +}; + + +/** + * @brief Name strings for defined PTP profiles + * + * @see PTP_PRESETS + */ +#define PTP_PRESETS_STRS \ +{ \ + "Custom", \ + "Default E2E", \ + "Default P2P", \ + "Power", \ + "Telecom" \ +} + +#endif // USE_NEW_PTP_PRESETS + + + +/** + * @brief Additional parameters for Power Profile + */ +#define PTP_POWER_PROFILE_GM_ID_MIN 3 +#define PTP_POWER_PROFILE_GM_ID_MAX 255 + +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 reserved_1; + uint16_t reserved_2; + TZDL tzdl; + +} PTP_POWER_PROFILE_CFG; + +#define _mbg_swab_ptp_power_profile_cfg( _p ) \ +{ \ + _mbg_swab32( &(_p)->network_incaccuracy ); \ + _mbg_swab8( &(_p)->grandmaster_id ); \ + _mbg_swab8( &(_p)->reserved_1 ); \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab_tzdl( &(_p)->tzdl ); \ + _mbg_swab32( &(_p)->flags ); \ +} + /** @@ -5277,16 +6512,16 @@ typedef char MBG_HOSTNAME[256]; */ typedef struct { - uint16_t n_supp_master; /**< number of unicast masters which can be specified */ - int16_t sync_intv_min; /**< log2 of minimum sync interval [s] */ - int16_t sync_intv_max; /**< log2 of maximum sync interval [s] */ - int16_t ann_intv_min; /**< log2 of minimum announce interval [s] */ - int16_t ann_intv_max; /**< log2 of maximum announce interval [s] */ - int16_t delay_req_intv_min; /**< log2 of minimum delay request interval [s] */ - int16_t delay_req_intv_max; /**< log2 of maximum delay request interval [s] */ - uint16_t reserved_0; /**< reserved, currently always 0 */ - uint32_t supp_flags; /**< a bit mask indicating which flags are supported */ - uint32_t reserved_1; /**< reserved, currently always 0 */ + uint16_t n_supp_master; ///< number of unicast masters which can be specified + int16_t sync_intv_min; ///< log2 of minimum sync interval [s] + int16_t sync_intv_max; ///< log2 of maximum sync interval [s] + int16_t ann_intv_min; ///< log2 of minimum announce interval [s] + int16_t ann_intv_max; ///< log2 of maximum announce interval [s] + int16_t delay_req_intv_min; ///< log2 of minimum delay request interval [s] + int16_t delay_req_intv_max; ///< log2 of maximum delay request interval [s] + uint16_t reserved_0; ///< reserved, currently always 0 + uint32_t supp_flags; ///< a bit mask indicating which flags are supported + uint32_t reserved_1; ///< reserved, currently always 0 } PTP_UC_MASTER_CFG_LIMITS; @@ -5306,26 +6541,29 @@ typedef struct /** - * @brief Specification of unicast masters + * @brief Configuration settings specifiying how to query a PTP unicast master * * This structure is used on a unicast slave to specify the settings of * a unicast master polled by the slave. The number of unicast masters * which can be specified depends on the capabilities of the slave device * and is returned in PTP_UC_MASTER_CFG_LIMITS::n_supp_master. + * + * The structure ::PTP_UC_MASTER_SETTINGS_IDX should be sent to the device + * to save the configuration. */ typedef struct { - MBG_HOSTNAME gm_host; /**< grandmaster's hostname or IP address */ - PTP_CLOCK_ID gm_clock_id; /**< use clock ID of master port, or PTP_CLOCK_ID_WILDCARD */ - PTP_PORT_ID gm_port_id; /**< use target port ID of master port (e.g. 135) or PTP_PORT_ID_WILDCARD */ - int16_t sync_intv; /**< sync interval [log2 s] */ - int16_t ann_intv; /**< announce interval [log2 s] */ - int16_t delay_req_intv; /**< delay request interval [log2 s]*/ - int32_t fix_offset; /**< constant time offset to be compensated [ns] */ - uint16_t message_duration; /**< time period until master stops sending messages [s] */ - uint16_t reserved_0; /**< reserved, currently always 0 */ - uint32_t reserved_1; /**< reserved, currently always 0 */ - uint32_t flags; /**< bit masks as specified below */ + MBG_HOSTNAME gm_host; ///< grandmaster's hostname or IP address + PTP_CLOCK_ID gm_clock_id; ///< use clock ID of master port, or ::PTP_CLOCK_ID_WILDCARD + PTP_PORT_ID gm_port_id; ///< use target port ID of master port (e.g. 135) or ::PTP_PORT_ID_WILDCARD + int16_t sync_intv; ///< sync interval [log2 s] + int16_t ann_intv; ///< announce interval [log2 s] + int16_t delay_req_intv; ///< delay request interval [log2 s] + int32_t fix_offset; ///< constant time offset to be compensated [ns] + uint16_t message_duration; ///< time period until master stops sending messages [s] + uint16_t reserved_0; ///< reserved, currently always 0 + uint32_t reserved_1; ///< reserved, currently always 0 + uint32_t flags; ///< reserved, currently always 0 } PTP_UC_MASTER_SETTINGS; @@ -5345,12 +6583,31 @@ typedef struct /** - * @brief Specification of a certain unicast master + * @brief Unicast PTP master message duration limits + * + * Each unicast PTP master sends messages to a unicast slave only + * for a given interval as requested by the particular slave, which + * is called message duration. + * These symbols define the minimum and maximum message duration + * configured on a slave for a specific unicast master, i.e. for + * PTP_UC_MASTER_SETTINGS::message_duration. The values are defined + * in the PTP v2 standard. + */ +enum PTP_UC_MSG_DURATION_LIMITS +{ + PTP_UC_MSG_DURATION_MIN = 10, ///< minimum message duration [s] + PTP_UC_MSG_DURATION_MAX = 1000 ///< maximum message duration [s] +}; + + + +/** + * @brief Configuration settings for a specific PTP unicast master */ typedef struct { - uint32_t idx; /**< index, 0..(PTP_UC_MASTER_CFG_LIMITS::n_supp_master - 1) */ - PTP_UC_MASTER_SETTINGS settings; /**< specification for the unicast master with that index */ + uint32_t idx; ///< index, 0..PTP_UC_MASTER_CFG_LIMITS::n_supp_master - 1 + PTP_UC_MASTER_SETTINGS settings; ///< specification for the unicast master with that index } PTP_UC_MASTER_SETTINGS_IDX; @@ -5362,13 +6619,16 @@ typedef struct /** - * @brief Capabilities and current settings of a unicast master + * @brief Current settings and general capabilities of a unicast master + * + * This structure is used with a PTP unicast slave device to specify + * a PTP unicast master which can be queried by the slave device. */ typedef struct { - PTP_UC_MASTER_SETTINGS settings; /**< current settings */ - uint32_t reserved; /**< reserved, currently always 0 */ - uint32_t flags; /**< reserved, currently always 0 */ + PTP_UC_MASTER_SETTINGS settings; ///< current settings + uint32_t reserved; ///< reserved, currently always 0 + uint32_t flags; ///< reserved, currently always 0 } PTP_UC_MASTER_INFO; @@ -5381,12 +6641,22 @@ typedef struct /** - * @brief Capabilities and current settings of a specific unicast master + * @brief Current settings and general capabilities of a specific unicast master + * + * This structure is used with a PTP unicast slave device to specify + * a PTP unicast master which can be queried by the slave device. + * + * This structure should be read from the device to retrieve the + * current settings and capabilities. The number of supported + * configuration records is PTP_UC_MASTER_CFG_LIMITS::n_supp_master. + * + * @note The ::PTP_UC_MASTER_SETTINGS_IDX structure should be send back + * to the device to save the configuration. */ typedef struct { - uint32_t idx; /**< index, 0..(PTP_UC_MASTER_CFG_LIMITS::n_supp_master - 1) */ - PTP_UC_MASTER_INFO info; /**< capabilities and current settings */ + uint32_t idx; ///< index, 0..PTP_UC_MASTER_CFG_LIMITS::n_supp_master - 1 + PTP_UC_MASTER_INFO info; ///< capabilities and current settings } PTP_UC_MASTER_INFO_IDX; @@ -5400,114 +6670,202 @@ typedef struct /** @} group_ptp */ +/** + * @defgroup group_lno Definitions used with LNO devices + * + * @{ */ -/*------------------------------------------------------------------------*/ +#define MAX_LNO_OUTPUT 4 + +/** + * @brief LNO status + */ +typedef struct +{ + uint16_t sine_lvl[MAX_LNO_OUTPUT]; ///< signal levels at the outputs + + uint16_t max_sine_lvl; ///< max level of an output, e.g. 1024 + uint8_t n_outputs; ///< actual number of outputs [0..::MAX_LNO_OUTPUT-1] + uint8_t out_enb_state; ///< e.g. bit 0 is set if corresponding output 0 is enabled, etc. + + uint16_t reserved_0; ///< reserved, currently always 0 + uint16_t flags; ///< status flags, see ::LNO_STATE_FLAG_BITS + +} LNO_STATE; + +#define _mbg_swab_lno_state( _p ) \ +{ \ + int i; \ + \ + for ( i = 0; i < MAX_LNO_OUTPUT; i++ ) \ + _mbg_swab16( &(_p)->sine_lvl[i] ); \ + \ + _mbg_swab_16( &(_p)->max_sine_lvl ); \ + _mbg_swab_16( &(_p)->reserved_0 ); \ + _mbg_swab_16( &(_p)->flags ); \ +} + + +/** + * @brief Flags used with LNO_STATE::flags + */ +enum LNO_STATE_FLAG_BITS +{ + LNO_FLAG_BIT_PLL_LOCKED, ///< PLL is locked + N_LNO_FLAG_BIT ///< number of known bits +}; + +#define LNO_FLAG_PLL_LOCKED ( 1UL << LNO_FLAG_BIT_PLL_LOCKED ) + +/** @} group_lno */ -/* Ephemeris parameters of one specific SV. Needed to compute the position */ -/* of a satellite at a given time with high precision. Valid for an */ -/* interval of 4 to 6 hours from start of transmission. */ +/*------------------------------------------------------------------------*/ + +/** + * @brief Ephemeris parameters of one specific satellite + * + * Needed to compute the position of a satellite at a given time with + * high precision. Valid for an interval of 4 to 6 hours from start + * of transmission. + */ typedef struct { - CSUM csum; /* checksum of the remaining bytes */ - int16_t valid; /* flag data are valid */ - - HEALTH health; /* health indication of transmitting SV [---] */ - IOD IODC; /* Issue Of Data, Clock */ - IOD IODE2; /* Issue of Data, Ephemeris (Subframe 2) */ - IOD IODE3; /* Issue of Data, Ephemeris (Subframe 3) */ - T_GPS tt; /* time of transmission */ - T_GPS t0c; /* Reference Time Clock [---] */ - T_GPS t0e; /* Reference Time Ephemeris [---] */ - - double sqrt_A; /* Square Root of semi-major Axis [sqrt(m)] */ - double e; /* Eccentricity [---] */ - double M0; /* +- Mean Anomaly at Ref. Time [rad] */ - double omega; /* +- Argument of Perigee [rad] */ - double OMEGA0; /* +- Longit. of Asc. Node of orbit plane [rad] */ - double OMEGADOT; /* +- Rate of Right Ascension [rad/sec] */ - double deltan; /* +- Mean Motion Diff. from computed value [rad/sec] */ - double i0; /* +- Inclination Angle [rad] */ - double idot; /* +- Rate of Inclination Angle [rad/sec] */ - double crc; /* +- Cosine Corr. Term to Orbit Radius [m] */ - double crs; /* +- Sine Corr. Term to Orbit Radius [m] */ - double cuc; /* +- Cosine Corr. Term to Arg. of Latitude [rad] */ - double cus; /* +- Sine Corr. Term to Arg. of Latitude [rad] */ - double cic; /* +- Cosine Corr. Term to Inclination Angle [rad] */ - double cis; /* +- Sine Corr. Term to Inclination Angle [rad] */ - - double af0; /* +- Clock Correction Coefficient 0 [sec] */ - double af1; /* +- Clock Correction Coefficient 1 [sec/sec] */ - double af2; /* +- Clock Correction Coefficient 2 [sec/sec^2] */ - double tgd; /* +- estimated group delay differential [sec] */ - - uint16_t URA; /* predicted User Range Accuracy */ - - uint8_t L2code; /* code on L2 channel [---] */ - uint8_t L2flag; /* L2 P data flag [---] */ + CSUM csum; ///< checksum of the remaining bytes + int16_t valid; ///< flag data are valid + + HEALTH health; ///< health indication of transmitting SV [---] + IOD IODC; ///< Issue Of Data, Clock + IOD IODE2; ///< Issue of Data, Ephemeris (Subframe 2) + IOD IODE3; ///< Issue of Data, Ephemeris (Subframe 3) + T_GPS tt; ///< time of transmission + T_GPS t0c; ///< Reference Time Clock [---] + T_GPS t0e; ///< Reference Time Ephemeris [---] + + double sqrt_A; ///< Square Root of semi-major Axis [sqrt(m)] + double e; ///< Eccentricity [---] + double M0; ///< +- Mean Anomaly at Ref. Time [rad] + double omega; ///< +- Argument of Perigee [rad] + double OMEGA0; ///< +- Longit. of Asc. Node of orbit plane [rad] + double OMEGADOT; ///< +- Rate of Right Ascension [rad/sec] + double deltan; ///< +- Mean Motion Diff. from computed value [rad/sec] + double i0; ///< +- Inclination Angle [rad] + double idot; ///< +- Rate of Inclination Angle [rad/sec] + double crc; ///< +- Cosine Corr. Term to Orbit Radius [m] + double crs; ///< +- Sine Corr. Term to Orbit Radius [m] + double cuc; ///< +- Cosine Corr. Term to Arg. of Latitude [rad] + double cus; ///< +- Sine Corr. Term to Arg. of Latitude [rad] + double cic; ///< +- Cosine Corr. Term to Inclination Angle [rad] + double cis; ///< +- Sine Corr. Term to Inclination Angle [rad] + + double af0; ///< +- Clock Correction Coefficient 0 [sec] + double af1; ///< +- Clock Correction Coefficient 1 [sec/sec] + double af2; ///< +- Clock Correction Coefficient 2 [sec/sec^2] + double tgd; ///< +- estimated group delay differential [sec] + + uint16_t URA; ///< predicted User Range Accuracy + + uint8_t L2code; ///< code on L2 channel [---] + uint8_t L2flag; ///< L2 P data flag [---] } EPH; -/* Almanac parameters of one specific SV. A reduced precision set of */ -/* parameters used to check if a satellite is in view at a given time. */ -/* Valid for an interval of more than 7 days from start of transmission. */ - +/** + * @brief Almanac parameters of one specific satellite + * + * A reduced precision set of parameters used to check if a satellite + * is in view at a given time. Valid for an interval of more than 7 days + * from start of transmission. + */ typedef struct { - CSUM csum; /* checksum of the remaining bytes */ - int16_t valid; /* flag data are valid */ + CSUM csum; ///< checksum of the remaining bytes + int16_t valid; ///< flag data are valid - HEALTH health; /* [---] */ - T_GPS t0a; /* Reference Time Almanac [sec] */ + HEALTH health; ///< [---] + T_GPS t0a; ///< Reference Time Almanac [sec] - double sqrt_A; /* Square Root of semi-major Axis [sqrt(m)] */ - double e; /* Eccentricity [---] */ + double sqrt_A; ///< Square Root of semi-major Axis [sqrt(m)] + double e; ///< Eccentricity [---] - double M0; /* +- Mean Anomaly at Ref. Time [rad] */ - double omega; /* +- Argument of Perigee [rad] */ - double OMEGA0; /* +- Longit. of Asc. Node of orbit plane [rad] */ - double OMEGADOT; /* +- Rate of Right Ascension [rad/sec] */ - double deltai; /* +- [rad] */ - double af0; /* +- Clock Correction Coefficient 0 [sec] */ - double af1; /* +- Clock Correction Coefficient 1 [sec/sec] */ + double M0; ///< +- Mean Anomaly at Ref. Time [rad] + double omega; ///< +- Argument of Perigee [rad] + double OMEGA0; ///< +- Longit. of Asc. Node of orbit plane [rad] + double OMEGADOT; ///< +- Rate of Right Ascension [rad/sec] + double deltai; ///< +- [rad] + double af0; ///< +- Clock Correction Coefficient 0 [sec] + double af1; ///< +- Clock Correction Coefficient 1 [sec/sec] } ALM; -/* Summary of configuration and health data of all SVs. */ - +/** + * @brief Summary of configuration and health data of all satellites + */ typedef struct { - CSUM csum; /* checksum of the remaining bytes */ - int16_t valid; /* flag data are valid */ + CSUM csum; ///< checksum of the remaining bytes + int16_t valid; ///< flag data are valid - T_GPS tot_51; /* time of transmission, page 51 */ - T_GPS tot_63; /* time of transmission, page 63 */ - T_GPS t0a; /* complete reference time almanac */ + T_GPS tot_51; ///< time of transmission, page 51 + T_GPS tot_63; ///< time of transmission, page 63 + T_GPS t0a; ///< complete reference time almanac - CFG cfg[N_SVNO]; /* SV configuration from page 63 */ - HEALTH health[N_SVNO]; /* SV health from pages 51, 63 */ + CFG cfg[N_SVNO]; ///< SV configuration from page 63 + HEALTH health[N_SVNO]; ///< SV health from pages 51, 63 } CFGH; /** - * @brief GPS UTC correction parameters + * @brief GPS %UTC correction parameters + * + * %UTC correction parameters basically as sent by the GPS satellites. + * + * The csum field is only used by the card's firmware to check the + * consistency of the structure in non-volatile memory. + * + * The field labeled valid indicates if the parameter set is valid, i.e. + * if it contains data received from the satellites. + * + * t0t, A0 and A1 contain fractional correction parameters for the current + * GPS-%UTC time offset in addition to the whole seconds. This is evaluated + * by the receivers' firmware to convert GPS time to %UTC time. + * + * The delta_tls field contains the current full seconds offset between + * GPS time and %UTC, which corresponds to the number of leap seconds inserted + * into the %UTC time scale since GPS was put into operation in January 1980. + * + * delta_tlfs holds the number of "future" leap seconds, i.e. the %UTC offset + * after the next leap second event defined by WNlsf and DNt. + * + * The fields WNlsf and DNt specify the GPS week number and the day number + * in that week at the end of which a leap second is 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. + * 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. */ typedef struct { - CSUM csum; /**< Checksum of the remaining bytes */ - int16_t valid; /**< Flag indicating UTC parameters are valid */ + CSUM csum; ///< Checksum of the remaining bytes + int16_t valid; ///< Flag indicating %UTC parameters are valid - T_GPS t0t; /**< Reference Time UTC Parameters [wn|sec] */ - double A0; /**< +- Clock Correction Coefficient 0 [sec] */ - double A1; /**< +- Clock Correction Coefficient 1 [sec/sec] */ + T_GPS t0t; ///< Reference Time %UTC Parameters [wn|sec] + double A0; ///< +- Clock Correction Coefficient 0 [sec] + double A1; ///< +- Clock Correction Coefficient 1 [sec/sec] - uint16_t WNlsf; /**< Week number of nearest leap second */ - int16_t DNt; /**< The day number at the end of which a leap second occurs */ - int8_t delta_tls; /**< Current UTC offset to GPS system time [sec] */ - int8_t delta_tlsf; /**< Future UTC offset to GPS system time after next leap second transition [sec] */ + uint16_t WNlsf; ///< Week number of nearest leap second + int16_t DNt; ///< The day number at the end of which a leap second occurs + int8_t delta_tls; ///< Current %UTC offset to GPS system time [sec] + int8_t delta_tlsf; ///< Future %UTC offset to GPS system time after next leap second transition [sec] } UTC; #define _mbg_swab_utc_parm( _p ) \ @@ -5523,38 +6881,40 @@ typedef struct -/* Ionospheric correction parameters */ - +/** + * @brief Ionospheric correction parameters + */ typedef struct { - CSUM csum; /* checksum of the remaining bytes */ - int16_t valid; /* flag data are valid */ + CSUM csum; ///< checksum of the remaining bytes + int16_t valid; ///< flag data are valid - double alpha_0; /* Ionosph. Corr. Coeff. Alpha 0 [sec] */ - double alpha_1; /* Ionosph. Corr. Coeff. Alpha 1 [sec/deg] */ - double alpha_2; /* Ionosph. Corr. Coeff. Alpha 2 [sec/deg^2] */ - double alpha_3; /* Ionosph. Corr. Coeff. Alpha 3 [sec/deg^3] */ + double alpha_0; ///< Ionosph. Corr. Coeff. Alpha 0 [sec] + double alpha_1; ///< Ionosph. Corr. Coeff. Alpha 1 [sec/deg] + double alpha_2; ///< Ionosph. Corr. Coeff. Alpha 2 [sec/deg^2] + double alpha_3; ///< Ionosph. Corr. Coeff. Alpha 3 [sec/deg^3] - double beta_0; /* Ionosph. Corr. Coeff. Beta 0 [sec] */ - double beta_1; /* Ionosph. Corr. Coeff. Beta 1 [sec/deg] */ - double beta_2; /* Ionosph. Corr. Coeff. Beta 2 [sec/deg^2] */ - double beta_3; /* Ionosph. Corr. Coeff. Beta 3 [sec/deg^3] */ + double beta_0; ///< Ionosph. Corr. Coeff. Beta 0 [sec] + double beta_1; ///< Ionosph. Corr. Coeff. Beta 1 [sec/deg] + double beta_2; ///< Ionosph. Corr. Coeff. Beta 2 [sec/deg^2] + double beta_3; ///< Ionosph. Corr. Coeff. Beta 3 [sec/deg^3] } IONO; -/* GPS ASCII message */ - +/** + * @brief GPS ASCII message + */ typedef struct { - CSUM csum; /* checksum of the remaining bytes */ - int16_t valid; /* flag data are valid */ - char s[23]; /* 22 chars GPS ASCII message plus trailing zero */ + CSUM csum; ///< checksum of the remaining bytes */ + int16_t valid; ///< flag data are valid + char s[23]; ///< 22 chars GPS ASCII message plus trailing zero } ASCII_MSG; -enum +enum GPS_PLATFORMS { GPS_PLATFORM_PORTABLE, GPS_PLATFORM_FIXED, @@ -5584,11 +6944,12 @@ enum -enum +enum TIME_MODES { TIME_MODE_DISABLED, TIME_MODE_SURVEY_IN, - TIME_MODE_FIXED + TIME_MODE_FIXED, + N_TIME_MODES }; @@ -5608,9 +6969,9 @@ typedef struct /** - Navigation Engine settings to set configuration - parameters of a dynamic platform model. -*/ + * Navigation Engine settings to set configuration + * parameters of a dynamic platform model. + */ typedef struct { uint8_t dynamic_platform; diff --git a/mbglib/common/gpsutils.c b/mbglib/common/gpsutils.c index f493af9..c5083ef 100755 --- a/mbglib/common/gpsutils.c +++ b/mbglib/common/gpsutils.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: gpsutils.c 1.4.1.3 2010/07/15 13:33:43 martin TEST $ + * $Id: gpsutils.c 1.9 2013/01/30 16:10:08 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,12 +10,18 @@ * * ----------------------------------------------------------------------- * $Log: gpsutils.c $ - * Revision 1.4.1.3 2010/07/15 13:33:43 martin + * Revision 1.9 2013/01/30 16:10:08 martin + * Exclude some code from compiling by default, and + * thus don't require pcpslstr.h by default. + * Revision 1.8 2012/10/15 14:27:05Z martin + * Exclude sprint_fixed_freq() from build except for Borland C / Windows. + * Revision 1.7 2010/07/15 09:32:09 martin * Use DEG character definition from pcpslstr.h. - * Revision 1.4.1.2 2004/11/09 14:42:36Z martin - * Use C99 fixed-size types in swap_double(). - * Revision 1.4.1.1 2003/05/16 08:36:27 MARTIN - * Fixed sprint_dms() to work correctly under QNX. + * Revision 1.6 2004/12/28 11:21:26Z martin + * Omit trap if fixed_freq is 0. + * Use C99 fixed-size data types were required. + * Revision 1.5 2003/02/04 09:20:04Z MARTIN + * New functions sprint_alt(), sprint_fixed_freq(). * Revision 1.4 2003/01/31 13:45:19 MARTIN * sprint_pos_geo() returns N/A if position not valid. * Revision 1.3 2002/12/12 16:07:04 martin @@ -32,11 +38,17 @@ #include <gpsutils.h> #undef _GPSUTILS -#include <pcpslstr.h> +#if !defined( USE_SPRINTF ) + #define USE_SPRINTF 0 +#endif + +#if USE_SPRINTF + #include <pcpslstr.h> +#endif #include <stdio.h> #include <string.h> - +#include <math.h> #define _eos( _s ) ( &(_s)[strlen( _s )] ) @@ -159,6 +171,8 @@ void swap_pos_doubles( POS *posp ) +#if USE_SPRINTF + /*HDR*/ void sprint_dms( char *s, DMS *pdms, int prec ) { @@ -175,6 +189,15 @@ void sprint_dms( char *s, DMS *pdms, int prec ) /*HDR*/ +void sprint_alt( char *s, double alt ) +{ + sprintf( s, "%.0fm", alt ); + +} /* sprint_dms */ + + + +/*HDR*/ void sprint_pos_geo( char *s, POS *ppos, const char *sep, int prec ) { if ( ppos->lla[LON] && ppos->lla[LAT] && ppos->lla[ALT] ) @@ -183,12 +206,111 @@ void sprint_pos_geo( char *s, POS *ppos, const char *sep, int prec ) strcat( s, sep ); sprint_dms( _eos( s ), &ppos->longitude, prec ); strcat( s, sep ); - sprintf( _eos( s ), "%.0fm", ppos->lla[ALT] ); + sprint_alt( _eos( s ), ppos->lla[ALT] ); } else strcpy( s, "N/A" ); } /* sprint_pos_geo */ +#endif + + + +#if defined( MBG_TGT_WIN32 ) && defined( __BORLANDC__ ) + +/*HDR*/ +void sprint_fixed_freq( char *s, FIXED_FREQ_INFO *p_ff ) +{ + double freq; + int range; + ushort unit; + ushort format; + + // Before re-calculating frequency, range is the base 10 exponent + // to the frequency value which is represented in kHz. + // After calculating range from real frequency, range is represented + // as follows: + // range display format divisor format index calculation + // -3 100mHz 1.000 [/1e-3] -3 % 3 = -3 + 3 = 0 % 3 = 0 + // -2 100mHz 10.00 [/1e-3] -2 % 3 = -2 + 3 = 1 % 3 = 1 + // -1 100mHz 100.0 [/1e-3] -1 % 3 = -1 + 3 = 2 % 3 = 2 + // 0 1Hz 1.000 [/1e0] 0 % 3 = 0 + 3 = 3 % 3 = 0 + // 1 10Hz 10.00 [/1e0] 1 % 3 = 1 + 3 = 1 % 3 = 1 + // 2 100Hz 100.0 [/1e0] 2 % 3 = 2 + 3 = 2 % 3 = 2 + // 3 1kHz 1.000 [/1e3] 3 % 3 = 0 + 3 = 3 % 3 = 0 + // 4 10kHz 10.00 [/1e3] 4 % 3 = 1 + 3 = 4 % 3 = 1 + // 5 100kHz 100.0 [/1e3] 5 % 3 = 2 + 3 = 5 % 3 = 2 + // 6 1MHz 1.000 [/1e6] 6 % 3 = 0 + 3 = 3 % 3 = 0 + // 7 10MHz 10.00 [/1e6] 7 % 3 = 1 + 3 = 4 % 3 = 1 + // 8 100MHz 100.0 [/1e6] 8 % 3 = 2 + 3 = 5 % 3 = 2 + + // format string for fp output + static const char *fmt_str[] = + { + "%4.3lf%s", + "%4.2lf%s", + "%4.1lf%s", + }; + + // Unit index and divisor are calculated as follows: + // range unit index calculation divisor calculation + // -3 mHz ( int )( ( -3 + 3 ) / 3 ) = 0 + // -2 mHz ( int )( ( -2 + 3 ) / 3 ) = 0 + // -1 mHz ( int )( ( -1 + 3 ) / 3 ) = 0 / 10e-3 = 10e( 3 * 0 - 3 ) + // 0 Hz ( int )( ( 0 + 3 ) / 3 ) = 1 + // 1 Hz ( int )( ( 1 + 3 ) / 3 ) = 1 + // 2 Hz ( int )( ( 2 + 3 ) / 3 ) = 1 / 1e0 = 10e( 3 * 1 - 3 ) + // 3 kHz ( int )( ( 3 + 3 ) / 3 ) = 2 + // 4 kHz ( int )( ( 4 + 3 ) / 3 ) = 2 + // 5 kHz ( int )( ( 5 + 3 ) / 3 ) = 2 / 10e3 = 10e( 3 * 2 - 3 ) + // 6 MHz ( int )( ( 6 + 3 ) / 3 ) = 3 + // 7 MHz ( int )( ( 7 + 3 ) / 3 ) = 3 + // 8 MHz ( int )( ( 8 + 3 ) / 3 ) = 3 / 10e6 =10e( 3 * 3 - 3 ) + + // unit string + static const char *unit_str[] = + { + "mHz", + "Hz", + "kHz", + "MHz" + }; + + + if ( p_ff->khz_val ) + { + // calculate frequency in Hz + freq = ( double ) p_ff->khz_val * pow( 10, ( p_ff->range + 3 ) ); + + // calculate decimal exponent + range = ( ( int ) log10( freq ) ); + + // check whether range is in the allowed range + // if so display frequency in broken format + if ( ( range >= -3 ) && ( range <= 8 ) ) + { + // calculate format index ( see above ) + format = ( ( ( range % 3 ) + 3 ) % 3 ); + + // calculate unit index + unit = ( ushort )( range + 3 ) / 3; + + // calculate display value + freq = freq / pow( 10, ( ( 3 * unit ) - 3 ) ); + sprintf( s, fmt_str[format], freq, unit_str[unit] ); + return; + } + else + { + // out of range display fequency in Hz + sprintf( s, "%lfHz", freq ); + } + } + else + strcpy( s, "N/A" ); + +} /* sprint_fixed_freq */ +#endif // defined( MBG_TGT_WIN32 ) && defined( __BORLANDC__ ) diff --git a/mbglib/common/gpsutils.h b/mbglib/common/gpsutils.h index 8716adf..fdac213 100755 --- a/mbglib/common/gpsutils.h +++ b/mbglib/common/gpsutils.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: gpsutils.h 1.4.1.2 2010/07/15 09:19:04 martin REL_M $ + * $Id: gpsutils.h 1.7 2010/07/15 09:32:09 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,10 +10,12 @@ * * ----------------------------------------------------------------------- * $Log: gpsutils.h $ - * Revision 1.4.1.2 2010/07/15 09:19:04 martin + * Revision 1.7 2010/07/15 09:32:09 martin * Use DEG character definition from pcpslstr.h. - * Revision 1.4.1.1 2003/05/15 09:40:25Z martin - * Changed degree string/char for QNX. + * Revision 1.6 2005/02/18 10:32:33Z martin + * Check more predefined macros to determine if compiling for Windows. + * Revision 1.5 2003/02/04 09:18:48Z MARTIN + * Updated function prototypes. * Revision 1.4 2002/12/12 16:08:11 martin * Definitions for degree character. * Requires mbggeo.h. @@ -62,7 +64,9 @@ extern "C" { void swap_iono_doubles( IONO *ionop ) ; void swap_pos_doubles( POS *posp ) ; void sprint_dms( char *s, DMS *pdms, int prec ) ; + void sprint_alt( char *s, double alt ) ; void sprint_pos_geo( char *s, POS *ppos, const char *sep, int prec ) ; + void sprint_fixed_freq( char *s, FIXED_FREQ_INFO *p_ff ) ; /* ----- function prototypes end ----- */ diff --git a/mbglib/common/lan_util.c b/mbglib/common/lan_util.c index 4e4d82f..bdda51c 100755 --- a/mbglib/common/lan_util.c +++ b/mbglib/common/lan_util.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: lan_util.c 1.1.1.13 2011/09/20 16:14:03 martin TEST martin $ + * $Id: lan_util.c 1.7 2013/05/22 16:49:42 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,32 +10,23 @@ * * ----------------------------------------------------------------------- * $Log: lan_util.c $ - * Revision 1.1.1.13 2011/09/20 16:14:03 martin - * Fix for old Linux ethtool headers. - * Revision 1.1.1.12 2011/09/14 13:50:48 martin - * Rewrote some functions sharing common code. - * Use predefined return values for those functions. - * Renamed some functions to more appropriate names. - * Revision 1.1.1.11 2011/09/08 10:37:36 udo - * Revision 1.1.1.10 2011/08/27 14:26:47 udo - * new get_port_ip4_addr() and get_port_ip4_netm() - * Revision 1.1.1.9 2011/08/27 13:34:57 udo - * new get_port_ip4_addr() and get_port_ip4_netm() - * Revision 1.1.1.8 2011/08/25 20:39:36 martin - * Added new functions to deal with MAC addresses. - * Revision 1.1.1.7 2011/08/09 08:13:19 philipp - * proper return code evaluating - * Revision 1.1.1.6 2011/08/08 16:12:08 martin - * Revision 1.1.1.5 2011/08/08 16:02:28 martin - * Revision 1.1.1.4 2011/08/04 13:46:12 philipp - * Linux implementation of function check_port_link - * which performs a link detection test for a specific, given interface - * Revision 1.1.1.3 2011/06/21 15:23:30 martin - * Fixed build under DOS. - * Revision 1.1.1.2 2011/04/20 16:08:55Z martin - * Revision 1.1.1.1 2011/03/04 10:33:22 martin - * Implemented dummy snprintf() function for environments - * which don't provide this. + * 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 + * checking the result. + * Added conditional debug code. + * Revision 1.5 2013/02/19 15:13:10 martin + * Added some new functions. + * Updated doxygen comments. + * Revision 1.4 2012/11/02 09:16:57 martin + * Fixed build under Windows. + * Revision 1.3 2012/10/02 18:23:28Z martin + * Removed obsolete code to avoid compiler warning. + * Revision 1.2 2012/03/09 08:49:19 martin + * Added some commonly used functions. * Revision 1.1 2011/03/04 10:01:32Z martin * Initial revision. * @@ -67,23 +58,64 @@ #include <linux/sockios.h> #include <linux/ethtool.h> - + #include <linux/rtnetlink.h> #endif - #include <sys/ioctl.h> #include <unistd.h> - #include <netinet/in.h> + #include <sys/ioctl.h> + #include <sys/errno.h> #include <arpa/inet.h> + #include <netinet/in.h> + +#else + + // dummy codes, the functions will report an error ... + #define SIOCGIFADDR 0 + #define SIOCGIFNETMASK 0 + #define SIOCGIFBRDADDR 0 + + #if defined( MBG_TGT_WIN32 ) + #define snprintf _snprintf + #endif + +#endif + +#if !defined( DEBUG_NETLINK ) + #define DEBUG_NETLINK ( 0 && defined( DEBUG ) && defined( MBG_TGT_LINUX ) ) #endif +#if DEBUG_NETLINK + // we need a function to output debugging information + #if !defined STANDALONE + #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, ... ); + #endif +#endif // DEBUG_NETLINK + + + // Maximum size of an IPv4 address string in dotted quad format, // including a terminating 0, and thus the required minimum size // for a buffer to take such a string. i.e. "aaa.bbb.ccc.ddd\0". #define MAX_IP4_ADDR_STR_SIZE 16 +#if defined ( MBG_TGT_LINUX ) + +struct route_info +{ + struct in_addr dstAddr; + struct in_addr srcAddr; + struct in_addr gateWay; + char ifName[IF_NAMESIZE]; +}; + +#endif + #if defined( __BORLANDC__ ) \ && ( __BORLANDC__ <= 0x410 ) // BC3.1 defines 0x410 ! @@ -114,29 +146,64 @@ int snprintf( char *s, size_t max_len, const char *fmt, ... ) /*HDR*/ /** + * @brief Count the number of sequential bits set starting from MSB + * + * E.g. for 0xC0 and 0xC1 the results are both 2 since only + * the 2 MSBs are sequentially set. + * + * @param p_mask The IP4 net mask + * + * @return The number of sequential MSB bits set in val + * + * @see ip4_net_mask_from_cidr + */ +int get_ip4_net_mask_bits( const IP4_ADDR *p_mask ) +{ + IP4_ADDR msb_mask = IP4_MSB_MASK; + int i; + + for ( i = 0; i < MAX_IP4_BITS; i++ ) + { + if ( ( *p_mask & msb_mask ) == 0 ) + break; + + msb_mask >>= 1; + } + + return i; + +} // get_ip4_net_mask_bits + + + +/*HDR*/ +/** * @brief Print an IPv4 address to a dotted quad format string. * * @param s The string buffer into which to print * @param max_len Maximum length of the string, i.e. size of the buffer - * @param addr The IPv4 address + * @param p_addr The IPv4 address * @param info An optional string which is prepended to the string, or NULL * * @return The overall number of characters printed to the string + * + * @see snprint_ip4_cidr_addr + * @see str_to_ip4_addr + * @see cidr_str_to_ip4_addr_and_net_mask */ -int snprint_ip4_addr( char *s, size_t max_len, const IP4_ADDR *addr, const char *info ) +int snprint_ip4_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, const char *info ) { int n = 0; + ulong ul = *p_addr; if ( info ) n += snprintf( 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, "%i.%i.%i.%i", - ( (*addr) >> 24 ) & 0xFF, - ( (*addr) >> 16 ) & 0xFF, - ( (*addr) >> 8 ) & 0xFF, - ( (*addr) ) & 0xFF + n += snprintf( &s[n], max_len - n, "%lu.%lu.%lu.%lu", + BYTE_3( ul ), BYTE_2( ul ), + BYTE_1( ul ), BYTE_0( ul ) ); return n; @@ -146,25 +213,67 @@ int snprint_ip4_addr( char *s, size_t max_len, const IP4_ADDR *addr, const char /*HDR*/ /** + * @brief Print an IPv4 address plus net mask to string in CIDR notation. + * + * The printed CIDR string is something like "172.16.3.250/24" + * + * @param s The string buffer into which to print + * @param max_len Maximum length of the string, i.e. size of the buffer + * @param p_addr The IPv4 address + * @param p_mask The IPv4 net mask + * @param info An optional string which is prepended to the string, or NULL + * + * @return The overall number of characters printed to the string + * + * @see snprint_ip4_addr + * @see str_to_ip4_addr + * @see cidr_str_to_ip4_addr_and_net_mask + */ +int snprint_ip4_cidr_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, + const IP4_ADDR *p_mask, const char *info ) +{ + 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 ); + + 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 ); + + return n; + +} // snprint_ip4_cidr_addr + + + +/*HDR*/ +/** * @brief Convert a string to an IP4_ADDR. * - * @param p 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 p_addr Pointer to the IP4_ADDR variable, or NULL, in which case this + * function can be used to check if the string is formally correct. + * @param s The string to be converted * * @return >= 0 on success, number of characters evaluated from the input string * -1 if invalid number found in string * -2 if separator is not a dot '.' + * + * @see snprint_ip4_addr + * @see snprint_ip4_cidr_addr + * @see cidr_str_to_ip4_addr_and_net_mask */ -int str_to_ip4_addr( IP4_ADDR *p, const char *s ) +int str_to_ip4_addr( IP4_ADDR *p_addr, const char *s ) { IP4_ADDR tmp_ip4_addr = 0; - char *cp; + const char *cp; int i; for ( i = 0, cp = (char *) s; ; ) { - unsigned long ul = strtoul( cp, &cp, 10 ); + unsigned long ul = strtoul( (char *) cp, (char **) &cp, 10 ); if ( ul > 255 ) // invalid number return -1; @@ -180,10 +289,11 @@ int str_to_ip4_addr( IP4_ADDR *p, const char *s ) cp++; // skip dot } - if ( p ) - *p = tmp_ip4_addr; + if ( p_addr ) + *p_addr = tmp_ip4_addr; - return cp - (char *) s; // success + // success: return the number of evaluated chars + return cp - s; } // str_to_ip4_addr @@ -191,6 +301,80 @@ int str_to_ip4_addr( IP4_ADDR *p, 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 + */ +int cidr_str_to_ip4_addr_and_net_mask( IP4_ADDR *p_addr, IP4_ADDR *p_mask, + const char *cidr_str ) +{ + IP4_ADDR mask; + long cidr_mask_bits; + const char *cp; + int l; + int rc = str_to_ip4_addr( p_addr, cidr_str ); + + if ( rc < 0 ) // return current error + return rc; + + + l = strlen( cidr_str ); + + if ( l < rc ) // input string too short + return MBG_LU_ERR_FMT; + + + cp = &cidr_str[rc]; + + 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; + goto done; + } + + + if ( *cp != '/' ) + return MBG_LU_ERR_FMT; + + + cp++; + cidr_mask_bits = strtol( (char *) cp, (char **) &cp, 10 ); + + if ( ( cidr_mask_bits < MIN_IP4_CIDR_NETMASK_BITS ) || + ( cidr_mask_bits > MAX_IP4_CIDR_NETMASK_BITS ) ) + return MBG_LU_ERR_RANGE; + + + mask = ip4_net_mask_from_cidr( (int) cidr_mask_bits ); + +done: + if ( p_mask ) + *p_mask = mask; + + // success: return the number of evaluated chars + return cp - cidr_str; + +} // cidr_str_to_ip4_addr_and_net_mask + + + +/*HDR*/ +/** * @brief Print a MAC ID or similar array of octets to a string. * * @param s The string buffer into which to print @@ -201,6 +385,10 @@ int str_to_ip4_addr( IP4_ADDR *p, const char *s ) * @param info An optional string which is prepended to the output, or NULL * * @return The overall number of characters printed to the string + * + * @see snprint_mac_addr + * @see str_to_octets + * @see check_octets_not_all_zero */ int snprint_octets( char *s, size_t max_len, const uint8_t *octets, int num_octets, char sep, const char *info ) @@ -234,6 +422,10 @@ int snprint_octets( char *s, size_t max_len, const uint8_t *octets, * @param p_mac_addr The MAC address to be printed * * @return The overall number of characters printed to the string + * + * @see snprint_octets + * @see str_to_octets + * @see check_octets_not_all_zero */ int snprint_mac_addr( char *s, size_t max_len, const MBG_MAC_ADDR *p_mac_addr ) { @@ -252,6 +444,10 @@ int snprint_mac_addr( char *s, size_t max_len, const MBG_MAC_ADDR *p_mac_addr ) * @param s The string to be converted * * @return The overall number of octets decoded from the string + * + * @see snprint_octets + * @see snprint_mac_addr + * @see check_octets_not_all_zero */ int str_to_octets( uint8_t *octets, int num_octets, const char *s ) { @@ -288,6 +484,10 @@ int str_to_octets( uint8_t *octets, int num_octets, const char *s ) * * @return MBG_LU_SUCCESS octets are valid, i.e. not all 0 * MBG_LU_ERR_NOT_SET octets are invalid, i.e. all 0 + * + * @see snprint_octets + * @see snprint_mac_addr + * @see str_to_octets */ int check_octets_not_all_zero( const uint8_t *octets, int num_octets ) { @@ -307,6 +507,25 @@ int check_octets_not_all_zero( const uint8_t *octets, int num_octets ) +/*HDR*/ +/** + * @brief Check if an array of octets is valid, i.e. != 0 + * + * @param p_addr Pointer to a MAC address + * + * @return MBG_LU_SUCCESS MAC address is valid, i.e. not all 0 + * MBG_LU_ERR_NOT_SET MAC address is invalid, i.e. all 0 + * + * @see check_octets_not_all_zero + */ +int check_mac_addr_not_all_zero( const MBG_MAC_ADDR *p_addr ) +{ + return check_octets_not_all_zero( p_addr->b, sizeof( p_addr->b ) ); + +} // check_mac_addr_not_all_zero + + + #if defined( MBG_TGT_UNIX ) /*HDR*/ @@ -317,7 +536,7 @@ int check_octets_not_all_zero( const uint8_t *octets, int num_octets ) * @param ioctl_code One of the predefined system SIOCGxxx IOCTL codes * @param p_ifreq Pointer to a request buffer * - * @return one of the MBG_LU_xxx codes + * @return one of the ::MBG_LU_CODES */ int do_siocg_ioctl( const char *if_name, int ioctl_code, struct ifreq *p_ifreq ) { @@ -336,10 +555,16 @@ int do_siocg_ioctl( const char *if_name, int ioctl_code, struct ifreq *p_ifreq ) rc = ioctl( fd, ioctl_code, p_ifreq ); + close( fd ); + if ( rc < 0 ) - rc = MBG_LU_ERR_IOCTL; + { + // errno has been set appropriately + if ( errno == EADDRNOTAVAIL ) + return MBG_LU_ERR_NOT_SET; - close( fd ); + return MBG_LU_ERR_IOCTL; + } return MBG_LU_SUCCESS; @@ -356,8 +581,10 @@ int do_siocg_ioctl( const char *if_name, int ioctl_code, struct ifreq *p_ifreq ) * @param if_name Name of the interface * @param p_mac_addr Pointer to the MAC address buffer to be filled up * - * @return one of the MBG_LU_xxx codes + * @return one of the ::MBG_LU_CODES * on error the MAC addr is set to all 0 + * + * @see get_port_mac_addr_check */ int get_port_mac_addr( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) { @@ -393,18 +620,17 @@ fail: * @param if_name Name of the interface * @param p_mac_addr Pointer to the MAC address buffer to be filled up * - * @return one of the MBG_LU_xxx codes + * @return one of the ::MBG_LU_CODES * on error the MAC addr is set to all 0 + * + * @see get_port_mac_addr */ int get_port_mac_addr_check( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) { int rc = get_port_mac_addr( if_name, p_mac_addr ); if ( rc == MBG_LU_SUCCESS ) - { - if ( !check_octets_not_all_zero( p_mac_addr->b, sizeof( *p_mac_addr ) ) ) - rc = MBG_LU_ERR_NOT_SET; - } + rc = check_octets_not_all_zero( p_mac_addr->b, sizeof( *p_mac_addr ) ); return rc; @@ -416,11 +642,11 @@ 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 ifname Name of the interface + * @param if_name Name of the interface * * @return 1 link detected on port * 0 no link detected on port - * one of the MBG_LU_xxx codes in case of an error + * one of the ::MBG_LU_CODES in case of an error */ int check_port_link( const char *if_name ) { @@ -449,44 +675,489 @@ int check_port_link( const char *if_name ) -/*HDR*/ +static /*HDR*/ /** - * @brief Retrieve the IPv4 address of a network interface as string + * @brief Retrieve some IPv4 address like info from a network interface * - * @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 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 * - * @return one of the MBG_LU_xxx 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 */ -int get_port_ip4_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) +int get_specific_port_ip4_addr( const char *if_name, IP4_ADDR *p_addr, int sigioc_code ) { int rc = MBG_LU_ERR_NSUPP; #if defined( MBG_TGT_LINUX ) struct ifreq ifr = { { { 0 } } }; - rc = do_siocg_ioctl( if_name, SIOCGIFADDR, &ifr ); + 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: + #endif + + *p_addr = 0; // make empty address + + return rc; + +} // get_specific_port_ip4_addr + - if ( buf_size < MAX_IP4_ADDR_STR_SIZE ) //###+++ + +/*HDR*/ +/** + * @brief Retrieve the IPv4 address of a network interface + * + * @param if_name Name of the interface + * @param p_addr Pointer to address field to be filled up + * + * @return one of the ::MBG_LU_CODES + * + * @see get_port_ip4_settings + * @see get_port_ip4_addr_str + * @see get_port_ip4_netmask + * @see get_port_ip4_netmask_str + * @see get_port_ip4_broad_addr + * @see get_port_ip4_broad_addr_str + * @see get_specific_port_ip4_addr + */ +int get_port_ip4_addr( const char *if_name, IP4_ADDR *p_addr ) +{ + return get_specific_port_ip4_addr( if_name, p_addr, SIOCGIFADDR ); + +} // get_port_ip4_addr + + + +/*HDR*/ +/** + * @brief Retrieve the IPv4 net mask of a network interface + * + * @param if_name Name of the interface + * @param p_addr Pointer to address field to be filled up + * + * @return one of the ::MBG_LU_CODES + * + * @see get_port_ip4_settings + * @see get_port_ip4_addr + * @see get_port_ip4_addr_str + * @see get_port_ip4_netmask_str + * @see get_port_ip4_broad_addr + * @see get_port_ip4_broad_addr_str + * @see get_specific_port_ip4_addr + */ +int get_port_ip4_netmask( const char *if_name, IP4_ADDR *p_addr ) +{ + return get_specific_port_ip4_addr( if_name, p_addr, SIOCGIFNETMASK ); + +} // get_port_ip4_netmask + + + +/*HDR*/ +/** + * @brief Retrieve the IPv4 broadcast address of a network interface + * + * @param if_name Name of the interface + * @param p_addr Pointer to address field to be filled up + * + * @return one of the ::MBG_LU_CODES + * + * @see get_port_ip4_settings + * @see get_port_ip4_addr + * @see get_port_ip4_addr_str + * @see get_port_ip4_netmask + * @see get_port_ip4_netmask_str + * @see get_port_ip4_broad_addr_str + * @see get_specific_port_ip4_addr + */ +int get_port_ip4_broad_addr( const char *if_name, IP4_ADDR *p_addr ) +{ + return get_specific_port_ip4_addr( if_name, p_addr, SIOCGIFBRDADDR ); + +} // get_port_ip4_broad_addr + + + +#if defined( MBG_TGT_LINUX ) + +static /*HDR*/ +/** + * @brief Read a requested message from the netlink socket + */ +int readNlSock( int sockFd, char *bufPtr, size_t buf_size, int seqNum, int pId ) +{ + struct nlmsghdr *nlHdr; + int readLen = 0; + int msgLen = 0; + + do + { + // receive response from the kernel, can be several chunks + if ( ( readLen = recv( sockFd, bufPtr, buf_size - msgLen, 0 ) ) < 0 ) { - rc = MBG_LU_ERR_BUFF_SZ; - goto fail; + #if DEBUG_NETLINK + mbglog( LOG_ERR, "%s: Failed to receive netlink packet: %s", + __func__, strerror( errno ) ); + #endif + return -1; } - strncpy( p_addr_buf, inet_ntoa( ( (struct sockaddr_in *) &ifr.ifr_addr )->sin_addr ), buf_size - 1 ); - p_addr_buf[buf_size-1] = 0; // force terminating 0 + nlHdr = (struct nlmsghdr *) bufPtr; - return rc; + // check if the header is valid + if ( ( NLMSG_OK( nlHdr, readLen ) == 0 ) || ( nlHdr->nlmsg_type == NLMSG_ERROR ) ) + { + #if DEBUG_NETLINK + mbglog( LOG_ERR, "%s: Invalid header in received netlink packet", + __func__ ); + #endif + return -1; + } -fail: + // check if the its the last message + if ( nlHdr->nlmsg_type == NLMSG_DONE ) + { + #if DEBUG_NETLINK + mbglog( LOG_ERR, "%s: Reached last message in received packet", + __func__ ); + #endif + break; + } + + // move the pointer to buffer appropriately + bufPtr += readLen; + msgLen += readLen; + + // check if its a multi part message + if ( ( nlHdr->nlmsg_flags & NLM_F_MULTI ) == 0 ) + { + // return if it's not a multi part message + #if DEBUG_NETLINK + mbglog( LOG_ERR, "%s: Received packet is not a multi part message", + __func__ ); + #endif + break; + } + + } while ( ( nlHdr->nlmsg_seq != seqNum ) || ( nlHdr->nlmsg_pid != pId ) ); + + #if DEBUG_NETLINK + mbglog( LOG_ERR, "%s: Received packet has len %i", + __func__, msgLen ); #endif - *p_addr_buf = 0; // make empty string + return msgLen; + +} // readNlSock + + + +#if DEBUG_NETLINK + +static /*HDR*/ +void log_netlink_bytes( const char *fnc, const char *info, const void *p, int n_bytes ) +{ + char ws[80]; + int n = 0; + int i; + + for ( i = 0; i < n_bytes; i++ ) + n += snprintf( &ws[n], sizeof( ws ) - n, " %i", BYTE_OF( *p, i ) ); + + mbglog( LOG_INFO, "%s: attibute %s, copying %i bytes:%s", + fnc, info, n_bytes, ws ); + +} // log_netlink_bytes + +#endif + + + +static /*HDR*/ +int parseRoutes( struct nlmsghdr *nlHdr, struct route_info *rtInfo ) +{ + // parse the route info returned + struct rtmsg *rtMsg; + struct rtattr *rtAttr; + int rtLen; + + rtMsg = (struct rtmsg *) NLMSG_DATA( nlHdr ); + + // If the route is not for AF_INET then return. + // This could be also IPv6 routes. + if ( rtMsg->rtm_family != AF_INET ) + { + #if DEBUG_NETLINK + mbglog( LOG_ERR, "%s: Route is not AF_INET (%li), but %li", + __func__, (long) AF_INET, (long) rtMsg->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 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 ); + #endif + return -1; + } + + + // get the rtattr field + rtAttr = (struct rtattr *) RTM_RTA( rtMsg ); + rtLen = RTM_PAYLOAD( nlHdr ); + + for ( ; RTA_OK( rtAttr, rtLen ); rtAttr = RTA_NEXT( rtAttr, rtLen ) ) + { + #if DEBUG_NETLINK + mbglog( LOG_ERR, "rtAttr at %p, %i bytes left", rtAttr, rtLen ); + #endif + + switch ( rtAttr->rta_type ) + { + case RTA_OIF: + if_indextoname( *(int *)RTA_DATA( rtAttr ), rtInfo->ifName ); + #if DEBUG_NETLINK + mbglog( LOG_ERR, "%s: attibute RTA_OIF, IF name: %s", + __func__, rtInfo->ifName ); + #endif + break; + + case RTA_GATEWAY: + memcpy( &rtInfo->gateWay, RTA_DATA( rtAttr ), sizeof( rtInfo->gateWay ) ); + #if DEBUG_NETLINK + log_netlink_bytes( __func__, "RTA_GATEWAY", &rtInfo->gateWay, sizeof( rtInfo->gateWay ) ); + #endif + break; + + case RTA_PREFSRC: + memcpy( &rtInfo->srcAddr , RTA_DATA( rtAttr ), sizeof( rtInfo->srcAddr ) ); + #if DEBUG_NETLINK + log_netlink_bytes( __func__, "RTA_PREFSRC", &rtInfo->srcAddr, sizeof( rtInfo->srcAddr ) ); + #endif + break; + + case RTA_DST: + memcpy( &rtInfo->dstAddr, RTA_DATA( rtAttr ), sizeof( rtInfo->dstAddr ) ); + #if DEBUG_NETLINK + log_netlink_bytes( __func__, "RTA_DST", &rtInfo->dstAddr, sizeof( rtInfo->dstAddr ) ); + #endif + break; + + #if DEBUG_NETLINK + case RTA_TABLE: + { + // The RTA_TABLE attribute was added to the kernel source in 2006 to support + // more than 255 routing tables. Originally the number of the routing table + // to which an entry belongs had been passed only in struct rtmsg::rtm_table, + // which is only 8 bits wide and should still hold the 8 LSBs of the full + // routing table number for compatibility, so this should still work for the + // standard routing tables, including the main table we are inspecting here. + // + // Whether this can be compiled in depends on the version of linux/rtnetlink.h + // 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 ) ); + mbglog( LOG_ERR, "%s: attibute RTA_TABLE %i (%i)", + __func__, rta_table, rtMsg->rtm_table ); + } + break; + + default: + mbglog( LOG_ERR, "%s: Found unknown route type %li", + __func__, (long) rtAttr->rta_type ); + #endif + } + } + + return 0; + +} // parseRoutes + +#endif // defined( MBG_TGT_LINUX ) + + + +/*HDR*/ +/** + * @brief Retrieve the IPv4 gateway (default route) + * + * @param p_addr Pointer to address field to be filled up + * + * @return one of the ::MBG_LU_CODES + */ +int get_ip4_gateway( IP4_ADDR *p_addr ) +{ + int ret_val = MBG_LU_ERR_NOT_SET; + +#if defined( MBG_TGT_LINUX ) + struct nlmsghdr *nlMsg; + struct route_info route_info; + char msgBuf[8192]; // pretty large buffer + + int sock; + int len; + int msgSeq = 0; + int idx; + + // create socket + if ( ( sock = socket( PF_NETLINK, SOCK_DGRAM, NETLINK_ROUTE ) ) < 0 ) + { + #if DEBUG_NETLINK + mbglog( LOG_ERR, "%s: Failed to create netlink socket: %s", + __func__, strerror( errno ) ); + #endif + ret_val = MBG_LU_ERR_SOCKET; + goto out; + } + + + // initialize the buffer + memset( msgBuf, 0, sizeof( msgBuf ) ); + + // point the header and the msg structure pointers into the buffer + nlMsg = (struct nlmsghdr *) msgBuf; + + // fill in the nlmsg header + nlMsg->nlmsg_len = NLMSG_LENGTH( sizeof( struct rtmsg ) ); // length of message + nlMsg->nlmsg_type = RTM_GETROUTE; // get the routes from kernel routing table + + nlMsg->nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST; // the message is a request for dump + nlMsg->nlmsg_seq = msgSeq++; // 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 DEBUG_NETLINK + mbglog( LOG_ERR, "%s: Failed to write to netlink socket: %s", + __func__, strerror( errno ) ); + #endif + ret_val = -1; + goto out; + } + + // read the response + if ( ( len = readNlSock( sock, msgBuf, sizeof( msgBuf ), msgSeq, getpid() ) ) < 0 ) + { + #if DEBUG_NETLINK + mbglog( LOG_ERR, "%s: Failed to read from netlink socket", + __func__ ); + #endif + ret_val = -1; + goto out; + } + + #if DEBUG_NETLINK + mbglog( LOG_ERR, "%s: Read %i bytes from netlink socket", __func__ ); + #endif + + // parse and print the response + for ( idx = 0; NLMSG_OK( nlMsg, len ); nlMsg = NLMSG_NEXT( nlMsg, len ), idx ++ ) + { + memset( &route_info, 0, sizeof( route_info ) ); + + #if DEBUG_NETLINK + mbglog( LOG_ERR, "\nnlMsg at %p, %i bytes left", nlMsg, len ); + #endif + + + if ( parseRoutes( nlMsg, &route_info ) < 0 ) + continue; // don't check route_info if it has not been set up + + #if DEBUG_NETLINK + { + char ws[100]; + int l = sizeof( ws ); + 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 ) ); + + mbglog( LOG_ERR, "%s: route %i: %s, if \"%s\"", + __func__, idx, ws, route_info.ifName ); + } + #endif + + // check if default IPv4 gateway + 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; + // 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 + mbglog( LOG_ERR, "%s: Default gateway found: %s", + __func__, (char *) inet_ntoa( route_info.gateWay ) ); + #else + break; + #endif + } + } + +out: + if ( sock >= 0 ) + close( sock ); + +#endif // defined( MBG_TGT_LINUX ) + + + if ( ret_val != MBG_LU_SUCCESS ) + *p_addr = 0; + + return ret_val; + +} // get_ip4_gateway + + + +/*HDR*/ +/** + * @brief Retrieve the IPv4 address of a network interface as string + * + * @param if_name Name of the interface + * @param p_addr_buf Pointer to the string buffer to be filled up + * @param buf_size size of the string buffer + * + * @return one of the ::MBG_LU_CODES + * + * @see get_port_ip4_settings + * @see get_port_ip4_addr + * @see get_port_ip4_netmask + * @see get_port_ip4_netmask_str + * @see get_port_ip4_broad_addr + * @see get_port_ip4_broad_addr_str + * @see get_specific_port_ip4_addr + */ +int get_port_ip4_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) +{ + IP4_ADDR addr; + + int rc = get_port_ip4_addr( if_name, &addr ); + + snprint_ip4_addr( p_addr_buf, buf_size, &addr, NULL ); return rc; @@ -502,38 +1173,136 @@ fail: * @param p_addr_buf Pointer to the string buffer to be filled up * @param buf_size size of the string buffer * - * @return one of the MBG_LU_xxx codes + * @return one of the ::MBG_LU_CODES + * + * @see get_port_ip4_settings + * @see get_port_ip4_addr + * @see get_port_ip4_addr_str + * @see get_port_ip4_netmask + * @see get_port_ip4_broad_addr + * @see get_port_ip4_broad_addr_str + * @see get_specific_port_ip4_addr */ int get_port_ip4_netmask_str( const char *if_name, char *p_addr_buf, int buf_size ) { - int rc = MBG_LU_ERR_NSUPP; + IP4_ADDR addr; - #if defined( MBG_TGT_LINUX ) - struct ifreq ifr = { { { 0 } } }; + int rc = get_port_ip4_netmask( if_name, &addr ); - rc = do_siocg_ioctl( if_name, SIOCGIFNETMASK, &ifr ); + snprint_ip4_addr( p_addr_buf, buf_size, &addr, NULL ); - if ( rc != MBG_LU_SUCCESS ) - goto fail; + return rc; - if ( buf_size < MAX_IP4_ADDR_STR_SIZE ) //###++++ - { - rc = MBG_LU_ERR_BUFF_SZ; - goto fail; - } +} // get_port_ip4_netmask_str - strncpy( p_addr_buf, inet_ntoa( ( (struct sockaddr_in *) &ifr.ifr_netmask )->sin_addr ), buf_size - 1 ); - p_addr_buf[buf_size-1] = 0; // force terminating 0 - return rc; -fail: - #endif +/*HDR*/ +/** + * @brief Retrieve the IPv4 broadcast address of a network interface as string + * + * @param if_name Name of the interface + * @param p_addr_buf Pointer to the string buffer to be filled up + * @param buf_size size of the string buffer + * + * @return one of the ::MBG_LU_CODES + * + * @see get_port_ip4_settings + * @see get_port_ip4_addr + * @see get_port_ip4_addr_str + * @see get_port_ip4_netmask + * @see get_port_ip4_netmask_str + * @see get_port_ip4_broad_addr + * @see get_specific_port_ip4_addr + */ +int get_port_ip4_broad_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) +{ + IP4_ADDR addr; + + int rc = get_port_ip4_broad_addr( if_name, &addr ); - *p_addr_buf = 0; // make empty string + snprint_ip4_addr( p_addr_buf, buf_size, &addr, NULL ); return rc; -} // get_port_ip4_netmask_str +} // get_port_ip4_broad_addr_str + + + +/*HDR*/ +/** + * @brief Retrieve the current IPv4 settings of a network interface + * + * @param if_name Name of the interface + * @param p Pointer to a IP4_SETTINGS structure to be filled up + * + * @return 0 on success, < 0 on error + * + * @see get_port_ip4_addr + * @see get_port_ip4_addr_str + * @see get_port_ip4_netmask + * @see get_port_ip4_netmask_str + * @see get_port_ip4_broad_addr + * @see get_port_ip4_broad_addr_str + * @see get_specific_port_ip4_addr + */ +int get_port_ip4_settings( const char *if_name, IP4_SETTINGS *p ) +{ + int link_up; + int rc; + int ret_val = 0; + + memset( p, 0, sizeof( *p ) ); + + rc = get_port_ip4_addr( if_name, &p->ip_addr ); + + if ( ( rc != MBG_LU_SUCCESS ) && ( rc != MBG_LU_ERR_NOT_SET ) ) + ret_val = -1; + + + rc = get_port_ip4_netmask( if_name, &p->netmask ); + + if ( ( rc != MBG_LU_SUCCESS ) && ( rc != MBG_LU_ERR_NOT_SET ) ) + ret_val = -1; + + + rc = get_port_ip4_broad_addr( if_name, &p->broad_addr ); + + if ( ( rc != MBG_LU_SUCCESS ) && ( rc != MBG_LU_ERR_NOT_SET ) ) + ret_val = -1; + + + rc = get_ip4_gateway( &p->gateway ); + + if ( ( rc != MBG_LU_SUCCESS ) && ( rc != MBG_LU_ERR_NOT_SET ) ) + ret_val = -1; + + + link_up = check_port_link( if_name ); + + if ( link_up ) + p->flags |= IP4_MSK_LINK; + +#if 0 //##+++++ + // We could also try to check VLAN and DHCP settings here, + // but as of now, this is specific to an application. + + // ##++++ The VLAN and DHCP status info collected below + // just return what has been configured previously by this program, + // however, it does not reflect any changes which have been made + // manually, e.g. via the command line. + if ( vlan_enabled ) + { + p->flags |= IP4_MSK_VLAN; + p->vlan_cfg = vlan_cfg; + } + + if ( dhcp_enabled ) + p->flags |= IP4_MSK_DHCP; +#endif + + return ret_val; + +} // get_port_ip4_settings diff --git a/mbglib/common/lan_util.h b/mbglib/common/lan_util.h index 3b480d5..6afd21a 100755 --- a/mbglib/common/lan_util.h +++ b/mbglib/common/lan_util.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: lan_util.h 1.1.1.7 2011/09/14 13:51:58 martin TEST $ + * $Id: lan_util.h 1.4 2013/02/19 15:15:53 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,21 +10,14 @@ * * ----------------------------------------------------------------------- * $Log: lan_util.h $ - * Revision 1.1.1.7 2011/09/14 13:51:58 martin - * Defined some common return codes. + * Revision 1.4 2013/02/19 15:15:53 martin + * Added some inline functions. + * Redefined return codes as named enum. + * Updated function prototypes. + * Revision 1.3 2012/10/02 18:24:29 martin + * Added some macros to simpliy conversion to string. + * Revision 1.2 2012/03/09 08:51:44 martin * Updated function prototypes. - * Revision 1.1.1.6 2011/08/27 14:26:47 udo - * new get_port_ip4_addr() and get_port_ip4_netm() - * Revision 1.1.1.5 2011/08/27 13:35:05 udo - * new get_port_ip4_addr() and get_port_ip4_netm() - * Revision 1.1.1.4 2011/08/25 20:39:14 martin - * Defined MBG_MAC_ADDR. - * Updated function prototypes - * Revision 1.1.1.3 2011/08/04 13:44:55 philipp - * prototype for function: check_port_link - * Revision 1.1.1.2 2011/06/22 07:47:48 martin - * Cleaned up handling of pragma pack(). - * Revision 1.1.1.1 2011/04/20 16:09:02 martin * Revision 1.1 2011/03/04 10:01:32 martin * Initial revision. * @@ -54,6 +47,15 @@ }; #endif + +#if defined( IFHWADDRLEN ) // usually defined in net/if.h + #if ( IFHWADDRLEN != 6 ) + #error Warning: IFHWADDRLEN is not 6! + #endif +#endif + + + #ifdef _LAN_UTIL #define _ext #define _DO_INIT @@ -82,23 +84,121 @@ extern "C" { #define MAC_SEP_CHAR_ALT '-' // alternate character #endif -#if !defined( IFHWADDRLEN ) - #define IFHWADDRLEN 6 //##+++++ usually defined in net/if.h -#endif -#define MBG_LU_SUCCESS 0 // success -#define MBG_LU_ERR_NSUPP -1 // function not supported -#define MBG_LU_ERR_PORT_NAME -2 // port name exceeds max length -#define MBG_LU_ERR_SOCKET -3 // failed to open socket -#define MBG_LU_ERR_IOCTL -4 // IOCTL call failed -#define MBG_LU_ERR_NOT_SET -5 // octets are all 0 -#define MBG_LU_ERR_BUFF_SZ -6 // buffer size too small +/** + * @brief Return codes for the LAN utility functions + */ +enum MBG_LU_CODES +{ + MBG_LU_SUCCESS = 0, ///< success + MBG_LU_ERR_NSUPP = -1, ///< function not supported + MBG_LU_ERR_PORT_NAME = -2, ///< port name exceeds max length + MBG_LU_ERR_SOCKET = -3, ///< failed to open socket + MBG_LU_ERR_IOCTL = -4, ///< IOCTL call failed + MBG_LU_ERR_NOT_SET = -5, ///< octets are all 0 + MBG_LU_ERR_BUFF_SZ = -6, ///< buffer size too small + MBG_LU_ERR_FMT = -7, ///< parameter format not correct + MBG_LU_ERR_RANGE = -8 ///< range for some parameter exceeded +}; + + +#define MAX_IP4_BITS ( 8 * sizeof( IP4_ADDR ) ) + +#define IP4_MSB_MASK ( 1UL << ( MAX_IP4_BITS - 1 ) ) + +#define MIN_IP4_CIDR_NETMASK_BITS 0 +#define MAX_IP4_CIDR_NETMASK_BITS MAX_IP4_BITS + + + +/** + * @brief Compute an IP4 net mask according to the number of CIDR netmask bits + * + * E.g. the 24 bits mentioned in "172.16.3.250/24" result in 0xFFFFFF00, + * corresponding to 255.255.255.0 in dotted quad notation. + * + * @param netmask_bits Number of netmask bits from CIDR notation + * + * @return The IP4 net mask + * + * @see get_ip4_net_mask_bits() + */ +static __mbg_inline +IP4_ADDR ip4_net_mask_from_cidr( int netmask_bits ) +{ + return (IP4_ADDR) ~( ( 1UL << ( MAX_IP4_BITS - netmask_bits ) ) - 1 ); + +} // ip4_net_mask_from_cidr + -typedef struct +/** + * @brief Determine the broadcast address for an IP4 address plus net mask + * + * E.g. IP 0xAC1003FA, net mask 0xFFFFFF00 yields broadcast addr 0xAC1003FF. + * In dotted quad notation, IP 172.16.3.250 with net mask 255.255.255.0 + * result in broadcast address 172.16.3.255. + * + * @param p_addr The full IP4 address + * @param p_mask The IP4 net mask + * + * @return The determined IP4 broadcast address + */ +static __mbg_inline +IP4_ADDR ip4_broad_addr_from_addr( const IP4_ADDR *p_addr, const IP4_ADDR *p_mask ) { - uint8_t b[IFHWADDRLEN]; -} MBG_MAC_ADDR; + return *p_addr | ~(*p_mask); + +} // ip4_broad_addr_from_addr + + + +/** + * @brief Determine the network part of an IP4 address based on the net mask + * + * E.g. IP 0xAC1003FA, net mask 0xFFFFFF00 yields network part 0xAC100300. + * In dotted quad notation, IP 172.16.3.250 with net mask 255.255.255.0 + * results in network part 172.16.3.0. + * + * @param p_addr The full IP4 address + * @param p_mask The IP4 net mask + * + * @return The network part of the IP4 address + */ +static __mbg_inline +IP4_ADDR ip4_net_part_from_addr( const IP4_ADDR *p_addr, const IP4_ADDR *p_mask ) +{ + return *p_addr & *p_mask; + +} // ip4_net_part_from_addr + + + +/** + * @brief Check if two IP4 addresses have the same network part. + * + * @param p_addr1 The first IP4 address to check + * @param p_addr2 The second IP4 address to check + * @param p_mask The IP4 net mask + * + * @return true, if the network parts are matching + */ +static __mbg_inline +int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, + const IP4_ADDR *p_mask ) +{ + return ip4_net_part_from_addr( p_addr1, p_mask ) + == ip4_net_part_from_addr( p_addr2, p_mask ); + +} // ip4_net_part_matches + + + +#define _ip4_addr_to_str( _s, _a ) \ + snprint_ip4_addr( _s, sizeof( _s ), _a, NULL ) + +#define _mac_addr_to_str( _s, _a ) \ + snprint_mac_addr( _s, sizeof( _s ), _a ) @@ -110,29 +210,90 @@ typedef struct /* by MAKEHDR, do not remove the comments. */ /** + * @brief Count the number of sequential bits set starting from MSB + * + * E.g. for 0xC0 and 0xC1 the results are both 2 since only + * the 2 MSBs are sequentially set. + * + * @param p_mask The IP4 net mask + * + * @return The number of sequential MSB bits set in val + * + * @see ip4_net_mask_from_cidr + */ + int get_ip4_net_mask_bits( const IP4_ADDR *p_mask ) ; + + /** * @brief Print an IPv4 address to a dotted quad format string. * * @param s The string buffer into which to print * @param max_len Maximum length of the string, i.e. size of the buffer - * @param addr The IPv4 address + * @param p_addr The IPv4 address * @param info An optional string which is prepended to the string, or NULL * * @return The overall number of characters printed to the string + * + * @see snprint_ip4_cidr_addr + * @see str_to_ip4_addr + * @see cidr_str_to_ip4_addr_and_net_mask */ - int snprint_ip4_addr( char *s, size_t max_len, const IP4_ADDR *addr, const char *info ) ; + int snprint_ip4_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, const char *info ) ; + + /** + * @brief Print an IPv4 address plus net mask to string in CIDR notation. + * + * The printed CIDR string is something like "172.16.3.250/24" + * + * @param s The string buffer into which to print + * @param max_len Maximum length of the string, i.e. size of the buffer + * @param p_addr The IPv4 address + * @param p_mask The IPv4 net mask + * @param info An optional string which is prepended to the string, or NULL + * + * @return The overall number of characters printed to the string + * + * @see snprint_ip4_addr + * @see str_to_ip4_addr + * @see cidr_str_to_ip4_addr_and_net_mask + */ + int snprint_ip4_cidr_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, const IP4_ADDR *p_mask, const char *info ) ; /** * @brief Convert a string to an IP4_ADDR. * - * @param p 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 p_addr Pointer to the IP4_ADDR variable, or NULL, in which case this + * function can be used to check if the string is formally correct. + * @param s The string to be converted * * @return >= 0 on success, number of characters evaluated from the input string * -1 if invalid number found in string * -2 if separator is not a dot '.' + * + * @see snprint_ip4_addr + * @see snprint_ip4_cidr_addr + * @see cidr_str_to_ip4_addr_and_net_mask */ - int str_to_ip4_addr( IP4_ADDR *p, const char *s ) ; + int str_to_ip4_addr( IP4_ADDR *p_addr, const char *s ) ; + + /** + * @brief Convert a string in CIDR notation to an IP4_ADDR and net mask. + * + * @param p_addr Pointer to an IP4_ADDR variable for the IP4 address, + * or NULL, in which case this function can be used + * to check if the string is formally correct. + * @param p_mask Pointer to an IP4_ADDR variable for the net mask, + * or NULL, in which case this function can be used + * to check if the string is formally correct. + * @param cidr_str The string to be converted, in CIDR format, e.g. "172.16.3.250/24" + * + * @return >= 0 on success, number of characters evaluated from the input string + * one of the ::MBG_LU_CODES on error + * + * @see snprint_ip4_addr + * @see snprint_ip4_cidr_addr + * @see str_to_ip4_addr + */ + int cidr_str_to_ip4_addr_and_net_mask( IP4_ADDR *p_addr, IP4_ADDR *p_mask, const char *cidr_str ) ; /** * @brief Print a MAC ID or similar array of octets to a string. @@ -145,6 +306,10 @@ typedef struct * @param info An optional string which is prepended to the output, or NULL * * @return The overall number of characters printed to the string + * + * @see snprint_mac_addr + * @see str_to_octets + * @see check_octets_not_all_zero */ int snprint_octets( char *s, size_t max_len, const uint8_t *octets, int num_octets, char sep, const char *info ) ; @@ -156,6 +321,10 @@ typedef struct * @param p_mac_addr The MAC address to be printed * * @return The overall number of characters printed to the string + * + * @see snprint_octets + * @see str_to_octets + * @see check_octets_not_all_zero */ int snprint_mac_addr( char *s, size_t max_len, const MBG_MAC_ADDR *p_mac_addr ) ; @@ -167,6 +336,10 @@ typedef struct * @param s The string to be converted * * @return The overall number of octets decoded from the string + * + * @see snprint_octets + * @see snprint_mac_addr + * @see check_octets_not_all_zero */ int str_to_octets( uint8_t *octets, int num_octets, const char *s ) ; @@ -178,17 +351,33 @@ typedef struct * * @return MBG_LU_SUCCESS octets are valid, i.e. not all 0 * MBG_LU_ERR_NOT_SET octets are invalid, i.e. all 0 + * + * @see snprint_octets + * @see snprint_mac_addr + * @see str_to_octets */ int check_octets_not_all_zero( const uint8_t *octets, int num_octets ) ; /** + * @brief Check if an array of octets is valid, i.e. != 0 + * + * @param p_addr Pointer to a MAC address + * + * @return MBG_LU_SUCCESS MAC address is valid, i.e. not all 0 + * MBG_LU_ERR_NOT_SET MAC address is invalid, i.e. all 0 + * + * @see check_octets_not_all_zero + */ + int check_mac_addr_not_all_zero( const MBG_MAC_ADDR *p_addr ) ; + + /** * @brief Do a SIOCGxxx IOCTL call to read specific information from a LAN interface * * @param if_name Name of the interface * @param ioctl_code One of the predefined system SIOCGxxx IOCTL codes * @param p_ifreq Pointer to a request buffer * - * @return one of the MBG_LU_xxx codes + * @return one of the ::MBG_LU_CODES */ int do_siocg_ioctl( const char *if_name, int ioctl_code, struct ifreq *p_ifreq ) ; @@ -198,8 +387,10 @@ typedef struct * @param if_name Name of the interface * @param p_mac_addr Pointer to the MAC address buffer to be filled up * - * @return one of the MBG_LU_xxx codes + * @return one of the ::MBG_LU_CODES * on error the MAC addr is set to all 0 + * + * @see get_port_mac_addr_check */ int get_port_mac_addr( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) ; @@ -209,30 +400,103 @@ typedef struct * @param if_name Name of the interface * @param p_mac_addr Pointer to the MAC address buffer to be filled up * - * @return one of the MBG_LU_xxx codes + * @return one of the ::MBG_LU_CODES * on error the MAC addr is set to all 0 + * + * @see get_port_mac_addr */ int get_port_mac_addr_check( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) ; /** * @brief Check the link state of a network interface * - * @param ifname Name of the interface + * @param if_name Name of the interface * * @return 1 link detected on port * 0 no link detected on port - * one of the MBG_LU_xxx codes in case of an error + * one of the ::MBG_LU_CODES in case of an error */ int check_port_link( const char *if_name ) ; /** + * @brief Retrieve the IPv4 address of a network interface + * + * @param if_name Name of the interface + * @param p_addr Pointer to address field to be filled up + * + * @return one of the ::MBG_LU_CODES + * + * @see get_port_ip4_settings + * @see get_port_ip4_addr_str + * @see get_port_ip4_netmask + * @see get_port_ip4_netmask_str + * @see get_port_ip4_broad_addr + * @see get_port_ip4_broad_addr_str + * @see get_specific_port_ip4_addr + */ + int get_port_ip4_addr( const char *if_name, IP4_ADDR *p_addr ) ; + + /** + * @brief Retrieve the IPv4 net mask of a network interface + * + * @param if_name Name of the interface + * @param p_addr Pointer to address field to be filled up + * + * @return one of the ::MBG_LU_CODES + * + * @see get_port_ip4_settings + * @see get_port_ip4_addr + * @see get_port_ip4_addr_str + * @see get_port_ip4_netmask_str + * @see get_port_ip4_broad_addr + * @see get_port_ip4_broad_addr_str + * @see get_specific_port_ip4_addr + */ + int get_port_ip4_netmask( const char *if_name, IP4_ADDR *p_addr ) ; + + /** + * @brief Retrieve the IPv4 broadcast address of a network interface + * + * @param if_name Name of the interface + * @param p_addr Pointer to address field to be filled up + * + * @return one of the ::MBG_LU_CODES + * + * @see get_port_ip4_settings + * @see get_port_ip4_addr + * @see get_port_ip4_addr_str + * @see get_port_ip4_netmask + * @see get_port_ip4_netmask_str + * @see get_port_ip4_broad_addr_str + * @see get_specific_port_ip4_addr + */ + int get_port_ip4_broad_addr( const char *if_name, IP4_ADDR *p_addr ) ; + + /** + * @brief Retrieve the IPv4 gateway (default route) + * + * @param p_addr Pointer to address field to be filled up + * + * @return one of the ::MBG_LU_CODES + */ + int get_ip4_gateway( IP4_ADDR *p_addr ) ; + + /** * @brief Retrieve the IPv4 address of a network interface as string * * @param if_name Name of the interface * @param p_addr_buf Pointer to the string buffer to be filled up * @param buf_size size of the string buffer * - * @return one of the MBG_LU_xxx codes + * @return one of the ::MBG_LU_CODES + * + * @see get_port_ip4_settings + * @see get_port_ip4_addr + * @see get_port_ip4_netmask + * @see get_port_ip4_netmask_str + * @see get_port_ip4_broad_addr + * @see get_port_ip4_broad_addr_str + * @see get_specific_port_ip4_addr */ int get_port_ip4_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) ; @@ -243,10 +507,55 @@ typedef struct * @param p_addr_buf Pointer to the string buffer to be filled up * @param buf_size size of the string buffer * - * @return one of the MBG_LU_xxx codes + * @return one of the ::MBG_LU_CODES + * + * @see get_port_ip4_settings + * @see get_port_ip4_addr + * @see get_port_ip4_addr_str + * @see get_port_ip4_netmask + * @see get_port_ip4_broad_addr + * @see get_port_ip4_broad_addr_str + * @see get_specific_port_ip4_addr */ int get_port_ip4_netmask_str( const char *if_name, char *p_addr_buf, int buf_size ) ; + /** + * @brief Retrieve the IPv4 broadcast address of a network interface as string + * + * @param if_name Name of the interface + * @param p_addr_buf Pointer to the string buffer to be filled up + * @param buf_size size of the string buffer + * + * @return one of the ::MBG_LU_CODES + * + * @see get_port_ip4_settings + * @see get_port_ip4_addr + * @see get_port_ip4_addr_str + * @see get_port_ip4_netmask + * @see get_port_ip4_netmask_str + * @see get_port_ip4_broad_addr + * @see get_specific_port_ip4_addr + */ + int get_port_ip4_broad_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) ; + + /** + * @brief Retrieve the current IPv4 settings of a network interface + * + * @param if_name Name of the interface + * @param p Pointer to a IP4_SETTINGS structure to be filled up + * + * @return 0 on success, < 0 on error + * + * @see get_port_ip4_addr + * @see get_port_ip4_addr_str + * @see get_port_ip4_netmask + * @see get_port_ip4_netmask_str + * @see get_port_ip4_broad_addr + * @see get_port_ip4_broad_addr_str + * @see get_specific_port_ip4_addr + */ + int get_port_ip4_settings( const char *if_name, IP4_SETTINGS *p ) ; + /* ----- function prototypes end ----- */ diff --git a/mbglib/common/macioctl.h b/mbglib/common/macioctl.h index cba3f79..f550a7c 100755 --- a/mbglib/common/macioctl.h +++ b/mbglib/common/macioctl.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: macioctl.h 1.33.1.31 2011/11/25 15:03:17 martin TEST $ + * $Id: macioctl.h 1.35 2013/04/11 13:46:05 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,74 +11,41 @@ * * ----------------------------------------------------------------------- * $Log: macioctl.h $ - * Revision 1.33.1.31 2011/11/25 15:03:17 martin + * Revision 1.35 2013/04/11 13:46:05 martin + * Account for modified spinlock handling under Windows. + * Revision 1.34 2012/10/02 18:29:49Z martin + * Account for some renamed library symbols. + * Account for renamed structures. * Support on-board event logs. - * Revision 1.33.1.30 2011/11/24 08:24:54 martin - * Revision 1.33.1.29 2011/11/23 16:49:06 martin - * Fixed a bug in IOCTL_PCPS_GENERIC_IO handler. * Support debug status. - * Revision 1.33.1.28 2011/10/05 09:00:14 martin * Made inline functions static. - * Revision 1.33.1.27 2011/09/21 16:01:54 martin * Include cfg_hlp.h. - * Revision 1.33.1.26 2011/09/08 13:17:54 martin * Always read receiver info directly from the device. - * Revision 1.33.1.25 2011/07/20 15:48:22 martin * Conditionally use older IOCTL request buffer structures. - * Revision 1.33.1.24 2011/07/19 12:52:05 martin - * Revision 1.33.1.23 2011/07/14 14:53:58 martin * 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. - * Revision 1.33.1.22 2011/07/06 11:19:19 martin * Support reading CORR_INFO, and reading/writing TR_DISTANCE. - * Revision 1.33.1.21 2011/06/29 10:51:16 martin * Support IOCTL_DEV_HAS_PZF. - * Revision 1.33.1.20 2011/05/18 10:08:13 martin - * Re-ordered IOCTL evaluation to match ioctl_get_required_privilege() - * which also makes sure calls requiring lowest latency are handled first. - * Revision 1.33.1.19 2011/05/17 16:05:06 martin * Use a single union type buffer instead of a large number of local * variables in ioctl_switch(). * The accumulated size of all local variables required much stack * space which led to problems under Windows. - * Revision 1.33.1.18 2011/05/17 09:37:31 martin * Support PTP unicast configuration. * Account for some IOCTL codes renamed to follow common naming conventions. - * Revision 1.33.1.17 2011/04/12 15:28:54 martin * Use common mutex primitives from mbgmutex.h. - * Revision 1.33.1.16 2011/03/31 10:57:00 martin - * Revision 1.33.1.15 2011/03/31 07:32:09 martin - * This version is the same as 1.33.1.12. - * Revision 1.33.1.14 2011/03/31 07:16:34 martin * Changes by Frank Kardel: Don't require copyin/copyout under NetBSD. - * Revision 1.33.1.13 2011/03/23 16:50:30 martin * Support NetBSD beside FreeBSD. - * Revision 1.33.1.12 2011/03/21 16:25:23 martin * Account for modified _pcpc_kfree(). - * Revision 1.33.1.11 2011/03/02 09:59:50 daniel * Bug fix: Use PCPS_TIME_STAMP with * IOCTL_GET_FAST_HR_TIMESTAMP as output size. - * Revision 1.33.1.10 2011/02/15 14:50:39Z martin - * In a call to retrieve RECEIVER_INFO don't read from device - * but just copy the field from the device info structure. - * Revision 1.33.1.9 2011/02/15 11:08:33 daniel - * Preliminary support for PTP unicast - * Revision 1.33.1.8 2011/02/09 17:08:27Z martin * Specify I/O range number when calling port I/O macros * so they can be used for different ranges under BSD. - * Revision 1.33.1.7 2011/01/26 16:37:55 martin * Modified inline declarations for gcc. - * Revision 1.33.1.6 2011/01/24 17:08:40 martin * Fixed build under FreeBSD. - * Revision 1.33.1.5 2010/11/09 10:57:33 martin * Added _sem_inc_safe_no_irp() macro (Windows only). - * Revision 1.33.1.4 2010/07/16 08:31:32Z martin - * Revision 1.33.1.3 2010/07/15 15:47:07 martin - * Revision 1.33.1.2 2010/07/14 14:48:52 martin * Simplified code and renamed some inline functions. - * Revision 1.33.1.1 2010/03/03 15:11:51 martin * Fixed macro. * Revision 1.33 2009/12/21 16:22:55 martin * Moved code reading memory mapped timestamps to inline functions. @@ -606,11 +573,11 @@ typedef union PORT_SETTINGS_IDX port_settings_idx; SYNTH synth; SYNTH_STATE synth_state; - ALL_POUT_INFO all_pout_info; + ALL_POUT_INFO_IDX all_pout_info_idx; POUT_SETTINGS_IDX pout_settings_idx; - ALL_STR_TYPE_INFO all_str_type_info; - ALL_PORT_INFO all_port_info; - ALL_PTP_UC_MASTER_INFO all_ptp_uc_master_info; + 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; @@ -679,6 +646,10 @@ void do_get_fast_hr_timestamp_safe( PCPS_DDEV *pddev, PCPS_TIME_STAMP *p_ts ) __ static __mbg_inline void do_get_fast_hr_timestamp_safe( PCPS_DDEV *pddev, PCPS_TIME_STAMP *p_ts ) { + #if defined( MBG_TGT_WIN32 ) + KIRQL OldIrql; + #endif + #if TEST_MM_ACCESS_64 volatile uint64_t *p = (volatile uint64_t *) pddev->mm_tstamp_addr; #else @@ -774,6 +745,10 @@ void do_get_fast_hr_timestamp_cycles_safe( PCPS_DDEV *pddev, PCPS_TIME_STAMP_CYC static __mbg_inline void do_get_fast_hr_timestamp_cycles_safe( PCPS_DDEV *pddev, PCPS_TIME_STAMP_CYCLES *p_ts_cyc ) { + #if defined( MBG_TGT_WIN32 ) + KIRQL OldIrql; + #endif + volatile uint32_t *p = (volatile uint32_t *) pddev->mm_tstamp_addr; _mbg_spin_lock_acquire( &pddev->mm_lock ); @@ -1497,25 +1472,25 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, // generic IOCTL functions are used instead. case IOCTL_GET_GPS_ALL_STR_TYPE_INFO: - _io_read_gps_chk( pddev, PC_GPS_ALL_STR_TYPE_INFO, all_str_type_info, pout, + _io_read_gps_chk( pddev, PC_GPS_ALL_STR_TYPE_INFO, all_str_type_info_idx, pout, pout_size, _pcps_ddev_has_receiver_info( pddev ) ); break; case IOCTL_GET_GPS_ALL_PORT_INFO: - _io_read_gps_chk( pddev, PC_GPS_ALL_PORT_INFO, all_port_info, pout, + _io_read_gps_chk( pddev, PC_GPS_ALL_PORT_INFO, all_port_info_idx, pout, pout_size, _pcps_ddev_has_receiver_info( pddev ) ); break; case IOCTL_GET_GPS_ALL_POUT_INFO: - _io_read_gps_chk( pddev, PC_GPS_ALL_POUT_INFO, all_pout_info, pout, + _io_read_gps_chk( pddev, PC_GPS_ALL_POUT_INFO, all_pout_info_idx, pout, pout_size, _pcps_ddev_has_receiver_info( pddev ) ); break; case IOCTL_GET_ALL_PTP_UC_MASTER_INFO: - _io_read_gps_chk( pddev, PC_GPS_ALL_PTP_UC_MASTER_INFO, all_ptp_uc_master_info, + _io_read_gps_chk( pddev, PC_GPS_ALL_PTP_UC_MASTER_INFO, all_ptp_uc_master_info_idx, pout, pout_size, _pcps_ddev_has_ptp_unicast( pddev ) ); break; diff --git a/mbglib/common/mbg_arch.h b/mbglib/common/mbg_arch.h index 7bb9a3b..726e679 100755 --- a/mbglib/common/mbg_arch.h +++ b/mbglib/common/mbg_arch.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbg_arch.h 1.3.1.4 2011/06/27 16:12:59 martin TEST $ + * $Id: mbg_arch.h 1.4 2012/10/02 18:32:00 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,11 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: mbg_arch.h $ - * Revision 1.3.1.4 2011/06/27 16:12:59 martin - * Revision 1.3.1.3 2011/04/12 12:55:28 martin - * Include words.h. - * Revision 1.3.1.2 2011/02/09 15:46:48 martin - * Revision 1.3.1.1 2011/02/09 15:26:58 martin + * Revision 1.4 2012/10/02 18:32:00 martin + * Include words.h and, conditionally, stdlib.h. + * Use generic preprocessor symbol MBG_TGT_KERNEL. * Revision 1.3 2009/06/12 13:12:37Z martin * Fixed compiler warning. * Revision 1.2 2009/03/19 15:14:15 martin diff --git a/mbglib/common/mbg_tgt.h b/mbglib/common/mbg_tgt.h index fa4d71f..cbb8b50 100755 --- a/mbglib/common/mbg_tgt.h +++ b/mbglib/common/mbg_tgt.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbg_tgt.h 1.24 2011/08/23 10:21:23 martin REL_M $ + * $Id: mbg_tgt.h 1.29 2013/02/01 14:50:46 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,6 +11,17 @@ * * ----------------------------------------------------------------------- * $Log: mbg_tgt.h $ + * Revision 1.29 2013/02/01 14:50:46 martin + * Fixed a typo which caused an error under Borland CBuilder 5. + * Revision 1.28 2012/12/12 10:03:16Z martin + * Fix for Borland C 3.1. + * Revision 1.27 2012/11/29 12:03:14Z martin + * Moved definition of _no_macro_fnc() to words.h. + * Revision 1.26 2012/11/02 09:01:47Z martin + * Merged some stuff depending on the build environment here + * and cleaned up. + * Revision 1.25 2012/04/04 07:17:18 martin + * Treat QNX Neutrino as Unix target. * Revision 1.24 2011/08/23 10:21:23 martin * New symbol _NO_MBG_API_ATTR which can be used with functions * which are going to be exported by a DLL, but actually aren't, yet. @@ -98,11 +109,16 @@ /* Start of header body */ -#if defined( _CVI ) || defined( _CVI_ ) +#if defined( _CVI_ ) - #define MBG_TGT_WIN32 #define MBG_TGT_CVI + #if defined( _NI_mswin_ ) + #define MBG_TGT_WIN32 + #else + #error Unsupported CVI target platform. + #endif + #elif defined( _WIN32_WINNT ) // MS platform SDK @@ -201,13 +217,29 @@ #endif -// Some definitions which depend on the type of compiler ... -#if defined( __GNUC__ ) - #define __mbg_inline __inline__ +#if defined( MBG_TGT_FREEBSD ) \ + || defined( MBG_TGT_NETBSD ) \ + || defined( MBG_TGT_OPENBSD ) + #define MBG_TGT_BSD + + #if defined( _KERNEL ) + #define MBG_TGT_KERNEL + #endif + +#endif + +#if defined( MBG_TGT_LINUX ) \ + || defined( MBG_TGT_BSD ) + #define MBG_TGT_UNIX +#endif - #define MBG_TGT_HAS_WCHAR_T 1 + + +// Some definitions depending on the build environment ... + +#if defined( __GNUC__ ) #if defined( __i386__ ) @@ -238,20 +270,115 @@ #endif + #if defined( MBG_TGT_LINUX ) + + #if defined( __KERNEL__ ) + #include <linux/types.h> + #else + #include <sys/types.h> + #include <stdint.h> + #include <stdbool.h> + #endif + + #elif defined( MBG_TGT_BSD ) + + #include <sys/types.h> + + #elif defined( MBG_TGT_QNX_NTO ) // QNX 6.x (Neutrino) + + #include <stdint.h> + #include <stdbool.h> + + #else + + #include <stdint.h> + #include <stdbool.h> + + #endif + + #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 + + #define MBG_TGT_HAS_WCHAR_T 1 + + #define __mbg_inline __inline__ + #elif defined( _MSC_VER ) + // Known predifined MS compiler version codes: + // 1700: MSVC++ 11.0 (Visual Studio 2012) + // 1600: MSVC++ 10.0 (Visual Studio 2010) + // 1500: MSVC++ 9.0 (Visual Studio 2008) + // 1400: MSVC++ 8.0 (Visual Studio 2005) + // 1310: MSVC++ 7.1 (Visual Studio 2003) + // 1300: MSVC++ 7.0 + // 1200: MSVC++ 6.0 + // 1100: MSVC++ 5.0 + + #if ( _MSC_VER >= 1600 ) + #include <stdint.h> + #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 + #else + #define MBG_TGT_HAS_INT_8_16_32 1 + #endif + + // no bool support anyway + #define MBG_TGT_MISSING_BOOL_TYPE 1 + + #define MBG_TGT_HAS_WCHAR_T 1 + #define __mbg_inline __forceinline - #define MBG_TGT_HAS_WCHAR_T 1 +#elif defined( _CVI_ ) + + // 1000 for CVI v10.0 (CVI 2010) + // 911 for CVI v9.1.1 (CVI 2009 SP1) + // 910 for CVI v9.1 (CVI 2009) + // 310 for CVI v3.1 + // 301 for CVI v3.0.1 + // 1 for CVI v3.0 -#elif defined( _CVI ) || defined( _CVI_ ) + #if ( _CVI_ >= 910 ) + // LabWindows/CVI 2009 is the first version providing stdint.h. + #include <stdint.h> + #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 + #else + #define USE_LONG_FOR_INT32 1 + #endif - // Inline code is not supported. + // As of LabWindows/CVI 2010, stdbool.h is still missing. + #define MBG_TGT_MISSING_BOOL_TYPE 1 - #define MBG_TGT_HAS_WCHAR_T 0 + #define MBG_TGT_HAS_WCHAR_T 0 + + // Inline code is not supported, though the inline keyword + // is silently accepted since CVI v9.0 #elif defined( __BORLANDC__ ) + // 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 + #include <stdint.h> + #include <stdbool.h> + #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 + #elif ( __BORLANDC__ >= 0x0550 ) + #define MBG_TGT_HAS_INT_8_16_32 1 + #define MBG_TGT_MISSING_BOOL_TYPE 1 + #else // e.g. BC 3.1 or earlier + #if ( __BORLANDC__ <= 0x410 ) + #define MBG_TGT_MISSING_64_BIT_TYPES 1 + #define MBG_TGT_MISSING_BOOL_TYPE 1 + #define USE_LONG_FOR_INT32 1 + #endif + #endif + + #define MBG_TGT_HAS_WCHAR_T defined( MBG_TGT_WIN32 ) + #if defined( __cplusplus ) #define __mbg_inline inline // standard C++ syntax #elif ( __BORLANDC__ > 0x410 ) // BC3.1 defines 0x410 ! @@ -260,33 +387,34 @@ #define __mbg_inline // up to BC3.1 not supported for C #endif - #define MBG_TGT_HAS_WCHAR_T defined( MBG_TGT_WIN32 ) - #elif defined( __WATCOMC__ ) - #define __mbg_inline _inline + // 1050 v10.5 + // 1100 v11.0 + // 1200 Open Watcom C++ v1.0 + // 1230 Open Watcom C++ v1.3 + // 1270 Open Watcom C++ v1.7 - #define MBG_TGT_HAS_WCHAR_T defined( MBG_TGT_WIN32 ) + #if defined( MBG_TGT_QNX ) // QNX 4.x -#endif + #include <sys/types.h> + #define MBG_TGT_MISSING_64_BIT_TYPES 1 + #elif ( __WATCOMC__ > 1230 ) // Open Watcom C 1.3 and above -#if defined( MBG_TGT_FREEBSD ) \ - || defined( MBG_TGT_NETBSD ) \ - || defined( MBG_TGT_OPENBSD ) - #define MBG_TGT_BSD + #include <stdint.h> + + #elif !defined( __WATCOM_INT64__ ) // Watcom C 11 + + #define MBG_TGT_MISSING_64_BIT_TYPES 1 - #if defined( _KERNEL ) - #define MBG_TGT_KERNEL #endif -#endif + #define MBG_TGT_HAS_WCHAR_T defined( MBG_TGT_WIN32 ) + + #define __mbg_inline _inline -#if defined( MBG_TGT_LINUX ) \ - || defined( MBG_TGT_BSD ) \ - || defined( MBG_TGT_QNX_NTO ) - #define MBG_TGT_UNIX #endif @@ -377,11 +505,6 @@ #endif -#if !defined( _nop_macro_fnc ) - #define _nop_macro_fnc() do {} while (0) -#endif - - // The macros below are defined in order to be able to check if // certain C language extensions are available on the target system: #if defined( __STDC_VERSION__ ) && ( __STDC_VERSION__ >= 199409L ) diff --git a/mbglib/common/mbgddmsg.h b/mbglib/common/mbgddmsg.h index 41afbd0..32f174a 100755 --- a/mbglib/common/mbgddmsg.h +++ b/mbglib/common/mbgddmsg.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgddmsg.h 1.9.1.2 2011/11/01 09:08:48 martin TEST $ + * $Id: mbgddmsg.h 1.10 2012/10/02 18:33:21 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,11 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: mbgddmsg.h $ - * Revision 1.9.1.2 2011/11/01 09:08:48 martin - * Revision 1.9.1.1 2011/03/29 13:55:19 martin - * Also enable debug msgs if MBG_DEBUG is defined. - * Revision 1.9 2011/01/26 18:13:49 martin + * Revision 1.10 2012/10/02 18:33:21 martin * Support for *BSD. + * Also enable debug msgs if MBG_DEBUG is defined. * Revision 1.8 2009/04/22 09:54:55 martin * Include mbg_tgt.h also if building without DEBUG. * Revision 1.7 2009/03/19 15:22:54 martin diff --git a/mbglib/common/mbgdevio.c b/mbglib/common/mbgdevio.c index d556fd1..8181e56 100755 --- a/mbglib/common/mbgdevio.c +++ b/mbglib/common/mbgdevio.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgdevio.c 1.35.1.29 2011/11/25 15:03:19 martin TEST $ + * $Id: mbgdevio.c 1.36 2012/10/02 18:37:09 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,80 +10,54 @@ * * ----------------------------------------------------------------------- * $Log: mbgdevio.c $ - * Revision 1.35.1.29 2011/11/25 15:03:19 martin + * Revision 1.36 2012/10/02 18:37:09 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 in + * general and but include it when this module is built. + * Updated doxygen comments. + * New functions mbg_get_all_irig_rx_info() and + * mbg_save_all_irig_rx_settings(). + * Account for renamed macros. * Support on-board event logs. - * Revision 1.35.1.28 2011/11/23 18:18:50 martin - * Fixed build under DOS. - * Revision 1.35.1.27 2011/11/23 16:41:14Z martin * New functions mbg_dev_has_debug_status() and * mbg_get_debug_status(). - * Revision 1.35.1.26 2011/09/26 13:58:54 martin * Added a workaround to make mbgmon (BC) build under Windows. * In mbg_get_serial_settings() return an error if the number of provided * serial ports or supported string types exceeds the numbers supported * by the driver. * Moved mbg_get_serial_settings() and mbg_save_serial_settings() * to an extra file. These functions expect parameters the sizes of - * which might change in future API versions, which would make + * which might change in future API versions, which would make * functions exported by shared libraries incompatible across versions. * Made functions mbg_get_gps_all_port_info() and * mbg_get_gps_all_str_type_info() non-static so they are now exported * by the shared libraries built from this module. * Include cfg_hlp.h. - * Revision 1.35.1.25 2011/07/20 15:50:51Z martin * Conditionally use older IOCTL request buffer structures. * Moved some macros etc. to the .h file. - * Modified some macros. - * Revision 1.35.1.24 2011/07/14 14:54:00 martin * 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. - * Revision 1.35.1.23 2011/07/08 10:11:00 martin - * Fixes for DOS. - * Revision 1.35.1.22 2011/07/06 11:19:20Z martin * Support reading CORR_INFO, and reading/writing TR_DISTANCE. - * Revision 1.35.1.21 2011/06/29 11:09:55 martin * Added mbg_dev_has_pzf() function. - * Revision 1.35.1.20 2011/06/27 13:02:50 martin - * Use O_RDWR flag when opening a device. - * Revision 1.35.1.19 2011/06/24 11:13:36 martin - * Revision 1.35.1.18 2011/06/22 10:05:45 martin * Support PTP unicast configuration. * Account for some IOCTL codes renamed to follow common naming conventions. - * Revision 1.35.1.17 2011/04/12 12:56:20 martin * Renamed mutex stuff to critical sections. - * Revision 1.35.1.16 2011/03/31 13:18:46 martin - * Coding style. - * Revision 1.35.1.15 2011/02/16 10:15:13 martin - * Revision 1.35.1.14 2011/02/15 14:24:55Z martin - * Revision 1.35.1.13 2011/02/15 11:21:47 daniel * Added API calls to support PTP unicast. - * Revision 1.35.1.12 2011/02/09 17:08:28Z martin * Specify I/O range number when calling port I/O macros * so they can be used for different ranges under BSD. - * Revision 1.35.1.11 2011/02/01 15:08:08 martin - * Revision 1.35.1.10 2011/01/28 09:33:21 martin * Modifications to support FreeBSD. - * Revision 1.35.1.9 2010/12/14 11:23:47 martin * Moved definition of MBG_HW_NAME to the header file. - * Revision 1.35.1.8 2010/12/14 10:56:33Z martin - * Revision 1.35.1.7 2010/08/18 13:43:20 martin - * Revision 1.35.1.6 2010/08/11 13:48:52 martin - * Cleaned up comments. - * Revision 1.35.1.5 2010/08/11 12:43:51 martin - * Revision 1.35.1.4 2010/05/21 13:10:37 martin - * Fixed platforms where cycles are not supported. - * Revision 1.35.1.3 2010/04/26 14:46:41 martin * Compute PC cycles frequency under Linux if cpu_tick is not set by the kernel. - * Revision 1.35.1.2 2010/02/09 14:05:38 stefan * Fixed a bug that kept the function mbg_open_device_by_name in a loop under certain conditions. - * Revision 1.35.1.1 2010/02/05 11:49:26 martin * Made xhrt leap second check an inline function. * Revision 1.35 2010/01/12 13:40:25 martin * Fixed a typo in mbg_dev_has_raw_irig_data(). * Revision 1.34 2009/12/15 15:34:58Z 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.33 2009/09/29 15:08:40Z martin * Support retrieving time discipline info. @@ -95,7 +69,7 @@ * Revision 1.30 2009/06/19 12:19:41Z martin * Support reading raw IRIG time. * Revision 1.29 2009/06/08 18:23:22 daniel - * Added PTP configuration functions and PTP state functions, but + * Added PTP configuration functions and PTP state functions, but * they are still excluded from build. * Added calls to support simple LAN interface configuration. * Revision 1.28 2009/03/19 15:30:04 martin @@ -111,30 +85,30 @@ * Account for renamed IOCTL codes. * Revision 1.27 2008/12/17 10:37:37 martin * Fixed a bug in mbg_open_device_by_name() with sel. mode MBG_MATCH_ANY. - * Support variable read buffer sizes under Linux, so + * Support variable read buffer sizes under Linux, so * mbg_get_all_port_info() and mbg_get_all_str_type_info() * can now be used under Linux. * Support PC cycles under Linux via inline rdtsc call. * Use predefined constants to convert fractions. - * New API calls mbg_get_fast_hr_timestamp_cycles(), and + * New API calls mbg_get_fast_hr_timestamp_cycles(), and * mbg_get_fast_hr_timestamp_comp() which take memory mapped HR time stamps - * in kernel space, and mbg_dev_has_fast_hr_timestamp() to check whether + * in kernel space, and mbg_dev_has_fast_hr_timestamp() to check whether * this is supported by a device. * Removed mm_*() functions since these are obsolete now. - * Support extrapolated HR time (xhrt) for Windows and Linux - * by providing a function mbg_xhrt_poll_thread_create() which + * Support extrapolated HR time (xhrt) for Windows and Linux + * by providing a function mbg_xhrt_poll_thread_create() which * starts a poll thread for a specific device which to read * HR time plus associated cycles in regular intervals. * Added functions mbg_get_process_affinity(), mbg_set_process_affinity(), - * and mbg_set_current_process_affinity_to_cpu(), and mbg_create_thread() + * and mbg_set_current_process_affinity_to_cpu(), and mbg_create_thread() * and mbg_set_thread_affinity() to control the extrapolation feature. * Use new preprocessor symbol MBGDEVIO_HAVE_THREAD_AFFINITY. * Added new functions mbg_get_xhrt_time_as_pcps_hr_time() and - * mbg_get_xhrt_time_as_filetime() (Windows only) to retrieve + * mbg_get_xhrt_time_as_filetime() (Windows only) to retrieve * fast extrapolated timestamps. - * Added function mbg_get_xhrt_cycles_frequency() to retrieve the + * Added function mbg_get_xhrt_cycles_frequency() to retrieve the * cycles counter frequency computed by the polling thread. - * Added function mbg_get_default_cycles_frequency_from_dev(), + * Added function mbg_get_default_cycles_frequency_from_dev(), * and mbg_get_default_cycles_frequency() (Windows only). * Moved mbg_open_device..() functions upwards. * Made device_info_list common. @@ -146,7 +120,7 @@ * Account Linux for device names renamed from /dev/mbgclk to /dev/mbgclock. * Support bigendian target platforms. * Revision 1.26 2008/02/26 16:54:21 martin - * New/changed functions for memory mapped access which are + * New/changed functions for memory mapped access which are * currently excluded from build. * Changed separator for device names from ' ' to '_'. * Added new type MBG_HW_NAME. @@ -161,10 +135,10 @@ * Revision 1.23 2008/01/30 10:32:35Z daniel * Renamed mapped memory funtions. * Revision 1.22 2008/01/25 15:27:42Z daniel - * Fixed a bug in mbg_get_hr_time_comp() where an overflow + * Fixed a bug in mbg_get_hr_time_comp() where an overflow * of the fractions was handled with wrong sign. * Revision 1.21 2008/01/17 15:49:59Z daniel - * Added functions mbg_find_devices_with_hw_id() and + * Added functions mbg_find_devices_with_hw_id() and * mbg_free_devics_list() to work with Linux Win32 OSs. * Added Doxygen compliant comments for API functions. * Support for mapped memory I/O under linux and windows. @@ -201,27 +175,27 @@ * Unified macros for Win32 and Linux. * Fixed warning under Win32 using type cast. * Revision 1.15 2005/01/31 16:44:21Z martin - * Added function mbg_get_hr_time_comp() which returns HR time stamp + * Added function mbg_get_hr_time_comp() which returns HR time stamp * which has latency compensated. * Revision 1.14 2005/01/14 10:22:23Z martin * Added functions which query device features. * Revision 1.13 2004/12/09 11:23:59Z martin * Support configuration of on-board frequency synthesizer. * Revision 1.12 2004/11/09 14:11:07Z martin - * 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. - * Renamed functions mbg_get_irig_info() and mbg_set_irig_settings() - * to mbg_get_irig_rx_info() and mbg_set_irig_rx_settings() + * Renamed functions mbg_get_irig_info() and mbg_set_irig_settings() + * to mbg_get_irig_rx_info() and mbg_set_irig_rx_settings() * New functions mbg_get_irig_tx_info() and mbg_set_irig_tx_settings(). * All API functions now use well defined parameter types instead of * generic types. Some new types have been defined therefore. * Added a workaround for GPS169PCI cards with early firmware versions - * which used the same codes to configure the IRIG output as the TCR - * cards use to configure the IRIG input. Those codes are now + * which used the same codes to configure the IRIG output as the TCR + * cards use to configure the IRIG input. Those codes are now * exclusively used to configure the IRIG input. The workaround - * has been included in order to let GPS169PCI cards work properly + * has been included in order to let GPS169PCI cards work properly * after a driver update, without requiring a firmware update. - * The macro _pcps_ddev_requires_irig_workaround() is used to check + * The macro _pcps_ddev_requires_irig_workaround() is used to check * if the workaround is required. * Renamed function mbg_get_gps_stat() to mbg_get_gps_bvar_stat(). * Revision 1.11 2004/08/17 11:13:45Z martin @@ -244,7 +218,7 @@ * New functions mbgdevio_get_version() and mbgdevio_check_version(). * New functions for generic read/write access. * New functions mbg_get_pcps_tzdl() and mbg_set_pcps_tzdl(). - * Fixed a bug passing the wrong command code to a + * Fixed a bug passing the wrong command code to a * direct access target in mbg_get_sync_time(). * Return driver info for direct access targets. * Include pcpsdrvr.h and pcps_dos.h, if applicable. @@ -262,7 +236,7 @@ * Extended macro calls for direct access targets. * Updated macros for Linux. * Revision 1.5 2003/04/15 19:35:25Z martin - * New functions mbg_setup_receiver_info(), + * New functions mbg_setup_receiver_info(), * mbg_get_serial_settings(), mbg_save_serial_settings(). * Revision 1.4 2003/04/09 16:07:16Z martin * New API functions mostly complete. @@ -270,7 +244,7 @@ * Added DllEntry function foe Win32. * Made MBG_Device_count and MBG_Device_Path local. * Revision 1.3 2003/01/24 13:44:40Z martin - * Fixed get_ref_time_from_driver_at_sec_change() to be used + * Fixed get_ref_time_from_driver_at_sec_change() to be used * with old kernel drivers. * Revision 1.2 2002/09/06 11:04:01Z martin * Some old API functions have been replaced by new ones @@ -296,7 +270,11 @@ #include <mbg_dpmi.h> #endif -#if !defined( MBG_USE_KERNEL_DRIVER ) +#if defined( MBG_USE_KERNEL_DRIVER ) + + #include <mbgioctl.h> + +#else #include <pcpsdrvr.h> #include <pci_asic.h> @@ -310,11 +288,11 @@ #define MAX_INFO_LEN 260 -typedef struct +typedef struct { - MBG_HW_NAME hw_name; + MBG_HW_NAME hw_name; char model_name[PCPS_CLOCK_NAME_SZ]; - PCPS_SN_STR serial_number; + PCPS_SN_STR serial_number; char hardware_id[MAX_INFO_LEN]; // OS dependent hardware_id to identify and open the device } MBG_DEVICE_INFO; @@ -464,6 +442,59 @@ static MBG_DEVICE_INFO device_info_list[MBG_MAX_DEVICES]; +/*HDR*/ +/** + 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 ) +{ + + return MBGDEVIO_VERSION; + +} // mbgdevio_get_version + + + +/*HDR*/ +/** + @brief Check if the DLL/shared library is compatible with a given version. + + If this library is used as a DLL/shared object library then the version + number can be checked to see if the header files which are actually used + to build an application are compatible with the header files which have + been used to build the library, and thus the API function are called + in the correct way. + + @param header_version Version number to be checked, should be ::MBGDEVIO_VERSION + from the mbgdevio.h file used to build the application + + @return ::MBG_SUCCESS if compatible, ::MBG_ERR_LIB_NOT_COMPATIBLE if not. + + @see mbgdevio_get_version() + @see ::MBGDEVIO_VERSION defined in mbgdevio.h + */ +_MBG_API_ATTR int _MBG_API mbgdevio_check_version( int header_version ) +{ + if ( header_version >= MBGDEVIO_COMPAT_VERSION ) + return MBG_SUCCESS; + + return _mbg_err_to_os( MBG_ERR_LIB_NOT_COMPATIBLE ); + +} // mbgdevio_check_version + + + static /*HDR*/ //##++ make this public ? int mbg_comp_hr_latency( PCPS_TIME_STAMP *ts, const MBG_PC_CYCLES *p_cyc_ts, @@ -499,7 +530,7 @@ int mbg_comp_hr_latency( PCPS_TIME_STAMP *ts, cyc_latency += ( (uint64_t) -1 ) >> 1; #if DEBUG && defined( MBG_TGT_LINUX ) - printf( "->%lli (%llX)", + printf( "->%lli (%llX)", (unsigned long long) cyc_latency, (unsigned long long) ( ( (uint64_t) -1 ) >> 1 ) ); @@ -563,57 +594,14 @@ int mbg_comp_hr_latency( PCPS_TIME_STAMP *ts, /*HDR*/ /** - Get the version number of the compiled mbgdevio library. - If the mbgdevio library is built as a DLL/shared object then - the version number of the compiled library may differ from - the version number of the import library and header files - which have been used to build an application. - - @return The version number + @brief Open a device by index, starting from 0. - @see ::MBGDEVIO_VERSION defined in mbgdevio.h. - */ -_MBG_API_ATTR int _MBG_API mbgdevio_get_version( void ) -{ - - return MBGDEVIO_VERSION; - -} // mbgdevio_get_version - - - -/*HDR*/ -/** - Check if the version of the compiled mbgdevio library is compatible - with a certain version which is passed as parameter. - - @param header_version Version number to be checked, should be ::MBGDEVIO_VERSION - defined in mbgdevio.h. - - @return ::MBG_SUCCESS if compatible, ::MBG_ERR_LIB_NOT_COMPATIBLE if not. - - @see ::MBGDEVIO_VERSION defined in mbgdevio.h. - */ -_MBG_API_ATTR int _MBG_API mbgdevio_check_version( int header_version ) -{ - if ( header_version >= MBGDEVIO_COMPAT_VERSION ) - return MBG_SUCCESS; - - return _mbg_err_to_os( MBG_ERR_LIB_NOT_COMPATIBLE ); - -} // mbgdevio_check_version - - - -/*HDR*/ -/** - Open a device by index, starting from 0. - This function is <b>out of date</b>, mbg_open_device_by_name() + This function is <b>out of date</b>, mbg_open_device_by_name() should be used instead. See the <b>note</b> for mbg_find_device() for details. - @param device_index Index of the device, use 0 for the first device. + @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 ) { @@ -628,7 +616,7 @@ _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device( unsigned int device_index goto fail; - dh = CreateFile( + dh = CreateFile( device_path, // file name GENERIC_READ | GENERIC_WRITE, // access mode 0, // share mode @@ -678,11 +666,12 @@ fail: static /*HDR*/ /* (Intentionally excluded from Doxygen) - Return a handle to a device specified by a given hardware_id. - The format the hardware_id depends on the operating system, so - this function is used only internally to detect devices for - which a unique name of the format MBG_HW_NAME is generated, - which is in turn used with the public API functions. + @brief Return a handle to a device specified by a given hardware_id. + + The format the hardware_id depends on the operating system, so + this function is used only internally to detect devices for + which a unique name of the format MBG_HW_NAME is generated, + which is in turn used with the public API functions. */ MBG_DEV_HANDLE _MBG_API mbg_open_device_by_hw_id( const char* hw_id ) { @@ -695,7 +684,7 @@ MBG_DEV_HANDLE _MBG_API mbg_open_device_by_hw_id( const char* hw_id ) if ( hw_id == NULL ) goto fail; - dh = CreateFile( + dh = CreateFile( hw_id, // file name GENERIC_READ | GENERIC_WRITE, // access mode 0, // share mode @@ -734,18 +723,19 @@ fail: /*HDR*/ /** - Get the number of supported devices installed on the computer. - This function is <b>out of date</b>, mbg_find_devices_with_names() + @brief Get the number of supported devices installed on the computer. + + This function is <b>out of date</b>, mbg_find_devices_with_names() should be used instead. - <b>Note:</b> This function is out of date since it may not work + <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 + 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. + @return The number of devices found @see mbg_find_devices_with_names() */ @@ -966,32 +956,31 @@ void get_hw_name_from_hw_id( MBG_DEVICE_INFO *dev_info ) /*HDR*/ /** - Return the number of supported devices installed on the system and - set up a list of unique names of those devices. + @brief Allocate memory and set up a list of installed and supported devices. This function should be used preferably instead of mbg_find_devices(). - @param 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 + @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 + @param max_devices Maximum number of devices the function should look for (can not exceed ::MBG_MAX_DEVICES). - @return Number of present devices + @return number of present devices @see ::MBG_HW_NAME for the format of the unique names @see mbg_free_device_name_list() @see mbg_find_devices() */ -_MBG_API_ATTR int _MBG_API mbg_find_devices_with_names( MBG_DEVICENAME_LIST **device_list, +_MBG_API_ATTR int _MBG_API mbg_find_devices_with_names( MBG_DEVICENAME_LIST **device_list, int max_devices ) { #if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_UNIX ) MBG_DEVICE_LIST *hardware_list = NULL; MBG_DEVICE_LIST *hardware_list_begin = NULL; - MBG_DEVICENAME_LIST *ListBegin = NULL; + MBG_DEVICENAME_LIST *ListBegin = NULL; MBG_DEVICE_INFO dev_info; int n_devices = 0; @@ -1054,7 +1043,9 @@ _MBG_API_ATTR int _MBG_API mbg_find_devices_with_names( MBG_DEVICENAME_LIST **de /*HDR*/ /** - Free the memory of the ::MBG_DEVICENAME_LIST that has been allocated before + @brief Free the memory allocated for a ::MBG_DEVICENAME_LIST. + + The list may have been set up and allocated before by mbg_find_devices_with_names(). @param *list Linked list of type ::MBG_DEVICENAME_LIST @@ -1097,7 +1088,8 @@ _MBG_API_ATTR void _MBG_API mbg_free_device_name_list( MBG_DEVICENAME_LIST *list /*HDR*/ /** - Return a handle to a device with a certain unique name. + @brief Return a handle to a device with a certain unique name. + The names of the devices that are installed on the system can be retrieved by the function mbg_find_devices_with_names(). @@ -1134,22 +1126,22 @@ _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const char* hw_na memset( device_info_list, 0, sizeof( device_info_list ) ); memset( tmp_sn, 0, sizeof( tmp_sn ) ); - // separate hw_name into clock model and serial number + // separate hw_name into clock model and serial number if ( hw_name && ( strlen( hw_name ) > 0 ) ) { // clock model - for ( i = 0; ( i < PCPS_CLOCK_NAME_SZ ) && ( hw_name[i] != '_' ) && ( (unsigned int) i < strlen( hw_name ) ); i++ ) + for ( i = 0; ( i < PCPS_CLOCK_NAME_SZ ) && ( hw_name[i] != '_' ) && ( i < (int) strlen( hw_name ) ); i++ ) tmp_model_name[i] = hw_name[i]; tmp_model_name[i] = 0; i++; // serial number - if ( ( unsigned int ) i < strlen( hw_name ) ) + if ( i < (int) strlen( hw_name ) ) { j = 0; - while( ( unsigned int ) i < strlen(hw_name) && j < PCPS_SN_SIZE ) + while ( ( i < (int) strlen( hw_name ) ) && ( j < PCPS_SN_SIZE ) ) { tmp_sn[j] = hw_name[i]; j++; @@ -1192,6 +1184,7 @@ _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const char* hw_na } else break; + i++; } @@ -1224,7 +1217,7 @@ _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const char* hw_na if ( hw_id[0] == '\0' ) goto fail; - dh = CreateFile( + dh = CreateFile( hw_id, // file name GENERIC_READ | GENERIC_WRITE, // access mode 0, // share mode @@ -1267,8 +1260,7 @@ fail: /*HDR*/ /** - Close a handle to a device and set the handle value to ::MBG_INVALID_DEV_HANDLE. - If required, unmap mapped memory. + @brief Close a handle to a device and set the handle value to ::MBG_INVALID_DEV_HANDLE. @param dev_handle Handle to a Meinberg device. */ @@ -1291,8 +1283,7 @@ _MBG_API_ATTR void _MBG_API mbg_close_device( MBG_DEV_HANDLE *dev_handle ) /*HDR*/ /** - Return a ::PCPS_DRVR_INFO structure that provides information - about the kernel device driver. + @brief Read information about the driver handling a given device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_DRVR_INFO structure which is filled up. @@ -1320,7 +1311,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_drvr_info( MBG_DEV_HANDLE dh, PCPS_DRVR_INFO /*HDR*/ /** - Return a ::PCPS_DEV structure that provides detailed information about the device. + @brief Read detailed device information. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_DEV structure to be filled up @@ -1345,7 +1336,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_device_info( MBG_DEV_HANDLE dh, PCPS_DEV *p ) /*HDR*/ /** - Return the current state of the on-board::PCPS_STATUS_PORT. + @brief Read the current state of the on-board ::PCPS_STATUS_PORT. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_STATUS_PORT value to be filled up @@ -1373,7 +1364,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_status_port( MBG_DEV_HANDLE dh, PCPS_STATUS_P /*HDR*/ /* (Intentionally excluded from Doxygen) - Generic read function which writes a command code to the device + 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! @@ -1397,7 +1388,7 @@ _MBG_API_ATTR int _MBG_API mbg_generic_read( MBG_DEV_HANDLE dh, int cmd, { _mbgdevio_vars(); rc = _mbgdevio_gen_read( dh, cmd, p, size ); - // No type information available, so endianess must be + // No type information available, so endianess must be // converted by the caller, if required. return _mbgdevio_ret_val; @@ -1407,10 +1398,10 @@ _MBG_API_ATTR int _MBG_API mbg_generic_read( MBG_DEV_HANDLE dh, int cmd, /*HDR*/ /* (Intentionally excluded from Doxygen) - Generic read function which writes a GPS command code to the device + 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 specific card. + 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. @@ -1434,7 +1425,7 @@ _MBG_API_ATTR int _MBG_API mbg_generic_read_gps( MBG_DEV_HANDLE dh, int cmd, { _mbgdevio_vars(); rc = _mbgdevio_gen_read_gps( dh, cmd, p, size ); - // No type information available, so endianess must be + // No type information available, so endianess must be // converted by the caller, if required. return _mbgdevio_ret_val; @@ -1444,8 +1435,8 @@ _MBG_API_ATTR int _MBG_API mbg_generic_read_gps( MBG_DEV_HANDLE dh, int cmd, /*HDR*/ /* (Intentionally excluded from Doxygen) - Generic write function which writes a command code plus an - associated number of data bytes to the device. + 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. @@ -1467,7 +1458,7 @@ _MBG_API_ATTR int _MBG_API mbg_generic_write( MBG_DEV_HANDLE dh, int cmd, const void *p, int size ) { _mbgdevio_vars(); - // No type information available, so endianess must be + // No type information available, so endianess must be // converted by the caller, if required. rc = _mbgdevio_gen_write( dh, cmd, p, size ); return _mbgdevio_ret_val; @@ -1478,10 +1469,10 @@ _MBG_API_ATTR int _MBG_API mbg_generic_write( MBG_DEV_HANDLE dh, int cmd, /*HDR*/ /* (Intentionally excluded from Doxygen) - Generic write function which writes a GPS command code plus an - associated number of data bytes to the device. + 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 specific card. + 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. @@ -1504,7 +1495,7 @@ _MBG_API_ATTR int _MBG_API mbg_generic_write_gps( MBG_DEV_HANDLE dh, int cmd, const void *p, int size ) { _mbgdevio_vars(); - // No type information available, so endianess must be + // No type information available, so endianess must be // converted by the caller, if required. rc = _mbgdevio_gen_write_gps( dh, cmd, p, size ); return _mbgdevio_ret_val; @@ -1517,7 +1508,7 @@ _MBG_API_ATTR int _MBG_API mbg_generic_write_gps( MBG_DEV_HANDLE dh, int cmd, /* (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 specific card. + check whether this call is supported by a device. <b>Warning</b>: This call is for debugging purposes and internal use only! @@ -1552,13 +1543,15 @@ _MBG_API_ATTR int _MBG_API mbg_generic_io( MBG_DEV_HANDLE dh, int type, /*HDR*/ /** - 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, + @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). - This call is supported by any device manufactured by Meinberg. However, - for higher accuracy and resolution the mbg_get_hr_time..() group of calls - should be used preferably if supported by the specific device. + 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. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_TIME structure to be filled up @@ -1582,9 +1575,10 @@ _MBG_API_ATTR int _MBG_API mbg_get_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) /*HDR*/ /** - Set a device's on-board clock manually by passing a ::PCPS_STIME structure - The macro _pcps_can_set_time() checks whether this call - is supported by a specific card. + @brief Set the device's on-board clock to a given date and time. + + The macro _pcps_can_set_time() checks whether this call + is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_STIME structure to be written @@ -1607,18 +1601,20 @@ _MBG_API_ATTR int _MBG_API mbg_set_time( MBG_DEV_HANDLE dh, const PCPS_STIME *p /*HDR*/ /** - Read a ::PCPS_TIME structure returning the date/time/status reporting - when the device was synchronized the last time to its time source, - e.g. the DCF77 signal or the GPS satellites. - The macro _pcps_has_sync_time() or the API call mbg_dev_has_sync_time() - check whether this call is supported by a specific card. + @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() or the API call mbg_dev_has_sync_time() + check whether this call is supported by a device. - The macro _pcps_has_sync_time() checks whether this call - is supported by a specific card. + 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 + <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. @param dh Valid handle to a Meinberg device @@ -1642,11 +1638,12 @@ _MBG_API_ATTR int _MBG_API mbg_get_sync_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) /*HDR*/ /** - Wait until the next second change, then return a ::PCPS_TIME - structure similar to mbg_get_time(). + @brief Wait until the next second change, then return current time. - <b>Note:</b> This API call is supported under Windows only. - The call blocks until the kernel driver detects a second change + 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. @param dh Valid handle to a Meinberg device @@ -1676,16 +1673,18 @@ _MBG_API_ATTR int _MBG_API mbg_get_time_sec_change( MBG_DEV_HANDLE dh, PCPS_TIME /*HDR*/ /** - Read a ::PCPS_HR_TIME (High Resolution time) structure returning + @brief Read the card's current time with high resolution, plus status. + + Fills up a ::PCPS_HR_TIME (High Resolution time) structure containing the current %UTC time (seconds since 1970), %UTC offset, and status. - The macro _pcps_has_hr_time() or the API call mbg_dev_has_hr_time() - check whether this call is supported by a specific card. + The macro _pcps_has_hr_time() or the API call mbg_dev_has_hr_time() + check whether this call is supported by a device. - <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. + <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 - provides mechanisms to account for and/or compensate the latency. + provide ways to account for and/or compensate the latency. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_HR_TIME structure to be filled up @@ -1711,10 +1710,10 @@ _MBG_API_ATTR int _MBG_API mbg_get_hr_time( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) /*HDR*/ /* (Intentionally excluded from Doxygen ) - Write a high resolution time stamp ::PCPS_TIME_STAMP to the clock + 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 specific card. + The macro _pcps_has_event_time() or the API call mbg_dev_has_event_time() + check whether this call is supported by a device. <b>Note:</b> This is only supported by some special firmware. @@ -1743,13 +1742,15 @@ _MBG_API_ATTR int _MBG_API mbg_set_event_time( MBG_DEV_HANDLE dh, const PCPS_TIM /*HDR*/ /** - Read the configuration of a device's serial port. - The macro _pcps_has_serial() checks whether this call - is supported by a specific card. + @brief Read the serial port configuration from an old type of device. + + <b>Note:</b> Direct usage of this function is obsolete. - <b>Note:</b> This function is supported only by a certain class - of devices, so it should not be called directly. The generic - function mbg_get_serial_settings() should be used instead. + The generic API function mbg_get_serial_settings() should be used instead + which fully supports the capabilities of current devices. + + The macro _pcps_has_serial() checks whether this call + is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_SERIAL structure to be filled up @@ -1772,13 +1773,15 @@ _MBG_API_ATTR int _MBG_API mbg_get_serial( MBG_DEV_HANDLE dh, PCPS_SERIAL *p ) /*HDR*/ /** - Write the configuration of a device's serial port. - The macro _pcps_has_serial() checks whether this call - is supported by a specific card. + @brief Write the serial port configuration to an old type of device. + + <b>Note:</b> Direct usage of this function is obsolete. - <b>Note:</b> This function is supported only by a certain class - of devices, so it should not be called directly. The generic - function mbg_save_serial_settings() should be used instead. + The generic API function mbg_save_serial_settings() should be used instead + which fully supports the capabilities of current devices. + + The macro _pcps_has_serial() checks whether this call + is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_SERIAL structure to be written @@ -1801,13 +1804,16 @@ _MBG_API_ATTR int _MBG_API mbg_set_serial( MBG_DEV_HANDLE dh, const PCPS_SERIAL /*HDR*/ /** - Read the card's time zone/daylight saving configuration code. - That tzcode is supported by some simpler cards and only allows only - a very basic configuration. - The macro _pcps_has_tzcode() or the API call mbg_dev_has_tzcode() - check whether this call is supported by a specific card. + @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 macro _pcps_has_tzcode() or the API call mbg_dev_has_tzcode() + check whether this call is supported by a device. + 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 + calls instead which allow for a more detailed configuration of the time zone and daylight saving settings. @param dh Valid handle to a Meinberg device @@ -1835,13 +1841,16 @@ _MBG_API_ATTR int _MBG_API mbg_get_tzcode( MBG_DEV_HANDLE dh, PCPS_TZCODE *p ) /*HDR*/ /** - Write the card's time zone/daylight saving configuration code. - That tzcode is supported by some simpler cards and only allows only - a very basic configuration. - The macro _pcps_has_tzcode() or the API call mbg_dev_has_tzcode() - check whether this call is supported by a specific card. + @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 macro _pcps_has_tzcode() or the API call mbg_dev_has_tzcode() + check whether this call is supported by a device. + 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 + calls instead which allow for a more detailed configuration of the time zone and daylight saving settings. @param dh Valid handle to a Meinberg device @@ -1869,12 +1878,17 @@ _MBG_API_ATTR int _MBG_API mbg_set_tzcode( MBG_DEV_HANDLE dh, const PCPS_TZCODE /*HDR*/ /** - Read the card's time zone/daylight saving parameters using the - ::PCPS_TZDL structure. - The macro _pcps_has_pcps_tzdl() or the API call mbg_dev_has_pcps_tzdl() - check whether this call is supported by a specific card. - Other cards may support the mbg_get_tzcode() or mbg_get_gps_tzdl() - calls instead. + @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 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_get_tzcode() or mbg_get_gps_tzdl() + calls instead. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_TZDL structure to be filled up @@ -1901,12 +1915,16 @@ _MBG_API_ATTR int _MBG_API mbg_get_pcps_tzdl( MBG_DEV_HANDLE dh, PCPS_TZDL *p ) /*HDR*/ /** - Write the card's time zone/daylight saving parameters using the - ::PCPS_TZDL structure. - The macro _pcps_has_pcps_tzdl() or the API call mbg_dev_has_pcps_tzdl() - check whether this call is supported by a specific card. - Other cards may support the mbg_set_tzcode() or mbg_set_gps_tzdl() - calls instead. + @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 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. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_TZDL structure to be written @@ -1937,10 +1955,14 @@ _MBG_API_ATTR int _MBG_API mbg_set_pcps_tzdl( MBG_DEV_HANDLE dh, const PCPS_TZDL /*HDR*/ /** - Read the reference time offset from %UTC for clocks which can't determine - that offset automatically, e.g. from an IRIG input signal. - The macro _pcps_has_ref_offs() or the API call mbg_dev_has_ref_offs() - check whether this call is supported by a specific card. + @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 macro _pcps_has_ref_offs() or the API call mbg_dev_has_ref_offs() + check whether this call is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::MBG_REF_OFFS value to be filled up @@ -1965,10 +1987,14 @@ _MBG_API_ATTR int _MBG_API mbg_get_ref_offs( MBG_DEV_HANDLE dh, MBG_REF_OFFS *p /*HDR*/ /** - Write the reference time offset from %UTC for clocks which can't determine - that offset automatically, e.g. from an IRIG input signal. - The macro _pcps_has_ref_offs() or the API call mbg_dev_has_ref_offs() - check whether this call is supported by a specific card. + @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 macro _pcps_has_ref_offs() or the API call mbg_dev_has_ref_offs() + check whether this call is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::MBG_REF_OFFS value to be written @@ -1997,11 +2023,12 @@ _MBG_API_ATTR int _MBG_API mbg_set_ref_offs( MBG_DEV_HANDLE dh, const MBG_REF_OF /*HDR*/ /** - 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 + @brief Read a ::MBG_OPT_INFO structure containing optional settings, controlled by flags. + + The ::MBG_OPT_INFO structure contains a mask of supported flags plus the current settings of those flags. - The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags() - check whether this call is supported by a specific card. + The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags() + check whether this call is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::MBG_OPT_INFO structure to be filled up @@ -2025,11 +2052,12 @@ _MBG_API_ATTR int _MBG_API mbg_get_opt_info( MBG_DEV_HANDLE dh, MBG_OPT_INFO *p /*HDR*/ /** - Write a ::MBG_OPT_SETTINGS structure contains optional settings, controlled by flags. - The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags() - check whether this call is supported by a specific card. - The ::MBG_OPT_INFO structure should be read first to check which of the specified - flags is supported by a specific card. + @brief Write a ::MBG_OPT_SETTINGS structure containing optional device settings. + + The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags() + check whether this call is supported by a device. + The ::MBG_OPT_INFO structure should be read first to check which of the specified + flag is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::MBG_OPT_SETTINGS structure to be written @@ -2058,16 +2086,21 @@ _MBG_API_ATTR int _MBG_API mbg_set_opt_settings( MBG_DEV_HANDLE dh, const MBG_OP /*HDR*/ /** - Read an ::IRIG_INFO structure containing the configuration of an IRIG input - plus the possible settings supported by that input. - The macro _pcps_is_irig_rx() or the API call mbg_dev_is_irig_rx() - check whether this call is supported by a specific card. + @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() @@ -2088,10 +2121,15 @@ _MBG_API_ATTR int _MBG_API mbg_get_irig_rx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p /*HDR*/ /** - Write an ::IRIG_SETTINGS structure containing the configuration of an 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 specific card. - The ::IRIG_INFO structure should be read first to determine the possible + @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 @@ -2099,6 +2137,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_irig_rx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p @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() @@ -2124,7 +2163,96 @@ _MBG_API_ATTR int _MBG_API mbg_set_irig_rx_settings( MBG_DEV_HANDLE dh, const IR /*HDR*/ /** - Check if a specific device supports the mbg_get_irig_ctrl_bits() call. + @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() +*/ +_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 ) +{ + int rc; + + if ( !_pcps_is_irig_rx( pdev ) ) + return _mbg_err_to_os( MBG_ERR_NOT_SUPP_BY_DEV ); + + rc = mbg_get_irig_rx_info( dh, p_irig_info ); + + if ( rc == MBG_SUCCESS && _pcps_has_ref_offs( pdev ) ) + rc = mbg_get_ref_offs( dh, p_ref_offs ); + + if ( rc == MBG_SUCCESS && _pcps_has_opt_flags( pdev ) ) + rc = mbg_get_opt_info( dh, p_opt_info ); + + return rc; + +} // mbg_get_all_irig_rx_info + + + +/*HDR*/ +/** + @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() +*/ +_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 ) +{ + int rc; + + if ( !_pcps_is_irig_rx( pdev ) ) + return _mbg_err_to_os( MBG_ERR_NOT_SUPP_BY_DEV ); + + rc = mbg_set_irig_rx_settings( dh, p_irig_settings ); + + if ( rc == MBG_SUCCESS && _pcps_has_ref_offs( pdev ) ) + rc = mbg_set_ref_offs( dh, p_ref_offs ); + + if ( rc == MBG_SUCCESS && _pcps_has_opt_flags( pdev ) ) + rc = mbg_set_opt_settings( dh, p_opt_settings ); + + return rc; + +} // mbg_save_all_irig_rx_settings + + + +/*HDR*/ +/** + @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. @@ -2143,14 +2271,27 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh, int *p /*HDR*/ /** - Read a ::MBG_IRIG_CTRL_BITS type which contains 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. + @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 specific card. + 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 @@ -2173,7 +2314,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_irig_ctrl_bits( MBG_DEV_HANDLE dh, /*HDR*/ /** - Check if a specific device supports the mbg_get_raw_irig_data() call. + @brief Check if a device supports the mbg_get_raw_irig_data() call. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2193,10 +2334,14 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_raw_irig_data( MBG_DEV_HANDLE dh, int *p /*HDR*/ /** - Read a ::MBG_RAW_IRIG_DATA type which contains all data - bits of the latest IRIG input frame. + @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 specific card. + 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 @@ -2220,10 +2365,13 @@ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data( MBG_DEV_HANDLE dh, /*HDR*/ /** - Read a ::MBG_RAW_IRIG_DATA type just after a second change which contains all data - bits of the latest IRIG input frame. + @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 specific card. + 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. @@ -2235,6 +2383,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data( MBG_DEV_HANDLE dh, @see mbg_dev_has_raw_irig_data() @see mbg_get_raw_irig_data() + @see mbg_get_time_sec_change() */ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data_on_sec_change( MBG_DEV_HANDLE dh, MBG_RAW_IRIG_DATA *p ) @@ -2255,7 +2404,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data_on_sec_change( MBG_DEV_HANDLE d /*HDR*/ /** - Check if a specific device supports the mbg_get_irig_time() call. + @brief Check if a device supports the mbg_get_irig_time() call. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2274,12 +2423,15 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_irig_time( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Read a ::PCPS_IRIG_TIME type which returns the raw IRIG day-of-year number + @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 specific card. + 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 @@ -2302,9 +2454,10 @@ _MBG_API_ATTR int _MBG_API mbg_get_irig_time( MBG_DEV_HANDLE dh, /*HDR*/ /** - Clear the card'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 specific card. + @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 @@ -2327,10 +2480,14 @@ _MBG_API_ATTR int _MBG_API mbg_clr_ucap_buff( MBG_DEV_HANDLE dh ) /*HDR*/ /** - Read a ::PCPS_UCAP_ENTRIES structure to retrieve the number of saved - user capture events and the maximum capture buffer size. - The macro _pcps_has_ucap() or the API call mbg_dev_has_ucap() - check whether this call is supported by a specific card. + @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 @@ -2356,16 +2513,19 @@ _MBG_API_ATTR int _MBG_API mbg_get_ucap_entries( MBG_DEV_HANDLE dh, PCPS_UCAP_EN /*HDR*/ /** - Retrieve a single time capture event from the on-board FIFO buffer - using a ::PCPS_HR_TIME structure. The oldest entry of the FIFO is retrieved - and then removed from the FIFO. - If no capture event is available in the FIFO buffer then both the seconds + @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 specific card. + + 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 + call which is obsolete but still supported for compatibility with older cards. @param dh Valid handle to a Meinberg device @@ -2392,14 +2552,17 @@ _MBG_API_ATTR int _MBG_API mbg_get_ucap_event( MBG_DEV_HANDLE dh, PCPS_HR_TIME * /*HDR*/ /** - Read the card's time zone/daylight saving parameters using the ::TZDL - structure. - The macro _pcps_has_tzdl() or the API call mbg_dev_has_tzdl() - check whether this call is supported by a specific card. + @brief Read the card's time zone/daylight saving parameters. - <b>Note:</b> In spite of the function name this call may also be + 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. + 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 @@ -2425,14 +2588,17 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_tzdl( MBG_DEV_HANDLE dh, TZDL *p ) /*HDR*/ /** - Write the card's time zone/daylight saving parameters using the ::TZDL - structure. - The macro _pcps_has_tzdl() or the API call mbg_dev_has_tzdl() - check whether this call is supported by a specific card. + @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. + <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 @@ -2462,13 +2628,15 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_tzdl( MBG_DEV_HANDLE dh, const TZDL *p ) /*HDR*/ /** - Retrieve the software revision of a GPS receiver. - This call is obsolete but still supported for compatibility + @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 specific card. + check whether this call is supported by a device. - <b>Note:</b> The function mbg_get_gps_receiver_info() should + <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 @@ -2492,11 +2660,15 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_sw_rev( MBG_DEV_HANDLE dh, SW_REV *p ) /*HDR*/ /** - Retrieve the status of the battery buffered GPS variables. + @brief Retrieve the status of the battery buffered GPS variables. + + These GPS variables hold some parameters sent by the GPS satellites + which are required for proper operation. If the saved set of parameters + 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 specific card. - The GPS receiver stays in cold boot mode until all of the - data sets are valid. + 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 @@ -2516,17 +2688,21 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_bvar_stat( MBG_DEV_HANDLE dh, BVAR_STAT * /*HDR*/ /** - Read the current board time using a ::TTM structure. + @brief Read the current board time using a ::TTM structure. + The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a specific card. + check whether this call is supported by a device. - <b>Note:</b> This call is pretty slow, so the mbg_get_hr_time_..() - group of calls should be used preferably. + <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() */ _MBG_API_ATTR int _MBG_API mbg_get_gps_time( MBG_DEV_HANDLE dh, TTM *p ) { @@ -2541,10 +2717,13 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_time( MBG_DEV_HANDLE dh, TTM *p ) /*HDR*/ /** - Write a ::TTM structure to a GPS receiver in order to set the + @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 specific card. + 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 @@ -2568,15 +2747,15 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_time( MBG_DEV_HANDLE dh, const TTM *p ) /*HDR*/ /** - Read a ::PORT_PARM structure to retrieve the configuration - of the device's serial ports. + @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 specific card. + 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. + <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 @@ -2598,15 +2777,15 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_port_parm( MBG_DEV_HANDLE dh, PORT_PARM * /*HDR*/ /** - Write a ::PORT_PARM structure to configure the on-board - serial ports. + @brief Write a ::PORT_PARM structure to configure the on-board serial ports. + The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a specific card. + 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. + <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 @@ -2632,13 +2811,16 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_parm( MBG_DEV_HANDLE dh, const PORT_ /*HDR*/ /** - Read an ::ANT_INFO structure to retrieve status information of the GPS antenna. + @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 specific card. + check whether this call is supported by a device. - <b>Note:</b> Normally the antenna connection status can also be + <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. + 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 @@ -2658,14 +2840,15 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_ant_info( MBG_DEV_HANDLE dh, ANT_INFO *p /*HDR*/ /** - Read a time capture event from the on-board FIFO buffer using a ::TTM structure. + @brief Read a time capture event from the on-board FIFO buffer using a ::TTM structure. + The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a specific card. + 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 card. Anyway, this call is still supported for compatibility - with older cards. + <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 @@ -2689,13 +2872,16 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_ucap( MBG_DEV_HANDLE dh, TTM *p ) /*HDR*/ /** - Read an ::ENABLE_FLAGS structure reporting whether certain outputs - shall be enabled immediately after the card's power-up, or only + @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 specific card. + check whether this call is supported by a device. - <b>Note:</b> Not all of the input signals specified for the + <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 @@ -2720,13 +2906,16 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_enable_flags( MBG_DEV_HANDLE dh, ENABLE_F /*HDR*/ /** - Write an ENABLE_FLAGS structure to configure whether certain outputs - shall be enabled immediately after the card's power-up, or only + @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 specific card. + check whether this call is supported by a device. - <b>Note:</b> Not all of the input signals specified for the + <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 @@ -2756,11 +2945,13 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_enable_flags( MBG_DEV_HANDLE dh, /*HDR*/ /** - Read a ::STAT_INFO structure to retrieve the status of the - GPS receiver, including mode of operation and numer of - visible/usable satellites. + @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 specific card. + 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 @@ -2782,9 +2973,10 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_stat_info( MBG_DEV_HANDLE dh, STAT_INFO * /*HDR*/ /** - Sends a ::GPS_CMD to a GPS receiver. + @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 specific card. + check whether this call is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::GPS_CMD @@ -2809,10 +3001,15 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_cmd( MBG_DEV_HANDLE dh, const GPS_CMD *p /*HDR*/ /** - Read the current GPS receiver position using the ::POS structure - which contains different coordinate formats. + @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 specific card. + 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 @@ -2836,10 +3033,13 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_pos( MBG_DEV_HANDLE dh, POS *p ) /*HDR*/ /** - Preset the GPS receiver position using ::XYZ coordinates - (ECEF: WGS84 "Earth Centered, Earth fixed" kartesian coordinates). + @brief Set the GPS receiver position using ::XYZ coordinates. + + The structure ::XYZ must specify the new position in ECEF + (Earth Centered, Earth Fixed) kartesian coordinates. + The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a specific card. + 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 @@ -2871,10 +3071,13 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_xyz( MBG_DEV_HANDLE dh, const XYZ p ) /*HDR*/ /** - Preset the GPS receiver position using ::LLA coordinates - (longitude, latitude, altitude) + @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 specific card. + 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 @@ -2906,10 +3109,13 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_lla( MBG_DEV_HANDLE dh, const LLA p ) /*HDR*/ /** - Read the configured length of the GPS antenna cable (::ANT_CABLE_LEN). - The cable delay is internally compensated by 5ns per meter cable. + @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 specific card. + 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 @@ -2934,10 +3140,13 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_ant_cable_len( MBG_DEV_HANDLE dh, ANT_CAB /*HDR*/ /** - Write the length of the GPS antenna cable (::ANT_CABLE_LEN). - The cable delay is internally compensated by 5ns per meter cable. + @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 specific card. + 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 @@ -2967,13 +3176,14 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_ant_cable_len( MBG_DEV_HANDLE dh, /*HDR*/ /** - Read a ::RECEIVER_INFO structure from a card. + @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 specific card. + 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 card which don't provide that structure by themselves. + <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 @@ -3000,7 +3210,8 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_receiver_info( MBG_DEV_HANDLE dh, RECEIVE /*HDR*/ /** - Read a ::STR_TYPE_INFO_IDX array of supported string types. + @brief Read a ::STR_TYPE_INFO_IDX array of supported string types. + The function mbg_setup_receiver_info() must have been called before, and the returned ::RECEIVER_INFO structure passed to this function. @@ -3059,7 +3270,8 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_str_type_info( MBG_DEV_HANDLE dh, /*HDR*/ /** - Read a ::PORT_INFO_IDX array of supported serial port configurations. + @brief Read a ::PORT_INFO_IDX array of supported serial port configurations. + The function mbg_setup_receiver_info() must have been called before, and the returned ::RECEIVER_INFO structure passed to this function. @@ -3118,13 +3330,16 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_port_info( MBG_DEV_HANDLE dh, /*HDR*/ /** - Write the configuration for a single serial port using the ::PORT_SETTINGS_IDX - structure which 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(). + @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 specific card. + check whether this call is supported by a device. - <b>Note:</b> The function mbg_save_serial_settings() should be used preferably + <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. @@ -3156,13 +3371,16 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings_idx( MBG_DEV_HANDLE dh, /*HDR*/ /** - Write the configuration for a single serial port using the ::PORT_SETTINGS - structure plus the port index. - Except for the parameter types, this call is equivalent to mbg_set_gps_port_settings_idx(). + @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 specific card. + check whether this call is supported by a device. - <b>Note:</b> The function mbg_save_serial_settings() should be used preferably + <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. @@ -3194,11 +3412,12 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings( MBG_DEV_HANDLE dh, /*HDR*/ /** - Set up a ::RECEIVER_INFO structure for a device. + @brief Set up a ::RECEIVER_INFO structure for a device. + If the device supports the ::RECEIVER_INFO structure then the structure - is read from the device, otherwise a structure is set up using + 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, + 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. @@ -3252,9 +3471,10 @@ check: /*HDR*/ /** - Read the version code of the on-board PCI/PCIe interface ASIC. + @brief Read the version code of the on-board PCI/PCIe interface ASIC. + The macro _pcps_has_asic_version() or the API call mbg_dev_has_asic_version() - check whether this call is supported by a specific card. + 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 @@ -3286,9 +3506,10 @@ _MBG_API_ATTR int _MBG_API mbg_get_asic_version( MBG_DEV_HANDLE dh, PCI_ASIC_VER /*HDR*/ /** - Read the features of the on-board PCI/PCIe interface ASIC. + @brief Read the features of the on-board PCI/PCIe interface ASIC. + The macro _pcps_has_asic_features() or the API call mbg_dev_has_asic_features() - check whether this call is supported by a specific card. + 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 @@ -3324,10 +3545,10 @@ _MBG_API_ATTR int _MBG_API mbg_get_asic_features( MBG_DEV_HANDLE dh, /*HDR*/ /** - Check if a specific device supports configurable time scales. + @brief Check if a device supports configurable time scales. - By default the cards return UTC and/or local time. However, some cards - can be configured to return pure GPS time or TAI instead. + 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. @@ -3347,11 +3568,13 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_time_scale( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Read a ::MBG_TIME_SCALE_INFO structure from a card telling which time scales - are supported by a card, and the current settings of the card. + @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 specific card. + 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 @@ -3377,14 +3600,16 @@ _MBG_API_ATTR int _MBG_API mbg_get_time_scale_info( MBG_DEV_HANDLE dh, MBG_TIME_ /*HDR*/ /** - Write a ::MBG_TIME_SCALE_SETTINGS structure to a card which determines - which time scale shall be represented by time stamps read from the card. + @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 specific card. + 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 + 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 @@ -3414,15 +3639,18 @@ _MBG_API_ATTR int _MBG_API mbg_set_time_scale_settings( MBG_DEV_HANDLE dh, MBG_T /*HDR*/ /** - Check if a specific device supports reading/writing a GPS UTC parameter - set via the PC bus (reading/writing these parameters via the serial port - is supported by all GPS devices). + @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 parameters are normally received from the satellites' broadcasts - and contain the current time offset between GPT time and UTC, plus information - on a pending leap second. + 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 + 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 @@ -3443,10 +3671,10 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_utc_parm( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Read a ::UTC structure from a card. + @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 specific card. + 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 @@ -3474,15 +3702,15 @@ _MBG_API_ATTR int _MBG_API mbg_get_utc_parm( MBG_DEV_HANDLE dh, UTC *p ) /*HDR*/ /** - Write a ::UTC structure to a card. + @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 card receives any satellites the settings - written to the board are overwritten by the parameters broadcasted + 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 specific card. + 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 @@ -3514,22 +3742,24 @@ _MBG_API_ATTR int _MBG_API mbg_set_utc_parm( MBG_DEV_HANDLE dh, UTC *p ) /*HDR*/ /** - Read a ::PCPS_TIME_CYCLES structure that contains a ::PCPS_TIME structure + @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 specific card since that call provides much better accuracy than this one. + 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 other operating systems the returned - cycles value is always 0. + 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 + 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 @@ -3560,21 +3790,23 @@ _MBG_API_ATTR int _MBG_API mbg_get_time_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_CYC /*HDR*/ /** - Read a ::PCPS_HR_TIME_CYCLES structure that contains a ::PCPS_HR_TIME structure + @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 specific card. + 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 other operating systems the returned - cycles value is always 0. + 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 + 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 @@ -3608,25 +3840,27 @@ _MBG_API_ATTR int _MBG_API mbg_get_hr_time_cycles( MBG_DEV_HANDLE dh, /*HDR*/ /** - Read a ::PCPS_HR_TIME structure plus cycle counter value, and correct the + @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 specific card. + 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 other operating systems the returned - cycles value is always 0. + 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 + 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 + @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. @@ -3665,10 +3899,13 @@ _MBG_API_ATTR int _MBG_API mbg_get_hr_time_comp( MBG_DEV_HANDLE dh, PCPS_HR_TIME /*HDR*/ /** - Read an ::IRIG_INFO structure containing the configuration of an IRIG output + @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 specific card. + + 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 @@ -3711,9 +3948,10 @@ _MBG_API_ATTR int _MBG_API mbg_get_irig_tx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p /*HDR*/ /** - Write an ::IRIG_SETTINGS structure containing the configuration of an 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 specific card. + @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 @@ -3764,10 +4002,13 @@ _MBG_API_ATTR int _MBG_API mbg_set_irig_tx_settings( MBG_DEV_HANDLE dh, const IR /*HDR*/ /** - Read a ::SYNTH structure containing the configuration of an optional + @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 specific card. + + 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 @@ -3793,10 +4034,13 @@ _MBG_API_ATTR int _MBG_API mbg_get_synth( MBG_DEV_HANDLE dh, SYNTH *p ) /*HDR*/ /** - Write a ::SYNTH structure containing the configuration of an optional + @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 specific card. + + 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 @@ -3816,7 +4060,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_synth( MBG_DEV_HANDLE dh, const SYNTH *p ) _mbg_swab_synth( &tmp ); p = &tmp; #endif - _mbgdevio_write_var_chk( dh, PCPS_SET_SYNTH, IOCTL_SET_SYNTH, + _mbgdevio_write_var_chk( dh, PCPS_SET_SYNTH, IOCTL_SET_SYNTH, p, _pcps_ddev_has_synth( dh ) ); return _mbgdevio_ret_val; @@ -3826,10 +4070,10 @@ _MBG_API_ATTR int _MBG_API mbg_set_synth( MBG_DEV_HANDLE dh, const SYNTH *p ) /*HDR*/ /** - Read a ::SYNTH_STATE structure reporting the current state - 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 specific card. + @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 @@ -3855,7 +4099,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_synth_state( MBG_DEV_HANDLE dh, SYNTH_STATE * /*HDR*/ /** - Check if a specific device supports the mbg_get_fast_hr_timestamp_...() calls. + @brief Check if a device supports the mbg_get_fast_hr_timestamp_...() calls. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -3876,7 +4120,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_fast_hr_timestamp( MBG_DEV_HANDLE dh, int /*HDR*/ /** - Read a high resolution ::PCPS_TIME_STAMP_CYCLES structure via memory mapped access. + @brief Read a high resolution ::PCPS_TIME_STAMP_CYCLES structure via memory mapped access. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_TIME_STAMP_CYCLES structure to be filled up @@ -3905,8 +4149,10 @@ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_cycles( MBG_DEV_HANDLE dh, /*HDR*/ /** - Read a high resolution ::PCPS_TIME_STAMP via memory mapped access, - and compensate the latency of the time stamp before it is returned. + @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 @@ -3948,12 +4194,12 @@ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_comp( MBG_DEV_HANDLE dh, /*HDR*/ /** - Read a high resolution ::PCPS_TIME_STAMP structure via memory mapped access. + @brief Read a high resolution ::PCPS_TIME_STAMP structure via memory mapped access. This function does not return or evaluate a cycles count, so the latency of the call can not be determined. However, depending on the timer hardware 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 + 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 @@ -3983,7 +4229,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp( MBG_DEV_HANDLE dh, /*HDR*/ /** - Check if a specific device is a GPS receiver. + @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. @@ -4000,7 +4246,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_is_gps( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device is a DCF77 receiver. + @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. @@ -4017,7 +4263,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_is_dcf( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device is a MSF receiver. + @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. @@ -4034,7 +4280,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_is_msf( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device is a WWVB receiver. + @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. @@ -4051,7 +4297,9 @@ _MBG_API_ATTR int _MBG_API mbg_dev_is_wwvb( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device is a long wave signal receiver, e.g. DCF77, MSF or WWVB. + @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. @@ -4068,8 +4316,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_is_lwr( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device is an IRIG receiver which supports - configuration of the IRIG input. + @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. @@ -4091,7 +4338,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_is_irig_rx( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device supports the HR_TIME functions. + @brief Check if a device supports the HR_TIME functions. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -4112,7 +4359,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_hr_time( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device supports configuration of antenna cable length. + @brief Check if a device supports configuration of antenna cable length. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -4132,8 +4379,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_cab_len( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device supports timezone / daylight saving configuration - using the ::TZDL structure. + @brief Check if a device supports timezone configuration using the ::TZDL structure. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -4154,8 +4400,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_tzdl( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device supports timezone / daylight saving configuration - using the ::PCPS_TZDL structure. + @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -4176,8 +4421,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_pcps_tzdl( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device supports timezone configuration - using the ::PCPS_TZCODE type. + @brief Check if a device supports timezone configuration using the ::PCPS_TZCODE type. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -4198,9 +4442,10 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_tzcode( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific 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. + @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. @@ -4221,7 +4466,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_tz( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /* (Intentionally excluded from Doxygen) - Check if a specific device supports setting an event time, i.e. + 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. @@ -4243,11 +4488,12 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_event_time( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device supports the ::RECEIVER_INFO structure and related calls. - Older GPS devices may not support that structure. + @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 + 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 @@ -4267,8 +4513,10 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_receiver_info( MBG_DEV_HANDLE dh, int *p /*HDR*/ /** - Check if a specific device supports the mbg_clr_ucap_buff() call - used to clear a card's on-board time capture FIFO buffer. + @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. @@ -4287,10 +4535,9 @@ _MBG_API_ATTR int _MBG_API mbg_dev_can_clr_ucap_buff( MBG_DEV_HANDLE dh, int *p /*HDR*/ /** - Check if a specific device supports the mbg_get_ucap_entries() and - mbg_get_ucap_event() calls. + @brief Check if a device supports the mbg_get_ucap_entries() and mbg_get_ucap_event() calls. - If the card does not but it is a GPS card then the card provides + 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. @@ -4314,8 +4561,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_ucap( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device provides an IRIG output which can - be configured. + @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. @@ -4339,9 +4585,9 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_irig_tx( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /* (Intentionally excluded from Doxygen) - Check if a specific device provides a serial output supporting + 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. + 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. @@ -4363,8 +4609,9 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_serial_hs( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device provides an input signal level value which - may be displayed, e.g. DCF77 or IRIG cards. + @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. @@ -4381,8 +4628,9 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_signal( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device provides an modulation signal which may be - displayed, e.g. the second marks of a DCF77 AM receiver. + @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. @@ -4399,7 +4647,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_mod( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device provides either an IRIG input or output. + @brief Check if a device provides either an IRIG input or output. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -4419,8 +4667,10 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_irig( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device provides a configurable ref time offset - required to convert the received time to %UTC. + @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. @@ -4440,8 +4690,10 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_ref_offs( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS - structures containing optional settings, controlled by flags. + @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. @@ -4461,8 +4713,9 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_opt_flags( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device supports large configuration data structures - as have been introducesde with the GPS receivers. + @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. @@ -4479,7 +4732,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_gps_data( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device provides a programmable frequency synthesizer. + @brief Check if a device provides a programmable frequency synthesizer. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -4499,7 +4752,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_synth( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /* (Intentionally excluded from Doxygen) - Check if a specific device supports the mbg_generic_io() call. + @brief Check if a device supports the mbg_generic_io() call. <b>Warning</b>: That call is for debugging purposes and internal use only! @@ -4520,7 +4773,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_generic_io( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device supports the mbg_get_asic_version() call. + @brief Check if a device supports the mbg_get_asic_version() call. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -4539,7 +4792,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_asic_version( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device supports the mbg_get_asic_features() call. + @brief Check if a device supports the mbg_get_asic_features() call. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -4558,14 +4811,17 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_asic_features( MBG_DEV_HANDLE dh, int *p /*HDR*/ /** - Read a ::POUT_INFO_IDX array of current settings and configuration - options of a card's programmable pulse outputs. + @brief Read current configuraton and features provided by the programmable pulse outputs. + + Reads a ::POUT_INFO_IDX array of current settings and configuration + options of the device's programmable pulse outputs. + 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 + 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 + 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. @@ -4594,7 +4850,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_pout_info( MBG_DEV_HANDLE dh, // has been read from a device which really supports it, or // a dummy structure has been setup. if ( p_ri && ( p_ri->model_code != GPS_MODEL_UNKNOWN ) ) - rc = _mbgdevio_gen_read_gps( dh, PC_GPS_ALL_POUT_INFO, pii, + rc = _mbgdevio_gen_read_gps( dh, PC_GPS_ALL_POUT_INFO, pii, p_ri->n_prg_out * sizeof( pii[0] ) ); else return _mbg_err_to_os( MBG_ERR_NOT_SUPP_BY_DEV ); @@ -4607,7 +4863,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_pout_info( MBG_DEV_HANDLE dh, for ( i = 0; i < p_ri->n_prg_out; i++ ) { POUT_INFO_IDX *p = &pii[i]; - _mbg_swab_pout_info_idx( p ); + _mbg_swab_pout_info_idx_on_get( p ); } } #endif @@ -4620,13 +4876,14 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_pout_info( MBG_DEV_HANDLE dh, /*HDR*/ /** - Write the configuration for a single programmable pulse output using - the ::POUT_SETTINGS_IDX structure which 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 + @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. @@ -4643,7 +4900,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings_idx( MBG_DEV_HANDLE dh, _mbgdevio_vars(); #if defined( MBG_ARCH_BIG_ENDIAN ) POUT_SETTINGS_IDX tmp = *p; - _mbg_swab_pout_settings_idx( &tmp ); + _mbg_swab_pout_settings_idx_on_set( &tmp ); p = &tmp; #endif _mbgdevio_write_gps_var_chk( dh, PC_GPS_POUT_SETTINGS_IDX, @@ -4657,12 +4914,15 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings_idx( MBG_DEV_HANDLE dh, /*HDR*/ /** - Write the configuration for a single programmable pulse output using - the ::POUT_SETTINGS structure plus the index of the output to be configured. - 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 + @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. @@ -4690,9 +4950,11 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings( MBG_DEV_HANDLE dh, /*HDR*/ /** - Read a card's IRQ status information which includes flags indicating - whether IRQs are currently enabled, and whether IRQ support by a card - is possibly unsafe due to the firmware and interface chip version. + @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 @@ -4717,7 +4979,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_irq_stat_info( MBG_DEV_HANDLE dh, PCPS_IRQ_ST /*HDR*/ /** - Check if a specific device provides simple LAN interface API calls. + @brief Check if a device provides simple LAN interface API calls. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -4739,9 +5001,10 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_lan_intf( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Read LAN interface information from a card which supports this. + @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 specific card. + 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 @@ -4768,9 +5031,10 @@ _MBG_API_ATTR int _MBG_API mbg_get_lan_if_info( MBG_DEV_HANDLE dh, LAN_IF_INFO * /*HDR*/ /** - Read LAN IPv4 state from a card which supports this. + @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 specific card. + 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 @@ -4797,9 +5061,10 @@ _MBG_API_ATTR int _MBG_API mbg_get_ip4_state( MBG_DEV_HANDLE dh, IP4_SETTINGS *p /*HDR*/ /** - Read LAN IPv4 settings from a card which supports this. + @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 specific card. + 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 @@ -4826,9 +5091,10 @@ _MBG_API_ATTR int _MBG_API mbg_get_ip4_settings( MBG_DEV_HANDLE dh, IP4_SETTINGS /*HDR*/ /** - Write LAN IPv4 settings to a card which supports this. + @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 specific card. + 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 @@ -4859,16 +5125,18 @@ _MBG_API_ATTR int _MBG_API mbg_set_ip4_settings( MBG_DEV_HANDLE dh, /*HDR*/ /** - Check if a specific device provides PTP configuration/status calls. + @brief Check if a device provides PTP configuration/status calls. @param dh Valid handle to a Meinberg device @param *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_ptp_state() - @see mbg_get_ptp_cfg_info() - @see mbg_set_ptp_cfg_settings() + @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 ) { @@ -4880,17 +5148,18 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_ptp( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device provides PTP Unicast feature/configuration. + @brief Check if a device provides PTP unicast feature/configuration. @param dh Valid handle to a Meinberg device @param *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_ptp_state() - @see mbg_get_ptp_uc_master_cfg_limits() - @see mbg_get_all_ptp_uc_master_info() - @see mbg_set_ptp_unicast_cfg_settings() + @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 ) { @@ -4902,18 +5171,21 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_ptp_unicast( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Read PTP/IEEE1588 status from a card which supports this. + @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 specific card. + 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 + @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_ptp_cfg_info() - @see mbg_set_ptp_cfg_settings() + @see mbg_dev_has_ptp + @see mbg_get_all_ptp_cfg_info + @see mbg_get_ptp_cfg_info + @see mbg_set_ptp_cfg_settings + @see mbg_dev_has_ptp_unicast */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_state( MBG_DEV_HANDLE dh, PTP_STATE *p ) { @@ -4930,18 +5202,21 @@ _MBG_API_ATTR int _MBG_API mbg_get_ptp_state( MBG_DEV_HANDLE dh, PTP_STATE *p ) /*HDR*/ /** - Read PTP/IEEE1588 config info and current settings from a card which supports this. + @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 specific card. + 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_ptp_state() - @see mbg_set_ptp_cfg_settings() + @see mbg_dev_has_ptp + @see mbg_get_all_ptp_cfg_info + @see mbg_get_ptp_state + @see mbg_set_ptp_cfg_settings + @see mbg_dev_has_ptp_unicast */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_cfg_info( MBG_DEV_HANDLE dh, PTP_CFG_INFO *p ) { @@ -4958,18 +5233,21 @@ _MBG_API_ATTR int _MBG_API mbg_get_ptp_cfg_info( MBG_DEV_HANDLE dh, PTP_CFG_INFO /*HDR*/ /** - Write PTP/IEEE1588 configuration settings to a card which supports this. + @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 specific card. + 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_ptp_state() - @see mbg_get_ptp_cfg_info() + @see mbg_dev_has_ptp + @see mbg_get_all_ptp_cfg_info + @see mbg_get_ptp_state + @see mbg_get_ptp_cfg_info + @see mbg_dev_has_ptp_unicast */ _MBG_API_ATTR int _MBG_API mbg_set_ptp_cfg_settings( MBG_DEV_HANDLE dh, const PTP_CFG_SETTINGS *p ) @@ -4991,17 +5269,21 @@ _MBG_API_ATTR int _MBG_API mbg_set_ptp_cfg_settings( MBG_DEV_HANDLE dh, /*HDR*/ /** - Read PTP/IEEE1588 unicast config info and current settings from a card which supports this. + @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 specific card. + check whether this call is supported by a device. @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PTP_UNICAST_CFG_INFO variable to be filled up + @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_set_ptp_unicast_cfg_settings() + @see mbg_dev_has_ptp_unicast + @see mbg_get_all_ptp_cfg_info + @see mbg_get_all_ptp_uc_master_info + @see mbg_set_ptp_uc_master_settings_idx + @see mbg_get_ptp_state */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_uc_master_cfg_limits( MBG_DEV_HANDLE dh, PTP_UC_MASTER_CFG_LIMITS *p ) { @@ -5018,14 +5300,14 @@ _MBG_API_ATTR int _MBG_API mbg_get_ptp_uc_master_cfg_limits( MBG_DEV_HANDLE dh, /*HDR*/ /** - Read a ::IOCTL_SET_PTP_UNICAST_CFG_SETTINGS array of current settings and configuration - options of a card's programmable pulse outputs. + @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 + 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 + 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. @@ -5034,13 +5316,15 @@ _MBG_API_ATTR int _MBG_API mbg_get_ptp_uc_master_cfg_limits( MBG_DEV_HANDLE dh, @return ::MBG_SUCCESS or error code returned by device I/O control function. - @see //##++++++++++++++++++++++ - @see - @see + @see mbg_dev_has_ptp_unicast + @see mbg_get_all_ptp_cfg_info + @see mbg_get_ptp_uc_master_cfg_limits + @see mbg_set_ptp_uc_master_settings_idx + @see mbg_get_ptp_state */ _MBG_API_ATTR int _MBG_API mbg_get_all_ptp_uc_master_info( MBG_DEV_HANDLE dh, - PTP_UC_MASTER_INFO_IDX pii[], - const PTP_UC_MASTER_CFG_LIMITS *p_umsl ) + PTP_UC_MASTER_INFO_IDX pii[], + const PTP_UC_MASTER_CFG_LIMITS *p_umsl ) { _mbgdevio_vars(); @@ -5077,19 +5361,21 @@ _MBG_API_ATTR int _MBG_API mbg_get_all_ptp_uc_master_info( MBG_DEV_HANDLE dh, /*HDR*/ /** - Write PTP/IEEE1588 unicast configuration settings to a card which supports this. + @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 specific card. + check whether this call is supported by a device. @param dh Valid handle to a Meinberg device. - @param *p ::PTP_UNICAST_CFG_SETTINGS structure to be written + @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_ptp_state() - @see mbg_get_ptp_cfg_info() - @see mbg_get_ptp_unicast_cfg_info() + @see mbg_dev_has_ptp_unicast + @see mbg_get_all_ptp_cfg_info + @see mbg_get_ptp_uc_master_cfg_limits + @see mbg_get_all_ptp_uc_master_info + @see mbg_get_ptp_state */ _MBG_API_ATTR int _MBG_API mbg_set_ptp_uc_master_settings_idx( MBG_DEV_HANDLE dh, const PTP_UC_MASTER_SETTINGS_IDX *p ) @@ -5111,9 +5397,10 @@ _MBG_API_ATTR int _MBG_API mbg_set_ptp_uc_master_settings_idx( MBG_DEV_HANDLE dh /*HDR*/ /** - Read system time and card 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 + @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. @@ -5123,8 +5410,8 @@ _MBG_API_ATTR int _MBG_API mbg_set_ptp_uc_master_settings_idx( MBG_DEV_HANDLE dh 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 with a specific card. + _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 @@ -5152,10 +5439,12 @@ _MBG_API_ATTR int _MBG_API mbg_get_time_info_hrt( MBG_DEV_HANDLE dh, MBG_TIME_IN /*HDR*/ /** + @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 with a specific card. + 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 @@ -5183,7 +5472,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_time_info_tstamp( MBG_DEV_HANDLE dh, MBG_TIME /*HDR*/ /** - Check if a specific device supports demodulation of the DCF77 PZF code. + @brief Check if a device supports demodulation of the DCF77 PZF code. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -5203,7 +5492,7 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_pzf( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device supports reading correlation info. + @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. @@ -5223,8 +5512,10 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_corr_info( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Check if a specific device supports configurable distance from transmitter - used to compensate RF propagation delay. + @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. @@ -5245,9 +5536,10 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_tr_distance( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Read PZF correlation info from a card which supports this. + @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 specific card. + 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 @@ -5272,11 +5564,13 @@ _MBG_API_ATTR int _MBG_API mbg_get_corr_info( MBG_DEV_HANDLE dh, CORR_INFO *p ) /*HDR*/ /** - Read configurable "distance from transmitter" parameter from a card - which supports this. The parameter is used to compensate the RF signal - propagation delay. + @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 specific card. + 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 @@ -5302,11 +5596,13 @@ _MBG_API_ATTR int _MBG_API mbg_get_tr_distance( MBG_DEV_HANDLE dh, TR_DISTANCE * /*HDR*/ /** - Write configurable "distance from transmitter" parameter to a card - which supports this. The parameter is used to compensate the RF signal - propagation delay. + @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 specific card. + 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 @@ -5335,7 +5631,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_tr_distance( MBG_DEV_HANDLE dh, const TR_DIST /*HDR*/ /** - Check if a specific device provides a debug status word to be read. + @brief Check if a device provides a debug status word to be read. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -5354,13 +5650,16 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_debug_status( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Read a debug status word from a card. 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. + @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 specific card. + 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 @@ -5384,7 +5683,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_debug_status( MBG_DEV_HANDLE dh, MBG_DEBUG_ST /*HDR*/ /** - Check if a specific device provides an on-board event log. + @brief Check if a device provides an on-board event log. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -5406,9 +5705,10 @@ _MBG_API_ATTR int _MBG_API mbg_dev_has_evt_log( MBG_DEV_HANDLE dh, int *p ) /*HDR*/ /** - Clear the card's on-board event log. + @brief Clear the card's on-board event log. + The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - check whether this call is supported by a specific device. + check whether this call is supported by a device. @param dh Valid handle to a Meinberg device @@ -5432,13 +5732,14 @@ _MBG_API_ATTR int _MBG_API mbg_clr_evt_log( MBG_DEV_HANDLE dh ) /*HDR*/ /** - Read max number of num event log entries which can - be saved on the board, and how many entries actually + @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. - _pcps_has_evt_log() checks whether supported. The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - check whether this call is supported by a specific device. + 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 @@ -5465,12 +5766,12 @@ _MBG_API_ATTR int _MBG_API mbg_get_num_evt_log_entries( MBG_DEV_HANDLE dh, MBG_N /*HDR*/ /** - Read the first (oldest) event log entry from a device. + @brief Read the first (oldest) event log entry from a device. @note Subsequent reads should be made using mbg_get_next_evt_log_entry(). The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - check whether this call is supported by a specific device. + 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. @@ -5500,13 +5801,13 @@ _MBG_API_ATTR int _MBG_API mbg_get_first_evt_log_entry( MBG_DEV_HANDLE dh, MBG_E /*HDR*/ /** - Read the next event log entry from a device. + @brief Read the next event log entry from a device. @note The first read should be made using mbg_get_first_evt_log_entry() to set the on-board read index to the oldest entry. The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - check whether this call is supported by a specific device. + 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. @@ -5536,8 +5837,9 @@ _MBG_API_ATTR int _MBG_API mbg_get_next_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EV /*HDR*/ /** - Read the CPU affinity of a process, i.e. on which of the available - CPUs the process can be executed. + @brief Read the CPU affinity of a process. + + This means on which of the available CPUs or CPU cores the process can be executed. @param pid The process ID. @param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. @@ -5571,8 +5873,10 @@ _MBG_API_ATTR int _MBG_API mbg_get_process_affinity( MBG_PROCESS_ID pid, MBG_CPU /*HDR*/ /** - Set the CPU affinity of a process, i.e. on which of the available - CPUs the process is allowed to be executed. + @brief Set the CPU affinity of a process. + + This determines on which of the available CPUs + the process is allowed to be executed. @param pid The process ID. @param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. @@ -5604,8 +5908,9 @@ _MBG_API_ATTR int _MBG_API mbg_set_process_affinity( MBG_PROCESS_ID pid, MBG_CPU /*HDR*/ /** - Set the CPU affinity of a process for a single CPU only, i.e. the process - may only be executed on that single CPU. + @brief Set the CPU affinity of a process for a single CPU only. + + This means the process may only be executed on that single CPU. @param cpu_num The number of the CPU. @@ -5631,7 +5936,8 @@ _MBG_API_ATTR int _MBG_API mbg_set_current_process_affinity_to_cpu( int cpu_num /*HDR*/ /** - Create a new execution thread for the current process. + @brief Create a new execution thread for the current process. + This function is only implemented for targets which support threads. @param p_ti Pointer to a ::MBG_THREAD_INFO structure to be filled up. @@ -5666,7 +5972,7 @@ _MBG_API_ATTR int _MBG_API mbg_thread_create( MBG_THREAD_INFO *p_ti, if ( h == NULL ) { CloseHandle( p_ti->exit_request ); - goto fail; + goto fail; } p_ti->thread_id = h; @@ -5688,8 +5994,9 @@ fail: /*HDR*/ /** - Stop a thread which has been created by mbg_thread_create(). Wait - until the thread has finished and release all resources. + @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. @@ -5736,8 +6043,11 @@ _MBG_API_ATTR int _MBG_API mbg_thread_stop( MBG_THREAD_INFO *p_ti ) /*HDR*/ /** - Let the current thread sleep for a certain interval unless a signal is - received indicating the thread should terminate. + @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. @@ -5786,8 +6096,11 @@ _MBG_API_ATTR int _MBG_API mbg_thread_sleep_interruptible( MBG_THREAD_INFO *p_ti /*HDR*/ /** - Set the CPU affinity of a single thread, i.e. on which of the available - CPUs the thread is allowed to be executed. + @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. @@ -5825,20 +6138,23 @@ _MBG_API_ATTR int _MBG_API mbg_thread_set_affinity( MBG_THREAD_INFO *p_ti, MBG_C static /*HDR*/ /** - A thread function which implements polling of a device at a regular interval. + @brief A thread function implementing polling of a device at regular intervals. + At each polling a high resolution time stamp and an associated cycles count - are saved which can be used to retrieve extrapolated time stamps using the + are saved which can be used to retrieve extrapolated time stamps using the cycles counter. The thread also computes the frequency of the system's cycles - counter. - On systems where the cycles counter is implemented by a CPU's time stamp - counter (TSC) it maybe required to set the thread or process affinity to a - single CPU to get reliable cycles counts. In this case also care should be - taken that the CPU's clock frequency is not stepped up and down e.g. due - to power saving mechanisms (e.g. Intel SpeedStep, or AMD Cool'n'Quiet). + counter. + + On systems where the cycles counter is implemented by a CPU's time stamp + counter (TSC) it may be required to set the thread or process affinity to a + single CPU to get reliable cycles counts. In this case also care should be + taken that the CPU's clock frequency is not stepped up and down e.g. due + to power saving mechanisms (e.g. Intel SpeedStep, or AMD Cool'n'Quiet). Otherwise time interpolation may be messed up. + This function is only implemented for targets which support threads. - @param *p_void Pointer to a ::MBG_POLL_THREAD_INFO structure. + @param *p_void Pointer to a ::MBG_POLL_THREAD_INFO structure. @return ::MBG_SUCCESS or nothing, depending on the taget system. @@ -5908,19 +6224,21 @@ MBG_THREAD_FNC_RET_VAL MBG_THREAD_FNC_ATTR mbg_xhrt_poll_thread_fnc( void *p_voi /*HDR*/ /** - Set up a ::MBG_POLL_THREAD_INFO structure and start a new thread - which runs the mbg_xhrt_poll_thread_fnc() function. + @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. + @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() + else the result of mbg_thread_create() @see mbg_xhrt_poll_thread_fnc() @see mbg_xhrt_poll_thread_stop() @@ -5954,12 +6272,13 @@ _MBG_API_ATTR int _MBG_API mbg_xhrt_poll_thread_create( MBG_POLL_THREAD_INFO *p_ /*HDR*/ /** - Stop a polling thread started by mbg_xhrt_poll_thread_create() - and release all associated resources. + @brief Stop a polling thread started by mbg_xhrt_poll_thread_create(). + + This call also releases all associated resources. @param *p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. - @return the result of mbg_thread_stop() + @return the result of mbg_thread_stop() @see mbg_xhrt_poll_thread_fnc() @see mbg_xhrt_poll_thread_create() @@ -6018,10 +6337,12 @@ int mbg_get_xhrt_data( MBG_XHRT_INFO *p, uint64_t *tstamp, MBG_XHRT_VARS *vars ) /*HDR*/ /** - Retrieve a time stamp in PCPS_HR_TIME format which is extrapolated - using the system's current cycles counter value and a time stamp - plus associated cycles counter value saved by the polling thread. + @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. @@ -6063,11 +6384,13 @@ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_pcps_hr_time( MBG_XHRT_INFO *p, /*HDR*/ /** - Retrieve a time stamp in FILETIME format which is extrapolated - using the system's current cycles counter value and a time stamp - plus associated cycles counter value saved by the polling thread. + @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 + + 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. @@ -6103,9 +6426,11 @@ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_filetime( MBG_XHRT_INFO *p, FILE /*HDR*/ /** - Retrieve the frequency of the system's cycles counter as determined - by the device polling thread. + @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. @@ -6141,7 +6466,9 @@ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_cycles_frequency( MBG_XHRT_INFO *p, MBG_ /*HDR*/ /** - Retrieve the default system's cycles counter frequency from the kernel driver. + @brief Retrieve the default system's cycles counter frequency from the kernel driver. + + This API call can be used on systems which don't provide this information in user space. @param dh handle of the device to which the IOCTL call is sent. @param *p Pointer of a ::MBG_PC_CYCLES_FREQUENCY variable to be filled up. @@ -6213,7 +6540,7 @@ done: /*HDR*/ /** - Retrieve the default system's cycles counter frequency. + @brief Retrieve the system's default cycles counter frequency. @note This may not be supported on all target platforms, in which case the returned frequency is 0 and the mbg_get_default_cycles_frequency_from_dev() diff --git a/mbglib/common/mbgdevio.h b/mbglib/common/mbgdevio.h index 24a312c..8455bd8 100755 --- a/mbglib/common/mbgdevio.h +++ b/mbglib/common/mbgdevio.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgdevio.h 1.39.1.25 2011/11/25 15:03:22 martin TEST $ + * $Id: mbgdevio.h 1.40 2012/10/02 18:40:30 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,67 +10,27 @@ * * ----------------------------------------------------------------------- * $Log: mbgdevio.h $ - * Revision 1.39.1.25 2011/11/25 15:03:22 martin - * Support on-board event logs. - * Revision 1.39.1.24 2011/11/23 16:42:03 martin - * Updated function prototypes. - * Added some comments. - * Revision 1.39.1.23.1.4 2011/11/23 16:37:24 martin - * Removed tmp. debug code. - * Revision 1.39.1.23.1.3 2011/11/23 16:32:53 martin - * Modified tmp. debug code. - * Revision 1.39.1.23.1.2 2011/11/22 15:13:14 martin + * Revision 1.40 2012/10/02 18:40:30 martin + * There are some g++ versions which fail to compile source code using + * the macros provided by Linux to define IOCTL codes. If only the API + * functions are called by an application then the IOCTL codes aren't + * required anyway, so we just avoid inclusion of mbgioctl.h. + * Updated doxygen comments. * Updated function prototypes. - * Revision 1.39.1.23.1.1 2011/11/21 14:16:33 martin - * Tmp. debug generic I/O. - * Revision 1.39.1.23 2011/11/16 10:09:28 martin + * Support on-board event logs. * Fixed a bug which caused a crash when generic I/O calls * were used under Windows. - * Revision 1.39.1.22 2011/10/21 14:08:28Z martin * Changes for QNX. - * Revision 1.39.1.21 2011/09/26 14:03:21 martin * Workaround to make mbgmon (BC) build under Windows. - * See diff for details. * Cleaned up CPU set support under Linux. - * Updated function prototypes. - * Revision 1.39.1.20 2011/07/20 15:52:22Z martin - * Conditionally use older IOCTL request buffer structures. * Moved some macros here so they can be used by other modules. - * Modified some macros and definitions. - * Revision 1.39.1.19 2011/07/19 15:46:39 martin - * Revision 1.39.1.18 2011/07/06 11:19:24 martin * Support reading CORR_INFO, and reading/writing TR_DISTANCE. - * Revision 1.39.1.17 2011/06/29 11:10:19 martin - * Updated function prototypes. - * Revision 1.39.1.16 2011/06/22 10:16:22 martin * Cleaned up handling of pragma pack(). * Cleaned up inclusion of header files. - * Updated function prototypes. - * Revision 1.39.1.15 2011/04/12 12:57:53 martin * Moved mutex definitions to new mbgmutex.h. * Renamed mutex stuff to critical sections. - * Revision 1.39.1.14 2011/03/31 13:20:55 martin - * Updated function prototypes. - * Revision 1.39.1.13 2011/02/15 14:26:22Z martin - * Revision 1.39.1.12 2011/02/15 11:22:29 daniel * Updated function prototypes to support PTP unicast configuration - * Revision 1.39.1.11 2011/02/02 12:21:39Z martin - * Fixed a type. - * Revision 1.39.1.10 2011/01/28 09:33:45 martin - * Cosmetics. - * Revision 1.39.1.9 2010/12/14 11:23:49 martin - * Moved definition of MBG_HW_NAME to the header file. - * Revision 1.39.1.8 2010/12/14 10:56:35Z martin - * Revision 1.39.1.7 2010/08/11 13:48:53 martin - * Cleaned up comments. - * Revision 1.39.1.6 2010/08/11 12:43:52 martin - * Revision 1.39.1.5 2010/07/15 08:40:57 martin - * Revision 1.39.1.4 2010/01/08 15:04:17Z martin - * Revision 1.39.1.3 2010/01/08 11:24:02Z martin - * Compute and check time of day only if any leap second status bit set. - * Revision 1.39.1.2 2010/01/08 11:13:57Z martin * Made xhrt leap second check an inline function. - * Revision 1.39.1.1 2010/01/07 15:49:37Z martin * Fixed macro to avoid compiler warning. * Revision 1.39 2009/12/15 15:34:59Z daniel * Support reading the raw IRIG data bits for firmware versions @@ -303,8 +263,6 @@ #if defined( MBG_USE_KERNEL_DRIVER ) - #include <mbgioctl.h> - #include <stdlib.h> #include <string.h> @@ -566,83 +524,95 @@ extern "C" { /* by MAKEHDR, do not remove the comments. */ /** - Get the version number of the compiled mbgdevio library. - If the mbgdevio library is built as a DLL/shared object then - the version number of the compiled library may differ from - the version number of the import library and header files - which have been used to build an application. + 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 + @return the version number - @see ::MBGDEVIO_VERSION defined in mbgdevio.h. + @see mbgdevio_check_version() + @see ::MBGDEVIO_VERSION defined in mbgdevio.h */ _MBG_API_ATTR int _MBG_API mbgdevio_get_version( void ) ; /** - Check if the version of the compiled mbgdevio library is compatible - with a certain version which is passed as parameter. + @brief Check if the DLL/shared library is compatible with a given version. + + If this library is used as a DLL/shared object library then the version + number can be checked to see if the header files which are actually used + to build an application are compatible with the header files which have + been used to build the library, and thus the API function are called + in the correct way. - @param header_version Version number to be checked, should be ::MBGDEVIO_VERSION - defined in mbgdevio.h. + @param header_version Version number to be checked, should be ::MBGDEVIO_VERSION + from the mbgdevio.h file used to build the application @return ::MBG_SUCCESS if compatible, ::MBG_ERR_LIB_NOT_COMPATIBLE if not. - @see ::MBGDEVIO_VERSION defined in mbgdevio.h. + @see mbgdevio_get_version() + @see ::MBGDEVIO_VERSION defined in mbgdevio.h */ _MBG_API_ATTR int _MBG_API mbgdevio_check_version( int header_version ) ; /** - Open a device by index, starting from 0. - This function is <b>out of date</b>, mbg_open_device_by_name() + @brief Open a device by index, starting from 0. + + This function is <b>out of date</b>, mbg_open_device_by_name() should be used instead. See the <b>note</b> for mbg_find_device() for details. - @param device_index Index of the device, use 0 for the first device. + @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 ) ; /** - Get the number of supported devices installed on the computer. - This function is <b>out of date</b>, mbg_find_devices_with_names() + @brief Get the number of supported devices installed on the computer. + + This function is <b>out of date</b>, mbg_find_devices_with_names() should be used instead. - <b>Note:</b> This function is out of date since it may not work + <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 + 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. + @return The number of devices found @see mbg_find_devices_with_names() */ _MBG_API_ATTR int _MBG_API mbg_find_devices( void ) ; /** - Return the number of supported devices installed on the system and - set up a list of unique names of those devices. + @brief Allocate memory and set up a list of installed and supported devices. This function should be used preferably instead of mbg_find_devices(). - @param 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 + @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 + @param max_devices Maximum number of devices the function should look for (can not exceed ::MBG_MAX_DEVICES). - @return Number of present devices + @return number of present devices @see ::MBG_HW_NAME for the format of the unique names @see mbg_free_device_name_list() @see mbg_find_devices() */ - _MBG_API_ATTR int _MBG_API mbg_find_devices_with_names( MBG_DEVICENAME_LIST **device_list, int max_devices ) ; + _MBG_API_ATTR int _MBG_API mbg_find_devices_with_names( MBG_DEVICENAME_LIST **device_list, int max_devices ) ; /** - Free the memory of the ::MBG_DEVICENAME_LIST that has been allocated before + @brief Free the memory allocated for a ::MBG_DEVICENAME_LIST. + + The list may have been set up and allocated before by mbg_find_devices_with_names(). @param *list Linked list of type ::MBG_DEVICENAME_LIST @@ -652,7 +622,8 @@ extern "C" { _MBG_API_ATTR void _MBG_API mbg_free_device_name_list( MBG_DEVICENAME_LIST *list) ; /** - Return a handle to a device with a certain unique name. + @brief Return a handle to a device with a certain unique name. + The names of the devices that are installed on the system can be retrieved by the function mbg_find_devices_with_names(). @@ -671,16 +642,14 @@ extern "C" { ; /** - Close a handle to a device and set the handle value to ::MBG_INVALID_DEV_HANDLE. - If required, unmap mapped memory. + @brief Close a handle to a device and set the handle value to ::MBG_INVALID_DEV_HANDLE. @param dev_handle Handle to a Meinberg device. */ _MBG_API_ATTR void _MBG_API mbg_close_device( MBG_DEV_HANDLE *dev_handle ) ; /** - Return a ::PCPS_DRVR_INFO structure that provides information - about the kernel device driver. + @brief Read information about the driver handling a given device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_DRVR_INFO structure which is filled up. @@ -690,7 +659,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_drvr_info( MBG_DEV_HANDLE dh, PCPS_DRVR_INFO *p ) ; /** - Return a ::PCPS_DEV structure that provides detailed information about the device. + @brief Read detailed device information. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_DEV structure to be filled up @@ -700,7 +669,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_device_info( MBG_DEV_HANDLE dh, PCPS_DEV *p ) ; /** - Return the current state of the on-board::PCPS_STATUS_PORT. + @brief Read the current state of the on-board ::PCPS_STATUS_PORT. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_STATUS_PORT value to be filled up @@ -712,7 +681,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_status_port( MBG_DEV_HANDLE dh, PCPS_STATUS_PORT *p ) ; /* (Intentionally excluded from Doxygen) - Generic read function which writes a command code to the device + 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! @@ -734,10 +703,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_generic_read( MBG_DEV_HANDLE dh, int cmd, void *p, int size ) ; /* (Intentionally excluded from Doxygen) - Generic read function which writes a GPS command code to the device + 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 specific card. + 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. @@ -759,8 +728,8 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_generic_read_gps( MBG_DEV_HANDLE dh, int cmd, void *p, int size ) ; /* (Intentionally excluded from Doxygen) - Generic write function which writes a command code plus an - associated number of data bytes to the device. + 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. @@ -781,10 +750,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_generic_write( MBG_DEV_HANDLE dh, int cmd, const void *p, int size ) ; /* (Intentionally excluded from Doxygen) - Generic write function which writes a GPS command code plus an - associated number of data bytes to the device. + 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 specific card. + 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. @@ -808,7 +777,7 @@ extern "C" { /* (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 specific card. + check whether this call is supported by a device. <b>Warning</b>: This call is for debugging purposes and internal use only! @@ -823,13 +792,15 @@ extern "C" { _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 ) ; /** - 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, + @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). - This call is supported by any device manufactured by Meinberg. However, - for higher accuracy and resolution the mbg_get_hr_time..() group of calls - should be used preferably if supported by the specific device. + 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. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_TIME structure to be filled up @@ -843,9 +814,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ; /** - Set a device's on-board clock manually by passing a ::PCPS_STIME structure - The macro _pcps_can_set_time() checks whether this call - is supported by a specific card. + @brief Set the device's on-board clock to a given date and time. + + The macro _pcps_can_set_time() checks whether this call + is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_STIME structure to be written @@ -857,18 +829,20 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_time( MBG_DEV_HANDLE dh, const PCPS_STIME *p ) ; /** - Read a ::PCPS_TIME structure returning the date/time/status reporting - when the device was synchronized the last time to its time source, - e.g. the DCF77 signal or the GPS satellites. - The macro _pcps_has_sync_time() or the API call mbg_dev_has_sync_time() - check whether this call is supported by a specific card. + @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() or the API call mbg_dev_has_sync_time() + check whether this call is supported by a device. - The macro _pcps_has_sync_time() checks whether this call - is supported by a specific card. + 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 + <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. @param dh Valid handle to a Meinberg device @@ -881,11 +855,12 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_sync_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ; /** - Wait until the next second change, then return a ::PCPS_TIME - structure similar to mbg_get_time(). + @brief Wait until the next second change, then return current time. - <b>Note:</b> This API call is supported under Windows only. - The call blocks until the kernel driver detects a second change + 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. @param dh Valid handle to a Meinberg device @@ -898,16 +873,18 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_time_sec_change( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ; /** - Read a ::PCPS_HR_TIME (High Resolution time) structure returning + @brief Read the card's current time with high resolution, plus status. + + Fills up a ::PCPS_HR_TIME (High Resolution time) structure containing the current %UTC time (seconds since 1970), %UTC offset, and status. - The macro _pcps_has_hr_time() or the API call mbg_dev_has_hr_time() - check whether this call is supported by a specific card. + The macro _pcps_has_hr_time() or the API call mbg_dev_has_hr_time() + check whether this call is supported by a device. - <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. + <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 - provides mechanisms to account for and/or compensate the latency. + provide ways to account for and/or compensate the latency. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_HR_TIME structure to be filled up @@ -922,10 +899,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_hr_time( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) ; /* (Intentionally excluded from Doxygen ) - Write a high resolution time stamp ::PCPS_TIME_STAMP to the clock + 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 specific card. + The macro _pcps_has_event_time() or the API call mbg_dev_has_event_time() + check whether this call is supported by a device. <b>Note:</b> This is only supported by some special firmware. @@ -939,13 +916,15 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_event_time( MBG_DEV_HANDLE dh, const PCPS_TIME_STAMP *p ) ; /** - Read the configuration of a device's serial port. - The macro _pcps_has_serial() checks whether this call - is supported by a specific card. + @brief Read the serial port configuration from an old type of device. + + <b>Note:</b> Direct usage of this function is obsolete. - <b>Note:</b> This function is supported only by a certain class - of devices, so it should not be called directly. The generic - function mbg_get_serial_settings() should be used instead. + The generic API function mbg_get_serial_settings() should be used instead + which fully supports the capabilities of current devices. + + The macro _pcps_has_serial() checks whether this call + is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_SERIAL structure to be filled up @@ -958,13 +937,15 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_serial( MBG_DEV_HANDLE dh, PCPS_SERIAL *p ) ; /** - Write the configuration of a device's serial port. - The macro _pcps_has_serial() checks whether this call - is supported by a specific card. + @brief Write the serial port configuration to an old type of device. + + <b>Note:</b> Direct usage of this function is obsolete. + + The generic API function mbg_save_serial_settings() should be used instead + which fully supports the capabilities of current devices. - <b>Note:</b> This function is supported only by a certain class - of devices, so it should not be called directly. The generic - function mbg_save_serial_settings() should be used instead. + The macro _pcps_has_serial() checks whether this call + is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_SERIAL structure to be written @@ -977,13 +958,16 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_serial( MBG_DEV_HANDLE dh, const PCPS_SERIAL *p ) ; /** - Read the card's time zone/daylight saving configuration code. - That tzcode is supported by some simpler cards and only allows only - a very basic configuration. - The macro _pcps_has_tzcode() or the API call mbg_dev_has_tzcode() - check whether this call is supported by a specific card. + @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 macro _pcps_has_tzcode() or the API call mbg_dev_has_tzcode() + check whether this call is supported by a device. + 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 + calls instead which allow for a more detailed configuration of the time zone and daylight saving settings. @param dh Valid handle to a Meinberg device @@ -1000,13 +984,16 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_tzcode( MBG_DEV_HANDLE dh, PCPS_TZCODE *p ) ; /** - Write the card's time zone/daylight saving configuration code. - That tzcode is supported by some simpler cards and only allows only - a very basic configuration. - The macro _pcps_has_tzcode() or the API call mbg_dev_has_tzcode() - check whether this call is supported by a specific card. + @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 macro _pcps_has_tzcode() or the API call mbg_dev_has_tzcode() + check whether this call is supported by a device. + 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 + calls instead which allow for a more detailed configuration of the time zone and daylight saving settings. @param dh Valid handle to a Meinberg device @@ -1023,12 +1010,17 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_tzcode( MBG_DEV_HANDLE dh, const PCPS_TZCODE *p ) ; /** - Read the card's time zone/daylight saving parameters using the - ::PCPS_TZDL structure. - The macro _pcps_has_pcps_tzdl() or the API call mbg_dev_has_pcps_tzdl() - check whether this call is supported by a specific card. - Other cards may support the mbg_get_tzcode() or mbg_get_gps_tzdl() - calls instead. + @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 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_get_tzcode() or mbg_get_gps_tzdl() + calls instead. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_TZDL structure to be filled up @@ -1044,12 +1036,16 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_pcps_tzdl( MBG_DEV_HANDLE dh, PCPS_TZDL *p ) ; /** - Write the card's time zone/daylight saving parameters using the - ::PCPS_TZDL structure. - The macro _pcps_has_pcps_tzdl() or the API call mbg_dev_has_pcps_tzdl() - check whether this call is supported by a specific card. - Other cards may support the mbg_set_tzcode() or mbg_set_gps_tzdl() - calls instead. + @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 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. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_TZDL structure to be written @@ -1065,10 +1061,14 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_pcps_tzdl( MBG_DEV_HANDLE dh, const PCPS_TZDL *p ) ; /** - Read the reference time offset from %UTC for clocks which can't determine - that offset automatically, e.g. from an IRIG input signal. - The macro _pcps_has_ref_offs() or the API call mbg_dev_has_ref_offs() - check whether this call is supported by a specific card. + @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 macro _pcps_has_ref_offs() or the API call mbg_dev_has_ref_offs() + check whether this call is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::MBG_REF_OFFS value to be filled up @@ -1082,10 +1082,14 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_ref_offs( MBG_DEV_HANDLE dh, MBG_REF_OFFS *p ) ; /** - Write the reference time offset from %UTC for clocks which can't determine - that offset automatically, e.g. from an IRIG input signal. - The macro _pcps_has_ref_offs() or the API call mbg_dev_has_ref_offs() - check whether this call is supported by a specific card. + @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 macro _pcps_has_ref_offs() or the API call mbg_dev_has_ref_offs() + check whether this call is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::MBG_REF_OFFS value to be written @@ -1099,11 +1103,12 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_ref_offs( MBG_DEV_HANDLE dh, const MBG_REF_OFFS *p ) ; /** - 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 + @brief Read a ::MBG_OPT_INFO structure containing optional settings, controlled by flags. + + The ::MBG_OPT_INFO structure contains a mask of supported flags plus the current settings of those flags. - The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags() - check whether this call is supported by a specific card. + The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags() + check whether this call is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::MBG_OPT_INFO structure to be filled up @@ -1116,11 +1121,12 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_opt_info( MBG_DEV_HANDLE dh, MBG_OPT_INFO *p ) ; /** - Write a ::MBG_OPT_SETTINGS structure contains optional settings, controlled by flags. - The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags() - check whether this call is supported by a specific card. - The ::MBG_OPT_INFO structure should be read first to check which of the specified - flags is supported by a specific card. + @brief Write a ::MBG_OPT_SETTINGS structure containing optional device settings. + + The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags() + check whether this call is supported by a device. + The ::MBG_OPT_INFO structure should be read first to check which of the specified + flag is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::MBG_OPT_SETTINGS structure to be written @@ -1133,16 +1139,21 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_opt_settings( MBG_DEV_HANDLE dh, const MBG_OPT_SETTINGS *p ) ; /** - Read an ::IRIG_INFO structure containing the configuration of an IRIG input - plus the possible settings supported by that input. - The macro _pcps_is_irig_rx() or the API call mbg_dev_is_irig_rx() - check whether this call is supported by a specific card. + @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() @@ -1152,10 +1163,15 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_irig_rx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p ) ; /** - Write an ::IRIG_SETTINGS structure containing the configuration of an 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 specific card. - The ::IRIG_INFO structure should be read first to determine the possible + @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 @@ -1163,6 +1179,7 @@ extern "C" { @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() @@ -1172,7 +1189,48 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_irig_rx_settings( MBG_DEV_HANDLE dh, const IRIG_SETTINGS *p ) ; /** - Check if a specific device supports the mbg_get_irig_ctrl_bits() call. + @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() +*/ + _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() +*/ + _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. @@ -1184,14 +1242,27 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh, int *p ) ; /** - Read a ::MBG_IRIG_CTRL_BITS type which contains 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. + @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 specific card. + 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 @@ -1203,7 +1274,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_irig_ctrl_bits( MBG_DEV_HANDLE dh, MBG_IRIG_CTRL_BITS *p ) ; /** - Check if a specific device supports the mbg_get_raw_irig_data() call. + @brief Check if a device supports the mbg_get_raw_irig_data() call. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -1216,10 +1287,14 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_raw_irig_data( MBG_DEV_HANDLE dh, int *p ) ; /** - Read a ::MBG_RAW_IRIG_DATA type which contains all data - bits of the latest IRIG input frame. + @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 specific card. + 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 @@ -1232,10 +1307,13 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data( MBG_DEV_HANDLE dh, MBG_RAW_IRIG_DATA *p ) ; /** - Read a ::MBG_RAW_IRIG_DATA type just after a second change which contains all data - bits of the latest IRIG input frame. + @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 specific card. + 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. @@ -1247,11 +1325,12 @@ extern "C" { @see mbg_dev_has_raw_irig_data() @see mbg_get_raw_irig_data() + @see mbg_get_time_sec_change() */ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data_on_sec_change( MBG_DEV_HANDLE dh, MBG_RAW_IRIG_DATA *p ) ; /** - Check if a specific device supports the mbg_get_irig_time() call. + @brief Check if a device supports the mbg_get_irig_time() call. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -1263,12 +1342,15 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_irig_time( MBG_DEV_HANDLE dh, int *p ) ; /** - Read a ::PCPS_IRIG_TIME type which returns the raw IRIG day-of-year number + @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 specific card. + 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 @@ -1280,9 +1362,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_irig_time( MBG_DEV_HANDLE dh, PCPS_IRIG_TIME *p ) ; /** - Clear the card'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 specific card. + @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 @@ -1295,10 +1378,14 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_clr_ucap_buff( MBG_DEV_HANDLE dh ) ; /** - Read a ::PCPS_UCAP_ENTRIES structure to retrieve the number of saved - user capture events and the maximum capture buffer size. - The macro _pcps_has_ucap() or the API call mbg_dev_has_ucap() - check whether this call is supported by a specific card. + @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 @@ -1312,16 +1399,19 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_ucap_entries( MBG_DEV_HANDLE dh, PCPS_UCAP_ENTRIES *p ) ; /** - Retrieve a single time capture event from the on-board FIFO buffer - using a ::PCPS_HR_TIME structure. The oldest entry of the FIFO is retrieved - and then removed from the FIFO. - If no capture event is available in the FIFO buffer then both the seconds + @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 specific card. + + 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 + call which is obsolete but still supported for compatibility with older cards. @param dh Valid handle to a Meinberg device @@ -1336,14 +1426,17 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_ucap_event( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) ; /** - Read the card's time zone/daylight saving parameters using the ::TZDL - structure. - The macro _pcps_has_tzdl() or the API call mbg_dev_has_tzdl() - check whether this call is supported by a specific card. + @brief Read the card's time zone/daylight saving parameters. - <b>Note:</b> In spite of the function name this call may also be + 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. + 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 @@ -1359,14 +1452,17 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_gps_tzdl( MBG_DEV_HANDLE dh, TZDL *p ) ; /** - Write the card's time zone/daylight saving parameters using the ::TZDL - structure. - The macro _pcps_has_tzdl() or the API call mbg_dev_has_tzdl() - check whether this call is supported by a specific card. + @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. - <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. + 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 @@ -1382,13 +1478,15 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_gps_tzdl( MBG_DEV_HANDLE dh, const TZDL *p ) ; /** - Retrieve the software revision of a GPS receiver. - This call is obsolete but still supported for compatibility + @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 specific card. + check whether this call is supported by a device. - <b>Note:</b> The function mbg_get_gps_receiver_info() should + <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 @@ -1402,11 +1500,15 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_gps_sw_rev( MBG_DEV_HANDLE dh, SW_REV *p ) ; /** - Retrieve the status of the battery buffered GPS variables. + @brief Retrieve the status of the battery buffered GPS variables. + + These GPS variables hold some parameters sent by the GPS satellites + which are required for proper operation. If the saved set of parameters + 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 specific card. - The GPS receiver stays in cold boot mode until all of the - data sets are valid. + 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 @@ -1416,25 +1518,32 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_gps_bvar_stat( MBG_DEV_HANDLE dh, BVAR_STAT *p ) ; /** - Read the current board time using a ::TTM structure. + @brief Read the current board time using a ::TTM structure. + The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a specific card. + check whether this call is supported by a device. - <b>Note:</b> This call is pretty slow, so the mbg_get_hr_time_..() - group of calls should be used preferably. + <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() */ _MBG_API_ATTR int _MBG_API mbg_get_gps_time( MBG_DEV_HANDLE dh, TTM *p ) ; /** - Write a ::TTM structure to a GPS receiver in order to set the + @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 specific card. + 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 @@ -1444,15 +1553,15 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_gps_time( MBG_DEV_HANDLE dh, const TTM *p ) ; /** - Read a ::PORT_PARM structure to retrieve the configuration - of the device's serial ports. + @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 specific card. + 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. + <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 @@ -1464,15 +1573,15 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_gps_port_parm( MBG_DEV_HANDLE dh, PORT_PARM *p ) ; /** - Write a ::PORT_PARM structure to configure the on-board - serial ports. + @brief Write a ::PORT_PARM structure to configure the on-board serial ports. + The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a specific card. + 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. + <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 @@ -1484,13 +1593,16 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_gps_port_parm( MBG_DEV_HANDLE dh, const PORT_PARM *p ) ; /** - Read an ::ANT_INFO structure to retrieve status information of the GPS antenna. + @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 specific card. + check whether this call is supported by a device. - <b>Note:</b> Normally the antenna connection status can also be + <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. + 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 @@ -1500,14 +1612,15 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_gps_ant_info( MBG_DEV_HANDLE dh, ANT_INFO *p ) ; /** - Read a time capture event from the on-board FIFO buffer using a ::TTM structure. + @brief Read a time capture event from the on-board FIFO buffer using a ::TTM structure. + The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a specific card. + 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 card. Anyway, this call is still supported for compatibility - with older cards. + <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 @@ -1521,13 +1634,16 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_gps_ucap( MBG_DEV_HANDLE dh, TTM *p ) ; /** - Read an ::ENABLE_FLAGS structure reporting whether certain outputs - shall be enabled immediately after the card's power-up, or only + @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 specific card. + check whether this call is supported by a device. - <b>Note:</b> Not all of the input signals specified for the + <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 @@ -1541,13 +1657,16 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_gps_enable_flags( MBG_DEV_HANDLE dh, ENABLE_FLAGS *p ) ; /** - Write an ENABLE_FLAGS structure to configure whether certain outputs - shall be enabled immediately after the card's power-up, or only + @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 specific card. + check whether this call is supported by a device. - <b>Note:</b> Not all of the input signals specified for the + <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 @@ -1561,11 +1680,13 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_gps_enable_flags( MBG_DEV_HANDLE dh, const ENABLE_FLAGS *p ) ; /** - Read a ::STAT_INFO structure to retrieve the status of the - GPS receiver, including mode of operation and numer of - visible/usable satellites. + @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 specific card. + 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 @@ -1577,9 +1698,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_gps_stat_info( MBG_DEV_HANDLE dh, STAT_INFO *p ) ; /** - Sends a ::GPS_CMD to a GPS receiver. + @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 specific card. + check whether this call is supported by a device. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::GPS_CMD @@ -1591,10 +1713,15 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_gps_cmd( MBG_DEV_HANDLE dh, const GPS_CMD *p ) ; /** - Read the current GPS receiver position using the ::POS structure - which contains different coordinate formats. + @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 specific card. + 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 @@ -1607,10 +1734,13 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_gps_pos( MBG_DEV_HANDLE dh, POS *p ) ; /** - Preset the GPS receiver position using ::XYZ coordinates - (ECEF: WGS84 "Earth Centered, Earth fixed" kartesian coordinates). + @brief Set the GPS receiver position using ::XYZ coordinates. + + The structure ::XYZ must specify the new position in ECEF + (Earth Centered, Earth Fixed) kartesian coordinates. + The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a specific card. + 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 @@ -1623,10 +1753,13 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_xyz( MBG_DEV_HANDLE dh, const XYZ p ) ; /** - Preset the GPS receiver position using ::LLA coordinates - (longitude, latitude, altitude) + @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 specific card. + 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 @@ -1639,10 +1772,13 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_lla( MBG_DEV_HANDLE dh, const LLA p ) ; /** - Read the configured length of the GPS antenna cable (::ANT_CABLE_LEN). - The cable delay is internally compensated by 5ns per meter cable. + @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 specific card. + 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 @@ -1655,10 +1791,13 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_gps_ant_cable_len( MBG_DEV_HANDLE dh, ANT_CABLE_LEN *p ) ; /** - Write the length of the GPS antenna cable (::ANT_CABLE_LEN). - The cable delay is internally compensated by 5ns per meter cable. + @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 specific card. + 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 @@ -1671,13 +1810,14 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_gps_ant_cable_len( MBG_DEV_HANDLE dh, const ANT_CABLE_LEN *p ) ; /** - Read a ::RECEIVER_INFO structure from a card. + @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 specific card. + 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 card which don't provide that structure by themselves. + <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 @@ -1689,7 +1829,8 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_gps_receiver_info( MBG_DEV_HANDLE dh, RECEIVER_INFO *p ) ; /** - Read a ::STR_TYPE_INFO_IDX array of supported string types. + @brief Read a ::STR_TYPE_INFO_IDX array of supported string types. + The function mbg_setup_receiver_info() must have been called before, and the returned ::RECEIVER_INFO structure passed to this function. @@ -1709,7 +1850,8 @@ extern "C" { _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 ) ; /** - Read a ::PORT_INFO_IDX array of supported serial port configurations. + @brief Read a ::PORT_INFO_IDX array of supported serial port configurations. + The function mbg_setup_receiver_info() must have been called before, and the returned ::RECEIVER_INFO structure passed to this function. @@ -1729,13 +1871,16 @@ extern "C" { _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 ) ; /** - Write the configuration for a single serial port using the ::PORT_SETTINGS_IDX - structure which 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(). + @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 specific card. + check whether this call is supported by a device. - <b>Note:</b> The function mbg_save_serial_settings() should be used preferably + <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. @@ -1750,13 +1895,16 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings_idx( MBG_DEV_HANDLE dh, const PORT_SETTINGS_IDX *p ) ; /** - Write the configuration for a single serial port using the ::PORT_SETTINGS - structure plus the port index. - Except for the parameter types, this call is equivalent to mbg_set_gps_port_settings_idx(). + @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 specific card. + check whether this call is supported by a device. - <b>Note:</b> The function mbg_save_serial_settings() should be used preferably + <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. @@ -1772,11 +1920,12 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings( MBG_DEV_HANDLE dh, const PORT_SETTINGS *p, int idx ) ; /** - Set up a ::RECEIVER_INFO structure for a device. + @brief Set up a ::RECEIVER_INFO structure for a device. + If the device supports the ::RECEIVER_INFO structure then the structure - is read from the device, otherwise a structure is set up using + 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, + 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. @@ -1791,9 +1940,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_setup_receiver_info( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, RECEIVER_INFO *p ) ; /** - Read the version code of the on-board PCI/PCIe interface ASIC. + @brief Read the version code of the on-board PCI/PCIe interface ASIC. + The macro _pcps_has_asic_version() or the API call mbg_dev_has_asic_version() - check whether this call is supported by a specific card. + 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 @@ -1805,9 +1955,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_asic_version( MBG_DEV_HANDLE dh, PCI_ASIC_VERSION *p ) ; /** - Read the features of the on-board PCI/PCIe interface ASIC. + @brief Read the features of the on-board PCI/PCIe interface ASIC. + The macro _pcps_has_asic_features() or the API call mbg_dev_has_asic_features() - check whether this call is supported by a specific card. + 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 @@ -1819,10 +1970,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_asic_features( MBG_DEV_HANDLE dh, PCI_ASIC_FEATURES *p ) ; /** - Check if a specific device supports configurable time scales. + @brief Check if a device supports configurable time scales. - By default the cards return UTC and/or local time. However, some cards - can be configured to return pure GPS time or TAI instead. + 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. @@ -1835,11 +1986,13 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_time_scale( MBG_DEV_HANDLE dh, int *p ) ; /** - Read a ::MBG_TIME_SCALE_INFO structure from a card telling which time scales - are supported by a card, and the current settings of the card. + @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 specific card. + 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 @@ -1853,14 +2006,16 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_time_scale_info( MBG_DEV_HANDLE dh, MBG_TIME_SCALE_INFO *p ) ; /** - Write a ::MBG_TIME_SCALE_SETTINGS structure to a card which determines - which time scale shall be represented by time stamps read from the card. + @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 specific card. + 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 + 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 @@ -1874,15 +2029,18 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_time_scale_settings( MBG_DEV_HANDLE dh, MBG_TIME_SCALE_SETTINGS *p ) ; /** - Check if a specific device supports reading/writing a GPS UTC parameter - set via the PC bus (reading/writing these parameters via the serial port - is supported by all GPS devices). + @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 parameters are normally received from the satellites' broadcasts - and contain the current time offset between GPT time and UTC, plus information - on a pending leap second. + 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 + 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 @@ -1896,10 +2054,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_utc_parm( MBG_DEV_HANDLE dh, int *p ) ; /** - Read a ::UTC structure from a card. + @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 specific card. + 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 @@ -1913,15 +2071,15 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_utc_parm( MBG_DEV_HANDLE dh, UTC *p ) ; /** - Write a ::UTC structure to a card. + @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 card receives any satellites the settings - written to the board are overwritten by the parameters broadcasted + 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 specific card. + 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 @@ -1935,22 +2093,24 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_utc_parm( MBG_DEV_HANDLE dh, UTC *p ) ; /** - Read a ::PCPS_TIME_CYCLES structure that contains a ::PCPS_TIME structure + @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 specific card since that call provides much better accuracy than this one. + 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 other operating systems the returned - cycles value is always 0. + 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 + 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 @@ -1966,21 +2126,23 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_time_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_CYCLES *p ) ; /** - Read a ::PCPS_HR_TIME_CYCLES structure that contains a ::PCPS_HR_TIME structure + @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 specific card. + 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 other operating systems the returned - cycles value is always 0. + 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 + 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 @@ -1996,25 +2158,27 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_hr_time_cycles( MBG_DEV_HANDLE dh, PCPS_HR_TIME_CYCLES *p ) ; /** - Read a ::PCPS_HR_TIME structure plus cycle counter value, and correct the + @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 specific card. + 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 other operating systems the returned - cycles value is always 0. + 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 + 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 + @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. @@ -2027,10 +2191,13 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_hr_time_comp( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p, int32_t *hns_latency ) ; /** - Read an ::IRIG_INFO structure containing the configuration of an IRIG output + @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 specific card. + + 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 @@ -2046,9 +2213,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_irig_tx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p ) ; /** - Write an ::IRIG_SETTINGS structure containing the configuration of an 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 specific card. + @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 @@ -2064,10 +2232,13 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_irig_tx_settings( MBG_DEV_HANDLE dh, const IRIG_SETTINGS *p ) ; /** - Read a ::SYNTH structure containing the configuration of an optional + @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 specific card. + + 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 @@ -2082,10 +2253,13 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_synth( MBG_DEV_HANDLE dh, SYNTH *p ) ; /** - Write a ::SYNTH structure containing the configuration of an optional + @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 specific card. + + 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 @@ -2100,10 +2274,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_synth( MBG_DEV_HANDLE dh, const SYNTH *p ) ; /** - Read a ::SYNTH_STATE structure reporting the current state - 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 specific card. + @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 @@ -2118,7 +2292,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_synth_state( MBG_DEV_HANDLE dh, SYNTH_STATE *p ) ; /** - Check if a specific device supports the mbg_get_fast_hr_timestamp_...() calls. + @brief Check if a device supports the mbg_get_fast_hr_timestamp_...() calls. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2132,7 +2306,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_fast_hr_timestamp( MBG_DEV_HANDLE dh, int *p ) ; /** - Read a high resolution ::PCPS_TIME_STAMP_CYCLES structure via memory mapped access. + @brief Read a high resolution ::PCPS_TIME_STAMP_CYCLES structure via memory mapped access. @param dh Valid handle to a Meinberg device @param *p Pointer to a ::PCPS_TIME_STAMP_CYCLES structure to be filled up @@ -2146,8 +2320,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP_CYCLES *p ) ; /** - Read a high resolution ::PCPS_TIME_STAMP via memory mapped access, - and compensate the latency of the time stamp before it is returned. + @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 @@ -2162,12 +2338,12 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_comp( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP *p, int32_t *hns_latency ) ; /** - Read a high resolution ::PCPS_TIME_STAMP structure via memory mapped access. + @brief Read a high resolution ::PCPS_TIME_STAMP structure via memory mapped access. This function does not return or evaluate a cycles count, so the latency of the call can not be determined. However, depending on the timer hardware 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 + 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 @@ -2182,7 +2358,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP *p ) ; /** - Check if a specific device is a GPS receiver. + @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. @@ -2192,7 +2368,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_is_gps( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device is a DCF77 receiver. + @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. @@ -2202,7 +2378,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_is_dcf( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device is a MSF receiver. + @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. @@ -2212,7 +2388,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_is_msf( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device is a WWVB receiver. + @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. @@ -2222,7 +2398,9 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_is_wwvb( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device is a long wave signal receiver, e.g. DCF77, MSF or WWVB. + @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. @@ -2232,8 +2410,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_is_lwr( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device is an IRIG receiver which supports - configuration of the IRIG input. + @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. @@ -2248,7 +2425,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_is_irig_rx( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device supports the HR_TIME functions. + @brief Check if a device supports the HR_TIME functions. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2262,7 +2439,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_hr_time( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device supports configuration of antenna cable length. + @brief Check if a device supports configuration of antenna cable length. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2275,8 +2452,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_cab_len( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device supports timezone / daylight saving configuration - using the ::TZDL structure. + @brief Check if a device supports timezone configuration using the ::TZDL structure. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2290,8 +2466,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_tzdl( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device supports timezone / daylight saving configuration - using the ::PCPS_TZDL structure. + @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2305,8 +2480,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_pcps_tzdl( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device supports timezone configuration - using the ::PCPS_TZCODE type. + @brief Check if a device supports timezone configuration using the ::PCPS_TZCODE type. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2320,9 +2494,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_tzcode( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific 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. + @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. @@ -2336,7 +2511,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_tz( MBG_DEV_HANDLE dh, int *p ) ; /* (Intentionally excluded from Doxygen) - Check if a specific device supports setting an event time, i.e. + 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. @@ -2351,11 +2526,12 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_event_time( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device supports the ::RECEIVER_INFO structure and related calls. - Older GPS devices may not support that structure. + @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 + 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 @@ -2368,8 +2544,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_receiver_info( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device supports the mbg_clr_ucap_buff() call - used to clear a card's on-board time capture FIFO buffer. + @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. @@ -2381,10 +2559,9 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_can_clr_ucap_buff( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device supports the mbg_get_ucap_entries() and - mbg_get_ucap_event() calls. + @brief Check if a device supports the mbg_get_ucap_entries() and mbg_get_ucap_event() calls. - If the card does not but it is a GPS card then the card provides + 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. @@ -2401,8 +2578,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_ucap( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device provides an IRIG output which can - be configured. + @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. @@ -2419,9 +2595,9 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_irig_tx( MBG_DEV_HANDLE dh, int *p ) ; /* (Intentionally excluded from Doxygen) - Check if a specific device provides a serial output supporting + 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. + 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. @@ -2436,8 +2612,9 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_serial_hs( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device provides an input signal level value which - may be displayed, e.g. DCF77 or IRIG cards. + @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. @@ -2447,8 +2624,9 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_signal( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device provides an modulation signal which may be - displayed, e.g. the second marks of a DCF77 AM receiver. + @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. @@ -2458,7 +2636,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_mod( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device provides either an IRIG input or output. + @brief Check if a device provides either an IRIG input or output. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2471,8 +2649,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_irig( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device provides a configurable ref time offset - required to convert the received time to %UTC. + @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. @@ -2485,8 +2665,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_ref_offs( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS - structures containing optional settings, controlled by flags. + @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. @@ -2499,8 +2681,9 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_opt_flags( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device supports large configuration data structures - as have been introducesde with the GPS receivers. + @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. @@ -2510,7 +2693,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_gps_data( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device provides a programmable frequency synthesizer. + @brief Check if a device provides a programmable frequency synthesizer. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2523,7 +2706,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_synth( MBG_DEV_HANDLE dh, int *p ) ; /* (Intentionally excluded from Doxygen) - Check if a specific device supports the mbg_generic_io() call. + @brief Check if a device supports the mbg_generic_io() call. <b>Warning</b>: That call is for debugging purposes and internal use only! @@ -2537,7 +2720,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_generic_io( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device supports the mbg_get_asic_version() call. + @brief Check if a device supports the mbg_get_asic_version() call. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2549,7 +2732,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_asic_version( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device supports the mbg_get_asic_features() call. + @brief Check if a device supports the mbg_get_asic_features() call. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2561,14 +2744,17 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_asic_features( MBG_DEV_HANDLE dh, int *p ) ; /** - Read a ::POUT_INFO_IDX array of current settings and configuration - options of a card's programmable pulse outputs. + @brief Read current configuraton and features provided by the programmable pulse outputs. + + Reads a ::POUT_INFO_IDX array of current settings and configuration + options of the device's programmable pulse outputs. + 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 + 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 + 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. @@ -2584,13 +2770,14 @@ extern "C" { _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 ) ; /** - Write the configuration for a single programmable pulse output using - the ::POUT_SETTINGS_IDX structure which 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 + @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. @@ -2604,12 +2791,15 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings_idx( MBG_DEV_HANDLE dh, const POUT_SETTINGS_IDX *p ) ; /** - Write the configuration for a single programmable pulse output using - the ::POUT_SETTINGS structure plus the index of the output to be configured. - 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 + @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. @@ -2624,9 +2814,11 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings( MBG_DEV_HANDLE dh, const POUT_SETTINGS *p, int idx ) ; /** - Read a card's IRQ status information which includes flags indicating - whether IRQs are currently enabled, and whether IRQ support by a card - is possibly unsafe due to the firmware and interface chip version. + @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 @@ -2636,7 +2828,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_irq_stat_info( MBG_DEV_HANDLE dh, PCPS_IRQ_STAT_INFO *p ) ; /** - Check if a specific device provides simple LAN interface API calls. + @brief Check if a device provides simple LAN interface API calls. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2651,9 +2843,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_lan_intf( MBG_DEV_HANDLE dh, int *p ) ; /** - Read LAN interface information from a card which supports this. + @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 specific card. + 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 @@ -2668,9 +2861,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_lan_if_info( MBG_DEV_HANDLE dh, LAN_IF_INFO *p ) ; /** - Read LAN IPv4 state from a card which supports this. + @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 specific card. + 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 @@ -2685,9 +2879,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_ip4_state( MBG_DEV_HANDLE dh, IP4_SETTINGS *p ) ; /** - Read LAN IPv4 settings from a card which supports this. + @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 specific card. + 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 @@ -2702,9 +2897,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_ip4_settings( MBG_DEV_HANDLE dh, IP4_SETTINGS *p ) ; /** - Write LAN IPv4 settings to a card which supports this. + @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 specific card. + 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 @@ -2718,106 +2914,122 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_ip4_settings( MBG_DEV_HANDLE dh, const IP4_SETTINGS *p ) ; /** - Check if a specific device provides PTP configuration/status calls. + @brief Check if a device provides PTP configuration/status calls. @param dh Valid handle to a Meinberg device @param *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_ptp_state() - @see mbg_get_ptp_cfg_info() - @see mbg_set_ptp_cfg_settings() + @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 ) ; /** - Check if a specific device provides PTP Unicast feature/configuration. + @brief Check if a device provides PTP unicast feature/configuration. @param dh Valid handle to a Meinberg device @param *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_ptp_state() - @see mbg_get_ptp_uc_master_cfg_limits() - @see mbg_get_all_ptp_uc_master_info() - @see mbg_set_ptp_unicast_cfg_settings() + @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 ) ; /** - Read PTP/IEEE1588 status from a card which supports this. + @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 specific card. + 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 + @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_ptp_cfg_info() - @see mbg_set_ptp_cfg_settings() + @see mbg_dev_has_ptp + @see mbg_get_all_ptp_cfg_info + @see mbg_get_ptp_cfg_info + @see mbg_set_ptp_cfg_settings + @see mbg_dev_has_ptp_unicast */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_state( MBG_DEV_HANDLE dh, PTP_STATE *p ) ; /** - Read PTP/IEEE1588 config info and current settings from a card which supports this. + @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 specific card. + 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_ptp_state() - @see mbg_set_ptp_cfg_settings() + @see mbg_dev_has_ptp + @see mbg_get_all_ptp_cfg_info + @see mbg_get_ptp_state + @see mbg_set_ptp_cfg_settings + @see mbg_dev_has_ptp_unicast */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_cfg_info( MBG_DEV_HANDLE dh, PTP_CFG_INFO *p ) ; /** - Write PTP/IEEE1588 configuration settings to a card which supports this. + @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 specific card. + 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_ptp_state() - @see mbg_get_ptp_cfg_info() + @see mbg_dev_has_ptp + @see mbg_get_all_ptp_cfg_info + @see mbg_get_ptp_state + @see mbg_get_ptp_cfg_info + @see mbg_dev_has_ptp_unicast */ _MBG_API_ATTR int _MBG_API mbg_set_ptp_cfg_settings( MBG_DEV_HANDLE dh, const PTP_CFG_SETTINGS *p ) ; /** - Read PTP/IEEE1588 unicast config info and current settings from a card which supports this. + @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 specific card. + check whether this call is supported by a device. @param dh Valid handle to a Meinberg device - @param *p Pointer to a ::PTP_UNICAST_CFG_INFO variable to be filled up + @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_set_ptp_unicast_cfg_settings() + @see mbg_dev_has_ptp_unicast + @see mbg_get_all_ptp_cfg_info + @see mbg_get_all_ptp_uc_master_info + @see mbg_set_ptp_uc_master_settings_idx + @see mbg_get_ptp_state */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_uc_master_cfg_limits( MBG_DEV_HANDLE dh, PTP_UC_MASTER_CFG_LIMITS *p ) ; /** - Read a ::IOCTL_SET_PTP_UNICAST_CFG_SETTINGS array of current settings and configuration - options of a card's programmable pulse outputs. + @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 + 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 + 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. @@ -2826,33 +3038,38 @@ extern "C" { @return ::MBG_SUCCESS or error code returned by device I/O control function. - @see //##++++++++++++++++++++++ - @see - @see + @see mbg_dev_has_ptp_unicast + @see mbg_get_all_ptp_cfg_info + @see mbg_get_ptp_uc_master_cfg_limits + @see mbg_set_ptp_uc_master_settings_idx + @see mbg_get_ptp_state */ _MBG_API_ATTR int _MBG_API mbg_get_all_ptp_uc_master_info( MBG_DEV_HANDLE dh, PTP_UC_MASTER_INFO_IDX pii[], const PTP_UC_MASTER_CFG_LIMITS *p_umsl ) ; /** - Write PTP/IEEE1588 unicast configuration settings to a card which supports this. + @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 specific card. + check whether this call is supported by a device. @param dh Valid handle to a Meinberg device. - @param *p ::PTP_UNICAST_CFG_SETTINGS structure to be written + @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_ptp_state() - @see mbg_get_ptp_cfg_info() - @see mbg_get_ptp_unicast_cfg_info() + @see mbg_dev_has_ptp_unicast + @see mbg_get_all_ptp_cfg_info + @see mbg_get_ptp_uc_master_cfg_limits + @see mbg_get_all_ptp_uc_master_info + @see mbg_get_ptp_state */ _MBG_API_ATTR int _MBG_API mbg_set_ptp_uc_master_settings_idx( MBG_DEV_HANDLE dh, const PTP_UC_MASTER_SETTINGS_IDX *p ) ; /** - Read system time and card 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 + @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. @@ -2862,8 +3079,8 @@ extern "C" { 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 with a specific card. + _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 @@ -2876,10 +3093,12 @@ extern "C" { _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 with a specific card. + 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 @@ -2892,7 +3111,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_time_info_tstamp( MBG_DEV_HANDLE dh, MBG_TIME_INFO_TSTAMP *p ) ; /** - Check if a specific device supports demodulation of the DCF77 PZF code. + @brief Check if a device supports demodulation of the DCF77 PZF code. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2905,7 +3124,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_pzf( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device supports reading correlation info. + @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. @@ -2918,8 +3137,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_corr_info( MBG_DEV_HANDLE dh, int *p ) ; /** - Check if a specific device supports configurable distance from transmitter - used to compensate RF propagation delay. + @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. @@ -2933,9 +3154,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_tr_distance( MBG_DEV_HANDLE dh, int *p ) ; /** - Read PZF correlation info from a card which supports this. + @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 specific card. + 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 @@ -2948,11 +3170,13 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_corr_info( MBG_DEV_HANDLE dh, CORR_INFO *p ) ; /** - Read configurable "distance from transmitter" parameter from a card - which supports this. The parameter is used to compensate the RF signal - propagation delay. + @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 specific card. + 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 @@ -2966,11 +3190,13 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_tr_distance( MBG_DEV_HANDLE dh, TR_DISTANCE *p ) ; /** - Write configurable "distance from transmitter" parameter to a card - which supports this. The parameter is used to compensate the RF signal - propagation delay. + @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 specific card. + 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 @@ -2984,7 +3210,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_tr_distance( MBG_DEV_HANDLE dh, const TR_DISTANCE *p ) ; /** - Check if a specific device provides a debug status word to be read. + @brief Check if a device provides a debug status word to be read. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -2996,13 +3222,16 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_debug_status( MBG_DEV_HANDLE dh, int *p ) ; /** - Read a debug status word from a card. 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. + @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 specific card. + 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 @@ -3014,7 +3243,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_debug_status( MBG_DEV_HANDLE dh, MBG_DEBUG_STATUS *p ) ; /** - Check if a specific device provides an on-board event log. + @brief Check if a device provides an on-board event log. @param dh Valid handle to a Meinberg device @param *p Pointer to an int which is set 0 or != 0 unless the call fails. @@ -3029,9 +3258,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_dev_has_evt_log( MBG_DEV_HANDLE dh, int *p ) ; /** - Clear the card's on-board event log. + @brief Clear the card's on-board event log. + The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - check whether this call is supported by a specific device. + check whether this call is supported by a device. @param dh Valid handle to a Meinberg device @@ -3045,13 +3275,14 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_clr_evt_log( MBG_DEV_HANDLE dh ) ; /** - Read max number of num event log entries which can - be saved on the board, and how many entries actually + @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. - _pcps_has_evt_log() checks whether supported. The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - check whether this call is supported by a specific device. + 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 @@ -3066,12 +3297,12 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_num_evt_log_entries( MBG_DEV_HANDLE dh, MBG_NUM_EVT_LOG_ENTRIES *p ) ; /** - Read the first (oldest) event log entry from a device. + @brief Read the first (oldest) event log entry from a device. @note Subsequent reads should be made using mbg_get_next_evt_log_entry(). The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - check whether this call is supported by a specific device. + 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. @@ -3089,13 +3320,13 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_first_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) ; /** - Read the next event log entry from a device. + @brief Read the next event log entry from a device. @note The first read should be made using mbg_get_first_evt_log_entry() to set the on-board read index to the oldest entry. The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - check whether this call is supported by a specific device. + 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. @@ -3113,8 +3344,9 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_next_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) ; /** - Read the CPU affinity of a process, i.e. on which of the available - CPUs the process can be executed. + @brief Read the CPU affinity of a process. + + This means on which of the available CPUs or CPU cores the process can be executed. @param pid The process ID. @param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. @@ -3127,8 +3359,10 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p ) ; /** - Set the CPU affinity of a process, i.e. on which of the available - CPUs the process is allowed to be executed. + @brief Set the CPU affinity of a process. + + This determines on which of the available CPUs + the process is allowed to be executed. @param pid The process ID. @param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. @@ -3141,8 +3375,9 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p ) ; /** - Set the CPU affinity of a process for a single CPU only, i.e. the process - may only be executed on that single CPU. + @brief Set the CPU affinity of a process for a single CPU only. + + This means the process may only be executed on that single CPU. @param cpu_num The number of the CPU. @@ -3154,7 +3389,8 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_current_process_affinity_to_cpu( int cpu_num ) ; /** - Create a new execution thread for the current process. + @brief Create a new execution thread for the current process. + This function is only implemented for targets which support threads. @param p_ti Pointer to a ::MBG_THREAD_INFO structure to be filled up. @@ -3170,8 +3406,9 @@ extern "C" { _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 ) ; /** - Stop a thread which has been created by mbg_thread_create(). Wait - until the thread has finished and release all resources. + @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. @@ -3185,8 +3422,11 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_thread_stop( MBG_THREAD_INFO *p_ti ) ; /** - Let the current thread sleep for a certain interval unless a signal is - received indicating the thread should terminate. + @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. @@ -3202,8 +3442,11 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_thread_sleep_interruptible( MBG_THREAD_INFO *p_ti, ulong sleep_ms ) ; /** - Set the CPU affinity of a single thread, i.e. on which of the available - CPUs the thread is allowed to be executed. + @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. @@ -3218,19 +3461,21 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_thread_set_affinity( MBG_THREAD_INFO *p_ti, MBG_CPU_SET *p ) ; /** - Set up a ::MBG_POLL_THREAD_INFO structure and start a new thread - which runs the mbg_xhrt_poll_thread_fnc() function. + @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. + @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() + else the result of mbg_thread_create() @see mbg_xhrt_poll_thread_fnc() @see mbg_xhrt_poll_thread_stop() @@ -3241,12 +3486,13 @@ extern "C" { _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 ) ; /** - Stop a polling thread started by mbg_xhrt_poll_thread_create() - and release all associated resources. + @brief Stop a polling thread started by mbg_xhrt_poll_thread_create(). + + This call also releases all associated resources. @param *p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. - @return the result of mbg_thread_stop() + @return the result of mbg_thread_stop() @see mbg_xhrt_poll_thread_fnc() @see mbg_xhrt_poll_thread_create() @@ -3257,10 +3503,12 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_xhrt_poll_thread_stop( MBG_POLL_THREAD_INFO *p_pti ) ; /** - Retrieve a time stamp in PCPS_HR_TIME format which is extrapolated - using the system's current cycles counter value and a time stamp - plus associated cycles counter value saved by the polling thread. + @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. @@ -3277,11 +3525,13 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_pcps_hr_time( MBG_XHRT_INFO *p, PCPS_HR_TIME *p_hrt ) ; /** - Retrieve a time stamp in FILETIME format which is extrapolated - using the system's current cycles counter value and a time stamp - plus associated cycles counter value saved by the polling thread. + @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 + + 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. @@ -3298,9 +3548,11 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_filetime( MBG_XHRT_INFO *p, FILETIME *p_ft ) ; /** - Retrieve the frequency of the system's cycles counter as determined - by the device polling thread. + @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. @@ -3316,7 +3568,9 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_xhrt_cycles_frequency( MBG_XHRT_INFO *p, MBG_PC_CYCLES_FREQUENCY *p_freq_hz ) ; /** - Retrieve the default system's cycles counter frequency from the kernel driver. + @brief Retrieve the default system's cycles counter frequency from the kernel driver. + + This API call can be used on systems which don't provide this information in user space. @param dh handle of the device to which the IOCTL call is sent. @param *p Pointer of a ::MBG_PC_CYCLES_FREQUENCY variable to be filled up. @@ -3328,7 +3582,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_default_cycles_frequency_from_dev( MBG_DEV_HANDLE dh, MBG_PC_CYCLES_FREQUENCY *p ) ; /** - Retrieve the default system's cycles counter frequency. + @brief Retrieve the system's default cycles counter frequency. @note This may not be supported on all target platforms, in which case the returned frequency is 0 and the mbg_get_default_cycles_frequency_from_dev() @@ -3397,7 +3651,7 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, // The code below depends on whether the target device is accessed via // IOCTLs to a device driver, or the hardware is accessed directly. -#if defined( _MBGIOCTL_H ) // using IOCTL to access device driver +#if defined( MBG_USE_KERNEL_DRIVER ) // using IOCTL to access device driver /** @brief Send a generic IOCTL command to the driver. diff --git a/mbglib/common/mbgerror.h b/mbglib/common/mbgerror.h index f6c41e4..bd9cb4a 100755 --- a/mbglib/common/mbgerror.h +++ b/mbglib/common/mbgerror.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgerror.h 1.5.1.1 2011/04/20 16:09:19 martin TEST $ + * $Id: mbgerror.h 1.6 2012/10/02 18:42:26 martin REL_M $ * $Name: $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany @@ -12,7 +12,10 @@ * * ----------------------------------------------------------------------- * $Log: mbgerror.h $ - * Revision 1.5.1.1 2011/04/20 16:09:19 martin + * Revision 1.6 2012/10/02 18:42:26 martin + * New codes MBG_ERR_N_POUT_EXCEEDS_SUPP and + * MBG_ERR_N_UC_MSTR_EXCEEDS_SUPP. + * Modified comments for doxygen. * Revision 1.5 2011/03/31 10:56:17 martin * Added MBG_ERR_COPY_TO_USER and MBG_ERR_COPY_FROM_USER. * Revision 1.4 2008/12/05 13:28:50 martin diff --git a/mbglib/common/mbggenio.h b/mbglib/common/mbggenio.h index dece56b..4487130 100755 --- a/mbglib/common/mbggenio.h +++ b/mbglib/common/mbggenio.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbggenio.h 1.5.1.4 2011/10/05 08:57:20 martin TEST $ + * $Id: mbggenio.h 1.6 2012/10/02 18:43:36 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,13 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: mbggenio.h $ - * Revision 1.5.1.4 2011/10/05 08:57:20 martin + * Revision 1.6 2012/10/02 18:43:36 martin * Fixed includes for NetBSD. - * Revision 1.5.1.3 2011/02/09 17:08:30 martin * Specify I/O range number when calling port I/O macros * so they can be used for different ranges under BSD. - * Revision 1.5.1.2 2011/02/01 12:12:18 martin - * Revision 1.5.1.1 2011/01/31 17:29:26 martin * Account for modified resource handling under *BSD. * Revision 1.5 2008/12/05 13:27:33 martin * Generally put macro arguments in brackets for evaluation diff --git a/mbglib/common/mbgioctl.h b/mbglib/common/mbgioctl.h index 16e1f7f..f127652 100755 --- a/mbglib/common/mbgioctl.h +++ b/mbglib/common/mbgioctl.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgioctl.h 1.24.1.12 2011/11/25 15:03:23 martin TEST $ + * $Id: mbgioctl.h 1.25 2012/10/02 18:45:55 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,26 +10,22 @@ * * ----------------------------------------------------------------------- * $Log: mbgioctl.h $ - * Revision 1.24.1.12 2011/11/25 15:03:23 martin + * 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. - * Revision 1.24.1.11 2011/11/22 15:47:27 martin * Support debug status. - * Revision 1.24.1.10 2011/07/20 15:49:00 martin * Conditionally use older IOCTL request buffer structures. - * Revision 1.24.1.9 2011/07/19 12:31:59 martin - * Relaxed required priority level for generic read functions. - * Revision 1.24.1.8 2011/07/18 10:18:49 martin - * Revision 1.24.1.7 2011/07/15 14:50:11 martin - * Revision 1.24.1.6 2011/07/14 14:54:01 martin * 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. - * Revision 1.24.1.5 2011/07/06 11:19:28 martin * Support reading CORR_INFO, and reading/writing TR_DISTANCE. - * Revision 1.24.1.4 2011/06/29 10:52:00 martin * New code IOCTL_DEV_HAS_PZF. - * Revision 1.24.1.3 2011/06/21 15:03:29 martin * 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. @@ -37,11 +33,7 @@ * Added definitions to set up a table of all known * IOCTL codes and names. * Use MBG_TGT_KERNEL instead of _KDD_. - * Fixed a typo. - * Revision 1.24.1.2 2011/03/22 11:19:46 martin * Use IOTYPE 'Z' under *BSD since this means passthrough on NetBSD. - * Revision 1.24.1.1 2011/02/15 11:21:21 daniel - * Added ioctls to support PTP unicast configuration * Revision 1.24 2009/12/15 15:34:59Z daniel * Support reading the raw IRIG data bits for firmware versions * which support this feature. @@ -238,57 +230,6 @@ // 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( 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 - - // read general driver info, device info, and status port #define IOCTL_GET_PCPS_DRVR_INFO _MBG_IOR( IOTYPE, 0x00, PCPS_DRVR_INFO ) @@ -687,7 +628,7 @@ typedef struct * Implementation should be done in a way which introduces as low * latency as possible when reading time stamps from a device. */ -enum +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 diff --git a/mbglib/common/mbgmutex.h b/mbglib/common/mbgmutex.h index 41212d1..0948c9c 100755 --- a/mbglib/common/mbgmutex.h +++ b/mbglib/common/mbgmutex.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgmutex.h 1.1.1.7 2011/10/21 14:08:30 martin TEST $ + * $Id: mbgmutex.h 1.3 2013/04/11 13:46:58 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,19 +11,13 @@ * * ----------------------------------------------------------------------- * $Log: mbgmutex.h $ - * Revision 1.1.1.7 2011/10/21 14:08:30 martin - * Changes for QNX. - * Revision 1.1.1.6 2011/05/31 14:19:55 martin - * Revision 1.1.1.5 2011/05/16 17:39:41 martin + * 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. * Don't define macros for semaphore destroy functions * if not required/supported on the target OS. - * Revision 1.1.1.4 2011/05/06 09:11:16Z martin - * Fix for DOS. - * Revision 1.1.1.3 2011/05/04 09:24:18Z martin - * Revision 1.1.1.2 2011/05/04 08:57:23 martin - * Fix for FreeBSD. - * Revision 1.1.1.1 2011/05/03 15:46:06 martin - * Fix for Linux kernel. * Revision 1.1 2011/04/15 12:26:59 martin * Initial revision. * @@ -55,8 +49,8 @@ typedef KSPIN_LOCK MBG_SPINLOCK; #define _mbg_spin_lock_init( _spl ) KeInitializeSpinLock( _spl ) // _mbg_spin_lock_destroy is not supported - #define _mbg_spin_lock_acquire( _spl ) KeAcquireSpinLockAtDpcLevel( _spl ) - #define _mbg_spin_lock_release( _spl ) KeReleaseSpinLockFromDpcLevel( _spl ) + #define _mbg_spin_lock_acquire( _spl ) KeAcquireSpinLock( _spl, &OldIrql ) + #define _mbg_spin_lock_release( _spl ) KeReleaseSpinLock( _spl, OldIrql ) #define _MBG_SPINLOCK_DEFINED 1 diff --git a/mbglib/common/mbgpccyc.h b/mbglib/common/mbgpccyc.h index 3b40c88..d94645c 100755 --- a/mbglib/common/mbgpccyc.h +++ b/mbglib/common/mbgpccyc.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgpccyc.h 1.1.1.6 2011/12/19 16:14:13 martin TEST $ + * $Id: mbgpccyc.h 1.2 2012/03/12 13:45:57 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,16 +10,11 @@ * * ----------------------------------------------------------------------- * $Log: mbgpccyc.h $ - * Revision 1.1.1.6 2011/12/19 16:14:13 martin - * Revision 1.1.1.5 2011/09/21 14:25:39 martin + * 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 * is provided for the given hardware platform. - * Revision 1.1.1.4 2011/07/20 15:58:53 martin - * Support cycles on IA64 only in kernel space. - * Revision 1.1.1.3 2011/07/13 09:44:49 martin - * Moved IA64 includes from pcpsdev.h to mbgpccyc.h. - * Revision 1.1.1.2 2011/07/06 13:23:36 martin - * Revision 1.1.1.1 2011/07/05 12:25:08 martin * Revision 1.1 2011/06/23 15:36:07 martin * Initial revision. * diff --git a/mbglib/common/mbgtime.h b/mbglib/common/mbgtime.h index 7dde395..d88bb57 100755 --- a/mbglib/common/mbgtime.h +++ b/mbglib/common/mbgtime.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgtime.h 1.17.1.7 2011/10/21 14:07:52 martin TEST $ + * $Id: mbgtime.h 1.19 2013/05/22 16:47:01 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,17 +10,11 @@ * * ----------------------------------------------------------------------- * $Log: mbgtime.h $ - * Revision 1.17.1.7 2011/10/21 14:07:52 martin - * Changes for QNX. - * Revision 1.17.1.6 2011/05/06 09:03:12 martin - * Fix for DOS. - * Revision 1.17.1.5 2011/05/06 08:07:58Z daniel - * include <time.h> for WIN32 target and firmware only - * Revision 1.17.1.4 2011/02/09 15:46:48Z martin - * Revision 1.17.1.3 2011/01/24 17:09:20 martin - * Fixed build under FreeBSD. - * Revision 1.17.1.2 2010/08/13 11:57:13 martin - * Revision 1.17.1.1 2010/08/13 11:39:20Z martin + * Revision 1.19 2013/05/22 16:47:01 martin + * Added some useful macros. + * Revision 1.18 2012/10/02 18:51:11 martin + * Include <time.h> for WIN32 target and firmware only + * Fixed build under QNX, DOS, and FreeBSD. * Revision 1.17 2010/08/06 13:03:03 martin * Removed obsolete code. * Revision 1.16 2010/07/16 10:22:07Z martin @@ -217,6 +211,28 @@ typedef struct #endif +/** + * @brief A table with the days of month + * + * First row is for standard years, second row is + * for leap years. + * + * @see DAYS_OF_MONTH_TABLE_INIT + */ +typedef char DAYS_OF_MONTH_TABLE[2][12]; + + +/** + * @brief An initializer for a ::DAYS_OF_MONTH_TABLE + */ +#define DAYS_OF_MONTH_TABLE_INIT \ +{ \ + { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }, \ + { 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 } \ +} + + + _ext TM_GPS dhms; _ext TM_GPS datum; @@ -271,12 +287,9 @@ _ext const TM_GPS init_tm ; -_ext char days_of_month[2][12] +_ext DAYS_OF_MONTH_TABLE days_of_month #ifdef _MBGTIME - = { - { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }, - { 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 } - } + = DAYS_OF_MONTH_TABLE_INIT #endif ; @@ -286,6 +299,15 @@ _ext char days_of_month[2][12] n_days( (_s)->mday, (_s)->month, (_s)->year ) +#define _is_leap_year( _y ) \ + ( ( ( ( (_y) % 4 ) == 0 ) && ( ( (_y) % 100 ) != 0 ) ) || ( ( (_y) % 400 ) == 0 ) ) + + +#define _get_days_of_month( _y, _m ) \ + days_of_month[ _is_leap_year( _y ) ][_m] + + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/mbgutil.c b/mbglib/common/mbgutil.c index 3342939..edc41b4 100755 --- a/mbglib/common/mbgutil.c +++ b/mbglib/common/mbgutil.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgutil.c 1.5.2.3 2011/11/28 14:24:44 daniel TEST $ + * $Id: mbgutil.c 1.6 2012/10/15 13:12:17 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,10 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: mbgutil.c $ - * Revision 1.5.2.3 2011/11/28 14:24:44 daniel - * Fixed firmware and asic version string - * Revision 1.5.2.2 2011/09/21 16:01:18Z martin - * Revision 1.5.2.1 2010/07/15 13:06:59 martin + * Revision 1.6 2012/10/15 13:12:17 martin + * Fixed build under DOS. + * Fixed format/type mismatch when printing UTC offset. + * Fixed generation of firmware and ASIC version string. * Revision 1.5 2009/03/19 09:09:55Z daniel * Fixed ambiguous syntax in mbg_str_dev_name(). * Support TAI and GPS time scales in mbg_str_pcps_hr_tstamp_loc(). @@ -400,7 +400,7 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_offs( char *s, int max_len, { ldiv_t ldt = ldiv( labs( pt->utc_offs ) / 60, 60 ); - n += mbg_snprintf( s + n, max_len - n, "%c%02u:%02uh", + n += mbg_snprintf( s + n, max_len - n, "%c%02lu:%02luh", ( pt->utc_offs < 0 ) ? '-' : '+', ldt.quot, ldt.rem ); } @@ -585,7 +585,7 @@ _MBG_API_ATTR int _MBG_API mbg_str_dev_name( char *s, int max_len, const char *s n = mbg_snprintf( s, max_len, "%s, S/N %s", model_code, sernum ); if ( fw_rev_num > 0 ) - n += mbg_snprintf( &s[n], max_len," (FW v%d.%02d", fw_rev_num>>8, fw_rev_num & 0x00FF ); + n += mbg_snprintf( &s[n], max_len," (FW v%X.%02X", fw_rev_num>>8, fw_rev_num & 0x00FF ); if ( asic_version_num > 0 ) { diff --git a/mbglib/common/mbgutil.h b/mbglib/common/mbgutil.h index e78f27c..8d1d748 100755 --- a/mbglib/common/mbgutil.h +++ b/mbglib/common/mbgutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgutil.h 1.16.1.2 2011/06/22 10:21:57 martin TEST $ + * $Id: mbgutil.h 1.17 2012/10/15 10:08:32 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,10 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: mbgutil.h $ - * Revision 1.16.1.2 2011/06/22 10:21:57 martin - * Cleaned up handling of pragma pack(). - * Revision 1.16.1.1 2011/02/09 15:27:23 martin + * Revision 1.17 2012/10/15 10:08:32 martin * Include stdlib.h. + * Cleaned up handling of pragma pack(). * Revision 1.16 2009/08/14 10:11:53Z daniel * New version code 306, compatibility version still 110. * Revision 1.15 2009/06/09 08:57:47Z daniel diff --git a/mbglib/common/myutil.h b/mbglib/common/myutil.h index 7e6b901..f24dafe 100755 --- a/mbglib/common/myutil.h +++ b/mbglib/common/myutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: myutil.h 1.14 2011/02/16 14:02:35 martin REL_M $ + * $Id: myutil.h 1.15 2012/10/02 18:51:52 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: myutil.h $ + * 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. * Revision 1.13 2010/12/13 15:59:39 martin @@ -66,8 +68,9 @@ /* Start of header body */ -#if defined( _USE_PACK ) // set byte alignment - #pragma pack( 1 ) +#if defined( _USE_PACK ) + #pragma pack( 1 ) // set byte alignment + #define _USING_BYTE_ALIGNMENT #endif @@ -208,8 +211,9 @@ extern "C" { #endif -#if defined( _USE_PACK ) // set default alignment - #pragma pack() +#if defined( _USING_BYTE_ALIGNMENT ) + #pragma pack() // set default alignment + #undef _USING_BYTE_ALIGNMENT #endif /* End of header body */ diff --git a/mbglib/common/ntp_shm.c b/mbglib/common/ntp_shm.c new file mode 100755 index 0000000..42d836a --- /dev/null +++ b/mbglib/common/ntp_shm.c @@ -0,0 +1,91 @@ + +/************************************************************************** + * + * $Id: ntp_shm.c 1.1 2012/05/29 09:54:15 martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * NTP shared memory support functions. + * + * ----------------------------------------------------------------------- + * $Log: ntp_shm.c $ + * Revision 1.1 2012/05/29 09:54:15 martin + * Initial revision. + * + **************************************************************************/ + +#define _NTP_SHM + #include <ntp_shm.h> +#undef _NTP_SHM + +#include <syslog.h> +#include <errno.h> +#include <string.h> + + +//##+++++++++++ +extern void mbg_log( int lvl, const char *fmt, ... ); + + +/*HDR*/ +struct shmTime *getShmTime( int unit ) +{ + struct shmTime *p; + + int shmid = shmget( (key_t) ( NTPD_BASE + unit ), + sizeof( struct shmTime ), IPC_CREAT | 0644 ); + + if ( shmid == -1 ) + { + mbg_log( LOG_ERR, "shmget %i failed: %s", unit, strerror( errno ) ); + return NULL; + } + + + p = (struct shmTime *) shmat( shmid, 0, 0 ); + + if ( (long) p == -1L ) + { + mbg_log( LOG_ERR, "shmat %i failed: %s", unit, strerror( errno ) ); + return NULL; + } + + return p; + +} // getShmTime + + + +/*HDR*/ +int ntpshm_init( struct shmTime **shmTime, int n_units ) +{ + int i; + int ret_val = 0; + + for ( i = 0; i < n_units; i++ ) + { + struct shmTime *p = getShmTime( i ); + shmTime[i] = p; + + if ( p == NULL ) + { + mbg_log( LOG_WARNING, "** Failed to initialize NTP SHM unit %i", i ); + ret_val = -1; + continue; + } + + memset( p, 0, sizeof( *p ) ); + + p->mode = 1; + p->precision = -5; /* initially 0.5 sec */ + p->nsamples = 3; /* stages of median filter */ + + mbg_log( LOG_INFO, "NTP SHM unit %i initialized successfully", i ); + } + + return ret_val; + +} // ntpshm_init + + diff --git a/mbglib/common/ntp_shm.h b/mbglib/common/ntp_shm.h new file mode 100755 index 0000000..270d71e --- /dev/null +++ b/mbglib/common/ntp_shm.h @@ -0,0 +1,127 @@ + +/************************************************************************** + * + * $Id: ntp_shm.h 1.2 2013/01/02 10:23:41 daniel REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for ntp_shm.c. + * + * ----------------------------------------------------------------------- + * $Log: ntp_shm.h $ + * Revision 1.2 2013/01/02 10:23:41 daniel + * Added nsec support. + * Revision 1.2 2013/01/02 10:23:41 daniel + * Added nsec support + * Revision 1.1 2012/05/29 09:54:15 martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _NTP_SHM_H +#define _NTP_SHM_H + + +/* Other headers to be included */ + +#include <sys/ipc.h> +#include <sys/shm.h> + + +#ifdef _NTP_SHM + #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 + +/** + * @defgroup group_ntp_defs NTP interface definitions + * + * @Note These definitions have been copied from the NTP source code (http://www.ntp.org) + * + * @{ */ + +/** @brief Structure of NTP's shared memory segment */ +struct shmTime { + int mode; /* 0 - if valid set + * use values, + * clear valid + * 1 - if valid set + * if count before and after read of + * values is equal, + * use values + * clear valid + */ + int count; + time_t clockTimeStampSec; /* external clock */ + int clockTimeStampUSec; /* external clock */ + time_t receiveTimeStampSec; /* internal clock, when external value was received */ + int receiveTimeStampUSec; /* internal clock, when external value was received */ + int leap; + int precision; + int nsamples; + int valid; + unsigned clockTimeStampNSec; /* unsigned ns timestamps */ + unsigned receiveTimeStampNSec; + int dummy[8]; +}; + +/** @brief codes used with struct shmTime::leap */ +#define LEAP_NOWARNING 0x0 /**< normal, no leap second warning */ +#define LEAP_ADDSECOND 0x1 /**< last minute of day has 61 seconds */ +#define LEAP_DELSECOND 0x2 /**< last minute of day has 59 seconds */ +#define LEAP_NOTINSYNC 0x3 /**< overload, clock is free running */ + +#define NTPD_BASE 0x4e545030 /* "NTP0" */ + +#define MAX_SHM_REFCLOCKS 4 + +/** @} group_ntp_defs */ + + + + +/* function prototypes: */ + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + struct shmTime *getShmTime( int unit ) ; + int ntpshm_init( struct shmTime **shmTime, int n_units ) ; + +/* ----- 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 /* _NTP_SHM_H */ + diff --git a/mbglib/common/parmgps.h b/mbglib/common/parmgps.h index 0b5dbf8..5ff32c8 100755 --- a/mbglib/common/parmgps.h +++ b/mbglib/common/parmgps.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: parmgps.h 1.7 2011/02/16 10:12:13 martin REL_M $ + * $Id: parmgps.h 1.8 2012/10/15 10:06:37 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: parmgps.h $ + * Revision 1.8 2012/10/15 10:06:37 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 @@ -48,8 +50,9 @@ /* Start of header body */ -#if defined( _USE_PACK ) // set byte alignment - #pragma pack( 1 ) +#if defined( _USE_PACK ) + #pragma pack( 1 ) // set byte alignment + #define _USING_BYTE_ALIGNMENT #endif @@ -125,8 +128,9 @@ _ext const char *mbg_framing_str[N_MBG_FRAMINGS] #endif -#if defined( _USE_PACK ) // set default alignment - #pragma pack() +#if defined( _USING_BYTE_ALIGNMENT ) + #pragma pack() // set default alignment + #undef _USING_BYTE_ALIGNMENT #endif /* End of header body */ diff --git a/mbglib/common/parmpcps.h b/mbglib/common/parmpcps.h index 7095d48..bc2f2bf 100755 --- a/mbglib/common/parmpcps.h +++ b/mbglib/common/parmpcps.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: parmpcps.h 1.7 2011/04/01 10:30:51 martin REL_M $ + * $Id: parmpcps.h 1.8 2012/10/15 10:05:38 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: parmpcps.h $ + * Revision 1.8 2012/10/15 10:05:38 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 @@ -49,8 +51,9 @@ /* Start of header body */ -#if defined( _USE_PACK ) // set byte alignment - #pragma pack( 1 ) +#if defined( _USE_PACK ) + #pragma pack( 1 ) // set byte alignment + #define _USING_BYTE_ALIGNMENT #endif @@ -146,8 +149,9 @@ _ext STR_TYPE_INFO default_str_type_info[DEFAULT_MAX_STR_TYPE] #endif -#if defined( _USE_PACK ) // set default alignment - #pragma pack() +#if defined( _USING_BYTE_ALIGNMENT ) + #pragma pack() // set default alignment + #undef _USING_BYTE_ALIGNMENT #endif /* End of header body */ diff --git a/mbglib/common/pci_asic.h b/mbglib/common/pci_asic.h index 66afe3e..bf104f2 100755 --- 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:12 martin REL_M $ + * $Id: pci_asic.h 1.23 2013/06/26 15:57:07 martin TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: pci_asic.h $ + * Revision 1.23 2013/06/26 15:57:07 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 @@ -280,13 +282,14 @@ enum PCI_ASIC_MAJOR_GPS180PEX, // PEX EPLD for GPS180PEX PCI_ASIC_MAJOR_TCR180PEX, // PEX EPLD for TCR180PEX PCI_ASIC_MAJOR_PZF180PEX, // PEX EPLD for PZF180PEX + PCI_ASIC_MAJOR_GLN180PEX, // PEX EPLD for GLN180PEX N_PCI_ASIC_MAJOR // the number of known codes }; /* The minor number increases when a new EPLD image is released. - At least EPLD images with the following "required minor" numbers - should be installed for proper operation. The "current minor" + At least EPLD images with the following "required minor" numbers + should be installed for proper operation. The "current minor" numbers can be used to check if a newer EPLD image is available: */ #define PCI_ASIC_CURRENT_MINOR_PEX511 0x04 @@ -333,6 +336,8 @@ enum #define PCI_ASIC_CURRENT_MINOR_PZF180PEX 0x00 #define PCI_ASIC_REQUIRED_MINOR_PZF180PEX 0x00 +#define PCI_ASIC_CURRENT_MINOR_GLN180PEX 0x00 +#define PCI_ASIC_REQUIRED_MINOR_GLN180PEX 0x00 typedef struct { @@ -353,6 +358,7 @@ typedef struct { PCPS_TYPE_GPS180PEX, PCI_ASIC_MAJOR_GPS180PEX, PCI_ASIC_CURRENT_MINOR_GPS180PEX, PCI_ASIC_REQUIRED_MINOR_GPS180PEX }, \ { PCPS_TYPE_TCR180PEX, PCI_ASIC_MAJOR_TCR180PEX, PCI_ASIC_CURRENT_MINOR_TCR180PEX, PCI_ASIC_REQUIRED_MINOR_TCR180PEX }, \ { PCPS_TYPE_PZF180PEX, PCI_ASIC_MAJOR_PZF180PEX, PCI_ASIC_CURRENT_MINOR_PZF180PEX, PCI_ASIC_REQUIRED_MINOR_PZF180PEX }, \ + { PCPS_TYPE_GLN180PEX, PCI_ASIC_MAJOR_GLN180PEX, PCI_ASIC_CURRENT_MINOR_GLN180PEX, PCI_ASIC_REQUIRED_MINOR_GLN180PEX }, \ { 0 } \ } diff --git a/mbglib/common/pcpsdefs.h b/mbglib/common/pcpsdefs.h index 46af1db..e301697 100755 --- a/mbglib/common/pcpsdefs.h +++ b/mbglib/common/pcpsdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsdefs.h 1.48 2011/11/25 15:02:28 martin TEST $ + * $Id: pcpsdefs.h 1.51 2013/06/25 09:51:39 martin TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,13 @@ * * ----------------------------------------------------------------------- * $Log: pcpsdefs.h $ + * Revision 1.51 2013/06/25 09:51:39 martin + * Support GLN180PEX. + * Revision 1.50 2013/01/30 15:59:54 martin + * Updated and fixed some doxygen comments. + * Revision 1.49 2012/10/02 18:53:02 martin + * Added structure PCPS_TIME_STATUS_X_MASKS. + * Added initializer for command names, useful for debugging. * Revision 1.48 2011/11/25 15:02:28 martin * Support on-board event logs. * Revision 1.47 2011/11/25 10:22:44 martin @@ -314,6 +321,7 @@ 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_TCR510PCI ( ( PCPS_REF_IRIG << 8 ) | 0x01 ) #define PCI_DEV_TCR167PCI ( ( PCPS_REF_IRIG << 8 ) | 0x02 ) @@ -424,7 +432,7 @@ typedef uint8_t PCPS_STATUS_PORT; /**< see @ref group_status_port "Bitmask" */ - #PCPS_SET_EVENT_TIME<br> Send a high resolution time stamp to the clock to - configure a UTC time when the clock shall generate + 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. @@ -483,7 +491,7 @@ typedef uint8_t PCPS_STATUS_PORT; /**< see @ref group_status_port "Bitmask" */ - #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 + 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. @@ -675,12 +683,14 @@ typedef uint8_t PCPS_SERIAL; typedef uint8_t PCPS_TZCODE; -/* the following codes are used with the PCPS_TZCODE parameter: */ -enum +/** + * @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_UTC, /* always %UTC */ PCPS_TZCODE_EET_EEST, /* East European Time, CET/CEST + 1h */ N_PCPS_TZCODE /* the number of valid codes */ }; @@ -730,7 +740,7 @@ typedef struct typedef struct { - int16_t offs; /**< offset from UTC to local time [min] */ + 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 */ @@ -839,6 +849,74 @@ typedef struct /** @} group_cmd_bytes */ +#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. + * + * This can e.g. be assigned to an array of MBG_CODE_NAME_TABLE_ENTRY elements + * and may be helpful when debugging. + */ +#define MBG_CMD_TABLE \ +{ \ + { 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 } \ +} + + + /* Codes returned when commands with parameters have been passed */ /* to the board */ #define PCPS_SUCCESS 0 /**< OK, no error */ @@ -920,6 +998,21 @@ typedef uint16_t PCPS_TIME_STATUS_X; /**< extended status */ #define _mbg_swab_pcps_time_status_x( _p ) _mbg_swab16( _p ) +typedef struct +{ + PCPS_TIME_STATUS_X set_mask; + PCPS_TIME_STATUS_X clr_mask; + +} PCPS_TIME_STATUS_X_MASKS; + +#define _mbg_swab_pcps_time_status_x_masks( _p ) \ +{ \ + _mbg_swab_pcps_time_status_x( &(_p)->set_mask ); \ + _mbg_swab_pcps_time_status_x( &(_p)->clr_mask ); \ +} + + + /** * The structure has been introduced to be able to read the * current time with higher resolution of fractions of seconds and @@ -937,7 +1030,7 @@ typedef uint16_t PCPS_TIME_STATUS_X; /**< extended status */ typedef struct { PCPS_TIME_STAMP tstamp; /**< High resolution time stamp (UTC) */ - int32_t utc_offs; /**< UTC offs [sec] (loc_time = UTC + utc_offs) */ + 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_HR_TIME; @@ -1059,7 +1152,7 @@ typedef struct PCPS_IRIG_TIME_s #define PCPS_DL_ANN 0x08 /**< a change in daylight saving is announced */ -#define PCPS_UTC 0x10 /**< a special UTC firmware is installed */ +#define PCPS_UTC 0x10 /**< a special %UTC firmware is installed */ #define PCPS_LS_ANN 0x20 /**< leap second announced */ /**< (requires firmware rev. REV_PCPS_LS_ANN_...) */ @@ -1313,7 +1406,7 @@ enum 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_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 }; diff --git a/mbglib/common/pcpsdev.h b/mbglib/common/pcpsdev.h index 43e5423..63cb67b 100755 --- a/mbglib/common/pcpsdev.h +++ b/mbglib/common/pcpsdev.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsdev.h 1.49.1.68 2011/11/28 10:04:39 martin TEST $ + * $Id: pcpsdev.h 1.51.1.2 2013/06/25 09:52:00 martin TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -17,118 +17,49 @@ * * ----------------------------------------------------------------------- * $Log: pcpsdev.h $ - * Revision 1.49.1.68 2011/11/28 10:04:39 martin - * PZF180PEX doesn't support TIME_SCALE by default. - * Revision 1.49.1.67 2011/11/25 15:03:23 martin + * Revision 1.51.1.2 2013/06/25 09:52:00 martin + * Support GLN180PEX. + * Revision 1.51.1.1 2013/05/08 10:56:53 martin + * Revision 1.51 2013/01/25 15:44:21 martin + * Added inline function setup_hr_time_cycles_from_timestamp_cycles() which sets + * up a PCPS_HR_TIME_CYCLES structure from PCPS_TIME_STAMP_CYCLES. + * Revision 1.50 2012/10/02 19:00:46 martin + * Support GPS180PEX, TCR180PEX, and PZF180PEX. + * Support DCF600USB, TCR600USB, MSF600USB, and WVB600USB. + * Runtime support for precise time API introduced with Windows 8. + * This does not yet for x64 builds. + * There are some g++ versions which fail to compile source code using + * the macros provided by Linux to define IOCTL codes. If only the API + * functions are called by an application then the IOCTL codes aren't + * required anyway, so we just avoid inclusion of mbgioctl.h. + * However, some IOCTL related definitions are required anyway, so + * they have been moved to this file which is always included. + * Bug fix: Use negative sign for delay in KeDelayExecutionThread() * Support on-board event logs. - * Revision 1.49.1.66 2011/11/24 14:01:45 martin - * Added kernel uptime/sleep for NetBSD. - * Revision 1.49.1.65 2011/11/24 08:54:53 martin * Moved macro _must_do_fw_workaround_20ms() here. - * Revision 1.49.1.64 2011/11/22 16:27:25 martin * New macro _pcps_has_debug_status(). - * Revision 1.49.1.63 2011/11/01 12:20:00 martin - * Revision 1.49.1.62 2011/11/01 12:14:33 martin - * Revision 1.49.1.61 2011/11/01 09:13:05 martin - * Revision 1.49.1.60 2011/10/31 08:55:05 martin - * Revision 1.49.1.59 2011/10/28 13:51:15 martin * Added some macros to test if specific stat_info stuff is supported. - * Revision 1.49.1.58 2011/10/21 14:07:27 martin - * Revision 1.49.1.57 2011/09/21 16:03:04 martin * Moved some definitions useful for configuration tools to new file cfg_hlp.h. - * Revision 1.49.1.56 2011/09/20 08:31:22 martin - * Modified default features for PZF180PEX. - * Revision 1.49.1.55 2011/09/12 12:32:38Z martin - * Revision 1.49.1.54 2011/09/12 09:45:12 martin - * Fixed a typo (missing comma). - * Revision 1.49.1.53 2011/08/05 11:02:28 martin - * Revision 1.49.1.52 2011/07/19 10:41:48 martin - * Revision 1.49.1.51 2011/07/14 13:29:14 martin - * Revision 1.49.1.50 2011/07/13 09:44:53 martin * Moved IA64 includes from pcpsdev.h to mbgpccyc.h. - * Revision 1.49.1.49 2011/07/06 13:23:24 martin - * Revision 1.49.1.48 2011/07/06 11:22:50 martin * Added macros _pcps_has_corr_info() and _pcps_has_tr_distance(). - * Revision 1.49.1.47 2011/07/05 12:25:19 martin - * Revision 1.49.1.46 2011/07/04 10:29:44 martin - * Modified a comment. - * Revision 1.49.1.45 2011/06/29 14:06:08 martin - * Added support for TCR600USB, MSF600USB, and WVB600USB. * Extended bus flag for USB v2 and macro _pcps_is_usb_v2(). * New feature ..._HAS_PZF and macro _pcps_has_pzf(). - * Revision 1.49.1.44 2011/06/29 09:10:26 martin - * Renamed PZF600PEX to PZF180PEX. - * Revision 1.49.1.43 2011/06/24 10:26:52 martin - * Fixed warning under DOS. - * Revision 1.49.1.42 2011/06/24 08:07:03Z martin * Moved PC cycles stuff to an new extra header. - * Revision 1.49.1.41 2011/06/21 15:17:36 martin - * Fixed build under DOS. - * Revision 1.49.1.40 2011/06/21 14:23:59Z martin * Cleaned up handling of pragma pack(). * Introduced generic MBG_SYS_TIME with nanosecond resolution. * Support struct timespec under Linux, if available. - * Revision 1.49.1.39 2011/06/01 09:29:09 martin - * Revision 1.49.1.38 2011/05/31 14:20:54 martin - * Revision 1.49.1.37 2011/05/16 13:18:38 martin * Use MBG_TGT_KERNEL instead of _KDD_. - * Revision 1.49.1.36 2011/05/06 13:47:38Z martin - * Support PZF600PEX. - * Revision 1.49.1.35 2011/04/19 15:06:24 martin * Added PTP unicast master configuration stuff. - * Revision 1.49.1.34 2011/03/29 14:08:45 martin * For compatibility use cpu_counter() instead of cpu_counter_serializing() under NetBSD. - * Revision 1.49.1.33 2011/03/28 09:50:18 martin - * Modifications for NetBSD from Frank Kardel. - * Revision 1.49.1.32 2011/03/25 11:09:43 martin * Optionally support timespec for sys time (USE_TIMESPEC). - * Started to support NetBSD. - * Revision 1.49.1.31 2011/02/16 10:10:49 martin - * Fixed macro syntax for _pcps_time_set_unread(). - * Revision 1.49.1.30 2011/02/15 14:24:56Z martin - * Revision 1.49.1.29 2011/02/10 13:34:21 martin - * Revision 1.49.1.28 2011/02/10 13:21:59 martin - * Revision 1.49.1.27 2011/02/10 12:26:17 martin - * Revision 1.49.1.26 2011/02/09 15:46:49 martin - * Revision 1.49.1.25 2011/02/04 14:44:44 martin - * Revision 1.49.1.24 2011/02/04 10:10:00 martin - * Revision 1.49.1.23 2011/02/02 12:34:10 martin - * Revision 1.49.1.22 2011/02/01 17:12:04 martin - * Revision 1.49.1.21 2011/01/28 13:11:11 martin - * Preliminary implementation of mbg_get_sys_time for FreeBSD traps. - * Revision 1.49.1.20 2011/01/28 10:34:37 martin + * Support FreeBSD and NetBSD. * Moved MBG_TGT_SUPP_MEM_ACC definition here. - * Revision 1.49.1.19 2011/01/26 16:39:05 martin - * Preliminarily support FreeBSD build. - * Revision 1.49.1.18 2011/01/24 17:09:51 martin - * Preliminarily fixed build under FreeBSD. - * Revision 1.49.1.17 2010/12/14 13:19:58 martin - * Fixed doxgen comments. - * Revision 1.49.1.16 2010/12/14 12:20:10 martin - * Revision 1.49.1.15 2010/11/25 14:54:22 martin * Moved status port register definitions to pcpsdefs.h. - * Revision 1.49.1.14 2010/11/11 09:15:38 martin - * Added definitions to support DCF600USB. - * Revision 1.49.1.13 2010/09/27 13:09:06 martin * Features are now defined using enum and bit masks. * Added initializer for feature names (used for debug). - * Revision 1.49.1.12 2010/08/25 12:44:42 martin - * Revision 1.49.1.11 2010/08/20 09:34:41Z martin * Added macro _pcps_features(). - * Revision 1.49.1.10 2010/08/17 15:34:23 martin - * Revision 1.49.1.9 2010/08/16 15:41:32 martin - * Revision 1.49.1.8 2010/08/13 12:14:46 daniel - * Revision 1.49.1.7 2010/08/13 11:57:54Z martin - * Revision 1.49.1.6 2010/08/13 11:39:28Z martin - * Revision 1.49.1.5 2010/08/13 11:19:41 martin * Implemented portable mbg_get_sys_uptime() and mbg_sleep_sec() * functions and associated types. - * Revision 1.49.1.4 2010/08/11 14:32:14 martin - * Revision 1.49.1.3 2010/08/11 13:47:42 martin - * Cleanup. - * Revision 1.49.1.2 2010/07/14 14:50:42 martin - * Revision 1.49.1.1 2010/06/30 13:17:18 martin - * Support GPS180PEX and TCR180PEX. * Revision 1.49 2010/06/30 13:03:48 martin * Use new preprocessor symbol MBG_ARCH_X86. * Use ulong port addresses for all platforms but x86. @@ -323,7 +254,15 @@ #include <usbdefs.h> #include <use_pack.h> -#if defined( MBG_TGT_LINUX ) +#if !defined( MBG_TGT_KERNEL ) + #include <string.h> +#endif + +#if defined( MBG_TGT_WIN32 ) + + #include <mbg_w32.h> + +#elif defined( MBG_TGT_LINUX ) #if defined( MBG_TGT_KERNEL ) #include <linux/delay.h> @@ -503,7 +442,12 @@ void mbg_get_sys_time( MBG_SYS_TIME *p ) #if defined( MBG_TGT_WIN32 ) #if defined( MBG_TGT_KERNEL ) // kernel space - KeQuerySystemTime( p ); + #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; @@ -617,6 +561,7 @@ void mbg_get_sys_uptime( MBG_SYS_UPTIME *p ) #elif defined( MBG_TGT_LINUX ) #if defined( MBG_TGT_KERNEL ) + // getrawmonotonic() can possibly be used for this in newer kernels { // Using a simple 64 bit division may result in a linker error // in kernel mode due to a missing symbol __udivdi3, so we use @@ -695,7 +640,7 @@ void mbg_sleep_sec( long sec ) // 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; + delay.QuadPart = - ((LONGLONG) sec * HNS_PER_SEC); KeDelayExecutionThread( KernelMode, FALSE, &delay ); #else // user space @@ -851,6 +796,7 @@ enum PCPS_TYPES PCPS_TYPE_TCR600USB, PCPS_TYPE_MSF600USB, PCPS_TYPE_WVB600USB, + PCPS_TYPE_GLN180PEX, N_PCPS_DEV_TYPE }; @@ -1212,6 +1158,8 @@ enum #define PCPS_FEAT_WVB600USB ( PCPS_FEAT_WWVB51USB ) +#define PCPS_FEAT_GLN180PEX ( PCPS_FEAT_GPS180PEX ) + // Some features of the API used to access Meinberg plug-in devices // have been implemented starting with the special firmware revision // numbers defined below. @@ -1686,6 +1634,82 @@ typedef uint32_t PCPS_IRQ_STAT_INFO; #undef _USING_BYTE_ALIGNMENT #endif + +// We must use native alignment here! + +// The structure below is used by the IOCTL_PCPS_GENERIC_... calls. + +#if defined( MBG_TGT_LINUX ) + #if defined( MBG_ARCH_ARM ) || defined( MBG_ARCH_SPARC ) + #define USE_IOCTL_GENERIC_REQ 0 + #endif +#endif + +#if defined( MBG_TGT_WIN32 ) + // required for 32bit/64 bit compatibility + #define USE_IOCTL_GENERIC_REQ 0 +#endif + +#if !defined( USE_IOCTL_GENERIC_REQ ) + #define USE_IOCTL_GENERIC_REQ 1 +#endif + + +#if USE_IOCTL_GENERIC_REQ + +// 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 +void setup_hr_time_cycles_from_timestamp_cycles( PCPS_HR_TIME_CYCLES *p_ht_c, + const PCPS_TIME_STAMP_CYCLES *p_ts_c ) +{ + memset( p_ht_c, 0, sizeof( *p_ht_c ) ); + + p_ht_c->t.tstamp = p_ts_c->tstamp; + p_ht_c->cycles = p_ts_c->cycles; + +} // setup_hr_time_cycles_from_timestamp_cycles + +#endif + + /* End of header body */ #undef _ext diff --git a/mbglib/common/pcpsdrvr.c b/mbglib/common/pcpsdrvr.c index cda390d..93d2a52 100755 --- a/mbglib/common/pcpsdrvr.c +++ b/mbglib/common/pcpsdrvr.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsdrvr.c 1.46.2.60 2011/12/20 11:32:16 martin TEST $ + * $Id: pcpsdrvr.c 1.50.1.1 2013/06/25 09:52:39 martin TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -63,124 +63,42 @@ * * ----------------------------------------------------------------------- * $Log: pcpsdrvr.c $ - * Revision 1.46.2.60 2011/12/20 11:32:16 martin - * Removed obsolete code. - * Revision 1.46.2.59 2011/11/25 15:13:01 martin + * Revision 1.50.1.1 2013/06/25 09:52:39 martin + * Revision 1.50 2013/03/15 10:01:58 martin + * Modified/added some debug messages. + * Revision 1.49 2013/03/15 08:35:08 martin + * Account for PTP270PEX HW v2 cards which can indicate + * when they are ready to be accessed. + * Account for unified, renamed PLX symbols. + * Revision 1.48 2012/11/05 16:32:02Z martin + * Fixed and enhanced some timing DEBUG code. + * Rewrote report_uptime(). + * Revision 1.47 2012/10/15 14:12:08 martin + * Support GPS180PEX, TCR180PEX, and PZF180PEX. + * Support DCF600USB, TCR600USB, MSF600USB, and WVB600USB. + * Support FreeBSD and NetBSD. * Support on-board event log. - * Revision 1.46.2.58 2011/11/23 17:47:33 martin - * Conditional code to test MM I/O for new PCI cards. - * Added debug messages for generic I/O. - * Revision 1.46.2.57 2011/11/18 10:15:33 martin - * Revision 1.46.2.56 2011/11/02 14:09:48 martin - * Revision 1.46.2.55 2011/11/01 09:10:59Z martin - * Revision 1.46.2.54 2011/10/21 14:07:28 martin - * Revision 1.46.2.53 2011/10/06 13:35:06 martin - * Revision 1.46.2.52 2011/10/06 13:29:13 martin - * Temp. don't delay for PTP270PEX under FreeBSD. - * Revision 1.46.2.51 2011/09/12 12:32:57 martin - * Revision 1.46.2.50 2011/09/09 08:28:57 martin - * Revision 1.46.2.49 2011/09/08 13:18:32 martin - * Always read the serial numbber directly from the device. - * Revision 1.46.2.48 2011/07/19 12:48:10 martin + * If required, wait until PTP270PEX has finished booting. + * Use USB micro frame timing conditionally only, yet disabled by default. + * Conditional debug code to test PCI access time and/or execution time + * of the low level functions. + * Always read the serial number directly from the device. * Unified low level functions and use 16 bit types for buffer sizes. - * Cleanup. - * Revision 1.46.2.47 2011/07/11 12:49:44 martin - * Revision 1.46.2.46 2011/07/11 11:00:42Z martin - * Modified some debug code. - * Revision 1.46.2.45 2011/07/05 10:44:22 martin - * Fixed build errors under Unix. - * Revision 1.46.2.44 2011/07/05 10:18:59 martin - * Fixed pcps_start_device() for USBv2 devices. - * Added warnings in case a device is not handled - * by chip setup or device feature check. - * Revision 1.46.2.43 2011/06/29 14:02:49Z martin - * Renamed PZF600PEX to PZF180PEX. - * Added support for TCR600USB, MSF600USB, and WVB600USB. - * Modified low level AMCC read functions for SPARC. - * Fixed handling of unaligned access for SPARC. - * Modified DEBUG_IO code. - * Added some debug messages. - * Updated some comments. - * Revision 1.46.2.42 2011/06/21 15:20:56 martin - * Fixed build under DOS. - * Revision 1.46.2.41 2011/06/20 16:53:34Z martin - * account for generic MBG_SYS_TIME with nanosecond resolution. - * Revision 1.46.2.40 2011/05/16 17:41:11 martin + * Added warnings in case a device is not handled by chip setup + * or device feature check. + * Modified low level AMCC read functions for SPARC to fix unaligned access. + * Added debug messages for generic I/O. * Initialize device semaphores only early at device initializition * if required, otherwise later, since early initialization can lead * to a trap e.g. under Windows. - * Revision 1.46.2.39 2011/05/06 13:47:39Z martin - * Support PZF600PEX. - * Revision 1.46.2.38 2011/04/19 15:06:56 martin - * Fixed build error on bigendian target. - * Revision 1.46.2.37 2011/04/12 15:28:56 martin + * Conditional code to test MM I/O for new PCI cards. * Use common mutex primitives from mbgmutex.h. - * Revision 1.46.2.36 2011/04/01 10:38:00 martin - * Modified mutex/spinlock initialization, and do deinitializaton. - * Fixed compiler warnings. - * Revision 1.46.2.35 2011/03/25 11:10:34 martin * Optionally support timespec for sys time (USE_TIMESPEC). - * Revision 1.46.2.34 2011/03/22 10:25:57 martin - * Modifications to support NetBSD. - * Revision 1.46.2.33 2011/03/21 16:26:03 martin - * Account for modified _pcps_kfree(). - * Revision 1.46.2.32 2011/02/16 10:14:37 martin * Set up basic default receiver info for devices which don't * support this structure. - * Revision 1.46.2.31 2011/02/15 14:24:57Z martin - * Revision 1.46.2.30 2011/02/10 09:18:07 martin - * Revision 1.46.2.29 2011/02/09 17:08:30Z martin - * Specify I/O range number when calling port I/O macros - * so they can be used for different ranges under BSD. - * Revision 1.46.2.28 2011/02/09 16:42:12 martin - * Revision 1.46.2.27 2011/02/09 15:27:49 martin - * Revision 1.46.2.26 2011/02/09 14:43:19Z martin - * Revision 1.46.2.25 2011/02/07 15:47:28 martin - * Fixed a potential trap in kernel messages. - * Revision 1.46.2.24 2011/02/04 14:44:45 martin - * Revision 1.46.2.23 2011/02/01 17:12:04 martin - * Revision 1.46.2.22 2011/02/01 15:08:34 martin - * Revision 1.46.2.21 2011/02/01 12:12:18 martin - * Revision 1.46.2.20 2011/01/31 17:30:28 martin - * Preliminary virt addr under *BSD. - * Revision 1.46.2.19 2011/01/28 10:34:06 martin * Moved MBG_TGT_SUPP_MEM_ACC definition to pcpsdev.h. - * Revision 1.46.2.18 2011/01/27 15:13:08 martin - * Added some debug messages in pcps_start_device(). - * Revision 1.46.2.17 2011/01/27 13:39:33 martin - * Revision 1.46.2.16 2011/01/27 11:01:48 martin - * Support static device list (no malloc) and use it under FreeBSD. - * Revision 1.46.2.15 2011/01/26 16:40:14 martin - * Fixed build under FreeBSD. - * Revision 1.46.2.14 2011/01/26 11:30:29 martin - * Fixed PTP270PEX boot delay. - * Revision 1.46.2.13 2011/01/07 14:00:58 daniel - * Re-enabled wait period for PTP270PEX - * Revision 1.46.2.12 2010/11/23 11:07:56Z martin - * Support memory mapped access under DOS. - * Revision 1.46.2.11 2010/11/22 14:19:27Z martin - * Support DCF600USB. - * Cleanup. - * Revision 1.46.2.10 2010/10/06 09:24:02 martin - * Revision 1.46.2.9 2010/09/27 13:09:22Z martin - * Revision 1.46.2.8 2010/09/21 13:10:15 daniel - * Check for raw IRIG data support in reciver info. - * Revision 1.46.2.7 2010/09/02 12:19:24Z martin * Introduced and use new function check_ri_feature(). * Also detect support for raw IRIG data from RECEIVER_INFO. - * Added debug code. - * Sleeping for PTP270PEX if uptime is too low needs to be fixed. - * Revision 1.46.2.6 2010/08/16 15:41:28 martin - * Revision 1.46.2.5 2010/08/13 11:56:49 martin - * Fixed build on WIN32_NON_PNP. - * Revision 1.46.2.4 2010/08/13 11:20:23Z martin - * If required, wait until PTP270PEX has finished booting. - * Revision 1.46.2.3 2010/08/11 13:41:47Z martin - * Code cleanup. - * Revision 1.46.2.2 2010/07/14 14:51:56 martin - * Use direct pointer to memory maopped timestamp. - * Revision 1.46.2.1 2010/06/30 15:02:12 martin - * Support GPS180PEX and TCR180PEX. * Revision 1.46 2009/12/15 14:45:33 daniel * Account for feature to read the raw IRIG bits. * Revision 1.45 2009/09/29 07:24:50Z martin @@ -389,6 +307,8 @@ #elif defined( MBG_TGT_WIN32 ) #include <pcps_ioc.h> #include <stdio.h> +#elif defined( MBG_TGT_DOS ) + #include <mbgplx.h> #endif #if !defined( MBG_TGT_LINUX ) && !defined( MBG_TGT_BSD ) @@ -413,26 +333,51 @@ #endif -// time required for PTP270PEX to be ready after booting -#define MAX_BOOT_TIME_PTP270PEX 27 // [s] +// In NetBSD defining DEBUG to build a debug version of this driver +// would interfere with DEBUG being defined for the kernel sources, +// so we need to define MBG_DEBUG instead. For simplicity, we define +// DEBUG locally in this module if MBG_DEBUG is defined. +#if defined( MBG_TGT_NETBSD ) && defined( MBG_DEBUG ) + #undef DEBUG + #define DEBUG MBG_DEBUG +#endif + + +#if !defined( USE_CMD_PTR ) + #define USE_CMD_PTR 1 +#endif + +#if !defined( DEBUG_ACCESS_TIMING ) + // test how much cycles it takes to read/write a register on the board + #define DEBUG_ACCESS_TIMING ( defined( DEBUG ) && ( DEBUG >= 10 ) ) +#endif +#if !defined( DEBUG_IO_TIMING ) + // test how much cycles it takes for a low level function to execute + #define DEBUG_IO_TIMING ( defined( DEBUG ) && ( DEBUG >= 10 ) ) +#endif #if !defined( DEBUG_IO ) - #if defined( MBG_TGT_NETBSD ) - #define DEBUG_IO ( defined( MBG_DEBUG ) && ( MBG_DEBUG >= DEBUG_LVL_IO ) ) - #else - #define DEBUG_IO ( defined( DEBUG ) && ( DEBUG >= DEBUG_LVL_IO ) ) - #endif + // debug which bytes are written to or read from the board + #define DEBUG_IO ( defined( DEBUG ) && ( DEBUG >= DEBUG_LVL_IO ) ) #endif #if !defined( DEBUG_PORTS ) - #define DEBUG_PORTS ( defined( DEBUG ) && ( DEBUG >= DEBUG_LVL_PORTS ) ) + #define DEBUG_PORTS ( defined( DEBUG ) && ( DEBUG >= DEBUG_LVL_PORTS ) ) #endif #if !defined( DEBUG_SERNUM ) - #define DEBUG_SERNUM ( defined( DEBUG ) && ( DEBUG >= DEBUG_LVL_SERNUM ) ) + #define DEBUG_SERNUM ( defined( DEBUG ) && ( DEBUG >= DEBUG_LVL_SERNUM ) ) #endif +#if !defined( USE_USB_MICRO_FRAMES ) + #define USE_USB_MICRO_FRAMES 0 +#endif + + +// max. time required for PTP270PEX to be ready after booting +#define MAX_BOOT_TIME_PTP270PEX 27 // [s] + extern const char pcps_driver_name[]; @@ -516,21 +461,221 @@ extern const char pcps_driver_name[]; #if defined( MBG_TGT_DOS ) || \ defined( MBG_TGT_QNX ) - #define CHECK_UPTIME 0 + #define MBG_TGT_HAS_UPTIME 0 #elif defined( MBG_TGT_FREEBSD ) // Under FreeBSD (at least 8.2) the kernel calls to read uptime always // return 1 when this driver is loaded automatically, so the system // locks up if we wait util uptime has reached a certain value. - #define CHECK_UPTIME 0 + #define MBG_TGT_HAS_UPTIME 0 #else - #define CHECK_UPTIME 1 + #define MBG_TGT_HAS_UPTIME 1 #endif +static __mbg_inline /*HDR*/ +int pcps_ddev_is_ptp270pex( const PCPS_DDEV *pddev ) +{ + return _pcps_ddev_is_pci( pddev ) && + ( _pcps_ddev_dev_id( pddev ) == PCI_DEV_PTP270PEX ); + +} // pcps_ddev_is_ptp270pex + + + + +#if defined( MBG_TGT_LINUX ) + +static /*HDR*/ +int mbg_plx_read_pecs_reg( struct pci_dev *pNode, + uint16_t reg, uint32_t *pval ) +{ + int rc; + + if ( reg & 0x03 ) + return PCI_BAD_REGISTER_NUMB; + + if ( reg < 0x1000 ) + { + rc = pci_read_config_dword( pNode, reg, pval ); + } + else + { + uint32_t mcr_idx_sav = (uint32_t) -1; + + reg -= 0x1000; + + rc = pci_read_config_dword( pNode, PLX_PECS_MAININDEX, &mcr_idx_sav ); + + if ( rc != PCI_SUCCESS ) + goto done; + + rc = pci_write_config_dword( pNode, PLX_PECS_MAININDEX, reg ); + + if ( rc != PCI_SUCCESS ) + goto done; + + rc = pci_read_config_dword( pNode, PLX_PECS_MAINDATA, pval ); + + if ( rc != PCI_SUCCESS ) + goto done; + + rc = pci_write_config_dword( pNode, PLX_PECS_MAININDEX, mcr_idx_sav ); + } + +done: + return rc; + +} // mbg_plx_read_pecs_reg + +#endif + + + +static /*HDR*/ +/** + * @brief Check if a PTP270PEX card can indicate when it's ready + * + * A PTP270PEX card must only be accessed by the driver + * after it has finished booting. Otherwise the host system + * may be locked up. + * + * On HW v2 cards the firmware can indicate when the card is + * ready to be accessed, so this can be checked by the driver. + * On these cards the on-board GPIO3 pin is hardwired to 0 + * to indicate this is supported, whereas on older v1 cards + * the GPIO3 pin is pulled up to 1. + * + * @param pddev The device to be checked + * + * @see ptp270pex_has_flagged_ready + */ +int ptp270pex_can_flag_ready( const PCPS_DDEV *pddev ) +{ + // The GPIO3 input level can only be read via a register + // which is located inside the PCI configuration space + // of the built-in PLX8111 PCIe-to-PCI bridge. + // + // So we must first locate the PCI bridge associated to our device, + // read the PECS_GPIOCTL register and return 1 if the GPIO3 bit + // has been pulled down to 0. + + uint32_t reg_val = (uint32_t) -1; + int rc = -1; + + #if defined( MBG_TGT_LINUX ) + + struct pci_dev *bridge = NULL; + + // search for any PLX PCI bridge device + while ( ( bridge = pci_get_device( PCI_VENDOR_ID_PLX, + PCI_DEVICE_ID_PLX_8111, bridge ) ) != NULL ) + { + uint8_t uc; + + #if defined( DEBUG ) + printk( KERN_INFO "%s: Found bridge: %s\n", + pcps_driver_name, pci_name( bridge ) ); + #endif + + // Read the secondary bus number. + rc = pci_read_config_byte( bridge, 0x19, &uc ); + + if ( ( rc == PCI_SUCCESS ) && ( uc == pddev->dev.cfg.bus_num ) ) + { + #if defined( DEBUG ) + printk( KERN_INFO "%s: Found bridge associated to device %s\n", + pcps_driver_name, _pcps_ddev_type_name( pddev ) ); + #endif + break; + } + } + + if ( bridge ) // associated PCI bridge has been found + { + rc = mbg_plx_read_pecs_reg( bridge, PLX_PECS_GPIOCTL, ®_val ); + + #if defined( DEBUG ) + printk( KERN_INFO "%s: Read cfg dword %04lX: %08lX, rc: %i\n", + pcps_driver_name, (ulong) PLX_PECS_GPIOCTL, (ulong) reg_val, rc ); + #endif + + // The pci_get_device() calls above has increased the use count + // for the last device which has been found, so we need to decrease + // the use count if we don't need to access the device anymore. + // This is done by calling the complementary function. + pci_dev_put( bridge ); + } + + #elif defined( MBG_TGT_WIN32 ) + + // We don't scan the PCI bus to find the associated bridge device + // but just assume the card can flag when it's ready. If the card + // actually can't then the driver just waits until the maximum + // required uptime has been reached or exceeded, so there's no danger + // that the system might lock up. + rc = 0; + reg_val = 0; + + #elif defined( MBG_TGT_DOS ) + + PLX_DEVICE_NODE dn_bridge = { 0 }; + + rc = mbg_find_plx8311_bridge( pddev->dev.cfg.bus_num, &dn_bridge ); + + if ( rc == PCI_SUCCESS ) + rc = mbg_plx_read_pecs_reg( &dn_bridge, PLX_PECS_GPIOCTL, ®_val ); + + #else + + #endif + + // The device can indicate when it's ready if reg_val + // has been read successfully, and the GPIO3 bit is 0. + return ( rc == 0 ) && ( ( reg_val & PLX_PECS_GPIOCTL_GPIO3_DATA ) == 0 ); + +} // ptp270pex_can_flag_ready + + + +static /*HDR*/ +/** + * @brief Check if a PTP270PEX card indicates it is ready + * + * A PTP270PEX card must only be accessed by the driver + * after it has finished booting. Otherwise the host system + * may be locked up. + * + * On HW v2 cards the firmware can indicate when the card is + * ready to be accessed, so the driver can call this function + * to check this. + * + * @note The function ptp270pex_can_flag_ready() should + * have been called before to check if the card actually + * supports this. + * + * @param pddev The device to be checked + * + * @see ptp270pex_can_flag_ready + */ +int ptp270pex_has_flagged_ready( const PCPS_DDEV *pddev ) +{ + // GPIO pin USERI is pulled down to 0 by the firmware + // as soon as the card is ready to be accessed. + // With PTP270PEX HW v1 cards this pin is always 1. + + // Read the LCS_CNTRL register and return 1 if the USERI + // bit is set. + + uint32_t cntrl_reg = _pcps_ddev_io_base_mapped( pddev, 1 ) + + PLX_LCS_CNTRL; + uint32_t reg_val = _mbg_inp32_to_cpu( pddev, 0, cntrl_reg ); + + return ( reg_val & PLX_LCS_CNTRL_USERI ) == 0; + +} // ptp270pex_has_flagged_ready -#if CHECK_UPTIME static /*HDR*/ long mbg_delta_sys_time_ms( const MBG_SYS_TIME *t2, const MBG_SYS_TIME *t1 ) @@ -555,50 +700,104 @@ long mbg_delta_sys_time_ms( const MBG_SYS_TIME *t2, const MBG_SYS_TIME *t1 ) +#if MBG_TGT_HAS_UPTIME + static /*HDR*/ void report_uptime( const MBG_SYS_UPTIME *p_uptime ) { - #if defined( MBG_TGT_LINUX ) - printk( KERN_INFO "%s: system uptime %llu jiffies -> %llu s, required %u s\n", - pcps_driver_name, (unsigned long long) ( get_jiffies_64() - INITIAL_JIFFIES ), - (unsigned long long) *p_uptime, MAX_BOOT_TIME_PTP270PEX ); - #elif defined( MBG_TGT_BSD ) - printf( "%s: system uptime %llu s, required %u s\n", - pcps_driver_name, (unsigned long long) *p_uptime, MAX_BOOT_TIME_PTP270PEX ); - #elif defined( MBG_TGT_WIN32 ) + #if defined( MBG_TGT_WIN32 ) + // Simplified code for Windows since Windows doesn't provide + // snprintf() or an equivalent function in kernel mode. WCHAR wcs_msg[120]; swprintf( wcs_msg, L"system uptime: %I64u s, required %u s", (int64_t) *p_uptime, MAX_BOOT_TIME_PTP270PEX ); _evt_msg( GlbDriverObject, wcs_msg ); + + #else + + char ws[120]; + int l = sizeof( ws ); + int n = 0; + + n += snprintf( &ws[n], l - n, "%s: system uptime ", pcps_driver_name ); + + #if defined( MBG_TGT_LINUX ) + n += snprintf( &ws[n], l - n, "%llu jiffies -> ", + (unsigned long long) ( get_jiffies_64() - INITIAL_JIFFIES ) ); + #endif + + n += snprintf( &ws[n], l - n, "%llu", (unsigned long long) *p_uptime ); + n += snprintf( &ws[n], l - n, " s, required %u s", MAX_BOOT_TIME_PTP270PEX ); + + if ( *p_uptime < MAX_BOOT_TIME_PTP270PEX ) + { + int waiting = (int) ( MAX_BOOT_TIME_PTP270PEX - *p_uptime ); + n += snprintf( &ws[n], l - n, ", waiting %i s", waiting ); + } + else + n += snprintf( &ws[n], l - n, ", OK." ); + + #if defined( MBG_TGT_LINUX ) + printk( KERN_INFO "%s\n", ws ); + #elif defined( MBG_TGT_BSD ) + printf( "%s\n", ws ); + #endif + #endif } // report_uptime +#endif // MBG_TGT_HAS_UPTIME + static /*HDR*/ -void check_uptime( void ) +void wait_ptp270pex_ready( const PCPS_DDEV *pddev ) { MBG_SYS_TIME t1; MBG_SYS_TIME t2; MBG_SYS_UPTIME uptime; int delayed = 0; + int can_flag_ready; int i = 0; + // A newer PTP270PEX card (HW v2.0) can indicate if it + // has finished booting and thus is ready to be accessed, + // but older PTP270PEX hardware does not support this. + can_flag_ready = ptp270pex_can_flag_ready( pddev ); + mbg_get_sys_time( &t1 ); for (;;) { mbg_get_sys_uptime( &uptime ); - #if !defined( DEBUG ) - if ( !delayed ) + #if MBG_TGT_HAS_UPTIME + #if !defined( DEBUG ) + if ( delayed ) + #endif + report_uptime( &uptime ); #endif - report_uptime( &uptime ); - if ( uptime == 0 ) - break; // assume uptime not supported + if ( can_flag_ready ) + { + if ( ptp270pex_has_flagged_ready( pddev ) ) + break; + } + else + { + // If the card is unable to indicate when it is ready + // and the target system doesn't support uptime + // then it makes no sense to keep looping and waiting, + // so just stop waiting and hope the card is ready. + if ( uptime == 0 || uptime == -1 ) + break; // assume uptime not supported + } + + // If the target system supports uptime then + // keep looping until the system uptime exceeds + // the max. boot time required by the card. if ( uptime >= MAX_BOOT_TIME_PTP270PEX ) break; @@ -607,10 +806,7 @@ void check_uptime( void ) delayed = 1; if ( ++i >= MAX_BOOT_TIME_PTP270PEX ) - { - delayed = 1; break; - } } if ( delayed ) @@ -637,9 +833,7 @@ void check_uptime( void ) #endif } -} // check_uptime - -#endif +} // wait_ptp270pex_ready @@ -709,7 +903,11 @@ int map_sys_virtual_address( PCPS_DDEV *pddev ) #endif // target specific code if ( pddev->mm_addr == NULL ) + { + _mbgddmsg_2( MBG_DBG_ERR, "%s: %s Failed to map virtual address", + pcps_driver_name, _pcps_ddev_type_name( pddev ) ); return -1; + } if ( _pcps_ddev_is_pci_mbgpex( pddev ) ) pddev->mm_tstamp_addr = &pddev->mm_addr->mbgpex.tstamp; @@ -751,7 +949,11 @@ void unmap_sys_virtual_address( PCPS_DDEV *pddev ) -#if defined( DEBUG ) && defined( MBG_TGT_LINUX ) +#if ( DEBUG_ACCESS_TIMING || DEBUG_IO_TIMING ) + +#define DEBUG_PRINT_ACCESS_TIMES ( 1 && defined( MBG_ARCH_X86 ) ) + +#if DEBUG_PRINT_ACCESS_TIMES #if 0 //##++++ static inline @@ -765,14 +967,107 @@ long _cyc_to_us( long long cyc ) #endif static inline -long _cyc_to_ns( long long cyc ) +long long _cyc_to_ps( long long cyc ) { - cyc *= 1000000; + cyc *= 1000000000; do_div( cyc, cpu_khz ); - return (long) cyc; + return cyc; } +#endif // DEBUG_PRINT_ACCESS_TIMES + +#endif // ( DEBUG_ACCESS_TIMING || DEBUG_IO_TIMING ) + + + +#if DEBUG_ACCESS_TIMING + +uint32_t dummy; + +static +void report_access_timing( const PCPS_DDEV *pddev, const char *info, + MBG_PC_CYCLES t_after_cmd, MBG_PC_CYCLES t_after_reread ) +{ + #if defined( MBG_TGT_LINUX ) + long long delta_cyc_write = t_after_cmd - pddev->acc_cycles; + long long delta_cyc_read = t_after_reread - t_after_cmd; + + #if DEBUG_PRINT_ACCESS_TIMES + long long delta_t_write = _cyc_to_ps( delta_cyc_write ); + long long delta_t_read = _cyc_to_ps( delta_cyc_read ); + #endif + + printk( KERN_INFO "%s %s: %lli/%lli cyc" + #if DEBUG_PRINT_ACCESS_TIMES + ", %lli/%lli ps @ %lu kHz" + #endif + "\n", + _pcps_ddev_type_name( pddev ), info, + delta_cyc_write, delta_cyc_read + #if DEBUG_PRINT_ACCESS_TIMES + , delta_t_write, delta_t_read, (ulong) cpu_khz + #endif + ); + #endif + +} // report_access_timing + +#endif + + +#if DEBUG_IO_TIMING + +static +void report_io_timing( const PCPS_DDEV *pddev, const char *info, + uint8_t cmd, uint16_t count, MBG_PC_CYCLES t_after_cmd, + MBG_PC_CYCLES t_after_busy, MBG_PC_CYCLES t_done ) +{ + #if defined( MBG_TGT_LINUX ) + long long cmd_cycles = t_after_cmd - pddev->acc_cycles; + long long busy_cycles = t_after_busy - t_after_cmd; + long long read_cycles = t_done - t_after_busy; + long long cycles_per_read = 0; + + #if DEBUG_PRINT_ACCESS_TIMES + long long cmd_time = _cyc_to_ps( cmd_cycles ); + long long busy_time = _cyc_to_ps( busy_cycles ); + long long read_time = _cyc_to_ps( read_cycles ); + long long time_per_read = 0; + #endif + + if ( count ) + { + cycles_per_read = read_cycles; + do_div( cycles_per_read, count ); + + #if DEBUG_PRINT_ACCESS_TIMES + time_per_read = read_time; + do_div( time_per_read, count ); + #endif + } + + printk( KERN_INFO "%s %s cmd: 0x%02X (%u bytes), " + "write %lli cyc, busy: %lli cyc, read: %lli/%lli cyc" + #if DEBUG_PRINT_ACCESS_TIMES + ",\n write %lli ps, busy: %lli ps, read: %lli/%lli ps @ %lu kHz" + #endif + "\n", + _pcps_ddev_type_name( pddev ), info, cmd, count, + cmd_cycles, busy_cycles, read_cycles, cycles_per_read + #if DEBUG_PRINT_ACCESS_TIMES + , cmd_time, busy_time, read_time, time_per_read, (ulong) cpu_khz + #endif + ); + #endif + + printk( KERN_ERR "cycles after cmd: %lli, after busy: %lli, when done: %lli\n", + (long long) t_after_cmd, + (long long) t_after_busy, + (long long) t_done ); + +} // report_io_timing + #endif @@ -1069,6 +1364,7 @@ static /*HDR*/ /* PCPS_READ_FNC */ short pcps_read_asic( PCPS_DDEV *pddev, uint8_t cmd, void FAR *buffer, uint16_t count ) { + short ret_val = MBG_SUCCESS; uint8_t FAR *p = (uint8_t FAR *) buffer; PCPS_IO_ADDR_MAPPED data_port; PCI_ASIC_REG ar; @@ -1076,18 +1372,42 @@ short pcps_read_asic( PCPS_DDEV *pddev, uint8_t cmd, int dt_quot; int dt_rem; _pcps_irq_flags + #if DEBUG_ACCESS_TIMING || DEBUG_IO_TIMING + MBG_PC_CYCLES t_after_cmd = 0; + #endif + #if DEBUG_ACCESS_TIMING + MBG_PC_CYCLES t_after_reread = 0; + #endif + + #if DEBUG_IO_TIMING + MBG_PC_CYCLES t_after_busy = 0; + MBG_PC_CYCLES t_done = 0; + #endif #if DEBUG_IO - _mbgddmsg_3( MBG_DBG_INIT_DEV, "pcps_read_asic: cmd: 0x%02X (0x%08X), cnt: %u", + _mbgddmsg_3( MBG_DBG_INIT_DEV, "pcps_read_asic: cmd: 0x%02X (0x%08X), cnt: %u", cmd, _cpu_to_mbg32( cmd ), count ); #endif _pcps_disb_local_irq_save(); + + // get current cycles and write the command byte mbg_get_pc_cycles( &pddev->acc_cycles ); - // write the command byte _mbg_outp32( pddev, 0, _pcps_ddev_io_base_mapped( pddev, 0 ) + offsetof( PCI_ASIC, pci_data ), cmd ); + + #if DEBUG_ACCESS_TIMING || DEBUG_IO_TIMING + mbg_get_pc_cycles( &t_after_cmd ); + #endif + + #if DEBUG_ACCESS_TIMING + dummy = _mbg_inp32_to_cpu( pddev, 0, _pcps_ddev_io_base_mapped( pddev, 0 ) + + offsetof( PCI_ASIC, addon_data ) ); + mbg_get_pc_cycles( &t_after_reread ); + #endif + + _pcps_local_irq_restore(); data_port = _pcps_ddev_io_base_mapped( pddev, 0 ) @@ -1097,9 +1417,19 @@ short pcps_read_asic( PCPS_DDEV *pddev, uint8_t cmd, // wait until BUSY flag goes low or timeout if ( pcps_wait_busy( pddev ) < 0 ) - return MBG_ERR_TIMEOUT; + { + #if DEBUG_IO_TIMING + mbg_get_pc_cycles( &t_after_busy ); + #endif + ret_val = MBG_ERR_TIMEOUT; + goto done; + } + #if DEBUG_IO_TIMING + mbg_get_pc_cycles( &t_after_busy ); + #endif + // no timeout: read bytes from the board's FIFO // first read full 32 bit words @@ -1129,7 +1459,17 @@ short pcps_read_asic( PCPS_DDEV *pddev, uint8_t cmd, } } - return MBG_SUCCESS; +done: + #if DEBUG_IO_TIMING + mbg_get_pc_cycles( &t_done ); + report_io_timing( pddev, "ASIC", cmd, count, t_after_cmd, t_after_busy, t_done ); + #endif + + #if DEBUG_ACCESS_TIMING + report_access_timing( pddev, "ASIC wr/rd", t_after_cmd, t_after_reread ); + #endif + + return ret_val; } // pcps_read_asic @@ -1152,14 +1492,20 @@ short pcps_read_asic_mm( PCPS_DDEV *pddev, uint8_t cmd, int dt_quot; int dt_rem; _pcps_irq_flags - #if defined( DEBUG ) && defined( MBG_TGT_LINUX ) + + #if DEBUG_ACCESS_TIMING || DEBUG_IO_TIMING MBG_PC_CYCLES t_after_cmd = 0; + #endif + + #if DEBUG_ACCESS_TIMING + MBG_PC_CYCLES t_after_reread = 0; + #endif + + #if DEBUG_IO_TIMING MBG_PC_CYCLES t_after_busy = 0; MBG_PC_CYCLES t_done = 0; - volatile uint32_t *p_cmd_reg; #endif - #if DEBUG_IO _mbgddmsg_3( MBG_DBG_INIT_DEV, "pcps_read_asic_mm: cmd: 0x%02X (0x%08X), cnt: %u", cmd, _cpu_to_mbg32( cmd ), count ); @@ -1167,20 +1513,27 @@ short pcps_read_asic_mm( PCPS_DDEV *pddev, uint8_t cmd, _pcps_disb_local_irq_save(); - // write the command byte - #if defined( DEBUG ) && defined( MBG_TGT_LINUX ) - p_cmd_reg = &pddev->mm_addr->mbgpex.asic.pci_data.ul; + // get current cycles and write the command byte + #if USE_CMD_PTR + { + volatile uint32_t *p_cmd_reg = &pddev->mm_addr->mbgpex.asic.pci_data.ul; mbg_get_pc_cycles( &pddev->acc_cycles ); *p_cmd_reg = cmd; + } #else mbg_get_pc_cycles( &pddev->acc_cycles ); pddev->mm_addr->mbgpex.asic.pci_data.ul = cmd; #endif - #if defined( DEBUG ) && defined( MBG_TGT_LINUX ) + #if DEBUG_ACCESS_TIMING || DEBUG_IO_TIMING mbg_get_pc_cycles( &t_after_cmd ); #endif + #if DEBUG_ACCESS_TIMING + dummy = pddev->mm_addr->mbgpex.asic.pci_data.ul; + mbg_get_pc_cycles( &t_after_reread ); + #endif + _pcps_local_irq_restore(); p_data_reg = &pddev->mm_addr->mbgpex.asic.addon_data.ul[0]; @@ -1190,12 +1543,15 @@ short pcps_read_asic_mm( PCPS_DDEV *pddev, uint8_t cmd, // wait until BUSY flag goes low or timeout if ( pcps_wait_busy( pddev ) < 0 ) { + #if DEBUG_IO_TIMING + mbg_get_pc_cycles( &t_after_busy ); + #endif ret_val = MBG_ERR_TIMEOUT; goto done; } - #if defined( DEBUG ) && defined( MBG_TGT_LINUX ) + #if DEBUG_IO_TIMING mbg_get_pc_cycles( &t_after_busy ); #endif @@ -1228,21 +1584,13 @@ short pcps_read_asic_mm( PCPS_DDEV *pddev, uint8_t cmd, } done: - #if defined( DEBUG ) && defined( MBG_TGT_LINUX ) - { - long read_time; + #if DEBUG_IO_TIMING mbg_get_pc_cycles( &t_done ); + report_io_timing( pddev, "ASIC MM", cmd, count, t_after_cmd, t_after_busy, t_done ); + #endif - read_time = _cyc_to_ns( t_done - t_after_busy ); - - printk( KERN_ERR "mm cmd: 0x%02X (%u), write %li ns, busy: %li ns, read: %li/%li ns\n", - cmd, count, - _cyc_to_ns( t_after_cmd - pddev->acc_cycles ), - _cyc_to_ns( t_after_busy - t_after_cmd ), - read_time, - count ? ( read_time / count ) : 0 - ); - } + #if DEBUG_ACCESS_TIMING + report_access_timing( pddev, "ASIC MM wr/rd", t_after_cmd, t_after_reread ); #endif return ret_val; @@ -1273,8 +1621,14 @@ short pcps_read_usb( PCPS_DDEV *pddev, uint8_t cmd, if ( ( rc == MBG_SUCCESS ) && ( count && buffer ) ) { #if defined( MBG_TGT_WIN32_PNP ) - int temp_fn1 = frame_number_1; - int temp_fn2 = frame_number_2; + #if USE_USB_MICRO_FRAMES + int temp_fn1 = micro_frame_number_1 ? micro_frame_number_1 : frame_number_1; + int temp_fn2 = micro_frame_number_2 ? micro_frame_number_2 : frame_number_2; + #else + int temp_fn1 = frame_number_1; + int temp_fn2 = frame_number_2; + #endif + LARGE_INTEGER UsbPreCount = Count1; LARGE_INTEGER UsbPostCount = Count2; #endif @@ -1282,6 +1636,7 @@ short pcps_read_usb( PCPS_DDEV *pddev, uint8_t cmd, rc = _pcps_usb_read( pddev, buffer, count ); #if defined( MBG_TGT_WIN32_PNP ) + if ( cmd == PCPS_GIVE_HR_TIME && rc == PCPS_SUCCESS ) { ULONGLONG usb_latency_cycles; @@ -1290,6 +1645,7 @@ short pcps_read_usb( PCPS_DDEV *pddev, uint8_t cmd, ULONGLONG frame_length_cycles; int FrameNumberDiff; + #if !USE_USB_MICRO_FRAMES if ( pddev->usb_20_mode ) { // USB 2.0 microframe timing. @@ -1298,6 +1654,7 @@ short pcps_read_usb( PCPS_DDEV *pddev, uint8_t cmd, usb_latency_cycles = ( (ULONGLONG) PerfFreq.QuadPart ) / 20000UL; // represents 50 us } else + #endif { // USB 1.1 mode with millisecond timing. // Compensate latency to millisecond frame boundaries. @@ -1308,7 +1665,15 @@ short pcps_read_usb( PCPS_DDEV *pddev, uint8_t cmd, FrameNumberDiff = temp_fn2 - temp_fn1; cycles_diff = (ULONGLONG) ( UsbPostCount.QuadPart - UsbPreCount.QuadPart ); - frame_length_cycles = (ULONGLONG) ( (ULONGLONG) PerfFreq.QuadPart ) / 1000UL; + + #if USE_USB_MICRO_FRAMES + if ( micro_frame_number_1 > 0 || micro_frame_number_2 > 0 ) + frame_length_cycles = (ULONGLONG) ( (ULONGLONG) PerfFreq.QuadPart ) / 8000UL; + else + frame_length_cycles = (ULONGLONG) ( (ULONGLONG) PerfFreq.QuadPart ) / 1000UL; + #else + frame_length_cycles = (ULONGLONG) ( (ULONGLONG) PerfFreq.QuadPart ) / 1000UL; + #endif if ( ( temp_fn1 == 0 ) && ( temp_fn2 == 0 ) ) { @@ -1680,9 +2045,9 @@ short pcps_read_gps_block( PCPS_DDEV *pddev, return rc; #if defined( MBG_ARCH_BIG_ENDIAN ) - // Swap n_bytes regardless of whether we have actuall read 1 or 2 bytes. - // If we have read only 1 byte then the other one is 0. - n_bytes = _mbg16_to_cpu( n_bytes ); + // Swap n_bytes regardless of whether we have actually read 1 or 2 bytes. + // If we have read only 1 byte then the other one is 0 anyway. + n_bytes = _mbg16_to_cpu( n_bytes ); #endif #if DEBUG_IO @@ -2913,7 +3278,7 @@ int pcps_start_device( PCPS_DDEV *pddev, if ( map_sys_virtual_address( pddev ) < 0 ) goto fail_with_cleanup; - #if 1 && DEBUG_IO && defined( MBG_TGT_LINUX ) //##+++++++++++++++ + #if DEBUG_IO && defined( MBG_TGT_LINUX ) printk( KERN_ERR "io_addr: 0x%llX, cmd: 0x%llX\n", (unsigned long long) _pcps_ddev_io_base_mapped( pddev, 0 ), (unsigned long long) _pcps_ddev_io_base_mapped( pddev, 0 ) + offsetof( PCI_ASIC, pci_data ) @@ -2968,12 +3333,12 @@ int pcps_start_device( PCPS_DDEV *pddev, // Attention: the interrupt control/status register is located in // the PLX configuration space which is addressed by a different // port address range than the normal data ports !! - pddev->irq_enb_disb_port = _pcps_ddev_io_base_mapped( pddev, 1 ) + PLX8311_REG_INTCSR; - pddev->irq_enb_mask = PLX8311_INT_ENB; - pddev->irq_disb_mask = PLX8311_INT_ENB; + pddev->irq_enb_disb_port = _pcps_ddev_io_base_mapped( pddev, 1 ) + PLX_LCS_INTCSR; + pddev->irq_enb_mask = PLX_LCS_INTCSR_INT_ENB; + pddev->irq_disb_mask = PLX_LCS_INTCSR_INT_ENB; - pddev->irq_flag_port = _pcps_ddev_io_base_mapped( pddev, 1 ) + PLX8311_REG_INTCSR; - pddev->irq_flag_mask = PLX8311_INT_FLAG; + pddev->irq_flag_port = _pcps_ddev_io_base_mapped( pddev, 1 ) + PLX_LCS_INTCSR; + pddev->irq_flag_mask = PLX_LCS_INTCSR_INT_FLAG; pddev->irq_ack_port = _pcps_ddev_io_base_mapped( pddev, 0 ) + offsetof( PCI_ASIC, control_status ); pddev->irq_ack_mask = PCI_ASIC_PCI_IRQF; @@ -3094,12 +3459,10 @@ chip_setup_done: } #endif - #if CHECK_UPTIME - // Make sure a PTP270PEX card has finished booting. - if ( _pcps_ddev_is_pci( pddev ) && ( _pcps_ddev_dev_id( pddev ) == PCI_DEV_PTP270PEX ) ) - check_uptime(); - #endif - + // A PTP270PEX card must have finished booting + // before it can be accessed. + if ( pcps_ddev_is_ptp270pex( pddev ) ) + wait_ptp270pex_ready( pddev ); // try to read firmware ID rc = pcps_get_fw_id( pddev, pddev->dev.cfg.fw_id ); @@ -3358,6 +3721,10 @@ chip_setup_done: pddev->dev.cfg.features = PCPS_FEAT_WVB600USB; break; + case PCPS_TYPE_GLN180PEX: + pddev->dev.cfg.features = PCPS_FEAT_GLN180PEX; + break; + default: #if defined( MBG_TGT_LINUX ) printk( KERN_WARNING "%s: no feature detection for device %s\n", @@ -3492,6 +3859,10 @@ check: _mbg_swab_asic_features( &pddev->asic_features ); + _mbgddmsg_3( MBG_DBG_INIT_DEV, "%s v%03X asic_features: 0x%08lX", + _pcps_ddev_type_name( pddev ), _pcps_ddev_fw_rev_num( pddev ), + (ulong) pddev->asic_features ); + #if MBG_TGT_SUPP_MEM_ACC if ( pddev->asic_features & PCI_ASIC_HAS_MM_IO ) pddev->dev.cfg.features |= PCPS_HAS_FAST_HR_TSTAMP; diff --git a/mbglib/common/pcpsdrvr.h b/mbglib/common/pcpsdrvr.h index c2b5ee4..90a5ee7 100755 --- a/mbglib/common/pcpsdrvr.h +++ b/mbglib/common/pcpsdrvr.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsdrvr.h 1.41.1.41 2011/12/20 13:58:43 martin TEST $ + * $Id: pcpsdrvr.h 1.44.1.1 2013/06/25 09:53:16 martin TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,80 +10,26 @@ * * ----------------------------------------------------------------------- * $Log: pcpsdrvr.h $ - * Revision 1.41.1.41 2011/12/20 13:58:43 martin - * Revision 1.41.1.40 2011/12/20 11:31:42Z martin + * Revision 1.44.1.1 2013/06/25 09:53:16 martin + * Revision 1.44 2013/03/15 10:01:09 martin + * Optionally override setting to support memory mapped I/O. + * Revision 1.43 2012/11/02 09:48:04 martin + * Removed obsolete include. + * Revision 1.42 2012/10/02 19:09:20 martin * Conditionally support memory mapped access for MBGPEX cards. - * Revision 1.41.1.39 2011/11/25 15:03:24 martin * Support on-board event logs. - * Revision 1.41.1.38 2011/11/22 16:27:47 martin * New macro _pcps_ddev_has_debug_status(). - * Revision 1.41.1.37 2011/10/28 13:51:15 martin * Added some macros to test if specific stat_info stuff is supported. - * Revision 1.41.1.36 2011/10/21 14:07:29 martin - * Revision 1.41.1.35 2011/09/09 12:47:13 martin - * Fixes for DOS. - * Revision 1.41.1.34 2011/07/19 12:48:39Z martin * Updated function prototypes. - * Code cleanup. - * Revision 1.41.1.33 2011/07/06 11:23:09 martin * Added macros _pcps_ddev_has_corr_info() and _pcps_ddev_has_tr_distance(). - * Revision 1.41.1.32 2011/07/04 10:29:44 martin - * Modified a comment. - * Revision 1.41.1.31 2011/06/29 14:01:32 martin - * Renamed PZF600PEX to PZF180PEX. - * Added support for TCR600USB, MSF600USB, and WVB600USB. + * Support GPS180PEX, TCR180PEX, and PZF180PEX. + * Support DCF600USB, TCR600USB, MSF600USB, and WVB600USB. * New macros _pcps_ddev_is_usb_v2() and _pcps_ddev_has_pcf(). - * Updated some comments. - * Revision 1.41.1.30 2011/06/29 09:10:27 martin - * Renamed PZF600PEX to PZF180PEX. - * Revision 1.41.1.29 2011/05/31 14:24:18 martin - * Revision 1.41.1.28 2011/05/16 16:39:20 martin - * Allocate non-paged memory under Windows. - * Revision 1.41.1.27 2011/05/06 13:47:40Z martin - * Support PZF600PEX. - * Revision 1.41.1.26 2011/04/12 15:50:57 martin - * Revision 1.41.1.25 2011/04/12 15:26:10Z martin - * Moved mutex definitions to new mbgmutex.h. - * Revision 1.41.1.24 2011/04/01 13:32:45 martin - * Added missing mutex destroy for Windows. - * Revision 1.41.1.23 2011/04/01 10:38:42Z martin - * Support mutex/spinlock destroy. - * Revision 1.41.1.22 2011/03/31 10:35:57 martin - * Fixed a typo. - * Revision 1.41.1.21 2011/03/28 09:53:52Z martin - * Modifications for NetBSD from Frank Kardel. - * Revision 1.41.1.20 2011/03/25 11:11:44 martin * Optionally support timespec for sys time (USE_TIMESPEC). - * Started to support NetBSD. - * Revision 1.41.1.19 2011/02/15 14:24:58 martin - * Revision 1.41.1.18 2011/02/09 17:08:31 martin + * Support FreeBSD and NetBSD. * Specify I/O range number when calling port I/O macros * so they can be used for different ranges under BSD. - * Revision 1.41.1.17 2011/02/04 14:44:46 martin - * Revision 1.41.1.16 2011/02/04 10:10:18 martin - * Revision 1.41.1.15 2011/02/02 12:20:42 martin - * Revision 1.41.1.14 2011/02/01 17:12:05 martin - * Revision 1.41.1.13 2011/02/01 14:49:43 martin - * Revision 1.41.1.12 2011/02/01 12:12:19 martin - * Revision 1.41.1.11 2011/01/31 17:30:02 martin - * Modified resource storage for *BSD. - * Revision 1.41.1.10 2011/01/27 13:39:01 martin - * Revision 1.41.1.9 2011/01/27 11:04:45 martin - * Revision 1.41.1.8 2011/01/27 11:01:49 martin - * Support static device list (no malloc) and use it under FreeBSD. - * Revision 1.41.1.7 2011/01/26 16:42:07 martin - * Fixed build under FreeBSD. - * Revision 1.41.1.6 2011/01/25 09:47:27 martin - * Fixed build under FreeBSD. - * Revision 1.41.1.5 2010/11/23 11:07:57 martin - * Support memory mapped access under DOS. - * Revision 1.41.1.4 2010/11/11 09:15:39Z martin - * Added definitions to support DCF600USB. - * Revision 1.41.1.3 2010/08/20 09:35:12 martin * Added macro _pcps_ddev_features(). - * Revision 1.41.1.2 2010/07/14 14:52:12 martin - * Revision 1.41.1.1 2010/06/30 15:01:52 martin - * Support GPS180PEX and TCR180PEX. * Revision 1.41 2010/06/30 13:44:49 martin * Use new preprocessor symbol MBG_ARCH_X86. * Revision 1.40 2010/01/12 14:05:05 daniel @@ -422,7 +368,7 @@ #include <mbggenio.h> #if defined( MBG_TGT_FREEBSD ) - #include <mbg_bsd.h> +// #include <mbg_bsd.h> #include <sys/malloc.h> #include <sys/_null.h> #include <sys/param.h> @@ -498,7 +444,9 @@ extern "C" { #endif -#define _PCPS_USE_MM_IO ( 1 && MBG_TGT_SUPP_MEM_ACC && !MBG_USE_MM_IO_FOR_PCI ) +#if !defined( _PCPS_USE_MM_IO ) + #define _PCPS_USE_MM_IO ( MBG_TGT_SUPP_MEM_ACC && !MBG_USE_MM_IO_FOR_PCI ) +#endif #if _PCPS_USE_MM_IO @@ -1020,7 +968,8 @@ _ext PCPS_DEV_TYPE pcps_dev_type[N_PCPS_DEV_TYPE] { PCPS_TYPE_PZF180PEX, "PZF180PEX", PCI_DEV_PZF180PEX, PCPS_REF_DCF, PCPS_BUS_PCI_MBGPEX }, { PCPS_TYPE_TCR600USB, "TCR600USB", USB_DEV_TCR600USB, PCPS_REF_IRIG, PCPS_BUS_USB_V2 }, { PCPS_TYPE_MSF600USB, "MSF600USB", USB_DEV_MSF600USB, PCPS_REF_MSF, PCPS_BUS_USB_V2 }, - { PCPS_TYPE_WVB600USB, "WVB600USB", USB_DEV_WVB600USB, PCPS_REF_WWVB, PCPS_BUS_USB_V2 } + { PCPS_TYPE_WVB600USB, "WVB600USB", USB_DEV_WVB600USB, PCPS_REF_WWVB, PCPS_BUS_USB_V2 }, + { PCPS_TYPE_GLN180PEX, "GLN180PEX", PCI_DEV_GLN180PEX, PCPS_REF_GPS, PCPS_BUS_PCI_MBGPEX } // If a new device is added here, don't forget to add it also // to the Windows .inf file of supported PCI an USB devices, @@ -1031,7 +980,7 @@ _ext PCPS_DEV_TYPE pcps_dev_type[N_PCPS_DEV_TYPE] #if !defined( PCPS_MAX_DDEVS ) - #define PCPS_MAX_DDEVS 4 + #define PCPS_MAX_DDEVS 16 #endif #if !defined( PCPS_MAX_ISA_CARDS ) @@ -1045,7 +994,7 @@ _ext int pcps_isa_ports[PCPS_MAX_ISA_CARDS + 1]; _ext int n_ddevs; #endif -#if defined( MBG_TGT_DOS ) || defined( MBG_TGT_NETWARE ) //##++ +#if defined( MBG_TGT_DOS ) || defined( MBG_TGT_NETWARE ) //##++ _ext int curr_ddev_num; _ext PCPS_DDEV *curr_ddev #ifdef _DO_INIT @@ -1069,6 +1018,7 @@ _ext const char *fw_id_ref[] "WWVB", // WWVB51USB, WVB600USB "DCF", // DCF600USB "PZF", // PZF180PEX + "GLN", // GLN180PEX NULL } #endif diff --git a/mbglib/common/pcpsirq.h b/mbglib/common/pcpsirq.h index 7b4f137..8156f87 100755 --- a/mbglib/common/pcpsirq.h +++ b/mbglib/common/pcpsirq.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsirq.h 1.7.1.3 2011/12/20 13:46:07 martin TEST $ + * $Id: pcpsirq.h 1.8 2012/10/15 09:50:44 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,6 +11,8 @@ * * ----------------------------------------------------------------------- * $Log: pcpsirq.h $ + * Revision 1.8 2012/10/15 09:50:44 martin + * Account for modified low level macros. * Revision 1.7.1.3 2011/12/20 13:46:07 martin * Conditionally support memory mapped access for MBGPEX cards. * Revision 1.7.1.2 2011/06/29 11:03:28 martin diff --git a/mbglib/common/pcpslstr.c b/mbglib/common/pcpslstr.c index 944cee0..e71e0d8 100755 --- a/mbglib/common/pcpslstr.c +++ b/mbglib/common/pcpslstr.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpslstr.c 1.22.1.4 2011/02/07 10:34:59 martin TEST $ + * $Id: pcpslstr.c 1.23 2012/10/15 13:09:35 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,13 +11,11 @@ * * ----------------------------------------------------------------------- * $Log: pcpslstr.c $ - * Revision 1.22.1.4 2011/02/07 10:34:59 martin + * Revision 1.23 2012/10/15 13:09:35 martin + * Added function sprint_utc_offs(). + * Cleaned up get_tz_name(). * Fixed potential compiler warning for sprintf(). - * Revision 1.22.1.3 2011/01/28 09:34:20 martin * Fixed build under FreeBSD. - * Revision 1.22.1.2 2010/11/05 12:55:10 martin - * Revision 1.22.1.1 2010/07/15 12:39:34 martin - * Added function sprint_utc_offs(). * Revision 1.22 2010/06/25 13:57:57Z daniel * Account for time zone offsets with minutes other than 0. * Revision 1.21 2009/03/19 08:06:58Z daniel diff --git a/mbglib/common/pcpslstr.h b/mbglib/common/pcpslstr.h index 2993aa0..637d587 100755 --- a/mbglib/common/pcpslstr.h +++ b/mbglib/common/pcpslstr.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpslstr.h 1.27.1.6 2011/10/04 10:41:39 martin REL_M $ + * $Id: pcpslstr.h 1.28 2012/10/15 13:01:23 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,18 +10,14 @@ * * ----------------------------------------------------------------------- * $Log: pcpslstr.h $ - * Revision 1.27.1.6 2011/10/04 10:41:39 martin - * Made all declarations extern C. + * Revision 1.28 2012/10/15 13:01:23 martin * Include cfg_hlp.h. - * Added DEFAULT_OPT_NAME_TR_DISTANCE. - * Revision 1.27.1.5 2011/02/16 09:34:23Z martin + * Made all declarations extern C. * Added menu titles for PTP and PTP Unicast configuration. - * Revision 1.27.1.4 2011/02/09 14:43:42Z martin - * Revision 1.27.1.3 2011/01/28 09:34:38 martin - * Fixed build under FreeBSD. - * Revision 1.27.1.2 2010/11/22 15:23:06 martin + * Added DEFAULT_OPT_NAME_TR_DISTANCE. + * Support time slots mode for programmable pulse outputs. * Added strings for programmable output synthesizer mode. - * Revision 1.27.1.1 2010/07/15 13:02:16 martin + * Fixed build under FreeBSD. * Also use ANSI umlauts under QNX. * Updated function prototypes. * Revision 1.27 2010/06/28 08:28:17Z stefan @@ -815,6 +811,7 @@ typedef struct #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_TIME_SLOTS "Zeitschlitze pro Minute" #define DEFAULT_GER_POUT_NAMES \ { \ @@ -833,7 +830,8 @@ typedef struct GER_POUT_NAME_TIMESTR, \ GER_POUT_NAME_10MHZ, \ GER_POUT_NAME_DCF77_M59, \ - GER_POUT_NAME_SYNTH \ + GER_POUT_NAME_SYNTH, \ + GER_POUT_NAME_TIME_SLOTS \ } /* @@ -856,6 +854,7 @@ typedef struct #define GER_POUT_HINT_10MHZ "Feste Ausgangsfrequenz 10 MHz" #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 DEFAULT_GER_POUT_HINTS \ { \ @@ -874,7 +873,8 @@ typedef struct GER_POUT_HINT_TIMESTR, \ GER_POUT_HINT_10MHZ, \ GER_POUT_HINT_DCF77_M59, \ - GER_POUT_HINT_SYNTH \ + GER_POUT_HINT_SYNTH, \ + GER_POUT_HINT_TIME_SLOTS \ } diff --git a/mbglib/common/pcpsutil.c b/mbglib/common/pcpsutil.c index d2813d2..d5fe621 100755 --- a/mbglib/common/pcpsutil.c +++ b/mbglib/common/pcpsutil.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsutil.c 1.14 2011/06/29 11:03:44 martin TEST $ + * $Id: pcpsutil.c 1.14 2011/06/29 11:03:44 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * diff --git a/mbglib/common/pcpsutil.h b/mbglib/common/pcpsutil.h index e5cab81..7bb0c28 100755 --- a/mbglib/common/pcpsutil.h +++ b/mbglib/common/pcpsutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsutil.h 1.14 2009/03/09 13:39:45 martin REL_M $ + * $Id: pcpsutil.h 1.16 2013/03/04 15:51:02 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: pcpsutil.h $ + * Revision 1.16 2013/03/04 15:51:02 martin + * Added dfrac_sec_from_bin(). + * Revision 1.15 2012/10/15 09:41:32 martin + * Cleaned up handling of pragma pack(). * Revision 1.14 2009/03/09 13:39:45 martin * Made pcps_exp_year() an inline function. * Revision 1.13 2008/12/10 19:59:48 martin @@ -63,8 +67,9 @@ /* Start of header body */ -#if defined( _USE_PACK ) // set byte alignment - #pragma pack( 1 ) +#if defined( _USE_PACK ) + #pragma pack( 1 ) // set byte alignment + #define _USING_BYTE_ALIGNMENT #endif @@ -171,8 +176,18 @@ uint32_t frac_sec_from_bin( uint32_t b, uint32_t scale ) -#if defined( _USE_PACK ) // set default alignment - #pragma pack() +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 + #undef _USING_BYTE_ALIGNMENT #endif /* End of header body */ diff --git a/mbglib/common/plxdefs.h b/mbglib/common/plxdefs.h index ba1ce53..0a71015 100755 --- a/mbglib/common/plxdefs.h +++ b/mbglib/common/plxdefs.h @@ -1,16 +1,34 @@ /************************************************************************** * - * $Id: plxdefs.h 1.2 2010/01/28 15:46:31 martin REL_M $ + * $Id: plxdefs.h 1.4 2013/03/15 10:24:09 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * * Description: - * Definitions to be used with PLX PCIexpress interface chips. + * Definitions to be used with PLX PCI Express interface chips. + * Some Meinberg cards use the PLX8311 chip in endpoint mode. + * + * The PLX8311 chip is combined of a PLX8111 PCIe-to-PCI bridge + * plus a PCI-to-Local bus interface combined in a single package. + * Thus each card using a PLX8311 implements an additional internal + * PCI bus with a single device connected to this bus. + * + * Each of these devices are individually visible from the PC's + * PCI bus and thus provide their own configuration spaces, + * configuration EEPROM, etc. + * + * Care must be taken not to confuse the registers of the PLX8311 + * with the correspondent registers of the built-in PLX8111 bridge. * * ----------------------------------------------------------------------- * $Log: plxdefs.h $ - * Revision 1.2 2010/01/28 15:46:31 martin + * Revision 1.4 2013/03/15 10:24:09 martin + * Renamed register and bit mask definitions to match the names in the data sheet. + * Added doxygen comments. + * Revision 1.3 2012/10/15 09:21:42Z martin + * Added some mailbox register addresses. + * Revision 1.2 2010/01/28 15:46:31Z martin * Added PLX8311_REG_CTRL. * Revision 1.1 2007/06/08 07:46:56Z martin * Initial revision. @@ -20,7 +38,6 @@ #ifndef _PLXDEFS_H #define _PLXDEFS_H - /* Other headers to be included */ @@ -33,19 +50,109 @@ /* Start of header body */ -// The following PLX8311 operation registers can -// be accessed via port I/O or memory mapped: -#define PLX8311_REG_INTCSR 0x68 + +/** + * PCI device ID of the PCI bridge also built into the PLX8311 + */ +#define PCI_DEVICE_ID_PLX_8111 0x8111 + + +/** + * @brief PLX PCI Express Configuration Space (PECS) registers + * + * These registers are located in the PCI configuration space + * and can be accessed using standard PCI configuration register + * access functions. + * + * In addition the PECS registers are mirrored into the 64k + * memory space addressed via PCI base register 0, and thus + * can be accessed using memory reads or writes via the PCI bus. + * + * The default values of these registers can be overwritten + * by the PCI Express interface serial EEPROM. + * + * Care must be taken not to confuse the registers of the PLX8311 + * with the correspondent registers of the built-in PLX8111. + * Similarly the serial EEPROM for the PLX8311 must not be confused + * with the serial EEPROM for the built-in PEX8111 PCI bridge. + * + * Address Offset: + * 0000h - 0FFFh PCI compatible configuration registers + * 1000h - 1FFFh Main configuration registers + * 2000h - 2FFFh Memory mapped indirect access (PLX8311 only, see manual) + * 8000h - 9FFFh 8k internal shared memory + * + * See chapter 19 of the PLX8311 manual. + */ +enum PLX_PECS_REGS +{ + PLX_PECS_PCICAPPTR = 0x34, ///< PCI capabilities pointer + // PLX_PECS_LINKSTAT = 0x72, ///< Link status + PLX_PECS_MAININDEX = 0x84, ///< Main Control Register index + PLX_PECS_MAINDATA = 0x88, ///< Main Control Register data + + PLX_PECS_EECTL = 0x1004, ///< Serial EEPROM control + PLX_PECS_EECLKFREQ = 0x1008, ///< Serial EEPROM clock frequency control + PLX_PECS_GPIOCTL = 0x1020, ///< General Purpose I/O control + PLX_PECS_GPIOSTAT = 0x1024, ///< General Purpose I/O status + PLX_PECS_TLPCFG0 = 0x1048, ///< TLP controller configuration 0 + + N_PLX_PECS_REGS // dummy +}; + + +// Bit masks used with the PLX_PECS_EECTL register. +// See chap 18.10 of the manual +#define PLX_PECS_EECTL_WRITE_DATA_SHIFT 0 +#define PLX_PECS_EECTL_READ_DATA_SHIFT 8 +#define PLX_PECS_EECTL_WRITE_START ( 1UL << 16 ) +#define PLX_PECS_EECTL_READ_START ( 1UL << 17 ) +#define PLX_PECS_EECTL_CS_ENB ( 1UL << 18 ) +#define PLX_PECS_EECTL_BUSY ( 1UL << 19 ) +#define PLX_PECS_EECTL_VALID ( 1UL << 20 ) +#define PLX_PECS_EECTL_PRESENT ( 1UL << 21 ) +#define PLX_PECS_EECTL_CS_ACTIVE ( 1UL << 22 ) +#define PLX_PECS_EECTL_RELOAD ( 1UL << 31 ) + +// Bit masks used with the PLX_PECS_EECLKFREQ register. +#define PLX_PECS_EECLKFREQ_8_3_MHZ 0x02 // 3 LSBs + +// Bit masks used with the PLX_PECS_GPIOCTL register. +#define PLX_PECS_GPIOCTL_GPIO3_DATA ( 1UL << 3 ) + + + +/** + * @brief Local Configuration Space (LCS) registers + * + * These registers are accessed with different addresses from + * local or PCI, and these addresses are to be used from PCI. + * See chapter 20 of the PLX8311 manual. + */ +enum PLX_LCS_REGS_PCI +{ + PLX_LCS_INTCSR = 0x68, ///< Interrupt control / status + PLX_LCS_CNTRL = 0x6C, ///< 0xEC from local + + N_PLX_LCS_REGS_PCI // dummy +}; + + +// Bit masks used with the PLX_LCS_CNTRL register. +#define PLX_LCS_CNTRL_USERO ( 1UL << 16 ) +#define PLX_LCS_CNTRL_USERI ( 1UL << 17 ) + // The following bits must be set in the INTCSR register // to let the local microcontroller be able to generate // interrupts on the PCI bus via the chip's LINTi# line: -#define PLX8311_INT_ENB ( (1UL << 11) | (1UL << 8) ) +#define PLX_LCS_INTCSR_INT_ENB ( ( 1UL << 11 ) /* Local Interrupt Input Enable */ \ + | ( 1UL << 8 ) /* Internal PCI Wire Interrupt Enable */ \ + ) // The bit below signals if an LINTi# interrupt is active: -#define PLX8311_INT_FLAG (1UL << 15) +#define PLX_LCS_INTCSR_INT_FLAG ( 1UL << 15 ) /* Local Interrupt Input Active */ -#define PLX8311_REG_CNTRL 0x6C /* End of header body */ diff --git a/mbglib/common/rsrc.h b/mbglib/common/rsrc.h index 744e443..0ea2d0d 100755 --- a/mbglib/common/rsrc.h +++ b/mbglib/common/rsrc.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: rsrc.h 1.4.1.1 2006/09/19 14:52:02 martin TEST $ + * $Id: rsrc.h 1.5 2012/10/12 11:25:14 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,8 +11,8 @@ * * ----------------------------------------------------------------------- * $Log: rsrc.h $ - * Revision 1.4.1.1 2006/09/19 14:52:02 martin - * Preliminary support for *BSD. + * Revision 1.5 2012/10/12 11:25:14 martin + * Support *BSD. * Revision 1.4 2001/02/28 15:45:11 MARTIN * Modified preprocessor syntax. * Revision 1.3 2001/02/05 10:22:24 MARTIN diff --git a/mbglib/common/toolutil.c b/mbglib/common/toolutil.c index 55d7ae7..9c9b2f2 100755 --- a/mbglib/common/toolutil.c +++ b/mbglib/common/toolutil.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: toolutil.c 1.3.2.12 2011/11/03 08:54:08 martin TEST $ + * $Id: toolutil.c 1.4.1.4 2013/02/05 15:27:30 martin TEST martin $ * * Description: * Common functions which can be used with Meinberg command line @@ -9,25 +9,20 @@ * * ----------------------------------------------------------------------- * $Log: toolutil.c $ - * Revision 1.3.2.12 2011/11/03 08:54:08 martin - * Revision 1.3.2.11 2011/10/31 08:48:52 martin - * Revision 1.3.2.10 2011/10/05 15:08:28 martin + * Revision 1.4.1.4 2013/02/05 15:27:30 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.4 2012/10/15 09:33:48 martin + * Use common way to handle version information. + * Open device with O_RDWR flag. + * Fixed printing delta timestamps. + * Added function to print PCPS_TIME. * Added function to show PZF correlation. - * Revision 1.3.2.9 2011/09/29 16:31:53 martin - * New function mbg_print_hr_time() which optionally prints hex status. - * Revision 1.3.2.8 2011/09/20 16:14:13 martin - * Revision 1.3.2.7 2011/09/07 15:05:04 martin - * Let th display functions for HR timestamps optionally show + * Added function mbg_print_hr_time() which optionally prints hex status. + * Let the display functions for HR timestamps optionally show * the raw (hex) timestamps. - * Revision 1.3.2.6 2011/07/08 11:39:00 martin - * Revision 1.3.2.5 2011/07/06 07:55:32 martin - * Revision 1.3.2.4 2011/07/05 15:35:56 martin - * Modified version handling. - * Revision 1.3.2.3 2011/07/05 14:36:47 martin - * New way to maintain version information. - * Revision 1.3.2.2 2011/06/27 13:02:11 martin - * Open device with O_RDWR flag. - * Revision 1.3.2.1 2010/11/05 12:56:02 martin * Revision 1.3 2009/06/19 12:12:14 martin * Added function mbg_print_hr_timestamp(). * Revision 1.2 2009/02/18 09:15:55 martin @@ -52,6 +47,19 @@ #include <string.h> +static __mbg_inline +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; + +} // 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 ) @@ -61,7 +69,7 @@ int mbg_program_info_str( char *s, size_t max_len, const char *pname, if ( last_year == 0 ) last_year = MBG_CURRENT_COPYRIGHT_YEAR; - n = snprintf( s, max_len, "%s v%i.%i.%i Copyright Meinberg ", pname, + n = snprintf( s, max_len, "%s v%i.%i.%i copyright Meinberg ", pname, MBG_MAJOR_VERSION_CODE, MBG_MINOR_VERSION_CODE, micro_version ); if ( first_year != last_year ) @@ -104,16 +112,6 @@ void mbg_print_usage_intro( const char *pname, const char *info ) /*HDR*/ -void mbg_print_help_options( void ) -{ - puts( "where opt is one of the options:" ); - mbg_print_opt_info( "-? or -h", "print this usage information" ); - -} // mbg_print_help_options - - - -/*HDR*/ void mbg_print_opt_info( const char *opt_name, const char *opt_info ) { if ( opt_name == NULL ) @@ -129,6 +127,16 @@ void mbg_print_opt_info( const char *opt_name, const char *opt_info ) /*HDR*/ +void mbg_print_help_options( void ) +{ + puts( "where opt is one of the options:" ); + mbg_print_opt_info( "-? or -h", "print this usage information" ); + +} // mbg_print_help_options + + + +/*HDR*/ void mbg_print_device_options( void ) { puts( "\nwhere dev is the name of a device, e.g.:\n" @@ -172,7 +180,7 @@ int mbg_ioctl_err( int rc, const char *descr ) /*HDR*/ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_dev ) { - unsigned long long port; + unsigned long port; int irq_num; int ret_val = 0; int rc; @@ -219,12 +227,12 @@ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_ port = _pcps_port_base( p_dev, 0 ); if ( port ) - printf( " at port 0x%03LX", port ); + printf( " at port 0x%03lX", port ); port = _pcps_port_base( p_dev, 1 ); if ( port ) - printf( "/0x%03LX", port ); + printf( "/0x%03lX", port ); irq_num = _pcps_irq_num( p_dev ); @@ -315,7 +323,12 @@ int mbg_check_devices( int argc, char *argv[], int optind, int (*fnc)( MBG_DEV_H // shall be displayed. const char *fn = ( num_devices > 1 ) ? argv[i] : NULL; - dh = open( argv[i], O_RDWR ); + #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 ) @@ -330,6 +343,26 @@ int mbg_check_devices( int argc, char *argv[], int optind, int (*fnc)( MBG_DEV_H /*HDR*/ +int mbg_snprint_date_time( char *s, int len_s, const PCPS_TIME *p, int verbose ) +{ + int 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 + ); + + if ( verbose ) + n += snprintf( s + n, len_s - n, " (UTC%+ih), st: %02Xh", + p->offs_utc, p->status ); + + return n; + +} // mbg_snprint_date_time + + + +/*HDR*/ int mbg_snprint_hr_tstamp( char *s, int len_s, const PCPS_TIME_STAMP *p, int show_raw ) { int n = 0; @@ -427,15 +460,7 @@ void mbg_print_hr_timestamp( PCPS_TIME_STAMP *p_ts, int32_t hns_latency, PCPS_TI printf( "HR time %s", ws ); if ( p_prv_ts ) - { - // print the difference between the current and the previous time stamp - 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 - double delta_t = (double) ( ts - prv_ts ) * 1E6 / PCPS_HRT_BIN_FRAC_SCALE; - printf( " (%+.1f us)", delta_t ); - } + printf( " (%+.1f us)", delta_timestamps( p_ts, p_prv_ts ) ); if ( !no_latency ) printf( ", latency: %.1f us", ( (double) hns_latency ) / 10 ); @@ -456,15 +481,7 @@ void mbg_print_hr_time( PCPS_HR_TIME *p_ht, int32_t hns_latency, PCPS_TIME_STAMP printf( "HR time %s", ws ); if ( p_prv_ts ) - { - // print the difference between the current and the previous time stamp - uint64_t ts = pcps_time_stamp_to_uint64( &p_ht->tstamp ); - 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 - double delta_t = (double) ( ts - prv_ts ) * 1E6 / PCPS_HRT_BIN_FRAC_SCALE; - printf( " (%+.1f us)", delta_t ); - } + printf( " (%+.1f us)", delta_timestamps( &p_ht->tstamp, p_prv_ts ) ); if ( !no_latency ) printf( ", latency: %.1f us", ( (double) hns_latency ) / 10 ); @@ -510,3 +527,4 @@ int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int show_c } // mbg_show_pzf_corr_info + diff --git a/mbglib/common/toolutil.h b/mbglib/common/toolutil.h index d47cca2..3657fda 100755 --- a/mbglib/common/toolutil.h +++ b/mbglib/common/toolutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: toolutil.h 1.2.1.5 2011/10/05 15:10:08 martin TEST $ + * $Id: toolutil.h 1.3.1.1 2013/02/05 14:38:26 martin TEST $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,16 +10,12 @@ * * ----------------------------------------------------------------------- * $Log: toolutil.h $ - * Revision 1.2.1.5 2011/10/05 15:10:08 martin + * Revision 1.3.1.1 2013/02/05 14:38:26 martin + * Started to support Windows target. + * Revision 1.3 2012/10/15 09:36:22 martin + * Use common way to handle version information. + * Added string table with PZF state names. * Updated function prototypes. - * Revision 1.2.1.4 2011/09/29 16:30:58 martin - * Updated function prototypes. - * Revision 1.2.1.3 2011/09/07 15:03:36 martin - * Updated function prototypes. - * Revision 1.2.1.2 2011/07/05 15:35:56 martin - * Modified version handling. - * Revision 1.2.1.1 2011/07/05 14:36:42 martin - * New way to maintain version information. * Revision 1.2 2009/06/19 12:11:35 martin * Updated function prototypes. * Revision 1.1 2008/12/17 10:45:14 martin @@ -38,6 +34,25 @@ #include <mbgdevio.h> #include <mbgversion.h> +#if defined( MBG_TGT_UNIX) + + #include <unistd.h> + +#elif defined( MBG_TGT_WIN32 ) + + #include <io.h> + #include <fcntl.h> + #include <sys/types.h> + #include <sys/stat.h> + #include <wingetopt.h> + + #define open _open + #define snprintf _snprintf + #define sleep( _x ) Sleep( (_x) * 1000 ) + #define usleep( _x ) Sleep( (_x) / 1000 ) + +#endif + #ifdef _TOOLUTIL @@ -54,6 +69,16 @@ extern "C" { #endif +#if !defined( MBG_EXP_YEAR_LIMIT ) + #define MBG_EXP_YEAR_LIMIT 1980 +#endif + +_ext uint16_t mbg_exp_year_limit +#ifdef _DO_INIT + = MBG_EXP_YEAR_LIMIT +#endif +; + _ext int must_print_usage; _ext const char *pzf_corr_state_name[N_PZF_CORR_STATE] @@ -71,14 +96,15 @@ _ext const char *pzf_corr_state_name[N_PZF_CORR_STATE] 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 ) ; void mbg_print_usage_intro( const char *pname, const char *info ) ; - void mbg_print_help_options( void ) ; void mbg_print_opt_info( const char *opt_name, const char *opt_info ) ; + void mbg_print_help_options( void ) ; void mbg_print_device_options( void ) ; void mbg_print_default_usage( const char *pname, const char *prog_info ) ; int mbg_ioctl_err( int rc, const char *descr ) ; 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 ) ; 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 ) ; diff --git a/mbglib/common/usbdefs.h b/mbglib/common/usbdefs.h index e900bbb..5bc12e8 100755 --- a/mbglib/common/usbdefs.h +++ b/mbglib/common/usbdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: usbdefs.h 1.15 2011/10/11 06:21:04 andre REL_M $ + * $Id: usbdefs.h 1.19 2013/06/04 10:45:53 daniel TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,15 @@ * * ----------------------------------------------------------------------- * $Log: usbdefs.h $ - * Revision 1.15 2011/10/11 06:21:04 andre + * Revision 1.19 2013/06/04 10:45:53 daniel + * Added class codes and device IDs for IMS devices MRI and BPE + * Revision 1.18 2013/01/24 11:29:21 joerg + * Added class code and device ID for LNE-GB + * Revision 1.17 2012/08/08 07:53:29Z daniel + * Added class code and device ID for LIU + * Revision 1.16 2012/02/13 09:29:59 paul + * added class code for LNO180 + * Revision 1.15 2011/10/11 06:21:04Z andre * added class code for GPS180 * Revision 1.14 2011/10/07 10:13:25Z daniel * New class code and device id for CPE @@ -78,9 +86,14 @@ enum MBG_USB_CLASS_WWVB, // WWVB Radio Clock MBG_USB_CLASS_SCU, // Meinberg Signal Changeover Unit MBG_USB_CLASS_ESI, // External Synchronization Interface - MBG_USB_CLASS_FCU, // Fan Control Unit + MBG_USB_CLASS_FCU, // Fan Control Unit MBG_USB_CLASS_CPE, // Configurable Port Expander MBG_USB_CLASS_GPS, // GPS Receiver + MBG_USB_CLASS_LNO, // Low Phase Noise Option + MBG_USB_CLASS_LIU, // Line Interface Unit + MBG_USB_CLASS_LNE, // LNE-GB + MBG_USB_CLASS_MRI, // MRS Input card for IMS + MBG_USB_CLASS_BPE, // IMS Backplane Port Expander N_MBG_USB_CLASS // number of known device class codes }; @@ -116,9 +129,17 @@ enum #define USB_DEV_CPE_01 ( ( MBG_USB_CLASS_CPE << 8 ) | 0x01 ) -#define USB_DEV_GPS180 ( ( MBG_USB_CLASS_GPS << 8 ) | 0x01 ) +#define USB_DEV_GPS180 ( ( MBG_USB_CLASS_GPS << 8 ) | 0x01 ) +#define USB_DEV_LNO180_01 ( ( MBG_USB_CLASS_LNO << 8 ) | 0x01 ) +#define USB_DEV_LIU_01 ( ( MBG_USB_CLASS_LIU << 8 ) | 0x01 ) + +#define USB_DEV_LNE_01 ( ( MBG_USB_CLASS_LNE << 8 ) | 0x01 ) + +#define USB_DEV_MRI_01 ( ( MBG_USB_CLASS_MRI << 8 ) | 0x01 ) + +#define USB_DEV_BPE_01 ( ( MBG_USB_CLASS_BPE << 8 ) | 0x01 ) enum { diff --git a/mbglib/common/use_pack.h b/mbglib/common/use_pack.h index aaacd42..5edcdfe 100755 --- a/mbglib/common/use_pack.h +++ b/mbglib/common/use_pack.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: use_pack.h 1.3 2011/01/26 10:01:41 martin REL_M $ + * $Id: use_pack.h 1.5 2012/10/12 12:40:01 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,6 +11,10 @@ * * ----------------------------------------------------------------------- * $Log: use_pack.h $ + * Revision 1.5 2012/10/12 12:40:01 martin + * Removed temporary changes. + * Revision 1.4 2012/10/02 18:06:25 martin + * Temporary changes to test alignment under Linux/Sparc. * Revision 1.3 2011/01/26 10:01:41 martin * Provided a way to suppress packing of structures on a project base. * Revision 1.2 2002/02/25 08:50:33 Andre diff --git a/mbglib/common/words.h b/mbglib/common/words.h index 5aa10e5..0331508 100755 --- a/mbglib/common/words.h +++ b/mbglib/common/words.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: words.h 1.27 2011/07/18 10:21:38 martin REL_M $ + * $Id: words.h 1.31 2012/11/29 11:54:39 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,19 @@ * * ----------------------------------------------------------------------- * $Log: words.h $ - * Revision 1.27 2011/07/18 10:21:38 martin + * Revision 1.31 2012/11/29 11:54:39 martin + * Removed #if sizeof() definitions which may cause build errors + * with some older compilers. + * Include stdbool.h for __ARMCC_VERSION targets. + * Moved _nop_macro_fnc() definition here. + * Revision 1.30 2012/11/02 09:12:29Z martin + * Moved most feature detection code to mbg_tgt.h. + * Tried to define missing features most flexibly and portably. + * Revision 1.29 2012/07/11 16:45:45Z martin + * New macros to access individual bytes of long constants. + * Revision 1.28 2012/04/05 14:36:18Z martin + * Support CVI 2010 compiler which provides C99 types. + * Revision 1.27 2011/07/18 10:21:38Z martin * Added definition for MBG_CODE_NAME_TABLE_ENTRY which can * be used to define tables assigning strings to numeric codes. * Revision 1.26 2011/04/06 10:23:03 martin @@ -85,23 +97,32 @@ #if !defined( _IS_MBG_FIRMWARE ) -#if defined( _C166 ) || \ - defined( _CC51 ) || \ - defined( __ARM ) || \ - defined( __ARMCC_VERSION ) - #define _IS_MBG_FIRMWARE 1 -#else - #define _IS_MBG_FIRMWARE 0 -#endif - + #if defined( _C166 ) || \ + defined( _CC51 ) || \ + defined( __ARM ) || \ + defined( __ARMCC_VERSION ) + #define _IS_MBG_FIRMWARE 1 + #else + #define _IS_MBG_FIRMWARE 0 + #endif #endif + #if !_IS_MBG_FIRMWARE #include <mbg_tgt.h> +#else + #if defined( __ARMCC_VERSION ) // Keil RealView Compiler for ARM + #include <stdint.h> + #include <stdbool.h> + #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 + #else + #define MBG_TGT_MISSING_64_BIT_TYPES 1 + #endif #endif + #ifdef _WORDS #define _ext #else @@ -111,117 +132,60 @@ /* Start of header body */ - -// The compilers below support native bit types. - -#if defined( _C166 ) || defined( _CC51 ) - #define _BIT_DEFINED 1 +#if defined( _C166 ) \ + || defined( _CC51 ) + #define _BIT_DEFINED 1 // these compilers natively support the "bit" type + #define USE_LONG_FOR_INT32 1 #endif -// Check whether the target system supports C99 fixed-size types. +#if !defined( MBG_TGT_HAS_EXACT_SIZE_TYPES ) -#if defined( MBG_TGT_LINUX ) // any Linux target - - #if defined( __KERNEL__ ) - #include <linux/types.h> - #else - #include <stdint.h> - #include <sys/types.h> - #endif + #if defined( MBG_TGT_HAS_INT_8_16_32 ) - #define _C99_BIT_TYPES_DEFINED 1 + // Define C99 exact size types using non-standard exact-size types + typedef __int8 int8_t; + typedef unsigned __int8 uint8_t; -#elif defined( MBG_TGT_BSD ) + typedef __int16 int16_t; + typedef unsigned __int16 uint16_t; - #include <sys/types.h> - - #define _C99_BIT_TYPES_DEFINED 1 - - // avoid inclusion of stdbool.h later - #define bit int - #define _BIT_DEFINED 1 - -#elif defined( MBG_TGT_QNX ) // QNX 4.x or QNX 6.x - - #if defined( MBG_TGT_QNX_NTO ) // QNX 6.x (Neutrino) with gcc - #include <stdint.h> - #else // QNX 4.x with Watcom C 10.6 - #include <sys/types.h> // 64 bit types not supported - #endif - - #define _C99_BIT_TYPES_DEFINED 1 - -#endif + typedef __int32 int32_t; + typedef unsigned __int32 uint32_t; + #else + // Assume a 16 or 32 bit compiler which doesn't + // support exact-size types. -// If it's not yet clear whether fixed-size types are supported, -// check the build environment which may be multi-platform. + typedef char int8_t; + typedef unsigned char uint8_t; -#if !defined( _C99_BIT_TYPES_DEFINED ) + typedef short int16_t; + typedef unsigned short uint16_t; - #if defined( __WATCOMC__ ) - #if __WATCOMC__ > 1230 // Open Watcom C 1.3 and above - #include <stdint.h> - #define _C99_BIT_TYPES_DEFINED 1 - #elif defined( __WATCOM_INT64__ ) // Watcom C 11, non-QNX - typedef __int64 int64_t; - typedef unsigned __int64 uint64_t; + // Using #if sizeof() to determine the size of a type may not + // be supported by all preprocessors, and may even result in + // build errors if used in a conditional preprocessor section, + // so we can't use this here without compatibility problems. - #define _C99_BIT_TYPES_DEFINED 1 + #if defined( USE_LONG_FOR_INT32 ) + typedef long int32_t; + typedef unsigned long uint32_t; + #elif defined( USE_INT_FOR_INT32 ) + typedef int int32_t; + typedef unsigned int uint32_t; + #else + #error Need to define int32_t and uint32_t #endif - #endif - - #if defined( __BORLANDC__ ) - #if ( __BORLANDC__ >= 0x570 ) // at least Borland Developer Studio 2006 - #define _C99_BIT_TYPES_DEFINED 1 - #endif - #endif - #if defined( __GNUC__ ) - #include <stdint.h> - #define _C99_BIT_TYPES_DEFINED 1 - #endif - - #if defined( __ARMCC_VERSION ) // Keil RealView Compiler for ARM - #include <stdint.h> - #define _C99_BIT_TYPES_DEFINED 1 #endif -#endif - - -// If neither the target system nor the build environment define C99 fixed-size -// types define those types based on standard types with the proper sizes -// commonly used in 16/32 bit environments. - -#if defined( _C99_BIT_TYPES_DEFINED ) - - #define MBG_TGT_HAS_64BIT_TYPES 1 - -#else - - typedef char int8_t; - typedef unsigned char uint8_t; + #if defined( MBG_TGT_MISSING_64_BIT_TYPES ) - typedef short int16_t; - typedef unsigned short uint16_t; - - typedef long int32_t; - typedef unsigned long uint32_t; - - - #if defined( MBG_TGT_WIN32 ) - - typedef __int64 int64_t; - typedef unsigned __int64 uint64_t; - - #define MBG_TGT_HAS_64BIT_TYPES 1 - - #else - // The types below are required to avoid build errors + // The build environment does not support 64 bit types. However, + // 64 bit types need to be defined to avoid build errors // if these types are formally used in function prototypes. // We explicitely use abnormal data types to hopefully // cause compiler errors in case these types are @@ -229,16 +193,29 @@ // platform which does not support 64 bit types. typedef void *int64_t; typedef void *uint64_t; + + #else + + // Define C99 types using non-standard exact-size types + // which are usually supported by build envonronments + // supporting 64 bit types but no C99 types. + typedef __int64 int64_t; + typedef unsigned __int64 uint64_t; + #endif #endif -#if !defined( MBG_TGT_HAS_64BIT_TYPES ) +#if defined( MBG_TGT_MISSING_64_BIT_TYPES ) #define MBG_TGT_HAS_64BIT_TYPES 0 +#else + + #define MBG_TGT_HAS_64BIT_TYPES 1 + #endif @@ -247,7 +224,9 @@ typedef unsigned char uchar; -#if !defined( MBG_TGT_LINUX ) && !( defined ( MBG_TGT_NETBSD ) && defined ( MBG_TGT_KERNEL ) ) +#if !defined( MBG_TGT_LINUX ) \ + && !( defined ( MBG_TGT_NETBSD ) \ + && defined ( MBG_TGT_KERNEL ) ) typedef unsigned short ushort; typedef unsigned int uint; typedef unsigned long ulong; @@ -260,14 +239,26 @@ typedef unsigned short word; typedef unsigned long longword; typedef unsigned long dword; + #if !defined( _BIT_DEFINED ) - #if _C99_BIT_TYPES_DEFINED - #include <stdbool.h> + // We need to implement a "bit" type. Preferably we use "bool" + // to do this, but this is only supported by C++ compilers, and + // by C compilers supporting the C99 standard. + + #if !defined( MBG_TGT_MISSING_BOOL_TYPE ) && \ + ( defined( __cplusplus ) || defined( __bool_true_false_are_defined ) ) typedef bool bit; - #else + + #else // C99 types not supported + + // Falling back to use "int" for "bit". This prevents error + // messages if "bit" is used in function prototypes, but may + // yield unexpected results for code like: + // return (bit) ( val & 0x10 ); typedef int bit; + #endif #define _BIT_REDEFINED 1 @@ -275,6 +266,12 @@ typedef unsigned long dword; #endif +#define BYTE_0( _x ) ( ( (ulong) (_x) ) & 0xFF ) +#define BYTE_1( _x ) ( ( ( (ulong) (_x) ) >> 8 ) & 0xFF ) +#define BYTE_2( _x ) ( ( ( (ulong) (_x) ) >> 16 ) & 0xFF ) +#define BYTE_3( _x ) ( ( ( (ulong) (_x) ) >> 24 ) & 0xFF ) + + #define HI_BYTE( _x ) ( (_x) >> 8 ) #define LO_BYTE( _x ) ( (_x) & 0xFF ) @@ -336,6 +333,15 @@ typedef unsigned long dword; #endif +// A macro function which can safely be used without +// side effects as a macro doing nothing. +// This is useful to define debug macros away in +// release builds, etc. +#if !defined( _nop_macro_fnc ) + #define _nop_macro_fnc() do {} while (0) +#endif + + /** * @brief A table entry which can be used to map codes to names. */ diff --git a/mbgsetsystime/mbgsetsystime.c b/mbgsetsystime/mbgsetsystime.c index 334b431..0dad203 100755 --- a/mbgsetsystime/mbgsetsystime.c +++ b/mbgsetsystime/mbgsetsystime.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgsetsystime.c 1.8.1.2 2011/07/05 15:35:55 martin TEST $ + * $Id: mbgsetsystime.c 1.8.1.3 2013/01/24 14:39:51 martin TEST $ * * Description: * Main file for mbgsetsystime program which reads the current date @@ -14,6 +14,7 @@ * * ----------------------------------------------------------------------- * $Log: mbgsetsystime.c $ + * Revision 1.8.1.3 2013/01/24 14:39:51 martin * Revision 1.8.1.2 2011/07/05 15:35:55 martin * Modified version handling. * Revision 1.8.1.1 2011/07/05 14:36:01 martin @@ -121,7 +122,7 @@ int do_mbgsetsystime( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) done: mbg_close_device( &dh ); - return 0; + return ret_val; } // do_mbgsetsystime diff --git a/mbgstatus/mbgstatus.c b/mbgstatus/mbgstatus.c index c1f264e..8e6bdd8 100755 --- a/mbgstatus/mbgstatus.c +++ b/mbgstatus/mbgstatus.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgstatus.c 1.13.1.19 2011/10/28 13:46:14 martin TEST $ + * $Id: mbgstatus.c 1.13.1.26 2013/06/25 09:54:09 martin TRASH martin $ * * Description: * Main file for mbgstatus program which demonstrates how to @@ -10,6 +10,15 @@ * * ----------------------------------------------------------------------- * $Log: mbgstatus.c $ + * Revision 1.13.1.26 2013/06/25 09:54:09 martin + * Revision 1.13.1.25 2013/02/05 14:36:47 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 @@ -102,7 +111,6 @@ // include system headers #include <stdio.h> #include <stdlib.h> -#include <unistd.h> #define MBG_MICRO_VERSION 0 @@ -121,6 +129,7 @@ static const char *osc_name[N_GPS_OSC] = DEFAULT_GPS_OSC_NAMES; static int year_limit = 1990; static int max_ref_offs_h = MBG_REF_OFFS_MAX / MINS_PER_HOUR; +static int invt_reason; LANGUAGE language; CTRY ctry; @@ -128,6 +137,29 @@ CTRY ctry; static /*HDR*/ +void show_invt_reason( void ) +{ + static const char fmt[] = "\n** Warning: %s\nThe command %s.\n"; + + switch ( invt_reason ) + { + case 2: + printf( fmt, DEFAULT_STR_IRIG_NOT_CFGD_EN, + "\"mbgirigcfg\" can be used to change the settings" ); + break; + + case 1: + printf( fmt, DEFAULT_STR_IRIG_INVT_EN, + "\"mbgctrl DATE=...\" can be used to set the on-board date" ); + break; + + } // switch + +} // show_invt_reason + + + +static /*HDR*/ void print_pcps_time( const char *s, const PCPS_TIME *tp, const char *tail ) { const char *fmt = "%s"; @@ -176,9 +208,14 @@ void print_position( const char *s, const POS *p, const char *tail ) if ( s ) + { printf( fmt, s ); - if ( verbose > 0 ) + if ( verbose ) + printf( "\n" ); + } + + if ( verbose > 1 ) { printf( " x: %.0fm y: %.0fm z: %.0fm", p->xyz[XP], p->xyz[YP], p->xyz[ZP] ); @@ -194,8 +231,11 @@ void print_position( const char *s, const POS *p, const char *tail ) if ( tail ) printf( fmt, tail ); - print_dms( " latitude: ", &p->latitude, tail ); - print_dms( " longitude:", &p->longitude, tail ); + if ( verbose ) + { + print_dms( " latitude: ", &p->latitude, tail ); + print_dms( " longitude:", &p->longitude, tail ); + } } // print_position @@ -262,9 +302,12 @@ void show_signal( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, int signal ) static /*HDR*/ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char *tail ) { - const char *status_fmt = "Status info: %s%s\n"; - const char *status_err = "*** "; - const char *status_ok = ""; + const char status_fmt[] = "Status info: %s%s\n"; + const char status_err[] = "*** "; + const char status_ok[] = ""; + const char *info_err = ( _pcps_is_gps( pdev ) || _pcps_is_lwr( pdev ) ) ? + "ANTENNA FAULTY" : "NO INPUT SIGNAL"; + const char info_ok[] = "Input signal available"; PCPS_TIME t; PCPS_STATUS_STRS strs; int signal; @@ -312,7 +355,7 @@ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char * printf( "\n" ); } - if ( _pcps_has_irig_time( pdev ) ) + if ( verbose && _pcps_has_irig_time( pdev ) ) { PCPS_IRIG_TIME it; @@ -323,20 +366,9 @@ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char * it.yday, it.hour, it.min, it.sec ); } - if ( _pcps_is_irig_rx( pdev ) ) - { - printf( status_fmt, - ( signal < PCPS_SIG_ERR ) ? status_err : status_ok, - ( signal < PCPS_SIG_ERR ) ? "NO INPUT SIGNAL" - : "Input signal available" ); - } - else - { - printf( status_fmt, - ( signal < PCPS_SIG_ERR ) ? status_err : status_ok, - ( signal < PCPS_SIG_ERR ) ? "ANTENNA IS NOT CONNECTED" - : "Antenna is connected" ); - } + printf( status_fmt, + ( signal < PCPS_SIG_ERR ) ? status_err : status_ok, + ( signal < PCPS_SIG_ERR ) ? info_err : info_ok ); // Evaluate the status code and setup status messages. pcps_status_strs( t.status, _pcps_time_is_read( &t ), @@ -352,6 +384,23 @@ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char * pstr->cp ); } + invt_reason = 0; + + if ( _pcps_is_irig_rx( pdev ) && ( t.status & PCPS_INVT ) ) + { + MBG_REF_OFFS ref_offs; + + rc = mbg_get_ref_offs( dh, &ref_offs ); + + if ( !mbg_ioctl_err( rc, "mbg_get_ref_offs" ) ) + { + if ( _pcps_ref_offs_out_of_range( ref_offs ) ) + invt_reason = 2; + else + invt_reason = 1; + } + } + } // show_time_and_status @@ -442,7 +491,7 @@ void show_gps_pos( MBG_DEV_HANDLE dh, const char *tail ) if ( mbg_ioctl_err( rc, "mbg_get_gps_pos" ) ) return; - print_position( "Receiver Position:\n", &pos, tail ); + print_position( "Receiver Position:", &pos, tail ); } // show_gps_pos @@ -605,14 +654,7 @@ void show_lan_intf_state( MBG_DEV_HANDLE dh ) printf( "On-board LAN interface settings:\n" ); - snprintf( ws, sizeof( ws ), "%02X-%02X-%02X-%02X-%02X-%02X", - lan_if_info.mac_addr[0], - lan_if_info.mac_addr[1], - lan_if_info.mac_addr[2], - lan_if_info.mac_addr[3], - lan_if_info.mac_addr[4], - lan_if_info.mac_addr[5] - ); + snprint_mac_addr( ws, sizeof( ws ), &lan_if_info.mac_addr ); printf( " MAC Address: %s\n", ws ); snprint_ip4_addr( ws, sizeof( ws ), &ip4_settings.ip_addr, NULL ); @@ -690,6 +732,10 @@ void show_ptp_state( MBG_DEV_HANDLE dh ) ); printf( " PTP time offset: %s\n", cp ); + if ( verbose ) + printf( " PTP UTC offset: %i, flags: 0x%02X\n", + ptp_state.utc_offset, ptp_state.flags ); + } // show_ptp_state @@ -766,13 +812,13 @@ int do_mbgstatus( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) if ( _pcps_has_utc_parm( p_dev ) && ( _pcps_is_gps( p_dev ) || ( verbose > 0 ) ) ) show_utc_info( dh, p_dev ); - if ( _pcps_has_irig_ctrl_bits( p_dev ) ) + if ( verbose && _pcps_has_irig_ctrl_bits( p_dev ) ) show_irig_ctrl_bits( dh ); - if ( _pcps_has_raw_irig_data( p_dev ) ) + if ( verbose && _pcps_has_raw_irig_data( p_dev ) ) show_raw_irig_data( dh ); - if ( _pcps_is_irig_rx( p_dev ) ) + if ( verbose && _pcps_is_irig_rx( p_dev ) ) show_irig_debug_status( dh ); if ( _pcps_has_lan_intf( p_dev ) ) @@ -781,6 +827,8 @@ int do_mbgstatus( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) if ( _pcps_has_ptp( p_dev ) ) show_ptp_state( dh ); + show_invt_reason(); + done: return ret_val; diff --git a/mbgsvcd/Makefile b/mbgsvcd/Makefile index 404db32..5a520bc 100755 --- a/mbgsvcd/Makefile +++ b/mbgsvcd/Makefile @@ -1,13 +1,17 @@ ######################################################################### # -# $Id: Makefile 1.1.1.3 2011/09/26 16:07:31 martin TEST $ +# $Id: Makefile 1.1.1.5 2013/04/22 14:23:03 daniel TRASH $ # # Description: # Makefile for mbgsvcd. # # ----------------------------------------------------------------------- # $Log: Makefile $ +# Revision 1.1.1.5 2013/04/22 14:23:03 daniel +# Add library rt +# Revision 1.1.1.4 2012/08/06 11:27:11 martin +# Added some object files to the list. # Revision 1.1.1.3 2011/09/26 16:07:31 martin # Updated for use with latest base Makefile. # Revision 1.1.1.2 2010/08/30 09:05:24 martin @@ -26,6 +30,10 @@ OBJS += toolutil.o OBJS += gpsutils.o OBJS += mbgmktm.o OBJS += pcpsmktm.o +OBJS += chk_time_info.o +OBJS += ntp_shm.o + +LDFLAGS += -lrt BASEDIR := .. include $(BASEDIR)/Makefile diff --git a/mbgsvcd/mbgsvcd.c b/mbgsvcd/mbgsvcd.c index 8b1ea22..9ad9201 100755 --- a/mbgsvcd/mbgsvcd.c +++ b/mbgsvcd/mbgsvcd.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgsvcd.c 1.3.1.14 2011/11/17 10:07:08 martin TEST daniel $ + * $Id: mbgsvcd.c 1.3.1.15.1.6 2013/06/26 16:33:21 martin TRASH $ * * Description: * Main file for mbgsvcd which compares the system time to a PCI card's @@ -9,6 +9,17 @@ * * ----------------------------------------------------------------------- * $Log: mbgsvcd.c $ + * Revision 1.3.1.15.1.6 2013/06/26 16:33:21 martin + * Don't include sys/sysinfo .h, doesn't build under FreeBSD. + * Revision 1.3.1.15.1.5 2013/04/24 08:19:53 daniel + * Use seconds for the trust time. + * Revision 1.3.1.15.1.3 2013/01/24 14:41:53 martin + * Revision 1.3.1.15.1.2 2013/01/02 10:24:47 daniel + * preliminary support for nsec + * Revision 1.3.1.15.1.1 2012/06/02 10:18:40 martin + * Tmp. code to print leap second status. + * Revision 1.3.1.15 2012/05/24 12:46:23 martin + * Moved some code to some extra modules which can be shared. * Revision 1.3.1.14 2011/11/17 10:07:08 martin * Added leap second support. * Revision 1.3.1.13 2011/10/06 13:03:46 martin @@ -54,6 +65,8 @@ #include <pcpsutil.h> #include <toolutil.h> // common utility functions #include <pcpsmktm.h> +#include <chk_time_info.h> +#include <ntp_shm.h> // include system headers #include <stdio.h> @@ -71,6 +84,10 @@ #include <signal.h> #include <syslog.h> #include <stdarg.h> +#include <time.h> +#include <sys/time.h> + +// #include <sys/sysinfo.h> #include <sys/ipc.h> @@ -86,70 +103,24 @@ static const char *pname = "mbgsvcd"; static int sleep_intv = 1; +static unsigned long trust_time_seconds = 345600UL; // 4 days as default static int pretend_sync; +static int frac_digits = 9; +static int print_raw; +MBG_PC_CYCLES_FREQUENCY cyc_freq; -/** - * @defgroup group_ntp_defs NTP interface definitions - * - * @Note These definitions have been copied from the NTP source code (http://www.ntp.org) - * - * @{ */ - -/** @brief Structure of NTP's shared memory segment */ -struct shmTime { - int mode; /* 0 - if valid set - * use values, - * clear valid - * 1 - if valid set - * if count before and after read of - * values is equal, - * use values - * clear valid - */ - int count; - time_t clockTimeStampSec; /* external clock */ - int clockTimeStampUSec; /* external clock */ - time_t receiveTimeStampSec; /* internal clock, when external value was received */ - int receiveTimeStampUSec; /* internal clock, when external value was received */ - int leap; - int precision; - int nsamples; - int valid; - int dummy[10]; -}; - -/** @brief codes used with struct shmTime::leap */ -#define LEAP_NOWARNING 0x0 /**< normal, no leap second warning */ -#define LEAP_ADDSECOND 0x1 /**< last minute of day has 61 seconds */ -#define LEAP_DELSECOND 0x2 /**< last minute of day has 59 seconds */ -#define LEAP_NOTINSYNC 0x3 /**< overload, clock is free running */ - -#define NTPD_BASE 0x4e545030 /* "NTP0" */ - -#define MAX_SHM_REFCLOCKS 4 - -/** @} group_ntp_defs */ static struct shmTime *shmTime[MAX_SHM_REFCLOCKS]; +static FILTER filter; //##++++ [MAX_SHM_REFCLOCKS] ? +static int has_synced_after_reset[MAX_SHM_REFCLOCKS] = { 0 }; +static long int ref_trust_time_start[MAX_SHM_REFCLOCKS] = { 0 }; +static long int ref_trust_time_expire[MAX_SHM_REFCLOCKS] = { 0 }; -#define MAX_FILTER_ENTRIES 32 - -typedef struct -{ - MBG_PC_CYCLES cyc[MAX_FILTER_ENTRIES]; - MBG_PC_CYCLES sum; - int entries; - int index; -} FILTER; - -static FILTER filter; - - -static /*HDR*/ +/*HDR*/ void mbg_log( int lvl, const char *fmt, ... ) { char ws[256]; @@ -167,98 +138,9 @@ void mbg_log( int lvl, const char *fmt, ... ) static /*HDR*/ -MBG_PC_CYCLES do_filter( FILTER *p, MBG_PC_CYCLES cyc ) -{ - if ( p->entries < MAX_FILTER_ENTRIES ) - p->entries++; - - if ( ++( p->index ) >= MAX_FILTER_ENTRIES ) - p->index = 0; - - // update the sum of filter entries - p->sum -= p->cyc[p->index]; // subtract oldest sample - p->cyc[p->index] = cyc; // save new sample - p->sum += cyc; // add new sample - - return p->sum / p->entries; // return mean value - -} /* do_filter */ - - - -static -struct shmTime *getShmTime( int unit ) -{ - struct shmTime *p; - - int shmid = shmget( (key_t) ( NTPD_BASE + unit ), - sizeof( struct shmTime ), IPC_CREAT | 0644 ); - - if ( shmid == -1 ) - { - mbg_log( LOG_ERR, "shmget %i failed: %s", unit, strerror( errno ) ); - return NULL; - } - - - p = (struct shmTime *) shmat( shmid, 0, 0 ); - - if ( (long) p == -1L ) - { - mbg_log( LOG_ERR, "shmat %i failed: %s", unit, strerror( errno ) ); - return NULL; - } - - return p; - -} // getShmTime - - - -static /*HDR*/ -int ntpshm_init( int n_units ) -{ - int i; - int ret_val = 0; - - for ( i = 0; i < n_units; i++ ) - { - struct shmTime *p = getShmTime( i ); - shmTime[i] = p; - - if ( p == NULL ) - { - mbg_log( LOG_WARNING, "** Failed to initialize NTP SHM unit %i", i ); - ret_val = -1; - continue; - } - - memset( p, 0, sizeof( *p ) ); - - p->mode = 1; - p->precision = -5; /* initially 0.5 sec */ - p->nsamples = 3; /* stages of median filter */ - - mbg_log( LOG_INFO, "NTP SHM unit %i initialized successfully", i ); - } - - return ret_val; - -} // ntpshm_init - - - -static /*HDR*/ int do_mbgsvctasks( void ) { - MBG_PC_CYCLES_FREQUENCY cyc_freq; - MBG_TIME_INFO_HRT hrti; - PCPS_TIME_STAMP *p_ref_ts; - MBG_PC_CYCLES *p_ref_cyc; - MBG_SYS_TIME_CYCLES *p_sys_tic; char ws[256]; - double d_ref; - double d_sys; int rc = 0; int n_devices_found; int n_devices; @@ -304,7 +186,7 @@ int do_mbgsvctasks( void ) } - // Search for devices up to the maximum of supported NTP SHM refclocks + // Search for devices up to the maximum of supported number of NTP SHM refclocks if ( n_devices > MAX_SHM_REFCLOCKS ) n_devices = MAX_SHM_REFCLOCKS; @@ -321,74 +203,73 @@ int do_mbgsvctasks( void ) (unsigned long long) cyc_freq ); // Initialize NTP shared memory area - ntpshm_init( n_devices ); + ntpshm_init( shmTime, n_devices ); for (;;) { for ( i = 0; i < n_devices; i++ ) { - double ltcy_sec; - double d_ref_comp; - MBG_PC_CYCLES ltcy_cyc; - MBG_PC_CYCLES exec_cyc; - MBG_PC_CYCLES exec_cyc_limit; - MBG_PC_CYCLES tmp; + MBG_CHK_TIME_INFO cti; const char *cp; + int leap; - rc = mbg_get_time_info_hrt( dhs[i], &hrti ); + rc = mbg_chk_time_info( dhs[i], &cti, &filter, 0 ); //##+++++ one or more filter instances ? - if ( mbg_ioctl_err( rc, "mbg_get_time_info_hrt" ) ) + if ( mbg_ioctl_err( rc, "mbg_chk_time_info" ) ) continue; - - p_ref_ts = &hrti.ref_hr_time_cycles.t.tstamp; - p_ref_cyc = &hrti.ref_hr_time_cycles.cycles; - p_sys_tic = &hrti.sys_time_cycles; - - d_ref = (double) p_ref_ts->sec + ( (double) p_ref_ts->frac ) / (double) PCPS_HRT_BIN_FRAC_SCALE; - d_sys = (double) p_sys_tic->sys_time.sec + (double) p_sys_tic->sys_time.nsec / 1e9; - - ltcy_cyc = mbg_delta_pc_cycles( p_ref_cyc, &p_sys_tic->cyc_after ); - exec_cyc = mbg_delta_pc_cycles( &p_sys_tic->cyc_after, &p_sys_tic->cyc_before ); - - ltcy_sec = cyc_freq ? ( ( (double) ltcy_cyc ) / (double) cyc_freq ) : 0.0; - - // Compensate latencies between time stamps -> - // normalize ref time to system time stamp - d_ref_comp = d_ref - ltcy_sec; - - exec_cyc_limit = do_filter( &filter, exec_cyc ); - - // Try to set the limit to 1.7 of the mean execution cycles. - tmp = ( 7 * exec_cyc_limit ) / 10; - - // If execution takes only a few cycles make sure the limit - // is above the mean number of cycles. - if ( tmp == 0 ) - tmp++; - - exec_cyc_limit += tmp; - cp = ""; + leap = 0; + + if ( ( has_synced_after_reset[i] == 1 ) && ( ( ( cti.hrti.ref_hr_time_cycles.t.status & PCPS_FREER ) == 1 ) + || ( ( cti.hrti.ref_hr_time_cycles.t.status & PCPS_SYNCD ) == 0 ) )) + + { + struct timespec ts; + + clock_gettime(CLOCK_MONOTONIC, &ts); + + if (ref_trust_time_start[i] == 0 ) + { + mbg_log( LOG_WARNING, "Device #%i, entering holdover mode", i ); + ref_trust_time_start[i] = ts.tv_sec; + ref_trust_time_expire[i] = ts.tv_sec + trust_time_seconds; + } + + if ( ts.tv_sec > ref_trust_time_expire[i] ) + { + mbg_log( LOG_WARNING, "Device #%i, trust time expired", i ); + has_synced_after_reset[i] = 0; + ref_trust_time_start[i] = 0; + ref_trust_time_expire[i] = 0; + } + } // check if refclock is sync and if exec time of the system time call was fast enough - if ( ( exec_cyc <= exec_cyc_limit ) && ( pretend_sync || ( - ( ( hrti.ref_hr_time_cycles.t.status & PCPS_FREER ) == 0 ) && - ( ( hrti.ref_hr_time_cycles.t.status & PCPS_SYNCD ) != 0 ) ) ) ) + if ( ( cti.exec_cyc <= cti.exec_cyc_limit ) && ( pretend_sync || has_synced_after_reset[i] || ( + ( ( cti.hrti.ref_hr_time_cycles.t.status & PCPS_FREER ) == 0 ) && + ( ( cti.hrti.ref_hr_time_cycles.t.status & PCPS_SYNCD ) != 0 ) ) ) ) { struct shmTime *p = shmTime[i]; + + has_synced_after_reset[i] = 1; if ( p ) { + MBG_SYS_TIME_CYCLES *p_sys_tic = &cti.hrti.sys_time_cycles; cp = " *"; // fill SHM structure p->count++; - p->clockTimeStampSec = (time_t) d_ref_comp; - p->clockTimeStampUSec = (int) ( ( d_ref_comp - p->clockTimeStampSec ) * 1e6 ); // get µs from d_ref + p->clockTimeStampSec = (time_t) cti.d_ref_comp; + p->clockTimeStampUSec = (int) ( ( cti.d_ref_comp - p->clockTimeStampSec ) * 1e6 ); // get µs from d_ref p->receiveTimeStampSec = (time_t) p_sys_tic->sys_time.sec; p->receiveTimeStampUSec = (int) ( p_sys_tic->sys_time.nsec / 1000 ); + // These fields are only supported by newer versions of ntpd //##++++++++++++++++++ which versions ? + p->clockTimeStampNSec = (int) ( ( cti.d_ref_comp - p->clockTimeStampSec ) * 1e9 ); // get ns from d_ref + p->receiveTimeStampNSec = (int) ( p_sys_tic->sys_time.nsec ); + // patch precision value according to the ref time accuracy if ( _pcps_is_lwr( &devs[i] ) ) p->precision = -8; @@ -405,41 +286,23 @@ int do_mbgsvctasks( void ) p->precision = -20; } - if ( hrti.ref_hr_time_cycles.t.status & PCPS_LS_ANN_NEG ) + if ( cti.hrti.ref_hr_time_cycles.t.status & PCPS_LS_ANN_NEG ) p->leap = LEAP_DELSECOND; else - if ( hrti.ref_hr_time_cycles.t.status & PCPS_LS_ANN ) + if ( cti.hrti.ref_hr_time_cycles.t.status & PCPS_LS_ANN ) p->leap = LEAP_ADDSECOND; else p->leap = LEAP_NOWARNING; + leap = p->leap; //##+++ + p->count++; p->valid = 1; } } - mbg_snprint_hr_tstamp( ws, sizeof( ws ), p_ref_ts, 0 ); // raw timestamp? - - printf( "%-9s: %s: %.7f-%.7f: %+.7f %+.7f, ltcy: ", - _pcps_type_name( &devs[i] ), ws, d_ref, d_sys, - d_ref - d_sys, d_ref_comp - d_sys ); - - if ( cyc_freq != 0 ) // print latency and execution time in microseconds - { - double exec_sec = (double) exec_cyc / (double) cyc_freq; - double exec_sec_limit = (double) exec_cyc_limit / (double) cyc_freq; - - printf( "%.2f us, exec: %.2f us, limit: %.2f us", - ltcy_sec * 1e6, exec_sec * 1e6, exec_sec_limit * 1e6 ); - } - else // print latency and execution time in cycles only - { - printf( "%lli cyc, exec: %lli cyc, limit: %lli cyc", - (long long) ltcy_cyc, (long long) exec_cyc, - (long long) exec_cyc_limit ); - } - - printf( "%s\n", cp ); + snprint_chk_time_info( ws, sizeof( ws ), &cti, &devs[i], frac_digits, print_raw ); + printf( "%s, leap: %02X%s\n", ws, leap, cp ); usleep( 10 ); } @@ -476,6 +339,7 @@ void usage( void ) mbg_print_opt_info( "-f", "run program in foreground" ); mbg_print_opt_info( "-s num", "sleep num seconds between calls" ); mbg_print_opt_info( "-p", "pretend device is always synchronized" ); + mbg_print_opt_info( "-t num", "set num seconds for refclock trust time, default 4 days (345600 seconds)" ); mbg_print_device_options(); puts( "" ); @@ -552,7 +416,7 @@ int main( int argc, char *argv[] ) mbg_print_program_info( pname, MBG_MICRO_VERSION, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); // check command line parameters - while ( ( c = getopt( argc, argv, "fps:h?" ) ) != -1 ) + while ( ( c = getopt( argc, argv, "fpst:h?" ) ) != -1 ) { switch ( c ) { @@ -568,6 +432,15 @@ int main( int argc, char *argv[] ) sleep_intv = atoi( optarg ); break; + case 't': + { + unsigned long tt = atoi( optarg ); + + if ( tt > 0 ) + trust_time_seconds = tt; + break; + } + case 'h': case '?': default: @@ -593,6 +466,8 @@ int main( int argc, char *argv[] ) startup_daemon(); } + mbg_log( LOG_INFO, "refclock trust time: %ul seconds", trust_time_seconds ); + rc = do_mbgsvctasks(); return abs( rc ); diff --git a/mbgversion.h b/mbgversion.h index 55d4d8d..c7df42f 100755 --- a/mbgversion.h +++ b/mbgversion.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgversion.h 1.1 2011/07/06 13:24:48 martin TEST $ + * $Id: mbgversion.h 1.1.1.2 2013/03/11 14:40:34 martin TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,13 +10,17 @@ * * ----------------------------------------------------------------------- * $Log: mbgversion.h $ + * Revision 1.1.1.2 2013/03/11 14:40:34 martin + * Changed copyright year to 2013. + * Revision 1.1.1.1 2012/10/16 10:23:20 martin + * Changed copyright year to 2012. * Revision 1.1 2011/07/06 13:24:48 martin * Initial revision. * **************************************************************************/ -#define MBG_CURRENT_COPYRIGHT_YEAR 2011 -#define MBG_CURRENT_COPYRIGHT_YEAR_STR "2011" +#define MBG_CURRENT_COPYRIGHT_YEAR 2013 +#define MBG_CURRENT_COPYRIGHT_YEAR_STR "2013" #define MBG_MAJOR_VERSION_CODE 0 #define MBG_MINOR_VERSION_CODE 99 diff --git a/mbgxhrtime/mbgxhrtime.c b/mbgxhrtime/mbgxhrtime.c index 863ba08..b7b8c79 100755 --- a/mbgxhrtime/mbgxhrtime.c +++ b/mbgxhrtime/mbgxhrtime.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgxhrtime.c 1.5.1.3 2011/09/07 15:08:56 martin TEST martin $ + * $Id: mbgxhrtime.c 1.5.1.3 2011/09/07 15:08:56 martin TEST $ * * Description: * Main file for mbgxhrtime program which demonstrates how to retrieve |