diff options
99 files changed, 10760 insertions, 11614 deletions
@@ -1,33 +1,18 @@ ######################################################################### # -# $Id: Makefile 1.1.1.14 2017/05/04 15:02:28 martin TEST $ +# $Id: Makefile 1.2 2017/07/06 09:45:24 martin REL_M $ # # Description: # Makefile for mbgtools which recurses into the subdirectories. # # ----------------------------------------------------------------------- # $Log: Makefile $ -# Revision 1.1.1.14 2017/05/04 15:02:28 martin -# Also test subdirs for BSDmakefile. -# Revision 1.1.1.13 2016/08/10 13:46:22 martin -# *** empty log message *** -# Revision 1.1.1.12 2016/08/10 11:31:37 martin +# Revision 1.2 2017/07/06 09:45:24 martin # Support quiet build. -# Revision 1.1.1.11 2014/04/23 14:56:46 martin -# Revision 1.1.1.10 2014/02/05 11:44:48 martin -# Revision 1.1.1.9 2013/07/23 11:08:31 martin -# Link against libutil. -# Revision 1.1.1.8 2011/11/24 11:25:00 martin -# Revision 1.1.1.7 2011/07/06 13:25:06 martin -# Revision 1.1.1.6 2011/03/25 11:05:55 martin +# Updated list of target subdirs. +# Also test subdirs for BSDmakefile. # Optional parameter USE_TIMESPEC. -# Revision 1.1.1.5 2011/03/21 16:24:12 martin -# Workaround for recursive make under NetBSD. -# Revision 1.1.1.4 2011/02/04 10:09:45 martin -# Revision 1.1.1.3 2011/02/02 12:33:29 martin -# Revision 1.1.1.2 2011/01/28 09:29:47 martin -# Revision 1.1.1.1 2011/01/27 16:16:40 martin # Revision 1.1 2011/01/27 15:41:01 martin # Initial revision # @@ -180,7 +165,7 @@ SUBDIRS += mbgshowsignal SUBDIRS += mbggpscap SUBDIRS += mbghrtime SUBDIRS += mbgfasttstamp -# SUBDIRS += mbgxhrtime ## not yet tested +## SUBDIRS += mbgxhrtime ## not yet tested SUBDIRS += test/mbgchksystime ## SUBDIRS += test/mbgclock-test @@ -1,7 +1,7 @@ -$Id: README 1.1.1.4 2017/04/25 19:53:10 martin TEST $ +$Id: README 1.2 2017/07/06 09:48:07 martin REL_M $ -This is the README file for mbgtools-fbsd-dev-2017-04-25 --------------------------------------------------------- +This is the README file for mbgtools-fbsd-1.0.0 +----------------------------------------------- Please send comments and required modifications to Meinberg support <support@meinberg.de> @@ -32,13 +32,6 @@ on older versions. Supported platforms are x86 and amd64. ---------------------------- mbgtools for FreeBSD is based on Meinberg's common driver library mbglib and implements the following programs each of which can be found in -its own subdirectory: - - -2. Driver files and programs ----------------------------- -mbgtools for Linux is based on Meinberg's common driver library mbglib -and implements the following programs each of which can be found in its own subdirectory. Each of the user space programs can be run with parameter '-?' to show @@ -108,6 +101,8 @@ mbgfasttstamp not. mbgxhrtime + !! This program has not yet been fully ported to FreeBSD, + !! and thus is not yet available This example program also shows how to get time stamps faster than shown in mbghrtime. This is not as easy as mbgfasttstamp but can be used with every card which can be used with mbghrtime, even if the @@ -211,7 +206,7 @@ If ntpd is to use the PCI card as reference time source make sure the mbgsvcd daemon is started. Run the following command to copy the service control script to the appropriate directory: -cp scripts/mbgsvcd /etc/rc.d/ + cp scripts/mbgsvcd /etc/rc.d/ Then edit the text file /etc/rc.conf and add the following line: @@ -227,7 +222,7 @@ as reference time source to discipline the system time. In order to achieve this, ntpd needs to be configured to use its shared memory driver (SHM, type 28). -The following entries needd to be made in the ntp.conf file +The following entries need to be made in the ntp.conf file to enable support for 4 PCI cards: server 127.127.28.0 minpoll 4 maxpoll 4 iburst diff --git a/mbgclock/Makefile b/mbgclock/Makefile index 6b441ec..90c88e0 100755 --- a/mbgclock/Makefile +++ b/mbgclock/Makefile @@ -1,7 +1,7 @@ ######################################################################### # -# $Id: Makefile 1.1.1.8 2016/08/10 11:32:05 martin TEST $ +# $Id: Makefile 1.2 2017/07/06 09:13:50 martin REL_M $ # # Description: # Makefile for mbgclock driver to support Meinberg bus level @@ -9,19 +9,8 @@ # # ----------------------------------------------------------------------- # $Log: Makefile $ -# Revision 1.1.1.8 2016/08/10 11:32:05 martin -# *** empty log message *** -# Revision 1.1.1.7 2015/09/18 14:52:59 martin -# *** empty log message *** -# Revision 1.1.1.6 2011/07/06 13:24:29 martin -# Revision 1.1.1.5 2011/05/06 14:12:02 martin -# Revision 1.1.1.4 2011/02/03 14:10:39 martin -# Revision 1.1.1.3 2011/01/26 17:38:58 martin -# Add support for DEBUG build. -# Revision 1.1.1.2 2011/01/26 16:36:37 martin -# Enabled all required source files. -# Revision 1.1.1.1 2011/01/26 14:12:02 martin -# Started modifications to build mbgclock. +# Revision 1.2 2017/07/06 09:13:50 martin +# Updated paths, module list, and compiler flags. # Revision 1.1 2011/01/26 13:56:32 martin # Initial skeleton based on FreeBSD's mypci.c sample program by Murray Stokely. # diff --git a/mbgclock/mbgclock_main.c b/mbgclock/mbgclock_main.c index cc09e42..006c9d6 100755 --- a/mbgclock/mbgclock_main.c +++ b/mbgclock/mbgclock_main.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgclock_main.c 1.1.1.15 2017/05/05 14:38:04 martin TEST $ + * $Id: mbgclock_main.c 1.2 2017/07/06 09:24:03 martin REL_M $ * * Description: * Main file for for mbgclock driver to support Meinberg bus level @@ -14,34 +14,15 @@ * * ----------------------------------------------------------------------- * $Log: mbgclock_main.c $ - * Revision 1.1.1.15 2017/05/05 14:38:04 martin - * Fixed some potential 'unused variable' errors. - * Revision 1.1.1.14 2015/01/16 09:53:54 martin - * Use "struct thread" instead of obsolete "d_thread_t" type. + * Revision 1.2 2017/07/06 09:24:03 martin + * Implemented IOCTL handler which basically can also + * supports privilege checking for IOCTL. + * Improved resource handling. + * Use 'struct thread' instead of obsolete 'd_thread_t' type. * Reported by John Baldwin and George Neville-Neil (FreeBSD bug #196692). - * Revision 1.1.1.13 2011/11/01 09:08:33 martin - * Revision 1.1.1.12 2011/10/05 10:38:06 martin * Unified handling of program version information. - * Started to support privilege checking for IOCTL. - * Fixed sign of returned error codes. - * Free resources on dealloc. - * Revision 1.1.1.11 2011/02/04 14:44:19 martin - * Revision 1.1.1.10 2011/02/02 12:33:52 martin - * Revision 1.1.1.9 2011/02/01 17:11:38 martin - * Revision 1.1.1.8 2011/02/01 14:49:42 martin - * Revision 1.1.1.7 2011/02/01 12:12:17 martin - * Revision 1.1.1.6 2011/01/31 17:28:56 martin - * Modified resource handling. - * Revision 1.1.1.5 2011/01/28 09:31:21 martin - * Fixed debug/non-debug build. - * Revision 1.1.1.4 2011/01/27 15:15:23 martin - * Loads and unloads properly. Calls pcps_start_device() which - * properly reads some data from a card. - * Revision 1.1.1.3 2011/01/26 16:37:18 martin - * Ioctl support compiled in. - * Revision 1.1.1.2 2011/01/26 15:05:53 martin - * Revision 1.1.1.1 2011/01/26 14:34:33 martin - * Started modifications to build mbgclock. + * Support DEBUG messages. + * Code cleanup. * Revision 1.1 2011/01/26 13:56:32 martin * Initial skeleton based on FreeBSD's mypci.c sample program by Murray Stokely. * @@ -211,6 +192,11 @@ mbgclock_write( struct cdev *dev, struct uio *uio, int ioflag ) +/* + * ATTENTION: This function returns one of the MBG_RETURN_CODES. + * However, POSITIVE numbers need to be returned in case of an error, + * so mbg_errno_to_os() needs to be called to convert the return code. + */ int mbgclock_ioctl( struct cdev *dev, u_long cmd, caddr_t data, int32_t flag, struct thread *td ) // credentials in thread @@ -253,67 +239,12 @@ mbgclock_ioctl( struct cdev *dev, u_long cmd, caddr_t data, default: _mbgddmsg_5( MBG_DBG_INFO, "%s: %p IOCTL 0x%02lX: unknown, permission denied, dev %s_%s", pcps_driver_name, dev, cmd, _pcps_ddev_type_name( pddev ), _pcps_ddev_sernum( pddev ) ); - return EPERM; + return mbg_errno_to_os( MBG_ERR_PERM ); } rc = ioctl_switch( pddev, cmd, (void *) data, (void *) data ); - // On success we return quickly. - - if ( rc == MBG_SUCCESS ) - { - _mbgddmsg_5( MBG_DBG_DETAIL, "%s: %p IOCTL 0x%02lX: success, dev %s_%s", - pcps_driver_name, dev, cmd, _pcps_ddev_type_name( pddev ), _pcps_ddev_sernum( pddev ) ); - goto out; - } - - - // An error has occurred. - // Generate an appropriate debug/error message - // and return an error status. - - switch ( rc ) - { - case MBG_ERR_INV_DEV_REQUEST: - _mbgddmsg_6( MBG_DBG_WARN, "%s: %p ioctl 0x%02lX: invalid cmd %04lX, dev %s_%s", - pcps_driver_name, dev, cmd, IOCBASECMD( cmd ), - _pcps_ddev_type_name( pddev ), _pcps_ddev_sernum( pddev ) ); - rc = ENOIOCTL; - break; - - - case MBG_ERR_NOT_SUPP_BY_DEV: - _mbgddmsg_5( MBG_DBG_WARN, "%s: %p ioctl 0x%02lX: not supported by dev %s_%s", - pcps_driver_name, dev, cmd, _pcps_ddev_type_name( pddev ), _pcps_ddev_sernum( pddev ) ); - rc = EINVAL; - break; - - - case MBG_ERR_NO_MEM: - _mbgddmsg_5( MBG_DBG_WARN, "%s: %p ioctl 0x%02lX: unable to allocate buffer for dev %s_%s", - pcps_driver_name, dev, cmd, _pcps_ddev_type_name( pddev ), _pcps_ddev_sernum( pddev ) ); - rc = EFAULT; - break; - - - case MBG_ERR_IRQ_UNSAFE: - _mbgddmsg_5( MBG_DBG_DETAIL, "%s: %p ioctl 0x%02lX: busy since unsafe IRQ enabled, dev %s_%s", - pcps_driver_name, dev, cmd, _pcps_ddev_type_name( pddev ), _pcps_ddev_sernum( pddev ) ); - rc = EBUSY; - break; - - - default: // any access error code returned by the low level routine - // or copying from or to user space - _mbgddmsg_6( MBG_DBG_WARN, "%s: %p ioctl 0x%02lX: error %i accessing dev %s_%s", - pcps_driver_name, dev, cmd, rc, _pcps_ddev_type_name( pddev ), _pcps_ddev_sernum( pddev ) ); - rc = EFAULT; - - } // switch error rc - - -out: - return rc; + return mbg_ret_val_to_os( rc ); } // mbgclock_ioctl @@ -449,7 +380,7 @@ mbgclock_probe( device_t device ) if ( vend_id != PCI_VENDOR_MEINBERG ) goto fail; - pdt = pcps_get_dev_type( PCPS_BUS_PCI, dev_id ); + pdt = pcps_get_dev_type_table_entry( PCPS_BUS_PCI, dev_id ); if ( pdt == NULL ) goto fail; @@ -511,12 +442,12 @@ mbgclock_attach( device_t device ) mbg_alloc_rsrcs( device ); - //##++++++ rc = pcps_start_device( pddev, device->bus->number, device->devfn ); - rc = pcps_start_device( psc->pddev, 0, 0 ); + //##++++++ rc = pcps_probe_device( pddev, device->bus->number, device->devfn ); + rc = pcps_probe_device( psc->pddev, 0, 0 ); if ( rc != PCPS_SUCCESS ) { - _mbgddmsg_3( MBG_DBG_INIT_DEV, "%s: attach device 0x%04X: pcps_start_device() failed, rc: %i", + _mbgddmsg_3( MBG_DBG_INIT_DEV, "%s: attach device 0x%04X: pcps_probe_device() failed, rc: %i", pcps_driver_name, dev_id, rc ); rc = ENXIO; goto fail; diff --git a/mbgctrl/Makefile b/mbgctrl/Makefile index 1383cd1..367960d 100755 --- a/mbgctrl/Makefile +++ b/mbgctrl/Makefile @@ -1,27 +1,16 @@ ######################################################################### # -# $Id: Makefile 1.7.1.8 2016/07/15 14:06:51 martin TEST $ +# $Id: Makefile 1.8 2017/07/05 18:51:21 martin REL_M $ # # Description: # Makefile for mbgctrl. # # ----------------------------------------------------------------------- # $Log: Makefile $ -# Revision 1.7.1.8 2016/07/15 14:06:51 martin -# Added new module timeutil.o. -# Revision 1.7.1.7 2015/10/27 15:07:37 martin -# Removed obsolete object modules. -# Revision 1.7.1.6 2015/08/31 14:22:53 martin -# Revision 1.7.1.5 2015/07/14 15:07:19 martin -# Added object module mbgerror.o. -# Revision 1.7.1.4 2014/04/28 13:19:51 martin -# Added module cfg_hlp.o. -# Revision 1.7.1.3 2011/09/26 15:50:00 martin -# Updated for use with latest base Makefile. -# Added modules devio_hlp and lan_util. -# Revision 1.7.1.2 2010/08/30 09:05:22 martin -# Revision 1.7.1.1 2010/08/30 08:20:54 martin +# Revision 1.8 2017/07/05 18:51:21 martin +# Updated list of object files and use top level +# Makefile properly. # Revision 1.7 2009/07/24 10:31:16 martin # Moved declarations to a common file which is now included. # Revision 1.6 2008/12/22 11:54:31 martin diff --git a/mbgctrl/mbgctrl.c b/mbgctrl/mbgctrl.c index b3930fd..ea9e250 100755 --- a/mbgctrl/mbgctrl.c +++ b/mbgctrl/mbgctrl.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgctrl.c 1.22.1.14.1.4 2017/02/08 11:41:20 martin TEST $ + * $Id: mbgctrl.c 1.23 2017/07/05 19:10:07 martin REL_M $ * * Description: * Main file for mbgctrl program which sends commands and @@ -9,48 +9,18 @@ * * ----------------------------------------------------------------------- * $Log: mbgctrl.c $ - * Revision 1.22.1.14.1.4 2017/02/08 11:41:20 martin - * Basic support for programmable pulse outputs, including pulse shift feature. - * Revision 1.22.1.14.1.3 2017/01/30 16:15:08 martin - * Enhanced PTP configuration. - * Fixed a bug where PTP unicast master configuration wasn't saved. - * Cleanup. - * Revision 1.22.1.14.1.2 2016/08/09 15:56:21 martin - * Account for modified library functions. - * Revision 1.22.1.14.1.1 2015/12/17 12:01:28 martin - * Fixed a compiler warning 'set but not used'. - * 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. - * Modified program version handling. - * Use O_RDWR flag when opening a device. - * Account for modified library functions which can now - * optionally print the raw (hex) HR time stamp. - * Revision 1.22.1.7 2011/04/19 10:02:37 martin - * Syntax fix. - * Revision 1.22.1.6 2011/04/19 09:57:00 martin - * Untabbified and removed trailing spaces. - * Revision 1.22.1.5 2011/03/21 08:32:18 martin - * Fixed compiler warning. - * Revision 1.22.1.4 2011/03/03 10:01:00 daniel - * Support configuring PTP roles. - * Revision 1.22.1.3 2011/02/18 13:35:59 daniel - * Revision 1.22.1.2 2011/02/18 13:35:11 daniel - * Revision 1.22.1.1 2011/02/18 11:27:29 daniel - * Preliminary support for configuring PTP parameters incl. Unicast + * Revision 1.23 2017/07/05 19:10:07 martin + * New way to maintain version information. + * Support build under Windows. * Bugfix: accept parameter keyword only when substring is found at the * start of the parameter string. + * Support configuring PTP parameters incl. unicast + * Warn if trying to handle serial port cfg but no serial port is supported. + * Basic support for programmable pulse outputs, including pulse shift feature. + * Yet incomplete support for synthesizer output. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. * Revision 1.22 2009/09/29 14:58:18 martin * Unified and simplified parameter evaluation. * Updated version number to 3.4.0. @@ -145,6 +115,7 @@ #define MBG_FIRST_COPYRIGHT_YEAR 2001 #define MBG_LAST_COPYRIGHT_YEAR 0 // use default +#define RC_USAGE 1 static const char *pname = "mbgctrl"; @@ -152,7 +123,6 @@ static char *dev_name; static int err_unicast_nsupp; -static const char str_empty[] = ""; static const char str_spc_not[] = " not"; static const char str_spc_not_supp[] = " (not supported)"; static const char str_spc_wildcard[] = " (wildcard)"; @@ -182,10 +152,11 @@ static const char * const pout_mode_names_eng[N_POUT_MODES] = DEFAULT_ENG_POUT_N static const char no_gps_cmd[] = "does not support GPS commands"; static const char no_tzdl[] = "does not support configurable time zone"; static const char no_tz[] = "does not support time zones"; +static const char no_synth[] = "has no synthesizer output"; static const char no_event_time[] = "does not support event times"; static const char no_enable_flags[] = "does not support enable flags"; static const char no_time_scale[] = "does not support a configurable time scale"; -static const char no_lan_intf[] = "does not provide a LAN interface"; +static const char no_lan_intf[] = "has no LAN interface"; static const char no_ptp[] = "does not provide PTP"; static const char no_cab_len[] = "does not support antenna signal delay compensation"; @@ -544,7 +515,7 @@ int set_tz_code( MBG_DEV_HANDLE dh, PCPS_TZCODE tzcode, const char *s ) { int rc = mbg_set_tzcode( dh, &tzcode ); - if ( mbg_ioctl_err( rc, "mbg_set_tzcode" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_tzcode" ) ) return rc; printf( "The clock's time zone setting has been set to %s.\n", s ); @@ -560,7 +531,7 @@ int set_gps_tzdl( MBG_DEV_HANDLE dh, const TZDL *tzdl, const char *info ) { int rc = mbg_set_gps_tzdl( dh, tzdl ); - if ( mbg_ioctl_err( rc, "set_gps_tzdl" ) ) + if ( mbg_cond_err_msg( rc, "set_gps_tzdl" ) ) return rc; if ( info ) @@ -601,7 +572,7 @@ int set_timezone( MBG_DEV_HANDLE dh, const char *tz_name, const PCPS_DEV *p_dev else { printf( "** Unknown timezone name %s\n", tz_name ); - rc = 1; + rc = RC_USAGE; } if ( tz_info ) @@ -627,7 +598,7 @@ int show_tzdl_offs( MBG_DEV_HANDLE dh, const char *info ) TZDL tzdl; int rc = mbg_get_gps_tzdl( dh, &tzdl ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_tzdl" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_gps_tzdl" ) ) return rc; printf( "%s timezone offset: UTC%+lis", info, (long) tzdl.offs ); @@ -660,6 +631,60 @@ int set_tzdl_offs( MBG_DEV_HANDLE dh, const char *s ) static /*HDR*/ +int show_synth( MBG_DEV_HANDLE dh, const char *info ) +{ + SYNTH synth; + int rc = mbg_get_synth( dh, &synth ); + + if ( mbg_cond_err_msg( rc, "mbg_get_synth" ) ) + return rc; + + printf( "%s synthesizer settings: freq %i.%iE%i Hz, phase %+i.%i deg", info, + synth.freq / 10, synth.freq % 10, synth.range, + synth.phase / 10, abs( synth.phase ) % 10 ); + +/* + int16_t freq; ///< four digits used; scale: 0.1 Hz; e.g. 1234 -> 123.4 Hz + int16_t range; ///< scale factor for freq; 0..::MAX_SYNTH_RANGE + int16_t phase; ///< -::MAX_SYNTH_PHASE..+::MAX_SYNTH_PHASE; >0 -> pulses later +*/ + return MBG_SUCCESS; + +} // show_synth + + + +static /*HDR*/ +int set_synth( MBG_DEV_HANDLE dh, const char *s ) +{ + SYNTH synth = { 0 }; + char *cp; + + long freq = strtol( s, &cp, 10 ) * 10; + + if ( *cp == '.' ) + { + long frac = strtol( ++cp, NULL, 10 ); + if ( frac < 0 || frac > 9 ) + goto fail; + + freq += frac; + } + + synth.freq = (int16_t) freq; + synth.range = 0; + synth.phase = 0; + + return mbg_set_synth( dh, &synth ); + +fail: + return MBG_ERR_INV_PARM; + +} // set_synth + + + +static /*HDR*/ int show_lan_intf( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *info ) { IP4_SETTINGS ip4_settings; @@ -667,7 +692,7 @@ int show_lan_intf( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *info ) int rc = mbg_get_ip4_settings( dh, &ip4_settings ); - if ( mbg_ioctl_err( rc, "mbg_get_ip4_settings" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_ip4_settings" ) ) return rc; printf( "On-board LAN interface settings:" ); @@ -731,7 +756,7 @@ int show_ptp_cfg( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *info ) int rc = mbg_get_all_ptp_cfg_info( dh, &all_ptp_cfg_info ); - if ( mbg_ioctl_err( rc, "mbg_get_all_ptp_cfg_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_all_ptp_cfg_info" ) ) return rc; unicast_supported = ( pi->supp_flags & PTP_CFG_MSK_SUPPORT_PTP_UNICAST ) != 0; @@ -843,9 +868,9 @@ static /*HDR*/ * @param p A pointer to a (char *) which is set to the beginning * of the value part of a parameter string * - * @return <0 Syntax error, i.e. missing colon - * 0 No error. If parameter has been found then *p set - * to the parameter value, else to NULL. + * @return ::MBG_SUCCESS on success. If parameter has been found then + * @p *p is set to the parameter value, else to NULL. + * ::MBG_ERR_PARM_FMT if syntax error, i.e. missing colon. */ int chk_parm_name( const char *arg, const char *id, char **p ) { @@ -856,7 +881,7 @@ int chk_parm_name( const char *arg, const char *id, char **p ) cp += strlen( id ); if ( *cp != ':' ) - return -1; + return MBG_ERR_PARM_FMT; cp++; } @@ -864,7 +889,7 @@ int chk_parm_name( const char *arg, const char *id, char **p ) if ( p ) *p = cp; // may be NULL - return 0; + return MBG_SUCCESS; } // chk_parm_name @@ -938,8 +963,8 @@ int chk_int16_parm( const char *arg, const char *id, int16_t *p, int16_t range_m char *cp; int idx = chk_parm_name( arg, id, &cp ); - if ( idx < 0 ) // parameter error - return -1; + if ( mbg_rc_is_error( idx ) ) // parameter error + return idx; if ( cp ) // parameter found { @@ -952,7 +977,7 @@ int chk_int16_parm( const char *arg, const char *id, int16_t *p, int16_t range_m if ( ( tmp < range_min ) || ( tmp > range_max ) ) { printf( "error: %s %i out of range (%i..%i)\n", info, tmp, range_min, range_max ); - return -1; + return MBG_ERR_RANGE; } *p = tmp; @@ -1033,7 +1058,7 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) // Domain Number idx = chk_parm_name( arg, ptp_name_dom, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error { err_info = ptp_name_dom; goto fail; @@ -1050,7 +1075,7 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) // V1 Hardware compatibility flag idx = chk_parm_name( arg, ptp_name_v1, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error { err_info = ptp_name_v1; goto fail; @@ -1101,7 +1126,7 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) // GM Host idx = chk_parm_name( arg, ptp_name_gmip, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error { err_info = ptp_name_gmip; goto fail; @@ -1135,7 +1160,7 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) // GM Clock ID idx = chk_parm_name( arg, ptp_name_gmid, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error { err_info = ptp_name_gmid; goto fail; @@ -1176,7 +1201,7 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) // GM Target Port ID idx = chk_parm_name( arg, ptp_name_pid, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error { err_info = ptp_name_pid; goto fail; @@ -1255,7 +1280,7 @@ int set_ptp_cfg( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) { rc = mbg_save_all_ptp_cfg_info( dh, &all_ptp_cfg_info ); - if ( mbg_ioctl_err( rc, "mbg_save_all_ptp_cfg_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_save_all_ptp_cfg_info" ) ) return rc; } @@ -1321,7 +1346,7 @@ int set_lan_intf( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) int rc = mbg_get_ip4_settings( dh, &prv_ip4_settings ); - if ( mbg_ioctl_err( rc, "mbg_get_ip4_settings" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_ip4_settings" ) ) return rc; if ( strcmp( arg, "DHCP" ) == 0 ) @@ -1402,7 +1427,7 @@ done: // now check static configuration save: rc = mbg_set_ip4_settings( dh, &ip4_settings ); - if ( mbg_ioctl_err( rc, "mbg_set_ip4_settings" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_ip4_settings" ) ) return rc; return MBG_SUCCESS; @@ -1452,7 +1477,7 @@ int set_gps_pos( MBG_DEV_HANDLE dh, const char *gp ) rc = mbg_set_gps_pos_lla ( dh, new_pos_lla ); - if ( mbg_ioctl_err( rc, "mbg_set_gps_pos_lla" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_gps_pos_lla" ) ) return rc; printf( "The clock's receiver position has been set to lat=%+.4f, lon=%+.4f, alt=%.0fm\n", @@ -1493,7 +1518,7 @@ int set_date_time( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, { rc = mbg_get_time( dh, &u.t ); - if ( mbg_ioctl_err( rc, "mbg_get_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_time" ) ) return rc; } @@ -1579,7 +1604,7 @@ int set_date_time( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, rc = mbg_set_gps_time( dh, &ttm ); - if ( mbg_ioctl_err( rc, "mbg_set_gps_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_gps_time" ) ) return rc; } else // is not a GPS card @@ -1615,7 +1640,7 @@ int set_date_time( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, rc = mbg_set_time( dh, &u.stime ); - if ( mbg_ioctl_err( rc, "mbg_set_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_time" ) ) return rc; } @@ -1638,7 +1663,7 @@ int check_setup_receiver_info( MBG_DEV_HANDLE dh, RECEIVER_INFO *p_ri ) if ( p_ri->ticks_per_sec == 0 && p_ri->model_code == 0 ) { rc = mbg_setup_receiver_info( dh, NULL, p_ri ); - mbg_ioctl_err( rc, "mbg_setup_receiver_info" ); + mbg_cond_err_msg( rc, "mbg_setup_receiver_info" ); } return rc; @@ -1664,7 +1689,7 @@ int check_get_receiver_port_cfg( MBG_DEV_HANDLE dh, RECEIVER_PORT_CFG *p_rpcfg, ( p_rpcfg->pii[0].port_info.port_settings.parm.baud_rate == 0 ) ) { rc = mbg_get_serial_settings( dh, p_dev, p_rpcfg, p_ri ); - mbg_ioctl_err( rc, "mbg_get_serial_settings" ); + mbg_cond_err_msg( rc, "mbg_get_serial_settings" ); } if ( mbg_rc_is_success( rc ) ) @@ -1789,7 +1814,7 @@ int save_serial_settings( MBG_DEV_HANDLE dh, unsigned int port_num, const char * // load current settings and supported settings rc = mbg_get_serial_settings( dh, p_dev, &rpcfg, p_ri ); - if ( mbg_ioctl_err( rc, "mbg_get_serial_settings" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_serial_settings" ) ) return rc; @@ -1857,7 +1882,7 @@ done_parm_str: // save new parameters rc = mbg_save_serial_settings( dh, p_dev, &rpcfg, port_num ); - if ( mbg_ioctl_err( rc, "mbg_save_serial_settings" ) ) + if ( mbg_cond_err_msg( rc, "mbg_save_serial_settings" ) ) return rc; @@ -1888,7 +1913,7 @@ int check_get_pout_cfg( MBG_DEV_HANDLE dh, ALL_POUT_INFO_IDX api, RECEIVER_INFO ( api[0].pout_info.supp_modes == 0 ) ) { rc = mbg_get_gps_all_pout_info( dh, api, p_ri ); - mbg_ioctl_err( rc, "mbg_get_gps_all_pout_info" ); + mbg_cond_err_msg( rc, "mbg_get_gps_all_pout_info" ); } if ( mbg_rc_is_success( rc ) ) @@ -2011,7 +2036,7 @@ int eval_pout( MBG_DEV_HANDLE dh, const char *s, int inst_num ) int i; int rc = check_get_pout_cfg( dh, api, &ri ); - if ( mbg_ioctl_err( rc, "check_get_pout_cfg" ) ) + if ( mbg_cond_err_msg( rc, "check_get_pout_cfg" ) ) return rc; n_pout = rc; // Contains now the number of programmable pulse outputs @@ -2022,7 +2047,7 @@ int eval_pout( MBG_DEV_HANDLE dh, const char *s, int inst_num ) // Mode idx = chk_parm_name( s, pout_name_mode, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error { err_info = pout_name_mode; goto fail; @@ -2054,7 +2079,7 @@ int eval_pout( MBG_DEV_HANDLE dh, const char *s, int inst_num ) // Pulse len idx = chk_parm_name( s, pout_name_len, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error { err_info = pout_name_len; goto fail; @@ -2095,7 +2120,7 @@ int eval_pout( MBG_DEV_HANDLE dh, const char *s, int inst_num ) // "Inverted" flag idx = chk_parm_name( s, pout_name_inv, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error { err_info = pout_name_inv; goto fail; @@ -2133,7 +2158,7 @@ int eval_pout( MBG_DEV_HANDLE dh, const char *s, int inst_num ) // "Only If Sync" flag idx = chk_parm_name( s, pout_name_ois, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error { err_info = pout_name_ois; goto fail; @@ -2171,7 +2196,7 @@ int eval_pout( MBG_DEV_HANDLE dh, const char *s, int inst_num ) // "Pulse Shift" parameter idx = chk_parm_name( s, pout_name_shift, &cp ); - if ( idx < 0 ) // parameter error + if ( mbg_rc_is_error( idx ) ) // parameter error { err_info = pout_name_shift; goto fail; @@ -2267,7 +2292,7 @@ int show_pout( MBG_DEV_HANDLE dh, const OPT_HANDLER_SPEC *p_opt, const PCPS_DEV int n_pout; int rc = check_get_pout_cfg( dh, api, &ri ); - if ( mbg_ioctl_err( rc, "check_get_pout_cfg" ) ) + if ( mbg_cond_err_msg( rc, "check_get_pout_cfg" ) ) return rc; n_pout = rc; // Contains now the number of programmable pulse outputs @@ -2365,7 +2390,7 @@ int show_enable_flags( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *inf rc = mbg_get_gps_enable_flags( dh, &ef ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_enable_flags" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_gps_enable_flags" ) ) return rc; printf( "%s enable flags: ", info ); @@ -2433,7 +2458,7 @@ int set_enable_flags( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev rc = mbg_get_gps_enable_flags( dh, &ef ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_enable_flags" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_gps_enable_flags" ) ) return rc; // Scan input parameters @@ -2466,7 +2491,7 @@ int set_enable_flags( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev save: rc = mbg_set_gps_enable_flags( dh, &ef ); - if ( mbg_ioctl_err( rc, "mbg_set_gps_enable_flags" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_gps_enable_flags" ) ) return rc; return MBG_SUCCESS; @@ -2480,7 +2505,7 @@ int send_gps_cmd( MBG_DEV_HANDLE dh, ushort cmd ) { int rc = mbg_set_gps_cmd( dh, &cmd ); - if ( mbg_ioctl_err( rc, "mbg_set_gps_cmd" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_gps_cmd" ) ) return rc; printf( "NOTE: the command code %u has been sent to the GPS clock.\n", cmd ); @@ -2497,7 +2522,7 @@ int show_ant_cable_len( MBG_DEV_HANDLE dh, const char *info ) ANT_CABLE_LEN len; int rc = mbg_get_gps_ant_cable_len( dh, &len ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_ant_cable_len" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_gps_ant_cable_len" ) ) return rc; printf( "%s antenna cable length: %u meter(s)", info, len ); @@ -2514,7 +2539,7 @@ int set_ant_cable_len( MBG_DEV_HANDLE dh, const char *s ) ANT_CABLE_LEN len = (ANT_CABLE_LEN) atol( s ); // TODO check range ? int rc = mbg_set_gps_ant_cable_len( dh, &len ); - if ( mbg_ioctl_err( rc, "mbg_set_gps_ant_cable_len" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_gps_ant_cable_len" ) ) return rc; return MBG_SUCCESS; @@ -2538,7 +2563,7 @@ int set_event_time( MBG_DEV_HANDLE dh, const char *s ) rc = mbg_set_event_time( dh, &event_ts ); - if ( mbg_ioctl_err( rc, "mbg_set_event_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_event_time" ) ) return rc; mbg_snprint_hr_tstamp( ws, sizeof( ws ), &event_ts, 0, 0 ); // raw timestamp? @@ -2563,7 +2588,7 @@ int get_n_time_scale( MBG_DEV_HANDLE dh, MBG_TIME_SCALE_INFO *p_tsci ) if ( rc == MBG_ERR_NOT_SUPP_BY_DEV ) printf( "This device does not support a configurable time scale.\n" ); else - mbg_ioctl_err( rc, "mbg_chk_dev_has_time_scale" ); + mbg_cond_err_msg( rc, "mbg_chk_dev_has_time_scale" ); goto done; } @@ -2591,7 +2616,7 @@ int show_time_scale( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *info rc = mbg_get_time_scale_info( dh, &tsci ); - if ( mbg_ioctl_err( rc, "mbg_get_time_scale_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_time_scale_info" ) ) return rc; printf( "%s time scale index: %u (%s)", info, tsci.settings.scale, @@ -2613,7 +2638,7 @@ int set_time_scale( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) rc = mbg_get_time_scale_info( dh, &tsci ); - if ( mbg_ioctl_err( rc, "mbg_get_time_scale_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_time_scale_info" ) ) return rc; @@ -2635,7 +2660,7 @@ int set_time_scale( MBG_DEV_HANDLE dh, const char *arg, const PCPS_DEV *p_dev ) rc = mbg_set_time_scale_settings( dh, &tsci.settings ); - if ( mbg_ioctl_err( rc, "mbg_set_time_scale_settings" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_time_scale_settings" ) ) return rc; return MBG_SUCCESS; @@ -2857,20 +2882,20 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p const char *stime = NULL; const char *cp; int i; - int rc = 0; + int rc = MBG_SUCCESS; int error_occurred = 0; must_print_usage = 0; for ( i = 1; i < argc; i++ ) { - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) error_occurred = 1; - if ( rc > 0 ) + if ( rc == RC_USAGE ) must_print_usage = 1; - rc = 0; + rc = MBG_SUCCESS; if ( ( strcmp( argv[i], "-?" ) == 0 ) || ( strcmp( argv[i], "-h" ) == 0 ) || @@ -3089,7 +3114,7 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p { rc = set_enable_flags( dh, ++cp, p_dev ); - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) { printf( "*** Warning: invalid enable flag parameter syntax\n" ); must_print_usage = 1; @@ -3123,7 +3148,7 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p { rc = set_time_scale( dh, ++cp, p_dev ); - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) { must_print_usage = 1; continue; @@ -3156,7 +3181,7 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p { rc = set_tzdl_offs( dh, ++cp ); - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) { must_print_usage = 1; continue; @@ -3171,6 +3196,39 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p } + cp = str_parm_p( argv[i], "SYNTH" ); + + if ( cp ) + { + if ( p_dev ) + { + char *info = "Current"; + + if ( !_pcps_has_synth( p_dev ) ) + { + err_msg( p_dev, no_synth ); + continue; + } + + if ( *cp == '=' ) + { + rc = set_synth( dh, ++cp ); + + if ( mbg_rc_is_error( rc ) ) + { + must_print_usage = 1; + continue; + } + + info = "New"; + } + + show_synth( dh, info ); + } + continue; + } + + cp = str_parm_p( argv[i], "LAN" ); if ( cp ) @@ -3189,7 +3247,7 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p { rc = set_lan_intf( dh, ++cp, p_dev ); - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) { must_print_usage = 1; continue; @@ -3222,7 +3280,7 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p { rc = set_ptp_cfg( dh, ++cp, p_dev ); - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) continue; info = "New"; @@ -3251,7 +3309,7 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p { rc = set_ant_cable_len( dh, ++cp ); - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) { must_print_usage = 1; continue; @@ -3277,9 +3335,9 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p if ( *cp == '=' ) rc = set_event_time( dh, ++cp ); else - rc = -1; + rc = MBG_ERR_PARM_FMT; - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) printf( "*** Warning: invalid event time parameter\n" ); } else @@ -3303,13 +3361,18 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p if ( p_dev ) if ( sdate || stime ) + { rc = set_date_time( dh, p_dev, sdate, stime ); + if ( mbg_rc_is_error( rc ) ) + error_occurred = 1; + } + if ( error_occurred ) - return -1; + return MBG_ERR_GENERIC; if ( must_print_usage ) - return 1; + return RC_USAGE; return MBG_SUCCESS; @@ -3324,6 +3387,7 @@ int main( int argc, char *argv[] ) PCPS_DEV dev = { { 0 } }; PCPS_DEV *pdev = NULL; MBG_DEV_HANDLE dh = MBG_INVALID_DEV_HANDLE; + MBG_DEV_FN tmp_dev_fn; int rc; mbg_print_program_info( pname, MBG_MICRO_VERSION, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR ); @@ -3336,31 +3400,17 @@ int main( int argc, char *argv[] ) // pass a device handle, so commands are not evaluated. check_cmd_line( argc, argv, dh, NULL, &ri, &rpcfg ); - if ( dev_name ) - { - #if defined( MBG_TGT_POSIX ) && !defined( MBG_TGT_QNX_NTO ) - dh = open( dev_name, O_RDWR ); - #else - dh = mbg_open_device_by_name( dev_name, MBG_MATCH_MODEL ); - #endif - } - else - dh = mbg_open_device( 0 ); // open first device found - - if ( dh == MBG_INVALID_DEV_HANDLE ) - { - //##++++++++++++++++++++++ - if ( dev_name ) - fprintf( stderr, "%s: ", dev_name ); + rc = mbg_open_device_by_param( &dh, dev_name, 0, 0, + tmp_dev_fn, sizeof( tmp_dev_fn ), 0 ); - perror( "Unable to open device" ); + if ( mbg_rc_is_error( rc ) ) goto fail; - } + // get information about the device - rc = mbg_get_show_dev_info( dh, dev_name, &dev ); + rc = mbg_get_show_dev_info( dh, NULL, &dev ); - if ( rc < 0 ) + if ( mbg_rc_is_error( rc ) ) goto fail; @@ -3378,13 +3428,13 @@ int main( int argc, char *argv[] ) mbg_close_device( &dh ); - return 0; + return MBG_EXIT_CODE_SUCCESS; show_usage: usage( dh, pdev, &ri, &rpcfg ); - return 1; + return MBG_EXIT_CODE_USAGE; fail: - return 2; + return MBG_EXIT_CODE_FAIL; } diff --git a/mbgfasttstamp/Makefile b/mbgfasttstamp/Makefile index 6628bd3..4eb3b9c 100755 --- a/mbgfasttstamp/Makefile +++ b/mbgfasttstamp/Makefile @@ -1,23 +1,16 @@ ######################################################################### # -# $Id: Makefile 1.2.1.7 2016/07/15 14:06:51 martin TEST $ +# $Id: Makefile 1.3 2017/07/05 18:50:00 martin REL_M $ # # Description: # Makefile for mbgfasttstamp. # # ----------------------------------------------------------------------- # $Log: Makefile $ -# Revision 1.2.1.7 2016/07/15 14:06:51 martin -# Added new module timeutil.o. -# Revision 1.2.1.6 2015/08/31 14:30:51 martin -# Revision 1.2.1.5 2015/07/14 15:07:20 martin -# Added object module mbgerror.o. -# Revision 1.2.1.4 2014/04/28 13:19:51 martin -# Added module cfg_hlp.o. -# Revision 1.2.1.3 2011/11/23 17:58:59 martin -# Revision 1.2.1.2 2010/08/30 09:05:23 martin -# Revision 1.2.1.1 2010/08/30 08:21:01 martin +# Revision 1.3 2017/07/05 18:50:00 martin +# Updated list of object files and use top level +# Makefile properly. # Revision 1.2 2009/07/24 10:31:16 martin # Moved declarations to a common file which is now included. # Revision 1.1 2008/12/22 11:45:01 martin diff --git a/mbgfasttstamp/mbgfasttstamp.c b/mbgfasttstamp/mbgfasttstamp.c index daad89b..ea5e5a3 100755 --- a/mbgfasttstamp/mbgfasttstamp.c +++ b/mbgfasttstamp/mbgfasttstamp.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgfasttstamp.c 1.6.1.14 2017/01/27 12:06:34 martin TEST $ + * $Id: mbgfasttstamp.c 1.7 2017/07/05 18:55:22 martin REL_M $ * * Description: * Main file for mbgfasttstamp program which demonstrates how to access @@ -9,29 +9,16 @@ * * ----------------------------------------------------------------------- * $Log: mbgfasttstamp.c $ - * Revision 1.6.1.14 2017/01/27 12:06:34 martin - * Don't use deprecated API call. - * Revision 1.6.1.13 2016/10/20 14:08:03 martin - * Parameters -u and -s imply -c. - * Revision 1.6.1.12 2015/10/26 13:50:10 martin - * Revision 1.6.1.11 2014/10/28 15:38:44Z martin - * Revision 1.6.1.10 2013/07/22 16:25:10Z martin - * Revision 1.6.1.9 2013/07/11 08:29:29 martin - * Account for modified function call parameter list. - * 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. - * Account for modified library functions which can now - * optionally print the raw (hex) HR time stamp. - * Started to support signal handler to catch CTRL-C. - * Revision 1.6.1.3 2011/01/28 12:04:07 martin - * Revision 1.6.1.2 2011/01/28 11:51:13 martin - * Revision 1.6.1.1 2011/01/28 11:17:00 martin + * Revision 1.7 2017/07/05 18:55:22 martin + * New way to maintain version information. + * Support build under Windows. * Abort if MM access not supported on the target OS. + * Support signal handler to catch CTRL-C. + * Added options to sleep between calls. + * Parameters -u and -s imply -c. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. * Revision 1.6 2010/05/21 12:54:33 martin * Print warning if no cycles supported on the target platform * and thus latencies can not be computed. @@ -97,8 +84,8 @@ int show_fast_hr_timestamp( MBG_DEV_HANDLE dh ) int rc = read_raw ? mbg_get_fast_hr_timestamp( dh, &ts ) : mbg_get_fast_hr_timestamp_comp( dh, &ts, &hns_latency ); - if ( mbg_ioctl_err( rc, "mbg_get_fast_hr_timestamp..." ) ) - goto fail; + if ( mbg_cond_err_msg( rc, "mbg_get_fast_hr_timestamp..." ) ) + return rc; mbg_print_hr_timestamp( &ts, hns_latency, NULL, read_raw, 1 ); // raw timestamp? @@ -117,10 +104,7 @@ int show_fast_hr_timestamp( MBG_DEV_HANDLE dh ) // if this_loops is < 0 then loop forever } - return 0; - -fail: - return -1; + return MBG_SUCCESS; } // show_fast_hr_timestamp @@ -150,8 +134,8 @@ int show_fast_hr_timestamp_burst( MBG_DEV_HANDLE dh ) { int rc = mbg_get_fast_hr_timestamp( dh, &ts[i] ); - if ( mbg_ioctl_err( rc, "mbg_get_fast_hr_timestamp" ) ) - goto fail; + if ( mbg_cond_err_msg( rc, "mbg_get_fast_hr_timestamp" ) ) + return rc; } } else @@ -159,8 +143,8 @@ int show_fast_hr_timestamp_burst( MBG_DEV_HANDLE dh ) { int rc = mbg_get_fast_hr_timestamp_comp( dh, &ts[i], &hns_latency[i] ); - if ( mbg_ioctl_err( rc, "mbg_get_fast_hr_timestamp_comp" ) ) - goto fail; + if ( mbg_cond_err_msg( rc, "mbg_get_fast_hr_timestamp_comp" ) ) + return rc; } for ( i = 0; i < this_loops; i++ ) @@ -169,11 +153,7 @@ int show_fast_hr_timestamp_burst( MBG_DEV_HANDLE dh ) mbg_print_hr_timestamp( &ts[i], hns_latency[i], p_prv_ts, read_raw, 0 ); // raw timestamp? } - return 0; - - -fail: - return -1; + return MBG_SUCCESS; } // show_fast_hr_timestamp_burst @@ -186,12 +166,9 @@ int do_mbgfasttstamp( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) if ( mbg_rc_is_error( rc ) ) { - if ( rc == MBG_ERR_NOT_SUPP_BY_DEV ) - printf( "This device does not support fast (memory mapped) time stamps.\n" ); - else - mbg_ioctl_err( rc, "mbg_chk_dev_has_fast_hr_timestamp" ); - - goto done; + mbg_cond_err_msg_info( rc, "mbg_chk_dev_has_fast_hr_timestamp", + "support fast (memory mapped) time stamps" ); + return rc; } if ( burst_read ) @@ -199,11 +176,12 @@ int do_mbgfasttstamp( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) else show_fast_hr_timestamp( dh ); -done: - return rc; + return MBG_SUCCESS; } // do_mbgfasttstamp +static MBG_DEV_HANDLER_FNC do_mbgfasttstamp; + static /*HDR*/ @@ -277,7 +255,7 @@ int main( int argc, char *argv[] ) if ( must_print_usage ) { usage(); - return 1; + return MBG_EXIT_CODE_USAGE; } #if !MBG_TGT_SUPP_MEM_ACC @@ -297,12 +275,8 @@ int main( int argc, char *argv[] ) printf( "\n" ); #endif - // The function below checks which devices have been specified - // on the command, and for each device - // - tries to open the device - // - shows basic device info - // - calls the specified callback function - rc = mbg_check_devices( argc, argv, optind, do_mbgfasttstamp, 0 ); + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbgfasttstamp, 0 ); - return abs( rc ); + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; } diff --git a/mbggpscap/Makefile b/mbggpscap/Makefile index f18ee1c..7f511e3 100755 --- a/mbggpscap/Makefile +++ b/mbggpscap/Makefile @@ -1,24 +1,16 @@ ######################################################################### # -# $Id: Makefile 1.7.1.7 2016/07/15 14:06:51 martin TEST $ +# $Id: Makefile 1.8 2017/07/05 18:50:00 martin REL_M $ # # Description: # Makefile for mbggpscap. # # ----------------------------------------------------------------------- # $Log: Makefile $ -# Revision 1.7.1.7 2016/07/15 14:06:51 martin -# Added new module timeutil.o. -# Revision 1.7.1.6 2015/08/31 14:26:13 martin -# Revision 1.7.1.5 2015/07/14 15:07:20 martin -# Added object module mbgerror.o. -# Revision 1.7.1.4 2014/04/28 13:19:51 martin -# Added module cfg_hlp.o. -# Revision 1.7.1.3 2011/09/26 16:01:46 martin -# Updated for use with latest base Makefile. -# Revision 1.7.1.2 2010/08/30 09:05:23 martin -# Revision 1.7.1.1 2010/08/30 08:21:32 martin +# Revision 1.8 2017/07/05 18:50:00 martin +# Updated list of object files and use top level +# Makefile properly. # Revision 1.7 2009/07/24 10:31:16 martin # Moved declarations to a common file which is now included. # Revision 1.6 2008/12/22 11:56:58 martin diff --git a/mbggpscap/mbggpscap.c b/mbggpscap/mbggpscap.c index 4a8205d..80c591e 100755 --- a/mbggpscap/mbggpscap.c +++ b/mbggpscap/mbggpscap.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbggpscap.c 1.10.1.13 2016/12/09 10:16:32 martin TEST $ + * $Id: mbggpscap.c 1.11 2017/07/05 18:59:14 martin REL_M $ * * Description: * Main file for mbggpscap program which demonstrates how to access @@ -13,32 +13,21 @@ * * ----------------------------------------------------------------------- * $Log: mbggpscap.c $ - * Revision 1.10.1.13 2016/12/09 10:16:32 martin - * Enhanced interval checking and error reporting. - * New command line option to clear buffer. - * Revision 1.10.1.12 2016/11/04 12:29:39 martin - * *** empty log message *** - * Revision 1.10.1.11 2015/10/26 13:50:42 martin - * Revision 1.10.1.10 2013/07/22 16:25:10Z martin - * Revision 1.10.1.9 2013/07/11 08:29:29 martin - * Account for modified function call parameter list. - * 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. - * Fixed a bug when displaying the capture event status. TTM and PCPS_HR_TIME - * are using different sets of status flags. - * Revision 1.10.1.4 2011/07/05 15:35:54 martin - * Modified version handling. - * Revision 1.10.1.3 2011/07/05 14:35:18 martin + * Revision 1.11 2017/07/05 18:59:14 martin * New way to maintain version information. - * Revision 1.10.1.2 2010/11/12 12:27:17 martin + * Support build under Windows. + * Improved code execution paths. * Improved reading capture events arriving at a high rate. * Support validation of capture signals arriving at a constant rate. - * Revision 1.10.1.1 2010/03/10 16:42:33 martin - * Improved code execution paths. + * Fixed a bug when displaying the capture event status. TTM and + * PCPS_HR_TIME are using different sets of status flags. + * New option -r which displays raw timestamps and raw status. + * New option -o which forces usage of old API. + * New command line option to clear buffer. + * Account for PCPS_HRT_BIN_FRAC_SCALE renamed to MBG_FRAC32_UNITS_PER_SEC. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. * Revision 1.10 2009/09/29 15:02:15 martin * Updated version number to 3.4.0. * Revision 1.9 2009/07/24 09:50:08 martin @@ -119,7 +108,7 @@ void show_ucap_event( const PCPS_HR_TIME *ucap ) int jitter_exceeded; double abs_delta; double d = ucap->tstamp.sec - prv_ucap.tstamp.sec; - d += ( (double) ucap->tstamp.frac - prv_ucap.tstamp.frac ) / PCPS_HRT_BIN_FRAC_SCALE; + d += ( (double) ucap->tstamp.frac - prv_ucap.tstamp.frac ) / MBG_FRAC32_UNITS_PER_SEC; printf( " %+.6f", d ); @@ -197,7 +186,7 @@ void check_serial_mode( MBG_DEV_HANDLE dh ) // read the clock's current port settings int rc = mbg_get_gps_port_parm( dh, &port_parm ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_port_parm" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_gps_port_parm" ) ) return; @@ -219,10 +208,10 @@ void check_serial_mode( MBG_DEV_HANDLE dh ) rc = mbg_set_gps_port_parm( dh, &port_parm ); -// ### TODO FIXME The call above requires root permissions, so -// print a more appropriate message if the cal failed. + // ### TODO FIXME The call above requires root permissions, so + // print a more appropriate message if the call failed. - if ( mbg_ioctl_err( rc, "mbg_set_gps_port_parm" ) ) + if ( mbg_cond_err_msg( rc, "mbg_set_gps_port_parm" ) ) return; printf( "NOTE: the clock's serial port mode has been changed.\n" ); @@ -315,7 +304,7 @@ int do_mbggpscap( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) rc = mbg_get_ucap_event( dh, &ucap_event ); - if ( mbg_ioctl_err( rc, "mbg_get_ucap_event" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_ucap_event" ) ) break; // an error has occurred // If a user capture event has been read then it @@ -341,7 +330,7 @@ int do_mbggpscap( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) rc = mbg_get_gps_ucap( dh, &ucap_ttm ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_ucap" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_gps_ucap" ) ) break; // an error has occurred @@ -367,6 +356,8 @@ int do_mbggpscap( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) } // do_mbggpscap +static MBG_DEV_HANDLER_FNC do_mbggpscap; + static /*HDR*/ @@ -441,7 +432,7 @@ int main( int argc, char *argv[] ) if ( must_print_usage ) { usage(); - return 1; + return MBG_EXIT_CODE_USAGE; } if ( nom_cap_intv != 0.0 ) @@ -450,12 +441,8 @@ int main( int argc, char *argv[] ) printf( "Maximum allowed capture jitter: %f s\n", max_cap_jitter ); } - // The function below checks which devices have been specified - // on the command, and for each device - // - tries to open the device - // - shows basic device info - // - calls the specified callback function - rc = mbg_check_devices( argc, argv, optind, do_mbggpscap, 0 ); + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbggpscap, 0 ); - return abs( rc ); + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; } diff --git a/mbghrtime/Makefile b/mbghrtime/Makefile index 7ed855c..48e5a14 100755 --- a/mbghrtime/Makefile +++ b/mbghrtime/Makefile @@ -1,24 +1,16 @@ ######################################################################### # -# $Id: Makefile 1.7.1.7 2016/07/15 14:06:51 martin TEST $ +# $Id: Makefile 1.8 2017/07/05 18:50:00 martin REL_M $ # # Description: # Makefile for mbghrtime. # # ----------------------------------------------------------------------- # $Log: Makefile $ -# Revision 1.7.1.7 2016/07/15 14:06:51 martin -# Added new module timeutil.o. -# Revision 1.7.1.6 2015/08/31 14:27:38 martin -# Revision 1.7.1.5 2015/07/14 15:07:20 martin -# Added object module mbgerror.o. -# Revision 1.7.1.4 2014/04/28 13:19:51 martin -# Added module cfg_hlp.o. -# Revision 1.7.1.3 2011/09/26 16:02:55 martin -# Updated for use with latest base Makefile. -# Revision 1.7.1.2 2010/08/30 09:05:23 martin -# Revision 1.7.1.1 2010/08/30 08:21:39 martin +# Revision 1.8 2017/07/05 18:50:00 martin +# Updated list of object files and use top level +# Makefile properly. # Revision 1.7 2009/07/24 10:31:16 martin # Moved declarations to a common file which is now included. # Revision 1.6 2008/12/22 11:56:59 martin diff --git a/mbghrtime/mbghrtime.c b/mbghrtime/mbghrtime.c index 7d4e8c8..2b0f4cd 100755 --- a/mbghrtime/mbghrtime.c +++ b/mbghrtime/mbghrtime.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbghrtime.c 1.11.1.16 2016/10/20 14:08:04 martin TEST $ + * $Id: mbghrtime.c 1.12 2017/07/05 19:02:13 martin REL_M $ * * Description: * Main file for mbghrtime program which demonstrates how to access @@ -10,32 +10,15 @@ * * ----------------------------------------------------------------------- * $Log: mbghrtime.c $ - * Revision 1.11.1.16 2016/10/20 14:08:04 martin - * Parameters -u and -s imply -c. - * Revision 1.11.1.15 2016/05/30 15:12:43 martin - * *** empty log message *** - * Revision 1.11.1.14 2015/10/26 14:17:20 martin - * Revision 1.11.1.13 2014/10/28 15:38:44Z martin - * Revision 1.11.1.12 2013/07/22 16:25:10Z martin - * Revision 1.11.1.11 2013/07/11 08:29:29 martin - * Account for modified function call parameter list. - * 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(). - * Revision 1.11.1.7 2011/09/07 15:08:55 martin - * Account for modified library functions which can now - * optionally print the raw (hex) HR time stamp. - * Revision 1.11.1.6 2011/07/05 15:35:54 martin - * Modified version handling. - * Revision 1.11.1.5 2011/07/05 14:35:18 martin + * Revision 1.12 2017/07/05 19:02:13 martin * New way to maintain version information. - * Revision 1.11.1.4 2011/01/28 12:04:08 martin - * Revision 1.11.1.3 2011/01/28 11:52:51 martin - * Revision 1.11.1.2 2011/01/28 11:51:13 martin - * Revision 1.11.1.1 2011/01/28 11:17:33 martin - * Starrted to support raw and burst. + * Support build under Windows. + * Support raw and burst mode. + * New options -s, -u, -v. + * Parameters -u and -s imply -c. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. * Revision 1.11 2010/05/21 12:54:33 martin * Print warning if no cycles supported on the target platform * and thus latencies can not be computed. @@ -116,7 +99,7 @@ int show_hr_timestamp( MBG_DEV_HANDLE dh ) int rc = read_raw ? mbg_get_hr_time( dh, &ht ) : mbg_get_hr_time_comp( dh, &ht, &hns_latency ); - if ( mbg_ioctl_err( rc, "mbg_get_hr_time_..." ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_hr_time_..." ) ) goto fail; mbg_print_hr_time( &ht, hns_latency, p, read_raw, verbose, verbose ); @@ -172,7 +155,7 @@ int show_hr_timestamp_burst( MBG_DEV_HANDLE dh ) { int rc = mbg_get_hr_time( dh, &ht[i] ); - if ( mbg_ioctl_err( rc, "mbg_get_hr_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_hr_time" ) ) goto fail; } } @@ -181,7 +164,7 @@ int show_hr_timestamp_burst( MBG_DEV_HANDLE dh ) { int rc = mbg_get_hr_time_comp( dh, &ht[i], &hns_latency[i] ); - if ( mbg_ioctl_err( rc, "mbg_get_hr_time_comp" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_hr_time_comp" ) ) goto fail; } @@ -211,7 +194,7 @@ int do_mbghrtime( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) if ( rc == MBG_ERR_NOT_SUPP_BY_DEV ) // ### TODO not_supp printf( "High resolution time not supported by this device.\n" ); else - mbg_ioctl_err( rc, "mbg_chk_dev_has_hr_time" ); + mbg_cond_err_msg( rc, "mbg_chk_dev_has_hr_time" ); goto done; } @@ -226,6 +209,8 @@ done: } // do_mbghrtime +static MBG_DEV_HANDLER_FNC do_mbghrtime; + static /*HDR*/ @@ -303,7 +288,7 @@ int main( int argc, char *argv[] ) if ( must_print_usage ) { usage(); - return 1; + return MBG_EXIT_CODE_USAGE; } @@ -320,12 +305,8 @@ int main( int argc, char *argv[] ) #endif - // The function below checks which devices have been specified - // on the command, and for each device - // - tries to open the device - // - shows basic device info - // - calls the specified callback function - rc = mbg_check_devices( argc, argv, optind, do_mbghrtime, 0 ); + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbghrtime, 0 ); - return abs( rc ); + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; } diff --git a/mbgirigcfg/Makefile b/mbgirigcfg/Makefile index 013fb1e..9639209 100755 --- a/mbgirigcfg/Makefile +++ b/mbgirigcfg/Makefile @@ -1,24 +1,16 @@ ######################################################################### # -# $Id: Makefile 1.5.1.7 2016/07/15 14:06:52 martin TEST $ +# $Id: Makefile 1.6 2017/07/05 18:50:01 martin REL_M $ # # Description: # Makefile for mbgirigcfg. # # ----------------------------------------------------------------------- # $Log: Makefile $ -# Revision 1.5.1.7 2016/07/15 14:06:52 martin -# Added new module timeutil.o. -# Revision 1.5.1.6 2015/08/31 14:23:34 martin -# Revision 1.5.1.5 2015/07/14 15:07:20 martin -# Added object module mbgerror.o. -# Revision 1.5.1.4 2014/04/28 13:19:51 martin -# Added module cfg_hlp.o. -# Revision 1.5.1.3 2011/09/26 16:04:01 martin -# Updated for use with latest base Makefile. -# Revision 1.5.1.2 2010/08/30 09:05:23 martin -# Revision 1.5.1.1 2010/08/30 08:21:45 martin +# Revision 1.6 2017/07/05 18:50:01 martin +# Updated list of object files and use top level +# Makefile properly. # Revision 1.5 2009/07/24 10:31:17 martin # Moved declarations to a common file which is now included. # Revision 1.4 2008/12/22 11:56:59 martin diff --git a/mbgirigcfg/mbgirigcfg.c b/mbgirigcfg/mbgirigcfg.c index 7f1cdd1..c3a89c8 100755 --- a/mbgirigcfg/mbgirigcfg.c +++ b/mbgirigcfg/mbgirigcfg.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgirigcfg.c 1.10.1.21 2015/10/26 13:52:50 martin TEST $ + * $Id: mbgirigcfg.c 1.11 2017/07/05 19:05:27 martin REL_M $ * * Description: * Main file for the mbgirigcfg program which can be used to configure @@ -10,40 +10,19 @@ * * ----------------------------------------------------------------------- * $Log: mbgirigcfg.c $ - * Revision 1.10.1.21 2015/10/26 13:52:50 martin - * Revision 1.10.1.20 2015/08/27 16:34:10Z martin - * Use safe string functions. - * Revision 1.10.1.19 2014/10/14 10:05:24 martin - * Revision 1.10.1.18 2014/08/27 10:50:59Z martin - * Support specification of minutes for ref offset. - * Revision 1.10.1.17 2013/07/22 16:25:11 martin - * Revision 1.10.1.16 2013/07/11 08:29:30 martin - * Account for modified function call parameter list. - * Revision 1.10.1.15 2013/07/10 13:00:51 martin - * Removed obsolete include to fix build under Windows. - * Revision 1.10.1.14 2012/04/11 16:12:43Z 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. - * Revision 1.10.1.10 2011/07/06 14:53:50 martin - * Revision 1.10.1.9 2011/07/05 15:35:54 martin - * Modified version handling. - * Revision 1.10.1.8 2011/07/05 14:35:18 martin + * Revision 1.11 2017/07/05 19:05:27 martin * New way to maintain version information. - * Revision 1.10.1.7 2011/07/05 12:24:58 martin - * Revision 1.10.1.6 2011/07/04 10:30:29 martin + * Support build under Windows. + * New parameter -i to let incoming TFOM flag be ignored. + * Accept parameter -? to print usage. * Use getopt() for option processing. * Support multiple devices. - * Revision 1.10.1.5 2011/07/01 13:49:47 martin - * bug fixes. - * Revision 1.10.1.4 2011/02/02 12:28:44 martin - * Revision 1.10.1.3 2010/08/30 08:22:24 martin - * Revision 1.10.1.2 2010/08/19 13:57:42 martin - * Revision 1.10.1.1 2010/08/19 11:26:12 martin - * Accept parameter -? to print usage. - * New parameter -i to let incoming TFOM flag be ignored. + * New parameter -X which set ref offs to 'unconfigured'. + * Support specification of minutes for ref offset. + * Use safe string functions. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. * Revision 1.10 2009/09/29 15:02:15 martin * Updated version number to 3.4.0. * Revision 1.9 2009/07/24 09:50:08 martin @@ -214,7 +193,7 @@ void print_cfg_rx( const char *info, const char *msg ) { int idx = irig_rx_info.settings.icode; char ws[16]; - char *cp = NULL; + const char *cp = NULL; printf( "%s %s configuration:\n", info, msg ); @@ -317,7 +296,7 @@ void set_new_ref_offs( char *s ) // expected format: [-]hh[:mm] // In case of e.g. "-0:30" conversion of the first part "-0" would yield - // 0 and thus the sign would get lost, so we check the sign explicitely. + // 0 and thus the sign would get lost, so we check the sign explicitly. if ( *cp == '-' ) is_negative = 1; @@ -741,7 +720,7 @@ int do_mbgirigcfg( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) rc = save_cfg( dh, p_dev ); - if ( mbg_ioctl_err( rc, "save IRIG configuration" ) ) + if ( mbg_cond_err_msg( rc, "save IRIG configuration" ) ) goto done; } else @@ -760,6 +739,8 @@ done: } // do_mbgirigcfg +static MBG_DEV_HANDLER_FNC do_mbgirigcfg; + int main( int argc, char *argv[] ) @@ -776,23 +757,20 @@ int main( int argc, char *argv[] ) if ( must_print_usage ) { usage(); - return 1; + return MBG_EXIT_CODE_USAGE; } + // We work with copies of the arguments here since the arguments + // are evaluated once more for each device. glb_argc = argc; glb_argv = argv; - - // The function below checks which devices have been specified - // on the command, and for each device - // - tries to open the device - // - shows basic device info - // - calls the specified callback function - rc = mbg_check_devices( glb_argc, glb_argv, optind, do_mbgirigcfg, 0 ); + // Handle each of the specified devices. + rc = mbg_handle_devices( glb_argc, glb_argv, optind, do_mbgirigcfg, 0 ); if ( must_print_help_info ) printf( "For help type \"%s -h\"\n\n", pname ); - return abs( rc ); + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; } diff --git a/mbglib/bsd/rsrc_bsd.c b/mbglib/bsd/rsrc_bsd.c index a1b14d1..1f81e6f 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.2 2017/07/06 09:05:19 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,8 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: rsrc_bsd.c $ - * Revision 1.1.1.1 2011/02/07 15:28:32 martin - * Removed obsolete code; more cleanup required. + * Revision 1.2 2017/07/06 09:05:19 martin + * Removed obsolete code. + * Cleanup. * Revision 1.1 2011/01/26 16:09:33 martin * Initial revision. * @@ -22,48 +23,16 @@ #undef _RSRC_BSD -// extern const char *pcps_driver_name; - - -#if 1 //##++ ||defined( KERNEL_VERSION ) && ( LINUX_VERSION_CODE < KERNEL_VERSION( 2, 6, 0 ) ) - - // check_region(), request_region(), and release_region() used in 2.2.x and - // maybe early 2.4.x kernels have been replaced by more versatile functions. - // Additionally, there have been defined some macros with the names - // of the old functions, but calling the new functions. Those macros are still - // supported by early 2.6.x kernels, but may not be supported anymore in the future. - // So if those macros don't exist then only the old functions can be used and we - // use some macros with the new names and call the old functions. - - #if !defined( request_region ) - #define __check_region( _rsrc, _start, _n ) \ - check_region( (_start), (_n) ) - - #define __request_region( _rsrc, _start, _n, _name ) \ - request_region( (_start), (_n), (_name) ) - - #define __release_region( _rsrc, _start, _n ) \ - release_region( (_start), (_n) ) - #endif - -#endif - - /*HDR*/ int rsrc_alloc_ports( ushort port, ushort n, ushort decode_width ) { -#if 0 //##++ - int rc = __check_region( &ioport_resource, port, n ); - - if ( rc < 0 ) - return( rc ); + // Nothing to do; just avoid "unused variable" warnings + (void) port; + (void) n; + (void) decode_width; - - __request_region( &ioport_resource, port, n, pcps_driver_name ); -#endif - - return 0; + return 0; // success } // rsrc_alloc_ports @@ -72,11 +41,10 @@ int rsrc_alloc_ports( ushort port, ushort n, ushort decode_width ) /*HDR*/ void rsrc_dealloc_ports( ushort port, ushort n ) { -#if 0 //##++ - __release_region( &ioport_resource, port, n ); -#endif + // Nothing to do; just avoid "unused variable" warnings + (void) port; + (void) n; } // rsrc_dealloc_ports - diff --git a/mbglib/common/amccdefs.h b/mbglib/common/amccdefs.h index 1d68cbe..3aeba78 100755 --- a/mbglib/common/amccdefs.h +++ b/mbglib/common/amccdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: amccdefs.h 1.2 2007/06/06 10:16:53 martin REL_M $ + * $Id: amccdefs.h 1.3 2017/05/10 15:21:33 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: amccdefs.h $ + * Revision 1.3 2017/05/10 15:21:33 martin + * Tiny cleanup. * Revision 1.2 2007/06/06 10:16:53 martin * Moved some IRQ bit masks here. * Revision 1.1 2000/07/20 09:19:39Z MARTIN @@ -33,6 +35,10 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + // The following operation registers are implemented // in the S5933. The registers can be accessed via port @@ -88,12 +94,6 @@ #undef _ext -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/cfg_hlp.c b/mbglib/common/cfg_hlp.c index b6581ad..4a9c674 100755 --- a/mbglib/common/cfg_hlp.c +++ b/mbglib/common/cfg_hlp.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: cfg_hlp.c 1.1.1.85 2017/04/11 14:47:08 martin TEST $ + * $Id: cfg_hlp.c 1.2 2017/07/05 12:17:38 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,165 +10,20 @@ * * ----------------------------------------------------------------------- * $Log: cfg_hlp.c $ - * Revision 1.1.1.85 2017/04/11 14:47:08 martin - * Revision 1.1.1.84 2017/04/06 09:16:16Z thomas-b - * mbg_snprint_revision is not preliminary any longer - * Revision 1.1.1.83 2017/03/27 10:37:18 thomas-b - * Added ALL_PTP_V1_COMMON_DATASETS and the appropriate free function - * Revision 1.1.1.82 2017/03/22 09:07:52 thomas-b - * Added function get_io_port_type_info_idx - * Revision 1.1.1.81 2017/03/02 15:29:27 thomas-b - * Adapted free_all_ntp_cfg_info for new ALL_NTP_CFG_INFO structure - * Revision 1.1.1.80 2017/02/28 15:24:27 gregoire - * peer strucutre in ALL_NTP_CFG_INFO renamed - * Revision 1.1.1.79 2017/02/24 09:38:25 philipp - * Do not use fixed buffers for monitorung event info and status - * Revision 1.1.1.78 2017/02/22 14:28:57 martin - * Fixed some warnings from clang compiler. - * Revision 1.1.1.77 2017/02/22 11:40:17 martin - * Account for preliminary code. - * Revision 1.1.1.76 2017/02/21 15:51:40 thomas-b - * Added ALL_MONITORING_STATUS and free function and extended ALL_MONITORING_INFO by events - * Revision 1.1.1.75 2017/02/16 12:58:01 thomas-b - * Added ALL_PTP_V2_COMMON_DATASETS structure and the appropriate free function - * Revision 1.1.1.74 2017/02/08 13:16:07 thomas-b - * Added ALL_MONITORING_INFO and the appropriate free function - * Revision 1.1.1.73 2017/02/07 09:46:51 thomas-b - * Added ALL_SNMP_INFO and the appropriate free function - * Revision 1.1.1.72 2016/12/19 12:13:55 philipp - * Added GPIO associated index helper - * Revision 1.1.1.71 2016/11/22 12:40:46 philipp - * Added I/O port helper functions - * Revision 1.1.1.70 2016/11/08 17:21:19 martin - * Doxygen fixes. - * Revision 1.1.1.69 2016/11/01 14:51:54 udo - * *** empty log message *** - * Revision 1.1.1.68 2016/11/01 09:24:01 martin - * *** empty log message *** - * Revision 1.1.1.67 2016/10/25 07:48:27 martin - * Doxygen fixes. - * Revision 1.1.1.66 2016/10/21 09:39:25 thomas-b - * Added struct ALL_XBP_INFO and appropriate free function - * Revision 1.1.1.65 2016/10/14 11:10:02 thomas-b - * Added ALL_UCAP_NET_INFO and the appropriate free function - * Revision 1.1.1.64 2016/09/28 15:04:02 thomas-b - * Added function to check whether NET_CFG_API stage 2 is supported - * Revision 1.1.1.63 2016/07/26 08:07:10 philipp - * Fixed compiler errors (name clash, syntax error) - * Revision 1.1.1.62 2016/07/15 14:09:48 martin - * Use functions from new module timeutil. - * Revision 1.1.1.61 2016/06/21 13:51:23 philipp - * Fixed nasty segfault due to pointer corruption - * Revision 1.1.1.60 2016/06/21 12:06:59 thomas-b - * Added function calloc_ucap_entry - * Revision 1.1.1.59 2016/06/21 10:25:30 philipp - * Freeing ucap entry list is now portable - * Revision 1.1.1.58 2016/06/21 07:39:21 philipp - * Use mbg_klist for ucap events and not an array -> Easier to handle MAX_UCAP_ENTRIES - * Revision 1.1.1.57 2016/06/16 07:46:45 philipp - * Fixed checking flags for IMS sensor specific features - * Revision 1.1.1.56 2016/06/15 14:04:27 thomas-b - * Added ALL_UCAP_INFO structure and function free_all_ucap_info - * Revision 1.1.1.55 2016/06/03 09:00:13 thomas-b - * tm structure does not have gmtoff field under Windows - * Revision 1.1.1.54 2016/06/02 10:24:22 philipp - * Renaming all revision macros and helper functions - * Revision 1.1.1.53 2016/05/27 07:27:43 philipp - * Fixed (potential) memleak - * Revision 1.1.1.52 2016/05/27 05:48:08 philipp - * Refactoring to support XMR_METRICS properly - * Revision 1.1.1.51 2016/05/26 11:01:09 thomas-b - * Removed info structures from ALL_NTP_STATUS - * Moved check functions of specific features to cfg_hlp - * Revision 1.1.1.50 2016/05/25 08:43:35 philipp - * Redesign of ALL_[xxx]_[XXX] structures and (helper) functions - * Revision 1.1.1.49 2016/05/23 09:37:40 philipp - * Extended ALL_XMULTI_REF_STATUS by holdover_status - * Revision 1.1.1.48 2016/05/23 08:59:03 philipp - * New function free_all_gpio_state - * Revision 1.1.1.47 2016/05/23 08:24:37 philipp - * New function free_all_ims_state - * Revision 1.1.1.46 2016/05/11 13:20:55 thomas-b - * Added ALL_NET_STATUS_INFO and the appropriate free function - * Revision 1.1.1.45 2016/04/26 14:21:58 thomas-b - * Renamed ALL_NET_CFG_INFO structure members - * Revision 1.1.1.44 2016/04/26 13:45:36 martin - * Tried portable printing of int64_t types. - * Revision 1.1.1.43 2016/04/26 08:40:17Z philipp - * Fixed compiler warning due to invalid format specifier - * Revision 1.1.1.42 2016/04/26 08:23:45 thomas-b - * Extended ALL_NET_CFG_INFO by DNS configurations - * Revision 1.1.1.41 2016/04/26 06:29:27 thomas-b - * Added ALL_NET_CFG_INFO for network configuration - * Revision 1.1.1.40 2016/04/25 14:55:32 martin - * *** empty log message *** - * Revision 1.1.1.39 2016/04/25 14:42:18 martin - * *** empty log message *** - * Revision 1.1.1.38 2016/04/25 11:22:41 martin - * Revision 1.1.1.37 2016/04/25 09:01:29Z martin - * *** empty log message *** - * Revision 1.1.1.36 2016/04/22 07:11:50 philipp - * Use pointer to pointer in get_all_* functions - * Revision 1.1.1.35 2016/04/20 14:45:46 thomas-b - * Renamed ALL_NTP_STATE_INFO to ALL_NTP_STATUS - * Revision 1.1.1.34 2016/04/20 13:49:12 thomas-b - * Added structure definitions and free functions for NTP - * Revision 1.1.1.33 2016/04/20 12:37:53 thomas-b - * Moved free functions for ALL_XMULTI_REF_INFO and ALL_XMULTI_REF_STATUS to cfg_hlp - * Revision 1.1.1.32 2016/04/08 07:54:17 philipp - * Added function mbg_print_ext_rev_info - * Revision 1.1.1.31 2016/04/07 08:07:38 philipp - * Added function normalize_nano_time_64 (Clemens) - * Revision 1.1.1.30 2016/04/04 15:08:45 martin - * Replaced chk_model_is_vsg() by xdevfeat::xdevfeat_is_vsg(). - * Revision 1.1.1.29 2016/03/03 11:16:50 martin - * Utility functions to alloc and free memory for hardware ID. - * Revision 1.1.1.28 2016/02/17 12:00:06Z gregoire - * new function chk_model_is_vsg - * Revision 1.1.1.27 2015/11/24 13:12:04Z philipp - * Extended / modified TLV functions - * Revision 1.1.1.26 2015/11/23 14:15:40 philipp - * Moved TLV related initializing functions to here - * Revision 1.1.1.25 2015/10/30 15:33:48 martin - * Revision 1.1.1.24 2015/10/27 16:17:32Z martin - * *** empty log message *** - * Revision 1.1.1.23 2015/10/26 16:31:52 martin - * *** empty log message *** - * Revision 1.1.1.22 2015/10/26 13:36:44 martin - * Revision 1.1.1.21 2015/10/15 12:49:09Z marvin - * Revision 1.1.1.20 2015/10/12 10:01:59Z martin - * *** empty log message *** - * Revision 1.1.1.19 2015/10/09 11:09:13 martin - * *** empty log message *** - * Revision 1.1.1.18 2015/10/08 10:32:16 martin - * *** empty log message *** - * Revision 1.1.1.17 2015/10/08 09:30:34 martin - * *** empty log message *** - * Revision 1.1.1.16 2015/10/07 16:03:19 martin - * *** empty log message *** - * Revision 1.1.1.15 2015/10/07 09:59:00 martin + * Revision 1.2 2017/07/05 12:17:38 martin + * Support functions for TLV, IMS, GPIO, and + * mbg_snprint_revision() provided by philipp. + * Support functions for network configuration, + * NTP configuration, ALL_UCAP stuff, SNMP and + * MONITORING, as well as ALL_PTP_V2_COMMON_DATASETS + * and ALL_PTP_V1_COMMON_DATASETS provided by thomas-b. + * Support functions for xmulti_ref and IO PORT stuff + * provided by philipp and thomas-b. * More common GNSS support. - * Revision 1.1.1.14 2015/10/05 13:29:45 martin - * Revision 1.1.1.13 2015/10/01 10:58:35Z thomas-b - * fixed call of mbgmktm with correct month and day values in nano_time_64_to_tm_gps - * Revision 1.1.1.12 2015/09/15 09:11:13 martin - * Moved some functions into a _PRELIMINARY_CODE section. - * Revision 1.1.1.11 2015/09/14 08:56:05 thomas-b - * Sustract 1900 from year when calling mbg_mktime - * Revision 1.1.1.10 2015/09/14 07:34:08 thomas-b - * Added missing includes of time.h and mbgmktm.h - * Revision 1.1.1.9 2015/09/11 12:09:04 thomas-b - * Added nano_time_64_to_tm_gps and tm_gps_to_nano_time_64 functions - * Revision 1.1.1.8 2015/08/31 14:55:11 martin - * Moved string trim functions to str_util module. - * Revision 1.1.1.7 2015/08/31 13:41:56 martin - * Revision 1.1.1.6 2014/10/29 16:25:31 martin - * Moved some functions and structures to more convenient files. - * Revision 1.1.1.5 2014/10/14 10:20:18 martin - * Revision 1.1.1.4 2014/10/14 10:05:10 martin - * Revision 1.1.1.3 2014/09/26 11:43:24Z martin - * Revision 1.1.1.2 2014/07/22 13:05:34 martin - * Revision 1.1.1.1 2014/04/28 12:29:45Z martin + * New functions alloc_dev_hw_id() and chk_free_dev_hw_id(). + * Tried portable printing of int64_t types. + * Account for frac_sec_from_bin() obsoleted by + * bin_frac_32_to_dec_frac(). * Revision 1.1 2014/04/25 09:14:49 martin * Initial revision. * @@ -194,166 +49,6 @@ #include <time.h> -#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) - -/*HDR*/ -/** - * @brief Normalize a ::NANO_TIME_64 struct - * - * After normalization, the following can be assumed:<br> - * - nano_secs is in the range [-10^9 + 1, 10^9 - 1]<br> - * - if secs is not 0, secs and nano_secs have the same sign - * - * @param[in,out] nt The NANO_TIME_64 to be normalized - */ -void normalize_nano_time_64( NANO_TIME_64 *nt ) -{ - int64_t additional_secs; - - // Step 1: Make sure nano seconds are in the interval [-10^9 + 1, 10^9 - 1] - additional_secs = nt->nano_secs / NSECS_PER_SEC; - nt->nano_secs -= additional_secs * NSECS_PER_SEC; - nt->secs += additional_secs; - - // Step 2: Make sure seconds and nanoseconds have same sign if seconds is not 0 - if ( nt->secs > 0 && nt->nano_secs < 0 ) - { - nt->secs -= 1; - nt->nano_secs += NSECS_PER_SEC; - } - else if ( nt->secs < 0 && nt->nano_secs > 0 ) - { - nt->secs += 1; - nt->nano_secs -= NSECS_PER_SEC; - } - -} // normalize_nano_time_64 - -#endif // !defined( MBG_TGT_MISSING_64_BIT_TYPES ) - - - -#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) - -/*HDR*/ -/** - * @brief Print a normalized ::NANO_TIME_64 into a string buffer - * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] nt The ::NANO_TIME_64 to be printed - */ -size_t snprint_nano_time_64( char *s, size_t max_len, const NANO_TIME_64 *nt ) -{ - size_t n = snprintf_safe( s, max_len, "%c%" PRId64 ".%09" PRId64, - _nano_time_negative( nt ) ? '-' : '+', - _abs64( nt->secs ), - _abs64( nt->nano_secs ) ); - return n; - -} // snprint_nano_time_64 - -#endif // !defined( MBG_TGT_MISSING_64_BIT_TYPES ) - - - -/*HDR*/ -/** - * @brief Print nano time into string buffer - * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] nt The ::NANO_TIME to be printed - */ -size_t snprint_nano_time( char *s, size_t max_len, const NANO_TIME *nt ) -{ - size_t n = snprintf_safe( s, max_len, "%c%li.%09li", - _nano_time_negative( nt ) ? '-' : '+', - labs( (long) nt->secs ), - labs( (long) nt->nano_secs ) ); - return n; - -} // snprint_nano_time - - - -#if defined( _PRELIMINARY_CODE ) - -//### TODO: eventually move these functions to a different module - -#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) - -/*HDR*/ -/** - * @brief Convert ::NANO_TIME_64 to ::TM_GPS - * - * @param[out] tm_gps The ::TM_GPS to be filled - * @param[in] nt The ::NANO_TIME_64 to be converted - * - * @return 1 on success, 0 on error - * - * @see ::tm_gps_to_nano_time_64 - */ -int nano_time_64_to_tm_gps( TM_GPS *tm_gps, const NANO_TIME_64 *nt ) -{ - struct tm tm = { 0 }; - time_t t = cvt_to_time_t( nt->secs ); - int rc = mbg_gmtime( &tm, &t ); - - if ( mbg_rc_is_success( rc ) ) - { - tm_gps->year = tm.tm_year + 1900; - tm_gps->month = tm.tm_mon + 1; - tm_gps->mday = tm.tm_mday; - tm_gps->yday = tm.tm_yday; - tm_gps->wday = tm.tm_wday; - tm_gps->hour = tm.tm_hour; - tm_gps->min = tm.tm_min; - tm_gps->sec = tm.tm_sec; - tm_gps->frac = 0; //### TODO convert fractions -#if defined( MBG_TGT_POSIX ) - tm_gps->offs_from_utc = tm.tm_gmtoff; //### TODO Is tm.tm_gmtoff even valid? -#endif - return 1; //### TODO return MBG_SUCCESS - } - - return 0; //### TODO return rc - -} // nano_time_64_to_tm_gps - - - -/*HDR*/ -/** - * @brief Convert ::TM_GPS to ::NANO_TIME_64 - * - * @param[out] nt The ::NANO_TIME_64 to be filled - * @param[in] tm The ::TM_GPS to be converted - * - * @return 1 on success, 0 on error - * - * @see ::nano_time_64_to_tm_gps - */ -int tm_gps_to_nano_time_64( NANO_TIME_64 *nt, const TM_GPS *tm ) -{ - time_t t = mbg_mktime( tm->year - 1900, tm->month - 1, tm->mday - 1, tm->hour, tm->min, tm->sec ); - - if ( t != (time_t) -1 ) - { - nt->secs = (uint64_t) t; - nt->nano_secs = 0; //### TODO: convert fractions - return 1; - } - - return 0; - -} // tm_gps_to_nano_time_64 - -#endif // !defined( MBG_TGT_MISSING_64_BIT_TYPES ) - -#endif // defined( _PRELIMINARY_CODE ) - - /*HDR*/ /** @@ -802,32 +497,35 @@ const char *get_hw_id_from_fw_id( const char *fw_id ) * @param[in] all_io_port_info Pointer to the ::ALL_IO_PORT_INFO, containing the current configuration * @param[in] io_port_info_idx Pointer to the ::MBG_IO_PORT_INFO_IDX, for which the ::MBG_IO_PORT_TYPE_INFO_IDX shall be found * - * @return Pointer to the found ::MBG_IO_PORT_TYPE_INFO_IDX or NULL - * + * @return Pointer to the ::MBG_IO_PORT_TYPE_INFO_IDX found, or NULL */ -MBG_IO_PORT_TYPE_INFO_IDX *get_io_port_type_info_idx(ALL_IO_PORT_INFO *all_io_port_info, MBG_IO_PORT_INFO_IDX *io_port_info_idx) +MBG_IO_PORT_TYPE_INFO_IDX *get_io_port_type_info_idx( ALL_IO_PORT_INFO *all_io_port_info, MBG_IO_PORT_INFO_IDX *io_port_info_idx ) { uint8_t i; - if(!all_io_port_info || !io_port_info_idx) + if ( !all_io_port_info || !io_port_info_idx ) return NULL; - for(i = 0; i < io_port_info_idx->info.num_types; ++i) + for ( i = 0; i < io_port_info_idx->info.num_types; ++i ) { - if(all_io_port_info->pt_infos[io_port_info_idx->idx][i].info.port_type == io_port_info_idx->info.settings.type) + MBG_IO_PORT_TYPE_INFO_IDX *ptii = &all_io_port_info->pt_infos[io_port_info_idx->idx][i]; + MBG_IO_PORT_TYPE_INFO *pti = &ptii->info; + + if ( pti->port_type == io_port_info_idx->info.settings.port_type ) { - if(all_io_port_info->pt_infos[io_port_info_idx->idx][i].info.port_type == MBG_IO_PORT_TYPE_GPIO) + if ( pti->port_type == MBG_IO_PORT_TYPE_GPIO ) { - if(all_io_port_info->pt_infos[io_port_info_idx->idx][i].info.data.gpio_limits.type == io_port_info_idx->info.settings.data.gpio_settings.type) - return &all_io_port_info->pt_infos[io_port_info_idx->idx][i]; + if ( pti->data.gpio_limits.type == io_port_info_idx->info.settings.data.gpio_settings.type ) + return ptii; } - else return &all_io_port_info->pt_infos[io_port_info_idx->idx][i]; + else + return ptii; } } return NULL; -} +} // get_io_port_type_info_idx @@ -908,24 +606,24 @@ void mbg_tlv_rcv_state_init( MBG_TLV_RCV_STATE *state, MBG_TLV_UID uid, uint32_t /*HDR*/ -size_t mbg_snprint_revision( char *buf, size_t buflen, - const char *prefix, const char *suffix, - uint32_t rev) +int mbg_snprint_revision( char *buf, size_t buflen, + const char *prefix, const char *suffix, + uint32_t rev) { - size_t bytes = 0; - uint32_t major, minor, patch; + size_t bytes = 0; + uint32_t major, minor, patch; - if ( prefix ) - bytes += snprintf_safe( &buf[bytes], buflen, "%s", prefix ); + if ( prefix ) + bytes += snprintf_safe( &buf[bytes], buflen, "%s", prefix ); - _mbg_decode_revision( rev, major, minor, patch ); - bytes += snprintf_safe( &buf[bytes], buflen - bytes, "%u.%u.%u", - major, minor, patch); + _mbg_decode_revision( rev, major, minor, patch ); + bytes += snprintf_safe( &buf[bytes], buflen - bytes, "%u.%u.%u", + major, minor, patch); - if ( suffix ) - bytes += snprintf_safe( &buf[bytes], buflen - bytes, "%s", suffix ); + if ( suffix ) + bytes += snprintf_safe( &buf[bytes], buflen - bytes, "%s", suffix ); - return bytes; + return _int_from_size_t( bytes ); } // mbg_snprint_revision @@ -1146,7 +844,7 @@ _NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_dep_on_ass_idx( const ALL_GPIO_INFO * * @return One of the @ref MBG_RETURN_CODES * * @see ::mbgextio_dev_has_gpio - * @see ::mbg_chk_dev_supp_gpio + * @see ::mbg_chk_dev_has_gpio * @see ::free_all_gpio_info */ _NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_has_status( const ALL_GPIO_INFO *info ) @@ -1485,6 +1183,9 @@ void free_all_ntp_status( ALL_NTP_STATUS *p ) { if ( p ) { + if ( p->refclk_states ) + free( p->refclk_states ); + if ( p->peer_states ) free( p->peer_states ); @@ -1502,7 +1203,6 @@ void free_all_ntp_status( ALL_NTP_STATUS *p ) * @param[in] p Pointer to the ::ALL_IMS_INFO structure, which will be freed * * @see ::mbgextio_dev_has_ims - * @see ::mbgextio_dev_ims_has_fdm * @see ::mbgextio_get_all_ims_info * @see ::mbgextio_get_all_ims_state */ @@ -1533,7 +1233,6 @@ void free_all_ims_info( ALL_IMS_INFO *p ) * @param[in] p Pointer to the ::ALL_IMS_STATE structure, which will be freed * * @see ::mbgextio_dev_has_ims - * @see ::mbgextio_dev_ims_has_fdm * @see ::mbgextio_get_all_ims_info * @see ::mbgextio_get_all_ims_state */ @@ -1745,3 +1444,75 @@ void free_all_ucap_net_info( ALL_UCAP_NET_INFO *p ) } // free_all_ucap_net_info + +/*HDR*/ +/** + * @brief Set up a ::NTP_TSTAMP structure from a hex string with a time in seconds and binary fractions + * + * @param[in] s A string with a time in seconds since NTP epoch 1900-01-01, + * with binary fractions separated by decimal point, + * e.g. 'dc763e43.73bd5a8f' as printed by the ntpq utility + * @param[out] p Address of a ::NTP_TSTAMP structure to be set up + * + * @see ::str_ntp_hex_to_nano_time_64 + */ +void str_ntp_hex_to_ntp_tstamp( const char *s, NTP_TSTAMP *p ) +{ + char *cp = NULL; + + p->seconds = strtoul( s, &cp, 16 ); + + if ( *cp == '.' ) // fractions may follow + { + cp++; // skip '.' + + p->fractions = strtoul( cp, NULL, 16 ); + } + else + p->fractions = 0; + +} // str_ntp_hex_to_ntp_tstamp + + + +#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + +/*HDR*/ +/** + * @brief Convert a ::NTP_TSTAMP structure to a ::NANO_TIME_64 structure + * + * @param[in] p_nts The ::NTP_TSTAMP structure to be converted + * @param[out] p_nt64 The ::NANO_TIME_64 structure to be filled up + */ +void ntp_tstamp_to_nanotime_64( const NTP_TSTAMP *p_nts, NANO_TIME_64 *p_nt64 ) +{ + p_nt64->secs = p_nts->seconds - NTP_SEC_BIAS; + p_nt64->nano_secs = bin_frac_32_to_dec_frac( p_nts->fractions, NSECS_PER_SEC ); + +} // ntp_tstamp_to_nanotime_64 + + + +/*HDR*/ +/** + * @brief Set up a ::NANO_TIME_64 structure from a hex string with a time in seconds and binary fractions + * + * @param[in] s A string with a time in seconds since epoch 1900-01-01, + * with binary fractions separated by decimal point, + * e.g. 'dc763e43.73bd5a8f' as printed by the ntpq utility + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + * + * @see ::str_ntp_hex_to_ntp_tstamp + */ +void str_ntp_hex_to_nano_time_64( const char *s, NANO_TIME_64 *p ) +{ + NTP_TSTAMP nts = { 0 }; + + str_ntp_hex_to_ntp_tstamp( s, &nts ); + ntp_tstamp_to_nanotime_64( &nts, p ); + +} // str_ntp_hex_to_nano_time_64 + +#endif // !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + + diff --git a/mbglib/common/cfg_hlp.h b/mbglib/common/cfg_hlp.h index 870869c..7cb4e49 100755 --- a/mbglib/common/cfg_hlp.h +++ b/mbglib/common/cfg_hlp.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: cfg_hlp.h 1.3.1.102 2017/05/04 15:05:10 martin TEST $ + * $Id: cfg_hlp.h 1.4 2017/07/05 13:22:00 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -19,194 +19,22 @@ * * ----------------------------------------------------------------------- * $Log: cfg_hlp.h $ - * Revision 1.3.1.102 2017/05/04 15:05:10 martin - * Exclude dfrac_sec_from_bin() from build for kernel targets - * which usually don't support floating point operations anyway. - * Revision 1.3.1.101 2017/04/25 15:41:20 martin - * Fixed build under FreeBSD. - * Revision 1.3.1.100 2017/03/29 12:33:26 philipp - * Extended event info and event status index structures by data pointer - * Revision 1.3.1.99 2017/03/27 10:37:18 thomas-b - * Added ALL_PTP_V1_COMMON_DATASETS and the appropriate free function - * Revision 1.3.1.98 2017/03/22 09:07:53 thomas-b - * Added function get_io_port_type_info_idx - * Revision 1.3.1.97 2017/03/17 12:01:02 martin - * Moved definitions of PCPS_HRT_FRAC_CONVERSION_TYPE, - * PCPS_HRT_BIN_FRAC_SCALE, and PCPS_HRT_FRAC_SCALE_FMT - * here. - * Revision 1.3.1.96 2017/03/17 11:45:17 martin - * Moved binary fraction conversion functions here. - * Revision 1.3.1.95 2017/03/02 14:03:00 gregoire - * ALL_NTP_CFG_INFO reworked - * Revision 1.3.1.94 2017/03/02 08:34:08 gregoire - * ALL_NTP_CFG_INFO: NTP_REFCLK_CFG_INFO_IDX added - * Revision 1.3.1.93 2017/02/28 15:25:17 gregoire - * ALL_NTP_CFG_INFO extended - * Revision 1.3.1.92 2017/02/24 09:38:25 philipp - * Do not use fixed buffers for monitorung event info and status - * Revision 1.3.1.91 2017/02/22 11:40:17 martin - * Account for preliminary code. - * Revision 1.3.1.90 2017/02/21 15:51:40 thomas-b - * Added ALL_MONITORING_STATUS and free function and extended ALL_MONITORING_INFO by events - * Revision 1.3.1.89 2017/02/16 12:58:01 thomas-b - * Added ALL_PTP_V2_COMMON_DATASETS structure and the appropriate free function - * Revision 1.3.1.88 2017/02/08 13:16:08 thomas-b - * Added ALL_MONITORING_INFO and the appropriate free function - * Revision 1.3.1.87 2017/02/07 09:46:51 thomas-b - * Added ALL_SNMP_INFO and the appropriate free function - * Revision 1.3.1.86 2016/12/19 12:13:55 philipp - * Added GPIO associated index helper - * Revision 1.3.1.85 2016/12/13 13:46:22 martin - * Increased MAX_PARM_PORT and MAX_PARM_POUT to 10. - * Revision 1.3.1.84 2016/11/22 12:40:46Z philipp - * Added I/O port helper functions - * Revision 1.3.1.83 2016/11/08 17:21:35 martin - * Updated function prototypes. - * Revision 1.3.1.82 2016/11/01 09:24:02 martin - * *** empty log message *** - * Revision 1.3.1.81 2016/10/25 07:48:27 martin - * Doxygen fixes. - * Revision 1.3.1.80 2016/10/21 09:39:26 thomas-b - * Added struct ALL_XBP_INFO and appropriate free function - * Revision 1.3.1.79 2016/10/14 11:10:03 thomas-b - * Added ALL_UCAP_NET_INFO and the appropriate free function - * Revision 1.3.1.78 2016/09/28 15:04:03 thomas-b - * Added function to check whether NET_CFG_API stage 2 is supported - * Revision 1.3.1.77 2016/08/11 13:25:06 martin - * Use mbgklist.h instead of mbg_klist.h. - * Revision 1.3.1.76 2016/08/11 08:36:56Z martin - * Exclude function prototypes from build for kernel space. - * Revision 1.3.1.75 2016/08/10 12:25:02Z martin - * Support FreeBSD. - * Revision 1.3.1.74 2016/08/09 07:09:28 martin - * Support QNX Neutrino. - * Revision 1.3.1.73 2016/06/21 12:06:59 thomas-b - * Added function calloc_ucap_entry - * Revision 1.3.1.72 2016/06/21 07:39:21 philipp - * Use mbg_klist for ucap events and not an array -> Easier to handle MAX_UCAP_ENTRIES - * Revision 1.3.1.71 2016/06/16 07:46:45 philipp - * Fixed checking flags for IMS sensor specific features - * Revision 1.3.1.70 2016/06/15 14:04:27 thomas-b - * Added ALL_UCAP_INFO structure and function free_all_ucap_info - * Revision 1.3.1.69 2016/06/02 10:24:22 philipp - * Renaming all revision macros and helper functions - * Revision 1.3.1.68 2016/05/31 11:29:15 philipp - * Extended ALL_XMULTI_REF_STATUS by flags if at least one ref type supports stats and/or metrics - * Revision 1.3.1.67 2016/05/27 05:48:08 philipp - * Refactoring to support XMR_METRICS properly - * Revision 1.3.1.66 2016/05/26 11:01:03 thomas-b - * Removed info structures from ALL_NTP_STATUS - * Moved check functions of specific features to cfg_hlp - * Revision 1.3.1.65 2016/05/25 08:43:36 philipp - * Redesign of ALL_[xxx]_[XXX] structures and (helper) functions - * Revision 1.3.1.64 2016/05/23 09:37:40 philipp - * Extended ALL_XMULTI_REF_STATUS by holdover_status - * Revision 1.3.1.63 2016/05/23 08:59:03 philipp - * New function free_all_gpio_state - * Revision 1.3.1.62 2016/05/23 08:24:38 philipp - * New function free_all_ims_state - * Revision 1.3.1.61 2016/05/11 13:20:59 thomas-b - * Added ALL_NET_STATUS_INFO and the appropriate free function - * Revision 1.3.1.60 2016/04/26 14:21:58 thomas-b - * Renamed ALL_NET_CFG_INFO structure members - * Revision 1.3.1.59 2016/04/26 08:23:45 thomas-b - * Extended ALL_NET_CFG_INFO by DNS configurations - * Revision 1.3.1.58 2016/04/26 06:29:30 thomas-b - * Added ALL_NET_CFG_INFO for network configuration - * Revision 1.3.1.57 2016/04/25 11:22:31 martin - * Revision 1.3.1.56 2016/04/25 10:43:38Z martin - * *** empty log message *** - * Revision 1.3.1.55 2016/04/22 07:11:50 philipp - * Use pointer to pointer in get_all_* functions - * Revision 1.3.1.54 2016/04/20 14:45:46 thomas-b - * Renamed ALL_NTP_STATE_INFO to ALL_NTP_STATUS - * Revision 1.3.1.53 2016/04/20 13:49:13 thomas-b - * Added structure definitions and free functions for NTP - * Revision 1.3.1.52 2016/04/20 12:37:53 thomas-b - * Moved free functions for ALL_XMULTI_REF_INFO and ALL_XMULTI_REF_STATUS to cfg_hlp - * Revision 1.3.1.51 2016/04/12 13:28:39 philipp - * New helper functions to get all feature related structures at once - * Revision 1.3.1.50 2016/04/12 08:25:10 thomas-b - * Added ALL_XMULTI_REF_STATUS structure - * Revision 1.3.1.49 2016/04/11 13:56:24 thomas-b - * Added ALL_XMULTI_REF_INFO structure - * Revision 1.3.1.48 2016/04/08 07:54:26 philipp - * Added function prototype mbg_print_ext_rev_info - * Revision 1.3.1.47 2016/04/04 15:08:45 martin - * Replaced chk_model_is_vsg() by xdevfeat::xdevfeat_is_vsg(). - * Revision 1.3.1.46 2016/03/03 11:20:30 martin - * Updated function prototypes. - * Revision 1.3.1.45 2016/02/17 12:00:07Z gregoire - * new function chk_model_is_vsg - * Revision 1.3.1.44 2016/02/10 15:45:32Z martin - * *** empty log message *** - * Revision 1.3.1.43 2015/11/24 13:12:04 philipp - * Extended / modified TLV functions - * Revision 1.3.1.42 2015/11/23 14:15:40 philipp - * Moved TLV related initializing functions to here - * Revision 1.3.1.41 2015/11/20 14:51:10 martin - * Revision 1.3.1.40 2015/11/02 11:00:48Z martin - * *** empty log message *** - * Revision 1.3.1.39 2015/11/02 09:20:02 martin - * *** empty log message *** - * Revision 1.3.1.38 2015/10/27 16:21:31 martin + * Revision 1.4 2017/07/05 13:22:00 martin + * Definitions for TLV, IMS, and GPIO provided by philipp. + * Definitions for ALL_XPB_INFO, ALL_NET_CFG_INFO, + * ALL_PTP_V2_COMMON_DATASETS, ALL_PTP_V1_COMMON_DATASETS, + * ALL_UCAP and associated stuff provided by thomas-b. + * Definitions for xmulti_ref and IO PORT, SNMP and MONITORING, + * and associated stuff provided by philipp and thomas-b. + * New definitions COMP_SIG_MODES and PCPS_TIME_EXT_FLAGS. + * New inline functions device_id_is_serial() and + * device_id_is_lan(). + * Moved inline function num_bits_set() and a lot of + * global configuration variables here. * Older defines N_SUPP_DEV, PCPS_MAX_DDEVS, and MBG_MAX_DEVICES * have been obsoleted by new defines N_SUPP_DEV_BUS, N_SUPP_DEV_EXT, * and N_SUPP_DEV_TOTAL. - * Revision 1.3.1.37 2015/10/26 16:31:53 martin - * *** empty log message *** - * Revision 1.3.1.36 2015/10/26 14:18:34 martin - * Revision 1.3.1.35 2015/10/15 12:49:10Z marvin - * Revision 1.3.1.34 2015/10/12 10:01:59Z martin - * *** empty log message *** - * Revision 1.3.1.33 2015/10/08 13:27:37 martin - * *** empty log message *** - * Revision 1.3.1.32 2015/10/08 10:32:16 martin - * *** empty log message *** - * Revision 1.3.1.31 2015/10/08 09:30:34 martin - * *** empty log message *** - * Revision 1.3.1.30 2015/10/07 10:12:08 martin - * *** empty log message *** - * Revision 1.3.1.29 2015/10/07 10:08:34 martin - * *** empty log message *** - * Revision 1.3.1.28 2015/10/07 09:59:00 martin - * More common GNSS support. - * Revision 1.3.1.27 2015/09/15 09:10:40 martin - * Updated function prototypes. - * Revision 1.3.1.26 2015/09/11 12:09:09 thomas-b - * Added nano_time_64_to_tm_gps and tm_gps_to_nano_time_64 functions - * Revision 1.3.1.25 2015/08/31 14:55:11 martin - * Moved string trim functions to str_util module. - * Revision 1.3.1.24 2015/08/31 14:49:25 martin - * Revision 1.3.1.23 2015/08/31 09:58:08 martin - * Revision 1.3.1.22 2015/08/27 16:30:10Z martin - * Revision 1.3.1.21 2015/08/26 07:31:51 martin - * Revision 1.3.1.20 2015/08/21 14:22:59 martin - * Revision 1.3.1.19 2014/10/29 16:25:31 martin - * Moved some functions and structures to more convenient files. - * Revision 1.3.1.18 2014/10/29 16:00:37 martin - * Revision 1.3.1.17 2014/10/29 14:21:55 martin - * Revision 1.3.1.16 2014/09/26 11:43:24 martin - * Revision 1.3.1.15 2014/07/22 13:05:35 martin - * Revision 1.3.1.14 2014/07/14 15:42:45Z martin - * Revision 1.3.1.13 2014/06/25 15:15:20 martin - * Revision 1.3.1.12 2014/06/25 08:51:36Z martin - * Support GPIO status. - * Revision 1.3.1.11 2014/05/22 16:15:16Z martin - * Revision 1.3.1.10 2014/05/14 12:43:53 martin - * Revision 1.3.1.9 2014/05/13 08:23:24 martin - * Revision 1.3.1.8 2014/05/13 08:19:34Z martin - * Revision 1.3.1.7 2014/04/28 12:33:09 martin - * Revision 1.3.1.6 2014/04/28 12:04:32 martin - * Revision 1.3.1.5 2014/04/25 09:16:38 martin * Updated function prototypes. - * Revision 1.3.1.4 2013/12/18 14:51:37 martin - * Moved inline function num_bits_set() here. - * Revision 1.3.1.3 2013/11/13 10:00:09 martin - * Revision 1.3.1.2 2013/11/12 12:12:40 marvin - * Changed calls for NTP info and settings. - * Revision 1.3.1.1 2013/09/25 10:14:38Z martin - * Started to support NTP configuration. * Revision 1.3 2013/09/25 10:02:15 martin * Added ALL_PTP_CFG_INFO, ALL_GNSS_SAT_INFO_IDX and * related definitions. @@ -438,13 +266,6 @@ typedef struct -/** - * @brief All monitoring status - * - * Used to collect all status information for monitoring of a device - * Depending on the ::MBG_MONITORING_LIMITS::supp_events, the - * appropriate event status for each event can be found in ::event_stati. - */ typedef struct { MBG_EVENT_STATUS_IDX status; @@ -452,6 +273,16 @@ typedef struct } MBG_EVENT_STATUS_IDX_DATA; + + +/** + * @brief All monitoring status + * + * Used to collect all status information for monitoring a device. + * Depending on the ::MBG_MONITORING_LIMITS::supp_num_events, + * the appropriate event status for each event can be found + * in ::ALL_MONITORING_STATUS::event_stati. + */ typedef struct { MBG_MONITORING_STATUS status; @@ -460,6 +291,7 @@ typedef struct } ALL_MONITORING_STATUS; + /// @brief Configuration settings for all unicast master specifications typedef PTP_UC_MASTER_INFO_IDX ALL_PTP_UC_MASTER_INFO_IDX[MAX_PARM_PTP_UC_MASTER]; @@ -486,8 +318,9 @@ typedef struct * @brief All PTPv1 common datasets for a PTP device * * Contains one of each common datasets plus one port dataset - * for each port of a device. The number of port datasets is - * defined in ::default_dataset::number_ports. + * for each port of a device. The number of port datasets is defined + * in the ::MBG_PTP_V1_DEFAULT_DATASET::number_ports field of the + * ::ALL_PTP_V1_COMMON_DATASETS::default_dataset member. * * @see ::MBG_PTP_V1_DEFAULT_DATASET * @see ::MBG_PTP_V1_CURRENT_DATASET @@ -511,8 +344,9 @@ typedef struct * @brief All PTPv2 common datasets for a PTP device * * Contains one of each common datasets plus one port dataset - * for each port of a device. The number of port datasets is - * defined in ::default_dataset::number_ports. + * for each port of a device. The number of port datasets is defined + * in the ::MBG_PTP_V1_DEFAULT_DATASET::number_ports field of the + * ::ALL_PTP_V1_COMMON_DATASETS::default_dataset member. * * @see ::MBG_PTP_V2_DEFAULT_DATASET * @see ::MBG_PTP_V2_CURRENT_DATASET @@ -543,10 +377,10 @@ typedef GNSS_SAT_INFO_IDX ALL_GNSS_SAT_INFO_IDX[MAX_PARM_GNSS_SAT]; /** - * @brief An array of configuration settings for all programmable pulse outputs #### + * @brief Summary information on all supported GNSS systems * - * Used to collect all configuration parameters of a clock's programmable pulse outputs - * that can be handled by a configuration program. ##### + * Used to collect all configuration parameters even for devices + * that can receive the signals from multiple satellite systems. */ typedef struct { @@ -559,7 +393,7 @@ typedef struct -/// @brief Configuration settings for all NTP server associatioions +/// @brief Configuration settings for all NTP server associations typedef NTP_PEER_SETTINGS ALL_NTP_PEER_SETTINGS[MAX_EXT_NTP_SERVERS]; /** @@ -598,6 +432,7 @@ typedef struct typedef struct { NTP_SYS_STATE sys_state; + NTP_REFCLK_STATE_IDX *refclk_states; NTP_PEER_STATE_IDX *peer_states; } ALL_NTP_STATUS; @@ -970,257 +805,14 @@ MBG_TLV_UID mbg_tlv_create_id( void ) -/** - * @brief Data type used for intermediate results on 32 bit multiplications - * - * We need 64 bits for intermediate integer results to avoid a range overflow - * from 32 x 32 bit multiplications. On systems which don't support 64 bit types - * we use the "double" type as a workaround. - */ -#if defined( MBG_TGT_MISSING_64_BIT_TYPES ) - #define PCPS_HRT_FRAC_CONVERSION_TYPE double -#else - #define PCPS_HRT_FRAC_CONVERSION_TYPE int64_t -#endif - -/** - * @brief Constant used to convert e.g. ::PCPS_TIME_STAMP::frac values - * - * Max value of ::PCPS_TIME_STAMP::frac + 1, used for scaling - */ -#define PCPS_HRT_BIN_FRAC_SCALE ( (PCPS_HRT_FRAC_CONVERSION_TYPE) 4294967296.0 ) // == 0x100000000 - - - -#ifndef PCPS_HRT_FRAC_SCALE - /** - * @brief Scale to be used to print ::PCPS_TIME_STAMP::frac values - * - * The function ::frac_sec_from_bin can be used for the conversion. - * - * @see ::PCPS_HRT_FRAC_SCALE_FMT - */ - #define PCPS_HRT_FRAC_SCALE 10000000UL -#endif - -#ifndef PCPS_HRT_FRAC_SCALE_FMT - /** - * @brief Format specifier used to print ::PCPS_TIME_STAMP::frac values - * - * Used to print values scaled with ::frac_sec_from_bin called - * with ::PCPS_HRT_FRAC_SCALE. - * - * @see ::PCPS_HRT_FRAC_SCALE - */ - #define PCPS_HRT_FRAC_SCALE_FMT "%07lu" -#endif - - - -/** - * @brief Convert a 16 bit binary fraction to a scaled decimal - * - * @param[in] bin The binary fraction - * @param[in] scale The scale factor - * - * @return The calculated number - * - * @see ::dec_frac_to_bin_frac_16 - * @see ::dec_frac_to_bin_frac_32 - * @see ::bin_frac_32_to_dec_frac - * @see ::frac_sec_from_bin - */ -static __mbg_inline -uint32_t bin_frac_16_to_dec_frac( uint16_t bin, uint32_t scale ) -{ - return (uint32_t) ( (PCPS_HRT_FRAC_CONVERSION_TYPE) bin * scale - / 0x10000UL ); - -} // bin_frac_16_to_dec_frac - - - -/** - * @brief Convert a 32 bit binary fraction to a scaled decimal - * - * @param[in] bin The binary fraction - * @param[in] scale The scale factor - * - * @return The calculated number - * - * @see ::dec_frac_to_bin_frac_32 - * @see ::dec_frac_to_bin_frac_16 - * @see ::bin_frac_16_to_dec_frac - */ -static __mbg_inline -uint32_t bin_frac_32_to_dec_frac( uint32_t bin, uint32_t scale ) -{ - return (uint32_t) ( (PCPS_HRT_FRAC_CONVERSION_TYPE) bin * scale - / PCPS_HRT_BIN_FRAC_SCALE ); - -} // bin_frac_32_to_dec_frac - - - -#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) - -// On targets which don't provide 64 bit data types -// PCPS_HRT_FRAC_CONVERSION_TYPE is defined as double, -// in which case the ">> 1" operation in the 2 functions -// below yields an "invalid use of floating point" error. -// This could probably be fixed by a different way of -// casting, at least for a partial expression. - -static __mbg_inline -uint16_t dec_frac_to_bin_frac_16( uint32_t dec, uint32_t scale ) -{ - return (uint16_t) ( ( ( (PCPS_HRT_FRAC_CONVERSION_TYPE) dec * 0x20000 / scale ) + 1 ) >> 1 ); - -} // dec_frac_to_bin_frac_16 - - -static __mbg_inline -uint32_t dec_frac_to_bin_frac_32( uint32_t dec, uint32_t scale ) -{ - return (uint32_t) ( ( ( (PCPS_HRT_FRAC_CONVERSION_TYPE) dec * PCPS_HRT_BIN_FRAC_SCALE * 2 / scale ) + 1 ) >> 1 ); - -} // dec_frac_to_bin_frac_32 - -#endif - - - -#define bin_frac_32_to_msec( _bin ) bin_frac_32_to_dec_frac( (_bin), 1000L ) -#define bin_frac_32_to_usec( _bin ) bin_frac_32_to_dec_frac( (_bin), 1000000L ) -#define bin_frac_32_to_nsec( _bin ) bin_frac_32_to_dec_frac( (_bin), 1000000000L ) -#define bin_frac_16_to_msec( _bin ) bin_frac_16_to_dec_frac( (_bin), 1000L ) -#define bin_frac_16_to_usec( _bin ) bin_frac_16_to_dec_frac( (_bin), 1000000L ) -#define bin_frac_16_to_nsec( _bin ) bin_frac_16_to_dec_frac( (_bin), 1000000000L ) - - -#define msec_to_bin_frac_32( _msec ) dec_frac_to_bin_frac_32( (_msec), 1000L ) -#define usec_to_bin_frac_32( _usec ) dec_frac_to_bin_frac_32( (_usec), 1000000L ) -#define nsec_to_bin_frac_32( _nsec ) dec_frac_to_bin_frac_32( (_nsec), 1000000000L ) -#define msec_to_bin_frac_16( _msec ) dec_frac_to_bin_frac_16( (_msec), 1000L ) -#define usec_to_bin_frac_16( _usec ) dec_frac_to_bin_frac_16( (_usec), 1000000L ) -#define nsec_to_bin_frac_16( _nsec ) dec_frac_to_bin_frac_16( (_nsec), 1000000000L ) - - - -/** - * @brief Convert a binary fraction to a scaled decimal - * - * Convert a binary fraction (e.g. of a second, as in ::PCPS_TIME_STAMP::frac) - * to a decimal fraction, using a specified scale factor. - * - * @param[in] b The binary fraction - * @param[in] scale The scale factor - * - * @return The calculated number - * - * @see ::bin_frac_32_to_dec_frac - */ -static __mbg_inline -uint32_t frac_sec_from_bin( uint32_t b, uint32_t scale ) -{ - return bin_frac_32_to_dec_frac( b, scale ); - -} // frac_sec_from_bin - - - -#if !defined( MBG_TGT_KERNEL ) - -/** - * @brief Convert a binary fraction to "double" fractions - * - * Convert a binary fraction (e.g. of a second, as in ::PCPS_TIME_STAMP::frac) - * to a "double" with the units of seconds.<br> - * E.g. a 0xFFFFFFFF fraction yields 0.9999999999.... - * - * @note Excluded from build for kernel drivers which usually - * don't support floating point operations. - * - * @param[in] b The binary fraction - * - * @return The calculated fraction - * - * @see ::PCPS_HRT_BIN_FRAC_SCALE - */ -static __mbg_inline -double dfrac_sec_from_bin( uint32_t b ) -{ - return (double) b / (double) PCPS_HRT_BIN_FRAC_SCALE; - -} // dfrac_sec_from_bin - -#endif // !defined( MBG_TGT_KERNEL ) - - - #if !defined( MBG_TGT_KERNEL ) -/* function prototypes: */ - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ /** - * @brief Normalize a ::NANO_TIME_64 struct - * - * After normalization, the following can be assumed:<br> - * - nano_secs is in the range [-10^9 + 1, 10^9 - 1]<br> - * - if secs is not 0, secs and nano_secs have the same sign - * - * @param[in,out] nt The NANO_TIME_64 to be normalized - */ - void normalize_nano_time_64( NANO_TIME_64 *nt ) ; - - /** - * @brief Print a normalized ::NANO_TIME_64 into a string buffer - * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] nt The ::NANO_TIME_64 to be printed - */ - size_t snprint_nano_time_64( char *s, size_t max_len, const NANO_TIME_64 *nt ) ; - - /** - * @brief Print nano time into string buffer - * - * @param[out] s The string buffer to be filled - * @param[in] max_len Size of the output buffer for 0-terminated string - * @param[in] nt The ::NANO_TIME to be printed - */ - size_t snprint_nano_time( char *s, size_t max_len, const NANO_TIME *nt ) ; - - /** - * @brief Convert ::NANO_TIME_64 to ::TM_GPS - * - * @param[out] tm_gps The ::TM_GPS to be filled - * @param[in] nt The ::NANO_TIME_64 to be converted - * - * @return 1 on success, 0 on error - * - * @see ::tm_gps_to_nano_time_64 - */ - int nano_time_64_to_tm_gps( TM_GPS *tm_gps, const NANO_TIME_64 *nt ) ; - - /** - * @brief Convert ::TM_GPS to ::NANO_TIME_64 - * - * @param[out] nt The ::NANO_TIME_64 to be filled - * @param[in] tm The ::TM_GPS to be converted - * - * @return 1 on success, 0 on error - * - * @see ::nano_time_64_to_tm_gps - */ - int tm_gps_to_nano_time_64( NANO_TIME_64 *nt, const TM_GPS *tm ) ; - - /** * @brief Check if a software revision name should be displayed * * The software revision name is usually empty, except if the @@ -1274,10 +866,9 @@ double dfrac_sec_from_bin( uint32_t b ) * @param[in] all_io_port_info Pointer to the ::ALL_IO_PORT_INFO, containing the current configuration * @param[in] io_port_info_idx Pointer to the ::MBG_IO_PORT_INFO_IDX, for which the ::MBG_IO_PORT_TYPE_INFO_IDX shall be found * - * @return Pointer to the found ::MBG_IO_PORT_TYPE_INFO_IDX or NULL - * + * @return Pointer to the ::MBG_IO_PORT_TYPE_INFO_IDX found, or NULL */ - MBG_IO_PORT_TYPE_INFO_IDX *get_io_port_type_info_idx(ALL_IO_PORT_INFO *all_io_port_info, MBG_IO_PORT_INFO_IDX *io_port_info_idx) ; + MBG_IO_PORT_TYPE_INFO_IDX *get_io_port_type_info_idx( ALL_IO_PORT_INFO *all_io_port_info, MBG_IO_PORT_INFO_IDX *io_port_info_idx ) ; /** * @brief Initializes a ::MBG_TLV_ANNOUNCE structure @@ -1313,7 +904,7 @@ double dfrac_sec_from_bin( uint32_t b ) */ void mbg_tlv_rcv_state_init( MBG_TLV_RCV_STATE *state, MBG_TLV_UID uid, uint32_t total_bytes ) ; - size_t mbg_snprint_revision( char *buf, size_t buflen, const char *prefix, const char *suffix, uint32_t rev) ; + int mbg_snprint_revision( char *buf, size_t buflen, const char *prefix, const char *suffix, uint32_t rev) ; _NO_MBG_API_ATTR int _MBG_API chk_dev_xbp_supp_nodes( const ALL_XBP_INFO *info ) ; _NO_MBG_API_ATTR int _MBG_API chk_dev_net_cfg_supp_stage_2( const ALL_NET_CFG_INFO *info ) ; _NO_MBG_API_ATTR int _MBG_API chk_dev_ntp_supp_client( const ALL_NTP_CFG_INFO *info ) ; @@ -1351,7 +942,7 @@ double dfrac_sec_from_bin( uint32_t b ) * @return One of the @ref MBG_RETURN_CODES * * @see ::mbgextio_dev_has_gpio - * @see ::mbg_chk_dev_supp_gpio + * @see ::mbg_chk_dev_has_gpio * @see ::free_all_gpio_info */ _NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_has_status( const ALL_GPIO_INFO *info ) ; @@ -1469,7 +1060,6 @@ double dfrac_sec_from_bin( uint32_t b ) * @param[in] p Pointer to the ::ALL_IMS_INFO structure, which will be freed * * @see ::mbgextio_dev_has_ims - * @see ::mbgextio_dev_ims_has_fdm * @see ::mbgextio_get_all_ims_info * @see ::mbgextio_get_all_ims_state */ @@ -1481,7 +1071,6 @@ double dfrac_sec_from_bin( uint32_t b ) * @param[in] p Pointer to the ::ALL_IMS_STATE structure, which will be freed * * @see ::mbgextio_dev_has_ims - * @see ::mbgextio_dev_ims_has_fdm * @see ::mbgextio_get_all_ims_info * @see ::mbgextio_get_all_ims_state */ @@ -1542,9 +1131,9 @@ double dfrac_sec_from_bin( uint32_t b ) /** * Allocates memory for a new ::UCAP_ENTRY structure * - * @return The new allocated ::UCAP_ENTRY or null if the calloc call was not successful + * @return The new allocated ::UCAP_ENTRY or NULL if the calloc call was not successful */ - UCAP_ENTRY* calloc_ucap_entry(void) ; + UCAP_ENTRY* calloc_ucap_entry( void ) ; /** * @brief Frees memory allocated by ::mbgextio_get_all_ucap_info @@ -1569,6 +1158,38 @@ double dfrac_sec_from_bin( uint32_t b ) */ void free_all_ucap_net_info( ALL_UCAP_NET_INFO *p ) ; + /** + * @brief Set up a ::NTP_TSTAMP structure from a hex string with a time in seconds and binary fractions + * + * @param[in] s A string with a time in seconds since NTP epoch 1900-01-01, + * with binary fractions separated by decimal point, + * e.g. 'dc763e43.73bd5a8f' as printed by the ntpq utility + * @param[out] p Address of a ::NTP_TSTAMP structure to be set up + * + * @see ::str_ntp_hex_to_nano_time_64 + */ + void str_ntp_hex_to_ntp_tstamp( const char *s, NTP_TSTAMP *p ) ; + + /** + * @brief Convert a ::NTP_TSTAMP structure to a ::NANO_TIME_64 structure + * + * @param[in] p_nts The ::NTP_TSTAMP structure to be converted + * @param[out] p_nt64 The ::NANO_TIME_64 structure to be filled up + */ + void ntp_tstamp_to_nanotime_64( const NTP_TSTAMP *p_nts, NANO_TIME_64 *p_nt64 ) ; + + /** + * @brief Set up a ::NANO_TIME_64 structure from a hex string with a time in seconds and binary fractions + * + * @param[in] s A string with a time in seconds since epoch 1900-01-01, + * with binary fractions separated by decimal point, + * e.g. 'dc763e43.73bd5a8f' as printed by the ntpq utility + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + * + * @see ::str_ntp_hex_to_ntp_tstamp + */ + void str_ntp_hex_to_nano_time_64( const char *s, NANO_TIME_64 *p ) ; + /* ----- function prototypes end ----- */ diff --git a/mbglib/common/charcode.h b/mbglib/common/charcode.h index 192a0f4..9605c95 100755 --- a/mbglib/common/charcode.h +++ b/mbglib/common/charcode.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: charcode.h 1.4 2016/08/10 12:25:41 martin TEST $ + * $Id: charcode.h 1.4 2016/08/10 12:25:41 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * diff --git a/mbglib/common/chk_time_info.c b/mbglib/common/chk_time_info.c index 67d7106..e1d1756 100755 --- a/mbglib/common/chk_time_info.c +++ b/mbglib/common/chk_time_info.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: chk_time_info.c 1.3.1.1.1.3 2015/09/03 11:19:15 martin TEST $ + * $Id: chk_time_info.c 1.4 2017/07/05 09:00:14 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,15 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: chk_time_info.c $ - * Revision 1.3.1.1.1.3 2015/09/03 11:19:15 martin - * Made mbg_snprint_hr_tstamp() more versatile - * by passing a new optional UTC offset parameter. - * Revision 1.3.1.1.1.2 2015/08/27 16:29:44 martin + * Revision 1.4 2017/07/05 09:00:14 martin * Use safe string functions from str_util.c. - * Revision 1.3.1.1.1.1 2014/11/10 10:35:57 martin - * Temporarily use a different definition of NANO_TIME_64. - * Revision 1.3.1.1 2013/11/08 14:56:36 martin - * Preliminary changes. + * Account for PCPS_HRT_BIN_FRAC_SCALE renamed + * to MBG_FRAC32_UNITS_PER_SEC. * Revision 1.3 2013/07/30 12:55:33 martin * Updated file description. * Revision 1.2 2013/03/04 16:01:01 martin @@ -93,7 +88,7 @@ int mbg_chk_time_info( MBG_DEV_HANDLE dh, MBG_CHK_TIME_INFO *p, FILTER *p_filter 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_ref = (double) p_ref_ts->sec + ( (double) p_ref_ts->frac ) / (double) MBG_FRAC32_UNITS_PER_SEC; p->d_sys = (double) p_sys_tic->sys_time.secs + (double) p_sys_tic->sys_time.nano_secs / 1e9; p->ltcy_cyc = mbg_delta_pc_cycles( p_ref_cyc, &p_sys_tic->cyc_after ); diff --git a/mbglib/common/chk_time_info.h b/mbglib/common/chk_time_info.h index c1fc4b7..1a66f6b 100755 --- a/mbglib/common/chk_time_info.h +++ b/mbglib/common/chk_time_info.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: chk_time_info.h 1.2.1.1 2015/08/27 16:29:54 martin TEST $ + * $Id: chk_time_info.h 1.3 2017/07/05 09:01:46 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: chk_time_info.h $ - * Revision 1.2.1.1 2015/08/27 16:29:54 martin + * Revision 1.3 2017/07/05 09:01:46 martin + * Tiny cleanup. + * Updated function prototypes. * Revision 1.2 2013/03/04 16:02:31 martin * Updated function prototypes. * Revision 1.1 2012/05/29 09:52:27 martin @@ -81,8 +83,6 @@ typedef struct -/* function prototypes: */ - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/cmp_time_util.c b/mbglib/common/cmp_time_util.c deleted file mode 100755 index de4c142..0000000 --- a/mbglib/common/cmp_time_util.c +++ /dev/null @@ -1,287 +0,0 @@ - -/************************************************************************** - * - * $Id: cmp_time_util.c 1.1.1.3 2014/05/26 16:01:48 martin TEST $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Shared time campare utility functions. - * - * ----------------------------------------------------------------------- - * $Log: cmp_time_util.c $ - * Revision 1.1.1.3 2014/05/26 16:01:48 martin - * Revision 1.1.1.2 2013/08/01 16:51:39 martin - * Revision 1.1.1.1 2013/08/01 15:17:30 marvin - * Revision 1.1 2013/07/25 10:42:59Z martin - * Initial revision. - * - **************************************************************************/ - -#define _CMP_TIME_UTIL - #include <cmp_time_util.h> -#undef _CMP_TIME_UTIL - -#include <mbgdevio.h> -#include <mbgutil.h> -#include <pcpsutil.h> -#include <stdio.h> - - -//##++++++ -extern MBG_PC_CYCLES_FREQUENCY cyc_freq; - - -/*HDR*/ -int chk_feat_supp( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, MBG_CHK_SUPP_FNC *chk_supp_fnc, - MBG_ERR_MSG_FNC err_msg_fnc, const char *not_supp_msg ) -{ - int ret_val = MBG_SUCCESS; // assume option is supported - - // If a check function has been specified we must call it to check - // if this parameter/command is supported by this particular device. - if ( chk_supp_fnc && ( dh != MBG_INVALID_DEV_HANDLE ) ) - { - int is_supported; - int rc = chk_supp_fnc( dh, &is_supported ); - - if ( rc != MBG_SUCCESS ) - { - if ( err_msg_fnc ) - err_msg_fnc( p_dev, "Failed to check if supported" ); //##++++ TODO:proper error msg - - ret_val = rc; - goto out; - } - - if ( !is_supported ) - { - ret_val = MBG_ERR_NOT_SUPP_BY_DEV; - - if ( err_msg_fnc && not_supp_msg ) - err_msg_fnc( p_dev, not_supp_msg ); - - goto out; - } - } - -out: - return ret_val; - -} // chk_feat_supp - - - -/*HDR*/ -int chk_fast_tstamp_supp( MBG_DEV_HANDLE dh1, const PCPS_DEV *p_dev_1, - MBG_DEV_HANDLE dh2, const PCPS_DEV *p_dev_2, - MBG_ERR_MSG_FNC err_msg_fnc ) -{ - int rc; - const char n_supp_msg[] = "fast (memory mapped) time stamps"; - - rc = chk_feat_supp( dh1, p_dev_1, mbg_dev_has_fast_hr_timestamp, - err_msg_fnc, n_supp_msg ); - - if ( rc == MBG_SUCCESS ) - rc = chk_feat_supp( dh2, p_dev_2, mbg_dev_has_fast_hr_timestamp, - err_msg_fnc, n_supp_msg ); - return rc; - -} // chk_fast_tstamp_supp - - - -/*HDR*/ -int get_htc_timestamps( MBG_DEV_HANDLE dh1, PCPS_HR_TIME_CYCLES *p_htc1, - MBG_DEV_HANDLE dh2, PCPS_HR_TIME_CYCLES *p_htc2, - int read_fast ) -{ - int rc; - - if ( read_fast ) - { - PCPS_TIME_STAMP_CYCLES ts_c1; - PCPS_TIME_STAMP_CYCLES ts_c2; - - rc = mbg_get_fast_hr_timestamp_cycles( dh1, &ts_c1 ); - - if ( mbg_ioctl_err( rc, "mbg_get_fast_hr_timestamp_cycles 1" ) ) - goto done; - - rc = mbg_get_fast_hr_timestamp_cycles( dh2, &ts_c2 ); - - if ( mbg_ioctl_err( rc, "mbg_get_fast_hr_timestamp_cycles 2" ) ) - goto done; - - setup_hr_time_cycles_from_timestamp_cycles( p_htc1, &ts_c1 ); - setup_hr_time_cycles_from_timestamp_cycles( p_htc2, &ts_c2 ); - } - else - { - rc = mbg_get_hr_time_cycles( dh1, p_htc1 ); - - if ( mbg_ioctl_err( rc, "mbg_get_hr_time_cycles 1" ) ) - goto done; - - rc = mbg_get_hr_time_cycles( dh2, p_htc2 ); - - if ( mbg_ioctl_err( rc, "mbg_get_hr_time_cycles 2" ) ) - goto done; - } - -done: - return rc; - -} // get_htc_timestamps - - - -/*HDR*/ -double get_htc_delta( const PCPS_HR_TIME_CYCLES *p_htc, - const PCPS_HR_TIME_CYCLES *p_htc_ref, - double *p_delta_ts, double *p_delta_cyc ) -{ - double delta_ts; - double delta_cyc; - - delta_ts = (double) p_htc->t.tstamp.sec + dfrac_sec_from_bin( p_htc->t.tstamp.frac ) - - (double) p_htc_ref->t.tstamp.sec - dfrac_sec_from_bin( p_htc_ref->t.tstamp.frac ); - - #if defined( MBG_TGT_WIN32 ) - { - __int64 dt_t = p_htc->cycles - p_htc_ref->cycles; - delta_cyc = (double) dt_t / (__int64) cyc_freq; - } - #else - delta_cyc = ( (double) ( p_htc->cycles - p_htc_ref->cycles ) ) / cyc_freq; - #endif - - if ( p_delta_ts ) - *p_delta_ts = delta_ts; - - if ( p_delta_cyc ) - *p_delta_cyc = delta_cyc; - - return delta_ts - delta_cyc; - -} // get_htc_delta - - - -/*HDR*/ -int mbg_snprint_hr_tstamp_ext( char *s, int max_len, - const PCPS_TIME_STAMP *p_ts, int print_raw ) -{ - int n = mbg_snprint_hr_tstamp( s, max_len, p_ts, 0 ); - - if ( print_raw ) - n += snprintf( &s[n], max_len - n, " (0x%08lX.%08lX)", - (ulong) p_ts->sec, - (ulong) p_ts->frac ); - - return n; - -} // mbg_snprint_hr_tstamp_ext - - - -#if defined( MBG_WX ) - -/*HDR*/ -int mbg_snprint_hr_tstamp( char *s, int len_s, const PCPS_TIME_STAMP *p, int show_raw ) -{ - int n = 0; - - // We'll use the standard C library functions to convert the seconds - // to broken-down calendar date and time. - time_t t = p->sec; - - // Our time stamp may be UTC, or have been converted to local time. - // Anyway, since we don't want to account for the system's time zone - // settings, we always use the gmtime() function for conversion: - struct tm *tmp = gmtime( &t ); - - if ( show_raw ) - n += snprintf( s + n, len_s - n, "raw: 0x%08lX.%08lX, ", - (ulong) p->sec, - (ulong) p->frac ); - - n += snprintf( s + n, len_s - n, "%04i-%02i-%02i %02i:%02i:%02i." PCPS_HRT_FRAC_SCALE_FMT, - tmp->tm_year + 1900, - tmp->tm_mon + 1, - tmp->tm_mday, - tmp->tm_hour, - tmp->tm_min, - tmp->tm_sec, - (ulong) frac_sec_from_bin( p->frac, PCPS_HRT_FRAC_SCALE ) - ); - - return n; - -} // mbg_snprint_hr_tstamp - -#endif - - - -/*HDR*/ -int mbg_snprint_hr_time_loc( char *s, int len_s, const PCPS_HR_TIME *p ) -{ - int n = 0; - - // We'll use the standard C library functions to convert the seconds - // to broken-down calendar date and time. - time_t t = p->tstamp.sec + p->utc_offs; - - // Our time stamp may be UTC, or have been converted to local time. - // Anyway, since we don't want to account for the system's time zone - // settings, we always use the gmtime() function for conversion: - struct tm *tmp = gmtime( &t ); - - n += snprintf( s + n, len_s - n, "%04i-%02i-%02i %02i:%02i:%02i." PCPS_HRT_FRAC_SCALE_FMT, - tmp->tm_year + 1900, - tmp->tm_mon + 1, - tmp->tm_mday, - tmp->tm_hour, - tmp->tm_min, - tmp->tm_sec, - (ulong) frac_sec_from_bin( p->tstamp.frac, PCPS_HRT_FRAC_SCALE ) - ); - - n += snprintf( s + n, len_s - n, " UTC" ); - - if ( !(p->status & PCPS_UTC ) ) - n += mbg_str_pcps_hr_time_offs( s + n, len_s - n, p, "" ); - -#if 0 - if(p->utc_offs != 0) - n += mbg_snprintf( n, len_s - n, "(%+02luh", - ( pt->utc_offs < 0 ) ? '-' : '+', - ldt.quot, ldt.rem ); -#endif - - return n; - -} // mbg_snprint_hr_time_loc - - - -#if defined( MBG_WX ) - -/*HDR*/ -int mbg_ioctl_err( int rc, const char *descr ) -{ - if ( rc < 0 ) - { - fprintf( stderr, "** IOCTL error %i: ", rc ); - perror( descr ); - return -1; - } - - return 0; - -} // mbg_ioctl_err - -#endif - diff --git a/mbglib/common/cmp_time_util.h b/mbglib/common/cmp_time_util.h deleted file mode 100755 index 88dcd73..0000000 --- a/mbglib/common/cmp_time_util.h +++ /dev/null @@ -1,87 +0,0 @@ - -/************************************************************************** - * - * $Id: cmp_time_util.h 1.1.2.1 2015/07/09 08:16:46 martin TEST $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for cmp_time_util.c. - * - * ----------------------------------------------------------------------- - * $Log: cmp_time_util.h $ - * Revision 1.1.2.1 2015/07/09 08:16:46 martin - * Tmp. backward compatibility patch for mbgtools-lx-dev-2014-12-02. - * Revision 1.1 2013/07/25 10:42:59 martin - * Initial revision. - * - **************************************************************************/ - -#ifndef _CMP_TIME_UTIL_H -#define _CMP_TIME_UTIL_H - - -/* Other headers to be included */ - -#include <mbgdevio.h> -#include <toolutil.h> - - -#ifdef _CMP_TIME_UTIL - #define _ext - #define _DO_INIT -#else - #define _ext extern -#endif - - -/* Start of header body */ - -#if 0 && defined( _USE_PACK ) // use default alignment - #pragma pack( 1 ) // set byte alignment - #define _USING_BYTE_ALIGNMENT -#endif - -#ifdef __cplusplus -extern "C" { -#endif - -typedef int (*MBG_ERR_MSG_FNC)( const PCPS_DEV *p_dev, const char *s ); - -typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh, int *p ); - - - -/* function prototypes: */ - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - int chk_feat_supp( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, MBG_CHK_SUPP_FNC *chk_supp_fnc, MBG_ERR_MSG_FNC err_msg_fnc, const char *not_supp_msg ) ; - int chk_fast_tstamp_supp( MBG_DEV_HANDLE dh1, const PCPS_DEV *p_dev_1, MBG_DEV_HANDLE dh2, const PCPS_DEV *p_dev_2, MBG_ERR_MSG_FNC err_msg_fnc ) ; - int get_htc_timestamps( MBG_DEV_HANDLE dh1, PCPS_HR_TIME_CYCLES *p_htc1, MBG_DEV_HANDLE dh2, PCPS_HR_TIME_CYCLES *p_htc2, int read_fast ) ; - double get_htc_delta( const PCPS_HR_TIME_CYCLES *p_htc, const PCPS_HR_TIME_CYCLES *p_htc_ref, double *p_delta_ts, double *p_delta_cyc ) ; - int mbg_snprint_hr_tstamp_ext( char *s, int max_len, const PCPS_TIME_STAMP *p_ts, 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 /* _CMP_TIME_UTIL_H */ - diff --git a/mbglib/common/cnv_wday.h b/mbglib/common/cnv_wday.h index 7736135..327d69d 100755 --- a/mbglib/common/cnv_wday.h +++ b/mbglib/common/cnv_wday.h @@ -1,7 +1,7 @@ /***************************************************************************/ /* */ -/* File: CNV_WDAY.H $Revision: 1.1 $ */ +/* File: CNV_WDAY.H $Revision: 1.2 $ */ /* */ /* Project: Common C Library */ /* */ @@ -24,18 +24,10 @@ /* */ /***************************************************************************/ - #ifndef _CNV_WDAY_H - /* Other headers to be included */ - - -#ifdef __cplusplus -extern "C" { -#endif - #ifdef _CNV_WDAY #define _ext #else @@ -45,6 +37,10 @@ extern "C" { /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + /* use the following macros if sure that the source value is in range */ @@ -80,11 +76,6 @@ extern "C" { #define _wday_chk_sun17_to_sun06( d ) _inrng( (d), _wday_sun17_to_sun06( (d) ), 1, 0, 7, 6 ) #define _wday_chk_sun06_to_sun17( d ) _inrng( (d), _wday_sun06_to_sun17( (d) ), 0, 1, 6, 7 ) - -/* function prototypes: */ - -/* #include <CNV_WDAY.hdr> not needed yet */ - /* End of header body */ diff --git a/mbglib/common/ctry.h b/mbglib/common/ctry.h index 8406a76..3d791ff 100755 --- a/mbglib/common/ctry.h +++ b/mbglib/common/ctry.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: ctry.h 1.13 2012/11/29 12:01:09 martin REL_M $ + * $Id: ctry.h 1.14 2017/06/23 09:53:27 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,8 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: ctry.h $ + * Revision 1.14 2017/06/23 09:53:27 martin + * Fixed spelling in an earlier log message. * Revision 1.13 2012/11/29 12:01:09 martin - * Don't include mbg_tgt.h explicitely since this will anyway be + * Don't include mbg_tgt.h explicitly since this will anyway be * included by words.h for non-firmware targets. So mbg_tgt.h * must not necessarily be added to firmware projects. * Revision 1.12 2011/06/22 07:37:57Z martin @@ -36,11 +38,11 @@ * Revision 1.4 2000/11/27 14:13:27 MARTIN * New types CLSTR, PLSTR, and PCLSTR. * New macro _lstr() calls lstr_lng() for the current language. - * Definitions associated with ctry_fmt_dt() and ctry_fmt_times() + * Definitions associated with ctry_fmt_dt() and ctry_fmt_times() * have been moved to a new file ctry_fmt.h. * Updated function prototypes. * Revision 1.3 2000/08/17 15:35:02 MARTIN - * No init function by default (previously DOS), + * No init function by default (previously DOS), * Revision 1.2 2000/07/21 09:48:34 MARTIN * Initial revision * diff --git a/mbglib/common/deviohlp.c b/mbglib/common/deviohlp.c index 991a1a2..b0a1180 100755 --- a/mbglib/common/deviohlp.c +++ b/mbglib/common/deviohlp.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: deviohlp.c 1.2.1.47 2016/11/08 17:21:49 martin TEST $ + * $Id: deviohlp.c 1.3 2017/07/05 13:47:44 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -18,106 +18,13 @@ * * ----------------------------------------------------------------------- * $Log: deviohlp.c $ - * Revision 1.2.1.47 2016/11/08 17:21:49 martin - * Doxygen fixes. - * Revision 1.2.1.46 2016/09/08 10:36:20 martin - * Removed obsolete parameter from an API call. - * Revision 1.2.1.45 2016/08/25 13:52:06Z thomas-b - * Adapted net_cfg functions to the structure changes - * Revision 1.2.1.44 2016/08/09 07:09:41 martin - * *** empty log message *** - * Revision 1.2.1.43 2016/07/22 09:58:45 martin - * Excluded some test code from build. - * Revision 1.2.1.42 2016/06/21 14:13:26 thomas-b - * Fixed bug when checking if ttm is available - * Revision 1.2.1.41 2016/06/21 12:07:35 thomas-b - * Adapted mbg_get_all_ucap_info to the new ALL_UCAP_INFO structure - * Revision 1.2.1.40 2016/06/15 14:04:06 thomas-b - * Added function mbg_get_all_ucap_info - * Revision 1.2.1.39 2016/06/01 11:35:29 martin - * Removed some code which is now in mbgdevio.c,h. - * Revision 1.2.1.38 2016/06/01 10:07:44 daniel - * *** empty log message *** - * Revision 1.2.1.37 2016/05/26 11:00:10 thomas-b - * Added parameter ALL_NTP_CFG_INFO to mbgextio_get_all_ntp_status - * Use calloc instead of realloc due to performance improvement - * Revision 1.2.1.36 2016/05/11 14:37:20 thomas-b - * Added functions to read/write ALL_NET_CFG_INFO and ALL_NET_STATUS_INFO - * Revision 1.2.1.35 2016/04/26 09:11:11 martin - * Made pcps_time_is_valid an inline function. - * Revision 1.2.1.34 2016/04/25 14:47:56Z martin - * *** empty log message *** - * Revision 1.2.1.33 2016/04/20 12:37:54 thomas-b - * Moved free functions for ALL_XMULTI_REF_INFO and ALL_XMULTI_REF_STATUS to cfg_hlp - * Revision 1.2.1.32 2016/04/18 14:45:29 thomas-b - * Added functions to get and save xmr info and status - * Revision 1.2.1.31 2016/04/04 12:29:30 thomas-b - * Reworked chk_bus_flags and PCI/PCI-E functions - * Revision 1.2.1.30 2016/03/30 07:56:55 thomas-b - * Fixed chk_bus_flags and mbg_chk_dev_is_pci - * Revision 1.2.1.29 2016/03/24 14:08:46 martin - * *** empty log message *** - * Revision 1.2.1.28 2016/03/22 10:53:29 martin - * *** empty log message *** - * Revision 1.2.1.27 2016/03/10 10:11:58 thomas-b - * Added functions, which check to which bus a device is connected - * Revision 1.2.1.26 2015/11/20 15:18:09 martin - * Revision 1.2.1.25 2015/11/02 11:00:48Z martin - * *** empty log message *** - * Revision 1.2.1.24 2015/10/28 16:06:40 martin - * Revision 1.2.1.23 2015/10/26 14:13:22Z martin - * Revision 1.2.1.22 2015/10/26 14:15:22Z martin - * Revision 1.2.1.21 2015/10/21 11:31:17Z martin - * *** empty log message *** - * Revision 1.2.1.20 2015/10/21 11:29:16 martin - * *** empty log message *** - * Revision 1.2.1.19 2015/10/21 11:21:51 martin - * *** empty log message *** - * Revision 1.2.1.18 2015/10/20 15:19:24 martin - * *** empty log message *** - * Revision 1.2.1.17 2015/10/19 16:42:15 martin - * *** empty log message *** - * Revision 1.2.1.16 2015/10/12 10:12:31 martin - * *** empty log message *** - * Revision 1.2.1.15 2015/10/08 13:27:37 martin - * *** empty log message *** - * Revision 1.2.1.14 2015/10/07 16:03:20 martin - * *** empty log message *** - * Revision 1.2.1.13 2015/10/07 10:54:19 martin - * Modified GNSS support. - * Revision 1.2.1.12 2015/09/17 10:05:17 martin - * Revision 1.2.1.11 2015/09/15 09:11:50Z martin - * *** empty log message *** - * Revision 1.2.1.10 2014/11/19 16:02:52 martin - * Revision 1.2.1.9 2014/10/29 16:25:31 martin - * Moved some functions and structures to more convenient files. - * Revision 1.2.1.8 2014/10/27 10:43:18 martin - * Revision 1.2.1.7 2014/07/14 15:42:45 martin - * Revision 1.2.1.6 2014/06/30 15:43:44 martin - * Revision 1.2.1.5 2014/04/28 12:21:26 martin - * Revision 1.2.1.4 2014/04/28 10:32:40 martin - * Revision 1.2.1.3 2014/04/28 09:49:15 martin - * Revision 1.2.1.2 2013/12/17 15:05:31 martin - * Revision 1.2.1.1 2013/12/16 13:53:27Z martin - * GNSS support + * Revision 1.3 2017/07/05 13:47:44 martin + * Many configuration functions provided by thomas-b, + * philipp, and martin. * Revision 1.2 2012/10/15 13:48:35Z martin * Added functions mbg_get_all_ptp_cfg_info(), mbg_save_all_ptp_cfg_info(). - * Revision 1.1.1.9 2012/07/18 11:00:46 martin - * Revision 1.1.1.8 2012/07/12 09:07:36Z martin - * Revision 1.1.1.7 2012/07/12 08:38:50Z martin * Account for renamed structure. - * Revision 1.1.1.6 2012/07/10 09:53:57 martin - * Revision 1.1.1.5 2012/04/11 15:45:10Z martin * Updated doxygen comments. - * Revision 1.1.1.4 2011/09/21 14:45:24 martin - * Moved mbgextio support functions to new module extiohlp.c. - * Revision 1.1.1.3 2011/09/20 15:36:02 marvin - * new functions: - * mbg_get_serial_settings - * mbg_set_serial_settings - * include mbgextio.h - * Revision 1.1.1.2 2011/08/05 10:30:28 martin - * Revision 1.1.1.1 2011/08/05 09:55:52 martin * Revision 1.1 2011/08/03 15:37:00Z martin * Initial revision with functions moved here from mbgdevio. * @@ -166,7 +73,7 @@ /*HDR*/ int chk_feat_supp( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, MBG_CHK_SUPP_FNC *chk_supp_fnc, - MBG_ERR_MSG_FNC err_msg_fnc, const char *not_supp_msg ) + MBG_ERR_MSG_FNC *err_msg_fnc, const char *not_supp_msg ) { const char *cp = NULL; int rc = MBG_SUCCESS; // assume option is supported @@ -940,8 +847,8 @@ out: * @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 + * @see ::mbg_chk_dev_has_ptp + * @see ::mbg_chk_dev_has_ptp_unicast */ int mbg_get_all_ptp_cfg_info( MBG_DEV_HANDLE dh, ALL_PTP_CFG_INFO *p ) { @@ -996,8 +903,8 @@ int mbg_get_all_ptp_cfg_info( MBG_DEV_HANDLE dh, ALL_PTP_CFG_INFO *p ) * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_set_ptp_cfg_settings * @see ::mbg_set_ptp_uc_master_settings_idx - * @see ::mbg_dev_has_ptp - * @see ::mbg_dev_has_ptp_unicast + * @see ::mbg_chk_dev_has_ptp + * @see ::mbg_chk_dev_has_ptp_unicast */ int mbg_save_all_ptp_cfg_info( MBG_DEV_HANDLE dh, const ALL_PTP_CFG_INFO *p ) { @@ -1040,7 +947,7 @@ int mbg_save_all_ptp_cfg_info( MBG_DEV_HANDLE dh, const ALL_PTP_CFG_INFO *p ) /** * @brief Read all XMR info into a newly or re-allocated ::ALL_XMULTI_REF_INFO * - * @note ::mbg_chk_dev_supp_xmr should be called before using this function + * @note ::mbg_chk_dev_has_xmr should be called before using this function * * A ::ALL_XMULTI_REF_INFO and a number of ::XMULTI_REF_INSTANCES::n_xmr_settings * of ::XMULTI_REF_INFO_IDX and ::XMR_EXT_SRC_INFO_IDX will be allocated and needs @@ -1157,7 +1064,7 @@ _NO_MBG_API_ATTR int _MBG_API mbg_save_all_xmulti_ref_info( MBG_DEV_HANDLE dh, A /** * @brief Read all XMR status info into a newly or re-allocated ::ALL_XMULTI_REF_STATUS * - * @note ::mbg_chk_dev_supp_xmr should be called before using this function + * @note ::mbg_chk_dev_has_xmr should be called before using this function * * A ::ALL_XMULTI_REF_STATUS and a number of ::XMULTI_REF_INSTANCES::n_xmr_settings * of ::XMULTI_REF_STATUS_IDX will be allocated and needs to be freed by calling @@ -1328,7 +1235,7 @@ void test_gpio( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int verbose ) ALL_GPIO_INFO_IDX all_gpio_info_idx = { { 0 } }; ALL_GPIO_STATUS_IDX all_gpio_status_idx = { { 0 } }; - rc = mbg_chk_dev_supp_gpio( dh ); + rc = mbg_chk_dev_has_gpio( dh ); printf( "\nGPIO chk supp: %i\n", rc ); @@ -1461,7 +1368,7 @@ void test_xmr( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int verbose ) int rc; int i; - rc = mbg_chk_dev_supp_xmr( dh ); + rc = mbg_chk_dev_has_xmr( dh ); printf( "\nXMR chk supp: %i\n", rc ); diff --git a/mbglib/common/deviohlp.h b/mbglib/common/deviohlp.h index 95b9aa8..f06b72a 100755 --- a/mbglib/common/deviohlp.h +++ b/mbglib/common/deviohlp.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: deviohlp.h 1.3.1.29 2016/11/08 17:21:56 martin TEST $ + * $Id: deviohlp.h 1.4 2017/07/05 13:50:18 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,57 +10,11 @@ * * ----------------------------------------------------------------------- * $Log: deviohlp.h $ - * Revision 1.3.1.29 2016/11/08 17:21:56 martin - * Updated function prototypes. - * Revision 1.3.1.28 2016/09/08 10:36:37 martin - * Removed obsolete parameter from an API call. - * Revision 1.3.1.27 2016/06/15 14:04:06Z thomas-b - * Added function mbg_get_all_ucap_info - * Revision 1.3.1.26 2016/06/01 11:35:30 martin - * Removed some code which is now in mbgdevio.c,h. - * Revision 1.3.1.25 2016/05/26 11:00:10 thomas-b - * Added parameter ALL_NTP_CFG_INFO to mbgextio_get_all_ntp_status - * Use calloc instead of realloc due to performance improvement - * Revision 1.3.1.24 2016/05/11 14:37:21 thomas-b - * Added functions to read/write ALL_NET_CFG_INFO and ALL_NET_STATUS_INFO - * Revision 1.3.1.23 2016/04/26 09:12:24 martin - * Made pcps_time_is_valid an inline function. - * Revision 1.3.1.22 2016/04/25 14:47:56Z martin - * *** empty log message *** - * Revision 1.3.1.21 2016/04/20 12:37:54 thomas-b - * Moved free functions for ALL_XMULTI_REF_INFO and ALL_XMULTI_REF_STATUS to cfg_hlp - * Revision 1.3.1.20 2016/04/18 14:45:30 thomas-b - * Added functions to get and save xmr info and status - * Revision 1.3.1.19 2016/03/24 14:08:46 martin - * *** empty log message *** - * Revision 1.3.1.18 2016/03/22 10:53:29 martin - * *** empty log message *** - * Revision 1.3.1.17 2016/03/10 10:11:58 thomas-b - * Added functions, which check to which bus a device is connected - * Revision 1.3.1.16 2015/11/20 15:18:27 martin - * Revision 1.3.1.15 2015/10/26 16:32:09Z martin - * *** empty log message *** - * Revision 1.3.1.14 2015/10/26 14:15:27 martin - * Revision 1.3.1.13 2015/10/21 11:31:17Z martin - * *** empty log message *** - * Revision 1.3.1.12 2015/10/21 11:29:16 martin - * *** empty log message *** - * Revision 1.3.1.11 2015/10/21 11:21:51 martin - * *** empty log message *** - * Revision 1.3.1.10 2015/10/19 16:42:16 martin - * *** empty log message *** - * Revision 1.3.1.9 2015/10/07 16:03:21 martin - * *** empty log message *** - * Revision 1.3.1.8 2015/10/07 10:54:19 martin - * Modified GNSS support. - * Revision 1.3.1.7 2014/10/29 16:25:32 martin - * Moved some functions and structures to more convenient files. - * Revision 1.3.1.6 2014/07/14 15:42:45 martin - * Revision 1.3.1.5 2014/06/30 15:43:44 martin - * Revision 1.3.1.4 2014/04/28 12:21:27 martin - * Revision 1.3.1.3 2014/04/28 10:32:40 martin - * Revision 1.3.1.2 2013/12/17 15:05:32 martin - * Revision 1.3.1.1 2013/12/16 13:53:45Z martin + * Revision 1.4 2017/07/05 13:50:18 martin + * Moved definition of PCPS_SER_PACK here. + * Defined function type MBG_ERR_MSG_FNC. + * New structure PCPS_TIME_EXT. + * New inline function pcps_time_is_valid(). * Updated function prototypes. * Revision 1.3 2013/09/26 08:25:18Z martin * Moved ALL_PTP_CFG_INFO definition to cfg_hlp.h. @@ -118,7 +72,7 @@ typedef struct -typedef int (*MBG_ERR_MSG_FNC)( const PCPS_DEV *p_dev, const char *s ); +typedef int MBG_ERR_MSG_FNC( const PCPS_DEV *p_dev, const char *s ); /** @@ -167,14 +121,12 @@ int pcps_time_is_valid( const PCPS_TIME *p ) -/* function prototypes: */ - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ - int chk_feat_supp( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, MBG_CHK_SUPP_FNC *chk_supp_fnc, MBG_ERR_MSG_FNC err_msg_fnc, const char *not_supp_msg ) ; + int chk_feat_supp( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, MBG_CHK_SUPP_FNC *chk_supp_fnc, MBG_ERR_MSG_FNC *err_msg_fnc, const char *not_supp_msg ) ; /** * @brief Read or setup all GNSS status information * @@ -342,8 +294,8 @@ int pcps_time_is_valid( const PCPS_TIME *p ) * @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 + * @see ::mbg_chk_dev_has_ptp + * @see ::mbg_chk_dev_has_ptp_unicast */ int mbg_get_all_ptp_cfg_info( MBG_DEV_HANDLE dh, ALL_PTP_CFG_INFO *p ) ; @@ -362,15 +314,15 @@ int pcps_time_is_valid( const PCPS_TIME *p ) * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_set_ptp_cfg_settings * @see ::mbg_set_ptp_uc_master_settings_idx - * @see ::mbg_dev_has_ptp - * @see ::mbg_dev_has_ptp_unicast + * @see ::mbg_chk_dev_has_ptp + * @see ::mbg_chk_dev_has_ptp_unicast */ int mbg_save_all_ptp_cfg_info( MBG_DEV_HANDLE dh, const ALL_PTP_CFG_INFO *p ) ; /** * @brief Read all XMR info into a newly or re-allocated ::ALL_XMULTI_REF_INFO * - * @note ::mbg_chk_dev_supp_xmr should be called before using this function + * @note ::mbg_chk_dev_has_xmr should be called before using this function * * A ::ALL_XMULTI_REF_INFO and a number of ::XMULTI_REF_INSTANCES::n_xmr_settings * of ::XMULTI_REF_INFO_IDX and ::XMR_EXT_SRC_INFO_IDX will be allocated and needs @@ -403,7 +355,7 @@ int pcps_time_is_valid( const PCPS_TIME *p ) /** * @brief Read all XMR status info into a newly or re-allocated ::ALL_XMULTI_REF_STATUS * - * @note ::mbg_chk_dev_supp_xmr should be called before using this function + * @note ::mbg_chk_dev_has_xmr should be called before using this function * * A ::ALL_XMULTI_REF_STATUS and a number of ::XMULTI_REF_INSTANCES::n_xmr_settings * of ::XMULTI_REF_STATUS_IDX will be allocated and needs to be freed by calling diff --git a/mbglib/common/gpsdefs.h b/mbglib/common/gpsdefs.h index e83cf8c..32194a6 100755 --- a/mbglib/common/gpsdefs.h +++ b/mbglib/common/gpsdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: gpsdefs.h 1.124.1.312 2017/05/03 13:45:42 philipp TEST $ + * $Id: gpsdefs.h 1.125 2017/07/05 18:18:27 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -13,656 +13,75 @@ * * ----------------------------------------------------------------------- * $Log: gpsdefs.h $ - * Revision 1.124.1.312 2017/05/03 13:45:42 philipp - * Refactored event types - * Revision 1.124.1.311 2017/04/25 11:36:24 martin - * Renamed GRC181PEX to GNS181PEX. - * Revision 1.124.1.310 2017/04/11 10:30:14 philipp - * Added USB lock swap macros - * Revision 1.124.1.309 2017/04/11 06:42:41 philipp - * Renamed MBG_USB_INTR structures to MBG_USB_LOCK - * Revision 1.124.1.308 2017/04/11 06:22:29 philipp - * Put MBG_USB_INTR_SETTINGS into MBG_USB_INTR_INFO - * Revision 1.124.1.307 2017/04/11 05:29:56 philipp - * Added commands, structures and defines for feature USB interrupt - * Revision 1.124.1.306 2017/04/04 10:57:27 paul.kretz - * Added FDM180M and associated definitions - * Revision 1.124.1.305 2017/04/04 09:06:40Z philipp - * Added general monitoring and event transactions - * Revision 1.124.1.304 2017/04/04 06:20:49 andre.hartmann - * xfeature for xhe unit added - * Revision 1.124.1.303 2017/03/28 09:38:45Z paul.kretz - * added support for MircoSync power supply module - * Revision 1.124.1.302 2017/03/27 10:38:13Z thomas-b - * Renamed PTPv1 common datasets, added swab macros, feature flag and comments - * Revision 1.124.1.301 2017/03/24 10:18:56 paul.kretz - * removed ENABLE_FLAGS in BUILTIN_FEAT_VSG180 - * Revision 1.124.1.300 2017/03/23 08:55:57Z thomas-b - * Fixed wrong documentation for MBG_IO_PORT_STATUS_BUFFER - * Revision 1.124.1.299 2017/03/22 09:46:28 thomas-b - * Added transaction for IO ports - * Revision 1.124.1.298 2017/03/22 08:54:45 thomas-b - * Fixed string initializer for POUT IO port type - * Revision 1.124.1.297 2017/03/22 08:28:21 philipp - * Added MBG_IO_PORT_OP_MODE_NONE to enum MBG_IO_PORT_OP_MODE_BITS - * Revision 1.124.1.296 2017/03/21 13:32:55 thomas-b - * Added relation string variable to MBG_IO_PORT_INFO structure - * Revision 1.124.1.295 2017/03/21 08:46:46 thomas-b - * Added support for physical and logical IO port groups - * Revision 1.124.1.294 2017/03/20 17:10:23 martin - * Fixed and added lots of swab..() macros. - * Revision 1.124.1.293 2017/03/20 10:10:02 martin - * Fixed build without _PRELIMINARY_CODE. - * Revision 1.124.1.292 2017/03/17 11:59:47 thomas-b - * Added directio in/out and io port positions - * Revision 1.124.1.291 2017/03/16 07:47:51 thomas-b - * Added several missing IO port conn types - * Added new IO port type prog. pulse and appropriate structures - * Revision 1.124.1.290 2017/03/15 09:08:12 philipp - * Added I/O port types - * Revision 1.124.1.289 2017/03/15 09:00:49 gregoire - * str initializer for NTP_SYMM_KEY_HASHES added - * Revision 1.124.1.288 2017/03/15 06:46:24 thomas-b - * Shortened string defines for IO port OP modes - * Revision 1.124.1.287 2017/03/14 13:44:41 philipp - * Added size initializer for new I/O port type ethernet - * Revision 1.124.1.286 2017/03/14 08:55:17 thomas-b - * Added IO port type for network - * Reworked event info structure - * Revision 1.124.1.285 2017/03/13 11:42:13 gregoire.diehl - * New PTP preset DOCSIS 3.1 added - * Revision 1.124.1.284 2017/03/10 10:36:41Z paul.kretz - * extended MBG_GPIO_VIDEO_TC_MODES enum - * Revision 1.124.1.283 2017/03/10 09:03:22Z philipp - * Added event_cfg_counter to MBG_MONITORING_STATUS - * Revision 1.124.1.282 2017/03/10 07:23:52 thomas-b - * Added define for invalid event sub_idx - * Revision 1.124.1.281 2017/03/08 12:44:25 thomas-b - * Added mask MBG_TRANSACTION_MSK_SET - * Revision 1.124.1.280 2017/03/08 12:35:44 thomas-b - * Added macros for transaction type set - * Revision 1.124.1.279 2017/03/08 11:42:41 paul.kretz - * bugfix in MBG_GPIO_VIDEO_TC_MODE_MASKS - * Revision 1.124.1.278 2017/03/07 13:56:35Z paul.kretz - * extended GPIO structs for time code support - * Revision 1.124.1.277 2017/03/07 13:46:12Z thomas-b - * Removed builtin feature for ignore lock - * Revision 1.124.1.276 2017/03/07 09:08:43 thomas-b - * *** empty log message *** - * Revision 1.124.1.275 2017/03/07 08:11:01 thomas-b - * Added global feature flag for bonding - * Revision 1.124.1.274 2017/03/03 07:26:53 thomas-b - * Renamed NTP transaction - * Revision 1.124.1.273 2017/03/03 06:42:39 thomas-b - * Relocated NTP_GLB_INFO, fixed several swab macros of new NTP structures - * Revision 1.124.1.272 2017/03/02 14:02:25 gregoire - * NTP related structures reworked - * MBG_TRANSACTION_TYPE_MONITORING_NTP added - * Revision 1.124.1.271 2017/03/01 10:44:26 philipp - * Use _PRELIMINARY_CODE macro instead of debug macro - * Revision 1.124.1.270 2017/02/28 15:31:08 gregoire - * NTP_GLB_INFO: field max_trusted_keys added - * NTP_CLNT_MODE_SETTINGS: field num_peers added - * NTP_SRV_MODE_SETTINGS: field num_refclks added - * NTP_SRV_MODE_INFO: field max_refclks added - * Revision 1.124.1.269 2017/02/27 09:20:34 thomas-b - * Fixed typo in GNSS_SV_STAT_QUALITY_INDS - * Revision 1.124.1.268 2017/02/27 07:44:30 thomas-b - * Changed builtin features for GNS181_UC from preset GPS to preset GNSS - * Revision 1.124.1.267 2017/02/24 11:00:55 philipp - * Moved event type from settings to info - * Revision 1.124.1.266 2017/02/24 09:38:25 philipp - * Do not use fixed buffers for monitorung event info and status - * Revision 1.124.1.265 2017/02/22 12:21:45 thomas-b - * Added string initializers for event types and severities - * Revision 1.124.1.264 2017/02/22 07:53:35 thomas-b - * Added swab macros for monitoring event and status structures - * Revision 1.124.1.263 2017/02/21 15:53:47 philipp - * Added monitoring event and status structures and defines - * Revision 1.124.1.262 2017/02/16 13:00:57 thomas-b - * Added MBG_PTP_V2_PORT_DATASET_IDX structure and removed MBG_PTP_V2_COMMON_DATASETS - * Revision 1.124.1.261 2017/02/16 09:01:31 martin - * New field MBG_GNSS_MODE_INFO::n_sv_status. - * Revision 1.124.1.260 2017/02/16 08:13:00 thomas-b - * Added structures and supp. flag for PTPv2 common datasets defined in IEEE1588-2008, chapter 8.2 - * Revision 1.124.1.259 2017/02/15 16:14:47 martin - * New GNSS type QZSS. - * Renamed GNSS_SV_INFO to GNSS_SV_STATUS. - * New flag MBG_GNSS_FLAG_MSK_HAS_SV_STATUS. - * Revision 1.124.1.258 2017/02/13 08:32:12 philipp - * Fixed GNSS swap macro redefinitions - * Revision 1.124.1.257 2017/02/13 08:26:53 philipp - * Fixed some typos in SNMP structures - * Revision 1.124.1.256 2017/02/10 15:21:11 martin - * Added swab macros for new structures. - * Revision 1.124.1.255 2017/02/10 14:26:22 martin - * New extended feature MBG_XFEATURE_GNSS_SV_INFO - * and associated structures. - * Revision 1.124.1.254 2017/02/08 13:33:42 philipp - * Removed redundant information MBG_SNMP_V12_TRAP_SETTINGS - * Revision 1.124.1.253 2017/02/08 12:49:30 thomas-b - * Changed all int8_t to char in SNMP structs, fixed typo and added some documentation - * Revision 1.124.1.252 2017/02/08 07:04:53 philipp - * Added swaP macros for SNMP monitoring structures - * Revision 1.124.1.251 2017/02/07 11:46:19 philipp - * Fixed duplicate members - * Revision 1.124.1.250 2017/02/07 11:39:42 philipp - * Added destination port for SNMP trap receivers - * Revision 1.124.1.249 2017/02/07 11:34:46 daniel - * *** empty log message *** - * Revision 1.124.1.248 2017/02/07 10:15:19 daniel - * Removed unneccessary xfeature LICENSE_LIMITS - * Revision 1.124.1.247 2017/02/06 13:10:25 philipp - * Added SNMP monitoring structures and defines - * Revision 1.124.1.246 2017/02/06 10:47:49 philipp - * Added monitoring XFeature skeleton - * Revision 1.124.1.245 2017/02/06 08:57:58 daniel - * Added XFEATURE for License Limits - * Revision 1.124.1.244 2017/02/01 09:45:25 daniel - * Added new TLV License types for PTPv1 and Time Monitor - * Revision 1.124.1.243 2017/02/01 09:35:38 martin - * Defined DEFAULT_POUT_PULSE_SHIFT_MIN and - * DEFAULT_POUT_PULSE_SHIFT_MAX. - * Revision 1.124.1.242 2017/01/27 10:24:11 philipp - * Fixed missing while in macro - * Revision 1.124.1.241 2017/01/27 09:13:15 martin - * Fixed macro syntax. - * Revision 1.124.1.240 2017/01/26 15:24:36 martin - * Support new model RSC180RDU. - * Revision 1.124.1.239 2017/01/26 15:13:57 martin - * Fixed some macros. - * Revision 1.124.1.238 2017/01/25 14:34:12 martin - * Added definition POUT_MODES_SUPP_TIMEBASE_UTC. - * Updated comments for POUT_SETTINGS_FLAG_BITS. - * Revision 1.124.1.237 2017/01/25 13:10:38 martin - * Added POUT bit masks definitions indicating which parameter fields - * are relevant for which POUT modes. - * Fixed macros _mbg_swab_pout_settings_on_get() and - * _mbg_swab_pout_settings_on_set(). - * Updated comments, and fixed some typos in comments. - * Revision 1.124.1.236 2017/01/24 14:15:44 daniel - * Started to define structures for PTPv1 datasets - * Revision 1.124.1.235 2017/01/10 16:17:11 daniel - * Added PTPv1 roles - * Revision 1.124.1.234 2017/01/06 15:53:20 martin - * More POUT pulse shift support. - * Revision 1.124.1.233 2017/01/05 14:16:35 martin - * Added missing definitions for PSX_4GE. - * Revision 1.124.1.232 2017/01/02 10:43:39 andre.hartmann - * Added model code for PSX_4GE board. - * Revision 1.124.1.231 2016/12/22 11:21:32Z philipp - * Added NTP and PTP hardware timestamping flags to MBG_NET_INTF_LINK_OPTS - * Revision 1.124.1.230 2016/12/22 10:19:21 martin - * Doxygen fix. - * Revision 1.124.1.229 2016/12/21 09:15:23 martin - * Added GPS_MODEL_HAS_SV_INFO to the BUILTIN_FEAT_GPS mask. - * Support new model GNS180_UC. - * Revision 1.124.1.228 2016/12/08 11:44:17 paul.kretz - * Updated masks for SCU_STAT_INFO - * Revision 1.124.1.227 2016/12/07 14:44:44Z paul.kretz - * Added new masks for SCU_STAT_INFO to support up to 4 power supplies - * Revision 1.124.1.226 2016/12/07 09:34:40Z martin - * Removed trailing spaces. - * Revision 1.124.1.225 2016/12/06 14:50:15 andre.hartmann - * Added model code for GPS165 - * Revision 1.124.1.224 2016/12/06 09:15:58Z thomas-b - * Added builtin feature HAS_SV_INFO for all GPS (only) receivers - * Revision 1.124.1.223 2016/12/01 11:20:08 philipp - * Fixed MBG_IO_PORT_INFO_MIN_SIZE - * Revision 1.124.1.222 2016/11/30 11:25:07 thomas-b - * Added builtin feature for SCU_STAT and added it to RSC180 and MDU180 - * Revision 1.124.1.221 2016/11/29 14:07:00 philipp - * Added MBG_IO_PORT_INFO_IDX_SIZES - * Revision 1.124.1.220 2016/11/25 11:32:15 philipp - * Finalized I/O port structures, enums, defines - * Revision 1.124.1.219 2016/11/24 07:06:34 philipp - * Honour big endian system when swapping bytes - * Revision 1.124.1.218 2016/11/23 12:41:12 philipp - * Fixed GPIO swap macro typos - * Revision 1.124.1.217 2016/11/23 09:36:30 paul.kretz - * added swab macros for GPIO's - * extended MBG_IO_PORT structs - * removed unused preprocessor symbol in FPGA_INFO struct - * Revision 1.124.1.216 2016/11/22 10:33:16Z philipp - * Implemented I/O ports - * Revision 1.124.1.215 2016/11/21 12:22:44 thomas-b - * Added enable flags as builtin feature for FDM180 - * Revision 1.124.1.214 2016/11/16 11:00:36 thomas-b - * Added core module type and revision to MBG_EXT_SYS_INFO - * Revision 1.124.1.213 2016/11/10 14:08:17 thomas-b - * Changed string name for GPS_MODEL_NAME_UNKNOWN - * Revision 1.124.1.212 2016/11/08 17:22:11 martin - * Doxygen fixes. - * Revision 1.124.1.211 2016/11/04 11:48:35 paul.kretz - * Support MDU312. - * Revision 1.124.1.210 2016/11/04 07:21:26Z thomas-b - * Added flag, mask, and idx for GPIO, which indicates that a GPIO configuration depends on another GPIO - * Revision 1.124.1.209 2016/11/02 11:54:57 paul.kretz - * added new xfeature MBG_XFEATURE_REQ_TTM - * Revision 1.124.1.208 2016/11/01 09:27:49Z thomas-b - * Added builtin feature for TZDL to FDM180 - * Revision 1.124.1.207 2016/11/01 09:24:12 martin - * *** empty log message *** - * Revision 1.124.1.206 2016/10/25 13:24:37 martin - * *** empty log message *** - * Revision 1.124.1.205 2016/10/25 08:56:40 martin - * Renamed MSK_ICODE_RX_HAS_SHORT_YEAR to MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P5. - * New MSK_ICODE_RX_HAS_ANY_SHORT_YEAR which includes - * all codes providing a year number, either after P5 or after P6. - * Doxygen fixes. - * Changes to builtin feature definitions. - * Revision 1.124.1.204 2016/10/24 08:12:04 martin - * Support MDU180. - * Revision 1.124.1.203 2016/10/20 10:43:20 thomas-b - * Added builtin feature GPS_MODEL_IS_BUS_LVL_DEV - * Revision 1.124.1.202 2016/10/19 10:19:59 thomas-b - * Added define for default user capture network UDP port - * Revision 1.124.1.201 2016/10/19 09:07:28 thomas-b - * Added supported flags for MBG_UCAP_NET_GLB_INFO - * Revision 1.124.1.200 2016/10/13 07:30:10 paul.kretz - * Extended sysinfo proc and fpga types by SAM3s, STM32F4, Cyclone4GX15 and Cyclone4CE22 - * Revision 1.124.1.199 2016/10/10 10:36:35Z thomas-b - * Added transfer protocol for ucap network receivers and added destination port - * Revision 1.124.1.198 2016/10/10 10:17:37 thomas-b - * Removed _PRELIMINARY_CODE_AUDIO restrictions - * Added new extended feature and structure definitions for ucap via network - * Revision 1.124.1.197 2016/10/07 11:24:50 thomas-b - * Fixed swab makro for addr settings - * Revision 1.124.1.196 2016/10/05 08:26:36 andre.hartmann - * Revision 1.124.1.195 2016/09/29 11:56:43Z philipp - * Added documentation for MBG_TRANSACTION_TYPE_NETWORK - * Revision 1.124.1.194 2016/09/29 10:43:41 thomas-b - * Added define for MBG_ARPHRD_ETHER - * Revision 1.124.1.193 2016/09/29 06:13:07 philipp - * Added support for beginning / ending typed transactions - * Revision 1.124.1.192 2016/09/28 13:35:00 philipp - * Renamed flag field - * Revision 1.124.1.191 2016/09/28 13:29:22 thomas-b - * Added feature flags for MBG_NET_GLB_CFG_INFO - * Revision 1.124.1.190 2016/09/26 13:04:54 udo - * added missing comma in MBG_TLV_FEAT_TYPE_NAMES - * Revision 1.124.1.189 2016/09/26 10:08:14 udo - * added TLV Feature MBG_TLV_FEAT_TYPE_FILE_REQUEST to request a generic file from HPS - * Revision 1.124.1.188 2016/09/23 08:29:09 martin - * Fixed missing comma in string table initializer. - * Revision 1.124.1.187 2016/09/22 12:12:29 philipp - * Split ::MBG_NET_INTF_LINK_OPTS::MBG_NET_INTF_LINK_OPT_CAN_SYNCE up into SyncE In and SyncE Out option - * Revision 1.124.1.186 2016/09/15 14:54:30 martin - * Support GRC181PEX. - * Revision 1.124.1.185 2016/09/12 09:16:49 martin - * Fixed cascaded comment characters. - * Revision 1.124.1.184 2016/09/08 10:25:03 martin - * Fixed build for 16 bit targets. - * Revision 1.124.1.183 2016/09/05 13:23:04 paul.kretz - * Added ENABLE_FLAGS to BUILTIN_FEAT_VSG180 - * Revision 1.124.1.182 2016/08/25 14:37:16Z paul.kretz - * added new gpio video type PAL_M - * Revision 1.124.1.181 2016/08/23 15:47:04Z martin - * Moved macros _setup_default_receiver_info_dcf() and - * _setup_default_receiver_info_gps() here. - * Revision 1.124.1.180 2016/08/16 13:01:13 martin - * Syntax fix. - * Revision 1.124.1.179 2016/08/12 11:05:14 paul.kretz - * Added digital audio output as new gpio type which is only included - * if symbol _PRELIMINARY_CODE_AUDIO is defined. - * Revision 1.124.1.178 2016/08/11 11:34:06Z martin - * Modified MBG_REF_OFFS_NOT_CFGD to avoid compiler warning. - * Revision 1.124.1.177 2016/08/11 11:30:16 martin - * Moved time monitoring stuff to new file time_mon.h. - * Revision 1.124.1.176 2016/08/11 10:28:09 udo - * prepare extended data set for time monitor - * Revision 1.124.1.175 2016/08/10 05:17:08 udo - * added domain number to Time Monitor Target Settings - * Revision 1.124.1.174 2016/08/09 14:48:06 martin - * Revision 1.124.1.173 2016/08/03 08:05:11Z thomas-b - * Finished new network structures, definitions and relations - * Revision 1.124.1.172 2016/07/29 09:36:21 paul.kretz - * Added definitions for N2X180. - * Revision 1.124.1.171 2016/07/15 14:08:09Z martin - * Fixed a typo. - * Revision 1.124.1.170 2016/07/07 14:17:02 martin - * Cleaned up POUT API. - * Doxygen fixes. - * Revision 1.124.1.169 2016/07/07 09:57:10 andre.hartmann - * added mbg_clk_res_info - * Revision 1.124.1.168 2016/06/28 15:42:16Z martin - * *** empty log message *** - * Revision 1.124.1.167 2016/06/28 15:04:40 martin - * Added definitions for GRC181. - * Added missing definitions for GPS180CSM. - * Revision 1.124.1.166 2016/06/23 09:23:24 thomas-b - * Added num_dns_srvr and num_dns_srch_dom to MBG_NET_GLB_CFG_SETTINGS - * Revision 1.124.1.165 2016/06/22 06:58:37 udo - * added new parameters to MBG_TIME_MON_TARGET_STATUS - * Revision 1.124.1.164 2016/06/21 06:34:54 andre - * QL alarms now separated for TDEV and MTIE - * comment for QL hysteresis added - * Revision 1.124.1.163 2016/06/10 07:59:09Z philipp - * Extended sysinfo proc and fpga types by SAM3u and Cyclone5 - * Revision 1.124.1.162 2016/06/09 09:17:08 thomas-b - * Added builtin features TIME and TZDL for TCR cards - * Revision 1.124.1.161 2016/06/06 08:59:45 andre - * Revision 1.124.1.160 2016/06/02 13:36:11Z philipp - * Extended MBG_EXT_SYS_INFO proc and fpga types - * Revision 1.124.1.159 2016/06/02 10:57:51 philipp - * Added string initializers for MBG_EXT_SYS_INFO's proc and FPGA types - * Revision 1.124.1.158 2016/06/02 10:24:22 philipp - * Renaming all revision macros and helper functions - * Revision 1.124.1.157 2016/06/02 10:15:35 philipp - * Renaming all MBG_EXT_REV_INFO related stuff to MBG_EXT_SYS_INFO. - * Revision 1.124.1.156 2016/06/01 10:49:49 andre - * Revision 1.124.1.155 2016/06/01 09:51:26Z philipp - * Added structures and definitions for new type MBG_LICENSE to be queried via TLV_API. - * Revision 1.124.1.154 2016/06/01 06:59:00 andre - * Revision 1.124.1.153 2016/05/31 14:32:27Z andre - * Revision 1.124.1.152 2016/05/31 14:32:02Z andre - * Revision 1.124.1.151 2016/05/30 08:14:09Z thomas-b - * Added builtin feature GPS_MODEL_HAS_TIME to GPS receivers and N2x - * Revision 1.124.1.150 2016/05/27 06:32:12 philipp - * Changed XMR_HOLDOVER_STATUS_MODE_NAMES - * Revision 1.124.1.149 2016/05/26 08:01:16 andre - * Revision 1.124.1.148 2016/05/24 14:43:10Z andre - * Revision 1.124.1.147 2016/05/24 13:32:24Z philipp - * Added PTP Statistics - * Revision 1.124.1.146 2016/05/20 08:58:52 thomas-b - * New BUILTIN_FEATURE GPS_HAS_TZCODE for older PZF cards - * Revision 1.124.1.145 2016/05/20 06:41:42 thomas-b - * Added TZDL and ENABLE_FLAGS to BUILTIN_FEAT_N2X - * Revision 1.124.1.144 2016/05/19 13:12:32 paul - * renamed two video HD formats: - * 1080i29.97Hz to 1080i59.94Hz and 1080i25Hz to 1080i50Hz - * Revision 1.124.1.143 2016/05/11 13:20:20Z thomas-b - * Changed several fields and flags in NET_CFG structures - * Revision 1.124.1.142 2016/05/09 08:06:53 philipp - * New array string initializers for LED modes and colors - * Revision 1.124.1.141 2016/05/04 09:57:27 thomas-b - * Comment changed - * Revision 1.124.1.140 2016/04/26 09:17:41 thomas-b - * Changed structure MBG_NET_GLB_CFG_SETTINGS - * Revision 1.124.1.139 2016/04/26 08:51:47 philipp - * New multi reference input type SyncE - * Revision 1.124.1.138 2016/04/26 08:18:58 thomas-b - * Added typedefs for interface route structures if _PRELIMINARY_CODE is not defined - * Revision 1.124.1.137 2016/04/26 07:39:45 thomas-b - * Changed names and descriptions in net_cfg structures - * Relocated preliminary code areas in net_cfg and ntp definitions - * Revision 1.124.1.136 2016/04/26 06:05:44 philipp - * Removed space to fix compiler error on ARM GCC 4.9.3 - * Revision 1.124.1.135 2016/04/25 15:13:58 martin - * *** empty log message *** - * Revision 1.124.1.134 2016/04/25 14:34:46 martin - * *** empty log message *** - * Revision 1.124.1.133 2016/04/25 10:23:22Z martin - * TLV code isn't preliminary anymore. - * Enums with more than 16 entries are not supported by 16 bit compilers. - * Revision 1.124.1.132 2016/04/22 08:36:27 philipp - * Added String initializers for GPIO bit out flags - * Revision 1.124.1.131 2016/04/21 10:53:29 philipp - * Added GPIO bits format strings. - * Added T1 SSM quality levels. - * Revision 1.124.1.130 2016/04/20 14:43:29 udo - * use NANO_TIME instead of double - * Revision 1.124.1.129 2016/04/20 13:16:58 thomas-b - * Added typedefs for NTP_SRV_MODE_INFO and NTP_SRV_MODE_SETTINGS - * Revision 1.124.1.128 2016/04/20 09:26:05 philipp - * Moved all HPS-PTP related structures to gpspriv.h and removed related extended feature bit from gpsdefs.h. - * Also removed functions from mbgextio and xdevfeat since HPS-PTP handling needs a redesign concerning structures. - * Thus, handle everything explicitly for now! - * -> Redesing this A.S.A.P.!!! - * Revision 1.124.1.127 2016/04/18 12:37:02 thomas-b - * New network structures and definitions for bonding and routing - * Revision 1.124.1.126 2016/04/15 13:14:08 daniel - * Added PTP profile ITU-T. G. 8275.2 - * Revision 1.124.1.125 2016/04/15 09:22:16 udo - * fixed alignment problem in PTP_DEV_CFG_GLB - * Revision 1.124.1.124 2016/04/15 08:17:28 philipp - * New feature MBG_XFEATURE_EXT_PTP - * Revision 1.124.1.123 2016/04/15 07:31:46 andre - * Revision 1.124.1.122 2016/04/08 10:18:02Z daniel - * Fixed MBG_ENCODE_EXT_REV macro - * Revision 1.124.1.121 2016/04/08 10:16:29 martin - * *** empty log message *** - * Revision 1.124.1.120 2016/04/07 13:20:23 philipp - * Extended NTP definitions and added new structure MBG_EXT_REV_INFO including enums, masks, etc.. - * Revision 1.124.1.119 2016/04/05 13:29:25 daniel - * Adjust ptp cfg and state structures to take care of unified data type sizes and alignment - * Revision 1.124.1.118 2016/04/04 14:46:13 martin - * Added TLV feature type names. - * Revision 1.124.1.117 2016/03/24 14:08:47 martin - * *** empty log message *** - * Revision 1.124.1.116 2016/03/24 09:14:52 martin - * New extended feature MBG_XFEATURE_PWR_CTL_API. - * Revision 1.124.1.115 2016/03/18 11:21:52 martin - * *** empty log message *** - * Revision 1.124.1.114 2016/03/18 10:32:25 martin - * *** empty log message *** - * Revision 1.124.1.113 2016/03/17 09:21:01 martin - * *** empty log message *** - * Revision 1.124.1.112 2016/03/16 15:13:37 martin - * *** empty log message *** - * Revision 1.124.1.111 2016/03/16 08:29:13 martin - * Removed ..._MODEL_HAS_GNSS_MODE definitions, use ..._MODEL_IS_GNSS - * instead. - * Revision 1.124.1.110 2016/03/15 14:55:04 martin - * Modified LNE and LED API. - * Revision 1.124.1.109 2016/03/14 11:54:06 martin - * Fixed duplicate macro name. - * Revision 1.124.1.108 2016/03/11 15:12:08 martin - * Started to refactor LED and LNE API. - * Revision 1.124.1.107 2016/03/11 11:25:26 martin - * Made XMR_STATS::step_det_val a reserved, unused field. - * Cleanup. - * Revision 1.124.1.106 2016/03/11 10:09:44 andre - * Revision 1.124.1.105 2016/03/02 15:03:42Z daniel - * Updates for new PTP Utility profile and PTP statistics - * Revision 1.124.1.104 2016/02/29 15:51:31 andre - * added estimated holdover var to XMR_HOLDOVER_STATUS - * Revision 1.124.1.103 2016/02/25 08:47:32Z paul - * Added definitions for GTS180. - * Revision 1.124.1.102 2016/02/24 09:23:55Z gregoire - * change PTP_ANN_RCPT_TIMEOUT_MAX from 255 to 8 - * Revision 1.124.1.101 2016/02/19 12:11:21Z udo - * added MBG_LNE_INFO_EXT - * Revision 1.124.1.100 2016/02/18 14:56:37 daniel - * Added TLV FEAT_TYPE LICENSE UPGRADE - * Revision 1.124.1.99 2016/02/18 11:27:27 udo - * added MBG_LNE_LED_STATUS - * Revision 1.124.1.98 2016/02/16 08:38:50 gregoire - * added new initializer to MBG_XFEATURE_NAMES - * Revision 1.124.1.97 2016/02/11 12:02:39Z daniel - * Added two TLV_FEAT_TYPES - * Revision 1.124.1.96 2016/02/10 15:52:36 thomas-b - * Added enum MBG_IMS_FDM_FLAGS and appropriate masks enum - * Revision 1.124.1.95 2016/02/03 13:27:44 martin - * Added definitions for LNE180SFP. - * Revision 1.124.1.94 2016/02/03 09:41:32 martin - * Fixed build without _PRELIMINARY_CODE. - * Revision 1.124.1.93 2016/02/02 15:53:46Z martin - * Added definitions for CSM100. - * Revision 1.124.1.92 2016/01/29 09:06:32 udo - * Added time-protocol type to Time Monitor Target settings. - * Revision 1.124.1.91 2016/01/22 11:34:39 gregoire - * Added string initializers for XMR_STATS_FLAGS_BITS. - * Revision 1.124.1.90 2016/01/22 08:16:07Z gregoire - * Renamed DEFAULT_MULTI_REF_NAMES_SHORT strings. - * Revision 1.124.1.89 2016/01/21 08:59:03Z andre - * Added auto_bis field in XMR_STATS. - * Revision 1.124.1.88 2016/01/19 14:11:47Z udo - * Modified time monitor structures. - * Revision 1.124.1.87 2016/01/18 08:37:03 udo - * Added support for PTP Time Monitoring on TSU/HPS100. - * Revision 1.124.1.86 2016/01/15 11:30:14 martin - * New field 'timestamp' in XMR_STATS. - * Revision 1.124.1.85 2016/01/15 08:52:51 martin - * Some flag masks for XMR_STATS. - * Revision 1.124.1.84 2016/01/13 15:26:00 martin - * Removed obsolete code added in the previous version. - * Revision 1.124.1.83 2016/01/13 15:09:17 martin - * Support XMR_STATS. - * Revision 1.124.1.82 2015/12/14 13:03:09 lars - * Fixes / changes in IRIG TX / RX masks. - * Revision 1.124.1.81 2015/12/14 11:09:01Z lars - * *** preliminary *** - * Revision 1.124.1.80 2015/12/09 17:34:56Z martin - * *** empty log message *** - * Revision 1.124.1.79 2015/12/09 10:21:18 martin - * *** empty log message *** - * Revision 1.124.1.78 2015/12/09 08:28:36 martin - * New legacy model codes. - * Changed/Added some IRIG enums. - * Revision 1.124.1.77 2015/12/07 14:43:04 martin - * Doxygen fixes. - * Revision 1.124.1.76 2015/12/04 14:20:18 paul - * Fixed a typo in comment of video string initialzier. - * Added support for configurable epochs for video outputs. - * Revision 1.124.1.75 2015/12/02 16:51:19Z martin - * *** empty log message *** - * Revision 1.124.1.74 2015/12/02 16:35:32 martin - * *** empty log message *** - * Revision 1.124.1.73 2015/12/01 11:34:33 martin - * *** empty log message *** - * Revision 1.124.1.72 2015/11/30 16:51:12 martin - * *** empty log message *** - * Revision 1.124.1.71 2015/11/30 16:22:30 martin - * *** empty log message *** - * Revision 1.124.1.70 2015/11/30 09:02:47 philipp - * Added TLV feature MBG_TLV_CTX_FLAG_FW_ROLLBACK. - * Revision 1.124.1.69 2015/11/30 08:16:57 philipp - * Added MBG_TLV_INFO feature macros. - * Revision 1.124.1.68 2015/11/26 17:01:08 martin - * *** empty log message *** - * Revision 1.124.1.67 2015/11/26 08:32:54 martin - * *** empty log message *** - * Revision 1.124.1.66 2015/11/25 16:55:08 martin - * Started to implement extended features. - * Revision 1.124.1.65 2015/11/24 13:10:54 philipp - * TLV additions / partly redesign and feature inline functions. - * Revision 1.124.1.64 2015/11/23 10:23:47 philipp - * Added Doxygen documentation for TLV structures, flags and masks. - * Revision 1.124.1.63 2015/11/23 10:11:28 martin - * *** empty log message *** - * Revision 1.124.1.62 2015/11/23 08:27:32 gregoire - * Added initializers for MBG_IMS_FDM_LINE_FREQS. - * Revision 1.124.1.61 2015/11/20 09:16:39Z philipp - * Fixed macro _mbg_swab_tlv_announce. - * Revision 1.124.1.60 2015/11/20 08:14:29 philipp - * Added id member to struct MBG_TLV_ANNOUNCE. - * Revision 1.124.1.59 2015/11/20 07:26:29 philipp - * Moved TLV structures here. - * Revision 1.124.1.58 2015/11/18 13:51:50 philipp - * Added leapfile to NTP miscellaneous structures. - * Revision 1.124.1.57 2015/11/18 13:39:22 philipp - * Added NTP miscellaneous structures. - * Revision 1.124.1.56 2015/11/06 12:42:08 philipp - * Added NTP statistics structures. - * Revision 1.124.1.55 2015/11/06 11:25:22 philipp - * Removed member symlink in NTP_REFCLK_CFG_SPEC since it is implementation defined. - * Revision 1.124.1.54 2015/11/06 11:16:35 philipp - * Added NTP symmetric key structures. - * Revision 1.124.1.53 2015/11/06 09:17:40 philipp - * Added byte swap macros to NTP restriction and NTP refclock configuration structures. - * Revision 1.124.1.52 2015/11/05 12:20:12 martin - * New define MBG_MAX_HOSTNAME_LEN. - * Preliminary fix for TZDL initializers. - * Updated some comments. - * Revision 1.124.1.51 2015/11/05 09:07:56 philipp - * Added structures for NTP restriction and refclock configuration (preliminary code). - * Revision 1.124.1.50 2015/10/28 12:09:26 martin - * GPIO types for SCG not preliminary anymore. - * Added definitions for LUE180. - * Revision 1.124.1.49 2015/10/26 11:55:19 daniel - * Merged aligned PTP SMPTE and TELECOM PHASE profile structures from previous branch here. - * Revision 1.124.1.48 2015/10/26 11:24:04 daniel - * Support for PTP Preset 802.1AS - * Revision 1.124.1.47 2015/10/26 10:56:42 paul - * added a new flag for GPIO studio clock out - * Revision 1.124.1.46 2015/10/26 09:47:53Z paul - * added a missing GPIO studio clock scale string initializer - * Revision 1.124.1.45 2015/10/23 11:00:27Z paul - * Revision 1.124.1.44 2015/10/22 14:35:51Z paul - * fixed a typo - * Revision 1.124.1.43 2015/10/22 14:17:34Z martin - * *** empty log message *** - * Revision 1.124.1.42 2015/10/22 14:15:02 paul - * some changes in GPIO structs - * Revision 1.124.1.41 2015/10/21 14:36:32Z paul - * renamed stud_clk_out in studio_clk_out and vid_sync_out in video_sync_out - * Revision 1.124.1.40 2015/10/20 13:38:57Z paul - * renamed HD format in GPIO video type - * Revision 1.124.1.39 2015/10/20 12:11:36Z paul - * Revision 1.124.1.38 2015/10/20 10:58:01Z martin - * *** empty log message *** - * Revision 1.124.1.37 2015/10/20 10:43:39 paul - * Revision 1.124.1.36 2015/10/20 10:15:57Z paul - * added preliminary studio clock structs and defines - * Revision 1.124.1.35 2015/10/19 10:48:00Z gregoire - * Revision 1.124.1.34 2015/10/19 10:08:47Z gregoire - * Revision 1.124.1.33 2015/10/16 11:03:06Z martin - * *** empty log message *** - * Revision 1.124.1.32 2015/10/15 14:17:22 martin - * *** empty log message *** - * Revision 1.124.1.31 2015/10/15 08:40:37 paul - * added two new HD video formats - * Revision 1.124.1.30 2015/10/15 07:38:14Z gregoire - * AES67 Media Profile added - * Revision 1.124.1.29 2015/10/13 08:44:08Z gregoire - * smpte_jam_event added to PTP_DEV_CFG_GLB - * Revision 1.124.1.28 2015/10/12 10:01:59Z martin - * *** empty log message *** - * Revision 1.124.1.27 2015/10/09 11:09:13 martin - * *** empty log message *** - * Revision 1.124.1.26 2015/10/09 09:03:50 gregoire - * Revision 1.124.1.25 2015/10/09 07:18:49Z gregoire - * Builtin feature BUILTIN_FEAT_GNSS set for GRC models. - * Revision 1.124.1.24 2015/10/08 13:27:37Z martin - * *** empty log message *** - * Revision 1.124.1.23 2015/10/06 10:33:39 paul - * Changed GPIO names. - * Added two defines for GPIO_TYPE_VIDEO_SYNC. - * Revision 1.124.1.22 2015/10/06 07:55:11Z paul - * Changed names of GPIO types and structs. - * Revision 1.124.1.21 2015/10/02 13:07:11Z martin - * Doxygen fixes. - * Revision 1.124.1.20 2015/10/02 10:33:00 martin - * *** empty log message *** - * Revision 1.124.1.19 2015/10/01 10:51:32 martin - * *** empty log message *** - * Revision 1.124.1.18 2015/09/30 08:03:45 paul - * Bug fix in some GPIO structs. - * Added comments. - * Revision 1.124.1.17 2015/09/29 09:55:22Z paul - * added video output and sync output as two new GPIO types - * Revision 1.124.1.16 2015/09/28 09:34:56Z thomas-b - * Renamed td_max_limit in MBG_IMS_FDM_LIMITS to td_pos_limit - * Revision 1.124.1.15 2015/09/18 13:58:44 martin - * *** empty log message *** - * Revision 1.124.1.14 2015/09/17 14:56:57 thomas-b - * Renamed several variables in MBG_FDM_SETTINGS and MBG_FDM_LIMITS - * Revision 1.124.1.13 2015/09/15 13:15:01 martin + * Revision 1.125 2017/07/05 18:18:27 martin + * New models GPS_MODEL_CTC100, GPS_MODEL_TCR180, + * GPS_MODEL_LUE180, GPS_MODEL_CPC_01, GPS_MODEL_TSU_01, + * GPS_MODEL_CMC_01, GPS_MODEL_SCU_01, GPS_MODEL_FCU_01, + * GPS_MODEL_CSM100, GPS_MODEL_LNE180SFP, GPS_MODEL_GTS180, + * GPS_MODEL_GPS180CSM, GPS_MODEL_GRC181, GPS_MODEL_N2X180, + * GPS_MODEL_GNS181PEX, GPS_MODEL_MDU180, GPS_MODEL_MDU312, + * GPS_MODEL_GPS165, GPS_MODEL_GNS181_UC, GPS_MODEL_PSX_4GE, + * GPS_MODEL_RSC180RDU, GPS_MODEL_USYNCPWR, GPS_MODEL_FDM180M, + * GPS_MODEL_LSG180, GPS_MODEL_GPS190, GPS_MODEL_GNS181 and + * associated definitions. + * New GPS_BUILTIN_FEATURE_BITS and associated definitions. + * New macros _setup_default_receiver_info_dcf() and + * _setup_default_receiver_info_gps() as well as associated + * definitions which can be used to set up a RECEIVER_INFO + * structure for legacy devices which don't provide it. + * New Receiver_INO feature bit GPS_FEAT_XFEATURE which + * indicates that a new, extended feature set is supported. + * Defined a new st of extended features (MBG_XFEATURE_BITS) + * and associated definitions. * Moved definitions for NANO_TIME and NANO_TIME_64 to words.h. - * Revision 1.124.1.12 2015/09/15 11:08:22 martin - * Support new model TCR180. - * Added missing comma in DEFAULT_GPS_MODEL_NAMES. - * Revision 1.124.1.11 2015/09/07 09:19:21 martin - * Revision 1.124.1.10 2015/09/04 09:19:17 daniel - * Moved 2 additional TSU strcutures to PREMINARY_CODE block - * Revision 1.124.1.9 2015/09/03 09:17:41 martin - * Doxygen fixes. - * Revision 1.124.1.8 2015/09/02 16:42:17 martin - * Preliminary code which is only included if a preprocessor symbol - * _PRELIMINARY_CODE is defined in the project Makefile. - * Revision 1.124.1.7 2015/08/25 10:30:13 daniel - * Revision 1.124.1.6 2015/08/25 10:02:37 daniel - * Revision 1.124.1.5 2015/08/25 09:16:39 daniel - * Changed reserved member in PTP_STATE to include tsu_secs - * Revision 1.124.1.4 2015/08/10 07:37:09 daniel - * Added sync_e byte swab macros - * Revision 1.124.1.3 2015/08/07 10:51:10 daniel - * Fixed typo in CTC100 declaration - * Revision 1.124.1.2 2015/08/07 10:49:40 daniel - * RE-added temp. PTP structures PTP_DEV_CFG_GLB and PTP_DEV_CFG_NET - * Added new model CTC100 - * Revision 1.124.1.1 2015/07/29 07:40:55 daniel + * New IRIG TX codes ICODE_TX_A006_A136, ICODE_TX_A007_A137, + * and associated definitions. + * Renamed ICODE_RX_G142_G146 to ICODE_RX_G142, and + * ICODE_RX_G002_G006 to ICODE_RX_G002. + * New IRIG RX codes ICODE_RX_A136_A137, ICODE_RX_A006_A007, + * ICODE_RX_G146, ICODE_RX_G006, and associated definitions. + * New union POUT_DATA union used for varying configuration + * data in POUT_SETTINGS, depending on the output mode. + * New POUT_MODES POUT_PTTI_PPS, POUT_HAVEQUICK, and + * associated definitions. + * Definitions to support a configurable pulse shift + * of some programmable output signals. + * New multiref source MULTI_REF_SYNCE and associated + * definitions. + * Added a number of swab..() macros that were still missing. + * XMR statistics, XMR_QL and some other XMR stuff by andre. + * New GPIO types including video modes, and associated stuff. + * Renamed some structure fields and added some definitions + * related to FDM. + * Added some SCU_STAT_MASKS. + * New GNSS_TYPE_QZSS, and modified MBG_GNSS_MODE_INFO. + * New flag MBG_GNSS_FLAG_HAS_SV_STATUS, structure + * GNSS_SV_STATUS and associated definitions. + * A bunch of new structures and definitions for network + * configuration. + * Many new structures and definitions for NTP configuration. + * New structures and associated definitions used to send + * user capture events over the network (ext_ucap). + * New PTP_ROLES and associated stuff. + * Changed one of PTP_STATE's reserved fields to tsu_secs. + * Changed PTP_ANN_RCPT_TIMEOUT_MAX from 255 to 8. + * New PTP_CFG_FLAGS, PTP_OPT_EXTS flags, PTP_PRESETS_MASKS + * and associated definitions. + * Definitions for PTPv1 and v2 data sets, and PTP statistics. + * Preliminary definitions to support SMPTE and SDH. + * Definition for XBP addressing of devices. + * Definitions to support TLVs. + * Added LED and LNE API definitions. + * MBG_EXT_SYS_INFO_BITS and associated definitions for an + * extended sysinfo API. + * MBG_CLK_RES_INFO and associated stuff for clock resolution + * info. + * Definitions for configuration transaction handling. + * Definitions for a higher level I/O port API. + * Definitions for monitoring / notification. + * Definitions for USB locking. + * Preliminary licensing stuff. + * Defined macros in a safer way. * Revision 1.124 2015/07/14 14:22:46 martin * Doxygen fix. * Revision 1.123 2015/07/06 13:00:10 martin @@ -1528,6 +947,9 @@ enum GPS_MODEL_CODES GPS_MODEL_RSC180RDU, GPS_MODEL_USYNCPWR, GPS_MODEL_FDM180M, + GPS_MODEL_LSG180, // Line Signal Generator + GPS_MODEL_GPS190, + GPS_MODEL_GNS181, N_GPS_MODEL /* If new model codes are added then care must be taken * to update the associated string initializers GPS_MODEL_NAMES @@ -1639,6 +1061,9 @@ enum GPS_MODEL_CODES #define GPS_MODEL_NAME_RSC180RDU "RSC180RDU" #define GPS_MODEL_NAME_USYNCPWR "MICROSYNC-PWR" #define GPS_MODEL_NAME_FDM180M "FDM180M" +#define GPS_MODEL_NAME_LSG180 "LSG180" +#define GPS_MODEL_NAME_GPS190 "GPS190" +#define GPS_MODEL_NAME_GNS181 "GNS181" /** @} anchor GPS_MODEL_NAMES */ @@ -1747,11 +1172,15 @@ enum GPS_MODEL_CODES GPS_MODEL_NAME_PSX_4GE, \ GPS_MODEL_NAME_RSC180RDU, \ GPS_MODEL_NAME_USYNCPWR, \ - GPS_MODEL_NAME_FDM180M \ + GPS_MODEL_NAME_FDM180M, \ + GPS_MODEL_NAME_LSG180, \ + GPS_MODEL_NAME_GPS190, \ + GPS_MODEL_NAME_GNS181 \ } + /** * @brief Definitions used to classify devices and built-in features * @@ -1763,6 +1192,14 @@ enum GPS_MODEL_CODES /** + * @brief A data type to hold a mask of @ref GPS_BUILTIN_FEATURE_MASKS + * + * @see @ref GPS_BUILTIN_FEATURE_MASKS + */ +typedef uint32_t BUILTIN_FEATURE_MASK; + + +/** * @brief Enumeration of classifiers and built-in features * * @see ::GPS_MODEL_CODES @@ -2280,6 +1717,19 @@ enum GPS_BUILTIN_FEATURE_BITS #define BUILTIN_FEAT_RSC180RDU ( GPS_MODEL_HAS_SCU_STAT ) #define BUILTIN_FEAT_USYNCPWR ( 0 ) #define BUILTIN_FEAT_FDM180M ( GPS_MODEL_HAS_TZDL | GPS_MODEL_HAS_ENABLE_FLAGS ) +#define BUILTIN_FEAT_LSG180 ( 0 ) +#define BUILTIN_FEAT_GPS190 ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GNS181 ( BUILTIN_FEAT_GNSS ) + +/** + * @brief Feature mask used for legacy devices + * + * This code is used to set builtin feature flags + * legacy devices not listed here, so we can simply + * search for ::BUILTIN_FEAT_UNDEFINED to identify + * such devices. The numeric value is just 0, though. + */ +#define BUILTIN_FEAT_UNDEFINED ( 0 ) /** @} anchor GPS_MODEL_BUILTIN_FEATURE_MASKS */ @@ -2384,6 +1834,9 @@ enum GPS_BUILTIN_FEATURE_BITS { GPS_MODEL_RSC180RDU, BUILTIN_FEAT_RSC180RDU }, \ { GPS_MODEL_USYNCPWR, BUILTIN_FEAT_USYNCPWR }, \ { GPS_MODEL_FDM180M, BUILTIN_FEAT_FDM180M }, \ + { GPS_MODEL_LSG180, BUILTIN_FEAT_LSG180 }, \ + { GPS_MODEL_GPS190, BUILTIN_FEAT_GPS190 }, \ + { GPS_MODEL_GNS181, BUILTIN_FEAT_GNS181 }, \ { 0, 0 } \ } @@ -4774,25 +4227,37 @@ enum ICODE_TX_CODES ) /** - * @brief A mask of IRIG TX formats supporting a 2 digit year number + * @brief A mask of IRIG TX formats providing a short year number after P5 + * + * The IEEE codes, the AFNOR codes, and some IRIG codes provide a + * 2 digit year number after position identifier P5. However, some + * IRIG G codes provide a 100ths-of-seconds field after P5,and + * eventually provide a year number after P6. + * + * @see @ref MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P6 + * @see @ref MSK_ICODE_TX_HAS_ANY_SHORT_YEAR */ -#define MSK_ICODE_TX_HAS_SHORT_YEAR \ -( \ - MSK_ICODE_TX_AFNOR | \ - MSK_ICODE_TX_IEEE1344 | \ - MSK_ICODE_TX_B2201344 | \ - MSK_ICODE_TX_B006_B126 | \ - MSK_ICODE_TX_B007_B127 | \ - MSK_ICODE_TX_G006_G146 | \ - MSK_ICODE_TX_C37118 | \ - MSK_ICODE_TX_A006_A136 | \ - MSK_ICODE_TX_A007_A137 \ +#define MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P5 \ +( \ + MSK_ICODE_TX_AFNOR | \ + MSK_ICODE_TX_IEEE1344 | \ + MSK_ICODE_TX_B2201344 | \ + MSK_ICODE_TX_B006_B126 | \ + MSK_ICODE_TX_B007_B127 | \ + MSK_ICODE_TX_C37118 | \ + MSK_ICODE_TX_A006_A136 | \ + MSK_ICODE_TX_A007_A137 \ ) /** - * @brief A mask of IRIG TX formats supporting a 2 digit year number + * @brief A mask of IRIG TX formats providing a short year number after P6 * - * This is after the P6 identifier. + * While most time codes that provide a year number do this after P5, + * there are some IRIG codes which provide a 100ths-of-seconds field + * at that position, and eventually provide a year number after P6. + * + * @see @ref MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P5 + * @see @ref MSK_ICODE_TX_HAS_ANY_SHORT_YEAR */ #define MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P6 \ ( \ @@ -4800,6 +4265,21 @@ enum ICODE_TX_CODES ) /** + * @brief A mask of IRIG TX formats providing a short year number in general + * + * Depending on the code format, the year number can be transmitted + * either after position identifier P5, or after P6. + * + * @see @ref MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P5 + * @see @ref MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P6 + */ +#define MSK_ICODE_TX_HAS_ANY_SHORT_YEAR \ +( \ + MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P5 | \ + MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P6 \ +) + +/** * @brief A mask of IRIG TX formats supporting TFOM */ #define MSK_ICODE_TX_HAS_TFOM \ @@ -6172,12 +5652,12 @@ enum POUT_MODES /// Switch 'on' or 'off' at the times specified in ::POUT_DATA::tm. POUT_TIMER, - /// Generate a pulse at the time specified in ::POUT_SETTINGS::POUT_DATA::tm[0]::on. + /// Generate a pulse at the time specified in ::POUT_SETTINGS::pout_data::tm[0]::on. /// Pulse length according to ::POUT_SETTINGS::mode_param, in [10 ms] units. /// See ::MAX_POUT_PULSE_LEN. POUT_SINGLE_SHOT, - /// Generate a cyclic pulse at the interval specified in ::POUT_SETTINGS::POUT_DATA::tm[0]:on::t. + /// Generate a cyclic pulse at the interval specified in ::POUT_SETTINGS::pout_data::tm[0]:on::t. /// Pulse length according to ::POUT_SETTINGS::mode_param, in [10 ms] units. /// See ::MAX_POUT_PULSE_LEN. POUT_CYCLIC_PULSE, @@ -6239,7 +5719,7 @@ enum POUT_MODES /// be in the range 0..::MBG_GPIO_CFG_LIMITS::num_io. POUT_GPIO, - /// A 1PPS signal with a fixed 20us pulse length + /// A 1 PPS signal with a fixed 20 us pulse length POUT_PTTI_PPS, /// A HaveQuick signal as configured in ::HAVEQUICK_SETTINGS::format @@ -6426,7 +5906,6 @@ enum POUT_MODES MSK_POUT_HAVEQUICK \ ) - /** @} anchor POUT_MODES_PARAM_MASKS */ @@ -6460,7 +5939,7 @@ enum POUT_MODES #define ENG_POUT_NAME_SYNTH "Synthesizer Frequency" #define ENG_POUT_NAME_TIME_SLOTS "Time Slots per Minute" #define ENG_POUT_NAME_GPIO "GPIO Signal" -#define ENG_POUT_PTTI_PPS "PTTI 1PPS" +#define ENG_POUT_PTTI_PPS "PTTI 1 PPS" #define ENG_POUT_HAVEQUICK "HaveQuick" /** @} anchor ENG_POUT_NAMES */ @@ -7269,9 +6748,12 @@ do \ * Used with the ::... field of ::XMULTI_REF_STATUS::flags * * @see ::XMULTI_REF_STATUS::flags - * @see ::XMR_QL_MASK - * @see ::_GET_XMR_QL - * @see ::_PUT_XMR_QL + * @see ::XMR_QL_TDEV_MASK + * @see ::_GET_XMR_QL_TDEV + * @see ::_PUT_XMR_QL_TDEV + * @see ::XMR_QL_MTIE_MASK + * @see ::_GET_XMR_QL_MTIE + * @see ::_PUT_XMR_QL_MTIE */ enum XMR_QL { @@ -9321,7 +8803,7 @@ do \ /** * @brief Enumeration of types used with GPIO type digital audio outputs * - * Used with ::MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT_SETTINGS::type, and used to + * Used with ::MBG_GPIO_DIGITAL_AUDIO_OUT_SETTINGS::type, and to * define ::MBG_GPIO_DIGITAL_AUDIO_TYPE_MASKS * * @see ::MBG_GPIO_DIGITAL_AUDIO_TYPE_MASKS @@ -9378,7 +8860,7 @@ enum MBG_GPIO_DIGITAL_AUDIO_FLAGS /** * @brief Bit masks associated with ::MBG_GPIO_DIGITAL_AUDIO_FLAGS * - * Used with ::MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT_SETTINGS::flags + * Used with ::MBG_GPIO_DIGITAL_AUDIO_OUT_SETTINGS::flags * * @see ::MBG_GPIO_DIGITAL_AUDIO_FLAGS */ @@ -9465,7 +8947,7 @@ enum MBG_GPIO_FLAGS /** * @brief Bit masks associated with ::MBG_GPIO_FLAGS * - * Used with ::MBG_GPIO_LIMITS::flags and ::MBG_GPIO_SETTINGS::flags + * Used with ::MBG_GPIO_LIMITS::supp_flags and ::MBG_GPIO_SETTINGS::flags * * @see ::MBG_GPIO_FLAGS */ @@ -11003,7 +10485,7 @@ do \ /** * @brief Flag bits used to define ::MBG_GNSS_MODE_INFO_FLAG_MASKS * - * @see ::MBG_GNSS_MODE_INFO_MASKS + * @see ::MBG_GNSS_MODE_INFO_FLAG_MASKS */ enum MBG_GNSS_MODE_INFO_FLAG_BITS { @@ -11016,9 +10498,9 @@ enum MBG_GNSS_MODE_INFO_FLAG_BITS /** - * @brief Flag masks used with MBG_GNSS_MODE_INFO::flags + * @brief Flag masks used with ::MBG_GNSS_MODE_INFO::flags * - * @see ::MBG_GNSS_MODE_FLAG_BITS + * @see ::MBG_GNSS_MODE_INFO_FLAG_BITS */ enum MBG_GNSS_MODE_INFO_FLAG_MASKS { @@ -11085,7 +10567,7 @@ do \ * @defgroup group_gnss_sv_status GNSS Satellite Status * * @note These structures and associated types are only supported by a device - * if ::MBG_XFEATURE_GNSS_SV_INFO is set in the extended device features. // FIXME + * if ::MBG_GNSS_FLAG_MSK_HAS_SV_STATUS is set // ::FIXME * * @{ */ @@ -11200,7 +10682,7 @@ do \ /** - * @brief Quality indicators used with ::GNSS_SV_STATUS::sv_stat + * @brief Quality indicators used with ::GNSS_SV_STATUS::stat_flags * * @see ::_gnss_sv_stat_quality_ind */ @@ -11218,7 +10700,7 @@ enum GNSS_SV_STAT_QUALITY_INDS /** - * @brief Health indicators used with ::GNSS_SV_STATUS::sv_stat + * @brief Health indicators used with ::GNSS_SV_STATUS::stat_flags * * @see ::_gnss_sv_stat_health_code */ @@ -11231,7 +10713,7 @@ enum GNSS_SV_STAT_HEALTH_CODES /** - * @brief Orbit source codes used with ::GNSS_SV_STATUS::sv_stat + * @brief Orbit source codes used with ::GNSS_SV_STATUS::stat_flags * * @see ::_gnss_sv_stat_orbit_src */ @@ -11460,10 +10942,13 @@ typedef char MBG_HOSTNAME[MBG_MAX_HOSTNAME_LEN]; ///< ASCIIZ format /** * @brief Hardware type for identification of physical interfaces * - * Use own definition for use under Windows, - * original ARPHRD_ETHER comes from linux/if_arp.h */ -#define MBG_ARPHRD_ETHER 1 +enum MBG_NET_HW_TYPES +{ + MBG_NET_HW_TYPE_UNKNOWN, + MBG_ARPHRD_ETHER, + N_MBG_NET_HW_TYPES +}; /** @@ -11826,7 +11311,7 @@ enum MBG_NET_INTF_LINK_PORT_TYPE_MASKS /** * @brief Initializers for network interface link port type long strings * - * @see ::MBG_NET_INTF_LINK_PORT_TYPE + * @see ::MBG_NET_INTF_LINK_PORT_TYPES */ #define MBG_NET_INTF_LINK_PORT_TYPE_LONG_STRS \ { \ @@ -11843,7 +11328,7 @@ enum MBG_NET_INTF_LINK_PORT_TYPE_MASKS /** * @brief Initializers for network interface link port type short strings * - * @see ::MBG_NET_INTF_LINK_PORT_TYPE + * @see ::MBG_NET_INTF_LINK_PORT_TYPES */ #define MBG_NET_INTF_LINK_PORT_TYPE_SHORT_STRS \ { \ @@ -12314,7 +11799,7 @@ typedef struct uint32_t flags; ///< Reserved, currently 0 uint32_t states; ///< see @ref MBG_NET_INTF_LINK_STATE_MASKS - uint32_t hw_type; ///< Hardware type of interface (see linux/if_arp.h, i.e. ARPHRD_ETHER) ::TODO + uint32_t hw_type; ///< Hardware type of interface (see ::MBG_NET_HW_TYPES) uint32_t mtu; ///< Max. packet size in bytes uint32_t txqlen; ///< Transmission queue length (number of packets) uint32_t speed; ///< Link speed in MBit/s @@ -14320,7 +13805,7 @@ enum SDH_NETWORK_OPTIONS /** - * @brief Flag masks used with ::MBG_SYNC_E_INFO::supp_sdh_network_opts + * @brief Flag masks used with MBG_SYNC_E_INFO::supp_sdh_network_opts ::FIXME * * @see ::SDH_NETWORK_OPTIONS */ @@ -14335,7 +13820,7 @@ enum SDH_NETWORK_OPTION_MASKS /** * @brief Name strings for SDH network options * - * @see ::SDH_NETWORK_OPTION + * @see ::SDH_NETWORK_OPTIONS */ #define SDH_NETWORK_OPTION_STRS \ { \ @@ -14365,7 +13850,7 @@ enum GBIT_LINK_COPPER_MODES /** - * @brief Flag masks used with ::MBG_SYNC_E_INFO::supp_gbit_link_copper_modes + * @brief Flag masks used with MBG_SYNC_E_INFO::supp_gbit_link_copper_modes ::FIXME * * @see ::GBIT_LINK_COPPER_MODES */ @@ -14875,7 +14360,8 @@ typedef struct int16_t grandmaster_variance; uint16_t grandmaster_sequence_number; uint16_t reserved_2; - uint32_t flags; + uint32_t flags; ///< see ::PTP_V1_PARENT_DATASET_FLAGS_MASKS + } MBG_PTP_V1_PARENT_DATASET; @@ -14905,20 +14391,20 @@ do \ enum PTP_V1_TIME_PROP_DATASET_DATASET_FLAGS { V1_TPROP_LEAP_59, - V1_TPROP_LEAP_61, + V1_TPROP_LEAP_61 }; /** - * @brief PTPv1 time drop dataset flag masks used with ::MBG_PTP_V1_TIME_PROP_DATASET::flags + * @brief PTPv1 time drop dataset flag masks used with ::MBG_PTP_V1_TIME_PROPERTIES_DATASET::flags * * @see ::PTP_V1_TIME_PROP_DATASET_DATASET_FLAGS */ enum PTP_V1_TIME_PROP_DATASET_FLAGS_MASKS { V1_TPROP_MSK_LEAP_59 = ( 1UL << V1_TPROP_LEAP_59 ), ///< see ::V1_TPROP_LEAP_59 - V1_TPROP_MSK_LEAP_61 = ( 1UL << V1_TPROP_LEAP_61 ), ///< see ::V1_TPROP_LEAP_61 + V1_TPROP_MSK_LEAP_61 = ( 1UL << V1_TPROP_LEAP_61 ) ///< see ::V1_TPROP_LEAP_61 }; @@ -14931,7 +14417,8 @@ typedef struct { int16_t current_utc_offset; uint16_t epoch_number; - uint32_t flags; + uint32_t flags; ///< see ::PTP_V1_TIME_PROP_DATASET_FLAGS_MASKS + } MBG_PTP_V1_TIME_PROPERTIES_DATASET; @@ -15116,7 +14603,7 @@ typedef struct */ typedef struct { - uint8_t parent_stats : 1; ///< indicates, whether the variance and change rate values are valid + uint8_t parent_stats : 1; ///< indicates whether the variance and change rate values are valid uint8_t reserved : 7; ///< reserved, currently always 0 } MBG_PTP_V2_PARENT_DATASET_FLAGS; @@ -15138,15 +14625,17 @@ typedef struct */ typedef struct { - PTP_PORT_IDENTITY parent_port_identity; ///< identity of the master port, that issues the sync messages, see ::PTP_PORT_IDENTITY - MBG_PTP_V2_PARENT_DATASET_FLAGS flags; ///< flags field, see ::MBG_PTP_V2_PARENT_DATASET_FLAGS - uint8_t reserved; ///< reserved, currently always 0 - uint16_t parent_log_variance; ///< estimate of the parent clock's PTP variance, only valid if ::flags::parent_stats is set - int32_t parent_phase_change_rate; ///< estimate of the parent clock's phase change rate, only valid if ::flags::parent_stats is set - uint8_t grandmaster_priority_1; ///< priority 1 attribute of the grandmaster clock - PTP_CLOCK_QUALITY grandmaster_clock_quality; ///< quality of the grandmaster clock, see ::PTP_CLOCK_QUALITY - uint8_t grandmaster_priority_2; ///< priority 2 attribute of the grandmaster clock - PTP_CLOCK_ID grandmaster_identity; ///< identity of the grandmaster clock, see ::PTP_CLOCK_ID + PTP_PORT_IDENTITY parent_port_identity; ///< Identity of the master port, that issues the sync messages, see ::PTP_PORT_IDENTITY + MBG_PTP_V2_PARENT_DATASET_FLAGS flags; ///< Flags field, see ::MBG_PTP_V2_PARENT_DATASET_FLAGS + uint8_t reserved; ///< Reserved, currently always 0 + uint16_t parent_log_variance; ///< Estimate of the parent clock's PTP variance, only valid if + ///< ::MBG_PTP_V2_PARENT_DATASET_FLAGS::parent_stats is set in ::MBG_PTP_V2_PARENT_DATASET::flags + int32_t parent_phase_change_rate; ///< Estimate of the parent clock's phase change rate, only valid if + ///< ::MBG_PTP_V2_PARENT_DATASET_FLAGS::parent_stats is set in ::MBG_PTP_V2_PARENT_DATASET::flags + uint8_t grandmaster_priority_1; ///< Priority 1 attribute of the grandmaster clock + PTP_CLOCK_QUALITY grandmaster_clock_quality; ///< Quality of the grandmaster clock, see ::PTP_CLOCK_QUALITY + uint8_t grandmaster_priority_2; ///< Priority 2 attribute of the grandmaster clock + PTP_CLOCK_ID grandmaster_identity; ///< Identity of the grandmaster clock, see ::PTP_CLOCK_ID } MBG_PTP_V2_PARENT_DATASET; @@ -15229,7 +14718,7 @@ typedef struct int8_t log_min_delay_req_interval; ///< minimum delay request interval for this port PTP_TIME_INTERVAL peer_mean_path_delay; ///< estimate of the current one-way propagation delay on the link, only valid if P2P is used, see ::PTP_TIME_INTERVAL int8_t log_announce_interval; ///< announce interval to be used by this port - uint8_t announce_receipt_timeout; ///< shall be an integral multiple of ::announce_interval + uint8_t announce_receipt_timeout; ///< shall be an integral multiple of ::MBG_PTP_V2_PORT_DATASET::log_announce_interval int8_t log_sync_interval; ///< mean sync interval to be used for multicast messages uint8_t delay_mechanism; ///< propagation delay measuring option, see ::PTP_DELAY_MECHS int8_t log_min_pdelay_req_interval; ///< minimum peer delay request interval for this port @@ -15610,7 +15099,7 @@ do \ */ typedef struct { - uint16_t idx; + uint32_t idx; NTP_RESTR restr; } NTP_RESTR_IDX; @@ -15618,7 +15107,7 @@ typedef struct #define _mbg_swab_ntp_restr_idx( _p ) \ do \ { \ - _mbg_swab16( &(_p)->idx ); \ + _mbg_swab32( &(_p)->idx ); \ _mbg_swab_ntp_restr( &(_p)->restr ); \ } while ( 0 ) @@ -15765,10 +15254,10 @@ typedef struct { uint8_t type; ///< See ::NTP_REFCLK_TYPES uint8_t instance; ///< Refclock instance of the specified type. Usually up to 4 instances of the same type are supported by ntpd. - uint8_t mode; ///< Driver specific "mode" //### TODO Flag to enable "mode"? + uint8_t mode; ///< Driver specific "mode" ::FIXME Flag to enable "mode"? int8_t stratum; ///< Stratum number to be fudged; -1 if unspecified and thus default is to be used - int8_t refid[4]; ///< Reference id used by driver //### TODO Flag to enable "refid"? + int8_t refid[4]; ///< Reference id used by driver ::FIXME Flag to enable "refid"? uint8_t minpoll; ///< Minimum polling interval, [log2 seconds], 0 if unused/unspecified uint8_t maxpoll; ///< Maximum polling interval, [log2 seconds], 0 if unused/unspecified @@ -15781,7 +15270,7 @@ typedef struct uint16_t drv_flags_enable; ///< Enable/disable driver specific flags, see @ref NTP_FUDGE_FLAG_NUMBERS uint16_t drv_flags_value; ///< 0 or 1, if (drv_flags_enable & x) == 1, see @ref NTP_FUDGE_FLAG_NUMBERS - uint32_t flags; ///< See @ref NTP_FLAG_MASKS. Only flags specified in ::TODO can be used here. + uint32_t flags; ///< See @ref NTP_FLAG_MASKS. Only flags specified in ::FIXME can be used here. uint32_t reserved_3; ///< Future use @@ -15806,7 +15295,7 @@ do \ */ typedef struct { - uint16_t idx; + uint32_t idx; NTP_REFCLK_CFG_SETTINGS settings; ///< See ::NTP_REFCLK_CFG_SETTINGS } NTP_REFCLK_CFG_SETTINGS_IDX; @@ -15814,7 +15303,7 @@ typedef struct #define _mbg_swab_ntp_refclk_cfg_settings_idx( _p ) \ do \ { \ - _mbg_swab16( &(_p)->idx ); \ + _mbg_swab32( &(_p)->idx ); \ _mbg_swab_ntp_refclk_cfg_settings( &(_p)->settings ); \ } while ( 0 ) @@ -15850,7 +15339,7 @@ do \ */ typedef struct { - uint16_t idx; + uint32_t idx; NTP_REFCLK_CFG_INFO info; } NTP_REFCLK_CFG_INFO_IDX; @@ -15858,7 +15347,7 @@ typedef struct #define _mbg_swab_ntp_refclk_cfg_info_idx( _p ) \ do \ { \ - _mbg_swab16( &(_p)->idx ); \ + _mbg_swab32( &(_p)->idx ); \ _mbg_swab_ntp_refclk_cfg_info( &(_p)->info ); \ } while ( 0 ) @@ -15934,6 +15423,11 @@ do \ /// prepared for hash algorithms like SHA256, SH384, up to SHA512. #define N_NTP_SYMM_KEY_LEN 128 +/// Maximum number of ip addresses which can be assign to each key in +/// order to limit usage +#define N_NTP_SYMM_KEY_MAX_IP_ADDR 8 + + /** * @brief NTP symmetric key specific settings @@ -15942,18 +15436,29 @@ do \ */ typedef struct { - uint16_t id; ///< Configurable key id (1..65534) - uint8_t hash; ///< See ::NTP_SYMM_KEY_HASHES - uint8_t reserved_1; ///< Future use - uint32_t reserved_2; ///< Future use - uint8_t key[N_NTP_SYMM_KEY_LEN]; ///< Hashed phrase, see ::N_NTP_SYMM_KEY_LEN + uint16_t id; ///< Configurable key id (1..65534) + uint8_t hash; ///< See ::NTP_SYMM_KEY_HASHES + uint8_t reserved_1; ///< Future use + + uint16_t reserved_2; ///< Future use + uint8_t num_ip_addr; ///< Number of configured ip addresses + uint8_t reserved_3; ///< Future use + + uint8_t key[N_NTP_SYMM_KEY_LEN]; ///< Hashed phrase, see ::N_NTP_SYMM_KEY_LEN + + MBG_IP_ADDR ip_addr[N_NTP_SYMM_KEY_MAX_IP_ADDR]; ///< Whitelist of ip addresses see ::N_NTP_SYMM_KEY_MAX_IP_ADDR } NTP_SYMM_KEY_SETTINGS; -#define _mbg_swab_ntp_symm_key_settings( _p ) \ -do \ -{ \ - _mbg_swab16( &(_p)->id ); \ +#define _mbg_swab_ntp_symm_key_settings( _p ) \ +do \ +{ \ + unsigned i; \ + \ + _mbg_swab16( &(_p)->id ); \ + \ + for ( i = 0; i < N_NTP_SYMM_KEY_MAX_IP_ADDR; ++i) \ + _mbg_swab_ip_addr( &(_p)->ip_addr[i] ); \ } while ( 0 ) @@ -15965,7 +15470,7 @@ do \ */ typedef struct { - uint16_t idx; + uint32_t idx; NTP_SYMM_KEY_SETTINGS settings; } NTP_SYMM_KEY_SETTINGS_IDX; @@ -15973,7 +15478,7 @@ typedef struct #define _mbg_swab_ntp_symm_key_settings_idx( _p ) \ do \ { \ - _mbg_swab16( &(_p)->idx ); \ + _mbg_swab32( &(_p)->idx ); \ _mbg_swab_ntp_symm_key_settings( &(_p)->settings ); \ } while ( 0 ) @@ -16008,7 +15513,7 @@ do \ */ typedef struct { - uint16_t idx; + uint32_t idx; NTP_SYMM_KEY_INFO info; } NTP_SYMM_KEY_INFO_IDX; @@ -16016,7 +15521,7 @@ typedef struct #define _mbg_swab_ntp_symm_key_info_idx( _p ) \ do \ { \ - _mbg_swab16( &(_p)->idx ); \ + _mbg_swab32( &(_p)->idx ); \ _mbg_swab_ntp_symm_key_info( &(_p)->info ); \ } while ( 0 ) @@ -16048,7 +15553,7 @@ do \ */ typedef struct { - uint16_t idx; + uint32_t idx; NTP_TRUSTED_KEY_SETTINGS settings; } NTP_TRUSTED_KEY_SETTINGS_IDX; @@ -16056,7 +15561,7 @@ typedef struct #define _mbg_swab_ntp_trusted_key_settings_idx( _p ) \ do \ { \ - _mbg_swab16( &(_p)->idx ); \ + _mbg_swab32( &(_p)->idx ); \ _mbg_swab_ntp_trusted_key_settings( &(_p)->settings ); \ } while ( 0 ) @@ -16090,7 +15595,7 @@ do \ */ typedef struct { - uint16_t idx; + uint32_t idx; NTP_TRUSTED_KEY_INFO info; } NTP_TRUSTED_KEY_INFO_IDX; @@ -16098,7 +15603,7 @@ typedef struct #define _mbg_swab_ntp_trusted_key_info_idx( _p ) \ do \ { \ - _mbg_swab16( &(_p)->idx ); \ + _mbg_swab32( &(_p)->idx ); \ _mbg_swab_ntp_trusted_key_info( &(_p)->info ); \ } while ( 0 ) @@ -16578,9 +16083,9 @@ do \ */ typedef struct { - uint8_t num_refclks; ///< number of available refclks @ref NTP_REFCLK_CFG_INFO - uint8_t reserved_1; ///< reserved, currently 0 - uint16_t reserved_2; ///< reserved, currently 0 + uint8_t num_refclks; ///< number of available refclks @ref NTP_REFCLK_CFG_INFO + uint8_t reserved_1; ///< reserved, currently 0 + uint16_t reserved_2; ///< reserved, currently 0 uint32_t reserved_3; ///< reserved, currently 0 @@ -16971,6 +16476,7 @@ enum NTP_SYS_STATE_SUPP_FLAGS NTP_SYS_STATE_SUPP_SYS_JITTER, ///< supports combined jitter, see ::NTP_SYS_STATE::sys_jitter NTP_SYS_STATE_SUPP_CLK_JITTER, ///< supports clock jitter, see ::NTP_SYS_STATE::clk_jitter NTP_SYS_STATE_SUPP_CLK_WANDER, ///< supports clock wander, see ::NTP_SYS_STATE::clk_wander + NTP_SYS_STATE_SUPP_SYS_ASSOC, ///< supports sys assoc ID as sys peer, see ::NTP_SYS_STATE::sys_assoc N_NTP_SYS_STATE_SUPP_FLAGS }; @@ -16993,7 +16499,8 @@ enum NTP_SYS_STATE_SUPP_FLAG_MASKS NTP_SYS_STATE_SUPP_FREQ_MSK = ( 1UL << NTP_SYS_STATE_SUPP_FREQ ), ///< see ::NTP_SYS_STATE_SUPP_FREQ NTP_SYS_STATE_SUPP_SYS_JITTER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_SYS_JITTER ), ///< see ::NTP_SYS_STATE_SUPP_SYS_JITTER NTP_SYS_STATE_SUPP_CLK_JITTER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_CLK_JITTER ), ///< see ::NTP_SYS_STATE_SUPP_CLK_JITTER - NTP_SYS_STATE_SUPP_CLK_WANDER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_CLK_WANDER ) ///< see ::NTP_SYS_STATE_SUPP_CLK_WANDER + NTP_SYS_STATE_SUPP_CLK_WANDER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_CLK_WANDER ), ///< see ::NTP_SYS_STATE_SUPP_CLK_WANDER + NTP_SYS_STATE_SUPP_SYS_ASSOC_MSK = ( 1UL << NTP_SYS_STATE_SUPP_SYS_ASSOC ) ///< see ::NTP_SYS_STATE_SUPP_SYS_ASSOC }; @@ -17023,7 +16530,7 @@ typedef struct uint8_t stratum; ///< Current stratum level of the system int8_t precision; ///< Precision of the system clock (2^precision) - uint16_t reserved_1; ///< Reserved, currently always 0 + uint16_t sys_assoc; ///< Association ID of the current system peer, do not use NTP_SYS_STATE::sys_peer if this is supported int32_t root_delay; ///< [us] Total roundtrip delay to the system peer int32_t root_disp; ///< [us] Total dispersion to the system peer @@ -17033,7 +16540,7 @@ typedef struct NTP_TSTAMP ref_time; ///< Last time the system time has been adjusted, see ::NTP_TSTAMP NTP_TSTAMP sys_time; ///< Current system time, see ::NTP_TSTAMP - uint16_t sys_peer; ///< Assocation ID of the current system peer + uint16_t sys_peer; ///< Index of the current system peer uint8_t poll; ///< Current polling interval for the system peer (tc) uint8_t minpoll; ///< Minimal polling interval for the system peer (mintc) @@ -17044,7 +16551,10 @@ typedef struct int32_t clk_jitter; ///< [us] Jitter of the clock int32_t clk_wander; ///< [ppb] Frequency wander of the clock - uint32_t reserved_2; ///< Reserved, currently always 0 + uint8_t cfg_counter; ///< Updated (increased) when config changes + uint8_t reserved_1; ///< Reserved, currently always 0 + uint16_t reserved_2; ///< Reserved, currently always 0 + uint32_t reserved_3; ///< Reserved, currently always 0 } NTP_SYS_STATE; @@ -17070,7 +16580,7 @@ do \ \ _mbg_swab8( &(_p)->stratum ); \ _mbg_swab8( &(_p)->precision ); \ - _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab16( &(_p)->sys_assoc ); \ \ _mbg_swab32( &(_p)->root_delay ); \ _mbg_swab32( &(_p)->root_disp ); \ @@ -17589,7 +17099,7 @@ typedef struct uint32_t reserved_9; ///< Reserved, currently always 0 -} NTP_PEER_STATE; +} NTP_PEER_STATE, NTP_REFCLK_STATE; @@ -17657,6 +17167,7 @@ do \ \ } while ( 0 ) +#define _mbg_swab_ntp_refclk_state ( _p ) _mbg_swab_ntp_peer_state( _p ) /** @@ -17671,7 +17182,8 @@ typedef struct uint32_t idx; ///< The index of the observed NTP peer NTP_PEER_STATE peer_state; ///< Peer state, see ::NTP_PEER_STATE -} NTP_PEER_STATE_IDX; +} NTP_PEER_STATE_IDX, NTP_REFCLK_STATE_IDX; + #define _mbg_swab_ntp_peer_state_idx( _p ) \ do \ @@ -17681,6 +17193,9 @@ do \ } while ( 0 ) +#define _mbg_swab_ntp_refclk_state_idx( _p ) _mbg_swab_ntp_peer_state_idx( _p ) + + /** @} defgroup group_ntp */ @@ -17693,7 +17208,7 @@ do \ #define MAX_LNO_OUTPUT 4 /** - * @brief LNO status + * @brief LNO state */ typedef struct { @@ -17723,7 +17238,7 @@ do \ /** - * @brief Flags used with LNO_STATE::flags + * @brief Flags used with ::LNO_STATE::flags */ enum LNO_STATE_FLAG_BITS { @@ -18249,6 +17764,9 @@ enum MBG_TLV_FEAT_TYPES /// 1) ::MBG_TLV_TYPE_BLOB => ::MBG_LICENSE_TIME_MONITOR_IDX, see @ref group_license_limits MBG_TLV_FEAT_TYPE_LICENSE_TIME_MONITOR_IDX, + /// 1) ::MBG_TLV_TYPE_BLOB => Unified Firmware Update (UFU) file, see mbg_ufu.h + MBG_TLV_FEAT_TYPE_UFU, + N_MBG_TLV_FEAT_TYPES // NOTE If new TLV feature types are appended here then an appropriate // name string has to be appended to ::MBG_TLV_FEAT_TYPE_NAMES, and care must @@ -18277,7 +17795,8 @@ enum MBG_TLV_FEAT_TYPES "TLV License NTP", \ "TLV File Request", \ "TLV License PTPV1 IDX", \ - "TLV License Time Monitor" \ + "TLV License Time Monitor", \ + "TLV Unified Firmware Update" \ } @@ -18780,7 +18299,7 @@ typedef struct /** - * @defgroup group_led_api Meinberg TLV API definitions + * @defgroup group_led_api Meinberg LED API definitions * * @note These structures and definitions are only supported by a device * if ::MBG_XFEATURE_LED_API is set in the extended device features. @@ -19444,8 +18963,7 @@ do \ /** * @defgroup group_license_limits License information * - * @note This structure and its definitions are only supported by a device - * if ::MBG_XFEATURE_LICENSE_LIMITS is set in the extended device features. + * @note This is probably obsolete. * * @{ */ @@ -19733,7 +19251,7 @@ do \ /** * @brief Bits used to define ::MBG_LICENSE_TIME_MONITOR_MEMBER_MSKS * - * @see ::MBG_LICENSE_TIME:MONITOR_MEMBER_MSKS + * @see ::MBG_LICENSE_TIME_MONITOR_MEMBER_MSKS */ enum MBG_LICENSE_TIME_MONITOR_MEMBERS { @@ -19964,14 +19482,12 @@ enum MBG_TRANSACTION_TYPES * @{ */ /** - * @brief Port types + * @brief IO Port types * - * Used with ::MBG_IO_PORT_TYPE_INFO::type and - * :: MBG_IO_PORT_SETTINGS::type + * Used with ::MBG_IO_PORT_TYPE_INFO::port_type and ::MBG_IO_PORT_SETTINGS::port_type */ enum MBG_IO_PORT_TYPES { - MBG_IO_PORT_TYPE_NONE = -1, ///< Only use this for ::MBG_IO_PORT_SETTINGS::type if ::MBG_IO_PORT_SETTINGS::op_mode is ::MBG_IO_PORT_OP_MODE_NONE MBG_IO_PORT_TYPE_PPS, MBG_IO_PORT_TYPE_10MHz, MBG_IO_PORT_TYPE_2048KHz, @@ -19983,6 +19499,14 @@ enum MBG_IO_PORT_TYPES N_MBG_IO_PORT_TYPES }; +/** + * @brief Port type to be used for an undefined/unassigned port + * + * Only use this for ::MBG_IO_PORT_SETTINGS::port_type + * if ::MBG_IO_PORT_SETTINGS::op_mode is ::MBG_IO_PORT_OP_MODE_NONE + */ +#define MBG_IO_PORT_TYPE_NONE ( (uint16_t) -1 ) + /** * @brief Strings descriptions for ::MBG_IO_PORT_TYPES @@ -20120,7 +19644,7 @@ enum MBG_IO_PORT_SRC_MSKS /** * @brief Port connector types * - * Used with ::MBG_IO_PORT_TYPE_INFO::conn_type + * Used with ::MBG_IO_PORT_INFO::conn_type * */ enum MBG_IO_PORT_CONN_TYPES @@ -20224,7 +19748,6 @@ enum MBG_IO_PORT_POS_MSKS * @see ::MBG_IO_PORT_SETTINGS_U * @see ::MBG_IO_PORT_SETTINGS_IDX * @see ::MBG_IO_PORT_INFO - * @see ::MBG_IO_PORT_INFO_U * @see ::MBG_IO_PORT_INFO_IDX * @see ::MBG_IO_PORT_TYPE_INFO * @see ::MBG_IO_PORT_TYPE_INFO_IDX @@ -20361,7 +19884,6 @@ enum MBG_IO_PORT_GRP_ROLE_MSKS * @see ::MBG_IO_PORT_LIMITS * @see ::MBG_IO_PORT_SETTINGS_IDX * @see ::MBG_IO_PORT_INFO - * @see ::MBG_IO_PORT_INFO_U * @see ::MBG_IO_PORT_INFO_IDX * @see ::MBG_IO_PORT_TYPE_INFO * @see ::MBG_IO_PORT_TYPE_INFO_IDX @@ -20406,7 +19928,6 @@ do \ * @see ::MBG_IO_PORT_LIMITS * @see ::MBG_IO_PORT_SETTINGS_IDX * @see ::MBG_IO_PORT_INFO - * @see ::MBG_IO_PORT_INFO_U * @see ::MBG_IO_PORT_INFO_IDX * @see ::MBG_IO_PORT_TYPE_INFO * @see ::MBG_IO_PORT_TYPE_INFO_IDX @@ -20415,7 +19936,7 @@ do \ */ typedef struct { - uint16_t type; ///< ::MBG_IO_PORT_TYPES + uint16_t port_type; ///< ::MBG_IO_PORT_TYPES uint8_t direction; ///< ::MBG_IO_PORT_DIRS uint8_t source; ///< ::MBG_IO_PORT_SRCS uint8_t op_mode; ///< ::MBG_IO_PORT_OP_MODE_BITS @@ -20427,17 +19948,17 @@ typedef struct * See ::MBG_IO_PORT_SETTINGS_MIN_SIZE */ - MBG_IO_PORT_SETTINGS_U data; ///< Data union for setting's type + MBG_IO_PORT_SETTINGS_U data; ///< Data union for settings' type } MBG_IO_PORT_SETTINGS; #define _mbg_swab_io_port_settings( _p, _recv ) \ do \ { \ - uint16_t t = (_p)->type; \ + uint16_t t = (_p)->port_type; \ if ( (_recv) ) \ _mbg_swab16( &t ); \ - _mbg_swab16( &(_p)->type ); \ + _mbg_swab16( &(_p)->port_type ); \ _mbg_swab_io_port_settings_u( t, &(_p)->data, (_recv) ); \ } while ( 0 ) @@ -20452,7 +19973,6 @@ do \ * @see ::MBG_IO_PORT_LIMITS * @see ::MBG_IO_PORT_SETTINGS * @see ::MBG_IO_PORT_INFO - * @see ::MBG_IO_PORT_INFO_U * @see ::MBG_IO_PORT_INFO_IDX * @see ::MBG_IO_PORT_TYPE_INFO * @see ::MBG_IO_PORT_TYPE_INFO_IDX @@ -20504,7 +20024,6 @@ do \ * @see ::MBG_IO_PORT_LIMITS * @see ::MBG_IO_PORT_SETTINGS * @see ::MBG_IO_PORT_SETTINGS_IDX - * @see ::MBG_IO_PORT_INFO_U * @see ::MBG_IO_PORT_INFO_IDX * @see ::MBG_IO_PORT_TYPE_INFO * @see ::MBG_IO_PORT_TYPE_INFO_IDX @@ -20785,11 +20304,11 @@ enum MBG_IO_PORT_STATUS_BITS * ::N_MBG_IO_PORT_STATUS_BITS are currently defined. * * The ::_set_io_port_status_bit macro should be used by the firmware - * to set a status bit in the buffer, and the ::check_byte_array_bit + * to set a status bit in the buffer, and the ::check_feat_supp_byte_array * to check if a bit is set * * @see ::_set_io_port_status_bit - * @see ::check_byte_array_bit + * @see ::check_feat_supp_byte_array */ typedef struct { @@ -20999,10 +20518,10 @@ typedef struct { MBG_SNMP_GLB_SETTINGS settings; uint8_t supp_versions; ///< See ::MBG_SNMP_VERSION_MSKS - uint8_t max_v12_settings; ///< Only valid if ::supp_versions contains ::MBG_SNMP_VERSION_MSK_V1 or ::MBG_SNMP_VERSION_MSK_V2c - uint8_t max_v3_settings; ///< Only valid if ::supp_versions contains ::MBG_SNMP_VERSION_MSK_V3 - uint8_t max_v12_trap_receivers; ///< Only valid if ::supp_versions contains ::MBG_SNMP_VERSION_MSK_V1 or ::MBG_SNMP_VERSION_MSK_V2c - uint8_t max_v3_trap_receivers; ///< Only valid if ::supp_versions contains ::MBG_SNMP_VERSION_MSK_V3 + uint8_t max_v12_settings; ///< Only valid if ::MBG_SNMP_GLB_INFO::supp_versions contains ::MBG_SNMP_VERSION_MSK_V1 or ::MBG_SNMP_VERSION_MSK_V2c + uint8_t max_v3_settings; ///< Only valid if ::MBG_SNMP_GLB_INFO::supp_versions contains ::MBG_SNMP_VERSION_MSK_V3 + uint8_t max_v12_trap_receivers; ///< Only valid if ::MBG_SNMP_GLB_INFO::supp_versions contains ::MBG_SNMP_VERSION_MSK_V1 or ::MBG_SNMP_VERSION_MSK_V2c + uint8_t max_v3_trap_receivers; ///< Only valid if ::MBG_SNMP_GLB_INFO::supp_versions contains ::MBG_SNMP_VERSION_MSK_V3 uint8_t reserved_1[3]; uint32_t reserved_2[2]; @@ -21034,7 +20553,7 @@ enum MBG_SNMP_ACCESS_TYPES typedef struct { - uint8_t version; ///< See ::MBG_MONITORING_SNMP_VERSIONS (1 or 2) + uint8_t version; ///< See ::MBG_SNMP_VERSIONS uint8_t access_type; ///< See ::MBG_SNMP_ACCESS_TYPES, ignore in trap settings uint8_t reserved_1[2]; uint32_t reserved_2[3]; @@ -21220,20 +20739,21 @@ enum MBG_SNMP_V3_PRIV_PROTOCOLS typedef struct { uint8_t access_type; ///< See ::MBG_SNMP_ACCESS_TYPES, ignore in trap settings - uint8_t sec_level; ///< See ::MBG_SNMP_V3_SEC_LEVEL - uint8_t auth_protocol; ///< See ::MBG_SNMP_V3_AUTH_PROTOCOLS if ::sec_level is - ///< ::MBG_SNMP_V3_SEC_LEVEL_AUTH_NO_PRIV or ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV - uint8_t priv_protocol; ///< See ::MBG_SNMP_V3_PRIV_PROTOCOLS if ::sec_level is - ///< ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV + uint8_t sec_level; ///< See ::MBG_SNMP_V3_SEC_LEVELS + uint8_t auth_protocol; ///< See ::MBG_SNMP_V3_AUTH_PROTOCOLS if ::MBG_SNMP_V3_SETTINGS::sec_level + ///< is ::MBG_SNMP_V3_SEC_LEVEL_AUTH_NO_PRIV or ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV + uint8_t priv_protocol; ///< See ::MBG_SNMP_V3_PRIV_PROTOCOLS if ::MBG_SNMP_V3_SETTINGS::sec_level + ///< is ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV uint32_t reserved_1[3]; - char user_name[MBG_MONITORING_STR_SIZE]; ///< Must be set - char auth_passwd[MBG_MONITORING_STR_SIZE]; ///< Passwd is for user if ::auth_protocol is ::MBG_SNMP_V3_SEC_LEVEL_AUTH_NO_PRIV or ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV + char user_name[MBG_MONITORING_STR_SIZE]; ///< User name used for authentication, always required. + char auth_passwd[MBG_MONITORING_STR_SIZE]; ///< Password associated with ::MBG_SNMP_V3_SETTINGS::user_name, if ::MBG_SNMP_V3_SETTINGS::auth_protocol + ///< is ::MBG_SNMP_V3_SEC_LEVEL_AUTH_NO_PRIV or ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV char sec_engine_id[MBG_MONITORING_STR_SIZE]; ///< Mandatory char context_engine_id[MBG_MONITORING_STR_SIZE]; ///< Ignore char context_name[MBG_MONITORING_STR_SIZE]; ///< Ignore char reserved_2[MBG_MONITORING_STR_SIZE]; ///< Future use char reserved_3[MBG_MONITORING_STR_SIZE]; ///< Future use - char priv_passwd[MBG_MONITORING_STR_SIZE]; /// Encryption passwd if ::auth_protocol is ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV + char priv_passwd[MBG_MONITORING_STR_SIZE]; ///< Encryption passwd if ::MBG_SNMP_V3_SETTINGS::auth_protocol is ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV uint32_t boots; ///< Number of system/deamon restarts -> Ignore uint32_t time; ///< Timeticks since last "boots" event -> Ignore uint32_t reserved_4[2]; @@ -21408,7 +20928,7 @@ typedef struct uint8_t severity; ///< See ::MBG_EVENT_SEVERITIES uint8_t reserved_1; uint16_t triggers; ///< See ::MBG_MONITORING_TYPE_MSKS if set in ::MBG_MONITORING_LIMITS::supp_types - uint16_t interval; ///< In seconds if ::MBG_EVENT_FLAG_MSK_INTERVAL is set in ::MBG_EVENT_INFO::supp_flags. 0 otherwise + uint16_t interval; ///< [s], only if ::MBG_EVENT_SUPP_FLAG_INTERVAL is set in ::MBG_EVENT_INFO::supp_flags, else 0. uint16_t reserved_2; uint32_t reserved_3[6]; @@ -21446,7 +20966,7 @@ do \ enum MBG_EVENT_SUPP_FLAGS { - MBG_EVENT_SUPP_FLAG_INTERVAL, ///< Event can be sent cyclical + MBG_EVENT_SUPP_FLAG_INTERVAL, ///< Event can be sent cyclically N_MBG_EVENT_SUPP_FLAGS }; @@ -21513,7 +21033,7 @@ do \ * * @note idx represents the event type, see ::MBG_EVENT_TYPES * Before requesting the struct, its availability should be checked - * in ::MBG_MONITORING_LIMITS::supp_events. + * in ::MBG_MONITORING_LIMITS::supp_num_events. * * @see ::MBG_EVENT_TYPES * @see ::MBG_MONITORING_LIMITS @@ -21601,7 +21121,7 @@ do \ /** - * @defgroup group_usb_lock + * @defgroup group_usb_lock USB locks * * @note This structure and its definitions are only supported by a device * if ::MBG_XFEATURE_USB_LOCK is set in the extended device features. @@ -21615,7 +21135,7 @@ do \ enum MBG_USB_LOCK_FLAGS { - MBG_USB_LOCK_FLAG_ACTIVE, ///< USB Connection is interrupted + MBG_USB_LOCK_FLAG_ACTIVE, ///< USB connection is interrupted N_MBG_USB_LOCK_FLAGS }; diff --git a/mbglib/common/gpsutils.c b/mbglib/common/gpsutils.c index 2388df3..48cefc1 100755 --- a/mbglib/common/gpsutils.c +++ b/mbglib/common/gpsutils.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: gpsutils.c 1.9.1.7 2016/08/11 12:45:54 martin TEST $ + * $Id: gpsutils.c 1.10 2017/07/05 13:57:06 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,16 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: gpsutils.c $ - * Revision 1.9.1.7 2016/08/11 12:45:54 martin - * Revision 1.9.1.6 2016/08/09 15:56:50Z martin - * Fixed format bug. - * Revision 1.9.1.5 2016/07/22 09:57:11 martin - * Quieted some compiler warninges. - * Revision 1.9.1.4 2015/09/07 09:19:58 martin - * Revision 1.9.1.3 2015/08/27 16:24:41 martin - * Revision 1.9.1.2 2015/08/25 15:34:48 martin + * Revision 1.10 2017/07/05 13:57:06 martin * Use save string functions from str_util.c. - * Revision 1.9.1.1 2015/08/21 14:21:57 martin + * Quieted some compiler warninges. + * Added doxygen comments. * 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. @@ -66,8 +60,8 @@ #if USE_SNPRINTF #include <str_util.h> -// #include <pcpslstr.h> -#define DEG "deg" + + #define DEG "deg" #endif #if _USE_GPSUTILS_FULL @@ -372,7 +366,7 @@ size_t snprint_pos_geo( char *s, size_t max_len, const POS *p, char sep, int pre return n; -} // sprint_pos_geo +} // snprint_pos_geo #endif // USE_SNPRINTF diff --git a/mbglib/common/gpsutils.h b/mbglib/common/gpsutils.h index 6fe959a..fd25e3e 100755 --- a/mbglib/common/gpsutils.h +++ b/mbglib/common/gpsutils.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: gpsutils.h 1.7.1.4 2016/08/11 13:50:01 martin TEST $ + * $Id: gpsutils.h 1.8 2017/07/05 13:58:25 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,12 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: gpsutils.h $ - * Revision 1.7.1.4 2016/08/11 13:50:01 martin + * Revision 1.8 2017/07/05 13:58:25 martin * Include stddef.h. - * Revision 1.7.1.3 2015/08/27 16:24:41Z martin - * Revision 1.7.1.2 2015/08/25 15:34:48 martin - * Use save string functions from str_util.c. - * Revision 1.7.1.1 2015/08/21 14:22:06 martin + * Updated function prototypes. * Revision 1.7 2010/07/15 09:32:09 martin * Use DEG character definition from pcpslstr.h. * Revision 1.6 2005/02/18 10:32:33Z martin @@ -53,13 +50,12 @@ /* Start of header body */ - -/* function prototypes: */ - #ifdef __cplusplus extern "C" { #endif + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/identdec.h b/mbglib/common/identdec.h index 6054ec7..2eff9fc 100755 --- a/mbglib/common/identdec.h +++ b/mbglib/common/identdec.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: identdec.h 1.1 2002/02/19 13:46:19 MARTIN REL_M $ + * $Id: identdec.h 1.2 2017/05/10 15:21:36 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: identdec.h $ + * Revision 1.2 2017/05/10 15:21:36 martin + * Tiny cleanup. * Revision 1.1 2002/02/19 13:46:19 MARTIN * Initial revision * @@ -34,16 +36,11 @@ /* Start of header body */ - - - - -/* function prototypes: */ - #ifdef __cplusplus extern "C" { #endif + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/lan_util.c b/mbglib/common/lan_util.c index 168aede..5fc9de1 100755 --- a/mbglib/common/lan_util.c +++ b/mbglib/common/lan_util.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: lan_util.c 1.11.1.15 2017/05/03 07:43:10 daniel TEST $ + * $Id: lan_util.c 1.12 2017/07/05 14:07:56 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,42 +10,25 @@ * * ----------------------------------------------------------------------- * $Log: lan_util.c $ - * Revision 1.11.1.15 2017/05/03 07:43:10 daniel - * Check port link in funtion get_port_ip4_settings() even if it returns an error - * Revision 1.11.1.14 2017/04/10 13:05:16 martin - * Fixed some compiler warnings. - * Revision 1.11.1.13 2017/02/23 15:24:22Z martin - * Fixed macro definition syntax to avoid clang compiler warnings. - * Revision 1.11.1.12 2016/10/31 17:39:47 martin - * Only return standard MBG_RETURN_CODES. - * Removed definitions of old MBG_LU_... return codes. - * Renamed check_octets_not_all_zero() to octets_are_all_zero(), which returns a bool now. - * Renamed check_mac_addr_not_all_zero() to mac_addr_all_zero(), which returns a bool now. + * Revision 1.12 2017/07/05 14:07:56 martin + * IPv6 support functions added by hannes. + * Function snprint_ip4_cidr_mask() fixed by hannes. It now behaves + * as expected and appends the CIDR mask bits to the IP address now. + * Mostly use safe string functions from str_util.c. + * New function snprint_ptp_clock_id(). + * Compiler warnings due to uninitialized vars quieted by thomas-b. + * Renamed check_octets_not_all_zero() to octets_are_all_zero(), + * which returns a bool now. + * Renamed check_mac_addr_not_all_zero() to mac_addr_all_zero(), + * which returns a bool now. * Removed get_port_mac_addr_check(). - * Updated doxygen comments. - * Revision 1.11.1.11 2016/09/22 12:25:26 thomas-b - * Fixed compiler warning for uninitialized vars - * Revision 1.11.1.10 2016/08/10 12:25:54 martin + * Removed definitions of old MBG_LU_... return codes, and + * only use standard MBG_RETURN_CODES instead. + * Fixed macro definition syntax to quiet clang compiler warnings. + * Let get_port_ip4_settings() check port link even if it + * returns an error (changed by daniel). * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. - * Revision 1.11.1.9 2016/08/09 07:10:22 martin - * *** empty log message *** - * Revision 1.11.1.8 2015/12/01 11:35:31 martin - * Doxygen fixes. - * Revision 1.11.1.7 2015/11/11 18:16:08 martin - * New function snprint_ptp_clock_id(). - * Revision 1.11.1.6 2015/11/04 17:06:35Z martin - * *** empty log message *** - * Revision 1.11.1.5 2015/09/17 10:06:30 martin - * Revision 1.11.1.4 2015/08/31 10:26:26Z martin - * Revision 1.11.1.3 2015/08/27 16:23:16Z martin - * Use safe string functions from str_util.c. - * Cleanup. - * Revision 1.11.1.2 2015/04/13 15:26:50 hannes - * Added all function defintions for IP6. - * FIX: Fixed snprint_ip4_cidr_mask to behave as expected. - * It will concatenate the cidr mask bits to the ip address now. - * Revision 1.11.1.1 2015/04/02 15:28:31 hannes - * Started adding the ipv4 functions for ipv6. + * Doxygen comments. * Revision 1.11 2015/04/01 14:31:14 hannes * Fix: cidr_str_to_ip4_addr_and_net_mask: Defaults correctly to * netmask 0.0.0.0 (/0) for no CIDR extension in cidr_str. @@ -290,7 +273,7 @@ size_t snprint_ip4_cidr_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, - * specifically ::MBG_ERR_INV_PARM if an invalid number or character was found in the string. + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. * * @see ::snprint_ip4_addr * @see ::snprint_ip4_cidr_addr @@ -309,7 +292,7 @@ int str_to_ip4_addr( IP4_ADDR *p_addr, const char *s ) unsigned long ul = strtoul( (char *) cp, (char **) &cp, 10 ); if ( ul > 0xFFUL ) // invalid number - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; tmp_ip4_addr |= ul << ( 8 * (3 - i) ); @@ -317,7 +300,7 @@ int str_to_ip4_addr( IP4_ADDR *p_addr, const char *s ) break; // done if ( *cp != '.' ) - return MBG_ERR_INV_PARM; // invalid string format, dot expected + return MBG_ERR_PARM_FMT; // invalid string format, dot expected cp++; // skip dot } @@ -348,7 +331,7 @@ int str_to_ip4_addr( IP4_ADDR *p_addr, const char *s ) * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, - * specifically ::MBG_ERR_INV_PARM if an invalid number or character was found in the string. + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. * * @see ::snprint_ip4_addr * @see ::snprint_ip4_cidr_addr @@ -370,7 +353,7 @@ int cidr_str_to_ip4_addr_and_net_mask( IP4_ADDR *p_addr, IP4_ADDR *p_mask, l = (int) strlen( cidr_str ); if ( l < rc ) // input string too short - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; cp = &cidr_str[rc]; @@ -385,7 +368,7 @@ int cidr_str_to_ip4_addr_and_net_mask( IP4_ADDR *p_addr, IP4_ADDR *p_mask, if ( *cp != '/' ) - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; cp++; @@ -546,7 +529,7 @@ size_t snprint_ip6_addr( char *s, size_t max_len, const IP6_ADDR *p_addr, const /* Is this address an encapsulated IPv4? */ if ( i == 6 && best.base == 0 && ( best.len == 6 || ( best.len == 5 && words[5] == 0xffff ) ) ) - return MBG_ERR_INV_PARM; // we don't support ecapsulated IPv4 + return MBG_ERR_INV_PARM; // we don't support encapsulated IPv4 sprintf( tp, "%x", words[i] ); tp += strlen( tp ); @@ -669,7 +652,7 @@ size_t snprint_ip6_cidr_mask_addr( char *s, size_t max_len, const IP6_ADDR *p_ad * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, - * specifically ::MBG_ERR_INV_PARM if an invalid number or character was found in the string. + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. * * @see ::snprint_ip6_addr * @see ::snprint_ip6_cidr_addr @@ -705,7 +688,7 @@ int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) read_cnt++; if ( *++s != ':' ) - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; } saw_xdigit = 0; @@ -725,7 +708,7 @@ int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) val |= ( pch - xdigits ); if ( val > 0xffff ) //### TODO signed? unsigned? - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; saw_xdigit = 1; continue; @@ -736,7 +719,7 @@ int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) if ( !saw_xdigit ) { if ( colonp ) - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; colonp = tp; continue; @@ -744,10 +727,10 @@ int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) } else if ( *s == '\0' ) - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; if ( tp - sizeof( uint16_t ) < startp ) - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; *tp-- = (uint8_t) ( val >> 8 ) & 0xff; *tp-- = (uint8_t) val & 0xff; @@ -762,13 +745,13 @@ int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) break; } - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; } if ( saw_xdigit ) { if ( tp - sizeof( uint16_t ) < startp ) - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; *tp-- = (uint8_t) (val >> 8) & 0xff; *tp-- = (uint8_t) val & 0xff; @@ -784,7 +767,7 @@ int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) size_t i; if ( tp == startp ) - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; for ( i = 0; i <= n; i++ ) { @@ -796,7 +779,7 @@ int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) } if ( tp != startp ) - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; if ( p_addr ) *p_addr = tmp; @@ -822,7 +805,7 @@ int str_to_ip6_addr( IP6_ADDR *p_addr, const char *s ) * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, - * specifically ::MBG_ERR_INV_PARM if an invalid number or character was found in the string. + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. * * @see ::snprint_ip4_addr * @see ::snprint_ip4_cidr_addr @@ -858,7 +841,7 @@ int cidr_str_to_ip6_addr_and_net_mask( IP6_ADDR *p_addr, IP6_ADDR *p_mask, const * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, - * specifically ::MBG_ERR_INV_PARM if an invalid number or character was found in the string. + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. * * @see ::snprint_ip6_addr * @see ::snprint_ip6_cidr_addr @@ -878,7 +861,7 @@ int cidr_str_to_ip6_addr_and_cidr_bits( IP6_ADDR *p_addr, int *p_cidr, l = strlen( cidr_str ); if ( l < rc ) // input string too short - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; cp = &cidr_str[rc]; @@ -891,7 +874,7 @@ int cidr_str_to_ip6_addr_and_cidr_bits( IP6_ADDR *p_addr, int *p_cidr, } if ( *cp != '/' ) - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; cp++; cidr_mask_bits = strtol( (char *) cp, (char **) &cp, 10 ); @@ -1166,7 +1149,7 @@ int do_siocg_ioctl( const char *if_name, int ioctl_code, struct ifreq *p_ifreq ) int rc; if ( strlen( if_name ) > ( IFNAMSIZ - 1 ) ) - return MBG_ERR_INV_PARM; + return MBG_ERR_PARM_FMT; sock_fd = socket( AF_INET, SOCK_DGRAM, 0 ); //### TODO: or AF_INET6/PF_INET6 for IPv6 @@ -1933,7 +1916,7 @@ out: if ( link_up ) p->flags |= IP4_MSK_LINK; - + return rc; } // get_port_ip4_settings diff --git a/mbglib/common/lan_util.h b/mbglib/common/lan_util.h index 106a9a9..27d49a3 100755 --- a/mbglib/common/lan_util.h +++ b/mbglib/common/lan_util.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: lan_util.h 1.6.1.7 2016/10/31 17:39:47 martin TEST $ + * $Id: lan_util.h 1.7 2017/07/05 14:10:58 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,23 +10,11 @@ * * ----------------------------------------------------------------------- * $Log: lan_util.h $ - * Revision 1.6.1.7 2016/10/31 17:39:47 martin - * Only return standard MBG_RETURN_CODES. + * Revision 1.7 2017/07/05 14:10:58 martin + * Some definitions used with IPv6 added by hannes. * Removed definitions of old MBG_LU_... return codes. - * Renamed check_octets_not_all_zero() to octets_are_all_zero(), which returns a bool now. - * Renamed check_mac_addr_not_all_zero() to mac_addr_all_zero(), which returns a bool now. - * Removed get_port_mac_addr_check(). - * Updated doxygen comments. - * Revision 1.6.1.6 2015/12/01 11:35:32 martin - * Doxygen fixes. - * Revision 1.6.1.5 2015/11/11 17:58:13 martin - * Revision 1.6.1.4 2015/11/04 17:06:36Z martin - * *** empty log message *** - * Revision 1.6.1.3 2015/08/27 16:23:23 martin - * Revision 1.6.1.2 2015/04/13 15:25:06 hannes - * Added defines for IP6 CIDR mask bits. - * Revision 1.6.1.1 2015/04/02 15:28:03 hannes - * Added most of the ipv4 functions for ipv6. + * Standard MBG_RETURN_CODES are now used instead. + * Updated function prototypes. * Revision 1.6 2014/09/24 08:32:58 martin * Fixed a POSIX header file dependency. * Revision 1.5 2013/10/02 07:20:36 martin @@ -213,8 +201,6 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, -/* function prototypes: */ - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ @@ -280,7 +266,7 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, - * specifically ::MBG_ERR_INV_PARM if an invalid number or character was found in the string. + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. * * @see ::snprint_ip4_addr * @see ::snprint_ip4_cidr_addr @@ -302,7 +288,7 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, - * specifically ::MBG_ERR_INV_PARM if an invalid number or character was found in the string. + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. * * @see ::snprint_ip4_addr * @see ::snprint_ip4_cidr_addr @@ -398,7 +384,7 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, - * specifically ::MBG_ERR_INV_PARM if an invalid number or character was found in the string. + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. * * @see ::snprint_ip6_addr * @see ::snprint_ip6_cidr_addr @@ -423,7 +409,7 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, - * specifically ::MBG_ERR_INV_PARM if an invalid number or character was found in the string. + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. * * @see ::snprint_ip4_addr * @see ::snprint_ip4_cidr_addr @@ -443,7 +429,7 @@ int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, * * @return A number >= 0 (::MBG_SUCCESS) according to the number of characters evaluated * from the input string, or one of the @ref MBG_ERROR_CODES on error, - * specifically ::MBG_ERR_INV_PARM if an invalid number or character was found in the string. + * specifically ::MBG_ERR_PARM_FMT if an invalid number or character was found in the string. * * @see ::snprint_ip6_addr * @see ::snprint_ip6_cidr_addr diff --git a/mbglib/common/macioctl.h b/mbglib/common/macioctl.h index aa4e894..3cb0dff 100755 --- a/mbglib/common/macioctl.h +++ b/mbglib/common/macioctl.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: macioctl.h 1.37.1.9 2017/02/22 15:23:45 martin TEST $ + * $Id: macioctl.h 1.38 2017/07/05 14:20:58 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,20 +11,14 @@ * * ----------------------------------------------------------------------- * $Log: macioctl.h $ - * Revision 1.37.1.9 2017/02/22 15:23:45 martin - * Fixed macro definition syntax to avoid clang compiler warnings. - * Revision 1.37.1.8 2016/09/20 13:34:38 martin - * Typo. - * Revision 1.37.1.7 2016/08/09 15:58:02 martin + * Revision 1.38 2017/07/05 14:20:58 martin + * Support GNSS, GPIO and xmulti_ref stuff. + * Support new way to check if a feature is supported. * Attribute always_inline is now in __mbg_inline. + * Fixed macro definition syntax to avoid clang compiler warnings. + * Account for frac_sec_from_bin() obsoleted by bin_frac_32_to_dec_frac(). + * IOCTL debugging code. * Removed trailing spaces. - * Revision 1.37.1.6 2014/07/16 15:19:55 martin - * Revision 1.37.1.5 2014/06/26 11:15:38 martin - * Revision 1.37.1.4 2014/06/25 08:52:01 martin - * Support GPIO status. - * Revision 1.37.1.3 2014/06/25 08:31:14Z martin - * Revision 1.37.1.2 2014/05/26 16:01:57 martin - * Revision 1.37.1.1 2014/05/22 16:16:18 martin * Revision 1.37 2014/05/19 15:57:25 martin * Fixed grammar in a comment. * Revision 1.36 2013/09/26 07:54:22 martin @@ -385,7 +379,7 @@ typedef struct rc = _pcps_read_var( _pddev, _cmd, iob._fld ); \ _pcps_sem_dec( _pddev ); \ \ - if ( rc != MBG_SUCCESS ) \ + if ( mbg_rc_is_error( rc ) ) \ goto err_access; \ \ _iob_to_pout_var( iob._fld, _pout ); \ @@ -403,7 +397,7 @@ typedef struct rc = _pcps_write_var( _pddev, _cmd, iob._fld ); \ _pcps_sem_dec( _pddev ); \ \ - if ( rc != MBG_SUCCESS ) \ + if ( mbg_rc_is_error( rc ) ) \ goto err_access; \ } @@ -416,7 +410,7 @@ typedef struct rc = _pcps_write_byte( _pddev, _cmd ); \ _pcps_sem_dec( _pddev ); \ \ - if ( rc != MBG_SUCCESS ) \ + if ( mbg_rc_is_error( rc ) ) \ goto err_access; \ } @@ -433,7 +427,7 @@ typedef struct rc = pcps_read_gps( _pddev, _cmd, (uchar FAR *) &iob._fld, _size ); \ _pcps_sem_dec( _pddev ); \ \ - if ( rc != MBG_SUCCESS ) \ + if ( mbg_rc_is_error( rc ) ) \ goto err_access; \ \ _iob_to_pout( &iob._fld, _pout, _size ); \ @@ -452,7 +446,7 @@ typedef struct rc = _pcps_read_gps_var( _pddev, _cmd, iob._fld ); \ _pcps_sem_dec( _pddev ); \ \ - if ( rc != MBG_SUCCESS ) \ + if ( mbg_rc_is_error( rc ) ) \ goto err_access; \ \ _iob_to_pout_var( iob._fld, _pout ); \ @@ -473,7 +467,7 @@ typedef struct rc = _pcps_write_gps_var( _pddev, _cmd, iob._fld ); \ _pcps_sem_dec( _pddev ); \ \ - if ( rc != MBG_SUCCESS ) \ + if ( mbg_rc_is_error( rc ) ) \ goto err_access; \ } @@ -639,6 +633,7 @@ typedef union ALL_XMULTI_REF_INFO_IDX all_xmulti_ref_info_idx; XMULTI_REF_SETTINGS_IDX xmulti_ref_settings_idx; XMR_HOLDOVER_STATUS xmr_holdover_status; + IOCTL_DEV_FEAT_REQ dev_feat_req; PCPS_MAPPED_MEM mapped_mem; @@ -750,7 +745,7 @@ void do_get_fast_hr_timestamp_safe( PCPS_DDEV *pddev, PCPS_TIME_STAMP *p_ts ) #if TEST_MM_ACCESS_TIME delta_frac = (long) ( tmp.frac - p_ts->frac ); - delta_ns = (unsigned) frac_sec_from_bin( delta_frac, 1000000000UL ); + delta_ns = (unsigned) bin_frac_32_to_dec_frac( delta_frac, NSECS_PER_SEC ); printk( KERN_INFO "MM tstamp dev %04X: %li/%li cyc (%lu kHz)" " %08lX.%08lX->%08lX.%08lX: %li (%u.%03u us)" @@ -795,6 +790,7 @@ void do_get_fast_hr_timestamp_cycles_safe( PCPS_DDEV *pddev, PCPS_TIME_STAMP_CYC } // do_get_fast_hr_timestamp_cycles_safe + #if defined( __GNUC__ ) // Avoid "no previous prototype" with some gcc versions. static __mbg_inline @@ -808,24 +804,25 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, /** * @brief Decode and handle IOCTL commands * - * This function is called from the OS dependent IOCTL handlers. + * This function is called from the OS-specific IOCTL handlers, so eventually + * the calling function needs to translate the Meinberg return codes to appropriate + * OS-specific return codes. * - * @param pddev Pointer to the device structure - * @param ioctl_code The IOCTL code to be handled */ + * @param[in] pddev Pointer to the device structure + * @param[in] ioctl_code The IOCTL code to be handled + */ #if defined( MBG_TGT_WIN32 ) /** - * @param pIrp The IRP associated with the IOCTL call - * @param ret_size The number of bytes to be returned - * @param pout_size The size of the output buffer + * @param[in] pIrp The IRP associated with the IOCTL call + * @param[in] ret_size The number of bytes to be returned + * @param[in] pout_size The size of the output buffer */ #endif /** - * @param pin The input buffer - * @param pout The output buffer + * @param[in] pin The input buffer + * @param[in] pout The output buffer * - * @return MBG_SUCCESS or one of the Meinberg error codes which need to be translated - * by the calling function to the OS dependent error code. - * @return -1 for unknown IOCTL codes + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES */ static __mbg_inline int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, @@ -884,7 +881,7 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, iob.pcps_hr_time_cycles.cycles = pddev->acc_cycles; _pcps_sem_dec( pddev ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) goto err_access; _iob_to_pout_var( iob.pcps_hr_time_cycles, pout ); @@ -913,7 +910,7 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, mbg_get_pc_cycles( &iob.pcps_time_cycles.cycles ); _pcps_sem_dec( pddev ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) goto err_access; _iob_to_pout_var( iob.pcps_time_cycles, pout ); @@ -962,7 +959,7 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, iob.mbg_time_info_hrt.ref_hr_time_cycles.cycles = pddev->acc_cycles; _pcps_sem_dec( pddev ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) goto err_access; _iob_to_pout_var( iob.mbg_time_info_hrt, pout ); @@ -1363,6 +1360,15 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, _report_cond( _pcps_ddev_has_xmr( pddev ), pout ); break; + case IOCTL_CHK_DEV_FEAT: + _iob_from_pin_var( iob.dev_feat_req, pin ); + rc = pcps_chk_dev_feat( pddev, iob.dev_feat_req.feat_req_type, iob.dev_feat_req.feat_num ); + #if 0 + _mbgddmsg_4( MBG_DBG_INFO, "%s: chk_dev_feat %i:%i returned %i", + pcps_driver_name, iob.dev_feat_req.feat_req_type, + iob.dev_feat_req.feat_num, rc ); + #endif + break; // The next codes are somewhat special since they change something @@ -1553,7 +1559,7 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, _pcps_kfree( p_buff_out, iob.req.out_sz ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) goto err_access; #else @@ -1578,7 +1584,7 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, _pcps_kfree( p_buff, buffer_size ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) goto err_access; #endif @@ -1608,7 +1614,7 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, _pcps_kfree( p_buff_out, iob.req.out_sz ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) goto err_access; #else @@ -1633,7 +1639,7 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, _pcps_kfree( p_buff, buffer_size ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) goto err_access; #endif @@ -1920,7 +1926,7 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, _pcps_kfree( p_buff_in, iob.req.in_sz ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) goto err_access; #else @@ -1941,7 +1947,7 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, _pcps_kfree( p_buff, buffer_size ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) goto err_access; #endif @@ -1970,7 +1976,7 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, _pcps_kfree( p_buff_in, iob.req.in_sz ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) goto err_access; #else @@ -1991,7 +1997,7 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, _pcps_kfree( p_buff, buffer_size ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) goto err_access; #endif @@ -2059,7 +2065,7 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, if ( p_buff_out ) _pcps_kfree( p_buff_out, iob.req.out_sz ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) goto err_access; #else @@ -2091,7 +2097,7 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, _pcps_kfree( p_buff, buffer_size ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) goto err_access; #endif @@ -2155,28 +2161,39 @@ int ioctl_switch( PCPS_DDEV *pddev, unsigned int ioctl_code, #endif // USE_DEBUG_PORT - default: + default: // Unknown IOCTL code goto err_inval; } + // We get here in case of success. return rc; err_inval: + // We get here if the IOCTL code is inappropriate + // for this target / OS. + // POSIX return code would probably be -ENODEV. return MBG_ERR_INV_DEV_REQUEST; err_support: + // We get here if the IOCTL code is inappropriate + // for this device. + // POSIX return code would be -ENOTTY. return MBG_ERR_NOT_SUPP_BY_DEV; err_no_mem: + // We get here if we were unable to allocate memory. + // POSIX return code would be -ENOMEM. return MBG_ERR_NO_MEM; err_busy_unsafe: return MBG_ERR_IRQ_UNSAFE; err_access: - return rc; // return the rc from the low level routine - + // We get here if device access failed. + // POSIX return code would probably be -EIO. + // Return the rc from the low level routine. + return rc; #if defined( USE_COPY_KERNEL_USER ) diff --git a/mbglib/common/mbg_cof.h b/mbglib/common/mbg_cof.h index 0c0e96f..ced7988 100755 --- a/mbglib/common/mbg_cof.h +++ b/mbglib/common/mbg_cof.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbg_cof.h 1.1.1.3 2016/08/10 14:19:00 martin TEST $ + * $Id: mbg_cof.h 1.2 2017/07/05 14:25:12 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,12 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: mbg_cof.h $ - * Revision 1.1.1.3 2016/08/10 14:19:00 martin - * *** empty log message *** - * Revision 1.1.1.2 2016/08/10 14:15:14 martin - * *** empty log message *** - * Revision 1.1.1.1 2016/08/09 15:59:01 martin - * Preliminary compatibility changes. + * Revision 1.2 2017/07/05 14:25:12 martin + * Reformatted code to conform to standard header file format. + * Changes tfor improved cross-platform compatibility. * Revision 1.1 2015/09/09 10:42:27 martin * Initial revision by philipp. * @@ -65,8 +62,6 @@ extern "C" { #endif -/* function prototypes: */ - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/mbg_daemonize.c b/mbglib/common/mbg_daemonize.c deleted file mode 100755 index 7182138..0000000 --- a/mbglib/common/mbg_daemonize.c +++ /dev/null @@ -1,231 +0,0 @@ - -/************************************************************************** - * - * $Id: mbg_daemonize.c 1.4.1.1 2014/04/15 13:39:36 martin TEST $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * NTP shared memory support functions. - * - * ----------------------------------------------------------------------- - * $Log: mbg_daemonize.c $ - * Revision 1.4.1.1 2014/04/15 13:39:36 martin - * Revision 1.4 2013/07/30 15:30:49 martin - * Revision 1.3 2013/07/30 12:53:49 martin - * Revision 1.2 2013/07/24 15:29:38 martin - * Revision 1.1 2013/07/23 16:10:18 martin - * Initial revision. - * - **************************************************************************/ - -#define _GNU_SOURCE // required for strsignal() in old glibc versions - -#define _MBG_DAEMONIZE - #include <mbg_daemonize.h> -#undef _MBG_DAEMONIZE - -#include <mbg_pidfile.h> - -#include <unistd.h> -#include <stdlib.h> -#include <syslog.h> -#include <errno.h> -#include <string.h> -#include <fcntl.h> -#include <signal.h> -#include <sys/types.h> -#include <sys/stat.h> - - -static /*HDR*/ -void close_files_and_redirect_stdio( void ) -{ - int i; - - #if defined( DEBUG ) - syslog( LOG_DEBUG, "Going to close all file handles, table size: %i, PID fd: %i", - getdtablesize(), glb_pid_fd ); - #endif - - // close all file descriptors, except the PID file descriptor - - for ( i = getdtablesize(); i >= 0; --i ) - { - if ( i != glb_pid_fd ) - { - int rc = close( i ); - - if ( rc < 0 ) - { - #if !defined( DEBUG ) || ( DEBUG < 2 ) - if ( errno != EBADF ) - #endif - syslog( LOG_DEBUG, "Failed to close fd %i: %s", i, strerror( errno ) ); - } - else - { - #if defined( DEBUG ) - syslog( LOG_DEBUG, "fd %i closed successfully", i ); - #endif - } - } - else - { - #if defined( DEBUG ) - syslog( LOG_DEBUG, "Not closing PID fd %i", i ); - #endif - } - } - - // handle standard I/O - - #if defined( DEBUG ) - syslog( LOG_DEBUG, "Going to open /dev/null as stdin, stdout, and stderr" ); - #endif - - if ( ( i = open( "/dev/null", O_RDWR ) ) == -1 ) // stdin - syslog( LOG_ERR, "Failed to open /dev/null as stdin: %s", strerror( errno ) ); - - if ( dup( i ) == -1 ) // stdout - syslog( LOG_ERR, "Failed dup stdin as stdout: %s", strerror( errno ) ); - - if ( dup( i ) == -1 ) // stderr - syslog( LOG_ERR, "Failed dup stdin as stderr: %s", strerror( errno ) ); - -} // close_files_and_redirect_stdio - - - -static /*HDR*/ -void set_running_dir( const char *new_dir ) -{ - // change running dir - int rc = chdir( new_dir ); - - if ( rc == -1 ) - syslog( LOG_WARNING, "Failed to chdir to \"%s\": %s", new_dir, strerror( errno ) ); - else - { - #if defined( DEBUG ) - syslog( LOG_DEBUG, "Successfully called chdir to \"%s\"", new_dir ); - #endif - } - -} // set_running_dir - - - -static /*HDR*/ -void set_signal_handling( void (*new_signal_handler)( int sig ) ) -{ - struct sigaction new_sig_action; - sigset_t new_sig_set; - - // Set signal mask - signals we want to block - sigemptyset( &new_sig_set ); - sigaddset( &new_sig_set, SIGCHLD ); // ignore child - i.e. we don't need to wait for it - sigaddset( &new_sig_set, SIGTSTP ); // ignore TTY stop signals - sigaddset( &new_sig_set, SIGTTOU ); // ignore TTY background writes - sigaddset( &new_sig_set, SIGTTIN ); // ignore TTY background reads - sigprocmask( SIG_BLOCK, &new_sig_set, NULL ); // block the signals specified above - - // Set up a signal handler - new_sig_action.sa_handler = new_signal_handler; - sigemptyset(&new_sig_action.sa_mask); - new_sig_action.sa_flags = 0; - - // Signals to handle - sigaction( SIGHUP, &new_sig_action, NULL ); // catch hangup signal - sigaction( SIGTERM, &new_sig_action, NULL ); // catch term signal - sigaction( SIGINT, &new_sig_action, NULL ); // catch interrupt signal - -} // set_signal_handling - - - -static /*HDR*/ -void signal_handler( int sig ) -{ - switch ( sig ) - { - case SIGHUP: - syslog( LOG_WARNING, "Received SIGHUP signal." ); - break; - - case SIGINT: - case SIGTERM: - syslog( LOG_INFO, "Daemon exiting" ); - exit( EXIT_SUCCESS ); - break; - - default: - syslog( LOG_WARNING, "Unhandled signal %s", strsignal( sig ) ); - break; - - } // switch - -} // signal_handler - - - -/*HDR*/ -void mbg_daemonize( const char *running_dir ) -{ - int i; - - if ( getppid() == 1 ) // already a daemon - { - syslog( LOG_WARNING, "Already daemon with PID %i when mbg_daemonize() was called", getpid() ); - return; - } - - set_signal_handling( signal_handler ); - - i = fork(); - - if ( i < 0 ) // failed to fork - { - syslog( LOG_ERR, "Failed to fork: %s", strerror( errno ) ); - exit( EXIT_FAILURE ); - } - - if ( i > 0 ) // we are the parent - { - #if defined( DEBUG ) - syslog( LOG_DEBUG, "Child process %i created successfully, parent %i exiting now", i, getpid() ); - #endif - exit( EXIT_SUCCESS ); // parent exits now - } - - // we are the child process which continues - - i = setsid(); // get a new process group - - if ( i < 0 ) // failed to fork - { - syslog( LOG_ERR, "Failed to get new session ID: %s", strerror( errno ) ); - exit( EXIT_FAILURE ); - } - - #if defined( DEBUG ) - syslog( LOG_DEBUG, "Got new session ID %i", i ); - #endif - - - close_files_and_redirect_stdio(); - - - // TODO: check if this should be done earlier, right after fork - umask( 027 ); // restrict file permissions to 0750 - - - set_running_dir( running_dir ? running_dir : DEFAULT_RUNNING_DIR ); - - // we are the first instance, so continue - - if ( mbg_pidfile_write_own_pid() < 0 ) - exit( EXIT_FAILURE ); - -} // mbg_daemonize - diff --git a/mbglib/common/mbg_daemonize.h b/mbglib/common/mbg_daemonize.h deleted file mode 100755 index 6387d3c..0000000 --- a/mbglib/common/mbg_daemonize.h +++ /dev/null @@ -1,77 +0,0 @@ - -/************************************************************************** - * - * $Id: mbg_daemonize.h 1.2 2013/07/30 15:30:49 martin REL_M $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for mbg_daemonize.c. - * - * ----------------------------------------------------------------------- - * $Log: mbg_daemonize.h $ - * Revision 1.2 2013/07/30 15:30:49 martin - * Revision 1.1 2013/07/23 16:10:18 martin - * Initial revision. - * - **************************************************************************/ - -#ifndef _MBG_DAEMONIZE_H -#define _MBG_DAEMONIZE_H - - -/* Other headers to be included */ - - - -#ifdef _MBG_DAEMONIZE - #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 - -#define DEFAULT_RUNNING_DIR "/" -#define DEFAULT_PIDFILE_DIR "/var/run/" - - -/* function prototypes: */ - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - void mbg_daemonize( const char *running_dir ) ; - -/* ----- function prototypes end ----- */ - -#ifdef __cplusplus -} -#endif - - -#if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment - #undef _USING_BYTE_ALIGNMENT -#endif - -/* End of header body */ - - -#undef _ext -#undef _DO_INIT - -#endif /* _MBG_DAEMONIZE_H */ diff --git a/mbglib/common/mbg_pidfile.c b/mbglib/common/mbg_pidfile.c deleted file mode 100755 index 8e7a9ba..0000000 --- a/mbglib/common/mbg_pidfile.c +++ /dev/null @@ -1,334 +0,0 @@ - -/************************************************************************** - * - * $Id: mbg_pidfile.c 1.5 2014/07/16 15:19:55 martin REL_M $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Functions to handle a PID file. - * - * ----------------------------------------------------------------------- - * $Log: mbg_pidfile.c $ - * Revision 1.5 2014/07/16 15:19:55 martin - * Revision 1.4 2013/08/01 16:17:01 martin - * Revision 1.3 2013/07/30 15:30:49 martin - * Revision 1.2 2013/07/24 15:29:38 martin - * Revision 1.1 2013/07/23 16:10:18 martin - * Initial revision. - * - **************************************************************************/ - -#define _MBG_PIDFILE - #include <mbg_pidfile.h> -#undef _MBG_PIDFILE - -#include <unistd.h> -#include <stdio.h> -#include <syslog.h> -#include <errno.h> -#include <string.h> -#include <fcntl.h> -#include <sys/file.h> - - -#define USE_ATEXIT_MBG_PIDFILE 0 - - -// PID file handling -// -// If we want to make sure that no other instance of this program -// is running, neither as daemon nor in the foreground only, we want -// to try to open and lock the PID file *before* the program forks. -// On the other hand, if running as daemon we need to write our PID -// to the PID file *after* the fork. -// -// So the best approach is to open and lock the PID file before the -// fork, and write the PID to it after the fork. So we need to make -// sure that the lock is persistant across the fork. -// -// The flopen() call opens and locks a PID file in one step and thus -// avoids a race condition. It is usually implemented using open() -// and flock(), so it is persistant across forks. So this call usually -// meets our requirements, but is not supported on all systems. -// -// If flopen() is not supported then we have to call open() first and -// then some locking function, which can be flock() or lockf(). -// -// flock() *can* be implemented on top of fcntl() but usually isn't. -// lockf() *is* usually implemented on top of fcntl() but may be not. -// fcntl() usually works on NFS mounts, other implementations usually don't. -// fcntl() usually inn't persistant across forks, but flock() is. -// -// PID files are usually not located inside the local file system, -// not on NFS mounts, thus flopen() the first choice, and using -// open() plus flock() is the second best choice. - -#if !defined( HAVE_FLOPEN ) - // flopen() is usually supported on *BSD - #define HAVE_FLOPEN defined( MBG_TGT_BSD ) -#endif - -#if HAVE_FLOPEN - #include <libutil.h> -#else - #define USE_FLOCK 1 -#endif - - -// file descriptor for the PID file -static const char *glb_pid_fn; - -// We don't make this static to be able to change this externally, -// though this is not recommended. -mode_t pid_file_mode = 0640; - - - -/*HDR*/ -/** - * @brief Close and remove a PID file - * - * Should be called immediately before a daemon terminates. - * - * @param[in] info An additional informational string written to the syslog - * - * @see ::mbg_pidfile_open_and_lock - * @see ::mbg_pidfile_write_own_pid - */ -void mbg_pidfile_close_and_remove( const char *info ) -{ - int rc; - - syslog( LOG_INFO, "mbg_pidfile_close_and_remove() called %s", info ); - - if ( glb_pid_fd >= 0 ) - { - rc = close( glb_pid_fd ); - - if ( rc == -1 ) - { - syslog( LOG_WARNING, "Failed to close PID file %s (fd %i): %s", - glb_pid_fn, glb_pid_fd, strerror( errno ) ); - } - else - { - #if defined( DEBUG ) - syslog( LOG_DEBUG, "PID file %s (fd %i) closed", - glb_pid_fn, glb_pid_fd ); - #endif - glb_pid_fd = -1; - } - } - - - if ( glb_pid_fn ) - { - rc = unlink( glb_pid_fn ); - - if ( rc == -1 ) - { - syslog( LOG_WARNING, "Failed to remove PID file %s: %s", - glb_pid_fn, strerror( errno ) ); - } - else - { - #if defined( DEBUG ) - syslog( LOG_DEBUG, "PID file %s removed", glb_pid_fn ); - #endif - - glb_pid_fn = NULL; - } - } - -} // mbg_pidfile_close_and_remove - - - -#if USE_ATEXIT_MBG_PIDFILE - -static /*HDR*/ -void mbg_pidfile_cleanup( void ) -{ - mbg_pidfile_close_and_remove( "from mbg_pidfile_cleanup()" ); - -} // mbg_pidfile_cleanup - -#endif - - - -/*HDR*/ -/** - * @brief Try to open and lock a PID file - * - * @note This function can be called before or after a program forks, - * which is useful if only a single instance of a program may be - * running, either as daemon or in the foreground. - * - * @param pid_fn File name of the PID file, including path - * - * @return The file descriptor of the PID file, or -1 on error - * - * @see ::mbg_pidfile_close_and_remove - * @see ::mbg_pidfile_write_own_pid - */ -int mbg_pidfile_open_and_lock( const char *pid_fn ) -{ - int flags = O_RDWR | O_CREAT; - - #if 1 && defined( O_CLOEXEC ) - flags |= O_CLOEXEC; // TODO: check if this is appropriate - #endif - -#if HAVE_FLOPEN - // This is the preferred method to open and lock a PID file. - // flopen() is usually available on *BSD. It does open() and flock() - // in one step and thus avoids a race condition between opening and locking. - // - // If flags includes O_NONBLOCK and the file is already locked, - // flopen() will fail and set errno to EWOULDBLOCK. - flags |= O_NONBLOCK; - - glb_pid_fd = flopen( pid_fn, flags, pid_file_mode ); - - if ( glb_pid_fd < 0 ) // failed to open PID file - { - syslog( LOG_ERR, "Failed to open PID file %s: %s", pid_fn, strerror( errno ) ); - goto out_err; - } - - #if defined( DEBUG ) - syslog( LOG_DEBUG, "Successfully opened and locked PID file %s (fd %i)", pid_fn, glb_pid_fd ); - #endif - -#else // flopen() not supported - - glb_pid_fd = open( pid_fn, flags, pid_file_mode ); - - if ( glb_pid_fd < 0 ) // failed to open PID file - { - syslog( LOG_ERR, "Failed to open PID file %s: %s", pid_fn, strerror( errno ) ); - goto out_err; - } - - #if defined( DEBUG ) - syslog( LOG_DEBUG, "Successfully opened PID file %s (fd %i)", pid_fn, glb_pid_fd ); - #endif - - #if USE_FLOCK - // This is the preferred method to lock a PID file, if flopen() - // open()+flock() is what flopen() usually does in one step. - // flock() locks are preserved across forks, at least under Linux - // where flock() is *not* implemented on top of fcntl(). - // However, flock() locks usually don't work on NFS mounts - // whereas fcntl() locks do. - flags = LOCK_EX; // get an exclusive lock - flags |= LOCK_NB; // non-blocking, return error if would block - - if ( flock( glb_pid_fd, flags ) < 0 ) // failed to get a lock on PID file - { - syslog( LOG_ERR, "Failed to get an flock() lock on PID file %s (fd %i): %s", - pid_fn, glb_pid_fd, strerror( errno ) ); - goto out_err_close; - } - - #if defined( DEBUG ) - syslog( LOG_DEBUG, "Got an flock() lock on PID file %s (fd %i)", - pid_fn, glb_pid_fd ); - #endif - - #else - // lockf() locks are usually (but not necessarily) implemented on top - // of fcntl(), but are *not* preserved across forks. - // If implemented on top of fnctl() then locking works also on NFS mounts, - // but locks are *not* preserved across forks. - // - // Try to lock the file using F_TLOCK which never blocks but returns - // an error if the file is already locked. - if ( lockf( glb_pid_fd, F_TLOCK, 0 ) < 0 ) // failed to get a lock on PID file - { - syslog( LOG_ERR, "Failed to get a lockf() lock on PID file %s (fd %i): %s", - pid_fn, glb_pid_fd, strerror( errno ) ); - goto out_err_close; - } - - #if defined( DEBUG ) - syslog( LOG_DEBUG, "Got a lockf() lock on PID file %s (fd %i)", - pid_fn, glb_pid_fd ); - #endif - - #endif - -#endif - - // save PID file name - glb_pid_fn = pid_fn; - -#if USE_ATEXIT_MBG_PIDFILE - #if defined( DEBUG ) - syslog( LOG_DEBUG, "Registering exit function %s from %s", "mbg_pidfile_cleanup", __func__ ); - #endif - atexit( mbg_pidfile_cleanup ); -#endif - goto out; - - -out_err_close: - close( glb_pid_fd ); - -out_err: - glb_pid_fd = -1; - -out: - return glb_pid_fd; - -} // mbg_pidfile_open_and_lock - - - -/*HDR*/ -/** - * @brief Write own process ID to our PID file - * - * @note If a program runs as daemon, i.e. forks, then this function - * has to be called <b>after</b> the fork in order to write the - * PID of the forked process to the PID file. - * - * @return The number of byte written to the PID file, or a negative number on error - * - * @see ::mbg_pidfile_close_and_remove - * @see ::mbg_pidfile_open_and_lock - */ -int mbg_pidfile_write_own_pid( void ) -{ - char tmp_str[64]; - - // write single line with PID to PID file - int n = snprintf( tmp_str, sizeof( tmp_str ), "%i\n", getpid() ); - int rc = write( glb_pid_fd, tmp_str, n ); - - if ( rc < 0 ) - syslog( LOG_ERR, "Failed to write to PID file %s (fd %i): %s", - glb_pid_fn, glb_pid_fd, strerror( errno ) ); - else - { - if ( rc != n ) - { - syslog( LOG_WARNING, "Could only write %i of %i chars to PID file %s (fd %i)", - rc, n, glb_pid_fn, glb_pid_fd ); - rc = -1; - } - else - { - #if defined( DEBUG ) - syslog( LOG_DEBUG, "Wrote own PID to PID file %s (fd %i): %i bytes", - glb_pid_fn, glb_pid_fd, n ); - #endif - } - } - - return rc; - -} // mbg_pidfile_write_own_pid - diff --git a/mbglib/common/mbg_pidfile.h b/mbglib/common/mbg_pidfile.h deleted file mode 100755 index f1b5926..0000000 --- a/mbglib/common/mbg_pidfile.h +++ /dev/null @@ -1,124 +0,0 @@ - -/************************************************************************** - * - * $Id: mbg_pidfile.h 1.4 2014/07/16 15:19:55 martin REL_M $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for mbg_daemonize.c. - * - * ----------------------------------------------------------------------- - * $Log: mbg_pidfile.h $ - * Revision 1.4 2014/07/16 15:19:55 martin - * Revision 1.3 2013/07/30 15:30:49 martin - * Revision 1.2 2013/07/24 15:29:38 martin - * Revision 1.1 2013/07/23 16:10:19 martin - * Initial revision. - * - **************************************************************************/ - -#ifndef _MBG_PIDFILE_H -#define _MBG_PIDFILE_H - - -/* Other headers to be included */ - - -#ifdef _MBG_PIDFILE - #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 - -#define DEFAULT_PIDFILE_DIR "/var/run/" - -_ext int glb_pid_fd -#if defined( _DO_INIT ) - = -1 -#endif -; - - -/* function prototypes: */ - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - /** - * @brief Close and remove a PID file - * - * Should be called immediately before a daemon terminates. - * - * @param[in] info An additional informational string written to the syslog - * - * @see ::mbg_pidfile_open_and_lock - * @see ::mbg_pidfile_write_own_pid - */ - void mbg_pidfile_close_and_remove( const char *info ) ; - - /** - * @brief Try to open and lock a PID file - * - * @note This function can be called before or after a program forks, - * which is useful if only a single instance of a program may be - * running, either as daemon or in the foreground. - * - * @param pid_fn File name of the PID file, including path - * - * @return The file descriptor of the PID file, or -1 on error - * - * @see ::mbg_pidfile_close_and_remove - * @see ::mbg_pidfile_write_own_pid - */ - int mbg_pidfile_open_and_lock( const char *pid_fn ) ; - - /** - * @brief Write own process ID to our PID file - * - * @note If a program runs as daemon, i.e. forks, then this function - * has to be called <b>after</b> the fork in order to write the - * PID of the forked process to the PID file. - * - * @return The number of byte written to the PID file, or a negative number on error - * - * @see ::mbg_pidfile_close_and_remove - * @see ::mbg_pidfile_open_and_lock - */ - int mbg_pidfile_write_own_pid( void ) ; - - -/* ----- function prototypes end ----- */ - -#ifdef __cplusplus -} -#endif - - -#if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment - #undef _USING_BYTE_ALIGNMENT -#endif - -/* End of header body */ - - -#undef _ext -#undef _DO_INIT - -#endif /* _MBG_PIDFILE_H */ diff --git a/mbglib/common/mbg_tgt.h b/mbglib/common/mbg_tgt.h index 93916d6..2a63b1a 100755 --- a/mbglib/common/mbg_tgt.h +++ b/mbglib/common/mbg_tgt.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbg_tgt.h 1.35.1.12 2017/04/19 15:03:38 martin TEST $ + * $Id: mbg_tgt.h 1.36 2017/07/04 12:35:11 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,32 +11,18 @@ * * ----------------------------------------------------------------------- * $Log: mbg_tgt.h $ - * Revision 1.35.1.12 2017/04/19 15:03:38 martin - * Evaluate preprocessor symbol KERNEL_HAS_BOOL to avoid - * a compiler error due to duplicate definition in specific Linux kernels - * patched by the distro maintainers. - * Revision 1.35.1.11 2017/04/12 07:50:31 martin - * Fixed missing struct timespec for DOS. - * Revision 1.35.1.10 2017/04/10 13:37:16Z martin - * Fixed some compiler warnings. - * Revision 1.35.1.9 2017/02/09 12:38:51Z martin - * Fixed missing brace. - * Revision 1.35.1.8 2017/02/09 12:31:17 martin - * Updated bool handling with Linux kernel. - * Revision 1.35.1.7 2017/02/09 10:41:24 martin - * Fixed missing 'bool' type for old Linux kernels. - * Revision 1.35.1.6 2016/09/27 15:33:30 martin - * Added definition for _NO_MBG_API. - * Revision 1.35.1.5 2016/09/26 16:17:36 martin - * Fixed definitions for Windows kernel mode build. - * Revision 1.35.1.4 2016/08/31 08:17:51Z thomas-b - * Do not typedef ssize_t if HAVE_SSIZE_T is defined already - * Revision 1.35.1.3 2016/08/11 08:27:17 martin + * Revision 1.36 2017/07/04 12:35:11 martin * Fixed build for Windows kernel space. - * Revision 1.35.1.2 2016/08/10 12:26:49Z martin - * *** empty log message *** - * Revision 1.35.1.1 2016/08/09 15:59:25 martin - * *** empty log message *** + * Don't define ssize_t if HAVE_SSIZE_T is already defined. + * Added definition for _NO_MBG_API. + * Fixed missing 'bool' type for old Linux kernels. + * Fixed missing 'struct timespec' for DOS. + * Evaluate preprocessor symbol KERNEL_HAS_BOOL to avoid + * compiler errors due to duplicate definitions in specific + * Linux kernels patched by the distro maintainers. + * Provide ssize_t for C++Builder 5. + * Improved Visual Studio version checking. + * New define MBG_TGT_HAS_NODE_NAME. * Revision 1.35 2016/08/05 12:21:34 martin * Conditionally define a macro _DEPRECATED_BY which can be used to * tag functions as deprecated, so compilers can emit appropriate warnings. @@ -215,6 +201,11 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + + #if defined( _CVI_ ) #define MBG_TGT_CVI @@ -452,6 +443,8 @@ #endif + #define MBG_TGT_HAS_DEV_FN 1 + #elif defined( MBG_TGT_BSD ) #if defined( MBG_TGT_KERNEL ) @@ -462,6 +455,8 @@ #include <stdbool.h> #endif + #define MBG_TGT_HAS_DEV_FN 1 + #elif defined( MBG_TGT_QNX_NTO ) // QNX 6.x (Neutrino) #include <unistd.h> @@ -502,6 +497,7 @@ #elif defined( _MSC_VER ) // Known predifined MS compiler version codes: + // 1910: MSVC++ 15.0 (Visual Studio 2017) // 1900: MSVC++ 14.0 (Visual Studio 2015) // 1800: MSVC++ 12.0 (Visual Studio 2013) // 1700: MSVC++ 11.0 (Visual Studio 2012) @@ -513,6 +509,35 @@ // 1200: MSVC++ 6.0 // 1100: MSVC++ 5.0 + // Enable this to get compile-time messages on the compiler version + #if 0 + #if ( _MSC_VER >= 1910 ) + #error >= 1910: MSVC++ 15.0 (Visual Studio 2017), or later + #elif ( _MSC_VER >= 1900 ) + #error 1900: MSVC++ 14.0 (Visual Studio 2015) + #elif ( _MSC_VER >= 1800 ) + #error 1800: MSVC++ 12.0 (Visual Studio 2013) + #elif ( _MSC_VER >= 1700 ) + #error 1700: MSVC++ 11.0 (Visual Studio 2012) + #elif ( _MSC_VER >= 1600 ) + #error 1600: MSVC++ 10.0 (Visual Studio 2010) + #elif ( _MSC_VER >= 1500 ) + #error 1500: MSVC++ 9.0 (Visual Studio 2008) + #elif ( _MSC_VER >= 1400 ) + #error STRINGIFY( _MSC_VER ) MSVC++ 8.0 (Visual Studio 2005, Windows Server 2003 SP1 DDK - AMD64) + #elif ( _MSC_VER >= 1310 ) + #error 1310: MSVC++ 7.1 (Visual Studio .NET 2003, Windows Server 2003 DDK) + #elif ( _MSC_VER >= 1300 ) + #error 1300: MSVC++ 7.0 (Visual Studio .NET 2002, Windows XP SP1 DDK) + #elif ( _MSC_VER >= 1200 ) + #error 1200: MSVC++ 6.0 + #elif ( _MSC_VER >= 1100 ) + #error 1100: MSVC++ 5.0 + #else + #error <1100: Older than MSVC 4 + #endif + #endif + // "struct timespec" is supported only since VS2015 // If it is then also the symbol TIME_UTC should be defined. // Functions to read the current time as struct timespec @@ -556,9 +581,13 @@ #define __func__ "func_???" #endif - // "deprecated" attribute - #if ( _MSC_VER >= 1400 ) - // This is supported since Visual Studio 2005 + // The "deprecated" attribute should be supported since Visual Studio 2005, + // but doesn't seem to be supported by the compiler shipped with the + // "Windows Server 2003 SP1 DDK", which is used to build kernel drivers + // and defines the same _MSC_VER number as VS2005. For now we assume + // that this is supported by compilers shipped with newer SDKs. + #if ( ( _MSC_VER >= 1500 ) || \ + ( ( _MSC_VER >= 1400 ) && !defined( _KDD_ ) ) ) #define _DEPRECATED_BY( _s ) __declspec(deprecated("deprecated, use \"" _s "\"")) #endif @@ -585,7 +614,7 @@ #define HAVE_SSIZE_T 1 - #endif + #endif // !defined ( HAVE_SSIZE_T ) #elif defined( _CVI_ ) @@ -677,6 +706,11 @@ #define __mbg_inline // up to BC3.1 not supported for C #endif + #if !defined ( HAVE_SSIZE_T ) + typedef int ssize_t; // required at least for C++ Builder 5 + #define HAVE_SSIZE_T 1 + #endif + #elif defined( __WATCOMC__ ) // 1050 v10.5 @@ -884,6 +918,10 @@ #define MBG_USE_MM_IO_FOR_PCI 0 #endif +#if !defined( MBG_TGT_HAS_DEV_FN ) + #define MBG_TGT_HAS_DEV_FN 0 +#endif + #if defined( MBG_TGT_MISSING_STRUCT_TIMESPEC ) #include <time.h> @@ -930,17 +968,6 @@ -/* End of header body */ - -#undef _ext - - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ @@ -954,5 +981,8 @@ extern "C" { } #endif +/* End of header body */ + +#undef _ext #endif /* _MBG_TGT_H */ diff --git a/mbglib/common/mbgddmsg.h b/mbglib/common/mbgddmsg.h index ecf9fba..4517d7b 100755 --- a/mbglib/common/mbgddmsg.h +++ b/mbglib/common/mbgddmsg.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgddmsg.h 1.10.1.6 2015/08/27 16:22:17 martin TEST $ + * $Id: mbgddmsg.h 1.11 2017/07/05 14:31:23 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -13,12 +13,10 @@ * * ----------------------------------------------------------------------- * $Log: mbgddmsg.h $ - * Revision 1.10.1.6 2015/08/27 16:22:17 martin - * Revision 1.10.1.5 2014/05/27 11:43:23 martin - * Revision 1.10.1.4 2014/04/15 13:45:24Z martin - * Revision 1.10.1.3 2014/04/11 12:38:39 martin - * Revision 1.10.1.2 2014/04/09 15:41:47 martin - * Revision 1.10.1.1 2014/04/09 15:10:35Z martin + * Revision 1.11 2017/07/05 14:31:23 martin + * Added _mbg_kdd_msg...() macros. + * Code cleanup. + * Updated function prototypes. * Revision 1.10 2012/10/02 18:33:21Z martin * Support for *BSD. * Also enable debug msgs if MBG_DEBUG is defined. @@ -249,8 +247,6 @@ do { #endif -/* function prototypes: */ - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/mbgdevio.c b/mbglib/common/mbgdevio.c index a379157..a789add 100755 --- a/mbglib/common/mbgdevio.c +++ b/mbglib/common/mbgdevio.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgdevio.c 1.38.1.45.1.12 2017/05/05 10:39:28 martin TEST $ + * $Id: mbgdevio.c 1.39 2017/07/05 15:02:47 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,94 +10,27 @@ * * ----------------------------------------------------------------------- * $Log: mbgdevio.c $ - * Revision 1.38.1.45.1.12 2017/05/05 10:39:28 martin - * Fixed build for big endian targets. - * Revision 1.38.1.45.1.11 2017/03/20 17:11:07 martin - * Replaced dummy swab...() macro calls by real macros. - * Revision 1.38.1.45.1.10 2017/02/22 14:29:17 martin - * Fixed a warning from clang compiler. - * Revision 1.38.1.45.1.9 2017/02/17 11:48:47 martin - * Fixed a potential buffer overflow. - * Revision 1.38.1.45.1.8 2017/02/01 16:23:00 martin - * PCPS_DEV * parameter for mbg_setup_receiver_info maynow be NULL. - * Revision 1.38.1.45.1.7 2016/09/19 14:29:00 martin - * Fixed build for direct access targets. - * Revision 1.38.1.45.1.6 2016/09/16 09:56:47 martin - * *** empty log message *** - * Revision 1.38.1.45.1.5 2016/09/16 07:19:58 martin - * Revision 1.38.1.45.1.4 2016/09/13 11:10:17Z martin - * Modified some macros to avoid compiler warnings. - * Renamed some macros. - * Revision 1.38.1.45.1.3 2016/08/09 16:00:15Z martin - * Fixed build for QNX Neutrino. - * Revision 1.38.1.45.1.2 2016/05/30 15:07:22 martin - * *** empty log message *** - * Revision 1.38.1.45.1.1 2015/12/17 14:18:32 martin - * Tmp. saved preliminary changes. - * Revision 1.38.1.45 2015/12/02 17:05:00 martin - * *** empty log message *** - * Revision 1.38.1.44 2015/12/02 16:36:16 martin - * *** empty log message *** - * Revision 1.38.1.43 2015/12/01 17:01:01 martin - * *** empty log message *** - * Revision 1.38.1.42 2015/12/01 15:24:33 martin - * Marked some functions deprecated. - * Revision 1.38.1.41 2015/12/01 13:58:31 martin - * *** empty log message *** - * Revision 1.38.1.40 2015/10/27 16:22:22 martin + * Revision 1.39 2017/07/05 15:02:47 martin + * Lots of new API functions provided by thomas-b, philipp, and martin. + * Fixed a potential buffer overflow in mbg_open_device_by_name(). + * Fixed a bug where XYZ and LLA were not written properly + * under target systems not using a kernel driver. + * Proper return codes from thread functions. + * PCPS_DEV * parameter for mbg_setup_receiver_info may now be NULL. + * New set of functions to determine if a specific feature is supported. + * The functions are named mbg_chk_dev_...(), are combined in a group + * mbgdevio_chk_supp_fncs, and replace and deprecate a set of older + * functions named mbg_chk_dev_(), which are collected in a group + * mbgdevio_chk_supp_fncs_deprecated. The new functions are much easier + * to be handled, and return a single, distinct return code which clearly + * tells if a feature is not supported, or an error occurred while trying + * to find this out. * Older defines N_SUPP_DEV, PCPS_MAX_DDEVS, and MBG_MAX_DEVICES * have been obsoleted by new defines N_SUPP_DEV_BUS, N_SUPP_DEV_EXT, * and N_SUPP_DEV_TOTAL. - * Revision 1.38.1.39 2015/10/26 14:45:06 martin - * *** empty log message *** - * Revision 1.38.1.38 2015/10/21 11:21:51 martin - * *** empty log message *** - * Revision 1.38.1.37 2015/10/20 16:02:01 martin - * *** empty log message *** - * Revision 1.38.1.36 2015/10/20 15:19:25 martin - * *** empty log message *** - * Revision 1.38.1.35 2015/10/19 16:42:16 martin - * *** empty log message *** - * Revision 1.38.1.34 2015/10/05 15:07:19 marvin - * Unicode support. - * Revision 1.38.1.33 2015/08/31 10:20:28Z martin - * Revision 1.38.1.32 2015/04/07 15:41:21Z martin - * Revision 1.38.1.31 2014/11/19 16:33:30 martin - * Revision 1.38.1.30 2014/11/19 16:15:43 martin - * Revision 1.38.1.29 2014/11/19 16:03:07 martin - * Revision 1.38.1.28 2014/11/19 14:41:45 martin - * Revision 1.38.1.27 2014/11/19 12:33:36 martin - * Cleaned up doxygen comments for mbg_dev_has...() functions. - * Revision 1.38.1.26 2014/10/27 10:44:02 martin - * Revision 1.38.1.25 2014/10/23 11:04:29 martin - * Doxygen stuff. - * Revision 1.38.1.24 2014/07/22 13:03:58 martin - * Revision 1.38.1.23 2014/07/18 11:01:39Z martin - * Revision 1.38.1.22 2014/07/16 15:19:56 martin - * Revision 1.38.1.21 2014/07/14 15:42:47 martin - * Revision 1.38.1.20 2014/07/02 15:34:55 martin - * Revision 1.38.1.19 2014/06/26 09:45:23 martin - * Revision 1.38.1.18 2014/05/27 11:34:29 martin - * Revision 1.38.1.17 2014/05/27 08:22:17 martin - * Revision 1.38.1.16 2014/05/26 16:02:12 martin - * Revision 1.38.1.15 2014/05/26 07:42:30 martin - * Revision 1.38.1.14 2014/05/23 12:30:50Z martin - * Revision 1.38.1.13 2014/05/23 09:53:03 martin - * Revision 1.38.1.12 2014/05/23 09:49:44 martin - * Revision 1.38.1.11 2014/05/23 09:24:06Z martin - * gpio and xmr functions. - * Revision 1.38.1.10 2014/05/22 16:16:26 martin - * Revision 1.38.1.9 2014/04/28 13:54:17 martin - * Revision 1.38.1.8 2014/04/23 15:42:57 martin - * Revision 1.38.1.7 2014/04/22 13:27:37 martin - * Revision 1.38.1.6 2014/04/17 13:16:46 martin - * Fixed a bug where XYZ and LLA were not written properly - * under target systems not using a kernel driver. - * Revision 1.38.1.4 2014/03/28 09:52:10Z martin - * Revision 1.38.1.3 2014/03/13 09:46:44 martin - * Revision 1.38.1.2 2014/01/31 14:45:34Z martin - * Revision 1.38.1.1 2013/12/05 16:35:59 martin - * Doxygen changes. + * Defined many macros in a safer way, and replaced some macros + * by inline functions. + * Improved doxygen comments. * Revision 1.38 2013/11/08 15:04:54 martin * Fixes for big endian targets. * Revision 1.37 2013/09/26 08:54:22 martin @@ -354,6 +287,7 @@ #include <mbgdevio.h> #undef _MBGDEVIO +#include <mbgutil.h> #include <gpsutils.h> #include <mbgerror.h> #include <cfg_hlp.h> @@ -371,7 +305,6 @@ #include <pcpsdrvr.h> #include <pci_asic.h> - #include <stdio.h> static PCPS_DRVR_INFO drvr_info = { MBGDEVIO_VERSION, 0, "MBGDEVIO direct" }; @@ -500,9 +433,9 @@ do \ #if defined( _MBGIOCTL_H ) #define _mbgdevio_old_query_cond( _dh, _cond, _ioctl, _p ) \ - _mbgdevio_vars(); \ + MBGDEVIO_RET_VAL rc; \ rc = _mbgdevio_read_var( _dh, -1, _ioctl, _p ); \ - return _mbgdevio_ret_val + return _mbgdevio_cnv_ret_val( rc ) #define _mbgdevio_old_query_ri_cond _mbgdevio_old_query_cond @@ -522,10 +455,105 @@ do \ #if defined( _MBGIOCTL_H ) - #define _mbgdevio_new_query_cond( _dh, _cond, _ioctl ) \ +static +int do_ioctl_chk_dev_feat( MBG_DEV_HANDLE dh, uint32_t feat_req_type, uint32_t feat_num ) +{ + MBGDEVIO_RET_VAL rc; + IOCTL_DEV_FEAT_REQ req; + req.feat_req_type = feat_req_type; + req.feat_num = feat_num; + rc = _do_mbg_ioctl( dh, IOCTL_CHK_DEV_FEAT, + &req, sizeof( req ), 0 ); + return _mbgdevio_cnv_ret_val( rc ); + +} // do_ioctl_chk_dev_feat + +#endif // defined( _MBGIOCTL_H ) + + + +static __mbg_inline +/** + * @brief Generic function to determine if a specific feature is supported + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] feat_type One of the defined ::DEV_FEAT_REQ_TYPES. + * @param[in] feat_num A feature number with range and meaning depending on the value of feat_type. + * + * @return ::MBG_SUCCESS if the requested feature is supported, see @ref mbgdevio_chk_supp_fncs + * + * @ingroup mbgdevio_chk_supp_fncs + * @see @ref mbgdevio_chk_supp_fncs + * @see ::mbgdevio_chk_dev_feat_deprecated (which is deprecated) + */ +int mbgdevio_chk_dev_feat( MBG_DEV_HANDLE dh, uint32_t feat_type, uint32_t feat_num ) +{ + #if defined( _MBGIOCTL_H ) + + // Use an IOCTL call to retrieve the information + // from the kernel driver. + return do_ioctl_chk_dev_feat( dh, feat_type, feat_num ); + #else + // This target doesn't use a kernel driver, so we retrieve + // the information directly from the device info structure. + return pcps_chk_dev_feat( dh, feat_type, feat_num ); + #endif + +} // mbgdevio_chk_dev_feat + + + +static __mbg_inline +/** + * @brief Deprecated generic function to determine if a specific feature is supported + * + * @deprecated This function is deprecated, use ::mbgdevio_chk_dev_feat preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] feat_type One of the defined ::DEV_FEAT_REQ_TYPES. + * @param[in] feat_num A feature number with range and meaning depending on the value of feat_type. + * @param[out] p Pointer to an int which is updated if the API call succeeds, i.e ::MBG_SUCCESS is returned + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS if feature request could be executed without error + * and *p was updated accordingly, see @ref mbgdevio_chk_supp_fncs_deprecated + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see @ref mbgdevio_chk_supp_fncs_deprecated + * @see ::mbgdevio_chk_dev_feat which should be used preferably + */ +int mbgdevio_chk_dev_feat_deprecated( MBG_DEV_HANDLE dh, uint32_t feat_type, uint32_t feat_num, int *p ) +{ + // Emulate the behavior of old feature-check functions. + int rc = mbgdevio_chk_dev_feat( dh, feat_type, feat_num ); + + // If we could definitely determine if the requested feature + // is supported or not then we accordingly update the integer + // variable the address of which has been passed by the caller, + // and return MBG_SUCCESS since we could determine the information + // successfully. + if ( mbg_rc_is_success( rc ) || ( rc == MBG_ERR_NOT_SUPP_BY_DEV ) ) + { + *p = mbg_rc_is_success( rc ); + return MBG_SUCCESS; + } + + // If we get here then there was some error when we tried to + // determine the requested information, e.g. an IOCTL error + // when accessing the kernel driver, so we return the associated + // error code. + return rc; + +} // mbgdevio_chk_dev_feat_deprecated + + + +#if defined( _MBGIOCTL_H ) + + #define _mbgdevio_new_query_condx( _dh, _cond, _ioctl ) \ { \ + MBGDEVIO_RET_VAL rc; \ int _flag = 0; \ - _mbgdevio_vars(); \ rc = _mbgdevio_read_var( _dh, -1, _ioctl, &_flag ); \ \ if ( rc == MBG_SUCCESS ) /* no IOCTL error */ \ @@ -533,33 +561,18 @@ do \ rc = MBG_ERR_NOT_SUPP_BY_DEV; /* not supp. */ \ \ /* success or IOCTL error */ \ - return _mbgdevio_ret_val; \ + return _mbgdevio_cnv_ret_val( rc ); \ } - #define _mbgdevio_new_query_ri_cond _mbgdevio_new_query_cond - #else - #define _mbgdevio_new_query_cond( _dh, _cond, _ioctl ) \ + #define _mbgdevio_new_query_condx( _dh, _cond, _ioctl ) \ return _cond( _dh ) ? MBG_SUCCESS : MBG_ERR_NOT_SUPP_BY_DEV - #define _mbgdevio_new_query_ri_cond( _dh, _cond, _ioctl ) \ - return _cond( _ri_addr( _dh ) ) ? MBG_SUCCESS : MBG_ERR_NOT_SUPP_BY_DEV - #endif - - -#define MAX_INFO_LEN 260 - -typedef struct -{ - MBG_HW_NAME hw_name; - char model_name[PCPS_CLOCK_NAME_SZ]; - PCPS_SN_STR serial_number; - char hardware_id[MAX_INFO_LEN]; ///< OS dependent hardware ID string to identify a unique device - -} MBG_DEVICE_INFO; +// ### FIXME +#define _mbgdevio_new_query_cond _mbgdevio_new_query_condx @@ -577,7 +590,7 @@ static MBG_PC_CYCLES_FREQUENCY pc_cycles_frequency; * been used to build the library, and thus the API function are called * in the correct way. * - * @return the version number + * @return The version number * * @see ::mbgdevio_check_version * @see ::MBGDEVIO_VERSION defined in mbgdevio.h @@ -603,7 +616,7 @@ _MBG_API_ATTR int _MBG_API mbgdevio_get_version( void ) * @param[in] header_version Version number to be checked, should be ::MBGDEVIO_VERSION * from the mbgdevio.h file version used to build the application * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE * * @see ::mbgdevio_get_version * @see ::MBGDEVIO_VERSION defined in mbgdevio.h @@ -625,7 +638,7 @@ _MBG_API_ATTR int _MBG_API mbgdevio_check_version( int header_version ) * * Very old devices may not provide a ::RECEIVER_INFO structure. * The ::mbg_setup_receiver_info call should be used preferably to set up - * a ::RECEIVER_INFO for a device. The function uses this call to determine + * a ::RECEIVER_INFO for a device. That function uses this call to determine * whether a ::RECEIVER_INFO can be read directly from a device, or sets up * a default structure using default values depending on the device type. * @@ -635,14 +648,15 @@ _MBG_API_ATTR int _MBG_API mbgdevio_check_version( int header_version ) * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_setup_receiver_info * @see ::mbg_get_gps_receiver_info */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_receiver_info( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_has_receiver_info, IOCTL_DEV_HAS_RECEIVER_INFO ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_PCPS, PCPS_BIT_HAS_RECEIVER_INFO ); } // mbg_chk_dev_has_receiver_info @@ -656,7 +670,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_receiver_info; * * Such structures have been introduced with the first Meinberg GPS receivers. * Mostly all configuration structures are large data structures, and mostly all - * current devices support this, but some very old devices may not. + * current devices support this, but some old devices may not. * * @note This function should be preferred over ::mbg_dev_has_gps_data, * which has been deprecated. @@ -664,11 +678,13 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_receiver_info; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_gps_data( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_has_gps_data, IOCTL_DEV_HAS_GPS_DATA ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_PCPS, PCPS_BIT_HAS_GPS_DATA_16 ); } // mbg_chk_dev_has_gps_data @@ -688,13 +704,14 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_gps_data; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_generic_io */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_generic_io( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_has_generic_io, IOCTL_DEV_HAS_GENERIC_IO ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_PCPS, PCPS_BIT_HAS_GENERIC_IO ); } // mbg_chk_dev_has_generic_io @@ -706,8 +723,8 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_generic_io; /** * @brief Check if a device supports the ::mbg_get_asic_version API call. * - * It depends on the bus interface chip assembled on the device - * if ::mbg_get_asic_version is supported, or not. + * If ::mbg_get_asic_version is supported, or not, depends on + * the bus interface chip assembled on the device. * * @note This function should be preferred over ::mbg_dev_has_asic_version, * which has been deprecated. @@ -715,13 +732,15 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_generic_io; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_asic_version */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_asic_version( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_has_asic_version, IOCTL_DEV_HAS_PCI_ASIC_VERSION ); + // TODO return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_PCPS, ... ); + _mbgdevio_new_query_condx( dh, _pcps_ddev_has_asic_version, IOCTL_DEV_HAS_PCI_ASIC_VERSION ); } // mbg_chk_dev_has_asic_version @@ -733,8 +752,8 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_asic_version; /** * @brief Check if a device supports the ::mbg_get_asic_features call. * - * It depends on the bus interface chip assembled on the device - * if ::mbg_get_asic_features is supported, or not. + * If ::mbg_get_asic_features is supported, or not, depends on + * the bus interface chip assembled on the device. * * @note This function should be preferred over ::mbg_dev_has_asic_features, * which has been deprecated. @@ -742,13 +761,15 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_asic_version; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_asic_features */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_asic_features( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_has_asic_features, IOCTL_DEV_HAS_PCI_ASIC_FEATURES ); + // TODO return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_PCPS, ... ); + _mbgdevio_new_query_condx( dh, _pcps_ddev_has_asic_features, IOCTL_DEV_HAS_PCI_ASIC_FEATURES ); } // mbg_chk_dev_has_asic_features @@ -756,9 +777,6 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_asic_features; - - - /*HDR*/ /** * @brief Check if a device provides eXtended Multi Ref (XMR) inputs. @@ -772,27 +790,39 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_asic_features; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_xmr_instances * @see ::mbg_get_gps_all_xmr_status * @see ::mbg_get_gps_all_xmr_info * @see ::mbg_set_gps_xmr_settings_idx * @see ::mbg_get_xmr_holdover_status */ -_MBG_API_ATTR int _MBG_API mbg_chk_dev_supp_xmr( MBG_DEV_HANDLE dh ) +_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_xmr( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_ri_cond( dh, _pcps_has_ri_xmr, IOCTL_DEV_HAS_XMR ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_RI, GPS_HAS_XMULTI_REF ); -} // mbg_chk_dev_supp_xmr +} // mbg_chk_dev_has_xmr -MBG_CHK_SUPP_FNC mbg_chk_dev_supp_xmr; +MBG_CHK_SUPP_FNC mbg_chk_dev_has_xmr; static /*HDR*/ /** - * @brief ::TODO + * @brief Check if device is a specific bus type + * + * This function checks if the bus flags associated with + * the device match the requested flags. This can be used e.g. + * to distinguish if a device is a PCI or USB device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] bus_flag_mask The bus flags to be tested, see @ref PCPS_BUS_FLAG_MASKS + * + * @return ::MBG_SUCCESS if the bus flags match, else ::MBG_ERR_NOT_SUPP_BY_DEV + * + * @see @ref PCPS_BUS_FLAG_MASKS */ int chk_bus_flags( MBG_DEV_HANDLE dh, int bus_flag_mask ) { @@ -811,14 +841,14 @@ int chk_bus_flags( MBG_DEV_HANDLE dh, int bus_flag_mask ) /*HDR*/ /** - * @brief Check if the device is connected to the ISA bus. - * - * @note This function should be used instead of checking the bus_flags manually + * @brief Check if the device is connected via the ISA bus * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @return ::MBG_SUCCESS if the device is connected to ISA, ::MBG_ERR_NOT_SUPP_BY_DEV otherwise + * @return ::MBG_SUCCESS if the device is connected via the ISA bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_isa( MBG_DEV_HANDLE dh ) { @@ -832,14 +862,14 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_isa; /*HDR*/ /** - * @brief Check if the device is connected to the MCA bus. - * - * @note This function should be used instead of checking the bus_flags manually + * @brief Check if the device is connected via the MCA bus * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @return ::MBG_SUCCESS if the device is connected to MCA, ::MBG_ERR_NOT_SUPP_BY_DEV otherwise + * @return ::MBG_SUCCESS if the device is connected via the MCA bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_mca( MBG_DEV_HANDLE dh ) { @@ -853,15 +883,14 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_mca; /*HDR*/ /** - * @brief Check if the device is connected to the PCI bus and if one of the PCI interface chips is used - * - * @note This function should be used instead of checking the bus_flags manually + * @brief Check if the device is connected via the PCI bus * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @return ::MBG_SUCCESS if the device is connected to PCI and one of the PCI interface chips is used, - * ::MBG_ERR_NOT_SUPP_BY_DEV otherwise + * @return ::MBG_SUCCESS if the device is connected via the PCI bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_pci( MBG_DEV_HANDLE dh ) { @@ -874,15 +903,14 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_pci; /*HDR*/ /** - * @brief Check if the device is connected to the PCI Express bus and if one of the PCI Express interface chips is used - * - * @note This function should be used instead of checking the bus_flags manually + * @brief Check if the device is connected via the PCI Express bus * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @return ::MBG_SUCCESS if the device is connected to PCI Express and one of the PCI Express interface chips is used, - * ::MBG_ERR_NOT_SUPP_BY_DEV otherwise + * @return ::MBG_SUCCESS if the device is connected via the PCI Express bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_pci_express( MBG_DEV_HANDLE dh ) { @@ -893,6 +921,7 @@ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_pci_express( MBG_DEV_HANDLE dh ) if ( mbg_rc_is_error( rc ) ) return rc; + // TODO Move this to the kernel driver if ( ( dev_info.type.bus_flags == PCPS_BUS_PCI_MBGPEX ) || ( dev_info.type.bus_flags == PCPS_BUS_PCI_PEX8311 ) ) return MBG_SUCCESS; @@ -907,14 +936,14 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_pci_express; /*HDR*/ /** - * @brief Check if the device is connected to the USB bus - * - * @note This function should be used instead of checking the bus_flags manually + * @brief Check if the device is connected via the USB bus * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @return ::MBG_SUCCESS if the device is connected to USB, ::MBG_ERR_NOT_SUPP_BY_DEV otherwise + * @return ::MBG_SUCCESS if the device is connected via the USB bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_usb( MBG_DEV_HANDLE dh ) { @@ -928,10 +957,10 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_usb; /*HDR*/ /** - * @brief Check if a device supports GNSS configuration. + * @brief Check if a device supports GNSS configuration * * This is usually the case if a device supports reception of - * several different satellite systems, e.g. GPS, Glonass, etc. + * different satellite systems, e.g. GPS, Glonass, Galileo, etc. * * @note This function should be preferred over ::mbg_dev_is_gnss, * which has been deprecated. @@ -939,15 +968,16 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_usb; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_gps_gnss_mode_info * @see ::mbg_set_gps_gnss_mode_settings * @see ::mbg_get_gps_all_gnss_sat_info */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_gnss( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_is_gnss, IOCTL_DEV_IS_GNSS ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_PCPS, PCPS_BIT_IS_GNSS ); } // mbg_chk_dev_is_gnss @@ -957,7 +987,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_gnss; /*HDR*/ /** - * @brief Check if a device is a GPS receiver. + * @brief Check if a device is a GPS receiver * * The function also returns ::MBG_SUCCESS for GNSS receivers * which can track GPS satellites beside other GNSS systems. @@ -968,11 +998,13 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_gnss; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_gps( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_is_gps, IOCTL_DEV_IS_GPS ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_REF_TYPE, PCPS_REF_GPS ); } // mbg_chk_dev_is_gps @@ -994,14 +1026,15 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_gps; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_pzf * @see ::mbg_chk_dev_is_lwr */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_dcf( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_is_dcf, IOCTL_DEV_IS_DCF ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_REF_TYPE, PCPS_REF_DCF ); } // mbg_chk_dev_is_dcf @@ -1024,16 +1057,17 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_dcf; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_corr_info - * @see ::mbg_chk_dev_supp_tr_distance + * @see ::mbg_chk_dev_has_tr_distance * @see ::mbg_chk_dev_is_dcf * @see ::mbg_chk_dev_is_lwr */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_pzf( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_has_pzf, IOCTL_DEV_HAS_PZF ); + _mbgdevio_new_query_condx( dh, _pcps_ddev_has_pzf, IOCTL_DEV_HAS_PZF ); } // mbg_chk_dev_has_pzf @@ -1043,7 +1077,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_pzf; /*HDR*/ /** - * @brief Check if a device is a MSF receiver. + * @brief Check if a device is a MSF receiver * * @note This function should be preferred over ::mbg_dev_is_msf, * which has been deprecated. @@ -1051,13 +1085,14 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_pzf; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_is_lwr */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_msf( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_is_msf, IOCTL_DEV_IS_MSF ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_REF_TYPE, PCPS_REF_MSF ); } // mbg_chk_dev_is_msf @@ -1067,7 +1102,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_msf; /*HDR*/ /** - * @brief Check if a device is a WWVB receiver. + * @brief Check if a device is a WWVB receiver * * @note This function should be preferred over ::mbg_dev_is_wwvb, * which has been deprecated. @@ -1075,13 +1110,14 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_msf; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_is_lwr */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_wwvb( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_is_wwvb, IOCTL_DEV_IS_WWVB ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_REF_TYPE, PCPS_REF_WWVB ); } // _pcps_ddev_is_wwvb @@ -1091,7 +1127,29 @@ MBG_CHK_SUPP_FNC _pcps_ddev_is_wwvb; /*HDR*/ /** - * @brief Check if a device is any long wave signal receiver. + * @brief Check if a device is a JJY receiver. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_is_lwr + */ +_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_jjy( MBG_DEV_HANDLE dh ) +{ + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_REF_TYPE, PCPS_REF_JJY ); + +} // _pcps_ddev_is_jjy + +MBG_CHK_SUPP_FNC _pcps_ddev_is_jjy; + + + +/*HDR*/ +/** + * @brief Check if a device is any long wave signal receiver * * Long wave receivers include e.g. DCF77, MSF, WWVB, or JJY. * @@ -1101,15 +1159,21 @@ MBG_CHK_SUPP_FNC _pcps_ddev_is_wwvb; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_is_dcf * @see ::mbg_chk_dev_is_msf * @see ::mbg_chk_dev_is_wwvb + * @see ::mbg_chk_dev_is_jjy */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_lwr( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_is_lwr, IOCTL_DEV_IS_LWR ); + // TODO Combine to single call + return mbg_rc_is_success( mbg_chk_dev_is_dcf( dh ) ) || + mbg_rc_is_success( mbg_chk_dev_is_msf( dh ) ) || + mbg_rc_is_success( mbg_chk_dev_is_wwvb( dh ) ) || + mbg_rc_is_success( mbg_chk_dev_is_jjy( dh ) ); } // mbg_chk_dev_is_lwr @@ -1127,28 +1191,27 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_lwr; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_irig_rx_info * @see ::mbg_set_irig_rx_settings * @see ::mbg_chk_dev_has_irig_tx * @see ::mbg_chk_dev_has_irig */ -_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_irig_rx( MBG_DEV_HANDLE dh ) +_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_tcr( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_is_irig_rx, IOCTL_DEV_IS_IRIG_RX ); - -} // mbg_chk_dev_is_irig_rx - -MBG_CHK_SUPP_FNC mbg_chk_dev_is_irig_rx; + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_REF_TYPE, PCPS_REF_IRIG ); +} // mbg_chk_dev_is_tcr +MBG_CHK_SUPP_FNC mbg_chk_dev_is_tcr; /*HDR*/ /** - * @brief Check if a device provides simple LAN interface API calls. + * @brief Check if a device supports simple LAN interface API calls * * @note This function should be preferred over ::mbg_dev_has_lan_intf, * which has been deprecated. @@ -1156,8 +1219,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_irig_rx; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_lan_if_info * @see ::mbg_get_ip4_state * @see ::mbg_get_ip4_settings @@ -1165,7 +1229,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_is_irig_rx; */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_lan_intf( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_has_lan_intf, IOCTL_DEV_HAS_LAN_INTF ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_PCPS, PCPS_BIT_HAS_LAN_INTF ); } // mbg_chk_dev_has_lan_intf @@ -1175,7 +1239,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_lan_intf; /*HDR*/ /** - * @brief Check if a device provides PTP configuration/status calls. + * @brief Check if a device supports PTP configuration/status calls * * @note This function should be preferred over ::mbg_dev_has_ptp, * which has been deprecated. @@ -1183,8 +1247,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_lan_intf; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_state * @see ::mbg_get_ptp_cfg_info @@ -1193,7 +1258,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_lan_intf; */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ptp( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_has_ptp, IOCTL_DEV_HAS_PTP ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_PCPS, PCPS_BIT_HAS_PTP ); } // mbg_chk_dev_has_ptp @@ -1203,7 +1268,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_ptp; /*HDR*/ /** - * @brief Check if a device provides PTP unicast feature/configuration. + * @brief Check if a device supports PTP unicast feature/configuration * * Not all devices which support PTP do also support PTP Unicast. This API * call checks if PTP Unicast is supported in addition to the standard @@ -1215,8 +1280,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_ptp; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_uc_master_cfg_limits * @see ::mbg_get_all_ptp_uc_master_info @@ -1225,7 +1291,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_ptp; */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ptp_unicast( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_ri_cond( dh, _pcps_has_ri_ptp_unicast, IOCTL_DEV_HAS_PTP_UNICAST ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_RI, GPS_HAS_PTP_UNICAST ); } // mbg_chk_dev_has_ptp_unicast @@ -1233,11 +1299,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_ptp_unicast; - - /*HDR*/ /** - * @brief Check if a device supports the mbg_get_hr_time... functions. + * @brief Check if a device supports the mbg_get_hr_time... functions * * @note This function should be preferred over ::mbg_dev_has_hr_time, * which has been deprecated. @@ -1245,15 +1309,16 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_ptp_unicast; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_hr_time * @see ::mbg_get_hr_time_cycles * @see ::mbg_get_hr_time_comp */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_hr_time( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_has_hr_time, IOCTL_DEV_HAS_HR_TIME ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_PCPS, PCPS_BIT_HAS_HR_TIME ); } // mbg_chk_dev_has_hr_time @@ -1263,7 +1328,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_hr_time; /*HDR*/ /** - * @brief Check if a device supports the mbg_get_fast_hr_timestamp... calls. + * @brief Check if a device supports the mbg_get_fast_hr_timestamp... calls * * @note This function should be preferred over ::mbg_dev_has_fast_hr_timestamp, * which has been deprecated. @@ -1271,15 +1336,16 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_hr_time; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_fast_hr_timestamp_cycles * @see ::mbg_get_fast_hr_timestamp_comp * @see ::mbg_get_fast_hr_timestamp */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_fast_hr_timestamp( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_has_fast_hr_timestamp, IOCTL_DEV_HAS_FAST_HR_TIMESTAMP ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_PCPS, PCPS_BIT_HAS_FAST_HR_TSTAMP ); } // mbg_chk_dev_has_fast_hr_timestamp @@ -1291,7 +1357,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_fast_hr_timestamp; /** * @brief Check if a device supports configurable time scales. * - * By default the cards return %UTC and/or local time. However, some cards + * By default the devices return %UTC and/or local time. However, some cards * can be configured to return raw GPS time or TAI instead. * * @note This function should be preferred over ::mbg_dev_has_time_scale, @@ -1300,8 +1366,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_fast_hr_timestamp; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_time_scale_info * @see ::mbg_set_time_scale_settings */ @@ -1316,7 +1383,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_time_scale; /*HDR*/ -/** (Intentionally excluded from Doxygen) +/* (Intentionally excluded from Doxygen) * @brief Check if a device supports setting an event time * * This feature is only supported by some special custom firmware @@ -1328,8 +1395,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_time_scale; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_set_event_time */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_event_time( MBG_DEV_HANDLE dh ) @@ -1342,11 +1410,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_event_time; - - /*HDR*/ /** - * @brief Check if a device supports the ::mbg_get_ucap_entries and ::mbg_get_ucap_event calls. + * @brief Check if a device supports the ::mbg_get_ucap_entries and ::mbg_get_ucap_event calls * * If the device doesn't support this but is a GPS card then the card provides * a time capture FIFO buffer and the obsolete ::mbg_get_gps_ucap call can be used @@ -1358,8 +1424,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_event_time; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_ucap_entries * @see ::mbg_get_ucap_event * @see ::mbg_clr_ucap_buff @@ -1377,7 +1444,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_ucap; /*HDR*/ /** - * @brief Check if a device supports the ::mbg_clr_ucap_buff call. + * @brief Check if a device supports the ::mbg_clr_ucap_buff call * * The ::mbg_clr_ucap_buff call can be used to clear a device's on-board * time capture FIFO buffer, but the call may not be supported by some @@ -1389,8 +1456,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_ucap; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_clr_ucap_buff */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_can_clr_ucap_buff( MBG_DEV_HANDLE dh ) @@ -1403,11 +1471,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_can_clr_ucap_buff; - - /*HDR*/ /** - * @brief Check if a device supports timezone configuration using the ::TZDL structure. + * @brief Check if a device supports timezone configuration using the ::TZDL structure * * @note This function should be preferred over ::mbg_dev_has_tzdl, * which has been deprecated. @@ -1415,8 +1481,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_can_clr_ucap_buff; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_gps_tzdl * @see ::mbg_set_gps_tzdl * @see ::mbg_chk_dev_has_tz @@ -1433,7 +1500,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_tzdl; /*HDR*/ /** - * @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure. + * @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure * * @note This function should be preferred over ::mbg_dev_has_pcps_tzdl, * which has been deprecated. @@ -1441,8 +1508,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_tzdl; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_pcps_tzdl * @see ::mbg_set_pcps_tzdl * @see ::mbg_chk_dev_has_tz @@ -1467,8 +1535,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_pcps_tzdl; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_tzcode * @see ::mbg_set_tzcode * @see ::mbg_chk_dev_has_tz @@ -1493,8 +1562,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_tzcode; * which has been deprecated. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_tzdl * @see ::mbg_chk_dev_has_pcps_tzdl * @see ::mbg_chk_dev_has_tzcode @@ -1509,8 +1579,6 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_tz; - - /*HDR*/ /** * @brief Check if a device provides either an IRIG input or output. @@ -1521,9 +1589,10 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_tz; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * - * @see ::mbg_chk_dev_is_irig_rx + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_is_tcr * @see ::mbg_chk_dev_has_irig_tx */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig( MBG_DEV_HANDLE dh ) @@ -1546,11 +1615,12 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_irig; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_irig_tx_info * @see ::mbg_set_irig_tx_settings - * @see ::mbg_chk_dev_is_irig_rx + * @see ::mbg_chk_dev_is_tcr * @see ::mbg_chk_dev_has_irig * @see @ref group_icode */ @@ -1574,8 +1644,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_irig_tx; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_irig_ctrl_bits */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh ) @@ -1590,7 +1661,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_irig_ctrl_bits; /*HDR*/ /** - * @brief Check if a device supports the ::mbg_get_raw_irig_data call. + * @brief Check if a device supports the ::mbg_get_raw_irig_data call * * @note This function should be preferred over ::mbg_dev_has_raw_irig_data, * which has been deprecated. @@ -1598,14 +1669,15 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_irig_ctrl_bits; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_raw_irig_data * @see ::mbg_get_raw_irig_data_on_sec_change */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_raw_irig_data( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_cond( dh, _pcps_ddev_has_raw_irig_data, IOCTL_DEV_HAS_RAW_IRIG_DATA ); + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_PCPS, PCPS_BIT_HAS_RAW_IRIG_DATA ); } // mbg_chk_dev_has_raw_irig_data @@ -1615,7 +1687,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_raw_irig_data; /*HDR*/ /** - * @brief Check if a device supports the ::mbg_get_irig_time call. + * @brief Check if a device supports the ::mbg_get_irig_time call * * @note This function should be preferred over ::mbg_dev_has_irig_time, * which has been deprecated. @@ -1623,8 +1695,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_raw_irig_data; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_irig_time */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_time( MBG_DEV_HANDLE dh ) @@ -1639,7 +1712,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_irig_time; /*HDR*/ /** - * @brief Check if a device provides the level of its inputs signal. + * @brief Check if a device provides the level of its inputs signal * * This is useful to display the signal level of e.g. an IRIG or similar * time code, or a long wave signal. @@ -1650,7 +1723,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_irig_time; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_signal( MBG_DEV_HANDLE dh ) { @@ -1664,7 +1739,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_signal; /*HDR*/ /** - * @brief Check if a device provides a modulation signal. + * @brief Check if a device provides a modulation signal * * Modulation signals are e.g. the second marks provided by a long wave receiver. * @@ -1674,7 +1749,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_signal; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_mod( MBG_DEV_HANDLE dh ) { @@ -1687,10 +1764,12 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_mod; /*HDR*/ -/** (Intentionally excluded from Doxygen) - * Check if a device provides a serial output supporting - * higher baud rates than older cards, i.e. ::DEFAULT_BAUD_RATES_DCF_HS - * rather than ::DEFAULT_BAUD_RATES_DCF. +/* (Intentionally excluded from Doxygen) + * @brief Check if a device supports higher baud rates than usual + * + * Check if a device provides a serial output that supports + * higher baud rates than older cards, i.e. ::DEFAULT_BAUD_RATES_DCF_HS + * rather than ::DEFAULT_BAUD_RATES_DCF. * * The call ::mbg_get_serial_settings takes care of this, so applications * which use that call as suggested don't need to use this call directly. @@ -1701,8 +1780,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_mod; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_serial_settings */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_serial_hs( MBG_DEV_HANDLE dh ) @@ -1715,11 +1795,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_serial_hs; - - /*HDR*/ /** - * @brief Check if a device provides a programmable frequency synthesizer. + * @brief Check if a device provides a programmable frequency synthesizer * * @note This function should be preferred over ::mbg_dev_has_synth, * which has been deprecated. @@ -1727,8 +1805,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_serial_hs; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_synth * @see ::mbg_set_synth */ @@ -1744,7 +1823,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_synth; /*HDR*/ /** - * @brief Check if a device provides GPIO signal inputs and/or outputs. + * @brief Check if a device provides GPIO signal inputs and/or outputs * * @note This function should be preferred over ::mbg_dev_has_gpio, * which has been deprecated. @@ -1752,28 +1831,27 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_synth; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_gpio_cfg_limits * @see ::mbg_get_gps_all_gpio_info * @see ::mbg_set_gps_gpio_settings_idx * @see ::mbg_get_gps_all_gpio_status */ -_MBG_API_ATTR int _MBG_API mbg_chk_dev_supp_gpio( MBG_DEV_HANDLE dh ) +_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_gpio( MBG_DEV_HANDLE dh ) { - _mbgdevio_new_query_ri_cond( dh, _pcps_has_ri_gpio, IOCTL_DEV_HAS_GPIO ); - -} // mbg_chk_dev_supp_gpio - -MBG_CHK_SUPP_FNC mbg_chk_dev_supp_gpio; + return mbgdevio_chk_dev_feat( dh, DEV_FEAT_REQ_TYPE_RI, GPS_HAS_GPIO ); +} // mbg_chk_dev_has_gpio +MBG_CHK_SUPP_FNC mbg_chk_dev_has_gpio; /*HDR*/ /** - * @brief Check if a device supports configuration of antenna cable length. + * @brief Check if a device supports configuration of antenna cable length * * @note This function should be preferred over ::mbg_dev_has_cab_len, * which has been deprecated. @@ -1781,8 +1859,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_supp_gpio; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_gps_ant_cable_len * @see ::mbg_set_gps_ant_cable_len */ @@ -1798,10 +1877,10 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_cab_len; /*HDR*/ /** - * @brief Check if a device provides a configurable ref time offset. + * @brief Check if a device provides a configurable ref time offset * * This may be required to convert the received time to %UTC, if the input - * signal doesn't specify this (e.g. with most IRIG code formats). //### + * signal doesn't specify this (e.g. with most IRIG code formats). * * @note This function should be preferred over ::mbg_dev_has_ref_offs, * which has been deprecated. @@ -1809,8 +1888,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_cab_len; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_ref_offs * @see ::mbg_set_ref_offs */ @@ -1829,7 +1909,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_ref_offs; * @brief Check if a device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS. * * These structures contain optional settings, controlled by flags. - * See ::MBG_OPT_SETTINGS and related definitions. + * See ::MBG_OPT_SETTINGS and associated definitions. * * @note This function should be preferred over ::mbg_dev_has_opt_flags, * which has been deprecated. @@ -1837,8 +1917,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_ref_offs; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_opt_info * @see ::mbg_set_opt_settings */ @@ -1859,7 +1940,7 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_opt_flags; * 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. + * Meinberg GPS and GNSS devices. * * The %UTC parameter set is usually received from the satellites' broadcasts * and contains the current time offset between GPS time and UTC, plus information @@ -1874,8 +1955,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_opt_flags; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_utc_parm * @see ::mbg_set_utc_parm */ @@ -1893,14 +1975,20 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_utc_parm; /** * @brief Check if a device supports reading correlation info * + * The PZF phase modulation decoded by DCF77 PZF receivers is decoded + * using a correlation approach, and optionally there's an API call + * supported which can be used to retrieve the correlation value + * and thus determine the quality of the input signal. + * * @note This function should be preferred over ::mbg_dev_has_corr_info, * which has been deprecated. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_pzf * @see ::mbg_get_corr_info */ @@ -1927,19 +2015,20 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_has_corr_info; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_pzf * @see ::mbg_get_tr_distance * @see ::mbg_set_tr_distance */ -_MBG_API_ATTR int _MBG_API mbg_chk_dev_supp_tr_distance( MBG_DEV_HANDLE dh ) +_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tr_distance( MBG_DEV_HANDLE dh ) { _mbgdevio_new_query_cond( dh, _pcps_ddev_has_tr_distance, IOCTL_DEV_HAS_TR_DISTANCE ); -} // mbg_chk_dev_supp_tr_distance +} // mbg_chk_dev_has_tr_distance -MBG_CHK_SUPP_FNC mbg_chk_dev_supp_tr_distance; +MBG_CHK_SUPP_FNC mbg_chk_dev_has_tr_distance; @@ -1953,23 +2042,24 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_supp_tr_distance; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_debug_status */ -_MBG_API_ATTR int _MBG_API mbg_chk_dev_supp_debug_status( MBG_DEV_HANDLE dh ) +_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_debug_status( MBG_DEV_HANDLE dh ) { _mbgdevio_new_query_cond( dh, _pcps_ddev_has_debug_status, IOCTL_DEV_HAS_DEBUG_STATUS ); -} // mbg_chk_dev_supp_debug_status +} // mbg_chk_dev_has_debug_status -MBG_CHK_SUPP_FNC mbg_chk_dev_supp_debug_status; +MBG_CHK_SUPP_FNC mbg_chk_dev_has_debug_status; /*HDR*/ /** - * @brief Check if a device provides an on-board event log. + * @brief Check if a device provides an on-board event log * * @note This function should be preferred over ::mbg_dev_has_evt_log, * which has been deprecated. @@ -1977,26 +2067,27 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_supp_debug_status; * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_clr_evt_log * @see ::mbg_get_num_evt_log_entries * @see ::mbg_get_first_evt_log_entry * @see ::mbg_get_next_evt_log_entry */ -_MBG_API_ATTR int _MBG_API mbg_chk_dev_supp_evt_log( MBG_DEV_HANDLE dh ) +_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_evt_log( MBG_DEV_HANDLE dh ) { _mbgdevio_new_query_cond( dh, _pcps_ddev_has_evt_log, IOCTL_DEV_HAS_EVT_LOG ); -} // mbg_chk_dev_supp_evt_log +} // mbg_chk_dev_has_evt_log -MBG_CHK_SUPP_FNC mbg_chk_dev_supp_evt_log; +MBG_CHK_SUPP_FNC mbg_chk_dev_has_evt_log; /*HDR*/ /** - * @brief Check if a device supports the ::RECEIVER_INFO structure and related calls. + * @brief Check if a device supports the ::RECEIVER_INFO structure and related calls * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_receiver_info preferably. * @@ -2004,8 +2095,9 @@ MBG_CHK_SUPP_FNC mbg_chk_dev_supp_evt_log; * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_receiver_info */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_receiver_info" ) _MBG_API mbg_dev_has_receiver_info( MBG_DEV_HANDLE dh, int *p ) @@ -2018,7 +2110,7 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_receiver_info" ) _MBG_API mbg /*HDR*/ /** - * @brief Check if a device supports large configuration data structures. + * @brief Check if a device supports large configuration data structures * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_gps_data preferably. * @@ -2026,8 +2118,9 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_receiver_info" ) _MBG_API mbg * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_gps_data */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_gps_data" ) _MBG_API mbg_dev_has_gps_data( MBG_DEV_HANDLE dh, int *p ) @@ -2040,7 +2133,7 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_gps_data" ) _MBG_API mbg_dev_ /*HDR*/ /** - * @brief Check if a device supports the ::mbg_generic_io API call. + * @brief Check if a device supports the ::mbg_generic_io API call * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_generic_io preferably. * @@ -2048,8 +2141,9 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_gps_data" ) _MBG_API mbg_dev_ * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_generic_io */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_generic_io" ) _MBG_API mbg_dev_has_generic_io( MBG_DEV_HANDLE dh, int *p ) @@ -2062,7 +2156,7 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_generic_io" ) _MBG_API mbg_de /*HDR*/ /** - * @brief Check if a device supports the ::mbg_get_asic_version call. + * @brief Check if a device supports the ::mbg_get_asic_version call * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_asic_version preferably. * @@ -2070,8 +2164,9 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_generic_io" ) _MBG_API mbg_de * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_asic_version */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_asic_version" ) _MBG_API mbg_dev_has_asic_version( MBG_DEV_HANDLE dh, int *p ) @@ -2092,8 +2187,9 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_asic_version" ) _MBG_API mbg_ * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_asic_features * @see ::mbg_get_asic_features */ @@ -2101,10 +2197,7 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_asic_features" ) _MBG_API mbg { _mbgdevio_old_query_cond( dh, _pcps_ddev_has_asic_features, IOCTL_DEV_HAS_PCI_ASIC_FEATURES, p ); -} // mbg_chk_dev_has_asic_features - - - +} // mbg_dev_has_asic_features @@ -2112,18 +2205,19 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_asic_features" ) _MBG_API mbg /** * @brief Check if a device provides extended multi ref (XMR) inputs. * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_supp_xmr preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_xmr preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_chk_dev_supp_xmr + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_xmr * @see @ref group_multi_ref_ext */ -_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_xmr" ) _MBG_API mbg_dev_has_xmr( MBG_DEV_HANDLE dh, int *p ) +_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_xmr" ) _MBG_API mbg_dev_has_xmr( MBG_DEV_HANDLE dh, int *p ) { _mbgdevio_old_query_ri_cond( dh, _pcps_has_ri_xmr, IOCTL_DEV_HAS_XMR, p ); @@ -2133,7 +2227,7 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_xmr" ) _MBG_API mbg_dev_has_ /*HDR*/ /** - * @brief Check if a device supports GNSS configuration. + * @brief Check if a device supports GNSS configuration * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_gnss preferably. * @@ -2141,8 +2235,9 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_xmr" ) _MBG_API mbg_dev_has_ * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_gnss */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gnss" ) _MBG_API mbg_dev_is_gnss( MBG_DEV_HANDLE dh, int *p ) @@ -2155,16 +2250,17 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gnss" ) _MBG_API mbg_dev_is_gn /*HDR*/ /** - * @brief Check if a device is a GPS receiver. + * @brief Check if a device is a GPS receiver * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_is_gps preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_gps preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_gps */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gps" ) _MBG_API mbg_dev_is_gps( MBG_DEV_HANDLE dh, int *p ) @@ -2177,7 +2273,7 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gps" ) _MBG_API mbg_dev_is_gps /*HDR*/ /** - * @brief Check if a device is a DCF77 receiver. + * @brief Check if a device is a DCF77 receiver * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_dcf preferably. * @@ -2185,8 +2281,9 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gps" ) _MBG_API mbg_dev_is_gps * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_dcf */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_dcf" ) _MBG_API mbg_dev_is_dcf( MBG_DEV_HANDLE dh, int *p ) @@ -2207,8 +2304,9 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_dcf" ) _MBG_API mbg_dev_is_dcf * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_pzf */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_pzf" ) _MBG_API mbg_dev_has_pzf( MBG_DEV_HANDLE dh, int *p ) @@ -2221,7 +2319,7 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_pzf" ) _MBG_API mbg_dev_has_p /*HDR*/ /** - * @brief Check if a device is a MSF receiver. + * @brief Check if a device is a MSF receiver * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_msf preferably. * @@ -2229,8 +2327,9 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_pzf" ) _MBG_API mbg_dev_has_p * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_msf */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_msf" ) _MBG_API mbg_dev_is_msf( MBG_DEV_HANDLE dh, int *p ) @@ -2243,7 +2342,7 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_msf" ) _MBG_API mbg_dev_is_msf /*HDR*/ /** - * @brief Check if a device is a WWVB receiver. + * @brief Check if a device is a WWVB receiver * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_wwvb preferably. * @@ -2251,8 +2350,9 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_msf" ) _MBG_API mbg_dev_is_msf * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_wwvb */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_wwvb" ) _MBG_API mbg_dev_is_wwvb( MBG_DEV_HANDLE dh, int *p ) @@ -2265,7 +2365,7 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_wwvb" ) _MBG_API mbg_dev_is_ww /*HDR*/ /** - * @brief Check if a device is any long wave signal receiver. + * @brief Check if a device is any long wave signal receiver * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_lwr preferably. * @@ -2273,8 +2373,9 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_wwvb" ) _MBG_API mbg_dev_is_ww * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_lwr */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_lwr" ) _MBG_API mbg_dev_is_lwr( MBG_DEV_HANDLE dh, int *p ) @@ -2289,17 +2390,18 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_lwr" ) _MBG_API mbg_dev_is_lwr /** * @brief Check if a device provides a configurable IRIG input. * - * @deprecated This function is deprecated, use ::mbg_chk_dev_is_irig_rx preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_tcr preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_chk_dev_is_irig_rx + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_tcr */ -_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_irig_rx" ) _MBG_API mbg_dev_is_irig_rx( MBG_DEV_HANDLE dh, int *p ) +_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_tcr" ) _MBG_API mbg_dev_is_irig_rx( MBG_DEV_HANDLE dh, int *p ) { _mbgdevio_old_query_cond( dh, _pcps_ddev_is_irig_rx, IOCTL_DEV_IS_IRIG_RX, p ); @@ -2307,11 +2409,9 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_irig_rx" ) _MBG_API mbg_dev_is - - /*HDR*/ /** - * @brief Check if a device provides simple LAN interface API calls. + * @brief Check if a device supports simple LAN interface API calls * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_lan_intf preferably. * @@ -2319,8 +2419,9 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_irig_rx" ) _MBG_API mbg_dev_is * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_lan_intf */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_lan_intf" ) _MBG_API mbg_dev_has_lan_intf( MBG_DEV_HANDLE dh, int *p ) @@ -2333,16 +2434,17 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_lan_intf" ) _MBG_API mbg_dev_ /*HDR*/ /** - * @brief Check if a device provides PTP configuration/status calls. + * @brief Check if a device supports PTP configuration/status calls * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_ptp preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ptp preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_ptp */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ptp" ) _MBG_API mbg_dev_has_ptp( MBG_DEV_HANDLE dh, int *p ) @@ -2355,16 +2457,17 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ptp" ) _MBG_API mbg_dev_has_p /*HDR*/ /** - * @brief Check if a device provides PTP unicast feature/configuration. + * @brief Check if a device supports PTP unicast feature/configuration * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_ptp_unicast preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ptp_unicast preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_ptp_unicast */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ptp_unicast" ) _MBG_API mbg_dev_has_ptp_unicast( MBG_DEV_HANDLE dh, int *p ) @@ -2375,20 +2478,19 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ptp_unicast" ) _MBG_API mbg_d - - /*HDR*/ /** - * @brief Check if a device supports the HR_TIME functions. + * @brief Check if a device supports the HR_TIME functions * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_hr_time preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_hr_time preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_hr_time */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_hr_time" ) _MBG_API mbg_dev_has_hr_time( MBG_DEV_HANDLE dh, int *p ) @@ -2401,21 +2503,22 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_hr_time" ) _MBG_API mbg_dev_h /*HDR*/ /** - * @brief Check if a device supports the mbg_get_fast_hr_timestamp_...() calls. + * @brief Check if a device supports the mbg_get_fast_hr_timestamp_...() calls * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_fast_hr_timestamp preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_fast_hr_timestamp preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_fast_hr_timestamp */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_fast_hr_timestamp" ) _MBG_API mbg_dev_has_fast_hr_timestamp( MBG_DEV_HANDLE dh, int *p ) { - _mbgdevio_old_query_cond( dh, _pcps_ddev_has_fast_hr_timestamp, IOCTL_DEV_HAS_FAST_HR_TIMESTAMP, p ); + return mbgdevio_chk_dev_feat_deprecated( dh, DEV_FEAT_REQ_TYPE_PCPS, PCPS_BIT_HAS_FAST_HR_TSTAMP, p ); } // mbg_dev_has_fast_hr_timestamp @@ -2423,16 +2526,17 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_fast_hr_timestamp" ) _MBG_API /*HDR*/ /** - * @brief Check if a device supports configurable time scales. + * @brief Check if a device supports configurable time scales * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_time_scale preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_time_scale preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_time_scale */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_time_scale" ) _MBG_API mbg_dev_has_time_scale( MBG_DEV_HANDLE dh, int *p ) @@ -2449,14 +2553,15 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_time_scale" ) _MBG_API mbg_de * * @note This is only supported by some customized devices * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_event_time preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_event_time preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_event_time */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_event_time" ) _MBG_API mbg_dev_has_event_time( MBG_DEV_HANDLE dh, int *p ) @@ -2467,20 +2572,19 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_event_time" ) _MBG_API mbg_de - - /*HDR*/ /** - * @brief Check if a device supports the ::mbg_get_ucap_entries and ::mbg_get_ucap_event calls. + * @brief Check if a device supports the ::mbg_get_ucap_entries and ::mbg_get_ucap_event calls * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_ucap preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ucap preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_ucap */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ucap" ) _MBG_API mbg_dev_has_ucap( MBG_DEV_HANDLE dh, int *p ) @@ -2493,15 +2597,15 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ucap" ) _MBG_API mbg_dev_has_ /*HDR*/ /** - * @brief Check if a device supports the ::mbg_clr_ucap_buff call. + * @brief Check if a device supports the ::mbg_clr_ucap_buff call * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_can_clr_ucap_buff preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_can_clr_ucap_buff preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_chk_dev_can_clr_ucap_buff */ @@ -2513,20 +2617,19 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_can_clr_ucap_buff" ) _MBG_API mbg - - /*HDR*/ /** - * @brief Check if a device supports timezone configuration using the ::TZDL structure. + * @brief Check if a device supports timezone configuration using the ::TZDL structure * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_tzdl preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tzdl preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_tzdl */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tzdl" ) _MBG_API mbg_dev_has_tzdl( MBG_DEV_HANDLE dh, int *p ) @@ -2539,16 +2642,17 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tzdl" ) _MBG_API mbg_dev_has_ /*HDR*/ /** - * @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure. + * @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_pcps_tzdl preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_pcps_tzdl preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_pcps_tzdl */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_pcps_tzdl" ) _MBG_API mbg_dev_has_pcps_tzdl( MBG_DEV_HANDLE dh, int *p ) @@ -2561,16 +2665,17 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_pcps_tzdl" ) _MBG_API mbg_dev /*HDR*/ /** - * @brief Check if a device supports timezone configuration using the ::PCPS_TZCODE type. + * @brief Check if a device supports timezone configuration using the ::PCPS_TZCODE type * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_tzcode preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tzcode preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_tzcode */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tzcode" ) _MBG_API mbg_dev_has_tzcode( MBG_DEV_HANDLE dh, int *p ) @@ -2583,16 +2688,17 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tzcode" ) _MBG_API mbg_dev_ha /*HDR*/ /** - * @brief Check if a device supports any kind of timezone configuration. + * @brief Check if a device supports any kind of timezone configuration * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_tz preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tz preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_tz */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tz" ) _MBG_API mbg_dev_has_tz( MBG_DEV_HANDLE dh, int *p ) @@ -2603,20 +2709,19 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tz" ) _MBG_API mbg_dev_has_tz - - /*HDR*/ /** - * @brief Check if a device provides either an IRIG input or output. + * @brief Check if a device provides either an IRIG input or output * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_irig preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_irig */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig" ) _MBG_API mbg_dev_has_irig( MBG_DEV_HANDLE dh, int *p ) @@ -2629,16 +2734,17 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig" ) _MBG_API mbg_dev_has_ /*HDR*/ /** - * @brief Check if a device provides a configurable IRIG output. + * @brief Check if a device provides a configurable IRIG output * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_irig_tx preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig_tx preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_irig_tx */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_tx" ) _MBG_API mbg_dev_has_irig_tx( MBG_DEV_HANDLE dh, int *p ) @@ -2653,14 +2759,15 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_tx" ) _MBG_API mbg_dev_h /** * @brief Check if a device supports the ::mbg_get_irig_ctrl_bits call * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_irig_ctrl_bits preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig_ctrl_bits preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_irig_ctrl_bits */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_ctrl_bits" ) _MBG_API mbg_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh, int *p ) @@ -2673,15 +2780,15 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_ctrl_bits" ) _MBG_API mb /*HDR*/ /** - * @brief Check if a device supports the ::mbg_get_raw_irig_data call. + * @brief Check if a device supports the ::mbg_get_raw_irig_data call * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_raw_irig_data preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_raw_irig_data preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_chk_dev_has_raw_irig_data */ @@ -2695,16 +2802,17 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_raw_irig_data" ) _MBG_API mbg /*HDR*/ /** - * @brief Check if a device supports the ::mbg_get_irig_time call. + * @brief Check if a device supports the ::mbg_get_irig_time call * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_irig_time preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig_time preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_irig_time */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_time" ) _MBG_API mbg_dev_has_irig_time( MBG_DEV_HANDLE dh, int *p ) @@ -2717,16 +2825,17 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_time" ) _MBG_API mbg_dev /*HDR*/ /** - * @brief Check if a device provides the level of its inputs signal. + * @brief Check if a device provides the level of its inputs signal * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_signal preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_signal preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_signal */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_signal" ) _MBG_API mbg_dev_has_signal( MBG_DEV_HANDLE dh, int *p ) @@ -2739,16 +2848,17 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_signal" ) _MBG_API mbg_dev_ha /*HDR*/ /** - * @brief Check if a device provides a modulation signal. + * @brief Check if a device provides a modulation signal * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_mod preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_mod preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_mod */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_mod" ) _MBG_API mbg_dev_has_mod( MBG_DEV_HANDLE dh, int *p ) @@ -2761,18 +2871,21 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_mod" ) _MBG_API mbg_dev_has_m /*HDR*/ /* (Intentionally excluded from Doxygen) - * Check if a device provides a serial output supporting - * higher baud rates than older cards, i.e. ::DEFAULT_BAUD_RATES_DCF_HS - * rather than ::DEFAULT_BAUD_RATES_DCF. + * @brief Check if a device supports higher baud rates than usual + * + * Check if a device provides a serial output that supports + * higher baud rates than older cards, i.e. ::DEFAULT_BAUD_RATES_DCF_HS + * rather than ::DEFAULT_BAUD_RATES_DCF. * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_serial_hs preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_serial_hs preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_serial_hs */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_serial_hs" ) _MBG_API mbg_dev_has_serial_hs( MBG_DEV_HANDLE dh, int *p ) @@ -2783,20 +2896,19 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_serial_hs" ) _MBG_API mbg_dev - - /*HDR*/ /** - * @brief Check if a device provides a programmable frequency synthesizer. + * @brief Check if a device provides a programmable frequency synthesizer * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_synth preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_synth preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_synth */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_synth" ) _MBG_API mbg_dev_has_synth( MBG_DEV_HANDLE dh, int *p ) @@ -2809,19 +2921,20 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_synth" ) _MBG_API mbg_dev_has /*HDR*/ /** - * @brief Check if a device provides GPIO signal inputs and/or outputs. + * @brief Check if a device provides GPIO signal inputs and/or outputs * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_supp_gpio preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_gpio preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_chk_dev_supp_gpio + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_gpio */ -_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_gpio" ) _MBG_API mbg_dev_has_gpio( MBG_DEV_HANDLE dh, int *p ) +_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_gpio" ) _MBG_API mbg_dev_has_gpio( MBG_DEV_HANDLE dh, int *p ) { _mbgdevio_old_query_ri_cond( dh, _pcps_has_ri_gpio, IOCTL_DEV_HAS_GPIO, p ); @@ -2829,20 +2942,19 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_gpio" ) _MBG_API mbg_dev_has - - /*HDR*/ /** - * @brief Check if a device supports configuration of antenna cable length. + * @brief Check if a device supports configuration of antenna cable length * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_cab_len preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_cab_len preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_cab_len */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_cab_len" ) _MBG_API mbg_dev_has_cab_len( MBG_DEV_HANDLE dh, int *p ) @@ -2855,16 +2967,17 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_cab_len" ) _MBG_API mbg_dev_h /*HDR*/ /** - * @brief Check if a device provides a configurable ref time offset. + * @brief Check if a device provides a configurable ref time offset * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_ref_offs preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ref_offs preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_ref_offs */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ref_offs" ) _MBG_API mbg_dev_has_ref_offs( MBG_DEV_HANDLE dh, int *p ) @@ -2877,16 +2990,17 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ref_offs" ) _MBG_API mbg_dev_ /*HDR*/ /** - * @brief Check if a device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS. + * @brief Check if a device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_opt_flags preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_opt_flags preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_opt_flags */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_opt_flags" ) _MBG_API mbg_dev_has_opt_flags( MBG_DEV_HANDLE dh, int *p ) @@ -2899,16 +3013,17 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_opt_flags" ) _MBG_API mbg_dev /*HDR*/ /** - * @brief Check if a device support reading/writing of ::UTC parameters. + * @brief Check if a device support reading/writing of ::UTC parameters * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_utc_parm preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_utc_parm preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_utc_parm */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_utc_parm" ) _MBG_API mbg_dev_has_utc_parm( MBG_DEV_HANDLE dh, int *p ) @@ -2923,14 +3038,15 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_utc_parm" ) _MBG_API mbg_dev_ /** * @brief Check if a device supports reading correlation info * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_corr_info preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_corr_info preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_corr_info */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_corr_info" ) _MBG_API mbg_dev_has_corr_info( MBG_DEV_HANDLE dh, int *p ) @@ -2945,17 +3061,18 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_corr_info" ) _MBG_API mbg_dev /** * @brief Check if a device supports configurable distance from transmitter * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_supp_tr_distance preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tr_distance preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_chk_dev_supp_tr_distance + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_tr_distance */ -_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_tr_distance" ) _MBG_API mbg_dev_has_tr_distance( MBG_DEV_HANDLE dh, int *p ) +_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tr_distance" ) _MBG_API mbg_dev_has_tr_distance( MBG_DEV_HANDLE dh, int *p ) { _mbgdevio_old_query_cond( dh, _pcps_ddev_has_tr_distance, IOCTL_DEV_HAS_TR_DISTANCE, p ); @@ -2967,17 +3084,18 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_tr_distance" ) _MBG_API mbg_ /** * @brief Check if a device provides a debug status word to be read * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_supp_debug_status preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_debug_status preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_chk_dev_supp_debug_status + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_debug_status */ -_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_debug_status" ) _MBG_API mbg_dev_has_debug_status( MBG_DEV_HANDLE dh, int *p ) +_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_debug_status" ) _MBG_API mbg_dev_has_debug_status( MBG_DEV_HANDLE dh, int *p ) { _mbgdevio_old_query_cond( dh, _pcps_ddev_has_debug_status, IOCTL_DEV_HAS_DEBUG_STATUS, p ); @@ -2989,17 +3107,18 @@ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_debug_status" ) _MBG_API mbg /** * @brief Check if a device provides an on-board event log. * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_supp_evt_log preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_evt_log preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_chk_dev_supp_evt_log + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_evt_log */ -_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_evt_log" ) _MBG_API mbg_dev_has_evt_log( MBG_DEV_HANDLE dh, int *p ) +_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_evt_log" ) _MBG_API mbg_dev_has_evt_log( MBG_DEV_HANDLE dh, int *p ) { _mbgdevio_old_query_cond( dh, _pcps_ddev_has_evt_log, IOCTL_DEV_HAS_EVT_LOG, p ); @@ -3017,7 +3136,7 @@ static /*HDR*/ * @param[in] p_cyc_freq Cycles frequency determined by the application, depending on the type of cycles counter * @param[out] hns_latency Optional pointer to a variable to receive the computed latency, or NULL * - * @return ::MBG_SUCCESS on success, or one of the @ref MBG_ERROR_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES */ int mbg_comp_hr_latency( PCPS_TIME_STAMP *ts, const MBG_PC_CYCLES *p_cyc_ts, @@ -3117,155 +3236,191 @@ int mbg_comp_hr_latency( PCPS_TIME_STAMP *ts, /*HDR*/ /** - * @brief Open a device by index, starting from 0 + * @brief Create a device file name according to an index number * - * @deprecated This function is deprecated, use ::mbg_open_device_by_name preferably. + * Create a system-specific device file name string, e.g. "/dev/mbgclock0" + * under Linux and similar systems, which can be used with the + * open() call on systems which support this. * - * @note See comments for ::mbg_find_devices for details. + * Under Windows a hardware ID string is used, so a Windows-specific function + * is called to retrieve the string * - * @param[in] device_index Index of the device, use 0 for the first device + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] dev_idx The device index number. * - * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * @see mbg_svc_get_device_path under Windows */ -_MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device( unsigned int device_index ) +_MBG_API_ATTR int _MBG_API mbg_dev_fn_from_dev_idx( char *s, int max_len, int dev_idx ) { -#if defined( MBG_TGT_WIN32 ) + size_t n = 0; - const char *device_path; - HANDLE dh; - - device_path = mbg_svc_get_device_path( device_index ); + #if MBG_TGT_HAS_DEV_FN + n = snprintf_safe( s, max_len, mbg_dev_fn_fmt, dev_idx ); + #elif defined( MBG_TGT_WIN32 ) + n = sn_cpy_str_safe( s, max_len, mbg_svc_get_device_path( dev_idx ) ); + #else + n = snprintf_safe( s, max_len, "index #%i", dev_idx ); + #endif - if ( device_path == NULL ) - goto fail; + return _int_from_size_t( n ); +} // mbg_dev_fn_from_dev_idx - dh = CreateFileA( - device_path, // file name - GENERIC_READ | GENERIC_WRITE, // access mode - 0, // share mode - NULL, // security descriptor - OPEN_EXISTING, // how to create - 0, // file attributes - NULL // handle to template file - ); - if ( INVALID_HANDLE_VALUE == dh ) - { - #if 0 //##++ - printf( "mbg_open_device: CreateFile failed for index %i\n", device_index ); - #endif +/*HDR*/ +/** + * @brief Open a device by index number + * + * For details and similar functions see @ref mbgdevio_open_fncs. + * + * @param[in] dev_idx Device index number, starting from 0. + * + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs + */ +MBG_DEV_HANDLE _MBG_API mbg_open_device( int dev_idx ) +{ + if ( dev_idx < 0 ) goto fail; - } - - return dh; - -fail: - return MBG_INVALID_DEV_HANDLE; -#elif defined( MBG_TGT_POSIX ) && !defined( MBG_TGT_QNX_NTO ) - - MBG_DEV_HANDLE dh; - char dev_fn[50]; - - if ( device_index > N_SUPP_DEV_BUS ) - device_index = N_SUPP_DEV_BUS; + #if defined( MBG_TGT_WIN32 ) + { + const char *device_path = mbg_svc_get_device_path( dev_idx ); - snprintf_safe( dev_fn, sizeof( dev_fn ), "/dev/mbgclock%d", device_index ); + return mbg_open_device_by_dev_fn( device_path ); + } + #elif MBG_TGT_HAS_DEV_FN + { + MBG_DEV_FN dev_fn; - dh = open( dev_fn, O_RDWR ); + mbg_dev_fn_from_dev_idx( dev_fn, sizeof( dev_fn ), dev_idx ); - return ( dh < 0 ) ? MBG_INVALID_DEV_HANDLE : dh; + return mbg_open_device_by_dev_fn( dev_fn ); + } + #else -#else + #if defined( _PCPSDRVR_H ) + if ( dev_idx < n_ddevs ) + return &pcps_ddev[dev_idx]; + #endif - return ( device_index < n_ddevs ) ? &pcps_ddev[device_index] : NULL; + // intentionally fall-through to "fail" + #endif -#endif +fail: + errno = ENODEV; // No such device + return MBG_INVALID_DEV_HANDLE; } // mbg_open_device -static /*HDR*/ -/* (Intentionally excluded from Doxygen) - * @brief Return a handle to a device specified by a given hardware_id. +/*HDR*/ +/** + * @brief Open a device specified by a device file name + * + * The format the device file name depends on the operating system. + * see ::MBG_DEV_FN. * - * 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. + * For details and similar functions see @ref mbgdevio_open_fncs. * - * @param[in] hw_id The hardware ID string + * @param[in] dev_fn The device file name * * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs + * @see ::MBG_DEV_FN */ -MBG_DEV_HANDLE _MBG_API mbg_open_device_by_hw_id( const char *hw_id ) +_MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_dev_fn( const char *dev_fn ) { #if defined( MBG_TGT_WIN32 ) - HANDLE dh; - int ret = 0; - BOOL usb = FALSE; - - if ( hw_id == NULL ) - goto fail; + if ( dev_fn == NULL ) + { + SetLastError( ERROR_INVALID_PARAMETER ); // TODO Is this error code appropriate? + return MBG_INVALID_DEV_HANDLE; + } - dh = CreateFileA( - hw_id, // file name + return CreateFileA( + dev_fn, // file name GENERIC_READ | GENERIC_WRITE, // access mode 0, // share mode NULL, // security descriptor OPEN_EXISTING, // how to create - strstr(hw_id,"usb") ? FILE_FLAG_OVERLAPPED : 0, // file attributes + strstr( dev_fn, "usb" ) ? FILE_FLAG_OVERLAPPED : 0, // file attributes NULL // handle to template file ); - if ( INVALID_HANDLE_VALUE == dh ) - goto fail; - - return dh; - -fail: - return MBG_INVALID_DEV_HANDLE; - #elif defined( MBG_TGT_POSIX ) && !defined( MBG_TGT_QNX_NTO ) - MBG_DEV_HANDLE dh = -1; - - if ( strlen( hw_id ) > 0 ) - dh = open( hw_id, O_RDWR ); + if ( dev_fn == NULL ) + { + errno = EFAULT; // Bad address, invalid pointer + return MBG_INVALID_DEV_HANDLE; + } - return ( dh < 0 ) ? MBG_INVALID_DEV_HANDLE : dh; + return open( dev_fn, O_RDWR ); #else + errno = ( dev_fn == NULL ) ? EFAULT : ENODEV; return MBG_INVALID_DEV_HANDLE; #endif -} // mbg_open_device_by_hw_id +} // mbg_open_device_by_dev_fn + /*HDR*/ /** - * @brief Get the number of supported devices installed on the computer. + * @brief Open a device specified by a device file name * - * @deprecated This function is deprecated, ::mbg_find_devices_with_names - * should be used instead. + * @deprecated This function is deprecated, use + * ::mbg_open_device_by_dev_fn preferably. + * + * The format the device file name depends on the operating system. + * see ::MBG_DEV_FN. + * + * For details and similar functions see @ref mbgdevio_open_fncs. * - * @note This function is out of date since it may not work - * correctly for Meinberg devices which are disconnected and reconnected - * while the system is running (e.g. USB devices). However, the function - * will be kept for compatibility reasons and works correctly if all - * Meinberg devices are connected at system boot and are not disconnected - * and reconnected during operation + * @param[in] dev_fn The device file name, see ::MBG_DEV_FN + * + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs + * @see ::MBG_DEV_FN + */ +_MBG_API_ATTR MBG_DEV_HANDLE _DEPRECATED_BY( "mbg_open_device_by_dev_fn" ) _MBG_API mbg_open_device_by_hw_id( const char *dev_fn ) +{ + return mbg_open_device_by_dev_fn( dev_fn ); + +} // mbg_open_device_by_hw_id + + + +/*HDR*/ +/** + * @brief Get the number of devices installed on the computer + * + * The function ::mbg_find_devices_with_names should eventually + * be used preferafly. See @ref mbgdevio_open_fncs. * * @return The number of devices found * * @see ::mbg_find_devices_with_names + * @see ::mbg_open_device + * @see @ref mbgdevio_open_fncs */ _MBG_API_ATTR int _MBG_API mbg_find_devices( void ) { @@ -3273,10 +3428,10 @@ _MBG_API_ATTR int _MBG_API mbg_find_devices( void ) #if defined( MBG_TGT_QNX_NTO ) // Since this program accessed the hardware directly - // I/O privileges must be assigned to the thread. + // I/O privileges have to be assigned to the thread. if ( ThreadCtl( _NTO_TCTL_IO, NULL ) == -1 ) { - perror( "Fatal error" ); + fprintf( stderr, "** ThreadCtl() failed to request I/O privileges: %s\n\n", strerror( errno ) ); exit( 1 ); } #endif @@ -3287,11 +3442,11 @@ _MBG_API_ATTR int _MBG_API mbg_find_devices( void ) pcps_detect_any_tsr(); prv_busy = pcps_tsr_set_busy_flag( 1 ); - pcps_detect_clocks( pcps_isa_ports, NULL ); + pcps_detect_devices( pcps_isa_ports, NULL ); pcps_tsr_set_busy_flag( prv_busy ); } #else - pcps_detect_clocks( pcps_isa_ports, NULL ); + pcps_detect_devices( pcps_isa_ports, NULL ); #endif return n_ddevs; @@ -3300,13 +3455,13 @@ _MBG_API_ATTR int _MBG_API mbg_find_devices( void ) return mbg_svc_find_devices(); -#elif defined( MBG_TGT_POSIX ) + #elif defined( MBG_TGT_POSIX ) MBG_DEV_HANDLE dh; int i = 0; int n = 0; - while( i < N_SUPP_DEV_BUS ) + while ( i < N_SUPP_DEV_BUS ) { dh = mbg_open_device( i ); @@ -3327,244 +3482,406 @@ _MBG_API_ATTR int _MBG_API mbg_find_devices( void ) -#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX ) +#if MBG_TGT_HAS_DEV_FN -//### TODO: document this function +/** + * @brief Free a list of device names that has been allocated before + * + * This function should be called to free a list that has been + * allocated by ::setup_dev_fn_list. + * + * @param[out] list Pointer to a list to be allocated and + * + * @see ::setup_dev_fn_list + * @see ::setup_dev_details_from_dev_fn + */ static /*HDR*/ -int mbg_find_devices_with_hw_id( MBG_DEVICE_LIST ** list, int max_devs ) +void free_dev_fn_list( MBG_DEV_FN_LIST_ENTRY *list ) { #if defined( MBG_TGT_WIN32 ) + mbg_svc_free_device_list( list ); // TODO + #else + while ( list ) + { + MBG_DEV_FN_LIST_ENTRY *next; - return mbg_svc_find_devices_with_hw_id( list, max_devs ); + if ( list->dev_fn_ptr ) + { + free( list->dev_fn_ptr ); + list->dev_fn_ptr = NULL; + } - #elif defined( MBG_TGT_POSIX ) + next = list->next; + free( list ); + list = next; + } + #endif - MBG_DEVICE_LIST *ListBegin; - int n = 0; - int i = 0; +} // free_dev_fn_list - (*list) = (MBG_DEVICE_LIST *) malloc( sizeof( **list ) ); - memset( *list, 0, sizeof( **list ) ); +#endif // MBG_TGT_HAS_DEV_FN - ListBegin = (*list); - for (;;) + +#if MBG_TGT_HAS_DEV_FN + +static /*HDR*/ +/** + * @brief Allocate and fill a list of device file names + * + * The function ::setup_dev_details_from_dev_fn can be called + * to get the model name / serial number ID associated with + * the device file name. + * + * The function ::free_dev_fn_list should be called when the + * returned list has been evaliuated and isn't needed anymore. + * + * @param[out] p_list Pointer to a list to be allocated and + * set up, set to NULL if no devices were found. + * @param[in] max_devs Max. number of devices to be added to the list. + * + * @return The number of devices found + * + * @see ::free_dev_fn_list + * @see ::setup_dev_details_from_dev_fn + */ +int setup_dev_fn_list( MBG_DEV_FN_LIST_ENTRY **p_list, int max_devs ) +{ + // The way to retrieve a list of devices currently present + // in the system depends on the operating system. + + #if defined( MBG_TGT_WIN32 ) + + return mbg_svc_find_devices_with_hw_id( p_list, max_devs ); + + #elif defined( MBG_TGT_POSIX ) + + MBG_DEV_FN_LIST_ENTRY *list_head = NULL; + MBG_DEV_FN_LIST_ENTRY *pos = NULL; + int n_dev_fn = 0; + int i; + + for ( i = 0; i < max_devs; i++ ) { - char dev_name[100]; + MBG_DEV_FN dev_fn; MBG_DEV_HANDLE dh; - snprintf_safe( dev_name, sizeof( dev_name ), "/dev/mbgclock%d", i ); - - dh = mbg_open_device_by_hw_id( dev_name ); + mbg_dev_fn_from_dev_idx( dev_fn, sizeof( dev_fn ), i ); + dh = mbg_open_device_by_dev_fn( dev_fn ); if ( dh != MBG_INVALID_DEV_HANDLE ) { - mbg_close_device( &dh ); + size_t sz = strlen( dev_fn ) + 1; // including terminating 0 - (*list)->device_path = (char *) malloc( strlen( dev_name ) + 1 ); - strcpy( (*list)->device_path, dev_name ); + if ( list_head == NULL ) // first turn + { + list_head = (MBG_DEV_FN_LIST_ENTRY *) calloc( 1, sizeof( *list_head ) ); + pos = list_head; + } + else + { + pos->next = (MBG_DEV_FN_LIST_ENTRY *) calloc( 1, sizeof( *pos ) ); + pos = pos->next; + } - (*list)->next = (MBG_DEVICE_LIST *) malloc( sizeof( **list ) ); - (*list) = (*list)->next; + if ( pos == NULL ) + goto out_free; - memset( *list, 0, sizeof( **list ) ); - n++; - } + pos->dev_fn_ptr = (char *) calloc( 1, sz ); - if ( ++i >= N_SUPP_DEV_BUS ) - break; - } + if ( pos->dev_fn_ptr == NULL ) + goto out_free; - if ( n > 0 ) - *list = ListBegin; - else - { - free( *list ); - *list = NULL; + strncpy_safe( pos->dev_fn_ptr, dev_fn, sz ); + n_dev_fn++; + + mbg_close_device( &dh ); + } } - return n; + if ( n_dev_fn ) + goto out; + + +out_free: + free_dev_fn_list( list_head ); + list_head = NULL; + n_dev_fn = 0; + +out: + *p_list = list_head; // Return the list + return n_dev_fn; #else + *p_list = NULL; return 0; #endif -} -#endif +} // setup_dev_fn_list + +#endif // MBG_TGT_HAS_DEV_FN -#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX ) +#if MBG_TGT_HAS_DEV_FN -//### TODO: document this function static /*HDR*/ -void _MBG_API mbg_free_device_list( MBG_DEVICE_LIST *devices ) +/** + * @brief Open a device, retrieve the ::PCPS_DEV info, then close it + * + * @param[out] p Pointer to a ::PCPS_DEV to be filled. + * @param[in] dev_fn The device file name of the device to be used. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ +int get_dev_info_for_dev_fn( PCPS_DEV *p, const char *dev_fn ) { + MBG_DEV_HANDLE dh; + int rc; - #if defined( MBG_TGT_WIN32 ) - mbg_svc_free_device_list( devices ); - #else - int i = 0; - MBG_DEVICE_LIST *Next = NULL; + memset( p, 0, sizeof( *p ) ); - while ( i < N_SUPP_DEV_BUS) - { - if ( devices ) - { - if ( devices->device_path ) - { - free( devices->device_path ); - devices->device_path = NULL; - } + // Try to retrieve device information. + dh = mbg_open_device_by_dev_fn( dev_fn ); - if ( devices->next ) - { - Next = devices->next; - free(devices); - devices = Next; - } - else - { - if ( devices ) - { - free( devices ); - devices = NULL; - } - break; - } - } - else - break; + if ( dh == MBG_INVALID_DEV_HANDLE ) + return mbg_get_last_error( NULL ); - i++; - } + rc = mbg_get_device_info( dh, p ); - #endif -} + mbg_close_device( &dh ); -#endif + return rc; +} // get_dev_info_for_dev_fn +#endif // MBG_TGT_HAS_DEV_FN -#if ( defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX ) ) -//### TODO: document this function + +#if MBG_TGT_HAS_DEV_FN + static /*HDR*/ -void get_hw_name_from_hw_id( MBG_DEVICE_INFO *dev_info ) +/** + * @brief Create a string with a unique device name + * + * The device name is composed of the device's type name and + * its serial number which is appended after an underscore '_'. + * So the string buffer is typically an ::MBG_DEV_NAME. + * + * @param[out] s Pointer to the output buffer for the string. + * @param[in] max_len Size of the output buffer. + * @param[in] p_dev Pointer to a ::PCPS_DEV structure providing the required information. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::MBG_DEV_NAME + */ +int snprint_dev_name( char *s, size_t max_len, const PCPS_DEV *p_dev ) { - MBG_DEV_HANDLE dh; - PCPS_DEV pdev; + size_t n = snprintf_safe( s, max_len, "%s_%s", + _pcps_type_name( p_dev ), _pcps_sernum( p_dev ) ); + return _int_from_size_t( n ); - dh = MBG_INVALID_DEV_HANDLE; - memset( &pdev, 0, sizeof( pdev ) ); +} // snprint_dev_name - // Default initializers - strcpy( dev_info->model_name, str_not_avail ); - strcpy( dev_info->serial_number, str_not_avail ); - strcpy( dev_info->hw_name, str_not_avail ); +#endif // MBG_TGT_HAS_DEV_FN - dh = mbg_open_device_by_hw_id( dev_info->hardware_id ); - if ( dh != MBG_INVALID_DEV_HANDLE ) + +static /*HDR*/ +/** + * @brief Lookup a specific device in an array of ::PCPS_DEV structures + * + * Look for a matching name, if a type name is specified, and for + * a matching serial number if that is also given. + * + * @param[in] dev_array The array of ::PCPS_DEV structures to be searched. + * @param[in] n_dev The number of entries in @p dev_array. + * @param[in] type_name An optional type name to search for, may be NULL. + * @param[in] sernum An optional serial number to search for, may be NULL. + * + * @return An index value >= 0 on success, or -1 if no entry was found + * + * @see ::lookup_dev_idx_ex + */ +int lookup_dev_idx( const PCPS_DEV *dev_array, int n_dev, + const char *type_name, const char *sernum ) +{ + int i; + + for ( i = 0; i < n_dev; i++ ) { - if ( mbg_rc_is_success( mbg_get_device_info( dh, &pdev ) ) ) - { - strcpy( dev_info->model_name, _pcps_type_name( &pdev ) ); - strcpy( dev_info->serial_number, _pcps_sernum( &pdev ) ); - snprintf_safe( dev_info->hw_name, sizeof( dev_info->hw_name ), "%s_%s", - _pcps_type_name( &pdev ), _pcps_sernum( &pdev ) ); - } + const PCPS_DEV *p_dev = &dev_array[i]; + + if ( type_name && strcmp( _pcps_type_name( p_dev ), type_name ) ) + continue; // Type name given, but doesn't match. + + if ( sernum && strcmp( _pcps_sernum( p_dev ), sernum ) ) + continue; // Serial number given, but doesn't match. - mbg_close_device( &dh ); + return i; // Matching device found. } -} // get_hw_name_from_hw_id + return -1; // No matching device found. + +} // lookup_dev_idx + + + +static /*HDR*/ +/** + * @brief Lookup a specific device in an array, depending on a match code + * + * The function first looks for an exact match of type name + * and serial number, then for a matching type name only, if + * @p selection_mode allows, and if no matching devic model + * can be found at all, returns the index of the first device + * found, if an appropriate @p selection_mode has been specified. + * + * @param[in] dev_array The array of ::PCPS_DEV structures to be searched. + * @param[in] n_dev The number of entries in @p dev_array. + * @param[in] type_name An optional type name to search for, may be NULL. + * @param[in] sernum An optional serial number to search for, may be NULL. + * @param[in] selection_mode One of the ::MBG_MATCH_MODES. + * + * @return An index value >= 0 on success, or -1 if no entry was found + * + * @see ::lookup_dev_idx + * @see ::MBG_MATCH_MODES + */ +int lookup_dev_idx_ex( const PCPS_DEV *dev_array, int n_dev, + const char *type_name, const char *sernum, + int selection_mode ) +{ + int dev_idx = -1; + + if ( n_dev == 0 ) // no devices available + goto out; + + dev_idx = lookup_dev_idx( dev_array, n_dev, type_name, sernum ); + + if ( dev_idx >= 0 ) + goto out; + + + // The requested combination of a clock model name and + // serial number was not found. If an exact match was + // requested then we're done anyway. + if ( selection_mode == MBG_MATCH_EXACTLY ) + goto out; -#endif + + // Look for device with matching name only, ignoring + // the serial number. + dev_idx = lookup_dev_idx( dev_array, n_dev, type_name, NULL ); + + if ( dev_idx >= 0 ) + goto out; + + + // As a last resort select the first device that + // has been found, if the selection mode allows. + if ( selection_mode == MBG_MATCH_ANY ) + dev_idx = 0; + +out: + return dev_idx; + +} // lookup_dev_idx_ex /*HDR*/ /** - * @brief Allocate memory and set up a list of installed and supported devices. + * @brief Allocate memory and set up a list of installed and supported devices * - * This function should be used preferably instead of ::mbg_find_devices. + * Allocate and fill a list with the names of Meinberg devices currently + * present in the system. * - * @param[in] device_list Pointer to a linked list of type ::MBG_DEVICENAME_LIST - * with device names. The list will be allocated by this - * function and has to be freed after usage by calling - * ::mbg_free_device_name_list. - * @param[in] max_devices Maximum number of devices the function should look for + * This can be used e.g. to populate a device selection dialog + * in a configuration program. + * + * When the list is not used anymore it can be freed by calling + * ::mbg_free_device_name_list. + * + * @param[in] p_list Pointer to a linked list to be allocated. + * @param[in] max_devices Maximum number of devices to be searched for * (must not exceed ::N_SUPP_DEV_BUS). * - * @return number of present devices + * @return The 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 + * @see ::MBG_DEV_NAME */ -_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_DEV_NAME_LIST_ENTRY **p_list, int max_devices ) { -#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX ) +#if MBG_TGT_HAS_DEV_FN - MBG_DEVICE_LIST *hardware_list = NULL; - MBG_DEVICE_LIST *hardware_list_begin = NULL; - MBG_DEVICENAME_LIST *ListBegin = NULL; - MBG_DEVICE_INFO dev_info; + MBG_DEV_FN_LIST_ENTRY *dev_fn_list_head = NULL; + MBG_DEV_FN_LIST_ENTRY *dev_fn_pos = NULL; - int n_devices = 0; - int i = 0; + MBG_DEV_NAME_LIST_ENTRY *list_head = NULL; + MBG_DEV_NAME_LIST_ENTRY *pos = NULL; - n_devices = mbg_find_devices_with_hw_id( &hardware_list, max_devices ); + int n_dev_fn = 0; + int n_dev_name = 0; - hardware_list_begin = hardware_list; + // First set up a list of device names, the format of which + // depends on the OS. + n_dev_fn = setup_dev_fn_list( &dev_fn_list_head, max_devices ); - if ( n_devices ) + // Now iterate through the device *file name* list + // and set up a *device name* list. + for ( dev_fn_pos = dev_fn_list_head; dev_fn_pos; dev_fn_pos = dev_fn_pos->next ) { - *device_list = (MBG_DEVICENAME_LIST *) malloc( sizeof( MBG_DEVICENAME_LIST ) ); - (*device_list)->next = NULL; - - // Save begin of the list - ListBegin = *device_list; + PCPS_DEV dev; + int rc; - // Loop through the list of hardware_ids and get their readable names - for (;;) + if ( list_head == NULL ) // first turn { - if ( hardware_list->device_path && i++ < N_SUPP_DEV_BUS ) - { - strcpy( dev_info.hardware_id, hardware_list->device_path ); + list_head = (MBG_DEV_NAME_LIST_ENTRY *) calloc( 1, sizeof( *list_head ) ); + pos = list_head; + } + else + { + pos->next = (MBG_DEV_NAME_LIST_ENTRY *) calloc( 1, sizeof( *pos ) ); + pos = pos->next; + } - get_hw_name_from_hw_id( &dev_info ); + if ( pos == NULL ) // failed to allocate memory + { + mbg_free_device_name_list( list_head ); // free this list + list_head = NULL; + n_dev_name = 0; + break; + } - strcpy( (*device_list)->device_name, dev_info.hw_name ); + // Get device details for the device. + rc = get_dev_info_for_dev_fn( &dev, dev_fn_pos->dev_fn_ptr ); - if ( hardware_list->next ) - { - hardware_list = hardware_list->next; - (*device_list)->next = (MBG_DEVICENAME_LIST *) malloc( sizeof( MBG_DEVICENAME_LIST ) ); - (*device_list) = (*device_list)->next; - (*device_list)->next = NULL; - } - else - break; - } - else - break; - } + if ( mbg_rc_is_success( rc ) ) + snprint_dev_name( pos->dev_name, sizeof( pos->dev_name ), + &dev ); - *device_list = ListBegin; + if ( ++n_dev_name > n_dev_fn ) // This should never happen + break; } - if ( hardware_list_begin ) - mbg_free_device_list( hardware_list_begin ); + // Free the device name list which we don't need anymore + free_dev_fn_list( dev_fn_list_head ); + + *p_list = list_head; // Return the list - return n_devices; + return n_dev_name; #else + *p_list = NULL; return 0; #endif @@ -3575,223 +3892,163 @@ _MBG_API_ATTR int _MBG_API mbg_find_devices_with_names( MBG_DEVICENAME_LIST **de /*HDR*/ /** - * @brief Free the memory allocated for a ::MBG_DEVICENAME_LIST. + * @brief Free the memory allocated for a list of ::MBG_DEV_NAME_LIST_ENTRY entries. * * The list may have been set up and allocated before * by ::mbg_find_devices_with_names. * - * @param[in,out] list Linked list of type ::MBG_DEVICENAME_LIST + * @param[in,out] list Linked list of ::MBG_DEV_NAME_LIST_ENTRY entries. * * @see ::mbg_find_devices_with_names */ -_MBG_API_ATTR void _MBG_API mbg_free_device_name_list( MBG_DEVICENAME_LIST *list) +_MBG_API_ATTR void _MBG_API mbg_free_device_name_list( MBG_DEV_NAME_LIST_ENTRY *list ) { -#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX ) - - MBG_DEVICENAME_LIST *Next = NULL; - int i = 0; - - // Deallocate members of linked list - while ( i < N_SUPP_DEV_BUS ) + while ( list ) { - if ( list ) - { - Next = list->next; - - free( list ); - list = NULL; - - if ( Next ) - list = Next->next; - else - break; - } - else - break; + MBG_DEV_NAME_LIST_ENTRY *next = list->next; - i++; + free( list ); + list = next; } -#else - // TODO: This needs to be handled -#endif -} // mbg_free_device_list +} // mbg_free_device_name_list /*HDR*/ /** - * @brief Return a handle to a device with a certain unique name. + * @brief Return a handle to a device with a particular device name * - * The names of the devices that are installed on the system can be retrieved by - * the function ::mbg_find_devices_with_names. + * See ::MBG_DEV_NAME for the possible formats of a device name. * - * This function should be used preferably instead of ::mbg_open_device. + * For details and similar functions see @ref mbgdevio_open_fncs. * - * @param[in] srch_name String with the unique name of the device to be opened - * @param[in] selection_mode One of the enum values of ::MBG_MATCH_MODE + * @param[in] srch_name String with the ::MBG_DEV_NAME of a device to be opened + * @param[in] selection_mode One of the ::MBG_MATCH_MODES * - * @return On success, the function returns a handle to the device, otherwise ::MBG_INVALID_DEV_HANDLE + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE * - * @see ::MBG_HW_NAME for the format of the unique names - * @see ::MBG_MATCH_MODE - * @see ::mbg_find_devices_with_names + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs + * @see ::MBG_DEV_NAME + * @see ::MBG_MATCH_MODES */ -_MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const char *srch_name, int selection_mode ) //##++++ +_MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const char *srch_name, int selection_mode ) { - //### TODO: FIXME for MBG_TGT_QNX_NTO - -#if ( ( defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX ) ) ) && ! defined( MBG_TGT_QNX_NTO ) - - static MBG_DEVICE_INFO device_info_list[N_SUPP_DEV_BUS]; - - MBG_DEV_HANDLE dh; - - MBG_DEVICE_LIST *devices = NULL; - MBG_DEVICE_LIST *ListBegin = NULL; - char hw_id[MAX_INFO_LEN]; - char tmp_model_name[PCPS_CLOCK_NAME_SZ] = { 0 }; - PCPS_SN_STR tmp_sn; // = { 0 }; //##++++ TODO check what this should be used for - int n_devices = 0; - size_t srch_name_len = srch_name ? strlen( srch_name ) : 0; + PCPS_DEV dev_array[N_SUPP_DEV_BUS] = { { { 0 } } }; + PCPS_CLOCK_NAME type_name = { 0 }; + PCPS_SN_STR sernum = { 0 }; + size_t srch_name_len = 0; size_t i = 0; - size_t j = 0; - hw_id[0] = '\0'; + const char *cp; + char c; + int dev_idx = -1; - memset( device_info_list, 0, sizeof( device_info_list ) ); - memset( tmp_sn, 0, sizeof( tmp_sn ) ); + if ( srch_name ) + srch_name_len = strlen( srch_name ); - // separate hw_name into clock model and serial number - if ( srch_name && ( srch_name_len > 0 ) ) + if ( srch_name_len ) { - // clock model - for ( i = 0; ( i < PCPS_CLOCK_NAME_SZ ) && ( srch_name[i] != '_' ) && ( i < srch_name_len ); i++ ) - { - char c = srch_name[i]; - // convert ASCII lower case characters to upper case - tmp_model_name[i] = ( c >= 'a' && c <= 'z' ) ? ( c - 0x20 ) : c; - } - - tmp_model_name[sizeof( tmp_model_name ) - 1] = 0; - i++; + // clock model name + cp = srch_name; + i = 0; - // serial number - if ( i < srch_name_len ) + for (;;) { - j = 0; + c = *cp++; - while ( ( i < srch_name_len ) && ( j < PCPS_SN_SIZE ) ) - { - tmp_sn[j] = srch_name[i]; - j++; - i++; - } - tmp_sn[j] = '\0'; - } - } - else - goto fail; + if ( c == 0 ) // end of string + break; - i = 0; + if ( c == '_' ) // separator before S/N + break; - // get OS-dependent hardware_id strings for devices that are present on the system - n_devices = mbg_find_devices_with_hw_id( &devices, N_SUPP_DEV_BUS ); + type_name[i] = ( c >= 'a' && c <= 'z' ) ? ( c - 0x20 ) : c; - ListBegin = devices; + if ( ++i >= ( sizeof( type_name ) - 1 ) ) + break; + } - if ( n_devices ) - { - for (;;) + type_name[i] = 0; // terminate string + + if ( c == '_' ) { - if ( devices->device_path && i < N_SUPP_DEV_BUS ) - { - strncpy( device_info_list[i].hardware_id, devices->device_path, MAX_INFO_LEN ); + // Serial number + i = 0; - // get readable hw_name for the device - get_hw_name_from_hw_id( &device_info_list[i] ); + for (;;) + { + c = *cp++; - if ( srch_name && strcmp( device_info_list[i].hw_name, srch_name ) == 0 ) - { - // The requested device was found - strcpy( hw_id, device_info_list[i].hardware_id ); + if ( c == 0 ) // end of string break; - } - else if ( devices->next ) - devices = devices->next; - else + + if ( c < '0' || c > '9' ) // not a digit break; - } - else - break; - i++; - } + sernum[i] = c; - // If the requested CLOCK_MODEL/SN combination was not found, - // decide what to do depending on the selection mode - if ( ( hw_id[0] == '\0' ) && ( selection_mode != MBG_MATCH_EXACTLY ) ) - { - for ( j = 0; j <= i; j++ ) - { - // Search for the same clock model - if ( ( tmp_model_name[0] != '\0' ) && strcmp( device_info_list[j].model_name, tmp_model_name ) == 0 ) - { - strcpy( hw_id, device_info_list[j].hardware_id ); + if ( ++i >= ( sizeof( sernum ) - 1 ) ) break; - } } - // Finally select the first device found on the system, if the clock model was not found - if ( ( selection_mode == MBG_MATCH_ANY ) && ( hw_id[0] == '\0' ) ) - strcpy( hw_id, device_info_list[0].hardware_id ); + sernum[i] = 0; // terminate string } } - mbg_free_device_list( ListBegin ); - -#endif - -#if defined( MBG_TGT_WIN32 ) + #if MBG_TGT_HAS_DEV_FN + { + MBG_DEV_FN dev_fn_array[N_SUPP_DEV_BUS] = { { 0 } }; + MBG_DEV_FN_LIST_ENTRY *list_head = NULL; - if ( hw_id[0] == '\0' ) - goto fail; + // Set up a temporary list with file names of devices + // that are currently present in the system. + int n_devices = setup_dev_fn_list( &list_head, N_SUPP_DEV_BUS ); - dh = CreateFileA( - hw_id, // file name - GENERIC_READ | GENERIC_WRITE, // access mode - 0, // share mode - NULL, // security descriptor - OPEN_EXISTING, // how to create - strstr(hw_id,"usb") ? FILE_FLAG_OVERLAPPED : 0, // file attributes - NULL // handle to template file - ); + if ( n_devices ) + { + MBG_DEV_FN_LIST_ENTRY *pos; - if ( INVALID_HANDLE_VALUE == dh ) - goto fail; + for ( i = 0, pos = list_head; pos && pos->dev_fn_ptr; pos = pos->next ) + { + int rc = get_dev_info_for_dev_fn( &dev_array[i], pos->dev_fn_ptr ); - return dh; + if ( mbg_rc_is_success( rc ) ) + { + // Save the associated device file name. + sn_cpy_str_safe( dev_fn_array[i], sizeof( dev_fn_array[i] ), pos->dev_fn_ptr ); + i++; + } + } -fail: - return MBG_INVALID_DEV_HANDLE; + dev_idx = lookup_dev_idx_ex( dev_array, i, type_name, sernum, selection_mode ); + } -#elif defined( MBG_TGT_POSIX ) && !defined( MBG_TGT_QNX_NTO ) + free_dev_fn_list( list_head ); - if ( hw_id[0] != '\0' ) - dh = open( hw_id, O_RDWR ); - else - goto fail; + // We even try to open the device if no match was found. + // This causes an "invalid device handle" value to be + // returned, and sets an appropriate "last error" code. + return mbg_open_device_by_dev_fn( ( dev_idx >= 0 ) ? dev_fn_array[dev_idx] : "" ); + } + #else + #if defined( _PCPSDRVR_H ) + mbg_find_devices(); - return ( dh < 0 ) ? MBG_INVALID_DEV_HANDLE : dh; + for ( i = 0; i < n_ddevs; i++ ) + dev_array[i] = pcps_ddev[i].dev; -fail: - return MBG_INVALID_DEV_HANDLE; + dev_idx = lookup_dev_idx_ex( dev_array, i, type_name, sernum, selection_mode ); -#else + if ( dev_idx >= 0 ) + return mbg_open_device( dev_idx ); + #endif - //return ( device_index < n_ddevs ) ? &pcps_ddev[device_index] : NULL; - return MBG_INVALID_DEV_HANDLE; + errno = ENODEV; + return MBG_INVALID_DEV_HANDLE; -#endif + #endif } // mbg_open_device_by_name @@ -3799,9 +4056,11 @@ fail: /*HDR*/ /** - * @brief Close a handle to a device and set the handle value to ::MBG_INVALID_DEV_HANDLE. + * @brief Close a device handle and set the handle value to ::MBG_INVALID_DEV_HANDLE * * @param[in,out] dev_handle Pointer to a Meinberg device handle + * + * @see @ref mbgdevio_open_fncs */ _MBG_API_ATTR void _MBG_API mbg_close_device( MBG_DEV_HANDLE *dev_handle ) { @@ -3825,20 +4084,18 @@ _MBG_API_ATTR void _MBG_API mbg_close_device( MBG_DEV_HANDLE *dev_handle ) * @brief Read information about the driver handling a given device * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] *p A ::PCPS_DRVR_INFO structure to be filled up. + * @param[out] p A ::PCPS_DRVR_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES */ _MBG_API_ATTR int _MBG_API mbg_get_drvr_info( MBG_DEV_HANDLE dh, PCPS_DRVR_INFO *p ) { #if defined( _MBGIOCTL_H ) - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_PCPS_DRVR_INFO, p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); #else - #if defined( __BORLANDC__ ) - dh; // avoid warnings "never used" - #endif + (void) dh; // avoid warning "never used" drvr_info.n_devs = n_ddevs; *p = drvr_info; return MBG_SUCCESS; @@ -3852,18 +4109,18 @@ _MBG_API_ATTR int _MBG_API mbg_get_drvr_info( MBG_DEV_HANDLE dh, PCPS_DRVR_INFO /** * @brief Read detailed device information * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] *p A ::PCPS_DEV structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES */ _MBG_API_ATTR int _MBG_API mbg_get_device_info( MBG_DEV_HANDLE dh, PCPS_DEV *p ) { #if defined( _MBGIOCTL_H ) - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_PCPS_DEV, p ); // Endianess is converted inside the kernel driver, if necessary. - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); #else *p = dh->dev; return MBG_SUCCESS; @@ -3881,20 +4138,20 @@ _MBG_API_ATTR int _MBG_API mbg_get_device_info( MBG_DEV_HANDLE dh, PCPS_DEV *p ) * also includes the ::PCPS_ST_MOD bit reflecting the time code * modulation of long wave receivers. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] *p A ::PCPS_STATUS_PORT value to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p A ::PCPS_STATUS_PORT value to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see @ref group_status_port "bitmask" //### TODO check syntax */ _MBG_API_ATTR int _MBG_API mbg_get_status_port( MBG_DEV_HANDLE dh, PCPS_STATUS_PORT *p ) { #if defined( _MBGIOCTL_H ) - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_PCPS_STATUS_PORT, p ); // No endianess conversion required. - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); #else *p = _pcps_ddev_read_status_port( dh ); // No endianess conversion required. @@ -3919,7 +4176,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_status_port( MBG_DEV_HANDLE dh, PCPS_STATUS_P * @param[out] p Pointer to a buffer to be filled up * @param[in] size Size of the output buffer * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_generic_write * @see ::mbg_generic_read_gps @@ -3929,11 +4186,11 @@ _MBG_API_ATTR int _MBG_API mbg_get_status_port( MBG_DEV_HANDLE dh, PCPS_STATUS_P _MBG_API_ATTR int _MBG_API mbg_generic_read( MBG_DEV_HANDLE dh, int cmd, void *p, int size ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_gen_read( dh, cmd, p, size ); // No type information available, so endianess has to be // converted by the caller, if required. - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_generic_read @@ -3955,7 +4212,7 @@ _MBG_API_ATTR int _MBG_API mbg_generic_read( MBG_DEV_HANDLE dh, int cmd, * @param[out] p Pointer to a buffer to be filled up * @param[in] size Size of the buffer, has to match the expected data size associated with cmd * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_chk_dev_has_gps_data * @see ::mbg_generic_write_gps @@ -3966,11 +4223,11 @@ _MBG_API_ATTR int _MBG_API mbg_generic_read( MBG_DEV_HANDLE dh, int cmd, _MBG_API_ATTR int _MBG_API mbg_generic_read_gps( MBG_DEV_HANDLE dh, int cmd, void *p, int size ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_gen_read_gps( dh, cmd, p, size ); // No type information available, so endianess has to be // converted by the caller, if required. - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_generic_read_gps @@ -3990,7 +4247,7 @@ _MBG_API_ATTR int _MBG_API mbg_generic_read_gps( MBG_DEV_HANDLE dh, int cmd, * @param[in] p Pointer to a buffer of data to be written * @param[in] size Size of the buffer, has to match the expected data size associated with cmd * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_generic_read * @see ::mbg_generic_read_gps @@ -4000,11 +4257,11 @@ _MBG_API_ATTR int _MBG_API mbg_generic_read_gps( MBG_DEV_HANDLE dh, int cmd, _MBG_API_ATTR int _MBG_API mbg_generic_write( MBG_DEV_HANDLE dh, int cmd, const void *p, int size ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; // No type information available, so endianess has to be // converted by the caller, if required. rc = _mbgdevio_gen_write( dh, cmd, p, size ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_generic_write @@ -4026,7 +4283,7 @@ _MBG_API_ATTR int _MBG_API mbg_generic_write( MBG_DEV_HANDLE dh, int cmd, * @param[in] p Pointer to a buffer of data to be written * @param[in] size Size of the buffer, has to match the expected data size associated with cmd * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_chk_dev_has_gps_data * @see ::mbg_generic_read_gps @@ -4037,11 +4294,11 @@ _MBG_API_ATTR int _MBG_API mbg_generic_write( MBG_DEV_HANDLE dh, int cmd, _MBG_API_ATTR int _MBG_API mbg_generic_write_gps( MBG_DEV_HANDLE dh, int cmd, const void *p, int size ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; // No type information available, so endianess has to be // converted by the caller, if required. rc = _mbgdevio_gen_write_gps( dh, cmd, p, size ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_generic_write_gps @@ -4055,9 +4312,9 @@ _MBG_API_ATTR int _MBG_API mbg_generic_write_gps( MBG_DEV_HANDLE dh, int cmd, * * <b>Warning</b>: This call is for debugging purposes and internal use only! * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_generic_io + * @see ::mbg_chk_dev_has_generic_io * @see ::mbg_generic_read * @see ::mbg_generic_write * @see ::mbg_generic_read_gps @@ -4067,7 +4324,7 @@ _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 ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if !defined( _MBGIOCTL_H ) // The hardware is accessed directly, so we must check @@ -4078,7 +4335,7 @@ _MBG_API_ATTR int _MBG_API mbg_generic_io( MBG_DEV_HANDLE dh, int type, // No type information available, so endianess must be // converted by the caller, if required. rc = _mbgdevio_gen_io( dh, type, in_p, in_sz, out_p, out_sz ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_generic_io @@ -4086,31 +4343,32 @@ _MBG_API_ATTR int _MBG_API mbg_generic_io( MBG_DEV_HANDLE dh, int type, /*HDR*/ /** - * @brief Read a ::PCPS_TIME structure returning the current date/time/status. + * @brief Read a ::PCPS_TIME structure returning the current date/time/status * * The returned time is local time according to the card's time zone setting, - * with a resolution of 10 ms (i.e. 10ths of seconds). + * with a resolution of 10 ms (i.e. 10ths of seconds) only. * * This call is supported by any device manufactured by Meinberg. - * However, for higher accuracy and resolution the @ref pcps_hr_time_fncs or - * the @ref pcps_fast_timestamp_fncs group of calls should be used preferably, + * However, for higher accuracy and resolution the @ref mbgdevio_hr_time_fncs or + * the @ref mbgdevio_fast_timestamp_fncs group of calls should be used preferably, * if supported by the device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_legacy_time_fncs * @see ::mbg_get_hr_time * @see ::mbg_set_time * @see ::mbg_get_sync_time */ _MBG_API_ATTR int _MBG_API mbg_get_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, PCPS_GIVE_TIME, IOCTL_GET_PCPS_TIME, p ); // No endianess conversion required. - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_time @@ -4120,25 +4378,25 @@ _MBG_API_ATTR int _MBG_API mbg_get_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) /** * @brief Set the device's on-board clock to a given date and time. * - * The macro ::_pcps_can_set_time checks whether this call - * is supported by a device. + * The macro ::_pcps_can_set_time checks whether + * this call is supported by a device. * * @todo Provide an API function replacing ::_pcps_can_set_time. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::PCPS_STIME structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_time */ _MBG_API_ATTR int _MBG_API mbg_set_time( MBG_DEV_HANDLE dh, const PCPS_STIME *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; // No endianess conversion required. _mbgdevio_write_var_chk( dh, PCPS_SET_TIME, IOCTL_SET_PCPS_TIME, p, _pcps_ddev_can_set_time( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_time @@ -4146,36 +4404,36 @@ _MBG_API_ATTR int _MBG_API mbg_set_time( MBG_DEV_HANDLE dh, const PCPS_STIME *p /*HDR*/ /** - * @brief Read the time when the device has last recently synchronized. + * @brief Read the time when the device has last recently synchronized * - * Fills a ::PCPS_TIME structure with the date/time/status reporting - * when the device was synchronized the last time to its time source, - * e.g. the DCF77 signal, the GPS satellites, or similar. + * Fills a ::PCPS_TIME structure with the date/time/status reporting + * when the device was synchronized the last time to its time source, + * e.g. the DCF77 signal, the GPS satellites, or similar. * - * The macro ::_pcps_has_sync_time checks whether this call - * is supported by a device. + * The macro ::_pcps_has_sync_time checks whether + * this call is supported by a device. * - * <b>Note:</b> If that information is not available on the board then - * the value of the returned ::PCPS_TIME::sec field is set to 0xFF. - * The macro ::_pcps_time_is_read can be used to check whether the - * returned information is valid, or "not set". + * <b>Note:</b> If that information is not available on the board then + * the value of the returned ::PCPS_TIME::sec field is set to 0xFF. + * The macro ::_pcps_time_is_read can be used to check whether the + * returned information is valid, or "not set". * * @todo Provide an API function replacing ::_pcps_has_sync_time. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_time */ _MBG_API_ATTR int _MBG_API mbg_get_sync_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_GIVE_SYNC_TIME, IOCTL_GET_PCPS_SYNC_TIME, p, _pcps_ddev_has_sync_time( dh ) ); // No endianess conversion required. - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_sync_time @@ -4183,7 +4441,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_sync_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) /*HDR*/ /** - * @brief Wait until the next second change, then return current time. + * @brief Wait until the next second change, then return current time * * Returns time in a ::PCPS_TIME structure similar to ::mbg_get_time. * @@ -4195,21 +4453,21 @@ _MBG_API_ATTR int _MBG_API mbg_get_sync_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_legacy_time_fncs * @see ::mbg_get_time */ _MBG_API_ATTR int _MBG_API mbg_get_time_sec_change( MBG_DEV_HANDLE dh, PCPS_TIME *p ) { #if defined( MBG_TGT_WIN32 ) - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_PCPS_TIME_SEC_CHANGE, p ); // No endianess conversion required. - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); #else - #if defined( __BORLANDC__ ) - dh; p; // avoid warnings "never used" - #endif + (void) dh; // avoid warning "never used" + (void) p; // avoid warning "never used" return MBG_ERR_NOT_SUPP_ON_OS; #endif @@ -4219,33 +4477,33 @@ _MBG_API_ATTR int _MBG_API mbg_get_time_sec_change( MBG_DEV_HANDLE dh, PCPS_TIME /*HDR*/ /** - * @brief Read the card's current time with high resolution, plus status. + * @brief Read the card's current time with high resolution, including status * * Fills up a ::PCPS_HR_TIME (High Resolution time) structure containing * the current %UTC time (seconds since 1970), %UTC offset, and status. * - * The API call ::mbg_chk_dev_has_hr_time checks whether this call - * is supported by the device. + * The API call ::mbg_chk_dev_has_hr_time checks whether + * this call is supported by a device. * - * For details see @ref ::pcps_hr_time_fncs + * For details see @ref ::mbgdevio_hr_time_fncs * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_HR_TIME structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @ingroup pcps_hr_time_fncs - * @see @ref pcps_hr_time_fncs - * @see @ref pcps_fast_timestamp_fncs - * @see @ref pcps_std_time_fncs + * @ingroup mbgdevio_hr_time_fncs + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs */ _MBG_API_ATTR int _MBG_API mbg_get_hr_time( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_GIVE_HR_TIME, IOCTL_GET_PCPS_HR_TIME, p, _pcps_ddev_has_hr_time( dh ) ); _mbg_swab_pcps_hr_time( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_hr_time @@ -4253,23 +4511,23 @@ _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 a device - to configure a %UTC time when the clock shall generate an event. - The macro _pcps_has_event_time() or the API call mbg_dev_has_event_time() - check whether this call is supported by a device. - - <b>Note:</b> This is only supported by some special firmware. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_STAMP structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * Write a high resolution time stamp ::PCPS_TIME_STAMP to a device + * to configure a %UTC time when the clock shall generate an event. + * The API call ::mbg_chk_dev_has_event_time checks whether + * this call is supported by a device. + * + * <b>Note:</b> This is only supported by some special firmware. * - * @see ::mbg_dev_has_event_time + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PCPS_TIME_STAMP structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_event_time */ _MBG_API_ATTR int _MBG_API mbg_set_event_time( MBG_DEV_HANDLE dh, const PCPS_TIME_STAMP *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) PCPS_TIME_STAMP tmp = *p; _mbg_swab_pcps_time_stamp( &tmp ); @@ -4277,7 +4535,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_event_time( MBG_DEV_HANDLE dh, const PCPS_TIM #endif _mbgdevio_write_var_chk( dh, PCPS_SET_EVENT_TIME, IOCTL_SET_PCPS_EVENT_TIME, p, _pcps_ddev_has_event_time( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_event_time @@ -4291,22 +4549,22 @@ _MBG_API_ATTR int _MBG_API mbg_set_event_time( MBG_DEV_HANDLE dh, const PCPS_TIM * 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. + * The macro ::_pcps_has_serial checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_SERIAL structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_serial_settings */ _MBG_API_ATTR int _MBG_API mbg_get_serial( MBG_DEV_HANDLE dh, PCPS_SERIAL *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, PCPS_GET_SERIAL, IOCTL_GET_PCPS_SERIAL, p ); // No endianess conversion required. - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_serial @@ -4320,22 +4578,22 @@ _MBG_API_ATTR int _MBG_API mbg_get_serial( MBG_DEV_HANDLE dh, PCPS_SERIAL *p ) * 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. + * The macro ::_pcps_has_serial checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::PCPS_SERIAL structure to be written * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_save_serial_settings */ _MBG_API_ATTR int _MBG_API mbg_set_serial( MBG_DEV_HANDLE dh, const PCPS_SERIAL *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; // No endianess conversion required. rc = _mbgdevio_write_var( dh, PCPS_SET_SERIAL, IOCTL_SET_PCPS_SERIAL, p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_serial @@ -4344,34 +4602,34 @@ _MBG_API_ATTR int _MBG_API mbg_set_serial( MBG_DEV_HANDLE dh, const PCPS_SERIAL /*HDR*/ /** * @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 - time zone and daylight saving settings. - + * + * The APIs using ::TZCODE are only supported by some simpler cards + * and allow just a very basic configuration. + * + * The API call ::mbg_chk_dev_has_tzcode checks whether + * this call is supported by a device. + * + * Other devices may support the ::mbg_get_pcps_tzdl or ::mbg_get_gps_tzdl + * calls instead which allow for a more detailed configuration of the + * time zone and daylight saving settings. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TZCODE structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::PCPS_TZCODE structure to be filled up. * - * @see ::mbg_dev_has_tzcode + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_tzcode * @see ::mbg_set_tzcode * @see ::mbg_get_pcps_tzdl * @see ::mbg_get_gps_tzdl */ _MBG_API_ATTR int _MBG_API mbg_get_tzcode( MBG_DEV_HANDLE dh, PCPS_TZCODE *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_GET_TZCODE, IOCTL_GET_PCPS_TZCODE, p, _pcps_ddev_has_tzcode( dh ) ); // No endianess conversion required. - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_tzcode @@ -4380,34 +4638,34 @@ _MBG_API_ATTR int _MBG_API mbg_get_tzcode( MBG_DEV_HANDLE dh, PCPS_TZCODE *p ) /*HDR*/ /** * @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 - time zone and daylight saving settings. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TZCODE structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES * - * @see ::mbg_dev_has_tzcode + * The APIs using ::TZCODE are only supported by some simpler cards + * and allow just a very basic configuration. + * + * The API call ::mbg_chk_dev_has_tzcode checks whether + * this call is supported by a device. + * + * Other devices may support the ::mbg_set_pcps_tzdl or ::mbg_set_gps_tzdl + * calls instead which allow for a more detailed configuration of the + * time zone and daylight saving settings. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PCPS_TZCODE structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_tzcode * @see ::mbg_get_tzcode * @see ::mbg_set_pcps_tzdl * @see ::mbg_set_gps_tzdl */ _MBG_API_ATTR int _MBG_API mbg_set_tzcode( MBG_DEV_HANDLE dh, const PCPS_TZCODE *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; // No endianess conversion required. _mbgdevio_write_var_chk( dh, PCPS_SET_TZCODE, IOCTL_SET_PCPS_TZCODE, p, _pcps_ddev_has_tzcode( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_tzcode @@ -4416,34 +4674,34 @@ _MBG_API_ATTR int _MBG_API mbg_set_tzcode( MBG_DEV_HANDLE dh, const PCPS_TZCODE /*HDR*/ /** * @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. - + * + * This function fills up a ::PCPS_TZDL structure which supports a more + * detailed configuration of time zone and daylight saving than the ::TZCODE + * structure. + * + * The API call ::mbg_chk_dev_has_pcps_tzdl checks whether + * this call is supported by a device. + * + * Other devices may support the ::mbg_get_tzcode or ::mbg_get_gps_tzdl + * calls instead. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TZDL structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_pcps_tzdl + * @param[out] p Pointer to a ::PCPS_TZDL structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_pcps_tzdl * @see ::mbg_set_pcps_tzdl * @see ::mbg_get_tzcode * @see ::mbg_get_gps_tzdl - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_pcps_tzdl( MBG_DEV_HANDLE dh, PCPS_TZDL *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_GET_PCPS_TZDL, IOCTL_GET_PCPS_TZDL, p, _pcps_ddev_has_pcps_tzdl( dh ) ); _mbg_swab_pcps_tzdl( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_pcps_tzdl @@ -4452,29 +4710,29 @@ _MBG_API_ATTR int _MBG_API mbg_get_pcps_tzdl( MBG_DEV_HANDLE dh, PCPS_TZDL *p ) /*HDR*/ /** * @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[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TZDL structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_pcps_tzdl + * + * This function passes a ::PCPS_TZDL structure to a device which supports + * a more detailed configuration of time zone and daylight saving than the + * ::TZCODE structure. + * + * The API call ::mbg_chk_dev_has_pcps_tzdl checks whether + * this call is supported by a device. + * Other cards may support the ::mbg_set_tzcode or ::mbg_set_gps_tzdl + * calls instead. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PCPS_TZDL structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_pcps_tzdl * @see ::mbg_get_pcps_tzdl * @see ::mbg_set_tzcode * @see ::mbg_set_gps_tzdl - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_pcps_tzdl( MBG_DEV_HANDLE dh, const PCPS_TZDL *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) PCPS_TZDL tmp = *p; _mbg_swab_pcps_tzdl( &tmp ); @@ -4482,7 +4740,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_pcps_tzdl( MBG_DEV_HANDLE dh, const PCPS_TZDL #endif _mbgdevio_write_var_chk( dh, PCPS_SET_PCPS_TZDL, IOCTL_SET_PCPS_TZDL, p, _pcps_ddev_has_pcps_tzdl( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_pcps_tzdl @@ -4490,30 +4748,30 @@ _MBG_API_ATTR int _MBG_API mbg_set_pcps_tzdl( MBG_DEV_HANDLE dh, const PCPS_TZDL /*HDR*/ /** - * @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. - + * @brief Read the %UTC offset configuration of the reference time from a device + * + * This parameter is used to specify the %UTC offset of an incoming + * reference time signal if a kind of time signal e.g. an IRIG input + * signal) does not provide this information. + * + * The API call ::mbg_chk_dev_has_ref_offs checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_REF_OFFS value to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ref_offs + * @param[out] p Pointer to a ::MBG_REF_OFFS value to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ref_offs * @see ::mbg_set_ref_offs - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ref_offs( MBG_DEV_HANDLE dh, MBG_REF_OFFS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_GET_REF_OFFS, IOCTL_GET_REF_OFFS, p, _pcps_ddev_has_ref_offs( dh ) ); _mbg_swab_mbg_ref_offs( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_ref_offs @@ -4522,25 +4780,25 @@ _MBG_API_ATTR int _MBG_API mbg_get_ref_offs( MBG_DEV_HANDLE dh, MBG_REF_OFFS *p /*HDR*/ /** * @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[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_REF_OFFS value to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ref_offs + * + * This parameter is used to specify the %UTC offset of an incoming + * reference time signal if a kind of time signal e.g. an IRIG input + * signal) does not provide this information. + * + * The API call ::mbg_chk_dev_has_ref_offs checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::MBG_REF_OFFS value to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ref_offs * @see ::mbg_get_ref_offs - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_ref_offs( MBG_DEV_HANDLE dh, const MBG_REF_OFFS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) MBG_REF_OFFS tmp = *p; _mbg_swab_mbg_ref_offs( &tmp ); @@ -4548,7 +4806,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_ref_offs( MBG_DEV_HANDLE dh, const MBG_REF_OF #endif _mbgdevio_write_var_chk( dh, PCPS_SET_REF_OFFS, IOCTL_SET_REF_OFFS, p, _pcps_ddev_has_ref_offs( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_ref_offs @@ -4556,28 +4814,29 @@ _MBG_API_ATTR int _MBG_API mbg_set_ref_offs( MBG_DEV_HANDLE dh, const MBG_REF_OF /*HDR*/ /** - * @brief Read a ::MBG_OPT_INFO structure containing optional settings, controlled by flags. - - The ::MBG_OPT_INFO structure contains a mask of supported flags plus the current - settings of those flags. - The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags() - check whether this call is supported by a device. - + * @brief Read a ::MBG_OPT_INFO structure containing optional settings, controlled by flags + * + * The ::MBG_OPT_INFO structure contains a mask of supported flags plus the current + * settings of those flags. + * + * The API call ::mbg_chk_dev_has_opt_flags checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_OPT_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_opt_flags + * @param[out] p Pointer to a ::MBG_OPT_INFO structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_opt_flags * @see ::mbg_set_opt_settings - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_opt_info( MBG_DEV_HANDLE dh, MBG_OPT_INFO *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_GET_OPT_INFO, IOCTL_GET_MBG_OPT_INFO, p, _pcps_ddev_has_opt_flags( dh ) ); _mbg_swab_mbg_opt_info( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_opt_info @@ -4586,23 +4845,24 @@ _MBG_API_ATTR int _MBG_API mbg_get_opt_info( MBG_DEV_HANDLE dh, MBG_OPT_INFO *p /*HDR*/ /** * @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. - + * + * The API call ::mbg_chk_dev_has_opt_flags checks whether + * this call is supported by a device. + * + * ::mbg_get_opt_info should be called first to check which of + * the specified flags is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_OPT_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_opt_flags + * @param[out] p Pointer to a ::MBG_OPT_SETTINGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_opt_flags * @see ::mbg_get_opt_info - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_opt_settings( MBG_DEV_HANDLE dh, const MBG_OPT_SETTINGS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) MBG_OPT_SETTINGS tmp = *p; _mbg_swab_mbg_opt_settings( &tmp ); @@ -4611,7 +4871,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_opt_settings( MBG_DEV_HANDLE dh, const MBG_OP _mbgdevio_write_var_chk( dh, PCPS_SET_OPT_SETTINGS, IOCTL_SET_MBG_OPT_SETTINGS, p, _pcps_ddev_has_opt_flags( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_opt_settings @@ -4625,28 +4885,28 @@ _MBG_API_ATTR int _MBG_API mbg_set_opt_settings( MBG_DEV_HANDLE dh, const MBG_OP * ::mbg_get_all_irig_rx_info should be used instead which also reads some * other associated parameters affecting the behaviour of the IRIG input. * - * The API call ::mbg_dev_is_irig_rx checks whether this call is supported - * by a device. + * The API call ::mbg_chk_dev_is_tcr checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] *p An ::IRIG_INFO structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_all_irig_rx_info * @see ::mbg_set_irig_rx_settings - * @see ::mbg_dev_is_irig_rx - * @see ::mbg_dev_has_irig_tx - * @see ::mbg_dev_has_irig + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_has_irig * @see @ref group_icode */ _MBG_API_ATTR int _MBG_API mbg_get_irig_rx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_GET_IRIG_RX_INFO, IOCTL_GET_PCPS_IRIG_RX_INFO, p, _pcps_ddev_is_irig_rx( dh ) ); _mbg_swab_irig_info( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_irig_rx_info @@ -4660,25 +4920,26 @@ _MBG_API_ATTR int _MBG_API mbg_get_irig_rx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p * ::mbg_save_all_irig_rx_settings should be used instead which also writes some * other associated parameters affecting the behaviour of the IRIG input. * - * The API call ::mbg_dev_is_irig_rx checks whether this call is supported - * by a device. The ::IRIG_INFO structure should be read first to determine + * The API call ::mbg_chk_dev_is_tcr checks whether + * this call is supported by a device. + * ::mbg_get_irig_rx_info should be called first to determine * the possible settings supported by the device's IRIG input. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] p Pointer to a ::IRIG_SETTINGS structure to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::IRIG_SETTINGS structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_save_all_irig_rx_settings * @see ::mbg_get_irig_rx_info - * @see ::mbg_dev_is_irig_rx - * @see ::mbg_dev_has_irig_tx - * @see ::mbg_dev_has_irig + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_has_irig * @see @ref group_icode */ _MBG_API_ATTR int _MBG_API mbg_set_irig_rx_settings( MBG_DEV_HANDLE dh, const IRIG_SETTINGS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) IRIG_SETTINGS tmp = *p; _mbg_swab_irig_settings( &tmp ); @@ -4687,7 +4948,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_irig_rx_settings( MBG_DEV_HANDLE dh, const IR _mbgdevio_write_var_chk( dh, PCPS_SET_IRIG_RX_SETTINGS, IOCTL_SET_PCPS_IRIG_RX_SETTINGS, p, _pcps_ddev_is_irig_rx( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_irig_rx_settings @@ -4695,21 +4956,21 @@ _MBG_API_ATTR int _MBG_API mbg_set_irig_rx_settings( MBG_DEV_HANDLE dh, const IR /*HDR*/ /** - * @brief Read all IRIG input configuration information from a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pdev Pointer to the device's ::PCPS_DEV structure - @param p_irig_info Pointer to a ::IRIG_SETTINGS structure to be written - @param p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written - @param p_opt_info Pointer to a ::MBG_OPT_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Read all IRIG input configuration information from a device + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] pdev Pointer to the device's ::PCPS_DEV structure //### TODO Make this obsolete + * @param[in] p_irig_info Pointer to a ::IRIG_SETTINGS structure to be written + * @param[in] p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written + * @param[in] p_opt_info Pointer to a ::MBG_OPT_SETTINGS structure to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_save_all_irig_rx_settings * @see ::mbg_set_irig_rx_settings * @see ::mbg_set_ref_offs * @see ::mbg_set_opt_settings -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_all_irig_rx_info( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, IRIG_INFO *p_irig_info, @@ -4738,25 +4999,25 @@ _MBG_API_ATTR int _MBG_API mbg_get_all_irig_rx_info( MBG_DEV_HANDLE dh, /*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[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pdev Pointer to the device's ::PCPS_DEV structure - @param p_irig_settings Pointer to a ::IRIG_SETTINGS structure to be written - @param p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written - @param p_opt_settings Pointer to a ::MBG_OPT_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The API call ::mbg_chk_dev_is_tcr checks whether + * this call is supported by a device. + * ::mbg_get_all_irig_rx_info should be called before to determine + * the possible settings supported by the IRIG input. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] pdev Pointer to the device's ::PCPS_DEV structure //### TODO Make this obsolete + * @param[out] p_irig_settings Pointer to a ::IRIG_SETTINGS structure to be written + * @param[out] p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written + * @param[out] p_opt_settings Pointer to a ::MBG_OPT_SETTINGS structure to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_all_irig_rx_info * @see ::mbg_set_irig_rx_settings * @see ::mbg_set_ref_offs * @see ::mbg_set_opt_settings -*/ + */ _MBG_API_ATTR int _MBG_API mbg_save_all_irig_rx_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const IRIG_SETTINGS *p_irig_settings, @@ -4785,41 +5046,41 @@ _MBG_API_ATTR int _MBG_API mbg_save_all_irig_rx_settings( MBG_DEV_HANDLE dh, /*HDR*/ /** * @brief Read the control function bits received from an incoming IRIG signal. - - This function fills a ::MBG_IRIG_CTRL_BITS structure with the control function - bits decoded from the incoming IRIG signal. - - The meaning of these bits depends on the type of IRIG code frame format. - - In some IRIG formats these bits provide some well-known information which can - also be evaluated by the device. For example, in IEEE 1344 or IEEE C37.118 code - the control function bits are used to provide the year number, UTC offset, - DST status, leap second warning, etc. - - For most IRIG code formats, however, these bits are reserved, i.e. not used - at all, or application defined, depending on the configuration of the IRIG - generator providing the IRIG signal. - - In the latter case the application has to evaluate the received control function - bits and can use this function to retrieve these bits from the receiver device. - - The macro _pcps_has_irig_ctrl_bits() or the API call mbg_dev_has_irig_ctrl_bits() - check whether this call is supported by a device. - + * + * This function fills an ::MBG_IRIG_CTRL_BITS structure with the control function + * bits decoded from the incoming IRIG signal. + * + * The meaning of these bits depends on the type of IRIG code frame format. + * + * In some IRIG formats these bits provide some well-known information which can + * also be evaluated by the device. For example, in IEEE 1344 or IEEE C37.118 code + * the control function bits are used to provide the year number, UTC offset, + * DST status, leap second warning, etc. + * + * For most IRIG code formats, however, these bits are reserved, i.e. not used + * at all, or application defined, depending on the configuration of the IRIG + * generator providing the IRIG signal. + * + * In the latter case the application has to evaluate the received control function + * bits and can use this function to retrieve these bits from the receiver device. + * + * The API call ::mbg_chk_dev_has_irig_ctrl_bits checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_IRIG_CTRL_BITS type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::MBG_IRIG_CTRL_BITS type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_irig_ctrl_bits + * @see ::mbg_chk_dev_has_irig_ctrl_bits */ _MBG_API_ATTR int _MBG_API mbg_get_irig_ctrl_bits( MBG_DEV_HANDLE dh, MBG_IRIG_CTRL_BITS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, PCPS_GET_IRIG_CTRL_BITS, IOCTL_GET_IRIG_CTRL_BITS, p ); _mbg_swab_irig_ctrl_bits( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_irig_ctrl_bits @@ -4828,29 +5089,29 @@ _MBG_API_ATTR int _MBG_API mbg_get_irig_ctrl_bits( MBG_DEV_HANDLE dh, /*HDR*/ /** * @brief Read raw IRIG data from an IRIG receiver. - - This function fills a ::MBG_RAW_IRIG_DATA structure with the raw data bits received - from the incoming IRIG signal. This enables an application itself to decode the - information provided by the IRIG signal. - - The macro _pcps_has_raw_irig_data() or the API call mbg_dev_has_raw_irig_data() - check whether this call is supported by a device. - + * + * This function reads an ::MBG_RAW_IRIG_DATA structure with the raw data bits received + * from the incoming IRIG signal. This enables an application itself to decode the + * information provided by the IRIG signal. + * + * The API call ::mbg_chk_dev_has_raw_irig_data checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_raw_irig_data + * @see ::mbg_chk_dev_has_raw_irig_data * @see ::mbg_get_raw_irig_data_on_sec_change */ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data( MBG_DEV_HANDLE dh, MBG_RAW_IRIG_DATA *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, PCPS_GET_RAW_IRIG_DATA, IOCTL_GET_RAW_IRIG_DATA, p ); // No endianess conversion required. - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_raw_irig_data @@ -4859,37 +5120,38 @@ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data( MBG_DEV_HANDLE dh, /*HDR*/ /** * @brief Wait for second changeover then read raw IRIG data from an IRIG receiver. - - This function waits until the second of the device's on-board time rolls over, and - then reads the last recent raw IRIG data from the device. - - The macro _pcps_has_raw_irig_data() or the API call mbg_dev_has_raw_irig_data() - check whether this call is supported by a device. - - <b>Note:</b> The mbg_get_time_sec_change() function called by this function is - supported under Windows only, so this function can also only be used under Windows. - + * + * This function waits until the second of the device's on-board time rolls over, + * and then reads the last recent raw IRIG data from the device. + * + * The API call ::mbg_chk_dev_has_raw_irig_data checks whether + * this call is supported by a device. + * + * <b>Note:</b> The ::mbg_get_time_sec_change function called + * by this function is supported under Windows only, so this function + * can also be used under Windows only. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_raw_irig_data + * @param[out] p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_raw_irig_data * @see ::mbg_get_raw_irig_data * @see ::mbg_get_time_sec_change -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data_on_sec_change( MBG_DEV_HANDLE dh, MBG_RAW_IRIG_DATA *p ) { PCPS_TIME t; - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = mbg_get_time_sec_change( dh, &t ); if ( mbg_rc_is_success( rc ) ) rc = mbg_get_raw_irig_data( dh, p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_raw_irig_data_on_sec_change @@ -4898,29 +5160,29 @@ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data_on_sec_change( MBG_DEV_HANDLE d /*HDR*/ /** * @brief Read the IRIG time and day-of-year number from an IRIG receiver. - - Fills up a ::PCPS_IRIG_TIME structure with the raw IRIG day-of-year number - and time decoded from the latest IRIG input frame. If the configured IRIG code - also contains the year number then the year number is also returned, otherwise - the returned year number is 0xFF. - - The macro _pcps_has_irig_time() or the API call mbg_dev_has_irig_time() - check whether this call is supported by a device. - + * + * Reads a ::PCPS_IRIG_TIME structure with the raw IRIG day-of-year number + * and time decoded from the latest IRIG input frame. If the configured IRIG code + * also contains the year number then the year number is also returned, otherwise + * the returned year number is 0xFF. + * + * The API call ::mbg_chk_dev_has_irig_time checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_IRIG_TIME type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_irig_time -*/ + * @param[out] p Pointer to a ::PCPS_IRIG_TIME type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_irig_time + */ _MBG_API_ATTR int _MBG_API mbg_get_irig_time( MBG_DEV_HANDLE dh, PCPS_IRIG_TIME *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, PCPS_GIVE_IRIG_TIME, IOCTL_GET_IRIG_TIME, p ); _mbg_swab_pcps_irig_time( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_irig_time @@ -4929,24 +5191,24 @@ _MBG_API_ATTR int _MBG_API mbg_get_irig_time( MBG_DEV_HANDLE dh, /*HDR*/ /** * @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. - + * + * The API call ::mbg_chk_dev_can_clr_ucap_buff checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_can_clr_ucap_buff + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_can_clr_ucap_buff * @see ::mbg_get_ucap_entries * @see ::mbg_get_ucap_event - */ + */ _MBG_API_ATTR int _MBG_API mbg_clr_ucap_buff( MBG_DEV_HANDLE dh ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_write_cmd_chk( dh, PCPS_CLR_UCAP_BUFF, IOCTL_PCPS_CLR_UCAP_BUFF, _pcps_ddev_can_clr_ucap_buff( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_clr_ucap_buff @@ -4955,31 +5217,31 @@ _MBG_API_ATTR int _MBG_API mbg_clr_ucap_buff( MBG_DEV_HANDLE dh ) /*HDR*/ /** * @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. - + * + * Reads a ::PCPS_UCAP_ENTRIES structure with the number of user capture + * events actually stored in the FIFO buffer, and the maximum number of + * events that can be held by the buffer. + * + * The API call ::mbg_chk_dev_has_ucap checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_UCAP_ENTRIES structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ucap + * @param[out] p Pointer to a ::PCPS_UCAP_ENTRIES structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ucap * @see ::mbg_get_ucap_entries * @see ::mbg_get_ucap_event - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ucap_entries( MBG_DEV_HANDLE dh, PCPS_UCAP_ENTRIES *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_GIVE_UCAP_ENTRIES, IOCTL_GET_PCPS_UCAP_ENTRIES, p, _pcps_ddev_has_ucap( dh ) ); _mbg_swab_pcps_ucap_entries( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_ucap_entries @@ -4987,38 +5249,38 @@ _MBG_API_ATTR int _MBG_API mbg_get_ucap_entries( MBG_DEV_HANDLE dh, PCPS_UCAP_EN /*HDR*/ /** - * @brief Retrieve a single time capture event from the on-board FIFO buffer. - - The capture event is returned in a ::PCPS_HR_TIME structure. The oldest entry - in the FIFO is retrieved and then removed from the FIFO. - - If no capture event is available in the FIFO buffer then both the seconds - and the fractions of the returned timestamp are 0. - - The macro _pcps_has_ucap() or the API call mbg_dev_has_ucap() - check whether this call is supported by a device. - - <b>Note:</b> This call is very much faster than the older mbg_get_gps_ucap() - call which is obsolete but still supported for compatibility with - older cards. - + * @brief Retrieve a single time capture event from the on-board FIFO buffer + * + * The capture event is returned in a ::PCPS_HR_TIME structure. The oldest entry + * in the FIFO is retrieved and then removed from the FIFO. + * + * If no capture event is available in the FIFO buffer then both the seconds + * and the fractions of the returned timestamp are 0. + * + * The API call ::mbg_chk_dev_has_ucap checks whether + * this call is supported by a device. + * + * <b>Note:</b> This call is very much faster than the older ::mbg_get_gps_ucap + * call which is obsolete but still supported for compatibility with + * older cards. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_HR_TIME structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ucap + * @param[out] p Pointer to a ::PCPS_HR_TIME structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ucap * @see ::mbg_get_ucap_entries * @see ::mbg_clr_ucap_buff - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ucap_event( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_GIVE_UCAP_EVENT, IOCTL_GET_PCPS_UCAP_EVENT, p, _pcps_ddev_has_ucap( dh ) ); _mbg_swab_pcps_hr_time( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_ucap_event @@ -5026,35 +5288,35 @@ _MBG_API_ATTR int _MBG_API mbg_get_ucap_event( MBG_DEV_HANDLE dh, PCPS_HR_TIME * /*HDR*/ /** - * @brief Read the card's time zone/daylight saving parameters. - - This function returns the time zone/daylight saving parameters - in a ::TZDL structure. - - The macro _pcps_has_tzdl() or the API call mbg_dev_has_tzdl() - check whether this call is supported by a device. - - <b>Note:</b> In spite of the function name this call may also be - supported by non-GPS cards. Other cards may support the mbg_get_tzcode() - or mbg_get_pcps_tzdl() calls instead. - + * @brief Read the card's time zone/daylight saving parameters + * + * This function returns the time zone/daylight saving parameters + * in a ::TZDL structure. + * + * The API call ::mbg_chk_dev_has_tzdl checks whether + * this call is supported by a device. + * + * <b>Note:</b> In spite of the function name this call may also be + * supported by non-GPS cards. Other cards may support the ::mbg_get_tzcode + * or ::mbg_get_pcps_tzdl calls instead. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TZDL structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_tzdl + * @param[out] p Pointer to a ::TZDL structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_tzdl * @see ::mbg_set_gps_tzdl * @see ::mbg_get_tzcode * @see ::mbg_get_pcps_tzdl * @see @ref group_tzdl - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_tzdl( MBG_DEV_HANDLE dh, TZDL *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_gps_var( dh, PC_GPS_TZDL, IOCTL_GET_GPS_TZDL, p ); _mbg_swab_tzdl( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_tzdl @@ -5063,38 +5325,38 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_tzdl( MBG_DEV_HANDLE dh, TZDL *p ) /*HDR*/ /** * @brief Write the card's time zone/daylight saving parameters. - - This function writes the time zone/daylight saving parameters - in a ::TZDL structure to a device. - - The macro _pcps_has_tzdl() or the API call mbg_dev_has_tzdl() - check whether this call is supported by a device. - - <b>Note:</b> In spite of the function name this call may also be - supported by non-GPS cards. Other cards may support the mbg_set_tzcode() - or mbg_set_pcps_tzdl() calls instead. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TZDL structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_tzdl + * + * This function writes the time zone/daylight saving parameters + * in a ::TZDL structure to a device. + * + * The API call ::mbg_chk_dev_has_tzdl checks whether + * this call is supported by a device. + * + * <b>Note:</b> In spite of the function name this call may also be + * supported by non-GPS cards. Other cards may support the ::mbg_set_tzcode + * or ::mbg_set_pcps_tzdl calls instead. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::TZDL structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_tzdl * @see ::mbg_get_gps_tzdl * @see ::mbg_set_tzcode * @see ::mbg_set_pcps_tzdl * @see @ref group_tzdl - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_tzdl( MBG_DEV_HANDLE dh, const TZDL *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) TZDL tmp = *p; _mbg_swab_tzdl( &tmp ); p = &tmp; #endif rc = _mbgdevio_write_gps_var( dh, PC_GPS_TZDL, IOCTL_SET_GPS_TZDL, p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_gps_tzdl @@ -5102,31 +5364,33 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_tzdl( MBG_DEV_HANDLE dh, const TZDL *p ) /*HDR*/ /** - * @brief Retrieve the software revision of a GPS receiver. - - This call is obsolete but still supported for compatibility - with older GPS cards. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> The function mbg_get_gps_receiver_info() should - be used instead, if supported by the card. - + * @brief Retrieve the software revision of a GPS receiver + * + * @deprecated This function is deprecated. + * + * This function is deprecated, but still supported + * for compatibility with older GPS cards. Normally + * the software revision is part of the ::RECEIVER_INFO + * structure. See ::mbg_setup_receiver_info which takes + * care of the different options. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::SW_REV structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_is_gps - * @see ::mbg_get_gps_receiver_info - */ + * @param[out] p Pointer to a ::SW_REV structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_setup_receiver_info + * @see ::mbg_chk_dev_is_gps + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_sw_rev( MBG_DEV_HANDLE dh, SW_REV *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_gps_var( dh, PC_GPS_SW_REV, IOCTL_GET_GPS_SW_REV, p ); _mbg_swab_sw_rev( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_sw_rev @@ -5135,26 +5399,36 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_sw_rev( MBG_DEV_HANDLE dh, SW_REV *p ) /*HDR*/ /** * @brief Retrieve the status of the battery buffered GPS variables. - - These GPS variables hold some parameters sent by the GPS satellites - which are required for proper operation. If the saved set of parameters - is not complete then the GPS receiver stays in COLD BOOT mode until - all data have been received and thus all data sets are valid. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - + * + * GPS receivers require some navigational data set to be available + * to be able to decode position and time accurately. This data set + * is transmitted periodically by the satellites, so it can + * simply be collected if it's not available. + * + * The ::BVAR_STAT type reports which parts of the data set are + * available in the receiver, and which are not. + * + * If the available data set is not complete then the receiver + * stays in COLD BOOT mode until all data have been received + * and thus all data sets are valid. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::BVAR_STAT structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::BVAR_STAT structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_is_gps + * @see ::BVAR_FLAGS */ _MBG_API_ATTR int _MBG_API mbg_get_gps_bvar_stat( MBG_DEV_HANDLE dh, BVAR_STAT *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_gps_var( dh, PC_GPS_BVAR_STAT, IOCTL_GET_GPS_BVAR_STAT, p ); _mbg_swab_bvar_stat( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_stat @@ -5162,28 +5436,28 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_bvar_stat( MBG_DEV_HANDLE dh, BVAR_STAT * /*HDR*/ /** - * @brief Read the current board time using a ::TTM structure. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This API call is pretty slow, so the mbg_get_hr_time_..() - or mbg_get_fast_hr_timestamp...() group of calls should be used preferably. - + * @brief Read the current board time using a ::TTM structure + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> This API call is pretty slow, so ::mbg_get_hr_time or + * ::mbg_get_fast_hr_timestamp or associated calls should be used preferably. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TTM structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::TTM structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_hr_time * @see ::mbg_get_fast_hr_timestamp -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_time( MBG_DEV_HANDLE dh, TTM *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_gps_var( dh, PC_GPS_TIME, IOCTL_GET_GPS_TIME, p ); _mbg_swab_ttm( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_time @@ -5191,29 +5465,31 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_time( MBG_DEV_HANDLE dh, TTM *p ) /*HDR*/ /** - * @brief Set the time on a GPS receiver device. - - Write a ::TTM structure to a GPS receiver in order to set the - on-board date and time. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TTM structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @brief Set the time on a GPS receiver device + * + * Write a ::TTM structure to a GPS receiver in order to set + * the on-board date and time. Date and time must be local time + * according to the device's on-board time zone configuration + * (::TZDL). + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::TTM structure to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES */ _MBG_API_ATTR int _MBG_API mbg_set_gps_time( MBG_DEV_HANDLE dh, const TTM *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) TTM tmp = *p; _mbg_swab_ttm( &tmp ); p = &tmp; #endif rc = _mbgdevio_write_gps_var( dh, PC_GPS_TIME, IOCTL_SET_GPS_TIME, p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_gps_time @@ -5222,28 +5498,30 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_time( MBG_DEV_HANDLE dh, const TTM *p ) /*HDR*/ /** * @brief Read a ::PORT_PARM structure with a device's serial port configuration. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This function is obsolete since it is only - supported by a certain class of devices and can handle only - up to 2 ports. The generic function mbg_get_serial_settings() - should be used instead. - + * + * @deprecated This function is deprecated, use ::mbg_get_serial_settings preferably. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> This function is deprecated since it is only + * supported by a certain class of devices and can handle only + * up to 2 serial ports. The generic function ::mbg_get_serial_settings + * should be used instead. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PORT_PARM structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::PORT_PARM structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_serial_settings */ _MBG_API_ATTR int _MBG_API mbg_get_gps_port_parm( MBG_DEV_HANDLE dh, PORT_PARM *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_gps_var( dh, PC_GPS_PORT_PARM, IOCTL_GET_GPS_PORT_PARM, p ); _mbg_swab_port_parm( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_port_parm @@ -5252,32 +5530,34 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_port_parm( MBG_DEV_HANDLE dh, PORT_PARM * /*HDR*/ /** * @brief Write a ::PORT_PARM structure to configure the on-board serial ports. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This function is obsolete since it is only - supported by a certain class of devices and can handle only - up to 2 ports. The generic function mbg_save_serial_settings() - should be used instead. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PORT_PARM structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * + * @deprecated This function is deprecated, use ::mbg_save_serial_settings preferably. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> This function is deprecated since it is only + * supported by a certain class of devices and can handle only + * up to 2 ports. The generic function ::mbg_save_serial_settings + * should be used instead. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PORT_PARM structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_save_serial_settings */ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_parm( MBG_DEV_HANDLE dh, const PORT_PARM *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) PORT_PARM tmp = *p; _mbg_swab_port_parm( &tmp ); p = &tmp; #endif rc = _mbgdevio_write_gps_var( dh, PC_GPS_PORT_PARM, IOCTL_SET_GPS_PORT_PARM, p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_gps_port_parm @@ -5286,27 +5566,27 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_parm( MBG_DEV_HANDLE dh, const PORT_ /*HDR*/ /** * @brief Read an ::ANT_INFO structure to retrieve an extended GPS antenna status. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> Normally the current antenna connection status can also be - determined by evaluation of the ::PCPS_TIME::signal or ::PCPS_HR_TIME::signal - fields. The "disconnected" status reported by ANT_INFO disappears only if - the antenna has been reconnected <b>and</b> the receiver has synchronized - to the GPS satellites again. - + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> Normally the current antenna connection status can also be + * determined by evaluation of the ::PCPS_TIME::signal or ::PCPS_HR_TIME::signal + * fields. The "disconnected" status reported by ::ANT_INFO disappears only if + * the antenna has been reconnected <b>and</b> the receiver has synchronized + * to the GPS satellites again. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ANT_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::ANT_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES */ _MBG_API_ATTR int _MBG_API mbg_get_gps_ant_info( MBG_DEV_HANDLE dh, ANT_INFO *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_gps_var( dh, PC_GPS_ANT_INFO, IOCTL_GET_GPS_ANT_INFO, p ); _mbg_swab_ant_info( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_ant_info @@ -5314,31 +5594,31 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_ant_info( MBG_DEV_HANDLE dh, ANT_INFO *p /*HDR*/ /** - * @brief Read a time capture event from the on-board FIFO buffer using a ::TTM structure. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This call is pretty slow and has been obsoleted by - mbg_get_ucap_event() which should be used preferably, if supported - by the device. Anyway, this call is still supported for compatibility - with older devices. - + * @brief Read a time capture event from the on-board FIFO buffer using a ::TTM structure + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> This call is pretty slow and has been obsoleted by + * ::mbg_get_ucap_event which should be used preferably, if supported + * by the device. Anyway, this call is still supported for compatibility + * with older devices which don't support ::mbg_get_ucap_event. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TTM structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::TTM structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_ucap_entries * @see ::mbg_get_ucap_event * @see ::mbg_clr_ucap_buff -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_ucap( MBG_DEV_HANDLE dh, TTM *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_gps_var( dh, PC_GPS_UCAP, IOCTL_GET_GPS_UCAP, p ); _mbg_swab_ttm( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_ucap @@ -5346,33 +5626,35 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_ucap( MBG_DEV_HANDLE dh, TTM *p ) /*HDR*/ /** - * @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. - + * @brief Read the ::ENABLE_FLAGS structure controlling when outputs are to be enabled + * + * The ::ENABLE_FLAGS structure controls whether certain signal outputs + * are to be enabled immediately after the device's power-up, or only + * after the device has synchronized to its input signal. + * * The function ::mbg_chk_dev_has_gps_data can be used to check * whether this call is supported by a device. - - <b>Note:</b> Not all of the input signals specified for the - ::ENABLE_FLAGS structure can be modified individually. - + * + * <b>Note:</b> Not all of the input signals specified for the + * ::ENABLE_FLAGS structure can be modified individually. + * See ::ENABLE_FLAGS_CODES. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::ENABLE_FLAGS structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::ENABLE_FLAGS structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::ENABLE_FLAGS + * @see ::ENABLE_FLAGS_CODES * @see ::mbg_set_gps_enable_flags -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_enable_flags( MBG_DEV_HANDLE dh, ENABLE_FLAGS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_gps_var( dh, PC_GPS_ENABLE_FLAGS, IOCTL_GET_GPS_ENABLE_FLAGS, p ); _mbg_swab_enable_flags( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_enable_flags @@ -5380,30 +5662,32 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_enable_flags( MBG_DEV_HANDLE dh, ENABLE_F /*HDR*/ /** - * @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. - + * @brief Write an ;;ENABLE_FLAGS structure to configure when outputs shall be enabled. + * + * The ::ENABLE_FLAGS structure controls whether certain signal outputs + * are to be enabled immediately after the device's power-up, or only + * after the device has synchronized to its input signal. + * * The function ::mbg_chk_dev_has_gps_data can be used to check * whether this call is supported by a device. - - <b>Note:</b> Not all of the input signals specified for the - ENABLE_FLAGS structure can be modified individually. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ENABLE_FLAGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * <b>Note:</b> Not all of the input signals specified for the + * ::ENABLE_FLAGS structure can be modified individually. + * See ::ENABLE_FLAGS_CODES. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ENABLE_FLAGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::ENABLE_FLAGS + * @see ::ENABLE_FLAGS_CODES * @see ::mbg_get_gps_enable_flags -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_enable_flags( MBG_DEV_HANDLE dh, const ENABLE_FLAGS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) ENABLE_FLAGS tmp = *p; _mbg_swab_enable_flags( &tmp ); @@ -5411,7 +5695,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_enable_flags( MBG_DEV_HANDLE dh, #endif rc = _mbgdevio_write_gps_var( dh, PC_GPS_ENABLE_FLAGS, IOCTL_SET_GPS_ENABLE_FLAGS, p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_gps_enable_flags @@ -5424,22 +5708,22 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_enable_flags( MBG_DEV_HANDLE dh, * The ::STAT_INFO structure reports the status of the GPS receiver, * including mode of operation and number of visible/usable satellites. * - * The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::STAT_INFO structure to be filled up + * @param[out] p Pointer to a ::STAT_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::STAT_INFO */ _MBG_API_ATTR int _MBG_API mbg_get_gps_stat_info( MBG_DEV_HANDLE dh, STAT_INFO *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_gps_var( dh, PC_GPS_STAT_INFO, IOCTL_GET_GPS_STAT_INFO, p ); _mbg_swab_stat_info( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_stat_info @@ -5447,28 +5731,28 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_stat_info( MBG_DEV_HANDLE dh, STAT_INFO * /*HDR*/ /** - * @brief Send a ::GPS_CMD to a GPS receiver device. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::GPS_CMD - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::PC_GPS_CMD_BOOT, ::PC_GPS_CMD_INIT_SYS, ::PC_GPS_CMD_INIT_USER, ::PC_GPS_CMD_INIT_DAC -*/ + * @brief Send one of the ::PC_GPS_COMMANDS to a GPS receiver device + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::GPS_CMD + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::PC_GPS_COMMANDS + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_cmd( MBG_DEV_HANDLE dh, const GPS_CMD *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) GPS_CMD tmp = *p; _mbg_swab_gps_cmd( &tmp ); p = &tmp; #endif rc = _mbgdevio_write_gps_var( dh, PC_GPS_CMD, IOCTL_SET_GPS_CMD, p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_gps_cmd @@ -5476,30 +5760,30 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_cmd( MBG_DEV_HANDLE dh, const GPS_CMD *p /*HDR*/ /** * @brief Read the current geographic position from a GPS device. - - The returned ::POS structure contains the current position in - ECEF (Earth Centered, Earth Fixed) kartesian coordinates, and in - geographic coordinates with different formats, using the WGS84 - geographic datum. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - + * + * The returned ::POS structure contains the current position in + * ECEF (Earth Centered, Earth Fixed) kartesian coordinates, and in + * geographic coordinates with different formats, using the WGS84 + * geographic datum. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::POS structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::POS structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_gps_pos_xyz * @see ::mbg_set_gps_pos_lla -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_pos( MBG_DEV_HANDLE dh, POS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_gps_var( dh, PC_GPS_POS, IOCTL_GET_GPS_POS, p ); swap_pos_doubles( p ); _mbg_swab_pos( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_pos @@ -5507,25 +5791,25 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_pos( MBG_DEV_HANDLE dh, POS *p ) /*HDR*/ /** - * @brief Set the GPS receiver position using ::XYZ coordinates. - - The structure ::XYZ must specify the new position in ECEF - (Earth Centered, Earth Fixed) kartesian coordinates. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param p Position in ::XYZ format to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Set the GPS receiver position using ::XYZ coordinates + * + * The structure ::XYZ must specify the new position in ECEF + * (Earth Centered, Earth Fixed) kartesian coordinates. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Position in ::XYZ format to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_gps_pos_lla * @see ::mbg_get_gps_pos -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_xyz( MBG_DEV_HANDLE dh, const XYZ p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; XYZ xyz; int i; @@ -5540,7 +5824,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_xyz( MBG_DEV_HANDLE dh, const XYZ p ) // XYZ is an array, not a structure. rc = _mbgdevio_write_gps( dh, PC_GPS_POS_XYZ, IOCTL_SET_GPS_POS_XYZ, xyz, sizeof( XYZ ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_gps_pos_xyz @@ -5553,20 +5837,20 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_xyz( MBG_DEV_HANDLE dh, const XYZ p ) * The structure ::LLA must specify the new position as longitude, * latitude, and altitude, using the WGS84 geographic datum. * - * The macro ::_pcps_is_gps or the API call ::mbg_dev_is_gps - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param p Position in ::LLA format to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Position in ::LLA format to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_set_gps_pos_xyz * @see ::mbg_get_gps_pos */ _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_lla( MBG_DEV_HANDLE dh, const LLA p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; LLA lla; int i; @@ -5581,7 +5865,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_lla( MBG_DEV_HANDLE dh, const LLA p ) // LLA is an array, not a structure. rc = _mbgdevio_write_gps( dh, PC_GPS_POS_LLA, IOCTL_SET_GPS_POS_LLA, lla, sizeof( LLA ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_gps_pos_lla @@ -5589,31 +5873,31 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_lla( MBG_DEV_HANDLE dh, const LLA p ) /*HDR*/ /** - * @brief Read the configured GPS antenna cable length from a device. + * @brief Read the configured antenna cable length from a device * * The antenna cable length parameter is used by GPS/GNSS receivers * to compensate the propagation delay of the RF signal over the antenna * cable, which is about 5 ns/m. * - * The macro ::_pcps_has_cab_len or the API call ::mbg_dev_has_cab_len - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_cab_len checks whether + * this call is supported by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p ::ANT_CABLE_LEN structure to be filled up + * @param[out] p Pointer to an ::ANT_CABLE_LEN structure to be filled up. * - * @return One of the @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_cab_len + * @see ::mbg_chk_dev_has_cab_len * @see ::mbg_set_gps_ant_cable_len */ _MBG_API_ATTR int _MBG_API mbg_get_gps_ant_cable_len( MBG_DEV_HANDLE dh, ANT_CABLE_LEN *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_gps_var_chk( dh, PC_GPS_ANT_CABLE_LEN, IOCTL_GET_GPS_ANT_CABLE_LEN, p, _pcps_ddev_has_cab_len( dh ) ); _mbg_swab_ant_cable_len( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_ant_cable_len @@ -5627,25 +5911,25 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_ant_cable_len( MBG_DEV_HANDLE dh, ANT_CAB * to compensate the propagation delay of the RF signal over the antenna * cable, which is about 5 ns/m. * - * The macro ::_pcps_has_cab_len or the API call ::mbg_dev_has_cab_len - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_cab_len checks whether + * this call is supported by a device. * * @note Different devices may accept different maximum values, so the * written value should be re-read using ::mbg_get_gps_ant_cable_len * to check if the parameter has been accepted. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p ::ANT_CABLE_LEN structure to be written + * @param[out] p Pointer to an ::ANT_CABLE_LEN structure to be written. * - * @return One of the @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_cab_len + * @see ::mbg_chk_dev_has_cab_len * @see ::mbg_get_gps_ant_cable_len -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_ant_cable_len( MBG_DEV_HANDLE dh, const ANT_CABLE_LEN *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) ANT_CABLE_LEN tmp = *p; _mbg_swab_ant_cable_len( &tmp ); @@ -5654,7 +5938,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_ant_cable_len( MBG_DEV_HANDLE dh, _mbgdevio_write_gps_var_chk( dh, PC_GPS_ANT_CABLE_LEN, IOCTL_SET_GPS_ANT_CABLE_LEN, p, _pcps_ddev_has_cab_len( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_gps_ant_cable_len @@ -5662,31 +5946,32 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_ant_cable_len( MBG_DEV_HANDLE dh, /*HDR*/ /** - * @brief Read the ::RECEIVER_INFO structure from a device. - - The macro _pcps_has_receiver_info() or the API call mbg_dev_has_receiver_info() - check whether this call is supported by a device. - - <b>Note:</b> Applications should call mbg_setup_receiver_info() - preferably, which also sets up a basic ::RECEIVER_INFO structure - for devices which don't provide that structure by themselves. - + * @brief Read the ::RECEIVER_INFO structure from a device + * + * The API call ::mbg_chk_dev_has_receiver_info checks + * whether this call is supported by a device. + * + * <b>Note:</b> Applications should call ::mbg_setup_receiver_info + * preferably, which also sets up a basic ::RECEIVER_INFO structure + * for devices which don't provide that structure by themselves. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::RECEIVER_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::RECEIVER_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_setup_receiver_info -*/ + * @see ::mbg_chk_dev_has_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_receiver_info( MBG_DEV_HANDLE dh, RECEIVER_INFO *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_gps_var_chk( dh, PC_GPS_RECEIVER_INFO, IOCTL_GET_GPS_RECEIVER_INFO, p, _pcps_ddev_has_receiver_info( dh ) ); _mbg_swab_receiver_info( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_receiver_info @@ -5697,28 +5982,28 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_receiver_info( MBG_DEV_HANDLE dh, RECEIVE /*HDR*/ /** * @brief Read a ::STR_TYPE_INFO_IDX array of supported string types. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure passed to this function. - - <b>Note:</b> The function mbg_get_serial_settings() should be used preferably - to get retrieve the current port settings and configuration options. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param stii Pointer to a an array of string type information to be filled up - @param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info() - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_setup_receiver_info - * @see ::mbg_get_gps_all_port_info + * + * A valid ::RECEIVER_INFO associated with the device + * has to be passed to this function. + * + * <b>Note:</b> The function ::mbg_get_serial_settings should be used preferably + * to get retrieve the current port settings and configuration options. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] stii Pointer to a an array of string type information to be filled up. + * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device //### TODO Make this obsolete + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_serial_settings -*/ + * @see ::mbg_get_gps_all_port_info + * @see ::mbg_setup_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_str_type_info( MBG_DEV_HANDLE dh, STR_TYPE_INFO_IDX stii[], const RECEIVER_INFO *p_ri ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if _MBG_SUPP_VAR_ACC_SIZE _mbgdevio_read_gps_chk( dh, PC_GPS_ALL_STR_TYPE_INFO, @@ -5748,7 +6033,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_str_type_info( MBG_DEV_HANDLE dh, } #endif - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_all_str_type_info @@ -5757,28 +6042,28 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_str_type_info( MBG_DEV_HANDLE dh, /*HDR*/ /** * @brief Read a ::PORT_INFO_IDX array of supported serial port configurations. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure passed to this function. - - <b>Note:</b> The function mbg_get_serial_settings() should be used preferably - to get retrieve the current port settings and configuration options. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pii Pointer to a an array of port configuration information to be filled up - @param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info() - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_setup_receiver_info - * @see ::mbg_get_gps_all_str_type_info + * + * A valid ::RECEIVER_INFO associated with the device + * has to be passed to this function. + * + * <b>Note:</b> The function ::mbg_get_serial_settings should be used preferably + * to get retrieve the current port settings and configuration options. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] pii Pointer to a an array of port configuration information to be filled up. + * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device //### TODO Make this obsolete + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_serial_settings -*/ + * @see ::mbg_get_gps_all_str_type_info + * @see ::mbg_setup_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_port_info( MBG_DEV_HANDLE dh, PORT_INFO_IDX pii[], const RECEIVER_INFO *p_ri ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if _MBG_SUPP_VAR_ACC_SIZE _mbgdevio_read_gps_chk( dh, PC_GPS_ALL_PORT_INFO, @@ -5808,7 +6093,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_port_info( MBG_DEV_HANDLE dh, } #endif - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_all_port_info @@ -5817,30 +6102,30 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_port_info( MBG_DEV_HANDLE dh, /*HDR*/ /** * @brief Write the configuration for a single serial port to a device. - - The ::PORT_SETTINGS_IDX structure contains both the ::PORT_SETTINGS - and the port index value. Except for the parameter types this call is - equivalent to mbg_set_gps_port_settings(). - - The macro _pcps_has_receiver_info() or the API call mbg_dev_has_receiver_info() - check whether this call is supported by a device. - - <b>Note:</b> The function mbg_save_serial_settings() should be used preferably - to write new port configuration to the board. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PORT_SETTINGS_IDX structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The ::PORT_SETTINGS_IDX structure contains both the ::PORT_SETTINGS + * and the port index value. Except for the parameter types this call is + * equivalent to ::mbg_set_gps_port_settings. + * + * The API call ::mbg_chk_dev_has_receiver_info checks + * whether this call is supported by a device. + * + * <b>Note:</b> The function ::mbg_save_serial_settings should be used preferably + * to write new port configuration to the board. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PORT_SETTINGS_IDX structure to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_save_serial_settings * @see ::mbg_set_gps_port_settings - * @see ::mbg_dev_has_receiver_info -*/ + * @see ::mbg_chk_dev_has_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings_idx( MBG_DEV_HANDLE dh, const PORT_SETTINGS_IDX *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) PORT_SETTINGS_IDX tmp = *p; _mbg_swab_port_settings_idx( &tmp ); @@ -5849,7 +6134,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings_idx( MBG_DEV_HANDLE dh, _mbgdevio_write_gps_var_chk( dh, PC_GPS_PORT_SETTINGS_IDX, IOCTL_SET_GPS_PORT_SETTINGS_IDX, p, _pcps_ddev_has_receiver_info( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_gps_port_settings_idx @@ -5858,27 +6143,27 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings_idx( MBG_DEV_HANDLE dh, /*HDR*/ /** * @brief Write the configuration for a single serial port to a device. - - The ::PORT_SETTINGS structure does not contain the port index, so the - the port index must be given separately. Except for the parameter types - this call is equivalent to mbg_set_gps_port_settings_idx(). - - The macro _pcps_has_receiver_info() or the API call mbg_dev_has_receiver_info() - check whether this call is supported by a device. - - <b>Note:</b> The function mbg_save_serial_settings() should be used preferably - to write new port configuration to the board. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PORT_SETTINGS structure to be filled up - @param idx Index of the serial port to be configured (starting from 0 ). - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The ::PORT_SETTINGS structure does not contain the port index, so the + * the port index must be given separately. Except for the parameter types + * this call is equivalent to ::mbg_set_gps_port_settings_idx. + * + * The API call ::mbg_chk_dev_has_receiver_info checks + * whether this call is supported by a device. + * + * <b>Note:</b> The function ::mbg_save_serial_settings should be used preferably + * to write new port configuration to the board. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PORT_SETTINGS structure to be written. + * @param[in] idx Index of the serial port to be configured (starting from 0). + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_save_serial_settings * @see ::mbg_set_gps_port_settings_idx - * @see ::mbg_dev_has_receiver_info -*/ + * @see ::mbg_chk_dev_has_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings( MBG_DEV_HANDLE dh, const PORT_SETTINGS *p, int idx ) { @@ -5903,20 +6188,22 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings( MBG_DEV_HANDLE dh, * If the device supports the ::RECEIVER_INFO structure then the structure * is read from the device, otherwise a structure is set up using * default values depending on the device type. - * Optionally, the function mbg_get_device_info() may have been called + * + * Optionally, the function ::mbg_get_device_info may have been called * before, and the returned ::PCPS_DEV structure can be passed to this * function. + * * If a NULL pointer is passed instead, the device info is retrieved * directly from the device, using the device handle. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] p_dev Optional pointer to a ::PCPS_DEV structure, may be NULL - * @param[out] p Pointer to a ::RECEIVER_INFO structure to be filled up + * @param[in] p_dev Optional pointer to a ::PCPS_DEV structure, may be NULL. + * @param[out] p Pointer to a ::RECEIVER_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_device_info - * @see ::mbg_dev_has_receiver_info + * @see ::mbg_chk_dev_has_receiver_info */ _MBG_API_ATTR int _MBG_API mbg_setup_receiver_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, @@ -5974,23 +6261,23 @@ check: /*HDR*/ /** * @brief Read the version code of the on-board PCI/PCIe interface ASIC. - - The macro _pcps_has_asic_version() or the API call mbg_dev_has_asic_version() - check whether this call is supported by a device. - + * + * The API call ::mbg_chk_dev_has_asic_version checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCI_ASIC_VERSION type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_asic_version -*/ + * @param[out] p Pointer to a ::PCI_ASIC_VERSION type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_asic_version + */ _MBG_API_ATTR int _MBG_API mbg_get_asic_version( MBG_DEV_HANDLE dh, PCI_ASIC_VERSION *p ) { #if defined( _MBGIOCTL_H ) - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_PCI_ASIC_VERSION, p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); #else if ( !_pcps_ddev_has_asic_version( dh ) ) return MBG_ERR_NOT_SUPP_BY_DEV; @@ -6007,26 +6294,26 @@ _MBG_API_ATTR int _MBG_API mbg_get_asic_version( MBG_DEV_HANDLE dh, PCI_ASIC_VER /*HDR*/ /** - * @brief Read the features of the on-board PCI/PCIe interface ASIC. - - The macro _pcps_has_asic_features() or the API call mbg_dev_has_asic_features() - check whether this call is supported by a device. - + * @brief Read the features of the on-board PCI/PCIe interface ASIC + * + * The API call ::mbg_chk_dev_has_asic_features checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCI_ASIC_FEATURES type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_asic_features -*/ + * @param[out] p Pointer to a ::PCI_ASIC_FEATURES type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_asic_features + */ _MBG_API_ATTR int _MBG_API mbg_get_asic_features( MBG_DEV_HANDLE dh, PCI_ASIC_FEATURES *p ) { #if defined( _MBGIOCTL_H ) - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_PCI_ASIC_FEATURES, p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); #else if ( !_pcps_ddev_has_asic_features( dh ) ) { @@ -6046,31 +6333,32 @@ _MBG_API_ATTR int _MBG_API mbg_get_asic_features( MBG_DEV_HANDLE dh, /*HDR*/ /** - * @brief Read the current time scale settings and which time scales are supported. - - The ::MBG_TIME_SCALE_INFO structure tells which time scale settings are supported - by a device, and which time scale is currently configured. - - The macro _pcps_has_time_scale() or the API call mbg_dev_has_time_scale() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_time_scale(). - + * @brief Read the current time scale settings and which time scales are supported + * + * The ::MBG_TIME_SCALE_INFO structure tells which time scale settings are supported + * by a device, and which time scale is currently configured. + * + * The API call ::mbg_chk_dev_has_time_scale checks whether + * this call is supported by a device. + * + * See also the notes for ::mbg_chk_dev_has_time_scale. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_TIME_SCALE_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::MBG_TIME_SCALE_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_time_scale_settings - * @see ::mbg_dev_has_time_scale -*/ + * @see ::mbg_chk_dev_has_time_scale + */ _MBG_API_ATTR int _MBG_API mbg_get_time_scale_info( MBG_DEV_HANDLE dh, MBG_TIME_SCALE_INFO *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_gps_var_chk( dh, PC_GPS_TIME_SCALE, IOCTL_GET_GPS_TIME_SCALE_INFO, p, _pcps_ddev_has_time_scale( dh ) ); _mbg_swab_mbg_time_scale_info( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_time_scale_info @@ -6078,29 +6366,30 @@ _MBG_API_ATTR int _MBG_API mbg_get_time_scale_info( MBG_DEV_HANDLE dh, MBG_TIME_ /*HDR*/ /** - * @brief Write the time scale configuration to a device. - - The ::MBG_TIME_SCALE_SETTINGS structure determines which time scale - is to be used for the time stamps which can be read from a device. - - The macro _pcps_has_time_scale() or the API call mbg_dev_has_time_scale() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_time_scale(). - - The function mbg_get_time_scale_info() should have been called before - in order to determine which time scales are supported by the card. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_TIME_SCALE_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Write the time scale configuration to a device + * + * The ::MBG_TIME_SCALE_SETTINGS structure determines which time scale + * is to be used for the time stamps which can be read from a device. + * + * The API call ::mbg_chk_dev_has_time_scale checks whether + * this call is supported by a device. + * + * See also the notes for ::mbg_chk_dev_has_time_scale. + * + * The function ::mbg_get_time_scale_info should have been called before + * in order to determine which time scales are supported by the card. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::MBG_TIME_SCALE_SETTINGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_time_scale_info - * @see ::mbg_dev_has_time_scale -*/ + * @see ::mbg_chk_dev_has_time_scale + */ _MBG_API_ATTR int _MBG_API mbg_set_time_scale_settings( MBG_DEV_HANDLE dh, const MBG_TIME_SCALE_SETTINGS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) MBG_TIME_SCALE_SETTINGS tmp = *p; _mbg_swab_mbg_time_scale_settings( &tmp ); @@ -6109,7 +6398,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_time_scale_settings( MBG_DEV_HANDLE dh, const _mbgdevio_write_gps_var_chk( dh, PC_GPS_TIME_SCALE, IOCTL_SET_GPS_TIME_SCALE_SETTINGS, p, _pcps_ddev_has_time_scale( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_time_scale_settings @@ -6117,30 +6406,31 @@ _MBG_API_ATTR int _MBG_API mbg_set_time_scale_settings( MBG_DEV_HANDLE dh, const /*HDR*/ /** - * @brief Read a ::UTC parameter structure from a device. - - The macro _pcps_has_utc_parm() or the API call mbg_dev_has_utc_parm() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_utc_parm(). - + * @brief Read a ::UTC parameter structure from a device + * + * The API call ::mbg_chk_dev_has_utc_parm checks whether + * this call is supported by a device. + * + * See also the notes for ::mbg_chk_dev_has_utc_parm. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::UTC structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_utc_parm + * @param[out] p Pointer to a ::UTC structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_utc_parm * @see ::mbg_set_utc_parm -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_utc_parm( MBG_DEV_HANDLE dh, UTC *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_gps_var_chk( dh, PC_GPS_UTC, IOCTL_GET_GPS_UTC_PARM, p, _pcps_ddev_has_utc_parm( dh ) ); _mbg_swab_utc_parm( p ); swap_double( &p->A0 ); swap_double( &p->A1 ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_utc_parm @@ -6149,27 +6439,28 @@ _MBG_API_ATTR int _MBG_API mbg_get_utc_parm( MBG_DEV_HANDLE dh, UTC *p ) /*HDR*/ /** * @brief Write a ::UTC parameter structure to a device. - - This should only be done for testing, or if a card is operated in - freewheeling mode. If the receiver is tracking any satellites then the settings - written to the device are overwritten by the parameters broadcasted - by the satellites. - - The macro _pcps_has_utc_parm() or the API call mbg_dev_has_utc_parm() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_utc_parm(). - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a valid ::UTC structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_utc_parm + * + * This should only be done for testing, or if a card is operated in + * freewheeling mode. If the receiver is tracking any satellites then the settings + * written to the device are overwritten by the parameters broadcast + * by the satellites. + * + * The API call ::mbg_chk_dev_has_utc_parm checks whether + * this call is supported by a device. + * + * See also the notes for mbg_chk_dev_has_utc_parm. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a valid ::UTC structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_utc_parm * @see ::mbg_get_utc_parm -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_utc_parm( MBG_DEV_HANDLE dh, const UTC *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; // the original parameters need to be modified anyway, so always use a copy UTC tmp = *p; @@ -6184,7 +6475,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_utc_parm( MBG_DEV_HANDLE dh, const UTC *p ) _mbgdevio_write_gps_var_chk( dh, PC_GPS_UTC, IOCTL_SET_GPS_UTC_PARM, &tmp, _pcps_ddev_has_utc_parm( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_utc_parm @@ -6193,38 +6484,39 @@ _MBG_API_ATTR int _MBG_API mbg_set_utc_parm( MBG_DEV_HANDLE dh, const UTC *p ) /*HDR*/ /** * @brief Read the current time plus the associated PC cycles from a device. - - The ::PCPS_TIME_CYCLES structure contains a ::PCPS_TIME structure - and a PC cycle counter value which can be used to compensate the latency - of the call, i.e. the program execution time until the time stamp has actually - been read from the board. - - This call is supported for any card, similar to mbg_get_time(). However, - the mbg_get_hr_time_cyles() call should be used preferably if supported by - the device since that call provides much better accuracy than this one. - - The cycle counter value corresponds to a value returned by QueryPerformanceCounter() - under Windows, and get_cycles() under Linux. On operating systems or targets which don't - provide a cycles counter the returned cycles value is always 0. - - Applications should first pick up their own cycle counter value and then call - this function. The difference of the cycle counter values corresponds to the - latency of the call in units of the cycle counter clock frequency, e.g as reported - by QueryPerformanceFrequency() under Windows. - + * + * The ::PCPS_TIME_CYCLES structure contains a ::PCPS_TIME structure + * and a PC cycles counter value which can be used to compensate the latency + * of the call, i.e. the program execution time until the time stamp has actually + * been read from the board. + * + * This call is supported for any card, similar to ::mbg_get_time. However, + * the ::mbg_get_hr_time_cycles call should be used preferably if supported by + * the device since that call provides much better accuracy than this one. + * + * The cycles counter value corresponds to a value returned by QueryPerformanceCounter() + * under Windows, and get_cycles() under Linux. On operating systems or targets which don't + * provide a cycles counter the returned cycles value is always 0. + * + * Applications should first pick up their own cycles counter value and then call + * this function. The difference of the cycles counter values corresponds to the + * latency of the call in units of the cycles counter clock frequency, e.g as reported + * by QueryPerformanceFrequency() under Windows. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_CYCLES structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::PCPS_TIME_CYCLES structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_legacy_time_fncs * @see ::mbg_get_hr_time_cycles * @see ::mbg_get_hr_time_comp * @see ::mbg_get_hr_time * @see ::mbg_get_time -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_time_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_CYCLES *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, PCPS_GIVE_TIME, IOCTL_GET_PCPS_TIME_CYCLES, p ); // No endianess conversion required. #if !defined( _MBGIOCTL_H ) @@ -6232,7 +6524,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_time_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_CYC // for PCPS_TIME, read stamp AFTER the call p->cycles = 0; //##++ #endif - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_time_cycles @@ -6243,42 +6535,42 @@ _MBG_API_ATTR int _MBG_API mbg_get_time_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_CYC * @brief Read the current high resolution time plus the associated PC cycles from a device. * * The returned ::PCPS_HR_TIME_CYCLES structure contains a ::PCPS_HR_TIME - * structure and a PC cycle counter value which can be used to compensate + * structure and a PC cycles counter value which can be used to compensate * the latency of the call, i.e. the program execution time until the time stamp * has actually been read from the board. * - * The API call ::mbg_chk_dev_has_hr_time checks whether this call - * is supported by the device. + * The API call ::mbg_chk_dev_has_hr_time checks whether + * this call is supported by the device. * - * For details see @ref ::pcps_hr_time_fncs + * For details see @ref ::mbgdevio_hr_time_fncs * - * The cycle counter value corresponds to a value returned by QueryPerformanceCounter() + * The cycles counter value corresponds to a value returned by QueryPerformanceCounter() * under Windows, and get_cycles() under Linux. On operating systems or targets which don't * provide a cycles counter the returned cycles value is always 0. * - * Applications should first pick up their own 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 cycles counter value and then call + * this function. The difference of the cycles counter values corresponds to the + * latency of the call in units of the cycles counter clock frequency, e.g as reported * by QueryPerformanceFrequency() under Windows. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_HR_TIME_CYCLES structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @ingroup pcps_hr_time_fncs + * @ingroup mbgdevio_hr_time_fncs * @see ::mbg_chk_dev_has_hr_time * @see ::mbg_get_hr_time * @see ::mbg_get_hr_time_cycles * @see ::mbg_get_hr_time_comp - * @see @ref pcps_hr_time_fncs - * @see @ref pcps_fast_timestamp_fncs - * @see @ref pcps_std_time_fncs + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs */ _MBG_API_ATTR int _MBG_API mbg_get_hr_time_cycles( MBG_DEV_HANDLE dh, PCPS_HR_TIME_CYCLES *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if !defined( _MBGIOCTL_H ) // only if not using IOCTLs // for PCPS_HR_TIME, read stamp BEFORE the call @@ -6288,7 +6580,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_hr_time_cycles( MBG_DEV_HANDLE dh, IOCTL_GET_PCPS_HR_TIME_CYCLES, p, _pcps_ddev_has_hr_time( dh ) ); _mbg_swab_pcps_hr_time_cycles( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_hr_time_cycles @@ -6298,22 +6590,22 @@ _MBG_API_ATTR int _MBG_API mbg_get_hr_time_cycles( MBG_DEV_HANDLE dh, /** * @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 + * Read a ::PCPS_HR_TIME structure plus cycles counter value, and correct the * time stamp for the latency of the call as described for ::mbg_get_hr_time_cycles, - * then return the compensated time stamp and optionally the latency. + * then return the compensated time stamp, and optionally the latency. * - * The API call ::mbg_chk_dev_has_hr_time checks whether this call - * is supported by the device. + * The API call ::mbg_chk_dev_has_hr_time checks whether + * this call is supported by the device. * - * For details see @ref ::pcps_hr_time_fncs + * For details see @ref ::mbgdevio_hr_time_fncs * - * The cycle counter value corresponds to a value returned by QueryPerformanceCounter() + * The cycles counter value corresponds to a value returned by QueryPerformanceCounter() * under Windows, and get_cycles() under Linux. On operating systems or targets which don't * provide a cycles counter the returned cycles value is always 0. * - * Applications should first pick up their own 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 cycles counter value and then call + * this function. The difference of the cycles counter values corresponds to the + * latency of the call in units of the cycles counter clock frequency, e.g as reported * by QueryPerformanceFrequency() under Windows. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. @@ -6321,16 +6613,16 @@ _MBG_API_ATTR int _MBG_API mbg_get_hr_time_cycles( MBG_DEV_HANDLE dh, * @param[out] hns_latency Optional pointer to an int32_t value to return * the latency in 100ns units, or NULL, if not used. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @ingroup pcps_hr_time_fncs + * @ingroup mbgdevio_hr_time_fncs * @see ::mbg_chk_dev_has_hr_time * @see ::mbg_get_hr_time * @see ::mbg_get_hr_time_cycles * @see ::mbg_get_hr_time_comp - * @see @ref pcps_hr_time_fncs - * @see @ref pcps_fast_timestamp_fncs - * @see @ref pcps_std_time_fncs + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs */ _MBG_API_ATTR int _MBG_API mbg_get_hr_time_comp( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p, int32_t *hns_latency ) @@ -6362,27 +6654,27 @@ _MBG_API_ATTR int _MBG_API mbg_get_hr_time_comp( MBG_DEV_HANDLE dh, PCPS_HR_TIME /*HDR*/ /** * @brief Read the current IRIG output settings plus the supported settings. - - The returned ::IRIG_INFO structure contains the configuration of an IRIG output - plus the possible settings supported by that output. - - The macro _pcps_has_irig_tx() or the API call mbg_dev_has_irig_tx() - check whether this call is supported by a device. - + * + * The returned ::IRIG_INFO structure contains the configuration of an IRIG output + * plus the possible settings supported by that output. + * + * The API call ::mbg_chk_dev_has_irig_tx checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an ::IRIG_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to an ::IRIG_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_irig_tx_settings - * @see ::mbg_dev_has_irig_tx - * @see ::mbg_dev_is_irig_rx - * @see ::mbg_dev_has_irig + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig * @see @ref group_icode -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_irig_tx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if !defined( _MBGIOCTL_H ) // This is a workaround for GPS169PCIs with early @@ -6402,7 +6694,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_irig_tx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p #undef _PCPS_CMD _mbg_swab_irig_info( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_irig_tx_info @@ -6410,25 +6702,25 @@ _MBG_API_ATTR int _MBG_API mbg_get_irig_tx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p /*HDR*/ /** - * @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[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an ::IRIG_INFO structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Write an ::IRIG_SETTINGS structure to a device to configure the IRIG output + * + * The API call ::mbg_chk_dev_has_irig_tx checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to an ::IRIG_INFO structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_irig_tx_info - * @see ::mbg_dev_has_irig_tx - * @see ::mbg_dev_is_irig_rx - * @see ::mbg_dev_has_irig + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig * @see @ref group_icode -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_irig_tx_settings( MBG_DEV_HANDLE dh, const IRIG_SETTINGS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if !defined( _MBGIOCTL_H ) uint8_t pcps_cmd; #endif @@ -6456,7 +6748,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_irig_tx_settings( MBG_DEV_HANDLE dh, const IR p, _pcps_ddev_has_irig_tx( dh ) ); #undef _PCPS_CMD - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_irig_tx_settings @@ -6464,31 +6756,31 @@ _MBG_API_ATTR int _MBG_API mbg_set_irig_tx_settings( MBG_DEV_HANDLE dh, const IR /*HDR*/ /** - * @brief Read the current frequency synthesizer settings from a device. + * @brief Read the current frequency synthesizer settings from a device * * Read a ::SYNTH structure containing the configuration of an optional * on-board programmable frequency synthesizer. * - * The macro ::_pcps_has_synth or the API call ::mbg_dev_has_synth - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_synth checks whether + * this call is supported by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::SYNTH structure to be filled up + * @param[out] p Pointer to a ::SYNTH structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_synth + * @see ::mbg_chk_dev_has_synth * @see ::mbg_set_synth * @see ::mbg_get_synth_state * @see @ref group_synth */ _MBG_API_ATTR int _MBG_API mbg_get_synth( MBG_DEV_HANDLE dh, SYNTH *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_GET_SYNTH, IOCTL_GET_SYNTH, p, _pcps_ddev_has_synth( dh ) ); _mbg_swab_synth( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_synth @@ -6496,27 +6788,27 @@ _MBG_API_ATTR int _MBG_API mbg_get_synth( MBG_DEV_HANDLE dh, SYNTH *p ) /*HDR*/ /** - * @brief Write some frequency synthesizer settings to a device. + * @brief Write frequency synthesizer configuration settings to a device * * Write a ::SYNTH structure containing the configuration of an optional * on-board programmable frequency synthesizer. * - * The macro _pcps_has_synth() or the API call mbg_dev_has_synth() - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_synth checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::SYNTH structure to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::SYNTH structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_synth + * @see ::mbg_chk_dev_has_synth * @see ::mbg_get_synth * @see ::mbg_get_synth_state - * @see @::\ref group_synth + * @see @ref group_synth */ _MBG_API_ATTR int _MBG_API mbg_set_synth( MBG_DEV_HANDLE dh, const SYNTH *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) SYNTH tmp = *p; _mbg_swab_synth( &tmp ); @@ -6524,7 +6816,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_synth( MBG_DEV_HANDLE dh, const SYNTH *p ) #endif _mbgdevio_write_var_chk( dh, PCPS_SET_SYNTH, IOCTL_SET_SYNTH, p, _pcps_ddev_has_synth( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_synth @@ -6532,28 +6824,28 @@ _MBG_API_ATTR int _MBG_API mbg_set_synth( MBG_DEV_HANDLE dh, const SYNTH *p ) /*HDR*/ /** - * @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. - + * @brief Read the current status of the on-board frequency synthesizer + * + * The API call ::mbg_chk_dev_has_synth checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::SYNTH_STATE structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_synth + * @param[out] p Pointer to a ::SYNTH_STATE structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_synth * @see ::mbg_get_synth * @see ::mbg_set_synth * @see @ref group_synth -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_synth_state( MBG_DEV_HANDLE dh, SYNTH_STATE *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_GET_SYNTH_STATE, IOCTL_GET_SYNTH_STATE, p, _pcps_ddev_has_synth( dh ) ); _mbg_swab_synth_state( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_synth_state @@ -6562,26 +6854,26 @@ _MBG_API_ATTR int _MBG_API mbg_get_synth_state( MBG_DEV_HANDLE dh, SYNTH_STATE * /*HDR*/ /** * @brief Read a high resolution ::PCPS_TIME_STAMP_CYCLES structure via memory mapped access. - + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_STAMP_CYCLES structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @ingroup pcps_fast_timestamp_fncs - * @see ::mbg_dev_has_fast_hr_timestamp + * @param[out] p Pointer to a ::PCPS_TIME_STAMP_CYCLES structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_fast_timestamp_fncs + * @see ::mbg_chk_dev_has_fast_hr_timestamp * @see ::mbg_get_fast_hr_timestamp_comp * @see ::mbg_get_fast_hr_timestamp - * @see @ref pcps_fast_timestamp_fncs + * @see @ref mbgdevio_fast_timestamp_fncs */ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP_CYCLES *p ) { #if defined( _MBGIOCTL_H ) - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_FAST_HR_TIMESTAMP_CYCLES, p ); // native endianess, no need to swap bytes - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); #else // This is currently not supported by the target environment. return MBG_ERR_NOT_SUPP_ON_OS; @@ -6593,22 +6885,22 @@ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_cycles( MBG_DEV_HANDLE dh, /*HDR*/ /** - * @brief Read a high resolution timestamp and compensate the latency of the call. - - The retrieved ::PCPS_TIME_STAMP is read from memory mapped registers, - and timestamp is compensated for the call's latency before it is returned. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_STAMP structure to be filled up - @param *hns_latency Optionally receive the latency in hectonanoseconds - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @ingroup pcps_fast_timestamp_fncs - * @see ::mbg_dev_has_fast_hr_timestamp + * @brief Read a high resolution timestamp and compensate the latency of the call + * + * The retrieved ::PCPS_TIME_STAMP is read from memory mapped registers, + * and timestamp is compensated for the call's latency before it is returned. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::PCPS_TIME_STAMP structure to be filled up + * @param[out] hns_latency Optionally receives the latency in hectonanoseconds //### TODO Check if hns + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_fast_timestamp_fncs + * @see ::mbg_chk_dev_has_fast_hr_timestamp * @see ::mbg_get_fast_hr_timestamp_cycles * @see ::mbg_get_fast_hr_timestamp - * @see @ref pcps_fast_timestamp_fncs + * @see @ref mbgdevio_fast_timestamp_fncs */ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_comp( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP *p, @@ -6640,33 +6932,33 @@ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_comp( MBG_DEV_HANDLE dh, /*HDR*/ /** - * @brief Read a high resolution ::PCPS_TIME_STAMP structure via memory mapped access. - - This function does not return or evaluate a cycles count, so the latency - of the call can not be determined. However, depending on the timer hardware - used as cycles counter it may take quite some time to read the cycles count - on some hardware architectures, so this call can be used to yield lower - latencies, under the restriction to be unable to determine the exact latency. - + * @brief Read a high resolution ::PCPS_TIME_STAMP structure via memory mapped access + * + * This function does not return or evaluate a cycles count, so the latency + * of the call can not be determined. However, depending on the timer hardware + * used as cycles counter it may take quite some time to read the cycles count + * on some hardware architectures, so this call can be used to yield lower + * latencies, under the restriction to be unable to determine the exact latency. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_STAMP structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @ingroup pcps_fast_timestamp_fncs - * @see ::mbg_dev_has_fast_hr_timestamp + * @param[out] p Pointer to a ::PCPS_TIME_STAMP structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_fast_timestamp_fncs + * @see ::mbg_chk_dev_has_fast_hr_timestamp * @see ::mbg_get_fast_hr_timestamp_comp * @see ::mbg_get_fast_hr_timestamp_cycles - * @see @ref pcps_fast_timestamp_fncs + * @see @ref mbgdevio_fast_timestamp_fncs */ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP *p ) { #if defined( _MBGIOCTL_H ) - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_FAST_HR_TIMESTAMP, p ); // native endianess, no need to swap bytes - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); #else // This is currently not supported by the target environment. return MBG_ERR_NOT_SUPP_ON_OS; @@ -6679,33 +6971,34 @@ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp( MBG_DEV_HANDLE dh, /*HDR*/ /** * @brief Read current configuraton and features provided by the programmable pulse outputs. - - Reads a ::POUT_INFO_IDX array of current settings and configuration - options of the device's programmable pulse outputs. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure passed to this function. - The function should only be called if the ::RECEIVER_INFO::n_prg_out - field (i.e. the number of programmable outputs on the board) is not 0. - - The array passed to this function to receive the returned data - must be able to hold at least ::RECEIVER_INFO::n_prg_out elements. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pii Pointer to a an array of ::POUT_INFO_IDX structures to be filled up - @param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info() - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * Read a ::POUT_INFO_IDX array of current settings and configuration + * options of the device's programmable pulse outputs. + * + * A valid ::RECEIVER_INFO associated with the device + * has to be passed to this function. + * + * The function should only be called if the ::RECEIVER_INFO::n_prg_out + * field (i.e. the number of programmable outputs on the board) is not 0. + * + * The array passed to this function to receive the returned data + * must be able to hold at least ::RECEIVER_INFO::n_prg_out elements. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] pii Pointer to a an array of ::POUT_INFO_IDX structures to be filled up + * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device //### TODO Make this obsolete + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_gps_pout_settings_idx * @see ::mbg_set_gps_pout_settings * @see ::mbg_setup_receiver_info -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_pout_info( MBG_DEV_HANDLE dh, POUT_INFO_IDX pii[], const RECEIVER_INFO *p_ri ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if _MBG_SUPP_VAR_ACC_SIZE _mbgdevio_read_gps_chk( dh, PC_GPS_ALL_POUT_INFO, @@ -6735,7 +7028,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_pout_info( MBG_DEV_HANDLE dh, } #endif - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_all_pout_info @@ -6744,27 +7037,27 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_pout_info( MBG_DEV_HANDLE dh, /*HDR*/ /** * @brief Write the configuration for a single programmable pulse output - - The ::POUT_SETTINGS_IDX structure contains both the ::POUT_SETTINGS - and the output index value. Except for the parameter types this call - is equivalent to mbg_set_gps_pout_settings(). - - The function should only be called if the ::RECEIVER_INFO::n_prg_out field - (i.e. the number of programmable outputs on the board) is not 0, and the - output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::POUT_SETTINGS_IDX structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The ::POUT_SETTINGS_IDX structure contains both the ::POUT_SETTINGS + * and the output index value. Except for the parameter types this call + * is equivalent to ::mbg_set_gps_pout_settings. + * + * The function should only be called if the ::RECEIVER_INFO::n_prg_out field + * (i.e. the number of programmable outputs on the board) is not 0, and the + * output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::POUT_SETTINGS_IDX structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_gps_all_pout_info * @see ::mbg_set_gps_pout_settings -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings_idx( MBG_DEV_HANDLE dh, const POUT_SETTINGS_IDX *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) POUT_SETTINGS_IDX tmp = *p; _mbg_swab_pout_settings_idx_on_set( &tmp ); @@ -6773,7 +7066,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings_idx( MBG_DEV_HANDLE dh, _mbgdevio_write_gps_var_chk( dh, PC_GPS_POUT_SETTINGS_IDX, IOCTL_SET_GPS_POUT_SETTINGS_IDX, p, _pcps_ddev_has_receiver_info( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_gps_pout_settings_idx @@ -6782,25 +7075,25 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings_idx( MBG_DEV_HANDLE dh, /*HDR*/ /** * @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[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::POUT_SETTINGS structure to be written - @param idx Index of the programmable pulse output to be configured (starting from 0 ). - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The ::POUT_SETTINGS structure does not contain the index of the + * programmable output to be configured, so the index must explicitly + * be passed to this function. Except for the parameter types this call + * is equivalent to ::mbg_set_gps_pout_settings_idx. + * + * The function should only be called if the ::RECEIVER_INFO::n_prg_out field + * (i.e. the number of programmable outputs on the board) is not 0, and the + * output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::POUT_SETTINGS structure to be written. + * @param[in] idx Index of the programmable pulse output to be configured (starting from 0 ). + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_gps_all_pout_info * @see ::mbg_set_gps_pout_settings_idx -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings( MBG_DEV_HANDLE dh, const POUT_SETTINGS *p, int idx ) { @@ -6818,23 +7111,25 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings( MBG_DEV_HANDLE dh, /*HDR*/ /** * @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. - + * + * IRQ status information includes flags indicating whether IRQs are + * actually enabled, and whether IRQ support by a card is possibly + * unsafe due to the firmware and interface chip version. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_IRQ_STAT_INFO variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::PCPS_IRQ_STAT_INFO variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see @ref PCPS_IRQ_STAT_INFO_DEFS */ _MBG_API_ATTR int _MBG_API mbg_get_irq_stat_info( MBG_DEV_HANDLE dh, PCPS_IRQ_STAT_INFO *p ) { #if defined( _MBGIOCTL_H ) - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_IRQ_STAT_INFO, p ); // native endianess, no need to swap bytes - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); #else *p = dh->irq_stat_info; return MBG_SUCCESS; @@ -6846,29 +7141,29 @@ _MBG_API_ATTR int _MBG_API mbg_get_irq_stat_info( MBG_DEV_HANDLE dh, PCPS_IRQ_ST /*HDR*/ /** - * @brief Read LAN interface information from a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - + * @brief Read LAN interface information from a device + * + * The API call ::mbg_chk_dev_has_lan_intf checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::LAN_IF_INFO variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_lan_intf + * @param[out] p Pointer to a ::LAN_IF_INFO variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_ip4_state * @see ::mbg_get_ip4_settings * @see ::mbg_set_ip4_settings - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_lan_if_info( MBG_DEV_HANDLE dh, LAN_IF_INFO *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_gps_var_chk( dh, PC_GPS_LAN_IF_INFO, IOCTL_GET_LAN_IF_INFO, p, _pcps_ddev_has_lan_intf( dh ) ); _mbg_swab_lan_if_info( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_lan_if_info @@ -6876,29 +7171,29 @@ _MBG_API_ATTR int _MBG_API mbg_get_lan_if_info( MBG_DEV_HANDLE dh, LAN_IF_INFO * /*HDR*/ /** - * @brief Read LAN IPv4 state from a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - + * @brief Read LAN IPv4 state from a device + * + * The API call ::mbg_chk_dev_has_lan_intf checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::IP4_SETTINGS variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_lan_intf + * @param[out] p Pointer to a ::IP4_SETTINGS variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info * @see ::mbg_get_ip4_settings * @see ::mbg_set_ip4_settings - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ip4_state( MBG_DEV_HANDLE dh, IP4_SETTINGS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_gps_var_chk( dh, PC_GPS_IP4_STATE, IOCTL_GET_IP4_STATE, p, _pcps_ddev_has_lan_intf( dh ) ); _mbg_swab_ip4_settings( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_ip4_state @@ -6907,28 +7202,28 @@ _MBG_API_ATTR int _MBG_API mbg_get_ip4_state( MBG_DEV_HANDLE dh, IP4_SETTINGS *p /*HDR*/ /** * @brief Read LAN IPv4 settings from a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - + * + * The API call ::mbg_chk_dev_has_lan_intf checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::IP4_SETTINGS variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_lan_intf + * @param[out] p Pointer to a ::IP4_SETTINGS variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info * @see ::mbg_get_ip4_state * @see ::mbg_set_ip4_settings - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ip4_settings( MBG_DEV_HANDLE dh, IP4_SETTINGS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_gps_var_chk( dh, PC_GPS_IP4_SETTINGS, IOCTL_GET_IP4_SETTINGS, p, _pcps_ddev_has_lan_intf( dh ) ); _mbg_swab_ip4_settings( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_ip4_settings @@ -6936,24 +7231,24 @@ _MBG_API_ATTR int _MBG_API mbg_get_ip4_settings( MBG_DEV_HANDLE dh, IP4_SETTINGS /*HDR*/ /** - * @brief Write LAN IPv4 settings to a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p ::IP4_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_lan_intf + * @brief Write LAN IPv4 settings to a device + * + * The API call ::mbg_chk_dev_has_lan_intf checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p ::IP4_SETTINGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info * @see ::mbg_get_ip4_settings -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_ip4_settings( MBG_DEV_HANDLE dh, const IP4_SETTINGS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) IP4_SETTINGS tmp = *p; _mbg_swab_ip4_settings( &tmp ); @@ -6962,7 +7257,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_ip4_settings( MBG_DEV_HANDLE dh, _mbgdevio_write_gps_var_chk( dh, PC_GPS_IP4_SETTINGS, IOCTL_SET_IP4_SETTINGS, p, _pcps_ddev_has_lan_intf( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_ip4_settings @@ -6970,30 +7265,30 @@ _MBG_API_ATTR int _MBG_API mbg_set_ip4_settings( MBG_DEV_HANDLE dh, /*HDR*/ /** - * @brief Read PTP/IEEE1588 status from a device. - - The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp() - check whether this call is supported by a device. - + * @brief Read PTP/IEEE1588 status from a device + * + * The API call ::mbg_chk_dev_has_ptp checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PTP_STATE variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp + * @param[out] p Pointer to a ::PTP_STATE variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_cfg_info * @see ::mbg_set_ptp_cfg_settings - * @see ::mbg_dev_has_ptp_unicast - */ + * @see ::mbg_chk_dev_has_ptp_unicast + */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_state( MBG_DEV_HANDLE dh, PTP_STATE *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_gps_var_chk( dh, PC_GPS_PTP_STATE, IOCTL_GET_PTP_STATE, p, _pcps_ddev_has_ptp( dh ) ); _mbg_swab_ptp_state( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_ptp_state @@ -7001,30 +7296,30 @@ _MBG_API_ATTR int _MBG_API mbg_get_ptp_state( MBG_DEV_HANDLE dh, PTP_STATE *p ) /*HDR*/ /** - * @brief Read PTP/IEEE1588 config info and current settings from a device. - - The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp() - check whether this call is supported by a device. - + * @brief Read PTP/IEEE1588 config info and current settings from a device + * + * The API call ::mbg_chk_dev_has_ptp checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PTP_CFG_INFO variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp + * @param[out] p Pointer to a ::PTP_CFG_INFO variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_state * @see ::mbg_set_ptp_cfg_settings - * @see ::mbg_dev_has_ptp_unicast - */ + * @see ::mbg_chk_dev_has_ptp_unicast + */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_cfg_info( MBG_DEV_HANDLE dh, PTP_CFG_INFO *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_gps_var_chk( dh, PC_GPS_PTP_CFG, IOCTL_GET_PTP_CFG_INFO, p, _pcps_ddev_has_ptp( dh ) ); _mbg_swab_ptp_cfg_info( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_ptp_cfg_info @@ -7033,25 +7328,25 @@ _MBG_API_ATTR int _MBG_API mbg_get_ptp_cfg_info( MBG_DEV_HANDLE dh, PTP_CFG_INFO /*HDR*/ /** * @brief Write PTP/IEEE1588 configuration settings to a device. - - The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p ::PTP_CFG_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp + * + * The API call ::mbg_chk_dev_has_ptp checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p ::PTP_CFG_SETTINGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_state * @see ::mbg_get_ptp_cfg_info - * @see ::mbg_dev_has_ptp_unicast -*/ + * @see ::mbg_chk_dev_has_ptp_unicast + */ _MBG_API_ATTR int _MBG_API mbg_set_ptp_cfg_settings( MBG_DEV_HANDLE dh, const PTP_CFG_SETTINGS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) PTP_CFG_SETTINGS tmp = *p; _mbg_swab_ptp_cfg_settings( &tmp ); @@ -7060,7 +7355,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_ptp_cfg_settings( MBG_DEV_HANDLE dh, _mbgdevio_write_gps_var_chk( dh, PC_GPS_PTP_CFG, IOCTL_SET_PTP_CFG_SETTINGS, p, _pcps_ddev_has_ptp( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_ptp_cfg_settings @@ -7069,30 +7364,30 @@ _MBG_API_ATTR int _MBG_API mbg_set_ptp_cfg_settings( MBG_DEV_HANDLE dh, /*HDR*/ /** * @brief Read PTP/IEEE1588 unicast master configuration limits from a device. - - The macro _pcps_has_ri_ptp_unicast() or the API call mbg_dev_has_ptp_unicast() - check whether this call is supported by a device. - + * + * The API call ::mbg_chk_dev_has_ptp_unicast checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PTP_UC_MASTER_CFG_LIMITS variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp_unicast + * @param[out] p Pointer to a ::PTP_UC_MASTER_CFG_LIMITS variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp_unicast * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_all_ptp_uc_master_info * @see ::mbg_set_ptp_uc_master_settings_idx * @see ::mbg_get_ptp_state - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_uc_master_cfg_limits( MBG_DEV_HANDLE dh, PTP_UC_MASTER_CFG_LIMITS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_gps_var_chk( dh, PC_GPS_PTP_UC_MASTER_CFG_LIMITS, IOCTL_PTP_UC_MASTER_CFG_LIMITS, p, _pcps_has_ri_ptp_unicast( _ri_addr( dh ) ) ); _mbg_swab_ptp_uc_master_cfg_limits( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_ptp_uc_master_cfg_limits @@ -7101,32 +7396,27 @@ _MBG_API_ATTR int _MBG_API mbg_get_ptp_uc_master_cfg_limits( MBG_DEV_HANDLE dh, /*HDR*/ /** * @brief Read PTP Unicast master settings and configuration options. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure passed to this function. - The function should only be called if the ::RECEIVER_INFO::n_prg_out - field (i.e. the number of programmable outputs on the board) is not 0. - - The array passed to this function to receive the returned data - must be able to hold at least ::RECEIVER_INFO::n_prg_out elements. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pii Pointer to a an array of ::PTP_UC_MASTER_INFO_IDX structures to be filled up - @param p_umsl Pointer to a ::PTP_UC_MASTER_CFG_LIMITS structure returned by mbg_get_ptp_uc_master_cfg_limits() - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp_unicast + * + * The array passed to this function to receive the returned data + * must be able to hold at least ::PTP_UC_MASTER_CFG_LIMITS::n_supp_master elements. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] pii Pointer to a an array of ::PTP_UC_MASTER_INFO_IDX structures to be filled up. + * @param[in] p_umsl Pointer to a ::PTP_UC_MASTER_CFG_LIMITS structure returned by ::mbg_get_ptp_uc_master_cfg_limits + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp_unicast * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_uc_master_cfg_limits * @see ::mbg_set_ptp_uc_master_settings_idx * @see ::mbg_get_ptp_state -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_all_ptp_uc_master_info( MBG_DEV_HANDLE dh, PTP_UC_MASTER_INFO_IDX pii[], const PTP_UC_MASTER_CFG_LIMITS *p_umsl ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if _MBG_SUPP_VAR_ACC_SIZE _mbgdevio_read_gps_chk( dh, PC_GPS_ALL_PTP_UC_MASTER_INFO, @@ -7153,7 +7443,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_all_ptp_uc_master_info( MBG_DEV_HANDLE dh, } #endif - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_all_ptp_uc_master_info @@ -7161,26 +7451,26 @@ _MBG_API_ATTR int _MBG_API mbg_get_all_ptp_uc_master_info( MBG_DEV_HANDLE dh, /*HDR*/ /** - * @brief Write PTP/IEEE1588 unicast configuration settings to a device. - - The macro _pcps_has_ri_ptp_unicast() or the API call mbg_dev_has_ptp_unicast() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p ::PTP_UC_MASTER_SETTINGS_IDX structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp_unicast + * @brief Write PTP/IEEE1588 unicast configuration settings to a device + * + * The API call ::mbg_chk_dev_has_ptp_unicast checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p ::PTP_UC_MASTER_SETTINGS_IDX structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp_unicast * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_uc_master_cfg_limits * @see ::mbg_get_all_ptp_uc_master_info * @see ::mbg_get_ptp_state -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_ptp_uc_master_settings_idx( MBG_DEV_HANDLE dh, const PTP_UC_MASTER_SETTINGS_IDX *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) PTP_UC_MASTER_SETTINGS_IDX tmp = *p; _mbg_swab_ptp_uc_master_settings_idx( &tmp ); @@ -7189,7 +7479,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_ptp_uc_master_settings_idx( MBG_DEV_HANDLE dh _mbgdevio_write_gps_var_chk( dh, PC_GPS_PTP_UC_MASTER_SETTINGS_IDX, IOCTL_SET_PTP_UC_MASTER_SETTINGS_IDX, p, _pcps_ddev_has_ptp_unicast( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_ptp_uc_master_settings_idx @@ -7210,25 +7500,25 @@ _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 API call - * ::mbg_dev_has_hr_time can be used to check whether this call is supported + * ::mbg_chk_dev_has_hr_time can be used to check whether this call is supported * by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::MBG_TIME_INFO_HRT structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_hr_time + * @see ::mbg_chk_dev_has_hr_time * @see ::mbg_get_time_info_tstamp */ _MBG_API_ATTR int _MBG_API mbg_get_time_info_hrt( MBG_DEV_HANDLE dh, MBG_TIME_INFO_HRT *p ) { #if defined( _MBGIOCTL_H ) - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, -1, IOCTL_GET_TIME_INFO_HRT, p, _pcps_ddev_has_hr_time( dh ) ); _mbg_swab_mbg_time_info_hrt( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); #else return MBG_ERR_NOT_SUPP_ON_OS; #endif @@ -7239,29 +7529,29 @@ _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. + * @brief Read both system time and associated device timestamp from the kernel driver * * This call is similar to ::mbg_get_time_info_hrt except that a - * ::mbg_get_fast_hr_timestamp_cycles call is made internally, so the - * API call ::mbg_dev_has_fast_hr_timestamp can be used to check - * whether this call is supported by a device. + * ::mbg_get_fast_hr_timestamp_cycles call is made internally, so + * the API call ::mbg_chk_dev_has_fast_hr_timestamp can be used to check whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::MBG_TIME_INFO_TSTAMP structure to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_TIME_INFO_TSTAMP structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_fast_hr_timestamp + * @see ::mbg_chk_dev_has_fast_hr_timestamp * @see ::mbg_get_time_info_hrt */ _MBG_API_ATTR int _MBG_API mbg_get_time_info_tstamp( MBG_DEV_HANDLE dh, MBG_TIME_INFO_TSTAMP *p ) { #if defined( _MBGIOCTL_H ) - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, -1, IOCTL_GET_TIME_INFO_TSTAMP, p, _pcps_ddev_has_fast_hr_timestamp( dh ) ); _mbg_swab_mbg_time_info_tstamp( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); #else return MBG_ERR_NOT_SUPP_ON_OS; #endif @@ -7274,25 +7564,25 @@ _MBG_API_ATTR int _MBG_API mbg_get_time_info_tstamp( MBG_DEV_HANDLE dh, MBG_TIME /** * @brief Read PZF correlation info from a device * - * The the API call ::mbg_dev_has_corr_info checks - * whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_corr_info checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::CORR_INFO structure to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::CORR_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_pzf - * @see ::mbg_dev_has_corr_info + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_chk_dev_has_corr_info */ _MBG_API_ATTR int _MBG_API mbg_get_corr_info( MBG_DEV_HANDLE dh, CORR_INFO *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_GET_CORR_INFO, IOCTL_GET_CORR_INFO, p, _pcps_ddev_has_corr_info( dh ) ); _mbg_swab_corr_info( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_corr_info @@ -7300,31 +7590,31 @@ _MBG_API_ATTR int _MBG_API mbg_get_corr_info( MBG_DEV_HANDLE dh, CORR_INFO *p ) /*HDR*/ /** - * @brief Read configurable "distance from transmitter" parameter from a device. + * @brief Read configurable "distance from transmitter" parameter from a device * * The distance from transmitter parameter is used to compensate * the RF propagation delay, mostly with long wave receivers. * - * The API call ::mbg_dev_has_tr_distance checks whether this call - * is supported by a device. + * The API call ::mbg_chk_dev_has_tr_distance checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::TR_DISTANCE variable to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::TR_DISTANCE variable to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_pzf - * @see ::mbg_dev_has_tr_distance + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_chk_dev_has_tr_distance * @see ::mbg_set_tr_distance */ _MBG_API_ATTR int _MBG_API mbg_get_tr_distance( MBG_DEV_HANDLE dh, TR_DISTANCE *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_GET_TR_DISTANCE, IOCTL_GET_TR_DISTANCE, p, _pcps_ddev_has_tr_distance( dh ) ); _mbg_swab_tr_distance( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_tr_distance @@ -7337,21 +7627,21 @@ _MBG_API_ATTR int _MBG_API mbg_get_tr_distance( MBG_DEV_HANDLE dh, TR_DISTANCE * * The distance from transmitter parameter is used to compensate * the RF propagation delay, mostly with long wave receivers. * - * The API call ::mbg_dev_has_tr_distance checks whether this call - * is supported by a device. + * The API call ::mbg_chk_dev_has_tr_distance checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] p Pointer to a ::TR_DISTANCE variable to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::TR_DISTANCE variable to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_pzf - * @see ::mbg_dev_has_tr_distance + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_chk_dev_has_tr_distance * @see ::mbg_get_tr_distance */ _MBG_API_ATTR int _MBG_API mbg_set_tr_distance( MBG_DEV_HANDLE dh, const TR_DISTANCE *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) TR_DISTANCE tmp = *p; _mbg_swab_tr_distance( &tmp ); @@ -7359,7 +7649,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_tr_distance( MBG_DEV_HANDLE dh, const TR_DIST #endif _mbgdevio_write_var_chk( dh, PCPS_SET_TR_DISTANCE, IOCTL_SET_TR_DISTANCE, p, _pcps_ddev_has_tr_distance( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_tr_distance @@ -7375,24 +7665,24 @@ _MBG_API_ATTR int _MBG_API mbg_set_tr_distance( MBG_DEV_HANDLE dh, const TR_DIST * * See ::MBG_DEBUG_STATUS and related definitions for details. * - * The API call ::mbg_dev_has_debug_status checks whether this call - * is supported by a device. + * The API call ::mbg_chk_dev_has_debug_status checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::MBG_DEBUG_STATUS variable to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_DEBUG_STATUS variable to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_debug_status + * @see ::mbg_chk_dev_has_debug_status */ _MBG_API_ATTR int _MBG_API mbg_get_debug_status( MBG_DEV_HANDLE dh, MBG_DEBUG_STATUS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_GET_DEBUG_STATUS, IOCTL_GET_DEBUG_STATUS, p, _pcps_ddev_has_debug_status( dh ) ); _mbg_swab_debug_status( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_debug_status @@ -7400,26 +7690,26 @@ _MBG_API_ATTR int _MBG_API mbg_get_debug_status( MBG_DEV_HANDLE dh, MBG_DEBUG_ST /*HDR*/ /** - * @brief Clear the device's on-board event log. + * @brief Clear the device's on-board event log * - * The API call ::mbg_dev_has_evt_log checks whether this call - * is supported by a device. + * The API call ::mbg_chk_dev_has_evt_log checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_evt_log + * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_get_num_evt_log_entries * @see ::mbg_get_first_evt_log_entry * @see ::mbg_get_next_evt_log_entry */ _MBG_API_ATTR int _MBG_API mbg_clr_evt_log( MBG_DEV_HANDLE dh ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_write_cmd_chk( dh, PCPS_CLR_EVT_LOG, IOCTL_CLR_EVT_LOG, _pcps_ddev_has_evt_log( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_clr_evt_log @@ -7427,33 +7717,33 @@ _MBG_API_ATTR int _MBG_API mbg_clr_evt_log( MBG_DEV_HANDLE dh ) /*HDR*/ /** - * @brief Read details about a device's on-board event log buffer. + * @brief Read details about a device's on-board event log buffer * - * The returned ::MBG_NUM_EVT_LOG_ENTRIES structure tells how many event log - * entries which can be saved on the board, and how many entries actually - * have been saved. + * The returned ::MBG_NUM_EVT_LOG_ENTRIES structure tells how many + * event log entries can be saved on the board, and how many entries + * actually have been saved. * - * The API call ::mbg_dev_has_evt_log checks whether this call - * is supported by a device. + * The API call ::mbg_chk_dev_has_evt_log checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::MBG_NUM_EVT_LOG_ENTRIES variable to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_NUM_EVT_LOG_ENTRIES variable to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_evt_log + * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_clr_evt_log * @see ::mbg_get_first_evt_log_entry * @see ::mbg_get_next_evt_log_entry */ _MBG_API_ATTR int _MBG_API mbg_get_num_evt_log_entries( MBG_DEV_HANDLE dh, MBG_NUM_EVT_LOG_ENTRIES *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_NUM_EVT_LOG_ENTRIES, IOCTL_GET_NUM_EVT_LOG_ENTRIES, p, _pcps_ddev_has_evt_log( dh ) ); _mbg_swab_mbg_num_evt_log_entries( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_num_evt_log_entries @@ -7461,34 +7751,34 @@ _MBG_API_ATTR int _MBG_API mbg_get_num_evt_log_entries( MBG_DEV_HANDLE dh, MBG_N /*HDR*/ /** - * @brief Read the first (oldest) event log entry from a device. + * @brief Read the first (oldest) event log entry from a device * * @note Subsequent reads should be made using ::mbg_get_next_evt_log_entry. * - * The API call ::mbg_dev_has_evt_log checks whether this call - * is supported by a device. + * The API call ::mbg_chk_dev_has_evt_log checks whether + * this call is supported by a device. * * If no (more) event log entry is available on the device then * the returned MBG_EVT_LOG_ENTRY::code is MBG_EVT_ID_NONE. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_evt_log + * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_clr_evt_log * @see ::mbg_get_num_evt_log_entries * @see ::mbg_get_next_evt_log_entry */ _MBG_API_ATTR int _MBG_API mbg_get_first_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_FIRST_EVT_LOG_ENTRY, IOCTL_GET_FIRST_EVT_LOG_ENTRY, p, _pcps_ddev_has_evt_log( dh ) ); _mbg_swab_mbg_evt_log_entry( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_first_evt_log_entry @@ -7496,35 +7786,35 @@ _MBG_API_ATTR int _MBG_API mbg_get_first_evt_log_entry( MBG_DEV_HANDLE dh, MBG_E /*HDR*/ /** - * @brief Read the next event log entry from a device. + * @brief Read the next event log entry from a device * * @note The first read should be made using ::mbg_get_first_evt_log_entry * to set the on-board read index to the oldest entry. * - * The API call ::mbg_dev_has_evt_log checks whether this call - * is supported by a device. + * The API call ::mbg_chk_dev_has_evt_log checks whether + * this call is supported by a device. * * If no (more) event log entry is available on the device then * the returned MBG_EVT_LOG_ENTRY::code is MBG_EVT_ID_NONE. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_evt_log + * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_clr_evt_log * @see ::mbg_get_num_evt_log_entries * @see ::mbg_get_first_evt_log_entry */ _MBG_API_ATTR int _MBG_API mbg_get_next_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_var_chk( dh, PCPS_NEXT_EVT_LOG_ENTRY, IOCTL_GET_NEXT_EVT_LOG_ENTRY, p, _pcps_ddev_has_evt_log( dh ) ); _mbg_swab_mbg_evt_log_entry( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_next_evt_log_entry @@ -7532,31 +7822,33 @@ _MBG_API_ATTR int _MBG_API mbg_get_next_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EV /*HDR*/ /** - * @brief Read the current GNSS mode info including current settings. + * @brief Read the current GNSS mode info including current settings * * The ::MBG_GNSS_MODE_INFO structure tells which GNSS systems are supported * by a device, and also includes the settings currently in effect. * - * The API call mbg_dev_is_gnss() can be used to check whether this call - * is supported by a device. See also the notes for mbg_dev_is_gnss(). + * The API call ::mbg_chk_dev_is_gnss can be used to check whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure to be filled up + * See also the notes for ::mbg_chk_dev_is_gnss. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_set_gps_gnss_mode_settings * @see ::mbg_get_gps_all_gnss_sat_info - * @see ::mbg_dev_is_gnss + * @see ::mbg_chk_dev_is_gnss */ _MBG_API_ATTR int _MBG_API mbg_get_gps_gnss_mode_info( MBG_DEV_HANDLE dh, MBG_GNSS_MODE_INFO *p_mi ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_gps_var_chk( dh, PC_GPS_GNSS_MODE, IOCTL_GET_GNSS_MODE_INFO, p_mi, _pcps_ddev_is_gnss( dh ) ); _mbg_swab_mbg_gnss_mode_info( p_mi ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_gnss_mode_info @@ -7564,30 +7856,32 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_gnss_mode_info( MBG_DEV_HANDLE dh, MBG_GN /*HDR*/ /** - * @brief Write the GNSS mode configuration to a device. + * @brief Write the GNSS mode configuration to a device * - * The ::MBG_GNSS_MODE_SETTINGS structure determines to configure the - * GNSS settings for a device, i.e. which satellite systems have to be used. + * The ::MBG_GNSS_MODE_SETTINGS structure determines the GNSS settings + * for a device, e.g. which satellite systems have to be used. * - * The function mbg_get_gps_gnss_mode_info() should have been called before + * The function ::mbg_get_gps_gnss_mode_info should have been called before * to determine which GNSS settings are supported by the device. * - * The API call mbg_dev_is_gnss() can be used to check whether these API calls - * are supported by a device. See also the notes for mbg_dev_is_gnss(). + * The API call ::mbg_chk_dev_is_gnss can be used to check whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p_ms Pointer to a ::MBG_GNSS_MODE_SETTINGS structure to be written + * See also the notes for ::mbg_chk_dev_is_gnss. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p_ms Pointer to a ::MBG_GNSS_MODE_SETTINGS structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_gps_gnss_mode_info * @see ::mbg_get_gps_all_gnss_sat_info - * @see ::mbg_dev_is_gnss + * @see ::mbg_chk_dev_is_gnss */ _MBG_API_ATTR int _MBG_API mbg_set_gps_gnss_mode_settings( MBG_DEV_HANDLE dh, const MBG_GNSS_MODE_SETTINGS *p_ms ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) MBG_GNSS_MODE_SETTINGS tmp = *p_ms; _mbg_swab_mbg_gnss_mode_settings( &tmp ); @@ -7596,7 +7890,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_gnss_mode_settings( MBG_DEV_HANDLE dh, _mbgdevio_write_gps_var_chk( dh, PC_GPS_GNSS_MODE, IOCTL_SET_GNSS_MODE_SETTINGS, p_ms, _pcps_ddev_is_gnss( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_gps_gnss_mode_settings @@ -7604,26 +7898,26 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_gnss_mode_settings( MBG_DEV_HANDLE dh, /*HDR*/ /** - * @brief Read a ::GNSS_SAT_INFO_IDX array of satellite status information. + * @brief Read a ::GNSS_SAT_INFO_IDX array of satellite status information * * The function ::mbg_get_gps_gnss_mode_info must have been called before, * and the returned ::MBG_GNSS_MODE_INFO structure be passed to this function. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] gsii Pointer to a an array of satellite info structures to be filled up - * @param[in] p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure returned by ::mbg_get_gps_gnss_mode_info + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] gsii Pointer to a an array of satellite info structures to be filled up. + * @param[in] p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure returned by ::mbg_get_gps_gnss_mode_info. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_gps_gnss_mode_info * @see ::mbg_set_gps_gnss_mode_settings - * @see ::mbg_dev_is_gnss + * @see ::mbg_chk_dev_is_gnss */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gnss_sat_info( MBG_DEV_HANDLE dh, GNSS_SAT_INFO_IDX gsii[], const MBG_GNSS_MODE_INFO *p_mi ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; int n_supp = num_bits_set( p_mi->supp_gnss_types ); @@ -7649,7 +7943,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gnss_sat_info( MBG_DEV_HANDLE dh, } #endif - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_all_gnss_sat_info @@ -7659,15 +7953,15 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gnss_sat_info( MBG_DEV_HANDLE dh, /** * @brief Read common GPIO configuration limits * - * The API call ::mbg_dev_has_gpio checks whether this call is supported - * by a device. + * The API call ::mbg_chk_dev_has_gpio checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] p A ::MBG_GPIO_CFG_LIMITS structure to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p A ::MBG_GPIO_CFG_LIMITS structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_gpio + * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits * @see ::mbg_get_gps_all_gpio_info * @see ::mbg_set_gps_gpio_settings_idx @@ -7675,13 +7969,13 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gnss_sat_info( MBG_DEV_HANDLE dh, */ _MBG_API_ATTR int _MBG_API mbg_get_gpio_cfg_limits( MBG_DEV_HANDLE dh, MBG_GPIO_CFG_LIMITS *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_gps_var_chk( dh, PC_GPS_GPIO_CFG_LIMITS, IOCTL_GET_GPIO_CFG_LIMITS, p, _pcps_ddev_has_gpio( dh ) ); _mbg_swab_mbg_gpio_cfg_limits( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gpio_cfg_limits @@ -7691,16 +7985,16 @@ _MBG_API_ATTR int _MBG_API mbg_get_gpio_cfg_limits( MBG_DEV_HANDLE dh, MBG_GPIO_ /** * @brief Get all GPIO settings and capabilities. * - * The API call ::mbg_dev_has_gpio checks whether this call is supported - * by a device. + * The API call ::mbg_chk_dev_has_gpio checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] gii An array of ::MBG_GPIO_STATUS_IDX structures to be filled up - * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] gii An array of ::MBG_GPIO_STATUS_IDX structures to be filled up. + * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_gpio + * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits * @see ::mbg_get_gps_all_gpio_info * @see ::mbg_set_gps_gpio_settings_idx @@ -7710,7 +8004,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gpio_info( MBG_DEV_HANDLE dh, MBG_GPIO_INFO_IDX gii[], const MBG_GPIO_CFG_LIMITS *p_gcl ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; uint32_t n_supp = p_gcl->num_io; @@ -7736,7 +8030,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gpio_info( MBG_DEV_HANDLE dh, } #endif - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_all_gpio_info @@ -7749,15 +8043,15 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gpio_info( MBG_DEV_HANDLE dh, * The ::MBG_GPIO_SETTINGS_IDX structure contains both the ::MBG_GPIO_SETTINGS * and the port index value. * - * The API call ::mbg_dev_has_gpio checks whether this call is supported - * by a device. + * The API call ::mbg_chk_dev_has_gpio checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] p Pointer to a ::MBG_GPIO_SETTINGS_IDX structure to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_GPIO_SETTINGS_IDX structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_gpio + * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits * @see ::mbg_get_gps_all_gpio_info * @see ::mbg_set_gps_gpio_settings_idx @@ -7766,7 +8060,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gpio_info( MBG_DEV_HANDLE dh, _MBG_API_ATTR int _MBG_API mbg_set_gps_gpio_settings_idx( MBG_DEV_HANDLE dh, const MBG_GPIO_SETTINGS_IDX *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) MBG_GPIO_SETTINGS_IDX tmp = *p; _mbg_swab_mbg_gpio_settings_idx( &tmp, 1 ); @@ -7775,7 +8069,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_gpio_settings_idx( MBG_DEV_HANDLE dh, _mbgdevio_write_gps_var_chk( dh, PC_GPS_GPIO_SETTINGS_IDX, IOCTL_SET_GPIO_SETTINGS_IDX, p, _pcps_ddev_has_gpio( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_gps_gpio_settings_idx @@ -7785,13 +8079,13 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_gpio_settings_idx( MBG_DEV_HANDLE dh, /** * @brief Read the status of all GPIO signal ports * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] gsi An array of ::MBG_GPIO_STATUS_IDX structures to be filled up - * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] gsi An array of ::MBG_GPIO_STATUS_IDX structures to be filled up. + * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_gpio + * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits * @see ::mbg_get_gps_all_gpio_info * @see ::mbg_set_gps_gpio_settings_idx @@ -7800,7 +8094,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gpio_status( MBG_DEV_HANDLE dh, MBG_GPIO_STATUS_IDX gsi[], const MBG_GPIO_CFG_LIMITS *p_gcl ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; uint32_t n_supp; @@ -7831,7 +8125,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gpio_status( MBG_DEV_HANDLE dh, } #endif - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_all_gpio_status @@ -7839,14 +8133,14 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gpio_status( MBG_DEV_HANDLE dh, /*HDR*/ /** - * @brief + * @brief Read ::XMULTI_REF_INSTANCES * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] *p A ::XMULTI_REF_INSTANCES structure to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p A ::XMULTI_REF_INSTANCES structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_gps_all_xmr_status * @see ::mbg_get_gps_all_xmr_info * @see ::mbg_set_gps_xmr_settings_idx @@ -7854,12 +8148,12 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gpio_status( MBG_DEV_HANDLE dh, */ _MBG_API_ATTR int _MBG_API mbg_get_xmr_instances( MBG_DEV_HANDLE dh, XMULTI_REF_INSTANCES *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; _mbgdevio_read_gps_var_chk( dh, PC_GPS_XMR_INSTANCES, IOCTL_GET_XMR_INSTANCES, p, _pcps_ddev_has_xmr( dh ) ); _mbg_swab_xmulti_ref_instances( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_xmr_instances @@ -7869,13 +8163,13 @@ _MBG_API_ATTR int _MBG_API mbg_get_xmr_instances( MBG_DEV_HANDLE dh, XMULTI_REF_ /** * @brief Read the status of all XMR sources * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] xmrsi An array of ::XMULTI_REF_STATUS_IDX structures to be filled up - * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] xmrsi An array of ::XMULTI_REF_STATUS_IDX structures to be filled up. + * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances * @see ::mbg_get_gps_all_xmr_info * @see ::mbg_set_gps_xmr_settings_idx @@ -7885,7 +8179,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_xmr_status( MBG_DEV_HANDLE dh, XMULTI_REF_STATUS_IDX xmrsi[], const XMULTI_REF_INSTANCES *p_xmri ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; int n_supp = p_xmri->n_xmr_settings; @@ -7911,7 +8205,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_xmr_status( MBG_DEV_HANDLE dh, } #endif - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_all_xmr_status @@ -7921,13 +8215,13 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_xmr_status( MBG_DEV_HANDLE dh, /** * @brief Read all XMR settings and capabilities * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] xmrii An array of ::XMULTI_REF_INFO_IDX structures to be filled up - * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] xmrii An array of ::XMULTI_REF_INFO_IDX structures to be filled up. + * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances * @see ::mbg_get_gps_all_xmr_status * @see ::mbg_set_gps_xmr_settings_idx @@ -7937,7 +8231,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_xmr_info( MBG_DEV_HANDLE dh, XMULTI_REF_INFO_IDX xmrii[], const XMULTI_REF_INSTANCES *p_xmri ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; int n_supp = p_xmri->n_xmr_settings; @@ -7963,7 +8257,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_xmr_info( MBG_DEV_HANDLE dh, } #endif - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_gps_all_xmr_info @@ -7976,15 +8270,15 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_xmr_info( MBG_DEV_HANDLE dh, * The ::XMULTI_REF_SETTINGS_IDX structure contains both the ::XMULTI_REF_SETTINGS * and the index value. * - * The macro ::_pcps_has_ri_xmr or the API call ::mbg_dev_has_xmr - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_xmr checks whether + * this call is supported by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::XMULTI_REF_SETTINGS_IDX structure to be written + * @param[in] p Pointer to a ::XMULTI_REF_SETTINGS_IDX structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances * @see ::mbg_get_gps_all_xmr_status * @see ::mbg_get_gps_all_xmr_info @@ -7993,7 +8287,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_xmr_info( MBG_DEV_HANDLE dh, _MBG_API_ATTR int _MBG_API mbg_set_gps_xmr_settings_idx( MBG_DEV_HANDLE dh, const XMULTI_REF_SETTINGS_IDX *p ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; #if defined( MBG_ARCH_BIG_ENDIAN ) XMULTI_REF_SETTINGS_IDX tmp = *p; _mbg_swab_xmulti_ref_settings_idx( &tmp ); @@ -8002,7 +8296,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_xmr_settings_idx( MBG_DEV_HANDLE dh, _mbgdevio_write_gps_var_chk( dh, PC_GPS_XMR_SETTINGS_IDX, IOCTL_SET_XMR_SETTINGS_IDX, p, _pcps_ddev_has_xmr( dh ) ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_set_gps_xmr_settings_idx @@ -8012,19 +8306,16 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_xmr_settings_idx( MBG_DEV_HANDLE dh, /** * @brief Read the current XMR holdover interval from a device * - * Read a ::SYNTH structure containing the configuration of an optional - * on-board programmable frequency synthesizer. + * The API call ::mbg_chk_dev_has_xmr checks whether + * this call is supported by a device. * - * The macro ::_pcps_has_ri_xmr or the API call ::mbg_dev_has_xmr - * check whether this call is supported by a device. + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::XMR_HOLDOVER_INTV structure to be filled up. + * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::XMR_HOLDOVER_INTV structure to be filled up - * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances * @see ::mbg_get_gps_all_xmr_status * @see ::mbg_get_gps_all_xmr_info @@ -8033,7 +8324,7 @@ _MBG_API_ATTR int _MBG_API mbg_set_gps_xmr_settings_idx( MBG_DEV_HANDLE dh, _MBG_API_ATTR int _MBG_API mbg_get_xmr_holdover_status( MBG_DEV_HANDLE dh, XMR_HOLDOVER_STATUS *p, const XMULTI_REF_INSTANCES *p_xmri ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; if ( !( p_xmri->flags & XMRIF_MSK_HOLDOVER_STATUS_SUPP ) ) return MBG_ERR_NOT_SUPP_BY_DEV; @@ -8043,7 +8334,7 @@ _MBG_API_ATTR int _MBG_API mbg_get_xmr_holdover_status( MBG_DEV_HANDLE dh, XMR_H _pcps_ddev_has_xmr( dh ) ); _mbg_swab_xmr_holdover_status( p ); - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbg_get_xmr_holdover_status @@ -8051,21 +8342,22 @@ _MBG_API_ATTR int _MBG_API mbg_get_xmr_holdover_status( MBG_DEV_HANDLE dh, XMR_H /*HDR*/ /** - * @brief Read the CPU affinity of a process. + * @brief Read the CPU affinity of a process * - * This means on which of the available CPUs or CPU cores the process can be executed. + * This means on which of the available CPUs or CPU cores + * a process may be executed. * - * @param pid The process ID. - * @param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. + * @param[in] pid The process ID. + * @param[out] p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. * - * @return ::MBG_SUCCESS or error code returned by the system call. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_set_process_affinity * @see ::mbg_set_current_process_affinity_to_cpu */ _MBG_API_ATTR int _MBG_API mbg_get_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p ) { - #if defined( MBG_TGT_LINUX ) + #if defined( MBG_TGT_LINUX ) // TODO Eventually generally for POSIX? if ( sched_getaffinity( pid, sizeof( *p ), p ) == 0 ) // success return MBG_SUCCESS; @@ -8076,7 +8368,10 @@ _MBG_API_ATTR int _MBG_API mbg_get_process_affinity( MBG_PROCESS_ID pid, MBG_CPU MBG_CPU_SET system_affinity_mask = 0; - return GetProcessAffinityMask( pid, p, &system_affinity_mask ) ? 0 : -1; + if ( GetProcessAffinityMask( pid, p, &system_affinity_mask ) ) + return MBG_SUCCESS; + + return mbg_get_last_error( NULL ); #else @@ -8091,27 +8386,33 @@ _MBG_API_ATTR int _MBG_API mbg_get_process_affinity( MBG_PROCESS_ID pid, MBG_CPU /*HDR*/ /** * @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. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * + * This determines on which of the available CPUs + * or CPU cores the process is allowed to be executed. + * + * @param[in] pid The process ID. + * @param[out] p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_process_affinity * @see ::mbg_set_current_process_affinity_to_cpu - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p ) { - #if defined( MBG_TGT_LINUX ) + #if defined( MBG_TGT_LINUX ) // TODO Eventually generally for POSIX? + + if ( sched_setaffinity( pid, sizeof( *p ), p ) == 0 ) + return MBG_SUCCESS; - return sched_setaffinity( pid, sizeof( *p ), p ); + return mbg_get_last_error( NULL ); #elif defined( MBG_TGT_WIN32 ) - return SetProcessAffinityMask( pid, *p ) ? 0 : -1; + if ( SetProcessAffinityMask( pid, *p ) ) + return MBG_SUCCESS; + + return mbg_get_last_error( NULL ); #else @@ -8125,17 +8426,17 @@ _MBG_API_ATTR int _MBG_API mbg_set_process_affinity( MBG_PROCESS_ID pid, MBG_CPU /*HDR*/ /** - * @brief Set the CPU affinity of a process for a single CPU only. - - This means the process may only be executed on that single CPU. - - @param cpu_num The number of the CPU. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * @brief Set the CPU affinity of a process for a single CPU only + * + * This means the process may only be executed on that single CPU. + * + * @param[in] cpu_num The number of the CPU. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_process_affinity * @see ::mbg_set_process_affinity - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_current_process_affinity_to_cpu( int cpu_num ) { MBG_CPU_SET cpu_set; @@ -8154,25 +8455,28 @@ _MBG_API_ATTR int _MBG_API mbg_set_current_process_affinity_to_cpu( int cpu_num /*HDR*/ /** * @brief Create a new execution thread for the current process. - - This function is only implemented for targets which support threads. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure to be filled up. - @param fnc The name of the thread function to be started. - @param arg A generic argument passed to the thread function. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * + * This function is only implemented for targets that support threads. + * + * @param[in] p_ti Pointer to a ::MBG_THREAD_INFO structure to be filled up. + * @param[in] fnc The name of the thread function to be started. + * @param[in] arg A generic argument passed to the thread function. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_thread_stop * @see ::mbg_thread_sleep_interruptible * @see ::mbg_thread_set_affinity - */ + */ _MBG_API_ATTR int _MBG_API mbg_thread_create( MBG_THREAD_INFO *p_ti, MBG_THREAD_FNC fnc, void *arg ) { - #if defined( MBG_TGT_LINUX ) + #if defined( MBG_TGT_LINUX ) // TODO Eventually generally for POSIX? + + if ( pthread_create( &p_ti->thread_id, NULL, fnc, arg ) == 0 ) + return MBG_SUCCESS; - return pthread_create( &p_ti->thread_id, NULL, fnc, arg ); + return mbg_get_last_error( NULL ); #elif defined( MBG_TGT_WIN32 ) @@ -8194,14 +8498,14 @@ _MBG_API_ATTR int _MBG_API mbg_thread_create( MBG_THREAD_INFO *p_ti, p_ti->thread_id = h; - return 0; + return MBG_SUCCESS; fail: - return GetLastError(); + return mbg_get_last_error( NULL ); #else - return -1; + return MBG_ERR_NOT_SUPP_ON_OS; #endif @@ -8211,26 +8515,30 @@ fail: /*HDR*/ /** - * @brief Stop a thread which has been created by mbg_thread_create(). - - Wait until the thread has finished and release all resources. - This function is only implemented for targets which support threads. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * @brief Stop a thread which has been created by ::mbg_thread_create. + * + * Wait until the thread has finished and release all resources. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_thread_create * @see ::mbg_thread_sleep_interruptible * @see ::mbg_thread_set_affinity - */ + */ _MBG_API_ATTR int _MBG_API mbg_thread_stop( MBG_THREAD_INFO *p_ti ) { - #if defined( MBG_TGT_LINUX ) + #if defined( MBG_TGT_LINUX ) // TODO Eventually generally for POSIX? pthread_cancel( p_ti->thread_id ); - return pthread_join( p_ti->thread_id, NULL ); + if ( pthread_join( p_ti->thread_id, NULL ) == 0 ) + return MBG_SUCCESS; + + return mbg_get_last_error( NULL ); #elif defined( MBG_TGT_WIN32 ) @@ -8243,14 +8551,14 @@ _MBG_API_ATTR int _MBG_API mbg_thread_stop( MBG_THREAD_INFO *p_ti ) CloseHandle( p_ti->thread_id ); p_ti->thread_id = NULL; - return 0; + return MBG_SUCCESS; } - return GetLastError(); + return mbg_get_last_error( NULL ); #else - return -1; + return MBG_ERR_NOT_SUPP_ON_OS; #endif @@ -8260,29 +8568,32 @@ _MBG_API_ATTR int _MBG_API mbg_thread_stop( MBG_THREAD_INFO *p_ti ) /*HDR*/ /** - * @brief Let the current thread sleep for a certain interval. - - The sleep is interrupted if a signal is received indicating - the thread should terminate. - - This function is only implemented for targets which support threads. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. - @param sleep_ms The number of milliseconds to sleep - * @return 0 if the sleep interval has expired normally - 1 if a signal to terminate has been received - <0 if an error has occurred - + * @brief Let the current thread sleep for a certain interval + * + * The sleep is interrupted if a signal is received indicating + * the thread should terminate. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. + * @param[in] sleep_ms The number of milliseconds to sleep + * + * @return MBG_SUCCESS if the sleep interval has expired normally, + * MBG_ERR_INTR if a signal to terminate has been received, + * or one of the other @ref MBG_ERROR_CODES + * * @see ::mbg_thread_create * @see ::mbg_thread_stop * @see ::mbg_thread_set_affinity - */ + */ _MBG_API_ATTR int _MBG_API mbg_thread_sleep_interruptible( MBG_THREAD_INFO *p_ti, ulong sleep_ms ) { - #if defined( MBG_TGT_LINUX ) + #if defined( MBG_TGT_LINUX ) // TODO Eventually generally for POSIX? - usleep( sleep_ms * 1000 ); - return 0; + if ( usleep( sleep_ms * 1000 ) == 0 ) + return MBG_SUCCESS; + + return mbg_get_last_error( NULL ); #elif defined( MBG_TGT_WIN32 ) @@ -8291,17 +8602,17 @@ _MBG_API_ATTR int _MBG_API mbg_thread_sleep_interruptible( MBG_THREAD_INFO *p_ti switch ( dw ) { case WAIT_OBJECT_0: // has been interrupted to terminate - return 1; + return MBG_ERR_INTR; case WAIT_TIMEOUT: // sleep interval expired without interruption - return 0; + return MBG_SUCCESS; } - return -1; + return mbg_get_last_error( NULL ); #else - return -1; + return MBG_ERR_NOT_SUPP_ON_OS; #endif @@ -8313,37 +8624,43 @@ _MBG_API_ATTR int _MBG_API mbg_thread_sleep_interruptible( MBG_THREAD_INFO *p_ti /*HDR*/ /** - * @brief Set the CPU affinity of a single thread. - - This determines on which of the available CPUs the thread - is allowed to be executed. - - This function is only implemented for targets which support thread affinity. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. - @param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * @brief Set the CPU affinity of a single thread + * + * This determines on which of the available CPUs the thread + * is allowed to be executed. + * + * This function is only implemented for targets that support thread affinity. + * + * @param[in,out] p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. + * @param[in] p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_thread_create * @see ::mbg_thread_stop * @see ::mbg_thread_sleep_interruptible - */ + */ _MBG_API_ATTR int _MBG_API mbg_thread_set_affinity( MBG_THREAD_INFO *p_ti, MBG_CPU_SET *p ) { - #if defined( MBG_TGT_LINUX ) + #if defined( MBG_TGT_LINUX ) // TODO Eventually generally for POSIX? - return pthread_setaffinity_np( tid, sizeof( *p ), p ); + if ( pthread_setaffinity_np( tid, sizeof( *p ), p ) == 0 ) + return MBG_SUCCESS; + + return mbg_get_last_error( NULL ); #elif defined( MBG_TGT_WIN32 ) MBG_CPU_SET prv_thread_affinity = SetThreadAffinityMask( p_ti->thread_id, *p ); - return prv_thread_affinity ? 0 : -1; + if ( prv_thread_affinity ) + return MBG_SUCCESS; + + return mbg_get_last_error( NULL ); #else - return -1; + return MBG_ERR_NOT_SUPP_ON_OS; #endif @@ -8356,31 +8673,31 @@ _MBG_API_ATTR int _MBG_API mbg_thread_set_affinity( MBG_THREAD_INFO *p_ti, MBG_C static /*HDR*/ /** * @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 - 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 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. - + * + * 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 + * 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 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 that support threads. + * + * @param[in,out] p_void Pointer to a ::MBG_POLL_THREAD_INFO structure. + * * @return ::MBG_SUCCESS or nothing, depending on the taget system. - + * * @see ::mbg_xhrt_poll_thread_create * @see ::mbg_xhrt_poll_thread_stop * @see ::mbg_get_xhrt_time_as_pcps_hr_time * @see ::mbg_get_xhrt_time_as_filetime * @see ::mbg_get_xhrt_cycles_frequency - */ + */ MBG_THREAD_FNC_RET_VAL MBG_THREAD_FNC_ATTR mbg_xhrt_poll_thread_fnc( void *p_void ) { MBG_XHRT_VARS prv_xhrt_vars; @@ -8403,7 +8720,7 @@ MBG_THREAD_FNC_RET_VAL MBG_THREAD_FNC_ATTR mbg_xhrt_poll_thread_fnc( void *p_voi xhrt_vars.pcps_hr_tstamp64 = pcps_time_stamp_to_uint64( &xhrt_vars.htc.t.tstamp ); if ( prv_xhrt_vars.pcps_hr_tstamp64 && ( ( xhrt_vars.htc.t.status & PCPS_LS_ENB ) == 0 ) ) - freq = ( mbg_delta_pc_cycles( &xhrt_vars.htc.cycles, &prv_xhrt_vars.htc.cycles ) * PCPS_HRT_BIN_FRAC_SCALE ) + freq = ( mbg_delta_pc_cycles( &xhrt_vars.htc.cycles, &prv_xhrt_vars.htc.cycles ) * MBG_FRAC32_UNITS_PER_SEC ) / ( xhrt_vars.pcps_hr_tstamp64 - prv_xhrt_vars.pcps_hr_tstamp64 ); } @@ -8429,39 +8746,42 @@ MBG_THREAD_FNC_RET_VAL MBG_THREAD_FNC_ATTR mbg_xhrt_poll_thread_fnc( void *p_voi if ( mbg_rc_is_success( rc ) ) prv_xhrt_vars = xhrt_vars; - if ( mbg_thread_sleep_interruptible( &p_pti->ti, sleep_ms ) ) + if ( mbg_rc_is_error( mbg_thread_sleep_interruptible( &p_pti->ti, sleep_ms ) ) ) break; } - _mbg_thread_exit( 0 ); + _mbg_thread_exit( MBG_SUCCESS ); // TODO or an optional error code? } // mbg_xhrt_poll_thread_fnc +MBG_THREAD_FNC mbg_xhrt_poll_thread_fnc; + /*HDR*/ /** - * @brief Set up a ::MBG_POLL_THREAD_INFO structure and start a new thread. - - The new thread runs the mbg_xhrt_poll_thread_fnc() function. - - This function is only implemented for targets which support threads. - - @param *p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. - @param dh the handle of the device to be polled. - @param freq_hz The initial cycles frequency, if known, in Hz. - @param sleep_ms the sleep interval for the poll thread function in ms. - If this parameter is 0 then the default sleep interval is used. - + * @brief Set up a ::MBG_POLL_THREAD_INFO structure and start a new thread + * + * The new thread runs a function which periodically reads + * a time stamp / cycles pair from a device. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. + * @param[in] dh the Handle of the device to be polled. + * @param[in] freq_hz The initial cycles frequency, if known, in Hz. + * @param[in] sleep_ms the sleep interval for the poll thread function in ms. + * If this parameter is 0 then the default sleep interval is used. + * * @return ::MBG_SUCCESS on success, - ::MBG_ERR_NOT_SUPP_BY_DEV if the device to poll does not support HR time - else the result of mbg_thread_create() - + * ::MBG_ERR_NOT_SUPP_BY_DEV if the device to poll does not support HR time + * else the result of ::mbg_thread_create. + * * @see ::mbg_xhrt_poll_thread_stop * @see ::mbg_get_xhrt_time_as_pcps_hr_time * @see ::mbg_get_xhrt_time_as_filetime * @see ::mbg_get_xhrt_cycles_frequency - */ + */ _MBG_API_ATTR int _MBG_API mbg_xhrt_poll_thread_create( MBG_POLL_THREAD_INFO *p_pti, MBG_DEV_HANDLE dh, MBG_PC_CYCLES_FREQUENCY freq_hz, int sleep_ms ) { @@ -8487,19 +8807,19 @@ _MBG_API_ATTR int _MBG_API mbg_xhrt_poll_thread_create( MBG_POLL_THREAD_INFO *p_ /*HDR*/ /** - * @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() - + * @brief Stop a polling thread started by ::mbg_xhrt_poll_thread_create + * + * This call also releases all associated resources. + * + * @param[in,out] p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. + * + * @return The result of ::mbg_thread_stop. + * * @see ::mbg_xhrt_poll_thread_create * @see ::mbg_get_xhrt_time_as_pcps_hr_time * @see ::mbg_get_xhrt_time_as_filetime * @see ::mbg_get_xhrt_cycles_frequency - */ + */ _MBG_API_ATTR int _MBG_API mbg_xhrt_poll_thread_stop( MBG_POLL_THREAD_INFO *p_pti ) { int rc = mbg_thread_stop( &p_pti->ti ); @@ -8513,8 +8833,33 @@ _MBG_API_ATTR int _MBG_API mbg_xhrt_poll_thread_stop( MBG_POLL_THREAD_INFO *p_pt -static /*HDR*/ -int mbg_get_xhrt_data( MBG_XHRT_INFO *p, uint64_t *tstamp, MBG_XHRT_VARS *vars ) +static __mbg_inline /*HDR*/ +/** + * @brief Retrieve an extrapolated time stamp + * + * Get the system's current cycles count and compute the current time + * based on last recent time stamp/cycles pair read by the polling thread. + * + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * This function is only implemented for targets that support threads. + * + * @param[in] p Pointer to a ::MBG_XHRT_INFO structure providing data from the polling thread. + * @param[out] p_tstamp Optional pointer to a variable to take the extrapolated time stamp, may be NULL. + * @param[out] p_vars Optional pointer to a ::MBG_XHRT_VARS structure to be filled up, may be NULL. + * + * @return The return code from the API call used by the polling thread + * to read the time from the device, usually ::mbg_get_hr_time_cycles, + * so ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * + * @ingroup mbg_xhrt_poll_group + * @see ::mbg_xhrt_poll_thread_create + * @see ::mbg_xhrt_poll_thread_stop + * @see ::mbg_get_xhrt_time_as_filetime + * @see ::mbg_get_xhrt_cycles_frequency + * @see @ref mbg_xhrt_poll_group + */ +int mbg_get_xhrt_data( MBG_XHRT_INFO *p, uint64_t *p_tstamp, MBG_XHRT_VARS *p_vars ) { MBG_XHRT_VARS xhrt_vars; MBG_PC_CYCLES cyc_now; @@ -8533,15 +8878,15 @@ int mbg_get_xhrt_data( MBG_XHRT_INFO *p, uint64_t *tstamp, MBG_XHRT_VARS *vars ) if ( freq_hz && xhrt_vars.pcps_hr_tstamp64 ) { t_now = xhrt_vars.pcps_hr_tstamp64 + - ( mbg_delta_pc_cycles( &cyc_now, &xhrt_vars.htc.cycles ) * PCPS_HRT_BIN_FRAC_SCALE ) / freq_hz; + ( mbg_delta_pc_cycles( &cyc_now, &xhrt_vars.htc.cycles ) * MBG_FRAC32_UNITS_PER_SEC ) / freq_hz; mbg_chk_tstamp64_leap_sec( &t_now, &xhrt_vars.htc.t.status ); } - if ( tstamp ) - *tstamp = t_now; + if ( p_tstamp ) + *p_tstamp = t_now; - if ( vars ) - *vars = xhrt_vars; + if ( p_vars ) + *p_vars = xhrt_vars; return ioctl_status; @@ -8551,24 +8896,28 @@ int mbg_get_xhrt_data( MBG_XHRT_INFO *p, uint64_t *tstamp, MBG_XHRT_VARS *vars ) /*HDR*/ /** - * @brief Retrieve an extrapolated time stamp in PCPS_HR_TIME format. - - The time stamp is extrapolated using the system's current cycles counter value - and a time stamp plus associated cycles counter value saved by the polling thread. - See mbg_xhrt_poll_thread_fnc() for details and limitations. - - This function is only implemented for targets which support threads. - - @param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. - @param *p_hrt Pointer to a ::PCPS_HR_TIME structure to be filled up. - - * @return MBG_SUCCESS or another return value from the polling thread's IOCTL call. - + * @brief Retrieve an extrapolated time stamp in ::PCPS_HR_TIME format + * + * The time stamp is extrapolated using the system's current cycles counter value + * and a time stamp plus associated cycles counter value saved by the polling thread. + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. + * @param[out] p_hrt Pointer to a ::PCPS_HR_TIME structure to be filled up. + * + * @return The return code from the API call used by the polling thread + * to read the time from the device, usually ::mbg_get_hr_time_cycles, + * so ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * + * @ingroup mbg_xhrt_poll_group * @see ::mbg_xhrt_poll_thread_create * @see ::mbg_xhrt_poll_thread_stop * @see ::mbg_get_xhrt_time_as_filetime * @see ::mbg_get_xhrt_cycles_frequency - */ + * @see @ref mbg_xhrt_poll_group + */ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_pcps_hr_time( MBG_XHRT_INFO *p, PCPS_HR_TIME *p_hrt ) { uint64_t tstamp64; @@ -8597,25 +8946,29 @@ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_pcps_hr_time( MBG_XHRT_INFO *p, /*HDR*/ /** - * @brief Retrieve an extrapolated time stamp in FILETIME format. - - The time stamp is extrapolated using the system's current cycles counter value - and a time stamp plus associated cycles counter value saved by the polling thread. - See mbg_xhrt_poll_thread_fnc() for details and limitations. - - Since FILETIME is a Windows specific type this function is only - implemented under Windows. - - @param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. - @param *p_ft Pointer to a FILETIME structure to be filled up. - - * @return MBG_SUCCESS or another return value from the polling thread's IOCTL call. - + * @brief Retrieve an extrapolated time stamp in FILETIME format + * + * The time stamp is extrapolated using the system's current cycles counter value + * and a time stamp plus associated cycles counter value saved by the polling thread. + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * Since FILETIME is a Windows-specific type this function is only + * implemented under Windows. + * + * @param[in,out] p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. + * @param[out] p_ft Pointer to a FILETIME structure to be filled up. + * + * @return The return code from the API call used by the polling thread + * to read the time from the device, usually ::mbg_get_hr_time_cycles, + * so ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * + * @ingroup mbg_xhrt_poll_group * @see ::mbg_xhrt_poll_thread_create * @see ::mbg_xhrt_poll_thread_stop * @see ::mbg_get_xhrt_time_as_pcps_hr_time * @see ::mbg_get_xhrt_cycles_frequency - */ + * @see @ref mbg_xhrt_poll_group + */ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_filetime( MBG_XHRT_INFO *p, FILETIME *p_ft ) { uint64_t tstamp64; @@ -8638,22 +8991,27 @@ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_filetime( MBG_XHRT_INFO *p, FILE /*HDR*/ /** - * @brief Retrieve the frequency of the system's cycles counter. - - The frequency is determined by the device polling thread. - See mbg_xhrt_poll_thread_fnc() for details and limitations. - - This function is only implemented for targets which support threads. - - @param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. - @param *p_freq_hz Pointer to a ::MBG_PC_CYCLES_FREQUENCY variable in which the frequency is returned. - * @return a status code from the polling thread: MBG_SUCCESS or an IOCTL error code. - + * @brief Retrieve the frequency of the system's cycles counter + * + * The frequency is determined by the device polling thread. + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. + * @param[out] p_freq_hz Pointer to a ::MBG_PC_CYCLES_FREQUENCY variable in which the frequency is returned. + * + * @return The return code from the API call used by the polling thread + * to read the time from the device, usually ::mbg_get_hr_time_cycles, + * so ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * + * @ingroup mbg_xhrt_poll_group * @see ::mbg_xhrt_poll_thread_create * @see ::mbg_xhrt_poll_thread_stop * @see ::mbg_get_xhrt_time_as_pcps_hr_time * @see ::mbg_get_xhrt_time_as_filetime - */ + * @see @ref mbg_xhrt_poll_group + */ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_cycles_frequency( MBG_XHRT_INFO *p, MBG_PC_CYCLES_FREQUENCY *p_freq_hz ) { MBG_PC_CYCLES_FREQUENCY freq_hz; @@ -8677,21 +9035,21 @@ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_cycles_frequency( MBG_XHRT_INFO *p, MBG_ /*HDR*/ /** - * @brief Retrieve the default system's cycles counter frequency from the kernel driver. - - This API call can be used on systems which don't provide this information in user space. - - @param dh handle of the device to which the IOCTL call is sent. - @param *p Pointer of a ::MBG_PC_CYCLES_FREQUENCY variable to be filled up. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Retrieve the system's default cycles counter frequency from the kernel driver + * + * This API call can be used on systems which don't provide this information in user space. + * + * @param[in] dh Handle of the device to which the IOCTL call is sent. + * @param[out] p Pointer of a ::MBG_PC_CYCLES_FREQUENCY variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_default_cycles_frequency - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_default_cycles_frequency_from_dev( MBG_DEV_HANDLE dh, MBG_PC_CYCLES_FREQUENCY *p ) { #if defined( _MBGIOCTL_H ) - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_CYCLES_FREQUENCY, p ); // native endianess, no need to swap bytes if ( mbg_rc_is_error( rc ) ) @@ -8724,13 +9082,13 @@ _MBG_API_ATTR int _MBG_API mbg_get_default_cycles_frequency_from_dev( MBG_DEV_HA // compute cycles frequency from delta htc delta_cycles = mbg_delta_pc_cycles( &htc2.cycles, &htc1.cycles ); delta_t = pcps_time_stamp_to_uint64( &htc2.t.tstamp ) - pcps_time_stamp_to_uint64( &htc1.t.tstamp ); - *p = ( delta_cycles * PCPS_HRT_BIN_FRAC_SCALE ) / delta_t; + *p = ( delta_cycles * MBG_FRAC32_UNITS_PER_SEC ) / delta_t; } } done: #endif - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); #else @@ -8746,16 +9104,16 @@ done: /*HDR*/ /** - @brief Retrieve the system's default cycles counter frequency. - - @note This may not be supported on all target platforms, in which case the - returned frequency is 0 and the mbg_get_default_cycles_frequency_from_dev() - call should be used. - - @return the default cycles counter frequency in Hz, or 0 if the value is not available. - + * @brief Retrieve the system's default cycles counter frequency + * + * @note This may not be supported on all target platforms, in which case the + * returned frequency is 0 and the ::mbg_get_default_cycles_frequency_from_dev + * call should be used instead. + * + * @return the default cycles counter frequency in Hz, or 0 if the value is not available. + * * @see ::mbg_get_default_cycles_frequency_from_dev -*/ + */ _MBG_API_ATTR MBG_PC_CYCLES_FREQUENCY _MBG_API mbg_get_default_cycles_frequency( void ) { #if defined MBG_TGT_WIN32 diff --git a/mbglib/common/mbgdevio.h b/mbglib/common/mbgdevio.h index 70f5ef5..440ceda 100755 --- a/mbglib/common/mbgdevio.h +++ b/mbglib/common/mbgdevio.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgdevio.h 1.41.1.30.1.11 2017/03/17 12:00:39 martin TEST $ + * $Id: mbgdevio.h 1.42 2017/07/05 15:20:32 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,71 +10,22 @@ * * ----------------------------------------------------------------------- * $Log: mbgdevio.h $ - * Revision 1.41.1.30.1.11 2017/03/17 12:00:39 martin - * Include cfg_hlp.h due to moved definitions. - * Revision 1.41.1.30.1.10 2017/02/01 16:23:19 martin - * Updated function prototypes. - * Revision 1.41.1.30.1.9 2016/10/20 11:25:21 martin - * Improved handling of ioctl error codes for POSIX. - * Revision 1.41.1.30.1.8 2016/10/17 17:12:44 martin - * Account for MBG_ERROR_CODES returned by the ioctl function under Linux. - * Revision 1.41.1.30.1.7 2016/09/23 08:54:21 martin - * Exclude mbg_chk_tstamp64_leap_sec() for BC builds for now. - * Revision 1.41.1.30.1.6 2016/09/22 08:30:40Z martin - * Fixed compiler warning under Windows x64. - * Revision 1.41.1.30.1.5 2016/08/11 07:48:12Z martin - * Fixed a compiler warning. - * Revision 1.41.1.30.1.4 2016/08/10 12:27:03Z martin - * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. - * Revision 1.41.1.30.1.3 2016/07/22 09:57:11 martin - * Quieted some compiler warninges. - * Revision 1.41.1.30.1.2 2016/07/15 14:09:48 martin + * Revision 1.42 2017/07/05 15:20:32 martin + * New MBGDEVIO_VERSION 0x0400, compatibility version unchanged. + * Account for MBG_ERROR_CODES returned by the ioctl functions. + * New type MBG_DEV_FN used for device file names, formerly often + * referred to as 'hardware ID'. + * New type MBG_DEV_NAME used for unique device names, composed of + * device type name and serial number appended after an underscore. + * Renamed and reworked list handling for device lists. * Use functions from new module timeutil. - * Revision 1.41.1.30.1.1 2016/05/30 15:07:32 martin - * *** empty log message *** - * Revision 1.41.1.30 2015/12/02 17:05:03 martin - * *** empty log message *** - * Revision 1.41.1.29 2015/12/02 16:36:19 martin - * *** empty log message *** - * Revision 1.41.1.28 2015/12/01 17:01:03 martin - * *** empty log message *** - * Revision 1.41.1.27 2015/12/01 13:58:33 martin - * *** empty log message *** - * Revision 1.41.1.26 2015/10/27 16:22:24 martin - * Older defines N_SUPP_DEV, PCPS_MAX_DDEVS, and MBG_MAX_DEVICES - * have been obsoleted by new defines N_SUPP_DEV_BUS, N_SUPP_DEV_EXT, - * and N_SUPP_DEV_TOTAL. - * Revision 1.41.1.25 2015/10/21 11:21:54 martin - * *** empty log message *** - * Revision 1.41.1.24 2015/10/20 16:02:04 martin - * *** empty log message *** - * Revision 1.41.1.23 2015/10/20 15:19:27 martin - * *** empty log message *** - * Revision 1.41.1.22 2015/10/19 16:42:18 martin - * *** empty log message *** - * Revision 1.41.1.21 2015/08/27 16:24:16 martin - * Revision 1.41.1.20 2014/11/19 16:33:31 martin - * Revision 1.41.1.19 2014/11/19 16:15:45 martin - * Revision 1.41.1.18 2014/11/19 16:03:09 martin - * Revision 1.41.1.17 2014/10/29 16:27:16 martin - * Revision 1.41.1.16 2014/07/18 11:01:41 martin - * Revision 1.41.1.15 2014/07/16 15:19:57 martin - * Revision 1.41.1.14 2014/07/16 13:06:39 martin - * Revision 1.41.1.13 2014/07/14 15:42:49 martin - * Revision 1.41.1.12 2014/06/26 12:24:22 martin - * Revision 1.41.1.11 2014/05/27 08:22:20Z martin - * Revision 1.41.1.10 2014/05/26 16:02:13 martin - * Revision 1.41.1.9 2014/05/23 12:40:19 martin - * Revision 1.41.1.8 2014/05/23 09:24:08 martin - * gpio and xmr functions. - * Revision 1.41.1.7 2014/04/23 15:42:59 martin - * Revision 1.41.1.6 2014/04/22 15:27:47 martin - * Revision 1.41.1.5 2014/04/22 13:29:18 martin - * Revision 1.41.1.4 2014/03/28 10:23:24 martin - * Revision 1.41.1.3 2014/03/05 10:38:29 martin - * Windows.h is now included in mbg_tgt.h. - * Revision 1.41.1.2 2014/01/31 14:45:35Z martin - * Revision 1.41.1.1 2013/12/12 11:24:16 martin + * windows.h is now included in mbg_tgt.h. + * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. + * Account for PCPS_HRT_BIN_FRAC_SCALE renamed to MBG_FRAC32_UNITS_PER_SEC. + * Fixed macro definition syntax to avoid clang compiler warnings. + * Exclude mbg_chk_tstamp64_leap_sec() for BC builds for now. + * Lots of new doxygen comments and groups. + * Updated function prototypes. * Revision 1.41 2013/09/26 08:54:54 martin * Defined thread function type MBG_THREAD_FNC. * Defined check-if-supported function type MBG_CHK_SUPP_FNC. @@ -250,9 +201,11 @@ #include <use_pack.h> #include <time.h> +#include <stdio.h> +#include <errno.h> -#define MBGDEVIO_VERSION 0x0307 +#define MBGDEVIO_VERSION 0x0400 #define MBGDEVIO_COMPAT_VERSION 0x0210 @@ -333,16 +286,15 @@ #if defined( MBG_USE_KERNEL_DRIVER ) + #include <mbgioctl.h> + #include <stdlib.h> #include <string.h> #endif -#if defined( MBG_TGT_POSIX ) - #include <stdio.h> - #include <errno.h> - +#if defined( MBG_TGT_POSIX ) && !defined( MBG_TGT_QNX_NTO ) #define MBG_HAS_POSIX_IOCTL 1 #endif @@ -358,8 +310,16 @@ #define MBGDEVIO_HAVE_THREAD_AFFINITY 0 #endif +#if ( 0 && defined( DEBUG ) ) + #define DEBUG_IOCTL 1 +#else + #define DEBUG_IOCTL 0 +#endif + + #ifdef _MBGDEVIO #define _ext + #define _DO_INIT #else #define _ext extern #endif @@ -373,80 +333,9 @@ #endif -//### TODO More detailed information for the function groups below. - -/** - * @defgroup pcps_hr_time_fncs API functions reading high resolution time, plus status - * - * These functions return a high resolution time, including status flags and - * local time offset according to the time zone configuration on the device. - * - * The API call ::mbg_chk_dev_has_hr_time checks if these functions are supported - * by a device. - * - * Due to the extended information returned to the caller these function - * require interaction with the on-board microcontroller, and thus take - * longer to execute. - * - * <b>Note:</b> These API calls provides better accuracy and higher resolution - * than the the standard functions in @ref pcps_std_time_fncs. - * - * The ::mbg_get_hr_time function doesn't account for the latency - * which is introduced when accessing the board. - * The ::mbg_get_hr_time_cycles and ::mbg_get_hr_time_comp calls - * provide ways to account for and/or compensate the latency. - * - * @see ::mbg_chk_dev_has_hr_time - * @see ::mbg_get_hr_time - * @see ::mbg_get_hr_time_cycles - * @see ::mbg_get_hr_time_comp - * @see @ref pcps_hr_time_fncs - * @see @ref pcps_fast_timestamp_fncs - * @see @ref pcps_std_time_fncs - */ - -/** - * @defgroup pcps_fast_timestamp_fncs API functions reading high resolution timestamps, without status - * - * These functions are fast, but return only the UTC time. No status flags, - * no time zone offset. The time stamps are read from a latched counter chain - * in the PCI chip set, so this is only supported by cards whose chi set supports this. - */ - -/** - * @defgroup pcps_std_time_fncs Legacy API functions to read or set the time - * - * These functions are supported by all devices, but return time only - * as a ::PCPS_TIME structure whose resolution is limited to 10 ms. - */ - -/** - * @defgroup pcps_chk_feat_fncs Functions used to check if a particular feature is supported - * - * Each of these functions can be used to check if a device supports a particular feature. - * ::MBG_SUCCESS is returned if the requested feature is supported, otherwise one of the - * @ref MBG_ERROR_CODES is returned, as appropriate. - */ - -/** - * @defgroup pcps_chk_feat_fncs_deprecated Deprecated functions used to check if a particular feature is supported - * - * @deprecated These function are deprecated. Use the @ref pcps_chk_feat_fncs preferably. - * - * These deprecated functions can still be used to check if a device supports - * a particular feature, and will be kept for compatibility. - * - * However, they return an error code if the call itself failed, and only if the - * call succeeded a flag variable is set up telling if the requested feature - * is supported, or not. So it's not very handy for an application to check both - * of these condition for every single call. - * - * There are newer replacement functions available which can be used in a - * much easier way. - * - * @see @ref pcps_chk_feat_fncs - */ - +#ifdef __cplusplus +extern "C" { +#endif // If MBGDEVIO_SIMPLE != 0 then some complex configuration // API calls are excluded from build, which would otherwise @@ -483,22 +372,42 @@ #endif -#define _mbgdevio_vars() \ - MBGDEVIO_RET_VAL rc +/** + * @brief An string that can take a device file name + * + * The format of the device file name depends on the type of + * operating system. + * + * On Linux and similar systems this is something like + * a regular file name with an index number appended, + * e.g. "/dev/mbgclock0". See ::MBGCLOCK_DEV_FN_BASE. + * + * Under Windows this is a complex string composed of GUIDs, + * bus-specific vendor and device ID numbers, etc., which can't + * easily be handled manually. + */ +typedef char MBG_DEV_FN[260]; // Conforming to MAX_PATH in Windows -#define _mbgdevio_ret_val \ - _mbgdevio_cnv_ret_val( rc ) +#if MBG_TGT_HAS_DEV_FN +#define MBGCLOCK_DEV_FN_BASE "/dev/mbgclock" +#define MBGCLOCK_DEV_FN_FMT MBGCLOCK_DEV_FN_BASE "%i" + +_ext const char mbg_dev_fn_base[] +#ifdef _DO_INIT + = MBGCLOCK_DEV_FN_BASE +#endif +; + +_ext const char mbg_dev_fn_fmt[] +#ifdef _DO_INIT + = MBGCLOCK_DEV_FN_FMT +#endif +; + +#endif -/** - * @brief A string buffer for a unique device ID - * - * The unique ID is made up of the device model name - * and its serial number, i.e. [model_name]_[serial_number] - * E.g.: "GPS170PCI_028210040670" - */ -typedef char MBG_HW_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; // Definitions specific to the target OS @@ -542,12 +451,9 @@ typedef char MBG_HW_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; #if !defined( MBG_TGT_WIN32 ) - - #define FILETIME int // just a dummy to avoid build errors - + #define FILETIME int // just a dummy to avoid build errors #endif - #if !defined( MBG_PROCESS_ID ) #define MBG_PROCESS_ID int #endif @@ -598,24 +504,57 @@ typedef char MBG_HW_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; #endif + +/** + * @brief A generic thread info structure + */ typedef struct { MBG_THREAD_ID thread_id; #if defined( MBG_TGT_WIN32 ) HANDLE exit_request; #endif + } MBG_THREAD_INFO; -typedef MBG_THREAD_FNC_RET_VAL (MBG_THREAD_FNC_ATTR *MBG_THREAD_FNC)(void *); +/** + * @brief A generic type of a thread function + */ +typedef MBG_THREAD_FNC_RET_VAL MBG_THREAD_FNC_ATTR MBG_THREAD_FNC( void * ); + + + +/** + * @brief A structure holding a time stamp / cycles count pair + * + * This can be used to extrapolate the current time from the current + * system cycles count. + * + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * @see @ref mbg_xhrt_poll_group + */ typedef struct { - PCPS_HR_TIME_CYCLES htc; - uint64_t pcps_hr_tstamp64; + PCPS_HR_TIME_CYCLES htc; ///< Cycles count associated with the time stamp + uint64_t pcps_hr_tstamp64; ///< Time stamp read from a device + } MBG_XHRT_VARS; + +/** + * @brief A status structure provided by the time polling thread function + * + * This can be used to get information from the poll thread function + * and extrapolate the current time from the current system cycles count. + * + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * @see @ref mbg_xhrt_poll_group + */ typedef struct { MBG_XHRT_VARS vars; @@ -625,13 +564,25 @@ typedef struct int sleep_ms; MBG_CRIT_SECT crit_sect; MBG_DEV_HANDLE dh; + } MBG_XHRT_INFO; + +/** + * @brief A structure used to control a poll thread function + * + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * @see ::mbg_xhrt_poll_thread_create + * @see ::mbg_xhrt_poll_thread_stop + * @see @ref mbg_xhrt_poll_group + */ typedef struct { MBG_XHRT_INFO xhrt_info; MBG_THREAD_INFO ti; + } MBG_POLL_THREAD_INFO; @@ -642,44 +593,255 @@ typedef struct * Match modes to determine how to proceed if a device with * particular model type and serial number has not been detected. */ -enum MBG_MATCH_MODE +enum MBG_MATCH_MODES { MBG_MATCH_ANY, ///< use the next device available on the system MBG_MATCH_MODEL, ///< use the next available device of the same type MBG_MATCH_EXACTLY, ///< use only exactly the excat matching device, otherwise fail - N_MBG_MATCH_MODE ///< number of known modes + N_MBG_MATCH_MODES ///< number of known modes }; -typedef struct _MBG_DEVICE_LIST +/** + * @brief An entry for a list of device file names + * + * Applications should consider this type as opaque, + * and must not rely on the type, number, and order of + * the structure members. + */ +typedef struct _MBG_DEV_FN_LIST_ENTRY MBG_DEV_FN_LIST_ENTRY; + + +/** + * @brief The structure behind the ::MBG_DEV_FN_LIST_ENTRY type + * + * Applications should consider this structure as opaque, + * and must not rely on the type, number, and order of + * the structure members. + * + * The definition is still in the header file since it + * is still required by some Windows-specific code. + */ +struct _MBG_DEV_FN_LIST_ENTRY { - char *device_path; /**< Hardware ID depending on the calling function */ - struct _MBG_DEVICE_LIST *next; + char *dev_fn_ptr; ///< Address of an OS-specific device file name + ///< that can be used with an OS-specific open call. + MBG_DEV_FN_LIST_ENTRY *next; +}; -} MBG_DEVICE_LIST; +/** + * @brief An entry for a list of device names + * + * Applications should consider this type as opaque, + * and must not rely on the type, number, and order of + * the structure members. + * + * @see ::mbg_find_devices_with_names + * @see ::mbg_free_device_name_list + */ +typedef struct _MBG_DEV_NAME_LIST_ENTRY MBG_DEV_NAME_LIST_ENTRY; + -typedef struct _MBG_DEVICENAME_LIST +/** + * @brief The structure behind the ::MBG_DEV_NAME_LIST_ENTRY type + * + * Applications should actually consider this structure as opaque, + * and must not rely on the type, number, and order of + * the structure members. + * + * The definition is still in the header file since it is still + * used by some Windows-specific code. + */ +struct _MBG_DEV_NAME_LIST_ENTRY { - char device_name[40]; /**< readable name */ - struct _MBG_DEVICENAME_LIST *next; + char dev_name[40]; ///< Readable device name (Should be ::MBG_DEV_NAME, which is smaller, though) + MBG_DEV_NAME_LIST_ENTRY *next; +}; + + + +/** + * @defgroup mbgdevio_open_fncs API functions that can be used to open a device + * + * Each of these functions can be used to open a device to obtain a valid + * ::MBG_DEV_HANDLE handle which can be used with subsequent API calls to + * access the particular device. + * + * If the device fails to be opened then each of these functions returns + * ::MBG_INVALID_DEV_HANDLE, and an OS-specific "last error" code is set + * accordingly. The caller can then use ::mbg_get_last_error immediately + * to retrieve the OS-specific error code, convert it, and return the + * associated Meinberg-specific error code. See @ref MBG_ERROR_CODES. + * + * Operating systems maintain a list of devices that are currently + * present in a system. The function ::mbg_open_device expects a number + * that is used as an index to this list. If only a single supported device + * is present then index 0 can always be used to open that device. + * + * The function ::mbg_find_devices can be used to retrieve the number of + * devices statically present in the system, and the highest index number + * that can be used is the number of devices - 1. + * + * In a plug-and-play system the device list maintained by the operating + * system may change over time, for example if a USB device is plugged in + * or out during operation. In this case index numbers may change, and may + * not always refer to the same device. + * + * So the function ::mbg_open_device_by_name can be used instead to open + * a specific device identified by model name and optionally serial number. + * See ::MBG_DEV_NAME for the format of such device name. + * + * If a list of unique device names is required e.g. to set up a + * device selection dialog in a GUI application then the function + * ::mbg_find_devices_with_names can be used to allocate and set up + * such a list. When the list has been evaluated and isn't needed + * anymore then ::mbg_free_device_name_list should be called to free + * the allocated memory. + * + * Inside the operating system the device is always identified by a + * device file name which can be used internally with an OS-specific + * "open" function, e.g. "open" on POSIX systems, or ""CreateFile" + * on Windows. + * + * While the device file name is a complex string under Windows, + * under Linux and similar systems this is just a device node name + * like "/dev/mbgclock0" which can easily be used to specify a + * particular device. See ::MBG_DEV_FN. + * + * On such systems the function ::mbg_open_device_by_dev_fn can be used + * to open a device specified by a device file name. + * + * @see ::mbg_open_device + * @see ::mbg_find_devices + * @see ::mbg_open_device_by_name + * @see ::mbg_find_devices_with_names + * @see ::mbg_open_device_by_dev_fn + * @see ::mbg_close_device + */ + + +/** + * @defgroup mbgdevio_hr_time_fncs API functions reading high resolution time, plus status + * + * These functions return a high resolution time, including status flags and + * local time offset according to the time zone configuration on the device. + * + * The API call ::mbg_chk_dev_has_hr_time checks if these functions are supported + * by a device. + * + * Due to the extended information returned to the caller these function + * require interaction with the on-board microcontroller, and thus take + * longer to execute than the @ref mbgdevio_fast_timestamp_fncs. + * + * <b>Note:</b> These API calls provides better accuracy and higher resolution + * than the the standard functions in @ref mbgdevio_legacy_time_fncs. + * + * The ::mbg_get_hr_time function doesn't account for the latency + * which is introduced when accessing the board. + * + * The ::mbg_get_hr_time_cycles and ::mbg_get_hr_time_comp calls + * provide ways to account for and/or compensate the latency. + * + * @see ::mbg_chk_dev_has_hr_time + * @see ::mbg_get_hr_time + * @see ::mbg_get_hr_time_cycles + * @see ::mbg_get_hr_time_comp + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs + */ + + +/** + * @defgroup mbgdevio_fast_timestamp_fncs Fast API functions reading high resolution timestamps, but no status + * + * These functions are fast, but return only the UTC time. No status flags, + * no time zone offset. The time stamps are read from a latched counter chain + * in the PCI chip set, so this is only supported by cards whose chip set supports this. + * + * @see ::mbg_chk_dev_has_fast_hr_timestamp + * @see ::mbg_get_fast_hr_timestamp + * @see ::mbg_get_fast_hr_timestamp_cycles + * @see ::mbg_get_fast_hr_timestamp_comp + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_legacy_time_fncs + */ + + +/** + * @defgroup mbgdevio_legacy_time_fncs Legacy API functions to read the time + * + * These functions are supported by all devices, but return time only + * as a ::PCPS_TIME structure, which provides local time according to the + * local time zone configured on the device, and with 10 ms resolution only. + * + * <b>Note:</b> The @ref mbgdevio_hr_time_fncs or @ref mbgdevio_fast_timestamp_fncs + * should be used preferably, if the device supports these. + * + * @see ::mbg_get_time + * @see ::mbg_get_time_cycles + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + */ + + +/** + * @defgroup mbgdevio_chk_supp_fncs mbgdevio functions used to check if a particular feature is supported + * @ingroup chk_supp_fncs + * + * These functions can be used to check if a device supports a particular feature. + * + * ::MBG_SUCCESS is returned if the requested feature is supported, + * ::MBG_ERR_NOT_SUPP_BY_DEV if the feature is not supported, or one of the other + * @ref MBG_ERROR_CODES is returned if an error occurred when trying to determine + * if the feature is supported, e.g. if the IOCTL call itself failed. + */ + + +/** + * @defgroup mbgdevio_chk_supp_fncs_deprecated Deprecated mbgdevio functions to check if a particular feature is supported + * @ingroup chk_supp_fncs + * + * @deprecated These functions are deprecated. Use the @ref mbgdevio_chk_supp_fncs preferably. + * + * These are the original functions that were introduced to check if a device supports + * a particular feature. The functions are deprecated, but will be kept for compatibility. + * + * The functions return ::MBG_SUCCESS if the information could be retrieved with out error, + * and an error code otherwise, e.g. if the IOCTL call itself failed. + * + * Only in case of success an integer variable the address of which has to be passed to the + * function is set to 1 or 0 depending on whether the requested feature is supported, or not. + * So the calling application always has to check 2 values after such function had been called. + * + * To make applications simpler the @ref mbgdevio_chk_supp_fncs have been introduced instead, + * which can be used in a much easier way. + * + * @see @ref mbgdevio_chk_supp_fncs + */ + + + +/** + * @defgroup mbg_xhrt_poll_group Extrapolation of high resolution time stamps + * + * ::TODO + */ -} MBG_DEVICENAME_LIST; /** - * @brief Type of functions to check if a feature is supported + * @brief The type of functions to check if a feature is supported + * + * @ingroup mbgdevio_chk_supp_fncs + * @see @ref mbgdevio_chk_supp_fncs */ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); -/* function prototypes: */ -#ifdef __cplusplus -extern "C" { -#endif /* ----- function prototypes begin ----- */ @@ -695,7 +857,7 @@ extern "C" { * been used to build the library, and thus the API function are called * in the correct way. * - * @return the version number + * @return The version number * * @see ::mbgdevio_check_version * @see ::MBGDEVIO_VERSION defined in mbgdevio.h @@ -714,7 +876,7 @@ extern "C" { * @param[in] header_version Version number to be checked, should be ::MBGDEVIO_VERSION * from the mbgdevio.h file version used to build the application * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE * * @see ::mbgdevio_get_version * @see ::MBGDEVIO_VERSION defined in mbgdevio.h @@ -726,7 +888,7 @@ extern "C" { * * Very old devices may not provide a ::RECEIVER_INFO structure. * The ::mbg_setup_receiver_info call should be used preferably to set up - * a ::RECEIVER_INFO for a device. The function uses this call to determine + * a ::RECEIVER_INFO for a device. That function uses this call to determine * whether a ::RECEIVER_INFO can be read directly from a device, or sets up * a default structure using default values depending on the device type. * @@ -736,8 +898,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_setup_receiver_info * @see ::mbg_get_gps_receiver_info */ @@ -748,7 +911,7 @@ extern "C" { * * Such structures have been introduced with the first Meinberg GPS receivers. * Mostly all configuration structures are large data structures, and mostly all - * current devices support this, but some very old devices may not. + * current devices support this, but some old devices may not. * * @note This function should be preferred over ::mbg_dev_has_gps_data, * which has been deprecated. @@ -756,7 +919,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_gps_data( MBG_DEV_HANDLE dh ) ; @@ -771,8 +936,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_generic_io */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_generic_io( MBG_DEV_HANDLE dh ) ; @@ -780,8 +946,8 @@ extern "C" { /** * @brief Check if a device supports the ::mbg_get_asic_version API call. * - * It depends on the bus interface chip assembled on the device - * if ::mbg_get_asic_version is supported, or not. + * If ::mbg_get_asic_version is supported, or not, depends on + * the bus interface chip assembled on the device. * * @note This function should be preferred over ::mbg_dev_has_asic_version, * which has been deprecated. @@ -789,8 +955,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_asic_version */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_asic_version( MBG_DEV_HANDLE dh ) ; @@ -798,8 +965,8 @@ extern "C" { /** * @brief Check if a device supports the ::mbg_get_asic_features call. * - * It depends on the bus interface chip assembled on the device - * if ::mbg_get_asic_features is supported, or not. + * If ::mbg_get_asic_features is supported, or not, depends on + * the bus interface chip assembled on the device. * * @note This function should be preferred over ::mbg_dev_has_asic_features, * which has been deprecated. @@ -807,8 +974,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_asic_features */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_asic_features( MBG_DEV_HANDLE dh ) ; @@ -825,83 +993,82 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_xmr_instances * @see ::mbg_get_gps_all_xmr_status * @see ::mbg_get_gps_all_xmr_info * @see ::mbg_set_gps_xmr_settings_idx * @see ::mbg_get_xmr_holdover_status */ - _MBG_API_ATTR int _MBG_API mbg_chk_dev_supp_xmr( MBG_DEV_HANDLE dh ) ; + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_xmr( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if the device is connected to the ISA bus. - * - * @note This function should be used instead of checking the bus_flags manually + * @brief Check if the device is connected via the ISA bus * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @return ::MBG_SUCCESS if the device is connected to ISA, ::MBG_ERR_NOT_SUPP_BY_DEV otherwise + * @return ::MBG_SUCCESS if the device is connected via the ISA bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_isa( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if the device is connected to the MCA bus. - * - * @note This function should be used instead of checking the bus_flags manually + * @brief Check if the device is connected via the MCA bus * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @return ::MBG_SUCCESS if the device is connected to MCA, ::MBG_ERR_NOT_SUPP_BY_DEV otherwise + * @return ::MBG_SUCCESS if the device is connected via the MCA bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_mca( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if the device is connected to the PCI bus and if one of the PCI interface chips is used - * - * @note This function should be used instead of checking the bus_flags manually + * @brief Check if the device is connected via the PCI bus * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @return ::MBG_SUCCESS if the device is connected to PCI and one of the PCI interface chips is used, - * ::MBG_ERR_NOT_SUPP_BY_DEV otherwise + * @return ::MBG_SUCCESS if the device is connected via the PCI bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_pci( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if the device is connected to the PCI Express bus and if one of the PCI Express interface chips is used - * - * @note This function should be used instead of checking the bus_flags manually + * @brief Check if the device is connected via the PCI Express bus * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @return ::MBG_SUCCESS if the device is connected to PCI Express and one of the PCI Express interface chips is used, - * ::MBG_ERR_NOT_SUPP_BY_DEV otherwise + * @return ::MBG_SUCCESS if the device is connected via the PCI Express bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_pci_express( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if the device is connected to the USB bus - * - * @note This function should be used instead of checking the bus_flags manually + * @brief Check if the device is connected via the USB bus * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @return ::MBG_SUCCESS if the device is connected to USB, ::MBG_ERR_NOT_SUPP_BY_DEV otherwise + * @return ::MBG_SUCCESS if the device is connected via the USB bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_usb( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports GNSS configuration. + * @brief Check if a device supports GNSS configuration * * This is usually the case if a device supports reception of - * several different satellite systems, e.g. GPS, Glonass, etc. + * different satellite systems, e.g. GPS, Glonass, Galileo, etc. * * @note This function should be preferred over ::mbg_dev_is_gnss, * which has been deprecated. @@ -909,8 +1076,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_gps_gnss_mode_info * @see ::mbg_set_gps_gnss_mode_settings * @see ::mbg_get_gps_all_gnss_sat_info @@ -918,7 +1086,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_gnss( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device is a GPS receiver. + * @brief Check if a device is a GPS receiver * * The function also returns ::MBG_SUCCESS for GNSS receivers * which can track GPS satellites beside other GNSS systems. @@ -929,7 +1097,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_gps( MBG_DEV_HANDLE dh ) ; @@ -946,8 +1116,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_pzf * @see ::mbg_chk_dev_is_lwr */ @@ -967,17 +1138,18 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_corr_info - * @see ::mbg_chk_dev_supp_tr_distance + * @see ::mbg_chk_dev_has_tr_distance * @see ::mbg_chk_dev_is_dcf * @see ::mbg_chk_dev_is_lwr */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_pzf( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device is a MSF receiver. + * @brief Check if a device is a MSF receiver * * @note This function should be preferred over ::mbg_dev_is_msf, * which has been deprecated. @@ -985,14 +1157,15 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_is_lwr */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_msf( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device is a WWVB receiver. + * @brief Check if a device is a WWVB receiver * * @note This function should be preferred over ::mbg_dev_is_wwvb, * which has been deprecated. @@ -1000,14 +1173,28 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_is_lwr */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_wwvb( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device is any long wave signal receiver. + * @brief Check if a device is a JJY receiver. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_is_lwr + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_jjy( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device is any long wave signal receiver * * Long wave receivers include e.g. DCF77, MSF, WWVB, or JJY. * @@ -1017,11 +1204,13 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_is_dcf * @see ::mbg_chk_dev_is_msf * @see ::mbg_chk_dev_is_wwvb + * @see ::mbg_chk_dev_is_jjy */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_lwr( MBG_DEV_HANDLE dh ) ; @@ -1034,17 +1223,18 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_irig_rx_info * @see ::mbg_set_irig_rx_settings * @see ::mbg_chk_dev_has_irig_tx * @see ::mbg_chk_dev_has_irig */ - _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_irig_rx( MBG_DEV_HANDLE dh ) ; + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_tcr( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device provides simple LAN interface API calls. + * @brief Check if a device supports simple LAN interface API calls * * @note This function should be preferred over ::mbg_dev_has_lan_intf, * which has been deprecated. @@ -1052,8 +1242,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_lan_if_info * @see ::mbg_get_ip4_state * @see ::mbg_get_ip4_settings @@ -1062,7 +1253,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_lan_intf( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device provides PTP configuration/status calls. + * @brief Check if a device supports PTP configuration/status calls * * @note This function should be preferred over ::mbg_dev_has_ptp, * which has been deprecated. @@ -1070,8 +1261,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_state * @see ::mbg_get_ptp_cfg_info @@ -1081,7 +1273,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ptp( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device provides PTP unicast feature/configuration. + * @brief Check if a device supports PTP unicast feature/configuration * * Not all devices which support PTP do also support PTP Unicast. This API * call checks if PTP Unicast is supported in addition to the standard @@ -1093,8 +1285,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_uc_master_cfg_limits * @see ::mbg_get_all_ptp_uc_master_info @@ -1104,7 +1297,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ptp_unicast( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports the mbg_get_hr_time... functions. + * @brief Check if a device supports the mbg_get_hr_time... functions * * @note This function should be preferred over ::mbg_dev_has_hr_time, * which has been deprecated. @@ -1112,8 +1305,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_hr_time * @see ::mbg_get_hr_time_cycles * @see ::mbg_get_hr_time_comp @@ -1121,7 +1315,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_hr_time( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports the mbg_get_fast_hr_timestamp... calls. + * @brief Check if a device supports the mbg_get_fast_hr_timestamp... calls * * @note This function should be preferred over ::mbg_dev_has_fast_hr_timestamp, * which has been deprecated. @@ -1129,8 +1323,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_fast_hr_timestamp_cycles * @see ::mbg_get_fast_hr_timestamp_comp * @see ::mbg_get_fast_hr_timestamp @@ -1140,7 +1335,7 @@ extern "C" { /** * @brief Check if a device supports configurable time scales. * - * By default the cards return %UTC and/or local time. However, some cards + * By default the devices return %UTC and/or local time. However, some cards * can be configured to return raw GPS time or TAI instead. * * @note This function should be preferred over ::mbg_dev_has_time_scale, @@ -1149,14 +1344,15 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_time_scale_info * @see ::mbg_set_time_scale_settings */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_time_scale( MBG_DEV_HANDLE dh ) ; - /** (Intentionally excluded from Doxygen) + /* (Intentionally excluded from Doxygen) * @brief Check if a device supports setting an event time * * This feature is only supported by some special custom firmware @@ -1168,14 +1364,15 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_set_event_time */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_event_time( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports the ::mbg_get_ucap_entries and ::mbg_get_ucap_event calls. + * @brief Check if a device supports the ::mbg_get_ucap_entries and ::mbg_get_ucap_event calls * * If the device doesn't support this but is a GPS card then the card provides * a time capture FIFO buffer and the obsolete ::mbg_get_gps_ucap call can be used @@ -1187,8 +1384,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_ucap_entries * @see ::mbg_get_ucap_event * @see ::mbg_clr_ucap_buff @@ -1197,7 +1395,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ucap( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports the ::mbg_clr_ucap_buff call. + * @brief Check if a device supports the ::mbg_clr_ucap_buff call * * The ::mbg_clr_ucap_buff call can be used to clear a device's on-board * time capture FIFO buffer, but the call may not be supported by some @@ -1209,14 +1407,15 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_clr_ucap_buff */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_can_clr_ucap_buff( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports timezone configuration using the ::TZDL structure. + * @brief Check if a device supports timezone configuration using the ::TZDL structure * * @note This function should be preferred over ::mbg_dev_has_tzdl, * which has been deprecated. @@ -1224,8 +1423,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_gps_tzdl * @see ::mbg_set_gps_tzdl * @see ::mbg_chk_dev_has_tz @@ -1233,7 +1433,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tzdl( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure. + * @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure * * @note This function should be preferred over ::mbg_dev_has_pcps_tzdl, * which has been deprecated. @@ -1241,8 +1441,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_pcps_tzdl * @see ::mbg_set_pcps_tzdl * @see ::mbg_chk_dev_has_tz @@ -1258,8 +1459,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_tzcode * @see ::mbg_set_tzcode * @see ::mbg_chk_dev_has_tz @@ -1275,8 +1477,9 @@ extern "C" { * which has been deprecated. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_tzdl * @see ::mbg_chk_dev_has_pcps_tzdl * @see ::mbg_chk_dev_has_tzcode @@ -1292,9 +1495,10 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * - * @see ::mbg_chk_dev_is_irig_rx + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_is_tcr * @see ::mbg_chk_dev_has_irig_tx */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig( MBG_DEV_HANDLE dh ) ; @@ -1308,11 +1512,12 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_irig_tx_info * @see ::mbg_set_irig_tx_settings - * @see ::mbg_chk_dev_is_irig_rx + * @see ::mbg_chk_dev_is_tcr * @see ::mbg_chk_dev_has_irig * @see @ref group_icode */ @@ -1327,14 +1532,15 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_irig_ctrl_bits */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports the ::mbg_get_raw_irig_data call. + * @brief Check if a device supports the ::mbg_get_raw_irig_data call * * @note This function should be preferred over ::mbg_dev_has_raw_irig_data, * which has been deprecated. @@ -1342,15 +1548,16 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_raw_irig_data * @see ::mbg_get_raw_irig_data_on_sec_change */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_raw_irig_data( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports the ::mbg_get_irig_time call. + * @brief Check if a device supports the ::mbg_get_irig_time call * * @note This function should be preferred over ::mbg_dev_has_irig_time, * which has been deprecated. @@ -1358,14 +1565,15 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_irig_time */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_time( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device provides the level of its inputs signal. + * @brief Check if a device provides the level of its inputs signal * * This is useful to display the signal level of e.g. an IRIG or similar * time code, or a long wave signal. @@ -1376,12 +1584,14 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_signal( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device provides a modulation signal. + * @brief Check if a device provides a modulation signal * * Modulation signals are e.g. the second marks provided by a long wave receiver. * @@ -1391,14 +1601,18 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_mod( MBG_DEV_HANDLE dh ) ; - /** (Intentionally excluded from Doxygen) - * Check if a device provides a serial output supporting - * higher baud rates than older cards, i.e. ::DEFAULT_BAUD_RATES_DCF_HS - * rather than ::DEFAULT_BAUD_RATES_DCF. + /* (Intentionally excluded from Doxygen) + * @brief Check if a device supports higher baud rates than usual + * + * Check if a device provides a serial output that supports + * higher baud rates than older cards, i.e. ::DEFAULT_BAUD_RATES_DCF_HS + * rather than ::DEFAULT_BAUD_RATES_DCF. * * The call ::mbg_get_serial_settings takes care of this, so applications * which use that call as suggested don't need to use this call directly. @@ -1409,14 +1623,15 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_serial_settings */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_serial_hs( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device provides a programmable frequency synthesizer. + * @brief Check if a device provides a programmable frequency synthesizer * * @note This function should be preferred over ::mbg_dev_has_synth, * which has been deprecated. @@ -1424,15 +1639,16 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_synth * @see ::mbg_set_synth */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_synth( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device provides GPIO signal inputs and/or outputs. + * @brief Check if a device provides GPIO signal inputs and/or outputs * * @note This function should be preferred over ::mbg_dev_has_gpio, * which has been deprecated. @@ -1440,17 +1656,18 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_gpio_cfg_limits * @see ::mbg_get_gps_all_gpio_info * @see ::mbg_set_gps_gpio_settings_idx * @see ::mbg_get_gps_all_gpio_status */ - _MBG_API_ATTR int _MBG_API mbg_chk_dev_supp_gpio( MBG_DEV_HANDLE dh ) ; + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_gpio( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports configuration of antenna cable length. + * @brief Check if a device supports configuration of antenna cable length * * @note This function should be preferred over ::mbg_dev_has_cab_len, * which has been deprecated. @@ -1458,18 +1675,19 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_gps_ant_cable_len * @see ::mbg_set_gps_ant_cable_len */ _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_cab_len( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device provides a configurable ref time offset. + * @brief Check if a device provides a configurable ref time offset * * This may be required to convert the received time to %UTC, if the input - * signal doesn't specify this (e.g. with most IRIG code formats). //### + * signal doesn't specify this (e.g. with most IRIG code formats). * * @note This function should be preferred over ::mbg_dev_has_ref_offs, * which has been deprecated. @@ -1477,8 +1695,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_ref_offs * @see ::mbg_set_ref_offs */ @@ -1488,7 +1707,7 @@ extern "C" { * @brief Check if a device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS. * * These structures contain optional settings, controlled by flags. - * See ::MBG_OPT_SETTINGS and related definitions. + * See ::MBG_OPT_SETTINGS and associated definitions. * * @note This function should be preferred over ::mbg_dev_has_opt_flags, * which has been deprecated. @@ -1496,8 +1715,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_opt_info * @see ::mbg_set_opt_settings */ @@ -1509,7 +1729,7 @@ extern "C" { * 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. + * Meinberg GPS and GNSS devices. * * The %UTC parameter set is usually received from the satellites' broadcasts * and contains the current time offset between GPS time and UTC, plus information @@ -1524,8 +1744,9 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_utc_parm * @see ::mbg_set_utc_parm */ @@ -1534,14 +1755,20 @@ extern "C" { /** * @brief Check if a device supports reading correlation info * + * The PZF phase modulation decoded by DCF77 PZF receivers is decoded + * using a correlation approach, and optionally there's an API call + * supported which can be used to retrieve the correlation value + * and thus determine the quality of the input signal. + * * @note This function should be preferred over ::mbg_dev_has_corr_info, * which has been deprecated. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_pzf * @see ::mbg_get_corr_info */ @@ -1559,13 +1786,14 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_chk_dev_has_pzf * @see ::mbg_get_tr_distance * @see ::mbg_set_tr_distance */ - _MBG_API_ATTR int _MBG_API mbg_chk_dev_supp_tr_distance( MBG_DEV_HANDLE dh ) ; + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tr_distance( MBG_DEV_HANDLE dh ) ; /** * @brief Check if a device provides a debug status word to be read @@ -1576,14 +1804,15 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_get_debug_status */ - _MBG_API_ATTR int _MBG_API mbg_chk_dev_supp_debug_status( MBG_DEV_HANDLE dh ) ; + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_debug_status( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device provides an on-board event log. + * @brief Check if a device provides an on-board event log * * @note This function should be preferred over ::mbg_dev_has_evt_log, * which has been deprecated. @@ -1591,17 +1820,18 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV - * if not supported, or one of the other @ref MBG_RETURN_CODES + * if not supported, or one of the other @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs * @see ::mbg_clr_evt_log * @see ::mbg_get_num_evt_log_entries * @see ::mbg_get_first_evt_log_entry * @see ::mbg_get_next_evt_log_entry */ - _MBG_API_ATTR int _MBG_API mbg_chk_dev_supp_evt_log( MBG_DEV_HANDLE dh ) ; + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_evt_log( MBG_DEV_HANDLE dh ) ; /** - * @brief Check if a device supports the ::RECEIVER_INFO structure and related calls. + * @brief Check if a device supports the ::RECEIVER_INFO structure and related calls * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_receiver_info preferably. * @@ -1609,14 +1839,15 @@ extern "C" { * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_receiver_info */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_receiver_info" ) _MBG_API mbg_dev_has_receiver_info( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports large configuration data structures. + * @brief Check if a device supports large configuration data structures * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_gps_data preferably. * @@ -1624,14 +1855,15 @@ extern "C" { * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_gps_data */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_gps_data" ) _MBG_API mbg_dev_has_gps_data( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports the ::mbg_generic_io API call. + * @brief Check if a device supports the ::mbg_generic_io API call * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_generic_io preferably. * @@ -1639,14 +1871,15 @@ extern "C" { * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_generic_io */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_generic_io" ) _MBG_API mbg_dev_has_generic_io( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports the ::mbg_get_asic_version call. + * @brief Check if a device supports the ::mbg_get_asic_version call * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_asic_version preferably. * @@ -1654,8 +1887,9 @@ extern "C" { * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_asic_version */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_asic_version" ) _MBG_API mbg_dev_has_asic_version( MBG_DEV_HANDLE dh, int *p ) ; @@ -1669,8 +1903,9 @@ extern "C" { * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_asic_features * @see ::mbg_get_asic_features */ @@ -1679,21 +1914,22 @@ extern "C" { /** * @brief Check if a device provides extended multi ref (XMR) inputs. * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_supp_xmr preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_xmr preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_chk_dev_supp_xmr + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_xmr * @see @ref group_multi_ref_ext */ - _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_xmr" ) _MBG_API mbg_dev_has_xmr( MBG_DEV_HANDLE dh, int *p ) ; + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_xmr" ) _MBG_API mbg_dev_has_xmr( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports GNSS configuration. + * @brief Check if a device supports GNSS configuration * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_gnss preferably. * @@ -1701,29 +1937,31 @@ extern "C" { * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_gnss */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gnss" ) _MBG_API mbg_dev_is_gnss( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device is a GPS receiver. + * @brief Check if a device is a GPS receiver * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_is_gps preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_gps preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_gps */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gps" ) _MBG_API mbg_dev_is_gps( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device is a DCF77 receiver. + * @brief Check if a device is a DCF77 receiver * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_dcf preferably. * @@ -1731,8 +1969,9 @@ extern "C" { * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_dcf */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_dcf" ) _MBG_API mbg_dev_is_dcf( MBG_DEV_HANDLE dh, int *p ) ; @@ -1746,14 +1985,15 @@ extern "C" { * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_pzf */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_pzf" ) _MBG_API mbg_dev_has_pzf( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device is a MSF receiver. + * @brief Check if a device is a MSF receiver * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_msf preferably. * @@ -1761,14 +2001,15 @@ extern "C" { * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_msf */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_msf" ) _MBG_API mbg_dev_is_msf( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device is a WWVB receiver. + * @brief Check if a device is a WWVB receiver * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_wwvb preferably. * @@ -1776,14 +2017,15 @@ extern "C" { * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_wwvb */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_wwvb" ) _MBG_API mbg_dev_is_wwvb( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device is any long wave signal receiver. + * @brief Check if a device is any long wave signal receiver * * @deprecated This function is deprecated, use ::mbg_chk_dev_is_lwr preferably. * @@ -1791,8 +2033,9 @@ extern "C" { * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_is_lwr */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_lwr" ) _MBG_API mbg_dev_is_lwr( MBG_DEV_HANDLE dh, int *p ) ; @@ -1800,20 +2043,21 @@ extern "C" { /** * @brief Check if a device provides a configurable IRIG input. * - * @deprecated This function is deprecated, use ::mbg_chk_dev_is_irig_rx preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_tcr preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_chk_dev_is_irig_rx + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_tcr */ - _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_irig_rx" ) _MBG_API mbg_dev_is_irig_rx( MBG_DEV_HANDLE dh, int *p ) ; + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_tcr" ) _MBG_API mbg_dev_is_irig_rx( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device provides simple LAN interface API calls. + * @brief Check if a device supports simple LAN interface API calls * * @deprecated This function is deprecated, use ::mbg_chk_dev_has_lan_intf preferably. * @@ -1821,83 +2065,89 @@ extern "C" { * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_lan_intf */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_lan_intf" ) _MBG_API mbg_dev_has_lan_intf( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device provides PTP configuration/status calls. + * @brief Check if a device supports PTP configuration/status calls * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_ptp preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ptp preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_ptp */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ptp" ) _MBG_API mbg_dev_has_ptp( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device provides PTP unicast feature/configuration. + * @brief Check if a device supports PTP unicast feature/configuration * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_ptp_unicast preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ptp_unicast preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_ptp_unicast */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ptp_unicast" ) _MBG_API mbg_dev_has_ptp_unicast( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports the HR_TIME functions. + * @brief Check if a device supports the HR_TIME functions * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_hr_time preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_hr_time preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_hr_time */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_hr_time" ) _MBG_API mbg_dev_has_hr_time( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports the mbg_get_fast_hr_timestamp_...() calls. + * @brief Check if a device supports the mbg_get_fast_hr_timestamp_...() calls * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_fast_hr_timestamp preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_fast_hr_timestamp preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_fast_hr_timestamp */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_fast_hr_timestamp" ) _MBG_API mbg_dev_has_fast_hr_timestamp( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports configurable time scales. + * @brief Check if a device supports configurable time scales * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_time_scale preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_time_scale preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_time_scale */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_time_scale" ) _MBG_API mbg_dev_has_time_scale( MBG_DEV_HANDLE dh, int *p ) ; @@ -1907,134 +2157,142 @@ extern "C" { * * @note This is only supported by some customized devices * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_event_time preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_event_time preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_event_time */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_event_time" ) _MBG_API mbg_dev_has_event_time( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports the ::mbg_get_ucap_entries and ::mbg_get_ucap_event calls. + * @brief Check if a device supports the ::mbg_get_ucap_entries and ::mbg_get_ucap_event calls * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_ucap preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ucap preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_ucap */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ucap" ) _MBG_API mbg_dev_has_ucap( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports the ::mbg_clr_ucap_buff call. + * @brief Check if a device supports the ::mbg_clr_ucap_buff call * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_can_clr_ucap_buff preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_can_clr_ucap_buff preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_chk_dev_can_clr_ucap_buff */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_can_clr_ucap_buff" ) _MBG_API mbg_dev_can_clr_ucap_buff( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports timezone configuration using the ::TZDL structure. + * @brief Check if a device supports timezone configuration using the ::TZDL structure * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_tzdl preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tzdl preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_tzdl */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tzdl" ) _MBG_API mbg_dev_has_tzdl( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure. + * @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_pcps_tzdl preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_pcps_tzdl preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_pcps_tzdl */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_pcps_tzdl" ) _MBG_API mbg_dev_has_pcps_tzdl( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports timezone configuration using the ::PCPS_TZCODE type. + * @brief Check if a device supports timezone configuration using the ::PCPS_TZCODE type * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_tzcode preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tzcode preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_tzcode */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tzcode" ) _MBG_API mbg_dev_has_tzcode( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports any kind of timezone configuration. + * @brief Check if a device supports any kind of timezone configuration * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_tz preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tz preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_tz */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tz" ) _MBG_API mbg_dev_has_tz( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device provides either an IRIG input or output. + * @brief Check if a device provides either an IRIG input or output * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_irig preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_irig */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig" ) _MBG_API mbg_dev_has_irig( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device provides a configurable IRIG output. + * @brief Check if a device provides a configurable IRIG output * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_irig_tx preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig_tx preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_irig_tx */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_tx" ) _MBG_API mbg_dev_has_irig_tx( MBG_DEV_HANDLE dh, int *p ) ; @@ -2042,181 +2300,194 @@ extern "C" { /** * @brief Check if a device supports the ::mbg_get_irig_ctrl_bits call * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_irig_ctrl_bits preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig_ctrl_bits preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_irig_ctrl_bits */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_ctrl_bits" ) _MBG_API mbg_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports the ::mbg_get_raw_irig_data call. + * @brief Check if a device supports the ::mbg_get_raw_irig_data call * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_raw_irig_data preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_raw_irig_data preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_chk_dev_has_raw_irig_data */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_raw_irig_data" ) _MBG_API mbg_dev_has_raw_irig_data( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports the ::mbg_get_irig_time call. + * @brief Check if a device supports the ::mbg_get_irig_time call * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_irig_time preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig_time preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_irig_time */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_time" ) _MBG_API mbg_dev_has_irig_time( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device provides the level of its inputs signal. + * @brief Check if a device provides the level of its inputs signal * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_signal preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_signal preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_signal */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_signal" ) _MBG_API mbg_dev_has_signal( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device provides a modulation signal. + * @brief Check if a device provides a modulation signal * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_mod preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_mod preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_mod */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_mod" ) _MBG_API mbg_dev_has_mod( MBG_DEV_HANDLE dh, int *p ) ; /* (Intentionally excluded from Doxygen) - * 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. + * @brief Check if a device supports higher baud rates than usual * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_serial_hs preferably. + * Check if a device provides a serial output that supports + * higher baud rates than older cards, i.e. ::DEFAULT_BAUD_RATES_DCF_HS + * rather than ::DEFAULT_BAUD_RATES_DCF. + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_serial_hs preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_serial_hs */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_serial_hs" ) _MBG_API mbg_dev_has_serial_hs( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device provides a programmable frequency synthesizer. + * @brief Check if a device provides a programmable frequency synthesizer * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_synth preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_synth preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_synth */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_synth" ) _MBG_API mbg_dev_has_synth( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device provides GPIO signal inputs and/or outputs. + * @brief Check if a device provides GPIO signal inputs and/or outputs * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_supp_gpio preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_gpio preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_chk_dev_supp_gpio + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_gpio */ - _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_gpio" ) _MBG_API mbg_dev_has_gpio( MBG_DEV_HANDLE dh, int *p ) ; + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_gpio" ) _MBG_API mbg_dev_has_gpio( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports configuration of antenna cable length. + * @brief Check if a device supports configuration of antenna cable length * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_cab_len preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_cab_len preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_cab_len */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_cab_len" ) _MBG_API mbg_dev_has_cab_len( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device provides a configurable ref time offset. + * @brief Check if a device provides a configurable ref time offset * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_ref_offs preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ref_offs preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_ref_offs */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ref_offs" ) _MBG_API mbg_dev_has_ref_offs( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS. + * @brief Check if a device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_opt_flags preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_opt_flags preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_opt_flags */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_opt_flags" ) _MBG_API mbg_dev_has_opt_flags( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Check if a device support reading/writing of ::UTC parameters. + * @brief Check if a device support reading/writing of ::UTC parameters * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_utc_parm preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_utc_parm preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_utc_parm */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_utc_parm" ) _MBG_API mbg_dev_has_utc_parm( MBG_DEV_HANDLE dh, int *p ) ; @@ -2224,14 +2495,15 @@ extern "C" { /** * @brief Check if a device supports reading correlation info * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_has_corr_info preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_corr_info preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_chk_supp_fncs_deprecated * @see ::mbg_chk_dev_has_corr_info */ _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_corr_info" ) _MBG_API mbg_dev_has_corr_info( MBG_DEV_HANDLE dh, int *p ) ; @@ -2239,136 +2511,201 @@ extern "C" { /** * @brief Check if a device supports configurable distance from transmitter * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_supp_tr_distance preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tr_distance preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_chk_dev_supp_tr_distance + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_tr_distance */ - _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_tr_distance" ) _MBG_API mbg_dev_has_tr_distance( MBG_DEV_HANDLE dh, int *p ) ; + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tr_distance" ) _MBG_API mbg_dev_has_tr_distance( MBG_DEV_HANDLE dh, int *p ) ; /** * @brief Check if a device provides a debug status word to be read * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_supp_debug_status preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_debug_status preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_chk_dev_supp_debug_status + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_debug_status */ - _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_debug_status" ) _MBG_API mbg_dev_has_debug_status( MBG_DEV_HANDLE dh, int *p ) ; + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_debug_status" ) _MBG_API mbg_dev_has_debug_status( MBG_DEV_HANDLE dh, int *p ) ; /** * @brief Check if a device provides an on-board event log. * - * @deprecated This function is deprecated. Use ::mbg_chk_dev_supp_evt_log preferably. + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_evt_log preferably. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to an int which is updated if the API call succeeds. * The flag is set != 0 if the requested feature is supported, else 0. * - * @return ::MBG_SUCCESS on success, if *p has been updated, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_chk_dev_supp_evt_log + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_evt_log */ - _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_supp_evt_log" ) _MBG_API mbg_dev_has_evt_log( MBG_DEV_HANDLE dh, int *p ) ; + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_evt_log" ) _MBG_API mbg_dev_has_evt_log( MBG_DEV_HANDLE dh, int *p ) ; /** - * @brief Open a device by index, starting from 0 + * @brief Create a device file name according to an index number * - * @deprecated This function is deprecated, use ::mbg_open_device_by_name preferably. + * Create a system-specific device file name string, e.g. "/dev/mbgclock0" + * under Linux and similar systems, which can be used with the + * open() call on systems which support this. * - * @note See comments for ::mbg_find_devices for details. + * Under Windows a hardware ID string is used, so a Windows-specific function + * is called to retrieve the string * - * @param[in] device_index Index of the device, use 0 for the first device + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] dev_idx The device index number. + * + * @see mbg_svc_get_device_path under Windows + */ + _MBG_API_ATTR int _MBG_API mbg_dev_fn_from_dev_idx( char *s, int max_len, int dev_idx ) ; + + /** + * @brief Open a device by index number + * + * For details and similar functions see @ref mbgdevio_open_fncs. + * + * @param[in] dev_idx Device index number, starting from 0. * * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs */ - _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device( unsigned int device_index ) ; + MBG_DEV_HANDLE _MBG_API mbg_open_device( int dev_idx ) ; /** - * @brief Get the number of supported devices installed on the computer. + * @brief Open a device specified by a device file name * - * @deprecated This function is deprecated, ::mbg_find_devices_with_names - * should be used instead. + * The format the device file name depends on the operating system. + * see ::MBG_DEV_FN. + * + * For details and similar functions see @ref mbgdevio_open_fncs. + * + * @param[in] dev_fn The device file name + * + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs + * @see ::MBG_DEV_FN + */ + _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_dev_fn( const char *dev_fn ) ; + + /** + * @brief Open a device specified by a device file name + * + * @deprecated This function is deprecated, use + * ::mbg_open_device_by_dev_fn preferably. + * + * The format the device file name depends on the operating system. + * see ::MBG_DEV_FN. + * + * For details and similar functions see @ref mbgdevio_open_fncs. + * + * @param[in] dev_fn The device file name, see ::MBG_DEV_FN + * + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs + * @see ::MBG_DEV_FN + */ + _MBG_API_ATTR MBG_DEV_HANDLE _DEPRECATED_BY( "mbg_open_device_by_dev_fn" ) _MBG_API mbg_open_device_by_hw_id( const char *dev_fn ) ; + + /** + * @brief Get the number of devices installed on the computer * - * @note This function is out of date since it may not work - * correctly for Meinberg devices which are disconnected and reconnected - * while the system is running (e.g. USB devices). However, the function - * will be kept for compatibility reasons and works correctly if all - * Meinberg devices are connected at system boot and are not disconnected - * and reconnected during operation + * The function ::mbg_find_devices_with_names should eventually + * be used preferafly. See @ref mbgdevio_open_fncs. * * @return The number of devices found * * @see ::mbg_find_devices_with_names + * @see ::mbg_open_device + * @see @ref mbgdevio_open_fncs */ _MBG_API_ATTR int _MBG_API mbg_find_devices( void ) ; /** - * @brief Allocate memory and set up a list of installed and supported devices. + * @brief Allocate memory and set up a list of installed and supported devices + * + * Allocate and fill a list with the names of Meinberg devices currently + * present in the system. * - * This function should be used preferably instead of ::mbg_find_devices. + * This can be used e.g. to populate a device selection dialog + * in a configuration program. * - * @param[in] device_list Pointer to a linked list of type ::MBG_DEVICENAME_LIST - * with device names. The list will be allocated by this - * function and has to be freed after usage by calling - * ::mbg_free_device_name_list. - * @param[in] max_devices Maximum number of devices the function should look for + * When the list is not used anymore it can be freed by calling + * ::mbg_free_device_name_list. + * + * @param[in] p_list Pointer to a linked list to be allocated. + * @param[in] max_devices Maximum number of devices to be searched for * (must not exceed ::N_SUPP_DEV_BUS). * - * @return number of present devices + * @return The 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 + * @see ::MBG_DEV_NAME */ - _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_DEV_NAME_LIST_ENTRY **p_list, int max_devices ) ; /** - * @brief Free the memory allocated for a ::MBG_DEVICENAME_LIST. + * @brief Free the memory allocated for a list of ::MBG_DEV_NAME_LIST_ENTRY entries. * * The list may have been set up and allocated before * by ::mbg_find_devices_with_names. * - * @param[in,out] list Linked list of type ::MBG_DEVICENAME_LIST + * @param[in,out] list Linked list of ::MBG_DEV_NAME_LIST_ENTRY entries. * * @see ::mbg_find_devices_with_names */ - _MBG_API_ATTR void _MBG_API mbg_free_device_name_list( MBG_DEVICENAME_LIST *list) ; + _MBG_API_ATTR void _MBG_API mbg_free_device_name_list( MBG_DEV_NAME_LIST_ENTRY *list ) ; /** - * @brief Return a handle to a device with a certain unique name. + * @brief Return a handle to a device with a particular device name * - * The names of the devices that are installed on the system can be retrieved by - * the function ::mbg_find_devices_with_names. + * See ::MBG_DEV_NAME for the possible formats of a device name. * - * This function should be used preferably instead of ::mbg_open_device. + * For details and similar functions see @ref mbgdevio_open_fncs. * - * @param[in] srch_name String with the unique name of the device to be opened - * @param[in] selection_mode One of the enum values of ::MBG_MATCH_MODE + * @param[in] srch_name String with the ::MBG_DEV_NAME of a device to be opened + * @param[in] selection_mode One of the ::MBG_MATCH_MODES * - * @return On success, the function returns a handle to the device, otherwise ::MBG_INVALID_DEV_HANDLE + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE * - * @see ::MBG_HW_NAME for the format of the unique names - * @see ::MBG_MATCH_MODE - * @see ::mbg_find_devices_with_names + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs + * @see ::MBG_DEV_NAME + * @see ::MBG_MATCH_MODES */ - _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const char *srch_name, int selection_mode ) //##++++ -; + _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const char *srch_name, int selection_mode ) ; /** - * @brief Close a handle to a device and set the handle value to ::MBG_INVALID_DEV_HANDLE. + * @brief Close a device handle and set the handle value to ::MBG_INVALID_DEV_HANDLE * * @param[in,out] dev_handle Pointer to a Meinberg device handle + * + * @see @ref mbgdevio_open_fncs */ _MBG_API_ATTR void _MBG_API mbg_close_device( MBG_DEV_HANDLE *dev_handle ) ; @@ -2376,19 +2713,19 @@ extern "C" { * @brief Read information about the driver handling a given device * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] *p A ::PCPS_DRVR_INFO structure to be filled up. + * @param[out] p A ::PCPS_DRVR_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES */ _MBG_API_ATTR int _MBG_API mbg_get_drvr_info( MBG_DEV_HANDLE dh, PCPS_DRVR_INFO *p ) ; /** * @brief Read detailed device information * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] *p A ::PCPS_DEV structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES */ _MBG_API_ATTR int _MBG_API mbg_get_device_info( MBG_DEV_HANDLE dh, PCPS_DEV *p ) ; @@ -2399,10 +2736,10 @@ extern "C" { * also includes the ::PCPS_ST_MOD bit reflecting the time code * modulation of long wave receivers. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] *p A ::PCPS_STATUS_PORT value to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p A ::PCPS_STATUS_PORT value to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see @ref group_status_port "bitmask" //### TODO check syntax */ @@ -2421,7 +2758,7 @@ extern "C" { * @param[out] p Pointer to a buffer to be filled up * @param[in] size Size of the output buffer * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_generic_write * @see ::mbg_generic_read_gps @@ -2445,7 +2782,7 @@ extern "C" { * @param[out] p Pointer to a buffer to be filled up * @param[in] size Size of the buffer, has to match the expected data size associated with cmd * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_chk_dev_has_gps_data * @see ::mbg_generic_write_gps @@ -2468,7 +2805,7 @@ extern "C" { * @param[in] p Pointer to a buffer of data to be written * @param[in] size Size of the buffer, has to match the expected data size associated with cmd * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_generic_read * @see ::mbg_generic_read_gps @@ -2492,7 +2829,7 @@ extern "C" { * @param[in] p Pointer to a buffer of data to be written * @param[in] size Size of the buffer, has to match the expected data size associated with cmd * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_chk_dev_has_gps_data * @see ::mbg_generic_read_gps @@ -2509,9 +2846,9 @@ extern "C" { * * <b>Warning</b>: This call is for debugging purposes and internal use only! * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_generic_io + * @see ::mbg_chk_dev_has_generic_io * @see ::mbg_generic_read * @see ::mbg_generic_write * @see ::mbg_generic_read_gps @@ -2520,21 +2857,22 @@ 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 ) ; /** - * @brief Read a ::PCPS_TIME structure returning the current date/time/status. + * @brief Read a ::PCPS_TIME structure returning the current date/time/status * * The returned time is local time according to the card's time zone setting, - * with a resolution of 10 ms (i.e. 10ths of seconds). + * with a resolution of 10 ms (i.e. 10ths of seconds) only. * * This call is supported by any device manufactured by Meinberg. - * However, for higher accuracy and resolution the @ref pcps_hr_time_fncs or - * the @ref pcps_fast_timestamp_fncs group of calls should be used preferably, + * However, for higher accuracy and resolution the @ref mbgdevio_hr_time_fncs or + * the @ref mbgdevio_fast_timestamp_fncs group of calls should be used preferably, * if supported by the device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_legacy_time_fncs * @see ::mbg_get_hr_time * @see ::mbg_set_time * @see ::mbg_get_sync_time @@ -2544,48 +2882,48 @@ extern "C" { /** * @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. + * The macro ::_pcps_can_set_time checks whether + * this call is supported by a device. * * @todo Provide an API function replacing ::_pcps_can_set_time. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::PCPS_STIME structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_time */ _MBG_API_ATTR int _MBG_API mbg_set_time( MBG_DEV_HANDLE dh, const PCPS_STIME *p ) ; /** - * @brief Read the time when the device has last recently synchronized. + * @brief Read the time when the device has last recently synchronized * - * Fills a ::PCPS_TIME structure with the date/time/status reporting - * when the device was synchronized the last time to its time source, - * e.g. the DCF77 signal, the GPS satellites, or similar. + * Fills a ::PCPS_TIME structure with the date/time/status reporting + * when the device was synchronized the last time to its time source, + * e.g. the DCF77 signal, the GPS satellites, or similar. * - * The macro ::_pcps_has_sync_time checks whether this call - * is supported by a device. + * The macro ::_pcps_has_sync_time checks whether + * this call is supported by a device. * - * <b>Note:</b> If that information is not available on the board then - * the value of the returned ::PCPS_TIME::sec field is set to 0xFF. - * The macro ::_pcps_time_is_read can be used to check whether the - * returned information is valid, or "not set". + * <b>Note:</b> If that information is not available on the board then + * the value of the returned ::PCPS_TIME::sec field is set to 0xFF. + * The macro ::_pcps_time_is_read can be used to check whether the + * returned information is valid, or "not set". * * @todo Provide an API function replacing ::_pcps_has_sync_time. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_time */ _MBG_API_ATTR int _MBG_API mbg_get_sync_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ; /** - * @brief Wait until the next second change, then return current time. + * @brief Wait until the next second change, then return current time * * Returns time in a ::PCPS_TIME structure similar to ::mbg_get_time. * @@ -2597,49 +2935,50 @@ extern "C" { * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_legacy_time_fncs * @see ::mbg_get_time */ _MBG_API_ATTR int _MBG_API mbg_get_time_sec_change( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ; /** - * @brief Read the card's current time with high resolution, plus status. + * @brief Read the card's current time with high resolution, including status * * Fills up a ::PCPS_HR_TIME (High Resolution time) structure containing * the current %UTC time (seconds since 1970), %UTC offset, and status. * - * The API call ::mbg_chk_dev_has_hr_time checks whether this call - * is supported by the device. + * The API call ::mbg_chk_dev_has_hr_time checks whether + * this call is supported by a device. * - * For details see @ref ::pcps_hr_time_fncs + * For details see @ref ::mbgdevio_hr_time_fncs * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_HR_TIME structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @ingroup pcps_hr_time_fncs - * @see @ref pcps_hr_time_fncs - * @see @ref pcps_fast_timestamp_fncs - * @see @ref pcps_std_time_fncs + * @ingroup mbgdevio_hr_time_fncs + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs */ _MBG_API_ATTR int _MBG_API mbg_get_hr_time( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) ; /* (Intentionally excluded from Doxygen ) - Write a high resolution time stamp ::PCPS_TIME_STAMP to a device - to configure a %UTC time when the clock shall generate an event. - The macro _pcps_has_event_time() or the API call mbg_dev_has_event_time() - check whether this call is supported by a device. - - <b>Note:</b> This is only supported by some special firmware. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_STAMP structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * Write a high resolution time stamp ::PCPS_TIME_STAMP to a device + * to configure a %UTC time when the clock shall generate an event. + * The API call ::mbg_chk_dev_has_event_time checks whether + * this call is supported by a device. + * + * <b>Note:</b> This is only supported by some special firmware. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PCPS_TIME_STAMP structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_event_time + * @see ::mbg_chk_dev_has_event_time */ _MBG_API_ATTR int _MBG_API mbg_set_event_time( MBG_DEV_HANDLE dh, const PCPS_TIME_STAMP *p ) ; @@ -2650,13 +2989,13 @@ extern "C" { * 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. + * The macro ::_pcps_has_serial checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_SERIAL structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_serial_settings */ @@ -2669,13 +3008,13 @@ extern "C" { * 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. + * The macro ::_pcps_has_serial checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::PCPS_SERIAL structure to be written * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_save_serial_settings */ @@ -2683,23 +3022,23 @@ extern "C" { /** * @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 - time zone and daylight saving settings. - + * + * The APIs using ::TZCODE are only supported by some simpler cards + * and allow just a very basic configuration. + * + * The API call ::mbg_chk_dev_has_tzcode checks whether + * this call is supported by a device. + * + * Other devices may support the ::mbg_get_pcps_tzdl or ::mbg_get_gps_tzdl + * calls instead which allow for a more detailed configuration of the + * time zone and daylight saving settings. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TZCODE structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::PCPS_TZCODE structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_tzcode + * @see ::mbg_chk_dev_has_tzcode * @see ::mbg_set_tzcode * @see ::mbg_get_pcps_tzdl * @see ::mbg_get_gps_tzdl @@ -2708,23 +3047,23 @@ extern "C" { /** * @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 - time zone and daylight saving settings. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TZCODE structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES * - * @see ::mbg_dev_has_tzcode + * The APIs using ::TZCODE are only supported by some simpler cards + * and allow just a very basic configuration. + * + * The API call ::mbg_chk_dev_has_tzcode checks whether + * this call is supported by a device. + * + * Other devices may support the ::mbg_set_pcps_tzdl or ::mbg_set_gps_tzdl + * calls instead which allow for a more detailed configuration of the + * time zone and daylight saving settings. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PCPS_TZCODE structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_tzcode * @see ::mbg_get_tzcode * @see ::mbg_set_pcps_tzdl * @see ::mbg_set_gps_tzdl @@ -2733,127 +3072,129 @@ extern "C" { /** * @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. - + * + * This function fills up a ::PCPS_TZDL structure which supports a more + * detailed configuration of time zone and daylight saving than the ::TZCODE + * structure. + * + * The API call ::mbg_chk_dev_has_pcps_tzdl checks whether + * this call is supported by a device. + * + * Other devices may support the ::mbg_get_tzcode or ::mbg_get_gps_tzdl + * calls instead. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TZDL structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_pcps_tzdl + * @param[out] p Pointer to a ::PCPS_TZDL structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_pcps_tzdl * @see ::mbg_set_pcps_tzdl * @see ::mbg_get_tzcode * @see ::mbg_get_gps_tzdl - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_pcps_tzdl( MBG_DEV_HANDLE dh, PCPS_TZDL *p ) ; /** * @brief Write 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[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TZDL structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_pcps_tzdl + * + * This function passes a ::PCPS_TZDL structure to a device which supports + * a more detailed configuration of time zone and daylight saving than the + * ::TZCODE structure. + * + * The API call ::mbg_chk_dev_has_pcps_tzdl checks whether + * this call is supported by a device. + * Other cards may support the ::mbg_set_tzcode or ::mbg_set_gps_tzdl + * calls instead. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PCPS_TZDL structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_pcps_tzdl * @see ::mbg_get_pcps_tzdl * @see ::mbg_set_tzcode * @see ::mbg_set_gps_tzdl - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_pcps_tzdl( MBG_DEV_HANDLE dh, const PCPS_TZDL *p ) ; /** - * @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. - + * @brief Read the %UTC offset configuration of the reference time from a device + * + * This parameter is used to specify the %UTC offset of an incoming + * reference time signal if a kind of time signal e.g. an IRIG input + * signal) does not provide this information. + * + * The API call ::mbg_chk_dev_has_ref_offs checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_REF_OFFS value to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ref_offs + * @param[out] p Pointer to a ::MBG_REF_OFFS value to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ref_offs * @see ::mbg_set_ref_offs - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ref_offs( MBG_DEV_HANDLE dh, MBG_REF_OFFS *p ) ; /** * @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[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_REF_OFFS value to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ref_offs + * + * This parameter is used to specify the %UTC offset of an incoming + * reference time signal if a kind of time signal e.g. an IRIG input + * signal) does not provide this information. + * + * The API call ::mbg_chk_dev_has_ref_offs checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::MBG_REF_OFFS value to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ref_offs * @see ::mbg_get_ref_offs - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_ref_offs( MBG_DEV_HANDLE dh, const MBG_REF_OFFS *p ) ; /** - * @brief Read a ::MBG_OPT_INFO structure containing optional settings, controlled by flags. - - The ::MBG_OPT_INFO structure contains a mask of supported flags plus the current - settings of those flags. - The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags() - check whether this call is supported by a device. - + * @brief Read a ::MBG_OPT_INFO structure containing optional settings, controlled by flags + * + * The ::MBG_OPT_INFO structure contains a mask of supported flags plus the current + * settings of those flags. + * + * The API call ::mbg_chk_dev_has_opt_flags checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_OPT_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_opt_flags + * @param[out] p Pointer to a ::MBG_OPT_INFO structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_opt_flags * @see ::mbg_set_opt_settings - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_opt_info( MBG_DEV_HANDLE dh, MBG_OPT_INFO *p ) ; /** * @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. - + * + * The API call ::mbg_chk_dev_has_opt_flags checks whether + * this call is supported by a device. + * + * ::mbg_get_opt_info should be called first to check which of + * the specified flags is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_OPT_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_opt_flags + * @param[out] p Pointer to a ::MBG_OPT_SETTINGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_opt_flags * @see ::mbg_get_opt_info - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_opt_settings( MBG_DEV_HANDLE dh, const MBG_OPT_SETTINGS *p ) ; /** @@ -2863,19 +3204,19 @@ extern "C" { * ::mbg_get_all_irig_rx_info should be used instead which also reads some * other associated parameters affecting the behaviour of the IRIG input. * - * The API call ::mbg_dev_is_irig_rx checks whether this call is supported - * by a device. + * The API call ::mbg_chk_dev_is_tcr checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] *p An ::IRIG_INFO structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_all_irig_rx_info * @see ::mbg_set_irig_rx_settings - * @see ::mbg_dev_is_irig_rx - * @see ::mbg_dev_has_irig_tx - * @see ::mbg_dev_has_irig + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_has_irig * @see @ref group_icode */ _MBG_API_ATTR int _MBG_API mbg_get_irig_rx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p ) ; @@ -2887,366 +3228,384 @@ extern "C" { * ::mbg_save_all_irig_rx_settings should be used instead which also writes some * other associated parameters affecting the behaviour of the IRIG input. * - * The API call ::mbg_dev_is_irig_rx checks whether this call is supported - * by a device. The ::IRIG_INFO structure should be read first to determine + * The API call ::mbg_chk_dev_is_tcr checks whether + * this call is supported by a device. + * ::mbg_get_irig_rx_info should be called first to determine * the possible settings supported by the device's IRIG input. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] p Pointer to a ::IRIG_SETTINGS structure to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::IRIG_SETTINGS structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_save_all_irig_rx_settings * @see ::mbg_get_irig_rx_info - * @see ::mbg_dev_is_irig_rx - * @see ::mbg_dev_has_irig_tx - * @see ::mbg_dev_has_irig + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_has_irig * @see @ref group_icode */ _MBG_API_ATTR int _MBG_API mbg_set_irig_rx_settings( MBG_DEV_HANDLE dh, const IRIG_SETTINGS *p ) ; /** - * @brief Read all IRIG input configuration information from a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pdev Pointer to the device's ::PCPS_DEV structure - @param p_irig_info Pointer to a ::IRIG_SETTINGS structure to be written - @param p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written - @param p_opt_info Pointer to a ::MBG_OPT_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Read all IRIG input configuration information from a device + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] pdev Pointer to the device's ::PCPS_DEV structure //### TODO Make this obsolete + * @param[in] p_irig_info Pointer to a ::IRIG_SETTINGS structure to be written + * @param[in] p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written + * @param[in] p_opt_info Pointer to a ::MBG_OPT_SETTINGS structure to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_save_all_irig_rx_settings * @see ::mbg_set_irig_rx_settings * @see ::mbg_set_ref_offs * @see ::mbg_set_opt_settings -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_all_irig_rx_info( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, IRIG_INFO *p_irig_info, MBG_REF_OFFS *p_ref_offs, MBG_OPT_INFO *p_opt_info ) ; /** * @brief Write all IRIG input configuration settings to a device. - - The macro _pcps_is_irig_rx() or the API call mbg_dev_is_irig_rx() - check whether this call is supported by a device. - The ::IRIG_INFO structure should be read first to determine the possible - settings supported by this card's IRIG input. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pdev Pointer to the device's ::PCPS_DEV structure - @param p_irig_settings Pointer to a ::IRIG_SETTINGS structure to be written - @param p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written - @param p_opt_settings Pointer to a ::MBG_OPT_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The API call ::mbg_chk_dev_is_tcr checks whether + * this call is supported by a device. + * ::mbg_get_all_irig_rx_info should be called before to determine + * the possible settings supported by the IRIG input. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] pdev Pointer to the device's ::PCPS_DEV structure //### TODO Make this obsolete + * @param[out] p_irig_settings Pointer to a ::IRIG_SETTINGS structure to be written + * @param[out] p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written + * @param[out] p_opt_settings Pointer to a ::MBG_OPT_SETTINGS structure to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_all_irig_rx_info * @see ::mbg_set_irig_rx_settings * @see ::mbg_set_ref_offs * @see ::mbg_set_opt_settings -*/ + */ _MBG_API_ATTR int _MBG_API mbg_save_all_irig_rx_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const IRIG_SETTINGS *p_irig_settings, const MBG_REF_OFFS *p_ref_offs, const MBG_OPT_SETTINGS *p_opt_settings ) ; /** * @brief Read the control function bits received from an incoming IRIG signal. - - This function fills a ::MBG_IRIG_CTRL_BITS structure with the control function - bits decoded from the incoming IRIG signal. - - The meaning of these bits depends on the type of IRIG code frame format. - - In some IRIG formats these bits provide some well-known information which can - also be evaluated by the device. For example, in IEEE 1344 or IEEE C37.118 code - the control function bits are used to provide the year number, UTC offset, - DST status, leap second warning, etc. - - For most IRIG code formats, however, these bits are reserved, i.e. not used - at all, or application defined, depending on the configuration of the IRIG - generator providing the IRIG signal. - - In the latter case the application has to evaluate the received control function - bits and can use this function to retrieve these bits from the receiver device. - - The macro _pcps_has_irig_ctrl_bits() or the API call mbg_dev_has_irig_ctrl_bits() - check whether this call is supported by a device. - + * + * This function fills an ::MBG_IRIG_CTRL_BITS structure with the control function + * bits decoded from the incoming IRIG signal. + * + * The meaning of these bits depends on the type of IRIG code frame format. + * + * In some IRIG formats these bits provide some well-known information which can + * also be evaluated by the device. For example, in IEEE 1344 or IEEE C37.118 code + * the control function bits are used to provide the year number, UTC offset, + * DST status, leap second warning, etc. + * + * For most IRIG code formats, however, these bits are reserved, i.e. not used + * at all, or application defined, depending on the configuration of the IRIG + * generator providing the IRIG signal. + * + * In the latter case the application has to evaluate the received control function + * bits and can use this function to retrieve these bits from the receiver device. + * + * The API call ::mbg_chk_dev_has_irig_ctrl_bits checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_IRIG_CTRL_BITS type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::MBG_IRIG_CTRL_BITS type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_irig_ctrl_bits + * @see ::mbg_chk_dev_has_irig_ctrl_bits */ _MBG_API_ATTR int _MBG_API mbg_get_irig_ctrl_bits( MBG_DEV_HANDLE dh, MBG_IRIG_CTRL_BITS *p ) ; /** * @brief Read raw IRIG data from an IRIG receiver. - - This function fills a ::MBG_RAW_IRIG_DATA structure with the raw data bits received - from the incoming IRIG signal. This enables an application itself to decode the - information provided by the IRIG signal. - - The macro _pcps_has_raw_irig_data() or the API call mbg_dev_has_raw_irig_data() - check whether this call is supported by a device. - + * + * This function reads an ::MBG_RAW_IRIG_DATA structure with the raw data bits received + * from the incoming IRIG signal. This enables an application itself to decode the + * information provided by the IRIG signal. + * + * The API call ::mbg_chk_dev_has_raw_irig_data checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_raw_irig_data + * @see ::mbg_chk_dev_has_raw_irig_data * @see ::mbg_get_raw_irig_data_on_sec_change */ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data( MBG_DEV_HANDLE dh, MBG_RAW_IRIG_DATA *p ) ; /** * @brief Wait for second changeover then read raw IRIG data from an IRIG receiver. - - This function waits until the second of the device's on-board time rolls over, and - then reads the last recent raw IRIG data from the device. - - The macro _pcps_has_raw_irig_data() or the API call mbg_dev_has_raw_irig_data() - check whether this call is supported by a device. - - <b>Note:</b> The mbg_get_time_sec_change() function called by this function is - supported under Windows only, so this function can also only be used under Windows. - + * + * This function waits until the second of the device's on-board time rolls over, + * and then reads the last recent raw IRIG data from the device. + * + * The API call ::mbg_chk_dev_has_raw_irig_data checks whether + * this call is supported by a device. + * + * <b>Note:</b> The ::mbg_get_time_sec_change function called + * by this function is supported under Windows only, so this function + * can also be used under Windows only. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_raw_irig_data + * @param[out] p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_raw_irig_data * @see ::mbg_get_raw_irig_data * @see ::mbg_get_time_sec_change -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data_on_sec_change( MBG_DEV_HANDLE dh, MBG_RAW_IRIG_DATA *p ) ; /** * @brief Read the IRIG time and day-of-year number from an IRIG receiver. - - Fills up a ::PCPS_IRIG_TIME structure with the raw IRIG day-of-year number - and time decoded from the latest IRIG input frame. If the configured IRIG code - also contains the year number then the year number is also returned, otherwise - the returned year number is 0xFF. - - The macro _pcps_has_irig_time() or the API call mbg_dev_has_irig_time() - check whether this call is supported by a device. - + * + * Reads a ::PCPS_IRIG_TIME structure with the raw IRIG day-of-year number + * and time decoded from the latest IRIG input frame. If the configured IRIG code + * also contains the year number then the year number is also returned, otherwise + * the returned year number is 0xFF. + * + * The API call ::mbg_chk_dev_has_irig_time checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_IRIG_TIME type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_irig_time -*/ + * @param[out] p Pointer to a ::PCPS_IRIG_TIME type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_irig_time + */ _MBG_API_ATTR int _MBG_API mbg_get_irig_time( MBG_DEV_HANDLE dh, PCPS_IRIG_TIME *p ) ; /** * @brief Clear a device's on-board time capture FIFO buffer. - - The macro _pcps_can_clr_ucap_buff() or the API call mbg_dev_can_clr_ucap_buff() - check whether this call is supported by a device. - + * + * The API call ::mbg_chk_dev_can_clr_ucap_buff checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_can_clr_ucap_buff + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_can_clr_ucap_buff * @see ::mbg_get_ucap_entries * @see ::mbg_get_ucap_event - */ + */ _MBG_API_ATTR int _MBG_API mbg_clr_ucap_buff( MBG_DEV_HANDLE dh ) ; /** * @brief Read information on a device's event capture buffer. - - Fills a ::PCPS_UCAP_ENTRIES structure with the number of user capture - events actually stored in the FIFO buffer, and the maximum number of - events that can be held by the buffer. - - The macro _pcps_has_ucap() or the API call mbg_dev_has_ucap() - check whether this call is supported by a device. - + * + * Reads a ::PCPS_UCAP_ENTRIES structure with the number of user capture + * events actually stored in the FIFO buffer, and the maximum number of + * events that can be held by the buffer. + * + * The API call ::mbg_chk_dev_has_ucap checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_UCAP_ENTRIES structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ucap + * @param[out] p Pointer to a ::PCPS_UCAP_ENTRIES structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ucap * @see ::mbg_get_ucap_entries * @see ::mbg_get_ucap_event - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ucap_entries( MBG_DEV_HANDLE dh, PCPS_UCAP_ENTRIES *p ) ; /** - * @brief Retrieve a single time capture event from the on-board FIFO buffer. - - The capture event is returned in a ::PCPS_HR_TIME structure. The oldest entry - in the FIFO is retrieved and then removed from the FIFO. - - If no capture event is available in the FIFO buffer then both the seconds - and the fractions of the returned timestamp are 0. - - The macro _pcps_has_ucap() or the API call mbg_dev_has_ucap() - check whether this call is supported by a device. - - <b>Note:</b> This call is very much faster than the older mbg_get_gps_ucap() - call which is obsolete but still supported for compatibility with - older cards. - + * @brief Retrieve a single time capture event from the on-board FIFO buffer + * + * The capture event is returned in a ::PCPS_HR_TIME structure. The oldest entry + * in the FIFO is retrieved and then removed from the FIFO. + * + * If no capture event is available in the FIFO buffer then both the seconds + * and the fractions of the returned timestamp are 0. + * + * The API call ::mbg_chk_dev_has_ucap checks whether + * this call is supported by a device. + * + * <b>Note:</b> This call is very much faster than the older ::mbg_get_gps_ucap + * call which is obsolete but still supported for compatibility with + * older cards. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_HR_TIME structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ucap + * @param[out] p Pointer to a ::PCPS_HR_TIME structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ucap * @see ::mbg_get_ucap_entries * @see ::mbg_clr_ucap_buff - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ucap_event( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) ; /** - * @brief Read the card's time zone/daylight saving parameters. - - This function returns the time zone/daylight saving parameters - in a ::TZDL structure. - - The macro _pcps_has_tzdl() or the API call mbg_dev_has_tzdl() - check whether this call is supported by a device. - - <b>Note:</b> In spite of the function name this call may also be - supported by non-GPS cards. Other cards may support the mbg_get_tzcode() - or mbg_get_pcps_tzdl() calls instead. - + * @brief Read the card's time zone/daylight saving parameters + * + * This function returns the time zone/daylight saving parameters + * in a ::TZDL structure. + * + * The API call ::mbg_chk_dev_has_tzdl checks whether + * this call is supported by a device. + * + * <b>Note:</b> In spite of the function name this call may also be + * supported by non-GPS cards. Other cards may support the ::mbg_get_tzcode + * or ::mbg_get_pcps_tzdl calls instead. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TZDL structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_tzdl + * @param[out] p Pointer to a ::TZDL structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_tzdl * @see ::mbg_set_gps_tzdl * @see ::mbg_get_tzcode * @see ::mbg_get_pcps_tzdl * @see @ref group_tzdl - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_tzdl( MBG_DEV_HANDLE dh, TZDL *p ) ; /** * @brief Write the card's time zone/daylight saving parameters. - - This function writes the time zone/daylight saving parameters - in a ::TZDL structure to a device. - - The macro _pcps_has_tzdl() or the API call mbg_dev_has_tzdl() - check whether this call is supported by a device. - - <b>Note:</b> In spite of the function name this call may also be - supported by non-GPS cards. Other cards may support the mbg_set_tzcode() - or mbg_set_pcps_tzdl() calls instead. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TZDL structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_tzdl + * + * This function writes the time zone/daylight saving parameters + * in a ::TZDL structure to a device. + * + * The API call ::mbg_chk_dev_has_tzdl checks whether + * this call is supported by a device. + * + * <b>Note:</b> In spite of the function name this call may also be + * supported by non-GPS cards. Other cards may support the ::mbg_set_tzcode + * or ::mbg_set_pcps_tzdl calls instead. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::TZDL structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_tzdl * @see ::mbg_get_gps_tzdl * @see ::mbg_set_tzcode * @see ::mbg_set_pcps_tzdl * @see @ref group_tzdl - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_tzdl( MBG_DEV_HANDLE dh, const TZDL *p ) ; /** - * @brief Retrieve the software revision of a GPS receiver. - - This call is obsolete but still supported for compatibility - with older GPS cards. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> The function mbg_get_gps_receiver_info() should - be used instead, if supported by the card. - + * @brief Retrieve the software revision of a GPS receiver + * + * @deprecated This function is deprecated. + * + * This function is deprecated, but still supported + * for compatibility with older GPS cards. Normally + * the software revision is part of the ::RECEIVER_INFO + * structure. See ::mbg_setup_receiver_info which takes + * care of the different options. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::SW_REV structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_is_gps - * @see ::mbg_get_gps_receiver_info - */ + * @param[out] p Pointer to a ::SW_REV structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_setup_receiver_info + * @see ::mbg_chk_dev_is_gps + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_sw_rev( MBG_DEV_HANDLE dh, SW_REV *p ) ; /** * @brief Retrieve the status of the battery buffered GPS variables. - - These GPS variables hold some parameters sent by the GPS satellites - which are required for proper operation. If the saved set of parameters - is not complete then the GPS receiver stays in COLD BOOT mode until - all data have been received and thus all data sets are valid. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - + * + * GPS receivers require some navigational data set to be available + * to be able to decode position and time accurately. This data set + * is transmitted periodically by the satellites, so it can + * simply be collected if it's not available. + * + * The ::BVAR_STAT type reports which parts of the data set are + * available in the receiver, and which are not. + * + * If the available data set is not complete then the receiver + * stays in COLD BOOT mode until all data have been received + * and thus all data sets are valid. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::BVAR_STAT structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::BVAR_STAT structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_is_gps + * @see ::BVAR_FLAGS */ _MBG_API_ATTR int _MBG_API mbg_get_gps_bvar_stat( MBG_DEV_HANDLE dh, BVAR_STAT *p ) ; /** - * @brief Read the current board time using a ::TTM structure. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This API call is pretty slow, so the mbg_get_hr_time_..() - or mbg_get_fast_hr_timestamp...() group of calls should be used preferably. - + * @brief Read the current board time using a ::TTM structure + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> This API call is pretty slow, so ::mbg_get_hr_time or + * ::mbg_get_fast_hr_timestamp or associated calls should be used preferably. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TTM structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::TTM structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_hr_time * @see ::mbg_get_fast_hr_timestamp -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_time( MBG_DEV_HANDLE dh, TTM *p ) ; /** - * @brief Set the time on a GPS receiver device. - - Write a ::TTM structure to a GPS receiver in order to set the - on-board date and time. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TTM structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @brief Set the time on a GPS receiver device + * + * Write a ::TTM structure to a GPS receiver in order to set + * the on-board date and time. Date and time must be local time + * according to the device's on-board time zone configuration + * (::TZDL). + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::TTM structure to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES */ _MBG_API_ATTR int _MBG_API mbg_set_gps_time( MBG_DEV_HANDLE dh, const TTM *p ) ; /** * @brief Read a ::PORT_PARM structure with a device's serial port configuration. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This function is obsolete since it is only - supported by a certain class of devices and can handle only - up to 2 ports. The generic function mbg_get_serial_settings() - should be used instead. - + * + * @deprecated This function is deprecated, use ::mbg_get_serial_settings preferably. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> This function is deprecated since it is only + * supported by a certain class of devices and can handle only + * up to 2 serial ports. The generic function ::mbg_get_serial_settings + * should be used instead. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PORT_PARM structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::PORT_PARM structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_serial_settings */ @@ -3254,19 +3613,21 @@ extern "C" { /** * @brief Write a ::PORT_PARM structure to configure the on-board serial ports. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This function is obsolete since it is only - supported by a certain class of devices and can handle only - up to 2 ports. The generic function mbg_save_serial_settings() - should be used instead. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PORT_PARM structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * + * @deprecated This function is deprecated, use ::mbg_save_serial_settings preferably. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> This function is deprecated since it is only + * supported by a certain class of devices and can handle only + * up to 2 ports. The generic function ::mbg_save_serial_settings + * should be used instead. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PORT_PARM structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_save_serial_settings */ @@ -3274,89 +3635,93 @@ extern "C" { /** * @brief Read an ::ANT_INFO structure to retrieve an extended GPS antenna status. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> Normally the current antenna connection status can also be - determined by evaluation of the ::PCPS_TIME::signal or ::PCPS_HR_TIME::signal - fields. The "disconnected" status reported by ANT_INFO disappears only if - the antenna has been reconnected <b>and</b> the receiver has synchronized - to the GPS satellites again. - + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> Normally the current antenna connection status can also be + * determined by evaluation of the ::PCPS_TIME::signal or ::PCPS_HR_TIME::signal + * fields. The "disconnected" status reported by ::ANT_INFO disappears only if + * the antenna has been reconnected <b>and</b> the receiver has synchronized + * to the GPS satellites again. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ANT_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::ANT_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES */ _MBG_API_ATTR int _MBG_API mbg_get_gps_ant_info( MBG_DEV_HANDLE dh, ANT_INFO *p ) ; /** - * @brief Read a time capture event from the on-board FIFO buffer using a ::TTM structure. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This call is pretty slow and has been obsoleted by - mbg_get_ucap_event() which should be used preferably, if supported - by the device. Anyway, this call is still supported for compatibility - with older devices. - + * @brief Read a time capture event from the on-board FIFO buffer using a ::TTM structure + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> This call is pretty slow and has been obsoleted by + * ::mbg_get_ucap_event which should be used preferably, if supported + * by the device. Anyway, this call is still supported for compatibility + * with older devices which don't support ::mbg_get_ucap_event. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TTM structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::TTM structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_ucap_entries * @see ::mbg_get_ucap_event * @see ::mbg_clr_ucap_buff -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_ucap( MBG_DEV_HANDLE dh, TTM *p ) ; /** - * @brief Read the ::ENABLE_FLAGS structure controlling when outputs are to be enabled. - - The ::ENABLE_FLAGS structure controls whether certain outputs - shall be enabled immediately after the card's power-up, or only - after the card has synchronized to its input signal. - + * @brief Read the ::ENABLE_FLAGS structure controlling when outputs are to be enabled + * + * The ::ENABLE_FLAGS structure controls whether certain signal outputs + * are to be enabled immediately after the device's power-up, or only + * after the device has synchronized to its input signal. + * * The function ::mbg_chk_dev_has_gps_data can be used to check * whether this call is supported by a device. - - <b>Note:</b> Not all of the input signals specified for the - ::ENABLE_FLAGS structure can be modified individually. - + * + * <b>Note:</b> Not all of the input signals specified for the + * ::ENABLE_FLAGS structure can be modified individually. + * See ::ENABLE_FLAGS_CODES. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::ENABLE_FLAGS structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::ENABLE_FLAGS structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::ENABLE_FLAGS + * @see ::ENABLE_FLAGS_CODES * @see ::mbg_set_gps_enable_flags -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_enable_flags( MBG_DEV_HANDLE dh, ENABLE_FLAGS *p ) ; /** - * @brief Write an ENABLE_FLAGS structure to configure when outputs shall be enabled. - - The ::ENABLE_FLAGS structure controls whether certain outputs - shall be enabled immediately after the card's power-up, or only - after the card has synchronized to its input signal. - + * @brief Write an ;;ENABLE_FLAGS structure to configure when outputs shall be enabled. + * + * The ::ENABLE_FLAGS structure controls whether certain signal outputs + * are to be enabled immediately after the device's power-up, or only + * after the device has synchronized to its input signal. + * * The function ::mbg_chk_dev_has_gps_data can be used to check * whether this call is supported by a device. - - <b>Note:</b> Not all of the input signals specified for the - ENABLE_FLAGS structure can be modified individually. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ENABLE_FLAGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * <b>Note:</b> Not all of the input signals specified for the + * ::ENABLE_FLAGS structure can be modified individually. + * See ::ENABLE_FLAGS_CODES. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ENABLE_FLAGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::ENABLE_FLAGS + * @see ::ENABLE_FLAGS_CODES * @see ::mbg_get_gps_enable_flags -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_enable_flags( MBG_DEV_HANDLE dh, const ENABLE_FLAGS *p ) ; /** @@ -3365,71 +3730,71 @@ extern "C" { * The ::STAT_INFO structure reports the status of the GPS receiver, * including mode of operation and number of visible/usable satellites. * - * The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::STAT_INFO structure to be filled up + * @param[out] p Pointer to a ::STAT_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::STAT_INFO */ _MBG_API_ATTR int _MBG_API mbg_get_gps_stat_info( MBG_DEV_HANDLE dh, STAT_INFO *p ) ; /** - * @brief Send a ::GPS_CMD to a GPS receiver device. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::GPS_CMD - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::PC_GPS_CMD_BOOT, ::PC_GPS_CMD_INIT_SYS, ::PC_GPS_CMD_INIT_USER, ::PC_GPS_CMD_INIT_DAC -*/ + * @brief Send one of the ::PC_GPS_COMMANDS to a GPS receiver device + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::GPS_CMD + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::PC_GPS_COMMANDS + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_cmd( MBG_DEV_HANDLE dh, const GPS_CMD *p ) ; /** * @brief Read the current geographic position from a GPS device. - - The returned ::POS structure contains the current position in - ECEF (Earth Centered, Earth Fixed) kartesian coordinates, and in - geographic coordinates with different formats, using the WGS84 - geographic datum. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - + * + * The returned ::POS structure contains the current position in + * ECEF (Earth Centered, Earth Fixed) kartesian coordinates, and in + * geographic coordinates with different formats, using the WGS84 + * geographic datum. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::POS structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::POS structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_gps_pos_xyz * @see ::mbg_set_gps_pos_lla -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_pos( MBG_DEV_HANDLE dh, POS *p ) ; /** - * @brief Set the GPS receiver position using ::XYZ coordinates. - - The structure ::XYZ must specify the new position in ECEF - (Earth Centered, Earth Fixed) kartesian coordinates. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param p Position in ::XYZ format to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Set the GPS receiver position using ::XYZ coordinates + * + * The structure ::XYZ must specify the new position in ECEF + * (Earth Centered, Earth Fixed) kartesian coordinates. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Position in ::XYZ format to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_gps_pos_lla * @see ::mbg_get_gps_pos -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_xyz( MBG_DEV_HANDLE dh, const XYZ p ) ; /** @@ -3438,13 +3803,13 @@ extern "C" { * The structure ::LLA must specify the new position as longitude, * latitude, and altitude, using the WGS84 geographic datum. * - * The macro ::_pcps_is_gps or the API call ::mbg_dev_is_gps - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param p Position in ::LLA format to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Position in ::LLA format to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_set_gps_pos_xyz * @see ::mbg_get_gps_pos @@ -3452,21 +3817,21 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_lla( MBG_DEV_HANDLE dh, const LLA p ) ; /** - * @brief Read the configured GPS antenna cable length from a device. + * @brief Read the configured antenna cable length from a device * * The antenna cable length parameter is used by GPS/GNSS receivers * to compensate the propagation delay of the RF signal over the antenna * cable, which is about 5 ns/m. * - * The macro ::_pcps_has_cab_len or the API call ::mbg_dev_has_cab_len - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_cab_len checks whether + * this call is supported by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p ::ANT_CABLE_LEN structure to be filled up + * @param[out] p Pointer to an ::ANT_CABLE_LEN structure to be filled up. * - * @return One of the @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_cab_len + * @see ::mbg_chk_dev_has_cab_len * @see ::mbg_set_gps_ant_cable_len */ _MBG_API_ATTR int _MBG_API mbg_get_gps_ant_cable_len( MBG_DEV_HANDLE dh, ANT_CABLE_LEN *p ) ; @@ -3478,131 +3843,132 @@ extern "C" { * to compensate the propagation delay of the RF signal over the antenna * cable, which is about 5 ns/m. * - * The macro ::_pcps_has_cab_len or the API call ::mbg_dev_has_cab_len - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_cab_len checks whether + * this call is supported by a device. * * @note Different devices may accept different maximum values, so the * written value should be re-read using ::mbg_get_gps_ant_cable_len * to check if the parameter has been accepted. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p ::ANT_CABLE_LEN structure to be written + * @param[out] p Pointer to an ::ANT_CABLE_LEN structure to be written. * - * @return One of the @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_cab_len + * @see ::mbg_chk_dev_has_cab_len * @see ::mbg_get_gps_ant_cable_len -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_ant_cable_len( MBG_DEV_HANDLE dh, const ANT_CABLE_LEN *p ) ; /** - * @brief Read the ::RECEIVER_INFO structure from a device. - - The macro _pcps_has_receiver_info() or the API call mbg_dev_has_receiver_info() - check whether this call is supported by a device. - - <b>Note:</b> Applications should call mbg_setup_receiver_info() - preferably, which also sets up a basic ::RECEIVER_INFO structure - for devices which don't provide that structure by themselves. - + * @brief Read the ::RECEIVER_INFO structure from a device + * + * The API call ::mbg_chk_dev_has_receiver_info checks + * whether this call is supported by a device. + * + * <b>Note:</b> Applications should call ::mbg_setup_receiver_info + * preferably, which also sets up a basic ::RECEIVER_INFO structure + * for devices which don't provide that structure by themselves. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::RECEIVER_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::RECEIVER_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_setup_receiver_info -*/ + * @see ::mbg_chk_dev_has_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_receiver_info( MBG_DEV_HANDLE dh, RECEIVER_INFO *p ) ; /** * @brief Read a ::STR_TYPE_INFO_IDX array of supported string types. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure passed to this function. - - <b>Note:</b> The function mbg_get_serial_settings() should be used preferably - to get retrieve the current port settings and configuration options. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param stii Pointer to a an array of string type information to be filled up - @param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info() - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_setup_receiver_info - * @see ::mbg_get_gps_all_port_info + * + * A valid ::RECEIVER_INFO associated with the device + * has to be passed to this function. + * + * <b>Note:</b> The function ::mbg_get_serial_settings should be used preferably + * to get retrieve the current port settings and configuration options. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] stii Pointer to a an array of string type information to be filled up. + * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device //### TODO Make this obsolete + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_serial_settings -*/ + * @see ::mbg_get_gps_all_port_info + * @see ::mbg_setup_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_str_type_info( MBG_DEV_HANDLE dh, STR_TYPE_INFO_IDX stii[], const RECEIVER_INFO *p_ri ) ; /** * @brief Read a ::PORT_INFO_IDX array of supported serial port configurations. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure passed to this function. - - <b>Note:</b> The function mbg_get_serial_settings() should be used preferably - to get retrieve the current port settings and configuration options. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pii Pointer to a an array of port configuration information to be filled up - @param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info() - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_setup_receiver_info - * @see ::mbg_get_gps_all_str_type_info + * + * A valid ::RECEIVER_INFO associated with the device + * has to be passed to this function. + * + * <b>Note:</b> The function ::mbg_get_serial_settings should be used preferably + * to get retrieve the current port settings and configuration options. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] pii Pointer to a an array of port configuration information to be filled up. + * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device //### TODO Make this obsolete + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_serial_settings -*/ + * @see ::mbg_get_gps_all_str_type_info + * @see ::mbg_setup_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_port_info( MBG_DEV_HANDLE dh, PORT_INFO_IDX pii[], const RECEIVER_INFO *p_ri ) ; /** * @brief Write the configuration for a single serial port to a device. - - The ::PORT_SETTINGS_IDX structure contains both the ::PORT_SETTINGS - and the port index value. Except for the parameter types this call is - equivalent to mbg_set_gps_port_settings(). - - The macro _pcps_has_receiver_info() or the API call mbg_dev_has_receiver_info() - check whether this call is supported by a device. - - <b>Note:</b> The function mbg_save_serial_settings() should be used preferably - to write new port configuration to the board. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PORT_SETTINGS_IDX structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The ::PORT_SETTINGS_IDX structure contains both the ::PORT_SETTINGS + * and the port index value. Except for the parameter types this call is + * equivalent to ::mbg_set_gps_port_settings. + * + * The API call ::mbg_chk_dev_has_receiver_info checks + * whether this call is supported by a device. + * + * <b>Note:</b> The function ::mbg_save_serial_settings should be used preferably + * to write new port configuration to the board. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PORT_SETTINGS_IDX structure to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_save_serial_settings * @see ::mbg_set_gps_port_settings - * @see ::mbg_dev_has_receiver_info -*/ + * @see ::mbg_chk_dev_has_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings_idx( MBG_DEV_HANDLE dh, const PORT_SETTINGS_IDX *p ) ; /** * @brief Write the configuration for a single serial port to a device. - - The ::PORT_SETTINGS structure does not contain the port index, so the - the port index must be given separately. Except for the parameter types - this call is equivalent to mbg_set_gps_port_settings_idx(). - - The macro _pcps_has_receiver_info() or the API call mbg_dev_has_receiver_info() - check whether this call is supported by a device. - - <b>Note:</b> The function mbg_save_serial_settings() should be used preferably - to write new port configuration to the board. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PORT_SETTINGS structure to be filled up - @param idx Index of the serial port to be configured (starting from 0 ). - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The ::PORT_SETTINGS structure does not contain the port index, so the + * the port index must be given separately. Except for the parameter types + * this call is equivalent to ::mbg_set_gps_port_settings_idx. + * + * The API call ::mbg_chk_dev_has_receiver_info checks + * whether this call is supported by a device. + * + * <b>Note:</b> The function ::mbg_save_serial_settings should be used preferably + * to write new port configuration to the board. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PORT_SETTINGS structure to be written. + * @param[in] idx Index of the serial port to be configured (starting from 0). + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_save_serial_settings * @see ::mbg_set_gps_port_settings_idx - * @see ::mbg_dev_has_receiver_info -*/ + * @see ::mbg_chk_dev_has_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings( MBG_DEV_HANDLE dh, const PORT_SETTINGS *p, int idx ) ; /** @@ -3611,225 +3977,232 @@ extern "C" { * If the device supports the ::RECEIVER_INFO structure then the structure * is read from the device, otherwise a structure is set up using * default values depending on the device type. - * Optionally, the function mbg_get_device_info() may have been called + * + * Optionally, the function ::mbg_get_device_info may have been called * before, and the returned ::PCPS_DEV structure can be passed to this * function. + * * If a NULL pointer is passed instead, the device info is retrieved * directly from the device, using the device handle. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] p_dev Optional pointer to a ::PCPS_DEV structure, may be NULL - * @param[out] p Pointer to a ::RECEIVER_INFO structure to be filled up + * @param[in] p_dev Optional pointer to a ::PCPS_DEV structure, may be NULL. + * @param[out] p Pointer to a ::RECEIVER_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_device_info - * @see ::mbg_dev_has_receiver_info + * @see ::mbg_chk_dev_has_receiver_info */ _MBG_API_ATTR int _MBG_API mbg_setup_receiver_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, RECEIVER_INFO *p ) ; /** * @brief Read the version code of the on-board PCI/PCIe interface ASIC. - - The macro _pcps_has_asic_version() or the API call mbg_dev_has_asic_version() - check whether this call is supported by a device. - + * + * The API call ::mbg_chk_dev_has_asic_version checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCI_ASIC_VERSION type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_asic_version -*/ + * @param[out] p Pointer to a ::PCI_ASIC_VERSION type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_asic_version + */ _MBG_API_ATTR int _MBG_API mbg_get_asic_version( MBG_DEV_HANDLE dh, PCI_ASIC_VERSION *p ) ; /** - * @brief Read the features of the on-board PCI/PCIe interface ASIC. - - The macro _pcps_has_asic_features() or the API call mbg_dev_has_asic_features() - check whether this call is supported by a device. - + * @brief Read the features of the on-board PCI/PCIe interface ASIC + * + * The API call ::mbg_chk_dev_has_asic_features checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCI_ASIC_FEATURES type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_asic_features -*/ + * @param[out] p Pointer to a ::PCI_ASIC_FEATURES type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_asic_features + */ _MBG_API_ATTR int _MBG_API mbg_get_asic_features( MBG_DEV_HANDLE dh, PCI_ASIC_FEATURES *p ) ; /** - * @brief Read the current time scale settings and which time scales are supported. - - The ::MBG_TIME_SCALE_INFO structure tells which time scale settings are supported - by a device, and which time scale is currently configured. - - The macro _pcps_has_time_scale() or the API call mbg_dev_has_time_scale() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_time_scale(). - + * @brief Read the current time scale settings and which time scales are supported + * + * The ::MBG_TIME_SCALE_INFO structure tells which time scale settings are supported + * by a device, and which time scale is currently configured. + * + * The API call ::mbg_chk_dev_has_time_scale checks whether + * this call is supported by a device. + * + * See also the notes for ::mbg_chk_dev_has_time_scale. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_TIME_SCALE_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::MBG_TIME_SCALE_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_time_scale_settings - * @see ::mbg_dev_has_time_scale -*/ + * @see ::mbg_chk_dev_has_time_scale + */ _MBG_API_ATTR int _MBG_API mbg_get_time_scale_info( MBG_DEV_HANDLE dh, MBG_TIME_SCALE_INFO *p ) ; /** - * @brief Write the time scale configuration to a device. - - The ::MBG_TIME_SCALE_SETTINGS structure determines which time scale - is to be used for the time stamps which can be read from a device. - - The macro _pcps_has_time_scale() or the API call mbg_dev_has_time_scale() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_time_scale(). - - The function mbg_get_time_scale_info() should have been called before - in order to determine which time scales are supported by the card. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_TIME_SCALE_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Write the time scale configuration to a device + * + * The ::MBG_TIME_SCALE_SETTINGS structure determines which time scale + * is to be used for the time stamps which can be read from a device. + * + * The API call ::mbg_chk_dev_has_time_scale checks whether + * this call is supported by a device. + * + * See also the notes for ::mbg_chk_dev_has_time_scale. + * + * The function ::mbg_get_time_scale_info should have been called before + * in order to determine which time scales are supported by the card. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::MBG_TIME_SCALE_SETTINGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_time_scale_info - * @see ::mbg_dev_has_time_scale -*/ + * @see ::mbg_chk_dev_has_time_scale + */ _MBG_API_ATTR int _MBG_API mbg_set_time_scale_settings( MBG_DEV_HANDLE dh, const MBG_TIME_SCALE_SETTINGS *p ) ; /** - * @brief Read a ::UTC parameter structure from a device. - - The macro _pcps_has_utc_parm() or the API call mbg_dev_has_utc_parm() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_utc_parm(). - + * @brief Read a ::UTC parameter structure from a device + * + * The API call ::mbg_chk_dev_has_utc_parm checks whether + * this call is supported by a device. + * + * See also the notes for ::mbg_chk_dev_has_utc_parm. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::UTC structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_utc_parm + * @param[out] p Pointer to a ::UTC structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_utc_parm * @see ::mbg_set_utc_parm -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_utc_parm( MBG_DEV_HANDLE dh, UTC *p ) ; /** * @brief Write a ::UTC parameter structure to a device. - - This should only be done for testing, or if a card is operated in - freewheeling mode. If the receiver is tracking any satellites then the settings - written to the device are overwritten by the parameters broadcasted - by the satellites. - - The macro _pcps_has_utc_parm() or the API call mbg_dev_has_utc_parm() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_utc_parm(). - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a valid ::UTC structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_utc_parm + * + * This should only be done for testing, or if a card is operated in + * freewheeling mode. If the receiver is tracking any satellites then the settings + * written to the device are overwritten by the parameters broadcast + * by the satellites. + * + * The API call ::mbg_chk_dev_has_utc_parm checks whether + * this call is supported by a device. + * + * See also the notes for mbg_chk_dev_has_utc_parm. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a valid ::UTC structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_utc_parm * @see ::mbg_get_utc_parm -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_utc_parm( MBG_DEV_HANDLE dh, const UTC *p ) ; /** * @brief Read the current time plus the associated PC cycles from a device. - - The ::PCPS_TIME_CYCLES structure contains a ::PCPS_TIME structure - and a PC cycle counter value which can be used to compensate the latency - of the call, i.e. the program execution time until the time stamp has actually - been read from the board. - - This call is supported for any card, similar to mbg_get_time(). However, - the mbg_get_hr_time_cyles() call should be used preferably if supported by - the device since that call provides much better accuracy than this one. - - The cycle counter value corresponds to a value returned by QueryPerformanceCounter() - under Windows, and get_cycles() under Linux. On operating systems or targets which don't - provide a cycles counter the returned cycles value is always 0. - - Applications should first pick up their own cycle counter value and then call - this function. The difference of the cycle counter values corresponds to the - latency of the call in units of the cycle counter clock frequency, e.g as reported - by QueryPerformanceFrequency() under Windows. - + * + * The ::PCPS_TIME_CYCLES structure contains a ::PCPS_TIME structure + * and a PC cycles counter value which can be used to compensate the latency + * of the call, i.e. the program execution time until the time stamp has actually + * been read from the board. + * + * This call is supported for any card, similar to ::mbg_get_time. However, + * the ::mbg_get_hr_time_cycles call should be used preferably if supported by + * the device since that call provides much better accuracy than this one. + * + * The cycles counter value corresponds to a value returned by QueryPerformanceCounter() + * under Windows, and get_cycles() under Linux. On operating systems or targets which don't + * provide a cycles counter the returned cycles value is always 0. + * + * Applications should first pick up their own cycles counter value and then call + * this function. The difference of the cycles counter values corresponds to the + * latency of the call in units of the cycles counter clock frequency, e.g as reported + * by QueryPerformanceFrequency() under Windows. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_CYCLES structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::PCPS_TIME_CYCLES structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_legacy_time_fncs * @see ::mbg_get_hr_time_cycles * @see ::mbg_get_hr_time_comp * @see ::mbg_get_hr_time * @see ::mbg_get_time -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_time_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_CYCLES *p ) ; /** * @brief Read the current high resolution time plus the associated PC cycles from a device. * * The returned ::PCPS_HR_TIME_CYCLES structure contains a ::PCPS_HR_TIME - * structure and a PC cycle counter value which can be used to compensate + * structure and a PC cycles counter value which can be used to compensate * the latency of the call, i.e. the program execution time until the time stamp * has actually been read from the board. * - * The API call ::mbg_chk_dev_has_hr_time checks whether this call - * is supported by the device. + * The API call ::mbg_chk_dev_has_hr_time checks whether + * this call is supported by the device. * - * For details see @ref ::pcps_hr_time_fncs + * For details see @ref ::mbgdevio_hr_time_fncs * - * The cycle counter value corresponds to a value returned by QueryPerformanceCounter() + * The cycles counter value corresponds to a value returned by QueryPerformanceCounter() * under Windows, and get_cycles() under Linux. On operating systems or targets which don't * provide a cycles counter the returned cycles value is always 0. * - * Applications should first pick up their own 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 cycles counter value and then call + * this function. The difference of the cycles counter values corresponds to the + * latency of the call in units of the cycles counter clock frequency, e.g as reported * by QueryPerformanceFrequency() under Windows. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_HR_TIME_CYCLES structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @ingroup pcps_hr_time_fncs + * @ingroup mbgdevio_hr_time_fncs * @see ::mbg_chk_dev_has_hr_time * @see ::mbg_get_hr_time * @see ::mbg_get_hr_time_cycles * @see ::mbg_get_hr_time_comp - * @see @ref pcps_hr_time_fncs - * @see @ref pcps_fast_timestamp_fncs - * @see @ref pcps_std_time_fncs + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs */ _MBG_API_ATTR int _MBG_API mbg_get_hr_time_cycles( MBG_DEV_HANDLE dh, PCPS_HR_TIME_CYCLES *p ) ; /** * @brief Read the current high resolution time, and compensate the call's latency. * - * Read a ::PCPS_HR_TIME structure plus cycle counter value, and correct the + * Read a ::PCPS_HR_TIME structure plus cycles counter value, and correct the * time stamp for the latency of the call as described for ::mbg_get_hr_time_cycles, - * then return the compensated time stamp and optionally the latency. + * then return the compensated time stamp, and optionally the latency. * - * The API call ::mbg_chk_dev_has_hr_time checks whether this call - * is supported by the device. + * The API call ::mbg_chk_dev_has_hr_time checks whether + * this call is supported by the device. * - * For details see @ref ::pcps_hr_time_fncs + * For details see @ref ::mbgdevio_hr_time_fncs * - * The cycle counter value corresponds to a value returned by QueryPerformanceCounter() + * The cycles counter value corresponds to a value returned by QueryPerformanceCounter() * under Windows, and get_cycles() under Linux. On operating systems or targets which don't * provide a cycles counter the returned cycles value is always 0. * - * Applications should first pick up their own 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 cycles counter value and then call + * this function. The difference of the cycles counter values corresponds to the + * latency of the call in units of the cycles counter clock frequency, e.g as reported * by QueryPerformanceFrequency() under Windows. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. @@ -3837,75 +4210,75 @@ extern "C" { * @param[out] hns_latency Optional pointer to an int32_t value to return * the latency in 100ns units, or NULL, if not used. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @ingroup pcps_hr_time_fncs + * @ingroup mbgdevio_hr_time_fncs * @see ::mbg_chk_dev_has_hr_time * @see ::mbg_get_hr_time * @see ::mbg_get_hr_time_cycles * @see ::mbg_get_hr_time_comp - * @see @ref pcps_hr_time_fncs - * @see @ref pcps_fast_timestamp_fncs - * @see @ref pcps_std_time_fncs + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs */ _MBG_API_ATTR int _MBG_API mbg_get_hr_time_comp( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p, int32_t *hns_latency ) ; /** * @brief Read the current IRIG output settings plus the supported settings. - - The returned ::IRIG_INFO structure contains the configuration of an IRIG output - plus the possible settings supported by that output. - - The macro _pcps_has_irig_tx() or the API call mbg_dev_has_irig_tx() - check whether this call is supported by a device. - + * + * The returned ::IRIG_INFO structure contains the configuration of an IRIG output + * plus the possible settings supported by that output. + * + * The API call ::mbg_chk_dev_has_irig_tx checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an ::IRIG_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to an ::IRIG_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_irig_tx_settings - * @see ::mbg_dev_has_irig_tx - * @see ::mbg_dev_is_irig_rx - * @see ::mbg_dev_has_irig + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig * @see @ref group_icode -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_irig_tx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p ) ; /** - * @brief Write an ::IRIG_SETTINGS structure to a device to configure the IRIG output. - - The macro _pcps_has_irig_tx() or the API call mbg_dev_has_irig_tx() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an ::IRIG_INFO structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Write an ::IRIG_SETTINGS structure to a device to configure the IRIG output + * + * The API call ::mbg_chk_dev_has_irig_tx checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to an ::IRIG_INFO structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_irig_tx_info - * @see ::mbg_dev_has_irig_tx - * @see ::mbg_dev_is_irig_rx - * @see ::mbg_dev_has_irig + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig * @see @ref group_icode -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_irig_tx_settings( MBG_DEV_HANDLE dh, const IRIG_SETTINGS *p ) ; /** - * @brief Read the current frequency synthesizer settings from a device. + * @brief Read the current frequency synthesizer settings from a device * * Read a ::SYNTH structure containing the configuration of an optional * on-board programmable frequency synthesizer. * - * The macro ::_pcps_has_synth or the API call ::mbg_dev_has_synth - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_synth checks whether + * this call is supported by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::SYNTH structure to be filled up + * @param[out] p Pointer to a ::SYNTH structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_synth + * @see ::mbg_chk_dev_has_synth * @see ::mbg_set_synth * @see ::mbg_get_synth_state * @see @ref group_synth @@ -3913,375 +4286,373 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_synth( MBG_DEV_HANDLE dh, SYNTH *p ) ; /** - * @brief Write some frequency synthesizer settings to a device. + * @brief Write frequency synthesizer configuration settings to a device * * Write a ::SYNTH structure containing the configuration of an optional * on-board programmable frequency synthesizer. * - * The macro _pcps_has_synth() or the API call mbg_dev_has_synth() - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_synth checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::SYNTH structure to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::SYNTH structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_synth + * @see ::mbg_chk_dev_has_synth * @see ::mbg_get_synth * @see ::mbg_get_synth_state - * @see @::\ref group_synth + * @see @ref group_synth */ _MBG_API_ATTR int _MBG_API mbg_set_synth( MBG_DEV_HANDLE dh, const SYNTH *p ) ; /** - * @brief Read the current status of the on-board frequency synthesizer. - - The macro _pcps_has_synth() or the API call mbg_dev_has_synth() - check whether this call is supported by a device. - + * @brief Read the current status of the on-board frequency synthesizer + * + * The API call ::mbg_chk_dev_has_synth checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::SYNTH_STATE structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_synth + * @param[out] p Pointer to a ::SYNTH_STATE structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_synth * @see ::mbg_get_synth * @see ::mbg_set_synth * @see @ref group_synth -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_synth_state( MBG_DEV_HANDLE dh, SYNTH_STATE *p ) ; /** * @brief Read a high resolution ::PCPS_TIME_STAMP_CYCLES structure via memory mapped access. - + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_STAMP_CYCLES structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @ingroup pcps_fast_timestamp_fncs - * @see ::mbg_dev_has_fast_hr_timestamp + * @param[out] p Pointer to a ::PCPS_TIME_STAMP_CYCLES structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_fast_timestamp_fncs + * @see ::mbg_chk_dev_has_fast_hr_timestamp * @see ::mbg_get_fast_hr_timestamp_comp * @see ::mbg_get_fast_hr_timestamp - * @see @ref pcps_fast_timestamp_fncs + * @see @ref mbgdevio_fast_timestamp_fncs */ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP_CYCLES *p ) ; /** - * @brief Read a high resolution timestamp and compensate the latency of the call. - - The retrieved ::PCPS_TIME_STAMP is read from memory mapped registers, - and timestamp is compensated for the call's latency before it is returned. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_STAMP structure to be filled up - @param *hns_latency Optionally receive the latency in hectonanoseconds - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @ingroup pcps_fast_timestamp_fncs - * @see ::mbg_dev_has_fast_hr_timestamp + * @brief Read a high resolution timestamp and compensate the latency of the call + * + * The retrieved ::PCPS_TIME_STAMP is read from memory mapped registers, + * and timestamp is compensated for the call's latency before it is returned. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::PCPS_TIME_STAMP structure to be filled up + * @param[out] hns_latency Optionally receives the latency in hectonanoseconds //### TODO Check if hns + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_fast_timestamp_fncs + * @see ::mbg_chk_dev_has_fast_hr_timestamp * @see ::mbg_get_fast_hr_timestamp_cycles * @see ::mbg_get_fast_hr_timestamp - * @see @ref pcps_fast_timestamp_fncs + * @see @ref mbgdevio_fast_timestamp_fncs */ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_comp( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP *p, int32_t *hns_latency ) ; /** - * @brief Read a high resolution ::PCPS_TIME_STAMP structure via memory mapped access. - - This function does not return or evaluate a cycles count, so the latency - of the call can not be determined. However, depending on the timer hardware - used as cycles counter it may take quite some time to read the cycles count - on some hardware architectures, so this call can be used to yield lower - latencies, under the restriction to be unable to determine the exact latency. - + * @brief Read a high resolution ::PCPS_TIME_STAMP structure via memory mapped access + * + * This function does not return or evaluate a cycles count, so the latency + * of the call can not be determined. However, depending on the timer hardware + * used as cycles counter it may take quite some time to read the cycles count + * on some hardware architectures, so this call can be used to yield lower + * latencies, under the restriction to be unable to determine the exact latency. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_STAMP structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @ingroup pcps_fast_timestamp_fncs - * @see ::mbg_dev_has_fast_hr_timestamp + * @param[out] p Pointer to a ::PCPS_TIME_STAMP structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_fast_timestamp_fncs + * @see ::mbg_chk_dev_has_fast_hr_timestamp * @see ::mbg_get_fast_hr_timestamp_comp * @see ::mbg_get_fast_hr_timestamp_cycles - * @see @ref pcps_fast_timestamp_fncs + * @see @ref mbgdevio_fast_timestamp_fncs */ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP *p ) ; /** * @brief Read current configuraton and features provided by the programmable pulse outputs. - - Reads a ::POUT_INFO_IDX array of current settings and configuration - options of the device's programmable pulse outputs. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure passed to this function. - The function should only be called if the ::RECEIVER_INFO::n_prg_out - field (i.e. the number of programmable outputs on the board) is not 0. - - The array passed to this function to receive the returned data - must be able to hold at least ::RECEIVER_INFO::n_prg_out elements. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pii Pointer to a an array of ::POUT_INFO_IDX structures to be filled up - @param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info() - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * Read a ::POUT_INFO_IDX array of current settings and configuration + * options of the device's programmable pulse outputs. + * + * A valid ::RECEIVER_INFO associated with the device + * has to be passed to this function. + * + * The function should only be called if the ::RECEIVER_INFO::n_prg_out + * field (i.e. the number of programmable outputs on the board) is not 0. + * + * The array passed to this function to receive the returned data + * must be able to hold at least ::RECEIVER_INFO::n_prg_out elements. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] pii Pointer to a an array of ::POUT_INFO_IDX structures to be filled up + * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device //### TODO Make this obsolete + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_gps_pout_settings_idx * @see ::mbg_set_gps_pout_settings * @see ::mbg_setup_receiver_info -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_pout_info( MBG_DEV_HANDLE dh, POUT_INFO_IDX pii[], const RECEIVER_INFO *p_ri ) ; /** * @brief Write the configuration for a single programmable pulse output - - The ::POUT_SETTINGS_IDX structure contains both the ::POUT_SETTINGS - and the output index value. Except for the parameter types this call - is equivalent to mbg_set_gps_pout_settings(). - - The function should only be called if the ::RECEIVER_INFO::n_prg_out field - (i.e. the number of programmable outputs on the board) is not 0, and the - output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::POUT_SETTINGS_IDX structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The ::POUT_SETTINGS_IDX structure contains both the ::POUT_SETTINGS + * and the output index value. Except for the parameter types this call + * is equivalent to ::mbg_set_gps_pout_settings. + * + * The function should only be called if the ::RECEIVER_INFO::n_prg_out field + * (i.e. the number of programmable outputs on the board) is not 0, and the + * output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::POUT_SETTINGS_IDX structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_gps_all_pout_info * @see ::mbg_set_gps_pout_settings -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings_idx( MBG_DEV_HANDLE dh, const POUT_SETTINGS_IDX *p ) ; /** * @brief Write the configuration for a single programmable pulse output - - The ::POUT_SETTINGS structure does not contain the index of the - programmable output to be configured, so the index must explicitely - be passed to this function. Except for the parameter types this call - is equivalent to mbg_set_gps_pout_settings_idx(). - - The function should only be called if the ::RECEIVER_INFO::n_prg_out field - (i.e. the number of programmable outputs on the board) is not 0, and the - output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::POUT_SETTINGS structure to be written - @param idx Index of the programmable pulse output to be configured (starting from 0 ). - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The ::POUT_SETTINGS structure does not contain the index of the + * programmable output to be configured, so the index must explicitly + * be passed to this function. Except for the parameter types this call + * is equivalent to ::mbg_set_gps_pout_settings_idx. + * + * The function should only be called if the ::RECEIVER_INFO::n_prg_out field + * (i.e. the number of programmable outputs on the board) is not 0, and the + * output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::POUT_SETTINGS structure to be written. + * @param[in] idx Index of the programmable pulse output to be configured (starting from 0 ). + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_gps_all_pout_info * @see ::mbg_set_gps_pout_settings_idx -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings( MBG_DEV_HANDLE dh, const POUT_SETTINGS *p, int idx ) ; /** * @brief Read a device's IRQ status information. - - IRQ status information includes flags indicating whether IRQs are - actually enabled, and whether IRQ support by a card is possibly - unsafe due to the firmware and interface chip version. - + * + * IRQ status information includes flags indicating whether IRQs are + * actually enabled, and whether IRQ support by a card is possibly + * unsafe due to the firmware and interface chip version. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_IRQ_STAT_INFO variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::PCPS_IRQ_STAT_INFO variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see @ref PCPS_IRQ_STAT_INFO_DEFS */ _MBG_API_ATTR int _MBG_API mbg_get_irq_stat_info( MBG_DEV_HANDLE dh, PCPS_IRQ_STAT_INFO *p ) ; /** - * @brief Read LAN interface information from a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - + * @brief Read LAN interface information from a device + * + * The API call ::mbg_chk_dev_has_lan_intf checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::LAN_IF_INFO variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_lan_intf + * @param[out] p Pointer to a ::LAN_IF_INFO variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_ip4_state * @see ::mbg_get_ip4_settings * @see ::mbg_set_ip4_settings - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_lan_if_info( MBG_DEV_HANDLE dh, LAN_IF_INFO *p ) ; /** - * @brief Read LAN IPv4 state from a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - + * @brief Read LAN IPv4 state from a device + * + * The API call ::mbg_chk_dev_has_lan_intf checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::IP4_SETTINGS variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_lan_intf + * @param[out] p Pointer to a ::IP4_SETTINGS variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info * @see ::mbg_get_ip4_settings * @see ::mbg_set_ip4_settings - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ip4_state( MBG_DEV_HANDLE dh, IP4_SETTINGS *p ) ; /** * @brief Read LAN IPv4 settings from a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - + * + * The API call ::mbg_chk_dev_has_lan_intf checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::IP4_SETTINGS variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_lan_intf + * @param[out] p Pointer to a ::IP4_SETTINGS variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info * @see ::mbg_get_ip4_state * @see ::mbg_set_ip4_settings - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ip4_settings( MBG_DEV_HANDLE dh, IP4_SETTINGS *p ) ; /** - * @brief Write LAN IPv4 settings to a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p ::IP4_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_lan_intf + * @brief Write LAN IPv4 settings to a device + * + * The API call ::mbg_chk_dev_has_lan_intf checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p ::IP4_SETTINGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info * @see ::mbg_get_ip4_settings -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_ip4_settings( MBG_DEV_HANDLE dh, const IP4_SETTINGS *p ) ; /** - * @brief Read PTP/IEEE1588 status from a device. - - The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp() - check whether this call is supported by a device. - + * @brief Read PTP/IEEE1588 status from a device + * + * The API call ::mbg_chk_dev_has_ptp checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PTP_STATE variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp + * @param[out] p Pointer to a ::PTP_STATE variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_cfg_info * @see ::mbg_set_ptp_cfg_settings - * @see ::mbg_dev_has_ptp_unicast - */ + * @see ::mbg_chk_dev_has_ptp_unicast + */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_state( MBG_DEV_HANDLE dh, PTP_STATE *p ) ; /** - * @brief Read PTP/IEEE1588 config info and current settings from a device. - - The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp() - check whether this call is supported by a device. - + * @brief Read PTP/IEEE1588 config info and current settings from a device + * + * The API call ::mbg_chk_dev_has_ptp checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PTP_CFG_INFO variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp + * @param[out] p Pointer to a ::PTP_CFG_INFO variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_state * @see ::mbg_set_ptp_cfg_settings - * @see ::mbg_dev_has_ptp_unicast - */ + * @see ::mbg_chk_dev_has_ptp_unicast + */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_cfg_info( MBG_DEV_HANDLE dh, PTP_CFG_INFO *p ) ; /** * @brief Write PTP/IEEE1588 configuration settings to a device. - - The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p ::PTP_CFG_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp + * + * The API call ::mbg_chk_dev_has_ptp checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p ::PTP_CFG_SETTINGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_state * @see ::mbg_get_ptp_cfg_info - * @see ::mbg_dev_has_ptp_unicast -*/ + * @see ::mbg_chk_dev_has_ptp_unicast + */ _MBG_API_ATTR int _MBG_API mbg_set_ptp_cfg_settings( MBG_DEV_HANDLE dh, const PTP_CFG_SETTINGS *p ) ; /** * @brief Read PTP/IEEE1588 unicast master configuration limits from a device. - - The macro _pcps_has_ri_ptp_unicast() or the API call mbg_dev_has_ptp_unicast() - check whether this call is supported by a device. - + * + * The API call ::mbg_chk_dev_has_ptp_unicast checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PTP_UC_MASTER_CFG_LIMITS variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp_unicast + * @param[out] p Pointer to a ::PTP_UC_MASTER_CFG_LIMITS variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp_unicast * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_all_ptp_uc_master_info * @see ::mbg_set_ptp_uc_master_settings_idx * @see ::mbg_get_ptp_state - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_uc_master_cfg_limits( MBG_DEV_HANDLE dh, PTP_UC_MASTER_CFG_LIMITS *p ) ; /** * @brief Read PTP Unicast master settings and configuration options. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure passed to this function. - The function should only be called if the ::RECEIVER_INFO::n_prg_out - field (i.e. the number of programmable outputs on the board) is not 0. - - The array passed to this function to receive the returned data - must be able to hold at least ::RECEIVER_INFO::n_prg_out elements. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pii Pointer to a an array of ::PTP_UC_MASTER_INFO_IDX structures to be filled up - @param p_umsl Pointer to a ::PTP_UC_MASTER_CFG_LIMITS structure returned by mbg_get_ptp_uc_master_cfg_limits() - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp_unicast + * + * The array passed to this function to receive the returned data + * must be able to hold at least ::PTP_UC_MASTER_CFG_LIMITS::n_supp_master elements. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] pii Pointer to a an array of ::PTP_UC_MASTER_INFO_IDX structures to be filled up. + * @param[in] p_umsl Pointer to a ::PTP_UC_MASTER_CFG_LIMITS structure returned by ::mbg_get_ptp_uc_master_cfg_limits + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp_unicast * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_uc_master_cfg_limits * @see ::mbg_set_ptp_uc_master_settings_idx * @see ::mbg_get_ptp_state -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_all_ptp_uc_master_info( MBG_DEV_HANDLE dh, PTP_UC_MASTER_INFO_IDX pii[], const PTP_UC_MASTER_CFG_LIMITS *p_umsl ) ; /** - * @brief Write PTP/IEEE1588 unicast configuration settings to a device. - - The macro _pcps_has_ri_ptp_unicast() or the API call mbg_dev_has_ptp_unicast() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p ::PTP_UC_MASTER_SETTINGS_IDX structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp_unicast + * @brief Write PTP/IEEE1588 unicast configuration settings to a device + * + * The API call ::mbg_chk_dev_has_ptp_unicast checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p ::PTP_UC_MASTER_SETTINGS_IDX structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp_unicast * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_uc_master_cfg_limits * @see ::mbg_get_all_ptp_uc_master_info * @see ::mbg_get_ptp_state -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_ptp_uc_master_settings_idx( MBG_DEV_HANDLE dh, const PTP_UC_MASTER_SETTINGS_IDX *p ) ; /** @@ -4298,33 +4669,33 @@ extern "C" { * the board. * * This call makes a ::mbg_get_hr_time_cycles call internally so the API call - * ::mbg_dev_has_hr_time can be used to check whether this call is supported + * ::mbg_chk_dev_has_hr_time can be used to check whether this call is supported * by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::MBG_TIME_INFO_HRT structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_hr_time + * @see ::mbg_chk_dev_has_hr_time * @see ::mbg_get_time_info_tstamp */ _MBG_API_ATTR int _MBG_API mbg_get_time_info_hrt( MBG_DEV_HANDLE dh, MBG_TIME_INFO_HRT *p ) ; /** - * @brief Read both system time and associated device timestamp from the kernel driver. + * @brief Read both system time and associated device timestamp from the kernel driver * * This call is similar to ::mbg_get_time_info_hrt except that a - * ::mbg_get_fast_hr_timestamp_cycles call is made internally, so the - * API call ::mbg_dev_has_fast_hr_timestamp can be used to check - * whether this call is supported by a device. + * ::mbg_get_fast_hr_timestamp_cycles call is made internally, so + * the API call ::mbg_chk_dev_has_fast_hr_timestamp can be used to check whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::MBG_TIME_INFO_TSTAMP structure to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_TIME_INFO_TSTAMP structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_fast_hr_timestamp + * @see ::mbg_chk_dev_has_fast_hr_timestamp * @see ::mbg_get_time_info_hrt */ _MBG_API_ATTR int _MBG_API mbg_get_time_info_tstamp( MBG_DEV_HANDLE dh, MBG_TIME_INFO_TSTAMP *p ) ; @@ -4332,35 +4703,35 @@ extern "C" { /** * @brief Read PZF correlation info from a device * - * The the API call ::mbg_dev_has_corr_info checks - * whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_corr_info checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::CORR_INFO structure to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::CORR_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_pzf - * @see ::mbg_dev_has_corr_info + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_chk_dev_has_corr_info */ _MBG_API_ATTR int _MBG_API mbg_get_corr_info( MBG_DEV_HANDLE dh, CORR_INFO *p ) ; /** - * @brief Read configurable "distance from transmitter" parameter from a device. + * @brief Read configurable "distance from transmitter" parameter from a device * * The distance from transmitter parameter is used to compensate * the RF propagation delay, mostly with long wave receivers. * - * The API call ::mbg_dev_has_tr_distance checks whether this call - * is supported by a device. + * The API call ::mbg_chk_dev_has_tr_distance checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::TR_DISTANCE variable to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::TR_DISTANCE variable to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_pzf - * @see ::mbg_dev_has_tr_distance + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_chk_dev_has_tr_distance * @see ::mbg_set_tr_distance */ _MBG_API_ATTR int _MBG_API mbg_get_tr_distance( MBG_DEV_HANDLE dh, TR_DISTANCE *p ) ; @@ -4371,16 +4742,16 @@ extern "C" { * The distance from transmitter parameter is used to compensate * the RF propagation delay, mostly with long wave receivers. * - * The API call ::mbg_dev_has_tr_distance checks whether this call - * is supported by a device. + * The API call ::mbg_chk_dev_has_tr_distance checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] p Pointer to a ::TR_DISTANCE variable to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::TR_DISTANCE variable to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_pzf - * @see ::mbg_dev_has_tr_distance + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_chk_dev_has_tr_distance * @see ::mbg_get_tr_distance */ _MBG_API_ATTR int _MBG_API mbg_set_tr_distance( MBG_DEV_HANDLE dh, const TR_DISTANCE *p ) ; @@ -4394,29 +4765,29 @@ extern "C" { * * See ::MBG_DEBUG_STATUS and related definitions for details. * - * The API call ::mbg_dev_has_debug_status checks whether this call - * is supported by a device. + * The API call ::mbg_chk_dev_has_debug_status checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::MBG_DEBUG_STATUS variable to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_DEBUG_STATUS variable to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_debug_status + * @see ::mbg_chk_dev_has_debug_status */ _MBG_API_ATTR int _MBG_API mbg_get_debug_status( MBG_DEV_HANDLE dh, MBG_DEBUG_STATUS *p ) ; /** - * @brief Clear the device's on-board event log. + * @brief Clear the device's on-board event log * - * The API call ::mbg_dev_has_evt_log checks whether this call - * is supported by a device. + * The API call ::mbg_chk_dev_has_evt_log checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_evt_log + * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_get_num_evt_log_entries * @see ::mbg_get_first_evt_log_entry * @see ::mbg_get_next_evt_log_entry @@ -4424,21 +4795,21 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_clr_evt_log( MBG_DEV_HANDLE dh ) ; /** - * @brief Read details about a device's on-board event log buffer. + * @brief Read details about a device's on-board event log buffer * - * The returned ::MBG_NUM_EVT_LOG_ENTRIES structure tells how many event log - * entries which can be saved on the board, and how many entries actually - * have been saved. + * The returned ::MBG_NUM_EVT_LOG_ENTRIES structure tells how many + * event log entries can be saved on the board, and how many entries + * actually have been saved. * - * The API call ::mbg_dev_has_evt_log checks whether this call - * is supported by a device. + * The API call ::mbg_chk_dev_has_evt_log checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::MBG_NUM_EVT_LOG_ENTRIES variable to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_NUM_EVT_LOG_ENTRIES variable to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_evt_log + * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_clr_evt_log * @see ::mbg_get_first_evt_log_entry * @see ::mbg_get_next_evt_log_entry @@ -4446,22 +4817,22 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_num_evt_log_entries( MBG_DEV_HANDLE dh, MBG_NUM_EVT_LOG_ENTRIES *p ) ; /** - * @brief Read the first (oldest) event log entry from a device. + * @brief Read the first (oldest) event log entry from a device * * @note Subsequent reads should be made using ::mbg_get_next_evt_log_entry. * - * The API call ::mbg_dev_has_evt_log checks whether this call - * is supported by a device. + * The API call ::mbg_chk_dev_has_evt_log checks whether + * this call is supported by a device. * * If no (more) event log entry is available on the device then * the returned MBG_EVT_LOG_ENTRY::code is MBG_EVT_ID_NONE. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_evt_log + * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_clr_evt_log * @see ::mbg_get_num_evt_log_entries * @see ::mbg_get_next_evt_log_entry @@ -4469,23 +4840,23 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_first_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) ; /** - * @brief Read the next event log entry from a device. + * @brief Read the next event log entry from a device * * @note The first read should be made using ::mbg_get_first_evt_log_entry * to set the on-board read index to the oldest entry. * - * The API call ::mbg_dev_has_evt_log checks whether this call - * is supported by a device. + * The API call ::mbg_chk_dev_has_evt_log checks whether + * this call is supported by a device. * * If no (more) event log entry is available on the device then * the returned MBG_EVT_LOG_ENTRY::code is MBG_EVT_ID_NONE. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_evt_log + * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_clr_evt_log * @see ::mbg_get_num_evt_log_entries * @see ::mbg_get_first_evt_log_entry @@ -4493,78 +4864,82 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_next_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) ; /** - * @brief Read the current GNSS mode info including current settings. + * @brief Read the current GNSS mode info including current settings * * The ::MBG_GNSS_MODE_INFO structure tells which GNSS systems are supported * by a device, and also includes the settings currently in effect. * - * The API call mbg_dev_is_gnss() can be used to check whether this call - * is supported by a device. See also the notes for mbg_dev_is_gnss(). + * The API call ::mbg_chk_dev_is_gnss can be used to check whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure to be filled up + * See also the notes for ::mbg_chk_dev_is_gnss. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_set_gps_gnss_mode_settings * @see ::mbg_get_gps_all_gnss_sat_info - * @see ::mbg_dev_is_gnss + * @see ::mbg_chk_dev_is_gnss */ _MBG_API_ATTR int _MBG_API mbg_get_gps_gnss_mode_info( MBG_DEV_HANDLE dh, MBG_GNSS_MODE_INFO *p_mi ) ; /** - * @brief Write the GNSS mode configuration to a device. + * @brief Write the GNSS mode configuration to a device * - * The ::MBG_GNSS_MODE_SETTINGS structure determines to configure the - * GNSS settings for a device, i.e. which satellite systems have to be used. + * The ::MBG_GNSS_MODE_SETTINGS structure determines the GNSS settings + * for a device, e.g. which satellite systems have to be used. * - * The function mbg_get_gps_gnss_mode_info() should have been called before + * The function ::mbg_get_gps_gnss_mode_info should have been called before * to determine which GNSS settings are supported by the device. * - * The API call mbg_dev_is_gnss() can be used to check whether these API calls - * are supported by a device. See also the notes for mbg_dev_is_gnss(). + * The API call ::mbg_chk_dev_is_gnss can be used to check whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p_ms Pointer to a ::MBG_GNSS_MODE_SETTINGS structure to be written + * See also the notes for ::mbg_chk_dev_is_gnss. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p_ms Pointer to a ::MBG_GNSS_MODE_SETTINGS structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_gps_gnss_mode_info * @see ::mbg_get_gps_all_gnss_sat_info - * @see ::mbg_dev_is_gnss + * @see ::mbg_chk_dev_is_gnss */ _MBG_API_ATTR int _MBG_API mbg_set_gps_gnss_mode_settings( MBG_DEV_HANDLE dh, const MBG_GNSS_MODE_SETTINGS *p_ms ) ; /** - * @brief Read a ::GNSS_SAT_INFO_IDX array of satellite status information. + * @brief Read a ::GNSS_SAT_INFO_IDX array of satellite status information * * The function ::mbg_get_gps_gnss_mode_info must have been called before, * and the returned ::MBG_GNSS_MODE_INFO structure be passed to this function. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] gsii Pointer to a an array of satellite info structures to be filled up - * @param[in] p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure returned by ::mbg_get_gps_gnss_mode_info + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] gsii Pointer to a an array of satellite info structures to be filled up. + * @param[in] p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure returned by ::mbg_get_gps_gnss_mode_info. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_gps_gnss_mode_info * @see ::mbg_set_gps_gnss_mode_settings - * @see ::mbg_dev_is_gnss + * @see ::mbg_chk_dev_is_gnss */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gnss_sat_info( MBG_DEV_HANDLE dh, GNSS_SAT_INFO_IDX gsii[], const MBG_GNSS_MODE_INFO *p_mi ) ; /** * @brief Read common GPIO configuration limits * - * The API call ::mbg_dev_has_gpio checks whether this call is supported - * by a device. + * The API call ::mbg_chk_dev_has_gpio checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] p A ::MBG_GPIO_CFG_LIMITS structure to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p A ::MBG_GPIO_CFG_LIMITS structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_gpio + * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits * @see ::mbg_get_gps_all_gpio_info * @see ::mbg_set_gps_gpio_settings_idx @@ -4575,16 +4950,16 @@ extern "C" { /** * @brief Get all GPIO settings and capabilities. * - * The API call ::mbg_dev_has_gpio checks whether this call is supported - * by a device. + * The API call ::mbg_chk_dev_has_gpio checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] gii An array of ::MBG_GPIO_STATUS_IDX structures to be filled up - * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] gii An array of ::MBG_GPIO_STATUS_IDX structures to be filled up. + * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_gpio + * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits * @see ::mbg_get_gps_all_gpio_info * @see ::mbg_set_gps_gpio_settings_idx @@ -4598,15 +4973,15 @@ extern "C" { * The ::MBG_GPIO_SETTINGS_IDX structure contains both the ::MBG_GPIO_SETTINGS * and the port index value. * - * The API call ::mbg_dev_has_gpio checks whether this call is supported - * by a device. + * The API call ::mbg_chk_dev_has_gpio checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] p Pointer to a ::MBG_GPIO_SETTINGS_IDX structure to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_GPIO_SETTINGS_IDX structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_gpio + * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits * @see ::mbg_get_gps_all_gpio_info * @see ::mbg_set_gps_gpio_settings_idx @@ -4617,13 +4992,13 @@ extern "C" { /** * @brief Read the status of all GPIO signal ports * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] gsi An array of ::MBG_GPIO_STATUS_IDX structures to be filled up - * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] gsi An array of ::MBG_GPIO_STATUS_IDX structures to be filled up. + * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_gpio + * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits * @see ::mbg_get_gps_all_gpio_info * @see ::mbg_set_gps_gpio_settings_idx @@ -4631,14 +5006,14 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gpio_status( MBG_DEV_HANDLE dh, MBG_GPIO_STATUS_IDX gsi[], const MBG_GPIO_CFG_LIMITS *p_gcl ) ; /** - * @brief + * @brief Read ::XMULTI_REF_INSTANCES * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] *p A ::XMULTI_REF_INSTANCES structure to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p A ::XMULTI_REF_INSTANCES structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_gps_all_xmr_status * @see ::mbg_get_gps_all_xmr_info * @see ::mbg_set_gps_xmr_settings_idx @@ -4649,13 +5024,13 @@ extern "C" { /** * @brief Read the status of all XMR sources * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] xmrsi An array of ::XMULTI_REF_STATUS_IDX structures to be filled up - * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] xmrsi An array of ::XMULTI_REF_STATUS_IDX structures to be filled up. + * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances * @see ::mbg_get_gps_all_xmr_info * @see ::mbg_set_gps_xmr_settings_idx @@ -4666,13 +5041,13 @@ extern "C" { /** * @brief Read all XMR settings and capabilities * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] xmrii An array of ::XMULTI_REF_INFO_IDX structures to be filled up - * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] xmrii An array of ::XMULTI_REF_INFO_IDX structures to be filled up. + * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances * @see ::mbg_get_gps_all_xmr_status * @see ::mbg_set_gps_xmr_settings_idx @@ -4686,15 +5061,15 @@ extern "C" { * The ::XMULTI_REF_SETTINGS_IDX structure contains both the ::XMULTI_REF_SETTINGS * and the index value. * - * The macro ::_pcps_has_ri_xmr or the API call ::mbg_dev_has_xmr - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_xmr checks whether + * this call is supported by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::XMULTI_REF_SETTINGS_IDX structure to be written + * @param[in] p Pointer to a ::XMULTI_REF_SETTINGS_IDX structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances * @see ::mbg_get_gps_all_xmr_status * @see ::mbg_get_gps_all_xmr_info @@ -4705,19 +5080,16 @@ extern "C" { /** * @brief Read the current XMR holdover interval from a device * - * Read a ::SYNTH structure containing the configuration of an optional - * on-board programmable frequency synthesizer. - * - * The macro ::_pcps_has_ri_xmr or the API call ::mbg_dev_has_xmr - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_xmr checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::XMR_HOLDOVER_INTV structure to be filled up - * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::XMR_HOLDOVER_INTV structure to be filled up. + * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances * @see ::mbg_get_gps_all_xmr_status * @see ::mbg_get_gps_all_xmr_info @@ -4726,14 +5098,15 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_xmr_holdover_status( MBG_DEV_HANDLE dh, XMR_HOLDOVER_STATUS *p, const XMULTI_REF_INSTANCES *p_xmri ) ; /** - * @brief Read the CPU affinity of a process. + * @brief Read the CPU affinity of a process * - * This means on which of the available CPUs or CPU cores the process can be executed. + * This means on which of the available CPUs or CPU cores + * a process may be executed. * - * @param pid The process ID. - * @param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. + * @param[in] pid The process ID. + * @param[out] p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. * - * @return ::MBG_SUCCESS or error code returned by the system call. + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_set_process_affinity * @see ::mbg_set_current_process_affinity_to_cpu @@ -4742,242 +5115,254 @@ extern "C" { /** * @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. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * + * This determines on which of the available CPUs + * or CPU cores the process is allowed to be executed. + * + * @param[in] pid The process ID. + * @param[out] p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_process_affinity * @see ::mbg_set_current_process_affinity_to_cpu - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p ) ; /** - * @brief Set the CPU affinity of a process for a single CPU only. - - This means the process may only be executed on that single CPU. - - @param cpu_num The number of the CPU. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * @brief Set the CPU affinity of a process for a single CPU only + * + * This means the process may only be executed on that single CPU. + * + * @param[in] cpu_num The number of the CPU. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_process_affinity * @see ::mbg_set_process_affinity - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_current_process_affinity_to_cpu( int cpu_num ) ; /** * @brief Create a new execution thread for the current process. - - This function is only implemented for targets which support threads. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure to be filled up. - @param fnc The name of the thread function to be started. - @param arg A generic argument passed to the thread function. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * + * This function is only implemented for targets that support threads. + * + * @param[in] p_ti Pointer to a ::MBG_THREAD_INFO structure to be filled up. + * @param[in] fnc The name of the thread function to be started. + * @param[in] arg A generic argument passed to the thread function. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_thread_stop * @see ::mbg_thread_sleep_interruptible * @see ::mbg_thread_set_affinity - */ + */ _MBG_API_ATTR int _MBG_API mbg_thread_create( MBG_THREAD_INFO *p_ti, MBG_THREAD_FNC fnc, void *arg ) ; /** - * @brief Stop a thread which has been created by mbg_thread_create(). - - Wait until the thread has finished and release all resources. - This function is only implemented for targets which support threads. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * @brief Stop a thread which has been created by ::mbg_thread_create. + * + * Wait until the thread has finished and release all resources. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_thread_create * @see ::mbg_thread_sleep_interruptible * @see ::mbg_thread_set_affinity - */ + */ _MBG_API_ATTR int _MBG_API mbg_thread_stop( MBG_THREAD_INFO *p_ti ) ; /** - * @brief Let the current thread sleep for a certain interval. - - The sleep is interrupted if a signal is received indicating - the thread should terminate. - - This function is only implemented for targets which support threads. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. - @param sleep_ms The number of milliseconds to sleep - * @return 0 if the sleep interval has expired normally - 1 if a signal to terminate has been received - <0 if an error has occurred - + * @brief Let the current thread sleep for a certain interval + * + * The sleep is interrupted if a signal is received indicating + * the thread should terminate. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. + * @param[in] sleep_ms The number of milliseconds to sleep + * + * @return MBG_SUCCESS if the sleep interval has expired normally, + * MBG_ERR_INTR if a signal to terminate has been received, + * or one of the other @ref MBG_ERROR_CODES + * * @see ::mbg_thread_create * @see ::mbg_thread_stop * @see ::mbg_thread_set_affinity - */ + */ _MBG_API_ATTR int _MBG_API mbg_thread_sleep_interruptible( MBG_THREAD_INFO *p_ti, ulong sleep_ms ) ; /** - * @brief Set the CPU affinity of a single thread. - - This determines on which of the available CPUs the thread - is allowed to be executed. - - This function is only implemented for targets which support thread affinity. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. - @param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * @brief Set the CPU affinity of a single thread + * + * This determines on which of the available CPUs the thread + * is allowed to be executed. + * + * This function is only implemented for targets that support thread affinity. + * + * @param[in,out] p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. + * @param[in] p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_thread_create * @see ::mbg_thread_stop * @see ::mbg_thread_sleep_interruptible - */ + */ _MBG_API_ATTR int _MBG_API mbg_thread_set_affinity( MBG_THREAD_INFO *p_ti, MBG_CPU_SET *p ) ; /** - * @brief Set up a ::MBG_POLL_THREAD_INFO structure and start a new thread. - - The new thread runs the mbg_xhrt_poll_thread_fnc() function. - - This function is only implemented for targets which support threads. - - @param *p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. - @param dh the handle of the device to be polled. - @param freq_hz The initial cycles frequency, if known, in Hz. - @param sleep_ms the sleep interval for the poll thread function in ms. - If this parameter is 0 then the default sleep interval is used. - + * @brief Set up a ::MBG_POLL_THREAD_INFO structure and start a new thread + * + * The new thread runs a function which periodically reads + * a time stamp / cycles pair from a device. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. + * @param[in] dh the Handle of the device to be polled. + * @param[in] freq_hz The initial cycles frequency, if known, in Hz. + * @param[in] sleep_ms the sleep interval for the poll thread function in ms. + * If this parameter is 0 then the default sleep interval is used. + * * @return ::MBG_SUCCESS on success, - ::MBG_ERR_NOT_SUPP_BY_DEV if the device to poll does not support HR time - else the result of mbg_thread_create() - + * ::MBG_ERR_NOT_SUPP_BY_DEV if the device to poll does not support HR time + * else the result of ::mbg_thread_create. + * * @see ::mbg_xhrt_poll_thread_stop * @see ::mbg_get_xhrt_time_as_pcps_hr_time * @see ::mbg_get_xhrt_time_as_filetime * @see ::mbg_get_xhrt_cycles_frequency - */ + */ _MBG_API_ATTR int _MBG_API mbg_xhrt_poll_thread_create( MBG_POLL_THREAD_INFO *p_pti, MBG_DEV_HANDLE dh, MBG_PC_CYCLES_FREQUENCY freq_hz, int sleep_ms ) ; /** - * @brief Stop a polling thread started by mbg_xhrt_poll_thread_create(). - - This call also releases all associated resources. - - @param *p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. - - * @return the result of mbg_thread_stop() - + * @brief Stop a polling thread started by ::mbg_xhrt_poll_thread_create + * + * This call also releases all associated resources. + * + * @param[in,out] p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. + * + * @return The result of ::mbg_thread_stop. + * * @see ::mbg_xhrt_poll_thread_create * @see ::mbg_get_xhrt_time_as_pcps_hr_time * @see ::mbg_get_xhrt_time_as_filetime * @see ::mbg_get_xhrt_cycles_frequency - */ + */ _MBG_API_ATTR int _MBG_API mbg_xhrt_poll_thread_stop( MBG_POLL_THREAD_INFO *p_pti ) ; /** - * @brief Retrieve an extrapolated time stamp in PCPS_HR_TIME format. - - The time stamp is extrapolated using the system's current cycles counter value - and a time stamp plus associated cycles counter value saved by the polling thread. - See mbg_xhrt_poll_thread_fnc() for details and limitations. - - This function is only implemented for targets which support threads. - - @param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. - @param *p_hrt Pointer to a ::PCPS_HR_TIME structure to be filled up. - - * @return MBG_SUCCESS or another return value from the polling thread's IOCTL call. - + * @brief Retrieve an extrapolated time stamp in ::PCPS_HR_TIME format + * + * The time stamp is extrapolated using the system's current cycles counter value + * and a time stamp plus associated cycles counter value saved by the polling thread. + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. + * @param[out] p_hrt Pointer to a ::PCPS_HR_TIME structure to be filled up. + * + * @return The return code from the API call used by the polling thread + * to read the time from the device, usually ::mbg_get_hr_time_cycles, + * so ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * + * @ingroup mbg_xhrt_poll_group * @see ::mbg_xhrt_poll_thread_create * @see ::mbg_xhrt_poll_thread_stop * @see ::mbg_get_xhrt_time_as_filetime * @see ::mbg_get_xhrt_cycles_frequency - */ + * @see @ref mbg_xhrt_poll_group + */ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_pcps_hr_time( MBG_XHRT_INFO *p, PCPS_HR_TIME *p_hrt ) ; /** - * @brief Retrieve an extrapolated time stamp in FILETIME format. - - The time stamp is extrapolated using the system's current cycles counter value - and a time stamp plus associated cycles counter value saved by the polling thread. - See mbg_xhrt_poll_thread_fnc() for details and limitations. - - Since FILETIME is a Windows specific type this function is only - implemented under Windows. - - @param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. - @param *p_ft Pointer to a FILETIME structure to be filled up. - - * @return MBG_SUCCESS or another return value from the polling thread's IOCTL call. - + * @brief Retrieve an extrapolated time stamp in FILETIME format + * + * The time stamp is extrapolated using the system's current cycles counter value + * and a time stamp plus associated cycles counter value saved by the polling thread. + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * Since FILETIME is a Windows-specific type this function is only + * implemented under Windows. + * + * @param[in,out] p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. + * @param[out] p_ft Pointer to a FILETIME structure to be filled up. + * + * @return The return code from the API call used by the polling thread + * to read the time from the device, usually ::mbg_get_hr_time_cycles, + * so ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * + * @ingroup mbg_xhrt_poll_group * @see ::mbg_xhrt_poll_thread_create * @see ::mbg_xhrt_poll_thread_stop * @see ::mbg_get_xhrt_time_as_pcps_hr_time * @see ::mbg_get_xhrt_cycles_frequency - */ + * @see @ref mbg_xhrt_poll_group + */ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_filetime( MBG_XHRT_INFO *p, FILETIME *p_ft ) ; /** - * @brief Retrieve the frequency of the system's cycles counter. - - The frequency is determined by the device polling thread. - See mbg_xhrt_poll_thread_fnc() for details and limitations. - - This function is only implemented for targets which support threads. - - @param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. - @param *p_freq_hz Pointer to a ::MBG_PC_CYCLES_FREQUENCY variable in which the frequency is returned. - * @return a status code from the polling thread: MBG_SUCCESS or an IOCTL error code. - + * @brief Retrieve the frequency of the system's cycles counter + * + * The frequency is determined by the device polling thread. + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. + * @param[out] p_freq_hz Pointer to a ::MBG_PC_CYCLES_FREQUENCY variable in which the frequency is returned. + * + * @return The return code from the API call used by the polling thread + * to read the time from the device, usually ::mbg_get_hr_time_cycles, + * so ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * + * @ingroup mbg_xhrt_poll_group * @see ::mbg_xhrt_poll_thread_create * @see ::mbg_xhrt_poll_thread_stop * @see ::mbg_get_xhrt_time_as_pcps_hr_time * @see ::mbg_get_xhrt_time_as_filetime - */ + * @see @ref mbg_xhrt_poll_group + */ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_cycles_frequency( MBG_XHRT_INFO *p, MBG_PC_CYCLES_FREQUENCY *p_freq_hz ) ; /** - * @brief Retrieve the default system's cycles counter frequency from the kernel driver. - - This API call can be used on systems which don't provide this information in user space. - - @param dh handle of the device to which the IOCTL call is sent. - @param *p Pointer of a ::MBG_PC_CYCLES_FREQUENCY variable to be filled up. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Retrieve the system's default cycles counter frequency from the kernel driver + * + * This API call can be used on systems which don't provide this information in user space. + * + * @param[in] dh Handle of the device to which the IOCTL call is sent. + * @param[out] p Pointer of a ::MBG_PC_CYCLES_FREQUENCY variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_default_cycles_frequency - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_default_cycles_frequency_from_dev( MBG_DEV_HANDLE dh, MBG_PC_CYCLES_FREQUENCY *p ) ; /** - @brief Retrieve the system's default cycles counter frequency. - - @note This may not be supported on all target platforms, in which case the - returned frequency is 0 and the mbg_get_default_cycles_frequency_from_dev() - call should be used. - - @return the default cycles counter frequency in Hz, or 0 if the value is not available. - + * @brief Retrieve the system's default cycles counter frequency + * + * @note This may not be supported on all target platforms, in which case the + * returned frequency is 0 and the ::mbg_get_default_cycles_frequency_from_dev + * call should be used instead. + * + * @return the default cycles counter frequency in Hz, or 0 if the value is not available. + * * @see ::mbg_get_default_cycles_frequency_from_dev -*/ + */ _MBG_API_ATTR MBG_PC_CYCLES_FREQUENCY _MBG_API mbg_get_default_cycles_frequency( void ) ; /* ----- function prototypes end ----- */ -#ifdef __cplusplus -} -#endif - #if defined( MBG_TGT_WIN32 ) @@ -4993,18 +5378,18 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, NULL ) ) { - DWORD rc = GetLastError(); + DWORD rc = GetLastError(); // FIXME - #if 0 //### TODO - // We can't call mbgsvctl_log_mbgdevio_error() here (for now). - // Is is defined in mbgsvctl.h, and including mbgsvctl.h here, - // or copying the prototype here results in DLL import/export - // mismatch errors. + #if 0 //### TODO + // We can't call mbgsvctl_log_mbgdevio_error() here (for now). + // Is is defined in mbgsvctl.h, and including mbgsvctl.h here, + // or copying the prototype here results in DLL import/export + // mismatch errors. - // do not report a USB device timeout error - if ( rc != MBG_ERR_USB_ACCESS ) - mbgsvctl_log_mbgdevio_error( ioctl_code, rc ); - #endif + // do not report a USB device timeout error + if ( rc != MBG_ERR_USB_ACCESS ) + mbgsvctl_log_mbgdevio_error( ioctl_code, rc ); + #endif return rc; } @@ -5022,8 +5407,25 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, // error number according to negative Meinberg error codes, so we need to return // -errno in case of an error to pass the original negative Meinberg error code. + static __mbg_inline + MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, unsigned long ioctl_code, const void *p ) + { + int rc = ioctl( dh, ioctl_code, (void *) p ); + + if ( rc == -1 ) // error + { + rc = -errno; + #if DEBUG_IOCTL + fprintf( stderr, "IOCTL 0x%08lX error: %s (rc: %i)\n", + (ulong) ioctl_code, mbg_strerror( rc ), rc ); + #endif + } + + return rc; + } + #define _do_mbg_ioctl( _dh, _ioctl, _p, _in_sz, _out_sz ) \ - ( ( ( rc = ioctl( _dh, _ioctl, _p ) ) >= 0 ) ? rc : -errno ) + do_mbg_ioctl( _dh, _ioctl, _p ) #endif @@ -5034,31 +5436,31 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, #if defined( MBG_USE_KERNEL_DRIVER ) // using IOCTL to access device driver -/** - @brief Send a generic IOCTL command to the driver. - - @param dh Valid handle to a Meinberg device - @param info Additional information for the kernel driver depending on - the IOCTL code, i.e. the low level function to be called: <br> - one of the PCPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}<br> - one of the PC_GPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}_GPS<br> - one of the PCPS_GEN_IO_... enumeration codes with IOCTL_PCPS_GENERIC_IO - @param ioctl_code One of the IOCTL_GENERIC_... codes telling the kernel driver - which low level function to use, e.g. normal read or write, - large (GPS) data read or write, or generic I/O. - @param in_p Pointer to an input buffer passed to the driver, can be NULL - @param in_sz Size of the input buffer, can be 0 if no buffer is used - @param out_p Pointer to an output buffer passed to the driver, can be NULL - @param out_sz Size of the output buffer, can be 0 if no buffer is used - - @return ::MBG_SUCCESS or error code returned by device I/O control function. -*/ + /** + * @brief Send a generic IOCTL command to the driver. + * + * @param dh Valid handle to a Meinberg device + * @param info Additional information for the kernel driver depending on + * the IOCTL code, i.e. the low level function to be called: <br> + * one of the PCPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}<br> + * one of the PC_GPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}_GPS<br> + * one of the PCPS_GEN_IO_... enumeration codes with IOCTL_PCPS_GENERIC_IO + * @param ioctl_code One of the IOCTL_GENERIC_... codes telling the kernel driver + * which low level function to use, e.g. normal read or write, + * large (GPS) data read or write, or generic I/O. + * @param in_p Pointer to an input buffer passed to the driver, can be NULL + * @param in_sz Size of the input buffer, can be 0 if no buffer is used + * @param out_p Pointer to an output buffer passed to the driver, can be NULL + * @param out_sz Size of the output buffer, can be 0 if no buffer is used + * + * @return ::MBG_SUCCESS or error code returned by device I/O control function. + */ static __mbg_inline int mbgdevio_do_gen_io( MBG_DEV_HANDLE dh, int info, unsigned int ioctl_code, const void *in_p, int in_sz, void *out_p, int out_sz ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; // Generic IOCTL calls always need to pass some info beside // the I/O buffers down to the driver, which usually is @@ -5108,7 +5510,7 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, #endif - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbgdevio_do_gen_io @@ -5246,10 +5648,11 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, #if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX ) -// ### TODO +// NOTE // For some reason the code below causes an internal compiler error // with Borland C++Builder 5.0 release builds. Since we don't need -// this function in the BC5 projects anyway we exclude it brom build. +// this function in the BC5 projects anyway we simply exclude it +// from build. #if !defined( __BORLANDC__ ) @@ -5275,7 +5678,7 @@ void mbg_chk_tstamp64_leap_sec( uint64_t *tstamp64, PCPS_TIME_STATUS_X *status ) // Decrement interpolated second to avoid automated overflow during the leap second. // Second 59 appears for the second time. - *tstamp64 -= PCPS_HRT_BIN_FRAC_SCALE; + *tstamp64 -= MBG_FRAC32_UNITS_PER_SEC; } else if ( *status & PCPS_LS_ENB ) // Clear bits when leap second expires and 0:00:00 UTC is reached @@ -5324,6 +5727,10 @@ void uint64_to_pcps_time_stamp( PCPS_TIME_STAMP *ts, uint64_t n ) #endif +#ifdef __cplusplus +} +#endif + #if defined( _USING_BYTE_ALIGNMENT ) #pragma pack() // set default alignment #undef _USING_BYTE_ALIGNMENT @@ -5333,6 +5740,7 @@ void uint64_to_pcps_time_stamp( PCPS_TIME_STAMP *ts, uint64_t n ) #undef _ext +#undef _DO_INIT #endif /* _MBGDEVIO_H */ diff --git a/mbglib/common/mbgerror.c b/mbglib/common/mbgerror.c index 60eee81..ffd4bb8 100755 --- a/mbglib/common/mbgerror.c +++ b/mbglib/common/mbgerror.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgerror.c 1.2.1.5 2017/02/22 11:53:24 martin TEST $ + * $Id: mbgerror.c 1.3 2017/07/05 09:20:07 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,17 +10,20 @@ * * ----------------------------------------------------------------------- * $Log: mbgerror.c $ - * Revision 1.2.1.5 2017/02/22 11:53:24 martin - * Removed type cast.which is now obsolete - * due to changed library type. - * Revision 1.2.1.4 2016/12/16 12:40:25Z thomas-b - * Added table entry for posix errors for ENOSPC (MBG_ERR_NO_SPACE) - * Revision 1.2.1.3 2016/09/13 10:24:02 martin - * Fixed some compiler warnings. - * Revision 1.2.1.2 2016/08/16 12:48:30Z gregoire.diehl - * CVI fixes - * Revision 1.2.1.1 2016/08/11 07:58:15 martin - * Fixed a compiler warning. + * Revision 1.3 2017/07/05 09:20:07 martin + * Fixed a bug where POSIX error ENODEV wasn't mapped at all, but + * EXDEV was instead translated erraneously to MBG_ERR_NO_DEV. + * Mapped POSIX error ENOSPC to MBG_ERR_NO_SPACE, and EFAULT + * to MBG_ERR_INV_PARM. + * Mapped Windows WSA error codes WSAEFAULT and WSAEINVAL + * to MBG_ERR_INV_PARM. + * Renamed mbg_ioctl_err() to mbg_cond_err_msg(). + * New function mbg_cond_err_msg_info() which takes an optional + * info string which is printed if the error code to be checked + * is MBG_ERR_NOT_SUPP_BY_DEV. + * Fixed build in Windows kernel mode. + * Fixed syntax error in CVI-specific code. + * Quieted some compiler warnings. * Revision 1.2 2016/08/05 12:25:44Z martin * Added some functions. * Revision 1.1 2014/03/07 12:08:14 martin @@ -89,12 +92,12 @@ static ERRNO_CNV_ENTRY posix_errno_table[] = // { EAGAIN, }, // 11, Try again { ENOMEM, MBG_ERR_NO_MEM }, // 12, Out of memory { EACCES, MBG_ERR_ACCESS }, // 13, Permission denied - // { EFAULT, }, // 14, Bad address + { EFAULT, MBG_ERR_INV_PARM }, // 14, Bad address, e.g. invalid pointer // { ENOTBLK, }, // 15, Block device required { EBUSY, MBG_ERR_BUSY }, // 16, Device or resource busy { EEXIST, MBG_ERR_EXIST }, // 17, File exists - { EXDEV, MBG_ERR_NO_DEV }, // 18, Cross-device link - // { ENODEV, }, // 19, No such device + // { EXDEV, }, // 18, Cross-device link + { ENODEV, MBG_ERR_NO_DEV }, // 19, No such device // { ENOTDIR, }, // 20, Not a directory // { EISDIR, }, // 21, Is a directory { EINVAL, MBG_ERR_INV_PARM }, // 22, Invalid argument @@ -147,8 +150,8 @@ static ERRNO_CNV_ENTRY posix_h_errno_table[] = #if defined( MBG_TGT_CVI ) -static ERRNO_CNV_ENTRY cvi_rs232_error_table[] = -{ +static ERRNO_CNV_ENTRY cvi_rs232_error_table[] = +{ // { kRS_UnknownSysError, }, // Unknown system error. // { kRS_InvalidPortNum, }, // In valid port number. // { kRS_PortNotOpen, }, // Port is not open. @@ -206,11 +209,14 @@ static ERRNO_CNV_ENTRY cvi_rs232_error_table[] = -#if defined( MBG_TGT_WIN32 ) +#if defined( MBG_TGT_WIN32 ) && !defined( MBG_TGT_KERNEL ) static ERRNO_CNV_ENTRY win32_error_table[] = { - // System Error Codes (1300-1699) + // Windows System Error Codes (0-499) + { ERROR_INVALID_PARAMETER, MBG_ERR_INV_PARM }, + + // Windows System Error Codes (1300-1699) { ERROR_ACCESS_DENIED, MBG_ERR_ACCESS }, // { ERROR_PRIVILEGE_NOT_HELD, MBG_ERR_PERM }, // { ERROR_INVALID_HANDLE, MBG_ERR_INV_HANDLE }, // @@ -241,8 +247,8 @@ static ERRNO_CNV_ENTRY win32_wsa_err_table[] = { WSAEINTR, MBG_ERR_INTR }, // 10004L A blocking operation was interrupted by a call to WSACancelBlockingCall. // { WSAEBADF // 10009L The file handle supplied is not valid. // { WSAEACCES // 10013L An attempt was made to access a socket in a way forbidden by its access permissions. - // { WSAEFAULT // 10014L The system detected an invalid pointer address in attempting to use a pointer argument in a call. - // { WSAEINVAL // 10022L An invalid argument was supplied. + { WSAEFAULT, MBG_ERR_INV_PARM }, // 10014L The system detected an invalid pointer address in attempting to use a pointer argument in a call. + { WSAEINVAL, MBG_ERR_INV_PARM }, // 10022L An invalid argument was supplied. // { WSAEMFILE // 10024L Too many open sockets. // { WSAEWOULDBLOCK // 10035L A non-blocking socket operation could not be completed immediately. // { WSAEINPROGRESS // 10036L A blocking operation is currently executing. @@ -359,20 +365,62 @@ const char *mbg_strerror( int mbg_errno ) -// test if ioctl error and print msg if true -//### TODO check if this should be renamed +#if !( defined( MBG_TGT_WIN32 ) && defined( MBG_TGT_KERNEL ) ) // not supported in Windows kernel mode + +/*HDR*/ +/** + * @brief Check if a value is an error code and print an associated error message + * + * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES + * @param[in] what A string indicated what failed + * + * @return true if rc represented an error code, and a message has been printed, else false + */ +bool mbg_cond_err_msg( int rc, const char *what ) +{ + return mbg_cond_err_msg_info( rc, what, NULL ); + +} // mbg_cond_err_msg + + + /*HDR*/ -int mbg_ioctl_err( int rc, const char *descr ) +/** + * @brief Check if a value is an general or a "not supported" error code and print an associated message + * + * If rc contains an error code then an error message is printed, and true is returned. + * + * If the optional parameter string info2 is not NULL then it should contain + * the name of a feature which has been tested before. In this case, if the error + * code is the specific error ::MBG_ERR_NOT_SUPP_BY_DEV then a "not supported" message + * is printed using info2. + * + * If info2 is NULL, or the error code is not ::MBG_ERR_NOT_SUPP_BY_DEV then the standard + * error message is printed anyway. + * + * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES + * @param[in] what A string indicated what failed + * @param[in] info An optional informational string telling what is not supported (may be NULL). + * + * @return true if rc represented an error code, and a message has been printed, else false + */ +bool mbg_cond_err_msg_info( int rc, const char *what, const char *info ) { if ( mbg_rc_is_error( rc ) ) { - fprintf( stderr, "** %s: %s (rc: %i)\n", descr, mbg_strerror( rc ), rc ); - return -1; + if ( info && ( rc == MBG_ERR_NOT_SUPP_BY_DEV ) ) + fprintf( stderr, "This device does not %s.\n", info ); + else + fprintf( stderr, "** %s failed: %s (rc: %i)\n", what, mbg_strerror( rc ), rc ); + + return true; } - return 0; + return false; -} // mbg_ioctl_err +} // mbg_cond_err_msg_info + +#endif // !( defined( MBG_TGT_WIN32 ) && defined( MBG_TGT_KERNEL ) ) @@ -406,7 +454,7 @@ int mbg_cvi_rs232_error_to_mbg( int cvi_rc, const char *info ) -#if defined( MBG_TGT_WIN32 ) +#if defined( MBG_TGT_WIN32 ) && !defined( MBG_TGT_KERNEL ) /*HDR*/ /** @@ -546,11 +594,15 @@ int mbg_get_last_error( const char *info ) { #if defined( MBG_TGT_WIN32 ) - // Under Windows the "last error" code after a non-socket function - // has to be retrieved by calling GetLastError(), whereas - // the "last error" code from POSIX-like socket functions - // is retrieved by calling WSAGetLastError(). - return mbg_win32_last_err_to_mbg( GetLastError(), info ); + #if !defined( MBG_TGT_KERNEL ) + // Under Windows the "last error" code after a non-socket function + // has to be retrieved by calling GetLastError(), whereas + // the "last error" code from POSIX-like socket functions + // is retrieved by calling WSAGetLastError(). + return mbg_win32_last_err_to_mbg( GetLastError(), info ); + #else + return MBG_ERR_GENERIC; + #endif #elif defined( MBG_TGT_POSIX ) @@ -595,11 +647,15 @@ int mbg_get_last_socket_error( const char *info ) #elif defined( MBG_TGT_WIN32 ) - // Under Windows the "last error" code after a socket function - // has to be retrieved by calling WSAGetLastError, whereas - // the "last error" code from non-socket POSIX-like functions - // is stored in errno as usual. - return mbg_win32_wsa_err_to_mbg( WSAGetLastError(), info ); + #if !defined( MBG_TGT_KERNEL ) + // Under Windows the "last error" code after a socket function + // has to be retrieved by calling WSAGetLastError, whereas + // the "last error" code from non-socket POSIX-like functions + // is stored in errno as usual. + return mbg_win32_wsa_err_to_mbg( WSAGetLastError(), info ); + #else + return MBG_ERR_GENERIC; + #endif #elif defined( MBG_TGT_POSIX ) @@ -642,7 +698,11 @@ int mbg_get_gethostbyname_error( const char *info ) #elif defined( MBG_TGT_WIN32 ) - return mbg_win32_wsa_err_to_mbg( WSAGetLastError(), info ); + #if !defined( MBG_TGT_KERNEL ) + return mbg_win32_wsa_err_to_mbg( WSAGetLastError(), info ); + #else + return MBG_ERR_GENERIC; + #endif #elif defined( MBG_TGT_POSIX ) @@ -728,6 +788,6 @@ int mbg_zlib_error_to_mbg( int zlib_error, const char *info, const char *msg ) } // mbg_zlib_error_to_mbg -#endif // defined(USE_MBG_ZLIB) +#endif // defined( USE_MBG_ZLIB ) diff --git a/mbglib/common/mbgerror.h b/mbglib/common/mbgerror.h index 817baac..20a3edc 100755 --- a/mbglib/common/mbgerror.h +++ b/mbglib/common/mbgerror.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgerror.h 1.13 2017/02/28 15:23:14 gregoire TEST $ + * $Id: mbgerror.h 1.15 2017/07/05 09:27:25 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,6 +11,16 @@ * * ----------------------------------------------------------------------- * $Log: mbgerror.h $ + * Revision 1.15 2017/07/05 09:27:25 martin + * New error code MBG_ERR_PARM_FMT. + * Changed message text for MBG_ERR_NO_ENTITY. + * Replaced old _mbg_err_to_os() macro by new inline functions + * mbg_errno_to_os() and mbg_ret_val_to_os(). + * Fixed build under Windows. + * Updated doxygen comments. + * Updated function prototypes. + * Revision 1.14 2017/05/10 15:21:39 martin + * Tiny cleanup. * Revision 1.13 2017/02/28 15:23:14 gregoire * error code MBG_ERR_INV_IDX added * Revision 1.12 2017/01/10 15:54:56 philipp @@ -70,10 +80,23 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + +#if defined( MBG_TGT_WIN32 ) + + #if !defined( STATUS_SUCCESS ) // not in kernel mode + #define STATUS_SUCCESS 0 + #endif + +#endif + + #if !defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_KERNEL ) - //### TODO Surprisingly we need this also for Windows - // in kernel mode. This should be fixed. - #define DWORD uint32_t // just to avoid compiler errors + // A dummy declaration for DWORD to avoid compiler errors. + // Also reqired in Windows kernel mode. + #define DWORD uint32_t #endif @@ -83,6 +106,11 @@ * * Appropriate error strings can be retrieved via the ::mbg_strerror function. * + * @see ::MBG_ERR_NAMES_ENG + * + * @anchor MBG_RETURN_CODES @{ */ + +/* ### TODO * Under Windows, some message strings are provided as resources appended * to the mbgctrl DLL, but the codes specified here have to be translated * to Windows-specific error codes before the appropriate resource string @@ -90,10 +118,7 @@ * of an error code and have it or'ed with 0xE0000000 afterwards, e.g. * ::MBG_ERR_GENERIC (-19) will yield Windows code 0xE0000013. * * See ::_mbg_err_to_os - * - * @see ::MBG_ERR_NAMES_ENG - * - * @anchor MBG_RETURN_CODES @{ */ + */ // NOTE: Some of these codes have to match codes which are defined in pcpsdefs.h // and returned by the firmware of bus-level devices, so the definitions @@ -195,7 +220,7 @@ #define MBG_ERR_EXIST -93 ///< file exists #define MBG_ERR_DATA_SIZE -94 ///< the received data size toesn't match the expected data size -#define MBG_ERR_NO_ENTITY -95 ///< no such entity //### TODO or use MBG_ERR_NO_DEV / MBG_ERR_NOT_FOUND ? +#define MBG_ERR_NO_ENTITY -95 ///< no such file or directory #define MBG_ERR_ALREADY_ALLOC -96 ///< pointer already allocated when trying to allocate memory #define MBG_ERR_HOST_NOT_FOUND -97 ///< host not found #define MBG_ERR_CONN_RESET -98 ///< connection reset by peer @@ -205,6 +230,8 @@ #define MBG_ERR_NOT_CONFIGURED -101 ///< configuration option is not active/configured #define MBG_ERR_INV_IDX -102 ///< invalid index value used +#define MBG_ERR_PARM_FMT -103 ///< parameter string format error + // NOTE: New codes have to be appended to this list, and the sequence of codes must not // be changed. Whenever new codes have been defined, appropriate entries have to be added // to the ::MBG_ERR_NAMES_ENG table initializer below, and the Windows-specific message @@ -291,7 +318,7 @@ { MBG_ERR_INV_TLV_UID, "MBG_ERR_INV_TLV_UID" }, /* ### TODO */ \ { MBG_ERR_EXIST, "File exists" }, \ { MBG_ERR_DATA_SIZE, "Received data size mismatch" }, \ - { MBG_ERR_NO_ENTITY, "No such entity" }, \ + { MBG_ERR_NO_ENTITY, "No such file or directory" }, \ { MBG_ERR_ALREADY_ALLOC, "Memory already allocated" }, \ { MBG_ERR_HOST_NOT_FOUND, "Host not found" }, \ { MBG_ERR_CONN_RESET, "Connection reset by peer" }, \ @@ -299,6 +326,7 @@ { MBG_ERR_NO_SPACE, "Insufficient disk space" }, \ { MBG_ERR_NOT_CONFIGURED, "Configuration is not active and/or configured" }, \ { MBG_ERR_INV_IDX, "Invalid or unsupported index value used"}, \ + { MBG_ERR_PARM_FMT, "Parameter string format error" }, \ { 0, NULL } /* end of table */ \ } @@ -350,30 +378,62 @@ bool mbg_rc_is_success( int rc ) -#if defined( MBG_TGT_WIN32 ) +static __mbg_inline /*HDR*/ +/** + * @brief Convert one of the @ref MBG_ERROR_CODES to an OS-specific format + * + * @param[in] err_no One of the @ref MBG_ERROR_CODES. + * + * @see @ref MBG_ERROR_CODES + */ +int mbg_errno_to_os( int err_no ) +{ + #if defined( MBG_TGT_WIN32 ) - // Windows-specific codes and code conversion + // Windows uses specially encoded numbers + return ( -err_no | 0xE0000000L ); + + #elif defined( MBG_TGT_BSD ) + + return -err_no; + + #else + + return err_no; - #if !defined( STATUS_SUCCESS ) // not in kernel mode - #define STATUS_SUCCESS 0 #endif - #define _mbg_err_to_os( _c ) \ - ( ( (_c) == MBG_SUCCESS ) ? STATUS_SUCCESS : ( abs( _c ) | 0xE0000000 ) ) +} // mbg_errno_to_os -#else - #define _mbg_err_to_os( _c ) (_c ) //### TODO remove this -#endif +static __mbg_inline /*HDR*/ +/** + * @brief Convert one of the @ref MBG_RETURN_CODES to an OS-specific format + * + * @param[in] rc One of the @ref MBG_RETURN_CODES. + * + * @see @ref MBG_RETURN_CODES + */ +int mbg_ret_val_to_os( int rc ) +{ + #if defined( MBG_TGT_WIN32 ) + return mbg_rc_is_error( rc ) ? mbg_errno_to_os( rc ) : STATUS_SUCCESS; + #elif defined( MBG_TGT_BSD ) + + return mbg_rc_is_error( rc ) ? mbg_errno_to_os( rc ) : MBG_SUCCESS; + + #else + + return rc; + + #endif + +} // mbg_ret_val_to_os -/* function prototypes: */ -#ifdef __cplusplus -extern "C" { -#endif /* ----- function prototypes begin ----- */ @@ -389,7 +449,37 @@ extern "C" { */ const char *mbg_strerror( int mbg_errno ) ; - int mbg_ioctl_err( int rc, const char *descr ) ; + /** + * @brief Check if a value is an error code and print an associated error message + * + * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES + * @param[in] what A string indicated what failed + * + * @return true if rc represented an error code, and a message has been printed, else false + */ + bool mbg_cond_err_msg( int rc, const char *what ) ; + + /** + * @brief Check if a value is an general or a "not supported" error code and print an associated message + * + * If rc contains an error code then an error message is printed, and true is returned. + * + * If the optional parameter string info2 is not NULL then it should contain + * the name of a feature which has been tested before. In this case, if the error + * code is the specific error ::MBG_ERR_NOT_SUPP_BY_DEV then a "not supported" message + * is printed using info2. + * + * If info2 is NULL, or the error code is not ::MBG_ERR_NOT_SUPP_BY_DEV then the standard + * error message is printed anyway. + * + * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES + * @param[in] what A string indicated what failed + * @param[in] info An optional informational string telling what is not supported (may be NULL). + * + * @return true if rc represented an error code, and a message has been printed, else false + */ + bool mbg_cond_err_msg_info( int rc, const char *what, const char *info ) ; + /** * @brief Translate an error code from the Labwindows/CVI RS-232 library to one of the @ref MBG_ERROR_CODES * diff --git a/mbglib/common/mbggeo.h b/mbglib/common/mbggeo.h index 57468d0..ff3165d 100755 --- a/mbglib/common/mbggeo.h +++ b/mbglib/common/mbggeo.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbggeo.h 1.13 2017/01/27 08:57:58 martin REL_M $ + * $Id: mbggeo.h 1.14 2017/05/10 15:21:40 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -22,6 +22,8 @@ * * ----------------------------------------------------------------------- * $Log: mbggeo.h $ + * Revision 1.14 2017/05/10 15:21:40 martin + * Tiny cleanup. * Revision 1.13 2017/01/27 08:57:58 martin * Fixed macro syntax. * Revision 1.12 2016/10/31 16:50:56 martin @@ -74,6 +76,10 @@ #define _USING_BYTE_ALIGNMENT #endif +#ifdef __cplusplus +extern "C" { +#endif + /** * @brief Geographic longitude or latitude in [degrees, minutes, seconds] @@ -287,12 +293,6 @@ _ext double sqrt_mue; // sqrt( mue ) -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/mbgioctl.h b/mbglib/common/mbgioctl.h index 56d9355..54732c1 100755 --- a/mbglib/common/mbgioctl.h +++ b/mbglib/common/mbgioctl.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgioctl.h 1.26.1.10 2017/02/22 15:23:45 martin TEST $ + * $Id: mbgioctl.h 1.27 2017/07/05 09:37:18 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,22 +10,11 @@ * * ----------------------------------------------------------------------- * $Log: mbgioctl.h $ - * Revision 1.26.1.10 2017/02/22 15:23:45 martin - * Fixed macro definition syntax to avoid clang compiler warnings. - * Revision 1.26.1.9 2014/10/17 13:28:28 martin - * Revision 1.26.1.8 2014/10/17 11:37:24 martin - * Doxygen changes. - * Revision 1.26.1.7 2014/06/26 09:44:03 martin - * Revision 1.26.1.6 2014/05/23 12:30:51 martin - * Revision 1.26.1.5 2014/05/22 16:16:52 martin - * Revision 1.26.1.4 2014/05/22 14:55:27 martin - * Added IOCTL codes for XMR support. - * Revision 1.26.1.3 2014/04/15 15:39:00 martin - * Support GPIO ports. - * Revision 1.26.1.2 2014/04/11 13:58:10 martin - * Simplified declaration of code/name tables. - * Revision 1.26.1.1 2014/03/05 10:37:58 martin - * Windows.h is now included in mbg_tgt.h. + * Revision 1.27 2017/07/05 09:37:18 martin + * Definitions to support GPIO ports and XMR. + * Support new way to check if specific feature supported. + * Moved some IOCTL-related definitions from pcpsdev.h here. + * Added some doxygen comments. * Revision 1.26 2013/09/26 08:27:04Z martin * Support GNSS API. * Revision 1.25 2012/10/02 18:45:55 martin @@ -143,11 +132,49 @@ /* Other headers to be included */ #include <mbg_tgt.h> +#include <mbgerror.h> #include <mbggeo.h> #include <pcpsdev.h> #include <pci_asic.h> +#if defined( MBG_TGT_LINUX ) + #include <linux/ioctl.h> +#endif + + +#if defined( MBG_TGT_BSD ) + #include <sys/ioccom.h> +#endif + + +#if defined( MBG_TGT_WIN32 ) + + #if !defined( MBG_TGT_KERNEL ) + #include <winioctl.h> + #endif + + #if !defined( MBG_TGT_WIN32_NON_PNP ) + #ifdef _MBGIOCTL + #include <initguid.h> // instance the GUID + #else + #include <guiddef.h> // just define the GUID + #endif + #endif + +#endif + + + +/* Start of header body */ + +// We have to use native alignment here! + +#ifdef __cplusplus +extern "C" { +#endif + + #if defined( MBG_ARCH_X86 ) #define USE_DEBUG_PORT 1 #else @@ -157,8 +184,6 @@ #if defined( MBG_TGT_LINUX ) - #include <linux/ioctl.h> - // a magic number used to generate IOCTL cmd codes #define IOTYPE 'M' @@ -171,8 +196,6 @@ #elif defined( MBG_TGT_BSD ) - #include <sys/ioccom.h> - // Under NetBSD 'Z' marks passthrough IOCTLs, under FreeBSD the code // does not seem to matter, so we use 'Z' anyway. #define IOTYPE 'Z' @@ -189,18 +212,6 @@ #define _MBG_SUPP_VAR_ACC_SIZE 1 #endif - #if !defined( MBG_TGT_KERNEL ) - #include <winioctl.h> - #endif - - #if !defined( MBG_TGT_WIN32_NON_PNP ) - #ifdef _MBGIOCTL - #include <initguid.h> // instance the GUID - #else - #include <guiddef.h> // just define the GUID - #endif - #endif - #ifdef DEFINE_GUID // don't break compiles of drivers that // include this header but don't want the // GUIDs @@ -238,17 +249,96 @@ #endif -#ifdef _MBGIOCTL - #define _ext - #define _DO_INIT + +// The structure below is used by the IOCTL_PCPS_GENERIC_... calls. + +#if defined( MBG_TGT_LINUX ) + #if defined( MBG_ARCH_ARM ) || defined( MBG_ARCH_SPARC ) + #define USE_IOCTL_GENERIC_REQ 0 + #endif +#endif + +#if defined( MBG_TGT_WIN32 ) + // required for 32bit/64 bit compatibility + #define USE_IOCTL_GENERIC_REQ 0 +#endif + +#if !defined( USE_IOCTL_GENERIC_REQ ) + #define USE_IOCTL_GENERIC_REQ 1 +#endif + + +#if USE_IOCTL_GENERIC_REQ + +/** + * @brief A structure used to pass generic IOCTL requests to the kernel driver + * + * @note This does not work properly under Linux/Sparc where the kernel + * may be 64 bit while user space is 32 bit, which leads to different sizes + * for pointers, size_t, etc. + */ +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 - #define _ext extern + +/** + * @brief Control structure used for generic IOCTL requests + * + * Used by the IOCTL_PCPS_GENERIC_... calls. + * + * @note Is slower, but avoids OS-specific problems occurring + * with IOCTL_GENERIC_REQ. + */ +typedef struct +{ + uint32_t info; + uint32_t data_size_in; + uint32_t data_size_out; + +} IOCTL_GENERIC_CTL; + + +/** + * @brief Data buffer used for generic IOCTL requests + * + * Used by the IOCTL_PCPS_GENERIC_... calls. + * + * @note Is slower, but avoids OS-specific problems occurring + * with IOCTL_GENERIC_REQ. + */ +typedef struct +{ + IOCTL_GENERIC_CTL ctl; + uint8_t data[1]; + +} IOCTL_GENERIC_BUFFER; + +#define _MBG_IOG( _t, _n, _s ) _MBG_IO( _t, _n ) + #endif -/* Start of header body */ -// We must use native alignment here! +/** + * @brief Request buffer used to query a device feature + */ +typedef struct +{ + uint32_t feat_req_type; ///< See ::DEV_FEAT_REQ_TYPES + uint32_t feat_num; ///< Number and range depending on ::IOCTL_DEV_FEAT_REQ::feat_req_type value + +} IOCTL_DEV_FEAT_REQ; + /** @@ -481,7 +571,7 @@ #define IOCTL_GET_XMR_HOLDOVER_STATUS _MBG_IOR( IOTYPE, 0xA2, XMR_HOLDOVER_STATUS ) #define IOCTL_GET_ALL_GPIO_STATUS _MBG_IOG( IOTYPE, 0xA3, IOCTL_GENERIC_REQ ) // variable size - +#define IOCTL_CHK_DEV_FEAT _MBG_IOW( IOTYPE, 0xA4, IOCTL_DEV_FEAT_REQ ) // The codes below are subject to changes without notice. They may be supported // by some kernel drivers, but usage is restricted to Meinberg software development. @@ -661,6 +751,7 @@ _mbg_cn_table_entry( IOCTL_GET_ALL_XMR_STATUS ), \ _mbg_cn_table_entry( IOCTL_GET_XMR_HOLDOVER_STATUS ), \ _mbg_cn_table_entry( IOCTL_GET_ALL_GPIO_STATUS ), \ + _mbg_cn_table_entry( IOCTL_CHK_DEV_FEAT ), \ \ _mbg_cn_table_entry( IOCTL_MBG_DBG_GET_PORT_ADDR ), \ _mbg_cn_table_entry( IOCTL_MBG_DBG_SET_PORT_ADDR ), \ @@ -822,6 +913,7 @@ int ioctl_get_required_privilege( ulong ioctl_code ) case IOCTL_DEV_HAS_EVT_LOG: case IOCTL_DEV_HAS_GPIO: case IOCTL_DEV_HAS_XMR: + case IOCTL_CHK_DEV_FEAT: return MBG_REQ_PRIVL_NONE; // The next codes are somewhat special since they change something @@ -941,18 +1033,6 @@ int ioctl_get_required_privilege( ulong ioctl_code ) -/* End of header body */ - -#undef _ext -#undef _DO_INIT - - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ @@ -967,4 +1047,9 @@ extern "C" { #endif +/* End of header body */ + +#undef _ext +#undef _DO_INIT + #endif /* _MBGIOCTL_H */ diff --git a/mbglib/common/mbgklist.h b/mbglib/common/mbgklist.h index 19f22a3..01a3f21 100755 --- a/mbglib/common/mbgklist.h +++ b/mbglib/common/mbgklist.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgklist.h 1.2.1.4 2017/01/12 15:09:45 philipp TEST $ + * $Id: mbgklist.h 1.3 2017/07/05 09:52:39 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,13 +10,11 @@ * * ----------------------------------------------------------------------- * $Log: mbgklist.h $ - * Revision 1.2.1.4 2017/01/12 15:09:45 philipp - * Added more safe loop macros - * Revision 1.2.1.3 2017/01/12 12:21:22 philipp - * Added safe loop macros - * Revision 1.2.1.2 2016/08/11 14:13:22 martin - * Revision 1.2.1.1 2016/08/10 14:32:13Z martin - * *** empty log message *** + * Revision 1.3 2017/07/05 09:52:39 martin + * Safe loop macros added by philipp. + * Check if 'typeof' is supported based on the type of compiler. + * Reformatted code to conform to standard header file format. + * Updated function prototypes. * Revision 1.2 2015/10/06 07:08:45 philipp * Added functions to loop containers of list entries * Revision 1.1 2015/09/09 10:42:27 martin @@ -121,8 +119,6 @@ struct mbg_klist_head -/* function prototypes: */ - static __mbg_inline void mbg_klist_init( struct mbg_klist_head *head ) { @@ -290,6 +286,24 @@ void mbg_klist_append_list_init( struct mbg_klist_head *head, struct mbg_klist_h /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ + /** + * @brief Sort a list + * + * @param[in] priv Private data, opaque to ::mbg_klist_sort, passed to @p cmp + * @param[in] head The list to sort + * @param[in] cmp The elements comparison function + * + * This function implements "merge sort", which has O(nlog(n)) + * complexity. + * + * The comparison function @p cmp must return a negative value if a + * should sort before b, and a positive value if a should sort after + * b. If a and b are equivalent, and their original relative + * ordering is to be preserved, cmp must return 0. + */ + void mbg_klist_sort( void *priv, struct mbg_klist_head *head, int (*cmp)( void *priv, struct mbg_klist_head *a, struct mbg_klist_head *b ) ) ; + + /* ----- function prototypes end ----- */ #ifdef __cplusplus diff --git a/mbglib/common/mbgmktm.c b/mbglib/common/mbgmktm.c index b8ada79..d6990c1 100755 --- a/mbglib/common/mbgmktm.c +++ b/mbglib/common/mbgmktm.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgmktm.c 1.1.1.3 2014/10/20 14:35:38 martin TEST $ + * $Id: mbgmktm.c 1.2 2017/07/05 10:00:29 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,10 +10,11 @@ * * ----------------------------------------------------------------------- * $Log: mbgmktm.c $ - * Revision 1.1.1.3 2014/10/20 14:35:38 martin + * Revision 1.2 2017/07/05 10:00:29 martin + * Let mbg_mktime() fail if year is out of a range which depends on + * the size of the 'time_t' type provided by the build environment. * Allow 0 as valid return value for mbg_mktime(). - * Revision 1.1.1.2 2014/10/14 13:52:28Z martin - * Revision 1.1.1.1 2014/10/14 08:59:02 martin + * Added some doxygen comments. * Revision 1.1 2006/08/22 08:57:15 martin * Former function totalsec() moved here from pcpsmktm.c. * diff --git a/mbglib/common/mbgmktm.h b/mbglib/common/mbgmktm.h index ab0d40e..d7a5473 100755 --- a/mbglib/common/mbgmktm.h +++ b/mbglib/common/mbgmktm.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgmktm.h 1.1.1.1 2014/10/14 13:53:50 martin TEST $ + * $Id: mbgmktm.h 1.2 2017/07/05 10:02:42 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: mbgmktm.h $ - * Revision 1.1.1.1 2014/10/14 13:53:50 martin + * Revision 1.2 2017/07/05 10:02:42 martin + * Include time.h. * Updated function prototypes. * Revision 1.1 2006/08/22 08:57:15 martin * Former function totalsec() moved here from pcpsmktm.c. @@ -35,9 +36,6 @@ /* Start of header body */ - -/* function prototypes: */ - #ifdef __cplusplus extern "C" { #endif diff --git a/mbglib/common/mbgmutex.h b/mbglib/common/mbgmutex.h index b8e1ae8..50d7938 100755 --- a/mbglib/common/mbgmutex.h +++ b/mbglib/common/mbgmutex.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgmutex.h 1.3.1.2 2014/03/04 12:08:12 martin TEST $ + * $Id: mbgmutex.h 1.4 2017/07/05 10:05:02 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,9 +11,9 @@ * * ----------------------------------------------------------------------- * $Log: mbgmutex.h $ - * Revision 1.3.1.2 2014/03/04 12:08:12 martin - * Revision 1.3.1.1 2014/01/08 17:20:57Z martin - * MBG_TGT_POSIX + * Revision 1.4 2017/07/05 10:05:02 martin + * windows.h is now included by mbg_tgt.h. + * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. * Revision 1.3 2013/04/11 13:46:58 martin * Use non-specific spinlock function under Windows. * Revision 1.2 2012/03/08 12:19:01Z martin @@ -45,6 +45,10 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + #if defined( MBG_TGT_KERNEL ) // definitions used in kernel space #if defined( MBG_TGT_WIN32 ) // Windows kernel space @@ -234,13 +238,6 @@ #endif - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/mbgpccyc.h b/mbglib/common/mbgpccyc.h index 584348a..cc9854a 100755 --- a/mbglib/common/mbgpccyc.h +++ b/mbglib/common/mbgpccyc.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgpccyc.h 1.6 2016/08/09 16:01:10 martin REL_M $ + * $Id: mbgpccyc.h 1.7 2017/05/10 15:21:41 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: mbgpccyc.h $ + * Revision 1.7 2017/05/10 15:21:41 martin + * Tiny cleanup. * Revision 1.6 2016/08/09 16:01:10 martin * Syntax fix. * Revision 1.5 2016/02/17 16:04:18 martin @@ -70,6 +72,10 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + /** * @brief Generic types to hold PC cycle counter values. * @@ -287,12 +293,6 @@ MBG_PC_CYCLES mbg_delta_pc_cycles( const MBG_PC_CYCLES *p1, const MBG_PC_CYCLES -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/mbgsystm.c b/mbglib/common/mbgsystm.c index 4095faf..7fc4155 100755 --- a/mbglib/common/mbgsystm.c +++ b/mbglib/common/mbgsystm.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgsystm.c 1.1.1.2 2016/08/10 12:27:11 martin TEST $ + * $Id: mbgsystm.c 1.2 2017/07/05 10:06:36 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,10 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: mbgsystm.c $ - * Revision 1.1.1.2 2016/08/10 12:27:11 martin - * *** empty log message *** - * Revision 1.1.1.1 2016/08/09 16:04:21 martin - * Made mbg_delta_sys_time_ms() an inline function. + * Revision 1.2 2017/07/05 10:06:36 martin + * Made mbg_delta_sys_time_ms() an inline function, + * so this file is now effectively empty. * Revision 1.1 2015/09/15 13:21:00 martin * Initial revision. * Moved existing code from different modules here. diff --git a/mbglib/common/mbgsystm.h b/mbglib/common/mbgsystm.h index 5b2ff67..79ea5e6 100755 --- a/mbglib/common/mbgsystm.h +++ b/mbglib/common/mbgsystm.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgsystm.h 1.1.1.9.1.5 2017/02/17 11:49:19 martin TEST $ + * $Id: mbgsystm.h 1.2 2017/07/04 12:26:57 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,33 +11,11 @@ * * ----------------------------------------------------------------------- * $Log: mbgsystm.h $ - * Revision 1.1.1.9.1.5 2017/02/17 11:49:19 martin - * Fixed control of inclusion of headers. - * Revision 1.1.1.9.1.4 2017/02/09 14:42:51 martin - * *** empty log message *** - * Revision 1.1.1.9.1.3 2017/02/09 11:03:29 martin - * Include ktime.h only for newer kernels. - * Revision 1.1.1.9.1.2 2016/09/08 09:54:04 martin - * Include mbg_win32.h for Windows kernel mode only. - * Revision 1.1.1.9.1.1 2016/08/22 15:05:11 martin - * Don't use mbg_win32.h? - * Revision 1.1.1.9 2016/08/10 12:28:36Z martin + * Revision 1.2 2017/07/04 12:26:57 martin + * More detailed control of inclusion of other headers. + * Made mbg_delta_sys_time_ms() as inline function here. * Updated function prototypes. - * Revision 1.1.1.8 2016/08/10 07:11:15 martin - * *** empty log message *** - * Revision 1.1.1.7 2016/08/09 16:04:48 martin - * Made mbg_delta_sys_time_ms() an inline function. * Cleanup. - * Revision 1.1.1.6 2015/11/04 09:33:40 martin - * Revision 1.1.1.5 2015/10/22 14:29:04Z martin - * *** empty log message *** - * Revision 1.1.1.4 2015/09/18 14:53:46 martin - * Fixes for FreeBSD. - * Revision 1.1.1.3 2015/09/18 13:59:29 martin - * *** empty log message *** - * Revision 1.1.1.2 2015/09/15 16:12:15 martin - * Revision 1.1.1.1 2015/09/15 13:52:32Z martin - * Fixed build error under DOS. * Revision 1.1 2015/09/15 13:21:00Z martin * Initial revision. * Moved existing code from different modules here. @@ -485,9 +463,6 @@ void mbg_sleep_sec( long sec ) -/* function prototypes: */ - - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/mbgtime.h b/mbglib/common/mbgtime.h index 2c5c50e..847cb88 100755 --- a/mbglib/common/mbgtime.h +++ b/mbglib/common/mbgtime.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgtime.h 1.23.1.3 2017/03/17 11:33:05 martin TEST $ + * $Id: mbgtime.h 1.24 2017/07/04 14:02:25 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,12 +10,17 @@ * * ----------------------------------------------------------------------- * $Log: mbgtime.h $ - * Revision 1.23.1.3 2017/03/17 11:33:05 martin - * *** empty log message *** - * Revision 1.23.1.2 2017/03/17 10:36:41 martin - * *** empty log message *** - * Revision 1.23.1.1 2017/03/16 15:24:46 martin - * Updated preliminary function prototypes. + * Revision 1.24 2017/07/04 14:02:25 martin + * Made definitions of some constants signed to avoid + * signed/unsigned compiler warnings. + * Moved some macros and inline functions for fraction + * conversion here. They are excluded from build in kernel + * mode, though, since some kernels don't support this properly. + * Moved some NANO_TIME- and NANO_TIME_64-related inline + * functions to new module nanotime.c. + * Renamed PCPS_HRT_BIN_FRAC_SCALE to MBG_FRAC32_UNITS_PER_SEC. + * Updated function prototypes. + * Doxygen stuff. * Revision 1.23 2017/03/16 12:26:13 martin * Updated function prototypes. * Revision 1.22 2017/01/25 13:10:55 gregoire.diehl @@ -232,14 +237,14 @@ typedef struct #define MSEC_PER_HOUR ( MSEC_PER_SEC * SECS_PER_HOUR ) #define MSEC_PER_DAY ( MSEC_PER_SEC * SECS_PER_DAY ) -#define NSECS_PER_SEC 1000000000UL +#define NSECS_PER_SEC 1000000000L #if !defined( HNS_PER_SEC ) - #define HNS_PER_SEC 10000000UL + #define HNS_PER_SEC 10000000L #endif #if !defined( HNS_PER_MS ) - #define HNS_PER_MS 10000UL + #define HNS_PER_MS 10000L #endif @@ -340,6 +345,171 @@ _ext DAYS_OF_MONTH_TABLE days_of_month +#if !defined( MBG_TGT_KERNEL ) + +/** + * @brief Data type used for intermediate results on 32 bit multiplications + * + * We need 64 bits for intermediate integer results to avoid a range overflow + * from 32 x 32 bit multiplications. On systems which don't support 64 bit types + * we use the "double" type as a workaround. + */ +#if defined( MBG_TGT_MISSING_64_BIT_TYPES ) + #define MBG_FRAC32_CONVERSION_TYPE double +#else + #define MBG_FRAC32_CONVERSION_TYPE int64_t +#endif + +/** + * @brief Constant used to convert e.g. ::PCPS_TIME_STAMP::frac values + * + * Max value of ::PCPS_TIME_STAMP::frac + 1, used for scaling + */ +#define MBG_FRAC32_UNITS_PER_SEC ( (MBG_FRAC32_CONVERSION_TYPE) 4294967296.0 ) // == 0x100000000 + + + +/** + * @brief Convert a 16 bit binary fraction to a scaled decimal + * + * @param[in] bin The binary fraction + * @param[in] scale The scale factor + * + * @return The calculated number + * + * @see ::dec_frac_to_bin_frac_16 + * @see ::dec_frac_to_bin_frac_32 + * @see ::bin_frac_32_to_dec_frac + * @see ::frac_sec_from_bin + */ +static __mbg_inline +uint32_t bin_frac_16_to_dec_frac( uint16_t bin, uint32_t scale ) +{ + return (uint32_t) ( (MBG_FRAC32_CONVERSION_TYPE) bin * scale + / 0x10000UL ); + +} // bin_frac_16_to_dec_frac + + + +/** + * @brief Convert a 32 bit binary fraction to a scaled decimal + * + * @param[in] bin The binary fraction + * @param[in] scale The scale factor + * + * @return The calculated number + * + * @see ::dec_frac_to_bin_frac_32 + * @see ::dec_frac_to_bin_frac_16 + * @see ::bin_frac_16_to_dec_frac + */ +static __mbg_inline +uint32_t bin_frac_32_to_dec_frac( uint32_t bin, uint32_t scale ) +{ + return (uint32_t) ( (MBG_FRAC32_CONVERSION_TYPE) bin * scale + / MBG_FRAC32_UNITS_PER_SEC ); + +} // bin_frac_32_to_dec_frac + + + +#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + +// On targets which don't provide 64 bit data types +// MBG_FRAC32_CONVERSION_TYPE is defined as double, +// in which case the ">> 1" operation in the 2 functions +// below yields an "invalid use of floating point" error. +// This could probably be fixed by a different way of +// casting, at least for a partial expression. + +static __mbg_inline +uint16_t dec_frac_to_bin_frac_16( uint32_t dec, uint32_t scale ) +{ + return (uint16_t) ( ( ( (MBG_FRAC32_CONVERSION_TYPE) dec * 0x20000 / scale ) + 1 ) >> 1 ); + +} // dec_frac_to_bin_frac_16 + + +static __mbg_inline +uint32_t dec_frac_to_bin_frac_32( uint32_t dec, uint32_t scale ) +{ + return (uint32_t) ( ( ( (MBG_FRAC32_CONVERSION_TYPE) dec * MBG_FRAC32_UNITS_PER_SEC * 2 / scale ) + 1 ) >> 1 ); + +} // dec_frac_to_bin_frac_32 + +#endif // !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + + + +#define bin_frac_32_to_msec( _bin ) bin_frac_32_to_dec_frac( (_bin), 1000L ) +#define bin_frac_32_to_usec( _bin ) bin_frac_32_to_dec_frac( (_bin), 1000000L ) +#define bin_frac_32_to_nsec( _bin ) bin_frac_32_to_dec_frac( (_bin), 1000000000L ) +#define bin_frac_16_to_msec( _bin ) bin_frac_16_to_dec_frac( (_bin), 1000L ) +#define bin_frac_16_to_usec( _bin ) bin_frac_16_to_dec_frac( (_bin), 1000000L ) +#define bin_frac_16_to_nsec( _bin ) bin_frac_16_to_dec_frac( (_bin), 1000000000L ) + + +#define msec_to_bin_frac_32( _msec ) dec_frac_to_bin_frac_32( (_msec), 1000L ) +#define usec_to_bin_frac_32( _usec ) dec_frac_to_bin_frac_32( (_usec), 1000000L ) +#define nsec_to_bin_frac_32( _nsec ) dec_frac_to_bin_frac_32( (_nsec), 1000000000L ) +#define msec_to_bin_frac_16( _msec ) dec_frac_to_bin_frac_16( (_msec), 1000L ) +#define usec_to_bin_frac_16( _usec ) dec_frac_to_bin_frac_16( (_usec), 1000000L ) +#define nsec_to_bin_frac_16( _nsec ) dec_frac_to_bin_frac_16( (_nsec), 1000000000L ) + + + +/** + * @brief Convert a binary fraction to a scaled decimal + * + * Convert a binary fraction (e.g. of a second, as in ::PCPS_TIME_STAMP::frac) + * to a decimal fraction, using a specified scale factor. + * + * @deprecated This function is deprecated, use ::bin_frac_32_to_dec_frac preferably. + * + * @param[in] b The binary fraction + * @param[in] scale The scale factor + * + * @return The calculated number + * + * @see ::bin_frac_32_to_dec_frac + */ +static __mbg_inline +uint32_t _DEPRECATED_BY( "bin_frac_32_to_dec_frac" ) frac_sec_from_bin( uint32_t b, uint32_t scale ) +{ + return bin_frac_32_to_dec_frac( b, scale ); + +} // frac_sec_from_bin + + + +/** + * @brief Convert a binary fraction to "double" fractions + * + * Convert a binary fraction (e.g. of a second, as in ::PCPS_TIME_STAMP::frac) + * to a "double" with the units of seconds.<br> + * E.g. a 0xFFFFFFFF fraction yields 0.9999999999.... + * + * @note Excluded from build for kernel drivers which usually + * don't support floating point operations. + * + * @param[in] b The binary fraction + * + * @return The calculated fraction + * + * @see ::MBG_FRAC32_UNITS_PER_SEC + */ +static __mbg_inline +double dfrac_sec_from_bin( uint32_t b ) +{ + return (double) b / (double) MBG_FRAC32_UNITS_PER_SEC; + +} // dfrac_sec_from_bin + +#endif // !defined( MBG_TGT_KERNEL ) + + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ @@ -383,11 +553,9 @@ _ext DAYS_OF_MONTH_TABLE days_of_month int err_tm( const TM_GPS *tm ) ; /** - * @brief Set the time in a ::TM_GPS structure to 00:00:00 - * - * FIXME what about the frac and UTC offset fields? + * @brief Set the time in a ::TM_GPS structure to 00:00:00.000 * - * @param[in] tm The date/time structure to be set + * @param[in,out] tm The date/time structure to be set * * @return Pointer to the ::TM_GPS structure that has been passed */ @@ -463,15 +631,12 @@ _ext DAYS_OF_MONTH_TABLE days_of_month int day_of_week( int day, int month, int year ) ; /** - * @brief FIXME Compute yearday-of-week from a given date + * @brief Update a year number by a number of days, accounting for leap years * - * @todo Specify range of returned day-of-week - * - * @param[in] day The day-of-month - * @param[in] month The month - * @param[in] year The full year number + * @param[in] day_num The number of days to evaluate + * @param[in] year The year number to start with * - * @return The computed day-of-week + * @return The computed year number */ int days_to_years( long *day_num, int year ) ; @@ -489,96 +654,6 @@ _ext DAYS_OF_MONTH_TABLE days_of_month long n_days( ushort mday, ushort month, ushort year ) ; /** - * @brief Convert a ::NANO_TIME time to double - * - * @param[in] p Address of a ::NANO_TIME structure to be converted - * - * @return The computed number of seconds with fractions, as double - * - * @see ::double_to_nano_time - */ - double nano_time_to_double( const NANO_TIME *p ) ; - - /** - * @brief Setup a ::NANO_TIME structure from a time provided as double - * - * @param[out] p Address of a ::NANO_TIME structure to be set up - * @param[in] d The time to be converted, in seconds with fractions, as double - * - * @see ::nano_time_to_double - */ - void double_to_nano_time( NANO_TIME *p, double d ) ; - - /** - * @brief Convert a ::NANO_TIME_64 time to double - * - * @param[in] p Address of a ::NANO_TIME_64 structure to be converted - * - * @return The computed number of seconds with fractions, as double - * - * @see ::double_to_nano_time_64 - */ - double nano_time_64_to_double( const NANO_TIME_64 *p ) ; - - /** - * @brief Setup a ::NANO_TIME_64 structure from a time as double - * - * @param[out] p Address of a ::NANO_TIME_64 structure to be set up - * @param[in] d The time to be converted, in seconds with fractions, as double - * - * @see ::nano_time_64_to_double - */ - void double_to_nano_time_64( NANO_TIME_64 *p, double d ) ; - - /** - * @brief Set up a ::NANO_TIME_64 structure from a string with a time in seconds and fractions - * - * @param[in] s A string with a time in seconds, with fractions separated by decimal point - * @param[out] p Address of a ::NANO_TIME_64 structure to be set up - */ - void str_s_to_nano_time_64( const char *s, NANO_TIME_64 *p ) ; - - /** - * @brief Set up a ::NANO_TIME_64 structure from a string with a time in milliseconds and fractions - * - * @param[in] s A string with a time in milliseconds, with fractions separated by decimal point - * @param[out] p Address of a ::NANO_TIME_64 structure to be set up - */ - void str_ms_to_nano_time_64( const char *s, NANO_TIME_64 *p ) ; - - /** - * @brief Convert a ::NTP_TSTAMP structure to a ::NANO_TIME_64 structure - * - * @param[in] p_nts The ::NTP_TSTAMP structure to be converted - * @param[out] p_nt64 The ::NANO_TIME_64 structure to be filled up - */ - void ntp_tstamp_to_nanotime_64( const NTP_TSTAMP *p_nts, NANO_TIME_64 *p_nt64 ) ; - - /** - * @brief Set up a ::NTP_TSTAMP structure from a hex string with a time in seconds and binary fractions - * - * @param[in] s A string with a time in seconds since epoch 1900-01-01, - * with binary fractions separated by decimal point, - * e.g. 'dc763e43.73bd5a8f' as printed by the ntpq utility - * @param[out] p Address of a ::NANO_TIME_64 structure to be set up - * - * @see ::str_ntp_hex_to_nano_time_64 - */ - void str_ntp_hex_to_ntp_tstamp( const char *s, NTP_TSTAMP *p ) ; - - /** - * @brief Set up a ::NANO_TIME_64 structure from a hex string with a time in seconds and binary fractions - * - * @param[in] s A string with a time in seconds since epoch 1900-01-01, - * with binary fractions separated by decimal point, - * e.g. 'dc763e43.73bd5a8f' as printed by the ntpq utility - * @param[out] p Address of a ::NANO_TIME_64 structure to be set up - * - * @see ::str_ntp_hex_to_ntp_tstamp - */ - void str_ntp_hex_to_nano_time_64( const char *s, NANO_TIME_64 *p ) ; - - /** * @brief Print time with hours, minutes, seconds to a string * * @param[out] s Address of a string buffer to be filled @@ -592,7 +667,7 @@ _ext DAYS_OF_MONTH_TABLE days_of_month * @param[out] s Address of a string buffer to be filled * @param[in] tm Address of a ::TM_GPS structure providing date and time */ - int sprint_short_time( char *s, TM_GPS *time ) ; + int sprint_short_time( char *s, const TM_GPS *tm ) ; /** * @brief Print date to a string diff --git a/mbglib/common/mbgutil.c b/mbglib/common/mbgutil.c index d3cb946..e588485 100755 --- a/mbglib/common/mbgutil.c +++ b/mbglib/common/mbgutil.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgutil.c 1.6.1.18 2016/07/22 09:57:11 martin TEST $ + * $Id: mbgutil.c 1.7 2017/07/05 16:40:35 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,30 +10,13 @@ * * ----------------------------------------------------------------------- * $Log: mbgutil.c $ - * Revision 1.6.1.18 2016/07/22 09:57:11 martin - * Quieted some compiler warninges. - * Revision 1.6.1.17 2016/07/15 14:09:48 martin + * Revision 1.7 2017/07/05 16:40:35 martin * Use functions from new module timeutil. - * Revision 1.6.1.16 2016/04/26 09:23:36 martin - * Revision 1.6.1.15 2016/03/16 11:46:34Z martin - * *** empty log message *** - * Revision 1.6.1.14 2015/12/01 11:36:25 martin - * *** empty log message *** - * Revision 1.6.1.13 2015/11/24 15:44:55 martin - * Revision 1.6.1.12 2015/11/20 16:30:41Z martin - * Revision 1.6.1.11 2015/11/02 10:12:28Z martin - * *** empty log message *** - * Revision 1.6.1.10 2015/10/30 11:36:54 martin - * Revision 1.6.1.9 2015/09/08 10:37:02Z martin - * Revision 1.6.1.8 2015/08/27 16:17:27Z martin * Use safe string functions from str_util.c. - * Revision 1.6.1.7 2014/05/27 11:32:47 martin - * Revision 1.6.1.6 2014/05/27 11:26:24 martin - * Revision 1.6.1.5 2014/03/13 16:04:12 martin - * Revision 1.6.1.4 2014/03/13 15:45:36 martin - * Revision 1.6.1.3 2014/03/13 14:31:52Z martin - * Revision 1.6.1.2 2013/10/23 10:40:53Z martin - * Revision 1.6.1.1 2013/10/22 10:05:55 martin + * Quieted some compiler warninges. + * Account for frac_sec_from_bin() obsoleted by bin_frac_32_to_dec_frac(). + * Account for renamed library symbols. + * Added doxygen comments. * Revision 1.6 2012/10/15 13:12:17 martin * Fixed build under DOS. * Fixed format/type mismatch when printing UTC offset. @@ -93,20 +76,6 @@ static const char str_inv_cnv[] = "(invalid conversion)"; -// The size_t type can eventually be larger than an int type. -// However, some snprintf-like functions expect a size_t value -// to specify the buffer size, but just return an int value. -// So we take care that at least the return value is limited -// to MAXINT. -#if defined( MBG_TGT_WIN32 ) - #define _int_from_size_t( _n ) \ - ( ( (_n) > INT_MAX ) ? INT_MAX : (int) (_n) ) -#else - #define _int_from_size_t( _n ) (_n) -#endif - - - /*HDR*/ /** * @brief Get the DLL/shared library's version code @@ -125,7 +94,7 @@ _MBG_API_ATTR int _MBG_API mbgutil_get_version( void ) /** * @brief Check the DLL/shared library's compatibility * - * @param header_version Version code defined in the header file when the application is built + * @param[in] header_version Version code defined in the header file when the application is built * * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE */ @@ -144,12 +113,13 @@ _MBG_API_ATTR int _MBG_API mbgutil_check_version( int header_version ) /** * @brief A portable, safe implementation of snprintf() * + * The output string buffer is in any case properly terminated by 0. * For a detailed description see ::vsnprintf_safe * - * @param s pointer to the output buffer - * @param max_len size of the output buffer - * @param fmt format string according to subsequent parameters - * @param ... variable argument list according to the format string + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] fmt Format string according to subsequent parameters + * @param[in] ... Variable argument list according to the format string * * @return the number of characters written to the output buffer, except the terminating 0 * @@ -180,9 +150,21 @@ _MBG_API mbg_snprintf( char *s, size_t max_len, const char * fmt, ... ) /*HDR*/ +/** + * @brief A portable, safe implementation of strncpy() + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the destination string buffer + * @param[in] max_len Size of the destination string buffer + * @param[in] src Pointer to the source string buffer + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_strncpy( char *s, size_t max_len, const char *src ) { size_t n = sn_cpy_str_safe( s, max_len, src ); + return _int_from_size_t( n ); } // mbg_strncpy @@ -193,12 +175,12 @@ _MBG_API_ATTR int _MBG_API mbg_strncpy( char *s, size_t max_len, const char *src /** * @brief Write a character multiple times to a string buffer * - * Append a terminating 0 to the buffer. + * The output string buffer is in any case properly terminated by 0. * - * @param s pointer to the output buffer - * @param max_len size of the output buffer - * @param c the character to write to the output buffer - * @param n the number of characters to write to the output buffer + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] c The character to write to the output buffer + * @param[in] n The number of characters to write to the output buffer * * @return the number of characters written to the output buffer, except the terminating 0 */ @@ -228,10 +210,23 @@ _MBG_API_ATTR int _MBG_API mbg_strchar( char *s, size_t max_len, char c, size_t /*HDR*/ +/** + * @brief Write a short date string "dd.mm." to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] mday Day-of-month number, 1..31 + * @param[in] month Month number, 1..12 + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_date_short( char *s, int max_len, int mday, int month ) { size_t n = snprintf_safe( s, max_len, "%02u.%02u.", mday, month ); + return _int_from_size_t( n ); } // mbg_str_date_short @@ -239,6 +234,19 @@ _MBG_API_ATTR int _MBG_API mbg_str_date_short( char *s, int max_len, /*HDR*/ +/** + * @brief Write a date string "dd.mm.yyyy" to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] mday Day-of-month number, 1..31 + * @param[in] month Month number, 1..12 + * @param[in] year Year number + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_date( char *s, int max_len, int mday, int month, int year ) { @@ -256,10 +264,23 @@ _MBG_API_ATTR int _MBG_API mbg_str_date( char *s, int max_len, /*HDR*/ +/** + * @brief Write a short time string "hh:mm" to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] hour Hours number, 0..23 + * @param[in] min Minutes number, 0..59 + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_time_short( char *s, int max_len, int hour, int min ) { size_t n = snprintf_safe( s, max_len, "%2u:%02u", hour, min ); + return _int_from_size_t( n ); } // mbg_str_time_short @@ -267,6 +288,19 @@ _MBG_API_ATTR int _MBG_API mbg_str_time_short( char *s, int max_len, /*HDR*/ +/** + * @brief Write a time string "hh:mm:ss" to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] hour Hours number, 0..23 + * @param[in] min Minutes number, 0..59 + * @param[in] sec Seconds number, 0..59, or 60 in case of leap second + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_time( char *s, int max_len, int hour, int min, int sec ) { @@ -281,6 +315,21 @@ _MBG_API_ATTR int _MBG_API mbg_str_time( char *s, int max_len, /*HDR*/ +/** + * @brief Write a long time string "hh:mm:ss.cc" to a string buffer + * + * Include 100ths of seconds. + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] hour Hours number, 0..23 + * @param[in] min Minutes number, 0..59 + * @param[in] sec Seconds number, 0..59, or 60 in case of leap second + * @param[in] sec100 Hundreths of seconds, 0..99 + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_time_long( char *s, int max_len, int hour, int min, int sec, int sec100 ) { @@ -295,6 +344,20 @@ _MBG_API_ATTR int _MBG_API mbg_str_time_long( char *s, int max_len, /*HDR*/ +/** + * @brief Write a full date and time string to a string buffer + * + * The number of space characters between date and time + * is determined by the global variable ::mbg_date_time_dist. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::TM_GPS structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_tm_gps_date_time( char *s, int max_len, const TM_GPS *pt ) { @@ -309,10 +372,22 @@ _MBG_API_ATTR int _MBG_API mbg_str_tm_gps_date_time( char *s, int max_len, /*HDR*/ +/** + * @brief Write the short date given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_date_short( char *s, int max_len, const PCPS_TIME *pt ) { size_t n = mbg_str_date_short( s, max_len, pt->mday, pt->month ); + return _int_from_size_t( n ); } // mbg_str_pcps_date_short @@ -320,10 +395,22 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_date_short( char *s, int max_len, /*HDR*/ +/** + * @brief Write the date given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_date( char *s, int max_len, const PCPS_TIME *pt ) { size_t n = mbg_str_date( s, max_len, pt->mday, pt->month, pt->year ); + return _int_from_size_t( n ); } // mbg_str_pcps_date @@ -331,10 +418,22 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_date( char *s, int max_len, /*HDR*/ +/** + * @brief Write the short time given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time_short( char *s, int max_len, const PCPS_TIME *pt ) { size_t n = mbg_str_time_short( s, max_len, pt->hour, pt->min ); + return _int_from_size_t( n ); } // mbg_str_pcps_time_short @@ -342,10 +441,22 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time_short( char *s, int max_len, /*HDR*/ +/** + * @brief Write the time given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time( char *s, int max_len, const PCPS_TIME *pt ) { size_t n = mbg_str_time( s, max_len, pt->hour, pt->min, pt->sec ); + return _int_from_size_t( n ); } // mbg_str_pcps_time @@ -353,10 +464,22 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time( char *s, int max_len, /*HDR*/ +/** + * @brief Write the time including sec100ths given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time_long( char *s, int max_len, const PCPS_TIME *pt ) { size_t n = mbg_str_time_long( s, max_len, pt->hour, pt->min, pt->sec, pt->sec100 ); + return _int_from_size_t( n ); } // mbg_str_pcps_time_long @@ -364,6 +487,21 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time_long( char *s, int max_len, /*HDR*/ +/** + * @brief Write date and time given as ::PCPS_TIME structure to a string buffer + * + * The number of space characters between date and time + * is determined by the global variable ::mbg_date_time_dist. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * @param[in] tz_str Optional time zone string to be appended, currently not used, may be NULL + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_date_time( char *s, int max_len, const PCPS_TIME *pt, const char *tz_str ) @@ -371,6 +509,7 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_date_time( char *s, int max_len, size_t n = mbg_str_pcps_date( s, max_len, pt ); n += mbg_strchar( &s[n], max_len - n, ' ', mbg_date_time_dist ); n += mbg_str_pcps_time( &s[n], max_len - _int_from_size_t( n ), pt ); + // FIXME Use tz_str ? return _int_from_size_t( n ); @@ -379,6 +518,17 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_date_time( char *s, int max_len, /*HDR*/ +/** + * @brief Write date derived from seconds-since-epoch to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] sec Number of seconds since the epoch to be converted to date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date( char *s, int max_len, uint32_t sec ) { @@ -395,6 +545,17 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date( char *s, int max_len, /*HDR*/ +/** + * @brief Write time derived from seconds-since-epoch to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] sec Number of seconds since the epoch to be converted to date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time( char *s, int max_len, uint32_t sec ) { @@ -410,14 +571,26 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time( char *s, int max_len, -/*HDR*/ -_MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date_time_utc( char *s, int max_len, - const PCPS_HR_TIME *pt ) +static /*HDR*/ +/* (explicitly excluded from Doxygen) + * @brief Write UTC date and time given as ::PCPS_HR_TIME structure to a string buffer + * + * The number of space characters between date and time + * is determined by the global variable ::mbg_date_time_dist. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] p_t Pointer to a time_t variable providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ +int do_str_pcps_hr_date_time( char *s, int max_len, const time_t *p_t ) { struct tm tm = { 0 }; int n = 0; - time_t t = cvt_to_time_t( pt->tstamp.sec ); - int rc = mbg_gmtime( &tm, &t ); + int rc = mbg_gmtime( &tm, p_t ); if ( mbg_rc_is_success( rc ) ) { @@ -430,41 +603,80 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date_time_utc( char *s, int max_len, return n; +} // do_str_pcps_hr_date_time + + + +/*HDR*/ +/** + * @brief Write UTC date and time given as ::PCPS_HR_TIME structure to a string buffer + * + * The number of space characters between date and time + * is determined by the global variable ::mbg_date_time_dist. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ +_MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date_time_utc( char *s, int max_len, + const PCPS_HR_TIME *pt ) +{ + time_t t = cvt_to_time_t( pt->tstamp.sec ); + + return do_str_pcps_hr_date_time( s, max_len, &t ); + } // mbg_str_pcps_hr_date_time_utc /*HDR*/ +/** + * @brief Write local date and time given as ::PCPS_HR_TIME structure to a string buffer + * + * The number of space characters between date and time + * is determined by the global variable ::mbg_date_time_dist. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date_time_loc( char *s, int max_len, const PCPS_HR_TIME *pt ) { - struct tm tm = { 0 }; - int n = 0; long l = (long) pt->tstamp.sec + pt->utc_offs; time_t t = cvt_to_time_t( l ); - int rc = mbg_gmtime( &tm, &t ); - - if ( mbg_rc_is_success( rc ) ) - { - n = mbg_str_date( s, max_len, tm.tm_mday , tm.tm_mon + 1, tm.tm_year ); - n += mbg_strchar( &s[n], max_len - n, ' ', mbg_date_time_dist ); - n += mbg_str_time( &s[n], max_len - n, tm.tm_hour, tm.tm_min, tm.tm_sec ); - } - else - n = sn_cpy_str_safe( s, max_len, str_inv_cnv ); - return n; + return do_str_pcps_hr_date_time( s, max_len, &t ); } // mbg_str_pcps_hr_date_time_loc /*HDR*/ +/** + * @brief Print binary ::PCPS_FRAC_32 fractions in decimal to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] frac Binary fractions of a second in ::PCPS_FRAC_32 format + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_frac( char *s, int max_len, uint32_t frac ) { size_t n = snprintf_safe( s, max_len, PCPS_HRT_FRAC_SCALE_FMT, - (ulong) frac_sec_from_bin( frac, PCPS_HRT_FRAC_SCALE ) ); + (ulong) bin_frac_32_to_dec_frac( frac, PCPS_HRT_FRAC_SCALE ) ); return _int_from_size_t( n ); } // mbg_str_pcps_hr_time_frac @@ -472,6 +684,19 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_frac( char *s, int max_len, /*HDR*/ +/** + * @brief Print the UTC offset from a ::PCPS_HR_TIME structure to a string buffer + * + * The output format is sign - hours - minutes, e.g. "+01:45h". + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date, and UTC offset + * @param[in] info An informational text to be prepended + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_offs( char *s, int max_len, const PCPS_HR_TIME *pt, const char *info ) @@ -494,6 +719,17 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_offs( char *s, int max_len, /*HDR*/ +/** + * @brief Write a high resolution UTC time stamp including fractions to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_tstamp_utc( char *s, int max_len, const PCPS_HR_TIME *pt ) { @@ -512,6 +748,17 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_tstamp_utc( char *s, int max_len, /*HDR*/ +/** + * @brief Write a high resolution local time stamp including fractions to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_tstamp_loc( char *s, int max_len, const PCPS_HR_TIME *pt ) { @@ -544,6 +791,17 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_tstamp_loc( char *s, int max_len, /*HDR*/ +/** + * @brief Write a raw high resolution time stamp to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_tstamp_raw( char *s, int max_len, const PCPS_TIME_STAMP *pt ) { @@ -555,6 +813,19 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_tstamp_raw( char *s, int max_len, /*HDR*/ +/** + * @brief Write a raw high resolution time stamp plus converted local time to a string buffer + * + * The output string also has the time status code appended as hex number. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_raw( char *s, int max_len, const PCPS_HR_TIME *pt ) { @@ -569,6 +840,17 @@ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_raw( char *s, int max_len, /*HDR*/ +/** + * @brief Write time capture / user capture time stamp to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure containing a user capture event + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_ucap( char *s, int max_len, const PCPS_HR_TIME *pt ) { @@ -582,6 +864,18 @@ _MBG_API_ATTR int _MBG_API mbg_str_ucap( char *s, int max_len, /*HDR*/ +/** + * @brief Write a geographic coordinate in degrees - minutes - seconds to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pdms Pointer to a ::DMS structure containing the coordinate + * @param[in] prec Number of digits of the geographic seconds after the decimal separator + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pos_dms( char *s, int max_len, const DMS *pdms, int prec ) { @@ -595,6 +889,17 @@ _MBG_API_ATTR int _MBG_API mbg_str_pos_dms( char *s, int max_len, /*HDR*/ +/** + * @brief Write a position's altitude parameter to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] alt The altitude parameter, in meters + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pos_alt( char *s, int max_len, double alt ) { size_t n = snprintf_safe( s, max_len, "%.0fm", alt ); @@ -605,6 +910,18 @@ _MBG_API_ATTR int _MBG_API mbg_str_pos_alt( char *s, int max_len, double alt ) /*HDR*/ +/** + * @brief Write geographic coordinates to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] ppos Pointer to a ::POS structure containing the coordinates + * @param[in] prec Number of digits of the geographic seconds after the decimal separator + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pos( char *s, int max_len, const POS *ppos, int prec ) { @@ -630,12 +947,23 @@ _MBG_API_ATTR int _MBG_API mbg_str_pos( char *s, int max_len, /*HDR*/ +/** + * @brief Write device info to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] short_name Short device name, e.g. in ::MBG_DEV_NAME format + * @param[in] fw_rev_num The firmware revision number + * @param[in] asic_ver_num The ASIC version number + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_dev_name( char *s, int max_len, const char *short_name, - uint16_t fw_rev_num, PCI_ASIC_VERSION asic_version_num ) + uint16_t fw_rev_num, PCI_ASIC_VERSION asic_ver_num ) { - #define HW_NAME_SZ ( PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1 ) - - char model_code[HW_NAME_SZ] = { 0 }; + MBG_DEV_NAME dev_name = { 0 }; PCPS_SN_STR sernum = { 0 }; unsigned int i = 0; size_t n = 0; @@ -643,21 +971,22 @@ _MBG_API_ATTR int _MBG_API mbg_str_dev_name( char *s, int max_len, const char *s if ( l > 0 ) { - // For serial port string specifies we just copy - // the short_name. + // For a serial port string specifies we just + // copy the short_name. if ( device_id_is_serial( short_name ) ) { n = sn_cpy_str_safe( s, max_len, short_name ); goto out; } - // If the short_name has more than HW_NAME_SZ characters + // If the short_name has more than sizeof( dev_name ) characters // then we have to reduce the maximum length. - // For bus level device, the short_name usually consists of + // For a bus level device the short_name usually consists of // the model name, followed by an underscore '_', followed // by the serial number, e.g. "PZF180PEX_046411000030". - if ( HW_NAME_SZ < l ) - l = HW_NAME_SZ; + // See ::MBG_DEV_NAME. + if ( l > sizeof( dev_name ) ) + l = sizeof( dev_name ); for ( i = 0; i < l; i++ ) { @@ -667,7 +996,7 @@ _MBG_API_ATTR int _MBG_API mbg_str_dev_name( char *s, int max_len, const char *s break; } - model_code[i] = short_name[i]; + dev_name[i] = short_name[i]; } strncpy_safe( sernum, &short_name[i], sizeof( sernum ) ); @@ -680,9 +1009,9 @@ _MBG_API_ATTR int _MBG_API mbg_str_dev_name( char *s, int max_len, const char *s sernum[MBG_GRP_SERNUM_LEN] = '\0'; } - n = snprintf_safe( s, max_len, "%s, S/N %s", model_code, sernum ); + n = snprintf_safe( s, max_len, "%s, S/N %s", dev_name, sernum ); - if ( fw_rev_num || asic_version_num ) + if ( fw_rev_num || asic_ver_num ) n += sn_cpy_str_safe( &s[n], max_len - n, " (" ); if ( fw_rev_num ) @@ -690,18 +1019,18 @@ _MBG_API_ATTR int _MBG_API mbg_str_dev_name( char *s, int max_len, const char *s n += snprintf_safe( &s[n], max_len - n, "FW v%X.%02X", fw_rev_num >> 8, fw_rev_num & 0xFF ); // Append a separator if ASIC version will follow. - if ( asic_version_num ) + if ( asic_ver_num ) n += sn_cpy_str_safe( &s[n], max_len - n, " / " ); } - if ( asic_version_num ) + if ( asic_ver_num ) { n += snprintf_safe( &s[n], max_len - n, "ASIC v%d.%02d", - _convert_asic_version_number( asic_version_num ) >> 8, - _convert_asic_version_number( asic_version_num ) & 0xFF ); + _convert_asic_version_number( asic_ver_num ) >> 8, + _convert_asic_version_number( asic_ver_num ) & 0xFF ); } - if ( fw_rev_num || asic_version_num ) + if ( fw_rev_num || asic_ver_num ) n += sn_cpy_str_safe( &s[n], max_len - n, ")" ); out: diff --git a/mbglib/common/mbgutil.h b/mbglib/common/mbgutil.h index 494f346..bc29f36 100755 --- a/mbglib/common/mbgutil.h +++ b/mbglib/common/mbgutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgutil.h 1.17.1.10 2016/07/15 14:10:05 martin TEST $ + * $Id: mbgutil.h 1.18 2017/07/05 16:44:35 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,19 +10,11 @@ * * ----------------------------------------------------------------------- * $Log: mbgutil.h $ - * Revision 1.17.1.10 2016/07/15 14:10:05 martin + * Revision 1.18 2017/07/05 16:44:35 martin + * New version code 0x0400, compatibility version still 0x0110. * Include timeutil.h. - * Revision 1.17.1.9 2015/08/27 16:17:53 martin + * windows.h is now included in mbg_tgt.h. * Updated function prototypes. - * Revision 1.17.1.8 2014/05/27 11:32:47 martin - * Revision 1.17.1.7 2014/03/13 16:04:12 martin - * Revision 1.17.1.6 2014/03/13 15:45:37 martin - * Revision 1.17.1.5 2014/03/13 14:58:52Z martin - * Revision 1.17.1.4 2014/03/13 14:31:53Z martin - * Revision 1.17.1.3 2014/03/05 10:38:30Z martin - * Windows.h is now included in mbg_tgt.h. - * Revision 1.17.1.2 2013/10/23 10:40:53Z martin - * Revision 1.17.1.1 2013/10/22 10:06:01 martin * Revision 1.17 2012/10/15 10:08:32 martin * Include stdlib.h. * Cleaned up handling of pragma pack(). @@ -77,7 +69,7 @@ #include <stdlib.h> -#define MBGUTIL_VERSION 0x0306 +#define MBGUTIL_VERSION 0x0400 #define MBGUTIL_COMPAT_VERSION 0x0110 @@ -116,24 +108,11 @@ #endif -#if defined( MBG_TGT_WIN32 ) - -#elif defined( MBG_TGT_LINUX ) - -#elif defined( MBG_TGT_OS2 ) - -#else - -#endif - - - -/* function prototypes: */ - #ifdef __cplusplus extern "C" { #endif + // The macro below can be used to simplify the API call if // a string variable is used rather than a char *. #define _mbg_strncpy( _s, _src ) \ @@ -155,7 +134,7 @@ extern "C" { /** * @brief Check the DLL/shared library's compatibility * - * @param header_version Version code defined in the header file when the application is built + * @param[in] header_version Version code defined in the header file when the application is built * * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE */ @@ -164,12 +143,13 @@ extern "C" { /** * @brief A portable, safe implementation of snprintf() * + * The output string buffer is in any case properly terminated by 0. * For a detailed description see ::vsnprintf_safe * - * @param s pointer to the output buffer - * @param max_len size of the output buffer - * @param fmt format string according to subsequent parameters - * @param ... variable argument list according to the format string + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] fmt Format string according to subsequent parameters + * @param[in] ... Variable argument list according to the format string * * @return the number of characters written to the output buffer, except the terminating 0 * @@ -178,48 +158,415 @@ extern "C" { */ _MBG_API_ATTR int __attribute__( ( format( printf, 3, 4 ) ) ) _MBG_API mbg_snprintf( char *s, size_t max_len, const char * fmt, ... ) ; + /** + * @brief A portable, safe implementation of strncpy() + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the destination string buffer + * @param[in] max_len Size of the destination string buffer + * @param[in] src Pointer to the source string buffer + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_strncpy( char *s, size_t max_len, const char *src ) ; + /** * @brief Write a character multiple times to a string buffer * - * Append a terminating 0 to the buffer. + * The output string buffer is in any case properly terminated by 0. * - * @param s pointer to the output buffer - * @param max_len size of the output buffer - * @param c the character to write to the output buffer - * @param n the number of characters to write to the output buffer + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] c The character to write to the output buffer + * @param[in] n The number of characters to write to the output buffer * * @return the number of characters written to the output buffer, except the terminating 0 */ _MBG_API_ATTR int _MBG_API mbg_strchar( char *s, size_t max_len, char c, size_t n ) ; + /** + * @brief Write a short date string "dd.mm." to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] mday Day-of-month number, 1..31 + * @param[in] month Month number, 1..12 + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_date_short( char *s, int max_len, int mday, int month ) ; + + /** + * @brief Write a date string "dd.mm.yyyy" to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] mday Day-of-month number, 1..31 + * @param[in] month Month number, 1..12 + * @param[in] year Year number + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_date( char *s, int max_len, int mday, int month, int year ) ; + + /** + * @brief Write a short time string "hh:mm" to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] hour Hours number, 0..23 + * @param[in] min Minutes number, 0..59 + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_time_short( char *s, int max_len, int hour, int min ) ; + + /** + * @brief Write a time string "hh:mm:ss" to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] hour Hours number, 0..23 + * @param[in] min Minutes number, 0..59 + * @param[in] sec Seconds number, 0..59, or 60 in case of leap second + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_time( char *s, int max_len, int hour, int min, int sec ) ; + + /** + * @brief Write a long time string "hh:mm:ss.cc" to a string buffer + * + * Include 100ths of seconds. + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] hour Hours number, 0..23 + * @param[in] min Minutes number, 0..59 + * @param[in] sec Seconds number, 0..59, or 60 in case of leap second + * @param[in] sec100 Hundreths of seconds, 0..99 + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_time_long( char *s, int max_len, int hour, int min, int sec, int sec100 ) ; + + /** + * @brief Write a full date and time string to a string buffer + * + * The number of space characters between date and time + * is determined by the global variable ::mbg_date_time_dist. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::TM_GPS structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_tm_gps_date_time( char *s, int max_len, const TM_GPS *pt ) ; + + /** + * @brief Write the short date given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_date_short( char *s, int max_len, const PCPS_TIME *pt ) ; + + /** + * @brief Write the date given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_date( char *s, int max_len, const PCPS_TIME *pt ) ; + + /** + * @brief Write the short time given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time_short( char *s, int max_len, const PCPS_TIME *pt ) ; + + /** + * @brief Write the time given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time( char *s, int max_len, const PCPS_TIME *pt ) ; + + /** + * @brief Write the time including sec100ths given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time_long( char *s, int max_len, const PCPS_TIME *pt ) ; + + /** + * @brief Write date and time given as ::PCPS_TIME structure to a string buffer + * + * The number of space characters between date and time + * is determined by the global variable ::mbg_date_time_dist. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * @param[in] tz_str Optional time zone string to be appended, currently not used, may be NULL + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_date_time( char *s, int max_len, const PCPS_TIME *pt, const char *tz_str ) ; + + /** + * @brief Write date derived from seconds-since-epoch to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] sec Number of seconds since the epoch to be converted to date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date( char *s, int max_len, uint32_t sec ) ; + + /** + * @brief Write time derived from seconds-since-epoch to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] sec Number of seconds since the epoch to be converted to date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time( char *s, int max_len, uint32_t sec ) ; + + /** + * @brief Write UTC date and time given as ::PCPS_HR_TIME structure to a string buffer + * + * The number of space characters between date and time + * is determined by the global variable ::mbg_date_time_dist. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date_time_utc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; + + /** + * @brief Write local date and time given as ::PCPS_HR_TIME structure to a string buffer + * + * The number of space characters between date and time + * is determined by the global variable ::mbg_date_time_dist. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date_time_loc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; + + /** + * @brief Print binary ::PCPS_FRAC_32 fractions in decimal to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] frac Binary fractions of a second in ::PCPS_FRAC_32 format + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_frac( char *s, int max_len, uint32_t frac ) ; + + /** + * @brief Print the UTC offset from a ::PCPS_HR_TIME structure to a string buffer + * + * The output format is sign - hours - minutes, e.g. "+01:45h". + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date, and UTC offset + * @param[in] info An informational text to be prepended + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_offs( char *s, int max_len, const PCPS_HR_TIME *pt, const char *info ) ; + + /** + * @brief Write a high resolution UTC time stamp including fractions to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_tstamp_utc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; + + /** + * @brief Write a high resolution local time stamp including fractions to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_tstamp_loc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; + + /** + * @brief Write a raw high resolution time stamp to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_tstamp_raw( char *s, int max_len, const PCPS_TIME_STAMP *pt ) ; + + /** + * @brief Write a raw high resolution time stamp plus converted local time to a string buffer + * + * The output string also has the time status code appended as hex number. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_raw( char *s, int max_len, const PCPS_HR_TIME *pt ) ; + + /** + * @brief Write time capture / user capture time stamp to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure containing a user capture event + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_ucap( char *s, int max_len, const PCPS_HR_TIME *pt ) ; + + /** + * @brief Write a geographic coordinate in degrees - minutes - seconds to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pdms Pointer to a ::DMS structure containing the coordinate + * @param[in] prec Number of digits of the geographic seconds after the decimal separator + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pos_dms( char *s, int max_len, const DMS *pdms, int prec ) ; + + /** + * @brief Write a position's altitude parameter to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] alt The altitude parameter, in meters + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pos_alt( char *s, int max_len, double alt ) ; + + /** + * @brief Write geographic coordinates to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] ppos Pointer to a ::POS structure containing the coordinates + * @param[in] prec Number of digits of the geographic seconds after the decimal separator + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pos( char *s, int max_len, const POS *ppos, int prec ) ; - _MBG_API_ATTR int _MBG_API mbg_str_dev_name( char *s, int max_len, const char *short_name, uint16_t fw_rev_num, PCI_ASIC_VERSION asic_version_num ) ; + + /** + * @brief Write device info to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] short_name Short device name, e.g. in ::MBG_DEV_NAME format + * @param[in] fw_rev_num The firmware revision number + * @param[in] asic_ver_num The ASIC version number + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_dev_name( char *s, int max_len, const char *short_name, uint16_t fw_rev_num, PCI_ASIC_VERSION asic_ver_num ) ; + /* ----- function prototypes end ----- */ diff --git a/mbglib/common/myutil.h b/mbglib/common/myutil.h index 0f0d817..aad15f1 100755 --- a/mbglib/common/myutil.h +++ b/mbglib/common/myutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: myutil.h 1.20 2017/03/22 15:09:03 andre.hartmann TEST $ + * $Id: myutil.h 1.20 2017/03/22 15:09:03 andre.hartmann REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * diff --git a/mbglib/common/nanotime.c b/mbglib/common/nanotime.c new file mode 100755 index 0000000..43cf863 --- /dev/null +++ b/mbglib/common/nanotime.c @@ -0,0 +1,312 @@ + +/************************************************************************** + * + * $Id: nanotime.c 1.2 2017/06/12 13:54:04 martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Meinberg Library module providing functions to handle NANO_TIME + * and NANO_TIME_64. + * + * ----------------------------------------------------------------------- + * $Log: nanotime.c $ + * Revision 1.2 2017/06/12 13:54:04 martin + * Fixed build under Windows. + * Revision 1.1 2017/06/12 08:49:09Z martin + * Initial revision. + * + **************************************************************************/ + +#define _NANOTIME + #include <nanotime.h> +#undef _NANOTIME + +#include <mbgtime.h> +#include <str_util.h> + +#include <stdlib.h> + + +// At least MSVC++ 9.0 / Visual Studio 2008 or older +// doesn't provide strtoll() +#if defined( _MSC_VER ) && ( _MSC_VER <= 1500 ) + #define strtoll _strtoi64 +#endif + + +/*HDR*/ +/** + * @brief Convert a ::NANO_TIME time to double + * + * @param[in] p Address of a ::NANO_TIME structure to be converted + * + * @return The computed number of seconds with fractions, as double + * + * @see ::double_to_nano_time + */ +double nano_time_to_double( const NANO_TIME *p ) +{ + double d = p->secs; + + d += ( (double) p->nano_secs ) / 1e9; + + return d; + +} // nano_time_to_double + + + +/*HDR*/ +/** + * @brief Setup a ::NANO_TIME structure from a time provided as double + * + * @param[out] p Address of a ::NANO_TIME structure to be set up + * @param[in] d The time to be converted, in seconds with fractions, as double + * + * @see ::nano_time_to_double + */ +void double_to_nano_time( NANO_TIME *p, double d ) +{ + p->secs = (int32_t) d; + + d -= (double) p->secs; + + p->nano_secs = (int32_t) ( d * 1e9 ); + +} // double_to_nano_time + + + +/*HDR*/ +/** + * @brief Print nano time into string buffer + * + * @param[out] s The string buffer to be filled + * @param[in] max_len Size of the output buffer for 0-terminated string + * @param[in] nt The ::NANO_TIME to be printed + */ +size_t snprint_nano_time( char *s, size_t max_len, const NANO_TIME *nt ) +{ + size_t n = snprintf_safe( s, max_len, "%c%li.%09li", + _nano_time_negative( nt ) ? '-' : '+', + labs( (long) nt->secs ), + labs( (long) nt->nano_secs ) ); + return n; + +} // snprint_nano_time + + + +#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + +/*HDR*/ +/** + * @brief Normalize a ::NANO_TIME_64 time + * + * After normalization, the following can be assumed:<br> + * - nano_secs is in the range [-10^9 + 1, 10^9 - 1]<br> + * - if secs is not 0, secs and nano_secs have the same sign + * + * @param[in,out] nt The ::NANO_TIME_64 to be normalized + */ +void normalize_nano_time_64( NANO_TIME_64 *nt ) +{ + int64_t additional_secs; + + // Step 1: Make sure nano seconds are in the interval [-10^9 + 1, 10^9 - 1] + additional_secs = nt->nano_secs / NSECS_PER_SEC; + nt->nano_secs -= additional_secs * NSECS_PER_SEC; + nt->secs += additional_secs; + + // Step 2: Make sure seconds and nanoseconds have same sign if seconds is not 0 + if ( nt->secs > 0 && nt->nano_secs < 0 ) + { + nt->secs -= 1; + nt->nano_secs += NSECS_PER_SEC; + } + else if ( nt->secs < 0 && nt->nano_secs > 0 ) + { + nt->secs += 1; + nt->nano_secs -= NSECS_PER_SEC; + } + +} // normalize_nano_time_64 + + + +/*HDR*/ +/** + * @brief Convert a ::NANO_TIME_64 time to double + * + * @param[in] p Address of a ::NANO_TIME_64 structure to be converted + * + * @return The computed number of seconds with fractions, as double + * + * @see ::double_to_nano_time_64 + */ +double nano_time_64_to_double( const NANO_TIME_64 *p ) +{ + double d = (double) p->secs; + + d += ( (double) p->nano_secs ) / 1e9; + + return d; + +} // nano_time_64_to_double + + + +/*HDR*/ +/** + * @brief Setup a ::NANO_TIME_64 structure from a time as double + * + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + * @param[in] d The time to be converted, in seconds with fractions, as double + * + * @see ::nano_time_64_to_double + */ +void double_to_nano_time_64( NANO_TIME_64 *p, double d ) +{ + p->secs = (int32_t) d; + + d -= (double) p->secs; + + p->nano_secs = (int32_t) ( d * 1e9 ); + +} // double_to_nano_time_64 + + + +/*HDR*/ +/** + * @brief Print a normalized ::NANO_TIME_64 into a string buffer + * + * @param[out] s The string buffer to be filled + * @param[in] max_len Size of the output buffer for 0-terminated string + * @param[in] nt The ::NANO_TIME_64 to be printed + */ +size_t snprint_nano_time_64( char *s, size_t max_len, const NANO_TIME_64 *nt ) +{ + size_t n = snprintf_safe( s, max_len, "%c%" PRId64 ".%09" PRId64, + _nano_time_negative( nt ) ? '-' : '+', + _abs64( nt->secs ), + _abs64( nt->nano_secs ) ); + return n; + +} // snprint_nano_time_64 + + + +static __mbg_inline /*HDR*/ +/** + * @brief Generic function to set up a ::NANO_TIME_64 structure from a string + * + * @param[in] s A string with a time in seconds, with fractions separated by decimal point + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + * @param[in] base The base of the conversion, i.e. 10 for a string with decimal numbers, or 16 for a hex string + * @param[in] frac_digits The number of fractions required to represent 1 nanosecond, e.g. + * 9 for a decimal string like 0.000000001, or + * TODO for a hex string like 0x00000000.00000000 + */ +void str_to_nano_time_64( const char *s, NANO_TIME_64 *p, int base, int frac_digits ) +{ + char *cp = NULL; + + p->secs = strtoll( s, &cp, base ); + + if ( *cp == '.' ) // fractions may follow + { + char *ep = NULL; + + cp++; // skip '.' + + p->nano_secs = strtoll( cp, &ep, base ); + + if ( p->nano_secs ) // only if fractions not 0 + { + int l = ep - cp; + + while ( l < frac_digits ) + { + p->nano_secs *= base; + l++; + } + + while ( l > frac_digits ) + { + p->nano_secs /= base; + l--; + } + + if ( p->secs < 0 ) + p->nano_secs = -p->nano_secs; + } + } + +} // str_to_nano_time_64 + + + +static __mbg_inline /*HDR*/ +/** + * @brief Generic function to divide ::NANO_TIME_64 value + * + * @param[in,out] p Address of a ::NANO_TIME_64 structure to be divided + * @param[in] div The number by which to divide + * @param[in] mul The complementary number to div, i.e. mul = 1000000000 / div + */ +void div_nano_time_64( NANO_TIME_64 *p, long div, long mul ) +{ + // At least MSVC++ 9.0 / Visual Studio 2008 or older + // doesn't provide lldiv_t and lldiv(). + #if defined( _MSC_VER ) && ( _MSC_VER <= 1500 ) //### TODO: Test this code + int64_t rem = p->secs % div; + p->secs /= div; + p->nano_secs = ( rem * mul ) + ( p->nano_secs / div ); + #else + lldiv_t lldt = lldiv( p->secs, div ); + p->secs = lldt.quot; + p->nano_secs = ( lldt.rem * mul ) + ( p->nano_secs / div ); + #endif + +} // div_nano_time_64 + + + +/*HDR*/ +/** + * @brief Set up a ::NANO_TIME_64 structure from a string with a time in seconds and fractions + * + * @param[in] s A string with a time in seconds, with fractions separated by decimal point + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + */ +void str_s_to_nano_time_64( const char *s, NANO_TIME_64 *p ) +{ + str_to_nano_time_64( s, p, 10, 9 ); + +} // str_s_to_nano_time_64 + + + +/*HDR*/ +/** + * @brief Set up a ::NANO_TIME_64 structure from a string with a time in milliseconds and fractions + * + * @param[in] s A string with a time in milliseconds, with fractions separated by decimal point + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + */ +void str_ms_to_nano_time_64( const char *s, NANO_TIME_64 *p ) +{ + // First do the same conversion as for a string representing seconds + str_s_to_nano_time_64( s, p ); + + // Now we have the value in milliseconds + // Divide by 1000 to get seconds + div_nano_time_64( p, 1000, 1000000UL ); + +} // str_ms_to_nano_time_64 + +#endif // !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + + diff --git a/mbglib/common/nanotime.h b/mbglib/common/nanotime.h new file mode 100755 index 0000000..85963a6 --- /dev/null +++ b/mbglib/common/nanotime.h @@ -0,0 +1,148 @@ + +/************************************************************************** + * + * $Id: nanotime.h 1.1 2017/06/12 08:49:09 martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for nanotime.c + * + * ----------------------------------------------------------------------- + * $Log: nanotime.h $ + * Revision 1.1 2017/06/12 08:49:09 martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _NANOTIME_H +#define _NANOTIME_H + +/* Other headers to be included */ + +#include <words.h> // implicitly includes mbg_tgt.h, if required, + // and defines some basic structures + +#ifdef _NANOTIME + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + + + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + /** + * @brief Convert a ::NANO_TIME time to double + * + * @param[in] p Address of a ::NANO_TIME structure to be converted + * + * @return The computed number of seconds with fractions, as double + * + * @see ::double_to_nano_time + */ + double nano_time_to_double( const NANO_TIME *p ) ; + + /** + * @brief Setup a ::NANO_TIME structure from a time provided as double + * + * @param[out] p Address of a ::NANO_TIME structure to be set up + * @param[in] d The time to be converted, in seconds with fractions, as double + * + * @see ::nano_time_to_double + */ + void double_to_nano_time( NANO_TIME *p, double d ) ; + + /** + * @brief Print nano time into string buffer + * + * @param[out] s The string buffer to be filled + * @param[in] max_len Size of the output buffer for 0-terminated string + * @param[in] nt The ::NANO_TIME to be printed + */ + size_t snprint_nano_time( char *s, size_t max_len, const NANO_TIME *nt ) ; + + /** + * @brief Normalize a ::NANO_TIME_64 time + * + * After normalization, the following can be assumed:<br> + * - nano_secs is in the range [-10^9 + 1, 10^9 - 1]<br> + * - if secs is not 0, secs and nano_secs have the same sign + * + * @param[in,out] nt The ::NANO_TIME_64 to be normalized + */ + void normalize_nano_time_64( NANO_TIME_64 *nt ) ; + + /** + * @brief Convert a ::NANO_TIME_64 time to double + * + * @param[in] p Address of a ::NANO_TIME_64 structure to be converted + * + * @return The computed number of seconds with fractions, as double + * + * @see ::double_to_nano_time_64 + */ + double nano_time_64_to_double( const NANO_TIME_64 *p ) ; + + /** + * @brief Setup a ::NANO_TIME_64 structure from a time as double + * + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + * @param[in] d The time to be converted, in seconds with fractions, as double + * + * @see ::nano_time_64_to_double + */ + void double_to_nano_time_64( NANO_TIME_64 *p, double d ) ; + + /** + * @brief Print a normalized ::NANO_TIME_64 into a string buffer + * + * @param[out] s The string buffer to be filled + * @param[in] max_len Size of the output buffer for 0-terminated string + * @param[in] nt The ::NANO_TIME_64 to be printed + */ + size_t snprint_nano_time_64( char *s, size_t max_len, const NANO_TIME_64 *nt ) ; + + /** + * @brief Set up a ::NANO_TIME_64 structure from a string with a time in seconds and fractions + * + * @param[in] s A string with a time in seconds, with fractions separated by decimal point + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + */ + void str_s_to_nano_time_64( const char *s, NANO_TIME_64 *p ) ; + + /** + * @brief Set up a ::NANO_TIME_64 structure from a string with a time in milliseconds and fractions + * + * @param[in] s A string with a time in milliseconds, with fractions separated by decimal point + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + */ + void str_ms_to_nano_time_64( const char *s, NANO_TIME_64 *p ) ; + + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _NANOTIME_H */ diff --git a/mbglib/common/ntp_shm.c b/mbglib/common/ntp_shm.c index 1fe9779..4be1d30 100755 --- a/mbglib/common/ntp_shm.c +++ b/mbglib/common/ntp_shm.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: ntp_shm.c 1.1.1.1 2013/07/23 16:10:35 martin TEST $ + * $Id: ntp_shm.c 1.2 2017/07/05 16:49:00 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: ntp_shm.c $ - * Revision 1.1.1.1 2013/07/23 16:10:35 martin + * Revision 1.2 2017/07/05 16:49:00 martin + * Patch submitted by <juergen.perlinger@t-online.de>: + * Support number of the first SHM unit to use. + * This intentionally changes the prototype for ntpshm_init(). * Revision 1.1 2012/05/29 09:54:15 martin * Initial revision. * @@ -56,19 +59,20 @@ struct shmTime *getShmTime( int unit ) /*HDR*/ -int ntpshm_init( struct shmTime **shmTime, int n_units ) +int ntpshm_init( struct shmTime **shmTime, int n_units, int n_unit0 ) { int i; int ret_val = 0; for ( i = 0; i < n_units; i++ ) { - struct shmTime *p = getShmTime( i ); + int u = i + n_unit0; + struct shmTime *p = getShmTime( u ); shmTime[i] = p; if ( p == NULL ) { - syslog( LOG_WARNING, "** Failed to initialize NTP SHM unit %i", i ); + syslog( LOG_WARNING, "** Failed to initialize NTP SHM unit %i", u ); ret_val = -1; continue; } @@ -79,7 +83,7 @@ int ntpshm_init( struct shmTime **shmTime, int n_units ) p->precision = -5; /* initially 0.5 sec */ p->nsamples = 3; /* stages of median filter */ - syslog( LOG_INFO, "NTP SHM unit %i initialized successfully", i ); + syslog( LOG_INFO, "NTP SHM unit %i initialized successfully", u ); } return ret_val; diff --git a/mbglib/common/ntp_shm.h b/mbglib/common/ntp_shm.h index 0589cfe..2cefc00 100755 --- a/mbglib/common/ntp_shm.h +++ b/mbglib/common/ntp_shm.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: ntp_shm.h 1.2.2.2 2014/07/30 10:20:38 martin TEST $ + * $Id: ntp_shm.h 1.3 2017/07/05 16:52:25 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,10 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: ntp_shm.h $ - * Revision 1.2.2.2 2014/07/30 10:20:38 martin - * Doxygen fixes. - * Revision 1.2.2.1 2013/12/12 11:28:35 martin - * Doxygen stuff. + * Revision 1.3 2017/07/05 16:52:25 martin + * Defined MAX_SHM_UNIT_OFFSET. + * Doxygen changes and fixes. + * Updated function prototypes. * Revision 1.2 2013/01/02 10:23:41 daniel * Added nsec support * Revision 1.1 2012/05/29 09:54:15 martin @@ -107,6 +107,12 @@ struct shmTime /** + * @brief Max. Number of SHM unit offset + */ +#define MAX_SHM_UNIT_OFFSET 128 + + +/** * @brief Basic SHM unit identifier (unit 0) */ #define NTPD_BASE 0x4e545030 ///< "NTP0" @@ -115,15 +121,13 @@ struct shmTime -/* 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 ) ; + int ntpshm_init( struct shmTime **shmTime, int n_units, int n_unit0 ) ; /* ----- function prototypes end ----- */ diff --git a/mbglib/common/pci.h b/mbglib/common/pci.h index fc8abb5..8f0a644 100755 --- a/mbglib/common/pci.h +++ b/mbglib/common/pci.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pci.h 1.9 2008/01/30 13:42:29 martin REL_M $ + * $Id: pci.h 1.10 2017/05/10 15:24:21 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: pci.h $ + * Revision 1.10 2017/05/10 15:24:21 martin + * Tiny cleanup. * Revision 1.9 2008/01/30 13:42:29 martin * Code cleanup to support different build environments properly. * Revision 1.8 2006/07/11 08:59:00Z martin @@ -67,7 +69,6 @@ #endif - #ifdef _PCI #define _ext #else @@ -77,6 +78,10 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + #if !defined( pci_fnc_init ) #define pci_fnc_init() 0 #endif @@ -132,16 +137,6 @@ #endif // defined( MBG_PCI_MACROS_MAP_GENERIC ) -/* End of header body */ - -#undef _ext - - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif /* ----- function prototypes begin ----- */ @@ -157,6 +152,10 @@ extern "C" { #endif +/* End of header body */ + +#undef _ext + #endif /* _PCI_H */ diff --git a/mbglib/common/pci_asic.h b/mbglib/common/pci_asic.h index 36f04af..3bbba03 100755 --- a/mbglib/common/pci_asic.h +++ b/mbglib/common/pci_asic.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pci_asic.h 1.27 2017/04/25 11:36:30 martin TEST $ + * $Id: pci_asic.h 1.29 2017/07/04 14:18:03 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: pci_asic.h $ + * Revision 1.29 2017/07/04 14:18:03 martin + * Updated minor version for PTP270PEX. + * Revision 1.28 2017/05/10 15:24:21 martin + * Tiny cleanup. * Revision 1.27 2017/04/25 11:36:30 martin * Renamed GRC181PEX to GNS181PEX. * Revision 1.26 2016/09/15 14:55:02 martin @@ -107,6 +111,11 @@ #define _USING_BYTE_ALIGNMENT #endif +#ifdef __cplusplus +extern "C" { +#endif + + /** * @brief Set of PCI ASIC registers which are writeable once after power-up **/ @@ -383,40 +392,41 @@ enum PCI_ASIC_MAJOR_VERSION_NUMBERS #define PCI_ASIC_CURRENT_MINOR_PEX511 0x04 #define PCI_ASIC_REQUIRED_MINOR_PEX511 0x03 -#define PCI_ASIC_FIX_HRT_MINOR_PEX511 0x04 // increases HRT accuracy -#define PCI_ASIC_FIX_IRQ_MINOR_PEX511 0x03 // fixes IRQ problem -#define PCI_ASIC_HR_TIME_MINOR_PEX511 0x02 // supports HR time with PEX511 +#define PCI_ASIC_FIX_HRT_MINOR_PEX511 0x04 // Increases HRT accuracy +#define PCI_ASIC_FIX_IRQ_MINOR_PEX511 0x03 // Fixes IRQ problem +#define PCI_ASIC_HR_TIME_MINOR_PEX511 0x02 // Supports HR time with PEX511 #define PCI_ASIC_CURRENT_MINOR_GPS170PEX 0x05 #define PCI_ASIC_REQUIRED_MINOR_GPS170PEX 0x03 -#define PCI_ASIC_ENH_HRT_MINOR_GPS170PEX 0x05 // enhanced MM HRT accuracy -#define PCI_ASIC_FIX_HRT_MINOR_GPS170PEX 0x04 // increases MM HRT accuracy -#define PCI_ASIC_FIX_IRQ_MINOR_GPS170PEX 0x03 // fixes IRQ problem +#define PCI_ASIC_ENH_HRT_MINOR_GPS170PEX 0x05 // Enhanced MM HRT accuracy +#define PCI_ASIC_FIX_HRT_MINOR_GPS170PEX 0x04 // Increases MM HRT accuracy +#define PCI_ASIC_FIX_IRQ_MINOR_GPS170PEX 0x03 // Fixes IRQ problem #define PCI_ASIC_CURRENT_MINOR_TCR511PEX 0x04 #define PCI_ASIC_REQUIRED_MINOR_TCR511PEX 0x03 // 0x04 // EPLD sources shared with PEX511 0x04 -#define PCI_ASIC_FIX_IRQ_MINOR_TCR511PEX 0x03 // fixes IRQ problem, increases HRT accuracy +#define PCI_ASIC_FIX_IRQ_MINOR_TCR511PEX 0x03 // Fixes IRQ problem, increases HRT accuracy -#define PCI_ASIC_CURRENT_MINOR_PTP270PEX 0x05 +#define PCI_ASIC_CURRENT_MINOR_PTP270PEX 0x06 #define PCI_ASIC_REQUIRED_MINOR_PTP270PEX 0x01 +// 0x06 // Supports 1 PPS pulse shift // 0x05 // ... // 0x04 // ... // 0x03 // ... -// 0x02 // increased accuracy of IRIG DCLS slopes -// 0x01 // supports inversion of ucap slopes +// 0x02 // Increased accuracy of IRIG DCLS slopes +// 0x01 // Supports inversion of ucap slopes #define PCI_ASIC_CURRENT_MINOR_FRC511PEX 0x01 #define PCI_ASIC_REQUIRED_MINOR_FRC511PEX 0x01 #define PCI_ASIC_CURRENT_MINOR_TCR170PEX 0x03 #define PCI_ASIC_REQUIRED_MINOR_TCR170PEX 0x02 -#define PCI_ASIC_FIX_EE_ACCESS_TCR170PEX 0x02 // fixes EE access problem after reset -#define PCI_ASIC_FIX_FO_IN_LEVEL_TCR170PEX 0x03 // correct polarity for fiber optic input +#define PCI_ASIC_FIX_EE_ACCESS_TCR170PEX 0x02 // Fixes EE access problem after reset +#define PCI_ASIC_FIX_FO_IN_LEVEL_TCR170PEX 0x03 // Correct polarity for fiber optic input #define PCI_ASIC_CURRENT_MINOR_GPS180PEX 0x06 #define PCI_ASIC_REQUIRED_MINOR_GPS180PEX 0x01 -// 0x01 // updated VHDL compiler and associated PCI primitives +// 0x01 // Updated VHDL compiler and associated PCI primitives // 0x02 // I/O using 3.3V LVTTL // 0x03 // GPS TIC pulse len now 1 sample clock // 0x04 // Enabled PCI IRQ line which had unintentionally been disabled earlier @@ -479,12 +489,6 @@ typedef struct } -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ @@ -510,4 +514,3 @@ extern "C" { #undef _DO_INIT #endif /* _PCI_ASIC_H */ - diff --git a/mbglib/common/pcidefs.h b/mbglib/common/pcidefs.h index 4a3baed..83c503d 100755 --- a/mbglib/common/pcidefs.h +++ b/mbglib/common/pcidefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcidefs.h 1.8 2013/09/26 09:26:34 martin REL_M $ + * $Id: pcidefs.h 1.9 2017/05/10 15:24:15 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: pcidefs.h $ + * Revision 1.9 2017/05/10 15:24:15 martin + * Tiny cleanup. * Revision 1.8 2013/09/26 09:26:34 martin * Added num of addr regs for PCI CFG header type 0x01. * Re-ordered definition of PCI vendor IDs based on numerical code. @@ -47,6 +49,9 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif // Available PCI subfunction codes depend on the operating system // so they are defined in the associated headers. @@ -239,24 +244,24 @@ typedef struct #define PCI_VENDOR_ADAPTEC_1 0x9004 #define PCI_VENDOR_ADAPTEC_2 0x9005 -/* End of header body */ -#undef _ext +/* ----- function prototypes begin ----- */ +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ +/* (no header definitions found) */ -/* function prototypes: */ +/* ----- function prototypes end ----- */ #ifdef __cplusplus -extern "C" { +} #endif -// currently none -#ifdef __cplusplus -} -#endif +/* End of header body */ +#undef _ext #endif /* _PCIDEFS_H */ diff --git a/mbglib/common/pcpsdefs.h b/mbglib/common/pcpsdefs.h index a0fa80e..d3fcf99 100755 --- a/mbglib/common/pcpsdefs.h +++ b/mbglib/common/pcpsdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsdefs.h 1.61 2017/04/25 11:38:38 martin TEST $ + * $Id: pcpsdefs.h 1.62 2017/07/04 16:24:53 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,11 @@ * * ----------------------------------------------------------------------- * $Log: pcpsdefs.h $ + * Revision 1.62 2017/07/04 16:24:53 martin + * Moved definitions PCPS_HRT_FRAC_SCALE and PCPS_HRT_FRAC_SCALE_FMT + * back here. + * New types PCPS_SECONDS and PCPS_FRAC_32. + * Fixed typo, wording, and doxygen comments. * Revision 1.61 2017/04/25 11:38:38 martin * Renamed GRC181PEX to GNS181PEX. * Revision 1.60 2017/03/17 12:00:05 martin @@ -427,7 +432,7 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * * The flags ::PCPS_ST_SEC and ::PCPS_ST_MIN are cleared whenever the clock * is read, so they are not very reliable in multitasking environments - * and thus should be considered deprecated. + * and thus should be considered as deprecated. * * The ::PCPS_ST_IRQF flag was used with old ISA cards to check * if the device has generated an IRQ. @@ -435,7 +440,7 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * associated flag of the PCI interface chip should be checked to see * if a particular card has generated an IRQ on the PC bus. * - * The macro ::_pcps_ddev_has_gen_irq() cares about this and should be used + * The macro ::_pcps_ddev_has_gen_irq cares about this and should be used * to determine in a portable way whether a card has generated an IRQ. * * @anchor PCPS_STATUS_PORT_BIT_MASKS @{ */ @@ -479,7 +484,7 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * the command code is passed. Every parameter byte has to be supplied * to the board exactly like a command byte. * - * Refer to function ::pcps_write() and the macro ::_pcps_write_var() + * Refer to function ::pcps_write and the macro ::_pcps_write_var * for details. * * - ::PCPS_GIVE_TIME<br> @@ -498,30 +503,30 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * Return a ::PCPS_TIME structure with date and time * of last synchronization of the clock or * the last time set via the interface. - * ::_pcps_has_sync_time() checks whether supported. + * ::_pcps_has_sync_time checks whether supported. * * - ::PCPS_GIVE_HR_TIME<br> * Return a ::PCPS_HR_TIME structure with current * date, time and status. This command should be * used to read the clock with higher resolution. - * ::_pcps_has_hr_time() checks whether supported. + * ::_pcps_has_hr_time checks whether supported. * * - ::PCPS_GIVE_IRIG_TIME<br> * Return a ::PCPS_IRIG_TIME structure with day-of-year, * time and status as decoded from the IRIG signal. - * ::_pcps_has_irig_time() checks whether supported. + * ::_pcps_has_irig_time checks whether supported. * * - ::PCPS_SET_TIME<br> * Set the board date, time and status. This command * expects sizeof( ::PCPS_STIME ) parameter bytes. - * ::_pcps_can_set_time() checks whether supported. + * ::_pcps_can_set_time checks whether supported. * * - ::PCPS_SET_EVENT_TIME<br> * Send a high resolution time stamp to the clock to * configure a %UTC time when the clock shall generate * some event. This command expects a ::PCPS_TIME_STAMP * parameter. - * ::_pcps_has_event_time() checks whether supported. + * ::_pcps_has_event_time checks whether supported. * (requires custom GPS CERN firmware) * * - ::PCPS_IRQ_NONE<br> @@ -539,10 +544,10 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * ::PCPS_SET_SERIAL<br> * Deprecated. Read or write the configuration of a card's * serial port COM0 in ::PCPS_SERIAL format. - * ::_pcps_has_serial() checks whether supported. + * ::_pcps_has_serial checks whether supported. * Newer cards should be configured using the structures ::RECEIVER_INFO, * ::PORT_INFO, and STR_TYPE_INFO. - * ::_pcps_has_receiver_info() checks whether these are supported. + * ::_pcps_has_receiver_info checks whether these are supported. * * - ::PCPS_GET_TZCODE<br> * ::PCPS_SET_TZCODE<br> @@ -550,7 +555,7 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * time zone code and should be used preferably * with older DCF77 receivers which have limited * support of different time zones. - * ::_pcps_has_tzcode() checks whether supported. + * ::_pcps_has_tzcode checks whether supported. * Most newer devices support the ::TZDL structure which can be * read or written using ::PC_GPS_TZDL. * @@ -558,7 +563,7 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * ::PCPS_SET_PCPS_TZDL<br> * Read or write time zone / daylight saving information * in ::PCPS_TZDL format. - * ::_pcps_has_pcps_tzdl() checks whether supported. + * ::_pcps_has_pcps_tzdl checks whether supported. * * - ::PCPS_GET_REF_OFFS<br> * ::PCPS_SET_REF_OFFS<br> @@ -566,7 +571,7 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * reference time offset from %UTC for clocks * which can't determine the offset automatically, * e.g. from an IRIG input signal. - * ::_pcps_has_ref_offs() checks whether supported. + * ::_pcps_has_ref_offs checks whether supported. * * - ::PCPS_GET_OPT_INFO<br> * ::PCPS_SET_OPT_SETTINGS<br> @@ -578,7 +583,7 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * When writing, clocks accepts a ::MBG_OPT_SETTINGS * structure only which contain the desired settings * of the supported flags only. - * ::_pcps_has_opt_flags() checks whether supported. + * ::_pcps_has_opt_flags checks whether supported. * * - ::PCPS_GET_IRIG_RX_INFO<br> * ::PCPS_SET_IRIG_RX_SETTINGS<br> @@ -591,7 +596,7 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * plus the current settings.<br> * When writing, clocks accepts an ::IRIG_SETTINGS * structure only which contain the desired settings - * only. ::_pcps_is_irig_rx() and ::_pcps_has_irig_tx() + * only. ::_pcps_is_irig_rx and ::_pcps_has_irig_tx * check whether supported. * * - ::PCPS_GET_IRIG_CTRL_BITS<br> @@ -602,7 +607,7 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * the IRIG frame type and the configuration of the IRIG generator. * So these bits are returned as-is and must be interpreted * by the application. - * ::_pcps_has_irig_ctrl_bits() checks whether supported. + * ::_pcps_has_irig_ctrl_bits checks whether supported. * * - ::PCPS_GET_SYNTH<br> * ::PCPS_SET_SYNTH<br> @@ -612,7 +617,7 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * status. The commands are only supported if the board * supports the ::RECEIVER_INFO structure and the flag * #GPS_HAS_SYNTH is set in the ::RECEIVER_INFO::features. - * ::_pcps_has_synth() checks whether supported. + * ::_pcps_has_synth checks whether supported. * The structures ::SYNTH and ::SYNTH_STATE used with these * commands are defined in gpsdefs.h. * @@ -627,30 +632,30 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * - ::PCPS_GIVE_SERNUM<br> * Returns ::PCPS_FIFO_SIZE characters of the * clock's serial number. - * ::_pcps_has_sernum() checks whether supported. + * ::_pcps_has_sernum checks whether supported. * * - ::PCPS_GENERIC_IO<br> * Generic I/O read and write. Can be used to query * specific data, e.g. a selected element of an array. - * ::_pcps_has_generic_io() checks whether supported. + * ::_pcps_has_generic_io checks whether supported. * * - ::PCPS_GET_DEBUG_STATUS<br> * This command reads an ::MBG_DEBUG_STATUS structure * which represents the internal status of the * IRIG decoder and some additional debug info. - * ::_pcps_has_debug_status() checks whether supported. + * ::_pcps_has_debug_status checks whether supported. * * - ::PCPS_READ_GPS_DATA<br> * ::PCPS_WRITE_GPS_DATA<br> * These commands are used by the functions - * ::pcps_read_gps() and ::pcps_write_gps() + * ::pcps_read_gps and ::pcps_write_gps * to read or write large data structures to * Meinberg GPS plug-in clocks. - * ::_pcps_is_gps() checks whether supported. + * ::_pcps_is_gps checks whether supported. * * - ::PCPS_CLR_UCAP_BUFF<br> * Clear a clock's time capture buffer. - * ::_pcps_can_clr_ucap_buff() checks whether + * ::_pcps_can_clr_ucap_buff checks whether * supported. * * - ::PCPS_GIVE_UCAP_ENTRIES<br> @@ -658,41 +663,41 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * reports the max number of entries and the * currently used number of entries in the * user capture buffer. - * ::_pcps_has_ucap() checks whether supported. + * ::_pcps_has_ucap checks whether supported. * * - ::PCPS_GIVE_UCAP_EVENT<br> * Read capture events using a PCPS_HR_TIME * structure. This is faster than reading using the * GPS command ::PC_GPS_UCAP. If no capture event is * available then the returned structure is all 0. - * ::_pcps_has_ucap() checks whether supported. + * ::_pcps_has_ucap checks whether supported. * * - ::PCPS_GET_CORR_INFO<br> * Read PZF correlation info using a ::CORR_INFO * structure. - * ::_pcps_has_pzf() checks whether supported. + * ::_pcps_has_pzf checks whether supported. * * - ::PCPS_GET_TR_DISTANCE<br> * ::PCPS_SET_TR_DISTANCE<br> * Read or write distance from the RF transmitter. * This is used to compensate the RF propagation delay * for PZF receivers. - * ::_pcps_has_tr_distance() checks whether supported. + * ::_pcps_has_tr_distance checks whether supported. * * - ::PCPS_CLR_EVT_LOG<br> * Clear on-board event log. - * ::_pcps_has_evt_log() checks whether supported. + * ::_pcps_has_evt_log checks whether supported. * * - ::PCPS_NUM_EVT_LOG_ENTRIES<br> * Read max. number of num event log entries which can * be saved on the board, and how many entries have currently * been saved. - * ::_pcps_has_evt_log() checks whether supported. + * ::_pcps_has_evt_log checks whether supported. * * - ::PCPS_FIRST_EVT_LOG_ENTRY<br> * ::PCPS_NEXT_EVT_LOG_ENTRY<br> * Read first (oldest) or next event log entry. - * ::_pcps_has_evt_log() checks whether supported. + * ::_pcps_has_evt_log checks whether supported. * * - ::PCPS_FORCE_RESET<br> * Resets the card's hardware. This may lock up the computer @@ -702,13 +707,13 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS #define PCPS_GIVE_TIME 0x00 ///< (r-) Read current time in ::PCPS_TIME format #define PCPS_GIVE_TIME_NOCLEAR 0x01 ///< (r-) Read current time in ::PCPS_TIME format, don't clear sec and min flags (deprecated) -#define PCPS_GIVE_SYNC_TIME 0x02 ///< (r-) Read last sync time as ::PCPS_TIME, only if ::_pcps_has_sync_time() -#define PCPS_GIVE_HR_TIME 0x03 ///< (r-) Read high res. time as ::PCPS_HR_TIME, only if ::_pcps_has_hr_time() -#define PCPS_GIVE_IRIG_TIME 0x04 ///< (r-) Read raw IRIG time as ::PCPS_IRIG_TIME, only if ::_pcps_has_irig_time() +#define PCPS_GIVE_SYNC_TIME 0x02 ///< (r-) Read last sync time as ::PCPS_TIME, only if ::_pcps_has_sync_time +#define PCPS_GIVE_HR_TIME 0x03 ///< (r-) Read high res. time as ::PCPS_HR_TIME, only if ::_pcps_has_hr_time +#define PCPS_GIVE_IRIG_TIME 0x04 ///< (r-) Read raw IRIG time as ::PCPS_IRIG_TIME, only if ::_pcps_has_irig_time #define PCPS_SET_TIME 0x10 ///< (-w) Set on-board time, see ::PCPS_STIME. Returns ::MBG_ERR_STIME on error. -#define PCPS_SET_EVENT_TIME 0x14 ///< (-w) Write event time as ::PCPS_TIME_STAMP, only if ::_pcps_has_event_time() +#define PCPS_SET_EVENT_TIME 0x14 ///< (-w) Write event time as ::PCPS_TIME_STAMP, only if ::_pcps_has_event_time #define PCPS_IRQ_NONE 0x20 ///< (-w) Disable IRQs #define PCPS_IRQ_1_SEC 0x21 ///< (-w) Enable IRQ per 1 second @@ -719,55 +724,55 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS #define PCPS_GET_SERIAL 0x30 ///< (r-) Read serial settings as ::PCPS_SERIAL, deprecated by ::PC_GPS_ALL_PORT_INFO #define PCPS_SET_SERIAL 0x31 ///< (-w) Write serial settings as ::PCPS_SERIAL, deprecated by ::PC_GPS_PORT_SETTINGS_IDX, returns ::MBG_ERR_CFG on error -#define PCPS_GET_TZCODE 0x32 ///< (r-) Read ::PCPS_TZCODE, only if ::_pcps_has_tzcode() -#define PCPS_SET_TZCODE 0x33 ///< (-w) Write ::PCPS_TZCODE, only if ::_pcps_has_tzcode(), returns ::MBG_ERR_CFG on error +#define PCPS_GET_TZCODE 0x32 ///< (r-) Read ::PCPS_TZCODE, only if ::_pcps_has_tzcode +#define PCPS_SET_TZCODE 0x33 ///< (-w) Write ::PCPS_TZCODE, only if ::_pcps_has_tzcode, returns ::MBG_ERR_CFG on error -#define PCPS_GET_PCPS_TZDL 0x34 ///< (r-) Read ::PCPS_TZDL, only if ::_pcps_has_pcps_tzdl() -#define PCPS_SET_PCPS_TZDL 0x35 ///< (-w) Write ::PCPS_TZDL, only if ::_pcps_has_pcps_tzdl(), returns ::MBG_ERR_CFG on error +#define PCPS_GET_PCPS_TZDL 0x34 ///< (r-) Read ::PCPS_TZDL, only if ::_pcps_has_pcps_tzdl +#define PCPS_SET_PCPS_TZDL 0x35 ///< (-w) Write ::PCPS_TZDL, only if ::_pcps_has_pcps_tzdl, returns ::MBG_ERR_CFG on error -#define PCPS_GET_REF_OFFS 0x36 ///< (r-) Read ::MBG_REF_OFFS, only if ::_pcps_has_ref_offs() -#define PCPS_SET_REF_OFFS 0x37 ///< (-w) Write ::MBG_REF_OFFS, only if ::_pcps_has_ref_offs(), returns ::MBG_ERR_CFG on error +#define PCPS_GET_REF_OFFS 0x36 ///< (r-) Read ::MBG_REF_OFFS, only if ::_pcps_has_ref_offs +#define PCPS_SET_REF_OFFS 0x37 ///< (-w) Write ::MBG_REF_OFFS, only if ::_pcps_has_ref_offs, returns ::MBG_ERR_CFG on error -#define PCPS_GET_OPT_INFO 0x38 ///< (r-) Read ::MBG_OPT_INFO, only if ::_pcps_has_opt_flags() -#define PCPS_SET_OPT_SETTINGS 0x39 ///< (-w) Write ::MBG_OPT_SETTINGS, only if ::_pcps_has_opt_flags(), returns ::MBG_ERR_CFG on error +#define PCPS_GET_OPT_INFO 0x38 ///< (r-) Read ::MBG_OPT_INFO, only if ::_pcps_has_opt_flags +#define PCPS_SET_OPT_SETTINGS 0x39 ///< (-w) Write ::MBG_OPT_SETTINGS, only if ::_pcps_has_opt_flags, returns ::MBG_ERR_CFG on error -#define PCPS_GET_IRIG_RX_INFO 0x3A ///< (r-) Read ::IRIG_INFO, only if ::_pcps_is_irig_rx() -#define PCPS_SET_IRIG_RX_SETTINGS 0x3B ///< (-w) Write ::IRIG_SETTINGS, only if ::_pcps_is_irig_rx(), returns ::MBG_ERR_CFG on error +#define PCPS_GET_IRIG_RX_INFO 0x3A ///< (r-) Read ::IRIG_INFO, only if ::_pcps_is_irig_rx +#define PCPS_SET_IRIG_RX_SETTINGS 0x3B ///< (-w) Write ::IRIG_SETTINGS, only if ::_pcps_is_irig_rx, returns ::MBG_ERR_CFG on error -#define PCPS_GET_IRIG_TX_INFO 0x3C ///< (r-) Read ::IRIG_INFO, only if ::_pcps_has_irig_tx() -#define PCPS_SET_IRIG_TX_SETTINGS 0x3D ///< (-w) Write ::IRIG_SETTINGS, only if ::_pcps_has_irig_tx(), returns ::MBG_ERR_CFG on error +#define PCPS_GET_IRIG_TX_INFO 0x3C ///< (r-) Read ::IRIG_INFO, only if ::_pcps_has_irig_tx +#define PCPS_SET_IRIG_TX_SETTINGS 0x3D ///< (-w) Write ::IRIG_SETTINGS, only if ::_pcps_has_irig_tx, returns ::MBG_ERR_CFG on error -#define PCPS_GET_SYNTH 0x3E ///< (r-) Read ::SYNTH, only if ::_pcps_has_synth() -#define PCPS_SET_SYNTH 0x3F ///< (-w) Write ::SYNTH, only if ::_pcps_has_synth(), returns ::MBG_ERR_CFG on error +#define PCPS_GET_SYNTH 0x3E ///< (r-) Read ::SYNTH, only if ::_pcps_has_synth +#define PCPS_SET_SYNTH 0x3F ///< (-w) Write ::SYNTH, only if ::_pcps_has_synth, returns ::MBG_ERR_CFG on error #define PCPS_GIVE_FW_ID_1 0x40 ///< (r-) Read first ::PCPS_FIFO_SIZE chars of firmware ID #define PCPS_GIVE_FW_ID_2 0x41 ///< (r-) Read last ::PCPS_FIFO_SIZE chars of firmware ID -#define PCPS_GIVE_SERNUM 0x42 ///< (r-) Read serial number as ::PCPS_SN_STR, only if _pcps_has_sernum() -#define PCPS_GENERIC_IO 0x43 ///< (rw) See ::pcps_generic_io() or ::_mbgdevio_gen_io() -#define PCPS_GET_SYNTH_STATE 0x44 ///< (r-) Read ::SYNTH_STATE, only if ::_pcps_has_synth() -#define PCPS_GET_IRIG_CTRL_BITS 0x45 ///< (r-) Read ::MBG_IRIG_CTRL_BITS, only if ::_pcps_has_irig_ctrl_bits() -#define PCPS_GET_RAW_IRIG_DATA 0x46 ///< (r-) Read ::MBG_RAW_IRIG_DATA, only if ::_pcps_has_raw_irig_data() +#define PCPS_GIVE_SERNUM 0x42 ///< (r-) Read serial number as ::PCPS_SN_STR, only if ::_pcps_has_sernum +#define PCPS_GENERIC_IO 0x43 ///< (rw) See ::pcps_generic_io or ::_mbgdevio_gen_io +#define PCPS_GET_SYNTH_STATE 0x44 ///< (r-) Read ::SYNTH_STATE, only if ::_pcps_has_synth +#define PCPS_GET_IRIG_CTRL_BITS 0x45 ///< (r-) Read ::MBG_IRIG_CTRL_BITS, only if ::_pcps_has_irig_ctrl_bits +#define PCPS_GET_RAW_IRIG_DATA 0x46 ///< (r-) Read ::MBG_RAW_IRIG_DATA, only if ::_pcps_has_raw_irig_data #define PCPS_GET_STATUS_PORT 0x4B ///< (r-) Read ::PCPS_STATUS_PORT -#define PCPS_GET_DEBUG_STATUS 0x4C ///< (r-) Read ::MBG_DEBUG_STATUS, only if ::_pcps_has_debug_status() +#define PCPS_GET_DEBUG_STATUS 0x4C ///< (r-) Read ::MBG_DEBUG_STATUS, only if ::_pcps_has_debug_status /// @note Command codes 0x4D, 0x4E, and 0x4F are reserved. #define PCPS_READ_GPS_DATA 0x50 ///< (r-) Read large data structure, see ::PC_GPS_CMD_CODES #define PCPS_WRITE_GPS_DATA 0x51 ///< (-w) Write large data structure, see ::PC_GPS_CMD_CODES -#define PCPS_CLR_UCAP_BUFF 0x60 ///< (-w) No param., clear on-board capture FIFO, only if ::_pcps_has_ucap() -#define PCPS_GIVE_UCAP_ENTRIES 0x61 ///< (r-) Read ::PCPS_UCAP_ENTRIES, only if ::_pcps_has_ucap() -#define PCPS_GIVE_UCAP_EVENT 0x62 ///< (r-) Return oldest event as ::PCPS_HR_TIME, only if ::_pcps_has_ucap() +#define PCPS_CLR_UCAP_BUFF 0x60 ///< (-w) No param., clear on-board capture FIFO, only if ::_pcps_has_ucap +#define PCPS_GIVE_UCAP_ENTRIES 0x61 ///< (r-) Read ::PCPS_UCAP_ENTRIES, only if ::_pcps_has_ucap +#define PCPS_GIVE_UCAP_EVENT 0x62 ///< (r-) Return oldest event as ::PCPS_HR_TIME, only if ::_pcps_has_ucap -#define PCPS_GET_CORR_INFO 0x63 ///< (r-) Read ::CORR_INFO structure, only if ::_pcps_has_pzf() -#define PCPS_GET_TR_DISTANCE 0x64 ///< (r-) Read ::TR_DISTANCE, only if ::_pcps_has_tr_distance() -#define PCPS_SET_TR_DISTANCE 0x65 ///< (-w) Write ::TR_DISTANCE, only if ::_pcps_has_tr_distance() +#define PCPS_GET_CORR_INFO 0x63 ///< (r-) Read ::CORR_INFO structure, only if ::_pcps_has_pzf +#define PCPS_GET_TR_DISTANCE 0x64 ///< (r-) Read ::TR_DISTANCE, only if ::_pcps_has_tr_distance +#define PCPS_SET_TR_DISTANCE 0x65 ///< (-w) Write ::TR_DISTANCE, only if ::_pcps_has_tr_distance -#define PCPS_CLR_EVT_LOG 0x66 ///< (-w) Write clear on-board event log, only if ::_pcps_has_evt_log() -#define PCPS_NUM_EVT_LOG_ENTRIES 0x67 ///< (r-) Read ::MBG_NUM_EVT_LOG_ENTRIES, only if ::_pcps_has_evt_log() -#define PCPS_FIRST_EVT_LOG_ENTRY 0x68 ///< (r-) Read first (oldest) ::MBG_EVT_LOG_ENTRY, only if ::_pcps_has_evt_log() -#define PCPS_NEXT_EVT_LOG_ENTRY 0x69 ///< (r-) Read next ::MBG_EVT_LOG_ENTRY, only if ::_pcps_has_evt_log() +#define PCPS_CLR_EVT_LOG 0x66 ///< (-w) Write clear on-board event log, only if ::_pcps_has_evt_log +#define PCPS_NUM_EVT_LOG_ENTRIES 0x67 ///< (r-) Read ::MBG_NUM_EVT_LOG_ENTRIES, only if ::_pcps_has_evt_log +#define PCPS_FIRST_EVT_LOG_ENTRY 0x68 ///< (r-) Read first (oldest) ::MBG_EVT_LOG_ENTRY, only if ::_pcps_has_evt_log +#define PCPS_NEXT_EVT_LOG_ENTRY 0x69 ///< (r-) Read next ::MBG_EVT_LOG_ENTRY, only if ::_pcps_has_evt_log #define PCPS_FORCE_RESET 0x80 ///< (-w) No param., reset the device (deprecated, this can lock up the computer!!) @@ -916,26 +921,91 @@ typedef char PCPS_ID_STR[PCPS_ID_SIZE]; typedef char PCPS_SN_STR[PCPS_SN_SIZE]; +/** + * @brief Seconds since epoch 1970-01-01, usually %UTC scale + * + * Used with ::PCPS_TIME_STAMP. + * + * @see ::PCPS_FRAC_32 + * @see ::PCPS_TIME_STAMP + */ +typedef uint32_t PCPS_SECONDS; + +#define _mbg_swab_pcps_seconds( _p ) \ +do \ +{ \ + _mbg_swab32( _p ); \ +} while ( 0 ) + + + +/** + * @brief 32 bit binary fraction of a second + * + * Used with ::PCPS_TIME_STAMP, e.g. + * 0x80000000 == 0.5 s, 0xFFFFFFFF == 0.9999999.. s, etc. + * Use ::bin_frac_32_to_dec_frac for conversion. + * + * @see ::bin_frac_32_to_dec_frac + * @see ::PCPS_SECONDS + * @see ::PCPS_TIME_STAMP + * @see ::PCPS_HRT_FRAC_SCALE + * @see ::PCPS_HRT_FRAC_SCALE_FMT + */ +typedef uint32_t PCPS_FRAC_32; + +#define _mbg_swab_pcps_frac_32( _p ) \ +do \ +{ \ + _mbg_swab32( _p ); \ +} while ( 0 ) + + /** * @brief A high resolution time stamp */ typedef struct { - uint32_t sec; ///< seconds since 1970, usually %UTC scale - uint32_t frac; ///< binary fractions of second (0x80000000 == 0.5 s, 0xFFFFFFFF == 0.9999999.. s) + PCPS_SECONDS sec; ///< seconds since 1970, usually %UTC scale + PCPS_FRAC_32 frac; ///< binary fractions of second, see ::PCPS_FRAC_32 } PCPS_TIME_STAMP; -#define _mbg_swab_pcps_time_stamp( _p ) \ -do \ -{ \ - _mbg_swab32( &(_p)->sec ); \ - _mbg_swab32( &(_p)->frac ); \ +#define _mbg_swab_pcps_time_stamp( _p ) \ +do \ +{ \ + _mbg_swab_pcps_seconds( &(_p)->sec ); \ + _mbg_swab_pcps_frac_32( &(_p)->frac ); \ } while ( 0 ) +#ifndef PCPS_HRT_FRAC_SCALE + /** + * @brief Scale to be used to print ::PCPS_TIME_STAMP::frac values + * + * The function ::frac_sec_from_bin can be used for the conversion. + * + * @see ::PCPS_HRT_FRAC_SCALE_FMT + */ + #define PCPS_HRT_FRAC_SCALE 10000000UL +#endif + +#ifndef PCPS_HRT_FRAC_SCALE_FMT + /** + * @brief Format specifier used to print ::PCPS_TIME_STAMP::frac values + * + * Used to print values scaled with ::frac_sec_from_bin called + * with ::PCPS_HRT_FRAC_SCALE. + * + * @see ::PCPS_HRT_FRAC_SCALE + */ + #define PCPS_HRT_FRAC_SCALE_FMT "%07lu" +#endif + + + /** * @brief Extended status code * @@ -1261,7 +1331,7 @@ enum PCPS_TIME_STATUS_FLAGS_EXT * shifted to the right position. ::PCPS_GET_SERIAL expects that parameter * byte and ::PCPS_GET_SERIAL returns the current configuration from * the board. - * _pcps_has_serial() checks whether supported. + * ::_pcps_has_serial checks whether supported. * For old GPS clocks refer to the comments for the ::PCPS_GET_SERIAL * command. */ @@ -1363,7 +1433,7 @@ typedef uint8_t PCPS_TZCODE; */ enum PCPS_TZCODES { - PCPS_TZCODE_CET_CEST, ///< default as broadcasted by DCF77 (UTC+1h/UTC+2h) + PCPS_TZCODE_CET_CEST, ///< default as broadcast by DCF77 (UTC+1h/UTC+2h) PCPS_TZCODE_CET, ///< always CET (UTC+1h), discard DST PCPS_TZCODE_UTC, ///< always %UTC PCPS_TZCODE_EET_EEST, ///< East European Time, CET/CEST + 1h @@ -1718,8 +1788,6 @@ typedef uint16_t PCPS_CMD_INFO; #undef _USING_BYTE_ALIGNMENT #endif -#define _PCPSDEFS_H_INCLUDED - /* End of header body */ #endif /* _PCPSDEFS_H */ diff --git a/mbglib/common/pcpsdev.h b/mbglib/common/pcpsdev.h index ded733d..75260db 100755 --- a/mbglib/common/pcpsdev.h +++ b/mbglib/common/pcpsdev.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsdev.h 1.55 2017/04/25 11:36:40 martin TEST $ + * $Id: pcpsdev.h 1.56 2017/07/04 16:31:08 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -17,6 +17,12 @@ * * ----------------------------------------------------------------------- * $Log: pcpsdev.h $ + * Revision 1.56 2017/07/04 16:31:08 martin + * New types PCPS_CLOCK_NAME and MBG_DEV_NAME. + * Definitions used with new feature check implementation. + * Changed some macros and definitions to clean up + * I/O port usage and storage. + * Moved some definitions used with IOCTLs to mbgioctl.h. * Revision 1.55 2017/04/25 11:36:40 martin * Renamed GRC181PEX to GNS181PEX. * Revision 1.54 2017/01/27 09:10:57 martin @@ -404,6 +410,13 @@ do \ +/** + * @defgroup group_bus_flag_masks BUS flag masks + * + * @anchor PCPS_BUS_FLAG_MASKS + * + * @{ */ + // The following flags describe the bus types which are // supported by the plugin clocks. #define PCPS_BUS_ISA 0x0001 ///< IBM compatible PC/AT ISA bus @@ -439,6 +452,8 @@ do \ // The constant below combines the PCI bus flags: #define PCPS_BUS_USB_V2 ( PCPS_BUS_USB | PCPS_BUS_USB_FLAG_V2 ) +/** @} defgroup group_bus_flag_masks */ + /** @@ -488,6 +503,8 @@ enum PCPS_TYPES #define PCPS_CLOCK_NAME_SZ 10 // including terminating 0 +typedef char PCPS_CLOCK_NAME[PCPS_CLOCK_NAME_SZ]; + typedef uint16_t PCPS_DEV_ID; typedef uint16_t PCPS_REF_TYPE; typedef uint16_t PCPS_BUS_FLAGS; @@ -502,33 +519,43 @@ typedef uint16_t PCPS_BUS_FLAGS; */ typedef struct { - uint16_t num; - char name[PCPS_CLOCK_NAME_SZ]; - PCPS_DEV_ID dev_id; - PCPS_REF_TYPE ref_type; - PCPS_BUS_FLAGS bus_flags; + uint16_t num; ///< see ::PCPS_TYPES + PCPS_CLOCK_NAME name; + PCPS_DEV_ID dev_id; ///< see @ref MEINBERG_PCI_DEVICE_IDS and @ref MBG_USB_DEVICE_IDS + PCPS_REF_TYPE ref_type; ///< see ::PCPS_REF_TYPES + PCPS_BUS_FLAGS bus_flags; ///< see @ref PCPS_BUS_FLAG_MASKS } PCPS_DEV_TYPE; -#if !defined( MBG_TGT_POSIX ) || defined( MBG_ARCH_X86 ) - typedef uint16_t PCPS_PORT_ADDR; -#else - typedef uint64_t PCPS_PORT_ADDR; -#endif - +/** + * @brief Legacy I/O address type, see ::PCPS_SHORT_PORT_RSRC + */ +typedef uint16_t PCPS_SHORT_PORT_ADDR; /** * @brief An I/O port resource used by a device + * + * This structure has originally been used to store information + * on an I/O address range. + * However, the 16 bits provided by ::PCPS_SHORT_PORT_ADDR may + * not be sufficient to hold an address on some target platforms, + * so this is only kept to maintain API compatibility when + * reporting I/O addresses to user space via ::PCPS_DEV_CFG + * and thus ::PCPS_DEV structures. + * A different structure is actually being used internally + * by the kernel drivers. */ typedef struct { - PCPS_PORT_ADDR base; + PCPS_SHORT_PORT_ADDR base; uint16_t num; -} PCPS_PORT_RSRC; +} PCPS_SHORT_PORT_RSRC; + + /** * @brief The max. number of I/O port resources used by a clock @@ -569,8 +596,8 @@ typedef struct PCPS_ERR_FLAGS err_flags; ///< See @ref PCPS_ERR_FLAG_MASKS PCPS_BUS_NUM bus_num; PCPS_SLOT_NUM slot_num; - PCPS_PORT_RSRC port[N_PCPS_PORT_RSRC]; - uint16_t status_port; + PCPS_SHORT_PORT_RSRC port[N_PCPS_PORT_RSRC]; + PCPS_SHORT_PORT_ADDR short_status_port; int16_t irq_num; uint32_t timeout_clk; PCPS_FW_REV_NUM fw_rev_num; @@ -1004,6 +1031,13 @@ typedef struct } PCPS_DEV; +#if 1 || defined( MBG_TGT_KERNEL ) //### FIXME + #define _USE_DEV_MACROS 1 +#else + #define _USE_DEV_MACROS 0 +#endif + + // The macros below simplify access to the data // stored in PCPS_DEV structure and should be used // to extract the desired information. @@ -1051,12 +1085,11 @@ typedef struct #define _pcps_bus_num( _d ) ( (_d)->cfg.bus_num ) #define _pcps_slot_num( _d ) ( (_d)->cfg.slot_num ) -#define _pcps_cfg_port_rsrc( _c, _n ) ( (_c)->port[_n] ) -#define _pcps_port_rsrc( _d, _n ) _pcps_cfg_port_rsrc( &(_d)->cfg, (_n) ) -#define _pcps_port_rsrc_unused( _d ) ( (_d)->base == 0 || (_d)->num == 0 ) +#define _pcps_cfg_short_port_rsrc( _c, _n ) ( (_c)->port[_n] ) +#define _pcps_short_port_rsrc( _d, _n ) _pcps_cfg_short_port_rsrc( &(_d)->cfg, (_n) ) -#define _pcps_cfg_port_base( _c, _n ) ( _pcps_cfg_port_rsrc( (_c), (_n) ).base ) -#define _pcps_port_base( _d, _n ) ( _pcps_port_rsrc( (_d), (_n) ).base ) +#define _pcps_cfg_short_port_base( _c, _n ) ( _pcps_cfg_short_port_rsrc( (_c), (_n) ).base ) +#define _pcps_short_port_base( _d, _n ) ( _pcps_short_port_rsrc( (_d), (_n) ).base ) #define _pcps_cfg_irq_num( _c ) ( (_c)->irq_num ) #define _pcps_irq_num( _d ) _pcps_cfg_irq_num( &(_d)->cfg ) @@ -1077,13 +1110,18 @@ typedef struct #define _pcps_clr_err_flags( _d, _msk ) ( _pcps_err_flags( _d ) &= ~(_msk) ) +#if _USE_DEV_MACROS + /// Check whether a special feature is supported #define _pcps_has_feature( _d, _f ) ( ( (_d)->cfg.features & (_f) ) != 0 ) /// Check whether a special feature is supported according to ::RECEIVER_INFO #define _pcps_has_ri_feature( _p_ri, _f ) ( ( (_p_ri)->features & (_f) ) != 0 ) -#define _ri_addr( _p ) &(_p)->xdev_features.receiver_info +#define _ri_addr( _p ) &(_p)->xdev_features.receiver_info +#define _xfeat_addr( _p ) &(_p)->xdev_features.xfeature_buffer +#define _tlv_info_addr( _p ) &(_p)->xdev_features.tlv_info + #define _pcps_can_set_time( _d ) _pcps_has_feature( (_d), PCPS_CAN_SET_TIME ) #define _pcps_has_serial( _d ) _pcps_has_feature( (_d), PCPS_HAS_SERIAL ) @@ -1196,6 +1234,7 @@ typedef struct _pcps_has_ri_feature( (_p_ri), GPS_HAS_XMRS_MULT_INSTC ) ) //### TODO should also check GPS_MODEL_HAS_XMR_HOLDOVER_INTV, which is a builtin feature flag only +#endif // _USE_DEV_MACROS // There are some versions of IRIG receiver cards which ignore the TFOM code @@ -1218,16 +1257,16 @@ typedef struct // PCI bridge built into the chip. Unfortunately there are some mainboards out there // which do not handle PCI resources behind this PCI bridge correctly. The symptom is // usually that both I/O address ranges of these cards get the same base address -// assigned by the BIOS, and the efeect is that in this case a card is not accessible +// assigned by the BIOS, and the effect is that in this case a card is not accessible // properly, since both I/O ranges try to respond to the same I/O addresses. -// As a consequence data read from the card is usually garbage. +// As a consequence, data read from the card is usually garbage. // The only known fix for this is a BIOS update for the mainboard which makes the // BIOS handle the card's resources properly. // The macro below can be used to test if both port base addresses assigned to a card // are identical, and thus the BIOS is probably faulty:: #define _pcps_pci_cfg_err( _d ) \ - ( _pcps_is_pci( _d ) && ( _pcps_port_base( _d, 1 ) == _pcps_port_base( _d, 0 ) ) ) + ( _pcps_is_pci( _d ) && ( _pcps_short_port_base( _d, 1 ) == _pcps_short_port_base( _d, 0 ) ) ) @@ -1248,6 +1287,22 @@ typedef struct /** + * @brief Codes used with ::IOCTL_DEV_FEAT_REQ::feat_req_type + */ +enum DEV_FEAT_REQ_TYPES +{ + DEV_FEAT_REQ_TYPE_BUILTIN, ///< feat_num field contains one of the ::GPS_BUILTIN_FEATURE_BITS + DEV_FEAT_REQ_TYPE_REF_TYPE, ///< feat_num field contains one of the ::PCPS_REF_TYPES + DEV_FEAT_REQ_TYPE_PCPS, ///< feat_num field contains one of the ::PCPS_FEATURE_BITS + DEV_FEAT_REQ_TYPE_RI, ///< feat_num field contains one of the ::GPS_FEATURE_BITS + DEV_FEAT_REQ_TYPE_XFEAT, ///< feat_num field contains one of the ::MBG_XFEATURE_BITS + DEV_FEAT_REQ_TYPE_TLV_FEAT, ///< feat_num field contains one of the ::MBG_TLV_FEAT_TYPES + N_DEV_FEAT_REQ_TYPES +}; + + + +/** * @brief Device driver information * * Used to pass info on the device driver to @@ -1384,6 +1439,13 @@ do \ +/** + * @defgroup group_irq_stat_info IRQ status information + * + * @anchor PCPS_IRQ_STAT_INFO_DEFS + * + * @{ */ + typedef uint32_t PCPS_IRQ_STAT_INFO; // Flags used with PCPS_IRQ_STAT_INFO: @@ -1393,6 +1455,10 @@ typedef uint32_t PCPS_IRQ_STAT_INFO; #define PCPS_IRQ_STATE_DANGER ( PCPS_IRQ_STAT_ENABLED | PCPS_IRQ_STAT_UNSAFE ) +/** @} defgroup group_irq_stat_info */ + + + #define _pcps_fw_rev_num_major( _v ) \ ( ( (_v) >> 8 ) & 0xFF ) @@ -1406,87 +1472,6 @@ typedef uint32_t PCPS_IRQ_STAT_INFO; #endif -// We must use native alignment here! - -// The structure below is used by the IOCTL_PCPS_GENERIC_... calls. - -#if defined( MBG_TGT_LINUX ) - #if defined( MBG_ARCH_ARM ) || defined( MBG_ARCH_SPARC ) - #define USE_IOCTL_GENERIC_REQ 0 - #endif -#endif - -#if defined( MBG_TGT_WIN32 ) - // required for 32bit/64 bit compatibility - #define USE_IOCTL_GENERIC_REQ 0 -#endif - -#if !defined( USE_IOCTL_GENERIC_REQ ) - #define USE_IOCTL_GENERIC_REQ 1 -#endif - - -#if USE_IOCTL_GENERIC_REQ - -/** - * @brief A structure used to pass generic IOCTL requests to the kernel driver - * - * @note This does not work properly under Linux/Sparc where the kernel - * may be 64 bit while user space is 32 bit, which leads to different sizes - * for pointers, size_t, etc. - */ -typedef struct -{ - ulong info; - const void *in_p; - size_t in_sz; - void *out_p; - size_t out_sz; - -} IOCTL_GENERIC_REQ; - -#define _MBG_IOG( _t, _n, _s ) _MBG_IOW( _t, _n, _s ) - -#else - -/** - * @brief Control structure used for generic IOCTL requests - * - * Used by the IOCTL_PCPS_GENERIC_... calls. - * - * @note Is slower, but avoids OS-specific problems occurring - * with IOCTL_GENERIC_REQ. - */ -typedef struct -{ - uint32_t info; - uint32_t data_size_in; - uint32_t data_size_out; - -} IOCTL_GENERIC_CTL; - - -/** - * @brief Data buffer used for generic IOCTL requests - * - * Used by the IOCTL_PCPS_GENERIC_... calls. - * - * @note Is slower, but avoids OS-specific problems occurring - * with IOCTL_GENERIC_REQ. - */ -typedef struct -{ - IOCTL_GENERIC_CTL ctl; - uint8_t data[1]; - -} IOCTL_GENERIC_BUFFER; - -#define _MBG_IOG( _t, _n, _s ) _MBG_IO( _t, _n ) - -#endif - - - #if !defined( MBG_TGT_KERNEL ) static __mbg_inline @@ -1503,6 +1488,20 @@ void setup_hr_time_cycles_from_timestamp_cycles( PCPS_HR_TIME_CYCLES *p_ht_c, #endif + +/** + * @brief A string buffer for a unique device ID + * + * The unique ID is made up of the device model name + * and its serial number, i.e. [model_name]_[serial_number] + * E.g.: "GPS170PCI_028210040670" + * + * @see ::snprint_dev_name + */ +typedef char MBG_DEV_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; + + + /* End of header body */ #undef _ext diff --git a/mbglib/common/pcpsdrvr.c b/mbglib/common/pcpsdrvr.c index 581bb07..fd6df88 100755 --- a/mbglib/common/pcpsdrvr.c +++ b/mbglib/common/pcpsdrvr.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsdrvr.c 1.51.1.38 2017/05/05 14:38:35 martin TEST $ + * $Id: pcpsdrvr.c 1.52 2017/07/04 16:45:36 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -32,8 +32,9 @@ * MCA bus: PS31 * ISA bus: PC31, PC32, GPS167PC * - * USB is not supported for some target environments, mainly because - * those operating systems don't provide full USB support. + * USB is not supported for all target environments, eventually + * because an operating systems doesn't provide full USB support, + * or USB support hasn't yet been implemented. * * PCI support is possible in two different ways. The preferred * functions are compiled in if one of the symbols _PCPS_USE_PCI_PNP @@ -42,12 +43,12 @@ * If _PCPS_USE_PCI_PNP is != 0 it is assumed that the operating * system's PCI layer detects a new PCI device and calls a driver's * add_device()/start_device() function to initialize the device. - * This new technique is supported with PNP operating systems - * (e.g. Win98, Win2K, newer Linux versions). + * This technique is supported with PNP operating systems + * (e.g. Windows versions after NT, Linux, *BSD). * * If _PCPS_USE_PCI_BIOS is != 0 the program scans the PCI bus * during startup to detect and initialize supported PCI devices. - * This techique is used with non-PNP operating systems. + * This techique is used with old non-PNP operating systems. * * The symbol _PCPS_USE_RSRCMGR must be defined != 0 to include * support of resource managers, if necessary. @@ -56,88 +57,38 @@ * detection (and therefore auto-detection of a MCA clock) is * supported. * - * MCA clocks are accessed using the same low level functions as - * ISA clocks, so if autodetection of MCA clocks is not supported - * then a MCA clock's known port number can be passed to - * pcps_detect_clocks() to let it be treated like an ISA clock. + * MCA devices are accessed using the same low level functions as + * ISA devices, so if autodetection of MCA clocks is not supported + * then a MCA device's known port number can be passed to + * pcps_detect_devices() to let it be treated like an ISA device. * * ----------------------------------------------------------------------- * $Log: pcpsdrvr.c $ - * Revision 1.51.1.38 2017/05/05 14:38:35 martin - * Fixed some warnings from clang. - * Revision 1.51.1.37 2017/04/25 11:36:47 martin - * Renamed GRC181PEX to GNS181PEX. - * Revision 1.51.1.36 2017/04/19 13:55:58 martin + * Revision 1.52 2017/07/04 16:45:36 martin + * Support GPS180AMC and GNS181PEX. + * Renamed some functions: Use _device instead of _clock, + * pcps_start_device() is now called pcps_probe_device(), etc. + * Runtime support for forcing I/O rather than MM access. * Increase MAX_BOOT_TIME_PTP270PEX from 27 to 40 seconds * to be safe in case a firmware update is applied at startup. - * Added some doxygen comments. - * Revision 1.51.1.35 2017/02/22 15:23:46 martin - * Fixed macro definition syntax to avoid clang compiler warnings. - * Revision 1.51.1.34 2017/02/22 11:32:12 martin - * Avoid 'redundant redeclaration' warning under FreeBSD 8.2. - * Revision 1.51.1.33 2017/02/10 15:27:45 martin * Fixed type of a register address. - * Revision 1.51.1.32 2016/09/26 16:23:22 martin - * Revision 1.51.1.31 2016/09/23 09:03:34Z martin - * *** empty log message *** - * Revision 1.51.1.30 2016/09/19 14:29:22 martin - * *** empty log message *** - * Revision 1.51.1.29 2016/09/16 09:57:43 martin - * Use macro _ri_addr(). - * Revision 1.51.1.28 2016/09/15 14:55:51 martin - * Support GRC181PEX. - * Revision 1.51.1.27 2016/09/14 16:21:42 martin - * Started code cleanup. - * Added doxygen comments. - * Revision 1.51.1.26 2016/09/13 10:12:08 martin - * Fixed some compiler warnings. - * Revision 1.51.1.25 2016/09/07 07:35:36Z martin - * Provided a driver name string for debug build on direct-access targets. - * Revision 1.51.1.24 2016/08/10 12:28:55 martin - * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. - * Revision 1.51.1.23 2016/08/09 16:01:43 martin - * Attribute always_inline is now in __mbg_inline. - * Revision 1.51.1.22 2016/08/09 07:12:57 martin - * *** empty log message *** - * Revision 1.51.1.21 2016/05/30 15:03:46 martin - * Conditional USB debug code. - * Revision 1.51.1.20 2016/04/06 13:54:37 martin - * *** empty log message *** - * Revision 1.51.1.19 2015/10/27 16:22:26 martin + * Cleaned up I/O port usage. * Older defines N_SUPP_DEV, PCPS_MAX_DDEVS, and MBG_MAX_DEVICES * have been obsoleted by new defines N_SUPP_DEV_BUS, N_SUPP_DEV_EXT, * and N_SUPP_DEV_TOTAL. - * Revision 1.51.1.18 2015/10/22 14:42:54 martin - * *** empty log message *** - * Revision 1.51.1.17 2015/09/18 14:54:24 martin - * Removed obsolete include file for FreeBSD. - * Revision 1.51.1.16 2015/09/15 09:16:04 martin - * Moved mbg_delta_sys_time_ms() to new module mbgsystm.c. - * Removed trailing white space. - * Revision 1.51.1.15 2014/10/30 16:03:10 martin - * Doxygen fixes. - * Revision 1.51.1.14 2014/10/29 10:32:13 martin - * Revision 1.51.1.13 2014/10/28 16:58:05 martin - * Revision 1.51.1.12 2014/05/26 16:03:00 martin - * Revision 1.51.1.11 2014/05/19 14:46:15 martin - * Fixed comment grammar. - * Revision 1.51.1.10 2014/04/17 08:38:12 martin * Fixed DEBUG build under *BSD. * Added DEBUG code dumping RECEIVER_INFO. - * Revision 1.51.1.9 2014/04/07 15:25:37 martin - * Started to rework Windows event logging. - * Revision 1.51.1.8 2014/04/07 10:35:25Z martin - * Revision 1.51.1.7 2014/04/07 09:56:45 martin - * Revision 1.51.1.6 2014/04/02 11:16:53 martin - * Revision 1.51.1.5 2014/03/20 16:40:25 martin - * Revision 1.51.1.4 2014/03/20 16:34:44 martin - * Runtime support for forcing I/O rather than MM access. - * Revision 1.51.1.3 2014/01/23 15:35:48 martin - * Support GPS180AMC. - * Revision 1.51.1.2 2013/12/16 10:45:52 martin + * Moved mbg_delta_sys_time_ms() to new module mbgsystm.c. + * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. + * Provided a driver name string for debug build on direct-access targets. + * Avoid 'redundant redeclaration' warning under FreeBSD 8.2. + * Fixed macro definition syntax to avoid clang compiler warnings. + * Fixed some other warnings from clang. + * Attribute always_inline is now in __mbg_inline. + * Conditional USB debug code. * Account for renamed symbols. - * Revision 1.51.1.1 2013/12/12 11:29:22 martin - * Doxygen stuff. + * Fixed typos, wording, and doxygen comments. + * Removed trailing white space. * Revision 1.51 2013/10/01 14:19:03 martin * Support GLN180PEX. * Revision 1.50 2013/03/15 10:01:58 martin @@ -612,7 +563,7 @@ * * @note Devices which support a configurable time scale do also * support reading/writing the GPS %UTC parameters via the PC bus. - * This is not explicitely coded in the ::RECEIVER_INFO::features + * This is not explicitly coded in the ::RECEIVER_INFO::features * since the the ::RECEIVER_INFO structure can also be read via * the serial port, and reading/writing the GPS %UTC parameters * via the serial port is supported by all GPS devices anyway. @@ -683,6 +634,9 @@ static const char *pcps_feature_names[N_PCPS_FEATURE_BITS] = PCPS_FEATURE_NAMES; static __mbg_inline /*HDR*/ +/** + * @brief Check if a device is a PTP270PEX card + */ int pcps_ddev_is_ptp270pex( const PCPS_DDEV *pddev ) { return _pcps_ddev_is_pci( pddev ) && @@ -703,7 +657,7 @@ static /*HDR*/ * @param[in] reg Number of the register to read * @param[out] pval Pointer to a variable to take the value read from the register * - * @return ::PCI_SUCCESS on success, or one of the PCI BIOS error codes + * @return ::PCI_SUCCESS on success, else one of the PCI BIOS error codes */ int mbg_plx_read_pecs_reg( struct pci_dev *pNode, uint16_t reg, uint32_t *pval ) @@ -764,7 +718,7 @@ static /*HDR*/ * 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 + * @param[in] pddev Pointer to the device structure * * @return true if the card can flag "ready" * @@ -874,7 +828,7 @@ static /*HDR*/ * have been called before to check if the card actually * supports this. * - * @param pddev The device to be checked + * @param[in] pddev Pointer to the device structure * * @return true if the card has flagged "ready" * @@ -907,7 +861,7 @@ static /*HDR*/ * * This is mainly used for debugging, and informational. * - * @param p_uptime The system uptime + * @param[in] p_uptime The system uptime * * @see ::wait_ptp270pex_ready * @see ::MAX_BOOT_TIME_PTP270PEX @@ -969,7 +923,7 @@ static /*HDR*/ * after it has finished booting. Otherwise the host system * may be locked up. * - * @param pddev The device to be checked + * @param[in] pddev Pointer to the device structure * * @see ::ptp270pex_can_flag_ready * @see ::ptp270pex_has_flagged_ready @@ -1070,7 +1024,10 @@ static /*HDR*/ * of IRQs was unsafe. Firmware upgrades are available to fix this. * See http://www.meinberg.de/english/info/pex-upgrades.htm * - * @param pddev The device to be checked + * @param[in] pddev Pointer to the device structure + * @param[in] req_fw_ver Required firmware version + * @param[in] req_asic_ver_major Required ASIC major version + * @param[in] req_asic_ver_minor Required ASIC major version * * @return true if IRQ operation is unsafe */ @@ -1100,7 +1057,14 @@ bool pcps_check_pex_irq_unsafe( PCPS_DDEV *pddev, uint16_t req_fw_ver, #if MBG_TGT_SUPP_MEM_ACC static __mbg_inline /*HDR*/ -int has_mapped_sys_virtual_address( PCPS_DDEV *pddev ) +/** + * @brief Check if a virtual address has been mapped for a device + * + * @param[in] pddev Pointer to the device structure + * + * @return true if virtual address has been mapped + */ +bool has_mapped_sys_virtual_address( PCPS_DDEV *pddev ) { return pddev->mm_addr != NULL; @@ -1109,6 +1073,13 @@ int has_mapped_sys_virtual_address( PCPS_DDEV *pddev ) static __mbg_inline /*HDR*/ +/** + * @brief Map a virtual address for a device + * + * @param[in] pddev Pointer to the device structure + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ int map_sys_virtual_address( PCPS_DDEV *pddev ) { pddev->mm_tstamp_addr = NULL; // unless configured below @@ -1151,19 +1122,24 @@ int map_sys_virtual_address( PCPS_DDEV *pddev ) if ( _pcps_ddev_is_pci_pex8311( pddev ) ) pddev->mm_tstamp_addr = &pddev->mm_addr->pex8311.tstamp; -#if 0 //### FIXME +#if 0 && defined( DEBUG ) // ### TODO _mbgddmsg_3( MBG_DBG_INIT_DEV, "MM addr: base: 0x%p, tstamp: 0x%p, offs: 0x%02lX", pddev->mm_addr, pddev->mm_tstamp_addr, (ulong) ( (uint8_t *) pddev->mm_tstamp_addr - (uint8_t *) pddev->mm_addr ) ); #endif - return 0; + return MBG_SUCCESS; } // map_sys_virtual_address static __mbg_inline /*HDR*/ +/** + * @brief Unmap a virtual address for a device, if it has been mapped before + * + * @param[in] pddev Pointer to the device structure + */ void unmap_sys_virtual_address( PCPS_DDEV *pddev ) { @@ -1198,23 +1174,26 @@ void unmap_sys_virtual_address( PCPS_DDEV *pddev ) #if DEBUG_PRINT_ACCESS_TIMES -#if 0 //### TODO FIXME if we need it -static inline -long _cyc_to_us( long long cyc ) -{ - cyc *= 1000; - do_div( cyc, cpu_khz ); - - return (long) cyc; -} -#endif - - -static __mbg_inline +static __mbg_inline /*HDR*/ +/** + * @brief Convert TSC cycles to picoseconds + * + * @note This has not yet been implemented for all target systems. + * + * A specific cycles frequency has to be provided by the target OS. + * + * @param[in] cyc The number of TSC cycles + * + * @return the computed number of picoseconds + */ long long _cyc_to_ps( long long cyc ) { - cyc *= 1000000000; + cyc *= 1000000000UL; + #if defined( MBG_TGT_LINUX ) + // The variable cpu_khz is exported by the kernel, and the + // do_div() function needs to be used in kernel space + // for the division. do_div( cyc, cpu_khz ); #else cyc = 0; //### TODO FIXME for different targets @@ -1231,9 +1210,19 @@ long long _cyc_to_ps( long long cyc ) #if DEBUG_ACCESS_TIMING -uint32_t dummy; +static uint32_t debug_dummy_var; static /*HDR*/ +/** + * @brief Report access timing for a device + * + * This is only used for testing. + * + * @param[in] pddev Pointer to the device structure + * @param[in] info Informational string to be printed + * @param[in] t_after_cmd Cycles value taken after command code has been written + * @param[in] t_after_reread Cycles value taken after a data word has been re-read + */ void report_access_timing( const PCPS_DDEV *pddev, const char *info, MBG_PC_CYCLES t_after_cmd, MBG_PC_CYCLES t_after_reread ) { @@ -1268,6 +1257,19 @@ void report_access_timing( const PCPS_DDEV *pddev, const char *info, #if DEBUG_IO_TIMING static /*HDR*/ +/** + * @brief Report I/O timing for a device + * + * This is only used for testing. + * + * @param[in] pddev Pointer to the device structure + * @param[in] info Informational string to be printed + * @param[in] cmd The command by tent to the device + * @param[in] count The number of bytes read from the device + * @param[in] t_after_cmd Cycles value taken after command code has been written + * @param[in] t_after_busy Cycles value taken after busy flag was cleard by the device + * @param[in] t_done Cycles value taken after bytes have been read + */ 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 ) @@ -1423,7 +1425,7 @@ int pcps_wait_busy( PCPS_DDEV *pddev ) * These group of functions is used for low level access to Meinberg * bus-level devices. Which of the function is actually to be used * depends on the device's bus type and interface chip and is determined - * by the function ::pcps_start_device which is called at device startup. + * by the function ::pcps_probe_device which is called at device startup. * * @see ::pcps_read_null * @see ::pcps_read_std @@ -1447,7 +1449,7 @@ static /*HDR*/ * @param[out] buffer A buffer to take the bytes to be read * @param[in] count The number of bytes to be read into the buffer * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @ingroup pcps_read_fncs * @see @ref pcps_read_fncs @@ -1479,7 +1481,7 @@ static /*HDR*/ * @param[out] buffer A buffer to take the bytes to be read * @param[in] count The number of bytes to be read into the buffer * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @ingroup pcps_read_fncs * @see @ref pcps_read_fncs @@ -1539,7 +1541,7 @@ static /*HDR*/ * @param[out] buffer A buffer to take the bytes to be read * @param[in] count The number of bytes to be read into the buffer * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @ingroup pcps_read_fncs * @see @ref pcps_read_fncs @@ -1616,7 +1618,7 @@ static /*HDR*/ * @param[out] buffer A buffer to take the bytes to be read * @param[in] count The number of bytes to be read into the buffer * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @ingroup pcps_read_fncs * @see @ref pcps_read_fncs @@ -1719,7 +1721,7 @@ static /*HDR*/ * @param[out] buffer A buffer to take the bytes to be read * @param[in] count The number of bytes to be read into the buffer * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @ingroup pcps_read_fncs * @see ::pcps_read_asic_mm @@ -1766,8 +1768,8 @@ int pcps_read_asic( PCPS_DDEV *pddev, uint8_t 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 ) ); + debug_dummy_var = _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 @@ -1857,7 +1859,7 @@ static /*HDR*/ * @param[out] buffer A buffer to take the bytes to be read * @param[in] count The number of bytes to be read into the buffer * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @ingroup pcps_read_fncs * @see ::pcps_read_asic @@ -1912,7 +1914,7 @@ int pcps_read_asic_mm( PCPS_DDEV *pddev, uint8_t cmd, #endif #if DEBUG_ACCESS_TIMING - dummy = pddev->mm_addr->mbgpex.asic.pci_data.ul; + debug_dummy_var = pddev->mm_addr->mbgpex.asic.pci_data.ul; mbg_get_pc_cycles( &t_after_reread ); #endif @@ -2000,10 +2002,9 @@ static /*HDR*/ * @param[out] buffer A buffer to take the bytes to be read * @param[in] count The number of bytes to be read into the buffer * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @ingroup pcps_read_fncs - * @see ::pcps_read_asic * @see @ref pcps_read_fncs */ int pcps_read_usb( PCPS_DDEV *pddev, uint8_t cmd, @@ -2376,27 +2377,25 @@ done: -/*-------------------------------------------------------------- - * Name: pcps_read_gps_block() - * - * Purpose: Get a block of data from GPS clock device. - * This is a local function which is called - * by pcps_read_gps(). +static /*HDR*/ +/** + * @brief Get a block of data from a GPS device * - * Input: pddev pointer to the device information - * data_type the code assigned to the data type - * buffer_size the size of the buffer - * block_num the number of the block to read - * block_size the size of the block to read + * This static function is used by ::pcps_read_gps. * - * Output: buffer filled with data + * @param[in] pddev Pointer to the device structure + * @param[in] data_type The code assigned to the dadta type, see @ref PC_GPS_CMD_CODES + * @param[out] buffer A buffer with data to be read according to the data_type + * @param[in] buffer_size The number of bytes to be read according to the data_type + * @param[in] block_num A buffer with data to be written according to the type code + * @param[in] block_size The number of bytes to be written according to the type code * - * Ret value: MBG_SUCCESS - * MBG_ERR_TIMEOUT - * MBG_ERR_NBYTES - *-------------------------------------------------------------*/ - -static /*HDR*/ + * @return ::MBG_SUCCESS on success, + * ::MBG_ERR_TIMEOUT if device didn't respond in time, + * ::MBG_ERR_NBYTES if the number of parameter bytes did not match + * the number of data bytes expected by the device, + * or one of the other @ref MBG_RETURN_CODES + */ int pcps_read_gps_block( PCPS_DDEV *pddev, uint8_t data_type, void FAR *buffer, @@ -2431,7 +2430,7 @@ int pcps_read_gps_block( PCPS_DDEV *pddev, // Write the command, expect to read one byte. rc = _pcps_read_var( pddev, PCPS_READ_GPS_DATA, uc ); - if ( rc != MBG_SUCCESS ) // Error ... + if ( mbg_rc_is_error( rc ) ) return rc; if ( uc != 1 ) // The board doesn't expect exactly one more byte @@ -2461,7 +2460,7 @@ int pcps_read_gps_block( PCPS_DDEV *pddev, n_bytes = 0; rc = _pcps_read( pddev, data_type, &n_bytes, size_n_bytes ); - if ( rc != MBG_SUCCESS ) // Error ... + if ( mbg_rc_is_error( rc ) ) // Error ... return rc; #if defined( MBG_ARCH_BIG_ENDIAN ) @@ -2491,23 +2490,31 @@ int pcps_read_gps_block( PCPS_DDEV *pddev, -/*-------------------------------------------------------------- - * Name: pcps_read_gps() +/*HDR*/ +/** + * @brief Read a large data structure from a device * - * Purpose: Get a data structure from a GPS clock. + * Read data structures which exceed ::PCPS_FIFO_SIZE bytes. + * This can't be handled in a single read cycle, and due to + * limitations of the device's microprocessor the execution time + * can be up to 20 milliseconds, depending on the device type. + * This has been introduced with the first GPS devices but is + * now in fact also used with non-GPS devices. * - * Input: pddev pointer to the device information - * data_type the code assigned to the data type - * buffer_size the size of the buffer + * @param[in] pddev Pointer to the device structure + * @param[in] data_type The code assigned to the dadta type, see @ref PC_GPS_CMD_CODES + * @param[out] buffer A buffer with data to be read according to the data_type + * @param[in] buffer_size The number of bytes to be read according to the data_type * - * Output: buffer filled with data + * @return ::MBG_SUCCESS on success, + * ::MBG_ERR_TIMEOUT if device didn't respond in time, + * ::MBG_ERR_NBYTES if the number of parameter bytes did not match + * the number of data bytes expected by the device, + * or one of the other @ref MBG_RETURN_CODES * - * Ret value: MBG_SUCCESS - * MBG_ERR_TIMEOUT - * MBG_ERR_NBYTES - *-------------------------------------------------------------*/ - -/*HDR*/ + * @ingroup pcps_io_fncs + * @see @ref pcps_io_fncs + */ int pcps_read_gps( PCPS_DDEV *pddev, uint8_t data_type, void FAR *buffer, @@ -2536,7 +2543,7 @@ int pcps_read_gps( PCPS_DDEV *pddev, rc = pcps_read_gps_block( pddev, data_type, p, buffer_size, (uint8_t) block_num, PCPS_FIFO_SIZE ); - if ( rc != MBG_SUCCESS ) // Error ... + if ( mbg_rc_is_error( rc ) ) // Error ... goto done; // Move the destination pointer to the next free byte. @@ -2563,25 +2570,28 @@ done: #endif -/*-------------------------------------------------------------- - * Name: pcps_write_gps() + +/*HDR*/ +/** + * @brief Write a large data structure to a device * - * Purpose: Write a data structure to a GPS clock. + * This has been introduced with the first GPS devices but is + * now in fact also used with non-GPS devices. * - * Input: pddev pointer to the device information - * data_type the code assigned to the data type - * buffer the data to write - * buffer_size the size of the buffer - * read_fnc function to access the board + * @param[in] pddev Pointer to the device structure + * @param[in] data_type The code assigned to the dadta type, see @ref PC_GPS_CMD_CODES + * @param[in] buffer A buffer with data to be written according to the data_type + * @param[in] buffer_size The number of bytes to be written according to the data_type * - * Output: -- + * @return ::MBG_SUCCESS on success, + * ::MBG_ERR_TIMEOUT if device didn't respond in time, + * ::MBG_ERR_NBYTES if the number of parameter bytes did not match + * the number of data bytes expected by the device, + * or one of the other @ref MBG_RETURN_CODES * - * Ret value: MBG_SUCCESS - * MBG_ERR_TIMEOUT - * MBG_ERR_NBYTES - *-------------------------------------------------------------*/ - -/*HDR*/ + * @ingroup pcps_io_fncs + * @see @ref pcps_io_fncs + */ int pcps_write_gps( PCPS_DDEV *pddev, uint8_t data_type, const void FAR *buffer, @@ -2614,7 +2624,7 @@ int pcps_write_gps( PCPS_DDEV *pddev, // Write the command, expect to read one byte. rc = _pcps_read_var( pddev, PCPS_WRITE_GPS_DATA, uc ); - if ( rc != MBG_SUCCESS ) // Error ... + if ( mbg_rc_is_error( rc ) ) // Error ... return rc; if ( uc != 1 ) // The board doesn't expect exactly one more byte @@ -2644,7 +2654,7 @@ int pcps_write_gps( PCPS_DDEV *pddev, n_bytes = 0; rc = _pcps_read( pddev, data_type, &n_bytes, size_n_bytes ); - if ( rc != MBG_SUCCESS ) // Error ... + if ( mbg_rc_is_error( rc ) ) // Error ... return rc; #if defined( MBG_ARCH_BIG_ENDIAN ) @@ -2669,7 +2679,7 @@ int pcps_write_gps( PCPS_DDEV *pddev, { rc = _pcps_write_byte( pddev, *p++ ); - if ( rc != MBG_SUCCESS ) // Error ... + if ( mbg_rc_is_error( rc ) ) // Error ... return rc; } @@ -2800,21 +2810,17 @@ no_rev_num: -/*-------------------------------------------------------------- - * Name: pcps_read_sernum() - * - * Purpose: This function tries to read the clock's S/N - * from the board, if supported by the clock. +/*HDR*/ +/** + * @brief Read the serial number from a device, if supported * - * Input: pddev pointer to the device information + * If the serial number could be read successfully then it is + * stored in one of the sub-structures of pddev. * - * Output: pddev sernum field filled with ASCIIZ + * @param[in,out] pddev Pointer to a device structure * - * Ret value: MBG_SUCCESS no error - * other error - *-------------------------------------------------------------*/ - -/*HDR*/ + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ int pcps_read_sernum( PCPS_DDEV *pddev ) { char *cp; @@ -2840,7 +2846,7 @@ int pcps_read_sernum( PCPS_DDEV *pddev ) rc = _pcps_read( pddev, PCPS_GIVE_SERNUM, pddev->dev.cfg.sernum, PCPS_FIFO_SIZE ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) { _mbgddmsg_2( MBG_DBG_INIT_DEV, "PCPS read SERNUM %X: rc = %i", _pcps_ddev_dev_id( pddev ), rc ); @@ -2863,7 +2869,7 @@ int pcps_read_sernum( PCPS_DDEV *pddev ) rc = _pcps_read_gps_var( pddev, PC_GPS_RECEIVER_INFO, *p_ri ); - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) { _mbgddmsg_2( MBG_DBG_INIT_DEV, "PCPS read GPS receiver info %X: rc = %i", _pcps_ddev_dev_id( pddev ), rc ); @@ -2894,7 +2900,7 @@ int pcps_read_sernum( PCPS_DDEV *pddev ) assert( sizeof( ident ) < sizeof( pddev->dev.cfg.sernum ) ); #endif - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) { _mbgddmsg_2( MBG_DBG_INIT_DEV, "PCPS read GPS ident %X: rc = %i", _pcps_ddev_dev_id( pddev ), rc ); @@ -2911,6 +2917,26 @@ int pcps_read_sernum( PCPS_DDEV *pddev ) #endif mbg_gps_ident_decode( _pcps_ddev_sernum( pddev ), &ident ); + + #if DEBUG_SERNUM + _mbgddmsg_1( MBG_DBG_DETAIL, "S/N decoded from ident: %s (raw)", + _pcps_ddev_sernum( pddev ) ); + #endif + + // Some old devices may have non-digits appended + // to the S/N string. Truncate such a string. + for ( cp = _pcps_ddev_sernum( pddev ); *cp; cp++ ) + if ( ( *cp < '0' ) || ( *cp > '9' ) ) + { + *cp = 0; + break; + } + + #if DEBUG_SERNUM + _mbgddmsg_1( MBG_DBG_DETAIL, "S/N decoded from ident: %s", + _pcps_ddev_sernum( pddev ) ); + #endif + goto check; } @@ -3005,7 +3031,7 @@ int pcps_rsrc_claim( PCPS_DDEV *pddev ) PCPS_IO_RSRC *p = &_pcps_ddev_io_rsrc( pddev, i ); ushort rc; - rc = _rsrc_alloc_ports( &pddev->rsrc, p->base_raw, p->num, decode_width ); //##++ + rc = _rsrc_alloc_ports( pddev, p->base_raw, p->num, decode_width ); // If the resource manager was unable to alloc the resources // then the selected range of ports is probably in use @@ -3024,19 +3050,21 @@ int pcps_rsrc_claim( PCPS_DDEV *pddev ) /*HDR*/ +/** + * @brief Release an I/O port resource range that has been claimed before + * + * @param[in,out] pddev The device structure + */ void pcps_rsrc_release( PCPS_DDEV *pddev ) { int i; - for ( i = 0; i < N_PCPS_PORT_RSRC; i++ ) + for ( i = 0; i < pddev->rsrc_info.num_rsrc_io; i++ ) { - PCPS_PORT_RSRC *p = &_pcps_ddev_port_rsrc( pddev, i ); - - if ( _pcps_port_rsrc_unused( p ) ) - continue; + PCPS_IO_RSRC *p = &_pcps_ddev_io_rsrc( pddev, i ); - // clean up if clock not found - _rsrc_dealloc_ports( &pddev->rsrc.hResource[i], p->base, p->num ); + if ( p->base_raw ) + _rsrc_dealloc_ports( pddev, p->base_raw, p->num ); } } // pcps_rsrc_release @@ -3046,6 +3074,11 @@ void pcps_rsrc_release( PCPS_DDEV *pddev ) #if defined( MBG_TGT_OS2 ) static /*HDR*/ +/** + * @brief Register a device under OS/2 + * + * @param[in] pddev The device structure + */ void pcps_rsrc_register_device( PCPS_DDEV *pddev ) { #define RSRC_BASE_NAME "RADIOCLK_# Meinberg Radio Clock " @@ -3110,14 +3143,17 @@ void pcps_rsrc_register_device( PCPS_DDEV *pddev ) * *-------------------------------------------------------------*/ -/*-------------------------------------------------------------- - * Convert the code read from PS/2 POS to the port base address. - *-------------------------------------------------------------*/ - -/*HDR*/ -ushort pcps_port_from_pos( ushort pos ) +static /*HDR*/ +/** + * @brief Convert the code read from PS/2 POS to the port base address + * + * @param[in] pos The POS code to be converted + * + * @return The decoded I/O port base address + */ +uint16_t pcps_port_from_pos( uint16_t pos ) { - ushort us = ( ( pos & 0x007E ) << 8 ) | 0x0100; + uint16_t us = ( ( pos & 0x007E ) << 8 ) | 0x0100; if ( pos & 0x0001 ) us |= 0x0010; @@ -3128,14 +3164,17 @@ ushort pcps_port_from_pos( ushort pos ) -/*-------------------------------------------------------------- - * Convert the port base address to a PS/2 POS code. - *-------------------------------------------------------------*/ - -/*HDR*/ -uchar pcps_pos_from_port( ushort port ) +static /*HDR*/ +/** + * @brief Convert the port base address to a PS/2 POS code + * + * @param[in] port The I/O port base address to be encoded + * + * @return The encoded POS code + */ +uint8_t pcps_pos_from_port( uint16_t port ) { - uchar uc; + uint8_t uc; uc = *( ( (uchar *) (&port) ) + 1 ) & 0x7E; @@ -3150,7 +3189,12 @@ uchar pcps_pos_from_port( ushort port ) static /*HDR*/ -void pcps_detect_mca_clocks( PCPS_DDEV_ALLOC_FNC *alloc_fnc, void *alloc_arg ) +/** + * @brief Detect MCA devices and allocate device info structures + * + * @param[in] alloc_fnc Pointer to function called to allocate a device structure for each detected device. + */ +void pcps_detect_mca_devices( PCPS_DDEV_ALLOC_FNC *alloc_fnc ) { short rc; ushort type_idx; @@ -3183,7 +3227,7 @@ void pcps_detect_mca_clocks( PCPS_DDEV_ALLOC_FNC *alloc_fnc, void *alloc_arg ) // New device found, try to add to list. - pddev = alloc_fnc( alloc_arg ); + pddev = alloc_fnc(); if ( pddev ) // Setup only if successful. { @@ -3194,24 +3238,33 @@ void pcps_detect_mca_clocks( PCPS_DDEV_ALLOC_FNC *alloc_fnc, void *alloc_arg ) //##++ Should try to read the interrupt line assigned to the clock. // The standard functions, however, don't use any interrupt. - pcps_start_device( pddev, 0, slot_num ); + pcps_probe_device( pddev, 0, slot_num ); } } mca_fnc_deinit(); -} // pcps_detect_mca_clocks +} // pcps_detect_mca_devices #endif /* _PCPS_USE_MCA */ -// The function below takes a bus flag and device ID to search -// the table of known devices for a device which matches the -// given criteria. - /*HDR*/ -PCPS_DEV_TYPE *pcps_get_dev_type( int bus_mask, ushort dev_id ) +/** + * @brief Lookup a specific device in the device table + * + * The function below takes a bus flag and device ID to search + * the table of known devices for a device which matches the + * given criteria. + * + * @param[in] bus_mask Mask of the bus type to look up, see @ref PCPS_BUS_FLAG_MASKS + * @param[in] dev_id The device ID to lookup, see @ref MEINBERG_PCI_DEVICE_IDS + * or @ref MBG_USB_DEVICE_IDS, depending on the bus_mask + * + * @return A pointer to the device table entry, or NULL if no entry found + */ +PCPS_DEV_TYPE *pcps_get_dev_type_table_entry( PCPS_BUS_FLAGS bus_mask, PCPS_DEV_ID dev_id ) { int i; @@ -3228,11 +3281,16 @@ PCPS_DEV_TYPE *pcps_get_dev_type( int bus_mask, ushort dev_id ) return NULL; -} // pcps_get_dev_type +} // pcps_get_dev_type_table_entry /*HDR*/ +/** + * @brief Allocate a device info structure for a device + * + * @return A pointer to the allocated structure, or NULL if failed + */ PCPS_DDEV *pcps_alloc_ddev( void ) { PCPS_DDEV *pddev; @@ -3279,6 +3337,11 @@ PCPS_DDEV *pcps_alloc_ddev( void ) /*HDR*/ +/** + * @brief Free a previously allocated device info structure + * + * @param[in] pddev Pointer to the device structure to be freed + */ void pcps_free_ddev( PCPS_DDEV *pddev ) { if ( pddev ) @@ -3306,16 +3369,33 @@ void pcps_free_ddev( PCPS_DDEV *pddev ) static /*HDR*/ -void rsrc_port_to_cfg_port( PCPS_PORT_RSRC *p_port_rsrc, const PCPS_IO_RSRC *p_io_rsrc ) +/** + * @brief Convert a raw I/O base address to a short format + * + * See notes for ::PCPS_SHORT_PORT_RSRC. + + * @param[out] p_short_port_rsrc Pointer to a variable that takes up the converted address + * @param[in] p_io_rsrc Pointer to a variable with the address to be converted + */ +void rsrc_port_to_cfg_port( PCPS_SHORT_PORT_RSRC *p_short_port_rsrc, const PCPS_IO_RSRC *p_io_rsrc ) { - p_port_rsrc->base = (PCPS_PORT_ADDR) p_io_rsrc->base_raw; - p_port_rsrc->num = p_io_rsrc->num; + p_short_port_rsrc->base = (PCPS_SHORT_PORT_ADDR) p_io_rsrc->base_raw; + p_short_port_rsrc->num = (uint16_t) p_io_rsrc->num; } // rsrc_port_to_cfg_port /*HDR*/ +/** + * @brief Add an I/O address range resource to the device structure + * + * @param[in,out] pddev Pointer to the device structure + * @param[in] base Base address of the I/O address range + * @param[in] num Number of addresses of the I/O address range + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ int pcps_add_rsrc_io( PCPS_DDEV *pddev, ulong base, ulong num ) { PCPS_RSRC_INFO *prsrci = &pddev->rsrc_info; @@ -3326,7 +3406,7 @@ int pcps_add_rsrc_io( PCPS_DDEV *pddev, ulong base, ulong num ) p->base_mapped = (PCPS_IO_ADDR_MAPPED) _pcps_ioremap( base, num ); p->base_raw = (PCPS_IO_ADDR_RAW) base; - p->num = (uint16_t) num; + p->num = num; prsrci->num_rsrc_io++; @@ -3343,6 +3423,15 @@ int pcps_add_rsrc_io( PCPS_DDEV *pddev, ulong base, ulong num ) /*HDR*/ +/** + * @brief Add a memory address range resource to the device structure + * + * @param[in,out] pddev Pointer to the device structure + * @param[in] start Start address of the memory range + * @param[in] len Size of the memory range + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ int pcps_add_rsrc_mem( PCPS_DDEV *pddev, MBG_MEM_ADDR start, ulong len ) { PCPS_RSRC_INFO *prsrci = &pddev->rsrc_info; @@ -3372,6 +3461,14 @@ int pcps_add_rsrc_mem( PCPS_DDEV *pddev, MBG_MEM_ADDR start, ulong len ) /*HDR*/ +/** + * @brief Add an IRQ number resource to the device structure + * + * @param[in,out] pddev Pointer to the device structure + * @param[in] irq_num Start address of the memory range + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ int pcps_add_rsrc_irq( PCPS_DDEV *pddev, int16_t irq_num ) { PCPS_RSRC_INFO *prsrci = &pddev->rsrc_info; @@ -3396,10 +3493,20 @@ int pcps_add_rsrc_irq( PCPS_DDEV *pddev, int16_t irq_num ) #if _PCPS_USE_PNP /*HDR*/ -int pcps_init_ddev( PCPS_DDEV *pddev, int bus_flags, ushort dev_id ) +/** + * @brief Initialize an allocated device structure for a specific device + * + * @param[in,out] pddev Pointer to the device structure + * @param[in] bus_mask Mask of the bus type to look up, see @ref PCPS_BUS_FLAG_MASKS + * @param[in] dev_id The device ID to lookup, see @ref MEINBERG_PCI_DEVICE_IDS + * or @ref MBG_USB_DEVICE_IDS, depending on the bus_mask + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ +int pcps_init_ddev( PCPS_DDEV *pddev, PCPS_BUS_FLAGS bus_mask, PCPS_DEV_ID dev_id ) { // First check if we really support the device to be added. - PCPS_DEV_TYPE *pdt = pcps_get_dev_type( bus_flags, dev_id ); + PCPS_DEV_TYPE *pdt = pcps_get_dev_type_table_entry( bus_mask, dev_id ); if ( pdt == NULL ) { @@ -3426,36 +3533,57 @@ int pcps_init_ddev( PCPS_DDEV *pddev, int bus_flags, ushort dev_id ) #if defined( DEBUG ) static /*HDR*/ -const char *get_feature_name( PCPS_FEATURES flag ) +/** + * @brief Get the name assigned to one of the @ref PCPS_FEATURE_MASKS flags + * + * @param[in] flag_mask one of the @ref PCPS_FEATURE_MASKS flags + * + * @return The associated feature name, or "unknown" + * + * @see @ref PCPS_FEATURE_MASKS + */ +const char *get_pcps_feature_name( PCPS_FEATURES flag_mask ) { int i; for ( i = 0; i < N_PCPS_FEATURE_BITS; i++ ) - if ( ( 1UL << i ) == flag ) + if ( ( 1UL << i ) == flag_mask ) return pcps_feature_names[i]; return "unknown"; -} // get_feature_name +} // get_pcps_feature_name #endif static /*HDR*/ +/** + * @brief Check the firmware to see if a specific feature is supported + * + * Some devices provide a specific feature only starting with a specific + * firmware version, but the device provides no way to test this, so + * the feature flag in the device structure is set if the firmware + * has the required version. + * + * @param[in,out] pddev Pointer to the device structure + * @param[in] req_rev_num Revision number required for the feature to be supported + * @param[in] flag_mask Flag mask of the feature to be tested + */ void check_feature( PCPS_DDEV *pddev, ushort req_rev_num, - PCPS_FEATURES flag ) + PCPS_FEATURES flag_mask ) { int supported = _pcps_ddev_fw_rev_num( pddev ) >= req_rev_num; if ( supported ) - pddev->dev.cfg.features |= flag; + pddev->dev.cfg.features |= flag_mask; #if defined( DEBUG ) _mbgddmsg_5( MBG_DBG_INIT_DEV, "%s v%03X: feature 0x%08lX (%s) %ssupported", _pcps_ddev_type_name( pddev ), _pcps_ddev_fw_rev_num( pddev ), - (ulong) flag, get_feature_name( flag ), + (ulong) flag_mask, get_pcps_feature_name( flag_mask ), supported ? "" : "not " ); #endif @@ -3464,8 +3592,18 @@ void check_feature( PCPS_DDEV *pddev, ushort req_rev_num, static /*HDR*/ -void check_ri_features( PCPS_DDEV *pddev, const RECEIVER_INFO *p_ri ) +/** + * @brief Check the receiver info features to see if a specific feature is supported + * + * Some devices provide a ::RECEIVER_INFO which provides some flags that + * can be mapped to the feature flags we use internally, so we scan these features + * and update the internal features mask accordingly. + * + * @param[in,out] pddev Pointer to the device structure + */ +void check_ri_features( PCPS_DDEV *pddev ) { + const RECEIVER_INFO *p_ri = _ri_addr( pddev ); int gps_feat_bit; for ( gps_feat_bit = 0; gps_feat_bit < N_GPS_FEATURE; gps_feat_bit++ ) @@ -3519,7 +3657,127 @@ void check_ri_features( PCPS_DDEV *pddev, const RECEIVER_INFO *p_ri ) /*HDR*/ -int pcps_start_device( PCPS_DDEV *pddev, +/** + * @brief Check if a specific feature of a specific feature type is supported + * + * There are different structures where information can be stored + * if a specific feature is supported. All information is set up + * when the ::pcps_probe_device function is called to probe and + * initialize the device. + * This generic low-level function can be called by API functions + * to check if a specific feature is supported. + * + * @param[in] p_ddev Pointer to the device structure + * @param[in] feat_req_type See ::DEV_FEAT_REQ_TYPES + * @param[in] feat_num Number and range depending on feat_req_type value + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @see ::pcps_probe_device + */ +int pcps_chk_dev_feat( PCPS_DDEV *p_ddev, uint32_t feat_req_type, uint32_t feat_num ) +{ + // NOTE In the code below we currently check if the bit to be tested + // is really defined in an enumeration, and return an error if a bit + // is tested which is not defined. + // Alternatively we could instead just check if the bit number is valid + // according to the buffer size. + + switch ( feat_req_type ) + { + case DEV_FEAT_REQ_TYPE_BUILTIN: + _mbgddmsg_3( MBG_DBG_DETAIL, "%s: chk_dev_feat: builtin_feat %i/%i", + pcps_driver_name, feat_num, N_GPS_BUILTIN_FEATURE_BITS ); + + if ( feat_num < N_GPS_BUILTIN_FEATURE_BITS ) + return _check_feat_supp_bit( p_ddev->builtin_features, feat_num ); + + break; // invalid + + + case DEV_FEAT_REQ_TYPE_REF_TYPE: + _mbgddmsg_3( MBG_DBG_DETAIL, "%s: chk_dev_feat: ref_type feat %i/%i", + pcps_driver_name, feat_num, N_PCPS_REF ); + + if ( feat_num < N_PCPS_REF ) + return ( feat_num == _pcps_ddev_ref_type( p_ddev ) ) ? MBG_SUCCESS : MBG_ERR_NOT_SUPP_BY_DEV; + + break; // invalid + + + case DEV_FEAT_REQ_TYPE_PCPS: + _mbgddmsg_3( MBG_DBG_DETAIL, "%s: chk_dev_feat: pcps_feat %i/%i", + pcps_driver_name, feat_num, N_PCPS_FEATURE_BITS ); + + if ( feat_num < N_PCPS_FEATURE_BITS ) + return _check_feat_supp_bit( p_ddev->dev.cfg.features, feat_num ); + + break; // invalid + + + case DEV_FEAT_REQ_TYPE_RI: + _mbgddmsg_3( MBG_DBG_DETAIL, "%s: chk_dev_feat: ri_feat %i/%i", + pcps_driver_name, feat_num, N_GPS_FEATURE ); + + if ( feat_num < N_GPS_FEATURE ) + return _check_feat_supp_bit( p_ddev->xdev_features.receiver_info.features, feat_num ); + + break; // invalid + + + + case DEV_FEAT_REQ_TYPE_XFEAT: + _mbgddmsg_3( MBG_DBG_DETAIL, "%s: chk_dev_feat: x_feat %i/%i", + pcps_driver_name, feat_num, N_MBG_XFEATURE ); + + if ( feat_num < N_MBG_XFEATURE ) + return check_feat_supp_byte_array( feat_num, p_ddev->xdev_features.xfeature_buffer.b, + sizeof( p_ddev->xdev_features.xfeature_buffer ) ); + break; // invalid + + + + case DEV_FEAT_REQ_TYPE_TLV_FEAT: + _mbgddmsg_3( MBG_DBG_DETAIL, "%s: chk_dev_feat: tlv_feat %i/%i", + pcps_driver_name, feat_num, N_MBG_TLV_FEAT_TYPES ); + + if ( feat_num < N_MBG_TLV_FEAT_TYPES ) + return check_feat_supp_byte_array( feat_num, p_ddev->xdev_features.tlv_info.supp_tlv_feat.b, + sizeof( p_ddev->xdev_features.tlv_info.supp_tlv_feat.b ) ); + break; // invalid + } + + _mbgddmsg_3( MBG_DBG_WARN, "%s: chk_dev_feat: *invalid* request %i:%i", + pcps_driver_name, feat_req_type, feat_num ); + + return MBG_ERR_INV_PARM; + +} // pcps_chk_dev_feat + + + +/*HDR*/ +/** + * @brief Probe if a device is supported, and allocate and setup the device structure + * + * This function should be called by the probe routines of any + * target-specific kernel drivers. + * If the device is supported then all specific information including + * supported features is read from the device and stored in sub-structures + * of the device structure addressed by pdev. + * + * @param[in,out] pddev Pointer to the device structure which has been initialized and will be set up + * @param[in] bus_num The bus number if supported (e.g. PCI), else 0 + * @param[in] dev_fnc_num The device/function number if supported (e.g. PCI), else 0 + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @see ::pcps_cleanup_device + * @see ::pcps_chk_dev_feat + */ +int pcps_probe_device( PCPS_DDEV *pddev, PCPS_BUS_NUM bus_num, PCPS_SLOT_NUM dev_fnc_num ) { @@ -3608,7 +3866,7 @@ int pcps_start_device( PCPS_DDEV *pddev, #error USB endpoint configuration can not be determined for this target. #endif - if ( rc == MBG_SUCCESS ) + if ( mbg_rc_is_success( rc ) ) if ( pddev->n_usb_ep < MBGUSB_MIN_ENDPOINTS_REQUIRED ) { #if defined( MBG_TGT_LINUX ) @@ -3640,14 +3898,11 @@ int pcps_start_device( PCPS_DDEV *pddev, // If access time is below 1 ms then there might be a V2.0 Hub between device and host. // In this case, you can expect that there is the 125 us microframe timing of USB 2.0. - if ( ( (ULONGLONG) ( Count2.QuadPart - Count1.QuadPart ) ) < ( (ULONGLONG) PerfFreq.QuadPart ) / 1000UL ) - pddev->usb_20_mode = 1; - else - pddev->usb_20_mode = 0; + pddev->usb_20_mode = ( (ULONGLONG) ( Count2.QuadPart - Count1.QuadPart ) ) < ( ( (ULONGLONG) PerfFreq.QuadPart ) / 1000UL ); } #endif - if ( rc != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) { _pcps_ddev_set_err_flags( pddev, PCPS_EF_IO_INIT ); goto fail; @@ -3738,7 +3993,7 @@ int pcps_start_device( PCPS_DDEV *pddev, pddev->irq_ack_port = pddev->irq_enb_disb_port; pddev->irq_ack_mask = PCI_ASIC_PCI_IRQF; - _mbgddmsg_1( MBG_DBG_INIT_DEV, "%s: pcps_start_device: interface is MBGPEX", + _mbgddmsg_1( MBG_DBG_INIT_DEV, "%s: pcps_probe_device: interface is MBGPEX", pcps_driver_name ); #if _PCPS_USE_MM_IO @@ -3879,7 +4134,7 @@ chip_setup_done: pddev->dev.cfg.irq_num = pddev->rsrc_info.num_rsrc_irq ? pddev->rsrc_info.irq.num : -1; - pddev->dev.cfg.status_port = _pcps_ddev_port_base( pddev, 0 ) + status_port_offs; + pddev->dev.cfg.short_status_port = _pcps_ddev_short_port_base( pddev, 0 ) + status_port_offs; pddev->dev.cfg.timeout_clk = PCPS_TIMEOUT_CNT; @@ -3919,19 +4174,19 @@ chip_setup_done: { #if defined( MBG_TGT_LINUX ) printk( KERN_WARNING "%s: duplicate base address 0x%04lX, device %s will not work properly (BIOS faulty)\n", - pcps_driver_name, (ulong) _pcps_ddev_port_base( pddev, 0 ), _pcps_ddev_type_name( pddev ) ); + pcps_driver_name, (ulong) _pcps_ddev_io_base_raw( pddev, 0 ), _pcps_ddev_type_name( pddev ) ); #elif defined( MBG_TGT_BSD ) printf( "%s: duplicate base address 0x%04lX, device %s will not work properly (BIOS faulty)\n", - pcps_driver_name, (ulong) _pcps_ddev_port_base( pddev, 0 ), _pcps_ddev_type_name( pddev ) ); + pcps_driver_name, (ulong) _pcps_ddev_io_base_raw( pddev, 0 ), _pcps_ddev_type_name( pddev ) ); #elif defined( MBG_TGT_WIN32 ) swprintf( pddev->wcs_msg, L"duplicate base address 0x%04lX, device %s will not work properly (BIOS faulty)", - (ulong) _pcps_ddev_port_base( pddev, 0 ), _pcps_ddev_type_name( pddev ) ); + (ulong) _pcps_ddev_io_base_raw( pddev, 0 ), _pcps_ddev_type_name( pddev ) ); _evt_msg_w( GlbDriverObject, pddev->wcs_msg ); #endif } - #if 0 && DEBUG //##++++++++++++++ + #if 0 && DEBUG //###++++++++++++++ TODO testing only { MBG_SYS_UPTIME uptime; mbg_get_sys_uptime( &uptime ); @@ -3957,11 +4212,11 @@ chip_setup_done: // just means there is no device using the given port address. #if defined( MBG_TGT_WIN32 ) swprintf( pddev->wcs_msg, L"No ISA card found at port %03lXh.", - (ulong) _pcps_ddev_port_base( pddev, 0 ) ); + (ulong) _pcps_ddev_io_base_raw( pddev, 0 ) ); _evt_msg_w( GlbDriverObject, pddev->wcs_msg ); #else _mbgddmsg_1( MBG_DBG_INIT_DEV, "No ISA card found at port %03lXh.", - (ulong) _pcps_ddev_port_base( pddev, 0 ) ); + (ulong) _pcps_ddev_io_base_raw( pddev, 0 ) ); #endif } else @@ -4025,7 +4280,7 @@ chip_setup_done: { pddev->raw_asic_version = pddev->mm_addr->mbgpex.asic.raw_version; _mbg_swab_asic_version( &pddev->raw_asic_version ); - _mbgddmsg_2( MBG_DBG_INIT_DEV, "%s: pcps_start_device: raw ASIC version %04X read via MM", + _mbgddmsg_2( MBG_DBG_INIT_DEV, "%s: pcps_probe_device: raw ASIC version %04X read via MM", pcps_driver_name, pddev->raw_asic_version ); } else @@ -4034,7 +4289,7 @@ chip_setup_done: pddev->raw_asic_version = _mbg_inp32_to_cpu( pddev, 0, _pcps_ddev_io_base_mapped( pddev, 0 ) + offsetof( PCI_ASIC, raw_version ) ); _mbg_swab_asic_version( &pddev->raw_asic_version ); - _mbgddmsg_2( MBG_DBG_INIT_DEV, "%s: pcps_start_device: raw ASIC version %04X read via I/O", + _mbgddmsg_2( MBG_DBG_INIT_DEV, "%s: pcps_probe_device: raw ASIC version %04X read via I/O", pcps_driver_name, pddev->raw_asic_version ); } @@ -4048,6 +4303,7 @@ chip_setup_done: case PCPS_TYPE_PC31: case PCPS_TYPE_PS31_OLD: case PCPS_TYPE_PS31: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_PC31PS31; check_feature( pddev, REV_CAN_SET_TIME_PC31PS31, PCPS_CAN_SET_TIME ); check_feature( pddev, REV_HAS_SERIAL_PC31PS31, PCPS_HAS_SERIAL ); @@ -4056,20 +4312,24 @@ chip_setup_done: break; case PCPS_TYPE_PC32: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_PC32; break; case PCPS_TYPE_PCI32: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_PCI32; break; case PCPS_TYPE_GPS167PC: + pddev->builtin_features = BUILTIN_FEAT_GPS167PC; pddev->dev.cfg.features = PCPS_FEAT_GPS167PC; check_feature( pddev, REV_HAS_HR_TIME_GPS167PC, PCPS_HAS_HR_TIME ); check_feature( pddev, REV_HAS_CABLE_LEN_GPS167PC, PCPS_HAS_CABLE_LEN ); break; case PCPS_TYPE_GPS167PCI: + pddev->builtin_features = BUILTIN_FEAT_GPS167PCI; pddev->dev.cfg.features = PCPS_FEAT_GPS167PCI; check_feature( pddev, REV_HAS_CABLE_LEN_GPS167PCI, PCPS_HAS_CABLE_LEN ); check_feature( pddev, REV_CAN_CLR_UCAP_BUFF_GPS167PCI, PCPS_CAN_CLR_UCAP_BUFF ); @@ -4077,43 +4337,52 @@ chip_setup_done: break; case PCPS_TYPE_PCI509: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_PCI509; break; case PCPS_TYPE_GPS168PCI: + pddev->builtin_features = BUILTIN_FEAT_GPS168PCI; pddev->dev.cfg.features = PCPS_FEAT_GPS168PCI; check_feature( pddev, REV_CAN_CLR_UCAP_BUFF_GPS168PCI, PCPS_CAN_CLR_UCAP_BUFF ); check_feature( pddev, REV_HAS_UCAP_GPS168PCI, PCPS_HAS_UCAP ); break; case PCPS_TYPE_PCI510: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_PCI510; break; case PCPS_TYPE_GPS169PCI: + pddev->builtin_features = BUILTIN_FEAT_GPS169PCI; pddev->dev.cfg.features = PCPS_FEAT_GPS169PCI; check_feature( pddev, REV_HAS_GPS_DATA_16_GPS169PCI, PCPS_HAS_GPS_DATA_16 ); break; case PCPS_TYPE_TCR510PCI: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_TCR510PCI; check_feature( pddev, REV_HAS_HR_TIME_TCR510PCI, PCPS_HAS_HR_TIME ); break; case PCPS_TYPE_TCR167PCI: + pddev->builtin_features = BUILTIN_FEAT_TCR167PCI; pddev->dev.cfg.features = PCPS_FEAT_TCR167PCI; break; case PCPS_TYPE_GPS170PCI: + pddev->builtin_features = BUILTIN_FEAT_GPS170PCI; pddev->dev.cfg.features = PCPS_FEAT_GPS170PCI; break; case PCPS_TYPE_PCI511: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_PCI511; check_feature( pddev, REV_HAS_HR_TIME_PCI511, PCPS_HAS_HR_TIME ); break; case PCPS_TYPE_TCR511PCI: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_TCR511PCI; check_feature( pddev, REV_HAS_IRIG_CTRL_BITS_TCR511PCI, PCPS_HAS_IRIG_CTRL_BITS ); check_feature( pddev, REV_HAS_IRIG_TIME_TCR511PCI, PCPS_HAS_IRIG_TIME ); @@ -4121,6 +4390,7 @@ chip_setup_done: break; case PCPS_TYPE_PEX511: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_PEX511; // HR time support for the PEX511 requires both a certain ASIC // version plus a certain firmware version. @@ -4133,6 +4403,7 @@ chip_setup_done: break; case PCPS_TYPE_TCR511PEX: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_TCR511PEX; check_feature( pddev, REV_HAS_IRIG_CTRL_BITS_TCR511PEX, PCPS_HAS_IRIG_CTRL_BITS ); check_feature( pddev, REV_HAS_IRIG_TIME_TCR511PEX, PCPS_HAS_IRIG_TIME ); @@ -4142,16 +4413,19 @@ chip_setup_done: break; case PCPS_TYPE_GPS170PEX: + pddev->builtin_features = BUILTIN_FEAT_GPS170PEX; pddev->dev.cfg.features = PCPS_FEAT_GPS170PEX; pcps_check_pex_irq_unsafe( pddev, REV_HAS_IRQ_FIX_MINOR_GPS170PEX, PCI_ASIC_MAJOR_GPS170PEX, PCI_ASIC_FIX_IRQ_MINOR_GPS170PEX ); break; case PCPS_TYPE_USB5131: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_USB5131; break; case PCPS_TYPE_TCR51USB: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_TCR51USB; check_feature( pddev, REV_HAS_IRIG_CTRL_BITS_TCR51USB, PCPS_HAS_IRIG_CTRL_BITS ); check_feature( pddev, REV_HAS_IRIG_TIME_TCR51USB, PCPS_HAS_IRIG_TIME ); @@ -4159,62 +4433,77 @@ chip_setup_done: break; case PCPS_TYPE_MSF51USB: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_MSF51USB; break; case PCPS_TYPE_PTP270PEX: + pddev->builtin_features = BUILTIN_FEAT_PTP270PEX; pddev->dev.cfg.features = PCPS_FEAT_PTP270PEX; break; case PCPS_TYPE_FRC511PEX: + pddev->builtin_features = BUILTIN_FEAT_FRC511PEX; pddev->dev.cfg.features = PCPS_FEAT_FRC511PEX; break; case PCPS_TYPE_TCR170PEX: + pddev->builtin_features = BUILTIN_FEAT_TCR170PEX; pddev->dev.cfg.features = PCPS_FEAT_TCR170PEX; break; case PCPS_TYPE_WWVB51USB: + pddev->builtin_features = BUILTIN_FEAT_WWVB511; pddev->dev.cfg.features = PCPS_FEAT_WWVB51USB; break; case PCPS_TYPE_GPS180PEX: + pddev->builtin_features = BUILTIN_FEAT_GPS180PEX; pddev->dev.cfg.features = PCPS_FEAT_GPS180PEX; break; case PCPS_TYPE_TCR180PEX: + pddev->builtin_features = BUILTIN_FEAT_TCR180PEX; pddev->dev.cfg.features = PCPS_FEAT_TCR180PEX; break; case PCPS_TYPE_DCF600USB: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_DCF600USB; break; case PCPS_TYPE_PZF180PEX: + pddev->builtin_features = BUILTIN_FEAT_PZF180PEX; pddev->dev.cfg.features = PCPS_FEAT_PZF180PEX; break; case PCPS_TYPE_TCR600USB: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_TCR600USB; break; case PCPS_TYPE_MSF600USB: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_MSF600USB; break; case PCPS_TYPE_WVB600USB: + pddev->builtin_features = BUILTIN_FEAT_UNDEFINED; pddev->dev.cfg.features = PCPS_FEAT_WVB600USB; break; case PCPS_TYPE_GLN180PEX: + pddev->builtin_features = BUILTIN_FEAT_GLN180PEX; pddev->dev.cfg.features = PCPS_FEAT_GLN180PEX; break; case PCPS_TYPE_GPS180AMC: + pddev->builtin_features = BUILTIN_FEAT_GPS180AMC; pddev->dev.cfg.features = PCPS_FEAT_GPS180AMC; break; case PCPS_TYPE_GNS181PEX: + pddev->builtin_features = BUILTIN_FEAT_GNS181PEX; pddev->dev.cfg.features = PCPS_FEAT_GNS181PEX; break; @@ -4320,7 +4609,7 @@ receiver_info_done: p_ri->flags ); #endif -#if 0 //##+++++++++ check if this is reasonnable +#if 0 //###+++++++++ TODO check if this is reasonable // Make sure this program supports at least as many ports as // the current clock device. @@ -4346,7 +4635,7 @@ receiver_info_done: _pcps_ddev_type_name( pddev ), _pcps_ddev_fw_rev_num( pddev ), (ulong) *_ri_addr( pddev ).features ); - check_ri_features( pddev, _ri_addr( pddev ) ); + check_ri_features( pddev ); _mbgddmsg_3( MBG_DBG_INIT_DEV, "%s v%03X actual features 1: 0x%08lX", _pcps_ddev_type_name( pddev ), _pcps_ddev_fw_rev_num( pddev ), @@ -4354,11 +4643,54 @@ receiver_info_done: #if !defined( MBG_TGT_OS2 ) && !defined( MBG_TGT_BSD ) // Function strstr may not be supported at kernel level, - // but this is not required, in most cases, either. + // but this is not required, in most cases, anyway. if ( strstr( _pcps_ddev_fw_id( pddev ), "CERN" ) != NULL ) pddev->dev.cfg.features |= PCPS_HAS_EVENT_TIME; #endif + + // Check if the device supports extended features + + rc = pcps_chk_dev_feat( pddev, DEV_FEAT_REQ_TYPE_RI, GPS_FEAT_XFEATURE ); + + if ( mbg_rc_is_success( rc ) ) + { + _mbgddmsg_1( MBG_DBG_INIT_DEV, "%s going to read XFEATURE_BUFFER", _pcps_ddev_type_name( pddev ) ); + + rc = _pcps_read_gps_var( pddev, PC_GPS_XFEATURE_BUFFER, *_xfeat_addr( pddev ) ); + + if ( mbg_rc_is_error( rc ) ) + { + #if defined( MBG_TGT_LINUX ) + printk( KERN_ERR "%s: failed to read XFEATURE_BUFFER from device %s\n", + pcps_driver_name, _pcps_ddev_type_name( pddev ) ); + #endif + memset( _xfeat_addr( pddev ), 0, sizeof( *_xfeat_addr( pddev ) ) ); + } + } + + + // Check if the device supports the TLV API + + rc = pcps_chk_dev_feat( pddev, DEV_FEAT_REQ_TYPE_XFEAT, MBG_XFEATURE_TLV_API ); + + if ( mbg_rc_is_success( rc ) ) + { + _mbgddmsg_1( MBG_DBG_INIT_DEV, "%s going to read TLV_INFO", _pcps_ddev_type_name( pddev ) ); + + rc = _pcps_read_gps_var( pddev, PC_GPS_TLV_INFO, *_tlv_info_addr( pddev ) ); + + if ( mbg_rc_is_error( rc ) ) + { + #if defined( MBG_TGT_LINUX ) + printk( KERN_ERR "%s: failed to read TLV_INFO from device %s\n", + pcps_driver_name, _pcps_ddev_type_name( pddev ) ); + #endif + memset( _tlv_info_addr( pddev ), 0, sizeof( *_tlv_info_addr( pddev ) ) ); + } + } + + #if DEBUG_IO && defined( MBG_TGT_LINUX ) { PCPS_TIME t = { 0 }; @@ -4419,11 +4751,18 @@ fail_with_cleanup: fail: return MBG_ERR_GENERIC; -} // pcps_start_device +} // pcps_probe_device /*HDR*/ +/** + * @brief Clean up function called by ::pcps_probe_device on error + * + * @param[in,out] pddev Pointer to the device structure + * + * @see ::pcps_probe_device + */ void pcps_cleanup_device( PCPS_DDEV *pddev ) { pddev->read = pcps_read_null; @@ -4440,13 +4779,24 @@ void pcps_cleanup_device( PCPS_DDEV *pddev ) -/*-------------------------------------------------------------- - * PCI functions - *-------------------------------------------------------------*/ - #if _PCPS_USE_PCI_BIOS static /*HDR*/ +/** + * @brief Read PCI recources for a PCI device on non-PnP systems + * + * This function should be called by the probe routines of any + * target-specific kernel drivers. + * If the device is supported then all specific information including + * supported features is read from the device and stored in sub-structures + * of the device structure addressed by pdev. + * + * @param[in] bus_num The PCI bus number + * @param[in] dev_fnc_num The PCI device/function number + * @param[in,out] pddev Pointer to the device structure to be set up + * + * @return 0 on success, or a combination of @ref PCPS_ERR_FLAG_MASKS masks on error + */ PCPS_ERR_FLAGS pcps_read_pci_rsrc( PCPS_BUS_NUM bus_num, PCPS_SLOT_NUM dev_fnc_num, PCPS_DDEV *pddev ) @@ -4505,20 +4855,36 @@ done: static /*HDR*/ +/** + * @brief Enable a PCI device which has not yet been enabled + * + * In PnP systems only PCI devices that are required for booting + * are always enabled by the PCI BIOS. Other PCI devices may only + * be fully enabled if a PC BIOS setup option "PNP OS installed" + * is set to "NO". + * If this option is set to "YES" then I/O access to the board + * may still be disabled, and a PnP operating system is expected + * to enable remaining devices when it boots up. + * Drivers can call this function to enable I/O and memory access, + * if required, in case this hasn't been done by the PCI BIOS + * or operating system. + * + * @param[in] bus_num The PCI bus number + * @param[in] dev_fnc_num The PCI device/function number + * @param[in] num_rsrc_mem If != 0 then memory access is also enabled + * + * @return 0 on success, or a combination of @ref PCPS_ERR_FLAG_MASKS masks on error + */ PCPS_ERR_FLAGS pcps_enable_pci_dev( PCPS_BUS_NUM bus_num, PCPS_SLOT_NUM dev_fnc_num, int num_rsrc_mem ) { PCPS_ERR_FLAGS err_flags = 0; - uint16_t pci_command; - uint16_t new_pci_command; + uint16_t pci_command; // current value read from the PCI cfg "command" register + uint16_t new_pci_command; // new value to be written to the PCI cfg "command" register int rc; - // If the option "PNP OS installed" is set to "YES" in the - // PC's BIOS setup, then I/O access to the board may still - // be disabled, so check if the clock is enabled and enable - // access to the board, if nessessary. rc = _mbg_pci_read_cfg_word( bus_num, dev_fnc_num, PCI_CS_COMMAND, &pci_command ); new_pci_command = pci_command | PCI_CMD_ENB_IO_ACC; @@ -4546,6 +4912,13 @@ PCPS_ERR_FLAGS pcps_enable_pci_dev( PCPS_BUS_NUM bus_num, /*HDR*/ +/** + * @brief Setup and start a PCI device in a non-PnP system + * + * @param[in,out] pddev Pointer to the device structure to be set up + * @param[in] bus_num The PCI bus number returned by the PCI BIOS + * @param[in] dev_fnc_num The PCI device/function number returned by the PCI BIOS + */ void pcps_setup_and_start_pci_dev( PCPS_DDEV *pddev, PCPS_BUS_NUM bus_num, PCPS_SLOT_NUM dev_fnc_num ) { @@ -4561,17 +4934,26 @@ void pcps_setup_and_start_pci_dev( PCPS_DDEV *pddev, _pcps_ddev_set_err_flags( pddev, err_flags ); } - pcps_start_device( pddev, bus_num, dev_fnc_num ); + pcps_probe_device( pddev, bus_num, dev_fnc_num ); } // pcps_setup_and_start_pci_dev /*HDR*/ -void pcps_detect_pci_clocks( PCPS_DDEV_ALLOC_FNC *alloc_fnc, void *alloc_arg, - PCPS_DDEV_CLEANUP_FNC *cleanup_fnc, - ushort vendor_id, PCPS_DEV_TYPE dev_type[], - int n_dev_types ) +/** + * @brief Detect and initialize PCI devices in a non-PnP system + * + * @param[in] alloc_fnc Pointer to function called to allocate a device structure for each detected device. + * @param[in] cleanup_fnc Pointer to function called if the device structure needs to be de-allocated in case of error. + * @param[in] vendor_id The PCI vendor ID code. + * @param[in] dev_type An array with known PCI devices for the specified vendor ID + * @param[in] n_dev_types The number of entries in the PCI device table + */ +void pcps_detect_pci_devices( PCPS_DDEV_ALLOC_FNC *alloc_fnc, + PCPS_DDEV_CLEANUP_FNC *cleanup_fnc, + ushort vendor_id, PCPS_DEV_TYPE dev_type[], + int n_dev_types ) { #if defined( MBG_TGT_QNX ) #if defined( MBG_TGT_QNX_NTO ) @@ -4676,26 +5058,29 @@ void pcps_detect_pci_clocks( PCPS_DDEV_ALLOC_FNC *alloc_fnc, void *alloc_arg, _mbg_pci_fnc_deinit(); #endif - (void) alloc_arg; // avoid compiler warning - -} // pcps_detect_pci_clocks +} // pcps_detect_pci_devices #endif // _PCPS_USE_PCI_BIOS -/*-------------------------------------------------------------- - * Try to detect ISA clocks - *-------------------------------------------------------------*/ - #if !_PCPS_USE_ISA_PNP /*HDR*/ -void pcps_detect_isa_clocks( PCPS_DDEV_ALLOC_FNC *alloc_fnc, - PCPS_DDEV_CLEANUP_FNC *cleanup_fnc, - PCPS_DDEV_REGISTER_FNC *register_fnc, - int isa_ports[PCPS_MAX_ISA_CARDS], - int isa_irqs[PCPS_MAX_ISA_CARDS] ) +/** + * @brief Detect and initialize ISA devices in a non-PnP system + * + * @param[in] alloc_fnc Pointer to function called to allocate a device structure for each detected device. + * @param[in] cleanup_fnc Pointer to function called if the device structure needs to be de-allocated in case of error. + * @param[in] register_fnc Pointer to function called to register a detected device. + * @param[in] isa_ports An array with potential I/O base addresses for ISA devices. + * @param[in] isa_irqs An array with potential IRQ numbers assigned to ISA devices. + */ +void pcps_detect_isa_devices( PCPS_DDEV_ALLOC_FNC *alloc_fnc, + PCPS_DDEV_CLEANUP_FNC *cleanup_fnc, + PCPS_DDEV_REGISTER_FNC *register_fnc, + int isa_ports[PCPS_MAX_ISA_CARDS], + int isa_irqs[PCPS_MAX_ISA_CARDS] ) { int *p_port = isa_ports; int *p_irq = isa_irqs; @@ -4737,7 +5122,7 @@ void pcps_detect_isa_clocks( PCPS_DDEV_ALLOC_FNC *alloc_fnc, // Init the device structure. This includes registration // of I/O ports with the OS's resource manager (if supported), // and reading the firmware ID. - pcps_start_device( pddev, 0, 0 ); + pcps_probe_device( pddev, 0, 0 ); // If an error has occurred, then remove the last // device from the list and try next. @@ -4758,7 +5143,7 @@ void pcps_detect_isa_clocks( PCPS_DDEV_ALLOC_FNC *alloc_fnc, } } -} // pcps_detect_isa_clocks +} // pcps_detect_isa_devices #endif //!_PCPS_USE_ISA_PNP @@ -4766,48 +5151,60 @@ void pcps_detect_isa_clocks( PCPS_DDEV_ALLOC_FNC *alloc_fnc, #if !_PCPS_USE_PNP -/*-------------------------------------------------------------- - * Try to detect any plug-in device. If a DOS TSR is - * installed, be sure it is disabled (BUSY flag set) when - * this function is called. - *-------------------------------------------------------------*/ - -/*HDR*/ -void _MBG_INIT_CODE_ATTR pcps_detect_clocks_alloc( PCPS_DDEV_ALLOC_FNC *alloc_fnc, - void *alloc_arg, - PCPS_DDEV_CLEANUP_FNC *cleanup_fnc, - int isa_ports[PCPS_MAX_ISA_CARDS], - int isa_irqs[PCPS_MAX_ISA_CARDS] ) +static /*HDR*/ +/** + * @brief Detect all bus-level devices in a non-PnP system, use specific alloc/cleanup functions + * + * @note If a DOS TSR is installed, be sure it is disabled (BUSY flag set) + * when this function is called. + * + * @param[in] alloc_fnc Pointer to function called to allocate a device structure for each detected device. + * @param[in] cleanup_fnc Pointer to function called if the device structure needs to be de-allocated in case of error. + * @param[in] isa_ports An array with potential I/O base addresses for ISA devices. + * @param[in] isa_irqs An array with potential IRQ numbers assigned to ISA devices. + */ +void _MBG_INIT_CODE_ATTR pcps_detect_devices_alloc( PCPS_DDEV_ALLOC_FNC *alloc_fnc, + PCPS_DDEV_CLEANUP_FNC *cleanup_fnc, + int isa_ports[PCPS_MAX_ISA_CARDS], + int isa_irqs[PCPS_MAX_ISA_CARDS] ) { #if defined( MBG_TGT_OS2 ) rsrc_register_driver(); // register driver and init resource manager #endif #if _PCPS_USE_PCI_BIOS - pcps_detect_pci_clocks( alloc_fnc, alloc_arg, cleanup_fnc, - PCI_VENDOR_MEINBERG, pcps_dev_type, N_PCPS_DEV_TYPE ); + pcps_detect_pci_devices( alloc_fnc, cleanup_fnc, PCI_VENDOR_MEINBERG, + pcps_dev_type, N_PCPS_DEV_TYPE ); #endif #if _PCPS_USE_MCA - pcps_detect_mca_clocks( alloc_fnc, alloc_arg ); + pcps_detect_mca_devices( alloc_fnc ); #endif #if !_PCPS_USE_ISA_PNP - pcps_detect_isa_clocks( alloc_fnc, cleanup_fnc, NULL, isa_ports, isa_irqs ); + pcps_detect_isa_devices( alloc_fnc, cleanup_fnc, NULL, isa_ports, isa_irqs ); #endif -} // pcps_detect_clocks_alloc +} // pcps_detect_devices_alloc /*HDR*/ -void _MBG_INIT_CODE_ATTR pcps_detect_clocks( int isa_ports[PCPS_MAX_ISA_CARDS], - int isa_irqs[PCPS_MAX_ISA_CARDS] ) +/** + * @brief Detect all bus-level devices in a non-PnP system + * + * @note If a DOS TSR is installed, be sure it is disabled (BUSY flag set) + * when this function is called. + * + * @param[in] isa_ports An array with potential I/O base addresses for ISA devices. + * @param[in] isa_irqs An array with potential IRQ numbers assigned to ISA devices. + */ +void _MBG_INIT_CODE_ATTR pcps_detect_devices( int isa_ports[PCPS_MAX_ISA_CARDS], + int isa_irqs[PCPS_MAX_ISA_CARDS] ) { - pcps_detect_clocks_alloc( pcps_alloc_ddev, NULL, pcps_free_ddev, - isa_ports, isa_irqs ); + pcps_detect_devices_alloc( pcps_alloc_ddev, pcps_free_ddev, isa_ports, isa_irqs ); -} // pcps_detect_clocks +} // pcps_detect_devices #endif // !_PCPS_USE_PNP diff --git a/mbglib/common/pcpsdrvr.h b/mbglib/common/pcpsdrvr.h index 82b1342..405002e 100755 --- a/mbglib/common/pcpsdrvr.h +++ b/mbglib/common/pcpsdrvr.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsdrvr.h 1.45.1.17 2017/04/25 11:36:51 martin TEST $ + * $Id: pcpsdrvr.h 1.46 2017/07/04 16:50:48 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,40 +10,20 @@ * * ----------------------------------------------------------------------- * $Log: pcpsdrvr.h $ - * Revision 1.45.1.17 2017/04/25 11:36:51 martin - * Renamed GRC181PEX to GNS181PEX. - * Revision 1.45.1.16 2017/02/22 15:23:46 martin - * Fixed macro definition syntax to avoid clang compiler warnings. - * Revision 1.45.1.15 2016/09/26 16:24:27 martin - * Revision 1.45.1.14 2016/09/19 14:29:22Z martin - * *** empty log message *** - * Revision 1.45.1.13 2016/09/16 09:57:43 martin - * Use macro _ri_addr(). - * Revision 1.45.1.12 2016/09/15 14:56:18 martin - * Support GRC181PEX. - * Revision 1.45.1.11 2016/09/14 16:20:54 martin - * Use more versatile types for function pointers. - * Prepare to use MBG_XDEV_FEATURES in PCPS_DDEV. - * Updated function prototypes. - * Revision 1.45.1.10 2016/08/09 07:13:04 martin - * *** empty log message *** - * Revision 1.45.1.9 2016/05/30 15:03:47 martin - * Conditional USB debug code. - * Revision 1.45.1.8 2016/01/04 11:24:20 martin - * Revision 1.45.1.7 2015/10/27 16:22:27Z martin + * Revision 1.46 2017/07/04 16:50:48 martin + * Support GPS180AMC and GNS181PEX. + * Support new module parameter force_io_access to provide + * runtime support for forcing I/O rather than MM access. + * Cleaned up I/O port usage. + * Added _pcps_ddev_has_xmr() macro. * Older defines N_SUPP_DEV, PCPS_MAX_DDEVS, and MBG_MAX_DEVICES * have been obsoleted by new defines N_SUPP_DEV_BUS, N_SUPP_DEV_EXT, * and N_SUPP_DEV_TOTAL. - * Revision 1.45.1.6 2014/05/22 14:54:35 martin - * Added _pcps_ddev_has_xmr() macro. - * Revision 1.45.1.5 2014/04/15 15:35:24 martin - * Support GPIO ports. - * Revision 1.45.1.4 2014/04/07 08:38:52 martin - * Revision 1.45.1.3 2014/03/20 16:40:39 martin - * Support new module parameter force_io_access. - * Revision 1.45.1.2 2014/01/23 15:35:49 martin - * Support GPS180AMC. - * Revision 1.45.1.1 2013/12/18 14:46:29 martin + * Conditional USB debug code. + * Use more versatile types for function pointers. + * Fixed macro definition syntax to avoid clang compiler warnings. + * Prepare to use MBG_XDEV_FEATURES in PCPS_DDEV. + * Updated function prototypes. * Revision 1.45 2013/09/26 09:08:09 martin * Support GLN180PEX and GNSS API. * Revision 1.44 2013/03/15 10:01:09 martin @@ -266,6 +246,7 @@ #define DEBUG_LVL_IO 12 +/* Other headers to be included */ #include <mbg_tgt.h> #include <xdevfeat.h> @@ -402,8 +383,6 @@ #endif - -/* Other headers to be included */ #include <pcpsdev.h> #include <cfg_hlp.h> #include <mbgmutex.h> @@ -413,7 +392,6 @@ #include <mbggenio.h> #if defined( MBG_TGT_FREEBSD ) -// #include <mbg_bsd.h> #include <sys/malloc.h> #include <sys/_null.h> #include <sys/param.h> @@ -528,11 +506,10 @@ extern "C" { #if defined( MBG_TGT_LINUX ) - #define _pcps_kmalloc( _sz ) kmalloc( _sz, GFP_ATOMIC ) - #define _pcps_kfree( _p, _sz ) kfree( _p ) + #define _pcps_kmalloc( _sz ) kmalloc( _sz, GFP_ATOMIC ) + #define _pcps_kfree( _p, _sz ) kfree( _p ) - //##+++++++++++++++++++ - // The special versions of _pcps_sem_inc() and _pcps_sem_dec() below + // These special versions of _pcps_sem_inc() and _pcps_sem_dec() // are only required to prevent interference with the IRQ handler // under Linux which implements the serial port emulation for the // NTP parse driver. @@ -559,20 +536,20 @@ extern "C" { // See "man 9 malloc" for details. MALLOC_DECLARE( M_MBGCLOCK ); - #define _pcps_kmalloc( _sz ) malloc( _sz, M_MBGCLOCK, M_NOWAIT | M_ZERO ) - #define _pcps_kfree( _p, _sv ) free( _p, M_MBGCLOCK ) + #define _pcps_kmalloc( _sz ) malloc( _sz, M_MBGCLOCK, M_NOWAIT | M_ZERO ) + #define _pcps_kfree( _p, _sv ) free( _p, M_MBGCLOCK ) #elif defined( MBG_TGT_NETBSD ) // For older NetBSD versions which do not suppport the calls // used below, see 'man 9 malloc'. - #define _pcps_kmalloc( _sz ) kmem_alloc( _sz, KM_NOSLEEP ) - #define _pcps_kfree( _p, _sz ) kmem_free( _p, _sz ) + #define _pcps_kmalloc( _sz ) kmem_alloc( _sz, KM_NOSLEEP ) + #define _pcps_kfree( _p, _sz ) kmem_free( _p, _sz ) #elif defined( MBG_TGT_WIN32 ) - #define _pcps_kmalloc( _sz ) ExAllocatePool( NonPagedPool, _sz ) - #define _pcps_kfree( _p, _sz ) ExFreePool( _p ) + #define _pcps_kmalloc( _sz ) ExAllocatePool( NonPagedPool, _sz ) + #define _pcps_kfree( _p, _sz ) ExFreePool( _p ) #elif defined( MBG_TGT_DOS ) @@ -598,7 +575,7 @@ extern "C" { -// If the macros below have not yet been defined then define some dummies: +// If these macros have not yet been defined then define some dummies: #if !defined( _pcps_sem_inc ) || !defined( _pcps_sem_dec ) @@ -612,9 +589,7 @@ extern "C" { -/* ------ definitions used with PCI clocks -------------------------- */ - -/* Default timeout count accessing the board */ +// Default timeout count when accessing a device #if _PCPS_USE_CLOCK_TICK #if defined( MBG_TGT_NETWARE ) @@ -635,10 +610,10 @@ extern "C" { #endif -// The structures below are used to provide a consistent +// These structures are used to provide a consistent // resource handling across different platforms. -// This is kept completely inside the kernel drivers, so these -// structures can be modified safely to suit our needs. +// This is kept completely inside the kernel drivers, so the +// structures can be modified safely, as appropriate. #if MBG_USE_MM_IO_FOR_PCI @@ -658,7 +633,11 @@ extern "C" { #else - typedef PCPS_PORT_ADDR PCPS_IO_ADDR_RAW; + #if !defined( MBG_TGT_POSIX ) || defined( MBG_ARCH_X86 ) + typedef uint16_t PCPS_IO_ADDR_RAW; ///< ### TODO ::PCPS_PORT_ADDR_X + #else + typedef uint64_t PCPS_IO_ADDR_RAW; + #endif typedef PCPS_IO_ADDR_RAW PCPS_IO_ADDR_MAPPED; #if defined( MBG_TGT_BSD ) @@ -678,17 +657,17 @@ typedef struct { #if defined( MBG_TGT_FREEBSD ) int rid; /* resource ID */ - struct resource *res; - bus_space_tag_t bst; - bus_space_handle_t bsh; + struct resource *res; ///< Resource information + bus_space_tag_t bst; ///< Bus space tag + bus_space_handle_t bsh; ///< Bus space handle #elif defined( MBG_TGT_NETBSD ) - int reg; /* BAR */ - int type; /* type */ - int valid; /* valid flag */ - bus_space_tag_t bst; /* bus space tag */ - bus_space_handle_t bsh; /* bus space handle */ - bus_addr_t base; /* base address */ - bus_size_t size; /* size */ + int reg; ///< Base Address Register (BAR) + int type; ///< Type + int valid; ///< Valid flag + bus_space_tag_t bst; ///< Bus space tag + bus_space_handle_t bsh; ///< Bus space handle + bus_addr_t base; ///< Base address + bus_size_t size; ///< Size #endif } BSD_RSRC_INFO; @@ -697,27 +676,33 @@ typedef struct /** - The structure below describes an I/O port resource - used by a clock. -*/ + * @brief I/O port resource information for a device + * + * @see ::PCPS_MEM_RSRC + * @see ::PCPS_IRQ_RSRC + */ typedef struct { #if defined( MBG_TGT_BSD ) - BSD_RSRC_INFO bsd; + BSD_RSRC_INFO bsd; ///< *BSD-specific stuff #endif - PCPS_IO_ADDR_MAPPED base_mapped; - PCPS_IO_ADDR_RAW base_raw; - uint16_t num; -} PCPS_IO_RSRC; + PCPS_IO_ADDR_MAPPED base_mapped; ///< A mapped port base address + PCPS_IO_ADDR_RAW base_raw; ///< A raw port base address + ulong num; ///< Number of addresses in this range +} PCPS_IO_RSRC; -// The structure below describes a bus memory resource -// used by a clock. +/** + * @brief Bus memory resource information for a device + * + * @see ::PCPS_IO_RSRC + * @see ::PCPS_IRQ_RSRC + */ typedef struct { #if defined( MBG_TGT_BSD ) - BSD_RSRC_INFO bsd; + BSD_RSRC_INFO bsd; ///< *BSD-specific stuff #endif MBG_MEM_ADDR start; ulong len; @@ -725,84 +710,104 @@ typedef struct } PCPS_MEM_RSRC; - -// The structure below describes a bus IRQ resource -// used by a clock. - +/** + * @brief IRQ resource information for a device + * + * @see ::PCPS_IO_RSRC + * @see ::PCPS_MEM_RSRC + */ typedef struct { #if defined( MBG_TGT_BSD ) - BSD_RSRC_INFO bsd; + BSD_RSRC_INFO bsd; ///< *BSD-specific stuff #endif - ushort num; + uint16_t num; ///< The IRQ number } PCPS_IRQ_RSRC; -// The max number of bus memory resources used by a device. +/** + * @brief The max number of bus memory resources used by a device. + */ #define N_PCPS_MEM_RSRC 2 -// The max number of bus memory and I/O resources used by a device. + +/** + * @brief The max number of bus memory and I/O resources used by a device. + */ #define MAX_PCPS_RSRC ( N_PCPS_MEM_RSRC + N_PCPS_PORT_RSRC ) + +/** + * @brief Resource info summary for a device + */ typedef struct { - int num_rsrc_io; - int num_rsrc_mem; - int num_rsrc_irq; - PCPS_IO_RSRC port[N_PCPS_PORT_RSRC]; - PCPS_MEM_RSRC mem[N_PCPS_MEM_RSRC]; - PCPS_IRQ_RSRC irq; + int num_rsrc_io; ///< Number of actually assigned I/O address ranges + int num_rsrc_mem; ///< Number of actually assigned memory address ranges + int num_rsrc_irq; ///< Number of actually assigned IRQ numbers + PCPS_IO_RSRC port[N_PCPS_PORT_RSRC]; ///< Info on actually assigned port ranges + PCPS_MEM_RSRC mem[N_PCPS_MEM_RSRC]; ///< Info on actually assigned memory ranges + PCPS_IRQ_RSRC irq; ///< Info on actually assigned IRQ numbers + } PCPS_RSRC_INFO; #if _PCPS_USE_USB - typedef struct - { - uint8_t addr; - uint16_t max_packet_size; - } PCPS_USB_EP; +/** + * @brief Information on a USB endpoint + */ +typedef struct +{ + uint8_t addr; + uint16_t max_packet_size; +} PCPS_USB_EP; - #if defined( MBG_TGT_LINUX ) - // definitions used to control the cyclic USB read thread +#if defined( MBG_TGT_LINUX ) + + // definitions used to control the cyclic USB read thread - #if _PCPS_USE_LINUX_KTHREAD + #if _PCPS_USE_LINUX_KTHREAD - // use kthread_run() / kthread_stop() - typedef struct task_struct *PCPS_THREAD_INFO; + // Used by kthread_run() / kthread_stop() + typedef struct task_struct *PCPS_THREAD_INFO; - #else + #else - // use kernel_thread() / daemonize() / kill_proc() - typedef struct - { - pid_t pid; - char name[17]; // 16 chars as supported by the kernel, plus trailing 0 - struct completion exit; - } PCPS_THREAD_INFO; + // Used by kernel_thread() / daemonize() / kill_proc() + typedef struct + { + pid_t pid; + char name[17]; // 16 chars as supported by the kernel, plus trailing 0 + struct completion exit; - #endif // _PCPS_USE_LINUX_KTHREAD + } PCPS_THREAD_INFO; - #endif // defined( MBG_TGT_LINUX ) + #endif // _PCPS_USE_LINUX_KTHREAD + +#endif // defined( MBG_TGT_LINUX ) #endif // _PCPS_USE_USB +/** + * @brief Memory layout of Meinberg PCI interface register + */ typedef union { - struct + struct pex8311 { PCI_ASIC asic; PCPS_TIME_STAMP tstamp; } pex8311; - struct + struct mbgpex { PCI_ASIC asic; uint8_t b[256 - sizeof( PCI_ASIC ) ]; @@ -813,104 +818,102 @@ typedef union } PCPS_MM_LAYOUT; + struct PCPS_DDEV_s; +typedef struct PCPS_DDEV_s PCPS_DDEV; -typedef int PCPS_READ_FNC( struct PCPS_DDEV_s *pddev, uint8_t cmd, void FAR *buffer, uint16_t count ); -typedef int PCPS_WRITE_FNC( struct PCPS_DDEV_s *pddev, uint8_t cmd, const void FAR *buffer, uint16_t count ); -typedef struct PCPS_DDEV_s *PCPS_DDEV_ALLOC_FNC( void ); -typedef void PCPS_DDEV_CLEANUP_FNC( struct PCPS_DDEV_s * ); -typedef int PCPS_DDEV_REGISTER_FNC( struct PCPS_DDEV_s * ); +typedef int PCPS_READ_FNC( PCPS_DDEV *pddev, uint8_t cmd, void FAR *buffer, uint16_t count ); +typedef int PCPS_WRITE_FNC( PCPS_DDEV *pddev, uint8_t cmd, const void FAR *buffer, uint16_t count ); +typedef PCPS_DDEV *PCPS_DDEV_ALLOC_FNC( void ); +typedef void PCPS_DDEV_CLEANUP_FNC( PCPS_DDEV *pddev ); +typedef int PCPS_DDEV_REGISTER_FNC( PCPS_DDEV *pddev ); -typedef struct PCPS_DDEV_s +struct PCPS_DDEV_s { - // the device info data - PCPS_DEV dev; + PCPS_DEV dev; ///< Device info data that can be passed to user space - PCPS_READ_FNC *read; + PCPS_READ_FNC *read; ///< Pointer to the read function depending on the PCI interface type - PCPS_IO_ADDR_MAPPED status_port; - PCPS_IO_ADDR_MAPPED irq_enb_disb_port; - PCPS_IO_ADDR_MAPPED irq_flag_port; - PCPS_IO_ADDR_MAPPED irq_ack_port; - uint32_t irq_enb_mask; - uint32_t irq_disb_mask; - uint32_t irq_flag_mask; - uint32_t irq_ack_mask; + PCPS_IO_ADDR_MAPPED status_port; ///< Address of the status port register + PCPS_IO_ADDR_MAPPED irq_enb_disb_port; ///< Address of the IRQ control register + PCPS_IO_ADDR_MAPPED irq_flag_port; ///< Address of the IRQ status register + PCPS_IO_ADDR_MAPPED irq_ack_port; ///< Address of the register to acknowledge an IRQ + uint32_t irq_enb_mask; ///< Bit mask to be set to enable IRQs + uint32_t irq_disb_mask; ///< Bit mask to be cleared to disable IRQs + uint32_t irq_flag_mask; ///< Bit mask used to check if device has generated an IRQ + uint32_t irq_ack_mask; ///< Bit mask to be set to acknowledge an IRQ - PCI_ASIC_VERSION raw_asic_version; - PCI_ASIC_VERSION asic_version; - PCI_ASIC_FEATURES asic_features; - PCPS_RSRC_INFO rsrc_info; + PCI_ASIC_VERSION raw_asic_version; ///< Raw ASIC version + PCI_ASIC_VERSION asic_version; ///< ASIC version + PCI_ASIC_FEATURES asic_features; ///< ASIC feature mask + PCPS_RSRC_INFO rsrc_info; ///< Summary of resources used by the device - MBG_PC_CYCLES acc_cycles; + MBG_PC_CYCLES acc_cycles; ///< Cycles count taken when device was accessed last time #if defined( _MBG_MUTEX_DEFINED ) - MBG_MUTEX dev_mutex; + MBG_MUTEX dev_mutex; ///< Mutex used for device access serialization #endif - PCPS_MM_LAYOUT FAR *mm_addr; - volatile PCPS_TIME_STAMP FAR *mm_tstamp_addr; + PCPS_MM_LAYOUT FAR *mm_addr; ///< Base address of the memory-mapped register block + volatile PCPS_TIME_STAMP FAR *mm_tstamp_addr; ///< Memory mapped address of the timestamp register #if defined( _MBG_SPINLOCK_DEFINED ) - MBG_SPINLOCK mm_lock; - MBG_SPINLOCK irq_lock; + MBG_SPINLOCK mm_lock; ///< Spinlock used to protect memory mapped access + MBG_SPINLOCK irq_lock; ///< Spinlock used to protect access to data updated by IRQ handler #endif - // The flag below holds IRQ information, e.g. whether the device's - // IRQ is possibly unsafe, and whether IRQ has been enabled on the device. + /// IRQ status information, e.g. whether the device's IRQ is + /// possibly unsafe, and whether IRQ has been enabled on the device. PCPS_IRQ_STAT_INFO irq_stat_info; - MBG_XDEV_FEATURES xdev_features; ///< Receiver info plus extended device features + BUILTIN_FEATURE_MASK builtin_features; ///< Mask of builtin features, depending on device type + MBG_XDEV_FEATURES xdev_features; ///< Receiver info plus extended device features #if _PCPS_USE_MM_IO - int use_mm_io; + int use_mm_io; ///< Flag indicating if memory mapped I/O is being used #endif #if _PCPS_USE_USB - int n_usb_ep; // number of endpoints supp. by the device - PCPS_USB_EP ep[MBGUSB_MAX_ENDPOINTS]; - uint8_t usb_20_mode; + int n_usb_ep; ///< Number of USB endpoints supported by the device + PCPS_USB_EP ep[MBGUSB_MAX_ENDPOINTS]; ///< Array of actual USB endpoints + bool usb_20_mode; ///< Flag indicating if USB 2.0 microframing is supported #endif #if defined( MBG_TGT_WIN32 ) - _pcps_ddev_data_win + _pcps_ddev_data_win ///< Some windows-specific stuff #endif #if defined( MBG_TGT_LINUX ) - atomic_t connected; - atomic_t access_in_progress; - atomic_t data_avail; - unsigned long jiffies_at_irq; - struct fasync_struct *fasyncptr; - PCPS_TIME t; + atomic_t connected; ///< Flag indicating if the device is "connected" + atomic_t access_in_progress; ///< Flag indicating if device access is currently in progress + atomic_t data_avail; ///< Flag indicating if data has been made available by IRQ handler + unsigned long jiffies_at_irq; ///< Set by IRQ handler, used to check if cyclic IRQs still occur + struct fasync_struct *fasyncptr; ///< Used for asynchronous signalling when data is available + PCPS_TIME t; ///< Date and time read by IRQ handler #if NEW_WAIT_QUEUE - wait_queue_head_t wait_queue; + wait_queue_head_t wait_queue; ///< Used for asynchronous I/O (newer kernel API) #else - struct wait_queue *wait_queue; + struct wait_queue *wait_queue; ///< Used for asynchronous I/O (older kernel API) #endif - dev_t lx_dev; - atomic_t open_count; + atomic_t open_count; ///< Number of processes that have opened this device - #if _PCPS_USE_LINUX_CHRDEV - struct cdev cdev; - #elif _PCPS_USE_LINUX_MISC_DEV - struct miscdevice mdev; - #endif + struct cdev cdev; ///< Linux device class + dev_t lx_dev; ///< Linux device associated with this device #if _PCPS_USE_USB - struct usb_device *udev; - struct usb_interface *intf; - PCPS_THREAD_INFO usb_read_thread; - struct semaphore sem_usb_cyclic; + struct usb_device *udev; ///< Linux USB device associated with this device + struct usb_interface *intf; ///< Linux USB interface associated with this device + PCPS_THREAD_INFO usb_read_thread; ///< Kernel thread to receive cyclic USB messages + struct semaphore sem_usb_cyclic; ///< Semaphore used for cyclic USB messages #endif #endif #if defined( MBG_TGT_BSD ) - int connected; - int open_count; + int connected; ///< BSD flag indicating if the device is "connected" + int open_count; ///< BSD number of processes that have opened this device #endif #if _PCPS_USE_RSRCMGR @@ -919,59 +922,69 @@ typedef struct PCPS_DDEV_s RSRC_LIST rsrc; #endif #endif - -} PCPS_DDEV; +}; -/* The PCI vendor ID and device ID numbers are used to detect a - * PCI clock in a system and query which resources have been - * assigned by the BIOS. - * (PCI vendor ID and PCI device IDs are defined in PCPSDEFS.H) +/** + * @brief The number of address lines decoded by a PCI clock */ - -/* the number of address lines decoded by a PCI clock */ #define PCPS_DECODE_WIDTH_PCI 16 /* ------ definitions used with MCA clocks -------------------------- */ -/* The MCA adapter ID number is used to detect a MCA clock in a +/* + * The MCA adapter ID number is used to detect a MCA clock in a * system and query which resources have been assigned by the * system's POS (programmable option select). */ -/* MCA Adapter ID numbers */ -#define MCA_ID_PS31 0x6AAC /* assigned by IBM */ -#define MCA_ID_PS31_OLD 0x6303 /* assigned by Meinberg, used with */ - /* the first series of PS31 boards */ +#define MCA_ID_PS31 0x6AAC ///< MCA adapter ID assigned by IBM +#define MCA_ID_PS31_OLD 0x6303 ///< MCA adapter ID assigned by Meinberg, used with the first series of PS31 boards -/* the total number of ports acquired by a MCA clock */ +/** + * @brief The total number of ports acquired by an MCA device + */ #define PCPS_NUM_PORTS_MCA 16 -/* the number of address lines decoded by a MCA clock */ +/** + * @brief The number of address lines decoded by an MCA device + */ #define PCPS_DECODE_WIDTH_MCA 16 /* ------ definitions used with ISA clocks -------------------------- */ -/* A board ID for the newer clocks with ISA bus. The number can - * be read at port_base+2 (low byte) and port_base+3 (high byte) - * of ISA clocks. This ID number matches the MCA adapter ID - * defined above and is not available on PC31 clocks. +/** + * @brief A board ID for later ISA bus devices + * + * The number can be read at port_base + 2 (low byte), and + * port_base + 3 (high byte) of ISA devices. This ID number + * matches the MCA adapter ID ::MCA_ID_PS31 and is not + * provided by PC31 devices. */ #define ISA_ID_PCPS MCA_ID_PS31 -/* The default port base address for ISA clocks. - * Some programs assume a default port for an ISA clock, - * others do not but require a cmd line parameter. + +/** + * @brief The default port base address for ISA bus devices + * + * Some programs assume a default port for an ISA default, + * but others do not but require a cmd line parameter. */ #define PCPS_DEFAULT_PORT 0x0300 -/* the total number of ports acquired by a ISA clock */ + +/** + * @brief The total number of I/O ports used by an ISA bus device + */ #define PCPS_NUM_PORTS_ISA 4 -/* the number of address lines decoded by a ISA clock */ + +/** + * @brief The number of address lines decoded by an ISA bus device + */ #define PCPS_DECODE_WIDTH_ISA 10 @@ -1055,8 +1068,10 @@ _ext int pcps_isa_ports[PCPS_MAX_ISA_CARDS + 1]; ; #endif -/* the first characters of a valid EPROM ID */ +/** + * @brief The first characters of a valid firmware ID + */ _ext const char *fw_id_ref[] #ifdef _DO_INIT = { @@ -1078,8 +1093,7 @@ _ext const char *fw_id_ref[] ; -// The macros below are used to distinguish ISA cards: - +// These macros are used to distinguish ISA cards: #define fw_id_ref_pcps fw_id_ref[0] #define fw_id_ref_gps fw_id_ref[2] @@ -1089,7 +1103,7 @@ _ext const char *fw_id_ref[] #endif -// The macros below accept a (PCPS_DDEV *) for easy access +// These macros accept a (PCPS_DDEV *) for easy access // to the information stored in PCPS_DDEV structures. // Access device type information: @@ -1100,6 +1114,7 @@ _ext const char *fw_id_ref[] #define _pcps_ddev_bus_flags( _p ) _pcps_bus_flags( &(_p)->dev ) // Query device type features: + #define _pcps_ddev_is_gps( _p ) _pcps_is_gps( &(_p)->dev ) #define _pcps_ddev_is_dcf( _p ) _pcps_is_dcf( &(_p)->dev ) #define _pcps_ddev_is_msf( _p ) _pcps_is_msf( &(_p)->dev ) @@ -1132,12 +1147,14 @@ _ext const char *fw_id_ref[] #define _pcps_ddev_bus_num( _p ) _pcps_bus_num( &(_p)->dev ) #define _pcps_ddev_slot_num( _p ) _pcps_slot_num( &(_p)->dev ) -#define _pcps_ddev_port_rsrc( _p, _n ) _pcps_port_rsrc( &(_p)->dev, _n ) -#define _pcps_ddev_port_base( _p, _n ) _pcps_port_base( &(_p)->dev, _n ) -#define _pcps_ddev_io_rsrc( _p, _n ) ( (_p)->rsrc_info.port[_n] ) -#define _pcps_ddev_io_base_mapped( _p, _n ) ( _pcps_ddev_io_rsrc( _p, _n ).base_mapped ) -#define _pcps_ddev_irq_num( _p ) _pcps_irq_num( &(_p)->dev ) -#define _pcps_ddev_timeout_clk( _p ) _pcps_timeout_clk( &(_p)->dev ) +#define _pcps_ddev_short_port_rsrc( _p, _n ) _pcps_short_port_rsrc( &(_p)->dev, _n ) +#define _pcps_ddev_short_port_base( _p, _n ) _pcps_short_port_base( &(_p)->dev, _n ) + +#define _pcps_ddev_io_rsrc( _p, _n ) ( (_p)->rsrc_info.port[_n] ) +#define _pcps_ddev_io_base_raw( _p, _n ) ( _pcps_ddev_io_rsrc( _p, _n ).base_raw ) +#define _pcps_ddev_io_base_mapped( _p, _n ) ( _pcps_ddev_io_rsrc( _p, _n ).base_mapped ) +#define _pcps_ddev_irq_num( _p ) _pcps_irq_num( &(_p)->dev ) +#define _pcps_ddev_timeout_clk( _p ) _pcps_timeout_clk( &(_p)->dev ) #define _pcps_ddev_fw_rev_num( _p ) _pcps_fw_rev_num( &(_p)->dev ) #define _pcps_ddev_features( _p ) _pcps_features( &(_p)->dev ) @@ -1147,7 +1164,7 @@ _ext const char *fw_id_ref[] #define _pcps_ddev_raw_asic_version( _p ) ( (_p)->raw_asic_version ) #define _pcps_ddev_asic_version( _p ) ( (_p)->asic_version ) -// The macros below handle the device's err_flags. +// These macros handle the device's err_flags: #define _pcps_ddev_chk_err_flags( _p, _msk ) \ _pcps_chk_err_flags( &(_p)->dev, _msk ) @@ -1158,9 +1175,7 @@ _ext const char *fw_id_ref[] _pcps_clr_err_flags( &(_p)->dev, _msk ) -// Query whether a special feature is supported: -#define _pcps_ddev_has_feature( _p, _f ) _pcps_has_feature( &(_p)->dev, _f ) - +// Query whether a specific feature is supported: #define _pcps_ddev_can_set_time( _p ) _pcps_can_set_time( &(_p)->dev ) #define _pcps_ddev_has_serial( _p ) _pcps_has_serial( &(_p)->dev ) #define _pcps_ddev_has_sync_time( _p ) _pcps_has_sync_time( &(_p)->dev ) @@ -1180,7 +1195,7 @@ _ext const char *fw_id_ref[] #define _pcps_ddev_has_ucap( _p ) _pcps_has_ucap( &(_p)->dev ) #define _pcps_ddev_has_irig_tx( _p ) _pcps_has_irig_tx( &(_p)->dev ) -// The macro below determines whether a DCF77 clock +// This macro determines whether a DCF77 clock // supports a higher baud rate than standard #define _pcps_ddev_has_serial_hs( _p ) \ _pcps_has_serial_hs( &(_p)->dev ) @@ -1283,7 +1298,7 @@ _ext const char *fw_id_ref[] _pcps_has_ri_xmr( _ri_addr( _p ) ) -// The macros below simplify read/write access to the clocks. +// These macros simplify read/write access to the clocks. // Call the device's read function to write the command byte _cmd // and read _n bytes to buffer _s. @@ -1293,7 +1308,8 @@ _ext const char *fw_id_ref[] #endif // Write a byte _b to a device. This is typically done by just writing -// the command byte from inside the read function. +// the command byte from within the read function, without actually +// reading any data bytes. #if !defined( _pcps_write_byte ) #define _pcps_write_byte( _pddev, _b ) \ _pcps_read( (_pddev), (_b), NULL, 0 ) @@ -1307,21 +1323,22 @@ _ext const char *fw_id_ref[] pcps_write( (_pddev), (_cmd), (uchar FAR *)(_p), (_n) ) #endif -// Read data structures which exceed PCPS_FIFO_SIZE bytes. -// This can't be handled in a single read cycle and due to limitations -// of the clock's microprocessor these calls can up to 20 milliseconds. -// Currently these function is only used to read GPS specific data -// from GPS clocks. +// Read data structures which exceed ::PCPS_FIFO_SIZE bytes. +// This can't be handled in a single read cycle and due to +// limitations of the device's microprocessor the execution time +// can be up to 20 milliseconds, depending on the device type. +// This has been introduced with the first GPS devices but is +// now in fact also used with non-GPS devices. #define _pcps_read_gps( _pddev, _cmd, _p, _n ) \ pcps_read_gps( (_pddev), (_cmd), (uchar FAR *) (_p), (_n) ) -// The write function opposite to the read function above. +// The complementary write function for the read function above. #define _pcps_write_gps( _pddev, _cmd, _p, _n ) \ pcps_write_gps( (_pddev), (_cmd), (uchar FAR *) (_p), (_n) ) -// The macros below simplify reading/writing typed variables by +// These macros simplify reading/writing typed variables by // determining the size automatically from the type of the variable. // Read data from a device to variable _s. @@ -1345,7 +1362,7 @@ _ext const char *fw_id_ref[] #define _pcps_read_gps_var( _pddev, _cmd, _s ) \ _pcps_read_gps( (_pddev), (_cmd), &(_s), sizeof( (_s) ) ) -// The write function opposite to the read function above. +// The complementary write function for the read function above. #define _pcps_write_gps_var( _pddev, _cmd, _s ) \ _pcps_write_gps( (_pddev), (_cmd), &(_s), sizeof( (_s) ) ) @@ -1357,8 +1374,9 @@ _ext const char *fw_id_ref[] _pcps_write_byte( (_pddev), PCPS_FORCE_RESET ) -// The macro below reads a device's status port which includes -// the BUSY flag and the modulation signal of DCF77 receivers. +// This macro reads a device's status port which includes +// the BUSY flag (::PCPS_ST_BUSY )and the modulation signal +// of DCF77 and other long wave receivers. // The macro takes a (PCPS_DDEV *) as argument. #if _PCPS_USE_MM_IO @@ -1380,8 +1398,8 @@ _ext const char *fw_id_ref[] ( _pcps_ddev_read_status_port( pddev ) & PCPS_ST_BUSY ) -// The macro below checks whether a workaround is required to get/set -// IRIG cfg from a GPS169PCI with IRIG output and early firmware version +// This macro checks whether a workaround is required to get/set +// IRIG cfg from a GPS169PCI with IRIG output and early firmware version. // This is handled in mbgdevio.c for direct access environments, and in // macioctl.h for kernel device drivers. #define _pcps_ddev_requires_irig_workaround( _d ) \ @@ -1505,6 +1523,10 @@ _ext const char *fw_id_ref[] #endif +/** + * @defgroup pcps_io_fncs Low level functions used to access the hardware device + */ + /* ----- function prototypes begin ----- */ @@ -1551,26 +1573,239 @@ _ext const char *fw_id_ref[] */ int pcps_generic_io( PCPS_DDEV *pddev, uint8_t type, const void FAR *in_buff, uint8_t in_cnt, void FAR *out_buff, uint8_t out_cnt ) ; + /** + * @brief Read a large data structure from a device + * + * Read data structures which exceed ::PCPS_FIFO_SIZE bytes. + * This can't be handled in a single read cycle, and due to + * limitations of the device's microprocessor the execution time + * can be up to 20 milliseconds, depending on the device type. + * This has been introduced with the first GPS devices but is + * now in fact also used with non-GPS devices. + * + * @param[in] pddev Pointer to the device structure + * @param[in] data_type The code assigned to the dadta type, see @ref PC_GPS_CMD_CODES + * @param[out] buffer A buffer with data to be read according to the data_type + * @param[in] buffer_size The number of bytes to be read according to the data_type + * + * @return ::MBG_SUCCESS on success, + * ::MBG_ERR_TIMEOUT if device didn't respond in time, + * ::MBG_ERR_NBYTES if the number of parameter bytes did not match + * the number of data bytes expected by the device, + * or one of the other @ref MBG_RETURN_CODES + * + * @ingroup pcps_io_fncs + * @see @ref pcps_io_fncs + */ int pcps_read_gps( PCPS_DDEV *pddev, uint8_t data_type, void FAR *buffer, uint16_t buffer_size ) ; + + /** + * @brief Write a large data structure to a device + * + * This has been introduced with the first GPS devices but is + * now in fact also used with non-GPS devices. + * + * @param[in] pddev Pointer to the device structure + * @param[in] data_type The code assigned to the dadta type, see @ref PC_GPS_CMD_CODES + * @param[in] buffer A buffer with data to be written according to the data_type + * @param[in] buffer_size The number of bytes to be written according to the data_type + * + * @return ::MBG_SUCCESS on success, + * ::MBG_ERR_TIMEOUT if device didn't respond in time, + * ::MBG_ERR_NBYTES if the number of parameter bytes did not match + * the number of data bytes expected by the device, + * or one of the other @ref MBG_RETURN_CODES + * + * @ingroup pcps_io_fncs + * @see @ref pcps_io_fncs + */ int pcps_write_gps( PCPS_DDEV *pddev, uint8_t data_type, const void FAR *buffer, uint16_t buffer_size ) ; + + /** + * @brief Read the serial number from a device, if supported + * + * If the serial number could be read successfully then it is + * stored in one of the sub-structures of pddev. + * + * @param[in,out] pddev Pointer to a device structure + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ int pcps_read_sernum( PCPS_DDEV *pddev ) ; + + /** + * @brief Release an I/O port resource range that has been claimed before + * + * @param[in,out] pddev The device structure + */ void pcps_rsrc_release( PCPS_DDEV *pddev ) ; - ushort pcps_port_from_pos( ushort pos ) ; - uchar pcps_pos_from_port( ushort port ) ; - PCPS_DEV_TYPE *pcps_get_dev_type( int bus_mask, ushort dev_id ) ; + + /** + * @brief Lookup a specific device in the device table + * + * The function below takes a bus flag and device ID to search + * the table of known devices for a device which matches the + * given criteria. + * + * @param[in] bus_mask Mask of the bus type to look up, see @ref PCPS_BUS_FLAG_MASKS + * @param[in] dev_id The device ID to lookup, see @ref MEINBERG_PCI_DEVICE_IDS + * or @ref MBG_USB_DEVICE_IDS, depending on the bus_mask + * + * @return A pointer to the device table entry, or NULL if no entry found + */ + PCPS_DEV_TYPE *pcps_get_dev_type_table_entry( PCPS_BUS_FLAGS bus_mask, PCPS_DEV_ID dev_id ) ; + + /** + * @brief Allocate a device info structure for a device + * + * @return A pointer to the allocated structure, or NULL if failed + */ PCPS_DDEV *pcps_alloc_ddev( void ) ; + + /** + * @brief Free a previously allocated device info structure + * + * @param[in] pddev Pointer to the device structure to be freed + */ void pcps_free_ddev( PCPS_DDEV *pddev ) ; + + /** + * @brief Add an I/O address range resource to the device structure + * + * @param[in,out] pddev Pointer to the device structure + * @param[in] base Base address of the I/O address range + * @param[in] num Number of addresses of the I/O address range + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ int pcps_add_rsrc_io( PCPS_DDEV *pddev, ulong base, ulong num ) ; + + /** + * @brief Add a memory address range resource to the device structure + * + * @param[in,out] pddev Pointer to the device structure + * @param[in] start Start address of the memory range + * @param[in] len Size of the memory range + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ int pcps_add_rsrc_mem( PCPS_DDEV *pddev, MBG_MEM_ADDR start, ulong len ) ; + + /** + * @brief Add an IRQ number resource to the device structure + * + * @param[in,out] pddev Pointer to the device structure + * @param[in] irq_num Start address of the memory range + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ int pcps_add_rsrc_irq( PCPS_DDEV *pddev, int16_t irq_num ) ; - int pcps_init_ddev( PCPS_DDEV *pddev, int bus_flags, ushort dev_id ) ; - int pcps_start_device( PCPS_DDEV *pddev, PCPS_BUS_NUM bus_num, PCPS_SLOT_NUM dev_fnc_num ) ; + + /** + * @brief Initialize an allocated device structure for a specific device + * + * @param[in,out] pddev Pointer to the device structure + * @param[in] bus_mask Mask of the bus type to look up, see @ref PCPS_BUS_FLAG_MASKS + * @param[in] dev_id The device ID to lookup, see @ref MEINBERG_PCI_DEVICE_IDS + * or @ref MBG_USB_DEVICE_IDS, depending on the bus_mask + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ + int pcps_init_ddev( PCPS_DDEV *pddev, PCPS_BUS_FLAGS bus_mask, PCPS_DEV_ID dev_id ) ; + + /** + * @brief Check if a specific feature of a specific feature type is supported + * + * There are different structures where information can be stored + * if a specific feature is supported. All information is set up + * when the ::pcps_probe_device function is called to probe and + * initialize the device. + * This generic low-level function can be called by API functions + * to check if a specific feature is supported. + * + * @param[in] p_ddev Pointer to the device structure + * @param[in] feat_req_type See ::DEV_FEAT_REQ_TYPES + * @param[in] feat_num Number and range depending on feat_req_type value + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @see ::pcps_probe_device + */ + int pcps_chk_dev_feat( PCPS_DDEV *p_ddev, uint32_t feat_req_type, uint32_t feat_num ) ; + + /** + * @brief Probe if a device is supported, and allocate and setup the device structure + * + * This function should be called by the probe routines of any + * target-specific kernel drivers. + * If the device is supported then all specific information including + * supported features is read from the device and stored in sub-structures + * of the device structure addressed by pdev. + * + * @param[in,out] pddev Pointer to the device structure which has been initialized and will be set up + * @param[in] bus_num The bus number if supported (e.g. PCI), else 0 + * @param[in] dev_fnc_num The device/function number if supported (e.g. PCI), else 0 + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @see ::pcps_cleanup_device + * @see ::pcps_chk_dev_feat + */ + int pcps_probe_device( PCPS_DDEV *pddev, PCPS_BUS_NUM bus_num, PCPS_SLOT_NUM dev_fnc_num ) ; + + /** + * @brief Clean up function called by ::pcps_probe_device on error + * + * @param[in,out] pddev Pointer to the device structure + * + * @see ::pcps_probe_device + */ void pcps_cleanup_device( PCPS_DDEV *pddev ) ; + + /** + * @brief Setup and start a PCI device in a non-PnP system + * + * @param[in,out] pddev Pointer to the device structure to be set up + * @param[in] bus_num The PCI bus number returned by the PCI BIOS + * @param[in] dev_fnc_num The PCI device/function number returned by the PCI BIOS + */ void pcps_setup_and_start_pci_dev( PCPS_DDEV *pddev, PCPS_BUS_NUM bus_num, PCPS_SLOT_NUM dev_fnc_num ) ; - void pcps_detect_pci_clocks( PCPS_DDEV_ALLOC_FNC *alloc_fnc, void *alloc_arg, PCPS_DDEV_CLEANUP_FNC *cleanup_fnc, ushort vendor_id, PCPS_DEV_TYPE dev_type[], int n_dev_types ) ; - void pcps_detect_isa_clocks( PCPS_DDEV_ALLOC_FNC *alloc_fnc, PCPS_DDEV_CLEANUP_FNC *cleanup_fnc, PCPS_DDEV_REGISTER_FNC *register_fnc, int isa_ports[PCPS_MAX_ISA_CARDS], int isa_irqs[PCPS_MAX_ISA_CARDS] ) ; - void _MBG_INIT_CODE_ATTR pcps_detect_clocks_alloc( PCPS_DDEV_ALLOC_FNC *alloc_fnc, void *alloc_arg, PCPS_DDEV_CLEANUP_FNC *cleanup_fnc, int isa_ports[PCPS_MAX_ISA_CARDS], int isa_irqs[PCPS_MAX_ISA_CARDS] ) ; - void _MBG_INIT_CODE_ATTR pcps_detect_clocks( int isa_ports[PCPS_MAX_ISA_CARDS], int isa_irqs[PCPS_MAX_ISA_CARDS] ) ; + + /** + * @brief Detect and initialize PCI devices in a non-PnP system + * + * @param[in] alloc_fnc Pointer to function called to allocate a device structure for each detected device. + * @param[in] cleanup_fnc Pointer to function called if the device structure needs to be de-allocated in case of error. + * @param[in] vendor_id The PCI vendor ID code. + * @param[in] dev_type An array with known PCI devices for the specified vendor ID + * @param[in] n_dev_types The number of entries in the PCI device table + */ + void pcps_detect_pci_devices( PCPS_DDEV_ALLOC_FNC *alloc_fnc, PCPS_DDEV_CLEANUP_FNC *cleanup_fnc, ushort vendor_id, PCPS_DEV_TYPE dev_type[], int n_dev_types ) ; + + /** + * @brief Detect and initialize ISA devices in a non-PnP system + * + * @param[in] alloc_fnc Pointer to function called to allocate a device structure for each detected device. + * @param[in] cleanup_fnc Pointer to function called if the device structure needs to be de-allocated in case of error. + * @param[in] register_fnc Pointer to function called to register a detected device. + * @param[in] isa_ports An array with potential I/O base addresses for ISA devices. + * @param[in] isa_irqs An array with potential IRQ numbers assigned to ISA devices. + */ + void pcps_detect_isa_devices( PCPS_DDEV_ALLOC_FNC *alloc_fnc, PCPS_DDEV_CLEANUP_FNC *cleanup_fnc, PCPS_DDEV_REGISTER_FNC *register_fnc, int isa_ports[PCPS_MAX_ISA_CARDS], int isa_irqs[PCPS_MAX_ISA_CARDS] ) ; + + /** + * @brief Detect all bus-level devices in a non-PnP system + * + * @note If a DOS TSR is installed, be sure it is disabled (BUSY flag set) + * when this function is called. + * + * @param[in] isa_ports An array with potential I/O base addresses for ISA devices. + * @param[in] isa_irqs An array with potential IRQ numbers assigned to ISA devices. + */ + void _MBG_INIT_CODE_ATTR pcps_detect_devices( int isa_ports[PCPS_MAX_ISA_CARDS], int isa_irqs[PCPS_MAX_ISA_CARDS] ) ; + /* ----- function prototypes end ----- */ diff --git a/mbglib/common/pcpslstr.c b/mbglib/common/pcpslstr.c index c9b1529..151a0e0 100755 --- a/mbglib/common/pcpslstr.c +++ b/mbglib/common/pcpslstr.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpslstr.c 1.24.1.2 2015/10/01 14:23:42 martin TEST $ + * $Id: pcpslstr.c 1.25 2017/07/05 07:43:53 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,9 +11,8 @@ * * ----------------------------------------------------------------------- * $Log: pcpslstr.c $ - * Revision 1.24.1.2 2015/10/01 14:23:42 martin - * Revision 1.24.1.1 2015/08/27 16:11:51Z martin - * Made string functions safe against buffer overruns. + * Revision 1.25 2017/07/05 07:43:53 martin + * Use safe string functions from str_util.c. * Started to add doxygen comments. * Revision 1.24 2014/03/13 14:32:27 martin * Fixed compiler warning. @@ -534,11 +533,11 @@ void pcps_status_strs( ushort status, int status_is_read, /*HDR*/ char *pcps_port_str( char *s, size_t max_len, const PCPS_DEV *pdev ) { - ushort port = _pcps_port_base( pdev, 0 ); + ushort port = _pcps_short_port_base( pdev, 0 ); size_t n = snprintf_safe( s, max_len, "%3Xh", port ); - port = _pcps_port_base( pdev, 1 ); + port = _pcps_short_port_base( pdev, 1 ); if ( port ) snprintf_safe( &s[n], max_len - n, ", %3Xh", port ); diff --git a/mbglib/common/pcpslstr.h b/mbglib/common/pcpslstr.h index 71f9519..241364c 100755 --- a/mbglib/common/pcpslstr.h +++ b/mbglib/common/pcpslstr.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpslstr.h 1.29.1.6 2016/08/10 12:29:03 martin TEST $ + * $Id: pcpslstr.h 1.30 2017/07/05 17:37:03 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,17 +10,12 @@ * * ----------------------------------------------------------------------- * $Log: pcpslstr.h $ - * Revision 1.29.1.6 2016/08/10 12:29:03 martin + * Revision 1.30 2017/07/05 17:37:03 martin * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. - * Revision 1.29.1.5 2015/11/20 14:50:02 martin - * Revision 1.29.1.4 2015/10/26 13:43:00Z martin - * Revision 1.29.1.3 2015/10/01 13:41:32Z martin - * Revision 1.29.1.2 2015/08/27 16:13:10Z martin - * Made string functions safe against buffer overruns. + * Account for new modes for programmable pulse outputs. * Started to add doxygen comments. + * Fixed typos, wording, and doxygen comments. * Updated function prototypes. - * Revision 1.29.1.1 2014/05/13 11:17:28 martin - * Account for new GPIO mode for programmable pulse outputs. * Revision 1.29 2012/11/20 10:47:29 martin * Moved some code definitions for special chars * to new header charcode.h. @@ -445,7 +440,7 @@ typedef struct #define DEFAULT_TZCODE_HINT_CET_CEST \ { \ - "Central European Time or Summer Time, as broadcasted by DCF77", \ + "Central European Time or Summer Time, as broadcast by DCF77", \ "Mitteleurop" LCAE "ische Zeit oder Sommerzeit, wie von DCF77 gesendet" \ } @@ -457,7 +452,7 @@ typedef struct #define DEFAULT_TZCODE_HINT_GMT_BST \ { \ - "Greenwich Mean Time or British Summer Time, as broadcasted by MSF", \ + "Greenwich Mean Time or British Summer Time, as broadcast by MSF", \ "Westeurop" LCAE "ische Zeit oder britische Sommerzeit, wie von MSF gesendet" \ } @@ -778,14 +773,16 @@ typedef struct #define GER_POUT_NAME_DCF77 "DCF77-Zeitmarken" #define GER_POUT_NAME_POS_OK "Position OK" #define GER_POUT_NAME_TIME_SYNC "Zeit synchron" -#define GER_POUT_NAME_ALL_SYNC "alles synchron" +#define GER_POUT_NAME_ALL_SYNC "Alles synchron" #define GER_POUT_NAME_TIMECODE "DCLS-Zeitcode" #define GER_POUT_NAME_TIMESTR "Serielles Zeittelegramm" #define GER_POUT_NAME_10MHZ "Festfrequenz 10 MHz" #define GER_POUT_NAME_DCF77_M59 "DCF77-Zeitmarken mit 59. Impuls" -#define GER_POUT_NAME_SYNTH "Frequenz-Synthesizer" +#define GER_POUT_NAME_SYNTH "Synthesizer-Frequenz" #define GER_POUT_NAME_TIME_SLOTS "Zeitschlitze pro Minute" #define GER_POUT_NAME_GPIO "GPIO-Signal" +#define GER_POUT_PTTI_PPS "PTTI 1 PPS" +#define GER_POUT_HAVEQUICK "HaveQuick" #define DEFAULT_GER_POUT_NAMES \ { \ @@ -806,7 +803,9 @@ typedef struct GER_POUT_NAME_DCF77_M59, \ GER_POUT_NAME_SYNTH, \ GER_POUT_NAME_TIME_SLOTS, \ - GER_POUT_NAME_GPIO \ + GER_POUT_NAME_GPIO, \ + GER_POUT_PTTI_PPS, \ + GER_POUT_HAVEQUICK \ } /* @@ -831,6 +830,8 @@ typedef struct #define GER_POUT_HINT_SYNTH "Durch programmierbaren Synthesizer erzeugte Frequenz" #define GER_POUT_HINT_TIME_SLOTS "Programmierbare Zeitslots, die in jeder Minute aktiviert werden" #define GER_POUT_HINT_GPIO "Signal des spezifizierten GPIO-Ein- oder Ausgangs" +#define GER_POUT_HINT_PTTI_PPS "20 us-Impuls zum Sekundenbeginn" +#define GER_POUT_HINT_HAVEQUICK "Dupliziertes HaveQuick-Signal" #define DEFAULT_GER_POUT_HINTS \ { \ @@ -851,7 +852,9 @@ typedef struct GER_POUT_HINT_DCF77_M59, \ GER_POUT_HINT_SYNTH, \ GER_POUT_HINT_TIME_SLOTS, \ - GER_POUT_HINT_GPIO \ + GER_POUT_HINT_GPIO, \ + GER_POUT_HINT_PTTI_PPS, \ + GER_POUT_HINT_HAVEQUICK \ } diff --git a/mbglib/common/pcpsmktm.c b/mbglib/common/pcpsmktm.c index 8ef3781..b26b1a8 100755 --- a/mbglib/common/pcpsmktm.c +++ b/mbglib/common/pcpsmktm.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsmktm.c 1.4.1.3 2014/10/14 10:23:21 martin TEST $ + * $Id: pcpsmktm.c 1.5 2017/07/05 08:05:11 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,9 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: pcpsmktm.c $ - * Revision 1.4.1.3 2014/10/14 10:23:21 martin - * Revision 1.4.1.2 2014/10/14 10:04:49 martin - * Revision 1.4.1.1 2014/10/14 08:59:11Z martin + * Revision 1.5 2017/07/05 08:05:11 martin + * Let pcps_mktime() return a 'time_t' instead of 'long', and made + * the PCPS_TIME pointer parameter 'const'. + * Added doxygen comments. * Revision 1.4 2006/12/14 15:27:49 martin * Include time.h. * Revision 1.3 2006/08/22 09:10:03 martin diff --git a/mbglib/common/pcpsmktm.h b/mbglib/common/pcpsmktm.h index 1ba5ded..eb4c05b 100755 --- a/mbglib/common/pcpsmktm.h +++ b/mbglib/common/pcpsmktm.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsmktm.h 1.1.1.1 2014/10/14 10:36:38 martin TEST $ + * $Id: pcpsmktm.h 1.2 2017/07/05 08:18:54 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: pcpsmktm.h $ - * Revision 1.1.1.1 2014/10/14 10:36:38 martin + * Revision 1.2 2017/07/05 08:18:54 martin + * Cleaned up to conform to standard header file format. * Updated function prototypes. * Revision 1.1 2001/02/02 15:31:07 MARTIN * @@ -42,7 +43,6 @@ extern "C" { #endif -/* function prototypes: */ /* ----- function prototypes begin ----- */ diff --git a/mbglib/common/pcpsutil.h b/mbglib/common/pcpsutil.h index c65bd6b..29dfdc7 100755 --- a/mbglib/common/pcpsutil.h +++ b/mbglib/common/pcpsutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsutil.h 1.22 2017/03/17 11:45:51 martin TEST $ + * $Id: pcpsutil.h 1.23 2017/05/10 15:26:09 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: pcpsutil.h $ + * Revision 1.23 2017/05/10 15:26:09 martin + * Tiny cleanup. * Revision 1.22 2017/03/17 11:45:51 martin * Moved binary fraction conversion functions to cfg_hlp.h. * Revision 1.21 2015/10/26 16:09:58 martin @@ -87,6 +89,9 @@ #define _USING_BYTE_ALIGNMENT #endif +#ifdef __cplusplus +extern "C" { +#endif /** @@ -115,12 +120,6 @@ uint16_t pcps_exp_year( uint8_t year, uint16_t year_lim ) -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/plxdefs.h b/mbglib/common/plxdefs.h index 0a71015..f59cc0d 100755 --- a/mbglib/common/plxdefs.h +++ b/mbglib/common/plxdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: plxdefs.h 1.4 2013/03/15 10:24:09 martin REL_M $ + * $Id: plxdefs.h 1.5 2017/05/10 15:26:09 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,7 +11,7 @@ * * 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 + * 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 @@ -23,6 +23,8 @@ * * ----------------------------------------------------------------------- * $Log: plxdefs.h $ + * Revision 1.5 2017/05/10 15:26:09 martin + * Tiny cleanup. * 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. @@ -50,6 +52,9 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif /** * PCI device ID of the PCI bridge also built into the PLX8311 @@ -155,17 +160,6 @@ enum PLX_LCS_REGS_PCI -/* End of header body */ - -#undef _ext - - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ @@ -179,5 +173,8 @@ extern "C" { } #endif +/* End of header body */ + +#undef _ext #endif /* _PLXDEFS_H */ diff --git a/mbglib/common/ptp_util.h b/mbglib/common/ptp_util.h index d8fa556..0b4c099 100755 --- a/mbglib/common/ptp_util.h +++ b/mbglib/common/ptp_util.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: ptp_util.h 1.5 2017/04/25 12:54:21 gregoire.diehl TEST $ + * $Id: ptp_util.h 1.6 2017/05/10 15:26:10 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: ptp_util.h $ + * Revision 1.6 2017/05/10 15:26:10 martin + * Tiny cleanup. * Revision 1.5 2017/04/25 12:54:21 gregoire.diehl * Merge changes from 1.3.1.7 & 1.4 * Revision 1.4 2016/11/10 09:05:26Z martin @@ -114,12 +116,12 @@ uint32_t get_supp_ptp_role_mask( uint32_t flags ) if ( flags & PTP_CFG_MSK_CAN_BE_TIME_MONITOR ) role_mask |= PTP_ROLE_MSK_TIME_MONITOR; - + if ( flags & PTP_CFG_MSK_CAN_BE_V1_MASTER ) role_mask |= PTP_ROLE_MSK_V1_MASTER; - + if ( flags & PTP_CFG_MSK_CAN_BE_V1_SLAVE ) - role_mask |= PTP_ROLE_MSK_V1_SLAVE; + role_mask |= PTP_ROLE_MSK_V1_SLAVE; return role_mask; @@ -127,8 +129,6 @@ uint32_t get_supp_ptp_role_mask( uint32_t flags ) -/* function prototypes: */ - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/rsrc.h b/mbglib/common/rsrc.h index 0ea2d0d..cc97d76 100755 --- a/mbglib/common/rsrc.h +++ b/mbglib/common/rsrc.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: rsrc.h 1.5 2012/10/12 11:25:14 martin REL_M $ + * $Id: rsrc.h 1.6 2017/05/10 15:26:10 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,6 +11,8 @@ * * ----------------------------------------------------------------------- * $Log: rsrc.h $ + * Revision 1.6 2017/05/10 15:26:10 martin + * Tiny cleanup. * Revision 1.5 2012/10/12 11:25:14 martin * Support *BSD. * Revision 1.4 2001/02/28 15:45:11 MARTIN @@ -51,6 +53,10 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + enum { RSRC_BUS_ISA, @@ -60,17 +66,6 @@ enum }; -/* End of header body */ - -#undef _ext - - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ @@ -85,5 +80,9 @@ extern "C" { #endif +/* End of header body */ + +#undef _ext + #endif /* _RSRC_H */ diff --git a/mbglib/common/str_util.h b/mbglib/common/str_util.h index 02f5b35..3b49318 100755 --- a/mbglib/common/str_util.h +++ b/mbglib/common/str_util.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: str_util.h 1.3 2016/12/14 16:22:24 martin TEST $ + * $Id: str_util.h 1.4 2017/05/10 15:26:10 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: str_util.h $ + * Revision 1.4 2017/05/10 15:26:10 martin + * Tiny cleanup. * Revision 1.3 2016/12/14 16:22:24 martin * Added macro _sn_cpy_str_safe() to simplify calls. * Revision 1.2 2016/08/05 12:33:17 martin @@ -57,8 +59,6 @@ _ext const char *str_not_avail #define _sn_cpy_str_safe( _dst, _src ) sn_cpy_str_safe( _dst, sizeof( _dst ), _src ) -/* function prototypes: */ - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/mbglib/common/timeutil.c b/mbglib/common/timeutil.c index 37b29e0..be65f18 100755 --- a/mbglib/common/timeutil.c +++ b/mbglib/common/timeutil.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: timeutil.c 1.1.1.5 2017/04/10 12:37:46 martin TEST $ + * $Id: timeutil.c 1.2 2017/07/05 07:10:48 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,16 +10,9 @@ * * ----------------------------------------------------------------------- * $Log: timeutil.c $ - * Revision 1.1.1.5 2017/04/10 12:37:46 martin - * Fixed some compiler warnings. - * Revision 1.1.1.4 2017/02/06 11:45:57Z martin - * Fixed build under Windows, and implemented mbg_clock_settime(), - * but system time is actually not yet set. - * Revision 1.1.1.3 2016/11/21 15:22:37Z martin - * Revision 1.1.1.2 2016/08/11 15:09:46Z martin - * *** empty log message *** - * Revision 1.1.1.1 2016/08/11 07:54:40 martin - * Fixed build with old Visual Studio. + * Revision 1.2 2017/07/05 07:10:48 martin + * Added mbg_clock_gettime(), mbg_clock_settime(), + * and check_precise_time_api() for Windows. * Revision 1.1 2016/07/15 14:14:19Z martin * Initial revision * @@ -29,10 +22,11 @@ #include <timeutil.h> #undef _TIMEUTIL +#include <mbgtime.h> #include <str_util.h> -#include <mbgerror.h> #if defined( MBG_TGT_WIN32 ) + #include <mbgerror.h> // NSECS_PER_SEC #include <stdio.h> #endif @@ -78,15 +72,14 @@ int mbg_clock_gettime( clockid_t clock_id, struct timespec *tp ) return ( rc == 0 ) ? -1 : 0 // rc == 0 means error #else #define EPOCH_HNS 116444736000000000i64 - #define NSEC_PER_SEC 1000000000i64 FILETIME ft; unsigned __int64 tmp; gstaft_fnc( &ft ); tmp = ( (__int64) ft.dwHighDateTime << 32 ) | ft.dwLowDateTime; tmp -= EPOCH_HNS; // convert to Unix epoch tmp *= 100; // convert to nanoseconds - tp->tv_sec = ( tmp / NSEC_PER_SEC ); - tp->tv_nsec = ( tmp % NSEC_PER_SEC ); + tp->tv_sec = ( tmp / NSECS_PER_SEC ); + tp->tv_nsec = ( tmp % NSECS_PER_SEC ); return 0; #endif } @@ -108,15 +101,14 @@ int mbg_clock_settime( clockid_t clock_id, const struct timespec *tp ) return ( rc == 0 ) ? -1 : 0 // rc == 0 means error #else #define EPOCH_HNS 116444736000000000i64 - #define NSEC_PER_SEC 1000000000i64 FILETIME ft; unsigned __int64 tmp; gstaft_fnc( &ft ); tmp = ( (__int64) ft.dwHighDateTime << 32 ) | ft.dwLowDateTime; tmp -= EPOCH_HNS; // convert to Unix epoch tmp *= 100; // convert to nanoseconds - res->tv_sec = ( tmp / NSEC_PER_SEC ); - res->tv_nsec = ( tmp % NSEC_PER_SEC ); + res->tv_sec = ( tmp / NSECS_PER_SEC ); + res->tv_nsec = ( tmp % NSECS_PER_SEC ); return 0; #endif #endif @@ -130,7 +122,7 @@ int mbg_clock_settime( clockid_t clock_id, const struct timespec *tp ) -bool force_legacy_gstaft; +bool force_legacy_gstaft; /*HDR*/ diff --git a/mbglib/common/timeutil.h b/mbglib/common/timeutil.h index 2eb9a39..233c174 100755 --- a/mbglib/common/timeutil.h +++ b/mbglib/common/timeutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: timeutil.h 1.2.1.3 2017/04/10 13:30:04 martin TEST $ + * $Id: timeutil.h 1.3 2017/07/05 07:15:00 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,15 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: timeutil.h $ - * Revision 1.2.1.3 2017/04/10 13:30:04 martin - * Fixed some compiler warnings. - * Revision 1.2.1.2 2017/02/06 11:14:13Z martin - * Fixed build under windows. + * Revision 1.3 2017/07/05 07:15:00 martin + * Provide basic support for clock_gettime()/clock_settime() + * compatible functions for Windows. * Updated function prototypes. - * Revision 1.2.1.1 2016/08/11 15:09:51Z martin - * *** empty log message *** - * Revision 1.2 2016/08/11 13:44:00 martin - * Include stddef.h. * Revision 1.1 2016/07/15 14:14:20Z martin * Initial revision * @@ -83,8 +78,6 @@ _ext GSTAFT_FNC gstaft_fnc #endif -/* function prototypes: */ - static __mbg_inline time_t cvt_to_time_t( time_t t ) { diff --git a/mbglib/common/toolutil.c b/mbglib/common/toolutil.c index b92401a..5657910 100755 --- a/mbglib/common/toolutil.c +++ b/mbglib/common/toolutil.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: toolutil.c 1.4.1.26 2016/10/20 11:25:49 martin TEST $ + * $Id: toolutil.c 1.5 2017/07/05 07:32:38 martin REL_M $ * * Description: * Common functions which can be used with Meinberg command line @@ -9,49 +9,26 @@ * * ----------------------------------------------------------------------- * $Log: toolutil.c $ - * Revision 1.4.1.26 2016/10/20 11:25:49 martin - * *** empty log message *** - * Revision 1.4.1.25 2016/08/11 07:27:26 martin - * Revision 1.4.1.24 2016/08/10 13:13:25Z martin - * *** empty log message *** - * Revision 1.4.1.23 2016/08/09 16:01:59 martin - * Fixed build for QNX Neutrino. - * Revision 1.4.1.22 2016/07/22 09:57:12 martin - * Quieted some compiler warninges. - * Revision 1.4.1.21 2016/07/15 14:12:00 martin - * *** empty log message *** - * Revision 1.4.1.20 2015/11/09 11:20:59 martin - * *** empty log message *** - * Revision 1.4.1.19 2015/10/26 13:58:39 martin - * Revision 1.4.1.18 2015/10/21 12:40:41Z martin - * Fixed some compiler warnings under Windows. - * Revision 1.4.1.17 2015/09/03 11:19:15Z martin - * Made mbg_snprint_hr_tstamp() more versatile - * by passing a new optional UTC offset parameter. - * Revision 1.4.1.16 2015/08/27 16:16:00 martin - * Use safe string functions. - * Revision 1.4.1.15 2015/07/14 15:16:29 martin - * Reworked error checking after opening device. - * Make stdout unbuffered if output is redirected. - * Revision 1.4.1.14 2014/10/22 15:36:12 martin - * Revision 1.4.1.13 2014/04/28 13:34:21 martin - * Print special firmware version info, if appropriate. - * Revision 1.4.1.12 2014/01/31 14:45:45 martin - * Revision 1.4.1.11 2013/12/04 09:58:53 martin + * Revision 1.5 2017/07/05 07:32:38 martin + * Renamed mbg_check_devices() to mbg_handle_devices() and added + * a new parameter which controls if only one or all devices + * should be handled if no device has been specified. + * New function mbg_open_device_by_param() which can be used e.g. to + * check if a parameter string is an device file name (MBG_DEV_FN), + * or a device index number, or a device name in MBG_DEV_NAME format, + * and calls the appropriate open function to open the device. + * Made mbg_snprint_hr_tstamp() more versatile by passing a new + * optional UTC offset parameter. + * Account for PCPS_HRT_BIN_FRAC_SCALE renamed to MBG_FRAC32_UNITS_PER_SEC. + * Account for frac_sec_from_bin() obsoleted by bin_frac_32_to_dec_frac(). * Print device options with OS-specific device names. - * Revision 1.4.1.10 2013/07/22 16:25:11Z martin - * Revision 1.4.1.9 2013/07/17 09:55:52 martin - * Revision 1.4.1.8 2013/07/16 15:45:19 martin - * Revision 1.4.1.7 2013/07/16 09:52:34 martin - * Revision 1.4.1.6 2013/07/11 15:31:17 martin - * Revision 1.4.1.5 2013/07/11 08:37:55 martin - * Add a parameter to mbg_check_devices() which controls if only one - * or all devices should be handled if no device has been specified. - * 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. + * Print special firmware version info, if appropriate. + * Reworked error checking after opening device. + * mbg_print_program_info() which is usually called first after program + * start now makes stdout unbuffered if output is redirected. + * Use safe string functions from str_util.c. + * Support Windows and QNX Neutrino targets. + * Added doxygen comments. * Revision 1.4 2012/10/15 09:33:48 martin * Use common way to handle version information. * Open device with O_RDWR flag. @@ -98,19 +75,37 @@ static __mbg_inline +/** + * @brief Compute the difference between two ::PCPS_TIME_STAMP values + * + * @param[in] p_ts Pointer to the current time stamp. + * @param[in] p_prv_ts Pointer to a previous time stamp. + * + * @return The time difference as double, in microseconds. + */ double delta_timestamps( const PCPS_TIME_STAMP *p_ts, const PCPS_TIME_STAMP *p_prv_ts ) { uint64_t ts = pcps_time_stamp_to_uint64( p_ts ); uint64_t prv_ts = pcps_time_stamp_to_uint64( p_prv_ts ); - // we divide by PCPS_HRT_BIN_FRAC_SCALE to get the correct fractions - // and we multiply by 1E6 to get the result in microseconds - return (double) ( (int64_t) ( ts - prv_ts ) ) * 1E6 / PCPS_HRT_BIN_FRAC_SCALE; + + // We divide by MBG_FRAC32_UNITS_PER_SEC to get the correct fractions + // and we multiply by 1E6 to get the result in microseconds. + return (double) ( (int64_t) ( ts - prv_ts ) ) * 1E6 / MBG_FRAC32_UNITS_PER_SEC; } // delta_timestamps /*HDR*/ +/** + * @brief Print the program version to a string buffer + * + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. + * @param[in] micro_version Micro version code for the application. + * + * @return The number of characters printed to the buffer. + */ int mbg_program_version_str( char *s, size_t max_len, int micro_version ) { int n; @@ -129,6 +124,18 @@ int mbg_program_version_str( char *s, size_t max_len, int micro_version ) /*HDR*/ +/** + * @brief Print some program info to a string buffer + * + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. + * @param[in] pname The program name. + * @param[in] micro_version Micro version code for the application. + * @param[in] first_year First copyright year. + * @param[in] last_year Last copyright year. + * + * @return The number of characters printed to the buffer. + */ int mbg_program_info_str( char *s, size_t max_len, const char *pname, int micro_version, int first_year, int last_year ) { @@ -159,10 +166,23 @@ int mbg_program_info_str( char *s, size_t max_len, const char *pname, /*HDR*/ +/** + * @brief Print program info to console + * + * @param[in] pname The program name. + * @param[in] micro_version Micro version code for the application. + * @param[in] first_year First copyright year. + * @param[in] last_year Last copyright year. + */ void mbg_print_program_info( const char *pname, int micro_version, int first_year, int last_year ) { char ws[256]; + // If the output has been redirected then make stdout unbuffered, + // e.g. to see the output immediately even though piped through 'tee'. + if ( !isatty( fileno( stdout ) ) ) + setvbuf( stdout, NULL, _IONBF, 0 ); + mbg_program_info_str( ws, sizeof( ws ), pname, micro_version, first_year, last_year ); printf( "\n%s\n\n", ws ); @@ -172,6 +192,12 @@ void mbg_print_program_info( const char *pname, int micro_version, int first_yea /*HDR*/ +/** + * @brief Print usage intro to console + * + * @param[in] pname The program name. + * @param[in] info An optional additional info string, may be NULL. + */ void mbg_print_usage_intro( const char *pname, const char *info ) { printf( "Usage: %s [[opt] [opt] ...] [[dev] [dev] ...]\n\n", pname ); @@ -185,13 +211,19 @@ void mbg_print_usage_intro( const char *pname, const char *info ) /*HDR*/ +/** + * @brief Print info on a single program option / argument + * + * @param[in] opt_name The option name, optional, may be NULL. + * @param[in] opt_info The option info, optional, may be NULL. + */ void mbg_print_opt_info( const char *opt_name, const char *opt_info ) { if ( opt_name == NULL ) - opt_name = ""; + opt_name = str_empty; if ( opt_info == NULL ) - opt_info = ""; + opt_info = str_empty; printf( " %8s %s\n", opt_name, opt_info ); @@ -200,9 +232,15 @@ void mbg_print_opt_info( const char *opt_name, const char *opt_info ) /*HDR*/ +/** + * @brief Print info on common program help arguments + * + * Lists program parameters causing printing + * of help / usage information. + */ void mbg_print_help_options( void ) { - puts( "where opt is one of the options:" ); + puts( "where \"opt\" is one of the options:" ); mbg_print_opt_info( "-? or -h", "print this usage information" ); } // mbg_print_help_options @@ -210,22 +248,35 @@ void mbg_print_help_options( void ) /*HDR*/ +/** + * @brief Print common info on how to specify devices on the command line + */ void mbg_print_device_options( void ) { printf( "\n" ); - #if ( defined( MBG_TGT_POSIX ) || defined( MBG_TGT_WIN32 ) ) && !defined( MBG_TGT_QNX_NTO ) - printf( "where dev is the device name, e.g.:\n" - " %s or %s", EXAMPLE_DEVICE_NAME_1, EXAMPLE_DEVICE_NAME_2 ); - #else - printf( "where dev is the device name or index." ); + puts( "where \"dev\" can be:" ); + + #if MBG_TGT_HAS_DEV_FN + printf( " a device file name, e.g. \"%s\" or \"%s\"\n", + EXAMPLE_DEV_FN_1, EXAMPLE_DEV_FN_2 ); #endif + printf( " a device type name, with or with S/N appended, e.g. \"%s\" or \"%s\"\n", + EXAMPLE_DEV_NAME_1, EXAMPLE_DEV_NAME_2 ); + + printf( " a device index, e.g. \"0\", \"1\",\"2\", ...\n" ); } // mbg_print_device_options /*HDR*/ +/** + * @brief Print program info and default usage information + * + * @param[in] pname The program name. + * @param[in] prog_info An optional additional info string, may be NULL. + */ void mbg_print_default_usage( const char *pname, const char *prog_info ) { mbg_print_usage_intro( pname, prog_info ); @@ -238,12 +289,20 @@ void mbg_print_default_usage( const char *pname, const char *prog_info ) /*HDR*/ +/** + * @brief Retrieve and print some common device info + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] dev_name A device name string to be printed + * @param[out] p_dev Pointer to a device info structure to be read from the device + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_dev ) { RECEIVER_INFO ri; unsigned long port; int irq_num; - int ret_val = 0; int rc; if ( dev_name ) @@ -252,13 +311,13 @@ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_ // get information about the device rc = mbg_get_device_info( dh, p_dev ); - if ( mbg_ioctl_err( rc, "mbg_get_device_info" ) ) - goto fail; + if ( mbg_cond_err_msg( rc, "mbg_get_device_info" ) ) + goto out; rc = mbg_setup_receiver_info( dh, p_dev, &ri ); - if ( mbg_ioctl_err( rc, "mbg_setup_receiver_info" ) ) - goto fail; + if ( mbg_cond_err_msg( rc, "mbg_setup_receiver_info" ) ) + goto out; printf( "%s", _pcps_type_name( p_dev ) ); @@ -280,7 +339,7 @@ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_ PCI_ASIC_VERSION av; int rc = mbg_get_asic_version( dh, &av ); - if ( rc == MBG_SUCCESS ) + if ( mbg_rc_is_success( rc ) ) { av = _convert_asic_version_number( av ); @@ -293,12 +352,12 @@ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_ printf( ")" ); - port = _pcps_port_base( p_dev, 0 ); + port = _pcps_short_port_base( p_dev, 0 ); if ( port ) printf( " at port 0x%03lX", port ); - port = _pcps_port_base( p_dev, 1 ); + port = _pcps_short_port_base( p_dev, 1 ); if ( port ) printf( "/0x%03lX", port ); @@ -308,177 +367,364 @@ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_ if ( irq_num != -1 ) printf( ", irq %i", irq_num ); - goto done; - -fail: - ret_val = -1; + rc = MBG_SUCCESS; -done: - puts( "" ); - return ret_val; +out: + puts( str_empty ); + return rc; } // mbg_get_show_dev_info /*HDR*/ -int mbg_check_device( MBG_DEV_HANDLE dh, const char *dev_name, - int (*fnc)( MBG_DEV_HANDLE, const PCPS_DEV *) ) +/** + * @brief Print device info and take some action on a specific device + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] dev_name A device name string to be printed. + * @param[in] fnc Pointer to a callback function that actually takes the action. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ +int mbg_handle_device( MBG_DEV_HANDLE dh, const char *dev_name, + MBG_DEV_HANDLER_FNC *fnc ) { PCPS_DEV dev; - int ret_val = MBG_SUCCESS; - - if ( mbg_get_show_dev_info( dh, dev_name, &dev ) < 0 ) - goto fail; - - if ( fnc ) - ret_val = fnc( dh, &dev ); + int rc; - goto done; + rc = mbg_get_show_dev_info( dh, dev_name, &dev ); -fail: - ret_val = -1; + if ( mbg_rc_is_success( rc ) ) + if ( fnc ) + rc = fnc( dh, &dev ); -done: mbg_close_device( &dh ); + puts( "" ); - return ret_val; + return rc; + +} // mbg_handle_device + -} // mbg_check_device + +/*HDR*/ +/** + * @brief Get the number of devices actually present + * + * Do a real search only when called for the first time. + * + * @return The number of devices currently present. + */ +int chk_get_num_devices( void ) +{ + static int num_devices; + static bool has_searched_devices; + + if ( !has_searched_devices ) + { + num_devices = mbg_find_devices(); + has_searched_devices = true; + } + + return num_devices; + +} // chk_get_num_devices /*HDR*/ -int mbg_check_open_result( MBG_DEV_HANDLE dh, const char *dev_name ) +int mbg_open_device_by_param( MBG_DEV_HANDLE *p_dh, const char *dev_param_str, + int dev_idx, int devices_specified, + char *dev_name_buffer, size_t dev_name_buffer_size, + int chk_dev_flags ) { - if ( dh == MBG_INVALID_DEV_HANDLE ) + MBG_DEV_HANDLE dh = MBG_INVALID_DEV_HANDLE; + int devices_found; + int rc = MBG_ERR_GENERIC; + + if ( dev_name_buffer_size ) // This should always be the case + dev_name_buffer[0] = 0; // Make string empty + + if ( dev_param_str ) { - int this_errno = errno; + // A device parameter string has been specified. + // This can be: + // - A device file name, see ::MBG_DEV_FN + // - A device model name like "GPS180PEX", eventually with the serial number + // appended after an underscore, as in "GPS180PEX_029511026220". + // See ::MBG_DEV_NAME. + // - A device index number as string, e.g "0" or "3". + + char *endptr; + long l; + + #if MBG_TGT_HAS_DEV_FN + // Check if the device parameter represents a device file name + if ( strncmp( dev_param_str, mbg_dev_fn_base, strlen( mbg_dev_fn_base ) ) == 0 ) + { + snprintf_safe( dev_name_buffer, dev_name_buffer_size, "%s", dev_param_str ); + dh = mbg_open_device_by_dev_fn( dev_param_str ); + goto out_chk; + } + #endif + + + // Check if the device parameter string is an index number. + endptr = NULL; + l = strtol( dev_param_str, &endptr, 0 ); + + // If endptr now points past the string then the + // whole string has been interpreted as number. + if ( endptr == &dev_param_str[strlen( dev_param_str )] ) + { + long l_max = (long) ( ( (unsigned int) -1 ) >> 1 ); + + if ( l > l_max ) + { + // The decoded number exceeds the maximum number + // that can be passed to ::mbg_open_device. + rc = MBG_ERR_RANGE; + goto out; + } + + // We use the decoded number as device index. + dev_idx = (int) l; + goto open_dev_with_idx; + } - const char *err_info = strerror( this_errno ); - fprintf( stderr, "Failed to open device" ); + // Finally assume the device name is a model name, eventually + // with serial number appended. + snprintf_safe( dev_name_buffer, dev_name_buffer_size, "%s", dev_param_str ); + dh = mbg_open_device_by_name( dev_param_str, MBG_MATCH_MODEL ); + goto out_chk; + } - if ( dev_name ) - fprintf( stderr, " %s", dev_name ); - fprintf( stderr, ": %s\n", err_info ); + // No device has been specified on the command line. - return mbg_posix_errno_to_mbg( this_errno, NULL ); +#if 0 // TODO + if ( chk_dev_flags & CHK_DEV_WITHOUT_DEV ) + { + // TODO Check if this branch is useful + // We have been called without a device to be used. + // This may be useful e.g. if we just want to print + // some general usage information. + if ( fnc ) + { + *p_dh = MBG_INVALID_DEV_HANDLE; + rc = fnc( *p_dh, NULL ); + } + else + { + // TODO Should we report an error if we have been called + // without callback function and without device? + } + goto out; } +#endif - return MBG_SUCCESS; -} // mbg_check_open_result +open_dev_with_idx: + devices_found = chk_get_num_devices(); + + if ( devices_found == 0 ) // no device found + { + // Don't continue without any device, unless + // explicitly requested to do so. + if ( !( chk_dev_flags & CHK_DEV_WITHOUT_DEV ) ) + return MBG_ERR_NO_DEV; + + // We may continue even if no device is available, + // but have to process the callback loop only once. + devices_found = 1; + } + + // Unless explicitly requested to handle all devices + // we have found, we only handle the first one. + if ( !( chk_dev_flags & CHK_DEV_ALL_DEVICES ) ) + devices_found = 1; + + + // Try to open the device with the specified index number. + mbg_dev_fn_from_dev_idx( dev_name_buffer, dev_name_buffer_size, dev_idx ); + dh = mbg_open_device( dev_idx ); + +out_chk: + // Now check if the "open" function we've just called before + // was successful. + if ( dh == MBG_INVALID_DEV_HANDLE ) + { + char msg[256]; + int n = 0; + rc = mbg_get_last_error( NULL ); + + n = snprintf_safe( msg, sizeof( msg ), "** Failed to open device" ); + + if ( dev_name_buffer[0] ) // string not empty + n += snprintf_safe( &msg[n], sizeof( msg ) - n, " %s", dev_name_buffer ); + + n += snprintf_safe( &msg[n], sizeof( msg ) - n, ": %s", mbg_strerror( rc ) ); + fprintf( stderr, "%s\n\n", msg ); + goto out; + } + + rc = MBG_SUCCESS; + + +out: + *p_dh = dh; + + return rc; + +} // mbg_open_device_by_param /*HDR*/ -int mbg_check_devices( int argc, char *argv[], int optind, - int (*fnc)( MBG_DEV_HANDLE, const PCPS_DEV *), - int chk_dev_flags ) +/** + * @brief Main action handler that can be called by utility programs + * + * This function checks the command line parameters passed to the program. + * Those which have not been evaluated before are interpreted as device specifiers. + * + * Device specifiers can be device file names like "/dev/mbgclock0" on target + * platforms that support such device names, see ::MBG_DEV_FN, + * or device type names like "GPS180PEX" which can optionally have a serial + * number appended, like "GPS180PEX_029511026220", to be able to distinguish + * between several devices of the same type (see ::MBG_DEV_NAME), + * or just an index number as required for the ::mbg_open_device call. + * + * For each of the specified devices the callback function @p fnc is called to + * take some specific action on the device. + * + * If no device has been specified in the argument list then ::mbg_find_devices + * is called to set up a device list, and depending on whether ::CHK_DEV_ALL_DEVICES + * is set in @p chk_dev_flags the callback function @p fnc is either called + * for every device from the list, or only for the first one. + * + * @param[in] argc Number of parameters of the program argument list. + * @param[in] argv Array of program argument strings. + * @param[in] optind Number of the command line arguments that have already been handled. + * @param[in] fnc Pointer to a callback function that actually takes an action on each specified device. + * @param[in] chk_dev_flags Bit mask controlling the behavior of the function, see ::CHK_DEV_FLAGS + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ +int mbg_handle_devices( int argc, char *argv[], int optind, + MBG_DEV_HANDLER_FNC *fnc, int chk_dev_flags ) { + MBG_DEV_FN tmp_dev_fn; MBG_DEV_HANDLE dh; - int ret_val = 0; int devices_specified = argc - optind; + int devices_found = 0; + const char *dev_param_str = NULL; + int rc = MBG_ERR_NO_DEV; int i; - // If the output has been redirected then make stdout unbuffered, - // e.g. to see the output immediately even though piped through 'tee'. - if ( !isatty( fileno( stdout ) ) ) - setvbuf( stdout, NULL, _IONBF, 0 ); - if ( devices_specified ) { // One or more device names have been specified // on the command line, so handle each device. for ( i = optind; i < argc; i++ ) { - // Print device name only if output for several devices - // shall be displayed. - const char *fn = ( devices_specified > 1 ) ? argv[i] : NULL; + dev_param_str = argv[i]; - #if defined( MBG_TGT_POSIX ) && !defined( MBG_TGT_QNX_NTO ) - dh = open( argv[i], O_RDWR ); - #else - dh = mbg_open_device_by_name( argv[i], MBG_MATCH_MODEL ); - #endif - ret_val = mbg_check_open_result( dh, argv[i] ); + rc = mbg_open_device_by_param( &dh, dev_param_str, 0, devices_specified, + tmp_dev_fn, sizeof( tmp_dev_fn ), chk_dev_flags ); - if ( ret_val == MBG_SUCCESS ) - ret_val = mbg_check_device( dh, fn, fnc ); + if ( mbg_rc_is_success( rc ) ) + rc = mbg_handle_device( dh, ( devices_specified > 1 ) ? tmp_dev_fn : NULL, fnc ); // Don't continue if one of the specified devices failed. - if ( ret_val != MBG_SUCCESS ) + if ( mbg_rc_is_error( rc ) ) break; } + + goto out; } - else // no device specified on the command line + + + // No device has been specified on the command line. + + if ( chk_dev_flags & CHK_DEV_WITHOUT_DEV ) { - if ( chk_dev_flags & CHK_DEV_WITHOUT_DEV ) + // TODO Check if this branch is useful + // We have been called without a device to be used. + // This may be useful e.g. if we just want to print + // some general usage information. + if ( fnc ) { - // TODO: check if this branch is useful - // We have been called without a device to be used. - // This may be useful e.g. if we just want to print - // some general usage information. - if ( fnc ) - { - dh = MBG_INVALID_DEV_HANDLE; - ret_val = fnc( dh, NULL ); - } - else - { - // should we report an error if we have been called - // without callback function and without device? - } + dh = MBG_INVALID_DEV_HANDLE; + rc = fnc( dh, NULL ); } else { - int devices_foundx = mbg_find_devices(); + // TODO Should we report an error if we have been called + // without callback function and without device? + } + goto out; + } - if ( devices_foundx == 0 ) // no device found - { - // Don't continue without any device, unless - // explicitely requested to do so. - if ( !( chk_dev_flags & CHK_DEV_WITHOUT_DEV ) ) - { - printf( "No device found.\n" ); - return 1; - } - - // We may continue even if no device is available, - // but must process the callback loop only once. - devices_foundx = 1; - } - // Unless explicitely requested to handle all devices - // we have found, we only handle the first one. - if ( !( chk_dev_flags & CHK_DEV_ALL_DEVICES ) ) - devices_foundx = 1; + devices_found = chk_get_num_devices(); - for ( i = 0; i < devices_foundx; i++ ) - { - dh = mbg_open_device( i ); + if ( devices_found == 0 ) // no device found + { + // Don't continue without any device, unless + // explicitly requested to do so. + if ( !( chk_dev_flags & CHK_DEV_WITHOUT_DEV ) ) + { + printf( "No device found.\n" ); // TODO + rc = MBG_ERR_NO_DEV; + goto out; + } - ret_val = mbg_check_open_result( dh, NULL ); + // We may continue even if no device is available, + // but must process the callback loop only once. + devices_found = 1; + } - if ( ret_val == MBG_SUCCESS ) - ret_val = mbg_check_device( dh, NULL, fnc ); - } + // Unless explicitly requested to handle all devices + // we have found, we only handle the first one. + if ( !( chk_dev_flags & CHK_DEV_ALL_DEVICES ) ) + devices_found = 1; - // If one of the unspecified devices failed we continue anyway - // and don't break here. - } + for ( i = 0; i < devices_found; i++ ) + { + rc = mbg_open_device_by_param( &dh, NULL, i, 0, tmp_dev_fn, + sizeof( tmp_dev_fn ), chk_dev_flags ); + + if ( mbg_rc_is_success( rc ) ) + rc = mbg_handle_device( dh, ( devices_found > 1 ) ? tmp_dev_fn : NULL, fnc ); + + // If one of the unspecified devices failed we continue anyway + // and don't break here. } - return ret_val; -} // mbg_check_devices +out: + return rc; + +} // mbg_handle_devices /*HDR*/ +/** + * @brief Print date and time from a ::PCPS_TIME structure to a string + * + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. + * @param[in] p Pointer to a ::PCPS_TIME structure to be evaluated. + * @param[in] verbose Increase verbosity of the output:<br> + * > 0: append UTC offset and status<br> + * > 1: append signal value + * + * @return The number of characters printed to the buffer. + */ size_t mbg_snprint_date_time( char *s, size_t max_len, const PCPS_TIME *p, int verbose ) { size_t n = 0; @@ -501,6 +747,17 @@ size_t mbg_snprint_date_time( char *s, size_t max_len, const PCPS_TIME *p, int v /*HDR*/ +/** + * @brief Print date and time from a ::PCPS_TIME_STAMP structure to a string + * + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. + * @param[in] p Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. + * @param[in] utc_offs A local time offset added to the time stamp before converted to date and time. + * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. + * + * @return The number of characters printed to the buffer. + */ size_t mbg_snprint_hr_tstamp( char *s, size_t max_len, const PCPS_TIME_STAMP *p, long utc_offs, int show_raw ) { @@ -529,7 +786,7 @@ size_t mbg_snprint_hr_tstamp( char *s, size_t max_len, const PCPS_TIME_STAMP *p, n += snprintf_safe( &s[n], max_len - n, "%04i-%02i-%02i %02i:%02i:%02i." PCPS_HRT_FRAC_SCALE_FMT, tm.tm_year + 1900, tm.tm_mon + 1, tm.tm_mday, tm.tm_hour, tm.tm_min, tm.tm_sec, - (ulong) frac_sec_from_bin( p->frac, PCPS_HRT_FRAC_SCALE ) ); + (ulong) bin_frac_32_to_dec_frac( p->frac, PCPS_HRT_FRAC_SCALE ) ); else n += snprint_gmtime_error( &s[n], max_len - n, rc, t, __func__ ); @@ -540,6 +797,19 @@ size_t mbg_snprint_hr_tstamp( char *s, size_t max_len, const PCPS_TIME_STAMP *p, /*HDR*/ +/** + * @brief Print date and time from a ::PCPS_HR_TIME structure to a string + * + * Converts the UTC timestamp first to local time according to + * the ::PCPS_HR_TIME::utc_offs value. + * + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. + * @param[in] p Pointer to a ::PCPS_HR_TIME structure to be evaluated. + * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. + * + * @return The number of characters printed to the buffer. + */ size_t mbg_snprint_hr_time( char *s, int max_len, const PCPS_HR_TIME *p, int show_raw ) { char ws[80]; @@ -587,6 +857,26 @@ size_t mbg_snprint_hr_time( char *s, int max_len, const PCPS_HR_TIME *p, int sho /*HDR*/ +/** + * @brief Print date and time from a ::PCPS_TIME_STAMP structure + * + * First the HR timestamp passed by parameter @p p_ts is printed. + * + * If the parameter @p p_prv_ts is not NULL then it should specify + * an earlier timestamp, and the elapsed time since @p p_ts + * is appended. + * + * Finally the latency value is printed in microseconds, unless + * parameter @p no_latency is != 0. + * + * @param[in] p_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. + * @param[in] hns_latency A latency number in hectonanoseconds, i.e. 100 ns units. + * @param[in] p_prv_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated, may be NULL + * @param[in] no_latency A flag indicating if printing the latency should be suppressed. + * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. + * + * @see ::mbg_print_hr_time + */ void mbg_print_hr_timestamp( PCPS_TIME_STAMP *p_ts, int32_t hns_latency, PCPS_TIME_STAMP *p_prv_ts, int no_latency, int show_raw ) { @@ -601,13 +891,36 @@ void mbg_print_hr_timestamp( PCPS_TIME_STAMP *p_ts, int32_t hns_latency, PCPS_TI if ( !no_latency ) printf( ", latency: %.1f us", ( (double) hns_latency ) / 10 ); - puts( "" ); + puts( str_empty ); } // mbg_print_hr_timestamp /*HDR*/ +/** + * @brief Print date and time from a ::PCPS_HR_TIME structure + * + * First the HR timestamp passed by parameter @p p_ht is printed. + * + * If the parameter @p p_prv_ts is not NULL then it should specify + * an earlier timestamp, and the elapsed time since @p p_ht + * is appended. + * + * Next the latency value is printed in microseconds, unless + * parameter @p no_latency is != 0. + * + * @param[in] p_ht Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. + * @param[in] hns_latency A latency number in hectonanoseconds, i.e. 100 ns units. + * @param[in] p_prv_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated, may be NULL + * @param[in] no_latency A flag indicating if printing the latency should be suppressed. + * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. + * @param[in] verbose Increase verbosity of the output:<br> + * > 0: append status code<br> + * > 1: append signal value + * + * @see ::mbg_print_hr_timestamp + */ void mbg_print_hr_time( PCPS_HR_TIME *p_ht, int32_t hns_latency, PCPS_TIME_STAMP *p_prv_ts, int no_latency, int show_raw, int verbose ) { @@ -635,7 +948,15 @@ void mbg_print_hr_time( PCPS_HR_TIME *p_ht, int32_t hns_latency, PCPS_TIME_STAMP /*HDR*/ -int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int show_corr_step ) +/** + * @brief Retrieve and print PZF correlation info for a device which supports this + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] show_corr_step A flag indicating if correlation step indicators are to be appended + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ +int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, int show_corr_step ) { CORR_INFO ci; char ws[80]; @@ -643,7 +964,7 @@ int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int show_c int rc = mbg_get_corr_info( dh, &ci ); - if ( mbg_ioctl_err( rc, "mbg_get_corr_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_corr_info" ) ) return rc; @@ -668,15 +989,18 @@ int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int show_c /*HDR*/ +/** + * @brief Retrieve a ::MBG_GNSS_MODE_INFO structure from a device + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_GNSS_MODE_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ int mbg_get_gps_gnss_mode_info_chk( MBG_DEV_HANDLE dh, MBG_GNSS_MODE_INFO *p ) { - int rc; - - if ( dh == MBG_INVALID_DEV_HANDLE ) - return MBG_ERR_INV_HANDLE; - - rc = mbg_get_gps_gnss_mode_info( dh, p ); - mbg_ioctl_err( rc, "mbg_get_gps_gnss_mode_info" ); + int rc = mbg_get_gps_gnss_mode_info( dh, p ); + mbg_cond_err_msg( rc, "mbg_get_gps_gnss_mode_info" ); return rc; diff --git a/mbglib/common/toolutil.h b/mbglib/common/toolutil.h index 05bece7..103e8af 100755 --- a/mbglib/common/toolutil.h +++ b/mbglib/common/toolutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: toolutil.h 1.3.1.11 2016/08/10 12:29:34 martin TEST $ + * $Id: toolutil.h 1.4 2017/07/05 07:38:06 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,25 +10,14 @@ * * ----------------------------------------------------------------------- * $Log: toolutil.h $ - * Revision 1.3.1.11 2016/08/10 12:29:34 martin + * Revision 1.4 2017/07/05 07:38:06 martin + * Support Windows target. + * Defined function type MBG_DEV_HANDLER_FNC. + * Defined some OS-specific strings e.g. for example + * file and device names used in help messages. * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. - * Revision 1.3.1.10 2015/11/09 11:20:59 martin - * *** empty log message *** - * Revision 1.3.1.9 2015/09/03 11:19:15 martin - * Made mbg_snprint_hr_tstamp() more versatile - * by passing a new optional UTC offset parameter. - * Revision 1.3.1.8 2015/08/27 16:16:29 martin + * Doxygen comments. * Updated function prototypes. - * Revision 1.3.1.7 2014/01/31 14:45:45 martin - * Revision 1.3.1.6 2013/12/04 09:59:44 martin - * Defined some OS-specific strings. - * Revision 1.3.1.5 2013/07/22 16:25:11Z martin - * Revision 1.3.1.4 2013/07/16 15:45:19 martin - * Revision 1.3.1.3 2013/07/16 09:52:34 martin - * Revision 1.3.1.2 2013/07/11 08:38:20 martin - * Updated function prototypes. - * 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. @@ -94,29 +83,30 @@ enum CHK_DEV_FLAGS }; -#if defined( MBG_TGT_WIN32 ) - - #define EXAMPLE_DEVICE_NAME_1 "gps180pex" - #define EXAMPLE_DEVICE_NAME_1_TCR "tcr167pci" - #define EXAMPLE_DEVICE_NAME_2 "tcr170pex_027911002000" - #define ROOT_PRIVILEGES_STR "as administrator" +#if MBG_TGT_HAS_DEV_FN + #define EXAMPLE_DEV_FN_1 MBGCLOCK_DEV_FN_BASE "0" + #define EXAMPLE_DEV_FN_1_TCR EXAMPLE_DEV_FN_1 + #define EXAMPLE_DEV_FN_2 MBGCLOCK_DEV_FN_BASE "3" +#endif -#elif defined( MBG_TGT_POSIX ) && !defined( MBG_TGT_QNX_NTO ) +#define EXAMPLE_DEV_NAME_1 "gps180pex" +#define EXAMPLE_DEV_NAME_1_TCR "tcr167pci" +#define EXAMPLE_DEV_NAME_2 "tcr170pex_027911002000" - #define EXAMPLE_DEVICE_NAME_1 "/dev/mbgclock0" - #define EXAMPLE_DEVICE_NAME_1_TCR EXAMPLE_DEVICE_NAME_1 - #define EXAMPLE_DEVICE_NAME_2 "/dev/mbgclock3" +#if defined( MBG_TGT_POSIX ) #define ROOT_PRIVILEGES_STR "with root privileges" +#else + #define ROOT_PRIVILEGES_STR "as administrator" #endif - #if !defined( MBG_EXP_YEAR_LIMIT ) #define MBG_EXP_YEAR_LIMIT 1980 #endif + _ext uint16_t mbg_exp_year_limit #ifdef _DO_INIT = MBG_EXP_YEAR_LIMIT @@ -125,6 +115,13 @@ _ext uint16_t mbg_exp_year_limit _ext int must_print_usage; +_ext const char str_empty[] +#ifdef _DO_INIT + = "" +#endif +; + + _ext const char *pzf_corr_state_name[N_PZF_CORR_STATE] #ifdef _DO_INIT = PZF_CORR_STATE_NAMES_ENG @@ -132,31 +129,279 @@ _ext const char *pzf_corr_state_name[N_PZF_CORR_STATE] ; + +/** + * @brief The type of functions to called to handle a device in a specific way. + */ +typedef int MBG_DEV_HANDLER_FNC( MBG_DEV_HANDLE, const PCPS_DEV *); + + + +/** + * @brief Exit codes returned by the command line tools + */ +enum MBG_EXIT_CODES +{ + MBG_EXIT_CODE_SUCCESS, ///< Device handled successfully for requested action + MBG_EXIT_CODE_USAGE, ///< Device not handled successfully, usage printed + MBG_EXIT_CODE_NOT_SUPP, ///< Not supported on the running OS + MBG_EXIT_CODE_FAIL, ///< Action failed for device + MBG_EXIT_CODE_INV_TIME, ///< Device has no valid time to set the system time with + N_MBG_EXIT_CODES +}; + + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ + /** + * @brief Print the program version to a string buffer + * + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. + * @param[in] micro_version Micro version code for the application. + * + * @return The number of characters printed to the buffer. + */ int mbg_program_version_str( char *s, size_t max_len, int micro_version ) ; + + /** + * @brief Print some program info to a string buffer + * + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. + * @param[in] pname The program name. + * @param[in] micro_version Micro version code for the application. + * @param[in] first_year First copyright year. + * @param[in] last_year Last copyright year. + * + * @return The number of characters printed to the buffer. + */ int mbg_program_info_str( char *s, size_t max_len, const char *pname, int micro_version, int first_year, int last_year ) ; + + /** + * @brief Print program info to console + * + * @param[in] pname The program name. + * @param[in] micro_version Micro version code for the application. + * @param[in] first_year First copyright year. + * @param[in] last_year Last copyright year. + */ void mbg_print_program_info( const char *pname, int micro_version, int first_year, int last_year ) ; + + /** + * @brief Print usage intro to console + * + * @param[in] pname The program name. + * @param[in] info An optional additional info string, may be NULL. + */ void mbg_print_usage_intro( const char *pname, const char *info ) ; + + /** + * @brief Print info on a single program option / argument + * + * @param[in] opt_name The option name, optional, may be NULL. + * @param[in] opt_info The option info, optional, may be NULL. + */ void mbg_print_opt_info( const char *opt_name, const char *opt_info ) ; + + /** + * @brief Print info on common program help arguments + * + * Lists program parameters causing printing + * of help / usage information. + */ void mbg_print_help_options( void ) ; + + /** + * @brief Print common info on how to specify devices on the command line + */ void mbg_print_device_options( void ) ; + + /** + * @brief Print program info and default usage information + * + * @param[in] pname The program name. + * @param[in] prog_info An optional additional info string, may be NULL. + */ void mbg_print_default_usage( const char *pname, const char *prog_info ) ; + + /** + * @brief Retrieve and print some common device info + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] dev_name A device name string to be printed + * @param[out] p_dev Pointer to a device info structure to be read from the device + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ int mbg_get_show_dev_info( MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_dev ) ; - int mbg_check_device( MBG_DEV_HANDLE dh, const char *dev_name, int (*fnc)( MBG_DEV_HANDLE, const PCPS_DEV *) ) ; - int mbg_check_open_result( MBG_DEV_HANDLE dh, const char *dev_name ) ; - int mbg_check_devices( int argc, char *argv[], int optind, int (*fnc)( MBG_DEV_HANDLE, const PCPS_DEV *), int chk_dev_flags ) ; + + /** + * @brief Print device info and take some action on a specific device + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] dev_name A device name string to be printed. + * @param[in] fnc Pointer to a callback function that actually takes the action. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ + int mbg_handle_device( MBG_DEV_HANDLE dh, const char *dev_name, MBG_DEV_HANDLER_FNC *fnc ) ; + + /** + * @brief Get the number of devices actually present + * + * Do a real search only when called for the first time. + * + * @return The number of devices currently present. + */ + int chk_get_num_devices( void ) ; + + int mbg_open_device_by_param( MBG_DEV_HANDLE *p_dh, const char *dev_param_str, int dev_idx, int devices_specified, char *dev_name_buffer, size_t dev_name_buffer_size, int chk_dev_flags ) ; + /** + * @brief Main action handler that can be called by utility programs + * + * This function checks the command line parameters passed to the program. + * Those which have not been evaluated before are interpreted as device specifiers. + * + * Device specifiers can be device file names like "/dev/mbgclock0" on target + * platforms that support such device names, see ::MBG_DEV_FN, + * or device type names like "GPS180PEX" which can optionally have a serial + * number appended, like "GPS180PEX_029511026220", to be able to distinguish + * between several devices of the same type (see ::MBG_DEV_NAME), + * or just an index number as required for the ::mbg_open_device call. + * + * For each of the specified devices the callback function @p fnc is called to + * take some specific action on the device. + * + * If no device has been specified in the argument list then ::mbg_find_devices + * is called to set up a device list, and depending on whether ::CHK_DEV_ALL_DEVICES + * is set in @p chk_dev_flags the callback function @p fnc is either called + * for every device from the list, or only for the first one. + * + * @param[in] argc Number of parameters of the program argument list. + * @param[in] argv Array of program argument strings. + * @param[in] optind Number of the command line arguments that have already been handled. + * @param[in] fnc Pointer to a callback function that actually takes an action on each specified device. + * @param[in] chk_dev_flags Bit mask controlling the behavior of the function, see ::CHK_DEV_FLAGS + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ + int mbg_handle_devices( int argc, char *argv[], int optind, MBG_DEV_HANDLER_FNC *fnc, int chk_dev_flags ) ; + + /** + * @brief Print date and time from a ::PCPS_TIME structure to a string + * + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. + * @param[in] p Pointer to a ::PCPS_TIME structure to be evaluated. + * @param[in] verbose Increase verbosity of the output:<br> + * > 0: append UTC offset and status<br> + * > 1: append signal value + * + * @return The number of characters printed to the buffer. + */ size_t mbg_snprint_date_time( char *s, size_t max_len, const PCPS_TIME *p, int verbose ) ; + + /** + * @brief Print date and time from a ::PCPS_TIME_STAMP structure to a string + * + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. + * @param[in] p Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. + * @param[in] utc_offs A local time offset added to the time stamp before converted to date and time. + * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. + * + * @return The number of characters printed to the buffer. + */ size_t mbg_snprint_hr_tstamp( char *s, size_t max_len, const PCPS_TIME_STAMP *p, long utc_offs, int show_raw ) ; + + /** + * @brief Print date and time from a ::PCPS_HR_TIME structure to a string + * + * Converts the UTC timestamp first to local time according to + * the ::PCPS_HR_TIME::utc_offs value. + * + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. + * @param[in] p Pointer to a ::PCPS_HR_TIME structure to be evaluated. + * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. + * + * @return The number of characters printed to the buffer. + */ size_t mbg_snprint_hr_time( char *s, int max_len, const PCPS_HR_TIME *p, int show_raw ) ; + + /** + * @brief Print date and time from a ::PCPS_TIME_STAMP structure + * + * First the HR timestamp passed by parameter @p p_ts is printed. + * + * If the parameter @p p_prv_ts is not NULL then it should specify + * an earlier timestamp, and the elapsed time since @p p_ts + * is appended. + * + * Finally the latency value is printed in microseconds, unless + * parameter @p no_latency is != 0. + * + * @param[in] p_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. + * @param[in] hns_latency A latency number in hectonanoseconds, i.e. 100 ns units. + * @param[in] p_prv_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated, may be NULL + * @param[in] no_latency A flag indicating if printing the latency should be suppressed. + * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. + * + * @see ::mbg_print_hr_time + */ void mbg_print_hr_timestamp( PCPS_TIME_STAMP *p_ts, int32_t hns_latency, PCPS_TIME_STAMP *p_prv_ts, int no_latency, int show_raw ) ; + + /** + * @brief Print date and time from a ::PCPS_HR_TIME structure + * + * First the HR timestamp passed by parameter @p p_ht is printed. + * + * If the parameter @p p_prv_ts is not NULL then it should specify + * an earlier timestamp, and the elapsed time since @p p_ht + * is appended. + * + * Next the latency value is printed in microseconds, unless + * parameter @p no_latency is != 0. + * + * @param[in] p_ht Pointer to a ::PCPS_TIME_STAMP structure to be evaluated. + * @param[in] hns_latency A latency number in hectonanoseconds, i.e. 100 ns units. + * @param[in] p_prv_ts Pointer to a ::PCPS_TIME_STAMP structure to be evaluated, may be NULL + * @param[in] no_latency A flag indicating if printing the latency should be suppressed. + * @param[in] show_raw Flag indicating if a raw timestamp (hex) is to be printed, too. + * @param[in] verbose Increase verbosity of the output:<br> + * > 0: append status code<br> + * > 1: append signal value + * + * @see ::mbg_print_hr_timestamp + */ void mbg_print_hr_time( PCPS_HR_TIME *p_ht, int32_t hns_latency, PCPS_TIME_STAMP *p_prv_ts, int no_latency, int show_raw, int verbose ) ; - int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, int show_corr_step ) ; + + /** + * @brief Retrieve and print PZF correlation info for a device which supports this + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] show_corr_step A flag indicating if correlation step indicators are to be appended + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ + int mbg_show_pzf_corr_info( MBG_DEV_HANDLE dh, int show_corr_step ) ; + + /** + * @brief Retrieve a ::MBG_GNSS_MODE_INFO structure from a device + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_GNSS_MODE_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ int mbg_get_gps_gnss_mode_info_chk( MBG_DEV_HANDLE dh, MBG_GNSS_MODE_INFO *p ) ; + /* ----- function prototypes end ----- */ diff --git a/mbglib/common/usbdefs.h b/mbglib/common/usbdefs.h index b7034a4..b69cbcb 100755 --- a/mbglib/common/usbdefs.h +++ b/mbglib/common/usbdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: usbdefs.h 1.28 2017/04/04 10:43:34 paul.kretz TEST $ + * $Id: usbdefs.h 1.30 2017/05/17 09:52:53 thomas.fasse REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,11 @@ * * ----------------------------------------------------------------------- * $Log: usbdefs.h $ - * Revision 1.28 2017/04/04 10:43:34 paul.kretz + * Revision 1.30 2017/05/17 09:52:53 thomas.fasse + * Device BITS was rennamed to LSG180. + * Revision 1.29 2017/05/16 07:19:40Z thomas.fasse + * Added ID, name string and table entry for LIU variant BITS by Paul + * Revision 1.28 2017/04/04 10:43:34Z paul.kretz * Added ID, name string and table entry for FDM180M * Added missing table entry for MicroSync power supply module * Revision 1.27 2017/03/28 09:37:15Z paul.kretz @@ -199,6 +203,7 @@ enum MBG_USB_CLASS_CODES #define USB_DEV_LNO180 ( ( MBG_USB_CLASS_LNO << 8 ) | 0x01 ) #define USB_DEV_LIU_01 ( ( MBG_USB_CLASS_LIU << 8 ) | 0x01 ) +#define USB_DEV_LSG180 ( ( MBG_USB_CLASS_LIU << 8 ) | 0x02 ) #define USB_DEV_LNE_01 ( ( MBG_USB_CLASS_LNE << 8 ) | 0x01 ) // LNE with standard copper #define USB_DEV_LNE180SFP ( ( MBG_USB_CLASS_LNE << 8 ) | 0x02 ) // LNE with SFP (fiber optic) @@ -291,6 +296,7 @@ enum MBG_USB_CLASS_CODES #define USB_DEV_NAME_LNO180 "LNO180" #define USB_DEV_NAME_LIU_01 "LIU_01" +#define USB_DEV_NAME_LSG180 "LSG180" #define USB_DEV_NAME_LNE_01 "LNE_01" #define USB_DEV_NAME_LNE180SFP "LNE180SFP" @@ -389,6 +395,7 @@ enum MBG_USB_CLASS_CODES { USB_DEV_PZF180, USB_DEV_NAME_PZF180 }, \ { USB_DEV_USYNCPWR, USB_DEV_NAME_USYNCPWR }, \ { USB_DEV_FDM180M, USB_DEV_NAME_FDM180M }, \ + { USB_DEV_LSG180, USB_DEV_NAME_LSG180 }, \ { 0, /* end of table */ NULL } \ } diff --git a/mbglib/common/words.h b/mbglib/common/words.h index 26057d6..bf50089 100755 --- a/mbglib/common/words.h +++ b/mbglib/common/words.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: words.h 1.39 2017/03/15 10:01:09 martin REL_M $ + * $Id: words.h 1.41 2017/07/05 12:06:35 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: words.h $ + * Revision 1.41 2017/07/05 12:06:35 martin + * Moved macro _int_from_size_t() here. + * Revision 1.40 2017/06/12 11:14:25 martin + * Empty _DEPRECATED_BY definition for firmware targets. * Revision 1.39 2017/03/15 10:01:09 martin * Added comments how to represent negative numbers in NANO_TIME * and NANO_TIME_64 structures. @@ -147,6 +151,10 @@ #else #define MBG_TGT_MISSING_64_BIT_TYPES 1 #endif + + #if !defined( _DEPRECATED_BY ) + #define _DEPRECATED_BY( _s ) // empty definition + #endif #endif @@ -630,6 +638,20 @@ do \ +// The size_t type can eventually be larger than an int type. +// However, some snprintf-like functions expect a size_t value +// to specify the buffer size, but just return an int value. +// So we take care that at least the return value is limited +// to MAXINT. +#if defined( MBG_TGT_WIN32 ) + #define _int_from_size_t( _n ) \ + ( ( (_n) > INT_MAX ) ? INT_MAX : (int) (_n) ) +#else + #define _int_from_size_t( _n ) (_n) +#endif + + + /** * @brief Make a string from a constant definition * diff --git a/mbglib/common/xdevfeat.c b/mbglib/common/xdevfeat.c deleted file mode 100755 index 5d5d17c..0000000 --- a/mbglib/common/xdevfeat.c +++ /dev/null @@ -1,1556 +0,0 @@ - -/************************************************************************** - * - * $Id: xdevfeat.c 1.1.1.28.1.13 2017/04/20 04:58:10 thomas-b TEST $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Meinberg API functions to check extended device features. - * - * See notes near "defgroup xdevfeat_chk_supp_fncs" in xdevfeat.h. - * - * ----------------------------------------------------------------------- - * $Log: xdevfeat.c $ - * Revision 1.1.1.28.1.13 2017/04/20 04:58:10 thomas-b - * Added function to check for extended features MBG_XFEATURE_USB_LOCK - * Revision 1.1.1.28.1.12 2017/03/07 13:45:34 thomas-b - * Check receiver info feature instead of builtin feature for ignore lock - * Revision 1.1.1.28.1.11 2017/02/22 11:32:47 martin - * Fixed warnings due to preliminary, unfinished code. - * Revision 1.1.1.28.1.10 2017/02/07 14:24:09 thomas-b - * Added function xdevfeat_has_monitoring, which checks if the extended feature MBG_XFEATURE_MONITORING is set - * Revision 1.1.1.28.1.9 2017/02/07 14:10:36 daniel - * Check license feature types - * Revision 1.1.1.28.1.8 2016/12/06 10:43:37 thomas-b - * Added function xdevfeat_has_sv_info - * Revision 1.1.1.28.1.7 2016/12/01 13:47:49 philipp - * Moved helper function check_byte_array_bit from xdevfeat.c to xtiocomm.c and make it public - * Revision 1.1.1.28.1.6 2016/11/30 16:12:26 thomas-b - * Added function xdevfeat_has_scu_stat - * Revision 1.1.1.28.1.5 2016/11/22 10:33:16 philipp - * Implemented I/O ports - * Revision 1.1.1.28.1.4 2016/11/02 12:16:18 thomas-b - * Fixed documentation - * Revision 1.1.1.28.1.3 2016/11/02 12:08:21 thomas-b - * Added function to check for new MBG_XFEATURE_REQ_TTM - * Revision 1.1.1.28.1.2 2016/11/01 09:34:43 martin - * Doxygen fixes. - * Revision 1.1.1.28.1.1 2016/10/25 08:07:54 martin - * Merged changes from 1.1.1.23.1.x. - * Revision 1.1.1.28 2016/10/20 14:46:04 thomas-b - * Added function to check if XBP is supported - * Revision 1.1.1.27 2016/10/20 10:43:36 thomas-b - * Added function to check if a device is a bus level device - * Revision 1.1.1.26 2016/10/14 11:09:41 thomas-b - * Added function to check MBG_XFEATURE_UCAP_NET - * Revision 1.1.1.25 2016/09/29 14:35:35 thomas-b - * Added function to check reboot feature - * Revision 1.1.1.24 2016/09/29 12:19:59 thomas-b - * Added function to check transactions feature - * Revision 1.1.1.23 2016/07/07 15:04:11 martin - * Renamed functions due to renamed library symbols. - * Revision 1.1.1.22 2016/06/15 10:15:51 thomas-b - * Added functions which check if the user capture feature is supported by a device - * Revision 1.1.1.21 2016/06/14 10:33:23 thomas-b - * Added functions which check if the event log feature is supported by a device - * Revision 1.1.1.20 2016/06/07 07:43:08 philipp - * New function to check for Irig Rx feature - * Revision 1.1.1.19 2016/06/02 10:15:40 philipp - * Renaming all MBG_EXT_REV_INFO related stuff to MBG_EXT_SYS_INFO. - * Revision 1.1.1.18 2016/05/30 08:10:47 thomas-b - * Added functions to check several builtin features - * Revision 1.1.1.17 2016/05/20 09:41:38 thomas-b - * Removed functions which check for a specific IMS card - * Revision 1.1.1.16 2016/05/20 08:50:46 thomas-b - * Added functions xdevfeat_has_time_scale and xdevfeat_has_tzcode - * Revision 1.1.1.15 2016/05/17 06:33:12 philipp - * New function to check whether a device has serial outputs - * Revision 1.1.1.14 2016/05/12 10:41:40 philipp - * New functions to check bpe card and IRIG Tx feature - * Revision 1.1.1.13 2016/05/10 06:15:32 philipp - * New function to check whether a device has programmable pulses - * Revision 1.1.1.12 2016/04/26 06:52:46 thomas-b - * Added functions to check if NET_CFG and LAN_IP4 APIs are supported - * Revision 1.1.1.11 2016/04/22 10:54:01 philipp - * New function to check whether device is LIU - * Revision 1.1.1.10 2016/04/20 13:21:06 thomas-b - * Added function to check if a device supports NTP - * Revision 1.1.1.9 2016/04/20 09:26:03 philipp - * Moved all HPS-PTP related structures to gpspriv.h and removed related extended feature bit from gpsdefs.h. - * Also removed functions from mbgextio and xdevfeat since HPS-PTP handling needs a redesign concerning structures. - * Thus, handle everything explicitly for now! - * -> Redesing this A.S.A.P.!!! - * Revision 1.1.1.8 2016/04/15 08:17:27 philipp - * New feature MBG_XFEATURE_EXT_PTP - * Revision 1.1.1.7 2016/04/13 07:01:22 philipp - * New function to check whether device is HPS - * Revision 1.1.1.6 2016/04/12 13:27:42 philipp - * Several new functions to check for device models and device features - * Revision 1.1.1.5 2016/04/11 13:57:13 thomas-b - * Added function xdevfeat_has_xmulti_ref - * Revision 1.1.1.4 2016/04/07 12:36:37 martin - * New function xdevfeat_has_ext_rev_info(). - * Revision 1.1.1.3 2016/04/04 15:31:25 martin - * New function xdevfeat_is_vsg(). - * Revision 1.1.1.2 2016/03/24 14:08:52 martin - * *** empty log message *** - * Revision 1.1.1.1 2016/03/18 10:48:10 martin - * *** empty log message *** - * Revision 1.1 2016/03/16 14:32:52 martin - * Initial revision. - * - **************************************************************************/ - -#define _XDEVFEAT - #include <xdevfeat.h> -#undef _XDEVFEAT - -#include <mbgerror.h> -#include <xtiocomm.h> - - - -typedef uint32_t BUILTIN_FEATURE_MASK; - - -/** - * @brief Entry for a table to specify model-depending built-in features - */ -typedef struct -{ - /// Model code according to ::RECEIVER_INFO::model_code, see ::GPS_MODEL_CODES - uint16_t model_code; - - /// A combination of @ref GPS_FEATURE_MASKS bit masks specifying the - /// built-in features supported by the specified device model. - BUILTIN_FEATURE_MASK feature_mask; - -} BUILTIN_FEATURE_TABLE_ENTRY; - - -/** - * @brief A static table of builtin features - * - * Used to lookup the builtin features of a particular device model. - */ -static BUILTIN_FEATURE_TABLE_ENTRY builtin_feature_table[] = GPS_MODEL_BUILTIN_FEATURES; - - - -static /*HDR*/ -/** - * @brief Check if a device supports a specific built-in feature or API - * - * Some features or API calls are implicitly supported by particular devices. - * This function uses the ::RECEIVER_INFO::model_code to look up the specific - * device in a table of ::BUILTIN_FEATURE_TABLE_ENTRY entries, and checks if - * the requested feature bits are set for this device model. - * If the model code of the specific device can't be found in the table then - * then ::MBG_ERR_DEV_NOT_SUPP is returned and the source code files probably - * need to be updated to support this device. - * - * @param[in] msk One of the @ref GPS_FEATURE_MASKS bit masks - * @param[in] p_ri A ::RECEIVER_INFO structure read from the device before - * - * @return ::MBG_SUCCESS if all specified mask bits are set in ::RECEIVER_INFO::features, - * ::MBG_ERR_NOT_SUPP_BY_DEV if the bits are not set, and ::MBG_ERR_DEV_NOT_SUPP - * if the model code can't be found in the table. - */ -int check_builtin_feature( BUILTIN_FEATURE_MASK msk, const RECEIVER_INFO *p_ri ) -{ - BUILTIN_FEATURE_TABLE_ENTRY *p; - - //### TODO Implement a kind of cache so we don't have to search the whole - // table if several features of the same device are checked after each other. - - for ( p = builtin_feature_table; p->model_code || p->feature_mask; p++ ) - if ( p->model_code == p_ri->model_code ) - return ( ( p->feature_mask & msk ) == msk ) ? MBG_SUCCESS : MBG_ERR_NOT_SUPP_BY_DEV; - - return MBG_ERR_DEV_NOT_SUPP; - -} // check_builtin_feature - - - -static /*HDR*/ -/** - * @brief Check if a device supports a specific feature or API - * - * This API call checks if a specific feature or API is supported - * according to the ::RECEIVER_INFO::features mask read from the device. - * - * @param[in] msk One of the @ref GPS_FEATURE_MASKS bit masks - * @param[in] p_ri A ::RECEIVER_INFO structure read from the device before - * - * @return ::MBG_SUCCESS if all specified mask bits are set in ::RECEIVER_INFO::features, - * else ::MBG_ERR_NOT_SUPP_BY_DEV - */ -int check_ri_feature( RI_FEATURES msk, const RECEIVER_INFO *p_ri ) -{ - return ( ( p_ri->features & msk ) == msk ) ? MBG_SUCCESS : MBG_ERR_NOT_SUPP_BY_DEV; - -} // check_ri_feature - - - -static /*HDR*/ -/** - * @brief Check if a specific extended feature is supported - * - * This API call checks if a specific extended feature or API is supported - * according to the ::MBG_XFEATURE_BUFFER read from the device. - * - * @param[in] xf_bit One of the ::MBG_XFEATURE_BITS - * @param[in] xv_buf Pointer to a ::MBG_XFEATURE_BUFFER read from the device before - * - * @return ::MBG_SUCCESS if the specified feature bit is set, else ::MBG_ERR_NOT_SUPP_BY_DEV or ::MBG_ERR_RANGE - * - * @see ::check_byte_array_bit - */ -int check_xfeature( int xf_bit, const MBG_XFEATURE_BUFFER *xv_buf ) -{ - return check_byte_array_bit( xf_bit, xv_buf->b, sizeof( xv_buf->b ) ); - -} // check_xfeature - - - -#if defined( _PRELIMINARY_CODE ) //### TODO do we need this? - -static /*HDR*/ -/** - * @brief Check if a specific bit is set in TLV's byte array. - * - * This API call checks if a specific TLV feature is supported according to - * the ::MBG_TLV_INFO read from the device. - * - * @param[in] tlv_feat_bit One of the ::MBG_TLV_FEAT_TYPES - * @param[in] tlv_info Pointer to a ::MBG_TLV_INFO read from the device before - * - * @return ::MBG_SUCCESS if the specified feature bit is set, else ::MBG_ERR_NOT_SUPP_BY_DEV or ::MBG_ERR_RANGE - * - * @see ::check_byte_array_bit - */ -int check_tlv_feat_supp( int tlv_feat_bit, const MBG_TLV_INFO *tlv_info ) -{ - return check_byte_array_bit( tlv_feat_bit, tlv_info->supp_tlv_feat.b, sizeof( tlv_info->supp_tlv_feat.b ) ); - -} // check_tlv_feat_supp - -#endif // defined( _PRELIMINARY_CODE ) - - - -/*HDR*/ -/** - * @brief Check if a device can receive the GPS satellite system - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_dev_is_gps - * @see ::mbg_chk_dev_is_gps - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_is_gps( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_IS_GPS, &p_xdf->receiver_info ); - -} // xdevfeat_is_gps - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_is_gps; - - - -/*HDR*/ -/** - * @brief Check if a device supports the GNSS API - * - * This is usually supported by devices which can receive signals - * from different satellite systems, e.g. GPS, GLONASS, ... - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_dev_is_gnss - * @see ::mbg_chk_dev_is_gnss - * @see ::MBG_GNSS_TYPES - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_is_gnss( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_IS_GNSS, &p_xdf->receiver_info ); - -} // xdevfeat_is_gnss - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_is_gnss; - - - -/*HDR*/ -/** - * @brief Check if a device is a time code receiver (IRIG or similar) - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_dev_is_tcr //### TODO - * @see ::mbg_chk_dev_is_tcr //### TODO - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_is_tcr( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_IS_TCR, &p_xdf->receiver_info ); - -} // xdevfeat_is_tcr - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_is_tcr; - - - -/*HDR*/ -/** - * @brief Check if a device is a DCF77 AM receiver - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_dev_is_dcf //### TODO - * @see ::mbg_chk_dev_is_dcf - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_is_dcf( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_IS_DCF_AM, &p_xdf->receiver_info ); - -} // xdevfeat_is_dcf_am - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_is_dcf; - - - -/*HDR*/ -/** - * @brief Check if a device can receive DCF77 PZF - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_dev_has_pzf //### TODO - * @see ::mbg_chk_dev_has_pzf - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_pzf( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_IS_DCF_PZF, &p_xdf->receiver_info ); - -} // xdevfeat_has_pzf - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_pzf; - - - -/*HDR*/ -/** - * @brief Check if a device is an MSF receiver - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_is_msf( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_IS_MSF, &p_xdf->receiver_info ); - -} // xdevfeat_is_msf - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_is_msf; - - - -/*HDR*/ -/** - * @brief Check if a device is a JJY receiver - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_is_jjy( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_IS_JJY, &p_xdf->receiver_info ); - -} // xdevfeat_is_jjy - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_is_jjy; - - - -/*HDR*/ -/** - * @brief Check if a device is a WWVB receiver - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_is_wwvb( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_IS_WWVB, &p_xdf->receiver_info ); - -} // xdevfeat_is_wwvb - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_is_wwvb; - - - -/*HDR*/ -/** - * @brief Check if a device is a bus level device - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_is_bus_lvl_dev( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_IS_BUS_LVL_DEV, &p_xdf->receiver_info ); - -} // xdevfeat_is_bus_lvl_dev - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_is_bus_lvl_dev; - - - -/*HDR*/ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_ims( const MBG_XDEV_FEATURES *p_xdf ) -{ - if ( mbg_rc_is_success( check_ri_feature( GPS_HAS_IMS, &p_xdf->receiver_info ) ) ) - return MBG_SUCCESS; - - return MBG_ERR_NOT_SUPP_BY_DEV; - -} // xdevfeat_has_ims - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_ims; - - - -/*HDR*/ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_gpio( const MBG_XDEV_FEATURES *p_xdf ) -{ - if ( mbg_rc_is_success( check_ri_feature( GPS_HAS_GPIO, &p_xdf->receiver_info ) ) ) - return MBG_SUCCESS; - - return MBG_ERR_NOT_SUPP_BY_DEV; - -} // xdevfeat_has_gpio - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_gpio; - - - -/*HDR*/ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_synth( const MBG_XDEV_FEATURES *p_xdf ) -{ - if ( mbg_rc_is_success( check_ri_feature( GPS_HAS_SYNTH, &p_xdf->receiver_info ) ) ) - return MBG_SUCCESS; - - return MBG_ERR_NOT_SUPP_BY_DEV; - -} // xdevfeat_has_synth - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_synth; - - - -/*HDR*/ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_prog_pulses( const MBG_XDEV_FEATURES *p_xdf ) -{ - const RECEIVER_INFO *ri = &p_xdf->receiver_info; - - if ( ri->n_prg_out > 0 ) - return MBG_SUCCESS; - - return MBG_ERR_NOT_SUPP_BY_DEV; - -} // xdevfeat_has_prog_pulses - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_prog_pulses; - - - -/*HDR*/ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_irig_tx( const MBG_XDEV_FEATURES *p_xdf ) -{ - if ( mbg_rc_is_success( check_ri_feature( GPS_HAS_IRIG_TX, &p_xdf->receiver_info ) ) ) - return MBG_SUCCESS; - - return MBG_ERR_NOT_SUPP_BY_DEV; - -} // xdevfeat_has_irig_tx - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_irig_tx; - - - -/*HDR*/ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_irig_rx( const MBG_XDEV_FEATURES *p_xdf ) -{ - if ( mbg_rc_is_success( check_ri_feature( GPS_HAS_IRIG_RX, &p_xdf->receiver_info ) ) ) - return MBG_SUCCESS; - - return MBG_ERR_NOT_SUPP_BY_DEV; - -} // xdevfeat_has_irig_rx - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_irig_rx; - - - -/*HDR*/ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_serouts( const MBG_XDEV_FEATURES *p_xdf ) -{ - const RECEIVER_INFO *ri = &p_xdf->receiver_info; - - if ( ri->n_com_ports > 0 ) - return MBG_SUCCESS; - - return MBG_ERR_NOT_SUPP_BY_DEV; - -} // xdevfeat_has_serouts - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_serouts; - - - -/*HDR*/ -/** - * @brief Check if a device supports the ::BVAR_STAT structure and API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_bvar_stat( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_HAS_BVAR_STAT, &p_xdf->receiver_info ); - -} // xdevfeat_has_bvar_stat - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_bvar_stat; - - - -/*HDR*/ -/** - * @brief Check if a device supports reading the position as ::XYZ array - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_pos_xyz( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_HAS_POS_XYZ, &p_xdf->receiver_info ); - -} // xdevfeat_has_pos_xyz - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_pos_xyz; - - - -/*HDR*/ -/** - * @brief Check if a device supports reading the position as ::LLA array - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_pos_lla( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_HAS_POS_LLA, &p_xdf->receiver_info ); - -} // xdevfeat_has_pos_lla - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_pos_lla; - - - -/*HDR*/ -/** - * @brief Check if the device supports the builtin feature TIME - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_time_ttm( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_HAS_TIME_TTM, &p_xdf->receiver_info ); - -} // xdevfeat_has_time_ttm - - - -/*HDR*/ -/** - * @brief Check if a device supports the ::MBG_TIME_SCALE_INFO structure and API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_ri_feature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_get_time_scale_info - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_time_scale( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_ri_feature( GPS_HAS_TIME_SCALE, &p_xdf->receiver_info ); - -} // xdevfeat_has_time_scale - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_time_scale; - - - -/*HDR*/ -/** - * @brief Check if a device supports the ::TZDL structure and API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_tzdl( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_HAS_TZDL, &p_xdf->receiver_info ); - -} // xdevfeat_has_tzdl - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_tzdl; - - - -/*HDR*/ -/** - * @brief Check if a device supports the ::TZCODE API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_tzcode( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_HAS_TZCODE, &p_xdf->receiver_info ); - -} // xdevfeat_has_tzcode - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_tzcode; - - - -/*HDR*/ -/** - * @brief Check if a device supports the ::ANT_INFO structure and API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_ant_info( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_HAS_ANT_INFO, &p_xdf->receiver_info ); - -} // xdevfeat_has_ant_info - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_ant_info; - - - -/*HDR*/ -/** - * @brief Check if a device supports the ::ENABLE_FLAGS structure and API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_enable_flags( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_HAS_ENABLE_FLAGS, &p_xdf->receiver_info ); - -} // xdevfeat_has_enable_flags - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_enable_flags; - - - -/*HDR*/ -/** - * @brief Check if a device supports the ::STAT_INFO structure and API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_gps_stat_info( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_HAS_STAT_INFO, &p_xdf->receiver_info ); - -} // xdevfeat_has_gps_stat_info - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_gps_stat_info; - - - -/*HDR*/ -/** - * @brief Check if a device supports the ::ANT_CABLE_LEN structure and API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_ant_cable_length( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_HAS_ANT_CABLE_LEN, &p_xdf->receiver_info ); - -} // xdevfeat_has_ant_cable_length - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_ant_cable_length; - - - -/*HDR*/ -/** - * @brief Check if a device supports the ::IGNORE_LOCK structure and API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_gps_ignore_lock( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_ri_feature( GPS_HAS_IGNORE_LOCK, &p_xdf->receiver_info ); - -} // xdevfeat_has_gps_ignore_lock - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_gps_ignore_lock; - - - -#if 0 //### TODO - - /*HDR*/ -/** - * @brief Check if a device supports the :: structure and API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_HAS_, &p_xdf->receiver_info ); - -} // xdevfeat_has_ - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_; - - - - /*HDR*/ -/** - * @brief Check if a device supports the :: structure and API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_HAS_, &p_xdf->receiver_info ); - -} // xdevfeat_has_ - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_; - -#endif // ### - - -/*HDR*/ -/** - * @brief Check if the device supports the SCU_STAT structures - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - * @see @ref group_scu - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_scu_stat( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_HAS_SCU_STAT, &p_xdf->receiver_info ); - -} // xdevfeat_has_scu_stat - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_scu_stat; - - -/*HDR*/ -/** - * @brief Check if the device supports the SV_INFO structures - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else ::MBG_ERR_NOT_SUPP_BY_DEV - * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_sv_info( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_builtin_feature( GPS_MODEL_HAS_SV_INFO, &p_xdf->receiver_info ); - -} // xdevfeat_has_sv_info - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_sv_info; - - -/*HDR*/ -/** - * @brief Check if a timecode receiver provides ::MBG_RAW_IRIG_DATA - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_ri_feature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_get_raw_irig_data - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_raw_irig_data( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_ri_feature( GPS_HAS_RAW_IRIG_DATA, &p_xdf->receiver_info ); - -} // xdevfeat_has_raw_irig_data - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_raw_irig_data; - - - -/*HDR*/ -/** - * @brief Check if a device supports the old LAN_IP4 API - * - * The LAN_IP4 API provides structures and functions to configure - * parts of the networking of a device and is superseded by the - * NET_CFG API. Some devices combine NET_CFG and LAN_IP4. - * Therefore, ::mbgextio_get_all_net_cfg_info should be used - * preferably to read the network configuration. - * It will translate the old structures into the new ones. - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_ri_feature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_get_all_net_cfg_info - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_lan_ip4( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_ri_feature( GPS_HAS_LAN_IP4, &p_xdf->receiver_info ); - -} // xdevfeat_has_lan_ip4 - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_lan_ip4; - - - -/*HDR*/ -/** - * @brief Check if a device supports the new NET_CFG API - * - * The NET_CFG API provides structures and functions to configure - * the complete networking part of a device and supersedes the - * LAN_IP4 API. Not all devices support the whole feature set - * of the NET_CFG API or combine NET_CFG and LAN_IP4. - * Therefore, ::mbgextio_get_all_net_cfg_info should be used - * preferably to read the network configuration. - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_ri_feature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_get_all_net_cfg_info - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_net_cfg( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_ri_feature( GPS_HAS_NET_CFG, &p_xdf->receiver_info ); - -} // xdevfeat_has_net_cfg - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_net_cfg; - - - -/*HDR*/ -/** - * @brief Check if a device supports the PTP API - * - * The PTP API consists of different calls and associated structures - * which * have evolved over time. Not all devices support every call, - * so ::mbgextio_get_all_ptp_cfg_info takes care to check which parts are - * supported and thus should be used preferably to read PTP information. - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_ri_feature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_get_all_ptp_cfg_info - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_ptp( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_ri_feature( GPS_HAS_PTP, &p_xdf->receiver_info ); - -} // xdevfeat_has_ptp - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_ptp; - - -/*HDR*/ -/** - * @brief Check if a device supports the NTP API - * - * The NTP API consists of different calls and associated structures - * which have evolved over time. Not all devices support every call, - * so ::mbgextio_get_all_ntp_cfg_info takes care to check which parts are - * supported and thus should be used preferably to read NTP information. - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_ri_feature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_get_all_ntp_cfg_info - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_ntp( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_ri_feature( GPS_HAS_NTP, &p_xdf->receiver_info ); - -} // xdevfeat_has_ntp - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_ntp; - - - -/*HDR*/ -/** - * @brief Check if a device supports the event log API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_ri_feature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_evt_log( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_ri_feature( GPS_HAS_EVT_LOG, &p_xdf->receiver_info ); - -} // xdevfeat_has_evt_log - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_evt_log; - - -/*HDR*/ -/** - * @brief Check if a device supports the USB lock feature, see ::MBG_XFEATURE_USB_LOCK - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_xfeature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref group_usb_lock - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_usb_lock( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_xfeature( MBG_XFEATURE_USB_LOCK, &p_xdf->xfeature_buffer ); - -} // xdevfeat_has_usb_lock - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_usb_lock; - - -/*HDR*/ -/** - * @brief Check if a device supports the user capture API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_ri_feature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_ucap( const MBG_XDEV_FEATURES *p_xdf ) -{ - const RECEIVER_INFO *ri = &p_xdf->receiver_info; - - if ( ri->n_ucaps > 0 ) - return MBG_SUCCESS; - - return MBG_ERR_NOT_SUPP_BY_DEV; - -} // xdevfeat_has_ucap - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_ucap; - - -/*HDR*/ -/** - * @brief Check if a device supports the user capture via network feature - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_xfeature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref group_ucap_net - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_ucap_net( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_xfeature( MBG_XFEATURE_UCAP_NET, &p_xdf->xfeature_buffer ); - -} // xdevfeat_has_ucap_net - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_ucap_net; - - - -/*HDR*/ -/** - * @brief Check if a device supports the TLV API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_xfeature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref group_tlv_api - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_tlv_api( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_xfeature( MBG_XFEATURE_TLV_API, &p_xdf->xfeature_buffer ); - -} // xdevfeat_has_ptp - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_tlv_api; - - - -/*HDR*/ -/** - * @brief Check if a device supports a firmware update via TLV - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_tlv_feat_supp - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_xmt_fw_update - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_supp_tlv_fw_update( const MBG_XDEV_FEATURES *p_xdf ) -{ -#if defined( _PRELIMINARY_CODE ) - return check_tlv_feat_supp( MBG_TLV_FEAT_TYPE_FW_UPDATE, &p_xdf->tlv_info ); -#else - return MBG_ERR_NOT_SUPP_BY_DEV; -#endif - -} // xdevfeat_supp_tlv_fw_update - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_supp_tlv_fw_update; - - - -/*HDR*/ -/** - * @brief Check if a device supports creating / sending a diagnostics file via TLV - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_tlv_feat_supp - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::TODO //refer to get diag function - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_supp_tlv_diag_file( const MBG_XDEV_FEATURES *p_xdf ) -{ -#if defined( _PRELIMINARY_CODE ) - return check_tlv_feat_supp( MBG_TLV_FEAT_TYPE_DIAG_FILE, &p_xdf->tlv_info ); -#else - return MBG_ERR_NOT_SUPP_BY_DEV; -#endif - -} // xdevfeat_supp_tlv_diag_file - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_supp_tlv_diag_file; - - - -/*HDR*/ -/** - * @brief Check if a device supports PTPv2 license infos - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_tlv_feat_supp - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_supp_tlv_ptpv2_license( const MBG_XDEV_FEATURES *p_xdf ) -{ -#if defined( _PRELIMINARY_CODE ) - return check_tlv_feat_supp( MBG_TLV_FEAT_TYPE_LICENSE_PTPV2_IDX, &p_xdf->tlv_info ); -#else - return MBG_ERR_NOT_SUPP_BY_DEV; -#endif - -} // xdevfeat_supp_tlv_ptpv2_license - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_supp_tlv_ptpv2_license; - - - -/*HDR*/ -/** - * @brief Check if a device supports NTP license infos via TLV - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_tlv_feat_supp - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_supp_tlv_ntp_license( const MBG_XDEV_FEATURES *p_xdf ) -{ -#if defined( _PRELIMINARY_CODE ) - return check_tlv_feat_supp( MBG_TLV_FEAT_TYPE_LICENSE_NTP_IDX, &p_xdf->tlv_info ); -#else - return MBG_ERR_NOT_SUPP_BY_DEV; -#endif - -} // xdevfeat_supp_tlv_ntp_license - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_supp_tlv_ntp_license; - - - -/*HDR*/ -/** - * @brief Check if a device supports PTPv1 License Infos via TLV - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_tlv_feat_supp - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_supp_tlv_ptpv1_license( const MBG_XDEV_FEATURES *p_xdf ) -{ -#if defined( _PRELIMINARY_CODE ) - return check_tlv_feat_supp( MBG_TLV_FEAT_TYPE_LICENSE_PTPV1_IDX, &p_xdf->tlv_info ); -#else - return MBG_ERR_NOT_SUPP_BY_DEV; -#endif - -} // xdevfeat_supp_tlv_ptpv1_license - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_supp_tlv_ptpv1_license; - - - -/*HDR*/ -/** - * @brief Check if a device supports Time Monitor License infos via TLV - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_tlv_feat_supp - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_supp_tlv_time_monitor_license( const MBG_XDEV_FEATURES *p_xdf ) -{ -#if defined( _PRELIMINARY_CODE ) - return check_tlv_feat_supp( MBG_TLV_FEAT_TYPE_LICENSE_TIME_MONITOR_IDX, &p_xdf->tlv_info ); -#else - return MBG_ERR_NOT_SUPP_BY_DEV; -#endif - -} // xdevfeat_supp_tlv_time_monitor_license - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_supp_tlv_time_monitor_license; - - - -/*HDR*/ -/** - * @brief Check if a device supports the ::GPS_SAVE_CFG command - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_xfeature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_cmd_save_cfg - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_cmd_save_cfg( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_xfeature( MBG_XFEATURE_SAVE_CFG, &p_xdf->xfeature_buffer ); - -} // xdevfeat_has_cmd_save_cfg - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_cmd_save_cfg; - - - -/*HDR*/ -/** - * @brief Check if a device supports the extended feature monitoring - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_xfeature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_monitoring( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_xfeature( MBG_XFEATURE_MONITORING, &p_xdf->xfeature_buffer ); - -} // xdevfeat_has_monitoring - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_monitoring; - - - -/*HDR*/ -/** - * @brief Check if a device supports the LED API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_xfeature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::TODO ### - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_led_api( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_xfeature( MBG_XFEATURE_LED_API, &p_xdf->xfeature_buffer ); - -} // xdevfeat_has_led_api - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_led_api; - - - -/*HDR*/ -/** - * @brief Check if a device supports the LNE API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_xfeature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::TODO ### - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_lne_api( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_xfeature( MBG_XFEATURE_LNE_API, &p_xdf->xfeature_buffer ); - -} // xdevfeat_has_lne_api - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_lne_api; - - - -/*HDR*/ -/** - * @brief Check if a device supports the power control API - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_xfeature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::TODO ### - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_pwr_ctl_api( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_xfeature( MBG_XFEATURE_PWR_CTL_API, &p_xdf->xfeature_buffer ); - -} // xdevfeat_has_pwr_ctl_api - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_pwr_ctl_api; - - - -/*HDR*/ -/** - * @brief Check if a device supports the ::MBG_EXT_SYS_INFO command - * - * @param[in,out] p_xdf Pointer to a valid message control structure - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_xfeature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::TODO ### - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_ext_sys_info( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_xfeature( MBG_XFEATURE_EXT_SYS_INFO, &p_xdf->xfeature_buffer ); - -} // xdevfeat_has_ext_sys_info - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_ext_sys_info; - - - -/*HDR*/ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_io_ports( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_xfeature( MBG_XFEATURE_IO_PORTS, &p_xdf->xfeature_buffer ); - -} // xdevfeat_has_io_ports - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_io_ports; - - - -/*HDR*/ -/** - * @brief Check if a device has ::MBG_XFEATURE_TRANSACTIONS - * - * @param[in,out] p_xdf Pointer to a valid message control structure - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_xfeature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::TODO ### - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_transactions( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_xfeature( MBG_XFEATURE_TRANSACTIONS, &p_xdf->xfeature_buffer ); - -} // xdevfeat_has_transactions - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_transactions; - - - -/*HDR*/ -/** - * @brief Check if a device has ::MBG_XFEATURE_REBOOT - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_xfeature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_reboot( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_xfeature( MBG_XFEATURE_REBOOT, &p_xdf->xfeature_buffer ); - -} // xdevfeat_has_reboot - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_reboot; - - - -/*HDR*/ -/** - * @brief Check if a device has ::MBG_XFEATURE_REQ_TTM - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_xfeature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - * @see mbgextio_get_time - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_req_ttm( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_xfeature( MBG_XFEATURE_REQ_TTM, &p_xdf->xfeature_buffer ); - -} // xdevfeat_has_req_ttm - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_req_ttm; - - - -/*HDR*/ -/** - * @brief Check if a device supports the extended multi ref features including multi instances - * - * The different multi ref feature and its appropriate flags have evolved over time. - * This function only checks the currently up-to-date GPS_HAS_XMRS_MULT_INSTC flag. - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_ri_feature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_get_all_xmulti_ref_info - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_xmulti_ref( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_ri_feature( GPS_HAS_XMRS_MULT_INSTC, &p_xdf->receiver_info ); - -} // xdevfeat_has_xmulti_ref - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_xmulti_ref; - - - -/*HDR*/ -/** - * @brief Check if a device supports the extended binary protocol (XBP) feature - * - * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device - * - * @return ::MBG_SUCCESS if supported, else error code from ::check_ri_feature - * - * @ingroup xdevfeat_chk_supp_fncs - * @see @ref xdevfeat_chk_supp_fncs - */ -_NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_has_xbp( const MBG_XDEV_FEATURES *p_xdf ) -{ - return check_ri_feature( GPS_HAS_XBP, &p_xdf->receiver_info ); - -} // xdevfeat_has_xbp - -XDEVFEAT_CHK_SUPP_FNC xdevfeat_has_xbp; diff --git a/mbglib/common/xdevfeat.h b/mbglib/common/xdevfeat.h index 3ce99d9..19cc633 100755 --- a/mbglib/common/xdevfeat.h +++ b/mbglib/common/xdevfeat.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: xdevfeat.h 1.1.1.28.1.13 2017/04/20 04:58:10 thomas-b TEST $ + * $Id: xdevfeat.h 1.2 2017/07/06 07:49:25 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,91 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: xdevfeat.h $ - * Revision 1.1.1.28.1.13 2017/04/20 04:58:10 thomas-b - * Added function to check for extended features MBG_XFEATURE_USB_LOCK - * Revision 1.1.1.28.1.12 2017/03/07 13:45:34 thomas-b - * Check receiver info feature instead of builtin feature for ignore lock - * Revision 1.1.1.28.1.11 2017/02/22 11:32:52 martin - * Fixed warnings due to preliminary, unfinished code. - * Revision 1.1.1.28.1.10 2017/02/07 14:24:09 thomas-b - * Added function xdevfeat_has_monitoring, which checks if the extended feature MBG_XFEATURE_MONITORING is set - * Revision 1.1.1.28.1.9 2017/02/07 14:10:48 daniel - * Updated function prototypes - * Revision 1.1.1.28.1.8 2016/12/06 10:43:37 thomas-b - * Added function xdevfeat_has_sv_info - * Revision 1.1.1.28.1.7 2016/11/30 16:12:27 thomas-b - * Added function xdevfeat_has_scu_stat - * Revision 1.1.1.28.1.6 2016/11/22 10:33:16 philipp - * Implemented I/O ports - * Revision 1.1.1.28.1.5 2016/11/07 11:31:49 thomas-b - * Fixed typedef for XDEVFEAT_CHK_SUPP_FNC - * Revision 1.1.1.28.1.4 2016/11/02 12:16:19 thomas-b - * Fixed documentation - * Revision 1.1.1.28.1.3 2016/11/02 12:08:22 thomas-b - * Added function to check for new MBG_XFEATURE_REQ_TTM - * Revision 1.1.1.28.1.2 2016/11/01 09:39:32 martin - * Doxygen changes - * Revision 1.1.1.28.1.1 2016/10/25 08:08:37 martin - * Updated function prototypes with preliminary changes. - * Revision 1.1.1.28 2016/10/20 14:46:05 thomas-b - * Added function to check if XBP is supported - * Revision 1.1.1.27 2016/10/20 10:43:36 thomas-b - * Added function to check if a device is a bus level device - * Revision 1.1.1.26 2016/10/14 11:09:41 thomas-b - * Added function to check MBG_XFEATURE_UCAP_NET - * Revision 1.1.1.25 2016/09/29 14:35:35 thomas-b - * Added function to check reboot feature - * Revision 1.1.1.24 2016/09/29 12:19:59 thomas-b - * Added function to check transactions feature - * Revision 1.1.1.23 2016/07/07 15:03:33 martin + * Revision 1.2 2017/07/06 07:49:25 martin + * Added some macros and inline function simplifying + * implementation of the individual check functions. * Updated function prototypes. - * Revision 1.1.1.22 2016/06/15 10:15:52 thomas-b - * Added functions which check if the user capture feature is supported by a device - * Revision 1.1.1.21 2016/06/14 10:33:23 thomas-b - * Added functions which check if the event log feature is supported by a device - * Revision 1.1.1.20 2016/06/07 07:43:09 philipp - * New function to check for Irig Rx feature - * Revision 1.1.1.19 2016/06/02 11:44:37 philipp - * Fixed prototype - * Revision 1.1.1.18 2016/05/30 08:10:47 thomas-b - * Added functions to check several builtin features - * Revision 1.1.1.17 2016/05/20 09:41:39 thomas-b - * Removed functions which check for a specific IMS card - * Revision 1.1.1.16 2016/05/20 08:50:47 thomas-b - * Added functions xdevfeat_has_time_scale and xdevfeat_has_tzcode - * Revision 1.1.1.15 2016/05/17 06:33:13 philipp - * New function to check whether a device has serial outputs - * Revision 1.1.1.14 2016/05/12 10:41:41 philipp - * New functions to check bpe card and IRIG Tx feature - * Revision 1.1.1.13 2016/05/10 06:15:32 philipp - * New function to check whether a device has programmable pulses - * Revision 1.1.1.12 2016/04/26 06:52:46 thomas-b - * Added functions to check if NET_CFG and LAN_IP4 APIs are supported - * Revision 1.1.1.11 2016/04/22 10:54:01 philipp - * New function to check whether device is LIU - * Revision 1.1.1.10 2016/04/20 13:12:58 thomas-b - * Added function to check if a device supports NTP - * Revision 1.1.1.9 2016/04/20 09:26:04 philipp - * Moved all HPS-PTP related structures to gpspriv.h and removed related extended feature bit from gpsdefs.h. - * Also removed functions from mbgextio and xdevfeat since HPS-PTP handling needs a redesign concerning structures. - * Thus, handle everything explicitly for now! - * -> Redesing this A.S.A.P.!!! - * Revision 1.1.1.8 2016/04/15 08:17:27 philipp - * New feature MBG_XFEATURE_EXT_PTP - * Revision 1.1.1.7 2016/04/13 07:01:22 philipp - * New function to check whether device is HPS - * Revision 1.1.1.6 2016/04/12 13:27:42 philipp - * Several new functions to check for device models and device features - * Revision 1.1.1.5 2016/04/11 13:57:17 thomas-b - * Added function xdevfeat_has_xmulti_ref - * Revision 1.1.1.4 2016/04/07 12:36:57 martin - * Updated function prototypes. - * Revision 1.1.1.3 2016/04/04 15:31:25 martin - * New function xdevfeat_is_vsg(). - * Revision 1.1.1.2 2016/03/24 14:08:52 martin - * *** empty log message *** - * Revision 1.1.1.1 2016/03/18 10:48:19 martin - * *** empty log message *** * Revision 1.1 2016/03/16 14:32:52 martin * Initial revision. * @@ -107,6 +26,7 @@ /* Other headers to be included */ #include <gpsdefs.h> +#include <mbgerror.h> #ifdef _XDEVFEAT #define _ext @@ -115,8 +35,13 @@ #define _ext extern #endif + /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + /** * @defgroup chk_supp_fncs Groups of functions used to check if a particular feature is supported * @@ -154,10 +79,6 @@ */ -#ifdef __cplusplus -extern "C" { -#endif - /** * @brief A structure combining all device feature information */ @@ -179,7 +100,75 @@ typedef int _NO_MBG_API XDEVFEAT_CHK_SUPP_FNC( const MBG_XDEV_FEATURES *p_xdf ); -/* function prototypes: */ +/** + * @brief Check if all bits of a specific mask are set in an integer bit mask + * + * This macros checks if specific bits are set in an integer bit mask. + * This is implemented as macro since the macro works properly with + * all integer sizes. + * + * @param[in] _supp_msk An integer bit mask + * @param[in] _chk_msk The bit mask to be tested + * + * @return ::MBG_SUCCESS if all bits of the test mask are set, or + * ::MBG_ERR_NOT_SUPP_BY_DEV if not. + */ +#define _check_feat_supp_mask( _supp_msk, _chk_msk ) \ + ( ( ( (_supp_msk) & (_chk_msk) ) == (_chk_msk) ) ? \ + MBG_SUCCESS : MBG_ERR_NOT_SUPP_BY_DEV ) + + + +/** + * @brief Check if a bits with a specific number is set in an integer bit mask + * + * This macros checks if a bits with specific number is set in an integer bit mask. + * This is implemented as macro since the macro works properly with + * all integer sizes. + * + * @param[in] _supp_msk An integer bit mask + * @param[in] _bit_num The bit mask to be tested + * + * @return ::MBG_SUCCESS if all bits of the test mask are set, or + * ::MBG_ERR_NOT_SUPP_BY_DEV if not. + */ +#define _check_feat_supp_bit( _supp_msk, _bit_num ) \ + ( ( (_supp_msk) & ( 1UL << (_bit_num) ) ) ? \ + MBG_SUCCESS : MBG_ERR_NOT_SUPP_BY_DEV ) + + + +static __mbg_inline /*HDR*/ +/** + * @brief Check if a specific bit is set in a byte array + * + * This function checks if a specific bit is set in an array of bytes. + * Bits are counted starting from the least significant bit of the least + * significant byte. + * + * @param[in] bit_num Number of the bit to be tested, 0..(8*(max_bytes-1)) + * @param[in] p Pointer to a buffer with an array of bytes + * @param[in] max_bytes The number of bytes in the buffer p + * + * @return ::MBG_SUCCESS if the bit is set, ::MBG_ERR_NOT_SUPP_BY_DEV if not, + * or ::MBG_ERR_RANGE if the bit number is out of the range of the array + */ +int check_feat_supp_byte_array( int bit_num, const uint8_t *p, int max_bytes ) +{ + int byte_num = bit_num >> 3; + + if ( byte_num < max_bytes ) // the normal case + { + ulong bit_mask = 1UL << ( bit_num & 0x07 ); + + return ( p[byte_num] & bit_mask ) ? MBG_SUCCESS : MBG_ERR_NOT_SUPP_BY_DEV; + } + + return MBG_ERR_RANGE; + +} // check_feat_supp_byte_array + + /* ----- function prototypes begin ----- */ @@ -229,8 +218,8 @@ typedef int _NO_MBG_API XDEVFEAT_CHK_SUPP_FNC( const MBG_XDEV_FEATURES *p_xdf ); * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) * * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_dev_is_tcr //### TODO - * @see ::mbg_chk_dev_is_tcr //### TODO + * @see ::mbgextio_dev_is_tcr + * @see ::mbg_chk_dev_is_tcr * @see @ref xdevfeat_chk_supp_fncs */ _NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_is_tcr( const MBG_XDEV_FEATURES *p_xdf ) ; @@ -244,7 +233,7 @@ typedef int _NO_MBG_API XDEVFEAT_CHK_SUPP_FNC( const MBG_XDEV_FEATURES *p_xdf ); * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) * * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_dev_is_dcf //### TODO + * @see ::mbgextio_dev_is_dcf * @see ::mbg_chk_dev_is_dcf * @see @ref xdevfeat_chk_supp_fncs */ @@ -259,7 +248,7 @@ typedef int _NO_MBG_API XDEVFEAT_CHK_SUPP_FNC( const MBG_XDEV_FEATURES *p_xdf ); * or ::MBG_ERR_DEV_NOT_SUPP (see @ref xdevfeat_chk_supp_fncs) * * @ingroup xdevfeat_chk_supp_fncs - * @see ::mbgextio_dev_has_pzf //### TODO + * @see ::mbgextio_dev_has_pzf * @see ::mbg_chk_dev_has_pzf * @see @ref xdevfeat_chk_supp_fncs */ @@ -734,6 +723,18 @@ typedef int _NO_MBG_API XDEVFEAT_CHK_SUPP_FNC( const MBG_XDEV_FEATURES *p_xdf ); _NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_supp_tlv_time_monitor_license( const MBG_XDEV_FEATURES *p_xdf ) ; /** + * @brief Check if a device supports UFU (Unified Firmware Update) via TLV + * + * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device + * + * @return ::MBG_SUCCESS if supported, else error code from ::check_tlv_feat_supp + * + * @ingroup xdevfeat_chk_supp_fncs + * @see @ref xdevfeat_chk_supp_fncs + */ + _NO_MBG_API_ATTR int _NO_MBG_API xdevfeat_supp_tlv_ufu( const MBG_XDEV_FEATURES *p_xdf ) ; + + /** * @brief Check if a device supports the ::GPS_SAVE_CFG command * * @param[in,out] p_xdf Pointer to a ::MBG_XDEV_FEATURES buffer associated with the device diff --git a/mbgsetsystime/BSDmakefile b/mbgsetsystime/BSDmakefile new file mode 100755 index 0000000..ce95c1d --- /dev/null +++ b/mbgsetsystime/BSDmakefile @@ -0,0 +1,32 @@ + +######################################################################### +# +# $Id: BSDmakefile 1.1 2017/07/06 07:58:41 martin REL_M $ +# +# Description: +# Special Makefile for mbgsetsystime under *BSD which doesn't contain +# any code specific to GNU make. +# +# ----------------------------------------------------------------------- +# $Log: BSDmakefile $ +# Revision 1.1 2017/07/06 07:58:41 martin +# Initial revision. +# +######################################################################### + +TARGET = mbgsetsystime +INST_TO_SBIN = 1 + +OBJS = $(TARGET).o +OBJS += mbgdevio.o +OBJS += timeutil.o +OBJS += str_util.o +OBJS += toolutil.o +OBJS += mbgerror.o +OBJS += cfg_hlp.o +OBJS += gpsutils.o +OBJS += mbgmktm.o +OBJS += pcpsmktm.o + +BASEDIR := .. +include $(BASEDIR)/Makefile diff --git a/mbgsetsystime/Makefile b/mbgsetsystime/Makefile deleted file mode 100755 index 4670b88..0000000 --- a/mbgsetsystime/Makefile +++ /dev/null @@ -1,70 +0,0 @@ - -######################################################################### -# -# $Id: Makefile 1.8.1.13 2017/02/09 11:23:31 martin TEST $ -# -# Description: -# Makefile for mbgsetsystime. -# -# ----------------------------------------------------------------------- -# $Log: Makefile $ -# Revision 1.8.1.13 2017/02/09 11:23:31 martin -# *** empty log message *** -# Revision 1.8.1.12 2016/08/10 11:32:23 martin -# *** empty log message *** -# Revision 1.8.1.11 2016/08/09 16:02:13 martin -# Fixed build for QNX Neutrino. -# Revision 1.8.1.10 2016/07/15 14:07:25 martin -# Added new module timeutil.o. -# Revision 1.8.1.9 2016/05/30 15:14:21 martin -# *** empty log message *** -# Revision 1.8.1.8 2015/12/17 14:26:48 martin -# Added -lrt to LDFLAGS. Required for clock_settime and glibc before 2.17. -# Revision 1.8.1.7 2015/12/16 14:51:30 martin -# Removed obsolete module cfg_hlp.o. -# Revision 1.8.1.6 2015/08/31 14:22:02 martin -# Revision 1.8.1.5 2015/07/14 15:07:20 martin -# Added object module mbgerror.o. -# Revision 1.8.1.4 2014/04/28 13:19:51 martin -# Added module cfg_hlp.o. -# Revision 1.8.1.3 2011/09/26 16:07:30 martin -# Updated for use with latest base Makefile. -# Revision 1.8.1.2 2010/08/30 09:05:23 martin -# Revision 1.8.1.1 2010/08/30 08:21:54 martin -# Revision 1.8 2009/07/24 10:31:17 martin -# Moved declarations to a common file which is now included. -# Revision 1.7 2008/12/22 11:56:59 martin -# Changed enumeration of source files. -# Define MBGDEVIO_SIMPLE to avoid inclusion of unnecessary modules. -# Revision 1.6 2007/03/02 11:45:10 martin -# Parameter "DEBUG=1" lets the target be built with debug enabled. -# Revision 1.5 2006/08/22 09:06:07 martin -# Added new library module mbgmktm.c. -# Revision 1.4 2003/07/08 15:33:47 martin -# Added gpsutils.c to the module list. -# Revision 1.3 2003/04/25 10:21:06 martin -# Updated source module list. -# Revision 1.2 2002/11/21 14:56:31 martin -# New targets install and uninstall. -# Revision 1.1 2001/09/17 15:08:46 martin -# -######################################################################### - -TARGET = mbgsetsystime -INST_TO_SBIN = 1 - -OBJS = $(TARGET).o -OBJS += mbgdevio.o -OBJS += timeutil.o -OBJS += str_util.o -OBJS += toolutil.o -OBJS += mbgerror.o -OBJS += cfg_hlp.o -OBJS += gpsutils.o -OBJS += mbgmktm.o -OBJS += pcpsmktm.o - -LDFLAGS += -lrt - -BASEDIR := .. -include $(BASEDIR)/Makefile diff --git a/mbgsetsystime/mbgsetsystime.c b/mbgsetsystime/mbgsetsystime.c index 97e9480..62068be 100755 --- a/mbgsetsystime/mbgsetsystime.c +++ b/mbgsetsystime/mbgsetsystime.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgsetsystime.c 1.8.1.20 2017/02/06 11:32:35 martin TEST $ + * $Id: mbgsetsystime.c 1.9 2017/07/05 18:24:44 martin REL_M $ * * Description: * Main file for mbgsetsystime program which reads the current date @@ -14,40 +14,14 @@ * * ----------------------------------------------------------------------- * $Log: mbgsetsystime.c $ - * Revision 1.8.1.20 2017/02/06 11:32:35 martin - * Fixec build under Windows, but system time is - * actually not yet set. - * Revision 1.8.1.19 2016/08/11 07:44:34Z martin - * Revision 1.8.1.18 2016/08/10 11:32:40Z martin - * *** empty log message *** - * Revision 1.8.1.17 2016/07/22 09:57:12 martin - * Quieted some compiler warninges. - * Revision 1.8.1.16 2016/07/15 14:11:31 martin - * Use functions from new module timeutil. - * Revision 1.8.1.15 2016/05/30 15:13:40 martin - * *** empty log message *** - * Revision 1.8.1.14 2015/12/17 12:00:07 martin - * Fixed a compiler warning. - * Revision 1.8.1.13 2015/12/16 15:05:21 martin - * Use mbg_rc_is_success() to evaluate return codes. - * Revision 1.8.1.12 2015/12/16 14:52:40 martin - * Use high resolution time if the device supports it. - * Revision 1.8.1.11 2014/10/28 16:06:48 martin - * Revision 1.8.1.10 2014/10/28 15:19:17 martin - * Revision 1.8.1.9 2014/10/28 13:53:33Z martin - * Revision 1.8.1.8 2014/10/14 10:20:07 martin - * Cleanup fixing compiler warnings under Windows. - * Revision 1.8.1.7 2013/07/22 16:25:11Z martin - * Revision 1.8.1.6 2013/07/11 08:29:30 martin - * Account for modified function call parameter list. - * Revision 1.8.1.5 2013/07/10 13:13:20 martin - * Revision 1.8.1.4 2013/07/10 13:03:29 martin - * Support build under Windows. - * Revision 1.8.1.3 2013/01/24 14:39:51Z 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 + * Revision 1.9 2017/07/05 18:24:44 martin * New way to maintain version information. + * Support build under Windows. + * Use high resolution time if the device supports it. + * Use codes and inline functions from mbgerror.h. + * Use functions from new module timeutil. + * Account for frac_sec_from_bin() obsoleted by bin_frac_32_to_dec_frac(). + * Proper return codes and exit codes. * Revision 1.8 2009/09/29 15:02:15 martin * Updated version number to 3.4.0. * Revision 1.7 2009/07/24 09:50:09 martin @@ -259,7 +233,7 @@ int do_set_system_time_from_pcps_time( MBG_DEV_HANDLE dh ) int rc = mbg_get_time( dh, &t ); - if ( mbg_ioctl_err( rc, "mbg_get_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_time" ) ) return rc; if ( t.status & PCPS_INVT ) @@ -286,7 +260,7 @@ int do_set_system_time_from_pcps_hr_time( MBG_DEV_HANDLE dh ) int rc = mbg_get_hr_time( dh, &ht ); - if ( mbg_ioctl_err( rc, "mbg_get_hr_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_hr_time" ) ) return rc; if ( ht.status & PCPS_INVT ) @@ -298,7 +272,7 @@ int do_set_system_time_from_pcps_hr_time( MBG_DEV_HANDLE dh ) } ts.tv_sec = ht.tstamp.sec; - ts.tv_nsec = frac_sec_from_bin( ht.tstamp.frac, NSECS_PER_SEC ); + ts.tv_nsec = bin_frac_32_to_dec_frac( ht.tstamp.frac, NSECS_PER_SEC ); return set_system_time( &ts ); @@ -333,6 +307,8 @@ done: } // do_mbgsetsystime +static MBG_DEV_HANDLER_FNC do_mbgsetsystime; + static /*HDR*/ @@ -373,23 +349,19 @@ int main( int argc, char *argv[] ) if ( must_print_usage ) { usage(); - return 1; + return MBG_EXIT_CODE_USAGE; } - // The function below checks which devices have been specified - // on the command, and for each device - // - tries to open the device - // - shows basic device info - // - calls the specified callback function - rc = mbg_check_devices( argc, argv, optind, do_mbgsetsystime, 0 ); + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbgsetsystime, 0 ); // determine the exit code based on the return code if ( mbg_rc_is_success( rc ) ) - return 0; // success + return MBG_EXIT_CODE_SUCCESS; // success if ( rc == MBG_ERR_INV_TIME ) - return 1; // device has no valid time + return MBG_EXIT_CODE_INV_TIME; // device has no valid time to set the system time with - return 2; // any error occurred + return MBG_EXIT_CODE_FAIL; // any error occurred } diff --git a/mbgshowsignal/Makefile b/mbgshowsignal/Makefile index a70b943..7bc355d 100755 --- a/mbgshowsignal/Makefile +++ b/mbgshowsignal/Makefile @@ -1,24 +1,16 @@ ######################################################################### # -# $Id: Makefile 1.7.1.7 2016/07/15 14:07:29 martin TEST $ +# $Id: Makefile 1.8 2017/07/05 18:26:51 martin REL_M $ # # Description: # Makefile for mbgshowsignal. # # ----------------------------------------------------------------------- # $Log: Makefile $ -# Revision 1.7.1.7 2016/07/15 14:07:29 martin -# *** empty log message *** -# Revision 1.7.1.6 2015/08/31 14:24:12 martin -# Revision 1.7.1.5 2015/07/14 15:07:20 martin -# Added object module mbgerror.o. -# Revision 1.7.1.4 2014/04/28 13:19:52 martin -# Added module cfg_hlp.o. -# Revision 1.7.1.3 2011/09/26 16:07:30 martin -# Updated for use with latest base Makefile. -# Revision 1.7.1.2 2010/08/30 09:05:23 martin -# Revision 1.7.1.1 2010/08/30 08:22:00 martin +# Revision 1.8 2017/07/05 18:26:51 martin +# Updated list of object files and use top level +# Makefile properly. # Revision 1.7 2009/07/24 10:31:17 martin # Moved declarations to a common file which is now included. # Revision 1.6 2008/12/22 11:56:59 martin diff --git a/mbgshowsignal/mbgshowsignal.c b/mbgshowsignal/mbgshowsignal.c index 0e086ae..f08bd95 100755 --- a/mbgshowsignal/mbgshowsignal.c +++ b/mbgshowsignal/mbgshowsignal.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgshowsignal.c 1.8.1.9 2016/05/30 15:08:59 martin TEST $ + * $Id: mbgshowsignal.c 1.9 2017/07/05 18:31:14 martin REL_M $ * * Description: * Main file for mbgshowsignal program which demonstrates how to @@ -10,22 +10,13 @@ * * ----------------------------------------------------------------------- * $Log: mbgshowsignal.c $ - * Revision 1.8.1.9 2016/05/30 15:08:59 martin - * *** empty log message *** - * Revision 1.8.1.8 2015/10/26 13:51:51 martin - * Revision 1.8.1.7 2013/07/22 16:25:11Z martin - * Revision 1.8.1.6 2013/07/11 08:29:30 martin - * Account for modified function call parameter list. - * Revision 1.8.1.5 2013/07/10 13:02:10 martin - * Removed obsolete include to fix build under Windows. - * Revision 1.8.1.4 2011/10/05 15:10:56Z martin - * Show PZF correlation state. - * Revision 1.8.1.3 2011/07/05 15:35:55 martin - * Modified version handling. - * Revision 1.8.1.2 2011/07/05 14:35:19 martin + * Revision 1.9 2017/07/05 18:31:14 martin * New way to maintain version information. - * Revision 1.8.1.1 2011/07/04 13:19:04 martin + * Support build under Windows. * Update modulation status continuously. + * Show PZF correlation state. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. * Revision 1.8 2009/09/29 15:02:15 martin * Updated version number to 3.4.0. * Revision 1.7 2009/07/24 09:50:09 martin @@ -70,17 +61,20 @@ static const char *pname = "mbgshowsignal"; static /*HDR*/ -int show_modulation( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) +int show_modulation( MBG_DEV_HANDLE dh ) { static time_t prv_sys_t; time_t sys_t; PCPS_STATUS_PORT status_port; // current value of the clock's status port PCPS_TIME t; int signal; + + bool dev_has_pzf = mbg_chk_dev_has_pzf( dh ) == MBG_SUCCESS; + int rc = mbg_get_status_port( dh, &status_port ); // read status port - if ( mbg_ioctl_err( rc, "mbg_get_status_port" ) ) - return -1; + if ( mbg_cond_err_msg( rc, "mbg_get_status_port" ) ) + return rc; // show signal only once per second sys_t = time( NULL ); @@ -89,8 +83,8 @@ int show_modulation( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) { rc = mbg_get_time( dh, &t ); - if ( mbg_ioctl_err( rc, "mbg_get_time" ) ) - return -1; + if ( mbg_cond_err_msg( rc, "mbg_get_time" ) ) + return rc; prv_sys_t = sys_t; } @@ -109,12 +103,12 @@ int show_modulation( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) printf( " Signal: %u%% ", signal * 100 / PCPS_SIG_MAX ); - if ( _pcps_has_pzf( p_dev ) ) - mbg_show_pzf_corr_info( dh, p_dev, 1 ); + if ( dev_has_pzf ) + rc = mbg_show_pzf_corr_info( dh, 1 ); printf( " " ); - return 0; + return rc; } // show_modulation @@ -127,30 +121,23 @@ int do_mbgshowsignal( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) if ( mbg_rc_is_error( rc ) ) { - if ( rc == MBG_ERR_NOT_SUPP_BY_DEV ) // ### TODO not_supp - { - printf( "This device does not support monitoring signal modulation.\n" ); - goto done; - } - - mbg_ioctl_err( rc, "mbg_dev_has_mod" ); - goto fail; + mbg_cond_err_msg_info( rc, "mbg_dev_has_mod", + "support monitoring signal modulation" ); + return rc; } printf( "\nMonitoring signal modulation:\n" ); for (;;) - if ( show_modulation( dh, p_dev ) < 0 ) - goto fail; + if ( mbg_rc_is_error( rc = show_modulation( dh ) ) ) + break; -done: - return 0; - -fail: - return -1; + return rc; } // do_mbgshowsignal +static MBG_DEV_HANDLER_FNC do_mbgshowsignal; + static /*HDR*/ @@ -190,15 +177,11 @@ int main( int argc, char *argv[] ) if ( must_print_usage ) { usage(); - return 1; + return MBG_EXIT_CODE_USAGE; } - // The function below checks which devices have been specified - // on the command, and for each device - // - tries to open the device - // - shows basic device info - // - calls the specified callback function - rc = mbg_check_devices( argc, argv, optind, do_mbgshowsignal, 0 ); + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbgshowsignal, 0 ); - return abs( rc ); + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; } diff --git a/mbgstatus/Makefile b/mbgstatus/Makefile index 2141869..214c076 100755 --- a/mbgstatus/Makefile +++ b/mbgstatus/Makefile @@ -1,36 +1,16 @@ ######################################################################### # -# $Id: Makefile 1.7.1.13 2016/09/05 11:31:32 martin TEST $ +# $Id: Makefile 1.8 2017/07/05 18:27:30 martin REL_M $ # # Description: # Makefile for mbgstatus. # # ----------------------------------------------------------------------- # $Log: Makefile $ -# Revision 1.7.1.13 2016/09/05 11:31:32 martin -# Removed mbgmktime from the list of object files. -# Revision 1.7.1.12 2016/07/15 14:07:29 martin -# *** empty log message *** -# Revision 1.7.1.11 2015/10/27 15:07:38 martin -# Removed obsolete object modules. -# Revision 1.7.1.10 2015/08/31 14:20:35 martin -# Revision 1.7.1.9 2015/07/14 15:07:21 martin -# Added object module mbgerror.o. -# Revision 1.7.1.8 2014/04/28 13:19:52 martin -# Added module cfg_hlp.o. -# Revision 1.7.1.7 2014/04/28 09:49:04 martin -# Revision 1.7.1.6 2014/04/25 09:15:34 martin -# Revision 1.7.1.5 2011/09/26 16:07:50 martin -# Updated for use with latest base Makefile. -# Added module lan_util. -# Revision 1.7.1.4 2010/08/30 09:05:24 martin -# Revision 1.7.1.3 2010/08/30 08:20:32 martin -# Revision 1.7.1.2 2010/08/24 08:35:11 martin -# This basically builds kernel modules and user space apps correctly. -# However, there's still an absolute path specification which needs -# to be resolved. -# Revision 1.7.1.1 2010/08/24 08:02:05 martin +# Revision 1.8 2017/07/05 18:27:30 martin +# Updated list of object files and use top level +# Makefile properly. # Revision 1.7 2009/07/24 10:31:17 martin # Moved declarations to a common file which is now included. # Revision 1.6 2008/12/22 11:54:32 martin @@ -64,6 +44,7 @@ OBJS += deviohlp.o OBJS += ctrydttm.o OBJS += ctry.o OBJS += lan_util.o +OBJS += nanotime.o BASEDIR := .. include $(BASEDIR)/Makefile diff --git a/mbgstatus/mbgstatus.c b/mbgstatus/mbgstatus.c index 644495c..e801034 100755 --- a/mbgstatus/mbgstatus.c +++ b/mbgstatus/mbgstatus.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgstatus.c 1.13.1.56 2016/10/20 14:08:04 martin TEST $ + * $Id: mbgstatus.c 1.14 2017/07/05 18:34:46 martin REL_M $ * * Description: * Main file for mbgstatus program which demonstrates how to @@ -10,91 +10,13 @@ * * ----------------------------------------------------------------------- * $Log: mbgstatus.c $ - * Revision 1.13.1.56 2016/10/20 14:08:04 martin - * Parameters -u and -s imply -c. - * Revision 1.13.1.55 2016/09/14 16:17:31 martin - * Account for changed APi function. - * Revision 1.13.1.54 2016/08/10 14:45:27 martin - * *** empty log message *** - * Revision 1.13.1.53 2016/07/22 09:57:12 martin - * Quieted some compiler warninges. - * Revision 1.13.1.52 2016/07/15 14:10:49 martin - * Use functions from new module timeutil. - * Revision 1.13.1.51 2015/11/10 16:20:18 martin - * *** empty log message *** - * Revision 1.13.1.50 2015/10/26 13:50:42 martin - * Revision 1.13.1.49 2015/10/07 10:58:09Z martin - * Account for changes in GNSS API. - * Revision 1.13.1.48 2015/08/27 16:34:10 martin - * Use safe string functions. - * Revision 1.13.1.47 2015/04/29 13:12:54 martin - * Support looping on device. - * Revision 1.13.1.46 2014/10/28 13:53:51Z martin - * Revision 1.13.1.45 2014/10/14 09:05:34 martin - * Revision 1.13.1.44 2014/07/14 15:42:44 martin - * Revision 1.13.1.43 2014/04/28 13:36:14 martin - * Revision 1.13.1.42 2014/04/28 12:39:59 martin - * Revision 1.13.1.41 2014/04/28 09:49:04 martin - * Revision 1.13.1.40 2014/04/25 09:15:57 martin - * Moved some functions to new module cfg_hlp.c. - * Revision 1.13.1.39 2014/04/23 14:56:42 martin - * Revision 1.13.1.38 2014/04/23 12:36:26 martin - * Revision 1.13.1.37 2014/04/23 08:44:45 martin - * Revision 1.13.1.36 2014/04/17 07:44:25 martin - * Revision 1.13.1.35 2014/04/15 13:39:07 martin - * Revision 1.13.1.34 2013/12/19 16:18:48 martin - * Revision 1.13.1.33 2013/08/01 16:51:33 martin - * Revision 1.13.1.32 2013/08/01 16:16:12 martin - * Revision 1.13.1.31 2013/07/22 16:25:11 martin - * Revision 1.13.1.30 2013/07/16 15:45:38 martin - * Revision 1.13.1.29 2013/07/11 08:29:30 martin - * Account for modified function call parameter list. - * Revision 1.13.1.28 2013/07/10 13:02:22 martin - * Revision 1.13.1.27 2013/07/08 12:04:39Z martin - * 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 - * Show PZF correlation state. - * Revision 1.13.1.16 2011/10/05 13:03:34 martin - * Adapted PZF correlation/signal/status display. - * Revision 1.13.1.15 2011/10/05 11:57:42 martin - * Revision 1.13.1.14 2011/09/29 16:30:03 martin - * Started to support PZF. - * Optionally show hex status. - * Changed what is displayed in certain levels of verbosity. - * Revision 1.13.1.13 2011/09/07 15:08:55 martin - * Account for modified library functions which can now - * optionally print the raw (hex) HR time stamp. - * Revision 1.13.1.12 2011/07/08 11:02:47 martin - * Revision 1.13.1.11 2011/07/05 15:35:55 martin - * Modified version handling. - * Revision 1.13.1.10 2011/07/05 14:35:19 martin + * Revision 1.14 2017/07/05 18:34:46 martin * New way to maintain version information. - * Revision 1.13.1.9 2011/04/20 16:08:27 martin - * Use snprint_ip4_addr() from module lan_util. - * Revision 1.13.1.8 2011/03/03 10:01:23 daniel - * Indicate Unicast role in PTP port state - * Revision 1.13.1.7 2011/02/07 12:10:58 martin - * Use mbg_get_ptp_status() API call. - * Revision 1.13.1.6 2010/11/25 14:54:51 martin - * Revision 1.13.1.5 2010/11/05 12:54:22 martin - * Introduce "verbose" flag and associated command line parameter -v. - * Revision 1.13.1.4 2010/10/15 11:28:56 martin - * Display UTC offs from IRIG signal. - * Revision 1.13.1.3 2010/08/30 08:22:24 martin - * Revision 1.13.1.2 2010/08/11 15:06:49 martin - * Preliminarily display raw IRIG data, if supported by the device. - * Revision 1.13.1.1 2010/02/17 14:11:43 martin - * Cosmetics ... + * Support build under Windows. + * Show many more details, at different verbosity levels. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. * Revision 1.13 2009/09/29 15:02:16 martin * Updated version number to 3.4.0. * Revision 1.12 2009/07/24 14:02:59 martin @@ -151,6 +73,7 @@ #include <deviohlp.h> #include <timeutil.h> #include <str_util.h> +#include <nanotime.h> // include system headers #include <stdio.h> @@ -165,6 +88,7 @@ static const char *pname = "mbgstatus"; static int loops; +static int must_list_device_names; static long sleep_secs; static long sleep_usecs; static unsigned int verbose; @@ -364,7 +288,8 @@ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char * int signal; int i; int rc = mbg_get_time( dh, &t ); - if ( mbg_ioctl_err( rc, "mbg_get_time" ) ) + + if ( mbg_cond_err_msg( rc, "mbg_get_time" ) ) return; @@ -377,7 +302,7 @@ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char * rc = mbg_get_hr_time( dh, &ht ); - if ( mbg_ioctl_err( rc, "mbg_get_hr_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_hr_time" ) ) return; mbg_snprint_hr_time( ws, sizeof( ws ), &ht, 0 ); // raw timestamp? @@ -402,7 +327,7 @@ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char * if ( _pcps_has_pzf( pdev ) ) { - mbg_show_pzf_corr_info( dh, pdev, 0 ); + mbg_show_pzf_corr_info( dh, 0 ); printf( "\n" ); } @@ -412,7 +337,7 @@ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char * rc = mbg_get_irig_time( dh, &it ); - if ( !mbg_ioctl_err( rc, "mbg_get_irig_time" ) ) + if ( !mbg_cond_err_msg( rc, "mbg_get_irig_time" ) ) printf( "Raw IRIG time: yday %u, %02u:%02u:%02u\n", it.yday, it.hour, it.min, it.sec ); } @@ -443,7 +368,7 @@ void show_time_and_status( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const char * rc = mbg_get_ref_offs( dh, &ref_offs ); - if ( !mbg_ioctl_err( rc, "mbg_get_ref_offs" ) ) + if ( !mbg_cond_err_msg( rc, "mbg_get_ref_offs" ) ) { if ( _pcps_ref_offs_out_of_range( ref_offs ) ) invt_reason = 2; @@ -462,7 +387,7 @@ void show_sync_time( MBG_DEV_HANDLE dh, const char *tail ) PCPS_TIME t; int rc = mbg_get_sync_time( dh, &t ); - if ( mbg_ioctl_err( rc, "mbg_get_sync_time" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_sync_time" ) ) return; print_pcps_time( "Last sync: ", &t, tail ); @@ -487,25 +412,21 @@ void show_ext_stat_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *t rc = mbg_setup_receiver_info( dh, p_dev, &ri ); - if ( mbg_ioctl_err( rc, "mbg_setup_receiver_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_setup_receiver_info" ) ) return; -#if !defined( DEBUG ) if ( mbg_rc_is_success( mbg_chk_dev_is_gps( dh ) ) ) -#endif { rc = mbg_chk_get_all_gnss_info( dh, &agi ); - if ( mbg_ioctl_err( rc, "mbg_chk_get_gnss_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_chk_get_gnss_info" ) ) return; } // now print information - #if DEBUG if ( verbose ) printf( "Feature mask: 0x%08lX\n", (ulong) ri.features ); - #endif if ( _pcps_has_stat_info( p_dev ) ) { @@ -530,7 +451,7 @@ void show_ext_stat_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev, const char *t if ( agi.n_gnss_supp ) { - #if defined( DEBUG ) + #if defined( DEBUG ) // TODO int must_print_sv_list = _pcps_has_stat_info_svs( p_dev ) && verbose; #else int must_print_sv_list = _pcps_is_gnss( p_dev ) && verbose; @@ -620,7 +541,7 @@ void show_gps_pos( MBG_DEV_HANDLE dh, const char *tail ) POS pos; int rc = mbg_get_gps_pos( dh, &pos ); - if ( mbg_ioctl_err( rc, "mbg_get_gps_pos" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_gps_pos" ) ) return; print_position( "Receiver Position:", &pos, tail ); @@ -636,7 +557,7 @@ void show_utc_info( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) int rc = mbg_get_utc_parm( dh, &utc ); - if ( mbg_ioctl_err( rc, "mbg_get_utc_parm" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_utc_parm" ) ) return; @@ -701,7 +622,7 @@ void show_irig_ctrl_bits( MBG_DEV_HANDLE dh ) int rc = mbg_get_irig_ctrl_bits( dh, &irig_ctrl_bits ); - if ( mbg_ioctl_err( rc, "mbg_get_irig_ctrl_bits" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_irig_ctrl_bits" ) ) return; printf( "IRIG control bits: %08lX (hex, LSB first)", (ulong) irig_ctrl_bits ); @@ -741,7 +662,7 @@ void show_raw_irig_data( MBG_DEV_HANDLE dh ) int rc = mbg_get_raw_irig_data( dh, &raw_irig_data ); - if ( mbg_ioctl_err( rc, "mbg_get_raw_irig_data" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_raw_irig_data" ) ) return; printf( "Raw IRIG data:" ); @@ -767,7 +688,7 @@ void show_irig_debug_status( MBG_DEV_HANDLE dh ) int i; int rc = _mbg_generic_read_var( dh, PCPS_GET_DEBUG_STATUS, st ); - if ( mbg_ioctl_err( rc, "show_irig_debug_status" ) ) + if ( mbg_cond_err_msg( rc, "show_irig_debug_status" ) ) return; printf( "Debug status (hex): %08lX\n", (ulong) st ); @@ -789,12 +710,12 @@ void show_lan_intf_state( MBG_DEV_HANDLE dh ) int rc = mbg_get_ip4_state( dh, &ip4_settings ); - if ( mbg_ioctl_err( rc, "mbg_get_ip4_state" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_ip4_state" ) ) return; rc = mbg_get_lan_if_info( dh, &lan_if_info ); - if ( mbg_ioctl_err( rc, "mbg_get_lan_if_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_lan_if_info" ) ) return; @@ -846,12 +767,12 @@ void show_ptp_state( MBG_DEV_HANDLE dh ) int rc = mbg_get_ptp_state( dh, &ptp_state ); - if ( mbg_ioctl_err( rc, "mbg_get_ptp_state" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_ptp_state" ) ) return; rc = mbg_get_ptp_cfg_info( dh, &ptp_info ); - if ( mbg_ioctl_err( rc, "mbg_get_ptp_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_ptp_info" ) ) return; @@ -1045,8 +966,8 @@ int check_irq_unsafe( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) int ret_val = 0; int rc = mbg_get_irq_stat_info( dh, &irq_stat_info ); - if ( mbg_ioctl_err( rc, "mbg_get_irq_stat_info" ) ) - return -1; + if ( mbg_cond_err_msg( rc, "mbg_get_irq_stat_info" ) ) + return rc; if ( irq_stat_info & PCPS_IRQ_STAT_UNSAFE ) { @@ -1115,26 +1036,18 @@ int do_mbgstatus( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) if ( verbose && _pcps_has_irig_ctrl_bits( p_dev ) ) show_irig_ctrl_bits( dh ); - if ( verbose && _pcps_has_raw_irig_data( p_dev ) ) + if ( verbose && ( mbg_chk_dev_has_raw_irig_data( dh ) == MBG_SUCCESS ) ) show_raw_irig_data( dh ); if ( verbose && _pcps_is_irig_rx( p_dev ) ) show_irig_debug_status( dh ); - if ( _pcps_has_lan_intf( p_dev ) ) + if ( mbg_chk_dev_has_lan_intf( dh ) == MBG_SUCCESS ) show_lan_intf_state( dh ); if ( _pcps_has_ptp( p_dev ) ) show_ptp_state( dh ); - #if 0 && defined( DEBUG ) //##++++++++ - if ( verbose > 1 ) - { - test_xmr( dh, p_dev, verbose ); - test_gpio( dh, p_dev, verbose ); - } - #endif - if ( loops > 0 ) loops--; @@ -1159,6 +1072,8 @@ done: } // do_mbgstatus +static MBG_DEV_HANDLER_FNC do_mbgstatus; + static /*HDR*/ @@ -1170,6 +1085,7 @@ void usage( void ) ); mbg_print_help_options(); mbg_print_opt_info( "-c", "run continuously" ); + mbg_print_opt_info( "-l", "list device names" ); mbg_print_opt_info( "-n num", "run num loops" ); mbg_print_opt_info( "-s num", "sleep num seconds between calls (implies -c)" ); mbg_print_opt_info( "-u num", "sleep num microseconds between calls (implies -c)" ); @@ -1194,7 +1110,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, "cn:s:u:vh?" ) ) != -1 ) + while ( ( c = getopt( argc, argv, "cln:s:u:vh?" ) ) != -1 ) { switch ( c ) { @@ -1202,6 +1118,10 @@ int main( int argc, char *argv[] ) loops = -1; break; + case 'l': + must_list_device_names = 1; + break; + case 'n': loops = atoi( optarg ); break; @@ -1230,19 +1150,38 @@ int main( int argc, char *argv[] ) if ( must_print_usage ) { usage(); - return 1; + return MBG_EXIT_CODE_USAGE; } + if ( must_list_device_names ) + { + MBG_DEV_NAME_LIST_ENTRY *list_head = NULL; + int n_dev = mbg_find_devices_with_names( &list_head, N_SUPP_DEV_BUS ); + + if ( n_dev ) + { + MBG_DEV_NAME_LIST_ENTRY *pos; + + printf( "Unique names of devices found:\n" ); + + for ( pos = list_head; pos; pos = pos->next ) + printf( " %s\n", pos->dev_name ); + } + else + printf( "No device found.\n" ); + + mbg_free_device_name_list( list_head ); + printf( "\n" ); + + return MBG_EXIT_CODE_SUCCESS; + } + if ( verbose ) pcps_date_time_dist = 1; - // The function below checks which devices have been specified - // on the command, and for each device - // - tries to open the device - // - shows basic device info - // - calls the specified callback function - rc = mbg_check_devices( argc, argv, optind, do_mbgstatus, CHK_DEV_ALL_DEVICES ); + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbgstatus, CHK_DEV_ALL_DEVICES ); - return abs( rc ); + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; } diff --git a/mbgsvcd/BSDmakefile b/mbgsvcd/BSDmakefile index 9f4742d..474c075 100755 --- a/mbgsvcd/BSDmakefile +++ b/mbgsvcd/BSDmakefile @@ -1,7 +1,7 @@ ######################################################################### # -# $Id: BSDmakefile 1.1 2017/04/25 20:21:30 martin TEST $ +# $Id: BSDmakefile 1.1 2017/04/25 20:21:30 martin REL_M $ # # Description: # Special Makefile for mbgsvcd under *BSD which doesn't contain diff --git a/mbgsvcd/mbgsvcd.c b/mbgsvcd/mbgsvcd.c index 9c1df73..b5f03d7 100755 --- a/mbgsvcd/mbgsvcd.c +++ b/mbgsvcd/mbgsvcd.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgsvcd.c 1.3.1.15.1.5.1.5 2017/02/17 11:49:39 martin TEST $ + * $Id: mbgsvcd.c 1.4 2017/07/05 18:45:29 martin REL_M $ * * Description: * Main file for mbgsvcd which compares the system time to a PCI card's @@ -9,59 +9,27 @@ * * ----------------------------------------------------------------------- * $Log: mbgsvcd.c $ - * Revision 1.3.1.15.1.5.1.5 2017/02/17 11:49:39 martin - * Fixed a comiler warning. - * Revision 1.3.1.15.1.5.1.4 2017/01/30 09:05:54 martin - * Fixed a typo. - * Removed non-ASCII character in comment. - * Revision 1.3.1.15.1.5.1.3 2017/01/27 12:23:35 martin - * Account for renamed structure fields. - * Revision 1.3.1.15.1.5.1.2 2015/12/17 11:59:39 martin - * Fixed a compiler warning 'set but not used'. - * Revision 1.3.1.15.1.5.1.1 2014/11/25 13:47:04 martin - * Support options -q and -r. - * 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 - * Combined printf() and syslog() to mbg_log(). - * Cleanup. - * Revision 1.3.1.12 2011/10/05 15:11:50 martin - * Log reasons for error if function calls fail. - * Revision 1.3.1.11 2011/09/07 15:08:56 martin - * Account for modified library functions which can now - * optionally print the raw (hex) HR time stamp. - * Revision 1.3.1.10 2011/07/14 13:30:57 martin - * Code cleanup. - * Eliminated some potential warnings due to ignored function return values. - * Revision 1.3.1.9 2011/07/05 15:35:55 martin - * Modified version handling. - * Revision 1.3.1.8 2011/07/05 14:35:19 martin + * Revision 1.4 2017/07/05 18:45:29 martin * New way to maintain version information. - * Revision 1.3.1.7 2011/06/23 15:35:40 martin - * Skip devices which don't support HR time immediately at startup. - * Revision 1.3.1.6 2011/06/23 15:02:55 martin + * Print PC cycles counter frequency at program start. + * Use /var/run as directory for the lockfile. + * Using generic MBG_SYS_TIME with nanosecond resolution. + * Workaround in case cycle frequency can not be determined. * Compute execution time limit in cycles instead of us so this can also * be done if the cycle counter clock rate can not be determined. - * Revision 1.3.1.5 2011/06/23 12:45:37 martin - * Workaround in case cycle frequency can not be determined. - * Revision 1.3.1.4 2011/06/20 15:10:22 martin - * Using generic MBG_SYS_TIME with nanosecond resolution. - * Revision 1.3.1.3 2011/03/25 11:05:24 martin - * Optionally support timespec for sys time. - * Cleanup. - * Revision 1.3.1.2 2011/03/23 16:30:40 martin - * Use /var/run as directory for the lockfile. - * Revision 1.3.1.1 2010/04/26 14:37:41 martin - * Print PC cycles counter frequency at program start. + * Skip devices which don't support HR time immediately at startup. + * Log reasons for error if function calls fail. + * Combined printf() and syslog() to mbg_log(). + * Added leap second support. + * Moved some code to some extra modules which can be shared. + * Use seconds for the trust time. + * Support options -q and -r. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Patch submitted by <juergen.perlinger@t-online.de>: + * Support variable number of SHM units and number + * of the first unit to use. + * Proper return codes and exit codes. * Revision 1.3 2010/03/03 14:59:36 martin * Support -p parameter to pretend sync. * Revision 1.2 2010/02/03 16:15:09 daniel @@ -73,6 +41,7 @@ #include <mbgdevio.h> #include <pcpsutil.h> #include <toolutil.h> // common utility functions +#include <mbgerror.h> #include <pcpsmktm.h> #include <chk_time_info.h> #include <ntp_shm.h> @@ -113,7 +82,8 @@ static int pretend_sync; // -p static int print_raw; // -r static int sleep_intv = 1; // -s static unsigned long trust_time_seconds; // -t - +static int n_unit0 = 0; // -o +static int n_units = MAX_SHM_REFCLOCKS; // -n static int frac_digits = 9; MBG_PC_CYCLES_FREQUENCY cyc_freq; @@ -183,7 +153,7 @@ int do_mbgsvctasks( void ) dhs[n_devices] = dh; devs[n_devices] = dev_info; - if ( ++n_devices >= MAX_SHM_REFCLOCKS ) + if ( ++n_devices >= n_units ) break; } @@ -202,7 +172,7 @@ int do_mbgsvctasks( void ) rc = mbg_get_default_cycles_frequency_from_dev( dhs[0], &cyc_freq ); - if ( mbg_ioctl_err( rc, "mbg_get_default_cycles_frequency_from_dev" ) ) + if ( mbg_cond_err_msg( rc, "mbg_get_default_cycles_frequency_from_dev" ) ) goto done; @@ -211,7 +181,7 @@ int do_mbgsvctasks( void ) (unsigned long long) cyc_freq ); // Initialize NTP shared memory area - ntpshm_init( shmTime, n_devices ); + ntpshm_init( shmTime, n_devices, n_unit0 ); for (;;) { @@ -223,7 +193,7 @@ int do_mbgsvctasks( void ) rc = mbg_chk_time_info( dhs[i], &cti, &filter, 0 ); //##+++++ one or more filter instances ? - if ( mbg_ioctl_err( rc, "mbg_chk_time_info" ) ) + if ( mbg_cond_err_msg( rc, "mbg_chk_time_info" ) ) continue; cp = ""; @@ -352,6 +322,8 @@ void usage( void ) 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_opt_info( "-n num", "number of SHM segments to use" ); + mbg_print_opt_info( "-o num", "SHM segment number offset (default 0)" ); mbg_print_device_options(); puts( "" ); @@ -429,7 +401,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, "fpqrst:h?" ) ) != -1 ) + while ( ( c = getopt( argc, argv, "fpqrst:n:o:h?" ) ) != -1 ) { switch ( c ) { @@ -463,6 +435,30 @@ int main( int argc, char *argv[] ) break; } + case 'n': + n_units = atoi( optarg ); + + if ( n_units < 0 || n_units > MAX_SHM_REFCLOCKS ) + { + mbg_log( LOG_WARNING, "Configured number of SHM units %i out of range, truncating to %i", + n_units, MAX_SHM_REFCLOCKS ); + n_units = MAX_SHM_REFCLOCKS; + } + + break; + + case 'o': + n_unit0 = atoi( optarg ); + + if ( n_unit0 < 0 || n_unit0 >= MAX_SHM_UNIT_OFFSET ) + { + mbg_log( LOG_WARNING, "Configured SHM unit offset %i out of range %i to %i, truncating to %i", + n_unit0, 0, MAX_SHM_UNIT_OFFSET, 0 ); + n_unit0 = 0; + } + + break; + case 'h': case '?': default: @@ -473,7 +469,7 @@ int main( int argc, char *argv[] ) if ( must_print_usage ) { usage(); - return 1; + return MBG_EXIT_CODE_USAGE; } if ( foreground == 0 ) @@ -493,5 +489,5 @@ int main( int argc, char *argv[] ) rc = do_mbgsvctasks(); - return abs( rc ); + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; } diff --git a/mbgversion.h b/mbgversion.h index 6bf9c1e..0556bde 100755 --- a/mbgversion.h +++ b/mbgversion.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgversion.h 1.1.1.3 2017/02/23 15:24:05 martin TEST $ + * $Id: mbgversion.h 1.2 2017/06/30 13:31:48 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,12 +10,8 @@ * * ----------------------------------------------------------------------- * $Log: mbgversion.h $ - * Revision 1.1.1.3 2017/02/23 15:24:05 martin - * Changed copyright year to 2017. - * 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.2 2017/06/30 13:31:48 martin + * Changed version code to 1.0.0 and copyright year to 2017. * Revision 1.1 2011/07/06 13:24:48 martin * Initial revision. * @@ -24,10 +20,10 @@ #define MBG_CURRENT_COPYRIGHT_YEAR 2017 #define MBG_CURRENT_COPYRIGHT_YEAR_STR "2017" -#define MBG_MAJOR_VERSION_CODE 0 -#define MBG_MINOR_VERSION_CODE 99 +#define MBG_MAJOR_VERSION_CODE 1 +#define MBG_MINOR_VERSION_CODE 0 -#define MBG_MAIN_VERSION_STR "0.99" +#define MBG_MAIN_VERSION_STR "1.0" #define MBG_MAIN_VERSION_CODE ( ( MBG_MAJOR_VERSION_CODE << 8 ) | MBG_MINOR_VERSION_CODE ) diff --git a/mbgxhrtime/Makefile b/mbgxhrtime/Makefile index 51c10a3..a507de6 100755 --- a/mbgxhrtime/Makefile +++ b/mbgxhrtime/Makefile @@ -1,24 +1,16 @@ ######################################################################### # -# $Id: Makefile 1.2.1.7 2016/07/15 14:07:29 martin TEST $ +# $Id: Makefile 1.3 2017/07/05 18:36:06 martin REL_M $ # # Description: # Makefile for mbgxhrtime. # # ----------------------------------------------------------------------- # $Log: Makefile $ -# Revision 1.2.1.7 2016/07/15 14:07:29 martin -# *** empty log message *** -# Revision 1.2.1.6 2015/08/31 14:29:41 martin -# Revision 1.2.1.5 2015/07/14 15:07:21 martin -# Added object module mbgerror.o. -# Revision 1.2.1.4 2014/04/28 13:19:52 martin -# Added module cfg_hlp.o. -# Revision 1.2.1.3 2011/09/26 16:07:31 martin -# Updated for use with latest base Makefile. -# Revision 1.2.1.2 2010/08/30 09:05:24 martin -# Revision 1.2.1.1 2010/08/30 08:22:11 martin +# Revision 1.3 2017/07/05 18:36:06 martin +# Updated list of object files and use top level +# Makefile properly. # Revision 1.2 2009/07/24 10:31:17 martin # Moved declarations to a common file which is now included. # Revision 1.1 2008/12/22 11:05:24 martin diff --git a/mbgxhrtime/mbgxhrtime.c b/mbgxhrtime/mbgxhrtime.c index 392bab9..c24b715 100755 --- a/mbgxhrtime/mbgxhrtime.c +++ b/mbgxhrtime/mbgxhrtime.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgxhrtime.c 1.5.1.10 2016/08/09 07:13:30 martin TEST $ + * $Id: mbgxhrtime.c 1.6 2017/07/05 18:38:18 martin REL_M $ * * Description: * Main file for mbgxhrtime program which demonstrates how to retrieve @@ -41,22 +41,12 @@ * * ----------------------------------------------------------------------- * $Log: mbgxhrtime.c $ - * Revision 1.5.1.10 2016/08/09 07:13:30 martin - * *** empty log message *** - * Revision 1.5.1.9 2015/10/26 13:53:10 martin - * Revision 1.5.1.8 2014/10/28 15:38:45Z martin - * Revision 1.5.1.7 2014/10/16 10:37:44Z martin - * Revision 1.5.1.6 2013/07/22 16:25:11Z martin - * Revision 1.5.1.5 2013/07/11 08:29:30 martin - * Account for modified function call parameter list. - * Revision 1.5.1.4 2013/07/10 13:02:58 martin - * Revision 1.5.1.3 2011/09/07 15:08:56Z martin - * Account for modified library functions which can now - * optionally print the raw (hex) HR time stamp. - * Revision 1.5.1.2 2011/07/05 15:35:56 martin - * Modified version handling. - * Revision 1.5.1.1 2011/07/05 14:36:11 martin + * Revision 1.6 2017/07/05 18:38:18 martin * New way to maintain version information. + * Support build under Windows. + * Use more functions from common library modules. + * Use codes and inline functions from mbgerror.h. + * Proper return codes and exit codes. * Revision 1.5 2009/09/29 14:25:07 martin * Display measured and default PC cycles frequency. * Updated version number to 3.4.0. @@ -195,7 +185,7 @@ int do_mbgxhrtime( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev ) rc = mbg_xhrt_poll_thread_create( &poll_thread_info, dh, 0, 0 ); if ( rc != MBG_SUCCESS ) - return -1; + return rc; for (;;) @@ -276,6 +266,8 @@ done: } // do_mbgxhrtime +static MBG_DEV_HANDLER_FNC do_mbgxhrtime; + static /*HDR*/ @@ -333,7 +325,7 @@ int main( int argc, char *argv[] ) if ( must_print_usage ) { usage(); - return 1; + return MBG_EXIT_CODE_USAGE; } #if USE_PROCESS_AFFINITY @@ -341,12 +333,8 @@ int main( int argc, char *argv[] ) puts( "" ); #endif - // The function below checks which devices have been specified - // on the command, and for each device - // - tries to open the device - // - shows basic device info - // - calls the specified callback function - rc = mbg_check_devices( argc, argv, optind, do_mbgxhrtime, 0 ); + // Handle each of the specified devices. + rc = mbg_handle_devices( argc, argv, optind, do_mbgxhrtime, 0 ); - return abs( rc ); + return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL; } diff --git a/scripts/mbgsvcd b/scripts/mbgsvcd index ed3b2f8..1c82153 100755 --- a/scripts/mbgsvcd +++ b/scripts/mbgsvcd @@ -1,6 +1,6 @@ #!/bin/sh # -# $Id: mbgsvcd 1.1 2011/07/06 13:26:01 martin TEST $ +# $Id: mbgsvcd 1.1 2011/07/06 13:26:01 martin REL_M $ # # PROVIDE: mbgsvcd # REQUIRE: DAEMON |