diff options
Diffstat (limited to 'mbglib/common/pcpsdefs.h')
| -rw-r--r-- | mbglib/common/pcpsdefs.h | 1936 |
1 files changed, 1207 insertions, 729 deletions
diff --git a/mbglib/common/pcpsdefs.h b/mbglib/common/pcpsdefs.h index a5b4b94..56ab821 100644 --- a/mbglib/common/pcpsdefs.h +++ b/mbglib/common/pcpsdefs.h @@ -1,16 +1,54 @@ /************************************************************************** * - * $Id: pcpsdefs.h 1.46 2011/01/13 11:44:29 martin REL_M $ + * $Id: pcpsdefs.h 1.55.1.2 2014/10/17 13:28:29 martin TEST $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * * Description: - * General definitions for Meinberg plug-in radio clocks + * General definitions for Meinberg plug-in devices. * * ----------------------------------------------------------------------- * $Log: pcpsdefs.h $ - * Revision 1.46 2011/01/13 11:44:29 martin + * Revision 1.55.1.2 2014/10/17 13:28:29 martin + * Revision 1.55.1.1 2014/10/17 11:36:44 martin + * Updated doxygen comments. + * Revision 1.55 2014/07/17 10:52:24 martin + * Increased safety of firmware builds. + * Revision 1.54 2014/07/17 09:54:19 martin + * New command codes PC_GPS_XMR_HOLDOVER_STATUS + * and PC_GPS_ALL_GPIO_STATUS. + * Huge update and cleanup on doxygen comments. + * Revision 1.53 2014/05/27 10:13:20 martin + * Support GPS180AMC. + * Moved some signal constant definitions to pcpsdefs.h. + * Simplified declaration of code/name tables. + * Huge rework of comments in doxygen format. + * Revision 1.52 2013/09/26 09:02:52Z martin + * Support GNSS API. + * Updated doxygen comments. + * Revision 1.51 2013/06/25 09:51:39 martin + * Support GLN180PEX. + * Revision 1.50 2013/01/30 15:59:54 martin + * Updated and fixed some doxygen comments. + * Revision 1.49 2012/10/02 18:53:02 martin + * Added structure PCPS_TIME_STATUS_X_MASKS. + * Added initializer for command names, useful for debugging. + * Revision 1.48 2011/11/25 15:02:28 martin + * Support on-board event logs. + * Revision 1.47 2011/11/25 10:22:44 martin + * Modified handling of pragma pack(). + * Made command group codes obsolete. They are still supported + * when building firmware, though. + * Support PTP unicast configuration. + * Support GPIO configuration. + * Support PZF180PEX. + * Added commands to read CORR_INFO, read/write TR_DISTANCE, + * PCPS_SYNC_PZF status, and associated structures. + * Added an initializer for a table of GPS command code/names. + * Added definitions MBG_PCPS_FMT_STATUS. + * Updated some comments. + * Revision 1.46 2011/01/13 11:44:29Z martin * Moved status port register definitions here. * Revision 1.45 2010/09/06 07:36:24 martin * Support GPS180PEX and TCR180PEX. @@ -182,8 +220,8 @@ * Changes before put under RCS control: * * Revision 1.5 2000/03/24 - * Introduced PCPS_GIVE_SERNUM - * Cleaned up for definitions for serial parameter byte + * Introduced PCPS_GIVE_SERNUM. + * Cleaned up for definitions for serial parameter byte. * Reviewed and updated comments. * * 1998/07/22 @@ -192,7 +230,7 @@ * Reviewed and updated comments. * * 1997/06/12 - * GPS definitions added. + * Added GPS definitions. * * 1996/01/25 * PCPS_TIME redefined from an array of bytes to a structure. @@ -208,37 +246,49 @@ #include <words.h> #include <use_pack.h> +#ifndef _USE_PCPSPRIV + #define _USE_PCPSPRIV _IS_MBG_FIRMWARE +#endif + +#if _USE_PCPSPRIV + #include <pcpspriv.h> +#endif -/* Start of header body */ +/* Start of header body */ -#if defined( _USE_PACK ) // set byte alignment - #pragma pack( 1 ) +#if defined( _USE_PACK ) + #pragma pack( 1 ) // set byte alignment + #define _USING_BYTE_ALIGNMENT #endif /** - * The following codes enumerate the ref time sources - * from which the clocks receive the reference time. + * @brief Enumeration of the ref time signal sources used by Meinberg devices */ -enum +enum PCPS_REF_TYPES { - PCPS_REF_NONE, /**< (unknown or not defined) */ - PCPS_REF_DCF, /**< see http://www.meinberg.de/english/info/dcf77.htm */ - PCPS_REF_GPS, /**< see http://www.meinberg.de/english/info/gps.htm */ - PCPS_REF_IRIG, /**< see http://www.meinberg.de/english/info/irig.htm */ - PCPS_REF_MSF, /**< MSF Receiver (UK) */ - PCPS_REF_PTP, /**< PTP Timestamp card */ - PCPS_REF_FRC, /**< Free Running Clock */ - PCPS_REF_WWVB, /**< WWVB Receiver (US) */ - PCPS_REF_JJY, /**< JJY Receiver (Japan) */ - N_PCPS_REF /**< number of valid ref time sources */ + PCPS_REF_NONE, ///< unknown, or not defined + PCPS_REF_DCF, ///< DCF77 long wave signal (Germany), see http://www.meinberg.de/english/info/dcf77.htm + PCPS_REF_GPS, ///< GPS satellite system, see http://www.meinberg.de/english/info/gps.htm + PCPS_REF_IRIG, ///< IRIG or similar time code, see http://www.meinberg.de/english/info/irig.htm + PCPS_REF_MSF, ///< MSF long wave signal (UK) + PCPS_REF_PTP, ///< PTP/IEEE1588 network protocol + PCPS_REF_FRC, ///< Free Running Clock + PCPS_REF_WWVB, ///< WWVB long wave signal (U.S.) + PCPS_REF_JJY, ///< JJY long wave signal (Japan) + N_PCPS_REF ///< number of defined ref time sources }; -/* Initializers for the reference source names */ +/** + * @defgroup group_pcps_ref_type_names Reference type names + * + * @see ::PCPS_REF_TYPES + * + * @{ */ -#define PCPS_REF_NAME_NONE_ENG "unknown" -#define PCPS_REF_NAME_NONE_GER "nicht bekannt" +#define PCPS_REF_NAME_NONE_ENG "unknown" +#define PCPS_REF_NAME_NONE_GER "nicht bekannt" #define PCPS_REF_NAME_DCF "DCF77" #define PCPS_REF_NAME_GPS "GPS" #define PCPS_REF_NAME_IRIG "IRIG" @@ -248,7 +298,14 @@ enum #define PCPS_REF_NAME_WWVB "WWVB" #define PCPS_REF_NAME_JJY "JJY" +/** @} @defgroup group_pcps_ref_type_names */ + +/** + * @brief Initializer for an array of English reference type names + * + * @see ::PCPS_REF_TYPES + */ #define PCPS_REF_NAMES_ENG \ { \ PCPS_REF_NAME_NONE_ENG, \ @@ -263,6 +320,11 @@ enum } +/** + * @brief Initializer for a multi-language array of reference type names + * + * @see ::PCPS_REF_TYPES + */ #define PCPS_REF_NAMES_LSTR \ { \ { PCPS_REF_NAME_NONE_ENG, PCPS_REF_NAME_NONE_GER }, \ @@ -278,20 +340,30 @@ enum -/** - PCI vendor ID number (assigned by PCI SIG) -*/ +/** + * @brief Meinberg PCI vendor ID (assigned by the PCI SIG) + * + * @see @ref MEINBERG_PCI_DEVICE_IDS + */ #define PCI_VENDOR_MEINBERG 0x1360 -/* PCI device ID numbers (assigned by Meinberg) * - * High byte: type of ref time source - * Low Byte: enumeration of device types - */ + +/** + * @brief PCI device IDs assigned by Meinberg + * + * High byte: type of ref time source, see ::PCPS_REF_TYPES + * Low Byte: enumeration of device types + * + * @see ::PCI_VENDOR_MEINBERG + * + * @anchor MEINBERG_PCI_DEVICE_IDS @{ */ + #define PCI_DEV_PCI32 ( ( PCPS_REF_DCF << 8 ) | 0x01 ) #define PCI_DEV_PCI509 ( ( PCPS_REF_DCF << 8 ) | 0x02 ) #define PCI_DEV_PCI510 ( ( PCPS_REF_DCF << 8 ) | 0x03 ) #define PCI_DEV_PCI511 ( ( PCPS_REF_DCF << 8 ) | 0x04 ) #define PCI_DEV_PEX511 ( ( PCPS_REF_DCF << 8 ) | 0x05 ) +#define PCI_DEV_PZF180PEX ( ( PCPS_REF_DCF << 8 ) | 0x06 ) #define PCI_DEV_GPS167PCI ( ( PCPS_REF_GPS << 8 ) | 0x01 ) #define PCI_DEV_GPS168PCI ( ( PCPS_REF_GPS << 8 ) | 0x02 ) @@ -299,6 +371,8 @@ enum #define PCI_DEV_GPS170PCI ( ( PCPS_REF_GPS << 8 ) | 0x04 ) #define PCI_DEV_GPS170PEX ( ( PCPS_REF_GPS << 8 ) | 0x05 ) #define PCI_DEV_GPS180PEX ( ( PCPS_REF_GPS << 8 ) | 0x06 ) +#define PCI_DEV_GLN180PEX ( ( PCPS_REF_GPS << 8 ) | 0x07 ) +#define PCI_DEV_GPS180AMC ( ( PCPS_REF_GPS << 8 ) | 0x08 ) #define PCI_DEV_TCR510PCI ( ( PCPS_REF_IRIG << 8 ) | 0x01 ) #define PCI_DEV_TCR167PCI ( ( PCPS_REF_IRIG << 8 ) | 0x02 ) @@ -311,511 +385,556 @@ enum #define PCI_DEV_FRC511PEX ( ( PCPS_REF_FRC << 8 ) | 0x01 ) +/** @} anchor MEINBERG_PCI_DEVICE_IDS */ -// definitions used for the status port register -// (not to be intermixed with PCPS_TIME_STATUS) -typedef uint8_t PCPS_STATUS_PORT; /**< see \ref group_status_port "Bitmask" */ -/** @defgroup group_status_port Bit masks of PCPS_STATUS_PORT +/** + * @defgroup group_status_port Definitions used with the status port + * + * The status port register on bus-level cards reflects some hardware + * signals (e.g. DCF-77 modulation), and flags used for communication + * with the card (e.g. the BUSY flag, ::PCPS_ST_BUSY). + * + * @note Must not be confused with ::PCPS_TIME_STATUS which returns + * the synchronization status and associated information + * + * @{ */ - Bit definitions used with the #PCPS_STATUS_PORT register. +/** + * @brief Type of the status register port + */ +typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS - The flags #PCPS_ST_SEC and #PCPS_ST_MIN are cleared whenever the clock - is read, so they are not very reliable in multitasking environments. - <b>NOTE</b>: The PCPS_ST_IRQF flag originates from old ISA cards. - Some PCI cards also support this, but in case of PCI cards the - associated flag of the PCI interface chip should be checked to see - if a certain card has generated an IRQ on the PC bus. +/** + * @brief Bit masks used with ::PCPS_STATUS_PORT + * + * The flags ::PCPS_ST_SEC and ::PCPS_ST_MIN are cleared whenever the clock + * is read, so they are not very reliable in multitasking environments. + * + * The ::PCPS_ST_IRQF flag originates from old ISA cards. + * Some PCI cards also support this, but in case of PCI cards the + * associated flag of the PCI interface chip should be checked to see + * if a particular card has generated an IRQ on the PC bus. + * + * The macro _pcps_ddev_has_gen_irq() cares about this and should be used + * to determine in a portable way whether a card has generated an IRQ. + * + * @anchor PCPS_STATUS_PORT_BIT_MASKS @{ */ - The macro _pcps_ddev_has_gen_irq() cares about this and should be used - to determine in a portable way whether a card has generated an IRQ. +#define PCPS_ST_BUSY 0x01 ///< the clock is busy filling the output FIFO +#define PCPS_ST_IRQF 0x02 ///< the clock has generated an IRQ on the PC bus (ISA cards only) +#define PCPS_ST_MOD 0x20 ///< the raw demodulated DCF77 signal +#define PCPS_ST_SEC 0x40 ///< seconds have changed since last reading +#define PCPS_ST_MIN 0x80 ///< minutes have changed since last reading - * @{ - */ +/** @} anchor PCPS_STATUS_PORT_BIT_MASKS */ -#define PCPS_ST_BUSY 0x01 /**< the clock is busy filling the output FIFO */ -#define PCPS_ST_IRQF 0x02 /**< the clock has generated an IRQ on the PC bus (ISA only)*/ -#define PCPS_ST_MOD 0x20 /**< the raw demodulated DCF77 signal */ -#define PCPS_ST_SEC 0x40 /**< seconds have changed since last reading */ -#define PCPS_ST_MIN 0x80 /**< minutes have changed since last reading */ - -/** @} */ - - - -/** @defgroup group_cmd_bytes Command bytes used to access the device - - The commands described below can be used to access the Meinberg - computer peripherals. However, some of the commands have not been - implemented with older clock models, or firmware versions. - - The device driver library contains functions which detect the clocks - and check which features are supported by a given clock model/firmware - The header files pcpsdev.h and pcpsdrvr.h contain macros which can be - used to query whether a detected clock supports a feature. - If checking is required, the name of the macro is given in the - comments below. - - Some commands expect parameters to be passed to the board. In that - case, the board returns the number of parameter bytes expected when - the command code is passed. Every parameter byte has to be supplied - to the board exactly like a command byte. - Refer to function pcps_write_data() and the macro _pcps_write_var() - for details. - - - - #PCPS_GIVE_TIME<br> - Return a PCPS_TIME structure with current date, - time and status. Supported by all clocks. - - - #PCPS_GIVE_TIME_NOCLEAR<br> - Same as #PCPS_GIVE_TIME but the bits #PCPS_ST_SEC - and #PCPS_ST_MIN (see pcpsdev.h) of the status - port are not cleared. - Supported by all clocks except PC31/PS31 with - firmware version older than v3.0. - This is mainly used by the DOS TSR and should - not be used in other environments. - - - #PCPS_GIVE_SYNC_TIME<br> - Return a ::PCPS_TIME structure with date and time - of last synchronization of the clock or - the last time set via the interface. - _pcps_has_sync_time() checks whether supported. - - - #PCPS_GIVE_HR_TIME<br> - Return a PCPS_HR_TIME structure with current - date, time and status. This command should be - used to read the clock with higher resolution. - _pcps_has_hr_time() checks whether supported. - - - #PCPS_GIVE_IRIG_TIME<br> - Return a PCPS_IRIG_TIME structure with day-of-year, - time and status as decoded from the IRIG signal. - _pcps_has_irig_time() checks whether supported. - - - #PCPS_SET_TIME<br> - Set the board date, time and status. This - command expects sizeof( ::PCPS_STIME ) parameter - bytes. - _pcps_can_set_time() checks whether supported. - - - #PCPS_SET_EVENT_TIME<br> - Send a high resolution time stamp to the clock to - configure a UTC time when the clock shall generate - some event. This command expects a PCPS_TIME_STAMP - parameter. - _pcps_has_event_time() checks whether supported. - (requires custom GPS CERN firmware) - - - #PCPS_IRQ_NONE<br> - Disable the board's hardware IRQ<br> - - #PCPS_IRQ_1_SEC<br> - Enable hardware IRQs once per second<br> - - #PCPS_IRQ_1_MIN<br> - Enable hardware IRQs once per minute<br> - - #PCPS_IRQ_10_MIN<br> - Enable hardware IRQs once per 10 minutes<br> - - #PCPS_IRQ_30_MIN<br> - Enable hardware IRQs once per 30 minutes<br> - - - #PCPS_GET_SERIAL<br> - #PCPS_SET_SERIAL<br> - These commands read or set the configuration - of a clock's serial port COM0. The commands - expect PCPS_SERIAL_BYTES parameter bytes and - should be used preferably with the DCF77 - clocks which have only one COM port. - _pcps_has_serial() checks whether supported. - Recent GPS clocks' COM ports should be cfg'd - using the structures RECEIVER_INFO, PORT_INFO, - and STR_TYPE_INFO. - _pcps_has_receiver_info() checks whether - these are supported. If they are not, then - the code #PC_GPS_PORT_PARM together with the - #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA - commands should be used. - - - #PCPS_GET_TZCODE<br> - #PCPS_SET_TZCODE<br> - These commands read or set a DCF77 clock's - time zone code and should be used preferably - with the newer DCF77 clocks which have limited - support of different time zones. - _pcps_has_tzcode() checks whether supported. - A GPS clock's time zone must be cfg'd using - the code #PC_GPS_TZDL together with the - #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA - commands. - - - #PCPS_GET_PCPS_TZDL<br> - #PCPS_SET_PCPS_TZDL<br> - These commands read or set a DCF77 clock's - time zone / daylight saving configuration. - _pcps_has_pcps_tzdl() checks whether supported. - A GPS clock's time zone must be cfg'd using - the code #PC_GPS_TZDL together with the - #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA - commands. - - - #PCPS_GET_REF_OFFS<br> - #PCPS_SET_REF_OFFS<br> - These commands can be used to configure the - reference time offset from UTC for clocks - which can't determine the offset automatically, - e.g. from an IRIG input signal. - _pcps_has_ref_offs() checks whether supported. - - - #PCPS_GET_OPT_INFO<br> - #PCPS_SET_OPT_SETTINGS<br> - These commands can be used to configure some - optional settings, controlled by flags. - When reading, the clock returns a MBG_OPT_INFO - structure which contains the supported values, - plus the current settings. - When writing, clocks accepts a MBG_OPT_SETTINGS - structure only which contain the desired settings - of the supported flags only. - _pcps_has_opt_flags() checks whether supported. - - - #PCPS_GET_IRIG_RX_INFO<br> - #PCPS_SET_IRIG_RX_SETTINGS<br> - #PCPS_GET_IRIG_TX_INFO<br> - #PCPS_SET_IRIG_TX_SETTINGS<br> - These commands can be used to configure IRIG - inputs and outputs.<br> - When reading, the clock returns an IRIG_INFO - structure which contains the supported values, - plus the current settings.<br> - When writing, clocks accepts an IRIG_SETTINGS - structure only which contain the desired settings - only. _pcps_is_irig_rx() and _pcps_is_irig_tx() - check whether supported. - - - #PCPS_GET_IRIG_CTRL_BITS<br> - This command can be used to retrieve the control function - bits of the latest IRIG input frame. Those bits may carry - some well-known information as in the IEEE1344 code, but - may also contain some customized information, depending on - the IRIG frame type and the configuration of the IRIG generator. - So these bits are returned as-is and must be interpreted - by the application. - _pcps_has_irig_ctrl_bits() checks whether supported. - - - #PCPS_GET_SYNTH<br> - #PCPS_SET_SYNTH<br> - #PCPS_GET_SYNTH_STATE<br> - These commands can be used to configure an on-board - frequency synthesizer and query the synthesizer - status. The commands are only supported if the board - supports the RECEIVER_INFO structure and the flag - #GPS_HAS_SYNTH is set in the RECEIVER_INFO::features. - _pcps_has_synth() checks whether supported. - The structures SYNTH and SYNTH_STATE used with these - commands are defined in gpsdefs.h. - - - #PCPS_GIVE_FW_ID_1<br> - #PCPS_GIVE_FW_ID_2<br> - Returns the first/second block of PCPS_FIFO_SIZE - characters of the firmware ID string. These - commands can be used to check if the board - responds properly. This is done by the clock - detection functions. - - - #PCPS_GIVE_SERNUM<br> - Returns PCPS_FIFO_SIZE characters of the - clock's serial number. - _pcps_has_sernum() checks whether supported. - - - #PCPS_GENERIC_IO<br> - Generic I/O read and write. Can be used to query - specific data, e.g. a selected element of an array. - _pcps_has_generic_io() checks whether supported. - - - #PCPS_GET_DEBUG_STATUS<br> - This command reads a MBG_DEBUG_STATUS structure - which represents the internal status of the - IRIG decoder and some additional debug info. - _pcps_has_debug_status() checks whether supported. - - - #PCPS_READ_GPS_DATA<br> - #PCPS_WRITE_GPS_DATA<br> - These commands are used by the functions - pcps_read_gps_data() and pcps_write_gps_data() - to read or write large data structures to - Meinberg GPS plug-in clocks. - _pcps_is_gps() checks whether supported. - - - #PCPS_CLR_UCAP_BUFF<br> - Clear a clock's time capture buffer. - _pcps_can_clr_ucap_buff() checks whether - supported. - - - #PCPS_GIVE_UCAP_ENTRIES<br> - Read a PCPS_UCAP_ENTRIES structure which - reports the max number of entries and the - currently used number of entries in the - user capture buffer. - _pcps_has_ucap() checks whether supported. - - - #PCPS_GIVE_UCAP_EVENT<br> - Read capture events using a PCPS_HR_TIME - structure. This is faster than reading using the - GPS command #PC_GPS_UCAP. If no capture event is - available then the structure is filled with 0s. - _pcps_has_ucap() checks whether supported. - - - #PCPS_FORCE_RESET<br> - Resets the microprocessor on the radio clock - board. This is for debug purposes only and - should not be used by standard applications. - - The command codes listed above are defined below. The commands are - grouped for bytes having the same high nibble: - @{ -*/ -#define PCPS_GIVE_TIME_GROUP 0x00 -#define PCPS_SET_TIME_GROUP 0x10 -#define PCPS_IRQ_GROUP 0x20 -#define PCPS_CFG_GROUP 0x30 -#define PCPS_GIVE_DATA_GROUP 0x40 -#define PCPS_GPS_DATA_GROUP 0x50 -#define PCPS_CTRL_GROUP 0x60 -#define PCPS_CFG2_GROUP 0x70 +/** @} defgroup group_status_port */ -/* PCPS_GIVE_TIME_GROUP */ -#define PCPS_GIVE_TIME ( PCPS_GIVE_TIME_GROUP | 0x0 ) -#define PCPS_GIVE_TIME_NOCLEAR ( PCPS_GIVE_TIME_GROUP | 0x1 ) -#define PCPS_GIVE_SYNC_TIME ( PCPS_GIVE_TIME_GROUP | 0x2 ) // only supported if _pcps_has_sync_time() -#define PCPS_GIVE_HR_TIME ( PCPS_GIVE_TIME_GROUP | 0x3 ) // only supported if _pcps_has_hr_time() -#define PCPS_GIVE_IRIG_TIME ( PCPS_GIVE_TIME_GROUP | 0x4 ) // only supported if _pcps_has_irig_time() +/** + * A format string to be used with snprintb() which is available on some Unix + * systems to print information held in a bit coded variable. + */ +#define MBG_PCPS_FMT_STATUS \ + "\177\20b\0FREER\0b\1DL_ENB\0b\2SYNCD\0b\3DL_ANN\0b\4UTC\0b\5LS_ANN\0b\6IFTM\0b\7INVT" \ + "\0b\x08LS_ENB\0b\11ANT_FAIL\0b\x0aLS_ANN_NEG\0b\x0bSCALE_GPS\0b\x0cSCALE_TAI\0\0" -/* PCPS_SET_TIME_GROUP */ -#define PCPS_SET_TIME ( PCPS_SET_TIME_GROUP | 0x0 ) -/* on error, return PCPS_ERR_STIME */ -/* Attention: The code below can be used EXCLUSIVELY */ -/* with a GPS167PCI with customized CERN firmware !! */ -/* _pcps_has_event_time() checks whether supported. */ -#define PCPS_SET_EVENT_TIME ( PCPS_SET_TIME_GROUP | 0x4 ) +/** + * @brief Command codes used to communicate with bus level devices + * + * These commands are used for low level access to bus-level devices + * manufactured by Meinberg. + * + * Applications should instead use the API functions declared in mbgdevio.h. + * + * The header files pcpsdev.h and pcpsdrvr.h contain macros which can be + * used to check if a detected device supports a certain feature or command. + * If checking is required then the name of the macro is given in the + * comments associated with the command codes. + * + * Some commands expect parameters to be passed to the board. In that + * case, the board returns the number of parameter bytes expected when + * the command code is passed. Every parameter byte has to be supplied + * to the board exactly like a command byte. + * + * Refer to function pcps_write_data() and the macro _pcps_write_var() + * for details. + * + * - #PCPS_GIVE_TIME<br> + * Return a PCPS_TIME structure with current date, + * time and status. Supported by all clocks. + * + * - #PCPS_GIVE_TIME_NOCLEAR<br> + * Same as #PCPS_GIVE_TIME but the bits #PCPS_ST_SEC + * and #PCPS_ST_MIN (see pcpsdev.h) of the status + * port are not cleared. + * Supported by all clocks except PC31/PS31 with + * firmware version older than v3.0. + * This is mainly used by the DOS TSR and should + * not be used in other environments. + * + * - #PCPS_GIVE_SYNC_TIME<br> + * Return a ::PCPS_TIME structure with date and time + * of last synchronization of the clock or + * the last time set via the interface. + * _pcps_has_sync_time() checks whether supported. + * + * - #PCPS_GIVE_HR_TIME<br> + * Return a PCPS_HR_TIME structure with current + * date, time and status. This command should be + * used to read the clock with higher resolution. + * _pcps_has_hr_time() checks whether supported. + * + * - #PCPS_GIVE_IRIG_TIME<br> + * Return a PCPS_IRIG_TIME structure with day-of-year, + * time and status as decoded from the IRIG signal. + * _pcps_has_irig_time() checks whether supported. + * + * - #PCPS_SET_TIME<br> + * Set the board date, time and status. This + * command expects sizeof( ::PCPS_STIME ) parameter + * bytes. + * _pcps_can_set_time() checks whether supported. + * + * - #PCPS_SET_EVENT_TIME<br> + * Send a high resolution time stamp to the clock to + * configure a %UTC time when the clock shall generate + * some event. This command expects a PCPS_TIME_STAMP + * parameter. + * _pcps_has_event_time() checks whether supported. + * (requires custom GPS CERN firmware) + * + * - #PCPS_IRQ_NONE<br> + * Disable the board's hardware IRQ<br> + * - #PCPS_IRQ_1_SEC<br> + * Enable hardware IRQs once per second<br> + * - #PCPS_IRQ_1_MIN<br> + * Enable hardware IRQs once per minute<br> + * - #PCPS_IRQ_10_MIN<br> + * Enable hardware IRQs once per 10 minutes<br> + * - #PCPS_IRQ_30_MIN<br> + * Enable hardware IRQs once per 30 minutes<br> + * + * - #PCPS_GET_SERIAL<br> + * #PCPS_SET_SERIAL<br> + * These commands read or set the configuration + * of a clock's serial port COM0. The commands + * expect PCPS_SERIAL_BYTES parameter bytes and + * should be used preferably with the DCF77 + * clocks which have only one COM port. + * _pcps_has_serial() checks whether supported. + * Recent GPS clocks' COM ports should be cfg'd + * using the structures RECEIVER_INFO, PORT_INFO, + * and STR_TYPE_INFO. + * _pcps_has_receiver_info() checks whether + * these are supported. If they are not, then + * the code #PC_GPS_PORT_PARM together with the + * #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA + * commands should be used. + * + * - #PCPS_GET_TZCODE<br> + * #PCPS_SET_TZCODE<br> + * These commands read or set a DCF77 clock's + * time zone code and should be used preferably + * with the newer DCF77 clocks which have limited + * support of different time zones. + * _pcps_has_tzcode() checks whether supported. + * A GPS clock's time zone must be cfg'd using + * the code #PC_GPS_TZDL together with the + * #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA + * commands. + * + * - #PCPS_GET_PCPS_TZDL<br> + * #PCPS_SET_PCPS_TZDL<br> + * These commands read or set a DCF77 clock's + * time zone / daylight saving configuration. + * _pcps_has_pcps_tzdl() checks whether supported. + * A GPS clock's time zone must be cfg'd using + * the code #PC_GPS_TZDL together with the + * #PCPS_READ_GPS_DATA and #PCPS_WRITE_GPS_DATA + * commands. + * + * - #PCPS_GET_REF_OFFS<br> + * #PCPS_SET_REF_OFFS<br> + * These commands can be used to configure the + * reference time offset from %UTC for clocks + * which can't determine the offset automatically, + * e.g. from an IRIG input signal. + * _pcps_has_ref_offs() checks whether supported. + * + * - #PCPS_GET_OPT_INFO<br> + * #PCPS_SET_OPT_SETTINGS<br> + * These commands can be used to configure some + * optional settings, controlled by flags. + * When reading, the clock returns a MBG_OPT_INFO + * structure which contains the supported values, + * plus the current settings. + * When writing, clocks accepts a MBG_OPT_SETTINGS + * structure only which contain the desired settings + * of the supported flags only. + * _pcps_has_opt_flags() checks whether supported. + * + * - #PCPS_GET_IRIG_RX_INFO<br> + * #PCPS_SET_IRIG_RX_SETTINGS<br> + * #PCPS_GET_IRIG_TX_INFO<br> + * #PCPS_SET_IRIG_TX_SETTINGS<br> + * These commands can be used to configure IRIG + * inputs and outputs.<br> + * When reading, the clock returns an IRIG_INFO + * structure which contains the supported values, + * plus the current settings.<br> + * When writing, clocks accepts an IRIG_SETTINGS + * structure only which contain the desired settings + * only. _pcps_is_irig_rx() and _pcps_is_irig_tx() + * check whether supported. + * + * - #PCPS_GET_IRIG_CTRL_BITS<br> + * This command can be used to retrieve the control function + * bits of the latest IRIG input frame. Those bits may carry + * some well-known information as in the IEEE1344 code, but + * may also contain some customized information, depending on + * the IRIG frame type and the configuration of the IRIG generator. + * So these bits are returned as-is and must be interpreted + * by the application. + * _pcps_has_irig_ctrl_bits() checks whether supported. + * + * - #PCPS_GET_SYNTH<br> + * #PCPS_SET_SYNTH<br> + * #PCPS_GET_SYNTH_STATE<br> + * These commands can be used to configure an on-board + * frequency synthesizer and query the synthesizer + * status. The commands are only supported if the board + * supports the RECEIVER_INFO structure and the flag + * #GPS_HAS_SYNTH is set in the RECEIVER_INFO::features. + * _pcps_has_synth() checks whether supported. + * The structures SYNTH and SYNTH_STATE used with these + * commands are defined in gpsdefs.h. + * + * - #PCPS_GIVE_FW_ID_1<br> + * #PCPS_GIVE_FW_ID_2<br> + * Returns the first/second block of PCPS_FIFO_SIZE + * characters of the firmware ID string. These + * commands can be used to check if the board + * responds properly. This is done by the clock + * detection functions. + * + * - #PCPS_GIVE_SERNUM<br> + * Returns PCPS_FIFO_SIZE characters of the + * clock's serial number. + * _pcps_has_sernum() checks whether supported. + * + * - #PCPS_GENERIC_IO<br> + * Generic I/O read and write. Can be used to query + * specific data, e.g. a selected element of an array. + * _pcps_has_generic_io() checks whether supported. + * + * - #PCPS_GET_DEBUG_STATUS<br> + * This command reads a MBG_DEBUG_STATUS structure + * which represents the internal status of the + * IRIG decoder and some additional debug info. + * _pcps_has_debug_status() checks whether supported. + * + * - #PCPS_READ_GPS_DATA<br> + * #PCPS_WRITE_GPS_DATA<br> + * These commands are used by the functions + * pcps_read_gps_data() and pcps_write_gps_data() + * to read or write large data structures to + * Meinberg GPS plug-in clocks. + * _pcps_is_gps() checks whether supported. + * + * - #PCPS_CLR_UCAP_BUFF<br> + * Clear a clock's time capture buffer. + * _pcps_can_clr_ucap_buff() checks whether + * supported. + * + * - #PCPS_GIVE_UCAP_ENTRIES<br> + * Read a PCPS_UCAP_ENTRIES structure which + * reports the max number of entries and the + * currently used number of entries in the + * user capture buffer. + * _pcps_has_ucap() checks whether supported. + * + * - #PCPS_GIVE_UCAP_EVENT<br> + * Read capture events using a PCPS_HR_TIME + * structure. This is faster than reading using the + * GPS command #PC_GPS_UCAP. If no capture event is + * available then the structure is filled with 0s. + * _pcps_has_ucap() checks whether supported. + * + * - #PCPS_GET_CORR_INFO<br> + * Read PZF correlation info using a CORR_INFO + * structure. + * _pcps_has_pzf() checks whether supported. + * + * - #PCPS_GET_TR_DISTANCE<br> + * #PCPS_SET_TR_DISTANCE<br> + * Read or write distance from the RF transmitter. + * This is used to compensate the RF propagation delay + * for PZF receivers. + * _pcps_has_tr_distance() checks whether supported. + * + * - #PCPS_CLR_EVT_LOG<br> + * Clear on-board event log. + * _pcps_has_evt_log() checks whether supported. + * + * - #PCPS_NUM_EVT_LOG_ENTRIES<br> + * Read max number of num event log entries which can + * be saved on the board, and how many entries actually + * have been saved. + * _pcps_has_evt_log() checks whether supported. + * + * - #PCPS_FIRST_EVT_LOG_ENTRY<br> + * - #PCPS_NEXT_EVT_LOG_ENTRY<br> + * Read first (oldest) or next event log entry. + * _pcps_has_evt_log() checks whether supported. + * + * - #PCPS_FORCE_RESET<br> + * Resets the microprocessor on the device. This is + * for special test scenarios only and should not be + * used by standard applications since this may lock up + * the computer. + * + * @anchor PCPS_CMD_CODES @{ */ +#define PCPS_GIVE_TIME 0x00 ///< (r-) read current time in ::PCPS_TIME format +#define PCPS_GIVE_TIME_NOCLEAR 0x01 ///< (r-) read current time in ::PCPS_TIME format, don't clear sec and min flags +#define PCPS_GIVE_SYNC_TIME 0x02 ///< (r-) read last sync time as ::PCPS_TIME, only if ::_pcps_has_sync_time() +#define PCPS_GIVE_HR_TIME 0x03 ///< (r-) read high res. time as ::PCPS_HR_TIME, only if ::_pcps_has_hr_time() +#define PCPS_GIVE_IRIG_TIME 0x04 ///< (r-) read raw IRIG time as ::PCPS_IRIG_TIME, only if ::_pcps_has_irig_time() -/* PCPS_IRQ_GROUP */ -#define PCPS_IRQ_NONE ( PCPS_IRQ_GROUP | 0x0 ) -#define PCPS_IRQ_1_SEC ( PCPS_IRQ_GROUP | 0x1 ) -#define PCPS_IRQ_1_MIN ( PCPS_IRQ_GROUP | 0x2 ) -#define PCPS_IRQ_10_MIN ( PCPS_IRQ_GROUP | 0x4 ) -#define PCPS_IRQ_30_MIN ( PCPS_IRQ_GROUP | 0x8 ) +#define PCPS_SET_TIME 0x10 ///< (-w) set on-board time, see ::PCPS_STIME +/* on error, return PCPS_ERR_STIME */ +#define PCPS_SET_EVENT_TIME 0x14 ///< (-w) write event time as ::PCPS_TIME_STAMP, only if ::_pcps_has_event_time() -/* PCPS_CFG_GROUP */ +#define PCPS_IRQ_NONE 0x20 ///< (-w) disable IRQs +#define PCPS_IRQ_1_SEC 0x21 ///< (-w) enable IRQ per 1 second +#define PCPS_IRQ_1_MIN 0x22 ///< (-w) enable IRQ per 1 minute (deprecated) +#define PCPS_IRQ_10_MIN 0x24 ///< (-w) enable IRQ per 10 minutes (deprecated) +#define PCPS_IRQ_30_MIN 0x28 ///< (-w) enable IRQ per 10 minutes (deprecated) -#define PCPS_GET_SERIAL ( PCPS_CFG_GROUP | 0x0 ) -#define PCPS_SET_SERIAL ( PCPS_CFG_GROUP | 0x1 ) +#define PCPS_GET_SERIAL 0x30 ///< (r-) read serial settings as ::PCPS_SERIAL, superseded by ::PC_GPS_ALL_PORT_INFO +#define PCPS_SET_SERIAL 0x31 ///< (-w) write serial settings as ::PCPS_SERIAL, superseded by ::PC_GPS_PORT_SETTINGS_IDX /* on error, return PCPS_ERR_CFG */ -typedef uint8_t PCPS_SERIAL; - - -#define PCPS_GET_TZCODE ( PCPS_CFG_GROUP | 0x2 ) -#define PCPS_SET_TZCODE ( PCPS_CFG_GROUP | 0x3 ) +#define PCPS_GET_TZCODE 0x32 ///< (r-) read ::PCPS_TZCODE, only if ::_pcps_has_tzcode() +#define PCPS_SET_TZCODE 0x33 ///< (-w) write ::PCPS_TZCODE, only if ::_pcps_has_tzcode() /* on error, return PCPS_ERR_CFG */ -typedef uint8_t PCPS_TZCODE; - -/* the following codes are used with the PCPS_TZCODE parameter: */ -enum -{ - PCPS_TZCODE_CET_CEST, /* default as broadcasted by DCF77 (UTC+1h/UTC+2h) */ - PCPS_TZCODE_CET, /* always CET (UTC+1h), discard DST */ - PCPS_TZCODE_UTC, /* always UTC */ - PCPS_TZCODE_EET_EEST, /* East European Time, CET/CEST + 1h */ - N_PCPS_TZCODE /* the number of valid codes */ -}; - -/* the definitions below are for compatibily only: */ -#define PCPS_TZCODE_MEZMESZ PCPS_TZCODE_CET_CEST -#define PCPS_TZCODE_MEZ PCPS_TZCODE_CET -#define PCPS_TZCODE_OEZ PCPS_TZCODE_EET_EEST - - -#define PCPS_GET_PCPS_TZDL ( PCPS_CFG_GROUP | 0x4 ) -#define PCPS_SET_PCPS_TZDL ( PCPS_CFG_GROUP | 0x5 ) +#define PCPS_GET_PCPS_TZDL 0x34 ///< (r-) read ::PCPS_TZDL, only if ::_pcps_has_pcps_tzdl() +#define PCPS_SET_PCPS_TZDL 0x35 ///< (-w) write ::PCPS_TZDL, only if ::_pcps_has_pcps_tzdl() /* on error, return PCPS_ERR_CFG */ -/** - * The structures below can be used to configure a clock's - * time zone/daylight saving setting. This structure is shorter - * than the TZDL structure used with GPS clocks. - */ -typedef struct -{ - // The year_or_wday field below contains the full year number - // or 0..6 == Sun..Sat if the DL_AUTO_FLAG is set; see below. - uint16_t year_or_wday; - uint8_t month; - uint8_t mday; - uint8_t hour; - uint8_t min; -} PCPS_DL_ONOFF; - -#define _mbg_swab_pcps_dl_onoff( _p ) \ -{ \ - _mbg_swab16( &(_p)->year_or_wday ); \ -} - -/** - * If the field year_or_wday is or'ed with the constant DL_AUTO_FLAG - * defined below then this means that start and end of daylight saving - * time shall be computed automatically for each year. In this case - * the remaining bits represent the day-of-week after the specified - * mday/month at which the change shall occur. If that flag is not set - * then the field contains the full four-digit year number and the - * mday/month values specify the exact date of that year. - */ -#define DL_AUTO_FLAG 0x8000 // also defined in gpsdefs.h - -typedef struct -{ - int16_t offs; /**< offset from UTC to local time [min] */ - int16_t offs_dl; /**< additional offset if DST enabled [min] */ - PCPS_DL_ONOFF tm_on; /**< date/time when daylight saving starts */ - PCPS_DL_ONOFF tm_off; /**< date/time when daylight saving ends */ -} PCPS_TZDL; - -#define _mbg_swab_pcps_tzdl( _p ) \ -{ \ - _mbg_swab16( &(_p)->offs ); \ - _mbg_swab16( &(_p)->offs_dl ); \ - _mbg_swab_pcps_dl_onoff( &(_p)->tm_on ); \ - _mbg_swab_pcps_dl_onoff( &(_p)->tm_off ); \ -} - - +#define PCPS_GET_REF_OFFS 0x36 ///< (r-) read ::MBG_REF_OFFS, only if ::_pcps_has_ref_offs() +#define PCPS_SET_REF_OFFS 0x37 ///< (-w) write ::MBG_REF_OFFS, only if ::_pcps_has_ref_offs() +/* on error, return PCPS_ERR_CFG */ -#define PCPS_GET_REF_OFFS ( PCPS_CFG_GROUP | 0x6 ) -#define PCPS_SET_REF_OFFS ( PCPS_CFG_GROUP | 0x7 ) +#define PCPS_GET_OPT_INFO 0x38 ///< (r-) read ::MBG_OPT_INFO, only if ::_pcps_has_opt_flags() +#define PCPS_SET_OPT_SETTINGS 0x39 ///< (-w) write ::MBG_OPT_SETTINGS, only if ::_pcps_has_opt_flags() /* on error, return PCPS_ERR_CFG */ -/* The associated type MBG_REF_OFFS is defined in gpsdefs.h. */ +#define PCPS_GET_IRIG_RX_INFO 0x3A ///< (r-) read ::IRIG_INFO, only if ::_pcps_is_irig_rx() +#define PCPS_SET_IRIG_RX_SETTINGS 0x3B ///< (-w) write ::IRIG_SETTINGS, only if ::_pcps_is_irig_rx() +/* on error, return PCPS_ERR_CFG */ +#define PCPS_GET_IRIG_TX_INFO 0x3C ///< (r-) read ::IRIG_INFO, only if ::_pcps_has_irig_tx() +#define PCPS_SET_IRIG_TX_SETTINGS 0x3D ///< (-w) write ::IRIG_SETTINGS, only if ::_pcps_has_irig_tx() +/* on error, return PCPS_ERR_CFG */ -#define PCPS_GET_OPT_INFO ( PCPS_CFG_GROUP | 0x8 ) -#define PCPS_SET_OPT_SETTINGS ( PCPS_CFG_GROUP | 0x9 ) +#define PCPS_GET_SYNTH 0x3E ///< (r-) read ::SYNTH, only if ::_pcps_has_synth() +#define PCPS_SET_SYNTH 0x3F ///< (-w) write ::SYNTH, only if ::_pcps_has_synth() /* on error, return PCPS_ERR_CFG */ -/* The associated structures MBG_OPT_INFO and MBG_OPT_SETTINGS - are defined in gpsdefs.h. */ +#define PCPS_GIVE_FW_ID_1 0x40 ///< (r-) get first ::PCPS_FIFO_SIZE chars of firmware ID +#define PCPS_GIVE_FW_ID_2 0x41 ///< (r-) get last ::PCPS_FIFO_SIZE chars of firmware ID +#define PCPS_GIVE_SERNUM 0x42 ///< (r-) read serial number as ::PCPS_SN_STR, only if _pcps_has_sernum() +#define PCPS_GENERIC_IO 0x43 ///< (rw) see pcps_generic_io() or _mbgdevio_gen_io() +#define PCPS_GET_SYNTH_STATE 0x44 ///< (r-) read ::SYNTH_STATE, only if _pcps_has_synth() +#define PCPS_GET_IRIG_CTRL_BITS 0x45 ///< (r-) read ::MBG_IRIG_CTRL_BITS, only if ::_pcps_has_irig_ctrl_bits() +#define PCPS_GET_RAW_IRIG_DATA 0x46 ///< (r-) read ::MBG_RAW_IRIG_DATA, only if ::_pcps_has_raw_irig_data() +#define PCPS_GET_STATUS_PORT 0x4B ///< (r-) read ::PCPS_STATUS_PORT +#define PCPS_GET_DEBUG_STATUS 0x4C ///< (r-) read ::MBG_DEBUG_STATUS, only if _pcps_has_debug_status() -#define PCPS_GET_IRIG_RX_INFO ( PCPS_CFG_GROUP | 0xA ) -#define PCPS_SET_IRIG_RX_SETTINGS ( PCPS_CFG_GROUP | 0xB ) -/* on error, return PCPS_ERR_CFG */ +// Command codes 0x4D, 0x4E, and 0x4F are reserved. -#define PCPS_GET_IRIG_TX_INFO ( PCPS_CFG_GROUP | 0xC ) -#define PCPS_SET_IRIG_TX_SETTINGS ( PCPS_CFG_GROUP | 0xD ) -/* on error, return PCPS_ERR_CFG */ +#define PCPS_READ_GPS_DATA 0x50 ///< (r-) read large data structure, see ::PC_GPS_CMD_CODES +#define PCPS_WRITE_GPS_DATA 0x51 ///< (-w) write large data structure, see ::PC_GPS_CMD_CODES -/* The associated structures IRIG_INFO and IRIG_SETTINGS - are defined in gpsdefs.h. */ +#define PCPS_CLR_UCAP_BUFF 0x60 ///< (-w) no param., clear on-board capture FIFO, only if ::_pcps_has_ucap() +#define PCPS_GIVE_UCAP_ENTRIES 0x61 ///< (r-) read ::PCPS_UCAP_ENTRIES, only if ::_pcps_has_ucap() +#define PCPS_GIVE_UCAP_EVENT 0x62 ///< (r-) return oldes event as ::PCPS_HR_TIME, only if ::_pcps_has_ucap() +#define PCPS_GET_CORR_INFO 0x63 ///< (r-) read ::CORR_INFO structure, only if _pcps_has_pzf() +#define PCPS_GET_TR_DISTANCE 0x64 ///< (r-) read ::TR_DISTANCE, only if _pcps_has_tr_distance() +#define PCPS_SET_TR_DISTANCE 0x65 ///< (-w) write ::TR_DISTANCE, only if _pcps_has_tr_distance() -#define PCPS_GET_SYNTH ( PCPS_CFG_GROUP | 0xE ) -#define PCPS_SET_SYNTH ( PCPS_CFG_GROUP | 0xF ) -/* on error, return PCPS_ERR_CFG */ +#define PCPS_CLR_EVT_LOG 0x66 ///< (-w) write clear on-board event log, only if _pcps_has_evt_log() +#define PCPS_NUM_EVT_LOG_ENTRIES 0x67 ///< (r-) read ::MBG_NUM_EVT_LOG_ENTRIES, only if _pcps_has_evt_log() +#define PCPS_FIRST_EVT_LOG_ENTRY 0x68 ///< (r-) read first (oldest) ::MBG_EVT_LOG_ENTRY, only if _pcps_has_evt_log() +#define PCPS_NEXT_EVT_LOG_ENTRY 0x69 ///< (r-) read next ::MBG_EVT_LOG_ENTRY, only if _pcps_has_evt_log() -/* The associated structure SYNTH is defined in gpsdefs.h. */ +#define PCPS_FORCE_RESET 0x80 ///< (-w) no param., reset the device (this can lockup the computer!!) +/// @note Command codes 0xF0 through 0xFF are reserved. +/** @} anchor PCPS_CMD_CODES */ -/* PCPS_GIVE_DATA_GROUP */ -#define PCPS_GIVE_FW_ID_1 ( PCPS_GIVE_DATA_GROUP | 0x0 ) -#define PCPS_GIVE_FW_ID_2 ( PCPS_GIVE_DATA_GROUP | 0x1 ) -#define PCPS_GIVE_SERNUM ( PCPS_GIVE_DATA_GROUP | 0x2 ) -#define PCPS_GENERIC_IO ( PCPS_GIVE_DATA_GROUP | 0x3 ) -#define PCPS_GET_SYNTH_STATE ( PCPS_GIVE_DATA_GROUP | 0x4 ) -#define PCPS_GET_IRIG_CTRL_BITS ( PCPS_GIVE_DATA_GROUP | 0x5 ) -#define PCPS_GET_RAW_IRIG_DATA ( PCPS_GIVE_DATA_GROUP | 0x6 ) +#if _IS_MBG_FIRMWARE -#define PCPS_GET_STATUS_PORT ( PCPS_GIVE_DATA_GROUP | 0xB ) -#define PCPS_GET_DEBUG_STATUS ( PCPS_GIVE_DATA_GROUP | 0xC ) -// expects sizeof( MBG_DEBUG_STATUS ) chars +/** + * @brief Deprecated command group codes + * + * @deprecated These group codes are deprecated. + * They should not be used anymore but removed + * from existing source code. The explicite command + * codes @ref PCPS_CMD_CODES should be used instead. + * + * @anchor PCPS_CMD_GROUP_CODES @{ */ -// PCPS_GIVE_DATA_GROUP codes 0x0D, 0x0E, and 0x0F are reserved. +#define PCPS_GIVE_TIME_GROUP 0x00 +#define PCPS_SET_TIME_GROUP 0x10 +#define PCPS_IRQ_GROUP 0x20 +#define PCPS_CFG_GROUP 0x30 +#define PCPS_GIVE_DATA_GROUP 0x40 +#define PCPS_GPS_DATA_GROUP 0x50 +#define PCPS_CTRL_GROUP 0x60 +#define PCPS_CFG2_GROUP 0x70 +/** @} anchor PCPS_CMD_GROUP_CODES */ -/* PCPS_GPS_DATA_GROUP */ -#define PCPS_READ_GPS_DATA ( PCPS_GPS_DATA_GROUP | 0x0 ) -#define PCPS_WRITE_GPS_DATA ( PCPS_GPS_DATA_GROUP | 0x1 ) +#endif // _IS_MBG_FIRMWARE -/* PCPS_CTRL_GROUP */ -#define PCPS_CLR_UCAP_BUFF ( PCPS_CTRL_GROUP | 0x0 ) -#define PCPS_GIVE_UCAP_ENTRIES ( PCPS_CTRL_GROUP | 0x1 ) -#define PCPS_GIVE_UCAP_EVENT ( PCPS_CTRL_GROUP | 0x2 ) -typedef struct -{ - uint32_t used; /**< the number of saved capture events */ - uint32_t max; /**< capture buffer size */ -} PCPS_UCAP_ENTRIES; +#if !defined( MBG_CMD_TABLE_EXT ) + #define MBG_CMD_TABLE_EXT _mbg_cn_table_end() +#endif -#define _mbg_swab_pcps_ucap_entries( _p ) \ -{ \ - _mbg_swab32( &(_p)->used ); \ - _mbg_swab32( &(_p)->max ); \ +/** + * @brief An initializer for a table of code/name entries of non-GPS commands. + * + * This can e.g. initialize an array of ::MBG_CODE_NAME_TABLE_ENTRY elements + * and may be helpful when debugging. + * + * @see @ref PCPS_CMD_CODES + */ +#define PCPS_CMD_CODES_TABLE \ +{ \ + _mbg_cn_table_entry( PCPS_GIVE_TIME ), /* 0x00 */ \ + _mbg_cn_table_entry( PCPS_GIVE_TIME_NOCLEAR ), /* 0x01 */ \ + _mbg_cn_table_entry( PCPS_GIVE_SYNC_TIME ), /* 0x02 */ \ + _mbg_cn_table_entry( PCPS_GIVE_HR_TIME ), /* 0x03 */ \ + _mbg_cn_table_entry( PCPS_GIVE_IRIG_TIME ), /* 0x04 */ \ + _mbg_cn_table_entry( PCPS_SET_TIME ), /* 0x10 */ \ + _mbg_cn_table_entry( PCPS_SET_EVENT_TIME ), /* 0x14 */ \ + _mbg_cn_table_entry( PCPS_IRQ_NONE ), /* 0x20 */ \ + _mbg_cn_table_entry( PCPS_IRQ_1_SEC ), /* 0x21 */ \ + _mbg_cn_table_entry( PCPS_IRQ_1_MIN ), /* 0x22 */ \ + _mbg_cn_table_entry( PCPS_IRQ_10_MIN ), /* 0x24 */ \ + _mbg_cn_table_entry( PCPS_IRQ_30_MIN ), /* 0x28 */ \ + _mbg_cn_table_entry( PCPS_GET_SERIAL ), /* 0x30 */ \ + _mbg_cn_table_entry( PCPS_SET_SERIAL ), /* 0x31 */ \ + _mbg_cn_table_entry( PCPS_GET_TZCODE ), /* 0x32 */ \ + _mbg_cn_table_entry( PCPS_SET_TZCODE ), /* 0x33 */ \ + _mbg_cn_table_entry( PCPS_GET_PCPS_TZDL ), /* 0x34 */ \ + _mbg_cn_table_entry( PCPS_SET_PCPS_TZDL ), /* 0x35 */ \ + _mbg_cn_table_entry( PCPS_GET_REF_OFFS ), /* 0x36 */ \ + _mbg_cn_table_entry( PCPS_SET_REF_OFFS ), /* 0x37 */ \ + _mbg_cn_table_entry( PCPS_GET_OPT_INFO ), /* 0x38 */ \ + _mbg_cn_table_entry( PCPS_SET_OPT_SETTINGS ), /* 0x39 */ \ + _mbg_cn_table_entry( PCPS_GET_IRIG_RX_INFO ), /* 0x3A */ \ + _mbg_cn_table_entry( PCPS_SET_IRIG_RX_SETTINGS ), /* 0x3B */ \ + _mbg_cn_table_entry( PCPS_GET_IRIG_TX_INFO ), /* 0x3C */ \ + _mbg_cn_table_entry( PCPS_SET_IRIG_TX_SETTINGS ), /* 0x3D */ \ + _mbg_cn_table_entry( PCPS_GET_SYNTH ), /* 0x3E */ \ + _mbg_cn_table_entry( PCPS_SET_SYNTH ), /* 0x3F */ \ + _mbg_cn_table_entry( PCPS_GIVE_FW_ID_1 ), /* 0x40 */ \ + _mbg_cn_table_entry( PCPS_GIVE_FW_ID_2 ), /* 0x41 */ \ + _mbg_cn_table_entry( PCPS_GIVE_SERNUM ), /* 0x42 */ \ + _mbg_cn_table_entry( PCPS_GENERIC_IO ), /* 0x43 */ \ + _mbg_cn_table_entry( PCPS_GET_SYNTH_STATE ), /* 0x44 */ \ + _mbg_cn_table_entry( PCPS_GET_IRIG_CTRL_BITS ), /* 0x45 */ \ + _mbg_cn_table_entry( PCPS_GET_RAW_IRIG_DATA ), /* 0x46 */ \ + _mbg_cn_table_entry( PCPS_GET_STATUS_PORT ), /* 0x4B */ \ + _mbg_cn_table_entry( PCPS_GET_DEBUG_STATUS ), /* 0x4C */ \ + _mbg_cn_table_entry( PCPS_READ_GPS_DATA ), /* 0x50 */ \ + _mbg_cn_table_entry( PCPS_WRITE_GPS_DATA ), /* 0x51 */ \ + _mbg_cn_table_entry( PCPS_CLR_UCAP_BUFF ), /* 0x60 */ \ + _mbg_cn_table_entry( PCPS_GIVE_UCAP_ENTRIES ), /* 0x61 */ \ + _mbg_cn_table_entry( PCPS_GIVE_UCAP_EVENT ), /* 0x62 */ \ + _mbg_cn_table_entry( PCPS_GET_CORR_INFO ), /* 0x63 */ \ + _mbg_cn_table_entry( PCPS_GET_TR_DISTANCE ), /* 0x64 */ \ + _mbg_cn_table_entry( PCPS_SET_TR_DISTANCE ), /* 0x65 */ \ + _mbg_cn_table_entry( PCPS_CLR_EVT_LOG ), /* 0x66 */ \ + _mbg_cn_table_entry( PCPS_NUM_EVT_LOG_ENTRIES ), /* 0x67 */ \ + _mbg_cn_table_entry( PCPS_FIRST_EVT_LOG_ENTRY ), /* 0x68 */ \ + _mbg_cn_table_entry( PCPS_NEXT_EVT_LOG_ENTRY ), /* 0x69 */ \ + _mbg_cn_table_entry( PCPS_FORCE_RESET ), /* 0x80 */ \ + MBG_CMD_TABLE_EXT, \ + _mbg_cn_table_end() \ } /** - special -- use with care ! -*/ -#define PCPS_FORCE_RESET 0x80 + * @brief Bus level command return codes + * + * @deprecated These codes are deprecated and @ref MBG_RETURN_CODES should be used + * instead which provide corresponding symbols with same numeric values. + * + * @anchor PCPS_LEVEL_CMD_RETURN_CODES @{ */ -/** @} */ +#define PCPS_SUCCESS 0 ///< OK, no error (see ::MBG_SUCCESS) +#define PCPS_ERR_STIME -1 ///< invalid date/time/status passed (see ::MBG_ERR_STIME) +#define PCPS_ERR_CFG -2 ///< invalid parms for a cmd writing config parameters (see ::MBG_ERR_CFG) -/* Codes returned when commands with parameters have been passed */ -/* to the board */ -#define PCPS_SUCCESS 0 /**< OK, no error */ -#define PCPS_ERR_STIME -1 /**< invalid date/time/status passed */ -#define PCPS_ERR_CFG -2 /**< invalid parms with a PCPS_CFG_GROUP cmd */ +/** @} anchor PCPS_LEVEL_CMD_RETURN_CODES */ -#ifndef BITMASK +#if !defined( BITMASK ) #define BITMASK( b ) ( ( 1 << b ) - 1 ) #endif -/** The size of the plug-in radio clock's on-board FIFO: */ +/** @brief The size of a bus level device's command/data FIFO */ #define PCPS_FIFO_SIZE 16 +/** @brief A data buffer for a bus level device's command/data */ typedef int8_t PCPS_BUFF[PCPS_FIFO_SIZE]; -#define PCPS_ID_SIZE ( 2 * PCPS_FIFO_SIZE + 1 ) /**< ASCIIZ string */ +/** @brief The maximum length of an ID string, including terminating 0 */ +#define PCPS_ID_SIZE ( 2 * PCPS_FIFO_SIZE + 1 ) ///< ASCIIZ string + +/** @brief A buffer for an ID string, including terminating 0 */ typedef char PCPS_ID_STR[PCPS_ID_SIZE]; -#define PCPS_SN_SIZE ( PCPS_FIFO_SIZE + 1 ) /**< ASCIIZ string */ +/** @brief The maximum length of a serial number string, including terminating 0 */ +#define PCPS_SN_SIZE ( PCPS_FIFO_SIZE + 1 ) ///< ASCIIZ string + +/** @brief A buffer for a serial number string, including terminating 0 */ typedef char PCPS_SN_STR[PCPS_SN_SIZE]; + /** - * The structure has been introduced to be able to handle - * high resolution time stamps. + * @brief A high resolution time stamp */ typedef struct { - uint32_t sec; /**< seconds since 1970 (UTC) */ - uint32_t frac; /**< fractions of second ( 0xFFFFFFFF == 0.9999.. sec) */ + uint32_t sec; ///< seconds since 1970, usually %UTC scale + uint32_t frac; ///< binary fractions of second (0x80000000 == 0.5 s, 0xFFFFFFFF == 0.9999999.. s) + } PCPS_TIME_STAMP; #define _mbg_swab_pcps_time_stamp( _p ) \ @@ -829,59 +948,123 @@ typedef struct // Depending on the target environment define a data type // which can be used to convert binary fractions without // range overflow. -#if defined( MBG_TGT_UNIX ) - #define PCPS_HRT_FRAC_CONVERSION_TYPE int64_t -#elif defined( MBG_TGT_WIN32 ) - #define PCPS_HRT_FRAC_CONVERSION_TYPE int64_t -#elif defined( __WATCOMC__ ) && ( __WATCOMC__ >= 1100 ) - #define PCPS_HRT_FRAC_CONVERSION_TYPE int64_t -#else +#if defined( MBG_TGT_MISSING_64_BIT_TYPES ) #define PCPS_HRT_FRAC_CONVERSION_TYPE double +#else + #define PCPS_HRT_FRAC_CONVERSION_TYPE int64_t #endif -// Max value of PCPS_TIME_STAMP::frac + 1 used for scaling +/** + * @brief Constant used to convert ::PCPS_TIME_STAMP::frac values + * + * Max value of ::PCPS_TIME_STAMP::frac + 1, used for scaling + */ #define PCPS_HRT_BIN_FRAC_SCALE ( (PCPS_HRT_FRAC_CONVERSION_TYPE) 4294967296.0 ) // == 0x100000000 -// The scale and format to be used to print the fractions -// of a second as returned in the PCPS_TIME_STAMP structure. -// The function frac_sec_from_bin() can be used for -// the conversion. #ifndef PCPS_HRT_FRAC_SCALE + /** + * @brief Scale to be used to print ::PCPS_TIME_STAMP::frac values + * + * The function ::frac_sec_from_bin can be used for the conversion. + * + * @see ::PCPS_HRT_FRAC_SCALE_FMT + */ #define PCPS_HRT_FRAC_SCALE 10000000UL #endif #ifndef PCPS_HRT_FRAC_SCALE_FMT + /** + * @brief Format specifier used to print ::PCPS_TIME_STAMP::frac values + * + * Used to print values scaled with ::frac_sec_from_bin called + * with ::PCPS_HRT_FRAC_SCALE. + * + * @see ::PCPS_HRT_FRAC_SCALE + */ #define PCPS_HRT_FRAC_SCALE_FMT "%07lu" #endif -typedef uint16_t PCPS_TIME_STATUS_X; /**< extended status */ +/** + * @brief Extended status code + * + * Low byte corresponds to ::PCPS_TIME_STATUS, high byte + * contains additional flags. + * + * @see ::PCPS_TIME_STATUS + * @see @ref PCPS_TIME_STATUS_FLAGS + */ +typedef uint16_t PCPS_TIME_STATUS_X; #define _mbg_swab_pcps_time_status_x( _p ) _mbg_swab16( _p ) +typedef struct +{ + PCPS_TIME_STATUS_X set_mask; + PCPS_TIME_STATUS_X clr_mask; + +} PCPS_TIME_STATUS_X_MASKS; + +#define _mbg_swab_pcps_time_status_x_masks( _p ) \ +{ \ + _mbg_swab_pcps_time_status_x( &(_p)->set_mask ); \ + _mbg_swab_pcps_time_status_x( &(_p)->clr_mask ); \ +} + + + /** - * The structure has been introduced to be able to read the - * current time with higher resolution of fractions of seconds and - * more detailed information on the time zone and status. - * The structure is returned if the new command #PCPS_GIVE_HR_TIME - * is written to the board. - * _pcps_has_hr_time() checks whether supported. - * - * Newer GPS boards also accept the #PCPS_GIVE_UCAP_EVENT command - * to return user capture event times using this format. In this - * case, the "signal" field contains the number of the capture - * input line, e.g. 0 or 1. - * _pcps_has_ucap() checks whether supported. + * @brief Definitions used to report a signal strength + * + * @anchor PCPS_SIG_VAL_DEFS @{ */ + +/** + * @brief A data type used to report the signal value + */ +typedef uint8_t PCPS_SIG_VAL; + +// The following constants are used to draw a signal bar +// depending on a DCF77 clock's signal value: +#define PCPS_SIG_BIAS 55 +#define PCPS_SIG_ERR 1 +#define PCPS_SIG_MIN 20 +#define PCPS_SIG_MAX 68 + +// These constants are used by non-DCF77 devices to indicate +// if an input signal is available or not: +#define PCPS_SIG_LVL_SIG_NOT_AVAIL 0 +#define PCPS_SIG_LVL_SIG_AVAIL 128 + +/** @} anchor PCPS_SIG_VAL_DEFS */ + + + +/** + * @brief High resolution time including status and local time offset + * + * Used to read time with high resolution of fractions of seconds and + * more detailed information on the local time offset and status. + * Should be prefered over ::PCPS_TIME. + * + * ::_pcps_has_hr_time checks whether the command ::PCPS_GIVE_TIME is + * supported to read a device's current time using this format. + * + * Newer devices providing time capture input may also accept the + * ::PCPS_GIVE_UCAP_EVENT command to read user capture event times + * using this format. In this case, the "signal" field contains + * the number of the capture input line, e.g. 0 or 1. + * ::_pcps_has_ucap checks whether this is supported. */ typedef struct { - PCPS_TIME_STAMP tstamp; /**< High resolution time stamp (UTC) */ - int32_t utc_offs; /**< UTC offs [sec] (loc_time = UTC + utc_offs) */ - PCPS_TIME_STATUS_X status; /**< status flags as defined below */ - uint8_t signal; /**< for normal time, the relative RF signal level, for ucap, the channel number */ + PCPS_TIME_STAMP tstamp; ///< High resolution time stamp (%UTC) + int32_t utc_offs; ///< %UTC offs [sec] (loc_time = tstamp + utc_offs) + PCPS_TIME_STATUS_X status; ///< status bits, see @ref PCPS_TIME_STATUS_FLAGS + PCPS_SIG_VAL signal; ///< signal strength, see @ref PCPS_SIG_VAL_DEFS, or capture input channel number + } PCPS_HR_TIME; #define _mbg_swab_pcps_hr_time( _p ) \ @@ -892,46 +1075,73 @@ typedef struct } +/** + * @brief Time synchronization status + * + * Used by legacy API calls. New API calls provide + * an extended status word ::PCPS_TIME_STATUS_X. + * + * @see ::PCPS_TIME_STATUS_FLAGS_COMMON + * @see ::PCPS_TIME_STATUS_X + */ typedef uint8_t PCPS_TIME_STATUS; -/** - The standard structure used to read times from the board. - The time has a resultion of 10 ms. -*/ -typedef struct PCPS_TIME_s + + +/** + * @brief Local calendar date and time, plus sync status + * + * This legacy structure is supported by all bus level devices but + * has a time resultion of 10 ms only. For more accurate time stamps + * the structures ::PCPS_HR_TIME and ::PCPS_TIME_STAMP should be + * used preferably. + * + * @see ::PCPS_HR_TIME + * @see ::PCPS_TIME_STAMP + * @see ::PCPS_STIME + */ +typedef struct { - uint8_t sec100; /**< hundredths of seconds, 0..99 */ - uint8_t sec; /**< seconds, 0..59, or 60 if leap second */ - uint8_t min; /**< minutes, 0..59 */ - uint8_t hour; /**< hours, 0..23 */ - - uint8_t mday; /**< day of month, 0..31 */ - uint8_t wday; /**< day of week, 1..7, 1 = Monday */ - uint8_t month; /**< month, 1..12 */ - uint8_t year; /**< year of the century, 0..99 */ - - PCPS_TIME_STATUS status; /**< status bits, see below */ - uint8_t signal; /**< relative signal strength, range depends on device type */ - int8_t offs_utc; /**< [hours], 0 if !_pcps_has_utc_offs() */ + uint8_t sec100; ///< hundredths of seconds, 0..99, 10 ms resolution + uint8_t sec; ///< seconds, 0..59, or 60 if leap second + uint8_t min; ///< minutes, 0..59 + uint8_t hour; ///< hours, 0..23 + + uint8_t mday; ///< day of month, 0..31 + uint8_t wday; ///< day of week, 1..7, 1 = Monday + uint8_t month; ///< month, 1..12 + uint8_t year; ///< year of the century, 0..99 + + PCPS_TIME_STATUS status; ///< status bits, see ::PCPS_TIME_STATUS_FLAGS_COMMON + PCPS_SIG_VAL signal; ///< signal strength, see @ref PCPS_SIG_VAL_DEFS + int8_t offs_utc; ///< [hours], 0 if not ::_pcps_has_utc_offs + } PCPS_TIME; -/** - The structure is passed as parameter with the PCPS_SET_TIME cmd -*/ -typedef struct PCPS_STIME_s + +/** + * @brief Date time and status used with the ::PCPS_SET_TIME command + * + * Similar to ::PCPS_TIME, but missing the ::PCPS_TIME::signal + * and ::PCPS_TIME::offs_utc fields. + * + * @see ::PCPS_TIME + */ +typedef struct { - uint8_t sec100; /**< hundredths of seconds, 0..99 */ - uint8_t sec; /**< seconds, 0..59, or 60 if leap second */ - uint8_t min; /**< minutes, 0..59 */ - uint8_t hour; /**< hours, 0..23 */ + uint8_t sec100; ///< hundredths of seconds, 0..99, 10 ms resolution + uint8_t sec; ///< seconds, 0..59, or 60 if leap second + uint8_t min; ///< minutes, 0..59 + uint8_t hour; ///< hours, 0..23 + + uint8_t mday; ///< day of month, 0..31 + uint8_t wday; ///< day of week, 1..7, 1 = Monday + uint8_t month; ///< month, 1..12 + uint8_t year; ///< year of the century, 0..99 - uint8_t mday; /**< day of month, 0..31 */ - uint8_t wday; /**< day of week, 1..7, 1 = Monday */ - uint8_t month; /**< month, 1..12 */ - uint8_t year; /**< year of the century, 0..99 */ + PCPS_TIME_STATUS status; ///< status bits, see ::PCPS_TIME_STATUS_FLAGS_COMMON - PCPS_TIME_STATUS status; /**< status bits, see below */ } PCPS_STIME; #ifdef _C166 @@ -950,32 +1160,35 @@ typedef union { PCPS_TIME t; PCPS_STIME stime; + } PCPS_TIME_UNION; /** - The structure below can be used to read the raw IRIG time - from an IRIG receiver card, if the card supports this. - See the #PCPS_GIVE_IRIG_TIME command. - - The granularity of the value in the .frac field depends on - the update interval of the structure as implementation - in the firmware. I.e. if the raw IRIG time is updated - only once per second, the .frac value can always be 0. -*/ -typedef struct PCPS_IRIG_TIME_s + * @brief Raw IRIG time + * + * Used to read the raw IRIG time from an IRIG receiver card, if the card + * supports this. See the ::PCPS_GIVE_IRIG_TIME command. + * + * The granularity of the value in the ::PCPS_IRIG_TIME::frac field + * depends on the update interval at which the structure is updated + * by the firmeware. I.e., if the raw IRIG time is updated only + * once per second, the ::PCPS_IRIG_TIME::frac value can always be 0. + */ +typedef struct { - PCPS_TIME_STATUS_X status; /**< status bits, see below */ - int16_t offs_utc; /**< [minutes] */ - uint16_t yday; /**< day of year, 1..365/366 */ - uint16_t frac; /**< fractions of seconds, 0.1 ms units */ - uint8_t sec; /**< seconds, 0..59, or 60 if leap second */ - uint8_t min; /**< minutes, 0..59 */ - uint8_t hour; /**< hours, 0..23 */ - uint8_t year; /**< 2 digit year number, 0xFF if year not supp. by the IRIG code */ - uint8_t signal; /**< relative signal strength, range depends on device type */ - uint8_t reserved; /**< currently not used, always 0 */ + PCPS_TIME_STATUS_X status; ///< status bits, see @ref PCPS_TIME_STATUS_FLAGS + int16_t offs_utc; ///< [minutes], 0 unless supported by the code format, see ::ICODE_RX_CODES and @ref group_icode + uint16_t yday; ///< day of year, 1..365/366 + uint16_t frac; ///< fractions of seconds, 0.1 ms units + uint8_t sec; ///< seconds, 0..59, or 60 if leap second + uint8_t min; ///< minutes, 0..59 + uint8_t hour; ///< hours, 0..23 + uint8_t year; ///< 2 digit year number, 0xFF if year not supp. by the time code, see ::ICODE_RX_CODES and @ref group_icode + PCPS_SIG_VAL signal; ///< signal strength, see @ref PCPS_SIG_VAL_DEFS + uint8_t reserved; ///< currently not used, always 0 + } PCPS_IRIG_TIME; #define _mbg_swab_pcps_irig_time( _p ) \ @@ -988,81 +1201,120 @@ typedef struct PCPS_IRIG_TIME_s +/** + * @brief Time status flags + * + * @anchor PCPS_TIME_STATUS_FLAGS @{ */ -/* Bit masks used with both PCPS_TIME_STATUS and PCPS_TIME_STATUS_X */ - -#define PCPS_FREER 0x01 /**< DCF77 clock running on xtal */ - /**< GPS receiver has not verified its position */ - -#define PCPS_DL_ENB 0x02 /**< daylight saving enabled */ - -#define PCPS_SYNCD 0x04 /**< clock has sync'ed at least once after pwr up */ +/** + * @brief Legacy time status flags + * + * Bit masks used with both ::PCPS_TIME_STATUS and ::PCPS_TIME_STATUS_X + */ +enum PCPS_TIME_STATUS_FLAGS_COMMON +{ + PCPS_FREER = 0x01, ///< long wave or time code receiver running on xtal, satellite receiver has not verified its position + PCPS_DL_ENB = 0x02, ///< daylight saving currently enabled + PCPS_SYNCD = 0x04, ///< long wave or time code receiver has sync'ed at least once after pwr up, sat receiver is synchronized + PCPS_DL_ANN = 0x08, ///< a change in daylight saving status is announced + PCPS_UTC = 0x10, ///< returned time is always %UTC instead of some local time + PCPS_LS_ANN = 0x20, ///< leap second announced, for *very* old clocks see ::REV_PCPS_LS_ANN_PC31PS31 + PCPS_IFTM = 0x40, ///< the current time has been set by an API call, for *very* old clocks see ::REV_PCPS_IFTM_PC31PS31 + PCPS_INVT = 0x80 ///< invalid time because battery had been disconnected, or absolute time can't be decoded safely +}; -#define PCPS_DL_ANN 0x08 /**< a change in daylight saving is announced */ -#define PCPS_UTC 0x10 /**< a special UTC firmware is installed */ +/** + * @brief Extended time status flags + * + * Bit masks used with ::PCPS_TIME_STATUS_X only + */ +enum PCPS_TIME_STATUS_FLAGS_EXT +{ + PCPS_LS_ENB = 0x0100, ///< current second is leap second + PCPS_ANT_FAIL = 0x0200, ///< antenna failure + PCPS_LS_ANN_NEG = 0x0400, ///< announced leap second is negative + PCPS_SCALE_GPS = 0x0800, ///< time stamp is GPS scale + PCPS_SCALE_TAI = 0x1000, ///< time stamp is TAI scale + + PCPS_UCAP_OVERRUN = 0x2000, ///< events interval too short (capture events only) + PCPS_UCAP_BUFFER_FULL = 0x4000, ///< events read too slow (capture events only) + + /** + * Bit masks used only with time stamps representing the current board time. + * A DCF77 PZF receiver can set this bit if it is actually synchronized + * using PZF correlation and thus provides higher accuracy than AM receivers. + * Same numeric code as ::PCPS_UCAP_OVERRUN + */ + PCPS_SYNC_PZF = 0x2000, + + /** + * Immediately after a clock has been accessed, subsequent accesses + * may be blocked for up to 1.5 msec to give the clock's microprocessor + * some time to decode the incoming time signal. + * The flag below is eventually set if a program tries to read ::PCPS_HR_TIME + * during this interval. In this case the read function returns the + * proper time stamp which is taken if the command byte is written, + * however, the read function returns with delay. + * This flag is not supported by all clocks. + */ + PCPS_IO_BLOCKED = 0x8000 +}; -#define PCPS_LS_ANN 0x20 /**< leap second announced */ - /**< (requires firmware rev. REV_PCPS_LS_ANN_...) */ -#define PCPS_IFTM 0x40 /**< the current time was set via PC */ - /**< (requires firmware rev. REV_PCPS_IFTM_...) */ -#define PCPS_INVT 0x80 /**< invalid time because battery was disconn'd */ +/** + * This bit mask can be used to extract the time scale information out + * of a PCPS_TIME_STATUS_X value. + */ +#define PCPS_SCALE_MASK ( PCPS_SCALE_TAI | PCPS_SCALE_GPS ) -/* Bit masks used only with PCPS_TIME_STATUS_X */ +/** @} anchor PCPS_TIME_STATUS_FLAGS */ -#define PCPS_LS_ENB 0x0100 /**< current second is leap second */ -#define PCPS_ANT_FAIL 0x0200 /**< antenna failure */ -#define PCPS_LS_ANN_NEG 0x0400 /**< announced leap second is negative */ -#define PCPS_SCALE_GPS 0x0800 /**< time stamp is GPS scale */ -#define PCPS_SCALE_TAI 0x1000 /**< time stamp is TAI scale */ -/* The next two bits are used only if the structure */ -/* PCPS_HR_TIME contains a user capture event */ -#define PCPS_UCAP_OVERRUN 0x2000 /**< events interval too short */ -#define PCPS_UCAP_BUFFER_FULL 0x4000 /**< events read too slow */ /** - * Immediately after a clock has been accessed, subsequent accesses - * are blocked for up to 1.5 msec to give the clock's microprocessor - * some time to decode the incoming time signal. - * The flag below is set if a program tries to read the PCPS_HR_TIME - * during this interval. In this case the read function returns the - * proper time stamp which is taken if the command byte is written, - * however, the read function returns with delay. - * This flag is not supported by all clocks. - */ -#define PCPS_IO_BLOCKED 0x8000 - -/** - This bit mask can be used to extract the time scale information out - of a PCPS_TIME_STATUS_X value. -*/ -#define PCPS_SCALE_MASK ( PCPS_SCALE_TAI | PCPS_SCALE_GPS ) - + * @brief Legacy definitions used to configure a device's serial port + * + * @deprecated This structure and the associated command codes + * are deprecated. ::PORT_SETTINGS, ::PORT_INFO and associated + * definitions should be used instead, if supported. + * + * @anchor PCPS_OLD_SERIAL_CFG @{ */ /** - * Some DCF77 clocks have a serial interface that can be controlled - * using the commands PCPS_SET_SERIAL and PCPS_GET_SERIAL. Both commands - * use a parameter byte describing transmission speed, framing and mode - * of operation. The parameter byte can be build using the constants - * defined below, by or'ing one of the constants of each group, shifted - * to the right position. PCPS_GET_SERIAL expects that parameter byte - * and PCPS_GET_SERIAL returns the current configuration from the board. + * @brief Configuration information for a device's serial port + * + * Used with ::PCPS_GET_SERIAL and ::PCPS_SET_SERIAL + * + * The serial interface on some old DCF77 clocks can be configured + * using the commands ::PCPS_SET_SERIAL and ::PCPS_GET_SERIAL. + * Both commands use a parameter byte describing transmission speed, + * framing and mode of operation. The parameter byte can be assembled + * using the constants defined in ::PCPS_BD_CODES, ::PCPS_FR_CODES, + * and ::PCPS_MOD_CODES, by or'ing one of the constants of each group, + * shifted to the right position. ::PCPS_GET_SERIAL expects that parameter + * byte and ::PCPS_GET_SERIAL returns the current configuration from + * the board. * _pcps_has_serial() checks whether supported. - * For GPS clocks, please refer to the comments for the PCPS_GET_SERIAL + * For old GPS clocks refer to the comments for the ::PCPS_GET_SERIAL * command. */ +typedef uint8_t PCPS_SERIAL; + /** - * Baud rate indices. The values below are obsolete and should - * be replaced by the codes named MBG_BAUD_RATE_... which are - * defined in gpsdefs.h. The resulting index numbers, however, - * have not changed. + * @brief Deprecated baud rate indices + * + * @deprecated These values are deprecated. + * ::MBG_BAUD_RATE_CODES and associated structures + * should be used preferably. + * + * The sequence of codes matches the sequence + * defined in ::MBG_BAUD_RATE_CODES. */ -enum +enum PCPS_BD_CODES { PCPS_BD_300, PCPS_BD_600, @@ -1071,202 +1323,428 @@ enum PCPS_BD_4800, PCPS_BD_9600, PCPS_BD_19200, - N_PCPS_BD /* number of codes */ + N_PCPS_BD ///< number of codes }; -#define PCPS_BD_BITS 4 /* field with in the cfg byte */ -#define PCPS_BD_SHIFT 0 /* num of bits to shift left */ +#define PCPS_BD_BITS 4 ///< field with in the cfg byte +#define PCPS_BD_SHIFT 0 ///< num of bits to shift left -/* - * Initializers for a table of all baud rate strings - * and values can be found in gpsdefs.h. - */ /** - * Unfortunately, the framing codes below can not simply be - * replaced by the newer MBG_FRAMING_... definitions since - * the order of indices does not match. + * @brief Deprecated framing code indices + * + * @deprecated These values are deprecated. + * ::MBG_FRAMING_CODES and associated structures + * should be used preferably. + * + * Unfortunately, these framing codes can *not* simply + * be replaced by the newer MBG_FRAMING_... definitions + * since the order of indices doesn't match. */ -enum +enum PCPS_FR_CODES { PCPS_FR_8N1, PCPS_FR_7E2, PCPS_FR_8N2, PCPS_FR_8E1, - N_PCPS_FR_DCF /* number of valid codes */ + N_PCPS_FR_DCF ///< number of valid codes }; -#define PCPS_FR_BITS 2 /* field with in the cfg byte */ -#define PCPS_FR_SHIFT PCPS_BD_BITS /* num of bits to shift left */ +#define PCPS_FR_BITS 2 ///< field with in the cfg byte +#define PCPS_FR_SHIFT PCPS_BD_BITS ///< num of bits to shift left + + -/* - * An initializer for a table of framing strings is only defined for - * the new MBG_FRAMING_... definitions. For editing the serial port - * configuration, the old codes above should be translated to the new - * codes to unify handling inside the edit functions. +/** + * @brief Deprecated codes for modes of operation + * + * @deprecated These values are deprecated. + * ::STR_MODES and associated structures + * should be used preferably. + * + * The sequence of codes matches the sequence + * defined in ::STR_MODES. */ +enum PCPS_MOD_CODES +{ + PCPS_MOD_REQ, ///< time string on request '?' only + PCPS_MOD_SEC, ///< time string once per second + PCPS_MOD_MIN, ///< time string once per minute + PCPS_MOD_RSVD, ///< reserved + N_PCPS_MOD_DCF ///< number of possible codes +}; + +#define PCPS_MOD_BITS 2 ///< field with in the cfg byte +#define PCPS_MOD_SHIFT ( PCPS_BD_BITS + PCPS_FR_BITS ) ///< num of bits to shift left -/** - Modes of operation +/** @} anchor PCPS_OLD_SERIAL_CFG */ - * Indices for modes of operation. The values below are obsolete - * and should be replaced by the codes named STR_... which are - * defined in gpsdefs.h. The resulting index numbers, however, - * have not changed. + + +/** + * @brief Type of variable to hold a TZ code + * + * This is used with the PCI interface but differs from ::TZCODE + * which is used with the binary protocol. + * + * @see ::TZCODE + * @see ::TZCODE_UNION */ -enum +typedef uint8_t PCPS_TZCODE; + + +/** + * @brief Enumeration of codes used with PCPS_TZCODE + */ +enum PCPS_TZCODES { - PCPS_MOD_REQ, /* time string on request '?' only */ - PCPS_MOD_SEC, /* time string once per second */ - PCPS_MOD_MIN, /* time string once per minute */ - PCPS_MOD_RSVD, /* reserved */ - N_PCPS_MOD_DCF /* number of possible codes */ + PCPS_TZCODE_CET_CEST, ///< default as broadcasted by DCF77 (UTC+1h/UTC+2h) + PCPS_TZCODE_CET, ///< always CET (UTC+1h), discard DST + PCPS_TZCODE_UTC, ///< always %UTC + PCPS_TZCODE_EET_EEST, ///< East European Time, CET/CEST + 1h + N_PCPS_TZCODE ///< the number of valid codes }; -#define PCPS_MOD_BITS 2 /* field with in the cfg byte */ -#define PCPS_MOD_SHIFT ( PCPS_BD_BITS + PCPS_FR_BITS ) - /* num of bits to shift left */ +/* the definitions below are for compatibily only: */ +#define PCPS_TZCODE_MEZMESZ PCPS_TZCODE_CET_CEST +#define PCPS_TZCODE_MEZ PCPS_TZCODE_CET +#define PCPS_TZCODE_OEZ PCPS_TZCODE_EET_EEST + + +/** + * @brief Daylight changeover specification + * + * Used as member field of ::PCPS_TZDL only. Most devices supporting + * conversion to local time support the ::TZDL structure instead. + * + * @see ::TZDL + */ +typedef struct +{ + uint16_t year_or_wday; ///< The full year number, or 0..6 == Sun..Sat if the ::DL_AUTO_FLAG is set + uint8_t month; ///< [1..12] + uint8_t mday; ///< [1..31] + uint8_t hour; ///< [0..23] + uint8_t min; ///< [0..59] + +} PCPS_DL_ONOFF; + +#define _mbg_swab_pcps_dl_onoff( _p ) \ +{ \ + _mbg_swab16( &(_p)->year_or_wday ); \ +} + +/** + * @brief A flag indicating if DST changeovers are to be computed automatically + * + * If ::PCPS_DL_ONOFF::year_or_wday is or'ed with the constant ::DL_AUTO_FLAG + * then start and end of daylight saving time shall be computed automatically + * for each year. In this case the remaining bits represent the day-of-week + * after the specified mday/month at which the change shall occur. + * If that flag is not set then the field contains the full four-digit year number + * and the ::PCPS_DL_ONOFF::mday and ::PCPS_DL_ONOFF::month values specify + * the exact date of that year. Most devices supporting conversion to local time + * support the ::TZDL structure instead. + * + * @see ::TZDL + * @see ::PCPS_TZDL + */ +#define DL_AUTO_FLAG 0x8000 // also defined in gpsdefs.h + /** - * The fixed-length standard time string being sent on the serial - * output is described below: - * - * \<STX\>D:dd.mm.yy;T:d;U:hh.mm.ss;uvwx\<ETX\> - * - * where \<STX\> and \<ETX\> represent the ASCII codes 0x02 and 0x03, - * 'dd.mm.yy' is the format of the current date, 'd' is the current - * day of week (1..7, 1 == Monday ) and 'hh.mm.ss' is the format of - * the current time. The characters 'uvwx' reflect the clock's status: - * - * u clock status character: - * '#' clock has not synchronized after reset - * ' ' (space, 20h) clock has synchronized after reset - * - * v clock status character, different for DCF77 or GPS receivers: - * '*' DCF77 clock currently runs on XTAL - * GPS receiver has not checked its position - * ' ' (space, 20h): - * DCF77 clock is syncronized with transmitter - * GPS receiver has determined its position - * - * x time zone indicator: - * 'U' UTC Universal Time, Coordinated - * ' ' MEZ European Standard Time, daylight saving disabled - * 'S' MESZ European Summertime, daylight saving enabled - * - * y anouncement of discontinuity of time, enabled during last hour - * before discontinuity comes in effect: - * '!' announcement of start or end of daylight saving - * 'A' announcement of leap second insertion - * ' ' (space, 20h): nothing announced + * @brief Specification of a local time zone + * + * Most devices supporting conversion to local time support + * the ::TZDL structure instead. + * + * @see ::DL_AUTO_FLAG + * @see ::TZDL */ +typedef struct +{ + int16_t offs; ///< offset from %UTC to local time [min] (local time = %UTC + offs) + int16_t offs_dl; ///< additional offset if DST enabled [min] (DST time = local time + offs_dl) + PCPS_DL_ONOFF tm_on; ///< date/time when daylight saving starts + PCPS_DL_ONOFF tm_off; ///< date/time when daylight saving ends + +} PCPS_TZDL; + +#define _mbg_swab_pcps_tzdl( _p ) \ +{ \ + _mbg_swab16( &(_p)->offs ); \ + _mbg_swab16( &(_p)->offs_dl ); \ + _mbg_swab_pcps_dl_onoff( &(_p)->tm_on ); \ + _mbg_swab_pcps_dl_onoff( &(_p)->tm_off ); \ +} + + + +/** + * @brief Status of the time capture FIFO buffer + * + * Only supported if ::RECEIVER_INFO::n_ucaps > 0. + */ +typedef struct +{ + uint32_t used; ///< the number of saved capture events + uint32_t max; ///< capture buffer size + +} PCPS_UCAP_ENTRIES; + +#define _mbg_swab_pcps_ucap_entries( _p ) \ +{ \ + _mbg_swab32( &(_p)->used ); \ + _mbg_swab32( &(_p)->max ); \ +} + +/** + * @defgroup group_pzf_supp Definitions used with PZF receivers + * + * @{ */ /** - * Some definitions used with PZF receivers + * @brief Receiver distance from transmitter [km] */ +typedef uint16_t TR_DISTANCE; ///< Range may vary with receiver type + +#define _mbg_swab_tr_distance( _p ) \ + _mbg_swab16( _p ) -/* receiver distance from transmitter [km] */ -typedef uint16_t TR_DISTANCE; -/* correlation status info */ +/** + * @brief PZF correlation status info + */ typedef struct { - uint8_t val; /**< correlation value, or check count if status == PZF_CORR_CHECK */ - uint8_t status; /**< status codes, see below */ - char corr_dir; /**< space, '<', or '>' */ - uint8_t signal; /**< signal level, may always be 0 for devices which do not support this */ + uint8_t val; ///< correlation value, or check count if status ==:: PZF_CORR_CHECK + uint8_t status; ///< status codes, see ::PZF_CORR_STATES + char corr_dir; ///< space, '<', or '>', just for information + PCPS_SIG_VAL signal; ///< signal strength, see @ref PCPS_SIG_VAL_DEFS + } CORR_INFO; -/** Codes used with CORR_INFO::status: */ -enum +#define _mbg_swab_corr_info( _p ) \ + _nop_macro_fnc() + + +/** + * @brief Codes used with ::CORR_INFO::status + */ +enum PZF_CORR_STATES { - PZF_CORR_RAW, /**< trying raw correlation, combi receivers running in AM mode */ - PZF_CORR_CHECK, /**< raw correlation achieved, doing plausibility checks */ - PZF_CORR_FINE, /**< fine correlation achieved */ + PZF_CORR_RAW, ///< trying raw correlation, combi receivers running in AM mode + PZF_CORR_CHECK, ///< raw correlation achieved, doing plausibility checks + PZF_CORR_FINE, ///< fine correlation achieved N_PZF_CORR_STATE }; +#define PZF_CORR_STATE_NAME_RAW_ENG "Searching" +#define PZF_CORR_STATE_NAME_CHECK_ENG "Correlating" +#define PZF_CORR_STATE_NAME_FINE_ENG "Locked" + +#define PZF_CORR_STATE_NAME_RAW_GER "suchen" +#define PZF_CORR_STATE_NAME_CHECK_GER "korrelieren" +#define PZF_CORR_STATE_NAME_FINE_GER "eingerastet" + + +#define PZF_CORR_STATE_NAMES_ENG \ +{ \ + PZF_CORR_STATE_NAME_RAW_ENG, \ + PZF_CORR_STATE_NAME_CHECK_ENG, \ + PZF_CORR_STATE_NAME_FINE_ENG \ +} + + +#define PZF_CORR_STATE_NAMES_LSTR \ +{ \ + { PZF_CORR_STATE_NAME_RAW_ENG, PZF_CORR_STATE_NAME_RAW_GER }, \ + { PZF_CORR_STATE_NAME_CHECK_ENG, PZF_CORR_STATE_NAME_CHECK_GER }, \ + { PZF_CORR_STATE_NAME_FINE_ENG, PZF_CORR_STATE_NAME_FINE_GER } \ +} + +/** @} defgroup group_pzf_supp */ + + + /** - * @defgroup gps_cmds_bus GPS commands passed via the system bus + * @brief GPS Command codes passed via the system bus * - * This enumeration defines the various types of data that can be read - * from or written to Meinberg bus level devices which support this. - * Access should be done using the functions ::pcps_read_gps_data() - * and ::pcps_write_gps_data() since the size of some of the structures - * exceeds the size of the devices's I/O buffer and must therefore be - * accessed in several portions. + * Codes specifying various types of data that can be read from or + * written to Meinberg bus level devices which support this. + * Access is done using the low level functions ::pcps_read_gps + * and ::pcps_write_gps since the size of some of the structures + * exceeds the size of the device's I/O buffer and must therefore be + * accessed in several blocks. + * + * Applications should instead use the API functions declared in mbgdevio.h. * * The structures to be used are defined in gpsdefs.h. Not all structures - * are supportet, yet. Check the R/W indicators for details. + * are supported, yet. Check the r/w indicators for details. + * + * @see @ref PCPS_CMD_CODES + * @see ::PC_GPS_CMD_CODES_TABLE */ -enum -{ // R/W data type description - // system data ----------------------------------------------- - PC_GPS_TZDL = 0, // R/W TZDL time zone / daylight saving - PC_GPS_SW_REV, // R/- SW_REV software revision - PC_GPS_BVAR_STAT, // R/- BVAR_STAT status of buffered variables - PC_GPS_TIME, // R/W TTM curr. time - PC_GPS_POS_XYZ, // -/W XYZ curr. pos. in ECEF coords - PC_GPS_POS_LLA, // -/W LLA curr. pos. in geogr. coords - PC_GPS_PORT_PARM, // R/W PORT_PARM param. of the serial ports - PC_GPS_ANT_INFO, // R/- ANT_INFO time diff after ant. disconn. - PC_GPS_UCAP, // R/- TTM user capture - PC_GPS_ENABLE_FLAGS, // R/W ENABLE_FLAGS controls when to enable outp. - PC_GPS_STAT_INFO, // R/- GPS_STAT_INFO - PC_GPS_CMD, // -/W GPS_CMD commands as described below - PC_GPS_IDENT, // R/- GPS_IDENT serial number - PC_GPS_POS, // R/- POS position XYZ, LLA, and DMS - PC_GPS_ANT_CABLE_LEN, // R/W ANT_CABLE_LEN used to compensate delay - // The codes below are supported by new GPS receiver boards: - PC_GPS_RECEIVER_INFO, // R/- RECEIVER_INFO rcvr model info - PC_GPS_ALL_STR_TYPE_INFO, // R/- n*STR_TYPE_INFO_IDX all string types - PC_GPS_ALL_PORT_INFO, // R/- n*PORT_INFO_IDX all port info - PC_GPS_PORT_SETTINGS_IDX, // -/W PORT_SETTINGS_IDX port settings only - PC_GPS_ALL_POUT_INFO, // R/- n*POUT_INFO_IDX all pout info - PC_GPS_POUT_SETTINGS_IDX, // -/W POUT_SETTINGS_IDX pout settings only - PC_GPS_TIME_SCALE, // R/W MBG_TIME_SCALE_{SETTINGS|INFO}, only if PCPS_HAS_TIME_SCALE - PC_GPS_LAN_IF_INFO, // R/- LAN_IF_INFO LAN interface info, only if PCPS_HAS_LAN_INTF - PC_GPS_IP4_STATE, // R/- IP4_SETTINGS LAN interface state, only if PCPS_HAS_LAN_INTF - PC_GPS_IP4_SETTINGS, // R/W IP4_SETTINGS LAN interface configuration, only if PCPS_HAS_LAN_INTF - PC_GPS_PTP_STATE, // R/- PTP_STATE, only if PCPS_HAS_PTP - PC_GPS_PTP_CFG, // R/W PTP_CFG_{SETTINGS|INFO}, only if PCPS_HAS_PTP +enum PC_GPS_CMD_CODES +{ + // system data + PC_GPS_TZDL = 0, ///< (r/w) ::TZDL, time zone / daylight saving, only if ::GPS_MODEL_HAS_TZDL + PC_GPS_SW_REV, ///< (r/-) ::SW_REV, software revision, deprecated by ::PC_GPS_RECEIVER_INFO + PC_GPS_BVAR_STAT, ///< (r/-) ::BVAR_STAT, status of buffered variables, only if ::GPS_MODEL_HAS_BVAR_STAT + PC_GPS_TIME, ///< (r/w) ::TTM, current time, deprecated by ::PCPS_GIVE_HR_TIME + PC_GPS_POS_XYZ, ///< (-/w) ::XYZ, current position in ECEF coordinates, only if ::GPS_MODEL_HAS_POS_XYZ + PC_GPS_POS_LLA, ///< (-/w) ::LLA, current position in geographic coordinates, only if ::GPS_MODEL_HAS_POS_LLA + PC_GPS_PORT_PARM, ///< (r/w) ::PORT_PARM, param. of the serial ports, deprecated by ::PC_GPS_ALL_PORT_INFO + PC_GPS_ANT_INFO, ///< (r/-) ::ANT_INFO, time diff at sync. after antenna had been disconn., only if ::GPS_MODEL_HAS_ANT_INFO + PC_GPS_UCAP, ///< (r/-) ::TTM, user capture events, deprecated by ::PCPS_GIVE_UCAP_EVENT + PC_GPS_ENABLE_FLAGS, ///< (r/w) ::ENABLE_FLAGS, when to enable serial, pulses, and synth, only if ::GPS_MODEL_HAS_ENABLE_FLAGS + PC_GPS_STAT_INFO, ///< (r/-) ::GPS_STAT_INFO, satellite info, mode of operation, and DAC info, only if ::GPS_MODEL_HAS_STAT_INFO + PC_GPS_CMD, ///< (-/w) ::GPS_CMD, send one of the ::PC_GPS_COMMANDS + PC_GPS_IDENT, ///< (r/-) ::IDENT, serial number, deprecated by ::PC_GPS_RECEIVER_INFO + PC_GPS_POS, ///< (r/-) ::POS, position ::XYZ, ::LLA, and ::DMS combined, only if ::GPS_MODEL_HAS_POS + PC_GPS_ANT_CABLE_LEN, ///< (r/w) ::ANT_CABLE_LEN, length of antenna cable, only if ::GPS_MODEL_HAS_ANT_CABLE_LENGTH + PC_GPS_RECEIVER_INFO, ///< (r/-) ::RECEIVER_INFO, rcvr model info, only if ::PCPS_HAS_RECEIVER_INFO + PC_GPS_ALL_STR_TYPE_INFO, ///< (r/-) n * ::STR_TYPE_INFO_IDX, names and capabilities of all supp. string types, only if ::RECEIVER_INFO::n_str_type > 0 + PC_GPS_ALL_PORT_INFO, ///< (r/-) n * ::PORT_INFO_IDX, settings and capabilities of all serial ports, only if ::RECEIVER_INFO::n_com_ports > 0 + PC_GPS_PORT_SETTINGS_IDX, ///< (-/w) ::PORT_SETTINGS_IDX, settings for specified serial port, only if ::RECEIVER_INFO::n_com_ports > 0 + + PC_GPS_ALL_POUT_INFO, ///< (r/-) n * ::POUT_INFO_IDX, all programmable output info + PC_GPS_POUT_SETTINGS_IDX, ///< (-/w) ::POUT_SETTINGS_IDX, settings for one programmable output + PC_GPS_TIME_SCALE, ///< (r/w) ::MBG_TIME_SCALE_SETTINGS / ::MBG_TIME_SCALE_INFO, only if ::PCPS_HAS_TIME_SCALE + PC_GPS_LAN_IF_INFO, ///< (r/-) ::LAN_IF_INFO, LAN interface info, only if ::PCPS_HAS_LAN_INTF + PC_GPS_IP4_STATE, ///< (r/-) ::IP4_SETTINGS, LAN interface state, only if ::PCPS_HAS_LAN_INTF + PC_GPS_IP4_SETTINGS, ///< (r/w) ::IP4_SETTINGS, LAN interface configuration, only if ::PCPS_HAS_LAN_INTF + PC_GPS_PTP_STATE, ///< (r/-) ::PTP_STATE, only if ::PCPS_HAS_PTP + PC_GPS_PTP_CFG, ///< (r/w) ::PTP_CFG_SETTINGS / ::PTP_CFG_INFO, only if ::PCPS_HAS_PTP + PC_GPS_PTP_UC_MASTER_CFG_LIMITS, ///< (r/-) ::PTP_UC_MASTER_CFG_LIMITS, only if ::PTP_CFG_MSK_SUPPORT_PTP_UNICAST + PC_GPS_ALL_PTP_UC_MASTER_INFO, ///< (r/-) n * ::PTP_UC_MASTER_INFO_IDX, only if ::PTP_CFG_MSK_SUPPORT_PTP_UNICAST + PC_GPS_PTP_UC_MASTER_SETTINGS_IDX, ///< (-/w) ::PTP_UC_MASTER_SETTINGS_IDX, only if ::PTP_CFG_MSK_SUPPORT_PTP_UNICAST + PC_GPS_GPIO_CFG_LIMITS, ///< (r/-) ::MBG_GPIO_CFG_LIMITS, only if ::GPS_HAS_GPIO + PC_GPS_ALL_GPIO_INFO, ///< (r/-) n * ::MBG_GPIO_INFO_IDX, all GPIO info, only if ::GPS_HAS_GPIO + PC_GPS_GPIO_SETTINGS_IDX, ///< (-/w) ::MBG_GPIO_SETTINGS_IDX, settings for a specific port, only if ::GPS_HAS_GPIO + PC_GPS_GNSS_MODE, ///< (r/w) ::MBG_GNSS_MODE_INFO / ::MBG_GNSS_MODE_SETTINGS, only if ::PCPS_IS_GNSS + PC_GPS_ALL_GNSS_SAT_INFO, ///< (r/-) n * ::GNSS_SAT_INFO_IDX, satellite info, only if ::PCPS_IS_GNSS + PC_GPS_XMR_INSTANCES, ///< (r/-) ::XMULTI_REF_INSTANCES, only if ::GPS_HAS_XMULTI_REF and ::GPS_HAS_XMRS_MULT_INSTC + PC_GPS_XMR_SETTINGS_IDX, ///< (-/w) ::XMULTI_REF_SETTINGS_IDX, idx 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, only if ::GPS_HAS_XMULTI_REF + PC_GPS_ALL_XMR_INFO, ///< (r/-) n * ::XMULTI_REF_INFO_IDX, where n == ::XMULTI_REF_INSTANCES::n_xmr_settings, only if ::GPS_HAS_XMULTI_REF + PC_GPS_ALL_XMR_STATUS, ///< (r/w) n * ::XMULTI_REF_STATUS_IDX, where n == ::XMULTI_REF_INSTANCES::n_xmr_settings, one structure on write, only if ::GPS_HAS_XMULTI_REF + PC_GPS_XMR_HOLDOVER_STATUS, ///< (r/-) ::XMR_HOLDOVER_STATUS, only if ::XMRIF_MSK_HOLDOVER_STATUS_SUPP + PC_GPS_ALL_GPIO_STATUS, ///< (r/-) n * ::MBG_GPIO_STATUS_IDX, where n == ::MBG_GPIO_CFG_LIMITS::num_io, only if ::MBG_GPIO_CFG_LIMIT_FLAG_MASK_STATUS_SUPP // GPS data - PC_GPS_CFGH = 0x80, // -/- CFGH SVs' config. and health codes - PC_GPS_ALM, // -/- SV_ALM one SV's num and almanac - PC_GPS_EPH, // -/- SV_EPH one SV's num and ephemeris - PC_GPS_UTC, // R/W UTC UTC corr. param., only if PCPS_HAS_UTC_PARM - PC_GPS_IONO, // -/- IONO ionospheric corr. param. - PC_GPS_ASCII_MSG // -/- ASCII_MSG the GPS ASCII message + PC_GPS_CFGH = 0x80, ///< (-/-) ::CFGH, SVs' config. and health codes (yet not used) + PC_GPS_ALM, ///< (-/-) ::SV_ALM, one SV's num and almanac (yet not used) + PC_GPS_EPH, ///< (-/-) ::SV_EPH, one SV's num and ephemeris (yet not used) + PC_GPS_UTC, ///< (r/w) ::UTC, %UTC corr. param., only if ::PCPS_HAS_UTC_PARM + PC_GPS_IONO, ///< (-/-) ::IONO, ionospheric corr. param. (yet not used) + PC_GPS_ASCII_MSG ///< (-/-) ::ASCII_MSG, the GPS ASCII message (yet not used) }; -/** codes used with PC_GPS_CMD */ -enum + +/** + * @brief An initializer for a table of code/name entries of GPS commands. + * + * This can e.g. be assigned to an array of ::MBG_CODE_NAME_TABLE_ENTRY elements + * and may be helpful when debugging. + * + * @see ::PC_GPS_CMD_CODES + */ +#define PC_GPS_CMD_CODES_TABLE \ +{ \ + _mbg_cn_table_entry( PC_GPS_TZDL ), \ + _mbg_cn_table_entry( PC_GPS_SW_REV ), \ + _mbg_cn_table_entry( PC_GPS_BVAR_STAT ), \ + _mbg_cn_table_entry( PC_GPS_TIME ), \ + _mbg_cn_table_entry( PC_GPS_POS_XYZ ), \ + _mbg_cn_table_entry( PC_GPS_POS_LLA ), \ + _mbg_cn_table_entry( PC_GPS_PORT_PARM ), \ + _mbg_cn_table_entry( PC_GPS_ANT_INFO ), \ + _mbg_cn_table_entry( PC_GPS_UCAP ), \ + _mbg_cn_table_entry( PC_GPS_ENABLE_FLAGS ), \ + _mbg_cn_table_entry( PC_GPS_STAT_INFO ), \ + _mbg_cn_table_entry( PC_GPS_CMD ), \ + _mbg_cn_table_entry( PC_GPS_IDENT ), \ + _mbg_cn_table_entry( PC_GPS_POS ), \ + _mbg_cn_table_entry( PC_GPS_ANT_CABLE_LEN ), \ + _mbg_cn_table_entry( PC_GPS_RECEIVER_INFO ), \ + _mbg_cn_table_entry( PC_GPS_ALL_STR_TYPE_INFO ), \ + _mbg_cn_table_entry( PC_GPS_ALL_PORT_INFO ), \ + _mbg_cn_table_entry( PC_GPS_PORT_SETTINGS_IDX ), \ + _mbg_cn_table_entry( PC_GPS_ALL_POUT_INFO ), \ + _mbg_cn_table_entry( PC_GPS_POUT_SETTINGS_IDX ), \ + _mbg_cn_table_entry( PC_GPS_TIME_SCALE ), \ + _mbg_cn_table_entry( PC_GPS_LAN_IF_INFO ), \ + _mbg_cn_table_entry( PC_GPS_IP4_STATE ), \ + _mbg_cn_table_entry( PC_GPS_IP4_SETTINGS ), \ + _mbg_cn_table_entry( PC_GPS_PTP_STATE ), \ + _mbg_cn_table_entry( PC_GPS_PTP_CFG ), \ + _mbg_cn_table_entry( PC_GPS_PTP_UC_MASTER_CFG_LIMITS ), \ + _mbg_cn_table_entry( PC_GPS_ALL_PTP_UC_MASTER_INFO ), \ + _mbg_cn_table_entry( PC_GPS_PTP_UC_MASTER_SETTINGS_IDX ), \ + _mbg_cn_table_entry( PC_GPS_GPIO_CFG_LIMITS ), \ + _mbg_cn_table_entry( PC_GPS_ALL_GPIO_INFO ), \ + _mbg_cn_table_entry( PC_GPS_GPIO_SETTINGS_IDX ), \ + _mbg_cn_table_entry( PC_GPS_GNSS_MODE ), \ + _mbg_cn_table_entry( PC_GPS_ALL_GNSS_SAT_INFO ), \ + _mbg_cn_table_entry( PC_GPS_XMR_INSTANCES ), \ + _mbg_cn_table_entry( PC_GPS_XMR_SETTINGS_IDX ), \ + _mbg_cn_table_entry( PC_GPS_ALL_XMR_INFO ), \ + _mbg_cn_table_entry( PC_GPS_ALL_XMR_STATUS ), \ + _mbg_cn_table_entry( PC_GPS_XMR_HOLDOVER_STATUS ), \ + _mbg_cn_table_entry( PC_GPS_ALL_GPIO_STATUS ), \ + _mbg_cn_table_entry( PC_GPS_CFGH ), \ + _mbg_cn_table_entry( PC_GPS_ALM ), \ + _mbg_cn_table_entry( PC_GPS_EPH ), \ + _mbg_cn_table_entry( PC_GPS_UTC ), \ + _mbg_cn_table_entry( PC_GPS_IONO ), \ + _mbg_cn_table_entry( PC_GPS_ASCII_MSG ), \ + _mbg_cn_table_end() \ +} + + + +/** + * @brief Codes used with ::PC_GPS_CMD + * + * @note These commands should only used with care, in very rare cases! + */ +enum PC_GPS_COMMANDS //##++++++++++++++ { - PC_GPS_CMD_BOOT = 1, /**< force the clock to boot mode */ - PC_GPS_CMD_INIT_SYS, /**< let the clock clear its system variables */ - PC_GPS_CMD_INIT_USER, /**< reset the clock's user parameters to defaults */ - PC_GPS_CMD_INIT_DAC, /**< initialize the oscillator disciplining values */ - N_PC_GPS_CMD /**< no command, just the number of known commands */ + PC_GPS_CMD_BOOT = 1, ///< force a GPS receiver to boot mode + PC_GPS_CMD_INIT_SYS, ///< let the clock clear its system variables + PC_GPS_CMD_INIT_USER, ///< reset the clock's user parameters to defaults + PC_GPS_CMD_INIT_DAC, ///< initialize the oscillator disciplining values + N_PC_GPS_CMD_CODES ///< no command, just the number of known commands }; -// The type below can be used to store an unambiguous command code. -// In case of the standard PCPS_... commands the lower byte contains -// the command code and the upper byte is 0. -// In case of a GPS command the lower byte contains PCPS_READ_GPS_DATA -// or PCPS_WRITE_GPS_DATA, as appropriate, and the upper byte contains -// the associated PC_GPS_... type code. + + +/** + * @brief A type used to store an unambiguous command code + * + * In case of the standard @ref PCPS_CMD_CODES the lower byte contains + * the command code and the upper byte is 0. + * In case of a GPS command the lower byte contains ::PCPS_READ_GPS_DATA + * or ::PCPS_WRITE_GPS_DATA, as appropriate, and the upper byte contains + * the associated type code from ::PC_GPS_CMD_CODES. + * + * Used internally by the firmware only. + */ typedef uint16_t PCPS_CMD_INFO; -#if defined( _USE_PACK ) // set default alignment - #pragma pack() + +#if defined( _USING_BYTE_ALIGNMENT ) + #pragma pack() // set default alignment + #undef _USING_BYTE_ALIGNMENT #endif +#define _PCPSDEFS_H_INCLUDED + /* End of header body */ #endif /* _PCPSDEFS_H */ |