mbgdevio.c

Go to the documentation of this file.

/**************************************************************************
 *
 *  $Id: mbgdevio.c 1.42 2018/11/22 14:21:19 martin REL_M $
 *
 *  Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
 *
 *  Description:
 *    Functions called from user space to access Meinberg device drivers.
 *
 * -----------------------------------------------------------------------
 *  $Log: mbgdevio.c $
 *  Revision 1.42  2018/11/22 14:21:19  martin
 *  Use new preprocessor symbol MBG_TGT_USE_IOCTL instead of
 *  obsolete MBG_USE_KERNEL_DRIVER.
 *  Revision 1.41  2018/09/21 08:57:32  martin
 *  Updated some comments.
 *  Revision 1.40  2018/07/05 08:46:20Z  martin
 *  Fixed function mbg_open_device_by_name() which failed
 *  with short device names.
 *  Fixed function mbg_chk_dev_is_lwr().
 *  Open all device nodes with FILE_FLAG_OVERLAPPED under Windows.
 *  mbg_dev_fn_from_dev_idx() returns a generic device name
 *  instead of the hardware ID string under Windows.
 *  Added missing linkage attribute for mbg_open_device().
 *  Added function mbg_split_dev_name().
 *  Added function mbg_chk_dev_has_dac_ctrl().
 *  Also accept '?' in S/N of uninitialized devices.
 *  Refactored implementation of deprecated feature check functions.
 *  Updated naming for device feature stuff.
 *  Removed obsolete size_t to int conversion code.
 *  Account for changes in mbgmutex.h.
 *  Removed usage of obsolete symbol MBGDEVIO_SIMPLE.
 *  Moved checking of the receiver info to an extra function.
 *  Updated and added some comments.
 *  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.
 *  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
 *  Support GNSS API.
 *  Support mbg_open_device_by_name() on Unix.
 *  Updated doxygen comments.
 *  Revision 1.36  2012/10/02 18:37:09Z  martin
 *  There are some g++ versions which fail to compile source code using
 *  the macros provided by Linux to define IOCTL codes. If only the API
 *  functions are called by an application then the IOCTL codes aren't
 *  required anyway, so we just avoid inclusion of mbgioctl.h in
 *  general and but include it when this module is built.
 *  Updated doxygen comments.
 *  New functions mbg_get_all_irig_rx_info() and
 *  mbg_save_all_irig_rx_settings().
 *  Account for renamed macros.
 *  Support on-board event logs.
 *  New functions mbg_dev_has_debug_status() and
 *  mbg_get_debug_status().
 *  Added a workaround to make mbgmon (BC) build under Windows.
 *  In mbg_get_serial_settings() return an error if the number of provided
 *  serial ports or supported string types exceeds the numbers supported
 *  by the driver.
 *  Moved mbg_get_serial_settings() and mbg_save_serial_settings()
 *  to an extra file. These functions expect parameters the sizes of
 *  which might change in future API versions, which would make
 *  functions exported by shared libraries incompatible across versions.
 *  Made functions mbg_get_gps_all_port_info() and
 *  mbg_get_gps_all_str_type_info() non-static so they are now exported
 *  by the shared libraries built from this module.
 *  Include cfg_hlp.h.
 *  Conditionally use older IOCTL request buffer structures.
 *  Moved some macros etc. to the .h file.
 *  Modified generic IOCTL handling such that for calls requiring variable sizes
 *  a fixed request block containing input and output buffer pointers and sizes is
 *  passed down to the kernel driver. This simplifies implementation under *BSD
 *  and also works for other target systems.
 *  Support reading CORR_INFO, and reading/writing TR_DISTANCE.
 *  Added mbg_dev_has_pzf() function.
 *  Support PTP unicast configuration.
 *  Account for some IOCTL codes renamed to follow common naming conventions.
 *  Renamed mutex stuff to critical sections.
 *  Added API calls to support PTP unicast.
 *  Specify I/O range number when calling port I/O macros
 *  so they can be used for different ranges under BSD.
 *  Modifications to support FreeBSD.
 *  Moved definition of MBG_HW_NAME to the header file.
 *  Compute PC cycles frequency under Linux if cpu_tick is not set by the kernel.
 *  Fixed a bug that kept the function mbg_open_device_by_name in a loop under certain conditions.
 *  Made xhrt leap second check an inline function.
 *  Revision 1.35  2010/01/12 13:40:25  martin
 *  Fixed a typo in mbg_dev_has_raw_irig_data().
 *  Revision 1.34  2009/12/15 15:34:58Z  daniel
 *  Support reading the raw IRIG data bits for firmware versions
 *  which support this feature.
 *  Revision 1.33  2009/09/29 15:08:40Z  martin
 *  Support retrieving time discipline info.
 *  Revision 1.32  2009/08/17 13:46:29  martin
 *  Moved specific definition of symbol _HAVE_IOCTL_WITH_SIZE
 *  to mbgioctl.h and renamed it to _MBG_SUPP_VAR_ACC_SIZE.
 *  Revision 1.31  2009/08/12 14:28:26  daniel
 *  Included PTP functions in build.
 *  Revision 1.30  2009/06/19 12:19:41Z  martin
 *  Support reading raw IRIG time.
 *  Revision 1.29  2009/06/08 18:23:22  daniel
 *  Added PTP configuration functions and PTP state functions, but
 *  they are still excluded from build.
 *  Added calls to support simple LAN interface configuration.
 *  Revision 1.28  2009/03/19 15:30:04  martin
 *  Added support for configurable time scales.
 *  Support reading/writing GPS UTC parameters.
 *  Support reading IRIG control function bits.
 *  Support reading MM timestamps without cycles.
 *  Fixed endianess correction in mbg_get_gps_pos().
 *  Endianess correction for ASIC version and ASIC features
 *  is now done by the kernel driver.
 *  Use generic cycles types and functions in mbg_get_default_cycles_frequency().
 *  mbg_tgt.h is now included in mbgdevio.h.
 *  Account for renamed IOCTL codes.
 *  Revision 1.27  2008/12/17 10:37:37  martin
 *  Fixed a bug in mbg_open_device_by_name() with sel. mode MBG_MATCH_ANY.
 *  Support variable read buffer sizes under Linux, so
 *  mbg_get_all_port_info() and mbg_get_all_str_type_info()
 *  can now be used under Linux.
 *  Support PC cycles under Linux via inline rdtsc call.
 *  Use predefined constants to convert fractions.
 *  New API calls mbg_get_fast_hr_timestamp_cycles(), and
 *  mbg_get_fast_hr_timestamp_comp() which take memory mapped HR time stamps
 *  in kernel space, and mbg_dev_has_fast_hr_timestamp() to check whether
 *  this is supported by a device.
 *  Removed mm_*() functions since these are obsolete now.
 *  Support extrapolated HR time (xhrt) for Windows and Linux
 *  by providing a function mbg_xhrt_poll_thread_create() which
 *  starts a poll thread for a specific device which to read
 *  HR time plus associated cycles in regular intervals.
 *  Added functions mbg_get_process_affinity(), mbg_set_process_affinity(),
 *  and mbg_set_current_process_affinity_to_cpu(), and mbg_create_thread()
 *  and mbg_set_thread_affinity() to control the extrapolation feature.
 *  Use new preprocessor symbol MBGDEVIO_HAVE_THREAD_AFFINITY.
 *  Added new functions mbg_get_xhrt_time_as_pcps_hr_time() and
 *  mbg_get_xhrt_time_as_filetime() (Windows only) to retrieve
 *  fast extrapolated timestamps.
 *  Added function mbg_get_xhrt_cycles_frequency() to retrieve the
 *  cycles counter frequency computed by the polling thread.
 *  Added function mbg_get_default_cycles_frequency_from_dev(),
 *  and mbg_get_default_cycles_frequency() (Windows only).
 *  Moved mbg_open_device..() functions upwards.
 *  Made device_info_list common.
 *  New functions mbg_dev_is_msf(), mbg_dev_is_wwvb(), mbg_dev_is_lwr(),
 *  mbg_dev_has_asic_version(), mbg_dev_has_asic_features(),
 *  and mbg_get_irq_stat_info().
 *  Exclude 2 more functions from build if symbol MBGDEVIO_SIMPLE is not 0.
 *  Account for MBG_VIRT_ADDR having beenrenamed to MBG_MEM_ADDR.
 *  Account Linux for device names renamed from /dev/mbgclk to /dev/mbgclock.
 *  Support bigendian target platforms.
 *  Revision 1.26  2008/02/26 16:54:21  martin
 *  New/changed functions for memory mapped access which are
 *  currently excluded from build.
 *  Changed separator for device names from ' ' to '_'.
 *  Added new type MBG_HW_NAME.
 *  Comment cleanup for doxygen.
 *  Revision 1.25  2008/02/04 13:42:45Z  martin
 *  Account for preprocessor symbol MBG_TGT_SUPP_MMAP.
 *  Revision 1.24  2008/01/31 08:31:40Z  martin
 *  Picked up changes from 1.19.1.2:
 *  Under DOS detect and disable any TSR while searching for devices.
 *  Exclude some complex configuration API calls from build
 *  If MBGDEVIO_SIMPLE is defined != 0.
 *  Revision 1.23  2008/01/30 10:32:35Z  daniel
 *  Renamed mapped memory funtions.
 *  Revision 1.22  2008/01/25 15:27:42Z  daniel
 *  Fixed a bug in mbg_get_hr_time_comp() where an overflow
 *  of the fractions was handled with wrong sign.
 *  Revision 1.21  2008/01/17 15:49:59Z  daniel
 *  Added functions mbg_find_devices_with_hw_id() and
 *  mbg_free_devics_list() to work with Linux Win32 OSs.
 *  Added Doxygen compliant comments for API functions.
 *  Support for mapped memory I/O under linux and windows.
 *  Added functions mbg_get_mapped_memory_info(),
 *  mbg_unmap_mapped_memory() and
 *  mbg_get_hr_timestamp_memory_mapped().
 *  Account for PCI_ASIC_FEATURES.
 *  Cleanup for PCI ASIC version.
 *  Revision 1.20  2007/09/27 07:31:12  daniel
 *  Moved declaration of portable inline specifier to mbg_tgt.h.
 *  Support hotplugging of devices as used with USB by Daniel's new
 *  functions mbg_find_devices_with_names(), mbg_free_device_name_list(),
 *  mbg_open_device_by_hw_id(), and mbg_open_device_by_name().
 *  In mbg_get_serial_settings() account for devices which have no
 *  serial port at all.
 *  Register event source if Windows DLL is loaded.
 *  Revision 1.19  2007/05/21 15:00:00Z  martin
 *  Unified naming convention for symbols related to ref_offs.
 *  Revision 1.18  2007/03/02 10:17:41Z  martin
 *  Use generic port I/O macros.
 *  Changes due to modified/renamed macros.
 *  Changes due to renamed library symbols.
 *  Preliminary support for *BSD.
 *  Revision 1.17  2006/05/02 13:15:37  martin
 *  Added mbg_set_gps_port_settings(), mbg_get_gps_all_pout_info(),
 *  mbg_set_gps_pout_settings_idx(), mbg_set_gps_pout_settings().
 *  Revision 1.16  2005/06/02 11:53:12Z  martin
 *  Implemented existing mbg_generic_..() functions.
 *  Added new functions mbg_generic_io() and mbg_dev_has_generic_io().
 *  Added new function mbg_get_synth_state().
 *  Partially use inline function.
 *  Changed order of some functions.
 *  More simplifications using macros.
 *  Unified macros for Win32 and Linux.
 *  Fixed warning under Win32 using type cast.
 *  Revision 1.15  2005/01/31 16:44:21Z  martin
 *  Added function mbg_get_hr_time_comp() which returns HR time stamp
 *  which has latency compensated.
 *  Revision 1.14  2005/01/14 10:22:23Z  martin
 *  Added functions which query device features.
 *  Revision 1.13  2004/12/09 11:23:59Z  martin
 *  Support configuration of on-board frequency synthesizer.
 *  Revision 1.12  2004/11/09 14:11:07Z  martin
 *  Modifications were required in order to be able to configure IRIG
 *  settings of cards which provide both IRIG input and output.
 *  Renamed functions mbg_get_irig_info() and mbg_set_irig_settings()
 *  to mbg_get_irig_rx_info() and mbg_set_irig_rx_settings()
 *  New functions mbg_get_irig_tx_info() and mbg_set_irig_tx_settings().
 *  All API functions now use well defined parameter types instead of
 *  generic types. Some new types have been defined therefore.
 *  Added a workaround for GPS169PCI cards with early firmware versions
 *  which used the same codes to configure the IRIG output as the TCR
 *  cards use to configure the IRIG input. Those codes are now
 *  exclusively used to configure the IRIG input. The workaround
 *  has been included in order to let GPS169PCI cards work properly
 *  after a driver update, without requiring a firmware update.
 *  The macro _pcps_ddev_requires_irig_workaround() is used to check
 *  if the workaround is required.
 *  Renamed function mbg_get_gps_stat() to mbg_get_gps_bvar_stat().
 *  Revision 1.11  2004/08/17 11:13:45Z  martin
 *  Account for renamed symbols.
 *  Revision 1.10  2004/04/14 09:39:17Z  martin
 *  Allow [g|s]et_irig_info() also for new devices with IRIG output.
 *  Use MBGDEVIO_COMPAT_VERSION to check version.
 *  Revision 1.9  2003/12/22 15:30:52Z  martin
 *  Added functions mbg_get_asic_version(), mbg_get_time_cycles(),
 *  and mbg_get_hr_time_cycles().
 *  Support higher baud rates for TCR510PCI and PCI510.
 *  Support PCPS_HR_TIME for TCR510PCI.
 *  API calls return ioctl results instead of success/-1.
 *  Moved some Win32 specific code to mbgsvctl DLL.
 *  Log Win32 ioctl errors to event log for debugging.
 *  Revision 1.8  2003/06/19 08:42:33Z  martin
 *  Renamed function mbg_clr_cap_buff() to mbg_clr_ucap_buff().
 *  New functions mbg_get_ucap_entries() and mbg_get_ucap_event().
 *  New function mbg_get_hr_ucap().
 *  New functions mbgdevio_get_version() and mbgdevio_check_version().
 *  New functions for generic read/write access.
 *  New functions mbg_get_pcps_tzdl() and mbg_set_pcps_tzdl().
 *  Fixed a bug passing the wrong command code to a
 *  direct access target in mbg_get_sync_time().
 *  Return driver info for direct access targets.
 *  Include pcpsdrvr.h and pcps_dos.h, if applicable.
 *  For direct access targets, check if a function is supported
 *  before accessing the hardware.
 *  Use const parameter pointers if applicable.
 *  Changes due to renamed symbols/macros.
 *  Source code cleanup.
 *  Revision 1.7  2003/05/16 08:52:46  MARTIN
 *  Swap doubles inside API functions.
 *  Enhanced support for direct access targets.
 *  Removed obsolete code.
 *  Revision 1.6  2003/04/25 10:14:16  martin
 *  Renamed macros.
 *  Extended macro calls for direct access targets.
 *  Updated macros for Linux.
 *  Revision 1.5  2003/04/15 19:35:25Z  martin
 *  New functions mbg_setup_receiver_info(),
 *  mbg_get_serial_settings(), mbg_save_serial_settings().
 *  Revision 1.4  2003/04/09 16:07:16Z  martin
 *  New API functions mostly complete.
 *  Use renamed IOCTL codes from mbgioctl.h.
 *  Added DllEntry function for Win32.
 *  Made MBG_Device_count and MBG_Device_Path local.
 *  Revision 1.3  2003/01/24 13:44:40Z  martin
 *  Fixed get_ref_time_from_driver_at_sec_change() to be used
 *  with old kernel drivers.
 *  Revision 1.2  2002/09/06 11:04:01Z  martin
 *  Some old API functions have been replaced by new ones
 *  for a common PnP/non-PnP API.
 *  New API function which clears capture buffer.
 *  New function get_ref_time_from_driver_at_sec_change().
 *  Revision 1.1  2002/02/19 13:48:20Z  MARTIN
 *  Initial revision
 *
 **************************************************************************/

#define _MBGDEVIO
 #include <mbgdevio.h>
#undef _MBGDEVIO

#include <mbgutil.h>
#include <gpsutils.h>
#include <mbgerror.h>
#include <cfg_hlp.h>
#include <str_util.h>

#if defined( MBG_TGT_DOS_PM )
  #include <mbg_dpmi.h>
#endif


#if !MBG_TGT_USE_IOCTL

  #include <pcpsdrvr.h>
  #include <pci_asic.h>

  static PCPS_DRVR_INFO drvr_info = { MBGDEVIO_VERSION, 0, "MBGDEVIO direct" };

#endif


// target specific code for different environments

#if defined( MBG_TGT_WIN32 )

  #include <mbgsvctl.h>
  #include <mbgnames.h>
  #include <pci_asic.h>
  #include <mbgutil.h>
  #include <timecnv.h>
  #include <pcpsutil.h>

  #include <tchar.h>
  #include <stdio.h>

#elif defined( MBG_TGT_POSIX ) && !defined( MBG_TGT_QNX_NTO )

  #include <unistd.h>
  #include <stdlib.h>
  #include <string.h>

  #if defined( DEBUG )
    #include <stdio.h>       // printf() debug output
  #endif

#else // other target OSs which access the hardware directly

  #if defined( MBG_TGT_QNX_NTO )
    #include <stdio.h>
    #include <sys/neutrino.h>
  #endif

  #if MBG_USE_DOS_TSR
    #include <pcps_dos.h>
  #else
    #define pcps_read_safe            _pcps_read
    #define pcps_write_safe           pcps_write
    #define pcps_read_gps_safe        pcps_read_gps
    #define pcps_write_gps_safe       pcps_write_gps

    #define _pcps_write_byte_safe     _pcps_write_byte
    #define _pcps_read_var_safe       _pcps_read_var
    #define _pcps_write_var_safe      _pcps_write_var
    #define _pcps_read_gps_var_safe   _pcps_read_gps_var
    #define _pcps_write_gps_var_safe  _pcps_write_gps_var
  #endif

#endif  // end of target specific code


#if !defined( _MBG_SUPP_VAR_ACC_SIZE )
  // If this symbol has not yet been defined then mbgioctl.h has probably
  // not yet been included. On target systems where the hardware is accessed
  // directly without a kernel driver variable buffer sizes are supported,
  // so we set the default to 1.
  #define _MBG_SUPP_VAR_ACC_SIZE   1
#endif


#if !defined( _mbgdevio_chk_cond )
  // If the macro has not been defined previously then
  // it may not be required for the target environment and
  // is defined as empty string.
  #define _mbgdevio_chk_cond( _cond ) _nop_macro_fnc()
#endif



#define _mbgdevio_read_chk( _dh, _cmd, _ioctl, _p, _sz, _cond ) \
do                                                              \
{                                                               \
  _mbgdevio_chk_cond( _cond );                                  \
  rc = _do_mbgdevio_read( _dh, _cmd, _ioctl, _p, _sz );         \
} while ( 0 )

#define _mbgdevio_read_var_chk( _dh, _cmd, _ioctl, _p, _cond ) \
do                                                             \
{                                                              \
  _mbgdevio_chk_cond( _cond );                                 \
  rc = _mbgdevio_read_var( _dh, _cmd, _ioctl, _p );            \
} while ( 0 )

#define _mbgdevio_write_var_chk( _dh, _cmd, _ioctl, _p, _cond ) \
do                                                              \
{                                                               \
  _mbgdevio_chk_cond( _cond );                                  \
  rc = _mbgdevio_write_var( _dh, _cmd, _ioctl, _p );            \
} while ( 0 )

#define _mbgdevio_write_cmd_chk( _dh, _cmd, _ioctl, _cond ) \
do                                                          \
{                                                           \
  _mbgdevio_chk_cond( _cond );                              \
  rc = _mbgdevio_write_cmd( _dh, _cmd, _ioctl );            \
} while ( 0 )

#define _mbgdevio_read_gps_chk( _dh, _cmd, _ioctl, _p, _sz, _cond ) \
do                                                                  \
{                                                                   \
  _mbgdevio_chk_cond( _cond );                                      \
  rc = _do_mbgdevio_read_gps( _dh, _cmd, _ioctl, _p, _sz );         \
} while ( 0 )

#define _mbgdevio_read_gps_var_chk( _dh, _cmd, _ioctl, _p, _cond ) \
do                                                                 \
{                                                                  \
  _mbgdevio_chk_cond( _cond );                                     \
  rc = _mbgdevio_read_gps_var( _dh, _cmd, _ioctl, _p );            \
} while ( 0 )

#define _mbgdevio_write_gps_var_chk( _dh, _cmd, _ioctl, _p, _cond ) \
do                                                                  \
{                                                                   \
  _mbgdevio_chk_cond( _cond );                                      \
  rc = _mbgdevio_write_gps_var( _dh, _cmd, _ioctl, _p );            \
} while ( 0 )



static /*HDR*/
int do_chk_dev_feat( MBG_DEV_HANDLE dh, uint32_t feat_type, uint32_t feat_num )
{
  #if defined( _MBGIOCTL_H )
  {
    // This target uses a kernel driver, so we send an IOCTL
    // to the kernel driver to retrieve the information.
    MBGDEVIO_RET_VAL rc;
    IOCTL_DEV_FEAT_REQ req;
    req.feat_type = feat_type;
    req.feat_num = feat_num;
    rc = _do_mbg_ioctl( dh, IOCTL_CHK_DEV_FEAT,
                        &req, sizeof( req ), 0 );
#if 0 && DEBUG
    {
      int rc2 = _mbgdevio_cnv_ret_val( rc );
      printf( "feat ioctl %lu:%lu ret: %i --> %i\n",
              (ulong) feat_type, (ulong) feat_num, rc, rc2 );
      return rc2;
    }
#else
    return _mbgdevio_cnv_ret_val( rc );
#endif
  }
  #else
    // This target doesn't use a kernel driver, so we directly call
    // the function that would be called by the kernel driver.
    return pcps_chk_dev_feat( dh, feat_type, feat_num );
  #endif

}  // do_chk_dev_feat



int do_chk_dev_feat_deprecated( MBG_DEV_HANDLE dh, MBG_CHK_SUPP_FNC *fnc, int *p )
{
  // Call the current feature check function.
  int rc = fnc( dh );
  int is_success = mbg_rc_is_success( rc );

  if ( is_success                         // definitely supported
  || ( rc == MBG_ERR_NOT_SUPP_BY_DEV ) )  // definitely NOT supported
  {
    // We could definitely determine if the requested feature
    // is supported or not, so we accordingly update the integer
    // variable the address of which has been passed by the caller,
    // and return MBG_SUCCESS since the information could be
    // retrieved successfully.
    *p = is_success;
    return MBG_SUCCESS;
  }

  // If execution goes here then there was some error trying
  // to determine the requested information, e.g. an IOCTL error
  // when accessing the kernel driver, so we return the associated
  // error code.
  return rc;

}  // do_chk_dev_feat_deprecated



#if defined( _MBGIOCTL_H )

static /*HDR*/
int do_query_cond( MBG_DEV_HANDLE dh, unsigned int ioctl_code )
{
    MBGDEVIO_RET_VAL rc;
    int flag = 0;
    rc = _mbgdevio_read_var( dh, -1, ioctl_code, &flag );

    if ( mbg_rc_is_success( rc ) )     // no IOCTL error
      if ( flag == 0 )                 // if returned value is 0
        rc = MBG_ERR_NOT_SUPP_BY_DEV;  // not supp.

    // success or IOCTL error
    return _mbgdevio_cnv_ret_val( rc );

}  // do_query_cond

#define _do_query_cond( _dh, _cond, _ioctl )  \
  do_query_cond( _dh, _ioctl )

#else

#define _do_query_cond( _dh, _cond, _ioctl )  \
  _cond( _dh ) ? MBG_SUCCESS : MBG_ERR_NOT_SUPP_BY_DEV

#endif


static MBG_PC_CYCLES_FREQUENCY pc_cycles_frequency;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbgdevio_get_version( void )
{
  return MBGDEVIO_VERSION;

}  // mbgdevio_get_version



/*HDR*/
_MBG_API_ATTR int _MBG_API mbgdevio_check_version( int header_version )
{
  if ( header_version >= MBGDEVIO_COMPAT_VERSION )
    return MBG_SUCCESS;

  return MBG_ERR_LIB_NOT_COMPATIBLE;

}  // mbgdevio_check_version



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_receiver_info( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_RECEIVER_INFO );

}  // mbg_chk_dev_has_receiver_info

MBG_CHK_SUPP_FNC mbg_chk_dev_has_receiver_info;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_gps_data( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_GPS_DATA_16 );

}  // mbg_chk_dev_has_gps_data

MBG_CHK_SUPP_FNC mbg_chk_dev_has_gps_data;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_generic_io( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_GENERIC_IO );

}  // mbg_chk_dev_has_generic_io

MBG_CHK_SUPP_FNC mbg_chk_dev_has_generic_io;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_asic_version( MBG_DEV_HANDLE dh )
{
  // TODO return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, ... );
  return _do_query_cond( dh, _pcps_ddev_has_asic_version, IOCTL_DEV_HAS_PCI_ASIC_VERSION );

}  // mbg_chk_dev_has_asic_version

MBG_CHK_SUPP_FNC mbg_chk_dev_has_asic_version;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_asic_features( MBG_DEV_HANDLE dh )
{
  // TODO return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, ... );
  return _do_query_cond( dh, _pcps_ddev_has_asic_features, IOCTL_DEV_HAS_PCI_ASIC_FEATURES );

}  // mbg_chk_dev_has_asic_features

MBG_CHK_SUPP_FNC mbg_chk_dev_has_asic_features;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_xmr( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_RI, GPS_HAS_XMULTI_REF );

}  // mbg_chk_dev_has_xmr

MBG_CHK_SUPP_FNC mbg_chk_dev_has_xmr;



static /*HDR*/
int chk_bus_flags( MBG_DEV_HANDLE dh, int bus_flag_mask )
{
  PCPS_DEV dev_info;

  int rc = mbg_get_device_info( dh, &dev_info );

  if ( mbg_rc_is_error( rc ) )
    return rc;

  return ( dev_info.type.bus_flags & bus_flag_mask ) ? MBG_SUCCESS : MBG_ERR_NOT_SUPP_BY_DEV;

}  // chk_bus_flags



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_isa( MBG_DEV_HANDLE dh )
{
  return chk_bus_flags( dh, PCPS_BUS_ISA );

}  // mbg_chk_dev_is_isa

MBG_CHK_SUPP_FNC mbg_chk_dev_is_isa;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_mca( MBG_DEV_HANDLE dh )
{
  return chk_bus_flags( dh, PCPS_BUS_MCA );

}  // mbg_chk_dev_is_mca

MBG_CHK_SUPP_FNC mbg_chk_dev_is_mca;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_pci( MBG_DEV_HANDLE dh )
{
  return chk_bus_flags( dh, PCPS_BUS_PCI );

}  // mbg_chk_dev_is_pci

MBG_CHK_SUPP_FNC mbg_chk_dev_is_pci;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_pci_express( MBG_DEV_HANDLE dh )
{
  PCPS_DEV dev_info;

  int rc = mbg_get_device_info( dh, &dev_info );

  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;

  return MBG_ERR_NOT_SUPP_BY_DEV;

}  // mbg_chk_dev_is_pci_express

MBG_CHK_SUPP_FNC mbg_chk_dev_is_pci_express;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_usb( MBG_DEV_HANDLE dh )
{
  return chk_bus_flags( dh, PCPS_BUS_USB );

}  // mbg_chk_dev_is_usb

MBG_CHK_SUPP_FNC mbg_chk_dev_is_usb;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_gnss( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_IS_GNSS );

}  // mbg_chk_dev_is_gnss

MBG_CHK_SUPP_FNC mbg_chk_dev_is_gnss;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_gps( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_REF_TYPE, PCPS_REF_GPS );

}  // mbg_chk_dev_is_gps

MBG_CHK_SUPP_FNC mbg_chk_dev_is_gps;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_dcf( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_REF_TYPE, PCPS_REF_DCF );

}  // mbg_chk_dev_is_dcf

MBG_CHK_SUPP_FNC mbg_chk_dev_is_dcf;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_pzf( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_PZF );

}  // mbg_chk_dev_has_pzf

MBG_CHK_SUPP_FNC mbg_chk_dev_has_pzf;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_msf( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_REF_TYPE, PCPS_REF_MSF );

}  // mbg_chk_dev_is_msf

MBG_CHK_SUPP_FNC mbg_chk_dev_is_msf;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_wwvb( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_REF_TYPE, PCPS_REF_WWVB );

}  // _pcps_ddev_is_wwvb

MBG_CHK_SUPP_FNC _pcps_ddev_is_wwvb;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_jjy( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_REF_TYPE, PCPS_REF_JJY );

}  // _pcps_ddev_is_jjy

MBG_CHK_SUPP_FNC _pcps_ddev_is_jjy;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_lwr( MBG_DEV_HANDLE dh )
{
  int rc = mbg_chk_dev_is_dcf( dh );

  if ( mbg_rc_is_success( rc ) )
    goto out;

  rc = mbg_chk_dev_is_msf( dh );

  if ( mbg_rc_is_success( rc ) )
    goto out;

  rc = mbg_chk_dev_is_wwvb( dh );

  if ( mbg_rc_is_success( rc ) )
    goto out;

  rc = mbg_chk_dev_is_jjy( dh );

  if ( mbg_rc_is_success( rc ) )
    goto out;

out:
  return rc;

}  // mbg_chk_dev_is_lwr

MBG_CHK_SUPP_FNC mbg_chk_dev_is_lwr;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_is_tcr( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_REF_TYPE, PCPS_REF_IRIG );

}  // mbg_chk_dev_is_tcr

MBG_CHK_SUPP_FNC mbg_chk_dev_is_tcr;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_lan_intf( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_LAN_INTF );

}  // mbg_chk_dev_has_lan_intf

MBG_CHK_SUPP_FNC mbg_chk_dev_has_lan_intf;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ptp( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_PTP );

}  // mbg_chk_dev_has_ptp

MBG_CHK_SUPP_FNC mbg_chk_dev_has_ptp;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ptp_unicast( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_RI, GPS_HAS_PTP_UNICAST );

}  // mbg_chk_dev_has_ptp_unicast

MBG_CHK_SUPP_FNC mbg_chk_dev_has_ptp_unicast;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_hr_time( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_HR_TIME );

}  // mbg_chk_dev_has_hr_time

MBG_CHK_SUPP_FNC mbg_chk_dev_has_hr_time;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_fast_hr_timestamp( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_FAST_HR_TSTAMP );

}  // mbg_chk_dev_has_fast_hr_timestamp

MBG_CHK_SUPP_FNC mbg_chk_dev_has_fast_hr_timestamp;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_time_scale( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_TIME_SCALE );

}  // mbg_chk_dev_has_time_scale

MBG_CHK_SUPP_FNC mbg_chk_dev_has_time_scale;



/*HDR*/
/* (Intentionally excluded from Doxygen)
 * @brief Check if a device supports setting an event time
 *
 * This feature is only supported by some special custom firmware
 * to preset a %UTC time at which the clock is to generate an output signal.
 *
 * @note This function should be preferred over ::mbg_dev_has_event_time,
 * which has been deprecated.
 *
 * @param[in]  dh  Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
 *
 * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV
 *         if not supported, or one of the other @ref MBG_ERROR_CODES
 *
 * @ingroup mbgdevio_chk_supp_fncs
 * @see ::mbg_set_event_time
 */
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_event_time( MBG_DEV_HANDLE dh )
{
  return _do_query_cond( dh, _pcps_ddev_has_event_time, IOCTL_DEV_HAS_EVENT_TIME );

}  // mbg_chk_dev_has_event_time

MBG_CHK_SUPP_FNC mbg_chk_dev_has_event_time;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ucap( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_UCAP );

}  // mbg_chk_dev_has_ucap

MBG_CHK_SUPP_FNC mbg_chk_dev_has_ucap;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_can_clr_ucap_buff( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_CAN_CLR_UCAP_BUFF );

}  // mbg_chk_dev_can_clr_ucap_buff

MBG_CHK_SUPP_FNC mbg_chk_dev_can_clr_ucap_buff;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tzdl( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_TZDL );

}  // mbg_chk_dev_has_tzdl

MBG_CHK_SUPP_FNC mbg_chk_dev_has_tzdl;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_pcps_tzdl( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_PCPS_TZDL );

}  // mbg_chk_dev_has_pcps_tzdl

MBG_CHK_SUPP_FNC mbg_chk_dev_has_pcps_tzdl;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tzcode( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_TZCODE );

}  // mbg_chk_dev_has_tzcode

MBG_CHK_SUPP_FNC mbg_chk_dev_has_tzcode;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tz( MBG_DEV_HANDLE dh )
{
  return _do_query_cond( dh, _pcps_ddev_has_tz, IOCTL_DEV_HAS_TZ );

}  // mbg_chk_dev_has_tz

MBG_CHK_SUPP_FNC mbg_chk_dev_has_tz;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig( MBG_DEV_HANDLE dh )
{
  return _do_query_cond( dh, _pcps_ddev_has_irig, IOCTL_DEV_HAS_IRIG );

}  // mbg_chk_dev_has_irig

MBG_CHK_SUPP_FNC mbg_chk_dev_has_irig;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_tx( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_IRIG_TX );

}  // mbg_chk_dev_has_irig_tx

MBG_CHK_SUPP_FNC mbg_chk_dev_has_irig_tx;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_IRIG_CTRL_BITS );

}  // mbg_chk_dev_has_irig_ctrl_bits

MBG_CHK_SUPP_FNC mbg_chk_dev_has_irig_ctrl_bits;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_raw_irig_data( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_RAW_IRIG_DATA );

}  // mbg_chk_dev_has_raw_irig_data

MBG_CHK_SUPP_FNC mbg_chk_dev_has_raw_irig_data;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_time( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_IRIG_TIME );

}  // mbg_chk_dev_has_irig_time

MBG_CHK_SUPP_FNC mbg_chk_dev_has_irig_time;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_signal( MBG_DEV_HANDLE dh )
{
  return _do_query_cond( dh, _pcps_ddev_has_signal, IOCTL_DEV_HAS_SIGNAL );

}  // mbg_chk_dev_has_signal

MBG_CHK_SUPP_FNC mbg_chk_dev_has_signal;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_mod( MBG_DEV_HANDLE dh )
{
  return _do_query_cond( dh, _pcps_ddev_has_mod, IOCTL_DEV_HAS_MOD );

}  // mbg_chk_dev_has_mod

MBG_CHK_SUPP_FNC mbg_chk_dev_has_mod;



/*HDR*/
/* (Intentionally excluded from Doxygen)
 * @brief Check if a device supports higher baud rates than usual
 *
 * Check if a device provides a serial output that supports
 * higher baud rates than older cards, i.e. ::DEFAULT_BAUD_RATES_DCF_HS
 * rather than ::DEFAULT_BAUD_RATES_DCF.
 *
 * The call ::mbg_get_serial_settings takes care of this, so applications
 * which use that call as suggested don't need to use this call directly.
 *
 * @note This function should be preferred over ::mbg_dev_has_serial_hs,
 * which has been deprecated.
 *
 * @param[in]  dh  Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
 *
 * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV
 *         if not supported, or one of the other @ref MBG_ERROR_CODES
 *
 * @ingroup mbgdevio_chk_supp_fncs
 * @see ::mbg_get_serial_settings
 */
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_serial_hs( MBG_DEV_HANDLE dh )
{
  return _do_query_cond( dh, _pcps_ddev_has_serial_hs, IOCTL_DEV_HAS_SERIAL_HS );

}  // mbg_chk_dev_has_serial_hs

MBG_CHK_SUPP_FNC mbg_chk_dev_has_serial_hs;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_synth( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_SYNTH );

}  // mbg_chk_dev_has_synth

MBG_CHK_SUPP_FNC mbg_chk_dev_has_synth;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_gpio( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_RI, GPS_HAS_GPIO );

}  // mbg_chk_dev_has_gpio

MBG_CHK_SUPP_FNC mbg_chk_dev_has_gpio;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_cab_len( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_CABLE_LEN );

}  // mbg_chk_dev_has_cab_len

MBG_CHK_SUPP_FNC mbg_chk_dev_has_cab_len;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ref_offs( MBG_DEV_HANDLE dh )
{
  return mbg_chk_dev_is_tcr( dh );  // All TCRs have this

}  // mbg_chk_dev_has_ref_offs

MBG_CHK_SUPP_FNC mbg_chk_dev_has_ref_offs;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_opt_flags( MBG_DEV_HANDLE dh )
{
  return mbg_chk_dev_is_tcr( dh );  // All TCRs have this

}  // mbg_chk_dev_has_opt_flags

MBG_CHK_SUPP_FNC mbg_chk_dev_has_opt_flags;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_utc_parm( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_UTC_PARM );

}  // mbg_chk_dev_has_utc_parm

MBG_CHK_SUPP_FNC mbg_chk_dev_has_utc_parm;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_corr_info( MBG_DEV_HANDLE dh )
{
  return mbg_chk_dev_has_pzf( dh );  // All DCF77 PZF receivers have this

}  // mbg_chk_dev_has_corr_info

MBG_CHK_SUPP_FNC mbg_chk_dev_has_corr_info;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tr_distance( MBG_DEV_HANDLE dh )
{
  return mbg_chk_dev_has_pzf( dh );  // All DCF77 PZF receivers have this

}  // mbg_chk_dev_has_tr_distance

MBG_CHK_SUPP_FNC mbg_chk_dev_has_tr_distance;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_debug_status( MBG_DEV_HANDLE dh )
{
  return mbg_chk_dev_is_tcr( dh );  // All TCRs have this

}  // mbg_chk_dev_has_debug_status

MBG_CHK_SUPP_FNC mbg_chk_dev_has_debug_status;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_evt_log( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_PCPS, PCPS_BIT_HAS_EVT_LOG );

}  // mbg_chk_dev_has_evt_log

MBG_CHK_SUPP_FNC mbg_chk_dev_has_evt_log;



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_chk_dev_has_dac_ctrl( MBG_DEV_HANDLE dh )
{
  return do_chk_dev_feat( dh, DEV_FEAT_TYPE_XFEAT, MBG_XFEATURE_DAC_CTRL_PCI );

}  // mbg_chk_dev_has_dac_ctrl

MBG_CHK_SUPP_FNC mbg_chk_dev_has_dac_ctrl;



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_receiver_info, p );

}  // mbg_dev_has_receiver_info



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_gps_data, p );

}  // mbg_dev_has_gps_data



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_generic_io" ) _MBG_API mbg_dev_has_generic_io( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_generic_io, p );

}  // mbg_dev_has_generic_io



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_asic_version, p );

}  // mbg_dev_has_asic_version



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_asic_features" ) _MBG_API mbg_dev_has_asic_features( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_asic_features, p );

}  // mbg_dev_has_asic_features



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_xmr" ) _MBG_API mbg_dev_has_xmr( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_xmr, p );

}  // mbg_dev_has_xmr



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gnss" ) _MBG_API mbg_dev_is_gnss( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_is_gnss, p );

}  // mbg_dev_is_gnss



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gps" ) _MBG_API mbg_dev_is_gps( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_is_gps, p );

}  // mbg_dev_is_gps



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_dcf" ) _MBG_API mbg_dev_is_dcf( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_is_dcf, p );

}  // mbg_dev_is_dcf



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_pzf" ) _MBG_API mbg_dev_has_pzf( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_pzf, p );

}  // mbg_dev_has_pzf



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_msf" ) _MBG_API mbg_dev_is_msf( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_is_msf, p );

}  // mbg_dev_is_msf



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_wwvb" ) _MBG_API mbg_dev_is_wwvb( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_is_wwvb, p );

}  // mbg_dev_is_wwvb



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_lwr" ) _MBG_API mbg_dev_is_lwr( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_is_lwr, p );

}  // mbg_dev_is_lwr



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_tcr" ) _MBG_API mbg_dev_is_irig_rx( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_is_tcr, p );

}  // mbg_dev_is_irig_rx



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_lan_intf, p );

}  // mbg_dev_has_lan_intf



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ptp" ) _MBG_API mbg_dev_has_ptp( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_ptp, p );

}  // mbg_dev_has_ptp



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_ptp_unicast, p );

}  // mbg_dev_has_ptp_unicast



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_hr_time, p );

}  // mbg_dev_has_hr_time



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_fast_hr_timestamp, p );

}  // mbg_dev_has_fast_hr_timestamp



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_time_scale, p );

}  // mbg_dev_has_time_scale



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_event_time" ) _MBG_API mbg_dev_has_event_time( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_event_time, p );

}  // mbg_dev_has_event_time



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ucap" ) _MBG_API mbg_dev_has_ucap( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_ucap, p );

}  // mbg_dev_has_ucap



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_can_clr_ucap_buff, p );

}  // mbg_dev_can_clr_ucap_buff



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tzdl" ) _MBG_API mbg_dev_has_tzdl( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_tzdl, p );

}  // mbg_dev_has_tzdl



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_pcps_tzdl, p );

}  // mbg_dev_has_pcps_tzdl



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tzcode" ) _MBG_API mbg_dev_has_tzcode( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_tzcode, p );

}  // mbg_dev_has_tzcode



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tz" ) _MBG_API mbg_dev_has_tz( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_tz, p );

}  // mbg_dev_has_tz



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig" ) _MBG_API mbg_dev_has_irig( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_irig, p );

}  // mbg_dev_has_irig



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_irig_tx, p );

}  // mbg_dev_has_irig_tx



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_irig_ctrl_bits, p );

}  // mbg_dev_has_irig_ctrl_bits



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_raw_irig_data, p );

}  // mbg_dev_has_raw_irig_data



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_irig_time, p );

}  // mbg_dev_has_irig_time



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_signal" ) _MBG_API mbg_dev_has_signal( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_signal, p );

}  // mbg_dev_has_signal



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_mod" ) _MBG_API mbg_dev_has_mod( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_mod, p );

}  // mbg_dev_has_mod



/*HDR*/
/* (Intentionally excluded from Doxygen)
 * @brief Check if a device supports higher baud rates than usual
 *
 * Check if a device provides a serial output that supports
 * higher baud rates than older cards, i.e. ::DEFAULT_BAUD_RATES_DCF_HS
 * rather than ::DEFAULT_BAUD_RATES_DCF.
 *
 * @deprecated This function is deprecated, use ::mbg_chk_dev_has_serial_hs preferably.
 *
 * @param[in]  dh  Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
 * @param[out] p   Pointer to an int which is updated if the API call succeeds.
 *                 The flag is set != 0 if the requested feature is supported, else 0.
 *
 * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES
 *
 * @ingroup mbgdevio_chk_supp_fncs_deprecated
 * @see ::mbg_chk_dev_has_serial_hs
 */
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_serial_hs" ) _MBG_API mbg_dev_has_serial_hs( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_serial_hs, p );

}  // mbg_dev_has_serial_hs



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_synth" ) _MBG_API mbg_dev_has_synth( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_synth, p );

}  // mbg_dev_has_synth



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_gpio" ) _MBG_API mbg_dev_has_gpio( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_gpio, p );

}  // mbg_dev_has_gpio



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_cab_len, p );

}  // mbg_dev_has_cab_len



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_ref_offs, p );

}  // mbg_dev_has_ref_offs



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_opt_flags, p );

}  // mbg_dev_has_opt_flags



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_utc_parm, p );

}  // mbg_dev_has_utc_parm



/*HDR*/
_MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_corr_info" ) _MBG_API mbg_dev_has_corr_info( MBG_DEV_HANDLE dh, int *p )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_corr_info, p );

}  // mbg_dev_has_corr_info



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_tr_distance, p );

}  // mbg_dev_has_tr_distance



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_debug_status, p );

}  // mbg_dev_has_debug_status



/*HDR*/
_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 )
{
  return do_chk_dev_feat_deprecated( dh, mbg_chk_dev_has_evt_log, p );

}  // mbg_dev_has_evt_log



static /*HDR*/
int mbg_comp_hr_latency( PCPS_TIME_STAMP *ts,
                         const MBG_PC_CYCLES *p_cyc_ts,
                         const MBG_PC_CYCLES *p_cyc_ontime,
                         const MBG_PC_CYCLES_FREQUENCY *p_cyc_freq,
                         int32_t *hns_latency )
{
  #if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX )

    int64_t cyc_latency;
    int64_t frac_latency;
    int64_t comp_frac;  //uint??

    // Compute latency in cycles counter units
    cyc_latency = mbg_delta_pc_cycles( p_cyc_ts, p_cyc_ontime );

    #if DEBUG && defined( MBG_TGT_LINUX ) && defined( MBG_ARCH_X86 )
      printf( "comp_lat: %08llX.%08llX %llX - %llX = %lli",
              (unsigned long long) ts->sec,
              (unsigned long long) ts->frac,
              (unsigned long long) *p_cyc_ts,
              (unsigned long long) *p_cyc_ontime,
              (unsigned long long) cyc_latency
            );
    #endif

    // Account for cycles counter overflow. If the CPU's TSC is used
    // this is supposed to happen once every 2^^63 units of the
    // cycles counter frequency, i.e. about every 97 years on a system
    // with 3 GHz clock.
    if ( cyc_latency < 0 )
    {
      cyc_latency += ( (uint64_t) -1 ) >> 1;

      #if DEBUG && defined( MBG_TGT_LINUX )
        printf( "->%lli (%llX)",
                (unsigned long long) cyc_latency,
                (unsigned long long) ( ( (uint64_t) -1 ) >> 1 )
              );
      #endif
    }

    // Convert latency to binary fractions of seconds,
    // i.e. units of 2^^-32.
    frac_latency = (*p_cyc_freq) ? ( cyc_latency * ( ( (int64_t) 1 ) << 32 ) / *p_cyc_freq ) : 0;

    // Compute the compensated fractional part of the HR time stamp
    // and account for borrows from the sec field.
    comp_frac = ts->frac - frac_latency;
    ts->frac = (uint32_t) comp_frac;            // yields 32 LSBs
    ts->sec += (uint32_t) ( comp_frac >> 32 );  // yields 32 MSBs

    #if DEBUG && defined( MBG_TGT_LINUX )
      printf( " frac_lat: %llX comp_frac: %08llX.%08llX",
              (unsigned long long) frac_latency,
              (unsigned long long) ts->sec,
              (unsigned long long) ts->frac
            );
    #endif

    if ( hns_latency && *p_cyc_freq )
    {
      int64_t tmp_hns_latency;

      // convert to hectonanoseconds
      tmp_hns_latency = cyc_latency * 10000000 / *p_cyc_freq;

      // check for range overflow
      #define MAX_HNS_LATENCY    0x7FFFFFFF   // int32_t
      #define MIN_HNS_LATENCY    ( -MAX_HNS_LATENCY - 1 )

      if ( tmp_hns_latency > MAX_HNS_LATENCY )
        tmp_hns_latency = MAX_HNS_LATENCY;
      else
        if ( tmp_hns_latency < MIN_HNS_LATENCY )
          tmp_hns_latency = MIN_HNS_LATENCY;

      *hns_latency = (int32_t) tmp_hns_latency;
    }

    #if DEBUG && defined( MBG_TGT_LINUX )
      printf( "\n" );
    #endif

    return MBG_SUCCESS;

  #else

    // This is currently not supported by the target environment.
    return MBG_ERR_NOT_SUPP_ON_OS;

  #endif

}  // mbg_comp_hr_latency



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_dev_fn_from_dev_idx( char *s, int max_len, int dev_idx )
{
  int n = 0;

  #if MBG_TGT_HAS_DEV_FN_BASE
    n = snprintf_safe( s, max_len, mbg_dev_fn_fmt, dev_idx );
  #else
    n = snprintf_safe( s, max_len, "Device #%i", dev_idx );
  #endif

  return n;

}  // mbg_dev_fn_from_dev_idx



/*HDR*/
_MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device( int dev_idx )
{
  if ( dev_idx < 0 )
    goto fail;

  #if defined( MBG_TGT_WIN32 )
  {
    const char *device_path = mbg_svc_get_device_path( dev_idx );

    return mbg_open_device_by_dev_fn( device_path );
  }
  #elif MBG_TGT_HAS_DEV_FN
  {
    MBG_DEV_FN dev_fn;

    mbg_dev_fn_from_dev_idx( dev_fn, sizeof( dev_fn ), dev_idx );

    return mbg_open_device_by_dev_fn( dev_fn );
  }
  #else

    #if defined( _PCPSDRVR_H )
      if ( dev_idx < n_ddevs )
        return &pcps_ddev[dev_idx];
    #endif

    // intentionally fall-through to "fail"
  #endif

fail:
  errno = ENODEV;  // No such device
  return MBG_INVALID_DEV_HANDLE;

} // mbg_open_device



/*HDR*/
_MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_dev_fn( const char *dev_fn )
{
#if defined( MBG_TGT_WIN32 )

  if ( dev_fn == NULL )
  {
    SetLastError( ERROR_INVALID_PARAMETER );  // TODO Is this error code appropriate?
    return MBG_INVALID_DEV_HANDLE;
  }

  return CreateFileA(
         dev_fn,                        // file name
         GENERIC_READ | GENERIC_WRITE,  // access mode
         0,                             // share mode
         NULL,                          // security descriptor
         OPEN_EXISTING,                 // how to create
         // If we don't use FILE_FLAG_OVERLAPPED here then
         // the Windows kernel serializes IOCTL calls (IRPs)
         // from several applications or threads. However,
         // serialization is anyway done by a device mutex
         // the kernel driver anyway, if required, so the
         // Windows kernel doesn't have to care.
         FILE_FLAG_OVERLAPPED,          // file attributes
         NULL                           // handle to template file
       );

#elif defined( MBG_TGT_POSIX ) && !defined( MBG_TGT_QNX_NTO )

  if ( dev_fn == NULL )
  {
    errno = EFAULT;  // Bad address, invalid pointer
    return MBG_INVALID_DEV_HANDLE;
  }

  return open( dev_fn, O_RDWR );

#else

  errno = ( dev_fn == NULL ) ? EFAULT : ENODEV;
  return MBG_INVALID_DEV_HANDLE;

#endif

} // mbg_open_device_by_dev_fn




/*HDR*/
_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*/
_MBG_API_ATTR int _MBG_API mbg_find_devices( void )
{
  #if defined( _PCPSDRVR_H )

    #if defined( MBG_TGT_QNX_NTO )
      // Since this program accessed the hardware directly
      // I/O privileges have to be assigned to the thread.
      if ( ThreadCtl( _NTO_TCTL_IO, NULL ) == -1 )
      {
        fprintf( stderr, "** ThreadCtl() failed to request I/O privileges: %s\n\n", strerror( errno ) );
        exit( 1 );
      }
    #endif

    #if defined( MBG_TGT_DOS ) && MBG_USE_DOS_TSR
    {
      short prv_busy;

      pcps_detect_any_tsr();
      prv_busy = pcps_tsr_set_busy_flag( 1 );
      pcps_detect_devices( pcps_isa_ports, NULL );
      pcps_tsr_set_busy_flag( prv_busy );
    }
    #else
      pcps_detect_devices( pcps_isa_ports, NULL );
    #endif

    return n_ddevs;

  #elif defined( MBG_TGT_WIN32 )

    return mbg_svc_find_devices();

  #elif defined( MBG_TGT_POSIX )

    MBG_DEV_HANDLE dh;
    int i = 0;
    int n = 0;

    while ( i < N_SUPP_DEV_BUS )
    {
      dh = mbg_open_device( i );

      if ( dh != MBG_INVALID_DEV_HANDLE )
      {
        mbg_close_device( &dh );
        n++;
      }

      i++;
    }

    return n;

  #endif

}  // mbg_find_devices



#if MBG_TGT_HAS_DEV_FN

static /*HDR*/
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;

      if ( list->dev_fn_ptr )
      {
        free( list->dev_fn_ptr );
        list->dev_fn_ptr = NULL;
      }

      next = list->next;
      free( list );
      list = next;
    }
  #endif

}  // free_dev_fn_list

#endif  // MBG_TGT_HAS_DEV_FN



#if MBG_TGT_HAS_DEV_FN

static /*HDR*/
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++ )
    {
      MBG_DEV_FN dev_fn;
      MBG_DEV_HANDLE dh;

      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 )
      {
        size_t sz = strlen( dev_fn ) + 1;  // including terminating 0

        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;
        }

        if ( pos == NULL )
          goto out_free;

        pos->dev_fn_ptr = (char *) calloc( 1, sz );

        if ( pos->dev_fn_ptr == NULL )
          goto out_free;

        strncpy_safe( pos->dev_fn_ptr, dev_fn, sz );
        n_dev_fn++;

        mbg_close_device( &dh );
      }
    }

    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

}  // setup_dev_fn_list

#endif  // MBG_TGT_HAS_DEV_FN



#if MBG_TGT_HAS_DEV_FN

static /*HDR*/
int get_dev_info_for_dev_fn( PCPS_DEV *p, const char *dev_fn  )
{
  MBG_DEV_HANDLE dh;
  int rc;

  memset( p, 0, sizeof( *p ) );

  // Try to retrieve device information.
  dh = mbg_open_device_by_dev_fn( dev_fn );

  if ( dh == MBG_INVALID_DEV_HANDLE )
    return mbg_get_last_error( NULL );

  rc = mbg_get_device_info( dh, p );

  mbg_close_device( &dh );

  return rc;

}  // get_dev_info_for_dev_fn

#endif  // MBG_TGT_HAS_DEV_FN



#if MBG_TGT_HAS_DEV_FN

static /*HDR*/
int snprint_dev_name( char *s, size_t max_len, const PCPS_DEV *p_dev )
{
  size_t n = snprintf_safe( s, max_len, MBG_DEV_NAME_FMT,
                            _pcps_type_name( p_dev ), _pcps_sernum( p_dev ) );
  return _int_from_size_t( n );

}  // snprint_dev_name

#endif  // MBG_TGT_HAS_DEV_FN



static /*HDR*/
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++ )
  {
    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.

    return i;  // Matching device found.
  }

  return -1;  // No matching device found.

}  // lookup_dev_idx



static /*HDR*/
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;


  // 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*/
_MBG_API_ATTR int _MBG_API mbg_find_devices_with_names( MBG_DEV_NAME_LIST_ENTRY **p_list,
                                                        int max_devices )
{
#if MBG_TGT_HAS_DEV_FN

  MBG_DEV_FN_LIST_ENTRY *dev_fn_list_head = NULL;
  MBG_DEV_FN_LIST_ENTRY *dev_fn_pos = NULL;

  MBG_DEV_NAME_LIST_ENTRY *list_head = NULL;
  MBG_DEV_NAME_LIST_ENTRY *pos = NULL;

  int n_dev_fn = 0;
  int n_dev_name = 0;

  // 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 );

  // 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 )
  {
    PCPS_DEV dev;
    int rc;

    if ( list_head == NULL )  // first turn
    {
      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;
    }

    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;
    }

    // Get device details for the device.
    rc = get_dev_info_for_dev_fn( &dev, dev_fn_pos->dev_fn_ptr );

    if ( mbg_rc_is_success( rc ) )
      snprint_dev_name( pos->dev_name, sizeof( pos->dev_name ),
                        &dev );

    if ( ++n_dev_name > n_dev_fn )  // This should never happen
      break;
  }

  // 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_dev_name;

#else

  *p_list = NULL;
  return 0;

#endif

}  // mbg_find_devices_with_names



/*HDR*/
_MBG_API_ATTR void _MBG_API mbg_free_device_name_list( MBG_DEV_NAME_LIST_ENTRY *list )
{
  while ( list )
  {
    MBG_DEV_NAME_LIST_ENTRY *next = list->next;

    free( list );
    list = next;
  }

}  // mbg_free_device_name_list



/*HDR*/
_MBG_API_ATTR void _MBG_API mbg_split_dev_name( const MBG_DEV_NAME dev_name,
                                                char *type_name, size_t type_name_size,
                                                char *sernum, size_t sernum_size )
{
  size_t dev_name_len = 0;
  size_t i = 0;
  char c;

  type_name[0] = 0;
  sernum[0] = 0;

  if ( dev_name )
    dev_name_len = strlen( dev_name );

  if ( dev_name_len )
  {
    // clock model name
    const char *cp = dev_name;
    i = 0;

    for (;;)
    {
      c = *cp;

      if ( c == 0 )  // end of string
        break;

      if ( c == '_' )  // separator before S/N, see MBG_DEV_NAME_FMT
        break;

      if ( i == ( type_name_size - 1 ) )
        break;

      type_name[i] = ( c >= 'a' && c <= 'z' ) ? ( c - 0x20 ) : c;

      i++;
      cp++;
    }

    type_name[i] = 0;  // terminate string

    if ( *cp == '_' )
    {
      // Serial number
      cp++;
      i = 0;

      for (;;)
      {
        c = *cp;

        if ( c == 0 )  // end of string
          break;

        if ( i == ( sernum_size - 1 ) )
          break;

        if ( ( c < '0' || c > '9' ) && ( c != '?' ) )  // not a digit
          break;

        sernum[i] = c;

        i++;
        cp++;
      }

      sernum[i] = 0;  // terminate string
    }
  }

}  // mbg_split_dev_name



/*HDR*/
_MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const MBG_DEV_NAME srch_name, int selection_mode )
{
  PCPS_DEV dev_array[N_SUPP_DEV_BUS] = { { { 0 } } };
  PCPS_CLOCK_NAME type_name;
  PCPS_SN_STR sernum;
  size_t i = 0;
  int dev_idx = -1;

  mbg_split_dev_name( srch_name, type_name, sizeof( type_name ),
                      sernum, sizeof( sernum ) );

  #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;

    // 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 );

    if ( n_devices )
    {
      MBG_DEV_FN_LIST_ENTRY *pos;

      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 );

        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++;
        }
      }

      dev_idx = lookup_dev_idx_ex( dev_array, _int_from_size_t( i ), type_name,
                                   sernum, selection_mode );
    }

    free_dev_fn_list( list_head );

    // 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();

      for ( i = 0; i < n_ddevs; i++ )
        dev_array[i] = pcps_ddev[i].dev;

      dev_idx = lookup_dev_idx_ex( dev_array, _int_from_size_t( i ), type_name,
                                   sernum, selection_mode );

      if ( dev_idx >= 0 )
        return mbg_open_device( dev_idx );
    #endif

    errno = ENODEV;
    return MBG_INVALID_DEV_HANDLE;

  #endif

} // mbg_open_device_by_name



/*HDR*/
_MBG_API_ATTR void _MBG_API mbg_close_device( MBG_DEV_HANDLE *dev_handle )
{
  if ( *dev_handle != MBG_INVALID_DEV_HANDLE && *dev_handle != 0 )   //##++++ dev_handle NULL/0 ???
  {
    #if defined( MBG_TGT_WIN32 )
      CloseHandle( *dev_handle );
    #elif defined( MBG_TGT_POSIX ) && !defined( MBG_TGT_QNX_NTO )
      close( *dev_handle );
    #endif
  }

  *dev_handle = MBG_INVALID_DEV_HANDLE;

}  // mbg_close_device



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_drvr_info( MBG_DEV_HANDLE dh, PCPS_DRVR_INFO *p )
{
  #if defined( _MBGIOCTL_H )
    MBGDEVIO_RET_VAL rc;
    rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_PCPS_DRVR_INFO, p );
    return _mbgdevio_cnv_ret_val( rc );
  #else
    (void) dh;   // avoid warning "never used"
    drvr_info.n_devs = n_ddevs;
    *p = drvr_info;
    return MBG_SUCCESS;
  #endif

}  // mbg_get_drvr_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_device_info( MBG_DEV_HANDLE dh, PCPS_DEV *p )
{
  #if defined( _MBGIOCTL_H )
    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_cnv_ret_val( rc );
  #else
    *p = dh->dev;
    return MBG_SUCCESS;
  #endif

}  // mbg_get_device_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_status_port( MBG_DEV_HANDLE dh, PCPS_STATUS_PORT *p )
{
  #if defined( _MBGIOCTL_H )
    MBGDEVIO_RET_VAL rc;
    rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_PCPS_STATUS_PORT, p );
    // No endianess conversion required.
    return _mbgdevio_cnv_ret_val( rc );
  #else
    *p = _pcps_ddev_read_status_port( dh );
    // No endianess conversion required.
    return MBG_SUCCESS;
  #endif

}  // mbg_get_status_port



/*HDR*/
/* (Intentionally excluded from Doxygen)
 * Generic read function which writes a command code to a device
 * and reads a number of replied data to a generic buffer.
 *
 * <b>Warning</b>: This is for debugging purposes only!
 * The specialized API calls should be used preferably.
 * Not all devices support each of the ::PC_GPS_COMMANDS.
 *
 * @param[in]   dh   Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
 * @param[in]   cmd  Can be any @ref PCPS_CMD_CODES "command code" supported by the device
 * @param[out]  p    Pointer to a buffer to be filled up
 * @param[in]   size Size of the output buffer
 *
 * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES
 *
 * @see ::mbg_generic_write
 * @see ::mbg_generic_read_gps
 * @see ::mbg_generic_write_gps
 * @see ::mbg_generic_io
 */
_MBG_API_ATTR int _MBG_API mbg_generic_read( MBG_DEV_HANDLE dh, int cmd,
                                             void *p, int size )
{
  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_cnv_ret_val( rc );

}  // mbg_generic_read



/*HDR*/
/* (Intentionally excluded from Doxygen)
 * Generic read function which writes a GPS command code to a device
 * and reads a number of data bytes back into a generic buffer.
 * The function ::mbg_chk_dev_has_gps_data can be used to check
 * whether this call is supported by a device.
 *
 * <b>Warning</b>: This is for debugging purposes only!
 * The specialized API calls should be used preferably.
 * Not all devices support each of the ::PC_GPS_COMMANDS.
 *
 * @param[in]   dh    Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
 * @param[in]   cmd   One of the ::PCPS_CMD_CODES supported by the device.
 * @param[out]  p     Pointer to a buffer to be filled up
 * @param[in]   size  Size of the buffer, has to match the expected data size associated with cmd
 *
 * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES
 *
 * @see ::mbg_chk_dev_has_gps_data
 * @see ::mbg_generic_write_gps
 * @see ::mbg_generic_read
 * @see ::mbg_generic_write
 * @see ::mbg_generic_io
 */
_MBG_API_ATTR int _MBG_API mbg_generic_read_gps( MBG_DEV_HANDLE dh, int cmd,
                                                 void *p, int size )
{
  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_cnv_ret_val( rc );

}  // mbg_generic_read_gps



/*HDR*/
/* (Intentionally excluded from Doxygen)
 * Generic write function which writes a command code plus an
 * associated number of data bytes to a device.
 *
 * <b>Warning</b>: This is for debugging purposes only!
 * The specialized API calls should be used preferably.
 * Not all devices support each of the ::PC_GPS_COMMANDS.
 *
 * @param[in]  dh    Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
 * @param[in]  cmd   One of the ::PCPS_CMD_CODES supported by the device.
 * @param[in]  p     Pointer to a buffer of data to be written
 * @param[in]  size  Size of the buffer, has to match the expected data size associated with cmd
 *
 * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES
 *
 * @see ::mbg_generic_read
 * @see ::mbg_generic_read_gps
 * @see ::mbg_generic_write_gps
 * @see ::mbg_generic_io
 */
_MBG_API_ATTR int _MBG_API mbg_generic_write( MBG_DEV_HANDLE dh, int cmd,
                                              const void *p, int size )
{
  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_cnv_ret_val( rc );

}  // mbg_generic_write



/*HDR*/
/* (Intentionally excluded from Doxygen)
 * Generic write function which writes a GPS command code plus an
 * associated number of data bytes to a device.
 * The function ::mbg_chk_dev_has_gps_data can be used to check
 * whether this call is supported by a device.
 *
 * <b>Warning</b>: This is for debugging purposes only!
 * The specialized API calls should be used preferably.
 * Not all devices support each of the ::PC_GPS_COMMANDS.
 *
 * @param[in]  dh    Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
 * @param[in]  cmd   One of the ::PCPS_CMD_CODES supported by the device.
 * @param[in]  p     Pointer to a buffer of data to be written
 * @param[in]  size  Size of the buffer, has to match the expected data size associated with cmd
 *
 * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES
 *
 * @see ::mbg_chk_dev_has_gps_data
 * @see ::mbg_generic_read_gps
 * @see ::mbg_generic_read
 * @see ::mbg_generic_write
 * @see ::mbg_generic_io
 */
_MBG_API_ATTR int _MBG_API mbg_generic_write_gps( MBG_DEV_HANDLE dh, int cmd,
                                                  const void *p, int size )
{
  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_cnv_ret_val( rc );

}  // mbg_generic_write_gps



/*HDR*/
/* (Intentionally excluded from Doxygen)
 * Write and/or read generic data to/from a device.
 * The function ::mbg_chk_dev_has_generic_io checks
 * whether this call is supported by a device.
 *
 * <b>Warning</b>: This call is for debugging purposes and internal use only!
 *
 * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES
 *
 * @see ::mbg_chk_dev_has_generic_io
 * @see ::mbg_generic_read
 * @see ::mbg_generic_write
 * @see ::mbg_generic_read_gps
 * @see ::mbg_generic_write_gps
 */
_MBG_API_ATTR int _MBG_API mbg_generic_io( MBG_DEV_HANDLE dh, int type,
                                           const void *in_p, int in_sz,
                                           void *out_p, int out_sz )
{
  MBGDEVIO_RET_VAL rc;

  #if !defined( _MBGIOCTL_H )
    // The hardware is accessed directly, so we must check
    // here if this call is supported.
    _mbgdevio_chk_cond( _pcps_ddev_has_generic_io( dh ) );
  #endif

  // 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_cnv_ret_val( rc );

}  // mbg_generic_io



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_time( MBG_DEV_HANDLE dh, PCPS_TIME *p )
{
  MBGDEVIO_RET_VAL rc;
  rc = _mbgdevio_read_var( dh, PCPS_GIVE_TIME, IOCTL_GET_PCPS_TIME, p );
  // No endianess conversion required.
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_time



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_time( MBG_DEV_HANDLE dh, const PCPS_STIME *p )
{
  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_cnv_ret_val( rc );

}  // mbg_set_time



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_sync_time( MBG_DEV_HANDLE dh, PCPS_TIME *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_sync_time



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_time_sec_change( MBG_DEV_HANDLE dh, PCPS_TIME *p )
{
  #if defined( MBG_TGT_WIN32 )
    MBGDEVIO_RET_VAL rc;
    rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_PCPS_TIME_SEC_CHANGE, p );
    // No endianess conversion required.
    return _mbgdevio_cnv_ret_val( rc );
  #else
    (void) dh;   // avoid warning "never used"
    (void) p;    // avoid warning "never used"
    return MBG_ERR_NOT_SUPP_ON_OS;
  #endif

}  // mbg_get_time_sec_change



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_hr_time( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_hr_time



/*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 API call ::mbg_chk_dev_has_event_time checks whether
 * this call is supported by a device.
 *
 * <b>Note:</b> This is only supported by some special firmware.
 *
 * @param[in]  dh  Valid ::MBG_DEV_HANDLE handle to a Meinberg device.
 * @param[in]  p   Pointer to a ::PCPS_TIME_STAMP structure to be written.
 *
 * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES
 *
 * @see ::mbg_chk_dev_has_event_time
 */
_MBG_API_ATTR int _MBG_API mbg_set_event_time( MBG_DEV_HANDLE dh, const PCPS_TIME_STAMP *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    PCPS_TIME_STAMP tmp = *p;
    _mbg_swab_pcps_time_stamp( &tmp );
    p = &tmp;
  #endif
  _mbgdevio_write_var_chk( dh, PCPS_SET_EVENT_TIME, IOCTL_SET_PCPS_EVENT_TIME,
                           p, _pcps_ddev_has_event_time( dh ) );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_event_time



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_serial( MBG_DEV_HANDLE dh, PCPS_SERIAL *p )
{
  MBGDEVIO_RET_VAL rc;
  rc = _mbgdevio_read_var( dh, PCPS_GET_SERIAL, IOCTL_GET_PCPS_SERIAL, p );
  // No endianess conversion required.
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_serial



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_serial( MBG_DEV_HANDLE dh, const PCPS_SERIAL *p )
{
  MBGDEVIO_RET_VAL rc;
  // No endianess conversion required.
  rc = _mbgdevio_write_var( dh, PCPS_SET_SERIAL, IOCTL_SET_PCPS_SERIAL, p );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_serial



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_tzcode( MBG_DEV_HANDLE dh, PCPS_TZCODE *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_tzcode



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_tzcode( MBG_DEV_HANDLE dh, const PCPS_TZCODE *p )
{
  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_cnv_ret_val( rc );

}  // mbg_set_tzcode



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_pcps_tzdl( MBG_DEV_HANDLE dh, PCPS_TZDL *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_pcps_tzdl



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_pcps_tzdl( MBG_DEV_HANDLE dh, const PCPS_TZDL *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    PCPS_TZDL tmp = *p;
    _mbg_swab_pcps_tzdl( &tmp );
    p = &tmp;
  #endif
  _mbgdevio_write_var_chk( dh, PCPS_SET_PCPS_TZDL, IOCTL_SET_PCPS_TZDL,
                           p, _pcps_ddev_has_pcps_tzdl( dh ) );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_pcps_tzdl



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_ref_offs( MBG_DEV_HANDLE dh, MBG_REF_OFFS *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_ref_offs



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_ref_offs( MBG_DEV_HANDLE dh, const MBG_REF_OFFS *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    MBG_REF_OFFS tmp = *p;
    _mbg_swab_mbg_ref_offs( &tmp );
    p = &tmp;
  #endif
  _mbgdevio_write_var_chk( dh, PCPS_SET_REF_OFFS, IOCTL_SET_REF_OFFS,
                           p, _pcps_ddev_has_ref_offs( dh ) );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_ref_offs



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_opt_info( MBG_DEV_HANDLE dh, MBG_OPT_INFO *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_opt_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_opt_settings( MBG_DEV_HANDLE dh, const MBG_OPT_SETTINGS *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    MBG_OPT_SETTINGS tmp = *p;
    _mbg_swab_mbg_opt_settings( &tmp );
    p = &tmp;
  #endif
  _mbgdevio_write_var_chk( dh, PCPS_SET_OPT_SETTINGS,
                           IOCTL_SET_MBG_OPT_SETTINGS, p,
                           _pcps_ddev_has_opt_flags( dh ) );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_opt_settings



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_irig_rx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_irig_rx_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_irig_rx_settings( MBG_DEV_HANDLE dh, const IRIG_SETTINGS *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    IRIG_SETTINGS tmp = *p;
    _mbg_swab_irig_settings( &tmp );
    p = &tmp;
  #endif
  _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_cnv_ret_val( rc );

}  // mbg_set_irig_rx_settings



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_all_irig_rx_info( MBG_DEV_HANDLE dh,
                                                     const PCPS_DEV *pdev,
                                                     IRIG_INFO *p_irig_info,
                                                     MBG_REF_OFFS *p_ref_offs,
                                                     MBG_OPT_INFO *p_opt_info )
{
  int rc;

  if ( !_pcps_is_irig_rx( pdev ) )
    return MBG_ERR_NOT_SUPP_BY_DEV;

  rc = mbg_get_irig_rx_info( dh, p_irig_info );

  if ( mbg_rc_is_success( rc ) && _pcps_has_ref_offs( pdev ) )
    rc = mbg_get_ref_offs( dh, p_ref_offs );

  if ( mbg_rc_is_success( rc ) && _pcps_has_opt_flags( pdev ) )
    rc = mbg_get_opt_info( dh, p_opt_info );

  return rc;

}  // mbg_get_all_irig_rx_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_save_all_irig_rx_settings( MBG_DEV_HANDLE dh,
                                                          const PCPS_DEV *pdev,
                                                          const IRIG_SETTINGS *p_irig_settings,
                                                          const MBG_REF_OFFS *p_ref_offs,
                                                          const MBG_OPT_SETTINGS *p_opt_settings )
{
  int rc;

  if ( !_pcps_is_irig_rx( pdev ) )
    return MBG_ERR_NOT_SUPP_BY_DEV;

  rc = mbg_set_irig_rx_settings( dh, p_irig_settings );

  if ( mbg_rc_is_success( rc ) && _pcps_has_ref_offs( pdev ) )
    rc = mbg_set_ref_offs( dh, p_ref_offs );

  if ( mbg_rc_is_success( rc ) && _pcps_has_opt_flags( pdev ) )
    rc = mbg_set_opt_settings( dh, p_opt_settings );

  return rc;

}  // mbg_save_all_irig_rx_settings



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_irig_ctrl_bits( MBG_DEV_HANDLE dh,
                                                   MBG_IRIG_CTRL_BITS *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_irig_ctrl_bits



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data( MBG_DEV_HANDLE dh,
                                                  MBG_RAW_IRIG_DATA *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_raw_irig_data



/*HDR*/
_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_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_cnv_ret_val( rc );

}  // mbg_get_raw_irig_data_on_sec_change



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_irig_time( MBG_DEV_HANDLE dh,
                                              PCPS_IRIG_TIME *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_irig_time



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_clr_ucap_buff( MBG_DEV_HANDLE dh )
{
  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_cnv_ret_val( rc );

}  // mbg_clr_ucap_buff



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_ucap_entries( MBG_DEV_HANDLE dh, PCPS_UCAP_ENTRIES *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_ucap_entries



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_ucap_event( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_ucap_event



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_tzdl( MBG_DEV_HANDLE dh, TZDL *p )
{
  MBGDEVIO_RET_VAL rc;
  rc = _mbgdevio_read_gps_var( dh, PC_GPS_TZDL, IOCTL_GET_GPS_TZDL, p );
  _mbg_swab_tzdl( p );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_gps_tzdl



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_tzdl( MBG_DEV_HANDLE dh, const TZDL *p )
{
  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_cnv_ret_val( rc );

}  // mbg_set_gps_tzdl



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_sw_rev( MBG_DEV_HANDLE dh, SW_REV *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_gps_sw_rev



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_bvar_stat( MBG_DEV_HANDLE dh, BVAR_STAT *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_gps_stat



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_time( MBG_DEV_HANDLE dh, TTM *p )
{
  MBGDEVIO_RET_VAL rc;
  rc = _mbgdevio_read_gps_var( dh, PC_GPS_TIME, IOCTL_GET_GPS_TIME, p );
  _mbg_swab_ttm( p );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_gps_time



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_time( MBG_DEV_HANDLE dh, const TTM *p )
{
  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_cnv_ret_val( rc );

}  // mbg_set_gps_time



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_port_parm( MBG_DEV_HANDLE dh, PORT_PARM *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_gps_port_parm



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_port_parm( MBG_DEV_HANDLE dh, const PORT_PARM *p )
{
  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_cnv_ret_val( rc );

}  // mbg_set_gps_port_parm



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_ant_info( MBG_DEV_HANDLE dh, ANT_INFO *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_gps_ant_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_ucap( MBG_DEV_HANDLE dh, TTM *p )
{
  MBGDEVIO_RET_VAL rc;
  rc = _mbgdevio_read_gps_var( dh, PC_GPS_UCAP, IOCTL_GET_GPS_UCAP, p );
  _mbg_swab_ttm( p );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_gps_ucap



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_enable_flags( MBG_DEV_HANDLE dh, ENABLE_FLAGS *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_gps_enable_flags



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_enable_flags( MBG_DEV_HANDLE dh,
                                       const ENABLE_FLAGS *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    ENABLE_FLAGS tmp = *p;
    _mbg_swab_enable_flags( &tmp );
    p = &tmp;
  #endif
  rc = _mbgdevio_write_gps_var( dh, PC_GPS_ENABLE_FLAGS,
                           IOCTL_SET_GPS_ENABLE_FLAGS, p );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_gps_enable_flags



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_stat_info( MBG_DEV_HANDLE dh, STAT_INFO *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_gps_stat_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_cmd( MBG_DEV_HANDLE dh, const GPS_CMD *p )
{
  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_cnv_ret_val( rc );

}  // mbg_set_gps_cmd


/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_pos( MBG_DEV_HANDLE dh, POS *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_gps_pos



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_pos_xyz( MBG_DEV_HANDLE dh, const XYZ p )
{
  MBGDEVIO_RET_VAL rc;
  XYZ xyz;
  int i;

  for ( i = 0; i < N_XYZ; i++ )
  {
    xyz[i] = p[i];
    swap_double( &xyz[i] );
    _mbg_swab_double( &xyz[i] );
  }

  // _mbgdevio_write_gps_var() would fail here since
  // 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_cnv_ret_val( rc );

}  // mbg_set_gps_pos_xyz



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_pos_lla( MBG_DEV_HANDLE dh, const LLA p )
{
  MBGDEVIO_RET_VAL rc;
  LLA lla;
  int i;

  for ( i = 0; i < N_LLA; i++ )
  {
    lla[i] = p[i];
    swap_double( &lla[i] );
    _mbg_swab_double( &lla[i] );
  }

  // _mbgdevio_write_gps_var() would fail here since
  // 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_cnv_ret_val( rc );

}  // mbg_set_gps_pos_lla



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_ant_cable_len( MBG_DEV_HANDLE dh, ANT_CABLE_LEN *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_gps_ant_cable_len



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_ant_cable_len( MBG_DEV_HANDLE dh,
                                                      const ANT_CABLE_LEN *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    ANT_CABLE_LEN tmp = *p;
    _mbg_swab_ant_cable_len( &tmp );
    p = &tmp;
  #endif
  _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_cnv_ret_val( rc );

}  // mbg_set_gps_ant_cable_len



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_receiver_info( MBG_DEV_HANDLE dh, RECEIVER_INFO *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_gps_receiver_info



/*HDR*/
_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_RET_VAL rc;

  #if _MBG_SUPP_VAR_ACC_SIZE
    _mbgdevio_read_gps_chk( dh, PC_GPS_ALL_STR_TYPE_INFO,
                            IOCTL_GET_GPS_ALL_STR_TYPE_INFO, stii,
                            p_ri->n_str_type * sizeof( stii[0] ),
                            _pcps_ddev_has_receiver_info( dh ) );
  #else
    // We check the model_code to see whether the receiver info
    // has been read from a device which really supports it, or
    // a dummy structure has been setup.
    if ( p_ri && ( p_ri->model_code != GPS_MODEL_UNKNOWN ) )
      rc = _mbgdevio_gen_read_gps( dh, PC_GPS_ALL_STR_TYPE_INFO, stii,
                                   p_ri->n_str_type * sizeof( stii[0] ) );
    else
      return MBG_ERR_NOT_SUPP_BY_DEV;
  #endif

  #if defined( MBG_ARCH_BIG_ENDIAN )
    if ( mbg_rc_is_success( rc ) )
    {
      int i;
      for ( i = 0; i < p_ri->n_str_type; i++ )
      {
        STR_TYPE_INFO_IDX *p = &stii[i];
        _mbg_swab_str_type_info_idx( p );
      }
    }
  #endif

  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_gps_all_str_type_info



/*HDR*/
_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_RET_VAL rc;

  #if _MBG_SUPP_VAR_ACC_SIZE
    _mbgdevio_read_gps_chk( dh, PC_GPS_ALL_PORT_INFO,
                            IOCTL_GET_GPS_ALL_PORT_INFO, pii,
                            p_ri->n_com_ports * sizeof( pii[0] ),
                            _pcps_ddev_has_receiver_info( dh ) );
  #else
    // We check the model_code to see whether the receiver info
    // has been read from a device which really supports it, or
    // a dummy structure has been set up.
    if ( p_ri && ( p_ri->model_code != GPS_MODEL_UNKNOWN ) )
      rc = _mbgdevio_gen_read_gps( dh, PC_GPS_ALL_PORT_INFO, pii,
                                   p_ri->n_com_ports * sizeof( pii[0] ) );
    else
      return MBG_ERR_NOT_SUPP_BY_DEV;
  #endif

  #if defined( MBG_ARCH_BIG_ENDIAN )
    if ( mbg_rc_is_success( rc ) )
    {
      int i;
      for ( i = 0; i < p_ri->n_com_ports; i++ )
      {
        PORT_INFO_IDX *p = &pii[i];
        _mbg_swab_port_info_idx( p );
      }
    }
  #endif

  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_gps_all_port_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings_idx( MBG_DEV_HANDLE dh,
                                                          const PORT_SETTINGS_IDX *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    PORT_SETTINGS_IDX tmp = *p;
    _mbg_swab_port_settings_idx( &tmp );
    p = &tmp;
  #endif
  _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_cnv_ret_val( rc );

}  // mbg_set_gps_port_settings_idx



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings( MBG_DEV_HANDLE dh,
                                                      const PORT_SETTINGS *p, int idx )
{
  PORT_SETTINGS_IDX psi = { 0 };

  psi.idx = idx;
  psi.port_settings = *p;
  _mbg_swab_port_settings_idx( &psi );

  return mbg_set_gps_port_settings_idx( dh, &psi );

}  // mbg_set_gps_port_settings



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_setup_receiver_info( MBG_DEV_HANDLE dh,
                                                    const PCPS_DEV *p_dev,
                                                    RECEIVER_INFO *p )
{
  PCPS_DEV dev = { { 0 } };
  int rc;

  if ( p_dev == NULL )
  {
    rc = mbg_get_device_info( dh, &dev );

    if ( mbg_rc_is_error( rc ) )
      return rc;

    p_dev = &dev;
  }

  // If the clock supports the receiver_info structure then
  // read it from the clock, otherwise set up some default
  // values depending on the clock type.
  if ( _pcps_has_receiver_info( p_dev ) )
  {
    rc = mbg_get_gps_receiver_info( dh, p );

    if ( mbg_rc_is_error( rc ) )
      return rc;

    goto check;
  }

  if ( _pcps_is_gps( p_dev ) )
    _setup_default_receiver_info_gps( p );
  else
    _setup_default_receiver_info_dcf( p, p_dev );

check:
  return chk_dev_receiver_info( p );

}  // mbg_setup_receiver_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_asic_version( MBG_DEV_HANDLE dh, PCI_ASIC_VERSION *p )
{
  #if defined( _MBGIOCTL_H )
    MBGDEVIO_RET_VAL rc;
    rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_PCI_ASIC_VERSION, p );
    return _mbgdevio_cnv_ret_val( rc );
  #else
    if ( !_pcps_ddev_has_asic_version( dh ) )
      return MBG_ERR_NOT_SUPP_BY_DEV;

    // TODO Should we care about memory mapped vs. port I/O access ?
    *p = _mbg_inp32_to_cpu( dh, 0, _pcps_ddev_io_base_mapped( dh, 0 )
             + offsetof( PCI_ASIC, raw_version ) );

    return MBG_SUCCESS;
  #endif

}  // mbg_get_asic_version



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_asic_features( MBG_DEV_HANDLE dh,
                                                  PCI_ASIC_FEATURES *p )
{

  #if defined( _MBGIOCTL_H )
    MBGDEVIO_RET_VAL rc;
    rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_PCI_ASIC_FEATURES, p );
    return _mbgdevio_cnv_ret_val( rc );
  #else
    if ( !_pcps_ddev_has_asic_features( dh ) )
    {
      *p = 0;
      return MBG_ERR_NOT_SUPP_BY_DEV;
    }

    // TODO Should we care about memory mapped vs. port I/O access ?
    *p = _mbg_inp32_to_cpu( dh, 0, _pcps_ddev_io_base_mapped( dh, 0 )
             + offsetof( PCI_ASIC, features ) );

    return MBG_SUCCESS;
  #endif

}  // mbg_get_asic_features



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_time_scale_info( MBG_DEV_HANDLE dh, MBG_TIME_SCALE_INFO *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_time_scale_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_time_scale_settings( MBG_DEV_HANDLE dh, const MBG_TIME_SCALE_SETTINGS *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    MBG_TIME_SCALE_SETTINGS tmp = *p;
    _mbg_swab_mbg_time_scale_settings( &tmp );
    p = &tmp;
  #endif
  _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_cnv_ret_val( rc );

}  // mbg_set_time_scale_settings



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_utc_parm( MBG_DEV_HANDLE dh, UTC *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_utc_parm



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_utc_parm( MBG_DEV_HANDLE dh, const UTC *p )
{
  MBGDEVIO_RET_VAL rc;

  // the original parameters need to be modified anyway, so always use a copy
  UTC tmp = *p;

  #if defined( MBG_ARCH_BIG_ENDIAN )
    _mbg_swab_utc_parm( &tmp );
  #endif

  swap_double( &tmp.A0 );
  swap_double( &tmp.A1 );

  _mbgdevio_write_gps_var_chk( dh, PC_GPS_UTC,
                               IOCTL_SET_GPS_UTC_PARM, &tmp,
                               _pcps_ddev_has_utc_parm( dh ) );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_utc_parm



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_time_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_CYCLES *p )
{
  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 )
    // only if not using IOCTLs
    // for PCPS_TIME, read stamp AFTER the call
    p->cycles = 0;  //##++
  #endif
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_time_cycles



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_hr_time_cycles( MBG_DEV_HANDLE dh,
                                                   PCPS_HR_TIME_CYCLES *p )
{
  MBGDEVIO_RET_VAL rc;
  #if !defined( _MBGIOCTL_H )
    // only if not using IOCTLs
    // for PCPS_HR_TIME, read stamp BEFORE the call
    p->cycles = 0;  //##++
  #endif
  _mbgdevio_read_var_chk( dh, PCPS_GIVE_HR_TIME,
                          IOCTL_GET_PCPS_HR_TIME_CYCLES,
                          p, _pcps_ddev_has_hr_time( dh ) );
  _mbg_swab_pcps_hr_time_cycles( p );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_hr_time_cycles



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_hr_time_comp( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p,
                                                 int32_t *hns_latency )
{
  PCPS_HR_TIME_CYCLES htc;
  MBG_PC_CYCLES cyc_now;
  int rc;

  // First get current time stamp counter value, then read
  // a high resolution time stamp from the board, plus the
  // associated time stamp counter value.
  mbg_get_pc_cycles( &cyc_now );

  rc = mbg_get_hr_time_cycles( dh, &htc );

  if ( mbg_rc_is_success( rc ) )
  {
    mbg_init_pc_cycles_frequency( dh, &pc_cycles_frequency );
    rc = mbg_comp_hr_latency( &htc.t.tstamp, &htc.cycles, &cyc_now, &pc_cycles_frequency, hns_latency );
    *p = htc.t;
  }

  return rc;

}  // mbg_get_hr_time_comp



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_irig_tx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p )
{
  MBGDEVIO_RET_VAL rc;

  #if !defined( _MBGIOCTL_H )
    // This is a workaround for GPS169PCIs with early
    // firmware versions. See RCS log for details.
    uint8_t pcps_cmd = PCPS_GET_IRIG_TX_INFO;

    if ( _pcps_ddev_requires_irig_workaround( dh ) )
      pcps_cmd = PCPS_GET_IRIG_RX_INFO;

    #define _PCPS_CMD   pcps_cmd
  #else
    #define _PCPS_CMD   PCPS_GET_IRIG_TX_INFO
  #endif

  _mbgdevio_read_var_chk( dh, _PCPS_CMD, IOCTL_GET_PCPS_IRIG_TX_INFO,
                          p, _pcps_ddev_has_irig_tx( dh ) );
  #undef _PCPS_CMD

  _mbg_swab_irig_info( p );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_irig_tx_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_irig_tx_settings( MBG_DEV_HANDLE dh, const IRIG_SETTINGS *p )
{
  MBGDEVIO_RET_VAL rc;
  #if !defined( _MBGIOCTL_H )
    uint8_t pcps_cmd;
  #endif

  #if defined( MBG_ARCH_BIG_ENDIAN )
    IRIG_SETTINGS tmp = *p;
    _mbg_swab_irig_settings( &tmp );
    p = &tmp;
  #endif

  #if !defined( _MBGIOCTL_H )
    // This is a workaround for GPS169PCIs with early
    // firmware versions. See RCS log for details.
    pcps_cmd = PCPS_SET_IRIG_TX_SETTINGS;

    if ( _pcps_ddev_requires_irig_workaround( dh ) )
      pcps_cmd = PCPS_SET_IRIG_RX_SETTINGS;

    #define _PCPS_CMD   pcps_cmd
  #else
    #define _PCPS_CMD   PCPS_SET_IRIG_TX_SETTINGS
  #endif

  _mbgdevio_write_var_chk( dh, _PCPS_CMD, IOCTL_SET_PCPS_IRIG_TX_SETTINGS,
                           p, _pcps_ddev_has_irig_tx( dh ) );
  #undef _PCPS_CMD

  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_irig_tx_settings



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_synth( MBG_DEV_HANDLE dh, SYNTH *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_synth



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_synth( MBG_DEV_HANDLE dh, const SYNTH *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    SYNTH tmp = *p;
    _mbg_swab_synth( &tmp );
    p = &tmp;
  #endif
  _mbgdevio_write_var_chk( dh, PCPS_SET_SYNTH, IOCTL_SET_SYNTH,
                           p, _pcps_ddev_has_synth( dh ) );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_synth



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_synth_state( MBG_DEV_HANDLE dh, SYNTH_STATE *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_synth_state



/*HDR*/
_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_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_cnv_ret_val( rc );
  #else
    // This is currently not supported by the target environment.
    return MBG_ERR_NOT_SUPP_ON_OS;
  #endif

}  // mbg_get_fast_hr_timestamp_cycles



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_comp( MBG_DEV_HANDLE dh,
                                                           PCPS_TIME_STAMP *p,
                                                           int32_t *hns_latency )
{
  PCPS_TIME_STAMP_CYCLES tc;
  MBG_PC_CYCLES cyc_now;
  int rc;

  // First get current time stamp counter value, then read
  // a high resolution time stamp from the board, plus the
  // associated time stamp counter value.
  mbg_get_pc_cycles( &cyc_now );

  rc = mbg_get_fast_hr_timestamp_cycles( dh, &tc );

  if ( mbg_rc_is_success( rc ) )
  {
    mbg_init_pc_cycles_frequency( dh, &pc_cycles_frequency );
    rc = mbg_comp_hr_latency( &tc.tstamp, &tc.cycles, &cyc_now, &pc_cycles_frequency, hns_latency );
    *p = tc.tstamp;
  }

  return rc;

}  // mbg_get_fast_hr_timestamp_comp



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp( MBG_DEV_HANDLE dh,
                                                      PCPS_TIME_STAMP *p )
{
  #if defined( _MBGIOCTL_H )
    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_cnv_ret_val( rc );
  #else
    // This is currently not supported by the target environment.
    return MBG_ERR_NOT_SUPP_ON_OS;
  #endif

}  // mbg_get_fast_hr_timestamp



/*HDR*/
_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_RET_VAL rc;

  #if _MBG_SUPP_VAR_ACC_SIZE
    _mbgdevio_read_gps_chk( dh, PC_GPS_ALL_POUT_INFO,
                            IOCTL_GET_GPS_ALL_POUT_INFO, pii,
                            p_ri->n_prg_out * sizeof( pii[0] ),
                            _pcps_ddev_has_receiver_info( dh ) );
  #else
    // We check the model_code to see whether the receiver info
    // has been read from a device which really supports it, or
    // a dummy structure has been setup.
    if ( p_ri && ( p_ri->model_code != GPS_MODEL_UNKNOWN ) )
      rc = _mbgdevio_gen_read_gps( dh, PC_GPS_ALL_POUT_INFO, pii,
                                   p_ri->n_prg_out * sizeof( pii[0] ) );
    else
      return MBG_ERR_NOT_SUPP_BY_DEV;
  #endif

  #if defined( MBG_ARCH_BIG_ENDIAN )
    if ( mbg_rc_is_success( rc ) )
    {
      int i;
      for ( i = 0; i < p_ri->n_prg_out; i++ )
      {
        POUT_INFO_IDX *p = &pii[i];
        _mbg_swab_pout_info_idx_on_get( p );
      }
    }
  #endif

  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_gps_all_pout_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings_idx( MBG_DEV_HANDLE dh,
                                                          const POUT_SETTINGS_IDX *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    POUT_SETTINGS_IDX tmp = *p;
    _mbg_swab_pout_settings_idx_on_set( &tmp );
    p = &tmp;
  #endif
  _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_cnv_ret_val( rc );

}  // mbg_set_gps_pout_settings_idx



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings( MBG_DEV_HANDLE dh,
                                                      const POUT_SETTINGS *p, int idx )
{
  POUT_SETTINGS_IDX psi = { 0 };

  psi.idx = idx;
  psi.pout_settings = *p;

  return mbg_set_gps_pout_settings_idx( dh, &psi );

}  // mbg_set_gps_pout_settings



/*HDR*/
_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_RET_VAL rc;
    rc = _mbgdevio_read_var( dh, -1, IOCTL_GET_IRQ_STAT_INFO, p );
    // native endianess, no need to swap bytes
    return _mbgdevio_cnv_ret_val( rc );
  #else
    *p = dh->irq_stat_info;
    return MBG_SUCCESS;
  #endif

}  // mbg_get_irq_stat_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_lan_if_info( MBG_DEV_HANDLE dh, LAN_IF_INFO *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_lan_if_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_ip4_state( MBG_DEV_HANDLE dh, IP4_SETTINGS *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_ip4_state



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_ip4_settings( MBG_DEV_HANDLE dh, IP4_SETTINGS *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_ip4_settings



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_ip4_settings( MBG_DEV_HANDLE dh,
                                                 const IP4_SETTINGS *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    IP4_SETTINGS tmp = *p;
    _mbg_swab_ip4_settings( &tmp );
    p = &tmp;
  #endif
  _mbgdevio_write_gps_var_chk( dh, PC_GPS_IP4_SETTINGS,
                               IOCTL_SET_IP4_SETTINGS, p,
                               _pcps_ddev_has_lan_intf( dh ) );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_ip4_settings



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_ptp_state( MBG_DEV_HANDLE dh, PTP_STATE *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_ptp_state



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_ptp_cfg_info( MBG_DEV_HANDLE dh, PTP_CFG_INFO *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_ptp_cfg_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_ptp_cfg_settings( MBG_DEV_HANDLE dh,
                                                     const PTP_CFG_SETTINGS *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    PTP_CFG_SETTINGS tmp = *p;
    _mbg_swab_ptp_cfg_settings( &tmp );
    p = &tmp;
  #endif
  _mbgdevio_write_gps_var_chk( dh, PC_GPS_PTP_CFG,
                               IOCTL_SET_PTP_CFG_SETTINGS, p,
                               _pcps_ddev_has_ptp( dh ) );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_ptp_cfg_settings



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_ptp_uc_master_cfg_limits( MBG_DEV_HANDLE dh, PTP_UC_MASTER_CFG_LIMITS *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_ptp_uc_master_cfg_limits



/*HDR*/
_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_RET_VAL rc;

  #if _MBG_SUPP_VAR_ACC_SIZE
    _mbgdevio_read_gps_chk( dh, PC_GPS_ALL_PTP_UC_MASTER_INFO,
                            IOCTL_GET_ALL_PTP_UC_MASTER_INFO, pii,
                            p_umsl->n_supp_master * sizeof( pii[0] ),
                            _pcps_ddev_has_ptp_unicast( dh ) );
  #else
    if ( p_umsl && p_umsl->n_supp_master )
      rc = _mbgdevio_gen_read_gps( dh, PC_GPS_ALL_PTP_UC_MASTER_INFO, pii,
                                             p_umsl->n_supp_master * sizeof( pii[0] ) );
    else
      return MBG_ERR_NOT_SUPP_BY_DEV;
  #endif

  #if defined( MBG_ARCH_BIG_ENDIAN )
    if ( mbg_rc_is_success( rc ) )
    {
      int i;
      for ( i = 0; i < p_umsl->n_supp_master; i++ )
      {
        PTP_UC_MASTER_INFO_IDX *p = &pii[i];
        _mbg_swab_ptp_uc_master_info_idx( p );
      }
    }
  #endif

  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_all_ptp_uc_master_info



/*HDR*/
_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_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    PTP_UC_MASTER_SETTINGS_IDX tmp = *p;
    _mbg_swab_ptp_uc_master_settings_idx( &tmp );
    p = &tmp;
  #endif
  _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_cnv_ret_val( rc );

}  // mbg_set_ptp_uc_master_settings_idx



/*HDR*/
_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_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_cnv_ret_val( rc );
  #else
    return MBG_ERR_NOT_SUPP_ON_OS;
  #endif

}  // mbg_get_time_info_hrt



/*HDR*/
_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_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_cnv_ret_val( rc );
  #else
    return MBG_ERR_NOT_SUPP_ON_OS;
  #endif

}  // mbg_get_time_info_tstamp



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_corr_info( MBG_DEV_HANDLE dh, CORR_INFO *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_corr_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_tr_distance( MBG_DEV_HANDLE dh, TR_DISTANCE *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_tr_distance



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_tr_distance( MBG_DEV_HANDLE dh, const TR_DISTANCE *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    TR_DISTANCE tmp = *p;
    _mbg_swab_tr_distance( &tmp );
    p = &tmp;
  #endif
  _mbgdevio_write_var_chk( dh, PCPS_SET_TR_DISTANCE, IOCTL_SET_TR_DISTANCE,
                           p, _pcps_ddev_has_tr_distance( dh ) );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_tr_distance



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_debug_status( MBG_DEV_HANDLE dh, MBG_DEBUG_STATUS *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_debug_status



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_clr_evt_log( MBG_DEV_HANDLE dh )
{
  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_cnv_ret_val( rc );

}  // mbg_clr_evt_log



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_num_evt_log_entries( MBG_DEV_HANDLE dh, MBG_NUM_EVT_LOG_ENTRIES *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_num_evt_log_entries



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_first_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_first_evt_log_entry



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_next_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_next_evt_log_entry



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_gps_gnss_mode_info( MBG_DEV_HANDLE dh, MBG_GNSS_MODE_INFO *p_mi )
{
  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_cnv_ret_val( rc );

}  // mbg_get_gps_gnss_mode_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_gnss_mode_settings( MBG_DEV_HANDLE dh,
                                                           const MBG_GNSS_MODE_SETTINGS *p_ms )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    MBG_GNSS_MODE_SETTINGS tmp = *p_ms;
    _mbg_swab_mbg_gnss_mode_settings( &tmp );
    p_ms = &tmp;
  #endif
  _mbgdevio_write_gps_var_chk( dh, PC_GPS_GNSS_MODE,
                               IOCTL_SET_GNSS_MODE_SETTINGS, p_ms,
                               _pcps_ddev_is_gnss( dh ) );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_gps_gnss_mode_settings



/*HDR*/
_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_RET_VAL rc;

  int n_supp = num_bits_set( p_mi->supp_gnss_types );

  #if _MBG_SUPP_VAR_ACC_SIZE
    _mbgdevio_read_gps_chk( dh, PC_GPS_ALL_GNSS_SAT_INFO,
                            IOCTL_GET_ALL_GNSS_SAT_INFO, gsii,
                            n_supp * sizeof( gsii[0] ),
                            _pcps_ddev_is_gnss( dh ) );
  #else
    rc = _mbgdevio_gen_read_gps( dh, PC_GPS_ALL_GNSS_SAT_INFO, gsii,
                                 n_supp * sizeof( gsii[0] ) );
  #endif

  #if defined( MBG_ARCH_BIG_ENDIAN )
    if ( mbg_rc_is_success( rc ) )
    {
      int i;
      for ( i = 0; i < n_supp; i++ )
      {
        GNSS_SAT_INFO_IDX *p = &gsii[i];
        _mbg_swab_gnss_sat_info_idx( p );
      }
    }
  #endif

  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_gps_all_gnss_sat_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_gpio_cfg_limits( MBG_DEV_HANDLE dh, MBG_GPIO_CFG_LIMITS *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_gpio_cfg_limits



/*HDR*/
_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_RET_VAL rc;

  uint32_t n_supp = p_gcl->num_io;

  #if _MBG_SUPP_VAR_ACC_SIZE
    _mbgdevio_read_gps_chk( dh, PC_GPS_ALL_GPIO_INFO,
                            IOCTL_GET_ALL_GPIO_INFO, gii,
                            n_supp * sizeof( gii[0] ),
                            _pcps_ddev_has_gpio( dh ) );
  #else
    rc = _mbgdevio_gen_read_gps( dh, PC_GPS_ALL_GPIO_INFO, gii,
                                 n_supp * sizeof( gii[0] ) );
  #endif

  #if defined( MBG_ARCH_BIG_ENDIAN )
    if ( mbg_rc_is_success( rc ) )
    {
      int i;
      for ( i = 0; i < n_supp; i++ )
      {
        MBG_GPIO_INFO_IDX *p = &gii[i];
        _mbg_swab_mbg_gpio_info_idx( p, 1 );
      }
    }
  #endif

  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_gps_all_gpio_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_gpio_settings_idx( MBG_DEV_HANDLE dh,
                                                          const MBG_GPIO_SETTINGS_IDX *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    MBG_GPIO_SETTINGS_IDX tmp = *p;
    _mbg_swab_mbg_gpio_settings_idx( &tmp, 1 );
    p = &tmp;
  #endif
  _mbgdevio_write_gps_var_chk( dh, PC_GPS_GPIO_SETTINGS_IDX,
                               IOCTL_SET_GPIO_SETTINGS_IDX, p,
                               _pcps_ddev_has_gpio( dh ) );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_gps_gpio_settings_idx



/*HDR*/
_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_RET_VAL rc;

  uint32_t n_supp;

  if ( !( p_gcl->flags & MBG_GPIO_CFG_LIMIT_FLAG_MASK_STATUS_SUPP ) )
    return MBG_ERR_NOT_SUPP_BY_DEV;

  n_supp = p_gcl->num_io;

  #if _MBG_SUPP_VAR_ACC_SIZE
    _mbgdevio_read_gps_chk( dh, PC_GPS_ALL_GPIO_STATUS,
                            IOCTL_GET_ALL_GPIO_STATUS, gsi,
                            n_supp * sizeof( gsi[0] ),
                            _pcps_ddev_has_gpio( dh ) );
  #else
    rc = _mbgdevio_gen_read_gps( dh, PC_GPS_ALL_GPIO_STATUS, gsi,
                                 n_supp * sizeof( gsi[0] ) );
  #endif

  #if defined( MBG_ARCH_BIG_ENDIAN )
    if ( mbg_rc_is_success( rc ) )
    {
      int i;
      for ( i = 0; i < n_supp; i++ )
      {
        MBG_GPIO_STATUS_IDX *p = &gsi[i];
        _mbg_swab_mbg_gpio_status_idx( p );
      }
    }
  #endif

  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_gps_all_gpio_status



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_xmr_instances( MBG_DEV_HANDLE dh, XMULTI_REF_INSTANCES *p )
{
  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_cnv_ret_val( rc );

}  // mbg_get_xmr_instances



/*HDR*/
_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_RET_VAL rc;

  int n_supp = p_xmri->n_xmr_settings;

  #if _MBG_SUPP_VAR_ACC_SIZE
    _mbgdevio_read_gps_chk( dh, PC_GPS_ALL_XMR_STATUS,
                            IOCTL_GET_ALL_XMR_STATUS, xmrsi,
                            n_supp * sizeof( xmrsi[0] ),
                            _pcps_ddev_has_xmr( dh ) );
  #else
    rc = _mbgdevio_gen_read_gps( dh, PC_GPS_ALL_XMR_STATUS, xmrsi,
                                 n_supp * sizeof( xmrsi[0] ) );
  #endif

  #if defined( MBG_ARCH_BIG_ENDIAN )
    if ( mbg_rc_is_success( rc ) )
    {
      int i;
      for ( i = 0; i < n_supp; i++ )
      {
        XMULTI_REF_STATUS_IDX *p = &xmrsi[i];
        _mbg_swab_xmulti_ref_status_idx( p );
      }
    }
  #endif

  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_gps_all_xmr_status



/*HDR*/
_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_RET_VAL rc;

  int n_supp = p_xmri->n_xmr_settings;

  #if _MBG_SUPP_VAR_ACC_SIZE
    _mbgdevio_read_gps_chk( dh, PC_GPS_ALL_XMR_INFO,
                            IOCTL_GET_ALL_XMR_INFO, xmrii,
                            n_supp * sizeof( xmrii[0] ),
                            _pcps_ddev_has_xmr( dh ) );
  #else
    rc = _mbgdevio_gen_read_gps( dh, PC_GPS_ALL_XMR_INFO, xmrii,
                                 n_supp * sizeof( xmrii[0] ) );
  #endif

  #if defined( MBG_ARCH_BIG_ENDIAN )
    if ( mbg_rc_is_success( rc ) )
    {
      int i;
      for ( i = 0; i < n_supp; i++ )
      {
        XMULTI_REF_INFO_IDX *p = &xmrii[i];
        _mbg_swab_xmulti_ref_info_idx( p );
      }
    }
  #endif

  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_gps_all_xmr_info



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_gps_xmr_settings_idx( MBG_DEV_HANDLE dh,
                                                         const XMULTI_REF_SETTINGS_IDX *p )
{
  MBGDEVIO_RET_VAL rc;
  #if defined( MBG_ARCH_BIG_ENDIAN )
    XMULTI_REF_SETTINGS_IDX tmp = *p;
    _mbg_swab_xmulti_ref_settings_idx( &tmp );
    p = &tmp;
  #endif
  _mbgdevio_write_gps_var_chk( dh, PC_GPS_XMR_SETTINGS_IDX,
                               IOCTL_SET_XMR_SETTINGS_IDX, p,
                               _pcps_ddev_has_xmr( dh ) );
  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_set_gps_xmr_settings_idx



/*HDR*/
_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_RET_VAL rc;

  if ( !( p_xmri->flags & XMRIF_MSK_HOLDOVER_STATUS_SUPP ) )
    return MBG_ERR_NOT_SUPP_BY_DEV;

  _mbgdevio_read_gps_var_chk( dh, PC_GPS_XMR_HOLDOVER_STATUS,
                              IOCTL_GET_XMR_HOLDOVER_STATUS, p,
                              _pcps_ddev_has_xmr( dh ) );
  _mbg_swab_xmr_holdover_status( p );

  return _mbgdevio_cnv_ret_val( rc );

}  // mbg_get_xmr_holdover_status



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p )
{
  #if defined( MBG_TGT_LINUX )  // TODO Eventually generally for POSIX?

    if ( sched_getaffinity( pid, sizeof( *p ), p ) == 0 )  // success
      return MBG_SUCCESS;

    return mbg_get_last_error( NULL );

  #elif defined( MBG_TGT_WIN32 )

    MBG_CPU_SET system_affinity_mask = 0;

    if ( GetProcessAffinityMask( pid, p, &system_affinity_mask ) )
      return MBG_SUCCESS;

    return mbg_get_last_error( NULL );

  #else

    return MBG_ERR_NOT_SUPP_ON_OS;

  #endif

}  // mbg_get_process_affinity



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p )
{
  #if defined( MBG_TGT_LINUX )  // TODO Eventually generally for POSIX?

    if ( sched_setaffinity( pid, sizeof( *p ), p ) == 0 )
      return MBG_SUCCESS;

    return mbg_get_last_error( NULL );

  #elif defined( MBG_TGT_WIN32 )

    if ( SetProcessAffinityMask( pid, *p ) )
      return MBG_SUCCESS;

    return mbg_get_last_error( NULL );

  #else

    return MBG_ERR_NOT_SUPP_ON_OS;

  #endif

}  // mbg_set_process_affinity



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_set_current_process_affinity_to_cpu( int cpu_num )
{
  MBG_CPU_SET cpu_set;

  _mbg_cpu_clear( &cpu_set );
  _mbg_cpu_set( cpu_num, &cpu_set );

  return mbg_set_process_affinity( _mbg_get_current_process(), &cpu_set );

}  // mbg_set_current_process_affinity_to_cpu



#if MBGDEVIO_USE_THREAD_API

/*HDR*/
_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 )  // TODO Eventually generally for POSIX?

    if ( pthread_create( &p_ti->thread_id, NULL, fnc, arg ) == 0 )
      return MBG_SUCCESS;

    return mbg_get_last_error( NULL );

  #elif defined( MBG_TGT_WIN32 )

    HANDLE h;
    DWORD thread_id = 0;

    p_ti->exit_request = CreateEvent( NULL, FALSE, FALSE, NULL );

    if ( p_ti->exit_request == NULL )
      goto fail;

    h = CreateThread( NULL, 0, fnc, arg, 0, &thread_id );

    if ( h == NULL )
    {
      CloseHandle( p_ti->exit_request );
      goto fail;
    }

    p_ti->thread_id = h;

    return MBG_SUCCESS;

fail:
    return mbg_get_last_error( NULL );

  #else

    return MBG_ERR_NOT_SUPP_ON_OS;

  #endif

}  // mbg_thread_create



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_thread_stop( MBG_THREAD_INFO *p_ti )
{
  #if defined( MBG_TGT_LINUX )  // TODO Eventually generally for POSIX?

    pthread_cancel( p_ti->thread_id );

    if ( pthread_join( p_ti->thread_id, NULL ) == 0 )
      return MBG_SUCCESS;

    return mbg_get_last_error( NULL );

  #elif defined( MBG_TGT_WIN32 )

    if ( SetEvent( p_ti->exit_request ) &&
         WaitForSingleObject( p_ti->thread_id, 10000L ) == 0 )
    {
      CloseHandle( p_ti->exit_request );
      p_ti->exit_request = NULL;

      CloseHandle( p_ti->thread_id );
      p_ti->thread_id = NULL;

      return MBG_SUCCESS;
    }

    return mbg_get_last_error( NULL );

  #else

    return MBG_ERR_NOT_SUPP_ON_OS;

  #endif

}  // mbg_thread_stop



/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_thread_sleep_interruptible( MBG_THREAD_INFO *p_ti, ulong sleep_ms )
{
  #if defined( MBG_TGT_LINUX )  // TODO Eventually generally for POSIX?

    if ( usleep( sleep_ms * 1000 ) == 0 )
      return MBG_SUCCESS;

    return mbg_get_last_error( NULL );

  #elif defined( MBG_TGT_WIN32 )

    DWORD dw = WaitForSingleObject( p_ti->exit_request, sleep_ms );

    switch ( dw )
    {
      case WAIT_OBJECT_0: // has been interrupted to terminate
        return MBG_ERR_INTR;

      case WAIT_TIMEOUT:  // sleep interval expired without interruption
        return MBG_SUCCESS;
    }

    return mbg_get_last_error( NULL );

  #else

    return MBG_ERR_NOT_SUPP_ON_OS;

  #endif

}  // mbg_thread_sleep_interruptible



#if MBGDEVIO_HAVE_THREAD_AFFINITY

/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_thread_set_affinity( MBG_THREAD_INFO *p_ti, MBG_CPU_SET *p )
{
  #if defined( MBG_TGT_LINUX )  // TODO Eventually generally for POSIX?

    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 );

    if ( prv_thread_affinity )
      return MBG_SUCCESS;

    return mbg_get_last_error( NULL );

  #else

    return MBG_ERR_NOT_SUPP_ON_OS;

  #endif

}  // mbg_thread_set_affinity

#endif



static /*HDR*/
MBG_THREAD_FNC_RET_VAL MBG_THREAD_FNC_ATTR mbg_xhrt_poll_thread_fnc( void *p_void )
{
  MBG_XHRT_VARS prv_xhrt_vars;

  MBG_POLL_THREAD_INFO *p_pti = (MBG_POLL_THREAD_INFO *) p_void;
  MBG_XHRT_INFO *p = &p_pti->xhrt_info;

  memset( &prv_xhrt_vars, 0, sizeof( prv_xhrt_vars ) );

  for (;;)
  {
    MBG_XHRT_VARS xhrt_vars;
    MBG_PC_CYCLES_FREQUENCY freq = 0;
    int sleep_ms;

    int rc = mbg_get_hr_time_cycles( p->dh, &xhrt_vars.htc );

    if ( mbg_rc_is_success( rc ) )
    {
      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 ) * MBG_FRAC32_UNITS_PER_SEC )
                                    / ( xhrt_vars.pcps_hr_tstamp64 - prv_xhrt_vars.pcps_hr_tstamp64 );
    }


    _mbg_crit_sect_enter( &p->crit_sect );

    if ( mbg_rc_is_success( rc ) )
    {
      p->vars = xhrt_vars;
      p->prv_vars = prv_xhrt_vars;

      if ( freq )
        p->freq_hz = freq;
    }

    p->ioctl_status = rc;

    sleep_ms = p->sleep_ms;

    _mbg_crit_sect_leave( &p->crit_sect  );


    if ( mbg_rc_is_success( rc ) )
      prv_xhrt_vars = xhrt_vars;

    if ( mbg_rc_is_error( mbg_thread_sleep_interruptible( &p_pti->ti, sleep_ms ) ) )
      break;
  }

  _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*/
_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 )
{
  int rc = mbg_chk_dev_has_hr_time( dh );

  if ( mbg_rc_is_error( rc ) )
    return rc;

  memset( p_pti, 0, sizeof( *p_pti ) );

  p_pti->xhrt_info.dh = dh;
  p_pti->xhrt_info.freq_hz = freq_hz;
  p_pti->xhrt_info.sleep_ms = sleep_ms ? sleep_ms : 1000;   // sleep 1 second by default
  _mbg_crit_sect_init( &p_pti->xhrt_info.crit_sect, "MBGDEVIO_xhrt_info" );

  rc = mbg_thread_create( &p_pti->ti, mbg_xhrt_poll_thread_fnc, p_pti );

  return rc;

}  // mbg_xhrt_poll_thread_create



/*HDR*/
_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 );

  if ( mbg_rc_is_success( rc ) )
    _mbg_crit_sect_destroy( &p_pti->xhrt_info.crit_sect );

  return rc;

}  // mbg_xhrt_poll_thread_stop



static __mbg_inline /*HDR*/
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;
  uint64_t t_now = 0;
  MBG_PC_CYCLES_FREQUENCY freq_hz;
  int ioctl_status;

  mbg_get_pc_cycles( &cyc_now );

  _mbg_crit_sect_enter( &p->crit_sect );
  xhrt_vars = p->vars;
  freq_hz = p->freq_hz;
  ioctl_status = p->ioctl_status;
  _mbg_crit_sect_leave( &p->crit_sect );

  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 ) * MBG_FRAC32_UNITS_PER_SEC ) / freq_hz;
    mbg_chk_tstamp64_leap_sec( &t_now, &xhrt_vars.htc.t.status );
  }

  if ( p_tstamp )
    *p_tstamp = t_now;

  if ( p_vars )
    *p_vars = xhrt_vars;

  return ioctl_status;

}  // mbg_get_xhrt_data



/*HDR*/
_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;
  MBG_XHRT_VARS xhrt_vars;

  int rc = mbg_get_xhrt_data( p, &tstamp64, &xhrt_vars );

  // Even if an IOCTL error has occurred recently in the polling thread
  // the interpolation may still work correctly. So we just continue
  // normally but pass the return code on to the calling function.

  uint64_to_pcps_time_stamp( &p_hrt->tstamp, tstamp64 );

  // Update status (valid only for the previous second!)
  p_hrt->signal   = xhrt_vars.htc.t.signal;
  p_hrt->status   = xhrt_vars.htc.t.status;
  p_hrt->utc_offs = xhrt_vars.htc.t.utc_offs;

  return rc;

}  // mbg_get_xhrt_time_as_pcps_hr_time



#if defined( MBG_TGT_WIN32 )

/*HDR*/
_MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_filetime( MBG_XHRT_INFO *p, FILETIME *p_ft )
{
  uint64_t tstamp64;

  int rc = mbg_get_xhrt_data( p, &tstamp64, NULL );

  // Even if an IOCTL error has occurred recently in the polling thread
  // the interpolation may still work correctly. So we just continue
  // normally but pass the return code on to the calling function.

  mbg_pcps_tstamp64_to_filetime( p_ft, &tstamp64 );

  return rc;

}  // mbg_get_xhrt_time_as_filetime

#endif



/*HDR*/
_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;
  int ioctl_status;

  _mbg_crit_sect_enter( &p->crit_sect );
  freq_hz = p->freq_hz;
  ioctl_status = p->ioctl_status;
  _mbg_crit_sect_leave( &p->crit_sect );

  if ( p_freq_hz )
    *p_freq_hz = freq_hz;

  return ioctl_status;

}  // mbg_get_xhrt_cycles_frequency

#endif // defined MBGDEVIO_USE_THREAD_API



/*HDR*/
_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_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 ) )
      *p = 0;

    #if defined( MBG_TGT_LINUX )
      if ( *p == 0 )
      {
        rc = mbg_chk_dev_has_hr_time( dh );

        if ( mbg_rc_is_success( rc ) )
        {
          PCPS_HR_TIME_CYCLES htc1;
          PCPS_HR_TIME_CYCLES htc2;
          double delta_cycles;
          double delta_t;

          rc = mbg_get_hr_time_cycles( dh, &htc1 );

          if ( mbg_rc_is_error( rc ) )
            goto done;

          sleep( 1 );

          rc = mbg_get_hr_time_cycles( dh, &htc2 );

          if ( mbg_rc_is_error( rc ) )
            goto done;

          // 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 * MBG_FRAC32_UNITS_PER_SEC ) / delta_t;
        }
      }
done:
    #endif

    return _mbgdevio_cnv_ret_val( rc );

  #else

    *p = 0;

    return MBG_ERR_NOT_SUPP_ON_OS;

  #endif

}  // mbg_get_default_cycles_frequency_from_dev



/*HDR*/
_MBG_API_ATTR MBG_PC_CYCLES_FREQUENCY _MBG_API mbg_get_default_cycles_frequency( void )
{
  #if defined MBG_TGT_WIN32

    MBG_PC_CYCLES_FREQUENCY pc_cycles_frequency;

    mbg_get_pc_cycles_frequency( &pc_cycles_frequency );

    return pc_cycles_frequency;

  #else

    return 0;

  #endif

}  // mbg_get_default_cycles_frequency



#if defined( MBG_TGT_WIN32 )

#if defined( _USRDLL )

BOOL APIENTRY DllMain( HANDLE hModule,
                       DWORD  ul_reason_for_call,
                       LPVOID lpReserved )
{
  if ( ul_reason_for_call == DLL_PROCESS_ATTACH )
    mbg_svc_register_event_source( MBG_APP_EVTLOG_NAME_MBGDEVIO_DLL );

  return TRUE;
}

#endif // defined( _USRDLL )

#endif  // defined( MBG_TGT_WIN32 )